CommentRake использует Python 3.12.13 в Conda-окружении commentrake-py312. Исходный manifest — environment.yml. Он описывает полное локальное окружение разработки; зависимости ядра остаются независимыми от интерфейсных адаптеров.
Публичный пакет поддерживает Python 3.12 и новее. Ближайшая матрица совместимости охватывает Python 3.12, 3.13 и 3.14; отсутствие верхней границы в requires-python не заменяет реальные испытания новых версий. Все команды разработки в текущем рабочем окружении по-прежнему выполняются на утверждённом Python 3.12.13.
| Группа | Пакеты | Назначение |
|---|---|---|
| Ядро | tree-sitter из официального PyPI |
API разбора исходного кода и диапазоны комментариев |
| Поставщик грамматик | tree-sitter-language-pack |
Единый набор Tree-sitter grammars; не добавлять отдельные tree-sitter-<language> packages |
| Исключения Git | pathspec==1.1.1 |
Совместимое сопоставление правил .gitignore при обнаружении файлов |
| Командный интерфейс | typer, rich |
Команды и форматированный вывод |
| Терминальный интерфейс | textual |
Полноэкранный терминальный интерфейс |
| Графический интерфейс | pyside6=6.11.* |
Qt 6 Widgets-адаптер после утверждения макетов |
| Разработка и тесты | pytest, ruff, mypy, coverage==7.15.2 |
Испытания, проверка качества, типов и покрытия |
| Сборка | hatchling, python-build |
Backend и локальная сборка пакета |
sqlite3 и tomllib поставляются со стандартной библиотекой Python 3.12, поэтому отдельные пакеты не требуются. Для исключений Git добавлен pathspec==1.1.1: официальный PyPI-релиз опубликован 26 апреля 2026 года, поддерживает Python 3.9–3.14 и проходит десятидневную выдержку. Он закреплён в Conda manifest и является прямой runtime-зависимостью проекта; в текущем Windows lock-файле уже присутствует та же версия. Для проверки типов выбран mypy==2.3.0: версия опубликована в официальном PyPI 13 июля 2026 года и проходит десятидневную выдержку. Его установленные зависимости также закреплены после проверки официального реестра: ast-serialize==0.6.0 от 30 июня 2026 года, librt==0.13.0 от 8 июля 2026 года и mypy-extensions==1.1.0 от 22 апреля 2025 года. Для покрытия выбран coverage==7.15.2: официальный PyPI-релиз опубликован 15 июля 2026 года, поддерживает Python 3.10+ и проходит десятидневную выдержку. Он входит только в development/test group и не становится runtime-зависимостью. pytest-cov, twine, PyInstaller и Nuitka пока намеренно не установлены.
На рабочей системе установлен полный Qt 6.11. Для Python-адаптера manifest закрепляет совместимую ветку PySide6 6.11; использование системной установки Qt вместо библиотек окружения отдельно не настраивается и должно быть проверено, если оно понадобится.
tree-sitter==0.26.0 остаётся базовым Python API. Единственный поставщик грамматик — tree-sitter-language-pack==1.14.0; отдельные пакеты tree-sitter-<language> не используются. Пакет установлен из официального PyPI как готовый Windows wheel.
Версия 1.14.0 опубликована 1 августа 2026 года и не проходит обычную десятидневную выдержку. Владелец явно одобрил это исключение 2 августа 2026 года: в этой версии нужны PostgreSQL и T-SQL. Исключение относится только к этому пакету и этой версии.
Локальный каталог пакета подтверждает идентификаторы rust, c, cpp, python, html, css, javascript, typescript, bash, powershell, qmljs, xml, sql, postgres и tsql. Кэш грамматик по умолчанию направляется в пользовательский каталог %LOCALAPPDATA%\CommentRake\grammars, а не в открытый проект; перенос в <проект>/.commentrake/ возможен только по отдельному явному выбору пользователя. Сканирование не загружает грамматики из сети. Нужные бинарные грамматики отдельно заранее получают и проверяют перед включением языковых адаптеров.
Первая волна охватывает Rust, C, C++, Python, HTML, CSS, JavaScript, TypeScript, POSIX shell, PowerShell, QML, XML/Qt .qrc, SQL, PostgreSQL и T-SQL. Каждый язык всё равно получает самостоятельный безопасный адаптер, запрос комментариев, защищённые конструкции и fixtures.
Первый реализуемый набор для NetRuleRouter: Rust (rust), C (c), C++ (cpp), QML (qmljs), XML для Qt resource files (xml), JavaScript (javascript) и общий SQL (sql). Qt покрывается совместно C++- и QML-адаптерами; JavaScript добавлен отдельно для самостоятельных JavaScript-файлов и вспомогательных скриптов QML-проектов, тогда как встроенный JavaScript в .qml разбирает QML-адаптер. PostgreSQL, T-SQL и Oracle SQL/PLSQL не входят в этот заход: они потребуют отдельных адаптеров и подтверждения особенностей диалекта. Для общего SQL допускаются только стандартные комментарии и междиалектные маркеры инструментов; диалектные тела и подсказки не интерпретируются.
Для Windows resource script (.rc, в том числе составного имени app.rc.in) grammar в выбранном наборе пока не подтверждена. Такой файл остаётся распознаваемым нестандартным именем, но до отдельного решения об адаптере обрабатывается только в безопасном режиме отчёта — без регулярного выражения для удаления комментариев.
conda env create --file environment.ymlДля существующего окружения:
conda env update --name commentrake-py312 --file environment.ymlПосле создания на Windows сохраняется environment.windows-64.lock.yml с точными разрешёнными версиями. Этот lock-файл платформозависим; для Linux и macOS создаются отдельные lock-файлы позднее в рамках платформенных проверок.
Проверка 3 августа 2026 года: pip check не нашёл нарушенных требований; успешно работают PySide6, Typer, Rich, Textual, pytest, Ruff, mypy, tree-sitter и tree-sitter-language-pack. Mypy, Ruff, 13 минимальных испытаний, sdist и wheel проходят успешно.
4 августа 2026 года в %LOCALAPPDATA%\CommentRake\grammars явно получены и локально проверены семь грамматик первого набора: tree_sitter_rust.dll, tree_sitter_c.dll, tree_sitter_cpp.dll, tree_sitter_qmljs.dll, tree_sitter_xml.dll, tree_sitter_javascript.dll и tree_sitter_sql.dll. Это не автоматическая загрузка при сканировании и не запись в открытый проект.
7 августа 2026 года по явной просьбе владельца туда же получены оставшиеся грамматики первой волны: tree_sitter_python.dll, tree_sitter_css.dll, tree_sitter_html.dll, tree_sitter_bash.dll, tree_sitter_powershell.dll, tree_sitter_postgres.dll и tree_sitter_tsx.dll. Загрузка выполнена отдельной командой вне сканирования, кэш остаётся в пользовательском каталоге.
Загрузка вынесена в отдельную команду вне сканирования — scripts/fetch-grammars.py. Скрипт спрашивает у поставщика ровно те грамматики, которые называют языковые адаптеры этого дерева, кладёт их в пользовательский кэш и не делает ничего, если они уже там; грамматику, которой у поставщика нет, он называет вслух, а не пропускает молча. Рабочий процесс качества запускает его на всех трёх системах перед испытаниями и хранит кэш между прогонами (actions/cache, ключ привязан к закреплённой версии пакета). Без этого шага на Linux и macOS пропускался весь языковой слой — около двухсот проверок, включая все адаптеры и регрессии.
Имена файлов грамматик различаются по системам: Windows — tree_sitter_rust.dll, Linux — libtree_sitter_rust.so, macOS — libtree_sitter_rust.dylib. Проверка наличия грамматики искала только написание Windows, поэтому на Linux и macOS заполненный кэш читался как пустой и любой файл разбирался как неразобранный. Исправлено 2026-08-14: принимаются оба написания, приставка lib — первым.
В conda-сборке PySide6 нет файла-метки py.typed, хотя все .pyi лежат рядом. Без метки mypy считает пакет нетипизированным и подставляет Any на всё, что приходит из Qt, а модули GUI вдобавок глушат import-untyped — локальная проверка молчит. В CI PySide6 ставится колесом с PyPI, где метка есть, и тот же код даёт десятки ошибок: так накопился 71 промах, невидимый на рабочей машине. 14 августа 2026 года по решению владельца в каталог пакета добавлен пустой файл py.typed; после этого локальный mypy совпадает с CI. При пересоздании окружения метку нужно поставить заново.
T-SQL получить не удалось. tree-sitter-language-pack==1.14.0 перечисляет tsql среди поддерживаемых языков, но отказывает в загрузке: Language 'tsql' not available for download. Available groups: ["all"]. Прямой вызов download(["tsql"]) возвращает успех, однако бинарный файл в кэше не появляется и downloaded_languages() его не показывает. Другая платформа проверена 2026-08-14 и ничего не меняет: на linux-x86_64 перечень поставщика (manifest_languages(), 371 язык) tsql не содержит вовсе, то есть дело не в сборке под Windows. Поскольку именно PostgreSQL и T-SQL были причиной одобренного исключения для версии 1.14.0, вопрос требует отдельного решения владельца: дождаться следующей версии пакета либо снять T-SQL с первой волны. До решения адаптер T-SQL остаётся без эталонных проверок — четыре теста пропускаются.
Рабочая копия проекта должна находиться на обычном локальном диске, а не в синхронизируемом облачном каталоге (Yandex.Disk и аналогичные). До 2026-08-07 рабочий каталог владельца находился в D:\Yandex.Disk\Projects\...; после переноса на D:\Projects\... и по причине, найденной ниже, он остаётся на обычном локальном диске.
Проверка 2026-08-12 показала причину: на синхронизируемом диске os.scandir и os.lstat расходятся в оценке одного и того же файла. Перечисление каталога сообщает для обычных файлов атрибут FILE_ATTRIBUTE_REPARSE_POINT (0x00080420), тогда как os.lstat для тех же файлов сообщает обычный файл (0x00080020). Обнаружение файлов раньше доверяло атрибуту из scandir как дешёвому способу пропускать junction'ы; на этом диске это молча отбросило 292 записи из 20 828 — настоящие исходные файлы, принятые за junction'ы. Весь набор тестов при этом оставался зелёным: единственная проверка про reparse points подменяла именно ту функцию, которая ошибалась. Теперь этот класс дефектов покрывает регрессионная проверка: файл с атрибутом reparse обязан остаться обычным включённым файлом (test_a_file_carrying_the_reparse_attribute_is_still_a_file).
Инструмент больше не доверяет этому атрибуту для файлов: проверка reparse выполняется только для каталогов, потому что junction в Windows — это каталог, а файловые ссылки перехватывает is_symlink(). Поэтому сканирование на таком диске больше не теряет файлы по этой причине — но гарантия там слабее, чем на обычном диске: ответы самой файловой системы нестабильны, а файл, синхронизируемый во время чтения, может измениться прямо во время сканирования.
Практический вывод для пользователя: на синхронизируемом диске стоит приостанавливать синхронизацию на время сканирования и применения правок, а собственный state.sqlite3 инструмента держать вне синхронизируемого дерева.