# CodePulse CLI — Kompletní dokumentace (Část 1/3)

> Verze: **5.2.0** | Balíček: `@archpulse/codepulse` | Licence: MIT | Node.js ≥ 16

---

## Obsah

- [Část 1](#): Přehled, technologie, architektura, instalace, konfigurace, `scan`
- [Část 2](#): `watch`, `diff`, `time-machine`, `health-trend`, `heatmap`, `coupling`, `audit`
- [Část 3](#): `profile`, `ghost`, `synth`, `verify`, `pr-risk`, `review`, `agent`, `license`, `detect-reward-hacking`, MCP Server, GitHub Actions, pluginy, i18n

---

## 1. Co je CodePulse

**CodePulse** je CLI nástroj pro hlubokou statickou a strukturální analýzu kódu navržený pro velké projekty v JS/TS a Pythonu. Jeho filozofií je **"Engineering Honesty"** (Inženýrská upřímnost): nástroj bez obalu ukazuje architektonické problémy bez jejich skrývání.

### Klíčové vlastnosti

- Sestavuje **graf závislostí** celého projektu pomocí AST analýzy.
- Detekuje **God Files** (monolitické soubory), **Critical Nodes** (kritické uzly) a **cyklické závislosti**.
- Vypočítává **Health Score** (skóre zdraví, 0–100) jako agregovanou metriku kondice kódové základny.
- Identifikuje **hotspots** — soubory s vysokou složitostí A vysokou frekvencí změn.
- Analyzuje **Temporal Coupling** (časovou provázanost) na základě historie Git.
- Spouští **externí lintery** (ESLint, Oxlint, Ruff, Cppcheck, ShellCheck, GolangCI-Lint a další).
- Poskytuje integrovaný **MCP Server** pro AI agenty (Claude, Cursor, Cline, Gemini, Copilot atd.).
- Podporuje **stroj času** (Time Machine) pro analýzu evoluce metrik v historii Git.
- Generuje **HTML reporty**, **SARIF soubory** a **SVG odznaky (badges)**.
- Odesílá **webhook upozornění** do Slacku, Discordu nebo Telegramu při degradaci Health Score.
- Funguje jako nativní **GitHub Action** pro integraci do CI/CD.

---

## 2. Technologický stack

| Kategorie | Technologie | Účel |
|---|---|---|
| Jazyk | TypeScript 6.0 | Celá kódová základna CLI |
| Sestavení | `tsc` | Kompilace do `dist/` |
| CLI framework | Commander.js 14 | Zpracování příkazů a přepínačů |
| AST (JS/TS) | `@babel/parser` + `@babel/traverse` | Analýza JS/TS souborů |
| AST (pokročilý) | `ts-morph` 28 | Hluboká analýza TypeScriptu |
| TUI Dashboard | `blessed` + `blessed-contrib` | Terminálové rozhraní (`watch`, `heatmap`) |
| Pseudoshell | `node-pty` | Integrovaný terminál uvnitř `watch` |
| Sledování souborů | `chokidar` 5 | Reaktivní sledování změn v reálném čase |
| Spinnery | `ora` | Indikátory průběhu v CLI |
| Barvy | `chalk` 4 | Formátování barevného výstupu |
| Šablony | `handlebars` | Generování HTML reportů |
| Glob | `glob` 13 | Vyhledávání souborů podle vzorů |
| GitHub API | `@octokit/rest` + `@actions/core` | Integrace s GitHub Actions a PR komentáře |
| MCP | `@modelcontextprotocol/sdk` | MCP server pro integraci s AI agenty |
| Testování | `vitest` 4 | Unit testy |

---

## 3. Architektura projektu

```
codepulse-cli/
├── src/
│   ├── index.ts                    # Vstupní bod CLI
│   ├── explain.ts                  # Databáze znalostí o architektonických konceptech
│   ├── mcp-setup.ts                # Nastavení MCP (konfigurační soubory pro agenty)
│   ├── mcp-paths.ts                # Cesty ke konfiguračním souborům MCP
│   │
│   ├── cli/commands/               # Registrace příkazů CLI (Commander.js)
│   │   ├── advanced-commands.ts    # coupling, pr-risk, explain, time-machine, profile, plugins
│   │   └── ...
│   │
│   ├── commands/                   # Implementace jednotlivých příkazů
│   │   ├── scan.ts          (412 řádků)  # codepulse scan
│   │   ├── watch.ts        (1868 řádků)  # codepulse watch — TUI dashboard (God File)
│   │   ├── diff.ts          (435 řádků)  # codepulse diff
│   │   ├── time-machine.ts  (197 řádků)  # codepulse time-machine
│   │   ├── health-trend.ts  (369 řádků)  # codepulse health-trend
│   │   ├── heatmap.ts       (247 řádků)  # codepulse heatmap
│   │   ├── coupling.ts       (60 řádků)  # codepulse coupling
│   │   ├── audit.ts          (98 řádků)  # codepulse audit
│   │   ├── profile.ts       (174 řádků)  # codepulse profile
│   │   ├── ghost.ts          (65 řádků)  # codepulse ghost
│   │   ├── review.ts        (117 řádků)  # codepulse review
│   │   ├── synth.ts          (80 řádků)  # codepulse synth
│   │   ├── verify.ts        (218 řádků)  # codepulse verify
│   │   ├── pr-risk.ts       (195 řádků)  # codepulse pr-risk
│   │   ├── reward-hacking.ts(131 řádků)  # codepulse detect-reward-hacking
│   │   ├── agent.ts         (342 řádků)  # codepulse agent
│   │   ├── license.ts       (204 řádků)  # codepulse license
│   │   ├── badge.ts                      # Generování SVG odznaku
│   │   ├── install-deps.ts  (398 řádků)  # Automatická instalace linterů
│   │   └── output.ts                     # Formátování statistik
│   │
│   ├── analyzer/                   # Analytické jádro
│   │   ├── index.ts                # Hlavní funkce analyze()
│   │   ├── scanner.ts              # Vyhledávání souborů (glob)
│   │   ├── ast.ts                  # Zpracování AST JS/TS přes Babel
│   │   ├── graph.ts                # Graf závislostí, centrality, kritické uzly
│   │   ├── git.ts                  # Git metriky: churn, temporal coupling
│   │   ├── workers.ts              # Worker thready pro paralelní analýzu
│   │   ├── cache.ts                # Vyrovnávací paměť (zlib komprese)
│   │   ├── python.ts               # Analýza souborů v Pythonu
│   │   ├── rust.ts                 # Analýza souborů v Rustu
│   │   ├── generic.ts              # Analýza ostatních jazyků
│   │   ├── ast-fingerprint.ts      # Detekce duplicit pomocí otisků AST
│   │   ├── architecture.ts         # Kontrola architektonických vrstev
│   │   ├── context.ts              # Načítání souboru .codepulse.json
│   │   ├── zlib.ts                 # Kompresní nástroje
│   │   └── time-machine/
│   │       ├── engine.ts           # Engine pro analýzu historie Git
│   │       ├── cache.ts            # Vyrovnávací paměť historických snímků (.codepulse-cache/snapshots/)
│   │       ├── sampling.ts         # Strategie vzorkování commitů
│   │       └── git-diff.ts         # Diffy mezi commity
│   │
│   ├── rules/                      # Pravidla a lintery
│   │   ├── index.ts                # Orchestrátor (spouští všechna pravidla)
│   │   ├── security.ts             # Detekce zranitelností (založená na regexu)
│   │   ├── fastLinter.ts           # Rychlý vestavěný linter
│   │   ├── agents/registry.ts      # Registr AI agentů + hlavní instrukce CodePulse
│   │   └── linters/                # Adaptéry pro externí lintery
│   │       ├── 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
│   │   ├── server.ts               # Spuštění MCP (stdio transport)
│   │   ├── 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 schémata nástrojů MCP
│   │
│   ├── reporter/
│   │   ├── html.ts                 # Generování HTML reportů
│   │   ├── sarif.ts                # Generování SARIF souborů
│   │   ├── health.ts               # Výpočet Health Score
│   │   └── stats.ts                # Agregace statistik
│   │
│   ├── utils/
│   │   ├── i18n.ts                 # Lokalizace (7 jazyků)
│   │   ├── webhooks.ts             # Integrace upozornění: Slack, Discord, Telegram
│   │   ├── plugins.ts              # Načítání pluginů
│   │   └── terminal.ts             # Podpora speciálních znaků v terminálu (UTF-8 / ASCII fallback)
│   │
│   └── locales/                    # Lokalizační soubory (JSON)
│       └── en.json, ru.json, ua.json, de.json, fr.json, ko.json, cs.json
│
├── plugins/                        # Adresář pro uživatelské pluginy
├── rules/                          # Uživatelská pravidla
├── translations/                   # Lokalizované verze README
├── action.yml                      # GitHub Action
└── .codepulse.json                 # Konfigurace projektu
```

---

## 4. Instalace

### Globálně pomocí npm

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

### Pomocí npx (bez permanentní instalace)

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

### Ze zdrojového kódu

```bash
git clone https://github.com/archpulse/codepulse-cli.git
cd codepulse-cli
npm install
npm run build
npm link   # vytvoří globální symlink 'codepulse'
```

### Požadavky na systém

- **Node.js ≥ 16.0.0**
- Git (vyžadován pro analýzu historie, coupling a time-machine)
- Volitelné: `oxlint`, `ruff`, `cppcheck`, `shellcheck`, `golangci-lint` (CodePulse je dokáže automaticky nainstalovat pomocí příkazu `install-deps`)

---

## 5. Konfigurace `.codepulse.json`

Soubor `.codepulse.json` v kořenovém adresáři projektu řídí chování celého analyzátoru.

### Kompletní schéma s komentáři

```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"]
      }
    ]
  }
}
```

### Parametry

| Parametr | Typ | Výchozí hodnota | Popis |
|---|---|---|---|
| `exclude` | `string[]` | `[]` | Adresáře nebo glob vzory vyloučené z analýzy |
| `rootDir` | `string` | `"."` | Kořenový adresář pro skenování |
| `godFileLines` | `number` | `500` | Limit řádků, při jehož překročení je soubor označen jako God File |
| `godFileImports` | `number` | `20` | Limit importů, při jehož překročení je soubor označen jako God File |
| `criticalNodeThreshold` | `number` | `15` | Limit centrality, při jehož překročení je uzel označen jako kritický |
| `alerts.slack` | `string` | — | URL pro Slack Incoming Webhook |
| `alerts.discord` | `string` | — | URL pro Discord Webhook |
| `alerts.telegram.token` | `string` | — | Token Telegram bota |
| `alerts.telegram.chatId` | `string` | — | Chat ID pro Telegram kanál/chat |
| `alerts.threshold` | `number` | `80` | Upozornění se odešle, pokud Health Score klesne pod tuto hodnotu |
| `alerts.branches` | `string[]` | `["main","master"]` | Větve, pro které jsou webhook upozornění aktivní |
| `architecture.layers` | `Layer[]` | — | Definice architektonických vrstev a povolených vazeb |

> **Proměnné prostředí:** Hodnoty začínající znakem `$` (např. `"$VAR_NAME"`) jsou při načítání konfigurace automaticky nahrazeny odpovídajícími hodnotami z `process.env`.

### Architektonické vrstvy (`architecture.layers`)

Umožňují vynutit hranice mezi jednotlivými moduly projektu. Pokud modul poruší pravidla závislostí, CodePulse zaznamená chybu `architecture-violation`.

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

- `name` — Libovolný název vrstvy
- `pattern` — Glob vzor určující soubory náležící do této vrstvy
- `allowDependenciesFrom` — Seznam vrstev, ze kterých je povoleno do této vrstvy importovat

---

## 6. Příkaz `scan`

Základní příkaz pro spuštění jednorázové kompletní analýzy projektu.

### Syntaxe

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

### Co `scan` dělá (krok za krokem)

1. Ověří existenci cílového adresáře.
2. Automaticky nainstaluje chybějící lintery (`runInstallDepsForProject`).
3. Zvolí engine pro lintování: ESLint / Oxlint / auto.
4. Spustí `analyze()` — jádro systému (AST, graf, Git metriky, lintery, bezpečnostní pravidla).
5. Vygeneruje interaktivní HTML report do `.codepulse-report/index.html`.
6. Vypočítá Health Score a vygeneruje SVG odznak `.codepulse-report/badge.svg`.
7. Volitelně vygeneruje report ve formátu SARIF.
8. Pokud je skóre pod limitem, odešle webhook upozornění do Slacku, Discordu nebo Telegramu.
9. Vypíše přehledné shrnutí výsledků do terminálu.

### Všechny přepínače (Flags)

| Přepínač | Popis |
|---|---|
| `--json` | Vypíše výsledky ve formátu JSON na stdout (skryje standardní UI výstup) |
| `--sarif` | Generuje SARIF report pro integraci s GitHub Code Scanning |
| `--open` | Po dokončení analýzy automaticky otevře HTML report v prohlížeči |
| `--strict` | Striktní režim: varování typu `dead-export` a `god-file` jsou povýšena na `error` |
| `--debug` | Zobrazí pouze systémové chyby analyzátoru (skryje chyby linterů) |
| `--ld` | Pouze diagnostika linterů (debug režim linterů) |
| `--focus <type>` | Filtruje výsledky podle typu problému |
| `--severity <level>` | Filtruje podle závažnosti: `error`, `warning`, `info` |
| `--group-by <field>` | Seskupí výstup podle: `file`, `type`, `severity` |
| `--max-issues <n>` | Zobrazí maximálně N problémů |
| `--ignore-warnings` / `-iw` | Skryje všechna varování (warnings) |
| `--fail-on <severity>` | Ukončí proces s návratovým kódem 1 při nálezu chyb dané závažnosti |
| `--precision` / `--eslint` | Vynutí použití ESLint engine (přesnější, ale pomalejší) |
| `--engine oxlint` | Vynutí použití Oxlint engine (extrémně rychlý) |

### Zkratky (Shortcuts)

| Zkratka | Ekvivalent |
|---|---|
| `-ld` | `--ld` |
| `-iw` | `--ignore-warnings` |
| `-diw` | `--debug --ignore-warnings` |
| `-ldiw` | `--ld --ignore-warnings` |

### Typy problémů (`--focus`)

| Typ | Popis |
|---|---|
| `dead-export` | Nepoužívaný exportovaný symbol |
| `god-file` | Příliš velký soubor (God File) |
| `critical-node` | Kritický uzel s vysokou centralitou v grafu |
| `circular-dependency` | Cyklická závislost mezi moduly |
| `vulnerability` | Známý bezpečnostní vzor / zranitelnost |
| `architecture-violation` | Porušení pravidel architektonických vrstev |
| `linter` | Chyba nalezená externím linterem |
| `high-complexity` | Vysoká cyklomatická složitost |
| `duplication` | Duplicitní kód (AST fingerprinting) |

### Příklady použití

```bash
# Základní sken aktuálního adresáře
codepulse scan .

# Výstup v JSON pro zpracování v CI/CD
codepulse scan . --json

# Zobrazit pouze fatální chyby
codepulse scan . --severity error

# Striktní režim a ukončení chybou při jakémkoliv erroru
codepulse scan . --strict --fail-on error

# Zaměřeno na detekci nepoužívaného kódu
codepulse scan . --focus dead-export

# Seskupení výsledků podle souborů
codepulse scan . --group-by file

# Generování SARIF souboru pro GitHub Security tab
codepulse scan . --sarif

# Precizní analýza pomocí ESLint
codepulse scan . --precision

# Otevření HTML reportu po dokončení
codepulse scan . --open

# Zobrazit maximálně 10 nejzávažnějších chyb
codepulse scan . --severity error --max-issues 10
```

### Ukázka výstupu v terminálu

```
  ◆ 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)
```

### Jak se počítá Health Score

| Faktor | Penalizace |
|---|---|
| God File | −10 bodů za soubor |
| Cyklická závislost | −8 bodů za cyklus |
| Critical Node | −5 bodů za uzel |
| Zranitelnost | −7 bodů za incident |
| Dead Export | −1 bod za symbol |
| Architektonické porušení | −6 bodů za incident |
| Hotspot | −2 body za soubor |

Výsledné rozmezí: **0–100**. Barevná indikace: 🟢 ≥ 90 / 🟡 ≥ 70 / 🔴 < 70.

---

# CodePulse CLI — Kompletní dokumentace (Část 2/3)

## 7. Příkaz `watch`

Reaktivní, interaktivní TUI (Terminal User Interface) dashboard. Sleduje soubory v reálném čase a přepočítává metriky při každém uložení.

### Syntaxe

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

### Co `watch` dělá

1. Inicializuje celoobrazovkové terminálové rozhraní (pomocí Blessed).
2. Spustí úvodní kompletní analýzu projektu.
3. Nastaví sledování souborů pomocí `chokidar` (s debounce intervalem 700 ms).
4. Při každé změně na pozadí spustí rychlou analýzu a překreslí panely dashboardu.
5. Volitelně odesílá webhook upozornění, pokud dojde k poklesu skóre.

### Panely na dashboardu

| Panel | Pozice | Popis |
|---|---|---|
| **Health Gauge** | Horní řádek, plná šířka | Vizuální ukazatel Health Score (0–100 %) |
| **Cockpit Terminal** | Vlevo nahoře | Integrovaný emulátor terminálu pro spouštění příkazů |
| **Telemetry** | Vpravo nahoře | Klíčové číselné ukazatele (Score, Files, Lines, Errors atd.) |
| **Complexity Chart** | Vlevo uprostřed | Graf vývoje průměrné cyklomatické složitosti (posledních 10 skenů) |
| **Hotspots Table** | Vpravo uprostřed | Přehled pěti nejrizikovějších souborů (hotspots) |
| **Hazard Log** | Vlevo dole | Tabulka všech nalezených chyb a varování v kódu |
| **Warp Log** | Vpravo dole | Systémový log (aktivity Git, webhooky, události souborového systému) |
| **Heatmap** (skrytý) | Pod viditelnou oblastí | Interaktivní riziková mapa projektu (lze zapnout přes Add Mode) |
| **Coupling** (skrytý) | Pod viditelnou oblastí | Analýza časové provázanosti (lze zapnout přes Add Mode) |
| **MCP Box** (skrytý) | Pod viditelnou oblastí | Informace a stav integrovaného MCP serveru (lze zapnout) |
| **Clock Bar** | Spodní řádek | Aktuální čas a nápověda ke klávesovým zkratkám |

### Klávesové zkratky ovládání

| Klávesa | Akce |
|---|---|
| `Tab` | Cyklické přepínání zaměření (focusu) mezi panely |
| `1`–`9` | Rychlé zaměření konkrétního panelu podle čísla |
| `Esc` | Zrušení zaměření panelu (vstup do režimu volného pohybu / scrollu) |
| `c` | Sbalení / rozbalení aktivního panelu |
| `+` / `-` | Zvětšení / zmenšení výšky vybraného panelu |
| `[` / `]` | Zmenšení / zvětšení šířky vybraného panelu |
| `a` | Otevření **Add Mode** (přidání skrytých panelů nebo nových oken) |
| `s` | Otevření **Swap Mode** (prohození pozic dvou panelů) |
| `x` | Zavření (skrytí) vybraného panelu |
| `Alt + ↑` / `Alt + ↓` | Vertikální posun celé plochy viewportu (styl Niri) |
| `Ctrl+C` | Ukončení režimu sledování |

### Cockpit Terminal

Levý horní panel obsahuje integrovaný terminál, ze kterého můžete přímo spouštět diagnostické příkazy CodePulse, aniž byste opustili dashboard. Stiskněte `Tab` pro aktivaci, napište příkaz a stiskněte `Enter`.

**Dostupné příkazy v konzoli 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
```

Výstup příkazu se zobrazuje přímo v panelu (historie až 120 řádků), ANSI barvy a speciální znaky jsou automaticky vyčištěny pro lepší čitelnost.

### Podporované typy souborů pro sledování

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

### Automaticky ignorované vzory (Ignored Patterns)

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

### Add Mode (`a`)

Po stisknutí klávesy `a` (stavový řádek zežloutne):
- Stiskněte číslo `1`–`9` pro obnovení dříve zavřeného panelu.
- Stiskněte `t` pro vytvoření nového **bash panelu** (skutečný shell využívající `node-pty`).
- Stiskněte `h` pro zobrazení nápovědy k dostupným panelům.
- Stiskněte `Esc` pro zrušení režimu přidávání.

### Swap Mode (`s`)

Umožňuje snadno prohodit pozice dvou panelů na obrazovce. Vyberte panel, stiskněte `s` a následně zadejte číslo panelu, se kterým ho chcete prohodit.

---

## 8. Příkaz `diff`

Porovnává strukturální a architektonické zdraví aktuální větve s cílovou větví.

### Syntaxe

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

### Co `diff` dělá

1. Uloží si název aktuální pracovní větve.
2. Provede analýzu aktuálního stavu (`analyze()`).
3. Pokud existují neuložené změny, bezpečně je uschová pomocí `git stash`.
4. Přepne se na cílovou větev (`git checkout <branch>`) a analyzuje ji.
5. Přepne se zpět na původní větev a obnoví neuložené změny (`git stash pop`).
6. Vygeneruje porovnávací report rozdílů.

### Porovnávané metriky

| Metrika | Popis |
|---|---|
| **Health Score** | Celkový rozdíl skóre (aktuální vs. cílové) |
| **God Files** | Nově vytvořené nebo odstraněné monolitické soubory |
| **Circular Dependencies** | Nově vzniklé nebo vyřešené cykly |
| **Issues** | Přírůstek / úbytek chyb (Errors) a varování (Warnings) |
| **Critical Nodes** | Změny v počtu kritických uzlů v grafu závislostí |

### Přepínače (Flags)

| Přepínač | Popis |
|---|---|
| `--json` | Výstup reportu ve formátu JSON |
| `--threshold <n>` | Ukončí proces s chybou 1, pokud Health Score klesne o více než N bodů |

### Příklady použití

```bash
# Porovnání s hlavní větví main
codepulse diff main

# Porovnat a selhat v CI, pokud zdraví kleslo o více než 5 bodů
codepulse diff main --threshold 5

# Výstup ve formátu JSON
codepulse diff develop --json
```

---

## 9. Příkaz `time-machine`

Analyzuje historii závislostí a evoluci architektury projektu v čase.

### Syntaxe

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

### Co `time-machine` dělá

1. Projde historii Git podle zvolené strategie vzorkování commitů.
2. U každého vybraného bodu provede checkout, spustí analýzu a uloží stav.
3. Využívá inteligentní caching snímků (`.codepulse-cache/snapshots/`) — commity, které již byly jednou analyzovány, se znovu nezpracovávají.
4. Zobrazí přehledné statistiky a trendy vývoje architektury projektu.

### Strategie vzorkování (`--strategy`)

| Strategie | Přepínač | Popis |
|---|---|---|
| `max-points` | `--strategy max-points --commits 30` | Vybere rovnoměrně N bodů z celé historie (výchozí) |
| `every-nth` | `--strategy every-nth --commits 10` | Analyzuje každý N-tý commit v historii |
| `interval` | `--strategy interval --interval weekly` | Vzorkování podle času: `daily` (denně), `weekly` (týdně), `monthly` (měsíčně) |
| `tag-only` | `--strategy tag-only` | Analyzuje pouze commity označené tagem (vhodné pro verze/releasy) |

### Přepínače (Flags)

| Přepínač | Popis |
|---|---|
| `--commits <n>` | Celkový počet bodů k analýze (výchozí: 30) |
| `--strategy <type>` | Zvolená strategie vzorkování |
| `--interval <period>` | Časový interval pro strategii `interval` |
| `--since <date>` | Analyzovat pouze commity vytvořené po zadaném datu (`2024-01-01`) |
| `--json` | Výstup historických dat v JSON formátu |

### Příklady použití

```bash
# Rychlá analýza 30 rovnoměrných bodů historie projektu
codepulse time-machine .

# Analýza historie za poslední půlrok na týdenní bázi
codepulse time-machine . --strategy interval --interval weekly --since 2024-01-01

# Analýza vývoje pouze u hlavních vydaných verzí (tags)
codepulse time-machine . --strategy tag-only
```

---

## 10. Příkaz `health-trend`

Vykreslí textové grafy vývoje kvality a složitosti kódu na základě dat ze Stroje času.

### Syntaxe

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

### Co `health-trend` dělá

1. Načte historické snímky ze složky `.codepulse-cache/snapshots/`.
2. Pokud data chybí, automaticky na pozadí spustí rychlou analýzu `time-machine` pro 15 bodů.
3. Vykreslí textové grafy (Unicode sparklines) vývoje klíčových ukazatelů.
4. Vyhodnotí celkový trend (Zlepšuje se / Zhoršuje se / Stabilní), určí nejlepší/nejhorší commity a náhlé nárůsty složitosti.

### Ukázka výstupu v terminálu

```
  ══════════════════════════════════════════════════════════════
  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%
```

---

## 11. Příkaz `heatmap`

Spustí interaktivní rizikovou mapu všech souborů v terminálu (TUI).

### Syntaxe

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

### Výpočet rizikového faktoru (Risk Score)

Pro každý soubor v projektu se vypočítává index rizika podle následujícího vzorce:

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

- **Complexity:** Cyklomatická složitost kódu v souboru.
- **Churn:** Počet změn (commitů) souboru v historii Git.
- **Centrality:** Míra provázanosti a důležitosti souboru v grafu závislostí.

### Barevné rozdělení rizikovosti

| Úroveň | Rozsah indexu | Barva |
|---|---|---|
| Nízké riziko (Low) | 0–3 | 🟢 Zelená |
| Střední riziko (Medium) | 3–7 | 🟡 Žlutá |
| Vysoké riziko (High) | 7+ | 🔴 Červená |

---

## 12. Příkaz `coupling`

Detekuje soubory, které vykazují vysokou míru "časové provázanosti" (Temporal Coupling).

### Syntaxe

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

### Co je to Temporal Coupling

Pokud jsou soubory A a B téměř vždy (např. v 80 % případů) upravovány společně v rámci jednoho commitu, vykazují **časovou provázanost**. Jde o skrytou formu závislosti, kterou standardní importy v kódu neodhalí. Často indikuje porušení Single Responsibility Principle (SRP) nebo nevhodný návrh struktury modulů.

### Příklad výstupu

```
    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%
  ...
```

---

## 13. Příkaz `audit`

Provede hlubokou analýzu architektonické integrity a vygeneruje podrobný report `AUDIT.md`.

### Syntaxe

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

### Co `audit` dělá

1. Spustí precizní sken projektu s plnou podporou pravidel linteru.
2. Vypočítá aktuální index zdraví (Health Score).
3. Vygeneruje podrobný soubor `AUDIT.md` v kořenovém adresáři projektu.
4. Zobrazí stručné shrnutí auditu přímo v terminálu.

---

# CodePulse CLI — Kompletní dokumentace (Část 3/3)

## 14. Příkaz `profile`

Propojí data z profileru (V8 CPU / Python cProfile) přímo s AST metrikami kódu a lokalizuje kritická místa.

### Syntaxe

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

### Podporované formáty souborů profilerů

| Koncovka | Formát |
|---|---|
| `.cpuprofile` | V8 CPU Profile (Node.js / Chrome DevTools profiler) |
| `.prof`, `.pstats` | Výstup modulu cProfile z Pythonu |

### Kategorie technického dluhu výkonu

- **active-hotspot:** Vysoká cyklomatická složitost kombinovaná s vysokým časem procesoru.
- **dormant-debt:** Vysoká cyklomatická složitost, ale kód je volán zřídka.
- **io-bound:** Vysoká doba provádění, ale nízká vnitřní složitost (pravděpodobně čekání na diskové I/O nebo síť).

---

## 15. Příkaz `ghost`

Vypočítá architektonický dopad ("Blast Radius") případných změn v daném souboru.

### Syntaxe

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

### Co `ghost` dělá

1. Vyhledá cílový soubor v grafu závislostí.
2. Identifikuje všechny přímé závislosti (kdo soubor importuje).
3. Rekurzivně analyzuje nepřímé závislosti a spočítá celkové procento zasaženého projektu při úpravě tohoto souboru.

---

## 16. Příkaz `synth`

Automaticky vygeneruje plán zátěžového testování a simulace selhání pro kritická místa projektu.

### Syntaxe

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

### Co `synth` dělá

1. Identifikuje 3 nejkritičtější uzly a 3 největší God Files v projektu.
2. Navrhne konkrétní scénáře testování rizik a mockování závislostí.
3. Uloží výsledný plán do souboru `STRESS_TEST_PLAN.md`.

---

## 17. Příkaz `verify`

Komplexní a chytré ověření integrity projektu: typecheck → build → lint → testy.

### Syntaxe

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

### Jak `verify` funguje

Nástroj zjistí použité technologie v projektu, analyzuje změny provedené od posledního commitu přes Git, zjistí, které soubory byly změněny, a pomocí grafu závislostí určí, které testy by mohly být těmito změnami ovlivněny. Spustí pouze tyto ovlivněné testy, což dramaticky urychluje vývojový cyklus.

---

## 18. Příkaz `pr-risk`

Vyhodnotí architektonické riziko a dopad změn navrhovaných v Pull Requestu.

### Syntaxe

```bash
# Předáním seznamu souborů
codepulse pr-risk --files src/a.ts,src/b.ts

# Pomocí přesměrování (pipe z git diff)
git diff --name-only HEAD | codepulse pr-risk
```

### Vzorec pro výpočet rizika souboru v PR

Rizikový faktor (Risk Score) se počítá na škále 0-100 na základě následujících vah:
- **Centrality Score:** Až 30 bodů (význam v grafu).
- **Complexity Score:** Až 25 bodů (složitost kódu).
- **Churn Score:** Až 15 bodů (častost změn v historii).
- **God File penalizace:** +20 bodů.
- **Critical Node penalizace:** +15 bodů.

Pokud PR obsahuje změnu souboru A, ale neobsahuje změnu souboru B, který s ním má silnou časovou provázanost (Temporal Coupling ≥ 70 %), nástroj vypíše důležité varování před možným zapomenutým refaktoringem.

---

## 19. Příkaz `review`

Automatizovaný nástroj pro CI/CD: provede statickou analýzu, vyhodnotí rizika PR a přidá markdown report přímo jako komentář do Pull Requestu na GitHubu.

### Syntaxe

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

### Přepínače (Flags)

| Přepínač | Popis |
|---|---|
| `--github` | Zapne integraci s GitHub API a publikuje komentář do PR |
| `--json` | Výstup reportu v JSON formátu |

---

## 20. Příkaz `agent`

Konfiguruje instrukce a pravidla chování pro vývojové AI agenty a IDE (např. Cursor, Claude Code atd.).

### Syntaxe

```bash
codepulse agent <agent-name> [prompt-name]
codepulse agent config          # Interaktivní TUI správce šablon
codepulse agent prompt config   # Přidání vlastní šablony instrukcí
```

### Podporovaní AI agenti a soubory (23 konfigurací)

Nástroj generuje specifické konfigurační soubory pro integraci (např. `.cursorrules`, `.clinerules`, `CLAUDE.md`, `.antigravityrules` atd.) a integruje do nich pravidla statické analýzy a 5fázový bezpečnostní protokol analýzy projektu.

---

## 21. Příkaz `license`

Vygeneruje soubor open-source licence pro váš projekt.

### Syntaxe

```bash
codepulse license <type> [author-name]
```

Podporované licence: `mit`, `isc`, `bsd-2`, `bsd-3`, `unlicense`, `apache`, `gpl`, `agpl`, `lgpl`, `mpl`.

---

## 22. Příkaz `detect-reward-hacking`

Diagnostikuje a odhaluje pokusy o "Reward Hacking" (podvádění AI při plnění testů/benchmarků) v kódu generovaném umělou inteligencí.

### Syntaxe

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

Nástroj pomocí AST detekuje zašifrované zkratky (hardcoded I/O shortcuts), podezřele velké vyhledávací tabulky imitující složité výpočty (benchmark hacks) a obcházení integračních testů (validation bypasses).

---

## 23. Příkaz `install-deps`

Analyzuje typy souborů v projektu a automaticky nainstaluje externí nativní lintery na základě operačního systému a dostupných balíčkovacích systémů (např. `apt`, `brew`, `pacman`, `npm`).

---

## 24. Model Context Protocol (MCP) Server

CodePulse disponuje plnohodnotným **MCP serverem**, který umožňuje AI asistentům přímou interakci s vaším projektem.

### Spuštění

```bash
codepulse mcp          # Spustí server přes stdio transport
codepulse mcp setup    # Zaregistruje server do konfigurace Claude Desktop / Cursor
```

Poskytuje AI agentům více než 17 specializovaných nástrojů pro detailní přehled o architektuře, složitosti a historii projektu bez nutnosti čtení celého zdrojového kódu.

---

## 25. GitHub Actions

Nativní akce pro automatizaci kontroly kvality v CI/CD pipeline.

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

---

## 26. Systém pluginů

Architektura CodePulse umožňuje snadné rozšiřování o vlastní pravidla statické analýzy. Pluginy se umisťují do složky `plugins/` v kořenu projektu nebo globálně do `~/.codepulse/plugins`.

---

## 27. Lokalizace (i18n)

CodePulse podporuje 7 jazyků rozhraní: angličtinu (`en`), ruštinu (`ru`), ukrajinštinu (`ua`), němčinu (`de`), francouzštinu (`fr`), korejštinu (`ko`) a češtinu (`cs`).

Jazyk lze změnit příkazem:

```bash
codepulse lang cs
```

---

## 28. Upozornění (Webhook Alerts)

Pokud Health Score projektu klesne pod nastavený limit na sledované Git větvi, CodePulse odešle strukturované upozornění se seznamem rizik a chyb do Slacku, Discordu nebo na Telegram.

---

## 29. Návratové kódy (Exit Codes)

- `0` — Analýza proběhla úspěšně, nebyly nalezeny kritické problémy.
- `1` — Byly nalezeny kritické chyby (v režimu `--strict` / `--fail-on error`).
- `1` — Riziko navrhovaných změn v PR překročilo povolený limit.
- `1` — Pokles Health Score v porovnání větví překročil nastavený limit.
- `1` — Ověření projektu v příkazu `verify` selhalo.

---

## 30. Rychlá nápověda (Cheat Sheet)

```bash
# Jednorázový kompletní sken
codepulse scan .

# Spuštění interaktivního monitoringu
codepulse watch .

# Porovnání větví
codepulse diff main --threshold 5

# Vizualizace rizik souborů
codepulse heatmap .

# Hluboký audit a výpis reportu
codepulse audit .

# Nastavení AI pravidel pro Cursor
codepulse agent cursor default
```