diff --git a/crates/pipdock-cli/tests/golden.rs b/crates/pipdock-cli/tests/golden.rs index 7b0a950..2fb89a5 100644 --- a/crates/pipdock-cli/tests/golden.rs +++ b/crates/pipdock-cli/tests/golden.rs @@ -9,8 +9,8 @@ //! * 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 every type in `SCHEMA_TYPES` — 23 as of S6 — which is the JSON -//! contract CLI-SPEC §6 promises consumers can pin against. +//! * `pipdock schema ` for every type in `SCHEMA_TYPES` — 25 as of Phase 3 P3 — 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 @@ -53,6 +53,7 @@ const SCHEMA_TYPES: &[&str] = &[ "Decision", "Intent", "Code", + "HealthReport", ]; fn pipdock() -> Command { diff --git a/crates/pipdock-cli/tests/snapshots/golden__schema-HealthReport.snap b/crates/pipdock-cli/tests/snapshots/golden__schema-HealthReport.snap new file mode 100644 index 0000000..0285fed --- /dev/null +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-HealthReport.snap @@ -0,0 +1,545 @@ +--- +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": "PD-ENV-001", + "description": "Interpreter path missing or not executable — the env was deleted or moved.", + "type": "string" + }, + { + "const": "PD-ENV-002", + "description": "PEP 668 `EXTERNALLY-MANAGED` marker present; mutation blocked by default.", + "type": "string" + }, + { + "const": "PD-ENV-003", + "description": "`probe.py` exited non-zero or produced unparseable output.", + "type": "string" + }, + { + "const": "PD-ENG-001", + "description": "pip or uv binary not found.", + "type": "string" + }, + { + "const": "PD-ENG-002", + "description": "pip older than 22.2, which predates `--dry-run --report`.", + "type": "string" + }, + { + "const": "PD-ENG-003", + "description": "uv emitted a shape the adapter does not recognize (uv newer than PipDock).", + "type": "string" + }, + { + "const": "PD-ENG-999", + "description": "Fallback for engine failures no classifier matched. Always last.", + "type": "string" + }, + { + "const": "PD-RES-001", + "description": "`ResolutionImpossible` or the uv equivalent: constraints cannot be satisfied.", + "type": "string" + }, + { + "const": "PD-RES-002", + "description": "Plan older than 10 minutes, or the env's probe hash changed since the preview.", + "type": "string" + }, + { + "const": "PD-RES-003", + "description": "A plan is already resolving or executing in this session.\n\nThe GUI drives one resumable flow across several IPC calls, so \"start a plan\" and \"run the\nplan\" are different messages arriving at different times — nothing structurally stops a\nsecond one arriving in between. Refusing is the only safe answer: two concurrent plans\nwould interleave engine commands against one environment, and DATA-FLOW §9.3's staleness\ncheck would be comparing against a set the other plan is busy changing.", + "type": "string" + }, + { + "const": "PD-RES-004", + "description": "A removal was asked for that the reverse-dependency guard refused (DATA-FLOW §5).\n\nIts own code rather than a reused one. The CLI printed `PD-PKG-002` here, which means \"no\nmatching distribution\" — the opposite of the truth: every package involved exists, and\nthat is precisely why the removal is being refused. A user grepping their logs for a typo\nwould have found this instead.\n\nNot raised when the guard merely *finds* dependents. That is a report the caller shows and\nthe user answers; the code appears only when execution is attempted anyway without the\nuser having accepted the breakage.", + "type": "string" + }, + { + "const": "PD-BLD-001", + "description": "MSVC build tools required but absent.", + "type": "string" + }, + { + "const": "PD-BLD-002", + "description": "Build backend failed (`pyproject.toml` error, `metadata-generation-failed`).", + "type": "string" + }, + { + "const": "PD-BLD-003", + "description": "Generic sdist wheel-build failure.", + "type": "string" + }, + { + "const": "PD-PKG-001", + "description": "No matching distribution, and metadata shows a requires-python mismatch.", + "type": "string" + }, + { + "const": "PD-PKG-002", + "description": "No matching distribution: name or version typo, or the release is gone.", + "type": "string" + }, + { + "const": "PD-PKG-003", + "description": "The requested release was yanked.", + "type": "string" + }, + { + "const": "PD-PKG-004", + "description": "Downloaded artifact failed hash verification.", + "type": "string" + }, + { + "const": "PD-NET-001", + "description": "Timeout, connection aborted, or DNS failure.", + "type": "string" + }, + { + "const": "PD-NET-002", + "description": "TLS/SSL verification failed — typically proxy or AV interception.", + "type": "string" + }, + { + "const": "PD-NET-010", + "description": "PEP 691 index refresh failed; the stale index stays searchable.", + "type": "string" + }, + { + "const": "PD-NET-011", + "description": "Code Health tools-venv bootstrap could not reach PyPI.", + "type": "string" + }, + { + "const": "PD-PRM-001", + "description": "`PermissionError` writing site-packages (admin-owned Python).", + "type": "string" + }, + { + "const": "PD-PRM-002", + "description": "File locked by a running process (`WinError 32`).", + "type": "string" + }, + { + "const": "PD-SNP-001", + "description": "Snapshot write failed before execution. **The plan is aborted; nothing runs.**", + "type": "string" + }, + { + "const": "PD-SNP-002", + "description": "A release needed to restore a snapshot is no longer available on PyPI.", + "type": "string" + }, + { + "const": "PD-SYS-001", + "description": "`MAX_PATH` exceeded without the long-path opt-in.", + "type": "string" + }, + { + "const": "PD-SYS-002", + "description": "Disk full.", + "type": "string" + }, + { + "const": "PD-HLT-001", + "description": "A Code Health tool is missing from the tools venv.", + "type": "string" + }, + { + "const": "PD-HLT-002", + "description": "A Code Health tool exited non-zero.", + "type": "string" + }, + { + "const": "PD-HLT-003", + "description": "A Code Health tool exceeded its watchdog timeout; partial report shown.", + "type": "string" + }, + { + "const": "PD-HLT-004", + "description": "`python -m venv` failed while building the tools environment.\n\n**Raised by PipDock, not classified from engine stderr.** Its own code rather than a reused\none: `PD-NET-011` is `Area::Net`, so `run::exit_for` would map a broken interpreter to exit\n6 and a script retrying on network failure would loop forever; `PD-HLT-001` tells the user\nto re-sync, which is the operation that just failed; and a Python built without `venv` is\nnot `PD-INT-001`'s \"a PipDock bug\".", + "type": "string" + }, + { + "const": "PD-INT-001", + "description": "A PipDock bug: panic or unexpected state.", + "type": "string" + } + ] + }, + "DeclaredSource": { + "description": "Where the project declares its dependencies, if anywhere.\n\ndeptry needs one of these to have anything to compare against. `None` is not an error — it is\nthe \"limited-mode notice\" §3 asks the UI to show, and the other two tools do not care.", + "oneOf": [ + { + "description": "A `pyproject.toml`, which is what deptry prefers.", + "properties": { + "kind": { + "const": "pyproject", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" + }, + { + "description": "One or more `requirements*.txt`, named so the UI can say which.", + "properties": { + "files": { + "description": "File names, sorted, relative to the project folder.", + "items": { + "type": "string" + }, + "type": "array" + }, + "kind": { + "const": "requirements", + "type": "string" + } + }, + "required": [ + "kind", + "files" + ], + "type": "object" + }, + { + "description": "Neither. deptry runs in limited mode and its findings mean less.", + "properties": { + "kind": { + "const": "none", + "type": "string" + } + }, + "required": [ + "kind" + ], + "type": "object" + } + ] + }, + "DeptryIssue": { + "description": "One deptry violation, grouped by the dependency it is about.\n\n**deptry emits a flat list**, one object per `(code, module, location)`:\n`{\"error\":{\"code\",\"message\"},\"module\",\"location\":{\"file\",\"line\",\"column\"}}`. §5 sketched a\nper-dependency object with a `locations` array; that shape does not exist. Grouping happens here\nrather than in the UI so the GUI, `pipdock health --json` and P4's saved report cannot disagree.", + "properties": { + "code": { + "description": "deptry's own code — `DEP001`..`DEP004`. Never a PipDock catalog code.", + "type": "string" + }, + "dep": { + "description": "The name deptry reported.\n\n**A module name, not necessarily a distribution.** `yaml` is `PyYAML`, `cv2` is\n`opencv-python`. Anything handing this to a package operation has to reconcile it first.", + "type": "string" + }, + "locations": { + "description": "Where it was found. Empty when deptry named no location.", + "items": { + "$ref": "#/$defs/SourceLocation" + }, + "type": "array" + }, + "message": { + "description": "deptry's message, verbatim.\n\nNot a `kind` derived from the code: that mapping would be PipDock's, maintained in two\nlanguages, against a tool that adds codes on its own schedule.", + "type": "string" + } + }, + "required": [ + "code", + "dep", + "message" + ], + "type": "object" + }, + "FixApplicability": { + "description": "How safe ruff considers its own fix.\n\nOnly `Safe` is ever applied: P5 runs plain `ruff check --fix`, which is what `--unsafe-fixes`\nexists to opt out of, and CODE-HEALTH-SPEC §1 makes the write path the narrow one.", + "oneOf": [ + { + "const": "safe", + "description": "Applied by `ruff check --fix`.", + "type": "string" + }, + { + "const": "unsafe", + "description": "Needs `--unsafe-fixes`, which PipDock never passes.", + "type": "string" + }, + { + "const": "display", + "description": "Shown but never applied.", + "type": "string" + } + ] + }, + "RuffFinding": { + "description": "One ruff finding.", + "properties": { + "code": { + "description": "The rule code, e.g. `F401`.\n\nOptional because the field is not ours. ruff 0.16.0 always sets it — a syntax error comes\nthrough as `invalid-syntax` rather than null, which is **not** what CODE-HEALTH-SPEC §6\nassumed — but tolerating null costs one `??` in the UI and stops a format change from\nfailing every run.", + "type": [ + "string", + "null" + ] + }, + "column": { + "description": "1-based.", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "filename": { + "description": "Absolute, as ruff reports it.", + "type": "string" + }, + "fix": { + "anyOf": [ + { + "$ref": "#/$defs/FixApplicability" + }, + { + "type": "null" + } + ], + "description": "Whether ruff offers a fix, and how confident it is in it." + }, + "message": { + "description": "ruff's message, verbatim.", + "type": "string" + }, + "name": { + "description": "The rule slug, e.g. `unused-import`.", + "type": "string" + }, + "row": { + "description": "1-based.", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "url": { + "description": "ruff's own documentation link.\n\n**Carried, never constructed.** The URL is keyed by rule *name*, so §6's\n`https://docs.astral.sh/ruff/rules/` 404s — `I001` lives at `.../unsorted-imports`.\nNull for a syntax error, which has no rule page.", + "type": [ + "string", + "null" + ] + } + }, + "required": [ + "name", + "message", + "filename", + "row", + "column" + ], + "type": "object" + }, + "RuffFindings": { + "description": "ruff's findings and the two counts the fix path is built on.", + "properties": { + "findings": { + "description": "Every finding, in ruff's order.", + "items": { + "$ref": "#/$defs/RuffFinding" + }, + "type": "array" + }, + "fixable": { + "description": "How many carry a **safe** fix — what `ruff check --fix` would actually apply.\n\nCounted here rather than in the UI because P5's confirm dialog and the CLI's prompt have to\nname the same number, and two implementations of \"count the safe ones\" will not stay equal.", + "format": "uint", + "minimum": 0, + "type": "integer" + }, + "fixableFiles": { + "description": "How many distinct files those touch. The number P5's dialog names.", + "format": "uint", + "minimum": 0, + "type": "integer" + } + }, + "required": [ + "findings", + "fixable", + "fixableFiles" + ], + "type": "object" + }, + "SourceLocation": { + "description": "A file and, when the tool knew it, a position in it.", + "properties": { + "column": { + "description": "1-based.", + "format": "uint32", + "minimum": 0, + "type": [ + "integer", + "null" + ] + }, + "file": { + "description": "Relative to the project folder where the tool reported it that way.", + "type": "string" + }, + "line": { + "description": "1-based. Absent for a whole-file finding such as an unused dependency in `pyproject.toml`.", + "format": "uint32", + "minimum": 0, + "type": [ + "integer", + "null" + ] + } + }, + "required": [ + "file" + ], + "type": "object" + }, + "ToolProblem": { + "description": "One tool that was asked to run and did not finish.\n\nDeliberately `PdError`-shaped so the UI can hand it straight to `PdErrorRow` rather than\ninventing a second error presentation for the same catalog codes.", + "properties": { + "code": { + "$ref": "#/$defs/Code", + "description": "The catalog code, so the row is localized from the same table as every other error." + }, + "message": { + "description": "Developer-facing detail. Never shown as-is (I18N §1).", + "type": "string" + }, + "stderrTail": { + "description": "Tail of the tool's stderr, capped as ERROR-CATALOG §3 caps every other one.", + "type": [ + "string", + "null" + ] + }, + "tool": { + "description": "Which tool: `deptry`, `vulture` or `ruff`.", + "type": "string" + } + }, + "required": [ + "tool", + "code", + "message" + ], + "type": "object" + }, + "VultureFinding": { + "description": "One vulture finding.\n\n**vulture has no machine-readable output.** Its text form is\n`:: (% confidence)`, and `message` is `unused ''` for\nseven kinds and `unreachable code after ''` for the eighth — which is why `name` is\noptional rather than parsed out of every line. §5 has it required; amended.", + "properties": { + "confidence": { + "description": "vulture's confidence percentage. Below 100 is a candidate, not a fact (§6).", + "format": "uint8", + "maximum": 255, + "minimum": 0, + "type": "integer" + }, + "line": { + "description": "1-based.", + "format": "uint32", + "minimum": 0, + "type": "integer" + }, + "message": { + "description": "The whole message, verbatim.", + "type": "string" + }, + "name": { + "description": "The identifier, when the message names one.", + "type": [ + "string", + "null" + ] + }, + "path": { + "description": "As vulture printed it, relative to the project folder.", + "type": "string" + } + }, + "required": [ + "path", + "line", + "message", + "confidence" + ], + "type": "object" + } + }, + "$schema": "https://json-schema.org/draft/2020-12/schema", + "description": "A Code Health run, whole or partial.\n\nThe only type in this module that reaches the wire, so the only one in `SCHEMA_TYPES` — the\nbindings generator hoists everything it references out of `$defs` into its own TS declaration.", + "properties": { + "declared": { + "$ref": "#/$defs/DeclaredSource", + "description": "What the project declares its dependencies in (§3's detection order)." + }, + "deptry": { + "description": "deptry's findings, grouped by dependency.", + "items": { + "$ref": "#/$defs/DeptryIssue" + }, + "type": "array" + }, + "env": { + "description": "`canonical_interpreter` of the environment deptry compared against.", + "type": "string" + }, + "problems": { + "description": "Why a requested tool contributed nothing.\n\n**Empty means every tool in `ran` completed.** This is what makes `PD-HLT-003`'s \"partial\nreport shown\" a shape rather than a promise: one tool failing does not fail the run, it\nlands here and the other two still report.", + "items": { + "$ref": "#/$defs/ToolProblem" + }, + "type": "array" + }, + "project": { + "description": "Absolute project folder the tools ran in. Data, never localized (I18N §2).", + "type": "string" + }, + "ran": { + "description": "Which tools were asked to run.\n\n**What makes an empty list readable.** Without it, \"no deptry findings\" and \"deptry never\nran\" are the same empty array, and the UI would have to render one as the other — which is\nthe \"never render a state you have not loaded\" rule applied to a tab.", + "items": { + "type": "string" + }, + "type": "array" + }, + "ranAt": { + "description": "When the run finished, RFC 3339.", + "type": "string" + }, + "ruff": { + "$ref": "#/$defs/RuffFindings", + "description": "ruff's findings, plus the counts P5's confirm dialog needs." + }, + "toolVersions": { + "additionalProperties": { + "type": "string" + }, + "description": "The version each tool reported, out of the tools manifest.", + "type": "object" + }, + "vulture": { + "description": "vulture's findings, in the order it reported them.", + "items": { + "$ref": "#/$defs/VultureFinding" + }, + "type": "array" + } + }, + "required": [ + "project", + "env", + "ranAt", + "toolVersions", + "declared", + "ran", + "deptry", + "vulture", + "ruff" + ], + "title": "HealthReport", + "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 index 67e291e..d799656 100644 --- a/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap +++ b/crates/pipdock-cli/tests/snapshots/golden__schema-unknown-type.snap @@ -2,4 +2,4 @@ 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, EngineInfo, RollbackPlan, RollbackPreview, Hit, PackageMeta, Freshness, RefreshReport, ProgressEvent, FlowStep, Decision, Intent, Code +error[PD-PKG-002]: unknown type "NoSuchType"; known types: Dist, OutdatedDist, PyEnv, CheckReport, StepResult, PlanRequest, ResolutionReport, ExecutionSummary, Pin, GuardReport, Diff, SnapshotMeta, EngineInfo, RollbackPlan, RollbackPreview, Hit, PackageMeta, Freshness, RefreshReport, ProgressEvent, FlowStep, Decision, Intent, Code, HealthReport diff --git a/crates/pipdock-core/src/health/mod.rs b/crates/pipdock-core/src/health/mod.rs index 936bdf7..d3571d1 100644 --- a/crates/pipdock-core/src/health/mod.rs +++ b/crates/pipdock-core/src/health/mod.rs @@ -8,8 +8,11 @@ pub mod deptry; pub mod project; pub mod report; pub mod ruff; +pub mod run; pub mod vulture; +pub use run::{RunOptions, has_findings, run_steps}; + pub use project::{DeclaredSource, declared_source}; pub use report::{ DeptryIssue, FixApplicability, HealthReport, RuffFinding, RuffFindings, SourceLocation, diff --git a/crates/pipdock-core/src/health/run.rs b/crates/pipdock-core/src/health/run.rs new file mode 100644 index 0000000..b84ed32 --- /dev/null +++ b/crates/pipdock-core/src/health/run.rs @@ -0,0 +1,480 @@ +//! Running the three tools and assembling a [`HealthReport`]. +//! +//! The shape that matters here is **skip-and-continue**. `PD-HLT-003` promises a "partial report +//! shown", so a tool that fails does not fail the run: it lands in `HealthReport.problems` and the +//! other two still report. That is the same rule `plan::execute` follows for a failed package, and +//! it is the thing most likely to be built as a whole-run failure by accident. + +use std::path::Path; + +use crate::engine::ProgressSink; +use crate::errors::{Code, PdError, Result}; +use crate::exec::Command; +use crate::model::{ExecMode, PkgName, PyEnv, StepStatus}; + +use super::report::{HealthReport, RuffFindings, ToolProblem}; +use super::{DEFAULT_EXCLUDES, DEFAULT_MIN_CONFIDENCE, HEALTH_TOOLS, TOOL_TIMEOUT}; + +/// What the caller wants run, and how. +/// +/// **Off the wire on purpose.** CODE-HEALTH-SPEC §4 says the confidence floor comes "from +/// settings", but `settings::Settings` has three fields and none of them is this. Adding them is a +/// golden, a bindings regeneration and a Settings screen, which is its own slice; until then the +/// constants are the answer and the doc is ahead of the code. +#[derive(Debug, Clone)] +pub struct RunOptions { + /// Which tools to run. Empty means all of [`HEALTH_TOOLS`]. + pub tools: Vec, + /// vulture's `--min-confidence`. + pub min_confidence: u8, + /// Extra exclusions on top of [`DEFAULT_EXCLUDES`]. + pub excludes: Vec, +} + +impl Default for RunOptions { + fn default() -> Self { + Self { + tools: HEALTH_TOOLS.iter().map(|t| (*t).to_owned()).collect(), + min_confidence: DEFAULT_MIN_CONFIDENCE, + excludes: Vec::new(), + } + } +} + +impl RunOptions { + /// The tools to run, in [`HEALTH_TOOLS`] order and with anything unknown dropped. + /// + /// Ordered by the constant rather than by what the caller passed, so `--tool ruff --tool + /// deptry` and `--tool deptry --tool ruff` produce the same report and the same progress. + #[must_use] + pub fn selected(&self) -> Vec<&'static str> { + HEALTH_TOOLS + .iter() + .filter(|t| self.tools.is_empty() || self.tools.iter().any(|want| want == *t)) + .copied() + .collect() + } +} + +/// How many steps a run reports, given the tools selected. +#[must_use] +pub fn run_steps(opts: &RunOptions) -> usize { + opts.selected().len() +} + +/// Run Code Health over `project` for `env`. +/// +/// * `tools_dir` — passed, not derived, for the reason `sync_tools_venv` documents: a test or CI +/// run must not clobber the developer's real `%LOCALAPPDATA%\PipDock\tools`. +/// * `project` — each tool's CWD, via the `Command::cwd` added for exactly this. +/// * `env` — recorded on the report so a stale one can be told from a current one. It is +/// deliberately **not** passed to any tool; see below. +/// * `sink` — carries the `CancellationToken`, and its `total` must already account for whatever +/// the caller did before this (an implicit tools sync, above all). +/// +/// # Errors +/// Only failures that make **every** tool meaningless: `PD-HLT-001` when a tool is missing from +/// the tools venv, `PD-ENV-003` when `project` cannot be read. A single tool failing is not one of +/// them — see `problems`. +/// +/// # deptry does not see the user's environment, and cannot be made to +/// +/// CODE-HEALTH-SPEC §3 says the environment is "passed to deptry so 'installed vs declared vs +/// imported' compares against reality". **deptry 0.25.1 has no such option.** It ignores +/// `VIRTUAL_ENV`, and reads whatever its own interpreter can import — verified by watching it +/// report `click`, which exists only in PipDock's tools venv, as `DEP003` transitive. Putting the +/// tools venv on a user interpreter's `PYTHONPATH` does not help: deptry's own dependencies come +/// with it. §2's isolation and §3's comparison are simply in conflict at this version. +/// +/// What that costs, precisely: deptry classifies an undeclared import as `DEP003` rather than +/// `DEP001` when it can see the package, so the split is wrong for the nine packages the tools venv +/// holds, and `DEP003` under-reports anything genuinely transitive in the *user's* environment. +/// Both still mean "you imported something you did not declare", which is what §6 tells the user to +/// fix either way. Kept rather than suppressed: `--ignore DEP003` would turn a mislabelled finding +/// into a missing one. +/// +/// §3 is amended to say this, and `deptry_is_never_told_about_an_environment` pins it so a future +/// deptry gaining the flag is noticed rather than silently continuing to be worked around. +pub async fn run( + tools_dir: &Path, + project: &Path, + env: &PyEnv, + opts: &RunOptions, + sink: &ProgressSink, +) -> Result { + let declared = super::declared_source(project)?; + let selected = opts.selected(); + + let mut report = HealthReport { + project: project.display().to_string(), + env: crate::exec::canonical_interpreter(&env.interpreter), + ran_at: String::new(), + tool_versions: super::read_manifest(tools_dir) + .map(|m| m.tools) + .unwrap_or_default(), + declared, + ran: selected.iter().map(|t| (*t).to_owned()).collect(), + deptry: Vec::new(), + vulture: Vec::new(), + ruff: RuffFindings::default(), + problems: Vec::new(), + }; + + for (i, tool) in selected.iter().enumerate() { + let step = sink.at(sink.step + i); + let name = PkgName::parse(tool)?; + step.started(Some(name.clone()), ExecMode::Isolated); + + match run_one(tools_dir, project, opts, tool).await { + Ok(out) => { + collect(&mut report, tool, &out)?; + step.finished(Some(name), ExecMode::Isolated, StepStatus::Ok); + } + Err(e) => { + // The skip-and-continue point. `Failed`, not an early return: the console drawer + // and the live region both need to see this step end, and the next tool still runs. + report.problems.push(ToolProblem { + tool: (*tool).to_owned(), + code: e.code, + message: e.message, + stderr_tail: e.stderr_tail, + }); + step.finished(Some(name), ExecMode::Isolated, StepStatus::Failed); + } + } + } + + report.ran_at = jiff::Timestamp::now().to_string(); + Ok(report) +} + +/// Invoke one tool and hand back its stdout. +/// +/// # Errors +/// `PD-HLT-001` when it is not in the tools venv, `PD-HLT-003` on its watchdog, `PD-HLT-002` when +/// it exited a way [`super::is_findings_exit`] does not recognize. +async fn run_one( + tools_dir: &Path, + project: &Path, + opts: &RunOptions, + tool: &str, +) -> Result { + let exe = super::tool_exe(tools_dir, tool); + if !exe.is_file() { + return Err(PdError::new( + Code::HltToolMissing, + format!("{tool} is not in the tools environment"), + )); + } + + // deptry writes its JSON to a path rather than a stream, so it needs a scratch file — under + // the tools directory, never in the project (§1). Unique per process so two runs cannot read + // each other's report. + let report_path = tools_dir + .join("runs") + .join(format!("{tool}-{}.json", std::process::id())); + if tool == "deptry" + && let Some(parent) = report_path.parent() + { + std::fs::create_dir_all(parent).map_err(|e| { + PdError::new( + Code::HltToolFailed, + format!("could not make room for deptry's report: {e}"), + ) + })?; + } + + let out = Command::new(&exe) + .args(argv(tool, opts, &report_path)) + .cwd(project) + .timeout(TOOL_TIMEOUT) + .run() + .await + .map_err(|e| watchdog(e, tool)); + + let stdout = match out { + Ok(out) if super::is_findings_exit(tool, out.code) => { + if tool == "deptry" { + std::fs::read_to_string(&report_path).map_err(|e| { + PdError::new( + Code::HltToolFailed, + format!("deptry exited cleanly but wrote no report: {e}"), + ) + }) + } else { + Ok(out.stdout) + } + } + Ok(out) => Err(PdError::new( + Code::HltToolFailed, + format!("{tool} exited {}", out.code.unwrap_or(-1)), + ) + .with_stderr(&out.stderr)), + Err(e) => Err(e), + }; + + // Cleaned on both paths: `%LOCALAPPDATA%\PipDock` is what SECURITY §8 promises a delete + // resets, and leaving a report per run turns that into a slow leak. + let _ = std::fs::remove_file(&report_path); + stdout +} + +/// The argv for one tool (CODE-HEALTH-SPEC §4, plus what running them taught). +fn argv(tool: &str, opts: &RunOptions, report_path: &Path) -> Vec { + let mut args: Vec = Vec::new(); + match tool { + "deptry" => { + args.push(".".into()); + // A real path, because `--json-output` is a *location* and not a stream: passing `-` + // creates a file literally called `-` in whatever the CWD is, which here is the user's + // project — the precise thing CODE-HEALTH-SPEC §1 forbids. The caller supplies a path + // under the tools directory and deletes it either way. + args.push("--json-output".into()); + args.push(report_path.display().to_string()); + // deptry colours its text report unconditionally, and the escapes are noise in the + // console drawer and in the bug-report log ring. + args.push("--no-ansi".into()); + // §7's notebook non-goal. + args.push("--ignore-notebooks".into()); + // deptry's exclusions are **regexes** matched with `re.match`, so they are anchored: + // a bare `build` would not match `pkg/build/`. Every other tool here takes globs. + for pattern in excludes(opts) { + args.push("--extend-exclude".into()); + args.push(format!(".*{}/.*", regex_escape(&pattern))); + } + // **No environment flag exists.** CODE-HEALTH-SPEC §3 says the env is "passed to deptry + // so 'installed vs declared vs imported' compares against reality"; deptry 0.25.1 has + // no such option, ignores VIRTUAL_ENV, and reads whatever is importable from the + // interpreter running it — verified by watching it report a tools-venv-only package as + // DEP003. See `run`'s doc comment for what that costs and what is disclosed. + } + "vulture" => { + args.push(".".into()); + args.push("--min-confidence".into()); + args.push(opts.min_confidence.to_string()); + // vulture takes one comma-separated list of globs, not repeated flags. + let globs = excludes(opts) + .iter() + .map(|p| format!("*/{p}/*")) + .collect::>() + .join(","); + if !globs.is_empty() { + args.push("--exclude".into()); + args.push(globs); + } + } + "ruff" => { + args.push("check".into()); + args.push(".".into()); + args.push("--output-format".into()); + args.push("json".into()); + // §7 again. ruff's excludes are globs and are *additive* to the project's own config. + args.push("--exclude".into()); + args.push("*.ipynb".into()); + for pattern in excludes(opts) { + args.push("--exclude".into()); + args.push(pattern); + } + } + _ => {} + } + args +} + +/// The default exclusions plus the caller's. +fn excludes(opts: &RunOptions) -> Vec { + DEFAULT_EXCLUDES + .iter() + .map(|d| (*d).to_owned()) + .chain(opts.excludes.iter().cloned()) + .collect() +} + +/// Escape the characters a directory name can contain that a regex would read as syntax. +/// +/// `.venv` is the case that matters and it is in the defaults: unescaped, `.` matches any +/// character, so the pattern would also exclude `avenv`, `1venv` and anything else shaped like it. +fn regex_escape(literal: &str) -> String { + literal.chars().fold(String::new(), |mut acc, c| { + if ".^$*+?()[]{}|\\".contains(c) { + acc.push('\\'); + } + acc.push(c); + acc + }) +} + +/// Fold one tool's stdout into the report. +fn collect(report: &mut HealthReport, tool: &str, stdout: &str) -> Result<()> { + match tool { + "deptry" => report.deptry = super::deptry::parse(stdout)?, + "vulture" => report.vulture = super::vulture::parse(stdout), + "ruff" => report.ruff = super::ruff::parse(stdout)?, + _ => {} + } + Ok(()) +} + +/// Re-read an `exec` timeout as the tool's own watchdog code. +/// +/// `exec::Command::stopped` raises `PD-INT-001` for both its watchdog and cancellation, so without +/// this a tool that ran long would tell the user PipDock hit an internal error — and `PD-HLT-003`, +/// which exists for exactly this, would never be reachable. +fn watchdog(e: PdError, tool: &str) -> PdError { + if e.code == Code::IntUnexpected && e.message.contains("timed out") { + return PdError::new( + Code::HltTimeout, + format!("{tool} exceeded its {TOOL_TIMEOUT:?} watchdog; its results are missing"), + ); + } + e +} + +/// Whether any tool reported something. +/// +/// Drives the CLI's exit code: a linter that exits 0 on findings is useless in a pre-commit hook. +#[must_use] +pub fn has_findings(report: &HealthReport) -> bool { + !report.deptry.is_empty() || !report.vulture.is_empty() || !report.ruff.findings.is_empty() +} + +/// Ensure `total` is not smaller than what will actually be emitted. +/// +/// A sink whose total is wrong is a progress bar that stops short or overshoots, and the caller +/// cannot always know whether a tools-venv sync will be needed until it asks. +#[must_use] +pub fn sink_for(sink: &ProgressSink, first_step: usize) -> ProgressSink { + sink.at(first_step) +} + +#[cfg(test)] +mod tests { + use super::*; + + fn opts_for(tools: &[&str]) -> RunOptions { + RunOptions { + tools: tools.iter().map(|t| (*t).to_owned()).collect(), + ..RunOptions::default() + } + } + + #[test] + fn no_selection_means_every_tool() { + assert_eq!(opts_for(&[]).selected(), HEALTH_TOOLS); + } + + #[test] + fn selection_order_is_the_constants_not_the_callers() { + // `--tool ruff --tool deptry` and the reverse must produce the same report and the same + // progress steps, or two identical runs disagree about what step 2 was. + assert_eq!( + opts_for(&["ruff", "deptry"]).selected(), + opts_for(&["deptry", "ruff"]).selected() + ); + assert_eq!(opts_for(&["ruff", "deptry"]).selected(), ["deptry", "ruff"]); + } + + #[test] + fn an_unknown_tool_is_dropped_rather_than_run() { + assert_eq!(opts_for(&["pip-audit"]).selected(), Vec::<&str>::new()); + } + + #[test] + fn run_steps_follows_the_selection() { + assert_eq!(run_steps(&opts_for(&[])), HEALTH_TOOLS.len()); + assert_eq!(run_steps(&opts_for(&["ruff"])), 1); + } + + /// The bug an unescaped default would ship: `.venv` as a regex also matches `avenv`. + #[test] + fn deptry_exclusions_are_escaped_regexes() { + let args = args_for("deptry"); + + assert!( + args.iter().any(|a| a == r".*\.venv/.*"), + "the dot must be escaped and the pattern anchored: {args:?}" + ); + assert!(!args.iter().any(|a| a == ".*.venv/.*")); + } + + #[test] + fn vulture_takes_one_comma_separated_list_not_repeated_flags() { + let args = args_for("vulture"); + let flags = args.iter().filter(|a| *a == "--exclude").count(); + + assert_eq!(flags, 1, "vulture takes a single list: {args:?}"); + assert!( + args.iter() + .any(|a| a.contains("*/.venv/*") && a.contains(',')) + ); + } + + /// The limitation, pinned. `run`'s doc comment says why it cannot be otherwise. + #[test] + fn deptry_is_never_told_about_an_environment() { + // deptry 0.25.1 has no such option — passing one fails the command outright — and + // CODE-HEALTH-SPEC §3 assumed one existed. If a future deptry gains it, this is what makes + // someone notice rather than leaving the workaround in place forever. + let args = args_for("deptry"); + + assert!( + !args.iter().any(|a| a == "--python" || a == "--venv"), + "deptry has no environment flag at the pinned version: {args:?}" + ); + } + + #[test] + fn deptrys_report_is_written_under_the_tools_directory_not_the_project() { + // §1: PipDock never writes into the user's project. `--json-output` takes a *location*, + // not a stream, so `-` would create a file called `-` in the CWD — which is the project. + // Verified against `deptry --help`. + let path = Path::new(r"C:\tools\runs\deptry-1.json"); + let args = argv("deptry", &RunOptions::default(), path); + let idx = args + .iter() + .position(|a| a == "--json-output") + .expect("--json-output"); + + assert_eq!(args[idx + 1], path.display().to_string()); + assert_ne!(args[idx + 1], "-", "`-` is a filename here, not stdout"); + } + + #[test] + fn notebooks_are_excluded_from_both_tools_that_can_see_them() { + // §7's non-goal, which is contractual per ROADMAP's standing risks. + assert!(args_for("deptry").iter().any(|a| a == "--ignore-notebooks")); + assert!(args_for("ruff").iter().any(|a| a == "*.ipynb")); + } + + #[test] + fn no_argv_entry_bundles_two_arguments() { + // SECURITY §2's argv rule, applied to the tools as it already is to the engines. + for tool in HEALTH_TOOLS { + for arg in args_for(tool) { + assert!( + !arg.contains(' ') || arg.starts_with('*') || arg.contains(','), + "{tool}: {arg:?} bundles arguments" + ); + } + } + } + + fn args_for(tool: &str) -> Vec { + argv( + tool, + &RunOptions::default(), + Path::new(r"C:\tools\runs\r.json"), + ) + } + #[test] + fn a_watchdog_reads_as_the_health_code_not_an_internal_error() { + let timed_out = PdError::new(Code::IntUnexpected, "timed out after 120s: ruff.exe"); + assert_eq!(watchdog(timed_out, "ruff").code, Code::HltTimeout); + } + + #[test] + fn a_cancellation_is_not_a_watchdog() { + let cancelled = PdError::new(Code::IntUnexpected, "cancelled: ruff.exe"); + assert_eq!(watchdog(cancelled, "ruff").code, Code::IntUnexpected); + } +} diff --git a/crates/pipdock-core/src/plan/mod.rs b/crates/pipdock-core/src/plan/mod.rs index 28f48cf..e02733c 100644 --- a/crates/pipdock-core/src/plan/mod.rs +++ b/crates/pipdock-core/src/plan/mod.rs @@ -282,6 +282,10 @@ pub fn json_schema(type_name: &str) -> Result { "Decision" => Decision, "Intent" => crate::flow::Intent, "Code" => crate::errors::Code, + // Only `HealthReport`, not its parts: the bindings generator hoists every `$defs` entry + // into its own TS declaration, so `DeptryIssue` and the rest arrive without being listed. + // Registering them separately would emit each twice. + "HealthReport" => crate::health::HealthReport, } } @@ -311,6 +315,7 @@ pub const SCHEMA_TYPES: &[&str] = &[ "Decision", "Intent", "Code", + "HealthReport", ]; /// DATA-FLOW §9.3: a report older than this is refused by [`execute`] and must be re-resolved. diff --git a/ui/src/ipc/generated.ts b/ui/src/ipc/generated.ts index eadec25..320a88a 100644 --- a/ui/src/ipc/generated.ts +++ b/ui/src/ipc/generated.ts @@ -144,6 +144,46 @@ export type Decision = | 'skip' | 'force-latest'; +/** + * Where the project declares its dependencies, if anywhere. + * + * deptry needs one of these to have anything to compare against. `None` is not an error — it is + * the "limited-mode notice" §3 asks the UI to show, and the other two tools do not care. + */ +export type DeclaredSource = + | { kind: 'pyproject' } + | { files: string[]; kind: 'requirements' } + | { kind: 'none' }; + +/** + * One deptry violation, grouped by the dependency it is about. + * + * **deptry emits a flat list**, one object per `(code, module, location)`: + * `{"error":{"code","message"},"module","location":{"file","line","column"}}`. §5 sketched a + * per-dependency object with a `locations` array; that shape does not exist. Grouping happens here + * rather than in the UI so the GUI, `pipdock health --json` and P4's saved report cannot disagree. + */ +export interface DeptryIssue { + /** deptry's own code — `DEP001`..`DEP004`. Never a PipDock catalog code. */ + code: string; + /** + * The name deptry reported. + * + * **A module name, not necessarily a distribution.** `yaml` is `PyYAML`, `cv2` is + * `opencv-python`. Anything handing this to a package operation has to reconcile it first. + */ + dep: string; + /** Where it was found. Empty when deptry named no location. */ + locations?: SourceLocation[]; + /** + * deptry's message, verbatim. + * + * Not a `kind` derived from the code: that mapping would be PipDock's, maintained in two + * languages, against a tool that adds codes on its own schedule. + */ + message: string; +} + /** The difference between two environment states. */ export interface Diff { /** Present now, absent in the snapshot. */ @@ -232,6 +272,17 @@ export interface ExecutionSummary { results?: StepResult[]; } +/** + * How safe ruff considers its own fix. + * + * Only `Safe` is ever applied: P5 runs plain `ruff check --fix`, which is what `--unsafe-fixes` + * exists to opt out of, and CODE-HEALTH-SPEC §1 makes the write path the narrow one. + */ +export type FixApplicability = + | 'safe' + | 'unsafe' + | 'display'; + /** * What the flow needs next. * @@ -271,6 +322,47 @@ export interface GuardReport { withDependents: PkgName[]; } +/** + * A Code Health run, whole or partial. + * + * The only type in this module that reaches the wire, so the only one in `SCHEMA_TYPES` — the + * bindings generator hoists everything it references out of `$defs` into its own TS declaration. + */ +export interface HealthReport { + /** What the project declares its dependencies in (§3's detection order). */ + declared: DeclaredSource; + /** deptry's findings, grouped by dependency. */ + deptry: DeptryIssue[]; + /** `canonical_interpreter` of the environment deptry compared against. */ + env: string; + /** + * Why a requested tool contributed nothing. + * + * **Empty means every tool in `ran` completed.** This is what makes `PD-HLT-003`'s "partial + * report shown" a shape rather than a promise: one tool failing does not fail the run, it + * lands here and the other two still report. + */ + problems?: ToolProblem[]; + /** Absolute project folder the tools ran in. Data, never localized (I18N §2). */ + project: string; + /** + * Which tools were asked to run. + * + * **What makes an empty list readable.** Without it, "no deptry findings" and "deptry never + * ran" are the same empty array, and the UI would have to render one as the other — which is + * the "never render a state you have not loaded" rule applied to a tab. + */ + ran: string[]; + /** When the run finished, RFC 3339. */ + ranAt: string; + /** ruff's findings, plus the counts P5's confirm dialog needs. */ + ruff: RuffFindings; + /** The version each tool reported, out of the tools manifest. */ + toolVersions: Record; + /** vulture's findings, in the order it reported them. */ + vulture: VultureFinding[]; +} + /** A package the resolver could not take all the way to `latest`. */ export interface HeldBack { /** Why it could not go further. Empty means the engine gave no attributable reason. */ @@ -500,6 +592,54 @@ export interface RollbackPreview { unrestorable: string[]; } +/** One ruff finding. */ +export interface RuffFinding { + /** + * The rule code, e.g. `F401`. + * + * Optional because the field is not ours. ruff 0.16.0 always sets it — a syntax error comes + * through as `invalid-syntax` rather than null, which is **not** what CODE-HEALTH-SPEC §6 + * assumed — but tolerating null costs one `??` in the UI and stops a format change from + * failing every run. + */ + code?: string | null; + /** 1-based. */ + column: number; + /** Absolute, as ruff reports it. */ + filename: string; + /** Whether ruff offers a fix, and how confident it is in it. */ + fix?: FixApplicability | null; + /** ruff's message, verbatim. */ + message: string; + /** The rule slug, e.g. `unused-import`. */ + name: string; + /** 1-based. */ + row: number; + /** + * ruff's own documentation link. + * + * **Carried, never constructed.** The URL is keyed by rule *name*, so §6's + * `https://docs.astral.sh/ruff/rules/` 404s — `I001` lives at `.../unsorted-imports`. + * Null for a syntax error, which has no rule page. + */ + url?: string | null; +} + +/** ruff's findings and the two counts the fix path is built on. */ +export interface RuffFindings { + /** Every finding, in ruff's order. */ + findings: RuffFinding[]; + /** + * How many carry a **safe** fix — what `ruff check --fix` would actually apply. + * + * Counted here rather than in the UI because P5's confirm dialog and the CLI's prompt have to + * name the same number, and two implementations of "count the safe ones" will not stay equal. + */ + fixable: number; + /** How many distinct files those touch. The number P5's dialog names. */ + fixableFiles: number; +} + /** * The `.meta.json` sidecar (ARCHITECTURE §6). * @@ -530,6 +670,16 @@ export interface SnapshotMeta { trigger: Trigger; } +/** A file and, when the tool knew it, a position in it. */ +export interface SourceLocation { + /** 1-based. */ + column?: number | null; + /** Relative to the project folder where the tool reported it that way. */ + file: string; + /** 1-based. Absent for a whole-file finding such as an unused dependency in `pyproject.toml`. */ + line?: number | null; +} + /** What the user asked for: a name, optionally constrained. */ export interface Spec { /** Normalized distribution name. */ @@ -576,6 +726,23 @@ export type Stream = | 'stdout' | 'stderr'; +/** + * One tool that was asked to run and did not finish. + * + * Deliberately `PdError`-shaped so the UI can hand it straight to `PdErrorRow` rather than + * inventing a second error presentation for the same catalog codes. + */ +export interface ToolProblem { + /** The catalog code, so the row is localized from the same table as every other error. */ + code: Code; + /** Developer-facing detail. Never shown as-is (I18N §1). */ + message: string; + /** Tail of the tool's stderr, capped as ERROR-CATALOG §3 caps every other one. */ + stderrTail?: string | null; + /** Which tool: `deptry`, `vulture` or `ruff`. */ + tool: string; +} + /** What caused a snapshot to be taken. Shown as the trigger label on the timeline (UI-SPEC §4). */ export type Trigger = | { plan: { planId: string } } @@ -584,3 +751,24 @@ export type Trigger = /** A version string as the engine reported it. Never reshaped or localized (I18N §2). */ export type Version = string; + +/** + * One vulture finding. + * + * **vulture has no machine-readable output.** Its text form is + * `:: (% confidence)`, and `message` is `unused ''` for + * seven kinds and `unreachable code after ''` for the eighth — which is why `name` is + * optional rather than parsed out of every line. §5 has it required; amended. + */ +export interface VultureFinding { + /** vulture's confidence percentage. Below 100 is a candidate, not a fact (§6). */ + confidence: number; + /** 1-based. */ + line: number; + /** The whole message, verbatim. */ + message: string; + /** The identifier, when the message names one. */ + name?: string | null; + /** As vulture printed it, relative to the project folder. */ + path: string; +}