feat(core): a cancelled audit is a state, not an error

P4 deferred cancellation for Code Health on a measurement of 1.3 s. An audit measures
18-68 s, which is a different answer to the same question — long enough that stopping
one is an ordinary thing to want rather than an edge case.

P4 also recorded *why* wiring the token alone would be wrong: `exec` reports a cancel
and a crash through the same `Code::IntUnexpected`, so a stopped run would render
"PipDock hit an internal error". So the token is wired **and** mapped.
`AuditReport.cancelled` is a boolean on the report, the shape
`ExecutionSummary.cancelled` established — the user asking a run to stop is not a tool
failure, so nothing lands in `problems` and no catalog code is minted for something
that went right. The step ends `Skipped`, not `Failed`, per S1's rule that a step
killed by us is not a step that went wrong.

The test needs a real subprocess and says so: `audit_once` checks the executable exists
before it spawns anything, so a fake directory returns `PD-HLT-001` and never reaches
the token. It is `#[ignore]`d like `search_latency` and **was run** — cancelled 1.5 s
into the advisory fetch, returning `cancelled: true` with an empty `problems`. Then
mutation-checked: with the mapping disabled it fails on exactly the `PD-INT-001` path
P4 warned about, and passes again with it restored.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
poli0981andClaude Opus 5 committed 2026-08-18 10:55:11 +07:00
1 parent 63899f9499
commit 3463ff8d76
1 file changed
+72 -2
+72 -2
View File
@@ -256,6 +256,15 @@ pub struct AuditReport {
/// Why the run contributed nothing. Empty means it completed.
#[serde(default, skip_serializing_if = "Vec::is_empty")]
pub problems: Vec<ToolProblem>,
/// The user stopped it.
///
/// A **state, not an error**, which is the shape `ExecutionSummary.cancelled` established: the
/// user asking a run to stop is not a tool failure, so nothing lands in `problems` and no
/// catalog code is minted for something that went right. It matters here in a way it did not
/// for Code Health, whose runs are 1.3 s — an audit is 18-68 s, which is long enough that
/// stopping one is an ordinary thing to want.
#[serde(default)]
pub cancelled: bool,
}
impl AuditReport {
@@ -293,18 +302,25 @@ pub async fn run(
packages: 0,
advisories: Vec::new(),
problems: Vec::new(),
cancelled: false,
};
let step = sink.at(sink.step);
let name = PkgName::parse(TOOL)?;
step.started(Some(name.clone()), ExecMode::Isolated);
match audit_once(audit_dir, freeze).await {
match audit_once(audit_dir, freeze, sink).await {
Ok(audited) => {
report.packages = audited.packages;
report.advisories = audited.advisories;
step.finished(Some(name), ExecMode::Isolated, StepStatus::Ok);
}
// **Skipped, not Failed**, and no problem row — S1's rule that a step killed by us is not
// a step that went wrong, applied to the one operation long enough for anyone to kill.
Err(e) if is_cancellation(&e) => {
report.cancelled = true;
step.finished(Some(name), ExecMode::Isolated, StepStatus::Skipped);
}
Err(e) => {
report.problems.push(ToolProblem {
tool: TOOL.to_owned(),
@@ -325,7 +341,7 @@ pub async fn run(
/// # Errors
/// `PD-HLT-001` when the audit venv has no pip-audit, `PD-HLT-003` on its watchdog, `PD-HLT-002`
/// when stdout is not the promised document.
async fn audit_once(audit_dir: &Path, freeze: &str) -> Result<Audited> {
async fn audit_once(audit_dir: &Path, freeze: &str, sink: &ProgressSink) -> Result<Audited> {
let exe = tool_exe(audit_dir, TOOL);
if !exe.is_file() {
return Err(PdError::new(
@@ -343,6 +359,7 @@ async fn audit_once(audit_dir: &Path, freeze: &str) -> Result<Audited> {
let out = Command::new(&exe)
.args(argv(&freeze_path))
.timeout(AUDIT_TIMEOUT)
.cancel(sink.cancel.clone())
.run()
.await
.map_err(watchdog);
@@ -375,6 +392,16 @@ fn argv(freeze: &Path) -> Vec<String> {
]
}
/// Did the user stop it, or did it break?
///
/// `exec` reports both through `Code::IntUnexpected`, distinguished only by the message it built
/// (`exec::Command::stopped`). Reading the message is unlovely, and it is what P4 warned about
/// when it recorded that wiring the token alone would render *"PipDock hit an internal error"* for
/// a cancel — the mapping has to be done, not merely enabled.
fn is_cancellation(e: &PdError) -> bool {
e.code == Code::IntUnexpected && e.message.starts_with("cancelled:")
}
/// Translate `exec`'s vocabulary into this path's.
///
/// `exec` speaks the *engine's*, and two of its codes are actively wrong here: a watchdog is not
@@ -615,4 +642,47 @@ mod tests {
assert_eq!(report.advisories.len(), 8, "the fixture's count, live");
assert!(report.advisories.iter().all(|a| a.url.is_some()));
}
/// Cancelling one, against the real tool, because nothing smaller can.
///
/// `audit_once` checks the executable exists before it spawns anything, so a fake directory
/// returns `PD-HLT-001` and never reaches the token — the cancel path is only observable with
/// a tool that actually runs. Same opt-in as above.
#[tokio::test]
#[ignore = "needs a synced audit venv; run with --ignored and PIPDOCK_AUDIT_DIR"]
async fn a_cancelled_run_is_cancelled_rather_than_failed() {
let Ok(dir) = std::env::var("PIPDOCK_AUDIT_DIR") else {
panic!("set PIPDOCK_AUDIT_DIR to a directory holding a synced audit venv");
};
let (tx, _rx) = tokio::sync::mpsc::unbounded_channel();
let token = tokio_util::sync::CancellationToken::new();
let sink = ProgressSink::new(tx, AUDIT_STEPS, token.clone());
// Cancelled while the advisory fetch is in flight — the 18-68 s window this feature exists
// to make interruptible.
let stopper = tokio::spawn(async move {
tokio::time::sleep(std::time::Duration::from_millis(1500)).await;
token.cancel();
});
let report = run(
std::path::Path::new(&dir),
&a_python_env(),
"urllib3==2.0.0
",
&sink,
)
.await
.expect("a cancelled run still returns a report");
stopper.await.expect("stopper");
// The whole point of P4's warning: a cancel must not read as `PipDock hit an internal
// error`, which is what `PD-INT-001` renders as.
assert!(report.cancelled, "a stopped run says so");
assert!(
report.problems.is_empty(),
"a cancel is not a failure: {:?}",
report.problems
);
assert!(report.advisories.is_empty());
}
}