From 1c728df64caa6512e8a087ed85ca04b759081c12 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Wed, 29 Jul 2026 20:02:45 +0700 Subject: [PATCH] test(cli): add the L4 golden-output suite TESTING L4 has been owed since M1. `assert_cmd` and `insta` were already dev-dependencies with zero references and no `tests/` directory in the crate. TESTING section 2 asks for "golden-output tests per command against a mocked core", and the CLI has no seam to mock at: run.rs builds its engine from the global options and drives a real interpreter, and print_preview / print_summary are private functions that println! rather than return. So the preview and summary renderings stay with L2 against real environments, and what is goldened here is everything deterministic without one -- the clap surface, the exit-code table CLI-SPEC section 5 calls a public contract, the --json error envelope, and `schema ` for all fifteen SCHEMA_TYPES. That last group is the point. It pins two contract bugs the M2 bridge has to fix, so the fix arrives as a reviewable diff rather than as an invisible change: - ExecutionSummary serializes plan_id and stderr_tail, where DATA-FLOW section 6 documents planId and stderrTail - Code serializes as its Rust variant name ("EnvInterpreterMissing"), where ERROR-CATALOG documents the wire code (PD-ENV-001) Both are visible in the committed snapshots today. The error envelope, which main.rs hand-builds rather than deriving, already has the documented shape -- so the same binary currently disagrees with itself across its two --json paths. Snapshots are filtered for the executable name (pipdock.exe on Windows) and the crate version, so they record the contract rather than the machine or the release. insta gains its `filters` feature for that. 183 tests pass, fmt and clippy clean. Co-Authored-By: Claude Opus 5 --- Cargo.lock | 20 + crates/pipdock-cli/Cargo.toml | 4 +- crates/pipdock-cli/tests/golden.rs | 252 ++++++++++++ .../golden__error-envelope-human.snap | 5 + .../golden__error-envelope-json.snap | 5 + .../tests/snapshots/golden__help-doctor.snap | 41 ++ .../tests/snapshots/golden__help-engine.snap | 42 ++ .../snapshots/golden__help-env-list.snap | 41 ++ .../tests/snapshots/golden__help-env-use.snap | 45 +++ .../tests/snapshots/golden__help-env.snap | 46 +++ .../tests/snapshots/golden__help-health.snap | 50 +++ .../snapshots/golden__help-index-refresh.snap | 41 ++ .../tests/snapshots/golden__help-index.snap | 45 +++ .../tests/snapshots/golden__help-info.snap | 45 +++ .../tests/snapshots/golden__help-install.snap | 48 +++ .../tests/snapshots/golden__help-list.snap | 44 +++ .../tests/snapshots/golden__help-pin-add.snap | 48 +++ .../snapshots/golden__help-pin-list.snap | 41 ++ .../snapshots/golden__help-pin-remove.snap | 45 +++ .../tests/snapshots/golden__help-pin.snap | 47 +++ .../snapshots/golden__help-pip-upgrade.snap | 41 ++ .../tests/snapshots/golden__help-schema.snap | 45 +++ .../tests/snapshots/golden__help-search.snap | 50 +++ .../golden__help-self-report-bug.snap | 41 ++ .../tests/snapshots/golden__help-self.snap | 45 +++ .../golden__help-snapshot-create.snap | 41 ++ .../snapshots/golden__help-snapshot-diff.snap | 45 +++ .../snapshots/golden__help-snapshot-list.snap | 41 ++ .../golden__help-snapshot-rollback.snap | 45 +++ .../snapshots/golden__help-snapshot.snap | 48 +++ .../snapshots/golden__help-uninstall.snap | 48 +++ .../tests/snapshots/golden__help-update.snap | 63 +++ .../tests/snapshots/golden__help.snap | 64 +++ .../snapshots/golden__schema-CheckReport.snap | 51 +++ .../tests/snapshots/golden__schema-Code.snap | 161 ++++++++ .../tests/snapshots/golden__schema-Diff.snap | 89 +++++ .../tests/snapshots/golden__schema-Dist.snap | 50 +++ .../golden__schema-ExecutionSummary.snap | 368 ++++++++++++++++++ .../snapshots/golden__schema-GuardReport.snap | 47 +++ .../tests/snapshots/golden__schema-Hit.snap | 55 +++ .../golden__schema-OutdatedDist.snap | 39 ++ .../snapshots/golden__schema-PackageMeta.snap | 54 +++ .../tests/snapshots/golden__schema-Pin.snap | 73 ++++ .../snapshots/golden__schema-PlanRequest.snap | 96 +++++ .../tests/snapshots/golden__schema-PyEnv.snap | 79 ++++ .../golden__schema-ResolutionReport.snap | 191 +++++++++ .../golden__schema-SnapshotMeta.snap | 117 ++++++ .../snapshots/golden__schema-StepResult.snap | 249 ++++++++++++ .../golden__schema-unknown-type.snap | 5 + 49 files changed, 3295 insertions(+), 1 deletion(-) create mode 100644 crates/pipdock-cli/tests/golden.rs create mode 100644 crates/pipdock-cli/tests/snapshots/golden__error-envelope-human.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__error-envelope-json.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-doctor.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-engine.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-env-list.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-env-use.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-env.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-health.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-index-refresh.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-index.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-info.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-install.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-list.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-pin-add.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-pin-list.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-pin-remove.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-pin.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-pip-upgrade.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-schema.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-search.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-self-report-bug.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-self.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-snapshot-create.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-snapshot-diff.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-snapshot-list.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-snapshot-rollback.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-snapshot.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-uninstall.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help-update.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__help.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Code.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Diff.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Dist.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-GuardReport.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Hit.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-OutdatedDist.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-PackageMeta.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-Pin.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-PlanRequest.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-PyEnv.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-SnapshotMeta.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-StepResult.snap create mode 100644 crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap diff --git a/Cargo.lock b/Cargo.lock index 864626d..b0fbbfa 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -1950,8 +1950,10 @@ checksum = "86f0f8fee8c926415c58d6ae43a08523a26faccb2323f5e6b644fe7dd4ef6b82" dependencies = [ "console", "once_cell", + "regex", "serde", "similar", + "strip-ansi-escapes", "tempfile", ] @@ -3954,6 +3956,15 @@ dependencies = [ "quote", ] +[[package]] +name = "strip-ansi-escapes" +version = "0.2.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "2a8f8038e7e7969abb3f1b7c2a811225e9296da208539e0f79c5251d6cac0025" +dependencies = [ + "vte", +] + [[package]] name = "strsim" version = "0.11.1" @@ -5020,6 +5031,15 @@ dependencies = [ "libc", ] +[[package]] +name = "vte" +version = "0.14.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "231fdcd7ef3037e8330d8e17e61011a2c244126acc0a982f4040ac3f9f0bc077" +dependencies = [ + "memchr", +] + [[package]] name = "wait-timeout" version = "0.2.1" diff --git a/crates/pipdock-cli/Cargo.toml b/crates/pipdock-cli/Cargo.toml index a3833ba..db365db 100644 --- a/crates/pipdock-cli/Cargo.toml +++ b/crates/pipdock-cli/Cargo.toml @@ -26,4 +26,6 @@ tracing-subscriber = { version = "0.3.23", features = ["env-filter"] } [dev-dependencies] assert_cmd = "2.2.2" -insta = "1.48.0" +# `filters` gives `Settings::add_filter`, used to keep the crate version out of the help +# snapshots so a release bump does not churn every golden in tests/golden.rs. +insta = { version = "1.48.0", features = ["filters"] } diff --git a/crates/pipdock-cli/tests/golden.rs b/crates/pipdock-cli/tests/golden.rs new file mode 100644 index 0000000..5dcd137 --- /dev/null +++ b/crates/pipdock-cli/tests/golden.rs @@ -0,0 +1,252 @@ +//! TESTING L4 — golden output for the CLI surface. +//! +//! Scope note. TESTING §2 asks for "golden-output tests per command against a mocked core". The +//! CLI has no seam to mock at: `run.rs` builds its engine from the global options and drives a +//! real interpreter, and `print_preview` / `print_summary` are private functions that `println!` +//! rather than return. So the preview and summary renderings are covered by L2 against real +//! environments, and what is goldened here is everything that is deterministic without one: +//! +//! * the clap surface — every command's help, which is the flag contract scripts read; +//! * the exhaustive exit-code table (CLI-SPEC §5), which the docs call a public contract; +//! * the `--json` error envelope; +//! * `pipdock schema ` for all 15 types in `SCHEMA_TYPES`, which is the JSON contract +//! CLI-SPEC §6 promises consumers can pin against. +//! +//! That last one earns its keep beyond regression cover: the M2 bridge changes the wire format to +//! camelCase and makes `Code` serialize as `PD-*` rather than as its Rust variant name. These +//! snapshots are how that change becomes reviewable instead of invisible. +//! +//! When the flow refactor moves rendering out of the CLI (ROADMAP Phase 2 — "the flow never +//! prints"), the preview and summary renderers become pure functions of core types and should +//! gain their own snapshots here. + +// Same allowance the core integration tests take: in a test a panic *is* the failure report, and +// the workspace-wide deny exists to keep them out of shipping code. +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use assert_cmd::Command; + +/// Types `pipdock schema` can emit. Kept in step with `pipdock_core::plan::SCHEMA_TYPES` by +/// `schema_lists_exactly_the_documented_types` below, so this list cannot silently fall behind. +const SCHEMA_TYPES: &[&str] = &[ + "Dist", + "OutdatedDist", + "PyEnv", + "CheckReport", + "StepResult", + "PlanRequest", + "ResolutionReport", + "ExecutionSummary", + "Pin", + "GuardReport", + "Diff", + "SnapshotMeta", + "Hit", + "PackageMeta", + "Code", +]; + +fn pipdock() -> Command { + let mut cmd = Command::cargo_bin("pipdock").expect("the `pipdock` binary builds"); + // Colour and width leak the terminal into the snapshot; pin both. + cmd.env("NO_COLOR", "1").env("COLUMNS", "100"); + cmd +} + +fn stdout_of(args: &[&str]) -> String { + let out = pipdock().args(args).output().expect("the process runs"); + String::from_utf8_lossy(&out.stdout).replace("\r\n", "\n") +} + +fn stderr_of(args: &[&str]) -> String { + let out = pipdock().args(args).output().expect("the process runs"); + String::from_utf8_lossy(&out.stderr).replace("\r\n", "\n") +} + +fn code_of(args: &[&str]) -> i32 { + pipdock() + .args(args) + .output() + .expect("the process runs") + .status + .code() + .expect("the process exits rather than being signalled") +} + +/// Two things would otherwise make these snapshots record the machine rather than the contract: +/// clap prints the real executable name in every usage line, which is `pipdock.exe` on Windows +/// and `pipdock` everywhere else; and the crate version appears wherever clap renders it, so a +/// release bump would churn the whole file. +fn settings() -> insta::Settings { + let mut s = insta::Settings::clone_current(); + s.add_filter(r"\bpipdock\.exe\b", "pipdock"); + s.add_filter(r"\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b", "[VERSION]"); + s +} + +// -- the clap surface --------------------------------------------------------------------------- + +#[test] +fn top_level_help_is_stable() { + settings().bind(|| insta::assert_snapshot!("help", stdout_of(&["--help"]))); +} + +#[test] +fn every_command_documents_itself() { + // Drives the same list CLI-SPEC §3 enumerates. A command added without a doc comment, or one + // whose flags change shape, shows up here as a diff rather than in a user's script. + for cmd in [ + "env", + "list", + "search", + "info", + "install", + "update", + "uninstall", + "pin", + "snapshot", + "doctor", + "health", + "pip-upgrade", + "engine", + "index", + "schema", + "self", + ] { + settings().bind(|| { + insta::assert_snapshot!(format!("help-{cmd}"), stdout_of(&[cmd, "--help"])); + }); + } +} + +#[test] +fn subcommand_help_is_stable() { + for (parent, child) in [ + ("env", "list"), + ("env", "use"), + ("pin", "add"), + ("pin", "remove"), + ("pin", "list"), + ("snapshot", "list"), + ("snapshot", "create"), + ("snapshot", "diff"), + ("snapshot", "rollback"), + ("index", "refresh"), + ("self", "report-bug"), + ] { + settings().bind(|| { + insta::assert_snapshot!( + format!("help-{parent}-{child}"), + stdout_of(&[parent, child, "--help"]) + ); + }); + } +} + +// -- exit codes (CLI-SPEC §5) ------------------------------------------------------------------- + +#[test] +fn the_exit_code_table_holds() { + // "Scripts pin against these, so the numbers are a public contract" (main.rs). Every row here + // is reachable without touching a real interpreter; the rest are exercised by L2. + let cases: &[(&str, &[&str], i32)] = &[ + ("help exits clean", &["--help"], 0), + ("version exits clean", &["--version"], 0), + ("a valid schema type", &["schema", "Dist"], 0), + // clap's own usage errors are 2, distinct from PlanAborted, which is also 2 but only + // reachable once a plan exists. + ("an unknown command", &["no-such-command"], 2), + ("a missing required argument", &["info"], 2), + ("an unparseable engine", &["--engine", "cargo", "list"], 2), + // PD-ENV-001 -> EnvError. + ( + "a missing environment", + &["list", "--env", "C:/definitely/not/here"], + 3, + ), + ( + "a missing environment, doctor", + &["doctor", "--env", "C:/definitely/not/here"], + 3, + ), + ]; + + let mut failures = Vec::new(); + for (what, args, want) in cases { + let got = code_of(args); + if got != *want { + failures.push(format!( + "{what}: `pipdock {}` exited {got}, want {want}", + args.join(" ") + )); + } + } + assert!(failures.is_empty(), "{}", failures.join("\n")); +} + +#[test] +fn conflicting_verbosity_flags_are_refused() { + // `quiet` declares conflicts_with = "verbose"; if that attribute is dropped the two silently + // both apply and the log level becomes whichever clap saw last. + assert_eq!(code_of(&["--quiet", "--verbose", "list"]), 2); +} + +// -- the error envelope ------------------------------------------------------------------------- + +#[test] +fn the_json_error_envelope_is_stable() { + // DATA-FLOW §6 and ERROR-CATALOG §3 fix this shape: a wire code, a developer-facing message, + // and a stderr tail. `code` must be the catalog code, never the Rust variant name. + let out = stdout_of(&["list", "--env", "C:/definitely/not/here", "--json"]); + insta::assert_snapshot!("error-envelope-json", out); +} + +#[test] +fn the_human_error_line_carries_its_code() { + // ERROR-CATALOG §3: every user-visible failure carries exactly one catalog code. + let err = stderr_of(&["list", "--env", "C:/definitely/not/here"]); + insta::assert_snapshot!("error-envelope-human", err); + assert!( + err.contains("PD-ENV-001"), + "the code must be in the message: {err}" + ); +} + +#[test] +fn an_unknown_schema_type_lists_the_known_ones() { + insta::assert_snapshot!("schema-unknown-type", stderr_of(&["schema", "NoSuchType"])); +} + +// -- the JSON contract (CLI-SPEC §6) ------------------------------------------------------------ + +#[test] +fn schema_lists_exactly_the_documented_types() { + // Guards the local copy above against `SCHEMA_TYPES` drifting in core. The error path prints + // the real list, so it is the cheapest way to read it back out of the binary. + let listed = stderr_of(&["schema", "NoSuchType"]); + let (_, tail) = listed + .split_once("known types: ") + .unwrap_or_else(|| panic!("the unknown-type message no longer lists the types:\n{listed}")); + let from_binary: Vec<&str> = tail.trim().split(", ").map(str::trim).collect(); + + assert_eq!( + from_binary, SCHEMA_TYPES, + "core's SCHEMA_TYPES and this test's copy disagree" + ); +} + +#[test] +fn every_schema_is_valid_json_and_stable() { + // These snapshots are the review surface for the M2 wire-format change: camelCase properties + // and `Code` serializing as PD-* both land here first. + for ty in SCHEMA_TYPES { + let out = stdout_of(&["schema", ty]); + let parsed: serde_json::Value = + serde_json::from_str(&out).unwrap_or_else(|e| panic!("`schema {ty}` is not JSON: {e}")); + assert!( + parsed.get("$schema").is_some() || parsed.get("title").is_some(), + "`schema {ty}` does not look like a JSON Schema document" + ); + insta::assert_snapshot!(format!("schema-{ty}"), out); + } +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__error-envelope-human.snap b/crates/pipdock-cli/tests/snapshots/golden__error-envelope-human.snap new file mode 100644 index 0000000..42606a6 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__error-envelope-human.snap @@ -0,0 +1,5 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: err +--- +error[PD-ENV-001]: no interpreter at C:/definitely/not/here diff --git a/crates/pipdock-cli/tests/snapshots/golden__error-envelope-json.snap b/crates/pipdock-cli/tests/snapshots/golden__error-envelope-json.snap new file mode 100644 index 0000000..dc1bd0a --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__error-envelope-json.snap @@ -0,0 +1,5 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{"code":"PD-ENV-001","message":"no interpreter at C:/definitely/not/here","stderrTail":null} diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-doctor.snap b/crates/pipdock-cli/tests/snapshots/golden__help-doctor.snap new file mode 100644 index 0000000..b4b1a54 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-doctor.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Engine check and environment sanity report + +Usage: pipdock doctor [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-engine.snap b/crates/pipdock-cli/tests/snapshots/golden__help-engine.snap new file mode 100644 index 0000000..29359a9 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-engine.snap @@ -0,0 +1,42 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Show or set the configured engine + +Usage: pipdock engine [OPTIONS] [ENGINE] + +Arguments: + [ENGINE] + Engine to switch to; omit to print the current one + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-env-list.snap b/crates/pipdock-cli/tests/snapshots/golden__help-env-list.snap new file mode 100644 index 0000000..5b59687 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-env-list.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +List discovered environments, their sources and PEP 668 flags + +Usage: pipdock env list [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-env-use.snap b/crates/pipdock-cli/tests/snapshots/golden__help-env-use.snap new file mode 100644 index 0000000..4c199d3 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-env-use.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Set the default environment + +Usage: pipdock env use [OPTIONS] + +Arguments: + + Interpreter or environment directory + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-env.snap b/crates/pipdock-cli/tests/snapshots/golden__help-env.snap new file mode 100644 index 0000000..eef4471 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-env.snap @@ -0,0 +1,46 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Manage environments + +Usage: pipdock env [OPTIONS] + +Commands: + list List discovered environments, their sources and PEP 668 flags + use Set the default environment + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-health.snap b/crates/pipdock-cli/tests/snapshots/golden__help-health.snap new file mode 100644 index 0000000..4e9b77a --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-health.snap @@ -0,0 +1,50 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Run Code Health (deptry / vulture / ruff) over a project folder + +Usage: pipdock health [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --path + Project folder; defaults to the folder remembered for this environment + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --tool + Run a single tool instead of all three + + --fix + Apply ruff's safe fixes. Prompts before writing + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-index-refresh.snap b/crates/pipdock-cli/tests/snapshots/golden__help-index-refresh.snap new file mode 100644 index 0000000..51a326f --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-index-refresh.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Re-pull the PEP 691 name index + +Usage: pipdock index refresh [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-index.snap b/crates/pipdock-cli/tests/snapshots/golden__help-index.snap new file mode 100644 index 0000000..de57617 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-index.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Index maintenance + +Usage: pipdock index [OPTIONS] + +Commands: + refresh Re-pull the PEP 691 name index + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-info.snap b/crates/pipdock-cli/tests/snapshots/golden__help-info.snap new file mode 100644 index 0000000..ed08beb --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-info.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Show cached PyPI metadata for a package + +Usage: pipdock info [OPTIONS] + +Arguments: + + Package name + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-install.snap b/crates/pipdock-cli/tests/snapshots/golden__help-install.snap new file mode 100644 index 0000000..a79f5f7 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-install.snap @@ -0,0 +1,48 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Install packages + +Usage: pipdock install [OPTIONS] ... + +Arguments: + ... + `name` or `name==version` + +Options: + --dry-run + Print the resolution report and exit without changing anything + + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-list.snap b/crates/pipdock-cli/tests/snapshots/golden__help-list.snap new file mode 100644 index 0000000..f048ccb --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-list.snap @@ -0,0 +1,44 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +List installed packages + +Usage: pipdock list [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --outdated + Show only packages with a newer release available + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-pin-add.snap b/crates/pipdock-cli/tests/snapshots/golden__help-pin-add.snap new file mode 100644 index 0000000..4903b96 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-pin-add.snap @@ -0,0 +1,48 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Pin a package so bulk updates skip it + +Usage: pipdock pin add [OPTIONS] + +Arguments: + + Package name + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --reason + Why it is pinned + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-pin-list.snap b/crates/pipdock-cli/tests/snapshots/golden__help-pin-list.snap new file mode 100644 index 0000000..d3e83fe --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-pin-list.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Show the pin list + +Usage: pipdock pin list [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-pin-remove.snap b/crates/pipdock-cli/tests/snapshots/golden__help-pin-remove.snap new file mode 100644 index 0000000..c74fecb --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-pin-remove.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Remove a pin + +Usage: pipdock pin remove [OPTIONS] + +Arguments: + + Package name + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-pin.snap b/crates/pipdock-cli/tests/snapshots/golden__help-pin.snap new file mode 100644 index 0000000..37eed26 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-pin.snap @@ -0,0 +1,47 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Manage the per-environment pin list + +Usage: pipdock pin [OPTIONS] + +Commands: + add Pin a package so bulk updates skip it + remove Remove a pin + list Show the pin list + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-pip-upgrade.snap b/crates/pipdock-cli/tests/snapshots/golden__help-pip-upgrade.snap new file mode 100644 index 0000000..f34a3c6 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-pip-upgrade.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Upgrade pip inside the selected environment + +Usage: pipdock pip-upgrade [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-schema.snap b/crates/pipdock-cli/tests/snapshots/golden__help-schema.snap new file mode 100644 index 0000000..e283b39 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-schema.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Print the JSON Schema for a core type so scripts can pin against it + +Usage: pipdock schema [OPTIONS] + +Arguments: + + Type name, e.g. `ResolutionReport` + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-search.snap b/crates/pipdock-cli/tests/snapshots/golden__help-search.snap new file mode 100644 index 0000000..b3a1aa6 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-search.snap @@ -0,0 +1,50 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Fuzzy-search the local PyPI name index + +Usage: pipdock search [OPTIONS] + +Arguments: + + Query string + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --limit + Maximum results + + [default: 20] + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-self-report-bug.snap b/crates/pipdock-cli/tests/snapshots/golden__help-self-report-bug.snap new file mode 100644 index 0000000..4deb426 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-self-report-bug.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Print a prefilled GitHub issue URL + +Usage: pipdock self report-bug [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-self.snap b/crates/pipdock-cli/tests/snapshots/golden__help-self.snap new file mode 100644 index 0000000..bbd2b7f --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-self.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Self-service helpers + +Usage: pipdock self [OPTIONS] + +Commands: + report-bug Print a prefilled GitHub issue URL + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-create.snap b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-create.snap new file mode 100644 index 0000000..6434606 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-create.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Take a snapshot now + +Usage: pipdock snapshot create [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-diff.snap b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-diff.snap new file mode 100644 index 0000000..6afe012 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-diff.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Diff a snapshot against the current environment + +Usage: pipdock snapshot diff [OPTIONS] + +Arguments: + + Snapshot id + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-list.snap b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-list.snap new file mode 100644 index 0000000..49c95c6 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-list.snap @@ -0,0 +1,41 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +List snapshots for the selected environment + +Usage: pipdock snapshot list [OPTIONS] + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-rollback.snap b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-rollback.snap new file mode 100644 index 0000000..402e9d3 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot-rollback.snap @@ -0,0 +1,45 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[parent, child, \"--help\"])" +--- +Restore a snapshot + +Usage: pipdock snapshot rollback [OPTIONS] + +Arguments: + + Snapshot id, or `latest` + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-snapshot.snap b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot.snap new file mode 100644 index 0000000..c2ce05e --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-snapshot.snap @@ -0,0 +1,48 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Manage snapshots + +Usage: pipdock snapshot [OPTIONS] + +Commands: + list List snapshots for the selected environment + create Take a snapshot now + diff Diff a snapshot against the current environment + rollback Restore a snapshot + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-uninstall.snap b/crates/pipdock-cli/tests/snapshots/golden__help-uninstall.snap new file mode 100644 index 0000000..236c914 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-uninstall.snap @@ -0,0 +1,48 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Remove packages, guarded by the reverse-dependency check + +Usage: pipdock uninstall [OPTIONS] ... + +Arguments: + ... + Packages to remove + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --force + Proceed even when the guard reports dependents that would break + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help-update.snap b/crates/pipdock-cli/tests/snapshots/golden__help-update.snap new file mode 100644 index 0000000..c3d9799 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help-update.snap @@ -0,0 +1,63 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[cmd, \"--help\"])" +--- +Update packages + +Usage: pipdock update [OPTIONS] [PKGS]... + +Arguments: + [PKGS]... + Packages to update; omit and pass `--all` for everything + +Options: + --all + Update every outdated package (pins still apply) + + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --strategy + Conflict strategy + + Possible values: + - compatible: Accept the resolver's compatible version. The safe default + - latest: Force the latest version. Off a TTY this requires an explicit acknowledgement + + [default: compatible] + + --except + Ad-hoc exclusions on top of the pin list + + --json + Machine-readable output; NDJSON for streaming commands + + --dry-run + Print the resolution report and exit without changing anything + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') diff --git a/crates/pipdock-cli/tests/snapshots/golden__help.snap b/crates/pipdock-cli/tests/snapshots/golden__help.snap new file mode 100644 index 0000000..b786da9 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__help.snap @@ -0,0 +1,64 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stdout_of(&[\"--help\"])" +--- +Inspect, install, update and clean up Python packages in bulk. +Every mutating operation is previewed and snapshotted first. + +Usage: pipdock [OPTIONS] + +Commands: + env Manage environments + list List installed packages + search Fuzzy-search the local PyPI name index + info Show cached PyPI metadata for a package + install Install packages + update Update packages + uninstall Remove packages, guarded by the reverse-dependency check + pin Manage the per-environment pin list + snapshot Manage snapshots + doctor Engine check and environment sanity report + health Run Code Health (deptry / vulture / ruff) over a project folder + pip-upgrade Upgrade pip inside the selected environment + engine Show or set the configured engine + index Index maintenance + schema Print the JSON Schema for a core type so scripts can pin against it + self Self-service helpers + help Print this message or the help of the given subcommand(s) + +Options: + --env + Interpreter or environment directory. Defaults to the last used env, else an auto-detected `.venv` in the working directory + + --engine + Override the configured engine for this invocation + + Possible values: + - pip: ` -m pip` + - uv: `uv pip --python ` + + --json + Machine-readable output; NDJSON for streaming commands + + -y, --yes + Assume defaults on all prompts. Conflicts resolve to *skip*, never *force* + + --quiet + Reduce log output + + --verbose + Increase log output + + --log-file + Tee logs to a file + + --no-snapshot + DANGEROUS: skip the pre-batch snapshot. CI images only; prints a warning. + + This is the sole documented escape from DATA-FLOW §9.2, and it exists because a throwaway CI container has nothing to roll back to. + + -h, --help + Print help (see a summary with '-h') + + -V, --version + Print version diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap new file mode 100644 index 0000000..a1fd532 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-CheckReport.snap @@ -0,0 +1,51 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "CheckFinding": { + "description": "One unsatisfied requirement reported by `pip check` / `uv pip check`.", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The distribution whose requirement is unsatisfied." + }, + "requirement": { + "description": "Human-readable requirement text as the engine printed it.", + "type": "string" + } + }, + "required": [ + "pkg", + "requirement" + ], + "type": "object" + }, + "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" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Post-execution environment verification.", + "properties": { + "findings": { + "default": [], + "description": "Details when `ok` is false.", + "items": { + "$ref": "#/$defs/CheckFinding" + }, + "type": "array" + }, + "ok": { + "description": "True when the engine reported no broken requirements.", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "title": "CheckReport", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Code.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Code.snap new file mode 100644 index 0000000..ae10a1b --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Code.snap @@ -0,0 +1,161 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "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": "EnvInterpreterMissing", + "description": "Interpreter path missing or not executable — the env was deleted or moved.", + "type": "string" + }, + { + "const": "EnvExternallyManaged", + "description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.", + "type": "string" + }, + { + "const": "EnvProbeFailed", + "description": "`probe.py` exited non-zero or produced unparseable output.", + "type": "string" + }, + { + "const": "EngNotFound", + "description": "pip or uv binary not found.", + "type": "string" + }, + { + "const": "EngPipTooOld", + "description": "pip older than 22.2, which predates `--dry-run --report`.", + "type": "string" + }, + { + "const": "EngUvShapeUnknown", + "description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).", + "type": "string" + }, + { + "const": "EngUnclassified", + "description": "Fallback for engine failures no classifier matched. Always last.", + "type": "string" + }, + { + "const": "ResImpossible", + "description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.", + "type": "string" + }, + { + "const": "ResPlanStale", + "description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.", + "type": "string" + }, + { + "const": "BldMsvcMissing", + "description": "MSVC build tools required but absent.", + "type": "string" + }, + { + "const": "BldBackendFailed", + "description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).", + "type": "string" + }, + { + "const": "BldWheelFailed", + "description": "Generic sdist wheel-build failure.", + "type": "string" + }, + { + "const": "PkgRequiresPython", + "description": "No matching distribution, and metadata shows a requires-python mismatch.", + "type": "string" + }, + { + "const": "PkgNotFound", + "description": "No matching distribution: name or version typo, or the release is gone.", + "type": "string" + }, + { + "const": "PkgYanked", + "description": "The requested release was yanked.", + "type": "string" + }, + { + "const": "PkgHashMismatch", + "description": "Downloaded artifact failed hash verification.", + "type": "string" + }, + { + "const": "NetUnreachable", + "description": "Timeout, connection aborted, or DNS failure.", + "type": "string" + }, + { + "const": "NetTlsFailure", + "description": "TLS/SSL verification failed — typically proxy or AV interception.", + "type": "string" + }, + { + "const": "NetIndexRefreshFailed", + "description": "PEP 691 index refresh failed; the stale index stays searchable.", + "type": "string" + }, + { + "const": "NetToolsBootstrapFailed", + "description": "Code Health tools-venv bootstrap could not reach PyPI.", + "type": "string" + }, + { + "const": "PrmSitePackagesReadOnly", + "description": "`PermissionError` writing site-packages (admin-owned Python).", + "type": "string" + }, + { + "const": "PrmFileLocked", + "description": "File locked by a running process (`WinError 32`).", + "type": "string" + }, + { + "const": "SnpWriteFailed", + "description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**", + "type": "string" + }, + { + "const": "SnpTargetUnavailable", + "description": "A release needed to restore a snapshot is no longer available on PyPI.", + "type": "string" + }, + { + "const": "SysPathTooLong", + "description": "`MAX_PATH` exceeded without the long-path opt-in.", + "type": "string" + }, + { + "const": "SysDiskFull", + "description": "Disk full.", + "type": "string" + }, + { + "const": "HltToolMissing", + "description": "A Code Health tool is missing from the tools venv.", + "type": "string" + }, + { + "const": "HltToolFailed", + "description": "A Code Health tool exited non-zero.", + "type": "string" + }, + { + "const": "HltTimeout", + "description": "A Code Health tool exceeded its watchdog timeout; partial report shown.", + "type": "string" + }, + { + "const": "IntUnexpected", + "description": "A PipDock bug: panic or unexpected state.", + "type": "string" + } + ], + "title": "Code" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Diff.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Diff.snap new file mode 100644 index 0000000..6a38424 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Diff.snap @@ -0,0 +1,89 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "ChangedEntry": { + "description": "One package whose version differs between two states.", + "properties": { + "current": { + "$ref": "#/$defs/Version", + "description": "What is installed now." + }, + "name": { + "$ref": "#/$defs/PkgName", + "description": "The package." + }, + "snapshot": { + "$ref": "#/$defs/Version", + "description": "What the snapshot recorded." + } + }, + "required": [ + "name", + "current", + "snapshot" + ], + "type": "object" + }, + "PinnedSpec": { + "description": "A resolved, exact `name==version` pair. Only these reach a mutating engine command.", + "properties": { + "name": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "version": { + "$ref": "#/$defs/Version", + "description": "The exact version the resolver chose." + } + }, + "required": [ + "name", + "version" + ], + "type": "object" + }, + "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" + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The difference between two environment states.", + "properties": { + "added": { + "description": "Present now, absent in the snapshot.", + "items": { + "$ref": "#/$defs/PinnedSpec" + }, + "type": "array" + }, + "changed": { + "description": "Present in both at different versions.", + "items": { + "$ref": "#/$defs/ChangedEntry" + }, + "type": "array" + }, + "removed": { + "description": "Present in the snapshot, absent now.", + "items": { + "$ref": "#/$defs/PinnedSpec" + }, + "type": "array" + } + }, + "required": [ + "added", + "removed", + "changed" + ], + "title": "Diff", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Dist.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Dist.snap new file mode 100644 index 0000000..1614967 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Dist.snap @@ -0,0 +1,50 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "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" + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "An installed distribution, as read by `probe.py` or ` list`.", + "properties": { + "name": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "requires_dist": { + "default": [], + "description": "Raw `Requires-Dist` entries. The reverse-dependency graph is built from these.", + "items": { + "type": "string" + }, + "type": "array" + }, + "requires_python": { + "default": null, + "description": "Raw `Requires-Python` specifier, when declared.", + "type": [ + "string", + "null" + ] + }, + "version": { + "$ref": "#/$defs/Version", + "description": "Installed version." + } + }, + "required": [ + "name", + "version" + ], + "title": "Dist", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap new file mode 100644 index 0000000..07f4133 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-ExecutionSummary.snap @@ -0,0 +1,368 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "CheckFinding": { + "description": "One unsatisfied requirement reported by `pip check` / `uv pip check`.", + "properties": { + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The distribution whose requirement is unsatisfied." + }, + "requirement": { + "description": "Human-readable requirement text as the engine printed it.", + "type": "string" + } + }, + "required": [ + "pkg", + "requirement" + ], + "type": "object" + }, + "CheckReport": { + "description": "Post-execution environment verification.", + "properties": { + "findings": { + "default": [], + "description": "Details when `ok` is false.", + "items": { + "$ref": "#/$defs/CheckFinding" + }, + "type": "array" + }, + "ok": { + "description": "True when the engine reported no broken requirements.", + "type": "boolean" + } + }, + "required": [ + "ok" + ], + "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": "EnvInterpreterMissing", + "description": "Interpreter path missing or not executable — the env was deleted or moved.", + "type": "string" + }, + { + "const": "EnvExternallyManaged", + "description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.", + "type": "string" + }, + { + "const": "EnvProbeFailed", + "description": "`probe.py` exited non-zero or produced unparseable output.", + "type": "string" + }, + { + "const": "EngNotFound", + "description": "pip or uv binary not found.", + "type": "string" + }, + { + "const": "EngPipTooOld", + "description": "pip older than 22.2, which predates `--dry-run --report`.", + "type": "string" + }, + { + "const": "EngUvShapeUnknown", + "description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).", + "type": "string" + }, + { + "const": "EngUnclassified", + "description": "Fallback for engine failures no classifier matched. Always last.", + "type": "string" + }, + { + "const": "ResImpossible", + "description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.", + "type": "string" + }, + { + "const": "ResPlanStale", + "description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.", + "type": "string" + }, + { + "const": "BldMsvcMissing", + "description": "MSVC build tools required but absent.", + "type": "string" + }, + { + "const": "BldBackendFailed", + "description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).", + "type": "string" + }, + { + "const": "BldWheelFailed", + "description": "Generic sdist wheel-build failure.", + "type": "string" + }, + { + "const": "PkgRequiresPython", + "description": "No matching distribution, and metadata shows a requires-python mismatch.", + "type": "string" + }, + { + "const": "PkgNotFound", + "description": "No matching distribution: name or version typo, or the release is gone.", + "type": "string" + }, + { + "const": "PkgYanked", + "description": "The requested release was yanked.", + "type": "string" + }, + { + "const": "PkgHashMismatch", + "description": "Downloaded artifact failed hash verification.", + "type": "string" + }, + { + "const": "NetUnreachable", + "description": "Timeout, connection aborted, or DNS failure.", + "type": "string" + }, + { + "const": "NetTlsFailure", + "description": "TLS/SSL verification failed — typically proxy or AV interception.", + "type": "string" + }, + { + "const": "NetIndexRefreshFailed", + "description": "PEP 691 index refresh failed; the stale index stays searchable.", + "type": "string" + }, + { + "const": "NetToolsBootstrapFailed", + "description": "Code Health tools-venv bootstrap could not reach PyPI.", + "type": "string" + }, + { + "const": "PrmSitePackagesReadOnly", + "description": "`PermissionError` writing site-packages (admin-owned Python).", + "type": "string" + }, + { + "const": "PrmFileLocked", + "description": "File locked by a running process (`WinError 32`).", + "type": "string" + }, + { + "const": "SnpWriteFailed", + "description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**", + "type": "string" + }, + { + "const": "SnpTargetUnavailable", + "description": "A release needed to restore a snapshot is no longer available on PyPI.", + "type": "string" + }, + { + "const": "SysPathTooLong", + "description": "`MAX_PATH` exceeded without the long-path opt-in.", + "type": "string" + }, + { + "const": "SysDiskFull", + "description": "Disk full.", + "type": "string" + }, + { + "const": "HltToolMissing", + "description": "A Code Health tool is missing from the tools venv.", + "type": "string" + }, + { + "const": "HltToolFailed", + "description": "A Code Health tool exited non-zero.", + "type": "string" + }, + { + "const": "HltTimeout", + "description": "A Code Health tool exceeded its watchdog timeout; partial report shown.", + "type": "string" + }, + { + "const": "IntUnexpected", + "description": "A PipDock bug: panic or unexpected state.", + "type": "string" + } + ] + }, + "Counts": { + "description": "Aggregate counts rendered as \"13 successful, 2 failed, 1 skipped\" (DATA-FLOW §6).", + "properties": { + "failed": { + "description": "Steps that failed, each with a catalog code.", + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "ok": { + "description": "Steps that applied.", + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "skipped": { + "description": "Steps not attempted.", + "format": "uint", + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "ok", + "failed", + "skipped" + ], + "type": "object" + }, + "ExecMode": { + "description": "Which of the two execution phases produced a result (ARCHITECTURE §8).", + "oneOf": [ + { + "const": "batch", + "description": "Phase A: one engine invocation for the whole pinned set.", + "type": "string" + }, + { + "const": "isolated", + "description": "Phase B: per-package sequential retry after Phase A failed. Skip-and-continue.", + "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" + }, + "StepResult": { + "description": "One row of the summary report (DATA-FLOW §6).", + "properties": { + "code": { + "anyOf": [ + { + "$ref": "#/$defs/Code" + }, + { + "type": "null" + } + ], + "description": "Catalog code, present exactly when `status` is `Failed`." + }, + "from": { + "anyOf": [ + { + "$ref": "#/$defs/Version" + }, + { + "type": "null" + } + ], + "description": "Version before the step, absent for a fresh install." + }, + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "status": { + "$ref": "#/$defs/StepStatus", + "description": "Whether it applied." + }, + "stderr_tail": { + "description": "Tail of the engine's stderr for the failure detail pane.", + "type": [ + "string", + "null" + ] + }, + "to": { + "anyOf": [ + { + "$ref": "#/$defs/Version" + }, + { + "type": "null" + } + ], + "description": "Version the step targeted." + } + }, + "required": [ + "pkg", + "status" + ], + "type": "object" + }, + "StepStatus": { + "description": "Outcome of a single package's step.", + "oneOf": [ + { + "const": "ok", + "description": "Applied successfully.", + "type": "string" + }, + { + "const": "failed", + "description": "Failed; carries a catalog code. Does **not** abort the batch.", + "type": "string" + }, + { + "const": "skipped", + "description": "Not attempted — user cancelled, or dropped by a Skip decision.", + "type": "string" + } + ] + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The end-of-run report shown in the summary sheet and emitted by `--json`.", + "properties": { + "check": { + "$ref": "#/$defs/CheckReport", + "description": "Post-run `engine.check()`." + }, + "counts": { + "$ref": "#/$defs/Counts", + "description": "Derived from `results`; see [`ExecutionSummary::tally`]." + }, + "phase": { + "$ref": "#/$defs/ExecMode", + "description": "Which phase produced these results." + }, + "plan_id": { + "description": "Correlates the summary with its snapshot and log ring buffer.", + "type": "string" + }, + "results": { + "default": [], + "description": "One row per package.", + "items": { + "$ref": "#/$defs/StepResult" + }, + "type": "array" + } + }, + "required": [ + "plan_id", + "phase", + "check", + "counts" + ], + "title": "ExecutionSummary", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-GuardReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-GuardReport.snap new file mode 100644 index 0000000..feead81 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-GuardReport.snap @@ -0,0 +1,47 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "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" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "What the uninstall guard found.\n\nRationale from DATA-FLOW §5: bare `pip uninstall` performs **no** dependency check at all, so\nthis is a core value-add rather than a nicety. It is computed once against the full set,\nbecause removing A and B together is fine when only B depends on A — asking per package would\nraise a warning the user cannot act on.", + "properties": { + "breaks": { + "additionalProperties": { + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + }, + "description": "For each package that has them, the installed packages that would break.", + "type": "object" + }, + "removing": { + "description": "The set the user asked to remove.", + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + }, + "with_dependents": { + "description": "The removal set expanded to include everything that depends on it, transitively — the\n\"remove dependents too\" option.", + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + } + }, + "required": [ + "removing", + "breaks", + "with_dependents" + ], + "title": "GuardReport", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Hit.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Hit.snap new file mode 100644 index 0000000..63a5c84 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Hit.snap @@ -0,0 +1,55 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "MatchKind": { + "description": "How a hit matched, in ranking order.", + "oneOf": [ + { + "const": "exact", + "description": "The query is the name.", + "type": "string" + }, + { + "const": "prefix", + "description": "The name starts with the query.", + "type": "string" + }, + { + "const": "fuzzy", + "description": "The query appears in the name, in order but not contiguously.", + "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" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "One search result.", + "properties": { + "display": { + "description": "The name as PyPI spells it, for display.", + "type": "string" + }, + "kind": { + "$ref": "#/$defs/MatchKind", + "description": "Why it ranked where it did. Exposed so the UI can group exact and prefix matches visually." + }, + "name": { + "$ref": "#/$defs/PkgName", + "description": "The normalized name, which is what every other module keys on." + } + }, + "required": [ + "name", + "display", + "kind" + ], + "title": "Hit", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-OutdatedDist.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-OutdatedDist.snap new file mode 100644 index 0000000..1a8ae26 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-OutdatedDist.snap @@ -0,0 +1,39 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "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" + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "An installed distribution with a newer release available.", + "properties": { + "current": { + "$ref": "#/$defs/Version", + "description": "Currently installed version." + }, + "latest": { + "$ref": "#/$defs/Version", + "description": "Newest version the index offers." + }, + "name": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + } + }, + "required": [ + "name", + "current", + "latest" + ], + "title": "OutdatedDist", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-PackageMeta.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-PackageMeta.snap new file mode 100644 index 0000000..6d69a89 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-PackageMeta.snap @@ -0,0 +1,54 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "Cached PyPI metadata for one package (ARCHITECTURE §5).", + "properties": { + "home_page": { + "description": "Project home page, when declared.", + "type": [ + "string", + "null" + ] + }, + "license": { + "description": "License text or identifier.", + "type": [ + "string", + "null" + ] + }, + "name": { + "description": "Normalized name.", + "type": "string" + }, + "requires_python": { + "description": "`Requires-Python` specifier.", + "type": [ + "string", + "null" + ] + }, + "summary": { + "description": "One-line description.", + "type": [ + "string", + "null" + ] + }, + "version": { + "description": "Newest release.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "name" + ], + "title": "PackageMeta", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-Pin.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-Pin.snap new file mode 100644 index 0000000..7dd96eb --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-Pin.snap @@ -0,0 +1,73 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "PinMode": { + "description": "How a pin constrains a package.", + "oneOf": [ + { + "const": "exclude", + "description": "Excluded from bulk updates. The user can still update it deliberately, one package at a\ntime — a pin is \"do not sweep this up\", not \"never touch this\".", + "type": "string" + }, + { + "additionalProperties": false, + "description": "Held at an exact version: excluded from bulk updates *and* restated at this version in\nevery plan, so the resolver treats it as fixed.", + "properties": { + "hold": { + "properties": { + "version": { + "$ref": "#/$defs/Version", + "description": "The version to hold at." + } + }, + "required": [ + "version" + ], + "type": "object" + } + }, + "required": [ + "hold" + ], + "type": "object" + } + ] + }, + "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" + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "A pin with the reason the user gave for it.", + "properties": { + "mode": { + "$ref": "#/$defs/PinMode", + "description": "How it is constrained." + }, + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "The pinned package." + }, + "reason": { + "description": "Free-text justification shown in the Pins screen.\n\nWorth storing even though nothing reads it programmatically: a pin without a reason\nbecomes a mystery the user is afraid to remove, and so stays forever.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "pkg", + "mode" + ], + "title": "Pin", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-PlanRequest.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-PlanRequest.snap new file mode 100644 index 0000000..55f36ea --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-PlanRequest.snap @@ -0,0 +1,96 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "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" + }, + "Spec": { + "description": "What the user asked for: a name, optionally constrained.", + "properties": { + "name": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "version_req": { + "description": "PEP 440 specifier such as `\">=2,<3\"`, or `None` for \"latest\".", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "name" + ], + "type": "object" + }, + "Strategy": { + "description": "How aggressively to resolve conflicts.", + "oneOf": [ + { + "const": "compatible", + "description": "Accept whatever the resolver can satisfy. The safe default; `[C]ompatible` in the CLI.", + "type": "string" + }, + { + "additionalProperties": false, + "description": "Force the latest version of the listed packages even though it violates another\npackage's requirement. The UI must name what breaks before this is selectable\n(UI-SPEC §4, DISCLAIMER §2).", + "properties": { + "force-latest": { + "properties": { + "overrides": { + "description": "Only these packages are forced; everything else stays `Compatible`.", + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + } + }, + "required": [ + "overrides" + ], + "type": "object" + } + }, + "required": [ + "force-latest" + ], + "type": "object" + } + ] + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The user's intent, before the engine has said anything about it.", + "properties": { + "installs": { + "default": [], + "description": "New packages queued in the dock bay.", + "items": { + "$ref": "#/$defs/Spec" + }, + "type": "array" + }, + "strategy": { + "$ref": "#/$defs/Strategy", + "description": "Conflict-handling strategy." + }, + "upgrades": { + "default": [], + "description": "Already-installed packages the user selected for upgrade.", + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + } + }, + "required": [ + "strategy" + ], + "title": "PlanRequest", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-PyEnv.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-PyEnv.snap new file mode 100644 index 0000000..3521fa4 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-PyEnv.snap @@ -0,0 +1,79 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "EnvSource": { + "description": "How an environment was discovered. Surfaced as the source chip in the Environments screen.", + "oneOf": [ + { + "const": "registry", + "description": "PEP 514 registry entry.", + "type": "string" + }, + { + "const": "py-launcher", + "description": "Reported by the `py` launcher (`py -0p`).", + "type": "string" + }, + { + "const": "uv", + "description": "Reported by `uv python list`.", + "type": "string" + }, + { + "const": "venv-scan", + "description": "Found by scanning known venv directories.", + "type": "string" + }, + { + "const": "manual", + "description": "Added by the user via *Browse…*.", + "type": "string" + } + ] + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "A Python environment PipDock can act on.", + "properties": { + "externally_managed": { + "description": "PEP 668 marker present. When true, mutation is blocked unless the user enabled the\nSettings override (`PD-ENV-002`, SECURITY §3).", + "type": "boolean" + }, + "hidden_user_site": { + "default": null, + "description": "User site-packages directory that `probe.py -I` is hiding, when there is one.\n\nOwner decision 2026-07-27 (SP-6): the probe keeps running isolated, so on a non-venv\nsystem Python it reports fewer distributions than `pip list` does. `Some` means packages\nreally are hidden and the Installed screen shows a note naming this path; `None` — always\nthe case inside a venv — means the listing is complete.", + "type": [ + "string", + "null" + ] + }, + "interpreter": { + "description": "Canonicalized path to the interpreter. Never a shell string — see SECURITY §2.", + "type": "string" + }, + "prefix": { + "description": "`sys.prefix` as reported by `probe.py`.", + "type": "string" + }, + "python_version": { + "description": "e.g. `\"3.12.4\"`.", + "type": "string" + }, + "source": { + "$ref": "#/$defs/EnvSource", + "description": "Where this env came from." + } + }, + "required": [ + "interpreter", + "prefix", + "python_version", + "externally_managed", + "source" + ], + "title": "PyEnv", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap new file mode 100644 index 0000000..f0563f5 --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-ResolutionReport.snap @@ -0,0 +1,191 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "Blocker": { + "description": "The package responsible for holding another one back.\n\nARCHITECTURE §3: the engine's report says *what* was held back; *who* is responsible comes from\ncross-referencing the reverse-dependency graph with each blocker's `Requires-Dist` constraint.\n**If attribution is ambiguous, show the constraint without a culprit rather than guessing.**", + "properties": { + "by": { + "anyOf": [ + { + "$ref": "#/$defs/PkgName" + }, + { + "type": "null" + } + ], + "description": "The package imposing the constraint, absent when attribution is ambiguous." + }, + "constraint": { + "description": "The constraint text, e.g. `\"requests<2.31\"`.", + "type": "string" + } + }, + "required": [ + "constraint" + ], + "type": "object" + }, + "Change": { + "description": "One line of the preview diff.", + "properties": { + "from": { + "anyOf": [ + { + "$ref": "#/$defs/Version" + }, + { + "type": "null" + } + ], + "description": "Version before, absent for a fresh install." + }, + "kind": { + "$ref": "#/$defs/ChangeKind", + "description": "Which preview section this belongs in." + }, + "name": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "to": { + "$ref": "#/$defs/Version", + "description": "Version the resolver chose." + } + }, + "required": [ + "name", + "to", + "kind" + ], + "type": "object" + }, + "ChangeKind": { + "description": "Which section of the preview a change belongs to (UI-SPEC §4).", + "oneOf": [ + { + "const": "upgrade", + "description": "An installed package moving to a newer version.", + "type": "string" + }, + { + "const": "new-dependency", + "description": "A package pulled in to satisfy something else.", + "type": "string" + }, + { + "const": "new-install", + "description": "A package the user explicitly asked to install.", + "type": "string" + }, + { + "const": "downgrade", + "description": "A package moving to an older version to satisfy a constraint.", + "type": "string" + } + ] + }, + "HeldBack": { + "description": "A package the resolver could not take all the way to `latest`.", + "properties": { + "blockers": { + "default": [], + "description": "Why it could not go further. Empty means the engine gave no attributable reason.", + "items": { + "$ref": "#/$defs/Blocker" + }, + "type": "array" + }, + "latest": { + "$ref": "#/$defs/Version", + "description": "The version the index offers." + }, + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "resolved": { + "$ref": "#/$defs/Version", + "description": "The version the resolver settled on." + } + }, + "required": [ + "pkg", + "resolved", + "latest" + ], + "type": "object" + }, + "ImpossibleDetail": { + "description": "A `ResolutionImpossible` outcome and whatever detail the engine gave (`PD-RES-001`).", + "properties": { + "explanation": { + "description": "The engine's own explanation, verbatim.", + "type": "string" + }, + "packages": { + "default": [], + "description": "Packages involved in the unsatisfiable set.", + "items": { + "$ref": "#/$defs/PkgName" + }, + "type": "array" + } + }, + "required": [ + "explanation" + ], + "type": "object" + }, + "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" + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "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": { + "changes": { + "default": [], + "description": "Everything that would change if the user confirms.", + "items": { + "$ref": "#/$defs/Change" + }, + "type": "array" + }, + "held_back": { + "default": [], + "description": "Packages that could not reach `latest`, with attribution.", + "items": { + "$ref": "#/$defs/HeldBack" + }, + "type": "array" + }, + "impossible": { + "anyOf": [ + { + "$ref": "#/$defs/ImpossibleDetail" + }, + { + "type": "null" + } + ], + "description": "Present when the whole resolution failed." + }, + "raw": { + "description": "The engine's untouched output, kept for the log and for bug reports.", + "type": "string" + } + }, + "required": [ + "raw" + ], + "title": "ResolutionReport", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-SnapshotMeta.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-SnapshotMeta.snap new file mode 100644 index 0000000..b9ff86f --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-SnapshotMeta.snap @@ -0,0 +1,117 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "EngineId": { + "description": "Which resolver PipDock is driving.", + "oneOf": [ + { + "const": "pip", + "description": "` -m pip …`", + "type": "string" + }, + { + "const": "uv", + "description": "`uv pip … --python `", + "type": "string" + } + ] + }, + "Trigger": { + "description": "What caused a snapshot to be taken. Shown as the trigger label on the timeline (UI-SPEC §4).", + "oneOf": [ + { + "additionalProperties": false, + "description": "Taken automatically before a plan executed.", + "properties": { + "plan": { + "properties": { + "plan_id": { + "description": "The plan's id, so a summary and its snapshot can be tied together.", + "type": "string" + } + }, + "required": [ + "plan_id" + ], + "type": "object" + } + }, + "required": [ + "plan" + ], + "type": "object" + }, + { + "additionalProperties": false, + "description": "Taken automatically before a rollback, because a rollback is itself reversible\n(DATA-FLOW §8).", + "properties": { + "rollback": { + "properties": { + "restoring": { + "description": "The snapshot being restored.", + "type": "string" + } + }, + "required": [ + "restoring" + ], + "type": "object" + } + }, + "required": [ + "rollback" + ], + "type": "object" + }, + { + "const": "manual", + "description": "Taken because the user asked.", + "type": "string" + } + ] + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "The `.meta.json` sidecar (ARCHITECTURE §6).", + "properties": { + "app_version": { + "description": "PipDock's version, so an old snapshot can be interpreted by a newer build.", + "type": "string" + }, + "created_at": { + "description": "When it was taken, RFC 3339.", + "type": "string" + }, + "engine": { + "$ref": "#/$defs/EngineId", + "description": "Which engine produced the freeze.\n\nLoad-bearing: pip freezes with `--all` and includes pip/setuptools, uv has no such flag and\nomits them (DATA-FLOW §7). Without this, a diff across engines would read as \"pip was\nuninstalled\"." + }, + "id": { + "description": "Snapshot id, which is also its filename stem.", + "type": "string" + }, + "package_count": { + "description": "How many distributions the freeze recorded.", + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "trigger": { + "$ref": "#/$defs/Trigger", + "description": "Why it was taken." + } + }, + "required": [ + "id", + "created_at", + "trigger", + "engine", + "package_count", + "app_version" + ], + "title": "Meta", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-StepResult.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-StepResult.snap new file mode 100644 index 0000000..ff3a35d --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-StepResult.snap @@ -0,0 +1,249 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: out +--- +{ + "$defs": { + "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": "EnvInterpreterMissing", + "description": "Interpreter path missing or not executable — the env was deleted or moved.", + "type": "string" + }, + { + "const": "EnvExternallyManaged", + "description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.", + "type": "string" + }, + { + "const": "EnvProbeFailed", + "description": "`probe.py` exited non-zero or produced unparseable output.", + "type": "string" + }, + { + "const": "EngNotFound", + "description": "pip or uv binary not found.", + "type": "string" + }, + { + "const": "EngPipTooOld", + "description": "pip older than 22.2, which predates `--dry-run --report`.", + "type": "string" + }, + { + "const": "EngUvShapeUnknown", + "description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).", + "type": "string" + }, + { + "const": "EngUnclassified", + "description": "Fallback for engine failures no classifier matched. Always last.", + "type": "string" + }, + { + "const": "ResImpossible", + "description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.", + "type": "string" + }, + { + "const": "ResPlanStale", + "description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.", + "type": "string" + }, + { + "const": "BldMsvcMissing", + "description": "MSVC build tools required but absent.", + "type": "string" + }, + { + "const": "BldBackendFailed", + "description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).", + "type": "string" + }, + { + "const": "BldWheelFailed", + "description": "Generic sdist wheel-build failure.", + "type": "string" + }, + { + "const": "PkgRequiresPython", + "description": "No matching distribution, and metadata shows a requires-python mismatch.", + "type": "string" + }, + { + "const": "PkgNotFound", + "description": "No matching distribution: name or version typo, or the release is gone.", + "type": "string" + }, + { + "const": "PkgYanked", + "description": "The requested release was yanked.", + "type": "string" + }, + { + "const": "PkgHashMismatch", + "description": "Downloaded artifact failed hash verification.", + "type": "string" + }, + { + "const": "NetUnreachable", + "description": "Timeout, connection aborted, or DNS failure.", + "type": "string" + }, + { + "const": "NetTlsFailure", + "description": "TLS/SSL verification failed — typically proxy or AV interception.", + "type": "string" + }, + { + "const": "NetIndexRefreshFailed", + "description": "PEP 691 index refresh failed; the stale index stays searchable.", + "type": "string" + }, + { + "const": "NetToolsBootstrapFailed", + "description": "Code Health tools-venv bootstrap could not reach PyPI.", + "type": "string" + }, + { + "const": "PrmSitePackagesReadOnly", + "description": "`PermissionError` writing site-packages (admin-owned Python).", + "type": "string" + }, + { + "const": "PrmFileLocked", + "description": "File locked by a running process (`WinError 32`).", + "type": "string" + }, + { + "const": "SnpWriteFailed", + "description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**", + "type": "string" + }, + { + "const": "SnpTargetUnavailable", + "description": "A release needed to restore a snapshot is no longer available on PyPI.", + "type": "string" + }, + { + "const": "SysPathTooLong", + "description": "`MAX_PATH` exceeded without the long-path opt-in.", + "type": "string" + }, + { + "const": "SysDiskFull", + "description": "Disk full.", + "type": "string" + }, + { + "const": "HltToolMissing", + "description": "A Code Health tool is missing from the tools venv.", + "type": "string" + }, + { + "const": "HltToolFailed", + "description": "A Code Health tool exited non-zero.", + "type": "string" + }, + { + "const": "HltTimeout", + "description": "A Code Health tool exceeded its watchdog timeout; partial report shown.", + "type": "string" + }, + { + "const": "IntUnexpected", + "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" + }, + "StepStatus": { + "description": "Outcome of a single package's step.", + "oneOf": [ + { + "const": "ok", + "description": "Applied successfully.", + "type": "string" + }, + { + "const": "failed", + "description": "Failed; carries a catalog code. Does **not** abort the batch.", + "type": "string" + }, + { + "const": "skipped", + "description": "Not attempted — user cancelled, or dropped by a Skip decision.", + "type": "string" + } + ] + }, + "Version": { + "description": "A version string as the engine reported it. Never reshaped or localized (I18N §2).", + "type": "string" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "One row of the summary report (DATA-FLOW §6).", + "properties": { + "code": { + "anyOf": [ + { + "$ref": "#/$defs/Code" + }, + { + "type": "null" + } + ], + "description": "Catalog code, present exactly when `status` is `Failed`." + }, + "from": { + "anyOf": [ + { + "$ref": "#/$defs/Version" + }, + { + "type": "null" + } + ], + "description": "Version before the step, absent for a fresh install." + }, + "pkg": { + "$ref": "#/$defs/PkgName", + "description": "Normalized distribution name." + }, + "status": { + "$ref": "#/$defs/StepStatus", + "description": "Whether it applied." + }, + "stderr_tail": { + "description": "Tail of the engine's stderr for the failure detail pane.", + "type": [ + "string", + "null" + ] + }, + "to": { + "anyOf": [ + { + "$ref": "#/$defs/Version" + }, + { + "type": "null" + } + ], + "description": "Version the step targeted." + } + }, + "required": [ + "pkg", + "status" + ], + "title": "StepResult", + "type": "object" +} diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap new file mode 100644 index 0000000..a56901c --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap @@ -0,0 +1,5 @@ +--- +source: crates/pipdock-cli/tests/golden.rs +expression: "stderr_of(&[\"schema\", \"NoSuchType\"])" +--- +error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, Hit, PackageMeta, Code