From 7a30e635f7607db45dd7dad6ed1c4c58feeb2d23 Mon Sep 17 00:00:00 2001 From: poli0981 <127664709+poli0981@users.noreply.github.com> Date: Mon, 27 Jul 2026 19:07:32 +0700 Subject: [PATCH] feat(core): subprocess layer and error classifiers Two pieces of M1, both of which turn a documented rule into something the code cannot forget. exec.rs is the single chokepoint for every external command. Command takes a program and a Vec and has no path that accepts a command line, so the "argv arrays, never a shell" rule of SECURITY section 2 is structural rather than a convention. Command::python() applies the SP-2 UTF-8 mitigation unconditionally, so no future call site can reintroduce the pip --report crash by forgetting it. canonical_interpreter() case- folds on Windows, which is the SP-6 finding about pins and snapshots splitting in two. The classifiers are driven by the captured corpus rather than by strings someone typed into a test, and writing that gate immediately paid for itself by failing on four real defects: - uv reports an unknown package *through* its resolver, so not-found was classified as a version conflict. That would send users hunting for a constraint problem that does not exist. - uv hard-wraps its diagnostics, so "was not found in the package\n registry" never matched as a literal. The classifier now collapses whitespace before matching, which makes every multi-word pattern wrap-proof. - pip prefixes unrelated failures with "Ignored the following yanked versions", which hijacked the Requires-Python fixture as a yank. The yank rules are removed entirely: a yank is not a failure at all, since both engines exit 0 and install the release. It is detected structurally by the plan parsers and shown as a preview warning. - Five catalog codes had no evidence of any kind. On coverage: two codes moved to the internally-raised table because that is where they genuinely belong, not to dodge the gate. PD-PKG-001 is raised by compat before an engine runs, and PD-ENV-002 is caught from probe.py's externally_managed field at step zero. The PEP 668 scenario is removed from the harness with its reasoning: the marker only applies outside a venv, deleting pyvenv.cfg to fake that just breaks the venv launcher, and planting it in a real system Python is not something a fixture script should do to a developer's machine. Two conditions that WERE reproducible are now real captures rather than guesses: PD-NET-001 via an unreachable index, and the uv phrasing for it, which needed three patterns pip does not use. The remaining eight are synthetic, each flagged, justified, and carrying what would replace it; a test enforces that labelling so they can never be mistaken for evidence of real engine behaviour. 58 tests, clippy -D warnings clean. Co-Authored-By: Claude Opus 5 --- crates/pipdock-core/src/errors/catalog.rs | 306 ++++++++++++- crates/pipdock-core/src/exec.rs | 418 ++++++++++++++++++ crates/pipdock-core/src/lib.rs | 1 + .../pipdock-core/tests/classifier_corpus.rs | 265 +++++++++++ .../pip/network-unreachable/meta.json | 31 ++ .../pip/network-unreachable/stderr.txt | 7 + .../pip/network-unreachable/stdout.txt | 0 .../fixtures/pip/requires-python/meta.json | 8 +- .../fixtures/pip/requires-python/stderr.txt | 2 +- .../fixtures/synthetic/disk-full/meta.json | 8 + .../fixtures/synthetic/disk-full/stderr.txt | 1 + .../fixtures/synthetic/file-locked/meta.json | 8 + .../fixtures/synthetic/file-locked/stderr.txt | 1 + .../synthetic/hash-mismatch/meta.json | 8 + .../synthetic/hash-mismatch/stderr.txt | 4 + .../fixtures/synthetic/msvc-missing/meta.json | 8 + .../synthetic/msvc-missing/stderr.txt | 2 + .../synthetic/path-too-long/meta.json | 8 + .../synthetic/path-too-long/stderr.txt | 1 + .../site-packages-read-only/meta.json | 8 + .../site-packages-read-only/stderr.txt | 3 + .../tls-verification-failed/meta.json | 8 + .../tls-verification-failed/stderr.txt | 2 + .../synthetic/wheel-build-failed/meta.json | 8 + .../synthetic/wheel-build-failed/stderr.txt | 5 + .../fixtures/uv/network-unreachable/meta.json | 29 ++ .../uv/network-unreachable/stderr.txt | 7 + .../uv/network-unreachable/stdout.txt | 0 .../fixtures/uv/requires-python/meta.json | 6 +- .../fixtures/uv/requires-python/stderr.txt | 4 +- spikes/capture.py | 42 +- 31 files changed, 1189 insertions(+), 20 deletions(-) create mode 100644 crates/pipdock-core/src/exec.rs create mode 100644 crates/pipdock-core/tests/classifier_corpus.rs create mode 100644 crates/pipdock-core/tests/fixtures/pip/network-unreachable/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/pip/network-unreachable/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/pip/network-unreachable/stdout.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/disk-full/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/disk-full/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/file-locked/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/file-locked/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/path-too-long/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/path-too-long/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/uv/network-unreachable/meta.json create mode 100644 crates/pipdock-core/tests/fixtures/uv/network-unreachable/stderr.txt create mode 100644 crates/pipdock-core/tests/fixtures/uv/network-unreachable/stdout.txt diff --git a/crates/pipdock-core/src/errors/catalog.rs b/crates/pipdock-core/src/errors/catalog.rs index b69e88d..2bd620d 100644 --- a/crates/pipdock-core/src/errors/catalog.rs +++ b/crates/pipdock-core/src/errors/catalog.rs @@ -240,17 +240,242 @@ impl fmt::Display for Code { } } +/// A stderr pattern and the code it implies. Order in [`CLASSIFIERS`] is priority order. +struct Classifier { + code: Code, + /// All of these substrings must be present (case-insensitively) for the rule to fire. + all_of: &'static [&'static str], +} + +/// Priority-ordered classifiers. **First match wins** (`docs/ERROR-CATALOG.md` §preamble). +/// +/// Ordering rules that matter, each learned from the SP-2 corpus: +/// +/// - Specific build failures precede the generic wheel-build failure, or every MSVC problem would +/// be reported as `PD-BLD-003`. +/// - TLS failures precede generic network failures: a certificate error also prints "Could not +/// fetch URL", and the corporate-proxy guidance is the useful one. +/// - `PD-PKG-001` is **absent by design**. pip reports a Requires-Python mismatch with the same +/// "No matching distribution found" text as an unknown name, and uv does not enforce it at all — +/// so it is raised by [`crate::compat`] before the engine runs, not classified from stderr. +static CLASSIFIERS: &[Classifier] = &[ + // -- environment --------------------------------------------------------- + Classifier { + code: Code::EnvExternallyManaged, + all_of: &["externally-managed-environment"], + }, + Classifier { + code: Code::EnvExternallyManaged, + all_of: &["externally-managed"], + }, + // -- package identity ---------------------------------------------------- + // Ahead of the resolution rules: uv reports an unknown name *through* its resolver, as + // "No solution found … because was not found in the package registry". Classified as + // a resolution failure it would send the user hunting for a version conflict that does not + // exist. + Classifier { + code: Code::PkgNotFound, + all_of: &["was not found in the package registry"], + }, + // -- resolution ---------------------------------------------------------- + Classifier { + code: Code::ResImpossible, + all_of: &["resolutionimpossible"], + }, + Classifier { + code: Code::ResImpossible, + all_of: &["conflicting dependencies"], + }, + Classifier { + code: Code::ResImpossible, + all_of: &["no solution found when resolving"], + }, + // -- build --------------------------------------------------------------- + Classifier { + code: Code::BldMsvcMissing, + all_of: &["microsoft visual c++"], + }, + Classifier { + code: Code::BldBackendFailed, + all_of: &["metadata-generation-failed"], + }, + Classifier { + code: Code::BldBackendFailed, + all_of: &["backendunavailable"], + }, + Classifier { + code: Code::BldBackendFailed, + all_of: &["the build backend returned an error"], + }, + Classifier { + code: Code::BldBackendFailed, + all_of: &["error in", "pyproject.toml"], + }, + Classifier { + code: Code::BldWheelFailed, + all_of: &["failed to build"], + }, + Classifier { + code: Code::BldWheelFailed, + all_of: &["failed building wheel"], + }, + // -- permissions --------------------------------------------------------- + // Checked before the generic OSError shapes below, which share their prefix. + Classifier { + code: Code::PrmFileLocked, + all_of: &["winerror 32"], + }, + Classifier { + code: Code::PrmSitePackagesReadOnly, + all_of: &["permissionerror"], + }, + Classifier { + code: Code::PrmSitePackagesReadOnly, + all_of: &["winerror 5"], + }, + // -- system -------------------------------------------------------------- + Classifier { + code: Code::SysDiskFull, + all_of: &["no space left on device"], + }, + Classifier { + code: Code::SysDiskFull, + all_of: &["winerror 112"], + }, + Classifier { + code: Code::SysPathTooLong, + all_of: &["path too long"], + }, + Classifier { + code: Code::SysPathTooLong, + all_of: &["filename or extension is too long"], + }, + // -- network ------------------------------------------------------------- + Classifier { + code: Code::NetTlsFailure, + all_of: &["certificate_verify_failed"], + }, + Classifier { + code: Code::NetTlsFailure, + all_of: &["sslerror"], + }, + Classifier { + code: Code::NetTlsFailure, + all_of: &["ssl certificate"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["connection aborted"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["temporary failure in name resolution"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["failed to establish a new connection"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["newconnectionerror"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["read timed out"], + }, + // uv's phrasing for the same conditions; it reports through its own HTTP stack. + Classifier { + code: Code::NetUnreachable, + all_of: &["tcp connect error"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["error sending request for url"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["failed to fetch"], + }, + Classifier { + code: Code::NetUnreachable, + all_of: &["could not fetch url"], + }, + // -- package / index ----------------------------------------------------- + Classifier { + code: Code::PkgHashMismatch, + all_of: &["do not match the hashes"], + }, + Classifier { + code: Code::PkgNotFound, + all_of: &["no matching distribution found"], + }, + Classifier { + code: Code::PkgNotFound, + all_of: &["could not find a version that satisfies"], + }, + // No `PD-PKG-003` rule. A yank is not a failure: both engines exit 0 and install the release + // (SP-2), so it is detected structurally by the plan parsers — pip's `is_yanked` field, uv's + // `warning: … is yanked` line — and shown as a preview warning. A stderr rule here also + // misfires: pip mentions "Ignored the following yanked versions" while reporting an entirely + // different failure, which classified the Requires-Python fixture as a yank. + // -- engine -------------------------------------------------------------- + Classifier { + code: Code::EngPipTooOld, + all_of: &["no such option: --report"], + }, + Classifier { + code: Code::EngNotFound, + all_of: &["no module named pip"], + }, + Classifier { + code: Code::EnvProbeFailed, + all_of: &["modulenotfounderror"], + }, +]; + /// Classify an engine's stderr into a catalog code. /// -/// Filled during spike SP-2, which captures real stderr for each case. Until then this returns -/// the documented fallback so no call site can accidentally surface an uncoded failure. +/// Patterns are checked in priority order and the **first** match wins, falling back to +/// [`Code::EngUnclassified`] (`PD-ENG-999`) so no failure can reach the user uncoded +/// (DATA-FLOW §9.4). /// -/// Contract when implemented: patterns are checked in priority order and the **first** match wins. +/// Matching is case-insensitive because the same condition is phrased differently by pip, uv and +/// the Windows CRT, and substring-based because engine messages interpolate paths and versions. +/// +/// Whitespace is collapsed first, which is not cosmetic: **uv hard-wraps its diagnostics** at a +/// fixed width, so its unknown-package message arrives as `"was not found in the package\n +/// registry"`. Matched literally, that phrase never appears and the failure is misread as a +/// version conflict, sending the user hunting for a constraint problem that does not exist. #[must_use] -pub fn classify_stderr(_stderr: &str) -> Code { +pub fn classify_stderr(stderr: &str) -> Code { + let haystack = normalize(stderr); + for rule in CLASSIFIERS { + if rule.all_of.iter().all(|needle| haystack.contains(needle)) { + return rule.code; + } + } Code::EngUnclassified } +/// Lowercase and collapse every run of whitespace to a single space, so patterns survive the +/// engines' line wrapping and CRLF. +fn normalize(text: &str) -> String { + let mut out = String::with_capacity(text.len()); + let mut in_space = false; + for ch in text.chars() { + if ch.is_whitespace() { + in_space = true; + } else { + if in_space && !out.is_empty() { + out.push(' '); + } + in_space = false; + out.extend(ch.to_lowercase()); + } + } + out +} + #[cfg(test)] mod tests { use super::*; @@ -300,4 +525,77 @@ mod tests { ); assert_eq!(Code::EngUnclassified.as_str(), "PD-ENG-999"); } + + #[test] + fn quiet_output_is_never_a_failure() { + // pip prints its upgrade notice on nearly every run and uv writes its whole plan to + // stderr, so a non-empty stderr must not imply failure. + for benign in [ + "", + " \r\n", + "[notice] A new release of pip is available: 25.0.1 -> 26.1.2", + "Resolved 3 packages in 831ms\r\nWould install 2 packages\r\n + httpcore==1.0.9", + ] { + assert_eq!(classify_stderr(benign), Code::EngUnclassified, "{benign:?}"); + } + } + + #[test] + fn patterns_survive_line_wrapping() { + // uv hard-wraps diagnostics, so a phrase can be split mid-sentence by a newline and + // indentation. Matched literally this reads as a version conflict instead of a typo. + let wrapped = " × No solution found when resolving dependencies:\r\n \ + ╰─▶ Because widget-9f3a was not found in the package\r\n \ + registry and you require widget-9f3a, we can conclude\r\n \ + that your requirements are unsatisfiable.\r\n"; + assert_eq!(classify_stderr(wrapped), Code::PkgNotFound); + } + + #[test] + fn specific_build_failures_beat_the_generic_one() { + // Both phrases appear together in a real MSVC failure; the specific one must win or the + // user gets "check the log" instead of "install the Build Tools". + let msvc = "error: Microsoft Visual C++ 14.0 or greater is required.\r\n\ + ERROR: Failed building wheel for somepkg\r\n"; + assert_eq!(classify_stderr(msvc), Code::BldMsvcMissing); + } + + #[test] + fn tls_failures_beat_generic_network_failures() { + // A certificate error also prints "Could not fetch URL"; the proxy guidance is the useful + // message, and SECURITY §4 forbids ever suggesting verification be disabled. + let tls = "SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] ...'))\r\n\ + ERROR: Could not fetch URL https://pypi.org/simple/requests/\r\n"; + assert_eq!(classify_stderr(tls), Code::NetTlsFailure); + } + + #[test] + fn a_locked_file_is_not_reported_as_a_permission_problem() { + // WinError 32 means "close the program using it", not "you lack permission" — different + // code, different advice. + let locked = "OSError: [WinError 32] The process cannot access the file because it is \ + being used by another process: 'C:\\proj\\.venv\\Lib\\site-packages\\x.pyd'"; + assert_eq!(classify_stderr(locked), Code::PrmFileLocked); + } + + #[test] + fn incidental_mentions_of_yanking_do_not_hijack_a_different_failure() { + // pip prefixes an unrelated resolution failure with "Ignored the following yanked + // versions", which a naive yank rule mis-classified as PD-PKG-003. + let stderr = "ERROR: Ignored the following yanked versions: 1.11.0, 1.14.0rc1\r\n\ + ERROR: No matching distribution found for scipy==1.7.3\r\n"; + assert_eq!(classify_stderr(stderr), Code::PkgNotFound); + } + + #[test] + fn classifiers_never_yield_a_code_outside_the_catalog() { + let all: HashSet<&str> = Code::ALL.iter().map(|c| c.as_str()).collect(); + for rule in CLASSIFIERS { + assert!( + all.contains(rule.code.as_str()), + "{} is not in Code::ALL", + rule.code + ); + } + } } diff --git a/crates/pipdock-core/src/exec.rs b/crates/pipdock-core/src/exec.rs new file mode 100644 index 0000000..8aa88b3 --- /dev/null +++ b/crates/pipdock-core/src/exec.rs @@ -0,0 +1,418 @@ +//! Subprocess execution — the single chokepoint for every external command. +//! +//! Two invariants live here rather than in the callers, so they cannot be forgotten one call site +//! at a time: +//! +//! 1. **argv arrays, never a shell** (SECURITY §2). [`Command`] takes a program and a `Vec` +//! and has no path that accepts a command line, so quoting and injection classes are +//! structurally absent. +//! 2. **pip always runs with UTF-8 stdio** (spike SP-2). `pip install --dry-run --report -` +//! crashes with `UnicodeEncodeError` on Windows under cp1252 — confirmed on pip 25.0.1 and +//! 26.1.2 — because pip writes the report through its vendored `rich` and the legacy Windows +//! console codec. It is data-dependent: an all-ASCII report succeeds, so this would pass +//! testing and fail on users' machines. [`Command::python`] sets the mitigation unconditionally. + +use std::collections::HashMap; +use std::path::{Path, PathBuf}; +use std::process::Stdio; +use std::time::Duration; + +use tokio::io::{AsyncBufReadExt, BufReader}; +use tokio::process::Command as TokioCommand; + +use crate::engine::{EventSink, ProgressEvent}; +use crate::errors::{Code, PdError, Result}; +use crate::model::{ExecMode, PkgName}; + +/// Default watchdog. Long resolves on a big environment are normal; hangs are not. +pub const DEFAULT_TIMEOUT: Duration = Duration::from_secs(600); + +/// What a finished command produced. +#[derive(Debug, Clone)] +pub struct Output { + /// Exit status, `None` if the process was killed by a signal or the watchdog. + pub code: Option, + /// Captured stdout. + pub stdout: String, + /// Captured stderr. For uv this carries the **plan**, not just errors (SP-1). + pub stderr: String, +} + +impl Output { + /// True when the process exited zero. + #[must_use] + pub fn ok(&self) -> bool { + self.code == Some(0) + } + + /// Turn a non-zero exit into a classified [`PdError`]. + /// + /// # Errors + /// Always returns an error; call only after checking [`Output::ok`]. + pub fn into_error(self) -> PdError { + PdError::from_engine_stderr(&self.stderr) + } +} + +/// A subprocess invocation. +/// +/// Deliberately minimal: there is no `arg_line`, no shell, and no way to pass a string that gets +/// split. If you find yourself wanting one, the answer is another `arg()`. +#[derive(Debug, Clone)] +pub struct Command { + program: PathBuf, + args: Vec, + cwd: Option, + env: HashMap, + timeout: Duration, +} + +impl Command { + /// Invoke an arbitrary program. + #[must_use] + pub fn new(program: impl Into) -> Self { + Self { + program: program.into(), + args: Vec::new(), + cwd: None, + env: HashMap::new(), + timeout: DEFAULT_TIMEOUT, + } + } + + /// Invoke a Python interpreter with the SP-2 encoding mitigation already applied. + /// + /// Use this for **every** `python -m pip …` and `probe.py` call. `PYTHONUTF8=1` covers the + /// interpreter's own text handling and `PYTHONIOENCODING=utf-8` covers the stdio streams pip's + /// vendored `rich` writes through. + #[must_use] + pub fn python(interpreter: impl Into) -> Self { + Self::new(interpreter) + .env("PYTHONIOENCODING", "utf-8") + .env("PYTHONUTF8", "1") + } + + /// Append one argument. One call, one argv entry — never a space-separated string. + #[must_use] + pub fn arg(mut self, arg: impl Into) -> Self { + self.args.push(arg.into()); + self + } + + /// Append several arguments. + #[must_use] + pub fn args(mut self, args: I) -> Self + where + I: IntoIterator, + S: Into, + { + self.args.extend(args.into_iter().map(Into::into)); + self + } + + /// Set the working directory. Code Health runs its tools with the project folder as CWD. + #[must_use] + pub fn cwd(mut self, dir: impl Into) -> Self { + self.cwd = Some(dir.into()); + self + } + + /// Set an environment variable for the child. + #[must_use] + pub fn env(mut self, key: impl Into, value: impl Into) -> Self { + self.env.insert(key.into(), value.into()); + self + } + + /// Override the watchdog. + #[must_use] + pub fn timeout(mut self, timeout: Duration) -> Self { + self.timeout = timeout; + self + } + + /// The argv this command would run, for logging and for the bug-report ring buffer. + #[must_use] + pub fn argv(&self) -> Vec { + let mut out = vec![self.program.display().to_string()]; + out.extend(self.args.iter().cloned()); + out + } + + fn build(&self) -> TokioCommand { + let mut cmd = TokioCommand::new(&self.program); + cmd.args(&self.args); + if let Some(dir) = &self.cwd { + cmd.current_dir(dir); + } + for (k, v) in &self.env { + cmd.env(k, v); + } + cmd.stdin(Stdio::null()); + cmd.stdout(Stdio::piped()); + cmd.stderr(Stdio::piped()); + #[cfg(windows)] + { + // Do not flash a console window when the GUI spawns an engine. + const CREATE_NO_WINDOW: u32 = 0x0800_0000; + cmd.creation_flags(CREATE_NO_WINDOW); + } + cmd + } + + /// Run to completion, capturing output. + /// + /// # Errors + /// `PD-ENG-001` when the program cannot be spawned, `PD-INT-001` when the watchdog fires. + pub async fn run(&self) -> Result { + let child = self.build().output(); + let out = tokio::time::timeout(self.timeout, child) + .await + .map_err(|_| { + PdError::new( + Code::IntUnexpected, + format!( + "timed out after {:?}: {}", + self.timeout, + self.program.display() + ), + ) + })?; + let out = out.map_err(|e| { + PdError::new( + Code::EngNotFound, + format!("could not run {}: {e}", self.program.display()), + ) + })?; + Ok(Output { + code: out.status.code(), + stdout: String::from_utf8_lossy(&out.stdout).into_owned(), + stderr: String::from_utf8_lossy(&out.stderr).into_owned(), + }) + } + + /// Run while streaming each output line to `sink`, for the live console drawer. + /// + /// Output is still captured and returned, because the parsers need the whole document and the + /// bug-report ring buffer needs the tail. + /// + /// # Errors + /// As [`Command::run`]. + pub async fn run_streaming( + &self, + sink: &EventSink, + step: usize, + pkg: Option, + phase: ExecMode, + ) -> Result { + let mut child = self.build().spawn().map_err(|e| { + PdError::new( + Code::EngNotFound, + format!("could not run {}: {e}", self.program.display()), + ) + })?; + + let stdout = child.stdout.take(); + let stderr = child.stderr.take(); + + let pump = |reader: Option| { + let sink = sink.clone(); + let pkg = pkg.clone(); + async move { + let mut buf = String::new(); + if let Some(r) = reader { + let mut lines = BufReader::new(r).lines(); + while let Ok(Some(line)) = lines.next_line().await { + // Send failure means the UI stopped listening; keep capturing regardless + // so the summary and the log are still complete. + let _ = sink.send(ProgressEvent { + step, + pkg: pkg.clone(), + phase, + line: line.clone(), + }); + buf.push_str(&line); + buf.push('\n'); + } + } + buf + } + }; + let pump_err = |reader: Option| { + let sink = sink.clone(); + let pkg = pkg.clone(); + async move { + let mut buf = String::new(); + if let Some(r) = reader { + let mut lines = BufReader::new(r).lines(); + while let Ok(Some(line)) = lines.next_line().await { + let _ = sink.send(ProgressEvent { + step, + pkg: pkg.clone(), + phase, + line: line.clone(), + }); + buf.push_str(&line); + buf.push('\n'); + } + } + buf + } + }; + + let run = async { + let (out, err, status) = tokio::join!(pump(stdout), pump_err(stderr), child.wait()); + (out, err, status) + }; + + let (stdout, stderr, status) = + tokio::time::timeout(self.timeout, run).await.map_err(|_| { + PdError::new( + Code::IntUnexpected, + format!( + "timed out after {:?}: {}", + self.timeout, + self.program.display() + ), + ) + })?; + + let status = status.map_err(|e| { + PdError::new(Code::IntUnexpected, format!("waiting on child failed: {e}")) + })?; + + Ok(Output { + code: status.code(), + stdout, + stderr, + }) + } +} + +/// Write `contents` to a uniquely named temp file and return its path. +/// +/// SECURITY §2: `probe.py` is written with a random name per invocation and never installed into +/// the environment. The caller removes it; a leaked file in the temp directory is harmless, an +/// overwritten one would not be. +/// +/// # Errors +/// `PD-SYS-002` when the file cannot be written. +pub fn write_temp(prefix: &str, extension: &str, contents: &str) -> Result { + use std::hash::{BuildHasher as _, RandomState}; + + let dir = std::env::temp_dir(); + // RandomState is seeded by the OS per process; hashing a fresh allocation's address plus a + // counter gives a unique-enough name without pulling in a rand dependency. + let nonce = RandomState::new().hash_one(std::time::Instant::now().elapsed().as_nanos()); + let path = dir.join(format!("{prefix}-{nonce:016x}.{extension}")); + std::fs::write(&path, contents).map_err(|e| { + PdError::new( + Code::SysDiskFull, + format!("could not write {}: {e}", path.display()), + ) + })?; + Ok(path) +} + +/// Canonicalize an interpreter path for identity purposes. +/// +/// **Spike SP-6.** The same interpreter reports different casing depending on how it was launched +/// — a Chocolatey shim yields `c:\python314\python.exe` where the direct install yields +/// `C:\Python314\python.exe`. `env_hash` is derived from this string (ARCHITECTURE §6), so without +/// case folding one environment would silently split its pins and snapshot history in two. +#[must_use] +pub fn canonical_interpreter(path: &Path) -> String { + let resolved = std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf()); + let text = resolved.display().to_string(); + // Strip the Windows verbatim prefix canonicalize() adds; it is noise in logs and in the hash. + let text = text.strip_prefix(r"\\?\").unwrap_or(&text).to_owned(); + if cfg!(windows) { + text.to_lowercase() + } else { + text + } +} + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn argv_is_one_token_per_argument() { + let cmd = Command::new("python.exe") + .arg("-m") + .arg("pip") + .args(["install", "requests==2.32.3"]); + assert_eq!( + cmd.argv(), + ["python.exe", "-m", "pip", "install", "requests==2.32.3"] + ); + } + + #[test] + fn a_path_with_spaces_stays_a_single_argument() { + // There is no quoting step to get wrong, because there is no command line. + let cmd = Command::new(r"C:\Program Files\Python312\python.exe").arg("--version"); + assert_eq!(cmd.argv()[0], r"C:\Program Files\Python312\python.exe"); + assert_eq!(cmd.argv().len(), 2); + } + + #[test] + fn python_commands_carry_the_sp2_encoding_mitigation() { + // Without these, `pip install --dry-run --report -` crashes on Windows/cp1252. + let cmd = Command::python("python.exe"); + assert_eq!( + cmd.env.get("PYTHONIOENCODING").map(String::as_str), + Some("utf-8") + ); + assert_eq!(cmd.env.get("PYTHONUTF8").map(String::as_str), Some("1")); + } + + #[tokio::test] + async fn runs_a_real_process_and_captures_output() { + let cmd = Command::new(std::env::var("COMSPEC").unwrap_or_else(|_| "cmd.exe".into())) + .args(["/C", "echo", "pipdock"]); + let out = cmd.run().await.expect("cmd.exe should run on Windows"); + assert!(out.ok(), "exit {:?}", out.code); + assert!( + out.stdout.contains("pipdock"), + "stdout was {:?}", + out.stdout + ); + } + + #[tokio::test] + async fn a_missing_program_is_an_engine_error() { + let err = Command::new("pipdock-definitely-not-a-real-binary") + .run() + .await + .expect_err("missing program must fail"); + assert_eq!(err.code, Code::EngNotFound); + } + + #[test] + fn temp_files_get_unique_names() { + let a = write_temp("pd-test", "txt", "a").expect("write"); + let b = write_temp("pd-test", "txt", "b").expect("write"); + assert_ne!(a, b, "two probe writes must not collide"); + let _ = std::fs::remove_file(a); + let _ = std::fs::remove_file(b); + } + + #[test] + fn interpreter_identity_is_case_folded_on_windows() { + // SP-6: the Chocolatey shim and the direct install differ only in casing, and env_hash is + // built from this string. + let a = canonical_interpreter(Path::new(r"C:\Python314\python.exe")); + let b = canonical_interpreter(Path::new(r"c:\python314\python.exe")); + if cfg!(windows) { + assert_eq!(a, b, "casing must not produce two identities"); + } + } + + #[test] + fn canonical_paths_have_no_verbatim_prefix() { + let p = canonical_interpreter(Path::new(".")); + assert!(!p.starts_with(r"\\?\"), "got {p}"); + } +} diff --git a/crates/pipdock-core/src/lib.rs b/crates/pipdock-core/src/lib.rs index e069bed..fd841be 100644 --- a/crates/pipdock-core/src/lib.rs +++ b/crates/pipdock-core/src/lib.rs @@ -27,6 +27,7 @@ pub mod compat; pub mod engine; pub mod envs; pub mod errors; +pub mod exec; pub mod graph; pub mod health; pub mod index; diff --git a/crates/pipdock-core/tests/classifier_corpus.rs b/crates/pipdock-core/tests/classifier_corpus.rs new file mode 100644 index 0000000..94fc770 --- /dev/null +++ b/crates/pipdock-core/tests/classifier_corpus.rs @@ -0,0 +1,265 @@ +//! The error-catalog corpus gate. +//! +//! `docs/TESTING.md` §2: *"every catalog code has ≥ 1 stderr fixture; a test enforces 'no code +//! without fixture'"*. This is that test, run against the fixtures spike SP-2 captured plus the +//! labelled synthetic ones for conditions the dev machine cannot produce. +//! +//! It does two jobs a unit test cannot: it proves the classifiers fire on **real engine output** +//! rather than on strings someone typed into a test, and it fails when a new `Code` variant is +//! added without evidence of what it looks like in the wild. + +// Integration tests are their own crate, so the lib's test-only allow does not reach them. +#![allow(clippy::unwrap_used, clippy::expect_used)] + +use std::collections::{BTreeMap, BTreeSet}; +use std::fs; +use std::path::{Path, PathBuf}; + +use pipdock_core::errors::{Code, classify_stderr}; + +fn fixtures_root() -> PathBuf { + Path::new(env!("CARGO_MANIFEST_DIR")).join("tests/fixtures") +} + +/// One fixture directory: what it expects, and what the engine actually wrote. +struct Fixture { + label: String, + expects: Option, + stderr: String, + synthetic: bool, +} + +fn load_all() -> Vec { + let mut out = Vec::new(); + let root = fixtures_root(); + for engine in ["pip", "uv", "synthetic"] { + let dir = root.join(engine); + let Ok(entries) = fs::read_dir(&dir) else { + continue; + }; + for entry in entries.flatten() { + let path = entry.path(); + if !path.is_dir() { + continue; + } + let meta_path = path.join("meta.json"); + let Ok(meta_raw) = fs::read_to_string(&meta_path) else { + continue; + }; + let meta: serde_json::Value = + serde_json::from_str(&meta_raw).unwrap_or_else(|e| panic!("{meta_path:?}: {e}")); + let stderr = fs::read_to_string(path.join("stderr.txt")).unwrap_or_default(); + out.push(Fixture { + label: format!( + "{engine}/{}", + path.file_name().unwrap_or_default().display() + ), + expects: meta["expects_code"].as_str().map(str::to_owned), + stderr, + synthetic: meta["synthetic"].as_bool().unwrap_or(false), + }); + } + } + assert!( + !out.is_empty(), + "no fixtures found under {:?}", + fixtures_root() + ); + out +} + +#[test] +fn every_fixture_with_an_expected_code_classifies_to_it() { + let mut failures = Vec::new(); + for f in load_all() { + let Some(expected) = &f.expects else { continue }; + // Yanked releases exit 0 in both engines and are a preview warning, not a failure + // (SP-2), so the classifier is not the component responsible for them. + if expected == "PD-PKG-003" { + continue; + } + let got = classify_stderr(&f.stderr); + if got.as_str() != expected { + failures.push(format!("{}: expected {expected}, got {got}", f.label)); + } + } + assert!( + failures.is_empty(), + "classifier mismatches:\n {}", + failures.join("\n ") + ); +} + +#[test] +fn no_code_without_a_fixture() { + // The gate TESTING §2 asks for: adding a Code variant without evidence fails CI. + let fixtures = load_all(); + + // A code is covered when some fixture names it, or when a fixture's stderr classifies to it. + let mut covered: BTreeSet<&'static str> = BTreeSet::new(); + for f in &fixtures { + if let Some(code) = f + .expects + .as_ref() + .and_then(|expected| Code::ALL.iter().find(|c| c.as_str() == expected)) + { + covered.insert(code.as_str()); + } + let got = classify_stderr(&f.stderr); + if got != Code::EngUnclassified { + covered.insert(got.as_str()); + } + } + + // Codes PipDock raises itself, which by definition have no engine stderr to capture. Each + // names the module that owns it, so this list stays honest rather than becoming a dumping + // ground for anything inconvenient. + let internally_raised: BTreeMap<&str, &str> = BTreeMap::from([ + ( + "PD-ENV-001", + "envs: interpreter path missing before any command runs", + ), + // PEP 668 applies only outside a venv, so it cannot be reproduced without planting the + // marker in a real system Python. It does not need to be: probe.py reports + // `externally_managed` and the environment is blocked at step zero (DATA-FLOW §2), before + // any engine runs. The classifier rule is a backstop for the Settings override path. + ( + "PD-ENV-002", + "envs: PEP 668 marker seen by probe.py before any engine command", + ), + ("PD-ENV-003", "envs: probe.py output unreadable"), + ("PD-ENG-001", "exec: the engine binary could not be spawned"), + ( + "PD-ENG-002", + "engine: pip version below the 22.2 report floor", + ), + ( + "PD-ENG-003", + "engine::uv: plan text did not match any known shape", + ), + ( + "PD-RES-002", + "plan: report older than PLAN_MAX_AGE or env drifted", + ), + ( + "PD-PKG-001", + "compat: Requires-Python enforced by PipDock, not by the engine", + ), + ( + "PD-PKG-003", + "engine: yanked releases exit 0; surfaced as a preview warning", + ), + ("PD-NET-010", "index: PEP 691 refresh failed"), + ( + "PD-NET-011", + "health: tools venv bootstrap could not reach PyPI", + ), + ("PD-SNP-001", "snapshot: write failed pre-execution"), + ( + "PD-SNP-002", + "snapshot: rollback target unavailable upstream", + ), + ("PD-HLT-001", "health: tool missing from the tools venv"), + ("PD-HLT-002", "health: tool exited non-zero"), + ("PD-HLT-003", "health: tool exceeded its watchdog"), + ("PD-INT-001", "anywhere: a PipDock bug"), + ("PD-ENG-999", "the fallback itself"), + ]); + + let missing: Vec<&str> = Code::ALL + .iter() + .map(|c| c.as_str()) + .filter(|c| !covered.contains(c) && !internally_raised.contains_key(c)) + .collect(); + + assert!( + missing.is_empty(), + "these codes have no fixture and are not listed as internally raised: {missing:?}\n\ + Capture one with `py -3.12 spikes/capture.py`, or add it to the internally_raised table \ + with the module that owns it." + ); +} + +#[test] +fn synthetic_fixtures_are_labelled_and_justified() { + // Synthetic fixtures are a stopgap for conditions this machine cannot produce (SP-2). They + // must stay obviously distinguishable from captures so nobody treats them as evidence of real + // engine behaviour, and each must say what would replace it. + let root = fixtures_root().join("synthetic"); + let entries = fs::read_dir(&root).unwrap_or_else(|e| panic!("{root:?}: {e}")); + let mut count = 0; + for entry in entries.flatten() { + let meta_path = entry.path().join("meta.json"); + let Ok(raw) = fs::read_to_string(&meta_path) else { + continue; + }; + let meta: serde_json::Value = serde_json::from_str(&raw).expect("valid meta.json"); + assert_eq!( + meta["synthetic"].as_bool(), + Some(true), + "{meta_path:?} must be flagged" + ); + assert!( + meta["why"].is_string(), + "{meta_path:?} must say why it is synthetic" + ); + assert!( + meta["replace_with"].is_string(), + "{meta_path:?} must say what replaces it" + ); + count += 1; + } + assert_eq!( + count, 8, + "expected exactly the eight documented unreproducible conditions" + ); +} + +#[test] +fn real_captures_are_not_silently_synthetic() { + for f in load_all() { + if f.label.starts_with("synthetic/") { + assert!(f.synthetic, "{} must be flagged synthetic", f.label); + } else { + assert!( + !f.synthetic, + "{} is a capture and must not be flagged synthetic", + f.label + ); + } + } +} + +#[test] +fn successful_runs_are_never_classified_as_failures() { + // pip prints its own upgrade notice to stderr on almost every run, and uv writes its entire + // plan there (SP-1). Treating a non-empty stderr as failure would break both engines, so the + // classifier must stay quiet on output from commands that exited zero. + for f in load_all() { + if f.expects.is_some() || f.label.starts_with("synthetic/") { + continue; + } + let got = classify_stderr(&f.stderr); + assert_eq!( + got, + Code::EngUnclassified, + "{}: successful run classified as {got}\n--- stderr ---\n{}", + f.label, + f.stderr + ); + } +} + +#[test] +fn crlf_in_fixtures_is_preserved() { + // .gitattributes marks the fixture tree -text so Windows line endings survive. If that + // regressed, the parsers would be tested against endings that never occur in production. + let with_crlf = load_all() + .iter() + .filter(|f| f.stderr.contains("\r\n")) + .count(); + assert!( + with_crlf > 0, + "no fixture retained CRLF — check .gitattributes" + ); +} diff --git a/crates/pipdock-core/tests/fixtures/pip/network-unreachable/meta.json b/crates/pipdock-core/tests/fixtures/pip/network-unreachable/meta.json new file mode 100644 index 0000000..5b98080 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/pip/network-unreachable/meta.json @@ -0,0 +1,31 @@ +{ + "scenario": "network-unreachable", + "question": "Index unreachable \u2014 connection refused rather than DNS or TLS failure.", + "expects_code": "PD-NET-001", + "engine": "pip", + "engine_version": "pip 25.0.1 from C:\\Users\\Anon\\AppData\\Local\\Temp\\pd-pip-network-unreachable-brhd_kqy\\venv\\Lib\\site-packages\\pip (python 3.12)", + "python": "Python 3.12.10", + "argv": [ + "\\pd-pip-network-unreachable-brhd_kqy\\venv\\Scripts\\python.exe", + "-m", + "pip", + "install", + "-U", + "--dry-run", + "--quiet", + "--report", + "-", + "--index-url", + "http://127.0.0.1:1/simple", + "idna" + ], + "extra_env": { + "PYTHONIOENCODING": "utf-8", + "PYTHONUTF8": "1" + }, + "exit_code": 1, + "seed": [], + "seed_exit_code": null, + "stdout_bytes": 0, + "stderr_bytes": 1947 +} diff --git a/crates/pipdock-core/tests/fixtures/pip/network-unreachable/stderr.txt b/crates/pipdock-core/tests/fixtures/pip/network-unreachable/stderr.txt new file mode 100644 index 0000000..a2b8ba4 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/pip/network-unreachable/stderr.txt @@ -0,0 +1,7 @@ +WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(': Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it')': /simple/idna/ +WARNING: Retrying (Retry(total=3, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(': Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it')': /simple/idna/ +WARNING: Retrying (Retry(total=2, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(': Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it')': /simple/idna/ +WARNING: Retrying (Retry(total=1, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(': Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it')': /simple/idna/ +WARNING: Retrying (Retry(total=0, connect=None, read=None, redirect=None, status=None)) after connection broken by 'NewConnectionError(': Failed to establish a new connection: [WinError 10061] No connection could be made because the target machine actively refused it')': /simple/idna/ +ERROR: Could not find a version that satisfies the requirement idna (from versions: none) +ERROR: No matching distribution found for idna diff --git a/crates/pipdock-core/tests/fixtures/pip/network-unreachable/stdout.txt b/crates/pipdock-core/tests/fixtures/pip/network-unreachable/stdout.txt new file mode 100644 index 0000000..e69de29 diff --git a/crates/pipdock-core/tests/fixtures/pip/requires-python/meta.json b/crates/pipdock-core/tests/fixtures/pip/requires-python/meta.json index a25108b..00e1816 100644 --- a/crates/pipdock-core/tests/fixtures/pip/requires-python/meta.json +++ b/crates/pipdock-core/tests/fixtures/pip/requires-python/meta.json @@ -1,12 +1,12 @@ { "scenario": "requires-python", - "question": "Requires-Python mismatch against the running interpreter.", - "expects_code": "PD-PKG-001", + "question": "Requires-Python mismatch against the running interpreter. ANSWER: pip refuses with the same 'No matching distribution found' text it uses for an unknown name, so the two are indistinguishable from stderr; uv ignores the constraint and plans the install. Hence PD-PKG-001 is raised by pipdock-core's compat module before either engine runs, and these fixtures record what the engines do instead.", + "expects_code": "PD-PKG-002", "engine": "pip", - "engine_version": "pip 25.0.1 from C:\\Users\\Anon\\AppData\\Local\\Temp\\pd-pip-requires-python-j_rytfff\\venv\\Lib\\site-packages\\pip (python 3.12)", + "engine_version": "pip 25.0.1 from C:\\Users\\Anon\\AppData\\Local\\Temp\\pd-pip-requires-python-ez076pnc\\venv\\Lib\\site-packages\\pip (python 3.12)", "python": "Python 3.12.10", "argv": [ - "\\pd-pip-requires-python-j_rytfff\\venv\\Scripts\\python.exe", + "\\pd-pip-requires-python-ez076pnc\\venv\\Scripts\\python.exe", "-m", "pip", "install", diff --git a/crates/pipdock-core/tests/fixtures/pip/requires-python/stderr.txt b/crates/pipdock-core/tests/fixtures/pip/requires-python/stderr.txt index 8e130cd..accfed2 100644 --- a/crates/pipdock-core/tests/fixtures/pip/requires-python/stderr.txt +++ b/crates/pipdock-core/tests/fixtures/pip/requires-python/stderr.txt @@ -2,5 +2,5 @@ ERROR: Ignored the following yanked versions: 1.11.0, 1.14.0rc1 ERROR: Could not find a version that satisfies the requirement scipy==1.7.3 (from versions: 0.8.0, 0.9.0, 0.10.0, 0.10.1, 0.11.0, 0.12.0, 0.12.1, 0.13.0, 0.13.1, 0.13.2, 0.13.3, 0.14.0, 0.14.1, 0.15.0, 0.15.1, 0.16.0, 0.16.1, 0.17.0, 0.17.1, 0.18.0, 0.18.1, 0.19.0, 0.19.1, 1.0.0, 1.0.1, 1.1.0, 1.2.0, 1.2.1, 1.2.2, 1.2.3, 1.3.0, 1.3.1, 1.3.2, 1.3.3, 1.4.0, 1.4.1, 1.5.0, 1.5.1, 1.5.2, 1.5.3, 1.5.4, 1.6.0, 1.6.1, 1.9.2, 1.9.3, 1.11.0rc1, 1.11.0rc2, 1.11.1, 1.11.2, 1.11.3, 1.11.4, 1.12.0rc1, 1.12.0rc2, 1.12.0, 1.13.0rc1, 1.13.0, 1.13.1, 1.14.0rc2, 1.14.0, 1.14.1, 1.15.0rc1, 1.15.0rc2, 1.15.0, 1.15.1, 1.15.2, 1.15.3, 1.16.0rc1, 1.16.0rc2, 1.16.0, 1.16.1, 1.16.2, 1.16.3, 1.17.0rc1, 1.17.0rc2, 1.17.0, 1.17.1, 1.18.0rc1, 1.18.0rc2, 1.18.0) [notice] A new release of pip is available: 25.0.1 -> 26.1.2 -[notice] To update, run: C:\Users\Anon\AppData\Local\Temp\pd-pip-requires-python-j_rytfff\venv\Scripts\python.exe -m pip install --upgrade pip +[notice] To update, run: C:\Users\Anon\AppData\Local\Temp\pd-pip-requires-python-ez076pnc\venv\Scripts\python.exe -m pip install --upgrade pip ERROR: No matching distribution found for scipy==1.7.3 diff --git a/crates/pipdock-core/tests/fixtures/synthetic/disk-full/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/disk-full/meta.json new file mode 100644 index 0000000..24903bd --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/disk-full/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "disk-full", + "expects_code": "PD-SYS-002", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/disk-full/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/disk-full/stderr.txt new file mode 100644 index 0000000..b322f76 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/disk-full/stderr.txt @@ -0,0 +1 @@ +ERROR: Could not install packages due to an OSError: [Errno 28] No space left on device diff --git a/crates/pipdock-core/tests/fixtures/synthetic/file-locked/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/file-locked/meta.json new file mode 100644 index 0000000..7002940 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/file-locked/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "file-locked", + "expects_code": "PD-PRM-002", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/file-locked/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/file-locked/stderr.txt new file mode 100644 index 0000000..849d332 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/file-locked/stderr.txt @@ -0,0 +1 @@ +ERROR: Could not install packages due to an OSError: [WinError 32] The process cannot access the file because it is being used by another process: 'C:\proj\.venv\Lib\site-packages\_cffi_backend.cp312-win_amd64.pyd' diff --git a/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/meta.json new file mode 100644 index 0000000..3ad9905 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "hash-mismatch", + "expects_code": "PD-PKG-004", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/stderr.txt new file mode 100644 index 0000000..cee7444 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/hash-mismatch/stderr.txt @@ -0,0 +1,4 @@ +ERROR: THESE PACKAGES DO NOT MATCH THE HASHES FROM THE REQUIREMENTS FILE. If you have updated the package versions, please update the hashes. Otherwise, examine the package contents carefully; someone may have tampered with them. + somepkg==1.2.3 from https://files.pythonhosted.org/packages/ab/cd/somepkg-1.2.3-py3-none-any.whl: + Expected sha256 0000000000000000000000000000000000000000000000000000000000000000 + Got 1111111111111111111111111111111111111111111111111111111111111111 diff --git a/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/meta.json new file mode 100644 index 0000000..00b793c --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "msvc-missing", + "expects_code": "PD-BLD-001", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/stderr.txt new file mode 100644 index 0000000..73bb9f3 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/msvc-missing/stderr.txt @@ -0,0 +1,2 @@ + error: Microsoft Visual C++ 14.0 or greater is required. Get it with "Microsoft C++ Build Tools": https://visualstudio.microsoft.com/visual-cpp-build-tools/ + ERROR: Failed building wheel for somepkg diff --git a/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/meta.json new file mode 100644 index 0000000..c0946db --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "path-too-long", + "expects_code": "PD-SYS-001", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/stderr.txt new file mode 100644 index 0000000..03911c1 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/path-too-long/stderr.txt @@ -0,0 +1 @@ +ERROR: Could not install packages due to an OSError: [Errno 2] No such file or directory: 'C:\proj\.venv\Lib\site-packages\averyveryverylongpackagename\...' path too long for the current system configuration diff --git a/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/meta.json new file mode 100644 index 0000000..cca3cd3 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "site-packages-read-only", + "expects_code": "PD-PRM-001", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/stderr.txt new file mode 100644 index 0000000..cf11827 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/site-packages-read-only/stderr.txt @@ -0,0 +1,3 @@ +ERROR: Could not install packages due to an OSError: [Errno 13] Permission denied: 'C:\Program Files\Python312\Lib\site-packages\idna' +Consider using the `--user` option or check the permissions. +PermissionError: [WinError 5] Access is denied diff --git a/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/meta.json new file mode 100644 index 0000000..3e7898c --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "tls-verification-failed", + "expects_code": "PD-NET-002", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/stderr.txt new file mode 100644 index 0000000..03bf97a --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/tls-verification-failed/stderr.txt @@ -0,0 +1,2 @@ +WARNING: Retrying (Retry(total=4, connect=None, read=None, redirect=None, status=None)) after connection broken by 'SSLError(SSLCertVerificationError(1, '[SSL: CERTIFICATE_VERIFY_FAILED] certificate verify failed: unable to get local issuer certificate (_ssl.c:1000)'))': /simple/requests/ +ERROR: Could not fetch URL https://pypi.org/simple/requests/: There was a problem confirming the ssl certificate diff --git a/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/meta.json b/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/meta.json new file mode 100644 index 0000000..dc7c00b --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/meta.json @@ -0,0 +1,8 @@ +{ + "scenario": "wheel-build-failed", + "expects_code": "PD-BLD-003", + "synthetic": true, + "why": "This machine cannot produce the condition; see spikes/README.md SP-2.", + "source": "hand-written from the documented vendor message", + "replace_with": "a real capture from the first bug report carrying this code" +} diff --git a/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/stderr.txt b/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/stderr.txt new file mode 100644 index 0000000..602b75d --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/synthetic/wheel-build-failed/stderr.txt @@ -0,0 +1,5 @@ + running build_ext + building 'somepkg._speedups' extension + error: command 'cl.exe' failed: None + ERROR: Failed building wheel for somepkg +ERROR: Failed to build installable wheels for some pyproject.toml based projects (somepkg) diff --git a/crates/pipdock-core/tests/fixtures/uv/network-unreachable/meta.json b/crates/pipdock-core/tests/fixtures/uv/network-unreachable/meta.json new file mode 100644 index 0000000..d522f99 --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/uv/network-unreachable/meta.json @@ -0,0 +1,29 @@ +{ + "scenario": "network-unreachable", + "question": "Index unreachable \u2014 connection refused rather than DNS or TLS failure.", + "expects_code": "PD-NET-001", + "engine": "uv", + "engine_version": "uv 0.11.32 (3010295ae 2026-07-23 x86_64-pc-windows-msvc)", + "python": "Python 3.12.10", + "argv": [ + "spikes\\.venv-uv-latest\\Scripts\\uv.exe", + "pip", + "install", + "-U", + "--dry-run", + "--index-url", + "http://127.0.0.1:1/simple", + "idna", + "--python", + "\\pd-uv-network-unreachable-ba6imiic\\venv\\Scripts\\python.exe" + ], + "extra_env": { + "PYTHONIOENCODING": "utf-8", + "PYTHONUTF8": "1" + }, + "exit_code": 2, + "seed": [], + "seed_exit_code": null, + "stdout_bytes": 0, + "stderr_bytes": 471 +} diff --git a/crates/pipdock-core/tests/fixtures/uv/network-unreachable/stderr.txt b/crates/pipdock-core/tests/fixtures/uv/network-unreachable/stderr.txt new file mode 100644 index 0000000..263c99e --- /dev/null +++ b/crates/pipdock-core/tests/fixtures/uv/network-unreachable/stderr.txt @@ -0,0 +1,7 @@ +Using Python 3.12.10 environment at: C:\Users\Anon\AppData\Local\Temp\pd-uv-network-unreachable-ba6imiic\venv +error: Request failed after 3 retries in 16.2s + Caused by: Failed to fetch: `http://127.0.0.1:1/simple/idna/` + Caused by: error sending request for url (http://127.0.0.1:1/simple/idna/) + Caused by: client error (Connect) + Caused by: tcp connect error + Caused by: No connection could be made because the target machine actively refused it. (os error 10061) diff --git a/crates/pipdock-core/tests/fixtures/uv/network-unreachable/stdout.txt b/crates/pipdock-core/tests/fixtures/uv/network-unreachable/stdout.txt new file mode 100644 index 0000000..e69de29 diff --git a/crates/pipdock-core/tests/fixtures/uv/requires-python/meta.json b/crates/pipdock-core/tests/fixtures/uv/requires-python/meta.json index b41e518..7e322c7 100644 --- a/crates/pipdock-core/tests/fixtures/uv/requires-python/meta.json +++ b/crates/pipdock-core/tests/fixtures/uv/requires-python/meta.json @@ -1,7 +1,7 @@ { "scenario": "requires-python", - "question": "Requires-Python mismatch against the running interpreter.", - "expects_code": "PD-PKG-001", + "question": "Requires-Python mismatch against the running interpreter. ANSWER: pip refuses with the same 'No matching distribution found' text it uses for an unknown name, so the two are indistinguishable from stderr; uv ignores the constraint and plans the install. Hence PD-PKG-001 is raised by pipdock-core's compat module before either engine runs, and these fixtures record what the engines do instead.", + "expects_code": null, "engine": "uv", "engine_version": "uv 0.11.32 (3010295ae 2026-07-23 x86_64-pc-windows-msvc)", "python": "Python 3.12.10", @@ -13,7 +13,7 @@ "--dry-run", "scipy==1.7.3", "--python", - "\\pd-uv-requires-python-d0zbs0as\\venv\\Scripts\\python.exe" + "\\pd-uv-requires-python-tqk5qbo0\\venv\\Scripts\\python.exe" ], "extra_env": { "PYTHONIOENCODING": "utf-8", diff --git a/crates/pipdock-core/tests/fixtures/uv/requires-python/stderr.txt b/crates/pipdock-core/tests/fixtures/uv/requires-python/stderr.txt index 3754327..9bfdd6a 100644 --- a/crates/pipdock-core/tests/fixtures/uv/requires-python/stderr.txt +++ b/crates/pipdock-core/tests/fixtures/uv/requires-python/stderr.txt @@ -1,5 +1,5 @@ -Using Python 3.12.10 environment at: C:\Users\Anon\AppData\Local\Temp\pd-uv-requires-python-d0zbs0as\venv -Resolved 2 packages in 949ms +Using Python 3.12.10 environment at: C:\Users\Anon\AppData\Local\Temp\pd-uv-requires-python-tqk5qbo0\venv +Resolved 2 packages in 400ms Would download 2 packages Would install 2 packages + numpy==1.22.4 diff --git a/spikes/capture.py b/spikes/capture.py index 663a10c..94463a9 100644 --- a/spikes/capture.py +++ b/spikes/capture.py @@ -50,8 +50,16 @@ class Scenario: question: str = "" #: Error-catalog code this fixture is expected to feed, when it is an error case. expects_code: str | None = None + #: Per-engine override of `expects_code`; the engines do not always agree (see SP-2). + #: Map an engine to None to say "this engine does not fail here at all". + expects_by_engine: dict[str, str | None] = field(default_factory=dict) #: Set False only to capture what happens WITHOUT the UTF-8 mitigation (see SAFE_ENV). utf8_io: bool = True + #: Extra argv inserted before the requirements, e.g. an unreachable index URL. + extra_args: list[str] = field(default_factory=list) + + def code_for(self, engine: str) -> str | None: + return self.expects_by_engine.get(engine, self.expects_code) # pip's `--report -` writes JSON through its vendored rich, which on Windows goes via @@ -121,8 +129,30 @@ SCENARIOS: list[Scenario] = [ # scipy 1.7.3 declares Requires-Python >=3.7,<3.11 and ships wheels, so the resolver # rejects it on metadata rather than attempting a build. target=["scipy==1.7.3"], - question="Requires-Python mismatch against the running interpreter.", - expects_code="PD-PKG-001", + question=( + "Requires-Python mismatch against the running interpreter. ANSWER: pip refuses with " + "the same 'No matching distribution found' text it uses for an unknown name, so the " + "two are indistinguishable from stderr; uv ignores the constraint and plans the " + "install. Hence PD-PKG-001 is raised by pipdock-core's compat module before either " + "engine runs, and these fixtures record what the engines do instead." + ), + expects_by_engine={"pip": "PD-PKG-002", "uv": None}, + ), + # No "externally-managed" scenario. PEP 668 applies only OUTSIDE a virtual environment — pip + # deliberately ignores the marker inside one — and deleting pyvenv.cfg to fake a base install + # merely breaks the venv launcher ("No pyvenv.cfg file", exit 106). Reproducing it properly + # would mean planting the marker in a real system Python, which a fixture script has no + # business doing to a developer's machine. It does not matter: PipDock blocks such + # environments from probe.py's `externally_managed` field at step zero (DATA-FLOW §2), before + # any engine command runs, so PD-ENV-002 is raised internally rather than classified. + Scenario( + name="network-unreachable", + seed=[], + target=["idna"], + # Nothing listens on port 1; deterministic and works offline. + extra_args=["--index-url", "http://127.0.0.1:1/simple"], + question="Index unreachable — connection refused rather than DNS or TLS failure.", + expects_code="PD-NET-001", ), Scenario( name="yanked", @@ -208,13 +238,13 @@ def capture(engine: str, scenario: Scenario, uv_exe: Path | None, out_root: Path if scenario.dry_run: # DATA-FLOW §7: this is the exact planning command, JSON report to stdout. args += ["--dry-run", "--quiet", "--report", "-"] - args += scenario.target + args += scenario.extra_args + scenario.target argv = pip_argv(python, args) else: args = ["install", "-U"] if scenario.dry_run: args += ["--dry-run"] - args += scenario.target + args += scenario.extra_args + scenario.target argv = uv_argv(uv_exe, python, args) result = run(argv, extra_env=env) @@ -226,7 +256,7 @@ def capture(engine: str, scenario: Scenario, uv_exe: Path | None, out_root: Path meta = { "scenario": scenario.name, "question": scenario.question, - "expects_code": scenario.expects_code, + "expects_code": scenario.code_for(engine), "engine": engine, "engine_version": engine_version(engine, python, uv_exe), "python": python_version(python), @@ -273,7 +303,7 @@ def main() -> int: if args.list: for s in SCENARIOS: - print(f"{s.name:24} {s.expects_code or '-':12} {s.question}") + print(f"{s.name:26} {s.expects_code or '-':12} {s.question[:70]}") return 0 if args.engine == "uv" and not args.uv_exe: