sverklo 0.2.12 → 0.2.13

package/dist/src/server/tool-overrides.test.js

@@ -0,0 +1,124 @@
+import { describe, it, expect, beforeEach } from "vitest";
+import { applyToolOverrides, __resetToolOverrideCache } from "./tool-overrides.js";
+// applyToolOverrides ships on every MCP session start and previously
+// had zero test coverage. These tests lock in the env-var override +
+// disable-list contract so a refactor can't silently change how tool
+// visibility or descriptions are controlled.
+const fixture = () => [
+    { name: "sverklo_search", description: "orig search", inputSchema: {} },
+    { name: "sverklo_refs", description: "orig refs", inputSchema: {} },
+    { name: "sverklo_forget", description: "orig forget", inputSchema: {} },
+    { name: "sverklo_remember", description: "orig remember", inputSchema: {} },
+];
+describe("applyToolOverrides — description overrides", () => {
+    beforeEach(() => {
+        // Strip any SVERKLO_TOOL_* env vars from a previous test.
+        for (const key of Object.keys(process.env)) {
+            if (key.startsWith("SVERKLO_TOOL_") || key === "SVERKLO_DISABLED_TOOLS") {
+                delete process.env[key];
+            }
+        }
+        __resetToolOverrideCache();
+    });
+    it("returns tools unchanged when no env vars are set", () => {
+        const result = applyToolOverrides(fixture());
+        expect(result).toHaveLength(4);
+        expect(result.find((t) => t.name === "sverklo_search")?.description).toBe("orig search");
+    });
+    it("overrides a tool description via SVERKLO_TOOL_<NAME>_DESCRIPTION", () => {
+        process.env.SVERKLO_TOOL_SEARCH_DESCRIPTION = "use only for architecture decisions";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result.find((t) => t.name === "sverklo_search")?.description).toBe("use only for architecture decisions");
+        // Other tools unchanged
+        expect(result.find((t) => t.name === "sverklo_refs")?.description).toBe("orig refs");
+    });
+    it("strips sverklo_ prefix when matching env var suffix", () => {
+        // Both SEARCH and REVIEW_DIFF-style names should work.
+        process.env.SVERKLO_TOOL_REMEMBER_DESCRIPTION = "project decision log only";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result.find((t) => t.name === "sverklo_remember")?.description).toBe("project decision log only");
+    });
+    it("handles multi-word tool names (underscore-separated)", () => {
+        const tools = [
+            { name: "sverklo_review_diff", description: "orig", inputSchema: {} },
+        ];
+        process.env.SVERKLO_TOOL_REVIEW_DIFF_DESCRIPTION = "strict review";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(tools);
+        expect(result[0].description).toBe("strict review");
+    });
+    it("never mutates the input array or its objects", () => {
+        const input = fixture();
+        const inputRef = input[0];
+        const inputDescription = inputRef.description;
+        process.env.SVERKLO_TOOL_SEARCH_DESCRIPTION = "mutated";
+        __resetToolOverrideCache();
+        applyToolOverrides(input);
+        // Source object must be unchanged — overrides return fresh objects.
+        expect(inputRef.description).toBe(inputDescription);
+    });
+    it("ignores empty-string overrides (treats as unset)", () => {
+        process.env.SVERKLO_TOOL_SEARCH_DESCRIPTION = "";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result.find((t) => t.name === "sverklo_search")?.description).toBe("orig search");
+    });
+});
+describe("applyToolOverrides — disable list", () => {
+    beforeEach(() => {
+        for (const key of Object.keys(process.env)) {
+            if (key.startsWith("SVERKLO_TOOL_") || key === "SVERKLO_DISABLED_TOOLS") {
+                delete process.env[key];
+            }
+        }
+        __resetToolOverrideCache();
+    });
+    it("hides a single tool named in SVERKLO_DISABLED_TOOLS", () => {
+        process.env.SVERKLO_DISABLED_TOOLS = "sverklo_forget";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result.map((t) => t.name)).not.toContain("sverklo_forget");
+        expect(result).toHaveLength(3);
+    });
+    it("hides multiple comma-separated tools", () => {
+        process.env.SVERKLO_DISABLED_TOOLS = "sverklo_forget,sverklo_remember";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result.map((t) => t.name)).toEqual(["sverklo_search", "sverklo_refs"]);
+    });
+    it("trims whitespace in the disabled list", () => {
+        process.env.SVERKLO_DISABLED_TOOLS = " sverklo_forget , sverklo_remember ";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result).toHaveLength(2);
+    });
+    it("ignores unknown tool names in the disabled list (no-op)", () => {
+        process.env.SVERKLO_DISABLED_TOOLS = "sverklo_nonexistent,sverklo_search";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result).toHaveLength(3);
+        expect(result.map((t) => t.name)).not.toContain("sverklo_search");
+    });
+});
+describe("applyToolOverrides — combined overrides", () => {
+    beforeEach(() => {
+        for (const key of Object.keys(process.env)) {
+            if (key.startsWith("SVERKLO_TOOL_") || key === "SVERKLO_DISABLED_TOOLS") {
+                delete process.env[key];
+            }
+        }
+        __resetToolOverrideCache();
+    });
+    it("applies description overrides and disable list together", () => {
+        process.env.SVERKLO_TOOL_SEARCH_DESCRIPTION = "custom";
+        process.env.SVERKLO_DISABLED_TOOLS = "sverklo_forget";
+        __resetToolOverrideCache();
+        const result = applyToolOverrides(fixture());
+        expect(result).toHaveLength(3);
+        expect(result.find((t) => t.name === "sverklo_search")?.description).toBe("custom");
+        expect(result.find((t) => t.name === "sverklo_forget")).toBeUndefined();
+    });
+});
+//# sourceMappingURL=tool-overrides.test.js.map

package/dist/src/server/tool-overrides.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-overrides.test.js","sourceRoot":"","sources":["../../../src/server/tool-overrides.test.ts"],"names":[],"mappings":"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"}

package/dist/src/server/tools/context-budget.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/server/tools/context-budget.test.js

@@ -0,0 +1,150 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, writeFileSync, mkdirSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { Indexer } from "../../indexer/indexer.js";
+import { getProjectConfig } from "../../utils/config.js";
+import { handleContext } from "./context.js";
+// Tests for the sverklo_context --budget N repo-map mode (issue #8).
+// These lock in the deterministic-ordering contract (same index +
+// same budget = same output), the budget clamping behavior, and the
+// exclude filter. We build a tiny real project so the tests exercise
+// the actual PageRank + chunk iteration, not a mock.
+describe("handleContext (budget mode)", () => {
+    let tmpRoot;
+    let indexer;
+    beforeEach(async () => {
+        tmpRoot = mkdtempSync(join(tmpdir(), "sverklo-context-budget-"));
+        mkdirSync(join(tmpRoot, "src"), { recursive: true });
+        mkdirSync(join(tmpRoot, "test"), { recursive: true });
+        // Seed a few files with different sizes so PageRank has something
+        // to differentiate. The exact rankings don't matter — we only
+        // assert that output is stable and contains expected path markers.
+        writeFileSync(join(tmpRoot, "src", "core.ts"), [
+            "export function load() { return 1; }",
+            "export function save() { return 2; }",
+            "export function reset() { return 3; }",
+        ].join("\n"), "utf-8");
+        writeFileSync(join(tmpRoot, "src", "helpers.ts"), [
+            "import { load } from './core';",
+            "export function helper1() { return load(); }",
+            "export function helper2() { return load(); }",
+        ].join("\n"), "utf-8");
+        writeFileSync(join(tmpRoot, "test", "core.test.ts"), [
+            "export function runTests() { return 'all-green'; }",
+            "export function setupSuite() { return {}; }",
+        ].join("\n"), "utf-8");
+        const cfg = getProjectConfig(tmpRoot);
+        indexer = new Indexer(cfg);
+        await indexer.index();
+    });
+    afterEach(() => {
+        try {
+            indexer.close();
+        }
+        catch { }
+        try {
+            rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it("returns a repo-map-shaped response when budget is set", async () => {
+        const out = await handleContext(indexer, { budget: 2000 });
+        expect(out).toContain("# Repo map");
+        expect(out).toContain("Budget: 2000 tokens");
+        expect(out).toContain("PageRank");
+    });
+    it("produces identical output for identical inputs (determinism contract)", async () => {
+        const a = await handleContext(indexer, { budget: 2000 });
+        const b = await handleContext(indexer, { budget: 2000 });
+        expect(a).toBe(b);
+    });
+    it("works without a task (pure PageRank ordering)", async () => {
+        const out = await handleContext(indexer, { budget: 2000 });
+        expect(out).not.toContain("centered on");
+        expect(out).toContain("PageRank");
+    });
+    it("accepts a task parameter and advertises the bias in the header", async () => {
+        const out = await handleContext(indexer, {
+            budget: 2000,
+            task: "understand loading logic",
+        });
+        expect(out).toContain("centered on: understand loading logic");
+        expect(out).toContain("task relevance");
+    });
+    it("respects the exclude filter", async () => {
+        const withTests = await handleContext(indexer, { budget: 4000, exclude: [] });
+        const withoutTests = await handleContext(indexer, {
+            budget: 4000,
+            exclude: ["test"],
+        });
+        // The test file should appear in the unfiltered version but not
+        // in the filtered one.
+        expect(withTests).toContain("core.test.ts");
+        expect(withoutTests).not.toContain("core.test.ts");
+    });
+    it("clamps budgets above the max and emits a warning line", async () => {
+        const out = await handleContext(indexer, { budget: 100_000 });
+        expect(out).toContain("clamped");
+        // The stated budget in the header should be the clamp ceiling,
+        // not the original request.
+        expect(out).toContain("32000");
+    });
+    it("rejects budgets below the minimum with a helpful message", async () => {
+        const out = await handleContext(indexer, { budget: 100 });
+        expect(out).toContain("Budget too small");
+        expect(out).toContain("Minimum");
+    });
+    it("scope filter restricts the map to matching paths", async () => {
+        const out = await handleContext(indexer, { budget: 2000, scope: "src/" });
+        expect(out).toContain("src/");
+        expect(out).not.toContain("test/core.test.ts");
+    });
+    it("reports a footer with rendered count and remaining-files hint", async () => {
+        const out = await handleContext(indexer, { budget: 2000 });
+        // "Rendered N of M files" footer is always present when the mode
+        // ran to completion.
+        expect(out).toMatch(/Rendered \d+ of \d+ files/);
+    });
+    it("falls back gracefully when task search fails internally", async () => {
+        // Even if search blows up, the map must still render in pure
+        // PageRank mode rather than returning an error. We can't easily
+        // force hybridSearch to throw here without monkey-patching, so
+        // we assert the contract indirectly: a task with zero meaningful
+        // matches should still produce a valid map.
+        const out = await handleContext(indexer, {
+            budget: 2000,
+            task: "zzzzz totally unrelated gibberish query",
+        });
+        expect(out).toContain("# Repo map");
+        expect(out).toMatch(/Rendered \d+ of \d+ files/);
+    });
+});
+// Separate suite: error / missing-task behavior when budget is NOT set.
+describe("handleContext (non-budget mode)", () => {
+    let tmpRoot;
+    let indexer;
+    beforeEach(async () => {
+        tmpRoot = mkdtempSync(join(tmpdir(), "sverklo-context-nobudget-"));
+        mkdirSync(join(tmpRoot, "src"), { recursive: true });
+        writeFileSync(join(tmpRoot, "src", "a.ts"), "export const a = 1;\n", "utf-8");
+        const cfg = getProjectConfig(tmpRoot);
+        indexer = new Indexer(cfg);
+        await indexer.index();
+    });
+    afterEach(() => {
+        try {
+            indexer.close();
+        }
+        catch { }
+        try {
+            rmSync(tmpRoot, { recursive: true, force: true });
+        }
+        catch { }
+    });
+    it("still requires a task when budget is not set", async () => {
+        const out = await handleContext(indexer, {});
+        expect(out).toContain("required");
+    });
+});
+//# sourceMappingURL=context-budget.test.js.map

package/dist/src/server/tools/context-budget.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context-budget.test.js","sourceRoot":"","sources":["../../../../src/server/tools/context-budget.test.ts"],"names":[],"mappings":"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"}

package/dist/src/server/tools/context.d.ts

@@ -18,8 +18,18 @@ export declare const contextTool: {
                 type: string;
                 description: string;
             };
+            budget: {
+                type: string;
+                description: string;
+            };
+            exclude: {
+                type: string;
+                items: {
+                    type: string;
+                };
+                description: string;
+            };
         };
-        required: string[];
     };
 };
 export declare function handleContext(indexer: Indexer, args: Record<string, unknown>): Promise<string>;

package/dist/src/server/tools/context.js

@@ -12,39 +12,65 @@
 //   full    — normal + dependency neighbours of top results
 import { hybridSearch } from "../../search/hybrid-search.js";
 import { handleRecall } from "./recall.js";
+import { estimateTokens } from "../../utils/tokens.js";
 export const contextTool = {
     name: "sverklo_context",
     description: "Umbrella context bundler. Give a task description and get a single curated bundle: " +
         "codebase overview header, semantically relevant code, related symbols, and matching " +
         "saved memories — in one round trip. Use this as the FIRST call when you start working " +
-        "on a new task and want to orient quickly. Drill down with the atomic tools (search, " +
-        "lookup, refs, recall) only after this.",
+        "on a new task and want to orient quickly. " +
+        "PASS `budget` for a PageRank-pruned repo map fit to a token budget — the ideal way " +
+        "to give an agent a complete mental model of an unfamiliar codebase in one call.",
     inputSchema: {
         type: "object",
         properties: {
             task: {
                 type: "string",
-                description: "Free-form description of what you're trying to do, e.g. 'add rate limiting to the login endpoint' or 'understand how billing webhooks are processed'.",
+                description: "Free-form description of what you're trying to do, e.g. 'add rate limiting to the login endpoint' or 'understand how billing webhooks are processed'. When `budget` is set and no task is given, returns a pure PageRank-ordered repo map.",
             },
             detail_level: {
                 type: "string",
                 enum: ["minimal", "normal", "full"],
-                description: "How much to return. minimal=fast/cheap (good for snap orientation); normal=balanced (default); full=adds dependency neighbours.",
+                description: "How much to return. minimal=fast/cheap (good for snap orientation); normal=balanced (default); full=adds dependency neighbours. Ignored when `budget` is set.",
             },
             scope: {
                 type: "string",
                 description: "Optional path prefix to constrain the search (e.g. 'src/api/').",
             },
+            budget: {
+                type: "number",
+                description: "When set, returns a PageRank-pruned repo map greedily filled to this token budget (inspired by aider's repo-map). Files are ordered by PageRank importance, optionally biased toward `task`. Only symbol signatures are rendered — use the atomic tools for full bodies. Typical values: 4000 (snap map), 8000 (full mental model), 16000 (deep context).",
+            },
+            exclude: {
+                type: "array",
+                items: { type: "string" },
+                description: "Path substrings to exclude from the repo map (e.g. ['test', 'migration']).",
+            },
         },
-        required: ["task"],
     },
 };
 export async function handleContext(indexer, args) {
-    const task = args.task?.trim();
-    if (!task)
-        return "Error: `task` is required.";
+    const task = args.task?.trim() || "";
     const detail = (args.detail_level || "normal");
     const scope = args.scope;
+    const budget = args.budget;
+    const exclude = args.exclude || [];
+    // ── Budget mode: PageRank-pruned repo map (issue #8) ──────────────
+    // When budget is set, we skip the standard search-based bundler and
+    // instead build a dense structural map greedily filled to the target
+    // token count. This is the "give the agent a complete mental model
+    // of an unfamiliar repo in one call" path — aider's repo-map pattern.
+    if (typeof budget === "number" && budget > 0) {
+        return await buildPrunedRepoMap(indexer, {
+            budget,
+            task,
+            scope,
+            exclude,
+        });
+    }
+    if (!task) {
+        return "Error: `task` is required (unless you pass `budget` for a pure repo map).";
+    }
     const searchLimit = detail === "minimal" ? 3 : detail === "normal" ? 5 : 8;
     const memoryLimit = detail === "minimal" ? 2 : 5;
     const tokenBudget = detail === "minimal" ? 1500 : detail === "normal" ? 3000 : 5000;
@@ -159,4 +185,172 @@ export async function handleContext(indexer, args) {
     }
     return parts.join("\n");
 }
+// ─────────────────────────────────────────────────────────────────────
+// Issue #8 — PageRank-pruned repo map fit to a token budget.
+//
+// Design (mirrors aider's repo-map, adapted to sverklo's symbol graph):
+//
+//   1. Rank files by PageRank DESC.
+//   2. If a task was provided, run a semantic search and upweight files
+//      that contain strong matches. This lets the map center on the
+//      subsystem the user is working in, instead of always the global
+//      hub files.
+//   3. Walk files in ranked order; for each, render signatures of its
+//      most important symbols (also ordered by PageRank proxy).
+//   4. Greedily fill the budget. Stop the instant adding the next file
+//      would exceed the cap. The output is deterministic given the
+//      same index state and budget — important for caching.
+//
+// Determinism note: we break PageRank ties by file path to keep output
+// stable across runs of the same input. This matters for caching and
+// snapshot-testing downstream.
+// ─────────────────────────────────────────────────────────────────────
+// Upper bound on the repo-map budget. Anything above 32k tokens is
+// almost certainly a mistake — the resulting map won't fit in any
+// current model's context window and the wall-clock cost of walking
+// every file climbs linearly. We cap and emit a warning in the
+// output so the caller knows we trimmed.
+const MAX_REPO_MAP_BUDGET = 32000;
+const MIN_REPO_MAP_BUDGET = 500;
+async function buildPrunedRepoMap(indexer, opts) {
+    let { budget } = opts;
+    const { task, scope, exclude } = opts;
+    // Clamp the budget to sane bounds. Sub-500 can't even fit a header
+    // + one file meaningfully; over 32k is nearly always unintentional.
+    let budgetWarning = "";
+    if (budget > MAX_REPO_MAP_BUDGET) {
+        budgetWarning = `_Budget ${budget} exceeded max ${MAX_REPO_MAP_BUDGET} — clamped. For larger maps, use multiple scoped calls._\n\n`;
+        budget = MAX_REPO_MAP_BUDGET;
+    }
+    else if (budget < MIN_REPO_MAP_BUDGET) {
+        return (`Budget too small: ${budget}. Minimum is ${MIN_REPO_MAP_BUDGET} tokens — ` +
+            `below that the repo map can't fit a useful number of files. ` +
+            `Try \`budget: ${MIN_REPO_MAP_BUDGET}\` for a snap view.`);
+    }
+    // Pull all files sorted by PageRank. file_store.getAll() already
+    // returns them in pagerank DESC order — see storage/file-store.ts.
+    let files = indexer.fileStore.getAll();
+    // Apply scope prefix and exclude substrings.
+    if (scope) {
+        files = files.filter((f) => f.path.startsWith(scope));
+    }
+    if (exclude.length > 0) {
+        files = files.filter((f) => !exclude.some((ex) => f.path.includes(ex)));
+    }
+    // Task-biased reranking: if the caller gave us a task, run a search
+    // and boost files that contain strong matches. We keep the PageRank
+    // signal as the primary order and only use the task signal as a
+    // tiebreaker / boost — so the output is still dominated by the
+    // structural importance of the codebase, not by query noise.
+    const taskBoost = new Map();
+    if (task) {
+        try {
+            const hits = await hybridSearch(indexer, {
+                query: task,
+                tokenBudget: 50000, // ask for a lot so boost is meaningful
+                scope,
+                type: "any",
+            });
+            // Accumulate score per file across all hits.
+            for (const h of hits) {
+                taskBoost.set(h.chunk.file_id, (taskBoost.get(h.chunk.file_id) || 0) + h.score);
+            }
+        }
+        catch {
+            // Fall back to pure PageRank if search fails — never block the map.
+        }
+    }
+    // Stable ranking: compose PageRank with the task boost, break ties
+    // by path so the same input always produces the same output.
+    const ranked = [...files].sort((a, b) => {
+        const ba = (taskBoost.get(a.id) || 0) * 0.5 + a.pagerank;
+        const bb = (taskBoost.get(b.id) || 0) * 0.5 + b.pagerank;
+        if (bb !== ba)
+            return bb - ba;
+        return a.path.localeCompare(b.path);
+    });
+    // Header first so the caller can still see the budget and ordering
+    // even when the budget is tiny and zero files fit.
+    const parts = [];
+    parts.push(`# Repo map${task ? ` · centered on: ${task}` : ""}${scope ? ` · scope: ${scope}` : ""}`);
+    parts.push(`_Budget: ${budget} tokens · ordered by PageRank${task ? " + task relevance" : ""}._`);
+    if (budgetWarning)
+        parts.push(budgetWarning);
+    parts.push("");
+    // Remaining budget after the header. 10% cushion for the trailing
+    // footer text and any rendering slack. Token estimates are rough —
+    // we use the same estimator as the indexer (chars / 3.5).
+    const headerCost = estimateTokens(parts.join("\n"));
+    let remaining = budget - headerCost - 100;
+    let filesRendered = 0;
+    let filesSkipped = 0;
+    for (const file of ranked) {
+        if (remaining <= 0) {
+            filesSkipped = ranked.length - filesRendered;
+            break;
+        }
+        // Pull the file's symbols. We only render symbol signatures
+        // (cheap) plus the symbol's name and type. Full bodies would
+        // blow the budget instantly — the point of a map is to be a
+        // legend, not the terrain.
+        const chunks = indexer.chunkStore
+            .getByFile(file.id)
+            .filter((c) => c.name);
+        if (chunks.length === 0)
+            continue;
+        // Render the file's entry. Symbols are ordered as they appear in
+        // the file (by start_line). Top-level types/classes come first in
+        // most codebases so this matches how a human skims.
+        const fileHeader = `## \`${file.path}\` · PR ${file.pagerank.toFixed(3)} · ${file.language || "?"}`;
+        const fileLines = [fileHeader];
+        // Soft cap on symbols-per-file so one massive file doesn't eat the
+        // whole budget. Files with >40 symbols render as "+ N more".
+        const CAP_PER_FILE = 40;
+        const shown = chunks.slice(0, CAP_PER_FILE);
+        for (const c of shown) {
+            const sig = c.signature ? c.signature.trim() : `${c.type} ${c.name}`;
+            // Keep each line short — the map should scan like an outline.
+            const truncated = sig.length > 110 ? sig.slice(0, 107) + "..." : sig;
+            fileLines.push(`- ${truncated}`);
+        }
+        if (chunks.length > CAP_PER_FILE) {
+            fileLines.push(`- _...and ${chunks.length - CAP_PER_FILE} more symbols_`);
+        }
+        const entry = fileLines.join("\n") + "\n";
+        const cost = estimateTokens(entry);
+        // If a single file's entry exceeds the remaining budget, render a
+        // truncated version (just the header + symbol count) so the caller
+        // still knows the file exists. Never render a partial entry with
+        // half its symbols cut off — that's confusing.
+        if (cost > remaining) {
+            const fallback = `## \`${file.path}\` · PR ${file.pagerank.toFixed(3)}\n` +
+                `- _${chunks.length} symbols (budget exhausted — use sverklo_lookup for details)_\n`;
+            const fallbackCost = estimateTokens(fallback);
+            if (fallbackCost <= remaining) {
+                parts.push(fallback);
+                remaining -= fallbackCost;
+                filesRendered++;
+            }
+            else {
+                filesSkipped = ranked.length - filesRendered;
+                break;
+            }
+        }
+        else {
+            parts.push(entry);
+            remaining -= cost;
+            filesRendered++;
+        }
+    }
+    // Footer
+    parts.push("");
+    parts.push(`_Rendered ${filesRendered} of ${ranked.length} files` +
+        (filesSkipped > 0
+            ? ` (${filesSkipped} skipped — budget exhausted; raise \`budget\` to see more)_`
+            : "_"));
+    if (filesRendered > 0) {
+        parts.push("_Use `sverklo_lookup name:<symbol>` or `sverklo_search query:<...>` to drill into any symbol._");
+    }
+    return parts.join("\n");
+}
 //# sourceMappingURL=context.js.map

package/dist/src/server/tools/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../src/server/tools/context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../../src/server/tools/context.ts"],"names":[],"mappings":"AAAA,6EAA6E;AAC7E,EAAE;AACF,8EAA8E;AAC9E,8EAA8E;AAC9E,wEAAwE;AACxE,2EAA2E;AAC3E,8CAA8C;AAC9C,EAAE;AACF,kCAAkC;AAClC,mEAAmE;AACnE,kFAAkF;AAClF,4DAA4D;AAG5D,OAAO,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAC7D,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC3C,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAGvD,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,IAAI,EAAE,iBAAiB;IACvB,WAAW,EACT,qFAAqF;QACrF,sFAAsF;QACtF,wFAAwF;QACxF,4CAA4C;QAC5C,qFAAqF;QACrF,iFAAiF;IACnF,WAAW,EAAE;QACX,IAAI,EAAE,QAAiB;QACvB,UAAU,EAAE;YACV,IAAI,EAAE;gBACJ,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,4OAA4O;aAC/O;YACD,YAAY,EAAE;gBACZ,IAAI,EAAE,QAAQ;gBACd,IAAI,EAAE,CAAC,SAAS,EAAE,QAAQ,EAAE,MAAM,CAAC;gBACnC,WAAW,EACT,+JAA+J;aAClK;YACD,KAAK,EAAE;gBACL,IAAI,EAAE,QAAQ;gBACd,WAAW,EAAE,iEAAiE;aAC/E;YACD,MAAM,EAAE;gBACN,IAAI,EAAE,QAAQ;gBACd,WAAW,EACT,2VAA2V;aAC9V;YACD,OAAO,EAAE;gBACP,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;gBACzB,WAAW,EAAE,4EAA4E;aAC1F;SACF;KACF;CACF,CAAC;AAIF,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAgB,EAChB,IAA6B;IAE7B,MAAM,IAAI,GAAI,IAAI,CAAC,IAAe,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;IACjD,MAAM,MAAM,GAAG,CAAE,IAAI,CAAC,YAAuB,IAAI,QAAQ,CAAgB,CAAC;IAC1E,MAAM,KAAK,GAAG,IAAI,CAAC,KAA2B,CAAC;IAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,MAA4B,CAAC;IACjD,MAAM,OAAO,GAAI,IAAI,CAAC,OAAgC,IAAI,EAAE,CAAC;IAE7D,qEAAqE;IACrE,oEAAoE;IACpE,qEAAqE;IACrE,mEAAmE;IACnE,sEAAsE;IACtE,IAAI,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,GAAG,CAAC,EAAE,CAAC;QAC7C,OAAO,MAAM,kBAAkB,CAAC,OAAO,EAAE;YACvC,MAAM;YACN,IAAI;YACJ,KAAK;YACL,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IAED,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO,2EAA2E,CAAC;IACrF,CAAC;IAED,MAAM,WAAW,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC3E,MAAM,WAAW,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IACjD,MAAM,WAAW,GAAG,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC;IAEpF,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CAAC,kBAAkB,IAAI,EAAE,CAAC,CAAC;IACrC,KAAK,CAAC,IAAI,CAAC,YAAY,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,YAAY,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACrE,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,sEAAsE;IACtE,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;IACnC,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC1B,KAAK,CAAC,IAAI,CACR,GAAG,MAAM,CAAC,WAAW,MAAM,MAAM,CAAC,SAAS,YAAY,MAAM,CAAC,UAAU,cAAc,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,GAAG,EAAE,CACvI,CAAC;IAEF,qEAAqE;IACrE,MAAM,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/E,IAAI,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC5B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACf,KAAK,CAAC,IAAI,CAAC,uCAAuC,CAAC,CAAC;QACpD,KAAK,MAAM,CAAC,IAAI,YAAY,EAAE,CAAC;YAC7B,MAAM,KAAK,GAAG,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,QAAQ,IAAI,KAAK,IAAI,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC;QACvD,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,sEAAsE;IACtE,MAAM,aAAa,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE;QAChD,KAAK,EAAE,IAAI;QACX,WAAW;QACX,KAAK;QACL,IAAI,EAAE,KAAK;KACZ,CAAC,CAAC;IACH,MAAM,UAAU,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC;IAEvD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,KAAK,CAAC,IAAI,CAAC,0BAA0B,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC;QAC3D,MAAM,SAAS,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5E,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;YAC3B,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;YAC5C,MAAM,IAAI,GAAG,IAAI,EAAE,IAAI,IAAI,SAAS,CAAC;YACrC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,QAAQ,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3D,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI;gBACxB,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,CAAC,KAAK,CAAC,IAAI,IAAI;gBACvC,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACtB,KAAK,CAAC,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,CAAC,KAAK,CAAC,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC;YAClE,IAAI,CAAC,CAAC,KAAK,CAAC,SAAS,EAAE,CAAC;gBACtB,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;YACzD,CAAC;QACH,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAEf,oEAAoE;QACpE,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;YACtB,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;YAC/B,MAAM,UAAU,GAAmE,EAAE,CAAC;YACtF,KAAK,MAAM,CAAC,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;gBACvC,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC;gBAC/B,IAAI,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC;oBAAE,SAAS;gBAC/B,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACjB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;gBACnC,IAAI,CAAC,IAAI;oBAAE,SAAS;gBAEpB,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;oBACrE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;oBAClD,IAAI,MAAM,EAAE,CAAC;wBACX,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,EAAE,EAAE,MAAM,CAAC,IAAI,EAAE,GAAG,EAAE,SAAS,EAAE,CAAC,CAAC;oBACxE,CAAC;gBACH,CAAC;gBACD,KAAK,MAAM,IAAI,IAAI,OAAO,CAAC,UAAU,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC;oBACvE,MAAM,MAAM,GAAG,SAAS,CAAC,GAAG,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;oBAClD,IAAI,MAAM,EAAE,CAAC;wBACX,UAAU,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,IAAI,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;oBAC5E,CAAC;gBACH,CAAC;YACH,CAAC;YACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;gBAC1B,KAAK,CAAC,IAAI,CAAC,0BAA0B,CAAC,CAAC;gBACvC,KAAK,MAAM,CAAC,IAAI,UAAU,EAAE,CAAC;oBAC3B,MAAM,KAAK,GAAG,CAAC,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC;oBAC9C,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;gBACrD,CAAC;gBACD,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;YACjB,CAAC;QACH,CAAC;IACH,CAAC;SAAM,CAAC;QACN,KAAK,CAAC,IAAI,CAAC,mCAAmC,IAAI,8EAA8E,CAAC,CAAC;QAClI,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACjB,CAAC;IAED,qEAAqE;IACrE,4EAA4E;IAC5E,oFAAoF;IACpF,IAAI,CAAC;QACH,MAAM,SAAS,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,WAAW,EAAE,CAAC,CAAC;QACnF,IAAI,SAAS,IAAI,SAAS,KAAK,oBAAoB,EAAE,CAAC;YACpD,KAAK,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAClC,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC;YAC7B,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QACjB,CAAC;IACH,CAAC;IAAC,MAAM,CAAC;QACP,6DAA6D;IAC/D,CAAC;IAED,sEAAsE;IACtE,KAAK,CAAC,IAAI,CAAC,mBAAmB,CAAC,CAAC;IAChC,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC1B,MAAM,GAAG,GAAG,UAAU,CAAC,CAAC,CAAC,CAAC;QAC1B,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YACnB,KAAK,CAAC,IAAI,CAAC,4BAA4B,GAAG,CAAC,KAAK,CAAC,IAAI,8CAA8C,CAAC,CAAC;YACrG,KAAK,CAAC,IAAI,CAAC,4BAA4B,GAAG,CAAC,KAAK,CAAC,IAAI,6BAA6B,CAAC,CAAC;QACtF,CAAC;IACH,CAAC;IACD,KAAK,CAAC,IAAI,CAAC,4EAA4E,CAAC,CAAC;IACzF,IAAI,MAAM,KAAK,MAAM,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,yEAAyE,CAAC,CAAC;IACxF,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC;AAED,wEAAwE;AACxE,6DAA6D;AAC7D,EAAE;AACF,wEAAwE;AACxE,EAAE;AACF,oCAAoC;AACpC,wEAAwE;AACxE,oEAAoE;AACpE,sEAAsE;AACtE,kBAAkB;AAClB,sEAAsE;AACtE,gEAAgE;AAChE,uEAAuE;AACvE,mEAAmE;AACnE,4DAA4D;AAC5D,EAAE;AACF,uEAAuE;AACvE,qEAAqE;AACrE,+BAA+B;AAC/B,wEAAwE;AAExE,mEAAmE;AACnE,kEAAkE;AAClE,oEAAoE;AACpE,+DAA+D;AAC/D,yCAAyC;AACzC,MAAM,mBAAmB,GAAG,KAAK,CAAC;AAClC,MAAM,mBAAmB,GAAG,GAAG,CAAC;AAEhC,KAAK,UAAU,kBAAkB,CAC/B,OAAgB,EAChB,IAKC;IAED,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IACtB,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,IAAI,CAAC;IAEtC,mEAAmE;IACnE,oEAAoE;IACpE,IAAI,aAAa,GAAG,EAAE,CAAC;IACvB,IAAI,MAAM,GAAG,mBAAmB,EAAE,CAAC;QACjC,aAAa,GAAG,WAAW,MAAM,iBAAiB,mBAAmB,8DAA8D,CAAC;QACpI,MAAM,GAAG,mBAAmB,CAAC;IAC/B,CAAC;SAAM,IAAI,MAAM,GAAG,mBAAmB,EAAE,CAAC;QACxC,OAAO,CACL,qBAAqB,MAAM,gBAAgB,mBAAmB,YAAY;YAC1E,8DAA8D;YAC9D,iBAAiB,mBAAmB,qBAAqB,CAC1D,CAAC;IACJ,CAAC;IAED,iEAAiE;IACjE,mEAAmE;IACnE,IAAI,KAAK,GAAiB,OAAO,CAAC,SAAS,CAAC,MAAM,EAAE,CAAC;IAErD,6CAA6C;IAC7C,IAAI,KAAK,EAAE,CAAC;QACV,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;IACxD,CAAC;IACD,IAAI,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACvB,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;IAC1E,CAAC;IAED,oEAAoE;IACpE,oEAAoE;IACpE,gEAAgE;IAChE,+DAA+D;IAC/D,6DAA6D;IAC7D,MAAM,SAAS,GAAG,IAAI,GAAG,EAAkB,CAAC;IAC5C,IAAI,IAAI,EAAE,CAAC;QACT,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,YAAY,CAAC,OAAO,EAAE;gBACvC,KAAK,EAAE,IAAI;gBACX,WAAW,EAAE,KAAK,EAAE,uCAAuC;gBAC3D,KAAK;gBACL,IAAI,EAAE,KAAK;aACZ,CAAC,CAAC;YACH,6CAA6C;YAC7C,KAAK,MAAM,CAAC,IAAI,IAAI,EAAE,CAAC;gBACrB,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,EAAE,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC;YAClF,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;IACH,CAAC;IAED,mEAAmE;IACnE,6DAA6D;IAC7D,MAAM,MAAM,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE;QACtC,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QACzD,MAAM,EAAE,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,QAAQ,CAAC;QACzD,IAAI,EAAE,KAAK,EAAE;YAAE,OAAO,EAAE,GAAG,EAAE,CAAC;QAC9B,OAAO,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;IACtC,CAAC,CAAC,CAAC;IAEH,mEAAmE;IACnE,mDAAmD;IACnD,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,CAAC,IAAI,CACR,aAAa,IAAI,CAAC,CAAC,CAAC,mBAAmB,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,CAAC,CAAC,CAAC,aAAa,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,CACzF,CAAC;IACF,KAAK,CAAC,IAAI,CACR,YAAY,MAAM,gCAAgC,IAAI,CAAC,CAAC,CAAC,mBAAmB,CAAC,CAAC,CAAC,EAAE,IAAI,CACtF,CAAC;IACF,IAAI,aAAa;QAAE,KAAK,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAEf,kEAAkE;IAClE,mEAAmE;IACnE,0DAA0D;IAC1D,MAAM,UAAU,GAAG,cAAc,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IACpD,IAAI,SAAS,GAAG,MAAM,GAAG,UAAU,GAAG,GAAG,CAAC;IAE1C,IAAI,aAAa,GAAG,CAAC,CAAC;IACtB,IAAI,YAAY,GAAG,CAAC,CAAC;IAErB,KAAK,MAAM,IAAI,IAAI,MAAM,EAAE,CAAC;QAC1B,IAAI,SAAS,IAAI,CAAC,EAAE,CAAC;YACnB,YAAY,GAAG,MAAM,CAAC,MAAM,GAAG,aAAa,CAAC;YAC7C,MAAM;QACR,CAAC;QAED,4DAA4D;QAC5D,6DAA6D;QAC7D,4DAA4D;QAC5D,2BAA2B;QAC3B,MAAM,MAAM,GAAgB,OAAO,CAAC,UAAU;aAC3C,SAAS,CAAC,IAAI,CAAC,EAAE,CAAC;aAClB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC;QAEzB,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,SAAS;QAElC,iEAAiE;QACjE,kEAAkE;QAClE,oDAAoD;QACpD,MAAM,UAAU,GAAG,QAAQ,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,QAAQ,IAAI,GAAG,EAAE,CAAC;QACpG,MAAM,SAAS,GAAa,CAAC,UAAU,CAAC,CAAC;QAEzC,mEAAmE;QACnE,6DAA6D;QAC7D,MAAM,YAAY,GAAG,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC;QAE5C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,MAAM,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;YACrE,8DAA8D;YAC9D,MAAM,SAAS,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;YACrE,SAAS,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,CAAC,CAAC;QACnC,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,GAAG,YAAY,EAAE,CAAC;YACjC,SAAS,CAAC,IAAI,CAAC,aAAa,MAAM,CAAC,MAAM,GAAG,YAAY,gBAAgB,CAAC,CAAC;QAC5E,CAAC;QAED,MAAM,KAAK,GAAG,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC1C,MAAM,IAAI,GAAG,cAAc,CAAC,KAAK,CAAC,CAAC;QAEnC,kEAAkE;QAClE,mEAAmE;QACnE,iEAAiE;QACjE,+CAA+C;QAC/C,IAAI,IAAI,GAAG,SAAS,EAAE,CAAC;YACrB,MAAM,QAAQ,GACZ,QAAQ,IAAI,CAAC,IAAI,WAAW,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI;gBACxD,MAAM,MAAM,CAAC,MAAM,iEAAiE,CAAC;YACvF,MAAM,YAAY,GAAG,cAAc,CAAC,QAAQ,CAAC,CAAC;YAC9C,IAAI,YAAY,IAAI,SAAS,EAAE,CAAC;gBAC9B,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;gBACrB,SAAS,IAAI,YAAY,CAAC;gBAC1B,aAAa,EAAE,CAAC;YAClB,CAAC;iBAAM,CAAC;gBACN,YAAY,GAAG,MAAM,CAAC,MAAM,GAAG,aAAa,CAAC;gBAC7C,MAAM;YACR,CAAC;QACH,CAAC;aAAM,CAAC;YACN,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YAClB,SAAS,IAAI,IAAI,CAAC;YAClB,aAAa,EAAE,CAAC;QAClB,CAAC;IACH,CAAC;IAED,SAAS;IACT,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACf,KAAK,CAAC,IAAI,CACR,aAAa,aAAa,OAAO,MAAM,CAAC,MAAM,QAAQ;QACpD,CAAC,YAAY,GAAG,CAAC;YACf,CAAC,CAAC,KAAK,YAAY,6DAA6D;YAChF,CAAC,CAAC,GAAG,CAAC,CACX,CAAC;IACF,IAAI,aAAa,GAAG,CAAC,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CACR,gGAAgG,CACjG,CAAC;IACJ,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC1B,CAAC"}

package/dist/src/server/tools/diff-heuristics.d.ts

@@ -0,0 +1,28 @@
+export interface DiffHunk {
+    filePath: string;
+    oldStart: number;
+    newStart: number;
+    /** Every line in the hunk, including context. Each entry is "+ ", "- ", " " followed by content. */
+    lines: string[];
+}
+export interface HeuristicFinding {
+    heuristic: string;
+    severity: "high" | "medium" | "low";
+    file: string;
+    line: number;
+    snippet: string;
+    message: string;
+}
+export declare function findUnguardedStreamCalls(hunks: DiffHunk[]): HeuristicFinding[];
+export declare const ALL_HEURISTICS: ((hunks: DiffHunk[]) => HeuristicFinding[])[];
+export declare function runAllHeuristics(hunks: DiffHunk[]): HeuristicFinding[];
+/**
+ * Parse a unified-diff string (output of `git diff -U5 ref`) into hunks.
+ * Very permissive — anything that doesn't match the expected header is
+ * skipped rather than raising.
+ */
+export declare function parseUnifiedDiff(diffText: string): DiffHunk[];
+/**
+ * Convenience: pull a unified diff from git and parse it.
+ */
+export declare function getDiffHunks(rootPath: string, ref: string): DiffHunk[];