brainclaw 1.9.1 → 1.10.0

package/dist/core/code-map/lang/query-runtime.js

@@ -0,0 +1,374 @@
+import { getParser, getQueryClass } from '../wasm-loader.js';
+/** Process-wide compiled-query cache, keyed `${providerId}|${lang}|${queryHash}`. */
+const queryCache = new Map();
+/**
+ * Compile a query asset ONCE per `(providerId, lang, queryHash)` and cache it.
+ * Compile failure is fatal + loud (spec §7 — a broken bundled asset fails here,
+ * never a silent per-file skip).
+ */
+async function compileCached(providerId, lang, queryHash, grammar, source) {
+    const key = `${providerId}|${lang}|${queryHash}`;
+    const hit = queryCache.get(key);
+    if (hit)
+        return hit;
+    const Query = await getQueryClass();
+    // The loader's `Query` comes from the SAME engine-glue instance the grammar was
+    // loaded against (and after initEngine), so the Emscripten Module is live here.
+    // Cast to the structural shape we consume.
+    const compiled = new Query(grammar, source); // throws loudly on a broken asset
+    queryCache.set(key, compiled);
+    return compiled;
+}
+/** Test/maintenance seam: drop the compiled-query cache. */
+export function __resetQueryCache() {
+    queryCache.clear();
+}
+/** Test seam: number of distinct compiled queries currently cached. */
+export function __queryCacheSize() {
+    return queryCache.size;
+}
+function spanOf(node) {
+    return {
+        start_line: node.startPosition.row + 1,
+        start_col: node.startPosition.column + 1,
+        end_line: node.endPosition.row + 1,
+        end_col: node.endPosition.column + 1,
+    };
+}
+/** Strip surrounding quotes from a module specifier text. */
+function stripQuotes(text) {
+    return text.replace(/^['"`]|['"`]$/g, '');
+}
+/**
+ * Walk up from a capture node to the enclosing import/export STATEMENT for
+ * span/ordinal anchoring, using the PROVIDER-LOCAL set of grammar node types that
+ * count as an import/export statement (cadrage §3 / Codex R1 langs#3-4).
+ *
+ * Each provider declares its OWN statement node types via
+ * {@link QueryRuntimeInput.enclosingStatementNodeTypes} (JS/TS
+ * `import_statement`/`export_statement`; Python `import_statement`/
+ * `import_from_statement`; PHP `namespace_use_declaration`; Java
+ * `import_declaration`). The runtime uses ONLY the set passed for the CURRENT file
+ * and NEVER imports/consults a central registry — adding a language is a provider
+ * declaration, not an edit here. This is the rule-of-N generalization the P1b
+ * review predicted: the runtime previously hard-coded the JS/Python statement
+ * names, which would have silently mis-spanned PHP/Java import statements.
+ */
+function enclosingStatement(node, statementTypes) {
+    let n = node;
+    while (n) {
+        if (statementTypes.has(n.type))
+            return n;
+        n = n.parent;
+    }
+    return node;
+}
+/** Parse a `@definition.<subtype>.<role>` capture name into its parts. */
+function parseDefinitionCapture(name) {
+    const m = /^definition\.(.+)\.(node|name|exported)$/.exec(name);
+    if (!m)
+        return null;
+    return { subtype: m[1], role: m[2] };
+}
+/**
+ * The fixed import/export capture roles the runtime `switch` honors. Together with
+ * the `definition.<subtype>.(node|name|exported)` pattern, this is the COMPLETE
+ * hard-coded capture convention — THE contract (P1b §3.4). A provider's captureMap
+ * may only use these capture names.
+ */
+const FIXED_IMPORT_EXPORT_CAPTURES = new Set([
+    'import.source',
+    'import.default.name',
+    'import.namespace.name',
+    'import.named.name',
+    'export.name',
+]);
+/** True iff `name` is a capture role the hard-coded runtime convention recognizes. */
+export function isConventionCapture(name) {
+    return parseDefinitionCapture(name) !== null || FIXED_IMPORT_EXPORT_CAPTURES.has(name);
+}
+/**
+ * Validate that a provider's declared `captureMap` mirrors the hard-coded capture
+ * convention the runtime actually drives off (P1b §3.4). Throws (loud — a provider
+ * authoring bug, not a per-file error) listing any capture the runtime would
+ * silently ignore. The runtime does NOT call this on the hot path; providers/tests
+ * call it once to assert their captureMap is honest. Returns the offending captures
+ * for assertion ergonomics.
+ */
+export function assertCaptureMapConforms(captureMap) {
+    const unknown = captureMap.map((m) => m.capture).filter((c) => !isConventionCapture(c));
+    if (unknown.length > 0) {
+        throw new Error(`captureMap declares captures the runtime convention does not recognize: ${unknown.join(', ')}. ` +
+            `The hard-coded convention is THE contract (definition.<subtype>.(node|name|exported) + ` +
+            `import.source/import.default.name/import.namespace.name/import.named.name/export.name).`);
+    }
+    return unknown;
+}
+/**
+ * Run the provider's tags + imports queries over one file and produce a draft.
+ * Never throws: parse/timeout failures set `attributes.parseStatus='parse_error'`
+ * and return a file-only draft; query exceptions return the partial draft + an
+ * `extraction_error` fact.
+ */
+export async function extractWithQueries(input) {
+    const facts = [];
+    // PROVIDER-LOCAL enclosing-statement node types — the only source of truth for
+    // import/export span anchoring (cadrage §3 / Codex R1). No registry lookup.
+    const statementTypes = new Set(input.enclosingStatementNodeTypes);
+    const emptyDraft = (parseStatus, tree) => ({
+        file: { path: input.path },
+        definitions: [],
+        imports: [],
+        exports: [],
+        tests: [],
+        facts,
+        attributes: { parseStatus, __tree: tree },
+    });
+    // Oversized — never parse (mirrors legacy skipped_too_large; core emits file node).
+    if (input.sizeBytes > input.maxParseFileBytes) {
+        facts.push({
+            code: 'skipped_too_large',
+            message: `file ${input.sizeBytes} bytes exceeds max_parse_file_bytes ${input.maxParseFileBytes}`,
+        });
+        return emptyDraft('skipped_too_large', null);
+    }
+    // --- Parse (bounded by max_query_wait_ms) ---
+    let tree;
+    let parser = null;
+    try {
+        const grammar = await input.grammarForLang(input.lang);
+        const Parser = await getParser();
+        parser = new Parser();
+        // `grammarForLang` returns the engine-opaque grammar handle (typed `unknown` so
+        // the runtime stays provider-agnostic); it IS a web-tree-sitter Language here.
+        parser.setLanguage(grammar);
+        const deadline = input.maxQueryWaitMs;
+        if (typeof deadline === 'number' && deadline > 0) {
+            // web-tree-sitter parse is synchronous; the bound is advisory. We honor it by
+            // measuring wall-clock and flagging overruns (the legacy path had no timeout,
+            // so overrun → parse_error keeps us strictly no-worse than legacy).
+            const t0 = Date.now();
+            const parsed = parser.parse(input.source);
+            if (Date.now() - t0 > deadline) {
+                try {
+                    parsed?.delete();
+                }
+                catch {
+                    /* best effort */
+                }
+                facts.push({ code: 'parse_error', message: `parse exceeded max_query_wait_ms ${deadline}` });
+                return emptyDraft('parse_error', null);
+            }
+            if (!parsed) {
+                facts.push({ code: 'parse_error', message: 'parser returned null' });
+                return emptyDraft('parse_error', null);
+            }
+            tree = parsed;
+        }
+        else {
+            const parsed = parser.parse(input.source);
+            if (!parsed) {
+                facts.push({ code: 'parse_error', message: 'parser returned null' });
+                return emptyDraft('parse_error', null);
+            }
+            tree = parsed;
+        }
+    }
+    catch (err) {
+        facts.push({ code: 'parse_error', message: err instanceof Error ? err.message : String(err) });
+        return emptyDraft('parse_error', null);
+    }
+    finally {
+        // The per-file parser is no longer needed once parse() returns; the TREE stays
+        // alive for refine/finalize. Delete the parser (best effort) so each file does
+        // not leak a web-tree-sitter Parser instance.
+        if (parser) {
+            try {
+                parser.delete();
+            }
+            catch {
+                /* best effort */
+            }
+        }
+    }
+    const definitions = [];
+    const imports = [];
+    const exports = [];
+    try {
+        const grammar = await input.grammarForLang(input.lang);
+        const tagsQuery = await compileCached(input.providerId, input.lang, input.tagsHash, grammar, input.tagsSource);
+        const importsQuery = await compileCached(input.providerId, input.lang, input.importsHash, grammar, input.importsSource);
+        // --- DEFINITIONS: one DefScratch per match (each match has a .node + .name). ---
+        const defScratch = [];
+        for (const match of tagsQuery.matches(tree.rootNode)) {
+            let subtype = '';
+            let nodeNode = null;
+            let nameNode = null;
+            let exported = false;
+            for (const cap of match.captures) {
+                const parsed = parseDefinitionCapture(cap.name);
+                if (!parsed)
+                    continue;
+                if (parsed.role === 'node') {
+                    subtype = parsed.subtype;
+                    nodeNode = cap.node;
+                }
+                else if (parsed.role === 'name') {
+                    nameNode = cap.node;
+                }
+                else {
+                    exported = true;
+                }
+            }
+            if (!nodeNode || !nameNode || !subtype)
+                continue;
+            defScratch.push({
+                subtype,
+                name: nameNode.text,
+                node: nodeNode,
+                nameNode,
+                exported,
+                ordinalIndex: nameNode.startIndex,
+            });
+        }
+        // --- IMPORTS / RE-EXPORTS / LOCAL EXPORTS ---
+        // Keyed by the captured @import.source node id so one statement with N
+        // sources yields N module nodes (multi-source aware). JS/TS = one source per
+        // statement → identical to the legacy per-statement grouping.
+        const importBySource = new Map();
+        const exportScratch = [];
+        for (const match of importsQuery.matches(tree.rootNode)) {
+            let sourceNode = null;
+            let defaultName = null;
+            let namespaceName = null;
+            let namedName = null;
+            let exportName = null;
+            for (const cap of match.captures) {
+                switch (cap.name) {
+                    case 'import.source':
+                        sourceNode = cap.node;
+                        break;
+                    case 'import.default.name':
+                        defaultName = cap.node;
+                        break;
+                    case 'import.namespace.name':
+                        namespaceName = cap.node;
+                        break;
+                    case 'import.named.name':
+                        namedName = cap.node;
+                        break;
+                    case 'export.name':
+                        exportName = cap.node;
+                        break;
+                    default:
+                        break;
+                }
+            }
+            if (sourceNode) {
+                // import statement OR re-export (export … from). Group PER captured source
+                // node so a statement with N sources emits N module nodes (Python
+                // `import a, b`). span/ordinal stay anchored on the enclosing statement,
+                // which for single-source JS/TS is byte-identical to per-statement grouping.
+                const stmt = enclosingStatement(sourceNode, statementTypes);
+                const isReExport = stmt.type === 'export_statement';
+                let scratch = importBySource.get(sourceNode.id);
+                if (!scratch) {
+                    scratch = {
+                        source: stripQuotes(sourceNode.text),
+                        statement: stmt,
+                        span: spanOf(stmt),
+                        names: [],
+                        ordinalIndex: stmt.startIndex,
+                        isReExport,
+                    };
+                    importBySource.set(sourceNode.id, scratch);
+                }
+                if (defaultName)
+                    scratch.names.push('default');
+                if (namespaceName)
+                    scratch.names.push('*');
+                if (namedName)
+                    scratch.names.push(namedName.text);
+            }
+            else if (exportName) {
+                // Local export clause / default-identifier — mark-or-add at finalize.
+                exportScratch.push({
+                    name: exportName.text,
+                    node: exportName,
+                    ordinalIndex: exportName.startIndex,
+                });
+            }
+        }
+        // `export * from 'm'` matches a pattern with no name capture → names empty.
+        // Legacy supplies "*" for a sourced re-export that carried no specifier.
+        for (const scratch of importBySource.values()) {
+            if (scratch.isReExport && scratch.names.length === 0)
+                scratch.names.push('*');
+        }
+        const anchored = [];
+        for (const d of defScratch) {
+            anchored.push({
+                ordinalIndex: d.ordinalIndex,
+                emit: (ordinal) => {
+                    definitions.push({
+                        ordinal,
+                        captureName: `definition.${d.subtype}.node`,
+                        name: d.name,
+                        subtype: d.subtype,
+                        span: spanOf(d.node),
+                        nameSpan: spanOf(d.nameNode),
+                        exported: d.exported || undefined,
+                        sourceNode: { node: d.node, nameNode: d.nameNode },
+                    });
+                },
+            });
+        }
+        for (const im of importBySource.values()) {
+            anchored.push({
+                ordinalIndex: im.ordinalIndex,
+                emit: (ordinal) => {
+                    imports.push({
+                        ordinal,
+                        source: im.source,
+                        span: im.span,
+                        importedNames: im.names,
+                        isReExport: im.isReExport || undefined,
+                    });
+                },
+            });
+        }
+        for (const ex of exportScratch) {
+            anchored.push({
+                ordinalIndex: ex.ordinalIndex,
+                emit: (ordinal) => {
+                    exports.push({ ordinal, name: ex.name, span: spanOf(enclosingStatement(ex.node, statementTypes)) });
+                },
+            });
+        }
+        // Stable sort by source byte offset; ties keep insertion (def→import→export) order.
+        anchored
+            .map((a, i) => ({ a, i }))
+            .sort((x, y) => (x.a.ordinalIndex - y.a.ordinalIndex) || (x.i - y.i))
+            .forEach((wrapped, ordinal) => wrapped.a.emit(ordinal));
+    }
+    catch (err) {
+        facts.push({
+            code: 'extraction_error',
+            message: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const parseStatus = tree.rootNode.hasError ? 'parse_error' : 'parsed';
+    if (parseStatus === 'parse_error') {
+        facts.push({ code: 'parse_error', message: 'tree contains syntax errors' });
+    }
+    return {
+        file: { path: input.path },
+        definitions,
+        imports,
+        exports,
+        tests: [],
+        facts,
+        attributes: { parseStatus, __tree: tree },
+    };
+}
+//# sourceMappingURL=query-runtime.js.map

package/dist/core/code-map/lang/registry.js

@@ -0,0 +1,125 @@
+/**
+ * Code Map P1a — CodeLanguageRegistry implementation (spec §4).
+ *
+ * Maps file extensions → providers (deterministic on collision: higher `priority`
+ * wins, then earlier registration), and runtime langs → providers. Surfaces the
+ * freshness inputs (provider versions + every query-asset hash per lang) and the
+ * `manifest.languages` entries keyed by runtime CodeLang.
+ *
+ * No behavior change in P1a — refresh.ts is NOT yet routed through this (Sprint 4
+ * cutover). The registry exists so the new core path can resolve a provider for a
+ * path and so freshness can fold in query-asset hashes.
+ */
+import path from 'node:path';
+export class DefaultCodeLanguageRegistry {
+    registrations = [];
+    nextOrder = 0;
+    register(p) {
+        this.registrations.push({ provider: p, order: this.nextOrder++ });
+    }
+    /**
+     * Resolve the provider owning a path's extension. On collision: highest
+     * `priority` (default 0) wins; ties broken by EARLIEST registration order.
+     */
+    providerForPath(path_) {
+        const ext = path.extname(path_).toLowerCase();
+        if (!ext)
+            return null;
+        const candidates = this.registrations.filter((r) => r.provider.extensions.some((e) => e.toLowerCase() === ext));
+        if (candidates.length === 0)
+            return null;
+        candidates.sort((a, b) => {
+            const pa = a.provider.priority ?? 0;
+            const pb = b.provider.priority ?? 0;
+            if (pa !== pb)
+                return pb - pa; // higher priority first
+            return a.order - b.order; // then earliest registration
+        });
+        const provider = candidates[0].provider;
+        return { provider, lang: provider.langForPath(path_) };
+    }
+    providerForLang(lang) {
+        // Same collision rule as providerForPath, applied over `languages`.
+        const candidates = this.registrations.filter((r) => r.provider.languages.includes(lang));
+        if (candidates.length === 0)
+            return null;
+        candidates.sort((a, b) => {
+            const pa = a.provider.priority ?? 0;
+            const pb = b.provider.priority ?? 0;
+            if (pa !== pb)
+                return pb - pa;
+            return a.order - b.order;
+        });
+        return candidates[0].provider;
+    }
+    activeLanguages() {
+        const seen = new Set();
+        const out = [];
+        for (const { provider } of this.registrations) {
+            for (const lang of provider.languages) {
+                if (!seen.has(lang)) {
+                    seen.add(lang);
+                    out.push(lang);
+                }
+            }
+        }
+        return out;
+    }
+    includedExtensions() {
+        const seen = new Set();
+        const out = [];
+        for (const { provider } of this.registrations) {
+            for (const ext of provider.extensions) {
+                const e = ext.toLowerCase();
+                if (!seen.has(e)) {
+                    seen.add(e);
+                    out.push(e);
+                }
+            }
+        }
+        return out;
+    }
+    /**
+     * `manifest.languages` entries keyed by runtime CodeLang. The winning provider
+     * per lang (collision rule) supplies the grammar name/version/hash.
+     */
+    languageEntries() {
+        const out = {};
+        for (const lang of this.activeLanguages()) {
+            const provider = this.providerForLang(lang);
+            if (!provider)
+                continue;
+            out[lang] = {
+                enabled: true,
+                grammar_name: provider.parser.grammarNameForLang(lang),
+                grammar_version: provider.version,
+                tree_sitter_grammar_hash: provider.parser.grammarHashForLang(lang),
+            };
+        }
+        return out;
+    }
+    /**
+     * Freshness inputs: per provider, its `version` + every query-asset hash for
+     * every lang it owns. Editing a `.scm` flips a hash here → `stale_extractor`.
+     * Deterministically ordered (registration order, then lang order).
+     */
+    configHashInputs() {
+        return this.registrations.map(({ provider }) => ({
+            id: provider.id,
+            version: provider.version,
+            queries: provider.languages.map((lang) => ({
+                lang,
+                tags: provider.queries.tags.hashForLang(lang),
+                imports: provider.queries.imports.hashForLang(lang),
+            })),
+        }));
+    }
+}
+/** Convenience: build a registry pre-loaded with the given providers. */
+export function createRegistry(...providers) {
+    const reg = new DefaultCodeLanguageRegistry();
+    for (const p of providers)
+        reg.register(p);
+    return reg;
+}
+//# sourceMappingURL=registry.js.map

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

@@ -0,0 +1,90 @@
+; Brainclaw Code Map — TypeScript/TSX/JavaScript IMPORTS + EXPORTS query (curated, vendored).
+; See ./README.md for the capture-name convention and provenance.
+;
+; Capture -> draft mapping performed by the query-runtime:
+;   @import.source            -> ImportDraft.source (string literal text; quotes stripped
+;                                by the runtime). The @import.source node ALSO anchors the
+;                                ImportDraft.span = enclosing import/export statement span.
+;   @import.default.name      -> contributes source-side imported name "default"
+;   @import.namespace.name    -> contributes source-side imported name "*"
+;   @import.named.name        -> contributes source-side imported name = specifier `name`
+;                                (NOT the local alias)
+;   @export.name              -> ExportDraft.name (a re-export / mark-or-add export target)
+;
+; This asset covers: `import` statements, `export { ... }` clauses (no source),
+; `export ... from '...'` / `export * from '...'` re-exports (WITH source), and
+; `export default <identifier>`. Declaration exports (`export function/class/...`) are
+; NOT handled here — they are definitions and carry their `exported` flag from tags.scm.
+;
+; Re-export source detection is the discriminator the provider's refine() uses to build
+; a module node (no phantom symbol) vs. a local `export {a}` mark-or-add. The runtime
+; surfaces both @import.source and @export.name on a re-export match; refine() routes
+; on source presence.
+
+; ===========================================================================
+; IMPORT STATEMENTS
+; ===========================================================================
+
+; bare side-effect import:  import 'm';
+(import_statement
+  source: (string (string_fragment) @import.source))
+
+; default import:  import def from 'm';
+(import_statement
+  (import_clause (identifier) @import.default.name)
+  source: (string (string_fragment) @import.source))
+
+; namespace import:  import * as ns from 'm';
+(import_statement
+  (import_clause (namespace_import (identifier) @import.namespace.name))
+  source: (string (string_fragment) @import.source))
+
+; named imports:  import { a, b as c } from 'm';
+; `name:` is the source-side specifier name (`a`, `b`) — the alias (`c`) is the
+; `alias:` field and is deliberately NOT captured (importedNames are source-side).
+(import_statement
+  (import_clause
+    (named_imports
+      (import_specifier
+        name: (identifier) @import.named.name)))
+  source: (string (string_fragment) @import.source))
+
+; ===========================================================================
+; RE-EXPORTS WITH A SOURCE MODULE  (export { a } from 'm';  export * from 'm';)
+; These carry @import.source so refine() builds a module node + imports edge.
+; ===========================================================================
+
+; export { a, b as c } from 'm';  -> source-side names a, b
+(export_statement
+  (export_clause
+    (export_specifier
+      name: (identifier) @import.named.name))
+  source: (string (string_fragment) @import.source))
+
+; export * from 'm';  (no export_clause) -> the runtime supplies "*" for the names
+(export_statement
+  "*"
+  source: (string (string_fragment) @import.source))
+
+; export * as ns from 'm';  -> namespace re-export
+(export_statement
+  (namespace_export (identifier) @import.namespace.name)
+  source: (string (string_fragment) @import.source))
+
+; ===========================================================================
+; LOCAL EXPORT CLAUSES  (export { a, b as c };  no source module)
+; -> @export.name per source-side specifier name; refine() does mark-or-add-export.
+; ===========================================================================
+(export_statement
+  (export_clause
+    (export_specifier
+      name: (identifier) @export.name))
+  !source)
+
+; ===========================================================================
+; DEFAULT EXPORT OF AN IDENTIFIER  (export default foo;)
+; -> @export.name = the referenced identifier; refine() links it if it names a symbol.
+; ===========================================================================
+(export_statement
+  "default"
+  (identifier) @export.name)