feat(wire)!: the preview carries what it was missing, and stops carrying the engine's output

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 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-17 00:55:27 +07:00
1 parent 80b2cee9e7
commit d2993bbd7d
17 files changed
+588 -31

No files matched your search

+5
View File
@@ -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 } => {
@@ -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"
}
},
@@ -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"
}
},
@@ -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",
@@ -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"
}
+30 -2
View File
@@ -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<YankWarning>,
}
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<Pars
changes,
held_back: Vec::new(),
impossible: None,
raw: stdout.to_owned(),
incompatible: Vec::new(),
forced: Vec::new(),
yanked: Vec::new(),
// pip's stderr — its warnings — not the `--report` document on stdout, which carries
// every package's README and is already parsed above.
raw: stderr.to_owned(),
},
yanked,
})
@@ -202,6 +223,9 @@ pub fn uv_plan(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedP
changes: Vec::new(),
held_back: Vec::new(),
impossible: Some(detail),
incompatible: Vec::new(),
forced: Vec::new(),
yanked: Vec::new(),
raw: text.to_owned(),
},
yanked: Vec::new(),
@@ -294,6 +318,9 @@ pub fn uv_plan(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<ParsedP
changes,
held_back: Vec::new(),
impossible: None,
incompatible: Vec::new(),
forced: Vec::new(),
yanked: Vec::new(),
raw: text.to_owned(),
},
yanked: uv_yank_warnings(text),
@@ -445,6 +472,7 @@ pub fn check_text(stdout: &str, ok: bool) -> crate::model::CheckReport {
crate::model::CheckReport {
ok: ok && findings.is_empty(),
findings,
error: None,
}
}
+2 -1
View File
@@ -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(
+2 -1
View File
@@ -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(
+4
View File
@@ -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,
+2
View File
@@ -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.
+7 -1
View File
@@ -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<CheckFinding>,
/// 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<Code>,
}
#[cfg(test)]
+71 -6
View File
@@ -118,6 +118,27 @@ pub struct HeldBack {
pub blockers: Vec<Blocker>,
}
/// 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<ImpossibleDetail>,
/// 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<PythonMismatch>,
/// 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<HeldBack>,
/// 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<crate::engine::parse::YankWarning>,
/// 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"
);
}
}
+3
View File
@@ -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(),
}
}
+32
View File
@@ -63,6 +63,8 @@ struct FakeEngine {
batch: Batch,
/// The constraints each install was given, in call order.
constraints: Arc<Mutex<Vec<Vec<PinnedSpec>>>>,
/// `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<CheckReport> {
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<String> {
@@ -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;
+17
View File
@@ -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
+57 -4
View File
@@ -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;
}
+1 -2
View File
@@ -55,8 +55,7 @@
"oldlib"
],
"explanation": "no version of oldlib is compatible with python 3.12"
},
"raw": ""
}
},
"round": 0,
"roundsRemaining": 3