Инструменты разработчика и AI-контекст (`chutils dev`)

Команда chutils dev предоставляет набор утилит для анализа кодовой базы, построения семантического индекса и аудита AI-готовности проекта. Эти инструменты помогают оптимизировать разработку и интеграцию с LLM-ассистентами (например, Gemini, Cursor).

Синтаксис

chutils dev [-h] {generate-context,ai-lint,chat-context,scaffold,mock,install-hooks,generate-few-shot,profile-imports,setup-github-actions,dashboard} ...

Подкоманды:

generate-context — Построение карты API и семантического дерева зависимостей.
ai-lint — Статический анализ AI-готовности кодовой базы.
chat-context — Интерактивная генерация компактного контекста для ИИ.
scaffold — Инициализация нового модуля Чистой Архитектуры.
mock — Локальный декларативный HTTP мок-сервер.
install-hooks — Установка Git-хуков для автоматических проверок.
generate-few-shot — Автогенерация few-shot банка примеров для ИИ-ассистентов.
profile-imports — Профилирование времени холодного старта и импорта модулей.
setup-github-actions — Интерактивная настройка и генерация GitHub Actions workflows.
dashboard — Запуск интерактивного TUI-дашборда CLI команд.
clean — Безопасная очистка проекта от кэшей и артефактов разработки.

dev generate-context

Сканирует модули проекта и генерирует отчет обо всем публичном API (классы, методы, функции, декораторы, docstrings) либо строит иерархический граф связей между компонентами на основе статического анализа AST.

Синтаксис подкоманды:

chutils dev generate-context [-h] [-f {markdown,json}] [-o OUTPUT] [--tree] [--no-weights] [--include-examples] [--project [PROJECT]]

Параметры и флаги:

Флаг	Описание	Обязательный
`-f, --format`	Формат вывода: `markdown` или `json` (по умолчанию: `markdown`).	Нет
`-o, --output`	Путь к файлу для сохранения результата. Если не указан, выводит в консоль.	Нет
`--tree`	Генерировать иерархический семантический индекс (структурированное JSON-дерево проекта) вместо плоского списка.	Нет
`--no-weights`	Не вычислять веса связей (сложность импортов) в графе зависимостей (актуально только для `--tree`).	Нет
`--include-examples`	Включить few-shot примеры из папки `docs/ai_examples/` в итоговый отчет.	Нет
`--project`	Путь к сканируемому проекту. Если флаг опущен, сканируется сама библиотека `chutils`. Если флаг передан без аргументов, сканируется текущий каталог (`.`).	Нет

Примеры использования:

1. Генерация плоской карты публичного API проекта:

chutils dev generate-context --project . -o api_map.md

2. Построение глубокого семантического JSON-индекса для AI-агентов:

chutils dev generate-context --project . --tree -o project_tree.json

Сбор метаданных и хэширование (Metadata & Hashes)

При каждом вызове generate-context утилита автоматически собирает и сохраняет следующие метаданные:

chutils_version — версия библиотеки chutils.
project_version — версия целевого проекта, извлеченная из pyproject.toml.
git_commit — SHA-1 хэш текущего git-коммита (и пометка (dirty), если есть незакоммиченные изменения).
generated_at — дата и время генерации в формате ISO 8601 UTC.
project_hash — детерминированный SHA-256 хэш проекта, вычисленный на основе путей и содержимого всех Python-файлов (с учетом фильтрации .gitignore и .chutilsignore).

Формат хранения:

Для Markdown (-f markdown): метаданные сохраняются в самом начале файла в виде блока YAML Frontmatter (между ---).
Для JSON (-f json или --tree): метаданные сохраняются в словаре верхнего уровня под ключом "metadata".

dev ai-lint

Проводит аудит проекта на соответствие лучшим практикам интеграции с ИИ. Проверяет качество типизации, полноту docstrings, размер файлов (LOC) и количество классов (CodeDecompositionRule), наличие файлов манифестов ( antigravity.md, agents.md, gemini.md), отсутствие захардкоженных секретов, а также синхронность связанных файлов и документации (FileDependencySyncRule).

Синтаксис подкоманды:

chutils dev ai-lint [-h] [--strict] [--soft-mode] [--ignore IGNORE] [--rules RULES] [--custom-rules-path CUSTOM_RULES_PATH] [--staged]

Параметры и флаги:

Флаг	Описание	Обязательный
`--strict`	Строгий режим: предупреждения трактуются как ошибки (возвращается ненулевой код выхода).	Нет
`--soft-mode`	Мягкий режим: всегда завершаться со статусом `0` даже при наличии серьезных ошибок.	Нет
`--ignore`	Исключаемые пути через запятую (например, `tests/,venv/,build/`). Также учитывает настройки из файлов `.gitignore` и `.chutilsignore`.	Нет
`--rules`	Список запускаемых правил через запятую (по умолчанию запускаются все правила).	Нет
`--custom-rules-path`	Путь к YAML/JSON файлу с пользовательскими правилами проверки.	Нет
`--staged`	Проверять только файлы, подготовленные к коммиту (staged) в Git. Позволяет значительно ускорить проверку в Git-хуках.	Нет

Примеры использования:

Запуск стандартного аудита:

chutils dev ai-lint

Вывод в консоли:

=== AI-Readiness Audit ===
[WARN] Файл 'gemini.md' не найден в корне проекта. Рекомендуется создать для улучшения инструкций ИИ.
[OK] Секреты в открытом виде не обнаружены.
[OK] Полнота аннотаций типов: 94%.
Аудит завершен. Найдено 1 предупреждение.

Встроенные правила линтинга:

Утилита включает в себя несколько встроенных правил проверки:

ManifestRule — Проверяет наличие ИИ-манифестов (antigravity.md, agents.md, gemini.md).
DocstringQualityRule — Оценивает полноту документации и аннотаций типов в кодовой базе.
SecurityHardcodeRule — Ищет случайно захардкоженные пароли, токены и приватные ключи.
ChutilsIntegrationRule — Проверяет корректность использования ленивого импорта и Rich-утилит библиотеки chutils.
APIMapRule — Требует наличия сгенерированного файла api_map.md (карты публичного API).
EnvSyncRule — Проверяет синхронность переменных в файлах .env и .env.example.
CodeDecompositionRule — Контролирует размер файлов (максимум 700 строк) и количество классов в файле (максимум 5).
APIMapHashRule — Вычисляет SHA-256 хэш проекта и сверяет его со значением, записанным в метаданных api_map.md. При обнаружении несовпадения выводит предупреждение о необходимости обновить карту API с помощью chutils dev generate-context -o api_map.md. Данное предупреждение не блокирует коммит/сборку (не приводит к ненулевому коду выхода даже в режиме --strict).
FileDependencySyncRule — Проверяет синхронность обновления связанных файлов и документации в соответствии с картой зависимостей.
UpgradeCheckRule — Обнаруживает изменение версии пакета в pyproject.toml по сравнению с Git HEAD. При повышении версии автоматически генерирует миграционный файл контекста для ИИ .chutils/migration_context.md на основе чейнджлогов релизов с GitHub API.

dev chat-context

Генерирует компактный и сфокусированный контекстный срез по конкретным подсистемам или описанию задачи, чтобы минимизировать размер контекста (число токенов) для LLM/AI-агентов. Если вызван без аргументов, запускается в интерактивном режиме с выводом меню выбора.

Синтаксис подкоманды:

chutils dev chat-context [-h] [-m MODULES] [-t TASK] [-l {public,internal,infrastructure,private,all}] [-o OUTPUT]

Параметры и флаги:

Флаг	Описание	Обязательный
`-m, --modules`	Список модулей через запятую для сбора контекста (например: `logger,config`).	Нет
`-t, --task`	Описание задачи или темы для автоматического подбора релевантных модулей (поиск по docstrings и именам символов).	Нет
`-l, --layer`	Фильтр по слоям абстракции: `public`, `internal`, `infrastructure`, `private`, `all` (по умолчанию: `public`).	Нет
`-o, --output`	Путь к файлу для сохранения результата. Если опущен, результат выводится в stdout.	Нет

Примеры использования:

1. Интерактивный режим выборки модулей:

chutils dev chat-context

2. Сбор публичного API и примеров для конкретной задачи:

chutils dev chat-context -t "logging and database connection setup" -o ai_context.md

3. Экспорт детального внутреннего контекста для выбранных модулей:

chutils dev chat-context -m logger,secret_manager -l internal -o logger_context.md

dev scaffold

Генерирует готовую структуру папок и шаблоны базовых файлов для нового функционального модуля по правилам Чистой Архитектуры (Clean Architecture) с соблюдением принципа инверсии зависимостей (Dependency Inversion) и строгой типизации.

Синтаксис подкоманды:

chutils dev scaffold [-h] [-o OUTPUT_DIR] [-f] module_name

Параметры и флаги:

Аргумент / Флаг	Описание	Обязательный
`module_name`	Имя создаваемого модуля (валидный Python-идентификатор в snake_case, например: `user_profile`).	Да
`-o, --output-dir`	Базовый путь для создания каталога модуля. По умолчанию создается в текущей директории с именем `module_name`.	Нет
`-f, --force`	Принудительно перезаписать файлы, если целевая папка уже существует и не пуста.	Нет

Создаваемая структура:

Сгенерированный модуль содержит следующие слои:

domain/ (Домен): Бизнес-сущности (entities.py), объекты-значения (value_objects.py) и абстрактные интерфейсы репозиториев (repositories.py). Не зависит от внешних библиотек и других слоев.
application/ (Прикладной слой): Сценарии использования (Use Cases в use_cases.py), которые оперируют интерфейсами домена.
infrastructure/ (Инфраструктура): Адаптеры баз данных/внешних API (db_adapters.py) и реализации репозиториев из домена (repositories.py).
presentation/ (Слой представления): Контроллеры для внешнего взаимодействия (cli.py и api.py).
container.py (DI): Контейнер зависимостей, связывающий все слои вместе.

Примеры использования:

1. Простая инициализация модуля в текущей директории:

chutils dev scaffold order_processing

2. Инициализация модуля с указанием пути вывода и перезаписью:

chutils dev scaffold user_auth -o ./src/user_auth -f

dev mock

Запускает локальный декларативный HTTP-сервер заглушек (мок-сервер) на базе YAML/JSON конфигурации. Поддерживает динамический роутинг (включая регулярные выражения с заменой групп в ответах), симуляцию задержек (delay), кастомные HTTP статус-коды, проксирование на реальный бэкенд (--proxy-fallback) и автоматическое обновление конфигурации "на лету" (Hot-Reload).

Синтаксис подкоманды:

chutils dev mock [-h] [-p PORT] [-r ROUTES] [--proxy-fallback PROXY_FALLBACK] {init} ...

Параметры и флаги:

Флаг / Подкоманда	Описание	Обязательный
`-p, --port`	Порт для запуска сервера (по умолчанию: `8888`).	Нет
`-r, --routes`	Путь к файлу конфигурации YAML или JSON (по умолчанию: `mocks.yml`).	Нет
`--proxy-fallback`	URL реального бэкенда для перенаправления запросов, если локальный роут заглушки не найден (например: `http://localhost:8000`).	Нет
`init [path]`	Подкоманда для инициализации шаблонного файла конфигурации `mocks.yml` (или по указанному пути).	Нет

dev mock init

Создает шаблонный файл конфигурации роутов mocks.yml (или по указанному пути) с примерами различных видов роутов, задержек и RegExp подстановок.

Пример вызова:

chutils dev mock init custom_mocks.yml

Формат файла конфигурации (YAML)

Пример сгенерированного mocks.yml файла:

# Декларативная конфигурация роутов для мок-сервера
# Поддерживаемые методы: GET, POST, PUT, DELETE, PATCH
# Поддерживается задержка (delay в секундах) и кастомные статусы (status)
# Поддерживается regex сопоставление путей при установке флага is_regex: true

- path: /api/users
  method: GET
  status: 200
  response:
    - id: 1
      name: "Иван Иванов"
    - id: 2
      name: "Петр Петров"

- path: /api/users/(\d+)
  method: GET
  is_regex: true
  status: 200
  response:
    id: "$1"
    name: "Пользователь $1"
    role: "user"

- path: /api/submit
  method: POST
  status: 201
  response:
    status: "success"
    message: "Данные успешно приняты"

- path: /api/slow-endpoint
  method: GET
  delay: 2.5
  status: 200
  response:
    message: "Этот ответ вернулся с задержкой 2.5 секунды"

Примеры использования:

1. Инициализация файла конфигурации по умолчанию:

chutils dev mock init

2. Запуск мок-сервера на порту 9000 с файлом custom_mocks.json:

chutils dev mock -p 9000 -r custom_mocks.json

3. Запуск с проксированием на рабочий бэкенд:

chutils dev mock --proxy-fallback http://localhost:8000

(При обращении к роуту, которого нет в mocks.yml, сервер прозрачно проксирует запрос на http://localhost:8000, сохраняя тело, заголовки и HTTP-метод).

dev install-hooks

Создает или обновляет pre-commit Git-хук в каталоге .git/hooks для автоматического запуска проверок перед фиксацией изменений.

Хук автоматически детектирует окружение (например, uv, poetry, pipenv, локальные .venv/venv директории или глобальный запуск) для правильного запуска команд.

Синтаксис подкоманды:

chutils dev install-hooks [-h] [-f] [--ruff] [--flake8]

Параметры и флаги:

Флаг / Аргумент	Описание	Обязательный
`-f, --force`	Принудительно перезаписать существующий файл `pre-commit` (без этого флага chutils допишет свой блок в конец существующего хука).	Нет
`--ruff`	Добавить автоматический вызов `ruff check --fix` и `ruff format` перед проверкой AI-готовности (`ai-lint`).	Нет
`--flake8`	Добавить автоматический вызов статического анализатора `flake8 .` в хук.	Нет

Примеры использования:

1. Стандартная установка хука только с проверкой ai-lint:

chutils dev install-hooks

2. Установка с форматированием кода и исправлением ошибок через Ruff:

chutils dev install-hooks --ruff

3. Принудительная перезапись существующего хука со всеми проверками (Ruff, Flake8, AI-ready linter):

chutils dev install-hooks -f --ruff --flake8

Примечание: Хуки устанавливаются с правами на выполнение (chmod +x). Убедитесь, что команда запускается из корня Git-репозитория.

dev generate-few-shot

Анализирует архитектуру целевого проекта с помощью AST-анализа и автоматически создаёт структурированный банк few-shot примеров в каталоге docs/ai_examples/. Примеры служат контекстом (few-shot prompting) для ИИ-ассистентов (Antigravity, Gemini CLI и др.), обучая их применять правильные архитектурные паттерны конкретного проекта.

Синтаксис подкоманды:

chutils dev generate-few-shot [-h] -p PROJECT [-f]

Параметры и флаги:

Флаг / Аргумент	Описание	Обязательный
`-p, --project`	Путь к корневой директории целевого проекта.	Да
`-f, --force`	Принудительно перезаписать существующие файлы при совпадении имён категорий (иначе они пропускаются).	Нет

Что генерируется:

Команда детектирует 5 архитектурных категорий и создаёт для каждой найденной папку в docs/ai_examples/<category>/ с тремя файлами:

Категория	Что детектируется	Файлы
`use_cases`	Классы с суффиксом `UseCase` или `Interactor`	`good_pattern.py`, `bad_pattern.py`, `README.md`
`repositories`	Классы с суффиксом `Repository` (абстрактные и конкретные)	`good_pattern.py`, `bad_pattern.py`, `README.md`
`logging`	Переменные-логгеры (`logging.getLogger`)	`good_pattern.py`, `bad_pattern.py`, `README.md`
`errors`	Пользовательские исключения (наследники `Exception`)	`good_pattern.py`, `bad_pattern.py`, `README.md`
`di`	DI-контейнеры (по имени файла или импорту DI-библиотеки)	`good_pattern.py`, `bad_pattern.py`, `README.md`

После генерации файлов команда создаёт или обновляет GEMINI.md в корне целевого проекта, добавляя блок со ссылками на банк примеров для ИИ-агентов.

Примеры использования:

1. Анализ и генерация банка примеров для текущего проекта:

chutils dev generate-few-shot -p ./my_project

Вывод в консоли:

🔍 Анализ проекта: ./my_project
✅ Категория 'use_cases': good_pattern.py, bad_pattern.py, README.md
✅ Категория 'repositories': good_pattern.py, bad_pattern.py, README.md
✅ Категория 'errors': good_pattern.py, bad_pattern.py, README.md
📝 GEMINI.md обновлён: ./my_project/GEMINI.md
Генерация завершена. Создано: 3 категории.

2. Повторная генерация с принудительной перезаписью (после изменений в коде проекта):

chutils dev generate-few-shot -p ./my_project --force

3. Генерация банка примеров для внешнего репозитория:

chutils dev generate-few-shot -p /path/to/another/repo

Примечание о слиянии: Без флага --force команда работает в режиме слияния — существующие папки категорий пропускаются, что позволяет добавлять новые категории без перезаписи пользовательских правок.

dev profile-imports

Профилирует время холодного старта и импорта модулей для выявления не-ленивых (тяжелых) зависимостей. Утилита запускает целевой импорт в изолированном подпроцессе с флагом -X importtime, парсит его вывод и визуализирует иерархическое дерево импортов, плоскую таблицу тяжелых импортов или экспортирует данные в формате JSON.

Синтаксис подкоманды:

chutils dev profile-imports [-h] [-t THRESHOLD] [--table] [--json] [target]

Параметры и флаги:

Флаг / Аргумент	Описание	Обязательный
`target`	Имя целевого модуля или путь к файлу для импорта (по умолчанию: `chutils`).	Нет
`-t, --threshold`	Порог времени в миллисекундах (float) для скрытия мелких веток импорта (по умолчанию: `1.0` мс).	Нет
`--table`	Вывести плоскую таблицу импортов, отсортированную по собственному времени (self time) по убыванию.	Нет
`--json`	Вывести распарсенные данные профилирования в формате JSON для машинного разбора.	Нет

Предупреждения и Аналитика:

В процессе работы утилита автоматически анализирует импорты и выводит предупреждения о потенциальных проблемах:

Дублирующиеся импорты (утечки) — модули, которые импортируются и инициализируются повторно.
Тяжелые не-ленивые импорты на верхнем уровне — обнаружение импорта тяжелых сторонних библиотек (таких как pydantic, watchdog, rich, keyring, yaml, dotenv и др.) на верхних уровнях иерархии (глубина 1 или 2). Рекомендуется переносить их импорт внутрь функций/методов (Lazy Import).

Примеры использования:

1. Отображение дерева импортов для chutils с порогом более 0.5 мс:

chutils dev profile-imports chutils -t 0.5

2. Отображение плоской таблицы тяжелых импортов:

chutils dev profile-imports --table

3. Экспорт дерева импортов в JSON для внешнего парсинга:

chutils dev profile-imports --json > import_tree.json

dev setup-github-actions

Настраивает и генерирует workflow-файл для GitHub Actions CI на основе Astral setup-uv. Поддерживает интерактивный режим (по умолчанию) и автоматический режим через CLI-параметры.

Синтаксис подкоманды:

chutils dev setup-github-actions [-h] [--interactive | --no-interactive] [--python-versions PYTHON_VERSIONS] [--with-pytest | --without-pytest] [--with-mypy | --without-mypy] [--with-ruff | --without-ruff] [--with-ai-lint | --without-ai-lint] [--output-file OUTPUT_FILE]

Параметры и флаги:

Флаг	Описание	Обязательный
`--interactive`	Запустить интерактивную настройку в консоли (по умолчанию).	Нет
`--no-interactive`	Использовать значения по умолчанию или явно переданные флаги.	Нет
`--python-versions`	Список версий Python через запятую (по умолчанию: `3.10,3.11,3.12,3.13`).	Нет
`--with-pytest / --without-pytest`	Включить/выключить запуск тестов с pytest.	Нет
`--with-mypy / --without-mypy`	Включить/выключить запуск статического анализа mypy.	Нет
`--with-ruff / --without-ruff`	Включить/выключить запуск линтера ruff.	Нет
`--with-ai-lint / --without-ai-lint`	Включить/выключить запуск ai-lint.	Нет
`--output-file`	Путь для сохранения workflow (по умолчанию: `.github/workflows/ci.yml`).	Нет

Примеры использования:

1. Интерактивная настройка:

chutils dev setup-github-actions

2. Быстрая генерация с дефолтными настройками без вопросов:

chutils dev setup-github-actions --no-interactive

3. Генерация с кастомными версиями Python без тестов:

chutils dev setup-github-actions --no-interactive --python-versions "3.11,3.12" --without-pytest --output-file ".github/workflows/main_ci.yml"

dev dashboard

Отображает интерактивный TUI-дашборд в терминале для просмотра, интерактивного ввода аргументов и запуска CLI-команд проекта (функций, декорированных @cli_command).

Синтаксис подкоманды:

chutils dev dashboard [-h]

Возможности:

Автоматический поиск команд — сканирует исходный код проекта с помощью статического AST-анализа для поиска функций с декоратором @cli_command.
Трехпанельный макет — список команд слева, подробное описание и форма аргументов справа сверху, лог выполнения в реальном времени справа снизу.
Интерактивный ввод — поддержка ввода строковых, числовых аргументов и bool-переключателей.
История параметров — сохраняет последние введенные параметры в .chutils_dashboard_history.json.
Изолированный запуск — выполняет выбранную команду в подпроцессе фонового потока, сохраняя отзывчивость интерфейса. Прерывание процесса клавишей Esc или Ctrl+C.

dev clean

Рекурсивно сканирует кодовую базу, находит стандартные артефакты сборки и кэши (__pycache__, .pytest_cache, .mypy_cache, .ruff_cache, .coverage, build/, dist/, *.egg-info и др.) и безопасно удаляет их.

Синтаксис подкоманды:

chutils dev clean [-h] [--dry-run] [-y | --yes | --force] [-e EXCLUDE] [-i INCLUDE]

Параметры и флаги:

Флаг	Описание	Обязательный
`--dry-run`	Вывести список найденных элементов и потенциально освобождаемый объем без физического удаления.	Нет
`-y, --yes, --force`	Удалить файлы сразу без интерактивного подтверждения.	Нет
`-e, --exclude`	Список исключаемых папок или шаблонов через запятую (например: `.venv,node_modules`).	Нет
`-i, --include`	Список дополнительных путей или шаблонов для удаления через запятую (например: `temp/,*.log`).	Нет

Настройка через `pyproject.toml`:

Вы можете переопределить стандартные списки исключений и добавить собственные шаблоны для очистки в секции [tool.chutils.clean]:

[tool.chutils.clean]
default_excludes = [".git", ".venv", "venv", ".idea", "site"]
extra_clean_targets = ["*.log", "tmp_data/"]

Примеры использования:

1. Просмотр списка мусорных файлов и объема диска без удаления:

chutils dev clean --dry-run

2. Быстрая очистка без вопросов:

chutils dev clean --yes

Инструменты разработчика и AI-контекст (chutils dev)

Синтаксис

Подкоманды:

dev generate-context

Синтаксис подкоманды:

Параметры и флаги:

Примеры использования:

Сбор метаданных и хэширование (Metadata & Hashes)

dev ai-lint

Синтаксис подкоманды:

Параметры и флаги:

Примеры использования:

Встроенные правила линтинга:

dev chat-context

Синтаксис подкоманды:

Параметры и флаги:

Примеры использования:

dev scaffold

Синтаксис подкоманды:

Параметры и флаги:

Создаваемая структура:

Примеры использования:

dev mock

Синтаксис подкоманды:

Параметры и флаги:

dev mock init

Пример вызова:

Формат файла конфигурации (YAML)

Примеры использования:

dev install-hooks

Синтаксис подкоманды:

Параметры и флаги:

Примеры использования:

dev generate-few-shot

Синтаксис подкоманды:

Параметры и флаги:

Что генерируется:

Примеры использования:

dev profile-imports

Синтаксис подкоманды:

Параметры и флаги:

Предупреждения и Аналитика:

Примеры использования:

dev setup-github-actions

Синтаксис подкоманды:

Параметры и флаги:

Примеры использования:

dev dashboard

Синтаксис подкоманды:

Возможности:

dev clean

Синтаксис подкоманды:

Параметры и флаги:

Настройка через pyproject.toml:

Примеры использования:

Инструменты разработчика и AI-контекст (`chutils dev`)

Настройка через `pyproject.toml`: