gitnexus 1.6.5-rc.8 → 1.6.5

package/dist/core/ingestion/languages/cpp/two-phase-lookup.js

@@ -0,0 +1,195 @@
+/**
+ * C++ two-phase template lookup support.
+ *
+ * Inside a class template body, names from a dependent base class are NOT
+ * found by ordinary unqualified lookup. The standard requires the
+ * `this->name` or `Base<T>::name` forms to make the lookup dependent.
+ * GitNexus's global free-call fallback otherwise binds such names to the
+ * dependent base's members, producing CALLS edges the compiler would
+ * reject.
+ *
+ * This module records — during `emitCppScopeCaptures` — which template
+ * class declarations have which dependent base class names (per file).
+ * `populateCppDependentBases` then resolves those names to class nodeIds
+ * using a workspace-wide registry, building the per-class set the
+ * `isCppDependentBaseMember` predicate consumes.
+ *
+ * Cross-file resolution: `Base<T>` may be declared in a different header
+ * than `Derived<T>`. `populateCppDependentBases` therefore runs as a
+ * workspace-wide pass (`populateWorkspaceOwners` hook) after every file
+ * has had `populateOwners` applied, so all class defs are reachable.
+ *
+ * Namespace disambiguation: when multiple classes share a simple name
+ * (e.g., `Box` in two namespaces), the resolver prefers the candidate
+ * whose qualified-name prefix (namespace path) matches the deriving
+ * class's prefix. If no namespace match is found, a unique simple-name
+ * match is accepted; ambiguous matches (multiple candidates, no
+ * namespace winner) are skipped conservatively.
+ *
+ * NOTE: module-level state, single-process-single-repo use only.
+ * `clearFileLocalNames()` clears this state alongside file-local linkage
+ * (see `file-local-linkage.ts`).
+ */
+import { findEnclosingClassDef } from '../../scope-resolution/scope/walkers.js';
+/**
+ * Capture-time record: for each template class declaration in a file,
+ * the simple names of its dependent base classes.
+ *
+ * Key: filePath
+ * Value: Map<className, Set<dependentBaseSimpleName>>
+ */
+const dependentBasesByFile = new Map();
+/**
+ * Post-`populateOwners` resolution: per-class-nodeId, the set of
+ * dependent-base-class nodeIds. Built by `populateCppDependentBases`
+ * from `dependentBasesByFile` + the workspace registry.
+ */
+const dependentBaseNodeIds = new Map();
+/**
+ * Record a dependent-base relationship discovered during scope-capture
+ * emission. `className` is the simple name of the template class;
+ * `baseName` is the simple name of the dependent base class.
+ *
+ * The capture-time recorder uses simple names because the registry
+ * resolution that maps names → nodeIds runs later (in
+ * `populateCppDependentBases`).
+ */
+export function markCppDependentBase(filePath, className, baseName) {
+    let perFile = dependentBasesByFile.get(filePath);
+    if (perFile === undefined) {
+        perFile = new Map();
+        dependentBasesByFile.set(filePath, perFile);
+    }
+    let bases = perFile.get(className);
+    if (bases === undefined) {
+        bases = new Set();
+        perFile.set(className, bases);
+    }
+    bases.add(baseName);
+}
+/** Clear two-phase-lookup state. Called from `clearFileLocalNames`. */
+export function clearCppDependentBases() {
+    dependentBasesByFile.clear();
+    dependentBaseNodeIds.clear();
+}
+/**
+ * Resolve recorded dependent-base simple names to class nodeIds using a
+ * workspace-wide index. Run as `populateWorkspaceOwners` after every
+ * file has had `populateOwners` applied, so class defs from ALL files
+ * are reachable.
+ *
+ * Disambiguation strategy (multiple classes sharing a simple name):
+ *  1. Prefer the candidate whose qualified-name namespace prefix matches
+ *     the deriving class's namespace prefix (same-namespace bias).
+ *  2. Fall back to accepting a unique simple-name match.
+ *  3. Skip when multiple candidates exist and no namespace match is
+ *     found (conservative: avoids false associations).
+ */
+export function populateCppDependentBases(parsedFiles) {
+    if (dependentBasesByFile.size === 0)
+        return;
+    // Build workspace-wide index: simpleName → {nodeId, nsPrefix}[]
+    // nsPrefix is the dot-joined namespace path (qualifiedName without the
+    // last segment). Classes at global scope have nsPrefix = ''.
+    const classesBySimpleName = new Map();
+    for (const parsed of parsedFiles) {
+        for (const def of parsed.localDefs) {
+            if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface')
+                continue;
+            const qn = def.qualifiedName ?? '';
+            const lastDot = qn.lastIndexOf('.');
+            const simple = lastDot >= 0 ? qn.slice(lastDot + 1) : qn;
+            if (simple === '')
+                continue;
+            const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
+            let entries = classesBySimpleName.get(simple);
+            if (entries === undefined) {
+                entries = [];
+                classesBySimpleName.set(simple, entries);
+            }
+            entries.push({ nodeId: def.nodeId, nsPrefix });
+        }
+    }
+    // Build a filePath → ParsedFile lookup for fast per-file access.
+    const parsedByFile = new Map();
+    for (const parsed of parsedFiles)
+        parsedByFile.set(parsed.filePath, parsed);
+    for (const [filePath, perFile] of dependentBasesByFile) {
+        const parsed = parsedByFile.get(filePath);
+        if (parsed === undefined)
+            continue;
+        // Build a simple-name → {nodeId, nsPrefix} map for THIS file's
+        // class-like defs so we can identify each template class precisely
+        // (avoids cross-file name collisions for the deriving class itself).
+        const localClassByName = new Map();
+        for (const def of parsed.localDefs) {
+            if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface')
+                continue;
+            const qn = def.qualifiedName ?? '';
+            const lastDot = qn.lastIndexOf('.');
+            const simple = lastDot >= 0 ? qn.slice(lastDot + 1) : qn;
+            if (simple === '')
+                continue;
+            const nsPrefix = lastDot >= 0 ? qn.slice(0, lastDot) : '';
+            localClassByName.set(simple, { nodeId: def.nodeId, nsPrefix });
+        }
+        for (const [className, baseNames] of perFile) {
+            const classEntry = localClassByName.get(className);
+            if (classEntry === undefined)
+                continue;
+            let bases = dependentBaseNodeIds.get(classEntry.nodeId);
+            if (bases === undefined) {
+                bases = new Set();
+                dependentBaseNodeIds.set(classEntry.nodeId, bases);
+            }
+            for (const baseName of baseNames) {
+                const candidates = classesBySimpleName.get(baseName);
+                if (candidates === undefined || candidates.length === 0)
+                    continue;
+                if (candidates.length === 1) {
+                    // Unique simple-name match — accept regardless of namespace.
+                    bases.add(candidates[0].nodeId);
+                    continue;
+                }
+                // Multiple classes share the same simple name — prefer the one
+                // whose namespace matches the deriving class's namespace.
+                // V1: exact dot-prefix match only. Cross-namespace inheritance
+                // (e.g., `ns::outer::Derived` extending bare `Inner` defined in
+                // `ns::outer::inner`) and inline-namespace cases are deferred to
+                // V2; the conservative skip-on-ambiguity below avoids false
+                // associations in those edge cases.
+                const nsMatch = candidates.find((c) => c.nsPrefix === classEntry.nsPrefix);
+                if (nsMatch !== undefined) {
+                    bases.add(nsMatch.nodeId);
+                }
+                // else: ambiguous (multiple candidates, no namespace match) → skip.
+            }
+        }
+    }
+}
+/**
+ * Two-phase lookup predicate: is the candidate def a member of a
+ * dependent base of the caller's enclosing template class?
+ *
+ * Used as an additional reject-filter in `pickUniqueGlobalCallable` and
+ * the receiver-bound member chain walk. ONLY apply for unqualified
+ * call forms — `this->name` and `Base<T>::name` are dependent lookup
+ * forms that the standard allows.
+ *
+ * Conservative bias: when the caller's enclosing class can't be
+ * identified, return `false` (let normal resolution proceed). Over-
+ * rejection is acceptable for the template case because the standard
+ * itself requires `this->` or qualified forms for dependent base
+ * access; missing edges here match the compiler's diagnostic shape.
+ */
+export function isCppDependentBaseMember(callerScopeId, candidateDef, scopes) {
+    if (candidateDef.ownerId === undefined)
+        return false;
+    const enclosing = findEnclosingClassDef(callerScopeId, scopes);
+    if (enclosing === undefined)
+        return false;
+    const bases = dependentBaseNodeIds.get(enclosing.nodeId);
+    if (bases === undefined)
+        return false;
+    return bases.has(candidateDef.ownerId);
+}

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;