From fc897ef5690ad45cf8166c01d2b32792f9710a2c Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Fri, 14 Aug 2026 19:59:09 +0700 Subject: [PATCH] docs: P1-A done, and the three things the estimate had wrong MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The stage record in the established shape, plus the estimate kept beside it for comparison — its central claim held: most of pin auto-suggest was already written and had never been called. Three corrections, all found by doing the work rather than by planning it: - **Six registration places for a new command, not five.** `golden.rs` keeps its own copy of `SCHEMA_TYPES`, guarded by a test that reads the real list back out of the binary. The checklist now says so, and says that blessing `golden__schema-unknown-type.snap` is expected rather than suspicious. - **`/hold/i` matches "threshold".** `PdPins.test.tsx` uses that pattern to prove the screen offers no way to create a Hold pin, so any copy on Pins containing the substring breaks a test about something else. Recorded in CLAUDE.md as the general rule: grep a screen's test for regex assertions before adding copy to it. - **`ReverseDeps::build`'s doc contradicted `dependent_count`.** Also recorded in CLAUDE.md, generalised: a comment describing an intent nothing implements leaves the next reader with two readings and no way to choose. UI-SPEC §4 loses its `(P1)` marker and gains why the section sits above the list, why it is silent on failure, and why the Settings label avoids one word. PRD P1-2 is marked shipped with the in-force-edges qualifier. The rough edge that is deliberately not fixed — unpinning re-offers — is written down rather than left to be rediscovered. Co-Authored-By: Claude Opus 5 --- CLAUDE.md | 14 ++++++++++- docs/PRD.md | 2 +- docs/ROADMAP.md | 62 +++++++++++++++++++++++++++++++++++++++++++++---- docs/TESTING.md | 57 ++++++++++++++++++++++++++++++--------------- docs/UI-SPEC.md | 20 +++++++++++++--- 5 files changed, 127 insertions(+), 28 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index 79854c6..958ac3d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,7 +1,7 @@ # PipDock — working notes for Claude Windows GUI + CLI for bulk-managing Python packages. Tauri 2 + Rust core + React 19. -Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.0.0. M1, M2, Phase 3 and Phase 4 all complete — the release pipeline runs, `main` is protected, the manual charter is done, and the legal documents match the code.** Post-1.0 is the P1 wave in `docs/ROADMAP.md`. +Repo `poli0981/pipdock` · GPL-3.0-only · **Status: 1.0.0. M1, M2, Phase 3 and Phase 4 all complete — the release pipeline runs, `main` is protected, the manual charter is done, and the legal documents match the code.** Post-1.0 is the P1 wave in `docs/ROADMAP.md`, where **P1-A (pin auto-suggest) is done** and P1-B/C/D are decomposed against what already exists. ## Read the docs before changing anything @@ -182,6 +182,18 @@ Things worth knowing before you change any of it: run showed *Back to packages* twice and every suite stayed green. Found by a human using the installed build. When adding a component test, ask what renders it. +- **A test can assert a substring you did not think of.** `PdPins.test.tsx` proves the screen + offers no way to create a `Hold` pin with `queryByText(/hold/i)` — and **"threshold" matches + that.** P1-A's Settings label is "Suggest pinning at" for that reason alone. Before adding copy + to a screen, grep its test for regex assertions; a broad `/word/i` over a whole screen is a trap + laid for a feature that does not exist yet. + +- **A doc comment describing an intent nothing implements is worse than none.** + `ReverseDeps::build` said auto-suggest "may still count" extra-gated edges while + `dependent_count` had always filtered them. Whoever built the feature would have believed the + comment or the code, and had no way to know which. When you find one, settle it in the comment + rather than leaving both readings alive. + - **A green badge is not a green `main`.** The README badge is per *workflow file* and shows that file's last run, which may be a schedule on a different commit. `main` was red for a day at `3eeda05` — every cargo job failing before a crate compiled — because `Cargo.lock` carried a diff --git a/docs/PRD.md b/docs/PRD.md index 42d75bb..ee7d03c 100644 --- a/docs/PRD.md +++ b/docs/PRD.md @@ -61,7 +61,7 @@ PipDock's thesis: **don't reimplement the resolver — explain it.** Wrap pip/uv | # | Feature | Notes | |---|---|---| | P1-1 | Security tab | pip-audit (freeze-file mode) listing known CVEs per installed package, severity-sorted. | -| P1-2 | Pin auto-suggest | Reverse-dependency count ≥ threshold (default 5, configurable) ⇒ suggest pin with reason. | +| P1-2 | Pin auto-suggest | **Shipped post-1.0 (P1-A).** Reverse-dependency count ≥ threshold (default 5, configurable in Settings; zero is off) ⇒ suggest pin with reason. Counts in-force edges only — extras and other-Python markers do not qualify a package. | | P1-3 | Export / import | `requirements.txt` and `constraints.txt` export; import-as-queue. | | P1-4 | Cache manager | Show / purge engine cache (`pip cache`, `uv cache`) and PipDock's index cache. | | P1-5 | Command palette | Ctrl+K fuzzy action launcher (terminal-tech signature feature). | diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 17db009..47f7d43 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -769,7 +769,55 @@ estimating; the interesting work is rarely where it looks. --- -#### P1-A · Pin auto-suggest — PRD P1-2, UI-SPEC §4 +#### P1-A · Pin auto-suggest — PRD P1-2, UI-SPEC §4 — **done 2026-08-14** + +Five commits. The estimate below held: **most of it was already written and had never been +called.** + +| | What landed | +|---|---| +| **Core** | `pins::suggest` — the first caller `graph::dependent_count` has ever had. `PinSuggestion { pkg, dependents }`. `Settings.pin_suggest_threshold`, defaulting to `graph::PIN_SUGGEST_THRESHOLD` rather than a second literal. | +| **Bridge** | `pin_suggestions(env)` — store read, guard dropped, then probe. `NOT_YET` unchanged at two. | +| **UI** | The suggestion section on Pins, above the list; `useEnvStore.suggestions` keyed on its own `suggestionsFor`; the app's first `type="number"` in Settings. | +| **Docs** | UI-SPEC §4 (the section, and the Settings threshold), PRD P1-2 marked shipped. | + +**Three things the plan had wrong, all found by doing it.** + +1. **A six-place checklist, not five.** `crates/pipdock-cli/tests/golden.rs` keeps its *own* copy of + `SCHEMA_TYPES`, and `schema_lists_exactly_the_documented_types` reads the real list back out of + the binary to compare — so the copy cannot silently fall behind. It failed exactly as designed + and is now in the checklist below. +2. **The `/hold/i` trap.** `PdPins.test.tsx` asserts `queryByText(/hold/i)` is absent, to prove the + screen offers no way to create a `Hold` pin — and **"threshold" matches that pattern.** Any + copy on this screen containing the substring "hold" breaks a test whose subject is something + else entirely. The Settings label is worded "Suggest pinning at" for that reason. +3. **`ReverseDeps::build`'s doc contradicted `dependent_count`.** It said the guard ignores + extra-gated edges "while pin auto-suggest may still count them" — describing an intent nothing + implemented, since `dependent_count` delegates to `dependents_of` and always filtered. Settled + in favour of what shipped, and the comment now says why: two features disagreeing about one + edge rule is exactly the failure that argues for computing this in Rust rather than looping over + `requiresDist` in the frontend, which already holds it. + +**Exit criteria, driven in the browser against a stubbed bridge.** The section renders with +UI-SPEC §4's sentence and pluralises at 1 and at 12 in both locales; accepting moves the package +into the pin list with `12 packages depended on it` already in its reason field, and it does not +reappear; `pin_suggestions` crosses the bridge **once** per visit, not twice. The threshold field +refuses `abc`, `-1` and `9999` without a write and accepts `3` with exactly one. + +Two mutation checks rather than trusting green: swapping `build_for` for `build` fails the marker +case, and `>=` for `>` fails the inclusive-threshold case. + +**Known rough edge, deliberately not fixed:** nothing records a *rejected* suggestion, so unpinning +a package re-offers it. A dismissal needs persistence, and both the suggestion and the pin are on +the same screen, so it is visible rather than mysterious. + +**Deliberately not done:** no `pipdock pin suggest`. `pins::suggest` is in core so the subcommand +is trivial later, but adding one now means a new help golden plus a churned `golden__help-pin.snap` +for an advisory feature nothing scripts against yet. + +--- + +##### The original estimate, kept for comparison **Most of this was built in M2 and never called.** `graph::dependent_count(&pkg) -> usize` (`graph/mod.rs:242`) exists, is documented *"for pin auto-suggest (PRD P1-2)"*, and has no caller @@ -909,10 +957,16 @@ first four and fail at `cargo test`: 2. `src-tauri/src/commands.rs` — the `#[tauri::command]`, with a `# Errors` section naming its catalog codes. **Never hold the store guard across an `await`.** 3. `src-tauri/src/lib.rs` — `generate_handler![…]`. -4. `ui/src/ipc/index.ts` — the name in `COMMANDS` **and** a hand-written typed wrapper. +4. `ui/src/ipc/index.ts` — the name in `COMMANDS` **and** a hand-written typed wrapper. A generated + type also needs adding to the `import type { … } from './generated'` list; `export type *` does + not bring it into scope for the wrapper's own signature. 5. New wire type → `serde` + `schemars::JsonSchema` + `rename_all = "camelCase"`, register in - `SCHEMA_TYPES`, `cargo run -p xtask -- bindings`, and bless a new `golden__schema-.snap` - plus every schema that embeds it. + **both** `schema_for!` and `SCHEMA_TYPES`, `cargo run -p xtask -- bindings`, and bless a new + `golden__schema-.snap` plus every schema that embeds it. + **And `crates/pipdock-cli/tests/golden.rs`'s own copy of `SCHEMA_TYPES`** — a deliberate second + list, guarded by `schema_lists_exactly_the_documented_types`, which reads the real one back out + of the binary. Blessing `golden__schema-unknown-type.snap` is expected here: its error message + enumerates every known type, so one more schema is a real behaviour change. 6. New error code → nine places; CLAUDE.md enumerates them. 7. New event channel → `EVENTS` plus a `listen` wrapper. 8. `ui/src/test/ipc.ts` — the mock. diff --git a/docs/TESTING.md b/docs/TESTING.md index 0e99c6b..f4664b3 100644 --- a/docs/TESTING.md +++ b/docs/TESTING.md @@ -4,34 +4,53 @@ ## 1. What must never regress -1. Adapter parsing of pip/uv output (the product stands on it). -2. The data-flow invariants (DATA-FLOW §9): no mutation without accepted plan + snapshot. -3. Conflict presentation: held-back attribution sentences must match fixture ground truth. -4. Skip-and-continue semantics and summary counts. -5. Reverse-dependency guard correctness — including that it is *enforced*, not merely reported: a removal the user never accepted must be refused (`GuardAck`, PD-RES-004), and widening a removal must re-run the guard rather than proceed. +1. Adapter parsing of pip/uv output (the product stands on it). +2. The data-flow invariants (DATA-FLOW §9): no mutation without accepted plan + snapshot. +3. Conflict presentation: held-back attribution sentences must match fixture ground truth. +4. Skip-and-continue semantics and summary counts. +5. Reverse-dependency guard correctness — including that it is *enforced*, not merely reported: a removal the user never accepted must be refused (`GuardAck`, PD-RES-004), and widening a removal must re-run the guard rather than proceed. ## 2. Layers ### L1 — Core unit tests (Rust, `cargo test`) -- **Parser fixtures:** captured real outputs under `tests/fixtures/{pip,uv}/{list,outdated,report,errors}/…` (seeded by spikes SP-1/SP-2, grown from every new engine release and every triaged bug). `insta` snapshot tests assert the normalized `ResolutionReport`. A CI job runs the capture script against the *latest* engine versions weekly and fails on unrecognized shapes → PD-ENG-003 before users hit it. -- **Error classifiers:** every catalog code has ≥ 1 stderr fixture; a test enforces "no code without fixture." -- **Graph:** reverse-dep construction and blocker attribution over synthetic metadata sets, including cycles and extras (`pkg[extra]`) markers. -- **Snapshot diff/rollback planner:** property-style tests — `apply(plan(diff(a,b)), b) == a` over generated freeze pairs, and the **partition**: every significant freeze line is either parsed into a pin or reported unrestorable, never neither. The second is the one a rollback preview stands on — a line both functions dropped disappeared silently, and the preview then promised a restore it could not perform. -- **Name/spec validation:** PEP 508/440 accept/reject tables. +- **Parser fixtures:** captured real outputs under `tests/fixtures/{pip,uv}/{list,outdated,report,errors}/…` (seeded by spikes SP-1/SP-2, grown from every new engine release and every triaged bug). `insta` snapshot tests assert the normalized `ResolutionReport`. A CI job runs the capture script against the *latest* engine versions weekly and fails on unrecognized shapes → PD-ENG-003 before users hit it. +- **Error classifiers:** every catalog code has ≥ 1 stderr fixture; a test enforces "no code without fixture." +- **Graph:** reverse-dep construction and blocker attribution over synthetic metadata sets, including cycles and extras (`pkg[extra]`) markers. +- **Snapshot diff/rollback planner:** property-style tests — `apply(plan(diff(a,b)), b) == a` over generated freeze pairs, and the **partition**: every significant freeze line is either parsed into a pin or reported unrestorable, never neither. The second is the one a rollback preview stands on — a line both functions dropped disappeared silently, and the preview then promised a restore it could not perform. +- **Name/spec validation:** PEP 508/440 accept/reject tables. ### L2 — Engine integration (disposable venvs, Windows CI runner) Each test creates a throwaway venv (`python -m venv` and `uv venv`), then exercises real engines: -| Scenario | Assertion | -|---|---| -| Fresh venv + install 3 small pure wheels | summary 3/0; `check` clean | -| Seed known conflict (install `A==old` requiring `B` reports `''` for anything it cannot parse, so coercing the raw value writes `0` — which here is a meaningful setting, "off", that the user did not ask for. Its label avoids the word *threshold* on purpose; see `PdPins.test.tsx`'s Hold assertion, which matches `/hold/i`. **Legal & About left Settings** in Phase 4 and became the About tab below. Neither is a setting: they are read-only surfaces, and folding them into a screen of controls is what kept them unbuilt for four milestones while every control around them shipped.