feat(python): index module-level singleton instances as CodeElement nodes

[TheGrouchy]

Problem

Python projects commonly define module-level singleton instances:

service = ServiceClass()

These are then imported by name in other modules:

from myapp.services import service

Because GitNexus only indexes class_definition and function_definition as named symbols, the instance variable service has no node in the graph. symbolTable.lookupExact() finds nothing, so no IMPORTS edge is created — even after #137. impact("service") returns zero upstream callers despite multiple files importing it.

This is the dominant module export pattern in FastAPI, Flask, Django, and most Python service-oriented codebases.

Solution

Add a tree-sitter query that captures module-scope call assignments as definition.instance, mapped to a CodeElement node:

; Module-level singleton instances: service = ServiceClass()
(module
  (expression_statement
    (assignment
      left: (identifier) @name
      right: (call))) @definition.instance)

The module anchor ensures only top-level assignments are captured — not locals inside functions or classes. right: (call) constrains matches to constructor/factory patterns, excluding plain constants (PORT = 8080, NAME = "app").

Changes

src/core/ingestion/tree-sitter-queries.ts

• Added definition.instance pattern to PYTHON_QUERIES

src/core/ingestion/parsing-processor.ts and src/core/ingestion/workers/parse-worker.ts

• Added 'definition.instance' to DEFINITION_CAPTURE_KEYS (enables correct line range via getDefinitionNodeFromCaptures)
• Added definition.instance → 'CodeElement' to label resolution in both sequential and worker paths

Design decisions

• Additive only — no existing nodes, edges, or schema changes
• CodeElement label — reuses existing type; no migration required
• right: (call) constraint — filters to instantiation patterns only; plain literals and dict/list assignments are excluded
• module anchor — prevents false positives from local variables inside functions or class bodies

Known limitation

Annotated assignments (service: ServiceType = ServiceClass()) use the annotated_assignment AST node and are not captured. Can be addressed as a follow-up.

Relationship to #137

These two PRs compose: #137 creates File → Symbol IMPORTS edges for named imports; this PR ensures the target symbol node exists for Python singleton patterns. Together they fully resolve Python named import tracing.

[vercel]

@TheGrouchy is attempting to deploy a commit to the NexusCore Team on Vercel.

A member of the Team first needs to authorize it.

[github-actions]

CI Report

❌ Some checks failed

Pipeline Status

Stage	Status	Details
✅ Typecheck	success	tsc --noEmit
❌ Unit Tests	failure	3 platforms
✅ Integration	success	3 OS x 4 groups = 12 jobs

Test Results

✅ 989 passed
· 280 suites · 989 total
· ⏱️ 18s
· 📊 839 unit + 150 integration

Code Coverage

Combined (Unit + Integration)

Metric	Coverage	Covered	Threshold	Status
Statements	37.18%	2299/6183	26%	🟢 ███████░░░░░░░░░░░░░
Branches	29.78%	1239/4160	23%	🟢 █████░░░░░░░░░░░░░░░
Functions	40.85%	277/678	28%	🟢 ████████░░░░░░░░░░░░
Lines	38.47%	2163/5622	27%	🟢 ███████░░░░░░░░░░░░░

Coverage breakdown by test suite

Unit Tests

Metric	Coverage	Covered	Threshold	Status
Statements	26.02%	1609/6183	26%	🟢 █████░░░░░░░░░░░░░░░
Branches	23.17%	964/4160	23%	🟢 ████░░░░░░░░░░░░░░░░
Functions	28.17%	191/678	28%	🟢 █████░░░░░░░░░░░░░░░
Lines	26.89%	1512/5622	27%	🔴 █████░░░░░░░░░░░░░░░

Integration Tests

Metric	Coverage	Covered	Threshold	Status
Statements	19.79%	1224/6183	26%	🔴 ███░░░░░░░░░░░░░░░░░
Branches	14.54%	605/4160	23%	🔴 ██░░░░░░░░░░░░░░░░░░
Functions	22.41%	152/678	28%	🔴 ████░░░░░░░░░░░░░░░░
Lines	20.56%	1156/5622	27%	🔴 ████░░░░░░░░░░░░░░░░

Coverage thresholds are auto-ratcheted — they only go up

Vitest thresholds.autoUpdate bumps the floor whenever local coverage exceeds it.
CI enforces the current thresholds; developers commit the ratcheted values.

---

_{📋 View full run · Generated by CI}

[magyargergo]

@claude

[claude]

Claude finished @magyargergo's task in 2m 39s —— View job

---

Code Review

• Read changed files
• Investigate CI failures
• Provide comprehensive code review

---

Summary

This PR adds Python module-level singleton instance indexing as CodeElement nodes, enabling impact("service") to return upstream callers when other modules do from myapp.services import service. The approach is sound and the changes compose correctly with #137. However, there are issues to address before merging.

---

CI Failure: Line Coverage Regression

The unit test pipeline fails on all 3 platforms due to a line coverage threshold breach:

Metric	Coverage	Threshold	Status
Lines	26.89%	27%	❌

The PR adds ~139 lines across 5 files but includes zero unit tests. The coverage ratchet previously locked the floor at 27%, and the new untested code diluted line coverage below that floor. Tests must be added for this to pass.

---

Bug: Bare import X Statements Produce Spurious Symbol Names

parse-worker.ts:288-304 and import-processor.ts:796-826

The extractImportedSymbolNames / extractSymbolNames functions have a subtle issue for Python import_statement nodes (bare import X.Y). The guard skips module_name typed children, but in a bare import_statement the module path appears as dotted_name, not module_name — so it falls through to:

if (child.type === 'dotted_name' || child.type === 'identifier') {
  names.push(child.text);  // ← pushes "myapp.services" as a symbol name
}

For import myapp.services, this would push "myapp.services" as a symbol name. Since symbolTable.lookupExact() won't find anything for it, no spurious edge is created — but the logic is wrong in principle. The function should early-return [] for import_statement nodes (as opposed to import_from_statement), since bare module imports don't bring named symbols into scope.

Fix this →

---

Duplication: addSymbolImportEdges Defined Twice

The helper is copy-pasted verbatim inside both processImports (line ~775) and processImportsFromExtracted (line ~1049). This creates a maintenance burden — any future change needs to be made in two places. It could be extracted to a module-level function.

Fix this →

---

Minor: Dead Branch in getLabelFromCaptures

parse-worker.ts:525

if (captureMap['definition.instance']) return 'CodeElement';
return 'CodeElement';  // fallthrough

The explicit definition.instance check is harmless but misleading — the function already falls through to 'CodeElement' for any unrecognized capture. The explicit branch suggests definition.instance maps to something other than the default, but it maps to the same value. Consider adding a comment or removing the explicit branch.

---

Missing Tests

The following new behavior has no test coverage, causing the CI line coverage failure:

1. Python singleton query — no test verifying that service = ServiceClass() at module level produces a CodeElement node with the correct name and isExported: true
2. extractImportedSymbolNames / extractSymbolNames — pure functions that are straightforward to unit test
3. Symbol-level IMPORTS edges — no test verifying that from myapp.services import service creates a File → CodeElement IMPORTS edge when the target symbol exists in the symbol table
4. Annotated assignments — the PR documents this as a known limitation (service: ServiceType = ServiceClass()); a test asserting it is not indexed would prevent silent regressions

---

Design Notes (not blocking)

• The module anchor in the tree-sitter query correctly prevents false positives inside function/class bodies — good call.
• The right: (call) constraint correctly excludes PORT = 8080 and NAME = "app" — this is the right filtering approach.
• Reusing CodeElement (no schema migration) is the right choice here.
• The symbolNames field in ExtractedImport being optional (symbolNames?: string[]) is the right API — preserves backward compatibility and avoids allocating arrays for languages where symbol extraction isn't implemented.

---

· Branch

[magyargergo]

Hey @TheGrouchy ,

Thank you for your submission! It's good to see someone has encountered with this and tried to fix it! There are some areas to tackle with. First of all, I'd like to ask you to implement regression for this PR. Please have a look at claude's review and address them at your earliest convenience.

Thank you!

[magyargergo]

This will be covered as part of #238 as it requires semantic resolution. Thank you for your contribution!