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:
1 parent
ce833c3475
commit
fc897ef569
5 files changed
+127
-28
No files matched your search
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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.
|
||||
|
||||
|
||||
Reference in new issue
Block a user