codedeep-mcp 0.1.0

package/dist/tools/common.js

@@ -0,0 +1,207 @@
+import { promises as fs } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+import { partnerOf } from '../git/analyzer.js';
+export function textResponse(text) {
+    return { content: [{ type: 'text', text }] };
+}
+// `resolve` collapses `..` segments so a traversal attempt produces a
+// relative path starting with `..` — that's how we detect escapes.
+export function normalizeFilePath(input, projectRoot) {
+    const cleaned = input.replace(/\\/g, '/');
+    const absolute = resolve(projectRoot, cleaned);
+    const rel = relative(projectRoot, absolute).replace(/\\/g, '/');
+    if (rel === '' || rel === '..' || rel.startsWith('../'))
+        return null;
+    return rel;
+}
+// projectRoot is fixed for the process lifetime, so its realpath is too —
+// caching it spares one syscall per safeReadIndexedFile call (pattern
+// scans call this once per candidate file).
+const realRootCache = new Map();
+async function realProjectRoot(projectRoot) {
+    let cached = realRootCache.get(projectRoot);
+    if (cached === undefined) {
+        cached = await fs.realpath(projectRoot);
+        realRootCache.set(projectRoot, cached);
+    }
+    return cached;
+}
+// Re-check scanner admission rules at read time so stale on-disk
+// state (symlink-swap, growth past cap, became-directory) can't
+// bypass the indexer's contract.
+export async function safeReadIndexedFile(relPath, config) {
+    const abs = join(config.projectRoot, relPath);
+    const stats = await fs.lstat(abs);
+    if (stats.isSymbolicLink()) {
+        throw new Error('refusing to follow symlink');
+    }
+    if (!stats.isFile()) {
+        throw new Error('not a regular file');
+    }
+    if (stats.size > config.maxFileSize) {
+        throw new Error(`exceeds maxFileSize (${stats.size} > ${config.maxFileSize})`);
+    }
+    // lstat only checks the final component. Resolve parent-directory
+    // symlinks so a swap higher up in the path can't escape projectRoot.
+    const [real, realRoot] = await Promise.all([
+        fs.realpath(abs),
+        realProjectRoot(config.projectRoot),
+    ]);
+    if (real !== realRoot && !real.startsWith(realRoot + sep)) {
+        throw new Error('path escapes project root');
+    }
+    return fs.readFile(abs, 'utf8');
+}
+// Among ranges that contain `line`, pick the smallest — targets the innermost
+// match (e.g. a method inside a same-named class). Returns null when no
+// candidate spans `line`; callers that want a fallback handle it themselves.
+export function innermostEnclosing(candidates, line) {
+    let innermost = null;
+    let innermostSize = Infinity;
+    for (const s of candidates) {
+        if (s.startLine > line || line > s.endLine)
+            continue;
+        const size = s.endLine - s.startLine;
+        if (size < innermostSize) {
+            innermost = s;
+            innermostSize = size;
+        }
+    }
+    return innermost;
+}
+// Innermost containing range when one exists; otherwise the candidate
+// nearest by startLine.
+export function pickByLine(candidates, line) {
+    const innermost = innermostEnclosing(candidates, line);
+    if (innermost)
+        return innermost;
+    let best = candidates[0];
+    let bestDist = Math.abs(line - best.startLine);
+    for (let i = 1; i < candidates.length; i++) {
+        const d = Math.abs(line - candidates[i].startLine);
+        if (d < bestDist) {
+            best = candidates[i];
+            bestDist = d;
+        }
+    }
+    return best;
+}
+export function renderAmbiguous(name, file, candidates) {
+    const lines = [`Multiple symbols named '${name}' in ${file}:`];
+    for (const c of candidates) {
+        lines.push(`- ${c.kind} ${c.startLine}-${c.endLine}: ${displaySignature(c)}`);
+    }
+    lines.push('', 'Pass `line` to disambiguate.');
+    return lines.join('\n');
+}
+export function omittedSuffix(omitted) {
+    return `- (${omitted} more omitted; raise \`limit\` to see all)`;
+}
+// Always emits the header; uses `(none)` as the body placeholder when
+// empty, so absence of callers/callees/exports is explicit in output.
+export function sectionOrNone(header, body) {
+    if (body.length === 0)
+        return `${header}\n(none)`;
+    return [header, ...body].join('\n');
+}
+// Elides the section when empty — for outlines where a missing section
+// is preferable to a `(none)` placeholder (imports, internal symbols).
+export function sectionOrEmpty(header, body) {
+    if (body.length === 0)
+        return '';
+    return [header, ...body].join('\n');
+}
+// Falls back to `name` when no signature was extracted (variables, some
+// Python defs) so list rows never trail an empty token.
+export function displaySignature(s) {
+    return s.signature || s.name;
+}
+// Builds the "Did you mean:" block for fuzzy suggestion replies. Returns
+// the lines (including a leading blank separator) when non-empty, [] when
+// empty so the calling site's leading sentence is the entire output.
+export function renderSuggestions(suggestions) {
+    if (suggestions.length === 0)
+        return [];
+    const lines = ['', 'Did you mean:'];
+    for (const s of suggestions) {
+        const tag = s.exported ? ' [exported]' : '';
+        lines.push(`- ${s.name} (${s.kind}, ${s.file}:${s.startLine})${tag}`);
+    }
+    return lines;
+}
+export const INDEXING_BANNER = '⏳ Indexing in progress. Results may be incomplete.';
+// Caller-row label for refs at file scope (no enclosing source symbol).
+export const MODULE_LEVEL = '(module-level)';
+// Per-line tag stamped on every approximate-name-match caller row so
+// consumers can distinguish AST-only matches from precise (LSP) refs.
+// Shared between `find_references` and `get_context`'s file-mode export
+// caller summary — both render the same data path.
+export const NAME_MATCH_TAG = '[name match, unverified]';
+// Tag for unresolved member-call rows (`obj.method()` / `ns.fn()`):
+// noisier than bare-name matches because the receiver could bind to any
+// object, so the property match alone carries the evidence.
+export const MEMBER_MATCH_TAG = '[member call, unverified]';
+// Heading qualifier that pairs with `NAME_MATCH_TAG`. Section headers
+// compose their own prefix and append this so the precision tier is
+// announced consistently.
+export const NAME_MATCH_HEADER_QUALIFIER = '(approximate — from AST name matching)';
+// Counterpart to `NAME_MATCH_TAG` for symbol-mode rows derived from the
+// id-keyed adjacency (precise within-file resolution). Emitted by
+// `get_context` symbol-mode caller/callee lists.
+export const STRUCTURAL_TAG = '[structural]';
+// Tag-less complexity body ("cyc N / cog M") for anything carrying the two
+// optional metrics, or null when neither is present. Cyclomatic is omitted at
+// the trivial 1, cognitive at 0, so a value may carry either, both, or neither;
+// show whichever the extractor populated. The param is a minimal structural
+// shape (not full `Symbol`) so a RiskRow can render its offender's complexity
+// without a synthetic Symbol. Used where the caller adds the [structural] tag
+// (formatComplexity) or deliberately suppresses it (Risk Hotspots rows, already
+// under a single [behavioral] heading).
+export function formatComplexityMetrics(sym) {
+    const parts = [];
+    if (sym.complexity !== undefined)
+        parts.push(`cyc ${sym.complexity}`);
+    if (sym.cognitiveComplexity !== undefined)
+        parts.push(`cog ${sym.cognitiveComplexity}`);
+    return parts.length === 0 ? null : parts.join(' / ');
+}
+// Renders the combined complexity body with the [structural] tag for a symbol,
+// or null when neither metric is present. Both metrics are genuinely structural
+// (no name-match approximation, unlike fan-in), so one [structural] tag covers
+// the line. Callers add their own prefix ("Complexity:" / "- Complexity:").
+export function formatComplexity(sym) {
+    const body = formatComplexityMetrics(sym);
+    return body === null ? null : `${body} ${STRUCTURAL_TAG}`;
+}
+// Tier tag for git-derived data: commit co-occurrence and history, not
+// code structure. Pairs with the design-notes tier vocabulary
+// ([structural] / [approximate] / [behavioral]).
+export const BEHAVIORAL_TAG = '[behavioral]';
+// The confidence direction is the most invertible bug in the git layer —
+// confidenceAB is the from-self direction only when the queried file is
+// fileA. Centralized (sharing analyzer's partnerOf for the orientation
+// pick) so get_context and find_references cannot disagree. Both tools
+// use the same default partner cap.
+export function topCoChangePartners(coChanges, selfPath, limit = 5) {
+    const rows = coChanges.map((c) => {
+        const selfIsA = c.fileA === selfPath;
+        return {
+            partner: partnerOf(c, selfPath),
+            // Floor at 1%: a pair only exists because coupling registered, so a
+            // "0% confidence" row (3 shared commits against a 600-commit hub
+            // file) would be self-contradictory output.
+            pct: Math.max(1, Math.round((selfIsA ? c.confidenceAB : c.confidenceBA) * 100)),
+            shared: c.sharedCommits,
+        };
+    });
+    rows.sort((a, b) => b.pct - a.pct ||
+        b.shared - a.shared ||
+        (a.partner < b.partner ? -1 : a.partner > b.partner ? 1 : 0));
+    return rows.slice(0, limit);
+}
+export function readinessBanner(ready) {
+    return ready ? '' : `${INDEXING_BANNER}\n\n`;
+}
+export function plural(word, count) {
+    return count === 1 ? word : `${word}s`;
+}

package/dist/tools/find-references.js

@@ -0,0 +1,224 @@
+import { dirname } from 'node:path';
+import { fileImportsName, fileImportsReceiver, isCallerOf, isClassMember, } from '../indexer/code-index.js';
+import { errMsg } from '../logger.js';
+import { RECEIVER_OPAQUE } from '../types.js';
+import { MEMBER_MATCH_TAG, MODULE_LEVEL, NAME_MATCH_HEADER_QUALIFIER, NAME_MATCH_TAG, normalizeFilePath, omittedSuffix, pickByLine, readinessBanner, renderAmbiguous, renderSuggestions, sectionOrEmpty, sectionOrNone, textResponse, topCoChangePartners, } from './common.js';
+const DEFAULT_LIMIT = 20;
+const MAX_LIMIT = 100;
+const SUGGEST_LIMIT = 5;
+// rankRefs' weakest tier: unresolved member refs with an unknown (non-import,
+// opaque/chained) receiver. Listed rows of this tier are capped so a hot
+// method's member-call sites can't dominate the caller list.
+const WEAK_MEMBER_TIER = 5;
+const WEAK_MEMBER_ROW_CAP = 8;
+const CALLERS_HEADER = `### Callers ${NAME_MATCH_HEADER_QUALIFIER}`;
+const CALLEES_HEADER = '### Callees (within-file — from AST resolution)';
+const PHASE_2_NOTE = '(none — ships with LSP in Phase 2)';
+export async function runFindReferences(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.');
+        }
+        // Compute banner before any index-dependent miss so partial first-pass
+        // results don't surface as definitive errors.
+        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));
+        }
+        const limit = Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+        const kind = args.kind ?? 'all';
+        const sections = [];
+        sections.push(`## References for \`${target.name}\` (${target.file}:${target.startLine})`);
+        if (kind === 'callers' || kind === 'all') {
+            sections.push(renderCallers(target, deps.index, limit));
+        }
+        if (kind === 'callees' || kind === 'all') {
+            sections.push(renderCallees(target, deps.index, limit));
+        }
+        if (kind === 'implementations' || kind === 'all') {
+            sections.push(renderPhase2('Implementations'));
+        }
+        if (kind === 'type_references' || kind === 'all') {
+            sections.push(renderPhase2('Type References'));
+        }
+        // Behavioral coupling rides along with kind 'all' only: it is
+        // file-granularity enrichment, not a reference kind, and it stays a
+        // separate section rather than a rankRefs tier — a co-committing
+        // file says nothing about whether any given AST row is a real call
+        // site, so it must not outrank verified rows. Vanishes (no header)
+        // outside git repos, unlike the structural sections above whose
+        // "(none)" is a real answer.
+        if (kind === 'all') {
+            const coChanges = renderCoChangePartners(target.file, deps.index);
+            if (coChanges)
+                sections.push(coChanges);
+        }
+        return textResponse(banner + sections.join('\n\n'));
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function renderCallers(target, index, limit) {
+    const filtered = index
+        .getReferencesByNameOrAlias(target.name, target.file, isClassMember(target))
+        .filter((ref) => isCallerOf(ref, target));
+    const ranked = rankRefs(filtered, target, index);
+    ranked.sort((a, b) => {
+        if (a.tier !== b.tier)
+            return a.tier - b.tier;
+        if (a.ref.file !== b.ref.file) {
+            return a.ref.file < b.ref.file ? -1 : 1;
+        }
+        return a.ref.line - b.ref.line;
+    });
+    // Capturing chained/member calls makes the weakest tier (unresolved member
+    // refs with an unknown receiver — `obj.m()` / chained) explode on hot method
+    // names. They already sort last, so resolved/import-connected rows are never
+    // starved; ALSO cap how many we list so they don't dominate the output — the
+    // rest fold into the omitted count (find_symbol's `References: ~N` still counts
+    // them all). WEAK_MEMBER_TIER mirrors rankRefs' tier-5 (unknown-receiver member).
+    const strong = ranked.filter((r) => r.tier < WEAK_MEMBER_TIER);
+    const weak = ranked.filter((r) => r.tier >= WEAK_MEMBER_TIER);
+    const weakShown = weak.slice(0, WEAK_MEMBER_ROW_CAP);
+    const shown = [...strong, ...weakShown].slice(0, limit);
+    const body = shown.map((r) => {
+        const callerLabel = r.source ? `${r.source.name}()` : MODULE_LEVEL;
+        // Resolved member refs (this.x() bound at extract time) carry the
+        // same confidence as resolved bare refs and keep the name-match tag;
+        // unresolved member rows get the noisier member tag.
+        const tag = r.ref.receiver !== undefined && r.ref.targetId === null
+            ? MEMBER_MATCH_TAG
+            : NAME_MATCH_TAG;
+        return `- ${r.ref.file}:${r.ref.line} — ${callerLabel}  ${tag}`;
+    });
+    const omitted = ranked.length - shown.length;
+    if (omitted > 0) {
+        // Two INDEPENDENT omission reasons, each with its own lever:
+        //  (1) `limit` truncated the list — raising it reveals more rows. Those rows
+        //      are HIGH-confidence only when STRONG rows were the ones cut
+        //      (`strong.length > limit`); if every strong row is already shown,
+        //      raising `limit` surfaces only more low-confidence `[member call]` rows,
+        //      so the high-confidence hint must NOT be advertised then.
+        //  (2) the weak-member cap dropped tier-5 rows beyond WEAK_MEMBER_ROW_CAP —
+        //      those are NOT revealable by `limit` (the full count lives in
+        //      find_symbol's `References: ~N`).
+        // Both can hold at once, so gate the high-confidence `limit` hint on
+        // `strongCut` (NOT on "limit cut anything" — weakShown rows can be limit-cut
+        // while all strong rows show) and the cap note on `capHidden`.
+        const capHidden = weak.length > weakShown.length;
+        const strongCut = strong.length > limit;
+        if (capHidden) {
+            const limitHint = strongCut ? ' raise `limit` to see more high-confidence rows;' : '';
+            body.push(`- (${omitted} more omitted;${limitHint} low-confidence \`[member call]\` sites are capped — full count via find_symbol's \`References: ~N\`)`);
+        }
+        else {
+            // No cap fired (every weak row is within WEAK_MEMBER_ROW_CAP), so all
+            // omitted rows are purely limit-truncated and fully revealable by `limit`.
+            body.push(omittedSuffix(omitted));
+        }
+    }
+    return sectionOrNone(CALLERS_HEADER, body);
+}
+function renderCallees(target, index, limit) {
+    // Within-file only — cross-file callee resolution waits for LSP (Phase 2).
+    const callees = index.getCallees(target.id);
+    const body = callees
+        .slice(0, limit)
+        .map((c) => `- ${c.file}:${c.startLine} — ${c.name}()`);
+    if (callees.length > limit) {
+        body.push(omittedSuffix(callees.length - limit));
+    }
+    return sectionOrNone(CALLEES_HEADER, body);
+}
+function renderPhase2(label) {
+    return `### ${label}\n${PHASE_2_NOTE}`;
+}
+// Confidence-only rows — find_references is the breadth view; the
+// shared-commit detail lives in get_context's co-change section.
+function renderCoChangePartners(file, index) {
+    const rows = topCoChangePartners(index.getCoChanges(file), file);
+    return sectionOrEmpty('### Co-change Partners (behavioral — from git)', rows.map((r) => `- ${r.partner}  ${r.pct}% confidence`));
+}
+function rankRefs(refs, target, index) {
+    const targetDir = dirname(target.file);
+    const targetParent = dirname(targetDir);
+    const importsCache = new Map();
+    const importsFor = (file) => {
+        let cached = importsCache.get(file);
+        if (cached === undefined) {
+            cached = index.getImports(file);
+            importsCache.set(file, cached);
+        }
+        return cached;
+    };
+    const out = [];
+    for (const ref of refs) {
+        const refDir = dirname(ref.file);
+        let tier;
+        if (ref.targetId === null && ref.receiver !== undefined) {
+            // Unresolved member refs rank by their receiver binding: an
+            // import-connected receiver (`import * as u; u.fn()`) is as strong
+            // as an import-connected bare name; anything else is the noisiest
+            // tier — the property match alone is weak evidence. An opaque
+            // (chained/computed) receiver can never name an import, so it goes
+            // straight to tier 5 — skipping the guaranteed-false import scan that
+            // chained-call capture makes the dominant unresolved-member case.
+            tier =
+                ref.receiver !== RECEIVER_OPAQUE &&
+                    fileImportsReceiver(importsFor(ref.file), ref.receiver)
+                    ? 2
+                    : WEAK_MEMBER_TIER;
+        }
+        else if (refDir === targetDir) {
+            tier = 1;
+        }
+        else if (fileImportsName(importsFor(ref.file), target.name)) {
+            tier = 2;
+        }
+        else if (refDir === targetParent || dirname(refDir) === targetParent) {
+            tier = 3;
+        }
+        else {
+            tier = 4;
+        }
+        const source = ref.sourceId ? index.getSymbolById(ref.sourceId) ?? null : null;
+        out.push({ ref, tier, source });
+    }
+    return out;
+}
+// rankRefs uses the shared fileImportsReceiver / fileImportsName (code-index.ts)
+// so impact's edge-strength classification and find_references' caller tiers
+// stay in lockstep. (Only namespace/module-object receivers are
+// "import-connected"; a value import merely NAMED like the receiver says
+// nothing about where the object's class lives. A wildcard import is a strong
+// signal — refs reach the ranker only after primaryRefMatchesTarget admitted
+// them.)
+function renderNoSymbol(name, file, suggestions) {
+    return [
+        `Error: no symbol '${name}' in '${file}'.`,
+        ...renderSuggestions(suggestions),
+    ].join('\n');
+}

package/dist/tools/find-symbol.js

@@ -0,0 +1,94 @@
+import { depthOf } from '../indexer/scanner.js';
+import { errMsg } from '../logger.js';
+import { formatComplexity, readinessBanner, renderSuggestions, textResponse, } from './common.js';
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+const SUGGEST_LIMIT = 5;
+export async function runFindSymbol(args, deps) {
+    try {
+        const trimmed = args.name.trim();
+        if (trimmed.length === 0) {
+            return textResponse('Error: name must be non-empty.');
+        }
+        const limit = Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+        const scope = normalizeScope(args.scope, deps.index);
+        const kind = args.kind;
+        const exactList = deps.index.findSymbolByName(trimmed, kind, scope);
+        const exactIds = new Set(exactList.map((s) => s.id));
+        const merged = [...exactList];
+        if (merged.length < limit) {
+            const prefixList = deps.index.findSymbolsByPrefix(trimmed, Infinity, kind, scope);
+            for (const sym of prefixList) {
+                if (exactIds.has(sym.id))
+                    continue;
+                merged.push(sym);
+            }
+        }
+        const banner = readinessBanner(deps.indexer.ready);
+        if (merged.length === 0) {
+            const filtered = deps.index.suggest(trimmed, SUGGEST_LIMIT, kind, scope);
+            return textResponse(banner + renderNoMatch(trimmed, filtered));
+        }
+        merged.sort((a, b) => compareEntries(a, b, exactIds));
+        const blocks = merged
+            .slice(0, limit)
+            .map((sym) => renderMatch(sym, deps.index));
+        return textResponse(banner + blocks.join('\n\n'));
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function normalizeScope(scope, index) {
+    if (!scope)
+        return undefined;
+    if (scope.endsWith('/'))
+        return scope;
+    // '.storybook' and 'packages/api.v2' have dots but aren't files; ask the
+    // index instead of guessing from the path shape.
+    if (index.hasFile(scope))
+        return scope;
+    return `${scope}/`;
+}
+function compareEntries(a, b, exactIds) {
+    const ea = exactIds.has(a.id);
+    const eb = exactIds.has(b.id);
+    if (ea !== eb)
+        return ea ? -1 : 1;
+    if (a.exported !== b.exported)
+        return a.exported ? -1 : 1;
+    const da = depthOf(a.file);
+    const db = depthOf(b.file);
+    if (da !== db)
+        return da - db;
+    if (a.file !== b.file)
+        return a.file < b.file ? -1 : 1;
+    const nameCmp = a.name.localeCompare(b.name);
+    if (nameCmp !== 0)
+        return nameCmp;
+    return a.startLine - b.startLine;
+}
+function renderMatch(sym, index) {
+    const range = `${sym.startLine}-${sym.endLine}`;
+    const exportedSuffix = sym.exported ? ' | exported' : '';
+    const lines = [
+        `${sym.file}:${range} | ${sym.kind}${exportedSuffix}`,
+        sym.signature,
+    ];
+    if (sym.doc && sym.doc.length > 0)
+        lines.push(sym.doc);
+    // Fan-in (reference-granular, cross-file) and fan-out (resolved within-file
+    // callees, a lower bound). Both O(1) — no caller-tree walk per match.
+    lines.push(`References: ~${index.getCallerCount(sym.id)}`);
+    lines.push(`Fan-out: ${index.getFanOut(sym.id)}`);
+    // Cyclomatic + cognitive complexity — genuinely structural (no name-match
+    // approximation, unlike fan-in). Present only for function/method symbols
+    // above each metric's trivial value (cyc 1 / cog 0).
+    const complexity = formatComplexity(sym);
+    if (complexity)
+        lines.push(`Complexity: ${complexity}`);
+    return lines.join('\n');
+}
+function renderNoMatch(name, suggestions) {
+    return [`No symbol '${name}' found.`, ...renderSuggestions(suggestions)].join('\n');
+}