SourceCraft Repo Health

Веб-сервис оценки здоровья открытых репозиториев SourceCraft: Repo Health Score от 0 до 100 по шести категориям, объяснение оценки до конкретных фактов и приоритизированные рекомендации по улучшению проекта.

Кейс 18 хакатона «Лидеры цифровой трансформации» 2026, заказчик — SourceCraft (Яндекс). Условия задачи и этапы конкурса — в docs/case.md.

Проанализировано 27 761 репозиторий каталога. Медианный Score — 52 из 100, лицензия есть у 8% проектов, настроенный CI — у 23%.

Стек: Python, Pandas, Optuna, FastAPI, SQLAlchemy, React / TypeScript, Docker Compose; необязательные AI summary через Groq.

Примеры экранов и отчётов · Методика · Код скоринга · Быстрый запуск

Посмотреть экран анализа репозитория

Снимок интерфейса хакатонной версии; значения относятся к сохранённому примеру.

Личный вклад — Рузель Салихов

В командном проекте отвечал за аналитическую часть и участвовал в разработке бэкенда:

• EDA и feature engineering для метрик репозиториев.
• Объяснимый скоринг: нормализация признаков, шесть категорий, взвешенная итоговая оценка и обработка недоступных данных.
• Эксперименты с подбором весов через Optuna — 500 trials в scoring/notebooks/optuna_and_check.ipynb.
• Разработка FastAPI-бэкенда и интеграция LLM для AI summary и рекомендаций.

Сборщик данных и фронтенд разрабатывали другие участники команды. Число 27 761 относится к командной выгрузке. Подбор весов скоринга выполнялся по составной эвристической целевой функции, без размеченной целевой переменной; это не supervised-модель, предсказывающая объективное качество репозитория.

Код аналитической части: scoring/normalizer.py, методика и ограничения: docs/methodology.md, docs/limitations.md.

Возможности сервиса

• Рейтинг открытых репозиториев с фильтрами по языку, полноте данных, наличию CI и статусу Security; сортировки по Score, лайкам и активности.
• Страница анализа: итоговая оценка, разбивка по шести категориям, раскрытие каждой до метрик и источников данных, сильные и слабые стороны, сведения о том, чего собрать не удалось.
• Рекомендации с приоритетом, доказательствами и ожидаемым эффектом на Score.
• Личный кабинет: вход через Я ID, свои репозитории, запуск анализа и повторный запуск с разницей оценки.
• Выгрузка отчёта в Markdown и PDF.
• Сравнение до четырёх проектов и страница методики прямо в интерфейсе.
• Периодический пересчёт по расписанию с историей оценок.

Запуск

Одной командой, без Docker — скрипт сам поставит зависимости, создаст настройки, сгенерирует ключ и поднимет бэкенд с интерфейсом:

./run.sh

Откройте http://localhost:5173. Остановка — Ctrl+C.

./run.sh --mock     # только интерфейс, на снимке данных: бэкенд не нужен
./run.sh --stop     # погасить всё, что осталось от прошлого запуска

Второй способ — через Docker, если нужен стенд в том же виде, в каком он будет развёрнут:

cp .env.example .env      # задать SECRET_KEY
docker compose up -d --build   # http://localhost:8080

Интерфейс умеет работать и без бэкенда — на снимке данных (./run.sh --mock). Workflow автоматической публикации GitHub Pages в текущей версии отсутствует. Развёртывание полного сервиса описано в docs/deploy.md.

Для разработки удобнее запускать части по отдельности — с горячей перезагрузкой интерфейса:

uv sync && cp .env.example .env
uv run uvicorn main:app --port 8000       # API на :8000

cd frontend && npm ci && cp .env.example .env
npm run dev                               # интерфейс на :5173

Переменные окружения, развёртывание публичного стенда и разбор типичных проблем — в docs/build-and-run.md.

Для AI summary и рекомендаций нужен GROQ_API_KEY в .env. Без ключа доступны базовые рекомендации движка правил; Repo Health Score рассчитывается независимо от LLM.

Проверки

uv run python -m unittest discover -s tests -v
npm --prefix frontend run typecheck

Unit-проверки охватывают отсутствие ключа LLM, ошибку провайдера и невалидный ответ; внешние запросы в этих проверках не выполняются.

Состав

backend/     REST API, авторизация Я ID, очередь анализа, планировщик
scoring/     методика Repo Health Score: нормализация, веса, рекомендации
collector/   сборщик данных с платформы (отдельный проект, свой README)
frontend/    веб-интерфейс
tools/       вспомогательные скрипты
docs/        документация
main.py      точка входа FastAPI
repo_health_report.csv   выгрузка сборщика, из неё строится витрина

Документация

Документ	О чём
docs/build-and-run.md	сборка, запуск, переменные окружения, стенд, типичные проблемы
docs/deploy.md	демонстрационный стенд: публичный URL, HTTPS, обновление данных
docs/architecture.md	архитектура решения, потоки данных, масштабирование, защита данных
docs/methodology.md	методика расчёта Repo Health Score
docs/roadmap.md	что готово и план развития до финальной версии
docs/examples/	примеры веб-отчётов и выгрузок на реальных репозиториях
docs/value.md	польза для пользователей и для платформы SourceCraft
docs/api-contract.md	описание API и форматов ответов
docs/openapi.yaml	то же машиночитаемо
docs/limitations.md	ограничения решения и что осталось закрыть
docs/external-services.md	внешние сервисы, обращение с данными, использование ИИ
collector/README.md	сборщик данных: запуск, порционный обход, выгрузка
frontend/README.md	интерфейс: структура, маршруты, выгрузка отчётов

Методика расчёта Score описана также в самом интерфейсе, на странице /methodology.

Пользовательский путь

1. Открыть рейтинг, отфильтровать по языку и полноте данных, отсортировать по Score.
2. Перейти в репозиторий: оценка, категории, подтверждающие факты, рекомендации.
3. Выгрузить отчёт в Markdown или PDF.
4. Войти через Я ID, выбрать собственный репозиторий, запустить анализ.
5. После исправлений запустить повторно и увидеть разницу оценки.