@4da/mcp-server 6.0.1 → 6.1.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/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 } : {}),
     };
 }

package/dist/live/resolution.d.ts

@@ -33,8 +33,18 @@ export interface GroupResolution {
     /** The full lockfile set plus drift entries (vulnerability scanning). */
     audit: ResolvedDependency[];
     drift: InstallDriftRecord[];
-    /** The file the versions were read from, or null when the group resolved from nothing. */
+    /** The (first) file the versions were read from, or null when the group resolved from nothing. */
     source: ResolutionSourceRecord | null;
+    /** Every file read, `source` first (Python merges its lockfiles and requirement files). */
+    sources: ResolutionSourceRecord[];
+    /**
+     * Set when no lockfile pins this group's versions: the manifest and how many
+     * of its dependencies are declared ranges, which are not sent to OSV.
+     */
+    unresolved: {
+        manifest: string;
+        ranges: number;
+    } | null;
     signatures: Map<string, FileSignature>;
     resolvedAt: string;
 }

package/dist/live/resolution.js

@@ -30,11 +30,20 @@ export function resolveGroup(group) {
         ...(manifest ? [manifest] : []),
     ]);
     const read = resolveVersionSource(group.dir, ecosystem);
+    const readFiles = read.source ? [read.source, ...(read.extraSources ?? [])] : [];
     // The manifest only matters when the resolver fell back to it; editing a
     // script in package.json must not throw away a scan of an unchanged lockfile.
-    if (manifest && read.kind === "lockfile")
+    if (manifest && !readFiles.includes(manifest))
         signatures.delete(manifest);
     let resolved = resolveVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets);
+    // No lockfile: a ranged dependency's version is the range's floor, a label.
+    const ranges = read.kind === "declared_ranges" ? read.ranges ?? new Map() : null;
+    if (ranges && ranges.size > 0) {
+        resolved = resolved.map((dep) => {
+            const declaredRange = ranges.get(dep.name);
+            return declaredRange ? { ...dep, declaredRange } : dep;
+        });
+    }
     let drift = [];
     let driftAudit = [];
     // Only a lockfile pins exact versions; comparing node_modules against a
@@ -50,11 +59,12 @@ export function resolveGroup(group) {
     const audit = [
         ...resolveAuditVersionsFrom(group.dir, group.deps, group.devDeps, ecosystem, read.versions, group.targets, resolved, read.instances),
         ...driftAudit,
-    ];
-    const source = read.source && read.kind
-        ? { path: read.source, kind: read.kind, mtimeMs: signatureMtime(signatures.get(read.source)) }
-        : null;
-    return { group, resolved, audit, drift, source, signatures, resolvedAt };
+    ].filter((dep) => !dep.declaredRange);
+    const sources = read.kind
+        ? readFiles.map((file) => ({ path: file, kind: read.kind, mtimeMs: signatureMtime(signatures.get(file)) }))
+        : [];
+    const unresolved = ranges && ranges.size > 0 && read.source ? { manifest: read.source, ranges: ranges.size } : null;
+    return { group, resolved, audit, drift, source: sources[0] ?? null, sources, unresolved, signatures, resolvedAt };
 }
 /** True when any file the resolution depended on changed, appeared, or vanished. */
 export function groupIsStale(result) {

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

@@ -1,5 +1,13 @@
 import type { SemverDistance } from "./types.js";
 export declare function parseSemver(version: string): [number, number, number] | null;
+/**
+ * How far `current` is behind `latest`. `label` is the kind of bump, by the
+ * caret rules npm and Cargo apply: below 1.0 a minor bump is breaking (^0.8.6
+ * does not admit 0.9.0) and below 0.1 a patch bump is too (^0.0.3 is =0.0.3),
+ * so both are labelled "major", the same as upgrade_impact and dependency_check.
+ * Until 6.0.2 sqlx 0.8 -> 0.9 and reqwest 0.12 -> 0.13 were labelled "minor".
+ * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
+ */
 export declare function computeSemverDistance(current: string, latest: string): SemverDistance | null;
 export declare function isPreRelease(version: string): boolean;
 /**

package/dist/live/semver-utils.js

@@ -5,6 +5,14 @@ export function parseSemver(version) {
         return null;
     return [parseInt(match[1]), parseInt(match[2]), parseInt(match[3])];
 }
+/**
+ * How far `current` is behind `latest`. `label` is the kind of bump, by the
+ * caret rules npm and Cargo apply: below 1.0 a minor bump is breaking (^0.8.6
+ * does not admit 0.9.0) and below 0.1 a patch bump is too (^0.0.3 is =0.0.3),
+ * so both are labelled "major", the same as upgrade_impact and dependency_check.
+ * Until 6.0.2 sqlx 0.8 -> 0.9 and reqwest 0.12 -> 0.13 were labelled "minor".
+ * The numeric fields stay literal (0.8.6 -> 0.9.0 is major 0, minor 1).
+ */
 export function computeSemverDistance(current, latest) {
     const c = parseSemver(current);
     const l = parseSemver(latest);
@@ -17,9 +25,9 @@ export function computeSemverDistance(current, latest) {
     if (major > 0)
         label = "major";
     else if (minor > 0)
-        label = "minor";
+        label = c[0] === 0 ? "major" : "minor";
     else if (patch > 0)
-        label = "patch";
+        label = c[0] === 0 && c[1] === 0 ? "major" : "patch";
     return { major: Math.max(0, major), minor: Math.max(0, minor), patch: Math.max(0, patch), label };
 }
 export function isPreRelease(version) {

package/dist/live/types.d.ts

@@ -37,6 +37,12 @@ export interface ResolvedDependency {
     installDriftOf?: string;
     /** On drift entries: the command that reinstalls from the lockfile. */
     installFix?: InstallFixCommand;
+    /**
+     * Set when no lockfile pins this dependency: the requirement the manifest
+     * declares ("^1.2.0"). `version` is then that range's floor, NOT an
+     * installed version, and the dependency is never sent to OSV as if it were.
+     */
+    declaredRange?: string;
 }
 /**
  * One npm direct dependency whose installed copy differs from its lockfile.
@@ -54,7 +60,8 @@ export interface InstallDriftRecord {
 export interface ResolutionSourceRecord {
     /** Absolute path. */
     path: string;
-    kind: "lockfile" | "manifest";
+    /** lockfile = exact versions; manifest = exact requirement pins; declared_ranges = no lockfile, range floors only. */
+    kind: "lockfile" | "manifest" | "declared_ranges";
     /** Modification time when it was read, or null if it vanished since. */
     mtimeMs: number | null;
 }
@@ -88,8 +95,12 @@ export interface OsvVulnerability {
             events: Array<{
                 introduced?: string;
                 fixed?: string;
+                last_affected?: string;
+                limit?: string;
             }>;
         }>;
+        /** Versions listed explicitly, in addition to (or instead of) the ranges. */
+        versions?: string[];
     }>;
     references?: Array<{
         type: string;
@@ -191,6 +202,11 @@ export interface RegistryPackageInfo {
     weeklyDownloads: number | null;
     isDev: boolean;
     fetchError: string | null;
+    /**
+     * No lockfile: the declared requirement ("^1.2.0"); `currentVersion` is then
+     * its floor, not an installed version.
+     */
+    declaredRange?: string;
     /**
      * The version node_modules actually holds, present only when it differs
      * from `currentVersion` (the lockfile's). Several differing installs across

package/dist/live/upgrade-sources.d.ts

@@ -59,6 +59,8 @@ export declare function isValidPackageName(name: string, ecosystem: UpgradeEcosy
 export declare function getRegistryIndex(net: UpgradeNet, ecosystem: UpgradeEcosystem, name: string): Promise<RegistryIndex | null>;
 /** The registry archive URL for one version, or null when it is not on the package's own registry. */
 export declare function archiveUrl(index: RegistryIndex, version: PublishedVersion): string | null;
+/** Cache key of one version's parsed changelog; it carries CHANGELOG_PARSER_VERSION. */
+export declare function changelogCacheKey(ecosystem: string, name: string, version: string): string;
 /** Parsed changelog shipped inside one version's archive (cached 7 days per version). */
 export declare function getChangelog(net: UpgradeNet, index: RegistryIndex, version: PublishedVersion): Promise<ChangelogResult>;
 /** OSV advisory ids affecting one version, or null when OSV could not be reached. */