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:
1 parent
80b2cee9e7
commit
d2993bbd7d
17 files changed
+588
-31
No files matched your search
@@ -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"
|
||||
}
|
||||
@@ -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,
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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(
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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.
|
||||
|
||||
@@ -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)]
|
||||
|
||||
@@ -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"
|
||||
);
|
||||
}
|
||||
}
|
||||
@@ -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(),
|
||||
}
|
||||
}
|
||||
|
||||
@@ -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;
|
||||
|
||||
@@ -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
@@ -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;
|
||||
}
|
||||
Vendored
+1
-2
@@ -55,8 +55,7 @@
|
||||
"oldlib"
|
||||
],
|
||||
"explanation": "no version of oldlib is compatible with python 3.12"
|
||||
},
|
||||
"raw": ""
|
||||
}
|
||||
},
|
||||
"round": 0,
|
||||
"roundsRemaining": 3
|
||||
|
||||
Reference in new issue
Block a user