gitnexus 1.6.6-rc.26 → 1.6.6-rc.28

package/README.md

@@ -359,6 +359,16 @@ npx gitnexus analyze
 
 For repositories with very large source files, `GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES` controls the worker job byte budget. The default is **8388608 bytes (8 MB)**.
 
+### Worker pool resilience tuning
+
+Three env vars expose the pool's resilience layers (respawn budget, cumulative-timeout cap, circuit breaker). Defaults are tuned for typical repos; bump them when an analyze legitimately needs more retries, or lower them to fail-fast on a known-bad shape.
+
+| Variable                                          | Default                   | Effect                                                                                                                            |
+| ------------------------------------------------- | ------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| `GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT`            | `3`                       | Max replacement spawns per slot before the slot is dropped from the active rotation.                                              |
+| `GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS`        | `5 × subBatchTimeoutMs`   | Total retry wall-time budget per job before quarantining. Bounds exponentially-growing retry waits.                              |
+| `GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD`    | `max(3, poolSize)`        | Per-slot consecutive deaths before the pool's circuit breaker trips. After tripping, dispatches require a fresh pool.            |
+
 ## Privacy
 
 - All processing happens locally on your machine

package/dist/cli/analyze.d.ts

@@ -69,6 +69,8 @@ export interface AnalyzeOptions {
     maxFileSize?: string;
     /** Override worker sub-batch idle timeout in seconds. */
     workerTimeout?: string;
+    /** Parse worker pool size; 0 disables workers (sequential fallback). */
+    workers?: string;
     embeddingThreads?: string;
     embeddingBatchSize?: string;
     embeddingSubBatchSize?: string;

package/dist/cli/analyze.js

@@ -133,10 +133,46 @@ function ensureHeap() {
                 `    (Windows: set NODE_OPTIONS=--max-old-space-size=24576 && gitnexus analyze [your-args])\n` +
                 `  If this persists, it may be a native crash unrelated to heap size.\n`, { recoveryHint: 'heap-oom-respawn' });
         }
-        process.exitCode = e.status ?? 1;
+        const status = typeof e === 'object' && e !== null && 'status' in e && typeof e.status === 'number'
+            ? e.status
+            : 1;
+        process.exitCode = status;
     }
     return true;
 }
+/**
+ * GITNEXUS_* env vars that `analyzeCommand` writes for backward-compatible
+ * downstream consumption. Snapshotted at function entry and restored in the
+ * finally block so that programmatic callers (tests, long-running hosts)
+ * don't see leaked state across invocations. `GITNEXUS_WORKER_POOL_SIZE` is
+ * NOT in this list: that knob is threaded through `runFullAnalysis` options
+ * (see `workerPoolSize` plumbing) so the CLI never has to mutate `process.env`
+ * for it in the first place.
+ */
+const ANALYZE_CLI_ENV_KEYS = [
+    'GITNEXUS_VERBOSE',
+    'GITNEXUS_MAX_FILE_SIZE',
+    'GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS',
+    'GITNEXUS_EMBEDDING_THREADS',
+    'GITNEXUS_EMBEDDING_BATCH_SIZE',
+    'GITNEXUS_EMBEDDING_SUB_BATCH_SIZE',
+    'GITNEXUS_EMBEDDING_DEVICE',
+];
+const snapshotAnalyzeEnv = () => {
+    const snap = {};
+    for (const k of ANALYZE_CLI_ENV_KEYS)
+        snap[k] = process.env[k];
+    return snap;
+};
+const restoreAnalyzeEnv = (snap) => {
+    for (const k of ANALYZE_CLI_ENV_KEYS) {
+        const v = snap[k];
+        if (v === undefined)
+            delete process.env[k];
+        else
+            process.env[k] = v;
+    }
+};
 /**
  * Whether the post-index skill step should run.
  *
@@ -159,6 +195,22 @@ export const analyzeCommand = async (inputPath, options) => {
     // async error that escapes the try/catch below (#1169) surfaces with
     // a stack trace and a non-zero exit code instead of a silent exit 0.
     installFatalHandlers();
+    // Snapshot the GITNEXUS_* env vars that the impl writes for downstream
+    // consumption, so they don't leak across `analyzeCommand` invocations in
+    // programmatic callers (tests, long-running hosts). `process.exit(0)` on
+    // the success path bypasses `finally` — intentional: when the process is
+    // exiting, restoration is moot. For early-return paths (validation
+    // errors) and the alreadyUpToDate fast path the finally restores the
+    // pre-call values.
+    const envSnap = snapshotAnalyzeEnv();
+    try {
+        await analyzeCommandImpl(inputPath, options);
+    }
+    finally {
+        restoreAnalyzeEnv(envSnap);
+    }
+};
+const analyzeCommandImpl = async (inputPath, options) => {
     if (options?.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';
     }
@@ -174,6 +226,23 @@ export const analyzeCommand = async (inputPath, options) => {
         }
         process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(Math.round(workerTimeoutSeconds * 1000));
     }
+    // `--workers` is threaded through `runFullAnalysis` options → PipelineOptions
+    // → createWorkerPool, intentionally bypassing the GITNEXUS_WORKER_POOL_SIZE
+    // env channel so this CLI surface never mutates `process.env` for pool size.
+    // Tests can therefore re-invoke analyzeCommand with different --workers
+    // values back-to-back and observe the value they passed, not whatever the
+    // previous call leaked.
+    let workerPoolSize;
+    if (options?.workers !== undefined) {
+        const parsedWorkers = Number(options.workers);
+        if (!Number.isInteger(parsedWorkers) || parsedWorkers < 0) {
+            cliError('  --workers must be a non-negative integer. ' +
+                'Pass 0 to disable the worker pool (sequential fallback).\n');
+            process.exitCode = 1;
+            return;
+        }
+        workerPoolSize = parsedWorkers;
+    }
     // Parse `--embeddings [limit]`: `true` → default cap, string → numeric cap
     // (0 disables the cap entirely). Validated up here so failures match the
     // sibling-validation pattern (exit before bar.start() — otherwise
@@ -394,6 +463,10 @@ export const analyzeCommand = async (inputPath, options) => {
             // be able to accept the duplicate name without also paying the
             // cost of a full pipeline re-index. See #829 review round 2.
             allowDuplicateName: options?.allowDuplicateName,
+            // Worker pool size threaded from --workers, replacing the previous
+            // GITNEXUS_WORKER_POOL_SIZE env mutation. `undefined` defers to the
+            // env / auto-formula fallback inside the pipeline.
+            workerPoolSize,
         }, {
             onProgress: (_phase, percent, message) => {
                 updateBar(percent, message);
@@ -515,7 +588,7 @@ export const analyzeCommand = async (inputPath, options) => {
         // eslint-disable-next-line no-console -- restoring after intentional progress-bar routing
         console.error = origError;
         bar.stop();
-        const msg = err.message || String(err);
+        const msg = err instanceof Error ? err.message : String(err);
         // Registry name-collision from --name (#829) — surface as an
         // actionable error rather than a generic stack-trace.
         if (err instanceof RegistryNameCollisionError) {

package/dist/cli/index.js

@@ -38,6 +38,7 @@ program
     .option('-v, --verbose', 'Enable verbose ingestion warnings (default: false)')
     .option('--max-file-size <kb>', 'Skip files larger than this (KB). Default: 512. Hard cap: 32768 (tree-sitter limit).')
     .option('--worker-timeout <seconds>', 'Worker sub-batch idle timeout before retry/fallback. Default: 30.')
+    .option('--workers <n>', 'Parse worker pool size. Default: cores-1 capped at 16. Pass 0 to disable workers (sequential).')
     .option('--embedding-threads <n>', 'Limit local ONNX embedding CPU threads')
     .option('--embedding-batch-size <n>', 'Number of nodes per embedding batch')
     .option('--embedding-sub-batch-size <n>', 'Number of chunks per embedding model call')
@@ -47,6 +48,11 @@ program
     '  GITNEXUS_MAX_FILE_SIZE=N  Override large-file skip threshold (KB). Default 512, max 32768.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS=N  Worker idle timeout in milliseconds. Default 30000.\n' +
     '  GITNEXUS_WORKER_SUB_BATCH_MAX_BYTES=N  Worker job byte budget. Default 8388608.\n' +
+    '  GITNEXUS_WORKER_POOL_SIZE=N  Parse worker count override. Default cores-1 capped at 16.\n' +
+    '  GITNEXUS_PARSE_CHUNK_CONCURRENCY=N  Concurrent in-flight parse chunks. Default 2.\n' +
+    '  GITNEXUS_WORKER_MAX_RESPAWNS_PER_SLOT=N  Max replacement spawns per slot before drop. Default 3.\n' +
+    '  GITNEXUS_WORKER_MAX_CUMULATIVE_TIMEOUT_MS=N  Total retry wall-time per job. Default 5x sub-batch timeout.\n' +
+    '  GITNEXUS_WORKER_CONSECUTIVE_FAILURE_THRESHOLD=N  Per-slot deaths to trip circuit breaker. Default max(3, poolSize).\n' +
     '  GITNEXUS_EMBEDDING_THREADS=N  Limit local ONNX CPU threads for --embeddings.\n' +
     '  GITNEXUS_SEMANTIC_EXACT_SCAN_LIMIT=N  Max embedding chunks for exact-scan fallback. Default 10000.\n' +
     '\nTip: `.gitnexusignore` supports `.gitignore`-style negation. Add e.g.\n' +

package/dist/cli/wiki.js

@@ -80,6 +80,25 @@ function prompt(question, hide = false) {
     });
 }
 export const wikiCommand = async (inputPath, options) => {
+    // Snapshot GITNEXUS_VERBOSE at entry — wikiCommand mutates it (the impl
+    // below) so cursor-client (process.env-driven) sees the right value during
+    // this run. Restored in finally so back-to-back wiki calls in long-running
+    // hosts don't leak verbose state from one invocation to the next. Pairs
+    // with the same snapshot/restore pattern in `analyzeCommand`.
+    const originalVerbose = process.env.GITNEXUS_VERBOSE;
+    try {
+        await wikiCommandImpl(inputPath, options);
+    }
+    finally {
+        if (originalVerbose === undefined) {
+            delete process.env.GITNEXUS_VERBOSE;
+        }
+        else {
+            process.env.GITNEXUS_VERBOSE = originalVerbose;
+        }
+    }
+};
+const wikiCommandImpl = async (inputPath, options) => {
     // Set verbose mode globally for cursor-client to pick up
     if (options?.verbose) {
         process.env.GITNEXUS_VERBOSE = '1';

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

@@ -0,0 +1,7 @@
+import type { SyntaxNode } from '../../utils/ast-helpers.js';
+export interface KotlinArityMetadata {
+    readonly parameterCount: number | undefined;
+    readonly requiredParameterCount: number | undefined;
+    readonly parameterTypes: readonly string[] | undefined;
+}
+export declare function computeKotlinArityMetadata(fnNode: SyntaxNode): KotlinArityMetadata;

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

@@ -0,0 +1,20 @@
+import { kotlinMethodConfig } from '../../method-extractors/configs/jvm.js';
+export function computeKotlinArityMetadata(fnNode) {
+    const params = kotlinMethodConfig.extractParameters?.(fnNode) ?? [];
+    let hasVararg = false;
+    const parameterTypes = [];
+    for (const param of params) {
+        if (param.isVariadic)
+            hasVararg = true;
+        if (param.type !== null)
+            parameterTypes.push(param.type);
+    }
+    if (hasVararg)
+        parameterTypes.push('vararg');
+    const required = params.filter((p) => !p.isOptional && !p.isVariadic).length;
+    return {
+        parameterCount: hasVararg ? undefined : params.length,
+        requiredParameterCount: required,
+        parameterTypes: parameterTypes.length > 0 ? parameterTypes : undefined,
+    };
+}

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

@@ -0,0 +1,2 @@
+import type { Callsite, SymbolDefinition } from '../../../../_shared/index.js';
+export declare function kotlinArityCompatibility(def: SymbolDefinition, callsite: Callsite): 'compatible' | 'unknown' | 'incompatible';

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

@@ -0,0 +1,15 @@
+export function kotlinArityCompatibility(def, callsite) {
+    const min = def.requiredParameterCount;
+    const max = def.parameterCount;
+    if (min === undefined && max === undefined)
+        return 'unknown';
+    const argCount = callsite.arity;
+    if (!Number.isFinite(argCount) || argCount < 0)
+        return 'unknown';
+    const hasVararg = def.parameterTypes?.some((t) => t === 'vararg') ?? false;
+    if (min !== undefined && argCount < min)
+        return 'incompatible';
+    if (max !== undefined && argCount > max && !hasVararg)
+        return 'incompatible';
+    return 'compatible';
+}

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

@@ -0,0 +1,7 @@
+export declare function recordKotlinCacheHit(): void;
+export declare function recordKotlinCacheMiss(): void;
+export declare function getKotlinCaptureCacheStats(): {
+    readonly hits: number;
+    readonly misses: number;
+};
+export declare function resetKotlinCaptureCacheStats(): void;

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

@@ -0,0 +1,15 @@
+let hits = 0;
+let misses = 0;
+export function recordKotlinCacheHit() {
+    hits += 1;
+}
+export function recordKotlinCacheMiss() {
+    misses += 1;
+}
+export function getKotlinCaptureCacheStats() {
+    return { hits, misses };
+}
+export function resetKotlinCaptureCacheStats() {
+    hits = 0;
+    misses = 0;
+}

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

@@ -0,0 +1,2 @@
+import type { CaptureMatch } from '../../../../_shared/index.js';
+export declare function emitKotlinScopeCaptures(sourceText: string, _filePath: string, cachedTree?: unknown): readonly CaptureMatch[];

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

@@ -0,0 +1,376 @@
+import { findNodeAtRange, nodeToCapture, syntheticCapture, } from '../../utils/ast-helpers.js';
+import { getTreeSitterBufferSize } from '../../constants.js';
+import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js';
+import { computeKotlinArityMetadata } from './arity-metadata.js';
+import { splitKotlinImportHeader } from './import-decomposer.js';
+import { recordKotlinCacheHit, recordKotlinCacheMiss } from './cache-stats.js';
+import { normalizeKotlinType } from './interpret.js';
+import { synthesizeKotlinReceiverBinding } from './receiver-binding.js';
+import { getKotlinParser, getKotlinScopeQuery } from './query.js';
+const FUNCTION_DECL_TAGS = ['@declaration.function'];
+export function emitKotlinScopeCaptures(sourceText, _filePath, cachedTree) {
+    let tree = cachedTree;
+    if (tree === undefined) {
+        tree = parseSourceSafe(getKotlinParser(), sourceText, undefined, {
+            bufferSize: getTreeSitterBufferSize(sourceText),
+        });
+        recordKotlinCacheMiss();
+    }
+    else {
+        recordKotlinCacheHit();
+    }
+    const out = [];
+    const returnTypes = collectKotlinReturnTypeTexts(tree.rootNode);
+    out.push(...synthesizeKotlinLocalAssignmentBindings(tree.rootNode, returnTypes));
+    out.push(...synthesizeKotlinLoopBindings(tree.rootNode, returnTypes));
+    for (const match of getKotlinScopeQuery().matches(tree.rootNode)) {
+        const grouped = {};
+        for (const capture of match.captures) {
+            const tag = '@' + capture.name;
+            grouped[tag] = nodeToCapture(tag, capture.node);
+        }
+        if (Object.keys(grouped).length === 0)
+            continue;
+        if (grouped['@import.statement'] !== undefined) {
+            const importNode = findNodeAtRange(tree.rootNode, grouped['@import.statement'].range, 'import_header');
+            if (importNode !== null) {
+                const decomposed = splitKotlinImportHeader(importNode);
+                if (decomposed !== null) {
+                    out.push(decomposed);
+                    continue;
+                }
+            }
+        }
+        if (grouped['@reference.call.free'] !== undefined &&
+            grouped['@reference.receiver'] !== undefined) {
+            continue;
+        }
+        if (grouped['@reference.read.member'] !== undefined) {
+            const anchor = grouped['@reference.read.member'];
+            const navNode = findNodeAtRange(tree.rootNode, anchor.range, 'navigation_expression');
+            if (navNode === null || !shouldEmitReadMember(navNode))
+                continue;
+        }
+        if (grouped['@scope.function'] !== undefined) {
+            out.push(grouped);
+            const fnNode = findNodeAtRange(tree.rootNode, grouped['@scope.function'].range, 'function_declaration');
+            if (fnNode !== null) {
+                out.push(...synthesizeKotlinReceiverBinding(fnNode));
+            }
+            continue;
+        }
+        const declTag = FUNCTION_DECL_TAGS.find((tag) => grouped[tag] !== undefined);
+        if (declTag !== undefined) {
+            const fnNode = findNodeAtRange(tree.rootNode, grouped[declTag].range, 'function_declaration');
+            if (fnNode !== null) {
+                const arity = computeKotlinArityMetadata(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));
+                }
+            }
+        }
+        const callTag = ['@reference.call.free', '@reference.call.member', '@reference.call.constructor'].find((tag) => grouped[tag] !== undefined);
+        if (callTag !== undefined && grouped['@reference.arity'] === undefined) {
+            const callNode = findNodeAtRange(tree.rootNode, grouped[callTag].range, 'call_expression');
+            if (callNode !== null) {
+                const args = callArguments(callNode);
+                grouped['@reference.arity'] = syntheticCapture('@reference.arity', callNode, String(args.length));
+                grouped['@reference.parameter-types'] = syntheticCapture('@reference.parameter-types', callNode, JSON.stringify(args.map(inferArgType)));
+            }
+        }
+        out.push(grouped);
+        const extensionFallback = extensionFreeCallFallback(grouped, tree.rootNode);
+        if (extensionFallback !== null)
+            out.push(extensionFallback);
+    }
+    return out;
+}
+function synthesizeKotlinLoopBindings(rootNode, returnTypes) {
+    const out = [];
+    for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+        const localTypes = collectKotlinLocalTypeTexts(fnNode, returnTypes);
+        for (const forNode of descendantsOfType(fnNode, 'for_statement')) {
+            const variable = forNode.namedChildren.find((child) => child.type === 'variable_declaration');
+            const name = variable?.namedChildren.find((child) => child.type === 'simple_identifier');
+            if (variable === undefined || name === undefined)
+                continue;
+            const explicitType = variable.namedChildren.find((child) => isKotlinTypeNode(child));
+            const iterable = forNode.namedChildren.find((child) => child.id !== variable.id && child.type !== 'control_structure_body');
+            const rawType = explicitType?.text ??
+                (iterable === undefined
+                    ? null
+                    : inferKotlinIterableElementType(iterable, localTypes, returnTypes));
+            if (rawType === null || rawType.trim() === '')
+                continue;
+            const anchor = forNode.namedChildren.find((child) => child.type === 'control_structure_body') ?? forNode;
+            out.push({
+                '@type-binding.annotation': nodeToCapture('@type-binding.annotation', anchor),
+                '@type-binding.name': syntheticCapture('@type-binding.name', name, name.text),
+                '@type-binding.type': syntheticCapture('@type-binding.type', explicitType ?? iterable ?? name, normalizeKotlinType(rawType)),
+            });
+        }
+    }
+    return out;
+}
+function synthesizeKotlinLocalAssignmentBindings(rootNode, returnTypes) {
+    const out = [];
+    for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+        const localTypes = new Map();
+        for (const prop of descendantsOfType(fnNode, 'property_declaration')) {
+            const inferred = inferKotlinPropertyType(prop, localTypes, returnTypes);
+            if (inferred === null)
+                continue;
+            localTypes.set(inferred.name.text, inferred.rawType);
+            if (inferred.synthetic) {
+                out.push({
+                    '@type-binding.annotation': nodeToCapture('@type-binding.annotation', prop),
+                    '@type-binding.name': syntheticCapture('@type-binding.name', inferred.name, inferred.name.text),
+                    '@type-binding.type': syntheticCapture('@type-binding.type', inferred.source, normalizeKotlinType(inferred.rawType)),
+                });
+            }
+        }
+    }
+    return out;
+}
+function collectKotlinLocalTypeTexts(fnNode, returnTypes) {
+    const out = new Map();
+    for (const node of descendants(fnNode)) {
+        if (node.type === 'parameter') {
+            const name = descendantsOfType(node, 'simple_identifier')[0];
+            const type = node.namedChildren.find((child) => isKotlinTypeNode(child));
+            if (name !== undefined && type !== undefined)
+                out.set(name.text, type.text);
+            continue;
+        }
+        if (node.type === 'property_declaration') {
+            const inferred = inferKotlinPropertyType(node, out, returnTypes);
+            if (inferred !== null)
+                out.set(inferred.name.text, inferred.rawType);
+        }
+    }
+    return out;
+}
+function collectKotlinReturnTypeTexts(rootNode) {
+    const out = new Map();
+    for (const fnNode of descendantsOfType(rootNode, 'function_declaration')) {
+        const name = fnNode.namedChildren.find((child) => child.type === 'simple_identifier');
+        const paramsIndex = fnNode.namedChildren.findIndex((child) => child.type === 'function_value_parameters');
+        const type = paramsIndex < 0
+            ? undefined
+            : fnNode.namedChildren.slice(paramsIndex + 1).find((child) => isKotlinTypeNode(child));
+        if (name !== undefined && type !== undefined)
+            out.set(name.text, type.text);
+    }
+    return out;
+}
+function inferKotlinPropertyType(prop, localTypes, returnTypes) {
+    const variable = prop.namedChildren.find((child) => child.type === 'variable_declaration');
+    const name = variable?.namedChildren.find((child) => child.type === 'simple_identifier');
+    if (variable === undefined || name === undefined)
+        return null;
+    const explicitType = variable.namedChildren.find((child) => isKotlinTypeNode(child));
+    if (explicitType !== undefined) {
+        return { name, rawType: explicitType.text, source: explicitType, synthetic: false };
+    }
+    const value = prop.namedChildren.find((child) => child.id !== variable.id && child.type !== 'binding_pattern_kind');
+    if (value?.type === 'simple_identifier') {
+        const rawType = localTypes.get(value.text);
+        return rawType === undefined ? null : { name, rawType, source: value, synthetic: true };
+    }
+    if (value?.type === 'call_expression') {
+        const callee = value.namedChildren.find((child) => child.type === 'simple_identifier');
+        if (callee === undefined)
+            return null;
+        const rawType = returnTypes.get(callee.text) ?? (isUppercaseName(callee.text) ? callee.text : null);
+        if (rawType === null)
+            return null;
+        return { name, rawType, source: callee, synthetic: true };
+    }
+    return null;
+}
+function inferKotlinIterableElementType(iterable, localTypes, returnTypes) {
+    if (iterable.type === 'simple_identifier') {
+        const raw = localTypes.get(iterable.text);
+        return raw === undefined ? null : kotlinContainerElementType(raw, 'values');
+    }
+    if (iterable.type === 'navigation_expression') {
+        const receiver = iterable.namedChildren[0];
+        const member = iterable.namedChildren
+            .find((child) => child.type === 'navigation_suffix')
+            ?.namedChildren.find((child) => child.type === 'simple_identifier')?.text;
+        if (receiver?.type !== 'simple_identifier')
+            return null;
+        const raw = localTypes.get(receiver.text);
+        return raw === undefined ? null : kotlinContainerElementType(raw, member ?? 'values');
+    }
+    if (iterable.type === 'call_expression') {
+        const callee = iterable.namedChildren.find((child) => child.type === 'simple_identifier');
+        if (callee === undefined)
+            return null;
+        const raw = returnTypes.get(callee.text);
+        return raw === undefined ? null : kotlinContainerElementType(raw, 'values');
+    }
+    return null;
+}
+function isUppercaseName(text) {
+    return /^[A-Z]/.test(text);
+}
+function kotlinContainerElementType(rawType, member) {
+    const parsed = parseKotlinGeneric(rawType);
+    if (parsed === null)
+        return normalizeKotlinType(rawType);
+    const base = parsed.base.split('.').pop() ?? parsed.base;
+    if (isKotlinMapType(base)) {
+        if (member === 'keys')
+            return parsed.args[0] ?? null;
+        return parsed.args[1] ?? null;
+    }
+    if (isKotlinIterableType(base))
+        return parsed.args[0] ?? null;
+    return normalizeKotlinType(rawType);
+}
+function parseKotlinGeneric(text) {
+    const trimmed = text.trim().replace(/\?$/, '');
+    const open = trimmed.indexOf('<');
+    const close = trimmed.lastIndexOf('>');
+    if (open < 0 || close < open)
+        return null;
+    return {
+        base: trimmed.slice(0, open).trim(),
+        args: splitTopLevelKotlinArgs(trimmed.slice(open + 1, close)),
+    };
+}
+function splitTopLevelKotlinArgs(text) {
+    const out = [];
+    let depth = 0;
+    let start = 0;
+    for (let i = 0; i < text.length; i++) {
+        const ch = text[i];
+        if (ch === '<')
+            depth++;
+        else if (ch === '>')
+            depth--;
+        else if (ch === ',' && depth === 0) {
+            out.push(text.slice(start, i).trim());
+            start = i + 1;
+        }
+    }
+    out.push(text.slice(start).trim());
+    return out.filter((arg) => arg.length > 0);
+}
+function isKotlinMapType(base) {
+    return ['Map', 'MutableMap', 'HashMap', 'LinkedHashMap'].includes(base);
+}
+function isKotlinIterableType(base) {
+    return [
+        'List',
+        'MutableList',
+        'ArrayList',
+        'Set',
+        'MutableSet',
+        'Collection',
+        'Iterable',
+        'Sequence',
+        'Array',
+    ].includes(base);
+}
+function isKotlinTypeNode(node) {
+    return (node.type === 'user_type' || node.type === 'nullable_type' || node.type === 'function_type');
+}
+function descendantsOfType(node, type) {
+    return descendants(node).filter((child) => child.type === type);
+}
+function descendants(node) {
+    const out = [];
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (child === null)
+            continue;
+        out.push(child, ...descendants(child));
+    }
+    return out;
+}
+function shouldEmitReadMember(navNode) {
+    const parent = navNode.parent;
+    if (parent === null)
+        return true;
+    if (parent.type === 'call_expression')
+        return false;
+    if (parent.type === 'directly_assignable_expression')
+        return false;
+    return true;
+}
+function callArguments(callNode) {
+    const suffix = callNode.namedChildren.find((child) => child.type === 'call_suffix');
+    if (suffix === undefined)
+        return [];
+    const valueArgs = suffix?.namedChildren.find((child) => child.type === 'value_arguments');
+    const args = valueArgs?.namedChildren.filter((child) => child.type === 'value_argument') ?? [];
+    const trailingLambdas = suffix.namedChildren.filter((child) => child.type === 'annotated_lambda');
+    return [...args, ...trailingLambdas];
+}
+function inferArgType(argNode) {
+    const value = argNode.namedChild(0) ?? argNode;
+    switch (value.type) {
+        case 'integer_literal':
+        case 'long_literal':
+            return 'Int';
+        case 'real_literal':
+            return 'Double';
+        case 'string_literal':
+        case 'line_string_literal':
+        case 'multi_line_string_literal':
+            return 'String';
+        case 'character_literal':
+            return 'Char';
+        case 'boolean_literal':
+            return 'Boolean';
+        case 'call_expression': {
+            const first = value.namedChild(0);
+            return first?.type === 'simple_identifier' ? first.text : '';
+        }
+        default:
+            return '';
+    }
+}
+function extensionFreeCallFallback(grouped, rootNode) {
+    const member = grouped['@reference.call.member'];
+    const receiver = grouped['@reference.receiver'];
+    const name = grouped['@reference.name'];
+    if (member === undefined || receiver === undefined || name === undefined)
+        return null;
+    const callNode = findNodeAtRange(rootNode, member.range, 'call_expression');
+    if (callNode === null)
+        return null;
+    const receiverNode = findNodeAtRange(rootNode, receiver.range);
+    if (receiverNode === null || !isLiteralReceiver(receiverNode))
+        return null;
+    const out = {
+        '@reference.call.free': syntheticCapture('@reference.call.free', callNode, callNode.text),
+        '@reference.name': syntheticCapture('@reference.name', callNode, name.text),
+    };
+    if (grouped['@reference.arity'] !== undefined)
+        out['@reference.arity'] = grouped['@reference.arity'];
+    if (grouped['@reference.parameter-types'] !== undefined) {
+        out['@reference.parameter-types'] = grouped['@reference.parameter-types'];
+    }
+    return out;
+}
+function isLiteralReceiver(node) {
+    return [
+        'integer_literal',
+        'long_literal',
+        'real_literal',
+        'string_literal',
+        'line_string_literal',
+        'multi_line_string_literal',
+        'character_literal',
+        'boolean_literal',
+    ].includes(node.type);
+}

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

@@ -0,0 +1,3 @@
+import type { CaptureMatch } from '../../../../_shared/index.js';
+import { type SyntaxNode } from '../../utils/ast-helpers.js';
+export declare function splitKotlinImportHeader(importNode: SyntaxNode): CaptureMatch | null;