@4da/mcp-server 6.2.4 → 6.2.5

package/dist/live/pinned-advisories.js

@@ -30,7 +30,7 @@ function nameKey(ecosystem, name) {
 /** Explicitly listed versions for one package of one record. */
 function listedVersions(vuln, name, ecosystem) {
     return (vuln.affected ?? [])
-        .filter((a) => a.package.ecosystem === ecosystem && samePackageName(a.package.name, name, ecosystem))
+        .filter((a) => a.package?.ecosystem === ecosystem && samePackageName(a.package.name, name, ecosystem))
         .flatMap((a) => a.versions ?? []);
 }
 export class PinnedRecordsSource {
@@ -40,7 +40,7 @@ export class PinnedRecordsSource {
     constructor(records) {
         for (const record of records) {
             this.byId.set(record.id, record);
-            const keys = new Set((record.affected ?? []).map((a) => `${a.package.ecosystem}\0${nameKey(a.package.ecosystem, a.package.name)}`));
+            const keys = new Set((record.affected ?? []).flatMap((a) => (a.package ? [`${a.package.ecosystem}\0${nameKey(a.package.ecosystem, a.package.name)}`] : [])));
             for (const key of keys) {
                 const list = this.byPackage.get(key);
                 if (list)
@@ -66,7 +66,7 @@ export class PinnedRecordsSource {
             .map((vuln) => vuln.id);
     }
     async query(deps) {
-        return deps.map((dep) => (dep.version === null ? [] : this.affecting(dep.ecosystem, dep.name, dep.version)));
+        return { ids: deps.map((dep) => (dep.version === null ? [] : this.affecting(dep.ecosystem, dep.name, dep.version))), failure: null };
     }
     async details(ids) {
         const out = new Map();

package/dist/live/pypi-advice.d.ts

@@ -0,0 +1,36 @@
+/**
+ * How a PyPI pin is moved, worded for how its requirements file is produced and installed
+ * (audit 6.2.5 A-4). Two kinds of advice installed nothing when run as written:
+ *
+ * - A compiled file (`uv pip compile`, `pip-compile`) pins the whole tree. Its `# via requests`
+ *   pins are transitive, and every pin is regenerated from the input (requirements.in,
+ *   pyproject.toml) on the next compile. "change `idna==2.7` to `idna==3.15` in requirements.txt"
+ *   conflicted with requests 2.19.1 (`idna<2.8`), and a hand edit is reverted anyway. The fix is a
+ *   re-compile with `--upgrade-package "idna==3.15"`, the checked target (a `>=` let the resolver
+ *   take a newer release nothing checked). uv 0.6.8 and pip-compile 7.6.2 both refuse to resolve
+ *   when a package that requires idna excludes 3.15 (run 2026-10-26 on Track A's hb-f6b fixture),
+ *   where a bare `--upgrade-package idna` silently kept 2.7.
+ * - A flat file that pins everything with `==`: each edit was presented as safe on its own, but 4
+ *   of pygoat's 15 do not resolve against the other pins (Django 5.2.17 needs asgiref>=3.8.1,
+ *   asgiref==3.6.0 is pinned), and neither does the full set. No resolver runs here, so the advice
+ *   says the edits must be re-resolved together; it never claims they are.
+ *
+ * A command is spliced only from plain tokens (audit 6.2.5 C-1); otherwise the words name no command.
+ */
+/**
+ * The advice for `name` at `installed` when a compiled requirements file in `projectDir` pins it;
+ * null when no compiled file does (the caller keeps its own advice). Both a declared pin and an
+ * indirect one are moved by re-compiling, never by editing the output.
+ */
+export declare function pypiCompiledInstruction(projectDir: string, name: string, installed: string, target: string): string | null;
+/**
+ * The sentence for an `==` edit of `name` in a flat file that pins every requirement exactly (two
+ * or more): its edits are not independently safe and must be resolved together. Null otherwise.
+ * The file is the first that pins it, in the order directFix reads them.
+ */
+export declare function pypiPinnedTogether(projectDir: string, name: string, installed: string): string | null;
+/**
+ * vulnerability_scan's short form, appended to "Upgrade X a → b": a compiled file is re-compiled
+ * and a fully pinned one re-resolved, never one `==` edit taken as safe alone (audit 6.2.5 A-4).
+ */
+export declare function pypiScanNote(projectDir: string, name: string, installed: string): string | null;

package/dist/live/pypi-advice.js

@@ -0,0 +1,158 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * How a PyPI pin is moved, worded for how its requirements file is produced and installed
+ * (audit 6.2.5 A-4). Two kinds of advice installed nothing when run as written:
+ *
+ * - A compiled file (`uv pip compile`, `pip-compile`) pins the whole tree. Its `# via requests`
+ *   pins are transitive, and every pin is regenerated from the input (requirements.in,
+ *   pyproject.toml) on the next compile. "change `idna==2.7` to `idna==3.15` in requirements.txt"
+ *   conflicted with requests 2.19.1 (`idna<2.8`), and a hand edit is reverted anyway. The fix is a
+ *   re-compile with `--upgrade-package "idna==3.15"`, the checked target (a `>=` let the resolver
+ *   take a newer release nothing checked). uv 0.6.8 and pip-compile 7.6.2 both refuse to resolve
+ *   when a package that requires idna excludes 3.15 (run 2026-10-26 on Track A's hb-f6b fixture),
+ *   where a bare `--upgrade-package idna` silently kept 2.7.
+ * - A flat file that pins everything with `==`: each edit was presented as safe on its own, but 4
+ *   of pygoat's 15 do not resolve against the other pins (Django 5.2.17 needs asgiref>=3.8.1,
+ *   asgiref==3.6.0 is pinned), and neither does the full set. No resolver runs here, so the advice
+ *   says the edits must be re-resolved together; it never claims they are.
+ *
+ * A command is spliced only from plain tokens (audit 6.2.5 C-1); otherwise the words name no command.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { compiledIndirect, compiledRequiredBy, compiledRequirements, confinedInclude, normalizePythonName, parseRequirements, requirementFiles, requirementOptions, } from "./lockfile-parsers-pygo.js";
+import { isShellSafeName, isShellSafeVersion } from "./shell-safe.js";
+/** A relative path of plain segments (`requirements.in`, `requirements/dev.txt`): no `..`, no root, no drive, nothing a shell expands. */
+function isPlainPath(file) {
+    return /^[A-Za-z0-9_][A-Za-z0-9_.-]*(?:\/[A-Za-z0-9_][A-Za-z0-9_.-]*)*$/.test(file) && !file.split("/").includes("..") && file.length <= 256;
+}
+function readText(file) {
+    try {
+        return fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+/** Requirement files that pin `name` at `installed`, relative to `projectDir`: the ones the scan reads, then their confined `-r` includes. */
+function filesPinning(projectDir, name, installed) {
+    const want = normalizePythonName(name);
+    const files = ["requirements.txt", "requirements-dev.txt", "requirements/base.txt"];
+    for (const f of requirementFiles(projectDir)) {
+        const rel = path.relative(projectDir, f).replace(/\\/g, "/");
+        if (!files.includes(rel))
+            files.push(rel);
+    }
+    const out = [];
+    for (let i = 0; i < files.length && i < 32; i++) {
+        const body = readText(path.join(projectDir, files[i]));
+        if (body === null)
+            continue;
+        if (parseRequirements(body).some((p) => p.name === want && p.version === installed))
+            out.push({ file: files[i], body });
+        for (const { option, target } of requirementOptions(body)) {
+            const included = option === "r" ? confinedInclude(path.dirname(path.join(projectDir, files[i])), target, projectDir) : null;
+            const rel = included ? path.relative(projectDir, included).replace(/\\/g, "/") : null;
+            if (rel && !files.includes(rel))
+                files.push(rel);
+        }
+    }
+    return out;
+}
+/** The input a compiled file names, when it is a plain path that exists inside the project (where the compile runs). */
+function presentInput(projectDir, compiled) {
+    const input = compiled.input;
+    if (!input || !isPlainPath(input))
+        return null;
+    const at = confinedInclude(projectDir, input, projectDir);
+    return at && fs.existsSync(at) ? input : null;
+}
+/** `uv pip compile` / `pip-compile` with the upgrade, when every spliced value is a plain token. */
+function compileCommand(tool, input, output, name, target) {
+    if (!isPlainPath(input) || !isPlainPath(output) || !isShellSafeName(name, "PyPI") || !isShellSafeVersion(target))
+        return null;
+    // Double quotes: `>` is a redirect outside them on every shell; cmd.exe keeps single quotes.
+    const upgrade = `--upgrade-package "${name}==${target}"`;
+    return tool === "uv" ? `uv pip compile ${input} -o ${output} ${upgrade}` : `pip-compile ${input} --output-file ${output} ${upgrade}`;
+}
+/**
+ * The advice for `name` at `installed` when a compiled requirements file in `projectDir` pins it;
+ * null when no compiled file does (the caller keeps its own advice). Both a declared pin and an
+ * indirect one are moved by re-compiling, never by editing the output.
+ */
+export function pypiCompiledInstruction(projectDir, name, installed, target) {
+    for (const { file, body } of filesPinning(projectDir, name, installed)) {
+        const compiled = compiledRequirements(body);
+        if (!compiled)
+            continue;
+        // Prose too carries only plain tokens: the target comes from advisory data, the rest from the repo.
+        const label = isShellSafeName(name, "PyPI") ? name : "this package";
+        const version = isShellSafeVersion(target) ? target : "the fixed release";
+        const safeFile = isPlainPath(file) ? file : "the requirements file";
+        const by = compiled.tool === "uv" ? " by `uv pip compile`" : compiled.tool === "pip-compile" ? " by `pip-compile`" : "";
+        const input = presentInput(projectDir, compiled);
+        const from = input ? ` from ${input}` : "";
+        const indirect = compiledIndirect(compiled, name);
+        const parents = compiledRequiredBy(compiled, name).filter((p) => isShellSafeName(p, "PyPI")).slice(0, 3);
+        const command = input && compiled.tool && isPlainPath(file) ? compileCommand(compiled.tool, input, file, name, target) : null;
+        const upgrade = isShellSafeName(name, "PyPI") && isShellSafeVersion(target) ? `\`--upgrade-package "${name}==${target}"\`` : "an `--upgrade-package` option for it";
+        const what = indirect
+            ? `${label} is not declared: ${safeFile} is compiled${by}${from} and pins it only because ${parents.length > 0 ? parents.join(", ") : "other packages"} require${parents.length === 1 ? "s" : ""} it`
+            : `${safeFile} is compiled${by}${from}, so a hand edit of it is reverted by the next compile${input ? `; make sure the ${label} requirement in ${input} admits ${version}` : `; make sure the ${label} requirement in the file it is compiled from admits ${version}`}`;
+        const instead = indirect ? " instead of editing it" : "";
+        const how = command
+            ? `${indirect ? "" : "then "}re-compile with the upgrade${instead}: \`${command}\`, keeping the other options its header records`
+            : compiled.tool
+                ? `${indirect ? "" : "then "}re-compile it${input ? "" : " from its input"} with ${upgrade}${instead}, keeping the options its header records`
+                : `${indirect ? "" : "then "}re-compile it with the tool that wrote it (\`uv pip compile\` or \`pip-compile\`) and ${upgrade}${instead}`;
+        const check = `the resolver refuses when ${indirect && parents.length > 0 ? parents.join(" or ") : "a package that requires it"} excludes ${version}; then raise ${indirect ? "that package" : "the one it names"} in the input as well, and put the other upgrades to ${safeFile} in the same compile (one --upgrade-package each)`;
+        return `${what}; ${how}. ${capitalise(check)}`;
+    }
+    return null;
+}
+function capitalise(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * The sentence for an `==` edit of `name` in a flat file that pins every requirement exactly (two
+ * or more): its edits are not independently safe and must be resolved together. Null otherwise.
+ * The file is the first that pins it, in the order directFix reads them.
+ */
+export function pypiPinnedTogether(projectDir, name, installed) {
+    const first = filesPinning(projectDir, name, installed)[0];
+    if (!first || compiledRequirements(first.body))
+        return null;
+    const { file, body } = first;
+    const pins = parseRequirements(body).length;
+    if (pins < 2 || pins !== requirementCount(body))
+        return null;
+    const where = isPlainPath(file) ? file : "the requirements file";
+    const check = isPlainPath(file) ? ` (\`uv pip compile ${file}\` prints the resolution and writes nothing; \`pip install --dry-run -r ${file}\` also checks)` : "";
+    return `${where} pins every requirement exactly, so this edit is not safe on its own: make every pin change to it together, re-resolve the file${check}, and raise any other pin the resolver reports as conflicting before installing`;
+}
+/** Requirement lines in a file (pins and ranges alike), options and comments aside. */
+function requirementCount(body) {
+    let n = 0;
+    for (const raw of body.replace(/\\\r?\n/g, " ").split(/\r?\n/)) {
+        const line = raw.replace(/(^|\s)#.*$/, "").trim();
+        if (line && !line.startsWith("-") && /^[A-Za-z0-9]/.test(line))
+            n++;
+    }
+    return n;
+}
+/**
+ * vulnerability_scan's short form, appended to "Upgrade X a → b": a compiled file is re-compiled
+ * and a fully pinned one re-resolved, never one `==` edit taken as safe alone (audit 6.2.5 A-4).
+ */
+export function pypiScanNote(projectDir, name, installed) {
+    const first = filesPinning(projectDir, name, installed)[0];
+    if (!first)
+        return null;
+    const where = isPlainPath(first.file) ? first.file : "the requirements file";
+    const compiled = compiledRequirements(first.body);
+    if (compiled) {
+        const input = presentInput(projectDir, compiled);
+        return `${where} is compiled${input ? ` from ${input}` : ""}: re-compile it with --upgrade-package instead of editing it${compiledIndirect(compiled, name) ? " (it is pinned only because other packages require it)" : ""}; upgrade_planner words the step`;
+    }
+    return pypiPinnedTogether(projectDir, name, installed) ? `${where} pins every requirement exactly: re-resolve it with the other pin changes before installing` : null;
+}

package/dist/live/rate-limiter.d.ts

@@ -5,6 +5,13 @@ export declare class RateLimiter {
     }>);
     canProceed(source: string): boolean;
     consume(source: string): boolean;
+    /**
+     * Take a token, waiting for one to refill when the bucket is empty, as long
+     * as it arrives by `deadline` (epoch ms). False when it would not: the
+     * caller then has no answer for that request and must say so, never treat
+     * it as an empty one.
+     */
+    acquire(source: string, deadline: number): Promise<boolean>;
     waitTimeMs(source: string): number;
     private refill;
 }

package/dist/live/rate-limiter.js

@@ -28,6 +28,22 @@ export class RateLimiter {
         bucket.tokens -= 1;
         return true;
     }
+    /**
+     * Take a token, waiting for one to refill when the bucket is empty, as long
+     * as it arrives by `deadline` (epoch ms). False when it would not: the
+     * caller then has no answer for that request and must say so, never treat
+     * it as an empty one.
+     */
+    async acquire(source, deadline) {
+        for (;;) {
+            if (this.consume(source))
+                return true;
+            const wait = Math.max(1, this.waitTimeMs(source));
+            if (Date.now() + wait > deadline)
+                return false;
+            await new Promise((resolve) => setTimeout(resolve, wait));
+        }
+    }
     waitTimeMs(source) {
         const bucket = this.buckets.get(source);
         if (!bucket)
@@ -46,7 +62,12 @@ export class RateLimiter {
     }
 }
 export const DEFAULT_RATE_LIMITS = {
-    osv: { maxPerMinute: 10 },
+    // querybatch requests (1,000 dependencies each). OSV.dev publishes no
+    // per-client limit for it and osv-scanner sends a tree's batches back to
+    // back; 10 a minute made any tree over 10,000 dependencies fail outright
+    // (D:\4DA\src-tauri, 10,568, reported 0 vulnerable on 2026-10-12). A burst
+    // of 60 covers 60,000 dependencies; past that a scan waits for tokens.
+    osv: { maxPerMinute: 60 },
     // Per-package advisory lists for fix-path checks (/v1/query), one request per vulnerable package.
     "osv-package": { maxPerMinute: 300 },
     // Fix-path lookups on registry CDNs (crates.io sparse index, abbreviated npm

package/dist/live/release-metadata.d.ts

@@ -51,6 +51,11 @@ export interface PackageReleaseIndex {
     /** When the package itself was first published, or null. */
     createdAt: string | null;
     releases: Record<string, ReleaseRecord>;
+    /**
+     * npm: the `latest` dist-tag. A package whose latest release is deprecated
+     * withdraws no deprecated release (withdrawn-releases.ts). Absent elsewhere.
+     */
+    latest?: string | null;
 }
 /** The outcome of one registry read: data, a definite "no such package", or "could not reach it". */
 export type RegistryLookup<T> = {

package/dist/live/resolution.d.ts

@@ -18,6 +18,7 @@
  */
 import { type FileSignature } from "./file-signature.js";
 import type { InstallDriftRecord, ResolutionSourceRecord, ResolvedDependency } from "./types.js";
+import type { LockfileProblem } from "./lockfile-types.js";
 /** The inputs of one resolution, kept so the same resolution can be re-run. */
 export interface ResolutionGroup {
     dir: string;
@@ -45,6 +46,8 @@ export interface GroupResolution {
         manifest: string;
         ranges: number;
     } | null;
+    /** Lockfiles present in this directory that could not be read, with the reason. */
+    problems: LockfileProblem[];
     signatures: Map<string, FileSignature>;
     resolvedAt: string;
 }

package/dist/live/resolution.js

@@ -35,7 +35,10 @@ export function resolveGroup(group) {
     // script in package.json must not throw away a scan of an unchanged lockfile.
     if (manifest && !readFiles.includes(manifest))
         signatures.delete(manifest);
-    let resolved = resolveVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets);
+    // Ruby and PHP: the lockfile (and composer.json) name the direct dependencies; the project scanner does not.
+    const deps = group.deps.length === 0 && group.devDeps.length === 0 && read.direct ? read.direct.deps : group.deps;
+    const devDeps = group.deps.length === 0 && group.devDeps.length === 0 && read.direct ? read.direct.devDeps : group.devDeps;
+    let resolved = resolveVersionsFrom(group.dir, deps, devDeps, ecosystem, read.versions, group.targets);
     // No lockfile: a ranged dependency's version is the range's floor, a label.
     const ranges = read.kind === "declared_ranges" ? read.ranges ?? new Map() : null;
     if (ranges && ranges.size > 0) {
@@ -57,14 +60,14 @@ export function resolveGroup(group) {
             signatures.set(file, signature);
     }
     const audit = [
-        ...resolveAuditVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets, resolved, read.instances),
+        ...resolveAuditVersionsFrom(group.dir, deps, devDeps, ecosystem, read.versions, group.targets, resolved, read.instances),
         ...driftAudit,
     ].filter((dep) => !dep.declaredRange);
     const sources = read.kind
         ? readFiles.map((file) => ({ path: file, kind: read.kind, mtimeMs: signatureMtime(signatures.get(file)) }))
         : [];
     const unresolved = ranges && ranges.size > 0 && read.source ? { manifest: read.source, ranges: ranges.size } : null;
-    return { group, resolved, audit, drift, source: sources[0] ?? null, sources, unresolved, signatures, resolvedAt };
+    return { group, resolved, audit, drift, source: sources[0] ?? null, sources, unresolved, problems: read.problems ?? [], signatures, resolvedAt };
 }
 /** True when any file the resolution depended on changed, appeared, or vanished. */
 export function groupIsStale(result) {

package/dist/live/scan-coverage.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Whether a vulnerability scan answered for every dependency it was given.
+ *
+ * Until 6.2.5 an OSV.dev outage, a 503, a timeout or the server's own rate
+ * limit turned a scan into `total_vulnerable_packages: 0`, flagged only by
+ * `_meta.offline` at the end of the answer, and dependency_health and
+ * upgrade_planner then scored and ranked that as a clean project (10,568
+ * dependencies of D:\4DA\src-tauri, 0 vulnerable, 2026-10-12). Every scan
+ * consumer now asks this module first, and an incomplete scan leads its
+ * answer with what was not checked.
+ */
+import type { VulnerabilityCoverage, VulnerabilityScanResult } from "./types.js";
+/** The reason given when live lookups are switched off. */
+export declare const LOOKUPS_DISABLED = "live lookups are disabled (FOURDA_OFFLINE=true)";
+/**
+ * Null when every dependency the scan was given has an advisory answer.
+ * Otherwise how many have none, and why. `result` null means no scan backs
+ * the answer at all: `expectedTotal` dependencies are then all unchecked.
+ */
+export declare function vulnerabilityCoverage(result: VulnerabilityScanResult | null, opts: {
+    enabled: boolean;
+    expectedTotal?: number;
+    notLoaded?: string;
+}): VulnerabilityCoverage | null;
+/** The first line an incomplete answer leads with. */
+export declare function notCheckedLine(reason: string, unchecked: number, total: number): string;

package/dist/live/scan-coverage.js

@@ -0,0 +1,70 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Whether a vulnerability scan answered for every dependency it was given.
+ *
+ * Until 6.2.5 an OSV.dev outage, a 503, a timeout or the server's own rate
+ * limit turned a scan into `total_vulnerable_packages: 0`, flagged only by
+ * `_meta.offline` at the end of the answer, and dependency_health and
+ * upgrade_planner then scored and ranked that as a clean project (10,568
+ * dependencies of D:\4DA\src-tauri, 0 vulnerable, 2026-10-12). Every scan
+ * consumer now asks this module first, and an incomplete scan leads its
+ * answer with what was not checked.
+ */
+/** The reason given when live lookups are switched off. */
+export const LOOKUPS_DISABLED = "live lookups are disabled (FOURDA_OFFLINE=true)";
+/**
+ * Null when every dependency the scan was given has an advisory answer.
+ * Otherwise how many have none, and why. `result` null means no scan backs
+ * the answer at all: `expectedTotal` dependencies are then all unchecked.
+ */
+export function vulnerabilityCoverage(result, opts) {
+    if (!result) {
+        const total = opts.expectedTotal ?? 0;
+        const reason = opts.enabled ? (opts.notLoaded ?? "the OSV.dev scan did not finish in time or OSV.dev was unreachable") : LOOKUPS_DISABLED;
+        return build(total, total, reason);
+    }
+    // A stub or an older result that says offline without a count answered for nothing.
+    const unchecked = result.unchecked ?? (result.offline ? result.totalScanned : 0);
+    const stale = result.staleAnswers ?? 0;
+    if (unchecked <= 0 && stale <= 0)
+        return null;
+    if (unchecked > 0) {
+        const gap = build(result.totalScanned, unchecked, result.uncheckedReason ?? "OSV.dev could not be queried");
+        return stale > 0 ? { ...gap, stale_dependencies: stale, note: `${gap.note} ${staleLine(result, stale)}` } : gap;
+    }
+    // Every dependency has an answer, but some only from an expired cache because the fresh query
+    // failed. That answer can predate an advisory, so it is not a current all-clear (audit 6.2.5
+    // B-2: dependency_check said `proceed` and the scan "0 vulnerable" on a 1 h old answer).
+    const reason = result.staleReason ?? "OSV.dev could not be queried";
+    return {
+        complete: false,
+        total_dependencies: result.totalScanned,
+        checked_dependencies: result.totalScanned,
+        unchecked_dependencies: 0,
+        stale_dependencies: stale,
+        reason,
+        note: `STALE: ${reason}. ${staleLine(result, stale)}`,
+    };
+}
+/** "N dependencies were answered only from an expired cached answer (the oldest fetched ...)". */
+function staleLine(result, stale) {
+    const n = stale.toLocaleString("en-US");
+    const oldest = result.staleOldestFetchedAt ? ` (the oldest fetched ${result.staleOldestFetchedAt} UTC)` : "";
+    return `${n} dependenc${stale === 1 ? "y was" : "ies were"} answered only from an expired cached answer${oldest}; an advisory published since would not show, so this is not a current all-clear. Call again once OSV.dev answers (force_refresh).`;
+}
+function build(total, unchecked, reason) {
+    return {
+        complete: false,
+        total_dependencies: total,
+        checked_dependencies: Math.max(0, total - unchecked),
+        unchecked_dependencies: unchecked,
+        reason,
+        note: notCheckedLine(reason, unchecked, total),
+    };
+}
+/** The first line an incomplete answer leads with. */
+export function notCheckedLine(reason, unchecked, total) {
+    const n = (x) => x.toLocaleString("en-US");
+    const scope = total > 0 ? `${n(unchecked)} of ${n(total)} dependencies have no vulnerability answer` : "no dependency has a vulnerability answer";
+    return `NOT CHECKED: ${reason} — ${scope}. Their absence from the findings means nothing: this is not a clean result. Call again once OSV.dev answers (force_refresh), or check them another way.`;
+}

package/dist/live/semver-utils.d.ts

@@ -9,6 +9,14 @@ export declare function parseSemver(version: string): [number, number, number] |
  * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
  */
 export declare function computeSemverDistance(current: string, latest: string): SemverDistance | null;
+/**
+ * Whether the suffix after MAJOR.MINOR.PATCH marks a prerelease. Semver: only
+ * `-` does; `+build` metadata is ignored for precedence, so `0.25.17+spec-1.1.0`
+ * (toml_edit) is a release, and `+incompatible` is a Go release. Until 6.2.5 a
+ * `+` counted as a prerelease, which named toml_edit 0.23.9 its latest stable.
+ * PEP 440 spellings (PyPI uses this too): `a`/`b`/`rc`/`alpha`/`beta`/`c`/`pre`
+ * and `.dev` mark a prerelease; `.post` and `+local` do not.
+ */
 export declare function isPreRelease(version: string): boolean;
 /**
  * Compare two versions by MAJOR.MINOR.PATCH. Returns 1 if a > b, -1 if a < b,

package/dist/live/semver-utils.js

@@ -5,6 +5,13 @@ export function parseSemver(version) {
         return null;
     return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
 }
+/** MAJOR[.MINOR[.PATCH]] at the start of a version, missing parts as 0; null without a leading number. */
+function parseLooseRelease(version) {
+    const match = version.replace(/^v/, "").match(/^(\d+)(?:\.(\d+))?(?:\.(\d+))?/);
+    if (!match)
+        return null;
+    return [parseInt(match[1]), parseInt(match[2] ?? "0"), parseInt(match[3] ?? "0")];
+}
 /**
  * How far `current` is behind `latest`. `label` is the kind of bump, by the
  * caret rules npm and Cargo apply: below 1.0 a minor bump is breaking (^0.8.6
@@ -14,8 +21,11 @@ export function parseSemver(version) {
  * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
  */
 export function computeSemverDistance(current, latest) {
-    const c = parseSemver(current);
-    const l = parseSemver(latest);
+    // Missing parts count as 0: PyPI and Go write `4.2` and `1.23`. Requiring three parts left
+    // Django 4.2 -> 5.2.17 and urllib3 1.23 -> 2.8.0 "unknown", which the planner counted as
+    // non-breaking (audit 6.2.5 A-3 / D-9).
+    const c = parseLooseRelease(current);
+    const l = parseLooseRelease(latest);
     if (!c || !l)
         return null;
     const major = l[0] - c[0];
@@ -30,8 +40,21 @@ export function computeSemverDistance(current, latest) {
         label = c[0] === 0 && c[1] === 0 ? "major" : "patch";
     return { major: Math.max(0, major), minor: Math.max(0, minor), patch: Math.max(0, patch), label };
 }
+/**
+ * Whether the suffix after MAJOR.MINOR.PATCH marks a prerelease. Semver: only
+ * `-` does; `+build` metadata is ignored for precedence, so `0.25.17+spec-1.1.0`
+ * (toml_edit) is a release, and `+incompatible` is a Go release. Until 6.2.5 a
+ * `+` counted as a prerelease, which named toml_edit 0.23.9 its latest stable.
+ * PEP 440 spellings (PyPI uses this too): `a`/`b`/`rc`/`alpha`/`beta`/`c`/`pre`
+ * and `.dev` mark a prerelease; `.post` and `+local` do not.
+ */
 export function isPreRelease(version) {
-    return /[-+]/.test(version.replace(/^v/, "").replace(/^\d+\.\d+\.\d+/, "").slice(0, 1));
+    const suffix = version.replace(/^v/, "").replace(/^\d+\.\d+\.\d+/, "").split("+")[0].toLowerCase();
+    if (suffix === "")
+        return false;
+    if (suffix.startsWith("-"))
+        return true;
+    return /^[._]?(?:a|b|c|rc|alpha|beta|pre|preview|dev)\d*/.test(suffix) && !/^[._-]?post/.test(suffix);
 }
 /**
  * Compare two versions by MAJOR.MINOR.PATCH. Returns 1 if a > b, -1 if a < b,

package/dist/live/severity-scope.d.ts

@@ -28,6 +28,19 @@ export interface DependencyScope {
     isDev: boolean;
     devScopeKnown: boolean;
 }
+/**
+ * Dev-only: EVERY installed path to this copy goes through dev dependencies (vulnerability_scan's
+ * `is_dev` with a known scope: a direct devDependency, or a transitive the lockfile marks dev).
+ * The one population `include_dev: false` leaves out, in vulnerability_scan, dependency_health and
+ * upgrade_planner alike. The three meant three things: health left out only direct
+ * devDependencies yet said "devDependencies left out" (NodeGoat: 82 vulnerable packages where 34
+ * are runtime), the scan kept 225 dev-only rows, and the planner dropped all 90 dev-only copies
+ * (final release audit of 6.2.5, finding 6).
+ */
+export declare function isDevOnlyCopy(d: {
+    isDev: boolean;
+    devScopeKnown?: boolean;
+}): boolean;
 /** Ordering for sorts and "at or above" filters; unknown ranks lowest. */
 export declare const SEVERITY_RANK: Record<SeverityTier, number>;
 /**
@@ -39,7 +52,7 @@ export declare const SEVERITY_RANK: Record<SeverityTier, number>;
  * transitive runtime high -> high.
  */
 export declare function scopeAdjustedSeverity(advisory: SeverityTier, scope: DependencyScope): SeverityTier;
-type ScopedEntry = Pick<VulnerabilityEntry, "severity" | "isDirect" | "isDev" | "devScopeKnown">;
+type ScopedEntry = Pick<VulnerabilityEntry, "severity" | "isDirect" | "isDev" | "devScopeKnown" | "malware">;
 /**
  * The grade a surface presents for one scan entry. A missing `isDirect`
  * (never produced today; defensive for foreign cache rows) is treated as
@@ -54,4 +67,16 @@ export declare function scopeAdjustmentReason(v: ScopedEntry): string | null;
 export type SeverityCounts = Record<SeverityTier, number>;
 /** Count entries per tier, using whichever tier function the caller names. */
 export declare function countBySeverity<T>(entries: T[], tierOf: (entry: T) => SeverityTier): SeverityCounts;
+/**
+ * The tier a finding RANKS by (the 4DA app's base urgency, severity vectors sv-004/sv-010/sv-019),
+ * then the scope rule, as presentedSeverity applies it: an ungraded advisory ranks medium, a
+ * malicious-package record (MAL-) at least high. A dev-only medium ranks low, as the scan presents
+ * it; the planner kept it at medium (final release audit, finding 2 and the 4DA severity parity).
+ */
+export declare function rankedSeverity(v: ScopedEntry & {
+    vulnId?: string;
+    aliases?: string[];
+    malware?: boolean;
+    summary?: string;
+}): Exclude<SeverityTier, "unknown">;
 export {};

package/dist/live/severity-scope.js

@@ -22,6 +22,19 @@
  * no discount without evidence. The advisory's own tier is never discarded;
  * surfaces carry it beside the presented grade as `advisory_severity`.
  */
+import { isMalware } from "./malware.js";
+/**
+ * Dev-only: EVERY installed path to this copy goes through dev dependencies (vulnerability_scan's
+ * `is_dev` with a known scope: a direct devDependency, or a transitive the lockfile marks dev).
+ * The one population `include_dev: false` leaves out, in vulnerability_scan, dependency_health and
+ * upgrade_planner alike. The three meant three things: health left out only direct
+ * devDependencies yet said "devDependencies left out" (NodeGoat: 82 vulnerable packages where 34
+ * are runtime), the scan kept 225 dev-only rows, and the planner dropped all 90 dev-only copies
+ * (final release audit of 6.2.5, finding 6).
+ */
+export function isDevOnlyCopy(d) {
+    return d.isDev === true && d.devScopeKnown === true;
+}
 const ONE_LEVEL_DOWN = {
     critical: "high",
     high: "medium",
@@ -59,6 +72,11 @@ export function scopeAdjustedSeverity(advisory, scope) {
  * direct, and a missing `devScopeKnown` as unknown: both mean no discount.
  */
 export function presentedSeverity(v) {
+    // An installed malicious copy is critical wherever it sits: a transitive or
+    // dev-only copy runs its install scripts all the same. The scan capped it at
+    // high for a transitive copy while the planner said critical (audit 6.2.5 D-3).
+    if (v.malware === true)
+        return "critical";
     return scopeAdjustedSeverity(v.severity, {
         isDirect: v.isDirect !== false,
         isDev: v.isDev === true,
@@ -87,3 +105,17 @@ export function countBySeverity(entries, tierOf) {
         counts[tierOf(entry)]++;
     return counts;
 }
+/**
+ * The tier a finding RANKS by (the 4DA app's base urgency, severity vectors sv-004/sv-010/sv-019),
+ * then the scope rule, as presentedSeverity applies it: an ungraded advisory ranks medium, a
+ * malicious-package record (MAL-) at least high. A dev-only medium ranks low, as the scan presents
+ * it; the planner kept it at medium (final release audit, finding 2 and the 4DA severity parity).
+ */
+export function rankedSeverity(v) {
+    // An installed malicious copy is critical (the 4DA lead, 2026-10-18), whatever its own grade.
+    if (v.malware === true || isMalware(v.vulnId ?? "", v.aliases ?? [], [], v.summary ?? ""))
+        return "critical";
+    const base = v.severity === "unknown" ? "medium" : v.severity;
+    const tier = presentedSeverity({ ...v, severity: base });
+    return tier === "unknown" ? "medium" : tier;
+}

package/dist/live/shell-safe.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Which values may be spliced into a command an agent is told to run.
+ *
+ * Package names, installed versions, Cargo dependency keys and `[target.'cfg(...)']`
+ * headers come from the scanned project's own files: a cloned repository controls
+ * them. upgrade_planner put a Cargo.toml target header inside `--target "..."`,
+ * where bash and PowerShell still expand `$(...)` and backticks, and a dependency
+ * key unquoted after `--rename` (audit 6.2.5 C-1). A command is named only when
+ * every spliced value is a plain token no shell (sh, bash, zsh, cmd.exe,
+ * PowerShell) reads specially; otherwise the caller falls back to words.
+ */
+export declare function isShellSafeName(name: string, ecosystem: string): boolean;
+export declare function isShellSafeVersion(version: string): boolean;
+/**
+ * A Cargo target header that can go inside double quotes on every shell. A `cfg` with a string
+ * literal (`cfg(target_os = "linux")`) cannot: its quotes end the argument early. It is left to
+ * the words, which was always the only correct answer for it.
+ */
+export declare function isShellSafeCargoTarget(target: string): boolean;