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:
1 parent
39a0c54f05
commit
3152c55eaa
4 files changed
+35
-9
No files matched your search
@@ -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)
|
||||
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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. |
|
||||
|
||||
@@ -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:?}"
|
||||
);
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user