feat(engine): a resolve can be stopped, and pip's impossibility is a report

Engine::resolve takes a ResolveCtx: the flow's cancellation token, which now reaches the dry-run
command, and a GuardAdjust the flow will use for Force latest, Hold pins and Requires-Python
exclusions (pins replace a name in the request and the guard set, releases leave the guard set,
exclusions ride as `name!=v`). A stopped resolve is FlowStep::Nothing(Cancelled) - nothing
planned, nothing ran - instead of an error (H13).

pip's ResolutionImpossible was a hard error, so under pip one unsatisfiable package failed the
whole preview while uv offered a per-package Skip. The pip adapter now returns
report.impossible, built from pip's "Cannot install A and B" line (H15). The same request now
exits 2 under both engines.

Running it found a defect the requirement files introduced: pip names a requirement that came
from a file as "-r <temp path> (line N)", so the impossibility lost the package the user asked
for and every error row showed a temp path that had already been deleted.
RequirementFiles::humanize puts the line back; uv names requirements by their text and needs
none of it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5.5 committed 2026-10-17 00:55:27 +07:00
1 parent d2993bbd7d
commit 8b18dc4795
7 files changed
+361 -25

No files matched your search

+239 -12
View File
@@ -209,8 +209,16 @@ pub trait Engine: Send + Sync {
/// Dry-run resolve `req` against `env`, normalized into a [`ResolutionReport`].
///
/// This is the only way a plan may be produced; DATA-FLOW §9.1 forbids any mutating call
/// without a report accepted in the same session.
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport>;
/// without a report accepted in the same session. `ctx` carries the cancellation token —
/// a resolve used to be the one engine call nothing could stop, so *Stop* while pip
/// backtracked left it running for up to ten minutes — and what the flow changes about the
/// guard set (forced pins, holds, exclusions).
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport>;
/// Install an exact pinned set, holding everything in `set.constraints` where it is.
///
@@ -249,6 +257,32 @@ pub trait Engine: Send + Sync {
async fn upgrade_pip(&self, env: &PyEnv) -> Result<StepResult>;
}
/// What one resolve is given besides the request itself.
#[derive(Debug, Clone, Default)]
pub struct ResolveCtx {
/// Stops the dry run; a stopped resolve returns an error with `Stop::Cancelled`.
pub cancel: tokio_util::sync::CancellationToken,
/// What the flow changes about the requirement lines the engine is given.
pub adjust: GuardAdjust,
}
/// Changes to the requirement lines of a resolve, made by the flow — never by an adapter.
///
/// SP-1 makes the guard set (every installed package the user is not moving, pinned) the default,
/// and three decisions need to depart from it on purpose: **Force latest** pins a package to its
/// latest and *releases* the packages whose constraints were holding it (DISCLAIMER §2); a **Hold**
/// pin restates its own version; a release whose `Requires-Python` excludes this environment is
/// **excluded** so the engine picks another.
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct GuardAdjust {
/// Exact requirements added to the resolve; these names leave the upgrade list and the guard.
pub pins: Vec<PinnedSpec>,
/// Installed packages released from the guard set — what a forced package will break.
pub release: Vec<PkgName>,
/// `name!=version` lines, for releases that cannot install here.
pub exclude: Vec<PinnedSpec>,
}
/// One install invocation: what to install, and what must not move while it happens.
///
/// SP-1's rule — restate the installed set or the resolver breaks it — was applied to the
@@ -286,6 +320,9 @@ impl InstallSet {
pub struct RequirementFiles {
requirements: crate::exec::TempFile,
constraints: Option<crate::exec::TempFile>,
/// What each file says, line by line, so [`Self::humanize`] can put it back.
requirement_lines: Vec<String>,
constraint_lines: Vec<String>,
}
impl RequirementFiles {
@@ -294,31 +331,57 @@ impl RequirementFiles {
/// # Errors
/// As [`crate::exec::TempFile::create`].
pub fn write(requirements: &[String], constraints: &[PinnedSpec]) -> Result<Self> {
let lines = |items: &mut dyn Iterator<Item = String>| {
let mut text = items.collect::<Vec<_>>().join("\n");
let text = |lines: &[String]| {
let mut text = lines.join("\n");
text.push('\n');
text
};
let requirements = crate::exec::TempFile::create(
"pipdock-req",
"txt",
&lines(&mut requirements.iter().cloned()),
)?;
let constraints = if constraints.is_empty() {
let requirement_lines = requirements.to_vec();
let constraint_lines: Vec<String> =
constraints.iter().map(PinnedSpec::to_requirement).collect();
let requirements =
crate::exec::TempFile::create("pipdock-req", "txt", &text(&requirement_lines))?;
let constraints = if constraint_lines.is_empty() {
None
} else {
Some(crate::exec::TempFile::create(
"pipdock-con",
"txt",
&lines(&mut constraints.iter().map(PinnedSpec::to_requirement)),
&text(&constraint_lines),
)?)
};
Ok(Self {
requirements,
constraints,
requirement_lines,
constraint_lines,
})
}
/// Engine text with every reference to these files replaced by the line it points at.
///
/// pip names a requirement that came from a file as `-r <path> (line N)`. Once the plan went
/// through a file, its impossibility read `Cannot install -r C:\…\pipdock-req-….txt (line 1)
/// and h11==0.12.0`: the preview lost the name of the package the user asked for, and every
/// error row showed a path that had already been deleted. Found by running pip, not by
/// reading it — uv names requirements by their text and needs none of this.
#[must_use]
pub fn humanize(&self, text: &str) -> String {
let mut out = replace_file_refs(
text,
&format!("-r {}", self.requirements.path().display()),
&self.requirement_lines,
);
if let Some(c) = &self.constraints {
out = replace_file_refs(
&out,
&format!("-c {}", c.path().display()),
&self.constraint_lines,
);
}
out
}
/// `-r <requirements> [-c <constraints>]`, one argv entry each.
#[must_use]
pub fn args(&self) -> Vec<String> {
@@ -334,6 +397,44 @@ impl RequirementFiles {
}
}
/// `<reference> (line N)` becomes line N; `(from <reference> (line N))` goes entirely, since the
/// requirement it annotates is already named just before it.
fn replace_file_refs(text: &str, reference: &str, lines: &[String]) -> String {
let mut out = String::with_capacity(text.len());
let mut rest = text;
while let Some(at) = rest.find(reference) {
let (head, after) = rest.split_at(at);
let after = &after[reference.len()..];
let parsed = after.strip_prefix(" (line ").and_then(|tail| {
let digits = tail.bytes().take_while(u8::is_ascii_digit).count();
let n: usize = tail[..digits].parse().ok()?;
let close = tail[digits..].strip_prefix(')')?;
Some((n, close))
});
let Some((n, close)) = parsed else {
// Not a line reference; keep it as it was.
out.push_str(head);
out.push_str(reference);
rest = after;
continue;
};
if let (Some(before), Some(close)) = (head.strip_suffix("(from "), close.strip_prefix(')'))
{
out.push_str(before.strip_suffix(' ').unwrap_or(before));
rest = close;
continue;
}
out.push_str(head);
match n.checked_sub(1).and_then(|i| lines.get(i)) {
Some(line) => out.push_str(line),
None => out.push_str(&rest[at..rest.len() - close.len()]),
}
rest = close;
}
out.push_str(rest);
out
}
/// The adapter for `id`.
///
/// Both heads reach this point by different routes — the CLI from `--engine` or the stored
@@ -407,7 +508,27 @@ pub fn plan_requirements(req: &PlanRequest, installed: &[crate::model::Dist]) ->
/// Omitting group 3 is the SP-1 failure — the resolver breaks installed dependents at exit 0.
#[must_use]
pub fn plan_argv_specs(req: &PlanRequest, installed: &[crate::model::Dist]) -> Vec<String> {
let mut out: Vec<String> = req.upgrades.iter().map(ToString::to_string).collect();
plan_lines(req, installed, &GuardAdjust::default())
}
/// [`plan_argv_specs`] with the flow's [`GuardAdjust`] applied.
#[must_use]
pub fn plan_lines(
req: &PlanRequest,
installed: &[crate::model::Dist],
adjust: &GuardAdjust,
) -> Vec<String> {
use std::collections::BTreeSet;
let pinned: BTreeSet<&PkgName> = adjust.pins.iter().map(|p| &p.name).collect();
let released: BTreeSet<&PkgName> = adjust.release.iter().collect();
let mut out: Vec<String> = req
.upgrades
.iter()
.filter(|n| !pinned.contains(n))
.map(ToString::to_string)
.collect();
out.extend(req.installs.iter().map(|s| match &s.version_req {
Some(v) if v.starts_with(['=', '<', '>', '!', '~']) => format!("{}{v}", s.name),
@@ -415,11 +536,19 @@ pub fn plan_argv_specs(req: &PlanRequest, installed: &[crate::model::Dist]) -> V
None => s.name.to_string(),
}));
out.extend(adjust.pins.iter().map(PinnedSpec::to_requirement));
out.extend(
plan_requirements(req, installed)
.iter()
.filter(|g| !pinned.contains(&g.name) && !released.contains(&g.name))
.map(PinnedSpec::to_requirement),
);
out.extend(
adjust
.exclude
.iter()
.map(|e| format!("{}!={}", e.name, e.version)),
);
out
}
@@ -607,6 +736,62 @@ mod tests {
);
}
#[test]
fn a_forced_package_is_pinned_and_what_held_it_is_released() {
// Force latest (DISCLAIMER §2): httpcore goes to its latest *exactly*, and httpx — whose
// constraint was holding it — leaves the guard set, or the engine would hold it right back.
let installed = [
dist("httpx", "0.23.0"),
dist("httpcore", "0.15.0"),
dist("h11", "0.12.0"),
];
let req = PlanRequest {
upgrades: vec![PkgName::parse("httpcore").unwrap()],
installs: Vec::new(),
strategy: Strategy::Compatible,
};
let adjust = GuardAdjust {
pins: vec![PinnedSpec {
name: PkgName::parse("httpcore").unwrap(),
version: Version("1.0.9".into()),
}],
release: vec![PkgName::parse("httpx").unwrap()],
exclude: Vec::new(),
};
assert_eq!(
plan_lines(&req, &installed, &adjust),
["httpcore==1.0.9", "h11==0.12.0"]
);
}
#[test]
fn an_excluded_release_rides_alongside_the_request() {
// A release whose Requires-Python excludes this environment is ruled out by name, and the
// engine is left to pick the next one — PipDock still does not resolve (invariant 3).
let installed = [dist("httpx", "0.23.0"), dist("httpcore", "0.15.0")];
let req = PlanRequest {
upgrades: vec![PkgName::parse("httpcore").unwrap()],
installs: Vec::new(),
strategy: Strategy::Compatible,
};
let adjust = GuardAdjust {
exclude: vec![PinnedSpec {
name: PkgName::parse("httpcore").unwrap(),
version: Version("1.0.9".into()),
}],
..GuardAdjust::default()
};
assert_eq!(
plan_lines(&req, &installed, &adjust),
["httpcore", "httpx==0.23.0", "httpcore!=1.0.9"]
);
assert_eq!(
plan_lines(&req, &installed, &GuardAdjust::default()),
plan_argv_specs(&req, &installed),
"no adjustment is exactly the SP-1 default"
);
}
#[test]
fn updating_everything_still_asks_for_something() {
// With --all every package is moving, so the guard set is empty. If only guards were
@@ -727,4 +912,46 @@ mod tests {
"command line is {command_line} characters"
);
}
#[test]
fn pip_names_a_file_requirement_by_its_line_and_the_line_comes_back() {
// The sentence pip 26.2.1 printed when the plan went through a file, verbatim but for
// the path, which is this run's own.
let files = RequirementFiles::write(
&["httpcore>=1.0".to_owned(), "httpx==0.23.0".to_owned()],
&[PinnedSpec {
name: PkgName::parse("h11").unwrap(),
version: Version("0.12.0".into()),
}],
)
.expect("written");
let args = files.args();
let (req, con) = (&args[1], &args[3]);
let stderr = format!(
"ERROR: Cannot install -r {req} (line 1) and -r {req} (line 2) because these package \
versions have conflicting dependencies.\n\
ERROR: Could not find a version that satisfies the requirement httpcore>=1.0 \
(from -r {req} (line 1)) (from versions: none)\n\
The user requested (constraint) -c {con} (line 1)\n\
-r {req} (line 9) is not a line this run wrote\n"
);
let out = files.humanize(&stderr);
assert!(
out.contains("Cannot install httpcore>=1.0 and httpx==0.23.0 because"),
"{out}"
);
assert!(
out.contains("requirement httpcore>=1.0 (from versions: none)"),
"{out}"
);
assert!(out.contains("(constraint) h11==0.12.0"), "{out}");
assert!(
out.contains(&format!("-r {req} (line 9)")),
"an unknown line is left alone rather than invented: {out}"
);
// And the impossibility now names the package the user asked for.
let detail = parse::pip_impossible(&out).expect("impossible");
let names: Vec<&str> = detail.packages.iter().map(PkgName::as_str).collect();
assert_eq!(names, ["httpcore", "httpx"]);
}
}
+45
View File
@@ -175,6 +175,51 @@ pub fn pip_report(stdout: &str, stderr: &str, installed: &[Dist]) -> Result<Pars
})
}
/// pip's ResolutionImpossible, read into the shape uv's impossibility already has.
///
/// pip runs with `--quiet`, so its whole explanation is one line — `ERROR: Cannot install A and B
/// because these package versions have conflicting dependencies.` — followed by the
/// ResolutionImpossible pointer. The packages are the requirements that line names. `None` when
/// the stderr is not an impossibility at all, so the caller classifies it instead.
#[must_use]
pub fn pip_impossible(stderr: &str) -> Option<crate::plan::ImpossibleDetail> {
if crate::errors::classify_stderr(stderr) != crate::errors::Code::ResImpossible {
return None;
}
let line = stderr
.lines()
.map(str::trim)
.find(|l| l.contains("Cannot install "))
.or_else(|| {
stderr
.lines()
.map(str::trim)
.find(|l| l.starts_with("ERROR:"))
})?;
let explanation = line.trim_start_matches("ERROR:").trim().to_owned();
let mut packages = Vec::new();
if let Some(rest) = explanation.strip_prefix("Cannot install ")
&& let Some((named, _)) = rest.split_once(" because")
{
for token in named.split([',']).flat_map(|t| t.split(" and ")) {
let token = token.trim();
let end = token
.find(['=', '<', '>', '!', '~', '[', ' '])
.unwrap_or(token.len());
if let Ok(name) = PkgName::parse(&token[..end])
&& !packages.contains(&name)
{
packages.push(name);
}
}
}
Some(crate::plan::ImpossibleDetail {
packages,
explanation,
})
}
/// pip prints the yank reason on stderr, not in the report JSON.
fn yank_reason_from_stderr(stderr: &str, pkg: &PkgName) -> Option<String> {
let flat = flatten(stderr);
+25 -5
View File
@@ -14,7 +14,7 @@ use crate::model::{
};
use crate::plan::{PlanRequest, ResolutionReport};
use super::{Engine, InstallSet, ProgressSink, single_pkg};
use super::{Engine, InstallSet, ProgressSink, ResolveCtx, single_pkg};
/// Drives pip as a subprocess.
#[derive(Debug, Clone, Copy, Default)]
@@ -133,17 +133,36 @@ impl Engine for PipEngine {
super::parse::outdated_json(&out.stdout)
}
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport> {
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport> {
// SP-1: the installed set must be restated or the resolver ignores it and plans an
// upgrade that breaks installed dependents. The caller assembles that set into `req`.
let installed = self.list_installed(env).await?;
let files = super::RequirementFiles::write(&super::plan_argv_specs(req, &installed), &[])?;
let out = Command::python(&env.interpreter)
let lines = super::plan_lines(req, &installed, &ctx.adjust);
let files = super::RequirementFiles::write(&lines, &[])?;
let mut out = Command::python(&env.interpreter)
.args(Self::argv_dry_run(&files.args()))
.timeout(watchdog::RESOLVE)
.cancel(ctx.cancel.clone())
.run()
.await?;
out.stderr = files.humanize(&out.stderr);
if !out.ok() {
// **The same shape uv gives** (ARCHITECTURE §3). pip's ResolutionImpossible was a hard
// error, so under pip one unsatisfiable package in a fifteen-package request failed
// the whole preview and the per-package *Skip* the preview offers under uv never
// appeared.
if let Some(detail) = super::parse::pip_impossible(&out.stderr) {
return Ok(ResolutionReport {
impossible: Some(detail),
raw: out.stderr,
..ResolutionReport::default()
});
}
return Err(out.into_error());
}
super::parse::pip_report(&out.stdout, &out.stderr, &installed)
@@ -161,12 +180,13 @@ impl Engine for PipEngine {
let files = super::RequirementFiles::write(&requirements, &set.constraints)?;
let mut argv = vec!["-m".to_owned(), "pip".to_owned(), "install".to_owned()];
argv.extend(files.args());
let out = Command::python(&env.interpreter)
let mut out = Command::python(&env.interpreter)
.args(argv)
.timeout(watchdog::INSTALL)
.cancel(sink.cancel.clone())
.run_streaming(&sink, single_pkg(&set.specs), mode)
.await?;
out.stderr = files.humanize(&out.stderr);
Ok(super::step_result(&set.specs, &out))
}
+10 -3
View File
@@ -25,7 +25,7 @@ use crate::model::{
};
use crate::plan::{PlanRequest, ResolutionReport};
use super::{Engine, InstallSet, ProgressSink, single_pkg};
use super::{Engine, InstallSet, ProgressSink, ResolveCtx, single_pkg};
/// Drives uv as a subprocess.
#[derive(Debug, Clone, Copy, Default)]
@@ -138,15 +138,22 @@ impl Engine for UvEngine {
super::parse::outdated_json(&out.stdout)
}
async fn resolve(&self, env: &PyEnv, req: &PlanRequest) -> Result<ResolutionReport> {
async fn resolve(
&self,
env: &PyEnv,
req: &PlanRequest,
ctx: &ResolveCtx,
) -> Result<ResolutionReport> {
// SP-1: without the installed set restated, uv plans an upgrade that breaks installed
// dependents and exits 0. Identical requirement to pip's adapter.
let installed = self.list_installed(env).await?;
let files = super::RequirementFiles::write(&super::plan_argv_specs(req, &installed), &[])?;
let lines = super::plan_lines(req, &installed, &ctx.adjust);
let files = super::RequirementFiles::write(&lines, &[])?;
let python = env.interpreter.display().to_string();
let out = Command::new("uv")
.args(Self::argv_dry_run(&python, &files.args()))
.timeout(watchdog::RESOLVE)
.cancel(ctx.cancel.clone())
.run()
.await?;
// uv exits non-zero on an unsatisfiable set, but its message is the most useful thing it
+14 -1
View File
@@ -266,7 +266,20 @@ impl UpdateFlow {
/// Resolve the current request and classify what the caller must do next.
async fn resolve(&mut self) -> Result<FlowStep> {
let mut report = self.engine.resolve(&self.env, &self.req).await?;
let ctx = crate::engine::ResolveCtx {
cancel: self.cancel.clone(),
adjust: crate::engine::GuardAdjust::default(),
};
let mut report = match self.engine.resolve(&self.env, &self.req, &ctx).await {
Ok(report) => report,
// A stopped resolve planned nothing and ran nothing; it is not a failure to report.
Err(e) if e.is_cancelled() => {
return Ok(FlowStep::Nothing {
reason: NothingReason::Cancelled,
});
}
Err(e) => return Err(e),
};
plan::derive_held_back(&mut report, &self.req.upgrades, &self.outdated, &self.graph);
self.report = report;
+7 -2
View File
@@ -16,7 +16,7 @@
use std::sync::{Arc, Mutex};
use async_trait::async_trait;
use pipdock_core::engine::{Engine, InstallSet, ProgressEvent, ProgressSink};
use pipdock_core::engine::{Engine, InstallSet, ProgressEvent, ProgressSink, ResolveCtx};
use pipdock_core::errors::Result;
use pipdock_core::model::{
CheckFinding, CheckReport, Dist, EngineId, EngineInfo, EnvSource, ExecMode, OutdatedDist,
@@ -111,7 +111,12 @@ impl Engine for FakeEngine {
async fn list_outdated(&self, _env: &PyEnv) -> Result<Vec<OutdatedDist>> {
Ok(Vec::new())
}
async fn resolve(&self, _env: &PyEnv, _req: &PlanRequest) -> Result<ResolutionReport> {
async fn resolve(
&self,
_env: &PyEnv,
_req: &PlanRequest,
_ctx: &ResolveCtx,
) -> Result<ResolutionReport> {
Ok(ResolutionReport {
changes: Vec::new(),
held_back: Vec::new(),
+21 -2
View File
@@ -15,7 +15,7 @@
use std::fs;
use std::path::{Path, PathBuf};
use pipdock_core::engine::parse::{ParsedPlan, pip_report, uv_plan};
use pipdock_core::engine::parse::{ParsedPlan, pip_impossible, pip_report, uv_plan};
use pipdock_core::model::{Dist, PkgName, Version};
fn fixtures_root() -> PathBuf {
@@ -163,13 +163,32 @@ fn uv_impossibility_carries_an_explanation_a_user_can_act_on() {
fn pip_impossibility_is_recognised_even_though_it_says_less() {
// pip writes nothing to stdout when resolution fails, so the report parser must fail rather
// than silently returning an empty plan — an empty plan would render as "no changes" and the
// user would never learn the resolve failed.
// user would never learn the resolve failed. (The adapter no longer gets this far with an
// impossibility: it reads the exit status first and returns `pip_impossible`'s report.)
let cap = load("pip", "impossible").expect("fixture");
assert_eq!(cap.exit_code, 1);
let err = pip_report(&cap.stdout, &cap.stderr, &[]).expect_err("must not parse as empty plan");
assert_eq!(err.code.as_str(), "PD-ENG-002");
}
#[test]
fn pip_impossibility_becomes_the_same_shape_uv_gives() {
// Under pip an unsatisfiable set was a hard error, so the preview could not offer the
// per-package Skip it offers under uv. The adapter now returns this instead.
let cap = load("pip", "impossible").expect("fixture");
let detail = pip_impossible(&cap.stderr).expect("recognised as impossible");
let names: Vec<&str> = detail.packages.iter().map(PkgName::as_str).collect();
assert_eq!(names, ["httpcore", "httpx"]);
assert!(
detail.explanation.contains("conflicting dependencies"),
"{}",
detail.explanation
);
// And it does not claim a failure that is something else.
let not_found = load("pip", "not-found").expect("fixture");
assert!(pip_impossible(&not_found.stderr).is_none());
}
#[test]
fn both_engines_flag_the_yanked_release_without_failing() {
// SP-2: a yank exits 0 in both engines. The plan is valid; the warning rides alongside it.