gitnexus 1.6.5-rc.2 → 1.6.5-rc.21

package/dist/core/ingestion/languages/c-cpp.js

@@ -37,6 +37,7 @@ import { createCallExtractor } from '../call-extractors/generic.js';
 import { cCallConfig, cppCallConfig } from '../call-extractors/configs/c-cpp.js';
 import { createHeritageExtractor } from '../heritage-extractors/generic.js';
 import { stripUeMacros } from '../cpp-ue-preprocessor.js';
+import { emitCScopeCaptures, interpretCImport, interpretCTypeBinding, cArityCompatibility, cBindingScopeFor, cImportOwningScope, cReceiverBinding, } from './c/index.js';
 const C_BUILT_INS = new Set([
     'printf',
     'fprintf',
@@ -338,6 +339,15 @@ export const cProvider = defineLanguage({
     heritageExtractor: createHeritageExtractor(SupportedLanguages.C),
     labelOverride: cppLabelOverride,
     builtInNames: C_BUILT_INS,
+    // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ──────────
+    emitScopeCaptures: emitCScopeCaptures,
+    interpretImport: interpretCImport,
+    interpretTypeBinding: interpretCTypeBinding,
+    bindingScopeFor: cBindingScopeFor,
+    importOwningScope: cImportOwningScope,
+    receiverBinding: cReceiverBinding,
+    arityCompatibility: cArityCompatibility,
+    // mergeBindings + resolveImportTarget live on ScopeResolver (see c/scope-resolver.ts).
 });
 export const cppProvider = defineLanguage({
     id: SupportedLanguages.CPlusPlus,

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

@@ -22,6 +22,7 @@ import { synthesizeCsharpReceiverBinding } from './receiver-binding.js';
 import { getCsharpParser, getCsharpScopeQuery } 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',
@@ -75,7 +76,7 @@ export function emitCsharpScopeCaptures(sourceText, _filePath, cachedTree) {
     // the LanguageProvider contract layer; cast here at the use site.
     let tree = cachedTree;
     if (tree === undefined) {
-        tree = getCsharpParser().parse(sourceText, undefined, {
+        tree = parseSourceSafe(getCsharpParser(), sourceText, undefined, {
             bufferSize: getTreeSitterBufferSize(sourceText),
         });
         recordCacheMiss();

package/dist/core/ingestion/languages/csharp/namespace-siblings.js

@@ -32,6 +32,7 @@
  */
 import { getCsharpParser } from './query.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 /** Build a structural view of a C# file by walking the tree-sitter
  *  AST. Prefers `cachedTree` (handed in via `treeCache`) so we don't
  *  re-parse files the orchestrator already parsed for `extractParsedFile`;
@@ -39,7 +40,7 @@ import { getTreeSitterBufferSize } from '../../constants.js';
  *  shared across calls. */
 function extractFileStructure(content, cachedTree) {
     const tree = cachedTree ??
-        getCsharpParser().parse(content, undefined, {
+        parseSourceSafe(getCsharpParser(), content, undefined, {
             bufferSize: getTreeSitterBufferSize(content),
         });
     const namespaces = [];
@@ -332,7 +333,7 @@ export function populateCsharpNamespaceSiblings(parsedFiles, indexes, inputs) {
             const key = q.includes('.') ? q.slice(q.lastIndexOf('.') + 1) : q;
             if (key === '')
                 continue;
-            const arr = defsByName.get(key) ?? [];
+            const arr = [...(defsByName.get(key) ?? [])];
             arr.push(def);
             defsByName.set(key, arr);
         }

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

@@ -6,10 +6,11 @@ import { splitGoImportStatement } from './import-decomposer.js';
 import { synthesizeGoReceiverBinding } from './receiver-binding.js';
 import { synthesizeGoTypeBindings } from './type-binding.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 export function emitGoScopeCaptures(sourceText, _filePath, cachedTree) {
     let tree = cachedTree;
     if (tree === undefined) {
-        tree = getGoParser().parse(sourceText, undefined, {
+        tree = parseSourceSafe(getGoParser(), sourceText, undefined, {
             bufferSize: getTreeSitterBufferSize(sourceText),
         });
         recordGoCacheMiss();

package/dist/core/ingestion/languages/go/range-binding.js

@@ -1,5 +1,6 @@
 import { getGoParser } from './query.js';
 import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
 export function populateGoRangeBindings(parsedFiles, _indexes, ctx) {
     const parser = getGoParser();
     for (const parsed of parsedFiles) {
@@ -8,7 +9,7 @@ export function populateGoRangeBindings(parsedFiles, _indexes, ctx) {
             continue;
         const cachedTree = ctx.treeCache?.get(parsed.filePath);
         const tree = cachedTree ??
-            parser.parse(sourceText, undefined, {
+            parseSourceSafe(parser, sourceText, undefined, {
                 bufferSize: getTreeSitterBufferSize(sourceText),
             });
         const moduleScope = parsed.scopes.find((s) => s.kind === 'Module');

package/dist/core/ingestion/languages/java/arity-metadata.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Extract Java arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `constructor_declaration`.
+ *
+ * Reuses `javaMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - varargs (`...`) collapses `parameterCount` to `undefined`
+ *   - `parameterTypes` collects declared type names; a literal
+ *     `'varargs'` marker is appended for variadic methods so
+ *     `javaArityCompatibility` can detect them.
+ */
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+export interface JavaArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computeJavaArityMetadata(fnNode: SyntaxNode): JavaArityMetadata;

package/dist/core/ingestion/languages/java/arity-metadata.js

@@ -0,0 +1,40 @@
+/**
+ * Extract Java arity metadata from a method-like tree-sitter node —
+ * `method_declaration` or `constructor_declaration`.
+ *
+ * Reuses `javaMethodConfig.extractParameters` so scope-extracted defs
+ * carry the same arity semantics as the legacy parse-worker path:
+ *   - varargs (`...`) collapses `parameterCount` to `undefined`
+ *   - `parameterTypes` collects declared type names; a literal
+ *     `'varargs'` marker is appended for variadic methods so
+ *     `javaArityCompatibility` can detect them.
+ */
+import { javaMethodConfig } from '../../method-extractors/configs/jvm.js';
+export function computeJavaArityMetadata(fnNode) {
+    const params = javaMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVariadic = false;
+    const types = [];
+    for (const p of params) {
+        if (p.isVariadic)
+            hasVariadic = true;
+        if (p.type !== null)
+            types.push(p.type);
+    }
+    if (hasVariadic)
+        types.push('varargs');
+    const total = params.length;
+    // For varargs methods, `parameterCount` (max) is unknown — any number of
+    // trailing arguments is valid.  But the fixed-prefix parameters (everything
+    // before the variadic `...` param) are still required, so we preserve that
+    // count in `requiredParameterCount` so `javaArityCompatibility` can reject
+    // calls that undersupply the fixed prefix (e.g. `f(int x, String... args)`
+    // called with 0 args).
+    const fixedCount = params.filter((p) => !p.isVariadic).length;
+    const parameterCount = hasVariadic ? undefined : total;
+    const requiredParameterCount = hasVariadic ? fixedCount : total;
+    return {
+        parameterCount,
+        requiredParameterCount,
+        parameterTypes: types.length > 0 ? types : undefined,
+    };
+}

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

@@ -0,0 +1,10 @@
+/**
+ * Java arity check, accommodating varargs (`...`).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — argCount matches parameterCount, OR varargs present.
+ *   - `'incompatible'` — argCount mismatches with no varargs.
+ *   - `'unknown'`      — metadata absent / incomplete.
+ */
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function javaArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,24 @@
+/**
+ * Java arity check, accommodating varargs (`...`).
+ *
+ * Verdicts:
+ *   - `'compatible'`   — argCount matches parameterCount, OR varargs present.
+ *   - `'incompatible'` — argCount mismatches with no varargs.
+ *   - `'unknown'`      — metadata absent / incomplete.
+ */
+export function javaArityCompatibility(def, callsite) {
+    const max = def.parameterCount;
+    const min = def.requiredParameterCount;
+    if (max === undefined && min === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    const hasVarArgs = def.parameterTypes !== undefined &&
+        def.parameterTypes.some((t) => t === 'varargs' || t.includes('...'));
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVarArgs)
+        return 'incompatible';
+    return 'compatible';
+}

package/dist/core/ingestion/languages/java/cache-stats.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (Java mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+export declare function recordCacheHit(): void;
+export declare function recordCacheMiss(): void;
+export declare function getJavaCaptureCacheStats(): {
+    hits: number;
+    misses: number;
+};
+export declare function resetJavaCaptureCacheStats(): void;

package/dist/core/ingestion/languages/java/cache-stats.js

@@ -0,0 +1,26 @@
+/**
+ * Dev-mode counters for the cross-phase scope-captures parse cache
+ * (Java mirror of `languages/csharp/cache-stats.ts`).
+ *
+ * Gated by `PROF_SCOPE_RESOLUTION=1`. Production builds fold every
+ * increment into dead code via the module-level `PROF` constant, so
+ * the hot path in `captures.ts` stays branch-free.
+ */
+const PROF = process.env.PROF_SCOPE_RESOLUTION === '1';
+let CACHE_HITS = 0;
+let CACHE_MISSES = 0;
+export function recordCacheHit() {
+    if (PROF)
+        CACHE_HITS++;
+}
+export function recordCacheMiss() {
+    if (PROF)
+        CACHE_MISSES++;
+}
+export function getJavaCaptureCacheStats() {
+    return { hits: CACHE_HITS, misses: CACHE_MISSES };
+}
+export function resetJavaCaptureCacheStats() {
+    CACHE_HITS = 0;
+    CACHE_MISSES = 0;
+}

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;