RealityLint: проверка README на расхождения с кодом

Что такое RealityLint и зачем он нужен

README-файлы часто устаревают: скрипты переименовывают, файлы перемещают, а документация продолжает описывать старые команды. Это путает пользователей и разработчиков. Я создал RealityLint — статический инструмент, который автоматически сравнивает утверждения из README с фактическим состоянием репозитория, не выполняя команды из документации. Это помогает поддерживать документацию в актуальном состоянии.

RealityLint работает локально и в CI, не требует API-ключей и не загружает код в облако. Он детерминирован и предсказуем, что делает его идеальным для автоматизации.

Какие проблемы обнаруживает RealityLint

Инструмент находит типичные расхождения между README и репозиторием:

• отсутствующие npm/yarn/pnpm/bun-скрипты, упомянутые в README;
• битые локальные ссылки и пути;
• отсутствующие файлы .env.example или .env.sample;
• несоответствие менеджера пакетов и lock-файла;
• отсутствующие Python-файлы для входа;
• отсутствующие цели Makefile;
• устаревшие утверждения о версии проекта;
• лицензионные утверждения без соответствующего файла лицензии.

Это лишь часть возможностей — список можно расширять под нужды проекта.

Почему я создал этот инструмент

Документация часто «гниёт» незаметно: инструкции перестают соответствовать коду, имена файлов меняются, а команды остаются в README после того, как перестают работать. Это вводит в заблуждение пользователей, контрибьюторов и даже владельцев проекта. Я хотел инструмент, который помогает сохранять честность документации.

Принципы дизайна

RealityLint спроектирован так, чтобы быть предсказуемым:

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

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

Установка и использование

Установите RealityLint из PyPI:

pip install realitylint

Затем запустите проверку в корне проекта:

realitylint .

Инструмент проанализирует README и выдаст отчёт о найденных расхождениях. Пример вывода:

# Пример отчёта
[WARN] README упоминает скрипт "build", но он отсутствует в package.json
[ERROR] Ссылка на ./docs/guide.md ведёт на несуществующий файл

Вы можете настроить проверки под свой проект, добавив конфигурационный файл.

Интеграция с GitHub Actions

RealityLint можно использовать как GitHub Action. Добавьте шаг в ваш workflow:

name: Lint README
on: [push, pull_request]
jobs:
  lint-readme:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run RealityLint
        uses: voonterr/realitylint@v1

Это позволит автоматически проверять README при каждом изменении.

Практический вывод: как начать использовать RealityLint

Установите RealityLint в свой проект и запустите его. Исправьте найденные расхождения. Добавьте проверку в CI, чтобы предотвращать будущее устаревание документации. Если вы сталкивались с устаревшими README, поделитесь, какие проверки были бы полезны — это поможет развитию инструмента.

Начните с малого: установите инструмент, запустите на своём проекте и посмотрите, какие проблемы он найдёт. Это первый шаг к честной и актуальной документации.