docs: P1-A done, and the three things the estimate had wrong

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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-14 20:19:28 +07:00
1 parent ce833c3475
commit fc897ef569
5 files changed
+127 -28

No files matched your search

+13 -1
View File
@@ -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
+1 -1
View File
@@ -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). |
+58 -4
View File
@@ -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-<T>.snap`
plus every schema that embeds it.
**both** `schema_for!` and `SCHEMA_TYPES`, `cargo run -p xtask -- bindings`, and bless a new
`golden__schema-<T>.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<T>` wrapper.
8. `ui/src/test/ipc.ts` — the mock.
+38 -19
View File
@@ -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<x`, then plan `B` latest) | plan shows held-back with correct blocker; Compatible path succeeds; Force path warns and `check` reports breakage |
| Batch with 1 deliberately broken sdist | Phase B isolates it; counts n-1 ok / 1 failed with PD-BLD-*; env passes `check` |
| Uninstall a depended-on package | guard lists dependents; `--force` proceeds |
| Snapshot → mutate → rollback | env freeze equals snapshot |
| PEP 668 marker file planted | PD-ENV-002 block; override path passes flag |
Scenario
Assertion
Fresh venv + install 3 small pure wheels
summary 3/0; `check` clean
Seed known conflict (install `A==old` requiring `B<x`, then plan `B` latest)
plan shows held-back with correct blocker; Compatible path succeeds; Force path warns and `check` reports breakage
Batch with 1 deliberately broken sdist
Phase B isolates it; counts n-1 ok / 1 failed with PD-BLD-*; env passes `check`
Uninstall a depended-on package
guard lists dependents; `--force` proceeds
Snapshot → mutate → rollback
env freeze equals snapshot
PEP 668 marker file planted
PD-ENV-002 block; override path passes flag
Fixture packages are tiny pinned PyPI wheels (documented list in `tests/integration/pins.toml`) so CI is deterministic; network-touching tests are tagged and can run against a local `pypiserver` mirror when offline determinism is needed.
@@ -53,4 +72,4 @@ Core target ≥ 85 % line coverage (`cargo llvm-cov`), classifiers and plan modu
## 4. Manual test charter (per release)
A short exploratory pass on a real machine: dirty 150+ package env, corporate-proxy simulation (PD-NET-002 copy), non-ASCII Windows username paths, VI locale sweep of all mutation dialogs, cancel mid-Phase-B, and SmartScreen/first-run installer experience.
A short exploratory pass on a real machine: dirty 150+ package env, corporate-proxy simulation (PD-NET-002 copy), non-ASCII Windows username paths, VI locale sweep of all mutation dialogs, cancel mid-Phase-B, and SmartScreen/first-run installer experience.
+17 -3
View File
@@ -95,8 +95,20 @@ budget intact. Neither button is a tab stop — the row is (see §8). Multi-sele
`pins::hold_requirements` has no caller and `engine::plan_requirements` restates every package at its
*installed* version — a hold at any other version is a promise nothing keeps, and the CLI cannot
create one either. With no environment selected the screen says so rather than "no pins": pins are
keyed by `env_hash`, so that is not an empty list. (P1) auto-suggest section: "`urllib3` — 12
packages depend on it. Pin?".
keyed by `env_hash`, so that is not an empty list.
**The auto-suggest section** — "`urllib3` — 12 packages depend on it. Pin?" — landed post-1.0 as
P1-A. It sits *above* the pin list, because it is a prompt to act and the list is a record of
having acted, and it is absent entirely when there is nothing to suggest. Accepting writes an
ordinary `Exclude` pin with the count as its reason (PRD P1-2's "suggest pin with reason"), which
the reason field below can then replace.
It costs one `probe.py` run, and that is why it is here rather than on a sidebar badge: only
someone who opened this tab pays for it. It is also **silent on failure** — this screen's job is
listing pins and it does that either way, so an error row about an advisory would be the loudest
thing on it. Counts come from `graph::dependent_count`, which counts in-force edges only: the same
set the uninstall guard warns about, because a user pinning on one rule and being warned on another
is the failure worth designing against.
**Snapshots** (surfaced under Environments → env detail): timeline of snapshots with trigger label, diff viewer (added/removed/changed in mono), `Rollback…` with its own preview per DATA-FLOW §8.
@@ -121,7 +133,9 @@ the snapshot's side.
**Health.** Project-folder picker (persisted per env) → run panel with three result tabs (deptry / vulture / ruff) per CODE-HEALTH-SPEC; `Fix with ruff` gated behind explicit confirm listing file count.
**Settings.** Engine (pip/uv radio + detected versions), locale (EN/VI), thresholds (pin auto-suggest count, snapshot retention), index refresh, PEP 668 override (off by default, scary copy), *Open logs folder*.
**Settings.** Engine (pip/uv radio + detected versions), locale (EN/VI), **pin auto-suggest count** (P1-A; zero turns suggestions off), snapshot retention, index refresh, PEP 668 override (off by default, scary copy), *Open logs folder*.
The threshold is the app's **first numeric input**, and it sets the rule for the next one: reject at the boundary, never store junk. `<input type="number">` 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.