brainclaw 1.9.1 → 1.10.0

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)

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

@@ -0,0 +1,364 @@
+/**
+ * Code Map P1b — PythonProvider (provider #2; cadrage §5/§6).
+ *
+ * Owns `.py` (runtime lang `python`). `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
+ * syntactically (cadrage §5, all provider-local):
+ *  - class methods: a `function_definition` directly in a `class_definition` body →
+ *    subtype `method` (`__init__` included). Identity span stays the
+ *    `function_definition` (decorators excluded — the query anchors the inner node).
+ *  - nested defs (a `function_definition` NOT directly owned by a class body) →
+ *    stay `function`.
+ *  - decorator-driven: `@property` → `property`; `@staticmethod`/`@classmethod` →
+ *    `method`. Decorators are NON-emitting (no node, no persisted attribute).
+ *  - `async def` → `function`/`method` by context (async is classification-only;
+ *    NOT persisted — there is no durable attribute field).
+ *  - module-level `UPPER_CASE` simple/annotated assignment → `constant`
+ *    (else `variable`; class/instance attrs are NOT symbols, never constants).
+ *
+ * NO exports edges — Python has 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` → same initialized
+ * web-tree-sitter instance as js-ts), 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 python grammar .wasm: dist basename + node_modules devDep fallback spec. */
+const PY_WASM_BASENAME = 'tree-sitter-python.wasm';
+const PY_WASM_NODE_MODULES_SPEC = 'tree-sitter-wasms/out/tree-sitter-python.wasm';
+const PY_GRAMMAR_NAME = 'tree-sitter-python';
+/** 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/python/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/python/.
+    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', 'python', 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(PY_WASM_BASENAME, PY_WASM_NODE_MODULES_SPEC),
+    grammarNameForLang: () => PY_GRAMMAR_NAME,
+    grammarHashForLang: () => grammarHashForWasm(PY_WASM_BASENAME, PY_WASM_NODE_MODULES_SPEC),
+};
+const queries = {
+    tags: {
+        name: 'tags',
+        sourceForLang: () => TAGS,
+        hashForLang: () => TAGS_HASH,
+    },
+    imports: {
+        name: 'imports',
+        sourceForLang: () => IMPORTS,
+        hashForLang: () => IMPORTS_HASH,
+    },
+    // Python import statement node types (cadrage §3 / Codex R1): `import a, b` is an
+    // `import_statement`; `from x import …` is an `import_from_statement`. Python has
+    // no export statement. PROVIDER-LOCAL — runtime gets this per file, no registry.
+    // (Same set the old module-global carried for Python → byte-identical output.)
+    enclosingStatementNodeTypes: ['import_statement', 'import_from_statement'],
+    // P1b §3.4: the runtime drives capture→draft mapping off the HARD-CODED
+    // capture-name convention (query-runtime.ts). This captureMap is a declared
+    // MIRROR, validated by `assertCaptureMapConforms`. Every entry names a
+    // convention-recognized role; Python invents none.
+    captureMap: [
+        { capture: 'definition.function.node', field: 'node', subtype: 'function' },
+        { capture: 'definition.function.name', field: 'name' },
+        { capture: 'definition.class.node', field: 'node', subtype: 'class' },
+        { capture: 'definition.class.name', field: 'name' },
+        { capture: 'definition.variable.node', field: 'node', subtype: 'variable' },
+        { capture: 'definition.variable.name', field: 'name' },
+        { capture: 'import.source', field: 'source' },
+        { capture: 'import.named.name', field: 'imported', optional: true },
+    ],
+};
+const vocabulary = {
+    nodeSubtypes: ['function', 'method', 'class', 'variable', 'constant', 'property'],
+    edgeKinds: ['contains', 'defines', 'imports'],
+    captureMap: queries.captureMap,
+};
+const capabilities = {
+    tiers: ['T1.definitions', 'T2.imports', 'T3.import_resolution'],
+    proven: {
+        'T1.definitions': true,
+        'T2.imports': true,
+        'T3.import_resolution': true,
+        'T4.tests_for': false,
+    },
+};
+/**
+ * P1c file-level import resolution for Python (cadrage v2 §"Python"). Maps an import
+ * source string — as the provider emits it on the `module` node `name` — to a single
+ * project-internal target FILE path, or `null` (stdlib / site-packages / unresolved).
+ *
+ * Source forms (verified against the provider's golden):
+ *  - absolute dotted: `os`, `os.path`, `collections`, `pkg`, `a.b.c`
+ *  - relative: leading dots count the package level — `.` / `..` (bare, from
+ *    `from . import x`), `.mod`, `..pkg`, `..pkg.sub`.
+ *
+ * Resolution (PEP 328 file-level approximation):
+ *  - relative: N leading dots ⇒ start at the importer's DIRECTORY and walk up (N-1)
+ *    levels (1 dot = current package). The remaining dotted tail (after the dots) is
+ *    a sub-path; empty tail (bare `.`/`..`) targets that package's `__init__.py`.
+ *  - absolute dotted: resolve project-ROOT-relative (`a.b.c` → `a/b/c.py` |
+ *    `a/b/c/__init__.py`). Stdlib / third-party names simply won't exist as project
+ *    files → `null` (no edge). v1 does NOT model `src/`-layout sys.path roots — a
+ *    documented limitation; symbol/submodule precision (`from . import sib` → the
+ *    `sib` SUBMODULE rather than the package `__init__`) is the P1c-B follow-up.
+ *
+ * Candidate order is `module.py` before `package/__init__.py` (a regular module
+ * shadows a package of the same dotted name in CPython import order). The CORE
+ * verifies existence via `ctx.fileExists` and owns id/edge minting — this returns a
+ * path only (dec#108/#109).
+ */
+function resolvePyImport(source, fromPath, ctx) {
+    const candidates = [];
+    if (source.startsWith('.')) {
+        let dots = 0;
+        while (source[dots] === '.')
+            dots++;
+        const tail = source.slice(dots); // after the dots: '' | 'mod' | 'pkg.sub'
+        let base = path.posix.dirname(toPosixPy(fromPath)); // current package dir (1 dot)
+        let escapedRoot = false;
+        for (let up = 1; up < dots; up++) {
+            if (base === '' || base === '.' || base === '/') {
+                escapedRoot = true;
+                break;
+            }
+            base = path.posix.dirname(base); // ..  = parent, etc.
+        }
+        if (escapedRoot)
+            return null;
+        if (base === '.' || base === '/')
+            base = '';
+        const prefix = base ? `${base}/` : '';
+        if (tail === '') {
+            candidates.push(`${prefix}__init__.py`); // the package itself
+        }
+        else {
+            const sub = tail.replace(/\./g, '/');
+            candidates.push(`${prefix}${sub}.py`, `${prefix}${sub}/__init__.py`);
+        }
+    }
+    else {
+        // Absolute dotted module, resolved project-root-relative.
+        const sub = source.replace(/\./g, '/');
+        candidates.push(`${sub}.py`, `${sub}/__init__.py`);
+    }
+    for (const c of candidates) {
+        const norm = c.replace(/^\.\//, '');
+        if (ctx.fileExists(norm))
+            return norm;
+    }
+    return null;
+}
+function toPosixPy(p) {
+    return p.replace(/\\/g, '/');
+}
+function isDefSourceNode(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'node' in v &&
+        'nameNode' in v &&
+        typeof v.node === 'object');
+}
+const UPPER_RE = /^[A-Z_][A-Z0-9_]*$/;
+/**
+ * True iff `defNode` (a `function_definition`) is a method — i.e. directly owned by
+ * a `class_definition` body. The grammar nests a def's statements under a `block`
+ * whose parent is the `class_definition`; a decorated method is wrapped in a
+ * `decorated_definition` (also inside that `block`). So walk: function_definition →
+ * (optional decorated_definition) → block → class_definition.
+ */
+function isClassMethod(defNode) {
+    let owner = defNode.parent;
+    // A decorated def sits inside a `decorated_definition` wrapper.
+    if (owner && owner.type === 'decorated_definition')
+        owner = owner.parent;
+    if (!owner || owner.type !== 'block')
+        return false;
+    const blockParent = owner.parent;
+    return !!blockParent && blockParent.type === 'class_definition';
+}
+/**
+ * Collect decorator names applied to `defNode`. A decorated def's parent is a
+ * `decorated_definition` whose `decorator` children carry the applied names (e.g.
+ * `@property`, `@staticmethod`, `@app.route(...)`). We read each decorator's leading
+ * identifier/attribute text (best-effort) to classify property/staticmethod/classmethod.
+ */
+function decoratorNames(defNode) {
+    const wrapper = defNode.parent;
+    if (!wrapper || wrapper.type !== 'decorated_definition')
+        return [];
+    const names = [];
+    for (let i = 0; i < wrapper.namedChildCount; i++) {
+        const child = wrapper.namedChild(i);
+        if (!child || child.type !== 'decorator')
+            continue;
+        // decorator text is like `@property` / `@staticmethod` / `@app.route("/x")`.
+        // Strip the leading `@` and any call/attribute tail to get the head name.
+        const text = child.text.replace(/^@/, '').trim();
+        const head = text.split(/[(\s]/)[0]; // up to first `(` or whitespace
+        names.push(head);
+    }
+    return names;
+}
+export class PythonProvider {
+    id = 'python';
+    displayName = 'Python';
+    languages = ['python'];
+    extensions = ['.py'];
+    priority = 0;
+    version = '0.1.0';
+    parser = parser;
+    queries = queries;
+    vocabulary = vocabulary;
+    capabilities = capabilities;
+    /** `.py` → `python`. */
+    langForPath(_p) {
+        return 'python';
+    }
+    async extractDraft(input, _services) {
+        return extractDraftViaRuntime(this.id, input, this.parser.grammarForLang);
+    }
+    /**
+     * Reclassify subtypes the structural query cannot express (cadrage §5). Drafts-only.
+     *  - function in a class body → method (decorator @property → property;
+     *    @staticmethod/@classmethod → method); nested/top-level defs stay function.
+     *  - module-level UPPER_CASE assignment → constant; else stays variable.
+     * `async` is never persisted (no attribute field) — it is classification-only and
+     * does not change the subtype beyond function/method by context.
+     */
+    refine(draft, _ctx) {
+        const definitions = draft.definitions.map((d) => {
+            const src = isDefSourceNode(d.sourceNode) ? d.sourceNode : null;
+            if (d.subtype === 'function') {
+                if (!src)
+                    return d;
+                const decos = decoratorNames(src.node);
+                // @property wins as a value-like member; @staticmethod/@classmethod are methods.
+                if (decos.includes('property'))
+                    return setSubtype(d, 'property');
+                const inClass = isClassMethod(src.node);
+                if (decos.includes('staticmethod') || decos.includes('classmethod')) {
+                    return setSubtype(d, 'method');
+                }
+                return inClass ? setSubtype(d, 'method') : d; // top-level / nested stay function
+            }
+            if (d.subtype === 'variable') {
+                // Module-level UPPER_CASE → constant; the tags.scm anchors variables under
+                // (module) only, so any captured variable IS module-level.
+                return UPPER_RE.test(d.name) ? setSubtype(d, 'constant') : d;
+            }
+            return d;
+        });
+        return { ...draft, definitions };
+    }
+    /**
+     * P1c file-level import resolution (T3). Returns at most one resolution per import:
+     * the resolved project-internal target file path, or `resolvedPath: null` when the
+     * specifier points outside the project (stdlib / site-packages / unresolved). The
+     * CORE pass filters out `null` paths and mints the `resolves_to` edge.
+     */
+    async resolveImport(req, ctx) {
+        const resolvedPath = resolvePyImport(req.source, req.fromPath, ctx);
+        return [{ source: req.source, resolvedPath, confidence: resolvedPath ? 1.0 : 0 }];
+    }
+    /**
+     * P1c-B importability for Python (overrides the `exported`-based default).
+     * Python has no export statement — `node.exported` is always false — so a symbol
+     * is importable iff it is TOP-LEVEL in its module: no OTHER symbol's span STRICTLY
+     * contains it. (A class method / nested function is contained by its class/func and
+     * is therefore NOT importable as `from .mod import X`.) Cadrage D2: span containment
+     * is the SOUND mechanism — the finalizer's file→contains/defines edges are emitted
+     * for EVERY symbol (not just top-level), so they cannot prove top-level status.
+     * A symbol lacking a usable span is SKIPPED (can't prove top-level → never guess).
+     */
+    isImportableSymbol(node, fileSymbols) {
+        if (node.kind !== 'symbol')
+            return false;
+        if (node.subtype === 'export')
+            return false; // defensive (Python never emits it)
+        const span = node.span;
+        if (!span)
+            return false;
+        for (const other of fileSymbols) {
+            if (other === node || other.id === node.id)
+                continue;
+            if (other.kind !== 'symbol')
+                continue;
+            if (other.span && spanStrictlyContains(other.span, span))
+                return false; // nested → not top-level
+        }
+        return true;
+    }
+}
+/** True iff `outer` strictly contains `inner` (covers it on both ends, larger on ≥1). */
+function spanStrictlyContains(outer, inner) {
+    const startsAtOrBefore = outer.start_line < inner.start_line ||
+        (outer.start_line === inner.start_line && outer.start_col <= inner.start_col);
+    const endsAtOrAfter = outer.end_line > inner.end_line ||
+        (outer.end_line === inner.end_line && outer.end_col >= inner.end_col);
+    if (!startsAtOrBefore || !endsAtOrAfter)
+        return false;
+    const strictlyLarger = outer.start_line < inner.start_line ||
+        outer.start_col < inner.start_col ||
+        outer.end_line > inner.end_line ||
+        outer.end_col > inner.end_col;
+    return strictlyLarger;
+}
+function setSubtype(d, subtype) {
+    return d.subtype === subtype ? d : { ...d, subtype };
+}
+async function extractDraftViaRuntime(providerId, input, grammarForLang) {
+    return extractWithQueries({
+        providerId,
+        lang: input.lang,
+        source: input.source,
+        sizeBytes: input.sizeBytes,
+        maxParseFileBytes: input.maxParseFileBytes,
+        maxQueryWaitMs: input.maxQueryWaitMs,
+        path: input.path,
+        grammarForLang,
+        tagsSource: TAGS,
+        tagsHash: TAGS_HASH,
+        importsSource: IMPORTS,
+        importsHash: IMPORTS_HASH,
+        enclosingStatementNodeTypes: queries.enclosingStatementNodeTypes,
+    });
+}
+/** Singleton instance for registry wiring. */
+export const pythonProvider = new PythonProvider();
+//# sourceMappingURL=index.js.map

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

@@ -0,0 +1,81 @@
+; Brainclaw Code Map — Python DEFINITIONS query (curated, vendored).
+; Grammar: tree-sitter-python (WASM vendored under dist/wasm/). See ./README.md for
+; the capture-name convention, the Python→vocabulary mapping, and provenance.
+;
+; The generic query-runtime (lang/query-runtime.ts) maps each match's captures:
+;   @definition.<subtype>.node     -> DefinitionDraft.span  (the LEGACY IDENTITY span)
+;   @definition.<subtype>.name     -> DefinitionDraft.name  (identifier text + ordinal)
+;   @definition.<subtype>.exported -> presence ⇒ exported=true  (UNUSED for Python:
+;                                     Python has no export statement, so this asset
+;                                     never emits it — every Python symbol is unexported)
+;
+; Structural subtypes emitted here: function | class | variable.
+;  - function_definition is captured UNIFORMLY as @definition.function (whether bare,
+;    decorated, top-level, nested, or sitting directly in a class body). The provider's
+;    refine() pass reclassifies:
+;      * a function_definition whose owner is a class body          -> method
+;        (@property -> property; @staticmethod/@classmethod -> method)
+;      * everything else (top-level + nested defs)                  -> stays function
+;    refine() decides method-vs-function and decorator-driven subtypes because the
+;    structural query cannot inspect the enclosing-scope chain or decorator semantics.
+;  - module-level assignment is captured as @definition.variable; refine() narrows an
+;    all-UPPER_CASE target to `constant`.
+;
+; IDENTITY SPAN: every definition pattern anchors @definition.*.node on the INNER
+; function_definition / class_definition node — NOT on any enclosing decorated_definition
+; wrapper. A decorated def's identity span therefore EXCLUDES its decorators (spec §5),
+; and the same single pattern matches the bare and the decorated forms (the inner node
+; is identical in both trees), so no separate decorated pattern is needed.
+
+; ---------------------------------------------------------------------------
+; function / async-function definitions  (def f(): ... / async def f(): ...)
+;
+; Matched at ANY depth (top-level, nested, class-body). `async def` is the same
+; function_definition node (the grammar marks async with an `async` keyword child,
+; not a distinct node type), so this one pattern covers sync + async; async-ness is
+; classification-only and is NOT persisted (no durable attribute field — spec §5).
+; refine() promotes class-body functions to `method`.
+; ---------------------------------------------------------------------------
+(function_definition
+  name: (identifier) @definition.function.name) @definition.function.node
+
+; ---------------------------------------------------------------------------
+; class definitions  (class C: ... / class C(Base): ...)
+; ---------------------------------------------------------------------------
+(class_definition
+  name: (identifier) @definition.class.name) @definition.class.node
+
+; ---------------------------------------------------------------------------
+; module-level variables / constants
+;
+; Anchored under `module` (the root) so ONLY top-level assignments are emitted —
+; class/instance attributes and locals are NOT symbols in P1b (spec §5). Covers both
+; a plain assignment (`X = 1`) and an annotated assignment (`X: int = 1`); both are a
+; single `assignment` node, the annotation living in its `type:` field. Only a simple
+; `identifier` target is captured (tuple/attribute/subscript targets are not symbols).
+; The @definition.variable.node identity span is the `assignment` node. refine()
+; narrows an all-UPPER_CASE name to `constant`; everything else stays `variable`.
+; ---------------------------------------------------------------------------
+(module
+  (expression_statement
+    (assignment
+      left: (identifier) @definition.variable.name) @definition.variable.node))
+
+; ---------------------------------------------------------------------------
+; ERROR-root recovery (parity with the TS asset).
+;
+; When tree-sitter cannot parse a file cleanly it may promote a subtree to an `ERROR`
+; node while still recovering well-formed declarations beneath it. Mirror the def/class
+; patterns under an `(ERROR ...)` ancestor so top-level symbols in an error-recovered
+; file are not silently dropped. (Functions/classes match at any depth above already,
+; but anchoring these explicitly keeps content parity for the ERROR-root shape and
+; documents the intent.) Module-level variables are intentionally NOT recovered under
+; ERROR — without the `module` anchor a bare identifier-assignment match is ambiguous.
+; ---------------------------------------------------------------------------
+(ERROR
+  (function_definition
+    name: (identifier) @definition.function.name) @definition.function.node)
+
+(ERROR
+  (class_definition
+    name: (identifier) @definition.class.name) @definition.class.node)