@4da/mcp-server 6.0.2 → 6.2.0

package/dist/index.js

@@ -51,7 +51,8 @@ import { validateToolArgs } from "./tool-args.js";
 // Tool registry: listing, schema resources, category metadata
 import { getCategoryManifest, getSchemaResources, getSlimToolList, getToolSchemaDocument, hasToolSchema, TOOL_REGISTRY, } from "./schema-registry.js";
 // Map-based tool dispatch (replaces per-tool imports + switch statement)
-import { dispatchTool } from "./tool-dispatch.js";
+import { DATABASE_FREE_TOOLS, dispatchTool } from "./tool-dispatch.js";
+import { SqliteUnavailableError, sqliteDriverStatus } from "./sqlite-driver.js";
 import { getPrompt, listPrompts } from "./prompts.js";
 import { checkBuildStaleness } from "./build-staleness.js";
 const __filename = fileURLToPath(import.meta.url);
@@ -107,7 +108,7 @@ function getDatabase() {
             const cwd = resolveProjectDir();
             // The root and every independently-locked project below it
             // (project-tree.ts): a repo root's own lockfile is often not the only one.
-            const tree = scanProjectTree(cwd);
+            const { entries: tree, discovery } = scanProjectTree(cwd);
             const scan = tree[0].scan;
             db.populateFromScan(scan);
             const groups = treeResolutionGroups(tree);
@@ -121,7 +122,7 @@ function getDatabase() {
                 // Initialize live intelligence with per-ecosystem resolved versions
                 // (targets carry platform-gated dep info so advisories can be flagged
                 // platform-relevant for the host).
-                liveIntel.initFromProjectTree(cwd, groups);
+                liveIntel.initFromProjectTree(cwd, groups, discovery);
                 if (liveIntel.isEnabled()) {
                     console.error(`[4DA]   Live intelligence: enabled (OSV.dev)`);
                     // The vulnerability scan goes through the warmup so a briefing that
@@ -206,6 +207,39 @@ function getDatabase() {
     }
     return db;
 }
+/**
+ * No SQLite driver is usable (Node < 22.13 and better-sqlite3's native module
+ * unbuilt): the live layer alone, from a project scan and an in-memory cache,
+ * so the dependency tools (DATABASE_FREE_TOOLS) still answer. Every other
+ * tool returns the driver error, which says how to fix it.
+ */
+function initWithoutDatabase() {
+    if (liveIntel)
+        return;
+    liveIntel = new LiveIntelligence(null);
+    setLiveIntelligence(liveIntel);
+    const cwd = resolveProjectDir();
+    const { entries, discovery } = scanProjectTree(cwd);
+    const groups = treeResolutionGroups(entries);
+    console.error(`[4DA] No SQLite driver: the dependency tools run without a database (${cwd}).`);
+    if (groups.length === 0)
+        return;
+    liveIntel.initFromProjectTree(cwd, groups, discovery);
+    if (liveIntel.isEnabled())
+        liveIntel.startVulnerabilityWarmup(cwd);
+}
+/** The database for a tool call; null only for a database-free tool when no SQLite driver is usable. */
+function databaseFor(tool) {
+    try {
+        return getDatabase();
+    }
+    catch (error) {
+        if (!(error instanceof SqliteUnavailableError) || !DATABASE_FREE_TOOLS.has(tool))
+            throw error;
+        initWithoutDatabase();
+        return null;
+    }
+}
 /** Standalone vs desktop-app database, decided once by the cheap probe (no scan, no resolution). */
 let standaloneMode = null;
 function isStandaloneMode() {
@@ -372,7 +406,7 @@ export function buildServer() {
             }
         }
         try {
-            const database = getDatabase();
+            const database = databaseFor(name);
             return await dispatchTool(name, database, args);
         }
         catch (error) {
@@ -517,6 +551,11 @@ async function main() {
     // -------------------------------------------------------------------------
     const dbPath = process.env.FOURDA_DB_PATH || undefined;
     const validation = FourDADatabase.validateDatabase(dbPath);
+    const sqlite = sqliteDriverStatus();
+    if (!sqlite.driver) {
+        console.error(`[4DA] ${sqlite.problem}`);
+        console.error(`  Dependency tools (${[...DATABASE_FREE_TOOLS].join(", ")}) still run, without a database.`);
+    }
     if (validation.valid) {
         console.error(`[4DA] Database validated — ${validation.tables?.length ?? 0} tables found`);
     }

package/dist/live/cache.d.ts

@@ -1,7 +1,29 @@
-import type Database from "better-sqlite3";
+import { type SqliteDatabase } from "../sqlite-driver.js";
+/**
+ * The server's own cache file (serverCacheDbPath(), `cache.db`), opened once
+ * per process. Falls back to an in-memory database when the file cannot be
+ * created (a read-only home directory): the server then runs uncached on disk
+ * rather than failing. Null when no SQLite driver is usable at all
+ * (sqlite-driver.ts); LiveCache then keeps entries in a Map for the session.
+ */
+export declare function getServerCacheDb(): SqliteDatabase | null;
+/** Close the shared cache connection (tests; the next getServerCacheDb() reopens it). */
+export declare function closeServerCacheDb(): void;
+/**
+ * Registry, OSV and changelog responses with a TTL.
+ *
+ * The cache never lives in the desktop app's database. A read-only connection
+ * (the app's `4da.db`, see FourDADatabase) is replaced by the server's own
+ * cache file; until 6.0.2 the server created a `live_cache` table inside the
+ * app's database and filled it.
+ */
 export declare class LiveCache {
     private db;
-    constructor(db: Database.Database);
+    /** Without any SQLite driver: entries for this session only, keyed like the table. */
+    private memory;
+    constructor(db: SqliteDatabase | null);
+    /** The Map store's equivalent of datetime('now') comparisons. */
+    private live;
     private ensureTable;
     get<T>(key: string): T | null;
     getStale<T>(key: string): {
@@ -9,6 +31,13 @@ export declare class LiveCache {
         fetchedAt: string;
     } | null;
     set(key: string, data: unknown, source: string, ttlSeconds: number): void;
+    /**
+     * Many entries in ONE transaction. A scan caches one row per dependency;
+     * as separate autocommits each paid its own WAL commit, and superset's
+     * 4,516 rows took about 40 s of a 55 s cold scan whose network part ended
+     * at 12 s (2026-10-10).
+     */
+    setMany(entries: Array<[key: string, data: unknown]>, source: string, ttlSeconds: number): void;
     purgeExpired(): number;
     invalidateSource(source: string): void;
     invalidateAll(): void;

package/dist/live/cache.js

@@ -1,12 +1,70 @@
 // SPDX-License-Identifier: Apache-2.0
+import fs from "node:fs";
+import path from "node:path";
+import { openDatabase, sqliteDriverStatus } from "../sqlite-driver.js";
+import { serverCacheDbPath } from "../db.js";
+let serverCache = null;
+/**
+ * The server's own cache file (serverCacheDbPath(), `cache.db`), opened once
+ * per process. Falls back to an in-memory database when the file cannot be
+ * created (a read-only home directory): the server then runs uncached on disk
+ * rather than failing. Null when no SQLite driver is usable at all
+ * (sqlite-driver.ts); LiveCache then keeps entries in a Map for the session.
+ */
+export function getServerCacheDb() {
+    if (serverCache?.open)
+        return serverCache;
+    if (!sqliteDriverStatus().driver)
+        return null;
+    const file = serverCacheDbPath();
+    try {
+        fs.mkdirSync(path.dirname(file), { recursive: true });
+        serverCache = openDatabase(file);
+        serverCache.pragma("journal_mode = WAL");
+        // A cache, not a record: in WAL mode NORMAL never corrupts the file, and
+        // a crash can only lose the last few writes, which are refetched.
+        serverCache.pragma("synchronous = NORMAL");
+    }
+    catch (error) {
+        console.error(`[4da] cannot open the cache at ${file} (${error instanceof Error ? error.message : String(error)}); caching in memory for this session`);
+        serverCache = openDatabase(":memory:");
+    }
+    return serverCache;
+}
+/** Close the shared cache connection (tests; the next getServerCacheDb() reopens it). */
+export function closeServerCacheDb() {
+    if (serverCache?.open)
+        serverCache.close();
+    serverCache = null;
+}
+/**
+ * Registry, OSV and changelog responses with a TTL.
+ *
+ * The cache never lives in the desktop app's database. A read-only connection
+ * (the app's `4da.db`, see FourDADatabase) is replaced by the server's own
+ * cache file; until 6.0.2 the server created a `live_cache` table inside the
+ * app's database and filled it.
+ */
 export class LiveCache {
     db;
+    /** Without any SQLite driver: entries for this session only, keyed like the table. */
+    memory = null;
     constructor(db) {
-        this.db = db;
+        this.db = !db || db.readonly ? getServerCacheDb() : db;
+        if (!this.db) {
+            this.memory = new Map();
+            return;
+        }
         this.ensureTable();
         this.purgeExpired();
     }
+    /** The Map store's equivalent of datetime('now') comparisons. */
+    live(row) {
+        return Date.parse(row.expires_at) > Date.now();
+    }
     ensureTable() {
+        if (!this.db)
+            return;
         this.db.exec(`
       CREATE TABLE IF NOT EXISTS live_cache (
         cache_key TEXT PRIMARY KEY,
@@ -20,6 +78,10 @@ export class LiveCache {
     `);
     }
     get(key) {
+        if (this.memory) {
+            const hit = this.memory.get(key);
+            return hit && this.live(hit) ? JSON.parse(hit.data) : null;
+        }
         const row = this.db.prepare("SELECT data FROM live_cache WHERE cache_key = ? AND expires_at > datetime('now')").get(key);
         if (!row)
             return null;
@@ -31,6 +93,10 @@ export class LiveCache {
         }
     }
     getStale(key) {
+        if (this.memory) {
+            const hit = this.memory.get(key);
+            return hit ? { data: JSON.parse(hit.data), fetchedAt: hit.fetched_at } : null;
+        }
         const row = this.db.prepare("SELECT data, fetched_at FROM live_cache WHERE cache_key = ?").get(key);
         if (!row)
             return null;
@@ -42,19 +108,65 @@ export class LiveCache {
         }
     }
     set(key, data, source, ttlSeconds) {
+        if (this.memory) {
+            const now = Date.now();
+            const iso = (ms) => new Date(ms).toISOString();
+            this.memory.set(key, { cache_key: key, data: JSON.stringify(data), source, fetched_at: iso(now), expires_at: iso(now + ttlSeconds * 1000) });
+            return;
+        }
         this.db.prepare(`
       INSERT OR REPLACE INTO live_cache (cache_key, data, source, fetched_at, expires_at)
       VALUES (?, ?, ?, datetime('now'), datetime('now', '+' || ? || ' seconds'))
     `).run(key, JSON.stringify(data), source, ttlSeconds);
     }
+    /**
+     * Many entries in ONE transaction. A scan caches one row per dependency;
+     * as separate autocommits each paid its own WAL commit, and superset's
+     * 4,516 rows took about 40 s of a 55 s cold scan whose network part ended
+     * at 12 s (2026-10-10).
+     */
+    setMany(entries, source, ttlSeconds) {
+        if (entries.length === 0)
+            return;
+        if (this.memory) {
+            for (const [key, data] of entries)
+                this.set(key, data, source, ttlSeconds);
+            return;
+        }
+        const insert = this.db.prepare(`
+      INSERT OR REPLACE INTO live_cache (cache_key, data, source, fetched_at, expires_at)
+      VALUES (?, ?, ?, datetime('now'), datetime('now', '+' || ? || ' seconds'))
+    `);
+        this.db.transaction(() => {
+            for (const [key, data] of entries)
+                insert.run(key, JSON.stringify(data), source, ttlSeconds);
+        })();
+    }
     purgeExpired() {
+        if (this.memory) {
+            let purged = 0;
+            for (const [key, row] of this.memory)
+                if (!this.live(row) && this.memory.delete(key))
+                    purged++;
+            return purged;
+        }
         const result = this.db.prepare("DELETE FROM live_cache WHERE expires_at <= datetime('now')").run();
         return result.changes;
     }
     invalidateSource(source) {
+        if (this.memory) {
+            for (const [key, row] of this.memory)
+                if (row.source === source)
+                    this.memory.delete(key);
+            return;
+        }
         this.db.prepare("DELETE FROM live_cache WHERE source = ?").run(source);
     }
     invalidateAll() {
+        if (this.memory) {
+            this.memory.clear();
+            return;
+        }
         this.db.prepare("DELETE FROM live_cache").run();
     }
 }

package/dist/live/changelog-classify.d.ts

@@ -20,8 +20,14 @@ export type EntryKind = "breaking" | "deprecation" | "security" | "change";
 export declare const MAX_ENTRY_CHARS = 400;
 /** Strip control and invisible/bidi characters, collapse whitespace, cap length. */
 export declare function sanitizeEntry(text: string, cap?: number): string;
+/**
+ * The text classified: RST ``literals`` read as `literals`, link targets and
+ * bare URLs dropped (a `go.dev/doc/go1.21` link made "Drop support for Go 1.21"
+ * read as a docs change), GitHub's "by @user in <PR url>" suffix dropped.
+ */
+export declare function classificationText(text: string): string;
 /** Kind of a single changelog line by its own wording. */
-export declare function classifyText(text: string): EntryKind;
+export declare function classifyText(raw: string): EntryKind;
 /**
  * What a sub-heading (or a label-only bullet such as express's "* remove:")
  * says about the entries under it:
@@ -34,8 +40,8 @@ export declare function classifyText(text: string): EntryKind;
  *   where only an explicit marker makes an entry breaking ("Added a clear()
  *   function ... removed from an axios instance" is not a removal).
  */
-export type EntryContext = EntryKind | "removal" | "additive";
+export type EntryContext = EntryKind | "removal" | "additive" | "fixes";
 /** Context implied by a heading or label, or null when it carries no signal ("### Changed"). */
 export declare function classifyHeading(heading: string): EntryContext | null;
 /** Final kind: an explicit heading or bullet parent wins; removal and additive contexts refine the line's wording. */
-export declare function classifyEntry(text: string, context: EntryContext | null): EntryKind;
+export declare function classifyEntry(raw: string, context: EntryContext | null): EntryKind;

package/dist/live/changelog-classify.js

@@ -35,7 +35,8 @@ export function sanitizeEntry(text, cap = MAX_ENTRY_CHARS) {
 // `BREAKING` but not the file name `BREAKING-CHANGES.md` (ratatui links it from routine entries);
 // a leading "Breaking -" / "[Breaking]" label too (webpack-merge 5, handlebars-rust).
 // Case-sensitive on purpose: lowercase "breaking" is prose, handled (with negation) below.
-const EXPLICIT_BREAKING_MARKER = /\bBREAKING\b(?![-_.]\w)|⚠|^\s*\*{0,2}\w+(?:\([^)]*\))?!:|^\s*\*{0,2}[Bb]reaking\*{0,2}\s*(?::|[-–—]\s)|^\s*\[(?:[Bb]reaking|[Rr]emoved)\]/;
+// "*Backwards-incompatible*:" (marshmallow 4) is the same call in other words.
+const EXPLICIT_BREAKING_MARKER = /\bBREAKING\b(?![-_.]\w)|⚠|^\s*\*{0,2}\w+(?:\([^)]*\))?!:|^\s*\*{0,2}[Bb]reaking\*{0,2}\s*(?::|[-–—]\s)|^\s*\[(?:[Bb]reaking|[Rr]emoved)\]|\b[Bb]ackwards?[- ][Ii]ncompatible\b/;
 /**
  * Text ABOUT breaking changes rather than one: a pointer to the list ("⚠️ List
  * of breaking changes can be found here"), a CI label check, a docs fix
@@ -126,7 +127,81 @@ const BREAKING_HEURISTIC = new RegExp([
     "\\bincompatib",
 ].join("|"), "i");
 /** Removals that change nothing a caller sees: "Removed unused imports", "Removed Webpack". */
-const INTERNAL_CHANGE = /\b(?:unused|unneeded|unnecessary|internal(?:ly)?|dead code|tests?|ci|lint(?:ing)?|typos?|comments?|docs?|documentation|readme|redundant|duplicated?|webpack|dev-?dependenc(?:y|ies)|dependency|warnings?|examples?|benchmarks?|release process|build process|tooling|usage|incorrect|wrong|erroneous|stray|spurious)\b/i;
+const INTERNAL_CHANGE = /\b(?:unused|unneeded|unnecessary|internal(?:ly)?|dead code|tests?|ci|lint(?:ing)?|typos?|comments?|docs?|documentation|readme|redundant|duplicated?|webpack|dev-?dependenc(?:y|ies)|dependency|warnings?|examples?|benchmarks?|release process|build process|tooling|usage|incorrect|wrong|erroneous|stray|spurious|private|maintainers?|contributors?|invalid|broken|bogus|[\w-]+\.(?:md|json|ya?ml|toml|lock|txt|cfg)(?![\w(]))\b/i;
+/**
+ * The removed thing is private by its name (`_prepare_conn`, a leading
+ * underscore): urllib3 2.0 lists such removals under "Removed".
+ */
+const PRIVATE_NAME = /^\W*(?:remove[sd]?|delete[sd]?|drop(?:s|ped)?)\b[^`]{0,40}`_[A-Za-z]/i;
+const isInternal = (t) => INTERNAL_CHANGE.test(t) || PRIVATE_NAME.test(t);
+/** Public API made private ("Assorted array helper methods and types made private"): a removal, though it says "private". */
+const MADE_PRIVATE = /\b(?:made|make|makes|is now|are now)\b[^.]{0,60}\bprivate\b/i;
+/**
+ * The entry says it changes nothing for users: "passing string or boolean still
+ * works as before", "This change should have no effect on users".
+ */
+const STATED_COMPATIBLE = /\b(?:still works?|still work as before|continues? to work|(?:is|are) still supported|remains? supported|(?:should|will|has|have) (?:have )?no (?:effect|impact) on (?:users|you|most users|existing code)|no user-facing)\b|(?<!\bnot |\bnon-?)\bbackwards?[- ]compatib(?:le|ility)\b/i;
+/**
+ * Not an API change although worded like one: undoing a removal or deprecation
+ * ("removes the deprecation notice from", "restore the `X()` function"), a
+ * relaxation ("remove Send bounds for request `Body`"), a repository rename, a
+ * swapped dependency ("Move from `winapi` to `windows` crate").
+ */
+const UNDO = /\bremov\w*\s+(?:the\s+)?(?:[\w`]+\s+)?(?:bounds?|restrictions?|limitations?|limits?|requirements?|constraints?|need for)\b|\brenam\w*\s+(?:the\s+)?(?:github\s+)?repo(?:sitory)?\b|\bmov(?:e|ed|es)\s+from\s+\x60[^\x60]+\x60\s+to\s+\x60[^\x60]+\x60\s+(?:crate|package|library)\b|\bremov\w*\s+(?:the\s+)?deprecation\s+(?:notices?|warnings?|messages?)\b|\bun-?deprecat|\b(?:restore[sd]?|restoring|re-?add(?:ed|s)?|reintroduc\w*)\b/i;
+/** A change confined to examples, docs, tests or CI: "Drop support for Go 1.21 in dice example". */
+const SCOPED_NON_API = /\bin (?:the )?(?:[\w-]+ )?(?:examples?|docs?|documentation|tests?|ci|workflows?|benchmarks?|readme)\b/i;
+const LEAD = String.raw `^\W*(?:\*\*[^*]{1,40}\*\*:?\s*)?`;
+/**
+ * Runtime and language support: dropped versions and raised minimums ("drop
+ * node 10.x", "Drop support for Go 1.21", "only support node 16-20", "Replace
+ * go 1.21 with go 1.22 in go mod", "increase MSRV to 1.63"). Breaking whatever
+ * the reason the entry gives ("drop node 10.x to upgrade dev dependencies").
+ */
+const RUNTIME_SUPPORT = new RegExp([
+    String.raw `\b(?:drop(?:s|ped|ping)?|remove[sd]?|removing|end(?:s|ed)?)\s+(?:official\s+)?(?:support\s+(?:for\s+)?)?(?:node(?:\.?js)?|python|py|go|golang|ruby|php|java|jdk|rust|rustc)\s*v?\d`,
+    String.raw `\b(?:only supports?|now requires?|requires? at least|minimum (?:supported )?(?:version of )?)\s*(?:node(?:\.?js)?|python|go|golang|rust|ruby|php|java)\s*v?\d`,
+    String.raw `\bonly supports? (?:node(?:\.?js)?|python|go|golang)\b`,
+    String.raw `\bgo\s*1\.\d+[^.]{0,30}\bgo\.?\s?mod\b`,
+    String.raw `\b(?:bump|bumped|raise|raised|increase|increased|update|updated|require|requires|now)\b.{0,60}\b(?:MSRV|minimum supported rust version|rust-version)\b.{0,30}\d+\.\d+`,
+].join("|"), "i");
+/**
+ * Wording that changes the API whatever heading it sits under (rule set added
+ * 2026-10-11 from the G3 panel's dev pairs): a leading removal or rename of
+ * something API-shaped, a changed default, a type made private, a move, a
+ * replacement, keyword-only arguments, "now ... instead of".
+ */
+const API_CHANGE = new RegExp([
+    // "remove UMD build", "remove `ReasonPhrase::from_bytes_unchecked()` method", "Remove previously deprecated code".
+    // The removed thing is named within the next few words, as in REMOVAL_HEURISTIC: "Remove a window when ...
+    // `cd`able by non-owners" (a security fix) has its backtick far later.
+    String.raw `${LEAD}(?:remove[sd]?|delete[sd]?|drop(?:s|ped)?)\b(?=(?:\s+[\w.:/-]+){0,4}\s*\(?\x60|(?:\s+[\w.:/-]+){0,5}?\s+(?:support|builds?|param(?:eter)?s?|options?|methods?|functions?|modules?|class(?:es)?|types?|exports?|features?|flags?|apis?|prefix(?:es)?|constructors?|requires|imports|entry ?points?|fields?|propert(?:y|ies)|arguments?|attributes?|traits?|structs?|enums?|macros?|commands?|settings?|config|keys?|aliases?|fallback|deprecated|code)\b)`,
+    String.raw `${LEAD}renamed?\b`,
+    String.raw `\x60[^\x60]+\x60\s+(?:is |was |has been )?renamed\b|\bchanged? (?:the )?name of\b`,
+    // Defaults: "Changed the default `blocksize` to 16KB", "now defaults `extended` to `false`", "default `header_read_timeout` to 30 seconds".
+    String.raw `${LEAD}(?:change[sd]?|set|make|made)\b[^.]{0,60}\bdefaults?\b[^.]{0,60}\bto\b`,
+    String.raw `${LEAD}default\s[^.]{0,60}\bto\b`,
+    String.raw `\bnow defaults?\b[^.]{0,40}\bto\b|\bdefaults? (?:value |values )?(?:is|are) now\b`,
+    String.raw `\b(?:keyword|positional)[- ]only\b`,
+    String.raw `\x60[^\x60]+\x60\s+(?:has been |have been |was |were |is |are )?moved (?:to|into|out of)\b`,
+    String.raw `${LEAD}moved?\b[^.]{0,80}\x60[^\x60]+\x60[^.]{0,60}\b(?:to|into|out of)\b`,
+    String.raw `\b(?:are|is|was|were|been)\s+(?:both\s+)?replaced\b|\x60[^\x60]+\x60\s+replaces\s+\x60`,
+    String.raw `\bnow\b[^.]{0,60}\binstead of\b`,
+    String.raw `\b(?:accepts?|takes?|returns?|receives?)\s+(?:a |an )?(?:pointer|reference|value|slice|copy)\b[^.]{0,30}\binstead of\b`,
+    String.raw `\bchang(?:e|ed|es)\b[^.]{0,80}\bfrom\s+\x60[^\x60]+\x60\s+to\s+\x60`,
+    String.raw `\bno longer (?:subclass(?:es)?|inherits?|comparable|usable|considers?|escapes?|initiali[sz]ed|quotes?|sets?|ha(?:s|ve) a default|safe|valid|recogni[sz]ed|parsed?|emitted|exposed|called)\b|\bis not set anymore\b|\bnot set anymore\b`,
+].join("|"), "i");
+/**
+ * The text classified: RST ``literals`` read as `literals`, link targets and
+ * bare URLs dropped (a `go.dev/doc/go1.21` link made "Drop support for Go 1.21"
+ * read as a docs change), GitHub's "by @user in <PR url>" suffix dropped.
+ */
+export function classificationText(text) {
+    return text
+        .replace(/``/g, "`")
+        .replace(/\]\([^)]*\)/g, "]")
+        .replace(/\bby @[\w-]+(?:\[bot\])? in\s+\S+/g, " ")
+        .replace(/https?:\/\/\S+/g, " ");
+}
 const DEPRECATION = /deprecat/i;
 /**
  * An entry whose main verb is "deprecate" is a deprecation even when it names
@@ -135,11 +210,14 @@ const DEPRECATION = /deprecat/i;
  */
 const LEADING_DEPRECATION = /^\W*(?:\*\*[^*]{1,40}\*\*:?\s*)?(?:deprecated?|deprecates|deprecating)\b/i;
 /** Kind of a single changelog line by its own wording. */
-export function classifyText(text) {
+export function classifyText(raw) {
+    const text = classificationText(raw);
     if (META_BREAKING.test(text))
         return SECURITY.test(text) ? "security" : "change";
     if (EXPLICIT_BREAKING_MARKER.test(text))
         return "breaking";
+    if (STATED_COMPATIBLE.test(text))
+        return DEPRECATION.test(text) ? "deprecation" : "change";
     if (NON_BREAKING_LABEL.test(text)) {
         if (SECURITY.test(text))
             return "security";
@@ -158,47 +236,82 @@ export function classifyText(text) {
         return "security";
     if (FUTURE_INTENT.test(text))
         return DEPRECATION.test(text) ? "deprecation" : "change";
-    if (BREAKING_HEURISTIC.test(text))
-        return "breaking";
-    if (REMOVAL_HEURISTIC.test(text) && !INTERNAL_CHANGE.test(text) && !LEADING_FIX.test(text))
+    if (UNDO.test(text))
+        return DEPRECATION.test(text) ? "deprecation" : "change";
+    if (!SCOPED_NON_API.test(text)) {
+        if (RUNTIME_SUPPORT.test(text) || BREAKING_HEURISTIC.test(text))
+            return "breaking";
+        if (MADE_PRIVATE.test(text) && !LEADING_FIX.test(text))
+            return "breaking";
+        if (API_CHANGE.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
+            return "breaking";
+    }
+    if (REMOVAL_HEURISTIC.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
         return "breaking";
     if (DEPRECATION.test(text))
         return "deprecation";
     return "change";
 }
-const ADDITIVE_HEADING = /^\W*(?:added|adds|new|new features?|features?|enhancements?|improvements?|fixed|fixes|bug ?fixes|performance(?: improvements)?|perf|optimi[sz]ations?|docs?|documentation|tests?|testing|internal|chores?|ci|build|refactor(?:ing)?|misc(?:ellaneous)?|other(?: changes)?)\W*$/i;
+const FIX_HEADING = /^\W*(?:fixed|fixes|bug ?fixes|bugfixes|fix)\W*$/i;
+// "Other changes" / "Misc" are not additive: pgx 5 files its type removals and renames
+// under "Other Changes", and marshmallow 4 a changed base class.
+const ADDITIVE_HEADING = /^\W*(?:added|adds|new|new features?|features?|enhancements?|improvements?|fixed|fixes|bug ?fixes|performance(?: improvements)?|perf|optimi[sz]ations?|docs?|documentation|tests?|testing|internal|chores?|ci|build|refactor(?:ing)?)\W*$/i;
 /** Context implied by a heading or label, or null when it carries no signal ("### Changed"). */
 export function classifyHeading(heading) {
     if (/(?<!-)\bbreaking\b|⚠|incompatib|migration|\bmajor changes?\b/i.test(heading))
         return "breaking";
-    if (/\bremov(?:e|ed|als?)\b|\bapi changes?\b/i.test(heading))
+    // "Removed", "Removals", "Deprecated and Removed", "API changes": a category.
+    // "`Cargo.lock` Removed from Tracking" (sqlx 0.9.0) is a news item about the
+    // repository, and its three paragraphs were flagged breaking.
+    // "Previously-deprecated APIs have been removed, including" (marshmallow 4) is a removal list, not a deprecation one.
+    if (/(?:^\W*|(?:\band|[&/,])\s*)remov(?:e|ed|als?)\b|\bapi changes?\b|\b(?:have|has) been removed\b|\b(?:were|are) removed\b/i.test(heading))
         return "removal";
     if (/security|vulnerab/i.test(heading))
         return "security";
     if (/deprecat/i.test(heading))
         return "deprecation";
+    // Fixes are additive, and stricter: the author filed the entry as a bug fix, so API-shaped
+    // wording in it ("change default export to named function") is not read as a break.
+    if (FIX_HEADING.test(heading))
+        return "fixes";
     if (ADDITIVE_HEADING.test(heading))
         return "additive";
     return null;
 }
 /** Final kind: an explicit heading or bullet parent wins; removal and additive contexts refine the line's wording. */
-export function classifyEntry(text, context) {
+export function classifyEntry(raw, context) {
     if (context === "breaking" || context === "security" || context === "deprecation") {
         // A security line under "Breaking" stays breaking: the heading is the author's own call.
         return context;
     }
+    const text = classificationText(raw);
     if (context === "removal") {
         if (META_BREAKING.test(text))
             return "change";
         if (EXPLICIT_BREAKING_MARKER.test(text))
             return "breaking";
-        if (DEPRECATION.test(text) && !/\bremov/i.test(text))
+        if (STATED_COMPATIBLE.test(text) || UNDO.test(text))
+            return DEPRECATION.test(text) ? "deprecation" : "change";
+        // A deprecation filed under Removed is one when it leads with it; "`x` (deprecated in 3.24.0)" was removed.
+        if (LEADING_DEPRECATION.test(text) || (DEPRECATION.test(text) && !/\bremov|\(deprecated (?:in|since)\b|\bno longer\b|\bwere replaced\b/i.test(text))) {
             return "deprecation";
-        return INTERNAL_CHANGE.test(text) ? "change" : "breaking";
+        }
+        return isInternal(text) ? "change" : "breaking";
     }
-    if (context === "additive") {
+    if (context === "additive" || context === "fixes") {
         if (!META_BREAKING.test(text) && EXPLICIT_BREAKING_MARKER.test(text))
             return "breaking";
+        // An API removal, rename or raised runtime minimum is breaking under "Features" too
+        // (uuid 11 lists "remove UMD build" there; hyper 1.0 "rename to `Http2ClientConnExec`").
+        const quiet = STATED_COMPATIBLE.test(text) || UNDO.test(text) || SCOPED_NON_API.test(text) || NON_BREAKING_LABEL.test(text);
+        if (!quiet && !META_BREAKING.test(text)) {
+            if (RUNTIME_SUPPORT.test(text))
+                return "breaking";
+            if (context === "additive" && MADE_PRIVATE.test(text) && !LEADING_FIX.test(text))
+                return "breaking";
+            if (context === "additive" && API_CHANGE.test(text) && !isInternal(text) && !LEADING_FIX.test(text))
+                return "breaking";
+        }
         if (SECURITY.test(text))
             return "security";
         return DEPRECATION.test(text) ? "deprecation" : "change";

package/dist/live/changelog.d.ts

@@ -7,6 +7,8 @@
  *   conventional          `## [7.0.0](https://…/compare/…) (2025-06-24)`
  *   plain / prefixed      `## 1.2.3`, `# v1.2.3 (2024-01-01)`, `### Version 1.2.3`, `## fastembed 5.0.0`
  *   setext                `1.2.3` underlined with `===` / `---`
+ *   reStructuredText      `Version 3.0.0` underlined (or over- and underlined)
+ *                         with any of `= - ~ ^ * + # " '`, then `Released 2023-09-30`
  *   History.md (express)  `1.2.3 / 2020-01-01`
  * A heading only opens a section when the rest of it looks like a trailer
  * (date, link, "yanked") — `## Upgrading from 1.x` or `#### Rust 1.70 support`
@@ -17,6 +19,13 @@
  * reference definitions are skipped: they are examples and URLs, not changes.
  */
 import { type EntryKind } from "./changelog-classify.js";
+/**
+ * Version of the parser AND classifier output. A parsed changelog is cached
+ * for 7 days per package version, so a fix to either one stays invisible
+ * for a week unless this changes: bump it with every change to parseChangelog
+ * or changelog-classify.ts that can alter a section or an entry's kind.
+ */
+export declare const CHANGELOG_PARSER_VERSION = 4;
 export interface ChangelogEntry {
     kind: EntryKind;
     text: string;
@@ -26,6 +35,14 @@ export interface ChangelogEntry {
      * under actix-web's "Removed" reads as harmless, to an agent and to a rater alike.
      */
     under?: string;
+    /**
+     * Bullets nested under this entry (feature lists, "Breaking change: ..."
+     * notes). They belong to the entry, not beside it: sqlx 0.9.0's Breaking
+     * section has 23 top-level bullets, and counting every nested one reported
+     * "83 entries flagged breaking" (2026-10-07). A nested bullet that is more
+     * severe than its parent raises the parent's kind.
+     */
+    details?: string[];
 }
 export interface ChangelogSection {
     version: string;
@@ -49,8 +66,10 @@ export declare function parseVersionHeading(raw: string): {
 } | null;
 /** Parse a changelog into version sections, in document order (usually newest first). */
 export declare function parseChangelog(text: string): ChangelogSection[];
-/** True when `version` lies in (from, to] by semver precedence; unreadable versions are out. */
-export declare function inRange(version: string, from: string, to: string): boolean;
+/** Version order: 1, -1, 0, or null when either side is unreadable. Semver precedence by default. */
+export type VersionOrder = (a: string, b: string) => number | null;
+/** True when `version` lies in (from, to] by `order`; unreadable versions are out. */
+export declare function inRange(version: string, from: string, to: string, order?: VersionOrder): boolean;
 /**
  * Sections in (from, to], plus whether the changelog reaches both ends of the
  * range: its newest section is at or past `to`, and its oldest at or before
@@ -58,7 +77,7 @@ export declare function inRange(version: string, from: string, to: string): bool
  * stopped being maintained two majors ago is reported as not covering the
  * range instead of silently presenting a partial history as the whole one.
  */
-export declare function selectRange(sections: ChangelogSection[], from: string, to: string, firstInRange: string): {
+export declare function selectRange(sections: ChangelogSection[], from: string, to: string, firstInRange: string, order?: VersionOrder): {
     sections: ChangelogSection[];
     coversRange: boolean;
 };