fix(docs): three things main was carrying, and the gate that missed one

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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-21 08:35:15 +07:00
1 parent 39a0c54f05
commit 3152c55eaa
4 files changed
+35 -9

No files matched your search

+11 -7
View File
@@ -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)
+1 -1
View File
@@ -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();
+1 -1
View File
@@ -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. |
+22
View File
@@ -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:?}"
);
}
}