From 7341feb84d4f0051ff2978a2712d0df3b2ca059d Mon Sep 17 00:00:00 2001 From: "Anaz S. Aji" Date: Thu, 11 Jun 2026 07:54:31 +0700 Subject: [PATCH] docs: sync debt tracker (#206) across all docs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #252 and #253 merged tech debt metrics but docs were not updated. Changes: - CHANGELOG.md + docs/changelog.md: added debt tracker to [0.5.0] Added - docs/roadmap.md: #206 Planned → Done - README.md: added 'cora debt' to commands table - docs/cli-reference.md: added cora debt subcommand with all flags - docs/configuration.md: added Tech Debt Tracker section (config + CLI) - AGENT.md: test count 453→485, added debt_tracker.rs + debt.rs to structure - .agent.md: test count 453→485 --- .agent.md | 2 +- AGENT.md | 8 +++++--- CHANGELOG.md | 6 ++++++ README.md | 1 + docs/changelog.md | 6 ++++++ docs/cli-reference.md | 5 +++++ docs/configuration.md | 26 ++++++++++++++++++++++++++ docs/roadmap.md | 2 +- 8 files changed, 51 insertions(+), 5 deletions(-) diff --git a/.agent.md b/.agent.md index 116898da..1251ce8a 100644 --- a/.agent.md +++ b/.agent.md @@ -8,7 +8,7 @@ Before creating any release PR, verify ALL of the following are updated: - [ ] `Cargo.toml` — version bump - [ ] All target issues merged to `develop` -- [ ] `cargo test` — all 453+ tests pass +- [ ] `cargo test` — all 485+ tests pass - [ ] `cargo clippy --all-targets -- -D warnings` — clean - [ ] `cargo fmt --all -- --check` — clean - [ ] `cargo build --release` — no errors diff --git a/AGENT.md b/AGENT.md index e861b50d..72566137 100644 --- a/AGENT.md +++ b/AGENT.md @@ -17,7 +17,7 @@ no managed API, no cloud service. Runs locally against diffs, scans, or branches ```bash cargo build # Build (debug) cargo build --release # Build (release) -cargo test # Run all 453 tests +cargo test # Run all 485 tests cargo clippy --all-targets -- -D warnings # Lint (strict) cargo fmt --all -- --check # Format check ``` @@ -39,6 +39,7 @@ src/ │ ├── init.rs # cora init (project scaffolding) │ ├── upload.rs # cora upload (review upload) │ ├── completion.rs # Shell completion generation +│ ├── debt.rs # cora debt (tech debt report) │ └── providers.rs # cora providers (list providers) ├── config/ │ ├── mod.rs @@ -58,6 +59,7 @@ src/ │ ├── security_scanner.rs # Static security pattern matching │ ├── language_analyzer.rs # Language-specific review guidance │ ├── secrets_scanner.rs # Secret/credential detection +│ ├── debt_tracker.rs # Tech debt metrics + history snapshots │ └── rules/ # Custom rule engine │ ├── mod.rs │ ├── builtin.rs # Built-in rules @@ -96,8 +98,8 @@ src/ ## Testing ```bash -cargo test # 453 tests total - # 431 unit tests +cargo test # 485 tests total + # 463 unit tests # 16 CLI integration tests # 6 config tests cargo test --no-verify # Skip pre-commit hooks (avoids timeout in hooks) diff --git a/CHANGELOG.md b/CHANGELOG.md index d99703a1..b4658545 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -37,6 +37,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Auto-chunking** — large diffs split into reviewable chunks automatically (#188) - `--no-auto-chunk` flag to disable - `src/engine/chunker.rs` module (~310 lines) +- **Tech debt metrics** — cumulative review history and trend tracking (#206) + - `DebtSnapshot` per-review JSON snapshots with quality score (0-10) + - `cora debt` subcommand — terminal table, `--json`, `--trend` ASCII graph, `--since`, `--branch` filters + - Auto-save after every review (best-effort, never fails review) + - `debt:` config section in `.cora.yaml` (history_dir, retention_days) + - 32 unit tests - **Multi-platform CI docs** — Gitea/Forgejo, GitLab CI, Bitbucket Pipelines workflow examples (#225) - **GitHub Marketplace action** — published as [`codecoradev/cora-review-action@v1`](https://github.com/marketplace/actions/cora-ai-code-review) - **Improved review prompt** — better consistency, lower false-negative rate, explicit error handling focus area diff --git a/README.md b/README.md index 372157a7..25d25b91 100644 --- a/README.md +++ b/README.md @@ -137,6 +137,7 @@ Works on **all CI platforms** — [Gitea, GitLab, Bitbucket →](https://codecor | `cora auth login` | Save API key | | `cora config show` | Show resolved config | | `cora providers` | List available LLM providers | +| `cora debt` | Show tech debt report from review history | | `cora mcp` | Start MCP server for AI coding agents | | `cora hook install` | Install pre-commit hook | diff --git a/docs/changelog.md b/docs/changelog.md index d99703a1..b4658545 100644 --- a/docs/changelog.md +++ b/docs/changelog.md @@ -37,6 +37,12 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - **Auto-chunking** — large diffs split into reviewable chunks automatically (#188) - `--no-auto-chunk` flag to disable - `src/engine/chunker.rs` module (~310 lines) +- **Tech debt metrics** — cumulative review history and trend tracking (#206) + - `DebtSnapshot` per-review JSON snapshots with quality score (0-10) + - `cora debt` subcommand — terminal table, `--json`, `--trend` ASCII graph, `--since`, `--branch` filters + - Auto-save after every review (best-effort, never fails review) + - `debt:` config section in `.cora.yaml` (history_dir, retention_days) + - 32 unit tests - **Multi-platform CI docs** — Gitea/Forgejo, GitLab CI, Bitbucket Pipelines workflow examples (#225) - **GitHub Marketplace action** — published as [`codecoradev/cora-review-action@v1`](https://github.com/marketplace/actions/cora-ai-code-review) - **Improved review prompt** — better consistency, lower false-negative rate, explicit error handling focus area diff --git a/docs/cli-reference.md b/docs/cli-reference.md index 61b49771..690e25de 100644 --- a/docs/cli-reference.md +++ b/docs/cli-reference.md @@ -47,6 +47,11 @@ Complete command reference for the cora CLI. | `cora upload-sarif` `` | Upload SARIF to GitHub Code Scanning | | `cora completion` `` | Generate shell completions (bash/zsh/fish) | | `cora mcp` | Start MCP server for AI coding agents (Claude Code, Cursor, Windsurf) | +| `cora debt` | Show tech debt report from review history | +| `cora debt --json` | Debt report in JSON format | +| `cora debt --trend` | Quality score trend graph | +| `cora debt --since ` | Filter by date or git tag | +| `cora debt --branch ` | Filter by branch name | ## Quick Examples diff --git a/docs/configuration.md b/docs/configuration.md index fd636b03..c01957c7 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -307,6 +307,32 @@ rules: Rules run during the deterministic pre-scan phase (no LLM needed). +## Tech Debt Tracker + +cora tracks review history and calculates tech debt metrics over time. + +### Config + +```yaml +debt: + enabled: true # default: true + history_dir: .cora/history # snapshot storage + retention_days: 90 # auto-cleanup old snapshots +``` + +### CLI + +```bash +cora debt # Show debt report table +cora debt --json # Machine-readable JSON output +cora debt --trend # ASCII quality score graph +cora debt --since 2026-06-01 # Filter by date +cora debt --since v0.4.5 # Filter by git tag +cora debt --branch develop # Filter by branch +``` + +Snapshots are auto-saved after every review (best-effort, never fails the review). + ## MCP Server cora includes a built-in MCP (Model Context Protocol) server that exposes rules and config to AI coding agents like Claude Code, Cursor, Copilot, and Windsurf. diff --git a/docs/roadmap.md b/docs/roadmap.md index aeabe139..72e5dafc 100644 --- a/docs/roadmap.md +++ b/docs/roadmap.md @@ -71,7 +71,7 @@ Demand-gated — we build what people actually need. Track progress on [GitHub I - [#207](https://github.com/codecoradev/cora-cli/issues/207) MCP server — expose rules to AI agents — ✓ Done - [#238](https://github.com/codecoradev/cora-cli/issues/238) Quality profiles bug fix — path resolution, fail-fast, dedup — ✓ Done - [#188](https://github.com/codecoradev/cora-cli/issues/188) Auto-chunking for large diffs — ✓ Done -- [#206](https://github.com/codecoradev/cora-cli/issues/206) Tech debt metrics — review history — ◎ Planned +- [#206](https://github.com/codecoradev/cora-cli/issues/206) Tech debt metrics — review history — ✓ Done ## v0.6 — Growth & Marketplace