@4da/mcp-server 5.0.3 → 6.0.0

package/dist/tools/record-feedback.js

@@ -13,11 +13,11 @@ export const recordFeedbackTool = {
 
 Feedback actions:
 - "click": User clicked/opened the item
-- "save": User saved/bookmarked the item
+- "save": User saved/bookmarked the item, or said it is relevant (also records a relevance label)
 - "dismiss": User dismissed the item
-- "mark_irrelevant": User marked item as not relevant
+- "mark_irrelevant": User said the item is not relevant (also records a relevance label)
 
-This records what happened; it does not train content preferences (interaction counts only graduate scoring's bootstrap gate).`,
+Only "save" and "mark_irrelevant" are relevance labels; they are what 4DA's accuracy measurement reads. Use them only when the user actually says whether the item matters to them. This does not train content preferences.`,
     inputSchema: {
         type: "object",
         properties: {
@@ -27,8 +27,7 @@ This records what happened; it does not train content preferences (interaction c
             },
             source_type: {
                 type: "string",
-                description: 'The source type: "hackernews", "arxiv", or "reddit"',
-                enum: ["hackernews", "arxiv", "reddit"],
+                description: "Optional. The item's source type (e.g. \"hackernews\", \"crates_io\", \"lobsters\"); if given it must match the item.",
             },
             action: {
                 type: "string",
@@ -36,7 +35,7 @@ This records what happened; it does not train content preferences (interaction c
                 enum: ["click", "save", "dismiss", "mark_irrelevant"],
             },
         },
-        required: ["item_id", "source_type", "action"],
+        required: ["item_id", "action"],
     },
 };
 const validActions = ["click", "save", "dismiss", "mark_irrelevant"];
@@ -44,10 +43,10 @@ const validActions = ["click", "save", "dismiss", "mark_irrelevant"];
  * Execute the record_feedback tool
  */
 export function executeRecordFeedback(db, params) {
-    if (!params.item_id || !params.source_type || !params.action) {
+    if (!params.item_id || !params.action) {
         return {
             success: false,
-            message: "item_id, source_type, and action are required",
+            message: "item_id and action are required",
         };
     }
     if (!validActions.includes(params.action)) {

package/dist/tools/signal-classifier.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Signal vocabulary for get_actionable_signals: the types, and the mapping
+ * from the desktop pipeline's stored priority tiers onto this tool's.
+ *
+ * This file used to hold a keyword classifier that labelled unstamped feed
+ * items. It was removed on 2026-10-02: two keywords such as "cve" and "patch"
+ * made an item a security alert, and any language name in the stack
+ * ("rust", "javascript") counted as a stack match, so russh and Angular CVEs
+ * no project used came out "high — affects your rust stack" and drove the
+ * briefing to human_only. The server no longer invents classifications;
+ * it reports the pipeline's, gated by the relevance judge.
+ */
+export type SignalType = "security_alert" | "breaking_change" | "tool_discovery" | "tech_trend" | "learning" | "competitive_intel";
+export type SignalPriority = "critical" | "high" | "medium" | "low";
+/**
+ * The desktop pipeline stores its own notification tiers in
+ * `source_items.signal_priority` — critical, alert, advisory, watch — not this
+ * tool's critical/high/medium/low. The reader used to cast the stored string
+ * straight through, so 92 of the 93 stamped rows in the live corpus carried a
+ * priority no filter, sort, or briefing rule recognised (they sorted last and
+ * an "alert"-tier security alert could never reach the human_only rule).
+ * Mapped by tier order; an unrecognised value lands in the middle rather than
+ * being silently dropped or silently promoted.
+ */
+export declare function normalizeStoredPriority(stored: string): SignalPriority;

package/dist/tools/signal-classifier.js

@@ -0,0 +1,40 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Signal vocabulary for get_actionable_signals: the types, and the mapping
+ * from the desktop pipeline's stored priority tiers onto this tool's.
+ *
+ * This file used to hold a keyword classifier that labelled unstamped feed
+ * items. It was removed on 2026-10-02: two keywords such as "cve" and "patch"
+ * made an item a security alert, and any language name in the stack
+ * ("rust", "javascript") counted as a stack match, so russh and Angular CVEs
+ * no project used came out "high — affects your rust stack" and drove the
+ * briefing to human_only. The server no longer invents classifications;
+ * it reports the pipeline's, gated by the relevance judge.
+ */
+/**
+ * The desktop pipeline stores its own notification tiers in
+ * `source_items.signal_priority` — critical, alert, advisory, watch — not this
+ * tool's critical/high/medium/low. The reader used to cast the stored string
+ * straight through, so 92 of the 93 stamped rows in the live corpus carried a
+ * priority no filter, sort, or briefing rule recognised (they sorted last and
+ * an "alert"-tier security alert could never reach the human_only rule).
+ * Mapped by tier order; an unrecognised value lands in the middle rather than
+ * being silently dropped or silently promoted.
+ */
+export function normalizeStoredPriority(stored) {
+    switch (stored.trim().toLowerCase()) {
+        case "critical":
+            return "critical";
+        case "alert":
+        case "high":
+            return "high";
+        case "advisory":
+        case "medium":
+            return "medium";
+        case "watch":
+        case "low":
+            return "low";
+        default:
+            return "medium";
+    }
+}

package/dist/tools/upgrade-impact-callsites.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Call-site scan for `upgrade_impact`: which files in THIS project use the
+ * package, and which of its symbols they name.
+ *
+ * The symbols are what make a changelog actionable: "6 breaking changes" is
+ * noise until one of them says `InitOptions` and the project imports
+ * `InitOptions`. The scan is local-only (nothing leaves the machine) and
+ * bounded, because it runs inside a tool call: at most 6000 candidate files,
+ * none over 1 MB, and the usual generated / vendored directories skipped.
+ * Symlinks are not followed, so a link cycle cannot stall the walk.
+ *
+ * It is a lexical scan, not a type-checker: an import inside a comment
+ * counts, and a re-exported symbol used through a local barrel does not.
+ * Both errors are tolerable for prioritising a changelog — the entries are
+ * all still listed; this only decides which come first.
+ */
+import type { UpgradeEcosystem } from "../live/upgrade-sources.js";
+export interface CallSiteReport {
+    total_files: number;
+    files: Array<{
+        path: string;
+        matches: number;
+    }>;
+    symbols_used: string[];
+    /** Present when the walk stopped at the file cap: counts are then lower bounds. */
+    truncated?: string;
+}
+/** Count npm usages of `pkg` (or `pkg/sub`) in one source file and collect imported names. */
+export declare function scanNpmSource(source: string, pkg: string, symbols: Set<string>): number;
+/** Count Rust usages of a crate (`-` read as `_`) in one file and collect the item names it reaches. */
+export declare function scanRustSource(source: string, crateName: string, symbols: Set<string>): number;
+/**
+ * Bounded scan of `root` for usages of `pkg`: concurrent reads under a time
+ * budget. Measured 2026-10-02 on 4DA's tree (856 TS/JS, 721 Rust files on a
+ * nearly full disk): one-at-a-time synchronous reads took 20-26 s cold, so the
+ * reads now overlap, a file is regex-scanned only when it contains the name at
+ * all, and a scan that runs out of time says its counts are lower bounds.
+ */
+export declare function scanCallSites(root: string, pkg: string, ecosystem: UpgradeEcosystem, opts?: {
+    timeBudgetMs?: number;
+    concurrency?: number;
+}): Promise<CallSiteReport>;
+/**
+ * Symbols (≥ 3 chars) that `text` names at a word boundary, case-sensitively.
+ * Shorter names (`fs`, `Ok`) would match ordinary prose, so they never flag.
+ * A plain lowercase word (`new`, `params`, `default` — Rust paths and
+ * CommonJS bindings yield plenty) counts only when the entry marks it as
+ * code: in backticks, called `name(`, or reached through `::` / `.`.
+ * Measured on the first live run: `TextEmbedding::new` put `new` in the
+ * symbol set, which would have flagged every "Add new model" entry.
+ */
+export declare function matchSymbols(text: string, symbols: string[]): string[];

package/dist/tools/upgrade-impact-callsites.js

@@ -0,0 +1,226 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Call-site scan for `upgrade_impact`: which files in THIS project use the
+ * package, and which of its symbols they name.
+ *
+ * The symbols are what make a changelog actionable: "6 breaking changes" is
+ * noise until one of them says `InitOptions` and the project imports
+ * `InitOptions`. The scan is local-only (nothing leaves the machine) and
+ * bounded, because it runs inside a tool call: at most 6000 candidate files,
+ * none over 1 MB, and the usual generated / vendored directories skipped.
+ * Symlinks are not followed, so a link cycle cannot stall the walk.
+ *
+ * It is a lexical scan, not a type-checker: an import inside a comment
+ * counts, and a re-exported symbol used through a local barrel does not.
+ * Both errors are tolerable for prioritising a changelog — the entries are
+ * all still listed; this only decides which come first.
+ */
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { IgnoreRules } from "../gitignore.js";
+const SKIP_DIRS = new Set([
+    "node_modules", "target", ".git", "dist", "build", "out", ".next",
+    "coverage", "vendor", ".claude", ".venv",
+]);
+const NPM_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts", ".vue", ".svelte"]);
+const RUST_EXTS = new Set([".rs"]);
+const MAX_FILES = 6000;
+const MAX_FILE_BYTES = 1024 * 1024;
+const MAX_REPORTED_FILES = 50;
+const MAX_SYMBOLS = 100;
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+const IDENT = /^[A-Za-z_$][\w$]*$/;
+/** Names from an import clause: `Def`, `* as ns`, `{ a, b as c, type D }`. Imported names, not local aliases. */
+function parseImportClause(clause, into) {
+    const braces = /\{([^}]*)\}/.exec(clause);
+    if (braces) {
+        for (const part of braces[1].split(",")) {
+            const name = part.trim().replace(/^type\s+/, "").split(/\s+as\s+/)[0].trim();
+            if (IDENT.test(name) && name !== "default")
+                into.add(name);
+        }
+    }
+    const outside = clause.replace(/\{[^}]*\}/g, "").replace(/^\s*type\s+/, "");
+    const ns = /\*\s+as\s+([A-Za-z_$][\w$]*)/.exec(outside);
+    if (ns)
+        into.add(ns[1]);
+    const def = /^\s*([A-Za-z_$][\w$]*)\s*(?:,|$)/.exec(outside);
+    if (def)
+        into.add(def[1]);
+}
+/** Count npm usages of `pkg` (or `pkg/sub`) in one source file and collect imported names. */
+export function scanNpmSource(source, pkg, symbols) {
+    const spec = `${escapeRegex(pkg)}(?:/[^'"\`\\s]*)?`;
+    let matches = 0;
+    const fromRe = new RegExp(String.raw `\b(?:import|export)\s+([^;'"\`]*?)\s*from\s*['"]${spec}['"]`, "g");
+    for (const m of source.matchAll(fromRe)) {
+        matches++;
+        if (!/^\s*\*\s*$/.test(m[1]))
+            parseImportClause(m[1], symbols);
+    }
+    const bareRe = new RegExp(String.raw `\bimport\s*['"]${spec}['"]`, "g");
+    matches += [...source.matchAll(bareRe)].length;
+    const dynRe = new RegExp(String.raw `\bimport\s*\(\s*['"]${spec}['"]\s*\)`, "g");
+    matches += [...source.matchAll(dynRe)].length;
+    const reqRe = new RegExp(String.raw `(?:(?:const|let|var)\s+(\{[^}]*\}|[A-Za-z_$][\w$]*)\s*=\s*)?\brequire\s*\(\s*['"]${spec}['"]\s*\)`, "g");
+    for (const m of source.matchAll(reqRe)) {
+        matches++;
+        const binding = m[1];
+        if (!binding)
+            continue;
+        if (binding.startsWith("{")) {
+            for (const part of binding.slice(1, -1).split(",")) {
+                const name = part.split(":")[0].trim();
+                if (IDENT.test(name))
+                    symbols.add(name);
+            }
+        }
+        else
+            symbols.add(binding);
+    }
+    return matches;
+}
+/** Leaf names of a Rust `use` tree: `{A, b::{C, D as E}, self, *}` -> A, C, D. */
+function useTreeLeaves(tree, into) {
+    const flat = tree.replace(/[{}]/g, ",");
+    for (const part of flat.split(",")) {
+        const pathPart = part.trim().split(/\s+as\s+/)[0].trim();
+        if (pathPart.endsWith("::"))
+            continue; // `models::{…}` — the group's members are the leaves
+        const leaf = pathPart.split("::").filter(Boolean).pop();
+        if (leaf && /^[A-Za-z_]\w*$/.test(leaf) && leaf !== "self" && leaf !== "super" && leaf !== "crate") {
+            into.add(leaf);
+        }
+    }
+}
+/** Count Rust usages of a crate (`-` read as `_`) in one file and collect the item names it reaches. */
+export function scanRustSource(source, crateName, symbols) {
+    const ident = escapeRegex(crateName.replace(/-/g, "_"));
+    let matches = 0;
+    const useRe = new RegExp(String.raw `\buse\s+(?:::)?${ident}::([^;]+);`, "g");
+    const withoutUses = source.replace(useRe, (_all, tree) => {
+        matches++;
+        useTreeLeaves(tree, symbols);
+        return "";
+    });
+    const externRe = new RegExp(String.raw `\bextern\s+crate\s+${ident}\b`, "g");
+    matches += [...withoutUses.matchAll(externRe)].length;
+    // Qualified paths outside `use` lines; `crate::x::` / `self::x::` are local modules, hence the lookbehind.
+    const pathRe = new RegExp(String.raw `(?<![\w:])${ident}::((?:[A-Za-z_]\w*::)*[A-Za-z_]\w*)`, "g");
+    for (const m of withoutUses.matchAll(pathRe)) {
+        matches++;
+        for (const seg of m[1].split("::"))
+            symbols.add(seg);
+    }
+    return matches;
+}
+/** Source files under `root`, skipping installed code, build output, hidden and .gitignored directories. */
+function listSources(root, exts, budget) {
+    const files = [];
+    const ignore = new IgnoreRules(root);
+    const stack = [[root, ""]];
+    while (stack.length > 0 && budget.left > 0) {
+        const [dir, rel] = stack.pop();
+        ignore.load(rel);
+        let entries;
+        try {
+            entries = fs.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (entry.isSymbolicLink())
+                continue;
+            const childRel = rel ? `${rel}/${entry.name}` : entry.name;
+            if (entry.isDirectory()) {
+                if (SKIP_DIRS.has(entry.name) || entry.name.startsWith(".") || ignore.ignores(childRel, true))
+                    continue;
+                stack.push([path.join(dir, entry.name), childRel]);
+            }
+            else if (entry.isFile() && exts.has(path.extname(entry.name).toLowerCase())) {
+                if (budget.left-- <= 0)
+                    break;
+                files.push(path.join(dir, entry.name));
+            }
+        }
+    }
+    return files;
+}
+/**
+ * Bounded scan of `root` for usages of `pkg`: concurrent reads under a time
+ * budget. Measured 2026-10-02 on 4DA's tree (856 TS/JS, 721 Rust files on a
+ * nearly full disk): one-at-a-time synchronous reads took 20-26 s cold, so the
+ * reads now overlap, a file is regex-scanned only when it contains the name at
+ * all, and a scan that runs out of time says its counts are lower bounds.
+ */
+export async function scanCallSites(root, pkg, ecosystem, opts = {}) {
+    const exts = ecosystem === "npm" ? NPM_EXTS : RUST_EXTS;
+    const budget = { left: MAX_FILES };
+    const symbols = new Set();
+    const hits = [];
+    const needle = ecosystem === "npm" ? pkg : pkg.replace(/-/g, "_");
+    const deadline = Date.now() + (opts.timeBudgetMs ?? CALLSITE_TIME_BUDGET_MS);
+    const files = listSources(root, exts, budget);
+    let next = 0;
+    let timedOut = false;
+    const worker = async () => {
+        while (next < files.length) {
+            if (Date.now() > deadline) {
+                timedOut = true;
+                return;
+            }
+            const file = files[next++];
+            let source;
+            try {
+                const stat = await fs.promises.stat(file);
+                if (stat.size > MAX_FILE_BYTES)
+                    continue;
+                source = await fs.promises.readFile(file, "utf8");
+            }
+            catch {
+                continue;
+            }
+            if (!source.includes(needle))
+                continue;
+            const matches = ecosystem === "npm" ? scanNpmSource(source, pkg, symbols) : scanRustSource(source, pkg, symbols);
+            if (matches > 0)
+                hits.push({ path: path.relative(root, file).split(path.sep).join("/"), matches });
+        }
+    };
+    await Promise.all(Array.from({ length: Math.min(opts.concurrency ?? 32, files.length) }, worker));
+    hits.sort((a, b) => b.matches - a.matches || a.path.localeCompare(b.path));
+    const report = {
+        total_files: hits.length,
+        files: hits.slice(0, MAX_REPORTED_FILES),
+        symbols_used: [...symbols].sort().slice(0, MAX_SYMBOLS),
+    };
+    if (budget.left <= 0)
+        report.truncated = `stopped after ${MAX_FILES} source files; counts are lower bounds`;
+    else if (timedOut)
+        report.truncated = `stopped after ${Math.round((opts.timeBudgetMs ?? CALLSITE_TIME_BUDGET_MS) / 1000)} s with ${files.length - next} of ${files.length} files unread; counts are lower bounds`;
+    return report;
+}
+const CALLSITE_TIME_BUDGET_MS = 10_000;
+/**
+ * Symbols (≥ 3 chars) that `text` names at a word boundary, case-sensitively.
+ * Shorter names (`fs`, `Ok`) would match ordinary prose, so they never flag.
+ * A plain lowercase word (`new`, `params`, `default` — Rust paths and
+ * CommonJS bindings yield plenty) counts only when the entry marks it as
+ * code: in backticks, called `name(`, or reached through `::` / `.`.
+ * Measured on the first live run: `TextEmbedding::new` put `new` in the
+ * symbol set, which would have flagged every "Add new model" entry.
+ */
+export function matchSymbols(text, symbols) {
+    return symbols.filter((s) => {
+        if (s.length < 3)
+            return false;
+        const e = escapeRegex(s);
+        const pattern = /^[a-z]+$/.test(s)
+            ? String.raw `\x60${e}(?:\(\))?\x60|(?<![\w$])${e}\(|(?:::|\.)${e}(?![\w$])|(?<![\w$])${e}::`
+            : String.raw `(?<![\w$])${e}(?![\w$])`;
+        return new RegExp(pattern).test(text);
+    });
+}

package/dist/tools/upgrade-impact-literals.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Breaking changes that live in string literals: route and pattern syntax.
+ *
+ * Symbol matching cannot see these. axum 0.8 changed path parameters from
+ * `/:single` and `/*many` to `/{single}` and `/{*many}`; a project's code
+ * imports `Router`, and the old syntax sits only in strings like
+ * `.route("/users/:id", ...)`. express 5 (path-to-regexp 8) and react-router
+ * changed route syntax the same way.
+ *
+ * So: take the backticked syntax fragments on the "from" side of a breaking
+ * entry ("changed from `/:single` ... to `/{single}`"), turn each into a shape
+ * (identifiers become placeholders, punctuation stays literal: `/:\w+`), and
+ * look for that shape inside string literals of the files that import the
+ * package. Only fragments that are mostly syntax qualify; a code path like
+ * `Router::route` or `res.json()` is symbol matching's job.
+ */
+import type { ReportSection } from "./upgrade-impact-report.js";
+export interface LiteralHit {
+    file: string;
+    line: number;
+    literal: string;
+}
+/**
+ * Shapes of the syntax an entry says is going away. Only the text before
+ * " to " when the entry reads "from X to Y", so the new syntax (which a
+ * migrated project already uses) is never reported as needing a change.
+ */
+export declare function oldSyntaxShapes(entryText: string): RegExp[];
+/** String literals of one source file, with their line numbers. */
+export declare function stringLiterals(source: string): Array<{
+    text: string;
+    line: number;
+}>;
+/**
+ * Flag breaking/deprecation entries whose old syntax appears in a string
+ * literal of a file that imports the package. Mutates the entries (adds
+ * `touches_your_code` and `matched_literals`) and returns how many breaking
+ * entries became touching, plus up to five example literals for the summary.
+ */
+export declare function flagOldSyntax(sections: ReportSection[], files: Array<{
+    path: string;
+}>, root: string | null): Promise<{
+    newlyTouching: number;
+    examples: string[];
+}>;

package/dist/tools/upgrade-impact-literals.js

@@ -0,0 +1,118 @@
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * Breaking changes that live in string literals: route and pattern syntax.
+ *
+ * Symbol matching cannot see these. axum 0.8 changed path parameters from
+ * `/:single` and `/*many` to `/{single}` and `/{*many}`; a project's code
+ * imports `Router`, and the old syntax sits only in strings like
+ * `.route("/users/:id", ...)`. express 5 (path-to-regexp 8) and react-router
+ * changed route syntax the same way.
+ *
+ * So: take the backticked syntax fragments on the "from" side of a breaking
+ * entry ("changed from `/:single` ... to `/{single}`"), turn each into a shape
+ * (identifiers become placeholders, punctuation stays literal: `/:\w+`), and
+ * look for that shape inside string literals of the files that import the
+ * package. Only fragments that are mostly syntax qualify; a code path like
+ * `Router::route` or `res.json()` is symbol matching's job.
+ */
+import { promises as fs } from "node:fs";
+import path from "node:path";
+/** Punctuation that makes a fragment syntax rather than a name. */
+const SYNTAX_CHARS = /[/:*{}?$%@#<>]/g;
+const WORD = /[A-Za-z_][\w-]*/g;
+const MAX_FILES = 300;
+const MAX_FILE_BYTES = 512 * 1024;
+const MAX_HITS_PER_ENTRY = 5;
+function escapeRegex(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+/**
+ * Shapes of the syntax an entry says is going away. Only the text before
+ * " to " when the entry reads "from X to Y", so the new syntax (which a
+ * migrated project already uses) is never reported as needing a change.
+ */
+export function oldSyntaxShapes(entryText) {
+    const fromTo = /\bfrom\b([\s\S]*?)\bto\b/i.exec(entryText);
+    const scope = fromTo ? fromTo[1] : entryText;
+    const shapes = [];
+    for (const [, fragment] of scope.matchAll(/`([^`\s]{2,40})`/g)) {
+        // A path or call (`Router::route`, `res.json()`, `a.b`) is a symbol, not syntax.
+        if (/^[\w$.:]+(?:\(\))?$/.test(fragment) || fragment.includes("("))
+            continue;
+        const syntax = fragment.match(SYNTAX_CHARS) ?? [];
+        const words = fragment.match(WORD) ?? [];
+        if (syntax.length < 2 || words.length === 0)
+            continue;
+        let pattern = "";
+        let last = 0;
+        for (const m of fragment.matchAll(WORD)) {
+            pattern += escapeRegex(fragment.slice(last, m.index)) + "[A-Za-z_][\\w-]*";
+            last = (m.index ?? 0) + m[0].length;
+        }
+        pattern += escapeRegex(fragment.slice(last));
+        shapes.push(new RegExp(pattern));
+    }
+    return shapes;
+}
+const STRING_LITERAL = /"(?:[^"\\\n]|\\.)*"|'(?:[^'\\\n]|\\.)*'|`(?:[^`\\]|\\.)*`/g;
+/** String literals of one source file, with their line numbers. */
+export function stringLiterals(source) {
+    const out = [];
+    for (const m of source.matchAll(STRING_LITERAL)) {
+        const start = m.index ?? 0;
+        out.push({ text: m[0].slice(1, -1), line: source.slice(0, start).split("\n").length });
+    }
+    return out;
+}
+/**
+ * Flag breaking/deprecation entries whose old syntax appears in a string
+ * literal of a file that imports the package. Mutates the entries (adds
+ * `touches_your_code` and `matched_literals`) and returns how many breaking
+ * entries became touching, plus up to five example literals for the summary.
+ */
+export async function flagOldSyntax(sections, files, root) {
+    const candidates = sections
+        .flatMap((s) => s.entries)
+        .filter((e) => e.kind === "breaking" || e.kind === "deprecation")
+        .map((entry) => ({ entry, shapes: oldSyntaxShapes(entry.text) }))
+        .filter((c) => c.shapes.length > 0);
+    if (!root || candidates.length === 0 || files.length === 0)
+        return { newlyTouching: 0, examples: [] };
+    const literals = [];
+    for (const file of files.slice(0, MAX_FILES)) {
+        const abs = path.resolve(root, file.path);
+        try {
+            const stat = await fs.stat(abs);
+            if (stat.size > MAX_FILE_BYTES)
+                continue;
+            for (const lit of stringLiterals(await fs.readFile(abs, "utf8"))) {
+                // Routes and patterns have no whitespace; code and prose inside strings do (a test
+                // fixture in 4DA's watcher.rs holding Rust source matched `/*many` on the first live run).
+                if (lit.text.length <= 200 && !/\s|\\[nrt]/.test(lit.text))
+                    literals.push({ file: file.path, ...lit });
+            }
+        }
+        catch {
+            // A file that vanished since the scan is simply not searched.
+        }
+    }
+    let newlyTouching = 0;
+    const examples = new Set();
+    for (const { entry, shapes } of candidates) {
+        const hits = [];
+        for (const lit of literals) {
+            if (hits.length >= MAX_HITS_PER_ENTRY)
+                break;
+            if (shapes.some((s) => s.test(lit.text)))
+                hits.push({ file: lit.file, line: lit.line, literal: lit.text.slice(0, 80) });
+        }
+        if (hits.length === 0)
+            continue;
+        if (entry.kind === "breaking" && !entry.touches_your_code)
+            newlyTouching++;
+        entry.touches_your_code = true;
+        entry.matched_literals = hits;
+        hits.forEach((h) => examples.size < 5 && examples.add(`"${h.literal}"`));
+    }
+    return { newlyTouching, examples: [...examples] };
+}

package/dist/tools/upgrade-impact-report.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Output shaping for `upgrade_impact`: cross-referencing changelog entries
+ * with the project's symbols, concise vs detailed trimming, and the one-line
+ * summary an agent reads first.
+ *
+ * Concise is the default because a multi-major upgrade (vite 6 -> 7 crosses
+ * dozens of releases) produces hundreds of "fix typo"-class entries that
+ * would bury the five that matter. Concise keeps EVERY breaking, deprecation
+ * and security entry; of the plain changes it keeps up to 20 per version that
+ * sit under an API or neutral heading ("Changed", "Methods", "Types", or none)
+ * and up to 3 under an additive one ("Added", "Fixed", "Docs"), and states how
+ * many it left out — omission is always visible, never silent.
+ *
+ * The neutral allowance is where the classifier's misses live: on the
+ * 2026-10-03 panel, 11 of 15 breaking changes it called plain sat under
+ * actix-web 4's "Functions" / "Methods" / "Types" headings, and three-per-version
+ * hid them from the agent entirely.
+ */
+import { type EntryKind } from "../live/changelog-classify.js";
+import type { ChangelogSection } from "../live/changelog.js";
+export type ResponseFormat = "concise" | "detailed";
+export interface ReportEntry {
+    kind: EntryKind;
+    text: string;
+    /** The changelog heading or parent bullet the entry sits under ("Removed", "Breaking Changes"). */
+    under?: string;
+    touches_your_code?: boolean;
+    matched_symbols?: string[];
+    /** String literals in your code that use the syntax this entry retires (route patterns and the like). */
+    matched_literals?: Array<{
+        file: string;
+        line: number;
+        literal: string;
+    }>;
+}
+export interface ReportSection {
+    version: string;
+    date: string | null;
+    entries: ReportEntry[];
+    /** Concise mode only: how many plain `change` entries were left out. */
+    omitted_changes?: number;
+}
+export interface ShapedChangelog {
+    sections: ReportSection[];
+    breaking: number;
+    deprecations: number;
+    security: number;
+    /** Breaking entries naming a symbol this project uses (deprecations are flagged per entry but not counted here). */
+    touching: number;
+    touchingSymbols: string[];
+    truncated?: string;
+    /** Entries left out because an earlier (newer) section already listed the same change. */
+    duplicates?: number;
+}
+/** Flag, order and trim changelog sections. Counts always cover every entry, trimmed or not. */
+export declare function shapeChangelog(sections: ChangelogSection[], symbols: string[], format: ResponseFormat): ShapedChangelog;
+export type UpgradeType = "patch" | "minor" | "major" | "prerelease" | "unknown";
+/**
+ * Upgrade class by semver. A 0.x minor bump is reported as "major": under
+ * caret rules (npm and Cargo alike) 0.32 -> 0.37 is as breaking as 1 -> 2.
+ */
+export declare function upgradeType(from: string, to: string): UpgradeType;
+/** Major versions crossed (0.x minors count as majors, matching `upgradeType`). */
+export declare function majorsCrossed(from: string, to: string): number;
+/** Up to `count` published versions nearest to `wanted` by precedence, for "version not found" errors. */
+export declare function nearestVersions(published: string[], requested: string, count?: number): string[];
+export interface SummaryInput {
+    pkg: string;
+    from: string;
+    to: string;
+    releases: number;
+    breaking: number;
+    touching: number;
+    touchingSymbols: string[];
+    /** missing = no changelog file; no_entries = a file with no section for these releases; partial = some of them. */
+    changelog: "missing" | "no_entries" | "partial" | "complete";
+    advisoriesFixed: number | null;
+}
+/** The one sentence a human or agent reads first. */
+export declare function summarize(input: SummaryInput): string;