@4da/mcp-server 6.0.2 → 6.2.0

package/dist/live/osv-scanner.js

@@ -7,18 +7,48 @@
  *
  * Privacy: sends only package names + versions (public manifest data).
  */
-import { fetchWithTimeout, fetchJson } from "./http-utils.js";
+import { fetchWithTimeout } from "./http-utils.js";
 import { cvssBaseScore } from "./cvss.js";
-import { compareVersions, isComparable, maxVersion, samePackageName } from "./version-compare.js";
+import { compareVersions, isComparable, maxVersion } from "./version-compare.js";
+import { collectAffectedSpans } from "./osv-ranges.js";
 const OSV_BATCH_URL = "https://api.osv.dev/v1/querybatch";
 const OSV_VULN_URL = "https://api.osv.dev/v1/vulns/";
 const OSV_TIMEOUT_MS = 15_000;
 const OSV_CACHE_TTL = 3600; // 1 hour
 const OSV_DETAIL_TTL = 86_400; // 24 hours — advisory details change rarely
 const MAX_BATCH_SIZE = 1000;
-// Bounded concurrency for advisory-detail hydration. Only the *vulnerable*
-// subset is hydrated (not every scanned dep), so this stays small in practice.
-const HYDRATE_CONCURRENCY = 8;
+/**
+ * Advisory details have no batch endpoint: one GET /v1/vulns/{id} each. They
+ * were fetched in rounds of 8, each round waiting for its slowest request, so
+ * a project with 900 distinct advisories (superset) made ~113 sequential
+ * round trips. Now a pool of HYDRATE_CONCURRENCY workers keeps that many
+ * requests in flight (osv-scanner itself hydrates in parallel), a failed or
+ * throttled request is retried once, and every result is cached for 24 h.
+ */
+const HYDRATE_CONCURRENCY = 24;
+/** querybatch chunks (1,000 dependencies each) sent at once. */
+const BATCH_CONCURRENCY = 4;
+const DETAIL_RETRY_DELAY_MS = 750;
+/**
+ * Detail fetches in flight, shared by every scanner in the process. The
+ * startup warm-up scan and the first tool call's scan used to run side by
+ * side and fetch the same advisories twice, both before either could cache
+ * them; a concurrent scan now waits on the request already made.
+ */
+const detailsInFlight = new Map();
+/** Run `work` over `items` with at most `limit` in flight; results in input order. */
+async function pool(items, limit, work) {
+    const out = new Array(items.length);
+    let next = 0;
+    const worker = async () => {
+        while (next < items.length) {
+            const i = next++;
+            out[i] = await work(items[i]);
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(limit, items.length) }, worker));
+    return out;
+}
 export class OsvScanner {
     cache;
     rateLimiter;
@@ -92,12 +122,18 @@ export class OsvScanner {
         // Phase 1 — enumerate advisory IDs per dep via the lightweight batch index.
         // querybatch returns only `{ id, modified }`; the rich fields (severity,
         // fixed version, summary, references) come from per-advisory hydration below.
-        const matches = [];
-        for (let offset = 0; offset < deps.length; offset += MAX_BATCH_SIZE) {
-            if (!this.rateLimiter.canProceed("osv")) {
+        const chunks = [];
+        for (let offset = 0; offset < deps.length; offset += MAX_BATCH_SIZE)
+            chunks.push(deps.slice(offset, offset + MAX_BATCH_SIZE));
+        // Every chunk is answered or the scan fails: a partial answer would call
+        // the unanswered dependencies clean. The rate limit is checked for all of
+        // them before any is sent.
+        for (let i = 0; i < chunks.length; i++) {
+            if (!this.rateLimiter.consume("osv")) {
                 throw new Error("OSV rate limit reached before all dependency batches completed");
             }
-            const chunk = deps.slice(offset, offset + MAX_BATCH_SIZE);
+        }
+        const answered = await pool(chunks, BATCH_CONCURRENCY, async (chunk) => {
             const queries = chunk.map((d) => ({
                 package: { name: d.name, ecosystem: d.ecosystem },
                 ...(d.version ? { version: d.version } : {}),
@@ -110,29 +146,27 @@ export class OsvScanner {
             if (!response.ok) {
                 throw new Error(`OSV API error: ${response.status}`);
             }
-            this.rateLimiter.consume("osv");
             const data = (await response.json());
-            for (let i = 0; i < chunk.length; i++) {
-                const ids = (data.results[i]?.vulns ?? []).map((v) => v.id);
-                matches.push({ dep: chunk[i], ids });
-            }
-        }
+            return chunk.map((dep, i) => ({ dep, ids: (data.results[i]?.vulns ?? []).map((v) => v.id) }));
+        });
+        const matches = answered.flat();
         // Phase 2 — hydrate each unique advisory once (cached, bounded concurrency).
         const uniqueIds = [...new Set(matches.flatMap((m) => m.ids))];
         const detailById = await this.hydrateDetails(uniqueIds);
         // Phase 3 — map to entries and cache per-dep (empty results cached too, so
         // clean deps are not re-queried).
         const results = [];
+        const rows = [];
         for (const { dep, ids } of matches) {
             // Drop advisories OSV has withdrawn/retracted — surfacing them is a false
             // positive. Un-hydrated ids (detail fetch failed) are kept: we can't know,
             // and dropping a real advisory is worse than keeping an un-enriched one.
             const liveIds = ids.filter((id) => !detailById.get(id)?.withdrawn);
             const depVulns = liveIds.map((id) => mapVulnerability(detailById.get(id) ?? { id }, dep));
-            const cacheKey = `osv:${dep.ecosystem}:${dep.name}:${dep.version}`;
-            this.cache.set(cacheKey, depVulns, "osv", OSV_CACHE_TTL);
+            rows.push([`osv:${dep.ecosystem}:${dep.name}:${dep.version}`, depVulns]);
             results.push(...depVulns);
         }
+        this.cache.setMany(rows, "osv", OSV_CACHE_TTL);
         return results;
     }
     /**
@@ -151,26 +185,40 @@ export class OsvScanner {
             else
                 toFetch.push(id);
         }
-        for (let i = 0; i < toFetch.length; i += HYDRATE_CONCURRENCY) {
-            const slice = toFetch.slice(i, i + HYDRATE_CONCURRENCY);
-            const settled = await Promise.allSettled(slice.map((id) => this.fetchDetail(id)));
-            settled.forEach((res, j) => {
-                if (res.status === "fulfilled" && res.value) {
-                    const id = slice[j];
-                    out.set(id, res.value);
-                    this.cache.set(`osv:detail:${id}`, res.value, "osv", OSV_DETAIL_TTL);
-                }
-            });
-        }
+        const fetched = [];
+        await pool(toFetch, HYDRATE_CONCURRENCY, async (id) => {
+            let pending = detailsInFlight.get(id);
+            if (!pending) {
+                pending = this.fetchDetail(id).finally(() => detailsInFlight.delete(id));
+                detailsInFlight.set(id, pending);
+            }
+            const detail = await pending;
+            if (detail) {
+                out.set(id, detail);
+                fetched.push([`osv:detail:${id}`, detail]);
+            }
+        });
+        this.cache.setMany(fetched, "osv", OSV_DETAIL_TTL);
         return out;
     }
+    /** One advisory's record; retried once after a throttle, a server error or a network failure. Null when it cannot be had. */
     async fetchDetail(id) {
-        try {
-            return await fetchJson(`${OSV_VULN_URL}${encodeURIComponent(id)}`, {}, OSV_TIMEOUT_MS);
-        }
-        catch {
-            return null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                const response = await fetchWithTimeout(`${OSV_VULN_URL}${encodeURIComponent(id)}`, {}, OSV_TIMEOUT_MS);
+                if (response.ok)
+                    return (await response.json());
+                // 404 and other client errors are answers, not failures to retry.
+                if (response.status !== 429 && response.status < 500)
+                    return null;
+            }
+            catch {
+                // network failure or timeout: retry once
+            }
+            if (attempt === 0)
+                await new Promise((resolve) => setTimeout(resolve, DETAIL_RETRY_DELAY_MS));
         }
+        return null;
     }
 }
 /**
@@ -313,7 +361,7 @@ function cvssToSeverity(score) {
 export function extractFixedVersion(affected, packageName, ecosystem, installedVersion) {
     if (!affected)
         return null;
-    const intervals = collectVulnerableIntervals(affected, packageName, ecosystem);
+    const intervals = collectAffectedSpans(affected, packageName, ecosystem);
     const fixes = intervals
         .map((i) => i.fixed)
         .filter((f) => f !== null);
@@ -330,7 +378,9 @@ export function extractFixedVersion(affected, packageName, ecosystem, installedV
     // unreadable bound compares as 0, which keeps those intervals eligible on
     // the introduced side only; "0" (since inception) orders below everything.
     const containing = intervals.find((i) => cmp(installedVersion, i.introduced) >= 0 &&
-        (i.fixed === null || cmp(installedVersion, i.fixed) < 0));
+        (i.fixed !== null
+            ? cmp(installedVersion, i.fixed) < 0
+            : i.lastAffected === null || cmp(installedVersion, i.lastAffected) <= 0));
     if (containing?.fixed && cmp(containing.fixed, installedVersion) > 0) {
         return containing.fixed;
     }
@@ -341,46 +391,3 @@ export function extractFixedVersion(affected, packageName, ecosystem, installedV
         return null;
     return above.reduce((min, v) => (cmp(v, min) < 0 ? v : min), above[0]);
 }
-/**
- * Flatten the matching package's version ranges into [introduced, fixed)
- * intervals. OSV sorts events within a range; each `introduced` opens an
- * interval and the next `fixed` closes it. GIT ranges hold commit hashes,
- * not versions, and are skipped.
- */
-function collectVulnerableIntervals(affected, packageName, ecosystem) {
-    const intervals = [];
-    for (const a of affected) {
-        // Names compare the registry's way: PEP 503 for PyPI (`Jinja2` is
-        // `jinja2`), `-`/`_` folding for crates. An exact compare found no range
-        // for Jinja2 or PyYAML and reported "no fix version published" for both.
-        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)
-                        intervals.push(open);
-                    open = { introduced: event.introduced, fixed: null };
-                }
-                else if (event.fixed !== undefined) {
-                    if (open) {
-                        open.fixed = event.fixed;
-                        intervals.push(open);
-                        open = null;
-                    }
-                    else {
-                        // `fixed` with no preceding `introduced` — treat as vulnerable
-                        // since inception ("0" = OSV's since-the-beginning sentinel).
-                        intervals.push({ introduced: "0", fixed: event.fixed });
-                    }
-                }
-            }
-            if (open)
-                intervals.push(open);
-        }
-    }
-    return intervals;
-}

package/dist/live/package-archive.d.ts

@@ -44,6 +44,8 @@ export declare function iterateTar(tar: Buffer): Generator<TarEntry>;
  * files are skipped.
  */
 export declare function readRootTextFiles(gz: Buffer, accept: (basename: string) => boolean): Map<string, string>;
+/** Download a registry archive, refusing at MAX_COMPRESSED_BYTES. */
+export declare function fetchArchiveBytes(url: string, fetchFn?: FetchFn, headers?: Record<string, string>): Promise<Buffer>;
 /** Download a registry archive (size-capped) and return the accepted root-level text files. */
 export declare function fetchArchiveRootFiles(url: string, accept: (basename: string) => boolean, fetchFn?: FetchFn, headers?: Record<string, string>): Promise<Map<string, string>>;
 export {};

package/dist/live/package-archive.js

@@ -176,11 +176,14 @@ async function readCapped(response, cap) {
     }
     return Buffer.concat(chunks);
 }
-/** Download a registry archive (size-capped) and return the accepted root-level text files. */
-export async function fetchArchiveRootFiles(url, accept, fetchFn = defaultFetch, headers = {}) {
+/** Download a registry archive, refusing at MAX_COMPRESSED_BYTES. */
+export async function fetchArchiveBytes(url, fetchFn = defaultFetch, headers = {}) {
     const response = await fetchFn(url, { headers }, ARCHIVE_TIMEOUT_MS);
     if (!response.ok)
         throw new ArchiveError(`archive download failed: HTTP ${response.status}`);
-    const gz = await readCapped(response, MAX_COMPRESSED_BYTES);
-    return readRootTextFiles(gz, accept);
+    return readCapped(response, MAX_COMPRESSED_BYTES);
+}
+/** Download a registry archive (size-capped) and return the accepted root-level text files. */
+export async function fetchArchiveRootFiles(url, accept, fetchFn = defaultFetch, headers = {}) {
+    return readRootTextFiles(await fetchArchiveBytes(url, fetchFn, headers), accept);
 }

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

@@ -0,0 +1,44 @@
+/**
+ * PyPI release index for dependency_check, from the JSON API
+ * (`GET pypi.org/pypi/<name>/json`): every release with its upload time and
+ * whether it is yanked.
+ *
+ * - A release's publish time is its EARLIEST file upload (later wheels for
+ *   new platforms do not make it newer).
+ * - A release is yanked when every one of its files is (PEP 592); pip then
+ *   skips it unless pinned with `==`.
+ * - A release with no files cannot be installed and is left out.
+ * - Versions are PEP 440 and are kept as the registry spells them.
+ *
+ * Not read, and reported as not applicable by the signals: publisher identity
+ * (the JSON API carries none), install-time hooks (PyPI exposes none in its
+ * index; an sdist-only release runs its build backend at install), and
+ * per-release dependency lists (one request per release).
+ *
+ * Privacy: the request names the package and nothing else.
+ */
+import type { LiveCache } from "./cache.js";
+import type { RateLimiter } from "./rate-limiter.js";
+import type { PackageReleaseIndex, RegistryLookup, ReleaseMetadataSource } from "./release-metadata.js";
+interface PyPIFile {
+    upload_time_iso_8601?: string;
+    yanked?: boolean;
+    yanked_reason?: string | null;
+}
+interface PyPIProject {
+    info?: {
+        name?: string;
+    };
+    releases?: Record<string, PyPIFile[] | null>;
+}
+export declare const PYPI_NOT_APPLICABLE = "not applicable on PyPI: its JSON API carries no publisher identity or install-hook metadata";
+/** The index the signals read, from one JSON API document. */
+export declare function projectPypiProject(name: string, doc: PyPIProject): PackageReleaseIndex;
+export declare class PypiReleasesReader implements ReleaseMetadataSource {
+    private cache;
+    private rateLimiter;
+    constructor(cache: LiveCache, rateLimiter: RateLimiter);
+    getReleases(name: string): Promise<RegistryLookup<PackageReleaseIndex>>;
+    getCreatedAt(name: string): Promise<RegistryLookup<string | null>>;
+}
+export {};

package/dist/live/pypi-releases.js

@@ -0,0 +1,103 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * PyPI release index for dependency_check, from the JSON API
+ * (`GET pypi.org/pypi/<name>/json`): every release with its upload time and
+ * whether it is yanked.
+ *
+ * - A release's publish time is its EARLIEST file upload (later wheels for
+ *   new platforms do not make it newer).
+ * - A release is yanked when every one of its files is (PEP 592); pip then
+ *   skips it unless pinned with `==`.
+ * - A release with no files cannot be installed and is left out.
+ * - Versions are PEP 440 and are kept as the registry spells them.
+ *
+ * Not read, and reported as not applicable by the signals: publisher identity
+ * (the JSON API carries none), install-time hooks (PyPI exposes none in its
+ * index; an sdist-only release runs its build backend at install), and
+ * per-release dependency lists (one request per release).
+ *
+ * Privacy: the request names the package and nothing else.
+ */
+import { fetchWithTimeout } from "./http-utils.js";
+import { parsePep440 } from "./version-compare.js";
+import { normalizePypiName } from "./upgrade-pypi.js";
+const PYPI_URL = "https://pypi.org/pypi";
+const TIMEOUT_MS = 30_000;
+const TTL_SECONDS = 3600;
+export const PYPI_NOT_APPLICABLE = "not applicable on PyPI: its JSON API carries no publisher identity or install-hook metadata";
+/** The index the signals read, from one JSON API document. */
+export function projectPypiProject(name, doc) {
+    const releases = {};
+    let createdAt = null;
+    for (const [version, rawFiles] of Object.entries(doc.releases ?? {})) {
+        const files = Array.isArray(rawFiles) ? rawFiles : [];
+        if (files.length === 0 || !parsePep440(version))
+            continue;
+        const times = files.map((f) => f.upload_time_iso_8601).filter((t) => typeof t === "string").sort();
+        const publishedAt = times[0] ?? null;
+        if (publishedAt && (!createdAt || publishedAt < createdAt))
+            createdAt = publishedAt;
+        const yanked = files.every((f) => f.yanked === true);
+        const reason = yanked ? files.find((f) => f.yanked_reason)?.yanked_reason ?? null : null;
+        releases[version] = {
+            version,
+            publishedAt,
+            trust: 0,
+            trustEvidence: PYPI_NOT_APPLICABLE,
+            installScripts: null,
+            deprecated: reason ? `yanked: ${reason}` : null,
+            withdrawn: yanked ? "yanked" : null,
+            dependencies: null,
+        };
+    }
+    return { ecosystem: "PyPI", name: doc.info?.name ?? name, createdAt, releases };
+}
+export class PypiReleasesReader {
+    cache;
+    rateLimiter;
+    constructor(cache, rateLimiter) {
+        this.cache = cache;
+        this.rateLimiter = rateLimiter;
+    }
+    async getReleases(name) {
+        const normalized = normalizePypiName(name);
+        const key = `pypi-releases:${normalized}`;
+        const hit = this.cache.get(key);
+        if (hit)
+            return { status: "ok", data: hit };
+        if (!this.rateLimiter.consume("pypi")) {
+            return { status: "unreachable", detail: "PyPI rate limit reached for this minute" };
+        }
+        let response;
+        try {
+            response = await fetchWithTimeout(`${PYPI_URL}/${encodeURIComponent(normalized)}/json`, { headers: { Accept: "application/json" } }, TIMEOUT_MS);
+        }
+        catch (err) {
+            return { status: "unreachable", detail: `PyPI: ${errorText(err)}` };
+        }
+        if (response.status === 404)
+            return { status: "not_found", detail: `"${name}" is not on PyPI` };
+        if (!response.ok)
+            return { status: "unreachable", detail: `PyPI answered HTTP ${response.status}` };
+        let doc;
+        try {
+            doc = (await response.json());
+        }
+        catch (err) {
+            return { status: "unreachable", detail: `PyPI: unreadable project document (${errorText(err)})` };
+        }
+        if (!doc.releases || typeof doc.releases !== "object") {
+            return { status: "unreachable", detail: `PyPI returned no release list for ${name}` };
+        }
+        const index = projectPypiProject(name, doc);
+        this.cache.set(key, index, "pypi", TTL_SECONDS);
+        return { status: "ok", data: index };
+    }
+    async getCreatedAt(name) {
+        const lookup = await this.getReleases(name);
+        return lookup.status === "ok" ? { status: "ok", data: lookup.data.createdAt } : lookup;
+    }
+}
+function errorText(err) {
+    return err instanceof Error ? err.message : String(err);
+}

package/dist/live/range-satisfies.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Does a declared requirement admit a version? npm ranges (package.json,
+ * package-lock `dependencies`, yarn) and Cargo version requirements.
+ *
+ * Used to tell "the parent already allows the fixed version, so a lockfile
+ * refresh is enough" from "waiting on upstream". The planner labelled
+ * minimist 1.2.5, braces 3.0.2 and mio 0.8.0 "waiting on upstream" although
+ * every parent's range admitted the fix, and a refresh fixed each one
+ * (fix-path oracle, 2026-10-10).
+ *
+ * Unknown syntax (git and file specs, `npm:` aliases, dist-tags) yields null,
+ * never a guess.
+ */
+/**
+ * Whether an npm range admits `version`. Null when the range is not a
+ * registry semver range (git, file, link, workspace, alias, tag) or the
+ * version is unreadable.
+ */
+export declare function npmRangeAdmits(range: string, version: string): boolean | null;
+/** Whether a Cargo version requirement ("0.8", "^1.2", ">=0.10, <0.11", "=1.0.5") admits `version`. Null when unreadable. */
+export declare function cargoReqAdmits(req: string, version: string): boolean | null;

package/dist/live/range-satisfies.js

@@ -0,0 +1,190 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Does a declared requirement admit a version? npm ranges (package.json,
+ * package-lock `dependencies`, yarn) and Cargo version requirements.
+ *
+ * Used to tell "the parent already allows the fixed version, so a lockfile
+ * refresh is enough" from "waiting on upstream". The planner labelled
+ * minimist 1.2.5, braces 3.0.2 and mio 0.8.0 "waiting on upstream" although
+ * every parent's range admitted the fix, and a refresh fixed each one
+ * (fix-path oracle, 2026-10-10).
+ *
+ * Unknown syntax (git and file specs, `npm:` aliases, dist-tags) yields null,
+ * never a guess.
+ */
+import { comparePrecedence, parseSemverPrecedence } from "./semver-precedence.js";
+const WILD = /^[xX*]$/;
+function parsePartial(raw) {
+    const text = raw.trim().replace(/^v/, "").replace(/\+.*$/, "");
+    if (text === "" || WILD.test(text))
+        return { major: null, minor: null, patch: null, prerelease: [] };
+    const m = /^(\d+|[xX*])(?:\.(\d+|[xX*]))?(?:\.(\d+|[xX*]))?(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?$/.exec(text);
+    if (!m)
+        return null;
+    const num = (s) => (s === undefined || WILD.test(s) ? null : Number(s));
+    const major = num(m[1]);
+    const minor = major === null ? null : num(m[2]);
+    const patch = minor === null ? null : num(m[3]);
+    return { major, minor, patch, prerelease: m[4] && patch !== null ? m[4].split(".") : [] };
+}
+const sv = (major, minor, patch, prerelease = []) => ({ major, minor, patch, prerelease });
+/** The lowest version of the next line: the `-0` prerelease, so 2.0.0-beta is excluded by "<2.0.0-0". */
+const below = (major, minor, patch) => ({ op: "<", v: sv(major, minor, patch, ["0"]) });
+function floorOf(p) {
+    return sv(p.major ?? 0, p.minor ?? 0, p.patch ?? 0, p.prerelease);
+}
+function caret(p) {
+    if (p.major === null)
+        return [];
+    const lo = { op: ">=", v: floorOf(p) };
+    if (p.major > 0)
+        return [lo, below(p.major + 1, 0, 0)];
+    if (p.minor === null)
+        return [lo, below(1, 0, 0)];
+    if (p.minor > 0)
+        return [lo, below(0, p.minor + 1, 0)];
+    if (p.patch === null)
+        return [lo, below(0, 1, 0)];
+    return [lo, below(0, 0, p.patch + 1)];
+}
+function tilde(p) {
+    if (p.major === null)
+        return [];
+    const lo = { op: ">=", v: floorOf(p) };
+    if (p.minor === null)
+        return [lo, below(p.major + 1, 0, 0)];
+    return [lo, below(p.major, p.minor + 1, 0)];
+}
+/** An x-range or partial version as a range: "1.2" = >=1.2.0 <1.3.0-0. */
+function xrange(p) {
+    if (p.major === null)
+        return [];
+    if (p.minor === null)
+        return [{ op: ">=", v: sv(p.major, 0, 0) }, below(p.major + 1, 0, 0)];
+    if (p.patch === null)
+        return [{ op: ">=", v: sv(p.major, p.minor, 0) }, below(p.major, p.minor + 1, 0)];
+    return [{ op: "=", v: floorOf(p) }];
+}
+function primitive(op, p) {
+    if (op === "=")
+        return xrange(p);
+    if (p.major === null)
+        return op === "<" || op === ">" ? null : [];
+    const full = p.patch !== null;
+    if (full)
+        return [{ op, v: floorOf(p) }];
+    // Partial bounds widen or narrow to the whole line, as node-semver does.
+    const next = p.minor === null ? sv(p.major + 1, 0, 0) : sv(p.major, p.minor + 1, 0);
+    switch (op) {
+        case ">=":
+            return [{ op: ">=", v: floorOf(p) }];
+        case ">":
+            return [{ op: ">=", v: next }];
+        case "<":
+            return [{ op: "<", v: sv(p.major, p.minor ?? 0, 0, ["0"]) }];
+        case "<=":
+            return [{ op: "<", v: { ...next, prerelease: ["0"] } }];
+    }
+}
+/** One comparator token: "^1.2", ">=1.0.0", "~0.3", "1.x". `bareIsCaret` = Cargo's reading of "1.2.3". */
+function comparatorSet(token, bareIsCaret) {
+    const m = /^(\^|~>?|>=|<=|>|<|=)?\s*(.*)$/.exec(token.trim());
+    if (!m)
+        return null;
+    const p = parsePartial(m[2]);
+    if (!p)
+        return null;
+    switch (m[1]) {
+        case "^":
+            return caret(p);
+        case "~":
+        case "~>":
+            return tilde(p);
+        case ">=":
+        case "<=":
+        case ">":
+        case "<":
+            return primitive(m[1], p);
+        case "=":
+            return xrange(p);
+        default:
+            return bareIsCaret && p.major !== null ? caret(p) : xrange(p);
+    }
+}
+function test(set, version) {
+    for (const c of set) {
+        const d = comparePrecedence(version, c.v);
+        const ok = c.op === ">=" ? d >= 0 : c.op === ">" ? d > 0 : c.op === "<" ? d < 0 : c.op === "<=" ? d <= 0 : d === 0;
+        if (!ok)
+            return false;
+    }
+    if (version.prerelease.length === 0)
+        return true;
+    // A prerelease satisfies only a set that names a prerelease of the same
+    // MAJOR.MINOR.PATCH (node-semver and Cargo agree on this).
+    return set.some((c) => c.v.prerelease.length > 0 &&
+        !(c.v.prerelease.length === 1 && c.v.prerelease[0] === "0" && c.op === "<") &&
+        c.v.major === version.major &&
+        c.v.minor === version.minor &&
+        c.v.patch === version.patch);
+}
+/**
+ * Whether an npm range admits `version`. Null when the range is not a
+ * registry semver range (git, file, link, workspace, alias, tag) or the
+ * version is unreadable.
+ */
+export function npmRangeAdmits(range, version) {
+    const v = parseSemverPrecedence(version);
+    if (!v)
+        return null;
+    // yarn berry writes "npm:^1.2.0"; an alias ("npm:other@^1") names another package.
+    const text = range.trim().replace(/^npm:(?=[\^~<>=\dvxX*\s]|$)/, "");
+    // Protocols (git+https:, file:, link:, workspace:, npm:alias@), paths, GitHub shorthand.
+    if (/^[a-z][a-z+]*:/i.test(text) || text.includes("/"))
+        return null;
+    // A dist-tag ("latest", "next", "beta").
+    if (/^[a-z][\w.-]*$/i.test(text) && !WILD.test(text))
+        return null;
+    for (const alt of text.split("||")) {
+        const part = alt.trim();
+        let set = [];
+        const hyphen = /^(\S+)\s+-\s+(\S+)$/.exec(part);
+        if (hyphen) {
+            const lo = parsePartial(hyphen[1]);
+            const hi = parsePartial(hyphen[2]);
+            if (!lo || !hi)
+                return null;
+            set.push({ op: ">=", v: floorOf(lo) });
+            const upper = hi.patch !== null ? [{ op: "<=", v: floorOf(hi) }] : primitive("<=", hi);
+            if (!upper)
+                return null;
+            set.push(...upper);
+        }
+        else {
+            // ">= 1.2.3" with a space after the operator is one comparator.
+            for (const token of part.replace(/([<>=~^])\s+/g, "$1").split(/\s+/).filter(Boolean)) {
+                const c = comparatorSet(token, false);
+                if (c === null)
+                    return null;
+                set = set.concat(c);
+            }
+        }
+        if (test(set, v))
+            return true;
+    }
+    return false;
+}
+/** Whether a Cargo version requirement ("0.8", "^1.2", ">=0.10, <0.11", "=1.0.5") admits `version`. Null when unreadable. */
+export function cargoReqAdmits(req, version) {
+    const v = parseSemverPrecedence(version);
+    if (!v)
+        return null;
+    let set = [];
+    for (const token of req.split(",").map((t) => t.trim()).filter(Boolean)) {
+        const c = comparatorSet(token, true);
+        if (c === null)
+            return null;
+        set = set.concat(c);
+    }
+    return test(set, v);
+}

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

@@ -12,6 +12,12 @@ export declare const DEFAULT_RATE_LIMITS: {
     osv: {
         maxPerMinute: number;
     };
+    "osv-package": {
+        maxPerMinute: number;
+    };
+    "fixpath-registry": {
+        maxPerMinute: number;
+    };
     hn: {
         maxPerMinute: number;
     };

package/dist/live/rate-limiter.js

@@ -47,6 +47,11 @@ export class RateLimiter {
 }
 export const DEFAULT_RATE_LIMITS = {
     osv: { maxPerMinute: 10 },
+    // 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
+    // documents): separate from the API buckets so a plan never starves health checks.
+    "fixpath-registry": { maxPerMinute: 600 },
     hn: { maxPerMinute: 30 },
     npm: { maxPerMinute: 120 },
     crates: { maxPerMinute: 50 },

package/dist/live/registry-health.js

@@ -10,6 +10,7 @@ function unavailable(dep, fetchError) {
         latestVersion: null, latestStableVersion: null, versionsBehind: null,
         deprecated: false, deprecationMessage: null, lastPublished: null,
         license: null, weeklyDownloads: null, isDev: dep.isDev, fetchError,
+        ...(dep.declaredRange ? { declaredRange: dep.declaredRange } : {}),
     };
 }
 export async function fetchRegistryHealthFor(deps, registries, enabled) {
@@ -70,5 +71,6 @@ function restampRegistryContext(info, dep) {
         currentVersion: dep.version,
         isDev: dep.isDev,
         versionsBehind: dep.version && latest ? computeSemverDistance(dep.version, latest) : null,
+        ...(dep.declaredRange ? { declaredRange: dep.declaredRange } : {}),
     };
 }