# CodePulse CLI — Полная документация (часть 1/3)

> Версия: **5.2.0** | Пакет: `@archpulse/codepulse` | Лицензия: MIT | Node.js ≥ 16

---

## Содержание

- [Часть 1](#): Обзор, стек, архитектура, установка, конфигурация, `scan`
- [Часть 2](#): `watch`, `diff`, `time-machine`, `health-trend`, `heatmap`, `coupling`, `audit`
- [Часть 3](#): `profile`, `ghost`, `synth`, `verify`, `pr-risk`, `review`, `agent`, `license`, `detect-reward-hacking`, MCP-сервер, GitHub Actions, плагины, i18n

---

## 1. Что такое CodePulse

**CodePulse** — CLI-инструмент для глубокого статического и структурного анализа кода, ориентированный на большие JS/TS и Python проекты. Его философия — **«Engineering Honesty»**: инструмент честно показывает архитектурные проблемы, не скрывая их.

### Ключевые возможности

- Строит **граф зависимостей** всего проекта через AST-анализ
- Обнаруживает **God Files** (файлы-монолиты), **Critical Nodes**, **циклические зависимости**
- Считает **Health Score** (0–100) как агрегированную метрику здоровья кодовой базы
- Выявляет **хотспоты** — файлы с высокой сложностью И частыми изменениями
- Анализирует **Temporal Coupling** (временну́ю связность) через git-историю
- Запускает **внешние линтеры** (ESLint, Oxlint, Ruff, Cppcheck, ShellCheck, GolangCI-Lint и др.)
- Предоставляет **MCP-сервер** для интеграции с AI-агентами (Claude, Cursor, Cline, Gemini, Copilot и др.)
- Поддерживает **машину времени** (Time Machine) — анализ эволюции метрик по git-истории
- Генерирует **HTML-отчёты**, **SARIF-файлы**, **SVG-бейджи**
- Отправляет **webhook-алерты** в Slack, Discord, Telegram при деградации Health Score
- Работает как **GitHub Action** для встраивания в CI/CD

---

## 2. Технологический стек

| Категория | Технология | Назначение |
|---|---|---|
| Язык | TypeScript 6.0 | Вся кодовая база CLI |
| Сборка | `tsc` | Компиляция в `dist/` |
| CLI-фреймворк | Commander.js 14 | Парсинг команд и флагов |
| AST (JS/TS) | `@babel/parser` + `@babel/traverse` | Разбор JS/TS файлов |
| AST (продвинутый) | `ts-morph` 28 | Глубокий анализ TypeScript |
| TUI-дашборд | `blessed` + `blessed-contrib` | Терминальный интерфейс (`watch`, `heatmap`) |
| Псевдотерминал | `node-pty` | Встроенный терминал внутри `watch` |
| Файловый вотчер | `chokidar` 5 | Слежение за изменениями файлов |
| Спиннеры | `ora` | Индикаторы прогресса |
| Цвета | `chalk` 4 | Цветной вывод в терминал |
| Шаблоны | `handlebars` | HTML-отчёты |
| Glob | `glob` 13 | Поиск файлов по маскам |
| GitHub API | `@octokit/rest` + `@actions/core` | Интеграция с GitHub Actions / PR-комментарии |
| MCP | `@modelcontextprotocol/sdk` | MCP-сервер для AI-агентов |
| Тесты | `vitest` 4 | Юнит-тесты |

---

## 3. Архитектура проекта

```
codepulse-cli/
├── src/
│   ├── index.ts                    # Точка входа CLI
│   ├── explain.ts                  # База знаний по архитектурным концепциям
│   ├── mcp-setup.ts                # Настройка MCP (запись конфигов для агентов)
│   ├── mcp-paths.ts                # Пути к конфиг-файлам MCP
│   │
│   ├── cli/commands/               # Регистрация CLI-команд (Commander.js)
│   │   ├── advanced-commands.ts    # coupling, pr-risk, explain, time-machine, profile, plugins
│   │   └── ...
│   │
│   ├── commands/                   # Реализация всех команд
│   │   ├── scan.ts          (412 строк)  # codepulse scan
│   │   ├── watch.ts        (1868 строк)  # codepulse watch — TUI-дашборд (God File)
│   │   ├── diff.ts          (435 строк)  # codepulse diff
│   │   ├── time-machine.ts  (197 строк)  # codepulse time-machine
│   │   ├── health-trend.ts  (369 строк)  # codepulse health-trend
│   │   ├── heatmap.ts       (247 строк)  # codepulse heatmap
│   │   ├── coupling.ts       (60 строк)  # codepulse coupling
│   │   ├── audit.ts          (98 строк)  # codepulse audit
│   │   ├── profile.ts       (174 строк)  # codepulse profile
│   │   ├── ghost.ts          (65 строк)  # codepulse ghost
│   │   ├── review.ts        (117 строк)  # codepulse review
│   │   ├── synth.ts          (80 строк)  # codepulse synth
│   │   ├── verify.ts        (218 строк)  # codepulse verify
│   │   ├── pr-risk.ts       (195 строк)  # codepulse pr-risk
│   │   ├── reward-hacking.ts(131 строк)  # codepulse detect-reward-hacking
│   │   ├── agent.ts         (342 строк)  # codepulse agent
│   │   ├── license.ts       (204 строк)  # codepulse license
│   │   ├── badge.ts                      # SVG-бейдж
│   │   ├── install-deps.ts  (398 строк)  # автоустановка линтеров
│   │   └── output.ts                     # форматирование статистики
│   │
│   ├── analyzer/                   # Ядро анализатора
│   │   ├── index.ts                # Главная функция analyze()
│   │   ├── scanner.ts              # Сканирование файлов (glob)
│   │   ├── ast.ts                  # AST-разбор JS/TS через Babel
│   │   ├── graph.ts                # Граф зависимостей, centrality, критические узлы
│   │   ├── git.ts                  # git-метрики: churn, temporal coupling
│   │   ├── workers.ts              # Worker-потоки для параллельного анализа
│   │   ├── cache.ts                # Кэш результатов (zlib-сжатие)
│   │   ├── python.ts               # Анализ Python-файлов
│   │   ├── rust.ts                 # Анализ Rust-файлов
│   │   ├── generic.ts              # Анализ остальных языков
│   │   ├── ast-fingerprint.ts      # AST-fingerprinting (дубли функций)
│   │   ├── architecture.ts         # Проверка архитектурных слоёв
│   │   ├── context.ts              # Загрузка .codepulse.json
│   │   ├── zlib.ts                 # Утилиты сжатия
│   │   └── time-machine/
│   │       ├── engine.ts           # Движок анализа git-истории
│   │       ├── cache.ts            # Кэш снапшотов (.codepulse-cache/snapshots/)
│   │       ├── sampling.ts         # Стратегии выборки коммитов
│   │       └── git-diff.ts         # Diff между коммитами
│   │
│   ├── rules/                      # Правила и линтеры
│   │   ├── index.ts                # Оркестратор (запускает все правила)
│   │   ├── security.ts             # Паттерны уязвимостей (regex-based)
│   │   ├── fastLinter.ts           # Быстрый встроенный линтер
│   │   ├── agents/registry.ts      # Реестр AI-агентов + мастер-правила CodePulse
│   │   └── linters/                # Адаптеры внешних линтеров
│   │       ├── javascript.ts       # ESLint / Oxlint
│   │       ├── python.ts           # Ruff
│   │       ├── rust.ts             # Clippy
│   │       ├── go.ts               # GolangCI-Lint, Revive
│   │       ├── cpp.ts              # Cppcheck
│   │       ├── lua.ts              # Luacheck, Selene
│   │       └── shell.ts            # ShellCheck
│   │
│   ├── mcp/                        # MCP-сервер
│   │   ├── server.ts               # Запуск MCP (stdio-транспорт)
│   │   ├── handlers-health.ts      # codepulse_identity, get_project_stats, analyze_project...
│   │   ├── handlers-architecture.ts# visualize_subgraph, get_blast_radius, find_cycles...
│   │   ├── handlers-agent.ts       # optimize_context, simulate_edit, store_memory...
│   │   └── definitions/            # JSON-схемы инструментов MCP
│   │
│   ├── reporter/
│   │   ├── html.ts                 # Генерация HTML-отчёта
│   │   ├── sarif.ts                # Генерация SARIF-файла
│   │   ├── health.ts               # Расчёт Health Score
│   │   └── stats.ts                # Агрегация статистики
│   │
│   ├── utils/
│   │   ├── i18n.ts                 # Интернационализация (7 языков)
│   │   ├── webhooks.ts             # Алерты: Slack, Discord, Telegram
│   │   ├── plugins.ts              # Загрузка плагинов
│   │   └── terminal.ts             # Символы терминала (UTF-8 / ASCII fallback)
│   │
│   └── locales/                    # UI-переводы (JSON)
│       └── en.json, ru.json, ua.json, de.json, fr.json, ko.json, cs.json
│
├── plugins/                        # Директория для пользовательских плагинов
├── rules/                          # Пользовательские правила
├── translations/                   # README на других языках
├── action.yml                      # GitHub Action
└── .codepulse.json                 # Конфигурация проекта
```

---

## 4. Установка

### Глобально через npm

```bash
npm install -g @archpulse/codepulse
```

### Через npx (без установки)

```bash
npx @archpulse/codepulse scan .
```

### Из исходников

```bash
git clone https://github.com/archpulse/codepulse-cli.git
cd codepulse-cli
npm install
npm run build
npm link   # делает 'codepulse' доступным глобально
```

### Системные требования

- **Node.js ≥ 16.0.0**
- Git (для метрик churn, temporal coupling, time-machine)
- Опционально: `oxlint`, `ruff`, `cppcheck`, `shellcheck`, `golangci-lint` (CodePulse может установить их автоматически командой `install-deps`)

---

## 5. Конфигурация `.codepulse.json`

Файл `.codepulse.json` в корне проекта управляет поведением всего анализатора.

### Полная схема с аннотациями

```json
{
  "exclude": ["benchmark", "dist", "node_modules"],
  "rootDir": "src",
  "godFileLines": 500,
  "godFileImports": 20,
  "criticalNodeThreshold": 15,
  "alerts": {
    "slack": "$CODEPULSE_SLACK_WEBHOOK",
    "discord": "$CODEPULSE_DISCORD_WEBHOOK",
    "telegram": {
      "token": "$TELEGRAM_BOT_TOKEN",
      "chatId": "$TELEGRAM_CHAT_ID"
    },
    "threshold": 80,
    "branches": ["main", "master"]
  },
  "architecture": {
    "layers": [
      {
        "name": "Domain",
        "pattern": "src/domain/**",
        "allowDependenciesFrom": []
      },
      {
        "name": "Application",
        "pattern": "src/commands/**",
        "allowDependenciesFrom": ["Domain"]
      }
    ]
  }
}
```

### Параметры

| Параметр | Тип | По умолчанию | Описание |
|---|---|---|---|
| `exclude` | `string[]` | `[]` | Директории/паттерны, исключаемые из анализа |
| `rootDir` | `string` | `"."` | Корневая директория для сканирования |
| `godFileLines` | `number` | `500` | Порог строк для признания файла God File |
| `godFileImports` | `number` | `20` | Порог импортов для признания файла God File |
| `criticalNodeThreshold` | `number` | `15` | Порог centrality для признания узла критическим |
| `alerts.slack` | `string` | — | URL Slack Incoming Webhook |
| `alerts.discord` | `string` | — | URL Discord Webhook |
| `alerts.telegram.token` | `string` | — | Токен Telegram-бота |
| `alerts.telegram.chatId` | `string` | — | ID чата/канала Telegram |
| `alerts.threshold` | `number` | `80` | Health Score < threshold → отправить алерт |
| `alerts.branches` | `string[]` | `["main","master"]` | Ветки, для которых работают webhook-алерты |
| `architecture.layers` | `Layer[]` | — | Определение архитектурных слоёв и допустимых зависимостей |

> **Env-переменные:** значения вида `"$VAR_NAME"` автоматически раскрываются из `process.env` при загрузке конфига.

### Архитектурные слои (`architecture.layers`)

Позволяют задать границы между модулями. Если слой нарушает правило зависимостей — CodePulse фиксирует `architecture-violation`.

```json
{
  "name": "Infrastructure",
  "pattern": "src/db/**",
  "allowDependenciesFrom": ["Domain", "Application"]
}
```

- `name` — произвольное имя слоя
- `pattern` — glob-маска файлов слоя
- `allowDependenciesFrom` — список слоёв, из которых разрешено импортировать этот слой

---

## 6. Команда `scan`

Основная команда — полный однократный анализ проекта.

### Синтаксис

```bash
codepulse scan [dir] [options]
```

### Что делает `scan` (шаг за шагом)

1. Проверяет наличие указанной директории
2. Автоматически устанавливает недостающие линтеры (`runInstallDepsForProject`)
3. Определяет движок линтинга: ESLint / Oxlint / auto
4. Запускает `analyze()` — ядро: AST, граф, git-метрики, линтеры, правила безопасности
5. Генерирует HTML-отчёт в `.codepulse-report/index.html`
6. Считает Health Score и генерирует SVG-бейдж `.codepulse-report/badge.svg`
7. Опционально генерирует SARIF-файл
8. Отправляет webhook-алерты в Slack/Discord/Telegram (если настроены и порог нарушен)
9. Выводит итоговую сводку в терминал

### Все флаги

| Флаг | Описание |
|---|---|
| `--json` | Вывод результатов в JSON на stdout (без UI-вывода) |
| `--sarif` | Генерация SARIF-файла для GitHub Code Scanning |
| `--open` | Открыть HTML-отчёт в браузере после анализа |
| `--strict` | Строгий режим: `dead-export` и `god-file` становятся `error` |
| `--debug` | Показать только программные ошибки (без linter-диагностики) |
| `--ld` | Только linter-диагностика (debug-режим линтера) |
| `--focus <type>` | Фильтр по типу проблемы |
| `--severity <level>` | Фильтр по уровню: `error`, `warning`, `info` |
| `--group-by <field>` | Группировка вывода: `file`, `type`, `severity` |
| `--max-issues <n>` | Показать не более N проблем |
| `--ignore-warnings` / `-iw` | Скрыть предупреждения |
| `--fail-on <severity>` | Выйти с кодом 1 при наличии проблем указанного уровня |
| `--precision` / `--eslint` | Принудительно использовать ESLint (точнее, но медленнее) |
| `--engine oxlint` | Принудительно использовать Oxlint (быстрее) |

### Краткие алиасы (нормализуются автоматически)

| Краткая форма | Развёртывается в |
|---|---|
| `-ld` | `--ld` |
| `-iw` | `--ignore-warnings` |
| `-diw` | `--debug --ignore-warnings` |
| `-ldiw` | `--ld --ignore-warnings` |

### Типы проблем (`--focus`)

| Тип | Описание |
|---|---|
| `dead-export` | Неиспользуемый экспорт |
| `god-file` | Файл-монолит (God File) |
| `critical-node` | Критический узел с высокой централизацией |
| `circular-dependency` | Циклическая зависимость |
| `vulnerability` | Паттерн уязвимости безопасности |
| `architecture-violation` | Нарушение архитектурных слоёв |
| `linter` | Диагностика внешнего линтера |
| `high-complexity` | Высокая цикломатическая сложность |
| `duplication` | Дублирование кода |

### Примеры

```bash
# Базовый скан
codepulse scan .

# JSON-вывод для CI/CD
codepulse scan . --json

# Только ошибки
codepulse scan . --severity error

# Строгий режим + выход с кодом 1 при ошибках
codepulse scan . --strict --fail-on error

# Фокус на мёртвом коде
codepulse scan . --focus dead-export

# Группировка по файлам
codepulse scan . --group-by file

# SARIF для GitHub Code Scanning
codepulse scan . --sarif

# ESLint (точный анализ)
codepulse scan . --precision

# Открыть отчёт в браузере
codepulse scan . --open

# Максимум 10 ошибок
codepulse scan . --severity error --max-issues 10
```

### Вывод в терминале

```
  ◆ CodePulse v5 — Engineering Honesty
  Scanning /path/to/project

  Engine: Auto (Resolving...)
  ✔ Analysis complete!

  Report: .codepulse-report/index.html
  Badge:  .codepulse-report/badge.svg
  Score:  87/100

  Files: 101  Lines: 16486  AvgComplexity: 2.90
  Issues: 2 errors  1 warning  (3 total)
```

### Как считается Health Score

| Фактор | Штраф |
|---|---|
| God Files | −10 за файл |
| Циклические зависимости | −8 за цикл |
| Critical Nodes | −5 за узел |
| Уязвимости | −7 за шт. |
| Dead Exports | −1 за шт. |
| Архитектурные нарушения | −6 за шт. |
| Хотспоты | −2 за шт. |

Диапазон: **0–100**. Цвет: 🟢 ≥ 90 / 🟡 ≥ 70 / 🔴 < 70.

---

# CodePulse CLI — Полная документация (часть 2/3)

## 7. Команда `watch`

Интерактивный TUI-дашборд реального времени. Следит за файлами и пересчитывает метрики при каждом сохранении.

### Синтаксис

```bash
codepulse watch [dir]
```

### Что делает `watch`

1. Поднимает Blessed-экран (терминальный UI на всё окно)
2. Запускает начальный анализ проекта
3. Начинает слежение за файлами через `chokidar` (дебаунс 700 мс)
4. При каждом изменении перезапускает `analyze()` и обновляет все панели дашборда
5. Опционально отправляет webhook-алерты при деградации Score

### Панели дашборда

| Панель | Позиция | Описание |
|---|---|---|
| **Health Gauge** | Верхняя строка, полная ширина | Полоса Health Score (0–100%) |
| **Cockpit Terminal** | Левая верхняя | Встроенный терминал для запуска codepulse-команд |
| **Telemetry** | Правая верхняя | Score, Files, Lines, Errors, Warnings, AvgComplexity |
| **Complexity Chart** | Левая средняя | График изменения средней сложности (последние 10 сканов) |
| **Hotspots Table** | Правая средняя | Топ-5 хотспотов по score |
| **Hazard Log** | Левая нижняя | Таблица всех найденных проблем (Severity / File:line / Message) |
| **Warp Log** | Правая нижняя | Лог событий: git-коммиты, webhook-статусы, события перезапуска |
| **Heatmap** (скрытая) | Ниже видимой области | Тепловая карта (открывается через Add Mode) |
| **Coupling** (скрытая) | Ниже видимой области | Temporal Coupling (открывается через Add Mode) |
| **MCP Box** (скрытая) | Ниже видимой области | Статус MCP-сервера (открывается через Add Mode) |
| **Clock Bar** | Нижняя строка | Часы (12/24ч в зависимости от локали) |

### Клавиши управления

| Клавиша | Действие |
|---|---|
| `Tab` | Переключение между панелями (цикл) |
| `1`–`9` | Быстрый переход к панели по номеру |
| `Esc` | Снять фокус с панели (режим прокрутки) |
| `c` | Свернуть/развернуть активную панель |
| `+` / `-` | Увеличить/уменьшить высоту панели |
| `[` / `]` | Уменьшить/увеличить ширину панели |
| `a` | Открыть **Add Mode** (добавить скрытую панель или терминал) |
| `s` | Открыть **Swap Mode** (поменять панели местами) |
| `x` | Закрыть активную панель |
| `Alt + ↑` / `Alt + ↓` | Прокрутить viewport вверх/вниз (Niri-стиль) |
| `Ctrl+C` | Выйти из `watch` |

### Cocpit Terminal (встроенный терминал)

Левая верхняя панель содержит встроенный терминал для запуска codepulse-команд прямо из дашборда. Нажмите `Tab` для фокуса, введите команду и нажмите `Enter`.

**Доступные команды в Cocpit:**

```
scan       audit       coupling    heatmap     health-trend
ghost      dead        graph       badge       review
synth      verify      detect-reward-hacking   diff
pr-risk    explain     time-machine             profile
stats      plugins     list        help
```

Вывод команды отображается в лог-области панели (до 120 строк). ANSI-коды автоматически стрипаются.

### Поддерживаемые расширения для watch

```
.ts  .tsx  .js  .jsx  .py  .java  .cpp  .c  .cs  .lua  .css  .scss  .html
```

### Игнорируемые паттерны

```
**/node_modules/**   **/.git/**   **/dist/**
**/build/**          **/coverage/**   **/.codepulse-report/**   **/*.min.js
```

### Add Mode (`a`)

В Add Mode (статусная строка становится жёлтой):
- Нажмите цифру `1`–`9` чтобы восстановить одну из закрытых панелей
- Нажмите `t` чтобы создать новую **bash-панель** (полноценный терминал через `node-pty`)
- Нажмите `h` чтобы показать список доступных панелей
- `Esc` — отмена

### Swap Mode (`s`)

Позволяет поменять две панели местами. Выберите активную панель, нажмите `s`, затем цифру второй панели.

### Технические детали `watch`

- **Debounce:** 700 мс между последним изменением файла и запуском анализа
- **Polling:** 1000 мс для обычных файлов, 3000 мс для бинарных
- **Blink:** мигание индикаторов каждые 500 мс
- **Clock:** часы обновляются каждую секунду; формат зависит от локали (12ч для en/ko, 24ч для остальных)
- **Monkey-patch:** `pty.js` перехватывается и перенаправляется на `node-pty` (совместимость с `blessed`)
- **Viewport:** скроллируемый (Niri-стиль) — панели могут быть ниже видимой области экрана

---

## 8. Команда `diff`

Сравнивает архитектурное состояние текущей ветки с целевой.

### Синтаксис

```bash
codepulse diff <branch> [options]
```

### Что делает `diff`

1. Запоминает текущую ветку
2. Анализирует текущую ветку (`analyze()`)
3. Сохраняет незакоммиченные изменения через `git stash` (если есть)
4. Делает `git checkout <branch>` и анализирует целевую ветку
5. Возвращается на исходную ветку, восстанавливает `git stash pop`
6. Строит отчёт о разнице

### Что сравнивается

| Метрика | Описание |
|---|---|
| **Health Score** | Дельта (текущий − целевой) |
| **God Files** | Новые God Files / исчезнувшие God Files |
| **Circular Dependencies** | Новые циклы / устранённые циклы |
| **Issues (Errors/Warnings)** | Новые / решённые проблемы |
| **Critical Nodes** | Новые / устранённые критические узлы |

### Флаги

| Флаг | Описание |
|---|---|
| `--json` | Вывод отчёта в JSON |
| `--threshold <n>` | Выйти с кодом 1 если Health Score упал более чем на N пунктов |

### Примеры

```bash
# Сравнить с main
codepulse diff main

# Сравнить и провалить CI если деградация > 5 пунктов
codepulse diff main --threshold 5

# JSON-вывод
codepulse diff develop --json
```

### Вывод (пример)

```
╭─ CodePulse Diff Report ────────────────────────────╮
│ Current: feature/new-module  →  Target: main        │
├─────────────────────────────────────────────────────┤
│ Health Score:  85 → 90  (▲5)                        │
├─────────────────────────────────────────────────────┤
│ God Files                                           │
│   + NEW  src/commands/big-feature.ts                │
├─────────────────────────────────────────────────────┤
│ Issues Delta                                        │
│   + 3 new errors                                    │
│   − 1 resolved warning                              │
├─────────────────────────────────────────────────────┤
│ 3 new issues  │  1 resolved                         │
╰─────────────────────────────────────────────────────╯
```

---

## 9. Команда `time-machine`

Анализирует эволюцию архитектуры проекта по git-истории.

### Синтаксис

```bash
codepulse time-machine [dir] [options]
```

### Что делает `time-machine`

1. Обходит git-историю согласно выбранной стратегии выборки
2. Для каждого выбранного коммита: checkout → analyze() → сохранение снапшота
3. Использует кэш (`.codepulse-cache/snapshots/`) — повторный анализ одного коммита пропускается
4. Выводит сводную статистику эволюции

### Стратегии выборки (`--strategy`)

| Стратегия | Флаг | Описание |
|---|---|---|
| `max-points` | `--strategy max-points --commits 30` | Равномерно выбирает N точек из всей истории (по умолчанию) |
| `every-nth` | `--strategy every-nth --commits 10` | Каждый N-й коммит |
| `interval` | `--strategy interval --interval weekly` | По временно́му интервалу: `daily`, `weekly`, `monthly` |
| `tag-only` | `--strategy tag-only` | Только теговые коммиты (релизы) |

### Флаги

| Флаг | Описание |
|---|---|
| `--commits <n>` | Количество точек выборки (по умолчанию: 30) |
| `--strategy <type>` | Стратегия: `max-points`, `every-nth`, `interval`, `tag-only` |
| `--interval <period>` | Для `interval`: `daily`, `weekly`, `monthly` |
| `--since <date>` | Анализировать только коммиты после даты (`2024-01-01`) |
| `--json` | Вывод в JSON |

### Примеры

```bash
# 30 равномерных точек по всей истории
codepulse time-machine .

# Последние 6 месяцев еженедельно
codepulse time-machine . --strategy interval --interval weekly --since 2024-01-01

# Только релизы
codepulse time-machine . --strategy tag-only

# JSON для дальнейшей обработки
codepulse time-machine . --json > history.json
```

### Вывод (пример)

```
  ════════════════════════════════════════════════════
  Dependency Graph Time Machine
  ════════════════════════════════════════════════════

  Commits scanned:  150
  Snapshots taken:  30
  AST parses:       87
  Cache hits:       63 (cache efficiency: 42%)

  Timeline:
  Jan 2024 → May 2026
  Files: 45 → 101
  Lines: 4200 → 16486
  Avg Complexity: 2.1 → 2.9
  Dependencies: 120 → 340 (+220)

  Evolution Insights (v2):
  Health Score:  95 → 82 (▼13)
  Regressions:   Detected 2 major complexity spikes.
    ! a3f5b2c: feat: add watch TUI dashboard...
    ! 8d1e094: refactor: merge all handlers...

  Risky Module Forecasting:
  Trend:           Degrading
  Projected Cplx:  4.2 (in next 3 months)
  WARNING  Architectural drift detected. Refactoring recommended soon.

  ✓ Snapshots saved to .codepulse-cache/snapshots/
```

### Кэш снапшотов

Снапшоты хранятся в `.codepulse-cache/snapshots/`. Каждый снапшот содержит:
- `sha` — хэш коммита
- `date` — дата коммита
- `message` — сообщение коммита
- `stats` — `{ files, totalLines, avgComplexity, healthScore, hotspots[] }`
- `graph` — `{ nodes[], edges[], circularDependencies[] }`

---

## 10. Команда `health-trend`

Визуализирует тренды метрик на основе сохранённых снапшотов.

### Синтаксис

```bash
codepulse health-trend [dir] [options]
```

### Что делает `health-trend`

1. Загружает снапшоты из `.codepulse-cache/snapshots/`
2. Если снапшотов нет — автоматически запускает `time-machine` с 15 точками
3. Строит спарклайны (Unicode-гистограммы) для каждой метрики
4. Показывает тренд (Improving / Regressing / Stable), лучший/худший момент, пики сложности

### Флаги

| Флаг | Описание |
|---|---|
| `--since <date>` | Только снапшоты после указанной даты |
| `--json` | Вывод в JSON |

### Пример вывода

```
  ══════════════════════════════════════════════════════════════
  Health Score Evolution
  ══════════════════════════════════════════════════════════════

  Health    ▅▆▇▇▆▅▄▄▅▆▆▇▇  95 → 82  (↓13)  Regressing ✗
  Complex   ▂▂▃▃▃▄▄▄▄▅▅▅▅  2.1 → 2.9  (↑0.8)  Regressing ✗
  Files     ▂▃▃▄▄▄▅▅▆▆▆▇▇  45 → 101  (+56)  Growing
  Issues    ▁▁▁▂▂▂▃▃▄▄▄▅▅  0 → 3  (↑3)  Regressing ✗

  Timeline: Jan 2024 ──────────────────── May 2026
  Snapshots: 30 commits analyzed

  Key Moments:
    ✓ Best:  a1b2c3 (Mar 2024) → Score: 97
    ✗ Worst: 9f8e7d (Apr 2026) → Score: 78
    ! Spike: 4c3b2a (Jan 2026) → Complexity jumped 35%
```

### JSON-структура (`--json`)

```json
{
  "snapshots": [
    { "sha": "abc1234", "date": "2024-01-15", "health": 95, "complexity": 2.1, "files": 45, "issues": 0 }
  ],
  "trends": {
    "health":     { "first": 95, "last": 82, "delta": -13, "direction": "down" },
    "complexity": { "first": 2.1, "last": 2.9, "delta": 0.8, "direction": "up" },
    "files":      { "first": 45, "last": 101, "delta": 56, "direction": "up" },
    "issues":     { "first": 0, "last": 3, "delta": 3, "direction": "up" }
  }
}
```

---

## 11. Команда `heatmap`

Интерактивная тепловая карта рисков файлов в TUI-интерфейсе.

### Синтаксис

```bash
codepulse heatmap [dir]
```

### Что делает `heatmap`

1. Запускает `analyze()` для проекта
2. Для каждого файла вычисляет **Risk Score** по формуле:

```
Risk = Complexity × log₂(Churn + 1) × (1 + Centrality / MaxCentrality)
```

3. Сортирует файлы по Risk Score
4. Открывает Blessed TUI с тремя панелями:
   - **Header** — общая статистика проекта
   - **Bar Chart** — риск по директориям (топ-12)
   - **Table** — все файлы, отсортированные по риску (прокручиваемая)

### Уровни риска

| Уровень | Диапазон | Цвет |
|---|---|---|
| Low | 0–3 | 🟢 Зелёный |
| Medium | 3–7 | 🟡 Жёлтый |
| High | 7+ | 🔴 Красный |

### Клавиши

| Клавиша | Действие |
|---|---|
| `↑` / `↓` | Прокрутка таблицы файлов |
| `q` / `Esc` / `Ctrl+C` | Выйти |

### Пример (упрощённо)

```
╔═══ CodePulse Heatmap ══════════════════════════════════╗
║ Project: my-app  Files: 101  Avg Risk: 1.8  High: 0   ║
║ Risk = complexity × log₂(churn + 1) × (1 + c/maxC)   ║
╠═══ Risk by Directory ══════════════════════════════════╣
║ [commands ████████]  [analyzer ██████]  [mcp ████]    ║
╠═══ Files by Risk Score ════════════════════════════════╣
║ File                   Risk  Complexity  Churn  Cntrl ║
║ src/commands/watch.ts  5.50  8.10        6      0.043 ║
║ src/analyzer/index.ts  3.21  5.20        4      0.031 ║
║ ...                                                    ║
╠═══ Legend ═════════════════════════════════════════════╣
║ ■ Low (0-3)  ■ Medium (3-7)  ■ High (7+)  q: quit   ║
╚════════════════════════════════════════════════════════╝
```

---

## 12. Команда `coupling`

Обнаруживает файлы, которые часто изменяются вместе в одних и тех же git-коммитах (Temporal Coupling).

### Синтаксис

```bash
codepulse coupling [dir]
```

### Что такое Temporal Coupling

Если файлы A и B изменяются в 80% одних и тех же коммитов — они **темпорально связаны**. Это скрытая зависимость, которой нет в `import`-графе. Высокая временна́я связность — сигнал, что файлы нарушают SRP или скрыто зависят друг от друга.

### Пример вывода

```
    Temporal Coupling Detector
  (Files that frequently change together in the same commit)

  File A                              File B                              Degree
  ────────────────────────────────────────────────────────────────────────────
  src/commands/watch.ts               src/analyzer/index.ts               87%
  src/mcp/handlers-health.ts          src/mcp/handlers-architecture.ts    72%
  src/rules/index.ts                  src/rules/security.ts               65%
  ...

  * threshold: 50% co-change rate. Filtered by 8 pairs.
```

### Применение

- Найти скрытые зависимости перед рефакторингом
- Понять, какие файлы нужно тестировать вместе
- Использует команда `pr-risk` для предупреждений

---

## 13. Команда `audit`

Глубокий архитектурный аудит с генерацией `AUDIT.md`.

### Синтаксис

```bash
codepulse audit [dir]
```

### Что делает `audit`

1. Запускает `analyze()` в режиме precision (ESLint)
2. Вычисляет Health Score
3. Генерирует `AUDIT.md` в директории проекта
4. Выводит краткое резюме в терминал

### Структура `AUDIT.md`

```markdown
# 🏥 CodePulse Architectural Audit Report

**Date:** 2026-05-20T17:00:00.000Z
**Project Health Score:** 87/100

## 📋 Executive Summary
The project architecture is healthy but showing signs of technical debt...

## 🗺️ Architectural Landmarks

### ⚡ Critical Nodes (High Centrality)
- **src/analyzer/index.ts** (Centrality: 0.87)
- **src/commands/watch.ts** (Centrality: 0.43)

### 🐘 God Files (High Complexity & Coupling)
- **src/commands/watch.ts** (Complexity: 8.1, Lines: 1868)

### 🔄 Circular Dependencies
- src/analyzer → src/rules → src/analyzer

## ✅ Recommended Actions
1. Break Cycles: Refactor the identified circular dependencies...
2. Decompose God Files: Split watch.ts into smaller modules...
3. Increase Test Coverage: Ensure Critical Nodes have near-100% test coverage.
```

### Вывод в терминале

```
 Audit Executive Summary
────────────────────────────────────────
Health Score:   87/100
Critical Nodes: 2
God Files:      1
Cycles:         0
────────────────────────────────────────
 Tip: Use 'codepulse explain' to deep dive into specific findings.
```

### Резюме по Health Score

| Диапазон | Сообщение |
|---|---|
| > 90 | "The project architecture is in excellent shape..." |
| 70–90 | "The project architecture is healthy but showing signs of technical debt..." |
| < 70 | "CRITICAL: The project architecture is highly coupled and complex..." |

---

# CodePulse CLI — Полная документация (часть 3/3)

## 14. Команда `profile`

Коррелирует данные профайлера (V8 / Python cProfile) с AST-метриками кода.

### Синтаксис

```bash
codepulse profile <file> [options]
```

### Флаги

| Флаг | Описание |
|---|---|
| `-d, --dir <dir>` | Директория проекта (по умолчанию: `.`) |
| `--lang <js\|ts\|py>` | Принудительный язык (авто-определение по расширению) |
| `--top <n>` | Топ N хотспотов (по умолчанию: 20) |
| `--json` | Вывод в JSON |

### Поддерживаемые форматы профайлеров

| Расширение | Формат |
|---|---|
| `.cpuprofile` | V8 CPU Profile (Node.js / Chrome DevTools) |
| `.prof`, `.pstats` | Python cProfile |

### Категории долга

| Категория | Описание |
|---|---|
| `active-hotspot` | Высокая CC + большое время выполнения |
| `dormant-debt` | Высокая CC, но редко вызывается |
| `io-bound` | Долго работает, но CC низкая (вероятно I/O) |

### Примеры

```bash
# V8 профиль
codepulse profile cpu.cpuprofile --dir ./my-app

# Python профиль
codepulse profile app.prof --lang py --top 10

# JSON-вывод
codepulse profile cpu.cpuprofile --json
```

---

## 15. Команда `ghost`

Вычисляет «Blast Radius» файла — сколько модулей пострадает при его изменении.

### Синтаксис

```bash
codepulse ghost <file> [options]
```

### Что делает `ghost`

1. Находит узел файла в графе зависимостей
2. Находит прямые зависимости (кто импортирует этот файл)
3. Рекурсивно обходит граф для подсчёта транзитивного влияния
4. Выводит процент затронутых файлов от общего числа

### Пример вывода

```
 Blast Radius: src/analyzer/index.ts
──────────────────────────────────────────────────────
  ⚠️  Changes to this file directly impact 12 modules:
    ➔ src/commands/scan.ts
    ➔ src/commands/watch.ts
    ➔ src/mcp/handlers-health.ts
    ...
──────────────────────────────────────────────────────
Total Project Impact: 45 / 101 files (44.6%)

  ⚠️  WARNING: HIGH BLAST RADIUS. This is a Core Architectural Node.
```

---

## 16. Команда `synth`

Генерирует синтетический план стресс-тестирования на основе критических узлов.

### Синтаксис

```bash
codepulse synth [dir]
```

### Что делает `synth`

1. Находит Critical Nodes и God Files (топ-3 каждого)
2. Для каждого узла генерирует сценарии тестирования
3. Сохраняет результат в `STRESS_TEST_PLAN.md`

### Структура `STRESS_TEST_PLAN.md`

```markdown
# 🧪 CodePulse Synthetic Test Plan

## 🎯 Priority Targets

### 🔴 watch.ts (God File)
- [ ] Integration Boundary Test
- [ ] Dependency Failure Simulation
- [ ] Concurrency Stress
- [ ] State Mutation Audit

## 🛠️ Implementation Heuristics
1. Mock Everything
2. Fuzzing
3. Snapshot Testing
```

---

## 17. Команда `verify`

Комплексная верификация проекта: typecheck → build → lint → тесты.

### Синтаксис

```bash
codepulse verify [dir]
```

### Что делает `verify`

1. Определяет стек (`typescript-node`, `javascript-node`, `python`)
2. Запускает шаги верификации в зависимости от стека:
   - **TypeScript**: `tsc --noEmit` → `npm run build` → `npm run lint`
   - **Python**: `ruff check .`
3. Находит изменённые файлы через `git diff --name-only HEAD`
4. По графу зависимостей определяет impacted тесты
5. Запускает только затронутые тесты (vitest / jest)
6. При провале показывает вероятную причину (Root Cause Analysis)

### Пример вывода

```
Starting Project Verification in /path/to/project
──────────────────────────────────────────────────
✔ Typecheck
✔ Build
✔ Lint
✔ Tests passed: 3 / 3
──────────────────────────────────────────────────

✅ Verification successful! Project is in GOD MODE. ✓
```

---

## 18. Команда `pr-risk`

Оценивает архитектурный риск Pull Request по изменённым файлам.

### Синтаксис

```bash
# Через флаг
codepulse pr-risk --files src/a.ts,src/b.ts

# Через stdin (pipe из git diff)
git diff --name-only HEAD | codepulse pr-risk
```

### Флаги

| Флаг | Описание |
|---|---|
| `--files <list>` | Список файлов через запятую |
| `--stdin` | Читать список файлов из stdin |
| `--threshold <n>` | Порог риска для exit code 1 (по умолчанию: 60) |

### Формула риска для файла

```
Centrality Score  = min(centrality/50, 1)  × 30
Complexity Score  = min(complexity/30, 1)   × 25
Churn Score       = min(churn/50, 1)        × 15
God File penalty                            +20
Critical Node penalty                       +15
─────────────────────────────────────────────────
Total Risk Score                    = min(sum, 100)
```

### Дополнительно: Temporal Coupling предупреждения

Если изменён файл A, но не изменён темпорально связанный с ним файл B (степень ≥ 70%) — выводится предупреждение.

### Пример вывода

```
  🔴 PR Risk Score:  72/100
  ────────────────────────────────────────

  src/analyzer/index.ts
    ● High centrality (43)
    ● Risk contribution:  55 pts

  src/commands/watch.ts
    ● God File detected
    ● Risk contribution:  72 pts

  ⚠️  Missing from PR but temporally coupled:
    • src/commands/scan.ts (coupled with src/analyzer/index.ts)
```

---

## 19. Команда `review`

Комплексный CI-ревью: анализ + проверка PR + опциональный комментарий в GitHub PR.

### Синтаксис

```bash
codepulse review [dir] [options]
```

### Флаги

| Флаг | Описание |
|---|---|
| `--github` | Опубликовать отчёт как комментарий к GitHub PR |
| `--json` | Вывод в JSON |

### Что делает `review`

1. Запускает `analyze()`
2. Получает список изменённых файлов (`git diff HEAD^ HEAD`)
3. Проверяет наличие критических ошибок и новых God Files
4. Рассчитывает Impact Score для каждого изменённого файла
5. Генерирует Markdown-отчёт
6. С `--github`: публикует отчёт как комментарий к PR через `@octokit/rest`

### Переменные окружения для `--github`

```bash
GITHUB_TOKEN=...          # токен с правами на comments
GITHUB_EVENT_PATH=...     # путь к event.json (устанавливается Actions автоматически)
GITHUB_REPOSITORY=...     # owner/repo
FAIL_ON_CRITICAL=true     # выйти с кодом 1 при критических ошибках
```

---

## 20. Команда `agent`

Настраивает AI-агентов (Cursor, Cline, Claude, Copilot и др.) с правилами CodePulse.

### Синтаксис

```bash
codepulse agent <agent-name> [prompt-name]
codepulse agent config          # TUI-конфигуратор промптов
codepulse agent prompt config   # Добавить новый промпт
```

### Поддерживаемые агенты (23 агента)

| Агент | Файл |
|---|---|
| Cline / Roo-Cline | `.clinerules` |
| Cursor | `.cursorrules` |
| Windsurf | `.windsurfrules` |
| GitHub Copilot | `.github/copilot-instructions.md` |
| Claude Code | `CLAUDE.md` |
| Claude Rules | `.clauderules` |
| Codex CLI | `.codexrules` / `CODEX.md` |
| Aider | `.aider.conf.yml` |
| Gemini CLI | `.gemini-instructions.md` |
| Qwen | `.qwenrules` |
| AMP | `.amprules` |
| OpenCode | `.opencoderules` |
| Kilo | `.kilorules` |
| Trae | `.traerules` |
| Pi Coding Agent | `.pirules` |
| Kiro CLI | `.kirorules` |
| PearAI | `.pearrules` |
| Supermaven | `.supermavenrules` |
| Void | `.voidrules` |
| **Antigravity** | `.antigravityrules` |
| Cody (Sourcegraph) | `.cody/AGENT.md` |
| Continue.dev | `.continue/rules/codepulse.md` |

### Встроенные промпты

| Промпт | Описание |
|---|---|
| `default` | Мастер-правила CodePulse (5-фазный протокол анализа) |
| `creative` | Creative Architect Mode — сначала брейншторм, потом реализация |
| `productivity` | Productivity Mode — прямые действия без переусложнения |

### Примеры

```bash
# Настроить Claude с правилами CodePulse
codepulse agent claude default

# Настроить Cursor с creative-промптом
codepulse agent cursor creative

# Открыть TUI-конфигуратор промптов
codepulse agent config

# Добавить собственный промпт
codepulse agent prompt config
```

### Мастер-правила CodePulse (`default`)

Содержат 5-фазный протокол для AI-агентов:
1. **PHASE 1 — Reconnaissance**: `codepulse_identity` для карты проекта
2. **PHASE 2 — Structural Audit**: `get_layers` + `get_architecture_violations`
3. **PHASE 3 — Pre-flight Risk**: `get_file_context` перед каждым редактированием
4. **PHASE 4 — Surgical Execution**: `find_similar_functions` для AST-дедупликации
5. **PHASE 5 — Validation**: `get_project_stats` + `get_architecture_violations` после изменений

---

## 21. Команда `license`

Генерирует файл `LICENSE` с выбранной лицензией.

### Синтаксис

```bash
codepulse license <type> [author-name]
codepulse license help    # список лицензий
```

### Поддерживаемые лицензии

`mit` · `isc` · `bsd-2` · `bsd-3` · `unlicense` · `apache` · `gpl` · `agpl` · `lgpl` · `mpl`

### Пример

```bash
codepulse license mit "John Doe"
# → создаёт ./LICENSE с текущим годом и именем автора
```

---

## 22. Команда `detect-reward-hacking`

Обнаруживает паттерны «reward hacking» в AI-генерированном коде через AST-анализ (`ts-morph`).

### Синтаксис

```bash
codepulse detect-reward-hacking [dir]
```

### Что ищет

| Паттерн | Тип | Описание |
|---|---|---|
| Hardcoded I/O shortcuts | `IO_SHORTCUT` | `if (input === "x") return "y"` — захардкоженные ответы |
| Large literal lookup tables | `BENCHMARK_HACK` | Object с >8 литеральными свойствами (имитация вычислений) |
| Validation bypasses | `VALIDATION_BYPASS` | Условия с `IS_BENCHMARK`, `is_test`, `bypass` |

### Пример вывода

```
🕵️  Detected 2 Reward Hacking patterns!

[IO_SHORTCUT] src/calculator.ts:42
  Suspicious hardcoded input-output shortcut detected.
  > if (input === "2+2") return "4";

[BENCHMARK_HACK] src/solver.ts:15
  Suspiciously large literal lookup table (12 entries).
  > { "test1": "result1", "test2": "result2", ...
```

---

## 23. Команда `install-deps`

Автоматически устанавливает внешние линтеры, необходимые для анализа проекта.

### Синтаксис

```bash
codepulse install-deps
```

### Поддерживаемые инструменты и менеджеры пакетов

| Инструмент | Язык | Менеджеры |
|---|---|---|
| `oxlint` | JS/TS | npm (global) |
| `ruff` | Python | pip / pacman / apk |
| `cppcheck` | C/C++ | apt / pacman / dnf / brew |
| `shellcheck` | Shell | apt / pacman / brew |
| `golangci-lint` | Go | go install / brew / scoop |
| `revive` | Go | go install |
| `luacheck` | Lua | luarocks / apt |
| `selene` | Lua | cargo / brew / scoop |
| `clippy` | Rust | rustup / cargo |

**Обнаруживаемые менеджеры пакетов:** `apt-get`, `pacman`, `dnf`, `zypper`, `apk` (Linux), `brew` (macOS), `choco`, `scoop`, `winget` (Windows).

**`runInstallDepsForProject`** — вызывается автоматически при `scan`: сканирует расширения файлов и устанавливает только нужные инструменты.

---

## 24. MCP-сервер

CodePulse включает полноценный **Model Context Protocol (MCP) сервер** для интеграции с AI-агентами.

### Запуск

```bash
codepulse mcp          # запустить MCP-сервер (stdio-транспорт)
codepulse mcp setup    # записать конфигурацию MCP в файлы агентов
```

### Все MCP-инструменты

**Здоровье проекта:**

| Инструмент | Описание |
|---|---|
| `codepulse_identity` | Полный health-check: God Files, Critical Nodes, Score |
| `get_project_stats` | Быстрые числовые KPI (файлы, строки, сложность) |
| `analyze_project` | Фильтруемый список проблем (focus, severity, limit) |
| `find_dead_code` | Список неиспользуемых экспортов |
| `get_hotspots` | Файлы с высокой сложностью и частыми изменениями |
| `explain_concept` | Объяснение концепций (god-file, dead-export и др.) |

**Архитектура и граф:**

| Инструмент | Описание |
|---|---|
| `get_file_context` | Полный контекст файла: complexity, centrality, temporal coupling |
| `get_file_dependencies` | Импорты и импортёры файла |
| `get_blast_radius` | Транзитивный blast radius файла |
| `visualize_subgraph` | Mermaid-диаграмма зависимостей файла |
| `get_directory_context` | Архитектурный обзор директории |
| `find_cycles_for_file` | Циклические зависимости для файла |
| `get_layers` | Определённые архитектурные слои |
| `get_architecture_violations` | Нарушения архитектурных границ |

**Анализ кода:**

| Инструмент | Описание |
|---|---|
| `get_evolutionary_risk` | Корреляция возраст + сложность + churn |
| `get_authorship_metadata` | Основные авторы файла (git blame) |
| `find_similar_functions` | AST-fingerprinting: дубли функций |
| `identify_orphans` | Файлы, не импортируемые никем |
| `predict_change_impact` | Blast radius конкретного символа |
| `simulate_edit` | Dry-run изменения с AST-валидацией |

**Агентские утилиты:**

| Инструмент | Описание |
|---|---|
| `optimize_context_for_claude` | Минимальный набор файлов для конкретной задачи |
| `store_memory` | Сохранить архитектурное решение в памяти проекта |
| `get_memories` | Получить сохранённые решения |
| `list_plugins` | Список загруженных плагинов |
| `request_architecture_review` | Формальная проверка архитектурных правил |
| `get_semantic_slice` | Извлечь конкретную функцию/класс из файла |
| `suggest_split_strategy` | План рефакторинга God File |

### Конфигурация MCP в Claude Desktop (`mcp-setup`)

```bash
codepulse mcp setup
```

Записывает конфигурацию MCP-сервера в конфиги поддерживаемых агентов (Claude Desktop, Cursor и др.).

---

## 25. GitHub Actions

### Использование

```yaml
- name: CodePulse Review
  uses: archpulse/codepulse-cli@v5
  with:
    command: review          # review | verify | audit | <любая команда>
    dir: .
    github_token: ${{ secrets.GITHUB_TOKEN }}
    fail_on_critical: true
```

### Входные параметры

| Параметр | По умолчанию | Описание |
|---|---|---|
| `command` | `review` | Команда: `review`, `verify`, `audit` или любая другая |
| `dir` | `.` | Директория проекта |
| `github_token` | `${{ github.token }}` | Токен для PR-комментариев |
| `fail_on_critical` | `true` | Завершить с кодом 1 при критических ошибках |

### Пример: полный CI-пайплайн

```yaml
name: CodePulse CI
on: [pull_request]

jobs:
  architecture-review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0    # нужна git-история для coupling/time-machine

      - name: CodePulse Review
        uses: archpulse/codepulse-cli@v5
        with:
          command: review
          github_token: ${{ secrets.GITHUB_TOKEN }}

      - name: CodePulse Verify
        uses: archpulse/codepulse-cli@v5
        with:
          command: verify

      - name: PR Risk Assessment
        run: |
          git diff --name-only HEAD^ HEAD | npx @archpulse/codepulse pr-risk --threshold 70
```

---

## 26. Плагины

CodePulse поддерживает систему плагинов для расширения правил анализа.

### Расположение

```
plugins/             # в корне проекта
~/.codepulse/plugins # глобальные плагины
```

### Структура плагина

```typescript
export default {
  name: "my-plugin",
  version: "1.0.0",
  description: "Custom architectural rules",
  author: "Your Name",
  category: "rules",
  rules: [
    {
      id: "no-direct-db-import",
      check: (file, result) => {
        // логика проверки
        return []; // Issue[]
      }
    }
  ]
};
```

### Команда просмотра плагинов

```bash
codepulse plugins list          # список в терминале
codepulse plugins list --json   # JSON-вывод
```

---

## 27. Интернационализация (i18n)

CodePulse поддерживает 7 языков интерфейса.

### Поддерживаемые языки

| Код | Язык | Формат времени |
|---|---|---|
| `en` | English | 12-часовой (AM/PM) |
| `ru` | Русский | 24-часовой |
| `ua` | Українська | 24-часовой |
| `de` | Deutsch | 24-часовой |
| `fr` | Français | 24-часовой |
| `ko` | 한국어 | 12-часовой |
| `cs` | Čeština | 24-часовой |

### Смена языка

```bash
codepulse lang ru    # переключить на русский
codepulse lang en    # вернуть английский
```

Настройка сохраняется в `~/.gemini/tmp/codepulse-cli/settings.json`.

### Переводы README

В директории `translations/` хранятся README на каждом языке:
- `README.ru.md`, `README.ua.md`, `README.de.md`
- `README.fr.md`, `README.ko.md`, `README.cs.md`

---

## 28. Webhook-алерты

При падении Health Score ниже порога CodePulse отправляет алерты.

### Конфигурация (`.codepulse.json`)

```json
{
  "alerts": {
    "slack": "$CODEPULSE_SLACK_WEBHOOK",
    "discord": "$CODEPULSE_DISCORD_WEBHOOK",
    "telegram": {
      "token": "$TELEGRAM_BOT_TOKEN",
      "chatId": "-1001234567890"
    },
    "threshold": 80,
    "branches": ["main", "master"]
  }
}
```

### Логика срабатывания

1. Алерт отправляется только если `Health Score < threshold`
2. Алерт отправляется только если текущая ветка входит в `branches`
3. Placeholder-URL (вида `XXXXXXXX`) автоматически пропускаются

### Содержание алерта

- Название проекта
- Git-ветка, хэш коммита, автор, сообщение коммита
- Health Score / порог
- Количество God Files, Circular Deps, Critical Nodes, Dead Exports, Hotspots

---

## 29. Статусы выхода (Exit Codes)

| Код | Условие |
|---|---|
| `0` | Успешное завершение |
| `1` | Критические ошибки найдены (при `--fail-on error` / `--strict`) |
| `1` | PR Risk Score превышает порог |
| `1` | Health Score упал больше чем на `--threshold` (команда `diff`) |
| `1` | Верификация провалилась (`verify`) |
| `1` | Директория не найдена |

---

## 30. Быстрая шпаргалка

```bash
# Основной анализ
codepulse scan .
codepulse scan . --json --fail-on error

# Мониторинг реального времени
codepulse watch .

# Git-сравнение
codepulse diff main --threshold 5

# История метрик
codepulse time-machine . --strategy interval --interval weekly
codepulse health-trend .

# Визуализация
codepulse heatmap .
codepulse coupling .

# Глубокий аудит
codepulse audit .

# CI/CD
codepulse review . --github
codepulse verify .
git diff --name-only HEAD | codepulse pr-risk --threshold 60

# Анализ конкретного файла
codepulse ghost src/analyzer/index.ts

# AI-агенты
codepulse agent claude default
codepulse mcp

# Профайлинг
codepulse profile cpu.cpuprofile --dir .

# Утилиты
codepulse license mit "John Doe"
codepulse install-deps
codepulse detect-reward-hacking .
codepulse synth .
codepulse explain god-file
codepulse lang ru
```