Project Architecture Mapper

Коротко: CLI для детерминированного построения архитектурной карты репозитория (ARCHITECTURE.md).

Quick start

Канонический путь: сначала установить пакет, затем использовать npx mapper .... Глобально TypeScript не нужен — он требуется только для разработки/сборки.

Установить пакет и проверить справку:

npm install @kwentin3/mapper
npx mapper --help

Первый запуск (генерация ARCHITECTURE.md для текущей папки):

npx mapper .

Windows notes

npx @kwentin3/mapper --help на Windows может быть нестабилен из-за особенностей npx/spawn. Рекомендуемый путь: установить пакет и запускать через npx mapper .... Запускайте из корня проекта.

Альтернатива (явный бин):

.\node_modules\.bin\mapper.cmd --help

PowerShell:

npx mapper --help

Bash:

npx mapper --help

Usage

Справка:

npx mapper --help

Базовый запуск (сканировать текущую папку):

npx mapper .

Точечный анализ файла (если нужен deep‑dive):

npx mapper --focus-file src/app/main.ts .

Troubleshooting

Если видите ошибку 'mapper' is not recognized:

• Убедитесь, что пакет установлен: npm install @kwentin3/mapper.
• Основная команда: npx mapper --help.
• Запускайте через npx mapper ... или .\node_modules\.bin\mapper.cmd ....

Кратко

Project Architecture Mapper — инструмент командной строки для статического анализа кода, который строит детерминированную архитектурную карту проекта и выводит её в формате Markdown (ARCHITECTURE.md). Цель — помочь разработчикам, архитекторам и автоматическим кодовым агентам безопасно ориентироваться в больших кодовых базах и принимать обоснованные решения по рефакторингу.

Для кого

• Разработчик, который исследует impact‑paths перед изменениями.
• Архитектор, который оценивает fan‑in / fan‑out и точки входа в систему.
• Кодовый агент (automation), которому нужна детерминированная, пригодная для автоматического разбора карта кода (не формальная схема).

Главная идея

Инструмент строит детерминированную (stable) архитектурную карту: сканирование → парсинг → резолв импортов → граф → сигналы → рендер. Вывод фокусируется на обозримых «сигналах» и path‑анализе, а не на изменении кода.

Зачем это нужно

Решает практические задачи:

• Навигация по большим кодовым базам — быстрый обзор точек входа и зависимостей.
• Impact analysis — какие файлы/модули затронет изменение.
• Снижение галлюцинаций LLM — предоставляет детерминированные, проверяемые факты о коде.

Чем не является

• Это не линтер и не checker стиля.
• Это не полная замена type‑checker'а (TypeScript, Flow и т.п.).
• Это не инструмент для принудительного применения best‑practices — сигналы производные и не навязывают изменений.

Быстрый старт (локальная сборка)

В каталоге проекта соберите и запустите CLI (Node >= 18, TypeScript dev environment):

Примеры (PowerShell):

1. Базовый запуск — сканировать текущую папку и записать ARCHITECTURE.md:

node dist/cli/main.js .

2. Фокус на одном файле (focused deep‑dive + impact path):

node dist/cli/main.js --focus-file src/app/main.ts .

3. Применить профиль (уменьшает объём inline сигналов и глубину глубокого анализа):

node dist/cli/main.js --profile fsd .

4. Показать все сигналы без бюджетов (детальный вывод):

node dist/cli/main.js --full-signals .

Как читать ARCHITECTURE.md

• AI Preamble — краткое объяснение, почему некоторые сигналы показаны и как ими пользоваться.
• Project Tree — дерево проекта с inline‑сигналами рядом с файлами.
• Summary — сводка: entrypoints, hub‑файлы по fan‑in/fan‑out.
• Local Dependencies — budgeted локальные зависимости и их влияние.
• --full-signals предназначен для аудита и спорных случаев; не рекомендуется как режим по умолчанию для больших репозиториев с кэшами и метаданными.
• Focused Deep‑Dive — детальный анализ выбранного файла (если использован --focus-file).
• Impact Path — пути воздействия от/к выбранному файлу.

Важно

• ARCHITECTURE.md генерируется CLI — не редактируйте файл вручную.
• Если карта устарела или вы изменяли код — перегенерируйте через CLI.
• Не анализируйте сгенерированные артефакты и кэши (например, artifacts/, out/, .cache/); исключайте их из сканирования, чтобы избежать PARSE-ERROR: UNSUPPORTED.

Роли и ответственность

• Источник истины для синтаксиса и списка флагов: вызов CLI с --help (например node dist/cli/main.js --help или установленный бин mapper --help). README предоставляет контекст и правила интерпретации вывода; он не заменяет --help как машинный контракт.

Основные сигналы (коротко)

• → ENTRYPOINT — помечает экспортируемые/публичные точки входа.
• Fan‑in / Fan‑out — узлы с высокой концентрацией входящих/исходящих зависимостей.
• [PROD] / [TEST] — пометка среды/назначения файла.
• ORPHAN — файл, на который нет ссылок или для которого граф зависимостей не построен (например, для языков или форматов без поддержки import-графа). ORPHAN не означает «безопасно для удаления».
• Contract signals — короткая индикация контрактного поведения: input / output / no contract.

Документация для разработчиков

Ссылки (не дублируя текст):

• docs/CLI.md
• docs/DEV_GUIDE.md
• docs/AGENT_MANIFEST.md
• docs/RENDER_CONTRACTS.md
• docs/test_policy_manifest.md
• docs/prd_project_architecture_mapper_v_0.9.md (PRD — источник архитектурной истины)

Инварианты проекта

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

Project Architecture Mapper

Project Architecture Mapper — инструмент командной строки для статического анализа кода, который строит детерминированную архитектурную карту проекта и выводит её в формате Markdown (ARCHITECTURE.md). Это краткая, инженерная справка — основной вход в документацию проекта.

Кому полезно

• Разработчикам и ревьюерам для оценки impact‑paths.
• Архитекторам для обнаружения hub‑файлов и зон высокой связности.
• Кодовым агентам для принятия обоснованных, детерминированных действий.

Ключевые тезисы

• Детерминированность: при тех же входных данных вывод должен быть стабильным.
• Статический анализ: проект не исполняет код и не делает динамической валидации.
• Derived signals: сигналы предназначены для информирования, а не для автоматического применения изменений.

Быстрый старт (минимум команд)

1. Собрать проект:

npm install
npm run build

2. Сгенерировать карту проекта (по умолчанию ARCHITECTURE.md):

node dist/cli/main.js .

3. Фокус на файле (deep‑dive + impact path):

node dist/cli/main.js --focus-file src/a.ts .

4. Полный вывод всех сигналов (без бюджетов):

node dist/cli/main.js --full-signals .

Как читать ARCHITECTURE.md

• AI Preamble — зачем и как использовать карту. Это текстовый навигационный блок: он не является машинной схемой и не предназначен для строгого парсинга.
• Project Tree — дерево проекта с inline‑сигналами.
• Summary — EntryPoints, Fan‑in/Fan‑out hubs.
• Local Dependencies — budgeted локальные зависимости. Обратите внимание: некоторые секции могут быть усечены в соответствии с выбранными бюджетами; используйте --full-signals, чтобы увидеть полный список сигналов. Отсутствие сигнала в выводе НЕ означает отсутствия соответствующей структуры в кодовой базе — для критичных решений эскалируйте к --full-signals.
• Focused Deep‑Dive и Impact Path — для целенаправленного анализа.

Мини‑карта структуры ARCHITECTURE.md

Стабильные разделы (заголовки ##) обычно используются как ориентиры/якоря при автоматическом разборе:

• AI Preamble
• Project Tree
• Summary (Entrypoints, Fan‑in/Fan‑out)
• Local Dependencies
• Focused Deep‑Dive
• Impact Path При интеграции ориентируйтесь на эти заголовки как точки входа для парсинга, но не полагайтесь на машинную структуру внутри AI Preamble.

Важно: ARCHITECTURE.md генерируется CLI — не редактируйте его вручную. Если информация устарела, перегенерируйте карту.

Документация разработчикам

• docs/CLI.md — справочник по флагам и рецепты использования.
• docs/DEV_GUIDE.md — базовое руководство по коду и тестам (с разделами по детерминизму и контрактной телеметрии).
• docs/prd_project_architecture_mapper_v_0.9.md — PRD (источник архитектурной правды).

Инварианты проекта

• Детерминизм
• Только статический анализ
• Derived signals, no enforcement
• Разделение анализа и рендера

Подробнее — смотрите docs/CLI.md и docs/DEV_GUIDE.md.