@4da/mcp-server 6.0.1 → 6.1.0

package/dist/live/lockfile-parsers-pygo.js

@@ -19,62 +19,212 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { emptySource, found, InstanceSet } from "./lockfile-types.js";
 // =============================================================================
-// Python: poetry.lock > uv.lock > Pipfile.lock > requirements.txt
+// Python: every lockfile and requirements file in the directory, merged
 // =============================================================================
 /** PEP 503 normalised name: lowercase, runs of `-`, `_`, `.` become one `-`. */
 export function normalizePythonName(name) {
     return name.trim().toLowerCase().replace(/[-_.]+/g, "-");
 }
+/** The TOML lockfiles: arrays of [[package]] tables. */
+const PYTHON_TOML_LOCKS = ["poetry.lock", "uv.lock", "pdm.lock"];
+/**
+ * Requirement files in a project directory: `*requirements*.txt` beside it
+ * (requirements-dev.txt, dev_requirements.txt, _test_minimum_requirements.txt)
+ * and every `.txt` in a `requirements/` folder (pip-compile-multi: superset
+ * keeps its 100 runtime pins in requirements/base.txt, which nothing read).
+ */
+export function requirementFiles(cwd) {
+    const out = [];
+    try {
+        for (const name of fs.readdirSync(cwd).sort()) {
+            if (/requirements[\w.-]*\.txt$/i.test(name) || includesRequirements(path.join(cwd, name)))
+                out.push(path.join(cwd, name));
+        }
+    }
+    catch {
+        return out;
+    }
+    try {
+        for (const name of fs.readdirSync(path.join(cwd, "requirements")).sort()) {
+            if (/\.txt$/i.test(name))
+                out.push(path.join(cwd, "requirements", name));
+        }
+    }
+    catch {
+        // no requirements/ folder
+    }
+    return out;
+}
+/** Above this a .txt is not read to decide whether it is a requirements file. */
+const MAX_SNIFF_BYTES = 256 * 1024;
+/**
+ * A `.txt` whose name does not say "requirements" but that includes one with
+ * `-r` and pins packages itself: CTFd's development.txt (`-r requirements.txt`,
+ * then pytest==5.4.2 and 21 more pins, 6 advisories pip-audit reports).
+ */
+function includesRequirements(file) {
+    if (!/\.txt$/i.test(file) || /requirements[\w.-]*\.txt$/i.test(file))
+        return false;
+    try {
+        const stat = fs.statSync(file);
+        if (!stat.isFile() || stat.size > MAX_SNIFF_BYTES)
+            return false;
+        const content = fs.readFileSync(file, "utf-8");
+        return /^\s*(?:-r|--requirement)[\s=]+\S+\.txt\s*$/m.test(content) && parseRequirements(content).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether a requirements file is dev-only by name: requirements-dev.txt,
+ * dev-requirements.txt, requirements/testing.txt, _test_minimum_requirements.txt,
+ * docs-requirements.txt. The convention is near universal, but it is a name:
+ * a package any other file also lists keeps an unknown scope, never "dev".
+ */
+export function devRequirementsFile(file) {
+    const name = path.basename(file).replace(/\.txt$/i, "");
+    return /(?:^|[-_.])(?:dev|devel|develop|development|test|tests|testing|lint|linting|docs?|ci|typing|mypy|bench|benchmarks?)(?:[-_.]|$)/i.test(name);
+}
+/**
+ * Every Python source in a directory, merged: poetry.lock, uv.lock, pdm.lock,
+ * Pipfile.lock AND the requirement files. One source per ecosystem dropped
+ * whatever sat beside the first: langchain's libs/community has a
+ * poetry.lock and _test_minimum_requirements.txt, and only the lock was read.
+ * The version a direct dependency resolves to comes from a lockfile first.
+ */
 export function resolvePython(cwd) {
-    // poetry.lock and uv.lock are TOML arrays of [[package]] tables.
-    for (const file of ["poetry.lock", "uv.lock"]) {
+    const versions = new Map();
+    const instances = new InstanceSet();
+    const sources = [];
+    let lockfile = false;
+    const take = (name, version, dev) => {
+        instances.add(name, version, dev);
+        if (!versions.has(name))
+            versions.set(name, version);
+    };
+    for (const file of PYTHON_TOML_LOCKS) {
         const lockPath = path.join(cwd, file);
         if (!fs.existsSync(lockPath))
             continue;
         try {
             const read = readTomlPackageLock(fs.readFileSync(lockPath, "utf-8"));
-            if (read.instances.size > 0)
-                return found(read.versions, read.instances, lockPath, "lockfile");
+            if (read.instances.size === 0)
+                continue;
+            for (const i of read.instances.toArray())
+                take(i.name, i.version, i.dev);
+            sources.push(lockPath);
+            lockfile = true;
         }
-        catch { /* fall through */ }
+        catch { /* unreadable: the next source */ }
     }
     const pipfileLock = path.join(cwd, "Pipfile.lock");
     if (fs.existsSync(pipfileLock)) {
         try {
             const lock = JSON.parse(fs.readFileSync(pipfileLock, "utf-8"));
-            const versions = new Map();
-            const instances = new InstanceSet();
+            let any = false;
             for (const [section, dev] of [["default", false], ["develop", true]]) {
                 for (const [name, info] of Object.entries(lock[section] ?? {})) {
                     const version = info.version?.replace(/^===?/, "");
                     if (!version)
                         continue;
-                    const normalized = normalizePythonName(name);
-                    instances.add(normalized, version, dev);
-                    if (!versions.has(normalized))
-                        versions.set(normalized, version);
+                    take(normalizePythonName(name), version, dev);
+                    any = true;
                 }
             }
-            if (instances.size > 0)
-                return found(versions, instances, pipfileLock, "lockfile");
+            if (any) {
+                sources.push(pipfileLock);
+                lockfile = true;
+            }
         }
-        catch { /* fall through */ }
+        catch { /* unreadable */ }
     }
-    const reqPath = path.join(cwd, "requirements.txt");
-    if (fs.existsSync(reqPath)) {
-        const versions = new Map();
-        const instances = new InstanceSet();
-        try {
-            for (const { name, version } of parseRequirements(fs.readFileSync(reqPath, "utf-8"))) {
-                instances.add(name, version);
-                if (!versions.has(name))
-                    versions.set(name, version);
-            }
+    for (const file of requirementFiles(cwd)) {
+        const dev = devRequirementsFile(file) ? true : undefined;
+        const pins = readRequirementsFile(file);
+        if (pins === null)
+            continue;
+        for (const { name, version } of pins)
+            take(name, version, dev);
+        sources.push(file);
+    }
+    if (sources.length === 0)
+        return emptySource();
+    return found(versions, instances, sources[0], lockfile ? "lockfile" : "manifest", { extraSources: sources.slice(1) });
+}
+/**
+ * Exact pins from one requirements file, following `-r`/`--requirement`
+ * includes (relative to the file) and applying `-c`/`--constraint` files:
+ * a constraints file installs nothing by itself, so its pins only give a
+ * version to a name the requirements list without one. Null when unreadable.
+ */
+export function readRequirementsFile(file, visited = new Set()) {
+    const key = path.resolve(file).toLowerCase();
+    if (visited.has(key))
+        return [];
+    visited.add(key);
+    let content;
+    try {
+        content = fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return null;
+    }
+    const dir = path.dirname(file);
+    const out = parseRequirements(content);
+    const constraints = new Map();
+    for (const { option, target } of requirementOptions(content)) {
+        const included = path.resolve(dir, target);
+        if (option === "r")
+            out.push(...(readRequirementsFile(included, visited) ?? []));
+        else
+            for (const pin of parseRequirements(safeRead(included)))
+                constraints.set(pin.name, pin.version);
+    }
+    if (constraints.size > 0) {
+        const pinned = new Set(out.map((p) => p.name));
+        for (const name of unpinnedRequirementNames(content)) {
+            const version = constraints.get(name);
+            if (version && !pinned.has(name))
+                out.push({ name, version });
         }
-        catch { /* skip */ }
-        return found(versions, instances, reqPath, "manifest");
     }
-    return emptySource();
+    return out;
+}
+function safeRead(file) {
+    try {
+        return fs.readFileSync(file, "utf-8");
+    }
+    catch {
+        return "";
+    }
+}
+/** `-r file` / `--requirement=file` / `-c file` / `--constraint file` lines (local paths only). */
+function requirementOptions(content) {
+    const out = [];
+    for (const raw of content.replace(/\\\r?\n/g, " ").split(/\r?\n/)) {
+        const m = /^\s*(?:-(r|c)|--(requirement|constraint))(?:\s*=\s*|\s+)(\S+)/.exec(raw);
+        if (!m || /^[a-z][a-z+]*:\/\//i.test(m[3]))
+            continue;
+        out.push({ option: (m[1] ?? (m[2] === "requirement" ? "r" : "c")), target: m[3] });
+    }
+    return out;
+}
+/** Names a requirements file lists with no exact pin ("flask", "flask>=2"), PEP 503 normalised. */
+function unpinnedRequirementNames(content) {
+    const out = [];
+    for (const raw of content.replace(/\\\r?\n/g, " ").split(/\r?\n/)) {
+        const line = raw.replace(/(^|\s)#.*$/, "").trim();
+        if (!line || line.startsWith("-"))
+            continue;
+        const spec = line.split(";")[0].trim();
+        if (/===?/.test(spec))
+            continue;
+        const m = /^([A-Za-z0-9][A-Za-z0-9._-]*)/.exec(spec);
+        if (m)
+            out.push(normalizePythonName(m[1]));
+    }
+    return out;
 }
 /**
  * [[package]] tables from poetry.lock (any version) or uv.lock. A pre-1.2

package/dist/live/lockfile-parsers.d.ts

@@ -25,7 +25,10 @@
 import { InstanceSet, type VersionSource } from "./lockfile-types.js";
 import type { OsvEcosystem } from "./types.js";
 export type { PackageInstance, VersionSource } from "./lockfile-types.js";
-/** Every lock file the resolver may read for this ecosystem, present or not, in priority order. */
+/**
+ * Every lock file the resolver may read for this ecosystem, present or not,
+ * in priority order; for Python also every requirements file present now.
+ */
 export declare function lockfileCandidates(cwd: string, ecosystem: OsvEcosystem): string[];
 /** The manifest the resolver falls back to for this ecosystem, or null when it has none. */
 export declare function manifestCandidate(cwd: string, ecosystem: OsvEcosystem): string | null;

package/dist/live/lockfile-parsers.js

@@ -27,22 +27,25 @@ import * as fs from "node:fs";
 import * as path from "node:path";
 import { readBunLock } from "./bun-lockfile.js";
 import { readPnpmLock, readYarnLock } from "./js-lockfile-readers.js";
-import { resolveGo, resolvePython } from "./lockfile-parsers-pygo.js";
+import { requirementFiles, resolveGo, resolvePython } from "./lockfile-parsers-pygo.js";
 import { emptySource, found, InstanceSet } from "./lockfile-types.js";
 const LOCKFILES = {
     npm: ["package-lock.json", "npm-shrinkwrap.json", "pnpm-lock.yaml", "yarn.lock", "bun.lock"],
     "crates.io": ["Cargo.lock"],
-    PyPI: ["poetry.lock", "uv.lock", "Pipfile.lock"],
+    PyPI: ["poetry.lock", "uv.lock", "pdm.lock", "Pipfile.lock"],
     Go: ["go.mod", "go.sum"],
 };
 const MANIFESTS = {
     npm: "package.json",
     "crates.io": "Cargo.toml",
-    PyPI: "requirements.txt",
 };
-/** Every lock file the resolver may read for this ecosystem, present or not, in priority order. */
+/**
+ * Every lock file the resolver may read for this ecosystem, present or not,
+ * in priority order; for Python also every requirements file present now.
+ */
 export function lockfileCandidates(cwd, ecosystem) {
-    return (LOCKFILES[ecosystem] ?? []).map((name) => path.join(cwd, name));
+    const fixed = (LOCKFILES[ecosystem] ?? []).map((name) => path.join(cwd, name));
+    return ecosystem === "PyPI" ? [...fixed, ...requirementFiles(cwd)] : fixed;
 }
 /** The manifest the resolver falls back to for this ecosystem, or null when it has none. */
 export function manifestCandidate(cwd, ecosystem) {
@@ -67,6 +70,30 @@ export function resolveVersionSource(cwd, ecosystem) {
 function manifestInstances(versions) {
     return [...versions].map(([name, version]) => ({ name, version }));
 }
+/**
+ * A manifest read with no lockfile beside it. Only an exact pin names the
+ * version that gets installed; any other requirement ("^1.2.0", "0.8") is
+ * kept in `ranges`, and its floor in `versions` is a label, not an install.
+ * nushell's samples/wasm/Cargo.toml (no Cargo.lock) was scanned as if its
+ * floors were installed and produced 2 false findings (2026-10-10).
+ */
+function declaredRanges(declared, exact, file) {
+    const versions = new Map();
+    const ranges = new Map();
+    for (const [name, spec] of declared) {
+        // "0.3" and "1" are ranges too: their floor is 0.3.0 / 1.0.0.
+        const partial = /(\d+)(?:\.(\d+))?/.exec(spec);
+        const version = extractVersionFromSpec(spec) ?? (partial ? `${partial[1]}.${partial[2] ?? "0"}.0` : null);
+        if (!version)
+            continue;
+        versions.set(name, version);
+        if (!exact(spec))
+            ranges.set(name, spec);
+    }
+    // Only exact pins are installs; ranged names are not instances at all.
+    const pinned = new Map([...versions].filter(([name]) => !ranges.has(name)));
+    return found(versions, manifestInstances(pinned), file, "declared_ranges", { ranges });
+}
 // =============================================================================
 // npm: package-lock.json > npm-shrinkwrap.json > pnpm-lock.yaml > yarn.lock > bun.lock > package.json ranges
 // =============================================================================
@@ -125,21 +152,20 @@ function resolveNpm(cwd) {
         }
         catch { /* fall through */ }
     }
-    // Fallback: extract version floors from package.json ranges
+    // No lockfile: package.json declares ranges, not installed versions.
     const pkgPath = path.join(cwd, "package.json");
     if (fs.existsSync(pkgPath)) {
-        const versions = new Map();
+        const declared = new Map();
         try {
             const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf-8"));
-            const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-            for (const [name, spec] of Object.entries(allDeps)) {
-                const version = extractVersionFromSpec(spec);
-                if (version)
-                    versions.set(name, version);
+            for (const [name, spec] of Object.entries({ ...pkg.dependencies, ...pkg.devDependencies })) {
+                if (typeof spec === "string")
+                    declared.set(name, spec);
             }
         }
         catch { /* skip */ }
-        return found(versions, manifestInstances(versions), pkgPath, "manifest");
+        // npm installs exactly "1.2.3" (or "=1.2.3"); anything else is a range.
+        return declaredRanges(declared, (spec) => /^=?v?\d+\.\d+\.\d+(?:-[\w.]+)?$/.test(spec.trim()), pkgPath);
     }
     return emptySource();
 }
@@ -259,25 +285,32 @@ function resolveRust(cwd) {
     return found(versions, instances, lockPath, "lockfile");
 }
 function resolveRustFromManifest(cwd) {
-    const versions = new Map();
+    const declared = new Map();
     const cargoPath = path.join(cwd, "Cargo.toml");
     if (!fs.existsSync(cargoPath))
         return emptySource();
     try {
-        const content = fs.readFileSync(cargoPath, "utf-8");
-        // name = "1.0" or name = { version = "1.0", ... }
-        const depRegex = /^([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]+)"|.*?version\s*=\s*"([^"]+)")/gm;
-        let match;
-        while ((match = depRegex.exec(content)) !== null) {
-            const name = match[1];
-            const version = match[2] || match[3];
-            if (version && /^\d/.test(version)) {
-                versions.set(name, version);
+        // name = "1.0" or name = { version = "1.0", ... }, inside dependency tables
+        // only: [package]'s own `version = "0.1.0"` and `edition = "2021"` were read
+        // as crates named "version" and "edition".
+        let inDeps = false;
+        for (const line of fs.readFileSync(cargoPath, "utf-8").split(/\r?\n/)) {
+            const header = /^\s*\[([^\]]+)\]\s*$/.exec(line);
+            if (header) {
+                inDeps = /(?:^|\.)(?:dev-|build-)?dependencies$/.test(header[1].trim());
+                continue;
             }
+            if (!inDeps)
+                continue;
+            const match = /^\s*([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]+)"|.*?\bversion\s*=\s*"([^"]+)")/.exec(line);
+            const spec = match?.[2] ?? match?.[3];
+            if (match && spec && /^[=^~]?\s*\d/.test(spec))
+                declared.set(match[1], spec);
         }
     }
     catch { /* skip */ }
-    return found(versions, manifestInstances(versions), cargoPath, "manifest");
+    // Cargo reads "1.0" as "^1.0": only "=1.2.3" names one version.
+    return declaredRanges(declared, (spec) => /^=\s*\d+\.\d+\.\d+/.test(spec.trim()), cargoPath);
 }
 // =============================================================================
 // Helpers

package/dist/live/lockfile-types.d.ts

@@ -16,9 +16,18 @@ export interface VersionSource {
     instances: PackageInstance[];
     /** Absolute path of the file the versions were read from, or null when none exists. */
     source: string | null;
-    /** `lockfile` = exact versions; `manifest` = read from a manifest (pins or specifier floors). */
-    kind: "lockfile" | "manifest" | null;
+    /**
+     * `lockfile` = exact versions; `manifest` = exact pins from a requirements
+     * file; `declared_ranges` = a manifest with no lockfile (package.json,
+     * Cargo.toml): its versions are the floors of declared ranges, not installs.
+     */
+    kind: SourceKind | null;
+    /** Every further file read for this ecosystem in this directory (Python reads several). */
+    extraSources?: string[];
+    /** declared_ranges: the declared requirement per name ("^1.2.0"), for names whose version is only a floor. */
+    ranges?: Map<string, string>;
 }
+export type SourceKind = "lockfile" | "manifest" | "declared_ranges";
 export declare function emptySource(): VersionSource;
 /**
  * Collects instances deduplicated by name@version. A copy seen as runtime
@@ -31,4 +40,4 @@ export declare class InstanceSet {
     get size(): number;
     toArray(): PackageInstance[];
 }
-export declare function found(versions: Map<string, string>, instances: InstanceSet | PackageInstance[], source: string, kind: "lockfile" | "manifest"): VersionSource;
+export declare function found(versions: Map<string, string>, instances: InstanceSet | PackageInstance[], source: string, kind: SourceKind, extra?: Pick<VersionSource, "extraSources" | "ranges">): VersionSource;

package/dist/live/lockfile-types.js

@@ -32,11 +32,12 @@ export class InstanceSet {
         return [...this.byKey.values()];
     }
 }
-export function found(versions, instances, source, kind) {
+export function found(versions, instances, source, kind, extra = {}) {
     return {
         versions,
         instances: Array.isArray(instances) ? instances : instances.toArray(),
         source,
         kind,
+        ...extra,
     };
 }

package/dist/live/osv-ranges.d.ts

@@ -0,0 +1,79 @@
+/**
+ * OSV affected ranges, read as version spans, and the smallest version that
+ * is clean against EVERY known advisory of a package.
+ *
+ * A fix target used to be the highest per-advisory fix among the advisories
+ * that affect the INSTALLED version. That target can itself be vulnerable to
+ * an advisory the installed version predates: openssl 0.10.38 was sent to
+ * 0.10.79, which GHSA-phqj-4mhp-q6mq affects (0.10.50 up to 0.10.80), so the
+ * recommended upgrade swapped one advisory for another (fix-path oracle,
+ * 2026-10-10). The target is now checked against all of the package's
+ * advisories, not only the ones the installed version has.
+ */
+import type { OsvVulnerability } from "./types.js";
+/**
+ * One affected span: [introduced, fixed), or [introduced, lastAffected]
+ * when OSV gives a `last_affected` event; both null = still open.
+ */
+export interface AffectedSpan {
+    introduced: string;
+    fixed: string | null;
+    lastAffected: string | null;
+}
+/** What one advisory says about one package: its spans plus any versions it lists explicitly. */
+export interface AdvisoryRanges {
+    id: string;
+    spans: AffectedSpan[];
+    versions: string[];
+}
+/**
+ * Flatten the matching package's version ranges into spans. OSV sorts events
+ * within a range; each `introduced` opens a span and the next `fixed` or
+ * `last_affected` closes it. GIT ranges hold commit hashes, not versions,
+ * and are skipped.
+ */
+export declare function collectAffectedSpans(affected: OsvVulnerability["affected"] | undefined, packageName: string, ecosystem: string): AffectedSpan[];
+/** One advisory's ranges for one package; null when the advisory is withdrawn. */
+export declare function advisoryRanges(vuln: OsvVulnerability, packageName: string, ecosystem: string): AdvisoryRanges | null;
+/** True when `version` lies in a span (or the explicit list) of this advisory. */
+export declare function advisoryAffects(advisory: AdvisoryRanges, version: string, ecosystem: string): boolean;
+/** Whether a version is a prerelease in its ecosystem's own terms. */
+export declare function isPrereleaseVersion(version: string, ecosystem: string): boolean;
+export interface CleanTarget {
+    /** The smallest candidate at or above every per-advisory fix that no fixable advisory affects; null when none is clean. */
+    target: string | null;
+    /** Where the candidates came from. */
+    basis: "registry" | "advisory_fixes";
+    /** The highest per-advisory fix. */
+    floor: string;
+    /** Advisories that affect the floor (why the target can be above it). */
+    floorAffectedBy: string[];
+    /**
+     * Advisories that still affect the returned target (only unfixable ones:
+     * every candidate has them), or, when `target` is null, the floor.
+     */
+    stillAffectedBy: string[];
+    /**
+     * Advisories no release fixes: they affect the newest candidate too
+     * (braces GHSA-vfj7-8cjw-p6xm, last_affected 3.0.3 = the newest release).
+     * No target can clear them, so they do not disqualify one; they are
+     * reported instead.
+     */
+    unfixable: string[];
+}
+/**
+ * The smallest version at or above the highest per-advisory fix that none
+ * of the package's fixable advisories affects.
+ *
+ * Candidates are the package's published releases when known (prereleases
+ * only when the floor is one), otherwise every fix event the advisories
+ * name. An advisory that affects the newest candidate has no fixed release
+ * and does not disqualify a target (it is listed in `unfixable`). Null when
+ * `fixes` is empty.
+ */
+export declare function smallestCleanVersion(input: {
+    ecosystem: string;
+    fixes: string[];
+    advisories: AdvisoryRanges[];
+    published: string[] | null;
+}): CleanTarget | null;

package/dist/live/osv-ranges.js

@@ -0,0 +1,133 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OSV affected ranges, read as version spans, and the smallest version that
+ * is clean against EVERY known advisory of a package.
+ *
+ * A fix target used to be the highest per-advisory fix among the advisories
+ * that affect the INSTALLED version. That target can itself be vulnerable to
+ * an advisory the installed version predates: openssl 0.10.38 was sent to
+ * 0.10.79, which GHSA-phqj-4mhp-q6mq affects (0.10.50 up to 0.10.80), so the
+ * recommended upgrade swapped one advisory for another (fix-path oracle,
+ * 2026-10-10). The target is now checked against all of the package's
+ * advisories, not only the ones the installed version has.
+ */
+import { compareVersions, isComparable, parsePep440, samePackageName } from "./version-compare.js";
+import { parseSemverPrecedence } from "./semver-precedence.js";
+/**
+ * Flatten the matching package's version ranges into spans. OSV sorts events
+ * within a range; each `introduced` opens a span and the next `fixed` or
+ * `last_affected` closes it. GIT ranges hold commit hashes, not versions,
+ * and are skipped.
+ */
+export function collectAffectedSpans(affected, packageName, ecosystem) {
+    const spans = [];
+    for (const a of affected ?? []) {
+        // Names compare the registry's way: PEP 503 for PyPI (`Jinja2` is
+        // `jinja2`), `-`/`_` folding for crates.
+        if (a.package.ecosystem !== ecosystem || !samePackageName(a.package.name, packageName, ecosystem))
+            continue;
+        for (const range of a.ranges || []) {
+            if (range.type === "GIT")
+                continue;
+            let open = null;
+            for (const event of range.events || []) {
+                if (event.introduced !== undefined) {
+                    if (open)
+                        spans.push(open);
+                    open = { introduced: event.introduced, fixed: null, lastAffected: null };
+                }
+                else if (event.fixed !== undefined || event.last_affected !== undefined) {
+                    const close = { fixed: event.fixed ?? null, lastAffected: event.fixed === undefined ? (event.last_affected ?? null) : null };
+                    if (open) {
+                        spans.push({ ...open, ...close });
+                        open = null;
+                    }
+                    else {
+                        // A closing event with no preceding `introduced`: affected since
+                        // inception ("0" = OSV's since-the-beginning sentinel).
+                        spans.push({ introduced: "0", ...close });
+                    }
+                }
+            }
+            if (open)
+                spans.push(open);
+        }
+    }
+    return spans;
+}
+/** Versions an advisory lists explicitly for this package (`affected[].versions`). */
+function listedVersions(affected, packageName, ecosystem) {
+    const out = [];
+    for (const a of affected ?? []) {
+        if (a.package.ecosystem !== ecosystem || !samePackageName(a.package.name, packageName, ecosystem))
+            continue;
+        out.push(...(a.versions ?? []));
+    }
+    return out;
+}
+/** One advisory's ranges for one package; null when the advisory is withdrawn. */
+export function advisoryRanges(vuln, packageName, ecosystem) {
+    if (vuln.withdrawn)
+        return null;
+    return {
+        id: vuln.id,
+        spans: collectAffectedSpans(vuln.affected, packageName, ecosystem),
+        versions: listedVersions(vuln.affected, packageName, ecosystem),
+    };
+}
+/** True when `version` lies in a span (or the explicit list) of this advisory. */
+export function advisoryAffects(advisory, version, ecosystem) {
+    if (advisory.versions.includes(version))
+        return true;
+    const cmp = (a, b) => compareVersions(a, b, ecosystem);
+    return advisory.spans.some((s) => cmp(version, s.introduced) >= 0 &&
+        (s.fixed !== null ? cmp(version, s.fixed) < 0 : s.lastAffected !== null ? cmp(version, s.lastAffected) <= 0 : true));
+}
+/** Whether a version is a prerelease in its ecosystem's own terms. */
+export function isPrereleaseVersion(version, ecosystem) {
+    if (ecosystem === "PyPI") {
+        const p = parsePep440(version);
+        return p ? p.pre !== null || p.dev !== null : false;
+    }
+    const p = parseSemverPrecedence(version.replace(/^v(?=\d)/, ""));
+    return p ? p.prerelease.length > 0 : false;
+}
+/**
+ * The smallest version at or above the highest per-advisory fix that none
+ * of the package's fixable advisories affects.
+ *
+ * Candidates are the package's published releases when known (prereleases
+ * only when the floor is one), otherwise every fix event the advisories
+ * name. An advisory that affects the newest candidate has no fixed release
+ * and does not disqualify a target (it is listed in `unfixable`). Null when
+ * `fixes` is empty.
+ */
+export function smallestCleanVersion(input) {
+    const { ecosystem } = input;
+    const fixes = input.fixes.filter((f) => isComparable(f, ecosystem));
+    if (fixes.length === 0)
+        return null;
+    const cmp = (a, b) => compareVersions(a, b, ecosystem);
+    const floor = fixes.reduce((max, v) => (cmp(v, max) > 0 ? v : max), fixes[0]);
+    const allowPre = isPrereleaseVersion(floor, ecosystem);
+    const fromRegistry = input.published !== null && input.published.length > 0;
+    const pool = fromRegistry
+        ? input.published
+        : [floor, ...input.advisories.flatMap((a) => a.spans.map((s) => s.fixed).filter((f) => f !== null))];
+    const candidates = [...new Set(pool)]
+        .filter((v) => isComparable(v, ecosystem) && cmp(v, floor) >= 0 && (allowPre || !isPrereleaseVersion(v, ecosystem)))
+        .sort(cmp);
+    const basis = fromRegistry ? "registry" : "advisory_fixes";
+    const newest = candidates[candidates.length - 1];
+    const unfixable = newest ? input.advisories.filter((a) => advisoryAffects(a, newest, ecosystem)) : [];
+    const fixable = input.advisories.filter((a) => !unfixable.includes(a));
+    const unfixableIds = [...new Set(unfixable.map((a) => a.id))];
+    const affecting = (v) => [...new Set(input.advisories.filter((a) => advisoryAffects(a, v, ecosystem)).map((a) => a.id))];
+    // Clean against everything if any candidate is; otherwise against every advisory a release fixes.
+    for (const pool of [input.advisories, fixable]) {
+        const candidate = candidates.find((v) => !pool.some((a) => advisoryAffects(a, v, ecosystem)));
+        if (candidate)
+            return { target: candidate, basis, floor, floorAffectedBy: affecting(floor), stillAffectedBy: affecting(candidate), unfixable: unfixableIds };
+    }
+    return { target: null, basis, floor, floorAffectedBy: affecting(floor), stillAffectedBy: affecting(floor), unfixable: unfixableIds };
+}

package/dist/live/osv-scanner.d.ts

@@ -22,6 +22,7 @@ export declare class OsvScanner {
      * real advisory is never silently dropped just because its detail 404'd.
      */
     private hydrateDetails;
+    /** One advisory's record; retried once after a throttle, a server error or a network failure. Null when it cannot be had. */
     private fetchDetail;
 }
 /**