codeanalyzer-python 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl

codeanalyzer/core.py

@@ -6,18 +6,25 @@ import sys
 from pathlib import Path
 from typing import Any, Dict, Optional, Union, List
 
+import time
+
 import ray
 from codeanalyzer.utils import logger
-from codeanalyzer.schema import PyApplication, PyModule, model_dump_json, model_validate_json
+from codeanalyzer.schema import (
+    PyApplication,
+    PyExternalSymbol,
+    PyModule,
+    model_dump_json,
+    model_validate_json,
+)
 from codeanalyzer.schema.py_schema import PyCallEdge
 from codeanalyzer.semantic_analysis.call_graph import (
+    filter_external_edges,
     jedi_call_graph_edges,
     merge_edges,
     resolve_unresolved_constructors,
 )
-from codeanalyzer.semantic_analysis.codeql import CodeQLLoader
-from codeanalyzer.semantic_analysis.codeql.codeql_analysis import CodeQL
-from codeanalyzer.semantic_analysis.codeql.codeql_exceptions import CodeQLExceptions
+from codeanalyzer.semantic_analysis.pycg import PyCG, PyCGExceptions
 from codeanalyzer.syntactic_analysis.exceptions import SymbolTableBuilderRayError
 from codeanalyzer.syntactic_analysis.symbol_table_builder import SymbolTableBuilder
 from codeanalyzer.utils import ProgressBar
@@ -48,7 +55,7 @@ def _process_file_with_ray(py_file: Union[Path, str], project_dir: Union[Path, s
 
 
 class Codeanalyzer:
-    """Core functionality for CodeQL analysis.
+    """Core static analysis engine for Python projects.
 
     Args:
         options (AnalysisOptions): Analysis configuration options containing all necessary parameters.
@@ -58,15 +65,13 @@ class Codeanalyzer:
         self.options = options
         self.project_dir = Path(options.input).resolve()
         self.skip_tests = options.skip_tests
-        self.using_codeql = options.using_codeql
+        self.analysis_level = options.analysis_level
         self.rebuild_analysis = options.rebuild_analysis
+        self.no_venv = options.no_venv
         self.cache_dir = (
             options.cache_dir.resolve() if options.cache_dir is not None else self.project_dir
         ) / ".codeanalyzer"
         self.clear_cache = options.clear_cache
-        self.db_path: Optional[Path] = None
-        self.codeql_bin: Optional[Path] = None
-        self.codeql_packs_dir: Optional[Path] = None
         self.virtualenv: Optional[Path] = None
         self.using_ray: bool = options.using_ray
         self.file_name: Optional[Path] = options.file_name
@@ -78,6 +83,7 @@ class Codeanalyzer:
         capture_output: bool = True,
         check: bool = True,
         suppress_output: bool = False,
+        log_on_failure: bool = True,
     ) -> subprocess.CompletedProcess:
         """
         Runs a subprocess with real-time output streaming to the logger.
@@ -87,7 +93,10 @@ class Codeanalyzer:
             cwd: Working directory to run the command in.
             capture_output: If True, retains and returns the output.
             check: If True, raises CalledProcessError on non-zero exit.
-            suppress_output: If True, silences log output.
+            suppress_output: If True, silences per-line debug output.
+            log_on_failure: If False, suppresses the error-level log on
+                non-zero exit (use when the caller handles the exception and
+                will emit its own diagnostic).
 
         Returns:
             subprocess.CompletedProcess
@@ -118,9 +127,10 @@ class Codeanalyzer:
 
         if check and returncode != 0:
             error_output = "\n".join(output_lines)
-            logger.error(f"Command failed with exit code {returncode}: {' '.join(cmd)}")
-            if error_output:
-                logger.error(f"Command output:\n{error_output}")
+            if log_on_failure:
+                logger.error(f"Command failed with exit code {returncode}: {' '.join(cmd)}")
+                if error_output:
+                    logger.error(f"Command output:\n{error_output}")
             raise subprocess.CalledProcessError(returncode, cmd, output=error_output)
 
         return subprocess.CompletedProcess(
@@ -226,13 +236,51 @@ class Codeanalyzer:
             f"a working Python interpreter that can create virtual environments."
         )
 
+    @staticmethod
+    def _uv_bin() -> Optional[str]:
+        """Path to the uv binary bundled with the ``uv`` PyPI package (a declared
+        dependency, so always present in our install -- including inside a Docker
+        image). We deliberately ignore any uv on PATH so the analyzer always uses
+        the pinned, vendored uv. Returns ``None`` only if the package is somehow
+        missing (callers fall back to pip)."""
+        try:
+            from uv import find_uv_bin
+            return str(find_uv_bin())
+        except Exception:
+            return None
+
+    def _install_into_venv(self, venv_python: Path, args: List[str]) -> None:
+        """Install packages into the target venv, preferring uv for speed (parallel
+        downloads + a shared global cache) and falling back to the venv's own pip
+        when uv is unavailable.
+
+        Raises ``subprocess.CalledProcessError`` on failure; callers in
+        ``__enter__`` catch this and warn-and-continue so a single failing
+        package (e.g. a C extension that needs system libs) does not abort the
+        entire analysis.
+        """
+        uv = self._uv_bin()
+        if uv:
+            cmd = [uv, "pip", "install", "--python", str(venv_python), *args]
+        else:
+            cmd = [str(venv_python), "-m", "pip", "install", *args]
+        self._cmd_exec_helper(
+            cmd, cwd=self.project_dir, check=True,
+            suppress_output=True, log_on_failure=False,
+        )
+
     def __enter__(self) -> "Codeanalyzer":
         # If no virtualenv is provided, try to create one using requirements.txt or pyproject.toml
         venv_path = self.cache_dir / self.project_dir.name / "virtualenv"
         # Ensure the cache directory exists for this project
         venv_path.parent.mkdir(parents=True, exist_ok=True)
+        if self.no_venv:
+            logger.info(
+                "--no-venv: using the ambient Python environment "
+                "(skipping virtualenv creation and dependency installation)"
+            )
         # Create the virtual environment if it does not exist
-        if not venv_path.exists() or self.rebuild_analysis:
+        if not self.no_venv and (not venv_path.exists() or self.rebuild_analysis):
             logger.info(f"(Re-)creating virtual environment at {venv_path}")
             self._cmd_exec_helper(
                 [str(self._get_base_interpreter()), "-m", "venv", str(venv_path)],
@@ -249,29 +297,35 @@ class Codeanalyzer:
                 ("test-requirements.txt", ["-r"]),
             ]
 
-            for dep_file, pip_args in dependency_files:
+            for dep_file, _ in dependency_files:
                 if (self.project_dir / dep_file).exists():
                     logger.info(f"Installing dependencies from {dep_file}")
-                    self._cmd_exec_helper(
-                        [str(venv_python), "-m", "pip", "install", "-U"] + pip_args + [str(self.project_dir / dep_file)],
-                        cwd=self.project_dir,
-                        check=True,
-                    )
+                    try:
+                        self._install_into_venv(
+                            venv_python,
+                            ["--upgrade", "-r", str(self.project_dir / dep_file)],
+                        )
+                    except subprocess.CalledProcessError as exc:
+                        logger.warning(
+                            f"Dependency installation from {dep_file} failed "
+                            f"(exit {exc.returncode}) — continuing without it. "
+                            "Jedi type resolution may be incomplete."
+                        )
 
             # Handle Pipenv files
             if (self.project_dir / "Pipfile").exists():
                 logger.info("Installing dependencies from Pipfile")
-                # Note: This would require pipenv to be installed
-                self._cmd_exec_helper(
-                    [str(venv_python), "-m", "pip", "install", "pipenv"],
-                    cwd=self.project_dir,
-                    check=True,
-                )
-                self._cmd_exec_helper(
-                    ["pipenv", "install", "--dev"],
-                    cwd=self.project_dir,
-                    check=True,
-                )
+                try:
+                    self._install_into_venv(venv_python, ["pipenv"])
+                    self._cmd_exec_helper(
+                        ["pipenv", "install", "--dev"],
+                        cwd=self.project_dir,
+                        check=True,
+                    )
+                except subprocess.CalledProcessError as exc:
+                    logger.warning(
+                        f"Pipenv installation failed (exit {exc.returncode}) — continuing without it."
+                    )
 
             # Handle conda environment files
             conda_files = ["conda.yml", "environment.yml"]
@@ -289,67 +343,23 @@ class Codeanalyzer:
 
             if any((self.project_dir / file).exists() for file in package_definition_files):
                 logger.info("Installing project in editable mode")
-                self._cmd_exec_helper(
-                    [str(venv_python), "-m", "pip", "install", "-e", str(self.project_dir)],
-                    cwd=self.project_dir,
-                    check=True,
-                )
+                try:
+                    self._install_into_venv(venv_python, ["-e", str(self.project_dir)])
+                except subprocess.CalledProcessError as exc:
+                    logger.warning(
+                        f"Editable install failed (exit {exc.returncode}) — "
+                        "continuing without it. Jedi type resolution may be incomplete."
+                    )
             else:
                 logger.warning("No package definition files found, skipping editable installation")
 
-        if self.using_codeql:
-            logger.info(f"(Re-)initializing CodeQL analysis for {self.project_dir}")
-
-            # Resolve the CLI binary before anything else uses it: DB build
-            # below needs it, and so does every subsequent query run.
-            self.codeql_bin = self._ensure_codeql_bin()
-            # Download the standard query library pack (idempotent). The
-            # CLI install ships only the language extractors; the
-            # ``codeql/python-all`` library pack must be fetched separately.
-            self.codeql_packs_dir = self._ensure_codeql_packs(self.codeql_bin)
-
-            cache_root = self.cache_dir / "codeql"
-            cache_root.mkdir(parents=True, exist_ok=True)
-            self.db_path = cache_root / f"{self.project_dir.name}-db"
-            self.db_path.mkdir(exist_ok=True)
-
-            checksum_file = self.db_path / ".checksum"
-            current_checksum = self._compute_checksum(self.project_dir)
-
-            def is_cache_valid() -> bool:
-                if not (self.db_path / "db-python").exists():
-                    return False
-                if not checksum_file.exists():
-                    return False
-                return checksum_file.read_text().strip() == current_checksum
-
-            if self.rebuild_analysis or not is_cache_valid():
-                logger.info("Creating new CodeQL database...")
-
-                cmd = [
-                    str(self.codeql_bin),
-                    "database",
-                    "create",
-                    str(self.db_path),
-                    f"--source-root={self.project_dir}",
-                    "--language=python",
-                    "--overwrite",
-                ]
-
-                proc = subprocess.Popen(
-                    cmd, stdout=subprocess.DEVNULL, stderr=subprocess.PIPE
-                )
-                _, err = proc.communicate()
-
-                if proc.returncode != 0:
-                    raise CodeQLExceptions.CodeQLDatabaseBuildException(
-                        f"Error building CodeQL database:\n{err.decode()}"
-                    )
-
-                checksum_file.write_text(current_checksum)
-
-            else:
-                logger.info(f"Reusing cached CodeQL DB at {self.db_path}")
+        # Point Jedi at the analysis venv so it resolves the project's third-party
+        # imports. This runs on both a fresh build and a lazy reuse of an existing
+        # venv -- previously self.virtualenv stayed None, so the install above was
+        # never actually used by the symbol-table builder. With --no-venv we leave
+        # it None so Jedi resolves against the ambient interpreter instead.
+        if not self.no_venv and venv_path.exists():
+            self.virtualenv = venv_path
 
         return self
 
@@ -358,6 +368,43 @@ class Codeanalyzer:
             logger.info(f"Clearing cache directory: {self.cache_dir}")
             shutil.rmtree(self.cache_dir)
 
+    @staticmethod
+    def _compute_external_symbols(symbol_table, call_graph):
+        """Build the external-symbol map: every call-graph endpoint whose signature
+        is not a declared class/callable in the symbol table is an external (an
+        imported library or builtin member). ``name``/``module`` are derived from
+        the signature (best effort: split on the last dot)."""
+        declared = set()
+
+        def walk_callable(c):
+            declared.add(c.signature)
+            for ic in (c.inner_callables or {}).values():
+                walk_callable(ic)
+            for cl in (c.inner_classes or {}).values():
+                walk_class(cl)
+
+        def walk_class(cl):
+            declared.add(cl.signature)
+            for m in (cl.methods or {}).values():
+                walk_callable(m)
+            for ic in (cl.inner_classes or {}).values():
+                walk_class(ic)
+
+        for mod in symbol_table.values():
+            for c in (mod.functions or {}).values():
+                walk_callable(c)
+            for cl in (mod.classes or {}).values():
+                walk_class(cl)
+
+        externals: Dict[str, PyExternalSymbol] = {}
+        for edge in call_graph:
+            for sig in (edge.source, edge.target):
+                if sig in declared or sig in externals:
+                    continue
+                module, name = sig.rsplit(".", 1) if "." in sig else (sig, sig)
+                externals[sig] = PyExternalSymbol(name=name, module=module)
+        return externals
+
     def analyze(self) -> PyApplication:
         """Analyze the project and return a PyApplication with symbol table.
         
@@ -378,27 +425,35 @@ class Codeanalyzer:
         # Build symbol table from cached application if available (if no available, the build a new one)
         symbol_table = self._build_symbol_table(cached_pyapplication.symbol_table if cached_pyapplication else {})
 
-        # Build the call graph in four steps:
-        #   1. Run CodeQL (when enabled). Produces resolved edges with
-        #      ``provenance=["codeql"]`` and augments ``PyCallsite``s
-        #      in-place — filling ``callee_signature`` for sites Jedi
-        #      couldn't resolve.
-        #   2. Heuristic fallback for constructor calls neither Jedi nor
-        #      CodeQL could resolve (commonly classes nested inside
-        #      functions). Walks the symbol table by class short-name +
-        #      scope and writes ``<class>.__init__`` into the site.
-        #   3. Derive Jedi edges from the now-fully-augmented symbol
-        #      table — these reflect every resolution the symbol table
-        #      contains, regardless of which pass put it there.
-        #   4. Merge with CodeQL edges; provenance unions for edges both
-        #      backends saw.
-        codeql_edges = self._get_call_graph(symbol_table, augment_sites=True)
         resolve_unresolved_constructors(symbol_table)
+
+        # Level 1: Jedi call graph.
+        t0_jedi = time.perf_counter()
         jedi_edges = jedi_call_graph_edges(symbol_table)
-        call_graph = merge_edges(jedi_edges, codeql_edges)
+        call_graph = list(jedi_edges)
+        logger.info("✅ Jedi: %d edges in %.1fs", len(call_graph), time.perf_counter() - t0_jedi)
+
+        if self.analysis_level >= 2:
+            # Level 2: also add PyCG edges. The Jedi edges double as the
+            # coupling graph that drives coupling-aware PyCG sharding.
+            pycg_edges = self._get_pycg_call_graph(symbol_table, jedi_edges)
+            call_graph = merge_edges(call_graph, pycg_edges)
+
+        call_graph = filter_external_edges(call_graph, symbol_table)
+
+        # Classify call-graph endpoints that are not declared in the symbol table
+        # (imported library / builtin members) once, so the JSON and Neo4j backends
+        # share one authoritative external-symbol set.
+        external_symbols = self._compute_external_symbols(symbol_table, call_graph)
 
         # Recreate pyapplication
-        app = PyApplication.builder().symbol_table(symbol_table).call_graph(call_graph).build()
+        app = (
+            PyApplication.builder()
+            .symbol_table(symbol_table)
+            .call_graph(call_graph)
+            .external_symbols(external_symbols)
+            .build()
+        )
         
         # Save to cache
         self._save_analysis_cache(app, cache_file)
@@ -491,7 +546,8 @@ class Codeanalyzer:
             Dict[str, PyModule]: A dictionary mapping file paths to PyModule objects.
         """
         symbol_table: Dict[str, PyModule] = {}
-        
+        t0_st = time.perf_counter()
+
         # Handle single file analysis
         if self.file_name is not None:
             single_file = self.project_dir / self.file_name
@@ -598,123 +654,44 @@ class Codeanalyzer:
             if files_from_cache > 0:
                 logger.info(f"Reused {files_from_cache} files from cache, processed {files_processed} new/changed files")
 
-        logger.info("✅ Symbol table generation complete.")
-        return symbol_table
-
-    def _ensure_codeql_packs(self, codeql_bin: Path) -> Path:
-        """Materialize a qlpack that depends on ``codeql/python-all``.
-
-        The CodeQL CLI install ships only the language extractors — query
-        library packs (and their transitive dependencies like
-        ``codeql/concepts``) must be resolved separately. The canonical
-        way is to declare the dependency in a ``qlpack.yml`` and run
-        ``codeql pack install`` in that directory; CodeQL writes a
-        ``codeql-pack.lock.yml`` and downloads everything needed.
-
-        We do this once per project under ``<cache_dir>/codeql/qlpack/``
-        and return that directory. The query runner then writes its
-        temporary ``.ql`` file inside this pack — colocation makes
-        ``import python`` resolve without any ``--additional-packs`` or
-        ``--search-path`` gymnastics.
-        """
-        pack_dir = self.cache_dir / "codeql" / "qlpack"
-        pack_dir.mkdir(parents=True, exist_ok=True)
-        qlpack_yml = pack_dir / "qlpack.yml"
-        lock_file = pack_dir / "codeql-pack.lock.yml"
-
-        if not qlpack_yml.exists():
-            qlpack_yml.write_text(
-                "name: codeanalyzer-deps\n"
-                "version: 1.0.0\n"
-                "dependencies:\n"
-                '  codeql/python-all: "*"\n'
-            )
-
-        if lock_file.exists():
-            logger.debug(f"CodeQL pack dependencies already installed in {pack_dir}")
-            return pack_dir
-
-        logger.info(f"Installing CodeQL pack dependencies in {pack_dir}.")
-        proc = subprocess.Popen(
-            [str(codeql_bin), "pack", "install", str(pack_dir)],
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-        )
-        _, err = proc.communicate()
-        if proc.returncode != 0:
-            raise CodeQLExceptions.CodeQLDatabaseBuildException(
-                f"Failed to install CodeQL pack dependencies:\n"
-                f"{(err or b'').decode(errors='replace')}"
-            )
-        return pack_dir
-
-    def _ensure_codeql_bin(self) -> Path:
-        """Locate (or download) the CodeQL CLI binary into the project cache.
-
-        Resolution order:
-          1. An existing binary inside ``<cache_dir>/codeql/bin/`` —
-             reused across runs on the same project.
-          2. ``codeql`` already on the user's PATH — picked up verbatim.
-          3. Otherwise, download into ``<cache_dir>/codeql/bin/``.
-
-        The project-local cache is preferred over PATH so the version we
-        installed earlier wins over whatever the OS ships — keeps behavior
-        deterministic when the user has both.
-        """
-        bin_root = self.cache_dir / "codeql" / "bin"
-        bin_root.mkdir(parents=True, exist_ok=True)
-
-        existing = next(
-            (p for p in bin_root.rglob("codeql") if p.is_file()),
-            None,
+        logger.info(
+            "✅ Symbol table: %d modules in %.1fs",
+            len(symbol_table), time.perf_counter() - t0_st,
         )
-        if existing and os.access(existing, os.X_OK):
-            logger.debug(f"Reusing cached CodeQL CLI at {existing}")
-            return existing.resolve()
-
-        on_path = shutil.which("codeql")
-        if on_path:
-            logger.debug(f"Using CodeQL CLI from PATH at {on_path}")
-            return Path(on_path)
-
-        logger.info(f"CodeQL CLI not found; downloading into {bin_root}.")
-        downloaded = CodeQLLoader.download_and_extract_codeql(bin_root)
-        if not downloaded.exists() or not os.access(downloaded, os.X_OK):
-            raise FileNotFoundError(
-                f"CodeQL binary not executable after download: {downloaded}"
-            )
-        return downloaded
+        return symbol_table
 
-    def _get_call_graph(
+    def _get_pycg_call_graph(
         self,
         symbol_table: Dict[str, PyModule],
-        augment_sites: bool = False,
+        jedi_edges: List[PyCallEdge],
     ) -> List[PyCallEdge]:
-        """Build CodeQL-resolved call edges and optionally augment sites.
+        """Build PyCG-resolved call edges.
 
-        Returns an empty list when CodeQL isn't enabled or the database
-        isn't available. Edges carry ``provenance=["codeql"]`` — merge
-        with Jedi-derived edges via ``call_graph.merge_edges``.
+        Runs PyCG's iterative name-pointer analysis over the whole project
+        and returns edges with ``provenance=["pycg"]``.  Falls back to an
+        empty list and logs a warning on any failure so the caller can
+        continue with Jedi-only edges.
 
-        When ``augment_sites`` is True, also mutates
-        ``PyCallable.call_sites`` in the symbol table to backfill
-        ``callee_signature`` for sites Jedi couldn't resolve. The single
-        CodeQL query is shared (cached on the ``CodeQL`` instance) so
-        this costs no extra DB work.
+        *jedi_edges* are the level-1 call edges; under the ``jedi`` shard
+        strategy they drive coupling-aware partitioning (see
+        :func:`shard_planner.plan_shards`).
         """
-        if not self.using_codeql or self.db_path is None:
-            return []
         try:
-            cq = CodeQL(
+            pycg = PyCG(
                 self.project_dir,
-                self.db_path,
-                codeql_bin=self.codeql_bin,
-                codeql_packs_dir=self.codeql_packs_dir,
+                skip_tests=self.skip_tests,
+                shard=self.options.pycg_shard,
+                shard_ceiling=self.options.pycg_shard_ceiling,
+                shard_timeout=self.options.pycg_shard_timeout,
+                shard_strategy=self.options.pycg_shard_strategy,
+                max_iter=self.options.pycg_max_iter,
+                using_ray=self.using_ray,
             )
-            edges = cq.build_call_graph_edges(symbol_table)
-            if augment_sites:
-                cq.augment_call_sites(symbol_table)
-            return edges
-        except Exception as exc:
-            logger.warning(f"CodeQL call-graph extraction failed: {exc}")
+            return pycg.build_call_graph_edges(symbol_table, jedi_edges=jedi_edges)
+        except PyCGExceptions.PyCGImportError as exc:
+            logger.warning(f"PyCG not installed — level 2 edges will be Jedi-only: {exc}")
+            return []
+        except PyCGExceptions.PyCGAnalysisError as exc:
+            logger.warning(f"PyCG analysis failed — level 2 edges will be Jedi-only: {exc}")
+            logger.debug("PyCG full traceback:", exc_info=True)
             return []

codeanalyzer/neo4j/bolt.py

@@ -77,6 +77,13 @@ def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
             for stmt in [*CONSTRAINTS, *INDEXES]:
                 s.run(stmt)
 
+        # The application anchor (a shared node) — used to scope the orphan prune
+        # so it never touches modules belonging to a different :PyApplication.
+        app_name = next(
+            (n.value for n in rows.nodes if n.labels and n.labels[0] == "PyApplication"),
+            None,
+        )
+
         # Partition nodes by owning module; shared nodes have no _module.
         by_module: Dict[str, List[NodeRow]] = {}
         shared: List[NodeRow] = []
@@ -135,13 +142,17 @@ def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
         _upsert_edges(session, neo4j, edges)
 
         # 6. orphan prune — only safe on a full run (a targeted run can't tell deleted from untargeted).
-        if full_run:
+        # Scope to THIS application's anchor so a full run for application B never
+        # deletes application A's modules from a shared database.
+        if full_run and app_name is not None:
             present = list(by_module.keys())
             with session() as s:
                 res = s.run(
-                    "MATCH (m:PyModule) WHERE NOT m.file_key IN $present "
+                    "MATCH (:PyApplication {name: $app})-[:PY_HAS_MODULE]->(m:PyModule) "
+                    "WHERE NOT m.file_key IN $present "
                     f"OPTIONAL MATCH (m)-{DESCENDANTS}->(x) DETACH DELETE x, m "
                     "RETURN count(m) AS pruned",
+                    app=app_name,
                     present=present,
                 )
                 pruned = res.single()

codeanalyzer/neo4j/catalog.py

@@ -34,7 +34,7 @@ from typing import Dict, List
 
 from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
 
-SCHEMA_VERSION = "1.0.0"
+SCHEMA_VERSION = "1.1.0"
 
 # PropType ∈ {"string", "integer", "float", "boolean", "string[]", "integer[]"}.
 
@@ -119,7 +119,7 @@ NODE_LABELS: List[NodeLabel] = [
         "PyExternal",
         "PySymbol",
         "signature",
-        {"signature": "string", "name": "string"},
+        {"signature": "string", "name": "string", "module": "string"},
     ),
     NodeLabel("PyPackage", "PyPackage", "name", {"name": "string"}),
     NodeLabel(

codeanalyzer/neo4j/project.py

@@ -60,11 +60,12 @@ def project(app: PyApplication, app_name: str) -> GraphRows:
         b.edge("PY_HAS_MODULE", app_ref, mod_ref)
         _project_module_body(b, file_key, mod_ref, mod)
 
-    # The aggregated :PY_CALLS twin. Endpoints not present in the symbol table become
-    # :PyExternal ghost nodes (the analyzer already preserves them as ghost nodes).
+    # The aggregated :PY_CALLS twin. Endpoints listed in app.external_symbols become
+    # :PyExternal ghost nodes; the rest are declared :PySymbol nodes already emitted.
+    externals = app.external_symbols or {}
     for e in app.call_graph:
-        src = _call_endpoint(b, e.source)
-        tgt = _call_endpoint(b, e.target)
+        src = _call_endpoint(b, e.source, externals)
+        tgt = _call_endpoint(b, e.target, externals)
         b.edge("PY_CALLS", src, tgt, _call_edge_props(e.weight, list(e.provenance or [])))
 
     return b.finish()
@@ -74,13 +75,20 @@ def _sym(signature: str) -> NodeRef:
     return NodeRef("PySymbol", "signature", signature)
 
 
-def _call_endpoint(b: RowBuilder, signature: str) -> NodeRef:
-    """A call-graph endpoint: a known callable already emitted, or a phantom
-    :PyExternal symbol materialized on demand for a ghost target."""
-    if b.has_key(signature):
+def _call_endpoint(b: RowBuilder, signature: str, externals: dict) -> NodeRef:
+    """A call-graph endpoint: a declared callable already emitted, or an external
+    symbol (imported library / builtin member) materialized as a :PyExternal ghost.
+
+    Classification is authoritative -- it comes from ``app.external_symbols``, not a
+    "present in the graph" heuristic -- so an imported module name (which exists only
+    as a :PyPackage) can never shadow the call target. A small fallback still
+    materializes an external for any endpoint that is neither declared nor listed."""
+    ext = externals.get(signature)
+    if ext is None and b.has_key("PySymbol", signature):
         return _sym(signature)
-    name = signature.rsplit(".", 1)[-1] if "." in signature else signature
-    return b.node(["PySymbol", "PyExternal"], "signature", signature, {"name": name})
+    name = ext.name if ext is not None else (signature.rsplit(".", 1)[-1] if "." in signature else signature)
+    module = ext.module if ext is not None else None
+    return b.node(["PySymbol", "PyExternal"], "signature", signature, prune({"name": name, "module": module}))
 
 
 # ----------------------------------------------------------------------------------------------