# 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` |

### Cockpit Terminal (вбудований термінал)

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

**Доступні команди в Cockpit:**

```
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 dive deep 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=...          # токен з правами на коментарі
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 ua    # перемикнути на українську
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 ua
```