@danielblomma/cortex-mcp 1.3.1 → 1.4.0

package/scaffold/scripts/parsers/tree-sitter/base.mjs

@@ -0,0 +1,163 @@
+/**
+ * Tree-sitter parser infrastructure for Cortex.
+ *
+ * Provides shared utilities for tree-sitter-based language parsers:
+ * WASM grammar loading (cached), parser creation, query execution,
+ * and helpers for converting tree-sitter captures into Cortex chunks.
+ *
+ * Tree-sitter is async at init/load time but parsing itself is sync.
+ * Language modules call initTreeSitter() + loadGrammar() at module
+ * load time (via top-level await) so that parseCode() can remain sync
+ * and match the contract expected by scripts/ingest.mjs.
+ */
+
+import path from "node:path";
+import fs from "node:fs";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { createRequire } from "node:module";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const require = createRequire(import.meta.url);
+
+let TreeSitterModule = null;
+let initPromise = null;
+const grammarCache = new Map();
+
+async function loadTreeSitter() {
+  if (TreeSitterModule) return TreeSitterModule;
+  const mod = await import("web-tree-sitter");
+  TreeSitterModule = mod.default ?? mod;
+  return TreeSitterModule;
+}
+
+export async function initTreeSitter() {
+  if (initPromise) return initPromise;
+  initPromise = (async () => {
+    const TreeSitter = await loadTreeSitter();
+    await TreeSitter.init();
+    return TreeSitter;
+  })();
+  return initPromise;
+}
+
+function resolveGrammarPath(grammarName) {
+  const override = process.env.CORTEX_TREE_SITTER_GRAMMAR_DIR;
+  const baseDir = override && override.trim().length > 0
+    ? override.trim()
+    : path.dirname(require.resolve("tree-sitter-wasms/package.json"));
+  const wasmFile = path.join(baseDir, "out", `tree-sitter-${grammarName}.wasm`);
+  if (!fs.existsSync(wasmFile)) {
+    throw new Error(`tree-sitter grammar WASM not found: ${wasmFile}`);
+  }
+  return wasmFile;
+}
+
+export async function loadGrammar(grammarName) {
+  if (grammarCache.has(grammarName)) {
+    return grammarCache.get(grammarName);
+  }
+  const TreeSitter = await initTreeSitter();
+  const wasmPath = resolveGrammarPath(grammarName);
+  const language = await TreeSitter.Language.load(wasmPath);
+  grammarCache.set(grammarName, language);
+  return language;
+}
+
+export function resetGrammarCache() {
+  grammarCache.clear();
+}
+
+export function createParser(language) {
+  if (!TreeSitterModule) {
+    throw new Error("tree-sitter not initialized — call initTreeSitter() first");
+  }
+  const parser = new TreeSitterModule();
+  parser.setLanguage(language);
+  return parser;
+}
+
+export function parseSource(language, code) {
+  const parser = createParser(language);
+  const tree = parser.parse(code);
+  return { tree, parser };
+}
+
+export function runQuery(language, queryString, node) {
+  const query = language.query(queryString);
+  const captures = query.captures(node);
+  return captures;
+}
+
+/**
+ * Group captures into records keyed by an anchor capture name.
+ * Tree-sitter queries often produce multiple captures per match
+ * (e.g. @fn + @fn.name + @fn.body). This groups all captures whose
+ * node is contained within the same anchor node.
+ *
+ * @param {Array<{name: string, node: object}>} captures
+ * @param {string} anchorName - capture name that marks the outer scope
+ * @returns {Array<Map<string, object>>} list of maps from capture-name to node
+ */
+export function groupByAnchor(captures, anchorName) {
+  const anchors = captures
+    .filter((c) => c.name === anchorName)
+    .sort((a, b) => a.node.startIndex - b.node.startIndex);
+
+  const groups = anchors.map(() => new Map());
+  groups.forEach((g, i) => g.set(anchorName, anchors[i].node));
+
+  for (const cap of captures) {
+    if (cap.name === anchorName) continue;
+    const idx = anchors.findIndex((a) =>
+      cap.node.startIndex >= a.node.startIndex &&
+      cap.node.endIndex <= a.node.endIndex
+    );
+    if (idx >= 0 && !groups[idx].has(cap.name)) {
+      groups[idx].set(cap.name, cap.node);
+    }
+  }
+
+  return groups;
+}
+
+export function lineRangeOf(node) {
+  return {
+    startLine: node.startPosition.row + 1,
+    endLine: node.endPosition.row + 1
+  };
+}
+
+export function bodyOf(node, maxChars = 12000) {
+  const text = node.text ?? "";
+  if (text.length <= maxChars) return text;
+  return text.slice(0, maxChars);
+}
+
+export function normalizeWhitespace(value) {
+  return String(value).replace(/\s+/g, " ").trim();
+}
+
+export function dedupe(items) {
+  return [...new Set(items.filter((item) => item != null && item !== ""))];
+}
+
+/**
+ * Convenience loader for language modules — initializes tree-sitter and
+ * pre-loads a grammar. Returns an object with the grammar handle and
+ * shared helpers so language modules don't need to reimport base.mjs.
+ */
+export async function prepareLanguage(grammarName) {
+  await initTreeSitter();
+  const language = await loadGrammar(grammarName);
+  return {
+    language,
+    parse: (code) => parseSource(language, code),
+    query: (queryString, node) => runQuery(language, queryString, node)
+  };
+}
+
+export function loadQueryFile(filePath) {
+  const url = filePath.startsWith("file:") ? new URL(filePath) : pathToFileURL(path.resolve(__dirname, filePath));
+  return fs.readFileSync(url, "utf8");
+}

package/scaffold/scripts/parsers/tree-sitter/queries/bash.calls.scm

@@ -0,0 +1,7 @@
+; Bash calls. Every `command` node has a `command_name` which contains
+; the program / function being invoked. The adapter filters out
+; builtins and common system commands so the graph reflects user-
+; defined function calls rather than shell plumbing.
+
+(command
+  name: (command_name) @call.name)

package/scaffold/scripts/parsers/tree-sitter/queries/bash.chunks.scm

@@ -0,0 +1,6 @@
+; Bash chunk captures. function_definition covers both
+; `function foo { ... }` and `foo() { ... }` styles — the name lives
+; in a `word` child.
+
+(function_definition
+  name: (word) @fn.name) @fn.decl

package/scaffold/scripts/parsers/tree-sitter/queries/bash.imports.scm

@@ -0,0 +1,5 @@
+; Bash "imports" are source/. commands. Capture all commands — the
+; adapter filters to command_name == "source" or "." and extracts
+; the first static `word` argument as the sourced path.
+
+(command) @import.cmd

package/scaffold/scripts/parsers/tree-sitter/queries/cpp.calls.scm

@@ -0,0 +1,17 @@
+; C/C++ call captures.
+; - Direct calls: `foo()` — identifier as function child.
+; - Member calls: `obj.m()` / `ptr->m()` — field_expression with a
+;   field_identifier; we capture the trailing field name.
+; - Qualified calls: `ns::f()` / `Class::staticMethod()` —
+;   qualified_identifier with a trailing name identifier.
+
+(call_expression
+  function: (identifier) @call.name)
+
+(call_expression
+  function: (field_expression
+    field: (field_identifier) @call.name))
+
+(call_expression
+  function: (qualified_identifier
+    name: (identifier) @call.name))

package/scaffold/scripts/parsers/tree-sitter/queries/cpp.chunks.scm

@@ -0,0 +1,30 @@
+; C/C++ chunk captures. tree-sitter-cpp parses C too (superset), so
+; one grammar covers .c, .h, .cpp, .cc, .hpp, .hh.
+;
+; - function_definition: top-level functions, methods defined inline
+;   inside class bodies, and out-of-class method definitions (with
+;   qualified_identifier like `Foo::bar`). The adapter inspects the
+;   function_declarator to pick the name form.
+; - class_specifier / struct_specifier / union_specifier: type decls.
+; - enum_specifier: plain `enum` and `enum class`.
+; - namespace_definition: named namespaces (including nested `a::b`).
+; - template_declaration is NOT captured directly — the inner
+;   class/function is captured separately, and walking up to the
+;   template_declaration parent for start-line is handled in the
+;   adapter if needed.
+
+(function_definition) @fn.decl
+
+(class_specifier
+  name: (type_identifier) @class.name) @class.decl
+
+(struct_specifier
+  name: (type_identifier) @struct.name) @struct.decl
+
+(union_specifier
+  name: (type_identifier) @union.name) @union.decl
+
+(enum_specifier
+  name: (type_identifier) @enum.name) @enum.decl
+
+(namespace_definition) @namespace.decl

package/scaffold/scripts/parsers/tree-sitter/queries/cpp.imports.scm

@@ -0,0 +1,6 @@
+; C/C++ include directives. `#include <x>` uses system_lib_string
+; (the path includes the angle brackets); `#include "x"` uses
+; string_literal. The adapter normalizes both to the bare path
+; (without angle brackets or quotes).
+
+(preproc_include) @include.decl

package/scaffold/scripts/parsers/tree-sitter/queries/go.calls.scm

@@ -0,0 +1,11 @@
+; Go call-expression captures. Function field can be:
+;   - identifier: direct call like foo()
+;   - selector_expression: qualified call like pkg.Fn() or obj.Method()
+; The adapter extracts the trailing identifier (the "name" of the call).
+
+(call_expression
+  function: (identifier) @call.name)
+
+(call_expression
+  function: (selector_expression
+    field: (field_identifier) @call.name))

package/scaffold/scripts/parsers/tree-sitter/queries/go.chunks.scm

@@ -0,0 +1,19 @@
+; Go chunk captures.
+; - function_declaration: top-level funcs
+; - method_declaration: methods with receiver (adapter extracts receiver type)
+; - type_declaration: wraps type_spec and type_alias — the adapter inspects
+;   the body type (struct_type / interface_type / other) to choose the kind.
+
+(function_declaration
+  name: (identifier) @fn.name) @fn.decl
+
+(method_declaration
+  name: (field_identifier) @method.name) @method.decl
+
+(type_declaration
+  (type_spec
+    name: (type_identifier) @type.name)) @type.decl
+
+(type_declaration
+  (type_alias
+    name: (type_identifier) @type.name)) @type.decl

package/scaffold/scripts/parsers/tree-sitter/queries/go.imports.scm

@@ -0,0 +1,6 @@
+; Go import captures. import_spec covers both single imports and
+; entries inside grouped import_spec_list. The adapter unquotes the
+; path string literal so "fmt" -> fmt, "github.com/foo/bar" -> github.com/foo/bar.
+
+(import_spec
+  path: (interpreted_string_literal) @import.path)

package/scaffold/scripts/parsers/tree-sitter/queries/java.calls.scm

@@ -0,0 +1,6 @@
+; Java call captures. method_invocation always has a `name` field of
+; kind identifier — the trailing method name. Covers foo(),
+; Helper.load(), obj.method(), System.out.println(...).
+
+(method_invocation
+  name: (identifier) @call.name)

package/scaffold/scripts/parsers/tree-sitter/queries/java.chunks.scm

@@ -0,0 +1,23 @@
+; Java chunk captures.
+; - class_declaration, interface_declaration, enum_declaration,
+;   record_declaration — each has an identifier name.
+; - method_declaration and constructor_declaration are nested in
+;   class/interface bodies; the adapter walks up to qualify names.
+
+(class_declaration
+  name: (identifier) @class.name) @class.decl
+
+(interface_declaration
+  name: (identifier) @interface.name) @interface.decl
+
+(enum_declaration
+  name: (identifier) @enum.name) @enum.decl
+
+(record_declaration
+  name: (identifier) @record.name) @record.decl
+
+(method_declaration
+  name: (identifier) @method.name) @method.decl
+
+(constructor_declaration
+  name: (identifier) @ctor.name) @ctor.decl

package/scaffold/scripts/parsers/tree-sitter/queries/java.imports.scm

@@ -0,0 +1,6 @@
+; Java import captures. The import_declaration node wraps either a
+; scoped_identifier (for the full path) or a scoped_identifier plus an
+; asterisk (wildcard). The adapter extracts the path text and appends
+; ".*" for wildcards.
+
+(import_declaration) @import.decl

package/scaffold/scripts/parsers/tree-sitter/queries/python.calls.scm

@@ -0,0 +1,11 @@
+; Python call captures. The `call` node's `function` field may be:
+;   - identifier: direct call like foo()
+;   - attribute: method/qualified call like obj.method() or pkg.fn()
+;   - subscript: rare dynamic indexing — intentionally skipped.
+
+(call
+  function: (identifier) @call.name)
+
+(call
+  function: (attribute
+    attribute: (identifier) @call.name))

package/scaffold/scripts/parsers/tree-sitter/queries/python.chunks.scm

@@ -0,0 +1,11 @@
+; Python chunk captures. function_definition covers both sync `def`
+; and `async def` in tree-sitter-python (async is a token on the node,
+; not a distinct node type). Decorated definitions wrap the inner
+; function/class; we capture the inner nodes directly since startLine
+; of the def/class is more useful than the decorator line.
+
+(function_definition
+  name: (identifier) @fn.name) @fn.decl
+
+(class_definition
+  name: (identifier) @class.name) @class.decl

package/scaffold/scripts/parsers/tree-sitter/queries/python.imports.scm

@@ -0,0 +1,13 @@
+; Python import captures. Covers three forms:
+;   import foo
+;   import foo as bar
+;   from pkg import name
+;   from .pkg import name
+;   from pkg import name as alias
+;
+; The adapter renders each as a dot-separated fully-qualified string
+; matching what a user would grep for ("pkg.name", "foo", ".pkg.name").
+
+(import_statement) @import.stmt
+
+(import_from_statement) @import.stmt

package/scaffold/scripts/parsers/tree-sitter/queries/ruby.calls.scm

@@ -0,0 +1,6 @@
+; Ruby call captures. Every call node in tree-sitter-ruby has a
+; `method` field of kind identifier — the method name regardless of
+; whether there's a receiver (foo(), obj.bar, Class.baz(...)).
+
+(call
+  method: (identifier) @call.name)

package/scaffold/scripts/parsers/tree-sitter/queries/ruby.chunks.scm

@@ -0,0 +1,16 @@
+; Ruby chunk captures.
+; - class / module: top-level or nested type-like declarations
+; - method: regular `def name` inside a class/module (or top-level)
+; - singleton_method: `def self.name` — class-level methods
+
+(class
+  name: (constant) @class.name) @class.decl
+
+(module
+  name: (constant) @module.name) @module.decl
+
+(method
+  name: (identifier) @method.name) @method.decl
+
+(singleton_method
+  name: (identifier) @singleton.name) @singleton.decl

package/scaffold/scripts/parsers/tree-sitter/queries/ruby.imports.scm

@@ -0,0 +1,8 @@
+; Ruby imports are function-style calls. Capture top-level calls
+; whose method identifier is a loader function; the adapter filters
+; to just require / require_relative / load / autoload and extracts
+; the string-literal path argument.
+
+(call
+  method: (identifier) @import.func
+  arguments: (argument_list)) @import.call

package/scaffold/scripts/parsers/tree-sitter/queries/rust.calls.scm

@@ -0,0 +1,31 @@
+; Call-expression captures for Rust. Extracts the callee identifier from
+; call_expression nodes. The function field may be:
+;   - identifier: direct call like foo()
+;   - scoped_identifier: path call like std::fs::read()
+;   - field_expression: method call like self.foo()
+; The adapter resolves the trailing name for each form.
+
+(call_expression
+  function: (identifier) @call.name)
+
+(call_expression
+  function: (scoped_identifier
+    name: (identifier) @call.name))
+
+(call_expression
+  function: (field_expression
+    field: (field_identifier) @call.name))
+
+(call_expression
+  function: (generic_function
+    function: (identifier) @call.name))
+
+(call_expression
+  function: (generic_function
+    function: (scoped_identifier
+      name: (identifier) @call.name)))
+
+(call_expression
+  function: (generic_function
+    function: (field_expression
+      field: (field_identifier) @call.name)))

package/scaffold/scripts/parsers/tree-sitter/queries/rust.chunks.scm

@@ -0,0 +1,29 @@
+; Top-level item captures for Rust.
+; Each @*.decl anchor wraps the whole item; companion captures expose
+; the name or other fields used by the adapter.
+
+(function_item
+  name: (identifier) @fn.name
+  body: (block)) @fn.decl
+
+(struct_item
+  name: (type_identifier) @struct.name) @struct.decl
+
+(enum_item
+  name: (type_identifier) @enum.name) @enum.decl
+
+(trait_item
+  name: (type_identifier) @trait.name) @trait.decl
+
+(impl_item
+  type: (type_identifier) @impl.type) @impl.decl
+
+(impl_item
+  type: (generic_type
+    type: (type_identifier) @impl.type)) @impl.decl
+
+(mod_item
+  name: (identifier) @mod.name) @mod.decl
+
+(macro_definition
+  name: (identifier) @macro.name) @macro.decl

package/scaffold/scripts/parsers/tree-sitter/queries/rust.imports.scm

@@ -0,0 +1,5 @@
+; Use-declaration captures for Rust. Each use_declaration's argument
+; node contains the path that the adapter renders as an import string.
+
+(use_declaration
+  argument: (_) @use.path)