brainclaw 1.9.1 → 1.10.0

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)

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