brainclaw 1.9.0 → 1.10.0

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

@@ -0,0 +1,251 @@
+/**
+ * Code Map langs#3-4 — PhpProvider (provider #3; cadrage v2 §5, dec#113).
+ *
+ * Owns `.php` (runtime lang `php`). `extractDraft` delegates to the generic
+ * query-runtime; the curated `tags.scm`/`imports.scm` (this dir) drive structural
+ * extraction. `refine()` carries what the tree-sitter queries CANNOT express
+ * (all provider-local, drafts-only):
+ *  - `__construct` (grammar node `method_declaration`) → subtype `constructor`
+ *    (Codex R1: PHP has a language-level constructor; collapse into `method` would
+ *    lose that distinction). Other methods/magic methods stay `method`.
+ *  - property names: the grammar's `variable_name` node text includes the leading
+ *    `$` (`$id`); the symbol name is `id` (how the property is referenced) → strip.
+ *  - GROUP use (`use A\{B, C as Bee}`): the query captures each clause's leaf name
+ *    (`B`, `C`) because NO single tree node carries the full `A\B` (Codex R1). We
+ *    walk the retained tree, find each group-use statement's prefix (`A`), and
+ *    prepend it to the leaf-name import drafts at that statement's span → full
+ *    source paths `A\B`, `A\C` (aliases already dropped by the query).
+ *
+ * NO exports edges — PHP `use` is modeled as module imports; there is no export
+ * statement (capabilities: T2 = imports).
+ *
+ * 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 php grammar .wasm: dist basename + node_modules devDep fallback spec. */
+const PHP_WASM_BASENAME = 'tree-sitter-php.wasm';
+const PHP_WASM_NODE_MODULES_SPEC = 'tree-sitter-wasms/out/tree-sitter-php.wasm';
+const PHP_GRAMMAR_NAME = 'tree-sitter-php';
+/** 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/php/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/php/.
+    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', 'php', 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(PHP_WASM_BASENAME, PHP_WASM_NODE_MODULES_SPEC),
+    grammarNameForLang: () => PHP_GRAMMAR_NAME,
+    grammarHashForLang: () => grammarHashForWasm(PHP_WASM_BASENAME, PHP_WASM_NODE_MODULES_SPEC),
+};
+const queries = {
+    tags: {
+        name: 'tags',
+        sourceForLang: () => TAGS,
+        hashForLang: () => TAGS_HASH,
+    },
+    imports: {
+        name: 'imports',
+        sourceForLang: () => IMPORTS,
+        hashForLang: () => IMPORTS_HASH,
+    },
+    // PHP `use` declarations are the import statement; PHP has no export statement.
+    enclosingStatementNodeTypes: ['namespace_use_declaration'],
+    // P1b §3.4 / cadrage: every capture mirrors the hard-coded runtime convention and
+    // is validated by `assertCaptureMapConforms`. PHP invents none beyond the
+    // namespaced `php.trait` subtype (still a definition.<subtype>.* capture).
+    captureMap: [
+        { capture: 'definition.namespace.node', field: 'node', subtype: 'namespace' },
+        { capture: 'definition.namespace.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.php.trait.node', field: 'node', subtype: 'php.trait' },
+        { capture: 'definition.php.trait.name', field: 'name' },
+        { capture: 'definition.enum.node', field: 'node', subtype: 'enum' },
+        { capture: 'definition.enum.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.constant.node', field: 'node', subtype: 'constant' },
+        { capture: 'definition.constant.name', field: 'name' },
+        { capture: 'definition.property.node', field: 'node', subtype: 'property' },
+        { capture: 'definition.property.name', field: 'name' },
+        { capture: 'import.source', field: 'source' },
+    ],
+};
+const vocabulary = {
+    nodeSubtypes: [
+        'namespace',
+        'class',
+        'interface',
+        'php.trait',
+        'enum',
+        'function',
+        'method',
+        'constructor',
+        'constant',
+        'property',
+    ],
+    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,
+    },
+};
+/** Build a span key matching the runtime's `spanOf` (1-based start/end line+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 USE_DECL = new Set(['namespace_use_declaration']);
+/**
+ * For each GROUP use statement (a `namespace_use_declaration` that contains a
+ * `namespace_use_group`), map its statement span → the group PREFIX (the direct
+ * `namespace_name` child, e.g. `App\Util`). The runtime emitted one import draft
+ * per group leaf (sources are the bare leaf names) at that statement's span;
+ * refine prepends `prefix\` to each.
+ */
+function groupPrefixBySpan(tree) {
+    const out = new Map();
+    for (const decl of collectByType(tree.rootNode, USE_DECL)) {
+        let group = null;
+        let prefix = null;
+        for (let i = 0; i < decl.namedChildCount; i++) {
+            const c = decl.namedChild(i);
+            if (!c)
+                continue;
+            if (c.type === 'namespace_use_group')
+                group = c;
+            else if (c.type === 'namespace_name' && !prefix)
+                prefix = c;
+        }
+        if (group && prefix)
+            out.set(spanKeyOfNode(decl), prefix.text);
+    }
+    return out;
+}
+export class PhpProvider {
+    id = 'php';
+    displayName = 'PHP';
+    languages = ['php'];
+    extensions = ['.php'];
+    priority = 0;
+    version = '0.1.0';
+    parser = parser;
+    queries = queries;
+    vocabulary = vocabulary;
+    capabilities = capabilities;
+    /** `.php` → `php`. */
+    langForPath(_p) {
+        return 'php';
+    }
+    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 §5):
+     *  - definitions: `__construct` method → constructor; property name `$x` → `x`.
+     *  - imports: synthesize full group-use source paths by prepending the prefix.
+     */
+    refine(draft, _ctx) {
+        const definitions = draft.definitions.map((d) => {
+            if (d.subtype === 'method' && d.name === '__construct') {
+                return { ...d, subtype: 'constructor' };
+            }
+            if (d.subtype === 'property' && d.name.startsWith('$')) {
+                return { ...d, name: d.name.slice(1) };
+            }
+            return d;
+        });
+        let imports = draft.imports;
+        const tree = draft.attributes?.__tree;
+        if (tree) {
+            const prefixBySpan = groupPrefixBySpan(tree);
+            if (prefixBySpan.size > 0) {
+                imports = draft.imports.map((im) => {
+                    const key = `${im.span.start_line}:${im.span.start_col}:${im.span.end_line}:${im.span.end_col}`;
+                    const prefix = prefixBySpan.get(key);
+                    // A group statement only ever produced group-leaf imports at its span;
+                    // a comma/simple `use` is a different statement (different span).
+                    return prefix ? { ...im, source: `${prefix}\\${im.source}` } : im;
+                });
+            }
+        }
+        return { ...draft, definitions, imports };
+    }
+}
+/** Singleton instance for registry wiring. */
+export const phpProvider = new PhpProvider();
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,44 @@
+; Code Map — PHP definitions (tags.scm). Provider #3 (langs#3-4).
+;
+; Capture-name convention (query-runtime.ts is the contract):
+;   @definition.<subtype>.node = the identity-span anchor (the whole declaration)
+;   @definition.<subtype>.name = the symbol name node
+; Subtypes: namespace/class/interface/enum/function/method/constant/property are
+; universal; php.trait is namespaced (a trait is NOT substitutable for an
+; interface). __construct is captured as `method` here and reclassified to
+; `constructor` in the provider's refine() (the grammar node is method_declaration).
+; enum cases and class consts both map to `constant`.
+
+(namespace_definition
+  name: (namespace_name) @definition.namespace.name) @definition.namespace.node
+
+(class_declaration
+  name: (name) @definition.class.name) @definition.class.node
+
+(interface_declaration
+  name: (name) @definition.interface.name) @definition.interface.node
+
+(trait_declaration
+  name: (name) @definition.php.trait.name) @definition.php.trait.node
+
+(enum_declaration
+  name: (name) @definition.enum.name) @definition.enum.node
+
+(enum_case
+  name: (name) @definition.constant.name) @definition.constant.node
+
+(function_definition
+  name: (name) @definition.function.name) @definition.function.node
+
+(method_declaration
+  name: (name) @definition.method.name) @definition.method.node
+
+; `const A = 1, B = 2;` yields one match per const_element (all sharing the
+; const_declaration identity span) — mirrors the JS/TS `const a,b` shared-span rule.
+(const_declaration
+  (const_element (name) @definition.constant.name)) @definition.constant.node
+
+; `public int $a, $b;` yields one match per property_element. The name node is the
+; `variable_name` (text "$a"); refine() strips the leading `$` for the symbol name.
+(property_declaration
+  (property_element (variable_name) @definition.property.name)) @definition.property.node

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

@@ -0,0 +1,9 @@
+/**
+ * The default {@link CodeLanguageProvider.isImportableSymbol}: a real, externally
+ * importable definition. Excludes synthetic `subtype:'export'` placeholders (TS
+ * export-clause nodes) so B never binds to a non-definition (Codex cadrage review).
+ */
+export function defaultImportableSymbol(node) {
+    return node.kind === 'symbol' && node.exported === true && node.subtype !== 'export';
+}
+//# sourceMappingURL=provider.js.map

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

@@ -0,0 +1,24 @@
+/**
+ * Code Map — default provider REGISTRATION list (P1b §3.2).
+ *
+ * This is the single declared EXTENSION POINT for "which language providers ship
+ * by default". Adding a language = importing its provider here and adding it to
+ * the `createRegistry(...)` call below — NOT editing `core.ts` (the orchestration)
+ * or the registry mechanics. `core.ts` imports the constructed `defaultRegistry`
+ * from this module.
+ *
+ * Registration order is the secondary collision tiebreak (after `priority`); keep
+ * it intentional. Pure construction — no behavior change vs the P1a inline
+ * `createRegistry(typeScriptProvider)` that previously lived in `core.ts`.
+ */
+import { createRegistry } from './registry.js';
+import { typeScriptProvider } from './typescript/index.js';
+import { pythonProvider } from './python/index.js';
+import { phpProvider } from './php/index.js';
+import { javaProvider } from './java/index.js';
+/**
+ * The default registry, pre-loaded with the bundled providers. Add a new
+ * provider's singleton to this `createRegistry(...)` call to register it.
+ */
+export const defaultRegistry = createRegistry(typeScriptProvider, pythonProvider, phpProvider, javaProvider);
+//# sourceMappingURL=providers.js.map

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

@@ -0,0 +1,90 @@
+; Brainclaw Code Map — Python IMPORTS query (curated, vendored).
+; Grammar: tree-sitter-python. See ./README.md for the capture-name convention.
+;
+; Python has NO export statement, so this asset emits imports ONLY (no @export.name).
+; Capabilities declare T2.imports = complete (specifiers); resolution is P1c.
+;
+; Capture -> draft mapping performed by the generic query-runtime:
+;   @import.source       -> ImportDraft.source (the runtime strips surrounding quotes;
+;                           Python module names are bare identifiers/dotted_names, so
+;                           there is nothing to strip — the text passes through verbatim,
+;                           which is exactly what relative-import dots `.` / `..pkg`
+;                           need). ALSO anchors ImportDraft.span = enclosing
+;                           import_statement / import_from_statement.
+;   @import.named.name   -> a source-side imported name (the `from x import NAME` target,
+;                           NOT the local alias; `*` for a wildcard import)
+;   @import.default.name -> (unused for Python — no default-import concept)
+;   @import.namespace.name -> (unused for Python — `import x as y` is a source-side
+;                           module node, not a namespace specifier)
+;
+; MULTI-SOURCE awareness (spec §3.3 / §6): the runtime groups module nodes PER captured
+; @import.source NODE, not per enclosing statement. So `import a, b` — one statement with
+; two `name:` children — yields TWO @import.source captures and therefore TWO module
+; nodes. For a `from x import a, b` statement the single module_name source node is
+; captured once per imported `name:` child across N matches; the runtime accumulates all
+; the names onto the one source node (keyed by node id). The span/ordinal stay anchored
+; on the enclosing statement.
+
+; ===========================================================================
+; `import` STATEMENTS   (import x / import x.y / import a, b / import x as y)
+; ===========================================================================
+
+; import x   /   import x.y   /   import a, b
+; Each `name:` child that is a bare dotted_name is one module source. A multi-source
+; statement (`import a, b`) has multiple `name:` children => multiple matches =>
+; multiple @import.source captures => multiple module nodes.
+(import_statement
+  name: (dotted_name) @import.source)
+
+; import x as y   ->   source-side module is `x`; the alias `y` is ignored (imported
+; names are source-side). Capture the INNER dotted_name only (NOT the aliased_import).
+(import_statement
+  name: (aliased_import
+    name: (dotted_name) @import.source))
+
+; ===========================================================================
+; `from … import …` STATEMENTS
+; ===========================================================================
+
+; from x import a   /   from x.y import a, b
+; One match per imported `name:` child; all share the single module_name source node,
+; so the runtime accumulates a, b onto module `x` (grouped by source-node id).
+(import_from_statement
+  module_name: (dotted_name) @import.source
+  name: (dotted_name) @import.named.name)
+
+; from x import a as c   ->   source-side imported name is `a` (alias `c` ignored).
+(import_from_statement
+  module_name: (dotted_name) @import.source
+  name: (aliased_import
+    name: (dotted_name) @import.named.name))
+
+; from x import *   ->   the wildcard_import node's text is `*`, captured as the name.
+(import_from_statement
+  module_name: (dotted_name) @import.source
+  (wildcard_import) @import.named.name)
+
+; ===========================================================================
+; RELATIVE `from … import …`   (from . import z / from ..pkg import a, b / *)
+;
+; The relative_import node's TEXT is the verbatim specifier WITH its leading dots
+; (`.`, `..`, `..pkg`) — that text IS how the relative-import level survives without a
+; durable-attribute field (spec §6); P1c resolution consumes the dots. Capturing the
+; relative_import node directly as @import.source preserves it verbatim.
+; ===========================================================================
+
+; from . import z   /   from ..pkg import a, b
+(import_from_statement
+  module_name: (relative_import) @import.source
+  name: (dotted_name) @import.named.name)
+
+; from .pkg import a as c
+(import_from_statement
+  module_name: (relative_import) @import.source
+  name: (aliased_import
+    name: (dotted_name) @import.named.name))
+
+; from . import *
+(import_from_statement
+  module_name: (relative_import) @import.source
+  (wildcard_import) @import.named.name)