brainclaw 1.9.0 → 1.10.0

package/dist/core/code-map/indexes.js

@@ -0,0 +1,197 @@
+/**
+ * Code Map index builders (spec §5.6, §5.7).
+ *
+ * Both indexes are derived purely from `files/**` shards and written atomically
+ * (store.ts uses writeFileAtomic). Queries answer from these + shards alone;
+ * materialized JSONL is never required.
+ *
+ * Ordering is deterministic so two refreshes over identical inputs produce
+ * byte-identical indexes (concurrency rule 5 spirit; helps "no JSONL committed"
+ * diffs stay clean).
+ */
+import { CODE_MAP_SCHEMA_VERSION, } from './types.js';
+import { fileNodeId } from './ids.js';
+/** Lowercase token normalization (spec §5.6 keys). */
+function tokenize(name) {
+    const lower = name.toLowerCase();
+    const tokens = new Set();
+    tokens.add(lower);
+    // split camelCase / snake / kebab boundaries into sub-tokens for partial recall
+    for (const part of name.split(/[^A-Za-z0-9]+/)) {
+        if (!part)
+            continue;
+        // camelCase split
+        for (const sub of part.replace(/([a-z0-9])([A-Z])/g, '$1 $2').split(/\s+/)) {
+            if (sub)
+                tokens.add(sub.toLowerCase());
+        }
+    }
+    return [...tokens];
+}
+export function buildSymbolsIndex(projectId, shards, extractorVersion) {
+    // Null-proto map: symbol-name tokens can collide with Object.prototype members
+    // (e.g. a method named `constructor`, or a `__proto__` key), which would make
+    // `entries[token] ??= []` see the inherited function and crash on .push, or make
+    // `entries['__proto__'] = …` mutate the prototype instead of adding a key.
+    const entries = Object.create(null);
+    // Deterministic shard order by path.
+    const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
+    for (const shard of ordered) {
+        for (const node of shard.nodes) {
+            if (node.kind !== 'symbol')
+                continue;
+            const entry = {
+                node_id: node.id,
+                name: node.name,
+                kind: node.kind,
+                subtype: node.subtype ?? null,
+                path: node.path,
+                file_id: shard.file_id,
+                score_hint: node.exported ? 1.0 : 0.8,
+            };
+            for (const token of tokenize(node.name)) {
+                (entries[token] ??= []).push(entry);
+            }
+        }
+    }
+    // Deterministic ordering within each token bucket.
+    for (const token of Object.keys(entries)) {
+        entries[token].sort((a, b) => a.path.localeCompare(b.path) ||
+            a.name.localeCompare(b.name) ||
+            a.node_id.localeCompare(b.node_id));
+    }
+    // Sort keys for byte-stable output.
+    const sortedEntries = Object.create(null);
+    for (const key of Object.keys(entries).sort())
+        sortedEntries[key] = entries[key];
+    return {
+        schema_version: CODE_MAP_SCHEMA_VERSION,
+        project_id: projectId,
+        updated_at: new Date().toISOString(),
+        extractor_version: extractorVersion,
+        entries: sortedEntries,
+    };
+}
+export function buildImportsIndex(projectId, shards) {
+    // module specifier -> (path -> entry)
+    const byModule = new Map();
+    const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
+    for (const shard of ordered) {
+        for (const node of shard.nodes) {
+            if (node.kind !== 'module')
+                continue;
+            const module = node.name;
+            const perPath = byModule.get(module) ?? new Map();
+            const entry = perPath.get(shard.path) ?? {
+                path: shard.path,
+                file_id: shard.file_id,
+                imported: [],
+            };
+            // Merge imported bindings across multiple imports of the same module in one
+            // file, deduped + sorted for byte-stable output (spec §5.7 imported[]).
+            const merged = new Set(entry.imported);
+            for (const name of node.imported_names ?? [])
+                merged.add(name);
+            entry.imported = [...merged].sort();
+            perPath.set(shard.path, entry);
+            byModule.set(module, perPath);
+        }
+    }
+    const entries = Object.create(null);
+    for (const key of [...byModule.keys()].sort()) {
+        const list = [...byModule.get(key).values()].sort((a, b) => a.path.localeCompare(b.path));
+        entries[key] = list;
+    }
+    return {
+        schema_version: CODE_MAP_SCHEMA_VERSION,
+        project_id: projectId,
+        updated_at: new Date().toISOString(),
+        entries,
+    };
+}
+/**
+ * P1d reverse-dependency index: "who imports this target". Derived from the P1c
+ * resolution edges that live on each IMPORTER's shard:
+ *  - `resolves_to` (module → target FILE node) → `dependents_by_file[targetPath]`
+ *  - `imports_symbol` (module → target SYMBOL node) → `dependents_by_symbol[nodeId]`
+ *
+ * `resolves_to.to` is a file NODE ID (not a path), so we invert fileNodeId→path by
+ * computing the id for every indexed shard (Codex review). One entry per (target,
+ * importer file): multiple module nodes in one importer that hit the same target are
+ * merged (imported names unioned, strongest confidence, lexicographically-smallest
+ * specifier) for byte-stable output. Deterministic key + array ordering.
+ */
+export function buildResolutionIndex(projectId, shards) {
+    // Invert file-node id → path so reverse resolves_to can be keyed by target path.
+    const fileNodeIdToPath = new Map();
+    for (const shard of shards) {
+        fileNodeIdToPath.set(fileNodeId(projectId, shard.path, shard.lang), shard.path);
+    }
+    // target key -> (importer path -> merged entry)
+    const byFile = new Map();
+    const bySymbol = new Map();
+    const addDependent = (bucket, targetKey, importerPath, importerFileId, module, imported, confidence) => {
+        const perImporter = bucket.get(targetKey) ?? new Map();
+        const prev = perImporter.get(importerPath);
+        if (!prev) {
+            perImporter.set(importerPath, {
+                path: importerPath,
+                file_id: importerFileId,
+                module,
+                imported: [...new Set(imported)].sort(),
+                confidence,
+            });
+        }
+        else {
+            // Merge a second edge from the same importer to the same target.
+            const mergedNames = new Set(prev.imported);
+            for (const n of imported)
+                mergedNames.add(n);
+            prev.imported = [...mergedNames].sort();
+            if (module && (!prev.module || module < prev.module))
+                prev.module = module; // smallest spec, stable
+            if (typeof confidence === 'number') {
+                prev.confidence = typeof prev.confidence === 'number' ? Math.max(prev.confidence, confidence) : confidence;
+            }
+        }
+        bucket.set(targetKey, perImporter);
+    };
+    const ordered = [...shards].sort((a, b) => a.path.localeCompare(b.path));
+    for (const shard of ordered) {
+        // module node id -> its specifier + imported names (for reason metadata).
+        const moduleById = new Map();
+        for (const n of shard.nodes) {
+            if (n.kind === 'module')
+                moduleById.set(n.id, { name: n.name, imported: n.imported_names ?? [] });
+        }
+        for (const e of shard.edges) {
+            if (e.kind !== 'resolves_to' && e.kind !== 'imports_symbol')
+                continue;
+            const mod = moduleById.get(e.from);
+            if (e.kind === 'resolves_to') {
+                const targetPath = fileNodeIdToPath.get(e.to);
+                if (!targetPath)
+                    continue; // target id not an indexed file (defensive)
+                addDependent(byFile, targetPath, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence);
+            }
+            else {
+                addDependent(bySymbol, e.to, shard.path, shard.file_id, mod?.name, mod?.imported ?? [], e.confidence);
+            }
+        }
+    }
+    const finalize = (bucket) => {
+        const out = Object.create(null);
+        for (const key of [...bucket.keys()].sort()) {
+            out[key] = [...bucket.get(key).values()].sort((a, b) => a.path.localeCompare(b.path));
+        }
+        return out;
+    };
+    return {
+        schema_version: CODE_MAP_SCHEMA_VERSION,
+        project_id: projectId,
+        updated_at: new Date().toISOString(),
+        dependents_by_file: finalize(byFile),
+        dependents_by_symbol: finalize(bySymbol),
+    };
+}
+//# sourceMappingURL=indexes.js.map

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

@@ -0,0 +1,17 @@
+; Code Map — Java imports (imports.scm). Provider #4 (langs#3-4).
+;
+; enclosingStatementNodeTypes = [import_declaration] (provider declaration); that
+; statement is the import span/ordinal anchor. Java import shapes (Codex R1):
+;   import a.b.C;            -> module a.b.C
+;   import a.b.*;            -> module a.b   + imported name '*'
+;   import static a.b.C.m;   -> module a.b.C + imported name 'm'   (split type/member)
+;   import static a.b.C.*;   -> module a.b.C + imported name '*'
+;
+; A single capture takes the scoped_identifier path verbatim (e.g. "a.b.C" or, for a
+; wildcard import, the package "a.b" — the grammar puts the `*` in a sibling
+; `asterisk` node, NOT inside scoped_identifier). The provider's refine() inspects
+; each import_declaration for the `static` keyword and the `asterisk` sibling and
+; rewrites source/imported-names accordingly (the static-split and wildcard rules
+; can't be expressed structurally without overlapping matches).
+
+(import_declaration [(scoped_identifier) (identifier)] @import.source)

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

@@ -0,0 +1,254 @@
+/**
+ * Code Map langs#3-4 — JavaProvider (provider #4; cadrage v2 §6, dec#113).
+ *
+ * Owns `.java` (runtime lang `java`). `extractDraft` delegates to the generic
+ * query-runtime; the curated `tags.scm`/`imports.scm` (this dir) drive structural
+ * extraction. All definition subtypes are fixed by the query (no def
+ * reclassification needed). `refine()` carries ONLY the import shaping the
+ * structural query cannot express without overlapping matches (Codex R1):
+ *  - wildcard `import a.b.*;` → imported name `*` (the package source `a.b` is
+ *    already captured; the grammar puts `*` in a sibling `asterisk` node).
+ *  - static `import static a.b.C.m;` → split the declaring type `a.b.C` (module
+ *    source) from the member `m` (imported name); `import static a.b.C.*;` →
+ *    source `a.b.C` + name `*`.
+ *  - plain `import a.b.C;` → source `a.b.C`, no imported name.
+ *
+ * NO exports edges — Java has no export statement (capabilities: T2 = imports).
+ * Nested/inner classes + their members are emitted by the same class/method
+ * patterns; the finalizer emits only file-level contains/defines (no nesting edges).
+ *
+ * Identity is owned by the CORE finalizer — this provider mints NO ids. The grammar
+ * is loaded 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));
+/** The java grammar .wasm: dist basename + node_modules devDep fallback spec. */
+const JAVA_WASM_BASENAME = 'tree-sitter-java.wasm';
+const JAVA_WASM_NODE_MODULES_SPEC = 'tree-sitter-wasms/out/tree-sitter-java.wasm';
+const JAVA_GRAMMAR_NAME = 'tree-sitter-java';
+/** Resolve a vendored `.scm` next to this module (dist) or from the source tree. */
+function readScm(basename) {
+    // Published / dist runtime: this module is dist/core/code-map/lang/java/index.js
+    // and the build copies the .scm assets alongside it (copy-code-map-wasm.mjs).
+    const local = path.join(HERE, basename);
+    if (fs.existsSync(local))
+        return fs.readFileSync(local, 'utf-8');
+    // From-source / dist-test fallback: tsc emits to dist[-test]/... but does NOT copy
+    // .scm, so walk up to the repo root (the dir holding package.json) and read the
+    // curated asset from src/core/code-map/lang/java/.
+    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', 'java', 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')}`;
+}
+// Load the curated query assets once at module init.
+const TAGS = readScm('tags.scm');
+const IMPORTS = readScm('imports.scm');
+const TAGS_HASH = sha256(TAGS);
+const IMPORTS_HASH = sha256(IMPORTS);
+const parser = {
+    grammarForLang: () => loadGrammarWasm(JAVA_WASM_BASENAME, JAVA_WASM_NODE_MODULES_SPEC),
+    grammarNameForLang: () => JAVA_GRAMMAR_NAME,
+    grammarHashForLang: () => grammarHashForWasm(JAVA_WASM_BASENAME, JAVA_WASM_NODE_MODULES_SPEC),
+};
+const queries = {
+    tags: {
+        name: 'tags',
+        sourceForLang: () => TAGS,
+        hashForLang: () => TAGS_HASH,
+    },
+    imports: {
+        name: 'imports',
+        sourceForLang: () => IMPORTS,
+        hashForLang: () => IMPORTS_HASH,
+    },
+    // Java import declarations are the import statement; Java has no export statement.
+    enclosingStatementNodeTypes: ['import_declaration'],
+    // P1b §3.4 / cadrage: every capture mirrors the hard-coded runtime convention and
+    // is validated by `assertCaptureMapConforms`. The namespaced java.annotation /
+    // java.record are still definition.<subtype>.* captures.
+    captureMap: [
+        { capture: 'definition.package.node', field: 'node', subtype: 'package' },
+        { capture: 'definition.package.name', field: 'name' },
+        { capture: 'definition.class.node', field: 'node', subtype: 'class' },
+        { capture: 'definition.class.name', field: 'name' },
+        { capture: 'definition.interface.node', field: 'node', subtype: 'interface' },
+        { capture: 'definition.interface.name', field: 'name' },
+        { capture: 'definition.enum.node', field: 'node', subtype: 'enum' },
+        { capture: 'definition.enum.name', field: 'name' },
+        { capture: 'definition.java.annotation.node', field: 'node', subtype: 'java.annotation' },
+        { capture: 'definition.java.annotation.name', field: 'name' },
+        { capture: 'definition.java.record.node', field: 'node', subtype: 'java.record' },
+        { capture: 'definition.java.record.name', field: 'name' },
+        { capture: 'definition.method.node', field: 'node', subtype: 'method' },
+        { capture: 'definition.method.name', field: 'name' },
+        { capture: 'definition.constructor.node', field: 'node', subtype: 'constructor' },
+        { capture: 'definition.constructor.name', field: 'name' },
+        { capture: 'definition.field.node', field: 'node', subtype: 'field' },
+        { capture: 'definition.field.name', field: 'name' },
+        { capture: 'definition.constant.node', field: 'node', subtype: 'constant' },
+        { capture: 'definition.constant.name', field: 'name' },
+        { capture: 'import.source', field: 'source' },
+    ],
+};
+const vocabulary = {
+    nodeSubtypes: [
+        'package',
+        'class',
+        'interface',
+        'enum',
+        'java.annotation',
+        'java.record',
+        'method',
+        'constructor',
+        'field',
+        'constant',
+    ],
+    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,
+    },
+};
+/** A span key matching the runtime's `spanOf` (1-based start/end line+col). */
+function spanKey(span) {
+    return `${span.start_line}:${span.start_col}:${span.end_line}:${span.end_col}`;
+}
+function spanKeyOfNode(node) {
+    return `${node.startPosition.row + 1}:${node.startPosition.column + 1}:${node.endPosition.row + 1}:${node.endPosition.column + 1}`;
+}
+/** Iterative named-node DFS collecting nodes whose type is in `types`. */
+function collectByType(root, types) {
+    const found = [];
+    const stack = [root];
+    while (stack.length > 0) {
+        const n = stack.pop();
+        if (types.has(n.type))
+            found.push(n);
+        for (let i = 0; i < n.namedChildCount; i++) {
+            const c = n.namedChild(i);
+            if (c)
+                stack.push(c);
+        }
+    }
+    return found;
+}
+const IMPORT_DECL = new Set(['import_declaration']);
+/** Map each import_declaration's statement span → its static/wildcard shape. */
+function importShapesBySpan(tree) {
+    const out = new Map();
+    for (const decl of collectByType(tree.rootNode, IMPORT_DECL)) {
+        let isStatic = false;
+        let isWildcard = false;
+        // `static` is an anonymous keyword token; `asterisk` is a named node. Iterate
+        // ALL children (named + anonymous) to detect both.
+        for (let i = 0; i < decl.childCount; i++) {
+            const c = decl.child(i);
+            if (!c)
+                continue;
+            if (c.type === 'static')
+                isStatic = true;
+            else if (c.type === 'asterisk')
+                isWildcard = true;
+        }
+        out.set(spanKeyOfNode(decl), { isStatic, isWildcard });
+    }
+    return out;
+}
+export class JavaProvider {
+    id = 'java';
+    displayName = 'Java';
+    languages = ['java'];
+    extensions = ['.java'];
+    priority = 0;
+    version = '0.1.0';
+    parser = parser;
+    queries = queries;
+    vocabulary = vocabulary;
+    capabilities = capabilities;
+    /** `.java` → `java`. */
+    langForPath(_p) {
+        return 'java';
+    }
+    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 refinement (cadrage v2 §6): shape import source / imported-names
+     * per the static-split and wildcard rules. Definitions need no reclassification.
+     */
+    refine(draft, _ctx) {
+        const tree = draft.attributes?.__tree;
+        if (!tree || draft.imports.length === 0)
+            return draft;
+        const shapes = importShapesBySpan(tree);
+        if (shapes.size === 0)
+            return draft;
+        const imports = draft.imports.map((im) => {
+            const shape = shapes.get(spanKey(im.span));
+            if (!shape)
+                return im;
+            if (shape.isWildcard) {
+                // `import a.b.*` / `import static a.b.C.*` → source is the captured path; add '*'.
+                return { ...im, importedNames: ['*'] };
+            }
+            if (shape.isStatic) {
+                // `import static a.b.C.m` → split declaring type (module) vs member (name).
+                const dot = im.source.lastIndexOf('.');
+                if (dot > 0) {
+                    return {
+                        ...im,
+                        source: im.source.slice(0, dot),
+                        importedNames: [im.source.slice(dot + 1)],
+                    };
+                }
+                return im;
+            }
+            // Plain `import a.b.C` → module a.b.C, no imported name.
+            return im;
+        });
+        return { ...draft, imports };
+    }
+}
+/** Singleton instance for registry wiring. */
+export const javaProvider = new JavaProvider();
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,48 @@
+; Code Map — Java definitions (tags.scm). Provider #4 (langs#3-4).
+;
+; 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: package/class/interface/enum/method/constructor/field/constant are
+; universal; annotation types → java.annotation and records → java.record are
+; namespaced (they are class-like at the JVM level but users reason about them as
+; distinct kinds — Codex R1). Nested/inner classes are captured by the same
+; class_declaration pattern (the finalizer emits file-level contains/defines only;
+; no fabricated nesting edges). enum constants → constant; constructors are a
+; distinct grammar node (constructor_declaration → constructor, not method).
+
+(package_declaration
+  [(scoped_identifier) (identifier)] @definition.package.name) @definition.package.node
+
+(class_declaration
+  name: (identifier) @definition.class.name) @definition.class.node
+
+(interface_declaration
+  name: (identifier) @definition.interface.name) @definition.interface.node
+
+(enum_declaration
+  name: (identifier) @definition.enum.name) @definition.enum.node
+
+(enum_constant
+  name: (identifier) @definition.constant.name) @definition.constant.node
+
+(annotation_type_declaration
+  name: (identifier) @definition.java.annotation.name) @definition.java.annotation.node
+
+(record_declaration
+  name: (identifier) @definition.java.record.name) @definition.java.record.node
+
+(method_declaration
+  name: (identifier) @definition.method.name) @definition.method.node
+
+(constructor_declaration
+  name: (identifier) @definition.constructor.name) @definition.constructor.node
+
+; `int a, b;` yields one match per variable_declarator (all sharing the
+; field_declaration identity span) — mirrors the const/property multi-declarator rule.
+(field_declaration
+  declarator: (variable_declarator name: (identifier) @definition.field.name)) @definition.field.node
+
+; Annotation member declarations are method-shaped (`String value() default ""`).
+(annotation_type_element_declaration
+  name: (identifier) @definition.method.name) @definition.method.node

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

@@ -0,0 +1,21 @@
+; Code Map — PHP imports (imports.scm). Provider #3 (langs#3-4).
+;
+; enclosingStatementNodeTypes = [namespace_use_declaration] (provider declaration);
+; that statement is the import span/ordinal anchor. PHP `use` brings a namespaced
+; symbol/module into scope; the source-side path is the module specifier.
+;
+;  - simple / comma / `use function` / `use const`: each clause's qualified_name
+;    (or bare name) is the full source path → captured directly as @import.source.
+;    Aliases (`use A\B as C`) are dropped (we capture the path, not the alias) —
+;    Codex R1.
+;  - GROUP use (`use A\{B, C as Bee}`): no single tree node carries the full
+;    `A\B` (the prefix `A` and the leaf `B` are separate nodes — Codex R1). We
+;    capture each group clause's leaf name here; the provider's refine() prepends
+;    the group prefix to synthesize the full source path.
+;  - include/require are OUT of scope (dynamic/runtime, not static specifiers).
+
+(namespace_use_clause [(qualified_name) (name)] @import.source)
+
+; Group clauses only ever carry a `namespace_name` (which itself spans
+; backslash-separated paths, e.g. `B\C`); `qualified_name` is not a valid child here.
+(namespace_use_group_clause (namespace_name) @import.source)