@4da/mcp-server 5.0.4 → 6.0.1

package/dist/live/severity-scope.d.ts

@@ -0,0 +1,57 @@
+/**
+ * One severity rule for every surface (AD-046).
+ *
+ * The desktop app grades an advisory by where the vulnerable package sits in
+ * the dependency graph, and every 4DA surface presents that one grade. This
+ * module is the MCP server's copy of the rule. Its Rust twin is
+ * `osv::identity::scope_adjusted_urgency` (src-tauri/src/osv/identity.rs):
+ * change one, change both, or the MCP server and the app disagree about the
+ * same advisory again.
+ *
+ * Measured 2026-09-10: `vulnerability_scan` graded `sandbox@3.1.2` (a
+ * transitive of paddle-webhook, dev/runtime scope unknown) CRITICAL
+ * (`by_severity.critical: 1`, and the briefing read "CRITICAL: Sandbox
+ * Breakout") while the app graded the same advisory High.
+ *
+ * The rule, applied in this order:
+ *   (a) transitive-only clamps critical to high;
+ *   (b) dev-only drops ONE level: critical to high, high to medium, medium to
+ *       low; low stays low.
+ * `unknown` stays `unknown` through both steps. Unknown dev scope is not dev:
+ * no discount without evidence. The advisory's own tier is never discarded;
+ * surfaces carry it beside the presented grade as `advisory_severity`.
+ */
+import type { VulnerabilityEntry } from "./types.js";
+export type SeverityTier = VulnerabilityEntry["severity"];
+export interface DependencyScope {
+    isDirect: boolean;
+    isDev: boolean;
+    devScopeKnown: boolean;
+}
+/** Ordering for sorts and "at or above" filters; unknown ranks lowest. */
+export declare const SEVERITY_RANK: Record<SeverityTier, number>;
+/**
+ * THE rule. Twin of the Rust `osv::identity::scope_adjusted_urgency`.
+ *
+ * direct runtime critical -> critical; transitive runtime critical -> high;
+ * direct dev critical -> high; transitive dev critical -> medium;
+ * direct dev high -> medium; transitive dev high -> medium;
+ * transitive runtime high -> high.
+ */
+export declare function scopeAdjustedSeverity(advisory: SeverityTier, scope: DependencyScope): SeverityTier;
+type ScopedEntry = Pick<VulnerabilityEntry, "severity" | "isDirect" | "isDev" | "devScopeKnown">;
+/**
+ * The grade a surface presents for one scan entry. A missing `isDirect`
+ * (never produced today; defensive for foreign cache rows) is treated as
+ * direct, and a missing `devScopeKnown` as unknown: both mean no discount.
+ */
+export declare function presentedSeverity(v: ScopedEntry): SeverityTier;
+/**
+ * Why the presented grade differs from the advisory's own tier, in words, or
+ * null when it does not differ.
+ */
+export declare function scopeAdjustmentReason(v: ScopedEntry): string | null;
+export type SeverityCounts = Record<SeverityTier, number>;
+/** Count entries per tier, using whichever tier function the caller names. */
+export declare function countBySeverity<T>(entries: T[], tierOf: (entry: T) => SeverityTier): SeverityCounts;
+export {};

package/dist/live/severity-scope.js

@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * One severity rule for every surface (AD-046).
+ *
+ * The desktop app grades an advisory by where the vulnerable package sits in
+ * the dependency graph, and every 4DA surface presents that one grade. This
+ * module is the MCP server's copy of the rule. Its Rust twin is
+ * `osv::identity::scope_adjusted_urgency` (src-tauri/src/osv/identity.rs):
+ * change one, change both, or the MCP server and the app disagree about the
+ * same advisory again.
+ *
+ * Measured 2026-09-10: `vulnerability_scan` graded `sandbox@3.1.2` (a
+ * transitive of paddle-webhook, dev/runtime scope unknown) CRITICAL
+ * (`by_severity.critical: 1`, and the briefing read "CRITICAL: Sandbox
+ * Breakout") while the app graded the same advisory High.
+ *
+ * The rule, applied in this order:
+ *   (a) transitive-only clamps critical to high;
+ *   (b) dev-only drops ONE level: critical to high, high to medium, medium to
+ *       low; low stays low.
+ * `unknown` stays `unknown` through both steps. Unknown dev scope is not dev:
+ * no discount without evidence. The advisory's own tier is never discarded;
+ * surfaces carry it beside the presented grade as `advisory_severity`.
+ */
+const ONE_LEVEL_DOWN = {
+    critical: "high",
+    high: "medium",
+    medium: "low",
+    low: "low",
+    unknown: "unknown",
+};
+/** Ordering for sorts and "at or above" filters; unknown ranks lowest. */
+export const SEVERITY_RANK = {
+    critical: 4,
+    high: 3,
+    medium: 2,
+    low: 1,
+    unknown: 0,
+};
+/**
+ * THE rule. Twin of the Rust `osv::identity::scope_adjusted_urgency`.
+ *
+ * direct runtime critical -> critical; transitive runtime critical -> high;
+ * direct dev critical -> high; transitive dev critical -> medium;
+ * direct dev high -> medium; transitive dev high -> medium;
+ * transitive runtime high -> high.
+ */
+export function scopeAdjustedSeverity(advisory, scope) {
+    let tier = advisory;
+    if (!scope.isDirect && tier === "critical")
+        tier = "high";
+    if (scope.devScopeKnown && scope.isDev)
+        tier = ONE_LEVEL_DOWN[tier];
+    return tier;
+}
+/**
+ * The grade a surface presents for one scan entry. A missing `isDirect`
+ * (never produced today; defensive for foreign cache rows) is treated as
+ * direct, and a missing `devScopeKnown` as unknown: both mean no discount.
+ */
+export function presentedSeverity(v) {
+    return scopeAdjustedSeverity(v.severity, {
+        isDirect: v.isDirect !== false,
+        isDev: v.isDev === true,
+        devScopeKnown: v.devScopeKnown === true,
+    });
+}
+/**
+ * Why the presented grade differs from the advisory's own tier, in words, or
+ * null when it does not differ.
+ */
+export function scopeAdjustmentReason(v) {
+    if (presentedSeverity(v) === v.severity)
+        return null;
+    const transitive = v.isDirect === false;
+    const dev = v.devScopeKnown === true && v.isDev === true;
+    if (transitive && dev)
+        return "transitive, dev-only dependency";
+    if (dev)
+        return "dev-only dependency";
+    return "transitive-only dependency";
+}
+/** Count entries per tier, using whichever tier function the caller names. */
+export function countBySeverity(entries, tierOf) {
+    const counts = { critical: 0, high: 0, medium: 0, low: 0, unknown: 0 };
+    for (const entry of entries)
+        counts[tierOf(entry)]++;
+    return counts;
+}

package/dist/live/types.d.ts

@@ -1,4 +1,6 @@
 export type OsvEcosystem = "npm" | "crates.io" | "PyPI" | "Go" | "Maven" | "NuGet" | "RubyGems" | "Packagist" | "Pub";
+/** The reinstall command that brings node_modules back in line with a directory's lockfile. */
+export type InstallFixCommand = "pnpm install" | "npm ci" | "yarn install" | "bun install";
 export interface ResolvedDependency {
     name: string;
     version: string | null;
@@ -10,6 +12,56 @@ export interface ResolvedDependency {
     target: string | null;
     /** False when `target` is not active on the host platform (advisory is not relevant). */
     platformActive: boolean;
+    /**
+     * Manifest directories this exact (ecosystem, name, version) resolved from.
+     *
+     * A scan root can span several independent workspaces — `src-tauri/`,
+     * `relay/`, `victauri-gauntlet/` all sit under one repo and pin their own
+     * versions. Without this, dedupe collapsed them and the report named a
+     * vulnerable version with no way to say WHICH workspace pinned it, so a
+     * patched primary crate looked vulnerable because a sibling lagged.
+     */
+    sourceDirs: string[];
+    /**
+     * npm DIRECT deps resolved from a lockfile only: the version node_modules
+     * actually holds (walking up for hoisted workspaces), or null when it is not
+     * installed or unreadable. Undefined when the check did not run (another
+     * ecosystem, no node_modules, or versions read from a manifest).
+     */
+    installedVersion?: string | null;
+    /**
+     * Set on the extra audit entry that asks OSV about an INSTALLED version the
+     * lockfile does not pin: the lockfile's version of the same package. The
+     * entry exists so `vulnerable_installed` is OSV's answer, not a guess.
+     */
+    installDriftOf?: string;
+    /** On drift entries: the command that reinstalls from the lockfile. */
+    installFix?: InstallFixCommand;
+}
+/**
+ * One npm direct dependency whose installed copy differs from its lockfile.
+ * `dir` is the manifest directory, spelled as the resolution group spells it.
+ */
+export interface InstallDriftRecord {
+    package: string;
+    dir: string;
+    lockfileVersion: string;
+    installedVersion: string;
+    fix: InstallFixCommand;
+    isDev: boolean;
+}
+/** A file one resolution group read its versions from. */
+export interface ResolutionSourceRecord {
+    /** Absolute path. */
+    path: string;
+    kind: "lockfile" | "manifest";
+    /** Modification time when it was read, or null if it vanished since. */
+    mtimeMs: number | null;
+}
+/** When the dependency set in use was assembled, and from which files. */
+export interface ResolutionProvenance {
+    resolvedAt: string;
+    sources: ResolutionSourceRecord[];
 }
 /**
  * An OSV record. The `/v1/querybatch` endpoint returns only `{ id, modified }`
@@ -71,6 +123,19 @@ export interface VulnerabilityEntry {
     target: string | null;
     /** False when the affected dep is not active on the host platform. */
     platformActive: boolean;
+    /**
+     * Manifest directories that pin this vulnerable version. Answers the first
+     * question a reader asks — *which project do I go fix?* — which a flat
+     * package-name list cannot.
+     */
+    sourceDirs: string[];
+    /**
+     * Set when this row is about an INSTALLED version the lockfile does not pin
+     * (node_modules drift): the lockfile's version of the same package.
+     */
+    installDriftOf?: string;
+    /** On drift rows: the command that reinstalls from the lockfile. */
+    installFix?: InstallFixCommand;
 }
 export interface VulnerabilityScanResult {
     scannedAt: string;
@@ -126,6 +191,12 @@ export interface RegistryPackageInfo {
     weeklyDownloads: number | null;
     isDev: boolean;
     fetchError: string | null;
+    /**
+     * The version node_modules actually holds, present only when it differs
+     * from `currentVersion` (the lockfile's). Several differing installs across
+     * workspaces are listed comma-separated.
+     */
+    installedVersion?: string;
 }
 export interface SemverDistance {
     major: number;
@@ -140,7 +211,19 @@ export interface DependencyHealthResult {
     totalDeps: number;
     outdatedCount: number;
     deprecatedCount: number;
+    /**
+     * Distinct packages with an advisory that is built on this host and is not a
+     * maintenance notice — the same set `vulnerability_scan` reports as
+     * `total_vulnerable_packages`, so the two tools agree over one scan.
+     */
     vulnerableCount: number;
+    /**
+     * Every advisory row the scan returned, before the platform and maintenance
+     * splits and before alias collapsing. Present so nothing is hidden by the
+     * `vulnerableCount` filter: the difference is platform-inactive packages and
+     * unmaintained-dependency notices.
+     */
+    advisoryCount: number;
     healthScore: number;
     dependencies: RegistryPackageInfo[];
     vulnerabilitySummary: {

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

@@ -0,0 +1,71 @@
+/**
+ * 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 { type FetchFn } from "./package-archive.js";
+import { type ChangelogSection } from "./changelog.js";
+export type UpgradeEcosystem = "npm" | "crates.io";
+/** crates.io refuses API requests without a descriptive User-Agent. */
+export declare const CRATES_USER_AGENT = "4da-mcp-server (https://4da.ai; upgrade_impact)";
+export interface PublishedVersion {
+    version: string;
+    published: string | null;
+    deprecated?: string;
+    yanked?: boolean;
+    /** Archive URL (npm `dist.tarball`); crates archives are derived from name + version. */
+    tarball?: string;
+}
+export interface RegistryIndex {
+    /** The registry's canonical spelling (crates.io folds `-`/`_`). */
+    name: string;
+    ecosystem: UpgradeEcosystem;
+    versions: PublishedVersion[];
+    repository: string | null;
+}
+export interface ChangelogResult {
+    found: boolean;
+    file?: string;
+    sections?: ChangelogSection[];
+    reason?: string;
+}
+/** The cache surface used here; `LiveCache` satisfies it. */
+export interface UpgradeCache {
+    get<T>(key: string): T | null;
+    set(key: string, data: unknown, source: string, ttlSeconds: number): void;
+}
+/** Network + cache seam. `contacted` collects every host actually requested. */
+export interface UpgradeNet {
+    fetch: FetchFn;
+    cache: UpgradeCache | null;
+    contacted: Set<string>;
+}
+export declare function createUpgradeNet(cache: UpgradeCache | null, fetchFn?: FetchFn): UpgradeNet;
+export declare function isValidPackageName(name: string, ecosystem: UpgradeEcosystem): boolean;
+/** Registry index with versions in ascending precedence order (unreadable versions dropped). Null = unknown package. */
+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;
+/** 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. */
+export declare function getOsvAdvisories(net: UpgradeNet, ecosystem: UpgradeEcosystem, name: string, version: string): Promise<string[] | 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 declare function releaseNotesUrl(repository: string | null): string | null;

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 {};