From 3152c55eaa3717fb395bfd9e27de70ff8894ae0e Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Thu, 20 Aug 2026 19:55:13 +0700 Subject: [PATCH] fix(docs): three things main was carrying, and the gate that missed one MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Found while surveying P1-6. None is caught by any suite, which is the common thread rather than a coincidence. `docs/ARCHITECTURE.md`'s `audit_run` row was the only row in the §7 command table missing its trailing pipe, so the table rendered wrong from 1.2.0. Every gate passed: the command is registered, declared and documented, and `documented()` strips only the *leading* pipe, so the row parsed correctly and nothing looked at its shape. A spec sentence is not a test — and neither is a spec table. The new `the_architecture_table_is_well_formed` asserts the shape as well as the contents, and was mutation-checked against the row it was written for. `catalog.rs`'s comment read "Rust has 33; docs tabulates 30" three lines above `assert_eq!(Code::ALL.len(), 34)`. Both numbers were one behind; the doc tabulates 31, folding PD-HLT-001..004 into one row. CLAUDE.md's error-code checklist named three schemas embedding `Code` while saying "four", and 1.2.0 made it genuinely four by adding `AuditReport` via `ToolProblem.code` — five snapshot files in all. So anyone adding a code today would leave `golden__schema-AuditReport.snap` stale. The line now says to grep `PD-ENV-001` across the snapshots rather than trust the list, because that is how the omission was found. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 18 +++++++++++------- crates/pipdock-core/src/errors/catalog.rs | 2 +- docs/ARCHITECTURE.md | 2 +- src-tauri/src/lib.rs | 22 ++++++++++++++++++++++ 4 files changed, 35 insertions(+), 9 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index dc671fe..57d825e 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -14,13 +14,17 @@ The design is fully specified. Read in this order; do not invent behaviour that 5. `docs/CLI-SPEC.md` — commands, flags, exit codes, JSON contracts 6. `docs/ERROR-CATALOG.md` — the launch codes and their stderr classifiers. **34 in Rust** (`Code::ALL`, pinned by two tests); the doc tabulates fewer rows because it folds - `PD-HLT-001..004` into one. Adding a code means the catalog, `Code::ALL`, both counts, the - "no code without a fixture" gate in `classifier_corpus.rs`, **both `locales/*/errors.json`**, - a regenerated `codes.json` (`cargo run -p xtask -- ipc-fixtures`), regenerated bindings, and - re-blessed goldens — `golden__schema-Code.snap` **and every schema that embeds it**, which - since P3 is **four**: `StepResult`, `ExecutionSummary` and `HealthReport`, the last via - `ToolProblem.code`. Nine places; the gates will tell you which you forgot, including - `i18n.test.ts`, which fails on a code with no copy in either language + `PD-HLT-001..004` into one, so it shows **31 rows**. Adding a code means the catalog, + `Code::ALL`, both counts, the "no code without a fixture" gate in `classifier_corpus.rs`, + **both `locales/*/errors.json`**, a regenerated `codes.json` + (`cargo run -p xtask -- ipc-fixtures`), regenerated bindings, and re-blessed goldens — + `golden__schema-Code.snap` **and every schema that embeds it**, which since 1.2.0 is + **four**: `StepResult`, `ExecutionSummary`, `HealthReport` and `AuditReport`, the last two + via `ToolProblem.code`. **Five snapshot files in all.** This line named three while saying + four, and stayed that way through 1.2.0 — grep `PD-ENV-001` across + `crates/pipdock-cli/tests/snapshots/` rather than trusting the list. Nine places; the + gates will tell you which you forgot, including `i18n.test.ts`, which fails on a code with + no copy in either language 7. `docs/CODE-HEALTH-SPEC.md`, `docs/SECURITY.md`, `docs/TESTING.md`, `docs/RELEASE-CI.md`, `docs/I18N.md`, `docs/ROADMAP.md` 8. `legal/` — EULA, Disclaimer, Privacy, Third-Party Notices (public; the in-app legal gate links to these GitHub URLs) diff --git a/crates/pipdock-core/src/errors/catalog.rs b/crates/pipdock-core/src/errors/catalog.rs index a702fd2..84cdb7f 100644 --- a/crates/pipdock-core/src/errors/catalog.rs +++ b/crates/pipdock-core/src/errors/catalog.rs @@ -739,7 +739,7 @@ mod tests { #[test] fn every_documented_code_has_exactly_one_variant() { - // Rust has 33; docs/ERROR-CATALOG.md tabulates 30, because it folds PD-HLT-001..004 into + // Rust has 34; docs/ERROR-CATALOG.md tabulates 31, because it folds PD-HLT-001..004 into // one row. Pin the number so the next person adding a code has to notice the docs exist. assert_eq!(Code::ALL.len(), 34); let wire: HashSet<&str> = Code::ALL.iter().map(|c| c.as_str()).collect(); diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index bed70b0..7c33244 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -142,7 +142,7 @@ This table is the surface. A command that is not listed here does not exist; add | `health_fix` | `FixReport` | Apply the gated `ruff` fix (P5). **Not `ExecutionSummary`** — there is no plan, no phase and no per-package counts in a fix, and inventing them would be four lies for one operation. Same correction §7 needed for `pip_upgrade`. | | `health_dirty` | `number \| null` | Uncommitted entries in the parked report's project, so the fix confirm can name one. `null` means no repository, no git, or git failed — a courtesy, not a precondition. Asked again inside `health_fix`: this decides what to render, that decides what to allow. | | `health_save_report` | `string[]` | Write a finished report as Markdown **and** JSON beside a user-chosen path, returning both. Rust-side rather than a filesystem capability: `dialog:allow-save` lets the webview ask for a path and nothing more. | -| `audit_run` | `AuditReport` | pip-audit over an environment (PRD P1-1). Takes the freeze itself, because pip is invoked with `--all` and uv is not, so the configured engine changes what is audited. Syncs its **own** venv on first use — a `msgpack` wheel gap fails this and leaves Code Health working. pip-audit failing is not an error: it lands in `problems` and the report still returns. +| `audit_run` | `AuditReport` | pip-audit over an environment (PRD P1-1). Takes the freeze itself, because pip is invoked with `--all` and uv is not, so the configured engine changes what is audited. Syncs its **own** venv on first use — a `msgpack` wheel gap fails this and leaves Code Health working. pip-audit failing is not an error: it lands in `problems` and the report still returns. | | `audit_cancel` | `bool` | Stop a running audit, reporting whether there was one. Exists where `health_run` has no equivalent because an audit is **18-68 s** rather than 1.3 s, dominated by a one-off advisory-database fetch. A cancel is a *state* on the report, never `PD-INT-001`. | | `audit_save_report` | `string[]` | Write a finished audit as Markdown **and** JSON beside a user-chosen path, returning both. `health_save_report`'s shape, for its reasons: `dialog:allow-save` asks for a path and grants no `fs`, and the report comes from the frontend because what the user asked to save is what is on their screen. | | `engine_info` | `EngineInfo[]` | Detected version and availability per engine. Settings shows both, so this returns both. | diff --git a/src-tauri/src/lib.rs b/src-tauri/src/lib.rs index 84624cc..6ce4d26 100644 --- a/src-tauri/src/lib.rs +++ b/src-tauri/src/lib.rs @@ -251,4 +251,26 @@ mod tests { "NOT_YET lists commands that exist: {stale:?}" ); } + + #[test] + fn the_architecture_table_is_well_formed() { + // [`documented`] strips only the *leading* pipe, so a row missing its trailing one + // parses fine and renders wrong. `audit_run` shipped that way in 1.2.0 and no gate + // could see it: the command was registered, declared and documented, and the only + // thing broken was the markdown. Assert the shape as well as the contents. + let src = include_str!("../../docs/ARCHITECTURE.md"); + let start = src + .find("| Command | Returns | Purpose |") + .expect("ARCHITECTURE §7's command table exists"); + let ragged: Vec<&str> = src[start..] + .lines() + .skip(2) + .take_while(|l| l.starts_with("| `")) + .filter(|l| !l.trim_end().ends_with('|')) + .collect(); + assert!( + ragged.is_empty(), + "ARCHITECTURE §7 rows missing a trailing pipe: {ragged:?}" + ); + } }