brainclaw 1.16.0 → 1.18.0

package/dist/core/code-map/lang/c/index.js

@@ -0,0 +1,150 @@
+/**
+ * Code Map langs batch 2 — CProvider (provider #6).
+ *
+ * Owns `.c` / `.h` (runtime lang `c`). `extractDraft` delegates to the generic
+ * query-runtime; the curated `tags.scm`/`imports.scm` (this dir) drive extraction.
+ * Definition subtypes are fixed by the query: a named C struct maps to `class`
+ * (the named aggregate devs search for like a class), a union → `c.union`
+ * (provider-namespaced — no universal peer), enum/typedef(→type)/`#define`(→macro)
+ * are universal, and `function_definition` → function. The function NAME is nested
+ * inside `function_declarator declarator: (identifier)`, wrapped in a
+ * `pointer_declarator` per `*` on the return type — the tags query enumerates the
+ * 0..3 pointer-depth alternatives (see tags.scm).
+ *
+ * `refine()` carries only what the import query cannot express structurally: a C
+ * `#include` path is either a `<...>` system-lib token or a `"..."` string literal,
+ * so the captured @import.source keeps its angle brackets / quotes — strip them to
+ * the bare header path. NO exports edges — C has no export statement (capabilities:
+ * T2 = imports). Identity is owned by the CORE finalizer — this provider mints NO
+ * ids. The grammar loads through the SHARED engine glue (`loadGrammarWasm`), never
+ * a fresh `web-tree-sitter` import (trp_8df65ab7).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadGrammarWasm, grammarHashForWasm } from '../../wasm-loader.js';
+import { extractWithQueries } from '../query-runtime.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const C_WASM_BASENAME = 'tree-sitter-c.wasm';
+const C_WASM_NODE_MODULES_SPEC = 'tree-sitter-wasms/out/tree-sitter-c.wasm';
+const C_GRAMMAR_NAME = 'tree-sitter-c';
+/** Resolve a vendored `.scm` next to this module (dist) or from the source tree. */
+function readScm(basename) {
+    const local = path.join(HERE, basename);
+    if (fs.existsSync(local))
+        return fs.readFileSync(local, 'utf-8');
+    let dir = HERE;
+    for (let i = 0; i < 12; i++) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            const fromSrc = path.join(dir, 'src', 'core', 'code-map', 'lang', 'c', basename);
+            if (fs.existsSync(fromSrc))
+                return fs.readFileSync(fromSrc, 'utf-8');
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`code-map: could not locate query asset ${basename} (from ${HERE})`);
+}
+function sha256(s) {
+    return `sha256:${crypto.createHash('sha256').update(s, 'utf-8').digest('hex')}`;
+}
+const TAGS = readScm('tags.scm');
+const IMPORTS = readScm('imports.scm');
+const TAGS_HASH = sha256(TAGS);
+const IMPORTS_HASH = sha256(IMPORTS);
+const parser = {
+    grammarForLang: () => loadGrammarWasm(C_WASM_BASENAME, C_WASM_NODE_MODULES_SPEC),
+    grammarNameForLang: () => C_GRAMMAR_NAME,
+    grammarHashForLang: () => grammarHashForWasm(C_WASM_BASENAME, C_WASM_NODE_MODULES_SPEC),
+};
+const queries = {
+    tags: { name: 'tags', sourceForLang: () => TAGS, hashForLang: () => TAGS_HASH },
+    imports: { name: 'imports', sourceForLang: () => IMPORTS, hashForLang: () => IMPORTS_HASH },
+    enclosingStatementNodeTypes: ['preproc_include'],
+    captureMap: [
+        { capture: 'definition.function.node', field: 'node', subtype: 'function' },
+        { capture: 'definition.function.name', field: 'name' },
+        { capture: 'definition.class.node', field: 'node', subtype: 'class' },
+        { capture: 'definition.class.name', field: 'name' },
+        { capture: 'definition.c.union.node', field: 'node', subtype: 'c.union' },
+        { capture: 'definition.c.union.name', field: 'name' },
+        { capture: 'definition.enum.node', field: 'node', subtype: 'enum' },
+        { capture: 'definition.enum.name', field: 'name' },
+        { capture: 'definition.type.node', field: 'node', subtype: 'type' },
+        { capture: 'definition.type.name', field: 'name' },
+        { capture: 'definition.macro.node', field: 'node', subtype: 'macro' },
+        { capture: 'definition.macro.name', field: 'name' },
+        { capture: 'import.source', field: 'source' },
+    ],
+};
+const vocabulary = {
+    nodeSubtypes: ['function', 'class', 'c.union', 'enum', 'type', 'macro'],
+    edgeKinds: ['contains', 'defines', 'imports'],
+    captureMap: queries.captureMap,
+};
+const capabilities = {
+    tiers: ['T1.definitions', 'T2.imports'],
+    proven: {
+        'T1.definitions': true,
+        'T2.imports': true,
+        'T3.import_resolution': false,
+        'T4.tests_for': false,
+    },
+};
+/**
+ * Strip the wrapping from a C `#include` path token: `<stdio.h>` → `stdio.h`
+ * (angle brackets) or `"config.h"` → `config.h` (double quotes). Leaves an
+ * already-bare path untouched.
+ */
+function stripIncludeWrapping(s) {
+    if (s.length >= 2 && s.startsWith('<') && s.endsWith('>'))
+        return s.slice(1, -1);
+    if (s.length >= 2 && s.startsWith('"') && s.endsWith('"'))
+        return s.slice(1, -1);
+    return s;
+}
+export class CProvider {
+    id = 'c';
+    displayName = 'C';
+    languages = ['c'];
+    extensions = ['.c', '.h'];
+    priority = 0;
+    version = '0.1.0';
+    parser = parser;
+    queries = queries;
+    vocabulary = vocabulary;
+    capabilities = capabilities;
+    langForPath(_p) {
+        return 'c';
+    }
+    async extractDraft(input, _services) {
+        return extractWithQueries({
+            providerId: this.id,
+            lang: input.lang,
+            source: input.source,
+            sizeBytes: input.sizeBytes,
+            maxParseFileBytes: input.maxParseFileBytes,
+            maxQueryWaitMs: input.maxQueryWaitMs,
+            path: input.path,
+            grammarForLang: this.parser.grammarForLang,
+            tagsSource: TAGS,
+            tagsHash: TAGS_HASH,
+            importsSource: IMPORTS,
+            importsHash: IMPORTS_HASH,
+            enclosingStatementNodeTypes: queries.enclosingStatementNodeTypes,
+        });
+    }
+    /** Drafts-only: strip the `<...>`/`"..."` wrapping from each include path. */
+    refine(draft, _ctx) {
+        if (draft.imports.length === 0)
+            return draft;
+        const imports = draft.imports.map((im) => ({ ...im, source: stripIncludeWrapping(im.source) }));
+        return { ...draft, imports };
+    }
+}
+export const cProvider = new CProvider();
+//# sourceMappingURL=index.js.map

package/dist/core/code-map/lang/c/tags.scm

@@ -0,0 +1,68 @@
+; Code Map — C definitions (tags.scm). Provider #6 (langs batch 2).
+;
+; Capture-name convention (query-runtime.ts is the contract):
+;   @definition.<subtype>.node = identity-span anchor (the whole declaration)
+;   @definition.<subtype>.name = the symbol name node
+; Subtypes: function/type/enum/macro are universal; a named C struct maps to
+; `class` (the named aggregate devs search for like a class); a union has no
+; universal peer so it is provider-namespaced → `c.union`.
+;
+; C's function grammar is NESTED: a function_definition's name lives inside a
+; `function_declarator declarator: (identifier)`, and that function_declarator is
+; wrapped in one `pointer_declarator` PER `*` on the return type
+; (`char *f()` → 1 level, `char **f()` → 2). Tree-sitter queries can't express
+; arbitrary depth, so the `declarator:` field is an alternation covering 0..3
+; pointer levels (covers all real C; 3 stars on a return type is already exotic).
+;
+; struct/union/enum REQUIRE a `body:` so only real DEFINITIONS are captured, never
+; references. Without it, `typedef struct Point PointT;` (an aggregate REFERENCE)
+; would double-capture a phantom `class:Point` at a second span. The named-aggregate
+; struct DEFINITION inside a `typedef struct Foo {..} Bar;` still matches (it has a
+; body) and coexists with the typedef's `type:Bar` — genuinely two named entities.
+
+(function_definition
+  declarator: [
+    (function_declarator
+      declarator: (identifier) @definition.function.name)
+    (pointer_declarator
+      (function_declarator
+        declarator: (identifier) @definition.function.name))
+    (pointer_declarator
+      (pointer_declarator
+        (function_declarator
+          declarator: (identifier) @definition.function.name)))
+    (pointer_declarator
+      (pointer_declarator
+        (pointer_declarator
+          (function_declarator
+            declarator: (identifier) @definition.function.name))))
+  ]) @definition.function.node
+
+(struct_specifier
+  name: (type_identifier) @definition.class.name
+  body: (field_declaration_list)) @definition.class.node
+
+(union_specifier
+  name: (type_identifier) @definition.c.union.name
+  body: (field_declaration_list)) @definition.c.union.node
+
+(enum_specifier
+  name: (type_identifier) @definition.enum.name
+  body: (enumerator_list)) @definition.enum.node
+
+; typedefs are structurally varied; capture the declared name best-effort — the
+; bare declared type_identifier and the `typedef char *Str;` pointer wrapping.
+(type_definition
+  declarator: (type_identifier) @definition.type.name) @definition.type.node
+
+(type_definition
+  declarator: (pointer_declarator
+    declarator: (type_identifier) @definition.type.name)) @definition.type.node
+
+; `#define NAME value` and `#define NAME(x) ...` are both macros (object-like and
+; function-like); the name is the identifier in either case.
+(preproc_def
+  name: (identifier) @definition.macro.name) @definition.macro.node
+
+(preproc_function_def
+  name: (identifier) @definition.macro.name) @definition.macro.node

package/dist/core/code-map/lang/cpp/imports.scm

@@ -0,0 +1,14 @@
+; Code Map — C++ imports (imports.scm). Provider #? (langs batch 2).
+;
+; enclosingStatementNodeTypes = [preproc_include] (the include span/ordinal anchor).
+; A C++ `#include` path is either a `system_lib_string` (`<vector>`, `<sys/types.h>`)
+; or a `string_literal` (`"config.h"`). Both carry their surrounding delimiters in
+; the captured text, so the provider's refine() strips the `<>`/`"` to the bare path
+; (the runtime's stripQuotes handles the quote case; refine also strips the angle
+; brackets the runtime leaves in place). One preproc_include = one module node.
+;
+; C++20 `import` modules (`import std;`) are intentionally NOT captured in v1 — rare
+; in practice and grammar-version-dependent.
+
+(preproc_include
+  path: [(system_lib_string) (string_literal)] @import.source)

package/dist/core/code-map/lang/cpp/index.js

@@ -0,0 +1,149 @@
+/**
+ * Code Map langs batch 2 — CppProvider (C++).
+ *
+ * Owns `.cpp`/`.cc`/`.cxx`/`.hpp`/`.hh`/`.h` (runtime lang `cpp`). tree-sitter-cpp
+ * is a superset of tree-sitter-c, so the C `#include`/function shapes apply and the
+ * curated `tags.scm`/`imports.scm` (this dir) add the C++-only constructs. Definition
+ * subtypes are fixed by the query (class_specifier/struct_specifier→class,
+ * enum_specifier→enum, namespace_definition→namespace, function_declarator→
+ * function/method, preproc_def(_function)→macro, typedef/using→type — all universal).
+ * `refine()` carries only what the import query cannot express structurally: a C++
+ * include path is a delimited literal (`<vector>` / `"config.h"`), so strip the
+ * surrounding `<>`/`"` to the bare path.
+ *
+ * `.h` is AMBIGUOUS C/C++: this provider claims `.h` at priority 0, and the C
+ * provider may claim it too — the registry's deterministic collision order decides
+ * the winner; core is NOT special-cased here.
+ *
+ * NO exports edges — C++ has no export statement (visibility is
+ * access-specifiers/headers; capabilities: T2 = imports). Identity is owned by the
+ * CORE finalizer — this provider mints NO ids. The grammar loads through the SHARED
+ * engine glue (`loadGrammarWasm`), never a fresh `web-tree-sitter` import (trp_8df65ab7).
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { loadGrammarWasm, grammarHashForWasm } from '../../wasm-loader.js';
+import { extractWithQueries } from '../query-runtime.js';
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const CPP_WASM_BASENAME = 'tree-sitter-cpp.wasm';
+const CPP_WASM_NODE_MODULES_SPEC = 'tree-sitter-wasms/out/tree-sitter-cpp.wasm';
+const CPP_GRAMMAR_NAME = 'tree-sitter-cpp';
+/** Resolve a vendored `.scm` next to this module (dist) or from the source tree. */
+function readScm(basename) {
+    const local = path.join(HERE, basename);
+    if (fs.existsSync(local))
+        return fs.readFileSync(local, 'utf-8');
+    let dir = HERE;
+    for (let i = 0; i < 12; i++) {
+        if (fs.existsSync(path.join(dir, 'package.json'))) {
+            const fromSrc = path.join(dir, 'src', 'core', 'code-map', 'lang', 'cpp', basename);
+            if (fs.existsSync(fromSrc))
+                return fs.readFileSync(fromSrc, 'utf-8');
+            break;
+        }
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`code-map: could not locate query asset ${basename} (from ${HERE})`);
+}
+function sha256(s) {
+    return `sha256:${crypto.createHash('sha256').update(s, 'utf-8').digest('hex')}`;
+}
+const TAGS = readScm('tags.scm');
+const IMPORTS = readScm('imports.scm');
+const TAGS_HASH = sha256(TAGS);
+const IMPORTS_HASH = sha256(IMPORTS);
+const parser = {
+    grammarForLang: () => loadGrammarWasm(CPP_WASM_BASENAME, CPP_WASM_NODE_MODULES_SPEC),
+    grammarNameForLang: () => CPP_GRAMMAR_NAME,
+    grammarHashForLang: () => grammarHashForWasm(CPP_WASM_BASENAME, CPP_WASM_NODE_MODULES_SPEC),
+};
+const queries = {
+    tags: { name: 'tags', sourceForLang: () => TAGS, hashForLang: () => TAGS_HASH },
+    imports: { name: 'imports', sourceForLang: () => IMPORTS, hashForLang: () => IMPORTS_HASH },
+    enclosingStatementNodeTypes: ['preproc_include'],
+    captureMap: [
+        { capture: 'definition.class.node', field: 'node', subtype: 'class' },
+        { capture: 'definition.class.name', field: 'name' },
+        { capture: 'definition.enum.node', field: 'node', subtype: 'enum' },
+        { capture: 'definition.enum.name', field: 'name' },
+        { capture: 'definition.cpp.union.node', field: 'node', subtype: 'cpp.union' },
+        { capture: 'definition.cpp.union.name', field: 'name' },
+        { capture: 'definition.namespace.node', field: 'node', subtype: 'namespace' },
+        { capture: 'definition.namespace.name', field: 'name' },
+        { capture: 'definition.function.node', field: 'node', subtype: 'function' },
+        { capture: 'definition.function.name', field: 'name' },
+        { capture: 'definition.method.node', field: 'node', subtype: 'method' },
+        { capture: 'definition.method.name', field: 'name' },
+        { capture: 'definition.macro.node', field: 'node', subtype: 'macro' },
+        { capture: 'definition.macro.name', field: 'name' },
+        { capture: 'definition.type.node', field: 'node', subtype: 'type' },
+        { capture: 'definition.type.name', field: 'name' },
+        { capture: 'import.source', field: 'source' },
+    ],
+};
+const vocabulary = {
+    nodeSubtypes: ['class', 'enum', 'cpp.union', 'namespace', 'function', 'method', 'macro', 'type'],
+    edgeKinds: ['contains', 'defines', 'imports'],
+    captureMap: queries.captureMap,
+};
+const capabilities = {
+    tiers: ['T1.definitions', 'T2.imports'],
+    proven: {
+        'T1.definitions': true,
+        'T2.imports': true,
+        'T3.import_resolution': false,
+        'T4.tests_for': false,
+    },
+};
+/** Strip the surrounding delimiters from a C++ include path (`<vector>`/`"a.h"`). */
+function stripIncludeDelimiters(s) {
+    return s.replace(/^[<"]/, '').replace(/[>"]$/, '');
+}
+export class CppProvider {
+    id = 'cpp';
+    displayName = 'C++';
+    languages = ['cpp'];
+    // `.h` is ambiguous C/C++; claimed at priority 0 and resolved by the registry's
+    // deterministic collision order if the C provider also claims it (no core special-case).
+    extensions = ['.cpp', '.cc', '.cxx', '.hpp', '.hh', '.h'];
+    priority = 0;
+    version = '0.1.0';
+    parser = parser;
+    queries = queries;
+    vocabulary = vocabulary;
+    capabilities = capabilities;
+    langForPath(_p) {
+        return 'cpp';
+    }
+    async extractDraft(input, _services) {
+        return extractWithQueries({
+            providerId: this.id,
+            lang: input.lang,
+            source: input.source,
+            sizeBytes: input.sizeBytes,
+            maxParseFileBytes: input.maxParseFileBytes,
+            maxQueryWaitMs: input.maxQueryWaitMs,
+            path: input.path,
+            grammarForLang: this.parser.grammarForLang,
+            tagsSource: TAGS,
+            tagsHash: TAGS_HASH,
+            importsSource: IMPORTS,
+            importsHash: IMPORTS_HASH,
+            enclosingStatementNodeTypes: queries.enclosingStatementNodeTypes,
+        });
+    }
+    /** Drafts-only: strip the delimiters from each include path (`<vector>` → `vector`). */
+    refine(draft, _ctx) {
+        if (draft.imports.length === 0)
+            return draft;
+        const imports = draft.imports.map((im) => ({ ...im, source: stripIncludeDelimiters(im.source) }));
+        return { ...draft, imports };
+    }
+}
+export const cppProvider = new CppProvider();
+//# sourceMappingURL=index.js.map

package/dist/core/code-map/lang/cpp/tags.scm

@@ -0,0 +1,87 @@
+; Code Map — C++ definitions (tags.scm). Provider #? (langs batch 2).
+;
+; Capture-name convention (query-runtime.ts is the contract):
+;   @definition.<subtype>.node = identity-span anchor (the declaration)
+;   @definition.<subtype>.name = the symbol name node
+; Subtypes are all UNIVERSAL: class/enum/namespace/function/method/macro/type
+; (a C++ struct maps to `class` — the named aggregate devs search for like a class;
+; `enum` and `enum class` both map to `enum`).
+;
+; DOUBLE-MATCH avoidance (the CRITICAL rule): a `*_specifier` node is emitted by
+; tree-sitter-cpp BOTH where a type is DEFINED and where it is merely USED as a
+; type (`struct Point p;`, `friend class Bar;`, `enum Color c;`). Requiring
+; `body: (_)` restricts each class/struct/enum pattern to the DEFINITION site, so a
+; type is captured exactly once (and use-sites/forward-decls are never mis-emitted).
+; struct→class and class→class share the `class` subtype but are distinct grammar
+; nodes, so they never co-match the same node.
+;
+; TEMPLATES are transparent: `template <...> class/struct/function` wraps the inner
+; specifier/definition, which the same patterns below capture directly (the
+; template_declaration wrapper carries no name of its own).
+;
+; FUNCTIONS anchor on `function_declarator` (the canonical tree-sitter-cpp shape),
+; NOT `function_definition`: this makes name capture immune to return-type
+; declarator wrapping (`int* f()`, `int& f()`, trailing-return `auto f() -> T`) and
+; keeps @node/@name in one match. The declarator's inner name node is mutually
+; exclusive per function_declarator, so the three function/method patterns can never
+; co-match the same node:
+;   identifier            -> function  (free functions; also file-scope prototypes)
+;   field_identifier      -> method    (in-class method decls / inline defs)
+;   qualified_identifier  -> method    (out-of-line member defs `Foo::bar`, name text
+;                                        is the fully-qualified path)
+; This means a member declared in-class AND defined out-of-line surfaces as TWO
+; method symbols (`bar` + `Foo::bar`) at distinct spans — accepted for v1 (aids
+; discovery, never a duplicate id). SCOPED OUT of v1: fields/member variables, enum
+; constants (enumerators), constructors/destructors/operators (their names are not
+; plain identifier/field_identifier/qualified_identifier nodes), and pointer-wrapped
+; typedefs — documented, low value, and kept out to avoid noise.
+
+; --- Aggregates (require `body:` = DEFINITION site only) ---
+(class_specifier
+  name: (type_identifier) @definition.class.name
+  body: (_)) @definition.class.node
+
+(struct_specifier
+  name: (type_identifier) @definition.class.name
+  body: (_)) @definition.class.node
+
+(enum_specifier
+  name: (type_identifier) @definition.enum.name
+  body: (_)) @definition.enum.node
+
+; union → cpp.union (namespaced, mirrors the C provider's c.union). body-guarded
+; so a union type reference / forward decl is not captured. Added because C++ wins
+; the shared `.h` extension, so header unions must be covered here too.
+(union_specifier
+  name: (type_identifier) @definition.cpp.union.name
+  body: (_)) @definition.cpp.union.node
+
+; Named namespaces only (anonymous namespaces have no `name:` and are skipped). The
+; name is a single `namespace_identifier` or, for `namespace a::b { }`, a
+; `nested_namespace_specifier` whose text is the joined path `a::b`.
+(namespace_definition
+  name: [(namespace_identifier) (nested_namespace_specifier)] @definition.namespace.name) @definition.namespace.node
+
+; --- Functions / methods (anchor on function_declarator; see header) ---
+(function_declarator
+  declarator: (identifier) @definition.function.name) @definition.function.node
+
+(function_declarator
+  declarator: (field_identifier) @definition.method.name) @definition.method.node
+
+(function_declarator
+  declarator: (qualified_identifier) @definition.method.name) @definition.method.node
+
+; --- Macros ---
+(preproc_def
+  name: (identifier) @definition.macro.name) @definition.macro.node
+
+(preproc_function_def
+  name: (identifier) @definition.macro.name) @definition.macro.node
+
+; --- Type aliases: `typedef T Name;` and `using Name = T;` ---
+(type_definition
+  declarator: (type_identifier) @definition.type.name) @definition.type.node
+
+(alias_declaration
+  name: (type_identifier) @definition.type.name) @definition.type.node

package/dist/core/code-map/lang/csharp/imports.scm

@@ -0,0 +1,20 @@
+; Code Map — C# imports (imports.scm). Provider #6 (langs batch 2).
+;
+; enclosingStatementNodeTypes = [using_directive] (the import span/ordinal anchor).
+; C# using shapes:
+;   using System.Text;          -> module System.Text
+;   using static System.Math;   -> module System.Math  (imports the type's static
+;                                  members; the whole qualified name IS the module —
+;                                  no member split like Java `import static`)
+;   using Json = Newtonsoft.Json; -> module Newtonsoft.Json + alias name `Json`
+;
+; The module reference is ALWAYS a direct qualified_name / identifier child of the
+; using_directive. An alias binding lives inside a sibling `name_equals` node (never
+; a direct qualified_name/identifier), so this single capture takes ONLY the module
+; path in every shape (plain / static / alias) — the static keyword and the alias
+; are not captured here. C# has no wildcard using and no string-literal module (so
+; nothing to quote-strip). The provider's refine() lifts an alias's binding name
+; (from the `name_equals` sibling) onto the module node's imported names.
+
+(using_directive
+  [(qualified_name) (identifier)] @import.source)