fix(python): resolve module imports to files and aliased module calls (#2387) by carlos-alm · Pull Request #2410 · optave/ops-codegraph-tool · GitHub

Closes #2387.

The problem

Python emitted zero imports edges, so deps, impact and map were blind on every Python repo, and import lib as L + L.f() resolved to nothing — leaving the callee reported as dead code. Four actively-developed Optave Python services are affected.

Two distinct defects, both reproduced on the minimal fixture from the issue before any change:

Neither resolver had a Python branch. A dotted module path (pipeline.util) is not a filesystem path, so it fell through to the bare-specifier fallback and was echoed back unchanged, matching no file node. Python's relative imports share JS's leading-dot spelling but mean "climb the package tree", so from ..util import x was mis-resolved by the generic relative branch as well.
The extractor put the alias in Import.source. For import lib as L, source was L — an alias can never resolve to a file. A multi-module import a, b also collapsed into a single record naming only a, silently losing b.

The approach

Import roots are derived from package layout, not assumed to be the repo root: walk up from the importing file while each level is a package (contains __init__.py), and stop at the first ancestor that is not. That ancestor is what would be on sys.path at runtime, so the PyPA-endorsed "src layout" (src/pipeline/…, imported as from pipeline…) and a flat layout resolve under one rule with no configuration. The src-layout case is exactly what made data-analytics-pipeline-svc resolve nothing.

Roots that no convention implies are read from pyproject.toml — [tool.pytest.ini_options] pythonpath, [tool.setuptools] package-dir, [tool.setuptools.packages.find] where, and poetry's packages[].from. That covers the pythonpath = ["src", "scripts"] case observed on the same repo, where scripts/ is importable but has no package marker.

Module bindings are modelled explicitly. A new Import.namespaceBindings field records local names bound to a module rather than a symbol. Call resolution reads it to interpret L.strip_block() as "strip_block, as declared in the module L refers to" — scoped to that module's file and authoritative, so a miss can't be claimed by an unrelated same-named function elsewhere. The field is defined generally (JavaScript's import * as ns is the same concept) but only Python populates it here.

from pkg import submod is resolved as a submodule when pkg/submod.py exists — Python's two readings of that statement are indistinguishable without knowing which files exist, so the resolver decides rather than the extractor. It both binds a namespace (so submod.f() resolves) and emits an imports edge to the submodule, so deps/impact name the module that actually changed instead of only the package barrel.

Import-root caches are cleared per rebuild alongside the Cargo one, since pyproject.toml isn't a watched extension and layout-derived roots go stale the moment an __init__.py is added or removed.

Engine parity

Mirrored in crates/codegraph-core/ (extractor, resolver, edge emission, call resolution, NAPI cache-clear export). Native and WASM were compared directly on five fixtures — Python minimal, Python src-layout, and three JS controls — and produce identical edge sets.

Worth knowing for future parity work: --engine wasm does not exercise the JS resolver when the native addon is present, because resolveImportPath prefers native regardless of the flag. The JS path has to be tested with the addon unavailable.

Verification

4833 TS tests pass, 886 Rust tests pass, lint and typecheck clean.
New coverage: 14 resolver unit tests (tests/unit/resolve.test.ts), 12 Rust resolver/extractor unit tests, and an 8-assertion integration test run against both engines (tests/integration/issue-2387-python-imports.test.ts) on a src-layout fixture. Assertions pin each edge to a specific target file, so a resolver falling back to a global same-name lookup cannot pass.
Stdlib and third-party modules deliberately stay unresolved and are treated as external; a test asserts every emitted imports edge lands on a real project file.

Found in passing, not fixed here

bug(parity): WASM path skips the #2032 reachability downgrade that native applies #2407 — the WASM path skips the roles --role dead: non-transitive fan-in means a function called only by another dead function is never flagged dead #2032 reachability downgrade that native applies. Not caused by this work: both role classifiers are untouched by this diff, and it reproduces on plain same-file JavaScript with no Python involved. Python previously had too few resolved call edges for the reachability path to be reached at all, which is why it stayed invisible.

…#2387) Python emitted zero `imports` edges, leaving `deps`, `impact` and `map` blind on every Python repo, and `import lib as L` + `L.f()` resolved to nothing, so the callee was reported as dead code. Two defects sat behind that: 1. Neither resolver had a Python branch. A dotted module path is not a filesystem path, so it fell through to the bare-specifier fallback and was echoed back unchanged, matching no file node. Python's relative imports share JS's leading-dot spelling but mean "climb the package tree", so they were mis-resolved by the generic relative branch too. 2. The extractor put the alias in `Import.source` for `import lib as L`, which can never resolve to a file, and `import a, b` collapsed into one record naming only `a`. Resolution derives the import root from package layout — walk up while each level has `__init__.py` — so the PyPA "src layout" and a flat layout work under one rule with no configuration, and honours pyproject-declared roots (`pythonpath`, `package-dir`, poetry `from`, setuptools `where`) for roots no convention implies. Module bindings are now recorded in a new `namespaceBindings` field, which call resolution reads to resolve `L.f()` as "f, as declared in the module L refers to". `from pkg import submod` is resolved as a submodule when `pkg/submod.py` exists, so it both binds a namespace and depends on the module that actually changed rather than only on `pkg/__init__.py`. Mirrored in crates/codegraph-core; both engines verified to produce identical edge sets on the fixtures.

Greptile Summary

The follow-up completes Python import resolution across the TypeScript/WASM and native Rust engines.

Resolves absolute, relative, configured-root, and submodule imports to project files.
Models module namespace bindings so aliased module calls resolve within the correct file.
Preserves local aliases and original names for aliased from … import statements.
Mirrors full-build behavior in incremental rebuilds and adds cross-engine regression coverage.

Confidence Score: 5/5

The PR appears safe to merge.

The previously reported aliased submodule failure is fixed, and no blocking failure remains.

Important Files Changed

Filename	Overview
src/extractors/python.ts	Correctly preserves local aliases and original imported names while splitting module imports into independent namespace bindings.
crates/codegraph-core/src/extractors/python.rs	Mirrors the TypeScript Python extraction behavior and its alias representation.
src/domain/graph/builder/stages/build-edges.ts	Resolves imported submodules and threads namespace bindings through full-build import and call edge construction.
crates/codegraph-core/src/domain/graph/builder/stages/build_edges.rs	Adds native namespace-scoped call resolution consistent with the TypeScript implementation.
src/domain/graph/resolve.ts	Adds Python-aware module, package-root, relative-import, and configured-root resolution.
crates/codegraph-core/src/domain/graph/resolve.rs	Mirrors Python import resolution and cache management in the native engine.
src/domain/graph/builder/incremental.ts	Carries namespace and submodule resolution into watcher-driven incremental edge rebuilding.
tests/integration/issue-2387-python-imports.test.ts	Verifies file-specific import and call edges, including the previously reported aliased submodule case, across both engines.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  Source["Python import statement"] --> Extract["Extract source, local binding, and rename pair"]
  Extract --> Resolve["Resolve module path or imported submodule"]
  Resolve --> ImportEdge["Emit file-level imports edge"]
  Resolve --> Namespace["Map local alias to module file"]
  Namespace --> Call["Resolve alias.function() in that file"]
  Call --> CallEdge["Emit scoped call edge"]

Reviews (2): Last reviewed commit: "fix(python): preserve local alias in ali..." | Re-trigger Greptile

Aliased submodule binding is lost

When Python uses from pkg import submod as alias, extraction records only submod, so this branch keys namespaceImports under the original name while alias.f() looks up the local alias. The call therefore produces no edge to f in pkg/submod.py, leaving dependency, impact, map, and dead-code results incorrect in both engines.

Knowledge Base Used:

Fixed — handlePyImportFrom (and the mirrored handle_import_from_stmt in python.rs) now records the local alias in names and preserves the pre-alias name in renamedImports/renamed_imports, exactly like the existing mechanism for JS's import { X as Y } (#1730). importNamePairs/import_name_pairs already recover the pre-alias name from there for resolvePythonSubmodule, so alias.f() now resolves correctly in both engines — no resolver-side changes were needed in build-edges.ts/incremental.ts/resolve.rs. Added extractor unit tests in both engines plus an integration test (from pipeline.stages import transform as tr; tr.run_transform([])) covering the call-through-alias case. Pushed in 230ca0b.

Codegraph Impact Analysis

29 functions changed → 56 callers affected across 9 files

resolveCallTargets in src/domain/graph/builder/call-resolver.ts:436 (15 transitive callers)
rebuildReverseDepEdges in src/domain/graph/builder/incremental.ts:330 (3 transitive callers)
buildImportedNamesMap in src/domain/graph/builder/incremental.ts:900 (5 transitive callers)
buildCallEdges in src/domain/graph/builder/incremental.ts:1490 (5 transitive callers)
rebuildEdgesForTargetFile in src/domain/graph/builder/incremental.ts:1762 (3 transitive callers)
rebuildFile in src/domain/graph/builder/incremental.ts:2239 (4 transitive callers)
emitEdgesForImport in src/domain/graph/builder/stages/build-edges.ts:265 (3 transitive callers)
buildImportedNamesForNative in src/domain/graph/builder/stages/build-edges.ts:1099 (3 transitive callers)
addImports in src/domain/graph/builder/stages/build-edges.ts:1114 (3 transitive callers)
buildCallEdgesJS in src/domain/graph/builder/stages/build-edges.ts:1227 (3 transitive callers)
buildImportedNamesMap in src/domain/graph/builder/stages/build-edges.ts:1356 (7 transitive callers)
addImportNames in src/domain/graph/builder/stages/build-edges.ts:1374 (6 transitive callers)
resolveFallbackTargets in src/domain/graph/builder/stages/build-edges.ts:1561 (3 transitive callers)
buildFileCallEdges in src/domain/graph/builder/stages/build-edges.ts:2025 (3 transitive callers)
isPythonFile in src/domain/graph/resolve.ts:778 (17 transitive callers)
pythonCandidateExists in src/domain/graph/resolve.ts:790 (6 transitive callers)
parsePyprojectImportRoots in src/domain/graph/resolve.ts:811 (3 transitive callers)
addRoot in src/domain/graph/resolve.ts:825 (3 transitive callers)
getPythonConfiguredRoots in src/domain/graph/resolve.ts:862 (4 transitive callers)
clearPythonImportRootsCache in src/domain/graph/resolve.ts:877 (3 transitive callers)

…2410) `from pkg import submod as alias` recorded the pre-alias name (`submod`) as the local binding in both engines, so `alias.f()` had no local name to key namespace/submodule resolution off of and resolved to nothing. This is the `from ... import` analogue of the `import lib as L` alias-loss this PR already fixes for the plain import form. Mirrors the existing renamedImports/renamed_imports mechanism used for JS's `import { X as Y }` (#1730): `names` now carries the local alias, and the pre-alias name is preserved in renamedImports/renamed_imports for resolvePythonSubmodule/barrel tracing to look up. import_name_pairs already recovers it from there, so no downstream resolver change is needed. Adds extractor unit tests in both engines plus an integration regression test for the call-through-alias case. docs check acknowledged: bug fix only, no new language/feature/architecture change. Found in Greptile review of #2410. Impact: 1 functions changed, 4 affected

Addressed Greptile's review feedback:

Fixed the aliased from-import submodule binding loss (Confidence Score concern + inline comment on build-edges.ts:1378-1388): from pkg import submod as alias now correctly records the local alias alias in Import.names (both the TS and Rust extractors), with the pre-alias name submod preserved in renamedImports/renamed_imports for resolvePythonSubmodule/barrel tracing to look up — mirroring the existing codegraph exports does not credit consumers that import via a rename (import { X as Y }) #1730 renamed-import mechanism already used for JS's import { X as Y }. No changes were needed in build-edges.ts, incremental.ts, or resolve.rs — importNamePairs/import_name_pairs already handle a renamed binding correctly once the extractor supplies one.
Added regression coverage: extractor-level unit tests in tests/parsers/unified.test.ts and inline #[test]s in crates/codegraph-core/src/extractors/python.rs, plus a new integration assertion in tests/integration/issue-2387-python-imports.test.ts for the call-through-alias case that the previous test suite omitted (as flagged in the Important Files Changed table).

Pushed in 230ca0b.

@greptileai

carlos-alm mentioned this pull request Aug 10, 2026

fix(roles): classify Python __main__ entrypoints as entry (#2392) #2411

Merged

greptile-apps Bot reviewed Aug 10, 2026

View reviewed changes

carlos-alm mentioned this pull request Aug 10, 2026

follow-up: nested tests/benchmarks/resolution/fixtures/*/.codegraph/ build artifacts aren't gitignored #2415

Closed

Merge branch 'main' into fix/python-import-resolution

b5f3216

carlos-alm merged commit 0f5f9b7 into main Aug 10, 2026
19 checks passed

carlos-alm deleted the fix/python-import-resolution branch August 10, 2026 03:02

github-actions Bot locked and limited conversation to collaborators Aug 10, 2026

                     if (name !== local) importedOriginalNames.set(local, name);
+                    // `from pkg import submod` binds a module too, but which reading applies
+                    // depends on whether `pkg/submod.py` exists — a question only the
+                    // resolver can answer (#2387).
+                    const submodule = resolvePythonSubmodule(
+                      path.join(rootDir, relPath),
+                      imp.source,
+                      original,
+                      rootDir,
+                      ctx.allFiles,
+                    );

fix(python): resolve module imports to files and aliased module calls (#2387) by carlos-alm · Pull Request #2410 · optave/ops-codegraph-tool · GitHub

Uh oh!

fix(python): resolve module imports to files and aliased module calls (#2387) - #2410

fix(python): resolve module imports to files and aliased module calls (#2387)#2410
carlos-alm merged 3 commits into
mainfrom
fix/python-import-resolution

carlos-alm commented Aug 10, 2026

Uh oh!

greptile-apps Bot commented Aug 10, 2026 •
edited
Loading

Uh oh!

Uh oh!

greptile-apps Bot Aug 10, 2026

Uh oh!

carlos-alm Aug 10, 2026

Uh oh!

github-actions Bot commented Aug 10, 2026 •
edited
Loading

Uh oh!

Uh oh!

carlos-alm commented Aug 10, 2026

Uh oh!

carlos-alm commented Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

fix(python): resolve module imports to files and aliased module calls (#2387) by carlos-alm · Pull Request #2410 · optave/ops-codegraph-tool · GitHub

Uh oh!

fix(python): resolve module imports to files and aliased module calls (#2387) - #2410

fix(python): resolve module imports to files and aliased module calls (#2387)#2410carlos-alm merged 3 commits intomainoptave/ops-codegraph-tool:mainfrom fix/python-import-resolutionoptave/ops-codegraph-tool:fix/python-import-resolutionCopy head branch name to clipboard

Conversation

carlos-alm commented Aug 10, 2026

The problem

The approach

Engine parity

Verification

Found in passing, not fixed here

Uh oh!

greptile-apps Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Flowchart

Uh oh!

greptile-apps Bot Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

carlos-alm Aug 10, 2026

Choose a reason for hiding this comment

Uh oh!

github-actions Bot commented Aug 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codegraph Impact Analysis

Uh oh!

carlos-alm commented Aug 10, 2026

Uh oh!

carlos-alm commented Aug 10, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

fix(python): resolve module imports to files and aliased module calls (#2387)#2410
carlos-alm merged 3 commits into
mainfrom
fix/python-import-resolution

greptile-apps Bot commented Aug 10, 2026 •
edited
Loading

github-actions Bot commented Aug 10, 2026 •
edited
Loading