codedeep-mcp 0.1.0

package/dist/tools/search-structure.js

@@ -0,0 +1,303 @@
+import { initParser, parseFile } from '../indexer/parser.js';
+import { compareShallowFirst } from '../indexer/scanner.js';
+import { errMsg, log } from '../logger.js';
+import { MODULE_LEVEL, displaySignature, innermostEnclosing, omittedSuffix, readinessBanner, safeReadIndexedFile, textResponse, } from './common.js';
+const DEFAULT_LIMIT = 10;
+const MAX_LIMIT = 100;
+// Git churn boost for query mode: recently active files float up. Capped
+// at 1.5x — the same magnitude as the exported-symbol boost — so churn
+// reorders near-ties but never outweighs MiniSearch's name relevance
+// (name field boost is 3). log1p-scaled because commit counts are
+// heavy-tailed: one 300-commit churner must not flatten the boost for
+// the 1-30 range where most files live.
+const GIT_BOOST_MAX_EXTRA = 0.5;
+// Memoized on the GitMeta OBJECT IDENTITY: every path that changes the
+// underlying commitFrequency data — applyGitAnalysis, load(), and
+// clearGitData() — replaces (or nulls) the GitMeta instance, so keying
+// on the object collapses cache validity into one invariant owned by
+// CodeIndex itself. No generation counter, no cross-module guard.
+const boostMemo = new WeakMap();
+function gitBoostMap(deps) {
+    const meta = deps.index.getGitMeta();
+    if (meta === null)
+        return undefined;
+    if (boostMemo.has(meta))
+        return boostMemo.get(meta);
+    const churned = deps.index
+        .getAllFiles()
+        .filter((f) => (f.commitFrequency ?? 0) > 0);
+    let map;
+    if (churned.length > 0) {
+        // Plain loop, NOT Math.max(...spread): spreading throws RangeError
+        // past ~125k elements, and an exception here would surface as an
+        // in-band tool error caused purely by git enrichment.
+        let maxLog = 0;
+        for (const f of churned) {
+            const lg = Math.log1p(f.commitFrequency);
+            if (lg > maxLog)
+                maxLog = lg;
+        }
+        map = new Map(churned.map((f) => [
+            f.path,
+            1 + GIT_BOOST_MAX_EXTRA * (Math.log1p(f.commitFrequency) / maxLog),
+        ]));
+    }
+    boostMemo.set(meta, map);
+    return map;
+}
+// Pattern scans read every candidate file from disk; bound the worst case
+// (zero matches on a huge repo) and tell the caller to narrow instead.
+const PATTERN_FILE_CAP = 2000;
+const MATCH_TEXT_CAP = 120;
+// User-facing language names → index-internal language ids.
+const LANGUAGE_ALIASES = {
+    typescript: ['typescript', 'tsx'],
+    ts: ['typescript', 'tsx'],
+    tsx: ['tsx'],
+    javascript: ['javascript'],
+    js: ['javascript'],
+    python: ['python'],
+    py: ['python'],
+    java: ['java'],
+    go: ['go'],
+    golang: ['go'],
+    rust: ['rust'],
+    rs: ['rust'],
+    swift: ['swift'],
+    kotlin: ['kotlin'],
+    kt: ['kotlin'],
+    dart: ['dart'],
+    flutter: ['dart'],
+    csharp: ['csharp'],
+    cs: ['csharp'],
+    php: ['php'],
+    ruby: ['ruby'],
+    rb: ['ruby'],
+    cpp: ['cpp'],
+    'c++': ['cpp'],
+    cc: ['cpp'],
+    c: ['c'],
+    objc: ['objc'],
+    'objective-c': ['objc'],
+    objectivec: ['objc'],
+};
+const SUPPORTED_LANGUAGES = 'typescript, tsx, javascript, python, java, go, rust, swift, kotlin, dart, csharp, php, ruby, cpp, c, objc';
+// Loaded lazily and cached: the native binding is only touched when a
+// `pattern` call arrives, and a load failure (unsupported platform)
+// degrades pattern mode without affecting the rest of the server.
+let astGrepLoad;
+function loadAstGrep() {
+    astGrepLoad ??= import('@ast-grep/napi').then((m) => m, (err) => {
+        log.warn(`search_structure: @ast-grep/napi unavailable: ${errMsg(err)}`);
+        return null;
+    });
+    return astGrepLoad;
+}
+export async function runSearchStructure(args, deps) {
+    try {
+        const banner = readinessBanner(deps.indexer.ready);
+        const limit = Math.min(args.limit ?? DEFAULT_LIMIT, MAX_LIMIT);
+        let languages;
+        if (args.language !== undefined) {
+            const expanded = LANGUAGE_ALIASES[args.language.trim().toLowerCase()];
+            if (!expanded) {
+                return textResponse(`Error: unknown language '${args.language}'. Supported: ${SUPPORTED_LANGUAGES}.`);
+            }
+            languages = new Set(expanded);
+        }
+        const pattern = args.pattern?.trim();
+        if (pattern) {
+            return textResponse(banner + (await runPatternMode(pattern, languages, limit, deps)));
+        }
+        const query = args.query?.trim();
+        if (!query) {
+            return textResponse('Error: provide a non-empty `query` or an ast-grep `pattern`.');
+        }
+        return textResponse(banner + runQueryMode(query, languages, limit, deps, args.language));
+    }
+    catch (err) {
+        return textResponse(`Error: ${errMsg(err)}`);
+    }
+}
+function runQueryMode(query, languages, limit, deps, languageArg) {
+    const { symbols, total } = deps.index.searchSymbols(query, {
+        limit,
+        languages,
+        boostByFile: gitBoostMap(deps),
+    });
+    if (symbols.length === 0) {
+        const filterNote = languageArg ? ` (language: ${languageArg})` : '';
+        return `No matches for '${query}'${filterNote}.`;
+    }
+    const blocks = symbols.map(renderSymbolBlock);
+    if (total > symbols.length) {
+        blocks.push(omittedSuffix(total - symbols.length));
+    }
+    return blocks.join('\n\n');
+}
+function symbolHeader(sym) {
+    const exportedSuffix = sym.exported ? ' | exported' : '';
+    return `${sym.file}:${sym.startLine}-${sym.endLine} | ${sym.kind}${exportedSuffix}`;
+}
+function renderSymbolBlock(sym) {
+    const lines = [symbolHeader(sym), displaySignature(sym)];
+    if (sym.doc && sym.doc.length > 0)
+        lines.push(sym.doc);
+    return lines.join('\n');
+}
+async function runPatternMode(pattern, languages, limit, deps) {
+    const ag = await loadAstGrep();
+    if (!ag) {
+        return ('Error: structural pattern matching is unavailable — the ' +
+            '@ast-grep/napi native binding failed to load on this platform. ' +
+            'Keyword `query` mode still works.');
+    }
+    // Pattern matching ships for the ast-grep built-in languages only;
+    // other indexed languages would need the pre-1.0 @ast-grep/lang-*
+    // packages.
+    const patternLangs = new Map([
+        ['typescript', ag.Lang.TypeScript],
+        ['tsx', ag.Lang.Tsx],
+        ['javascript', ag.Lang.JavaScript],
+    ]);
+    const targets = new Map([...patternLangs].filter(([id]) => !languages || languages.has(id)));
+    if (targets.size === 0) {
+        return ('Structural patterns are not supported for this language yet — ' +
+            'this phase covers TypeScript/TSX/JavaScript only. ' +
+            'Keyword `query` mode works for all indexed languages.');
+    }
+    // ast-grep does not reject malformed patterns (they silently match
+    // nothing), so validate by parsing the pattern as code with our own
+    // tree-sitter grammars. `hasError` covers both ERROR nodes and
+    // zero-width MISSING-token recovery (e.g. `function f() {`), which an
+    // ERROR-kind query would let through.
+    await initParser();
+    const invalidLangs = [];
+    for (const id of targets.keys()) {
+        if (!patternParses(id, pattern)) {
+            invalidLangs.push(id);
+            targets.delete(id);
+        }
+    }
+    if (targets.size === 0) {
+        return `Error: invalid ast-grep pattern '${pattern}' — it does not parse as ${invalidLangs.join('/')} code.`;
+    }
+    const files = deps.index
+        .getAllFiles()
+        .filter((f) => targets.has(f.language))
+        .sort(compareShallowFirst);
+    const { matches, skipped, fileCapHit } = await scanPattern(ag, pattern, targets, files, limit, deps.config);
+    const blocks = renderPatternMatches(matches.slice(0, limit), deps.index);
+    if (blocks.length === 0) {
+        if (files.length > 0) {
+            blocks.push(`No structural matches for pattern '${pattern}'.`);
+        }
+        else if (languages !== undefined || invalidLangs.length > 0) {
+            // A blanket "nothing is indexed" claim would be false here — the
+            // emptiness came from the language filter / pattern validation.
+            blocks.push(`No structural matches for pattern '${pattern}' — no indexed files match the scanned language(s) (${[...targets.keys()].join('/')}).`);
+        }
+        else {
+            blocks.push(`No structural matches for pattern '${pattern}' — no TypeScript/TSX/JavaScript files are indexed.`);
+        }
+    }
+    const notes = [];
+    if (matches.length > limit)
+        notes.push('(more matches exist; raise `limit` to see all)');
+    if (fileCapHit) {
+        notes.push(`(stopped after scanning ${PATTERN_FILE_CAP} files; pass \`language\` to narrow the scan)`);
+    }
+    if (skipped > 0)
+        notes.push(`(${skipped} file${skipped === 1 ? '' : 's'} could not be read and were skipped)`);
+    if (invalidLangs.length > 0) {
+        notes.push(`(pattern does not parse as ${invalidLangs.join('/')}; those files were skipped)`);
+    }
+    return [...blocks, ...notes].join('\n\n');
+}
+// Validates the pattern by parsing it as code with OUR web-tree-sitter
+// grammar for the index language id. Requires initParser() to have run
+// (the caller awaits it). No catch: an unexpected parser throw must reach
+// runSearchStructure's outer in-band handler as the REAL error, not be
+// mislabeled as an invalid pattern.
+function patternParses(languageId, pattern) {
+    const tree = parseFile(pattern, languageId);
+    if (!tree)
+        return false;
+    try {
+        return !tree.rootNode.hasError;
+    }
+    finally {
+        tree.delete();
+    }
+}
+// Reads and scans each candidate file, collecting up to limit+1 matches
+// (the sentinel detects truncation). Per-file failures are skipped and
+// counted, never thrown.
+async function scanPattern(ag, pattern, targets, files, limit, config) {
+    const matches = [];
+    let scanned = 0;
+    let skipped = 0;
+    let fileCapHit = false;
+    for (const file of files) {
+        if (matches.length > limit)
+            break;
+        if (scanned >= PATTERN_FILE_CAP) {
+            fileCapHit = true;
+            break;
+        }
+        scanned++;
+        try {
+            const content = await safeReadIndexedFile(file.path, config);
+            // parseAsync offloads parsing to the threadpool, so long scans
+            // keep yielding to the event loop between files.
+            const root = (await ag.parseAsync(targets.get(file.language), content)).root();
+            for (const node of root.findAll(pattern)) {
+                matches.push({
+                    file: file.path,
+                    line: node.range().start.line + 1,
+                    text: firstLine(node.text()),
+                });
+                if (matches.length > limit)
+                    break;
+            }
+        }
+        catch (err) {
+            skipped++;
+            log.debug(`search_structure: skipped ${file.path}: ${errMsg(err)}`);
+        }
+    }
+    return { matches, skipped, fileCapHit };
+}
+function firstLine(text) {
+    // First visual line only, line-ending agnostic: cut at the first CR or LF.
+    // A CRLF- or lone-CR-authored source file (common on Windows) would
+    // otherwise leave a stray '\r' on the rendered snippet — slicing at '\n'
+    // alone keeps the '\r' of a '\r\n' pair, and a lone '\r' has no '\n' at all.
+    const end = text.search(/[\r\n]/);
+    const line = end === -1 ? text : text.slice(0, end);
+    return line.length > MATCH_TEXT_CAP ? `${line.slice(0, MATCH_TEXT_CAP)}…` : line;
+}
+// Groups matches by (file, enclosing symbol); module-level matches get a
+// `file (module level)` header. Insertion order follows scan order, so
+// output stays shallow-first and in-document-order.
+function renderPatternMatches(matches, index) {
+    const groups = new Map();
+    for (const m of matches) {
+        const sym = innermostEnclosing(index.getSymbolsInFile(m.file), m.line);
+        const key = `${m.file}\0${sym?.id ?? ''}`;
+        let group = groups.get(key);
+        if (!group) {
+            group = sym
+                ? { header: symbolHeader(sym), signature: displaySignature(sym), rows: [] }
+                : { header: `${m.file} ${MODULE_LEVEL}`, signature: null, rows: [] };
+            groups.set(key, group);
+        }
+        group.rows.push(`  match :${m.line}  ${m.text}`);
+    }
+    const blocks = [];
+    for (const g of groups.values()) {
+        const lines = g.signature ? [g.header, g.signature, ...g.rows] : [g.header, ...g.rows];
+        blocks.push(lines.join('\n'));
+    }
+    return blocks;
+}

package/dist/types.js

@@ -0,0 +1,61 @@
+// Shared types for codedeep-mcp.
+//
+// Note: the `Symbol` interface name shadows the global `Symbol` constructor
+// when imported, but only as a *type* — the runtime `Symbol(...)` value is
+// untouched. Module-scoped interfaces do NOT merge with `lib.es5.d.ts`'s
+// global `Symbol` (that would require `declare global`).
+// SymbolKinds that bare-identifier calls (`foo()`) can never bind to:
+// methods require member access (resolved separately via the receiver and
+// `methodsByClass`); interfaces and types never appear at runtime. Used by
+// the extractor's call resolver to exclude these from `nameToId`, and by
+// `isCallerOf` to reject bare-name matches against these kinds (member
+// refs — `receiver` present — may still match methods).
+export const NON_CALLABLE_KINDS = new Set([
+    'method',
+    'interface',
+    'type',
+    // Bare `Color()` is never a valid call on an enum, and enums have no
+    // invocable members, so member refs can't target them either.
+    'enum',
+    // Same for namespaces: in declaration merging (`namespace fmt` +
+    // `function fmt`) the call belongs to the function — without this
+    // entry the namespace symbol would win the extractor's first-wins
+    // nameToId and steal the function's resolved refs.
+    'module',
+]);
+// Sentinel values stored in `ImportInfo.importedNames[].name` to encode
+// non-named imports. Both `default` and `*` are reserved words in module
+// syntax and cannot collide with a real exported identifier; consumers
+// distinguish them by these constants instead of comparing to literals.
+export const IMPORT_DEFAULT = 'default';
+export const IMPORT_NAMESPACE = '*';
+// Receiver sentinel for member calls whose receiver is NOT a single resolvable
+// token — chained `a.b().c()`, indexed `arr[0].run()`, non-null `a!.b()`. A
+// non-identifier marker, so it can never collide with a real receiver name or an
+// import local: the consumers (memberRefMatchesTarget / rankRefs / edgeStrength)
+// already treat an unknown receiver as a weak, tier-5, never-resolved member
+// include. These refs are therefore FINDABLE by method name (recall) but can
+// never form a resolved cross-file edge.
+export const RECEIVER_OPAQUE = '()';
+// Sentinel language tag for files whose extension we don't recognize.
+// They're recorded as FileInfo (so overview can report them) but skipped
+// at parse/extract time.
+export const LANGUAGE_UNKNOWN = 'unknown';
+// Extracts `Class` from a member FQN `<file>:<Class>.<member>`; null for
+// top-level FQNs (`<file>:<name>`). File paths can contain dots, so the
+// split is the first `.` AFTER the first `:` — this function is the one
+// parser of that contract (extractor member resolution and code-index
+// member gating both rely on it).
+export function classNameFromFqn(fqn) {
+    const colon = fqn.indexOf(':');
+    if (colon === -1)
+        return null;
+    const dot = fqn.indexOf('.', colon + 1);
+    if (dot === -1)
+        return null;
+    // Empty class segment means the dot belongs to the SYMBOL name, not a member
+    // separator — e.g. a top-level Swift operator function `func .*` has FQN
+    // `file:.*`. Treat it as top-level (null), not a member of class "".
+    const cls = fqn.slice(colon + 1, dot);
+    return cls === '' ? null : cls;
+}

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "codedeep-mcp",
+  "version": "0.1.0",
+  "description": "MCP server that gives AI coding agents structural understanding of a codebase — symbols, references, blast radius, cyclomatic/cognitive complexity, and behavioral-git signals across 14 languages (tree-sitter).",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "tree-sitter",
+    "code-intelligence",
+    "code-analysis",
+    "ast",
+    "cyclomatic-complexity",
+    "cognitive-complexity",
+    "ai-agents",
+    "developer-tools"
+  ],
+  "license": "MIT",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "codedeep-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/",
+    "grammars/"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/planexhq/codedeep-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/planexhq/codedeep-mcp/issues"
+  },
+  "homepage": "https://github.com/planexhq/codedeep-mcp#readme",
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "copy:grammars": "node scripts/copy-grammars.mjs",
+    "prebuild": "npm run copy:grammars",
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsc -p tsconfig.json --watch",
+    "start": "node dist/index.js",
+    "dogfood": "tsx scripts/dogfood/run.ts",
+    "test": "vitest run --passWithNoTests",
+    "inspect": "npm run build && npx @modelcontextprotocol/inspector node dist/index.js",
+    "prepare": "npm run build"
+  },
+  "dependencies": {
+    "@ast-grep/napi": "^0.43.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "minisearch": "^7.1.2",
+    "picomatch": "^4.0.4",
+    "web-tree-sitter": "^0.26.8",
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "@repomix/tree-sitter-wasms": "^0.1.17",
+    "@tree-sitter-grammars/tree-sitter-kotlin": "^1.1.0",
+    "@types/node": "^25.6.0",
+    "@types/picomatch": "^4.0.3",
+    "tree-sitter-objc": "^3.0.2",
+    "tsx": "^4.22.4",
+    "typescript": "^6.0.0",
+    "vitest": "^4.1.0"
+  }
+}