From 2bf6d078aac60757f3a8a4ad905922210f8042b6 Mon Sep 17 00:00:00 2001 From: Gergo Magyar Date: Tue, 12 May 2026 09:07:47 +0100 Subject: [PATCH 01/33] ci(claude): allow Bash in code-review job without interactive approval Claude Code defaults to prompting for Bash approval. In GitHub Actions there is no human to approve, so gh pr comment and similar commands fail and the PR receives no review comment. Pass --dangerously-skip-permissions for the code-review step only (headless CI; token and checkout are already scoped). Co-authored-by: Cursor --- .github/workflows/claude.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.github/workflows/claude.yml b/.github/workflows/claude.yml index 4f43c3d9d..021a56930 100644 --- a/.github/workflows/claude.yml +++ b/.github/workflows/claude.yml @@ -158,6 +158,8 @@ jobs: github_token: ${{ secrets.GITHUB_TOKEN }} allowed_non_write_users: '*' show_full_output: true + # Review posts use Bash (`gh`, etc.); default mode asks for approval — impossible in CI. + claude_args: '--dangerously-skip-permissions' plugin_marketplaces: 'https://github.com/anthropics/claude-code.git' plugins: 'code-review@claude-code-plugins' prompt: '/code-review:code-review https://github.com/${{ github.repository }}/pull/${{ steps.pr.outputs.number }} --comment' From d4f34905bc09e973913030a6b0a5f0045a3d6f89 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Tue, 12 May 2026 09:37:44 +0100 Subject: [PATCH 02/33] feat: migrate Java to scope-based registry resolution (RFC #909 Ring 3) (#1482) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * feat: implement Java scope-based resolution (RFC #909 Ring 3) Add scope-resolution pipeline for Java, following the C# pattern: - query.ts: tree-sitter query for scopes, declarations, imports, type bindings, and references against tree-sitter-java grammar - captures.ts: orchestrator synthesizing import decomposition, receiver bindings (this/super), arity metadata, and reference arity - import-decomposer.ts: decompose import_declaration nodes into kind/source/name markers (named, wildcard, static, static-wildcard) - interpret.ts: convert captures to ParsedImport/ParsedTypeBinding - receiver-binding.ts: synthesize this/super type-bindings on instance methods with superclass support - arity-metadata.ts: extract parameter count/types using javaMethodConfig - arity.ts: Java arity compatibility check with varargs support - merge-bindings.ts: Java shadowing precedence (local > import > wildcard) - simple-hooks.ts: bindingScopeFor, importOwningScope, receiverBinding - import-target.ts: package path to file path resolution - scope-resolver.ts: ScopeResolver implementation registered in registry Wire scope hooks into javaProvider (java.ts) and register javaScopeResolver in SCOPE_RESOLVERS registry. Add createResolverParityIt wrapper to java.test.ts for parity testing. All 172 existing Java tests pass. Java is NOT added to MIGRATED_LANGUAGES — the resolver sits idle until the migration flag is flipped. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * chore(autofix): apply prettier + eslint fixes via /autofix command * fix: address review findings 1-4 — varargs arity, static import resolution, importOwningScope, stripGeneric Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/22308da3-59c9-47e6-8e52-738305b1b80a Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * docs: document registry-primary parity status and CI visibility gap in scope-resolver Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/22308da3-59c9-47e6-8e52-738305b1b80a Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix: add generic type erasure fallback in stripGeneric + update scope-resolver docs Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/223f77ac-59a7-4487-9316-f2be05eac5d3 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix: improve stripGeneric fallback regex — use valid Java identifier chars and handle nested generics Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/223f77ac-59a7-4487-9316-f2be05eac5d3 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix: address adversarial review findings 1-6 — flaky test, wildcard import fixture, varargs fixed-prefix test, qualified generic stripping, JSDoc updates Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/172c8a1a-cdf3-4de8-9142-f2c12c14b0a6 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * docs: add inline comment explaining stripQualifier/stripGeneric call order Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/172c8a1a-cdf3-4de8-9142-f2c12c14b0a6 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test: add varargs 0-arg fixture and strengthen wildcard import assertions Finding 1: Added `badCall()` method with 0-arg `fmt.format()` call to the varargs fixture. Test documents that legacy mode still resolves this call (arity rejection is registry-primary only). The fixture now exercises both the success path (2-arg, 3-arg) and the undersupplied path (0-arg). Finding 2: Strengthened wildcard import test to assert `targetFilePath` on the CALLS edge (`com/example/models/User.java`), confirming the call resolved through the wildcard-imported type to the correct file. Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/2b4e5602-9833-485c-ab48-e1d54fdf8465 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * chore(autofix): apply prettier + eslint fixes via /autofix command --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Gergő Magyar --- gitnexus/src/core/ingestion/languages/java.ts | 22 ++ .../languages/java/arity-metadata.ts | 49 ++++ .../core/ingestion/languages/java/arity.ts | 31 +++ .../ingestion/languages/java/cache-stats.ts | 30 +++ .../core/ingestion/languages/java/captures.ts | 235 ++++++++++++++++++ .../languages/java/import-decomposer.ts | 104 ++++++++ .../ingestion/languages/java/import-target.ts | 108 ++++++++ .../core/ingestion/languages/java/index.ts | 30 +++ .../ingestion/languages/java/interpret.ts | 141 +++++++++++ .../languages/java/merge-bindings.ts | 44 ++++ .../core/ingestion/languages/java/query.ts | 197 +++++++++++++++ .../languages/java/receiver-binding.ts | 103 ++++++++ .../languages/java/scope-resolver.ts | 97 ++++++++ .../ingestion/languages/java/simple-hooks.ts | 54 ++++ .../scope-resolution/pipeline/registry.ts | 2 + .../com/example/app/Main.java | 15 ++ .../com/example/util/Formatter.java | 8 + .../com/example/app/Main.java | 10 + .../com/example/models/Order.java | 7 + .../com/example/models/User.java | 7 + .../test/integration/resolvers/java.test.ts | 53 +++- gitnexus/test/integration/worker-pool.test.ts | 2 +- 22 files changed, 1347 insertions(+), 2 deletions(-) create mode 100644 gitnexus/src/core/ingestion/languages/java/arity-metadata.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/arity.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/cache-stats.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/captures.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/import-decomposer.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/import-target.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/index.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/interpret.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/merge-bindings.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/query.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/receiver-binding.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/scope-resolver.ts create mode 100644 gitnexus/src/core/ingestion/languages/java/simple-hooks.ts create mode 100644 gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/util/Formatter.java create mode 100644 gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/app/Main.java create mode 100644 gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/Order.java create mode 100644 gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/User.java diff --git a/gitnexus/src/core/ingestion/languages/java.ts b/gitnexus/src/core/ingestion/languages/java.ts index 96139ccda..c70eacb10 100644 --- a/gitnexus/src/core/ingestion/languages/java.ts +++ b/gitnexus/src/core/ingestion/languages/java.ts @@ -27,6 +27,17 @@ import { javaMethodConfig } from '../method-extractors/configs/jvm.js'; import { createVariableExtractor } from '../variable-extractors/generic.js'; import { javaVariableConfig } from '../variable-extractors/configs/jvm.js'; import { createHeritageExtractor } from '../heritage-extractors/generic.js'; +import { + emitJavaScopeCaptures, + interpretJavaImport, + interpretJavaTypeBinding, + javaBindingScopeFor, + javaImportOwningScope, + javaMergeBindings, + javaReceiverBinding, + javaArityCompatibility, + resolveJavaImportTarget, +} from './java/index.js'; export const javaProvider = defineLanguage({ id: SupportedLanguages.Java, @@ -65,4 +76,15 @@ export const javaProvider = defineLanguage({ variableExtractor: createVariableExtractor(javaVariableConfig), classExtractor: createClassExtractor(javaClassConfig), heritageExtractor: createHeritageExtractor(SupportedLanguages.Java), + + // ── RFC #909 Ring 3: scope-based resolution hooks ── + emitScopeCaptures: emitJavaScopeCaptures, + interpretImport: interpretJavaImport, + interpretTypeBinding: interpretJavaTypeBinding, + bindingScopeFor: javaBindingScopeFor, + importOwningScope: javaImportOwningScope, + mergeBindings: (_scope, bindings) => javaMergeBindings(bindings), + receiverBinding: javaReceiverBinding, + arityCompatibility: javaArityCompatibility, + resolveImportTarget: resolveJavaImportTarget, }); diff --git a/gitnexus/src/core/ingestion/languages/java/arity-metadata.ts b/gitnexus/src/core/ingestion/languages/java/arity-metadata.ts new file mode 100644 index 000000000..47cccbff9 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/arity-metadata.ts @@ -0,0 +1,49 @@ +/** + * 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'; +import { javaMethodConfig } from '../../method-extractors/configs/jvm.js'; + +export interface JavaArityMetadata { + readonly parameterCount: number | undefined; + readonly requiredParameterCount: number | undefined; + readonly parameterTypes: readonly string[] | undefined; +} + +export function computeJavaArityMetadata(fnNode: SyntaxNode): JavaArityMetadata { + const params = javaMethodConfig.extractParameters?.(fnNode) ?? []; + + let hasVariadic = false; + const types: string[] = []; + 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, + }; +} diff --git a/gitnexus/src/core/ingestion/languages/java/arity.ts b/gitnexus/src/core/ingestion/languages/java/arity.ts new file mode 100644 index 000000000..f98a8209d --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/arity.ts @@ -0,0 +1,31 @@ +/** + * 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 'gitnexus-shared'; + +export function javaArityCompatibility( + def: SymbolDefinition, + callsite: Callsite, +): 'compatible' | 'unknown' | 'incompatible' { + 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'; +} diff --git a/gitnexus/src/core/ingestion/languages/java/cache-stats.ts b/gitnexus/src/core/ingestion/languages/java/cache-stats.ts new file mode 100644 index 000000000..a4c58f11f --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/cache-stats.ts @@ -0,0 +1,30 @@ +/** + * 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(): void { + if (PROF) CACHE_HITS++; +} + +export function recordCacheMiss(): void { + if (PROF) CACHE_MISSES++; +} + +export function getJavaCaptureCacheStats(): { hits: number; misses: number } { + return { hits: CACHE_HITS, misses: CACHE_MISSES }; +} + +export function resetJavaCaptureCacheStats(): void { + CACHE_HITS = 0; + CACHE_MISSES = 0; +} diff --git a/gitnexus/src/core/ingestion/languages/java/captures.ts b/gitnexus/src/core/ingestion/languages/java/captures.ts new file mode 100644 index 000000000..73ea605fe --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/captures.ts @@ -0,0 +1,235 @@ +/** + * `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 { Capture, CaptureMatch } from 'gitnexus-shared'; +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'] as const; + +/** tree-sitter-java node types that the method extractor accepts. */ +const FUNCTION_NODE_TYPES = ['method_declaration', 'constructor_declaration'] as const; + +/** 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: SyntaxNode): boolean { + 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: string, + _filePath: string, + cachedTree?: unknown, +): readonly CaptureMatch[] { + let tree = cachedTree as ReturnType['parse']> | undefined; + if (tree === undefined) { + tree = parseSourceSafe(getJavaParser(), sourceText, undefined, { + bufferSize: getTreeSitterBufferSize(sourceText), + }); + recordCacheMiss(); + } else { + recordCacheHit(); + } + + const rawMatches = getJavaScopeQuery().matches(tree.rootNode); + const out: CaptureMatch[] = []; + + for (const m of rawMatches) { + const grouped: Record = {}; + 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'] as const + ).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; +} + +type SyntaxNode = ReturnType['parse']>['rootNode']; + +/** Infer a Java argument's static type from literal patterns. */ +function inferArgType(argNode: SyntaxNode): string { + 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: SyntaxNode, range: Capture['range']): SyntaxNode | null { + for (const nodeType of FUNCTION_NODE_TYPES) { + const n = findNodeAtRange(rootNode, range, nodeType); + if (n !== null) return n as SyntaxNode; + } + return null; +} diff --git a/gitnexus/src/core/ingestion/languages/java/import-decomposer.ts b/gitnexus/src/core/ingestion/languages/java/import-decomposer.ts new file mode 100644 index 000000000..59c74d144 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/import-decomposer.ts @@ -0,0 +1,104 @@ +/** + * 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 { Capture, CaptureMatch } from 'gitnexus-shared'; +import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js'; + +type ImportKind = 'named' | 'wildcard' | 'static' | 'static-wildcard'; + +interface ImportSpec { + readonly kind: ImportKind; + /** Full dotted path: `com.example.User`. */ + readonly source: string; + /** Local binding name — last path segment for named/static, + * `'*'` for wildcard/static-wildcard. */ + readonly name: string; + /** Node to anchor the synthesized captures (range-wise). */ + readonly atNode: SyntaxNode; +} + +export function splitImportDeclaration(stmtNode: SyntaxNode): CaptureMatch | null { + if (stmtNode.type !== 'import_declaration') return null; + const spec = parseImportDeclaration(stmtNode); + if (spec === null) return null; + return buildImportMatch(stmtNode, spec); +} + +function parseImportDeclaration(node: SyntaxNode): ImportSpec | null { + // 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: SyntaxNode | null = 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: SyntaxNode, spec: ImportSpec): CaptureMatch { + const m: Record = { + '@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; +} diff --git a/gitnexus/src/core/ingestion/languages/java/import-target.ts b/gitnexus/src/core/ingestion/languages/java/import-target.ts new file mode 100644 index 000000000..b78b6369b --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/import-target.ts @@ -0,0 +1,108 @@ +/** + * 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 'gitnexus-shared'; + +export interface JavaResolveContext { + readonly fromFile: string; + readonly allFilePaths: ReadonlySet; +} + +export function resolveJavaImportTarget( + parsedImport: ParsedImport, + workspaceIndex: WorkspaceIndex, +): string | null { + const ctx = workspaceIndex as JavaResolveContext | undefined; + if ( + ctx === undefined || + typeof (ctx as { fromFile?: unknown }).fromFile !== 'string' || + !((ctx as { allFilePaths?: unknown }).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: string | null = null; + let suffixFile: string | null = null; + let directoryChild: string | null = 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: string | null = 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; +} diff --git a/gitnexus/src/core/ingestion/languages/java/index.ts b/gitnexus/src/core/ingestion/languages/java/index.ts new file mode 100644 index 000000000..443faac4b --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/index.ts @@ -0,0 +1,30 @@ +/** + * 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'; diff --git a/gitnexus/src/core/ingestion/languages/java/interpret.ts b/gitnexus/src/core/ingestion/languages/java/interpret.ts new file mode 100644 index 000000000..9c207d451 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/interpret.ts @@ -0,0 +1,141 @@ +/** + * 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, TypeRef } from 'gitnexus-shared'; + +// ─── interpretImport ────────────────────────────────────────────────────── + +export function interpretJavaImport(captures: CaptureMatch): ParsedImport | null { + 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: CaptureMatch): ParsedTypeBinding | null { + 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` becomes + // `BaseModel` 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: TypeRef['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`, `Optional` → `User`). + * 2. Known two-arg map/container types → extract the value type + * (`Map` → `User`). + * 3. **Fallback (JVM type erasure):** any other generic type → + * strip the generic parameters and keep the raw class name + * (`BaseModel` → `BaseModel`, `CustomList` → `CustomList`). + * This ensures receiver bindings (`this`/`super`) on classes with + * generic superclasses resolve to the correct class file. + */ +function stripGeneric(text: string): string { + // 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` → `BaseModel`, `Builder` → `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>` → `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: string): string { + const lastDot = text.lastIndexOf('.'); + if (lastDot === -1) return text; + return text.slice(lastDot + 1); +} diff --git a/gitnexus/src/core/ingestion/languages/java/merge-bindings.ts b/gitnexus/src/core/ingestion/languages/java/merge-bindings.ts new file mode 100644 index 000000000..9056705d0 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/merge-bindings.ts @@ -0,0 +1,44 @@ +/** + * 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 'gitnexus-shared'; + +const TIER_LOCAL = 0; +const TIER_IMPORT = 1; +const TIER_WILDCARD = 2; +const TIER_UNKNOWN = 3; + +function tierOf(b: BindingRef): number { + switch (b.origin) { + case 'local': + return TIER_LOCAL; + case 'reexport': + case 'import': + case 'namespace': + return TIER_IMPORT; + case 'wildcard': + return TIER_WILDCARD; + default: + return TIER_UNKNOWN; + } +} + +export function javaMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[] { + if (bindings.length === 0) return bindings; + + let bestTier = Number.POSITIVE_INFINITY; + for (const b of bindings) bestTier = Math.min(bestTier, tierOf(b)); + const survivors = bindings.filter((b) => tierOf(b) === bestTier); + + const seen = new Map(); + for (const b of survivors) seen.set(b.def.nodeId, b); + return [...seen.values()]; +} diff --git a/gitnexus/src/core/ingestion/languages/java/query.ts b/gitnexus/src/core/ingestion/languages/java/query.ts new file mode 100644 index 000000000..3fabbb7bf --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/query.ts @@ -0,0 +1,197 @@ +/** + * Tree-sitter query for Java scope captures (RFC §5.1). + * + * Captures the structural skeleton the generic scope-resolution + * pipeline consumes: scopes (module/class/function), declarations + * (class-likes, method-likes, fields, variables), imports (import + * declarations), type bindings (parameter annotations, variable + * annotations, constructor inference), and references (call sites, + * member writes/reads). + * + * Java specifics that shape this query: + * + * - Java uses `program` as the root node (not `compilation_unit`). + * - `import_declaration` nodes carry `scoped_identifier` children + * and optional `asterisk` for wildcard imports. + * - `static` imports are detected by an anonymous `static` token + * child within `import_declaration`. + * - `var` (Java 10+ local variable type inference) parses as a + * `type_identifier` with text `"var"`, not a dedicated node type. + * - Modifiers (`public`, `static`, etc.) are grouped under a + * `modifiers` named child with anonymous keyword tokens. + * - Superclass inheritance uses a `superclass:` field containing + * a `superclass` node wrapping a `type_identifier`. + * + * Exposes lazy `Parser` and `Query` singletons so callers don't pay + * tree-sitter init cost per file. + */ + +import Parser from 'tree-sitter'; +import Java from 'tree-sitter-java'; + +const JAVA_SCOPE_QUERY = ` +;; Scopes +(program) @scope.module + +(class_declaration) @scope.class +(interface_declaration) @scope.class +(enum_declaration) @scope.class +(record_declaration) @scope.class +(annotation_type_declaration) @scope.class + +(method_declaration) @scope.function +(constructor_declaration) @scope.function + +;; Declarations — types +(class_declaration + name: (identifier) @declaration.name) @declaration.class + +(interface_declaration + name: (identifier) @declaration.name) @declaration.interface + +(enum_declaration + name: (identifier) @declaration.name) @declaration.enum + +(record_declaration + name: (identifier) @declaration.name) @declaration.record + +(annotation_type_declaration + name: (identifier) @declaration.name) @declaration.class + +;; Declarations — methods / constructors +(method_declaration + name: (identifier) @declaration.name) @declaration.method + +(constructor_declaration + name: (identifier) @declaration.name) @declaration.constructor + +;; Declarations — fields +(field_declaration + declarator: (variable_declarator + name: (identifier) @declaration.name)) @declaration.variable + +;; Declarations — local variables +(local_variable_declaration + declarator: (variable_declarator + name: (identifier) @declaration.name)) @declaration.variable + +;; Imports — single anchor per import_declaration +(import_declaration) @import.statement + +;; Type bindings — parameter annotations: void f(User u) +(formal_parameter + type: (type_identifier) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.parameter + +(formal_parameter + type: (generic_type) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.parameter + +(formal_parameter + type: (scoped_type_identifier) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.parameter + +;; Type bindings — local variable annotations: User u = new User(); +(local_variable_declaration + type: (type_identifier) @type-binding.type + declarator: (variable_declarator + name: (identifier) @type-binding.name)) @type-binding.annotation + +(local_variable_declaration + type: (generic_type) @type-binding.type + declarator: (variable_declarator + name: (identifier) @type-binding.name)) @type-binding.annotation + +;; Type bindings — var u = new User(); (Java 10+ local variable type inference) +;; tree-sitter-java parses \`var\` as a \`type_identifier\` with text "var". +;; The type-binding.constructor anchor fires when the rhs is an +;; object_creation_expression so interpretJavaTypeBinding can infer +;; the concrete type from the constructor call. +(local_variable_declaration + type: (type_identifier) @_var_type + declarator: (variable_declarator + name: (identifier) @type-binding.name + value: (object_creation_expression + type: (type_identifier) @type-binding.type))) @type-binding.constructor + +;; Type bindings — field declarations: private User user; +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (variable_declarator + name: (identifier) @type-binding.name)) @type-binding.annotation + +(field_declaration + type: (generic_type) @type-binding.type + declarator: (variable_declarator + name: (identifier) @type-binding.name)) @type-binding.annotation + +;; Type bindings — method return type: public User getUser() { } +(method_declaration + type: (type_identifier) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.return + +(method_declaration + type: (generic_type) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.return + +;; Type bindings — enhanced for: for (User u : list) +(enhanced_for_statement + type: (type_identifier) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.annotation + +(enhanced_for_statement + type: (generic_type) @type-binding.type + name: (identifier) @type-binding.name) @type-binding.annotation + +;; References — all method calls: foo() and obj.method() +;; tree-sitter-java's query engine drops negation-based \`!object\` +;; patterns when a positive \`object:\` pattern exists for the same +;; node type, so we match all calls here and classify free vs +;; member in captures.ts based on the presence of @reference.receiver. +(method_invocation + object: (_) @reference.receiver + name: (identifier) @reference.name) @reference.call.member + +(method_invocation + name: (identifier) @reference.name) @reference.call.free + +;; References — constructor calls: new User(...) +(object_creation_expression + type: (type_identifier) @reference.name) @reference.call.constructor + +(object_creation_expression + type: (generic_type + (type_identifier) @reference.name)) @reference.call.constructor + +(object_creation_expression + type: (scoped_type_identifier) @reference.call.constructor.qualified) @reference.call.constructor + +;; References — field/property writes: obj.name = "x" +(assignment_expression + left: (field_access + object: (_) @reference.receiver + field: (identifier) @reference.name)) @reference.write.member + +;; References — field/property reads: obj.name +(field_access + object: (_) @reference.receiver + field: (identifier) @reference.name) @reference.read.member +`; + +let _parser: Parser | null = null; +let _query: Parser.Query | null = null; + +export function getJavaParser(): Parser { + if (_parser === null) { + _parser = new Parser(); + _parser.setLanguage(Java as Parameters[0]); + } + return _parser; +} + +export function getJavaScopeQuery(): Parser.Query { + if (_query === null) { + _query = new Parser.Query(Java as Parameters[0], JAVA_SCOPE_QUERY); + } + return _query; +} diff --git a/gitnexus/src/core/ingestion/languages/java/receiver-binding.ts b/gitnexus/src/core/ingestion/languages/java/receiver-binding.ts new file mode 100644 index 000000000..4d6d60ded --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/receiver-binding.ts @@ -0,0 +1,103 @@ +/** + * Synthesize `@type-binding.self` captures for Java instance methods — + * one for `this` (always on non-static methods inside a type + * declaration) and optionally one for `super` (only on class methods + * when the enclosing class has a `superclass`). + * + * Mirrors `languages/csharp/receiver-binding.ts` in structure. + */ + +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js'; + +const TYPE_DECL_NODE_TYPES = new Set([ + 'class_declaration', + 'interface_declaration', + 'enum_declaration', + 'record_declaration', +]); + +const FUNCTION_NODE_TYPES = new Set(['method_declaration', 'constructor_declaration']); + +/** Walk up to the enclosing type declaration. */ +function findEnclosingTypeDeclaration(node: SyntaxNode): SyntaxNode | null { + let cur: SyntaxNode | null = node.parent; + while (cur !== null) { + if (TYPE_DECL_NODE_TYPES.has(cur.type)) return cur; + cur = cur.parent; + } + return null; +} + +function typeName(typeNode: SyntaxNode): string | null { + return typeNode.childForFieldName('name')?.text ?? null; +} + +/** First superclass text. tree-sitter-java uses a `superclass` field + * containing a `superclass` node wrapping a `type_identifier`. */ +function firstSuperclassText(typeNode: SyntaxNode): string | null { + const superclass = typeNode.childForFieldName('superclass'); + if (superclass === null) return null; + // The superclass node wraps the type_identifier + for (let i = 0; i < superclass.namedChildCount; i++) { + const child = superclass.namedChild(i); + if (child !== null && (child.type === 'type_identifier' || child.type === 'generic_type')) { + return child.text; + } + } + return null; +} + +/** Check if a method has the `static` modifier. In tree-sitter-java, + * modifiers are grouped under a `modifiers` named child with anonymous + * keyword tokens. */ +function isStaticMethod(fnNode: SyntaxNode): boolean { + for (let i = 0; i < fnNode.namedChildCount; i++) { + const child = fnNode.namedChild(i); + if (child !== null && child.type === 'modifiers') { + for (let j = 0; j < child.childCount; j++) { + const mod = child.child(j); + if (mod !== null && mod.text.trim() === 'static') return true; + } + } + } + return false; +} + +export function synthesizeJavaReceiverBinding(fnNode: SyntaxNode): CaptureMatch[] { + if (!FUNCTION_NODE_TYPES.has(fnNode.type)) return []; + if (isStaticMethod(fnNode)) return []; + + const enclosingType = findEnclosingTypeDeclaration(fnNode); + if (enclosingType === null) return []; + + const enclosingName = typeName(enclosingType); + if (enclosingName === null) return []; + + // Anchor to the method body so the synthesized captures are inside + // the function scope. + const anchorNode = fnNode.childForFieldName('body'); + if (anchorNode === null) return []; + + const out: CaptureMatch[] = []; + out.push(buildReceiverMatch(anchorNode, 'this', enclosingName)); + + // `super` applies only to class/record methods with an explicit superclass. + if (enclosingType.type === 'class_declaration' || enclosingType.type === 'record_declaration') { + const superText = firstSuperclassText(enclosingType); + if (superText !== null) { + out.push(buildReceiverMatch(anchorNode, 'super', superText)); + } + } + + return out; +} + +function buildReceiverMatch(anchorNode: SyntaxNode, name: string, typeText: string): CaptureMatch { + const m: Record = { + '@type-binding.self': nodeToCapture('@type-binding.self', anchorNode), + '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, name), + '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeText), + }; + return m; +} diff --git a/gitnexus/src/core/ingestion/languages/java/scope-resolver.ts b/gitnexus/src/core/ingestion/languages/java/scope-resolver.ts new file mode 100644 index 000000000..dac974cc7 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/scope-resolver.ts @@ -0,0 +1,97 @@ +/** + * Java `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by + * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3). + * + * ## Registry-primary parity status + * + * Java is **not** in `MIGRATED_LANGUAGES` — the scope-resolution + * registry runs in shadow mode only. Parity in forced registry mode + * (`REGISTRY_PRIMARY_JAVA=1`) is 143/172 (83%). The 29 gaps fall into: + * + * - switch pattern binding / sealed-class exhaustiveness + * - Map.values() / entrySet() iteration type propagation + * - assignment / method chain return-type propagation across files + * - virtual dispatch / interface default methods + * + * These are the same category of advanced-resolution gaps seen in prior + * migrations (Python, C#, Go). Parity is below the ≥99% flip threshold + * per RFC §6.4. + * + * **CI visibility:** Because Java is absent from `MIGRATED_LANGUAGES`, + * the parity CI workflow (`ci-scope-parity.yml`) does not run Java in + * either `REGISTRY_PRIMARY_JAVA=0` or `=1` mode. Regressions in forced + * mode are only visible via manual `REGISTRY_PRIMARY_JAVA=1 npx vitest + * run java.test.ts`. Before flipping Java to registry-primary, a + * non-required CI step should be added to run Java tests in forced mode + * and report parity as a dashboard input. + * + * **Parity baseline (29 failures):** The 29 gaps in forced registry mode + * are tracked in this PR (#1482) and this JSDoc. If the gap count + * changes (up or down), update this baseline accordingly. + * + * ### Known flip-blockers (must fix before adding to MIGRATED_LANGUAGES) + * + * - Varargs arity: fixed-prefix count is now preserved, but no + * integration fixture exercises the 0-arg rejection path yet. + * - Static import resolution: `import static X.Y.m` now correctly + * resolves to `X/Y.java` (the class), not `X/Y/m.java` (the member). + * Edge cases with nested classes may remain. + * - Generic superclass receiver binding: `BaseModel` now strips + * to `BaseModel` via JVM type-erasure fallback in `stripGeneric`. + * - Wildcard import (`import com.example.*`) file selection is + * nondeterministic when multiple classes share a package directory. + * May produce wrong-file edges in forced mode. + * - Qualified generic type parameters in field/parameter annotations + * (`com.example.BaseModel`) — rare in practice but may miss + * resolution when the full qualifier is present with generics. + */ + +import type { ParsedFile } from 'gitnexus-shared'; +import { SupportedLanguages } from 'gitnexus-shared'; +import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js'; +import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js'; +import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js'; +import { javaProvider } from '../java.js'; +import { + javaArityCompatibility, + javaMergeBindings, + resolveJavaImportTarget, + type JavaResolveContext, +} from './index.js'; + +const javaScopeResolver: ScopeResolver = { + language: SupportedLanguages.Java, + languageProvider: javaProvider, + importEdgeReason: 'java-scope: import', + + resolveImportTarget: (targetRaw, fromFile, allFilePaths) => { + const ws: JavaResolveContext = { fromFile, allFilePaths }; + return resolveJavaImportTarget( + { kind: 'named', localName: '_', importedName: '_', targetRaw }, + ws, + ); + }, + + mergeBindings: (existing, incoming) => [...javaMergeBindings([...existing, ...incoming])], + + arityCompatibility: (callsite, def) => javaArityCompatibility(def, callsite), + + buildMro: (graph, parsedFiles, nodeLookup) => + buildMro(graph, parsedFiles, nodeLookup, defaultLinearize), + + populateOwners: (parsed: ParsedFile) => populateClassOwnedMembers(parsed), + + isSuperReceiver: (text) => text.trim() === 'super', + + // Java is statically typed — field-fallback heuristic stays off + fieldFallbackOnMethodLookup: false, + propagatesReturnTypesAcrossImports: true, + + // Java doesn't collapse member calls + collapseMemberCallsByCallerTarget: false, + + // Hoist return-type bindings to Module scope for cross-file propagation + hoistTypeBindingsToModule: true, +}; + +export { javaScopeResolver }; diff --git a/gitnexus/src/core/ingestion/languages/java/simple-hooks.ts b/gitnexus/src/core/ingestion/languages/java/simple-hooks.ts new file mode 100644 index 000000000..e69f768a6 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/java/simple-hooks.ts @@ -0,0 +1,54 @@ +/** + * Small hooks for the Java provider. Each is a few lines; they make + * the provider's choice explicit rather than relying on defaults. + */ + +import type { + CaptureMatch, + ParsedImport, + Scope, + ScopeId, + ScopeTree, + TypeRef, +} from 'gitnexus-shared'; + +// ─── bindingScopeFor ────────────────────────────────────────────────────── + +/** Method return-type bindings hoist to Module scope so cross-file + * `propagateImportedReturnTypes` and chain-follow can find them. */ +export function javaBindingScopeFor( + decl: CaptureMatch, + innermost: Scope, + tree: ScopeTree, +): ScopeId | null { + if (decl['@type-binding.return'] !== undefined) { + let cur: Scope | undefined = innermost; + while (cur !== undefined && cur.kind !== 'Module') { + const parentId: ScopeId | null = cur.parent ?? null; + if (parentId === null) break; + cur = tree.getScope(parentId); + } + if (cur !== undefined && cur.kind === 'Module') return cur.id; + } + return null; +} + +// ─── importOwningScope ──────────────────────────────────────────────────── + +/** Java imports are always at compilation-unit (Module) level (JLS §7.5). + * Return `null` unconditionally so the default Module scope is used. */ +export function javaImportOwningScope( + _imp: ParsedImport, + _innermost: Scope, + _tree: ScopeTree, +): ScopeId | null { + return null; +} + +// ─── receiverBinding ────────────────────────────────────────────────────── + +/** Look up `this` or `super` in the function scope's type bindings. */ +export function javaReceiverBinding(functionScope: Scope): TypeRef | null { + if (functionScope.kind !== 'Function') return null; + return functionScope.typeBindings.get('this') ?? functionScope.typeBindings.get('super') ?? null; +} diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts index 0667be8f5..ecd7b69aa 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts @@ -15,6 +15,7 @@ import { pythonScopeResolver } from '../../languages/python/scope-resolver.js'; import { csharpScopeResolver } from '../../languages/csharp/scope-resolver.js'; import { typescriptScopeResolver } from '../../languages/typescript/scope-resolver.js'; import { goScopeResolver } from '../../languages/go/scope-resolver.js'; +import { javaScopeResolver } from '../../languages/java/scope-resolver.js'; import { cScopeResolver } from '../../languages/c/scope-resolver.js'; /** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates @@ -29,5 +30,6 @@ export const SCOPE_RESOLVERS: ReadonlyMap = n [SupportedLanguages.CSharp, csharpScopeResolver], [SupportedLanguages.TypeScript, typescriptScopeResolver], [SupportedLanguages.Go, goScopeResolver], + [SupportedLanguages.Java, javaScopeResolver], [SupportedLanguages.C, cScopeResolver], ]); diff --git a/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/app/Main.java b/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/app/Main.java index e32e3c07e..88c3b71ac 100644 --- a/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/app/Main.java +++ b/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/app/Main.java @@ -1,10 +1,25 @@ package com.example.app; import com.example.util.Logger; +import com.example.util.Formatter; public class Main { public void run() { Logger logger = new Logger(); logger.record("hello", "world", "test"); + + Formatter fmt = new Formatter(); + // 2-arg call: satisfies fixed prefix (level) + 1 vararg + fmt.format(1, "hello"); + // 3-arg call: satisfies fixed prefix (level) + 2 varargs + fmt.format(2, "hello", "world"); + } + + public void badCall() { + Formatter fmt = new Formatter(); + // 0-arg call: does NOT satisfy the required fixed prefix (int level) + // This should be rejected by arity — no CALLS edge to format + fmt.format(); } } + diff --git a/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/util/Formatter.java b/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/util/Formatter.java new file mode 100644 index 000000000..6884acf16 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/java-variadic-resolution/com/example/util/Formatter.java @@ -0,0 +1,8 @@ +package com.example.util; + +public class Formatter { + /** Varargs with a required fixed prefix — 0-arg calls should be rejected. */ + public void format(int level, String... args) { + for (String a : args) System.out.println(level + ": " + a); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/app/Main.java b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/app/Main.java new file mode 100644 index 000000000..bb4d88597 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/app/Main.java @@ -0,0 +1,10 @@ +package com.example.app; + +import com.example.models.*; + +public class Main { + public void run() { + User user = new User(); + user.save(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/Order.java b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/Order.java new file mode 100644 index 000000000..2804c749e --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/Order.java @@ -0,0 +1,7 @@ +package com.example.models; + +public class Order { + public void submit() { + System.out.println("submitting order"); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/User.java b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/User.java new file mode 100644 index 000000000..910f44884 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/java-wildcard-import/com/example/models/User.java @@ -0,0 +1,7 @@ +package com.example.models; + +public class User { + public void save() { + System.out.println("saving user"); + } +} diff --git a/gitnexus/test/integration/resolvers/java.test.ts b/gitnexus/test/integration/resolvers/java.test.ts index d9bae90bf..8a813525b 100644 --- a/gitnexus/test/integration/resolvers/java.test.ts +++ b/gitnexus/test/integration/resolvers/java.test.ts @@ -1,11 +1,12 @@ /** * Java: class extends + implements multiple interfaces + ambiguous package disambiguation */ -import { describe, it, expect, beforeAll } from 'vitest'; +import { describe, expect, beforeAll } from 'vitest'; import path from 'path'; import { FIXTURES, CROSS_FILE_FIXTURES, + createResolverParityIt, getRelationships, getNodesByLabel, getNodesByLabelFull, @@ -14,6 +15,8 @@ import { type PipelineResult, } from './helpers.js'; +const it = createResolverParityIt('java'); + // --------------------------------------------------------------------------- // Heritage: class extends + implements multiple interfaces // --------------------------------------------------------------------------- @@ -438,6 +441,54 @@ describe('Java variadic call resolution', () => { } expect(allDangling).toEqual([]); }); + + it('resolves 2-arg call to fixed-prefix varargs method format(int, String...) in Formatter.java', () => { + const calls = getRelationships(result, 'CALLS'); + const fmtCall = calls.find((c) => c.target === 'format' && c.source === 'run'); + expect(fmtCall).toBeDefined(); + expect(fmtCall!.targetFilePath).toBe('com/example/util/Formatter.java'); + }); + + it('0-arg call to format(int, String...) still resolves in legacy mode (arity rejection is registry-only)', () => { + // In REGISTRY_PRIMARY_JAVA=1 mode, `requiredParameterCount = 1` causes + // `javaArityCompatibility` to return 'incompatible' for 0-arg calls, + // preventing the CALLS edge. In default (legacy) mode, arity is not + // enforced so the edge is created. This test documents the legacy + // behavior; the negative assertion is a flip-blocker for registry-primary. + const calls = getRelationships(result, 'CALLS'); + const zeroArgFmtCall = calls.find((c) => c.target === 'format' && c.source === 'badCall'); + expect(zeroArgFmtCall).toBeDefined(); + }); +}); + +// --------------------------------------------------------------------------- +// Wildcard import: `import com.example.models.*` resolves to a package file +// --------------------------------------------------------------------------- + +describe('Java wildcard import resolution', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'java-wildcard-import'), () => {}); + }, 60000); + + it('parses wildcard import without errors and creates graph nodes', () => { + // The wildcard import (`import com.example.models.*`) exercises the + // directoryChild branch in resolveJavaImportTarget. Even if no IMPORTS + // edge is created (nondeterministic file selection — documented flip + // blocker), the graph must contain valid nodes for all classes. + const classes = getNodesByLabel(result, 'Class'); + expect(classes).toContain('Main'); + expect(classes).toContain('User'); + expect(classes).toContain('Order'); + }); + + it('resolves user.save() call via wildcard-imported User', () => { + const calls = getRelationships(result, 'CALLS'); + const saveCall = calls.find((c) => c.target === 'save' && c.source === 'run'); + expect(saveCall).toBeDefined(); + expect(saveCall!.targetFilePath).toBe('com/example/models/User.java'); + }); }); // --------------------------------------------------------------------------- diff --git a/gitnexus/test/integration/worker-pool.test.ts b/gitnexus/test/integration/worker-pool.test.ts index 845c1cfba..7fba8ebf5 100644 --- a/gitnexus/test/integration/worker-pool.test.ts +++ b/gitnexus/test/integration/worker-pool.test.ts @@ -354,7 +354,7 @@ describe('worker pool integration', () => { try { await expect(pool.dispatch([{ path: 'crash.ts', content: '' }])).rejects.toThrow( - /simulated startup crash|exited with code/, + /simulated startup crash|exited with code|idle timeout/, ); const warnRecords = cap.records().filter((r) => Number(r.level) >= 40 /* warn or above */); expect(warnRecords.length).toBeGreaterThan(0); From 4fa40e9881531b5a5d4c11459b188f872b6cb843 Mon Sep 17 00:00:00 2001 From: Abhigyan Patwari <126312502+abhigyanpatwari@users.noreply.github.com> Date: Tue, 12 May 2026 13:14:56 +0100 Subject: [PATCH 03/33] feat(analyze): incremental indexing (parse cache + DB writeback + scope-res short-circuit) (#1479) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * docs: incremental indexing design spec Captures the design agreed in brainstorming on 2026-05-10: - Transitive importer closure with public-surface-change optimization - Git-only change detection (non-git repos: full rebuild as today) - New default behavior; --force opts out - New hydratePhase + loadGraphFromLbug primitive - Iterative closure expansion with parseCache reuse - incrementalInProgress dirty flag for crash recovery Prior art: PR #592 (zenprocess), PR #533 (davidbeesley), PR #1146 (azeemshaik025) — referenced and credited. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(communities): seed Leiden RNG for deterministic community detection The vendored Leiden algorithm defaults to Math.random for tie-breaking and randomized walks, which produces non-deterministic community assignments and modularity values across runs on the same graph. Pass a seeded mulberry32 RNG (LEIDEN_SEED=0xC0DE) so: - The same graph always produces the same partition - Modularity values are reproducible - Equivalence tests for incremental indexing can compare community assignments byte-for-byte This is foundational for the upcoming incremental-indexing feature (see docs/superpowers/specs/2026-05-10-incremental-indexing-design.md) where the correctness contract is incremental output ≡ full rebuild output. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(incremental): change-detection, surface signatures, closure expansion Three new modules supporting the incremental-indexing pipeline: * core/incremental/git-diff.ts — getChangedFilesSinceCommit() unions 'git diff lastCommit HEAD' (committed) with 'git status --porcelain' (dirty tree). Renames flattened to delete(orig) + add(new). Throws LastCommitMissingError when lastCommit is gone (caller falls back to full rebuild). * core/incremental/surface.ts — extractSurfaceSignature() produces a stable hash of a file's publicly-visible symbols (functions, classes, methods, interfaces, types, heritage). Body-only edits → same hash. Signature/heritage changes → different hash. Drives the closure scoping optimization. * core/incremental/closure.ts — computeImporterClosure() iterative fixpoint: parse each closure file, extract surface, query DB importers, expand. Uses a parseCache so each file is parsed once. Generic over TParseResult so closure logic is decoupled from the pipeline's parse representation. 32 unit tests across the three modules. Tests cover edge cases: clean tree, dirty-only, mixed, renames, deletes, multi-hop cascade, cycle termination, surface invariance, etc. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(lbug): loadGraphFromLbug, queryImporters, deleteAllCommunitiesAndProcesses Three new primitives in lbug-adapter.ts to support incremental indexing: * loadGraphFromLbug(graph, unchangedFilePaths) — streams all nodes for files in the set across every hydratable node table (excludes Community/Process — graph-wide, regenerated downstream). Then loads edges where both endpoints belong to loaded nodes, excluding MEMBER_OF / STEP_IN_PROCESS edges (also graph-wide). FilePaths chunked at 200 per query to keep statement size bounded on huge repos. Endpoint-level join filters by source-side filePath in the query, target-side checked JS-side via the loadedNodeIds set. * queryImporters(targetFilePath) — returns DISTINCT a.filePath where a -[IMPORTS]-> b and b.filePath = target. Powers closure expansion: when a changed file's surface signature changes, all its importers must be re-parsed. * deleteAllCommunitiesAndProcesses() — drops Community/Process nodes (and their edges via DETACH DELETE) at the start of each incremental run so the communities/processes phases regenerate them from the fully-merged graph. Required for the 'Leiden runs on full graph' correctness invariant. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(pipeline): hydrate phase + parse-filter for incremental indexing Wires the incremental-indexing infrastructure into the phase-based pipeline. Three coordinated changes: * New hydratePhase (deps: structure) — loads node/edge state for files OUTSIDE ctx.options.filesToParse from the existing LadybugDB index. Runs before parse so the parse phase can produce a partial graph while downstream phases (mro, communities, processes) still see the full graph. No-op in full-rebuild mode (filesToParse unset). * PipelineOptions.filesToParse: optional ReadonlySet. When set, parse phase filters scanned files to this set; hydrate fills the complement. Set by runFullAnalysis when it detects an eligible incremental run; never set by callers directly. * gitnexus-shared PipelinePhase enum: 'hydrate' added so progress callbacks can report the new phase distinctly from 'structure'. Phase order: scan → structure → hydrate → markdown,cobol → parse → routes,tools,orm → crossFile → scopeResolution → mro → communities → processes. Communities (Leiden) still runs on the full graph, satisfying the correctness invariant. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(analyze): incremental orchestrator branch + meta schema Wires incremental indexing into runFullAnalysis. Highlights: * RepoMeta schema extended: schemaVersion, surfaceSignatures, and incrementalInProgress fields. INCREMENTAL_SCHEMA_VERSION = 1. * core/incremental/file-hash.ts — v1 surface signature: SHA-256 of file content. v2 will switch to a true surface-only signature (defined in surface.ts) so body-only edits don't expand the closure. The plumbing is signature-agnostic so the swap is local. * core/incremental/orchestrator.ts — eligibility check, closure computation (uses file-hash as the surface signal), dirty-flag management, subgraph extraction, signature merge. * run-analyze.ts adds: - hasDirtyTree() check on the existing 'lastCommit==HEAD' early-exit so an uncommitted edit triggers re-index (was a coarse equality check before). - incremental branch: try incremental first; fall through to full rebuild on any setup failure or eligibility miss. - runIncrementalBranch() — opens existing DB, deletes closure-file rows + Community/Process, runs pipeline with filesToParse, writes only the changed-subgraph back, refreshes FTS, updates meta with new surfaceSignatures and clears the dirty flag. - Full-rebuild path now populates surfaceSignatures + schemaVersion in meta.json so the next run is eligible for incremental. Crash recovery: incrementalInProgress is set BEFORE any DB mutation and cleared on success by overwriting meta.json. A crash anywhere in between leaves the flag set, and the next analyze run forces a full rebuild (cheapest path back to a known-good index). v1 limitation documented: body-only edits trigger 1-hop closure expansion (content-hash signal). True surface-only optimization is deferred to v2 — see design doc for the integration path. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(incremental): drop invalid --no-renames=false from git diff The flag --no-renames=false isn't valid git syntax (it's parsed as a file path). Git's default rename detection is on; removing the flag keeps that behavior. Caught while running an end-to-end smoke test against a small fixture repo: incremental setup failed with 'Command failed: git diff --name-status -z --no-renames=false ...'. After the fix, the incremental path runs cleanly: closure is computed, hydrate phase loads unchanged-file state from DB, parse phase only re-parses files in closure, and the writeback updates only changed nodes/edges. Co-Authored-By: Claude Opus 4.7 (1M context) * Revert v1 incremental indexing (5 commits) Reverts the v1 design that parsed only closure files into a fresh graph and tried to hydrate the rest from DB. Real-repo equivalence test failed: cross-file resolution operates on partial parse data (closure files only), so CALLS edges that resolve through unchanged files silently fall off. Diff against full rebuild on the same edited state: -50 nodes, -425 edges, -5 communities, -48 processes. Architecture pivot: switch to PR #533-style content-addressed parse cache. Pipeline parses every file (cache-served when possible), giving cross-file resolution full data, with DB writeback then restricted to changed-file rows. Reverts: d4b9de47 fix(incremental): drop invalid --no-renames=false f35f7634 feat(analyze): incremental orchestrator branch + meta schema bc039686 feat(pipeline): hydrate phase + parse-filter 98bb893d feat(lbug): loadGraphFromLbug, queryImporters, ... aa8d7ae3 feat(incremental): change-detection, surface signatures, closure Kept: d9e340b0 feat(communities): seed Leiden RNG (foundational) 8235ca36 docs: incremental indexing design spec (will be revised) Co-Authored-By: Claude Opus 4.7 (1M context) * feat(analyze): incremental DB writeback (Option B) Equivalence-preserving incremental analyze. The pipeline still parses every file (correctness invariant: cross-file resolution / scope resolution / MRO / community detection all need full graph data); the saving comes from selectively replacing only changed-file rows in LadybugDB instead of wiping and reloading the whole graph. How it works: * On every analyze, we hash all source files (SHA-256 of content) and store the map in meta.json.fileHashes alongside schemaVersion. * The next run loads the prior map and diffs: - changed: content hash differs → file's DB rows replaced. - added: not in prior map → file's DB rows inserted. - deleted: in prior map but not on disk → file's DB rows dropped. * If the diff is non-empty AND no --force / no schema mismatch / no dirty flag, take the incremental path: - Set incrementalInProgress dirty flag (BEFORE any DB mutation). - Open existing DB (no wipe). - deleteNodesForFile() for each changed/added/deleted file. - deleteAllCommunitiesAndProcesses() — Leiden regenerates these. - extractChangedSubgraph() from the in-memory ctx.graph: nodes whose filePath is in the writable set + Community + Process + edges with at least one endpoint in the writable set (edges entirely between hydrated unchanged nodes are skipped — already in DB). - loadGraphToLbug() on the subgraph. Unchanged-file rows in DB untouched. - Recreate FTS indexes. - Update meta with new fileHashes; clear dirty flag. * Otherwise full-rebuild path runs as before. Crash recovery: incrementalInProgress is the dirty flag. Set before destructive ops; cleared on success. Set on next-run startup → forces full rebuild (cheapest path back to known-good). Other changes: * Dirty-tree gate on the existing 'lastCommit==HEAD' early-return: uncommitted edits no longer slip through as 'already up to date'. * deleteAllCommunitiesAndProcesses helper in lbug-adapter. * Skip the embedding cache+restore cycle when willTryIncremental is true — embeddings stay in DB; re-inserting them would PK-conflict. End-to-end equivalence verified on this repo (993 files, 24K nodes): incremental run produces byte-identical {nodes, edges, clusters, flows} to a full rebuild from the same edited state. Speedup is currently modest (~5% on this repo) because the parse phase still runs in full. Parse-cache integration is a separate follow-up that composes cleanly on top of this work. See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md. Co-Authored-By: Claude Opus 4.7 (1M context) * feat(analyze): chunk-level parse cache for full incremental speedup Composes with the incremental DB writeback (commit 27f3b49d) to deliver the major-speedup half of incremental indexing. Previously, the parse phase ran in full on every analyze; the speedup came purely from selective DB rewriting. With this commit the parse phase also reuses prior tree-sitter output for chunks whose contents haven't changed. How it works: * Cache layer (gitnexus/src/storage/parse-cache.ts): - File: /.gitnexus/parse-cache.json. Versioned, atomic write. - Key: chunk content hash = sha256(sorted(filePath:fileContentHash for each file in chunk)). - Value: ParseWorkerResult[] (raw worker output for the chunk, pre-merge). - Granularity: per chunk (~20MB byte-budget). A change to one file invalidates only its chunk — typically 1 of ~50 on a 1000-file repo (~98% cache hit ratio on a small edit). * Worker contract (gitnexus/src/core/ingestion/parsing-processor.ts): - Extracted the chunk-result merge loop into a public mergeChunkResults() so the same logic applies to live worker output AND replayed cache entries. - processParsingWithWorkers / processParsing accept an optional outRawResults out-parameter that captures worker output before merging — used by parse-impl to populate the cache after a miss. * Parse phase wiring (parse-impl.ts): - For each chunk, compute its content hash (after reading file contents). Cache hit → mergeChunkResults() on cached results, skip the worker dispatch entirely. Cache miss → run workers normally, capture raw results, store under the chunk hash. - Cache mutations happen in-place on the ParseCache passed via PipelineOptions.parseCache. * Lifecycle (run-analyze.ts): - loadParseCache() before pipeline runs. - Cache passed via runPipelineFromRepo's PipelineOptions. - saveParseCache() after the pipeline + DB writeback succeed. Equivalence verified on this repo (993 files, 24K nodes): Cold (no cache, full work): 141.1s Warm cache + 1-file edit, incremental: 63.6s ← 55% speedup Warm cache + 1-file edit, --force: 71.6s ← 49% speedup All three runs produce byte-identical {nodes, edges, clusters, flows}. The cache survives --force (content-addressed = always correct), so even forced rebuilds get the parse-skip benefit. Why chunk-level rather than per-file: workers process sub-batches and emit aggregated ParseWorkerResults. Per-file granularity would require restructuring the worker contract; chunk-level captures most of the practical speedup with no worker-side changes. Co-Authored-By: Claude Opus 4.7 (1M context) * perf(parse-impl): smaller default chunk budget (20MB→2MB) for cache granularity The parse cache is keyed at chunk granularity. With the previous 20MB budget, a typical mid-size repo (e.g. this worktree at 9MB total parseable source) fits in a single chunk — meaning ANY file change invalidates the whole chunk and re-parses every file. 2MB default produces ~5x more chunks on the same input, so a one-file edit invalidates ~1/N of cached chunks instead of the whole thing. Cold-run overhead from more chunks is <5% (one extra serialization pass per chunk). Override via GITNEXUS_CHUNK_BYTE_BUDGET env var for benchmarking. Measured on this repo (~9MB / 887 parseable files): Cold (no cache): 143s Warm cache, no source changes: 2s (early-return) Warm cache + 1-file edit: 81s (~43% off cold) Speedup is bounded by the scopeResolution phase (~58s flat regardless of parse cache) and by GitNexus's own auto-writes during analyze (AGENTS.md / .claude/skills/ etc. mutate between runs and invalidate chunks containing them). Both are addressable in follow-ups. Co-Authored-By: Claude Opus 4.7 (1M context) * perf(scope-resolution): reuse worker-produced ParsedFile + stabilize chunk order Two compounding optimizations that drop warm-cache analyze from ~134s to ~38s on a 1000-file repo (72% faster), and cold rebuild from ~143s to ~86s (40% faster) by short-circuiting work that was previously re-done. 1. SCOPE-RESOLUTION: REUSE WORKER PARSEDFILE Previously, the scope-resolution phase re-parsed every file with tree-sitter on the main thread (~58s on a 1000-file repo) because worker-produced tree-sitter Trees can't cross the worker MessageChannel. But the worker ALSO produces a artifact via , which structured-clones fine — and it's exactly what scope-resolution would re-derive. Threading those ParsedFiles through the parse phase () into ( map) lets scope- resolution skip its extract loop on a per-file basis. The fast path is bounded only by per file (cheap graph mutation). On this repo: scopeResolution went from 58s → 5s. 2. MAP-PRESERVING PARSE-CACHE SERIALIZATION is a which JSON.stringify collapses to . The first attempt at threading parsedFiles through the parse cache crashed at runtime with "importerModule.typeBindings is not iterable" because cached entries came back as plain objects. Added a JSON replacer/reviver pair in parse-cache.ts that round-trips Map and Set instances through tagged plain objects (). Symmetric: save uses replacer, load uses reviver. 3. STABLE CHUNK ORDERING The byte-budget chunker walked files in filesystem-scan order, which on Windows isn't guaranteed to be stable across runs. Even with identical source content, two scans could place files in different chunks, shifting chunk hashes and causing 100% parse-cache misses. Added a deterministic alphabetical sort on before chunking. Chunk membership is now stable across runs, so a single-file edit invalidates exactly one chunk, not all of them. Measured on this repo (993 files, 24K nodes): Cold rebuild: 86s (was 143s) Warm cache, no source changes: 3s (early-return) Warm cache + 1-file edit: 38s (was 134s) Co-Authored-By: Claude Opus 4.7 (1M context) * docs(incremental): update spec + AGENTS.md + GUARDRAILS.md for shipped design - Rewrite docs/superpowers/specs/2026-05-10-incremental-indexing-design.md to describe the architecture that actually shipped (parse cache + incremental DB writeback + scope-resolution short-circuit), with the v1 hydrate-phase post-mortem preserved as historical context. - AGENTS.md "Keeping the Index Fresh" section: note that incremental is the new default and --force is the explicit opt-out; mention the parse-cache file location and that it's safe to delete. - GUARDRAILS.md Signs: add an "Index seems corrupt or incremental is misbehaving" entry pointing users to --force as the manual escape hatch (the dirty flag handles automatic recovery). Co-Authored-By: Claude Opus 4.7 (1M context) * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(incremental): bugbot review + CI test failures Bugbot (PR #1479): - Medium: pruneCache was exported but never called -> cache grew unbounded. Wire pruneCache into run-analyze before saveParseCache, using a transient usedKeys Set on ParseCache that the parse phase populates as it processes chunks. - Low: willTryIncremental (pre-pipeline) and isIncremental (post-pipeline) could desync, silently dropping embeddings on mispredicted runs. Removed the prediction; the embedding cache now loads unconditionally when shouldLoadCache is true. The re-insert step gates on the actual isIncremental value to avoid PK-conflicts when the incremental-writeback path keeps DB rows. CI test failures: - cli-e2e #1169 + run-analyze.test.ts #1233: my dirty-tree gate on the lastCommit==HEAD early-return saw GitNexus's own auto-generated outputs (.claude/, .cursor/, AGENTS.md, CLAUDE.md) as dirty, perpetually defeating the up-to-date fast path. Extended the pathspec exclusion to cover all auto-gen outputs, not just .gitnexus/. - ruby field-type disambig: my chunk-stability sort exposed a pre-existing order-dependency in Ruby cross-file resolution (`user.address.save -> Address#save` only resolves correctly when user.rb parses before address.rb in some configurations). Removed the sort. Filesystem ordering is stable enough in practice that the parse cache still hits the common case; the pre-existing fragility is left for a separate fix. - pipeline-graph-golden: regenerated. Seeded Leiden RNG produces a partition different from the previous Math.random snapshot. - staleness `parallel calls` was a CI timing flake; passes locally. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(incremental): re-insert cached embeddings on incremental path Bugbot re-review caught: deleteNodesForFile cascades to the CodeEmbedding table (DELETE WHERE e.nodeId STARTS WITH ...), so changed-file embedding rows are wiped along with their nodes. The previous fix gated re-insert on `!isIncremental`, which silently dropped those embeddings — a regression versus the full-rebuild path's "preserve embeddings by default" guarantee. Remove the `!isIncremental` gate. The per-batch try/catch already handles the unchanged-file PK-conflict case ("some may fail if node was removed, that's fine") with the same semantics, so re-inserting the full cached set on incremental works: - changed-file rows: deleted, then re-inserted from cache (preserved) - unchanged-file rows: still in DB, re-insert PK-conflicts and is silently ignored (existing rows are correct) Cost: re-inserting ~24K embeddings on incremental when only a few files changed — most are no-op conflicts. Bounded by batch size of 200; ~3-5s overhead. Worth it for correctness. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(incremental): address Claude+Bugbot review findings + remove design doc Addresses CHANGES_REQUESTED review on PR #1479: 1. Remove docs/superpowers/specs/2026-05-10-incremental-indexing-design.md per maintainer request. 2. BLOCKER (Claude Finding 1, Bugbot Round 3): Stale cross-file edges between unchanged files. extractChangedSubgraph excluded edges where both endpoints were unchanged-file nodes — when a barrel/re-export file changes, cross-file resolution may update CALLS edges between two unchanged files that would then be silently lost. Fix: 1-hop importer-closure expansion of the writable set in run-analyze.ts. Before deleting/rewriting rows, query DB for importers of every changed/deleted file and add them to the writable set. Their nodes get deleted+rewritten too, so cross-file's refined edges land in the DB. Re-added queryImporters to lbug-adapter.ts. 3. BLOCKER (Claude Finding 3): Parse cache key omitted parser version. After a GitNexus upgrade, the cache silently replays pre-upgrade ParseWorkerResults against the new schema → wrong CALLS/IMPORTS/ scope edges with no visible signal. Fix: PARSE_CACHE_VERSION now embeds the gitnexus npm package version (read at module load via createRequire on package.json). Format: `${SCHEMA_BUMP}+${PKG_VERSION}` e.g. "1+1.6.4". Any release that bumps package.json automatically invalidates the on-disk cache. Mismatched versions fall through to an empty cache (next save overwrites with the new version baked in). 4. BLOCKER (Claude Finding 2): No automated tests for incremental behavior. Added 28 unit tests across 3 files: - incremental-file-hash.test.ts (10 tests) diffFileHashes classification, computeFileHash determinism, computeFileHashes batch / missing-file tolerance, sorted output. - incremental-parse-cache.test.ts (12 tests) computeChunkHash stability and order-independence, version prefix format, pruneCache, load/save round-trip on empty / missing / corrupt / version-mismatched files, AND a Map/Set round-trip test that pins the JSON replacer/reviver behaviour (without it, ParsedFile.scopes[*].typeBindings collapses to {} and downstream `.get()` / iteration throws). - incremental-subgraph-extract.test.ts (6 tests) writable-set node inclusion, Community/Process always kept, edge inclusion when at least one endpoint is writable, MEMBER_OF edges via graph-wide endpoints, empty subgraph case. 5. Medium (Claude Finding 6): AGENTS.md "Keeping the Index Fresh" said "only changed files are re-parsed." Imprecise — the pipeline parses every file every run; the cache skips tree-sitter for chunks whose contents haven't changed. Reworded to match the design doc. Test plan still expects: [x] Typecheck clean [x] All 28 new unit tests pass [x] All previously-failing tests still pass on the rebased branch [x] Equivalence verified locally (incremental ≡ --force, byte-identical stats on this repo) Co-Authored-By: Claude Opus 4.7 (1M context) * fix(incremental): round 3 review feedback — bounded BFS, atomic meta, integration test, docs Addresses remaining findings on PR #1479 from Claude's re-review of commit ad7bd31 + verifies the outstanding Bugbot HIGH severity. 1. F1 — Transitive importer expansion (Claude, was Medium-but-noted). Previous 1-hop importer expansion missed barrel re-export chains (A imports C, C re-exports B; when B changes, only C was pulled in — A was left with potentially-stale CALLS edges to refined targets). Replaced the single pass with a bounded BFS over the IMPORTS graph (depth ≤ 4). Catches nested barrel pyramids without ballooning into a near-full rebuild on monorepos with deep re-export trees. `--force` remains the escape hatch documented in GUARDRAILS.md for cases that exceed the bound. 2. F2 — Integration test for incremental orchestration (Claude, BLOCKER, DoD §2.7). The unit tests added in ad7bd31 covered `diffFileHashes`, `extractChangedSubgraph`, `computeChunkHash`, `pruneCache`, and the Map/Set JSON round-trip — but none of them exercised the real `runFullAnalysis` orchestration. Added gitnexus/test/unit/ incremental-orchestration.test.ts with four end-to-end tests against a real git-initialized fixture repo + real LadybugDB: a. First run populates fileHashes + schemaVersion and clears incrementalInProgress on success. b. Second run on unchanged state takes the alreadyUpToDate fast path (early-return). c. Second run after a source edit takes the incremental path (not full rebuild) and rotates fileHashes for the touched file while keeping the dirty flag cleared. d. A pre-set incrementalInProgress flag forces a full rebuild that clears it (crash-recovery wire). These would catch any regression that wires `isIncremental` from a pre-pipeline prediction (the Bugbot finding from commit 5eb0597) or accidentally re-gates the embedding re-insert on `!isIncremental` (the Bugbot finding from commit 60c10f1). 3. F3 — GUARDRAILS.md docs accuracy (Claude, Low). Line 33 still said "only changed files are re-parsed" — AGENTS.md was already corrected in ad7bd31 but GUARDRAILS.md was missed. Reworded to match. 4. F5 — Atomic saveMeta (Claude, Medium; vvladescu-tb fork). The dirty flag (`incrementalInProgress`) travels through meta.json. A crash mid-write would leave a corrupt meta.json that `loadMeta` would silently treat as "no prior index", losing the flag and skipping recovery. Switched to tmp-file + rename matching saveParseCache. 5. Bugbot's "Subgraph edges reference nodes absent from subgraph" (HIGH severity). Verified as FALSE POSITIVE: `getNodeLabel` in lbug-adapter.ts derives labels from the node-ID string (parses the table prefix), not from the in-memory graph. The CSV generator writes (src_id, dst_id, type) rows without consulting node objects; `splitRelCsvByLabelPair` routes by ID-derived label; `COPY ... (from=X, to=Y)` resolves both endpoints against the live LadybugDB where unchanged-file nodes still exist. No fix needed. All 213 tests pass locally (including the 4 new integration tests and the previously-failing CI tests). Co-Authored-By: Claude Opus 4.7 (1M context) * fix(incremental): address Bugbot round-4 findings (added-file shadow seed + dedupe) Bugbot review on commit e23e4400 surfaced two new findings against the incremental writeback in run-analyze.ts: HIGH — Incremental BFS misses importers of newly added files. queryImporters() reads the pre-pipeline DB. For a NEWLY ADDED file there are no IMPORTS rows pointing to it yet, so unchanged files whose pre-existing import statements now resolve to the newcomer keep stale CALLS edges pointing at the OLD resolution target. LOW — Deleted files double-counted in filesToDelete. hashDiff.deleted entries can reappear in writableFiles via the BFS expansion (queryImporters can return a now-deleted path), so deleteNodesForFile() ran twice for the same file. Fixes: - Add gitnexus/src/core/incremental/shadow-candidates.ts: derive the pre-existing file paths whose JS/TS module-resolution claim an added file can steal. Pattern catalogue: same-basename/ different-extension, bare-file-beats-directory-index, and directory-index-beats-bare-file. Emit both POSIX and Windows separators because the prior fileHashes map may have been written from either OS. - In run-analyze.ts, seed the BFS frontier with shadow candidates that exist in the prior meta.fileHashes. Their importers — found via queryImporters — get pulled into the writable set so their CALLS edges re-resolve against the new file. - Dedupe filesToDelete via Set to avoid the double-call. Tests: gitnexus/test/unit/incremental-shadow-candidates.test.ts — 8 cases covering each shadow pattern, separator handling, .d.ts as a single extension token, deduplication, and the no-self-shadow invariant. All 40 incremental tests (file-hash, parse-cache, subgraph-extract, shadow-candidates, orchestration) pass locally. Note on the third Bugbot finding ("Subgraph edges reference nodes absent from subgraph"): re-anchored from a prior review pass — the code at subgraph-extract.ts:48 is unchanged. Already verified as a false positive: getNodeLabel parses labels from ID strings, CSV write is by ID, and COPY resolves against the live DB. * chore(autofix): apply prettier + eslint fixes via /autofix command * test(incremental): exact-equality stats invariant + analyze ≡ analyze --force Addresses the only remaining Claude production-readiness review finding on PR #1479 (Low-Medium, test-quality only — Claude itself said it does NOT block merge, but the central PR claim "incremental ≡ full rebuild" deserves explicit CI coverage rather than implicit trust). Changes to gitnexus/test/unit/incremental-orchestration.test.ts: 1) Tighten the existing "comment-only edit takes incremental path" test. - Replace toBeGreaterThan(0) bounds assertions on stats.files and stats.nodes with exact toBe(firstMeta) per-field equality across files / nodes / edges / communities / processes. DoD §2.7 calls out bounds-only assertions as masking regressions that drop half the graph; this swap closes that gap. - Rationale: a comment-only edit must change the file content hash (driving the incremental path) without changing any graph data. Therefore every stat MUST be identical to the first run. Anything else is a regression. 2) New test: incremental output is byte-equivalent to a full rebuild. - Run analyze → comment-only edit → analyze (incremental writeback) → analyze --force (full rebuild from same on-disk state). - Assert files / nodes / edges / communities / processes are exactly equal across the incremental and the --force passes. - This is the PR's central correctness contract, now proven by a test that exercises the real runtime path end-to-end against a real on-disk LadybugDB. All 5 orchestration tests pass locally (52s), including the new equivalence test — every stat field matches exactly between incremental and --force on the mini-repo fixture. tsc --noEmit clean. * fix(incremental): F1 cross-file edge consistency + F4 stable chunk sort + unit coverage (#1511) Patch addressing two of the still-open changes-requested findings on PR #1479, rebased onto the current feat/incremental-indexing head. F3 (parser fingerprint in the cache key), F5 (atomic saveMeta), and F6 (AGENTS.md phrasing) were already handled on the branch, so the corresponding parts of the original patch were dropped as redundant. F1 (Blocker) — Cross-file edges between unchanged files Adds `computeEffectiveWriteSet(graph, toWriteSet)` to subgraph-extract.ts: a single pass over the new graph's edges that pulls the unchanged-side file of every writable-boundary-crossing edge into the write set. run-analyze composes it ON TOP of the existing importer-BFS expansion and feeds the combined set to BOTH `deleteNodesForFile` and `extractChangedSubgraph`, so the delete cascade and the writeback subgraph cover identical files (asymmetry would leave stale rows or PK-conflict at COPY time). The BFS reads IMPORTS from the pre-pipeline DB (catches files that *stopped* importing a changed file); the edge walk reads the new graph (catches refined CALLS edges the pre-run DB couldn't predict, e.g. a barrel re-export shifting a symbol from B to D). `extractChangedSubgraph` stays a pure filter — all expansion is the orchestrator's job. F4 (Medium) — Restore alphabetical chunk sort `parseableScanned` is sorted before chunking. Filesystem-scan order isn't stable enough across runs/platforms (notably macOS APFS) to keep chunk hashes consistent, so the parse cache thrashes without it. The pre-existing Ruby cross-file resolution order-dependency the old comment cited is independent — the sort surfaces it but doesn't cause it; tracked separately rather than leaving the cache cold. Tests — incremental-subgraph-extract.test.ts Locks the F1 invariants: `extractChangedSubgraph` is a pure filter (includes only the set it's given, plus graph-wide nodes; edges fire on one writable endpoint), and `computeEffectiveWriteSet` covers the barrel-re-export scenario, the symmetric edge-into- changed-file case, the no-boundary-crossed no-op, graph-wide-node edges, and input-immutability. Supersedes the prior extractChangedSubgraph-only test file on the branch. Co-authored-by: Val Vladescu * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(call-processor): register properties in pre-pass to fix order-dependent field type disambiguation + regenerate golden snapshot Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/2d66666f-861c-432e-a4b0-11f2aefca98a Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix(call-processor): port worker-path property enrichment into the sequential pre-pass Copilot's pre-pass in 8184439 fixed the Ruby attr_accessor order-dependence, but it copied the OLD in-loop registration logic, not the canonical worker path in parse-worker.ts. That left the sequential and worker paths emitting non-identical Property nodes/symbols for the same source — silently breaking the `incremental ≡ --force` invariant the moment a repo crosses the worker threshold between runs. Two concrete divergences are closed here: * Node id: worker keys Property as `${file}:${className}.${propName}` (qualified). Pre-pass was using `${file}:${propName}` (unqualified). Same source produced different graph ids depending on which path ran. * Field metadata: worker enriches each routed property with `provider.fieldExtractor` + `getFieldInfo`, falling back to `routedFieldInfo.type` for `declaredType` when the routing payload lacks one (e.g. types discovered from `@address = Address.new` ctor assignments rather than YARD `@return [Type]`), and propagates `visibility` / `isStatic` / `isReadonly`. Pre-pass did none of this, so on the sequential path `resolveFieldAccessType` failed to walk chains where the type only came from the FieldExtractor. The pre-pass now mirrors parse-worker.ts:1803-1898 verbatim, with one deliberate difference: the FieldInfo cache is scoped to a single `processCalls` invocation rather than module-level (the worker process is short-lived; the main thread is not, and a module-level cache would leak state between analyze runs). Also drops the now-stale "Defer resolution: Ruby attr_accessor properties are registered during this same loop" comment on `pendingWrites.push` — the rationale is no longer accurate after Copilot's pre-pass, but the deferral is still needed so write-access tracking sees inference that completes during the main loop. Comment updated to reflect that. Verification: * `tsc --noEmit`: 0 errors * test/unit (call-processor, call-routing, field-extraction, ruby-self-call): 224 passing * test/integration (ruby, ruby-sequential-mixin, pipeline-graph-golden): 137 passing Co-Authored-By: Claude Opus 4.7 (1M context) * fix(call-processor): key fieldInfoCache by filePath:startIndex, not raw byte offset Claude's review of 255bdf6 caught a real collision in the FieldInfoCache I added: keying by `classNode.startIndex` alone is a per-file byte offset, so two files that both begin with a class at byte 0 — extremely common in Ruby / Python, where files frequently open with `class Foo`, `module Foo` — collide on the same cache entry. The second file's `getFieldInfo` then returns the first file's FieldInfo map, producing wrong `declaredType` / `visibility` / `isReadonly` on its properties. Same shape as the bug that already exists in parse-worker.ts:377 (also keyed by `classNode.startIndex` in a module-level map, persistent across files processed by the same worker). Fixing the symmetric pre-existing leak in parse-worker.ts is a separate, scoped follow-up — left out of this commit to keep the fix minimal and reviewable. Cache map and key are now both string-typed. Composite key `${context.filePath}:${classNode.startIndex}` keeps the within-file hit rate (one FieldExtractor.extract() per class regardless of how many `attr_accessor` lines it has) while eliminating cross-file aliasing. Verification on the patched HEAD: * `tsc --noEmit`: 0 errors * test/unit (call-processor, call-routing, field-extraction, ruby-self-call): 224 passing * test/integration (ruby, ruby-sequential-mixin, pipeline-graph-golden): 137 passing Co-Authored-By: Claude Opus 4.7 (1M context) --------- Co-authored-by: Claude Opus 4.7 (1M context) Co-authored-by: Gergő Magyar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Val Vladescu Co-authored-by: Val Vladescu Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --- AGENTS.md | 7 +- GUARDRAILS.md | 8 +- .../src/core/incremental/shadow-candidates.ts | 76 ++++ .../src/core/incremental/subgraph-extract.ts | 123 ++++++ gitnexus/src/core/ingestion/call-processor.ts | 224 ++++++++-- .../src/core/ingestion/community-processor.ts | 19 + .../src/core/ingestion/parsing-processor.ts | 177 ++++---- .../ingestion/pipeline-phases/parse-impl.ts | 175 ++++++-- .../core/ingestion/pipeline-phases/parse.ts | 14 + gitnexus/src/core/ingestion/pipeline.ts | 13 + .../scope-resolution/pipeline/phase.ts | 15 +- .../scope-resolution/pipeline/run.ts | 51 ++- gitnexus/src/core/lbug/lbug-adapter.ts | 71 ++++ gitnexus/src/core/run-analyze.ts | 383 ++++++++++++++++-- gitnexus/src/storage/file-hash.ts | 104 +++++ gitnexus/src/storage/parse-cache.ts | 213 ++++++++++ gitnexus/src/storage/repo-manager.ts | 47 ++- .../mini-repo/expected-graph.json | 2 +- .../test/unit/incremental-file-hash.test.ts | 124 ++++++ .../unit/incremental-orchestration.test.ts | 263 ++++++++++++ .../test/unit/incremental-parse-cache.test.ts | 243 +++++++++++ .../incremental-shadow-candidates.test.ts | 75 ++++ .../unit/incremental-subgraph-extract.test.ts | 169 ++++++++ 23 files changed, 2409 insertions(+), 187 deletions(-) create mode 100644 gitnexus/src/core/incremental/shadow-candidates.ts create mode 100644 gitnexus/src/core/incremental/subgraph-extract.ts create mode 100644 gitnexus/src/storage/file-hash.ts create mode 100644 gitnexus/src/storage/parse-cache.ts create mode 100644 gitnexus/test/unit/incremental-file-hash.test.ts create mode 100644 gitnexus/test/unit/incremental-orchestration.test.ts create mode 100644 gitnexus/test/unit/incremental-parse-cache.test.ts create mode 100644 gitnexus/test/unit/incremental-shadow-candidates.test.ts create mode 100644 gitnexus/test/unit/incremental-subgraph-extract.test.ts diff --git a/AGENTS.md b/AGENTS.md index 60317d73d..1346facc9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -149,11 +149,16 @@ Indexed as **GitNexus** (4325 symbols, 10556 relationships, 300 execution flows) ## Keeping the Index Fresh ```bash -npx gitnexus analyze # basic refresh; preserves any existing embeddings +npx gitnexus analyze # incremental by default; preserves embeddings +npx gitnexus analyze --force # full rebuild from scratch (opt out of incremental) npx gitnexus analyze --embeddings # also generate embeddings for new/changed nodes npx gitnexus analyze --drop-embeddings # explicit opt-in to wipe existing embeddings ``` +`analyze` runs **incrementally by default**. The pipeline still parses every file every run (cross-file resolution requires it), but tree-sitter parsing is **served from a content-addressed cache** at `.gitnexus/parse-cache.json` for chunks whose file contents haven't changed since the last run. Only changed-file rows (and their importers) are rewritten in LadybugDB; unchanged-file rows are preserved. Output is byte-equivalent to a full rebuild. Pass `--force` to wipe and re-index from scratch (e.g., to recover from a corrupt index, or after upgrading GitNexus). + +The parse cache key is **content-addressed and version-tagged**: it survives `--force` runs, and is automatically invalidated by a `gitnexus` package upgrade (so a new tree-sitter grammar doesn't silently replay stale parse output). Safe to delete `.gitnexus/parse-cache.json` at any time — it'll be rebuilt on the next analyze. + Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no longer drops existing vectors — pass `--drop-embeddings` to wipe. > Claude Code: PostToolUse hook detects a stale index after `git commit` and `git merge` and prompts the agent to run `analyze`. The hook does not invoke `analyze` itself. diff --git a/GUARDRAILS.md b/GUARDRAILS.md index 1cc032759..c09f0319a 100644 --- a/GUARDRAILS.md +++ b/GUARDRAILS.md @@ -30,9 +30,15 @@ Format: **Trigger → Instruction → Reason**. Append new Signs when the same m ### Stale graph after edits - **Trigger:** MCP warns index is behind `HEAD`, or search doesn't match latest commit. -- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used). +- **Do:** `npx gitnexus analyze` (plus `--embeddings` if used). Runs incrementally by default — the pipeline parses every file every run (cross-file resolution requires it), but tree-sitter dispatch is skipped for unchanged file chunks via the content-addressed cache, and only changed-file rows (plus their importers, transitively) are rewritten in LadybugDB. - **Why:** Tools query LadybugDB from last analyze; git changes are invisible until re-indexed. +### Index seems corrupt or "incremental" is misbehaving + +- **Trigger:** `analyze` produces unexpected results, or `meta.json.incrementalInProgress` is set, or the index is in a half-state after a crash. +- **Do:** `npx gitnexus analyze --force` to rebuild from scratch. The dirty-flag check forces this automatically when a previous incremental run didn't complete cleanly, but `--force` is the manual escape hatch. Safe to delete `.gitnexus/parse-cache.json` at any time — content-addressed, will be regenerated. +- **Why:** Incremental writeback is selective DB row replacement; if the on-disk state is inconsistent for any reason, a full rebuild is the cheapest path back to a known-good index. + ### Embeddings vanished after analyze - **Trigger:** Semantic search quality drops; `stats.embeddings` in `meta.json` is 0 after refresh. diff --git a/gitnexus/src/core/incremental/shadow-candidates.ts b/gitnexus/src/core/incremental/shadow-candidates.ts new file mode 100644 index 000000000..415a6d9df --- /dev/null +++ b/gitnexus/src/core/incremental/shadow-candidates.ts @@ -0,0 +1,76 @@ +/** + * Shadow-candidate path derivation for incremental indexing. + * + * Background — Bugbot review on PR #1479: + * queryImporters() on a NEWLY ADDED file returns 0 importers in the + * pre-pipeline DB, because the new file's IMPORTS rows haven't been + * written yet. But pre-existing files may have IMPORTS edges that + * *resolved to a sibling path*, and the newcomer can now steal that + * resolution under standard JS/TS module-resolution rules. Without + * pulling those pre-existing files into the writable set, their + * stale CALLS edges remain pointing at the OLD resolution target. + * + * Given an added file path, this helper enumerates the pre-existing + * file paths whose import-resolution claim the newcomer can steal. + * Caller filters the candidates against the prior-run `fileHashes` + * map so we only query importers of paths that actually existed. + * + * Shadow patterns covered (resolution-priority-aware): + * + * (a) Same basename, different extension — + * added `foo/bar.ts` shadows `foo/bar.{tsx,js,jsx,mjs,cjs,d.ts}`. + * (b) Bare-file beats directory-style index — + * added `foo/bar.ts` shadows `foo/bar/index.{ts,tsx,...}`. + * (c) Directory-index beats bare-file — + * added `foo/index.ts` shadows `foo.{ts,tsx,...}` (rare but real, + * e.g. converting a single-file module into a directory module). + * + * Resolution-order priority is conservatively wide: we enumerate ALL + * common extensions because we don't know which the importer actually + * specified, and over-seeding is harmless (extra BFS work, but the + * subgraph extract still gates write-back by file membership). + * + * Cross-platform path separators: candidates are emitted with both `/` + * and `\` for shadow pattern (b), since the caller's prior fileHashes + * map may use either depending on the OS that wrote it. + */ + +const SHADOW_EXTS = ['.d.ts', '.tsx', '.ts', '.jsx', '.js', '.mjs', '.cjs']; + +/** + * Enumerate pre-existing paths whose import-resolution `added` can steal. + * + * @param added — repo-relative path of a newly-added file + * @returns deduplicated list of candidate paths (NOT filtered against + * any known-files set — caller does that) + */ +export const shadowCandidatesFor = (added: string): string[] => { + const ext = SHADOW_EXTS.find((e) => added.endsWith(e)); + if (!ext) return []; + + const noExt = added.slice(0, -ext.length); + const out = new Set(); + + // (a) Same basename, different extension. + for (const alt of SHADOW_EXTS) { + if (alt !== ext) out.add(noExt + alt); + } + + // (b) Bare file beats sibling directory-style index. + for (const idx of SHADOW_EXTS) { + out.add(`${noExt}/index${idx}`); + out.add(`${noExt}\\index${idx}`); + } + + // (c) New `foo/index.ext` shadows old `foo.ext`. + const idxSuffixSlash = '/index'; + const idxSuffixBack = '\\index'; + let dir: string | null = null; + if (noExt.endsWith(idxSuffixSlash)) dir = noExt.slice(0, -idxSuffixSlash.length); + else if (noExt.endsWith(idxSuffixBack)) dir = noExt.slice(0, -idxSuffixBack.length); + if (dir !== null) { + for (const alt of SHADOW_EXTS) out.add(dir + alt); + } + + return [...out]; +}; diff --git a/gitnexus/src/core/incremental/subgraph-extract.ts b/gitnexus/src/core/incremental/subgraph-extract.ts new file mode 100644 index 000000000..71fe656be --- /dev/null +++ b/gitnexus/src/core/incremental/subgraph-extract.ts @@ -0,0 +1,123 @@ +/** + * Subgraph extraction for incremental DB writeback. + * + * Given the FULL ctx.graph produced by the pipeline (all files parsed, + * all phases run) and the set of file paths whose DB rows must be + * replaced, produce a smaller KnowledgeGraph that contains: + * + * - Every node whose `properties.filePath` is in `toWriteSet`. + * - Every graph-wide node (Community, Process) — these are regenerated + * each run by the communities/processes phases and must be fully + * rewritten. + * - Every relationship where AT LEAST ONE endpoint is in the writable + * set above. Relationships entirely between unchanged-file nodes + * are skipped — their rows are still in the DB and re-inserting + * them would PK-conflict at COPY time. + * + * The resulting subgraph is what gets passed to `loadGraphToLbug` after + * the orchestrator has deleted the corresponding DB rows. Hydrated + * unchanged-file rows are never touched in the DB. + * + * # Cross-file edge consistency (Finding 1) + * + * `extractChangedSubgraph` intentionally does NOT expand the set it is + * given — expansion is the orchestrator's job, so the SAME expanded set + * can be fed to both `deleteNodesForFile` and this function (asymmetry + * between the delete set and the write set silently corrupts the DB). + * `computeEffectiveWriteSet` below performs the boundary-crossing 1-hop + * walk; the orchestrator composes it with its importer-BFS expansion and + * passes the result here. + * + * Why the 1-hop walk is needed: consider a barrel re-export change — + * file C (a barrel) shifts `export { foo } from './b'` to + * `export { foo } from './d'`. After scope resolution, file A's CALLS + * edge to `foo` resolves to D instead of B, even though A's content is + * byte-for-byte identical: + * + * - Old A→B edge survives in DB (neither A nor B is changed → not deleted) + * - New A→D edge is missing (neither A nor D in writable set → skipped) + * + * Pulling the unchanged-side file of every writable-boundary-crossing + * edge into the write set fixes both halves: the orchestrator's + * `DETACH DELETE` cleans up the stale unchanged-side rows, and the new + * cross-file edges land because at least one endpoint is now writable. + * + * Limitation (documented): if a file X *stopped* importing from a + * changed file C, X has no edge to C in the new graph, so this 1-hop + * walk doesn't catch it. The orchestrator's importer-BFS (which reads + * IMPORTS from the pre-pipeline DB) covers that case instead. + */ + +import type { GraphNode, GraphRelationship } from 'gitnexus-shared'; +import { createKnowledgeGraph } from '../graph/graph.js'; +import type { KnowledgeGraph } from '../graph/types.js'; + +const isGraphWide = (label: string): boolean => label === 'Community' || label === 'Process'; + +/** + * Build a Map for every File-bound node in the graph. + * Graph-wide nodes (Community/Process) have no filePath and are filtered. + */ +const indexNodeFilePaths = (fullGraph: KnowledgeGraph): Map => { + const idx = new Map(); + fullGraph.forEachNode((n: GraphNode) => { + const fp = n.properties?.filePath as string | undefined; + if (fp) idx.set(n.id, fp); + }); + return idx; +}; + +export const extractChangedSubgraph = ( + fullGraph: KnowledgeGraph, + toWriteSet: ReadonlySet, +): KnowledgeGraph => { + const sub = createKnowledgeGraph(); + const writableNodeIds = new Set(); + + fullGraph.forEachNode((n: GraphNode) => { + const filePath = n.properties?.filePath as string | undefined; + const include = (filePath && toWriteSet.has(filePath)) || isGraphWide(n.label); + if (include) { + sub.addNode(n); + writableNodeIds.add(n.id); + } + }); + + fullGraph.forEachRelationship((r: GraphRelationship) => { + if (writableNodeIds.has(r.sourceId) || writableNodeIds.has(r.targetId)) { + sub.addRelationship(r); + } + }); + + return sub; +}; + +/** + * Public — derive the EFFECTIVE write-set: `toWriteSet` expanded by one + * hop along every edge in the new graph that crosses the writable + * boundary (one endpoint in a writable file, the other in an unchanged + * file). The unchanged-side file is pulled in so its stale rows are + * deleted + rewritten in lockstep with the changed side. + * + * Single pass over the edge list. Does NOT mutate `toWriteSet`. The + * orchestrator MUST feed the returned set to both `deleteNodesForFile` + * and `extractChangedSubgraph` — feeding the unexpanded set to either + * one leaves stale rows or PK-conflicts at COPY time. + */ +export const computeEffectiveWriteSet = ( + fullGraph: KnowledgeGraph, + toWriteSet: ReadonlySet, +): Set => { + const nodeFilePaths = indexNodeFilePaths(fullGraph); + const expanded = new Set(toWriteSet); + fullGraph.forEachRelationship((r: GraphRelationship) => { + const sourcePath = nodeFilePaths.get(r.sourceId); + const targetPath = nodeFilePaths.get(r.targetId); + if (!sourcePath || !targetPath) return; // skip edges to graph-wide nodes + const sourceWritable = toWriteSet.has(sourcePath); + const targetWritable = toWriteSet.has(targetPath); + if (sourceWritable && !targetWritable) expanded.add(targetPath); + else if (targetWritable && !sourceWritable) expanded.add(sourcePath); + }); + return expanded; +}; diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts index 9fa6c1ae5..b45478f7a 100644 --- a/gitnexus/src/core/ingestion/call-processor.ts +++ b/gitnexus/src/core/ingestion/call-processor.ts @@ -42,12 +42,14 @@ import { isVerboseIngestionEnabled } from './utils/verbose.js'; import { yieldToEventLoop } from './utils/event-loop.js'; import { parseSourceSafe } from '../tree-sitter/safe-parse.js'; import { + CLASS_CONTAINER_TYPES, FUNCTION_NODE_TYPES, - findEnclosingClassId, findEnclosingClassInfo, genericFuncName, inferFunctionLabel, } from './utils/ast-helpers.js'; +import type { FieldInfo, FieldExtractorContext } from './field-types.js'; +import type { LanguageProvider } from './language-provider.js'; import { typeTagForId, constTagForId, buildCollisionGroups } from './utils/method-props.js'; import type { MethodInfo } from './method-types.js'; import { @@ -77,6 +79,62 @@ import type { LiteralTypeInferrer } from './type-extractors/types.js'; import type { SyntaxNode } from './utils/ast-helpers.js'; import { logger } from '../logger.js'; + +// ── Property-prepass helpers (parity with parse-worker.ts) ── +// These mirror the sequential-path equivalents in parse-worker.ts so the main- +// thread `processCalls` pre-pass produces byte-identical Property nodes/symbols +// to the worker pool. Drift between the two paths breaks the +// `incremental ≡ --force` invariant the moment a repo crosses the worker +// threshold between runs. + +/** Walk up to the nearest enclosing class/struct/interface AST node. */ +const findEnclosingClassNode = (node: SyntaxNode): SyntaxNode | null => { + let current = node.parent; + while (current) { + if (CLASS_CONTAINER_TYPES.has(current.type)) return current; + current = current.parent; + } + return null; +}; + +/** No-op SymbolTable stub for FieldExtractorContext — matches parse-worker. */ +const NOOP_SYMBOL_TABLE: SymbolTableReader = { + lookupExact: () => undefined, + lookupExactFull: () => undefined, + lookupExactAll: () => [], + lookupCallableByName: () => [], + getFiles: () => [][Symbol.iterator](), + getStats: () => ({ fileCount: 0 }), +}; + +/** + * Extract (and cache) field info for a class node. Cache is passed in so it + * stays scoped to a single `processCalls` invocation rather than leaking + * across analyze runs (worker uses module-level caching because each worker + * process is short-lived; the main thread is not). + * + * Cache key is `${filePath}:${classNode.startIndex}` — startIndex alone is a + * per-file byte offset, so almost every Ruby/Python file's leading class lands + * at byte 0 and would collide across files in the shared map. + */ +const getFieldInfo = ( + classNode: SyntaxNode, + provider: LanguageProvider, + context: FieldExtractorContext, + cache: Map>, +): Map | undefined => { + if (!provider.fieldExtractor) return undefined; + const cacheKey = `${context.filePath}:${classNode.startIndex}`; + const cached = cache.get(cacheKey); + if (cached) return cached; + const result = provider.fieldExtractor.extract(classNode, context); + if (!result?.fields?.length) return undefined; + const map = new Map(); + for (const field of result.fields) map.set(field.name, field); + cache.set(cacheKey, map); + return map; +}; + /** Per-file resolved type bindings for exported symbols. * Populated during call processing, consumed by Phase 14 re-resolution pass. */ export type ExportedTypeMap = Map>; @@ -860,6 +918,120 @@ export const processCalls = async ( prepared.push({ file, language, provider, tree, matches, parentMap, typeEnv }); } + // ── Property-registration pre-pass ── + // Register all routed properties (e.g. Ruby attr_accessor) BEFORE the + // resolution loop so cross-file field-type lookups (e.g. + // `user.address.save → Address#save`) succeed regardless of file + // processing order. This MUST stay in lockstep with the equivalent + // worker-path block in parse-worker.ts (kind === 'properties') — any + // divergence between the two paths breaks the `incremental ≡ --force` + // invariant once a repo crosses the worker threshold between runs. + const fieldInfoCache = new Map>(); + for (const { file, language, provider, matches, typeEnv } of prepared) { + const callRouter = provider.callRouter; + if (!callRouter) continue; + matches.forEach((match) => { + const captureMap: Record = {}; + match.captures.forEach((c) => (captureMap[c.name] = c.node)); + if (!captureMap['call']) return; + const callNameNode = captureMap['call.name']; + if (!callNameNode) return; + const routed = callRouter(callNameNode.text, captureMap['call']); + if (!routed || routed.kind !== 'properties') return; + + const propEnclosingInfo = findEnclosingClassInfo( + captureMap['call'], + file.path, + provider.resolveEnclosingOwner, + ); + const propEnclosingClassId = propEnclosingInfo?.classId ?? null; + + // Enrich routed properties with FieldExtractor metadata so types + // discovered from constructor assignments (e.g. `@address = Address.new`) + // are propagated even when the routing payload itself lacks declaredType. + let routedFieldMap: Map | undefined; + if (provider.fieldExtractor && typeEnv) { + const classNode = findEnclosingClassNode(captureMap['call']); + if (classNode) { + routedFieldMap = getFieldInfo( + classNode, + provider, + { + typeEnv, + symbolTable: NOOP_SYMBOL_TABLE, + filePath: file.path, + language, + }, + fieldInfoCache, + ); + } + } + + const fileId = generateId('File', file.path); + for (const item of routed.items) { + const routedFieldInfo = routedFieldMap?.get(item.propName); + const propQualifiedName = propEnclosingInfo + ? `${propEnclosingInfo.className}.${item.propName}` + : item.propName; + const nodeId = generateId('Property', `${file.path}:${propQualifiedName}`); + graph.addNode({ + id: nodeId, + label: 'Property', + properties: { + name: item.propName, + filePath: file.path, + startLine: item.startLine, + endLine: item.endLine, + language, + isExported: true, + description: item.accessorType, + ...(item.declaredType + ? { declaredType: item.declaredType } + : routedFieldInfo?.type + ? { declaredType: routedFieldInfo.type } + : {}), + ...(routedFieldInfo?.visibility !== undefined + ? { visibility: routedFieldInfo.visibility } + : {}), + ...(routedFieldInfo?.isStatic !== undefined + ? { isStatic: routedFieldInfo.isStatic } + : {}), + ...(routedFieldInfo?.isReadonly !== undefined + ? { isReadonly: routedFieldInfo.isReadonly } + : {}), + }, + }); + ctx.model.symbols.add(file.path, item.propName, nodeId, 'Property', { + ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}), + ...(item.declaredType + ? { declaredType: item.declaredType } + : routedFieldInfo?.type + ? { declaredType: routedFieldInfo.type } + : {}), + }); + const relId = generateId('DEFINES', `${fileId}->${nodeId}`); + graph.addRelationship({ + id: relId, + sourceId: fileId, + targetId: nodeId, + type: 'DEFINES', + confidence: 1.0, + reason: '', + }); + if (propEnclosingClassId) { + graph.addRelationship({ + id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`), + sourceId: propEnclosingClassId, + targetId: nodeId, + type: 'HAS_PROPERTY', + confidence: 1.0, + reason: '', + }); + } + } + }); + } + // ── Resolution loop: verify constructor bindings and resolve calls ── // The accumulator (if present) is now fully populated from the preparation // loop above, so verifyConstructorBindings sees all provider bindings @@ -930,9 +1102,10 @@ export const processCalls = async ( provider, ); const srcId = enclosing || generateId('File', file.path); - // Defer resolution: Ruby attr_accessor properties are registered during - // this same loop, so cross-file lookups fail if the declaring file hasn't - // been processed yet. Collect now, resolve after all files are done. + // Defer resolution so write-access tracking sees the FINAL graph + // state — properties from the pre-pass are present, but receiver-type + // resolution can still depend on inference that completes during the + // main loop. Resolve after all files have been processed. pendingWrites.push({ receiverTypeName, propertyName, filePath: file.path, srcId }); } // Assignment-only capture (no @call sibling): skip the rest of this @@ -1053,47 +1226,8 @@ export const processCalls = async ( return; case 'properties': { - const fileId = generateId('File', file.path); - const propEnclosingClassId = findEnclosingClassId(captureMap['call'], file.path); - for (const item of routed.items) { - const nodeId = generateId('Property', `${file.path}:${item.propName}`); - graph.addNode({ - id: nodeId, - label: 'Property', - properties: { - name: item.propName, - filePath: file.path, - startLine: item.startLine, - endLine: item.endLine, - language, - isExported: true, - description: item.accessorType, - }, - }); - ctx.model.symbols.add(file.path, item.propName, nodeId, 'Property', { - ...(propEnclosingClassId ? { ownerId: propEnclosingClassId } : {}), - ...(item.declaredType ? { declaredType: item.declaredType } : {}), - }); - const relId = generateId('DEFINES', `${fileId}->${nodeId}`); - graph.addRelationship({ - id: relId, - sourceId: fileId, - targetId: nodeId, - type: 'DEFINES', - confidence: 1.0, - reason: '', - }); - if (propEnclosingClassId) { - graph.addRelationship({ - id: generateId('HAS_PROPERTY', `${propEnclosingClassId}->${nodeId}`), - sourceId: propEnclosingClassId, - targetId: nodeId, - type: 'HAS_PROPERTY', - confidence: 1.0, - reason: '', - }); - } - } + // Properties already registered in the pre-pass above. + // Skip to avoid duplicate nodes/edges. return; } diff --git a/gitnexus/src/core/ingestion/community-processor.ts b/gitnexus/src/core/ingestion/community-processor.ts index 9913e4a3f..ac8f068fa 100644 --- a/gitnexus/src/core/ingestion/community-processor.ts +++ b/gitnexus/src/core/ingestion/community-processor.ts @@ -41,6 +41,24 @@ interface LeidenDetailedResult { modularity: number; } +/** + * Deterministic PRNG (mulberry32) seed for the vendored Leiden algorithm. + * Vendored Leiden defaults `rng: Math.random`, which makes community + * assignment non-deterministic across runs. Passing a seeded RNG gives us + * reproducible community/modularity output, which is required for the + * incremental-indexing equivalence test (incremental ≡ full rebuild). + */ +const LEIDEN_SEED = 0xc0de; +function createSeededRng(seed: number): () => number { + let s = seed >>> 0; + return () => { + s = (s + 0x6d2b79f5) >>> 0; + let t = Math.imul(s ^ (s >>> 15), 1 | s); + t = (t + Math.imul(t ^ (t >>> 7), 61 | t)) ^ t; + return ((t ^ (t >>> 14)) >>> 0) / 4294967296; + }; +} + // ============================================================================ // TYPES // ============================================================================ @@ -150,6 +168,7 @@ export const processCommunities = async ( leiden.detailed(graph, { resolution: isLarge ? 2.0 : 1.0, maxIterations: isLarge ? 3 : 0, + rng: createSeededRng(LEIDEN_SEED), }), ), new Promise((_, reject) => diff --git a/gitnexus/src/core/ingestion/parsing-processor.ts b/gitnexus/src/core/ingestion/parsing-processor.ts index 7559b26bc..04a17db4f 100644 --- a/gitnexus/src/core/ingestion/parsing-processor.ts +++ b/gitnexus/src/core/ingestion/parsing-processor.ts @@ -82,6 +82,88 @@ export interface WorkerExtractedData { // Worker-based parallel parsing // ============================================================================ +/** + * Merge a list of `ParseWorkerResult`s into the running graph + symbol + * table state and produce the chunk-aggregated `WorkerExtractedData`. + * + * Extracted from `processParsingWithWorkers` so the same merge logic can + * be applied to both freshly-parsed worker output AND cached worker + * output replayed during incremental analyze. Idempotent on the + * accumulator fields (push-only); idempotent on graph if the caller + * starts from a clean graph (otherwise duplicate `addNode` calls are + * silently no-op'd by `KnowledgeGraph`). + */ +export const mergeChunkResults = ( + graph: KnowledgeGraph, + symbolTable: SymbolTableWriter, + chunkResults: readonly ParseWorkerResult[], +): WorkerExtractedData => { + const allImports: ExtractedImport[] = []; + const allCalls: ExtractedCall[] = []; + const allAssignments: ExtractedAssignment[] = []; + const allHeritage: ExtractedHeritage[] = []; + const allRoutes: ExtractedRoute[] = []; + const allFetchCalls: ExtractedFetchCall[] = []; + const allDecoratorRoutes: ExtractedDecoratorRoute[] = []; + const allToolDefs: ExtractedToolDef[] = []; + const allORMQueries: ExtractedORMQuery[] = []; + const allConstructorBindings: FileConstructorBindings[] = []; + const fileScopeBindingsByFile: FileScopeBindings[] = []; + const allParsedFiles: ParsedFile[] = []; + + for (const result of chunkResults) { + for (const node of result.nodes) { + graph.addNode({ + id: node.id, + label: node.label as NodeLabel, + properties: node.properties, + }); + } + for (const rel of result.relationships) { + graph.addRelationship(rel); + } + for (const sym of result.symbols) { + symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type, { + parameterCount: sym.parameterCount, + requiredParameterCount: sym.requiredParameterCount, + parameterTypes: sym.parameterTypes, + returnType: sym.returnType, + declaredType: sym.declaredType, + ownerId: sym.ownerId, + qualifiedName: sym.qualifiedName, + }); + } + for (const item of result.imports) allImports.push(item); + for (const item of result.calls) allCalls.push(item); + for (const item of result.assignments) allAssignments.push(item); + for (const item of result.heritage) allHeritage.push(item); + for (const item of result.routes) allRoutes.push(item); + for (const item of result.fetchCalls) allFetchCalls.push(item); + for (const item of result.decoratorRoutes) allDecoratorRoutes.push(item); + for (const item of result.toolDefs) allToolDefs.push(item); + if (result.ormQueries) for (const item of result.ormQueries) allORMQueries.push(item); + for (const item of result.constructorBindings) allConstructorBindings.push(item); + if (result.fileScopeBindings) + for (const item of result.fileScopeBindings) fileScopeBindingsByFile.push(item); + if (result.parsedFiles) for (const item of result.parsedFiles) allParsedFiles.push(item); + } + + return { + imports: allImports, + calls: allCalls, + assignments: allAssignments, + heritage: allHeritage, + routes: allRoutes, + fetchCalls: allFetchCalls, + decoratorRoutes: allDecoratorRoutes, + toolDefs: allToolDefs, + ormQueries: allORMQueries, + constructorBindings: allConstructorBindings, + fileScopeBindings: fileScopeBindingsByFile, + parsedFiles: allParsedFiles, + }; +}; + const processParsingWithWorkers = async ( graph: KnowledgeGraph, files: { path: string; content: string }[], @@ -89,6 +171,14 @@ const processParsingWithWorkers = async ( astCache: ASTCache, workerPool: WorkerPool, onFileProgress?: FileProgressCallback, + /** + * When provided, populated with the raw worker results before merging. + * Used by the incremental-indexing parse cache to capture the per-chunk + * worker output for caching across runs. The mutation happens in-place + * so the caller (parse-impl) can keep a reference. See + * `gitnexus/src/storage/parse-cache.ts`. + */ + outRawResults?: ParseWorkerResult[], ): Promise => { // Filter to parseable files only const parseableFiles: ParseWorkerInput[] = []; @@ -123,63 +213,16 @@ const processParsingWithWorkers = async ( }, ); - // Merge results from all workers into graph and symbol table - const allImports: ExtractedImport[] = []; - const allCalls: ExtractedCall[] = []; - const allAssignments: ExtractedAssignment[] = []; - const allHeritage: ExtractedHeritage[] = []; - const allRoutes: ExtractedRoute[] = []; - const allFetchCalls: ExtractedFetchCall[] = []; - const allDecoratorRoutes: ExtractedDecoratorRoute[] = []; - const allToolDefs: ExtractedToolDef[] = []; - const allORMQueries: ExtractedORMQuery[] = []; - const allConstructorBindings: FileConstructorBindings[] = []; - const fileScopeBindingsByFile: FileScopeBindings[] = []; - const allParsedFiles: ParsedFile[] = []; - for (const result of chunkResults) { - for (const node of result.nodes) { - graph.addNode({ - id: node.id, - label: node.label as NodeLabel, - properties: node.properties, - }); - } - - for (const rel of result.relationships) { - graph.addRelationship(rel); - } - - for (const sym of result.symbols) { - symbolTable.add(sym.filePath, sym.name, sym.nodeId, sym.type, { - parameterCount: sym.parameterCount, - requiredParameterCount: sym.requiredParameterCount, - parameterTypes: sym.parameterTypes, - returnType: sym.returnType, - declaredType: sym.declaredType, - ownerId: sym.ownerId, - qualifiedName: sym.qualifiedName, - }); - } - - for (const item of result.imports) allImports.push(item); - for (const item of result.calls) allCalls.push(item); - for (const item of result.assignments) allAssignments.push(item); - for (const item of result.heritage) allHeritage.push(item); - for (const item of result.routes) allRoutes.push(item); - for (const item of result.fetchCalls) allFetchCalls.push(item); - for (const item of result.decoratorRoutes) allDecoratorRoutes.push(item); - for (const item of result.toolDefs) allToolDefs.push(item); - if (result.ormQueries) for (const item of result.ormQueries) allORMQueries.push(item); - for (const item of result.constructorBindings) allConstructorBindings.push(item); - if (result.fileScopeBindings) - for (const item of result.fileScopeBindings) fileScopeBindingsByFile.push(item); - // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of - // workers that don't emit the field yet (older worker builds or - // partial rollouts), since the additive contract means undefined = - // "this worker produced no ParsedFiles for this chunk". - if (result.parsedFiles) for (const item of result.parsedFiles) allParsedFiles.push(item); + // Capture the raw chunk results for the incremental parse cache before + // merging — the cache stores the unmerged worker output so a future run + // can re-merge them into a fresh graph state. + if (outRawResults) { + for (const r of chunkResults) outRawResults.push(r); } + // Merge results from all workers into graph and symbol table. + const merged = mergeChunkResults(graph, symbolTable, chunkResults); + // Merge and log skipped languages from workers const skippedLanguages = new Map(); for (const result of chunkResults) { @@ -196,20 +239,7 @@ const processParsingWithWorkers = async ( // Final progress onFileProgress?.(total, total, 'done'); - return { - imports: allImports, - calls: allCalls, - assignments: allAssignments, - heritage: allHeritage, - routes: allRoutes, - fetchCalls: allFetchCalls, - decoratorRoutes: allDecoratorRoutes, - toolDefs: allToolDefs, - ormQueries: allORMQueries, - constructorBindings: allConstructorBindings, - fileScopeBindings: fileScopeBindingsByFile, - parsedFiles: allParsedFiles, - }; + return merged; }; // ============================================================================ @@ -732,6 +762,14 @@ export const processParsing = async ( scopeTreeCache: ASTCache | undefined, onFileProgress?: FileProgressCallback, workerPool?: WorkerPool, + /** + * Optional out-parameter for the incremental parse cache. When + * provided AND the worker-pool path runs successfully, populated + * with the raw `ParseWorkerResult[]` from the workers (pre-merge). + * Stays empty for the sequential fallback path (no per-chunk + * artifact to cache there). See `gitnexus/src/storage/parse-cache.ts`. + */ + outRawResults?: ParseWorkerResult[], ): Promise => { let lastProgress = 0; const reportProgress: FileProgressCallback | undefined = onFileProgress @@ -759,6 +797,7 @@ export const processParsing = async ( astCache, workerPool, reportProgress, + outRawResults, ); } catch (err) { const message = err instanceof Error ? err.message : String(err); diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts index bd39a4330..17cfaab3f 100644 --- a/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts +++ b/gitnexus/src/core/ingestion/pipeline-phases/parse-impl.ts @@ -17,7 +17,10 @@ import { enrichExportedTypeMap, type BindingEntry, } from '../binding-accumulator.js'; -import { processParsing } from '../parsing-processor.js'; +import { processParsing, mergeChunkResults } from '../parsing-processor.js'; +import { fileContentHash, computeChunkHash } from '../../../storage/parse-cache.js'; +import type { ParseWorkerResult } from '../workers/parse-worker.js'; +import type { WorkerExtractedData } from '../parsing-processor.js'; import { processImports, processImportsFromExtracted, @@ -72,8 +75,21 @@ import { extractORMQueriesInline } from './orm-extraction.js'; import { logger } from '../../logger.js'; // ── Constants ────────────────────────────────────────────────────────────── -/** Max bytes of source content to load per parse chunk. */ -const CHUNK_BYTE_BUDGET = 20 * 1024 * 1024; // 20MB +/** Max bytes of source content to load per parse chunk. + * + * Memory bound for the worker pool dispatch + a granularity knob for + * the parse cache. A single file change invalidates only its enclosing + * chunk, so smaller budgets → finer-grained invalidation. + * + * Override via GITNEXUS_CHUNK_BYTE_BUDGET (bytes) — the default of 2MB + * gives a useful invalidation floor (~1/N chunks on a multi-MB repo) + * while keeping worker dispatch overhead under 5% on cold runs. + */ +const CHUNK_BYTE_BUDGET = (() => { + const env = Number(process.env.GITNEXUS_CHUNK_BYTE_BUDGET); + if (Number.isFinite(env) && env > 0) return env; + return 2 * 1024 * 1024; +})(); // ── Main parse + resolve function ────────────────────────────────────────── @@ -119,6 +135,11 @@ export async function runChunkedParseAndResolve( * source. See plan * docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4). */ scopeTreeCache: ASTCache; + /** Worker-produced ParsedFile artifacts aggregated across chunks. + * Threaded into scope-resolution as a re-extract cache so the warm- + * cache analyze run can skip the dominant `extractParsedFile` cost + * (otherwise ~58s on a 1000-file repo). */ + parsedFiles: import('gitnexus-shared').ParsedFile[]; }> { const ctx = createResolutionContext(); const symbolTable = ctx.model.symbols; @@ -142,6 +163,15 @@ export async function runChunkedParseAndResolve( ); } + // Sort parseableScanned alphabetically for stable chunk membership + // across runs (Finding 4). Without this, filesystem-scan order can + // shift between runs (notably on macOS APFS where directory entry + // order can change after modifications) — different files in the + // same chunk → different chunk hash → cache miss even when no file + // content changed. The cache also becomes platform-specific: a + // Linux-built cache misses on macOS for the same repo. + parseableScanned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0)); + const totalParseable = parseableScanned.length; if (totalParseable === 0) { @@ -271,6 +301,20 @@ export async function runChunkedParseAndResolve( const deferredWorkerHeritage: ExtractedHeritage[] = []; const deferredConstructorBindings: FileConstructorBindings[] = []; const deferredAssignments: ExtractedAssignment[] = []; + // Aggregated per-file ParsedFile artifacts produced by workers' calls + // to `extractParsedFile`. Threaded through to the scope-resolution + // phase so it can SKIP its own re-extraction on cache hits — this is + // the second-half of the parse-cache speedup since scope-resolution's + // re-parse otherwise dominates the warm-cache wall-clock time. + const allParsedFiles: import('gitnexus-shared').ParsedFile[] = []; + + // Incremental parse cache (Option B): chunk-level content-addressed. + // When the chunk's (filePath, content-hash) signature matches a prior + // run's, replay the cached ParseWorkerResult[] instead of dispatching + // to workers. See gitnexus/src/storage/parse-cache.ts. + const parseCache = options?.parseCache; + let chunkCacheHits = 0; + let chunkCacheMisses = 0; try { for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) { @@ -281,29 +325,89 @@ export async function runChunkedParseAndResolve( .filter((p) => chunkContents.has(p)) .map((p) => ({ path: p, content: chunkContents.get(p)! })); - const chunkWorkerData = await processParsing( - graph, - chunkFiles, - symbolTable, - astCache, - scopeTreeCache, - (current, _total, filePath) => { - const globalCurrent = filesParsedSoFar + current; - const parsingProgress = 20 + (globalCurrent / totalParseable) * 62; - onProgress({ - phase: 'parsing', - percent: Math.round(parsingProgress), - message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`, - detail: filePath, - stats: { - filesProcessed: globalCurrent, - totalFiles: totalParseable, - nodesCreated: graph.nodeCount, - }, - }); - }, - workerPool, - ); + // Compute the chunk's content-hash signature (if cache available). + let chunkHash: string | null = null; + if (parseCache) { + const entries = chunkFiles.map((f) => ({ + filePath: f.path, + contentHash: fileContentHash(f.content), + })); + chunkHash = computeChunkHash(entries); + } + + let chunkWorkerData: WorkerExtractedData | null; + const cachedRaw = chunkHash ? parseCache!.entries.get(chunkHash) : undefined; + + // Track every chunk hash we touched so the orchestrator can + // prune stale entries (chunks whose composition no longer + // corresponds to a live chunk in the current scan) before saving. + if (parseCache && chunkHash) parseCache.usedKeys.add(chunkHash); + + if (cachedRaw && cachedRaw.length > 0) { + // Cache hit: replay the cached worker output through the same + // merge logic the live worker path uses. + chunkCacheHits++; + chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw); + if (isDev) { + logger.info( + `📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash!.slice(0, 8)})`, + ); + } + // Progress update so UI advances even on a cache hit. + const cachedFiles = chunkFiles.length; + onProgress({ + phase: 'parsing', + percent: Math.round(20 + ((filesParsedSoFar + cachedFiles) / totalParseable) * 62), + message: `Parsing chunk ${chunkIdx + 1}/${numChunks} (cache)...`, + stats: { + filesProcessed: filesParsedSoFar + cachedFiles, + totalFiles: totalParseable, + nodesCreated: graph.nodeCount, + }, + }); + } else { + // Cache miss: dispatch to workers, capture the raw results, store + // them under the chunk hash for the next run. + chunkCacheMisses++; + const rawResults: ParseWorkerResult[] = []; + chunkWorkerData = await processParsing( + graph, + chunkFiles, + symbolTable, + astCache, + scopeTreeCache, + (current, _total, filePath) => { + const globalCurrent = filesParsedSoFar + current; + const parsingProgress = 20 + (globalCurrent / totalParseable) * 62; + onProgress({ + phase: 'parsing', + percent: Math.round(parsingProgress), + message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`, + detail: filePath, + stats: { + filesProcessed: globalCurrent, + totalFiles: totalParseable, + nodesCreated: graph.nodeCount, + }, + }); + }, + workerPool, + // Capture raw results only when we have a cache to write to — + // otherwise we'd retain extra arrays for nothing. + parseCache && chunkHash ? rawResults : undefined, + ); + // Persist the raw results for this chunk hash. Sequential path + // doesn't populate rawResults (it writes directly to graph), so + // small repos without worker pool simply don't cache. That's fine. + if (parseCache && chunkHash && rawResults.length > 0) { + parseCache.entries.set(chunkHash, rawResults); + if (isDev) { + logger.info( + `📦 parse-cache MISS+store: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`, + ); + } + } + } const chunkBasePercent = 20 + (filesParsedSoFar / totalParseable) * 62; @@ -349,6 +453,12 @@ export async function runChunkedParseAndResolve( for (const item of chunkWorkerData.heritage) deferredWorkerHeritage.push(item); for (const item of chunkWorkerData.constructorBindings) deferredConstructorBindings.push(item); + // Aggregate worker-produced ParsedFile artifacts so scope- + // resolution can use them as a re-extraction cache (skips its + // own tree-sitter re-parse on warm runs). + if (chunkWorkerData.parsedFiles?.length) { + for (const item of chunkWorkerData.parsedFiles) allParsedFiles.push(item); + } if (chunkWorkerData.assignments?.length) { for (const item of chunkWorkerData.assignments) deferredAssignments.push(item); } @@ -422,6 +532,12 @@ export async function runChunkedParseAndResolve( astCache.clear(); } + if (isDev && parseCache && (chunkCacheHits > 0 || chunkCacheMisses > 0)) { + logger.info( + `📦 parse-cache summary: ${chunkCacheHits} chunk hit(s), ${chunkCacheMisses} miss(es) across ${numChunks} chunk(s)`, + ); + } + const fullWorkerHeritageMap = deferredWorkerHeritage.length > 0 ? buildHeritageMap(deferredWorkerHeritage, ctx, getHeritageStrategyForLanguage) @@ -621,5 +737,12 @@ export async function runChunkedParseAndResolve( // chunk-local `astCache` above is intentionally NOT exposed // because parse-impl clears it between chunks. scopeTreeCache, + // Per-file ParsedFile artifacts produced by workers' calls to + // `extractParsedFile`. Empty when only the sequential path ran + // (sequential doesn't go through the worker, and extracts ParsedFile + // inline rather than emitting it). Consumed by scope-resolution as + // a re-extraction cache: when the file's ParsedFile is here, + // scope-resolution skips its own `extractParsedFile` call. + parsedFiles: allParsedFiles, }; } diff --git a/gitnexus/src/core/ingestion/pipeline-phases/parse.ts b/gitnexus/src/core/ingestion/pipeline-phases/parse.ts index a20d1e4b0..a3fa81be7 100644 --- a/gitnexus/src/core/ingestion/pipeline-phases/parse.ts +++ b/gitnexus/src/core/ingestion/pipeline-phases/parse.ts @@ -20,6 +20,7 @@ import type { PipelinePhase, PipelineContext, PhaseResult } from './types.js'; import { getPhaseOutput } from './types.js'; import type { StructureOutput } from './structure.js'; import type { BindingAccumulator } from '../binding-accumulator.js'; +import type { ParsedFile } from 'gitnexus-shared'; import type { ExtractedFetchCall, ExtractedRoute, @@ -81,6 +82,19 @@ export interface ParseOutput { * `scopeTreeCache.clear()` after its extract loop finishes. */ readonly scopeTreeCache: ASTCache; + /** + * Per-file `ParsedFile` artifacts produced by workers' calls to + * `extractParsedFile`. Threaded through to `scopeResolutionPhase` + * as a re-extraction cache: when a file's ParsedFile is present here, + * scope-resolution can skip its own `extractParsedFile` (which would + * otherwise re-parse the file with tree-sitter on the main thread, + * costing ~58s on a 1000-file repo). + * + * Empty for files that went through the sequential parse fallback — + * sequential doesn't emit ParsedFile artifacts; scope-resolution + * falls back to a fresh extract for those. + */ + readonly parsedFiles: readonly ParsedFile[]; } export const parsePhase: PipelinePhase = { diff --git a/gitnexus/src/core/ingestion/pipeline.ts b/gitnexus/src/core/ingestion/pipeline.ts index c220ea224..1ee8e102f 100644 --- a/gitnexus/src/core/ingestion/pipeline.ts +++ b/gitnexus/src/core/ingestion/pipeline.ts @@ -55,6 +55,19 @@ export interface PipelineOptions { minFiles?: number; minBytes?: number; }; + /** + * Incremental-indexing parse cache. When provided: + * - The parse phase looks up each chunk's content hash in + * `parseCache.entries`. On hit, it replays the cached + * `ParseWorkerResult[]` instead of dispatching to workers. + * - On miss, it runs the workers as today and stores the new + * results in `parseCache.entries` keyed by chunk hash. + * The caller (`run-analyze.ts`) is responsible for loading the cache + * before the pipeline runs and persisting it after. Cache survives + * `--force` because keys are content-addressed. + * See `gitnexus/src/storage/parse-cache.ts`. + */ + parseCache?: import('../../storage/parse-cache.js').ParseCache; } // ── Phase registry ───────────────────────────────────────────────────────── diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts index c2fda9777..98a9f8994 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/phase.ts @@ -93,13 +93,25 @@ export const scopeResolutionPhase: PipelinePhase = { // Worker-mode parses leave the cache empty for those files; they // also fall back to a fresh parse — no correctness impact. const parseOutput = getPhaseOutput(deps, 'parse'); - const { scopeTreeCache, resolutionContext } = parseOutput; + const { scopeTreeCache, resolutionContext, parsedFiles: workerParsedFiles } = parseOutput; // SemanticModel populated during `parse`: scope-resolution consumes // TypeRegistry / MethodRegistry / SymbolTable lookups instead of // rebuilding parallel indexes. See ARCHITECTURE.md § "Semantic-model // source of truth". const model = resolutionContext.model; + // Build a per-file lookup of ParsedFile artifacts the workers (or + // sequential extracts) already produced. Threading this into + // `runScopeResolution` lets the per-language extract loop short- + // circuit `extractParsedFile` — the dominant cost on the warm-cache + // path, since workers can't return tree-sitter Trees across the + // MessageChannel and scope-resolution would otherwise re-parse + // every file from scratch on the main thread. + const preExtractedByPath = new Map(); + for (const pf of workerParsedFiles) { + preExtractedByPath.set(pf.filePath, pf); + } + let totalFiles = 0; let totalImports = 0; let totalRefs = 0; @@ -143,6 +155,7 @@ export const scopeResolutionPhase: PipelinePhase = { files, treeCache: scopeTreeCache, resolutionConfig, + preExtractedParsedFiles: preExtractedByPath, onWarn: (msg) => { if (isSemanticModelValidatorEnabled()) { logger.warn(`[scope-resolution:${lang}] ${msg}`); diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts index e2c734a43..31a58cdfa 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts @@ -72,6 +72,22 @@ interface RunScopeResolutionInput { * provider doesn't supply a config loader. */ readonly resolutionConfig?: unknown; + /** + * Pre-extracted ParsedFile artifacts keyed by file path. When a + * file is present here, the extract loop reuses it directly and + * skips `extractParsedFile` (which would re-parse the file with + * tree-sitter on the main thread). Only files matching the + * provider's language are honored — the loop verifies this + * implicitly by language filter at the call-site (scopeResolution + * phase). + * + * Worker-mode parses produce these ParsedFile artifacts as a side + * effect of `extractParsedFile` running inside the worker; threading + * them here is what lets the warm-cache analyze run skip the ~58s + * scope-resolution re-parse loop on a multi-thousand-file repo. + * Cache miss is safe — falls back to fresh extract. + */ + readonly preExtractedParsedFiles?: ReadonlyMap; } interface RunScopeResolutionStats { @@ -104,22 +120,37 @@ export function runScopeResolution( const parsedFiles: ParsedFile[] = []; let filesSkipped = 0; const treeCache = input.treeCache; + const preExtracted = input.preExtractedParsedFiles; + let preExtractedHits = 0; for (const file of files) { - const cachedTree = treeCache?.get(file.path); - const parsed = extractParsedFile( - provider.languageProvider, - file.content, - file.path, - onWarn, - cachedTree, - ); + let parsed: ParsedFile | undefined; + // Fast path: a worker (during the parse phase) already produced a + // ParsedFile for this file via `extractParsedFile`. Reuse it + // directly — skips a tree-sitter re-parse on the main thread. + if (preExtracted !== undefined) { + parsed = preExtracted.get(file.path); + if (parsed !== undefined) preExtractedHits++; + } if (parsed === undefined) { - filesSkipped++; - continue; + const cachedTree = treeCache?.get(file.path); + parsed = extractParsedFile( + provider.languageProvider, + file.content, + file.path, + onWarn, + cachedTree, + ); + if (parsed === undefined) { + filesSkipped++; + continue; + } } provider.populateOwners(parsed); parsedFiles.push(parsed); } + if (PROF && preExtracted !== undefined) { + logger.warn(`[scope-resolution prof] pre-extracted hits: ${preExtractedHits}/${files.length}`); + } provider.populateWorkspaceOwners?.(parsedFiles, { fileContents: getFileContents() }); // Reconcile scope-resolution's ownership view into the SemanticModel. diff --git a/gitnexus/src/core/lbug/lbug-adapter.ts b/gitnexus/src/core/lbug/lbug-adapter.ts index fe831cd43..caa7a58a1 100644 --- a/gitnexus/src/core/lbug/lbug-adapter.ts +++ b/gitnexus/src/core/lbug/lbug-adapter.ts @@ -1204,6 +1204,77 @@ export const deleteNodesForFile = async ( export const getEmbeddingTableName = (): string => EMBEDDING_TABLE_NAME; +/** + * Return the distinct repo-relative paths of files that import + * `targetFilePath` according to the IMPORTS edges currently in the + * DB. Used by the incremental writeback path to expand the + * "files-to-rewrite" set so that files importing a changed file get + * their edges (which may have been refined by cross-file resolution) + * re-emitted, rather than left stale in the DB. + * + * The DB query reads the *previous* run's state — pre-pipeline, before + * any nodes are deleted — so the returned importers are "files that + * USED TO import the target". That's the right set to invalidate: + * those are the files whose edges in the DB might no longer match + * what cross-file resolution produces given the changed file's new + * exports. + */ +export const queryImporters = async (targetFilePath: string): Promise => { + if (!conn) { + throw new Error('LadybugDB not initialized. Call initLbug first.'); + } + const escaped = targetFilePath.replace(/'/g, "''"); + const cypher = ` + MATCH (a)-[r:${REL_TABLE_NAME}]->(b) + WHERE r.type = 'IMPORTS' AND b.filePath = '${escaped}' + RETURN DISTINCT a.filePath AS importer + `; + try { + const queryResult = await conn.query(cypher); + const result = Array.isArray(queryResult) ? queryResult[0] : queryResult; + const rows = await result.getAll(); + const out: string[] = []; + for (const row of rows) { + const v = (row as { importer?: unknown }).importer; + if (typeof v === 'string' && v.length > 0) out.push(v); + } + return out; + } catch { + return []; + } +}; + +/** + * Drop every Community and Process node (and their MEMBER_OF / + * STEP_IN_PROCESS edges via DETACH DELETE). Used at the start of an + * incremental run so the communities and processes phases regenerate + * them from scratch on the merged graph — required for the + * "Leiden runs on the FULL graph" correctness invariant. + */ +export const deleteAllCommunitiesAndProcesses = async (): Promise<{ + nodesDeleted: number; +}> => { + if (!conn) { + throw new Error('LadybugDB not initialized. Call initLbug first.'); + } + let nodesDeleted = 0; + for (const label of ['Community', 'Process']) { + try { + const countResult = await conn.query(`MATCH (n:${label}) RETURN count(n) AS cnt`); + const result = Array.isArray(countResult) ? countResult[0] : countResult; + const rows = await result.getAll(); + const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0); + if (count > 0) { + await conn.query(`MATCH (n:${label}) DETACH DELETE n`); + nodesDeleted += count; + } + } catch { + // Table may not exist yet on a freshly-initialized DB — fine. + } + } + return { nodesDeleted }; +}; + // ============================================================================ // Full-Text Search (FTS) Functions // ============================================================================ diff --git a/gitnexus/src/core/run-analyze.ts b/gitnexus/src/core/run-analyze.ts index fa2757f45..425f18f9a 100644 --- a/gitnexus/src/core/run-analyze.ts +++ b/gitnexus/src/core/run-analyze.ts @@ -11,6 +11,7 @@ import path from 'path'; import fs from 'fs/promises'; +import { execFileSync } from 'child_process'; import { runPipelineFromRepo } from './ingestion/pipeline.js'; import { initLbug, @@ -20,6 +21,9 @@ import { executeWithReusedStatement, closeLbug, loadCachedEmbeddings, + deleteNodesForFile, + deleteAllCommunitiesAndProcesses, + queryImporters, } from './lbug/lbug-adapter.js'; import { createSearchFTSIndexes } from './search/fts-indexes.js'; import { @@ -29,7 +33,15 @@ import { ensureGitNexusIgnored, registerRepo, cleanupOldKuzuFiles, + INCREMENTAL_SCHEMA_VERSION, } from '../storage/repo-manager.js'; +import { computeFileHashes, diffFileHashes } from '../storage/file-hash.js'; +import { + extractChangedSubgraph, + computeEffectiveWriteSet, +} from './incremental/subgraph-extract.js'; +import { shadowCandidatesFor } from './incremental/shadow-candidates.js'; +import { loadParseCache, saveParseCache, pruneCache } from '../storage/parse-cache.js'; import { getCurrentCommit, getRemoteUrl, @@ -178,23 +190,81 @@ export async function runFullAnalysis( const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : ''; const existingMeta = await loadMeta(storagePath); + // ── Crash recovery: dirty flag forces full rebuild ──────────────── + // If the previous incremental run set incrementalInProgress and didn't + // clear it, the on-disk index may be in a half-state. Cheapest path + // back to a known-good index is to wipe + rebuild from scratch. + if (existingMeta?.incrementalInProgress) { + log( + 'Previous incremental run did not complete cleanly (incrementalInProgress flag set); ' + + 'forcing full rebuild to restore a known-good index.', + ); + options = { ...options, force: true }; + // Reload meta after clearing the flag in-memory; we still want fileHashes + // for the post-rebuild meta carry-over, but force=true ensures the + // rebuild path executes. + } + // ── Early-return: already up to date ────────────────────────────── if (existingMeta && !options.force && existingMeta.lastCommit === currentCommit) { // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes if (currentCommit !== '') { - await ensureGitNexusIgnored(repoPath); - return { - // `resolveRepoIdentityRoot` collapses worktree roots to the - // canonical repo basename (#1259) but leaves arbitrary subdirs - // and `--skip-git` paths unchanged (#1232/#1233 intent preserved). - repoName: - options.registryName ?? - getInferredRepoName(repoPath) ?? - path.basename(resolveRepoIdentityRoot(repoPath)), - repoPath, - stats: existingMeta.stats ?? {}, - alreadyUpToDate: true, - }; + // For git repos, even if HEAD matches lastCommit, the working tree + // may have uncommitted changes. Only short-circuit when the working + // tree is also clean — otherwise fall through to the incremental + // path which will hash-diff and update only changed files. + // + // We exclude paths that GitNexus itself writes during analyze: + // .gitnexus/ — db / parse cache / meta.json + // .claude/, .cursor/ — auto-generated agent skill files + // AGENTS.md, CLAUDE.md — auto-updated stats blocks + // Counting them as dirty would perpetually defeat the up-to-date + // fast path because the previous analyze just wrote them + // (regression vs PR #1233 behavior). + const dirty = (() => { + try { + const out = execFileSync( + 'git', + [ + 'status', + '--porcelain', + '--', + '.', + ':(exclude).gitnexus', + ':(exclude).gitnexus/**', + ':(exclude).claude', + ':(exclude).claude/**', + ':(exclude).cursor', + ':(exclude).cursor/**', + ':(exclude)AGENTS.md', + ':(exclude)CLAUDE.md', + ], + { + cwd: repoPath, + stdio: ['ignore', 'pipe', 'ignore'], + encoding: 'utf8', + }, + ); + return out.trim().length > 0; + } catch { + return true; // conservative on git failure + } + })(); + if (!dirty) { + await ensureGitNexusIgnored(repoPath); + return { + // `resolveRepoIdentityRoot` collapses worktree roots to the + // canonical repo basename (#1259) but leaves arbitrary subdirs + // and `--skip-git` paths unchanged (#1232/#1233 intent preserved). + repoName: + options.registryName ?? + getInferredRepoName(repoPath) ?? + path.basename(resolveRepoIdentityRoot(repoPath)), + repoPath, + stats: existingMeta.stats ?? {}, + alreadyUpToDate: true, + }; + } } } @@ -243,6 +313,14 @@ export async function runFullAnalysis( ); } + // We *always* load the embedding cache when one is requested (regardless + // of the predicted `willTryIncremental`). The post-pipeline branch may + // disagree with the prediction (e.g. when the pipeline produces zero + // File nodes, `isIncremental` flips false and the full-rebuild path + // wipes the DB) — loading unconditionally is cheap insurance against + // silently dropping embeddings on a mispredicted run. The re-insert + // step gates itself on the actual `isIncremental` value to avoid + // PK-conflicts when the incremental writeback path keeps the rows. if (shouldLoadCache && existingMeta) { try { progress('embeddings', 0, 'Caching embeddings...'); @@ -270,24 +348,89 @@ export async function runFullAnalysis( } } + // ── Load incremental parse cache ────────────────────────────────── + // Content-addressed: safe to reuse across `--force` runs (chunks whose + // file contents haven't changed produce identical worker output). + // Loaded into a single ParseCache object that the pipeline mutates + // in-place (cache hits leave entries unchanged; misses add new ones). + const parseCache = await loadParseCache(storagePath); + // ── Phase 1: Full Pipeline (0–60%) ──────────────────────────────── - const pipelineResult = await runPipelineFromRepo(repoPath, (p) => { - const phaseLabel = PHASE_LABELS[p.phase] || p.phase; - const scaled = Math.round(p.percent * 0.6); - const message = p.detail ? `${p.message || phaseLabel} (${p.detail})` : p.message || phaseLabel; - progress(p.phase, scaled, message); - }); + const pipelineResult = await runPipelineFromRepo( + repoPath, + (p) => { + const phaseLabel = PHASE_LABELS[p.phase] || p.phase; + const scaled = Math.round(p.percent * 0.6); + const message = p.detail + ? `${p.message || phaseLabel} (${p.detail})` + : p.message || phaseLabel; + progress(p.phase, scaled, message); + }, + { parseCache }, + ); // ── Phase 2: LadybugDB (60–85%) ────────────────────────────────── progress('lbug', 60, 'Loading into LadybugDB...'); - await closeLbug(); - const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`]; - for (const f of lbugFiles) { - try { - await fs.rm(f, { recursive: true, force: true }); - } catch { - /* swallow */ + // Compute current per-file content hashes from the pipeline's File nodes. + // Used both to drive the incremental DB writeback (when eligible) and to + // populate meta.json.fileHashes for the next run. + const allFilePaths: string[] = []; + pipelineResult.graph.forEachNode((n) => { + if (n.label === 'File') { + const fp = n.properties?.filePath as string | undefined; + if (fp) allFilePaths.push(fp); + } + }); + const newFileHashes = await computeFileHashes(repoPath, allFilePaths); + + // Decide incremental vs full at THIS point (post-pipeline, pre-DB). + // All eligibility conditions are checked here against the actual + // pipeline output — no separate pre-pipeline prediction to desync from + // (Bugbot review on PR #1479: a prediction that flipped post-pipeline + // could skip the embedding cache load and then take the full-rebuild + // path, silently losing embeddings). + const isIncremental = + !options.force && + !!existingMeta && + existingMeta.schemaVersion === INCREMENTAL_SCHEMA_VERSION && + !!existingMeta.fileHashes && + Object.keys(existingMeta.fileHashes).length > 0 && + repoHasGit && + allFilePaths.length > 0; + + const hashDiff = isIncremental + ? diffFileHashes(newFileHashes, existingMeta!.fileHashes) + : undefined; + + if (isIncremental && hashDiff) { + log( + `Incremental: changed=${hashDiff.changed.length}, ` + + `added=${hashDiff.added.length}, ` + + `deleted=${hashDiff.deleted.length} ` + + `(skipping wipe + ${ + allFilePaths.length - hashDiff.toWrite.length + } unchanged file rows preserved)`, + ); + // Set the dirty flag BEFORE any destructive DB mutation. Cleared on + // success at the meta-save step. + await saveMeta(storagePath, { + ...existingMeta!, + incrementalInProgress: { + startedAt: Date.now(), + toWriteCount: hashDiff.toWrite.length, + }, + }); + } else { + // Full rebuild path: wipe DB files first. + await closeLbug(); + const lbugFiles = [lbugPath, `${lbugPath}.wal`, `${lbugPath}.lock`]; + for (const f of lbugFiles) { + try { + await fs.rm(f, { recursive: true, force: true }); + } catch { + /* swallow */ + } } } @@ -298,11 +441,145 @@ export async function runFullAnalysis( // must be released to avoid blocking subsequent invocations. let lbugMsgCount = 0; - await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => { - lbugMsgCount++; - const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24)); - progress('lbug', pct, msg); - }); + if (isIncremental && hashDiff) { + // ── Incremental DB writeback ─────────────────────────────────── + // 0. Expand the writable set with transitive importers of + // changed/deleted files (bounded BFS). + // + // Reason (Bugbot/Claude review on PR #1479): when a barrel / + // re-export file C changes, cross-file resolution may update + // CALLS edges between two unchanged files A and B (A imports + // from C, C re-exports something from B). Those refined edges + // live in `ctx.graph` but would be excluded from the subgraph + // if neither endpoint is in the changed set. To catch this, + // files that imported (directly OR transitively, through + // other unchanged intermediaries) any changed file get pulled + // into the writable set so their rows are deleted + rewritten + // against the refined edges. + // + // BFS bound: MAX_IMPORTER_BFS_DEPTH. Practically sized to + // catch nested barrel chains (e.g. `index.ts → submodule/index.ts + // → submodule/impl.ts`) without ballooning into a near-full- + // rebuild on monorepos with deep re-export pyramids. Beyond + // this depth, the "incremental ≡ full-rebuild" invariant is + // self-acknowledged as best-effort; `--force` remains the + // escape hatch documented in GUARDRAILS.md. + // + // `queryImporters` reads `IMPORTS` from the pre-pipeline DB + // state, so the result is "files that USED TO import the + // target" — exactly the set whose previously-stored edges may + // no longer match what cross-file resolution produces this run. + const MAX_IMPORTER_BFS_DEPTH = 4; + const writableFiles = new Set(hashDiff.toWrite); + const directlyChangedCount = writableFiles.size; + + // Shadow-seed: for ADDED files, queryImporters returns 0 (the new + // file has no IMPORTS rows in the pre-pipeline DB yet). But pre- + // existing unchanged files may have IMPORTS edges whose module- + // resolution claim the newcomer can steal under standard JS/TS + // resolution (Bugbot review on PR #1479). For each added file we + // derive the shadow candidates and, if the candidate was a known + // file in the prior meta, seed it into the BFS frontier so its + // importers — surfaced via queryImporters — get their CALLS edges + // re-resolved against the new file. See shadow-candidates.ts for + // the full pattern catalogue. + const priorFileSet = new Set( + existingMeta?.fileHashes ? Object.keys(existingMeta.fileHashes) : [], + ); + const shadowSeed: string[] = []; + for (const added of hashDiff.added) { + for (const cand of shadowCandidatesFor(added)) { + if (priorFileSet.has(cand) && !writableFiles.has(cand)) { + shadowSeed.push(cand); + } + } + } + + { + let frontier: string[] = [...hashDiff.toWrite, ...hashDiff.deleted, ...shadowSeed]; + for (let depth = 0; depth < MAX_IMPORTER_BFS_DEPTH && frontier.length > 0; depth++) { + const nextFrontier: string[] = []; + for (const f of frontier) { + try { + const importers = await queryImporters(f); + for (const i of importers) { + if (!writableFiles.has(i)) { + writableFiles.add(i); + nextFrontier.push(i); + } + } + } catch { + /* per-file importer query failure → skip; correctness degrades on + that branch, but DB stays writable. */ + } + } + frontier = nextFrontier; + } + } + const importerExpansion = writableFiles.size - directlyChangedCount; + if (importerExpansion > 0) { + log( + `Incremental: +${importerExpansion} importer(s) added to writable set ` + + `(BFS depth ≤ ${MAX_IMPORTER_BFS_DEPTH}` + + (shadowSeed.length > 0 ? `, ${shadowSeed.length} shadow-seed(s)` : '') + + `)`, + ); + } + + // 1. Compute the EFFECTIVE write-set (Finding 1). Two layers, + // composed: + // (a) `writableFiles` — toWrite ∪ transitive importers of + // changed/deleted files (the bounded BFS above, reading + // IMPORTS from the pre-pipeline DB). + // (b) `computeEffectiveWriteSet` — walks the NEW graph's + // edges and pulls in any unchanged-side file that sits + // on a writable-boundary-crossing edge (catches refined + // cross-file CALLS edges that the pre-run DB couldn't + // predict, e.g. a barrel re-export shifting `foo` from + // B to D). + // The composed set is the input to BOTH deleteNodesForFile + // and extractChangedSubgraph — asymmetry between the two would + // leave stale rows or PK-conflict at COPY time. + const effectiveWriteSet = computeEffectiveWriteSet(pipelineResult.graph, writableFiles); + // Deduped: deleted entries may already appear via importer-BFS + // expansion (queryImporters can return a now-deleted path), which + // would otherwise call deleteNodesForFile twice for the same file + // (Bugbot LOW finding on PR #1479). + const filesToDelete = [...new Set([...effectiveWriteSet, ...hashDiff.deleted])]; + for (let i = 0; i < filesToDelete.length; i++) { + const f = filesToDelete[i]; + try { + await deleteNodesForFile(f); + } catch { + /* file may not have rows (e.g. an unparseable file) — fine */ + } + if (i % 20 === 0) { + progress('lbug', 62, `Removing rows for changed files (${i}/${filesToDelete.length})...`); + } + } + // 2. Drop graph-wide nodes (Community, Process). They'll be re-inserted + // from the fresh pipeline output below. Required for the + // "Leiden runs on the FULL graph" correctness invariant. + await deleteAllCommunitiesAndProcesses(); + + // 3. Extract the changed subgraph from the FULL ctx.graph and write + // only that. Unchanged-file rows in the DB stay untouched. Pass + // the SAME effectiveWriteSet so the subgraph and the deletes + // cover identical files (asymmetry would silently corrupt). + const subgraph = extractChangedSubgraph(pipelineResult.graph, effectiveWriteSet); + await loadGraphToLbug(subgraph, pipelineResult.repoPath, storagePath, (msg) => { + lbugMsgCount++; + const pct = Math.min(84, 65 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 19)); + progress('lbug', pct, msg); + }); + } else { + // ── Full rebuild ─────────────────────────────────────────────── + await loadGraphToLbug(pipelineResult.graph, pipelineResult.repoPath, storagePath, (msg) => { + lbugMsgCount++; + const pct = Math.min(84, 60 + Math.round((lbugMsgCount / (lbugMsgCount + 10)) * 24)); + progress('lbug', pct, msg); + }); + } // ── Phase 3: FTS (85–90%) ───────────────────────────────────────── progress('fts', 85, 'Creating search indexes...'); @@ -310,6 +587,19 @@ export async function runFullAnalysis( progress('fts', 90, 'Search indexes ready'); // ── Phase 3.5: Re-insert cached embeddings ──────────────────────── + // Runs on BOTH the full-rebuild path and the incremental path: + // - Full rebuild: DB was wiped, every cached row needs to come back. + // - Incremental: changed-file rows were just deleted by + // deleteNodesForFile (which cascades to their + // embedding rows) — so their cached vectors need + // to come back too. Unchanged-file rows still + // exist; re-inserting their cached vectors would + // PK-conflict, but the per-batch try/catch below + // silently ignores those (matches the existing + // "some may fail if node was removed, that's + // fine" semantics). Bugbot review on PR #1479 + // flagged that gating this on `!isIncremental` + // silently lost changed-file embeddings. if (cachedEmbeddings.length > 0) { const cachedDims = cachedEmbeddings[0].embedding.length; const { EMBEDDING_DIMS } = await import('./lbug/schema.js'); @@ -456,6 +746,12 @@ export async function runFullAnalysis( const effectiveSemanticMode = semanticMode ?? (runtimeCapabilities.semanticMode === 'vector-index' ? 'vector-index' : 'exact-scan'); + + // Convert the post-run file-hash map to the on-disk Record + // shape consumed by RepoMeta.fileHashes. + const newFileHashesRecord: Record = {}; + for (const [k, v] of newFileHashes) newFileHashesRecord[k] = v; + const meta = { repoPath, lastCommit: currentCommit, @@ -485,8 +781,33 @@ export async function runFullAnalysis( reason: runtimeCapabilities.reason, }, }, + // Incremental-indexing fields. Populated for git repos so the next + // analyze run can take the incremental DB-writeback path. Setting + // incrementalInProgress to undefined explicitly clears any prior + // dirty flag (full and incremental success paths converge here). + schemaVersion: hasGitDir(repoPath) ? INCREMENTAL_SCHEMA_VERSION : undefined, + fileHashes: hasGitDir(repoPath) ? newFileHashesRecord : undefined, + incrementalInProgress: undefined as { startedAt: number; toWriteCount: number } | undefined, }; await saveMeta(storagePath, meta); + + // Persist the incremental parse cache for the next run. Wraps in + // try/catch so a cache-write failure never breaks an otherwise + // successful indexing run. Prune stale chunk-hash entries first so + // the cache file size stays bounded across runs (chunks whose + // composition no longer matches anything in the current scan are + // dead weight; the parse phase populates `usedKeys` as it processes + // chunks). + try { + const pruned = pruneCache(parseCache, parseCache.usedKeys); + if (pruned > 0) { + log(`Parse cache: pruned ${pruned} stale chunk entries`); + } + await saveParseCache(storagePath, parseCache); + } catch (e) { + log(`Warning: could not save parse cache (${(e as Error).message}); continuing.`); + } + // Forward the --name alias and the registry-collision bypass bit. // `allowDuplicateName` is its own concern — independent from the // pipeline `force` above. The CLI maps it from diff --git a/gitnexus/src/storage/file-hash.ts b/gitnexus/src/storage/file-hash.ts new file mode 100644 index 000000000..b39111815 --- /dev/null +++ b/gitnexus/src/storage/file-hash.ts @@ -0,0 +1,104 @@ +/** + * Per-file content hashing for incremental DB writeback. + * + * On every analyze run we compute SHA-256 of every file's content and + * store the map in meta.json. The next run compares disk against the + * stored map and produces: + * - `changed` — content differs (re-emit DB rows for this file) + * - `added` — file is new on disk (insert DB rows) + * - `deleted` — file was in last meta but no longer on disk (drop rows) + * + * The pipeline still parses every file (correctness invariant: cross-file + * resolution needs full data). What this enables is a SELECTIVE DB + * writeback: instead of wipe-and-reload of the whole graph (~50s of CSV + * COPY on a 25K-node repo), we only delete-and-rewrite rows for the + * changed/added/deleted set. + * + * See docs/superpowers/specs/2026-05-10-incremental-indexing-design.md + * (Option B revision). + */ + +import { createHash } from 'crypto'; +import fs from 'fs/promises'; +import path from 'path'; + +/** + * Compute SHA-256 of a single file. Returns null when the file can't be + * read — caller treats that as "no signature, assume changed". + */ +export const computeFileHash = async (absPath: string): Promise => { + try { + const buf = await fs.readFile(absPath); + return createHash('sha256').update(buf).digest('hex'); + } catch { + return null; + } +}; + +/** + * Compute SHA-256 hashes for many files in parallel batches. Files that + * fail to read are omitted from the result map. + */ +export const computeFileHashes = async ( + repoPath: string, + relPaths: readonly string[], +): Promise> => { + const out = new Map(); + const BATCH = 100; + for (let i = 0; i < relPaths.length; i += BATCH) { + const batch = relPaths.slice(i, i + BATCH); + const results = await Promise.all( + batch.map(async (rel) => { + const h = await computeFileHash(path.join(repoPath, rel)); + return h ? ([rel, h] as const) : null; + }), + ); + for (const r of results) if (r) out.set(r[0], r[1]); + } + return out; +}; + +/** Result of comparing the current on-disk hashes against stored ones. */ +export interface FileHashDiff { + /** Files whose content hash differs from stored. */ + changed: string[]; + /** Files in the current scan that weren't in the stored map. */ + added: string[]; + /** Files in the stored map that aren't in the current scan. */ + deleted: string[]; + /** All files whose DB rows must be replaced (changed ∪ added). */ + toWrite: string[]; +} + +/** + * Diff a current hash map against a previously stored one. + * + * Sorted output so two runs produce identical diff arrays for the same + * changes — useful for stable logging / equivalence checks. + */ +export const diffFileHashes = ( + current: ReadonlyMap, + stored: Readonly> | undefined, +): FileHashDiff => { + const storedMap = new Map(stored ? Object.entries(stored) : []); + const changed: string[] = []; + const added: string[] = []; + for (const [p, h] of current) { + const prev = storedMap.get(p); + if (prev === undefined) added.push(p); + else if (prev !== h) changed.push(p); + } + const deleted: string[] = []; + for (const p of storedMap.keys()) { + if (!current.has(p)) deleted.push(p); + } + changed.sort(); + added.sort(); + deleted.sort(); + return { + changed, + added, + deleted, + toWrite: [...changed, ...added].sort(), + }; +}; diff --git a/gitnexus/src/storage/parse-cache.ts b/gitnexus/src/storage/parse-cache.ts new file mode 100644 index 000000000..a1abf76fa --- /dev/null +++ b/gitnexus/src/storage/parse-cache.ts @@ -0,0 +1,213 @@ +/** + * Chunk-level content-addressed parse cache. + * + * The pipeline always parses every file (correctness invariant: cross-file + * resolution and downstream phases need full graph data). What this cache + * does is skip the tree-sitter worker dispatch when a chunk's contents + * haven't changed since the last run. + * + * Granularity: chunk-level. The parse phase chunks files into ~20MB byte + * budgets. The cache key is `sha256(joined(filePath:contentHash for each + * file in the chunk, sorted))`. A change to a single file invalidates only + * that file's chunk — typically 1 of ~50 chunks on a 1000-file repo. + * + * Why not per-file: + * - Workers process sub-batches and emit aggregated `ParseWorkerResult`s. + * Splitting back to per-file would require reworking the worker contract. + * - Chunk-level invalidation gives a useful speedup floor (98% on a single + * 1-of-50 invalidated chunk) without touching the worker. + * + * Survives `--force` because it's content-addressed: the same bytes always + * produce the same key. `--force` only matters for the LadybugDB writeback; + * the cache itself is always safe to reuse. + */ + +import { createHash } from 'crypto'; +import { createRequire } from 'module'; +import fs from 'fs/promises'; +import path from 'path'; +import { fileURLToPath } from 'url'; +import type { ParseWorkerResult } from '../core/ingestion/workers/parse-worker.js'; + +/** + * Cache version composed of: + * - A schema bump knob (`SCHEMA_BUMP`) for hand-controlled invalidation + * when ParseWorkerResult shape or upstream parse semantics change. + * - The current `gitnexus` npm package version, read at module load. + * Any release that ships an updated tree-sitter grammar or revised + * extractor logic implies a version bump in package.json, which + * automatically invalidates the on-disk cache. Without this, a user + * running `npm i -g gitnexus@latest` after a parser-affecting + * release would silently replay pre-upgrade ParseWorkerResults + * against the new graph schema (Bugbot/Claude review on #1479). + * + * On version mismatch, `loadParseCache` returns an empty cache and the + * next save overwrites the on-disk file with the new version baked in. + */ +const SCHEMA_BUMP = 1; +const GITNEXUS_PKG_VERSION = (() => { + try { + // package.json sits at gitnexus/package.json — two levels up from + // gitnexus/src/storage/parse-cache.ts (or its dist/ equivalent). + const here = path.dirname(fileURLToPath(import.meta.url)); + const candidates = [ + path.join(here, '..', '..', 'package.json'), // src/storage → gitnexus/ + path.join(here, '..', '..', '..', 'package.json'), // dist/storage → gitnexus/ + ]; + const requireCJS = createRequire(import.meta.url); + for (const c of candidates) { + try { + const pkg = requireCJS(c); + if (typeof pkg?.version === 'string') return pkg.version; + } catch { + /* try next candidate */ + } + } + } catch { + /* fall through to fallback */ + } + return '0.0.0-unknown'; +})(); +export const PARSE_CACHE_VERSION = `${SCHEMA_BUMP}+${GITNEXUS_PKG_VERSION}`; + +const CACHE_FILENAME = 'parse-cache.json'; + +/** On-disk shape. */ +interface ParseCacheFile { + version: string; + /** key = chunk hash (hex) → cached chunk result list. */ + entries: Record; +} + +/** Runtime view: keyed Map for fast lookup; mutated in place during a run. */ +export interface ParseCache { + version: string; + entries: Map; + /** + * Hashes referenced (hit OR miss-and-stored) by the current run. + * The parse phase populates this as it processes chunks; the orchestrator + * uses it as input to `pruneCache` before saving so entries that no + * longer correspond to any chunk in the current scan are discarded. + * Transient — never serialized to disk. + */ + usedKeys: Set; +} + +/** SHA-256 hex of a single string or buffer. */ +const sha256Hex = (input: Buffer | string): string => + createHash('sha256') + .update(typeof input === 'string' ? Buffer.from(input) : input) + .digest('hex'); + +/** Stable hash of a single file's contents — used by callers to compose a chunk hash. */ +export const fileContentHash = (content: Buffer | string): string => sha256Hex(content); + +/** + * Compute the canonical cache key for a chunk's contents. + * + * `entries` is the list of (filePath, file content hash) for every file + * in the chunk. We sort by filePath before hashing so chunks composed of + * the same files in different order produce the same key. + */ +export const computeChunkHash = ( + entries: Array<{ filePath: string; contentHash: string }>, +): string => { + const sorted = [...entries].sort((a, b) => (a.filePath < b.filePath ? -1 : 1)); + const joined = sorted.map((e) => `${e.filePath}:${e.contentHash}`).join('\n'); + return sha256Hex(joined); +}; + +/** + * JSON replacer that round-trips Map/Set instances through plain JSON. + * + * `ParseWorkerResult.parsedFiles[*].scopes[*].typeBindings` is a + * `ReadonlyMap`; without this transform it serializes + * to `{}` and downstream code that iterates / `.get()`s on it crashes + * with "is not iterable". Applied symmetrically by `mapReviver` on + * load so the in-memory shape stays Map-typed. + */ +const MAP_TAG = '__$mapEntries$__'; +const SET_TAG = '__$setValues$__'; + +const mapReplacer = (_key: string, value: unknown): unknown => { + if (value instanceof Map) return { [MAP_TAG]: Array.from(value.entries()) }; + if (value instanceof Set) return { [SET_TAG]: Array.from(value.values()) }; + return value; +}; + +const mapReviver = (_key: string, value: unknown): unknown => { + if (value && typeof value === 'object') { + const v = value as Record; + if (Array.isArray(v[MAP_TAG])) return new Map(v[MAP_TAG] as [unknown, unknown][]); + if (Array.isArray(v[SET_TAG])) return new Set(v[SET_TAG] as unknown[]); + } + return value; +}; + +/** + * Load the parse cache. Returns an empty cache on any failure (missing + * file, corrupt JSON, version mismatch). Never throws on a normal load. + */ +export const loadParseCache = async (storagePath: string): Promise => { + const cachePath = path.join(storagePath, CACHE_FILENAME); + try { + const raw = await fs.readFile(cachePath, 'utf-8'); + const data = JSON.parse(raw, mapReviver) as ParseCacheFile; + if ( + typeof data !== 'object' || + data === null || + data.version !== PARSE_CACHE_VERSION || + typeof data.entries !== 'object' || + data.entries === null + ) { + return emptyCache(); + } + const entries = new Map(); + for (const [k, v] of Object.entries(data.entries)) { + if (Array.isArray(v)) entries.set(k, v as ParseWorkerResult[]); + } + return { version: PARSE_CACHE_VERSION, entries, usedKeys: new Set() }; + } catch { + return emptyCache(); + } +}; + +/** + * Persist the cache to disk atomically (write-and-rename) so a crash + * mid-write doesn't leave a corrupt file. + */ +export const saveParseCache = async (storagePath: string, cache: ParseCache): Promise => { + await fs.mkdir(storagePath, { recursive: true }); + const cachePath = path.join(storagePath, CACHE_FILENAME); + const tmpPath = `${cachePath}.tmp`; + const out: ParseCacheFile = { + version: cache.version, + entries: Object.fromEntries(cache.entries), + }; + // Compact JSON; this file can be tens of MB on a large repo and pretty- + // printing roughly doubles size for no value. + await fs.writeFile(tmpPath, JSON.stringify(out, mapReplacer), 'utf-8'); + await fs.rename(tmpPath, cachePath); +}; + +/** + * Drop entries whose hashes are not in `usedHashes`. Called at the end + * of a run so chunks that no longer correspond to any current chunk + * don't keep their stale entries forever. + */ +export const pruneCache = (cache: ParseCache, usedHashes: ReadonlySet): number => { + let removed = 0; + for (const k of cache.entries.keys()) { + if (!usedHashes.has(k)) { + cache.entries.delete(k); + removed++; + } + } + return removed; +}; + +const emptyCache = (): ParseCache => ({ + version: PARSE_CACHE_VERSION, + entries: new Map(), + usedKeys: new Set(), +}); diff --git a/gitnexus/src/storage/repo-manager.ts b/gitnexus/src/storage/repo-manager.ts index 8c0bda95f..456a6c143 100644 --- a/gitnexus/src/storage/repo-manager.ts +++ b/gitnexus/src/storage/repo-manager.ts @@ -71,8 +71,40 @@ export interface RepoMeta { processes?: number; embeddings?: number; }; + /** + * Bumped whenever incremental-indexing invariants change in an + * incompatible way (delete-and-rewrite logic, subgraph extraction, + * graph-wide node handling). On mismatch, runFullAnalysis forces a + * full rebuild rather than risk an inconsistent incremental update. + */ + schemaVersion?: number; + /** + * SHA-256 of every file's content at the time of the last successful + * indexing run. The next run computes current hashes and diffs against + * this map to determine which files' DB rows must be replaced. + * Map keys are repo-relative paths. + */ + fileHashes?: Record; + /** + * Crash-recovery dirty flag. Written to meta.json BEFORE any + * destructive DB mutation in an incremental run; cleared on success + * by overwriting meta.json. If a run crashes between, the next run + * sees the flag and forces a full rebuild — the cheapest path back + * to a known-good index. + */ + incrementalInProgress?: { + /** When the incremental run started (epoch ms). */ + startedAt: number; + /** Number of files in the writable set, for diagnostic logs. */ + toWriteCount: number; + }; } +/** + * Bumped whenever incremental-indexing invariants change incompatibly. + */ +export const INCREMENTAL_SCHEMA_VERSION = 1; + export interface IndexedRepo { repoPath: string; storagePath: string; @@ -186,12 +218,23 @@ export const loadMeta = async (storagePath: string): Promise => }; /** - * Save metadata to storage + * Save metadata to storage. + * + * Atomic via tmp-file + rename (matches `saveParseCache`'s pattern). The + * `incrementalInProgress` dirty flag travels through this file — a crash + * mid-write would leave a corrupt `meta.json` that the next run's + * `loadMeta` would silently treat as "no prior index", losing the dirty + * flag and skipping the recovery full-rebuild. Write-and-rename rules + * that out: the rename is atomic on POSIX and on Windows (`fs.rename` + * on `node:fs/promises` uses `MoveFileEx(REPLACE_EXISTING)`), so either + * the old or the new file is observed at every moment. */ export const saveMeta = async (storagePath: string, meta: RepoMeta): Promise => { await fs.mkdir(storagePath, { recursive: true }); const metaPath = path.join(storagePath, 'meta.json'); - await fs.writeFile(metaPath, JSON.stringify(meta, null, 2), 'utf-8'); + const tmpPath = `${metaPath}.tmp`; + await fs.writeFile(tmpPath, JSON.stringify(meta, null, 2), 'utf-8'); + await fs.rename(tmpPath, metaPath); }; /** diff --git a/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json b/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json index 0d66fd3a7..34f2a6106 100644 --- a/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json +++ b/gitnexus/test/fixtures/pipeline-golden/mini-repo/expected-graph.json @@ -25,5 +25,5 @@ "MEMBER_OF": 12, "STEP_IN_PROCESS": 12 }, - "edgeDigest": "a418debec537cf959fe56fd1fbbbfb59a640398cdb3c61ce0bcb8056c1f45110" + "edgeDigest": "6f414427a20c037df3e336f055c83f987e7d381c9bfa73b4d2be690cb8103302" } diff --git a/gitnexus/test/unit/incremental-file-hash.test.ts b/gitnexus/test/unit/incremental-file-hash.test.ts new file mode 100644 index 000000000..0f59dfb09 --- /dev/null +++ b/gitnexus/test/unit/incremental-file-hash.test.ts @@ -0,0 +1,124 @@ +import { describe, it, expect } from 'vitest'; +import { mkdtemp, writeFile, rm } from 'fs/promises'; +import { tmpdir } from 'os'; +import path from 'path'; +import { computeFileHash, computeFileHashes, diffFileHashes } from '../../src/storage/file-hash.js'; + +describe('diffFileHashes', () => { + it('classifies files into changed / added / deleted / toWrite', () => { + const stored = { a: 'h-a', b: 'h-b', c: 'h-c' }; + const current = new Map([ + ['a', 'h-a'], // unchanged + ['b', 'h-b-NEW'], // changed + ['d', 'h-d'], // added + // 'c' is gone → deleted + ]); + const diff = diffFileHashes(current, stored); + expect(diff.changed).toEqual(['b']); + expect(diff.added).toEqual(['d']); + expect(diff.deleted).toEqual(['c']); + // toWrite is the union of changed ∪ added (rows to be (re)written) + expect(diff.toWrite.sort()).toEqual(['b', 'd']); + }); + + it('treats no stored map as "everything is added"', () => { + const current = new Map([ + ['x', 'h1'], + ['y', 'h2'], + ]); + const diff = diffFileHashes(current, undefined); + expect(diff.added.sort()).toEqual(['x', 'y']); + expect(diff.changed).toEqual([]); + expect(diff.deleted).toEqual([]); + expect(diff.toWrite.sort()).toEqual(['x', 'y']); + }); + + it('returns sorted arrays for stable cross-platform comparison', () => { + const stored = { z: 'h', a: 'h', m: 'h' }; + const current = new Map([ + ['z', 'h2'], + ['a', 'h2'], + ['m', 'h2'], + ]); + const diff = diffFileHashes(current, stored); + expect(diff.changed).toEqual(['a', 'm', 'z']); + expect(diff.toWrite).toEqual(['a', 'm', 'z']); + }); + + it('handles empty current map (all stored files become deleted)', () => { + const stored = { a: 'h1', b: 'h2' }; + const diff = diffFileHashes(new Map(), stored); + expect(diff.deleted).toEqual(['a', 'b']); + expect(diff.changed).toEqual([]); + expect(diff.added).toEqual([]); + }); +}); + +describe('computeFileHash', () => { + it('produces a stable SHA-256 hex digest', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-fh-')); + try { + const f = path.join(dir, 'a.txt'); + await writeFile(f, 'hello world\n', 'utf-8'); + const h1 = await computeFileHash(f); + const h2 = await computeFileHash(f); + expect(h1).toBe(h2); + expect(h1).toMatch(/^[a-f0-9]{64}$/); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('returns null on missing file (caller treats as "no signature")', async () => { + const h = await computeFileHash('/definitely/does/not/exist/here.xyz'); + expect(h).toBeNull(); + }); + + it('different content → different hash', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-fh-')); + try { + const a = path.join(dir, 'a.txt'); + const b = path.join(dir, 'b.txt'); + await writeFile(a, 'hello', 'utf-8'); + await writeFile(b, 'goodbye', 'utf-8'); + const ha = await computeFileHash(a); + const hb = await computeFileHash(b); + expect(ha).not.toBeNull(); + expect(hb).not.toBeNull(); + expect(ha).not.toBe(hb); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); +}); + +describe('computeFileHashes', () => { + it('hashes a small batch of files in parallel', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-fh-')); + try { + await writeFile(path.join(dir, 'one.txt'), 'A', 'utf-8'); + await writeFile(path.join(dir, 'two.txt'), 'B', 'utf-8'); + await writeFile(path.join(dir, 'three.txt'), 'C', 'utf-8'); + const map = await computeFileHashes(dir, ['one.txt', 'two.txt', 'three.txt']); + expect(map.size).toBe(3); + expect(map.get('one.txt')).toMatch(/^[a-f0-9]{64}$/); + // All distinct since contents differ + const hashes = [...map.values()]; + expect(new Set(hashes).size).toBe(3); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('omits files that fail to read (no entry in result)', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-fh-')); + try { + await writeFile(path.join(dir, 'real.txt'), 'X', 'utf-8'); + const map = await computeFileHashes(dir, ['real.txt', 'phantom.txt']); + expect(map.has('real.txt')).toBe(true); + expect(map.has('phantom.txt')).toBe(false); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/gitnexus/test/unit/incremental-orchestration.test.ts b/gitnexus/test/unit/incremental-orchestration.test.ts new file mode 100644 index 000000000..3d0d244af --- /dev/null +++ b/gitnexus/test/unit/incremental-orchestration.test.ts @@ -0,0 +1,263 @@ +/** + * Integration coverage for the `runFullAnalysis` incremental-orchestration + * wiring (Claude PR-review Finding 2). + * + * These tests exercise the *real runtime path* — they call + * `runFullAnalysis` against a real on-disk git repo backed by a real + * LadybugDB at `/.gitnexus/`, and assert behaviours that pure + * unit tests on `diffFileHashes` / `extractChangedSubgraph` cannot + * catch: + * + * - the `isIncremental` decision (post-pipeline eligibility check) + * - `incrementalInProgress` dirty-flag set-before-mutation and + * clear-on-success + * - the importer-closure expansion (1-hop reached via the writable + * set, transitive reachable via bounded BFS) + * - the "forced full rebuild on dirty-flag-from-prior-crash" path + * + * Each test creates a temporary git repo, runs the analyzer, and asserts + * on the resulting `meta.json` and graph state. Cleanup is best-effort + * (Windows LadybugDB handle release can lag; `cleanupTempDir` retries). + */ + +import { execSync } from 'child_process'; +import { writeFile, readFile, copyFile, mkdir } from 'fs/promises'; +import path from 'path'; +import { fileURLToPath } from 'url'; +import { describe, it, expect } from 'vitest'; +import { + getStoragePaths, + saveMeta, + loadMeta, + INCREMENTAL_SCHEMA_VERSION, + type RepoMeta, +} from '../../src/storage/repo-manager.js'; +import { createTempDir } from '../helpers/test-db.js'; + +const HERE = path.dirname(fileURLToPath(import.meta.url)); +const FIXTURE_SRC = path.resolve(HERE, '..', 'fixtures', 'mini-repo', 'src'); + +/** + * Copy the mini-repo fixture into a fresh git-initialized temp directory. + * Returns the temp handle so the caller owns cleanup. + */ +async function setupMiniRepo(): Promise<{ dbPath: string; cleanup: () => Promise }> { + const tmp = await createTempDir('gitnexus-incr-orch-'); + const dest = path.join(tmp.dbPath, 'src'); + await mkdir(dest, { recursive: true }); + // Copy mini-repo fixture files + const names = [ + 'index.ts', + 'handler.ts', + 'validator.ts', + 'formatter.ts', + 'middleware.ts', + 'logger.ts', + 'db.ts', + ]; + for (const n of names) { + await copyFile(path.join(FIXTURE_SRC, n), path.join(dest, n)); + } + execSync('git init', { cwd: tmp.dbPath, stdio: 'pipe' }); + execSync('git -c user.name=test -c user.email=t@t -c commit.gpgsign=false add -A', { + cwd: tmp.dbPath, + stdio: 'pipe', + }); + execSync('git -c user.name=test -c user.email=t@t -c commit.gpgsign=false commit -q -m initial', { + cwd: tmp.dbPath, + stdio: 'pipe', + }); + return tmp; +} + +describe('runFullAnalysis — incremental orchestration', () => { + it('first run populates fileHashes + schemaVersion and clears incrementalInProgress on success', async () => { + const repo = await setupMiniRepo(); + try { + const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); + await runFullAnalysis(repo.dbPath, { skipAgentsMd: true }, { onProgress: () => {} }); + + const { storagePath } = getStoragePaths(repo.dbPath); + const meta = await loadMeta(storagePath); + expect(meta).not.toBeNull(); + expect(meta!.schemaVersion).toBe(INCREMENTAL_SCHEMA_VERSION); + expect(meta!.fileHashes).toBeDefined(); + expect(Object.keys(meta!.fileHashes ?? {}).length).toBeGreaterThan(0); + // Dirty flag MUST be cleared after a successful run. + expect(meta!.incrementalInProgress).toBeUndefined(); + } finally { + await repo.cleanup(); + } + }, 180_000); + + it('second run on unchanged state takes the alreadyUpToDate fast path', async () => { + const repo = await setupMiniRepo(); + try { + const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); + const first = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true }, + { onProgress: () => {} }, + ); + expect(first.alreadyUpToDate).toBeUndefined(); + + const second = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true }, + { onProgress: () => {} }, + ); + // lastCommit==HEAD && working tree clean (mod GitNexus output) → + // early-return fast path. + expect(second.alreadyUpToDate).toBe(true); + } finally { + await repo.cleanup(); + } + }, 300_000); + + it('second run after a comment-only edit takes the incremental path, clears the dirty flag, and preserves graph stats exactly', async () => { + const repo = await setupMiniRepo(); + try { + const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); + await runFullAnalysis(repo.dbPath, { skipAgentsMd: true }, { onProgress: () => {} }); + const { storagePath } = getStoragePaths(repo.dbPath); + const firstMeta = await loadMeta(storagePath); + + // Modify a source file with a COMMENT-ONLY edit — by construction + // this changes the content hash (driving the incremental code path) + // without changing any symbol, scope binding, call edge, import, + // or community membership. Therefore every graph-stat invariant + // (files / nodes / edges / communities / processes) MUST be + // bit-identical to the first run. Anything else is a regression. + const target = path.join(repo.dbPath, 'src', 'logger.ts'); + const before = await readFile(target, 'utf-8'); + await writeFile(target, before + '\n// touched by test\n', 'utf-8'); + + const second = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true }, + { onProgress: () => {} }, + ); + // The early-return alreadyUpToDate path must NOT fire (the dirty + // tree should kick the run through to incremental writeback). + expect(second.alreadyUpToDate).toBeUndefined(); + + const secondMeta = await loadMeta(storagePath); + expect(secondMeta).not.toBeNull(); + // Dirty flag must be cleared on success. + expect(secondMeta!.incrementalInProgress).toBeUndefined(); + // fileHashes[logger.ts] must have rotated to the new content. + expect(secondMeta!.fileHashes?.['src/logger.ts']).toBeDefined(); + expect(secondMeta!.fileHashes?.['src/logger.ts']).not.toBe( + firstMeta!.fileHashes?.['src/logger.ts'], + ); + // Exact-equality stats invariant. DoD §2.7: avoid bounds-only + // assertions that would mask a regression dropping half the graph. + expect(secondMeta!.stats?.files).toBe(firstMeta!.stats?.files); + expect(secondMeta!.stats?.nodes).toBe(firstMeta!.stats?.nodes); + expect(secondMeta!.stats?.edges).toBe(firstMeta!.stats?.edges); + expect(secondMeta!.stats?.communities).toBe(firstMeta!.stats?.communities); + expect(secondMeta!.stats?.processes).toBe(firstMeta!.stats?.processes); + } finally { + await repo.cleanup(); + } + }, 300_000); + + it('incremental output is byte-equivalent to a full rebuild (incremental ≡ --force on the same repo state)', async () => { + // The central correctness contract of this PR: an incremental run + // and a full rebuild from the same repo state must produce identical + // graph stats. We exercise it end-to-end: + // + // 1. setup mini-repo + run analyze (populates the index) + // 2. edit one source file (comment-only — same graph) + // 3. run incremental analyze → record secondMeta + // 4. run analyze --force from the same state → record forceMeta + // 5. assert every stats invariant is exactly equal. + // + // Steps 3 and 4 share the same on-disk file contents, so any + // divergence is purely an artifact of the writeback strategy. If + // any invariant differs, the PR's load-bearing claim is violated. + const repo = await setupMiniRepo(); + try { + const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); + + // Step 1: initial index. + await runFullAnalysis(repo.dbPath, { skipAgentsMd: true }, { onProgress: () => {} }); + + // Step 2: comment-only edit, same as the test above. + const target = path.join(repo.dbPath, 'src', 'logger.ts'); + const original = await readFile(target, 'utf-8'); + await writeFile(target, original + '\n// equivalence test touch\n', 'utf-8'); + + // Step 3: incremental writeback for the edited file. + const incremental = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true }, + { onProgress: () => {} }, + ); + expect(incremental.alreadyUpToDate).toBeUndefined(); + const { storagePath } = getStoragePaths(repo.dbPath); + const secondMeta = await loadMeta(storagePath); + expect(secondMeta).not.toBeNull(); + + // Step 4: force a full rebuild from the SAME on-disk file state. + const forced = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true, force: true }, + { onProgress: () => {} }, + ); + expect(forced.alreadyUpToDate).toBeUndefined(); + const forceMeta = await loadMeta(storagePath); + expect(forceMeta).not.toBeNull(); + + // Step 5: exact-equality across every stat. `toEqual` would also + // work but `toBe` per-field makes a failure pinpoint the field. + expect(secondMeta!.stats?.files).toBe(forceMeta!.stats?.files); + expect(secondMeta!.stats?.nodes).toBe(forceMeta!.stats?.nodes); + expect(secondMeta!.stats?.edges).toBe(forceMeta!.stats?.edges); + expect(secondMeta!.stats?.communities).toBe(forceMeta!.stats?.communities); + expect(secondMeta!.stats?.processes).toBe(forceMeta!.stats?.processes); + } finally { + await repo.cleanup(); + } + }, 600_000); + + it('a stale incrementalInProgress flag at startup forces a full rebuild that clears it', async () => { + const repo = await setupMiniRepo(); + try { + const { runFullAnalysis } = await import('../../src/core/run-analyze.js'); + // First run lays down a normal index. + await runFullAnalysis(repo.dbPath, { skipAgentsMd: true }, { onProgress: () => {} }); + + // Manually corrupt meta.json with a stale dirty flag — simulates + // a crashed previous incremental run. + const { storagePath } = getStoragePaths(repo.dbPath); + const meta = await loadMeta(storagePath); + expect(meta).not.toBeNull(); + const tampered: RepoMeta = { + ...meta!, + incrementalInProgress: { + startedAt: Date.now() - 60_000, + toWriteCount: 3, + }, + }; + await saveMeta(storagePath, tampered); + + // Next run must detect the flag, force a full rebuild (which + // overwrites meta), and clear the flag. + const recovered = await runFullAnalysis( + repo.dbPath, + { skipAgentsMd: true }, + { onProgress: () => {} }, + ); + // A full rebuild was taken — the alreadyUpToDate fast path + // explicitly cannot fire because the dirty-flag check rewrote + // `options.force` to true. + expect(recovered.alreadyUpToDate).toBeUndefined(); + + const after = await loadMeta(storagePath); + expect(after!.incrementalInProgress).toBeUndefined(); + } finally { + await repo.cleanup(); + } + }, 300_000); +}); diff --git a/gitnexus/test/unit/incremental-parse-cache.test.ts b/gitnexus/test/unit/incremental-parse-cache.test.ts new file mode 100644 index 000000000..757b9cf3a --- /dev/null +++ b/gitnexus/test/unit/incremental-parse-cache.test.ts @@ -0,0 +1,243 @@ +import { describe, it, expect } from 'vitest'; +import { mkdtemp, rm } from 'fs/promises'; +import { tmpdir } from 'os'; +import path from 'path'; +import { + PARSE_CACHE_VERSION, + computeChunkHash, + fileContentHash, + loadParseCache, + saveParseCache, + pruneCache, + type ParseCache, +} from '../../src/storage/parse-cache.js'; +import type { ParseWorkerResult } from '../../src/core/ingestion/workers/parse-worker.js'; + +const minimalResult = (overrides: Partial = {}): ParseWorkerResult => ({ + nodes: [], + relationships: [], + symbols: [], + imports: [], + calls: [], + assignments: [], + heritage: [], + routes: [], + fetchCalls: [], + decoratorRoutes: [], + toolDefs: [], + ormQueries: [], + constructorBindings: [], + fileScopeBindings: [], + parsedFiles: [], + skippedLanguages: {}, + fileCount: 0, + ...overrides, +}); + +describe('computeChunkHash', () => { + it('produces a stable hex hash for a fixed set of (filePath, contentHash) entries', () => { + const entries = [ + { filePath: 'a.ts', contentHash: 'h-a' }, + { filePath: 'b.ts', contentHash: 'h-b' }, + { filePath: 'c.ts', contentHash: 'h-c' }, + ]; + const h1 = computeChunkHash(entries); + const h2 = computeChunkHash(entries); + expect(h1).toBe(h2); + expect(h1).toMatch(/^[a-f0-9]{64}$/); + }); + + it('is order-independent (same files in different order → same hash)', () => { + const order1 = [ + { filePath: 'a.ts', contentHash: 'h-a' }, + { filePath: 'b.ts', contentHash: 'h-b' }, + ]; + const order2 = [ + { filePath: 'b.ts', contentHash: 'h-b' }, + { filePath: 'a.ts', contentHash: 'h-a' }, + ]; + expect(computeChunkHash(order1)).toBe(computeChunkHash(order2)); + }); + + it('changes when any file content changes', () => { + const before = [ + { filePath: 'a.ts', contentHash: 'h-a' }, + { filePath: 'b.ts', contentHash: 'h-b' }, + ]; + const after = [ + { filePath: 'a.ts', contentHash: 'h-a' }, + { filePath: 'b.ts', contentHash: 'h-b-NEW' }, // b.ts content changed + ]; + expect(computeChunkHash(before)).not.toBe(computeChunkHash(after)); + }); + + it('changes when chunk membership changes (file added or removed)', () => { + const small = [ + { filePath: 'a.ts', contentHash: 'h-a' }, + { filePath: 'b.ts', contentHash: 'h-b' }, + ]; + const bigger = [...small, { filePath: 'c.ts', contentHash: 'h-c' }]; + expect(computeChunkHash(small)).not.toBe(computeChunkHash(bigger)); + }); +}); + +describe('fileContentHash', () => { + it('hashes a string deterministically', () => { + expect(fileContentHash('hello')).toBe(fileContentHash('hello')); + expect(fileContentHash('hello')).not.toBe(fileContentHash('hello!')); + expect(fileContentHash('hello')).toMatch(/^[a-f0-9]{64}$/); + }); + + it('handles Buffer input identical to its string form', () => { + const s = 'sentinel'; + expect(fileContentHash(Buffer.from(s))).toBe(fileContentHash(s)); + }); +}); + +describe('PARSE_CACHE_VERSION', () => { + it('embeds the gitnexus package version (so upgrades invalidate the cache)', () => { + // Looks like "1+1.6.4" — schema bump prefix + actual gitnexus version + expect(PARSE_CACHE_VERSION).toMatch(/^\d+\+\d+\.\d+\.\d+/); + }); +}); + +describe('pruneCache', () => { + it('drops entries whose hashes are not in the used-set', () => { + const cache: ParseCache = { + version: PARSE_CACHE_VERSION, + entries: new Map([ + ['hash-A', [minimalResult()]], + ['hash-B', [minimalResult()]], + ['hash-C', [minimalResult()]], + ]), + usedKeys: new Set(['hash-A']), + }; + const removed = pruneCache(cache, cache.usedKeys); + expect(removed).toBe(2); + expect([...cache.entries.keys()].sort()).toEqual(['hash-A']); + }); + + it('returns 0 when every entry is in use', () => { + const cache: ParseCache = { + version: PARSE_CACHE_VERSION, + entries: new Map([ + ['hash-A', [minimalResult()]], + ['hash-B', [minimalResult()]], + ]), + usedKeys: new Set(['hash-A', 'hash-B']), + }; + expect(pruneCache(cache, cache.usedKeys)).toBe(0); + expect(cache.entries.size).toBe(2); + }); +}); + +describe('loadParseCache / saveParseCache (round-trip)', () => { + it('round-trips an empty cache', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-pc-')); + try { + const cache: ParseCache = { + version: PARSE_CACHE_VERSION, + entries: new Map(), + usedKeys: new Set(), + }; + await saveParseCache(dir, cache); + const loaded = await loadParseCache(dir); + expect(loaded.version).toBe(PARSE_CACHE_VERSION); + expect(loaded.entries.size).toBe(0); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('returns an empty cache when the file is missing', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-pc-')); + try { + const loaded = await loadParseCache(dir); + expect(loaded.entries.size).toBe(0); + expect(loaded.usedKeys.size).toBe(0); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('returns an empty cache on version mismatch (next-run regen)', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-pc-')); + try { + // Write a cache file with a different version directly + const fs = await import('fs/promises'); + await fs.writeFile( + path.join(dir, 'parse-cache.json'), + JSON.stringify({ version: 'foreign-99', entries: { h: [] } }), + 'utf-8', + ); + const loaded = await loadParseCache(dir); + expect(loaded.entries.size).toBe(0); // mismatch → empty + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('returns an empty cache on corrupt JSON', async () => { + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-pc-')); + try { + const fs = await import('fs/promises'); + await fs.writeFile(path.join(dir, 'parse-cache.json'), '{not-json', 'utf-8'); + const loaded = await loadParseCache(dir); + expect(loaded.entries.size).toBe(0); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); + + it('round-trips Map and Set values through the JSON replacer/reviver', async () => { + // ParsedFile.scopes[*].typeBindings is a ReadonlyMap. + // Without the replacer/reviver pair, JSON.stringify collapses Maps to + // {} and downstream code that does .get() / iterates entries crashes + // with "is not iterable". This test pins the round-trip behaviour. + const dir = await mkdtemp(path.join(tmpdir(), 'gnx-pc-')); + try { + const innerMap = new Map([ + ['k1', 'v1'], + ['k2', 'v2'], + ]); + const innerSet = new Set(['s1', 's2']); + // Stash the live Map/Set inside a synthetic ParseWorkerResult — we + // only need the serializer to traverse them. Casting to bypass the + // strict shape isn't a problem here: this test is about JSON + // round-tripping of arbitrary nested Map/Set values, not full + // ParseWorkerResult contents. + const fake = minimalResult({ + parsedFiles: [ + { + filePath: 't.ts', + // Cast through unknown to satisfy the readonly Scope shape + // while still smuggling a live Map into the serializer's + // traversal path — see comment block above. + scopes: [{ id: 's1', typeBindings: innerMap, extras: innerSet }], + } as unknown as ParseWorkerResult['parsedFiles'][number], + ], + }); + + const cache: ParseCache = { + version: PARSE_CACHE_VERSION, + entries: new Map([['chunk-h', [fake]]]), + usedKeys: new Set(['chunk-h']), + }; + await saveParseCache(dir, cache); + const loaded = await loadParseCache(dir); + const reloaded = loaded.entries.get('chunk-h')?.[0]; + expect(reloaded).toBeDefined(); + const scope = (reloaded as ParseWorkerResult).parsedFiles[0]?.scopes[0] as unknown as { + typeBindings?: unknown; + extras?: unknown; + }; + expect(scope.typeBindings).toBeInstanceOf(Map); + expect((scope.typeBindings as Map).get('k1')).toBe('v1'); + expect((scope.typeBindings as Map).size).toBe(2); + expect(scope.extras).toBeInstanceOf(Set); + expect((scope.extras as Set).has('s2')).toBe(true); + } finally { + await rm(dir, { recursive: true, force: true }); + } + }); +}); diff --git a/gitnexus/test/unit/incremental-shadow-candidates.test.ts b/gitnexus/test/unit/incremental-shadow-candidates.test.ts new file mode 100644 index 000000000..207cc0b3c --- /dev/null +++ b/gitnexus/test/unit/incremental-shadow-candidates.test.ts @@ -0,0 +1,75 @@ +import { describe, it, expect } from 'vitest'; +import { shadowCandidatesFor } from '../../src/core/incremental/shadow-candidates.js'; + +describe('shadowCandidatesFor', () => { + it('returns an empty list when the input has no recognised module extension', () => { + expect(shadowCandidatesFor('README.md')).toEqual([]); + expect(shadowCandidatesFor('src/foo')).toEqual([]); + expect(shadowCandidatesFor('binary.so')).toEqual([]); + }); + + it('enumerates same-basename / different-extension candidates (pattern a)', () => { + const out = shadowCandidatesFor('src/foo/bar.ts'); + // All non-.ts module extensions on the same path should appear. + expect(out).toContain('src/foo/bar.tsx'); + expect(out).toContain('src/foo/bar.js'); + expect(out).toContain('src/foo/bar.jsx'); + expect(out).toContain('src/foo/bar.mjs'); + expect(out).toContain('src/foo/bar.cjs'); + expect(out).toContain('src/foo/bar.d.ts'); + // ...but NOT the same .ts (you can't shadow yourself). + expect(out).not.toContain('src/foo/bar.ts'); + }); + + it('enumerates directory-style index candidates (pattern b) for both path separators', () => { + const out = shadowCandidatesFor('src/foo/bar.ts'); + // POSIX form + expect(out).toContain('src/foo/bar/index.ts'); + expect(out).toContain('src/foo/bar/index.tsx'); + expect(out).toContain('src/foo/bar/index.js'); + // Windows form + expect(out).toContain('src/foo/bar\\index.ts'); + expect(out).toContain('src/foo/bar\\index.js'); + }); + + it('enumerates bare-file shadows when the added file is a directory index (pattern c)', () => { + const out = shadowCandidatesFor('src/foo/index.ts'); + // Adding foo/index.ts can shadow foo.{ext} (rare but real — converting + // a single-file module into a directory module). + expect(out).toContain('src/foo.ts'); + expect(out).toContain('src/foo.tsx'); + expect(out).toContain('src/foo.js'); + expect(out).toContain('src/foo.jsx'); + expect(out).toContain('src/foo.mjs'); + expect(out).toContain('src/foo.cjs'); + }); + + it('also handles the Windows-separator form of `foo\\index.ts`', () => { + const out = shadowCandidatesFor('src\\foo\\index.ts'); + expect(out).toContain('src\\foo.ts'); + expect(out).toContain('src\\foo.tsx'); + expect(out).toContain('src\\foo.js'); + }); + + it('handles `.d.ts` as a single extension token (not `.ts`)', () => { + // The longest-match scan in shadowCandidatesFor puts `.d.ts` first. + // For `foo.d.ts`, the noExt portion is "foo" (not "foo.d"), so the + // pattern (a) candidates should be the non-.d.ts module variants. + const out = shadowCandidatesFor('types/foo.d.ts'); + expect(out).toContain('types/foo.ts'); + expect(out).toContain('types/foo.tsx'); + expect(out).toContain('types/foo.js'); + // Not the .d.ts itself. + expect(out).not.toContain('types/foo.d.ts'); + }); + + it('deduplicates output (no candidate appears twice)', () => { + const out = shadowCandidatesFor('src/foo/bar.ts'); + expect(out.length).toBe(new Set(out).size); + }); + + it('never includes the input path itself', () => { + const input = 'src/foo/bar.ts'; + expect(shadowCandidatesFor(input)).not.toContain(input); + }); +}); diff --git a/gitnexus/test/unit/incremental-subgraph-extract.test.ts b/gitnexus/test/unit/incremental-subgraph-extract.test.ts new file mode 100644 index 000000000..dc720fd9e --- /dev/null +++ b/gitnexus/test/unit/incremental-subgraph-extract.test.ts @@ -0,0 +1,169 @@ +/** + * Tests for incremental DB writeback subgraph extraction. + * + * Locks the Finding 1 fix (PR #1479 review): cross-file edges between + * two unchanged files MUST land in the writeback subgraph when a third + * (changed) file alters their cross-file resolution. The pre-fix + * behaviour silently dropped those edges, leaving stale rows in the DB. + * + * These tests use synthetic graphs constructed via createKnowledgeGraph + * directly — they don't run the parser, so they're cheap and stable. + */ + +import { describe, it, expect } from 'vitest'; +import type { GraphNode, GraphRelationship } from 'gitnexus-shared'; +import { createKnowledgeGraph } from '../../src/core/graph/graph.js'; +import { + extractChangedSubgraph, + computeEffectiveWriteSet, +} from '../../src/core/incremental/subgraph-extract.js'; + +const makeFileNode = (id: string, filePath: string, label = 'Function'): GraphNode => + ({ + id, + label, + properties: { filePath, name: id }, + }) as unknown as GraphNode; + +const makeWideNode = (id: string, label: 'Community' | 'Process'): GraphNode => + ({ + id, + label, + properties: {}, + }) as unknown as GraphNode; + +const makeRel = ( + id: string, + sourceId: string, + targetId: string, + type = 'CALLS', +): GraphRelationship => + ({ + id, + sourceId, + targetId, + type, + properties: {}, + }) as unknown as GraphRelationship; + +describe('extractChangedSubgraph', () => { + it('includes nodes whose filePath is in the explicit toWriteSet', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a', '/repo/a.ts')); + g.addNode(makeFileNode('c', '/repo/c.ts')); + + const sub = extractChangedSubgraph(g, new Set(['/repo/c.ts'])); + + expect(sub.nodes.map((n) => n.id).sort()).toEqual(['c']); + }); + + it('always includes graph-wide nodes (Community, Process)', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a', '/repo/a.ts')); + g.addNode(makeWideNode('comm-1', 'Community')); + g.addNode(makeWideNode('proc-1', 'Process')); + + const sub = extractChangedSubgraph(g, new Set([])); // no files changed + + expect(sub.nodes.map((n) => n.id).sort()).toEqual(['comm-1', 'proc-1']); + }); + + it('includes a relationship when at least one endpoint is writable', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a:fn', '/repo/a.ts')); + g.addNode(makeFileNode('c:fn', '/repo/c.ts')); + g.addRelationship(makeRel('e1', 'a:fn', 'c:fn', 'CALLS')); + + // toWriteSet already includes A (the orchestrator expanded it via + // computeEffectiveWriteSet) — both endpoints writable, edge fires. + const sub = extractChangedSubgraph(g, new Set(['/repo/a.ts', '/repo/c.ts'])); + + expect(sub.nodes.map((n) => n.id).sort()).toEqual(['a:fn', 'c:fn']); + expect(sub.relationships.map((r) => r.id)).toEqual(['e1']); + }); + + it('skips a relationship entirely between unchanged files', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('x:fn', '/repo/x.ts')); + g.addNode(makeFileNode('y:fn', '/repo/y.ts')); + g.addRelationship(makeRel('e1', 'x:fn', 'y:fn', 'CALLS')); + + const sub = extractChangedSubgraph(g, new Set(['/repo/c.ts'])); + + expect(sub.nodes).toEqual([]); + expect(sub.relationships).toEqual([]); + }); +}); + +describe('computeEffectiveWriteSet (Finding 1)', () => { + it('barrel re-export — expands the writable set to the consumer file', () => { + // Scenario: file C (a barrel) used to re-export from B; now re-exports + // from D. File A is unchanged byte-wise but its CALLS to foo() now + // resolve to D instead of B. Both A and D are unchanged at the file + // level — but A's edges have shifted. + // + // Pre-fix: toWriteSet={C} → A's nodes not deleted, A→D edge not + // inserted (neither endpoint writable). DB ends up with + // stale A→B and missing A→D. + // Post-fix: the new graph has A→C (A still imports the barrel), so + // A crosses the writable boundary and joins the effective + // write set. deleteNodesForFile(A) then clears the stale + // rows and the subgraph carries the new A→D edge. + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a:fn', '/repo/a.ts')); + g.addNode(makeFileNode('b:fn', '/repo/b.ts')); + g.addNode(makeFileNode('c:re-export', '/repo/c.ts')); + g.addNode(makeFileNode('d:fn', '/repo/d.ts')); + g.addRelationship(makeRel('e1', 'a:fn', 'c:re-export', 'IMPORTS')); + g.addRelationship(makeRel('e2', 'a:fn', 'd:fn', 'CALLS')); + + const effective = computeEffectiveWriteSet(g, new Set(['/repo/c.ts'])); + + expect([...effective].sort()).toEqual(['/repo/a.ts', '/repo/c.ts']); + }); + + it('picks up edges pointing INTO the changed file (symmetric case)', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('b:fn', '/repo/b.ts')); + g.addNode(makeFileNode('c:fn', '/repo/c.ts')); + g.addRelationship(makeRel('e1', 'b:fn', 'c:fn', 'CALLS')); + + const effective = computeEffectiveWriteSet(g, new Set(['/repo/c.ts'])); + + expect([...effective].sort()).toEqual(['/repo/b.ts', '/repo/c.ts']); + }); + + it('does not expand when no edge crosses the writable boundary', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('x:fn', '/repo/x.ts')); + g.addNode(makeFileNode('y:fn', '/repo/y.ts')); + g.addRelationship(makeRel('e1', 'x:fn', 'y:fn', 'CALLS')); + + const effective = computeEffectiveWriteSet(g, new Set(['/repo/c.ts'])); + + expect([...effective].sort()).toEqual(['/repo/c.ts']); + }); + + it('ignores edges to graph-wide nodes (no filePath)', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a:fn', '/repo/a.ts')); + g.addNode(makeWideNode('comm-1', 'Community')); + g.addRelationship(makeRel('e1', 'a:fn', 'comm-1', 'BELONGS_TO')); + + const effective = computeEffectiveWriteSet(g, new Set(['/repo/a.ts'])); + + expect([...effective].sort()).toEqual(['/repo/a.ts']); + }); + + it('does not mutate the input set', () => { + const g = createKnowledgeGraph(); + g.addNode(makeFileNode('a:fn', '/repo/a.ts')); + g.addNode(makeFileNode('c:fn', '/repo/c.ts')); + g.addRelationship(makeRel('e1', 'a:fn', 'c:fn', 'CALLS')); + + const input = new Set(['/repo/c.ts']); + computeEffectiveWriteSet(g, input); + + expect([...input]).toEqual(['/repo/c.ts']); + }); +}); From 0daae9370141f4130fdf357823794916f1896699 Mon Sep 17 00:00:00 2001 From: evolution Date: Tue, 12 May 2026 21:03:45 +0800 Subject: [PATCH 04/33] fix(lbug): drain checkpoint result before close (#1506) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(lbug): drain checkpoint result before close * test(lbug): cover checkpoint drain lifecycle * fix(lbug): close query results after reads * fix(lbug): close all stream query results * fix(lbug): harden query result cleanup --------- Co-authored-by: Gergő Magyar --- gitnexus/src/core/lbug/lbug-adapter.ts | 146 ++++-- .../lbug-close-handle-release.test.ts | 43 +- .../unit/lbug-checkpoint-lifecycle.test.ts | 420 ++++++++++++++++++ gitnexus/test/unit/lbug-checkpoint.test.ts | 8 + 4 files changed, 575 insertions(+), 42 deletions(-) create mode 100644 gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts diff --git a/gitnexus/src/core/lbug/lbug-adapter.ts b/gitnexus/src/core/lbug/lbug-adapter.ts index caa7a58a1..cf8f1cb71 100644 --- a/gitnexus/src/core/lbug/lbug-adapter.ts +++ b/gitnexus/src/core/lbug/lbug-adapter.ts @@ -218,6 +218,65 @@ const runWithSessionLock = async (operation: () => Promise): Promise => const normalizeCopyPath = (filePath: string): string => filePath.replace(/\\/g, '/'); +const closeQueryResult = async (result: lbug.QueryResult): Promise => { + try { + await result.close(); + } catch { + // Best-effort cleanup only. + } +}; + +const drainQueryResult = async ( + queryResult: lbug.QueryResult | lbug.QueryResult[], +): Promise => { + const results = Array.isArray(queryResult) ? queryResult : [queryResult]; + let firstError: unknown; + let hasError = false; + for (const result of results) { + try { + await result.getAll(); + } catch (err) { + if (!hasError) { + firstError = err; + hasError = true; + } + } finally { + await closeQueryResult(result); + } + } + if (hasError) throw firstError; +}; + +const readQueryRows = async ( + queryResult: lbug.QueryResult | lbug.QueryResult[], +): Promise => { + const results = Array.isArray(queryResult) ? queryResult : [queryResult]; + let rows: any[] = []; + let firstError: unknown; + let hasError = false; + for (let i = 0; i < results.length; i++) { + const result = results[i]; + try { + const resultRows = await result.getAll(); + if (i === 0) rows = resultRows; + } catch (err) { + if (!hasError) { + firstError = err; + hasError = true; + } + } finally { + await closeQueryResult(result); + } + } + if (hasError) throw firstError; + return rows; +}; + +const queryAndDrain = async (targetConn: lbug.Connection, cypher: string): Promise => { + const queryResult = await targetConn.query(cypher); + await drainQueryResult(queryResult); +}; + export const initLbug = async (dbPath: string) => { return runWithSessionLock(() => ensureLbugInitialized(dbPath)); }; @@ -319,7 +378,7 @@ const doInitLbug = async (dbPath: string) => { for (const schemaQuery of SCHEMA_QUERIES) { try { - await conn.query(schemaQuery); + await queryAndDrain(conn, schemaQuery); } catch (err) { const msg = err instanceof Error ? err.message : String(err); // Suppression list: @@ -384,14 +443,14 @@ export const loadGraphToLbug = async ( const copyQuery = getCopyQuery(table, normalizedPath); try { - await conn.query(copyQuery); + await queryAndDrain(conn, copyQuery); } catch (err) { try { const retryQuery = copyQuery.replace( 'auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)', ); - await conn.query(retryQuery); + await queryAndDrain(conn, retryQuery); } catch (retryErr) { const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr); throw new Error(`COPY failed for ${table}: ${retryMsg.slice(0, 200)}`); @@ -433,14 +492,14 @@ export const loadGraphToLbug = async ( } try { - await conn.query(copyQuery); + await queryAndDrain(conn, copyQuery); } catch (err) { try { const retryQuery = copyQuery.replace( 'auto_detect=false)', 'auto_detect=false, IGNORE_ERRORS=true)', ); - await conn.query(retryQuery); + await queryAndDrain(conn, retryQuery); } catch (retryErr) { const retryMsg = retryErr instanceof Error ? retryErr.message : String(retryErr); warnings.push(`${fromLabel}->${toLabel} (${rows} edges): ${retryMsg.slice(0, 80)}`); @@ -562,11 +621,14 @@ const fallbackRelationshipInserts = async ( const esc = (s: string) => s.replace(/'/g, "''").replace(/\\/g, '\\\\').replace(/\n/g, '\\n').replace(/\r/g, '\\r'); - await conn.query(` + await queryAndDrain( + conn, + ` MATCH (a:${escapeLabel(fromLabel)} {id: '${esc(fromId)}' }), (b:${escapeLabel(toLabel)} {id: '${esc(toId)}' }) CREATE (a)-[:${REL_TABLE_NAME} {type: '${esc(relType)}', confidence: ${confidence}, reason: '${esc(reason)}', step: ${step}}]->(b) - `); + `, + ); } catch { // skip } @@ -679,14 +741,14 @@ export const insertNodeToLbug = async ( if (targetDbPath) { const tempHandle = await openLbugConnection(lbug, targetDbPath); try { - await tempHandle.conn.query(query); + await queryAndDrain(tempHandle.conn, query); return true; } finally { await closeLbugConnection(tempHandle); } } else if (conn) { // Use existing persistent connection (when called from analyze) - await conn.query(query); + await queryAndDrain(conn, query); return true; } @@ -757,7 +819,7 @@ export const batchInsertNodesToLbug = async ( query = `MERGE (n:${t} {id: ${escapeValue(properties.id)}}) SET n.name = ${escapeValue(properties.name)}, n.filePath = ${escapeValue(properties.filePath)}, n.startLine = ${properties.startLine || 0}, n.endLine = ${properties.endLine || 0}, n.content = ${escapeValue(properties.content || '')}${descPart}`; } - await tempConn.query(query); + await queryAndDrain(tempConn, query); inserted++; } catch (e: any) { // Don't console.error here - it corrupts MCP JSON-RPC on stderr @@ -777,11 +839,7 @@ export const executeQuery = async (cypher: string): Promise => { } const queryResult = await conn.query(cypher); - // LadybugDB uses getAll() instead of hasNext()/getNext() - // Query returns QueryResult for single queries, QueryResult[] for multi-statement - const result = Array.isArray(queryResult) ? queryResult[0] : queryResult; - const rows = await result.getAll(); - return rows; + return await readQueryRows(queryResult); }; export const streamQuery = async ( @@ -793,8 +851,10 @@ export const streamQuery = async ( } const queryResult = await conn.query(cypher); - const result = Array.isArray(queryResult) ? queryResult[0] : queryResult; + const results = Array.isArray(queryResult) ? queryResult : [queryResult]; + const result = results[0]; let rowCount = 0; + let streamError: unknown; try { while (await result.hasNext()) { @@ -803,11 +863,14 @@ export const streamQuery = async ( rowCount++; } return rowCount; + } catch (err) { + streamError = err; + throw err; } finally { try { - await result.close(); - } catch { - // Best-effort cleanup only. + await drainQueryResult(results); + } catch (err) { + if (streamError === undefined) throw err; } } }; @@ -829,8 +892,7 @@ export const executePrepared = async ( throw new Error(`Prepare failed: ${errMsg}`); } const queryResult = await conn.execute(stmt, params); - const result = Array.isArray(queryResult) ? queryResult[0] : queryResult; - return await result.getAll(); + return await readQueryRows(queryResult); }; export const executeWithReusedStatement = async ( @@ -852,7 +914,7 @@ export const executeWithReusedStatement = async ( } try { for (const params of subBatch) { - await conn.execute(stmt, params); + await drainQueryResult(await conn.execute(stmt, params)); } } catch (e) { const msg = e instanceof Error ? e.message : String(e); @@ -874,8 +936,7 @@ export const getLbugStats = async (): Promise<{ nodes: number; edges: number }> const queryResult = await conn.query( `MATCH (n:${escapeTableName(tableName)}) RETURN count(n) AS cnt`, ); - const nodeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult; - const nodeRows = await nodeResult.getAll(); + const nodeRows = await readQueryRows(queryResult); if (nodeRows.length > 0) { totalNodes += Number(nodeRows[0]?.cnt ?? nodeRows[0]?.[0] ?? 0); } @@ -889,8 +950,7 @@ export const getLbugStats = async (): Promise<{ nodes: number; edges: number }> const queryResult = await conn.query( `MATCH ()-[r:${REL_TABLE_NAME}]->() RETURN count(r) AS cnt`, ); - const edgeResult = Array.isArray(queryResult) ? queryResult[0] : queryResult; - const edgeRows = await edgeResult.getAll(); + const edgeRows = await readQueryRows(queryResult); if (edgeRows.length > 0) { totalEdges = Number(edgeRows[0]?.cnt ?? edgeRows[0]?.[0] ?? 0); } @@ -926,8 +986,7 @@ export const loadCachedEmbeddings = async (): Promise<{ const check = await conn.query( `MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN e.nodeId AS nodeId, e.chunkIndex AS chunkIndex LIMIT 1`, ); - const checkResult = Array.isArray(check) ? check[0] : check; - await checkResult.getAll(); + await readQueryRows(check); } catch { return { embeddingNodeIds: new Set(), embeddings: [] }; } @@ -951,8 +1010,7 @@ export const loadCachedEmbeddings = async (): Promise<{ throw err; } } - const result = Array.isArray(rows) ? rows[0] : rows; - for (const row of await result.getAll()) { + for (const row of await readQueryRows(rows)) { const nodeId = String(row.nodeId ?? row[0] ?? ''); if (!nodeId) continue; embeddingNodeIds.add(nodeId); @@ -1060,7 +1118,8 @@ export const fetchExistingEmbeddingHashes = async ( export const flushWAL = async (): Promise => { if (!conn) return; try { - await conn.query('CHECKPOINT'); + const checkpointResult = await conn.query('CHECKPOINT'); + await drainQueryResult(checkpointResult); } catch { /* ignore — older LadybugDB or schemaless DB may not accept it */ } @@ -1170,13 +1229,13 @@ export const deleteNodesForFile = async ( const countResult = await targetConn!.query( `MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' RETURN count(n) AS cnt`, ); - const result = Array.isArray(countResult) ? countResult[0] : countResult; - const rows = await result.getAll(); + const rows = await readQueryRows(countResult); const count = Number(rows[0]?.cnt ?? rows[0]?.[0] ?? 0); if (count > 0) { // Delete nodes (and implicitly their relationships via DETACH) - await targetConn!.query( + await queryAndDrain( + targetConn!, `MATCH (n:${tn}) WHERE n.filePath = '${escapedPath}' DETACH DELETE n`, ); deletedNodes += count; @@ -1188,7 +1247,8 @@ export const deleteNodesForFile = async ( // Also delete any embeddings for nodes in this file try { - await targetConn!.query( + await queryAndDrain( + targetConn!, `MATCH (e:${EMBEDDING_TABLE_NAME}) WHERE e.nodeId STARTS WITH '${escapedPath}' DELETE e`, ); } catch { @@ -1303,7 +1363,7 @@ export const loadFTSExtension = async ( throw new Error('LadybugDB not initialized. Call initLbug first.'); } - const loaded = await extensionManager.ensure((sql) => c.query(sql), 'fts', 'FTS', opts); + const loaded = await extensionManager.ensure((sql) => queryAndDrain(c, sql), 'fts', 'FTS', opts); if (loaded && useModuleState) ftsLoaded = true; return loaded; }; @@ -1333,7 +1393,12 @@ export const loadVectorExtension = async ( throw new Error('LadybugDB not initialized. Call initLbug first.'); } - const loaded = await extensionManager.ensure((sql) => c.query(sql), 'VECTOR', 'VECTOR', opts); + const loaded = await extensionManager.ensure( + (sql) => queryAndDrain(c, sql), + 'VECTOR', + 'VECTOR', + opts, + ); if (loaded && useModuleState) vectorExtensionLoaded = true; return loaded; }; @@ -1365,7 +1430,7 @@ export const createFTSIndex = async ( const query = `CALL CREATE_FTS_INDEX('${tableName}', '${indexName}', [${propList}], stemmer := '${stemmer}')`; try { - await conn.query(query); + await queryAndDrain(conn, query); ensuredFTSIndexes.add(key); } catch (e: any) { if (e.message?.includes('already exists')) { @@ -1449,8 +1514,7 @@ export const queryFTS = async ( try { const queryResult = await conn.query(cypher); - const result = Array.isArray(queryResult) ? queryResult[0] : queryResult; - const rows = await result.getAll(); + const rows = await readQueryRows(queryResult); return rows.map((row: any) => { const node = row.node || row[0] || {}; @@ -1481,7 +1545,7 @@ export const dropFTSIndex = async (tableName: string, indexName: string): Promis } try { - await conn.query(`CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`); + await queryAndDrain(conn, `CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`); } catch { // Index may not exist } finally { diff --git a/gitnexus/test/integration/lbug-close-handle-release.test.ts b/gitnexus/test/integration/lbug-close-handle-release.test.ts index c0a3b8758..65a53bc7d 100644 --- a/gitnexus/test/integration/lbug-close-handle-release.test.ts +++ b/gitnexus/test/integration/lbug-close-handle-release.test.ts @@ -8,9 +8,16 @@ * absorbed by the open-time retry in `lbug-config.ts`. */ import path from 'path'; -import { describe, it } from 'vitest'; +import { describe, expect, it } from 'vitest'; import { createTempDir } from '../helpers/test-db.js'; +/** + * LadybugDB's native Windows file lock can outlive Database.close() for + * same-process close/reopen cycles. Keep true reopen coverage on POSIX and + * cover ordering deterministically in lbug-checkpoint-lifecycle.test.ts. + */ +const itLbugReopen = process.platform === 'win32' ? it.skip : it; + describe('safeClose — close + reopen does not surface lock errors', () => { it('survives 10 sequential open/close/reopen cycles on the same path', async () => { const tmp = await createTempDir('gitnexus-lbug-close-cycle-'); @@ -38,4 +45,38 @@ describe('safeClose — close + reopen does not surface lock errors', () => { await tmp.cleanup(); } }); + + itLbugReopen('flushes WAL when switching between two database paths in one process', async () => { + const repoA = await createTempDir('gitnexus-lbug-switch-a-'); + const repoB = await createTempDir('gitnexus-lbug-switch-b-'); + const dbPathA = path.join(repoA.dbPath, 'lbug'); + const dbPathB = path.join(repoB.dbPath, 'lbug'); + + try { + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + + await adapter.withLbugDb(dbPathA, async () => { + await adapter.executeQuery( + "CREATE (:File {id: 'file:a', name: 'a.ts', filePath: 'a.ts', content: 'repo a'})", + ); + }); + + await adapter.withLbugDb(dbPathB, async () => { + await adapter.executeQuery( + "CREATE (:File {id: 'file:b', name: 'b.ts', filePath: 'b.ts', content: 'repo b'})", + ); + }); + + const rows = await adapter.withLbugDb(dbPathA, async () => + adapter.executeQuery("MATCH (n:File {id: 'file:a'}) RETURN n.filePath AS filePath"), + ); + + expect(rows).toEqual([{ filePath: 'a.ts' }]); + } finally { + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.closeLbug().catch(() => {}); + await repoA.cleanup(); + await repoB.cleanup(); + } + }); }); diff --git a/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts b/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts new file mode 100644 index 000000000..3e9ffe8f6 --- /dev/null +++ b/gitnexus/test/unit/lbug-checkpoint-lifecycle.test.ts @@ -0,0 +1,420 @@ +import { afterEach, describe, expect, it, vi } from 'vitest'; + +describe('lbug adapter CHECKPOINT lifecycle', () => { + afterEach(() => { + vi.doUnmock('../../src/core/lbug/lbug-config.js'); + vi.doUnmock('../../src/core/lbug/extension-loader.js'); + vi.resetModules(); + vi.clearAllMocks(); + }); + + it('drains and closes CHECKPOINT result before closing connection and database handles', async () => { + vi.resetModules(); + + const events: string[] = []; + const checkpointResult = { + getAll: vi.fn(async () => { + events.push('checkpoint:getAll'); + return []; + }), + close: vi.fn(() => { + events.push('checkpoint:close'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'CHECKPOINT') { + events.push('checkpoint:query'); + return checkpointResult; + } + return genericResult; + }), + close: vi.fn(async () => { + events.push('conn:close'); + }), + }; + const db = { + close: vi.fn(async () => { + events.push('db:close'); + }), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-checkpoint-lifecycle/lbug'); + + events.length = 0; + await adapter.closeLbug(); + + expect(events).toEqual([ + 'checkpoint:query', + 'checkpoint:getAll', + 'checkpoint:close', + 'conn:close', + 'db:close', + ]); + }); + + it('closes normal query results after reading rows', async () => { + vi.resetModules(); + + const events: string[] = []; + const queryResult = { + getAll: vi.fn(async () => { + events.push('query:getAll'); + return [{ id: 'file:a' }]; + }), + close: vi.fn(() => { + events.push('query:close'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'MATCH (n:File) RETURN n.id AS id') { + events.push('query:run'); + return queryResult; + } + return genericResult; + }), + close: vi.fn(async () => {}), + }; + const db = { + close: vi.fn(async () => {}), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-query-lifecycle/lbug'); + + events.length = 0; + await expect(adapter.executeQuery('MATCH (n:File) RETURN n.id AS id')).resolves.toEqual([ + { id: 'file:a' }, + ]); + + expect(events).toEqual(['query:run', 'query:getAll', 'query:close']); + + await adapter.closeLbug(); + }); + + it('treats synchronous query result close errors as best-effort cleanup', async () => { + vi.resetModules(); + + const queryResult = { + getAll: vi.fn(async () => [{ id: 'file:a' }]), + close: vi.fn(() => { + throw new Error('close failed'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'MATCH (n:File) RETURN n.id AS id') { + return queryResult; + } + return genericResult; + }), + close: vi.fn(async () => {}), + }; + const db = { + close: vi.fn(async () => {}), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-sync-close-lifecycle/lbug'); + + await expect(adapter.executeQuery('MATCH (n:File) RETURN n.id AS id')).resolves.toEqual([ + { id: 'file:a' }, + ]); + expect(queryResult.close).toHaveBeenCalledOnce(); + + await adapter.closeLbug(); + }); + + it('closes later query results when an earlier array result fails to read', async () => { + vi.resetModules(); + + const events: string[] = []; + const firstResult = { + getAll: vi.fn(async () => { + events.push('first:getAll'); + throw new Error('read failed'); + }), + close: vi.fn(() => { + events.push('first:close'); + }), + }; + const secondResult = { + getAll: vi.fn(async () => { + events.push('second:getAll'); + return []; + }), + close: vi.fn(() => { + events.push('second:close'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'MATCH (n:File) RETURN n.id AS id') { + return [firstResult, secondResult]; + } + return genericResult; + }), + close: vi.fn(async () => {}), + }; + const db = { + close: vi.fn(async () => {}), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-array-error-lifecycle/lbug'); + + await expect(adapter.executeQuery('MATCH (n:File) RETURN n.id AS id')).rejects.toThrow( + 'read failed', + ); + expect(events).toEqual(['first:getAll', 'first:close', 'second:getAll', 'second:close']); + + await adapter.closeLbug(); + }); + + it('closes non-first stream query results when LadybugDB returns an array', async () => { + vi.resetModules(); + + const events: string[] = []; + const firstResult = { + hasNext: vi + .fn() + .mockImplementationOnce(() => { + events.push('first:hasNext:true'); + return true; + }) + .mockImplementationOnce(() => { + events.push('first:hasNext:false'); + return false; + }), + getNext: vi.fn(async () => { + events.push('first:getNext'); + return { id: 'file:a' }; + }), + getAll: vi.fn(async () => { + events.push('first:getAll'); + return []; + }), + close: vi.fn(() => { + events.push('first:close'); + }), + }; + const secondResult = { + getAll: vi.fn(async () => { + events.push('second:getAll'); + return []; + }), + close: vi.fn(() => { + events.push('second:close'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'MATCH (n:File) RETURN n.id AS id') { + events.push('stream:query'); + return [firstResult, secondResult]; + } + return genericResult; + }), + close: vi.fn(async () => {}), + }; + const db = { + close: vi.fn(async () => {}), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-stream-lifecycle/lbug'); + + const rows: unknown[] = []; + events.length = 0; + await expect( + adapter.streamQuery('MATCH (n:File) RETURN n.id AS id', (row) => { + rows.push(row); + }), + ).resolves.toBe(1); + + expect(rows).toEqual([{ id: 'file:a' }]); + expect(events).toEqual([ + 'stream:query', + 'first:hasNext:true', + 'first:getNext', + 'first:hasNext:false', + 'first:getAll', + 'first:close', + 'second:getAll', + 'second:close', + ]); + + await adapter.closeLbug(); + }); + + it('drains stream query results when row handling fails before the result is exhausted', async () => { + vi.resetModules(); + + const events: string[] = []; + const queryResult = { + hasNext: vi.fn(() => { + events.push('stream:hasNext'); + return true; + }), + getNext: vi.fn(async () => { + events.push('stream:getNext'); + return { id: 'file:a' }; + }), + getAll: vi.fn(async () => { + events.push('stream:getAll'); + return [{ id: 'file:b' }]; + }), + close: vi.fn(() => { + events.push('stream:close'); + }), + }; + const genericResult = { + getAll: vi.fn(async () => []), + close: vi.fn(), + }; + const conn = { + query: vi.fn(async (sql: string) => { + if (sql === 'MATCH (n:File) RETURN n.id AS id') { + events.push('stream:query'); + return queryResult; + } + return genericResult; + }), + close: vi.fn(async () => {}), + }; + const db = { + close: vi.fn(async () => {}), + }; + + vi.doMock('../../src/core/lbug/lbug-config.js', () => ({ + openLbugConnection: vi.fn(async () => ({ db, conn })), + closeLbugConnection: vi.fn(async () => {}), + isDbBusyError: vi.fn((err: unknown) => String(err).toLowerCase().includes('lock')), + isOpenRetryExhausted: vi.fn(() => false), + waitForWindowsHandleRelease: vi.fn(async () => true), + })); + vi.doMock('../../src/core/lbug/extension-loader.js', () => ({ + extensionManager: { + ensure: vi.fn(async () => true), + getCapabilities: vi.fn(() => []), + reset: vi.fn(), + }, + })); + + const adapter = await import('../../src/core/lbug/lbug-adapter.js'); + await adapter.initLbug('/tmp/gitnexus-lbug-stream-error-lifecycle/lbug'); + + await expect( + adapter.streamQuery('MATCH (n:File) RETURN n.id AS id', () => { + throw new Error('client disconnected'); + }), + ).rejects.toThrow('client disconnected'); + + expect(events).toEqual([ + 'stream:query', + 'stream:hasNext', + 'stream:getNext', + 'stream:getAll', + 'stream:close', + ]); + + await adapter.closeLbug(); + }); +}); diff --git a/gitnexus/test/unit/lbug-checkpoint.test.ts b/gitnexus/test/unit/lbug-checkpoint.test.ts index 5b68ee9bd..5b9603997 100644 --- a/gitnexus/test/unit/lbug-checkpoint.test.ts +++ b/gitnexus/test/unit/lbug-checkpoint.test.ts @@ -58,6 +58,14 @@ describe('flushWAL / safeClose — consolidation guard (#1376)', () => { expect(matches.length).toBe(1); }); + it('flushWAL drains and closes the CHECKPOINT result before returning', () => { + const flushBody = adapterSource.slice( + adapterSource.indexOf('export const flushWAL'), + adapterSource.indexOf('export const safeClose'), + ); + expect(flushBody).toMatch(/await drainQueryResult\(checkpointResult\)/); + }); + it('conn.close() only appears inside safeClose (with eslint-disable)', () => { // Every conn.close() in the adapter must live inside safeClose, guarded // by the eslint-disable comment. Count occurrences to catch leaks. From a2f1b077009d9b6e1743a5d8550985381d4f2f6d Mon Sep 17 00:00:00 2001 From: Harlan Zhou Date: Tue, 12 May 2026 23:05:58 +0800 Subject: [PATCH 05/33] fix: resolve TypeScript ESM .js extension imports to .ts source files (#1525) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: resolve TypeScript ESM .js extension imports to .ts source files TypeScript ESM requires imports to use .js extensions even when source files are .ts (moduleResolution: node16/bundler). The import resolver now strips JS-family extensions (.js/.jsx/.mjs/.cjs) and retries with TS equivalents (.ts/.tsx/.mts/.cts) when the literal .js file does not exist. This fallback only applies to TypeScript/JavaScript languages. Also adds .mts/.cts to the EXTENSIONS list for completeness. Fixes #1503 * fix: address review findings — normalization, edge-case tests, integration test - Fix makeCtx to use production normalization (.replace backslash) instead of .toLowerCase() (Finding 3) - Add tests for .mjs/.cjs with competing .ts/.mts siblings (Finding 1) - Add tests for ./dir.js → dir/index.ts boundary (Finding 2) - Add integration test verifying full pipeline CALLS edges for ESM .js imports (Finding 4) - Document path alias .js limitation as known follow-up (Finding 5) * chore(autofix): apply prettier + eslint fixes via /autofix command * chore: retrigger CI after bot-only tip commit Co-authored-by: Cursor --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Gergo Magyar Co-authored-by: Cursor --- .../ingestion/import-resolvers/standard.ts | 32 +++- .../core/ingestion/import-resolvers/utils.ts | 4 + .../typescript-esm-js-extension.test.ts | 62 +++++++ .../unit/esm-extension-resolution.test.ts | 153 ++++++++++++++++++ 4 files changed, 250 insertions(+), 1 deletion(-) create mode 100644 gitnexus/test/integration/resolvers/typescript-esm-js-extension.test.ts create mode 100644 gitnexus/test/unit/esm-extension-resolution.test.ts diff --git a/gitnexus/src/core/ingestion/import-resolvers/standard.ts b/gitnexus/src/core/ingestion/import-resolvers/standard.ts index f8aae9625..47e2dabb2 100644 --- a/gitnexus/src/core/ingestion/import-resolvers/standard.ts +++ b/gitnexus/src/core/ingestion/import-resolvers/standard.ts @@ -128,7 +128,21 @@ export const resolveImportPath = ( if (importPath.startsWith('.')) { const resolved = tryResolveWithExtensions(basePath, allFiles); - return cache(resolved); + if (resolved) return cache(resolved); + + // TypeScript ESM: imports use .js/.jsx/.mjs/.cjs but source files are + // .ts/.tsx/.mts/.cts. Strip the JS-family extension and re-resolve. + // NOTE: This fallback only applies to relative imports. Path alias imports + // (e.g. @/utils.js via tsconfig paths) do not yet strip .js extensions — + // that is a known limitation tracked for follow-up. + if (language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) { + const stripped = stripJsExtension(basePath); + if (stripped !== null) { + return cache(tryResolveWithExtensions(stripped, allFiles)); + } + } + + return cache(null); } // ---- Generic package/absolute import resolution (suffix matching) ---- @@ -182,3 +196,19 @@ export function resolveStandard( export function createStandardStrategy(language: SupportedLanguages): ImportResolverStrategy { return (raw, fp, ctx) => resolveStandard(raw, fp, ctx, language); } + +// ============================================================================ +// ESM extension helpers +// ============================================================================ + +/** JS-family extensions that TypeScript ESM maps to TS equivalents. */ +const JS_EXTENSION_PATTERN = /\.(js|jsx|mjs|cjs)$/; + +/** + * Strip a JS-family extension from a path, returning the stem. + * Returns `null` if the path does not end with a JS-family extension. + */ +export function stripJsExtension(path: string): string | null { + const match = JS_EXTENSION_PATTERN.exec(path); + return match ? path.slice(0, -match[0].length) : null; +} diff --git a/gitnexus/src/core/ingestion/import-resolvers/utils.ts b/gitnexus/src/core/ingestion/import-resolvers/utils.ts index 8d915eb7f..c4d36556c 100644 --- a/gitnexus/src/core/ingestion/import-resolvers/utils.ts +++ b/gitnexus/src/core/ingestion/import-resolvers/utils.ts @@ -9,8 +9,12 @@ export const EXTENSIONS = [ // TypeScript/JavaScript '.tsx', '.ts', + '.mts', + '.cts', '.jsx', '.js', + '.mjs', + '.cjs', '.vue', '/index.tsx', '/index.ts', diff --git a/gitnexus/test/integration/resolvers/typescript-esm-js-extension.test.ts b/gitnexus/test/integration/resolvers/typescript-esm-js-extension.test.ts new file mode 100644 index 000000000..476082563 --- /dev/null +++ b/gitnexus/test/integration/resolvers/typescript-esm-js-extension.test.ts @@ -0,0 +1,62 @@ +/** + * Integration test: TypeScript ESM .js extension imports produce CALLS edges. + * + * Verifies the full pipeline: .js import → resolveImportPath strips .js → + * resolves to .ts → scope-resolver emits CALLS edge. + */ +import { describe, it, expect, beforeAll, afterAll } from 'vitest'; +import path from 'path'; +import fs from 'node:fs'; +import os from 'node:os'; +import { getRelationships, runPipelineFromRepo, type PipelineResult } from './helpers.js'; + +function writeFixtureRepo(root: string, files: Record): void { + for (const [relPath, content] of Object.entries(files)) { + const fullPath = path.join(root, relPath); + fs.mkdirSync(path.dirname(fullPath), { recursive: true }); + fs.writeFileSync(fullPath, content, 'utf8'); + } +} + +describe('TypeScript ESM .js extension → CALLS edges', () => { + let result: PipelineResult; + let repoDir: string | undefined; + + beforeAll(async () => { + repoDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-ts-esm-js-ext-')); + writeFixtureRepo(repoDir, { + 'src/utils.ts': ` +export function estimateTokens(text: string): number { + return Math.ceil(text.length / 4); +} +`, + 'src/index.ts': ` +import { estimateTokens } from './utils.js'; + +export function processText(text: string): number { + return estimateTokens(text); +} +`, + }); + result = await runPipelineFromRepo(repoDir, () => {}); + }, 60000); + + afterAll(() => { + if (repoDir !== undefined) fs.rmSync(repoDir, { recursive: true, force: true }); + }); + + it('emits CALLS edge from processText → estimateTokens via .js import', () => { + const calls = getRelationships(result, 'CALLS'); + const edge = calls.find((c) => c.source === 'processText' && c.target === 'estimateTokens'); + expect(edge).toBeDefined(); + expect(edge!.targetFilePath).toBe('src/utils.ts'); + }); + + it('emits IMPORTS edge from index.ts → utils.ts', () => { + const imports = getRelationships(result, 'IMPORTS'); + const edge = imports.find( + (e) => e.sourceFilePath === 'src/index.ts' && e.targetFilePath === 'src/utils.ts', + ); + expect(edge).toBeDefined(); + }); +}); diff --git a/gitnexus/test/unit/esm-extension-resolution.test.ts b/gitnexus/test/unit/esm-extension-resolution.test.ts new file mode 100644 index 000000000..69dc652cf --- /dev/null +++ b/gitnexus/test/unit/esm-extension-resolution.test.ts @@ -0,0 +1,153 @@ +/** + * Unit tests for TypeScript ESM .js extension resolution. + * + * TypeScript ESM requires imports to use .js extensions even when source + * files are .ts. The resolver must map .js → .ts (and .jsx → .tsx, + * .mjs → .mts, .cjs → .cts) when the literal .js file does not exist. + */ + +import { describe, it, expect } from 'vitest'; +import { resolveImportPath } from '../../src/core/ingestion/import-resolvers/standard.js'; +import { stripJsExtension } from '../../src/core/ingestion/import-resolvers/standard.js'; +import { buildSuffixIndex } from '../../src/core/ingestion/import-resolvers/utils.js'; +import { SupportedLanguages } from 'gitnexus-shared'; + +function makeCtx(files: string[]) { + // Match production normalization: only replace backslashes with forward slashes + const normalized = files.map((f) => f.replace(/\\/g, '/')); + const allFilesSet = new Set(files); + const index = buildSuffixIndex(normalized, files); + const cache = new Map(); + return { files, normalized, allFilesSet, index, cache }; +} + +function resolve( + currentFile: string, + importPath: string, + language: SupportedLanguages, + ctx: ReturnType, +): string | null { + return resolveImportPath( + currentFile, + importPath, + ctx.allFilesSet, + ctx.files, + ctx.normalized, + ctx.cache, + language, + null, + ctx.index, + ); +} + +describe('TypeScript ESM .js extension resolution', () => { + it('resolves ./utils.js to ./utils.ts when .js does not exist', () => { + const ctx = makeCtx(['src/index.ts', 'src/utils.ts']); + const result = resolve('src/index.ts', './utils.js', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/utils.ts'); + }); + + it('resolves ./component.jsx to ./component.tsx', () => { + const ctx = makeCtx(['src/app.ts', 'src/component.tsx']); + const result = resolve('src/app.ts', './component.jsx', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/component.tsx'); + }); + + it('resolves ./config.mjs to ./config.mts', () => { + const ctx = makeCtx(['src/index.ts', 'src/config.mts']); + const result = resolve('src/index.ts', './config.mjs', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/config.mts'); + }); + + it('resolves ./legacy.cjs to ./legacy.cts', () => { + const ctx = makeCtx(['src/index.ts', 'src/legacy.cts']); + const result = resolve('src/index.ts', './legacy.cjs', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/legacy.cts'); + }); + + it('prefers actual .js file when it exists', () => { + const ctx = makeCtx(['src/index.ts', 'src/utils.js', 'src/utils.ts']); + const result = resolve('src/index.ts', './utils.js', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/utils.js'); + }); + + it('resolves relative path with ../ and .js extension', () => { + const ctx = makeCtx(['src/helpers/token.ts', 'src/core/engine.ts']); + const result = resolve( + 'src/core/engine.ts', + '../helpers/token.js', + SupportedLanguages.TypeScript, + ctx, + ); + expect(result).toBe('src/helpers/token.ts'); + }); + + it('works for JavaScript language too', () => { + const ctx = makeCtx(['src/index.js', 'src/utils.ts']); + const result = resolve('src/index.js', './utils.js', SupportedLanguages.JavaScript, ctx); + expect(result).toBe('src/utils.ts'); + }); + + it('does NOT apply ESM fallback for non-TS/JS languages', () => { + const ctx = makeCtx(['src/main.py', 'src/utils.ts']); + const result = resolve('src/main.py', './utils.js', SupportedLanguages.Python, ctx); + expect(result).toBeNull(); + }); + + it('returns null when neither .js nor .ts exists', () => { + const ctx = makeCtx(['src/index.ts']); + const result = resolve('src/index.ts', './missing.js', SupportedLanguages.TypeScript, ctx); + expect(result).toBeNull(); + }); +}); + +describe('ESM extension resolution — .mjs/.cjs with competing siblings', () => { + it('resolves ./config.mjs to .ts when only .ts exists (no .mts)', () => { + const ctx = makeCtx(['src/index.ts', 'src/config.ts']); + const result = resolve('src/index.ts', './config.mjs', SupportedLanguages.TypeScript, ctx); + // .ts wins because EXTENSIONS order tries .ts before .mts + expect(result).toBe('src/config.ts'); + }); + + it('resolves ./config.mjs to .mts when both .ts and .mts exist', () => { + // Note: EXTENSIONS order is .tsx, .ts, .mts, .cts — so .ts wins over .mts. + // This is intentional for a source-analysis tool: we resolve to the first + // matching source file. In practice, having both config.ts and config.mts + // in the same directory is extremely rare. + const ctx = makeCtx(['src/index.ts', 'src/config.ts', 'src/config.mts']); + const result = resolve('src/index.ts', './config.mjs', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/config.ts'); + }); + + it('resolves ./config.cjs to .cts when only .cts exists', () => { + const ctx = makeCtx(['src/index.ts', 'src/config.cts']); + const result = resolve('src/index.ts', './config.cjs', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/config.cts'); + }); +}); + +describe('ESM extension resolution — directory index boundary', () => { + it('resolves ./dir.js to dir/index.ts when dir/ exists (bundler-mode)', () => { + // After stripping .js from "dir.js" → "dir", tryResolveWithExtensions probes + // "/index.ts" suffix. This matches bundler-mode behavior where bare directory + // imports resolve to index files. Intentional for source-analysis compatibility. + const ctx = makeCtx(['src/index.ts', 'src/dir/index.ts']); + const result = resolve('src/index.ts', './dir.js', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/dir/index.ts'); + }); + + it('resolves ./dir/index.js to dir/index.ts', () => { + const ctx = makeCtx(['src/index.ts', 'src/dir/index.ts']); + const result = resolve('src/index.ts', './dir/index.js', SupportedLanguages.TypeScript, ctx); + expect(result).toBe('src/dir/index.ts'); + }); +}); + +describe('stripJsExtension', () => { + it('strips .js', () => expect(stripJsExtension('foo/bar.js')).toBe('foo/bar')); + it('strips .jsx', () => expect(stripJsExtension('foo/bar.jsx')).toBe('foo/bar')); + it('strips .mjs', () => expect(stripJsExtension('foo/bar.mjs')).toBe('foo/bar')); + it('strips .cjs', () => expect(stripJsExtension('foo/bar.cjs')).toBe('foo/bar')); + it('returns null for .ts', () => expect(stripJsExtension('foo/bar.ts')).toBeNull()); + it('returns null for no extension', () => expect(stripJsExtension('foo/bar')).toBeNull()); +}); From 8083c39f6d8271c6ec88ff53db127fe4d11b217e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Gerg=C5=91=20Magyar?= Date: Tue, 12 May 2026 16:56:31 +0100 Subject: [PATCH 06/33] feat(php): migrate PHP to scope-based resolution model (#938) [supersedes #1124] (#1497) --- .../scope-resolution/method-dispatch-index.ts | 52 +- .../registries/lookup-core.ts | 19 +- gitnexus/src/core/ingestion/languages/php.ts | 28 +- .../ingestion/languages/php/arity-metadata.ts | 73 ++ .../src/core/ingestion/languages/php/arity.ts | 47 + .../ingestion/languages/php/cache-stats.ts | 30 + .../core/ingestion/languages/php/captures.ts | 806 ++++++++++++++++++ .../languages/php/import-decomposer.ts | 304 +++++++ .../ingestion/languages/php/import-target.ts | 140 +++ .../src/core/ingestion/languages/php/index.ts | 73 ++ .../core/ingestion/languages/php/interpret.ts | 250 ++++++ .../ingestion/languages/php/merge-bindings.ts | 51 ++ .../languages/php/namespace-siblings.ts | 335 ++++++++ .../src/core/ingestion/languages/php/query.ts | 332 ++++++++ .../languages/php/receiver-binding.ts | 136 +++ .../ingestion/languages/php/scope-resolver.ts | 421 +++++++++ .../ingestion/languages/php/simple-hooks.ts | 134 +++ .../core/ingestion/registry-primary-flag.ts | 1 + .../contract/scope-resolver.ts | 68 ++ .../graph-bridge/method-dispatch.ts | 13 +- .../graph-bridge/node-lookup.ts | 5 + .../passes/free-call-fallback.ts | 82 +- .../passes/overload-narrowing.ts | 30 +- .../passes/receiver-bound-calls.ts | 27 +- .../scope-resolution/pipeline/registry.ts | 2 + .../scope-resolution/pipeline/run.ts | 17 +- .../src/core/ingestion/tree-sitter-queries.ts | 10 + .../app/{BProvider.php => Models/User.php} | 0 .../php-calls/app/Services/UserService.php | 7 +- .../app/Services/Dynamic.php | 113 +++ .../app/Services/OtherTargets.php | 16 + .../app/Services/Targets.php | 36 + .../php-dynamic-calls/composer.json | 5 + .../app/Models/User.php | 8 + .../app/Other/User.php | 8 + .../app/Services/Service.php | 25 + .../php-fqn-cross-namespace/composer.json | 7 + .../app/Models/ChildModel.php | 10 + .../app/Models/Orphan.php | 8 + .../app/Models/ParentModel.php | 10 + .../app/Services/Caller.php | 42 + .../php-mro-arity-mismatch/composer.json | 5 + .../composer.json | 8 + .../src/App/Caller.php | 19 + .../src/App/Utils/Caller.php | 10 + .../src/App/Utils/Format.php | 6 + .../src/Vendor/Utils/Format.php | 6 + .../php-parent-vs-trait/app/Auditable.php | 8 + .../php-parent-vs-trait/app/Base.php | 8 + .../php-parent-vs-trait/app/Child.php | 14 + .../php-parent-vs-trait/composer.json | 7 + .../app/Models/Consumer.php | 20 + .../app/Traits/TraitA.php | 10 + .../app/Traits/TraitB.php | 10 + .../app/Traits/TraitC.php | 8 + .../php-transitive-traits/composer.json | 7 + .../app/Models/UserRepo.php | 8 + .../app/Services/Mixed.php | 23 + .../php-typed-property-dedup/composer.json | 5 + .../app/Models/Handler.php | 26 + .../app/Services/Caller.php | 58 ++ .../composer.json | 5 + .../app/Services/Caller.php | 30 + .../app/Utils/Logger.php | 19 + .../php-variadic-arity-minimum/composer.json | 7 + .../test/integration/resolvers/helpers.ts | 46 + .../test/integration/resolvers/php.test.ts | 490 ++++++++++- .../test/unit/registry-primary-flag.test.ts | 15 +- .../overload-narrowing.test.ts | 19 +- .../pick-implicit-this-overload.test.ts | 156 ++++ .../unit/scope-resolution/registries.test.ts | 45 +- 71 files changed, 4846 insertions(+), 33 deletions(-) create mode 100644 gitnexus/src/core/ingestion/languages/php/arity-metadata.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/arity.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/cache-stats.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/captures.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/import-decomposer.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/import-target.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/index.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/interpret.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/merge-bindings.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/namespace-siblings.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/query.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/receiver-binding.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/scope-resolver.ts create mode 100644 gitnexus/src/core/ingestion/languages/php/simple-hooks.ts rename gitnexus/test/fixtures/cross-file-binding/php-consumer-before-provider/app/{BProvider.php => Models/User.php} (100%) create mode 100644 gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/Dynamic.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/OtherTargets.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/Targets.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/app/Models/User.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/app/Other/User.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/app/Services/Service.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/ChildModel.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/Orphan.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/ParentModel.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Services/Caller.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Caller.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Utils/Caller.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Utils/Format.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/Vendor/Utils/Format.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/app/Auditable.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/app/Base.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/app/Child.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Models/Consumer.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitA.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitB.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitC.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-transitive-traits/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-typed-property-dedup/app/Models/UserRepo.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-typed-property-dedup/app/Services/Mixed.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-typed-property-dedup/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/app/Models/Handler.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/app/Services/Caller.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/composer.json create mode 100644 gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/app/Services/Caller.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/app/Utils/Logger.php create mode 100644 gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/composer.json create mode 100644 gitnexus/test/unit/scope-resolution/pick-implicit-this-overload.test.ts diff --git a/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts b/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts index d09e8fa89..dcaa45055 100644 --- a/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts +++ b/gitnexus-shared/src/scope-resolution/method-dispatch-index.ts @@ -40,11 +40,27 @@ export interface MethodDispatchIndex { readonly mroByOwnerDefId: ReadonlyMap; /** Interfaces / traits → classes that implement them. */ readonly implsByInterfaceDefId: ReadonlyMap; + /** + * Optional parallel MRO view that EXCLUDES mixin-like augmentation + * (e.g., PHP traits). Populated only when the input supplies + * `computeExtendsOnlyMro`. Used by the super-branch dispatch in + * `receiver-bound-calls` so that `parent::method()` walks the + * inheritance chain only, not the trait-augmented one. Undefined for + * languages without mixin-like semantics — callers should fall back + * to `mroFor` when this is missing. + */ + readonly extendsOnlyMroByOwnerDefId?: ReadonlyMap; /** `mroByOwnerDefId.get`, with an empty frozen array on miss. */ mroFor(ownerDefId: DefId): readonly DefId[]; /** `implsByInterfaceDefId.get`, with an empty frozen array on miss. */ implementorsOf(interfaceDefId: DefId): readonly DefId[]; + /** + * `extendsOnlyMroByOwnerDefId.get`, with an empty frozen array on miss. + * Undefined when `extendsOnlyMroByOwnerDefId` was not populated; callers + * should treat this as equivalent to `mroFor` for non-mixin languages. + */ + readonly extendsOnlyMroFor?: (ownerDefId: DefId) => readonly DefId[]; } export interface MethodDispatchInput { @@ -81,12 +97,25 @@ export interface MethodDispatchInput { * write-wins policy and fires at most once per unique owner. */ readonly implementsOf: (ownerDefId: DefId) => readonly DefId[]; + /** + * Optional: return the EXTENDS-only ancestor chain for `ownerDefId`, + * excluding the owner itself AND any mixin-like augmentation (e.g., + * PHP traits). Languages without mixin semantics leave this undefined + * and the index's `extendsOnlyMroByOwnerDefId` stays unpopulated. + * + * Same contract as `computeMro`: pure, deterministic, `[]` on no parents. + * Called at most once per unique owner (first-write-wins). + */ + readonly computeExtendsOnlyMro?: (ownerDefId: DefId) => readonly DefId[]; } // ─── Builder ──────────────────────────────────────────────────────────────── export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDispatchIndex { const mroByOwnerDefId = new Map(); + const extendsOnlyByOwnerDefId = input.computeExtendsOnlyMro + ? new Map() + : undefined; const implsBuilding = new Map(); const implsSeen = new Map>(); @@ -97,6 +126,14 @@ export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDisp const chain = input.computeMro(ownerId); mroByOwnerDefId.set(ownerId, Object.freeze(chain.slice())); } + if ( + input.computeExtendsOnlyMro !== undefined && + extendsOnlyByOwnerDefId !== undefined && + !extendsOnlyByOwnerDefId.has(ownerId) + ) { + const extOnly = input.computeExtendsOnlyMro(ownerId); + extendsOnlyByOwnerDefId.set(ownerId, Object.freeze(extOnly.slice())); + } for (const ifaceId of input.implementsOf(ownerId)) { let seen = implsSeen.get(ifaceId); @@ -121,7 +158,7 @@ export function buildMethodDispatchIndex(input: MethodDispatchInput): MethodDisp implsByInterfaceDefId.set(ifaceId, Object.freeze(owners.slice())); } - return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId); + return wrapIndex(mroByOwnerDefId, implsByInterfaceDefId, extendsOnlyByOwnerDefId); } // ─── Internal ─────────────────────────────────────────────────────────────── @@ -131,8 +168,9 @@ const EMPTY: readonly DefId[] = Object.freeze([]); function wrapIndex( mroByOwnerDefId: Map, implsByInterfaceDefId: Map, + extendsOnlyMroByOwnerDefId: Map | undefined, ): MethodDispatchIndex { - return { + const base: MethodDispatchIndex = { mroByOwnerDefId, implsByInterfaceDefId, mroFor(ownerDefId: DefId): readonly DefId[] { @@ -142,4 +180,14 @@ function wrapIndex( return implsByInterfaceDefId.get(interfaceDefId) ?? EMPTY; }, }; + if (extendsOnlyMroByOwnerDefId !== undefined) { + return { + ...base, + extendsOnlyMroByOwnerDefId, + extendsOnlyMroFor(ownerDefId: DefId): readonly DefId[] { + return extendsOnlyMroByOwnerDefId.get(ownerDefId) ?? EMPTY; + }, + }; + } + return base; } diff --git a/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts b/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts index a18ad4930..fff3e7adb 100644 --- a/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts +++ b/gitnexus-shared/src/scope-resolution/registries/lookup-core.ts @@ -423,13 +423,30 @@ function applyArityFilter( } let anyCompatible = false; + let anyUnknown = false; for (const state of perCandidate.values()) { const verdict = arityFn(callsite, state.def); state.signals.arityVerdict = verdict; if (verdict === 'compatible') anyCompatible = true; + else if (verdict === 'unknown') anyUnknown = true; } - if (!anyCompatible) return; + // When ALL candidates are 'incompatible' (none compatible, none unknown), + // the call is genuinely arity-broken — drop every candidate so the + // registry returns no resolution. This matches the PHP variadic case + // f(int $req, ...$rest) called with zero args: every candidate definitively + // rejects, and emitting an edge to a definitively-rejected callable is + // a false positive. When some candidates are 'unknown' (missing metadata), + // keep the set so downstream evidence can break the tie — that's the + // original safety-fallback behavior. + if (!anyCompatible) { + if (!anyUnknown) { + for (const defId of perCandidate.keys()) { + perCandidate.delete(defId); + } + } + return; + } // Filter: when at least one compatible candidate exists, drop incompatibles. for (const [defId, state] of perCandidate) { diff --git a/gitnexus/src/core/ingestion/languages/php.ts b/gitnexus/src/core/ingestion/languages/php.ts index eb8f296f8..caca85335 100644 --- a/gitnexus/src/core/ingestion/languages/php.ts +++ b/gitnexus/src/core/ingestion/languages/php.ts @@ -5,12 +5,22 @@ * and standard export/import resolution. PHP files can use a variety of * extensions from legacy versions through modern PHP 8. */ +import { + emitPhpScopeCaptures, + interpretPhpImport, + interpretPhpTypeBinding, + phpArityCompatibility, + phpMergeBindings, + resolvePhpImportTarget, + phpBindingScopeFor, + phpImportOwningScope, + phpReceiverBinding, +} from './php/index.js'; import { SupportedLanguages } from 'gitnexus-shared'; import { createClassExtractor } from '../class-extractors/generic.js'; import { phpClassConfig } from '../class-extractors/configs/php.js'; -import { defineLanguage } from '../language-provider.js'; -import type { AstFrameworkPatternConfig } from '../language-provider.js'; +import { defineLanguage, type AstFrameworkPatternConfig } from '../language-provider.js'; import { typeConfig as phpConfig } from '../type-extractors/php.js'; import { phpExportChecker } from '../export-detection.js'; import { createImportResolver } from '../import-resolvers/resolver-factory.js'; @@ -289,4 +299,18 @@ export const phpProvider = defineLanguage({ descriptionExtractor: phpDescriptionExtractor, isRouteFile: isPhpRouteFile, builtInNames: BUILT_INS, + // ── RFC #909 Ring 3: scope-based resolution hooks ────────────────────── + emitScopeCaptures: emitPhpScopeCaptures, + interpretImport: interpretPhpImport, + interpretTypeBinding: interpretPhpTypeBinding, + // LanguageProvider uses (def, callsite); phpArityCompatibility uses (def, callsite) — same. + arityCompatibility: phpArityCompatibility, + // LanguageProvider adapter: (parsedImport, workspaceIndex) → string | null + resolveImportTarget: resolvePhpImportTarget, + // mergeBindings on LanguageProvider: (scope, bindings) — ignore scope id, + // delegate to phpMergeBindings which uses binding origin tiers. + mergeBindings: (_scope, bindings) => [...phpMergeBindings(bindings)], + bindingScopeFor: phpBindingScopeFor, + importOwningScope: phpImportOwningScope, + receiverBinding: phpReceiverBinding, }); diff --git a/gitnexus/src/core/ingestion/languages/php/arity-metadata.ts b/gitnexus/src/core/ingestion/languages/php/arity-metadata.ts new file mode 100644 index 000000000..40662bd61 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/arity-metadata.ts @@ -0,0 +1,73 @@ +/** + * Extract PHP arity metadata from a method-like tree-sitter node — + * `method_declaration` or `function_definition`. + * + * Reuses `phpMethodConfig.extractParameters` so scope-extracted defs + * carry the same arity semantics as the legacy parse-worker path: + * - `variadic_parameter` (`...$args`) collapses `parameterCount` to + * `undefined`, which `phpArityCompatibility` then treats as + * "max unknown" — the candidate stays eligible at `argCount >= required`. + * - Defaulted parameters (`= expr`) contribute to `optionalCount`; + * `requiredParameterCount = total − optionalCount − (variadic ? 1 : 0)`. + * The variadic slot itself accepts zero args so it is subtracted from + * the required count — `f(int $a, ...$rest)` requires exactly 1 arg, + * not 2, and `f(...$rest)` requires 0. + * - `property_promotion_parameter` (constructor-promoted) is counted + * the same as `simple_parameter` since both consume an argument slot. + * - `parameterTypes` collects declared type names; a literal `'...'` + * marker is appended for variadic methods so `phpArityCompatibility` + * can detect them without re-reading the AST. + */ + +import type { SyntaxNode } from '../../utils/ast-helpers.js'; +import { phpMethodConfig } from '../../method-extractors/configs/php.js'; + +interface PhpArityMetadata { + readonly parameterCount: number | undefined; + readonly requiredParameterCount: number | undefined; + readonly parameterTypes: readonly string[] | undefined; +} + +export function computePhpArityMetadata(fnNode: SyntaxNode): PhpArityMetadata { + const params = phpMethodConfig.extractParameters?.(fnNode) ?? []; + + let hasVariadic = false; + let optionalCount = 0; + const types: string[] = []; + + for (const p of params) { + if (p.isVariadic) { + hasVariadic = true; + } else if (p.isOptional) { + optionalCount++; + } + if (p.type !== null) types.push(p.type); + } + // PHP variadic marker convention: append the literal '...' string to + // `parameterTypes`. This is intentionally DIFFERENT from C#, which uses + // the literal 'params' (its source-language keyword). The shared + // `narrowOverloadCandidates` pass in `scope-resolution/passes/overload- + // narrowing.ts` checks for the C# 'params' marker — that branch is + // dead code for PHP because PHP variadic methods set `parameterCount + // = undefined` (see line below), which skips the `max !== undefined` + // gate that hosts the 'params' check. PHP's actual variadic-aware + // arity logic lives in `phpArityCompatibility` (arity.ts) and now + // also in `phpEmitUnresolvedReceiverEdges` (scope-resolver.ts), both + // of which check `'...'`. Finding 9 of PR #1497 adversarial review. + if (hasVariadic) types.push('...'); + + const total = params.length; + // Variadic methods accept any arg count ≥ required — leave `parameterCount` + // undefined so the registry treats max as unknown. + const parameterCount = hasVariadic ? undefined : total; + // The variadic slot itself accepts zero args; subtract it from the required + // count so PHP's ArgumentCountError-equivalent calls (too few args before + // the variadic) are correctly rejected by arity compatibility. + const requiredParameterCount = total - optionalCount - (hasVariadic ? 1 : 0); + + return { + parameterCount, + requiredParameterCount, + parameterTypes: types.length > 0 ? types : undefined, + }; +} diff --git a/gitnexus/src/core/ingestion/languages/php/arity.ts b/gitnexus/src/core/ingestion/languages/php/arity.ts new file mode 100644 index 000000000..5b99a73c7 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/arity.ts @@ -0,0 +1,47 @@ +/** + * PHP arity check, accommodating variadic (`...$args`) and default parameters. + * + * The `def` metadata synthesized by `arity-metadata.ts`: + * - `parameterCount` — total formal parameters; `undefined` when + * the method has a variadic `...$param`. + * - `requiredParameterCount` — min required (excludes defaulted params + * and the variadic itself). + * - `parameterTypes` — declared type strings; contains the + * literal `'...'` when the method is variadic. + * + * Verdicts: + * - `'compatible'` — `required <= argCount <= max`, OR the def has + * variadic (any `argCount >= required`). + * - `'incompatible'` — argCount below required, or above max with no variadic. + * - `'unknown'` — metadata absent / incomplete; named-args can satisfy + * any arity so we return unknown when we detect them. + * + * PHP supports named arguments (PHP 8.0+): `save(force: true)`. Named-arg + * call sites cannot be arity-checked statically without parsing arg names, + * so we return `'unknown'` when the callsite carries named args (signalled + * by a negative `arity` value per the shared Callsite contract). + */ + +import type { Callsite, SymbolDefinition } from 'gitnexus-shared'; + +export function phpArityCompatibility( + def: SymbolDefinition, + callsite: Callsite, +): 'compatible' | 'unknown' | 'incompatible' { + const max = def.parameterCount; + const min = def.requiredParameterCount; + if (max === undefined && min === undefined) return 'unknown'; + + const argCount = callsite.arity; + // Negative arity signals named-argument call sites — can't narrow statically. + if (!Number.isFinite(argCount) || argCount < 0) return 'unknown'; + + const hasVarArgs = + def.parameterTypes !== undefined && + def.parameterTypes.some((t) => t === '...' || t.startsWith('...')); + + if (min !== undefined && argCount < min) return 'incompatible'; + if (max !== undefined && argCount > max && !hasVarArgs) return 'incompatible'; + + return 'compatible'; +} diff --git a/gitnexus/src/core/ingestion/languages/php/cache-stats.ts b/gitnexus/src/core/ingestion/languages/php/cache-stats.ts new file mode 100644 index 000000000..508eec580 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/cache-stats.ts @@ -0,0 +1,30 @@ +/** + * Dev-mode counters for the cross-phase scope-captures parse cache + * (PHP 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(): void { + if (PROF) CACHE_HITS++; +} + +export function recordCacheMiss(): void { + if (PROF) CACHE_MISSES++; +} + +export function getPhpCaptureCacheStats(): { hits: number; misses: number } { + return { hits: CACHE_HITS, misses: CACHE_MISSES }; +} + +export function resetPhpCaptureCacheStats(): void { + CACHE_HITS = 0; + CACHE_MISSES = 0; +} diff --git a/gitnexus/src/core/ingestion/languages/php/captures.ts b/gitnexus/src/core/ingestion/languages/php/captures.ts new file mode 100644 index 000000000..692d87bc1 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/captures.ts @@ -0,0 +1,806 @@ +/** + * `emitScopeCaptures` for PHP (RFC #909 Ring 3 LANG-php). + * + * Drives the PHP scope query against tree-sitter-php and groups raw + * matches into `CaptureMatch[]` for the central extractor. Layers two + * synthesized streams on top: + * + * 1. **Decomposed use declarations** — each `namespace_use_declaration` + * is re-emitted with `@import.kind/source/name/alias` markers so + * `interpretPhpImport` can recover the ParsedImport shape without + * re-parsing raw text. Grouped uses fan out to one match per clause. + * + * 2. **Receiver-binding synthesis** — `$this` and `parent` type-bindings + * are synthesized on every non-static method entry. PHP's grammar + * does not express "implicit receiver of a non-static class method" + * via a clean `.scm` pattern, so we walk up the AST in code. + * + * 3. **Arity metadata synthesis** — `@declaration.parameter-count` / + * `@declaration.required-parameter-count` / `@declaration.parameter-types` + * are synthesized on function-like declarations so the registry can + * narrow overloads. + * + * 4. **PHPDoc synthesis** — @param and @return annotations in comment + * nodes preceding method/function declarations are extracted and emitted + * as `@type-binding.parameter` and `@type-binding.return` matches. + * + * 5. **Foreach loop synthesis** — `foreach ($users as $user)` emits + * a `@type-binding.alias` match binding the loop variable to the + * element type of the iterable (resolved from PHPDoc or scopeEnv). + * + * Pure given the input source text. No I/O, no globals consulted. + */ + +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { findNodeAtRange, nodeToCapture, syntheticCapture } from '../../utils/ast-helpers.js'; +import { splitNamespaceUseDeclaration } from './import-decomposer.js'; +import { computePhpArityMetadata } from './arity-metadata.js'; +import { synthesizePhpReceiverBinding } from './receiver-binding.js'; +import { getPhpParser, getPhpScopeQuery } from './query.js'; +import { recordCacheHit, recordCacheMiss } from './cache-stats.js'; +import { getTreeSitterBufferSize } from '../../constants.js'; +import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js'; + +type SyntaxNode = ReturnType['parse']>['rootNode']; + +/** Declaration anchors that carry function-like arity metadata. */ +const FUNCTION_DECL_TAGS = ['@declaration.method', '@declaration.function'] as const; + +/** tree-sitter-php node types that the method extractor accepts. */ +const FUNCTION_NODE_TYPES = [ + 'method_declaration', + 'function_definition', + 'anonymous_function', + 'arrow_function', +] as const; + +export function emitPhpScopeCaptures( + sourceText: string, + _filePath: string, + cachedTree?: unknown, +): readonly CaptureMatch[] { + // Skip the parse when the caller already produced a Tree for this source. + // The cachedTree parameter is typed as `unknown` at the LanguageProvider + // contract layer; cast here at the use site. + let tree = cachedTree as ReturnType['parse']> | undefined; + if (tree === undefined) { + tree = parseSourceSafe(getPhpParser(), sourceText, undefined, { + bufferSize: getTreeSitterBufferSize(sourceText), + }); + recordCacheMiss(); + } else { + recordCacheHit(); + } + + const rawMatches = getPhpScopeQuery().matches(tree.rootNode); + const out: CaptureMatch[] = []; + + // Pre-scan: collect anchor node IDs of property_declaration nodes already + // matched by the typed @declaration.property pattern (query.ts ~lines 95–98). + // The untyped @declaration.variable catch-all (query.ts ~lines 101–103) is + // intentionally loose — it has no `type:` constraint, so tree-sitter also + // matches it against typed property declarations and emits a second capture + // for the same property_declaration anchor. Graph-level def-id collision + // currently masks the duplicate at the node-emit layer, but the catch-all + // capture still flows through scope-binding / name-keyed registries with a + // `$`-prefixed name that the typed branch's `$`-strip never normalizes — + // a known vector for receiver-binding lookup pollution. The two patterns + // produce separate rawMatches entries with separate `grouped` maps, so the + // dedup has to be cross-match: build the set here, then skip + // @declaration.variable matches whose anchor is in it (loop below). + const typedPropertyAnchorIds = new Set(); + for (const m of rawMatches) { + for (const c of m.captures) { + if (c.name === 'declaration.property') { + typedPropertyAnchorIds.add(c.node.id); + break; + } + } + } + + for (const m of rawMatches) { + // Group captures by their tag name. Tree-sitter strips the leading + // `@`; we put it back so the central extractor's prefix lookups work. + const grouped: Record = {}; + for (const c of m.captures) { + const tag = '@' + c.name; + grouped[tag] = nodeToCapture(tag, c.node); + } + if (Object.keys(grouped).length === 0) continue; + + // Cross-match dedup for the typed-property double-match described above: + // skip @declaration.variable matches whose anchor was already captured as + // @declaration.property in an earlier match. + if (grouped['@declaration.variable'] !== undefined) { + const varCap = m.captures.find((c) => c.name === 'declaration.variable'); + if (varCap !== undefined && typedPropertyAnchorIds.has(varCap.node.id)) continue; + } + + // Normalize PHP property declarations: strip leading `$` from + // `@declaration.name` for @declaration.property matches. PHP stores + // field names WITHOUT the `$` sigil in the graph so that member access + // lookups like `$user->address` can find the property named `address` + // (not `$address`). `@type-binding.annotation` already strips `$` in + // `interpretPhpTypeBinding`; this mirrors that for the declaration side. + // + // Only applies to `@declaration.property` — typed class properties and + // constructor-promoted parameters. Untyped `@declaration.variable` keeps + // its `$` prefix (those defs are Variable type and not in the field + // registry, so their name doesn't affect member lookup). + if ( + grouped['@declaration.property'] !== undefined && + grouped['@declaration.name'] !== undefined + ) { + const nameCap = grouped['@declaration.name']; + if (nameCap.text.startsWith('$')) { + grouped['@declaration.name'] = { ...nameCap, text: nameCap.text.slice(1) }; + } + } + + // Normalize PHP receiver expressions so the compound-receiver resolver + // can walk chains expressed with `->` (PHP) as if they used `.` (the + // resolver's canonical separator). Without this, `$user->address->save()` + // has receiver text `$user->address` — the resolver sees no `.` separator, + // treats it as a bare identifier, and cannot walk field types. + // + // Transformation applied to `@reference.receiver` captures: + // 1. Replace `->` with `.` ($user->address → $user.address) + // 2. Strip leading `$` from each segment ($user.address → user.address) + // 3. Strip trailing `?` on null-safe receivers ($user? → user) + // + // This is a PHP-local normalization — no shared pipeline code is changed. + if (grouped['@reference.receiver'] !== undefined) { + const recvCap = grouped['@reference.receiver']!; + const normalized = normalizePhpReceiver(recvCap.text); + if (normalized !== recvCap.text) { + grouped['@reference.receiver'] = { ...recvCap, text: normalized }; + } + } + + // Normalize static property write: strip leading `$` from `@reference.name` + // so `User::$count` resolves to property `count` (stored without `$` in graph). + if (grouped['@reference.write.static'] !== undefined) { + const nameCap = grouped['@reference.name']; + if (nameCap !== undefined && nameCap.text.startsWith('$')) { + grouped['@reference.name'] = { + ...nameCap, + text: nameCap.text.slice(1), + }; + } + // Re-tag as @reference.write.member so downstream passes see a uniform write kind. + grouped['@reference.write.member'] = grouped['@reference.write.static']!; + delete grouped['@reference.write.static']; + } + + // Decompose each `namespace_use_declaration` so `interpretPhpImport` + // sees the kind/source/name/alias markers it consumes. + if (grouped['@import.statement'] !== undefined) { + const stmtCapture = grouped['@import.statement']; + const stmtNode = findNodeAtRange( + tree.rootNode, + stmtCapture.range, + 'namespace_use_declaration', + ); + if (stmtNode !== null) { + const decomposed = splitNamespaceUseDeclaration(stmtNode); + if (decomposed.length > 0) { + for (const d of decomposed) out.push(d); + continue; + } + } + // Defensive fallback: emit the raw match. + out.push(grouped); + continue; + } + + // Synthesize `$this` / `parent` receiver type-bindings on every + // non-static method-like. Mirrors C#'s `this` / `base` synthesis. + 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 synthesizePhpReceiverBinding(fnNode)) { + out.push(synth); + } + // Synthesize PHPDoc @param and @return type bindings for this fn. + for (const synth of synthesizePhpDocBindings(fnNode)) { + out.push(synth); + } + // Synthesize foreach loop variable bindings inside this fn body. + for (const synth of synthesizeForeachBindings(fnNode)) { + out.push(synth); + } + } + continue; + } + + // Synthesize arity metadata on function-like declarations so the + // registry can narrow overloads. + 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 = computePhpArityMetadata(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 call site so the registry's + // arity filter can narrow overloads. Count the `argument` children of + // the backing `arguments` node. Mirrors C#'s pattern (csharp/captures.ts + // lines 149-186). PHP needs this for arity-based dispatch (Cluster H). + const callTag = ( + ['@reference.call.free', '@reference.call.member', '@reference.call.constructor'] as const + ).find((t) => grouped[t] !== undefined); + if (callTag !== undefined && grouped['@reference.arity'] === undefined) { + const anchor = grouped[callTag]!; + const callNode = + findNodeAtRange(tree.rootNode, anchor.range, 'function_call_expression') ?? + findNodeAtRange(tree.rootNode, anchor.range, 'member_call_expression') ?? + findNodeAtRange(tree.rootNode, anchor.range, 'nullsafe_member_call_expression') ?? + findNodeAtRange(tree.rootNode, anchor.range, 'scoped_call_expression') ?? + findNodeAtRange(tree.rootNode, anchor.range, 'object_creation_expression'); + if (callNode !== null) { + const argList = callNode.childForFieldName('arguments'); + const args: SyntaxNode[] = []; + if (argList !== null) { + for (let i = 0; i < argList.namedChildCount; i++) { + const child = argList.namedChild(i); + if (child !== null && child.type === 'argument') args.push(child); + } + } + grouped['@reference.arity'] = syntheticCapture( + '@reference.arity', + callNode, + String(args.length), + ); + // Infer argument types from literal nodes for type-based narrowing. + // Non-literal arguments emit empty string ("unknown" = any-match). + const argTypes = args.map((arg) => inferPhpArgType(arg)); + grouped['@reference.parameter-types'] = syntheticCapture( + '@reference.parameter-types', + callNode, + JSON.stringify(argTypes), + ); + } + } + + out.push(grouped); + } + + return out; +} + +/** Find the first PHP function-like node at the given range. */ +function findFunctionNode(rootNode: SyntaxNode, range: Capture['range']): SyntaxNode | null { + for (const nodeType of FUNCTION_NODE_TYPES) { + const n = findNodeAtRange(rootNode, range, nodeType); + if (n !== null) return n as SyntaxNode; + } + return null; +} + +// ─── PHP receiver normalization ────────────────────────────────────────────── + +/** + * Normalize a PHP receiver expression so the language-agnostic + * compound-receiver resolver (which splits on `.`) can walk field-type chains. + * + * The compound-receiver resolver: + * - splits on `.` to get chain segments + * - looks up the first segment in `typeBindings` (keyed with `$` for variables) + * - walks subsequent segments as field names (stored without `$` in the graph) + * + * Transformation: + * 1. Replace `->` and `?->` with `.` so the resolver's splitter works + * 2. Strip any bare `?` fragment left by null-safe chain ends + * 3. Strip `$` from all segments EXCEPT the first (which is a variable + * and must keep `$` for typeBindings lookup — e.g. `$user → User`) + * + * Examples: + * `$user` → `$user` (bare variable — unchanged) + * `$user->address` → `$user.address` + * `$user->address->city` → `$user.address.city` + * `$user?` → `$user` (null-safe trailing `?` stripped) + * `$this` → `$this` (receiverBinding uses `$this`) + * `parent` → `parent` (super-receiver check) + */ +function normalizePhpReceiver(raw: string): string { + // Keep `$this`, `parent`, and `self` as-is. + if (raw === '$this' || raw === 'parent' || raw === 'self') return raw; + + // Replace `?->` (null-safe) and plain `->` with `.`. + let text = raw.replace(/\?->/g, '.').replace(/->/g, '.'); + // Strip a trailing `?` (null-safe fragment on the last object node). + text = text.replace(/\?$/, ''); + // Collapse any doubled dots from `?->` where `?` was on its own. + text = text.replace(/\.{2,}/g, '.'); + // Strip trailing dot. + text = text.replace(/\.$/, ''); + + // Split on `.` and strip `$` from all segments EXCEPT the first. + // The first segment is a PHP variable (typeBinding key includes `$`). + // Subsequent segments are property/method names (stored without `$`). + const segments = text.split('.'); + for (let i = 1; i < segments.length; i++) { + const s = segments[i]; + if (s !== undefined && s.startsWith('$')) segments[i] = s.slice(1); + } + return segments.join('.'); +} + +// ─── PHP argument type inference ───────────────────────────────────────────── + +/** + * Infer the PHP type of a call argument from its literal shape. + * Returns an empty string for non-literals (treated as "unknown" = any-match). + * Mirrors C#'s `inferArgType` helper. + */ +function inferPhpArgType(argNode: SyntaxNode): string { + // argument node wraps the actual expression + const expr = argNode.firstNamedChild ?? argNode; + switch (expr.type) { + case 'integer': + return 'int'; + case 'float': + return 'float'; + case 'string': + case 'encapsed_string': + case 'heredoc': + case 'nowdoc': + return 'string'; + case 'boolean': + case 'true': + case 'false': + return 'bool'; + case 'null': + return 'null'; + default: + return ''; + } +} + +// ─── PHPDoc synthesis ───────────────────────────────────────────────────────── + +/** PHP 8+ attribute_list nodes that appear between PHPDoc and method. */ +const SKIP_SIBLING_TYPES = new Set(['attribute_list', 'attribute', 'comment']); + +/** Regex for PHPDoc @param: standard `@param Type $name` */ +const PHPDOC_PARAM_RE = /@param\s+(\S+)\s+\$(\w+)/g; +/** Regex for PHPDoc @param: alternate `@param $name Type` */ +const PHPDOC_PARAM_ALT_RE = /@param\s+\$(\w+)\s+(\S+)/g; +/** Regex for PHPDoc @return: `@return Type` */ +const PHPDOC_RETURN_RE = /@return\s+(\S+)/; + +/** + * Normalize a PHP type string to a simple class name for binding purposes. + * Returns null for primitives or uninformative types. + * Mirrors `normalizePhpType` in `interpret.ts` but operates on raw PHPDoc strings. + */ +function normalizePhpDocType(raw: string): string | null { + let type = raw.trim(); + // Strip nullable prefix + if (type.startsWith('?')) type = type.slice(1).trim(); + // Strip array suffix: User[] → User + if (type.endsWith('[]')) type = type.slice(0, -2).trim(); + // Strip union with null/false/void + if (type.includes('|')) { + const parts = type + .split('|') + .map((p) => p.trim()) + .filter((p) => p !== 'null' && p !== 'false' && p !== 'void' && p !== 'mixed' && p !== ''); + if (parts.length !== 1) return null; + type = parts[0]; + } + // Strip intersection: take first part + if (type.includes('&')) { + const first = type.split('&')[0].trim(); + if (first === '') return null; + type = first; + } + // Strip generic wrapper: Collection → User + const genericMatch = type.match(/^\w[\w\\]*\s*<([^,<>]+)>$/); + if (genericMatch) { + type = genericMatch[1].trim(); + // Strip array suffix again inside generic + if (type.endsWith('[]')) type = type.slice(0, -2).trim(); + } + // Strip namespace qualifier: \App\Models\User → User + if (type.includes('\\')) { + const segs = type.split('\\').filter(Boolean); + type = segs[segs.length - 1] ?? type; + } + // Reject primitives + if (PHP_PRIMITIVES.has(type.toLowerCase())) return null; + // Must be a simple identifier + if (!/^\w+$/.test(type)) return null; + return type; +} + +const PHP_PRIMITIVES = new Set([ + 'int', + 'integer', + 'float', + 'double', + 'string', + 'bool', + 'boolean', + 'array', + 'object', + 'callable', + 'iterable', + 'null', + 'void', + 'never', + 'mixed', + 'false', + 'true', + 'self', + 'static', + 'parent', +]); + +/** + * Collect comment text from siblings immediately before `fnNode`. + * Skips PHP 8+ attribute_list nodes. + */ +function collectPrecedingComments(fnNode: SyntaxNode): string { + const texts: string[] = []; + let sibling = fnNode.previousSibling; + while (sibling !== null) { + if (sibling.type === 'comment') { + texts.unshift(sibling.text); + } else if (sibling.isNamed && !SKIP_SIBLING_TYPES.has(sibling.type)) { + break; + } + sibling = sibling.previousSibling; + } + return texts.join('\n'); +} + +/** + * Synthesize PHPDoc @param and @return type-binding captures for a + * method_declaration or function_definition node. + * + * PHPDoc @param Type $name → `@type-binding.parameter` match (anchored at fn body/return_type). + * PHPDoc @return Type → `@type-binding.return` match (anchored at fn name). + */ +function synthesizePhpDocBindings(fnNode: SyntaxNode): CaptureMatch[] { + if (fnNode.type !== 'method_declaration' && fnNode.type !== 'function_definition') return []; + + const commentBlock = collectPrecedingComments(fnNode); + if (commentBlock === '') return []; + + const out: CaptureMatch[] = []; + + // Anchor for parameter type-bindings: the function body (or return_type as fallback). + // The binding must be inside the function scope so it's visible to body statements. + const bodyNode = fnNode.childForFieldName('body'); + const anchorNode = bodyNode ?? fnNode; + + // ── @param annotations ──────────────────────────────────────────────────── + PHPDOC_PARAM_RE.lastIndex = 0; + let m: RegExpExecArray | null; + const seenParams = new Set(); + + while ((m = PHPDOC_PARAM_RE.exec(commentBlock)) !== null) { + const rawType = m[1]; + const paramName = '$' + m[2]; + const typeName = normalizePhpDocType(rawType); + if (typeName === null) continue; + seenParams.add(paramName); + out.push({ + '@type-binding.parameter': nodeToCapture('@type-binding.parameter', anchorNode), + '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, paramName), + '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeName), + }); + } + + // Also check alternate PHPDoc order: @param $name Type + PHPDOC_PARAM_ALT_RE.lastIndex = 0; + while ((m = PHPDOC_PARAM_ALT_RE.exec(commentBlock)) !== null) { + const paramName = '$' + m[1]; + if (seenParams.has(paramName)) continue; // standard format takes priority + const rawType = m[2]; + const typeName = normalizePhpDocType(rawType); + if (typeName === null) continue; + out.push({ + '@type-binding.parameter': nodeToCapture('@type-binding.parameter', anchorNode), + '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, paramName), + '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeName), + }); + } + + // ── @return annotation ──────────────────────────────────────────────────── + const returnMatch = PHPDOC_RETURN_RE.exec(commentBlock); + if (returnMatch !== null) { + const rawType = returnMatch[1]; + const typeName = normalizePhpDocType(rawType); + if (typeName !== null) { + // @return bindings must be anchored at the method name and hoisted to Module scope + // by phpBindingScopeFor (which checks for @type-binding.return presence). + // Use the function_definition/method_declaration node itself as the anchor — it + // coincides with the innermost scope's range, so auto-hoist kicks in. + const nameNode = fnNode.childForFieldName('name') ?? fnNode; + out.push({ + '@type-binding.return': nodeToCapture('@type-binding.return', fnNode), + '@type-binding.name': syntheticCapture('@type-binding.name', nameNode, nameNode.text), + '@type-binding.type': syntheticCapture('@type-binding.type', nameNode, typeName), + }); + } + } + + return out; +} + +// ─── Foreach synthesis ─────────────────────────────────────────────────────── + +/** + * Walk all `foreach_statement` nodes inside `fnNode` and synthesize + * `@type-binding.alias` captures binding the loop variable to the + * element type of the iterable. + * + * Supports: + * - `foreach ($users as $user)` — simple iterable variable + * - `foreach ($users as $k => $user)` — key→value pair + * - `foreach ($this->users as $user)` — member access iterable + * - `foreach (getUsers() as $user)` — NOT yet supported (needs return type) + * + * The element type is resolved by: + * 1. Looking up the iterable name in PHPDoc @param bindings already + * collected for this function (passed via typeBindingsByName). + * 2. Direct resolution when iterable's env type IS the element type + * (because PHPDoc normalizes `User[]` → `User` already). + */ +function synthesizeForeachBindings(fnNode: SyntaxNode): CaptureMatch[] { + if ( + fnNode.type !== 'method_declaration' && + fnNode.type !== 'function_definition' && + fnNode.type !== 'anonymous_function' && + fnNode.type !== 'arrow_function' + ) { + return []; + } + + const out: CaptureMatch[] = []; + + // Build a mini type map from the function's PHPDoc @param annotations. + // This is re-parsed here (not cached from synthesizePhpDocBindings) for simplicity; + // the cost is negligible given the small comment sizes. + const commentBlock = collectPrecedingComments(fnNode); + const paramTypeMap = buildParamTypeMap(commentBlock); + + // Walk the function body for foreach_statement nodes. + const bodyNode = fnNode.childForFieldName('body'); + if (bodyNode === null) return []; + collectForeachBindings(bodyNode, fnNode, paramTypeMap, out); + + return out; +} + +/** Build a map of `$paramName → elementTypeName` from PHPDoc @param in a comment block. */ +function buildParamTypeMap(commentBlock: string): Map { + const map = new Map(); + if (commentBlock === '') return map; + + PHPDOC_PARAM_RE.lastIndex = 0; + let m: RegExpExecArray | null; + while ((m = PHPDOC_PARAM_RE.exec(commentBlock)) !== null) { + const rawType = m[1]; + const paramName = '$' + m[2]; + const typeName = normalizePhpDocType(rawType); + if (typeName !== null) map.set(paramName, typeName); + } + PHPDOC_PARAM_ALT_RE.lastIndex = 0; + while ((m = PHPDOC_PARAM_ALT_RE.exec(commentBlock)) !== null) { + const paramName = '$' + m[1]; + if (map.has(paramName)) continue; + const rawType = m[2]; + const typeName = normalizePhpDocType(rawType); + if (typeName !== null) map.set(paramName, typeName); + } + return map; +} + +/** + * Walk a subtree and collect foreach_statement bindings. + * Recursively descends into all child nodes. + */ +function collectForeachBindings( + node: SyntaxNode, + fnNode: SyntaxNode, + paramTypeMap: Map, + out: CaptureMatch[], +): void { + if (node.type === 'foreach_statement') { + const synth = synthesizeSingleForeach(node, fnNode, paramTypeMap); + if (synth !== null) out.push(synth); + } + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child !== null) { + collectForeachBindings(child, fnNode, paramTypeMap, out); + } + } +} + +/** + * Synthesize a single `@type-binding.alias` match for a `foreach_statement`. + * + * AST structure for foreach_statement (tree-sitter-php): + * foreach ( as ) + * Named children (excluding body): first = iterable, second = value or pair. + */ +function synthesizeSingleForeach( + foreachNode: SyntaxNode, + fnNode: SyntaxNode, + paramTypeMap: Map, +): CaptureMatch | null { + // Collect non-body named children: [iterable, value_or_pair] + const bodyNode = foreachNode.childForFieldName('body'); + const children: SyntaxNode[] = []; + for (let i = 0; i < foreachNode.namedChildCount; i++) { + const child = foreachNode.namedChild(i); + if (child !== null && child !== bodyNode) children.push(child); + } + if (children.length < 2) return null; + + const iterableNode = children[0]; + const valueOrPair = children[1]; + + // Determine the loop variable node + let loopVarNode: SyntaxNode; + if (valueOrPair.type === 'pair') { + // $key => $value — use the last named child of the pair + const lastChild = valueOrPair.namedChild(valueOrPair.namedChildCount - 1); + if (lastChild === null) return null; + loopVarNode = + lastChild.type === 'by_ref' ? (lastChild.firstNamedChild ?? lastChild) : lastChild; + } else { + loopVarNode = + valueOrPair.type === 'by_ref' ? (valueOrPair.firstNamedChild ?? valueOrPair) : valueOrPair; + } + + // Loop variable must be a variable_name + if (loopVarNode.type !== 'variable_name') return null; + const loopVarName = loopVarNode.text; // e.g. '$user' + + // Resolve the element type from the iterable + let elementType: string | null = null; + + if (iterableNode.type === 'variable_name') { + // foreach ($users as $user) — look up $users in param map + const iterableName = iterableNode.text; // e.g. '$users' + elementType = paramTypeMap.get(iterableName) ?? null; + } else if (iterableNode.type === 'member_access_expression') { + // foreach ($this->users as $user) — property name is the field + const propNameNode = iterableNode.childForFieldName('name'); + if (propNameNode !== null) { + // Property stored with $ prefix in paramTypeMap (rare for $this->prop patterns) + // Try both with and without $ prefix + const propKey = '$' + propNameNode.text; + elementType = paramTypeMap.get(propKey) ?? null; + if (elementType === null) { + // Try to find the property type from the enclosing class + elementType = findClassPropertyElementType(iterableNode, fnNode); + } + } + } else if (iterableNode.type === 'function_call_expression') { + // foreach (getUsers() as $user) — use the function name as a type alias. + // The function's @return annotation produces a @type-binding.return binding + // in the Module scope (e.g. getUsers → User). The scope-extractor's + // followChainedRef will resolve $user → getUsers → User. + const funcNode = iterableNode.childForFieldName('function'); + if (funcNode !== null && funcNode.type === 'name') { + elementType = funcNode.text; // e.g. 'getUsers' — chain will be resolved later + } + } else if (iterableNode.type === 'member_call_expression') { + // foreach ($this->getUsers() as $user) — use the method name as a type alias. + const methodNameNode = iterableNode.childForFieldName('name'); + if (methodNameNode !== null) { + elementType = methodNameNode.text; // e.g. 'getUsers' + } + } + + if (elementType === null) return null; + + // Anchor the binding inside the foreach body so it's scoped to the loop. + const anchorNode = bodyNode ?? foreachNode; + + return { + '@type-binding.alias': nodeToCapture('@type-binding.alias', anchorNode), + '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, loopVarName), + '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, elementType), + }; +} + +/** + * Try to find the element type for `$this->property` member access by walking + * up from the foreach to the enclosing class and scanning the property declaration. + */ +function findClassPropertyElementType( + memberAccessNode: SyntaxNode, + fnNode: SyntaxNode, +): string | null { + const propNameNode = memberAccessNode.childForFieldName('name'); + if (propNameNode === null) return null; + const propName = propNameNode.text; + + // Walk up from fnNode to find the enclosing class declaration + let cur: SyntaxNode | null = fnNode.parent; + while (cur !== null) { + if (cur.type === 'class_declaration' || cur.type === 'trait_declaration') { + break; + } + cur = cur.parent; + } + if (cur === null) return null; + + // Find the property_declaration with matching variable_name '$propName' + const declList = cur.childForFieldName('body'); + if (declList === null) return null; + + for (let i = 0; i < declList.namedChildCount; i++) { + const child = declList.namedChild(i); + if (child === null || child.type !== 'property_declaration') continue; + for (let j = 0; j < child.namedChildCount; j++) { + const elem = child.namedChild(j); + if (elem === null || elem.type !== 'property_element') continue; + const varNameNode = elem.firstNamedChild; + if (varNameNode === null || varNameNode.text !== '$' + propName) continue; + // Found the property — get its element type from @var PHPDoc or native type + return extractPropertyElementType(child); + } + } + return null; +} + +/** Regex for PHPDoc @var: `@var Type` */ +const PHPDOC_VAR_RE = /@var\s+(\S+)/; + +/** + * Extract element type from a property_declaration node: + * 1. PHPDoc @var annotation on a preceding comment sibling + * 2. PHP 7.4+ native type field (non-array) + */ +function extractPropertyElementType(propDecl: SyntaxNode): string | null { + // Strategy 1: PHPDoc @var on a preceding comment sibling + let sibling = propDecl.previousSibling; + while (sibling !== null) { + if (sibling.type === 'comment') { + const m = PHPDOC_VAR_RE.exec(sibling.text); + if (m !== null) return normalizePhpDocType(m[1]); + } else if (sibling.isNamed && !SKIP_SIBLING_TYPES.has(sibling.type)) { + break; + } + sibling = sibling.previousSibling; + } + // Strategy 2: native type field — skip generic 'array' + const typeNode = propDecl.childForFieldName('type'); + if (typeNode === null) return null; + const typeName = typeNode.text.trim(); + if (typeName === 'array' || typeName === '') return null; + return normalizePhpDocType(typeName); +} diff --git a/gitnexus/src/core/ingestion/languages/php/import-decomposer.ts b/gitnexus/src/core/ingestion/languages/php/import-decomposer.ts new file mode 100644 index 000000000..f17456805 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/import-decomposer.ts @@ -0,0 +1,304 @@ +/** + * Decompose a PHP `namespace_use_declaration` into one or more + * `CaptureMatch` objects carrying the synthesized markers + * `@import.kind` / `@import.source` / `@import.name` / `@import.alias` + * that `interpretPhpImport` consumes. + * + * PHP import forms handled: + * + * use Foo\Bar; → namespace, localName=Bar + * use Foo\Bar as Baz; → alias, localName=Baz + * use function Foo\bar; → function, localName=bar + * use const Foo\BAR; → const, localName=BAR + * use Foo\{A, B as C}; → grouped: one match per clause + * use function Foo\{f, g as h}; → grouped function variants + * use const Foo\{X, Y as Z}; → grouped const variants + * + * Unlike C#'s decomposer this is 1:N — each grouped use_declaration + * fans out to one CaptureMatch per inner clause. + */ + +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js'; + +export type PhpImportKind = 'namespace' | 'alias' | 'function' | 'const'; + +interface PhpImportSpec { + readonly kind: PhpImportKind; + /** Full backslash-separated path (backslashes intact): `Foo\Bar\Baz`. */ + readonly source: string; + /** Local binding name — last source segment for plain imports, the + * alias identifier for aliased imports. */ + readonly name: string; + /** Present iff kind === 'alias'. */ + readonly alias?: string; + /** Anchor node for synthesized captures (range-wise). */ + readonly atNode: SyntaxNode; +} + +/** + * Decompose a `namespace_use_declaration` node into one `CaptureMatch` + * per logical import. Returns `[]` when the node is unrecognized or + * carries no resolvable clauses. + */ +export function splitNamespaceUseDeclaration(stmtNode: SyntaxNode): CaptureMatch[] { + if (stmtNode.type !== 'namespace_use_declaration') return []; + + // Detect qualifier keyword: `use function` / `use const` + // tree-sitter-php uses a `use_type` or `function`/`const` keyword + // child to distinguish them. We scan the raw text before the first + // backslash-path child. + const qualifier = detectQualifier(stmtNode); + + // Grouped use: `use Foo\{A, B as C}` — find namespace_use_group child. + const groupNode = findNamedChild(stmtNode, 'namespace_use_group'); + if (groupNode !== null) { + return decomposeGrouped(stmtNode, groupNode, qualifier); + } + + // Single use clause (possibly aliased). + const spec = parseSingleUseClause(stmtNode, qualifier); + if (spec === null) return []; + return [buildImportMatch(stmtNode, spec)]; +} + +// ── Qualifier detection ──────────────────────────────────────────────────── + +/** + * Return the qualifier keyword appearing after `use`: + * `'function'`, `'const'`, or `null` for plain namespace use. + * + * tree-sitter-php emits the qualifier as a `name` node with text + * "function" or "const" (not a keyword token in recent grammars), + * or as a dedicated `use_type` node. We inspect the node's raw text + * to be grammar-version-agnostic. + */ +function detectQualifier(node: SyntaxNode): PhpImportKind { + const raw = node.text; + // Match `use function` or `use const` at the start (after optional whitespace) + if (/^\s*use\s+function\s/i.test(raw)) return 'function'; + if (/^\s*use\s+const\s/i.test(raw)) return 'const'; + return 'namespace'; +} + +// ── Single clause parsing ────────────────────────────────────────────────── + +function parseSingleUseClause(node: SyntaxNode, qualifier: PhpImportKind): PhpImportSpec | null { + // A plain `namespace_use_declaration` has one or more + // `namespace_use_clause` named children (each clause is one import, + // comma-separated for multiple). For the single case there is one. + const clause = findNamedChild(node, 'namespace_use_clause'); + if (clause !== null) return parseUseClause(clause, qualifier); + + // Older grammar versions may put the qualified_name directly under + // the declaration node. Check for a qualified_name or name child. + const qualName = findNamedChild(node, 'qualified_name') ?? findNamedChild(node, 'name'); + if (qualName === null) return null; + const source = qualName.text.trim(); + if (source === '') return null; + return { + kind: qualifier, + source, + name: lastSegment(source), + atNode: node, + }; +} + +function parseUseClause(clause: SyntaxNode, qualifier: PhpImportKind): PhpImportSpec | null { + // namespace_use_clause: + // qualified_name (or name) + // optional: alias_clause → "as" name (some grammar versions) + // optional: bare name node (tree-sitter-php ≥ 0.22 emits the + // alias as a sibling `name` node + // directly, not inside alias_clause) + const qualName = findNamedChild(clause, 'qualified_name') ?? findNamedChild(clause, 'name'); + if (qualName === null) return null; + const source = qualName.text.trim(); + if (source === '') return null; + + // Strategy 1: explicit alias_clause wrapper (older grammar versions). + const aliasClause = findNamedChild(clause, 'alias_clause'); + if (aliasClause !== null) { + // alias_clause: "as" name + const aliasName = findNamedChild(aliasClause, 'name') ?? aliasClause.firstNamedChild; + const alias = aliasName?.text.trim() ?? ''; + if (alias === '') return null; + return { + kind: 'alias', + source, + name: alias, + alias, + atNode: clause, + }; + } + + // Strategy 2: bare sibling `name` node after the qualified_name. + // tree-sitter-php (≥ 0.22) emits `use Foo\Bar as Baz` as: + // namespace_use_clause + // qualified_name "Foo\Bar" + // name "Baz" ← alias, no alias_clause wrapper + // Detect by: clause has ≥2 named children AND the last named child is + // a `name` node that differs from the qualName node. + if (clause.namedChildCount >= 2) { + const lastChild = clause.namedChild(clause.namedChildCount - 1); + if (lastChild !== null && lastChild !== qualName && lastChild.type === 'name') { + const alias = lastChild.text.trim(); + if (alias !== '') { + return { + kind: 'alias', + source, + name: alias, + alias, + atNode: clause, + }; + } + } + } + + return { + kind: qualifier, + source, + name: lastSegment(source), + atNode: clause, + }; +} + +// ── Grouped use decomposition ────────────────────────────────────────────── + +/** + * Decompose `use Foo\Bar\{A, B as C, function f, const X}` into one + * `CaptureMatch` per inner clause. + * + * The leading prefix (`Foo\Bar`) is prepended to each inner path. + * Inner clauses can override the qualifier with their own `function` / + * `const` keyword inside the group. + */ +function decomposeGrouped( + stmtNode: SyntaxNode, + groupNode: SyntaxNode, + outerQualifier: PhpImportKind, +): CaptureMatch[] { + // The prefix is the qualified_name that precedes the `{...}` group. + const prefixNode = findNamedChild(stmtNode, 'qualified_name') ?? findNamedChild(stmtNode, 'name'); + const prefix = prefixNode?.text.trim() ?? ''; + + const out: CaptureMatch[] = []; + + for (let i = 0; i < groupNode.namedChildCount; i++) { + const child = groupNode.namedChild(i); + if (child === null) continue; + + // Each child in a group may be: + // namespace_use_clause — plain or aliased + // namespace_use_type — `function` or `const` qualifier inside group + // We detect an inline qualifier by checking the raw text of the clause. + if (child.type !== 'namespace_use_clause') continue; + + const innerQualifier = detectInnerQualifier(child) ?? outerQualifier; + const spec = parseInnerClause(child, prefix, innerQualifier); + if (spec !== null) { + out.push(buildImportMatch(stmtNode, spec)); + } + } + + return out; +} + +/** + * Detect an inline qualifier keyword inside a grouped clause. + * e.g. `use Foo\{function bar, const BAZ}` — each clause may start with + * `function` or `const`. + */ +function detectInnerQualifier(clause: SyntaxNode): PhpImportKind | null { + const raw = clause.text.trim(); + if (/^function\s/i.test(raw)) return 'function'; + if (/^const\s/i.test(raw)) return 'const'; + return null; +} + +function parseInnerClause( + clause: SyntaxNode, + prefix: string, + qualifier: PhpImportKind, +): PhpImportSpec | null { + const qualName = findNamedChild(clause, 'qualified_name') ?? findNamedChild(clause, 'name'); + if (qualName === null) return null; + + // Strip inline `function` / `const` text prefix if present in the text. + let innerPath = qualName.text.trim(); + innerPath = innerPath.replace(/^(?:function|const)\s+/i, '').trim(); + if (innerPath === '') return null; + + const source = prefix !== '' ? `${prefix}\\${innerPath}` : innerPath; + + // Strategy 1: explicit alias_clause wrapper (older grammar versions). + const aliasClause = findNamedChild(clause, 'alias_clause'); + if (aliasClause !== null) { + const aliasName = findNamedChild(aliasClause, 'name') ?? aliasClause.firstNamedChild; + const alias = aliasName?.text.trim() ?? ''; + if (alias === '') return null; + return { + kind: 'alias', + source, + name: alias, + alias, + atNode: clause, + }; + } + + // Strategy 2: bare sibling `name` node after the qualified_name (tree-sitter-php ≥ 0.22). + if (clause.namedChildCount >= 2) { + const lastChild = clause.namedChild(clause.namedChildCount - 1); + if (lastChild !== null && lastChild !== qualName && lastChild.type === 'name') { + const alias = lastChild.text.trim(); + if (alias !== '') { + return { + kind: 'alias', + source, + name: alias, + alias, + atNode: clause, + }; + } + } + } + + return { + kind: qualifier, + source, + name: lastSegment(innerPath), + atNode: clause, + }; +} + +// ── CaptureMatch builder ─────────────────────────────────────────────────── + +function buildImportMatch(stmtNode: SyntaxNode, spec: PhpImportSpec): CaptureMatch { + const m: Record = { + '@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), + }; + if (spec.alias !== undefined) { + m['@import.alias'] = syntheticCapture('@import.alias', spec.atNode, spec.alias); + } + return m; +} + +// ── Helpers ──────────────────────────────────────────────────────────────── + +/** Last backslash-separated segment: `Foo\Bar\Baz` → `Baz`. */ +function lastSegment(path: string): string { + const parts = path.split('\\').filter(Boolean); + return parts[parts.length - 1] ?? path; +} + +/** Find the first named child with a given node type. */ +function findNamedChild(node: SyntaxNode, type: string): SyntaxNode | null { + for (let i = 0; i < node.namedChildCount; i++) { + const child = node.namedChild(i); + if (child !== null && child.type === type) return child; + } + return null; +} diff --git a/gitnexus/src/core/ingestion/languages/php/import-target.ts b/gitnexus/src/core/ingestion/languages/php/import-target.ts new file mode 100644 index 000000000..ebf7938b3 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/import-target.ts @@ -0,0 +1,140 @@ +/** + * Adapter from `(ParsedImport, WorkspaceIndex)` → concrete file path. + * + * Delegates to the existing `resolvePhpImportInternal` (PSR-4 via + * composer.json + suffix matching fallback). The `WorkspaceIndex` is + * opaque at this layer; consumers wire a `PhpResolveContext` shape + * carrying `fromFile` + `allFilePaths`. + * + * `loadPhpComposerConfig` is the `ScopeResolver.loadResolutionConfig` + * implementation — it loads `composer.json` once per workspace pass and + * threads the parsed config into every subsequent `resolveImportTarget` + * call via the opaque `resolutionConfig` parameter. + * + * Returning `null` lets the finalize algorithm mark the edge as + * `linkStatus: 'unresolved'`. + */ + +import type { ParsedImport, WorkspaceIndex } from 'gitnexus-shared'; +import { resolvePhpImportInternal } from '../../import-resolvers/php.js'; +import type { ComposerConfig } from '../../language-config.js'; +import { readFileSync } from 'node:fs'; +import { join } from 'node:path'; + +export interface PhpResolveContext { + readonly fromFile: string; + readonly allFilePaths: ReadonlySet; +} + +// ─── loadResolutionConfig ────────────────────────────────────────────────── + +/** + * Load and parse `composer.json` from the repo root. Returns a + * `ComposerConfig` object (PSR-4 namespace → directory mappings) or + * `null` when no `composer.json` is present or it cannot be parsed. + * + * The result is threaded into each `resolvePhpImportInternal` call as + * the `composerConfig` argument. + */ +export function loadPhpComposerConfig(repoPath: string): ComposerConfig | null { + try { + const composerPath = join(repoPath, 'composer.json'); + const raw = readFileSync(composerPath, 'utf8'); + const parsed = JSON.parse(raw) as unknown; + if (typeof parsed !== 'object' || parsed === null) return null; + + const composer = parsed as Record; + const autoload = composer['autoload'] as Record | undefined; + if (autoload === undefined) return null; + + const psr4Raw = (autoload['psr-4'] ?? {}) as Record; + const psr4 = new Map(); + + for (const [ns, dirs] of Object.entries(psr4Raw)) { + // namespace prefix ends with `\` — keep as-is; resolver strips it + const normalizedNs = ns.replace(/\\$/, ''); + const dir = Array.isArray(dirs) ? dirs[0] : dirs; + if (typeof dir === 'string') { + // Normalize directory path (strip trailing slash) + const normalizedDir = dir.replace(/\/+$/, ''); + psr4.set(normalizedNs, normalizedDir); + } + } + + return { psr4 }; + } catch { + return null; + } +} + +// ─── resolvePhpImportTarget ──────────────────────────────────────────────── + +/** + * LanguageProvider-shaped adapter: `(ParsedImport, WorkspaceIndex) → string | null`. + * + * The `WorkspaceIndex` is `unknown` in the shared contract. The scope-resolution + * orchestrator hands us a `PhpResolveContext`-shaped object; narrow structurally + * rather than via a cast chain so unexpected shapes return `null` cleanly. + */ +export function resolvePhpImportTarget( + parsedImport: ParsedImport, + workspaceIndex: WorkspaceIndex, +): string | null { + const ctx = workspaceIndex as PhpResolveContext | undefined; + if ( + ctx === undefined || + typeof (ctx as { fromFile?: unknown }).fromFile !== 'string' || + !((ctx as { allFilePaths?: unknown }).allFilePaths instanceof Set) + ) { + return null; + } + if (parsedImport.kind === 'dynamic-unresolved') return null; + if (parsedImport.targetRaw === null || parsedImport.targetRaw === '') return null; + + const allFiles = ctx.allFilePaths as Set; + const normalizedFileList = [...allFiles].map((f) => f.replace(/\\/g, '/')); + const allFileList = [...allFiles]; + + return resolvePhpImportInternal( + parsedImport.targetRaw, + null, // composerConfig not available through LanguageProvider path + allFiles, + normalizedFileList, + allFileList, + undefined, + ); +} + +/** + * ScopeResolver-shaped adapter: `(targetRaw, fromFile, allFilePaths, resolutionConfig?) → string | null`. + * + * Used inside `scope-resolver.ts`. Accepts the optional `resolutionConfig` + * (a `ComposerConfig | null` loaded once per workspace by + * `loadPhpComposerConfig`) and threads it into `resolvePhpImportInternal`. + */ +export function resolvePhpImportTargetInternal( + targetRaw: string, + _fromFile: string, + allFilePaths: ReadonlySet, + resolutionConfig?: unknown, +): string | null { + if (targetRaw === '') return null; + + const composerConfig = + resolutionConfig !== undefined && resolutionConfig !== null + ? (resolutionConfig as ComposerConfig) + : null; + + const allFiles = allFilePaths as Set; + const normalizedFileList = [...allFiles].map((f) => f.replace(/\\/g, '/')); + const allFileList = [...allFiles]; + + return resolvePhpImportInternal( + targetRaw, + composerConfig, + allFiles, + normalizedFileList, + allFileList, + undefined, + ); +} diff --git a/gitnexus/src/core/ingestion/languages/php/index.ts b/gitnexus/src/core/ingestion/languages/php/index.ts new file mode 100644 index 000000000..9b549bc3d --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/index.ts @@ -0,0 +1,73 @@ +/** + * PHP scope-resolution hooks (RFC #909 Ring 3 LANG-php, #938). + * + * Public API barrel. Consumers should import from this file rather than + * the individual modules. + * + * Module layout (each file is a single concern): + * + * - `query.ts` — tree-sitter query + lazy parser/query singletons + * - `captures.ts` — `emitPhpScopeCaptures` orchestrator + * - `import-decomposer.ts` — each `namespace_use_declaration` → ParsedImport captures + * - `interpret.ts` — capture-match → `ParsedImport` / `ParsedTypeBinding` + * - `simple-hooks.ts` — small/no-op hooks made explicit + * - `receiver-binding.ts` — synthesize `$this` / `parent` type-bindings on + * instance-method entry + * - `merge-bindings.ts` — PHP `use` precedence (local > import > wildcard) + * - `arity.ts` — PHP arity compatibility (variadic, defaults) + * - `arity-metadata.ts` — synthesize arity metadata from declarations + * - `import-target.ts` — `(ParsedImport, WorkspaceIndex) → file path` adapter + * wrapping `resolvePhpImportInternal` (PSR-4 + composer.json) + * - `scope-resolver.ts` — `ScopeResolver` registered in `SCOPE_RESOLVERS` + * - `cache-stats.ts` — PROF_SCOPE_RESOLUTION cache hit/miss counters + * + * ## Known limitations + * + * The PHP registry-primary path intentionally does NOT resolve the following. + * Each is a conscious trade-off at migration time. + * + * 1. **Trait `$this` → using-class binding** — for methods defined in a + * trait, `$this` is synthesized as a binding to the trait itself. + * Resolving `$this` to the actual using-class type requires cross-file + * analysis of all `use TraitName;` declarations in class bodies. + * Deferred to a follow-up; trait method resolution falls back to the + * trait scope. + * + * 2. **Anonymous classes** — `new class extends Foo { }` have no stable + * class name and are skipped by receiver-binding synthesis. The class + * body is still scoped; member lookups inside it will fall back to + * free-call resolution. + * + * 3. **Dynamic property/method access** — `$obj->{$name}()` and + * `$$varName` are not followed. The dynamic receiver is ignored and + * the call falls through to the shared free-call resolver. + * + * 4. **Magic methods** — `__get`, `__set`, `__call`, `__callStatic` are + * not modeled as virtual dispatch; they appear as regular method + * declarations in the graph but calls that would route through them + * at runtime are not distinguished. + * + * 5. **Laravel facade magic** — `App::make(...)`, `Cache::get(...)` etc. + * resolve statically to the Facade class rather than the underlying + * bound implementation. Deferred to a Laravel-specific plugin. + * + * 6. **Intersection types in parameters** — `T&U $param` takes the first + * named part (`T`). This matches the legacy type-extractor's behavior. + * + * Shadow-harness corpus parity is the authoritative signal for which of + * these matter in practice. The CI parity gate blocks any PR that regresses + * either the legacy or registry-primary run of + * `test/integration/resolvers/php.test.ts`. + */ + +export { emitPhpScopeCaptures } from './captures.js'; +export { getPhpCaptureCacheStats, resetPhpCaptureCacheStats } from './cache-stats.js'; +export { interpretPhpImport, interpretPhpTypeBinding } from './interpret.js'; +export { phpMergeBindings } from './merge-bindings.js'; +export { phpArityCompatibility } from './arity.js'; +export { resolvePhpImportTarget, type PhpResolveContext } from './import-target.js'; +export { phpBindingScopeFor, phpImportOwningScope, phpReceiverBinding } from './simple-hooks.js'; +// NOTE: phpScopeResolver is intentionally NOT re-exported from this barrel. +// Importing it here would create a circular dependency: +// php.ts → php/index.js → php/scope-resolver.js → ../php.js +// Registry and other consumers must import directly from './php/scope-resolver.js'. diff --git a/gitnexus/src/core/ingestion/languages/php/interpret.ts b/gitnexus/src/core/ingestion/languages/php/interpret.ts new file mode 100644 index 000000000..8aa07a736 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/interpret.ts @@ -0,0 +1,250 @@ +/** + * Capture-match → semantic-shape interpreters for PHP. + * + * - `interpretPhpImport` → `ParsedImport` + * - `interpretPhpTypeBinding` → `ParsedTypeBinding` + * + * Import matches arrive pre-decomposed by `emitPhpScopeCaptures` (one + * CaptureMatch per logical import, with synthesized `@import.kind / + * source / name / alias` markers). Type-binding matches arrive from + * the raw query captures — each `@type-binding.*` anchor carries + * `@type-binding.name` + `@type-binding.type`. + */ + +import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared'; + +// ─── interpretImport ────────────────────────────────────────────────────── + +export function interpretPhpImport(captures: CaptureMatch): ParsedImport | null { + const kindCap = captures['@import.kind']; + const sourceCap = captures['@import.source']; + const nameCap = captures['@import.name']; + const aliasCap = captures['@import.alias']; + + const kind = kindCap?.text; + if (kind === undefined || sourceCap === undefined) return null; + + const source = sourceCap.text.trim(); + if (source === '') return null; + + switch (kind) { + case 'namespace': { + // `use Foo\Bar;` — PHP `use` is a NAMED import (binds the class + // `Bar`, not the namespace `Foo`). This differs from C# `using`, + // which is a true namespace import. Producing 'named' here makes + // `new Bar()` resolve to the imported class def. + const localName = nameCap?.text.trim() ?? lastSegment(source); + return { + kind: 'named', + localName, + importedName: localName, + targetRaw: source, + }; + } + case 'alias': { + // `use Foo\Bar as Baz;` + if (aliasCap === undefined) return null; + const alias = aliasCap.text.trim(); + if (alias === '') return null; + const importedName = lastSegment(source); + return { + kind: 'alias', + localName: alias, + importedName, + alias, + targetRaw: source, + }; + } + case 'function': { + // `use function Foo\bar;` — treat as named import; importedName is + // the function name (last segment). targetRaw is the full path. + const localName = nameCap?.text.trim() ?? lastSegment(source); + return { + kind: 'named', + localName, + importedName: localName, + targetRaw: source, + }; + } + case 'const': { + // `use const Foo\BAR;` — same shape as function. + const localName = nameCap?.text.trim() ?? lastSegment(source); + return { + kind: 'named', + localName, + importedName: localName, + targetRaw: source, + }; + } + default: + return null; + } +} + +// ─── interpretTypeBinding ───────────────────────────────────────────────── + +export function interpretPhpTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null { + const nameCap = captures['@type-binding.name']; + const typeCap = captures['@type-binding.type']; + if (nameCap === undefined || typeCap === undefined) return null; + + // Determine source from anchor captures. Order: most-specific first. + let source: TypeRef['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.alias'] !== undefined) source = 'assignment-inferred'; + else if (captures['@type-binding.return'] !== undefined) source = 'return-annotation'; + + let rawType: string | null; + + if (source === 'assignment-inferred') { + // `@type-binding.alias` captures cover several assignment RHS shapes: + // - `$alias = $u` → rawType = '$u' (variable alias) + // - `$u = getUser()` → rawType = 'getUser' (callable alias) + // - `$u = new User()` → rawType = 'User' (constructor — via @type-binding.constructor; handled below) + // - `$role = UserRole::Viewer` → rawType = 'UserRole' (enum/class constant) + // + // For variable aliases (`$u`), `normalizePhpType` returns null because + // `$` is not a word character. We must preserve the raw `$`-prefixed name + // so `followChainedRef` can walk the chain `$alias → $u → User`. + // For callable/class names, `normalizePhpType` strips qualifiers correctly. + const rawText = typeCap.text.trim(); + if (rawText.startsWith('$')) { + // Variable alias: keep as-is for chain-following. + rawType = rawText; + } else { + rawType = normalizePhpType(rawText); + } + } else { + // All other sources: strip PHP type decoration to get the simple class name: + // ?User → User (nullable prefix) + // User|null → User (union with null/false/void) + // User&Loggable → User (intersection — take first meaningful) + // Collection → User (PHPDoc generic wrapper) + // User[] → User (array suffix) + // \App\Models\User → User (backslash qualifier) + rawType = normalizePhpType(typeCap.text.trim()); + } + + if (rawType === null) return null; + + // PHP variable names include the `$` sigil (e.g. `$user`). Most + // bindings keep it because they are looked up via the variable + // (`$user->method()` finds binding `$user`). Property field bindings + // are different: `$user->address` looks up `address` (no sigil) on + // the User class. Property declarations carry source `'annotation'`, + // so we strip the leading `$` for that source only. + let boundName = nameCap.text.trim(); + if (source === 'annotation' && boundName.startsWith('$')) { + boundName = boundName.slice(1); + } + + return { boundName, rawTypeName: rawType, source }; +} + +// ─── Type normalization ─────────────────────────────────────────────────── + +/** + * Normalize a PHP type string to a simple class identifier, or `null` + * when the type is uninformative (primitive, void, mixed, self, etc.). + * + * Rules applied in order: + * 1. Strip nullable prefix `?` + * 2. Split on `|` (union) — keep only if exactly one non-null part + * 3. Take first part of `&` intersection + * 4. Strip array suffix `[]` + * 5. Strip generic wrapper `Collection` → `User` + * 6. Canonicalize leading backslash off: `\App\Models\User` → `App\Models\User` + * 7. Reject PHP primitive / pseudo types + * + * The qualified form is preserved on `TypeRef.rawName` so downstream PHP + * receiver resolution can distinguish `\App\Other\User` from a same-simple-name + * `User` reachable via `use`. Without this, fully-qualified type hints collapse + * to ambiguous simple names and resolve against the caller's scope chain + * instead of the explicit target the source named (Codex PR #1497 review, + * finding 1). + */ +export function normalizePhpType(raw: string): string | null { + // 1. Strip nullable prefix + let type = raw.startsWith('?') ? raw.slice(1).trim() : raw; + + // 2. Union type — keep only if one non-null/false/void part remains + if (type.includes('|')) { + const parts = type + .split('|') + .map((p) => p.trim()) + .filter((p) => p !== 'null' && p !== 'false' && p !== 'void' && p !== 'mixed' && p !== ''); + if (parts.length !== 1) return null; + type = parts[0]; + } + + // 3. Intersection type — take the first part + if (type.includes('&')) { + const first = type.split('&')[0].trim(); + if (first === '') return null; + type = first; + } + + // 4. Strip array suffix + if (type.endsWith('[]')) type = type.slice(0, -2).trim(); + + // 5. Strip single-arg generic wrapper: Collection → User + // Qualified inner types (Collection<\App\Models\User>) survive — the + // capture group preserves whatever the writer named. + const genericMatch = type.match(/^\w[\w\\]*\s*<([^,<>]+)>$/); + if (genericMatch) { + type = genericMatch[1].trim(); + } + + // 6. Canonicalize leading backslash off — keep the qualified path intact. + // `\App\Models\User` → `App\Models\User`. `App\Models\User` → unchanged. + // Unqualified `User` stays as `User`. The qualified form is the lookup + // key into the workspace QualifiedNameIndex (PHP defs are indexed by + // namespace-joined qualifiedName); the leading-backslash distinction in + // source is only an "absolute path" anchor, not part of the canonical key. + if (type.startsWith('\\')) type = type.replace(/^\\+/, ''); + + // 7. Reject primitives / pseudo-types + if (isPrimitiveOrPseudo(type)) return null; + + // Must be a (possibly qualified) PHP identifier — segments of word chars + // separated by single backslashes. Empty segments (consecutive backslashes, + // trailing backslash) are rejected. + if (!/^\w+(?:\\\w+)*$/.test(type)) return null; + + return type; +} + +const PHP_PRIMITIVE_TYPES = new Set([ + 'int', + 'integer', + 'float', + 'double', + 'string', + 'bool', + 'boolean', + 'array', + 'object', + 'callable', + 'iterable', + 'null', + 'void', + 'never', + 'mixed', + 'false', + 'true', + 'self', + 'static', + 'parent', +]); + +function isPrimitiveOrPseudo(type: string): boolean { + return PHP_PRIMITIVE_TYPES.has(type.toLowerCase()); +} + +/** Last backslash-separated segment: `Foo\Bar\Baz` → `Baz`. */ +function lastSegment(path: string): string { + const parts = path.split('\\').filter(Boolean); + return parts[parts.length - 1] ?? path; +} diff --git a/gitnexus/src/core/ingestion/languages/php/merge-bindings.ts b/gitnexus/src/core/ingestion/languages/php/merge-bindings.ts new file mode 100644 index 000000000..257496550 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/merge-bindings.ts @@ -0,0 +1,51 @@ +/** + * PHP shadowing precedence for the `mergeBindings` hook. + * + * Tier ranking (lower wins in shadowing): + * + * - 0: `local` — a class member, method, local variable, or parameter + * declared in this scope. + * - 1: `import` / `namespace` / `reexport` — `use Foo\Bar;`, + * `use Foo\Bar as Baz;`, `use function`, `use const`. + * All use-statement flavors that introduce a name sit at this tier. + * - 2: `wildcard` — grouped uses / wildcard imports (deferred; mapped + * here for completeness). + * + * Within a surviving tier we de-dup by `DefId`, last-write-wins so a + * `use` re-declared further down the file cleanly replaces the earlier + * binding. + */ + +import type { BindingRef } from 'gitnexus-shared'; + +const TIER_LOCAL = 0; +const TIER_IMPORT = 1; +const TIER_WILDCARD = 2; +const TIER_UNKNOWN = 3; + +function tierOf(b: BindingRef): number { + switch (b.origin) { + case 'local': + return TIER_LOCAL; + case 'reexport': + case 'import': + case 'namespace': + return TIER_IMPORT; + case 'wildcard': + return TIER_WILDCARD; + default: + return TIER_UNKNOWN; + } +} + +export function phpMergeBindings(bindings: readonly BindingRef[]): readonly BindingRef[] { + if (bindings.length === 0) return bindings; + + let bestTier = Number.POSITIVE_INFINITY; + for (const b of bindings) bestTier = Math.min(bestTier, tierOf(b)); + const survivors = bindings.filter((b) => tierOf(b) === bestTier); + + const seen = new Map(); + for (const b of survivors) seen.set(b.def.nodeId, b); + return [...seen.values()]; +} diff --git a/gitnexus/src/core/ingestion/languages/php/namespace-siblings.ts b/gitnexus/src/core/ingestion/languages/php/namespace-siblings.ts new file mode 100644 index 000000000..20b99d971 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/namespace-siblings.ts @@ -0,0 +1,335 @@ +/** + * PHP same-namespace cross-file visibility. + * + * In PHP, every class declared in `namespace Foo\Bar` is visible to all + * other files in the same namespace WITHOUT an explicit `use` statement. + * Without this pass, `Service.php` (namespace `App\Services`) can't see + * `User` declared in `Models.php` (namespace `App\Models`) unless + * `UserService.php` has an explicit `use App\Models\User` statement. + * + * More importantly, A.php (namespace `App\Models`) can return `Greeting` + * (same namespace `App\Models`) without importing it, and the compound- + * receiver resolver needs to find `Greeting` as a class binding in the + * scope chain. + * + * Implementation mirrors C#'s `namespace-siblings.ts`: + * 1. Extract the declared namespace from each PHP file's source. + * 2. Group class-like defs by namespace. + * 3. Inject sibling class defs into each file's Module scope's + * `bindingAugmentations` with `origin: 'namespace'`. + * 4. Also mirror return-type bindings from same-namespace siblings + * so cross-file chain-follow finds return types without explicit imports. + * + * Uses the PHP tree-sitter parser (via the lazy singleton in `query.ts`) + * to extract namespace declarations — same AST that `extractParsedFile` + * already parsed, reused via `treeCache` to avoid double-parsing. + */ + +import type { BindingRef, ParsedFile, Scope, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; +import { getPhpParser } from './query.js'; +import { getTreeSitterBufferSize } from '../../constants.js'; +import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js'; + +// ─── PHP file structure extraction ────────────────────────────────────────── + +interface PhpFileStructure { + /** The declared namespace (backslash-separated), or '' for global namespace. */ + readonly namespace: string; +} + +type PhpTree = ReturnType['parse']>; + +/** + * Extract the declared namespace from a PHP file's source. + * Uses the cached AST tree when available to avoid re-parsing. + */ +function extractPhpFileStructure(content: string, cachedTree: unknown): PhpFileStructure { + const tree = + (cachedTree as PhpTree | undefined) ?? + parseSourceSafe(getPhpParser(), content, undefined, { + bufferSize: getTreeSitterBufferSize(content), + }); + + // Walk top-level nodes looking for namespace_definition. + // PHP files have at most one namespace declaration (PSR-4 convention). + // `namespace_definition` has a `name:` field of type `namespace_name`. + const root = tree.rootNode; + for (let i = 0; i < root.namedChildCount; i++) { + const child = root.namedChild(i); + if (child === null) continue; + if (child.type === 'namespace_definition') { + const nameNode = child.childForFieldName('name'); + if (nameNode !== null) { + return { namespace: nameNode.text }; + } + } + } + + return { namespace: '' }; +} + +// ─── Augmentation bucket helper ───────────────────────────────────────────── + +function getAugmentationBucket( + augmentations: Map>, + scopeId: ScopeId, + name: string, +): BindingRef[] { + let scopeBindings = augmentations.get(scopeId); + if (scopeBindings === undefined) { + scopeBindings = new Map(); + augmentations.set(scopeId, scopeBindings); + } + let bucket = scopeBindings.get(name); + if (bucket === undefined) { + bucket = []; + scopeBindings.set(name, bucket); + } + return bucket; +} + +function isClassLikeDef(def: SymbolDefinition): boolean { + return ( + def.type === 'Class' || + def.type === 'Interface' || + def.type === 'Struct' || + def.type === 'Enum' || + def.type === 'Trait' + ); +} + +// ─── Public entry point ────────────────────────────────────────────────────── + +export interface PhpSiblingInputs { + readonly fileContents: ReadonlyMap; + readonly treeCache?: { get(filePath: string): unknown }; +} + +/** + * Side-channel cache populated by `populatePhpNamespaceSiblings` so that + * later visibility-check hooks (e.g., `isCallableVisibleFromCaller`) can + * look up a file's PHP namespace without re-parsing. Cleared at the start + * of every populate run so stale entries don't leak across resolutions. + */ +const namespaceByFilePath = new Map(); + +/** + * Read the cached PHP namespace for a given filePath. Returns `''` (global) + * when the file has no namespace_definition or hasn't been processed yet. + * Callers should only consult this AFTER either `populatePhpClassQualifiedNames` + * or `populatePhpNamespaceSiblings` has run for the current resolution. + */ +export function getPhpNamespaceForFile(filePath: string): string { + return namespaceByFilePath.get(filePath) ?? ''; +} + +/** + * Inject same-namespace class defs and return-type bindings into each + * PHP file's Module scope's `bindingAugmentations`. This makes classes + * in the same PHP namespace visible to each other without explicit `use` + * statements, mirroring PHP's actual runtime behavior. + * + * Uses `origin: 'namespace'` so `phpMergeBindings` tiers it below + * explicit `use` imports (`origin: 'import'`) and local declarations. + */ +export function populatePhpNamespaceSiblings( + parsedFiles: readonly ParsedFile[], + indexes: ScopeResolutionIndexes, + inputs: PhpSiblingInputs, +): void { + // Step 1: extract namespace structure for each file. Also seed the + // side-channel cache used by visibility-check hooks downstream. + namespaceByFilePath.clear(); + const structureByFile = new Map(); + for (const parsed of parsedFiles) { + const content = inputs.fileContents.get(parsed.filePath); + if (content === undefined) continue; + const cachedTree = inputs.treeCache?.get(parsed.filePath); + const struct = extractPhpFileStructure(content, cachedTree); + structureByFile.set(parsed.filePath, struct); + namespaceByFilePath.set(parsed.filePath, struct.namespace); + } + + // Step 2: group class-like defs and module scopes by namespace. + interface NamespaceBucket { + readonly scopes: { filePath: string; scopeId: ScopeId; scope: Scope }[]; + readonly classDefs: SymbolDefinition[]; + } + const buckets = new Map(); + const getBucket = (ns: string): NamespaceBucket => { + let b = buckets.get(ns); + if (b === undefined) { + b = { scopes: [], classDefs: [] }; + buckets.set(ns, b); + } + return b; + }; + + for (const parsed of parsedFiles) { + const struct = structureByFile.get(parsed.filePath); + if (struct === undefined) continue; + const ns = struct.namespace; + const bucket = getBucket(ns); + + // Register the file's module scope in the bucket. + const moduleScope = parsed.scopes.find((s) => s.kind === 'Module'); + if (moduleScope !== undefined) { + bucket.scopes.push({ + filePath: parsed.filePath, + scopeId: moduleScope.id, + scope: moduleScope, + }); + } + + // Collect class-like defs declared at the top-level of this file + // (defs in Class or Module scopes, excluding nested inner classes). + for (const scope of parsed.scopes) { + if (scope.kind !== 'Class') continue; + // Only top-level class scopes (parent is Module or Namespace scope). + if (scope.parent === null) continue; + const parentScope = parsed.scopes.find((s) => s.id === scope.parent); + if ( + parentScope === undefined || + (parentScope.kind !== 'Module' && parentScope.kind !== 'Namespace') + ) { + continue; + } + for (const def of scope.ownedDefs) { + if (isClassLikeDef(def)) { + bucket.classDefs.push(def); + break; // one class-like per scope + } + } + } + } + + const augmentations = indexes.bindingAugmentations as Map>; + + // Step 3: For each namespace bucket, inject sibling class bindings + // into every file's Module scope (that is NOT the declaring file). + for (const [, bucket] of buckets) { + // Build name → def map (simple name of qualifiedName). + const defsByName = new Map(); + for (const def of bucket.classDefs) { + const q = def.qualifiedName ?? ''; + const simpleName = q.includes('.') + ? q.slice(q.lastIndexOf('.') + 1) + : q.includes('\\') + ? q.slice(q.lastIndexOf('\\') + 1) + : q; + if (simpleName === '') continue; + const arr = defsByName.get(simpleName) ?? []; + arr.push(def); + defsByName.set(simpleName, arr); + } + + for (const { filePath, scopeId, scope } of bucket.scopes) { + for (const [name, defs] of defsByName) { + // Skip if already locally declared (origin: 'local' wins). + const local = scope.bindings.get(name); + if (local !== undefined && local.some((b) => b.origin === 'local')) continue; + + for (const def of defs) { + if (def.filePath === filePath) continue; // don't self-inject + const arr = getAugmentationBucket(augmentations, scopeId, name); + if (arr.some((b) => b.def.nodeId === def.nodeId)) continue; + arr.push({ def, origin: 'namespace' }); + } + } + } + } + + // Step 3b: Inject fully-qualified-name bindings into every PHP file's + // Module scope. PHP `\App\Models\User` (leading-backslash FQN) and + // `App\Models\User` (already-qualified relative) on a parameter or + // typed receiver must resolve to the exact namespace-qualified class + // regardless of which simple-name `User` the caller's `use` imports + // shadowed. The shared `findClassBindingInScope` scope-chain walk + // consumes these augmentations via `lookupBindingsAt`, so adding the + // qualified key on every file's module scope routes FQN-receivers to + // the right def. Codex PR #1497 review, finding 1. + // + // Cost: O(PHP files × class-like defs in the workspace) augmentation + // entries. Bounded and acceptable in practice — typical PHP projects + // have hundreds of files and classes, not tens of thousands. + for (const parsed of parsedFiles) { + const moduleScope = parsed.scopes.find((s) => s.kind === 'Module'); + if (moduleScope === undefined) continue; + const moduleScopeId = moduleScope.id; + + for (const [ns, bucket] of buckets) { + if (ns === '') continue; // global-namespace classes have no qualified form to register + for (const def of bucket.classDefs) { + const q = def.qualifiedName ?? ''; + const simpleName = q.includes('\\') ? q.slice(q.lastIndexOf('\\') + 1) : q; + if (simpleName === '') continue; + const fqn = `${ns}\\${simpleName}`; + const arr = getAugmentationBucket(augmentations, moduleScopeId, fqn); + if (arr.some((b) => b.def.nodeId === def.nodeId)) continue; + arr.push({ def, origin: 'namespace' }); + } + } + } + + // Step 4: Mirror return-type bindings from same-namespace sibling files. + // This enables chain-follow like `$c->greet()->save()` where `greet()` + // returns `Greeting` (declared in A.php, same namespace) and `Greeting` + // isn't imported in the calling file. Without this, the compound-receiver + // resolver can't resolve `Greeting` as a class binding in the importer's + // scope chain. + // + // Additionally, mirror from files that are imported via `use` (different + // namespace) so return types from dependencies are chain-followable too. + for (const parsed of parsedFiles) { + const moduleScope = parsed.scopes.find((s) => s.kind === 'Module'); + if (moduleScope === undefined) continue; + const moduleTypeBindings = moduleScope.typeBindings as Map< + string, + import('gitnexus-shared').TypeRef + >; + + const struct = structureByFile.get(parsed.filePath); + const ownNs = struct?.namespace ?? ''; + + // Collect namespaces accessible from this file: + // 1. Own namespace (same-ns siblings) + // 2. Namespaces of directly imported files (via parsedImports → targetRaw → PSR-4 namespace) + const accessibleFiles = new Set(); + + // Same-namespace siblings. + const sameBucket = buckets.get(ownNs); + if (sameBucket !== undefined) { + for (const { filePath } of sameBucket.scopes) { + if (filePath !== parsed.filePath) accessibleFiles.add(filePath); + } + } + + // Files directly imported by this file (finalized import edges). + const ownModuleScopeBindings = indexes.bindings.get(moduleScope.id); + if (ownModuleScopeBindings !== undefined) { + for (const [, refs] of ownModuleScopeBindings) { + for (const ref of refs) { + if (ref.origin === 'import' || ref.origin === 'namespace') { + const importFilePath = ref.def.filePath; + if (importFilePath !== parsed.filePath) { + accessibleFiles.add(importFilePath); + } + } + } + } + } + + // Mirror return-type bindings from accessible files. + for (const srcFilePath of accessibleFiles) { + const srcParsed = parsedFiles.find((p) => p.filePath === srcFilePath); + if (srcParsed === undefined) continue; + const srcModuleScope = srcParsed.scopes.find((s) => s.kind === 'Module'); + if (srcModuleScope === undefined) continue; + for (const [boundName, typeRef] of srcModuleScope.typeBindings) { + if (moduleTypeBindings.has(boundName)) continue; + moduleTypeBindings.set(boundName, typeRef); + } + } + } +} diff --git a/gitnexus/src/core/ingestion/languages/php/query.ts b/gitnexus/src/core/ingestion/languages/php/query.ts new file mode 100644 index 000000000..fa84c911f --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/query.ts @@ -0,0 +1,332 @@ +/** + * Tree-sitter query for PHP scope captures (RFC #909 Ring 3 LANG-php). + * + * Captures the structural skeleton the generic scope-resolution pipeline + * consumes: scopes (program/namespace/class/function), declarations + * (class-likes, method-likes, properties, variables), imports + * (namespace_use_declaration), type bindings (parameter annotations, + * property types, constructor-inferred locals, return types), and + * references (call sites, member writes). + * + * PHP specifics that shape this query: + * + * - `namespace_use_declaration` is an import only at top level / inside + * namespace blocks. Class-body `use_declaration` (trait-use) is a + * different node type and is NOT captured here. + * + * - `object_creation_expression` has `name` and `qualified_name` as + * direct children (no wrapping node). + * + * - `method_declaration` exposes a `return_type:` named field containing + * a `type` node, which may be `named_type`, `optional_type`, etc. + * + * - `property_element` has a `name:` field of type `variable_name`. + * + * - `variable_name` nodes always include the `$` sigil in their text. + * + * Exposes lazy `Parser` and `Query` singletons so callers don't pay + * tree-sitter init cost per file. + */ + +import Parser from 'tree-sitter'; +import Php from 'tree-sitter-php'; + +// tree-sitter-php exports `{ php, php_only, html }` in recent versions, or the +// language directly in older versions. +// +// IMPORTANT: must match the grammar used by the central parse phase +// (`src/core/tree-sitter/parser-loader.ts` line: `[SupportedLanguages.PHP]: PHP.php_only`). +// Using a different grammar variant causes tree-sitter to throw when running +// a query built against grammar A on a tree parsed by grammar B — this error +// is swallowed by `scope-extractor-bridge.ts`, producing silent empty results. +const Php_typed = Php as unknown as { php_only?: unknown; php?: unknown }; +const PHP_LANG = Php_typed.php_only ?? Php_typed.php ?? Php; + +const PHP_SCOPE_QUERY = ` +;; ── Scopes ──────────────────────────────────────────────────────────────── + +(program) @scope.module + +;; Both block-scoped and statement-scoped namespace declarations. +(namespace_definition) @scope.namespace + +(class_declaration) @scope.class +(interface_declaration) @scope.class +(trait_declaration) @scope.class +(enum_declaration) @scope.class + +(method_declaration) @scope.function +(function_definition) @scope.function +(anonymous_function) @scope.function +(arrow_function) @scope.function + +;; ── Declarations — types ────────────────────────────────────────────────── + +(class_declaration + name: (name) @declaration.name) @declaration.class + +(interface_declaration + name: (name) @declaration.name) @declaration.interface + +(trait_declaration + name: (name) @declaration.name) @declaration.trait + +(enum_declaration + name: (name) @declaration.name) @declaration.enum + +;; ── Declarations — methods / functions / constructors ───────────────────── + +(method_declaration + name: (name) @declaration.name) @declaration.method + +(function_definition + name: (name) @declaration.name) @declaration.function + +;; ── Declarations — properties ───────────────────────────────────────────── + +;; PHP 7.4+ typed property: private UserRepo $repo; +;; property_element has name: (variable_name) field. +;; Emits BOTH a declaration (so SemanticModel registers the property) AND a type-binding. +(property_declaration + type: (_) @type-binding.type + (property_element + name: (variable_name) @type-binding.name)) @type-binding.annotation + +(property_declaration + type: (_) + (property_element + name: (variable_name) @declaration.name)) @declaration.property + +;; Untyped property: public $id; — capture as plain declaration. +(property_declaration + (property_element + name: (variable_name) @declaration.name)) @declaration.variable + +;; ── Imports — namespace_use_declaration ─────────────────────────────────── +;; +;; Captures ALL forms: plain, alias, function/const qualifiers, and grouped. +;; The import-decomposer in captures.ts fans out grouped uses. +;; +;; NOTE: class-body use_declaration = trait-use, NOT an import. +;; Only namespace_use_declaration (top-level / namespace scope) is an import. + +(namespace_use_declaration) @import.statement + +;; ── Type bindings — parameters ──────────────────────────────────────────── + +;; simple_parameter with a type hint: function f(User $u) +;; type field is a 'type' supertype (named_type, optional_type, union_type, etc.) +(simple_parameter + type: (_) @type-binding.type + name: (variable_name) @type-binding.name) @type-binding.parameter + +;; property_promotion_parameter: function __construct(private User $u) +;; Emits type-binding so the constructor body can resolve $u as the typed param. +(property_promotion_parameter + type: (_) @type-binding.type + name: (variable_name) @type-binding.name) @type-binding.parameter + +;; Also emit a @type-binding.annotation for the promoted parameter so that +;; phpBindingScopeFor can hoist it to the Class scope (stripping the $ sigil). +;; This enables compound-receiver resolution: $user->address->save() resolves +;; address → Address via the Class scope's typeBindings. +;; The @type-binding.parameter above stays for constructor-body resolution ($address). +(property_promotion_parameter + type: (_) @type-binding.type + name: (variable_name) @type-binding.name) @type-binding.annotation + +;; Also emit a @declaration.property so SemanticModel registers the promoted +;; parameter as a class-owned property (enabling $obj->propName lookups). +(property_promotion_parameter + name: (variable_name) @declaration.name) @declaration.property + +;; ── Type bindings — local assignment: $u = new User() ───────────────────── + +;; new ClassName() — name is a direct child of object_creation_expression +(assignment_expression + left: (variable_name) @type-binding.name + right: (object_creation_expression + (name) @type-binding.type)) @type-binding.constructor + +;; new Foo\Bar\ClassName() — qualified_name wraps name +(assignment_expression + left: (variable_name) @type-binding.name + right: (object_creation_expression + (qualified_name + (name) @type-binding.type))) @type-binding.constructor + +;; ── Type bindings — $alias = $u (identifier alias) ─────────────────────── + +(assignment_expression + left: (variable_name) @type-binding.name + right: (variable_name) @type-binding.type) @type-binding.alias + +;; ── Type bindings — $u = factory() (free call return alias) ────────────── + +(assignment_expression + left: (variable_name) @type-binding.name + right: (function_call_expression + function: (name) @type-binding.type)) @type-binding.alias + +;; ── Type bindings — $u = $svc->getUser() (method call return alias) ─────── + +(assignment_expression + left: (variable_name) @type-binding.name + right: (member_call_expression + name: (name) @type-binding.type)) @type-binding.alias + +;; ── Type bindings — method return type ─────────────────────────────────── + +;; method_declaration exposes return_type: field (type node supertype). +;; named_type wraps the class name: function getUser(): User +(method_declaration + name: (name) @type-binding.name + return_type: (named_type + (name) @type-binding.type)) @type-binding.return + +;; nullable return type via optional_type: function getUser(): ?User +(method_declaration + name: (name) @type-binding.name + return_type: (optional_type + (named_type + (name) @type-binding.type))) @type-binding.return + +;; function_definition (top-level or namespace-level) return type: User +;; Enables cross-file return-type propagation for free functions. +(function_definition + name: (name) @type-binding.name + return_type: (named_type + (name) @type-binding.type)) @type-binding.return + +;; nullable return type for function_definition: ?User +(function_definition + name: (name) @type-binding.name + return_type: (optional_type + (named_type + (name) @type-binding.type))) @type-binding.return + +;; ── References — free calls: foo() ─────────────────────────────────────── + +(function_call_expression + function: (name) @reference.name) @reference.call.free + +;; ── References — member calls: $obj->method() ──────────────────────────── +;; +;; SAFETY-INVARIANT (Finding 1 of PR #1497 adversarial review): the name: +;; field is constrained to (name), NOT (_) — tree-sitter-php emits +;; variable_name nodes for dynamic method names ($obj->$method(), +;; $obj->{$method}()). Keeping the pattern at (name) is what suppresses +;; capture of those dynamic shapes. The resolver is structural-only and +;; cannot infer the bound method name from runtime values; relaxing this +;; pattern to (_) would silently emit zero-confidence false-positive +;; edges. Regression: test/fixtures/lang-resolution/php-dynamic-calls/. + +(member_call_expression + object: (_) @reference.receiver + name: (name) @reference.name) @reference.call.member + +;; ── References — null-safe member calls: $obj?->method() (PHP 8+) ───────── + +(nullsafe_member_call_expression + object: (_) @reference.receiver + name: (name) @reference.name) @reference.call.member + +;; ── References — static calls: X::method() ─────────────────────────────── +;; +;; Same SAFETY-INVARIANT as member_call_expression above: name: (name) +;; deliberately excludes variable_name so Class::$method() and +;; $className::$method() shapes do not capture. The receiver field uses +;; (_) because static dispatch on a variable receiver +;; ($className::method()) IS captured — but resolution falls through +;; harmlessly when $className has no class type binding. See +;; php-dynamic-calls/ regression suite. + +(scoped_call_expression + scope: (_) @reference.receiver + name: (name) @reference.name) @reference.call.member + +;; ── Type bindings — $x = X::Constant or $x = X::CASE (enum case) ───────── +;; Binds the variable to the class name X so member calls on $x dispatch +;; to X's methods (e.g. UserRole::Viewer → label()). +;; +;; tree-sitter-php emits class_constant_access_expression with two name +;; children: [0]=class/enum name, [1]=constant/case name. The dot-anchor +;; before (name) matches only the FIRST name child (the class). + +(assignment_expression + left: (variable_name) @type-binding.name + right: (class_constant_access_expression + . (name) @type-binding.type)) @type-binding.alias + +(assignment_expression + left: (variable_name) @type-binding.name + right: (class_constant_access_expression + (qualified_name + (name) @type-binding.type))) @type-binding.alias + +;; ── Type bindings — $x = SomeClass::staticFactory() ────────────────────── +;; Binds $x to the type returned by the static factory method, anchored on +;; the method name (chain-follow resolves the actual return type later). + +(assignment_expression + left: (variable_name) @type-binding.name + right: (scoped_call_expression + name: (name) @type-binding.type)) @type-binding.alias + +;; ── Type bindings — null-safe member-call result: $x = $a?->getY() ─────── + +(assignment_expression + left: (variable_name) @type-binding.name + right: (nullsafe_member_call_expression + name: (name) @type-binding.type)) @type-binding.alias + +;; ── References — constructor calls: new User() ─────────────────────────── + +(object_creation_expression + (name) @reference.name) @reference.call.constructor + +(object_creation_expression + (qualified_name + (name) @reference.name)) @reference.call.constructor + +;; ── References — member writes: $obj->prop = $x ────────────────────────── + +(assignment_expression + left: (member_access_expression + object: (_) @reference.receiver + name: (name) @reference.name)) @reference.write.member + +;; ── References — static property writes: User::$count = $x ────────────── +;; Uses @reference.write.static anchor so captures.ts can strip the leading +;; $ from the variable_name capture (static props are stored without $ in graph). +;; +;; SAFETY-INVARIANT (Finding 2 of PR #1497 adversarial review): no +;; read-access property capture exists in this query — dynamic property +;; reads ($obj->$prop, $obj->{$prop}) produce no captures, which is the +;; desired behavior for a structural-only resolver. Adding a read pattern +;; in the future MUST keep name: (name) (not (_)) to preserve the +;; suppression. Regression: php-dynamic-calls/ fixture dynamicPropertyRead. + +(assignment_expression + left: (scoped_property_access_expression + scope: (_) @reference.receiver + name: (variable_name) @reference.name)) @reference.write.static +`; + +let _parser: Parser | null = null; +let _query: Parser.Query | null = null; + +export function getPhpParser(): Parser { + if (_parser === null) { + _parser = new Parser(); + _parser.setLanguage(PHP_LANG as Parameters[0]); + } + return _parser; +} + +export function getPhpScopeQuery(): Parser.Query { + if (_query === null) { + _query = new Parser.Query(PHP_LANG as Parameters[0], PHP_SCOPE_QUERY); + } + return _query; +} diff --git a/gitnexus/src/core/ingestion/languages/php/receiver-binding.ts b/gitnexus/src/core/ingestion/languages/php/receiver-binding.ts new file mode 100644 index 000000000..79709fe61 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/receiver-binding.ts @@ -0,0 +1,136 @@ +/** + * Synthesize `@type-binding.self` captures for PHP instance methods — + * one for `$this` (always on non-static methods inside a type + * declaration) and optionally one for `parent` (only on class methods + * when the enclosing class has an explicit `base_clause`). + * + * Mirrors `languages/csharp/receiver-binding.ts` in structure. PHP's + * grammar doesn't give us a clean `.scm` pattern for "implicit receiver + * on every instance method inside an enclosing type" because `$this` is + * not a parameter — it's an implicit receiver. Synthesis in code is the + * same approach C# uses for `this` / `base`. + * + * ## Known limitations + * + * - **Trait `$this`**: for methods defined in a trait, `$this` is + * synthesized as a binding to the trait itself. The actual using-class + * type is not known at single-file parse time. V1 limitation — + * documented in `index.ts`. + * - **Anonymous classes**: skipped (no stable enclosing class name). + */ + +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js'; + +const TYPE_DECL_NODE_TYPES = new Set([ + 'class_declaration', + 'interface_declaration', + 'trait_declaration', + 'enum_declaration', +]); + +const FUNCTION_NODE_TYPES = new Set([ + 'method_declaration', + 'function_definition', + 'anonymous_function', + 'arrow_function', +]); + +/** Walk up to find the enclosing type declaration. */ +function findEnclosingTypeDeclaration(node: SyntaxNode): SyntaxNode | null { + let cur: SyntaxNode | null = node.parent; + while (cur !== null) { + if (TYPE_DECL_NODE_TYPES.has(cur.type)) return cur; + cur = cur.parent; + } + return null; +} + +function typeName(typeNode: SyntaxNode): string | null { + return typeNode.childForFieldName('name')?.text ?? null; +} + +/** + * Return the base class name from a `base_clause` child of the class node. + * `base_clause` contains a `qualified_name` or `name` child. + */ +function baseClauseText(typeNode: SyntaxNode): string | null { + for (let i = 0; i < typeNode.namedChildCount; i++) { + const child = typeNode.namedChild(i); + if (child === null || child.type !== 'base_clause') continue; + const nameNode = child.firstNamedChild; + if (nameNode === null) return null; + // Take last segment of qualified name (e.g. \App\Models\BaseModel → BaseModel) + const text = nameNode.text.trim(); + const segments = text.split('\\').filter(Boolean); + return segments[segments.length - 1] ?? text; + } + return null; +} + +/** Check whether this method has a `static_modifier` child. */ +function isStaticMethod(fnNode: SyntaxNode): boolean { + for (let i = 0; i < fnNode.namedChildCount; i++) { + const child = fnNode.namedChild(i); + if (child !== null && child.type === 'static_modifier') return true; + } + return false; +} + +/** + * Build zero, one, or two `@type-binding.self` matches for `fnNode`: + * + * - Returns `[]` if the function is free (no enclosing type), static, + * or the enclosing type has no resolvable name. + * - Returns one match (`$this`) for non-static methods inside a + * class / trait / interface / enum body. + * - Returns two matches (`$this` + `parent`) only when the function + * lives in a `class_declaration` that has an explicit `base_clause`. + * + * The caller is responsible for guaranteeing + * `FUNCTION_NODE_TYPES.has(fnNode.type)`. + */ +export function synthesizePhpReceiverBinding(fnNode: SyntaxNode): CaptureMatch[] { + if (!FUNCTION_NODE_TYPES.has(fnNode.type)) return []; + if (isStaticMethod(fnNode)) return []; + + const enclosingType = findEnclosingTypeDeclaration(fnNode); + if (enclosingType === null) return []; + + // Anonymous class — skip (no stable name). + if (enclosingType.type === 'anonymous_class_declaration') return []; + + const enclosingName = typeName(enclosingType); + if (enclosingName === null) return []; + + // Anchor the synthesized captures to the method body (compound_statement) + // so they land inside the function scope, not at the class scope. + // For interface/abstract methods that have no body, skip. + const bodyNode = + fnNode.childForFieldName('body') ?? + // arrow_function: body is the expression after `=>` + fnNode.childForFieldName('return_value'); + if (bodyNode === null) return []; + + const out: CaptureMatch[] = []; + out.push(buildReceiverMatch(bodyNode, '$this', enclosingName)); + + // `parent` applies only to class methods with an explicit base_clause. + if (enclosingType.type === 'class_declaration') { + const baseText = baseClauseText(enclosingType); + if (baseText !== null) { + out.push(buildReceiverMatch(bodyNode, 'parent', baseText)); + } + } + + return out; +} + +function buildReceiverMatch(anchorNode: SyntaxNode, name: string, typeText: string): CaptureMatch { + const m: Record = { + '@type-binding.self': nodeToCapture('@type-binding.self', anchorNode), + '@type-binding.name': syntheticCapture('@type-binding.name', anchorNode, name), + '@type-binding.type': syntheticCapture('@type-binding.type', anchorNode, typeText), + }; + return m; +} diff --git a/gitnexus/src/core/ingestion/languages/php/scope-resolver.ts b/gitnexus/src/core/ingestion/languages/php/scope-resolver.ts new file mode 100644 index 000000000..8b1fcf41b --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/scope-resolver.ts @@ -0,0 +1,421 @@ +/** + * PHP `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by + * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3 LANG-php). + * + * Third migration after Python and C#. See `pythonScopeResolver` for the + * canonical shape. + * + * ## Circular-import avoidance + * + * The old PR had `php/scope-resolver.ts` importing `phpProvider` from + * `../php.js` while `php.ts` imported `phpScopeResolver` from `./php/index.js` + * — undefined at module load. The canonical fix (mirroring C#): + * + * - `scope-resolver.ts` imports `phpProvider` from `../php.js` ✓ + * - `php.ts` imports individual hook FUNCTIONS from `./php/index.js` ✗ + * + * Node's ESM handles the cycle correctly because `phpProvider` is a named + * export that is live-binding — by the time `phpScopeResolver` is first + * read (lazily, at resolution time), `phpProvider` is fully initialized. + */ + +import type { ParsedFile } from 'gitnexus-shared'; +import { SupportedLanguages } from 'gitnexus-shared'; +import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js'; +import { + findReceiverTypeBinding, + populateClassOwnedMembers, +} from '../../scope-resolution/scope/walkers.js'; +import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js'; +import type { KnowledgeGraph } from '../../../graph/types.js'; +import type { GraphNodeLookup } from '../../scope-resolution/graph-bridge/node-lookup.js'; +import { + resolveCallerGraphId, + resolveDefGraphId, +} from '../../scope-resolution/graph-bridge/ids.js'; +import { narrowOverloadCandidates } from '../../scope-resolution/passes/overload-narrowing.js'; +import type { SemanticModel } from '../../model/semantic-model.js'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; +import type { SymbolDefinition } from 'gitnexus-shared'; +import { phpProvider } from '../php.js'; +import { phpArityCompatibility, phpMergeBindings } from './index.js'; +import { resolvePhpImportTargetInternal, loadPhpComposerConfig } from './import-target.js'; +import { populatePhpNamespaceSiblings, getPhpNamespaceForFile } from './namespace-siblings.js'; + +/** + * PHP MRO builder — extends the generic EXTENDS-only MRO with trait-use + * relationships encoded as IMPLEMENTS edges. + * + * PHP trait-use (`use TraitName;` inside a class body) is recorded in the + * graph as an IMPLEMENTS edge from the using class to the Trait node. The + * generic `buildMro` only walks EXTENDS edges, so trait methods are invisible + * to the MRO-based dispatch index. This variant: + * + * 1. Runs the generic `buildMro` (EXTENDS edges, Class defs only). + * 2. Indexes Trait defs from `parsedFiles` alongside Class defs. + * 3. Walks IMPLEMENTS edges; for each edge whose target resolves to a + * Trait DefId, prepends that Trait DefId to the source class's MRO. + * + * Trait methods are searched BEFORE parent-class methods (PHP semantics: + * a trait method shadows the parent-class method but is overridden by the + * using class's own methods). + */ +/** + * PHP free-call visibility check for `pickUniqueGlobalCallable`. Returns + * true when the candidate function is reachable from the caller's PHP + * namespace context, false when the cross-namespace bridge would be a + * false positive (e.g., `\App\Utils\format` is not visible from `\App` + * without an explicit `use function App\Utils\format;`). + * + * Rules (PHP semantics): + * 1. Same-namespace candidates are always visible. + * 2. Global-namespace candidates (no namespace prefix) are visible from + * every caller — PHP's global fallback for functions/constants. + * 3. Candidates in a different namespace are visible only when the + * caller has a `use function` import that matches the candidate's + * fully-qualified name. + */ +function phpIsCallableVisibleFromCaller(ctx: { + callerParsed: ParsedFile; + candidate: SymbolDefinition; +}): boolean { + const { callerParsed, candidate } = ctx; + const callerNs = getPhpNamespaceForFile(callerParsed.filePath); + const candNs = getPhpNamespaceForFile(candidate.filePath); + + // Global-namespace candidate: PHP falls back to global for functions + // and constants when the local namespace doesn't define them. + if (candNs === '') return true; + + // Same-namespace: caller can see the candidate without an explicit use. + if (candNs === callerNs) return true; + + // Cross-namespace: require an explicit `use function` import in the + // caller's parsedImports that matches the candidate's fully-qualified + // name. interpret.ts maps `use function Foo\bar` to a named import with + // localName = 'bar' and targetRaw = 'Foo\\bar'. + const candQualified = + candidate.qualifiedName === undefined + ? '' + : candNs !== '' && !candidate.qualifiedName.includes('\\') + ? `${candNs}\\${candidate.qualifiedName}` + : candidate.qualifiedName; + if (candQualified === '') return false; + return callerParsed.parsedImports.some( + (imp) => + imp.kind === 'named' && + imp.targetRaw.replace(/^\\+/, '') === candQualified.replace(/^\\+/, ''), + ); +} + +/** + * Compute the EXTENDS-only ancestor chain for every class — no trait + * augmentation. PHP semantics: `parent::method()` walks this view so + * that `parent::` resolves to the parent class's method, even when a + * composed trait shadows the same name. + * + * Returns the same shape as `buildPhpMro` so callers can swap views + * without changing dispatch logic. Just `buildMro` + `defaultLinearize` + * — no trait IMPLEMENTS edge walk. + */ +function buildPhpExtendsOnlyMro( + graph: KnowledgeGraph, + parsedFiles: readonly ParsedFile[], + nodeLookup: GraphNodeLookup, +): Map { + return buildMro(graph, parsedFiles, nodeLookup, defaultLinearize); +} + +function buildPhpMro( + graph: KnowledgeGraph, + parsedFiles: readonly ParsedFile[], + nodeLookup: GraphNodeLookup, +): Map { + // Step 1: run generic MRO (Class-only, EXTENDS-only). + const mro = buildMro(graph, parsedFiles, nodeLookup, defaultLinearize); + + // Step 2: build a graphId → defId map for ALL class-like defs including Traits. + // After the `isLinkableLabel` fix, Trait nodes are now indexed in nodeLookup. + const defIdByGraphId = new Map(); + for (const parsed of parsedFiles) { + for (const def of parsed.localDefs) { + if (def.type !== 'Class' && def.type !== 'Trait') continue; + const graphId = resolveDefGraphId(parsed.filePath, def, nodeLookup); + if (graphId !== undefined) defIdByGraphId.set(graphId, def.nodeId); + } + } + + // Step 2b: build a Set of Trait defIds for O(1) trait-vs-interface checks. + const traitDefIds = new Set(); + for (const parsed of parsedFiles) { + for (const def of parsed.localDefs) { + if (def.type === 'Trait') traitDefIds.add(def.nodeId); + } + } + + // Step 3: collect direct trait-use edges (IMPLEMENTS where target is a Trait). + // Maps class/trait defId → [traitDefId, ...] for direct `use TraitName;`. + const directTraitUse = new Map(); + for (const rel of graph.iterRelationshipsByType('IMPLEMENTS')) { + const sourceDefId = defIdByGraphId.get(rel.sourceId); + if (sourceDefId === undefined) continue; + const targetDefId = defIdByGraphId.get(rel.targetId); + if (targetDefId === undefined) continue; + if (!traitDefIds.has(targetDefId)) continue; + + let list = directTraitUse.get(sourceDefId); + if (list === undefined) { + list = []; + directTraitUse.set(sourceDefId, list); + } + if (!list.includes(targetDefId)) list.push(targetDefId); + } + + // Step 4: augment every class's MRO by prepending the traits used by + // any class in its ancestor chain (transitively closed). PHP semantics: + // a trait used by a parent class is also visible on the child, and a + // trait-using-trait chain is flattened to a single ancestor set. + // + // For each class, walk its (already-computed) EXTENDS-based MRO and + // collect all transitively-used traits via BFS — `trait A { use B; } + // trait B { use C; } class X { use A; }` must include C in X's MRO. + // Prepend them before the EXTENDS ancestors so the method dispatch + // index finds trait methods before falling back to the parent class + // hierarchy. + for (const [classDefId, extendsMro] of mro) { + const ancestorChain = [classDefId, ...extendsMro]; + const seeds: string[] = []; + for (const ancestorId of ancestorChain) { + for (const traitId of directTraitUse.get(ancestorId) ?? []) { + seeds.push(traitId); + } + } + const allTraits = collectTransitiveTraits(seeds, directTraitUse); + + if (allTraits.length > 0) { + // Prepend traits before EXTENDS ancestors: own class's traits first, + // then parent traits (in ancestor order). This ensures trait methods + // are found before falling back to the inheritance chain. + mro.set(classDefId, [...allTraits, ...extendsMro]); + } + } + + // Step 5: also insert Trait-only entries for classes that use traits + // directly but have no EXTENDS parents (not in `mro` yet). + for (const [classDefId, traits] of directTraitUse) { + if (!mro.has(classDefId) && !traitDefIds.has(classDefId)) { + // Class with no EXTENDS but with trait-use — add to MRO map. + const allTraits = collectTransitiveTraits([...traits], directTraitUse); + mro.set(classDefId, allTraits); + } + } + + return mro; +} + +/** + * Collect the transitive closure of traits reachable from the seed set. + * BFS over `directTraitUse` until fixpoint. The `seen` set guards against + * cycles (invalid PHP but defensively handled) and prevents duplicate + * entries when multiple seeds converge on the same trait. Insertion order + * is preserved — first-seen wins for MRO ordering. + */ +function collectTransitiveTraits( + seeds: readonly string[], + directTraitUse: ReadonlyMap, +): string[] { + const out: string[] = []; + const seen = new Set(); + const queue: string[] = [...seeds]; + while (queue.length > 0) { + const t = queue.shift()!; + if (seen.has(t)) continue; + seen.add(t); + out.push(t); + for (const next of directTraitUse.get(t) ?? []) { + if (!seen.has(next)) queue.push(next); + } + } + return out; +} + +/** + * Emit CALLS edges for PHP member-call sites whose receiver has no type + * binding (e.g. `mixed`-typed parameters, untyped variables). + * + * PHP is dynamically typed: a parameter declared as `mixed` (or with no + * type hint) cannot be resolved by the generic receiver-bound pass, which + * requires a `TypeRef` in scope. This hook does a workspace-wide method + * name lookup: when exactly one def in the workspace matches the called + * method name, emit the CALLS edge. + * + * Only fires for sites that are NOT already in `handledSites` and whose + * receiver has no type binding in the scope chain. Unique-name-match + * constraint avoids false positives for common method names. + */ +function phpEmitUnresolvedReceiverEdges( + graph: KnowledgeGraph, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], + nodeLookup: GraphNodeLookup, + handledSites: Set, + model: SemanticModel, +): number { + let emitted = 0; + const seen = new Set(); + + for (const parsed of parsedFiles) { + for (const site of parsed.referenceSites) { + if (site.kind !== 'call') continue; + if (site.explicitReceiver === undefined) continue; + + const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`; + if (handledSites.has(siteKey)) continue; + + // Only proceed when the receiver has NO type binding — it's unresolvable + // by the generic pass. This is the `mixed` / unannotated case. + const typeRef = findReceiverTypeBinding(site.inScope, site.explicitReceiver.name, scopes); + if (typeRef !== undefined) continue; + + // Workspace-wide lookup: collect all methods matching the called name. + // Filter out defs with no qualifiedName (legacy parse stubs without full + // metadata) and deduplicate by nodeId so reconcileOwnership double-registration + // doesn't inflate the count. + const allCandidates = model.methods.lookupMethodByName(site.name); + const seen2 = new Set(); + const candidates = allCandidates.filter((c) => { + if (c.qualifiedName === undefined) return false; + if (seen2.has(c.nodeId)) return false; + seen2.add(c.nodeId); + return true; + }); + if (candidates.length !== 1) continue; // ambiguous or missing — skip + + const fnDef = candidates[0]; + if (fnDef === undefined) continue; + + // Apply arity narrowing — a unique method name match is not enough + // when arity says the call is definitively incompatible (e.g., PHP + // f(int $req, ...$rest) called with zero args). This prevents the + // fallback from emitting edges that the receiver-bound pass already + // rejected for arity reasons. + if (narrowOverloadCandidates([fnDef], site.arity, site.argumentTypes).length === 0) { + continue; + } + + // Tighten the fallback further with an EXACT-required-arity gate + // (Finding 8 / U4): the first-stage `narrowOverloadCandidates` + // accepts any argCount in `min..max` (or `>= min` when variadic), + // which over-emits 0.6-confidence edges for common method names + // whose only workspace candidate has optional / defaulted params. + // For the fallback path only, require argCount === required for + // fixed-arity candidates. Variadic candidates keep the relaxed + // `argCount >= required` semantics (already enforced by the first- + // stage check, so no extra work here). + const min = fnDef.requiredParameterCount; + const hasVarArgs = + fnDef.parameterTypes !== undefined && + fnDef.parameterTypes.some((t) => t === '...' || t.startsWith('...')); + if ( + min !== undefined && + Number.isFinite(site.arity) && + site.arity >= 0 && + !hasVarArgs && + site.arity !== min + ) { + continue; + } + + const callerGraphId = resolveCallerGraphId(site.inScope, scopes, nodeLookup); + if (callerGraphId === undefined) continue; + const tgtGraphId = resolveDefGraphId(fnDef.filePath, fnDef, nodeLookup); + if (tgtGraphId === undefined) continue; + + handledSites.add(siteKey); + const relId = `rel:CALLS:${callerGraphId}->${tgtGraphId}`; + if (seen.has(relId)) continue; + seen.add(relId); + graph.addRelationship({ + id: relId, + sourceId: callerGraphId, + targetId: tgtGraphId, + type: 'CALLS', + confidence: 0.6, + reason: 'php-unresolved-receiver-fallback', + }); + emitted++; + } + } + return emitted; +} + +const phpScopeResolver: ScopeResolver = { + language: SupportedLanguages.PHP, + languageProvider: phpProvider, + importEdgeReason: 'php-scope: use', + + resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => + resolvePhpImportTargetInternal(targetRaw, fromFile, allFilePaths, resolutionConfig), + + loadResolutionConfig: (repoPath) => loadPhpComposerConfig(repoPath), + + // PHP LEGB-like precedence: local > import/namespace/reexport > wildcard. + // The per-scope id is unused by phpMergeBindings (tier ordering computed + // purely from BindingRef.origin), so we don't synthesize a Scope. + mergeBindings: (existing, incoming) => [...phpMergeBindings([...existing, ...incoming])], + + // Adapter: phpArityCompatibility uses (def, callsite); the contract is (callsite, def). + arityCompatibility: (callsite, def) => phpArityCompatibility(def, callsite), + + buildMro: (graph, parsedFiles, nodeLookup) => buildPhpMro(graph, parsedFiles, nodeLookup), + + // PHP-specific: parent::method() must walk inheritance only, skipping + // composed traits. See buildPhpExtendsOnlyMro and the super-branch use + // in `passes/receiver-bound-calls.ts`. + buildExtendsOnlyMro: (graph, parsedFiles, nodeLookup) => + buildPhpExtendsOnlyMro(graph, parsedFiles, nodeLookup), + + // PHP free-call visibility: cross-namespace candidates are blocked + // unless explicitly `use function`-imported by the caller. Prevents + // false-positive CALLS edges between unrelated namespaces sharing a + // function name. Same-namespace and global-namespace candidates pass + // unchanged. + isCallableVisibleFromCaller: phpIsCallableVisibleFromCaller, + + populateOwners: (parsed: ParsedFile) => populateClassOwnedMembers(parsed), + + // PHP same-namespace cross-file visibility — classes in the same + // PHP namespace are visible without explicit `use` statements. + // Mirrors C#'s `populateNamespaceSiblings`. + populateNamespaceSiblings: populatePhpNamespaceSiblings, + + // PHP uses `parent` for super-class dispatch (not `super()`). + isSuperReceiver: (text) => text.trim() === 'parent', + + // PHP is dynamically typed — field-fallback heuristic on so that + // method calls on `mixed`-typed receivers (no annotation) fall back + // to a workspace-wide name search rather than silently dropping the edge. + fieldFallbackOnMethodLookup: true, + + // PHP: allow free-call fallback to unique workspace-wide callable when + // lexical/import bindings miss. Needed for two cases: + // 1. `use function` imports where PSR-4 directory resolution is + // non-deterministic (multiple .php files in same namespace dir). + // 2. Unimported free calls within the same namespace (same-namespace + // visibility without an explicit use statement, e.g. test fixtures). + allowGlobalFreeCallFallback: true, + + // Return-type propagation on — PHP method signatures are authoritative + // enough for cross-file chain-follow. + propagatesReturnTypesAcrossImports: true, + + // PHP hoists method return-type bindings to the Module scope so + // `propagateImportedReturnTypes` can pick them up across files. + hoistTypeBindingsToModule: true, + + // PHP recovers member calls on `mixed`/untyped receivers via a + // workspace-wide unique-method-name lookup, mirroring the legacy DAG. + emitUnresolvedReceiverEdges: phpEmitUnresolvedReceiverEdges, +}; + +export { phpScopeResolver }; diff --git a/gitnexus/src/core/ingestion/languages/php/simple-hooks.ts b/gitnexus/src/core/ingestion/languages/php/simple-hooks.ts new file mode 100644 index 000000000..89a9a2658 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/php/simple-hooks.ts @@ -0,0 +1,134 @@ +/** + * Trivial / no-op-ish hooks for the PHP provider. Made explicit so + * reviewers don't have to re-derive the analysis from "absence == default". + */ + +import type { + CaptureMatch, + ParsedImport, + Scope, + ScopeId, + ScopeTree, + TypeRef, +} from 'gitnexus-shared'; + +// ─── bindingScopeFor ────────────────────────────────────────────────────── + +/** + * PHP method return-type bindings (`@type-binding.return`) must hoist + * to the enclosing Module scope so `propagateImportedReturnTypes` can + * mirror them across files. Without this hoist, the return binding gets + * stuck at the Class scope and is invisible to the cross-file propagation + * pass that reads only `sourceModule.typeBindings`. + * + * All other bindings delegate to the default "innermost scope" rule. + */ +export function phpBindingScopeFor( + decl: CaptureMatch, + innermost: Scope, + tree: ScopeTree, +): ScopeId | null { + if (decl['@type-binding.return'] !== undefined) { + let cur: Scope | undefined = innermost; + while (cur !== undefined && cur.kind !== 'Module') { + const parentId: ScopeId | null = cur.parent ?? null; + if (parentId === null) break; + cur = tree.getScope(parentId); + } + if (cur !== undefined && cur.kind === 'Module') return cur.id; + } + + // Constructor-promoted properties (`function __construct(public User $u)`) + // are declared inside the constructor's Function scope in the AST, but they + // are class-owned fields. Hoist the @declaration.property binding to the + // enclosing Class scope so `populateClassOwnedMembers` assigns the correct + // ownerId and `findOwnedMember` can resolve `$obj->u`. + if (decl['@declaration.property'] !== undefined && innermost.kind === 'Function') { + let cur: Scope | undefined = innermost; + while (cur !== undefined && cur.kind !== 'Class') { + const parentId: ScopeId | null = cur.parent ?? null; + if (parentId === null) break; + cur = tree.getScope(parentId); + } + if (cur !== undefined && cur.kind === 'Class') return cur.id; + } + + // Constructor-promoted property TYPE BINDING (`function __construct(public Address $address)`) + // produces both a @type-binding.parameter (stays in Function scope for `$address` lookups + // inside the constructor body) AND a @type-binding.annotation (query.ts). The annotation + // capture is emitted so this hoist branch can place `address → Address` in the CLASS scope. + // + // The compound-receiver resolver (`resolveCompoundReceiverClass`) reads typeBindings from + // the class scope: `cs.typeBindings.get('address')`. Without hoisting, `$user->address->save()` + // fails to resolve `address` because the type binding is in the constructor's Function scope. + // + // `@type-binding.annotation` for a promoted param appears with innermost = Function scope + // (the constructor). Regular typed class properties (`private Address $addr;`) have their + // annotation already in the Class scope, so this branch only fires for promoted params. + if (decl['@type-binding.annotation'] !== undefined && innermost.kind === 'Function') { + let cur: Scope | undefined = innermost; + while (cur !== undefined && cur.kind !== 'Class') { + const parentId: ScopeId | null = cur.parent ?? null; + if (parentId === null) break; + cur = tree.getScope(parentId); + } + if (cur !== undefined && cur.kind === 'Class') return cur.id; + } + + return null; +} + +// ─── importOwningScope ──────────────────────────────────────────────────── + +/** + * Determine which scope owns a `use` import declaration. + * + * - `use` inside `namespace Foo { }` → attach to that Namespace scope. + * - Top-level `use` (no enclosing namespace) → innermost (Module). + * - `use TraitName;` inside a class body → this is a trait-use + * (heritage), NOT a namespace import. The grammar emits + * `use_declaration` for trait-use (distinct from + * `namespace_use_declaration`). Our query only captures + * `namespace_use_declaration`, so trait-use never reaches this hook + * in practice. Returning `null` here is a safety fallback. + */ +export function phpImportOwningScope( + _imp: ParsedImport, + innermost: Scope, + _tree: ScopeTree, +): ScopeId | null { + // Namespace-scoped or module-scoped imports attach to the innermost scope + // (either Namespace or Module). Class-scoped imports should not occur for + // namespace_use_declaration; if they do, attach to the class scope. + if ( + innermost.kind === 'Namespace' || + innermost.kind === 'Module' || + innermost.kind === 'Class' || + innermost.kind === 'Function' + ) { + return innermost.id; + } + return null; +} + +// ─── receiverBinding ────────────────────────────────────────────────────── + +/** + * Look up `$this` or `parent` in the function scope's type bindings. + * + * Both are synthesized as `@type-binding.self` captures during capture + * emission (`receiver-binding.ts`) — `$this` for every non-static + * method inside a class/trait/interface/enum body, `parent` additionally + * for class methods with an explicit `base_clause`. + * + * Returns `null` for: + * - static methods (no `$this` synthesized) + * - free functions (no enclosing class) + * - non-Function scopes + */ +export function phpReceiverBinding(functionScope: Scope): TypeRef | null { + if (functionScope.kind !== 'Function') return null; + return ( + functionScope.typeBindings.get('$this') ?? functionScope.typeBindings.get('parent') ?? null + ); +} diff --git a/gitnexus/src/core/ingestion/registry-primary-flag.ts b/gitnexus/src/core/ingestion/registry-primary-flag.ts index e063ce20c..6818007a3 100644 --- a/gitnexus/src/core/ingestion/registry-primary-flag.ts +++ b/gitnexus/src/core/ingestion/registry-primary-flag.ts @@ -72,6 +72,7 @@ export const MIGRATED_LANGUAGES: ReadonlySet = new Set; + /** + * Optional parallel MRO that EXCLUDES mixin-like augmentation (e.g., PHP + * traits). Returns the inheritance-only ancestor chain — the same kind + * of map as `buildMro` but built only from inheritance edges (EXTENDS). + * + * Used by the shared super-branch dispatch in `receiver-bound-calls` + * so that `parent::method()` walks the inheritance chain only, not the + * trait-augmented one. PHP semantics: `parent::` explicitly bypasses + * traits, even when a composed trait shadows a same-named parent method. + * + * Languages without mixin-like semantics leave this undefined — callers + * fall back to `buildMro`/`mroFor`, which for those languages is already + * the inheritance chain. + */ + readonly buildExtendsOnlyMro?: ( + graph: KnowledgeGraph, + parsedFiles: readonly ParsedFile[], + nodeLookup: GraphNodeLookup, + ) => Map; + /** * Mutate `parsed.localDefs[i].ownerId` to point at the structural * owner. Python's rule: methods (Function defs whose parent scope @@ -484,6 +504,26 @@ export interface ScopeResolver { */ readonly isFileLocalDef?: (def: SymbolDefinition) => boolean; + /** + * Optional predicate to gate free-call fallback emission by caller-side + * visibility. When provided, `pickUniqueGlobalCallable` rejects candidates + * the caller cannot legally reach — e.g., a PHP function in a different + * namespace with no `use function` import, which PHP runtime would treat + * as `Call to undefined function`. Returning `false` blocks the candidate; + * returning `true` allows it; undefined-default keeps current behavior + * (no visibility filtering, equivalent to "all candidates visible"). + * + * The hook receives the caller's `ParsedFile` (so it can consult + * `parsedImports`, `moduleScope`, etc.) and the candidate `SymbolDefinition`. + * The predicate must be pure: same inputs → same answer. + * + * Languages without namespace-scoped function resolution leave this undefined. + */ + readonly isCallableVisibleFromCaller?: (ctx: { + readonly callerParsed: ParsedFile; + readonly candidate: SymbolDefinition; + }) => boolean; + /** * Optional post-finalize hook to inject cross-file bindings that * aren't modeled via explicit imports. Runs after @@ -576,4 +616,32 @@ export interface ScopeResolver { readonly treeCache?: { get(filePath: string): unknown }; }, ) => void; + + /** + * Optional post-resolution pass: emit CALLS edges for member-call sites + * whose receiver cannot be typed by the scope chain (no `TypeRef`). + * Dynamically-typed languages with untyped/`mixed`/`Any` parameters use + * this hook to recover the call edge via workspace-wide method-name + * lookup, mirroring what their legacy resolvers did. + * + * Runs AFTER `emitReceiverBoundCalls` and BEFORE `emitFreeCallFallback`. + * Implementations MUST: + * - Skip sites already in `handledSites` (Invariant I2). + * - Add resolved site keys to `handledSites` before returning. + * - Stay narrow: a unique workspace-wide match is the safe baseline. + * Multi-candidate fallbacks should narrow by arity / argument types + * before emitting to keep false-positive rate bounded. + * + * Returns the number of edges emitted (for telemetry). + * + * Default: undefined (no unresolved-receiver fallback). + */ + readonly emitUnresolvedReceiverEdges?: ( + graph: KnowledgeGraph, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], + nodeLookup: GraphNodeLookup, + handledSites: Set, + model: SemanticModel, + ) => number; } diff --git a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/method-dispatch.ts b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/method-dispatch.ts index 164147ac6..419ab478f 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/method-dispatch.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/method-dispatch.ts @@ -22,8 +22,9 @@ const EMPTY_DEFS: readonly string[] = Object.freeze([]); export function buildPopulatedMethodDispatch( mroByDefId: ReadonlyMap, + extendsOnlyMroByDefId?: ReadonlyMap, ): MethodDispatchIndex { - return { + const base: MethodDispatchIndex = { mroByOwnerDefId: mroByDefId, implsByInterfaceDefId: new Map(), mroFor(ownerDefId) { @@ -33,4 +34,14 @@ export function buildPopulatedMethodDispatch( return EMPTY_DEFS; }, }; + if (extendsOnlyMroByDefId !== undefined) { + return { + ...base, + extendsOnlyMroByOwnerDefId: extendsOnlyMroByDefId, + extendsOnlyMroFor(ownerDefId) { + return extendsOnlyMroByDefId.get(ownerDefId) ?? EMPTY_DEFS; + }, + }; + } + return base; } diff --git a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts index 70aa875fb..c3b53c6f7 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts @@ -117,6 +117,11 @@ export function isLinkableLabel(label: NodeLabel): boolean { label === 'Interface' || label === 'Struct' || label === 'Enum' || + // Trait nodes are linkable so MRO builders can bridge PHP/Rust trait + // defs between scope-resolution DefIds and the graph's node ids. + // IMPLEMENTS edges from classes to traits are otherwise invisible to + // the scope-resolution MRO pass. + label === 'Trait' || // Variable / Property are linkable too — receiver-bound write/read // ACCESSES edges target field nodes (e.g. `user.name = "x"` → // ACCESSES edge to User's `name` Variable/Property node). diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts index 44f941daf..eb6dd71fb 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts @@ -39,6 +39,10 @@ export function emitFreeCallFallback( options: { readonly allowGlobalFallback?: boolean; readonly isFileLocalDef?: (def: SymbolDefinition) => boolean; + readonly isCallableVisibleFromCaller?: (ctx: { + readonly callerParsed: ParsedFile; + readonly candidate: SymbolDefinition; + }) => boolean; } = {}, ): number { let emitted = 0; @@ -82,6 +86,11 @@ export function emitFreeCallFallback( scopes, parsed.filePath, options.isFileLocalDef, + site.arity, + options.isCallableVisibleFromCaller !== undefined + ? (candidate) => + options.isCallableVisibleFromCaller!({ callerParsed: parsed, candidate }) + : undefined, ); } if (fnDef === undefined) continue; @@ -118,6 +127,8 @@ function pickUniqueGlobalCallable( scopes: ScopeResolutionIndexes, callerFilePath: string, isFileLocalDef?: (def: SymbolDefinition) => boolean, + callArity?: number, + isCallerVisible?: (candidate: SymbolDefinition) => boolean, ): SymbolDefinition | undefined { const scopeDefs: SymbolDefinition[] = []; const scopeSeen = new Set(); @@ -130,6 +141,13 @@ function pickUniqueGlobalCallable( if (isFileLocalDef !== undefined && def.filePath !== callerFilePath && isFileLocalDef(def)) { continue; } + // Caller-side visibility filter (e.g., PHP namespace + use-function + // import gating). When defined, blocks candidates the caller cannot + // legally reach. Languages without namespace-scoped function resolution + // leave this undefined → no filtering. + if (isCallerVisible !== undefined && !isCallerVisible(def)) { + continue; + } const key = logicalCallableKey(def); if (scopeSeen.has(key)) continue; scopeSeen.add(key); @@ -137,6 +155,15 @@ function pickUniqueGlobalCallable( } if (scopeDefs.length === 1) return scopeDefs[0]; + // When multiple scope-index candidates exist, attempt arity narrowing + // before falling back to the semantic-model lookup. This handles + // registry-primary languages where the model is not populated for the + // migrated language's files (call-processor skips them). + if (scopeDefs.length > 1 && callArity !== undefined) { + const arityMatch = narrowByArity(scopeDefs, callArity); + if (arityMatch !== undefined) return arityMatch; + } + const defs: SymbolDefinition[] = []; const seen = new Set(); const push = (pool: readonly SymbolDefinition[]): void => { @@ -147,6 +174,10 @@ function pickUniqueGlobalCallable( if (isFileLocalDef !== undefined && def.filePath !== callerFilePath && isFileLocalDef(def)) { continue; } + // Same caller-visibility filter applied to the model-side pool. + if (isCallerVisible !== undefined && !isCallerVisible(def)) { + continue; + } const key = logicalCallableKey(def); if (seen.has(key)) continue; seen.add(key); @@ -157,7 +188,35 @@ function pickUniqueGlobalCallable( push(model.symbols.lookupCallableByName(name)); push(model.methods.lookupMethodByName(name)); - return defs.length === 1 ? defs[0] : undefined; + if (defs.length === 1) return defs[0]; + + // When multiple candidates exist and the call site has a known arity, + // narrow by parameter count. + if (defs.length > 1 && callArity !== undefined) { + const arityMatch = narrowByArity(defs, callArity); + if (arityMatch !== undefined) return arityMatch; + } + + return undefined; +} + +/** + * Narrow a list of callable candidates by call-site arity. + * A def is compatible when `requiredParameterCount <= arity <= parameterCount`. + * Defs with `parameterCount === undefined` (variadic/unknown) are always kept. + * Returns the single compatible def, or `undefined` when zero or multiple match. + */ +function narrowByArity( + defs: readonly SymbolDefinition[], + callArity: number, +): SymbolDefinition | undefined { + const compatible = defs.filter((d) => { + const total = d.parameterCount; + if (total === undefined) return true; // unknown arity — keep + const required = d.requiredParameterCount ?? total; + return required <= callArity && callArity <= total; + }); + return compatible.length === 1 ? compatible[0] : undefined; } function logicalCallableKey(def: SymbolDefinition): string { @@ -189,10 +248,18 @@ function pickConstructorOrClass( /** Walk up from the call-site scope to the enclosing class scope, * pick a method member by name with overload narrowing on arity + - * argument types. Returns undefined if there's no enclosing class - * or no matching method. Used for implicit-this calls inside a - * class body where multiple overloads share the call name. */ -function pickImplicitThisOverload( + * argument types. Returns undefined if there's no enclosing class, + * no matching method, OR narrowing leaves multiple compatible + * candidates — in the multi-candidate case, picking + * `candidates[0]` would emit a high-confidence CALLS edge whose + * target depends on registration order rather than a defensible + * resolution. Mirrors `pickUniqueGlobalCallable`'s uniqueness check + * in the same file (Codex PR #1497 review, finding 2). + * + * Exported for unit testing — language-agnostic logic, exercised + * via synthetic stubs in `pick-implicit-this-overload.test.ts`. The + * production call site is `applyFreeCallFallback` immediately above. */ +export function pickImplicitThisOverload( site: { readonly inScope: ScopeId; readonly name: string; @@ -225,6 +292,11 @@ function pickImplicitThisOverload( if (overloads.length === 0) return undefined; if (overloads.length === 1) return overloads[0]; + // Narrow on arity + argument types. Require a UNIQUE survivor — + // ambiguous narrowing (multiple compatible candidates with no + // disambiguating signal) leaves the call unresolved rather than + // routing to an arbitrary first overload by registration order. const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes); + if (candidates.length !== 1) return undefined; return candidates[0]; } diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts index 922afb36c..f36287052 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts @@ -13,9 +13,13 @@ * 2. Exact-required-match wins over variadic. Variadic is detected * via a `parameterTypes` entry equal to `'params'` or starting * with `'params '` (C# `params` / variadic marker). - * 3. If the arity filter empties the set, fall back to the full - * overload list rather than returning nothing — the caller still - * needs a best-effort candidate. + * 3. If the arity filter empties the set AND any candidate had + * unknown bounds (both `parameterCount` and `requiredParameterCount` + * undefined), fall back to the full overload list — the empty + * result may be due to missing metadata rather than a real mismatch. + * If EVERY rejected candidate had definite arity bounds, trust the + * filter and return empty — the call is genuinely arity-incompatible + * (e.g., PHP `f(int $req, ...$rest)` called with zero args). * 4. If `argTypes` is present, filter further by per-slot type * equality. An empty string in `argTypes[i]` means "unknown" and * counts as a match. Mismatches disqualify. A non-empty typed @@ -39,6 +43,16 @@ export function narrowOverloadCandidates( const max = d.parameterCount; const min = d.requiredParameterCount; if (max !== undefined && argCount > max) { + // Variadic marker check is C#-specific (the 'params' keyword). + // Other languages use their own marker — PHP uses '...' (see + // `languages/php/arity-metadata.ts:46`), Python uses '*args'- + // shaped metadata that lives outside `parameterTypes` entirely. + // This branch is dead code for those languages because they + // set `parameterCount = undefined` for variadic functions, + // which keeps `max` undefined and skips this check entirely. + // Adding new variadic markers here changes behavior for those + // other languages too — don't extend without auditing each + // adapter's `arity-metadata.ts`. Finding 9 of PR #1497. const variadic = d.parameterTypes !== undefined && d.parameterTypes.some((t) => t === 'params' || t.startsWith('params ')); @@ -48,8 +62,16 @@ export function narrowOverloadCandidates( return true; }); + // When the arity filter empties the set, only fall back to the full + // overload list if some candidate had unknown bounds — otherwise the + // empty result is authoritative (every candidate definitively failed + // arity, e.g., PHP variadic with required-prefix called with too few + // args). + const anyUnknownBounds = overloads.some( + (d) => d.parameterCount === undefined && d.requiredParameterCount === undefined, + ); const candidates: readonly SymbolDefinition[] = - arityMatches.length > 0 ? arityMatches : overloads; + arityMatches.length > 0 ? arityMatches : anyUnknownBounds ? overloads : []; if (argTypes !== undefined && argTypes.length > 0) { const typed = candidates.filter((d) => { diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts index 925151b6c..0cb544db9 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts @@ -165,7 +165,16 @@ export function emitReceiverBoundCalls( if (provider.isSuperReceiver(receiverName)) { const enclosingClass = findEnclosingClassDef(site.inScope, scopes); if (enclosingClass !== undefined) { - const ancestors = scopes.methodDispatch.mroFor(enclosingClass.nodeId); + // For super-receiver dispatch (`parent::`, `base.`, `super()`), + // walk the inheritance-only ancestor chain when the language + // exposes it. PHP's `parent::` semantically bypasses composed + // traits; other languages without mixin augmentation have no + // `extendsOnlyMroFor` and fall back to `mroFor`. + const extendsOnly = scopes.methodDispatch.extendsOnlyMroFor; + const ancestors = + extendsOnly !== undefined + ? extendsOnly(enclosingClass.nodeId) + : scopes.methodDispatch.mroFor(enclosingClass.nodeId); let memberDef: SymbolDefinition | undefined; for (const ownerId of ancestors) { memberDef = findOwnedMember(ownerId, memberName, model); @@ -283,7 +292,21 @@ export function emitReceiverBoundCalls( let memberDef: SymbolDefinition | undefined; for (const ownerId of chain) { memberDef = findOwnedMember(ownerId, memberName, model); - if (memberDef !== undefined) break; + if (memberDef !== undefined) { + // The MRO chain is most-derived-first ([classDef, ...ancestors]). + // If the most-derived definition is arity-incompatible with the + // call site, PHP throws ArgumentCountError at runtime — it does + // NOT silently dispatch to an ancestor. Terminate the chain walk + // so no edge is emitted, rather than falling through to an + // arity-compatible ancestor (which would be a false positive). + if ( + narrowOverloadCandidates([memberDef], site.arity, site.argumentTypes).length === 0 + ) { + memberDef = undefined; + break; + } + break; + } } if (memberDef !== undefined) { const reason = diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts index ecd7b69aa..c606661c8 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts @@ -17,6 +17,7 @@ import { typescriptScopeResolver } from '../../languages/typescript/scope-resolv import { goScopeResolver } from '../../languages/go/scope-resolver.js'; import { javaScopeResolver } from '../../languages/java/scope-resolver.js'; import { cScopeResolver } from '../../languages/c/scope-resolver.js'; +import { phpScopeResolver } from '../../languages/php/scope-resolver.js'; /** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates * this map intersected with `MIGRATED_LANGUAGES` (the per-language @@ -32,4 +33,5 @@ export const SCOPE_RESOLVERS: ReadonlyMap = n [SupportedLanguages.Go, goScopeResolver], [SupportedLanguages.Java, javaScopeResolver], [SupportedLanguages.C, cScopeResolver], + [SupportedLanguages.PHP, phpScopeResolver], ]); diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts index 31a58cdfa..47f8a3551 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts @@ -184,6 +184,7 @@ export function runScopeResolution( const allFilePaths = new Set(parsedFiles.map((f) => f.filePath)); const nodeLookup = buildGraphNodeLookup(graph); const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup); + const extendsOnlyMroByClassDefId = provider.buildExtendsOnlyMro?.(graph, parsedFiles, nodeLookup); const resolutionConfig = input.resolutionConfig; const finalized = finalizeScopeModel(parsedFiles, { @@ -205,7 +206,7 @@ export function runScopeResolution( // the type system. const indexes = { ...finalized, - methodDispatch: buildPopulatedMethodDispatch(mroByClassDefId), + methodDispatch: buildPopulatedMethodDispatch(mroByClassDefId, extendsOnlyMroByClassDefId), }; // Build the workspace resolution index ONCE — scope-valued lookups @@ -283,6 +284,17 @@ export function runScopeResolution( workspaceIndex, readonlyModel, ); + const unresolvedReceiverExtras = + provider.emitUnresolvedReceiverEdges !== undefined + ? provider.emitUnresolvedReceiverEdges( + graph, + indexes, + parsedFiles, + nodeLookup, + handledSites, + readonlyModel, + ) + : 0; const freeCallExtras = emitFreeCallFallback( graph, indexes, @@ -295,6 +307,7 @@ export function runScopeResolution( { allowGlobalFallback: provider.allowGlobalFreeCallFallback === true, isFileLocalDef: provider.isFileLocalDef, + isCallableVisibleFromCaller: provider.isCallableVisibleFromCaller, }, ); const { emitted, skipped } = emitReferencesViaLookup( @@ -330,7 +343,7 @@ export function runScopeResolution( filesSkipped, importsEmitted, resolve: resolveStats, - referenceEdgesEmitted: emitted + receiverExtras + freeCallExtras, + referenceEdgesEmitted: emitted + receiverExtras + unresolvedReceiverExtras + freeCallExtras, referenceSkipped: skipped, }; } diff --git a/gitnexus/src/core/ingestion/tree-sitter-queries.ts b/gitnexus/src/core/ingestion/tree-sitter-queries.ts index 8e165a837..d65229808 100644 --- a/gitnexus/src/core/ingestion/tree-sitter-queries.ts +++ b/gitnexus/src/core/ingestion/tree-sitter-queries.ts @@ -1020,6 +1020,16 @@ export const PHP_QUERIES = ` (use_declaration [(name) (qualified_name)] @heritage.trait))) @heritage +; ── Heritage: trait uses another trait (transitive trait composition) ──────── +; PHP allows a trait body to contain "use OtherTrait;". The trait-uses-trait +; IMPLEMENTS edge is required by buildPhpMro to compute the full transitive +; trait closure (depth 3+ chains). +(trait_declaration + name: (name) @heritage.class + body: (declaration_list + (use_declaration + [(name) (qualified_name)] @heritage.trait))) @heritage + ; PHP HTTP consumers: file_get_contents('/path'), curl_init('/path') (function_call_expression function: (name) @_php_http (#match? @_php_http "^(file_get_contents|curl_init)$") diff --git a/gitnexus/test/fixtures/cross-file-binding/php-consumer-before-provider/app/BProvider.php b/gitnexus/test/fixtures/cross-file-binding/php-consumer-before-provider/app/Models/User.php similarity index 100% rename from gitnexus/test/fixtures/cross-file-binding/php-consumer-before-provider/app/BProvider.php rename to gitnexus/test/fixtures/cross-file-binding/php-consumer-before-provider/app/Models/User.php diff --git a/gitnexus/test/fixtures/lang-resolution/php-calls/app/Services/UserService.php b/gitnexus/test/fixtures/lang-resolution/php-calls/app/Services/UserService.php index fa0a1b8be..882e12d64 100644 --- a/gitnexus/test/fixtures/lang-resolution/php-calls/app/Services/UserService.php +++ b/gitnexus/test/fixtures/lang-resolution/php-calls/app/Services/UserService.php @@ -2,10 +2,13 @@ namespace App\Services; -use function App\Utils\OneArg\log; -use function App\Utils\ZeroArg\log as zero_log; +use function App\Utils\OneArg\write_audit; +use function App\Utils\ZeroArg\write_audit as zero_write_audit; function create_user(): string { + // Two visible write_audit candidates (different arities). Arity narrowing + // must pick the 1-arg OneArg version. This validates that visibility + + // arity together correctly disambiguate. return write_audit('hello'); } diff --git a/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/Dynamic.php b/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/Dynamic.php new file mode 100644 index 000000000..4904f3c24 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/Dynamic.php @@ -0,0 +1,113 @@ +$method() — dynamic method name via variable_name node. + // Query pattern requires `name: (name)` so this is not captured. + $method = 'dynamicProcess'; + $obj->$method(); + } + + public function memberCallBraceDynamicName(Targets $obj): void + { + // $obj->{$method}() — brace-syntax variant of the above. + $method = 'dynamicBrace'; + $obj->{$method}(); + } + + public function scopedCallDynamicMethodName(): void + { + // ClassName::$method() — dynamic method name on static dispatch. + $method = 'dynamicHandle'; + Targets::$method(); + } + + public function scopedCallVariableClassNameStaticMethod($className): void + { + // $className::method() — class-name is an untyped parameter (no + // type hint, no string-literal assignment that could be picked up + // by a future type-binding heuristic). Receiver IS captured but + // resolution falls through because $className has no class type + // binding in scope. The unresolved-receiver fallback also doesn't + // fire because `dynamicStaticMethod` is unique workspace-wide AND + // exact-arity narrowing in U4 would still match — meaning the + // ONLY thing keeping the edge count at zero today is the absence + // of any type binding for the receiver. + $className::dynamicStaticMethod(); + } + + public function scopedCallDynamicClassAndMethodName(): void + { + // $className::$method() — both dynamic. + $className = 'App\\Services\\Targets'; + $method = 'dynamicScopedDynName'; + $className::$method(); + } + + public function callUserFuncVariableCallable($callable): void + { + // call_user_func($callable, ...) — resolver is structural-only + // and never inspects argument values to infer the callable. + // The literal `call_user_func` itself is an unresolved built-in. + call_user_func($callable); + } + + public function callUserFuncArrayVariable($callable, $args): void + { + // call_user_func_array($callable, $args) — unknown-arity variant. + call_user_func_array($callable, $args); + } + + public function callUserFuncStringCallable(): void + { + // 'Class::method' string-callable form — argument is a string + // literal, never reaches the function: child of function_call_expression. + call_user_func('App\\Services\\Targets::dynamicCallableMethod'); + } + + public function callUserFuncArrayObjectCallable(Targets $obj): void + { + // [$obj, 'method'] array-callable form — array is an argument + // value, not the function: child. + call_user_func([$obj, 'dynamicArrayCallableMethod']); + } + + public function callUserFuncArrayClassNameCallable(): void + { + // ['Class', 'method'] array-callable with class-name string. + call_user_func(['App\\Services\\Targets', 'dynamicArrayClassCallableMethod']); + } + + public function dynamicPropertyRead(Targets $obj): string + { + // $obj->$prop — dynamic property read. No read-access property + // capture pattern exists in query.ts at all (Finding 2). + $prop = 'dynamicProp'; + return $obj->$prop; + } + + public function sanityStaticCall(Targets $obj): void + { + // The fixture's deliberate sanity-check call. THIS one DOES emit + // a CALLS edge — if the assertion that this edge exists ever + // fails, the test infra is broken, not the dynamic-dispatch + // suppression. Without this, every zero-edge assertion above + // would pass even if the pipeline never emitted any edges at all. + $obj->sanityStaticallyNamedTarget(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/OtherTargets.php b/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/OtherTargets.php new file mode 100644 index 000000000..c8b70a20d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-dynamic-calls/app/Services/OtherTargets.php @@ -0,0 +1,16 @@ +record()` MUST resolve to app/Other/User.php::record, +// NOT app/Models/User.php::record. The `saveLocal` method exercises the +// simple-name path as a control — `User` here is the imported App\Models\User. +class Service { + public function save(\App\Other\User $u): void { + $u->record(); + } + + public function saveLocal(User $u): void { + $u->record(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/composer.json b/gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/composer.json new file mode 100644 index 000000000..386b0bd2d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-fqn-cross-namespace/composer.json @@ -0,0 +1,7 @@ +{ + "autoload": { + "psr-4": { + "App\\": "app/" + } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/ChildModel.php b/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/ChildModel.php new file mode 100644 index 000000000..0dff935c9 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/app/Models/ChildModel.php @@ -0,0 +1,10 @@ + hits Case 2 (findClassBindingInScope) in + // receiver-bound-calls.ts. + // Pre-fix bug: MRO walk emits a false CALLS edge to ParentModel::method + // because Case 2 used `continue` on arity mismatch and fell through. + // Post-fix: zero edges (PHP throws ArgumentCountError at runtime). + ChildModel::method(1); + } + + public function callCompatible(): void + { + // Happy path: ChildModel::compat takes 1 arg; matches call site. + ChildModel::compat(1); + } + + public function callNoParent(): void + { + // Orphan::method takes 2 args; called with 1; no parent class exists. + // Pre-fix: same Case 2 bug — the loop exhausts with memberDef cleared, + // BUT with `continue` the loop simply ends after one iteration since + // the chain has only one entry; no edge would have been emitted here + // even pre-fix. Post-fix: same — zero edges. Documents the boundary. + Orphan::method(1); + } + + public function callMostDerivedHappy(): void + { + // Happy path: ChildModel::method takes 2 args; matches call site. + ChildModel::method(1, 2); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/composer.json b/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/composer.json new file mode 100644 index 000000000..60ede80e5 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-mro-arity-mismatch/composer.json @@ -0,0 +1,5 @@ +{ + "autoload": { + "psr-4": { "App\\": "app/" } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/composer.json b/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/composer.json new file mode 100644 index 000000000..3675b0d1c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/composer.json @@ -0,0 +1,8 @@ +{ + "autoload": { + "psr-4": { + "App\\": "src/App/", + "Vendor\\": "src/Vendor/" + } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Caller.php b/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Caller.php new file mode 100644 index 000000000..6fecabb3c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-namespace-fallback-isolation/src/App/Caller.php @@ -0,0 +1,19 @@ +record(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/composer.json b/gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/composer.json new file mode 100644 index 000000000..386b0bd2d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-parent-vs-trait/composer.json @@ -0,0 +1,7 @@ +{ + "autoload": { + "psr-4": { + "App\\": "app/" + } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Models/Consumer.php b/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Models/Consumer.php new file mode 100644 index 000000000..86d330173 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Models/Consumer.php @@ -0,0 +1,20 @@ +aMethod(); + } + + public function callDepthTwo(): string { + return $this->bMethod(); + } + + public function callDepthThree(): string { + return $this->deepMethod(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitA.php b/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitA.php new file mode 100644 index 000000000..4408b8dfb --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-transitive-traits/app/Traits/TraitA.php @@ -0,0 +1,10 @@ += required → edge emitted + * - variadic candidate, argCount < required → NO edge + */ +class Caller +{ + public function callHappyPath($h): void + { + // happyPath(): min=0. argCount=0 → exact match. Edge. + $h->happyPath(); + } + + public function callDefaultExactRequired($h): void + { + // withDefault($a, $b=0): min=1. argCount=1 === min → exact match. Edge. + $h->withDefault('a'); + } + + public function callDefaultBeyondRequired($h): void + { + // withDefault($a, $b=0): min=1, max=2. argCount=2 > min. + // Pre-fix: first-stage narrow accepts (2 <= 2), edge emitted. + // Post-fix: exact-required gate rejects (2 !== 1), no edge. + $h->withDefault('a', 99); + } + + public function callVariadicAtRequired($h): void + { + // variadicLog($level, ...$args): min=1, hasVarArgs. + // argCount=1 === min → edge emitted (variadic relaxed path). + $h->variadicLog('info'); + } + + public function callVariadicBeyondRequired($h): void + { + // variadicLog($level, ...$args): min=1, hasVarArgs. + // argCount=2 > min, variadic → edge emitted. + $h->variadicLog('info', 'arg1'); + } + + public function callVariadicBelowRequired($h): void + { + // variadicLogTwoRequired($a, $b, ...$rest): min=2, hasVarArgs. + // argCount=1 < min → no edge (first-stage rejects). Both pre/post-fix. + $h->variadicLogTwoRequired('only-one'); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/composer.json b/gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/composer.json new file mode 100644 index 000000000..60ede80e5 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-unresolved-receiver-arity/composer.json @@ -0,0 +1,5 @@ +{ + "autoload": { + "psr-4": { "App\\": "app/" } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/app/Services/Caller.php b/gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/app/Services/Caller.php new file mode 100644 index 000000000..1da29a43a --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/php-variadic-arity-minimum/app/Services/Caller.php @@ -0,0 +1,30 @@ +method()` precedence inside a class that composes a trait AND + // extends a parent both defining the same method requires the augmented + // trait-aware MRO (trait shadows parent). The legacy DAG has no + // trait-aware MRO, so it fails to bind the call to the trait. Scope- + // resolver-only correctness win (commit af9af4a9 U3). + '$this->record() still resolves to Auditable::record (trait shadows parent)', + // Fully-qualified type-hint resolution (`\App\Other\User $u` parameter) + // routes through the scope-resolver's bindingAugmentations channel + // populated by `populatePhpNamespaceSiblings` Step 3b. The legacy DAG + // resolves receiver types via simple-name workspace lookup and has no + // namespace-prefixed binding channel, so it cannot distinguish the FQN + // target from a same-simple-name class reachable via `use`. Scope- + // resolver-only correctness win (Codex PR #1497 review, finding 1). + '\\App\\Other\\User parameter resolves $u->record() to app/Other/User.php (NOT app/Models/User.php)', + // MRO arity-mismatch on class-name receivers (`Child::method(1)` where + // Child::method takes 2 args and Parent::method takes 1): the legacy + // DAG has no arity narrowing on Case 2 (class-name) MRO walk, so it + // emits a false CALLS edge to Parent::method on fallthrough. Scope- + // resolver-only correctness win (PR #1497 review Image 1 / U1). + 'arity-incompatible most-derived override does NOT fall through to ParentModel::method', + // Class-name receiver with single-class arity mismatch (no parent in + // the MRO chain): legacy resolves the method by name without arity + // gating, so it emits a CALLS edge even when arity is definitively + // incompatible. The scope-resolver's `narrowOverloadCandidates` check + // in `receiver-bound-calls.ts` Case 2 rejects this post-fix. Scope- + // resolver-only correctness win (PR #1497 / U1). + 'arity-incompatible class with no parent emits zero CALLS edges (regression check)', + // `phpEmitUnresolvedReceiverEdges` exact-required-arity gate (PR + // #1497 / U4): the legacy DAG has no equivalent unresolved-receiver + // fallback hook, so it resolves these untyped-receiver sites via a + // different code path that over-emits for default-parameter and + // variadic-required-mismatch shapes. Scope-resolver-only correctness + // wins; backporting to legacy is out of scope. + 'argCount > required (2>1) on candidate with default param emits NO edge post-fix', + 'variadic candidate, argCount < required (1<2) emits NO edge', + ]), python: new Set([ // Suffix-fallback lex tiebreak depends on the registry-primary // resolver's deterministic sort. The legacy resolver returns the diff --git a/gitnexus/test/integration/resolvers/php.test.ts b/gitnexus/test/integration/resolvers/php.test.ts index e120d92f4..336e5dee2 100644 --- a/gitnexus/test/integration/resolvers/php.test.ts +++ b/gitnexus/test/integration/resolvers/php.test.ts @@ -1,11 +1,12 @@ /** * PHP: PSR-4 imports, extends, implements, trait use, enums, calls + ambiguous disambiguation */ -import { describe, it, expect, beforeAll } from 'vitest'; +import { describe, expect, beforeAll } from 'vitest'; import path from 'path'; import { FIXTURES, CROSS_FILE_FIXTURES, + createResolverParityIt, getRelationships, getNodesByLabel, getNodesByLabelFull, @@ -14,6 +15,12 @@ import { type PipelineResult, } from './helpers.js'; +// Wrap vitest's `it` so legacy-DAG-only divergences (commit af9af4a9 U1/U3) +// are skipped under REGISTRY_PRIMARY_PHP=0. The skip list lives in +// helpers.ts:LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES.php — sibling pattern +// to csharp/typescript/python. +const it = createResolverParityIt('php'); + // --------------------------------------------------------------------------- // Heritage: PSR-4 imports, extends, implements, trait use, enums, calls // --------------------------------------------------------------------------- @@ -91,6 +98,10 @@ describe('PHP heritage & import resolution', () => { expect(targets).toContain('label'); }); + // save($entity: mixed) calls $entity->getId() — the receiver is typed `mixed` + // so there is no TypeRef in scope. The scope-resolver `emitUnresolvedReceiverEdges` + // hook (PHP-wired) recovers this case via workspace-wide unique-name lookup, + // matching the legacy DAG behavior. it('emits CALLS edge: save → getId', () => { const calls = getRelationships(result, 'CALLS').filter( (e) => e.source === 'save' && e.target === 'getId', @@ -439,6 +450,161 @@ describe('PHP variadic call resolution', () => { }); }); +// --------------------------------------------------------------------------- +// Variadic arity minimum: required-arg count must be enforced for variadic +// functions. f(int $req, ...$rest) called as f() is an ArgumentCountError at +// PHP runtime and must NOT emit a CALLS edge from the resolver. +// --------------------------------------------------------------------------- + +describe('PHP variadic arity minimum (U1)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-variadic-arity-minimum'), () => {}); + }, 60000); + + const callsFrom = (source: string, target: string) => + getRelationships(result, 'CALLS').filter((c) => c.source === source && c.target === target); + + it('emits CALLS edge for record(level, ...msgs) with arity 4 (happy path)', () => { + expect(callsFrom('callValidRecord', 'record').length).toBe(1); + }); + + it('emits CALLS edge for record(level) with only the required arg (arity 1)', () => { + expect(callsFrom('callValidRecordMin', 'record').length).toBe(1); + }); + + it('does NOT emit CALLS edge for record() with zero args (below required=1)', () => { + expect(callsFrom('callTooFewRecord', 'record').length).toBe(0); + }); + + it('emits CALLS edge for format() — pure variadic, required=0', () => { + expect(callsFrom('callPureVariadic', 'format').length).toBe(1); + }); + + it('emits CALLS edge for pad("x") — required+optional+variadic, only required given', () => { + expect(callsFrom('callPadMin', 'pad').length).toBe(1); + }); + + it('does NOT emit CALLS edge for pad() with zero args (below required=1)', () => { + expect(callsFrom('callPadTooFew', 'pad').length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// Transitive trait MRO: trait A uses B uses C — Consumer using A must see C's +// methods. Current depth-2 expansion in buildPhpMro silently drops methods +// from 3+ level chains. +// --------------------------------------------------------------------------- + +describe('PHP transitive trait MRO (U2)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-transitive-traits'), () => {}); + }, 60000); + + const callsFrom = (source: string, target: string) => + getRelationships(result, 'CALLS').filter((c) => c.source === source && c.target === target); + + it('detects 3 traits and 1 class', () => { + expect(getNodesByLabel(result, 'Trait')).toEqual(['TraitA', 'TraitB', 'TraitC']); + expect(getNodesByLabel(result, 'Class')).toContain('Consumer'); + }); + + it('depth-1: $this->aMethod() resolves to TraitA::aMethod', () => { + expect(callsFrom('callDepthOne', 'aMethod').length).toBe(1); + }); + + it('depth-2: $this->bMethod() resolves to TraitB::bMethod (TraitA uses TraitB)', () => { + expect(callsFrom('callDepthTwo', 'bMethod').length).toBe(1); + }); + + it('depth-3: $this->deepMethod() resolves to TraitC::deepMethod (TraitA → TraitB → TraitC)', () => { + expect(callsFrom('callDepthThree', 'deepMethod').length).toBe(1); + }); +}); + +// --------------------------------------------------------------------------- +// parent:: bypasses traits. When a class composes a trait AND extends a parent +// that both define the same method name, parent::method() must resolve to the +// parent class (PHP semantics), NOT the trait. $this->method() still goes to +// the trait (PHP's own-class > trait > parent precedence). +// --------------------------------------------------------------------------- + +describe('PHP parent:: bypasses traits (U3)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-parent-vs-trait'), () => {}); + }, 60000); + + const callsFromTo = (source: string, target: string, file: string) => + getRelationships(result, 'CALLS').filter( + (c) => c.source === source && c.target === target && c.targetFilePath === file, + ); + + it('parent::record() resolves to Base::record, NOT Auditable::record', () => { + expect(callsFromTo('callViaParent', 'record', 'app/Base.php').length).toBe(1); + expect(callsFromTo('callViaParent', 'record', 'app/Auditable.php').length).toBe(0); + }); + + it('$this->record() still resolves to Auditable::record (trait shadows parent)', () => { + expect(callsFromTo('callViaThis', 'record', 'app/Auditable.php').length).toBe(1); + expect(callsFromTo('callViaThis', 'record', 'app/Base.php').length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// Namespace-aware free-call fallback. PHP's `pickUniqueGlobalCallable` must +// reject cross-namespace candidates that the caller can't reach without an +// explicit `use function` import. Same-namespace and globally-imported calls +// still emit edges. +// --------------------------------------------------------------------------- + +describe('PHP namespace-aware free-call fallback (U4)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'php-namespace-fallback-isolation'), + () => {}, + ); + }, 60000); + + const callsFromTo = (source: string, target: string, file?: string) => + getRelationships(result, 'CALLS').filter( + (c) => + c.source === source && + c.target === target && + (file === undefined || c.targetFilePath === file), + ); + + it('rejects cross-namespace candidate when caller has no use-function import', () => { + // callNoImport (in \App) calls format('x'). Workspace has \App\Utils\format/1 + // and \Vendor\Utils\format/2. Caller is in \App — NOT same namespace as + // either candidate, and no `use function` for `format` is in scope. + // Expected: NO CALLS edge. + expect(callsFromTo('callNoImport', 'format').length).toBe(0); + }); + + it('resolves same-namespace free call (caller in App\\Utils → App\\Utils\\format)', () => { + expect(callsFromTo('callSameNamespace', 'format', 'src/App/Utils/Format.php').length).toBe(1); + }); + + it('resolves use-function-imported alias (vendorFormat → Vendor\\Utils\\format)', () => { + // `use function Vendor\Utils\format as vendorFormat;`. Caller in \App calls + // vendorFormat('x', 80) — the import target is reachable. The CALLS edge + // may surface against either the alias name (`vendorFormat`) or the + // canonical function name (`format` in the vendor file) depending on + // dedup ordering; either way, exactly one edge total. + expect( + callsFromTo('callImported', 'vendorFormat').length + + callsFromTo('callImported', 'format', 'src/Vendor/Utils/Format.php').length, + ).toBe(1); + }); +}); + // --------------------------------------------------------------------------- // Local shadow: same-file definition takes priority over imported name // --------------------------------------------------------------------------- @@ -1807,3 +1973,325 @@ describe('PHP Child extends ParentClass — inherited method resolution (SM-9)', expect(parentMethodCall!.source).toBe('run'); }); }); + +// --------------------------------------------------------------------------- +// Fully-qualified type-hint resolution (Codex PR #1497 review, finding 1). +// +// Two `User` classes coexist in the workspace: `App\Models\User` and +// `App\Other\User`. A service file imports the simple-name `User` from +// App\Models, but uses a fully-qualified `\App\Other\User` in a parameter +// annotation. PHP runtime semantics: the leading `\` is an absolute namespace +// path; the parameter is always `App\Other\User`, even when the simple +// `User` is bound to a different class by `use`. +// +// Pre-fix: `normalizePhpType` strips the qualifier so the TypeRef carries +// only `User`, then `findClassBindingInScope` walks the scope chain and +// resolves to the imported `App\Models\User` — emitting a CALLS edge to the +// wrong class. Post-fix: qualified form survives on `rawName`, the +// QualifiedNameIndex fallback (or a PHP-specific qualified lookup) routes +// the call to App\Other\User::record. +// --------------------------------------------------------------------------- + +describe('PHP fully-qualified type-hint resolution (Codex #1497)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-fqn-cross-namespace'), () => {}); + }, 60000); + + const callsFromTo = (source: string, target: string, file: string) => + getRelationships(result, 'CALLS').filter( + (c) => c.source === source && c.target === target && c.targetFilePath === file, + ); + + it('detects both User classes in distinct namespaces', () => { + expect(getNodesByLabel(result, 'Class')).toContain('User'); + // Exactly two User entries — one per namespace. + const userClasses = getNodesByLabelFull(result, 'Class').filter((n) => n.name === 'User'); + expect(userClasses.length).toBe(2); + const userFiles = userClasses.map((c) => c.properties.filePath as string).sort(); + expect( + userFiles.some((f) => f.includes('Models/User.php') || f.includes('Models\\User.php')), + ).toBe(true); + expect( + userFiles.some((f) => f.includes('Other/User.php') || f.includes('Other\\User.php')), + ).toBe(true); + }); + + it('\\App\\Other\\User parameter resolves $u->record() to app/Other/User.php (NOT app/Models/User.php)', () => { + // The bug Codex flagged: FQN parameter collapses to simple `User`, then + // resolves to the imported `App\Models\User` instead of the explicit + // `\App\Other\User` named in the annotation. Post-fix: exactly one edge, + // pointing to the FQN target. + expect(callsFromTo('save', 'record', 'app/Other/User.php').length).toBe(1); + expect(callsFromTo('save', 'record', 'app/Models/User.php').length).toBe(0); + }); + + it('simple-name `User $u` parameter resolves to the imported App\\Models\\User (control case)', () => { + // Sanity check that unqualified type-hint resolution still works via the + // `use App\Models\User;` import. Without this control, U2's normalizer + // change could regress the simple-name path and we'd miss it. + expect(callsFromTo('saveLocal', 'record', 'app/Models/User.php').length).toBe(1); + expect(callsFromTo('saveLocal', 'record', 'app/Other/User.php').length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// MRO arity-mismatch: most-derived override with incompatible arity must NOT +// fall through to an arity-compatible ancestor (PHP throws ArgumentCountError +// at runtime). See receiver-bound-calls.ts Case 2. +// --------------------------------------------------------------------------- + +describe('PHP MRO arity-mismatch fallthrough', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-mro-arity-mismatch'), () => {}); + }, 60000); + + const callsFromTo = (source: string, target: string, targetFilePath: string) => + getRelationships(result, 'CALLS').filter( + (c) => c.source === source && c.target === target && c.targetFilePath === targetFilePath, + ); + + it('detects ParentModel, ChildModel, Orphan, and Caller classes', () => { + expect(getNodesByLabel(result, 'Class')).toEqual([ + 'Caller', + 'ChildModel', + 'Orphan', + 'ParentModel', + ]); + }); + + it('arity-incompatible most-derived override does NOT fall through to ParentModel::method', () => { + // Pre-fix bug: `$child->method(1)` with ChildModel::method(int,int) and + // ParentModel::method(int) would emit a false CALLS edge to ParentModel::method. + // Post-fix: zero CALLS edges from callIncompatible for this site. + expect(callsFromTo('callIncompatible', 'method', 'app/Models/ParentModel.php').length).toBe(0); + expect(callsFromTo('callIncompatible', 'method', 'app/Models/ChildModel.php').length).toBe(0); + }); + + it('arity-compatible most-derived override emits exactly one CALLS edge to ChildModel::compat', () => { + // Happy path: ChildModel::compat(int) matches the call site $child->compat(1). + expect(callsFromTo('callCompatible', 'compat', 'app/Models/ChildModel.php').length).toBe(1); + expect(callsFromTo('callCompatible', 'compat', 'app/Models/ParentModel.php').length).toBe(0); + }); + + it('arity-incompatible class with no parent emits zero CALLS edges (regression check)', () => { + // Orphan::method(int,int) called with one arg, no parent class — must remain + // unresolved both before and after the fix. + expect(callsFromTo('callNoParent', 'method', 'app/Models/Orphan.php').length).toBe(0); + }); + + it('arity-compatible most-derived call still resolves to ChildModel::method (happy path)', () => { + // Ensure the fix did not break compatible-arity resolution. + expect(callsFromTo('callMostDerivedHappy', 'method', 'app/Models/ChildModel.php').length).toBe( + 1, + ); + expect(callsFromTo('callMostDerivedHappy', 'method', 'app/Models/ParentModel.php').length).toBe( + 0, + ); + }); +}); + +// --------------------------------------------------------------------------- +// @declaration.variable double-match dedup on typed properties. +// Pre-fix, the catch-all property pattern in query.ts (no `type:` constraint) +// also matched typed property declarations and emitted a stray Variable def +// alongside the legitimate Property def. captures.ts now pre-scans rawMatches +// for @declaration.property anchors and suppresses the duplicate. +// --------------------------------------------------------------------------- + +describe('PHP typed-property double-match dedup', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-typed-property-dedup'), () => {}); + }, 60000); + + it('detects the Mixed class', () => { + expect(getNodesByLabel(result, 'Class')).toContain('Mixed'); + }); + + it('emits exactly one Property def for the typed property `$repo`', () => { + const properties = getNodesByLabel(result, 'Property'); + expect(properties.filter((n) => n === 'repo').length).toBe(1); + }); + + it('emits exactly one Property def for the constructor-promoted typed `$promotedRepo`', () => { + const properties = getNodesByLabel(result, 'Property'); + expect(properties.filter((n) => n === 'promotedRepo').length).toBe(1); + }); + + it('emits zero stray Variable defs for typed property and promoted typed parameter', () => { + // Pre-fix: a Variable def named `$repo` and `$promotedRepo` (no `$` strip) + // would slip through the catch-all pattern. Post-fix: zero. + const variables = getNodesByLabel(result, 'Variable'); + expect(variables.filter((n) => n === '$repo' || n === 'repo').length).toBe(0); + expect(variables.filter((n) => n === '$promotedRepo' || n === 'promotedRepo').length).toBe(0); + }); + + it('untyped property `$id` still emits its catch-all Property def (regression check)', () => { + // The untyped catch-all @declaration.variable pattern is the legitimate + // path for `public $id;`. Make sure the cross-match dedup does not + // over-suppress untyped declarations — they have no @declaration.property + // sibling, so their anchor is not in the typedPropertyAnchorIds set. + const properties = getNodesByLabel(result, 'Property'); + expect(properties.filter((n) => n === 'id').length).toBe(1); + }); + + it('no `$`-prefixed Property or Variable defs leak from typed declarations', () => { + // The catch-all branch does NOT run the `$`-strip normalization, so any + // def it produces for a typed property carries a `$`-prefixed name — + // a known receiver-binding lookup pollution vector. Post-fix the + // catch-all is suppressed for typed property_declaration anchors, so + // no `$repo` / `$promotedRepo` def should appear at any label. + for (const n of result.graph.iterNodes()) { + const name = String(n.properties.name); + if (name === '$repo' || name === '$promotedRepo') { + throw new Error(`leaked $-prefixed def: ${n.label}|${name}|${n.id}`); + } + } + }); +}); + +// --------------------------------------------------------------------------- +// Dynamic PHP constructs MUST NOT capture as resolvable references. +// Findings 1-7 of the PR #1497 adversarial review confirmed via grammar +// inspection that $obj->$method(), call_user_func(...), array/string +// callables, and dynamic property reads produce zero captures. This suite +// locks that invariant in regression so a future query.ts edit cannot +// silently relax `name: (name)` to `name: (_)` and reintroduce false- +// positive edges. +// --------------------------------------------------------------------------- + +describe('PHP dynamic dispatch — negative regression suite', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'php-dynamic-calls'), () => {}); + }, 60000); + + const callsFromDynamicTo = (target: string) => + getRelationships(result, 'CALLS').filter( + (c) => + c.target === target && + // Source is some method on `Dynamic` (the file under test). + c.sourceFilePath === 'app/Services/Dynamic.php', + ); + + it('detects the Dynamic and Targets classes', () => { + expect(getNodesByLabel(result, 'Class')).toContain('Dynamic'); + expect(getNodesByLabel(result, 'Class')).toContain('Targets'); + }); + + it('sanity check: non-dynamic call DOES emit an edge', () => { + // Without this, every zero-edge assertion below would pass even if the + // pipeline emitted no CALLS edges at all. + expect(callsFromDynamicTo('sanityStaticallyNamedTarget').length).toBe(1); + }); + + it('$obj->$method() emits no CALLS edge to dynamicProcess', () => { + expect(callsFromDynamicTo('dynamicProcess').length).toBe(0); + }); + + it('$obj->{$method}() emits no CALLS edge to dynamicBrace', () => { + expect(callsFromDynamicTo('dynamicBrace').length).toBe(0); + }); + + it('Class::$method() emits no CALLS edge to dynamicHandle', () => { + expect(callsFromDynamicTo('dynamicHandle').length).toBe(0); + }); + + it('$className::method() with untyped variable receiver emits no CALLS edge', () => { + // Two attractor classes (Targets and OtherTargets) both expose + // dynamicStaticMethod so the unresolved-receiver fallback (Finding 8 / + // U4) cannot fire — that isolates this assertion to the dynamic- + // dispatch suppression at the query / receiver-bound-calls layer. + expect(callsFromDynamicTo('dynamicStaticMethod').length).toBe(0); + }); + + it('$className::$method() with dynamic class and method names emits no CALLS edge', () => { + expect(callsFromDynamicTo('dynamicScopedDynName').length).toBe(0); + }); + + it('call_user_func / call_user_func_array string and array callables emit no CALLS edges', () => { + // call_user_func itself is a built-in with no workspace def, so the + // free-call to it is unresolved — no edge to `call_user_func`. + expect(callsFromDynamicTo('call_user_func').length).toBe(0); + expect(callsFromDynamicTo('call_user_func_array').length).toBe(0); + // None of the named targets reachable only via the callable argument + // should pick up a false-positive edge. + expect(callsFromDynamicTo('dynamicCallableMethod').length).toBe(0); + expect(callsFromDynamicTo('dynamicArrayCallableMethod').length).toBe(0); + expect(callsFromDynamicTo('dynamicArrayClassCallableMethod').length).toBe(0); + }); + + it('dynamic property read ($obj->$prop) emits no read-edge to dynamicProp', () => { + // No read-access property capture pattern exists in query.ts at all + // (Finding 2). Verify no CALLS / READS / write edge targets `dynamicProp`. + expect(callsFromDynamicTo('dynamicProp').length).toBe(0); + const reads = getRelationships(result, 'READS').filter( + (r) => r.target === 'dynamicProp' && r.sourceFilePath === 'app/Services/Dynamic.php', + ); + expect(reads.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// phpEmitUnresolvedReceiverEdges exact-required-arity gate (Finding 8 / U4). +// The 0.6-confidence fallback for untyped receivers now requires argCount +// to exactly match the candidate's required parameter count for fixed- +// arity candidates. Variadic candidates keep the relaxed argCount >= +// required semantics. +// --------------------------------------------------------------------------- + +describe('PHP unresolved-receiver fallback exact-required-arity gate', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'php-unresolved-receiver-arity'), + () => {}, + ); + }, 60000); + + const fallbackEdgeFromTo = (source: string, target: string) => + getRelationships(result, 'CALLS').filter( + (c) => + c.source === source && c.target === target && c.targetFilePath === 'app/Models/Handler.php', + ); + + it('detects Handler and Caller classes', () => { + expect(getNodesByLabel(result, 'Class')).toContain('Handler'); + expect(getNodesByLabel(result, 'Class')).toContain('Caller'); + }); + + it('happy path: argCount === required (0===0) emits 0.6 fallback edge', () => { + expect(fallbackEdgeFromTo('callHappyPath', 'happyPath').length).toBe(1); + }); + + it('argCount === required (1===1) on candidate with default param still emits edge', () => { + expect(fallbackEdgeFromTo('callDefaultExactRequired', 'withDefault').length).toBe(1); + }); + + it('argCount > required (2>1) on candidate with default param emits NO edge post-fix', () => { + // Pre-fix: first-stage narrowOverloadCandidates accepted (1 <= 2 <= 2). + // Post-fix: exact-required gate rejects (2 !== 1). + expect(fallbackEdgeFromTo('callDefaultBeyondRequired', 'withDefault').length).toBe(0); + }); + + it('variadic candidate, argCount === required (1===1) emits edge', () => { + expect(fallbackEdgeFromTo('callVariadicAtRequired', 'variadicLog').length).toBe(1); + }); + + it('variadic candidate, argCount > required (2>1) emits edge (relaxed)', () => { + expect(fallbackEdgeFromTo('callVariadicBeyondRequired', 'variadicLog').length).toBe(1); + }); + + it('variadic candidate, argCount < required (1<2) emits NO edge', () => { + expect(fallbackEdgeFromTo('callVariadicBelowRequired', 'variadicLogTwoRequired').length).toBe( + 0, + ); + }); +}); diff --git a/gitnexus/test/unit/registry-primary-flag.test.ts b/gitnexus/test/unit/registry-primary-flag.test.ts index 9e8be3455..864754b7f 100644 --- a/gitnexus/test/unit/registry-primary-flag.test.ts +++ b/gitnexus/test/unit/registry-primary-flag.test.ts @@ -148,17 +148,20 @@ describe('primaryLanguages', () => { it('returns exactly the flipped languages (env opts in unmigrated, opts out migrated)', () => { // Migrated languages are default-on; each must be opted out here when - // testing explicit env overrides. Java (unmigrated) opts in; Go stays off. - process.env['REGISTRY_PRIMARY_PYTHON'] = 'false'; - process.env['REGISTRY_PRIMARY_CSHARP'] = 'false'; - process.env['REGISTRY_PRIMARY_TYPESCRIPT'] = 'false'; - process.env['REGISTRY_PRIMARY_GO'] = 'false'; - process.env['REGISTRY_PRIMARY_C'] = 'false'; + // testing explicit env overrides. Java (unmigrated) opts in. + // Opt out every member of MIGRATED_LANGUAGES dynamically so this test + // does not have to be updated each time a new language ships its + // Ring 3 migration (PHP joined the set in commit 69786b16; future + // Ring 3 additions land here without test churn). + for (const lang of MIGRATED_LANGUAGES) { + process.env[envVarNameFor(lang)] = 'false'; + } process.env['REGISTRY_PRIMARY_JAVA'] = '1'; const enabled = primaryLanguages(); expect(enabled.has(SupportedLanguages.Python)).toBe(false); expect(enabled.has(SupportedLanguages.CSharp)).toBe(false); expect(enabled.has(SupportedLanguages.Go)).toBe(false); + expect(enabled.has(SupportedLanguages.PHP)).toBe(false); expect(enabled.has(SupportedLanguages.Java)).toBe(true); // Only Java is on: migrated defaults overridden off, Java explicitly on. expect(enabled.size).toBe(1); diff --git a/gitnexus/test/unit/scope-resolution/overload-narrowing.test.ts b/gitnexus/test/unit/scope-resolution/overload-narrowing.test.ts index 810c3a79b..9a14fdddd 100644 --- a/gitnexus/test/unit/scope-resolution/overload-narrowing.test.ts +++ b/gitnexus/test/unit/scope-resolution/overload-narrowing.test.ts @@ -69,11 +69,26 @@ describe('narrowOverloadCandidates — arity filtering', () => { expect(result.map((d) => d.nodeId)).toEqual(['v:1']); }); - it('falls back to the full overload list when arity filter empties it', () => { + it('returns empty when arity filter empties the set AND every candidate had definite bounds', () => { // argCount=5 doesn't match any overload (none variadic, all have max < 5). + // Post-commit af9af4a9 (PR #1497 / U1): the empty result is now authoritative + // because every rejected candidate had defined `parameterCount` / + // `requiredParameterCount`. The old "always fall back to full list" rescue + // was deliberately removed so resolvers actually drop calls that are + // definitively arity-incompatible (e.g., PHP `f(int $req, ...$rest)` + // called with zero args). const result = narrowOverloadCandidates([add1, add2, add3], 5, undefined); - expect(result.map((d) => d.nodeId)).toEqual(['add:1', 'add:2', 'add:3']); + expect(result.map((d) => d.nodeId)).toEqual([]); }); + + // Note: the `anyUnknownBounds ? overloads : []` branch in + // narrowOverloadCandidates is structurally unreachable in this caller's + // shape — a candidate with both `parameterCount` and `requiredParameterCount` + // undefined always passes the arity filter (neither `argCount > max` nor + // `argCount < min` can fire), so `arityMatches.length` is always > 0 + // whenever `anyUnknownBounds` is true. The branch is preserved in the + // source as a defensive guard for future refactors that might add + // additional rejection criteria in the filter. }); describe('narrowOverloadCandidates — type narrowing', () => { diff --git a/gitnexus/test/unit/scope-resolution/pick-implicit-this-overload.test.ts b/gitnexus/test/unit/scope-resolution/pick-implicit-this-overload.test.ts new file mode 100644 index 000000000..26f526382 --- /dev/null +++ b/gitnexus/test/unit/scope-resolution/pick-implicit-this-overload.test.ts @@ -0,0 +1,156 @@ +/** + * Unit tests for `pickImplicitThisOverload` — the implicit-`this` free-call + * resolver in `free-call-fallback.ts`. + * + * Codex PR #1497 review, finding 2: the previous implementation returned + * `candidates[0]` after `narrowOverloadCandidates` regardless of how many + * candidates survived narrowing. When two same-name methods on the same + * class had identical arity and unknown argument types, narrowing left both + * compatible and the resolver emitted a high-confidence CALLS edge whose + * target depended on registration order. The fix tightens the picker to + * require a UNIQUE post-narrowing candidate; otherwise the call is left + * unresolved. + * + * These tests exercise the function via synthetic stubs — no fixtures, no + * pipeline — because the failure shape (two same-arity overloads with + * indistinguishable types) cannot be produced by a PHP integration fixture + * (PHP forbids method overloading) and any C# fixture would entangle this + * unit's contract with the wider C# resolver. + */ + +import { describe, it, expect } from 'vitest'; +import type { Scope, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import { pickImplicitThisOverload } from '../../../src/core/ingestion/scope-resolution/passes/free-call-fallback.js'; +import type { ScopeResolutionIndexes } from '../../../src/core/ingestion/model/scope-resolution-indexes.js'; +import type { SemanticModel } from '../../../src/core/ingestion/model/semantic-model.js'; +import type { WorkspaceResolutionIndex } from '../../../src/core/ingestion/scope-resolution/workspace-index.js'; + +const CLASS_SCOPE_ID = 'scope:test.cs#1:1-100:1:Class' as ScopeId; +const CLASS_DEF_ID = 'def:test.cs:Foo'; + +const mkMethod = (overrides: Partial & { nodeId: string }): SymbolDefinition => ({ + nodeId: overrides.nodeId, + filePath: 'x.cs', + type: 'Method', + ...overrides, +}); + +const mkClassScope = (): Scope => + ({ + id: CLASS_SCOPE_ID, + parent: null, + kind: 'Class', + range: { startLine: 1, startCol: 1, endLine: 100, endCol: 1 }, + filePath: 'test.cs', + bindings: new Map(), + typeBindings: new Map(), + ownedDefs: [], + }) as unknown as Scope; + +const mkScopes = (scope: Scope): ScopeResolutionIndexes => + ({ + scopeTree: { + getScope: (id: ScopeId) => (id === scope.id ? scope : undefined), + }, + }) as unknown as ScopeResolutionIndexes; + +const mkWorkspaceIndex = (mapping: ReadonlyMap): WorkspaceResolutionIndex => + ({ + classScopeIdToDefId: mapping, + }) as unknown as WorkspaceResolutionIndex; + +const mkModel = ( + overloadsByName: ReadonlyMap, +): SemanticModel => + ({ + methods: { + lookupAllByOwner: (_classDefId: string, name: string) => + overloadsByName.get(name) ?? ([] as readonly SymbolDefinition[]), + }, + }) as unknown as SemanticModel; + +describe('pickImplicitThisOverload — uniqueness guard (Codex #1497 finding 2)', () => { + const site = { + inScope: CLASS_SCOPE_ID, + name: 'save', + arity: 1, + argumentTypes: undefined, + }; + + it('returns the sole overload when only one method exists on the owner', () => { + const sole = mkMethod({ nodeId: 'm:1', parameterCount: 1, requiredParameterCount: 1 }); + const scopes = mkScopes(mkClassScope()); + const workspace = mkWorkspaceIndex(new Map([[CLASS_SCOPE_ID, CLASS_DEF_ID]])); + const model = mkModel(new Map([['save', [sole]]])); + + const result = pickImplicitThisOverload(site, scopes, workspace, model); + + expect(result?.nodeId).toBe('m:1'); + }); + + it('returns the single survivor when narrowing disambiguates by arity', () => { + const save1 = mkMethod({ nodeId: 'm:1', parameterCount: 1, requiredParameterCount: 1 }); + const save2 = mkMethod({ nodeId: 'm:2', parameterCount: 2, requiredParameterCount: 2 }); + const scopes = mkScopes(mkClassScope()); + const workspace = mkWorkspaceIndex(new Map([[CLASS_SCOPE_ID, CLASS_DEF_ID]])); + const model = mkModel(new Map([['save', [save1, save2]]])); + + // site.arity = 1 → only save1 survives narrowing. + const result = pickImplicitThisOverload(site, scopes, workspace, model); + + expect(result?.nodeId).toBe('m:1'); + }); + + it('returns undefined when narrowing leaves two compatible candidates (the bug)', () => { + // Two same-arity, same-required-count overloads with no disambiguating + // parameter-type info on either def. `narrowOverloadCandidates` keeps + // both; pre-fix code returned `candidates[0]` (registration order); + // post-fix code returns undefined. + const save1 = mkMethod({ nodeId: 'm:1', parameterCount: 1, requiredParameterCount: 1 }); + const save2 = mkMethod({ nodeId: 'm:2', parameterCount: 1, requiredParameterCount: 1 }); + const scopes = mkScopes(mkClassScope()); + const workspace = mkWorkspaceIndex(new Map([[CLASS_SCOPE_ID, CLASS_DEF_ID]])); + const model = mkModel(new Map([['save', [save1, save2]]])); + + const result = pickImplicitThisOverload(site, scopes, workspace, model); + + expect(result).toBeUndefined(); + }); + + it('returns undefined when no method on the owner matches the call name', () => { + const scopes = mkScopes(mkClassScope()); + const workspace = mkWorkspaceIndex(new Map([[CLASS_SCOPE_ID, CLASS_DEF_ID]])); + const model = mkModel(new Map()); + + const result = pickImplicitThisOverload(site, scopes, workspace, model); + + expect(result).toBeUndefined(); + }); + + it('returns undefined when the call site is not inside a Class scope', () => { + // Module-scope sites: no enclosing class, so the implicit-this picker + // has nothing to pick from. Different from an empty-narrowing miss. + const moduleScope = { + id: 'scope:test.cs#1:1-100:1:Module' as ScopeId, + parent: null, + kind: 'Module', + range: { startLine: 1, startCol: 1, endLine: 100, endCol: 1 }, + filePath: 'test.cs', + bindings: new Map(), + typeBindings: new Map(), + ownedDefs: [], + } as unknown as Scope; + const scopes = mkScopes(moduleScope); + const workspace = mkWorkspaceIndex(new Map()); + const model = mkModel(new Map()); + + const result = pickImplicitThisOverload( + { ...site, inScope: moduleScope.id }, + scopes, + workspace, + model, + ); + + expect(result).toBeUndefined(); + }); +}); diff --git a/gitnexus/test/unit/scope-resolution/registries.test.ts b/gitnexus/test/unit/scope-resolution/registries.test.ts index b204287b5..2681af69f 100644 --- a/gitnexus/test/unit/scope-resolution/registries.test.ts +++ b/gitnexus/test/unit/scope-resolution/registries.test.ts @@ -250,7 +250,13 @@ describe('Step 5: arity filter', () => { ); }); - it('keeps incompatible candidates when no compatible candidate exists (soft penalty)', () => { + it('drops every candidate when ALL are incompatible AND none unknown (hard rejection)', () => { + // Post-commit af9af4a9 (PR #1497 / U1): the old soft-penalty fallback + // that kept incompatible candidates with `arityMatchIncompatible` + // weight was deliberately removed at this layer too. When every + // candidate is definitively arity-incompatible, the registry returns + // no resolution — matching the PHP variadic case `f(int $req, ...$rest)` + // called with zero args. const save3 = mkDef({ nodeId: 'def:save-three', type: 'Method', @@ -268,8 +274,41 @@ describe('Step 5: arity filter', () => { const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', { callsite: { arity: 1 }, }); - expect(results).toHaveLength(1); - expect(evidenceOfKind(results[0]!, 'arity-match')?.weight).toBe( + expect(results).toHaveLength(0); + }); + + it('keeps incompatible candidates when at least one verdict is unknown (soft penalty)', () => { + // The soft-rescue path is still active when at least one candidate's + // arity verdict is 'unknown' — that signals missing metadata rather + // than a definitive mismatch, so all candidates (including incompatible + // ones) are preserved with their evidence weights for downstream + // tie-breaking. + const save3 = mkDef({ + nodeId: 'def:save-three', + type: 'Method', + qualifiedName: 'User.save', + parameterCount: 3, + }); + const saveUnknown = mkDef({ + nodeId: 'def:save-unknown', + type: 'Method', + qualifiedName: 'User.save', + }); + const mod = mkScope({ + id: 'scope:m', + parent: null, + bindings: { save: [mkBinding(save3, 'local'), mkBinding(saveUnknown, 'local')] }, + }); + const ctx = makeCtx([mod], [save3, saveUnknown], { + arity: (_callsite, def) => (def.nodeId === 'def:save-unknown' ? 'unknown' : 'incompatible'), + }); + const results = buildMethodRegistry(ctx).lookup('save', 'scope:m', { + callsite: { arity: 1 }, + }); + expect(results).toHaveLength(2); + const incompat = results.find((r) => r.def.nodeId === 'def:save-three'); + expect(incompat).toBeDefined(); + expect(evidenceOfKind(incompat!, 'arity-match')?.weight).toBe( EvidenceWeights.arityMatchIncompatible, ); }); From 7637bd1c8332feafb5073dd93f2390610ab4e61c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Tue, 12 May 2026 23:41:05 +0100 Subject: [PATCH 07/33] chore(deps)(deps): bump @protobufjs/utf8 in /gitnexus (#1535) --- gitnexus/package-lock.json | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/gitnexus/package-lock.json b/gitnexus/package-lock.json index 7aa9dc7bf..13b225aed 100644 --- a/gitnexus/package-lock.json +++ b/gitnexus/package-lock.json @@ -1646,9 +1646,9 @@ "license": "BSD-3-Clause" }, "node_modules/@protobufjs/utf8": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.0.tgz", - "integrity": "sha512-Vvn3zZrhQZkkBE8LSuW3em98c0FwgO4nxzv6OdSxPKJIEKY2bGbHn+mhGIPerzI4twdxaP8/0+06HBpwf345Lw==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/utf8/-/utf8-1.1.1.tgz", + "integrity": "sha512-oOAWABowe8EAbMyWKM0tYDKi8Yaox52D+HWZhAIJqQXbqe0xI/GV7FhLWqlEKreMkfDjshR5FKgi3mnle0h6Eg==", "license": "BSD-3-Clause" }, "node_modules/@rolldown/binding-android-arm64": { From 6a2361687358cb52173662bc5d5528fb5aee3bf3 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 06:40:24 +0100 Subject: [PATCH 08/33] chore(deps)(deps): bump protobufjs from 7.5.5 to 7.5.8 in /gitnexus (#1536) --- gitnexus/package-lock.json | 24 ++++++++++++------------ 1 file changed, 12 insertions(+), 12 deletions(-) diff --git a/gitnexus/package-lock.json b/gitnexus/package-lock.json index 13b225aed..15831e54d 100644 --- a/gitnexus/package-lock.json +++ b/gitnexus/package-lock.json @@ -1600,9 +1600,9 @@ "license": "BSD-3-Clause" }, "node_modules/@protobufjs/codegen": { - "version": "2.0.4", - "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.4.tgz", - "integrity": "sha512-YyFaikqM5sH0ziFZCN3xDC7zeGaB/d0IUb9CATugHWbd1FRFwWwt4ld4OYMPWu5a3Xe01mGAULCdqhMlPl29Jg==", + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/@protobufjs/codegen/-/codegen-2.0.5.tgz", + "integrity": "sha512-zgXFLzW3Ap33e6d0Wlj4MGIm6Ce8O89n/apUaGNB/jx+hw+ruWEp7EwGUshdLKVRCxZW12fp9r40E1mQrf/34g==", "license": "BSD-3-Clause" }, "node_modules/@protobufjs/eventemitter": { @@ -1628,9 +1628,9 @@ "license": "BSD-3-Clause" }, "node_modules/@protobufjs/inquire": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.0.tgz", - "integrity": "sha512-kdSefcPdruJiFMVSbn801t4vFK7KB/5gd2fYvrxhuJYg8ILrmn9SKSX2tZdV6V+ksulWqS7aXjBcRXl3wHoD9Q==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@protobufjs/inquire/-/inquire-1.1.1.tgz", + "integrity": "sha512-mnzgDV26ueAvk7rsbt9L7bE0SuAoqyuys/sMMrmVcN5x9VsxpcG3rqAUSgDyLp0UZlmNfIbQ4fHfCtreVBk8Ew==", "license": "BSD-3-Clause" }, "node_modules/@protobufjs/path": { @@ -4543,22 +4543,22 @@ "license": "MIT" }, "node_modules/protobufjs": { - "version": "7.5.5", - "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.5.tgz", - "integrity": "sha512-3wY1AxV+VBNW8Yypfd1yQY9pXnqTAN+KwQxL8iYm3/BjKYMNg4i0owhEe26PWDOMaIrzeeF98Lqd5NGz4omiIg==", + "version": "7.5.8", + "resolved": "https://registry.npmjs.org/protobufjs/-/protobufjs-7.5.8.tgz", + "integrity": "sha512-dvpCIeLPbXZS/Ete7yLaO7RenOdken2NHKykBXbsaGxZT0UTltcarBciw+A78SRQs9iMAAVpsYA+l8b1hTePIA==", "hasInstallScript": true, "license": "BSD-3-Clause", "dependencies": { "@protobufjs/aspromise": "^1.1.2", "@protobufjs/base64": "^1.1.2", - "@protobufjs/codegen": "^2.0.4", + "@protobufjs/codegen": "^2.0.5", "@protobufjs/eventemitter": "^1.1.0", "@protobufjs/fetch": "^1.1.0", "@protobufjs/float": "^1.0.2", - "@protobufjs/inquire": "^1.1.0", + "@protobufjs/inquire": "^1.1.1", "@protobufjs/path": "^1.1.2", "@protobufjs/pool": "^1.1.0", - "@protobufjs/utf8": "^1.1.0", + "@protobufjs/utf8": "^1.1.1", "@types/node": ">=13.7.0", "long": "^5.0.0" }, From aed6cfc7ea8ec55e592d6d3d5df94c75382de75c Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 08:00:14 +0100 Subject: [PATCH 09/33] chore(deps)(deps): bump mermaid (#1514) --- gitnexus-web/package-lock.json | 177 +++++---------------------------- gitnexus-web/package.json | 2 +- 2 files changed, 25 insertions(+), 154 deletions(-) diff --git a/gitnexus-web/package-lock.json b/gitnexus-web/package-lock.json index 4a4b73349..fa15ce15d 100644 --- a/gitnexus-web/package-lock.json +++ b/gitnexus-web/package-lock.json @@ -29,7 +29,7 @@ "langchain": "^1.3.5", "lru-cache": "^11.2.4", "lucide-react": "^1.14.0", - "mermaid": "^11.14.0", + "mermaid": "^11.15.0", "mnemonist": "^0.39.0", "pandemonium": "^2.4.0", "react": "^19.2.5", @@ -528,41 +528,10 @@ "integrity": "sha512-gAmrUZSGtKc3AiBL71iNWxDsyUC5uMaKKGdvzYsBoTW/xi42JQHl7eKV2OYzCUqvc+D2RCcf7EXY2iCyFIk6og==", "license": "MIT" }, - "node_modules/@chevrotain/cst-dts-gen": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz", - "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==", - "license": "Apache-2.0", - "dependencies": { - "@chevrotain/gast": "12.0.0", - "@chevrotain/types": "12.0.0" - } - }, - "node_modules/@chevrotain/gast": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz", - "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==", - "license": "Apache-2.0", - "dependencies": { - "@chevrotain/types": "12.0.0" - } - }, - "node_modules/@chevrotain/regexp-to-ast": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz", - "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==", - "license": "Apache-2.0" - }, "node_modules/@chevrotain/types": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz", - "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==", - "license": "Apache-2.0" - }, - "node_modules/@chevrotain/utils": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz", - "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==", + "version": "11.1.2", + "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz", + "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==", "license": "Apache-2.0" }, "node_modules/@cspotcode/source-map-support": { @@ -1679,12 +1648,12 @@ } }, "node_modules/@mermaid-js/parser": { - "version": "1.1.0", - "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz", - "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==", + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.1.tgz", + "integrity": "sha512-VuHdsYMK1bT6X2JbcAaWAhugTRvRBRyuZgd+c22swUeI9g/ntaxF7CY7dYarhZovofCbUNO0G7JesfmNtjYOCw==", "license": "MIT", "dependencies": { - "langium": "^4.0.0" + "@chevrotain/types": "~11.1.1" } }, "node_modules/@napi-rs/wasm-runtime": { @@ -3643,34 +3612,6 @@ "url": "https://github.com/sponsors/wooorm" } }, - "node_modules/chevrotain": { - "version": "12.0.0", - "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz", - "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==", - "license": "Apache-2.0", - "dependencies": { - "@chevrotain/cst-dts-gen": "12.0.0", - "@chevrotain/gast": "12.0.0", - "@chevrotain/regexp-to-ast": "12.0.0", - "@chevrotain/types": "12.0.0", - "@chevrotain/utils": "12.0.0" - }, - "engines": { - "node": ">=22.0.0" - } - }, - "node_modules/chevrotain-allstar": { - "version": "0.4.1", - "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.1.tgz", - "integrity": "sha512-PvVJm3oGqrveUVW2Vt/eZGeiAIsJszYweUcYwcskg9e+IubNYKKD+rHHem7A6XVO22eDAL+inxNIGAzZ/VIWlA==", - "license": "MIT", - "dependencies": { - "lodash-es": "^4.17.21" - }, - "peerDependencies": { - "chevrotain": "^12.0.0" - } - }, "node_modules/chownr": { "version": "3.0.0", "resolved": "https://registry.npmjs.org/chownr/-/chownr-3.0.0.tgz", @@ -4628,6 +4569,16 @@ "node": ">= 0.4" } }, + "node_modules/es-toolkit": { + "version": "1.46.1", + "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.46.1.tgz", + "integrity": "sha512-5eNtXOs3tbfxXOj04tjjseeWkRWaoCjdEI+96DgwzZoe6c9juL49pXlzAFTI72aWC9Y8p7168g6XIKjh7k6pyQ==", + "license": "MIT", + "workspaces": [ + "docs", + "benchmarks" + ] + }, "node_modules/esbuild": { "version": "0.27.0", "resolved": "https://registry.npmjs.org/esbuild/-/esbuild-0.27.0.tgz", @@ -5661,24 +5612,6 @@ "@langchain/core": "^1.1.42" } }, - "node_modules/langium": { - "version": "4.2.2", - "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.2.tgz", - "integrity": "sha512-JUshTRAfHI4/MF9dH2WupvjSXyn8JBuUEWazB8ZVJUtXutT0doDlAv1XKbZ1Pb5sMexa8FF4CFBc0iiul7gbUQ==", - "license": "MIT", - "dependencies": { - "@chevrotain/regexp-to-ast": "~12.0.0", - "chevrotain": "~12.0.0", - "chevrotain-allstar": "~0.4.1", - "vscode-languageserver": "~9.0.1", - "vscode-languageserver-textdocument": "~1.0.11", - "vscode-uri": "~3.1.0" - }, - "engines": { - "node": ">=20.10.0", - "npm": ">=10.2.3" - } - }, "node_modules/langsmith": { "version": "0.5.23", "resolved": "https://registry.npmjs.org/langsmith/-/langsmith-0.5.23.tgz", @@ -6422,14 +6355,14 @@ } }, "node_modules/mermaid": { - "version": "11.14.0", - "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz", - "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==", + "version": "11.15.0", + "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.15.0.tgz", + "integrity": "sha512-pTMbcf3rWdtLiYGpmoTjHEpeY8seiy6sR+9nD7LOs8KfUbHE4lOUAprTRqRAcWSQ6MQpdX+YEsxShtGsINtPtw==", "license": "MIT", "dependencies": { "@braintree/sanitize-url": "^7.1.1", "@iconify/utils": "^3.0.2", - "@mermaid-js/parser": "^1.1.0", + "@mermaid-js/parser": "^1.1.1", "@types/d3": "^7.4.3", "@upsetjs/venn.js": "^2.0.0", "cytoscape": "^3.33.1", @@ -6440,27 +6373,14 @@ "dagre-d3-es": "7.0.14", "dayjs": "^1.11.19", "dompurify": "^3.3.1", + "es-toolkit": "^1.45.1", "katex": "^0.16.25", "khroma": "^2.1.0", - "lodash-es": "^4.17.23", "marked": "^16.3.0", "roughjs": "^4.6.6", "stylis": "^4.3.6", "ts-dedent": "^2.2.0", - "uuid": "^11.1.0" - } - }, - "node_modules/mermaid/node_modules/uuid": { - "version": "11.1.0", - "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz", - "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==", - "funding": [ - "https://github.com/sponsors/broofa", - "https://github.com/sponsors/ctavan" - ], - "license": "MIT", - "bin": { - "uuid": "dist/esm/bin/uuid" + "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0" } }, "node_modules/micromark": { @@ -8875,55 +8795,6 @@ "dev": true, "license": "MIT" }, - "node_modules/vscode-jsonrpc": { - "version": "8.2.0", - "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz", - "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==", - "license": "MIT", - "engines": { - "node": ">=14.0.0" - } - }, - "node_modules/vscode-languageserver": { - "version": "9.0.1", - "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz", - "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==", - "license": "MIT", - "dependencies": { - "vscode-languageserver-protocol": "3.17.5" - }, - "bin": { - "installServerIntoExtension": "bin/installServerIntoExtension" - } - }, - "node_modules/vscode-languageserver-protocol": { - "version": "3.17.5", - "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz", - "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==", - "license": "MIT", - "dependencies": { - "vscode-jsonrpc": "8.2.0", - "vscode-languageserver-types": "3.17.5" - } - }, - "node_modules/vscode-languageserver-textdocument": { - "version": "1.0.12", - "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz", - "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==", - "license": "MIT" - }, - "node_modules/vscode-languageserver-types": { - "version": "3.17.5", - "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz", - "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==", - "license": "MIT" - }, - "node_modules/vscode-uri": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz", - "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==", - "license": "MIT" - }, "node_modules/w3c-xmlserializer": { "version": "5.0.0", "resolved": "https://registry.npmjs.org/w3c-xmlserializer/-/w3c-xmlserializer-5.0.0.tgz", diff --git a/gitnexus-web/package.json b/gitnexus-web/package.json index 5913749b0..18eb43caf 100644 --- a/gitnexus-web/package.json +++ b/gitnexus-web/package.json @@ -39,7 +39,7 @@ "langchain": "^1.3.5", "lru-cache": "^11.2.4", "lucide-react": "^1.14.0", - "mermaid": "^11.14.0", + "mermaid": "^11.15.0", "mnemonist": "^0.39.0", "pandemonium": "^2.4.0", "react": "^19.2.5", From ec4624af87b23f0f0953a8f013fb3775948566a3 Mon Sep 17 00:00:00 2001 From: Abhigyan Patwari <126312502+abhigyanpatwari@users.noreply.github.com> Date: Wed, 13 May 2026 08:56:27 +0100 Subject: [PATCH 10/33] fix(hooks): cap concurrent augment subprocesses (#1486) (#1510) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(hooks): cap concurrent augment subprocesses to prevent runaway process spawn (#1486) When Claude Code fires PreToolUse hooks for parallel Grep/Glob/Bash tool calls, each invocation spawned its own `gitnexus augment` subprocess — a Node + LadybugDB cold start that holds resources for several seconds. Under heavy parallel search load (issue #1486: 180+ piled-up processes, load avg > 100), these accumulated faster than they completed because nothing capped concurrent in-flight augments. Add a lockfile-based concurrency guard under `<.gitnexus>/.hook-locks/`: each running hook claims a `.lock`, the guard counts live PIDs and prunes stale entries (>30s mtime or pid no longer alive), and bails silently when MAX_INFLIGHT (3) is reached. Augment is best-effort enrichment — missing a few fires under burst load is preferable to melting the system. Applied to all three hook variants that spawn augment: - gitnexus/hooks/claude/gitnexus-hook.cjs (npm-installed Claude hook) - gitnexus-claude-plugin/hooks/gitnexus-hook.js (plugin Claude hook) - gitnexus-cursor-integration/hooks/gitnexus-hook.cjs (Cursor hook) Co-Authored-By: Claude Opus 4.7 (1M context) * fix(hooks): make augment concurrency cap a hard cap via atomic slot files Address Claude's review of #1510. The original count-then-claim guard had a TOCTOU window: N hooks could each read `active < MAX_INFLIGHT` between readdirSync and the per-pid `wx` write and all proceed, briefly exceeding the cap. The PR title's "cap" language overstated this. Replace with fixed-name `slot-0.lock` ... `slot-N.lock` under `.hook-locks/`. `O_CREAT|O_EXCL` on a fixed path is OS-atomic — exactly one process wins each slot, so the cap is hard regardless of burst arrival timing. Each slot file contains the owning PID so stale-takeover still works when a hook crashes without releasing. PID liveness is checked before age (Claude's Finding 3): a slow-but-alive hook is never wrongly evicted. The 30s age window only kicks in to defend against PID reuse on a long-abandoned slot, well above the 7s augment timeout so a healthy run never hits it. Also adds the missing concurrency-guard tests to cursor-hook.test.ts (Claude's Finding 2): source-level wiring + dead-PID reclaim + 3-slots-full bail. Previously only the CJS and Plugin variants had test coverage for the guard; the Cursor variant was validated only by code inspection. Tests: 5726 passing, +9 from baseline (1 hard-cap burst test + 4 source regressions in hooks.test.ts; 3 source + 2 integration in cursor-hook.test.ts). Co-Authored-By: Claude Opus 4.7 (1M context) * fix(hooks): inspect slot mtime + content via single fd (codeql TOCTOU) CodeQL flagged the stale-takeover path in acquireHookSlot as a potential filesystem race (js/file-system-race): statSync(slotPath) followed by readFileSync(slotPath) gives a TOCTOU window where the file could be swapped between the metadata check and the content read. Replace the two separate path-based calls with a single openSync + fstatSync + readSync + closeSync sequence. Both mtime and owner PID now come from the same file descriptor, so the operations are atomic on one inode. No behavioral change beyond closing the race. Applied to all three hook variants (CJS, Plugin, Cursor). Co-Authored-By: Claude Opus 4.7 (1M context) * fix(hooks): distinguish EPERM from ESRCH in PID liveness check Cursor Bugbot caught a contradiction with the stated design: the bare `catch` after `process.kill(owner, 0)` was treating EPERM (process exists but owned by another user) the same as ESRCH (process gone), which would evict a live slot whenever the lock dir straddled user boundaries. Inspect the error code: ESRCH → dead, evict; EPERM → still alive, keep the slot; anything else → assume alive (be conservative under unexpected failure rather than over-evict). Applied to all three hook variants. Co-Authored-By: Claude Opus 4.7 (1M context) * fix(hooks): fail closed when lock dir cannot be created Previously the mkdirSync catch in acquireHookSlot returned `() => {}` (a truthy no-op). The caller checks `if (!release) return;` to skip augment when the guard can't be established — but a truthy no-op slipped through that check and let augment spawn unguarded. On a cross-user shared `.gitnexus/` or read-only filesystem, N concurrent hooks would each take that branch and reintroduce the #1486 fan-out the guard exists to prevent. Return `null` instead so the caller's `if (!release) return;` skips augment cleanly. Augment is best-effort enrichment — skipping it when the guard fails is strictly safer than running unguarded. Also clarify the stale-slot comment: PID-liveness wins for slots younger than HOOK_LOCK_STALE_MS, but age is the final arbiter beyond 30s (PID-reuse defense). The previous wording said "PID-liveness wins over age" without qualifying it, which contradicted the >30s branch. Add source-level regression tests in hooks.test.ts and cursor-hook.test.ts asserting acquireHookSlot returns null (not () => {}) on lock-dir failure. Note in the Cursor test file that the 10-spawner burst test is not duplicated because the algorithm is byte-for-byte identical to the CJS hook and already covered there. Co-Authored-By: Claude Opus 4.7 (1M context) * refactor(hooks): extract lock guard into helper modules Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/04dd20c5-28fd-433a-83cf-ad83fd03fb32 --------- Co-authored-by: Claude Opus 4.7 (1M context) Co-authored-by: Gergő Magyar Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> --- gitnexus-claude-plugin/hooks/gitnexus-hook.js | 9 +- gitnexus-claude-plugin/hooks/hook-lock.js | 119 +++++++ gitnexus-cursor-integration/README.md | 12 +- .../hooks/gitnexus-hook.cjs | 9 +- .../hooks/hook-lock.cjs | 119 +++++++ gitnexus/hooks/claude/gitnexus-hook.cjs | 9 +- gitnexus/hooks/claude/hook-lock.cjs | 119 +++++++ gitnexus/src/cli/setup.ts | 9 + gitnexus/test/unit/cursor-hook.test.ts | 178 +++++++++++ gitnexus/test/unit/hooks.test.ts | 300 ++++++++++++++++++ 10 files changed, 875 insertions(+), 8 deletions(-) create mode 100644 gitnexus-claude-plugin/hooks/hook-lock.js create mode 100644 gitnexus-cursor-integration/hooks/hook-lock.cjs create mode 100644 gitnexus/hooks/claude/hook-lock.cjs diff --git a/gitnexus-claude-plugin/hooks/gitnexus-hook.js b/gitnexus-claude-plugin/hooks/gitnexus-hook.js index 7d8fbfda4..245d34043 100644 --- a/gitnexus-claude-plugin/hooks/gitnexus-hook.js +++ b/gitnexus-claude-plugin/hooks/gitnexus-hook.js @@ -14,6 +14,7 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); +const { acquireHookSlot } = require('./hook-lock.js'); /** * Read JSON input from stdin synchronously. @@ -217,7 +218,8 @@ function sendHookResponse(hookEventName, message) { function handlePreToolUse(input) { const cwd = input.cwd || process.cwd(); if (!path.isAbsolute(cwd)) return; - if (!findGitNexusDir(cwd)) return; + const gitNexusDir = findGitNexusDir(cwd); + if (!gitNexusDir) return; const toolName = input.tool_name || ''; const toolInput = input.tool_input || {}; @@ -227,6 +229,9 @@ function handlePreToolUse(input) { const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; + const release = acquireHookSlot(gitNexusDir); + if (!release) return; + let result = ''; try { const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000); @@ -235,6 +240,8 @@ function handlePreToolUse(input) { } } catch { /* graceful failure */ + } finally { + release(); } if (result && result.trim()) { diff --git a/gitnexus-claude-plugin/hooks/hook-lock.js b/gitnexus-claude-plugin/hooks/hook-lock.js new file mode 100644 index 000000000..759856384 --- /dev/null +++ b/gitnexus-claude-plugin/hooks/hook-lock.js @@ -0,0 +1,119 @@ +const fs = require('fs'); +const path = require('path'); + +const HOOK_LOCK_SUBDIR = '.hook-locks'; +const HOOK_LOCK_MAX_INFLIGHT = 3; +const HOOK_LOCK_STALE_MS = 30000; + +function acquireHookSlot(gitNexusDir) { + const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR); + try { + fs.mkdirSync(lockDir, { recursive: true }); + } catch { + // Cannot create lock dir (read-only fs, cross-user perm denial, out of + // inodes, etc.) — fail closed by returning null. Caller skips augment. + // Fail-open here would let N concurrent hooks all proceed unguarded and + // reintroduce the #1486 fan-out the guard exists to prevent. + return null; + } + + const myPidStr = String(process.pid); + + for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) { + const slotPath = path.join(lockDir, `slot-${slot}.lock`); + for (let attempt = 0; attempt < 2; attempt++) { + try { + fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' }); + let released = false; + const release = () => { + if (released) return; + released = true; + try { + // Only unlink if we still own the slot. If we appeared stale and + // another hook took over, the file now belongs to it — leave alone. + const content = fs.readFileSync(slotPath, 'utf-8').trim(); + if (content === myPidStr) fs.unlinkSync(slotPath); + } catch { + /* already removed or unreadable */ + } + }; + process.on('exit', release); + return release; + } catch { + // Slot exists. Decide whether to take it over. + // Open once and inspect mtime + content via the same fd so there's + // no TOCTOU between the metadata check and the content read + // (codeql js/file-system-race). + let fd; + try { + fd = fs.openSync(slotPath, 'r'); + } catch { + continue; // Vanished between EEXIST and open — retry this slot. + } + let isLive = false; + let mtimeMs = Date.now(); + try { + mtimeMs = fs.fstatSync(fd).mtimeMs; + const buf = Buffer.alloc(32); + const n = fs.readSync(fd, buf, 0, 32, 0); + const ownerStr = buf.slice(0, n).toString('utf-8').trim(); + if (ownerStr === '') { + // Owner created the file but hasn't written its PID yet. The + // wx open+write window is microseconds; give it the benefit + // of the doubt and treat as live. + isLive = true; + } else { + const owner = Number.parseInt(ownerStr, 10); + if (Number.isFinite(owner) && owner > 0) { + try { + process.kill(owner, 0); + isLive = true; + } catch (e) { + // ESRCH = process gone → treat as dead. EPERM = process exists + // but owned by another user (cross-user lock dir) → still alive, + // keep the slot. Anything else: be conservative, assume alive. + if (e && e.code === 'ESRCH') { + isLive = false; + } else { + isLive = true; + } + } + } + } + } catch { + /* unreadable — treat as dead */ + } finally { + try { + fs.closeSync(fd); + } catch { + /* already closed */ + } + } + // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins — + // a slow-but-alive hook is never wrongly evicted. For older slots, + // age is the final arbiter as a defense against PID reuse on long- + // abandoned slots. 30s >> the 7s augment timeout, so a healthy run + // never crosses this threshold. + if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) { + isLive = false; + } + if (isLive) break; // Try the next slot. + try { + fs.unlinkSync(slotPath); + } catch { + /* another hook beat us to it — retry will hit EEXIST */ + } + // Loop and retry this slot. + } + } + } + + return null; +} + +module.exports = { + HOOK_LOCK_SUBDIR, + HOOK_LOCK_MAX_INFLIGHT, + HOOK_LOCK_STALE_MS, + acquireHookSlot, +}; diff --git a/gitnexus-cursor-integration/README.md b/gitnexus-cursor-integration/README.md index 0da8b1981..6545bacec 100644 --- a/gitnexus-cursor-integration/README.md +++ b/gitnexus-cursor-integration/README.md @@ -10,20 +10,21 @@ Static config that adds GitNexus knowledge-graph augmentation and skill files to | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- | | **MCP** | `gitnexus` MCP server with 16 tools (`query`, `context`, `impact`, `detect_changes`, `rename`, …) | `npx gitnexus setup` writes `~/.cursor/mcp.json` automatically. | | **Skills** | `/gitnexus-exploring`, `/gitnexus-debugging`, `/gitnexus-impact-analysis`, `/gitnexus-refactoring`, `/gitnexus-pr-review` markdown skills | `npx gitnexus setup` copies them to `~/.cursor/skills/gitnexus/`. | -| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets | **Manual** — copy the two files described below into your project's `.cursor/`. | +| **Hooks** _(this README)_ | `postToolUse` hook that enriches `Shell` / `Read` / `Grep` tool calls with graph context — same augmentation Claude Code gets | **Manual** — copy the files described below into your project's `.cursor/`. | ## Hook install Cursor 2.4+ reads `.cursor/hooks.json` from the project root and runs hook commands with the project root as the working directory ([docs](https://cursor.com/docs/agent/hooks)). -From this repo's `gitnexus-cursor-integration/hooks/`, copy the two files into your **project root**: +From this repo's `gitnexus-cursor-integration/hooks/`, copy the files below into your **project root**: ```text / ├── .cursor/ │ └── hooks.json ← from gitnexus-cursor-integration/hooks/hooks.json └── hooks/ - └── gitnexus-hook.cjs ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs + ├── gitnexus-hook.cjs ← from gitnexus-cursor-integration/hooks/gitnexus-hook.cjs + └── hook-lock.cjs ← from gitnexus-cursor-integration/hooks/hook-lock.cjs ``` Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` pointing at a clone of this repo): @@ -32,6 +33,7 @@ Equivalent shell commands (run from your project root, with `$GITNEXUS_REPO` poi mkdir -p .cursor hooks cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hooks.json" .cursor/hooks.json cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs" hooks/gitnexus-hook.cjs +cp "$GITNEXUS_REPO/gitnexus-cursor-integration/hooks/hook-lock.cjs" hooks/hook-lock.cjs ``` If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array rather than overwriting. @@ -49,7 +51,7 @@ If you already have a `.cursor/hooks.json`, merge the `hooks.postToolUse` array | -------------------------------------------------------------------- | ------------------------------ | | `~/.cursor/mcp.json` | ✅ | | `~/.cursor/skills/gitnexus/*` | ✅ | -| `/.cursor/hooks.json` + `/hooks/gitnexus-hook.cjs` | ❌ — copy manually (see above) | +| `/.cursor/hooks.json` + `/hooks/gitnexus-hook.cjs` + `/hooks/hook-lock.cjs` | ❌ — copy manually (see above) | Hook install is per-project (Cursor scopes hooks to a project root); skills and MCP config are global. @@ -84,6 +86,6 @@ Empty stdout means "no augmentation, continue normally" — the hook never block ## Troubleshooting -- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has both `.cursor/hooks.json` and the script at `hooks/gitnexus-hook.cjs`. Then `npx gitnexus list` to confirm the project is indexed. +- **Nothing happens** — Confirm Cursor is on 2.4+ and the project root has `.cursor/hooks.json` plus both hook files at `hooks/gitnexus-hook.cjs` and `hooks/hook-lock.cjs`. Then `npx gitnexus list` to confirm the project is indexed. - **`gitnexus` not found** — The hook prefers a locally-resolvable `gitnexus/dist/cli/index.js` and falls back to `npx -y gitnexus`. Install globally with `npm i -g gitnexus` to skip the npx cold-start latency. - **Wrong pattern extracted** — Set `GITNEXUS_DEBUG=1` and run a tool call. The raw stdin payload is logged to stderr; use it to confirm Cursor's actual `tool_input` field names against the table above. If they differ, file an issue with the captured payload. diff --git a/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs b/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs index 0ea336619..74c5587b3 100644 --- a/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs +++ b/gitnexus-cursor-integration/hooks/gitnexus-hook.cjs @@ -18,6 +18,7 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); +const { acquireHookSlot } = require('./hook-lock.cjs'); function readInput() { try { @@ -227,7 +228,8 @@ function main() { } const cwd = input.cwd || process.cwd(); if (!path.isAbsolute(cwd)) return; - if (!findGitNexusDir(cwd)) return; + const gitNexusDir = findGitNexusDir(cwd); + if (!gitNexusDir) return; const toolName = input.tool_name || ''; const toolInput = input.tool_input || {}; @@ -235,6 +237,9 @@ function main() { const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; + const release = acquireHookSlot(gitNexusDir); + if (!release) return; + const cliPath = resolveCliPath(); let result = ''; try { @@ -244,6 +249,8 @@ function main() { } } catch { /* graceful failure */ + } finally { + release(); } if (result && result.trim()) { diff --git a/gitnexus-cursor-integration/hooks/hook-lock.cjs b/gitnexus-cursor-integration/hooks/hook-lock.cjs new file mode 100644 index 000000000..759856384 --- /dev/null +++ b/gitnexus-cursor-integration/hooks/hook-lock.cjs @@ -0,0 +1,119 @@ +const fs = require('fs'); +const path = require('path'); + +const HOOK_LOCK_SUBDIR = '.hook-locks'; +const HOOK_LOCK_MAX_INFLIGHT = 3; +const HOOK_LOCK_STALE_MS = 30000; + +function acquireHookSlot(gitNexusDir) { + const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR); + try { + fs.mkdirSync(lockDir, { recursive: true }); + } catch { + // Cannot create lock dir (read-only fs, cross-user perm denial, out of + // inodes, etc.) — fail closed by returning null. Caller skips augment. + // Fail-open here would let N concurrent hooks all proceed unguarded and + // reintroduce the #1486 fan-out the guard exists to prevent. + return null; + } + + const myPidStr = String(process.pid); + + for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) { + const slotPath = path.join(lockDir, `slot-${slot}.lock`); + for (let attempt = 0; attempt < 2; attempt++) { + try { + fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' }); + let released = false; + const release = () => { + if (released) return; + released = true; + try { + // Only unlink if we still own the slot. If we appeared stale and + // another hook took over, the file now belongs to it — leave alone. + const content = fs.readFileSync(slotPath, 'utf-8').trim(); + if (content === myPidStr) fs.unlinkSync(slotPath); + } catch { + /* already removed or unreadable */ + } + }; + process.on('exit', release); + return release; + } catch { + // Slot exists. Decide whether to take it over. + // Open once and inspect mtime + content via the same fd so there's + // no TOCTOU between the metadata check and the content read + // (codeql js/file-system-race). + let fd; + try { + fd = fs.openSync(slotPath, 'r'); + } catch { + continue; // Vanished between EEXIST and open — retry this slot. + } + let isLive = false; + let mtimeMs = Date.now(); + try { + mtimeMs = fs.fstatSync(fd).mtimeMs; + const buf = Buffer.alloc(32); + const n = fs.readSync(fd, buf, 0, 32, 0); + const ownerStr = buf.slice(0, n).toString('utf-8').trim(); + if (ownerStr === '') { + // Owner created the file but hasn't written its PID yet. The + // wx open+write window is microseconds; give it the benefit + // of the doubt and treat as live. + isLive = true; + } else { + const owner = Number.parseInt(ownerStr, 10); + if (Number.isFinite(owner) && owner > 0) { + try { + process.kill(owner, 0); + isLive = true; + } catch (e) { + // ESRCH = process gone → treat as dead. EPERM = process exists + // but owned by another user (cross-user lock dir) → still alive, + // keep the slot. Anything else: be conservative, assume alive. + if (e && e.code === 'ESRCH') { + isLive = false; + } else { + isLive = true; + } + } + } + } + } catch { + /* unreadable — treat as dead */ + } finally { + try { + fs.closeSync(fd); + } catch { + /* already closed */ + } + } + // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins — + // a slow-but-alive hook is never wrongly evicted. For older slots, + // age is the final arbiter as a defense against PID reuse on long- + // abandoned slots. 30s >> the 7s augment timeout, so a healthy run + // never crosses this threshold. + if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) { + isLive = false; + } + if (isLive) break; // Try the next slot. + try { + fs.unlinkSync(slotPath); + } catch { + /* another hook beat us to it — retry will hit EEXIST */ + } + // Loop and retry this slot. + } + } + } + + return null; +} + +module.exports = { + HOOK_LOCK_SUBDIR, + HOOK_LOCK_MAX_INFLIGHT, + HOOK_LOCK_STALE_MS, + acquireHookSlot, +}; diff --git a/gitnexus/hooks/claude/gitnexus-hook.cjs b/gitnexus/hooks/claude/gitnexus-hook.cjs index 7bfa150cd..9541fcb50 100755 --- a/gitnexus/hooks/claude/gitnexus-hook.cjs +++ b/gitnexus/hooks/claude/gitnexus-hook.cjs @@ -14,6 +14,7 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); +const { acquireHookSlot } = require('./hook-lock.cjs'); /** * Read JSON input from stdin synchronously. @@ -207,7 +208,8 @@ function runGitNexusCli(cliPath, args, cwd, timeout) { function handlePreToolUse(input) { const cwd = input.cwd || process.cwd(); if (!path.isAbsolute(cwd)) return; - if (!findGitNexusDir(cwd)) return; + const gitNexusDir = findGitNexusDir(cwd); + if (!gitNexusDir) return; const toolName = input.tool_name || ''; const toolInput = input.tool_input || {}; @@ -217,6 +219,9 @@ function handlePreToolUse(input) { const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; + const release = acquireHookSlot(gitNexusDir); + if (!release) return; + const cliPath = resolveCliPath(); let result = ''; try { @@ -226,6 +231,8 @@ function handlePreToolUse(input) { } } catch { /* graceful failure */ + } finally { + release(); } if (result && result.trim()) { diff --git a/gitnexus/hooks/claude/hook-lock.cjs b/gitnexus/hooks/claude/hook-lock.cjs new file mode 100644 index 000000000..759856384 --- /dev/null +++ b/gitnexus/hooks/claude/hook-lock.cjs @@ -0,0 +1,119 @@ +const fs = require('fs'); +const path = require('path'); + +const HOOK_LOCK_SUBDIR = '.hook-locks'; +const HOOK_LOCK_MAX_INFLIGHT = 3; +const HOOK_LOCK_STALE_MS = 30000; + +function acquireHookSlot(gitNexusDir) { + const lockDir = path.join(gitNexusDir, HOOK_LOCK_SUBDIR); + try { + fs.mkdirSync(lockDir, { recursive: true }); + } catch { + // Cannot create lock dir (read-only fs, cross-user perm denial, out of + // inodes, etc.) — fail closed by returning null. Caller skips augment. + // Fail-open here would let N concurrent hooks all proceed unguarded and + // reintroduce the #1486 fan-out the guard exists to prevent. + return null; + } + + const myPidStr = String(process.pid); + + for (let slot = 0; slot < HOOK_LOCK_MAX_INFLIGHT; slot++) { + const slotPath = path.join(lockDir, `slot-${slot}.lock`); + for (let attempt = 0; attempt < 2; attempt++) { + try { + fs.writeFileSync(slotPath, myPidStr, { flag: 'wx' }); + let released = false; + const release = () => { + if (released) return; + released = true; + try { + // Only unlink if we still own the slot. If we appeared stale and + // another hook took over, the file now belongs to it — leave alone. + const content = fs.readFileSync(slotPath, 'utf-8').trim(); + if (content === myPidStr) fs.unlinkSync(slotPath); + } catch { + /* already removed or unreadable */ + } + }; + process.on('exit', release); + return release; + } catch { + // Slot exists. Decide whether to take it over. + // Open once and inspect mtime + content via the same fd so there's + // no TOCTOU between the metadata check and the content read + // (codeql js/file-system-race). + let fd; + try { + fd = fs.openSync(slotPath, 'r'); + } catch { + continue; // Vanished between EEXIST and open — retry this slot. + } + let isLive = false; + let mtimeMs = Date.now(); + try { + mtimeMs = fs.fstatSync(fd).mtimeMs; + const buf = Buffer.alloc(32); + const n = fs.readSync(fd, buf, 0, 32, 0); + const ownerStr = buf.slice(0, n).toString('utf-8').trim(); + if (ownerStr === '') { + // Owner created the file but hasn't written its PID yet. The + // wx open+write window is microseconds; give it the benefit + // of the doubt and treat as live. + isLive = true; + } else { + const owner = Number.parseInt(ownerStr, 10); + if (Number.isFinite(owner) && owner > 0) { + try { + process.kill(owner, 0); + isLive = true; + } catch (e) { + // ESRCH = process gone → treat as dead. EPERM = process exists + // but owned by another user (cross-user lock dir) → still alive, + // keep the slot. Anything else: be conservative, assume alive. + if (e && e.code === 'ESRCH') { + isLive = false; + } else { + isLive = true; + } + } + } + } + } catch { + /* unreadable — treat as dead */ + } finally { + try { + fs.closeSync(fd); + } catch { + /* already closed */ + } + } + // For slots younger than HOOK_LOCK_STALE_MS, PID-liveness wins — + // a slow-but-alive hook is never wrongly evicted. For older slots, + // age is the final arbiter as a defense against PID reuse on long- + // abandoned slots. 30s >> the 7s augment timeout, so a healthy run + // never crosses this threshold. + if (isLive && Date.now() - mtimeMs > HOOK_LOCK_STALE_MS) { + isLive = false; + } + if (isLive) break; // Try the next slot. + try { + fs.unlinkSync(slotPath); + } catch { + /* another hook beat us to it — retry will hit EEXIST */ + } + // Loop and retry this slot. + } + } + } + + return null; +} + +module.exports = { + HOOK_LOCK_SUBDIR, + HOOK_LOCK_MAX_INFLIGHT, + HOOK_LOCK_STALE_MS, + acquireHookSlot, +}; diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts index af3c4737a..8f52e0f2d 100644 --- a/gitnexus/src/cli/setup.ts +++ b/gitnexus/src/cli/setup.ts @@ -364,6 +364,15 @@ async function installClaudeCodeHooks(result: SetupResult): Promise { // Script not found in source — skip } + try { + await fs.copyFile( + path.join(pluginHooksPath, 'hook-lock.cjs'), + path.join(destHooksDir, 'hook-lock.cjs'), + ); + } catch { + // Helper not found in source — skip + } + const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/'); // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization). // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote` diff --git a/gitnexus/test/unit/cursor-hook.test.ts b/gitnexus/test/unit/cursor-hook.test.ts index f0d875dee..e64979895 100644 --- a/gitnexus/test/unit/cursor-hook.test.ts +++ b/gitnexus/test/unit/cursor-hook.test.ts @@ -35,6 +35,15 @@ const CURSOR_HOOK = path.resolve( 'hooks', 'gitnexus-hook.cjs', ); +const CURSOR_HOOK_LOCK = path.resolve( + __dirname, + '..', + '..', + '..', + 'gitnexus-cursor-integration', + 'hooks', + 'hook-lock.cjs', +); const CURSOR_HOOKS_JSON = path.resolve( __dirname, '..', @@ -60,16 +69,35 @@ function parseCursorOutput(stdout: string): { additional_context?: string } | nu // ─── Test fixtures ────────────────────────────────────────────────── let tmpDir: string; +// Separate fixture for the concurrency guard tests: this one has a real +// `.gitnexus/` so the hook reaches acquireHookSlot. The base tmpDir above +// deliberately has no .gitnexus so unrelated early-exit tests stay cheap. +let guardTmpDir: string; +let guardGitNexusDir: string; beforeAll(() => { tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-cursor-hook-test-')); spawnSync('git', ['init'], { cwd: tmpDir, stdio: 'pipe' }); spawnSync('git', ['config', 'user.email', 'test@test.com'], { cwd: tmpDir, stdio: 'pipe' }); spawnSync('git', ['config', 'user.name', 'Test'], { cwd: tmpDir, stdio: 'pipe' }); + + guardTmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-cursor-hook-guard-')); + guardGitNexusDir = path.join(guardTmpDir, '.gitnexus'); + fs.mkdirSync(guardGitNexusDir, { recursive: true }); + spawnSync('git', ['init'], { cwd: guardTmpDir, stdio: 'pipe' }); + spawnSync('git', ['config', 'user.email', 'test@test.com'], { + cwd: guardTmpDir, + stdio: 'pipe', + }); + spawnSync('git', ['config', 'user.name', 'Test'], { cwd: guardTmpDir, stdio: 'pipe' }); + fs.writeFileSync(path.join(guardTmpDir, 'dummy.txt'), 'hello'); + spawnSync('git', ['add', '.'], { cwd: guardTmpDir, stdio: 'pipe' }); + spawnSync('git', ['commit', '-m', 'init'], { cwd: guardTmpDir, stdio: 'pipe' }); }); afterAll(() => { fs.rmSync(tmpDir, { recursive: true, force: true }); + fs.rmSync(guardTmpDir, { recursive: true, force: true }); }); // ─── Manifest + hook file presence ─────────────────────────────────── @@ -375,6 +403,155 @@ describe('Cursor hook debug logging', () => { }); }); +// ─── Source code regression: concurrency guard (#1486) ───────────── + +describe('Cursor hook concurrency guard', () => { + const source = fs.readFileSync(CURSOR_HOOK, 'utf-8'); + const lockSource = fs.readFileSync(CURSOR_HOOK_LOCK, 'utf-8'); + + it('loads acquireHookSlot helper module', () => { + expect(source).toContain('acquireHookSlot'); + expect(source).toContain('hook-lock.cjs'); + }); + + it('helper defines acquireHookSlot with MAX_INFLIGHT constant', () => { + expect(lockSource).toContain('function acquireHookSlot'); + expect(lockSource).toContain('HOOK_LOCK_MAX_INFLIGHT'); + }); + + it('calls acquireHookSlot in main() and releases via finally', () => { + // The Cursor hook uses a flat main() dispatcher rather than a separate + // handlePreToolUse — assert the guard call + finally release wiring is + // present so a future refactor cannot accidentally skip it. + expect(source).toContain('acquireHookSlot('); + expect(source).toMatch(/finally\s*\{[^}]*release\(\)/s); + }); + + it('uses atomic fixed-name slot files (hard cap, not soft TOCTOU cap)', () => { + expect(lockSource).toMatch(/slot-\$\{slot\}\.lock|`slot-/); + const slotFn = lockSource.slice( + lockSource.indexOf('function acquireHookSlot'), + lockSource.indexOf('function', lockSource.indexOf('function acquireHookSlot') + 1), + ); + expect(slotFn).not.toContain('readdirSync'); + }); + + it('fails closed when lock dir cannot be created', () => { + // Regression: see hooks.test.ts. The mkdirSync catch must return null + // (skip augment) rather than `() => {}` (proceed unguarded), so that + // a read-only or cross-user `.gitnexus/` cannot reintroduce #1486. + const slotFn = lockSource.slice( + lockSource.indexOf('function acquireHookSlot'), + lockSource.indexOf('function', lockSource.indexOf('function acquireHookSlot') + 1), + ); + const mkdirCatch = slotFn.slice( + slotFn.indexOf('fs.mkdirSync(lockDir'), + slotFn.indexOf('const myPidStr'), + ); + expect(mkdirCatch).toContain('return null'); + expect(mkdirCatch).not.toMatch(/return\s*\(\s*\)\s*=>\s*\{\s*\}/); + }); + + // Note: the 10-concurrent-spawner burst test that validates `wx` + // (O_CREAT|O_EXCL) under simultaneous contention lives in + // hooks.test.ts. The Cursor hook uses byte-for-byte the same + // acquireHookSlot, so duplicating the burst test here would only test + // the OS primitive, not Cursor-specific wiring. The source-level checks + // above guarantee the Cursor hook keeps calling that same algorithm. +}); + +// ─── Integration: concurrency guard skips when slots are full ────── + +describe('Cursor hook concurrency guard (integration)', () => { + it('exits silently when all MAX_INFLIGHT slots hold live pids', async () => { + const { spawn } = await import('child_process'); + const lockDir = path.join(guardGitNexusDir, '.hook-locks'); + fs.mkdirSync(lockDir, { recursive: true }); + + const sleepers = [0, 1, 2].map(() => + spawn(process.execPath, ['-e', 'setTimeout(()=>{},60000)'], { + stdio: 'ignore', + detached: false, + }), + ); + const writtenLocks: string[] = []; + try { + for (let i = 0; i < sleepers.length; i++) { + const p = path.join(lockDir, `slot-${i}.lock`); + fs.writeFileSync(p, String(sleepers[i].pid)); + writtenLocks.push(p); + } + + const result = runHook(CURSOR_HOOK, { + tool_name: 'Grep', + tool_input: { query: 'validateUser' }, + cwd: guardTmpDir, + }); + + expect(result.stdout.trim()).toBe(''); + for (let i = 0; i < sleepers.length; i++) { + const p = path.join(lockDir, `slot-${i}.lock`); + expect(fs.existsSync(p)).toBe(true); + expect(fs.readFileSync(p, 'utf-8').trim()).toBe(String(sleepers[i].pid)); + } + } finally { + for (const child of sleepers) { + try { + child.kill(); + } catch { + /* ignore */ + } + } + for (const p of writtenLocks) { + try { + fs.unlinkSync(p); + } catch { + /* ignore */ + } + } + try { + fs.rmdirSync(lockDir); + } catch { + /* ignore */ + } + } + }); + + it('reclaims a slot held by a dead pid', () => { + const lockDir = path.join(guardGitNexusDir, '.hook-locks'); + fs.mkdirSync(lockDir, { recursive: true }); + const deadPid = 2_147_483_640; + const stalePath = path.join(lockDir, 'slot-0.lock'); + try { + fs.writeFileSync(stalePath, String(deadPid)); + expect(fs.readFileSync(stalePath, 'utf-8').trim()).toBe(String(deadPid)); + + runHook(CURSOR_HOOK, { + tool_name: 'Grep', + tool_input: { query: 'validateUser' }, + cwd: guardTmpDir, + }); + + // The hook reclaimed and then released slot-0 — either gone (released) + // or no longer owned by the dead pid. + if (fs.existsSync(stalePath)) { + expect(fs.readFileSync(stalePath, 'utf-8').trim()).not.toBe(String(deadPid)); + } + } finally { + try { + fs.unlinkSync(stalePath); + } catch { + /* already pruned */ + } + try { + fs.rmdirSync(lockDir); + } catch { + /* ignore */ + } + } + }); +}); + // ─── Documented contract behavior (extractPattern via the live hook) ─ describe('Shell quoted-pattern parser limitations (documented)', () => { @@ -429,6 +606,7 @@ describe('Cursor integration install docs', () => { const body = fs.readFileSync(integrationReadme, 'utf-8'); expect(body).toContain('.cursor/hooks.json'); expect(body).toContain('hooks/gitnexus-hook.cjs'); + expect(body).toContain('hooks/hook-lock.cjs'); expect(body).toContain('Hook install'); }); diff --git a/gitnexus/test/unit/hooks.test.ts b/gitnexus/test/unit/hooks.test.ts index da19da002..346ee1ed6 100644 --- a/gitnexus/test/unit/hooks.test.ts +++ b/gitnexus/test/unit/hooks.test.ts @@ -26,6 +26,7 @@ import { runHook, parseHookOutput } from '../utils/hook-test-helpers.js'; // ─── Paths to both hook variants ──────────────────────────────────── const CJS_HOOK = path.resolve(__dirname, '..', '..', 'hooks', 'claude', 'gitnexus-hook.cjs'); +const CJS_HOOK_LOCK = path.resolve(__dirname, '..', '..', 'hooks', 'claude', 'hook-lock.cjs'); const PLUGIN_HOOK = path.resolve( __dirname, '..', @@ -35,6 +36,15 @@ const PLUGIN_HOOK = path.resolve( 'hooks', 'gitnexus-hook.js', ); +const PLUGIN_HOOK_LOCK = path.resolve( + __dirname, + '..', + '..', + '..', + 'gitnexus-claude-plugin', + 'hooks', + 'hook-lock.js', +); // ─── Test fixtures: temporary .gitnexus directory ─────────────────── @@ -294,6 +304,296 @@ describe('Git mutation regex', () => { } }); +// ─── Source code regression: PreToolUse concurrency guard (#1486) ── + +describe('PreToolUse concurrency guard', () => { + for (const [label, hookPath, lockPath] of [ + ['CJS', CJS_HOOK, CJS_HOOK_LOCK], + ['Plugin', PLUGIN_HOOK, PLUGIN_HOOK_LOCK], + ] as const) { + it(`${label} hook loads acquireHookSlot helper`, () => { + const source = fs.readFileSync(hookPath, 'utf-8'); + expect(source).toContain('acquireHookSlot'); + expect(source).toContain('hook-lock'); + }); + + it(`${label} helper defines acquireHookSlot`, () => { + const source = fs.readFileSync(lockPath, 'utf-8'); + expect(source).toContain('function acquireHookSlot'); + expect(source).toContain('HOOK_LOCK_MAX_INFLIGHT'); + }); + + it(`${label} hook calls acquireHookSlot in handlePreToolUse`, () => { + const source = fs.readFileSync(hookPath, 'utf-8'); + const preBody = source.slice( + source.indexOf('function handlePreToolUse'), + source.indexOf('function handlePostToolUse'), + ); + expect(preBody).toContain('acquireHookSlot('); + expect(preBody).toMatch(/release\(\)/); + }); + + it(`${label} hook uses atomic fixed-name slot files (hard cap)`, () => { + // Regression for the TOCTOU soft-cap: an earlier revision counted + // entries then wrote a per-pid lock, which let simultaneous bursts + // exceed MAX_INFLIGHT. The hard-cap version writes to fixed-name + // slot-N.lock paths so O_CREAT|O_EXCL is atomic across processes. + const source = fs.readFileSync(lockPath, 'utf-8'); + expect(source).toMatch(/slot-\$\{slot\}\.lock|`slot-/); + // And no longer reads the lock dir to count active hooks. + const slotFn = source.slice( + source.indexOf('function acquireHookSlot'), + source.indexOf('function', source.indexOf('function acquireHookSlot') + 1), + ); + expect(slotFn).not.toContain('readdirSync'); + }); + + it(`${label} hook fails closed when lock dir cannot be created`, () => { + // Regression: an earlier revision returned `() => {}` (truthy no-op) on + // mkdirSync failure, which left callers — `if (!release) return;` — to + // proceed unguarded and reintroduce the #1486 fan-out on read-only or + // cross-user `.gitnexus/` setups. The guard must fail closed (null). + const source = fs.readFileSync(lockPath, 'utf-8'); + const slotFn = source.slice( + source.indexOf('function acquireHookSlot'), + source.indexOf('function', source.indexOf('function acquireHookSlot') + 1), + ); + const mkdirCatch = slotFn.slice( + slotFn.indexOf('fs.mkdirSync(lockDir'), + slotFn.indexOf('const myPidStr'), + ); + expect(mkdirCatch).toContain('return null'); + expect(mkdirCatch).not.toMatch(/return\s*\(\s*\)\s*=>\s*\{\s*\}/); + }); + } +}); + +// ─── Integration: concurrency guard skips when slots are full ────── + +describe('PreToolUse concurrency guard (integration)', () => { + for (const [label, hookPath] of [ + ['CJS', CJS_HOOK], + ['Plugin', PLUGIN_HOOK], + ] as const) { + it(`${label}: hook exits silently when all MAX_INFLIGHT slots hold live pids`, async () => { + const { spawn } = await import('child_process'); + const lockDir = path.join(gitNexusDir, '.hook-locks'); + fs.mkdirSync(lockDir, { recursive: true }); + + // Spawn 3 long-sleeping node child processes to use as live PIDs. + const sleepers = [0, 1, 2].map(() => + spawn(process.execPath, ['-e', 'setTimeout(()=>{},60000)'], { + stdio: 'ignore', + detached: false, + }), + ); + const writtenLocks: string[] = []; + try { + for (let i = 0; i < sleepers.length; i++) { + // Slot files are named slot-N.lock; content is the owning PID. + const p = path.join(lockDir, `slot-${i}.lock`); + fs.writeFileSync(p, String(sleepers[i].pid)); + writtenLocks.push(p); + } + + const result = runHook(hookPath, { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }); + + expect(result.stdout.trim()).toBe(''); + // Sentinel slot files survive; the hook bailed before claiming any of them. + for (let i = 0; i < sleepers.length; i++) { + const p = path.join(lockDir, `slot-${i}.lock`); + expect(fs.existsSync(p)).toBe(true); + // Owner unchanged. + expect(fs.readFileSync(p, 'utf-8').trim()).toBe(String(sleepers[i].pid)); + } + } finally { + for (const child of sleepers) { + try { + child.kill(); + } catch { + /* ignore */ + } + } + for (const p of writtenLocks) { + try { + fs.unlinkSync(p); + } catch { + /* ignore */ + } + } + try { + fs.rmdirSync(lockDir); + } catch { + /* ignore */ + } + } + }); + + it(`${label}: hook reclaims a slot held by a dead pid`, () => { + const lockDir = path.join(gitNexusDir, '.hook-locks'); + fs.mkdirSync(lockDir, { recursive: true }); + // PID 1 exists on every POSIX system (init); on Windows process.kill(1,0) + // throws. Use a definitely-dead PID instead: a very large number unlikely + // to be assigned. + const deadPid = 2_147_483_640; + const stalePath = path.join(lockDir, 'slot-0.lock'); + try { + fs.writeFileSync(stalePath, String(deadPid)); + expect(fs.readFileSync(stalePath, 'utf-8').trim()).toBe(String(deadPid)); + + runHook(hookPath, { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }); + + // The hook reclaimed and then released slot-0 — either the file is + // gone (released) or its content is something other than the dead PID. + if (fs.existsSync(stalePath)) { + expect(fs.readFileSync(stalePath, 'utf-8').trim()).not.toBe(String(deadPid)); + } + } finally { + try { + fs.unlinkSync(stalePath); + } catch { + /* already pruned */ + } + try { + fs.rmdirSync(lockDir); + } catch { + /* ignore */ + } + } + }); + + it(`${label}: hook does not exceed MAX_INFLIGHT under simultaneous bursts (hard cap)`, async () => { + // Spawn many hook processes concurrently and assert that at most + // MAX_INFLIGHT (3) slot files end up populated by live pids. The + // O_CREAT|O_EXCL slot scheme makes this a hard cap, not the soft cap + // that the count-then-claim approach gives. + const { spawn } = await import('child_process'); + const lockDir = path.join(gitNexusDir, '.hook-locks'); + // Clean any leftover slot files. + try { + for (const f of fs.readdirSync(lockDir)) fs.unlinkSync(path.join(lockDir, f)); + } catch { + /* dir may not exist yet */ + } + fs.mkdirSync(lockDir, { recursive: true }); + + // We use child workers that just claim a slot via the same algorithm + // and then sleep, so we can observe the on-disk state under contention + // without spawning the real gitnexus augment CLI. + const claimerScript = ` + const fs = require('fs'); const path = require('path'); + const lockDir = ${JSON.stringify(lockDir)}; + const MAX = 3; + const STALE = 30000; + const myPid = String(process.pid); + function tryAcquire() { + for (let slot = 0; slot < MAX; slot++) { + const p = path.join(lockDir, 'slot-' + slot + '.lock'); + for (let a = 0; a < 2; a++) { + try { fs.writeFileSync(p, myPid, { flag: 'wx' }); return p; } + catch { + let stat; try { stat = fs.statSync(p); } catch { continue; } + let live = false; + try { + const s = fs.readFileSync(p, 'utf-8').trim(); + if (s === '') live = true; + else { const o = Number.parseInt(s, 10); + if (Number.isFinite(o) && o > 0) { try { process.kill(o, 0); live = true; } catch {} } + } + } catch {} + if (live && Date.now() - stat.mtimeMs > STALE) live = false; + if (live) break; + try { fs.unlinkSync(p); } catch {} + } + } + } + return null; + } + const claimed = tryAcquire(); + if (claimed) { + process.stdout.write('CLAIMED:' + claimed + '\\n'); + setTimeout(() => {}, 5000); + } else { + process.stdout.write('SKIPPED\\n'); + } + `; + + const N = 10; + const claimers = Array.from({ length: N }, () => + spawn(process.execPath, ['-e', claimerScript], { + stdio: ['ignore', 'pipe', 'ignore'], + detached: false, + }), + ); + try { + // Wait until every claimer has printed its decision. + const decisions = await Promise.all( + claimers.map( + (c) => + new Promise((resolve) => { + let buf = ''; + c.stdout!.on('data', (d) => { + buf += d.toString(); + if (buf.includes('\n')) resolve(buf.split('\n')[0]); + }); + c.on('exit', () => resolve(buf.split('\n')[0] || 'EXIT')); + }), + ), + ); + const claimedCount = decisions.filter((d) => d.startsWith('CLAIMED:')).length; + const skippedCount = decisions.filter((d) => d === 'SKIPPED').length; + + // HARD CAP: never more than 3 winners, regardless of how many bursts. + expect(claimedCount).toBeLessThanOrEqual(3); + // And the remainder must have all explicitly skipped. + expect(claimedCount + skippedCount).toBe(N); + + // On-disk state matches. + const liveSlots = fs + .readdirSync(lockDir) + .filter((f) => /^slot-\d+\.lock$/.test(f)) + .filter((f) => { + try { + const o = Number.parseInt(fs.readFileSync(path.join(lockDir, f), 'utf-8').trim(), 10); + return Number.isFinite(o) && o > 0; + } catch { + return false; + } + }); + expect(liveSlots.length).toBeLessThanOrEqual(3); + } finally { + for (const c of claimers) { + try { + c.kill(); + } catch { + /* ignore */ + } + } + try { + for (const f of fs.readdirSync(lockDir)) fs.unlinkSync(path.join(lockDir, f)); + } catch { + /* ignore */ + } + try { + fs.rmdirSync(lockDir); + } catch { + /* ignore */ + } + } + }); + } +}); + // ─── Integration: PostToolUse staleness detection ─────────────────── describe('PostToolUse staleness detection (integration)', () => { From e8c8ddec8a02faa6621624d797190c62caae8056 Mon Sep 17 00:00:00 2001 From: azizur100389 Date: Wed, 13 May 2026 11:53:09 +0100 Subject: [PATCH 11/33] fix(wiki): sanitize generated mermaid diagrams (#1539) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(wiki): sanitize generated mermaid diagrams * fix(wiki): address mermaid sanitizer review --------- Co-authored-by: Gergő Magyar --- gitnexus/src/core/wiki/generator.ts | 9 +- gitnexus/src/core/wiki/html-viewer.ts | 3 +- gitnexus/src/core/wiki/mermaid-sanitizer.ts | 119 ++++++++++++++++++ gitnexus/test/integration/cli-e2e.test.ts | 56 ++++----- .../test/unit/wiki-mermaid-sanitizer.test.ts | 97 ++++++++++++++ 5 files changed, 248 insertions(+), 36 deletions(-) create mode 100644 gitnexus/src/core/wiki/mermaid-sanitizer.ts create mode 100644 gitnexus/test/unit/wiki-mermaid-sanitizer.test.ts diff --git a/gitnexus/src/core/wiki/generator.ts b/gitnexus/src/core/wiki/generator.ts index 9f65d26e8..dc9c2e74e 100644 --- a/gitnexus/src/core/wiki/generator.ts +++ b/gitnexus/src/core/wiki/generator.ts @@ -28,6 +28,7 @@ import { type FileWithExports, } from './graph-queries.js'; import { generateHTMLViewer } from './html-viewer.js'; +import { sanitizeMermaidMarkdown } from './mermaid-sanitizer.js'; import { callLLM, @@ -591,7 +592,7 @@ export class WikiGenerator { const response = await this.invokeLLM(prompt, MODULE_SYSTEM_PROMPT, this.streamOpts(node.name)); // Write page with front matter - const pageContent = `# ${node.name}\n\n${response.content}`; + const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`); await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8'); } @@ -631,7 +632,7 @@ export class WikiGenerator { const response = await this.invokeLLM(prompt, PARENT_SYSTEM_PROMPT, this.streamOpts(node.name)); - const pageContent = `# ${node.name}\n\n${response.content}`; + const pageContent = sanitizeMermaidMarkdown(`# ${node.name}\n\n${response.content}`); await fs.writeFile(path.join(this.wikiDir, `${node.slug}.md`), pageContent, 'utf-8'); } @@ -681,7 +682,9 @@ export class WikiGenerator { this.streamOpts('Generating overview', 88), ); - const pageContent = `# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`; + const pageContent = sanitizeMermaidMarkdown( + `# ${path.basename(this.repoPath)} — Wiki\n\n${response.content}`, + ); await fs.writeFile(path.join(this.wikiDir, 'overview.md'), pageContent, 'utf-8'); } diff --git a/gitnexus/src/core/wiki/html-viewer.ts b/gitnexus/src/core/wiki/html-viewer.ts index f961d36ae..c0fd7323a 100644 --- a/gitnexus/src/core/wiki/html-viewer.ts +++ b/gitnexus/src/core/wiki/html-viewer.ts @@ -7,6 +7,7 @@ import fs from 'fs/promises'; import path from 'path'; +import { sanitizeMermaidMarkdown } from './mermaid-sanitizer.js'; interface ModuleTreeNode { name: string; @@ -42,7 +43,7 @@ export async function generateHTMLViewer(wikiDir: string, projectName: string): const dirEntries = await fs.readdir(wikiDir); for (const f of dirEntries.filter((f) => f.endsWith('.md'))) { const content = await fs.readFile(path.join(wikiDir, f), 'utf-8'); - pages[f.replace(/\.md$/, '')] = content; + pages[f.replace(/\.md$/, '')] = sanitizeMermaidMarkdown(content); } const html = buildHTML(projectName, moduleTree, pages, meta); diff --git a/gitnexus/src/core/wiki/mermaid-sanitizer.ts b/gitnexus/src/core/wiki/mermaid-sanitizer.ts new file mode 100644 index 000000000..c8d443c78 --- /dev/null +++ b/gitnexus/src/core/wiki/mermaid-sanitizer.ts @@ -0,0 +1,119 @@ +const MERMAID_FENCE_RE = /```mermaid\s*\n([\s\S]*?)```/g; +const NODE_LABEL_RE = + /(\[[^\]\n]*(?:\\n)[^\]\n]*\]|\{[^}\n]*(?:\\n)[^}\n]*\}|\([^)\n]*(?:\\n)[^)\n]*\))/g; +const EDGE_LABEL_RE = /\|([^|\n]+)\|/g; +const UNSAFE_EDGE_LABEL_RE = /[()[\]{}<>]/; +const UNSAFE_NODE_ID_RE = /[^A-Za-z0-9_-]/; +const NODE_ID_RE = /^[A-Za-z0-9_.:/()-]+$/; + +const LINE_PREFIX_RE = /^(\s*(?:(?:[-A-Za-z0-9_]+)\s*:\s*)?)(.*)$/; +const EDGE_RE = + /(\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?\|[^|\n]*\|(?:[>|ox])?|\s*(?:[ox])?(?:--+|==+|\.\.+)(?:[>|ox])?|\s*<--+>?\s*)/g; + +export function sanitizeMermaidMarkdown(markdown: string): string { + return markdown.replace(MERMAID_FENCE_RE, (_match, diagram: string) => { + return '```mermaid\n' + sanitizeMermaidDiagram(diagram) + '```'; + }); +} + +export function sanitizeMermaidDiagram(diagram: string): string { + const aliases = new Map(); + let nextAlias = 1; + + const aliasFor = (id: string): string => { + const existing = aliases.get(id); + if (existing) return existing; + + const base = id.replace(/[^A-Za-z0-9_-]/g, '_').replace(/^_+|_+$/g, '') || 'node'; + let alias = base; + while ([...aliases.values()].includes(alias)) { + nextAlias += 1; + alias = `${base}_${nextAlias}`; + } + aliases.set(id, alias); + return alias; + }; + + return diagram + .split('\n') + .map((line) => sanitizeMermaidLine(line, aliasFor)) + .join('\n'); +} + +function sanitizeMermaidLine(line: string, aliasFor: (id: string) => string): string { + let sanitized = replaceLiteralLineBreaksInLabels(line); + sanitized = quoteUnsafeEdgeLabels(sanitized); + + const prefixMatch = sanitized.match(LINE_PREFIX_RE); + if (!prefixMatch) return sanitized; + + const prefix = prefixMatch[1]; + const body = prefixMatch[2]; + if (isDirectiveLine(body)) return sanitized; + + const parts = body.split(EDGE_RE); + if (parts.length === 1) return sanitized; + + for (let i = 0; i < parts.length; i += 2) { + parts[i] = sanitizeNodeReference(parts[i], aliasFor); + } + + return prefix + parts.join(''); +} + +function replaceLiteralLineBreaksInLabels(line: string): string { + return line.replace(NODE_LABEL_RE, (label) => label.replace(/\\n/g, '
')); +} + +function quoteUnsafeEdgeLabels(line: string): string { + return line.replace(EDGE_LABEL_RE, (match, label: string) => { + const trimmed = label.trim(); + if (!UNSAFE_EDGE_LABEL_RE.test(trimmed)) return match; + if ( + (trimmed.startsWith('"') && trimmed.endsWith('"')) || + (trimmed.startsWith("'") && trimmed.endsWith("'")) + ) { + return match; + } + return `|"${escapeMermaidLabel(trimmed)}"|`; + }); +} + +function sanitizeNodeReference(segment: string, aliasFor: (id: string) => string): string { + const match = segment.match(/^(\s*)([A-Za-z0-9_.:/()-]+)(.*?)(\s*)$/); + if (!match) return segment; + + const [, leading, id, suffix, trailing] = match; + if (!NODE_ID_RE.test(id) || !UNSAFE_NODE_ID_RE.test(id)) return segment; + const hasInlineLabel = + suffix.trim().startsWith('[') || suffix.trim().startsWith('(') || suffix.trim().startsWith('{'); + + if (hasInlineLabel) return `${leading}${aliasFor(id)}${suffix}${trailing}`; + + return `${leading}${aliasFor(id)}["${escapeMermaidLabel(id)}"]${suffix}${trailing}`; +} + +function escapeMermaidLabel(label: string): string { + return label.replace(/\\/g, '\\\\').replace(/"/g, '\\"'); +} + +function isDirectiveLine(line: string): boolean { + const trimmed = line.trim(); + return ( + trimmed === '' || + trimmed.startsWith('%%') || + trimmed.startsWith('graph ') || + trimmed.startsWith('flowchart ') || + trimmed.startsWith('sequenceDiagram') || + trimmed.startsWith('classDiagram') || + trimmed.startsWith('stateDiagram') || + trimmed.startsWith('erDiagram') || + trimmed.startsWith('journey') || + trimmed.startsWith('gantt') || + trimmed.startsWith('pie ') || + trimmed.startsWith('mindmap') || + trimmed.startsWith('timeline') || + trimmed.startsWith('subgraph ') || + trimmed === 'end' + ); +} diff --git a/gitnexus/test/integration/cli-e2e.test.ts b/gitnexus/test/integration/cli-e2e.test.ts index 8037511bf..99e52c330 100644 --- a/gitnexus/test/integration/cli-e2e.test.ts +++ b/gitnexus/test/integration/cli-e2e.test.ts @@ -36,6 +36,7 @@ const FIXTURE_SRC = path.resolve(testDir, '..', 'fixtures', 'mini-repo'); // still works), `afterAll` rms the parent tmpdir. let MINI_REPO: string; let tmpParent: string; +let suiteGitnexusHome: string; // Absolute file:// URL to tsx loader — needed when spawning CLI with cwd // outside the project tree (bare 'tsx' specifier won't resolve there). @@ -49,6 +50,7 @@ beforeAll(() => { // Copy the fixture into an isolated tmpdir named `mini-repo` so that the // `--repo mini-repo` CLI arg (which matches by basename) still works. tmpParent = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-cli-e2e-')); + suiteGitnexusHome = fs.mkdtempSync(path.join(os.tmpdir(), 'gn-cli-e2e-home-')); MINI_REPO = path.join(tmpParent, 'mini-repo'); fs.cpSync(FIXTURE_SRC, MINI_REPO, { recursive: true }); @@ -75,21 +77,30 @@ afterAll(() => { if (tmpParent) { fs.rmSync(tmpParent, { recursive: true, force: true }); } + if (suiteGitnexusHome) { + fs.rmSync(suiteGitnexusHome, { recursive: true, force: true }); + } }); +function cliEnv(extraEnv: Record = {}) { + return { + ...process.env, + GITNEXUS_HOME: suiteGitnexusHome, + // Pre-set --max-old-space-size so analyzeCommand's ensureHeap() sees it + // and skips the re-exec. The re-exec drops the tsx loader (--import tsx + // is not in process.argv), causing ERR_UNKNOWN_FILE_EXTENSION on .ts files. + NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), + ...extraEnv, + }; +} + function runCli(command: string, cwd: string, timeoutMs = 15000) { return spawnSync(process.execPath, ['--import', tsxImportUrl, cliEntry, command], { cwd, encoding: 'utf8', timeout: timeoutMs, stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - // Pre-set --max-old-space-size so analyzeCommand's ensureHeap() sees it - // and skips the re-exec. The re-exec drops the tsx loader (--import tsx - // is not in process.argv), causing ERR_UNKNOWN_FILE_EXTENSION on .ts files. - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }); } @@ -103,10 +114,7 @@ function runCliRaw(extraArgs: string[], cwd: string, timeoutMs = 15000) { encoding: 'utf8', timeout: timeoutMs, stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }); } @@ -126,11 +134,7 @@ function runCliWithEnv( encoding: 'utf8', timeout: timeoutMs, stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - ...extraEnv, - }, + env: cliEnv(extraEnv), }); } @@ -919,10 +923,7 @@ describe('CLI end-to-end', () => { encoding: 'utf8', timeout: timeoutMs, stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }); } @@ -1042,10 +1043,7 @@ describe('CLI end-to-end', () => { encoding: 'utf8', timeout: 15000, stdio: ['pipe', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }, ); if (result.status === null) return; @@ -1159,10 +1157,7 @@ describe('CLI end-to-end', () => { { cwd: MINI_REPO, stdio: ['ignore', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }, ); @@ -1212,10 +1207,7 @@ describe('CLI end-to-end', () => { { cwd: MINI_REPO, stdio: ['ignore', 'pipe', 'pipe'], - env: { - ...process.env, - NODE_OPTIONS: `${process.env.NODE_OPTIONS || ''} --max-old-space-size=8192`.trim(), - }, + env: cliEnv(), }, ); diff --git a/gitnexus/test/unit/wiki-mermaid-sanitizer.test.ts b/gitnexus/test/unit/wiki-mermaid-sanitizer.test.ts new file mode 100644 index 000000000..e8c74c8cb --- /dev/null +++ b/gitnexus/test/unit/wiki-mermaid-sanitizer.test.ts @@ -0,0 +1,97 @@ +import { describe, expect, it } from 'vitest'; + +import { + sanitizeMermaidDiagram, + sanitizeMermaidMarkdown, +} from '../../src/core/wiki/mermaid-sanitizer.js'; + +describe('sanitizeMermaidMarkdown', () => { + it('replaces literal newline escapes inside rectangle and diamond labels', () => { + const markdown = [ + '```mermaid', + 'flowchart TD', + ' A[HTTP request\\nwith ID param] --> B{Preceding tei:zone\\nwith @start=#pid?}', + '```', + ].join('\n'); + + const sanitized = sanitizeMermaidMarkdown(markdown); + + expect(sanitized).toContain('A[HTTP request
with ID param]'); + expect(sanitized).toContain('B{Preceding tei:zone
with @start=#pid?}'); + expect(sanitized).not.toContain('\\n'); + }); + + it('quotes unsafe edge labels without changing safe labels', () => { + const diagram = [ + 'graph LR', + ' Script -->|doc()| eXist[(eXist-db XML)]', + ' Client -->|HTTP params| Script', + ].join('\n'); + + const sanitized = sanitizeMermaidDiagram(diagram); + + expect(sanitized).toContain('Script -->|"doc()"| eXist[(eXist-db XML)]'); + expect(sanitized).toContain('Client -->|HTTP params| Script'); + }); + + it('escapes backslashes and quotes in quoted edge labels', () => { + const diagram = ['graph LR', ' Script -->|doc("C:\\\\tmp")| Target'].join('\n'); + + const sanitized = sanitizeMermaidDiagram(diagram); + + expect(sanitized).toContain('Script -->|"doc(\\"C:\\\\\\\\tmp\\")"| Target'); + }); + + it('aliases bare node IDs that contain dots and keeps display labels', () => { + const diagram = [ + 'graph LR', + ' Client -->|xmlurl + xslurl| xslt-conversion.xq', + ' xslt-conversion.xq -->|stream-transform| lbpwebjs-main.xsl', + ' lbpwebjs-main.xsl -->|fetches| TEI-XML[(TEI XML in eXist)]', + ].join('\n'); + + const sanitized = sanitizeMermaidDiagram(diagram); + + expect(sanitized).toContain( + 'Client -->|xmlurl + xslurl| xslt-conversion_xq["xslt-conversion.xq"]', + ); + expect(sanitized).toContain( + 'xslt-conversion_xq["xslt-conversion.xq"] -->|stream-transform| lbpwebjs-main_xsl["lbpwebjs-main.xsl"]', + ); + expect(sanitized).toContain( + 'lbpwebjs-main_xsl["lbpwebjs-main.xsl"] -->|fetches| TEI-XML[(TEI XML in eXist)]', + ); + }); + + it('aliases unsafe node IDs while preserving existing inline labels', () => { + const diagram = [ + 'graph LR', + ' file.name.ts[(eXist-db XML)] --> target.node["Target node"]', + ].join('\n'); + + const sanitized = sanitizeMermaidDiagram(diagram); + + expect(sanitized).toContain('file_name_ts[(eXist-db XML)] --> target_node["Target node"]'); + }); + + it('only rewrites fenced Mermaid blocks in markdown', () => { + const markdown = [ + 'Regular text with doc() and file.name.ts.', + '', + '```ts', + 'const label = "A\\nB";', + '```', + '', + '```mermaid', + 'flowchart LR', + ' A -->|doc()| file.name.ts', + '```', + ].join('\n'); + + const sanitized = sanitizeMermaidMarkdown(markdown); + + expect(sanitized).toContain('Regular text with doc() and file.name.ts.'); + expect(sanitized).toContain('const label = "A\\nB";'); + expect(sanitized).toContain('A -->|"doc()"| file_name_ts["file.name.ts"]'); + }); +}); From 48cd55a120718b7804ba15d3206386e527036279 Mon Sep 17 00:00:00 2001 From: azizur100389 Date: Wed, 13 May 2026 12:30:21 +0100 Subject: [PATCH 12/33] fix(search): guard against undefined bm25Results when FTS unavailable (#1489) (#1540) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(search): guard against undefined bm25Results when FTS unavailable (#1489) When the FTS extension is unavailable in the MCP process, searchFTSFromLbug can return an unexpected shape or throw, leaving bm25Results undefined. The for-loop then crashes with "bm25Results is not iterable". - mergeWithRRF: default both inputs via ?? [] so undefined never reaches the iteration loops - hybridSearch: wrap searchFTSFromLbug in try/catch and fall back to semantic-only search instead of crashing - local-backend query handler: guard bm25SearchResult?.results and semanticResults with ?? [] - bm25Search: wrap the dynamic import in try/catch for sandboxed MCP contexts; guard ftsResponse?.results Adds 6 regression tests covering undefined inputs and FTS failure fallback. Fixes #1489 * fix(search): address review findings on #1489 crash guards - Guard ftsResponse.results with ?? [] in hybridSearch (Finding 1) - Add logger.warn on bm25-index.js import failure (Finding 3) - Add unit test for callTool query FTS throw path (Finding 2) --------- Co-authored-by: Gergő Magyar --- gitnexus/src/core/search/hybrid-search.ts | 29 +++++-- gitnexus/src/mcp/local/local-backend.ts | 29 +++++-- gitnexus/test/unit/calltool-dispatch.test.ts | 13 ++++ gitnexus/test/unit/hybrid-search.test.ts | 82 +++++++++++++++++++- 4 files changed, 137 insertions(+), 16 deletions(-) diff --git a/gitnexus/src/core/search/hybrid-search.ts b/gitnexus/src/core/search/hybrid-search.ts index b76a9f5e9..a2521dd83 100644 --- a/gitnexus/src/core/search/hybrid-search.ts +++ b/gitnexus/src/core/search/hybrid-search.ts @@ -50,9 +50,15 @@ export const mergeWithRRF = ( ): HybridSearchResult[] => { const merged = new Map(); + // Guard against undefined/null inputs (#1489) — when FTS is unavailable + // in the MCP process, bm25Results can arrive as undefined and the + // for-loop would throw "bm25Results is not iterable". + const safeBm25 = bm25Results ?? []; + const safeSemantic = semanticResults ?? []; + // Process BM25 results - for (let i = 0; i < bm25Results.length; i++) { - const r = bm25Results[i]; + for (let i = 0; i < safeBm25.length; i++) { + const r = safeBm25[i]; const rrfScore = 1 / (RRF_K + i + 1); // i+1 because rank starts at 1 merged.set(r.filePath, { @@ -65,8 +71,8 @@ export const mergeWithRRF = ( } // Process semantic results and merge - for (let i = 0; i < semanticResults.length; i++) { - const r = semanticResults[i]; + for (let i = 0; i < safeSemantic.length; i++) { + const r = safeSemantic[i]; const rrfScore = 1 / (RRF_K + i + 1); const existing = merged.get(r.filePath); @@ -149,6 +155,9 @@ export const formatHybridResults = (results: HybridSearchResult[]): string => { * Execute BM25 + semantic search and merge with RRF. * Uses LadybugDB FTS for always-fresh BM25 results (no cached data). * The semanticSearch function is injected to keep this module environment-agnostic. + * + * When FTS is unavailable (e.g. read-only MCP connection, missing indexes), + * falls back to semantic-only results instead of crashing (#1489). */ export const hybridSearch = async ( query: string, @@ -160,8 +169,16 @@ export const hybridSearch = async ( k?: number, ) => Promise, ): Promise => { - // Use LadybugDB FTS for always-fresh BM25 results - const { results: bm25Results } = await searchFTSFromLbug(query, limit); + // Use LadybugDB FTS for always-fresh BM25 results. + // If FTS fails (e.g. extension not loaded in MCP process), fall back to + // semantic-only search instead of crashing with "bm25Results is not iterable". + let bm25Results: BM25SearchResult[] = []; + try { + const ftsResponse = await searchFTSFromLbug(query, limit); + bm25Results = ftsResponse?.results ?? []; + } catch { + // FTS unavailable — continue with semantic-only search + } const semanticResults = await semanticSearch(executeQuery, query, limit); return mergeWithRRF(bm25Results, semanticResults, limit); }; diff --git a/gitnexus/src/mcp/local/local-backend.ts b/gitnexus/src/mcp/local/local-backend.ts index 167c1db81..922a69f85 100644 --- a/gitnexus/src/mcp/local/local-backend.ts +++ b/gitnexus/src/mcp/local/local-backend.ts @@ -755,8 +755,10 @@ export class LocalBackend { timer.time('vector', this.semanticSearch(repo, searchQuery, searchLimit)), ]); - const bm25Results = bm25SearchResult.results; - const ftsUsed = bm25SearchResult.ftsUsed; + // Guard against undefined results (#1489) — when FTS is entirely + // unavailable the search helper may return an unexpected shape. + const bm25Results = bm25SearchResult?.results ?? []; + const ftsUsed = bm25SearchResult?.ftsUsed ?? false; // Merge via reciprocal rank fusion timer.start('merge'); @@ -774,8 +776,9 @@ export class LocalBackend { } } - for (let i = 0; i < semanticResults.length; i++) { - const result = semanticResults[i]; + const safeSemanticResults = semanticResults ?? []; + for (let i = 0; i < safeSemanticResults.length; i++) { + const result = safeSemanticResults[i]; const key = result.nodeId || result.filePath; const rrfScore = 1 / (60 + i); const existing = scoreMap.get(key); @@ -992,7 +995,17 @@ export class LocalBackend { query: string, limit: number, ): Promise<{ results: any[]; ftsUsed: boolean }> { - const { searchFTSFromLbug } = await import('../../core/search/bm25-index.js'); + let searchFTSFromLbug; + try { + ({ searchFTSFromLbug } = await import('../../core/search/bm25-index.js')); + } catch (err: any) { + // Module import can fail in sandboxed MCP contexts (#1489) + logger.warn( + { err: err?.message }, + 'GitNexus: bm25-index.js import failed — falling back to semantic-only', + ); + return { results: [], ftsUsed: false }; + } let ftsResponse; try { ftsResponse = await searchFTSFromLbug(query, limit, repo.id); @@ -1004,8 +1017,10 @@ export class LocalBackend { return { results: [], ftsUsed: false }; } - const bm25Results = ftsResponse.results; - const ftsUsed = ftsResponse.ftsAvailable; + // Guard against unexpected response shape (#1489) — ftsResponse.results + // could be undefined when the FTS extension is unavailable in the MCP process. + const bm25Results = ftsResponse?.results ?? []; + const ftsUsed = ftsResponse?.ftsAvailable ?? false; const results: any[] = []; diff --git a/gitnexus/test/unit/calltool-dispatch.test.ts b/gitnexus/test/unit/calltool-dispatch.test.ts index 45e1b71d2..8a9a1a629 100644 --- a/gitnexus/test/unit/calltool-dispatch.test.ts +++ b/gitnexus/test/unit/calltool-dispatch.test.ts @@ -216,6 +216,19 @@ describe('LocalBackend.callTool', () => { expect(result).not.toHaveProperty('warning'); }); + it('does not crash when searchFTSFromLbug throws (#1489)', async () => { + const { searchFTSFromLbug } = await import('../../src/core/search/bm25-index.js'); + vi.mocked(searchFTSFromLbug).mockRejectedValueOnce(new Error('bm25Results is not iterable')); + (executeParameterized as any).mockResolvedValue([]); + + const result = await backend.callTool('query', { query: 'auth' }); + + // Should still return a valid result shape (semantic-only fallback) + expect(result).toHaveProperty('processes'); + expect(result).toHaveProperty('definitions'); + expect(result).not.toHaveProperty('error'); + }); + it('skips vector index query when VECTOR is unsupported by the platform', async () => { const cap = _captureLogger(); platformMocks.isVectorExtensionSupportedByPlatform.mockReturnValue(false); diff --git a/gitnexus/test/unit/hybrid-search.test.ts b/gitnexus/test/unit/hybrid-search.test.ts index ee2a4499b..813f78aa7 100644 --- a/gitnexus/test/unit/hybrid-search.test.ts +++ b/gitnexus/test/unit/hybrid-search.test.ts @@ -1,5 +1,5 @@ /** - * P1 Unit Tests: Hybrid Search (mergeWithRRF) + * P1 Unit Tests: Hybrid Search (mergeWithRRF + hybridSearch) * * Tests: mergeWithRRF from hybrid-search.ts * - BM25-only merge @@ -7,12 +7,20 @@ * - Combined ranking * - Limit parameter * - Empty inputs + * - Undefined/null inputs (#1489) + * + * Tests: hybridSearch fallback when FTS unavailable (#1489) */ -import { describe, it, expect } from 'vitest'; -import { mergeWithRRF } from '../../src/core/search/hybrid-search.js'; +import { describe, it, expect, vi } from 'vitest'; +import { mergeWithRRF, hybridSearch } from '../../src/core/search/hybrid-search.js'; import type { BM25SearchResult } from '../../src/core/search/bm25-index.js'; import type { SemanticSearchResult } from '../../src/core/embeddings/types.js'; +vi.mock('../../src/core/search/bm25-index.js', async (importOriginal) => { + const actual = (await importOriginal()) as any; + return { ...actual, searchFTSFromLbug: vi.fn() }; +}); + let bm25Rank = 0; function makeBM25(filePath: string, score: number): BM25SearchResult { return { filePath, score, rank: ++bm25Rank }; @@ -123,4 +131,72 @@ describe('mergeWithRRF', () => { expect(result[0].bm25Score).toBe(15); expect(result[0].semanticScore).toBeCloseTo(0.7); // 1 - distance }); + + // Regression: #1489 — bm25Results is not iterable when FTS unavailable + it('does not crash when bm25Results is undefined (#1489)', () => { + const semantic: SemanticSearchResult[] = [makeSemantic('src/a.ts', 0.1)]; + // Force undefined to simulate the crash path where FTS returns unexpected shape + const result = mergeWithRRF(undefined as any, semantic); + expect(result).toHaveLength(1); + expect(result[0].filePath).toBe('src/a.ts'); + expect(result[0].sources).toEqual(['semantic']); + }); + + it('does not crash when semanticResults is undefined (#1489)', () => { + const bm25: BM25SearchResult[] = [makeBM25('src/a.ts', 10)]; + const result = mergeWithRRF(bm25, undefined as any); + expect(result).toHaveLength(1); + expect(result[0].filePath).toBe('src/a.ts'); + expect(result[0].sources).toEqual(['bm25']); + }); + + it('does not crash when both inputs are undefined (#1489)', () => { + const result = mergeWithRRF(undefined as any, undefined as any); + expect(result).toHaveLength(0); + }); +}); + +// Regression: #1489 — hybridSearch must not crash when FTS is unavailable +describe('hybridSearch — FTS failure fallback (#1489)', () => { + it('falls back to semantic-only when searchFTSFromLbug throws', async () => { + const { searchFTSFromLbug } = await import('../../src/core/search/bm25-index.js'); + vi.mocked(searchFTSFromLbug).mockRejectedValueOnce(new Error('bm25Results is not iterable')); + + const mockExecuteQuery = vi.fn().mockResolvedValue([]); + const mockSemanticSearch = vi + .fn() + .mockResolvedValue([makeSemantic('src/semantic-hit.ts', 0.15)]); + + const results = await hybridSearch('test query', 10, mockExecuteQuery, mockSemanticSearch); + expect(results).toHaveLength(1); + expect(results[0].filePath).toBe('src/semantic-hit.ts'); + expect(results[0].sources).toEqual(['semantic']); + }); + + it('returns empty when both FTS and semantic return nothing', async () => { + const { searchFTSFromLbug } = await import('../../src/core/search/bm25-index.js'); + vi.mocked(searchFTSFromLbug).mockRejectedValueOnce(new Error('FTS unavailable')); + + const mockExecuteQuery = vi.fn().mockResolvedValue([]); + const mockSemanticSearch = vi.fn().mockResolvedValue([]); + + const results = await hybridSearch('test query', 10, mockExecuteQuery, mockSemanticSearch); + expect(results).toHaveLength(0); + }); + + it('works normally when FTS succeeds', async () => { + const { searchFTSFromLbug } = await import('../../src/core/search/bm25-index.js'); + vi.mocked(searchFTSFromLbug).mockResolvedValueOnce({ + results: [{ filePath: 'src/fts-hit.ts', score: 5, rank: 1 }], + ftsAvailable: true, + }); + + const mockExecuteQuery = vi.fn().mockResolvedValue([]); + const mockSemanticSearch = vi.fn().mockResolvedValue([]); + + const results = await hybridSearch('test query', 10, mockExecuteQuery, mockSemanticSearch); + expect(results).toHaveLength(1); + expect(results[0].filePath).toBe('src/fts-hit.ts'); + expect(results[0].sources).toEqual(['bm25']); + }); }); From 4cc4e9c84b98eb8c3f3fd251a409a139fbd658f9 Mon Sep 17 00:00:00 2001 From: GoGoLin <47466606+LINSUISHENG034@users.noreply.github.com> Date: Wed, 13 May 2026 20:02:58 +0800 Subject: [PATCH 13/33] fix(build): use platform-aware tsc command for win32 (#1531) --- gitnexus/scripts/build.js | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/gitnexus/scripts/build.js b/gitnexus/scripts/build.js index 84f43fc6b..ec7f67cf4 100644 --- a/gitnexus/scripts/build.js +++ b/gitnexus/scripts/build.js @@ -21,11 +21,15 @@ const SHARED_DEST = path.join(DIST, '_shared'); // ── 1. Build gitnexus-shared ─────────────────────────────────────── console.log('[build] compiling gitnexus-shared…'); -execSync('npx tsc', { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 }); +const tscCmd = + process.platform === 'win32' + ? path.join('node_modules', '.bin', 'tsc.cmd') + : path.join('node_modules', '.bin', 'tsc'); +execSync(tscCmd, { cwd: SHARED_ROOT, stdio: 'inherit', timeout: 120_000 }); // ── 2. Build gitnexus ────────────────────────────────────────────── console.log('[build] compiling gitnexus…'); -execSync('npx tsc', { cwd: ROOT, stdio: 'inherit', timeout: 120_000 }); +execSync(tscCmd, { cwd: ROOT, stdio: 'inherit', timeout: 120_000 }); // ── 3. Copy shared dist ──────────────────────────────────────────── console.log('[build] copying shared module into dist/_shared…'); From a9d72e2dbf696976c6f09f7ef90e7acff1bc4182 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 13:31:07 +0100 Subject: [PATCH 14/33] chore(deps): bump urllib3 in /eval in the uv group across 1 directory (#1512) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps the uv group with 1 update in the /eval directory: [urllib3](https://github.com/urllib3/urllib3). Updates `urllib3` from 2.6.3 to 2.7.0 - [Release notes](https://github.com/urllib3/urllib3/releases) - [Changelog](https://github.com/urllib3/urllib3/blob/main/CHANGES.rst) - [Commits](https://github.com/urllib3/urllib3/compare/2.6.3...2.7.0) --- updated-dependencies: - dependency-name: urllib3 dependency-version: 2.7.0 dependency-type: indirect dependency-group: uv ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Gergő Magyar --- eval/uv.lock | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/eval/uv.lock b/eval/uv.lock index fcd666e75..04b89f336 100644 --- a/eval/uv.lock +++ b/eval/uv.lock @@ -2278,11 +2278,11 @@ wheels = [ [[package]] name = "urllib3" -version = "2.6.3" +version = "2.7.0" source = { registry = "https://pypi.org/simple" } -sdist = { url = "https://files.pythonhosted.org/packages/c7/24/5f1b3bdffd70275f6661c76461e25f024d5a38a46f04aaca912426a2b1d3/urllib3-2.6.3.tar.gz", hash = "sha256:1b62b6884944a57dbe321509ab94fd4d3b307075e0c2eae991ac71ee15ad38ed", size = 435556, upload-time = "2026-01-07T16:24:43.925Z" } +sdist = { url = "https://files.pythonhosted.org/packages/53/0c/06f8b233b8fd13b9e5ee11424ef85419ba0d8ba0b3138bf360be2ff56953/urllib3-2.7.0.tar.gz", hash = "sha256:231e0ec3b63ceb14667c67be60f2f2c40a518cb38b03af60abc813da26505f4c", size = 433602, upload-time = "2026-05-07T16:13:18.596Z" } wheels = [ - { url = "https://files.pythonhosted.org/packages/39/08/aaaad47bc4e9dc8c725e68f9d04865dbcb2052843ff09c97b08904852d84/urllib3-2.6.3-py3-none-any.whl", hash = "sha256:bf272323e553dfb2e87d9bfd225ca7b0f467b919d7bbd355436d3fd37cb0acd4", size = 131584, upload-time = "2026-01-07T16:24:42.685Z" }, + { url = "https://files.pythonhosted.org/packages/7f/3e/5db95bcf282c52709639744ca2a8b149baccf648e39c8cc87553df9eae0c/urllib3-2.7.0-py3-none-any.whl", hash = "sha256:9fb4c81ebbb1ce9531cce37674bbc6f1360472bc18ca9a553ede278ef7276897", size = 131087, upload-time = "2026-05-07T16:13:17.151Z" }, ] [[package]] From 38ff7365e862625c50d88974b5cce9dc462b3bd6 Mon Sep 17 00:00:00 2001 From: Hugo Gu Date: Wed, 13 May 2026 21:45:37 +0800 Subject: [PATCH 15/33] fix(docker): install ca-certificates in runtime image for TLS verification (#1545) (#1547) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Close: #1545 Co-authored-by: Gergő Magyar --- Dockerfile.cli | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Dockerfile.cli b/Dockerfile.cli index 60b56451f..05bedd6c3 100644 --- a/Dockerfile.cli +++ b/Dockerfile.cli @@ -40,8 +40,8 @@ RUN npm prune --omit=dev --prefix gitnexus # node:22-bookworm-slim FROM node:22-bookworm-slim@sha256:9f6d5975c7dca860947d3915877f85607946403fc55349f39b4bc3688448bb6e AS runtime -# curl for the healthcheck; git so `gitnexus` can clone repos at runtime. -RUN apt-get update && apt-get install -y --no-install-recommends curl git && rm -rf /var/lib/apt/lists/* \ +# curl for the healthcheck; git for cloning; ca-certificates for TLS verification. +RUN apt-get update && apt-get install -y --no-install-recommends curl git ca-certificates && rm -rf /var/lib/apt/lists/* \ && rm -rf /usr/local/lib/node_modules/npm \ && rm -rf /usr/local/lib/node_modules/corepack \ && rm -f /usr/local/bin/npm /usr/local/bin/npx /usr/local/bin/corepack From 507f84b69af29f6a5596538a59175bd930d07e57 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9on=20Simmons?= Date: Wed, 13 May 2026 12:14:52 -0400 Subject: [PATCH 16/33] fix(docker): symlink gitnexus binary onto $PATH in runtime image (#1551) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The README documents the Docker workflow as: WORKSPACE_DIR=$HOME/code docker compose up -d docker compose exec gitnexus-server gitnexus index /workspace/my-repo …but `gitnexus` is not on $PATH inside the published image: $ docker compose exec gitnexus-server which gitnexus (empty) $ docker compose exec gitnexus-server gitnexus --version exec: "gitnexus": executable file not found in $PATH The package.json `bin` entry (`"gitnexus": "dist/cli/index.js"`) would normally surface via `node_modules/.bin/gitnexus`, but `npm prune --omit=dev` in the builder stage strips that directory before the runtime stage copies it in. The `dist/cli/index.js` itself already has the `#!/usr/bin/env node` shebang and 755 permissions, so a single symlink into /usr/local/bin makes the README's literal command work. Verified locally: $ docker build -f Dockerfile.cli -t gitnexus:local-pr-test . $ docker run --rm gitnexus:local-pr-test gitnexus --version 1.6.4 $ docker run --rm gitnexus:local-pr-test gitnexus --help Usage: gitnexus [options] [command] … $ docker run --rm -d --name t gitnexus:local-pr-test \ && sleep 4 && docker exec t curl -s localhost:4747/api/health {"status":"ok"} CMD continues to invoke `node gitnexus/dist/cli/index.js serve …` unchanged, so the change is additive and the server boot path is untouched. Refs #1549. --- Dockerfile.cli | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/Dockerfile.cli b/Dockerfile.cli index 05bedd6c3..3275c8f7e 100644 --- a/Dockerfile.cli +++ b/Dockerfile.cli @@ -58,6 +58,15 @@ COPY --from=builder --chown=node:node /app/gitnexus/package.json ./gitnexus/pack COPY --from=builder --chown=node:node /app/gitnexus/scripts/install-duckdb-extension.mjs ./gitnexus/scripts/install-duckdb-extension.mjs COPY --from=builder --chown=node:node /app/gitnexus/vendor ./gitnexus/vendor +# Expose the `gitnexus` binary on PATH so the documented Docker workflow +# (`docker compose exec gitnexus-server gitnexus index /workspace/`) +# works without users having to invoke `node /app/gitnexus/dist/cli/index.js`. +# `npm prune --omit=dev` in the builder stage strips `node_modules/.bin/` +# entries, so the `gitnexus` bin declared in package.json (`dist/cli/index.js`, +# which already carries `#!/usr/bin/env node` and 755 perms) is otherwise +# unreachable from $PATH. +RUN ln -s /app/gitnexus/dist/cli/index.js /usr/local/bin/gitnexus + USER node # The web UI defaults to http://localhost:4747 - keep that contract. From 88d3df77cc74aaf08e813f8f220b5914a2e122c8 Mon Sep 17 00:00:00 2001 From: Shane Thurston Wijaya <129602553+sanguine59@users.noreply.github.com> Date: Thu, 14 May 2026 00:35:39 +0700 Subject: [PATCH 17/33] feat:(wiki) added --timeout and --retries flags for large module pages to mitigate timeout aborts (#1543) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat:(wiki) added --timeout and --retries flags for large module pages to mitigate timeout aborts * docs(wiki): document --timeout and --retries options * docs(wiki): document --timeout and --retries in SKILL.md --------- Co-authored-by: Gergő Magyar --- README.md | 6 ++++++ gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md | 2 ++ gitnexus/src/cli/index.ts | 2 ++ gitnexus/src/cli/wiki.ts | 12 ++++++++++++ gitnexus/src/core/wiki/llm-client.ts | 10 +++++++--- 5 files changed, 29 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 3c3a28c27..e08c0eb7d 100644 --- a/README.md +++ b/README.md @@ -722,6 +722,12 @@ gitnexus wiki --base-url https://api.anthropic.com/v1 # Force full regeneration gitnexus wiki --force + + +# Increase the timeout or retries for large codebase or slow LLM providers +gitnexus wiki --timeout # Per-attempt LLM request timeout in seconds (default: 60) +gitnexus wiki --retries # Max LLM retry attempts per request (default: 3) + ``` The wiki generator reads the indexed graph structure, groups files into modules via LLM, generates per-module documentation pages, and creates an overview page — all with cross-references to the knowledge graph. diff --git a/gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md b/gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md index 1c38face4..11945b8cc 100644 --- a/gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md +++ b/gitnexus-claude-plugin/skills/gitnexus-cli/SKILL.md @@ -62,6 +62,8 @@ Generates repository documentation from the knowledge graph using an LLM. Requir | `--api-key ` | LLM API key | | `--concurrency ` | Parallel LLM calls (default: 3) | | `--gist` | Publish wiki as a public GitHub Gist | +| `--timeout ` | Per-attempt LLM request timeout in seconds (default: 60) | +| `--retries ` | Max LLM retry attempts per request (default: 3) | ### list — Show all indexed repos diff --git a/gitnexus/src/cli/index.ts b/gitnexus/src/cli/index.ts index d38675f03..4b009e4aa 100644 --- a/gitnexus/src/cli/index.ts +++ b/gitnexus/src/cli/index.ts @@ -161,6 +161,8 @@ program ) .option('--no-reasoning-model', 'Disable reasoning model mode (overrides saved config)') .option('--concurrency ', 'Parallel LLM calls (default: 3)', '3') + .option('--timeout ', 'Per-attempt LLM request timeout in seconds (default: 60)') + .option('--retries ', 'Max LLM retry attempts per request (default: 3)') .option('--gist', 'Publish wiki as a public GitHub Gist after generation') .option('-v, --verbose', 'Enable verbose output (show LLM commands and responses)') .option('--review', 'Stop after grouping to review module structure before generating pages') diff --git a/gitnexus/src/cli/wiki.ts b/gitnexus/src/cli/wiki.ts index 38a0f82a6..8d9da9572 100644 --- a/gitnexus/src/cli/wiki.ts +++ b/gitnexus/src/cli/wiki.ts @@ -33,6 +33,8 @@ export interface WikiCommandOptions { provider?: LLMProvider; verbose?: boolean; review?: boolean; + timeout?: string; + retries?: string; } /** @@ -347,6 +349,16 @@ export const wikiCommand = async (inputPath?: string, options?: WikiCommandOptio } } + // ── Apply per-run overrides not saved to config ──────────────────── + if (options?.timeout) { + const secs = parseInt(options.timeout, 10); + if (!isNaN(secs) && secs > 0) llmConfig.requestTimeoutMs = secs * 1000; + } + if (options?.retries) { + const n = parseInt(options.retries, 10); + if (!isNaN(n) && n > 0) llmConfig.maxAttempts = n; + } + // ── Setup progress bar with elapsed timer ────────────────────────── const bar = new cliProgress.SingleBar( { diff --git a/gitnexus/src/core/wiki/llm-client.ts b/gitnexus/src/core/wiki/llm-client.ts index 37fe7a9f2..40ef831bf 100644 --- a/gitnexus/src/core/wiki/llm-client.ts +++ b/gitnexus/src/core/wiki/llm-client.ts @@ -23,6 +23,10 @@ export interface LLMConfig { apiVersion?: string; /** When true, strips sampling params and uses max_completion_tokens instead of max_tokens */ isReasoningModel?: boolean; + /** Per-attempt fetch timeout in ms (default: 60_000). */ + requestTimeoutMs?: number; + /** Max fetch attempts before giving up (default: 3). */ + maxAttempts?: number; } export interface LLMResponse { @@ -237,12 +241,12 @@ export async function callLLM( // indefinitely on a frozen TCP connection — the per-call // signal is the only timeout `resilientFetch` honors; // `capDelayMs` only bounds the *backoff* between attempts. - // 60s matches typical LLM completion budgets. - signal: AbortSignal.timeout(60_000), + // Default 60s; raise via --timeout for slow models or large pages. + signal: AbortSignal.timeout(config.requestTimeoutMs ?? 60_000), }, { breakerKey: `wiki-llm-${new URL(url).host}`, - retry: { maxAttempts: 3, baseDelayMs: 2_000, capDelayMs: 30_000 }, + retry: { maxAttempts: config.maxAttempts ?? 3, baseDelayMs: 2_000, capDelayMs: 30_000 }, }, ); } catch (err) { From afa38432a45224fa0fac23842ec035ff5c33484a Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Wed, 13 May 2026 22:17:53 +0100 Subject: [PATCH 18/33] chore(deps)(deps-dev): bump vite from 8.0.10 to 8.0.11 in /gitnexus-web (#1555) --- gitnexus-web/package-lock.json | 168 ++++++++++++++++----------------- gitnexus-web/package.json | 2 +- 2 files changed, 85 insertions(+), 85 deletions(-) diff --git a/gitnexus-web/package-lock.json b/gitnexus-web/package-lock.json index fa15ce15d..91613d2b1 100644 --- a/gitnexus-web/package-lock.json +++ b/gitnexus-web/package-lock.json @@ -60,7 +60,7 @@ "jsdom": "^29.1.1", "tree-sitter-wasms": "^0.1.13", "typescript": "^5.4.5", - "vite": "^8.0.10", + "vite": "^8.0.11", "vitest": "^4.1.5", "wait-on": "^9.0.5" }, @@ -1713,9 +1713,9 @@ } }, "node_modules/@oxc-project/types": { - "version": "0.127.0", - "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.127.0.tgz", - "integrity": "sha512-aIYXQBo4lCbO4z0R3FHeucQHpF46l2LbMdxRvqvuRuW2OxdnSkcng5B8+K12spgLDj93rtN3+J2Vac/TIO+ciQ==", + "version": "0.128.0", + "resolved": "https://registry.npmjs.org/@oxc-project/types/-/types-0.128.0.tgz", + "integrity": "sha512-huv1Y/LzBJkBVHt3OlC7u0zHBW9qXf1FdD7sGmc1rXc2P1mTwHssYv7jyGx5KAACSCH+9B3Bhn6Z9luHRvf7pQ==", "license": "MIT", "funding": { "url": "https://github.com/sponsors/Boshen" @@ -1738,9 +1738,9 @@ } }, "node_modules/@rolldown/binding-android-arm64": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.17.tgz", - "integrity": "sha512-s70pVGhw4zqGeFnXWvAzJDlvxhlRollagdCCKRgOsgUOH3N1l0LIxf83AtGzmb5SiVM4Hjl5HyarMRfdfj3DaQ==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-android-arm64/-/binding-android-arm64-1.0.0-rc.18.tgz", + "integrity": "sha512-lIDyUAfD7U3+BWKzdxMbJcsYHuqXqmGz40aeRqvuAm3y5TkJSYTBW2RDrn65DJFPQqVjUAUqq5uz8urzQ8aBdQ==", "cpu": [ "arm64" ], @@ -1754,9 +1754,9 @@ } }, "node_modules/@rolldown/binding-darwin-arm64": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.17.tgz", - "integrity": "sha512-4ksWc9n0mhlZpZ9PMZgTGjeOPRu8MB1Z3Tz0Mo02eWfWCHMW1zN82Qz/pL/rC+yQa+8ZnutMF0JjJe7PjwasYw==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-arm64/-/binding-darwin-arm64-1.0.0-rc.18.tgz", + "integrity": "sha512-apJq2ktnGp27nSInMR5Vcj8kY6xJzDAvfdIFlpDcAK/w4cDO58qVoi1YQsES/SKiFNge/6e4CUzgjfHduYqWpQ==", "cpu": [ "arm64" ], @@ -1770,9 +1770,9 @@ } }, "node_modules/@rolldown/binding-darwin-x64": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.17.tgz", - "integrity": "sha512-SUSDOI6WwUVNcWxd02QEBjLdY1VPHvlEkw6T/8nYG322iYWCTxRb1vzk4E+mWWYehTp7ERibq54LSJGjmouOsw==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-darwin-x64/-/binding-darwin-x64-1.0.0-rc.18.tgz", + "integrity": "sha512-5Ofot8xbs+pxRHJqm9/9N/4sTQOvdrwEsmPE9pdLEEoAbdZtG6F2LMDfO1sp6ZAtXJuJV/21ew2srq3W8NXB5g==", "cpu": [ "x64" ], @@ -1786,9 +1786,9 @@ } }, "node_modules/@rolldown/binding-freebsd-x64": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.17.tgz", - "integrity": "sha512-hwnz3nw9dbJ05EDO/PvcjaaewqqDy7Y1rn1UO81l8iIK1GjenME75dl16ajbvSSMfv66WXSRCYKIqfgq2KCfxw==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-freebsd-x64/-/binding-freebsd-x64-1.0.0-rc.18.tgz", + "integrity": "sha512-7h8eeOTT1eyqJyx64BFCnWZpNm486hGWt2sqeLLgDxA0xI1oGZ9H7gK1S85uNGmBhkdPwa/6reTxfFFKvIsebw==", "cpu": [ "x64" ], @@ -1802,9 +1802,9 @@ } }, "node_modules/@rolldown/binding-linux-arm-gnueabihf": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.17.tgz", - "integrity": "sha512-IS+W7epTcwANmFSQFrS1SivEXHtl1JtuQA9wlxrZTcNi6mx+FDOYrakGevvvTwgj2JvWiK8B29/qD9BELZPyXQ==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm-gnueabihf/-/binding-linux-arm-gnueabihf-1.0.0-rc.18.tgz", + "integrity": "sha512-eRcm/HVt9U/JFu5RKAEKwGQYtDCKWLiaH6wOnsSEp6NMBb/3Os8LgHZlNyzMpFVNmiiMFlfb2zEnebfzJrHFmg==", "cpu": [ "arm" ], @@ -1818,9 +1818,9 @@ } }, "node_modules/@rolldown/binding-linux-arm64-gnu": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.17.tgz", - "integrity": "sha512-e6usGaHKW5BMNZOymS1UcEYGowQMWcgZ71Z17Sl/h2+ZziNJ1a9n3Zvcz6LdRyIW5572wBCTH/Z+bKuZouGk9Q==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-gnu/-/binding-linux-arm64-gnu-1.0.0-rc.18.tgz", + "integrity": "sha512-SOrT/cT4ukTmgnrEz/Hg3m7LBnuCLW9psDeMKrimRWY4I8DmnO7Lco8W2vtqPmMkbVu8iJ+g4GFLVLLOVjJ9DQ==", "cpu": [ "arm64" ], @@ -1834,9 +1834,9 @@ } }, "node_modules/@rolldown/binding-linux-arm64-musl": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.17.tgz", - "integrity": "sha512-b/CgbwAJpmrRLp02RPfhbudf5tZnN9nsPWK82znefso832etkem8H7FSZwxrOI9djcdTP7U6YfNhbRnh7djErg==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-arm64-musl/-/binding-linux-arm64-musl-1.0.0-rc.18.tgz", + "integrity": "sha512-QWjdxN1HJCpBTAcZ5N5F7wju3gVPzRzSpmGzx7na0c/1qpN9CFil+xt+l9lV/1M6/gqHSNXCiqPfwhVJPeLnug==", "cpu": [ "arm64" ], @@ -1850,9 +1850,9 @@ } }, "node_modules/@rolldown/binding-linux-ppc64-gnu": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.17.tgz", - "integrity": "sha512-4EII1iNGRUN5WwGbF/kOh/EIkoDN9HsupgLQoXfY+D1oyJm7/F4t5PYU5n8SWZgG0FEwakyM8pGgwcBYruGTlA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-ppc64-gnu/-/binding-linux-ppc64-gnu-1.0.0-rc.18.tgz", + "integrity": "sha512-ugCOyj7a4d9h3q9B+wXmf6g3a68UsjGh6dob5DHevHGMwDUbhsYNbSPxJsENcIttJZ9jv7qGM2UesLw5jqIhdg==", "cpu": [ "ppc64" ], @@ -1866,9 +1866,9 @@ } }, "node_modules/@rolldown/binding-linux-s390x-gnu": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.17.tgz", - "integrity": "sha512-AH8oq3XqQo4IibpVXvPeLDI5pzkpYn0WiZAfT05kFzoJ6tQNzwRdDYQ45M8I/gslbodRZwW8uxLhbSBbkv96rA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-s390x-gnu/-/binding-linux-s390x-gnu-1.0.0-rc.18.tgz", + "integrity": "sha512-kKWRhbsotpXkGbcd5dllUWg5gEXcDAa8u5YnP9AV5DYNbvJHGzzuwv7dpmhc8NqKMJldl0a+x76IHbspEpEmdA==", "cpu": [ "s390x" ], @@ -1882,9 +1882,9 @@ } }, "node_modules/@rolldown/binding-linux-x64-gnu": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.17.tgz", - "integrity": "sha512-cLnjV3xfo7KslbU41Z7z8BH/E1y5mzUYzAqih1d1MDaIGZRCMqTijqLv76/P7fyHuvUcfGsIpqCdddbxLLK9rA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-gnu/-/binding-linux-x64-gnu-1.0.0-rc.18.tgz", + "integrity": "sha512-uCo8ElcCIAMyYAZyuIZ81oFkhTSIllNvUCHCAlbhlN4ji3uC28h7IIdlXyIvGO7HsuqnV9p3rD/bpH7XhIyhRw==", "cpu": [ "x64" ], @@ -1898,9 +1898,9 @@ } }, "node_modules/@rolldown/binding-linux-x64-musl": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.17.tgz", - "integrity": "sha512-0phclDw1spsL7dUB37sIARuis2tAgomCJXAHZlpt8PXZ4Ba0dRP1e+66lsRqrfhISeN9bEGNjQs+T/Fbd7oYGw==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-linux-x64-musl/-/binding-linux-x64-musl-1.0.0-rc.18.tgz", + "integrity": "sha512-XNOQZtuE6yUIvx4rwGemwh8kpL1xvU41FXy/s9K7T/3JVcqGzo3NfKM2HrbrGgfPYGFW42f07Wk++aOC6B9NWA==", "cpu": [ "x64" ], @@ -1914,9 +1914,9 @@ } }, "node_modules/@rolldown/binding-openharmony-arm64": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.17.tgz", - "integrity": "sha512-0ag/hEgXOwgw4t8QyQvUCxvEg+V0KBcA6YuOx9g0r02MprutRF5dyljgm3EmR02O292UX7UeS6HzWHAl6KgyhA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-openharmony-arm64/-/binding-openharmony-arm64-1.0.0-rc.18.tgz", + "integrity": "sha512-tSn/kzrfa7tNOXr7sEacDBN4YsIqTyLqh45IO0nHDwtpKIDNDJr+VFojt+4klSpChxB29JLyduSsE0MKEwa65A==", "cpu": [ "arm64" ], @@ -1930,9 +1930,9 @@ } }, "node_modules/@rolldown/binding-wasm32-wasi": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.17.tgz", - "integrity": "sha512-LEXei6vo0E5wTGwpkJ4KoT3OZJRnglwldt5ziLzOlc6qqb55z4tWNq2A+PFqCJuvWWdP53CVhG1Z9NtToDPJrA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-wasm32-wasi/-/binding-wasm32-wasi-1.0.0-rc.18.tgz", + "integrity": "sha512-+J9YGmc+czgqlhYmwun3S3O0FIZhsH8ep2456xwjAdIOmuJxM7xz4P4PtrxU+Bz17a/5bqPA8o3HAAoX0teUdg==", "cpu": [ "wasm32" ], @@ -1948,9 +1948,9 @@ } }, "node_modules/@rolldown/binding-win32-arm64-msvc": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.17.tgz", - "integrity": "sha512-gUmyzBl3SPMa6hrqFUth9sVfcLBlYsbMzBx5PlexMroZStgzGqlZ26pYG89rBb45Mnia+oil6YAIFeEWGWhoZA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-arm64-msvc/-/binding-win32-arm64-msvc-1.0.0-rc.18.tgz", + "integrity": "sha512-zsu47DgU0FQzSwi6sU9dZoEdUv7pc1AptSEz/Z8HBg54sV0Pbs3N0+CrIbTsgiu6EyoaNN9CHboqbLaz9lhOyQ==", "cpu": [ "arm64" ], @@ -1964,9 +1964,9 @@ } }, "node_modules/@rolldown/binding-win32-x64-msvc": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.17.tgz", - "integrity": "sha512-3hkiolcUAvPB9FLb3UZdfjVVNWherN1f/skkGWJP/fgSQhYUZpSIRr0/I8ZK9TkF3F7kxvJAk0+IcKvPHk9qQg==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/binding-win32-x64-msvc/-/binding-win32-x64-msvc-1.0.0-rc.18.tgz", + "integrity": "sha512-7H+3yqGgmnlDTRRhw/xpYY9J1kf4GC681nVc4GqKhExZTDrVVrV2tsOR9kso0fvgBdcTCcQShx4SLLoHgaLwhg==", "cpu": [ "x64" ], @@ -7136,9 +7136,9 @@ } }, "node_modules/nanoid": { - "version": "3.3.11", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", - "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", + "version": "3.3.12", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz", + "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==", "funding": [ { "type": "github", @@ -7515,9 +7515,9 @@ } }, "node_modules/postcss": { - "version": "8.5.10", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.10.tgz", - "integrity": "sha512-pMMHxBOZKFU6HgAZ4eyGnwXF/EvPGGqUr0MnZ5+99485wwW41kW91A4LOGxSHhgugZmSChL5AlElNdwlNgcnLQ==", + "version": "8.5.14", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.14.tgz", + "integrity": "sha512-SoSL4+OSEtR99LHFZQiJLkT59C5B1amGO1NzTwj7TT1qCUgUO6hxOvzkOYxD+vMrXBM3XJIKzokoERdqQq/Zmg==", "funding": [ { "type": "opencollective", @@ -7867,13 +7867,13 @@ "license": "Unlicense" }, "node_modules/rolldown": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.17.tgz", - "integrity": "sha512-ZrT53oAKrtA4+YtBWPQbtPOxIbVDbxT0orcYERKd63VJTF13zPcgXTvD4843L8pcsI7M6MErt8QtON6lrB9tyA==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/rolldown/-/rolldown-1.0.0-rc.18.tgz", + "integrity": "sha512-phmyKBpuBdRYDf4hgyynGAYn/rDDe+iZXKVJ7WX5b1zQzpLkP5oJRPGsfJuHdzPMlyyEO/4sPW6yfSx2gf7lVg==", "license": "MIT", "dependencies": { - "@oxc-project/types": "=0.127.0", - "@rolldown/pluginutils": "1.0.0-rc.17" + "@oxc-project/types": "=0.128.0", + "@rolldown/pluginutils": "1.0.0-rc.18" }, "bin": { "rolldown": "bin/cli.mjs" @@ -7882,27 +7882,27 @@ "node": "^20.19.0 || >=22.12.0" }, "optionalDependencies": { - "@rolldown/binding-android-arm64": "1.0.0-rc.17", - "@rolldown/binding-darwin-arm64": "1.0.0-rc.17", - "@rolldown/binding-darwin-x64": "1.0.0-rc.17", - "@rolldown/binding-freebsd-x64": "1.0.0-rc.17", - "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.17", - "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.17", - "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.17", - "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.17", - "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.17", - "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.17", - "@rolldown/binding-linux-x64-musl": "1.0.0-rc.17", - "@rolldown/binding-openharmony-arm64": "1.0.0-rc.17", - "@rolldown/binding-wasm32-wasi": "1.0.0-rc.17", - "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.17", - "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.17" + "@rolldown/binding-android-arm64": "1.0.0-rc.18", + "@rolldown/binding-darwin-arm64": "1.0.0-rc.18", + "@rolldown/binding-darwin-x64": "1.0.0-rc.18", + "@rolldown/binding-freebsd-x64": "1.0.0-rc.18", + "@rolldown/binding-linux-arm-gnueabihf": "1.0.0-rc.18", + "@rolldown/binding-linux-arm64-gnu": "1.0.0-rc.18", + "@rolldown/binding-linux-arm64-musl": "1.0.0-rc.18", + "@rolldown/binding-linux-ppc64-gnu": "1.0.0-rc.18", + "@rolldown/binding-linux-s390x-gnu": "1.0.0-rc.18", + "@rolldown/binding-linux-x64-gnu": "1.0.0-rc.18", + "@rolldown/binding-linux-x64-musl": "1.0.0-rc.18", + "@rolldown/binding-openharmony-arm64": "1.0.0-rc.18", + "@rolldown/binding-wasm32-wasi": "1.0.0-rc.18", + "@rolldown/binding-win32-arm64-msvc": "1.0.0-rc.18", + "@rolldown/binding-win32-x64-msvc": "1.0.0-rc.18" } }, "node_modules/rolldown/node_modules/@rolldown/pluginutils": { - "version": "1.0.0-rc.17", - "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.17.tgz", - "integrity": "sha512-n8iosDOt6Ig1UhJ2AYqoIhHWh/isz0xpicHTzpKBeotdVsTEcxsSA/i3EVM7gQAj0rU27OLAxCjzlj15IWY7bg==", + "version": "1.0.0-rc.18", + "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-rc.18.tgz", + "integrity": "sha512-CUY5Mnhe64xQBGZEEXQ5WyZwsc1JU3vAZLIxtrsBt3LO6UOb+C8GunVKqe9sT8NeWb4lqSaoJtp2xo6GxT1MNw==", "license": "MIT" }, "node_modules/roughjs": { @@ -8622,15 +8622,15 @@ } }, "node_modules/vite": { - "version": "8.0.10", - "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.10.tgz", - "integrity": "sha512-rZuUu9j6J5uotLDs+cAA4O5H4K1SfPliUlQwqa6YEwSrWDZzP4rhm00oJR5snMewjxF5V/K3D4kctsUTsIU9Mw==", + "version": "8.0.11", + "resolved": "https://registry.npmjs.org/vite/-/vite-8.0.11.tgz", + "integrity": "sha512-Jz1mxtUBR5xTT65VOdJZUUeoyLtqljmFkiUXhPTLZka3RDc9vpi/xXkyrnsdRcm2lIi3l3GPMnAidTsEGIj3Ow==", "license": "MIT", "dependencies": { "lightningcss": "^1.32.0", "picomatch": "^4.0.4", - "postcss": "^8.5.10", - "rolldown": "1.0.0-rc.17", + "postcss": "^8.5.14", + "rolldown": "1.0.0-rc.18", "tinyglobby": "^0.2.16" }, "bin": { @@ -8647,7 +8647,7 @@ }, "peerDependencies": { "@types/node": "^20.19.0 || >=22.12.0", - "@vitejs/devtools": "^0.1.0", + "@vitejs/devtools": "^0.1.18", "esbuild": "^0.27.0 || ^0.28.0", "jiti": ">=1.21.0", "less": "^4.0.0", diff --git a/gitnexus-web/package.json b/gitnexus-web/package.json index 18eb43caf..79d290299 100644 --- a/gitnexus-web/package.json +++ b/gitnexus-web/package.json @@ -70,7 +70,7 @@ "jsdom": "^29.1.1", "tree-sitter-wasms": "^0.1.13", "typescript": "^5.4.5", - "vite": "^8.0.10", + "vite": "^8.0.11", "vitest": "^4.1.5", "wait-on": "^9.0.5" } From 80acaf052f312fde9ca380b38c9f2da9825325b2 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 14 May 2026 06:45:14 +0100 Subject: [PATCH 19/33] chore(deps): bump sigstore/cosign-installer from 4.1.1 to 4.1.2 (#1557) --- .github/workflows/docker.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/docker.yml b/.github/workflows/docker.yml index 93dcf9ce3..0cd526768 100644 --- a/.github/workflows/docker.yml +++ b/.github/workflows/docker.yml @@ -135,7 +135,7 @@ jobs: uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0 - name: Install Cosign - uses: sigstore/cosign-installer@cad07c2e89fa2edd6e2d7bab4c1aa38e53f76003 # v4.1.1 + uses: sigstore/cosign-installer@6f9f17788090df1f26f669e9d70d6ae9567deba6 # v4.1.2 - name: Log in to GitHub Container Registry if: ${{ github.event_name != 'pull_request' && !inputs.dry_run }} From 0566c98b54022bcce54c450543af4bcf7f516b70 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 14 May 2026 07:12:36 +0100 Subject: [PATCH 20/33] chore(deps)(deps): bump @langchain/google-genai in /gitnexus-web (#1554) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Bumps [@langchain/google-genai](https://github.com/langchain-ai/langchainjs) from 2.1.28 to 2.1.30. - [Release notes](https://github.com/langchain-ai/langchainjs/releases) - [Commits](https://github.com/langchain-ai/langchainjs/commits) --- updated-dependencies: - dependency-name: "@langchain/google-genai" dependency-version: 2.1.30 dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Gergő Magyar --- gitnexus-web/package-lock.json | 26 ++++++-------------------- gitnexus-web/package.json | 2 +- 2 files changed, 7 insertions(+), 21 deletions(-) diff --git a/gitnexus-web/package-lock.json b/gitnexus-web/package-lock.json index 91613d2b1..cf69e1083 100644 --- a/gitnexus-web/package-lock.json +++ b/gitnexus-web/package-lock.json @@ -10,7 +10,7 @@ "dependencies": { "@langchain/anthropic": "^1.3.29", "@langchain/core": "^1.1.44", - "@langchain/google-genai": "^2.1.28", + "@langchain/google-genai": "^2.1.30", "@langchain/langgraph": "^1.2.9", "@langchain/ollama": "^1.2.6", "@langchain/openai": "^1.4.5", @@ -1402,32 +1402,18 @@ } }, "node_modules/@langchain/google-genai": { - "version": "2.1.28", - "resolved": "https://registry.npmjs.org/@langchain/google-genai/-/google-genai-2.1.28.tgz", - "integrity": "sha512-iTzNYWST8hTRqOXZdme18tq5GnCUwtrrJECE51ZCjg6Vg0mPsV44amdC+/bc+UK0+uphKWESGWs277aAyM2MlA==", + "version": "2.1.30", + "resolved": "https://registry.npmjs.org/@langchain/google-genai/-/google-genai-2.1.30.tgz", + "integrity": "sha512-0wKgy1NvV89fw5MwYiOOhh18SnUEH20z6MZrPV6Tj2hMAA3jAHVSLlIcCQ2mDRJo2r1aHLV8MDXhzkvD1tEHoQ==", "license": "MIT", "dependencies": { - "@google/generative-ai": "^0.24.0", - "uuid": "^11.1.0" + "@google/generative-ai": "^0.24.0" }, "engines": { "node": ">=20" }, "peerDependencies": { - "@langchain/core": "^1.1.41" - } - }, - "node_modules/@langchain/google-genai/node_modules/uuid": { - "version": "11.1.0", - "resolved": "https://registry.npmjs.org/uuid/-/uuid-11.1.0.tgz", - "integrity": "sha512-0/A9rDy9P7cJ+8w1c9WD9V//9Wj15Ce2MPz8Ri6032usz+NfePxx5AcN3bN+r6ZL6jEo066/yNYB3tn4pQEx+A==", - "funding": [ - "https://github.com/sponsors/broofa", - "https://github.com/sponsors/ctavan" - ], - "license": "MIT", - "bin": { - "uuid": "dist/esm/bin/uuid" + "@langchain/core": "^1.1.43" } }, "node_modules/@langchain/langgraph": { diff --git a/gitnexus-web/package.json b/gitnexus-web/package.json index 79d290299..211bb65c7 100644 --- a/gitnexus-web/package.json +++ b/gitnexus-web/package.json @@ -21,7 +21,7 @@ "gitnexus-shared": "file:../gitnexus-shared", "@langchain/anthropic": "^1.3.29", "@langchain/core": "^1.1.44", - "@langchain/google-genai": "^2.1.28", + "@langchain/google-genai": "^2.1.30", "@langchain/langgraph": "^1.2.9", "@langchain/ollama": "^1.2.6", "@langchain/openai": "^1.4.5", From 6229417bd5d16a52319f52782305bed6832a8bb8 Mon Sep 17 00:00:00 2001 From: Dennis Palatov Date: Wed, 13 May 2026 23:40:15 -0700 Subject: [PATCH 21/33] feat: gitnexus:keep marker preserves custom context sections (resubmit of #605) (#1508) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: gitnexus:keep marker preserves custom context sections When is present inside the gitnexus block, analyze only updates the stats line instead of replacing the entire section with the verbose template. Lets users maintain lean custom context without it being overwritten on every reindex. Co-Authored-By: Claude Opus 4.6 (1M context) * feat: improve gitnexus:keep marker to reliably preserve custom sections The `` marker inside a GitNexus block tells `analyze` to only update the stats line (node/edge/flow counts) while preserving the user's custom layout. This lets teams trim the verbose default template to a lean format without having it overwritten on every reindex. Changes: - Broaden stats-line regex to match both "Indexed as" and "indexed by GitNexus as" formats - Improve stats extraction from generated content (prefer structured match over greedy parentheses) - If keep marker is present but no stats line found, preserve the section as-is instead of falling through to full replace - Add tests for keep preservation and no-keep replacement Co-Authored-By: Claude Opus 4.6 (1M context) * fix: address PR #1508 review findings (F1-F5) Refactor the keep-marker stats-update path and close the test-coverage gaps surfaced by the production-readiness review. ## Findings 2 + 3 (high) — fragile extraction → silent corruption Stop re-extracting `newName` (first `**bold**`) and `newStats` (first `(...)`, with fallback) from generated content. Both are structurally fragile: - F2: newName silently picks the wrong value if the template ever emits bold text before the project-name line (no current bug; an unstated contract with no enforcement) - F3: newStats fallback `\(([^)]+)\)` matches `({target: "symbolName", direction: "upstream"})` from the Always-Do bullet when `noStats: true` suppresses the canonical stats line, silently corrupting the stats output Fix: pass `projectName: string` and `stats: RepoStats` directly into `upsertGitNexusSection`. Build the stats line from those values. Both callers in `generateAIContextFiles` already have them in scope. ## Finding 1 (high) — misleading return value When a keep marker is present but no stats line matches the pattern, the function previously returned `'updated'` without writing, producing `CLAUDE.md (updated)` in CLI output for a file that was not touched. Add a distinct `'preserved'` return variant; CLI now reports `CLAUDE.md (preserved)` honestly. ## Finding 4 (medium) — unanchored stats regex `/(?:Indexed as|...) \*\*[^*]+\*\* \([^)]+\)/` could match prose embedded mid-paragraph in user content (e.g. "you'll see it Indexed as **Foo** (note: ...)"). Anchor with `^...$` plus the `m` flag so only standalone stats lines match. ## Finding 5 — test coverage gaps Seven new tests, each cross-referenced to the review finding: - keep marker OUTSIDE the GitNexus section has no effect - AGENTS.md keep path preserves custom layout (parity with CLAUDE.md) - idempotent: second run produces byte-identical output - CRLF file with keep marker: stats line updates correctly - noStats + keep marker: not corrupted by Always-Do tuple text (F3 regression guard) - returns 'preserved' (not 'updated') when no stats line matches (F1 regression guard) - project name with markdown punctuation (hyphens/slash/dot) lands intact All 23 ai-context tests pass; typecheck, prettier, eslint clean. * docs(ai-context): address PR #1508 review findings on keep-marker path - Clarify that noStats affects generated template only, not keep-section stats updates - Fix stats-line regex comment to match behavior (no end anchor; trailing suffix kept) - Assert '. MCP tools.' survives stats replacement in preserve-custom-section test - Document LF normalization when rewriting CRLF seed in keep-marker CRLF test Co-authored-by: Cursor --------- Co-authored-by: Claude Opus 4.6 (1M context) Co-authored-by: dp-web4 Co-authored-by: Gergő Magyar Co-authored-by: Cursor --- gitnexus/src/cli/ai-context.ts | 53 ++++- gitnexus/test/unit/ai-context.test.ts | 310 +++++++++++++++++++++++++- 2 files changed, 358 insertions(+), 5 deletions(-) diff --git a/gitnexus/src/cli/ai-context.ts b/gitnexus/src/cli/ai-context.ts index 8e18fed7d..42dcb7aa7 100644 --- a/gitnexus/src/cli/ai-context.ts +++ b/gitnexus/src/cli/ai-context.ts @@ -199,7 +199,9 @@ async function fileExists(filePath: string): Promise { async function upsertGitNexusSection( filePath: string, content: string, -): Promise<'created' | 'updated' | 'appended'> { + projectName: string, + stats: RepoStats, +): Promise<'created' | 'updated' | 'appended' | 'preserved'> { const exists = await fileExists(filePath); if (!exists) { @@ -223,7 +225,50 @@ async function upsertGitNexusSection( ); if (startIdx !== -1 && endIdx !== -1 && endIdx > startIdx) { - // Replace existing section + const existingSection = existingContent.substring( + startIdx, + endIdx + GITNEXUS_END_MARKER.length, + ); + + // If the existing section contains , preserve the user's + // custom layout and only update the stats line (node/edge/flow counts). + // This lets teams trim the verbose default template to a lean format without + // having it overwritten on every `gitnexus analyze`. + // + // Note: the keep-marker check operates on `existingSection` (the substring + // between valid section markers identified by findSectionMarkerIndex), so + // a keep marker in user prose OUTSIDE the GitNexus block has no effect. + if (existingSection.includes('')) { + // Build the new stats line from the caller-provided values directly. + // We do NOT re-extract from `content` because: + // (a) first-bold extraction is fragile if the template evolves + // (b) the parenthesized-text fallback can match unrelated tuples + // like `({target: "symbolName", direction: "upstream"})` + // when noStats is set + // Passing projectName + stats explicitly makes the contract obvious. + // noStats controls template generation, not keep-section stat updates — the user opted into a stats line by keeping it. + const newStatsInner = `${stats.nodes || 0} symbols, ${stats.edges || 0} relationships, ${stats.processes || 0} execution flows`; + const statsLine = `Indexed as **${projectName}** (${newStatsInner})`; + + // Match either canonical phrasing at line start (`^` with `m` flag) so we + // cannot replace prose embedded mid-paragraph. Deliberately no `$`: text + // after the closing `)` on the same line (e.g. ". MCP tools.") stays intact. + const statsPattern = /^(?:Indexed as|indexed by GitNexus as) \*\*[^*]+\*\* \([^)]+\)/m; + + if (statsPattern.test(existingSection)) { + const updatedSection = existingSection.replace(statsPattern, statsLine); + const before = existingContent.substring(0, startIdx); + const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length); + await fs.writeFile(filePath, (before + updatedSection + after).trim() + '\n', 'utf-8'); + return 'updated'; + } + // Keep marker present but no stats line matched. Section is preserved + // unchanged on disk; return a distinct status so callers/CLI output + // don't mis-report this as 'updated' (which would imply a write). + return 'preserved'; + } + + // No keep marker — replace existing section with full verbose content const before = existingContent.substring(0, startIdx); const after = existingContent.substring(endIdx + GITNEXUS_END_MARKER.length); const newContent = before + content + after; @@ -344,12 +389,12 @@ export async function generateAIContextFiles( if (!options?.skipAgentsMd) { // Create AGENTS.md (standard for Cursor, Windsurf, OpenCode, Cline, etc.) const agentsPath = path.join(repoPath, 'AGENTS.md'); - const agentsResult = await upsertGitNexusSection(agentsPath, content); + const agentsResult = await upsertGitNexusSection(agentsPath, content, projectName, stats); createdFiles.push(`AGENTS.md (${agentsResult})`); // Create CLAUDE.md (for Claude Code) const claudePath = path.join(repoPath, 'CLAUDE.md'); - const claudeResult = await upsertGitNexusSection(claudePath, content); + const claudeResult = await upsertGitNexusSection(claudePath, content, projectName, stats); createdFiles.push(`CLAUDE.md (${claudeResult})`); } else { createdFiles.push('AGENTS.md (skipped via --skip-agents-md)'); diff --git a/gitnexus/test/unit/ai-context.test.ts b/gitnexus/test/unit/ai-context.test.ts index 71d7ddbdc..13e927637 100644 --- a/gitnexus/test/unit/ai-context.test.ts +++ b/gitnexus/test/unit/ai-context.test.ts @@ -123,9 +123,81 @@ describe('generateAIContextFiles', () => { expect(starts).toBe(1); }); + it('preserves custom section when gitnexus:keep is present', async () => { + const claudeMdPath = path.join(tmpDir, 'CLAUDE.md'); + + // Write a custom lean section with keep marker + const customContent = `# My Project + +Some project docs here. + + + +# GitNexus — Code Knowledge Graph + +Indexed as **TestProject** (50 symbols, 100 relationships, 5 execution flows). MCP tools. + +| Tool | Use for | +|------|---------| +| query | Find flows | + +Resources: gitnexus://repo/TestProject/context + +`; + await fs.writeFile(claudeMdPath, customContent, 'utf-8'); + + // Run analyze with new stats — should only update the stats line + const stats = { nodes: 999, edges: 1234, processes: 42 }; + await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats); + + const result = await fs.readFile(claudeMdPath, 'utf-8'); + + // Stats should be updated + expect(result).toContain('999 symbols'); + expect(result).toContain('1234 relationships'); + expect(result).toContain('42 execution flows'); + expect(result).toContain('. MCP tools.'); + + // Custom layout should be preserved (not replaced with verbose template) + expect(result).toContain(''); + expect(result).toContain('Code Knowledge Graph'); + expect(result).toContain('| query | Find flows |'); + + // Verbose template sections should NOT be present + expect(result).not.toContain('## Always Do'); + expect(result).not.toContain('## Never Do'); + expect(result).not.toContain('## When Debugging'); + + // Non-GitNexus content should be preserved + expect(result).toContain('# My Project'); + expect(result).toContain('Some project docs here.'); + }); + + it('replaces section when no keep marker is present', async () => { + const agentsPath = path.join(tmpDir, 'AGENTS.md'); + + // Write a section WITHOUT keep marker + const content = ` +# GitNexus — Code Intelligence + +Old content here. + +`; + await fs.writeFile(agentsPath, content, 'utf-8'); + + const stats = { nodes: 100, edges: 200, processes: 10 }; + await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats); + + const result = await fs.readFile(agentsPath, 'utf-8'); + + // Should have the full verbose template + expect(result).toContain('## Always Do'); + expect(result).not.toContain('Old content here'); + }); + it('installs skills files', async () => { const stats = { nodes: 10 }; - const result = await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats); + await generateAIContextFiles(tmpDir, storagePath, 'TestProject', stats); // Should have installed skill files const skillsDir = path.join(tmpDir, '.claude', 'skills', 'gitnexus'); @@ -371,4 +443,240 @@ describe('generateAIContextFiles', () => { await fs.rm(crlfDir, { recursive: true, force: true }); } }); + + // ────────────────────────────────────────────────────────────────── + // Keep-marker edge cases (added to address PR #1508 review findings) + // ────────────────────────────────────────────────────────────────── + + it('keep marker OUTSIDE the GitNexus section has no effect (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-scope-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + // Keep marker appears in user prose BEFORE the GitNexus section. + // The keep-path must NOT be triggered — full template replacement + // is the correct behavior here, because the marker is not inside + // the generated block. + const fileWithOutOfBandMarker = `# My Project + +A note about markers: they only apply inside the +GitNexus block below, not in prose like this. + + +Old verbose stub here. + +`; + await fs.writeFile(claudePath, fileWithOutOfBandMarker, 'utf-8'); + + const stats = { nodes: 50, edges: 100, processes: 5 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'TestProject', stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Section MUST have been fully replaced — keep marker outside section ignored + expect(result).toContain('## Always Do'); + expect(result).not.toContain('Old verbose stub here.'); + // User's prose with the marker reference is preserved untouched + expect(result).toContain('A note about markers'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('AGENTS.md keep path preserves custom layout (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-agents-')); + try { + const agentsPath = path.join(dir, 'AGENTS.md'); + const customAgents = `# AGENTS instructions + +Project-specific agent guidance. + + + +# GitNexus context for AGENTS + +Indexed as **AgentsTest** (10 symbols, 20 relationships, 1 execution flows). + +Use 'query' for finding flows, 'context' for symbol details. + +`; + await fs.writeFile(agentsPath, customAgents, 'utf-8'); + + const stats = { nodes: 777, edges: 888, processes: 9 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'AgentsTest', stats); + + const result = await fs.readFile(agentsPath, 'utf-8'); + // Stats updated + expect(result).toContain('777 symbols'); + expect(result).toContain('888 relationships'); + expect(result).toContain('9 execution flows'); + // Custom layout preserved + expect(result).toContain('# GitNexus context for AGENTS'); + expect(result).toContain("Use 'query' for finding flows"); + // Verbose template NOT injected + expect(result).not.toContain('## Always Do'); + // Non-GitNexus content preserved + expect(result).toContain('# AGENTS instructions'); + expect(result).toContain('Project-specific agent guidance.'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('idempotent: second run with keep marker produces byte-identical output (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-idem-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = `# Project + + + +Indexed as **Idem** (1 symbols, 2 relationships, 3 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 99, edges: 100, processes: 7 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'Idem', stats); + const afterFirst = await fs.readFile(claudePath, 'utf-8'); + + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'Idem', stats); + const afterSecond = await fs.readFile(claudePath, 'utf-8'); + + expect(afterSecond).toBe(afterFirst); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('CRLF file with keep marker: stats line updates without corrupting content (#1508 review F5)', async () => { + // upsertGitNexusSection writes with .trim() + '\n', so the saved file uses LF + // line endings throughout — CRLF in the seed input is not preserved. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-crlf-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const crlfContent = + '# Project\r\n' + + '\r\n' + + '\r\n' + + '\r\n' + + 'Indexed as **CRLFTest** (5 symbols, 6 relationships, 7 execution flows). Custom CRLF.\r\n' + + '\r\n'; + await fs.writeFile(claudePath, crlfContent, 'utf-8'); + + const stats = { nodes: 50, edges: 60, processes: 7 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), 'CRLFTest', stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Stats updated correctly + expect(result).toContain('50 symbols'); + expect(result).toContain('60 relationships'); + // Custom prose preserved + expect(result).toContain('Custom CRLF'); + // No verbose template injected + expect(result).not.toContain('## Always Do'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('noStats + keep marker: stats line update is NOT corrupted by Always-Do tuple text (#1508 review F3)', async () => { + // Regression guard: with the old fallback regex `\(([^)]+)\)`, when + // noStats=true suppressed the canonical stats line from generated + // content, the fallback matched the FIRST parenthesized text in the + // template, which was `({target: "symbolName", direction: "upstream"})` + // from the Always Do bullet — silently writing that as the stats line. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-nostats-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = ` + +Indexed as **NoStatsTest** (1 symbols, 1 relationships, 1 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 42, edges: 84, processes: 3 }; + await generateAIContextFiles( + dir, + path.join(dir, '.gitnexus'), + 'NoStatsTest', + stats, + undefined, + { noStats: true }, + ); + + const result = await fs.readFile(claudePath, 'utf-8'); + // Stats line MUST NOT have been corrupted with the Always-Do tuple text + expect(result).not.toMatch(/\(\{target:/); + expect(result).not.toMatch(/direction:\s*"upstream"/); + // Stats line should reflect a sensible numeric update (passed stats) + expect(result).toContain('42 symbols'); + // Custom prose still preserved + expect(result).toContain('Custom.'); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it("returns 'preserved' (not 'updated') when keep marker is present but no stats line matches (#1508 review F1)", async () => { + // Regression guard for the misleading-return-value bug: previously the + // function returned 'updated' without writing when the keep-section had + // no recognizable stats line, causing CLI output to claim files were + // updated when they were not. + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-noline-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + // Custom keep-section with NO "Indexed as ..." or "indexed by GitNexus as ..." line + const seed = `# Project + + + +# GitNexus block (custom, no stats line) + +This block intentionally omits the standard stats line. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + const stats = { nodes: 100, edges: 200, processes: 10 }; + const result = await generateAIContextFiles( + dir, + path.join(dir, '.gitnexus'), + 'NoLineTest', + stats, + ); + + // The result manifest should reflect 'preserved', not 'updated' + expect(result.files).toContain('CLAUDE.md (preserved)'); + // File on disk is unchanged + const onDisk = await fs.readFile(claudePath, 'utf-8'); + expect(onDisk).toBe(seed); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); + + it('project name with markdown-sensitive punctuation lands intact in stats line (#1508 review F5)', async () => { + const dir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-keep-punct-')); + try { + const claudePath = path.join(dir, 'CLAUDE.md'); + const seed = ` + +Indexed as **placeholder** (1 symbols, 1 relationships, 1 execution flows). Custom. + +`; + await fs.writeFile(claudePath, seed, 'utf-8'); + + // Name with hyphens, dot, and slash — exactly what dp-web4/some-repo + // style names look like + const trickyName = 'dp-web4/some-repo.v2'; + const stats = { nodes: 5, edges: 10, processes: 1 }; + await generateAIContextFiles(dir, path.join(dir, '.gitnexus'), trickyName, stats); + + const result = await fs.readFile(claudePath, 'utf-8'); + // The full name appears in the bold of the stats line, intact + expect(result).toContain(`Indexed as **${trickyName}** (5 symbols`); + } finally { + await fs.rm(dir, { recursive: true, force: true }); + } + }); }); From a3eef48ce3ea9aba848ef0eed8c0b11ba77bdd80 Mon Sep 17 00:00:00 2001 From: RezaAlmiro <124073314+RezaAlmiro@users.noreply.github.com> Date: Thu, 14 May 2026 10:26:27 +0300 Subject: [PATCH 22/33] fix(cli): make --no-stats actually omit volatile counts (#1477) (#1478) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(cli): make --no-stats actually omit volatile counts (#1477) Closes #1477. The `--no-stats` flag on `gitnexus analyze` was advertised as "Omit volatile file/symbol counts from AGENTS.md and CLAUDE.md" but had no effect: every reindex still rewrote the markdown with fresh count phrases, producing chore-commit churn on every run — the exact problem the flag was added to solve in #704. Root cause is commander.js negation-flag semantics. `.option( '--no-stats', ...)` registers the option under the accessor `stats` (boolean, default `true`; `false` when the flag is passed), NOT `noStats`. The two action-handler reads in `analyze.ts` (lines 414 and 500 pre-fix) read `options?.noStats`, which is always `undefined`, so the `noStats` payload always reached `runFullAnalysis` / `generateAIContextFiles` as `undefined`/falsy and the count branch in the template always fired. Fixed by replacing `options?.noStats` with `options?.stats === false` at both reads. The strict `=== false` check (rather than `!options?.stats`) means absent options or absent `.stats` field fall through as no-stats=false, preserving the documented default-on behaviour. Also updated the `AnalyzeOptions` interface to declare `stats?: boolean` (matching commander's actual output) with a JSDoc explaining the negation, since the prior `noStats?: boolean` shape was a static-type misrepresentation of what commander provides at runtime. Internal call sites that re-pack `{ noStats: ... }` for downstream consumers (`run-analyze.ts`, `ai-context.ts`) keep their existing field name — those interfaces are not commander- shaped, so `noStats` is the correct name there. ## Regression tests Two new unit tests in `test/unit/ai-context.test.ts`: * `omits volatile counts when noStats option is set (#1477)` — asserts the count parenthetical is absent from both CLAUDE.md and AGENTS.md when `noStats: true` is passed. * `preserves volatile counts when noStats is not set (default)` — documents the default-on path so a future refactor can't silently flip the default. Both call `generateAIContextFiles` directly with distinctive numbers that would unmistakably leak through if the omit branch is broken. ## Manual verification * `vitest run test/unit/ai-context.test.ts` → 13/13 pass (11 prior + 2 new). * Verified before-fix behaviour by checking out main, running `npx gitnexus analyze --no-stats` against an indexed repo, and observing the count phrase still present. Re-running on the fix branch with the same flag strips the phrase as documented. Co-Authored-By: Claude Opus 4.7 (1M context) * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(cli): resolve merge conflict markers in analyze.ts (PR #1478) Remove leftover conflict hunks from main merge; keep commander stats shape (stats?: boolean), wire noStats: options?.stats === false into runFullAnalysis and generateAIContextFiles, and retain indexOnly / skipSkills / skipAgentsMd wiring from main. Co-authored-by: Cursor * test(cli): cover analyzeCommand → runFullAnalysis noStats bridge (#1477) Assert commander-shaped options.stats maps to the internal noStats payload (including explicit true/false and skipAgentsMd combination) so the CLI bridge cannot regress without failing tests. Co-authored-by: Cursor * test(cli): cover AGENTS.md default stats + skills noStats bridge (#1478) - Assert volatile stats phrase in both CLAUDE.md and AGENTS.md when noStats is omitted - Add bridge test for --skills regeneration path with stats:false → generateAIContextFiles noStats - Note shared noStats expression beside skills-path call; stub process.exit for full analyze path Co-authored-by: Cursor --------- Co-authored-by: Claude Opus 4.7 (1M context) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Gergő Magyar Co-authored-by: Cursor --- gitnexus/src/cli/analyze.ts | 29 +++- gitnexus/test/unit/ai-context.test.ts | 48 ++++++ .../test/unit/analyze-no-stats-bridge.test.ts | 140 ++++++++++++++++++ 3 files changed, 213 insertions(+), 4 deletions(-) create mode 100644 gitnexus/test/unit/analyze-no-stats-bridge.test.ts diff --git a/gitnexus/src/cli/analyze.ts b/gitnexus/src/cli/analyze.ts index d5a7638f9..a20503bc4 100644 --- a/gitnexus/src/cli/analyze.ts +++ b/gitnexus/src/cli/analyze.ts @@ -117,8 +117,18 @@ export interface AnalyzeOptions { verbose?: boolean; /** Skip AGENTS.md and CLAUDE.md gitnexus block updates. */ skipAgentsMd?: boolean; - /** Omit volatile symbol/relationship counts from AGENTS.md and CLAUDE.md. */ - noStats?: boolean; + /** + * Stats inclusion in AGENTS.md and CLAUDE.md. + * + * Commander.js represents `--no-stats` as `stats: boolean` (default + * `true`; `false` when the user passes `--no-stats`), NOT as + * `noStats: boolean`. Reading the negated form would always be + * `undefined` and the flag would silently no-op (#1477). Consumers + * that want "did the user request --no-stats?" should compare with + * `=== false` to distinguish the explicit-off case from the + * default-on case. + */ + stats?: boolean; /** Skip installing standard GitNexus skill files to .claude/skills/gitnexus/. */ skipSkills?: boolean; /** Pure index mode: skip all file injection (AGENTS.md, CLAUDE.md, skills). */ @@ -449,7 +459,12 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption skipGit: options?.skipGit, skipAgentsMd, skipSkills, - noStats: options?.noStats, + // commander.js `.option('--no-stats', …)` registers the flag as + // `options.stats` (boolean, default true; `false` when the user + // passed --no-stats). Reading `options?.noStats` here returns + // undefined every time, so the flag was a no-op on the markdown + // rewrite path before this fix. See #1477. + noStats: options?.stats === false, registryName: options?.name, // Registry-collision bypass — its own CLI flag, intentionally NOT // overloading --force. A user who hits the collision guard should @@ -537,7 +552,13 @@ export const analyzeCommand = async (inputPath?: string, options?: AnalyzeOption processes: s.processes, }, skillResult.skills, - { skipAgentsMd, skipSkills, noStats: options?.noStats }, + { + skipAgentsMd, + skipSkills, + // Mirror runFullAnalysis `noStats` bridge (#1477) — same expression; + // exercised on the `--skills` path by analyze-no-stats-bridge.test.ts. + noStats: options?.stats === false, + }, ); } } catch { diff --git a/gitnexus/test/unit/ai-context.test.ts b/gitnexus/test/unit/ai-context.test.ts index 13e927637..68dee21dd 100644 --- a/gitnexus/test/unit/ai-context.test.ts +++ b/gitnexus/test/unit/ai-context.test.ts @@ -45,6 +45,54 @@ describe('generateAIContextFiles', () => { expect(content).toContain('TestProject'); }); + it('omits volatile counts when noStats option is set (#1477)', async () => { + // Distinct subdir per case so we can assert on a clean slate. + const subDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-no-stats-test-')); + const subStorage = path.join(subDir, '.gitnexus'); + await fs.mkdir(subStorage, { recursive: true }); + try { + // Stats values picked to be unmistakable if they leak through. + const stats = { nodes: 12345, edges: 67890, processes: 99 }; + await generateAIContextFiles(subDir, subStorage, 'NoStatsProject', stats, undefined, { + noStats: true, + }); + + for (const f of ['CLAUDE.md', 'AGENTS.md']) { + const content = await fs.readFile(path.join(subDir, f), 'utf-8'); + expect(content).toContain('NoStatsProject'); + // The "(N symbols, N relationships, N execution flows)" + // phrase MUST NOT appear when noStats=true. + expect(content).not.toMatch( + /\(\d+\s+symbols,\s+\d+\s+relationships,\s+\d+\s+execution flows\)/, + ); + // And the distinctive numbers must not leak via any other path. + expect(content).not.toContain('12345'); + expect(content).not.toContain('67890'); + } + } finally { + await fs.rm(subDir, { recursive: true, force: true }); + } + }); + + it('preserves volatile counts when noStats is not set (default)', async () => { + const subDir = await fs.mkdtemp(path.join(os.tmpdir(), 'gn-with-stats-test-')); + const subStorage = path.join(subDir, '.gitnexus'); + await fs.mkdir(subStorage, { recursive: true }); + try { + const stats = { nodes: 12345, edges: 67890, processes: 99 }; + await generateAIContextFiles(subDir, subStorage, 'WithStatsProject', stats); + for (const f of ['CLAUDE.md', 'AGENTS.md']) { + const content = await fs.readFile(path.join(subDir, f), 'utf-8'); + expect(content).toContain('WithStatsProject'); + expect(content).toMatch( + /\(12345\s+symbols,\s+67890\s+relationships,\s+99\s+execution flows\)/, + ); + } + } finally { + await fs.rm(subDir, { recursive: true, force: true }); + } + }); + it('keeps the load-bearing repo-specific sections in the CLAUDE.md block (#856)', async () => { // The trimmed block must still contain everything that is genuinely // unique per repo or load-bearing for the agent: the freshness warning, diff --git a/gitnexus/test/unit/analyze-no-stats-bridge.test.ts b/gitnexus/test/unit/analyze-no-stats-bridge.test.ts new file mode 100644 index 000000000..f941141ef --- /dev/null +++ b/gitnexus/test/unit/analyze-no-stats-bridge.test.ts @@ -0,0 +1,140 @@ +import { beforeEach, describe, expect, it, vi } from 'vitest'; + +const { runFullAnalysisMock, generateAIContextFilesMock, generateSkillFilesMock } = vi.hoisted( + () => { + const runFullAnalysisMock = vi.fn(); + const generateAIContextFilesMock = vi.fn(async () => ({ files: [] as string[] })); + const generateSkillFilesMock = vi.fn(async () => ({ + skills: [{ name: 'c', label: 'Community', symbolCount: 1, fileCount: 1 }], + outputPath: '/repo/.claude/skills/generated', + })); + return { runFullAnalysisMock, generateAIContextFilesMock, generateSkillFilesMock }; + }, +); + +vi.mock('../../src/core/run-analyze.js', () => ({ + runFullAnalysis: runFullAnalysisMock, +})); + +vi.mock('../../src/cli/ai-context.js', () => ({ + generateAIContextFiles: generateAIContextFilesMock, +})); + +vi.mock('../../src/cli/skill-gen.js', () => ({ + generateSkillFiles: generateSkillFilesMock, +})); + +vi.mock('../../src/core/lbug/lbug-adapter.js', () => ({ + closeLbug: vi.fn(async () => undefined), +})); + +vi.mock('../../src/storage/repo-manager.js', () => ({ + getStoragePaths: vi.fn(() => ({ storagePath: '.gitnexus', lbugPath: '.gitnexus/lbug' })), + getGlobalRegistryPath: vi.fn(() => 'registry.json'), + RegistryNameCollisionError: class RegistryNameCollisionError extends Error {}, + AnalysisNotFinalizedError: class AnalysisNotFinalizedError extends Error {}, + assertAnalysisFinalized: vi.fn(async () => undefined), +})); + +vi.mock('../../src/storage/git.js', () => ({ + getGitRoot: vi.fn(() => '/repo'), + hasGitDir: vi.fn(() => true), +})); + +vi.mock('../../src/core/ingestion/utils/max-file-size.js', () => ({ + getMaxFileSizeBannerMessage: vi.fn(() => null), +})); + +describe('analyzeCommand commander → runFullAnalysis noStats bridge (#1477)', () => { + beforeEach(() => { + vi.resetModules(); + runFullAnalysisMock.mockReset(); + runFullAnalysisMock.mockResolvedValue({ + repoName: 'repo', + repoPath: '/repo', + stats: {}, + alreadyUpToDate: true, + }); + generateAIContextFilesMock.mockReset(); + generateAIContextFilesMock.mockResolvedValue({ files: [] }); + generateSkillFilesMock.mockReset(); + generateSkillFilesMock.mockResolvedValue({ + skills: [{ name: 'c', label: 'Community', symbolCount: 1, fileCount: 1 }], + outputPath: '/repo/.claude/skills/generated', + }); + process.exitCode = undefined; + process.env.NODE_OPTIONS = `${process.env.NODE_OPTIONS ?? ''} --max-old-space-size=8192`.trim(); + }); + + it('maps commander-shaped stats:false to noStats:true (equivalent to --no-stats)', async () => { + const { analyzeCommand } = await import('../../src/cli/analyze.js'); + + await analyzeCommand(undefined, { stats: false }); + + expect(runFullAnalysisMock).toHaveBeenCalledTimes(1); + const opts = runFullAnalysisMock.mock.calls[0][1]; + expect(opts.noStats).toBe(true); + }); + + it('maps omitted stats to noStats:false (default-on preserved)', async () => { + const { analyzeCommand } = await import('../../src/cli/analyze.js'); + + await analyzeCommand(undefined, {}); + + const opts = runFullAnalysisMock.mock.calls[0][1]; + expect(opts.noStats).toBe(false); + }); + + it('maps explicit stats:true to noStats:false', async () => { + const { analyzeCommand } = await import('../../src/cli/analyze.js'); + + await analyzeCommand(undefined, { stats: true }); + + const opts = runFullAnalysisMock.mock.calls[0][1]; + expect(opts.noStats).toBe(false); + }); + + it('still maps stats:false to noStats:true when skipAgentsMd is set', async () => { + const { analyzeCommand } = await import('../../src/cli/analyze.js'); + + await analyzeCommand(undefined, { stats: false, skipAgentsMd: true }); + + const opts = runFullAnalysisMock.mock.calls[0][1]; + expect(opts.noStats).toBe(true); + expect(opts.skipAgentsMd).toBe(true); + }); + + it('passes stats:false as noStats to generateAIContextFiles on the --skills regeneration path (#1477)', async () => { + runFullAnalysisMock.mockResolvedValueOnce({ + repoName: 'repo', + repoPath: '/repo', + stats: { + files: 1, + nodes: 10, + edges: 20, + communities: 0, + processes: 5, + }, + alreadyUpToDate: false, + pipelineResult: { communityResult: undefined }, + }); + + const exitSpy = vi.spyOn(process, 'exit').mockImplementation(() => undefined as never); + try { + const { analyzeCommand } = await import('../../src/cli/analyze.js'); + + await analyzeCommand(undefined, { skills: true, stats: false }); + + expect(generateSkillFilesMock).toHaveBeenCalledTimes(1); + expect(generateAIContextFilesMock).toHaveBeenCalledTimes(1); + const aiCtxOpts = generateAIContextFilesMock.mock.calls[0]![5]; + expect(aiCtxOpts).toEqual({ + skipAgentsMd: undefined, + skipSkills: undefined, + noStats: true, + }); + } finally { + exitSpy.mockRestore(); + } + }); +}); From e9349ce66aa65d45b92ab0dcca12ec0804970ca8 Mon Sep 17 00:00:00 2001 From: Ash Gupta Date: Thu, 14 May 2026 00:58:58 -0700 Subject: [PATCH 23/33] fix(markdown): handle CRLF line endings in section heading parser (#1469) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(markdown): handle CRLF line endings in section heading parser split('\n') on CRLF content leaves a trailing \r on each line, and the heading regex /^(#{1,6})\s+(.+)$/ (anchored with $) fails to match '## Heading\r' because $ matches before end-of-string, not before \r. Result: Windows-authored markdown silently produces zero Section nodes. Use split(/\r\n|\r|\n/) to normalize all line-ending conventions. Pure additive — LF-only files produce identical output. CR-only (Mac OS Classic) becomes tolerated as a side benefit at zero risk. Adds integration test markdown-processor-crlf.test.ts covering LF baseline, CRLF (the regression), CR-only, mixed, and startLine/endLine correctness. * test(markdown): strengthen CRLF integration tests + clarify split comment - Assert section names, levels, line spans, and CONTAINS hierarchy (not only counts) - Document trailing-newline effect on endLine via exact toEqual expectations - Reword markdown-processor comment: \$ only at end-of-string vs .+ before \\r Co-authored-by: Cursor * chore: empty commit Co-authored-by: Cursor --------- Co-authored-by: Gergő Magyar Co-authored-by: Cursor --- .../src/core/ingestion/markdown-processor.ts | 7 +- .../markdown-processor-crlf.test.ts | 158 ++++++++++++++++++ 2 files changed, 164 insertions(+), 1 deletion(-) create mode 100644 gitnexus/test/integration/markdown-processor-crlf.test.ts diff --git a/gitnexus/src/core/ingestion/markdown-processor.ts b/gitnexus/src/core/ingestion/markdown-processor.ts index dc0e7fee4..b2013ee7a 100644 --- a/gitnexus/src/core/ingestion/markdown-processor.ts +++ b/gitnexus/src/core/ingestion/markdown-processor.ts @@ -36,7 +36,12 @@ export const processMarkdown = ( // Skip if file node doesn't exist (shouldn't happen, structure-processor creates it) if (!graph.getNode(fileNodeId)) continue; - const lines = file.content.split('\n'); + // Normalize CRLF/CR to LF before splitting so that line-end agnostic + // markdown files (Windows-authored, mixed) yield correct headings. + // Without this, splitting on `\n` alone leaves `## Heading\r` on each line; + // `$` in HEADING_RE only matches at end-of-string, while `.+` stops before + // the trailing `\r`, so the line never matches as a heading. + const lines = file.content.split(/\r\n|\r|\n/); // --- Extract headings and build hierarchy --- // First pass: collect all heading positions so we can compute endLine spans diff --git a/gitnexus/test/integration/markdown-processor-crlf.test.ts b/gitnexus/test/integration/markdown-processor-crlf.test.ts new file mode 100644 index 000000000..7a3e91a95 --- /dev/null +++ b/gitnexus/test/integration/markdown-processor-crlf.test.ts @@ -0,0 +1,158 @@ +/** + * Regression test for CRLF-encoded markdown heading extraction. + * + * Files with CRLF line endings (Windows-authored markdown) previously + * produced zero Section nodes because `split('\n')` left a trailing `\r` + * on each line, and the heading regex `/^(#{1,6})\s+(.+)$/` (anchored + * with `$`) failed to match `## Heading\r` because `$` only matches at + * end-of-string while `.+` does not consume the trailing `\r`. + * + * Fix: split on `/\r\n|\r|\n/` so all line-ending conventions are + * normalized at split time. See markdown-processor.ts line 39. + */ + +import { describe, it, expect } from 'vitest'; +import { processMarkdown } from '../../src/core/ingestion/markdown-processor.js'; +import { createKnowledgeGraph } from '../../src/core/graph/graph.js'; +import { generateId } from '../../src/lib/utils.js'; +import type { GraphNode } from 'gitnexus-shared'; +import type { KnowledgeGraph } from '../../src/core/graph/types.js'; + +function getMarkdownSections(graph: KnowledgeGraph, filePath: string): GraphNode[] { + return [...graph.iterNodes()] + .filter((n) => n.label === 'Section' && n.properties.filePath === filePath) + .sort( + (a, b) => + ((a.properties.startLine as number | undefined) ?? 0) - + ((b.properties.startLine as number | undefined) ?? 0), + ); +} + +function expectContainsEdge(graph: KnowledgeGraph, sourceId: string, targetId: string) { + const found = [...graph.iterRelationshipsByType('CONTAINS')].some( + (r) => r.sourceId === sourceId && r.targetId === targetId, + ); + expect(found).toBe(true); +} + +function setupGraphWithFile(filePath: string) { + const graph = createKnowledgeGraph(); + const fileNode: GraphNode = { + id: generateId('File', filePath), + label: 'File', + properties: { name: filePath, filePath }, + }; + graph.addNode(fileNode); + return graph; +} + +describe('markdown-processor CRLF tolerance', () => { + it('extracts headings from LF-encoded markdown (baseline)', () => { + const filePath = 'lf.md'; + const graph = setupGraphWithFile(filePath); + const content = '# Title\nbody line 1\n## Sub\nbody line 2\n### SubSub\nmore\n'; + + const stats = processMarkdown(graph, [{ path: filePath, content }], new Set([filePath])); + + expect(stats.sections).toBe(3); + const sections = getMarkdownSections(graph, filePath); + expect(sections.map((s) => s.properties.name)).toEqual(['Title', 'Sub', 'SubSub']); + expect(sections.map((s) => s.properties.level)).toEqual([1, 2, 3]); + expect(sections.map((s) => s.properties.startLine)).toEqual([1, 3, 5]); + expect(sections.map((s) => s.properties.endLine)).toEqual([7, 7, 7]); + for (const s of sections) { + expect(String(s.properties.name)).not.toMatch(/\r/); + } + const fileId = generateId('File', filePath); + expectContainsEdge(graph, fileId, sections[0]!.id); + expectContainsEdge(graph, sections[0]!.id, sections[1]!.id); + expectContainsEdge(graph, sections[1]!.id, sections[2]!.id); + }); + + it('extracts headings from CRLF-encoded markdown (the regression)', () => { + const filePath = 'crlf.md'; + const graph = setupGraphWithFile(filePath); + const content = '# Title\r\nbody line 1\r\n## Sub\r\nbody line 2\r\n### SubSub\r\nmore\r\n'; + + const stats = processMarkdown(graph, [{ path: filePath, content }], new Set([filePath])); + + // Pre-fix: this returned 0 because `## Sub\r` failed the heading regex. + expect(stats.sections).toBe(3); + const sections = getMarkdownSections(graph, filePath); + expect(sections.map((s) => s.properties.name)).toEqual(['Title', 'Sub', 'SubSub']); + expect(sections.map((s) => s.properties.level)).toEqual([1, 2, 3]); + expect(sections.map((s) => s.properties.startLine)).toEqual([1, 3, 5]); + expect(sections.map((s) => s.properties.endLine)).toEqual([7, 7, 7]); + for (const s of sections) { + expect(String(s.properties.name)).not.toMatch(/\r/); + } + const fileId = generateId('File', filePath); + expectContainsEdge(graph, fileId, sections[0]!.id); + expectContainsEdge(graph, sections[0]!.id, sections[1]!.id); + expectContainsEdge(graph, sections[1]!.id, sections[2]!.id); + }); + + it('extracts headings from CR-only-encoded markdown (old Mac OS Classic)', () => { + const filePath = 'cr.md'; + const graph = setupGraphWithFile(filePath); + const content = '# Title\rbody line 1\r## Sub\rbody line 2\r'; + + const stats = processMarkdown(graph, [{ path: filePath, content }], new Set([filePath])); + + expect(stats.sections).toBe(2); + const sections = getMarkdownSections(graph, filePath); + expect(sections.map((s) => s.properties.name)).toEqual(['Title', 'Sub']); + expect(sections.map((s) => s.properties.level)).toEqual([1, 2]); + expect(sections.map((s) => s.properties.startLine)).toEqual([1, 3]); + expect(sections.map((s) => s.properties.endLine)).toEqual([5, 5]); + for (const s of sections) { + expect(String(s.properties.name)).not.toMatch(/\r/); + } + const fileId = generateId('File', filePath); + expectContainsEdge(graph, fileId, sections[0]!.id); + expectContainsEdge(graph, sections[0]!.id, sections[1]!.id); + }); + + it('extracts headings from mixed CRLF + LF markdown', () => { + const filePath = 'mixed.md'; + const graph = setupGraphWithFile(filePath); + const content = '# LF Title\nbody\r\n## CRLF Sub\r\nmore\n### Trailing LF\nend\n'; + + const stats = processMarkdown(graph, [{ path: filePath, content }], new Set([filePath])); + + expect(stats.sections).toBe(3); + const sections = getMarkdownSections(graph, filePath); + expect(sections.map((s) => s.properties.name)).toEqual(['LF Title', 'CRLF Sub', 'Trailing LF']); + expect(sections.map((s) => s.properties.level)).toEqual([1, 2, 3]); + expect(sections.map((s) => s.properties.startLine)).toEqual([1, 3, 5]); + expect(sections.map((s) => s.properties.endLine)).toEqual([7, 7, 7]); + for (const s of sections) { + expect(String(s.properties.name)).not.toMatch(/\r/); + } + const fileId = generateId('File', filePath); + expectContainsEdge(graph, fileId, sections[0]!.id); + expectContainsEdge(graph, sections[0]!.id, sections[1]!.id); + expectContainsEdge(graph, sections[1]!.id, sections[2]!.id); + }); + + it('reports correct startLine and endLine for CRLF content', () => { + const filePath = 'crlf-lines.md'; + const graph = setupGraphWithFile(filePath); + // Lines 1, 3, 5 are headings (1-indexed) + const content = '# T\r\nbody\r\n## Sub\r\nmore\r\n### SubSub\r\ntail\r\n'; + + processMarkdown(graph, [{ path: filePath, content }], new Set([filePath])); + + const sections = getMarkdownSections(graph, filePath); + const titleSection = sections.find((s) => s.properties.name === 'T'); + const subSection = sections.find((s) => s.properties.name === 'Sub'); + const subSubSection = sections.find((s) => s.properties.name === 'SubSub'); + + expect(titleSection?.properties.startLine).toBe(1); + expect(titleSection?.properties.endLine).toBe(7); + expect(subSection?.properties.startLine).toBe(3); + expect(subSection?.properties.endLine).toBe(7); + expect(subSubSection?.properties.startLine).toBe(5); + expect(subSubSection?.properties.endLine).toBe(7); + }); +}); From e01f0912bcc0381c6ca3e7a78e90a4dc8bbfd16d Mon Sep 17 00:00:00 2001 From: WENJIE HUANG <82434538+SZU-WenjieHuang@users.noreply.github.com> Date: Thu, 14 May 2026 16:30:52 +0800 Subject: [PATCH 24/33] feat(cpp): migrate C++ to scope-based resolution model (#938) (#1520) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(cpp): complete scope-resolution parity * fix(ci): resolve formatting, lint errors for PR #1520 - prettier: format arity-metadata.ts, captures.ts, index.ts - eslint: rename unused HEADER_GLOB to _HEADER_GLOB - eslint: replace unsafe parser.parse() with parseSourceSafe() - eslint: suppress intentional console.warn/log in sync.ts - eslint: remove unused _it import alias in cpp.test.ts * fix(ci): complete formatting, lint, and typecheck fixes - prettier: format call-processor.ts, imported-return-types.ts, include-extractor.test.ts, cpp-captures.test.ts, cpp-imports.test.ts - eslint: suppress intentional console.warn in manifest-extractor.ts - typecheck: restore 'thrift' in ContractType union (was accidentally removed) and add thrift case to exhaustive switch in manifest-extractor * fix(ci): revert unintended group module changes that broke tests Restore types.ts, config-parser.ts, matching.ts, sync.ts, and manifest-extractor.ts to upstream/main versions. The original commit accidentally removed fields (thrift, workspace_deps, exclude_links_paths, exclude_links_param_only_paths) from DetectConfig/MatchingConfig/ContractType which are still referenced by matching.test.ts, config-parser.test.ts, sync.test.ts and other integration tests. This PR's scope is C++ scope-resolution parity only — group module type definitions and logic should remain unchanged. * fix(codeql): address security and quality alerts - arity-metadata.ts, interpret.ts: replace single-pass template strip regex (/<[^>]*>/g) with a while-loop to fully handle nested templates like Map> — resolves 'Incomplete multi-character sanitization' - cpp.test.ts: remove unused vitest 'it' import since the file defines its own 'it' via createResolverParityIt — resolves 'Assignment to constant' - include-extractor.test.ts: use fs.mkdtempSync() instead of predictable os.tmpdir()+Date.now() paths — resolves 'Insecure temporary file' - interpret.ts: remove redundant 'name !== undefined' check (already guaranteed by early return) — resolves 'Comparison between inconvertible types' * review: address Claude review findings on PR #1520 - Findings 1-3 (BLOCKERS): restore include-extractor.ts and its test to the main baseline. Block-comment fallback regression, suffix-resolve false-positive suppression, and the four deleted regression tests (#3-#6) are now back. These changes were unrelated to C++ scope parity and should not have been in this PR. - Finding 4 (MAJOR, partial): revert COMPOUND_RECEIVER_MAX_DEPTH 6 to 4. No C++ test exercises depth > 4 (cpp-chain-call uses a 2-hop chain), so the bump risked silent regressions on other migrated languages without justification. The wildcard-origin propagation in imported-return-types.ts is retained — C++ #include and using namespace both emit wildcard-origin bindings (cpp/import-decomposer .ts:40,90), so wildcard propagation is causal to C++ parity. - Finding 6: tighten write-access dedup test with exact per-field counts (nameWrites = 2, addrWrites = 1) instead of total-count + sub string containment, so a regression in one of the two name writes can no longer be masked. - Finding 8: skipped. Box-drawing characters in cpp/query.ts comments match the established convention used in csharp/java/php query files. Finding 5 (int/long normalization tie-breaker) left as documented follow-up — proper fix requires resolver-level tie-breaker logic and risks regressing other arity-matching tests. * fix(cpp): stop #include from leaking class methods and namespace members (U1) The C++ registry-primary resolver was emitting impossible CALLS edges for ordinary headers: an including file's unqualified save() resolved to User::save and unqualified foo() resolved to ns::foo. Two leak paths converged on localDefs: 1. expandCppWildcardNames (file-local-linkage.ts) iterated the flattened localDefs and exported every simple tail, including class-owned methods and namespace-contained symbols. Replaced with a scope-aware filter: build nodeId -> owning Scope from Scope.ownedDefs and skip defs whose owning scope is Namespace or Class. 2. The shared global free-call fallback's pickUniqueGlobalCallable walks the workspace registry by simple name and would still hit class methods / namespace members even with wildcard expansion fixed. Plugged the gap via the existing isFileLocalDef hook — semantically 'logically invisible cross-file' — by tracking per- file non-globally-visible nodeIds (populateCppNonGloballyVisible, called from populateOwners) and adding an ownerId !== undefined fast-path for class-owned defs. Side fix in shared finalize-algorithm.ts: when wildcard expansion resolves to a real target but produces zero propagating names, the edge was dropped, taking the file-level IMPORTS edge with it. Preserve the original wildcard edge so #include dependencies survive even when the header exposes no unqualified bindings. Tests: cpp-include-no-class-leak, cpp-include-no-namespace-leak, and cpp-anon-ns-same-file-visible fixtures. Negative tests mode-gated to REGISTRY_PRIMARY_CPP=1 via the expected-failures registry — legacy DAG has no scope-aware filtering on the global fallback; backporting is out of scope. All 2104 resolver integration tests pass under registry-primary mode. * fix(cpp): suppress receiver-bound CALLS when integer-width overloads collide (U2) C++ arity-metadata normalizes int, long, short, unsigned, size_t to 'int' so single-candidate flows like 'process(42L)' match a 'long'- typed parameter via loose matching. But when both 'process(int)' and 'process(long)' coexist as method overloads, they both end up with parameterTypes=['int'] in the registry, and pickOverload's narrowing returns 2 candidates with no way to disambiguate. The previous code picked candidates[0] arbitrarily, emitting a CALLS edge to the wrong overload roughly half the time. Fix: - Add isOverloadAmbiguousAfterNormalization in overload-narrowing.ts that detects >1 candidate sharing identical parameterTypes sequences. - Have pickOverload return a new OVERLOAD_AMBIGUOUS sentinel when this fires. - In the receiver-bound-calls loop, when pickOverload signals ambiguity, suppress the edge AND add the site to handledSites so the late-stage emitReferencesViaLookup pass does not re-emit the pre-resolved reference. Without the handled-mark, the reference index still carries a toDef and emits the same wrong edge. Graph schema has no ambiguous-target edge model, so emitting two edges (one per candidate) would require a separate schema change. Zero-edge is the only safe outcome. Other languages: the ambiguity check is a precondition gate, not a behavior change for normal narrowing. Languages whose normalizers do not collapse distinct types into a single token (verified by grep over *-arity-metadata.ts) will never produce >1 candidate with identical parameterTypes from genuinely distinct declarations, so the branch is effectively C++-only in practice. Test: cpp-overload-int-long fixture asserts exactly .toBe(0) CALLS edges. Count=1 = arbitrary pick (the bug); count>1 = unsupported ambiguous-edge model. Mode-gated to REGISTRY_PRIMARY_CPP=1 — legacy DAG has no OVERLOAD_AMBIGUOUS wiring; backporting is out of scope. All 2105 resolver integration tests pass under registry-primary; all 139 cpp tests pass under both modes (3 negative tests skipped in legacy as documented). * test(cpp): add integration coverage for anonymous-namespace, using-namespace conflict, and std-shim leakage (U3+U4+U5) Three new end-to-end fixtures exercise the resolver pipeline against scenarios that previously had only unit-level coverage or no coverage at all (Claude review Finding 7): U3 — cpp-anon-ns-cross-file: helper.cpp declares 'namespace { void worker(); }' and calls it internally. caller.cpp declares a separate 'void worker()' and calls it. Asserts (a) the cross-file CALLS edge from caller's run() does not target helper.cpp's anonymous-namespace worker, and (b) the same-file edge from helper_entry() to its own worker still resolves (positive guard against a 'no edges at all' regression making the negative check vacuously pass). Includes a state-isolation guard that re-runs the same fixture and asserts identical results, proving clearFileLocalNames() is called by the pipeline entry. U4 — cpp-using-namespace-conflict: Two headers each declaring 'namespace a { foo() }' and 'namespace b { foo() }' respectively, plus a caller doing 'using namespace a; using namespace b; foo()'. Asserts exactly zero CALLS edges. One edge = arbitrary pick (the bug); two edges would require an ambiguous-target edge model GitNexus does not have. Depends on U1 — without scope-aware filtering, both foo()s would already be in the importer's wildcard binding set as simple 'foo', so the test would pass for the wrong reason. U5 — cpp-using-namespace-std-smoke: Fixture-local 'namespace std { void cout_write(); void println(); }' shim rather than real — captures the wildcard-leak shape deterministically without depending on system-header modeling stability (out of scope per plan). Asserts (a) the project-local call resolves correctly, (b) no leak to shim STL symbols, and (c) no CALLS/ACCESSES edges from the caller into std-shim.h at all. Negative tests for U2/U4 mode-gated to REGISTRY_PRIMARY_CPP=1 via the expected-failures registry; legacy DAG lacks the OVERLOAD_AMBIGUOUS suppression and the namespace-aware filtering, so the leaks persist there. All 2112 resolver integration tests pass under registry-primary; all 146 cpp tests pass under both modes (4 negative tests skipped in legacy as documented). * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(cpp): scope-aware isSuperReceiver classification (U1) The C++ isSuperReceiver hook used a regex `/^[A-Z]\w*::/` that misclassified any uppercase-qualified call as a super-receiver call. Singleton::getInstance(), std::Foo::bar(), and PascalCase namespace calls all entered the super branch, where the absence of an enclosing class (or wrong MRO context) dropped the resolution entirely. Fix: - New optional ScopeResolver hook isSuperReceiverInContext(text, callerScope, scopes). Languages where super classification depends on caller context define it; receiver-bound-calls.ts prefers it when defined and falls back to the simple isSuperReceiver(text) otherwise. Other migrated languages (Python, Java, C#, PHP, Go, TypeScript) are unchanged. - C++ implementation: parse the LHS of '::' from the receiver text, resolve via findClassBindingInScope, and return true only when the LHS is a class-like def in the caller's enclosing class's MRO. Returns false for namespace LHS, unresolved LHS, self-class LHS (qualified self-calls aren't super), and any non-'::' form. - Extended the C++ tree-sitter query to capture the LHS of qualified_identifier as @reference.receiver so qualified static member calls (Singleton::getInstance()) reach the receiver-bound Case 2 (class-name receiver) path. Without the receiver capture, qualified calls had no explicit receiver and could not resolve through any receiver-bound branch. Test: cpp-namespace-qualified-not-super fixture. Singleton::getInstance() from a free function asserts exactly 1 CALLS edge through the qualified-call path. Passes under both REGISTRY_PRIMARY_CPP=1 and =0. All 2113 resolver integration tests pass; all 147 cpp tests pass under both modes. * fix(cpp): suppress receiver-bound CALLS when default-arg overloads collide (U4) ISO C++ rejects 's.f(1)' as ambiguous when both 'void f(int)' and 'void f(int, int = 0)' are declared on S. The previous resolver returned the first viable candidate via pickOverload's fallback. Extended isOverloadAmbiguousAfterNormalization to take an optional argCount: when provided, the predicate compares only the first argCount slots of each candidate's parameterTypes. Candidates whose declared-prefix matches up to argCount are treated as ambiguous because default arguments make all of them equally viable for the call. Without argCount, behavior is unchanged (the original int/long normalization-collapse contract, full-length equality required). pickOverload now passes site.arity so default-arg ambiguity fires. Test: cpp-overload-default-arg-ambiguous fixture. s.f(1) where S has f(int) and f(int, int = 0) asserts exactly .toBe(0) CALLS edges. Passes under both REGISTRY_PRIMARY_CPP=1 and =0. All 2114 resolver integration tests pass; all 148 cpp tests pass under both modes. * fix(cpp): two-phase template lookup suppresses dependent-base members (U3) ISO C++ two-phase name lookup: inside a class template body, unqualified calls MUST NOT bind to members of a dependent base class. Only this->name or Base::name forms make the lookup dependent. GCC and Clang both reject the unqualified form with 'declaration of f must be available'. Before this fix, GitNexus's global free-call fallback walked the workspace registry by simple name and bound unqualified calls inside template bodies to dependent-base members, producing CALLS edges the compiler would reject. Implementation: - New languages/cpp/two-phase-lookup.ts module: per-pipeline state recording (className, dependentBaseName) pairs at capture time and resolving them to nodeId sets during populateOwners. - captures.ts detectCppDependentBases walks the AST once finding every template_declaration containing a class/struct definition. For each, it collects template-parameter names (typename T, class T, non-type int N, template-template parameters) and walks each base in the base_class_clause checking whether any inner type_identifier matches a template parameter. Conservative bias: typename T::U, decltype, and template-template-parameter shapes also classified as dependent. - Extended scope-resolution contract's isCallableVisibleFromCaller hook with optional callerScope and scopes fields. C++ implements the hook to consult isCppDependentBaseMember: when the candidate is a member of a dependent base of the caller's enclosing class, the hook returns false and pickUniqueGlobalCallable skips the candidate. - clearFileLocalNames also clears the dependent-base state per pipeline run. Fixtures: - cpp-two-phase-dependent-base: Derived deriving from Base, unqualified f() and i inside Derived's body. Asserts zero CALLS edges and zero ACCESSES edges respectively. - cpp-two-phase-this-qualified, cpp-two-phase-non-dependent-base, cpp-two-phase-namespace-free-call-inside-template: positive fixtures left as documented gaps (this-> and qualified-name resolution inside template bodies are pre-existing resolver weaknesses independent of U3). Tracked separately. Negative test mode-gated to REGISTRY_PRIMARY_CPP=1 via the expected- failures registry; legacy DAG has no two-phase lookup. All 2116 resolver integration tests pass under registry-primary; all 150 cpp tests pass under both modes (5 negative tests skipped in legacy as documented). * fix(cpp): implement V1 ADL (Koenig lookup) for free-function calls (U2) Plan 2026-05-13-001 U2. Adds argument-dependent lookup as a new candidate-generating tier in `emitFreeCallFallback`: when ordinary unqualified lookup is empty, ADL surfaces candidates from each value-class-typed argument's enclosing namespace. V1 boundary (locked by cpp-adl-pointer-arg-boundary fixture): - only direct enclosing-namespace closure - only directly-named class-type values (pointer / reference / template- spec args excluded; closure rules deferred to V2) - ADL fires ONLY when ordinary lookup is empty (no union-and-resolve) Parenthesized name `(f)(s)` suppresses ADL per ISO C++ [basic.lookup.argdep]/3.1. Multi-candidate ambiguity (e.g. `process(int)` vs `process(long)` after C++ int-width normalization) returns the ADL_AMBIGUOUS sentinel — caller suppresses entirely, mirroring the OVERLOAD_AMBIGUOUS contract from plan 2026-05-12-002 U2. Implementation: - `cpp/adl.ts` — new module: per-pipeline argInfoBySite + noAdlSites Maps populated at capture time, classToNamespaceQualifiedName Map populated during populateOwners; `pickCppAdlCandidates` returns SymbolDefinition | ADL_AMBIGUOUS | undefined - `scope-resolution/contract/scope-resolver.ts` — adds optional `resolveAdlCandidates` hook - `scope-resolution/passes/free-call-fallback.ts` — invokes ADL hook between `findCallableBindingInScope` and `pickUniqueGlobalCallable`; marks site handled on `'ambiguous'` so emit-references doesn't retry - `cpp/captures.ts` — detects `parenthesized_expression` function wrap; per-arg classification (pointer/reference/value class) preserving the shape info the existing arity-narrowing normalizer strips - `cpp/scope-resolver.ts` — registers hook, populates associated namespaces, clears state in loadResolutionConfig Negative tests (parens, pointer-boundary, ambiguous) gated under LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES.cpp — legacy DAG has no V1/V2 ADL boundary or ADL_AMBIGUOUS suppression. 154/154 cpp integration tests pass under REGISTRY_PRIMARY_CPP=1; 147 pass + 7 skipped under =0 (legacy parity baseline). * fix(cpp): inline namespace transitive walking + qualified namespace resolution (U5) Plan 2026-05-13-001 U5. Two ISO C++ inline-namespace semantics: 1. Unqualified-lookup transitive visibility: inline-namespace members reach the enclosing namespace's scope as if declared there. The `populateCppNonGloballyVisible` exemption keeps them globally visible so cross-file unqualified lookup finds them. 2. Qualified-receiver transitive visibility: `outer::foo()` resolves to `outer::v1::foo()` when `v1` is inline (and through arbitrarily-deep nesting like `outer::v1::experimental::foo`, matching libc++ `__1` / libstdc++ `__cxx11`). The second behavior required a new resolver case in `receiver-bound-calls.ts` (Case 1.5: language-specific qualified-receiver member lookup) because C++ qualified-namespace member calls had no prior resolution path — receiver-bound Case 1 only handled `ParsedImport.kind === 'namespace'` (Python/JS-style) and Case 2 handles class receivers, neither of which fired for `outer::foo()`. The new hook `resolveQualifiedReceiverMember` is opt-in; languages without C++-style qualified-name semantics omit it. Implementation: - `cpp/inline-namespaces.ts` — new module: per-pipeline `inlineNamespaceRangesByFile` + `inlineNamespaceScopeIds` Sets; `markCppInlineNamespaceRange` at capture time; `populateCppInlineNamespaceScopes` resolves ranges → scope IDs; `resolveCppQualifiedNamespaceMember` walks namespace scopes by simple name and descends transitively through inline children only. - `scope-resolution/contract/scope-resolver.ts` — adds optional `resolveQualifiedReceiverMember` hook to the contract. - `scope-resolution/passes/receiver-bound-calls.ts` — Case 1.5 invokes the hook between Case 1 (namespace imports) and Case 2 (class-name receiver). Returns undefined for non-namespace receivers so Case 2 still resolves class-qualified calls. - `cpp/captures.ts` — detects `inline` keyword child on `namespace_definition`; records 1-based range to match Scope.range. - `cpp/file-local-linkage.ts` — `populateCppNonGloballyVisible` exempts inline-namespace scopes so cross-file unqualified lookup keeps their members visible. - `cpp/scope-resolver.ts` — wires `populateCppInlineNamespaceScopes` into populateOwners (BEFORE `populateCppNonGloballyVisible` so the exemption sees populated state); registers `resolveQualifiedReceiverMember` hook. 4 fixtures: `cpp-inline-namespace-unqualified`, `-versioned`, `-nested` (two transitive inline hops, STL `__1` shape), and `-adl-participation` (composes with U2 — ADL surfaces records declared inside inline child namespaces). All 4 assert exactly 1 CALLS edge with correct target file. Versioned fixture gated under LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES.cpp — legacy DAG can't disambiguate two same-name foos without inline awareness. Other 3 coincidentally resolve in legacy. 158/158 cpp integration tests pass under REGISTRY_PRIMARY_CPP=1; 150 pass + 8 skipped under =0 (legacy parity baseline). * test(cpp): Phase 5 cross-unit composition tests for U1/U2/U3/U5 Plan 2026-05-13-001 Phase 5. Locks in correct behavior at the intersections between the previously-shipped scope-resolver units. Enhancement to U1: `isSuperReceiverInContext` strips template-argument lists (`Base` → `Base`) and namespace prefixes (`outer::v1::Base` → `Base`) before resolving the receiver in the caller's scope chain. This makes the super-receiver classification work for template-class heritage shapes like `Base::method()` and `outer::v1::Base::f()`. Three fixtures + four tests: - `cpp-phase5-u1-u3-qualified-base-call`: `template struct Derived : Base` with `Base::method()` inside a template body. Asserts NO mis-routing (count = 0) — documents the V1 gap that template-class inheritance isn't captured as EXTENDS by the legacy DAG, so MRO walks are empty and the super branch can't dispatch. The composition still works correctly: U1's template-arg-stripping classifies `Base` as a super candidate, but the empty-MRO terminates without false edges. - `cpp-phase5-u2-u3-adl-from-derived`: `Derived : Base` where `Base::record` shadows `audit::record`. Unqualified `record(e)` inside the template body should resolve via ADL to `audit::record` (because U3 + the `isFileLocalDef` class- owned filter suppress `Base::record`). Asserts 1 edge to audit.h and 0 edges to base.h. - `cpp-phase5-u3-u5-inline-base`: `template struct Derived : outer::v1::Base` where `v1` is inline. Unqualified `f()` inside `Derived::g()` should NOT bind to Base::f (dependent-base suppression even across inline namespace prefix). Asserts count = 0. Phase 5 tests asserting no-false-positives are gated under LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES.cpp — legacy DAG over- resolves without the template-arg-stripping qualified-receiver path and without two-phase dependent-base suppression. 162/162 cpp integration tests pass under REGISTRY_PRIMARY_CPP=1; 152 pass + 10 skipped under =0 (legacy parity baseline). --------- Co-authored-by: HuangWenjie Co-authored-by: Gergo Magyar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../scope-resolution/finalize-algorithm.ts | 11 +- gitnexus/src/core/ingestion/call-processor.ts | 26 +- .../src/core/ingestion/languages/c-cpp.ts | 19 + .../src/core/ingestion/languages/cpp/adl.ts | 335 +++++++ .../ingestion/languages/cpp/arity-metadata.ts | 185 ++++ .../src/core/ingestion/languages/cpp/arity.ts | 35 + .../core/ingestion/languages/cpp/captures.ts | 832 ++++++++++++++++++ .../languages/cpp/file-local-linkage.ts | 214 +++++ .../ingestion/languages/cpp/header-scan.ts | 53 ++ .../languages/cpp/import-decomposer.ts | 120 +++ .../ingestion/languages/cpp/import-target.ts | 18 + .../src/core/ingestion/languages/cpp/index.ts | 16 + .../languages/cpp/inline-namespaces.ts | 170 ++++ .../core/ingestion/languages/cpp/interpret.ts | 112 +++ .../ingestion/languages/cpp/merge-bindings.ts | 38 + .../src/core/ingestion/languages/cpp/query.ts | 462 ++++++++++ .../ingestion/languages/cpp/range-bindings.ts | 255 ++++++ .../ingestion/languages/cpp/scope-resolver.ts | 230 +++++ .../ingestion/languages/cpp/simple-hooks.ts | 79 ++ .../languages/cpp/two-phase-lookup.ts | 133 +++ .../core/ingestion/registry-primary-flag.ts | 1 + .../contract/scope-resolver.ts | 100 +++ .../passes/free-call-fallback.ts | 49 +- .../passes/imported-return-types.ts | 3 +- .../passes/overload-narrowing.ts | 60 ++ .../passes/receiver-bound-calls.ts | 86 +- .../scope-resolution/pipeline/registry.ts | 2 + .../scope-resolution/pipeline/run.ts | 1 + .../core/ingestion/workers/parse-worker.ts | 3 + .../lang-resolution/cpp-adl-ambiguous/alpha.h | 7 + .../lang-resolution/cpp-adl-ambiguous/app.cpp | 8 + .../lang-resolution/cpp-adl-basic/app.cpp | 8 + .../lang-resolution/cpp-adl-basic/audit.h | 6 + .../cpp-adl-pointer-arg-boundary/app.cpp | 8 + .../cpp-adl-pointer-arg-boundary/audit.h | 6 + .../cpp-adl-suppressed-parens/app.cpp | 8 + .../cpp-adl-suppressed-parens/audit.h | 6 + .../cpp-anon-ns-cross-file/caller.cpp | 5 + .../cpp-anon-ns-cross-file/helper.cpp | 7 + .../cpp-anon-ns-same-file-visible/helper.cpp | 7 + .../cpp-include-no-class-leak/caller.cpp | 5 + .../cpp-include-no-class-leak/user.h | 6 + .../cpp-include-no-namespace-leak/caller.cpp | 5 + .../cpp-include-no-namespace-leak/lib.h | 5 + .../app.cpp | 8 + .../audit.h | 8 + .../cpp-inline-namespace-nested/caller.cpp | 5 + .../cpp-inline-namespace-nested/lib.h | 9 + .../caller.cpp | 5 + .../cpp-inline-namespace-unqualified/lib.h | 7 + .../cpp-inline-namespace-versioned/caller.cpp | 5 + .../cpp-inline-namespace-versioned/lib.h | 10 + .../caller.cpp | 5 + .../singleton.h | 6 + .../caller.cpp | 6 + .../service.cpp | 4 + .../service.h | 7 + .../cpp-overload-int-long/caller.cpp | 6 + .../cpp-overload-int-long/service.cpp | 4 + .../cpp-overload-int-long/service.h | 7 + .../classes.h | 13 + .../cpp-phase5-u2-u3-adl-from-derived/audit.h | 6 + .../cpp-phase5-u2-u3-adl-from-derived/base.h | 8 + .../derived.h | 11 + .../cpp-phase5-u3-u5-inline-base/base.h | 10 + .../cpp-phase5-u3-u5-inline-base/derived.h | 10 + .../cpp-two-phase-dependent-base/base.h | 7 + .../cpp-two-phase-dependent-base/derived.h | 13 + .../base.h | 6 + .../derived.h | 11 + .../helpers.h | 5 + .../concrete-base.h | 5 + .../derived.h | 10 + .../cpp-two-phase-this-qualified/base.h | 7 + .../cpp-two-phase-this-qualified/derived.h | 13 + .../cpp-using-namespace-conflict/a.h | 5 + .../cpp-using-namespace-conflict/b.h | 5 + .../cpp-using-namespace-conflict/caller.cpp | 9 + .../cpp-using-namespace-std-smoke/caller.cpp | 9 + .../cpp-using-namespace-std-smoke/helper.cpp | 1 + .../cpp-using-namespace-std-smoke/std-shim.h | 13 + .../test/integration/resolvers/cpp.test.ts | 611 ++++++++++++- .../test/integration/resolvers/helpers.ts | 68 ++ .../test/unit/registry-primary-flag.test.ts | 11 +- .../scope-resolution/cpp/cpp-arity.test.ts | 168 ++++ .../scope-resolution/cpp/cpp-captures.test.ts | 426 +++++++++ .../scope-resolution/cpp/cpp-imports.test.ts | 161 ++++ 87 files changed, 5445 insertions(+), 24 deletions(-) create mode 100644 gitnexus/src/core/ingestion/languages/cpp/adl.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/arity.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/captures.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/file-local-linkage.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/header-scan.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/import-decomposer.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/import-target.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/index.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/inline-namespaces.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/interpret.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/merge-bindings.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/query.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/range-bindings.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/simple-hooks.ts create mode 100644 gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/alpha.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/helper.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-same-file-visible/helper.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/user.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/lib.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/lib.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/lib.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/lib.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/singleton.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-qualified-base-call/classes.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/concrete-base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/a.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/b.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/caller.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/helper.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/std-shim.h create mode 100644 gitnexus/test/unit/scope-resolution/cpp/cpp-arity.test.ts create mode 100644 gitnexus/test/unit/scope-resolution/cpp/cpp-captures.test.ts create mode 100644 gitnexus/test/unit/scope-resolution/cpp/cpp-imports.test.ts diff --git a/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts b/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts index a94012a0b..f5d3dd0bf 100644 --- a/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts +++ b/gitnexus-shared/src/scope-resolution/finalize-algorithm.ts @@ -833,7 +833,16 @@ function expandWildcard( if (target === undefined) return [edge]; const names = hooks.expandsWildcardTo(edge.targetModuleScope, workspace); - if (names.length === 0) return []; + if (names.length === 0) { + // Resolved wildcard with zero propagating names is still a real file- + // level dependency (e.g. a C++ header that only declares classes — + // `#include` is a valid IMPORTS edge, but unqualified-binding names + // are correctly empty since class methods require `Class::method`). + // Preserve the original wildcard edge so the file→file IMPORTS edge + // survives; downstream binding materialization sees no propagated + // names because the edge has no `targetExportedName`/`localName`. + return [edge]; + } const expanded: ImportEdge[] = []; for (const name of names) { diff --git a/gitnexus/src/core/ingestion/call-processor.ts b/gitnexus/src/core/ingestion/call-processor.ts index b45478f7a..35a59dab4 100644 --- a/gitnexus/src/core/ingestion/call-processor.ts +++ b/gitnexus/src/core/ingestion/call-processor.ts @@ -774,6 +774,7 @@ export const processCalls = async ( propertyName: string; filePath: string; srcId: string; + line?: number; }[] = []; // Phase P cross-file: accumulate heritage across files for cross-file isSubclassOf. // Used as a secondary check when per-file parentMap lacks the relationship — helps @@ -1102,11 +1103,16 @@ export const processCalls = async ( provider, ); const srcId = enclosing || generateId('File', file.path); - // Defer resolution so write-access tracking sees the FINAL graph - // state — properties from the pre-pass are present, but receiver-type - // resolution can still depend on inference that completes during the - // main loop. Resolve after all files have been processed. - pendingWrites.push({ receiverTypeName, propertyName, filePath: file.path, srcId }); + // Defer resolution: Ruby attr_accessor properties are registered during + // this same loop, so cross-file lookups fail if the declaring file hasn't + // been processed yet. Collect now, resolve after all files are done. + pendingWrites.push({ + receiverTypeName, + propertyName, + filePath: file.path, + srcId, + line: captureMap['assignment'].startPosition.row + 1, + }); } // Assignment-only capture (no @call sibling): skip the rest of this // forEach iteration — this acts as a `continue` in the match loop. @@ -1516,7 +1522,10 @@ export const processCalls = async ( ); if (fieldOwner) { graph.addRelationship({ - id: generateId('ACCESSES', `${pw.srcId}:${fieldOwner.nodeId}:write`), + id: generateId( + 'ACCESSES', + `${pw.srcId}:${fieldOwner.nodeId}:write${pw.line !== undefined ? `:${pw.line}` : ''}`, + ), sourceId: pw.srcId, targetId: fieldOwner.nodeId, type: 'ACCESSES', @@ -3113,7 +3122,10 @@ export const processAssignmentsFromExtracted = ( const fieldOwner = resolveFieldOwnership(receiverTypeName, asn.propertyName, asn.filePath, ctx); if (!fieldOwner) continue; graph.addRelationship({ - id: generateId('ACCESSES', `${asn.sourceId}:${fieldOwner.nodeId}:write`), + id: generateId( + 'ACCESSES', + `${asn.sourceId}:${fieldOwner.nodeId}:write${asn.line !== undefined ? `:${asn.line}` : ''}`, + ), sourceId: asn.sourceId, targetId: fieldOwner.nodeId, type: 'ACCESSES', diff --git a/gitnexus/src/core/ingestion/languages/c-cpp.ts b/gitnexus/src/core/ingestion/languages/c-cpp.ts index 7fab4689b..58e59fe6f 100644 --- a/gitnexus/src/core/ingestion/languages/c-cpp.ts +++ b/gitnexus/src/core/ingestion/languages/c-cpp.ts @@ -55,6 +55,15 @@ import { cImportOwningScope, cReceiverBinding, } from './c/index.js'; +import { + emitCppScopeCaptures, + interpretCppImport, + interpretCppTypeBinding, + cppArityCompatibility, + cppBindingScopeFor, + cppImportOwningScope, + cppReceiverBinding, +} from './cpp/index.js'; const C_BUILT_INS: ReadonlySet = new Set([ 'printf', @@ -447,4 +456,14 @@ export const cppProvider = defineLanguage({ heritageExtractor: createHeritageExtractor(SupportedLanguages.CPlusPlus), labelOverride: cppLabelOverride, builtInNames: C_BUILT_INS, + + // ── RFC #909 Ring 3: scope-based resolution hooks (RFC §5) ────────── + emitScopeCaptures: emitCppScopeCaptures, + interpretImport: interpretCppImport, + interpretTypeBinding: interpretCppTypeBinding, + bindingScopeFor: cppBindingScopeFor, + importOwningScope: cppImportOwningScope, + receiverBinding: cppReceiverBinding, + arityCompatibility: cppArityCompatibility, + // mergeBindings + resolveImportTarget live on ScopeResolver (see cpp/scope-resolver.ts). }); diff --git a/gitnexus/src/core/ingestion/languages/cpp/adl.ts b/gitnexus/src/core/ingestion/languages/cpp/adl.ts new file mode 100644 index 000000000..112502a74 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/adl.ts @@ -0,0 +1,335 @@ +/** + * C++ argument-dependent lookup (ADL / Koenig lookup) — V1. + * + * When ordinary unqualified lookup fails for a free-call site, ADL also + * considers candidates declared in the **associated namespaces** of the + * call's argument types (ISO C++ `[basic.lookup.argdep]`). The canonical + * pattern V1 unlocks: + * + * namespace audit { struct Event; void record(Event); } + * namespace app { void run() { audit::Event e; record(e); } } + * + * Without ADL: `record(e)` is unresolved because `app::run` doesn't + * `using` anything. With V1 ADL: `audit::record` is discovered via + * `audit::Event`'s associated namespace. + * + * ## V1 boundary + * + * V1 covers ONE associated-entity rule: an argument that's a directly-named + * class type (`audit::Event e`) contributes its **direct enclosing + * namespace** to the candidate set. Anything else — pointer/reference + * arguments, function-pointer arguments, template specializations, + * base-class associated namespaces — is V2 closure work and is + * deliberately excluded. The `cpp-adl-pointer-arg-boundary` fixture + * locks the exclusion in CI. + * + * V1 also short-circuits to ADL only when ordinary lookup is empty + * (`findCallableBindingInScope` returned undefined). ISO C++ would + * normally merge ADL candidates with ordinary-lookup candidates and + * run overload resolution over the union; V1 defers that merge to V2. + * + * ## Parenthesized-name suppression + * + * `(f)(s)` MUST NOT trigger ADL — the parenthesized name forces ordinary + * lookup only. `captures.ts` records sites whose `function` child is a + * `parenthesized_expression` into `noAdlSites`; `pickCppAdlCandidates` + * short-circuits when the site key is present. + * + * ## State lifecycle + * + * Three module-level maps populated per pipeline invocation, cleared via + * `clearCppAdlState()` (called from `clearFileLocalNames`): + * + * - `argInfoBySite` — per-call-site argument shape (capture-time) + * - `noAdlSites` — call sites with parenthesized function (capture-time) + * - `classToNamespaceQualifiedName` — class def → its enclosing namespace + * qualified name (`populateCppAssociatedNamespaces` time) + * + * The class→namespace map uses qualified names (not scope IDs) because + * C++ namespaces are open: `namespace N { ... }` in file A and + * `namespace N { ... }` in file B produce two distinct Namespace scopes + * but logically share the same namespace. ADL must consider candidates + * declared in either file. + */ + +import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; +import { + isOverloadAmbiguousAfterNormalization, + narrowOverloadCandidates, +} from '../../scope-resolution/passes/overload-narrowing.js'; + +/** + * Per-argument shape information collected at capture time. ADL only + * fires for arguments where `simpleClassName !== ''` AND `!isPointer` + * AND `!isReference` — i.e., directly-named class-type values. + */ +export interface CppAdlArgInfo { + /** Simple class-like type name (last segment of qualified name); empty + * for primitives, literals, function pointers, template specs, etc. */ + readonly simpleClassName: string; + /** True when the variable's declarator was a `pointer_declarator`. V1 + * excludes pointer-typed args (closure rules deferred to V2). */ + readonly isPointer: boolean; + /** True when the variable's declarator was a `reference_declarator`. */ + readonly isReference: boolean; +} + +const argInfoBySite = new Map(); +const noAdlSites = new Set(); +const classToNamespaceQualifiedName = new Map(); + +/** Sentinel returned by `pickCppAdlCandidates` when ADL surfaces multiple + * candidates that share normalized parameter types — the caller MUST + * suppress (zero edges) rather than pick arbitrarily. Mirrors the + * OVERLOAD_AMBIGUOUS contract from the receiver-bound path. */ +export const ADL_AMBIGUOUS = Symbol('ADL_AMBIGUOUS'); +export type AdlResult = SymbolDefinition | typeof ADL_AMBIGUOUS | undefined; + +function siteKey(filePath: string, line: number, col: number): string { + return `${filePath}:${line}:${col}`; +} + +/** Record per-call-site argument info. Called once per call site from + * `emitCppScopeCaptures`. */ +export function markCppAdlSiteArgs( + filePath: string, + line: number, + col: number, + args: readonly CppAdlArgInfo[], +): void { + argInfoBySite.set(siteKey(filePath, line, col), args); +} + +/** Mark a call site as ADL-suppressed (function child wrapped in + * `parenthesized_expression`, e.g. `(f)(s)`). */ +export function markCppAdlSiteNoAdl(filePath: string, line: number, col: number): void { + noAdlSites.add(siteKey(filePath, line, col)); +} + +/** Clear ADL state. Called from `clearFileLocalNames` so all C++ resolver + * per-pipeline state is reset together. */ +export function clearCppAdlState(): void { + argInfoBySite.clear(); + noAdlSites.clear(); + classToNamespaceQualifiedName.clear(); +} + +/** + * Walk `parsed.scopes` to record each Class def's enclosing namespace + * qualified name. Run from the cpp resolver's `populateOwners` hook so + * the index is available before any resolution pass consults it. + * + * Computes the namespace's qualified name by walking parent scope chain + * and looking up Namespace defs in each parent's `ownedDefs`. The + * resulting name is dot-joined (matching `populateClassOwnedMembers`'s + * dotted convention; conversion to `::` is consumer-internal). + */ +export function populateCppAssociatedNamespaces(parsed: ParsedFile): void { + const scopesById = new Map(); + for (const scope of parsed.scopes) scopesById.set(scope.id, scope); + + for (const scope of parsed.scopes) { + if (scope.kind !== 'Class') continue; + const nsQName = computeEnclosingNamespaceQName(scope, scopesById); + if (nsQName === '') continue; + for (const def of scope.ownedDefs) { + if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue; + classToNamespaceQualifiedName.set(def.nodeId, nsQName); + } + } +} + +/** + * V1 ADL candidate picker. Returns: + * - `SymbolDefinition` — exactly one ADL candidate (or unique survivor + * after narrowing); caller emits the CALLS edge. + * - `ADL_AMBIGUOUS` — multiple candidates with no disambiguator; + * caller MUST suppress (zero edges). + * - `undefined` — no ADL candidates; caller falls through to ordinary + * `pickUniqueGlobalCallable` fallback. + * + * Fires only when: + * - the call site is not in `noAdlSites` (parenthesized form), AND + * - at least one argument is a directly-named class type (not pointer, + * not reference, not literal/primitive). + */ +export function pickCppAdlCandidates( + site: { + readonly name: string; + readonly arity?: number; + readonly argumentTypes?: readonly string[]; + readonly atRange: { startLine: number; startCol: number }; + }, + callerParsed: ParsedFile, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], +): AdlResult { + const key = siteKey(callerParsed.filePath, site.atRange.startLine, site.atRange.startCol); + if (noAdlSites.has(key)) return undefined; + const args = argInfoBySite.get(key); + if (args === undefined || args.length === 0) return undefined; + + // Collect associated namespace QNames from every value-class-typed arg. + const associatedNamespaces = new Set(); + for (const arg of args) { + if (arg.simpleClassName === '') continue; + if (arg.isPointer || arg.isReference) continue; + const classDef = findCppClassDefBySimpleName(arg.simpleClassName, scopes); + if (classDef === undefined) continue; + const nsQName = classToNamespaceQualifiedName.get(classDef.nodeId); + if (nsQName !== undefined) associatedNamespaces.add(nsQName); + } + if (associatedNamespaces.size === 0) return undefined; + + // Walk every namespace scope in every parsed file; collect callable + // ownedDefs whose enclosing namespace matches one of the associated + // QNames AND whose simple name matches the call's name. + const candidates: SymbolDefinition[] = []; + const seenKey = new Set(); + for (const parsed of parsedFiles) { + const scopesById = new Map(); + for (const sc of parsed.scopes) scopesById.set(sc.id, sc); + for (const scope of parsed.scopes) { + if (scope.kind !== 'Namespace') continue; + const qName = computeNamespaceQName(scope, scopesById); + if (!associatedNamespaces.has(qName)) continue; + for (const def of scope.ownedDefs) { + if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') { + continue; + } + const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; + if (simple !== site.name) continue; + // Dedup by nodeId — using normalized parameter-types as the key + // would collapse `process(int)`/`process(long)`-style overloads + // (both normalize to `['int']`) before + // `isOverloadAmbiguousAfterNormalization` can detect them. + if (seenKey.has(def.nodeId)) continue; + seenKey.add(def.nodeId); + candidates.push(def); + } + } + } + if (candidates.length === 0) return undefined; + if (candidates.length === 1) return candidates[0]; + + // Multi-candidate: narrow then check ambiguity. Reuses the OVERLOAD_AMBIGUOUS + // sentinel contract from `overload-narrowing.ts` so int/long-collision-style + // ambiguity also suppresses on the ADL path. + const narrowed = narrowOverloadCandidates(candidates, site.arity, site.argumentTypes); + if (narrowed.length === 1) return narrowed[0]; + if (narrowed.length === 0) return undefined; + if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) return ADL_AMBIGUOUS; + // Multiple surviving candidates that aren't normalization-ambiguous — + // ISO C++ would run overload resolution; V1 lacks conversion ranking so + // suppress rather than pick arbitrarily. Mirrors `pickImplicitThisOverload`'s + // unique-survivor requirement (see `pick-implicit-this-overload.test.ts`). + return ADL_AMBIGUOUS; +} + +/** Walk upward from a Class scope, finding the innermost enclosing + * Namespace scope, and return that namespace's qualified name (dot- + * joined, outermost-first). Returns '' when the class has no enclosing + * namespace (e.g., declared at translation-unit scope). */ +function computeEnclosingNamespaceQName( + classScope: { readonly parent: ScopeId | null }, + scopesById: ReadonlyMap< + ScopeId, + { + readonly parent: ScopeId | null; + readonly kind: string; + readonly ownedDefs: readonly SymbolDefinition[]; + } + >, +): string { + let parentId: ScopeId | null = classScope.parent; + while (parentId !== null) { + const parent = scopesById.get(parentId); + if (parent === undefined) return ''; + if (parent.kind === 'Namespace') { + return computeNamespaceQName(parent, scopesById); + } + parentId = parent.parent; + } + return ''; +} + +/** Walk upward from a Namespace scope collecting each enclosing + * Namespace's simple name (innermost last). Returns the dot-joined + * qualified name (e.g., `outer.inner`). The namespace's own def lives + * in its OWN scope's `ownedDefs` (the C++ extractor stamps the + * namespace-decl def into the namespace scope itself, not the parent + * module scope). */ +function computeNamespaceQName( + nsScope: { readonly parent: ScopeId | null; readonly ownedDefs: readonly SymbolDefinition[] }, + scopesById: ReadonlyMap< + ScopeId, + { + readonly parent: ScopeId | null; + readonly kind: string; + readonly ownedDefs: readonly SymbolDefinition[]; + } + >, +): string { + const segments: string[] = []; + let currentId: ScopeId | null = nsScope.parent; + let current: + | { readonly parent: ScopeId | null; readonly ownedDefs: readonly SymbolDefinition[] } + | undefined = nsScope; + // Outer guard against pathological cycles in malformed scope trees. + let safety = 64; + while (current !== undefined && safety-- > 0) { + const nsDef = findNamespaceDefInScope(current); + if (nsDef === undefined) { + // No name found — bail out. Returning a partial QName would risk + // false ADL associations. + return ''; + } + const simple = nsDef.qualifiedName?.split('.').pop() ?? nsDef.qualifiedName ?? ''; + segments.unshift(simple); + // Walk up to next enclosing namespace (skipping non-namespace parents). + let nextId: ScopeId | null = currentId; + let nextNs: typeof current | undefined; + while (nextId !== null) { + const nx = scopesById.get(nextId); + if (nx === undefined) break; + if (nx.kind === 'Namespace') { + nextNs = nx; + currentId = nx.parent; + break; + } + nextId = nx.parent; + } + current = nextNs; + } + return segments.join('.'); +} + +/** Find the Namespace def attached to this scope (the namespace's own + * decl, stamped into its own `ownedDefs` by the C++ extractor). Returns + * the first Namespace-type def encountered — for normal C++ the scope + * carries exactly one Namespace-typed self def. */ +function findNamespaceDefInScope(scope: { + readonly ownedDefs: readonly SymbolDefinition[]; +}): SymbolDefinition | undefined { + for (const def of scope.ownedDefs) { + if (def.type === 'Namespace') return def; + } + return undefined; +} + +/** Find a class-like def by simple name across the workspace. V1 + * arbitrary-pick on collisions (multiple classes share the simple name); + * C++ ADL strictness would require full type-driven lookup, but V1 + * trades that for simplicity. */ +function findCppClassDefBySimpleName( + simpleName: string, + scopes: ScopeResolutionIndexes, +): SymbolDefinition | undefined { + for (const def of scopes.defs.byId.values()) { + if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue; + const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; + if (simple === simpleName) return def; + } + return undefined; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts b/gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts new file mode 100644 index 000000000..fb47d3122 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/arity-metadata.ts @@ -0,0 +1,185 @@ +import type { SyntaxNode } from '../../utils/ast-helpers.js'; + +export interface CppArityInfo { + parameterCount?: number; + requiredParameterCount?: number; + parameterTypes?: string[]; +} + +/** + * Compute declaration arity from a C++ function definition or declaration node. + * Extends the C arity computation with support for: + * - optional_parameter_declaration (default parameters) + * - variadic_parameter_declaration / parameter packs + * - (void) explicit zero-parameter form + */ +export function computeCppDeclarationArity(node: SyntaxNode): CppArityInfo { + const funcDecl = findFuncDeclarator(node); + if (funcDecl === null) return {}; + + const paramList = funcDecl.childForFieldName('parameters'); + if (paramList === null) return {}; + + const params: SyntaxNode[] = []; + // Track whether a C-style variadic `...` anonymous token appears. + // tree-sitter-cpp emits `...` as an anonymous (non-named) child of + // parameter_list, not as `variadic_parameter`. + let hasEllipsis = false; + for (let i = 0; i < paramList.childCount; i++) { + const child = paramList.child(i); + if (child === null) continue; + if ( + child.type === 'parameter_declaration' || + child.type === 'optional_parameter_declaration' || + child.type === 'variadic_parameter' || + child.type === 'variadic_parameter_declaration' + ) { + params.push(child); + } else if (child.type === '...' || (!child.isNamed && child.text === '...')) { + hasEllipsis = true; + } + } + + // Empty parameter list: C++ `void foo()` means zero params (unlike C) + if (params.length === 0 && !hasEllipsis) { + return { parameterCount: 0, requiredParameterCount: 0, parameterTypes: [] }; + } + + // (void) means zero parameters + if (params.length === 1 && params[0].type === 'parameter_declaration') { + const typeNode = params[0].childForFieldName('type'); + const hasDeclarator = params[0].childForFieldName('declarator') !== null; + if (typeNode !== null && typeNode.text === 'void' && !hasDeclarator) { + return { parameterCount: 0, requiredParameterCount: 0, parameterTypes: [] }; + } + } + + // C-style variadic: `void foo(int x, ...)` — the `...` is an anonymous + // token in tree-sitter-cpp, detected via `hasEllipsis` above. + // C++ parameter packs: `template void foo(Ts... args)` — + // detected as `variadic_parameter_declaration`. + const isVariadic = + hasEllipsis || + params.some( + (p) => p.type === 'variadic_parameter' || p.type === 'variadic_parameter_declaration', + ); + const optionalCount = params.filter((p) => p.type === 'optional_parameter_declaration').length; + const requiredCount = params.filter( + (p) => + p.type === 'parameter_declaration' || + // variadic_parameter_declaration with a name is a parameter pack — counts as one + p.type === 'variadic_parameter_declaration', + ).length; + const totalNonVariadic = requiredCount + optionalCount; + + const types: string[] = []; + for (const p of params) { + if (p.type === 'variadic_parameter') { + types.push('...'); + } else if (p.type === 'variadic_parameter_declaration') { + // Parameter pack: treated as variadic + types.push('...'); + } else { + const typeNode = p.childForFieldName('type'); + types.push(normalizeCppParamType(typeNode?.text ?? 'unknown')); + } + } + // Append '...' for C-style variadic if not already in types + if (hasEllipsis && !types.includes('...')) { + types.push('...'); + } + + return { + parameterCount: isVariadic ? undefined : totalNonVariadic, + requiredParameterCount: requiredCount, + parameterTypes: types, + }; +} + +/** + * Compute call-site arity from a call_expression node. + */ +export function computeCppCallArity(node: SyntaxNode): number { + const argList = node.childForFieldName('arguments'); + if (argList === null) return 0; + + let count = 0; + for (let i = 0; i < argList.childCount; i++) { + const child = argList.child(i); + if (child === null) continue; + if (child.type !== ',' && child.type !== '(' && child.type !== ')') { + count++; + } + } + return count; +} + +/** + * Normalize a C++ parameter type for overload disambiguation. + * Maps common qualified/aliased types to their canonical short forms + * so that `narrowOverloadCandidates` can match against literal-inferred + * argument types (e.g. `inferCppLiteralType` returns `'string'` for + * string literals, not `'std::string'`). + */ +function normalizeCppParamType(raw: string): string { + let t = raw.trim(); + // Strip const, volatile, etc. + t = t.replace(/\b(const|volatile|restrict|mutable|constexpr)\b/g, '').trim(); + // Strip reference/pointer markers + t = t.replace(/[&*]+\s*$/, '').trim(); + // Strip template parameters (loop handles nested: Map> → Map) + while (t.includes('<')) { + const stripped = t.replace(/<[^<>]*>/g, ''); + if (stripped === t) break; // avoid infinite loop on malformed input + t = stripped; + } + t = t.trim(); + // Map std:: types to canonical short forms + const STD_MAP: Record = { + 'std::string': 'string', + 'std::wstring': 'string', + 'std::string_view': 'string', + string: 'string', + char: 'char', + int: 'int', + long: 'int', + short: 'int', + unsigned: 'int', + 'unsigned int': 'int', + 'long long': 'int', + size_t: 'int', + 'std::size_t': 'int', + float: 'double', + double: 'double', + bool: 'bool', + nullptr_t: 'null', + 'std::nullptr_t': 'null', + }; + return STD_MAP[t] ?? t; +} + +function findFuncDeclarator(node: SyntaxNode): SyntaxNode | null { + let decl = node.childForFieldName('declarator'); + if (decl === null) { + for (let i = 0; i < node.childCount; i++) { + const c = node.child(i); + if (c?.type === 'function_declarator') return c; + } + return null; + } + // Unwrap pointer_declarator / reference_declarator + while (decl.type === 'pointer_declarator' || decl.type === 'reference_declarator') { + const next = decl.childForFieldName('declarator'); + if (next === null) { + // reference_declarator may not use field name + for (let i = 0; i < decl.childCount; i++) { + const c = decl.child(i); + if (c?.type === 'function_declarator') return c; + } + break; + } + decl = next; + } + if (decl.type === 'function_declarator') return decl; + return null; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/arity.ts b/gitnexus/src/core/ingestion/languages/cpp/arity.ts new file mode 100644 index 000000000..e13fa6a3a --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/arity.ts @@ -0,0 +1,35 @@ +import type { Callsite, SymbolDefinition } from 'gitnexus-shared'; + +/** + * C++ arity compatibility: supports overloading and default parameters. + * + * Unlike C (no overloading, exact match only), C++ has: + * - Overloaded functions (same name, different signatures) + * - Default parameters (requiredParameterCount < parameterCount) + * - Variadic functions (C-style `...`) + * - Parameter packs (V1: treated as variadic) + * - Templates (V1: generic-ignored, arity check on non-template params) + * + * Verdict: + * - 'compatible': callsite.arity fits within [required, total] range + * - 'incompatible': callsite.arity is outside the valid range + * - 'unknown': insufficient metadata to determine + */ +export function cppArityCompatibility( + def: SymbolDefinition, + callsite: Callsite, +): 'compatible' | 'unknown' | 'incompatible' { + const max = def.parameterCount; + const min = def.requiredParameterCount; + if (max === undefined && min === undefined) return 'unknown'; + if (!Number.isFinite(callsite.arity) || callsite.arity < 0) return 'unknown'; + + const variadic = def.parameterTypes?.some((t) => t === '...') ?? false; + + // Too few arguments: less than the minimum required + if (min !== undefined && callsite.arity < min) return 'incompatible'; + // Too many arguments: more than the maximum and not variadic + if (max !== undefined && callsite.arity > max && !variadic) return 'incompatible'; + + return 'compatible'; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/captures.ts b/gitnexus/src/core/ingestion/languages/cpp/captures.ts new file mode 100644 index 000000000..e6d63635a --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/captures.ts @@ -0,0 +1,832 @@ +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { + findNodeAtRange, + nodeToCapture, + syntheticCapture, + type SyntaxNode, +} from '../../utils/ast-helpers.js'; +import { getCppParser, getCppScopeQuery } from './query.js'; +import { getTreeSitterBufferSize } from '../../constants.js'; +import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js'; +import { splitCppInclude, splitCppUsingDecl } from './import-decomposer.js'; +import { computeCppDeclarationArity, computeCppCallArity } from './arity-metadata.js'; +import { markFileLocal } from './file-local-linkage.js'; +import { markCppDependentBase } from './two-phase-lookup.js'; +import { markCppAdlSiteArgs, markCppAdlSiteNoAdl, type CppAdlArgInfo } from './adl.js'; +import { markCppInlineNamespaceRange } from './inline-namespaces.js'; + +export function emitCppScopeCaptures( + sourceText: string, + filePath: string, + cachedTree?: unknown, +): readonly CaptureMatch[] { + let tree = cachedTree as ReturnType['parse']> | undefined; + if (tree === undefined) { + tree = parseSourceSafe(getCppParser(), sourceText, undefined, { + bufferSize: getTreeSitterBufferSize(sourceText), + }); + } + + const rawMatches = getCppScopeQuery().matches(tree.rootNode); + const out: CaptureMatch[] = []; + + // Track ranges where typedef-struct was captured as @declaration.struct + // so we can suppress the duplicate @declaration.typedef match. + const structTypedefRanges = new Set(); + + for (const m of rawMatches) { + const grouped: Record = {}; + for (const c of m.captures) { + const tag = '@' + c.name; + if (tag.startsWith('@_')) continue; + grouped[tag] = nodeToCapture(tag, c.node); + } + if (Object.keys(grouped).length === 0) continue; + + // ── Handle #include statements ────────────────────────────────── + if (grouped['@import.statement'] !== undefined) { + const anchor = grouped['@import.statement']!; + const includeNode = findNodeAtRange(tree.rootNode, anchor.range, 'preproc_include'); + if (includeNode !== null) { + const split = splitCppInclude(includeNode); + if (split !== null) { + out.push(split); + continue; + } + } + } + + // ── Handle using declarations (using namespace / using name) ──── + if (grouped['@import.using-decl'] !== undefined) { + const anchor = grouped['@import.using-decl']!; + const usingNode = findNodeAtRange(tree.rootNode, anchor.range, 'using_declaration'); + if (usingNode !== null) { + const split = splitCppUsingDecl(usingNode); + if (split !== null) { + out.push(split); + continue; + } + } + } + + // ── Track typedef-struct ranges ───────────────────────────────── + const structAnchor = grouped['@declaration.struct'] ?? grouped['@declaration.class']; + if (structAnchor !== undefined) { + const r = structAnchor.range; + structTypedefRanges.add(`${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`); + } + + // Suppress @declaration.typedef if the same range was already captured + const typedefAnchor = grouped['@declaration.typedef']; + if (typedefAnchor !== undefined) { + const r = typedefAnchor.range; + const key = `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`; + if (structTypedefRanges.has(key)) continue; + } + + // ── Enrich function/method declarations with arity metadata ───── + const declAnchor = grouped['@declaration.function'] ?? grouped['@declaration.method']; + if (declAnchor !== undefined) { + const fnNode = + findNodeAtRange(tree.rootNode, declAnchor.range, 'function_definition') ?? + findNodeAtRange(tree.rootNode, declAnchor.range, 'declaration') ?? + findNodeAtRange(tree.rootNode, declAnchor.range, 'field_declaration'); + if (fnNode !== null) { + const arity = computeCppDeclarationArity(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), + ); + } + + // Detect static storage class (file-local linkage) + if (hasStaticStorageClass(fnNode)) { + const nameText = grouped['@declaration.name']?.text; + if (nameText !== undefined) { + markFileLocal(filePath, nameText); + } + } + + // Detect anonymous namespace (file-local linkage) + if (isInsideAnonymousNamespace(fnNode)) { + const nameText = grouped['@declaration.name']?.text; + if (nameText !== undefined) { + markFileLocal(filePath, nameText); + } + } + } + } + + // ── Detect static variables (file-local linkage) ──────────────── + const varDeclAnchor = grouped['@declaration.variable']; + if (varDeclAnchor !== undefined) { + const varNode = findNodeAtRange(tree.rootNode, varDeclAnchor.range, 'declaration'); + if (varNode !== null) { + if (hasStaticStorageClass(varNode) || isInsideAnonymousNamespace(varNode)) { + const nameText = grouped['@declaration.name']?.text; + if (nameText !== undefined) { + markFileLocal(filePath, nameText); + } + } + } + } + + // ── Enrich call references with arity ─────────────────────────── + const callAnchor = + grouped['@reference.call.free'] ?? + grouped['@reference.call.member'] ?? + grouped['@reference.call.qualified']; + if (callAnchor !== undefined && grouped['@reference.arity'] === undefined) { + const callNode = findNodeAtRange(tree.rootNode, callAnchor.range, 'call_expression'); + if (callNode !== null) { + grouped['@reference.arity'] = syntheticCapture( + '@reference.arity', + callNode, + String(computeCppCallArity(callNode)), + ); + } + } + + // ── Enrich constructor calls (new Foo()) with arity ───────────── + const ctorCallAnchor = grouped['@reference.call.constructor']; + if (ctorCallAnchor !== undefined && grouped['@reference.arity'] === undefined) { + const newNode = findNodeAtRange(tree.rootNode, ctorCallAnchor.range, 'new_expression'); + if (newNode !== null) { + grouped['@reference.arity'] = syntheticCapture( + '@reference.arity', + newNode, + String(computeCppCallArity(newNode)), + ); + } + } + + // ── Synthesize argument types for overload narrowing ──────────── + const anyCallAnchor = callAnchor ?? ctorCallAnchor; + if (anyCallAnchor !== undefined && grouped['@reference.parameter-types'] === undefined) { + const cNode = + findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'call_expression') ?? + findNodeAtRange(tree.rootNode, anyCallAnchor.range, 'new_expression'); + if (cNode !== null) { + const argTypes = inferCppCallArgTypes(cNode); + if (argTypes !== undefined && argTypes.length > 0) { + grouped['@reference.parameter-types'] = syntheticCapture( + '@reference.parameter-types', + cNode, + JSON.stringify(argTypes), + ); + } + } + } + + // ── Inline namespace detection ────────────────────────────────── + // `inline namespace v1 { ... }` — tree-sitter-cpp exposes the + // `inline` keyword as a child of `namespace_definition`. Record the + // namespace's source range so `populateCppInlineNamespaceScopes` + // (during populateOwners) can match it back to the corresponding + // Namespace scope. + if (grouped['@declaration.namespace'] !== undefined) { + const anchor = grouped['@declaration.namespace']!; + const nsNode = findNodeAtRange(tree.rootNode, anchor.range, 'namespace_definition'); + if (nsNode !== null && isInlineNamespace(nsNode)) { + // Range coords stored in the shared Range shape use 1-based + // line numbers (see `ast-helpers.ts` rangeForNode where + // `startPosition.row + 1` is applied). Match that convention so + // `populateCppInlineNamespaceScopes` can join against `Scope.range`. + markCppInlineNamespaceRange(filePath, { + startLine: nsNode.startPosition.row + 1, + startCol: nsNode.startPosition.column, + endLine: nsNode.endPosition.row + 1, + endCol: nsNode.endPosition.column, + }); + } + } + + // ── ADL (Koenig lookup) per-site recording ────────────────────── + // Only free-call sites (no explicit receiver) participate in ADL — + // qualified `Ns::f(s)` and member `obj.f(s)` calls bypass the + // free-call fallback entirely (handled by receiver-bound-calls). + if (grouped['@reference.call.free'] !== undefined) { + const freeCallNode = findNodeAtRange( + tree.rootNode, + grouped['@reference.call.free']!.range, + 'call_expression', + ); + if (freeCallNode !== null) { + const adlAnchorRange = grouped['@reference.call.free']!.range; + if (isParenthesizedFunctionCall(freeCallNode)) { + markCppAdlSiteNoAdl(filePath, adlAnchorRange.startLine, adlAnchorRange.startCol); + } + const adlArgs = inferCppCallAdlArgs(freeCallNode); + if (adlArgs.length > 0) { + markCppAdlSiteArgs(filePath, adlAnchorRange.startLine, adlAnchorRange.startCol, adlArgs); + } + } + } + + // ── Post-process @type-binding.assignment for auto declarations ── + // The wildcard `type: (_)` in the @type-binding.assignment query + // pattern matches before the more specific @type-binding.alias and + // @type-binding.member-access patterns. When the type is `auto` + // (placeholder_type_specifier), we re-inspect the AST to synthesize + // the correct capture tags so interpret.ts can produce the right + // rawTypeName for compound-receiver chain resolution. + if ( + grouped['@type-binding.assignment'] !== undefined && + grouped['@type-binding.type']?.text === 'auto' + ) { + const anchor = grouped['@type-binding.assignment']!; + const declNode = findNodeAtRange(tree.rootNode, anchor.range, 'declaration'); + if (declNode !== null) { + const declarator = declNode.childForFieldName('declarator'); + if (declarator?.type === 'init_declarator') { + const valueNode = declarator.childForFieldName('value'); + if (valueNode !== null) { + if (valueNode.type === 'identifier') { + // auto alias = existingVar → promote to @type-binding.alias + grouped['@type-binding.alias'] = anchor; + grouped['@type-binding.type'] = nodeToCapture('@type-binding.type', valueNode); + delete grouped['@type-binding.assignment']; + } else if (valueNode.type === 'field_expression') { + // auto addr = user.address → promote to @type-binding.member-access + const argNode = valueNode.childForFieldName('argument'); + const fieldNode = valueNode.childForFieldName('field'); + if (argNode !== null && fieldNode !== null) { + grouped['@type-binding.member-access'] = anchor; + grouped['@type-binding.member-access-receiver'] = nodeToCapture( + '@type-binding.member-access-receiver', + argNode, + ); + grouped['@type-binding.type'] = nodeToCapture('@type-binding.type', fieldNode); + delete grouped['@type-binding.assignment']; + } + } else if (valueNode.type === 'call_expression') { + const fnNode = valueNode.childForFieldName('function'); + if (fnNode?.type === 'field_expression') { + // auto city = addr.getCity() → promote to @type-binding.alias + // with dotted rawName "addr.getCity" for compound-receiver + const argNode = fnNode.childForFieldName('argument'); + const fieldNode = fnNode.childForFieldName('field'); + if (argNode !== null && fieldNode !== null) { + grouped['@type-binding.member-access'] = anchor; + grouped['@type-binding.member-access-receiver'] = nodeToCapture( + '@type-binding.member-access-receiver', + argNode, + ); + grouped['@type-binding.type'] = nodeToCapture('@type-binding.type', fieldNode); + delete grouped['@type-binding.assignment']; + } + } + } + } + } + } + } + + out.push(grouped); + } + + // ── Detect dependent-base relationships for two-phase template lookup ── + // Walk the tree once, finding every `template_declaration` whose + // child is a class/struct definition with a `base_class_clause` whose + // base names reference an in-scope template parameter. Record the + // (className, dependentBaseName) pair so `populateCppDependentBases` + // (called from the `populateOwners` hook) can resolve names to nodeIds + // and the resolver can suppress unqualified-call binding to those + // bases per ISO C++ two-phase lookup. + detectCppDependentBases(tree.rootNode, filePath); + + return out; +} + +/** + * Walk the AST finding every template_declaration containing a class or + * struct definition with a dependent base. Records (className, baseName) + * pairs into the module-level state via `markCppDependentBase`. + * + * A base is "dependent" when its name (typically a template_type like + * `Base`) uses a template parameter of the enclosing template_declaration. + * Conservative bias: `typename T::U`, `decltype(...)` and template-template + * parameter shapes are also treated as dependent. + */ +function detectCppDependentBases(root: SyntaxNode, filePath: string): void { + const stack: SyntaxNode[] = [root]; + while (stack.length > 0) { + const node = stack.pop()!; + if (node.type === 'template_declaration') { + // Collect template-parameter names declared by this declaration. + // Inner template_declarations shadow outer ones — handled by the + // recursive descent below (each template_declaration creates its + // own parameter scope). + const params = collectTemplateParameterNames(node); + + // Find the class/struct definition inside this template_declaration. + const classNode = findChildOfType(node, ['class_specifier', 'struct_specifier']); + if (classNode !== null) { + const className = getTypeIdentifierName(classNode); + if (className !== '') { + const baseClause = findChildOfType(classNode, ['base_class_clause']); + if (baseClause !== null) { + for (const base of iterBaseClasses(baseClause)) { + if (isBaseDependent(base, params)) { + const baseName = extractBaseSimpleName(base); + if (baseName !== '') { + markCppDependentBase(filePath, className, baseName); + } + } + } + } + } + } + } + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child !== null) stack.push(child); + } + } +} + +/** Collect simple template parameter names from a template_declaration. */ +function collectTemplateParameterNames(templateDecl: SyntaxNode): Set { + const names = new Set(); + const paramList = findChildOfType(templateDecl, ['template_parameter_list']); + if (paramList === null) return names; + for (let i = 0; i < paramList.childCount; i++) { + const param = paramList.child(i); + if (param === null) continue; + if ( + param.type === 'type_parameter_declaration' || + param.type === 'optional_type_parameter_declaration' || + param.type === 'variadic_type_parameter_declaration' + ) { + const idNode = findFirstDescendantOfType(param, 'type_identifier'); + if (idNode !== null) names.add(idNode.text); + } else if ( + param.type === 'parameter_declaration' || + param.type === 'optional_parameter_declaration' || + param.type === 'variadic_parameter_declaration' + ) { + // Non-type template parameter (e.g. `template`). + const idNode = findFirstDescendantOfType(param, 'identifier'); + if (idNode !== null) names.add(idNode.text); + } else if (param.type === 'template_template_parameter_declaration') { + // template-template parameter (e.g. `template class TT>`) + const idNode = findFirstDescendantOfType(param, 'type_identifier'); + if (idNode !== null) names.add(idNode.text); + } + } + return names; +} + +/** Yield each base-class entry from a `base_class_clause`. */ +function* iterBaseClasses(baseClause: SyntaxNode): IterableIterator { + for (let i = 0; i < baseClause.childCount; i++) { + const child = baseClause.child(i); + if (child === null) continue; + // Skip ':', ',', and access_specifier nodes — the base names are + // type_identifier, template_type, or qualified_identifier. + if ( + child.type === 'type_identifier' || + child.type === 'template_type' || + child.type === 'qualified_identifier' + ) { + yield child; + } + } +} + +/** + * A base is dependent when: + * - it's a `template_type` and its argument list contains a + * `type_identifier` matching one of the enclosing template's params + * (e.g., `Base` where `T` is a template parameter), OR + * - it contains a `typename`, `decltype`, or `template_template_parameter` + * shape (conservatively treated as dependent). + * + * Non-dependent: `Base`, `ConcreteBase`, `Base` where + * `MyConcrete` is not a template parameter. + */ +function isBaseDependent(baseNode: SyntaxNode, templateParams: Set): boolean { + if (baseNode.type !== 'template_type') { + // Bare `type_identifier` or `qualified_identifier` bases — not + // dependent (the base name itself doesn't reference a template + // parameter at this level). + return false; + } + // Walk all descendants of the template_argument_list looking for any + // type_identifier matching a template parameter, or any conservative- + // dependent shape. + const stack: SyntaxNode[] = [baseNode]; + while (stack.length > 0) { + const node = stack.pop()!; + if (node.type === 'type_identifier' && templateParams.has(node.text)) { + return true; + } + if ( + node.type === 'decltype' || + node.type === 'dependent_type' || + node.type === 'template_template_parameter_declaration' + ) { + return true; + } + if (node.type === 'qualified_identifier') { + // `typename T::U` or `T::nested` — if any inner identifier matches + // a template parameter, dependent. + for (let i = 0; i < node.childCount; i++) { + const c = node.child(i); + if (c !== null) stack.push(c); + } + continue; + } + for (let i = 0; i < node.childCount; i++) { + const c = node.child(i); + if (c !== null) stack.push(c); + } + } + return false; +} + +/** Extract the simple name of a base class node. */ +function extractBaseSimpleName(baseNode: SyntaxNode): string { + if (baseNode.type === 'type_identifier') return baseNode.text; + if (baseNode.type === 'template_type') { + const nameNode = baseNode.childForFieldName('name'); + if (nameNode !== null) return nameNode.text; + // Fallback: first type_identifier descendant. + const id = findFirstDescendantOfType(baseNode, 'type_identifier'); + if (id !== null) return id.text; + } + if (baseNode.type === 'qualified_identifier') { + const nameNode = baseNode.childForFieldName('name'); + if (nameNode !== null) return nameNode.text; + } + return ''; +} + +/** Find the first direct child matching one of the given types. */ +function findChildOfType(node: SyntaxNode, types: readonly string[]): SyntaxNode | null { + for (let i = 0; i < node.childCount; i++) { + const c = node.child(i); + if (c !== null && types.includes(c.type)) return c; + } + return null; +} + +/** Recursive search for the first descendant of a given type. */ +function findFirstDescendantOfType(node: SyntaxNode, type: string): SyntaxNode | null { + if (node.type === type) return node; + for (let i = 0; i < node.childCount; i++) { + const c = node.child(i); + if (c === null) continue; + const hit = findFirstDescendantOfType(c, type); + if (hit !== null) return hit; + } + return null; +} + +/** Get the name of a class/struct/template_type node via its `name` field. */ +function getTypeIdentifierName(node: SyntaxNode): string { + const nameNode = node.childForFieldName('name'); + if (nameNode !== null) return nameNode.text; + const id = findFirstDescendantOfType(node, 'type_identifier'); + return id !== null ? id.text : ''; +} + +/** + * Infer argument types from a call_expression or new_expression node. + * Used for overload disambiguation by parameter types. + * + * Only literal types are inferred — identifiers and complex expressions + * return empty string (unknown) so narrowOverloadCandidates treats them + * as any-match. + */ +function inferCppCallArgTypes(node: SyntaxNode): string[] | undefined { + const argList = node.childForFieldName('arguments'); + if (argList === null) return undefined; + + const types: string[] = []; + for (let i = 0; i < argList.childCount; i++) { + const child = argList.child(i); + if (child === null) continue; + if (child.type === ',' || child.type === '(' || child.type === ')') continue; + const litType = inferCppLiteralType(child); + if (litType !== '') { + types.push(litType); + } else if (child.type === 'identifier') { + // Variable reference — look up declared type in enclosing scope + types.push(lookupDeclaredTypeForIdentifier(child)); + } else { + types.push(''); + } + } + return types.length > 0 ? types : undefined; +} + +/** + * Infer the canonical type name of a C++ literal AST node. + * Returns empty string for non-literal / unknown nodes. + */ +function inferCppLiteralType(node: SyntaxNode): string { + switch (node.type) { + case 'number_literal': { + const text = node.text; + // Floating-point literals contain '.', 'e', 'E', or end with 'f'/'F' + if ( + text.includes('.') || + text.includes('e') || + text.includes('E') || + text.endsWith('f') || + text.endsWith('F') + ) { + return 'double'; + } + return 'int'; + } + case 'string_literal': + case 'raw_string_literal': + case 'concatenated_string': + return 'string'; + case 'char_literal': + return 'char'; + case 'true': + case 'false': + return 'bool'; + case 'null': + case 'nullptr': + return 'null'; + default: + return ''; + } +} + +/** + * Look up the declared type of a variable by scanning sibling declarations + * in the enclosing compound_statement (function body). Handles: + * - `std::string result = ...` → 'string' + * - `int n = ...` → 'int' + * - `const int n = ...` → 'int' + * Returns empty string if no declaration found or type is auto/placeholder. + */ +function lookupDeclaredTypeForIdentifier(identNode: SyntaxNode): string { + const varName = identNode.text; + // Walk up to the enclosing compound_statement (function body) + let scope: SyntaxNode | null = identNode.parent; + while ( + scope !== null && + scope.type !== 'compound_statement' && + scope.type !== 'translation_unit' + ) { + scope = scope.parent; + } + if (scope === null) return ''; + + // Scan declarations in the scope for a matching variable name + for (let i = 0; i < scope.childCount; i++) { + const stmt = scope.child(i); + if (stmt === null || stmt.type !== 'declaration') continue; + + const typeNode = stmt.childForFieldName('type'); + if (typeNode === null) continue; + // Skip auto/placeholder types — those need chain-follow, not literal + if (typeNode.type === 'placeholder_type_specifier') continue; + + // Check init_declarator children for the variable name + const declarator = stmt.childForFieldName('declarator'); + if (declarator === null) continue; + if (declarator.type === 'init_declarator') { + const nameChild = declarator.childForFieldName('declarator'); + if (nameChild !== null && nameChild.text === varName) { + return normalizeCppTypeText(typeNode.text); + } + } else if (declarator.text === varName) { + return normalizeCppTypeText(typeNode.text); + } + } + return ''; +} + +/** Normalize a type-specifier text for argument type matching. + * Strips qualifiers (const, volatile), namespace prefixes (std::), + * and pointer/reference markers. */ +function normalizeCppTypeText(text: string): string { + let t = text.trim(); + t = t.replace(/\b(const|volatile|static|extern|mutable)\b/g, '').trim(); + t = t.replace(/^.*::/, ''); // strip namespace prefix + t = t.replace(/[*&]/g, '').trim(); + return t; +} + +/** + * Detect whether a `namespace_definition` AST node is inline. + * Tree-sitter-cpp exposes the `inline` keyword as an anonymous child + * node — we scan direct children for that keyword. + */ +function isInlineNamespace(nsNode: SyntaxNode): boolean { + for (let i = 0; i < nsNode.childCount; i++) { + const c = nsNode.child(i); + if (c === null) continue; + if (c.type === 'inline') return true; + // Some grammar variants surface keywords by their text rather than + // by a dedicated node type; check both for resilience. + if (c.text === 'inline' && (c.type === 'storage_class_specifier' || c.type === 'inline')) { + return true; + } + } + return false; +} + +/** + * Detect `(f)(args)` shape — the call-expression's `function` field is a + * `parenthesized_expression`. ISO C++ specifies that this form suppresses + * ADL (`[basic.lookup.argdep]/3.1`): the parenthesized name is treated as + * an ordinary unqualified-lookup-only callee. + */ +function isParenthesizedFunctionCall(callNode: SyntaxNode): boolean { + const fn = callNode.childForFieldName('function'); + return fn !== null && fn.type === 'parenthesized_expression'; +} + +/** + * Per-argument ADL classification: walk each argument of a free call and + * decide whether it's a directly-named class type (V1 ADL fires) or + * something V1 excludes (pointer, reference, primitive, literal, function + * pointer, template specialization). + * + * V1 only fires for value class-typed args: `void f(N::S); N::S s; f(s);`. + * Pointer args (`N::S* p; f(p);`) intentionally return `simpleClassName=''` + * to lock the V1 boundary — the `cpp-adl-pointer-arg-boundary` fixture + * regression-tests this. + */ +function inferCppCallAdlArgs(callNode: SyntaxNode): CppAdlArgInfo[] { + const argList = callNode.childForFieldName('arguments'); + if (argList === null) return []; + const out: CppAdlArgInfo[] = []; + for (let i = 0; i < argList.childCount; i++) { + const child = argList.child(i); + if (child === null) continue; + if (child.type === ',' || child.type === '(' || child.type === ')') continue; + out.push(classifyAdlArg(child)); + } + return out; +} + +const EMPTY_ADL_ARG: CppAdlArgInfo = { simpleClassName: '', isPointer: false, isReference: false }; + +function classifyAdlArg(argNode: SyntaxNode): CppAdlArgInfo { + // Literals and primitive-shaped expressions never have associated namespaces. + if ( + argNode.type === 'number_literal' || + argNode.type === 'string_literal' || + argNode.type === 'raw_string_literal' || + argNode.type === 'char_literal' || + argNode.type === 'true' || + argNode.type === 'false' || + argNode.type === 'null' || + argNode.type === 'nullptr' + ) { + return EMPTY_ADL_ARG; + } + // Variable reference — look up its declared type (preserving pointer / + // reference / qualified-name shape; the existing arity-narrowing helper + // strips this info). + if (argNode.type === 'identifier') { + return lookupAdlIdentifierType(argNode); + } + // Other shapes (calls, member access, operators) — V1 unsupported. + return EMPTY_ADL_ARG; +} + +function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { + const varName = identNode.text; + let scope: SyntaxNode | null = identNode.parent; + while ( + scope !== null && + scope.type !== 'compound_statement' && + scope.type !== 'translation_unit' + ) { + scope = scope.parent; + } + if (scope === null) return EMPTY_ADL_ARG; + + for (let i = 0; i < scope.childCount; i++) { + const stmt = scope.child(i); + if (stmt === null || stmt.type !== 'declaration') continue; + const typeNode = stmt.childForFieldName('type'); + if (typeNode === null) continue; + if (typeNode.type === 'placeholder_type_specifier') continue; + + const declarator = stmt.childForFieldName('declarator'); + if (declarator === null) continue; + + // Unwrap declarator chain to find pointer/reference markers and the + // variable name. `init_declarator > pointer_declarator > identifier` + // means pointer-typed; `init_declarator > reference_declarator > ...` + // means reference-typed; bare `init_declarator > identifier` is value. + let isPointer = false; + let isReference = false; + let inner: SyntaxNode = declarator; + let nameText: string | null = null; + let safety = 16; // bound walk depth defensively + while (safety-- > 0) { + if (inner.type === 'pointer_declarator') { + isPointer = true; + const next = inner.childForFieldName('declarator'); + if (next === null) break; + inner = next; + continue; + } + if (inner.type === 'reference_declarator') { + isReference = true; + // reference_declarator has a single child (the inner declarator). + let next: SyntaxNode | null = null; + for (let j = 0; j < inner.namedChildCount; j++) { + const c = inner.namedChild(j); + if (c !== null) { + next = c; + break; + } + } + if (next === null) break; + inner = next; + continue; + } + if (inner.type === 'init_declarator') { + const next = inner.childForFieldName('declarator'); + if (next === null) break; + inner = next; + continue; + } + // Reached the leaf — usually `identifier`. Take its text. + nameText = inner.text; + break; + } + if (nameText !== varName) continue; + + const simpleClassName = extractAdlSimpleTypeName(typeNode); + return { simpleClassName, isPointer, isReference }; + } + return EMPTY_ADL_ARG; +} + +/** Extract the simple class-like type name from a `type:` field node. + * Returns '' for primitives, template specializations, function pointers, + * and any other shape V1 ADL doesn't support — those args are excluded + * from associated-namespace closure. */ +function extractAdlSimpleTypeName(typeNode: SyntaxNode): string { + if (typeNode.type === 'primitive_type') return ''; + if (typeNode.type === 'sized_type_specifier') return ''; + if (typeNode.type === 'type_identifier') return typeNode.text; + if (typeNode.type === 'qualified_identifier') { + const nameNode = typeNode.childForFieldName('name'); + if (nameNode !== null) return extractAdlSimpleTypeName(nameNode); + const id = findFirstDescendantOfType(typeNode, 'type_identifier'); + return id !== null ? id.text : ''; + } + // template_type (e.g. `vector`), function pointers, decltype — V1 excludes. + return ''; +} + +/** + * Check if a C++ function_definition or declaration has `static` storage class. + */ +function hasStaticStorageClass(node: SyntaxNode): boolean { + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child !== null && child.type === 'storage_class_specifier' && child.text === 'static') { + return true; + } + } + return false; +} + +/** + * Check if a node is inside an anonymous namespace (file-local linkage in C++). + * Anonymous namespaces have no `name` field in tree-sitter-cpp. + */ +function isInsideAnonymousNamespace(node: SyntaxNode): boolean { + let ancestor: SyntaxNode | null = node.parent ?? null; + while (ancestor !== null) { + if (ancestor.type === 'namespace_definition') { + // Anonymous namespace: has declaration_list but no name child + const nameChild = ancestor.childForFieldName?.('name') ?? null; + if (nameChild === null) return true; + } + ancestor = ancestor.parent; + } + return false; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/file-local-linkage.ts b/gitnexus/src/core/ingestion/languages/cpp/file-local-linkage.ts new file mode 100644 index 000000000..e46327558 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/file-local-linkage.ts @@ -0,0 +1,214 @@ +import type { ParsedFile, Scope, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import { isCppInlineNamespaceScope } from './inline-namespaces.js'; + +/** + * Per-file set of symbol names with file-local linkage. + * In C++ there are two sources of file-local linkage: + * 1. `static` storage class (same as C) + * 2. Anonymous namespace (`namespace { ... }`) + * + * Populated during `emitCppScopeCaptures` and consumed by + * `expandCppWildcardNames` to exclude file-local symbols from + * cross-file wildcard import visibility. + * + * NOTE: module-level state, single-process-single-repo use only. + * Call `clearFileLocalNames()` at the start of each resolution pass. + * + * Key: filePath, Value: Set of file-local symbol names. + */ +const fileLocalNames = new Map>(); + +/** + * Per-file set of `SymbolDefinition.nodeId`s that are NOT visible by + * unqualified lookup from outside the file — class-owned methods/fields + * and namespace-nested symbols. Populated by `populateCppNonGloballyVisible` + * during the per-file `populateOwners` hook; consumed by + * `isCppDefGloballyVisible` from both `expandCppWildcardNames` (wildcard + * propagation) and the global free-call fallback's `isFileLocalDef` hook. + * + * Tracked per filePath rather than as a single global set so cross-file + * lookup correctly compares the candidate's owning file's non-visible + * set without leaking across pipeline invocations (the global free-call + * fallback checks `def.filePath !== callerFilePath` and then asks "is + * this def visible from outside its own file?" — that's exactly what + * this set encodes). + */ +const nonGloballyVisibleNodeIds = new Map>(); + +/** Record a symbol name as file-local (static or anonymous namespace). */ +export function markFileLocal(filePath: string, name: string): void { + let names = fileLocalNames.get(filePath); + if (names === undefined) { + names = new Set(); + fileLocalNames.set(filePath, names); + } + names.add(name); +} + +/** Check whether a symbol name has file-local linkage in the given file. */ +export function isFileLocal(filePath: string, name: string): boolean { + return fileLocalNames.get(filePath)?.has(name) ?? false; +} + +/** Clear tracked file-local names (call at start of each resolution pass). */ +export function clearFileLocalNames(): void { + fileLocalNames.clear(); + nonGloballyVisibleNodeIds.clear(); +} + +/** + * Populate per-file "not globally visible" nodeIds by walking the parsed + * file's scopes. Run as part of the `populateOwners` hook so every C++ + * scope is reflected before any cross-file resolution pass consults the + * set. + * + * A def is "not globally visible" when its nearest structurally enclosing + * scope is a `Namespace` or `Class` — those require qualification + * (`ns::name`, `Class::method`) for cross-file unqualified lookup. + * Module-scoped defs remain globally visible. + */ +export function populateCppNonGloballyVisible(parsed: { + readonly filePath: string; + readonly scopes: readonly { + readonly id: ScopeId; + readonly kind: string; + readonly ownedDefs: readonly { readonly nodeId: string }[]; + }[]; +}): void { + let set = nonGloballyVisibleNodeIds.get(parsed.filePath); + if (set === undefined) { + set = new Set(); + nonGloballyVisibleNodeIds.set(parsed.filePath, set); + } + for (const scope of parsed.scopes) { + if (scope.kind !== 'Namespace' && scope.kind !== 'Class') continue; + // Inline namespaces (`inline namespace v1 { ... }`) propagate their + // members to the enclosing namespace's unqualified-lookup scope per + // ISO C++ `[namespace.def]/p4`. Skip them here so cross-file + // unqualified lookup can still see their callable defs. + if (scope.kind === 'Namespace' && isCppInlineNamespaceScope(scope.id)) continue; + for (const def of scope.ownedDefs) { + set.add(def.nodeId); + } + } +} + +/** + * Check whether a def is visible by unqualified lookup from outside its + * own file. Returns `false` for class-owned and namespace-nested defs. + * + * Used by the global free-call fallback's `isFileLocalDef` hook (which + * historically meant "static / anonymous-namespace" but semantically + * stands for "logically invisible cross-file"). Including class methods + * and namespace members under the same negative answer fixes the leak + * where unqualified `save()` resolved to `User::save` through a shared + * workspace registry walk. + */ +export function isCppDefGloballyVisible(filePath: string, nodeId: string): boolean { + return nonGloballyVisibleNodeIds.get(filePath)?.has(nodeId) !== true; +} + +/** + * Return the names visible through a C++ wildcard import (`#include` or + * `using namespace`). + * + * ## Contract + * + * C++ unqualified name lookup only sees names at the importer's enclosing + * scope. Class members and namespace-nested symbols are NOT visible by + * unqualified lookup from a free function in an including TU — they must + * be reached via `Class::method`, `ns::name`, or a working `using` + * declaration. The filter below enforces that contract for header + * propagation: only defs whose nearest enclosing scope is the header's + * `Module` scope are emitted as wildcard-binding names. + * + * ## Why scope-aware and not predicate-on-qualifiedName + * + * A naive `def.qualifiedName.indexOf('.') === -1` check is unreliable + * because `populateClassOwnedMembers` + * (`gitnexus/src/core/ingestion/scope-resolution/scope/walkers.ts`) + * only dot-qualifies `qualifiedName` for `Class` scopes. Namespace-nested + * defs (`namespace ns { void foo(); }`) arrive in `localDefs` with + * `qualifiedName === 'foo'` and `ownerId === undefined`, indistinguishable + * from a top-level free function. The structural truth lives in + * `Scope.ownedDefs`: each scope lists what it structurally owns; the + * Module scope owns only top-level symbols. We look the def up by + * `nodeId` against the scope tree to identify its owning kind. + * + * ## `localDefs` consumer survey (recorded for future maintainers) + * + * Other consumers of `ParsedFile.localDefs` were audited at the time + * this filter was introduced (see PR #1520 / plan + * `docs/plans/2026-05-12-002-fix-cpp-resolver-followups-plan.md`): + * + * - `finalize-orchestrator.ts:113,163` — flattens defs into a workspace + * registry keyed by `ownerId` + `qualifiedName`; class-owned and + * namespace-owned symbols are registered under their owner, not as + * unqualified names. Not a leak surface. + * - `csharp/namespace-siblings.ts:307`, `go/expand-wildcards.ts:86`, + * `php/scope-resolver.ts:141,151`, `c/static-linkage.ts:51` — other + * languages' own wildcard / sibling expansions. Each owns its own + * visibility contract. + * - `receiver-bound-calls.ts:99`, `reconcile-ownership.ts:66,119`, + * `mro.ts:61` — keyed by `ownerId` for member lookup, never used + * as unqualified bindings. + * - `go/interface-impls.ts:40,53`, `go/package-siblings.ts:41` — Go- + * specific, sibling-package scoped. + * + * No other consumer treats `localDefs` as a flat unqualified-binding + * set the way this function did before the fix. If a future consumer + * does, mirror this filter or harden registration so class/namespace + * members never enter `localDefs` unqualified. + */ +export function expandCppWildcardNames( + targetModuleScope: ScopeId, + parsedFiles: readonly ParsedFile[], +): readonly string[] { + const target = parsedFiles.find((p) => p.moduleScope === targetModuleScope); + if (target === undefined) return []; + + // Build nodeId → owning Scope map from the structural scope tree. + // `Scope.ownedDefs` is the canonical source of structural ownership; + // `localDefs` is its flattened union, which is why the original code + // leaked: walking only `localDefs` discards the owning-scope context. + const ownerScopeByNodeId = new Map(); + for (const scope of target.scopes) { + for (const ownedDef of scope.ownedDefs) { + ownerScopeByNodeId.set(ownedDef.nodeId, scope); + } + } + + const seen = new Set(); + const names: string[] = []; + for (const def of target.localDefs) { + // Defense-in-depth: class methods carry a non-undefined ownerId after + // `populateClassOwnedMembers` runs. Skip them outright. + if (def.ownerId !== undefined) continue; + + // Structural visibility check: exclude defs whose owning scope is a + // Namespace or Class — these require qualification (`ns::name`, + // `Class::method`) and are NOT reachable by unqualified lookup in an + // including TU. When the owning scope is unknown we default to + // include (preserves prior behavior for any def whose structural + // ownership wasn't recorded in `Scope.ownedDefs`). + const ownerScope = ownerScopeByNodeId.get(def.nodeId); + if ( + ownerScope !== undefined && + (ownerScope.kind === 'Namespace' || ownerScope.kind === 'Class') + ) { + continue; + } + + const name = simpleName(def); + if (name === '') continue; + if (isFileLocal(target.filePath, name)) continue; + if (seen.has(name)) continue; + seen.add(name); + names.push(name); + } + return names; +} + +function simpleName(def: SymbolDefinition): string { + return def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/header-scan.ts b/gitnexus/src/core/ingestion/languages/cpp/header-scan.ts new file mode 100644 index 000000000..39ef608b3 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/header-scan.ts @@ -0,0 +1,53 @@ +import { readdirSync, type Dirent } from 'fs'; +import { join, relative } from 'path'; + +/** C++ header extensions to scan for in the workspace. */ +const HEADER_EXTENSIONS = new Set(['.h', '.hpp', '.hxx', '.hh']); + +/** + * Walk `repoPath` recursively and return relative paths of all C++ header files. + * Used by `loadResolutionConfig` so the C++ resolver can resolve `#include` + * targets that live in header files. + * + * Scans for: .h, .hpp, .hxx, .hh + */ +export function scanCppHeaderFiles(repoPath: string): ReadonlySet { + const headers = new Set(); + walk(repoPath, repoPath, headers); + return headers; +} + +function walk(dir: string, root: string, out: Set): void { + let entries: Dirent[]; + try { + entries = readdirSync(dir, { withFileTypes: true, encoding: 'utf8' }); + } catch { + return; // permission denied, etc. + } + for (const entry of entries) { + const name = entry.name; + const full = join(dir, name); + if (entry.isDirectory()) { + if ( + name === 'node_modules' || + name === '.git' || + name === 'vendor' || + name === 'dist' || + name === 'build' || + name === 'out' || + name === 'target' || + name === '_build' || + name === '.next' || + name.startsWith('cmake-build') + ) { + continue; + } + walk(full, root, out); + } else if (entry.isFile()) { + const ext = name.slice(name.lastIndexOf('.')); + if (HEADER_EXTENSIONS.has(ext)) { + out.add(relative(root, full).replace(/\\/g, '/')); + } + } + } +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/import-decomposer.ts b/gitnexus/src/core/ingestion/languages/cpp/import-decomposer.ts new file mode 100644 index 000000000..eb6b252ce --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/import-decomposer.ts @@ -0,0 +1,120 @@ +import type { Capture, CaptureMatch } from 'gitnexus-shared'; +import { nodeToCapture, syntheticCapture, type SyntaxNode } from '../../utils/ast-helpers.js'; + +/** + * Decompose a `preproc_include` node into a CaptureMatch with structured + * import captures. C++ #include maps to a wildcard import (all symbols + * from the header are visible). Identical to C's splitCInclude. + */ +export function splitCppInclude(node: SyntaxNode): CaptureMatch | null { + const pathNode = node.childForFieldName?.('path') ?? null; + if (pathNode === null) { + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child === null) continue; + if (child.type === 'string_literal' || child.type === 'system_lib_string') { + return buildIncludeCapture(node, child); + } + } + return null; + } + return buildIncludeCapture(node, pathNode); +} + +function buildIncludeCapture(node: SyntaxNode, pathNode: SyntaxNode): CaptureMatch { + let raw: string; + if (pathNode.type === 'string_literal') { + const content = pathNode.namedChildren.find((c) => c.type === 'string_content'); + raw = content?.text ?? pathNode.text.replace(/^"|"$/g, ''); + } else { + raw = pathNode.text; + if (raw.startsWith('<') && raw.endsWith('>')) { + raw = raw.slice(1, -1); + } + } + + const isSystem = pathNode.type === 'system_lib_string'; + + const result: Record = { + '@import.statement': nodeToCapture('@import.statement', node), + '@import.kind': syntheticCapture('@import.kind', node, 'wildcard'), + '@import.source': syntheticCapture('@import.source', node, raw), + }; + + if (isSystem) { + result['@import.system'] = syntheticCapture('@import.system', node, 'true'); + } + + return result; +} + +/** + * Decompose a `using_declaration` node into a CaptureMatch. + * + * tree-sitter-cpp produces: + * using namespace std; → using_declaration { "using", "namespace", identifier("std"), ";" } + * using std::vector; → using_declaration { "using", qualified_identifier("std::vector"), ";" } + * + * The first form is a wildcard import (all names from namespace). + * The second form is a named import (single symbol). + */ +export function splitCppUsingDecl(node: SyntaxNode): CaptureMatch | null { + if (node.type !== 'using_declaration') return null; + + // Check for "namespace" keyword among anonymous children + let hasNamespaceKeyword = false; + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child !== null && !child.isNamed && child.text === 'namespace') { + hasNamespaceKeyword = true; + break; + } + } + + if (hasNamespaceKeyword) { + // using namespace ; + // The namespace name can be an identifier or qualified_identifier + let namespaceName: string | null = null; + for (let i = 0; i < node.namedChildCount; i++) { + const child = node.namedChild(i); + if (child === null) continue; + if (child.type === 'identifier' || child.type === 'qualified_identifier') { + namespaceName = child.text; + break; + } + } + if (namespaceName === null) return null; + + return { + '@import.statement': nodeToCapture('@import.statement', node), + '@import.kind': syntheticCapture('@import.kind', node, 'wildcard'), + '@import.source': syntheticCapture('@import.source', node, namespaceName), + '@import.using-namespace': syntheticCapture('@import.using-namespace', node, 'true'), + }; + } + + // using ; (e.g. using std::vector) + let qualId: SyntaxNode | null = null; + for (let i = 0; i < node.namedChildCount; i++) { + const child = node.namedChild(i); + if (child !== null && child.type === 'qualified_identifier') { + qualId = child; + break; + } + } + if (qualId === null) return null; + + // Extract the imported name (last identifier) and source (namespace part) + const nameNode = qualId.childForFieldName?.('name') ?? null; + const scopeNode = qualId.childForFieldName?.('scope') ?? null; + + const importedName = nameNode?.text ?? qualId.text.split('::').pop() ?? ''; + const source = scopeNode?.text ?? qualId.text.replace(new RegExp('::' + importedName + '$'), ''); + + return { + '@import.statement': nodeToCapture('@import.statement', node), + '@import.kind': syntheticCapture('@import.kind', node, 'named'), + '@import.source': syntheticCapture('@import.source', node, source), + '@import.name': syntheticCapture('@import.name', node, importedName), + }; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/import-target.ts b/gitnexus/src/core/ingestion/languages/cpp/import-target.ts new file mode 100644 index 000000000..26e317c6e --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/import-target.ts @@ -0,0 +1,18 @@ +import { resolveCImportTarget } from '../c/import-target.js'; + +/** + * Resolve a C++ #include path to a file in the workspace. + * C++ #include path resolution is identical to C: + * 1. Same-directory sibling (relative lookup) + * 2. Exact match + * 3. Suffix match with depth + lexicographic tiebreak + * + * Re-exports the C implementation since the #include semantics are shared. + */ +export function resolveCppImportTarget( + targetRaw: string, + fromFile: string, + allFilePaths: ReadonlySet, +): string | null { + return resolveCImportTarget(targetRaw, fromFile, allFilePaths); +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/index.ts b/gitnexus/src/core/ingestion/languages/cpp/index.ts new file mode 100644 index 000000000..c4d208d76 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/index.ts @@ -0,0 +1,16 @@ +/** + * C++ scope-resolution hooks (RFC #909 Ring 3). + */ +export { emitCppScopeCaptures } from './captures.js'; +export { interpretCppImport, interpretCppTypeBinding, normalizeCppTypeName } from './interpret.js'; +export { splitCppInclude, splitCppUsingDecl } from './import-decomposer.js'; +export { cppArityCompatibility } from './arity.js'; +export { cppMergeBindings } from './merge-bindings.js'; +export { cppBindingScopeFor, cppImportOwningScope, cppReceiverBinding } from './simple-hooks.js'; +export { resolveCppImportTarget } from './import-target.js'; +export { + markFileLocal, + isFileLocal, + clearFileLocalNames, + expandCppWildcardNames, +} from './file-local-linkage.js'; diff --git a/gitnexus/src/core/ingestion/languages/cpp/inline-namespaces.ts b/gitnexus/src/core/ingestion/languages/cpp/inline-namespaces.ts new file mode 100644 index 000000000..c08402a85 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/inline-namespaces.ts @@ -0,0 +1,170 @@ +/** + * C++ inline namespace support (U5 of plan 2026-05-13-001). + * + * `inline namespace v1 { void foo(); }` has two ISO C++ semantics that + * GitNexus must model: + * + * 1. **Transitive unqualified visibility.** Names declared in an inline + * namespace are reachable by unqualified lookup from the enclosing + * namespace's scope, as if they were declared directly there. + * `populateCppNonGloballyVisible` (file-local-linkage.ts) treats + * inline-namespace members as globally visible for cross-file + * unqualified lookup. + * + * 2. **Transitive qualified visibility.** `outer::foo()` resolves to + * `outer::v1::foo()` when `v1` is inline. The qualified-namespace + * receiver resolver (`resolveCppQualifiedNamespaceMember`) walks + * inline-namespace children transitively when collecting candidates. + * + * State lifecycle: capture-time `markCppInlineNamespaceRange` records each + * inline namespace's source range; `populateCppInlineNamespaceScopes` + * resolves ranges to `ScopeId`s during `populateOwners`. Cleared via + * `clearCppInlineNamespaces`, called from `clearFileLocalNames`. + * + * STL idiom this enables: `std::__1::vector` (libc++) and `std::__cxx11` + * (libstdc++) are inline namespaces of `std`. With this support, + * `std::vector` qualified calls resolve to the inline-namespace + * declaration transparently. + */ + +import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; + +interface RangeKey { + readonly startLine: number; + readonly startCol: number; + readonly endLine: number; + readonly endCol: number; +} + +const inlineNamespaceRangesByFile = new Map>(); +const inlineNamespaceScopeIds = new Set(); + +function rangeKey(r: RangeKey): string { + return `${r.startLine}:${r.startCol}:${r.endLine}:${r.endCol}`; +} + +/** Capture-time: record a namespace_definition's range as inline. + * Called from `emitCppScopeCaptures` when the tree-sitter AST shows an + * `inline` keyword child on `namespace_definition`. */ +export function markCppInlineNamespaceRange(filePath: string, range: RangeKey): void { + let set = inlineNamespaceRangesByFile.get(filePath); + if (set === undefined) { + set = new Set(); + inlineNamespaceRangesByFile.set(filePath, set); + } + set.add(rangeKey(range)); +} + +/** Clear all inline-namespace state. Called from `clearFileLocalNames`. */ +export function clearCppInlineNamespaces(): void { + inlineNamespaceRangesByFile.clear(); + inlineNamespaceScopeIds.clear(); +} + +/** Resolve captured ranges to actual ScopeIds by matching scope ranges + * against the inline-namespace ranges recorded for this file. Run from + * the cpp resolver's `populateOwners` hook so the per-pipeline Set is + * populated before any resolution pass consults it. */ +export function populateCppInlineNamespaceScopes(parsed: ParsedFile): void { + const ranges = inlineNamespaceRangesByFile.get(parsed.filePath); + if (ranges === undefined || ranges.size === 0) return; + for (const scope of parsed.scopes) { + if (scope.kind !== 'Namespace') continue; + if (ranges.has(rangeKey(scope.range))) { + inlineNamespaceScopeIds.add(scope.id); + } + } +} + +/** Predicate consumed by `populateCppNonGloballyVisible` to exempt + * inline-namespace members from cross-file unqualified-lookup + * exclusion (they remain reachable as if declared at the enclosing + * namespace's level). */ +export function isCppInlineNamespaceScope(scopeId: ScopeId): boolean { + return inlineNamespaceScopeIds.has(scopeId); +} + +/** + * Walk every parsed file looking for a Namespace scope whose qualified + * name matches `receiverName`, collect its callable ownedDefs matching + * `memberName`, transitively descending into any inline-namespace + * children (since they're members of the enclosing namespace under ISO + * C++). + * + * Returns the most specific (innermost) match — for `outer::foo()` + * where `inline namespace v1` declares `foo`, returns `v1::foo`. When + * multiple inline-namespace children declare the same name, ISO C++ + * leaves the call ambiguous; V1 returns the first match in source + * order (stable across runs). + */ +export function resolveCppQualifiedNamespaceMember( + receiverName: string, + memberName: string, + parsedFiles: readonly ParsedFile[], + _scopes: ScopeResolutionIndexes, +): SymbolDefinition | undefined { + for (const parsed of parsedFiles) { + const scopesById = new Map(); + for (const sc of parsed.scopes) scopesById.set(sc.id, sc); + for (const scope of parsed.scopes) { + if (scope.kind !== 'Namespace') continue; + const nsDef = findNamespaceDefInScope(scope); + if (nsDef === undefined) continue; + const nsName = nsDef.qualifiedName?.split('.').pop() ?? nsDef.qualifiedName ?? ''; + if (nsName !== receiverName) continue; + // Found a matching namespace scope in this file. Collect the + // member transitively through any inline-namespace children. + const hit = findMemberInNamespaceTransitive(scope, scopesById, memberName); + if (hit !== undefined) return hit; + } + } + return undefined; +} + +/** Recursively search a namespace scope and any inline-namespace + * descendants for a callable def with the given simple name. Non-inline + * nested namespaces are NOT traversed — they require explicit + * qualification (`outer::nested::foo`). */ +function findMemberInNamespaceTransitive( + scope: { + readonly id: ScopeId; + readonly ownedDefs: readonly SymbolDefinition[]; + readonly parent: ScopeId | null; + }, + scopesById: ReadonlyMap< + ScopeId, + { + readonly id: ScopeId; + readonly kind: string; + readonly parent: ScopeId | null; + readonly ownedDefs: readonly SymbolDefinition[]; + } + >, + memberName: string, +): SymbolDefinition | undefined { + // Check this scope's own ownedDefs first. + for (const def of scope.ownedDefs) { + if (def.type !== 'Function' && def.type !== 'Method' && def.type !== 'Constructor') continue; + const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; + if (simple === memberName) return def; + } + // Descend into inline-namespace children. + for (const childScope of scopesById.values()) { + if (childScope.parent !== scope.id) continue; + if (childScope.kind !== 'Namespace') continue; + if (!inlineNamespaceScopeIds.has(childScope.id)) continue; + const hit = findMemberInNamespaceTransitive(childScope, scopesById, memberName); + if (hit !== undefined) return hit; + } + return undefined; +} + +function findNamespaceDefInScope(scope: { + readonly ownedDefs: readonly SymbolDefinition[]; +}): SymbolDefinition | undefined { + for (const def of scope.ownedDefs) { + if (def.type === 'Namespace') return def; + } + return undefined; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/interpret.ts b/gitnexus/src/core/ingestion/languages/cpp/interpret.ts new file mode 100644 index 000000000..a5c1692a8 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/interpret.ts @@ -0,0 +1,112 @@ +import type { CaptureMatch, ParsedImport, ParsedTypeBinding, TypeRef } from 'gitnexus-shared'; + +/** + * Interpret a C++ import capture into a ParsedImport. + * + * C++ has three import forms: + * 1. #include "file.h" → wildcard import (all symbols from header) + * 2. using namespace X; → wildcard import (all symbols from namespace X) + * 3. using X::name; → named import (single symbol from namespace X) + * + * System headers (#include <...>) are not resolved to local files. + */ +export function interpretCppImport(captures: CaptureMatch): ParsedImport | null { + const source = captures['@import.source']?.text; + if (source === undefined) return null; + + // System headers are not resolved to local files + if (captures['@import.system'] !== undefined) return null; + + const kind = captures['@import.kind']?.text; + + if (kind === 'named') { + // using X::name — named import + const importedName = captures['@import.name']?.text; + if (importedName === undefined) return null; + return { kind: 'named', targetRaw: source, localName: importedName, importedName }; + } + + // #include or using namespace — wildcard import + return { kind: 'wildcard', targetRaw: source }; +} + +/** + * Interpret a C++ type-binding capture into a ParsedTypeBinding. + * + * Source classification (strongest → weakest): + * - `'parameter-annotation'` — function parameter type + * - `'annotation'` — explicit type declaration (`User user;`) + * - `'assignment-inferred'` — typed init (`User user = ...`) + * - `'constructor'` — constructor call (`auto u = User(...)` / `User{}`) + * - `'return'` — function return type + * - `'field'` — class field type + * - `'alias'` — `auto x = existingVar` + */ +export function interpretCppTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null { + const name = captures['@type-binding.name']?.text; + const type = captures['@type-binding.type']?.text; + if (name === undefined || type === undefined) return null; + + let source: TypeRef['source'] = 'annotation'; + + if (captures['@type-binding.parameter'] !== undefined) { + source = 'parameter-annotation'; + } else if (captures['@type-binding.constructor'] !== undefined) { + source = 'constructor-inferred'; + } else if (captures['@type-binding.return'] !== undefined) { + source = 'return-annotation'; + } else if (captures['@type-binding.field'] !== undefined) { + // Field types are structurally equivalent to annotations — the type + // is explicitly written, not inferred. + source = 'annotation'; + } else if (captures['@type-binding.member-access'] !== undefined) { + // auto addr = user.address — the type is inferred from the member access. + // Synthesize a dotted rawName ("receiver.field") so compound-receiver + // can resolve the chain: look up receiver's class, then field's type. + const receiver = captures['@type-binding.member-access-receiver']?.text; + if (receiver !== undefined) { + return { boundName: name, rawTypeName: `${receiver}.${type}`, source: 'assignment-inferred' }; + } + source = 'assignment-inferred'; + } else if (captures['@type-binding.alias'] !== undefined) { + // auto alias = existingVar — the type is inferred from the RHS variable. + source = 'assignment-inferred'; + } else if (captures['@type-binding.assignment'] !== undefined) { + source = 'assignment-inferred'; + } else if (captures['@type-binding.annotation'] !== undefined) { + source = 'annotation'; + } + + return { boundName: name, rawTypeName: normalizeCppTypeName(type), source }; +} + +/** + * Normalize a C++ type name: strip pointer/array/reference syntax, + * qualifiers, and template parameters (V1: generic-ignored). + */ +export function normalizeCppTypeName(text: string): string { + let t = text.trim(); + // Strip const, volatile, restrict, static, extern, inline, mutable, constexpr + t = t + .replace(/\b(const|volatile|restrict|static|extern|inline|mutable|constexpr|consteval)\b/g, '') + .trim(); + // Strip template parameters (loop handles nested: Map> → Map) + while (t.includes('<')) { + const stripped = t.replace(/<[^<>]*>/g, ''); + if (stripped === t) break; // avoid infinite loop on malformed input + t = stripped; + } + t = t.trim(); + // Strip pointer stars + while (t.endsWith('*')) t = t.slice(0, -1).trim(); + while (t.startsWith('*')) t = t.slice(1).trim(); + // Strip reference markers + while (t.endsWith('&')) t = t.slice(0, -1).trim(); + // Strip array brackets + t = t.replace(/\[.*?\]/g, '').trim(); + // Strip struct/union/enum/class prefixes + t = t.replace(/^(struct|union|enum|class)\s+/, ''); + // Strip leading :: (global namespace qualifier) + t = t.replace(/^::/, ''); + return t; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/merge-bindings.ts b/gitnexus/src/core/ingestion/languages/cpp/merge-bindings.ts new file mode 100644 index 000000000..6409cef46 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/merge-bindings.ts @@ -0,0 +1,38 @@ +import type { BindingRef } from 'gitnexus-shared'; + +const TIER: Record = { + local: 0, + namespace: 1, + import: 2, + reexport: 3, + wildcard: 4, +}; + +/** + * C++ merge bindings: first-wins by tier. + * + * C++ tier precedence: + * local(0) > namespace(1) > import(2) > reexport(3) > wildcard(4) + * + * Unlike C (no namespaces), C++ uses the `namespace` tier for symbols + * brought in via `using namespace X;` that are then locally referenced. + * The tier ordering ensures local definitions shadow namespace imports, + * which in turn shadow wildcard #include imports. + */ +export function cppMergeBindings( + existing: readonly BindingRef[], + incoming: readonly BindingRef[], + _scopeId: string, +): BindingRef[] { + const seen = new Set(); + return [...existing, ...incoming] + .sort( + (a, b) => + (TIER[a.origin] ?? 99) - (TIER[b.origin] ?? 99) || a.def.nodeId.localeCompare(b.def.nodeId), + ) + .filter((binding) => { + if (seen.has(binding.def.nodeId)) return false; + seen.add(binding.def.nodeId); + return true; + }); +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/query.ts b/gitnexus/src/core/ingestion/languages/cpp/query.ts new file mode 100644 index 000000000..4e451617d --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/query.ts @@ -0,0 +1,462 @@ +import Parser from 'tree-sitter'; +import CPP from 'tree-sitter-cpp'; + +const CPP_SCOPE_QUERY = ` +;; ─── Scopes ────────────────────────────────────────────────────────── +(translation_unit) @scope.module +(namespace_definition) @scope.namespace +(class_specifier) @scope.class +(struct_specifier) @scope.class +(function_definition) @scope.function +(lambda_expression) @scope.function +(compound_statement) @scope.block +(if_statement) @scope.block +(for_statement) @scope.block +(for_range_loop) @scope.block +(while_statement) @scope.block +(do_statement) @scope.block +(switch_statement) @scope.block +(case_statement) @scope.block +(try_statement) @scope.block +(catch_clause) @scope.block + +;; ─── Declarations — namespace ──────────────────────────────────────── +(namespace_definition + name: (namespace_identifier) @declaration.name) @declaration.namespace + +;; Anonymous namespace (no name child) — captured as scope only, names +;; inside are marked file-local by captures.ts. + +;; ─── Declarations — class / struct (named) ─────────────────────────── +(class_specifier + name: (type_identifier) @declaration.name + body: (field_declaration_list)) @declaration.class + +(struct_specifier + name: (type_identifier) @declaration.name + body: (field_declaration_list)) @declaration.struct + +;; ─── Declarations — class / struct inside template_declaration ─────── +(template_declaration + (class_specifier + name: (type_identifier) @declaration.name + body: (field_declaration_list)) @declaration.class) + +(template_declaration + (struct_specifier + name: (type_identifier) @declaration.name + body: (field_declaration_list)) @declaration.struct) + +;; ─── Declarations — enum ───────────────────────────────────────────── +(enum_specifier + name: (type_identifier) @declaration.name) @declaration.enum + +;; ─── Declarations — enum constants ─────────────────────────────────── +(enumerator + name: (identifier) @declaration.name) @declaration.const + +;; ─── Declarations — function definition (plain identifier) ────────── +(function_definition + declarator: (function_declarator + declarator: (identifier) @declaration.name)) @declaration.function + +;; ─── Declarations — function definition with pointer return ───────── +(function_definition + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (identifier) @declaration.name))) @declaration.function + +;; ─── Declarations — out-of-class method (qualified_identifier) ────── +(function_definition + declarator: (function_declarator + declarator: (qualified_identifier + name: (identifier) @declaration.name))) @declaration.method + +;; ─── Declarations — out-of-class method with pointer return ───────── +(function_definition + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (qualified_identifier + name: (identifier) @declaration.name)))) @declaration.method + +;; ─── Declarations — out-of-class method (destructor_name) ─────────── +(function_definition + declarator: (function_declarator + declarator: (qualified_identifier + name: (destructor_name) @declaration.name))) @declaration.method + +;; ─── Declarations — template function definition ──────────────────── +(template_declaration + (function_definition + declarator: (function_declarator + declarator: (identifier) @declaration.name)) @declaration.function) + +;; ─── Declarations — template method (qualified) ───────────────────── +(template_declaration + (function_definition + declarator: (function_declarator + declarator: (qualified_identifier + name: (identifier) @declaration.name))) @declaration.method) + +;; ─── Declarations — inline method in class body (field_identifier) ── +;; tree-sitter-cpp uses field_identifier for names inside class bodies +(function_definition + declarator: (function_declarator + declarator: (field_identifier) @declaration.name)) @declaration.method + +;; ─── Declarations — inline method with pointer return (field_identifier) ── +;; Covers: User* lookup(int id) { ... } inside a class body +;; AST: function_definition > pointer_declarator > function_declarator > field_identifier +(function_definition + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (field_identifier) @declaration.name))) @declaration.method + +;; ─── Declarations — inline method with reference return (field_identifier) ── +;; Covers: User& getRef() { ... } inside a class body +(function_definition + declarator: (reference_declarator + (function_declarator + declarator: (field_identifier) @declaration.name))) @declaration.method + +;; ─── Declarations — function prototype (forward declaration) ──────── +(declaration + declarator: (function_declarator + declarator: (identifier) @declaration.name)) @declaration.function + +;; ─── Declarations — function prototype with pointer return ────────── +(declaration + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (identifier) @declaration.name))) @declaration.function + +;; ─── Declarations — typedef ───────────────────────────────────────── +(type_definition + declarator: (type_identifier) @declaration.name) @declaration.typedef + +;; ─── Declarations — type alias (using Name = Type) ────────────────── +(alias_declaration + name: (type_identifier) @declaration.name) @declaration.typedef + +;; ─── Declarations — method prototype in class body (forward decl) ──── +;; Covers: class User { void save(); std::string getName(); }; +;; AST: field_declaration > function_declarator > field_identifier +(field_declaration + declarator: (function_declarator + declarator: (field_identifier) @declaration.name)) @declaration.method + +;; Method prototype with pointer return: User* lookup(int id); +(field_declaration + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (field_identifier) @declaration.name))) @declaration.method + +;; Method prototype with reference return: User& getRef(); +(field_declaration + declarator: (reference_declarator + (function_declarator + declarator: (field_identifier) @declaration.name))) @declaration.method + +;; ─── Declarations — fields ────────────────────────────────────────── +(field_declaration + declarator: (field_identifier) @declaration.name) @declaration.field + +;; Declarations — fields (pointer) +(field_declaration + declarator: (pointer_declarator + declarator: (field_identifier) @declaration.name)) @declaration.field + +;; Declarations — fields (reference) +(field_declaration + declarator: (reference_declarator + (field_identifier) @declaration.name)) @declaration.field + +;; ─── Declarations — variables (with initializer) ──────────────────── +(declaration + declarator: (init_declarator + declarator: (identifier) @declaration.name)) @declaration.variable + +;; ─── Declarations — macro definitions ─────────────────────────────── +(preproc_def + name: (identifier) @declaration.name) @declaration.macro + +(preproc_function_def + name: (identifier) @declaration.name) @declaration.macro + +;; ─── Imports — #include ───────────────────────────────────────────── +(preproc_include) @import.statement + +;; ─── Imports — using declaration ───────────────────────────────────── +;; Both "using namespace std;" and "using std::vector;" are +;; using_declaration nodes in tree-sitter-cpp. The captures.ts +;; differentiates between them by checking for a "namespace" anonymous +;; child token. +(using_declaration) @import.using-decl + +;; ─── Type bindings — parameter annotations ────────────────────────── +(parameter_declaration + type: (_) @type-binding.type + declarator: (identifier) @type-binding.name) @type-binding.parameter + +;; Type bindings — reference parameter (const std::string& name) +(parameter_declaration + type: (_) @type-binding.type + declarator: (reference_declarator + (identifier) @type-binding.name)) @type-binding.parameter + +;; Type bindings — pointer parameter (User* ptr) +(parameter_declaration + type: (_) @type-binding.type + declarator: (pointer_declarator + declarator: (identifier) @type-binding.name)) @type-binding.parameter + +;; ─── Type bindings — variable with type (init_declarator) ─────────── +;; Covers: User user("alice"), User user = ..., int x = 0 +(declaration + type: (_) @type-binding.type + declarator: (init_declarator + declarator: (identifier) @type-binding.name)) @type-binding.assignment + +;; ─── Type bindings — plain declaration (no initializer) ───────────── +;; Covers: User user; +(declaration + type: (type_identifier) @type-binding.type + declarator: (identifier) @type-binding.name) @type-binding.annotation + +;; ─── Type bindings — pointer variable declaration ─────────────────── +;; Covers: User* ptr = new User() +(declaration + type: (type_identifier) @type-binding.type + declarator: (init_declarator + declarator: (pointer_declarator + declarator: (identifier) @type-binding.name))) @type-binding.annotation + +;; ─── Type bindings — auto + constructor call ──────────────────────── +;; Covers: auto user = User("alice") +;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + call_expression > identifier +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (call_expression + function: (identifier) @type-binding.type))) @type-binding.constructor + +;; ─── Type bindings — auto + brace-init (compound_literal_expression) ─ +;; Covers: auto user = User{}, auto user = User{args} +;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + compound_literal_expression > type_identifier +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (compound_literal_expression + type: (type_identifier) @type-binding.type))) @type-binding.constructor + +;; ─── Type bindings — auto + scoped brace-init (qualified) ─────────── +;; Covers: auto client = ns::HttpClient{} +;; AST: compound_literal_expression > qualified_identifier > type_identifier +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (compound_literal_expression + type: (qualified_identifier + name: (type_identifier) @type-binding.type)))) @type-binding.constructor + +;; ─── Type bindings — auto + new expression ────────────────────────── +;; Covers: auto user = new User(name) +;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + new_expression > type_identifier +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (new_expression + type: (type_identifier) @type-binding.type))) @type-binding.constructor + +;; ─── Type bindings — auto + qualified template factory (std::make_shared()) ─ +;; AST: declaration(1 > placeholder_type_specifier(2)2 > init_declarator(3 > +;; identifier(4)4 > call_expression(5 > qualified_identifier(6 > +;; template_function(7 > template_argument_list(8 > type_descriptor(9 > +;; type_identifier(10)10 )9 )8 )7 )6 )5 )3 )1 +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (call_expression + function: (qualified_identifier + name: (template_function + arguments: (template_argument_list + (type_descriptor + type: (type_identifier) @type-binding.type))))))) @type-binding.constructor + +;; ─── Type bindings — auto + bare template factory (make_shared()) ─────── +;; Same but without qualified_identifier wrapper — one fewer nesting level +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (call_expression + function: (template_function + arguments: (template_argument_list + (type_descriptor + type: (type_identifier) @type-binding.type)))))) @type-binding.constructor + +;; ─── Type bindings — auto alias assignment ────────────────────────── +;; Covers: auto alias = existingVar (RHS is a plain identifier) +;; AST: declaration > placeholder_type_specifier/auto > init_declarator > identifier + identifier +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (identifier) @type-binding.type)) @type-binding.alias + +;; ─── Type bindings — auto + member access (field_expression) ──────── +;; Covers: auto addr = user.address (RHS is obj.field) +;; AST: declaration > placeholder_type_specifier > init_declarator > identifier + field_expression +;; We capture the field name as @type-binding.type so the compound-receiver +;; chain resolver can look it up on the receiver class scope. +;; The full obj.field text is synthesized by interpret.ts into a dotted +;; rawName for chain-follow resolution. +(declaration + type: (placeholder_type_specifier) + declarator: (init_declarator + declarator: (identifier) @type-binding.name + value: (field_expression + argument: (_) @type-binding.member-access-receiver + field: (field_identifier) @type-binding.type))) @type-binding.member-access + +;; ─── Type bindings — function return type ─────────────────────────── +;; Covers: User getUser() { ... } +;; AST: function_definition > type_identifier + function_declarator > identifier +(function_definition + type: (type_identifier) @type-binding.type + declarator: (function_declarator + declarator: (identifier) @type-binding.name)) @type-binding.return + +;; Return type — out-of-class method: User Class::getUser() { ... } +(function_definition + type: (type_identifier) @type-binding.type + declarator: (function_declarator + declarator: (qualified_identifier + name: (identifier) @type-binding.name))) @type-binding.return + +;; Return type — pointer return: User* getUser() { ... } +(function_definition + type: (type_identifier) @type-binding.type + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (identifier) @type-binding.name))) @type-binding.return + +;; ─── Type bindings — inline method return type ────────────────────── +;; Covers: class Foo { User getUser() { ... } }; +(function_definition + type: (type_identifier) @type-binding.type + declarator: (function_declarator + declarator: (field_identifier) @type-binding.name)) @type-binding.return + +;; Inline method pointer return type: class Foo { User* lookup(int) { ... } }; +(function_definition + type: (type_identifier) @type-binding.type + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (field_identifier) @type-binding.name))) @type-binding.return + +;; ─── Type bindings — method prototype return type in class body ────── +;; Covers: class User { User* lookup(int); std::string getName(); }; +;; AST: field_declaration > function_declarator > field_identifier +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (function_declarator + declarator: (field_identifier) @type-binding.name)) @type-binding.return + +;; Method prototype pointer return type: User* lookup(int id); +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (pointer_declarator + declarator: (function_declarator + declarator: (field_identifier) @type-binding.name))) @type-binding.return + +;; ─── Type bindings — field type declarations (class members) ──────── +;; Covers: class User { Address address; }; +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (field_identifier) @type-binding.name) @type-binding.field + +;; Field pointer type: Address* address; +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (pointer_declarator + declarator: (field_identifier) @type-binding.name)) @type-binding.field + +;; Field reference type: Address& address; +(field_declaration + type: (type_identifier) @type-binding.type + declarator: (reference_declarator + (field_identifier) @type-binding.name)) @type-binding.field + +;; ─── References — constructor calls (new Foo()) ───────────────────── +(new_expression + type: (type_identifier) @reference.name) @reference.call.constructor + +;; Constructor call with qualified type: new ns::Foo() +(new_expression + type: (qualified_identifier + name: (type_identifier) @reference.name)) @reference.call.constructor + +;; ─── References — free calls ──────────────────────────────────────── +(call_expression + function: (identifier) @reference.name) @reference.call.free + +;; ─── References — qualified calls (Namespace func or Class method) ─── +;; Capture the LHS of scope-resolution as the explicit receiver so +;; qualified static member calls route through receiver-bound-calls +;; Case 2 (class-name receiver) path. Without the receiver capture, +;; qualified calls have no explicit receiver and class methods cannot +;; resolve through receiver-bound paths. +(call_expression + function: (qualified_identifier + scope: (_) @reference.receiver + name: (identifier) @reference.name)) @reference.call.qualified + +;; ─── References — member calls (obj.method() / ptr->method()) ─────── +(call_expression + function: (field_expression + argument: (_) @reference.receiver + field: (field_identifier) @reference.name)) @reference.call.member + +;; ─── References — template calls (func()) ──────────────────────── +(call_expression + function: (template_function + name: (identifier) @reference.name)) @reference.call.free + +;; Note: Ns::func() is parsed as qualified_identifier by tree-sitter-cpp, +;; already captured by the qualified calls pattern above. + +;; ─── References — field reads ─────────────────────────────────────── +(field_expression + argument: (_) @reference.receiver + field: (field_identifier) @reference.name) @reference.read + +;; ─── References — field writes (assignment) ───────────────────────── +(assignment_expression + left: (field_expression + argument: (_) @reference.receiver + field: (field_identifier) @reference.name)) @reference.write +`; + +let _parser: Parser | null = null; +let _query: Parser.Query | null = null; + +export function getCppParser(): Parser { + if (_parser === null) { + _parser = new Parser(); + _parser.setLanguage(CPP as Parameters[0]); + } + return _parser; +} + +export function getCppScopeQuery(): Parser.Query { + if (_query === null) { + _query = new Parser.Query(CPP as Parameters[0], CPP_SCOPE_QUERY); + } + return _query; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/range-bindings.ts b/gitnexus/src/core/ingestion/languages/cpp/range-bindings.ts new file mode 100644 index 000000000..204d1ab21 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/range-bindings.ts @@ -0,0 +1,255 @@ +import type { ParsedFile, Scope, TypeRef } from 'gitnexus-shared'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; +import { getCppParser } from './query.js'; +import { getTreeSitterBufferSize } from '../../constants.js'; +import { parseSourceSafe } from '../../../tree-sitter/safe-parse.js'; + +/** + * Populate range-for loop variable type bindings for C++. + * + * Handles three patterns: + * 1. `for (auto& user : users)` — simple range-for + * 2. `for (auto& [key, user] : userMap)` — structured binding + * 3. `for (auto& user : *usersPtr)` — dereference range-for + * + * Strategy: look up the range source variable's type in scope + * typeBindings, extract the last template argument as the element + * type, and inject a typeBinding for the loop variable. + */ +export function populateCppRangeBindings( + parsedFiles: readonly ParsedFile[], + _indexes: ScopeResolutionIndexes, + ctx: { + readonly fileContents: ReadonlyMap; + readonly treeCache?: { get(filePath: string): unknown }; + }, +): void { + const parser = getCppParser(); + + for (const parsed of parsedFiles) { + const sourceText = ctx.fileContents.get(parsed.filePath); + if (sourceText === undefined) continue; + + const cachedTree = ctx.treeCache?.get(parsed.filePath); + const tree = + (cachedTree as ReturnType | undefined) ?? + parseSourceSafe(parser, sourceText, undefined, { + bufferSize: getTreeSitterBufferSize(sourceText), + }); + + const moduleScope = parsed.scopes.find((s) => s.kind === 'Module'); + if (moduleScope === undefined) continue; + + const scopeMap = new Map(parsed.scopes.map((s) => [s.id, s])); + + // Build a map from parameter name → AST parameter_declaration node + // so we can extract the un-normalized template type from the AST. + const paramTypeMap = buildParamTemplateMap(tree.rootNode); + + for (const rangeNode of tree.rootNode.descendantsOfType('for_range_loop')) { + // Get the declarator (loop variable) + const declarator = rangeNode.childForFieldName('declarator'); + if (declarator === null) continue; + + // Get the range source expression (right side of ':') + const right = rangeNode.childForFieldName('right'); + if (right === null) continue; + + // Determine the loop variable name(s) and whether this is a structured binding + const varNames = extractLoopVarNames(declarator); + if (varNames.length === 0) continue; + + // Determine the range source variable name (handle dereference) + const sourceVarName = extractSourceVarName(right); + if (sourceVarName === null) continue; + + // Look up the source variable's full template type from the AST + // (scope typeBindings have been normalized and lost template params) + const fullType = paramTypeMap.get(sourceVarName); + if (fullType === undefined) continue; + + // Extract element type from the container type + const elementType = extractCppElementType(fullType); + if (elementType === null) continue; + + // Find the enclosing function scope + const functionScope = findEnclosingFunctionScope(rangeNode, scopeMap); + const targetScope = functionScope ?? moduleScope; + const mutable = targetScope.typeBindings as Map; + + // For structured binding [key, user], bind the last identifier to the element type + // For simple range-for, bind the single variable + const bindVar = varNames[varNames.length - 1]; + mutable.set(bindVar, { + rawName: elementType, + declaredAtScope: targetScope.id, + source: 'annotation', + }); + } + } +} + +/** Minimal tree-sitter node shape needed by range-binding helpers. */ +interface TsNode { + readonly type: string; + readonly text: string; + readonly childCount: number; + child(index: number): TsNode | null; + descendantsOfType(type: string): readonly TsNode[]; + childForFieldName(name: string): TsNode | null; +} + +/** + * Build a map from parameter name → full (un-normalized) type text + * by walking the AST for all `parameter_declaration` nodes. + * + * This bypasses `normalizeCppTypeName` which strips template params, + * giving us the raw `std::vector` text needed for element-type + * extraction. + */ +function buildParamTemplateMap(rootNode: TsNode): Map { + const map = new Map(); + for (const paramNode of rootNode.descendantsOfType('parameter_declaration')) { + const typeNode = paramNode.childForFieldName('type'); + if (typeNode === null) continue; + + // Extract the parameter name from the declarator subtree. + // The declarator may be: identifier, reference_declarator > identifier, + // or pointer_declarator > identifier. + const declNode = paramNode.childForFieldName('declarator'); + if (declNode === null) continue; + + const idents = declNode.descendantsOfType('identifier'); + if (idents.length === 0) continue; + const paramName = idents[idents.length - 1].text; + + // Use the full type node text (preserving template params) + map.set(paramName, typeNode.text); + } + return map; +} + +/** + * Extract loop variable name(s) from the declarator node. + * Handles both simple `identifier` and `structured_binding_declarator`. + */ +function extractLoopVarNames(declarator: TsNode): string[] { + // The declarator is typically reference_declarator or pointer_declarator wrapping + // either an identifier or a structured_binding_declarator. + const structBindings = declarator.descendantsOfType('structured_binding_declarator'); + if (structBindings.length > 0) { + // structured_binding_declarator contains identifiers like [key, user] + const idents = structBindings[0].descendantsOfType('identifier'); + return idents.map((id) => id.text).filter((t) => t !== '_'); + } + + // Simple case: reference_declarator > identifier or just identifier + const idents = declarator.descendantsOfType('identifier'); + if (idents.length > 0) { + return [idents[idents.length - 1].text]; + } + + return []; +} + +/** + * Extract the source variable name from the range expression. + * Handles plain identifiers and dereference expressions (*ptr). + */ +function extractSourceVarName(right: TsNode): string | null { + if (right.type === 'identifier') { + return right.text; + } + if (right.type === 'pointer_expression') { + // *usersPtr → get the argument (usersPtr) + const arg = right.childForFieldName('argument'); + if (arg !== null) return arg.text; + } + return null; +} + +/** + * Extract the element type from a C++ container type string. + * + * Examples: + * - `vector` → `User` + * - `std::vector` → `User` + * - `map` → `User` (last template arg) + * - `map` → `User` + * + * For structured bindings with maps, the last template arg is the value type. + * For vectors/sets, the first (and only) template arg is the element type. + */ +function extractCppElementType(rawType: string): string | null { + // Find the outermost template argument list + const ltIdx = rawType.indexOf('<'); + if (ltIdx === -1) return null; + + // Extract the template argument string (handle nested templates) + let depth = 0; + let lastCommaOrStart = ltIdx + 1; + let lastArg = ''; + + for (let i = ltIdx; i < rawType.length; i++) { + const ch = rawType[i]; + if (ch === '<') { + depth++; + } else if (ch === '>') { + depth--; + if (depth === 0) { + lastArg = rawType.slice(lastCommaOrStart, i).trim(); + break; + } + } else if (ch === ',' && depth === 1) { + lastCommaOrStart = i + 1; + } + } + + if (lastArg === '') return null; + + // Strip pointer/reference qualifiers and const + let elementType = lastArg + .replace(/^const\s+/, '') + .replace(/\s*[*&]+\s*$/, '') + .trim(); + + // Strip namespace prefix (std::string → string) + const lastColon = elementType.lastIndexOf('::'); + if (lastColon !== -1) { + elementType = elementType.slice(lastColon + 2); + } + + return elementType || null; +} + +/** + * Find the enclosing Function scope for a tree-sitter node by + * walking up the AST and matching source positions. + */ +function findEnclosingFunctionScope( + node: unknown, + scopeMap: ReadonlyMap, +): Scope | null { + const tsNode = node as { + readonly parent: unknown; + readonly type: string; + readonly startPosition: { readonly row: number; readonly column: number }; + }; + let current: typeof tsNode | null = tsNode; + while (current !== null) { + if (current.type === 'function_definition') { + for (const scope of scopeMap.values()) { + if ( + scope.kind === 'Function' && + scope.range.startLine === current.startPosition.row && + scope.range.startCol === current.startPosition.column + ) { + return scope; + } + } + break; + } + current = (current.parent as typeof tsNode) ?? null; + } + return null; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts new file mode 100644 index 000000000..a85e5b113 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts @@ -0,0 +1,230 @@ +import type { ParsedFile, SymbolDefinition } from 'gitnexus-shared'; +import { + findClassBindingInScope, + findEnclosingClassDef, +} from '../../scope-resolution/scope/walkers.js'; +import { SupportedLanguages } from 'gitnexus-shared'; +import { buildMro, defaultLinearize } from '../../scope-resolution/passes/mro.js'; +import { populateClassOwnedMembers } from '../../scope-resolution/scope/walkers.js'; +import type { ScopeResolver } from '../../scope-resolution/contract/scope-resolver.js'; +import { cppProvider } from '../c-cpp.js'; +import { cppArityCompatibility } from './arity.js'; +import { cppMergeBindings } from './merge-bindings.js'; +import { resolveCppImportTarget } from './import-target.js'; +import { scanCppHeaderFiles } from './header-scan.js'; +import { + expandCppWildcardNames, + isFileLocal, + clearFileLocalNames, + populateCppNonGloballyVisible, + isCppDefGloballyVisible, +} from './file-local-linkage.js'; +import { + populateCppDependentBases, + clearCppDependentBases, + isCppDependentBaseMember, +} from './two-phase-lookup.js'; +import { + populateCppAssociatedNamespaces, + clearCppAdlState, + pickCppAdlCandidates, + ADL_AMBIGUOUS, +} from './adl.js'; +import { + clearCppInlineNamespaces, + populateCppInlineNamespaceScopes, + resolveCppQualifiedNamespaceMember, +} from './inline-namespaces.js'; +import { populateCppRangeBindings } from './range-bindings.js'; + +/** + * C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by + * the generic `runScopeResolution` orchestrator (RFC #909 Ring 3). + * + * C++ extends C's scope resolution with: + * - Namespaces (`namespace foo { ... }`) + * - Classes with methods and multiple inheritance + * - `using namespace` (wildcard import from namespace) + * - `using X::name` (named import from namespace) + * - Anonymous namespace (file-local linkage, like C `static`) + * - Default parameters (requiredParameterCount < parameterCount) + * - Overloading (arity-based disambiguation) + * - Templates (V1: generic-ignored, `List` ≡ `List`) + * - Leftmost-base MRO for multiple inheritance + */ +export const cppScopeResolver: ScopeResolver = { + language: SupportedLanguages.CPlusPlus, + languageProvider: cppProvider, + importEdgeReason: 'cpp-scope: include', + + loadResolutionConfig: (repoPath: string) => { + // Clear stale per-pipeline state from any previous invocation. + clearFileLocalNames(); + clearCppDependentBases(); + clearCppAdlState(); + clearCppInlineNamespaces(); + return scanCppHeaderFiles(repoPath); + }, + + resolveImportTarget: (targetRaw, fromFile, allFilePaths, resolutionConfig) => { + // Augment allFilePaths with header files discovered via loadResolutionConfig. + // C++ .h/.hpp/.hxx/.hh files may be classified differently by language + // detection but are importable from .cpp files via #include. + const headerPaths = resolutionConfig as ReadonlySet | undefined; + if (headerPaths !== undefined && headerPaths.size > 0) { + const augmented = new Set(allFilePaths); + for (const h of headerPaths) augmented.add(h); + return resolveCppImportTarget(targetRaw, fromFile, augmented); + } + return resolveCppImportTarget(targetRaw, fromFile, allFilePaths); + }, + + expandsWildcardTo: (targetModuleScope, parsedFiles) => + expandCppWildcardNames(targetModuleScope, parsedFiles), + + mergeBindings: (existing, incoming, scopeId) => cppMergeBindings(existing, incoming, scopeId), + + // Adapter: cppArityCompatibility predates ScopeResolver and uses + // (def, callsite). ScopeResolver contract is (callsite, def). + arityCompatibility: (callsite, def) => cppArityCompatibility(def, callsite), + + buildMro: (graph, parsedFiles, nodeLookup) => + buildMro(graph, parsedFiles, nodeLookup, defaultLinearize), + + populateOwners: (parsed: ParsedFile) => { + populateClassOwnedMembers(parsed); + // Resolve inline-namespace ranges (recorded at capture time) to + // ScopeIds BEFORE `populateCppNonGloballyVisible` runs, so the + // inline-namespace exemption sees the populated Set. + populateCppInlineNamespaceScopes(parsed); + // Track namespace-nested and class-nested defs so the global free-call + // fallback and wildcard expansion can suppress them as unqualified + // cross-file callables. + populateCppNonGloballyVisible(parsed); + // Resolve recorded template-class → dependent-base simple names to + // class nodeIds for two-phase template lookup (U3 of plan + // 2026-05-13-001). + populateCppDependentBases(parsed); + // Build the class-def → enclosing-namespace-qualified-name map used + // by ADL (U2 of plan 2026-05-13-001) to identify each argument type's + // associated namespace for Koenig lookup. + populateCppAssociatedNamespaces(parsed); + }, + + // Simple `isSuperReceiver` returns false for C++. Real super + // classification is caller-context-dependent and lives in + // `isSuperReceiverInContext` below — without scope context the + // previous regex `/^[A-Z]\w*::/` misclassified namespace-qualified + // calls (e.g., `Singleton::getInstance()`) as super calls and routed + // them through the wrong resolution branch. + isSuperReceiver: () => false, + + isSuperReceiverInContext: (text, callerScope, scopes) => { + // The receiver text comes from the LHS of `::` in `qualified_identifier` + // (e.g., for `Base::method()`, text is `Base`). Strip template + // arguments (V1: name-only matching, generics ignored) and any leading + // namespace qualifier so the lookup matches the bare class def's + // simple name. `Base::method()` → `Base`; `outer::v1::Base` → + // `Base`. This handles the Phase 5 cross-unit composition where + // qualified base-method calls appear inside template bodies. + let lhs = text; + const sepIdx = lhs.indexOf('::'); + if (sepIdx > 0) lhs = lhs.slice(0, sepIdx).trim(); + // Strip trailing template-argument list (greedy: drop everything from + // the first `<` onward — V1 ignores generics). + const lt = lhs.indexOf('<'); + if (lt > 0) lhs = lhs.slice(0, lt).trim(); + // Strip nested namespace prefix from the receiver text itself (the + // `outer::v1::Base` shape that appears in derived-list `base_class_clause`). + const lastDoubleColon = lhs.lastIndexOf('::'); + if (lastDoubleColon >= 0) lhs = lhs.slice(lastDoubleColon + 2).trim(); + if (lhs.length === 0) return false; + + // Resolve the LHS in the caller's scope chain. Only class-like + // resolutions can be super receivers; Namespace and unresolved + // names are not super calls. + const lhsDef = findClassBindingInScope(callerScope, lhs, scopes); + if (lhsDef === undefined) return false; + + // The caller must have an enclosing class — super calls only make + // sense inside a class body. Free functions can use `ClassName::` + // for namespace-qualified calls but those are not super. + const enclosing = findEnclosingClassDef(callerScope, scopes); + if (enclosing === undefined) return false; + + // `lhsDef` must be in the caller's MRO (i.e., the caller's enclosing + // class derives from it). The class itself counts as its own MRO + // root — `Self::method()` is a qualified self-call, not a super + // call, so exclude the caller's own class. + if (lhsDef.nodeId === enclosing.nodeId) return false; + const mro = scopes.methodDispatch.mroFor(enclosing.nodeId); + return mro.includes(lhsDef.nodeId); + }, + + // C++ is statically typed — disable field fallback heuristic + fieldFallbackOnMethodLookup: false, + // C++ needs return type propagation across #include boundaries + propagatesReturnTypesAcrossImports: true, + // C++ #include brings in all symbols — enable global free call fallback + allowGlobalFreeCallFallback: true, + // Range-for element type inference: for (auto& user : users) → bind user to User + populateRangeBindings: populateCppRangeBindings, + // C++ method return-type bindings need to be visible from module scope + // for cross-file propagation and compound-receiver chain resolution. + // cppBindingScopeFor hoists @type-binding.return to Module scope. + hoistTypeBindingsToModule: true, + // The `isFileLocalDef` hook on the global free-call fallback names + // file-local linkage historically, but semantically gates "logically + // invisible cross-file" defs. C++ extends this to also reject class- + // owned methods/fields and namespace-nested symbols — an unqualified + // call from a free function MUST NOT resolve to `User::save` or + // `ns::foo` (Cppreference, "Unqualified name lookup"). Without this + // gate, the global fallback walks every callable in the workspace + // registry and matches any class method or namespace function by + // simple name. + isFileLocalDef: (def: SymbolDefinition) => { + const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; + if (isFileLocal(def.filePath, simple)) return true; + // Class-owned (Method/Field) — `populateClassOwnedMembers` already + // stamps `ownerId`; cheap fast-path before consulting the scope map. + if (def.ownerId !== undefined) return true; + // Namespace-nested defs — require qualification cross-file. Scope- + // walked at `populateOwners` time into a per-file nodeId set. + if (!isCppDefGloballyVisible(def.filePath, def.nodeId)) return true; + return false; + }, + + // C++ two-phase template lookup: inside a class template body, + // unqualified calls MUST NOT bind to members of a dependent base + // class. The standard requires `this->name()` or `Base::name()` + // forms to make the lookup dependent. Without this gate the global + // free-call fallback walks the workspace registry and silently binds + // unqualified calls to dependent-base members, producing CALLS edges + // the compiler would reject. See plan 2026-05-13-001 U3. + isCallableVisibleFromCaller: ({ candidate, callerScope, scopes }) => { + if (callerScope === undefined || scopes === undefined) return true; + // Reject when the candidate is a member of a dependent base of the + // caller's enclosing template class. Otherwise allow. + return !isCppDependentBaseMember(callerScope, candidate, scopes); + }, + + // C++ argument-dependent / Koenig lookup (U2 of plan 2026-05-13-001). + // Fires after `findCallableBindingInScope` returns undefined; surfaces + // candidates from the associated namespaces of class-typed arguments. + // V1 limitation: only direct enclosing-namespace closure for value + // class-typed args; pointer/reference/template-spec args excluded. + resolveAdlCandidates: (site, callerParsed, scopes, parsedFiles) => { + const result = pickCppAdlCandidates(site, callerParsed, scopes, parsedFiles); + if (result === ADL_AMBIGUOUS) return 'ambiguous'; + return result; + }, + + // C++ qualified namespace-member resolution (U5 of plan 2026-05-13-001). + // Handles `outer::foo()` where `outer` is a namespace (not a class). + // Walks each parsed file's namespace scopes by simple name, then + // descends transitively through inline-namespace children when + // searching for the called member. Returns undefined for non-namespace + // receivers so receiver-bound-calls Case 2 still gets a chance. + resolveQualifiedReceiverMember: (receiverName, memberName, _callerScope, scopes, parsedFiles) => + resolveCppQualifiedNamespaceMember(receiverName, memberName, parsedFiles, scopes), +}; diff --git a/gitnexus/src/core/ingestion/languages/cpp/simple-hooks.ts b/gitnexus/src/core/ingestion/languages/cpp/simple-hooks.ts new file mode 100644 index 000000000..63500abd5 --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/simple-hooks.ts @@ -0,0 +1,79 @@ +import type { + CaptureMatch, + ParsedImport, + Scope, + ScopeId, + ScopeTree, + TypeRef, +} from 'gitnexus-shared'; + +/** + * C++ binding scope: default auto-hoist (null) for most declarations. + * + * For `for` statement init-scope variables (e.g. `for (int i = 0; ...)`), + * the variable is scoped to the for-block, not the enclosing function. + * The tree-sitter scope query already captures for_statement as @scope.block, + * so tree-sitter's scope nesting handles this automatically — we return null + * to let the default auto-hoist apply. + */ +export function cppBindingScopeFor( + decl: CaptureMatch, + innermost: Scope, + tree: ScopeTree, +): ScopeId | null { + // Hoist return-type bindings to Module scope so: + // 1. propagateImportedReturnTypes can mirror them across files + // 2. compound-receiver can find method return types via hoistTypeBindingsToModule + if (decl['@type-binding.return'] !== undefined) { + let cur: Scope | undefined = innermost; + while (cur !== undefined && cur.kind !== 'Module') { + const parentId: ScopeId | null = cur.parent ?? null; + if (parentId === null) break; + cur = tree.getScope(parentId); + } + if (cur !== undefined && cur.kind === 'Module') return cur.id; + } + return null; // default auto-hoist for other bindings +} + +/** + * C++ import owning scope: default (null). + * #include and using declarations are file-scoped in C++. + */ +export function cppImportOwningScope( + _imp: ParsedImport, + _innermost: Scope, + _tree: ScopeTree, +): ScopeId | null { + return null; +} + +/** + * C++ receiver binding: return `this` TypeRef for methods inside a class. + * + * When a function scope is inside a class scope, the implicit `this` pointer + * refers to the enclosing class. This enables `this->method()` and implicit + * `this` member access resolution. + */ +export function cppReceiverBinding(functionScope: Scope): TypeRef | null { + // Walk up the scope tree to find an enclosing class scope + if (functionScope.parent === null) return null; + + // The scope tree structure nests function scopes inside class scopes. + // The orchestrator provides the function scope; we need to check if + // its parent chain contains a class scope. + // + // However, the ScopeResolver.receiverBinding contract receives only + // the function Scope (not the full ScopeTree), and the Scope type + // includes `parent` (a ScopeId) but not a reference to the parent + // Scope object. + // + // The orchestrator already handles this by looking up the class owner + // via populateOwners. We return null here and let the shared infra + // handle receiver resolution through the class-ownership mechanism. + // + // This is consistent with how C# and Go handle it — the receiver + // binding is established through populateOwners + the MRO chain, + // not through this hook. + return null; +} diff --git a/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts b/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts new file mode 100644 index 000000000..7840ed81a --- /dev/null +++ b/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts @@ -0,0 +1,133 @@ +/** + * 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::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 the workspace registry, building the per-class set the + * `isDependentBaseMember` predicate consumes. + * + * NOTE: module-level state, single-process-single-repo use only. + * `clearFileLocalNames()` clears this state alongside file-local linkage + * (see `file-local-linkage.ts`). + */ + +import type { ParsedFile, ScopeId, SymbolDefinition } from 'gitnexus-shared'; +import type { ScopeResolutionIndexes } from '../../model/scope-resolution-indexes.js'; +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> + */ +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: string, className: string, baseName: string): void { + 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(): void { + dependentBasesByFile.clear(); + dependentBaseNodeIds.clear(); +} + +/** + * Resolve recorded dependent-base simple names to class nodeIds using + * the parsed file's localDefs. Run as part of `populateOwners` so the + * resolved set is available before any resolution pass consults it. + * + * Matches by simple name within the same file (the template class and + * its base are typically declared in the same TU; cross-file template + * bases are an edge case deferred to V2). + */ +export function populateCppDependentBases(parsed: ParsedFile): void { + const perFile = dependentBasesByFile.get(parsed.filePath); + if (perFile === undefined) return; + + // Build simple-name → nodeId index for this file's class-like defs. + const classByName = new Map(); + for (const def of parsed.localDefs) { + if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue; + const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; + if (simple !== '') classByName.set(simple, def.nodeId); + } + + for (const [className, baseNames] of perFile) { + const classNodeId = classByName.get(className); + if (classNodeId === undefined) continue; + let bases = dependentBaseNodeIds.get(classNodeId); + if (bases === undefined) { + bases = new Set(); + dependentBaseNodeIds.set(classNodeId, bases); + } + for (const baseName of baseNames) { + const baseNodeId = classByName.get(baseName); + if (baseNodeId !== undefined) bases.add(baseNodeId); + } + } +} + +/** + * 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::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: ScopeId, + candidateDef: SymbolDefinition, + scopes: ScopeResolutionIndexes, +): boolean { + 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); +} diff --git a/gitnexus/src/core/ingestion/registry-primary-flag.ts b/gitnexus/src/core/ingestion/registry-primary-flag.ts index 6818007a3..869157adb 100644 --- a/gitnexus/src/core/ingestion/registry-primary-flag.ts +++ b/gitnexus/src/core/ingestion/registry-primary-flag.ts @@ -72,6 +72,7 @@ export const MIGRATED_LANGUAGES: ReadonlySet = new Set::<...>` (or another super- + * form the language recognizes), AND + * - `` resolves (via scope chain) to a class-like def, AND + * - that class is in the MRO of the caller's enclosing class. + * + * Returns `false` for namespace-qualified calls, unresolved names, + * class-qualified calls where the class is NOT in the caller's MRO, + * and any text the simple `isSuperReceiver` hook also rejects. + */ + readonly isSuperReceiverInContext?: ( + receiverText: string, + callerScope: ScopeId, + scopes: ScopeResolutionIndexes, + ) => boolean; + // ─── Optional toggles ────────────────────────────────────────────────────── /** @@ -522,8 +560,70 @@ export interface ScopeResolver { readonly isCallableVisibleFromCaller?: (ctx: { readonly callerParsed: ParsedFile; readonly candidate: SymbolDefinition; + /** Caller's enclosing scope id. Languages that gate visibility on + * caller scope (e.g. C++ two-phase template lookup) consult it; + * others ignore. Optional so existing implementations stay valid. */ + readonly callerScope?: ScopeId; + /** ScopeResolutionIndexes for scope-tree walks. Optional for the + * same reason as `callerScope`. */ + readonly scopes?: ScopeResolutionIndexes; }) => boolean; + /** + * Optional argument-dependent-lookup (ADL / Koenig lookup) hook for + * languages with C++-style associated-namespace candidate addition. + * + * Runs in the free-call fallback AFTER `findCallableBindingInScope` + * returns `undefined` and BEFORE `pickUniqueGlobalCallable`. The hook + * inspects the call site's argument types, computes the associated + * namespace set, and returns either: + * - a unique `SymbolDefinition` — emit the CALLS edge to it. + * - `'ambiguous'` — multiple candidates share normalized parameter + * types; the caller MUST suppress (zero edges). Mirrors the + * OVERLOAD_AMBIGUOUS sentinel from `overload-narrowing.ts`. + * - `undefined` — no ADL candidates; caller falls through to the + * global free-call fallback (`pickUniqueGlobalCallable`). + * + * Languages without C++-style ADL leave this undefined. The + * cross-language contract is "additive tier" — defining the hook never + * removes candidates the prior tier would have produced. + */ + readonly resolveAdlCandidates?: ( + site: { + readonly name: string; + readonly arity?: number; + readonly argumentTypes?: readonly string[]; + readonly atRange: { readonly startLine: number; readonly startCol: number }; + }, + callerParsed: ParsedFile, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], + ) => SymbolDefinition | 'ambiguous' | undefined; + + /** + * Optional resolver for qualified-receiver member calls where the + * receiver is a namespace (not a class) and ordinary scope-chain / + * import resolution doesn't find the member. C++ uses this for + * `outer::foo()` style calls and to walk through inline-namespace + * children transitively (`outer::v1::foo` reachable as `outer::foo`). + * + * Languages whose qualified-name semantics are already covered by the + * receiver-bound-calls Case-1 namespace-targets path (e.g., Python's + * `import X; X.foo()`) leave this undefined. + * + * Receiver-bound-calls invokes this hook AFTER Case 1 (namespace + * imports) and AFTER Case 2 (class-name receiver) fail to resolve. + * Returns the target def, or `undefined` to fall through to the + * remaining cases. + */ + readonly resolveQualifiedReceiverMember?: ( + receiverName: string, + memberName: string, + callerScope: ScopeId, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], + ) => SymbolDefinition | undefined; + /** * Optional post-finalize hook to inject cross-file bindings that * aren't modeled via explicit imports. Runs after diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts index eb6dd71fb..2dc20d2ef 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/free-call-fallback.ts @@ -42,7 +42,20 @@ export function emitFreeCallFallback( readonly isCallableVisibleFromCaller?: (ctx: { readonly callerParsed: ParsedFile; readonly candidate: SymbolDefinition; + readonly callerScope?: ScopeId; + readonly scopes?: ScopeResolutionIndexes; }) => boolean; + readonly resolveAdlCandidates?: ( + site: { + readonly name: string; + readonly arity?: number; + readonly argumentTypes?: readonly string[]; + readonly atRange: { readonly startLine: number; readonly startCol: number }; + }, + callerParsed: ParsedFile, + scopes: ScopeResolutionIndexes, + parsedFiles: readonly ParsedFile[], + ) => SymbolDefinition | 'ambiguous' | undefined; } = {}, ): number { let emitted = 0; @@ -75,6 +88,35 @@ export function emitFreeCallFallback( if (fnDef === undefined) { fnDef = findCallableBindingInScope(site.inScope, site.name, scopes); } + // V1 ADL tier (C++ Koenig lookup, opt-in via provider.resolveAdlCandidates). + // Fires only when ordinary lookup is empty — V1 limitation per + // plan 2026-05-13-001 U2; ISO C++ would merge ADL with ordinary lookup + // and run overload resolution over the union. + // + // Sentinel 'ambiguous': ADL surfaced multiple candidates with + // identical normalized parameter types (mirrors OVERLOAD_AMBIGUOUS). + // We mark the site handled so `emit-references` does not retry, and + // continue to the next site without emitting an edge. + if (fnDef === undefined && options.resolveAdlCandidates !== undefined) { + const adlResult = options.resolveAdlCandidates( + { + name: site.name, + arity: site.arity, + argumentTypes: site.argumentTypes, + atRange: { startLine: site.atRange.startLine, startCol: site.atRange.startCol }, + }, + parsed, + scopes, + parsedFiles, + ); + if (adlResult === 'ambiguous') { + handledSites.add(`${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`); + continue; + } + if (adlResult !== undefined) { + fnDef = adlResult; + } + } // V1: pickUniqueGlobalCallable ignores import context — resolves to any // globally-unique callable. False cross-package edges are possible when // the caller does not import the target package. Same-package calls are @@ -89,7 +131,12 @@ export function emitFreeCallFallback( site.arity, options.isCallableVisibleFromCaller !== undefined ? (candidate) => - options.isCallableVisibleFromCaller!({ callerParsed: parsed, candidate }) + options.isCallableVisibleFromCaller!({ + callerParsed: parsed, + candidate, + callerScope: site.inScope, + scopes, + }) : undefined, ); } diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/imported-return-types.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/imported-return-types.ts index cbdfc62aa..33716778d 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/imported-return-types.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/imported-return-types.ts @@ -151,7 +151,8 @@ export function propagateImportedReturnTypes( const refs = lookupBindingsAt(importerModule.id, localName, indexes); for (const ref of refs) { - if (ref.origin !== 'import' && ref.origin !== 'reexport') continue; + if (ref.origin !== 'import' && ref.origin !== 'reexport' && ref.origin !== 'wildcard') + continue; const sourceModule = moduleScopeByFile.get(ref.def.filePath); if (sourceModule === undefined) continue; diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts index f36287052..bff16d27e 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/overload-narrowing.ts @@ -88,3 +88,63 @@ export function narrowOverloadCandidates( return candidates; } + +/** + * Detect when >1 candidate share identical `parameterTypes` after the + * per-language normalizer has collapsed distinct underlying types. This + * signals "the resolver cannot pick the right overload — the + * normalization that helps single-candidate flows now hides a real + * ambiguity" and lets callers suppress the edge rather than pick + * arbitrarily. + * + * Concrete trigger (PR #1520 review follow-up plan U2, Claude review + * Finding 5): the C++ `arity-metadata.ts` normalizer collapses `int`, + * `long`, `short`, `unsigned`, and `size_t` to `'int'`. Without this + * check, `process(int)` and `process(long)` both end up with + * `parameterTypes === ['int']`, and `pickOverload` arbitrarily picks + * the first — emitting a false CALLS edge to the wrong overload. + * + * Returns false when: + * - 0 or 1 candidates (no ambiguity to detect) + * - any candidate has undefined `parameterTypes` (can't compare) + * - candidates differ in arity or in any parameter-type slot + * + * Other languages: this check is a precondition gate, not a behavior + * change for normal narrowing. Languages whose normalizers do not + * collapse distinct types (verified by grep over `*-arity-metadata.ts` + * — no `int → int` collapse outside C++) will never produce >1 + * candidate with identical `parameterTypes` from genuinely distinct + * declarations, so this returns false for them. The branch is + * effectively C++-only in practice. + */ +export function isOverloadAmbiguousAfterNormalization( + candidates: readonly SymbolDefinition[], + argCount?: number, +): boolean { + if (candidates.length < 2) return false; + const first = candidates[0].parameterTypes; + if (first === undefined) return false; + // When argCount is provided, compare only the first `argCount` slots — + // this catches default-argument ambiguity: `void f(int); void f(int, int = 0);` + // called with `f(1)` (argCount=1) leaves both candidates viable because + // default args make them arity-compatible, and their first slot is + // identical even though full parameterTypes lengths differ. + // Without argCount, fall back to full-sequence comparison (the original + // int/long normalization-collapse case). + const compareUpTo = argCount !== undefined ? argCount : first.length; + if (compareUpTo === 0) return false; + if (first.length < compareUpTo) return false; + for (let i = 1; i < candidates.length; i++) { + const p = candidates[i].parameterTypes; + if (p === undefined) return false; + if (p.length < compareUpTo) return false; + for (let j = 0; j < compareUpTo; j++) { + if (p[j] !== first[j]) return false; + } + // When argCount is NOT provided, also require length equality so + // distinct-arity candidates that happen to share a prefix don't + // collapse to ambiguous (preserves the original int/long contract). + if (argCount === undefined && p.length !== first.length) return false; + } + return true; +} diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts index 0cb544db9..9b57a7555 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts @@ -51,7 +51,10 @@ import { import { tryEmitEdge } from '../graph-bridge/edges.js'; import { resolveCompoundReceiverClass } from '../passes/compound-receiver.js'; import { resolveDefGraphId } from '../graph-bridge/ids.js'; -import { narrowOverloadCandidates } from './overload-narrowing.js'; +import { + narrowOverloadCandidates, + isOverloadAmbiguousAfterNormalization, +} from './overload-narrowing.js'; /** Subset of `ScopeResolver` consumed by this pass. Accepting the * subset rather than the full provider keeps tests and partial @@ -59,10 +62,12 @@ import { narrowOverloadCandidates } from './overload-narrowing.js'; type ReceiverBoundProviderSubset = Pick< ScopeResolver, | 'isSuperReceiver' + | 'isSuperReceiverInContext' | 'fieldFallbackOnMethodLookup' | 'collapseMemberCallsByCallerTarget' | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule' + | 'resolveQualifiedReceiverMember' >; export function emitReceiverBoundCalls( @@ -162,7 +167,14 @@ export function emitReceiverBoundCalls( const siteKey = `${parsed.filePath}:${site.atRange.startLine}:${site.atRange.startCol}`; // ── super branch ───────────────────────────────────────────── - if (provider.isSuperReceiver(receiverName)) { + // Languages with caller-context-dependent super classification + // (C++) define `isSuperReceiverInContext`; we prefer it. Simple + // text-only languages (Python, Java, PHP) use the plain hook. + const isSuper = + provider.isSuperReceiverInContext !== undefined + ? provider.isSuperReceiverInContext(receiverName, site.inScope, scopes) + : provider.isSuperReceiver(receiverName); + if (isSuper) { const enclosingClass = findEnclosingClassDef(site.inScope, scopes); if (enclosingClass !== undefined) { // For super-receiver dispatch (`parent::`, `base.`, `super()`), @@ -285,6 +297,38 @@ export function emitReceiverBoundCalls( if (found) continue; } + // ── Case 1.5: qualified namespace-receiver (language-specific) ─── + // Languages whose qualified-name semantics need workspace-wide + // namespace-scope walking (C++ `outer::foo()`, including inline- + // namespace transitive traversal) implement `resolveQualifiedReceiverMember`. + // Runs before Case 2 so namespace receivers don't accidentally match a + // class with the same simple name. + if (provider.resolveQualifiedReceiverMember !== undefined) { + const memberDef = provider.resolveQualifiedReceiverMember( + receiverName, + memberName, + site.inScope, + scopes, + parsedFiles, + ); + if (memberDef !== undefined) { + const ok = tryEmitEdge( + graph, + scopes, + nodeLookup, + site, + memberDef, + memberDef.filePath !== parsed.filePath ? 'import-resolved' : 'global', + seen, + 0.85, + collapse, + ); + if (ok) emitted++; + handledSites.add(siteKey); + continue; + } + } + // ── Case 2: class-name receiver ────────────────────────────── const classDef = findClassBindingInScope(site.inScope, receiverName, scopes); if (classDef !== undefined) { @@ -454,9 +498,24 @@ export function emitReceiverBoundCalls( if (ownerDef !== undefined) { const chain = [ownerDef.nodeId, ...scopes.methodDispatch.mroFor(ownerDef.nodeId)]; let memberDef: SymbolDefinition | undefined; + let ambiguous = false; for (const ownerId of chain) { - memberDef = pickOverload(ownerId, memberName, site, model); - if (memberDef !== undefined) break; + const picked = pickOverload(ownerId, memberName, site, model); + if (picked === OVERLOAD_AMBIGUOUS) { + ambiguous = true; + break; + } + if (picked !== undefined) { + memberDef = picked; + break; + } + } + if (ambiguous) { + // Suppress and mark handled so `emitReferencesViaLookup` + // doesn't re-emit the pre-resolved reference. See + // OVERLOAD_AMBIGUOUS docstring for the upstream cause. + handledSites.add(siteKey); + continue; } if (memberDef !== undefined) { // For read/write ACCESSES, mirror the legacy DAG's reason @@ -509,7 +568,7 @@ function pickOverload( memberName: string, site: ParsedFile['referenceSites'][number], model: SemanticModel, -): SymbolDefinition | undefined { +): SymbolDefinition | typeof OVERLOAD_AMBIGUOUS | undefined { const overloads = model.methods.lookupAllByOwner(ownerId, memberName); if (overloads.length === 0) { // Non-callable member (field / property / variable) — ACCESSES @@ -520,5 +579,22 @@ function pickOverload( if (overloads.length === 1) return overloads[0]; const candidates = narrowOverloadCandidates(overloads, site.arity, site.argumentTypes); + // When narrowing leaves >1 candidate that share identical normalized + // parameter-types (e.g., C++ `f(int)` vs `f(long)` both collapsed to + // `['int']` by `normalizeCppParamType`), suppress the edge entirely. + // The graph schema has no ambiguous-target edge model, so emitting one + // would arbitrarily pick a candidate and lie about the call's target. + // PR #1520 review follow-up plan U2 / Claude review Finding 5. + if (isOverloadAmbiguousAfterNormalization(candidates, site.arity)) return OVERLOAD_AMBIGUOUS; return candidates[0] ?? overloads[0]; } + +/** + * Sentinel returned by `pickOverload` when narrowing leaves >1 candidate + * sharing identical normalized parameter-types. Callers should suppress + * the CALLS edge AND mark the site as handled so `emitReferencesViaLookup` + * does not re-emit from the pre-resolved reference index. See + * `pickOverload` JSDoc for the upstream cause (per-language normalizer + * collapses distinct types in arity-metadata). + */ +export const OVERLOAD_AMBIGUOUS = Symbol('overload-ambiguous'); diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts index c606661c8..713497da4 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/registry.ts @@ -17,6 +17,7 @@ import { typescriptScopeResolver } from '../../languages/typescript/scope-resolv import { goScopeResolver } from '../../languages/go/scope-resolver.js'; import { javaScopeResolver } from '../../languages/java/scope-resolver.js'; import { cScopeResolver } from '../../languages/c/scope-resolver.js'; +import { cppScopeResolver } from '../../languages/cpp/scope-resolver.js'; import { phpScopeResolver } from '../../languages/php/scope-resolver.js'; /** Map of `SupportedLanguages` → `ScopeResolver`. The phase iterates @@ -33,5 +34,6 @@ export const SCOPE_RESOLVERS: ReadonlyMap = n [SupportedLanguages.Go, goScopeResolver], [SupportedLanguages.Java, javaScopeResolver], [SupportedLanguages.C, cScopeResolver], + [SupportedLanguages.CPlusPlus, cppScopeResolver], [SupportedLanguages.PHP, phpScopeResolver], ]); diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts index 47f8a3551..4f74cfce2 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts @@ -308,6 +308,7 @@ export function runScopeResolution( allowGlobalFallback: provider.allowGlobalFreeCallFallback === true, isFileLocalDef: provider.isFileLocalDef, isCallableVisibleFromCaller: provider.isCallableVisibleFromCaller, + resolveAdlCandidates: provider.resolveAdlCandidates, }, ); const { emitted, skipped } = emitReferencesViaLookup( diff --git a/gitnexus/src/core/ingestion/workers/parse-worker.ts b/gitnexus/src/core/ingestion/workers/parse-worker.ts index def4e1299..9a71fc16c 100644 --- a/gitnexus/src/core/ingestion/workers/parse-worker.ts +++ b/gitnexus/src/core/ingestion/workers/parse-worker.ts @@ -181,6 +181,8 @@ export interface ExtractedAssignment { propertyName: string; /** Resolved type name of the receiver if available from TypeEnv */ receiverTypeName?: string; + /** 1-indexed line number of the assignment site (used for per-site dedup) */ + line?: number; } // `ExtractedHeritage` now lives in `../model/heritage-map.ts` and is @@ -1580,6 +1582,7 @@ const processFileGroup = ( sourceId: srcId, receiverText, propertyName, + line: captureMap['assignment'].startPosition.row + 1, ...(receiverTypeName ? { receiverTypeName } : {}), }); } diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/alpha.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/alpha.h new file mode 100644 index 000000000..c873a3a67 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/alpha.h @@ -0,0 +1,7 @@ +#pragma once + +namespace alpha { + struct Token {}; + void process(Token t, int n); + void process(Token t, long n); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/app.cpp new file mode 100644 index 000000000..94c283ac5 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-ambiguous/app.cpp @@ -0,0 +1,8 @@ +#include "alpha.h" + +namespace app { + void run() { + alpha::Token t; + process(t, 42); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/app.cpp new file mode 100644 index 000000000..7fc21a0be --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event e; + record(e); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/audit.h new file mode 100644 index 000000000..2c9803a3d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-basic/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/app.cpp new file mode 100644 index 000000000..3eff3b66c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event* p; + record(p); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/audit.h new file mode 100644 index 000000000..ca2c149d2 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-arg-boundary/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event* e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/app.cpp new file mode 100644 index 000000000..64b2c6451 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event e; + (record)(e); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/audit.h new file mode 100644 index 000000000..2c9803a3d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-suppressed-parens/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/caller.cpp new file mode 100644 index 000000000..d60127bfe --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/caller.cpp @@ -0,0 +1,5 @@ +void worker(); + +void run() { + worker(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/helper.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/helper.cpp new file mode 100644 index 000000000..feeef4747 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-cross-file/helper.cpp @@ -0,0 +1,7 @@ +namespace { + void worker() {} +} + +void helper_entry() { + worker(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-same-file-visible/helper.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-same-file-visible/helper.cpp new file mode 100644 index 000000000..3d992bfe5 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-anon-ns-same-file-visible/helper.cpp @@ -0,0 +1,7 @@ +namespace { + void w() {} +} + +void run() { + w(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/caller.cpp new file mode 100644 index 000000000..8de016602 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/caller.cpp @@ -0,0 +1,5 @@ +#include "user.h" + +void run() { + save(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/user.h b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/user.h new file mode 100644 index 000000000..089fa6c59 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-class-leak/user.h @@ -0,0 +1,6 @@ +#pragma once + +class User { +public: + void save(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/caller.cpp new file mode 100644 index 000000000..90b1f2aff --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/caller.cpp @@ -0,0 +1,5 @@ +#include "lib.h" + +void run() { + foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/lib.h b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/lib.h new file mode 100644 index 000000000..11f71286f --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-include-no-namespace-leak/lib.h @@ -0,0 +1,5 @@ +#pragma once + +namespace ns { + void foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/app.cpp new file mode 100644 index 000000000..7fc21a0be --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event e; + record(e); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/audit.h new file mode 100644 index 000000000..9d657461a --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-adl-participation/audit.h @@ -0,0 +1,8 @@ +#pragma once + +namespace audit { + inline namespace v1 { + struct Event {}; + void record(Event e); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/caller.cpp new file mode 100644 index 000000000..f2aa44454 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/caller.cpp @@ -0,0 +1,5 @@ +#include "lib.h" + +void run() { + outer::foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/lib.h b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/lib.h new file mode 100644 index 000000000..ba85f2aed --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-nested/lib.h @@ -0,0 +1,9 @@ +#pragma once + +namespace outer { + inline namespace v1 { + inline namespace experimental { + void foo(); + } + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/caller.cpp new file mode 100644 index 000000000..f2aa44454 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/caller.cpp @@ -0,0 +1,5 @@ +#include "lib.h" + +void run() { + outer::foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/lib.h b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/lib.h new file mode 100644 index 000000000..e0ffb1eca --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-unqualified/lib.h @@ -0,0 +1,7 @@ +#pragma once + +namespace outer { + inline namespace v1 { + void foo(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/caller.cpp new file mode 100644 index 000000000..f2aa44454 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/caller.cpp @@ -0,0 +1,5 @@ +#include "lib.h" + +void run() { + outer::foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/lib.h b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/lib.h new file mode 100644 index 000000000..0ff3e61b3 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-inline-namespace-versioned/lib.h @@ -0,0 +1,10 @@ +#pragma once + +namespace outer { + inline namespace v1 { + void foo(); + } + namespace v0 { + void foo(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/caller.cpp new file mode 100644 index 000000000..d1edc41c4 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/caller.cpp @@ -0,0 +1,5 @@ +#include "singleton.h" + +void run() { + Singleton::getInstance(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/singleton.h b/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/singleton.h new file mode 100644 index 000000000..aa2e255e6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-namespace-qualified-not-super/singleton.h @@ -0,0 +1,6 @@ +#pragma once + +class Singleton { +public: + static Singleton* getInstance(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/caller.cpp new file mode 100644 index 000000000..2c4ee7f29 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/caller.cpp @@ -0,0 +1,6 @@ +#include "service.h" + +void run() { + S s; + s.f(1); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.cpp new file mode 100644 index 000000000..cd6f080e5 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.cpp @@ -0,0 +1,4 @@ +#include "service.h" + +void S::f(int) {} +void S::f(int, int) {} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.h b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.h new file mode 100644 index 000000000..66ad00371 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-default-arg-ambiguous/service.h @@ -0,0 +1,7 @@ +#pragma once + +class S { +public: + void f(int); + void f(int, int = 0); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/caller.cpp new file mode 100644 index 000000000..89e62ead1 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/caller.cpp @@ -0,0 +1,6 @@ +#include "service.h" + +void run() { + Service s; + s.process(42); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.cpp new file mode 100644 index 000000000..9bde80f6f --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.cpp @@ -0,0 +1,4 @@ +#include "service.h" + +void Service::process(int x) {} +void Service::process(long x) {} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.h b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.h new file mode 100644 index 000000000..1e4c5de07 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-overload-int-long/service.h @@ -0,0 +1,7 @@ +#pragma once + +class Service { +public: + void process(int x); + void process(long x); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-qualified-base-call/classes.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-qualified-base-call/classes.h new file mode 100644 index 000000000..1d53b7dfa --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-qualified-base-call/classes.h @@ -0,0 +1,13 @@ +#pragma once + +template +struct Base { + void method(); +}; + +template +struct Derived : Base { + void g() { + Base::method(); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/audit.h new file mode 100644 index 000000000..2c9803a3d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/base.h new file mode 100644 index 000000000..ccbe5b670 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/base.h @@ -0,0 +1,8 @@ +#pragma once + +#include "audit.h" + +template +struct Base { + void record(audit::Event e); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/derived.h new file mode 100644 index 000000000..ca37c8109 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u2-u3-adl-from-derived/derived.h @@ -0,0 +1,11 @@ +#pragma once + +#include "base.h" + +template +struct Derived : Base { + void g() { + audit::Event e; + record(e); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/base.h new file mode 100644 index 000000000..e9711ff08 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/base.h @@ -0,0 +1,10 @@ +#pragma once + +namespace outer { + inline namespace v1 { + template + struct Base { + void f(); + }; + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/derived.h new file mode 100644 index 000000000..b18febac8 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u3-u5-inline-base/derived.h @@ -0,0 +1,10 @@ +#pragma once + +#include "base.h" + +template +struct Derived : outer::v1::Base { + void g() { + f(); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/base.h new file mode 100644 index 000000000..1c7084ee6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/base.h @@ -0,0 +1,7 @@ +#pragma once + +template +struct Base { + void f(); + int i; +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/derived.h new file mode 100644 index 000000000..fc66c6725 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base/derived.h @@ -0,0 +1,13 @@ +#pragma once + +#include "base.h" + +template +struct Derived : Base { + void g() { + f(); + } + int h() { + return i; + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/base.h new file mode 100644 index 000000000..2b7804ba4 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/base.h @@ -0,0 +1,6 @@ +#pragma once + +template +struct Base { + void unused(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h new file mode 100644 index 000000000..ef57810fc --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h @@ -0,0 +1,11 @@ +#pragma once + +#include "base.h" +#include "helpers.h" + +template +struct D : Base { + void g() { + utils::ns_helper(); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h new file mode 100644 index 000000000..5e291aba6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h @@ -0,0 +1,5 @@ +#pragma once + +namespace utils { + void ns_helper(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/concrete-base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/concrete-base.h new file mode 100644 index 000000000..7b5d1a167 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/concrete-base.h @@ -0,0 +1,5 @@ +#pragma once + +struct ConcreteBase { + void f(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/derived.h new file mode 100644 index 000000000..e0db6269c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-non-dependent-base/derived.h @@ -0,0 +1,10 @@ +#pragma once + +#include "concrete-base.h" + +template +struct Derived : ConcreteBase { + void g() { + f(); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h new file mode 100644 index 000000000..1c7084ee6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h @@ -0,0 +1,7 @@ +#pragma once + +template +struct Base { + void f(); + int i; +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h new file mode 100644 index 000000000..5c13c1737 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h @@ -0,0 +1,13 @@ +#pragma once + +#include "base.h" + +template +struct Derived : Base { + void g() { + this->f(); + } + int h() { + return this->i; + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/a.h b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/a.h new file mode 100644 index 000000000..c02e1e19c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/a.h @@ -0,0 +1,5 @@ +#pragma once + +namespace a { + void foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/b.h b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/b.h new file mode 100644 index 000000000..67b75dd79 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/b.h @@ -0,0 +1,5 @@ +#pragma once + +namespace b { + void foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/caller.cpp new file mode 100644 index 000000000..37270861c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-conflict/caller.cpp @@ -0,0 +1,9 @@ +#include "a.h" +#include "b.h" + +using namespace a; +using namespace b; + +void run() { + foo(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/caller.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/caller.cpp new file mode 100644 index 000000000..56737c424 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/caller.cpp @@ -0,0 +1,9 @@ +#include "std-shim.h" + +using namespace std; + +void project_helper(); + +void run() { + project_helper(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/helper.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/helper.cpp new file mode 100644 index 000000000..010ffb083 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/helper.cpp @@ -0,0 +1 @@ +void project_helper() {} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/std-shim.h b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/std-shim.h new file mode 100644 index 000000000..6055204c6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-using-namespace-std-smoke/std-shim.h @@ -0,0 +1,13 @@ +#pragma once + +// Fixture-local std-shaped namespace. Captures the wildcard-leak shape +// without depending on real system-header modeling. The names mirror +// common STL identifiers (cout_write, println) so a regression that +// re-introduces unqualified std:: binding shows up in the assertions +// below — without us having to control whether GitNexus parses real +// system headers. + +namespace std { + void cout_write(); + void println(); +} diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index 0839d59f0..1f6135408 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -1,7 +1,7 @@ /** * C++: diamond inheritance + include-based imports + ambiguous #include disambiguation */ -import { describe, it, expect, beforeAll } from 'vitest'; +import { describe, expect, beforeAll } from 'vitest'; import path from 'path'; import { FIXTURES, @@ -11,9 +11,12 @@ import { getNodesByLabelFull, edgeSet, runPipelineFromRepo, + createResolverParityIt, type PipelineResult, } from './helpers.js'; +const it = createResolverParityIt('cpp'); + // --------------------------------------------------------------------------- // Heritage: diamond inheritance + include-based imports // --------------------------------------------------------------------------- @@ -937,10 +940,13 @@ describe('Write access tracking (C++)', () => { it('emits ACCESSES write edges for field assignments', () => { const accesses = getRelationships(result, 'ACCESSES'); const writes = accesses.filter((e) => e.rel.reason === 'write'); - expect(writes.length).toBe(2); - const fieldNames = writes.map((e) => e.target); - expect(fieldNames).toContain('name'); - expect(fieldNames).toContain('address'); + expect(writes.length).toBe(3); + // Per-field exact counts: both `user.name = ...` and `user.name += ...` + // must produce distinct edges (no dedup); single write to `address`. + const nameWrites = writes.filter((e) => e.target === 'name'); + expect(nameWrites.length).toBe(2); + const addrWrites = writes.filter((e) => e.target === 'address'); + expect(addrWrites.length).toBe(1); const sources = writes.map((e) => e.source); expect(sources).toContain('updateUser'); }); @@ -1582,3 +1588,598 @@ describe('C++ Derived : A, B — diamond inheritance via leftmost-base MRO (SM-1 expect(methodCall!.source).toBe('run'); }); }); + +// --------------------------------------------------------------------------- +// U1: `#include` must not leak class-owned methods as unqualified bindings +// --------------------------------------------------------------------------- + +describe('C++ include does not leak class methods', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-include-no-class-leak'), () => {}); + }, 60000); + + it('does NOT resolve unqualified save() to User::save via #include', () => { + const calls = getRelationships(result, 'CALLS'); + const leak = calls.filter((c) => c.source === 'run' && c.target === 'save'); + expect(leak.length).toBe(0); + }); + + it('preserves the file-level #include IMPORTS edge', () => { + const imports = getRelationships(result, 'IMPORTS'); + expect(imports.length).toBe(1); + expect(imports[0].targetFilePath).toBe('user.h'); + }); +}); + +// --------------------------------------------------------------------------- +// U1: `#include` must not leak namespace-nested symbols as unqualified bindings +// --------------------------------------------------------------------------- + +describe('C++ include does not leak namespace members', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-include-no-namespace-leak'), + () => {}, + ); + }, 60000); + + it('does NOT resolve unqualified foo() to ns::foo via #include', () => { + const calls = getRelationships(result, 'CALLS'); + const leak = calls.filter((c) => c.source === 'run' && c.target === 'foo'); + expect(leak.length).toBe(0); + }); + + it('preserves the file-level #include IMPORTS edge', () => { + const imports = getRelationships(result, 'IMPORTS'); + expect(imports.length).toBe(1); + expect(imports[0].targetFilePath).toBe('lib.h'); + }); +}); + +// --------------------------------------------------------------------------- +// U1: anonymous-namespace symbols remain visible within their declaring TU +// (positive companion to the cross-file exclusion test below) +// --------------------------------------------------------------------------- + +describe('C++ anonymous namespace symbols visible in same TU', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-anon-ns-same-file-visible'), + () => {}, + ); + }, 60000); + + it('resolves run() -> w() within the same TU', () => { + const calls = getRelationships(result, 'CALLS'); + const wCalls = calls.filter((c) => c.source === 'run' && c.target === 'w'); + expect(wCalls.length).toBe(1); + }); +}); + +// --------------------------------------------------------------------------- +// U2: integer-width overload ambiguity suppresses CALLS edge entirely +// (PR #1520 review follow-up plan U2; Claude review Finding 5) +// --------------------------------------------------------------------------- + +describe('C++ ambiguous integer-width overloads', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-overload-int-long'), () => {}); + }, 60000); + + it('emits zero CALLS edges when process(int)/process(long) collide after normalization', () => { + const calls = getRelationships(result, 'CALLS'); + const processCalls = calls.filter((c) => c.source === 'run' && c.target === 'process'); + // Exact .toBe(0): any non-zero count is a regression. count=1 = arbitrary + // pick (the bug U2 fixes); count=2+ would require an ambiguous-edge model + // GitNexus does not have. The resolver must suppress entirely. + expect(processCalls.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// U3: anonymous-namespace symbols MUST NOT leak across translation units +// (full-pipeline integration test; unit-level coverage exists separately) +// PR #1520 review follow-up plan U3 / Claude review Finding 7 +// --------------------------------------------------------------------------- + +describe('C++ anonymous namespace cross-file exclusion (integration)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-anon-ns-cross-file'), () => {}); + }, 60000); + + it('caller.cpp::run -> worker does NOT target helper.cpp anonymous-namespace worker', () => { + const calls = getRelationships(result, 'CALLS'); + const crossFileLeak = calls.filter( + (c) => + c.source === 'run' && c.target === 'worker' && c.targetFilePath?.includes('helper.cpp'), + ); + expect(crossFileLeak.length).toBe(0); + }); + + it('helper.cpp::helper_entry still resolves its OWN anonymous-namespace worker (positive guard)', () => { + const calls = getRelationships(result, 'CALLS'); + const sameFileResolve = calls.filter( + (c) => + c.source === 'helper_entry' && + c.target === 'worker' && + c.targetFilePath?.includes('helper.cpp'), + ); + // Pairs with the negative test above so a "no edges at all" regression + // doesn't make the cross-file leak check pass vacuously. + expect(sameFileResolve.length).toBe(1); + }); +}); + +// State-isolation guard: re-run the same fixture and assert identical +// results. Proves `clearFileLocalNames()` (called from the cpp resolver's +// `loadResolutionConfig`) is exercised by `runPipelineFromRepo` and +// that module-level `fileLocalNames` state doesn't bleed across runs. +describe('C++ anonymous namespace state-isolation guard', () => { + it('second run of the same fixture produces identical worker-cross-file edge count', async () => { + const fixture = path.join(FIXTURES, 'cpp-anon-ns-cross-file'); + const r1 = await runPipelineFromRepo(fixture, () => {}); + const r2 = await runPipelineFromRepo(fixture, () => {}); + const countLeak = (r: PipelineResult): number => + getRelationships(r, 'CALLS').filter( + (c) => + c.source === 'run' && c.target === 'worker' && c.targetFilePath?.includes('helper.cpp'), + ).length; + expect(countLeak(r1)).toBe(0); + expect(countLeak(r2)).toBe(0); + }, 120000); +}); + +// --------------------------------------------------------------------------- +// U4: `using namespace` with conflicting names from two namespaces +// The resolver MUST emit zero CALLS edges — emitting one is arbitrary +// pick; emitting two requires an ambiguous-target edge model GitNexus +// does not have. +// Depends on U1 (without scope-aware filtering, `a::foo` and `b::foo` +// would already be in the importer's wildcard binding set as simple +// `foo` and this test would pass for the wrong reason). +// PR #1520 review follow-up plan U4 / Claude review Finding 7 +// --------------------------------------------------------------------------- + +describe('C++ using-namespace with conflicting names', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-using-namespace-conflict'), + () => {}, + ); + }, 60000); + + it('emits zero CALLS edges for ambiguous foo() bound via two using-namespace declarations', () => { + const calls = getRelationships(result, 'CALLS'); + const fooCalls = calls.filter((c) => c.source === 'run' && c.target === 'foo'); + expect(fooCalls.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// U5: `using namespace std` MUST NOT leak shim STL symbols into unqualified +// bindings. Uses a fixture-local `namespace std { ... }` shim rather than +// real — captures the wildcard-leak shape deterministically +// without depending on system-header modeling stability. +// PR #1520 review follow-up plan U5 / Claude review Finding 7 +// --------------------------------------------------------------------------- + +describe('C++ using-namespace std smoke test', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-using-namespace-std-smoke'), + () => {}, + ); + }, 60000); + + it('resolves the project call (positive guard against vacuous pass)', () => { + const calls = getRelationships(result, 'CALLS'); + const projectCalls = calls.filter((c) => c.source === 'run' && c.target === 'project_helper'); + expect(projectCalls.length).toBe(1); + }); + + it('does NOT leak unqualified bindings for shim STL symbols', () => { + const calls = getRelationships(result, 'CALLS'); + const stlLeaks = calls.filter( + (c) => c.source === 'run' && (c.target === 'cout_write' || c.target === 'println'), + ); + expect(stlLeaks.length).toBe(0); + }); + + it('emits no CALLS or ACCESSES edges from run() into std-shim.h', () => { + const calls = getRelationships(result, 'CALLS'); + const accesses = getRelationships(result, 'ACCESSES'); + const intoShim = [...calls, ...accesses].filter( + (e) => e.source === 'run' && e.targetFilePath?.includes('std-shim.h'), + ); + expect(intoShim.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// U1 (follow-up plan 2026-05-13-001): namespace-qualified or class-qualified +// calls from outside that class MUST NOT be classified as super-receiver calls. +// The `isSuperReceiverInContext` hook consults the caller's MRO. +// --------------------------------------------------------------------------- + +describe('C++ namespace-qualified call is not a super receiver', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-namespace-qualified-not-super'), + () => {}, + ); + }, 60000); + + it('resolves Singleton::getInstance() from a free function (not as super call)', () => { + const calls = getRelationships(result, 'CALLS'); + const getInstanceCalls = calls.filter((c) => c.source === 'run' && c.target === 'getInstance'); + // Exactly 1: routed through the normal qualified-call path, NOT the super + // branch. Before the U1 fix the regex `/^[A-Z]\w*::/` matched Singleton::, + // entered the super branch with no enclosing class, and dropped the edge. + expect(getInstanceCalls.length).toBe(1); + expect(getInstanceCalls[0].targetFilePath).toContain('singleton.h'); + }); +}); + +// --------------------------------------------------------------------------- +// U4 (follow-up plan 2026-05-13-001): default-argument overload ambiguity. +// `void f(int); void f(int, int = 0); f(1);` is ambiguous per ISO C++. The +// OVERLOAD_AMBIGUOUS sentinel from plan 2026-05-12-002 U2 should detect +// this case via isOverloadAmbiguousAfterNormalization. +// --------------------------------------------------------------------------- + +describe('C++ default-argument overload ambiguity', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-overload-default-arg-ambiguous'), + () => {}, + ); + }, 60000); + + it('s.f(1) emits zero CALLS edges when f(int) and f(int, int=0) both match', () => { + const calls = getRelationships(result, 'CALLS'); + const fCalls = calls.filter((c) => c.source === 'run' && c.target === 'f'); + // Exact .toBe(0): count=1 means arbitrary pick (the bug); count=2+ would + // require an ambiguous-target edge model GitNexus does not have. The + // resolver must suppress entirely. Standard C++ rejects the call as + // ambiguous (GCC/Clang both diagnose). + expect(fCalls.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// U3 (follow-up plan 2026-05-13-001): two-phase template lookup. +// Inside a class template body, unqualified calls MUST NOT bind to members +// of a dependent base class. Only `this->name()` or `Base::name()` forms +// should resolve. +// --------------------------------------------------------------------------- + +describe('C++ two-phase template lookup — dependent base suppression', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-two-phase-dependent-base'), + () => {}, + ); + }, 60000); + + it('Derived::g() -> f() does NOT bind to Base::f (dependent base)', () => { + const calls = getRelationships(result, 'CALLS'); + const leaks = calls.filter((c) => c.source === 'g' && c.target === 'f'); + expect(leaks.length).toBe(0); + }); + + it('Derived::h() -> i does NOT bind to Base::i (dependent base)', () => { + const accesses = getRelationships(result, 'ACCESSES'); + const leaks = accesses.filter((c) => c.source === 'h' && c.target === 'i'); + expect(leaks.length).toBe(0); + }); +}); + +// NOTE: positive guards (this->f() resolves, non-dependent-base unqualified +// f() resolves, namespace-qualified utils::ns_helper() resolves) inside +// template bodies are documented gaps in C++ template-context resolution +// independent of U3's dependent-base suppression. The U3 core asserts only +// the negative behavior (dependent-base members are NOT bound by unqualified +// calls); the positive cases would require additional `this` type-binding +// and template-body member-lookup work tracked separately. See plan +// 2026-05-13-001 follow-ups. + +// --------------------------------------------------------------------------- +// U2 (follow-up plan 2026-05-13-001): argument-dependent (Koenig) lookup. +// Free-function calls with class-typed arguments must consider candidates +// declared in the argument's enclosing namespace (associated namespace). +// V1 boundary: only direct enclosing-namespace closure for value class- +// typed args; pointer / reference / template-spec args excluded. +// --------------------------------------------------------------------------- + +describe('C++ ADL — basic associated-namespace closure', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-adl-basic'), () => {}); + }, 60000); + + it('record(e) where e is audit::Event resolves to audit::record via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + // Exactly 1: ordinary lookup is empty (no `using` statement, no local + // declaration), ADL surfaces audit::record because audit::Event's + // associated namespace is `audit`. The CALLS edge should target the + // declaration in audit.h. + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); +}); + +describe('C++ ADL — parenthesized name suppresses ADL', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-adl-suppressed-parens'), () => {}); + }, 60000); + + it('(record)(e) emits zero CALLS edges — ADL is suppressed by parentheses', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + // Exact .toBe(0): ISO C++ [basic.lookup.argdep]/3.1 specifies that the + // parenthesized form `(f)(x)` forces ordinary lookup only — ADL must + // NOT fire. Without ordinary-lookup candidates (no `using`, no local + // declaration), the call goes unresolved. + expect(recordCalls.length).toBe(0); + }); +}); + +describe('C++ ADL — pointer-arg V1 boundary', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-adl-pointer-arg-boundary'), + () => {}, + ); + }, 60000); + + it('record(p) where p is audit::Event* emits zero CALLS — V1 ADL excludes pointer args', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + // Exact .toBe(0): V1 ADL covers only directly-named class-type values + // (per plan 2026-05-13-001 R4). Pointer-typed args fall under + // associated-entity closure rules deferred to V2. This fixture locks + // the boundary in CI so the implementer cannot accidentally extend + // V1 to include pointer types. Real ISO C++ would resolve via V2 + // closure; matching that requires the V2 follow-up plan. + expect(recordCalls.length).toBe(0); + }); +}); + +describe('C++ ADL — int/long-collision overloads suppress via OVERLOAD_AMBIGUOUS', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-adl-ambiguous'), () => {}); + }, 60000); + + it('process(t, 42) emits zero CALLS edges when ADL surfaces process(Token,int)/process(Token,long) (collide after C++ int normalization)', () => { + const calls = getRelationships(result, 'CALLS'); + const processCalls = calls.filter((c) => c.source === 'run' && c.target === 'process'); + // Exact .toBe(0): both alpha::process(Token, int) and + // alpha::process(Token, long) are surfaced via ADL (alpha::Token's + // associated namespace). C++ arity-metadata normalizes int/long to + // 'int', so both candidates have parameterTypes ['Token', 'int']. + // narrowOverloadCandidates can't disambiguate (arg-types are + // ['', 'int']), and isOverloadAmbiguousAfterNormalization detects + // the collision → ADL_AMBIGUOUS sentinel → caller suppresses. + // count=1 is the bug (arbitrary first-pick); count=2 would require + // an ambiguous-target edge model GitNexus does not have. + expect(processCalls.length).toBe(0); + }); +}); + +// --------------------------------------------------------------------------- +// U5 (follow-up plan 2026-05-13-001): inline namespace transitive walking. +// `inline namespace v1 { ... }` makes its members reachable through the +// enclosing namespace's qualified lookup as if declared directly there +// (ISO C++ `[namespace.def]/p4`). Adds a C++-specific +// `resolveQualifiedReceiverMember` hook on the ScopeResolver contract. +// --------------------------------------------------------------------------- + +describe('C++ inline namespace — outer::foo resolves to inline child', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-inline-namespace-unqualified'), + () => {}, + ); + }, 60000); + + it('outer::foo() resolves to outer::v1::foo via inline-namespace transitive walking', () => { + const calls = getRelationships(result, 'CALLS'); + const fooCalls = calls.filter((c) => c.source === 'run' && c.target === 'foo'); + // Exactly 1: the inline-namespace exemption lets `outer::foo()` reach + // the declaration in `outer::v1::foo()`. Without U5 the call would be + // unresolved (count = 0). + expect(fooCalls.length).toBe(1); + expect(fooCalls[0].targetFilePath).toContain('lib.h'); + }); +}); + +describe('C++ inline namespace — versioned (v1 inline, v0 not)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-inline-namespace-versioned'), + () => {}, + ); + }, 60000); + + it('outer::foo() resolves to outer::v1::foo (inline child), NOT outer::v0::foo', () => { + const calls = getRelationships(result, 'CALLS'); + const fooCalls = calls.filter((c) => c.source === 'run' && c.target === 'foo'); + // Exactly 1: only inline-namespace children are reachable through the + // enclosing namespace's qualified lookup. `v0` is NOT inline so its + // `foo` is NOT visible as `outer::foo`. + expect(fooCalls.length).toBe(1); + expect(fooCalls[0].targetFilePath).toContain('lib.h'); + }); +}); + +describe('C++ inline namespace — nested (STL __1-style)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-inline-namespace-nested'), + () => {}, + ); + }, 60000); + + it('outer::foo() resolves through two transitive inline namespaces (v1 then experimental)', () => { + const calls = getRelationships(result, 'CALLS'); + const fooCalls = calls.filter((c) => c.source === 'run' && c.target === 'foo'); + // Exactly 1: the resolver descends inline namespaces depth-first, so + // `outer::foo` reaches `outer::v1::experimental::foo` through two + // transitive inline-namespace hops. Mirrors libc++ `std::__1::vector` + // / libstdc++ `std::__cxx11` qualified-call shape. + expect(fooCalls.length).toBe(1); + expect(fooCalls[0].targetFilePath).toContain('lib.h'); + }); +}); + +describe('C++ inline namespace — ADL participation', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-inline-namespace-adl-participation'), + () => {}, + ); + }, 60000); + + it('ADL surfaces audit::v1::record through inline-namespace transitive walking', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + // Exactly 1: `audit::Event e;` resolves Event's enclosing namespace + // to `audit` (the inline child `v1` is transparent — see U2's + // computeNamespaceQName walking through the inline scope). ADL then + // surfaces every callable named `record` in any namespace scope + // matching qname 'audit' across files. Since inline namespaces are + // exempted from the non-globally-visible filter, the `record` + // declared inside `inline namespace v1` is reachable. count=0 + // would be the bug — ADL failing to walk inline children. + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); +}); + +// --------------------------------------------------------------------------- +// Phase 5 (follow-up plan 2026-05-13-001): cross-unit composition tests. +// Lock in correct interaction between U1 (super-receiver context), U2 (ADL), +// U3 (two-phase lookup), and U5 (inline namespaces). +// --------------------------------------------------------------------------- + +describe('C++ Phase 5 U1×U3 — qualified Base::method() inside template body (no false positives)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-phase5-u1-u3-qualified-base-call'), + () => {}, + ); + }, 60000); + + it('Base::method() does NOT mis-route to a class method outside the MRO', () => { + const calls = getRelationships(result, 'CALLS'); + const methodCalls = calls.filter((c) => c.source === 'g' && c.target === 'method'); + // V1 documented gap: cross-file (and same-file) template-class + // inheritance is not captured as an EXTENDS edge by the legacy DAG + // (the cpp captures.ts has no `base_class_clause` heritage emitter + // for template_type bases). Without an EXTENDS edge, MRO is empty + // and the U1 super branch can't dispatch. Result: 0 CALLS edges. + // + // This Phase 5 cross-unit composition test locks in that the + // template-arg-stripping U1 logic produces NO false positives — + // `Base` correctly classifies as a super-receiver candidate but + // (due to empty MRO) doesn't accidentally route to an unrelated + // method named `method` via any other case. count > 0 here would + // indicate the U1 stripped lookup mis-resolved across cases. + expect(methodCalls.length).toBe(0); + }); +}); + +describe('C++ Phase 5 U2×U3 — ADL routes around dependent-base shadow', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-phase5-u2-u3-adl-from-derived'), + () => {}, + ); + }, 60000); + + it('record(e) inside Derived::g() resolves via ADL to audit::record (not Base::record)', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'g' && c.target === 'record'); + // Exactly 1: Base::record is class-owned so the global free-call + // fallback's `isFileLocalDef` blocks it (and U3's two-phase + // suppression also fires for unqualified calls inside template + // body when the candidate is a dependent-base member). ADL then + // surfaces audit::record via `audit::Event`'s associated namespace. + // The two-phase + ADL composition leaves exactly one CALLS edge — + // to audit::record in audit.h. + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); + + it('record(e) does NOT bind to Base::record (class-owned dependent-base member)', () => { + const calls = getRelationships(result, 'CALLS'); + const baseRecordLeaks = calls.filter( + (c) => c.source === 'g' && c.target === 'record' && c.targetFilePath?.includes('base.h'), + ); + expect(baseRecordLeaks.length).toBe(0); + }); +}); + +describe('C++ Phase 5 U3×U5 — template Derived : outer::v1::Base (inline)', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-phase5-u3-u5-inline-base'), + () => {}, + ); + }, 60000); + + it('unqualified f() inside Derived::g() does NOT bind to outer::v1::Base::f (dependent base across inline namespace)', () => { + const calls = getRelationships(result, 'CALLS'); + const fLeaks = calls.filter((c) => c.source === 'g' && c.target === 'f'); + // Exact .toBe(0): same suppression rationale as the plain U3 fixture + // (`cpp-two-phase-dependent-base`) — `f()` is unqualified, Base is a + // dependent base, and Base::f is class-owned so the global free-call + // fallback's `isFileLocalDef` blocks it. The inline-namespace wrapper + // doesn't change the suppression behavior: dependent-base detection + // walks the heritage's simple name (`Base`) regardless of the + // qualifying namespace path. + expect(fLeaks.length).toBe(0); + }); +}); diff --git a/gitnexus/test/integration/resolvers/helpers.ts b/gitnexus/test/integration/resolvers/helpers.ts index 571f2121f..7cbfaaf6c 100644 --- a/gitnexus/test/integration/resolvers/helpers.ts +++ b/gitnexus/test/integration/resolvers/helpers.ts @@ -90,6 +90,74 @@ const LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES: Readonly([ + // The legacy DAG path has no scope-aware filtering on the global + // free-call fallback, so `#include`d headers still leak class + // methods (`User::save`) and namespace members (`ns::foo`) as + // resolution targets for unqualified calls. The scope-resolver + // path filters via `populateCppNonGloballyVisible` + + // `isFileLocalDef`. Scope-resolver-only correctness win + // (PR #1520 review follow-up plan U1); backporting to legacy is + // out of scope. + 'does NOT resolve unqualified save() to User::save via #include', + 'does NOT resolve unqualified foo() to ns::foo via #include', + // The legacy DAG path lacks the OVERLOAD_AMBIGUOUS suppression + // wired through `pickOverload` + `isOverloadAmbiguousAfterNormalization`, + // so it arbitrarily picks the first overload when `f(int)` and + // `f(long)` collide after C++ integer-width normalization. Scope- + // resolver-only correctness win (PR #1520 review follow-up plan U2 / + // Claude review Finding 5); backporting to legacy is out of scope. + 'emits zero CALLS edges when process(int)/process(long) collide after normalization', + // The legacy DAG path resolves `using namespace a; using namespace b; foo()` + // by walking the workspace registry by simple name and binding to + // the first match — same shape as the integer-width collision, just + // with namespace-resolution as the ambiguity source. Scope-resolver- + // only correctness win (PR #1520 review follow-up plan U4 / Claude + // review Finding 7); backporting to legacy is out of scope. + 'emits zero CALLS edges for ambiguous foo() bound via two using-namespace declarations', + // The legacy DAG path lacks two-phase template lookup. Unqualified + // calls inside a class template body bind to dependent-base members + // there, producing CALLS edges the compiler would reject (ISO C++ + // two-phase name lookup). Scope-resolver-only correctness win + // (PR #1520 review follow-up plan 2026-05-13-001 U3); backporting + // is out of scope. + 'Derived::g() -> f() does NOT bind to Base::f (dependent base)', + // The legacy DAG path has no V1/V2 ADL boundary — pointer-typed + // arguments resolve via the workspace-wide simple-name walk. The + // scope-resolver V1 ADL pass excludes pointer args (closure rules + // deferred to V2) per plan 2026-05-13-001 U2 / R4. Scope-resolver- + // only correctness win; backporting is out of scope. + 'record(p) where p is audit::Event* emits zero CALLS — V1 ADL excludes pointer args', + // The legacy DAG path has no ADL_AMBIGUOUS suppression sentinel. + // When ADL surfaces multiple overloads that collide after C++ + // int/long normalization, legacy picks the first match arbitrarily. + // The scope-resolver path suppresses via the ADL_AMBIGUOUS sentinel + // (mirroring OVERLOAD_AMBIGUOUS for receiver-bound paths). Scope- + // resolver-only correctness win (PR #1520 review follow-up plan + // 2026-05-13-001 U2); backporting is out of scope. + 'process(t, 42) emits zero CALLS edges when ADL surfaces process(Token,int)/process(Token,long) (collide after C++ int normalization)', + // The legacy DAG path has no qualified namespace-member resolver + // and no inline-namespace awareness. For the versioned fixture + // (`outer::v1::foo` inline, `outer::v0::foo` not), the registry- + // primary path resolves `outer::foo()` to v1 via the inline + // exemption; legacy can't see EITHER and emits zero edges. The + // unqualified / nested fixtures coincidentally resolve in legacy + // because their global free-call fallback picks the unique simple- + // name match; the versioned fixture has two `foo`s and legacy can't + // disambiguate. Scope-resolver-only correctness win (PR #1520 + // review follow-up plan 2026-05-13-001 U5); backporting is out of + // scope. + 'outer::foo() resolves to outer::v1::foo (inline child), NOT outer::v0::foo', + // Phase 5 cross-unit composition tests assert no false positives + // for compositions where the legacy DAG over-resolves. The legacy + // path has no template-arg-stripping qualified-receiver logic and + // no two-phase dependent-base suppression, so it produces CALLS + // edges where the registry-primary path correctly suppresses. + // Scope-resolver-only correctness wins (PR #1520 review follow-up + // plan 2026-05-13-001 Phase 5); backporting is out of scope. + 'Base::method() does NOT mis-route to a class method outside the MRO', + 'unqualified f() inside Derived::g() does NOT bind to outer::v1::Base::f (dependent base across inline namespace)', + ]), }; type ResolverParityEnv = Readonly>; diff --git a/gitnexus/test/unit/registry-primary-flag.test.ts b/gitnexus/test/unit/registry-primary-flag.test.ts index 864754b7f..e800bd14a 100644 --- a/gitnexus/test/unit/registry-primary-flag.test.ts +++ b/gitnexus/test/unit/registry-primary-flag.test.ts @@ -127,8 +127,10 @@ describe('isRegistryPrimary', () => { it('handles the CPlusPlus → REGISTRY_PRIMARY_CPP mapping correctly', () => { process.env['REGISTRY_PRIMARY_CPP'] = 'true'; expect(isRegistryPrimary(SupportedLanguages.CPlusPlus)).toBe(true); - // Negative: the TS-key-style name is NOT read. - delete process.env['REGISTRY_PRIMARY_CPP']; + // Negative: the TS-key-style name is NOT read. CPlusPlus is now in + // MIGRATED_LANGUAGES, so we must explicitly opt it out via the + // canonical env var to verify the wrong-name var has no effect. + process.env['REGISTRY_PRIMARY_CPP'] = 'false'; process.env['REGISTRY_PRIMARY_CPLUSPLUS'] = 'true'; expect(isRegistryPrimary(SupportedLanguages.CPlusPlus)).toBe(false); }); @@ -151,8 +153,8 @@ describe('primaryLanguages', () => { // testing explicit env overrides. Java (unmigrated) opts in. // Opt out every member of MIGRATED_LANGUAGES dynamically so this test // does not have to be updated each time a new language ships its - // Ring 3 migration (PHP joined the set in commit 69786b16; future - // Ring 3 additions land here without test churn). + // Ring 3 migration (C++ and PHP joined the set in their respective + // Ring 3 migrations; future Ring 3 additions land here without test churn). for (const lang of MIGRATED_LANGUAGES) { process.env[envVarNameFor(lang)] = 'false'; } @@ -161,6 +163,7 @@ describe('primaryLanguages', () => { expect(enabled.has(SupportedLanguages.Python)).toBe(false); expect(enabled.has(SupportedLanguages.CSharp)).toBe(false); expect(enabled.has(SupportedLanguages.Go)).toBe(false); + expect(enabled.has(SupportedLanguages.CPlusPlus)).toBe(false); expect(enabled.has(SupportedLanguages.PHP)).toBe(false); expect(enabled.has(SupportedLanguages.Java)).toBe(true); // Only Java is on: migrated defaults overridden off, Java explicitly on. diff --git a/gitnexus/test/unit/scope-resolution/cpp/cpp-arity.test.ts b/gitnexus/test/unit/scope-resolution/cpp/cpp-arity.test.ts new file mode 100644 index 000000000..a89a3167d --- /dev/null +++ b/gitnexus/test/unit/scope-resolution/cpp/cpp-arity.test.ts @@ -0,0 +1,168 @@ +/** + * Unit tests for C++ arity compatibility and metadata. + */ + +import { describe, it, expect } from 'vitest'; +import { cppArityCompatibility } from '../../../../src/core/ingestion/languages/cpp/arity.js'; +import { + computeCppDeclarationArity, + computeCppCallArity, +} from '../../../../src/core/ingestion/languages/cpp/arity-metadata.js'; +import { getCppParser } from '../../../../src/core/ingestion/languages/cpp/query.js'; +import type { SyntaxNode } from '../../../../src/core/ingestion/utils/ast-helpers.js'; +import type { SymbolDefinition, Callsite } from 'gitnexus-shared'; + +function parseFuncDef(src: string): SyntaxNode | null { + const tree = getCppParser().parse(src); + for (let i = 0; i < tree.rootNode.namedChildCount; i++) { + const child = tree.rootNode.namedChild(i); + if (child?.type === 'function_definition') return child as SyntaxNode; + } + return null; +} + +function parseCallExpr(src: string): SyntaxNode | null { + const tree = getCppParser().parse(src); + const walk = (node: SyntaxNode): SyntaxNode | null => { + if (node.type === 'call_expression') return node; + for (let i = 0; i < node.namedChildCount; i++) { + const found = walk(node.namedChild(i) as SyntaxNode); + if (found) return found; + } + return null; + }; + return walk(tree.rootNode as SyntaxNode); +} + +function mkDef(overrides: Partial = {}): SymbolDefinition { + return { + nodeId: 'test-def', + qualifiedName: 'test', + filePath: 'test.cpp', + type: 'Function', + ...overrides, + } as SymbolDefinition; +} + +function mkCallsite(arity: number): Callsite { + return { arity } as Callsite; +} + +// ── Declaration arity ─────────────────────────────────────────────────────── + +describe('computeCppDeclarationArity', () => { + it('computes arity for zero-parameter function', () => { + const node = parseFuncDef('void foo() {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBe(0); + expect(arity.requiredParameterCount).toBe(0); + }); + + it('computes arity for (void) parameter', () => { + const node = parseFuncDef('void foo(void) {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBe(0); + expect(arity.requiredParameterCount).toBe(0); + }); + + it('computes arity for multiple parameters', () => { + const node = parseFuncDef('void foo(int x, int y, int z) {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBe(3); + expect(arity.requiredParameterCount).toBe(3); + }); + + it('computes arity with default parameters', () => { + const node = parseFuncDef('void foo(int x, int y = 5, int z = 10) {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBe(3); + expect(arity.requiredParameterCount).toBe(1); + }); + + it('detects variadic function', () => { + const node = parseFuncDef('void foo(int x, ...) {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBeUndefined(); // variadic → undefined max + expect(arity.requiredParameterCount).toBe(1); + expect(arity.parameterTypes).toContain('...'); + }); + + it('handles pointer return type', () => { + const node = parseFuncDef('int* create(int size) {}'); + expect(node).not.toBeNull(); + const arity = computeCppDeclarationArity(node!); + expect(arity.parameterCount).toBe(1); + }); +}); + +// ── Call-site arity ───────────────────────────────────────────────────────── + +describe('computeCppCallArity', () => { + it('computes arity for no-argument call', () => { + const node = parseCallExpr('void f() { foo(); }'); + expect(node).not.toBeNull(); + expect(computeCppCallArity(node!)).toBe(0); + }); + + it('computes arity for multi-argument call', () => { + const node = parseCallExpr('void f() { foo(1, 2, 3); }'); + expect(node).not.toBeNull(); + expect(computeCppCallArity(node!)).toBe(3); + }); + + it('computes arity for single-argument call', () => { + const node = parseCallExpr('void f() { foo(42); }'); + expect(node).not.toBeNull(); + expect(computeCppCallArity(node!)).toBe(1); + }); +}); + +// ── Arity compatibility ───────────────────────────────────────────────────── + +describe('cppArityCompatibility', () => { + it('returns compatible for exact match', () => { + const def = mkDef({ parameterCount: 2, requiredParameterCount: 2 }); + expect(cppArityCompatibility(def, mkCallsite(2))).toBe('compatible'); + }); + + it('returns compatible when call uses default params', () => { + const def = mkDef({ parameterCount: 3, requiredParameterCount: 1 }); + expect(cppArityCompatibility(def, mkCallsite(1))).toBe('compatible'); + expect(cppArityCompatibility(def, mkCallsite(2))).toBe('compatible'); + expect(cppArityCompatibility(def, mkCallsite(3))).toBe('compatible'); + }); + + it('returns incompatible for too few args', () => { + const def = mkDef({ parameterCount: 3, requiredParameterCount: 2 }); + expect(cppArityCompatibility(def, mkCallsite(1))).toBe('incompatible'); + }); + + it('returns incompatible for too many args (non-variadic)', () => { + const def = mkDef({ parameterCount: 2, requiredParameterCount: 2 }); + expect(cppArityCompatibility(def, mkCallsite(5))).toBe('incompatible'); + }); + + it('returns compatible for variadic with extra args', () => { + const def = mkDef({ + parameterCount: undefined, + requiredParameterCount: 1, + parameterTypes: ['int', '...'], + }); + expect(cppArityCompatibility(def, mkCallsite(5))).toBe('compatible'); + }); + + it('returns unknown when no metadata', () => { + const def = mkDef({}); + expect(cppArityCompatibility(def, mkCallsite(2))).toBe('unknown'); + }); + + it('returns unknown for negative arity', () => { + const def = mkDef({ parameterCount: 2, requiredParameterCount: 2 }); + expect(cppArityCompatibility(def, mkCallsite(-1))).toBe('unknown'); + }); +}); diff --git a/gitnexus/test/unit/scope-resolution/cpp/cpp-captures.test.ts b/gitnexus/test/unit/scope-resolution/cpp/cpp-captures.test.ts new file mode 100644 index 000000000..8e000261c --- /dev/null +++ b/gitnexus/test/unit/scope-resolution/cpp/cpp-captures.test.ts @@ -0,0 +1,426 @@ +/** + * Unit tests for C++ scope query + captures orchestrator. + * + * Pins the capture-tag vocabulary + range shape for every construct + * the scope-resolution pipeline reads. Runs against tree-sitter-cpp. + */ + +import { describe, it, expect, beforeEach } from 'vitest'; +import { emitCppScopeCaptures } from '../../../../src/core/ingestion/languages/cpp/captures.js'; +import { + clearFileLocalNames, + isFileLocal, +} from '../../../../src/core/ingestion/languages/cpp/file-local-linkage.js'; + +function tagsFor(src: string, filePath = 'test.cpp'): string[][] { + const matches = emitCppScopeCaptures(src, filePath); + return matches.map((m) => Object.keys(m).sort()); +} + +function findMatch(src: string, predicate: (tags: string[]) => boolean, filePath = 'test.cpp') { + const matches = emitCppScopeCaptures(src, filePath); + return matches.find((m) => predicate(Object.keys(m))); +} + +function allMatches(src: string, predicate: (tags: string[]) => boolean, filePath = 'test.cpp') { + const matches = emitCppScopeCaptures(src, filePath); + return matches.filter((m) => predicate(Object.keys(m))); +} + +// ── Scopes ────────────────────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — scopes', () => { + it('captures translation_unit as @scope.module', () => { + const all = tagsFor('int x = 1;'); + expect(all.some((t) => t.includes('@scope.module'))).toBe(true); + }); + + it('captures class_specifier as @scope.class', () => { + const all = tagsFor('class Foo { int x; };'); + expect(all.some((t) => t.includes('@scope.class'))).toBe(true); + }); + + it('captures struct_specifier as @scope.class', () => { + const all = tagsFor('struct Point { int x; int y; };'); + expect(all.some((t) => t.includes('@scope.class'))).toBe(true); + }); + + it('captures namespace_definition as @scope.namespace', () => { + const all = tagsFor('namespace foo { int x; }'); + expect(all.some((t) => t.includes('@scope.namespace'))).toBe(true); + }); + + it('captures function_definition as @scope.function', () => { + const all = tagsFor('void foo() { }'); + expect(all.some((t) => t.includes('@scope.function'))).toBe(true); + }); + + it('captures lambda_expression as @scope.function', () => { + const all = tagsFor('auto f = [](int x) { return x; };'); + expect(all.some((t) => t.includes('@scope.function'))).toBe(true); + }); + + it('captures block-level scopes (if, for, while, do, switch, case, try, catch)', () => { + const src = ` + void f() { + if (true) { } + for (int i = 0; i < 10; i++) { } + while (true) { } + do { } while (false); + switch (0) { case 0: break; } + try { } catch (...) { } + } + `; + const all = tagsFor(src); + const blocks = all.filter((t) => t.includes('@scope.block')); + expect(blocks.length).toBeGreaterThanOrEqual(6); + }); + + it('captures for_range_loop as @scope.block', () => { + const src = ` + #include + void f() { + std::vector v; + for (auto& x : v) { } + } + `; + const all = tagsFor(src); + const blocks = all.filter((t) => t.includes('@scope.block')); + expect(blocks.length).toBeGreaterThanOrEqual(1); + }); +}); + +// ── Declarations — classes / structs ──────────────────────────────────────── + +describe('emitCppScopeCaptures — class declarations', () => { + it('captures named class with @declaration.class', () => { + const m = findMatch('class Foo { int x; };', (t) => t.includes('@declaration.class')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('Foo'); + }); + + it('captures named struct with @declaration.struct', () => { + const m = findMatch('struct Point { int x; int y; };', (t) => + t.includes('@declaration.struct'), + ); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('Point'); + }); + + it('captures template class with @declaration.class', () => { + const m = findMatch('template class Container { T val; };', (t) => + t.includes('@declaration.class'), + ); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('Container'); + }); +}); + +// ── Declarations — namespaces ─────────────────────────────────────────────── + +describe('emitCppScopeCaptures — namespace declarations', () => { + it('captures named namespace with @declaration.namespace', () => { + const m = findMatch('namespace foo { int x; }', (t) => t.includes('@declaration.namespace')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('foo'); + }); + + it('anonymous namespace has no @declaration.namespace (only @scope.namespace)', () => { + const matches = allMatches('namespace { int x; }', (t) => t.includes('@declaration.namespace')); + // Anonymous namespace should NOT produce a @declaration.namespace + expect(matches.length).toBe(0); + }); +}); + +// ── Declarations — functions / methods ────────────────────────────────────── + +describe('emitCppScopeCaptures — function declarations', () => { + it('captures function definition with @declaration.function', () => { + const m = findMatch('void foo() {}', (t) => t.includes('@declaration.function')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('foo'); + }); + + it('captures function with pointer return as @declaration.function', () => { + const m = findMatch('int* create() {}', (t) => t.includes('@declaration.function')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('create'); + }); + + it('captures out-of-class method (qualified_identifier) as @declaration.method', () => { + const m = findMatch('void Foo::bar() {}', (t) => t.includes('@declaration.method')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('bar'); + }); + + it('captures destructor as @declaration.method', () => { + const m = findMatch('void Foo::~Foo() {}', (t) => t.includes('@declaration.method')); + expect(m).toBeDefined(); + // destructor_name includes the ~ + expect(m!['@declaration.name'].text).toContain('~'); + }); + + it('captures inline method (field_identifier) as @declaration.method', () => { + const src = 'class Foo { void bar() {} };'; + const m = findMatch(src, (t) => t.includes('@declaration.method')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('bar'); + }); + + it('captures function prototype as @declaration.function', () => { + const m = findMatch('void foo();', (t) => t.includes('@declaration.function')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('foo'); + }); + + it('captures template function as @declaration.function', () => { + const m = findMatch('template void foo(T x) {}', (t) => + t.includes('@declaration.function'), + ); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('foo'); + }); +}); + +// ── Declarations — fields ─────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — field declarations', () => { + it('captures plain field', () => { + const m = findMatch('class Foo { int val; };', (t) => t.includes('@declaration.field')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('val'); + }); + + it('captures pointer field', () => { + const m = findMatch('class Foo { int* ptr; };', (t) => t.includes('@declaration.field')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('ptr'); + }); + + it('captures reference field', () => { + const m = findMatch('class Foo { int& ref; };', (t) => t.includes('@declaration.field')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('ref'); + }); +}); + +// ── Declarations — variables ──────────────────────────────────────────────── + +describe('emitCppScopeCaptures — variable declarations', () => { + it('captures variable with initializer', () => { + const m = findMatch('int x = 42;', (t) => t.includes('@declaration.variable')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('x'); + }); +}); + +// ── Declarations — enums ──────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — enum declarations', () => { + it('captures enum with @declaration.enum', () => { + const m = findMatch('enum Color { Red, Green, Blue };', (t) => t.includes('@declaration.enum')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('Color'); + }); + + it('captures enum constants with @declaration.const', () => { + const matches = allMatches('enum Color { Red, Green, Blue };', (t) => + t.includes('@declaration.const'), + ); + expect(matches.length).toBe(3); + const names = matches.map((m) => m['@declaration.name'].text).sort(); + expect(names).toEqual(['Blue', 'Green', 'Red']); + }); +}); + +// ── Declarations — typedef / alias ────────────────────────────────────────── + +describe('emitCppScopeCaptures — typedef/alias declarations', () => { + it('captures typedef as @declaration.typedef', () => { + const m = findMatch('typedef int MyInt;', (t) => t.includes('@declaration.typedef')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('MyInt'); + }); + + it('captures using alias as @declaration.typedef', () => { + const m = findMatch('using MyInt = int;', (t) => t.includes('@declaration.typedef')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('MyInt'); + }); +}); + +// ── Declarations — macros ─────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — macro declarations', () => { + it('captures #define as @declaration.macro', () => { + const m = findMatch('#define MAX 100', (t) => t.includes('@declaration.macro')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('MAX'); + }); + + it('captures #define function as @declaration.macro', () => { + const m = findMatch('#define ADD(a,b) ((a)+(b))', (t) => t.includes('@declaration.macro')); + expect(m).toBeDefined(); + expect(m!['@declaration.name'].text).toBe('ADD'); + }); +}); + +// ── Imports ───────────────────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — imports', () => { + it('captures #include local as wildcard import', () => { + const m = findMatch('#include "foo.h"', (t) => t.includes('@import.source')); + expect(m).toBeDefined(); + expect(m!['@import.source'].text).toBe('foo.h'); + expect(m!['@import.kind'].text).toBe('wildcard'); + expect(m!['@import.system']).toBeUndefined(); + }); + + it('captures #include system with system marker', () => { + const m = findMatch('#include ', (t) => t.includes('@import.source')); + expect(m).toBeDefined(); + expect(m!['@import.source'].text).toBe('iostream'); + expect(m!['@import.system']).toBeDefined(); + }); + + it('captures using namespace as wildcard import', () => { + const m = findMatch('using namespace std;', (t) => t.includes('@import.using-namespace')); + expect(m).toBeDefined(); + expect(m!['@import.source'].text).toBe('std'); + expect(m!['@import.kind'].text).toBe('wildcard'); + }); + + it('captures using declaration as named import', () => { + const m = findMatch('using std::vector;', (t) => t.includes('@import.name')); + expect(m).toBeDefined(); + expect(m!['@import.source'].text).toBe('std'); + expect(m!['@import.name'].text).toBe('vector'); + expect(m!['@import.kind'].text).toBe('named'); + }); +}); + +// ── References ────────────────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — references', () => { + it('captures free call', () => { + const src = 'void f() { foo(); }'; + const m = findMatch(src, (t) => t.includes('@reference.call.free')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('foo'); + }); + + it('captures member call (obj.method())', () => { + const src = 'void f() { obj.method(); }'; + const m = findMatch(src, (t) => t.includes('@reference.call.member')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('method'); + }); + + it('captures member call (ptr->method())', () => { + const src = 'void f() { ptr->method(); }'; + const m = findMatch(src, (t) => t.includes('@reference.call.member')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('method'); + }); + + it('captures qualified call (Namespace::func())', () => { + const src = 'void f() { Foo::bar(); }'; + const m = findMatch(src, (t) => t.includes('@reference.call.qualified')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('bar'); + }); + + it('captures field read', () => { + const src = 'void f() { int x = obj.val; }'; + const m = findMatch(src, (t) => t.includes('@reference.read')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('val'); + }); + + it('captures field write', () => { + const src = 'void f() { obj.val = 42; }'; + const m = findMatch(src, (t) => t.includes('@reference.write')); + expect(m).toBeDefined(); + expect(m!['@reference.name'].text).toBe('val'); + }); +}); + +// ── Type bindings ─────────────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — type bindings', () => { + it('captures parameter type binding', () => { + const src = 'void foo(int x) {}'; + const m = findMatch(src, (t) => t.includes('@type-binding.parameter')); + expect(m).toBeDefined(); + expect(m!['@type-binding.name'].text).toBe('x'); + }); + + it('captures variable type binding', () => { + const src = 'int x = 42;'; + const m = findMatch(src, (t) => t.includes('@type-binding.assignment')); + expect(m).toBeDefined(); + expect(m!['@type-binding.name'].text).toBe('x'); + }); +}); + +// ── Arity enrichment ──────────────────────────────────────────────────────── + +describe('emitCppScopeCaptures — arity enrichment', () => { + it('enriches function declaration with parameter count', () => { + const m = findMatch('void foo(int x, int y) {}', (t) => + t.includes('@declaration.parameter-count'), + ); + expect(m).toBeDefined(); + expect(m!['@declaration.parameter-count'].text).toBe('2'); + }); + + it('enriches zero-parameter function', () => { + const m = findMatch('void foo() {}', (t) => t.includes('@declaration.parameter-count')); + expect(m).toBeDefined(); + expect(m!['@declaration.parameter-count'].text).toBe('0'); + }); + + it('detects default parameters (required < total)', () => { + const m = findMatch('void foo(int x, int y = 5) {}', (t) => + t.includes('@declaration.required-parameter-count'), + ); + expect(m).toBeDefined(); + expect(m!['@declaration.required-parameter-count'].text).toBe('1'); + expect(m!['@declaration.parameter-count'].text).toBe('2'); + }); + + it('enriches call reference with arity', () => { + const src = 'void f() { foo(1, 2, 3); }'; + const m = findMatch(src, (t) => t.includes('@reference.arity')); + expect(m).toBeDefined(); + expect(m!['@reference.arity'].text).toBe('3'); + }); +}); + +// ── Static / anonymous namespace detection ────────────────────────────────── + +describe('emitCppScopeCaptures — file-local linkage', () => { + beforeEach(() => { + clearFileLocalNames(); + }); + + it('detects static function as file-local', () => { + emitCppScopeCaptures('static void helper() {}', 'test.cpp'); + expect(isFileLocal('test.cpp', 'helper')).toBe(true); + }); + + it('does not mark non-static function as file-local', () => { + emitCppScopeCaptures('void helper() {}', 'test.cpp'); + expect(isFileLocal('test.cpp', 'helper')).toBe(false); + }); + + it('detects function in anonymous namespace as file-local', () => { + emitCppScopeCaptures('namespace { void helper() {} }', 'test.cpp'); + expect(isFileLocal('test.cpp', 'helper')).toBe(true); + }); + + it('does not mark function in named namespace as file-local', () => { + emitCppScopeCaptures('namespace foo { void helper() {} }', 'test.cpp'); + expect(isFileLocal('test.cpp', 'helper')).toBe(false); + }); +}); diff --git a/gitnexus/test/unit/scope-resolution/cpp/cpp-imports.test.ts b/gitnexus/test/unit/scope-resolution/cpp/cpp-imports.test.ts new file mode 100644 index 000000000..6bc6e1b86 --- /dev/null +++ b/gitnexus/test/unit/scope-resolution/cpp/cpp-imports.test.ts @@ -0,0 +1,161 @@ +/** + * Unit tests for C++ import decomposition, interpretation, and target resolution. + */ + +import { describe, it, expect } from 'vitest'; +import { getCppParser } from '../../../../src/core/ingestion/languages/cpp/query.js'; +import { + splitCppInclude, + splitCppUsingDecl, +} from '../../../../src/core/ingestion/languages/cpp/import-decomposer.js'; +import { interpretCppImport } from '../../../../src/core/ingestion/languages/cpp/interpret.js'; +import { resolveCppImportTarget } from '../../../../src/core/ingestion/languages/cpp/import-target.js'; +import type { SyntaxNode } from '../../../../src/core/ingestion/utils/ast-helpers.js'; + +function parseNode(src: string, type: string): SyntaxNode | null { + const tree = getCppParser().parse(src); + for (let i = 0; i < tree.rootNode.namedChildCount; i++) { + const child = tree.rootNode.namedChild(i); + if (child?.type === type) return child as SyntaxNode; + } + return null; +} + +function capt(name: string, text: string) { + return { name, text, range: { startLine: 1, startCol: 1, endLine: 1, endCol: 1 } }; +} + +// ── #include decomposition ────────────────────────────────────────────────── + +describe('C++ include decomposition (splitCppInclude)', () => { + it('decomposes local include "#include \\"foo.h\\""', () => { + const node = parseNode('#include "foo.h"', 'preproc_include'); + expect(node).not.toBeNull(); + const match = splitCppInclude(node!); + expect(match).not.toBeNull(); + expect(match!['@import.source'].text).toBe('foo.h'); + expect(match!['@import.kind'].text).toBe('wildcard'); + expect(match!['@import.system']).toBeUndefined(); + }); + + it('decomposes system include "#include "', () => { + const node = parseNode('#include ', 'preproc_include'); + expect(node).not.toBeNull(); + const match = splitCppInclude(node!); + expect(match).not.toBeNull(); + expect(match!['@import.source'].text).toBe('iostream'); + expect(match!['@import.system']).toBeDefined(); + }); + + it('decomposes C++ header include "#include \\"utils/helpers.hpp\\""', () => { + const node = parseNode('#include "utils/helpers.hpp"', 'preproc_include'); + expect(node).not.toBeNull(); + const match = splitCppInclude(node!); + expect(match).not.toBeNull(); + expect(match!['@import.source'].text).toBe('utils/helpers.hpp'); + }); +}); + +// ── using declaration decomposition ───────────────────────────────────────── + +describe('C++ using declaration decomposition (splitCppUsingDecl)', () => { + it('decomposes "using namespace std;" as wildcard import', () => { + const node = parseNode('using namespace std;', 'using_declaration'); + expect(node).not.toBeNull(); + const match = splitCppUsingDecl(node!); + expect(match).not.toBeNull(); + expect(match!['@import.kind'].text).toBe('wildcard'); + expect(match!['@import.source'].text).toBe('std'); + expect(match!['@import.using-namespace']).toBeDefined(); + }); + + it('decomposes "using std::vector;" as named import', () => { + const node = parseNode('using std::vector;', 'using_declaration'); + expect(node).not.toBeNull(); + const match = splitCppUsingDecl(node!); + expect(match).not.toBeNull(); + expect(match!['@import.kind'].text).toBe('named'); + expect(match!['@import.source'].text).toBe('std'); + expect(match!['@import.name'].text).toBe('vector'); + }); + + it('decomposes nested namespace "using namespace foo::bar;"', () => { + const node = parseNode('using namespace foo::bar;', 'using_declaration'); + expect(node).not.toBeNull(); + const match = splitCppUsingDecl(node!); + expect(match).not.toBeNull(); + expect(match!['@import.kind'].text).toBe('wildcard'); + expect(match!['@import.source'].text).toBe('foo::bar'); + }); +}); + +// ── Import interpretation ─────────────────────────────────────────────────── + +describe('C++ import interpretation (interpretCppImport)', () => { + it('interprets local include as wildcard import', () => { + const result = interpretCppImport({ + '@import.kind': capt('@import.kind', 'wildcard'), + '@import.source': capt('@import.source', 'header.hpp'), + }); + expect(result).toEqual({ kind: 'wildcard', targetRaw: 'header.hpp' }); + }); + + it('returns null for system headers', () => { + const result = interpretCppImport({ + '@import.kind': capt('@import.kind', 'wildcard'), + '@import.source': capt('@import.source', 'iostream'), + '@import.system': capt('@import.system', 'true'), + }); + expect(result).toBeNull(); + }); + + it('interprets named import (using std::vector)', () => { + const result = interpretCppImport({ + '@import.kind': capt('@import.kind', 'named'), + '@import.source': capt('@import.source', 'std'), + '@import.name': capt('@import.name', 'vector'), + }); + expect(result).not.toBeNull(); + expect(result!.kind).toBe('named'); + expect(result!.targetRaw).toBe('std'); + }); + + it('returns null when @import.source is missing', () => { + const result = interpretCppImport({ + '@import.kind': capt('@import.kind', 'wildcard'), + }); + expect(result).toBeNull(); + }); +}); + +// ── Import target resolution ──────────────────────────────────────────────── + +describe('C++ import target resolution (resolveCppImportTarget)', () => { + it('resolves .hpp header', () => { + const result = resolveCppImportTarget('foo.hpp', 'main.cpp', new Set(['foo.hpp', 'bar.cpp'])); + expect(result).toBe('foo.hpp'); + }); + + it('resolves .hxx header', () => { + const result = resolveCppImportTarget('foo.hxx', 'main.cpp', new Set(['foo.hxx'])); + expect(result).toBe('foo.hxx'); + }); + + it('prefers same-directory sibling', () => { + const result = resolveCppImportTarget( + 'bar.hpp', + 'src/foo.cpp', + new Set(['include/bar.hpp', 'src/bar.hpp']), + ); + expect(result).toBe('src/bar.hpp'); + }); + + it('resolves suffix match with depth tiebreak', () => { + const result = resolveCppImportTarget('foo.h', 'main.cpp', new Set(['a/b/c/foo.h', 'z/foo.h'])); + expect(result).toBe('z/foo.h'); + }); + + it('returns null for no match', () => { + expect(resolveCppImportTarget('missing.hpp', 'main.cpp', new Set(['foo.h']))).toBeNull(); + }); +}); From 75cb49477ea313f0258391251ea07dc37fcf4b7a Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 12:25:05 +0100 Subject: [PATCH 25/33] feat(cpp): emit EXTENDS edges for template and qualified template bases (#1581) * Initial plan * fix: emit cpp extends edges for template bases Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/eaddb1ac-7b57-4f44-94ba-a07a578d078d Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * chore: address final review notes Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/eaddb1ac-7b57-4f44-94ba-a07a578d078d Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix: keep cpp extends edges class-owned Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/b10bbb4d-6746-46fa-9b82-5c0962cd8b3f Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test: address cpp follow-up review findings Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/be67e437-055f-4a71-a24e-d3bfb87ad0cd Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --- .../core/ingestion/languages/cpp/captures.ts | 73 +++++++++++++++-- .../src/core/ingestion/languages/cpp/query.ts | 19 +++++ .../contract/scope-resolver.ts | 3 + .../scope-resolution/pipeline/run.ts | 79 ++++++++++++++++++- .../base.h | 7 ++ .../derived.h | 6 ++ .../base.h | 12 +++ .../derived.h | 11 +++ .../test/integration/resolvers/cpp.test.ts | 72 +++++++++++++---- .../test/integration/resolvers/helpers.ts | 7 +- 10 files changed, 262 insertions(+), 27 deletions(-) create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/derived.h diff --git a/gitnexus/src/core/ingestion/languages/cpp/captures.ts b/gitnexus/src/core/ingestion/languages/cpp/captures.ts index e6d63635a..325742bfb 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/captures.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/captures.ts @@ -301,6 +301,13 @@ export function emitCppScopeCaptures( out.push(grouped); } + // ── Emit inheritance references for scope-resolution MRO / EXTENDS ── + // Walk every class/struct base list and synthesize `@reference.inherits` + // captures consumed by the registry-primary graph bridge. The lookup name + // is normalized to the bare class name so `Base` / `outer::v1::Base` + // resolve through V1's simple-name `findClassBindingInScope('Base')`. + emitCppInheritanceCaptures(tree.rootNode, out); + // ── Detect dependent-base relationships for two-phase template lookup ── // Walk the tree once, finding every `template_declaration` whose // child is a class/struct definition with a `base_class_clause` whose @@ -314,6 +321,40 @@ export function emitCppScopeCaptures( return out; } +/** + * Walk every C++ class/struct base clause and emit `@reference.inherits` + * captures for each base so scope resolution can resolve them into EXTENDS + * edges. Lookup names are normalized to bare class names (`Base` → `Base`, + * `outer::v1::Base` → `Base`) to match the V1 simple-name + * `findClassBindingInScope` contract. This intentionally preserves the + * existing scope-chain tradeoff: qualified namespace context is discarded + * here instead of introducing a C++-only name-resolution lane in shared + * ingestion infrastructure. + */ +function emitCppInheritanceCaptures(root: SyntaxNode, out: CaptureMatch[]): void { + const stack: SyntaxNode[] = [root]; + while (stack.length > 0) { + const node = stack.pop()!; + if (node.type === 'class_specifier' || node.type === 'struct_specifier') { + const baseClause = findChildOfType(node, ['base_class_clause']); + if (baseClause !== null) { + for (const base of iterBaseClasses(baseClause)) { + const baseName = extractBaseLookupName(base); + if (baseName.length === 0) continue; + out.push({ + '@reference.inherits': nodeToCapture('@reference.inherits', base), + '@reference.name': syntheticCapture('@reference.name', base, baseName), + }); + } + } + } + for (let i = 0; i < node.childCount; i++) { + const child = node.child(i); + if (child !== null) stack.push(child); + } + } +} + /** * Walk the AST finding every template_declaration containing a class or * struct definition with a dependent base. Records (className, baseName) @@ -344,7 +385,7 @@ function detectCppDependentBases(root: SyntaxNode, filePath: string): void { if (baseClause !== null) { for (const base of iterBaseClasses(baseClause)) { if (isBaseDependent(base, params)) { - const baseName = extractBaseSimpleName(base); + const baseName = extractBaseLookupName(base); if (baseName !== '') { markCppDependentBase(filePath, className, baseName); } @@ -461,19 +502,35 @@ function isBaseDependent(baseNode: SyntaxNode, templateParams: Set): boo return false; } -/** Extract the simple name of a base class node. */ -function extractBaseSimpleName(baseNode: SyntaxNode): string { - if (baseNode.type === 'type_identifier') return baseNode.text; +/** + * Recursively extract the bare lookup name of a base class node. + * Examples: `Base` → `Base`, `Base` → `Base`, + * `outer::v1::Base` → `Base`. Namespace qualifiers are intentionally + * dropped to align with V1 scope-chain lookup everywhere else in the + * registry-primary pipeline. + */ +function extractBaseLookupName(baseNode: SyntaxNode): string { + if (baseNode.type === 'type_identifier' || baseNode.type === 'identifier') return baseNode.text; if (baseNode.type === 'template_type') { const nameNode = baseNode.childForFieldName('name'); - if (nameNode !== null) return nameNode.text; - // Fallback: first type_identifier descendant. - const id = findFirstDescendantOfType(baseNode, 'type_identifier'); + if (nameNode !== null) return extractBaseLookupName(nameNode); + const id = + findFirstDescendantOfType(baseNode, 'type_identifier') ?? + findFirstDescendantOfType(baseNode, 'identifier'); if (id !== null) return id.text; } if (baseNode.type === 'qualified_identifier') { const nameNode = baseNode.childForFieldName('name'); - if (nameNode !== null) return nameNode.text; + if (nameNode !== null) { + const nested = extractBaseLookupName(nameNode); + if (nested.length > 0) return nested; + } + for (let i = baseNode.childCount - 1; i >= 0; i--) { + const child = baseNode.child(i); + if (child === null) continue; + const nested = extractBaseLookupName(child); + if (nested.length > 0) return nested; + } } return ''; } diff --git a/gitnexus/src/core/ingestion/languages/cpp/query.ts b/gitnexus/src/core/ingestion/languages/cpp/query.ts index 4e451617d..0e6a0a7ae 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/query.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/query.ts @@ -417,6 +417,25 @@ const CPP_SCOPE_QUERY = ` scope: (_) @reference.receiver name: (identifier) @reference.name)) @reference.call.qualified +;; Nested qualified receiver: outer::v1::Base::f() +;; tree-sitter-cpp nests this as qualified_identifier(name: +;; qualified_identifier(scope: qualified_identifier(...), name: identifier)). +;; Capturing the innermost receiver still gives isSuperReceiverInContext +;; enough text to strip qualifiers/template args down to Base. +(call_expression + function: (qualified_identifier + name: (qualified_identifier + scope: (_) @reference.receiver + name: (identifier) @reference.name))) @reference.call.qualified + +;; Double-nested qualified receiver: outer::v1::Base::f() +(call_expression + function: (qualified_identifier + name: (qualified_identifier + name: (qualified_identifier + scope: (_) @reference.receiver + name: (identifier) @reference.name)))) @reference.call.qualified + ;; ─── References — member calls (obj.method() / ptr->method()) ─────── (call_expression function: (field_expression diff --git a/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts b/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts index d7b3618a2..d29b6efa8 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts @@ -87,6 +87,9 @@ * attempting emission (even on dedup-collapse), because the * per-(caller, target) collapse semantics require multiple call * sites in the same caller body not produce multiple edges. + * `preEmitInheritanceEdges` also pre-marks every `inherits` site so + * the generic bridge cannot remap class heritage into method-owned + * EXTENDS edges via `resolveCallerGraphId`. * * - **I3 — `propagateImportedReturnTypes` mutation timing + ordering.** * The pass mutates `Scope.typeBindings` (a plain `new Map(...)` from diff --git a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts index 4f74cfce2..0809d59ca 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/pipeline/run.ts @@ -32,16 +32,88 @@ import { extractParsedFile } from '../../scope-extractor-bridge.js'; import { finalizeScopeModel } from '../../finalize-orchestrator.js'; import { resolveReferenceSites, type ResolveStats } from '../../resolve-references.js'; import { buildGraphNodeLookup } from '../graph-bridge/node-lookup.js'; +import { resolveDefGraphId } from '../graph-bridge/ids.js'; import { buildPopulatedMethodDispatch } from '../graph-bridge/method-dispatch.js'; +import { tryEmitEdge } from '../graph-bridge/edges.js'; import { propagateImportedReturnTypes } from '../passes/imported-return-types.js'; import { emitReceiverBoundCalls } from '../passes/receiver-bound-calls.js'; import { emitFreeCallFallback } from '../passes/free-call-fallback.js'; import { emitReferencesViaLookup } from '../graph-bridge/references-to-edges.js'; import { emitImportEdges } from '../graph-bridge/imports-to-edges.js'; import type { ScopeResolver } from '../contract/scope-resolver.js'; +import { findClassBindingInScope, findEnclosingClassDef } from '../scope/walkers.js'; import { buildWorkspaceResolutionIndex } from '../workspace-index.js'; import { logger } from '../../../logger.js'; + +/** + * Resolve inheritance reference sites early and pre-emit their EXTENDS edges + * before MRO construction. This lets template-base captures contribute to the + * graph in time for `buildMro`, while `handledSites` prevents the generic + * reference-edge bridge from re-emitting the same sites later. + * + * @returns Site keys to seed the downstream handled-site skip set. + */ +function preEmitInheritanceEdges( + graph: KnowledgeGraph, + scopes: ReturnType, + nodeLookup: ReturnType, +): Set { + const handledSites = new Set(); + const seen = new Set(); + const existing = new Set(); + for (const rel of graph.iterRelationshipsByType('EXTENDS')) { + existing.add(`${rel.sourceId}->${rel.targetId}`); + } + + for (const site of scopes.referenceSites) { + if (site.kind !== 'inherits') continue; + const scope = scopes.scopeTree.getScope(site.inScope); + const siteKey = + scope?.filePath !== undefined + ? `${scope.filePath}:${site.atRange.startLine}:${site.atRange.startCol}` + : undefined; + if (siteKey !== undefined) { + // Intentionally suppress every `inherits` site from the generic + // reference bridge, even when this pre-pass can't emit an EXTENDS + // edge. The shared bridge resolves the source via + // `resolveCallerGraphId`, which can degrade class-heritage sites into + // method-owned EXTENDS edges once methods exist on the class. This + // pre-pass is the authoritative inheritance emitter, so broad + // suppression keeps `buildMro` and the final graph class-owned. + handledSites.add(siteKey); + } + + const targetDef = findClassBindingInScope(site.inScope, site.name, scopes); + if (targetDef === undefined) continue; + + const callerClass = findEnclosingClassDef(site.inScope, scopes); + if (callerClass === undefined) continue; + const callerGraphId = resolveDefGraphId(callerClass.filePath, callerClass, nodeLookup); + const targetGraphId = resolveDefGraphId(targetDef.filePath, targetDef, nodeLookup); + if (callerGraphId === undefined || targetGraphId === undefined) continue; + const edgeKey = `${callerGraphId}->${targetGraphId}`; + if (existing.has(edgeKey)) continue; + + if ( + tryEmitEdge( + graph, + scopes, + nodeLookup, + site, + targetDef, + 'scope-resolution: inherits', + seen, + 0.85, + ) + ) { + existing.add(edgeKey); + } + } + + return handledSites; +} + interface RunScopeResolutionInput { readonly graph: KnowledgeGraph; /** @@ -183,8 +255,6 @@ export function runScopeResolution( // ── Phase 2: finalize → ScopeResolutionIndexes ───────────────────────── const allFilePaths = new Set(parsedFiles.map((f) => f.filePath)); const nodeLookup = buildGraphNodeLookup(graph); - const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup); - const extendsOnlyMroByClassDefId = provider.buildExtendsOnlyMro?.(graph, parsedFiles, nodeLookup); const resolutionConfig = input.resolutionConfig; const finalized = finalizeScopeModel(parsedFiles, { @@ -197,6 +267,9 @@ export function runScopeResolution( provider.mergeBindings(existing, incoming, scopeId), }, }); + const preEmittedInheritanceSites = preEmitInheritanceEdges(graph, finalized, nodeLookup); + const mroByClassDefId = provider.buildMro(graph, parsedFiles, nodeLookup); + const extendsOnlyMroByClassDefId = provider.buildExtendsOnlyMro?.(graph, parsedFiles, nodeLookup); // Replace the empty MethodDispatchIndex that finalizeScopeModel // builds by design with the populated one derived from the @@ -273,7 +346,7 @@ export function runScopeResolution( const tResolve = PROF ? process.hrtime.bigint() : 0n; // ── Phase 4: emit graph edges (LOAD-BEARING ORDER — see I1) ──────────── - const handledSites = new Set(); + const handledSites = new Set(preEmittedInheritanceSites); const receiverExtras = emitReceiverBoundCalls( graph, indexes, diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/base.h new file mode 100644 index 000000000..30b2f5bd6 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/base.h @@ -0,0 +1,7 @@ +#pragma once + +template +struct A {}; + +template +struct B {}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/derived.h new file mode 100644 index 000000000..7fe417b6a --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-template-multi-base-list/derived.h @@ -0,0 +1,6 @@ +#pragma once + +#include "base.h" + +template +struct Derived : A, B {}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/base.h new file mode 100644 index 000000000..de3e84def --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/base.h @@ -0,0 +1,12 @@ +#pragma once + +namespace outer { + inline namespace v1 { + template + struct Base { + void f(); + }; + + void free_fn(); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/derived.h new file mode 100644 index 000000000..2ff5523a1 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-phase5-u1-u3-u5-qualified-inline-base-call/derived.h @@ -0,0 +1,11 @@ +#pragma once + +#include "base.h" + +template +struct Derived : outer::v1::Base { + void g() { + outer::v1::Base::f(); + outer::v1::free_fn(); + } +}; diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index 1f6135408..bcc90350a 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -2098,7 +2098,7 @@ describe('C++ inline namespace — ADL participation', () => { // U3 (two-phase lookup), and U5 (inline namespaces). // --------------------------------------------------------------------------- -describe('C++ Phase 5 U1×U3 — qualified Base::method() inside template body (no false positives)', () => { +describe('C++ Phase 5 U1×U3 — qualified Base::method() inside template body', () => { let result: PipelineResult; beforeAll(async () => { @@ -2108,22 +2108,33 @@ describe('C++ Phase 5 U1×U3 — qualified Base::method() inside template bod ); }, 60000); - it('Base::method() does NOT mis-route to a class method outside the MRO', () => { + it('emits EXTENDS edge: Derived → Base for template base Base', () => { + const extends_ = getRelationships(result, 'EXTENDS'); + expect(edgeSet(extends_)).toContain('Derived → Base'); + }); + + it('Base::method() resolves to Base::method inside template body', () => { const calls = getRelationships(result, 'CALLS'); const methodCalls = calls.filter((c) => c.source === 'g' && c.target === 'method'); - // V1 documented gap: cross-file (and same-file) template-class - // inheritance is not captured as an EXTENDS edge by the legacy DAG - // (the cpp captures.ts has no `base_class_clause` heritage emitter - // for template_type bases). Without an EXTENDS edge, MRO is empty - // and the U1 super branch can't dispatch. Result: 0 CALLS edges. - // - // This Phase 5 cross-unit composition test locks in that the - // template-arg-stripping U1 logic produces NO false positives — - // `Base` correctly classifies as a super-receiver candidate but - // (due to empty MRO) doesn't accidentally route to an unrelated - // method named `method` via any other case. count > 0 here would - // indicate the U1 stripped lookup mis-resolved across cases. - expect(methodCalls.length).toBe(0); + expect(methodCalls.length).toBe(1); + expect(methodCalls[0].targetFilePath).toContain('classes.h'); + }); +}); + +describe('C++ Phase 5 U1×U3 — template multi-base list', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-phase5-u1-u3-template-multi-base-list'), + () => {}, + ); + }, 60000); + + it('emits EXTENDS edges: Derived → A, Derived → B for template multi-base list', () => { + const extends_ = getRelationships(result, 'EXTENDS'); + expect(extends_.length).toBe(2); + expect(edgeSet(extends_)).toEqual(['Derived → A', 'Derived → B']); }); }); @@ -2183,3 +2194,34 @@ describe('C++ Phase 5 U3×U5 — template Derived : outer::v1::Base (inline)' expect(fLeaks.length).toBe(0); }); }); + +describe('C++ Phase 5 U1×U3×U5 — qualified outer::v1::Base::f() inside template body', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-phase5-u1-u3-u5-qualified-inline-base-call'), + () => {}, + ); + }, 60000); + + it('emits EXTENDS edge: Derived → Base for qualified template base outer::v1::Base', () => { + const extends_ = getRelationships(result, 'EXTENDS'); + expect(edgeSet(extends_)).toContain('Derived → Base'); + }); + + it('outer::v1::Base::f() resolves to Base::f inside template body', () => { + const calls = getRelationships(result, 'CALLS'); + const fCalls = calls.filter((c) => c.source === 'g' && c.target === 'f'); + expect(fCalls.length).toBe(1); + expect(fCalls[0].targetFilePath).toContain('base.h'); + }); + + it('outer::v1::free_fn() resolves as a namespace free function, not a super-receiver method', () => { + const calls = getRelationships(result, 'CALLS'); + const freeCalls = calls.filter((c) => c.source === 'g' && c.target === 'free_fn'); + expect(freeCalls.length).toBe(1); + expect(freeCalls[0].targetLabel).toBe('Function'); + expect(freeCalls[0].rel.reason).toBe('import-resolved'); + }); +}); diff --git a/gitnexus/test/integration/resolvers/helpers.ts b/gitnexus/test/integration/resolvers/helpers.ts index 7cbfaaf6c..418bbc0fb 100644 --- a/gitnexus/test/integration/resolvers/helpers.ts +++ b/gitnexus/test/integration/resolvers/helpers.ts @@ -155,8 +155,13 @@ const LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES: Readonly::method() does NOT mis-route to a class method outside the MRO', + 'emits EXTENDS edge: Derived → Base for template base Base', + 'emits EXTENDS edges: Derived → A, Derived → B for template multi-base list', + 'Base::method() resolves to Base::method inside template body', 'unqualified f() inside Derived::g() does NOT bind to outer::v1::Base::f (dependent base across inline namespace)', + 'emits EXTENDS edge: Derived → Base for qualified template base outer::v1::Base', + 'outer::v1::Base::f() resolves to Base::f inside template body', + 'outer::v1::free_fn() resolves as a namespace free function, not a super-receiver method', ]), }; From c901ee4666c47c09fcf21887613c9084c582a3ec Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 13:06:39 +0100 Subject: [PATCH 26/33] fix(cpp): workspace-wide dependent-base name resolution for cross-file templates (#1586) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * fix(cpp): workspace-wide dependent-base name resolution (cross-file support) - Replace per-file `populateCppDependentBases(parsed)` with a workspace-wide `populateCppDependentBases(parsedFiles)` that builds a cross-file class index - Use qualified-name prefix for namespace disambiguation when multiple classes share a simple name (e.g. `Box` in two namespaces) - Move the call from `populateOwners` (per-file) to the new `populateWorkspaceOwners` hook so all files are processed before resolution runs - Add `cpp-two-phase-dependent-base-ns` fixture: Base in a namespace in a separate file from Derived, plus a namespace-free function with the same name — exercises the path where the class-owned filter does not apply - Add two integration tests for the new fixture" Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/d78fae8b-cd32-45d8-a815-2b27d7d89e62 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix(cpp): clarify V1 conservative exact-prefix namespace match in two-phase-lookup Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/d78fae8b-cd32-45d8-a815-2b27d7d89e62 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Gergő Magyar Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --- .../ingestion/languages/cpp/scope-resolver.ts | 13 +- .../languages/cpp/two-phase-lookup.ts | 126 ++++++++++++++---- .../cpp-two-phase-dependent-base-ns/base.h | 19 +++ .../cpp-two-phase-dependent-base-ns/derived.h | 21 +++ .../test/integration/resolvers/cpp.test.ts | 31 +++++ 5 files changed, 179 insertions(+), 31 deletions(-) create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/derived.h diff --git a/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts index a85e5b113..02aaff3bf 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts @@ -101,16 +101,21 @@ export const cppScopeResolver: ScopeResolver = { // fallback and wildcard expansion can suppress them as unqualified // cross-file callables. populateCppNonGloballyVisible(parsed); - // Resolve recorded template-class → dependent-base simple names to - // class nodeIds for two-phase template lookup (U3 of plan - // 2026-05-13-001). - populateCppDependentBases(parsed); // Build the class-def → enclosing-namespace-qualified-name map used // by ADL (U2 of plan 2026-05-13-001) to identify each argument type's // associated namespace for Koenig lookup. populateCppAssociatedNamespaces(parsed); }, + // Resolve recorded template-class → dependent-base simple names to + // class nodeIds for two-phase template lookup (U3 of plan + // 2026-05-13-001). Runs AFTER all files have had `populateOwners` + // applied so that cross-file base classes (e.g. Base in base.h, + // Derived in derived.h) are reachable in the workspace index. + populateWorkspaceOwners: (parsedFiles: readonly ParsedFile[]) => { + populateCppDependentBases(parsedFiles); + }, + // Simple `isSuperReceiver` returns false for C++. Real super // classification is caller-context-dependent and lives in // `isSuperReceiverInContext` below — without scope context the diff --git a/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts b/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts index 7840ed81a..8d0050eb1 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/two-phase-lookup.ts @@ -11,8 +11,20 @@ * 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 the workspace registry, building the per-class set the - * `isDependentBaseMember` predicate consumes. + * using a workspace-wide registry, building the per-class set the + * `isCppDependentBaseMember` predicate consumes. + * + * Cross-file resolution: `Base` may be declared in a different header + * than `Derived`. `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 @@ -69,37 +81,97 @@ export function clearCppDependentBases(): void { } /** - * Resolve recorded dependent-base simple names to class nodeIds using - * the parsed file's localDefs. Run as part of `populateOwners` so the - * resolved set is available before any resolution pass consults it. + * 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. * - * Matches by simple name within the same file (the template class and - * its base are typically declared in the same TU; cross-file template - * bases are an edge case deferred to V2). + * 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(parsed: ParsedFile): void { - const perFile = dependentBasesByFile.get(parsed.filePath); - if (perFile === undefined) return; +export function populateCppDependentBases(parsedFiles: readonly ParsedFile[]): void { + if (dependentBasesByFile.size === 0) return; - // Build simple-name → nodeId index for this file's class-like defs. - const classByName = new Map(); - for (const def of parsed.localDefs) { - if (def.type !== 'Class' && def.type !== 'Struct' && def.type !== 'Interface') continue; - const simple = def.qualifiedName?.split('.').pop() ?? def.qualifiedName ?? ''; - if (simple !== '') classByName.set(simple, def.nodeId); + // 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 }); + } } - for (const [className, baseNames] of perFile) { - const classNodeId = classByName.get(className); - if (classNodeId === undefined) continue; - let bases = dependentBaseNodeIds.get(classNodeId); - if (bases === undefined) { - bases = new Set(); - dependentBaseNodeIds.set(classNodeId, bases); + // 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 baseName of baseNames) { - const baseNodeId = classByName.get(baseName); - if (baseNodeId !== undefined) bases.add(baseNodeId); + + 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. + } } } } diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/base.h new file mode 100644 index 000000000..c9ecf5c22 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/base.h @@ -0,0 +1,19 @@ +#pragma once + +namespace geom { + +template +struct Base { + void compute(); + int area; +}; + +// Free function inside the same namespace — no ownerId, so the +// class-owned filter does NOT apply to this candidate. It is instead +// suppressed by the namespace-nesting filter (isCppDefGloballyVisible). +// The test therefore exercises a candidate path that is orthogonal to +// the class-owned filter, proving the overall suppression stack is +// robust even when ownerId-based blocking is absent. +void compute(); + +} // namespace geom diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/derived.h new file mode 100644 index 000000000..9596bcc81 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-dependent-base-ns/derived.h @@ -0,0 +1,21 @@ +#pragma once + +#include "base.h" + +namespace geom { + +template +struct Derived : Base { + // Unqualified call to compute() inside a template body whose base is + // dependent. Two-phase lookup: the compiler does NOT look into + // Base for this name — so GitNexus must also suppress the edge. + void g() { + compute(); + } + // Unqualified field access — same reasoning applies. + int h() { + return area; + } +}; + +} // namespace geom diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index bcc90350a..26fb02d36 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -1903,6 +1903,37 @@ describe('C++ two-phase template lookup — dependent base suppression', () => { // and template-body member-lookup work tracked separately. See plan // 2026-05-13-001 follow-ups. +// --------------------------------------------------------------------------- +// U3 cross-file namespace variant: Base lives in a different file AND +// inside a namespace. The fixture also contains a free function with the +// same name inside the namespace — that candidate has no ownerId, so the +// class-owned filter does NOT apply to it; it is instead suppressed by the +// namespace-nesting filter. Both candidates must still yield zero edges. +// --------------------------------------------------------------------------- + +describe('C++ two-phase template lookup — cross-file namespace variant', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-two-phase-dependent-base-ns'), + () => {}, + ); + }, 60000); + + it('geom::Derived::g() -> compute() does NOT bind to geom::Base::compute (cross-file dependent base, class-owned)', () => { + const calls = getRelationships(result, 'CALLS'); + const leaks = calls.filter((c) => c.source === 'g' && c.target === 'compute'); + expect(leaks.length).toBe(0); + }); + + it('geom::Derived::h() -> area does NOT bind to geom::Base::area (cross-file dependent base, class-owned)', () => { + const accesses = getRelationships(result, 'ACCESSES'); + const leaks = accesses.filter((c) => c.source === 'h' && c.target === 'area'); + expect(leaks.length).toBe(0); + }); +}); + // --------------------------------------------------------------------------- // U2 (follow-up plan 2026-05-13-001): argument-dependent (Koenig) lookup. // Free-function calls with class-typed arguments must consider candidates From 586dbf7aa1a2b4ba9b03b1b374ebd641df61f032 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 15:00:29 +0100 Subject: [PATCH 27/33] feat(cpp): disambiguate template specializations in class graph IDs and receiver routing (#1587) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * fix(cpp): disambiguate template specializations in class graph IDs Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/c929edb2-f2e9-41c6-a2e9-2092b967f603 * fix(cpp): guard template-specialization class lookup fallback Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/c929edb2-f2e9-41c6-a2e9-2092b967f603 * fix(cpp): address github-actions inline review findings Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/68d8fbac-4ff4-47f7-b732-eaf2c2f94043 * fix(cpp): cover template-type receiver binding for specialization routing Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/9505dfcd-3fb6-4bc2-a134-f60fe0dc8cd9 * chore(cpp): clarify specialization-binding fallback assumptions Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/9505dfcd-3fb6-4bc2-a134-f60fe0dc8cd9 --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Gergő Magyar --- .../src/scope-resolution/symbol-definition.ts | 2 + .../class-extractors/configs/c-cpp.ts | 57 ++++++++++++++ .../ingestion/class-extractors/generic.ts | 10 +++ gitnexus/src/core/ingestion/class-types.ts | 16 ++++ .../core/ingestion/languages/cpp/interpret.ts | 14 ++-- .../src/core/ingestion/languages/cpp/query.ts | 31 ++++++++ .../src/core/ingestion/model/symbol-table.ts | 4 + .../src/core/ingestion/parsing-processor.ts | 49 +++++++++++- .../src/core/ingestion/scope-extractor.ts | 5 ++ .../scope-resolution/graph-bridge/ids.ts | 20 ++++- .../graph-bridge/node-lookup.ts | 17 ++++ .../passes/receiver-bound-calls.ts | 53 ++++++++++++- .../src/core/ingestion/tree-sitter-queries.ts | 13 ++++ .../src/core/ingestion/utils/ast-helpers.ts | 12 ++- .../ingestion/utils/template-arguments.ts | 57 ++++++++++++++ .../core/ingestion/workers/parse-worker.ts | 51 +++++++++++- .../app.cpp | 7 ++ .../list_order.h | 14 ++++ .../list_user.h | 14 ++++ .../test/integration/resolvers/cpp.test.ts | 78 +++++++++++++++++++ .../test/integration/resolvers/helpers.ts | 6 ++ 21 files changed, 517 insertions(+), 13 deletions(-) create mode 100644 gitnexus/src/core/ingestion/utils/template-arguments.ts create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_order.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_user.h diff --git a/gitnexus-shared/src/scope-resolution/symbol-definition.ts b/gitnexus-shared/src/scope-resolution/symbol-definition.ts index d07dbf38b..7f9840f5c 100644 --- a/gitnexus-shared/src/scope-resolution/symbol-definition.ts +++ b/gitnexus-shared/src/scope-resolution/symbol-definition.ts @@ -30,6 +30,8 @@ export interface SymbolDefinition { returnType?: string; /** Declared type for non-callable symbols — fields/properties (e.g. 'Address', 'List') */ declaredType?: string; + /** Generic/template specialization arguments for class-like symbols (e.g. ['User'], ['T*']). */ + templateArguments?: string[]; /** Links Method/Constructor/Property to owning Class/Struct/Trait nodeId */ ownerId?: string; } diff --git a/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts b/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts index fcc1a22bf..fb5df99c3 100644 --- a/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts +++ b/gitnexus/src/core/ingestion/class-extractors/configs/c-cpp.ts @@ -2,6 +2,40 @@ import { SupportedLanguages } from 'gitnexus-shared'; import type { ClassExtractionConfig } from '../../class-types.js'; +import { + extractTemplateArguments, + stripTemplateArguments, +} from '../../utils/template-arguments.js'; + +function shouldSkipCppTemplateDuplicateCapture( + captureMap: Record, + definitionName: string | undefined, + capturedName: string | undefined, +): boolean { + if (captureMap['template-arguments'] !== undefined) return false; + if (!definitionName) return false; + const argsFromDefinitionName = extractTemplateArguments(definitionName); + if (argsFromDefinitionName === undefined) return false; + const argsFromCaptureName = capturedName ? extractTemplateArguments(capturedName) : undefined; + // Generic class capture emits only `List`, while the specialization-aware + // capture emits `List` + `@declaration.template-arguments`. Skip the former + // when the declaration name itself is templated to avoid duplicate class defs. + return argsFromCaptureName === undefined; +} + +function extractCppTemplateArgumentsWithFallback( + captureMap: Record, + definitionName: string | undefined, + capturedName: string | undefined, +): string[] | undefined { + return ( + (captureMap['template-arguments'] + ? extractTemplateArguments(captureMap['template-arguments'].text) + : undefined) ?? + (definitionName ? extractTemplateArguments(definitionName) : undefined) ?? + (capturedName ? extractTemplateArguments(capturedName) : undefined) + ); +} export const cClassConfig: ClassExtractionConfig = { language: SupportedLanguages.C, @@ -12,4 +46,27 @@ export const cppClassConfig: ClassExtractionConfig = { language: SupportedLanguages.CPlusPlus, typeDeclarationNodes: ['class_specifier', 'struct_specifier', 'enum_specifier'], ancestorScopeNodeTypes: ['namespace_definition', 'class_specifier', 'struct_specifier'], + extractName: (node) => { + const nameNode = node.childForFieldName?.('name'); + if (!nameNode) return undefined; + if (nameNode.type !== 'template_type') return undefined; + return stripTemplateArguments(nameNode.text); + }, + extractTemplateArguments: (node) => { + const nameNode = node.childForFieldName?.('name'); + if (!nameNode || nameNode.type !== 'template_type') return undefined; + return extractTemplateArguments(nameNode.text); + }, + shouldSkipClassCapture: ({ captureMap, definitionNode, nameNode }) => + shouldSkipCppTemplateDuplicateCapture( + captureMap, + definitionNode?.childForFieldName?.('name')?.text, + nameNode?.text, + ), + extractTemplateArgumentsFromCapture: ({ captureMap, definitionNode, nameNode }) => + extractCppTemplateArgumentsWithFallback( + captureMap, + definitionNode?.childForFieldName?.('name')?.text, + nameNode?.text, + ), }; diff --git a/gitnexus/src/core/ingestion/class-extractors/generic.ts b/gitnexus/src/core/ingestion/class-extractors/generic.ts index 303eb80c0..5f20d1dc2 100644 --- a/gitnexus/src/core/ingestion/class-extractors/generic.ts +++ b/gitnexus/src/core/ingestion/class-extractors/generic.ts @@ -154,10 +154,12 @@ export function createClassExtractor(config: ClassExtractionConfig): ClassExtrac if (!name || !type) return null; + const templateArguments = config.extractTemplateArguments?.(node); return { name, type, qualifiedName: buildQualifiedName(node, name) || name, + ...(templateArguments !== undefined ? { templateArguments } : {}), }; }; @@ -173,5 +175,13 @@ export function createClassExtractor(config: ClassExtractionConfig): ClassExtrac extractQualifiedName(node: SyntaxNode, simpleName: string): string | null { return extract(node, { name: simpleName })?.qualifiedName ?? null; }, + + shouldSkipClassCapture(context): boolean { + return config.shouldSkipClassCapture?.(context) ?? false; + }, + + extractTemplateArgumentsFromCapture(context): string[] | undefined { + return config.extractTemplateArgumentsFromCapture?.(context); + }, }; } diff --git a/gitnexus/src/core/ingestion/class-types.ts b/gitnexus/src/core/ingestion/class-types.ts index 858d4c2eb..9407d41fa 100644 --- a/gitnexus/src/core/ingestion/class-types.ts +++ b/gitnexus/src/core/ingestion/class-types.ts @@ -10,6 +10,13 @@ export interface ExtractedClassSymbol { name: string; type: ClassLikeNodeLabel; qualifiedName: string; + templateArguments?: string[]; +} + +export interface ClassCaptureContext { + captureMap: Record; + definitionNode: SyntaxNode | null; + nameNode: SyntaxNode | undefined; } /** @@ -30,6 +37,10 @@ export interface ClassExtractor { }, ): ExtractedClassSymbol | null; extractQualifiedName(node: SyntaxNode, simpleName: string): string | null; + shouldSkipClassCapture?( + context: ClassCaptureContext & { nodeLabel: ClassLikeNodeLabel }, + ): boolean; + extractTemplateArgumentsFromCapture?(context: ClassCaptureContext): string[] | undefined; } export interface ClassExtractionConfig { @@ -41,4 +52,9 @@ export interface ClassExtractionConfig { extractName?: (node: SyntaxNode) => string | undefined; extractType?: (node: SyntaxNode) => ClassLikeNodeLabel | undefined; extractScopeSegments?: (node: SyntaxNode) => string[] | null | undefined; + extractTemplateArguments?: (node: SyntaxNode) => string[] | undefined; + shouldSkipClassCapture?( + context: ClassCaptureContext & { nodeLabel: ClassLikeNodeLabel }, + ): boolean; + extractTemplateArgumentsFromCapture?(context: ClassCaptureContext): string[] | undefined; } diff --git a/gitnexus/src/core/ingestion/languages/cpp/interpret.ts b/gitnexus/src/core/ingestion/languages/cpp/interpret.ts index a5c1692a8..b330a3fc0 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/interpret.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/interpret.ts @@ -82,7 +82,12 @@ export function interpretCppTypeBinding(captures: CaptureMatch): ParsedTypeBindi /** * Normalize a C++ type name: strip pointer/array/reference syntax, - * qualifiers, and template parameters (V1: generic-ignored). + * qualifiers, while preserving template arguments for specialization-aware + * receiver binding (`List` vs `List`). + * + * Keeping template arguments here allows receiver-bound fallback to match + * specialization-specific class defs first; non-template behavior is preserved + * by base-name fallback in resolveClassBindingForName. */ export function normalizeCppTypeName(text: string): string { let t = text.trim(); @@ -90,13 +95,6 @@ export function normalizeCppTypeName(text: string): string { t = t .replace(/\b(const|volatile|restrict|static|extern|inline|mutable|constexpr|consteval)\b/g, '') .trim(); - // Strip template parameters (loop handles nested: Map> → Map) - while (t.includes('<')) { - const stripped = t.replace(/<[^<>]*>/g, ''); - if (stripped === t) break; // avoid infinite loop on malformed input - t = stripped; - } - t = t.trim(); // Strip pointer stars while (t.endsWith('*')) t = t.slice(0, -1).trim(); while (t.startsWith('*')) t = t.slice(1).trim(); diff --git a/gitnexus/src/core/ingestion/languages/cpp/query.ts b/gitnexus/src/core/ingestion/languages/cpp/query.ts index 0e6a0a7ae..70d544e3d 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/query.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/query.ts @@ -32,21 +32,47 @@ const CPP_SCOPE_QUERY = ` name: (type_identifier) @declaration.name body: (field_declaration_list)) @declaration.class +(class_specifier + name: (template_type + (type_identifier) @declaration.name + (template_argument_list) @declaration.template-arguments) + body: (field_declaration_list)) @declaration.class + (struct_specifier name: (type_identifier) @declaration.name body: (field_declaration_list)) @declaration.struct +(struct_specifier + name: (template_type + (type_identifier) @declaration.name + (template_argument_list) @declaration.template-arguments) + body: (field_declaration_list)) @declaration.struct + ;; ─── Declarations — class / struct inside template_declaration ─────── (template_declaration (class_specifier name: (type_identifier) @declaration.name body: (field_declaration_list)) @declaration.class) +(template_declaration + (class_specifier + name: (template_type + (type_identifier) @declaration.name + (template_argument_list) @declaration.template-arguments) + body: (field_declaration_list)) @declaration.class) + (template_declaration (struct_specifier name: (type_identifier) @declaration.name body: (field_declaration_list)) @declaration.struct) +(template_declaration + (struct_specifier + name: (template_type + (type_identifier) @declaration.name + (template_argument_list) @declaration.template-arguments) + body: (field_declaration_list)) @declaration.struct) + ;; ─── Declarations — enum ───────────────────────────────────────────── (enum_specifier name: (type_identifier) @declaration.name) @declaration.enum @@ -223,6 +249,11 @@ const CPP_SCOPE_QUERY = ` type: (type_identifier) @type-binding.type declarator: (identifier) @type-binding.name) @type-binding.annotation +;; Covers: List users; +(declaration + type: (template_type) @type-binding.type + declarator: (identifier) @type-binding.name) @type-binding.annotation + ;; ─── Type bindings — pointer variable declaration ─────────────────── ;; Covers: User* ptr = new User() (declaration diff --git a/gitnexus/src/core/ingestion/model/symbol-table.ts b/gitnexus/src/core/ingestion/model/symbol-table.ts index c22f63acb..a730c66eb 100644 --- a/gitnexus/src/core/ingestion/model/symbol-table.ts +++ b/gitnexus/src/core/ingestion/model/symbol-table.ts @@ -128,6 +128,7 @@ export interface AddMetadata { parameterTypes?: string[]; returnType?: string; declaredType?: string; + templateArguments?: string[]; ownerId?: string; qualifiedName?: string; } @@ -277,6 +278,9 @@ export const createSymbolTable = (): InternalSymbolTable => { : {}), ...(metadata?.returnType !== undefined ? { returnType: metadata.returnType } : {}), ...(metadata?.declaredType !== undefined ? { declaredType: metadata.declaredType } : {}), + ...(metadata?.templateArguments !== undefined + ? { templateArguments: metadata.templateArguments } + : {}), ...(metadata?.ownerId !== undefined ? { ownerId: metadata.ownerId } : {}), }; diff --git a/gitnexus/src/core/ingestion/parsing-processor.ts b/gitnexus/src/core/ingestion/parsing-processor.ts index 04a17db4f..f88e78ed9 100644 --- a/gitnexus/src/core/ingestion/parsing-processor.ts +++ b/gitnexus/src/core/ingestion/parsing-processor.ts @@ -30,6 +30,7 @@ import { constTagForId, buildCollisionGroups, } from './utils/method-props.js'; +import { extractTemplateArguments, templateArgumentsIdTag } from './utils/template-arguments.js'; import type { LanguageProvider } from './language-provider.js'; import type { ParsedFile } from 'gitnexus-shared'; import { WorkerPool } from './workers/worker-pool.js'; @@ -129,6 +130,7 @@ export const mergeChunkResults = ( parameterTypes: sym.parameterTypes, returnType: sym.returnType, declaredType: sym.declaredType, + templateArguments: sym.templateArguments, ownerId: sym.ownerId, qualifiedName: sym.qualifiedName, }); @@ -483,6 +485,23 @@ const processParsingSequential = async ( }) : null; const nodeLabel = extractedClassSymbol?.type ?? defaultNodeLabel; + const isClassLikeLabel = + nodeLabel === 'Class' || + nodeLabel === 'Struct' || + nodeLabel === 'Interface' || + nodeLabel === 'Enum' || + nodeLabel === 'Record'; + if ( + isClassLikeLabel && + provider.classExtractor?.shouldSkipClassCapture?.({ + captureMap, + definitionNode, + nameNode, + nodeLabel, + }) === true + ) { + return; + } // Synthesize name for constructors without explicit @name capture (e.g. Swift init) if (!nameNode && nodeLabel !== 'Constructor' && !extractedClassSymbol) return; const nodeName = extractedClassSymbol?.name ?? (nameNode ? nameNode.text : 'init'); @@ -610,7 +629,31 @@ const processParsingSequential = async ( cached.groups, ); } - const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${arityTag}`); + const classTemplateArguments = + extractedClassSymbol?.templateArguments ?? + provider.classExtractor?.extractTemplateArgumentsFromCapture?.({ + captureMap, + definitionNode, + nameNode, + }) ?? + (captureMap['template-arguments'] + ? extractTemplateArguments(captureMap['template-arguments'].text) + : undefined) ?? + (nameNode && nameNode.text ? extractTemplateArguments(nameNode.text) : undefined); + const classTemplateTag = + (nodeLabel === 'Class' || + nodeLabel === 'Struct' || + nodeLabel === 'Interface' || + nodeLabel === 'Enum' || + nodeLabel === 'Record') && + classTemplateArguments !== undefined && + classTemplateArguments.length > 0 + ? templateArgumentsIdTag(classTemplateArguments) + : ''; + const nodeId = generateId( + nodeLabel, + `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}`, + ); const classNodeForSymbol = definitionNodeForRange || definitionNode || nameNode; const qualifiedTypeName = extractedClassSymbol?.qualifiedName ?? @@ -643,6 +686,9 @@ const processParsingSequential = async ( nodeName, ), ...(qualifiedTypeName !== undefined ? { qualifiedName: qualifiedTypeName } : {}), + ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0 + ? { templateArguments: classTemplateArguments } + : {}), ...(frameworkHint ? { astFrameworkMultiplier: frameworkHint.entryPointMultiplier, @@ -700,6 +746,7 @@ const processParsingSequential = async ( parameterTypes: methodProps.parameterTypes as string[] | undefined, returnType: methodProps.returnType as string | undefined, declaredType, + templateArguments: classTemplateArguments, ownerId: enclosingClassId ?? undefined, qualifiedName: qualifiedTypeName, }); diff --git a/gitnexus/src/core/ingestion/scope-extractor.ts b/gitnexus/src/core/ingestion/scope-extractor.ts index f13cb2c73..44088b49f 100644 --- a/gitnexus/src/core/ingestion/scope-extractor.ts +++ b/gitnexus/src/core/ingestion/scope-extractor.ts @@ -76,6 +76,7 @@ import type { } from 'gitnexus-shared'; import { buildPositionIndex, buildScopeTree, canParentScope, makeScopeId } from 'gitnexus-shared'; import type { LanguageProvider } from './language-provider.js'; +import { extractTemplateArguments } from './utils/template-arguments.js'; // ─── Narrow hook surface the extractor actually uses ─────────────────────── @@ -533,6 +534,9 @@ function buildDefFromDeclarationMatch( const qualifiedCap = match['@declaration.qualified_name']; const qualifiedName = qualifiedCap?.text; + const templateArguments = + extractTemplateArguments(match['@declaration.template-arguments']?.text ?? '') ?? + extractTemplateArguments(qualifiedName ?? nameCap.text); // Optional arity metadata — producers (e.g. Python emit-captures) // synthesize these on function/method declarations. Their absence is @@ -554,6 +558,7 @@ function buildDefFromDeclarationMatch( ...(parameterTypes !== undefined ? { parameterTypes } : {}), ...(declaredType !== undefined ? { declaredType } : {}), ...(returnType !== undefined ? { returnType } : {}), + ...(templateArguments !== undefined ? { templateArguments } : {}), }; } diff --git a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/ids.ts b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/ids.ts index ad59f4f10..adc32bbd3 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/ids.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/ids.ts @@ -71,7 +71,12 @@ function isCallerAnchorLabel(label: NodeLabel): boolean { */ export function resolveDefGraphId( filePath: string, - def: { qualifiedName?: string; type?: NodeLabel; parameterTypes?: readonly string[] }, + def: { + qualifiedName?: string; + type?: NodeLabel; + parameterTypes?: readonly string[]; + templateArguments?: readonly string[]; + }, nodeLookup: GraphNodeLookup, ): string | undefined { const qn = def.qualifiedName; @@ -89,6 +94,19 @@ export function resolveDefGraphId( const pHit = nodeLookup.get(pKey); if (pHit !== undefined) return pHit; } + if ( + (def.type === 'Class' || + def.type === 'Struct' || + def.type === 'Interface' || + def.type === 'Enum' || + def.type === 'Record') && + def.templateArguments !== undefined && + def.templateArguments.length > 0 + ) { + const tKey = qualifiedKey(filePath, def.type, `${qn}~${def.templateArguments.join(',')}`); + const tHit = nodeLookup.get(tKey); + if (tHit !== undefined) return tHit; + } const qualifiedHit = nodeLookup.get(qualifiedKey(filePath, def.type, qn)); if (qualifiedHit !== undefined) return qualifiedHit; } diff --git a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts index c3b53c6f7..d712c29e3 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/graph-bridge/node-lookup.ts @@ -67,6 +67,7 @@ export function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup { filePath?: string; name?: string; qualifiedName?: string; + templateArguments?: readonly string[]; }; if (props.filePath === undefined || props.name === undefined) continue; if (!isLinkableLabel(node.label)) continue; @@ -96,6 +97,22 @@ export function buildGraphNodeLookup(graph: KnowledgeGraph): GraphNodeLookup { // Each overload is unique — set unconditionally. lookup.set(pKey, node.id); } + if ( + (node.label === 'Class' || + node.label === 'Struct' || + node.label === 'Interface' || + node.label === 'Enum' || + node.label === 'Record') && + props.templateArguments !== undefined && + props.templateArguments.length > 0 + ) { + const tKey = qualifiedKey( + props.filePath, + node.label, + `${qualified}~${props.templateArguments.join(',')}`, + ); + if (!lookup.has(tKey)) lookup.set(tKey, node.id); + } } // Fallback key: simple name. First-wins within a file — used when diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts index 9b57a7555..80ff3a200 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts @@ -55,6 +55,10 @@ import { narrowOverloadCandidates, isOverloadAmbiguousAfterNormalization, } from './overload-narrowing.js'; +import { + extractTemplateArguments, + stripTemplateArguments, +} from '../../utils/template-arguments.js'; /** Subset of `ScopeResolver` consumed by this pass. Accepting the * subset rather than the full provider keeps tests and partial @@ -70,6 +74,53 @@ type ReceiverBoundProviderSubset = Pick< | 'resolveQualifiedReceiverMember' >; +function normalizeTemplateArgToken(value: string): string { + return value.replace(/\s+/g, ''); +} + +function resolveClassBindingForName( + scopeId: string, + rawClassName: string, + scopes: ScopeResolutionIndexes, +): SymbolDefinition | undefined { + const direct = findClassBindingInScope(scopeId, rawClassName, scopes); + if (direct !== undefined) return direct; + + if (!rawClassName.includes('<')) return undefined; + const baseName = stripTemplateArguments(rawClassName).replace(/\s+/g, ''); + if (baseName.length === 0) return undefined; + + const wantedArgs = extractTemplateArguments(rawClassName)?.map(normalizeTemplateArgToken); + if (wantedArgs !== undefined && wantedArgs.length > 0) { + // qualifiedNames is a Map and may not contain the stripped base name at all + // (e.g., unresolved type binding or only template-qualified entries), so + // default to [] before checking `.length`. + const qnameIds = scopes.qualifiedNames.get(baseName) ?? []; + if (qnameIds.length === 0) { + return findClassBindingInScope(scopeId, baseName, scopes); + } + const matches: SymbolDefinition[] = []; + for (const id of qnameIds) { + const def = scopes.defs.get(id); + if (def === undefined || !isClassLike(def.type)) continue; + const defArgs = def.templateArguments?.map(normalizeTemplateArgToken); + if ( + defArgs !== undefined && + defArgs.length === wantedArgs.length && + defArgs.every((value, i) => value === wantedArgs[i]) + ) { + matches.push(def); + } + } + if (matches.length === 1) return matches[0]; + // Scope extractor only records class definitions with bodies in C++, so + // forward declarations are not expected here. Keep fallback behavior for + // safety in non-ODR or mixed-language edge cases. + } + + return findClassBindingInScope(scopeId, baseName, scopes); +} + export function emitReceiverBoundCalls( graph: KnowledgeGraph, scopes: ScopeResolutionIndexes, @@ -470,7 +521,7 @@ export function emitReceiverBoundCalls( // ── Case 4: simple typeBinding (`u: U`) ────────────────────── if (typeRef !== undefined && !typeRef.rawName.includes('.')) { - let ownerDef = findClassBindingInScope(site.inScope, typeRef.rawName, scopes); + let ownerDef = resolveClassBindingForName(site.inScope, typeRef.rawName, scopes); // `findClassBindingInScope(..., typeRef.rawName)` only works when // rawName is itself a class symbol reachable through scope bindings. // For languages with namespace-style imports (Go), imported types diff --git a/gitnexus/src/core/ingestion/tree-sitter-queries.ts b/gitnexus/src/core/ingestion/tree-sitter-queries.ts index d65229808..f02ae2cb2 100644 --- a/gitnexus/src/core/ingestion/tree-sitter-queries.ts +++ b/gitnexus/src/core/ingestion/tree-sitter-queries.ts @@ -680,7 +680,15 @@ export const GO_QUERIES = ` export const CPP_QUERIES = ` ; Classes, Structs, Namespaces (class_specifier name: (type_identifier) @name) @definition.class +(class_specifier + name: (template_type + (type_identifier) @name + (template_argument_list) @template-arguments)) @definition.class (struct_specifier name: (type_identifier) @name) @definition.struct +(struct_specifier + name: (template_type + (type_identifier) @name + (template_argument_list) @template-arguments)) @definition.struct (namespace_definition name: (namespace_identifier) @name) @definition.namespace (enum_specifier name: (type_identifier) @name) @definition.enum @@ -762,6 +770,11 @@ export const CPP_QUERIES = ` ; Templates (template_declaration (class_specifier name: (type_identifier) @name)) @definition.template +(template_declaration + (class_specifier + name: (template_type + (type_identifier) @name + (template_argument_list) @template-arguments))) @definition.template (template_declaration (function_definition declarator: (function_declarator declarator: (identifier) @name))) @definition.template ; Includes diff --git a/gitnexus/src/core/ingestion/utils/ast-helpers.ts b/gitnexus/src/core/ingestion/utils/ast-helpers.ts index ec76cd1db..351cfdedb 100644 --- a/gitnexus/src/core/ingestion/utils/ast-helpers.ts +++ b/gitnexus/src/core/ingestion/utils/ast-helpers.ts @@ -2,6 +2,11 @@ import type Parser from 'tree-sitter'; import type { Capture, NodeLabel, Range } from 'gitnexus-shared'; import type { LanguageProvider } from '../language-provider.js'; import { generateId } from '../../../lib/utils.js'; +import { + extractTemplateArguments, + stripTemplateArguments, + templateArgumentsIdTag, +} from './template-arguments.js'; /** Tree-sitter AST node. Re-exported for use across ingestion modules. */ export type SyntaxNode = Parser.SyntaxNode; @@ -390,8 +395,13 @@ export const findEnclosingClassInfo = ( ) { label = 'Interface'; } + const templateArguments = extractTemplateArguments(nameNode.text); + const classIdName = + templateArguments !== undefined + ? `${stripTemplateArguments(nameNode.text)}${templateArgumentsIdTag(templateArguments)}` + : nameNode.text; return { - classId: generateId(label, `${filePath}:${nameNode.text}`), + classId: generateId(label, `${filePath}:${classIdName}`), className: nameNode.text, }; } diff --git a/gitnexus/src/core/ingestion/utils/template-arguments.ts b/gitnexus/src/core/ingestion/utils/template-arguments.ts new file mode 100644 index 000000000..e1c6e3463 --- /dev/null +++ b/gitnexus/src/core/ingestion/utils/template-arguments.ts @@ -0,0 +1,57 @@ +/** + * Parse top-level generic/template arguments from a type-like string. + * + * Examples: + * - `List` -> ['int'] + * - `Map>` -> ['string', 'vector'] + * - `List` -> ['T*'] + */ +export function extractTemplateArguments(text: string): string[] | undefined { + const start = text.indexOf('<'); + if (start === -1) return undefined; + let depth = 0; + let end = -1; + for (let i = start; i < text.length; i += 1) { + const ch = text[i]; + if (ch === '<') depth += 1; + else if (ch === '>') { + depth -= 1; + if (depth === 0) { + end = i; + break; + } + if (depth < 0) return undefined; + } + } + if (end === -1) return undefined; + const inner = text.slice(start + 1, end); + if (inner.trim().length === 0) return undefined; + + const args: string[] = []; + let tokenStart = 0; + let nested = 0; + for (let i = 0; i < inner.length; i += 1) { + const ch = inner[i]; + if (ch === '<') nested += 1; + else if (ch === '>') nested -= 1; + else if (ch === ',' && nested === 0) { + const token = inner.slice(tokenStart, i).replace(/\s+/g, ''); + if (token.length > 0) args.push(token); + tokenStart = i + 1; + } + } + const last = inner.slice(tokenStart).replace(/\s+/g, ''); + if (last.length > 0) args.push(last); + return args.length > 0 ? args : undefined; +} + +export function stripTemplateArguments(text: string): string { + const start = text.indexOf('<'); + if (start === -1) return text; + return text.slice(0, start); +} + +export function templateArgumentsIdTag(templateArguments?: readonly string[]): string { + if (templateArguments === undefined || templateArguments.length === 0) return ''; + return `~${templateArguments.join(',')}`; +} diff --git a/gitnexus/src/core/ingestion/workers/parse-worker.ts b/gitnexus/src/core/ingestion/workers/parse-worker.ts index 9a71fc16c..e22b927ed 100644 --- a/gitnexus/src/core/ingestion/workers/parse-worker.ts +++ b/gitnexus/src/core/ingestion/workers/parse-worker.ts @@ -82,6 +82,7 @@ import { constTagForId, buildCollisionGroups, } from '../utils/method-props.js'; +import { extractTemplateArguments, templateArgumentsIdTag } from '../utils/template-arguments.js'; import type { LanguageProvider } from '../language-provider.js'; import type { ParsedFile } from 'gitnexus-shared'; import { extractParsedFile } from '../scope-extractor-bridge.js'; @@ -129,6 +130,7 @@ interface ParsedSymbol { parameterTypes?: string[]; returnType?: string; declaredType?: string; + templateArguments?: string[]; ownerId?: string; visibility?: string; isStatic?: boolean; @@ -2001,6 +2003,23 @@ const processFileGroup = ( }) : null; const nodeLabel = extractedClassSymbol?.type ?? defaultNodeLabel; + const isClassLikeLabel = + nodeLabel === 'Class' || + nodeLabel === 'Struct' || + nodeLabel === 'Interface' || + nodeLabel === 'Enum' || + nodeLabel === 'Record'; + if ( + isClassLikeLabel && + provider.classExtractor?.shouldSkipClassCapture?.({ + captureMap, + definitionNode, + nameNode, + nodeLabel, + }) === true + ) { + continue; + } // Dedup: variable captures (Const/Static/Variable) may overlap with higher-priority // captures (e.g. `const fn = () => {}` matches both @definition.function and @definition.const). @@ -2114,7 +2133,31 @@ const processFileGroup = ( ); arityTag += constTagForId(defMethodMap, nodeName, arityForId, defMethodInfo, groups); } - const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${arityTag}`); + const classTemplateArguments = + extractedClassSymbol?.templateArguments ?? + provider.classExtractor?.extractTemplateArgumentsFromCapture?.({ + captureMap, + definitionNode, + nameNode, + }) ?? + (captureMap['template-arguments'] + ? extractTemplateArguments(captureMap['template-arguments'].text) + : undefined) ?? + (nameNode && nameNode.text ? extractTemplateArguments(nameNode.text) : undefined); + const classTemplateTag = + (nodeLabel === 'Class' || + nodeLabel === 'Struct' || + nodeLabel === 'Interface' || + nodeLabel === 'Enum' || + nodeLabel === 'Record') && + classTemplateArguments !== undefined && + classTemplateArguments.length > 0 + ? templateArgumentsIdTag(classTemplateArguments) + : ''; + const nodeId = generateId( + nodeLabel, + `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}`, + ); const classNodeForSymbol = definitionNode || nameNode; const qualifiedTypeName = extractedClassSymbol?.qualifiedName ?? @@ -2237,6 +2280,9 @@ const processFileGroup = ( ? isVueSetupTopLevel(nameNode || definitionNode) : cachedExportCheck(provider.exportChecker, nameNode || definitionNode, nodeName), ...(qualifiedTypeName !== undefined ? { qualifiedName: qualifiedTypeName } : {}), + ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0 + ? { templateArguments: classTemplateArguments } + : {}), ...(frameworkHint ? { astFrameworkMultiplier: frameworkHint.entryPointMultiplier, @@ -2262,6 +2308,9 @@ const processFileGroup = ( parameterTypes: methodProps.parameterTypes as string[] | undefined, returnType: methodProps.returnType as string | undefined, ...(declaredType !== undefined ? { declaredType } : {}), + ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0 + ? { templateArguments: classTemplateArguments } + : {}), ...(enclosingClassId ? { ownerId: enclosingClassId } : {}), visibility: methodProps.visibility as string | undefined, isStatic: methodProps.isStatic as boolean | undefined, diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp new file mode 100644 index 000000000..237ce1cae --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/app.cpp @@ -0,0 +1,7 @@ +#include "list_user.h" +#include "list_order.h" + +void callUserSave() { + List list; + list.save(); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_order.h b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_order.h new file mode 100644 index 000000000..015a16b5b --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_order.h @@ -0,0 +1,14 @@ +#pragma once + +struct Order {}; + +template +class List; + +template <> +class List { +public: + void callSave() { save(); } + void save() { persistOrder(); } + void persistOrder() {} +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_user.h b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_user.h new file mode 100644 index 000000000..d9ba7fb24 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-template-specialization-disambiguation/list_user.h @@ -0,0 +1,14 @@ +#pragma once + +struct User {}; + +template +class List; + +template <> +class List { +public: + void callSave() { save(); } + void save() { persistUser(); } + void persistUser() {} +}; diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index 26fb02d36..25a7f9de7 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -1464,6 +1464,84 @@ describe('C++ template overload cross-file and chain resolution', () => { }); }); +describe('C++ template specialization disambiguation across files', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-template-specialization-disambiguation'), + () => {}, + ); + }, 60000); + + it('emits distinct Class nodes for List and List', () => { + const classes = getNodesByLabelFull(result, 'Class').filter( + (c) => c.name === 'List' && Array.isArray(c.properties.templateArguments), + ); + expect(classes.length).toBe(2); + const fingerprints = new Set(classes.map((c) => c.properties.templateArguments.join(','))); + expect(fingerprints).toEqual(new Set(['User', 'Order'])); + }); + + it('callSave() in each specialization resolves to its own save()', () => { + const calls = getRelationships(result, 'CALLS'); + const saveEdges = calls.filter((c) => c.source === 'callSave' && c.target === 'save'); + expect(saveEdges.length).toBe(2); + + const hasMethod = getRelationships(result, 'HAS_METHOD'); + const ownerFingerprints = new Set(); + for (const edge of saveEdges) { + const sourceOwnerEdge = hasMethod.find((e) => e.rel.targetId === edge.rel.sourceId); + const targetOwnerEdge = hasMethod.find((e) => e.rel.targetId === edge.rel.targetId); + expect(sourceOwnerEdge).toBeDefined(); + expect(targetOwnerEdge).toBeDefined(); + expect(sourceOwnerEdge!.rel.sourceId).toBe(targetOwnerEdge!.rel.sourceId); + const ownerNode = result.graph.getNode(sourceOwnerEdge!.rel.sourceId); + const fp = ownerNode?.properties.templateArguments?.join(','); + if (fp) ownerFingerprints.add(fp); + } + expect(ownerFingerprints).toEqual(new Set(['User', 'Order'])); + }); + + it('save specialization bodies route to their own sibling method', () => { + const calls = getRelationships(result, 'CALLS'); + + const persistUserCalls = calls.filter((c) => c.target === 'persistUser'); + expect(persistUserCalls.length).toBe(1); + const userSaveOwner = getRelationships(result, 'HAS_METHOD').find( + (e) => e.rel.targetId === persistUserCalls[0].rel.sourceId, + ); + expect(userSaveOwner).toBeDefined(); + const userOwnerNode = result.graph.getNode(userSaveOwner!.rel.sourceId); + expect(userOwnerNode?.properties.templateArguments).toEqual(['User']); + + const persistOrderCalls = calls.filter((c) => c.target === 'persistOrder'); + expect(persistOrderCalls.length).toBe(1); + const orderSaveOwner = getRelationships(result, 'HAS_METHOD').find( + (e) => e.rel.targetId === persistOrderCalls[0].rel.sourceId, + ); + expect(orderSaveOwner).toBeDefined(); + const orderOwnerNode = result.graph.getNode(orderSaveOwner!.rel.sourceId); + expect(orderOwnerNode?.properties.templateArguments).toEqual(['Order']); + }); + + it('resolves external List receiver call to List::save', () => { + const calls = getRelationships(result, 'CALLS'); + const edge = calls.find( + (c) => + c.source === 'callUserSave' && c.target === 'save' && c.targetFilePath === 'list_user.h', + ); + expect(edge).toBeDefined(); + + const ownerEdge = getRelationships(result, 'HAS_METHOD').find( + (e) => e.rel.targetId === edge!.rel.targetId, + ); + expect(ownerEdge).toBeDefined(); + const ownerNode = result.graph.getNode(ownerEdge!.rel.sourceId); + expect(ownerNode?.properties.templateArguments).toEqual(['User']); + }); +}); + // ── Phase P: C++ out-of-class method definition + overload disambiguation ─ describe('C++ out-of-class method definition with overloaded declarations', () => { diff --git a/gitnexus/test/integration/resolvers/helpers.ts b/gitnexus/test/integration/resolvers/helpers.ts index 418bbc0fb..5149e3e69 100644 --- a/gitnexus/test/integration/resolvers/helpers.ts +++ b/gitnexus/test/integration/resolvers/helpers.ts @@ -162,6 +162,12 @@ const LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES: Readonly', 'outer::v1::Base::f() resolves to Base::f inside template body', 'outer::v1::free_fn() resolves as a namespace free function, not a super-receiver method', + // Template specialization owner identity currently relies on + // class-template fingerprints in the registry-primary graph bridge. + // Legacy DAG collapses specializations to the simple class name. + 'emits distinct Class nodes for List and List', + 'callSave() in each specialization resolves to its own save()', + 'save specialization bodies route to their own sibling method', ]), }; From 911a2ee1e6e4662d9b732e707e65ae45901c60b6 Mon Sep 17 00:00:00 2001 From: Harlan Zhou Date: Thu, 14 May 2026 23:15:17 +0800 Subject: [PATCH 28/33] fix: apply ESM .js extension fallback to tsconfig path alias resolution (#1530) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix: apply ESM .js extension fallback to tsconfig path alias resolution Path alias imports (e.g. `@/utils.js` via tsconfig paths) now correctly strip JS-family extensions and retry with TS equivalents when the literal .js file does not exist. This applies the same stripJsExtension fallback already used for relative imports to the alias resolution branch. Fixes #1528 * chore(autofix): apply prettier + eslint fixes via /autofix command * test(esm): cover .mjs/.cjs path-alias extension resolution Co-authored-by: Cursor * test(esm): use Map for path aliases in resolveWithAlias helper Matches TsconfigPaths.aliases from language-config. CI cannot run tsc -p tsconfig.test.json yet: the project has hundreds of pre-existing errors under test/ (fixtures + unit/integration); enable that step after backlog cleanup. Co-authored-by: Cursor --------- Co-authored-by: Gergő Magyar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Cursor --- .../ingestion/import-resolvers/standard.ts | 10 ++- .../unit/esm-extension-resolution.test.ts | 73 +++++++++++++++++++ 2 files changed, 80 insertions(+), 3 deletions(-) diff --git a/gitnexus/src/core/ingestion/import-resolvers/standard.ts b/gitnexus/src/core/ingestion/import-resolvers/standard.ts index 47e2dabb2..4ee6e1440 100644 --- a/gitnexus/src/core/ingestion/import-resolvers/standard.ts +++ b/gitnexus/src/core/ingestion/import-resolvers/standard.ts @@ -72,6 +72,13 @@ export const resolveImportPath = ( const resolved = tryResolveWithExtensions(rewritten, allFiles); if (resolved) return cache(resolved); + // ESM fallback: strip .js/.jsx/.mjs/.cjs and retry with TS equivalents + const strippedAlias = stripJsExtension(rewritten); + if (strippedAlias !== null) { + const esmResolved = tryResolveWithExtensions(strippedAlias, allFiles); + if (esmResolved) return cache(esmResolved); + } + // Try suffix matching as fallback const parts = rewritten.split('/').filter(Boolean); const suffixResult = suffixResolve(parts, normalizedFileList, allFileList, index); @@ -132,9 +139,6 @@ export const resolveImportPath = ( // TypeScript ESM: imports use .js/.jsx/.mjs/.cjs but source files are // .ts/.tsx/.mts/.cts. Strip the JS-family extension and re-resolve. - // NOTE: This fallback only applies to relative imports. Path alias imports - // (e.g. @/utils.js via tsconfig paths) do not yet strip .js extensions — - // that is a known limitation tracked for follow-up. if (language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) { const stripped = stripJsExtension(basePath); if (stripped !== null) { diff --git a/gitnexus/test/unit/esm-extension-resolution.test.ts b/gitnexus/test/unit/esm-extension-resolution.test.ts index 69dc652cf..794888049 100644 --- a/gitnexus/test/unit/esm-extension-resolution.test.ts +++ b/gitnexus/test/unit/esm-extension-resolution.test.ts @@ -151,3 +151,76 @@ describe('stripJsExtension', () => { it('returns null for .ts', () => expect(stripJsExtension('foo/bar.ts')).toBeNull()); it('returns null for no extension', () => expect(stripJsExtension('foo/bar')).toBeNull()); }); + +describe('ESM extension resolution — path aliases with .js extensions', () => { + const aliasAtToSrc = new Map([['@/', 'src/']]); + const aliasTildeToSrc = new Map([['~/', 'src/']]); + + function resolveWithAlias( + currentFile: string, + importPath: string, + ctx: ReturnType, + aliases: Map, + baseUrl = '.', + ): string | null { + return resolveImportPath( + currentFile, + importPath, + ctx.allFilesSet, + ctx.files, + ctx.normalized, + ctx.cache, + SupportedLanguages.TypeScript, + { aliases, baseUrl }, + ctx.index, + ); + } + + it('resolves @/utils.js to src/utils.ts via alias', () => { + const ctx = makeCtx(['src/index.ts', 'src/utils.ts']); + const result = resolveWithAlias('src/index.ts', '@/utils.js', ctx, aliasAtToSrc, '.'); + expect(result).toBe('src/utils.ts'); + }); + + it('resolves @/component.jsx to src/component.tsx via alias', () => { + const ctx = makeCtx(['src/index.ts', 'src/component.tsx']); + const result = resolveWithAlias('src/index.ts', '@/component.jsx', ctx, aliasAtToSrc, '.'); + expect(result).toBe('src/component.tsx'); + }); + + it('resolves @/config.mjs to src/config.mts via alias', () => { + const ctx = makeCtx(['src/index.ts', 'src/config.mts']); + const result = resolveWithAlias('src/index.ts', '@/config.mjs', ctx, aliasAtToSrc, '.'); + expect(result).toBe('src/config.mts'); + }); + + it('resolves @/legacy.cjs to src/legacy.cts via alias', () => { + const ctx = makeCtx(['src/index.ts', 'src/legacy.cts']); + const result = resolveWithAlias('src/index.ts', '@/legacy.cjs', ctx, aliasAtToSrc, '.'); + expect(result).toBe('src/legacy.cts'); + }); + + it('prefers actual .js file over TS fallback in alias resolution', () => { + const ctx = makeCtx(['src/index.ts', 'src/utils.js', 'src/utils.ts']); + const result = resolveWithAlias('src/index.ts', '@/utils.js', ctx, aliasAtToSrc, '.'); + expect(result).toBe('src/utils.js'); + }); + + it('resolves alias with baseUrl prefix', () => { + const ctx = makeCtx(['app/src/index.ts', 'app/src/helpers/token.ts']); + const result = resolveWithAlias( + 'app/src/index.ts', + '~/helpers/token.js', + ctx, + aliasTildeToSrc, + 'app', + ); + expect(result).toBe('app/src/helpers/token.ts'); + }); + + it('returns null when alias .js import has no matching source', () => { + const ctx = makeCtx(['src/index.ts']); + const result = resolveWithAlias('src/index.ts', '@/missing.js', ctx, aliasAtToSrc, '.'); + expect(result).toBeNull(); + }); +}); From 89c03b2ebb8a21b09ae927ce4358141888976b8c Mon Sep 17 00:00:00 2001 From: Derek Pearson <32114370+dpearson2699@users.noreply.github.com> Date: Thu, 14 May 2026 11:39:30 -0400 Subject: [PATCH 29/33] fix: skip Claude augment hook when GitNexus server owns DB (#1493) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(claude): skip augment hook when server owns db * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(hooks): cross-platform DB lock probe for MCP owner guard Extract hook-db-lock-probe.cjs with a single hasGitNexusDbLockedByGitNexusServer entry point used by both Claude hooks: - Linux: scan /proc//fd via dev+inode (no lsof required), optional lsof fallback; GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS caps scan time - macOS and other Unix: trusted lsof + ps (absolute paths / env overrides) - Windows: Restart Manager + Win32_Process via win-rm-list-json.ps1 and GITNEXUS_HOOK_POWERSHELL_PATH Update hooks.test.ts source coverage for the probe module. Co-authored-by: Cursor * Update gitnexus/hooks/claude/win-rm-list-json.ps1 Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * Apply suggestion from @github-actions[bot] Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> * fix(gitnexus): repair package.json JSON after malformed engines edit Co-authored-by: Cursor * Update Node.js engine version requirement to 22.0.0 * Update Node.js engine version to >=22.0.0 * fix(hooks): address ce-code-review findings on PR #1493 P0: - Replace malformed `RM_UNIQUE_PROCESS` block in `gitnexus/hooks/claude/win-rm-list-json.ps1` (duplicate struct decl + duplicate `ProcessStartTime` + unbalanced braces) with a single well-formed `[StructLayout(LayoutKind.Sequential, Pack = 4)]` struct, so PowerShell `Add-Type` actually compiles and the Windows DB-lock probe stops fail-open on every machine. - `gitnexus/src/cli/setup.ts` now copies `hook-db-lock-probe.cjs` and `win-rm-list-json.ps1` into the user's `~/.claude/hooks/gitnexus/` alongside `hook-lock.cjs`, preventing the `MODULE_NOT_FOUND` thrown by `gitnexus-hook.cjs:18`'s top-level require on every fresh install. `gitnexus/test/unit/setup.test.ts` extended to assert both new copy destinations. - Four fail-open hook tests (`ENOENT lsof`, `npx parent line`, `non-GitNexus ps line`, `ps ENOENT`) now seed `createHookToolDir` with a valid `[GitNexus]` stderr line so `expect(parseHookOutput).not.toBeNull()` actually holds on CI. P1: - Plugin copy of `win-rm-list-json.ps1` gains `Pack = 4` so its CLR struct matches the 12-byte native `RM_UNIQUE_PROCESS` layout (multi-blocker `RmGetList` no longer reads mangled `dwProcessId`). - `GITNEXUS_HOOK_CLI_PATH = ''` now falls through to the resolution chain in `gitnexus-hook.cjs`, matching the plugin copy and removing the twin-file divergence on empty-string envs. - Lock-warning suppression test seeds `gitnexusMarkerPath` and asserts the augment subprocess actually ran, plus `GITNEXUS_DEBUG=1` preserves the full discarded prefix. - MCP-owner skip branch in both hook copies now emits `[GitNexus] augment skipped: MCP server owns DB` on stderr, so agents can distinguish intentional skip from silent failure. P2: - `ps` loop in `hook-db-lock-probe.cjs` fails-closed on `ETIMEDOUT` to mirror the `lsof` handling (symmetric subprocess-probe contract). - `RmStartSession` return value captured in both `.ps1` copies; exits early with `[]` on non-zero so subsequent RM API calls don't operate on an invalid handle. - Windows RM-list `.ps1` encoded cache distinguishes uninitialized (`undefined`) from load-failed (`null`) with a one-shot `GITNEXUS_DEBUG` warning instead of silently caching empty string. - `createHookToolDir` helper accepts `lsofOutputLines` and `psOutputByPid`; the multi-PID test uses them instead of duplicating the fake-binary construction inline. - All five skip-path tests now assert `result.status === 0` and the new skip-signal stderr line. - `AGENTS.md` documents the seven hook configuration env vars (`GITNEXUS_HOOK_CLI_PATH`, `_LSOF_PATH`, `_PS_PATH`, `_POWERSHELL_PATH`, `_LINUX_PROC_BUDGET_MS`, `_RM_TARGET`, `GITNEXUS_DEBUG`). - `GITNEXUS_DEBUG` path in `gitnexus-hook.cjs`/`.js` writes the full discarded stderr prefix instead of a 180-char preview. - Inline comment in `hook-db-lock-probe.cjs` explains the intentional Windows ETIMEDOUT fail-closed semantics. - Removed the unnecessary `as WriteFileOptions` cast and orphaned `import type { WriteFileOptions }` in `hooks.test.ts`. P3: - `isGitNexusServerCommand` unexported from `hook-db-lock-probe.cjs` (kept as private helper). - Env-path overrides (`GITNEXUS_HOOK_CLI_PATH`, `_POWERSHELL_PATH`, `_LSOF_PATH`, `_PS_PATH`) require `fs.existsSync` before being returned, so typos / stale config fall through to the standard resolution chain. Misc: - `gitnexus/package.json` engines.node back to `>=22.0.0` (matches origin/main and the original PR reviewer's earlier request). Twin-tree parity / CI sync mechanism tracked separately at abhigyanpatwari/GitNexus#1591. Test plan: vitest run test/unit/hooks.test.ts → 113 passed, 18 Unix-only skipped; setup.test.ts → 14 passed. * chore(autofix): apply prettier + eslint fixes via /autofix command * trigger --------- Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> Co-authored-by: Gergő Magyar Co-authored-by: Cursor --- AGENTS.md | 14 + gitnexus-claude-plugin/hooks/gitnexus-hook.js | 42 +- .../hooks/hook-db-lock-probe.cjs | 238 +++++++++ .../hooks/win-rm-list-json.ps1 | 76 +++ gitnexus/hooks/claude/gitnexus-hook.cjs | 37 +- gitnexus/hooks/claude/hook-db-lock-probe.cjs | 238 +++++++++ gitnexus/hooks/claude/win-rm-list-json.ps1 | 76 +++ gitnexus/src/cli/setup.ts | 18 + gitnexus/test/unit/hooks.test.ts | 498 ++++++++++++++++++ gitnexus/test/unit/setup.test.ts | 15 + gitnexus/test/utils/hook-test-helpers.ts | 2 + 11 files changed, 1248 insertions(+), 6 deletions(-) create mode 100644 gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs create mode 100644 gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 create mode 100644 gitnexus/hooks/claude/hook-db-lock-probe.cjs create mode 100644 gitnexus/hooks/claude/win-rm-list-json.ps1 diff --git a/AGENTS.md b/AGENTS.md index 1346facc9..b9b9138b1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -174,6 +174,20 @@ Check `.gitnexus/meta.json` `stats.embeddings` (0 = none). A plain `analyze` no | Tools/resources/schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` | | CLI commands (index, status, clean, wiki) | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` | +## Hook env knobs + +The Claude Code hook (`gitnexus/hooks/claude/gitnexus-hook.cjs` and the mirrored plugin copy under `gitnexus-claude-plugin/hooks/`) honours these env vars. Defaults work for normal installations; set them only to override resolution. All path overrides ignore values that do not exist on disk and fall through to the standard resolution chain. + +| Env var | Type | Default | Purpose | +|---------|------|---------|---------| +| `GITNEXUS_HOOK_CLI_PATH` | path | resolved via package layout / `require.resolve` | Override path to the `gitnexus` CLI entry the hook spawns for `augment`. | +| `GITNEXUS_HOOK_LSOF_PATH` | path | `lsof` on `PATH` (with `/usr/bin/lsof`, `/usr/sbin/lsof`, `/sbin/lsof` fallbacks) | Override POSIX `lsof` location for the DB-lock probe. | +| `GITNEXUS_HOOK_PS_PATH` | path | `ps` on `PATH` (with `/bin/ps`, `/usr/bin/ps` fallbacks) | Override POSIX `ps` location. | +| `GITNEXUS_HOOK_POWERSHELL_PATH` | path | `%SystemRoot%\System32\WindowsPowerShell\v1.0\powershell.exe` (then `SysWOW64`, then `powershell.exe` on `PATH`) | Override Windows PowerShell location used by the Restart-Manager probe. | +| `GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS` | integer ms | `1200` | Max wall-clock for the Linux `/proc` fd scan before bailing out to the `lsof` fallback. | +| `GITNEXUS_HOOK_RM_TARGET` | path | derived | Restart-Manager target file (the LadybugDB path under `.gitnexus/`). Set internally by the hook; rarely overridden manually. | +| `GITNEXUS_DEBUG` | boolean (`1`/`true`) | unset | Verbose stderr from the hook: prints discarded augment-stderr prefixes and one-shot `.ps1` load-failure warnings. | + ## Repo reference diff --git a/gitnexus-claude-plugin/hooks/gitnexus-hook.js b/gitnexus-claude-plugin/hooks/gitnexus-hook.js index 245d34043..7ff03e430 100644 --- a/gitnexus-claude-plugin/hooks/gitnexus-hook.js +++ b/gitnexus-claude-plugin/hooks/gitnexus-hook.js @@ -15,6 +15,7 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); const { acquireHookSlot } = require('./hook-lock.js'); +const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs'); /** * Read JSON input from stdin synchronously. @@ -103,6 +104,28 @@ function findGitNexusDir(startDir) { return null; } +function hasGitNexusServerOwner(gitNexusDir) { + return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid); +} + +function extractAugmentContext(stderr) { + const output = (stderr || '').trim(); + const marker = output.indexOf('[GitNexus]'); + const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true'; + if (debug && output.length > 0) { + // Emit the FULL discarded prefix (everything before the marker, or all of + // it when no marker is present) so suppressed diagnostics — LadybugDB lock + // warnings, parser errors, etc. — remain recoverable on the hook's own + // stderr. The untruncated payload lets operators see exactly what was + // filtered out instead of a 180-char JSON-quoted preview. + const discarded = marker === -1 ? output : output.slice(0, marker).trim(); + if (discarded.length > 0) { + process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`); + } + } + return marker === -1 ? '' : output.slice(marker).trim(); +} + /** * Extract search pattern from tool input. */ @@ -170,6 +193,15 @@ function extractPattern(toolName, toolInput) { */ function runGitNexusCli(args, cwd, timeout) { const isWin = process.platform === 'win32'; + const hookCli = process.env.GITNEXUS_HOOK_CLI_PATH; + if (hookCli !== undefined && String(hookCli).trim() && fs.existsSync(String(hookCli))) { + return spawnSync(process.execPath, [String(hookCli), ...args], { + encoding: 'utf-8', + timeout, + cwd, + stdio: ['pipe', 'pipe', 'pipe'], + }); + } // Detect whether 'gitnexus' is on PATH (cheap check, no execution) let useDirectBinary = false; @@ -228,6 +260,10 @@ function handlePreToolUse(input) { const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; + if (hasGitNexusServerOwner(gitNexusDir)) { + process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n'); + return; + } const release = acquireHookSlot(gitNexusDir); if (!release) return; @@ -236,7 +272,7 @@ function handlePreToolUse(input) { try { const child = runGitNexusCli(['augment', '--', pattern], cwd, 7000); if (!child.error && child.status === 0) { - result = child.stderr || ''; + result = extractAugmentContext(child.stderr || ''); } } catch { /* graceful failure */ @@ -244,8 +280,8 @@ function handlePreToolUse(input) { release(); } - if (result && result.trim()) { - sendHookResponse('PreToolUse', result.trim()); + if (result) { + sendHookResponse('PreToolUse', result); } } diff --git a/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs new file mode 100644 index 000000000..783cd0804 --- /dev/null +++ b/gitnexus-claude-plugin/hooks/hook-db-lock-probe.cjs @@ -0,0 +1,238 @@ +/** + * Cross-platform best-effort probe: does another process hold dbPath open + * with a command line that looks like a GitNexus MCP/serve server? + * + * Backends (no user-installed Sysinternals): + * - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof; + * optional lsof fallback when proc scan finds nothing. + * - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first). + * - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script + + * Win32_Process for command lines; trusted powershell.exe under %SystemRoot%. + * + * Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or + * PowerShell ETIMEDOUT (Windows), matching the hook contract. + */ + +const fs = require('fs'); +const path = require('path'); +const { spawnSync } = require('child_process'); + +function isGitNexusServerCommand(command) { + const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command); + const hasGitNexus = + /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) || + /node_modules[/\\]gitnexus[/\\]/.test(command); + return hasServerMode && hasGitNexus; +} + +function resolveHookBinary(tool) { + const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH'; + const fromEnv = process.env[envKey]; + if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) { + return String(fromEnv); + } + const candidates = + tool === 'lsof' + ? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool] + : ['/bin/ps', '/usr/bin/ps', tool]; + for (const candidate of candidates) { + if (candidate === tool) return tool; + try { + if (fs.existsSync(candidate)) return candidate; + } catch { + /* ignore */ + } + } + return tool; +} + +function resolveWindowsPowerShellPath() { + const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH; + if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) { + return String(fromEnv).trim(); + } + const root = process.env.SystemRoot || 'C:\\Windows'; + const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'); + if (fs.existsSync(ps)) return ps; + const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe'); + if (fs.existsSync(psWow)) return psWow; + return 'powershell.exe'; +} + +// Sentinel: +// undefined = not loaded yet (try the read) +// string = encoded PowerShell command (successful load) +// null = load attempted and failed (do not retry; warning already emitted) +let windowsRmListPsEncodedCommandCache; +let windowsRmListPsLoadFailureWarned = false; +function getWindowsRmListEncodedCommand() { + if (windowsRmListPsEncodedCommandCache !== undefined) { + return windowsRmListPsEncodedCommandCache; + } + try { + const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1'); + const src = fs + .readFileSync(ps1Path, 'utf8') + .replace(/^\uFEFF/, '') + .replace(/\r\n/g, '\n'); + windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64'); + } catch (err) { + windowsRmListPsEncodedCommandCache = null; + if ( + !windowsRmListPsLoadFailureWarned && + (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true') + ) { + windowsRmListPsLoadFailureWarned = true; + const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown'; + process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`); + } + } + return windowsRmListPsEncodedCommandCache; +} + +function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) { + const encoded = getWindowsRmListEncodedCommand(); + if (!encoded) return false; + const psExe = resolveWindowsPowerShellPath(); + const r = spawnSync( + psExe, + [ + '-NoProfile', + '-NonInteractive', + '-ExecutionPolicy', + 'Bypass', + '-STA', + '-EncodedCommand', + encoded, + ], + { + encoding: 'utf-8', + timeout: 6000, + stdio: ['ignore', 'pipe', 'ignore'], + env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs }, + }, + ); + // ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment). + if (r.error) return r.error.code === 'ETIMEDOUT'; + if (r.status !== 0) return false; + let rows; + try { + rows = JSON.parse(String(r.stdout || '').trim() || '[]'); + } catch { + return false; + } + if (!Array.isArray(rows)) return false; + for (const row of rows) { + const procId = Number(row.pid); + const cmd = String(row.cmd || ''); + if (!Number.isFinite(procId) || procId === myPid) continue; + if (isGitNexusServerCommand(cmd)) return true; + } + return false; +} + +function readLinuxCmdline(pidStr) { + try { + return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim(); + } catch { + return ''; + } +} + +function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) { + const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS; + const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200; + const start = Date.now(); + let targetStat; + try { + targetStat = fs.statSync(dbPathAbs); + } catch { + return false; + } + let procEntries; + try { + procEntries = fs.readdirSync('/proc', { withFileTypes: true }); + } catch { + return false; + } + for (const ent of procEntries) { + if (Date.now() - start > budget) return false; + if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue; + const pid = Number.parseInt(ent.name, 10); + if (!Number.isFinite(pid) || pid === myPid) continue; + const fdDir = path.join('/proc', ent.name, 'fd'); + let fds; + try { + fds = fs.readdirSync(fdDir); + } catch { + continue; + } + let holds = false; + for (const fd of fds) { + if (Date.now() - start > budget) return false; + try { + const st = fs.statSync(path.join(fdDir, fd)); + if (st.dev === targetStat.dev && st.ino === targetStat.ino) { + holds = true; + break; + } + } catch { + /* ignore */ + } + } + if (!holds) continue; + if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true; + } + return false; +} + +function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) { + const lsofPath = resolveHookBinary('lsof'); + const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], { + encoding: 'utf-8', + timeout: 1000, + stdio: ['ignore', 'pipe', 'ignore'], + }); + if (lsof.error) return lsof.error.code === 'ETIMEDOUT'; + + const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean); + const psPath = resolveHookBinary('ps'); + for (const pid of pids) { + if (Number(pid) === myPid) continue; + const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], { + encoding: 'utf-8', + timeout: 500, + stdio: ['ignore', 'pipe', 'ignore'], + }); + if (ps.error) { + if (ps.error.code === 'ETIMEDOUT') return true; + continue; + } + if (isGitNexusServerCommand(ps.stdout || '')) return true; + } + return false; +} + +/** + * @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug). + * @param {number} myPid Current process PID (hook runner), excluded from matches. + */ +function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) { + if (!fs.existsSync(dbPath)) return false; + const dbPathAbs = path.resolve(dbPath); + + if (process.platform === 'win32') { + return hasGitNexusServerOwnerWindows(dbPathAbs, myPid); + } + + if (process.platform === 'linux') { + if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true; + return unixLsofPsFindGitNexusServer(dbPathAbs, myPid); + } + + return unixLsofPsFindGitNexusServer(dbPathAbs, myPid); +} + +module.exports = { + hasGitNexusDbLockedByGitNexusServer, +}; diff --git a/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 new file mode 100644 index 000000000..5c1564e30 --- /dev/null +++ b/gitnexus-claude-plugin/hooks/win-rm-list-json.ps1 @@ -0,0 +1,76 @@ +$ErrorActionPreference = 'Stop' +$target = $env:GITNEXUS_HOOK_RM_TARGET +if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 } +$target = (Resolve-Path -LiteralPath $target).ProviderPath + +if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) { +Add-Type @' +using System; +using System.Runtime.InteropServices; +namespace GitNexusHookRm { + public static class Native { + public const int ErrorMoreData = 234; + [StructLayout(LayoutKind.Sequential, Pack = 4)] + public struct RM_UNIQUE_PROCESS { + public int dwProcessId; + public long ProcessStartTime; + } + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] + public struct RM_PROCESS_INFO { + public RM_UNIQUE_PROCESS Process; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] + public string strAppName; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] + public string strServiceShortName; + public uint ApplicationType; + public uint AppStatus; + public uint TSSessionId; + public uint bRestartable; + } + [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] + public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey); + [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] + public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames); + [DllImport("rstrtmgr.dll")] + public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons); + [DllImport("rstrtmgr.dll")] + public static extern int RmEndSession(uint pSessionHandle); + } +} +'@ +} + +$h = [uint32]0 +$key = [guid]::NewGuid().ToString('N') +$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key) +if ($rmErr -ne 0) { Write-Output '[]'; exit 0 } +$files = @($target) +$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null) +if ($err -ne 0) { + [void][GitNexusHookRm.Native]::RmEndSession($h) + Write-Output '[]' + exit 0 +} +$need = [uint32]0 +$n = [uint32]0 +$reboot = [uint32]0 +$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot) +if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) { + [void][GitNexusHookRm.Native]::RmEndSession($h) + Write-Output '[]' + exit 0 +} +$n = $need +$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n) +$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot) +[void][GitNexusHookRm.Native]::RmEndSession($h) +if ($err -ne 0) { Write-Output '[]'; exit 0 } + +$out = @() +for ($i = 0; $i -lt [int]$n; $i++) { + $procId = $buf[$i].Process.dwProcessId + $p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue + $cmd = if ($p) { $p.CommandLine } else { '' } + $out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd } +} +ConvertTo-Json -InputObject @($out) -Compress diff --git a/gitnexus/hooks/claude/gitnexus-hook.cjs b/gitnexus/hooks/claude/gitnexus-hook.cjs index 9541fcb50..e39fcf8e1 100755 --- a/gitnexus/hooks/claude/gitnexus-hook.cjs +++ b/gitnexus/hooks/claude/gitnexus-hook.cjs @@ -15,6 +15,7 @@ const fs = require('fs'); const path = require('path'); const { spawnSync } = require('child_process'); const { acquireHookSlot } = require('./hook-lock.cjs'); +const { hasGitNexusDbLockedByGitNexusServer } = require('./hook-db-lock-probe.cjs'); /** * Read JSON input from stdin synchronously. @@ -103,6 +104,28 @@ function findGitNexusDir(startDir) { return null; } +function hasGitNexusServerOwner(gitNexusDir) { + return hasGitNexusDbLockedByGitNexusServer(path.join(gitNexusDir, 'lbug'), process.pid); +} + +function extractAugmentContext(stderr) { + const output = (stderr || '').trim(); + const marker = output.indexOf('[GitNexus]'); + const debug = process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true'; + if (debug && output.length > 0) { + // Emit the FULL discarded prefix (everything before the marker, or all of + // it when no marker is present) so suppressed diagnostics — KuzuDB lock + // warnings, parser errors, etc. — remain recoverable on the hook's own + // stderr. The untruncated payload lets operators see exactly what was + // filtered out instead of a 180-char JSON-quoted preview. + const discarded = marker === -1 ? output : output.slice(0, marker).trim(); + if (discarded.length > 0) { + process.stderr.write(`[GitNexus hook] augment stderr discarded prefix:\n${discarded}\n`); + } + } + return marker === -1 ? '' : output.slice(marker).trim(); +} + /** * Extract search pattern from tool input. */ @@ -168,6 +191,10 @@ function extractPattern(toolName, toolInput) { * 3. Fall back to npx (returns empty string) */ function resolveCliPath() { + const fromEnv = process.env.GITNEXUS_HOOK_CLI_PATH; + if (fromEnv !== undefined && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) { + return String(fromEnv); + } let cliPath = path.resolve(__dirname, '..', '..', 'dist', 'cli', 'index.js'); if (!fs.existsSync(cliPath)) { try { @@ -218,6 +245,10 @@ function handlePreToolUse(input) { const pattern = extractPattern(toolName, toolInput); if (!pattern || pattern.length < 3) return; + if (hasGitNexusServerOwner(gitNexusDir)) { + process.stderr.write('[GitNexus] augment skipped: MCP server owns DB\n'); + return; + } const release = acquireHookSlot(gitNexusDir); if (!release) return; @@ -227,7 +258,7 @@ function handlePreToolUse(input) { try { const child = runGitNexusCli(cliPath, ['augment', '--', pattern], cwd, 7000); if (!child.error && child.status === 0) { - result = child.stderr || ''; + result = extractAugmentContext(child.stderr || ''); } } catch { /* graceful failure */ @@ -235,8 +266,8 @@ function handlePreToolUse(input) { release(); } - if (result && result.trim()) { - sendHookResponse('PreToolUse', result.trim()); + if (result) { + sendHookResponse('PreToolUse', result); } } diff --git a/gitnexus/hooks/claude/hook-db-lock-probe.cjs b/gitnexus/hooks/claude/hook-db-lock-probe.cjs new file mode 100644 index 000000000..783cd0804 --- /dev/null +++ b/gitnexus/hooks/claude/hook-db-lock-probe.cjs @@ -0,0 +1,238 @@ +/** + * Cross-platform best-effort probe: does another process hold dbPath open + * with a command line that looks like a GitNexus MCP/serve server? + * + * Backends (no user-installed Sysinternals): + * - Linux: scan procfs under /proc (per-PID fd entries) via stat(2) (dev+inode); works without lsof; + * optional lsof fallback when proc scan finds nothing. + * - macOS / *BSD / etc.: trusted lsof + ps (absolute paths first). + * - Windows: Restart Manager (rstrtmgr) via bundled PowerShell script + + * Win32_Process for command lines; trusted powershell.exe under %SystemRoot%. + * + * Fail-open on most errors; fail-closed only on lsof ETIMEDOUT (Unix) or + * PowerShell ETIMEDOUT (Windows), matching the hook contract. + */ + +const fs = require('fs'); +const path = require('path'); +const { spawnSync } = require('child_process'); + +function isGitNexusServerCommand(command) { + const hasServerMode = /(?:^|\s)(mcp|serve)(?:\s|$)/.test(command); + const hasGitNexus = + /(?:^|[/\\\s])gitnexus(?:\.cmd)?(?:\s|$)/.test(command) || + /node_modules[/\\]gitnexus[/\\]/.test(command); + return hasServerMode && hasGitNexus; +} + +function resolveHookBinary(tool) { + const envKey = tool === 'lsof' ? 'GITNEXUS_HOOK_LSOF_PATH' : 'GITNEXUS_HOOK_PS_PATH'; + const fromEnv = process.env[envKey]; + if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv))) { + return String(fromEnv); + } + const candidates = + tool === 'lsof' + ? ['/usr/bin/lsof', '/usr/sbin/lsof', '/sbin/lsof', tool] + : ['/bin/ps', '/usr/bin/ps', tool]; + for (const candidate of candidates) { + if (candidate === tool) return tool; + try { + if (fs.existsSync(candidate)) return candidate; + } catch { + /* ignore */ + } + } + return tool; +} + +function resolveWindowsPowerShellPath() { + const fromEnv = process.env.GITNEXUS_HOOK_POWERSHELL_PATH; + if (fromEnv && String(fromEnv).trim() && fs.existsSync(String(fromEnv).trim())) { + return String(fromEnv).trim(); + } + const root = process.env.SystemRoot || 'C:\\Windows'; + const ps = path.join(root, 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe'); + if (fs.existsSync(ps)) return ps; + const psWow = path.join(root, 'SysWOW64', 'WindowsPowerShell', 'v1.0', 'powershell.exe'); + if (fs.existsSync(psWow)) return psWow; + return 'powershell.exe'; +} + +// Sentinel: +// undefined = not loaded yet (try the read) +// string = encoded PowerShell command (successful load) +// null = load attempted and failed (do not retry; warning already emitted) +let windowsRmListPsEncodedCommandCache; +let windowsRmListPsLoadFailureWarned = false; +function getWindowsRmListEncodedCommand() { + if (windowsRmListPsEncodedCommandCache !== undefined) { + return windowsRmListPsEncodedCommandCache; + } + try { + const ps1Path = path.join(__dirname, 'win-rm-list-json.ps1'); + const src = fs + .readFileSync(ps1Path, 'utf8') + .replace(/^\uFEFF/, '') + .replace(/\r\n/g, '\n'); + windowsRmListPsEncodedCommandCache = Buffer.from(src, 'utf16le').toString('base64'); + } catch (err) { + windowsRmListPsEncodedCommandCache = null; + if ( + !windowsRmListPsLoadFailureWarned && + (process.env.GITNEXUS_DEBUG === '1' || process.env.GITNEXUS_DEBUG === 'true') + ) { + windowsRmListPsLoadFailureWarned = true; + const msg = err && err.message ? String(err.message).slice(0, 200) : 'unknown'; + process.stderr.write(`[GitNexus hook] win-rm-list-json.ps1 load failed: ${msg}\n`); + } + } + return windowsRmListPsEncodedCommandCache; +} + +function hasGitNexusServerOwnerWindows(dbPathAbs, myPid) { + const encoded = getWindowsRmListEncodedCommand(); + if (!encoded) return false; + const psExe = resolveWindowsPowerShellPath(); + const r = spawnSync( + psExe, + [ + '-NoProfile', + '-NonInteractive', + '-ExecutionPolicy', + 'Bypass', + '-STA', + '-EncodedCommand', + encoded, + ], + { + encoding: 'utf-8', + timeout: 6000, + stdio: ['ignore', 'pipe', 'ignore'], + env: { ...process.env, GITNEXUS_HOOK_RM_TARGET: dbPathAbs }, + }, + ); + // ETIMEDOUT means the PowerShell probe didn't return in time; treat as 'unresponsive process holds DB' → fail-closed (skip augment). + if (r.error) return r.error.code === 'ETIMEDOUT'; + if (r.status !== 0) return false; + let rows; + try { + rows = JSON.parse(String(r.stdout || '').trim() || '[]'); + } catch { + return false; + } + if (!Array.isArray(rows)) return false; + for (const row of rows) { + const procId = Number(row.pid); + const cmd = String(row.cmd || ''); + if (!Number.isFinite(procId) || procId === myPid) continue; + if (isGitNexusServerCommand(cmd)) return true; + } + return false; +} + +function readLinuxCmdline(pidStr) { + try { + return fs.readFileSync(`/proc/${pidStr}/cmdline`, 'utf8').replace(/\0+/g, ' ').trim(); + } catch { + return ''; + } +} + +function linuxProcScanFindGitNexusServer(dbPathAbs, myPid) { + const raw = process.env.GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS; + const budget = Number(raw && String(raw).trim()) ? Number.parseInt(String(raw), 10) : 1200; + const start = Date.now(); + let targetStat; + try { + targetStat = fs.statSync(dbPathAbs); + } catch { + return false; + } + let procEntries; + try { + procEntries = fs.readdirSync('/proc', { withFileTypes: true }); + } catch { + return false; + } + for (const ent of procEntries) { + if (Date.now() - start > budget) return false; + if (!ent.isDirectory() || !/^\d+$/.test(ent.name)) continue; + const pid = Number.parseInt(ent.name, 10); + if (!Number.isFinite(pid) || pid === myPid) continue; + const fdDir = path.join('/proc', ent.name, 'fd'); + let fds; + try { + fds = fs.readdirSync(fdDir); + } catch { + continue; + } + let holds = false; + for (const fd of fds) { + if (Date.now() - start > budget) return false; + try { + const st = fs.statSync(path.join(fdDir, fd)); + if (st.dev === targetStat.dev && st.ino === targetStat.ino) { + holds = true; + break; + } + } catch { + /* ignore */ + } + } + if (!holds) continue; + if (isGitNexusServerCommand(readLinuxCmdline(ent.name))) return true; + } + return false; +} + +function unixLsofPsFindGitNexusServer(dbPathAbs, myPid) { + const lsofPath = resolveHookBinary('lsof'); + const lsof = spawnSync(lsofPath, ['-nP', '-t', '--', dbPathAbs], { + encoding: 'utf-8', + timeout: 1000, + stdio: ['ignore', 'pipe', 'ignore'], + }); + if (lsof.error) return lsof.error.code === 'ETIMEDOUT'; + + const pids = (lsof.stdout || '').split(/\s+/).filter(Boolean); + const psPath = resolveHookBinary('ps'); + for (const pid of pids) { + if (Number(pid) === myPid) continue; + const ps = spawnSync(psPath, ['-p', pid, '-o', 'command='], { + encoding: 'utf-8', + timeout: 500, + stdio: ['ignore', 'pipe', 'ignore'], + }); + if (ps.error) { + if (ps.error.code === 'ETIMEDOUT') return true; + continue; + } + if (isGitNexusServerCommand(ps.stdout || '')) return true; + } + return false; +} + +/** + * @param {string} dbPath Absolute or relative path to the DB file (e.g. .../lbug). + * @param {number} myPid Current process PID (hook runner), excluded from matches. + */ +function hasGitNexusDbLockedByGitNexusServer(dbPath, myPid) { + if (!fs.existsSync(dbPath)) return false; + const dbPathAbs = path.resolve(dbPath); + + if (process.platform === 'win32') { + return hasGitNexusServerOwnerWindows(dbPathAbs, myPid); + } + + if (process.platform === 'linux') { + if (linuxProcScanFindGitNexusServer(dbPathAbs, myPid)) return true; + return unixLsofPsFindGitNexusServer(dbPathAbs, myPid); + } + + return unixLsofPsFindGitNexusServer(dbPathAbs, myPid); +} + +module.exports = { + hasGitNexusDbLockedByGitNexusServer, +}; diff --git a/gitnexus/hooks/claude/win-rm-list-json.ps1 b/gitnexus/hooks/claude/win-rm-list-json.ps1 new file mode 100644 index 000000000..5c1564e30 --- /dev/null +++ b/gitnexus/hooks/claude/win-rm-list-json.ps1 @@ -0,0 +1,76 @@ +$ErrorActionPreference = 'Stop' +$target = $env:GITNEXUS_HOOK_RM_TARGET +if ([string]::IsNullOrWhiteSpace($target)) { Write-Output '[]'; exit 0 } +$target = (Resolve-Path -LiteralPath $target).ProviderPath + +if (-not ([Management.Automation.PSTypeName]'GitNexusHookRm.Native').Type) { +Add-Type @' +using System; +using System.Runtime.InteropServices; +namespace GitNexusHookRm { + public static class Native { + public const int ErrorMoreData = 234; + [StructLayout(LayoutKind.Sequential, Pack = 4)] + public struct RM_UNIQUE_PROCESS { + public int dwProcessId; + public long ProcessStartTime; + } + [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)] + public struct RM_PROCESS_INFO { + public RM_UNIQUE_PROCESS Process; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 256)] + public string strAppName; + [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 64)] + public string strServiceShortName; + public uint ApplicationType; + public uint AppStatus; + public uint TSSessionId; + public uint bRestartable; + } + [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] + public static extern int RmStartSession(out uint pSessionHandle, uint dwSessionFlags, string strSessionKey); + [DllImport("rstrtmgr.dll", CharSet = CharSet.Unicode)] + public static extern int RmRegisterResources(uint pSessionHandle, uint nFiles, string[] rgsFileNames, uint nApplications, IntPtr rgApplications, uint nServices, string[] rgsServiceNames); + [DllImport("rstrtmgr.dll")] + public static extern int RmGetList(uint dwSessionHandle, out uint pnProcInfoNeeded, ref uint pnProcInfo, [In, Out] RM_PROCESS_INFO[] rgAffectedApps, ref uint lpdwRebootReasons); + [DllImport("rstrtmgr.dll")] + public static extern int RmEndSession(uint pSessionHandle); + } +} +'@ +} + +$h = [uint32]0 +$key = [guid]::NewGuid().ToString('N') +$rmErr = [GitNexusHookRm.Native]::RmStartSession([ref]$h, 0, $key) +if ($rmErr -ne 0) { Write-Output '[]'; exit 0 } +$files = @($target) +$err = [GitNexusHookRm.Native]::RmRegisterResources($h, 1, $files, 0, [IntPtr]::Zero, 0, $null) +if ($err -ne 0) { + [void][GitNexusHookRm.Native]::RmEndSession($h) + Write-Output '[]' + exit 0 +} +$need = [uint32]0 +$n = [uint32]0 +$reboot = [uint32]0 +$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $null, [ref]$reboot) +if ($err -ne [GitNexusHookRm.Native]::ErrorMoreData) { + [void][GitNexusHookRm.Native]::RmEndSession($h) + Write-Output '[]' + exit 0 +} +$n = $need +$buf = New-Object GitNexusHookRm.Native+RM_PROCESS_INFO[] ([int]$n) +$err = [GitNexusHookRm.Native]::RmGetList($h, [ref]$need, [ref]$n, $buf, [ref]$reboot) +[void][GitNexusHookRm.Native]::RmEndSession($h) +if ($err -ne 0) { Write-Output '[]'; exit 0 } + +$out = @() +for ($i = 0; $i -lt [int]$n; $i++) { + $procId = $buf[$i].Process.dwProcessId + $p = Get-CimInstance -ClassName Win32_Process -Filter "ProcessId=$procId" -ErrorAction SilentlyContinue + $cmd = if ($p) { $p.CommandLine } else { '' } + $out += [PSCustomObject]@{ pid = [int]$procId; cmd = $cmd } +} +ConvertTo-Json -InputObject @($out) -Compress diff --git a/gitnexus/src/cli/setup.ts b/gitnexus/src/cli/setup.ts index 8f52e0f2d..3e7cbad8f 100644 --- a/gitnexus/src/cli/setup.ts +++ b/gitnexus/src/cli/setup.ts @@ -373,6 +373,24 @@ async function installClaudeCodeHooks(result: SetupResult): Promise { // Helper not found in source — skip } + try { + await fs.copyFile( + path.join(pluginHooksPath, 'hook-db-lock-probe.cjs'), + path.join(destHooksDir, 'hook-db-lock-probe.cjs'), + ); + } catch { + // Helper not found in source — skip + } + + try { + await fs.copyFile( + path.join(pluginHooksPath, 'win-rm-list-json.ps1'), + path.join(destHooksDir, 'win-rm-list-json.ps1'), + ); + } catch { + // Helper not found in source — skip + } + const hookPath = path.join(destHooksDir, 'gitnexus-hook.cjs').replace(/\\/g, '/'); // Escape backslashes FIRST, then quotes (CodeQL js/incomplete-sanitization). // The previous shape `replace(/"/g, '\\"')` alone would let `path\with"quote` diff --git a/gitnexus/test/unit/hooks.test.ts b/gitnexus/test/unit/hooks.test.ts index 346ee1ed6..a0ef2b8cb 100644 --- a/gitnexus/test/unit/hooks.test.ts +++ b/gitnexus/test/unit/hooks.test.ts @@ -12,6 +12,7 @@ * - shell injection: verifies no shell: true in spawnSync calls * - dispatch map: correct handler routing * - cross-platform: Windows .cmd extension handling + * - cross-platform: DB lock probe (Linux /proc, Unix lsof, Windows RM) * * Since the hooks are CJS scripts that call main() on load, we test them * by spawning them as child processes with controlled stdin JSON. @@ -45,6 +46,23 @@ const PLUGIN_HOOK_LOCK = path.resolve( 'hooks', 'hook-lock.js', ); +const CJS_HOOK_DB_PROBE = path.resolve( + __dirname, + '..', + '..', + 'hooks', + 'claude', + 'hook-db-lock-probe.cjs', +); +const PLUGIN_HOOK_DB_PROBE = path.resolve( + __dirname, + '..', + '..', + '..', + 'gitnexus-claude-plugin', + 'hooks', + 'hook-db-lock-probe.cjs', +); // ─── Test fixtures: temporary .gitnexus directory ─────────────────── @@ -109,6 +127,62 @@ function createGlobalRegistry(homeDir: string, marker: 'both' | 'registry' | 're } } +function writeExecutable(filePath: string, content: string) { + fs.writeFileSync(filePath, content, { mode: 0o755 }); +} + +function createHookToolDir(options: { + gitnexusStderr?: string; + gitnexusMarkerPath?: string; + lsofOutput?: string; + lsofOutputLines?: string[]; + psOutput?: string; + psOutputByPid?: Record; + lsofSleepMs?: number; +}) { + const binDir = fs.mkdtempSync(path.join(os.tmpdir(), 'gitnexus-hook-bin-')); + const gitnexusStderr = JSON.stringify(options.gitnexusStderr ?? ''); + const markerPath = JSON.stringify(options.gitnexusMarkerPath ?? ''); + + const fakeGitNexus = `#!/usr/bin/env node\nconst fs = require('fs');\nconst marker = ${markerPath};\nif (marker) fs.writeFileSync(marker, 'called');\nprocess.stderr.write(${gitnexusStderr});\n`; + writeExecutable(path.join(binDir, 'gitnexus'), fakeGitNexus); + writeExecutable(path.join(binDir, 'gitnexus-cli.js'), fakeGitNexus); + + const lsofOutput = + options.lsofOutputLines != null + ? options.lsofOutputLines.join('\n') + (options.lsofOutputLines.length ? '\n' : '') + : (options.lsofOutput ?? ''); + const lsofBody = + options.lsofSleepMs != null + ? `#!/usr/bin/env node\nsetTimeout(() => {}, ${Number(options.lsofSleepMs)});\n` + : `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(lsofOutput)});\nprocess.exit(0);\n`; + writeExecutable(path.join(binDir, 'lsof'), lsofBody); + + const psBody = + options.psOutputByPid != null + ? `#!/usr/bin/env node +const byPid = ${JSON.stringify(options.psOutputByPid)}; +const args = process.argv; +const p = args[args.indexOf('-p') + 1]; +process.stdout.write(byPid[p] ?? ''); +process.exit(0); +` + : `#!/usr/bin/env node\nprocess.stdout.write(${JSON.stringify(options.psOutput ?? '')});\nprocess.exit(0);\n`; + writeExecutable(path.join(binDir, 'ps'), psBody); + + return binDir; +} + +function hookEnv(binDir: string) { + return { + ...process.env, + PATH: `${binDir}${path.delimiter}${process.env.PATH || ''}`, + GITNEXUS_HOOK_CLI_PATH: path.join(binDir, 'gitnexus-cli.js'), + GITNEXUS_HOOK_LSOF_PATH: path.join(binDir, 'lsof'), + GITNEXUS_HOOK_PS_PATH: path.join(binDir, 'ps'), + }; +} + // ─── Both hook files should exist ─────────────────────────────────── describe('Hook files exist', () => { @@ -594,6 +668,430 @@ describe('PreToolUse concurrency guard (integration)', () => { } }); +// ─── Source: cross-platform DB lock probe module (#1493) ───────────── + +describe('Cross-platform DB lock probe (source)', () => { + for (const [label, hookPath, probePath] of [ + ['CJS', CJS_HOOK, CJS_HOOK_DB_PROBE], + ['Plugin', PLUGIN_HOOK, PLUGIN_HOOK_DB_PROBE], + ] as const) { + it(`${label} probe file exists`, () => { + expect(fs.existsSync(probePath)).toBe(true); + }); + + it(`${label} hook requires hook-db-lock-probe.cjs`, () => { + const source = fs.readFileSync(hookPath, 'utf-8'); + expect(source).toContain("require('./hook-db-lock-probe.cjs')"); + }); + + it(`${label} probe covers Linux /proc, Unix lsof, and Windows Restart Manager`, () => { + const p = fs.readFileSync(probePath, 'utf-8'); + expect(p).toContain('win-rm-list-json.ps1'); + expect(p).toContain('/proc/'); + expect(p).toContain('linuxProcScanFindGitNexusServer'); + expect(p).toContain('unixLsofPsFindGitNexusServer'); + expect(p).toContain('hasGitNexusServerOwnerWindows'); + expect(p).toContain('GITNEXUS_HOOK_LSOF_PATH'); + expect(p).toContain('GITNEXUS_HOOK_POWERSHELL_PATH'); + expect(p).toContain('GITNEXUS_HOOK_LINUX_PROC_BUDGET_MS'); + }); + } +}); + +// ─── Integration: PreToolUse augmentation filtering (#1492) ───────── + +describe('PreToolUse augmentation filtering (integration)', () => { + for (const [label, hookPath] of [ + ['CJS', CJS_HOOK], + ['Plugin', PLUGIN_HOOK], + ] as const) { + it(`${label}: emits valid GitNexus augmentation context`, () => { + const binDir = createHookToolDir({ + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + + const output = parseHookOutput(result.stdout); + expect(output).not.toBeNull(); + expect(output!.hookEventName).toBe('PreToolUse'); + expect(output!.additionalContext).toContain('[GitNexus] 1 related symbol found'); + } finally { + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: suppresses LadybugDB lock warnings from augment stderr`, () => { + const markerPath = path.join(os.tmpdir(), 'gn-hook-lockwarn-' + process.pid + '-' + label); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: + 'GitNexus: FTS extension load failed: IO exception: Could not set lock on file : /tmp/repo/.gitnexus/lbug\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + + expect(result.stdout.trim()).toBe(''); + expect(fs.existsSync(markerPath)).toBe(true); + + // Finding #18: when GITNEXUS_DEBUG=1 is set, the discarded prefix is + // recoverable on the hook's stderr (not silently dropped). + const debugResult = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: { ...hookEnv(binDir), GITNEXUS_DEBUG: '1' } }, + ); + expect(debugResult.stderr).toContain('augment stderr discarded prefix'); + expect(debugResult.stderr).toContain('Could not set lock on file'); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it.skipIf(process.platform === 'win32')( + `${label}: skips augment when a GitNexus MCP process owns the repo DB`, + () => { + const markerPath = path.join(os.tmpdir(), `gitnexus-hook-called-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + lsofOutput: '12345\n', + psOutput: 'node /tmp/node_modules/.bin/gitnexus mcp\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + + expect(result.stdout.trim()).toBe(''); + expect(result.status).toBe(0); + expect(result.stderr).toContain('[GitNexus] augment skipped'); + expect(fs.existsSync(markerPath)).toBe(false); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }, + ); + } +}); + +describe.skipIf(process.platform === 'win32')( + 'Ladybug DB owner guard — production-shaped ps + failure modes (#1493)', + () => { + for (const [label, hookPath] of [ + ['CJS', CJS_HOOK], + ['Plugin', PLUGIN_HOOK], + ] as const) { + it(`${label}: skips augment for real node_modules/gitnexus ps line (npx child)`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-prodps-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + lsofOutput: '99901\n', + psOutput: 'node /tmp/node_modules/gitnexus/dist/cli/index.js mcp\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + expect(result.stdout.trim()).toBe(''); + expect(result.status).toBe(0); + expect(result.stderr).toContain('[GitNexus] augment skipped'); + expect(fs.existsSync(markerPath)).toBe(false); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: npx parent command line is NOT treated as GitNexus server owner`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-npx-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + lsofOutput: '99902\n', + psOutput: 'npx -y gitnexus@latest mcp\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + const output = parseHookOutput(result.stdout); + expect(output).not.toBeNull(); + expect(fs.existsSync(markerPath)).toBe(true); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: skips augment for gitnexus serve child`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-serve-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + lsofOutput: '99903\n', + psOutput: 'node /repo/node_modules/gitnexus/dist/cli/index.js serve\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + expect(result.stdout.trim()).toBe(''); + expect(result.status).toBe(0); + expect(result.stderr).toContain('[GitNexus] augment skipped'); + expect(fs.existsSync(markerPath)).toBe(false); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: ENOENT lsof → augment still runs (fail-open)`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-enoent-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + lsofOutput: '', + psOutput: '', + }); + try { + const env = { + ...hookEnv(binDir), + GITNEXUS_HOOK_LSOF_PATH: path.join(binDir, '__missing_lsof__'), + }; + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env }, + ); + const output = parseHookOutput(result.stdout); + expect(output).not.toBeNull(); + expect(fs.existsSync(markerPath)).toBe(true); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: ETIMEDOUT lsof → augment skipped (fail-closed)`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-etime-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + lsofSleepMs: 5000, + psOutput: '', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + expect(result.stdout.trim()).toBe(''); + expect(result.status).toBe(0); + expect(result.stderr).toContain('[GitNexus] augment skipped'); + expect(fs.existsSync(markerPath)).toBe(false); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: non-GitNexus ps line → augment runs`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-other-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + lsofOutput: '99904\n', + psOutput: '/usr/bin/bash -l\n', + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + const output = parseHookOutput(result.stdout); + expect(output).not.toBeNull(); + expect(fs.existsSync(markerPath)).toBe(true); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: multiple PIDs — skip if any ps line is GitNexus MCP`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-multi-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + lsofOutputLines: ['111', '222'], + psOutputByPid: { + '111': 'vim /tmp/x\n', + '222': 'node /x/node_modules/gitnexus/dist/cli/index.js mcp\n', + }, + }); + try { + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env: hookEnv(binDir) }, + ); + expect(result.stdout.trim()).toBe(''); + expect(result.status).toBe(0); + expect(result.stderr).toContain('[GitNexus] augment skipped'); + expect(fs.existsSync(markerPath)).toBe(false); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + + it(`${label}: ps ENOENT → augment runs (ignore that PID)`, () => { + const markerPath = path.join(os.tmpdir(), `gn-hook-pseno-${process.pid}-${label}`); + const lbugPath = path.join(gitNexusDir, 'lbug'); + fs.writeFileSync(lbugPath, ''); + fs.rmSync(markerPath, { force: true }); + const binDir = createHookToolDir({ + gitnexusMarkerPath: markerPath, + gitnexusStderr: '[GitNexus] 1 related symbol found:\n\nvalidateUser (src/auth.ts)\n', + lsofOutput: '99905\n', + psOutput: '', + }); + try { + const env = { + ...hookEnv(binDir), + GITNEXUS_HOOK_PS_PATH: path.join(binDir, '__missing_ps__'), + }; + const result = runHook( + hookPath, + { + hook_event_name: 'PreToolUse', + tool_name: 'Grep', + tool_input: { pattern: 'validateUser' }, + cwd: tmpDir, + }, + undefined, + { env }, + ); + const output = parseHookOutput(result.stdout); + expect(output).not.toBeNull(); + expect(fs.existsSync(markerPath)).toBe(true); + } finally { + fs.rmSync(markerPath, { force: true }); + fs.rmSync(binDir, { recursive: true, force: true }); + } + }); + } + }, +); + // ─── Integration: PostToolUse staleness detection ─────────────────── describe('PostToolUse staleness detection (integration)', () => { diff --git a/gitnexus/test/unit/setup.test.ts b/gitnexus/test/unit/setup.test.ts index 95ad261f0..bdf1cd1fd 100644 --- a/gitnexus/test/unit/setup.test.ts +++ b/gitnexus/test/unit/setup.test.ts @@ -267,6 +267,21 @@ describe('setupClaudeCode', () => { }); }); + it('copies hook-db-lock-probe.cjs and win-rm-list-json.ps1 to ~/.claude/hooks/gitnexus/', async () => { + setPlatform('linux'); + + const { setupCommand } = await import('../../src/cli/setup.js'); + await setupCommand(); + + const destHooksDir = path.join(tempHome, '.claude', 'hooks', 'gitnexus'); + await expect( + fs.access(path.join(destHooksDir, 'hook-db-lock-probe.cjs')), + ).resolves.toBeUndefined(); + await expect( + fs.access(path.join(destHooksDir, 'win-rm-list-json.ps1')), + ).resolves.toBeUndefined(); + }); + it('falls back to first line on Windows when no .cmd/.bat wrapper found', async () => { setPlatform('win32'); // Edge case: where returns only the POSIX script (no .cmd wrapper) diff --git a/gitnexus/test/utils/hook-test-helpers.ts b/gitnexus/test/utils/hook-test-helpers.ts index 6f5c5fbfd..3f519bc81 100644 --- a/gitnexus/test/utils/hook-test-helpers.ts +++ b/gitnexus/test/utils/hook-test-helpers.ts @@ -7,12 +7,14 @@ export function runHook( hookPath: string, input: Record, cwd?: string, + options: { env?: NodeJS.ProcessEnv } = {}, ): { stdout: string; stderr: string; status: number | null } { const result = spawnSync(process.execPath, [hookPath], { input: JSON.stringify(input), encoding: 'utf-8', timeout: 10000, cwd, + env: options.env, stdio: ['pipe', 'pipe', 'pipe'], }); return { From 8b2d8018bc860c68632e8d0bed8092a77352cab3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?L=C3=A9on=20Simmons?= Date: Thu, 14 May 2026 12:26:34 -0400 Subject: [PATCH 30/33] fix(cli): tolerate read-only workspace in `ensureGitNexusIgnored` (#1549) (#1550) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * fix(cli): tolerate read-only workspace in ensureGitNexusIgnored The documented Docker workflow mounts the host workspace at /workspace:ro and runs `gitnexus index /workspace/` against an index produced by a prior host-side `analyze`. Since PR #1248 ("keep GitNexus ignores inside .gitnexus") the index command has called `ensureGitNexusIgnored`, which unconditionally writes `/.gitnexus/.gitignore` and `/.git/info/exclude` — both fail with EROFS on the :ro bind mount even though the host already wrote the correct file during `analyze`. Two complementary changes: 1. Idempotent fast path. Read the existing .gitnexus/.gitignore content first; if it already matches the desired value (`*\n`), skip the write entirely. This is the common case for the Docker workflow and avoids touching the FS at all. 2. EROFS/EACCES tolerance. When a write is genuinely needed but the FS refuses it, log a structured warning via the existing pino logger and continue. `registerRepo` runs before `ensureGitNexusIgnored` in `indexCommand`, so the global-registry write is already committed when we get here — letting the gitignore-write failure propagate leaves the user with a registered-but-error-exited command. Three new unit tests pin the behaviour: - idempotent re-call leaves mtime untouched - ENOENT-then-correct path on a writable parent succeeds - :ro parent (simulated via chmod 0o555) does not throw, on the already-correct fast path and on the cold-create path Existing tests (61) still pass. Closes #1549. * test(storage): cover read-only ignore paths and tolerate EPERM (#1550) - Add isReadOnlyFilesystemError helper including EPERM alongside EROFS/EACCES for ensureGitNexusIgnored and ensureGitInfoExclude (Windows parity with lbug-config / bridge-db patterns). - Skip chmod-based read-only tests on win32 and uid 0; assert logger.warn on POSIX chmod denial for missing .gitignore. - Add repo-manager-ensure-ignore-readonly.test.ts with vi.mock fs/promises delegating writeFile so EROFS/EACCES/EPERM rejections are asserted with structured log path and message for both .gitignore and .git/info/exclude. Co-authored-by: Cursor * chore(autofix): apply prettier + eslint fixes via /autofix command --------- Co-authored-by: Gergő Magyar Co-authored-by: Cursor Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- gitnexus/src/storage/repo-manager.ts | 51 +++++++- ...epo-manager-ensure-ignore-readonly.test.ts | 113 ++++++++++++++++++ gitnexus/test/unit/repo-manager.test.ts | 72 ++++++++++- 3 files changed, 230 insertions(+), 6 deletions(-) create mode 100644 gitnexus/test/unit/repo-manager-ensure-ignore-readonly.test.ts diff --git a/gitnexus/src/storage/repo-manager.ts b/gitnexus/src/storage/repo-manager.ts index 456a6c143..44446e0ec 100644 --- a/gitnexus/src/storage/repo-manager.ts +++ b/gitnexus/src/storage/repo-manager.ts @@ -11,6 +11,7 @@ import { realpathSync } from 'fs'; import path from 'path'; import os from 'os'; import { getInferredRepoName, resolveRepoIdentityRoot } from './git.js'; +import { logger } from '../core/logger.js'; /** * Normalise a repo path for registry comparison across platforms @@ -281,14 +282,44 @@ export const findRepo = async (startPath: string): Promise = return null; }; +function isReadOnlyFilesystemError(err: unknown): boolean { + const code = (err as NodeJS.ErrnoException)?.code; + return code === 'EROFS' || code === 'EACCES' || code === 'EPERM'; +} + /** * Keep generated index files ignored without modifying the user's root .gitignore. */ export const ensureGitNexusIgnored = async (repoPath: string): Promise => { const gitignorePath = path.join(getStoragePath(repoPath), '.gitignore'); + const desired = '*\n'; - await fs.mkdir(path.dirname(gitignorePath), { recursive: true }); - await fs.writeFile(gitignorePath, '*\n', 'utf-8'); + // Idempotent fast path: skip the write entirely when the file already has + // the expected content. Lets this run cleanly on read-only mounts (e.g. + // the documented Docker workflow with WORKSPACE_DIR bound :ro) when an + // earlier `analyze` already created the file. See issue #1549. + try { + if ((await fs.readFile(gitignorePath, 'utf-8')) === desired) { + await ensureGitInfoExclude(repoPath); + return; + } + } catch (err: any) { + if (err?.code !== 'ENOENT') throw err; + } + + try { + await fs.mkdir(path.dirname(gitignorePath), { recursive: true }); + await fs.writeFile(gitignorePath, desired, 'utf-8'); + } catch (err: any) { + if (isReadOnlyFilesystemError(err)) { + logger.warn( + { path: gitignorePath, code: err.code }, + 'GitNexus storage filesystem is not writable; skipping .gitnexus/.gitignore. Generated files may appear as untracked in this repo locally.', + ); + } else { + throw err; + } + } await ensureGitInfoExclude(repoPath); }; @@ -304,8 +335,6 @@ const ensureGitInfoExclude = async (repoPath: string): Promise => { return; } - await fs.mkdir(path.dirname(excludePath), { recursive: true }); - let content = ''; try { content = await fs.readFile(excludePath, 'utf-8'); @@ -320,7 +349,19 @@ const ensureGitInfoExclude = async (repoPath: string): Promise => { if (excludes.includes(GITNEXUS_DIR) || excludes.includes(GITNEXUS_EXCLUDE_ENTRY)) return; const separator = content.length === 0 || content.endsWith('\n') ? '' : '\n'; - await fs.writeFile(excludePath, `${content}${separator}${GITNEXUS_EXCLUDE_ENTRY}\n`, 'utf-8'); + try { + await fs.mkdir(path.dirname(excludePath), { recursive: true }); + await fs.writeFile(excludePath, `${content}${separator}${GITNEXUS_EXCLUDE_ENTRY}\n`, 'utf-8'); + } catch (err: any) { + if (isReadOnlyFilesystemError(err)) { + logger.warn( + { path: excludePath, code: err.code }, + 'GitNexus storage filesystem is not writable; skipping .git/info/exclude update. .gitnexus/ may appear as untracked in `git status` locally.', + ); + } else { + throw err; + } + } }; // ─── Global Registry (~/.gitnexus/registry.json) ─────────────────────── diff --git a/gitnexus/test/unit/repo-manager-ensure-ignore-readonly.test.ts b/gitnexus/test/unit/repo-manager-ensure-ignore-readonly.test.ts new file mode 100644 index 000000000..8e49a01f3 --- /dev/null +++ b/gitnexus/test/unit/repo-manager-ensure-ignore-readonly.test.ts @@ -0,0 +1,113 @@ +/** + * Read-only / permission-denied write paths for ensureGitNexusIgnored (#1549, PR #1550). + * Separate from repo-manager.test.ts: Vitest cannot vi.spyOn ESM namespace exports of + * fs/promises; a delegating vi.mock is required for cross-platform mock rejects. + */ +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; +import path from 'path'; + +const fswCtx = vi.hoisted(() => ({ + writeFileMock: vi.fn(), + realWrite: null as ((...args: unknown[]) => Promise) | null, +})); + +vi.mock('fs/promises', async (importOriginal) => { + const actual = await importOriginal(); + const d = actual.default; + fswCtx.realWrite = d.writeFile.bind(d); + fswCtx.writeFileMock.mockImplementation((...args) => fswCtx.realWrite!(...args)); + return { + default: new Proxy(d, { + get(target, prop) { + if (prop === 'writeFile') return fswCtx.writeFileMock; + const v = Reflect.get(target, prop, target) as unknown; + return typeof v === 'function' ? (v as (...args: unknown[]) => unknown).bind(target) : v; + }, + }), + }; +}); + +import fs from 'fs/promises'; +import { ensureGitNexusIgnored } from '../../src/storage/repo-manager.js'; +import { _captureLogger } from '../../src/core/logger.js'; +import { createTempDir } from '../helpers/test-db.js'; + +const samePath = (a: string, b: string) => path.normalize(a) === path.normalize(b); + +describe('ensureGitNexusIgnored — mocked writeFile (EROFS / EACCES / EPERM)', () => { + let tmpRepo: Awaited>; + + beforeEach(async () => { + tmpRepo = await createTempDir('gitnexus-ro-ignore-mock-'); + fswCtx.writeFileMock.mockClear(); + fswCtx.writeFileMock.mockImplementation((...args) => fswCtx.realWrite!(...args)); + }); + + afterEach(async () => { + await tmpRepo.cleanup(); + }); + + it.each(['EROFS', 'EACCES', 'EPERM'] as const)( + 'tolerates %s on .git/info/exclude write and logs a warn', + async (code) => { + const gitignorePath = path.join(tmpRepo.dbPath, '.gitnexus', '.gitignore'); + await fs.mkdir(path.dirname(gitignorePath), { recursive: true }); + await fs.writeFile(gitignorePath, '*\n', 'utf-8'); + + const excludePath = path.join(tmpRepo.dbPath, '.git', 'info', 'exclude'); + await fs.mkdir(path.dirname(excludePath), { recursive: true }); + await fs.writeFile(excludePath, '# empty\n', 'utf-8'); + + const cap = _captureLogger(); + fswCtx.writeFileMock.mockRejectedValueOnce(Object.assign(new Error('mock ro'), { code })); + + try { + await expect(ensureGitNexusIgnored(tmpRepo.dbPath)).resolves.not.toThrow(); + expect(fswCtx.writeFileMock).toHaveBeenCalled(); + expect( + cap + .records() + .some( + (r) => + r.level === 40 && + r.code === code && + typeof r.path === 'string' && + samePath(String(r.path), excludePath) && + String(r.msg ?? '').includes('.git/info/exclude'), + ), + ).toBe(true); + } finally { + cap.restore(); + } + }, + ); + + it.each(['EROFS', 'EACCES', 'EPERM'] as const)( + 'tolerates %s on .gitnexus/.gitignore write and logs a warn', + async (code) => { + const cap = _captureLogger(); + const gitignorePath = path.join(tmpRepo.dbPath, '.gitnexus', '.gitignore'); + + fswCtx.writeFileMock.mockRejectedValueOnce(Object.assign(new Error('mock ro'), { code })); + + try { + await expect(ensureGitNexusIgnored(tmpRepo.dbPath)).resolves.not.toThrow(); + expect(fswCtx.writeFileMock).toHaveBeenCalled(); + expect( + cap + .records() + .some( + (r) => + r.level === 40 && + r.code === code && + typeof r.path === 'string' && + samePath(String(r.path), gitignorePath) && + String(r.msg ?? '').includes('.gitnexus/.gitignore'), + ), + ).toBe(true); + } finally { + cap.restore(); + } + }, + ); +}); diff --git a/gitnexus/test/unit/repo-manager.test.ts b/gitnexus/test/unit/repo-manager.test.ts index bbd0fd50e..d3dd65a27 100644 --- a/gitnexus/test/unit/repo-manager.test.ts +++ b/gitnexus/test/unit/repo-manager.test.ts @@ -4,10 +4,11 @@ * Tests: getStoragePath, getStoragePaths, readRegistry, registerRepo, unregisterRepo * Covers hardening fixes #29 (API key file permissions) and #30 (case-insensitive paths on Windows) */ -import { describe, it, expect, beforeEach, afterEach } from 'vitest'; +import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'; import path from 'path'; import os from 'os'; import fs from 'fs/promises'; +import { _captureLogger } from '../../src/core/logger.js'; import { getStoragePath, getStoragePaths, @@ -73,6 +74,7 @@ describe('ensureGitNexusIgnored (#1233)', () => { }); afterEach(async () => { + vi.restoreAllMocks(); await tmpRepo.cleanup(); }); @@ -139,6 +141,74 @@ describe('ensureGitNexusIgnored (#1233)', () => { }); expect(status).toBe(''); }); + + // ─ Read-only workspace tolerance (#1549) ──────────────────────────── + // The documented Docker workflow mounts the host workspace at /workspace:ro + // and runs `gitnexus index /workspace/`. The host has already created + // the .gitnexus dir during a prior `analyze`, so the gitignore file already + // exists with the correct content — there's no real work to do. The tests + // below pin two pieces of behaviour that make that workflow work: + // (a) the function short-circuits when the file is already correct + // (no write attempt, no mtime bump); + // (b) when a write *is* needed but the FS is not writable + // (EROFS / EACCES / EPERM), the function logs and continues instead of + // throwing — so the caller's `registerRepo` work stays committed. + + it('does not re-write .gitnexus/.gitignore when it already has the desired content', async () => { + await ensureGitNexusIgnored(tmpRepo.dbPath); + const gitignorePath = path.join(tmpRepo.dbPath, '.gitnexus', '.gitignore'); + const before = await fs.stat(gitignorePath); + + await new Promise((resolve) => setTimeout(resolve, 25)); + + await ensureGitNexusIgnored(tmpRepo.dbPath); + + const after = await fs.stat(gitignorePath); + expect(after.mtimeMs).toBe(before.mtimeMs); + }); + + it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)( + 'does not throw when .gitnexus/.gitignore is already correct and the storage dir is read-only', + async () => { + await ensureGitNexusIgnored(tmpRepo.dbPath); + const storagePath = path.join(tmpRepo.dbPath, '.gitnexus'); + + await fs.chmod(storagePath, 0o555); + try { + await expect(ensureGitNexusIgnored(tmpRepo.dbPath)).resolves.not.toThrow(); + } finally { + await fs.chmod(storagePath, 0o755); + } + }, + ); + + it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)( + 'warns and continues when the storage dir is read-only and the file does not yet exist', + async () => { + const storagePath = path.join(tmpRepo.dbPath, '.gitnexus'); + await fs.mkdir(storagePath, { recursive: true }); + await fs.chmod(storagePath, 0o555); + + const cap = _captureLogger(); + try { + await expect(ensureGitNexusIgnored(tmpRepo.dbPath)).resolves.not.toThrow(); + expect( + cap + .records() + .some( + (r) => + r.level === 40 && + (r.code === 'EACCES' || r.code === 'EPERM') && + String(r.msg ?? '').includes('.gitnexus/.gitignore') && + String(r.path ?? '').includes('.gitnexus'), + ), + ).toBe(true); + } finally { + cap.restore(); + await fs.chmod(storagePath, 0o755); + } + }, + ); }); // ─── readRegistry ──────────────────────────────────────────────────── From c2193318b51623e6838092fbff88d9b8b4564dd7 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 17:56:32 +0100 Subject: [PATCH 31/33] feat(cpp): Enable C++ ADL for class pointer arguments and exclude function pointers (#1592) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * fix: unwrap cpp adl pointer argument types Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/2e9c8549-e062-410c-9ce3-66ba0a181590 * chore: tighten cpp adl function-pointer guard Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/2e9c8549-e062-410c-9ce3-66ba0a181590 * docs: clarify cpp adl implementation comments Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/2e9c8549-e062-410c-9ce3-66ba0a181590 * fix: avoid aborting cpp adl declaration scan Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/e54f1d4b-9aac-407c-9b5e-b5f3ea0534ea --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Gergő Magyar --- .../src/core/ingestion/languages/cpp/adl.ts | 35 +++++---- .../core/ingestion/languages/cpp/captures.ts | 39 ++++++---- .../cpp-adl-function-pointer-arg/app.cpp | 8 ++ .../cpp-adl-function-pointer-arg/audit.h | 5 ++ .../app.cpp | 9 +++ .../audit.h | 6 ++ .../app.cpp | 8 ++ .../audit.h | 6 ++ .../cpp-adl-pointer-to-pointer/app.cpp | 8 ++ .../cpp-adl-pointer-to-pointer/audit.h | 6 ++ .../test/integration/resolvers/cpp.test.ts | 78 +++++++++++++++++-- 11 files changed, 170 insertions(+), 38 deletions(-) create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/audit.h diff --git a/gitnexus/src/core/ingestion/languages/cpp/adl.ts b/gitnexus/src/core/ingestion/languages/cpp/adl.ts index 112502a74..4c7b034b6 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/adl.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/adl.ts @@ -1,5 +1,5 @@ /** - * C++ argument-dependent lookup (ADL / Koenig lookup) — V1. + * C++ argument-dependent lookup (ADL / Koenig lookup). * * When ordinary unqualified lookup fails for a free-call site, ADL also * considers candidates declared in the **associated namespaces** of the @@ -13,17 +13,18 @@ * `using` anything. With V1 ADL: `audit::record` is discovered via * `audit::Event`'s associated namespace. * - * ## V1 boundary + * ## Current boundary * - * V1 covers ONE associated-entity rule: an argument that's a directly-named + * The current implementation covers ONE associated-entity rule: an argument that's a directly-named * class type (`audit::Event e`) contributes its **direct enclosing - * namespace** to the candidate set. Anything else — pointer/reference + * namespace** to the candidate set. V2 extends that one step to + * pointer-typed class args (`audit::Event* p`, `audit::Event** pp`): + * they contribute the pointee class's enclosing namespace too. Reference * arguments, function-pointer arguments, template specializations, - * base-class associated namespaces — is V2 closure work and is - * deliberately excluded. The `cpp-adl-pointer-arg-boundary` fixture - * locks the exclusion in CI. + * base-class associated namespaces, and the rest of the full closure are + * still deliberately excluded. * - * V1 also short-circuits to ADL only when ordinary lookup is empty + * The current implementation also short-circuits to ADL only when ordinary lookup is empty * (`findCallableBindingInScope` returned undefined). ISO C++ would * normally merge ADL candidates with ordinary-lookup candidates and * run overload resolution over the union; V1 defers that merge to V2. @@ -60,16 +61,16 @@ import { } from '../../scope-resolution/passes/overload-narrowing.js'; /** - * Per-argument shape information collected at capture time. ADL only - * fires for arguments where `simpleClassName !== ''` AND `!isPointer` - * AND `!isReference` — i.e., directly-named class-type values. + * Per-argument shape information collected at capture time. ADL fires for + * arguments where `simpleClassName !== ''` AND `!isReference`, including + * class pointers whose declarator chain resolves to a named class type. */ export interface CppAdlArgInfo { /** Simple class-like type name (last segment of qualified name); empty * for primitives, literals, function pointers, template specs, etc. */ readonly simpleClassName: string; - /** True when the variable's declarator was a `pointer_declarator`. V1 - * excludes pointer-typed args (closure rules deferred to V2). */ + /** True when the variable's declarator contained one or more + * `pointer_declarator` wrappers. */ readonly isPointer: boolean; /** True when the variable's declarator was a `reference_declarator`. */ readonly isReference: boolean; @@ -151,8 +152,8 @@ export function populateCppAssociatedNamespaces(parsed: ParsedFile): void { * * Fires only when: * - the call site is not in `noAdlSites` (parenthesized form), AND - * - at least one argument is a directly-named class type (not pointer, - * not reference, not literal/primitive). + * - at least one argument resolves to a named class type (value or + * pointer, but not reference, function pointer, literal, or primitive). */ export function pickCppAdlCandidates( site: { @@ -170,11 +171,11 @@ export function pickCppAdlCandidates( const args = argInfoBySite.get(key); if (args === undefined || args.length === 0) return undefined; - // Collect associated namespace QNames from every value-class-typed arg. + // Collect associated namespace QNames from every participating class-typed arg. const associatedNamespaces = new Set(); for (const arg of args) { if (arg.simpleClassName === '') continue; - if (arg.isPointer || arg.isReference) continue; + if (arg.isReference) continue; const classDef = findCppClassDefBySimpleName(arg.simpleClassName, scopes); if (classDef === undefined) continue; const nsQName = classToNamespaceQualifiedName.get(classDef.nodeId); diff --git a/gitnexus/src/core/ingestion/languages/cpp/captures.ts b/gitnexus/src/core/ingestion/languages/cpp/captures.ts index 325742bfb..17b6962aa 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/captures.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/captures.ts @@ -720,14 +720,15 @@ function isParenthesizedFunctionCall(callNode: SyntaxNode): boolean { /** * Per-argument ADL classification: walk each argument of a free call and - * decide whether it's a directly-named class type (V1 ADL fires) or - * something V1 excludes (pointer, reference, primitive, literal, function - * pointer, template specialization). + * decide whether it resolves to a directly-named class or class-pointer + * type (ADL fires) or to an excluded shape such as a reference, function + * pointer, primitive, literal, or template specialization. * - * V1 only fires for value class-typed args: `void f(N::S); N::S s; f(s);`. - * Pointer args (`N::S* p; f(p);`) intentionally return `simpleClassName=''` - * to lock the V1 boundary — the `cpp-adl-pointer-arg-boundary` fixture - * regression-tests this. + * Class-typed values and class pointers (`N::S`, `N::S*`, `N::S**`) all + * preserve the pointee class name for associated-namespace lookup. + * Function pointers remain excluded even when their return type names a + * class, because the associated entity is the pointed-to function type, + * not the return type. */ function inferCppCallAdlArgs(callNode: SyntaxNode): CppAdlArgInfo[] { const argList = callNode.childForFieldName('arguments'); @@ -792,15 +793,23 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { // Unwrap declarator chain to find pointer/reference markers and the // variable name. `init_declarator > pointer_declarator > identifier` - // means pointer-typed; `init_declarator > reference_declarator > ...` - // means reference-typed; bare `init_declarator > identifier` is value. + // means pointer-typed; repeated pointer wrappers still count as pointer + // typed; `init_declarator > reference_declarator > ...` means + // reference-typed; bare `init_declarator > identifier` is value. + // Function-pointer wrappers (`pointer_declarator > function_declarator`) + // must not contribute ADL associated namespaces. let isPointer = false; let isReference = false; + let isFunctionPointer = false; let inner: SyntaxNode = declarator; let nameText: string | null = null; let safety = 16; // bound walk depth defensively while (safety-- > 0) { if (inner.type === 'pointer_declarator') { + if (findFirstDescendantOfType(inner, 'function_declarator') !== null) { + isFunctionPointer = true; + break; + } isPointer = true; const next = inner.childForFieldName('declarator'); if (next === null) break; @@ -828,11 +837,15 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { inner = next; continue; } + if (inner.type === 'function_declarator') { + isFunctionPointer = true; + break; + } // Reached the leaf — usually `identifier`. Take its text. nameText = inner.text; break; } - if (nameText !== varName) continue; + if (isFunctionPointer || nameText !== varName) continue; const simpleClassName = extractAdlSimpleTypeName(typeNode); return { simpleClassName, isPointer, isReference }; @@ -841,9 +854,9 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { } /** Extract the simple class-like type name from a `type:` field node. - * Returns '' for primitives, template specializations, function pointers, - * and any other shape V1 ADL doesn't support — those args are excluded - * from associated-namespace closure. */ + * Returns '' for primitives, template specializations, and any other + * unsupported type-only shape. Function pointers are filtered at the + * declarator level in `lookupAdlIdentifierType`. */ function extractAdlSimpleTypeName(typeNode: SyntaxNode): string { if (typeNode.type === 'primitive_type') return ''; if (typeNode.type === 'sized_type_specifier') return ''; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/app.cpp new file mode 100644 index 000000000..b9f99d201 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + void (*g)(); + record(g); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/audit.h new file mode 100644 index 000000000..a0283cabc --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-arg/audit.h @@ -0,0 +1,5 @@ +#pragma once + +namespace audit { + void record(void (*g)()); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/app.cpp new file mode 100644 index 000000000..9e6cfd188 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/app.cpp @@ -0,0 +1,9 @@ +#include "audit.h" + +namespace app { + void run() { + void (*fp)(); + audit::Event e; + record(e); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/audit.h new file mode 100644 index 000000000..2c9803a3d --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-before-class-arg/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/app.cpp new file mode 100644 index 000000000..0cf4ee3bb --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event (*factory)(); + record(factory); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/audit.h new file mode 100644 index 000000000..a2438fe5e --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-function-pointer-class-return-arg/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event (*factory)()); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/app.cpp new file mode 100644 index 000000000..33508836e --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/app.cpp @@ -0,0 +1,8 @@ +#include "audit.h" + +namespace app { + void run() { + audit::Event** pp; + record(pp); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/audit.h new file mode 100644 index 000000000..2f719362c --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-pointer-to-pointer/audit.h @@ -0,0 +1,6 @@ +#pragma once + +namespace audit { + struct Event {}; + void record(Event** e); +} diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index 25a7f9de7..eafa76cf9 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -2057,7 +2057,7 @@ describe('C++ ADL — parenthesized name suppresses ADL', () => { }); }); -describe('C++ ADL — pointer-arg V1 boundary', () => { +describe('C++ ADL — pointer arg unwrapping', () => { let result: PipelineResult; beforeAll(async () => { @@ -2067,19 +2067,81 @@ describe('C++ ADL — pointer-arg V1 boundary', () => { ); }, 60000); - it('record(p) where p is audit::Event* emits zero CALLS — V1 ADL excludes pointer args', () => { + it('record(p) where p is audit::Event* resolves to audit::record via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); +}); + +describe('C++ ADL — function pointer args do not participate', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-adl-function-pointer-arg'), + () => {}, + ); + }, 60000); + + it('record(g) where g is void (*)() emits zero CALLS edges', () => { const calls = getRelationships(result, 'CALLS'); const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); - // Exact .toBe(0): V1 ADL covers only directly-named class-type values - // (per plan 2026-05-13-001 R4). Pointer-typed args fall under - // associated-entity closure rules deferred to V2. This fixture locks - // the boundary in CI so the implementer cannot accidentally extend - // V1 to include pointer types. Real ISO C++ would resolve via V2 - // closure; matching that requires the V2 follow-up plan. expect(recordCalls.length).toBe(0); }); }); +describe('C++ ADL — preceding function-pointer declarations do not block class args', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-adl-function-pointer-before-class-arg'), + () => {}, + ); + }, 60000); + + it('record(e) still resolves via ADL when an earlier declaration is void (*)()', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); +}); + +describe('C++ ADL — class-returning function pointer args do not participate', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-adl-function-pointer-class-return-arg'), + () => {}, + ); + }, 60000); + + it('record(factory) where factory is audit::Event (*)() emits zero CALLS edges', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + expect(recordCalls.length).toBe(0); + }); +}); + +describe('C++ ADL — pointer-to-pointer args participate', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-adl-pointer-to-pointer'), () => {}); + }, 60000); + + it('record(pp) where pp is audit::Event** resolves to audit::record via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'run' && c.target === 'record'); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('audit.h'); + }); +}); + describe('C++ ADL — int/long-collision overloads suppress via OVERLOAD_AMBIGUOUS', () => { let result: PipelineResult; From b00ba2ab4755acb3eb20ee92232bd4091ee36352 Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 18:18:36 +0100 Subject: [PATCH 32/33] feat(cpp): resolve template-body `this->` + `using ns::name` calls in scope resolver (#1590) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * Initial plan * fix(cpp): resolve this-> and using-name calls in template bodies Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/d9d91945-f19c-4fd2-9b52-b0ebc9aa34b6 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * fix(cpp): treat duplicate using-name hits as ambiguous Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/d9d91945-f19c-4fd2-9b52-b0ebc9aa34b6 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * chore(autofix): apply prettier + eslint fixes via /autofix command * fix(cpp): gate this-receiver path and harden overload semantics Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/030a1842-c698-460d-ae2a-95037e6def73 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test(cpp): add positive this-> overload case and document field shadowing Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/030a1842-c698-460d-ae2a-95037e6def73 Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> * test(cpp): skip new template-this assertions in legacy parity lane Agent-Logs-Url: https://github.com/abhigyanpatwari/GitNexus/sessions/27002f6e-6331-41e3-8175-9d9e4691927c Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: magyargergo <11230420+magyargergo@users.noreply.github.com> Co-authored-by: Gergő Magyar Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com> --- .../ingestion/languages/cpp/scope-resolver.ts | 33 ++++++ .../contract/scope-resolver.ts | 12 +++ .../passes/receiver-bound-calls.ts | 83 ++++++++++++++ .../derived.h | 3 + .../helpers.h | 1 + .../cpp-two-phase-paired/base.h | 6 ++ .../cpp-two-phase-paired/derived.h | 14 +++ .../base.h | 6 ++ .../derived.h | 16 +++ .../cpp-two-phase-this-qualified/base.h | 1 + .../cpp-two-phase-this-qualified/derived.h | 3 + .../test/integration/resolvers/cpp.test.ts | 102 ++++++++++++++++-- .../test/integration/resolvers/helpers.ts | 9 ++ 13 files changed, 281 insertions(+), 8 deletions(-) create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/derived.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/base.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/derived.h diff --git a/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts index 02aaff3bf..431717d27 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/scope-resolver.ts @@ -36,6 +36,10 @@ import { resolveCppQualifiedNamespaceMember, } from './inline-namespaces.js'; import { populateCppRangeBindings } from './range-bindings.js'; +import { + isOverloadAmbiguousAfterNormalization, + narrowOverloadCandidates, +} from '../../scope-resolution/passes/overload-narrowing.js'; /** * C++ `ScopeResolver` registered in `SCOPE_RESOLVERS` and consumed by @@ -178,6 +182,8 @@ export const cppScopeResolver: ScopeResolver = { // for cross-file propagation and compound-receiver chain resolution. // cppBindingScopeFor hoists @type-binding.return to Module scope. hoistTypeBindingsToModule: true, + // Enable receiver-bound explicit-`this` fallback only for C++. + resolveThisViaEnclosingClass: true, // The `isFileLocalDef` hook on the global free-call fallback names // file-local linkage historically, but semantically gates "logically // invisible cross-file" defs. C++ extends this to also reject class- @@ -219,6 +225,33 @@ export const cppScopeResolver: ScopeResolver = { // V1 limitation: only direct enclosing-namespace closure for value // class-typed args; pointer/reference/template-spec args excluded. resolveAdlCandidates: (site, callerParsed, scopes, parsedFiles) => { + // `using ns::name;` introduces `name` into ordinary unqualified lookup. + // For template-class method bodies, lexical scope walks can miss this + // named-using visibility; recover by resolving the imported namespace + // member directly when the local call name matches a named using import. + const usingNamedHits: SymbolDefinition[] = []; + const seenUsing = new Set(); + for (const imp of callerParsed.parsedImports) { + if (imp.kind !== 'named') continue; + if (imp.localName !== site.name) continue; + const member = resolveCppQualifiedNamespaceMember( + imp.targetRaw, + imp.importedName, + parsedFiles, + scopes, + ); + if (member === undefined) continue; + if (seenUsing.has(member.nodeId)) continue; + seenUsing.add(member.nodeId); + usingNamedHits.push(member); + } + if (usingNamedHits.length > 0) { + const narrowed = narrowOverloadCandidates(usingNamedHits, site.arity, site.argumentTypes); + if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) return 'ambiguous'; + if (narrowed.length === 1) return narrowed[0]; + if (narrowed.length > 1) return 'ambiguous'; + } + const result = pickCppAdlCandidates(site, callerParsed, scopes, parsedFiles); if (result === ADL_AMBIGUOUS) return 'ambiguous'; return result; diff --git a/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts b/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts index d29b6efa8..36856e6a8 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/contract/scope-resolver.ts @@ -627,6 +627,18 @@ export interface ScopeResolver { parsedFiles: readonly ParsedFile[], ) => SymbolDefinition | undefined; + /** + * Enable the receiver-bound Case 0.5 fallback for explicit `this` + * receivers (`this->m()` / `this.m()`) that resolves against the + * enclosing class + MRO even when no explicit `this` typeBinding is + * present in scope. + * + * Keep disabled for languages where the existing type-binding path + * (Case 4) already handles `this` correctly and overload ambiguity + * suppression must remain unchanged. + */ + readonly resolveThisViaEnclosingClass?: boolean; + /** * Optional post-finalize hook to inject cross-file bindings that * aren't modeled via explicit imports. Runs after diff --git a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts index 80ff3a200..5aff78261 100644 --- a/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts +++ b/gitnexus/src/core/ingestion/scope-resolution/passes/receiver-bound-calls.ts @@ -72,6 +72,7 @@ type ReceiverBoundProviderSubset = Pick< | 'unwrapCollectionAccessor' | 'hoistTypeBindingsToModule' | 'resolveQualifiedReceiverMember' + | 'resolveThisViaEnclosingClass' >; function normalizeTemplateArgToken(value: string): string { @@ -321,6 +322,88 @@ export function emitReceiverBoundCalls( } } + // ── Case 0.5: implicit `this` receiver ─────────────────────── + // C++ `this->member()` (and same-shape receivers in other OO + // languages) should resolve against the enclosing class + MRO + // even when there is no explicit `this` typeBinding in scope. + if (provider.resolveThisViaEnclosingClass === true && receiverName === 'this') { + const enclosingClass = findEnclosingClassDef(site.inScope, scopes); + if (enclosingClass !== undefined) { + const chain = [ + enclosingClass.nodeId, + ...scopes.methodDispatch.mroFor(enclosingClass.nodeId), + ]; + let memberDef: SymbolDefinition | undefined; + let ambiguous = false; + let hiddenByName = false; + for (const ownerId of chain) { + const methodOverloads = model.methods.lookupAllByOwner(ownerId, memberName); + if (methodOverloads.length > 0) { + const narrowed = narrowOverloadCandidates( + methodOverloads, + site.arity, + site.argumentTypes, + ); + if (isOverloadAmbiguousAfterNormalization(narrowed, site.arity)) { + ambiguous = true; + break; + } + if (narrowed.length === 0) { + // C++ name hiding: if the derived class declares `f`, base-class + // overloads named `f` are hidden for member lookup + // ([basic.lookup.classref]). A non-viable derived overload set + // therefore terminates lookup instead of falling through to base. + hiddenByName = true; + break; + } + memberDef = narrowed[0] ?? methodOverloads[0]; + break; + } + + // Field/property lookup intentionally runs only after the method + // lookup above: in C++ member-name lookup, functions with this + // name hide same-named base members; we therefore prefer method + // candidates first and only target a field when no methods with + // this name exist on the current owner. + memberDef = model.fields.lookupFieldByOwner(ownerId, memberName); + if (memberDef !== undefined) { + break; + } + } + if (ambiguous) { + handledSites.add(siteKey); + continue; + } + if (hiddenByName) { + handledSites.add(siteKey); + continue; + } + if (memberDef !== undefined) { + const reason = + site.kind === 'write' || site.kind === 'read' + ? site.kind + : memberDef.filePath !== parsed.filePath + ? 'import-resolved' + : 'global'; + const confidence = site.kind === 'write' || site.kind === 'read' ? 1.0 : 0.85; + const ok = tryEmitEdge( + graph, + scopes, + nodeLookup, + site, + memberDef, + reason, + seen, + confidence, + collapse, + ); + if (ok) emitted++; + handledSites.add(siteKey); + continue; + } + } + } + // ── Case 1: namespace receiver ─────────────────────────────── const targetFiles = namespaceTargets.get(receiverName); if (targetFiles !== undefined) { diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h index ef57810fc..e3ea61977 100644 --- a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/derived.h @@ -3,9 +3,12 @@ #include "base.h" #include "helpers.h" +using utils::ns_helper_2; + template struct D : Base { void g() { utils::ns_helper(); + ns_helper_2(); } }; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h index 5e291aba6..4bd7a9833 100644 --- a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-namespace-free-call-inside-template/helpers.h @@ -2,4 +2,5 @@ namespace utils { void ns_helper(); + void ns_helper_2(); } diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/base.h new file mode 100644 index 000000000..84bc1a954 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/base.h @@ -0,0 +1,6 @@ +#pragma once + +template +struct Base { + void f(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/derived.h new file mode 100644 index 000000000..c7cc1a53b --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-paired/derived.h @@ -0,0 +1,14 @@ +#pragma once + +#include "base.h" + +template +struct Derived : Base { + void g_unqualified() { + f(); + } + + void g_this() { + this->f(); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/base.h new file mode 100644 index 000000000..84bc1a954 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/base.h @@ -0,0 +1,6 @@ +#pragma once + +template +struct Base { + void f(); +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/derived.h new file mode 100644 index 000000000..ad867e820 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-name-hiding-arity/derived.h @@ -0,0 +1,16 @@ +#pragma once + +#include "base.h" + +template +struct Derived : Base { + void f(int); + + void g() { + this->f(); + } + + void g_ok() { + this->f(42); + } +}; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h index 1c7084ee6..286f877a1 100644 --- a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/base.h @@ -3,5 +3,6 @@ template struct Base { void f(); + void base_method(); int i; }; diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h index 5c13c1737..9b154a429 100644 --- a/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h +++ b/gitnexus/test/fixtures/lang-resolution/cpp-two-phase-this-qualified/derived.h @@ -7,6 +7,9 @@ struct Derived : Base { void g() { this->f(); } + void k() { + this->base_method(); + } int h() { return this->i; } diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index eafa76cf9..cd95cfae7 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -1972,14 +1972,100 @@ describe('C++ two-phase template lookup — dependent base suppression', () => { }); }); -// NOTE: positive guards (this->f() resolves, non-dependent-base unqualified -// f() resolves, namespace-qualified utils::ns_helper() resolves) inside -// template bodies are documented gaps in C++ template-context resolution -// independent of U3's dependent-base suppression. The U3 core asserts only -// the negative behavior (dependent-base members are NOT bound by unqualified -// calls); the positive cases would require additional `this` type-binding -// and template-body member-lookup work tracked separately. See plan -// 2026-05-13-001 follow-ups. +describe('C++ two-phase template lookup — positive this-qualified calls', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-two-phase-this-qualified'), + () => {}, + ); + }, 60000); + + it('Derived::g() -> this->f() resolves to f (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const thisCalls = calls.filter((c) => c.source === 'g' && c.target === 'f'); + expect(thisCalls.length).toBe(1); + expect(thisCalls[0].targetFilePath).toContain('base.h'); + }); + + it('Derived::k() -> this->base_method() resolves via EXTENDS chain (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const inheritedCalls = calls.filter((c) => c.source === 'k' && c.target === 'base_method'); + expect(inheritedCalls.length).toBe(1); + expect(inheritedCalls[0].targetFilePath).toContain('base.h'); + }); +}); + +describe('C++ two-phase template lookup — paired unqualified + this-qualified in one fixture', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-two-phase-paired'), () => {}); + }, 60000); + + it('Derived::g_unqualified() -> f() does NOT bind to Base::f', () => { + const calls = getRelationships(result, 'CALLS'); + const leaks = calls.filter((c) => c.source === 'g_unqualified' && c.target === 'f'); + expect(leaks.length).toBe(0); + }); + + it('Derived::g_this() -> this->f() resolves to Base::f (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const resolved = calls.filter((c) => c.source === 'g_this' && c.target === 'f'); + expect(resolved.length).toBe(1); + expect(resolved[0].targetFilePath).toContain('base.h'); + }); +}); + +describe('C++ two-phase template lookup — namespace calls inside template body', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-two-phase-namespace-free-call-inside-template'), + () => {}, + ); + }, 60000); + + it('D::g() -> utils::ns_helper() resolves (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const qualifiedCalls = calls.filter((c) => c.source === 'g' && c.target === 'ns_helper'); + expect(qualifiedCalls.length).toBe(1); + expect(qualifiedCalls[0].targetFilePath).toContain('helpers.h'); + }); + + it('D::g() -> ns_helper_2() resolves after using-declaration (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const usingCalls = calls.filter((c) => c.source === 'g' && c.target === 'ns_helper_2'); + expect(usingCalls.length).toBe(1); + expect(usingCalls[0].targetFilePath).toContain('helpers.h'); + }); +}); + +describe('C++ two-phase template lookup — this-> name-hiding arity mismatch', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-two-phase-this-name-hiding-arity'), + () => {}, + ); + }, 60000); + + it('Derived::g() -> this->f() emits zero CALLS edges when only hidden derived overload is arity-incompatible', () => { + const calls = getRelationships(result, 'CALLS'); + const fCalls = calls.filter((c) => c.source === 'g' && c.target === 'f'); + expect(fCalls.length).toBe(0); + }); + + it('Derived::g_ok() -> this->f(42) resolves to derived overload (1 edge)', () => { + const calls = getRelationships(result, 'CALLS'); + const fCalls = calls.filter((c) => c.source === 'g_ok' && c.target === 'f'); + expect(fCalls.length).toBe(1); + expect(fCalls[0].targetFilePath).toContain('derived.h'); + }); +}); // --------------------------------------------------------------------------- // U3 cross-file namespace variant: Base lives in a different file AND diff --git a/gitnexus/test/integration/resolvers/helpers.ts b/gitnexus/test/integration/resolvers/helpers.ts index 5149e3e69..396e7905b 100644 --- a/gitnexus/test/integration/resolvers/helpers.ts +++ b/gitnexus/test/integration/resolvers/helpers.ts @@ -168,6 +168,15 @@ const LEGACY_RESOLVER_PARITY_EXPECTED_FAILURES: Readonly and List', 'callSave() in each specialization resolves to its own save()', 'save specialization bodies route to their own sibling method', + // PR #1590 follow-up: explicit `this->` resolution in template class + // bodies and paired two-phase assertions are scope-resolver-only. + // Legacy DAG lacks this receiver-bound template semantics and + // dependent-base suppression parity for these shapes. + 'Derived::g() -> this->f() resolves to f (1 edge)', + 'Derived::k() -> this->base_method() resolves via EXTENDS chain (1 edge)', + 'Derived::g_unqualified() -> f() does NOT bind to Base::f', + 'Derived::g_this() -> this->f() resolves to Base::f (1 edge)', + 'Derived::g() -> this->f() emits zero CALLS edges when only hidden derived overload is arity-incompatible', ]), }; From cdac8a691ae6c58fee9a64ae5e9442d776e5fa7c Mon Sep 17 00:00:00 2001 From: Copilot <198982749+Copilot@users.noreply.github.com> Date: Thu, 14 May 2026 20:25:12 +0100 Subject: [PATCH 33/33] feat: C++ ADL V2: include class-typed reference args (incl. rvalue refs) in associated-namespace lookup (#1595) --- .../src/core/ingestion/languages/cpp/adl.ts | 24 ++++----- .../core/ingestion/languages/cpp/captures.ts | 15 +++--- .../cpp-adl-reference-arg-boundary/app.cpp | 21 ++++++++ .../cpp-adl-reference-arg-boundary/audit.h | 5 ++ .../cpp-adl-reference-arg-boundary/record.h | 8 +++ .../cpp-adl-rvalue-ref/app.cpp | 9 ++++ .../cpp-adl-rvalue-ref/audit.h | 5 ++ .../cpp-adl-rvalue-ref/record-rvalue.h | 7 +++ .../test/integration/resolvers/cpp.test.ts | 50 ++++++++++++++++++- 9 files changed, 119 insertions(+), 25 deletions(-) create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/record.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/app.cpp create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/audit.h create mode 100644 gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/record-rvalue.h diff --git a/gitnexus/src/core/ingestion/languages/cpp/adl.ts b/gitnexus/src/core/ingestion/languages/cpp/adl.ts index 4c7b034b6..8d6c1563d 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/adl.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/adl.ts @@ -18,11 +18,11 @@ * The current implementation covers ONE associated-entity rule: an argument that's a directly-named * class type (`audit::Event e`) contributes its **direct enclosing * namespace** to the candidate set. V2 extends that one step to - * pointer-typed class args (`audit::Event* p`, `audit::Event** pp`): - * they contribute the pointee class's enclosing namespace too. Reference - * arguments, function-pointer arguments, template specializations, - * base-class associated namespaces, and the rest of the full closure are - * still deliberately excluded. + * pointer-typed and reference-typed class args (`audit::Event* p`, + * `audit::Event& r`, `audit::Event&& rr`): they contribute the pointee / + * referred class's enclosing namespace too. Function-pointer arguments, + * template specializations, base-class associated namespaces, and the + * rest of the full closure are still deliberately excluded. * * The current implementation also short-circuits to ADL only when ordinary lookup is empty * (`findCallableBindingInScope` returned undefined). ISO C++ would @@ -62,18 +62,13 @@ import { /** * Per-argument shape information collected at capture time. ADL fires for - * arguments where `simpleClassName !== ''` AND `!isReference`, including - * class pointers whose declarator chain resolves to a named class type. + * arguments where `simpleClassName !== ''`, including class pointers and + * references whose declarator chain resolves to a named class type. */ export interface CppAdlArgInfo { /** Simple class-like type name (last segment of qualified name); empty * for primitives, literals, function pointers, template specs, etc. */ readonly simpleClassName: string; - /** True when the variable's declarator contained one or more - * `pointer_declarator` wrappers. */ - readonly isPointer: boolean; - /** True when the variable's declarator was a `reference_declarator`. */ - readonly isReference: boolean; } const argInfoBySite = new Map(); @@ -152,8 +147,8 @@ export function populateCppAssociatedNamespaces(parsed: ParsedFile): void { * * Fires only when: * - the call site is not in `noAdlSites` (parenthesized form), AND - * - at least one argument resolves to a named class type (value or - * pointer, but not reference, function pointer, literal, or primitive). + * - at least one argument resolves to a named class type (value, + * pointer, or reference; but not function pointer, literal, or primitive). */ export function pickCppAdlCandidates( site: { @@ -175,7 +170,6 @@ export function pickCppAdlCandidates( const associatedNamespaces = new Set(); for (const arg of args) { if (arg.simpleClassName === '') continue; - if (arg.isReference) continue; const classDef = findCppClassDefBySimpleName(arg.simpleClassName, scopes); if (classDef === undefined) continue; const nsQName = classToNamespaceQualifiedName.get(classDef.nodeId); diff --git a/gitnexus/src/core/ingestion/languages/cpp/captures.ts b/gitnexus/src/core/ingestion/languages/cpp/captures.ts index 17b6962aa..75ef30804 100644 --- a/gitnexus/src/core/ingestion/languages/cpp/captures.ts +++ b/gitnexus/src/core/ingestion/languages/cpp/captures.ts @@ -743,7 +743,7 @@ function inferCppCallAdlArgs(callNode: SyntaxNode): CppAdlArgInfo[] { return out; } -const EMPTY_ADL_ARG: CppAdlArgInfo = { simpleClassName: '', isPointer: false, isReference: false }; +const EMPTY_ADL_ARG: CppAdlArgInfo = { simpleClassName: '' }; function classifyAdlArg(argNode: SyntaxNode): CppAdlArgInfo { // Literals and primitive-shaped expressions never have associated namespaces. @@ -794,12 +794,11 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { // Unwrap declarator chain to find pointer/reference markers and the // variable name. `init_declarator > pointer_declarator > identifier` // means pointer-typed; repeated pointer wrappers still count as pointer - // typed; `init_declarator > reference_declarator > ...` means - // reference-typed; bare `init_declarator > identifier` is value. + // typed; `init_declarator > reference_declarator > ...` (or + // `rvalue_reference_declarator`) means reference-typed; bare + // `init_declarator > identifier` is value. // Function-pointer wrappers (`pointer_declarator > function_declarator`) // must not contribute ADL associated namespaces. - let isPointer = false; - let isReference = false; let isFunctionPointer = false; let inner: SyntaxNode = declarator; let nameText: string | null = null; @@ -810,14 +809,12 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { isFunctionPointer = true; break; } - isPointer = true; const next = inner.childForFieldName('declarator'); if (next === null) break; inner = next; continue; } - if (inner.type === 'reference_declarator') { - isReference = true; + if (inner.type === 'reference_declarator' || inner.type === 'rvalue_reference_declarator') { // reference_declarator has a single child (the inner declarator). let next: SyntaxNode | null = null; for (let j = 0; j < inner.namedChildCount; j++) { @@ -848,7 +845,7 @@ function lookupAdlIdentifierType(identNode: SyntaxNode): CppAdlArgInfo { if (isFunctionPointer || nameText !== varName) continue; const simpleClassName = extractAdlSimpleTypeName(typeNode); - return { simpleClassName, isPointer, isReference }; + return { simpleClassName }; } return EMPTY_ADL_ARG; } diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/app.cpp new file mode 100644 index 000000000..e32733d9b --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/app.cpp @@ -0,0 +1,21 @@ +#include "audit.h" + +namespace app { + void runRef() { + audit::Event e; + audit::Event& s = e; + record(s); + } + + void runConstRef() { + audit::Event e; + const audit::Event& constEventRef = e; + recordConst(constEventRef); + } + + void runPrimitiveRef() { + int n = 0; + int& r = n; + note(r); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/audit.h new file mode 100644 index 000000000..4b4600381 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/audit.h @@ -0,0 +1,5 @@ +#pragma once + +namespace audit { + struct Event {}; +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/record.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/record.h new file mode 100644 index 000000000..590ac5a87 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-reference-arg-boundary/record.h @@ -0,0 +1,8 @@ +#pragma once + +#include "audit.h" + +namespace audit { + void record(Event& e); + void recordConst(const Event& e); +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/app.cpp b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/app.cpp new file mode 100644 index 000000000..8a5f57ba9 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/app.cpp @@ -0,0 +1,9 @@ +#include "audit.h" + +namespace app { + void runRvalueRef() { + audit::Event e; + audit::Event&& rr = static_cast(e); + record(rr); + } +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/audit.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/audit.h new file mode 100644 index 000000000..4b4600381 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/audit.h @@ -0,0 +1,5 @@ +#pragma once + +namespace audit { + struct Event {}; +} diff --git a/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/record-rvalue.h b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/record-rvalue.h new file mode 100644 index 000000000..ae3cf7462 --- /dev/null +++ b/gitnexus/test/fixtures/lang-resolution/cpp-adl-rvalue-ref/record-rvalue.h @@ -0,0 +1,7 @@ +#pragma once + +#include "audit.h" + +namespace audit { + void record(Event&& e); +} diff --git a/gitnexus/test/integration/resolvers/cpp.test.ts b/gitnexus/test/integration/resolvers/cpp.test.ts index cd95cfae7..7bc040182 100644 --- a/gitnexus/test/integration/resolvers/cpp.test.ts +++ b/gitnexus/test/integration/resolvers/cpp.test.ts @@ -2103,7 +2103,7 @@ describe('C++ two-phase template lookup — cross-file namespace variant', () => // Free-function calls with class-typed arguments must consider candidates // declared in the argument's enclosing namespace (associated namespace). // V1 boundary: only direct enclosing-namespace closure for value class- -// typed args; pointer / reference / template-spec args excluded. +// typed args; pointer and reference args included, template-spec args excluded. // --------------------------------------------------------------------------- describe('C++ ADL — basic associated-namespace closure', () => { @@ -2161,6 +2161,54 @@ describe('C++ ADL — pointer arg unwrapping', () => { }); }); +describe('C++ ADL — reference arg unwrapping', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo( + path.join(FIXTURES, 'cpp-adl-reference-arg-boundary'), + () => {}, + ); + }, 60000); + + it('record(s) where s is audit::Event& resolves to audit::record via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'runRef' && c.target === 'record'); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('record.h'); + }); + + it('recordConst(cs) where cs is const audit::Event& resolves via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter( + (c) => c.source === 'runConstRef' && c.target === 'recordConst', + ); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('record.h'); + }); + + it('note(r) where r is int& emits zero CALLS edges (primitive ref)', () => { + const calls = getRelationships(result, 'CALLS'); + const noteCalls = calls.filter((c) => c.source === 'runPrimitiveRef' && c.target === 'note'); + expect(noteCalls.length).toBe(0); + }); +}); + +describe('C++ ADL — rvalue reference args participate', () => { + let result: PipelineResult; + + beforeAll(async () => { + result = await runPipelineFromRepo(path.join(FIXTURES, 'cpp-adl-rvalue-ref'), () => {}); + }, 60000); + + it('record(rr) where rr is audit::Event&& resolves to audit::record via ADL', () => { + const calls = getRelationships(result, 'CALLS'); + const recordCalls = calls.filter((c) => c.source === 'runRvalueRef' && c.target === 'record'); + expect(recordCalls.length).toBe(1); + expect(recordCalls[0].targetFilePath).toContain('record-rvalue.h'); + }); +}); + describe('C++ ADL — function pointer args do not participate', () => { let result: PipelineResult;