@4da/mcp-server 5.0.3 → 6.0.0

package/dist/live/upgrade-sources.js

@@ -0,0 +1,198 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Network sources for `upgrade_impact`: registry version index, the target
+ * version's changelog (read from its registry archive) and OSV advisories.
+ *
+ * Privacy rule (Decision 1, option A): the only hosts contacted are the
+ * package's own registry (registry.npmjs.org; crates.io + static.crates.io)
+ * and api.osv.dev. A changelog is never fetched from GitHub or a docs site,
+ * even when the archive ships none — the report then hands the agent a
+ * `release_notes_url` built from registry metadata, and the agent decides
+ * whether to fetch it. Every request goes through `UpgradeNet`, which records
+ * the host so `_meta.sources` is a fact, not a claim, and which tests replace
+ * with a fake fetch.
+ *
+ * Request budget per call: index (1) + archive (1) + OSV for from/to (2) = 4,
+ * each cached (index 6 h, parsed changelog 7 d, OSV 1 h). The npm packument
+ * is large (vite's is ~39 MB, measured 2026-10-02), so only a reduced index
+ * is cached — never the raw document.
+ */
+import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
+import { ArchiveError, defaultFetch, fetchArchiveRootFiles } from "./package-archive.js";
+import { findChangelogFile, isChangelogName, parseChangelog } from "./changelog.js";
+/** crates.io refuses API requests without a descriptive User-Agent. */
+export const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
+const INDEX_TTL = 6 * 3600;
+const CHANGELOG_TTL = 7 * 86_400;
+const OSV_TTL = 3600;
+const CACHE_SOURCE = "upgrade-impact";
+const INDEX_TIMEOUT_MS = 30_000;
+const OSV_TIMEOUT_MS = 10_000;
+export function createUpgradeNet(cache, fetchFn = defaultFetch) {
+    const contacted = new Set();
+    return {
+        contacted,
+        cache,
+        fetch: (url, init, timeoutMs) => {
+            contacted.add(new URL(url).host);
+            return fetchFn(url, init, timeoutMs);
+        },
+    };
+}
+const NPM_NAME = /^(?:@[a-z0-9-~][a-z0-9-._~]*\/)?[a-z0-9-~][a-z0-9-._~]*$/i;
+const CRATE_NAME = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/;
+export function isValidPackageName(name, ecosystem) {
+    return ecosystem === "npm" ? NPM_NAME.test(name) && name.length <= 214 : CRATE_NAME.test(name);
+}
+async function cached(net, key, ttl, load) {
+    const hit = net.cache?.get(key);
+    if (hit !== null && hit !== undefined)
+        return hit;
+    const value = await load();
+    net.cache?.set(key, value, CACHE_SOURCE, ttl);
+    return value;
+}
+function repositoryUrl(repo) {
+    if (typeof repo === "string")
+        return repo;
+    if (repo && typeof repo === "object" && typeof repo.url === "string") {
+        return repo.url;
+    }
+    return null;
+}
+async function loadNpmIndex(net, name) {
+    const url = `https://registry.npmjs.org/${name.replaceAll("/", "%2F")}`;
+    const res = await net.fetch(url, { headers: { Accept: "application/json" } }, INDEX_TIMEOUT_MS);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`npm registry HTTP ${res.status} for ${name}`);
+    const doc = (await res.json());
+    const versions = Object.entries(doc.versions ?? {}).map(([version, meta]) => {
+        const entry = { version, published: doc.time?.[version] ?? null };
+        if (typeof meta.deprecated === "string" && meta.deprecated)
+            entry.deprecated = meta.deprecated;
+        if (meta.dist?.tarball)
+            entry.tarball = meta.dist.tarball;
+        return entry;
+    });
+    return { name: doc.name ?? name, ecosystem: "npm", versions, repository: repositoryUrl(doc.repository) };
+}
+async function loadCratesIndex(net, name) {
+    const url = `https://crates.io/api/v1/crates/${encodeURIComponent(name)}`;
+    const headers = { Accept: "application/json", "User-Agent": CRATES_USER_AGENT };
+    const res = await net.fetch(url, { headers }, INDEX_TIMEOUT_MS);
+    if (res.status === 404)
+        return null;
+    if (!res.ok)
+        throw new Error(`crates.io HTTP ${res.status} for ${name}`);
+    const doc = (await res.json());
+    const versions = (doc.versions ?? [])
+        .filter((v) => typeof v.num === "string")
+        .map((v) => {
+        const entry = { version: v.num, published: v.created_at ?? null };
+        if (v.yanked)
+            entry.yanked = true;
+        return entry;
+    });
+    return { name: doc.crate?.name ?? name, ecosystem: "crates.io", versions, repository: doc.crate?.repository ?? null };
+}
+/** Registry index with versions in ascending precedence order (unreadable versions dropped). Null = unknown package. */
+export async function getRegistryIndex(net, ecosystem, name) {
+    const key = `upgrade-impact:index:${ecosystem}:${ecosystem === "crates.io" ? name.replace(/-/g, "_") : name}`;
+    const index = await cached(net, key, INDEX_TTL, () => ecosystem === "npm" ? loadNpmIndex(net, name) : loadCratesIndex(net, name));
+    if (!index)
+        return null;
+    const versions = index.versions
+        .filter((v) => parseSemverPrecedence(v.version) !== null)
+        .sort((a, b) => compareVersionPrecedence(a.version, b.version) ?? 0);
+    return { ...index, versions };
+}
+const ARCHIVE_HOSTS = new Set(["registry.npmjs.org", "static.crates.io"]);
+/** The registry archive URL for one version, or null when it is not on the package's own registry. */
+export function archiveUrl(index, version) {
+    const url = index.ecosystem === "crates.io"
+        ? `https://static.crates.io/crates/${index.name}/${index.name}-${version.version}.crate`
+        : version.tarball;
+    if (!url)
+        return null;
+    try {
+        const parsed = new URL(url);
+        return parsed.protocol === "https:" && ARCHIVE_HOSTS.has(parsed.host) ? url : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Parsed changelog shipped inside one version's archive (cached 7 days per version). */
+export async function getChangelog(net, index, version) {
+    const url = archiveUrl(index, version);
+    if (!url) {
+        return { found: false, reason: "the version's archive is not hosted on the package's own registry" };
+    }
+    const key = `upgrade-impact:changelog:${index.ecosystem}:${index.name}:${version.version}`;
+    const hit = net.cache?.get(key);
+    if (hit)
+        return hit;
+    const headers = index.ecosystem === "crates.io" ? { "User-Agent": CRATES_USER_AGENT } : {};
+    let files;
+    try {
+        files = await fetchArchiveRootFiles(url, isChangelogName, net.fetch, headers);
+    }
+    catch (err) {
+        const result = { found: false, reason: `could not read the ${version.version} archive: ${err.message}` };
+        // A published archive never changes, so a cap or format refusal is permanent;
+        // a network failure is not, and must not be remembered for a week.
+        if (err instanceof ArchiveError)
+            net.cache?.set(key, result, CACHE_SOURCE, CHANGELOG_TTL);
+        return result;
+    }
+    const file = findChangelogFile(files.keys());
+    const sections = file ? parseChangelog(files.get(file) ?? "") : [];
+    const result = !file
+        ? { found: false, reason: `the ${version.version} archive ships no changelog file` }
+        : sections.length === 0
+            ? { found: false, file, reason: `${file} has no version headings this parser recognises` }
+            : { found: true, file, sections };
+    net.cache?.set(key, result, CACHE_SOURCE, CHANGELOG_TTL);
+    return result;
+}
+/** OSV advisory ids affecting one version, or null when OSV could not be reached. */
+export async function getOsvAdvisories(net, ecosystem, name, version) {
+    const key = `upgrade-impact:osv:${ecosystem}:${name}:${version}`;
+    const hit = net.cache?.get(key);
+    if (hit)
+        return hit;
+    try {
+        const res = await net.fetch("https://api.osv.dev/v1/query", {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({ package: { name, ecosystem }, version }),
+        }, OSV_TIMEOUT_MS);
+        if (!res.ok)
+            return null;
+        const body = (await res.json());
+        const ids = (body.vulns ?? []).map((v) => v.id).filter((id) => typeof id === "string");
+        net.cache?.set(key, ids, CACHE_SOURCE, OSV_TTL);
+        return ids;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Release-notes page derived from the registry's own `repository` field: a
+ * GitHub repo becomes `https://github.com/<owner>/<repo>/releases`; any other
+ * https repository URL is returned as-is; anything else is null.
+ */
+export function releaseNotesUrl(repository) {
+    if (!repository)
+        return null;
+    const raw = repository.trim();
+    const shorthand = /^(?:github:)?([\w.-]+)\/([\w.-]+)$/.exec(raw);
+    const gh = shorthand ?? /github\.com[/:]([\w.-]+)\/([\w.-]+?)(?:\.git)?(?:[/#?].*)?$/i.exec(raw);
+    if (gh)
+        return `https://github.com/${gh[1]}/${gh[2].replace(/\.git$/, "")}/releases`;
+    const https = raw.replace(/^git\+/, "");
+    return /^https:\/\//i.test(https) ? https.replace(/\.git$/, "") : null;
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Version ordering per ecosystem, for advisory ranges and fix selection.
+ *
+ * `compareSemver` reads MAJOR.MINOR.PATCH and calls anything else "equal".
+ * That is wrong outside npm and crates.io, and it was wrong in practice
+ * (measured 2026-10-02 against pip-audit and osv-scanner):
+ * - PyPI versions are PEP 440, not semver. `5.1` and `4.2` are ordinary
+ *   releases; read as "equal" to everything, django 3.2.0 was sent to the 5.1
+ *   line's fix (5.1.1) instead of its own line's (3.2.25 / 4.2.16).
+ * - Go versions carry a `v`, OSV's Go ranges do not, and pseudo-versions
+ *   (`v0.0.0-20200622213623-75b288015ac9`) order as semver prereleases.
+ *
+ * `0` is OSV's "since the beginning" bound and orders below every version.
+ */
+import type { OsvEcosystem } from "./types.js";
+interface Pep440 {
+    epoch: number;
+    release: number[];
+    /** Pre-release: [rank, n] with a=0, b=1, rc=2; null for none. */
+    pre: [number, number] | null;
+    post: number | null;
+    dev: number | null;
+}
+export declare function parsePep440(version: string): Pep440 | null;
+export declare function comparePep440(a: Pep440, b: Pep440): number;
+/** Whether `version` is readable for this ecosystem's ordering. */
+export declare function isComparable(version: string, ecosystem: OsvEcosystem | string): boolean;
+/**
+ * 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;
+/** 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. */
+export declare function samePackageName(a: string, b: string, ecosystem: OsvEcosystem | string): boolean;
+/** Whether a user-typed package name (`package` parameters) names this dependency: registry rules, then case-insensitive. */
+export declare function namesPackage(query: string, name: string, ecosystem: OsvEcosystem | string): boolean;
+export {};

package/dist/live/version-compare.js

@@ -0,0 +1,130 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Version ordering per ecosystem, for advisory ranges and fix selection.
+ *
+ * `compareSemver` reads MAJOR.MINOR.PATCH and calls anything else "equal".
+ * That is wrong outside npm and crates.io, and it was wrong in practice
+ * (measured 2026-10-02 against pip-audit and osv-scanner):
+ * - PyPI versions are PEP 440, not semver. `5.1` and `4.2` are ordinary
+ *   releases; read as "equal" to everything, django 3.2.0 was sent to the 5.1
+ *   line's fix (5.1.1) instead of its own line's (3.2.25 / 4.2.16).
+ * - Go versions carry a `v`, OSV's Go ranges do not, and pseudo-versions
+ *   (`v0.0.0-20200622213623-75b288015ac9`) order as semver prereleases.
+ *
+ * `0` is OSV's "since the beginning" bound and orders below every version.
+ */
+import { compareSemver, parseSemver } from "./semver-utils.js";
+import { compareVersionPrecedence, parseSemverPrecedence } from "./semver-precedence.js";
+const PEP440 = /^v?(?:(\d+)!)?(\d+(?:\.\d+)*)(?:[-_.]?(a|alpha|b|beta|c|rc|pre|preview)[-_.]?(\d*))?(?:(?:[-_.]?(?:post|rev|r)[-_.]?(\d*))|-(\d+))?(?:[-_.]?dev[-_.]?(\d*))?(?:\+[a-z0-9]+(?:[-_.][a-z0-9]+)*)?$/i;
+export function parsePep440(version) {
+    const m = PEP440.exec(version.trim());
+    if (!m)
+        return null;
+    const preRank = { a: 0, alpha: 0, b: 1, beta: 1, c: 2, rc: 2, pre: 2, preview: 2 };
+    return {
+        epoch: m[1] ? Number(m[1]) : 0,
+        release: m[2].split(".").map(Number),
+        pre: m[3] ? [preRank[m[3].toLowerCase()], m[4] ? Number(m[4]) : 0] : null,
+        post: m[5] !== undefined ? (m[5] ? Number(m[5]) : 0) : m[6] !== undefined ? Number(m[6]) : null,
+        dev: m[7] !== undefined ? (m[7] ? Number(m[7]) : 0) : null,
+    };
+}
+export function comparePep440(a, b) {
+    if (a.epoch !== b.epoch)
+        return a.epoch > b.epoch ? 1 : -1;
+    const len = Math.max(a.release.length, b.release.length);
+    for (let i = 0; i < len; i++) {
+        const x = a.release[i] ?? 0;
+        const y = b.release[i] ?? 0;
+        if (x !== y)
+            return x > y ? 1 : -1;
+    }
+    // PEP 440's sort key within one release:
+    //   X.devN < X.aN.devM < X.aN < X.aN.postM < X.bN < X.rcN < X < X.postN.devM < X.postN
+    // pre: a/b/rc rank, a dev-only release below every pre-release, a final above;
+    // then post (none lowest); then dev (none highest).
+    const key = (v) => [
+        v.pre ? v.pre[0] : v.post === null && v.dev !== null ? -1 : 3,
+        v.pre ? v.pre[1] : 0,
+        v.post === null ? -1 : v.post,
+        v.dev === null ? Number.POSITIVE_INFINITY : v.dev,
+    ];
+    const ka = key(a);
+    const kb = key(b);
+    for (let i = 0; i < ka.length; i++) {
+        if (ka[i] !== kb[i])
+            return ka[i] > kb[i] ? 1 : -1;
+    }
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Dispatch
+// ---------------------------------------------------------------------------
+const stripGoV = (v) => v.replace(/^v(?=\d)/, "");
+/** Whether `version` is readable for this ecosystem's ordering. */
+export function isComparable(version, ecosystem) {
+    if (version === "0")
+        return true;
+    switch (ecosystem) {
+        case "PyPI":
+            return parsePep440(version) !== null;
+        case "Go":
+            return parseSemverPrecedence(stripGoV(version)) !== null;
+        case "npm":
+        case "crates.io":
+            return parseSemverPrecedence(version) !== null;
+        default:
+            return parseSemver(version) !== 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 function compareVersions(a, b, ecosystem) {
+    if (a === b)
+        return 0;
+    if (a === "0")
+        return isComparable(b, ecosystem) ? -1 : 0;
+    if (b === "0")
+        return isComparable(a, ecosystem) ? 1 : 0;
+    switch (ecosystem) {
+        case "PyPI": {
+            const pa = parsePep440(a);
+            const pb = parsePep440(b);
+            return pa && pb ? comparePep440(pa, pb) : 0;
+        }
+        case "Go":
+            return compareVersionPrecedence(stripGoV(a), stripGoV(b)) ?? 0;
+        case "npm":
+        case "crates.io":
+            return compareVersionPrecedence(a, b) ?? compareSemver(a, b);
+        default:
+            return compareSemver(a, b);
+    }
+}
+/** Highest of `versions` in this ecosystem's order, or null when empty. */
+export function maxVersion(versions, ecosystem) {
+    if (versions.length === 0)
+        return null;
+    return versions.reduce((max, v) => (compareVersions(v, max, ecosystem) > 0 ? v : max), versions[0]);
+}
+/** Package-name equality as the ecosystem's registry defines it. */
+export function samePackageName(a, b, ecosystem) {
+    if (a === b)
+        return true;
+    if (ecosystem === "PyPI") {
+        const n = (s) => s.toLowerCase().replace(/[-_.]+/g, "-");
+        return n(a) === n(b);
+    }
+    if (ecosystem === "crates.io") {
+        const n = (s) => s.toLowerCase().replace(/_/g, "-");
+        return n(a) === n(b);
+    }
+    return false;
+}
+/** Whether a user-typed package name (`package` parameters) names this dependency: registry rules, then case-insensitive. */
+export function namesPackage(query, name, ecosystem) {
+    const q = query.trim();
+    return samePackageName(q, name, ecosystem) || q.toLowerCase() === name.toLowerCase();
+}

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

@@ -3,9 +3,12 @@
  *
  * Extracts exact dependency versions from lock files.
  * Priority: lock file (exact) > manifest (range/specifier).
- * Uses only Node.js built-ins — no external parsers.
+ * Uses only Node.js built-ins — no external parsers. The per-ecosystem
+ * parsers live in lockfile-parsers.ts, which also reports which file each
+ * resolution read from.
  */
 import type { OsvEcosystem, ResolvedDependency } from "./types.js";
+import { type PackageInstance } from "./lockfile-parsers.js";
 /**
  * Map a language/ecosystem alias to its OSV ecosystem id (case-insensitive).
  *
@@ -18,8 +21,18 @@ import type { OsvEcosystem, ResolvedDependency } from "./types.js";
  */
 export declare function mapEcosystem(language: string): OsvEcosystem;
 export declare function resolveVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
+/** `resolveVersions` over a version map the caller already read from `cwd`. */
+export declare function resolveVersionsFrom(cwd: string, deps: string[], devDeps: string[], ecosystem: OsvEcosystem, versionMap: Map<string, string>, targets?: Record<string, string>): ResolvedDependency[];
 /**
  * Resolve the complete lockfile package set for vulnerability scanning.
  * Direct dependency health and upgrade planning continue to use resolveVersions.
  */
 export declare function resolveAuditVersions(cwd: string, deps: string[], devDeps: string[], language: string, targets?: Record<string, string>): ResolvedDependency[];
+/**
+ * `resolveAuditVersions` over a version map the caller already read. `direct`
+ * lets the caller pass direct entries it has already enriched (install state)
+ * so the audit set carries the same objects' context. `instances` is every
+ * installed copy the lockfile holds; without it the version map (one copy per
+ * name) is all there is.
+ */
+export declare function resolveAuditVersionsFrom(cwd: string, deps: string[], devDeps: string[], ecosystem: OsvEcosystem, versionMap: Map<string, string>, targets?: Record<string, string>, direct?: ResolvedDependency[], instances?: PackageInstance[]): ResolvedDependency[];