@4da/mcp-server 6.2.4 → 6.2.5

package/dist/live/shell-safe.js

@@ -0,0 +1,36 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * 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.
+ */
+/** npm (scoped or not), crates.io and PyPI names: letters, digits, `.`, `_`, `-`; npm's `@scope/`. */
+const PACKAGE_NAME = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\/)?[A-Za-z0-9][A-Za-z0-9._-]*$/;
+/** Go module paths: host/path segments of letters, digits, `.`, `_`, `~`, `-`. */
+const GO_MODULE = /^[A-Za-z0-9][A-Za-z0-9._~-]*(?:\/[A-Za-z0-9._~-]+)*$/;
+/** Versions as every supported ecosystem writes them: `1.2.3`, `v1.2.3`, `1.0.0-rc.1+build`, `2.0.0b1`. */
+const VERSION = /^v?[0-9A-Za-z][0-9A-Za-z.+_-]*$/;
+/** A Cargo target given as a plain triple (`x86_64-pc-windows-msvc`). */
+const TARGET_TRIPLE = /^[A-Za-z0-9_.-]+$/;
+/** A Cargo `cfg(...)` target with no string literals: `cfg(windows)`, `cfg(not(unix))`, `cfg(all(unix, target_pointer_width = 64))`. */
+const CFG_PLAIN = /^cfg\([A-Za-z0-9_(), =]*\)$/;
+export function isShellSafeName(name, ecosystem) {
+    return (ecosystem === "Go" ? GO_MODULE : PACKAGE_NAME).test(name) && name.length <= 214;
+}
+export function isShellSafeVersion(version) {
+    return VERSION.test(version) && version.length <= 128;
+}
+/**
+ * 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 function isShellSafeCargoTarget(target) {
+    return (TARGET_TRIPLE.test(target) || CFG_PLAIN.test(target)) && target.length <= 256;
+}

package/dist/live/types.d.ts

@@ -86,7 +86,8 @@ export interface OsvVulnerability {
         score: string;
     }>;
     affected?: Array<{
-        package: {
+        /** Optional in the OSV schema: an entry with only GIT ranges has no package (EEF-CVE-2026-56812). */
+        package?: {
             name: string;
             ecosystem: string;
         };
@@ -101,14 +102,20 @@ export interface OsvVulnerability {
         }>;
         /** Versions listed explicitly, in addition to (or instead of) the ranges. */
         versions?: string[];
+        /** RustSec puts `informational` (unmaintained | unsound | notice) here, per package. */
+        database_specific?: {
+            informational?: string;
+        };
     }>;
     references?: Array<{
         type: string;
         url: string;
     }>;
-    /** GitHub-advisory severity label: LOW | MODERATE | HIGH | CRITICAL. */
+    /** GitHub-advisory severity label: LOW | MODERATE | HIGH | CRITICAL; `cwe_ids` (CWE-506 = malicious code). */
     database_specific?: {
         severity?: string;
+        cwe_ids?: string[];
+        informational?: string;
     };
     /** Set (to an RFC3339 timestamp) when the advisory has been withdrawn/retracted. */
     withdrawn?: string;
@@ -126,6 +133,22 @@ export interface VulnerabilityEntry {
     aliases: string[];
     severity: "critical" | "high" | "medium" | "low" | "unknown";
     cvssScore: number | null;
+    /**
+     * Set when `severity` is not this record's own: it rates nothing (Go's
+     * records) and names a GHSA alias, whose rating it took (osv-scanner.ts
+     * rateFromAliases). The alias's id.
+     */
+    severityFrom?: string;
+    /** A malicious-package record (malware.ts isMalware: a MAL- id or alias, or CWE-506). */
+    malware?: boolean;
+    /**
+     * Whether the record makes this a maintenance notice for this package
+     * (maintenance.ts isMaintenanceRecord: a stated `informational` class decides, the
+     * wording only when none is stated). Absent only on foreign or stub entries, which
+     * fall back to the summary wording; the scan cache key moved to osv:v3 so entries
+     * cached by 6.2.4 without it are never read.
+     */
+    maintenance?: boolean;
     summary: string;
     fixedVersion: string | null;
     published: string;
@@ -164,10 +187,55 @@ export interface VulnerabilityScanResult {
         unknown: number;
     };
     vulnerabilities: VulnerabilityEntry[];
+    /** Dependencies OSV answered for and found no advisory on (unchecked ones are never counted clean). */
     cleanCount: number;
     scanDurationMs: number;
     cached: boolean;
+    /** True when any dependency has no advisory answer (`unchecked` > 0), or lookups are disabled. */
     offline: boolean;
+    /**
+     * Dependencies with NO advisory answer: OSV.dev could not be reached, failed,
+     * timed out, or the query budget ran out, and no earlier answer was cached.
+     * Their absence from `vulnerabilities` means nothing. Absent (= 0) on older
+     * stubs.
+     */
+    unchecked?: number;
+    /** Why `unchecked` dependencies have no answer, in words; null when every one was answered. */
+    uncheckedReason?: string | null;
+    /** Dependencies answered from an OSV answer older than the 1 h cache life, because a fresh query failed. */
+    staleAnswers?: number;
+    /** Why fresh answers were not had for the `staleAnswers` dependencies. */
+    staleReason?: string;
+    /** fetched_at (SQLite UTC, "YYYY-MM-DD HH:MM:SS") of the oldest stale answer used. */
+    staleOldestFetchedAt?: string | null;
+    /** Records rated from a GHSA alias, and those that name one but stay unknown (cap, time budget, no answer), with why. */
+    aliasSeverity?: AliasSeverityReport;
+}
+export interface AliasSeverityReport {
+    /** Records whose severity came from their GHSA alias. */
+    rated: number;
+    /** GHSA alias ids that could not be read (cap, time budget, no answer): they never lower a grade. */
+    unresolved: string[];
+    /** Record ids that name a GHSA alias and are still unknown: no alias of theirs could be read or graded. */
+    ungraded: string[];
+    /** Why `unresolved` or `ungraded` is not empty; null when both are. */
+    reason: string | null;
+}
+/** How much of a dependency set OSV actually answered for. */
+export interface VulnerabilityCoverage {
+    complete: false;
+    /** Dependencies sent for checking. */
+    total_dependencies: number;
+    /** Dependencies with an advisory answer (fresh or stale). */
+    checked_dependencies: number;
+    /** Dependencies with NO answer: nothing is known about their advisories. */
+    unchecked_dependencies: number;
+    /** Dependencies answered only from an expired cached answer (a fresh query failed); present when any were. */
+    stale_dependencies?: number;
+    /** Why, in words ("OSV.dev unreachable (fetch failed)", "live lookups disabled (FOURDA_OFFLINE=true)"). */
+    reason: string;
+    /** One line to read first; never a clean result. */
+    note: string;
 }
 export interface LiveHeadline {
     id: string;
@@ -213,6 +281,14 @@ export interface RegistryPackageInfo {
      * workspaces are listed comma-separated.
      */
     installedVersion?: string;
+    /**
+     * dependency_health: present when `latestStableVersion` is NOT offered as an upgrade: an advisory
+     * affects it or the registry withdrew it. The newest release above `currentVersion` that is
+     * neither (null when none), which `versionsBehind` is then measured to.
+     */
+    latestSafeVersion?: string | null;
+    /** dependency_health: why `latestStableVersion` is not offered, or that it could not be checked. */
+    latestStableNote?: string;
 }
 export interface SemverDistance {
     major: number;
@@ -224,7 +300,23 @@ export interface DependencyHealthResult {
     scannedAt: string;
     projectPath: string;
     ecosystemsScanned: string[];
+    /**
+     * Direct dependencies checked against their registries (the rows in
+     * `dependencies`; devDependencies only with include_dev). Freshness,
+     * deprecation and `outdatedCount` / `deprecatedCount` are over these.
+     */
     totalDeps: number;
+    /** Installed packages (direct and transitive) the vulnerability scan covered: what `vulnerableCount` ranges over. */
+    treeDeps?: number;
+    /** Of `vulnerableCount`, the packages a manifest declares directly. Null when the check is incomplete. */
+    vulnerableDirectCount?: number | null;
+    /** The penalties the score subtracts from 100, and how each is computed. Absent when the score is withheld. */
+    healthScoreBasis?: {
+        vulnerabilities: number;
+        outdated: number;
+        deprecated: number;
+        note: string;
+    };
     outdatedCount: number;
     deprecatedCount: number;
     /**
@@ -232,21 +324,55 @@ export interface DependencyHealthResult {
      * maintenance notice — the same set `vulnerability_scan` reports as
      * `total_vulnerable_packages`, so the two tools agree over one scan.
      */
-    vulnerableCount: number;
     /**
-     * Every advisory row the scan returned, before the platform and maintenance
-     * splits and before alias collapsing. Present so nothing is hidden by the
-     * `vulnerableCount` filter: the difference is platform-inactive packages and
-     * unmaintained-dependency notices.
+     * Distinct vulnerable packages across the full installed tree (`treeDeps`),
+     * the same set vulnerability_scan reports as `total_vulnerable_packages`
+     * for the same scope. It can exceed `totalDeps`, which counts direct
+     * dependencies only. Null when any dependency could not be checked.
+     */
+    vulnerableCount: number | null;
+    /**
+     * Distinct advisories the scan returned (records naming each other, such as
+     * a GHSA and its PYSEC twin, are one advisory per installed copy, as in
+     * vulnerability_scan), before the platform and maintenance splits. Present
+     * so nothing is hidden by the `vulnerableCount` filter: the difference is
+     * platform-inactive packages and unmaintained-dependency notices.
      */
     advisoryCount: number;
-    healthScore: number;
+    /** Null when vulnerability data is missing or incomplete: a score computed without it would read as healthier than it is. */
+    healthScore: number | null;
+    /**
+     * Why `healthScore` is null: OSV gave no answer for some dependencies, a
+     * lockfile could not be read, or nothing was resolved at all. Absent when
+     * there is a score.
+     */
+    withheldReason?: "vulnerability_data_incomplete" | "lockfile_unreadable" | "nothing_checked";
+    /**
+     * Present when the score is over the checked part only: a lockfile read with
+     * entries skipped (PARTIAL) or a requirements include refused (REFUSED).
+     * The counts are lower bounds; `notes` say what is missing.
+     */
+    scoreCoverage?: {
+        complete: false;
+        basis: "checked_part";
+        notes: string[];
+    };
+    /** Records graded from a GHSA alias, and those still unknown, as in vulnerability_scan's `_meta.alias_severity`. */
+    aliasSeverity?: AliasSeverityReport;
+    /** Present when the vulnerability check is incomplete: what was not checked and why. */
+    vulnerabilityCoverage?: VulnerabilityCoverage;
     dependencies: RegistryPackageInfo[];
+    /**
+     * Advisories (not packages) on the full tree by their own grade, over the same actionable set: the
+     * same counts as vulnerability_scan's `advisory_by_severity` for the same scope. `unknown` counts the
+     * ungraded ones, which were left out of every bucket before (pygoat: 186 counted of 187).
+     */
     vulnerabilitySummary: {
         critical: number;
         high: number;
         medium: number;
         low: number;
+        unknown: number;
     } | null;
     summary: string;
     scanDurationMs: number;

package/dist/live/version-compare.d.ts

@@ -25,13 +25,62 @@ interface Pep440 {
 }
 export declare function parsePep440(version: string): Pep440 | null;
 export declare function comparePep440(a: Pep440, b: Pep440): number;
+/**
+ * A Composer version as `VersionParser::normalize` reads it: an optional `v`,
+ * up to four (here: any number of) numeric parts padded with zeros, then a
+ * stability suffix. OSV's Packagist ranges use two-part bounds
+ * (`introduced: "6.4"`, symfony/process GHSA-r39x-jcww-82v6), which
+ * MAJOR.MINOR.PATCH could not read: compared as "equal" to everything, the
+ * 5.4 line's fix 5.4.51 counted as inside [6.4, 6.4.33) and the target jumped
+ * to 8.0.5 (readiness audit H2, 2026-10-16). `1.2` is `1.2.0.0`.
+ */
+interface ComposerVersion {
+    release: number[];
+    /** dev=0 < alpha=1 < beta=2 < RC=3 < stable=4 < patch=5. */
+    stability: number;
+    stabilityNum: number[];
+    /** A trailing `-dev` (`1.0.0-beta2-dev`): below the same version without it. */
+    dev: boolean;
+}
+export declare function parseComposerVersion(version: string): ComposerVersion | null;
+export declare function compareComposer(a: ComposerVersion, b: ComposerVersion): number;
+/**
+ * Gem::Version's canonical segments: `-` reads as `.pre.`, the text splits
+ * into runs of digits and letters, and trailing zeros of the release part
+ * and of the prerelease part are dropped, so `3.0` equals `3.0.0` (OSV's
+ * RubyGems bounds are two-part: rack GHSA-6xw4-3v39-52mm `introduced: "3.0"`).
+ */
+export declare function parseGemVersion(version: string): Array<number | string> | null;
+/** Gem::Version#<=>: a missing segment is 0, a letter run sorts below a number. */
+export declare function compareGem(a: Array<number | string>, b: Array<number | string>): number;
+/**
+ * A version as the ecosystem itself writes it, for output. Go module versions always carry a `v`
+ * (go.mod, `go get`), while OSV's Go ranges and the proxy list read here do not: targetVersion
+ * 0.60.0 sat beside currentVersion v0.60.0's line (final release audit of 6.2.5, 7e). Every other
+ * ecosystem is returned as it is.
+ */
+export declare function inEcosystemForm<T extends string | null | undefined>(ecosystem: string, version: T): T;
 /** Whether `version` is readable for this ecosystem's ordering. */
 export declare function isComparable(version: string, ecosystem: OsvEcosystem | string): boolean;
+/** Whether a readable version is a prerelease in Composer's or Gem::Version's own terms; null for other ecosystems or unreadable text. */
+export declare function isComposerOrGemPrerelease(version: string, ecosystem: OsvEcosystem | string): boolean | null;
 /**
  * Order two versions of one ecosystem: 1, -1, or 0 for equal OR unreadable
  * (the same contract as compareSemver, so an unreadable bound never decides).
  */
 export declare function compareVersions(a: string, b: string, ecosystem: OsvEcosystem | string): number;
+/**
+ * `version` against an advisory window's LOWER bound (`introduced`). As
+ * Composer reads a constraint, a Packagist bound with no stability suffix
+ * opens at that release's dev stability (`>=8.0` is `>= 8.0.0.0-dev`), so the
+ * line's own prereleases are inside it: GHSA-r39x-jcww-82v6 opens at `8.0`
+ * and lists v8.0.0-BETA1 and v8.0.0-RC1 as affected. Compared as a plain
+ * version they fell below it (review of 6.2.5 H2, 2026-10-18). The upper
+ * bound keeps the plain order on purpose: a prerelease of the fix release
+ * (8.0.5-RC1) stays affected, the safe reading (Composer would exclude it).
+ * Every other ecosystem: compareVersions.
+ */
+export declare function compareToLowerBound(version: string, bound: string, ecosystem: OsvEcosystem | string): number;
 /** Highest of `versions` in this ecosystem's order, or null when empty. */
 export declare function maxVersion(versions: string[], ecosystem: OsvEcosystem | string): string | null;
 /** Package-name equality as the ecosystem's registry defines it. */

package/dist/live/version-compare.js

@@ -77,10 +77,95 @@ function compareLocal(a, b) {
     }
     return Math.sign(a.length - b.length);
 }
+const COMPOSER = /^v?(\d+(?:\.\d+){0,3})(?:[._-]?(stable|beta|b|alpha|a|rc|patch|pl|p)((?:[.-]?\d+)*))?(?:[.-]?(dev))?(?:\+[0-9a-z.-]+)?$/i;
+const COMPOSER_RANK = { alpha: 1, a: 1, beta: 2, b: 2, rc: 3, stable: 4, patch: 5, pl: 5, p: 5 };
+export function parseComposerVersion(version) {
+    const m = COMPOSER.exec(version.trim());
+    if (!m)
+        return null;
+    const token = m[2]?.toLowerCase();
+    const devOnly = !token && m[4] !== undefined;
+    return {
+        release: m[1].split(".").map(Number),
+        stability: devOnly ? 0 : token ? COMPOSER_RANK[token] : 4,
+        stabilityNum: m[3] ? m[3].split(/[.-]/).filter(Boolean).map(Number) : [],
+        dev: !devOnly && m[4] !== undefined,
+    };
+}
+function comparePadded(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x !== y)
+            return x > y ? 1 : -1;
+    }
+    return 0;
+}
+export function compareComposer(a, b) {
+    const byRelease = comparePadded(a.release, b.release) || Math.sign(a.stability - b.stability);
+    if (byRelease !== 0)
+        return byRelease;
+    // A bare tag sorts below a numbered one: `beta` < `beta0` (composer/semver, by version_compare).
+    const bareA = a.stabilityNum.length === 0;
+    const bareB = b.stabilityNum.length === 0;
+    if (bareA !== bareB)
+        return bareA ? -1 : 1;
+    return comparePadded(a.stabilityNum, b.stabilityNum) || (a.dev === b.dev ? 0 : a.dev ? -1 : 1);
+}
+// ---------------------------------------------------------------------------
+// Gem::Version (RubyGems)
+// ---------------------------------------------------------------------------
+/** Gem::Version::ANCHORED_VERSION_PATTERN. */
+const GEM = /^[0-9]+(?:\.[0-9a-zA-Z]+)*(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+/**
+ * Gem::Version's canonical segments: `-` reads as `.pre.`, the text splits
+ * into runs of digits and letters, and trailing zeros of the release part
+ * and of the prerelease part are dropped, so `3.0` equals `3.0.0` (OSV's
+ * RubyGems bounds are two-part: rack GHSA-6xw4-3v39-52mm `introduced: "3.0"`).
+ */
+export function parseGemVersion(version) {
+    const v = version.trim();
+    if (!GEM.test(v))
+        return null;
+    const segments = (v.replace(/-/g, ".pre.").match(/[0-9]+|[a-z]+/gi) ?? []).map((s) => (/^\d/.test(s) ? Number(s) : s));
+    const firstString = segments.findIndex((s) => typeof s === "string");
+    const cut = firstString < 0 ? segments.length : firstString;
+    const trim = (part) => {
+        let end = part.length;
+        while (end > 0 && part[end - 1] === 0)
+            end--;
+        return part.slice(0, end);
+    };
+    return [...trim(segments.slice(0, cut)), ...trim(segments.slice(cut))];
+}
+/** Gem::Version#<=>: a missing segment is 0, a letter run sorts below a number. */
+export function compareGem(a, b) {
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const x = a[i] ?? 0;
+        const y = b[i] ?? 0;
+        if (x === y)
+            continue;
+        if (typeof x !== typeof y)
+            return typeof x === "string" ? -1 : 1;
+        return x > y ? 1 : -1;
+    }
+    return 0;
+}
 // ---------------------------------------------------------------------------
 // Dispatch
 // ---------------------------------------------------------------------------
 const stripGoV = (v) => v.replace(/^v(?=\d)/, "");
+/**
+ * A version as the ecosystem itself writes it, for output. Go module versions always carry a `v`
+ * (go.mod, `go get`), while OSV's Go ranges and the proxy list read here do not: targetVersion
+ * 0.60.0 sat beside currentVersion v0.60.0's line (final release audit of 6.2.5, 7e). Every other
+ * ecosystem is returned as it is.
+ */
+export function inEcosystemForm(ecosystem, version) {
+    if (ecosystem !== "Go" || typeof version !== "string" || !/^\d/.test(version))
+        return version;
+    return `v${version}`;
+}
 /** Whether `version` is readable for this ecosystem's ordering. */
 export function isComparable(version, ecosystem) {
     if (version === "0")
@@ -93,10 +178,26 @@ export function isComparable(version, ecosystem) {
         case "npm":
         case "crates.io":
             return parseSemverPrecedence(version) !== null;
+        case "Packagist":
+            return parseComposerVersion(version) !== null;
+        case "RubyGems":
+            return parseGemVersion(version) !== null;
         default:
             return parseSemver(version) !== null;
     }
 }
+/** Whether a readable version is a prerelease in Composer's or Gem::Version's own terms; null for other ecosystems or unreadable text. */
+export function isComposerOrGemPrerelease(version, ecosystem) {
+    if (ecosystem === "Packagist") {
+        const c = parseComposerVersion(version);
+        return c ? c.stability < 4 || c.dev : null;
+    }
+    if (ecosystem === "RubyGems") {
+        const g = parseGemVersion(version);
+        return g ? g.some((s) => typeof s === "string") : null;
+    }
+    return null;
+}
 /**
  * Order two versions of one ecosystem: 1, -1, or 0 for equal OR unreadable
  * (the same contract as compareSemver, so an unreadable bound never decides).
@@ -119,10 +220,40 @@ export function compareVersions(a, b, ecosystem) {
         case "npm":
         case "crates.io":
             return compareVersionPrecedence(a, b) ?? compareSemver(a, b);
+        case "Packagist": {
+            const ca = parseComposerVersion(a);
+            const cb = parseComposerVersion(b);
+            return ca && cb ? compareComposer(ca, cb) : 0;
+        }
+        case "RubyGems": {
+            const ga = parseGemVersion(a);
+            const gb = parseGemVersion(b);
+            return ga && gb ? compareGem(ga, gb) : 0;
+        }
         default:
             return compareSemver(a, b);
     }
 }
+/**
+ * `version` against an advisory window's LOWER bound (`introduced`). As
+ * Composer reads a constraint, a Packagist bound with no stability suffix
+ * opens at that release's dev stability (`>=8.0` is `>= 8.0.0.0-dev`), so the
+ * line's own prereleases are inside it: GHSA-r39x-jcww-82v6 opens at `8.0`
+ * and lists v8.0.0-BETA1 and v8.0.0-RC1 as affected. Compared as a plain
+ * version they fell below it (review of 6.2.5 H2, 2026-10-18). The upper
+ * bound keeps the plain order on purpose: a prerelease of the fix release
+ * (8.0.5-RC1) stays affected, the safe reading (Composer would exclude it).
+ * Every other ecosystem: compareVersions.
+ */
+export function compareToLowerBound(version, bound, ecosystem) {
+    if (ecosystem === "Packagist" && bound !== "0") {
+        const v = parseComposerVersion(version);
+        const b = parseComposerVersion(bound);
+        if (v && b && b.stability === 4 && !/stable/i.test(bound))
+            return compareComposer(v, { ...b, stability: 0, stabilityNum: [], dev: false });
+    }
+    return compareVersions(version, bound, ecosystem);
+}
 /** Highest of `versions` in this ecosystem's order, or null when empty. */
 export function maxVersion(versions, ecosystem) {
     if (versions.length === 0)

package/dist/live/withdrawn-releases.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which releases a registry has withdrawn, so that no fix target is ever one
+ * of them (4DA FX-H5, the app's `osv/release_facts.rs`; the rule the shared
+ * fix_target vectors pin, README "Optional fix_target registry fields").
+ *
+ * - crates.io: `yanked`.
+ * - PyPI: a release whose every file is `yanked` (PEP 592).
+ * - npm: `deprecated`, but ONLY when a later, non-deprecated, stable release
+ *   exists on the same caret line (same major; same minor for 0.x). npm's
+ *   `deprecated` is often a whole-major "please upgrade" notice rather than a
+ *   withdrawn release: glob deprecates 160 of its 168 versions ("Old versions
+ *   of glob are not supported"), 10.5.0 included, and excluding them all sent
+ *   glob 10.4.5 to 12.0.0, a major jump. lodash 4.18.0 ("Bad release") is
+ *   excluded because 4.18.1 is clean on 4.x. A package whose `latest` is
+ *   itself deprecated (retired whole) excludes nothing.
+ *
+ * Pure functions; the registry readers (fix-paths.ts, npm-packument.ts) call
+ * them on what they already fetched.
+ */
+import type { PackageReleaseIndex } from "./release-metadata.js";
+/**
+ * dependency_check's view: every release of `index` that is never a candidate, with the
+ * registry's words. Withdrawn records (crates.io/PyPI yanked, npm unpublished, Go retracted:
+ * none of them installable as asked) plus the npm deprecations the rule above withdraws.
+ */
+export declare function excludedReleases(index: PackageReleaseIndex): Map<string, string>;
+/** npm's per-version `deprecated`: a non-empty message, or `true` (the app's `npm_deprecated`). */
+export declare function isNpmDeprecated(value: unknown): boolean;
+/**
+ * The npm releases to exclude as fix targets, from a packument's `versions`
+ * (version -> its `deprecated`) and `dist-tags.latest` (see the module notes).
+ */
+export declare function npmExcludedVersions(deprecation: Record<string, unknown>, latest: string | null | undefined): string[];
+/** How a registry names a withdrawal, for the release `version`. */
+export declare function withdrawalText(ecosystem: string, version: string, detail?: string | null): string;
+/**
+ * The withdrawn releases in plain words, releases with the same reason said once:
+ * "7.5.3, 7.5.4 and 7.5.5 are deprecated on npm ("Old versions of tar ...")".
+ */
+export declare function sayWithdrawn(versions: string[], why: Record<string, string>, ecosystem: string): string;
+/**
+ * The plain-words note for a target moved past withdrawn releases, or for no
+ * target because every release that would fix it was withdrawn (the app's
+ * Upgrade Plan wording: "No installable fix").
+ *   "4.18.0 is deprecated on npm ("Bad release..."); 4.18.1 is the smallest clean release"
+ *   "No installable fix: 0.3.17 is yanked on crates.io, and no later release is known to clear it"
+ * `why` holds the registry's own text per withdrawn release (withdrawalText).
+ * `clean: false`: the target clears only the advisories a release fixes.
+ */
+export declare function withheldNote(withheld: string[], target: string | null, why: Record<string, string>, ecosystem: string, clean?: boolean): string | null;

package/dist/live/withdrawn-releases.js

@@ -0,0 +1,125 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Which releases a registry has withdrawn, so that no fix target is ever one
+ * of them (4DA FX-H5, the app's `osv/release_facts.rs`; the rule the shared
+ * fix_target vectors pin, README "Optional fix_target registry fields").
+ *
+ * - crates.io: `yanked`.
+ * - PyPI: a release whose every file is `yanked` (PEP 592).
+ * - npm: `deprecated`, but ONLY when a later, non-deprecated, stable release
+ *   exists on the same caret line (same major; same minor for 0.x). npm's
+ *   `deprecated` is often a whole-major "please upgrade" notice rather than a
+ *   withdrawn release: glob deprecates 160 of its 168 versions ("Old versions
+ *   of glob are not supported"), 10.5.0 included, and excluding them all sent
+ *   glob 10.4.5 to 12.0.0, a major jump. lodash 4.18.0 ("Bad release") is
+ *   excluded because 4.18.1 is clean on 4.x. A package whose `latest` is
+ *   itself deprecated (retired whole) excludes nothing.
+ *
+ * Pure functions; the registry readers (fix-paths.ts, npm-packument.ts) call
+ * them on what they already fetched.
+ */
+import { comparePrecedence, parseSemverPrecedence } from "./semver-precedence.js";
+/**
+ * dependency_check's view: every release of `index` that is never a candidate, with the
+ * registry's words. Withdrawn records (crates.io/PyPI yanked, npm unpublished, Go retracted:
+ * none of them installable as asked) plus the npm deprecations the rule above withdraws.
+ */
+export function excludedReleases(index) {
+    const out = new Map();
+    const releases = Object.values(index.releases);
+    for (const r of releases) {
+        if (r.withdrawn)
+            out.set(r.version, r.withdrawn === "yanked" ? withdrawalText(index.ecosystem, r.version) : `${r.version} was ${r.withdrawn} from the registry`);
+    }
+    if (index.ecosystem === "npm") {
+        const live = Object.fromEntries(releases.filter((r) => !r.withdrawn).map((r) => [r.version, r.deprecated]));
+        for (const v of npmExcludedVersions(live, index.latest))
+            out.set(v, withdrawalText("npm", v, index.releases[v]?.deprecated));
+    }
+    return out;
+}
+/** npm's per-version `deprecated`: a non-empty message, or `true` (the app's `npm_deprecated`). */
+export function isNpmDeprecated(value) {
+    return (typeof value === "string" && value !== "") || value === true;
+}
+/**
+ * The npm releases to exclude as fix targets, from a packument's `versions`
+ * (version -> its `deprecated`) and `dist-tags.latest` (see the module notes).
+ */
+export function npmExcludedVersions(deprecation, latest) {
+    if (latest && latest in deprecation && isNpmDeprecated(deprecation[latest]))
+        return [];
+    const clean = Object.entries(deprecation)
+        .filter(([, d]) => !isNpmDeprecated(d))
+        .map(([v]) => parseSemverPrecedence(v))
+        .filter((p) => p !== null && p.prerelease.length === 0);
+    return Object.entries(deprecation)
+        .filter(([, d]) => isNpmDeprecated(d))
+        .filter(([v]) => {
+        const p = parseSemverPrecedence(v);
+        return p !== null && clean.some((c) => c.major === p.major && (p.major > 0 || c.minor === p.minor) && comparePrecedence(c, p) > 0);
+    })
+        .map(([v]) => v);
+}
+/** How a registry names a withdrawal, for the release `version`. */
+export function withdrawalText(ecosystem, version, detail) {
+    const quoted = detail?.trim() ? ` ("${clip(detail.trim(), 120)}")` : "";
+    switch (ecosystem) {
+        case "npm":
+            return `${version} is deprecated on npm${quoted}`;
+        case "crates.io":
+            return `${version} is yanked on crates.io`;
+        case "PyPI":
+            return `${version} is yanked on PyPI${quoted}`;
+        default:
+            return `${version} is withdrawn on the registry${quoted}`;
+    }
+}
+/** At most `max` characters, cut at a word, "..." when cut. */
+function clip(text, max) {
+    if (text.length <= max)
+        return text;
+    const cut = text.slice(0, max);
+    return `${cut.slice(0, Math.max(cut.lastIndexOf(" "), max / 2)).replace(/[\s,;:.]+$/, "")}...`;
+}
+/**
+ * The withdrawn releases in plain words, releases with the same reason said once:
+ * "7.5.3, 7.5.4 and 7.5.5 are deprecated on npm ("Old versions of tar ...")".
+ */
+export function sayWithdrawn(versions, why, ecosystem) {
+    const groups = [];
+    for (const v of versions) {
+        const text = why[v] ?? withdrawalText(ecosystem, v);
+        const rest = text.startsWith(`${v} is `) ? text.slice(v.length + " is ".length) : null;
+        const last = groups[groups.length - 1];
+        if (rest !== null && last && last.rest === rest)
+            last.versions.push(v);
+        else
+            groups.push({ rest: rest ?? text, versions: rest === null ? [] : [v] });
+    }
+    return groups
+        .map((g) => {
+        if (g.versions.length === 0)
+            return g.rest;
+        const names = g.versions.length === 1 ? g.versions[0] : `${g.versions.slice(0, -1).join(", ")} and ${g.versions[g.versions.length - 1]}`;
+        return `${names} ${g.versions.length === 1 ? "is" : "are"} ${g.rest}`;
+    })
+        .join("; ");
+}
+/**
+ * The plain-words note for a target moved past withdrawn releases, or for no
+ * target because every release that would fix it was withdrawn (the app's
+ * Upgrade Plan wording: "No installable fix").
+ *   "4.18.0 is deprecated on npm ("Bad release..."); 4.18.1 is the smallest clean release"
+ *   "No installable fix: 0.3.17 is yanked on crates.io, and no later release is known to clear it"
+ * `why` holds the registry's own text per withdrawn release (withdrawalText).
+ * `clean: false`: the target clears only the advisories a release fixes.
+ */
+export function withheldNote(withheld, target, why, ecosystem, clean = true) {
+    if (withheld.length === 0)
+        return null;
+    const said = sayWithdrawn(withheld, why, ecosystem);
+    if (!target)
+        return `No installable fix: ${said}, and no later release is known to clear it — pin, patch, or replace`;
+    return `${said}; ${target} is the smallest ${clean ? "clean release" : "installable release that clears the advisories a release fixes"}`;
+}

package/dist/project-manifests.d.ts

@@ -26,6 +26,13 @@ export declare function parsePyprojectDependencies(content: string): {
 };
 /** Requirement names (pins and ranges alike) from a requirements file, PEP 503 normalised. */
 export declare function parseRequirementNames(content: string): string[];
+/**
+ * Requirement names from a requirements file and every file it includes with `-r` (confined to
+ * `root`, as the version reader confines them): an included file's pins are declared too. A pin
+ * in `-r sub/inner.txt` read as "Transitive dependency, not declared in your manifest" (final
+ * release audit of 6.2.5, 7g: jinja2==2.10).
+ */
+export declare function requirementNamesWithIncludes(file: string, root?: string, visited?: Set<string>): string[];
 /** Direct Go dependencies: go.mod requirements not marked `// indirect`. */
 export declare function parseGoModDirectDeps(content: string): string[];
 /**