From d2993bbd7d710ff28b01c56eb8d60a6dafbe81cd Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Fri, 16 Oct 2026 20:52:57 +0700 Subject: [PATCH] feat(wire)!: the preview carries what it was missing, and stops carrying the engine's output MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A contract change, deliberately in one commit; four schema goldens re-blessed for it (`ResolutionReport`, `FlowStep`, `CheckReport`, `ExecutionSummary`). **`ResolutionReport.raw` leaves the wire.** It was pip's whole `--report` document — every package's README — cloned into each `FlowStep`, serialized over IPC on every round and printed by `--json` (33 KB for two packages, megabytes for "update all"). Nothing in the UI ever read it. It stays in Rust (`#[serde(skip)]`) for the log, and for pip it now holds stderr — pip's warnings — rather than the report the parser already consumed. **New fields, all omitted when empty, so existing JSON reads the same:** - `incompatible: [PythonMismatch]` — pins whose `Requires-Python` excludes this environment (PD-PKG-001), as structured data: the preview shows the required range against the environment's version, which a sentence assembled in Rust could not let it do (invariant 4). Filled by a later commit. - `forced: [HeldBack]` — what "Force latest" will break. Filled by a later commit. - `yanked: [YankWarning]` — **both adapters parsed yank warnings and then dropped them** (`.map(|p| p.report)`), so PD-PKG-003's preview warning has never been shown. `ParsedPlan::into_report` keeps them. **`CheckReport.error`.** A post-execution check that could not run was reported as `ok: true` — "verified" exactly when nothing was, for instance when the run had broken pip itself. It is now `ok: false` with the reason's code; the rows still carry the per-package truth. `CheckReport` therefore embeds `Code`, which makes it the sixth schema that does. **`NothingReason::Cancelled`**, for a resolve the user stopped (wired in a later commit); the CLI maps it to exit 130. Co-Authored-By: Claude Opus 5.5 --- crates/pipdock-cli/src/run.rs | 5 + .../snapshots/golden__schema-CheckReport.snap | 193 +++++++++++++++++- .../golden__schema-ExecutionSummary.snap | 13 +- .../snapshots/golden__schema-FlowStep.snap | 84 +++++++- .../golden__schema-ResolutionReport.snap | 79 ++++++- crates/pipdock-core/src/engine/parse.rs | 32 ++- crates/pipdock-core/src/engine/pip.rs | 3 +- crates/pipdock-core/src/engine/uv.rs | 3 +- crates/pipdock-core/src/fixtures.rs | 4 + crates/pipdock-core/src/flow/mod.rs | 2 + crates/pipdock-core/src/model.rs | 8 +- crates/pipdock-core/src/plan/mod.rs | 77 ++++++- crates/pipdock-core/src/plan/preview.rs | 3 + crates/pipdock-core/tests/execution.rs | 32 +++ crates/pipdock-core/tests/plan_parsers.rs | 17 ++ ui/src/ipc/generated.ts | 61 +++++- ui/src/test/fixtures/flow_step.json | 3 +- 17 files changed, 588 insertions(+), 31 deletions(-) diff --git a/crates/pipdock-cli/src/run.rs b/crates/pipdock-cli/src/run.rs index 0fe10de..9ebc4d6 100644 --- a/crates/pipdock-cli/src/run.rs +++ b/crates/pipdock-cli/src/run.rs @@ -556,6 +556,11 @@ pub async fn plan_and_run(opts: &GlobalOpts, intent: Intent, dry_run: bool) -> R println!("every package was skipped; nothing to do"); Exit::PlanAborted } + // CLI-SPEC §5: a user cancel is 130, and nothing ran. + NothingReason::Cancelled => { + eprintln!("cancelled before anything was planned"); + Exit::Cancelled + } }); } FlowStep::NeedsConfirm { report } | FlowStep::RoundsExhausted { report } => { diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap index a1fd532..29ef3ac 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap @@ -22,6 +22,186 @@ expression: out ], "type": "object" }, + "Code": { + "description": "Every code PipDock can surface at v1 launch.\n\n`docs/TESTING.md` §2 requires at least one captured stderr fixture per variant before ship;\nthe test that enforces \"no code without fixture\" lives beside the classifiers.", + "oneOf": [ + { + "const": "PD-ENV-001", + "description": "Interpreter path missing or not executable — the env was deleted or moved.", + "type": "string" + }, + { + "const": "PD-ENV-002", + "description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.", + "type": "string" + }, + { + "const": "PD-ENV-003", + "description": "`probe.py` exited non-zero or produced unparseable output.", + "type": "string" + }, + { + "const": "PD-ENG-001", + "description": "pip or uv binary not found.", + "type": "string" + }, + { + "const": "PD-ENG-002", + "description": "pip older than 22.2, which predates `--dry-run --report`.", + "type": "string" + }, + { + "const": "PD-ENG-003", + "description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).", + "type": "string" + }, + { + "const": "PD-ENG-004", + "description": "An engine command ran past its watchdog and was stopped.\n\n**Raised by PipDock, never classified from stderr.** Its own code because the alternative\nwas `PD-INT-001`, which is what the shared watchdog reported until 1.4.0: an sdist build\nstill compiling after ten minutes is not \"a PipDock bug\", and in the batch phase that error\naborted the whole run — no summary, no per-package retry.", + "type": "string" + }, + { + "const": "PD-ENG-999", + "description": "Fallback for engine failures no classifier matched. Always last.", + "type": "string" + }, + { + "const": "PD-RES-001", + "description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.", + "type": "string" + }, + { + "const": "PD-RES-002", + "description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.", + "type": "string" + }, + { + "const": "PD-RES-003", + "description": "A plan is already resolving or executing in this session.\n\nThe GUI drives one resumable flow across several IPC calls, so \"start a plan\" and \"run the\nplan\" are different messages arriving at different times — nothing structurally stops a\nsecond one arriving in between. Refusing is the only safe answer: two concurrent plans\nwould interleave engine commands against one environment, and DATA-FLOW §9.3's staleness\ncheck would be comparing against a set the other plan is busy changing.", + "type": "string" + }, + { + "const": "PD-RES-004", + "description": "A removal was asked for that the reverse-dependency guard refused (DATA-FLOW §5).\n\nIts own code rather than a reused one. The CLI printed `PD-PKG-002` here, which means \"no\nmatching distribution\" — the opposite of the truth: every package involved exists, and\nthat is precisely why the removal is being refused. A user grepping their logs for a typo\nwould have found this instead.\n\nNot raised when the guard merely *finds* dependents. That is a report the caller shows and\nthe user answers; the code appears only when execution is attempted anyway without the\nuser having accepted the breakage.", + "type": "string" + }, + { + "const": "PD-BLD-001", + "description": "MSVC build tools required but absent.", + "type": "string" + }, + { + "const": "PD-BLD-002", + "description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).", + "type": "string" + }, + { + "const": "PD-BLD-003", + "description": "Generic sdist wheel-build failure.", + "type": "string" + }, + { + "const": "PD-PKG-001", + "description": "No matching distribution, and metadata shows a requires-python mismatch.", + "type": "string" + }, + { + "const": "PD-PKG-002", + "description": "No matching distribution: name or version typo, or the release is gone.", + "type": "string" + }, + { + "const": "PD-PKG-003", + "description": "The requested release was yanked.", + "type": "string" + }, + { + "const": "PD-PKG-004", + "description": "Downloaded artifact failed hash verification.", + "type": "string" + }, + { + "const": "PD-NET-001", + "description": "Timeout, connection aborted, or DNS failure.", + "type": "string" + }, + { + "const": "PD-NET-002", + "description": "TLS/SSL verification failed — typically proxy or AV interception.", + "type": "string" + }, + { + "const": "PD-NET-010", + "description": "PEP 691 index refresh failed; the stale index stays searchable.", + "type": "string" + }, + { + "const": "PD-NET-011", + "description": "Code Health tools-venv bootstrap could not reach PyPI.", + "type": "string" + }, + { + "const": "PD-PRM-001", + "description": "`PermissionError` writing site-packages (admin-owned Python).", + "type": "string" + }, + { + "const": "PD-PRM-002", + "description": "File locked by a running process (`WinError 32`).", + "type": "string" + }, + { + "const": "PD-PRM-003", + "description": "A source file in the user's project cannot be written.\n\n**Not `PD-PRM-001`.** That one is scoped to site-packages and its catalogued action is\n\"use a venv\", which is nonsense advice for a read-only `util.py` — the same class of wrong\nanswer P3 removed when a corrupted `ruff.exe` reported `PD-ENG-001`, \"install the engine\".\n\nRaised by PipDock **before anything is written**, never classified from stderr: ruff can\nfail to write a file and still exit 1, which `is_findings_exit` accepts as a clean run, so\na stderr-matched code would arrive after a fix had already reported success.", + "type": "string" + }, + { + "const": "PD-SNP-001", + "description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**", + "type": "string" + }, + { + "const": "PD-SNP-002", + "description": "A release needed to restore a snapshot is no longer available on PyPI.", + "type": "string" + }, + { + "const": "PD-SYS-001", + "description": "`MAX_PATH` exceeded without the long-path opt-in.", + "type": "string" + }, + { + "const": "PD-SYS-002", + "description": "Disk full.", + "type": "string" + }, + { + "const": "PD-HLT-001", + "description": "A Code Health tool is missing from the tools venv.", + "type": "string" + }, + { + "const": "PD-HLT-002", + "description": "A Code Health tool exited non-zero.", + "type": "string" + }, + { + "const": "PD-HLT-003", + "description": "A Code Health tool exceeded its watchdog timeout; partial report shown.", + "type": "string" + }, + { + "const": "PD-HLT-004", + "description": "`python -m venv` failed while building the tools environment.\n\n**Raised by PipDock, not classified from engine stderr.** Its own code rather than a reused\none: `PD-NET-011` is `Area::Net`, so `run::exit_for` would map a broken interpreter to exit\n6 and a script retrying on network failure would loop forever; `PD-HLT-001` tells the user\nto re-sync, which is the operation that just failed; and a Python built without `venv` is\nnot `PD-INT-001`'s \"a PipDock bug\".", + "type": "string" + }, + { + "const": "PD-INT-001", + "description": "A PipDock bug: panic or unexpected state.", + "type": "string" + } + ] + }, "PkgName": { "description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.", "type": "string" @@ -30,6 +210,17 @@ expression: out "$schema": "https://json-schema.org/draft/2020-12/schema", "description": "Post-execution environment verification.", "properties": { + "error": { + "anyOf": [ + { + "$ref": "#/$defs/Code" + }, + { + "type": "null" + } + ], + "description": "Set when the check could not run at all, with the reason's code; `ok` is false then.\n\nA check that could not run used to be reported as `ok: true` — \"verified\" in exactly the\ncase where nothing was verified, such as a pip broken by the run it was meant to check." + }, "findings": { "default": [], "description": "Details when `ok` is false.", @@ -39,7 +230,7 @@ expression: out "type": "array" }, "ok": { - "description": "True when the engine reported no broken requirements.", + "description": "True when the check **ran** and the engine reported no broken requirements.", "type": "boolean" } }, diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap index 14a827c..6eb7335 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap @@ -25,6 +25,17 @@ expression: out "CheckReport": { "description": "Post-execution environment verification.", "properties": { + "error": { + "anyOf": [ + { + "$ref": "#/$defs/Code" + }, + { + "type": "null" + } + ], + "description": "Set when the check could not run at all, with the reason's code; `ok` is false then.\n\nA check that could not run used to be reported as `ok: true` — \"verified\" in exactly the\ncase where nothing was verified, such as a pip broken by the run it was meant to check." + }, "findings": { "default": [], "description": "Details when `ok` is false.", @@ -34,7 +45,7 @@ expression: out "type": "array" }, "ok": { - "description": "True when the engine reported no broken requirements.", + "description": "True when the check **ran** and the engine reported no broken requirements.", "type": "boolean" } }, diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-FlowStep.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-FlowStep.snap index a28fb93..7e94a05 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-FlowStep.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-FlowStep.snap @@ -158,6 +158,11 @@ expression: out "const": "everything-skipped", "description": "Every candidate was skipped while resolving conflicts, so no plan remains.", "type": "string" + }, + { + "const": "cancelled", + "description": "The user stopped the resolve before it finished. Nothing was planned, nothing ran.", + "type": "string" } ] }, @@ -165,6 +170,34 @@ expression: out "description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.", "type": "string" }, + "PythonMismatch": { + "description": "A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`).\n\nHard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree:\npip refuses such a pin with the same \"No matching distribution\" it uses for a typo, and uv\nignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows\nthe required range against the environment's version, and a catalog cannot un-join a string.", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The package." + }, + "python": { + "description": "The environment's Python, e.g. `\"3.12.4\"`.", + "type": "string" + }, + "requiresPython": { + "description": "That release's `Requires-Python`, verbatim.", + "type": "string" + }, + "version": { + "$ref": "#/$defs/Version", + "description": "The version that was asked for or planned." + } + }, + "required": [ + "pkg", + "version", + "requiresPython", + "python" + ], + "type": "object" + }, "ResolutionReport": { "description": "The normalized dry-run result.\n\n**Both adapters must emit this same shape** — that is the whole point of the `Engine` trait\n(ARCHITECTURE §3). The pip adapter fills it from `--dry-run --report` JSON; the uv adapter from\nuv's text plan output.\n\nThe exact field set is **provisional until spike SP-1** confirms uv's output is rich enough to\npopulate `held_back.blockers`. If it is not, SP-1's go/no-go says v1.0 ships pip-primary with uv\nbehind a beta flag.", "properties": { @@ -176,6 +209,13 @@ expression: out }, "type": "array" }, + "forced": { + "description": "Packages the user chose to **force** past what installed dependents allow, each with what\nit will break — the \"Will break\" section of the preview (DISCLAIMER §2).", + "items": { + "$ref": "#/$defs/HeldBack" + }, + "type": "array" + }, "heldBack": { "default": [], "description": "Packages that could not reach `latest`, with attribution.", @@ -195,19 +235,51 @@ expression: out ], "description": "Present when the whole resolution failed." }, - "raw": { - "description": "The engine's untouched output, kept for the log and for bug reports.", - "type": "string" + "incompatible": { + "description": "Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`).", + "items": { + "$ref": "#/$defs/PythonMismatch" + }, + "type": "array" + }, + "yanked": { + "description": "Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2):\nboth engines exit 0 and install them. Both adapters parsed these and then dropped them, so\nthe preview never showed one.", + "items": { + "$ref": "#/$defs/YankWarning" + }, + "type": "array" } }, - "required": [ - "raw" - ], "type": "object" }, "Version": { "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", "type": "string" + }, + "YankWarning": { + "description": "A yanked release appearing in a plan.\n\nSP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview\nwarning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003).", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The yanked distribution." + }, + "reason": { + "description": "Upstream's stated reason, when given.", + "type": [ + "string", + "null" + ] + }, + "version": { + "$ref": "#/$defs/Version", + "description": "The version that was yanked." + } + }, + "required": [ + "pkg", + "version" + ], + "type": "object" } }, "$schema": "https://json-schema.org/draft/2020-12/schema", diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap index 6419ad4..9a1284b 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap @@ -150,9 +150,62 @@ expression: out "description": "A PEP 503-normalized distribution name.\n\nConstructing one is the *only* way a package name reaches an argv array, which is what makes\nSECURITY §2's \"validated before it reaches argv\" claim structural rather than aspirational.", "type": "string" }, + "PythonMismatch": { + "description": "A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`).\n\nHard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree:\npip refuses such a pin with the same \"No matching distribution\" it uses for a typo, and uv\nignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows\nthe required range against the environment's version, and a catalog cannot un-join a string.", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The package." + }, + "python": { + "description": "The environment's Python, e.g. `\"3.12.4\"`.", + "type": "string" + }, + "requiresPython": { + "description": "That release's `Requires-Python`, verbatim.", + "type": "string" + }, + "version": { + "$ref": "#/$defs/Version", + "description": "The version that was asked for or planned." + } + }, + "required": [ + "pkg", + "version", + "requiresPython", + "python" + ], + "type": "object" + }, "Version": { "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", "type": "string" + }, + "YankWarning": { + "description": "A yanked release appearing in a plan.\n\nSP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview\nwarning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003).", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The yanked distribution." + }, + "reason": { + "description": "Upstream's stated reason, when given.", + "type": [ + "string", + "null" + ] + }, + "version": { + "$ref": "#/$defs/Version", + "description": "The version that was yanked." + } + }, + "required": [ + "pkg", + "version" + ], + "type": "object" } }, "$schema": "https://json-schema.org/draft/2020-12/schema", @@ -166,6 +219,13 @@ expression: out }, "type": "array" }, + "forced": { + "description": "Packages the user chose to **force** past what installed dependents allow, each with what\nit will break — the \"Will break\" section of the preview (DISCLAIMER §2).", + "items": { + "$ref": "#/$defs/HeldBack" + }, + "type": "array" + }, "heldBack": { "default": [], "description": "Packages that could not reach `latest`, with attribution.", @@ -185,14 +245,21 @@ expression: out ], "description": "Present when the whole resolution failed." }, - "raw": { - "description": "The engine's untouched output, kept for the log and for bug reports.", - "type": "string" + "incompatible": { + "description": "Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`).", + "items": { + "$ref": "#/$defs/PythonMismatch" + }, + "type": "array" + }, + "yanked": { + "description": "Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2):\nboth engines exit 0 and install them. Both adapters parsed these and then dropped them, so\nthe preview never showed one.", + "items": { + "$ref": "#/$defs/YankWarning" + }, + "type": "array" } }, - "required": [ - "raw" - ], "title": "ResolutionReport", "type": "object" } diff --git a/crates/pipdock-core/src/engine/parse.rs b/crates/pipdock-core/src/engine/parse.rs index 85af86f..c0888a4 100644 --- a/crates/pipdock-core/src/engine/parse.rs +++ b/crates/pipdock-core/src/engine/parse.rs @@ -22,7 +22,9 @@ use crate::plan::{Change, ChangeKind, ImpossibleDetail, ResolutionReport}; /// /// SP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview /// warning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003). -#[derive(Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize)] +#[derive( + Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema, +)] pub struct YankWarning { /// The yanked distribution. pub pkg: PkgName, @@ -41,6 +43,20 @@ pub struct ParsedPlan { pub yanked: Vec, } +impl ParsedPlan { + /// The report with its yank warnings inside it, where the preview can see them. + /// + /// Both adapters used to take `.report` and drop `.yanked`, so the PD-PKG-003 warning both + /// parsers worked to extract never reached a user. + #[must_use] + pub fn into_report(self) -> crate::plan::ResolutionReport { + crate::plan::ResolutionReport { + yanked: self.yanked, + ..self.report + } + } +} + // -- pip --------------------------------------------------------------------- /// Parse pip's `install --dry-run --report -` JSON from stdout. @@ -148,7 +164,12 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result Result Result crate::model::CheckReport { crate::model::CheckReport { ok: ok && findings.is_empty(), findings, + error: None, } } diff --git a/crates/pipdock-core/src/engine/pip.rs b/crates/pipdock-core/src/engine/pip.rs index add8214..b598000 100644 --- a/crates/pipdock-core/src/engine/pip.rs +++ b/crates/pipdock-core/src/engine/pip.rs @@ -146,7 +146,8 @@ impl Engine for PipEngine { if !out.ok() { return Err(out.into_error()); } - super::parse::pip_report(&out.stdout, &out.stderr, &installed).map(|p| p.report) + super::parse::pip_report(&out.stdout, &out.stderr, &installed) + .map(super::parse::ParsedPlan::into_report) } async fn install( diff --git a/crates/pipdock-core/src/engine/uv.rs b/crates/pipdock-core/src/engine/uv.rs index 0585106..12eb0da 100644 --- a/crates/pipdock-core/src/engine/uv.rs +++ b/crates/pipdock-core/src/engine/uv.rs @@ -151,7 +151,8 @@ impl Engine for UvEngine { .await?; // uv exits non-zero on an unsatisfiable set, but its message is the most useful thing it // produces (SP-1), so the plan is parsed either way and the parser decides. - super::parse::uv_plan(&out.stdout, &out.stderr, &installed).map(|p| p.report) + super::parse::uv_plan(&out.stdout, &out.stderr, &installed) + .map(super::parse::ParsedPlan::into_report) } async fn install( diff --git a/crates/pipdock-core/src/fixtures.rs b/crates/pipdock-core/src/fixtures.rs index ba97a96..ed83a16 100644 --- a/crates/pipdock-core/src/fixtures.rs +++ b/crates/pipdock-core/src/fixtures.rs @@ -150,6 +150,9 @@ fn flow_step() -> crate::flow::FlowStep { explanation: "no version of oldlib is compatible with python 3.12".to_owned(), packages: vec![pkg("oldlib")], }), + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), }, round: 0, @@ -190,6 +193,7 @@ fn execution_summary() -> crate::plan::ExecutionSummary { results, check: CheckReport { ok: true, + error: None, findings: Vec::new(), }, counts, diff --git a/crates/pipdock-core/src/flow/mod.rs b/crates/pipdock-core/src/flow/mod.rs index 7e9484a..5594c6a 100644 --- a/crates/pipdock-core/src/flow/mod.rs +++ b/crates/pipdock-core/src/flow/mod.rs @@ -88,6 +88,8 @@ pub enum NothingReason { NothingToDo, /// Every candidate was skipped while resolving conflicts, so no plan remains. EverythingSkipped, + /// The user stopped the resolve before it finished. Nothing was planned, nothing ran. + Cancelled, } /// What the flow needs next. diff --git a/crates/pipdock-core/src/model.rs b/crates/pipdock-core/src/model.rs index b5819cb..5a0e87b 100644 --- a/crates/pipdock-core/src/model.rs +++ b/crates/pipdock-core/src/model.rs @@ -439,11 +439,17 @@ pub struct CheckFinding { /// Post-execution environment verification. #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, schemars::JsonSchema)] pub struct CheckReport { - /// True when the engine reported no broken requirements. + /// True when the check **ran** and the engine reported no broken requirements. pub ok: bool, /// Details when `ok` is false. #[serde(default)] pub findings: Vec, + /// Set when the check could not run at all, with the reason's code; `ok` is false then. + /// + /// A check that could not run used to be reported as `ok: true` — "verified" in exactly the + /// case where nothing was verified, such as a pip broken by the run it was meant to check. + #[serde(default, skip_serializing_if = "Option::is_none")] + pub error: Option, } #[cfg(test)] diff --git a/crates/pipdock-core/src/plan/mod.rs b/crates/pipdock-core/src/plan/mod.rs index 691884f..0fa59f7 100644 --- a/crates/pipdock-core/src/plan/mod.rs +++ b/crates/pipdock-core/src/plan/mod.rs @@ -118,6 +118,27 @@ pub struct HeldBack { pub blockers: Vec, } +/// A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`). +/// +/// Hard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree: +/// pip refuses such a pin with the same "No matching distribution" it uses for a typo, and uv +/// ignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows +/// the required range against the environment's version, and a catalog cannot un-join a string. +#[derive( + Debug, Clone, PartialEq, Eq, serde::Serialize, serde::Deserialize, schemars::JsonSchema, +)] +#[serde(rename_all = "camelCase")] +pub struct PythonMismatch { + /// The package. + pub pkg: PkgName, + /// The version that was asked for or planned. + pub version: Version, + /// That release's `Requires-Python`, verbatim. + pub requires_python: String, + /// The environment's Python, e.g. `"3.12.4"`. + pub python: String, +} + /// A `ResolutionImpossible` outcome and whatever detail the engine gave (`PD-RES-001`). #[derive(Debug, Clone, serde::Serialize, serde::Deserialize, schemars::JsonSchema)] pub struct ImpossibleDetail { @@ -151,7 +172,24 @@ pub struct ResolutionReport { /// Present when the whole resolution failed. #[serde(skip_serializing_if = "Option::is_none")] pub impossible: Option, - /// The engine's untouched output, kept for the log and for bug reports. + /// Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`). + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub incompatible: Vec, + /// Packages the user chose to **force** past what installed dependents allow, each with what + /// it will break — the "Will break" section of the preview (DISCLAIMER §2). + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub forced: Vec, + /// Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2): + /// both engines exit 0 and install them. Both adapters parsed these and then dropped them, so + /// the preview never showed one. + #[serde(default, skip_serializing_if = "Vec::is_empty")] + pub yanked: Vec, + /// What the engine wrote while resolving — uv's plan, pip's warnings — for the log ring and + /// the debug log. **Never on the wire.** It used to be, as pip's whole `--report` document + /// with every package's README inside it, cloned into each `FlowStep` and serialized over IPC + /// on every round (33 KB for two packages; megabytes for "update all"). + #[serde(skip)] + #[schemars(skip)] pub raw: String, } @@ -507,6 +545,7 @@ pub async fn execute( results: Vec::new(), check: engine.check(env).await.unwrap_or(CheckReport { ok: true, + error: None, findings: Vec::new(), }), counts: Counts::default(), @@ -746,14 +785,16 @@ async fn summary( } } -/// Run the post-execution check, treating an unrunnable check as "no findings". +/// Run the post-execution check, reporting a check that could not run **as not having run**. /// -/// A check that could not run must not turn a successful run into a reported failure; the summary -/// already carries the per-package truth. +/// It must not turn a successful run into a failed one — the summary's rows still carry the +/// per-package truth — but it must not say "verified" either, which `unwrap_or(ok: true)` did: +/// exactly when pip had been broken by the run it was meant to check. async fn post_check(engine: &dyn Engine, env: &PyEnv) -> CheckReport { - engine.check(env).await.unwrap_or(CheckReport { - ok: true, + engine.check(env).await.unwrap_or_else(|e| CheckReport { + ok: false, findings: Vec::new(), + error: Some(e.code), }) } @@ -1048,6 +1089,9 @@ mod tests { changes: vec![], held_back: vec![held], impossible: None, + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), }; assert!(!report.is_clean()); @@ -1064,6 +1108,9 @@ mod tests { }], held_back: vec![], impossible: None, + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), }; assert!(report.is_clean()); @@ -1122,4 +1169,22 @@ mod tests { offenders.join("\n ") ); } + + #[test] + fn the_engine_output_never_crosses_the_wire() { + // pip's whole `--report` — every README in the plan — rode in each FlowStep over IPC and + // into `--json`. It stays in Rust, for the log. + let report = ResolutionReport { + raw: "a very large engine document".into(), + ..ResolutionReport::default() + }; + let wire = serde_json::to_value(&report).expect("serializes"); + assert!(wire.get("raw").is_none(), "{wire}"); + let schema = serde_json::to_value(schemars::schema_for!(ResolutionReport)) + .expect("schema serializes"); + assert!( + schema["properties"].get("raw").is_none(), + "the schema must not promise it either" + ); + } } diff --git a/crates/pipdock-core/src/plan/preview.rs b/crates/pipdock-core/src/plan/preview.rs index 2718f51..907805a 100644 --- a/crates/pipdock-core/src/plan/preview.rs +++ b/crates/pipdock-core/src/plan/preview.rs @@ -238,6 +238,9 @@ mod tests { changes: Vec::new(), held_back: Vec::new(), impossible: None, + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), } } diff --git a/crates/pipdock-core/tests/execution.rs b/crates/pipdock-core/tests/execution.rs index 8cf90a9..5e1bccb 100644 --- a/crates/pipdock-core/tests/execution.rs +++ b/crates/pipdock-core/tests/execution.rs @@ -63,6 +63,8 @@ struct FakeEngine { batch: Batch, /// The constraints each install was given, in call order. constraints: Arc>>>, + /// `check` cannot run at all — a pip broken by the run it was meant to verify. + check_breaks: bool, } impl FakeEngine { @@ -72,10 +74,12 @@ impl FakeEngine { calls: Arc::new(Mutex::new(Vec::new())), check: CheckReport { ok: true, + error: None, findings: Vec::new(), }, batch: Batch::Runs, constraints: Arc::new(Mutex::new(Vec::new())), + check_breaks: false, } } @@ -112,6 +116,9 @@ impl Engine for FakeEngine { changes: Vec::new(), held_back: Vec::new(), impossible: None, + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), }) } @@ -218,6 +225,12 @@ impl Engine for FakeEngine { }) } async fn check(&self, _env: &PyEnv) -> Result { + if self.check_breaks { + return Err(pipdock_core::errors::PdError::new( + pipdock_core::errors::Code::EngNotFound, + "No module named pip", + )); + } Ok(self.check.clone()) } async fn freeze(&self, _env: &PyEnv) -> Result { @@ -258,6 +271,9 @@ fn report(packages: &[(&str, &str)]) -> ResolutionReport { .collect(), held_back: Vec::new(), impossible: None, + incompatible: Vec::new(), + forced: Vec::new(), + yanked: Vec::new(), raw: String::new(), } } @@ -590,6 +606,7 @@ async fn post_check_findings_reach_the_summary() { requirement: "apiclient 1.4 requires requests<2.31, but you have requests 2.32.3" .into(), }], + error: None, }; let summary = run(&engine, &[("requests", "2.32.3")]).await; @@ -792,6 +809,21 @@ async fn an_isolated_step_holds_everything_else_where_the_preview_put_it() { assert_eq!(rendered(&constraints[2]), ["alpha==2.0", "bystander==1.5"]); } +#[tokio::test] +async fn a_check_that_could_not_run_is_not_reported_as_passed() { + // `unwrap_or(ok: true)` said "verified" exactly when nothing was — for instance when the run + // being checked had broken pip itself. + let mut engine = FakeEngine::new(&[]); + engine.check_breaks = true; + let summary = run(&engine, &[("alpha", "1.0")]).await; + assert!(!summary.check.ok, "{:?}", summary.check); + assert_eq!( + summary.check.error, + Some(pipdock_core::errors::Code::EngNotFound) + ); + assert_eq!(summary.counts.ok, 1, "the install itself still succeeded"); +} + #[tokio::test] async fn an_uncancelled_run_does_not_claim_it_was_cancelled() { let summary = run(&FakeEngine::new(&[]), &[("alpha", "1.0")]).await; diff --git a/crates/pipdock-core/tests/plan_parsers.rs b/crates/pipdock-core/tests/plan_parsers.rs index 754f7b2..b063ee0 100644 --- a/crates/pipdock-core/tests/plan_parsers.rs +++ b/crates/pipdock-core/tests/plan_parsers.rs @@ -201,6 +201,23 @@ fn both_engines_flag_the_yanked_release_without_failing() { } } +#[test] +fn a_yank_reaches_the_report_the_preview_reads() { + // Both adapters took `.report` and dropped `.yanked`, so the warning both parsers extract + // never reached a user. `into_report` is what the adapters return now. + for engine in CORPORA { + let cap = load(engine, "yanked").expect("fixture"); + let parsed = match engine { + "pip" => pip_report(&cap.stdout, &cap.stderr, &[]), + _ => uv_plan(&cap.stdout, &cap.stderr, &[]), + } + .unwrap_or_else(|e| panic!("{engine}: {e}")); + let report = parsed.into_report(); + assert_eq!(report.yanked.len(), 1, "{engine}"); + assert_eq!(report.yanked[0].pkg.as_str(), "urllib3", "{engine}"); + } +} + #[test] fn the_encoding_crash_fixture_is_reported_as_a_pipdock_bug() { // The fixture captured without the UTF-8 mitigation. Reporting it as "upgrade pip" would send diff --git a/ui/src/ipc/generated.ts b/ui/src/ipc/generated.ts index 363af46..c943ed4 100644 --- a/ui/src/ipc/generated.ts +++ b/ui/src/ipc/generated.ts @@ -192,9 +192,16 @@ export interface CheckFinding { /** Post-execution environment verification. */ export interface CheckReport { + /** + * Set when the check could not run at all, with the reason's code; `ok` is false then. + * + * A check that could not run used to be reported as `ok: true` — "verified" in exactly the + * case where nothing was verified, such as a pip broken by the run it was meant to check. + */ + error?: Code | null; /** Details when `ok` is false. */ findings?: CheckFinding[]; - /** True when the engine reported no broken requirements. */ + /** True when the check **ran** and the engine reported no broken requirements. */ ok: boolean; } @@ -639,7 +646,8 @@ export type MatchKind = /** Why a flow ended before there was anything to confirm. */ export type NothingReason = | 'nothing-to-do' - | 'everything-skipped'; + | 'everything-skipped' + | 'cancelled'; /** An installed distribution with a newer release available. */ export interface OutdatedDist { @@ -779,6 +787,25 @@ export interface PyEnv { source: EnvSource; } +/** + * A pin the user asked for that cannot install on this environment's Python (`PD-PKG-001`). + * + * Hard invariant 10 says PipDock enforces `Requires-Python` itself, because the engines disagree: + * pip refuses such a pin with the same "No matching distribution" it uses for a typo, and uv + * ignores an upper bound and plans it. Structured, not a sentence (invariant 4): the preview shows + * the required range against the environment's version, and a catalog cannot un-join a string. + */ +export interface PythonMismatch { + /** The package. */ + pkg: PkgName; + /** The environment's Python, e.g. `"3.12.4"`. */ + python: string; + /** That release's `Requires-Python`, verbatim. */ + requiresPython: string; + /** The version that was asked for or planned. */ + version: Version; +} + /** What a refresh did. */ export interface RefreshReport { /** How long the whole refresh took. */ @@ -803,12 +830,23 @@ export interface RefreshReport { export interface ResolutionReport { /** Everything that would change if the user confirms. */ changes?: Change[]; + /** + * Packages the user chose to **force** past what installed dependents allow, each with what + * it will break — the "Will break" section of the preview (DISCLAIMER §2). + */ + forced?: HeldBack[]; /** Packages that could not reach `latest`, with attribution. */ heldBack?: HeldBack[]; /** Present when the whole resolution failed. */ impossible?: ImpossibleDetail | null; - /** The engine's untouched output, kept for the log and for bug reports. */ - raw: string; + /** Pins left out because their `Requires-Python` excludes this environment (`PD-PKG-001`). */ + incompatible?: PythonMismatch[]; + /** + * Yanked releases the plan would install. A warning, not a failure (`PD-PKG-003`, SP-2): + * both engines exit 0 and install them. Both adapters parsed these and then dropped them, so + * the preview never showed one. + */ + yanked?: YankWarning[]; } /** The operations that would restore a snapshot. */ @@ -1041,3 +1079,18 @@ export interface VultureFinding { /** As vulture printed it, relative to the project folder. */ path: string; } + +/** + * A yanked release appearing in a plan. + * + * SP-2: a yank is **not** a failure. Both engines exit 0 and install it, so this is a preview + * warning row, not an error path (`docs/ERROR-CATALOG.md` PD-PKG-003). + */ +export interface YankWarning { + /** The yanked distribution. */ + pkg: PkgName; + /** Upstream's stated reason, when given. */ + reason?: string | null; + /** The version that was yanked. */ + version: Version; +} diff --git a/ui/src/test/fixtures/flow_step.json b/ui/src/test/fixtures/flow_step.json index f1e182b..076e178 100644 --- a/ui/src/test/fixtures/flow_step.json +++ b/ui/src/test/fixtures/flow_step.json @@ -55,8 +55,7 @@ "oldlib" ], "explanation": "no version of oldlib is compatible with python 3.12" - }, - "raw": "" + } }, "round": 0, "roundsRemaining": 3