Kursach

Kursach – утилита для генерации единого HTML-документа с листингами исходного кода, изображениями и статистикой по проекту. Предназначена для подготовки отчётов к курсовым и дипломным работам.

Цель

Создать CLI-приложение на Go, которое автоматически собирает содержимое программного проекта в один читаемый HTML-файл с:

• листингами всех текстовых файлов (с нумерацией строк и подсветкой синтаксиса),
• ссылками или встроенными изображениями (масштабированными до 300×300),
• исключением файлов по правилам .gitignore,
• итоговой статистикой (число файлов, строк кода и т.д.).

Результат пригоден для вставки в отчёт по курсовой/дипломной работе как приложение с листингами.

Установка

Из репозитория (требуется установленный Go)

go install git.ymnuktech.ru/ymnuk/kursach@latest

Из исходников

git clone https://git.ymnuktech.ru/ymnuk/kursach.git
cd kursach
go build -o kursach .

Использование

# Генерация отчета для текущей директории
kursach

# Генерация отчета для указанной директории
kursach -i ./my-project -o report.html

# Включение оглавления
kursach -t -i ./my-project -o report.html

# Преобразование markdown файлов в HTML (по умолчанию включено)
kursach -m -i ./my-project -o report.html

# Отключение преобразования markdown файлов (вывод в виде обычного текста)
kursach -m=false -i ./my-project -o report.html

# Подробный вывод
kursach -v -i ./my-project -o report.html

# Просмотр всех опций
kursach -h

Флаги

• -i, --input — входная директория (по умолчанию .)
• -o, --output — выходной HTML-файл (по умолчанию kursach.html)
• -t, --toc — включить оглавление (навигацию по якорям)
• -m, --render-markdown — преобразовывать markdown файлы в HTML (по умолчанию true)
• -v, --verbose — подробный вывод
• -version — показать информацию о версии
• -h, --help — показать справку

Особенности

• Подсветка синтаксиса: Используется библиотека chroma для подсветки более чем 100 языков программирования
• Нумерация строк: Автоматическая нумерация строк в исходном коде
• Обработка markdown файлов: Markdown файлы преобразуются в HTML с форматированием (управляемое флагом -m)
• Обработка изображений: Изображения автоматически масштабируются до 300×300 и встраиваются в HTML
• Игнорирование файлов: Учитываются правила из .gitignore файлов
• Статистика: Автоматически генерируется статистика по проекту
• Самодостаточный HTML: Все ресурсы встроены в один HTML файл

Архитектура

Проект состоит из следующих модулей:

• cmd/kursach — точка входа и CLI интерфейс
• internal/processing — обработка файлов (классификация, конвертация)
• internal/html — генерация HTML и TOC
• internal/stats — сбор и отображение статистики

Технологии

• Язык: Go 1.20+
• Зависимости:
  • github.com/go-enry/go-enry/v2 — детекция типа файла и языка
  • github.com/alecthomas/chroma/v2 — подсветка синтаксиса
  • golang.org/x/image/draw — ресайз изображений
  • github.com/sabhiram/go-gitignore — обработка .gitignore

Тестирование

Проект покрыт тестами на всех уровнях:

# Запуск всех тестов
go test ./...

# Запуск тестов с покрытием
go test -cover ./...

CI/CD

Проект использует Woodpecker CI для автоматической сборки и выпуска релизов. При пуше тега в репозиторий автоматически:

• Собираются бинарники для различных платформ (Linux, macOS, Windows)
• Создается релиз
• Загружаются бинарники в релиз

Лицензия

Этот проект распространяется под лицензией MIT. Подробности см. в файле LICENSE.

Почему "Kursach"?

Название отражает основное применение: студенты могут быстро сгенерировать приложение к курсовой/дипломной работе с полным листингом кода, не копируя файлы вручную и не теряя форматирование.