RealityLint: линтер для README, который сверяет документацию с реальным кодом

Open-source CLI RealityLint статически проверяет, соответствуют ли команды и файлы из README реальному состоянию репозитория. Инструмент находит устаревшую документацию без выполнения команд и отправки кода в LLM.

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

Мне стало интересно: можно ли автоматически находить хотя бы часть таких расхождений, не выполняя команды из README и не отправляя исходный код в LLM? Так появился RealityLint — open-source CLI, который статически сверяет проверяемые утверждения из README с реальным состоянием репозитория.

RealityLint: как работает линтер, проверяющий README

RealityLint — это CLI-инструмент, написанный на Python, который анализирует README и сопоставляет его содержимое с файловой структурой репозитория. Он не выполняет команды и не отправляет код во внешние сервисы, а работает статически, что делает его быстрым и безопасным. Инструмент проверяет наличие файлов и директорий, упомянутых в README, а также корректность некоторых команд, не требующих выполнения.

Например, если в README написано npm install, RealityLint проверит, есть ли в репозитории файл package.json. Если в документации указан путь к конфигурационному файлу, например .env.example, линтер убедится, что этот файл существует. Если команда ссылается на скрипт, RealityLint проверит его наличие в соответствующей директории.

Инструмент можно запустить как часть CI/CD пайплайна, чтобы автоматически обнаруживать устаревшую документацию при каждом изменении репозитория. Это позволяет поддерживать README в актуальном состоянии без ручной проверки.

Предыстория и контекст

Проблема устаревшей документации существует столько же, сколько существует сама документация. README — это первое, что видит пользователь, и часто единственное, что он читает. Если инструкция не работает, пользователь теряет доверие к проекту и уходит к конкурентам. Особенно это критично для open-source проектов, где хорошая документация — залог популярности.

Существующие инструменты, такие как markdown-link-check или markdownlint, проверяют только синтаксис и ссылки, но не проверяют соответствие содержимого README реальному коду. Более продвинутые решения, использующие LLM, могут анализировать код, но они дороги и не всегда точны. RealityLint заполняет эту нишу, предлагая простой и предсказуемый способ проверки фактических утверждений в документации.

Чем RealityLint отличается от других инструментов?

В отличие от LLM-решений, RealityLint не пытается понять смысл текста. Он работает по чётким правилам: находит в README упоминания файлов, директорий и команд, а затем проверяет их существование в репозитории. Это делает его быстрым, детерминированным и бесплатным. Он не требует доступа к интернету и может работать в изолированной среде, что важно для проектов с высокими требованиями к безопасности.

Например, если в README написано python manage.py migrate, RealityLint проверит, существует ли файл manage.py в корне проекта. Если в документации указано cp .env.example .env, линтер убедится, что .env.example присутствует. Такие проверки покрывают значительную часть типичных ошибок в README.

Технические подробности и архитектура

RealityLint написан на Python и использует стандартную библиотеку для работы с файловой системой и парсинга Markdown. Он разбивает README на секции и извлекает из них фрагменты кода и пути к файлам. Для этого применяются регулярные выражения и эвристики, которые позволяют находить команды и пути в тексте.

Инструмент поддерживает несколько режимов проверки. В режиме files он проверяет существование файлов и директорий, упомянутых в README. В режиме commands он анализирует команды и проверяет, что все необходимые файлы для их выполнения присутствуют. Также есть режим config, который проверяет, что все упомянутые конфигурационные файлы существуют.

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

Кого затронет и как

RealityLint будет полезен всем, кто поддерживает open-source проекты. Поддерживающие проекты смогут автоматически проверять актуальность README при каждом pull request, что снизит количество issue, связанных с неработающей документацией. Пользователи получат более надёжные инструкции, а значит, меньше ошибок при установке и настройке.

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

В России и СНГ RealityLint может быть особенно востребован в компаниях, которые разрабатывают собственные фреймворки и библиотеки, так как он не зависит от внешних сервисов и может использоваться в закрытых сетях.

Что будет дальше

Автор RealityLint планирует развивать инструмент, добавляя новые проверки и улучшая эвристики. В планах — поддержка других языков разметки, таких как AsciiDoc, и интеграция с популярными CI-системами, например GitHub Actions и GitLab CI. Также рассматривается возможность проверки не только README, но и других документов, таких как CONTRIBUTING.md или CHANGELOG.md.

В долгосрочной перспективе RealityLint может стать частью стандартного набора инструментов для обеспечения качества документации, наряду с линтерами кода. Уже сейчас он доступен на GitHub, и любой желающий может попробовать его на своём проекте.

Итог

RealityLint — это простой и эффективный способ автоматически проверять соответствие README реальному состоянию репозитория. Он не требует выполнения команд, не отправляет код в облако и может быть легко интегрирован в CI/CD. Если вы поддерживаете open-source проект или просто хотите, чтобы ваша документация всегда была актуальной, попробуйте RealityLint — он сэкономит вам время и нервы.