codedeep-mcp 0.1.0

package/dist/tools/get-context.js

@@ -0,0 +1,370 @@
+import { isCallerOf, isClassMember, } from '../indexer/code-index.js';
+import { errMsg } from '../logger.js';
+import { classNameFromFqn } from '../types.js';
+import { BEHAVIORAL_TAG, MODULE_LEVEL, NAME_MATCH_HEADER_QUALIFIER, NAME_MATCH_TAG, STRUCTURAL_TAG, displaySignature, formatComplexity, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, safeReadIndexedFile, sectionOrEmpty, sectionOrNone, textResponse, topCoChangePartners, } from './common.js';
+const DEFAULT_MAX_TOKENS = 3000;
+const SUGGEST_LIMIT = 5;
+// `exported_by` is intentionally absent: the TS extractor skips re-export
+// statements (`export { x } from './y'`), so any "exported by" listing in
+// Phase 1a would only surface coincidentally same-named exports from
+// unrelated files. The section returns when re-export edges land.
+// `co_changes` and `git` sit last: they render at the end and are the
+// first casualties under max_tokens pressure (enrichment, not core).
+const ALL_SECTIONS = ['body', 'callers', 'callees', 'coupling', 'imports', 'co_changes', 'git'];
+function truncationNote(at, maxTokens) {
+    return `(Sections from \`${at}\` onward omitted to stay within max_tokens=${maxTokens}.)`;
+}
+async function renderBudgeted(header, items, include, maxTokens, neverDrop) {
+    const blocks = [header];
+    let used = estimate(header);
+    let truncatedAt = null;
+    for (const item of items) {
+        if (!include.has(item.includeKey))
+            continue;
+        // Once the budget is spent, a cheap peek avoids rendering work whose
+        // output would be discarded: known-empty sections skip silently,
+        // known non-empty ones become the truncation point without paying
+        // their render. Sections without a peek (recent-changes subprocess)
+        // still render below so the note stays honest.
+        if (item.includeKey !== neverDrop && used >= maxTokens) {
+            const peek = item.peekNonEmpty?.();
+            if (peek === false)
+                continue;
+            if (peek === true) {
+                truncatedAt = item.name;
+                break;
+            }
+        }
+        // Render BEFORE deciding truncation: a section that renders empty
+        // (e.g. git sections outside a repo) is silently elided either way,
+        // so the truncation note can never name it and promise content a
+        // larger max_tokens would not reveal.
+        const text = await item.render();
+        if (!text)
+            continue;
+        const cost = estimate(text);
+        if (item.includeKey !== neverDrop && used + cost > maxTokens) {
+            truncatedAt = item.name;
+            break;
+        }
+        blocks.push(text);
+        used += cost;
+    }
+    if (truncatedAt)
+        blocks.push(truncationNote(truncatedAt, maxTokens));
+    return blocks.join('\n\n');
+}
+export async function runGetContext(args, deps) {
+    try {
+        const file = normalizeFilePath(args.file, deps.config.projectRoot);
+        if (file === null) {
+            return textResponse(`Error: file "${args.file}" is outside the project root.`);
+        }
+        const include = parseInclude(args.include);
+        const maxTokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
+        const banner = readinessBanner(deps.indexer.ready);
+        if (args.symbol !== undefined) {
+            const trimmed = args.symbol.trim();
+            if (trimmed.length === 0) {
+                return textResponse('Error: symbol must be non-empty.');
+            }
+            const body = await renderSymbolMode(file, trimmed, args.line, include, maxTokens, deps);
+            return textResponse(banner + body);
+        }
+        return textResponse(banner + (await renderFileMode(file, include, maxTokens, deps)));
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function parseInclude(input) {
+    if (!input)
+        return new Set(ALL_SECTIONS);
+    const set = new Set();
+    for (const s of input) {
+        const lower = s.toLowerCase();
+        if (ALL_SECTIONS.includes(lower)) {
+            set.add(lower);
+        }
+    }
+    return set;
+}
+async function renderSymbolMode(file, name, line, include, maxTokens, deps) {
+    const candidates = deps.index
+        .getSymbolsInFile(file)
+        .filter((s) => s.name === name);
+    if (candidates.length === 0) {
+        const suggestions = deps.index.suggest(name, SUGGEST_LIMIT, undefined, file);
+        return renderNoSymbol(name, file, suggestions);
+    }
+    let target;
+    if (candidates.length > 1) {
+        if (line === undefined) {
+            return renderAmbiguous(name, file, candidates);
+        }
+        target = pickByLine(candidates, line);
+    }
+    else {
+        target = candidates[0];
+    }
+    return renderSymbolBlock(target, file, include, maxTokens, deps);
+}
+function renderNoSymbol(name, file, suggestions) {
+    return [
+        `No symbol '${name}' found in ${file}.`,
+        ...renderSuggestions(suggestions),
+    ].join('\n');
+}
+async function renderSymbolBlock(target, file, include, maxTokens, deps) {
+    const headerLines = [];
+    const exportedTag = target.exported ? ' | exported' : '';
+    headerLines.push(`${target.file}:${target.startLine}-${target.endLine} | ${target.kind}${exportedTag}`);
+    if (target.signature)
+        headerLines.push(target.signature);
+    if (target.doc && target.doc.length > 0)
+        headerLines.push(target.doc);
+    const header = headerLines.join('\n');
+    // `body` is the highest-priority section and is never dropped to fit budget.
+    const items = [
+        {
+            name: 'body',
+            includeKey: 'body',
+            render: () => renderBody(target, deps.config),
+        },
+        {
+            name: 'callers',
+            includeKey: 'callers',
+            render: () => renderCallerEdges(deps.index.getCallerEdges(target.id)),
+            peekNonEmpty: () => true, // sectionOrNone renders "(none)"
+        },
+        {
+            name: 'callees',
+            includeKey: 'callees',
+            render: () => renderCalleeEdges(deps.index.getCallees(target.id)),
+            peekNonEmpty: () => true,
+        },
+        {
+            name: 'coupling',
+            includeKey: 'coupling',
+            render: () => renderCoupling(target, deps.index),
+            peekNonEmpty: () => true,
+        },
+        {
+            name: 'imports',
+            includeKey: 'imports',
+            render: () => renderImports(file, deps.index),
+            peekNonEmpty: () => deps.index.getImports(file).length > 0,
+        },
+        ...gitSectionItems(target.file, deps),
+    ];
+    return renderBudgeted(header, items, include, maxTokens, 'body');
+}
+// The two git sections are identical in both modes and always trail the
+// list (first to drop under budget pressure).
+function gitSectionItems(file, deps) {
+    return [
+        {
+            name: 'co-change partners',
+            includeKey: 'co_changes',
+            render: () => renderCoChanges(file, deps.index),
+            peekNonEmpty: () => deps.index.getCoChanges(file).length > 0,
+        },
+        {
+            name: 'recent changes',
+            includeKey: 'git',
+            render: () => renderRecentChanges(file, deps.git),
+        },
+    ];
+}
+function renderCoChanges(file, index) {
+    const rows = topCoChangePartners(index.getCoChanges(file), file);
+    return sectionOrEmpty(`### Co-change Partners (${rows.length} behavioral)`, rows.map((r) => `- ${r.partner}  ${r.pct}% confidence (${r.shared} shared ${plural('commit', r.shared)})`));
+}
+// Defensive try/catch at the tool boundary: GitService promises not to
+// throw, but a git failure must never turn a get_context call into an
+// in-band "Error:" response — the section just vanishes.
+async function renderRecentChanges(file, git) {
+    let commits;
+    try {
+        commits = await git.recentCommits(file);
+    }
+    catch {
+        return '';
+    }
+    return sectionOrEmpty(`### Recent Changes ${BEHAVIORAL_TAG}`, commits.map((c) => `- ${c.date} ${c.hash} "${c.subject}"`));
+}
+async function renderBody(target, config) {
+    let content;
+    try {
+        content = await safeReadIndexedFile(target.file, config);
+    }
+    catch (err) {
+        return `### Body\n(unable to read ${target.file}: ${errMsg(err)})`;
+    }
+    const lines = content.split('\n');
+    const start = Math.max(0, target.startLine - 1);
+    const end = Math.min(lines.length, target.endLine);
+    // Strip the trailing CR of each CRLF pair so a Windows-authored source file
+    // doesn't leak a stray '\r' onto every rendered body line (the same class of
+    // bug fixed for search_structure's snippet renderer). The split stays on
+    // '\n' to keep line indices aligned with tree-sitter's row numbering, which
+    // treats '\r\n' as a single row — so only a trailing '\r' can remain.
+    const slice = lines
+        .slice(start, end)
+        .map((l) => (l.endsWith('\r') ? l.slice(0, -1) : l))
+        .join('\n');
+    return `### Body\n\`\`\`${target.language}\n${slice}\n\`\`\``;
+}
+function renderCallerEdges(edges) {
+    return sectionOrNone('### Callers', edges.map((e) => {
+        const label = e.symbol ? displaySignature(e.symbol) : MODULE_LEVEL;
+        return `- ${e.file}:${e.line} — ${label} ${STRUCTURAL_TAG}`;
+    }));
+}
+// Per-symbol coupling. The lines sit in different precision tiers, so each
+// carries its own tag rather than a blanket one: fan-out is the id-keyed
+// RESOLVED callee count ([structural]); fan-in (getCallerCount) and the
+// transitive blast radius walk the SAME approximate name-match caller set
+// find_references tags [name match, unverified]. Blast radius uses depth-2
+// (enough to tell a leaf from a hub, cheap for one symbol) and the SAME
+// counting method as `impact` via countDistinctCallers — the method matches,
+// not necessarily the number, since `impact` defaults to a deeper walk; a
+// trailing `+` flags an undercount from ANY cap (breadth/node OR the depth-2
+// wall), so a deep caller chain is never silently truncated here.
+function renderCoupling(target, index) {
+    const fanIn = index.getCallerCount(target.id);
+    const fanOut = index.getFanOut(target.id);
+    const blast = index.getBlastRadius(target.id, { maxDepth: 2 });
+    const cap = blast.truncated ? '+' : '';
+    const blastLine = blast.callers === 0
+        ? `- Blast radius: 0 callers (no upstream call sites in the index) ${NAME_MATCH_TAG}`
+        : `- Blast radius: ${blast.callers}${cap} ${plural('caller', blast.callers)} across ` +
+            `${blast.depths} ${plural('depth', blast.depths)} ` +
+            `(${blast.files} ${plural('file', blast.files)}) ${NAME_MATCH_TAG}`;
+    const complexity = formatComplexity(target);
+    return [
+        '### Coupling',
+        `- Fan-in: ~${fanIn} (callers) ${NAME_MATCH_TAG}`,
+        `- Fan-out: ${fanOut} (callees) ${STRUCTURAL_TAG}`,
+        ...(complexity ? [`- Complexity: ${complexity}`] : []),
+        blastLine,
+    ].join('\n');
+}
+function renderCalleeEdges(edges) {
+    return sectionOrNone('### Callees', edges.map((e) => `- ${e.file}:${e.startLine} — ${displaySignature(e)} ${STRUCTURAL_TAG}`));
+}
+function renderImportLines(imports) {
+    return imports.map((imp) => `- ${imp.sourceModule}: ${formatImportNames(imp)}`);
+}
+function renderImports(file, index) {
+    return sectionOrEmpty('### Imports', renderImportLines(index.getImports(file)));
+}
+function formatImportNames(imp) {
+    return imp.importedNames
+        .map((n) => n.alias && n.alias !== n.name ? `${n.name} as ${n.alias}` : n.name)
+        .join(', ');
+}
+async function renderFileMode(file, include, maxTokens, deps) {
+    const symbols = deps.index.getSymbolsInFile(file);
+    const imports = deps.index.getImports(file);
+    const indexed = deps.index.hasFile(file);
+    let lineCount = 0;
+    if (indexed) {
+        try {
+            const content = await safeReadIndexedFile(file, deps.config);
+            lineCount = content.length === 0 ? 0 : content.split('\n').length;
+        }
+        catch { }
+    }
+    const indexedNote = indexed
+        ? ''
+        : '\n(File is not in the index — likely excluded by config, oversized, or not yet scanned. Use `overview` to see indexed paths.)';
+    const header = `## File: ${file} (${lineCount} ${plural('line', lineCount)}, ${symbols.length} ${plural('symbol', symbols.length)})${indexedNote}`;
+    // Methods/getters/setters inherit `exported` from their enclosing class;
+    // the file-mode outline hides members to avoid duplicating each class's
+    // surface area in the export list — but only when that class is declared
+    // in THIS file. Go/Rust/Swift/Kotlin members routinely live apart from
+    // their type (Go methods in handlers.go beside server.go; Rust impl blocks;
+    // Swift/Kotlin extensions; Kotlin companion objects) — a methods-apart file
+    // would otherwise render as "Exports (none)". The check is purely
+    // name-presence (no per-language allow-list), so TS/Py/Java members (always
+    // co-located with their class) keep their unchanged outlines automatically.
+    const typeNamesInFile = new Set(symbols.filter((s) => !isClassMember(s)).map((s) => s.name));
+    const topLevel = symbols.filter((s) => {
+        const cls = classNameFromFqn(s.fqn);
+        return cls === null || !typeNamesInFile.has(cls);
+    });
+    const exported = topLevel.filter((s) => s.exported);
+    const internal = topLevel.filter((s) => !s.exported);
+    // `body` covers the outline (Exports + Internal); `callees` has no
+    // file-mode analogue. Renderers are lazy so dropped sections don't pay
+    // for caller scans.
+    const items = [
+        {
+            name: 'Exports',
+            includeKey: 'body',
+            render: () => sectionOrNone('### Exports', exported.map(formatFileSymbolLine)),
+        },
+        {
+            name: 'Internal',
+            includeKey: 'body',
+            render: () => sectionOrEmpty('### Internal', internal.map(formatFileSymbolLine)),
+        },
+        {
+            name: 'Imports',
+            includeKey: 'imports',
+            render: () => sectionOrEmpty('### Imports', renderImportLines(imports)),
+            peekNonEmpty: () => imports.length > 0,
+        },
+        {
+            name: "Callers of this file's exports",
+            includeKey: 'callers',
+            render: () => sectionOrNone(`### Callers of this file's exports ${NAME_MATCH_HEADER_QUALIFIER}`, collectExportCallers(exported, deps.index)),
+            // sectionOrNone always renders; peeking spares the reference scan
+            // when the budget is already gone.
+            peekNonEmpty: () => true,
+        },
+        ...gitSectionItems(file, deps),
+    ];
+    return renderBudgeted(header, items, include, maxTokens);
+}
+// Uses `getReferencesByNameOrAlias + isCallerOf` (same data path as
+// find_references) so cross-file callers — the common case for exported
+// symbols — are surfaced. `getCallerEdges` powers symbol-mode's strict
+// [structural] view; this file-mode summary aggregates per-file and
+// benefits from including import-scoped name-match refs. The
+// `[name match, unverified]` tag matches find_references's caller list
+// so consumers know the data is approximate (same precision tier).
+// Member refs to top-level exports (`utils.foo()` through a namespace
+// import) flow in here via getReferencesByNameOrAlias like bare-name
+// refs; the aggregate per-file rows keep the shared name-match tag.
+function collectExportCallers(exportedSyms, index) {
+    const byFile = new Map();
+    for (const exp of exportedSyms) {
+        // Pass targetIsMember so member-ref scoping matches find_references
+        // exactly — the file-mode outline now admits members (a Go method whose
+        // receiver type lives in another file), and a `pkg.Method()` module call
+        // must not be scoped as if it could reach a member.
+        for (const ref of index.getReferencesByNameOrAlias(exp.name, exp.file, isClassMember(exp))) {
+            if (!isCallerOf(ref, exp))
+                continue;
+            let set = byFile.get(ref.file);
+            if (!set) {
+                set = new Set();
+                byFile.set(ref.file, set);
+            }
+            set.add(exp.name);
+        }
+    }
+    const lines = [];
+    for (const [f, names] of byFile) {
+        lines.push(`- ${f} — uses ${[...names].sort().join(', ')}  ${NAME_MATCH_TAG}`);
+    }
+    return lines.sort();
+}
+function formatFileSymbolLine(s) {
+    return `- ${s.name} (${s.kind}, line ${s.startLine}) — ${displaySignature(s)}`;
+}
+function estimate(text) {
+    return Math.ceil(text.length / 4);
+}

package/dist/tools/impact.js

@@ -0,0 +1,218 @@
+import { countDistinctCallers, } from '../indexer/code-index.js';
+import { errMsg } from '../logger.js';
+import { BEHAVIORAL_TAG, MEMBER_MATCH_TAG, MODULE_LEVEL, NAME_MATCH_TAG, STRUCTURAL_TAG, normalizeFilePath, pickByLine, plural, readinessBanner, renderAmbiguous, renderSuggestions, textResponse, topCoChangePartners, } from './common.js';
+const DEFAULT_DEPTH = 3;
+// Past 5 hops the heuristic name-match noise compounds multiplicatively and
+// the tree is mostly candidates; cap is a precision guardrail, not just budget.
+const MAX_DEPTH = 5;
+const DEFAULT_MAX_TOKENS = 3000;
+const SUGGEST_LIMIT = 5;
+export async function runImpact(args, deps) {
+    try {
+        const file = normalizeFilePath(args.file, deps.config.projectRoot);
+        if (file === null) {
+            return textResponse(`Error: file "${args.file}" is outside the project root.`);
+        }
+        const trimmed = args.symbol.trim();
+        if (trimmed.length === 0) {
+            return textResponse('Error: symbol must be non-empty.');
+        }
+        // Computed before any miss so partial first-pass results aren't surfaced
+        // as definitive errors (matches find_references).
+        const banner = readinessBanner(deps.indexer.ready);
+        if (!deps.index.hasFile(file)) {
+            return textResponse(banner + `Error: file '${file}' not found in index.`);
+        }
+        const candidates = deps.index
+            .getSymbolsInFile(file)
+            .filter((s) => s.name === trimmed);
+        if (candidates.length === 0) {
+            const suggestions = deps.index.suggest(trimmed, SUGGEST_LIMIT, undefined, file);
+            return textResponse(banner + renderNoSymbol(trimmed, file, suggestions));
+        }
+        let target;
+        if (candidates.length === 1) {
+            target = candidates[0];
+        }
+        else if (args.line !== undefined) {
+            target = pickByLine(candidates, args.line);
+        }
+        else {
+            return textResponse(banner + renderAmbiguous(trimmed, file, candidates));
+        }
+        // Clamp to [1, MAX_DEPTH]. The MCP schema enforces .positive(), but
+        // runImpact is also invoked directly (tests / internal callers); a
+        // non-positive depth would make maxDepth<=0 and falsely report "0 callers".
+        const depth = Math.max(1, Math.min(args.depth ?? DEFAULT_DEPTH, MAX_DEPTH));
+        const maxTokens = args.max_tokens ?? DEFAULT_MAX_TOKENS;
+        const includeWeak = args.include_weak ?? false;
+        const tree = deps.index.getCallerTree(target.id, {
+            maxDepth: depth,
+            includeWeak,
+        });
+        return textResponse(banner + renderImpact(tree, target, depth, maxTokens, deps.index));
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function renderNoSymbol(name, file, suggestions) {
+    return [
+        `Error: no symbol '${name}' in '${file}'.`,
+        ...renderSuggestions(suggestions),
+    ].join('\n');
+}
+// Edge strength -> the existing per-row provenance tier tag. Honest by
+// construction: resolved within-file edges are [structural]; everything
+// cross-file is a name/member match, never asserted as verified.
+function tagFor(strength) {
+    if (strength === 'resolved')
+        return STRUCTURAL_TAG;
+    if (strength === 'weak-member')
+        return MEMBER_MATCH_TAG;
+    return NAME_MATCH_TAG;
+}
+function estimate(text) {
+    return Math.ceil(text.length / 4);
+}
+function flattenByDepth(root) {
+    const byDepth = new Map();
+    const walk = (node) => {
+        for (const child of node.children) {
+            let bucket = byDepth.get(child.depth);
+            if (!bucket) {
+                bucket = [];
+                byDepth.set(child.depth, bucket);
+            }
+            bucket.push(child);
+            walk(child);
+        }
+    };
+    walk(root);
+    return byDepth;
+}
+function renderNodeRow(node) {
+    const label = node.isModuleLevel ? MODULE_LEVEL : `${node.name}()`;
+    let row = `- ${node.file}:${node.line} — ${label}  ${tagFor(node.strength)}`;
+    const marks = [];
+    if (node.isCycle)
+        marks.push('cycle — already shown on this path');
+    if (node.leafByPolicy) {
+        // Distinguish WHY this real caller was not expanded: a resolved /
+        // import-connected leaf stopped on the depth-confidence floor; a weaker
+        // edge stopped on its class. Both are lifted by include_weak.
+        const reason = node.strength === 'resolved' || node.strength === 'import-connected'
+            ? 'low confidence at this depth'
+            : 'weak edge';
+        marks.push(`not expanded (${reason}) — pass include_weak`);
+    }
+    if (node.truncatedChildren > 0) {
+        marks.push(`+${node.truncatedChildren} more truncated`);
+    }
+    // The grouped call sites are otherwise unsurfaced; a caller that hits the
+    // target several times (or a file with several module-level call sites)
+    // would otherwise read as a single call.
+    if (node.sites.length > 1) {
+        marks.push(`${node.sites.length} call sites`);
+    }
+    if (marks.length > 0)
+        row += `  (${marks.join('; ')})`;
+    // BFS-flattening loses the tree edges; name the caller this row reaches the
+    // target through.
+    if (node.via)
+        row += `\n  ← via ${node.via}()`;
+    return row;
+}
+function renderDepthGroup(depth, nodes) {
+    const label = depth === 1 ? 'direct callers' : 'callers of the above';
+    const gloss = depth === 1 ? ' — highest risk' : '';
+    const header = `### Depth ${depth} — ${label} (${nodes.length})${gloss}`;
+    return [header, ...nodes.map(renderNodeRow)].join('\n');
+}
+function renderCoChanges(file, index) {
+    const rows = topCoChangePartners(index.getCoChanges(file), file);
+    if (rows.length === 0)
+        return '';
+    return [
+        `### Co-change Partners ${BEHAVIORAL_TAG}`,
+        ...rows.map((r) => `- ${r.partner}  ${r.pct}% confidence`),
+        '(May also be affected: no call edge, but these files historically change with this one.)',
+    ].join('\n');
+}
+// Depth-first budget loop: title/disclaimer/summary always; Depth 1 is the
+// floor (never dropped, like get_context's body); deeper hops and then the
+// behavioral section drop first, each with an honest, distinctly-worded note.
+function renderImpact(tree, target, depth, maxTokens, index) {
+    const header = `## Impact of \`${target.name}\` (${target.file}:${target.startLine})`;
+    const disclaimer = `Upstream callers traced to depth ${depth}. Edges are AST name-matches, ` +
+        `not compiler-verified — treat as candidates.`;
+    const blocks = [header, disclaimer];
+    if (tree.totalNodes === 0) {
+        blocks.push('0 callers found.');
+        blocks.push('(No upstream call sites in the index — not proof of dead code; calls ' +
+            'through dynamic dispatch or inheritance may be invisible.)');
+        const cc = renderCoChanges(target.file, index);
+        if (cc)
+            blocks.push(cc);
+        pushLimitations(blocks, tree);
+        return blocks.join('\n\n');
+    }
+    const byDepth = flattenByDepth(tree.root);
+    const depths = [...byDepth.keys()].sort((a, b) => a - b);
+    // Distinct caller/file/depth counts (and the depth-wall flag) via the shared
+    // helper (a DAG diamond is ONE caller, not N) — the single source of truth
+    // get_context and overview reuse, so the surfaces never report divergent
+    // numbers. impact keeps tree.truncated and depthCapped SEPARATE below: they
+    // map to two distinct remediation hints (raise max_tokens/narrow vs raise
+    // depth), unlike the scalar BlastRadius which collapses both into one `+`.
+    const blast = countDistinctCallers(tree.root);
+    const depthCapped = blast.depthCapped;
+    const callerCount = blast.callers;
+    // A trailing `+` flags that a breadth/size cap fired, so the true total may
+    // be higher than the number shown.
+    blocks.push(`${callerCount}${tree.truncated ? '+' : ''} ${plural('caller', callerCount)} across ` +
+        `${blast.depths} ${plural('depth', blast.depths)} ` +
+        `(${blast.files} ${plural('file', blast.files)}).`);
+    let used = estimate(blocks.join('\n\n'));
+    let cutoff = null;
+    for (const d of depths) {
+        const group = renderDepthGroup(d, byDepth.get(d) ?? []);
+        const cost = estimate(group);
+        // Depth 1 is the floor — never dropped to fit budget.
+        if (d > 1 && used + cost > maxTokens) {
+            cutoff = d;
+            break;
+        }
+        blocks.push(group);
+        used += cost;
+    }
+    // Incompleteness notes — distinctly worded so the agent knows which lever to
+    // pull: budget cutoff (raise max_tokens) vs depth wall (raise depth) vs the
+    // graph-size cap (the walk itself was bounded; counts may understate).
+    if (cutoff !== null) {
+        blocks.push(`(Depth ${cutoff}+ omitted to stay within max_tokens=${maxTokens}; the counts above include the omitted callers — raise max_tokens to see them.)`);
+    }
+    else if (depthCapped) {
+        blocks.push(`(Some depth-${depth} callers may have further callers; raise \`depth\` to expand.)`);
+    }
+    if (tree.truncated) {
+        blocks.push('(Caller discovery hit the breadth/size limit; some callers are not shown ' +
+            'and the counts above may understate the true total — narrow the scope to see them.)');
+    }
+    // Co-change rides last and only when the budget did not already cut off.
+    if (cutoff === null) {
+        const cc = renderCoChanges(target.file, index);
+        if (cc && used + estimate(cc) <= maxTokens)
+            blocks.push(cc);
+    }
+    pushLimitations(blocks, tree);
+    return blocks.join('\n\n');
+}
+// Render the structured CallerTreeResult.limitations as a trailing footnote so
+// the disclosure cannot drift from a hand-written copy of it (the top
+// disclaimer stays short and the scope caveats live here, once).
+function pushLimitations(blocks, tree) {
+    if (tree.limitations.length === 0)
+        return;
+    blocks.push(['Limitations:', ...tree.limitations.map((l) => `- ${l}`)].join('\n'));
+}