fix(health, audit, index, snapshot): what was previewed is what is fixed, and smaller holes

Code Health
- ruff --fix ran `check . --fix` with none of the exclusions the previewed run used (C4). Real
  ruff 0.17.1, verified: it rewrote every .ipynb in the tree - the preview excludes notebooks -
  and, in a project whose pyproject sets its own `exclude` (which replaces ruff's defaults), the
  files under .venv as well. The fix argv is now the read-only argv plus --fix, by construction;
  re-run against both cases, neither file changes.
- git status runs with -c core.fsmonitor=false (M40): a project folder that carries its own
  .git/config could name a program for `git status` to run, and asking "is it safe to write
  here" would have run it.
- One tool whose output cannot be read is that tool's problem, not the run's (H24). A `?` at the
  last step returned from the whole run, taking the other tools' findings with it.
- The fix's own failures speak Code Health's codes, and a timeout says files may already have
  been rewritten (M39). Project paths lose Windows' \?\ prefix, which every filename in the
  report carried (M47).

Security tab
- pip-audit is given pins, not the raw freeze (H21): one editable install failed the whole audit.

Index
- TLS failures read the error's source chain (M32): reqwest's top-level message never mentions
  the certificate, so PD-NET-002's guidance never showed.
- Typed, borrowing parse instead of a Value tree of 700k objects; the ingest runs on a blocking
  thread; connect/read timeouts replace a single 120 s total a slow link could exceed while
  making progress (M36). An empty project list is refused rather than ingested over the index
  (L55).

Snapshots
- Ids are fixed width and the list orders by created_at (M43): the timestamp's trimmed fraction
  made `…09-42Z` sort after `…09-4235606Z`. A sidecar whose id is not a PipDock id is ignored
  rather than used to build a freeze-file path (L54).

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 545e86bd31
commit 535b4c8707
8 files changed
+269 -47

No files matched your search

+3 -2
View File
@@ -1194,7 +1194,7 @@ pub async fn health(
print_health(opts, &report);
}
if fix {
return apply_fix(opts, &tools_dir, &project, &report).await;
return apply_fix(opts, &tools_dir, &project, &report, &run_opts).await;
}
Ok(if health::has_findings(&report) {
Exit::PartialFailure
@@ -1229,6 +1229,7 @@ async fn apply_fix(
tools_dir: &Path,
project: &Path,
report: &health::HealthReport,
run_opts: &health::RunOptions,
) -> Result<Exit> {
use pipdock_core::health::fix;
@@ -1286,7 +1287,7 @@ async fn apply_fix(
// process produced seconds ago, so there is no window between confirming and fixing for the
// tree to drift in. The consent is still built from what was actually observed.
let consent = fix::consent_ok(report.ruff.fixable_files, dirty.is_some(), dirty)?;
let fixed = fix::apply(tools_dir, project, &report.ruff, consent).await?;
let fixed = fix::apply(tools_dir, project, &report.ruff, consent, run_opts).await?;
if opts.json {
println!(
+10 -1
View File
@@ -354,7 +354,16 @@ async fn audit_once(audit_dir: &Path, freeze: &str, sink: &ProgressSink) -> Resu
// `--path <site-packages>` is rejected outright alongside `--no-deps`. Written to the system
// temp directory rather than into the user's project or the environment being audited, and
// removed when it drops, on every path.
let freeze_file = crate::exec::TempFile::create("pipdock-audit", "txt", freeze)?;
//
// **Pins only.** An editable install (`-e …`) or a direct reference (`name @ file:///…`) is a
// line pip-audit cannot look up on an index, and it failed the whole run over one: an
// environment with a single `pip install -e .` could not be audited at all (H21). They are not
// on PyPI, so they have no PyPI advisories; the package count says how many were audited.
let pins: String = crate::snapshot::parse_freeze(freeze)
.iter()
.map(|(name, version)| format!("{name}=={version}\n"))
.collect();
let freeze_file = crate::exec::TempFile::create("pipdock-audit", "txt", &pins)?;
let out = Command::python_tool(&exe)
.args(argv(freeze_file.path()))
+54 -3
View File
@@ -60,6 +60,11 @@ pub struct DirtyTree {
/// Checked rather than reasoned about, and re-check it if the process layer ever changes.
pub async fn dirty(project: &Path) -> Option<DirtyTree> {
let out = Command::new("git")
// **A repository can name a program for `git status` to run**: `core.fsmonitor` in its
// `.git/config`. A project folder the user downloaded rather than cloned carries its own
// `.git/config`, so asking "is it safe to write here" would have run whatever it named
// (M40). Overridden on the command line, which wins over every config file.
.args(["-c", "core.fsmonitor=false"])
.arg("--no-optional-locks")
.arg("status")
.arg("--porcelain")
@@ -234,7 +239,8 @@ pub async fn recheck(
.cwd(project)
.timeout(super::TOOL_TIMEOUT)
.run()
.await?;
.await
.map_err(|e| super::run::watchdog(e, "ruff"))?;
if !super::is_findings_exit("ruff", out.code) {
return Err(PdError::new(
Code::HltToolFailed,
@@ -267,6 +273,7 @@ pub async fn apply(
project: &Path,
before: &super::report::RuffFindings,
consent: FixConsent,
opts: &super::RunOptions,
) -> Result<FixReport> {
use super::report::FixApplicability;
@@ -289,11 +296,24 @@ pub async fn apply(
}
let out = Command::new(&exe)
.args(["check", ".", "--fix", "--output-format", "json"])
.args(fix_argv(opts))
.cwd(project)
.timeout(super::TOOL_TIMEOUT)
.run()
.await?;
.await
.map_err(|e| {
// Stopped part-way through is the one outcome a fix cannot report as nothing: ruff
// writes as it goes, so some files may already be rewritten.
let e = super::run::watchdog(e, "ruff");
if e.code == Code::HltTimeout {
PdError::new(
Code::HltTimeout,
format!("{} — some files may already have been rewritten", e.message),
)
} else {
e
}
})?;
if !super::is_findings_exit("ruff", out.code) {
return Err(PdError::new(
Code::HltToolFailed,
@@ -315,10 +335,41 @@ pub async fn apply(
})
}
/// The read-only run's argv plus `--fix` — **the same exclusions, by construction**.
///
/// The fix ran `check . --fix` with none of them (C4). The preview never looked inside `.venv`,
/// `node_modules` or a notebook, so the fix rewrote files nobody had been shown: site-packages,
/// and every `.ipynb` in the tree. `recheck` and the run share `ruff_argv`; now so does this.
fn fix_argv(opts: &super::RunOptions) -> Vec<String> {
let mut argv = super::run::ruff_argv(opts);
argv.push("--fix".to_owned());
argv
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn the_fix_excludes_everything_the_preview_excluded() {
let opts = super::super::RunOptions {
excludes: vec!["generated".to_owned()],
..super::super::RunOptions::default()
};
let read = super::super::run::ruff_argv(&opts);
let fix = fix_argv(&opts);
assert_eq!(
&fix[..read.len()],
read.as_slice(),
"the read-only argv, untouched"
);
assert_eq!(fix.last().map(String::as_str), Some("--fix"));
for excluded in ["*.ipynb", ".venv", "node_modules", "generated"] {
assert!(fix.iter().any(|a| a == excluded), "{excluded} is excluded");
}
assert!(!fix.iter().any(|a| a == "--unsafe-fixes"));
}
#[test]
fn a_frontend_claiming_a_clean_tree_against_a_dirty_one_is_refused() {
let found = Some(DirtyTree { entries: 3 });
+40 -2
View File
@@ -57,7 +57,7 @@ impl DeclaredSource {
/// # Errors
/// `PD-ENV-003` when the path is not a readable directory, or is inside `tools_dir`.
pub fn validate_project(project: &Path, tools_dir: &Path) -> Result<PathBuf> {
let canonical = project.canonicalize().map_err(|e| {
let canonical = project.canonicalize().map(plain).map_err(|e| {
PdError::new(
Code::EnvProbeFailed,
format!("cannot read {}: {e}", project.display()),
@@ -70,7 +70,7 @@ pub fn validate_project(project: &Path, tools_dir: &Path) -> Result<PathBuf> {
));
}
// Compared against the canonical tools path, or `..` walks straight past this.
if let Ok(tools) = tools_dir.canonicalize()
if let Ok(tools) = tools_dir.canonicalize().map(plain)
&& canonical.starts_with(&tools)
{
return Err(PdError::new(
@@ -84,6 +84,28 @@ pub fn validate_project(project: &Path, tools_dir: &Path) -> Result<PathBuf> {
Ok(canonical)
}
/// A canonical path without Windows' verbatim prefix.
///
/// `canonicalize` returns `\\?\C:\…`. Used as a tool's working directory, every filename ruff
/// and vulture reported came back under that prefix — on screen, in the saved report — and the
/// report's own project path read the same (M47). The drive and UNC forms are the only two a
/// project folder can take; anything else is returned untouched.
#[must_use]
pub fn plain(path: PathBuf) -> PathBuf {
let Some(text) = path.to_str() else {
return path;
};
if let Some(rest) = text.strip_prefix(r"\\?\UNC\") {
return PathBuf::from(format!(r"\\{rest}"));
}
if let Some(rest) = text.strip_prefix(r"\\?\")
&& rest.as_bytes().get(1) == Some(&b':')
{
return PathBuf::from(rest);
}
path
}
pub fn declared_source(project: &Path) -> Result<DeclaredSource> {
let unreadable = |e: &dyn std::fmt::Display| {
PdError::new(
@@ -228,4 +250,20 @@ mod tests {
fn write(dir: &Path, name: &str) {
std::fs::write(dir.join(name), "").expect("write");
}
#[test]
fn a_verbatim_path_comes_back_plain() {
assert_eq!(
plain(PathBuf::from(r"\\?\C:\Dự án\proj")),
PathBuf::from(r"C:\Dự án\proj")
);
assert_eq!(
plain(PathBuf::from(r"\\?\UNC\server\share\proj")),
PathBuf::from(r"\\server\share\proj")
);
assert_eq!(plain(PathBuf::from(r"C:\proj")), PathBuf::from(r"C:\proj"));
// A volume GUID path has no drive letter to fall back to, so it stays as it is.
let guid = r"\\?\Volume{0b1c2d3e-0000-0000-0000-000000000000}\proj";
assert_eq!(plain(PathBuf::from(guid)), PathBuf::from(guid));
}
}
+10 -4
View File
@@ -165,9 +165,15 @@ pub async fn run(
continue;
}
match run_one(tools_dir, project, opts, tool).await {
Ok(out) => {
collect(&mut report, tool, &out)?;
// A tool whose output cannot be read is that tool's problem, like one that cannot run. The
// `?` this replaced returned from the whole run, so one deptry format change took ruff's
// and vulture's findings with it — the skip-and-continue rule, broken at the last step
// (H24).
match run_one(tools_dir, project, opts, tool)
.await
.and_then(|out| collect(&mut report, tool, &out))
{
Ok(()) => {
step.finished(Some(name), ExecMode::Isolated, StepStatus::Ok);
}
Err(e) => {
@@ -378,7 +384,7 @@ fn collect(report: &mut HealthReport, tool: &str, stdout: &str) -> Result<()> {
///
/// Found by replacing a tool with a non-executable file of the same name — present, so the sync
/// check said Fresh, and unrunnable, so the run reached this path.
fn watchdog(e: PdError, tool: &str) -> PdError {
pub(super) fn watchdog(e: PdError, tool: &str) -> PdError {
if e.is_timeout() {
return PdError::new(
Code::HltTimeout,
+115 -29
View File
@@ -277,10 +277,12 @@ pub struct RefreshReport {
pub async fn refresh(app_data: &std::path::Path, now: jiff::Timestamp) -> Result<RefreshReport> {
let started = std::time::Instant::now();
let client = http_client()?;
let response = client
let response = shared_client()?
.get(SIMPLE_INDEX_URL)
.header("Accept", PEP691_ACCEPT)
// Tens of megabytes. The client's connect and read timeouts catch a dead connection; a
// slow one that is still delivering gets this long (M36).
.timeout(REFRESH_TIMEOUT)
.send()
.await
.map_err(|e| net_err("could not fetch the package index", &e))?;
@@ -298,34 +300,52 @@ pub async fn refresh(app_data: &std::path::Path, now: jiff::Timestamp) -> Result
.map_err(|e| net_err("could not read the package index", &e))?;
let wire_bytes = body.len();
let doc: serde_json::Value = serde_json::from_slice(&body).map_err(|e| {
// Typed, borrowing the names out of the body: a `serde_json::Value` of 700,000 objects is the
// whole document again in allocations, for a parse that only wants one field of each (M36).
#[derive(serde::Deserialize)]
struct Simple<'a> {
#[serde(borrow)]
projects: Vec<Project<'a>>,
}
#[derive(serde::Deserialize)]
struct Project<'a> {
#[serde(borrow)]
name: std::borrow::Cow<'a, str>,
}
let doc: Simple<'_> = serde_json::from_slice(&body).map_err(|e| {
PdError::new(
Code::NetIndexRefreshFailed,
format!("index is not JSON: {e}"),
format!("the package index is not the PEP 691 document: {e}"),
)
})?;
let projects = doc
.get("projects")
.and_then(serde_json::Value::as_array)
.ok_or_else(|| {
PdError::new(
Code::NetIndexRefreshFailed,
"index JSON has no `projects` array",
)
})?;
let rows: Vec<(String, String)> = projects
// An empty list is not an index, whatever said it was: a captive portal or a broken mirror.
// Ingesting it replaced every name with none, and search found nothing until the next week's
// refresh (L55).
if doc.projects.is_empty() {
return Err(PdError::new(
Code::NetIndexRefreshFailed,
"the package index listed no projects; the previous index is kept",
));
}
let rows: Vec<(String, String)> = doc
.projects
.iter()
.filter_map(|p| p.get("name")?.as_str())
.map(|name| (crate::model::normalize_name(name), name.to_owned()))
.map(|p| (crate::model::normalize_name(&p.name), p.name.to_string()))
.collect();
// Opened only now, after the download: the ingest is synchronous, so the handle never spans an
// await. Holding one open across a multi-second PyPI transfer would block every other command
// that wanted the store, for no benefit.
let store = Store::open(app_data)?;
ingest(&store, &rows)?;
store.set(KEY_LAST_REFRESH, &now.to_string())?;
// Opened only now, after the download, and on a blocking thread: hundreds of thousands of
// inserts are a second of synchronous work, which on an async worker stalls every other task
// scheduled there (M36). The handle never spans an await.
let app_data = app_data.to_path_buf();
let stamp = now.to_string();
let rows = tokio::task::spawn_blocking(move || -> Result<Vec<(String, String)>> {
let store = Store::open(&app_data)?;
ingest(&store, &rows)?;
store.set(KEY_LAST_REFRESH, &stamp)?;
Ok(rows)
})
.await
.map_err(|e| PdError::new(Code::IntUnexpected, format!("index ingest stopped: {e}")))??;
Ok(RefreshReport {
projects: rows.len(),
@@ -546,6 +566,9 @@ pub(crate) fn shared_client() -> Result<&'static reqwest::Client> {
Ok(CLIENT.get_or_init(|| client))
}
/// The whole-request ceiling for the index download, which is tens of megabytes.
const REFRESH_TIMEOUT: Duration = Duration::from_secs(600);
/// An HTTPS client restricted to PyPI's hosts.
///
/// SECURITY §4: certificate verification is always on and redirects may not leave `pypi.org` or
@@ -555,6 +578,11 @@ fn http_client() -> Result<reqwest::Client> {
reqwest::Client::builder()
.user_agent(concat!("pipdock/", env!("CARGO_PKG_VERSION")))
// A dead connection is caught by these; a request's own `.timeout` bounds the whole
// thing. One 120 s total used to cover both, which a slow link downloading the index
// could exceed while making progress the whole time (M36).
.connect_timeout(Duration::from_secs(15))
.read_timeout(Duration::from_secs(60))
.timeout(Duration::from_secs(120))
.redirect(reqwest::redirect::Policy::custom(|attempt| {
let host_ok = attempt.url().host_str().is_some_and(|h| {
@@ -573,15 +601,36 @@ fn http_client() -> Result<reqwest::Client> {
}
fn net_err(what: &str, e: &reqwest::Error) -> PdError {
// A TLS failure gets its own code because its guidance is different: corporate proxy or AV
// interception, and never "turn verification off" (SECURITY §4).
let text = e.to_string().to_ascii_lowercase();
let code = if text.contains("certificate") || text.contains("tls") || text.contains("ssl") {
let chain = error_chain(e);
PdError::new(net_code(&chain), format!("{what}: {chain}"))
}
/// An error and every `source()` beneath it, as one line.
///
/// reqwest's own message is "error sending request for url (…)"; the reason — refused, reset,
/// "invalid peer certificate: UnknownIssuer" — is in the chain beneath it, and reading only the
/// top made every TLS failure PD-NET-001, so PD-NET-002's corporate-proxy guidance never showed
/// (M32).
fn error_chain(e: &dyn std::error::Error) -> String {
let mut out = e.to_string();
let mut source = e.source();
while let Some(s) = source {
out.push_str(": ");
out.push_str(&s.to_string());
source = s.source();
}
out
}
/// A TLS failure gets its own code because its guidance is different: corporate proxy or AV
/// interception, and never "turn verification off" (SECURITY §4).
fn net_code(chain: &str) -> Code {
let text = chain.to_ascii_lowercase();
if text.contains("certificate") || text.contains("tls") || text.contains("ssl") {
Code::NetTlsFailure
} else {
Code::NetUnreachable
};
PdError::new(code, format!("{what}: {e}"))
}
}
#[cfg(test)]
@@ -809,4 +858,41 @@ mod tests {
.expect("write");
assert_eq!(last_refresh(&store).expect("read"), Some(now));
}
#[test]
fn a_tls_failure_below_a_generic_message_is_still_a_tls_failure() {
// reqwest says "error sending request"; the certificate is two sources down.
#[derive(Debug)]
struct Layer(&'static str, Option<Box<Layer>>);
impl std::fmt::Display for Layer {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.write_str(self.0)
}
}
impl std::error::Error for Layer {
fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
self.1.as_deref().map(|l| l as _)
}
}
let e = Layer(
"error sending request for url (https://pypi.org/simple/)",
Some(Box::new(Layer(
"client error (Connect)",
Some(Box::new(Layer(
"invalid peer certificate: UnknownIssuer",
None,
))),
))),
);
let chain = error_chain(&e);
assert!(
chain.ends_with("invalid peer certificate: UnknownIssuer"),
"{chain}"
);
assert_eq!(net_code(&chain), Code::NetTlsFailure);
assert_eq!(
net_code("error sending request: connection refused"),
Code::NetUnreachable
);
}
}
+36 -5
View File
@@ -407,10 +407,25 @@ pub fn create(
/// Snapshot ids sort lexicographically in time order, which is what makes `latest` cheap and the
/// timeline correct without reading every sidecar. Also filename-safe: no colons.
/// `20261016T145809-423560600Z`: fixed width, so ids sort as the times they name.
///
/// They were the timestamp with punctuation swapped out, and the timestamp drops trailing zeros
/// in its fraction — so `…09-42Z` (.42 s) sorted after `…09-4235606Z` (.4235606 s), and a snapshot
/// taken on an exact second sorted after every other one in that second (M43). [`list`] orders by
/// `created_at` either way, so ids written before this keep their place.
fn snapshot_id(now: jiff::Timestamp) -> String {
now.to_string()
.replace([':', '-'], "")
.replace(['.', '+'], "-")
format!(
"{}-{:09}Z",
now.strftime("%Y%m%dT%H%M%S"),
now.subsec_nanosecond()
)
}
/// An id is a filename stem PipDock wrote: digits, ASCII letters and `-`. A sidecar edited to
/// say anything else — `..\\..\\elsewhere` — is not a snapshot to load a freeze file through
/// (L54).
fn is_snapshot_id(id: &str) -> bool {
!id.is_empty() && id.bytes().all(|b| b.is_ascii_alphanumeric() || b == b'-')
}
/// List snapshots for an environment, newest first.
@@ -428,10 +443,13 @@ pub fn list(app_data: &Path, env_hash: &str) -> Result<Vec<Meta>> {
.flatten()
.filter(|e| e.file_name().to_string_lossy().ends_with(".meta.json"))
.filter_map(|e| std::fs::read_to_string(e.path()).ok())
.filter_map(|raw| serde_json::from_str(&raw).ok())
.filter_map(|raw| serde_json::from_str::<Meta>(&raw).ok())
.filter(|m| is_snapshot_id(&m.id))
.collect();
out.sort_by(|a: &Meta, b: &Meta| b.id.cmp(&a.id));
// Newest first, by the time each one records rather than by its id — see `snapshot_id`.
let when = |m: &Meta| m.created_at.parse::<jiff::Timestamp>().ok();
out.sort_by(|a: &Meta, b: &Meta| when(b).cmp(&when(a)).then_with(|| b.id.cmp(&a.id)));
Ok(out)
}
@@ -848,4 +866,17 @@ idna==3.4
let added: Vec<&str> = d.added.iter().map(|s| s.name.as_str()).collect();
assert_eq!(added, ["setuptools"]);
}
#[test]
fn ids_sort_as_the_times_they_name() {
let at = |t: &str| snapshot_id(t.parse().expect("timestamp"));
let exact = at("2026-10-16T14:58:09Z");
let early = at("2026-10-16T14:58:09.42Z");
let late = at("2026-10-16T14:58:09.4235606Z");
assert_eq!(late, "20261016T145809-423560600Z");
assert!(exact < early && early < late, "{exact} {early} {late}");
assert!(is_snapshot_id(&late));
assert!(!is_snapshot_id(r"..\\..\\elsewhere"));
assert!(!is_snapshot_id(""));
}
}
+1 -1
View File
@@ -1333,7 +1333,7 @@ pub async fn health_fix(
acknowledged_dirty,
fix::dirty(&session.project).await,
)?;
fix::apply(&tools_dir, &session.project, &fresh, consent).await
fix::apply(&tools_dir, &session.project, &fresh, consent, &opts).await
}
.await;