arceus-s 1.6.4

package/dist/core/ingestion/languages/java/captures.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `emitScopeCaptures` for Java.
+ *
+ * Drives the Java scope query against tree-sitter-java and groups raw
+ * matches into `CaptureMatch[]` for the central extractor. Layers:
+ *
+ *   1. **Decomposed import declarations** — each `import_declaration`
+ *      is re-emitted with `@import.kind/source/name` markers.
+ *   2. **Receiver binding synthesis** — `this`/`super` type-bindings
+ *      on instance methods.
+ *   3. **Arity metadata** on method/constructor declarations.
+ *   4. **Reference arity** on call sites.
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitJavaScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];

package/dist/core/ingestion/languages/java/captures.js

@@ -0,0 +1,187 @@
+/**
+ * `emitScopeCaptures` for Java.
+ *
+ * Drives the Java scope query against tree-sitter-java and groups raw
+ * matches into `CaptureMatch[]` for the central extractor. Layers:
+ *
+ *   1. **Decomposed import declarations** — each `import_declaration`
+ *      is re-emitted with `@import.kind/source/name` markers.
+ *   2. **Receiver binding synthesis** — `this`/`super` type-bindings
+ *      on instance methods.
+ *   3. **Arity metadata** on method/constructor declarations.
+ *   4. **Reference arity** on call sites.
+ *
+ * Pure given the input source text. No I/O, no globals consulted.
+ */
+import { findNodeAtRange, nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+import { splitImportDeclaration } from './import-decomposer.js';
+import { computeJavaArityMetadata } from './arity-metadata.js';
+import { synthesizeJavaReceiverBinding } from './receiver-binding.js';
+import { getJavaParser, getJavaScopeQuery } from './query.js';
+import { recordCacheHit, recordCacheMiss } from './cache-stats.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+/** Declaration anchors that carry function-like arity metadata. */
+const FUNCTION_DECL_TAGS = ['@declaration.method', '@declaration.constructor'];
+/** tree-sitter-java node types that the method extractor accepts. */
+const FUNCTION_NODE_TYPES = ['method_declaration', 'constructor_declaration'];
+/** Suppress read.member emissions when the field_access is already
+ *  covered by a method_invocation (object of a call) or an
+ *  assignment_expression (write target). */
+function shouldEmitReadMember(memberNode) {
+    const parent = memberNode.parent;
+    if (parent === null)
+        return true;
+    switch (parent.type) {
+        case 'method_invocation':
+            // Don't emit read.member when the field_access is the object of a method_invocation
+            // (the method call already handles this relationship)
+            return parent.childForFieldName('object')?.id !== memberNode.id;
+        case 'assignment_expression':
+            return parent.childForFieldName('left')?.id !== memberNode.id;
+        default:
+            return true;
+    }
+}
+export function emitJavaScopeCaptures(sourceText, _filePath, cachedTree) {
+    let tree = cachedTree;
+    if (tree === undefined) {
+        tree = parseSourceSafe(getJavaParser(), sourceText, undefined, {
+            bufferSize: getTreeSitterBufferSize(sourceText),
+        });
+        recordCacheMiss();
+    }
+    else {
+        recordCacheHit();
+    }
+    const rawMatches = getJavaScopeQuery().matches(tree.rootNode);
+    const out = [];
+    for (const m of rawMatches) {
+        const grouped = {};
+        for (const c of m.captures) {
+            const tag = '@' + c.name;
+            grouped[tag] = nodeToCapture(tag, c.node);
+        }
+        if (Object.keys(grouped).length === 0)
+            continue;
+        // Decompose each `import_declaration`.
+        if (grouped['@import.statement'] !== undefined) {
+            const stmtCapture = grouped['@import.statement'];
+            const stmtNode = findNodeAtRange(tree.rootNode, stmtCapture.range, 'import_declaration');
+            if (stmtNode !== null) {
+                const decomposed = splitImportDeclaration(stmtNode);
+                if (decomposed !== null) {
+                    out.push(decomposed);
+                    continue;
+                }
+            }
+            out.push(grouped);
+            continue;
+        }
+        // Skip free-call matches that are actually member calls. The query
+        // matches ALL method_invocations as @reference.call.free (without
+        // negation) because tree-sitter-java's query engine drops !object
+        // patterns when a positive object: pattern exists for the same node
+        // type. Filter here: if the match has @reference.call.free but also
+        // has @reference.receiver, it's a member call — skip the free match
+        // (the separate @reference.call.member match covers it).
+        if (grouped['@reference.call.free'] !== undefined &&
+            grouped['@reference.receiver'] !== undefined) {
+            continue;
+        }
+        // Filter read.member when it's a child of method_invocation or assignment.
+        if (grouped['@reference.read.member'] !== undefined) {
+            const anchor = grouped['@reference.read.member'];
+            const memberNode = findNodeAtRange(tree.rootNode, anchor.range, 'field_access');
+            if (memberNode === null || !shouldEmitReadMember(memberNode)) {
+                continue;
+            }
+        }
+        // Synthesize `this` / `super` receiver type-bindings on every
+        // instance method-like.
+        if (grouped['@scope.function'] !== undefined) {
+            out.push(grouped);
+            const anchor = grouped['@scope.function'];
+            const fnNode = findFunctionNode(tree.rootNode, anchor.range);
+            if (fnNode !== null) {
+                for (const synth of synthesizeJavaReceiverBinding(fnNode)) {
+                    out.push(synth);
+                }
+            }
+            continue;
+        }
+        // Synthesize arity metadata on function-like declarations.
+        const declTag = FUNCTION_DECL_TAGS.find((t) => grouped[t] !== undefined);
+        if (declTag !== undefined) {
+            const anchor = grouped[declTag];
+            const fnNode = findFunctionNode(tree.rootNode, anchor.range);
+            if (fnNode !== null) {
+                const arity = computeJavaArityMetadata(fnNode);
+                if (arity.parameterCount !== undefined) {
+                    grouped['@declaration.parameter-count'] = syntheticCapture('@declaration.parameter-count', fnNode, String(arity.parameterCount));
+                }
+                if (arity.requiredParameterCount !== undefined) {
+                    grouped['@declaration.required-parameter-count'] = syntheticCapture('@declaration.required-parameter-count', fnNode, String(arity.requiredParameterCount));
+                }
+                if (arity.parameterTypes !== undefined) {
+                    grouped['@declaration.parameter-types'] = syntheticCapture('@declaration.parameter-types', fnNode, JSON.stringify(arity.parameterTypes));
+                }
+            }
+        }
+        // Synthesize `@reference.arity` on every callsite.
+        const callTag = ['@reference.call.free', '@reference.call.member', '@reference.call.constructor'].find((t) => grouped[t] !== undefined);
+        if (callTag !== undefined && grouped['@reference.arity'] === undefined) {
+            const anchor = grouped[callTag];
+            const callNode = findNodeAtRange(tree.rootNode, anchor.range, 'method_invocation') ??
+                findNodeAtRange(tree.rootNode, anchor.range, 'object_creation_expression');
+            if (callNode !== null) {
+                const argList = callNode.childForFieldName('arguments');
+                const args = argList === null
+                    ? []
+                    : argList.namedChildren.filter((c) => c !== null && c.type !== 'comment');
+                grouped['@reference.arity'] = syntheticCapture('@reference.arity', callNode, String(args.length));
+                const argTypes = args.map((arg) => inferArgType(arg));
+                grouped['@reference.parameter-types'] = syntheticCapture('@reference.parameter-types', callNode, JSON.stringify(argTypes));
+            }
+        }
+        out.push(grouped);
+    }
+    return out;
+}
+/** Infer a Java argument's static type from literal patterns. */
+function inferArgType(argNode) {
+    switch (argNode.type) {
+        case 'decimal_integer_literal':
+        case 'hex_integer_literal':
+        case 'octal_integer_literal':
+        case 'binary_integer_literal':
+            return 'int';
+        case 'decimal_floating_point_literal':
+        case 'hex_floating_point_literal':
+            return 'double';
+        case 'string_literal':
+            return 'String';
+        case 'character_literal':
+            return 'char';
+        case 'true':
+        case 'false':
+            return 'boolean';
+        case 'null_literal':
+            return 'null';
+        case 'object_creation_expression': {
+            const typeNode = argNode.childForFieldName('type');
+            return typeNode?.text ?? '';
+        }
+        default:
+            return '';
+    }
+}
+/** Find the first Java function-like node at the given range. */
+function findFunctionNode(rootNode, range) {
+    for (const nodeType of FUNCTION_NODE_TYPES) {
+        const n = findNodeAtRange(rootNode, range, nodeType);
+        if (n !== null)
+            return n;
+    }
+    return null;
+}

package/dist/core/ingestion/languages/java/import-decomposer.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Decompose a Java `import_declaration` into a `CaptureMatch` carrying
+ * the synthesized markers `@import.kind` / `@import.source` /
+ * `@import.name` that `interpretJavaImport` consumes.
+ *
+ * Unlike C#'s using-directive decomposer, Java has four import forms:
+ *
+ *   import com.example.User;                     → named
+ *   import com.example.*;                         → wildcard
+ *   import static com.example.Utils.format;       → static
+ *   import static com.example.Utils.*;             → static-wildcard
+ *
+ * Each produces exactly one import. The decomposer inspects the raw
+ * source text and tree-sitter children to determine the flavor.
+ */
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+export declare function splitImportDeclaration(stmtNode: SyntaxNode): CaptureMatch | null;

package/dist/core/ingestion/languages/java/import-decomposer.js

@@ -0,0 +1,85 @@
+/**
+ * Decompose a Java `import_declaration` into a `CaptureMatch` carrying
+ * the synthesized markers `@import.kind` / `@import.source` /
+ * `@import.name` that `interpretJavaImport` consumes.
+ *
+ * Unlike C#'s using-directive decomposer, Java has four import forms:
+ *
+ *   import com.example.User;                     → named
+ *   import com.example.*;                         → wildcard
+ *   import static com.example.Utils.format;       → static
+ *   import static com.example.Utils.*;             → static-wildcard
+ *
+ * Each produces exactly one import. The decomposer inspects the raw
+ * source text and tree-sitter children to determine the flavor.
+ */
+import { nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js';
+export function splitImportDeclaration(stmtNode) {
+    if (stmtNode.type !== 'import_declaration')
+        return null;
+    const spec = parseImportDeclaration(stmtNode);
+    if (spec === null)
+        return null;
+    return buildImportMatch(stmtNode, spec);
+}
+function parseImportDeclaration(node) {
+    // Detect `static` by checking for an anonymous `static` token child.
+    let isStatic = false;
+    for (let i = 0; i < node.childCount; i++) {
+        const child = node.child(i);
+        if (child !== null && child.type === 'static') {
+            isStatic = true;
+            break;
+        }
+    }
+    // Detect wildcard by checking for `asterisk` named child.
+    let isWildcard = false;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null && child.type === 'asterisk') {
+            isWildcard = true;
+            break;
+        }
+    }
+    // Find the scoped_identifier (or identifier for single-segment imports).
+    let pathNode = null;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child !== null && (child.type === 'scoped_identifier' || child.type === 'identifier')) {
+            pathNode = child;
+            break;
+        }
+    }
+    if (pathNode === null)
+        return null;
+    const fullPath = pathNode.text;
+    if (fullPath === '')
+        return null;
+    if (isStatic && isWildcard) {
+        // `import static com.example.Utils.*;`
+        return { kind: 'static-wildcard', source: fullPath, name: '*', atNode: node };
+    }
+    if (isStatic) {
+        // `import static com.example.Utils.format;`
+        const lastDot = fullPath.lastIndexOf('.');
+        const name = lastDot >= 0 ? fullPath.slice(lastDot + 1) : fullPath;
+        return { kind: 'static', source: fullPath, name, atNode: node };
+    }
+    if (isWildcard) {
+        // `import com.example.*;`
+        return { kind: 'wildcard', source: fullPath, name: '*', atNode: node };
+    }
+    // `import com.example.User;`
+    const lastDot = fullPath.lastIndexOf('.');
+    const name = lastDot >= 0 ? fullPath.slice(lastDot + 1) : fullPath;
+    return { kind: 'named', source: fullPath, name, atNode: node };
+}
+function buildImportMatch(stmtNode, spec) {
+    const m = {
+        '@import.statement': nodeToCapture('@import.statement', stmtNode),
+        '@import.kind': syntheticCapture('@import.kind', spec.atNode, spec.kind),
+        '@import.source': syntheticCapture('@import.source', spec.atNode, spec.source),
+        '@import.name': syntheticCapture('@import.name', spec.atNode, spec.name),
+    };
+    return m;
+}

package/dist/core/ingestion/languages/java/import-target.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Converts Java package paths (dots → slashes) and tries:
+ *   1. Exact file match: `com/example/User.java`
+ *   2. Suffix match for nested layouts
+ *   3. Directory match (wildcard imports)
+ *   4. Progressive prefix stripping for non-standard layouts
+ *
+ * Returns `null` for unresolvable / JDK imports.
+ */
+import type { ParsedImport, WorkspaceIndex } from '../../../../_shared/index.js';
+export interface JavaResolveContext {
+    readonly fromFile: string;
+    readonly allFilePaths: ReadonlySet<string>;
+}
+export declare function resolveJavaImportTarget(parsedImport: ParsedImport, workspaceIndex: WorkspaceIndex): string | null;

package/dist/core/ingestion/languages/java/import-target.js

@@ -0,0 +1,100 @@
+/**
+ * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path.
+ *
+ * Converts Java package paths (dots → slashes) and tries:
+ *   1. Exact file match: `com/example/User.java`
+ *   2. Suffix match for nested layouts
+ *   3. Directory match (wildcard imports)
+ *   4. Progressive prefix stripping for non-standard layouts
+ *
+ * Returns `null` for unresolvable / JDK imports.
+ */
+export function resolveJavaImportTarget(parsedImport, workspaceIndex) {
+    const ctx = workspaceIndex;
+    if (ctx === undefined ||
+        typeof ctx.fromFile !== 'string' ||
+        !(ctx.allFilePaths instanceof Set)) {
+        return null;
+    }
+    if (parsedImport.kind === 'dynamic-unresolved')
+        return null;
+    if (parsedImport.targetRaw === null || parsedImport.targetRaw === '')
+        return null;
+    // Strip trailing `.*` for wildcard imports: `com.example.*` → `com.example`
+    let target = parsedImport.targetRaw;
+    if (target.endsWith('.*')) {
+        target = target.slice(0, -2);
+    }
+    // Package path: `com.example.User` → `com/example/User`
+    const pathLike = target.replace(/\./g, '/');
+    const suffix = `/${pathLike}`;
+    let exactFile = null;
+    let suffixFile = null;
+    let directoryChild = null;
+    const dirPrefix = `${pathLike}/`;
+    const suffixDirPrefix = `/${dirPrefix}`;
+    for (const raw of ctx.allFilePaths) {
+        const f = raw.replace(/\\/g, '/');
+        if (!f.endsWith('.java'))
+            continue;
+        if (f === `${pathLike}.java`) {
+            exactFile = raw;
+            break;
+        }
+        if (suffixFile === null && f.endsWith(`${suffix}.java`)) {
+            suffixFile = raw;
+        }
+        if (directoryChild === null) {
+            const atRoot = f.startsWith(dirPrefix);
+            const atNested = f.includes(suffixDirPrefix);
+            if (atRoot || atNested) {
+                const idx = atRoot ? 0 : f.indexOf(suffixDirPrefix) + 1;
+                const after = f.slice(idx + dirPrefix.length);
+                if (after.length > 0 && !after.includes('/')) {
+                    directoryChild = raw;
+                }
+            }
+        }
+    }
+    if (exactFile !== null)
+        return exactFile;
+    if (suffixFile !== null)
+        return suffixFile;
+    if (directoryChild !== null)
+        return directoryChild;
+    // Progressive prefix stripping — handles `import com.example.User;`
+    // in a repo laid out `User.java` (no `com/example/` prefix).
+    const segments = pathLike.split('/').filter(Boolean);
+    for (let skip = 1; skip < segments.length; skip++) {
+        const tail = segments.slice(skip).join('/');
+        if (tail === '')
+            continue;
+        const tailFile = `${tail}.java`;
+        const tailSuffix = `/${tailFile}`;
+        const tailDir = `${tail}/`;
+        const tailSuffixDir = `/${tailDir}`;
+        let tailDirectChild = null;
+        for (const raw of ctx.allFilePaths) {
+            const f = raw.replace(/\\/g, '/');
+            if (!f.endsWith('.java'))
+                continue;
+            if (f === tailFile)
+                return raw;
+            if (f.endsWith(tailSuffix))
+                return raw;
+            if (tailDirectChild === null) {
+                const atRoot = f.startsWith(tailDir);
+                const atNested = f.includes(tailSuffixDir);
+                if (atRoot || atNested) {
+                    const idx = atRoot ? 0 : f.indexOf(tailSuffixDir) + 1;
+                    const after = f.slice(idx + tailDir.length);
+                    if (after.length > 0 && !after.includes('/'))
+                        tailDirectChild = raw;
+                }
+            }
+        }
+        if (tailDirectChild !== null)
+            return tailDirectChild;
+    }
+    return null;
+}

package/dist/core/ingestion/languages/java/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Java scope-resolution hooks (RFC #909 Ring 3).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules.
+ *
+ * Module layout:
+ *
+ *   - `query.ts`               — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`            — `emitJavaScopeCaptures` orchestrator
+ *   - `import-decomposer.ts`   — each `import` → ParsedImport-shaped captures
+ *   - `interpret.ts`           — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `simple-hooks.ts`        — small hooks made explicit
+ *   - `receiver-binding.ts`    — synthesize `this`/`super` type-bindings on
+ *                                instance-method entry
+ *   - `merge-bindings.ts`      — Java import precedence
+ *   - `arity.ts`               — Java arity compatibility (varargs)
+ *   - `arity-metadata.ts`      — synthesize arity metadata from declarations
+ *   - `import-target.ts`       — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *   - `scope-resolver.ts`      — `ScopeResolver` registered in `SCOPE_RESOLVERS`
+ *   - `cache-stats.ts`         — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ */
+export { emitJavaScopeCaptures } from './captures.js';
+export { getJavaCaptureCacheStats, resetJavaCaptureCacheStats } from './cache-stats.js';
+export { interpretJavaImport, interpretJavaTypeBinding } from './interpret.js';
+export { javaMergeBindings } from './merge-bindings.js';
+export { javaArityCompatibility } from './arity.js';
+export { resolveJavaImportTarget, type JavaResolveContext } from './import-target.js';
+export { javaBindingScopeFor, javaImportOwningScope, javaReceiverBinding } from './simple-hooks.js';

package/dist/core/ingestion/languages/java/index.js

@@ -0,0 +1,29 @@
+/**
+ * Java scope-resolution hooks (RFC #909 Ring 3).
+ *
+ * Public API barrel. Consumers should import from this file rather than
+ * the individual modules.
+ *
+ * Module layout:
+ *
+ *   - `query.ts`               — tree-sitter query + lazy parser/query singletons
+ *   - `captures.ts`            — `emitJavaScopeCaptures` orchestrator
+ *   - `import-decomposer.ts`   — each `import` → ParsedImport-shaped captures
+ *   - `interpret.ts`           — capture-match → `ParsedImport` / `ParsedTypeBinding`
+ *   - `simple-hooks.ts`        — small hooks made explicit
+ *   - `receiver-binding.ts`    — synthesize `this`/`super` type-bindings on
+ *                                instance-method entry
+ *   - `merge-bindings.ts`      — Java import precedence
+ *   - `arity.ts`               — Java arity compatibility (varargs)
+ *   - `arity-metadata.ts`      — synthesize arity metadata from declarations
+ *   - `import-target.ts`       — `(ParsedImport, WorkspaceIndex) → file path` adapter
+ *   - `scope-resolver.ts`      — `ScopeResolver` registered in `SCOPE_RESOLVERS`
+ *   - `cache-stats.ts`         — PROF_SCOPE_RESOLUTION cache hit/miss counters
+ */
+export { emitJavaScopeCaptures } from './captures.js';
+export { getJavaCaptureCacheStats, resetJavaCaptureCacheStats } from './cache-stats.js';
+export { interpretJavaImport, interpretJavaTypeBinding } from './interpret.js';
+export { javaMergeBindings } from './merge-bindings.js';
+export { javaArityCompatibility } from './arity.js';
+export { resolveJavaImportTarget } from './import-target.js';
+export { javaBindingScopeFor, javaImportOwningScope, javaReceiverBinding } from './simple-hooks.js';

package/dist/core/ingestion/languages/java/interpret.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Capture-match → semantic-shape interpreters for Java.
+ *
+ *   - `interpretJavaImport`       → `ParsedImport`
+ *   - `interpretJavaTypeBinding`  → `ParsedTypeBinding`
+ *
+ * Import matches arrive pre-decomposed by `emitJavaScopeCaptures`
+ * (one import per match, with synthesized `@import.kind/source/name`
+ * markers). Type-binding matches arrive from the raw query captures.
+ */
+import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from '../../../../_shared/index.js';
+export declare function interpretJavaImport(captures: CaptureMatch): ParsedImport | null;
+export declare function interpretJavaTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null;

package/dist/core/ingestion/languages/java/interpret.js

@@ -0,0 +1,131 @@
+/**
+ * Capture-match → semantic-shape interpreters for Java.
+ *
+ *   - `interpretJavaImport`       → `ParsedImport`
+ *   - `interpretJavaTypeBinding`  → `ParsedTypeBinding`
+ *
+ * Import matches arrive pre-decomposed by `emitJavaScopeCaptures`
+ * (one import per match, with synthesized `@import.kind/source/name`
+ * markers). Type-binding matches arrive from the raw query captures.
+ */
+// ─── interpretImport ──────────────────────────────────────────────────────
+export function interpretJavaImport(captures) {
+    const kindCap = captures['@import.kind'];
+    const sourceCap = captures['@import.source'];
+    const nameCap = captures['@import.name'];
+    const kind = kindCap?.text;
+    if (kind === undefined || sourceCap === undefined)
+        return null;
+    switch (kind) {
+        case 'named': {
+            // `import com.example.User;`
+            return {
+                kind: 'named',
+                localName: nameCap?.text ?? sourceCap.text.split('.').pop() ?? sourceCap.text,
+                importedName: sourceCap.text,
+                targetRaw: sourceCap.text,
+            };
+        }
+        case 'wildcard': {
+            // `import com.example.*;`
+            return {
+                kind: 'wildcard',
+                targetRaw: sourceCap.text + '.*',
+            };
+        }
+        case 'static': {
+            // `import static com.example.Utils.format;`
+            // The source contains the full path including the member name
+            // (e.g. `com.example.Utils.format`).  For file resolution we need
+            // the class path (`com.example.Utils`), so strip the final member
+            // segment.  The local binding name is the member itself.
+            const fullSource = sourceCap.text;
+            const lastDot = fullSource.lastIndexOf('.');
+            const classPath = lastDot >= 0 ? fullSource.slice(0, lastDot) : fullSource;
+            return {
+                kind: 'named',
+                localName: nameCap?.text ?? (lastDot >= 0 ? fullSource.slice(lastDot + 1) : fullSource),
+                importedName: fullSource,
+                targetRaw: classPath,
+            };
+        }
+        case 'static-wildcard': {
+            // `import static com.example.Utils.*;`
+            // The source is the class path (e.g. `com.example.Utils`).
+            // Resolution should target the class file, not a wildcard directory
+            // scan — `Utils.java` is the file that contains the static members.
+            return {
+                kind: 'wildcard',
+                targetRaw: sourceCap.text + '.*',
+            };
+        }
+        default:
+            return null;
+    }
+}
+// ─── interpretTypeBinding ─────────────────────────────────────────────────
+export function interpretJavaTypeBinding(captures) {
+    const nameCap = captures['@type-binding.name'];
+    const typeCap = captures['@type-binding.type'];
+    if (nameCap === undefined || typeCap === undefined)
+        return null;
+    // Strip qualifier first so that `com.example.BaseModel<T>` becomes
+    // `BaseModel<T>` before stripGeneric — the JVM-erasure fallback pattern
+    // requires an unqualified identifier at the start of the string.
+    const rawType = stripGeneric(stripQualifier(typeCap.text.trim()));
+    // Skip `var` — tree-sitter-java parses `var` as type_identifier with
+    // text "var". When used without a constructor initializer, there's no
+    // concrete type to bind.
+    if (rawType === 'var')
+        return null;
+    let source = 'parameter-annotation';
+    if (captures['@type-binding.self'] !== undefined)
+        source = 'self';
+    else if (captures['@type-binding.constructor'] !== undefined)
+        source = 'constructor-inferred';
+    else if (captures['@type-binding.annotation'] !== undefined)
+        source = 'annotation';
+    else if (captures['@type-binding.return'] !== undefined)
+        source = 'return-annotation';
+    return { boundName: nameCap.text, rawTypeName: rawType, source };
+}
+/**
+ * Unwrap generic type parameters from Java types.
+ *
+ * Three tiers, checked in order:
+ *   1. Known single-arg collection wrappers → extract the element type
+ *      (`List<User>` → `User`, `Optional<User>` → `User`).
+ *   2. Known two-arg map/container types → extract the value type
+ *      (`Map<String, User>` → `User`).
+ *   3. **Fallback (JVM type erasure):** any other generic type →
+ *      strip the generic parameters and keep the raw class name
+ *      (`BaseModel<T>` → `BaseModel`, `CustomList<Foo>` → `CustomList`).
+ *      This ensures receiver bindings (`this`/`super`) on classes with
+ *      generic superclasses resolve to the correct class file.
+ */
+function stripGeneric(text) {
+    // Single-type-argument containers — extract the element type.
+    const single = text.match(/^(?:[A-Za-z_][A-Za-z0-9_.]*\.)?(?:List|ArrayList|LinkedList|Set|HashSet|TreeSet|SortedSet|LinkedHashSet|Collection|Iterable|Iterator|Optional|Stream|CompletableFuture|Future|Queue|Deque|ArrayDeque|PriorityQueue|Vector|Stack|Supplier|Consumer|Predicate|Function)<([^,<>]+)>$/);
+    if (single !== null)
+        return single[1].trim();
+    // Two-type-argument map/container types — extract the value type (second arg).
+    const twoArg = text.match(/^(?:[A-Za-z_][A-Za-z0-9_.]*\.)?(?:Map|HashMap|TreeMap|LinkedHashMap|ConcurrentHashMap|ConcurrentMap|SortedMap|NavigableMap|Hashtable|EnumMap|WeakHashMap|IdentityHashMap|BiFunction|BiConsumer|BiPredicate|Pair|Entry)<[^,<>]+,\s*([^,<>]+)>$/);
+    if (twoArg !== null)
+        return twoArg[1].trim();
+    // Fallback: strip generic parameters from any unrecognized generic type.
+    // `BaseModel<T>` → `BaseModel`, `Builder<Self>` → `Builder`.
+    // This mirrors JVM type erasure — the raw class name is the resolvable symbol.
+    // The pattern matches up to the first `<` to handle nested generics safely
+    // (e.g. `BaseModel<List<String>>` → `BaseModel`).
+    const fallback = text.match(/^([A-Za-z_$][A-Za-z0-9_$]*)<.+>$/s);
+    if (fallback !== null)
+        return fallback[1].trim();
+    return text;
+}
+/** `com.example.User` → `User`. */
+function stripQualifier(text) {
+    const lastDot = text.lastIndexOf('.');
+    if (lastDot === -1)
+        return text;
+    return text.slice(lastDot + 1);
+}

package/dist/core/ingestion/languages/java/merge-bindings.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Java shadowing precedence for the `mergeBindings` hook.
+ *
+ * Tier ranking (lower wins):
+ *   - 0: `local` — class member, method, local variable, parameter
+ *   - 1: `import` / `namespace` / `reexport` — explicit imports
+ *   - 2: `wildcard` — wildcard imports (`import x.y.*`)
+ *
+ * Within a surviving tier: de-dup by DefId, last-write-wins.
+ */
+import type { BindingRef } from '../../../../_shared/index.js';
+export declare function javaMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[];