Soft RealityLint — open-source инструмент для проверки актуальности README

RealityLint — open-source инструмент для проверки актуальности README

README может выглядеть идеально и при этом уже не соответствовать проекту.

Разработчик переименовал команду, переместил файл, удалил .env.example, сменил package manager — а документация продолжает предлагать старый способ запуска.

В итоге новый пользователь копирует команду из README:


npm run dev


а в реальном package.json:

{
"scripts": {
"start": "node app.js"
}
}

README при этом может быть синтаксически полностью корректным. Обычный Markdown-линтер ничего подозрительного не увидит.

Именно для таких ситуаций я сделал RealityLint — небольшой open-source инструмент для проверки того, не разошлась ли документация с реальным состоянием репозитория.

GitHub:
GitHub - voonterr/realitylint: Detect when your README drifts away from your real project. Static, deterministic documentation consistency checker.

Что такое RealityLint​

RealityLint — статический open-source инструмент, который сравнивает проверяемые утверждения из README с реальным состоянием репозитория.

Главный принцип:

Если утверждение можно доказать по локальным файлам — проверяем. Если нельзя проверить надёжно — не угадываем.

Инструмент не пытается «понять весь README». Он ищет конкретные вещи, которые можно проверить детерминированно.

Например:

cp .env.example .env
RealityLint проверит, существует ли .env.example.

Или:

python scripts/start.py
Проверит наличие scripts/start.py.

Но сам файл запускать не будет.

---

Что уже умеет проверять​

Сейчас RealityLint обнаруживает:

• отсутствующие npm, yarn, pnpm и bun scripts;
• битые локальные ссылки и пути;
• отсутствующие .env.exampleи .env.sample;
• несоответствие package manager и lock-файла;
• отсутствующие Python entry-файлы;
• отсутствующие Makefile targets;
• устаревшие указания версии проекта;
• заявления о лицензии при отсутствии соответствующего LICENSE-файла;
• очевидные локальные пути, которых больше нет;
• некорректные или нечитаемые package metadata.

Также учитываются команды с переходом в подкаталог:

cd frontend && npm run dev
и распространённые варианты:

npm --prefix frontend run dev
pnpm -C frontend dev
yarn --cwd frontend dev
make -C backend run

---

Почему без LLM​

Я специально не стал строить RealityLint вокруг языковой модели.

Для CI-инструмента мне хотелось получить максимально предсказуемое поведение:

Одинаковый репозиторий → одинаковый результат.

Поэтому RealityLint:

• не использует LLM;
• не требует API-ключа;
• не отправляет исходный код во внешний сервис;
• работает локально;
• не требует сетевого доступа для анализа;
• старается избегать предположений там, где нет достаточных доказательств.

Для линтера документации ложное обвинение иногда хуже, чем пропущенный слишком сложный случай.

---

Команды из README не выполняются​

Для меня это было принципиальным ограничением.

Если в README встречается:

python scripts/start.py

RealityLint анализирует команду и проверяет наличие файла.

Он не запускает python scripts/start.py.

То же самое относится к package scripts, Makefile и другим инструкциям.

То есть это именно статический анализ документации, а не sandbox для выполнения команд из README.

---

Установка​

Проект опубликован на PyPI:

python -m pip install realitylint
Проверка текущего репозитория:

realitylint
Можно проверить другой каталог:

realitylint /path/to/repository

---

Как выглядит результат​

Например, для специально подготовленного сломанного тестового проекта RealityLint может показать примерно такой результат:

RealityLint score: 34/100

ERROR   Documented local link target does not exist.
WARNING README uses yarn, but repository has only an npm lockfile.
ERROR   Documented package script "dev" is not defined in package.json.
ERROR   Documented environment template ".env.example" does not exist.
ERROR   Documented Python entry file does not exist.

Задача здесь не просто показать «README плохой», а дать конкретную причину, которую можно исправить.

---

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

RealityLint можно поставить непосредственно в CI и проверять документацию при изменениях репозитория.

Пример:

name: README reality check

on:

• pull_request

permissions:
contents: read

jobs:
realitylint:
runs-on: ubuntu-latest

Тогда сценарий получается примерно такой:

Изменили код
↓
забыли обновить README
↓
открыли Pull Request
↓
RealityLint обнаружил расхождение

---

Форматы вывода​

Помимо обычного текста поддерживаются:

realitylint . --format text
realitylint . --format json
realitylint . --format markdown
realitylint . --format sarif

SARIF позволяет использовать результаты в инструментах Code Scanning, а JSON удобен для собственной автоматизации.

Также можно выбирать уровень, при котором проверка должна завершать CI ошибкой:

realitylint . --fail-on error
realitylint . --fail-on warning
realitylint . --fail-on never

---

Что хочу добавить дальше​

Проект пока находится на ранней стадии, и сейчас я выбираю следующие направления.

Docker Compose​

Например:

docker compose up api
а сервиса api в Compose-файле уже нет.

Drift переменных окружения​

Ещё одно направление — сравнение переменных между README, .env.example и реальной конфигурацией проекта.

Например документация всё ещё требует DATABASE_URL, хотя проект уже перешёл на другую схему настройки.

Go и Rust​

Проверка вещей вроде:

go run ./cmd/server
или:

cargo run --bin server

Ignore directives​

В документации иногда специально приводятся неправильные или условные примеры.

Поэтому хочу добавить возможность отключать отдельную проверку для конкретного фрагмента, а не целиком правило.

---

Зачем вообще проверять README автоматически​

Большая часть документации действительно слишком сложна для строгой автоматической проверки.

Например утверждение:

API обрабатывает запрос за 50 мс.

статически проверить нельзя.

Но есть другой класс утверждений:

• существует ли файл;
• существует ли указанная команда;
• есть ли Make target;
• совпадает ли package manager;
• существует ли локальная ссылка;
• есть ли заявленная лицензия;
• совпадает ли указанная версия.

Для них уже есть достаточно объективных данных внутри самого репозитория.

И именно на этой области я сейчас концентрирую RealityLint.

---

Нужна обратная связь​

Проект развивается, поэтому мне особенно интересен взгляд людей, которые работают с реальными репозиториями и CI/CD.

Буду благодарен за мнение:

• какие виды устаревшей документации встречаются у вас чаще всего;
• какие проверки действительно стоило бы запускать в CI;
• где подобный анализатор может создавать лишний шум;
• какие проверки стоит добавить следующими.

Если есть идея для нового правила — тоже интересно обсудить.

RealityLint:
GitHub - voonterr/realitylint: Detect when your README drifts away from your real project. Static, deterministic documentation consistency checker.

Установка:

pip install realitylint
Проект распространяется под лицензией MIT.