@4da/mcp-server 5.0.4 → 6.0.0

package/dist/tools/knowledge-gap-grading.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Knowledge-gap grading: the pure rules that decide whether an unread item is
+ * evidence about a dependency and how severe the gap is. The database walk
+ * lives in knowledge-gaps.ts; advisory ranges in knowledge-gap-ranges.ts.
+ */
+import type { AdvisoryTier } from "./knowledge-gap-ranges.js";
+export declare function mentionsPackage(text: string, pkg: string): boolean;
+/** A knowledge gap's severity. */
+export type GapSeverity = "critical" | "high" | "medium" | "low";
+/** The subset of an item this grading needs. */
+export interface GradableItem {
+    title: string | null;
+    source_type?: string | null;
+    content_type?: string | null;
+    /**
+     * Set by a caller that has already decided whether this item cites the
+     * dependency: the dependency linker's structured proof says what a title
+     * cannot. Unset, the title decides.
+     */
+    cites?: boolean;
+}
+/** Package-registry sources: every row is a published version of a package. */
+export declare const REGISTRY_SOURCES: Set<string>;
+/** Advisory sources: every row is a security advisory. */
+export declare const ADVISORY_SOURCES: Set<string>;
+/**
+ * A registry advisory row (`knowledge_decay::is_advisory_row`). An editorial
+ * story the pipeline typed `security_advisory` is not one: it cites by title
+ * like any other story and is never proof of exposure (AD-040 rule 4).
+ */
+export declare function isAdvisoryRow(item: GradableItem): boolean;
+/**
+ * The subject package of an advisory title in the ingested "[ID] package:
+ * summary" shape ("[GHSA-h395-gr6q-cpjc] jsonwebtoken: ..."), or null when
+ * the title has another shape and cannot be read that way.
+ */
+export declare function advisorySubject(title: string): string | null;
+/** Same package name, ignoring case and the crates.io `-`/`_` split. */
+export declare function samePackage(a: string, b: string): boolean;
+/** The released version a registry row announces ("npm: react v19.3.0" → "19.3.0"), if any. */
+export declare function registryVersionFromTitle(title: string): string | null;
+/**
+ * Is an install inside a known advisory range?
+ * - exposed: a readable same-ecosystem advisory range contains the version
+ * - safe:    every readable same-ecosystem range excludes it
+ * - unknown: nothing readable stored for its ecosystem, or no readable
+ *            installed version — no claim either way
+ */
+export type Exposure = "exposed" | "safe" | "unknown";
+/** Parse a source_items.published_at value (SQLite "YYYY-MM-DD HH:MM:SS" or ISO). */
+export declare function parsePublishedAt(value: string | null | undefined): number | null;
+/**
+ * Grade a knowledge gap by CONSEQUENCE, never by volume, on the tiers the
+ * desktop app draws (`knowledge_decay::classify_severity`):
+ *
+ * - `critical`: an advisory citing the dependency still reaches an install,
+ *   and the most severe advisory reaching an install is critical or high by
+ *   its OWN grade — CVSS band, else the source's curated label (AD-040 rule 2).
+ * - `high`: the same with a medium, low or ungraded advisory; or a title
+ *   naming the dependency with a breaking change, deprecation or end of life.
+ * - `medium`: a registry release newer than an install, or a title naming the
+ *   dependency with a release, update or upgrade.
+ * - `low`: everything else, including a large pile of passing mentions.
+ *
+ * `critical` used to mean "an advisory names the dependency", whatever the
+ * advisory's own tier: the jsonwebtoken crate's GHSA-h395-gr6q-cpjc, graded
+ * medium by its source and High by the app, was a critical gap here (measured
+ * 2026-09-11). Earlier still, `medium` meant "3+ recent unread mentions"
+ * matched on the content body: a `tracing` gap evidenced by "The Matrix:
+ * Writing Code That Doesn't Need Comments", a `typescript` gap by a
+ * Databricks job posting, fourteen of fifteen gaps noise. Two implementations
+ * of one concept disagreeing is what this mirrors the app to avoid.
+ */
+export declare function gradeGap(items: GradableItem[], packageName: string, 
+/**
+ * An advisory citing this dependency still reaches an install, or cannot be
+ * ruled out. False when every such advisory is fixed at or below the
+ * installed versions: you cannot be "critically behind" on something you
+ * already patched. Defaults to true so callers without version data keep
+ * the conservative grade.
+ */
+stillVulnerable?: boolean, 
+/**
+ * The installed version(s), when known. A registry row is only a version
+ * UPDATE when it is newer than an install (AD-041): the row for the version
+ * every project already runs is not missed intelligence. Unknown keeps the
+ * conservative grade.
+ */
+installedVersion?: string | readonly string[] | null, 
+/** The tier of the most severe stored advisory reaching an install; null when ungraded. */
+advisoryTier?: AdvisoryTier | null): GapSeverity;

package/dist/tools/knowledge-gap-grading.js

@@ -0,0 +1,157 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Knowledge-gap grading: the pure rules that decide whether an unread item is
+ * evidence about a dependency and how severe the gap is. The database walk
+ * lives in knowledge-gaps.ts; advisory ranges in knowledge-gap-ranges.ts.
+ */
+import { comparePrecedence, parseSemverPrecedence } from "../live/semver-precedence.js";
+// Word-boundary matching prevents "cve" matching inside "achieve", "receiver", etc.
+function hasWordBoundary(text, term) {
+    const regex = new RegExp(`\\b${escapeRegExp(term)}\\b`, "i");
+    return regex.test(text);
+}
+// Package names can contain regex metacharacters (@scope/name, c++, next.js).
+function escapeRegExp(s) {
+    return s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+}
+// True when `text` mentions the package name as a whole word. Word characters
+// for this purpose include - and _ (so dep "hono" does NOT match "hono-shim",
+// and never matches "in HONOr of"). @scope/name matches as the full literal.
+export function mentionsPackage(text, pkg) {
+    const regex = new RegExp(`(^|[^A-Za-z0-9_-])${escapeRegExp(pkg)}($|[^A-Za-z0-9_-])`, "i");
+    return regex.test(text);
+}
+/** Package-registry sources: every row is a published version of a package. */
+export const REGISTRY_SOURCES = new Set(["crates_io", "npm_registry", "pypi", "go_modules"]);
+/** Advisory sources: every row is a security advisory. */
+export const ADVISORY_SOURCES = new Set(["osv", "cve"]);
+/**
+ * A registry advisory row (`knowledge_decay::is_advisory_row`). An editorial
+ * story the pipeline typed `security_advisory` is not one: it cites by title
+ * like any other story and is never proof of exposure (AD-040 rule 4).
+ */
+export function isAdvisoryRow(item) {
+    return ADVISORY_SOURCES.has(item.source_type ?? "");
+}
+/**
+ * The subject package of an advisory title in the ingested "[ID] package:
+ * summary" shape ("[GHSA-h395-gr6q-cpjc] jsonwebtoken: ..."), or null when
+ * the title has another shape and cannot be read that way.
+ */
+export function advisorySubject(title) {
+    const match = /^\s*\[[^\]]+\]\s*([^:\s]+)\s*:/.exec(title);
+    return match ? match[1] : null;
+}
+/** Same package name, ignoring case and the crates.io `-`/`_` split. */
+export function samePackage(a, b) {
+    const norm = (s) => s.toLowerCase().replace(/_/g, "-");
+    return norm(a) === norm(b);
+}
+/** The released version a registry row announces ("npm: react v19.3.0" → "19.3.0"), if any. */
+export function registryVersionFromTitle(title) {
+    const versions = title.match(/\bv?\d+\.\d+(?:\.\d+)?(?:[-+][0-9A-Za-z.-]+)?\b/g);
+    if (!versions || versions.length === 0)
+        return null;
+    return versions[versions.length - 1].replace(/^v/, "");
+}
+/** Parse a source_items.published_at value (SQLite "YYYY-MM-DD HH:MM:SS" or ISO). */
+export function parsePublishedAt(value) {
+    if (!value)
+        return null;
+    const iso = value.includes("T") ? value : `${value.replace(" ", "T")}Z`;
+    const ms = Date.parse(iso);
+    return Number.isNaN(ms) ? null : ms;
+}
+/**
+ * Does `item` cite `packageName` by its title alone? An advisory row cites
+ * only its SUBJECT package and never falls back to a word in its title
+ * ("[CVE-2026-63642] MagicMirror newsfeed Socket.IO notification ..." is not
+ * a socket.io advisory); every other row names the package in its title.
+ */
+function citesByTitle(item, packageName) {
+    const title = item.title || "";
+    if (isAdvisoryRow(item)) {
+        const subject = advisorySubject(title);
+        return subject !== null && samePackage(subject, packageName);
+    }
+    return mentionsPackage(title, packageName);
+}
+const RETIREMENT_KEYWORDS = ["breaking", "deprecated", "deprecation", "eol"];
+const CONSEQUENCE_KEYWORDS = ["release", "released", "update", "upgrade"];
+/**
+ * Grade a knowledge gap by CONSEQUENCE, never by volume, on the tiers the
+ * desktop app draws (`knowledge_decay::classify_severity`):
+ *
+ * - `critical`: an advisory citing the dependency still reaches an install,
+ *   and the most severe advisory reaching an install is critical or high by
+ *   its OWN grade — CVSS band, else the source's curated label (AD-040 rule 2).
+ * - `high`: the same with a medium, low or ungraded advisory; or a title
+ *   naming the dependency with a breaking change, deprecation or end of life.
+ * - `medium`: a registry release newer than an install, or a title naming the
+ *   dependency with a release, update or upgrade.
+ * - `low`: everything else, including a large pile of passing mentions.
+ *
+ * `critical` used to mean "an advisory names the dependency", whatever the
+ * advisory's own tier: the jsonwebtoken crate's GHSA-h395-gr6q-cpjc, graded
+ * medium by its source and High by the app, was a critical gap here (measured
+ * 2026-09-11). Earlier still, `medium` meant "3+ recent unread mentions"
+ * matched on the content body: a `tracing` gap evidenced by "The Matrix:
+ * Writing Code That Doesn't Need Comments", a `typescript` gap by a
+ * Databricks job posting, fourteen of fifteen gaps noise. Two implementations
+ * of one concept disagreeing is what this mirrors the app to avoid.
+ */
+export function gradeGap(items, packageName, 
+/**
+ * An advisory citing this dependency still reaches an install, or cannot be
+ * ruled out. False when every such advisory is fixed at or below the
+ * installed versions: you cannot be "critically behind" on something you
+ * already patched. Defaults to true so callers without version data keep
+ * the conservative grade.
+ */
+stillVulnerable = true, 
+/**
+ * The installed version(s), when known. A registry row is only a version
+ * UPDATE when it is newer than an install (AD-041): the row for the version
+ * every project already runs is not missed intelligence. Unknown keeps the
+ * conservative grade.
+ */
+installedVersion = null, 
+/** The tier of the most severe stored advisory reaching an install; null when ungraded. */
+advisoryTier = null) {
+    const cites = (item) => item.cites ?? citesByTitle(item, packageName);
+    // The tiers below the security tier read the TITLE, as the app's do: it
+    // must name the dependency (an advisory's subject counts).
+    const titleNames = (item) => mentionsPackage(item.title || "", packageName) || (isAdvisoryRow(item) && citesByTitle(item, packageName));
+    // "Announcing <thing> <version>" is the canonical release phrasing and names
+    // no other keyword. The version token is REQUIRED, matching the rule
+    // `content_dna_classifiers` settled on: it keeps "Announcing axum 0.8.0" and
+    // rejects "Announcing Toasty, an async ORM" and "Announcing our Series B".
+    const announcesAVersion = (title) => (hasWordBoundary(title, "announcing") || hasWordBoundary(title, "introducing")) && /\bv?\d+\.\d+/.test(title);
+    const retires = (title) => RETIREMENT_KEYWORDS.some((kw) => hasWordBoundary(title, kw)) || /\bend[\s-]of[\s-]life\b/i.test(title);
+    const carriesConsequence = (title) => CONSEQUENCE_KEYWORDS.some((kw) => hasWordBoundary(title, kw)) || announcesAVersion(title);
+    // A registry row IS a version update: "crates.io: serde v1.0.220" names no
+    // consequence keyword, but an unread release of a direct dependency is the
+    // exact thing `knowledge_decay::gap_is_substantive` counts — provided it is
+    // newer than an install (live: "npm: @tauri-apps/api v2.11.1" on 2.11.1).
+    // Compared by semver precedence, so 0.10.0-rc.19 is newer than rc.18.
+    const installed = (typeof installedVersion === "string" ? [installedVersion] : (installedVersion ?? []))
+        .map((v) => parseSemverPrecedence(v))
+        .filter((v) => v !== null);
+    const isNewerRelease = (item) => {
+        if (!REGISTRY_SOURCES.has(item.source_type ?? ""))
+            return false;
+        const released = parseSemverPrecedence(registryVersionFromTitle(item.title || "") ?? "");
+        if (released === null || installed.length === 0)
+            return true;
+        return installed.some((v) => comparePrecedence(released, v) > 0);
+    };
+    if (stillVulnerable && items.some((item) => isAdvisoryRow(item) && cites(item))) {
+        return advisoryTier === "critical" || advisoryTier === "high" ? "critical" : "high";
+    }
+    if (items.some((item) => cites(item) && titleNames(item) && retires(item.title || "")))
+        return "high";
+    if (items.some((item) => cites(item) && (isNewerRelease(item) || (titleNames(item) && carriesConsequence(item.title || ""))))) {
+        return "medium";
+    }
+    return "low";
+}

package/dist/tools/knowledge-gap-installs.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Knowledge-gap installs: the install each declaring project carries, with
+ * its ecosystem (AD-045: a package is (ecosystem, name)). The MCP twin of the
+ * version join in `temporal::get_all_dependencies` (tiers i and ii),
+ * `knowledge_decay::installs_for` and `osv::exposure::canonical`.
+ *
+ * The first cut resolved ONE version per package name (first seen across the
+ * machine) and displayed it beside whichever project row came first, so a gap
+ * could judge one project's install and name another's.
+ */
+import type { FourDADatabase } from "../db.js";
+import type { LiveIntelligence } from "../live/index.js";
+/** A `project_dependencies` row as the gap walk reads it. */
+export interface DeclaringRow {
+    package_name: string;
+    version: string | null;
+    project_path: string;
+    language: string;
+}
+/** One declaring project's install of a dependency. */
+export interface Install {
+    projectPath: string;
+    language: string;
+    /** The OSV ecosystem ("npm", "crates.io", ...); null when the label names none the app knows. */
+    ecosystem: string | null;
+    version: string | null;
+}
+/**
+ * The OSV ecosystem a `project_dependencies.language` or
+ * `user_dependencies.ecosystem` label names, or null when it names none
+ * (`osv::exposure::canonical`). `mapEcosystem` falls back to npm for a label
+ * it does not know; that fallback must not decide which advisories apply.
+ */
+export declare function osvEcosystem(label: string | null | undefined): string | null;
+export declare const sameEcosystem: (a: string, b: string) => boolean;
+/** Does a stored name denote this dependency? crates.io treats `-` and `_` as one namespace. */
+export declare function denotes(storedName: string, ecosystem: string | null, depName: string): boolean;
+/** The other crates.io spelling of a name (`http_body_util` / `http-body-util`). */
+export declare const otherSpelling: (name: string) => string;
+/**
+ * Resolves the install each declaring project carries: the manifest's own
+ * version when it is a real version; else the lockfile-resolved one in
+ * `user_dependencies` (the same project and ecosystem family, then a lockfile
+ * under the same active repo root — a workspace member resolved by the
+ * workspace lockfile); else the live resolver's version for that project.
+ * Never across repo roots or ecosystems: a project is never judged on a
+ * sibling's version.
+ */
+export declare class InstallResolver {
+    private readonly lockStmt;
+    private readonly lockRowsByName;
+    private readonly resolved;
+    private readonly activeRoots;
+    constructor(db: FourDADatabase, liveIntel: Pick<LiveIntelligence, "getResolvedDeps" | "isInitialized"> | null | undefined, activeRoots: readonly string[]);
+    /** One install per declaring project and ecosystem. */
+    installsFor(rows: DeclaringRow[]): Install[];
+    private versionOf;
+    private lockRows;
+    /**
+     * The live resolver's version for THIS project: the resolution whose
+     * manifest directory is the project. Without a lockfile table (standalone
+     * mode, one project) the resolver's version for the package is the install.
+     */
+    private fromResolver;
+}

package/dist/tools/knowledge-gap-installs.js

@@ -0,0 +1,134 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Knowledge-gap installs: the install each declaring project carries, with
+ * its ecosystem (AD-045: a package is (ecosystem, name)). The MCP twin of the
+ * version join in `temporal::get_all_dependencies` (tiers i and ii),
+ * `knowledge_decay::installs_for` and `osv::exposure::canonical`.
+ *
+ * The first cut resolved ONE version per package name (first seen across the
+ * machine) and displayed it beside whichever project row came first, so a gap
+ * could judge one project's install and name another's.
+ */
+import { parseSemverPrecedence } from "../live/semver-precedence.js";
+import { mapEcosystem } from "../live/version-resolver.js";
+import { samePackage } from "./knowledge-gap-grading.js";
+import { allRows, normPath, sharesRoot } from "./knowledge-gap-scope.js";
+const NPM_LABELS = new Set(["npm", "javascript", "typescript", "node", "js", "ts"]);
+/**
+ * The OSV ecosystem a `project_dependencies.language` or
+ * `user_dependencies.ecosystem` label names, or null when it names none
+ * (`osv::exposure::canonical`). `mapEcosystem` falls back to npm for a label
+ * it does not know; that fallback must not decide which advisories apply.
+ */
+export function osvEcosystem(label) {
+    const lower = (label ?? "").trim().toLowerCase();
+    const mapped = mapEcosystem(lower);
+    return mapped === "npm" && !NPM_LABELS.has(lower) ? null : mapped;
+}
+/** The family a lockfile join compares: an unknown label is its own family (`temporal::ecosystem_family`). */
+function ecosystemFamily(label) {
+    return osvEcosystem(label) ?? `other:${(label ?? "").trim().toLowerCase()}`;
+}
+export const sameEcosystem = (a, b) => a.toLowerCase() === b.toLowerCase();
+/** Does a stored name denote this dependency? crates.io treats `-` and `_` as one namespace. */
+export function denotes(storedName, ecosystem, depName) {
+    if (storedName.toLowerCase() === depName.toLowerCase())
+        return true;
+    return ecosystem !== null && sameEcosystem(ecosystem, "crates.io") && samePackage(storedName, depName);
+}
+/** The other crates.io spelling of a name (`http_body_util` / `http-body-util`). */
+export const otherSpelling = (name) => name.includes("_") ? name.replace(/_/g, "-") : name.replace(/-/g, "_");
+/**
+ * Resolves the install each declaring project carries: the manifest's own
+ * version when it is a real version; else the lockfile-resolved one in
+ * `user_dependencies` (the same project and ecosystem family, then a lockfile
+ * under the same active repo root — a workspace member resolved by the
+ * workspace lockfile); else the live resolver's version for that project.
+ * Never across repo roots or ecosystems: a project is never judged on a
+ * sibling's version.
+ */
+export class InstallResolver {
+    lockStmt = null;
+    lockRowsByName = new Map();
+    resolved;
+    activeRoots;
+    constructor(db, liveIntel, activeRoots) {
+        this.activeRoots = activeRoots;
+        this.resolved = liveIntel && liveIntel.isInitialized() ? liveIntel.getResolvedDeps() : [];
+        const has = (column) => db.hasColumn("user_dependencies", column);
+        if (!["project_path", "package_name", "version", "ecosystem"].every(has))
+            return;
+        const order = [has("is_direct") ? "is_direct DESC" : "", has("last_seen_at") ? "last_seen_at DESC" : ""]
+            .filter(Boolean)
+            .join(", ");
+        try {
+            this.lockStmt = db.getRawDb().prepare(`SELECT project_path, package_name, version, ecosystem FROM user_dependencies
+         WHERE lower(package_name) IN (lower(?), lower(?)) AND version IS NOT NULL AND version != ''
+         ${order ? `ORDER BY ${order}` : ""}`);
+        }
+        catch {
+            // No readable lockfile table: fall through to the resolver.
+        }
+    }
+    /** One install per declaring project and ecosystem. */
+    installsFor(rows) {
+        const seen = new Set();
+        const installs = [];
+        for (const row of rows) {
+            const key = `${normPath(row.project_path)}\0${ecosystemFamily(row.language)}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            installs.push({
+                projectPath: row.project_path,
+                language: row.language,
+                ecosystem: osvEcosystem(row.language),
+                version: this.versionOf(row),
+            });
+        }
+        return installs;
+    }
+    versionOf(row) {
+        // A manifest records a RANGE when it records anything ("^4.1.5"); only a
+        // real version is an install.
+        if (row.version && parseSemverPrecedence(row.version) !== null)
+            return row.version;
+        const family = ecosystemFamily(row.language);
+        const locked = this.lockRows(row.package_name).filter((l) => ecosystemFamily(l.ecosystem) === family && denotes(l.package_name, family, row.package_name));
+        const here = normPath(row.project_path);
+        const own = locked.find((l) => normPath(l.project_path) === here);
+        if (own)
+            return own.version;
+        const workspace = locked.find((l) => sharesRoot(row.project_path, l.project_path, this.activeRoots));
+        if (workspace)
+            return workspace.version;
+        return this.fromResolver(row);
+    }
+    lockRows(name) {
+        if (!this.lockStmt)
+            return [];
+        const key = name.toLowerCase();
+        let rows = this.lockRowsByName.get(key);
+        if (!rows) {
+            rows = allRows(this.lockStmt, name, otherSpelling(name));
+            this.lockRowsByName.set(key, rows);
+        }
+        return rows;
+    }
+    /**
+     * The live resolver's version for THIS project: the resolution whose
+     * manifest directory is the project. Without a lockfile table (standalone
+     * mode, one project) the resolver's version for the package is the install.
+     */
+    fromResolver(row) {
+        const ecosystem = osvEcosystem(row.language);
+        if (ecosystem === null)
+            return null;
+        const matches = this.resolved.filter((d) => d.version && sameEcosystem(d.ecosystem, ecosystem) && denotes(d.name, ecosystem, row.package_name));
+        const here = normPath(row.project_path);
+        const own = matches.find((d) => (d.sourceDirs ?? []).some((dir) => normPath(dir) === here));
+        if (own)
+            return own.version;
+        return this.lockStmt === null ? (matches[0]?.version ?? null) : null;
+    }
+}

package/dist/tools/knowledge-gap-ranges.d.ts

@@ -0,0 +1,51 @@
+/**
+ * OSV affected-range evaluation for knowledge gaps: the TypeScript twin of
+ * `src-tauri/src/osv/matching.rs::check_version_affected`, so the desktop app
+ * and this server answer "is this install inside that advisory?" the same way.
+ *
+ * The first version here understood only `introduced`/`fixed`. GHSA-9crc-q9x8-hgqq
+ * stores vitest's pre-1.0 window as `[{"introduced":"0"},{"last_affected":"0.0.125"}]`;
+ * the loop never saw a `fixed`, read the trailing `introduced: "0"` as
+ * "affected from 0 onward", and put EVERY vitest version inside a CVSS 9.6
+ * advisory (measured 2026-09-11 against vitest 4.1.11, whose one real exposure
+ * is fixed at exactly 4.1.11).
+ */
+/** One event of an OSV affected range; OSV sets exactly one key per event. */
+export interface AdvisoryRangeEvent {
+    introduced?: string;
+    fixed?: string;
+    last_affected?: string;
+    limit?: string;
+}
+/** An advisory's own severity tier. */
+export type AdvisoryTier = "critical" | "high" | "medium" | "low";
+/**
+ * The SEMVER/ECOSYSTEM ranges of a stored `osv_advisories.affected_ranges`
+ * value as event lists, or null when the value is missing or unreadable.
+ * `[]` is readable and contains nothing. GIT ranges carry commit hashes and
+ * are skipped, as the Rust reference skips them; a range with no `type` is
+ * read as SEMVER.
+ */
+export declare function parseAffectedRanges(json: string | null | undefined): AdvisoryRangeEvent[][] | null;
+/** Is `installed` inside any of `ranges`? Null when the installed version is unreadable. */
+export declare function rangesContain(ranges: AdvisoryRangeEvent[][], installed: string): boolean | null;
+/**
+ * Is `installed` inside any of these advisory ranges?
+ *
+ * An advisory naming your dependency is only a gap if you are actually
+ * exposed: the live tool once graded three Hono CVEs `critical` on hono
+ * 4.13.2 when all three are fixed in 4.12.34, a version this repo had already
+ * pinned past via `pnpm.overrides`.
+ *
+ * Conservative by construction: a missing or unreadable installed version
+ * counts as AFFECTED. Never claim someone is safe on missing information.
+ */
+export declare function versionInAnyRange(ranges: AdvisoryRangeEvent[][], installed: string | null | undefined): boolean;
+/**
+ * An advisory's tier: its CVSS band first (>= 9 critical, >= 7 high, >= 4
+ * medium, else low: `osv::types::cvss_band`), else the source's curated label,
+ * else null (ungraded). Mirrors `knowledge_decay::advisory_tier_for`.
+ */
+export declare function advisoryTier(cvssScore: number | null | undefined, label: string | null | undefined): AdvisoryTier | null;
+/** The more severe of two tiers; null (ungraded) ranks below every tier. */
+export declare function moreSevereTier(a: AdvisoryTier | null, b: AdvisoryTier | null): AdvisoryTier | null;

package/dist/tools/knowledge-gap-ranges.js

@@ -0,0 +1,146 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * OSV affected-range evaluation for knowledge gaps: the TypeScript twin of
+ * `src-tauri/src/osv/matching.rs::check_version_affected`, so the desktop app
+ * and this server answer "is this install inside that advisory?" the same way.
+ *
+ * The first version here understood only `introduced`/`fixed`. GHSA-9crc-q9x8-hgqq
+ * stores vitest's pre-1.0 window as `[{"introduced":"0"},{"last_affected":"0.0.125"}]`;
+ * the loop never saw a `fixed`, read the trailing `introduced: "0"` as
+ * "affected from 0 onward", and put EVERY vitest version inside a CVSS 9.6
+ * advisory (measured 2026-09-11 against vitest 4.1.11, whose one real exposure
+ * is fixed at exactly 4.1.11).
+ */
+import { comparePrecedence, parseSemverPrecedence } from "../live/semver-precedence.js";
+/**
+ * The SEMVER/ECOSYSTEM ranges of a stored `osv_advisories.affected_ranges`
+ * value as event lists, or null when the value is missing or unreadable.
+ * `[]` is readable and contains nothing. GIT ranges carry commit hashes and
+ * are skipped, as the Rust reference skips them; a range with no `type` is
+ * read as SEMVER.
+ */
+export function parseAffectedRanges(json) {
+    if (typeof json !== "string" || json.trim() === "")
+        return null;
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!Array.isArray(parsed))
+        return null;
+    const ranges = [];
+    for (const range of parsed) {
+        if (typeof range !== "object" || range === null)
+            continue;
+        const { type, events } = range;
+        if (typeof type === "string" && type !== "SEMVER" && type !== "ECOSYSTEM")
+            continue;
+        if (!Array.isArray(events))
+            continue;
+        ranges.push(events.filter((e) => typeof e === "object" && e !== null));
+    }
+    return ranges;
+}
+/**
+ * OSV's marker for a boundary nobody knows ("2.5.0-NA", from PYSEC imports).
+ * `matching.rs::is_unknown_bound`: such a bound grounds no match.
+ */
+function isUnknownBound(v) {
+    const t = v.trim();
+    return t.endsWith("-NA") || t.endsWith("-na");
+}
+function closingEvent(event) {
+    const read = (v) => (isUnknownBound(v) ? null : parseSemverPrecedence(v));
+    if (typeof event.fixed === "string")
+        return { bound: read(event.fixed), inclusive: false };
+    if (typeof event.last_affected === "string")
+        return { bound: read(event.last_affected), inclusive: true };
+    if (typeof event.limit === "string") {
+        return { bound: event.limit.trim() === "*" ? "unbounded" : read(event.limit), inclusive: false };
+    }
+    return null;
+}
+/**
+ * Is `version` inside this one range? Events pair up in order: `introduced`
+ * opens, `fixed` and `limit` close exclusively, `last_affected` closes
+ * inclusively, and one range may hold several pairs. A closing event always
+ * ends the pair it closes, even when its bound is unknown or unreadable: such
+ * a bound matches nothing and leaves no open range behind. Only an
+ * `introduced` that nothing closed means "affected from there on".
+ */
+function eventsContain(events, version) {
+    const atOrAbove = (lower) => lower === "zero" || comparePrecedence(version, lower) >= 0;
+    let lower = null;
+    for (const event of events) {
+        if (typeof event.introduced === "string") {
+            lower = event.introduced.trim() === "0" ? "zero" : parseSemverPrecedence(event.introduced);
+        }
+        const upper = closingEvent(event);
+        if (upper === null)
+            continue;
+        if (lower !== null && upper.bound !== null && atOrAbove(lower)) {
+            if (upper.bound === "unbounded")
+                return true;
+            const cmp = comparePrecedence(version, upper.bound);
+            if (upper.inclusive ? cmp <= 0 : cmp < 0)
+                return true;
+        }
+        lower = null;
+    }
+    return lower !== null && atOrAbove(lower);
+}
+/** Is `installed` inside any of `ranges`? Null when the installed version is unreadable. */
+export function rangesContain(ranges, installed) {
+    const version = parseSemverPrecedence(installed);
+    if (version === null)
+        return null;
+    return ranges.some((events) => eventsContain(events, version));
+}
+/**
+ * Is `installed` inside any of these advisory ranges?
+ *
+ * An advisory naming your dependency is only a gap if you are actually
+ * exposed: the live tool once graded three Hono CVEs `critical` on hono
+ * 4.13.2 when all three are fixed in 4.12.34, a version this repo had already
+ * pinned past via `pnpm.overrides`.
+ *
+ * Conservative by construction: a missing or unreadable installed version
+ * counts as AFFECTED. Never claim someone is safe on missing information.
+ */
+export function versionInAnyRange(ranges, installed) {
+    if (!installed)
+        return true;
+    return rangesContain(ranges, installed) ?? true;
+}
+const TIERS = new Set(["critical", "high", "medium", "low"]);
+const isTier = (s) => TIERS.has(s);
+/**
+ * An advisory's tier: its CVSS band first (>= 9 critical, >= 7 high, >= 4
+ * medium, else low: `osv::types::cvss_band`), else the source's curated label,
+ * else null (ungraded). Mirrors `knowledge_decay::advisory_tier_for`.
+ */
+export function advisoryTier(cvssScore, label) {
+    if (typeof cvssScore === "number" && Number.isFinite(cvssScore)) {
+        if (cvssScore >= 9)
+            return "critical";
+        if (cvssScore >= 7)
+            return "high";
+        if (cvssScore >= 4)
+            return "medium";
+        return "low";
+    }
+    const l = typeof label === "string" ? label.trim().toLowerCase() : "";
+    return isTier(l) ? l : null;
+}
+const TIER_RANK = { critical: 4, high: 3, medium: 2, low: 1 };
+/** The more severe of two tiers; null (ungraded) ranks below every tier. */
+export function moreSevereTier(a, b) {
+    if (a === null)
+        return b;
+    if (b === null)
+        return a;
+    return TIER_RANK[b] > TIER_RANK[a] ? b : a;
+}