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

codeanalyzer/__main__.py

@@ -7,13 +7,18 @@ from codeanalyzer.core import Codeanalyzer
 from codeanalyzer.utils import _set_log_level, logger
 from codeanalyzer.config import OutputFormat
 from codeanalyzer.schema import model_dump_json
-from codeanalyzer.options import AnalysisOptions
+from codeanalyzer.options import AnalysisOptions, EmitTarget
 
 
 def main(
     input: Annotated[
-        Path, typer.Option("-i", "--input", help="Path to the project root directory.")
-    ],
+        Optional[Path],
+        typer.Option(
+            "-i",
+            "--input",
+            help="Path to the project root directory (not required for --emit schema).",
+        ),
+    ] = None,
     output: Annotated[
         Optional[Path],
         typer.Option("-o", "--output", help="Output directory for artifacts."),
@@ -23,14 +28,61 @@ def main(
         typer.Option(
             "-f",
             "--format",
-            help="Output format: json or msgpack.",
+            help="Output format for --emit json: json or msgpack.",
             case_sensitive=False,
         ),
     ] = OutputFormat.JSON,
-    analysis_level: Annotated[
-        int,
-        typer.Option("-a", "--analysis-level", help="1: symbol table, 2: call graph."),
-    ] = 1,
+    emit: Annotated[
+        EmitTarget,
+        typer.Option(
+            "--emit",
+            help="Output target: json (analysis.json, default) | neo4j (graph.cypher or live "
+            "Bolt push) | schema (the Neo4j schema.json contract).",
+            case_sensitive=False,
+        ),
+    ] = EmitTarget.JSON,
+    app_name: Annotated[
+        Optional[str],
+        typer.Option(
+            "--app-name",
+            help="Logical application name for the graph :PyApplication anchor "
+            "(default: input dir name).",
+        ),
+    ] = None,
+    neo4j_uri: Annotated[
+        Optional[str],
+        typer.Option(
+            "--neo4j-uri",
+            envvar="NEO4J_URI",
+            help="Push the graph to a live Neo4j over Bolt (incremental); omit to write "
+            "graph.cypher. [env: NEO4J_URI]",
+        ),
+    ] = None,
+    neo4j_user: Annotated[
+        str,
+        typer.Option(
+            "--neo4j-user",
+            envvar="NEO4J_USERNAME",
+            help="Neo4j username. [env: NEO4J_USERNAME]",
+        ),
+    ] = "neo4j",
+    neo4j_password: Annotated[
+        str,
+        typer.Option(
+            "--neo4j-password",
+            envvar="NEO4J_PASSWORD",
+            help="Neo4j password. Prefer the env var over the flag (the flag is visible in shell "
+            "history / process list). [env: NEO4J_PASSWORD]",
+        ),
+    ] = "neo4j",
+    neo4j_database: Annotated[
+        Optional[str],
+        typer.Option(
+            "--neo4j-database",
+            envvar="NEO4J_DATABASE",
+            help="Neo4j database name (default: server default). [env: NEO4J_DATABASE]",
+        ),
+    ] = None,
     using_codeql: Annotated[
         bool, typer.Option("--codeql/--no-codeql", help="Enable CodeQL-based analysis.")
     ] = False,
@@ -82,7 +134,12 @@ def main(
         input=input,
         output=output,
         format=format,
-        analysis_level=analysis_level,
+        emit=emit,
+        app_name=app_name,
+        neo4j_uri=neo4j_uri,
+        neo4j_user=neo4j_user,
+        neo4j_password=neo4j_password,
+        neo4j_database=neo4j_database,
         using_codeql=using_codeql,
         using_ray=using_ray,
         rebuild_analysis=rebuild_analysis,
@@ -94,6 +151,18 @@ def main(
     )
 
     _set_log_level(options.verbosity)
+
+    # The schema contract is a static artifact — no project analysis required.
+    if options.emit == EmitTarget.SCHEMA:
+        from codeanalyzer.neo4j.emit import emit_schema
+
+        emit_schema(options.output)
+        return
+
+    # Every other target requires an input project.
+    if options.input is None:
+        logger.error("Missing option '-i' / '--input' (required for --emit json | neo4j).")
+        raise typer.Exit(code=1)
     if not options.input.exists():
         logger.error(f"Input path '{options.input}' does not exist.")
         raise typer.Exit(code=1)
@@ -117,7 +186,11 @@ def main(
     with Codeanalyzer(options) as analyzer:
         artifacts = analyzer.analyze()
 
-        if options.output is None:
+        if options.emit == EmitTarget.NEO4J:
+            from codeanalyzer.neo4j.emit import emit_neo4j
+
+            emit_neo4j(artifacts, options)
+        elif options.output is None:
             print(model_dump_json(artifacts, separators=(",", ":")))
         else:
             options.output.mkdir(parents=True, exist_ok=True)
@@ -147,7 +220,7 @@ def _write_output(artifacts, output_dir: Path, format: OutputFormat):
 
 app = typer.Typer(
     callback=main,
-    name="codeanalyzer",
+    name="canpy",
     help="Static Analysis on Python source code using Jedi, CodeQL and Tree sitter.",
     invoke_without_command=True,
     no_args_is_help=True,
@@ -156,5 +229,20 @@ app = typer.Typer(
     pretty_exceptions_show_locals=False,
 )
 
+def deprecated_main() -> None:
+    """Entry point for the legacy ``codeanalyzer`` command. Prints a one-line
+    deprecation notice to stderr (so piped stdout — e.g. ``--emit schema`` — stays
+    clean) and then runs the CLI unchanged. Kept for backwards compatibility; will
+    be removed in a future release."""
+    import sys
+
+    print(
+        "codeanalyzer: this command has been renamed to `canpy`. The `codeanalyzer` "
+        "alias is deprecated and will be removed in a future release — please use `canpy`.",
+        file=sys.stderr,
+    )
+    app()
+
+
 if __name__ == "__main__":
     app()

codeanalyzer/core.py

@@ -9,7 +9,14 @@ from typing import Any, Dict, Optional, Union, List
 import ray
 from codeanalyzer.utils import logger
 from codeanalyzer.schema import PyApplication, PyModule, model_dump_json, model_validate_json
+from codeanalyzer.schema.py_schema import PyCallEdge
+from codeanalyzer.semantic_analysis.call_graph import (
+    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.syntactic_analysis.exceptions import SymbolTableBuilderRayError
 from codeanalyzer.syntactic_analysis.symbol_table_builder import SymbolTableBuilder
@@ -49,7 +56,6 @@ class Codeanalyzer:
 
     def __init__(self, options: AnalysisOptions) -> None:
         self.options = options
-        self.analysis_depth = options.analysis_level
         self.project_dir = Path(options.input).resolve()
         self.skip_tests = options.skip_tests
         self.using_codeql = options.using_codeql
@@ -60,6 +66,7 @@ class 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
@@ -292,6 +299,15 @@ class Codeanalyzer:
 
         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"
@@ -310,19 +326,6 @@ class Codeanalyzer:
             if self.rebuild_analysis or not is_cache_valid():
                 logger.info("Creating new CodeQL database...")
 
-                codeql_in_path = shutil.which("codeql")
-                if codeql_in_path:
-                    self.codeql_bin = Path(codeql_in_path)
-                else:
-                    self.codeql_bin = CodeQLLoader.download_and_extract_codeql(
-                        self.cache_dir / "codeql" / "bin"
-                    )
-
-                if not shutil.which(str(self.codeql_bin)):
-                    raise FileNotFoundError(
-                        f"CodeQL binary not executable: {self.codeql_bin}"
-                    )
-
                 cmd = [
                     str(self.codeql_bin),
                     "database",
@@ -375,8 +378,27 @@ 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)
+        jedi_edges = jedi_call_graph_edges(symbol_table)
+        call_graph = merge_edges(jedi_edges, codeql_edges)
+
         # Recreate pyapplication
-        app = PyApplication.builder().symbol_table(symbol_table).build()
+        app = PyApplication.builder().symbol_table(symbol_table).call_graph(call_graph).build()
         
         # Save to cache
         self._save_analysis_cache(app, cache_file)
@@ -579,7 +601,120 @@ class Codeanalyzer:
         logger.info("✅ Symbol table generation complete.")
         return symbol_table
 
-    def _get_call_graph(self) -> Dict[str, Any]:
-        """Retrieve call graph from CodeQL database."""
-        logger.warning("Call graph extraction not yet implemented.")
-        return {}
+    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,
+        )
+        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
+
+    def _get_call_graph(
+        self,
+        symbol_table: Dict[str, PyModule],
+        augment_sites: bool = False,
+    ) -> List[PyCallEdge]:
+        """Build CodeQL-resolved call edges and optionally augment sites.
+
+        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``.
+
+        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.
+        """
+        if not self.using_codeql or self.db_path is None:
+            return []
+        try:
+            cq = CodeQL(
+                self.project_dir,
+                self.db_path,
+                codeql_bin=self.codeql_bin,
+                codeql_packs_dir=self.codeql_packs_dir,
+            )
+            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 []

codeanalyzer/neo4j/__init__.py

@@ -0,0 +1,46 @@
+################################################################################
+# Copyright IBM Corporation 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""Neo4j output: a pure projection of the :class:`PyApplication` IR to graph rows,
+plus the two writers (cypher snapshot / bolt incremental). Nothing here runs
+unless ``--emit neo4j`` (or ``--emit schema``) is selected.
+"""
+from codeanalyzer.neo4j.bolt import BoltConfig, bolt_writer
+from codeanalyzer.neo4j.catalog import (
+    MARKER_LABELS,
+    NODE_LABELS,
+    REL_TYPES,
+    SCHEMA_VERSION,
+    build_schema_document,
+)
+from codeanalyzer.neo4j.cypher import render_cypher
+from codeanalyzer.neo4j.project import project
+from codeanalyzer.neo4j.rows import EdgeRow, GraphRows, NodeRow
+
+__all__ = [
+    "project",
+    "render_cypher",
+    "bolt_writer",
+    "BoltConfig",
+    "build_schema_document",
+    "SCHEMA_VERSION",
+    "NODE_LABELS",
+    "REL_TYPES",
+    "MARKER_LABELS",
+    "GraphRows",
+    "NodeRow",
+    "EdgeRow",
+]

codeanalyzer/neo4j/bolt.py

@@ -0,0 +1,223 @@
+################################################################################
+# Copyright IBM Corporation 2025
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#       http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+################################################################################
+
+"""The incremental writer: push :class:`GraphRows` into a live Neo4j over Bolt.
+Unlike the snapshot writer, this one reads the DB's current state and updates
+only what changed.
+
+Algorithm (the module subgraph is the unit of idempotent replacement):
+  1. ensure constraints + indexes.
+  2. diff each module's ``content_hash`` against the DB → the set of changed modules.
+  3. per changed module, in a transaction: delete the edges it owned (edges out of
+     its nodes), detach-delete the declarations it no longer emits, then upsert
+     its current nodes.
+  4. upsert edges owned by changed modules (+ the shared edges).
+  5. on a FULL run only, prune modules whose source file vanished.
+
+Nodes are MERGE-upserted, never blindly deleted, so a declaration another
+(unchanged) module still references survives and its incoming edges stay valid.
+``:PyExternal`` / ``:PyPackage`` / ``:PyDecorator`` are shared (no ``_module``) and are
+MERGE-only.
+
+The ``neo4j`` driver is imported lazily so it stays an optional dependency and
+off the default (json) output path entirely.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Dict, List, Optional
+
+from codeanalyzer.neo4j.rows import EdgeRow, GraphRows, NodeRow, chunk
+from codeanalyzer.neo4j.schema import CONSTRAINTS, INDEXES
+from codeanalyzer.utils import logger
+
+DESCENDANTS = "[:PY_DECLARES|PY_HAS_METHOD|PY_HAS_ATTRIBUTE|PY_DECLARES_VAR|PY_HAS_CALLSITE*1..]"
+BATCH = 1000
+
+
+@dataclass
+class BoltConfig:
+    uri: str
+    user: str
+    password: str
+    database: Optional[str] = None
+
+
+def bolt_writer(rows: GraphRows, cfg: BoltConfig, full_run: bool) -> None:
+    try:
+        import neo4j  # noqa: WPS433 (lazy, optional dependency)
+    except ImportError as exc:  # pragma: no cover - exercised only without the extra
+        raise RuntimeError(
+            "The 'neo4j' driver is required for '--emit neo4j --neo4j-uri'. "
+            "Install it with: pip install 'codeanalyzer-python[neo4j]'"
+        ) from exc
+
+    driver = neo4j.GraphDatabase.driver(cfg.uri, auth=(cfg.user, cfg.password))
+    session_kwargs = {"database": cfg.database} if cfg.database else {}
+
+    def session():
+        return driver.session(**session_kwargs)
+
+    try:
+        # 1. schema (DDL runs in its own autocommit transactions).
+        with session() as s:
+            for stmt in [*CONSTRAINTS, *INDEXES]:
+                s.run(stmt)
+
+        # Partition nodes by owning module; shared nodes have no _module.
+        by_module: Dict[str, List[NodeRow]] = {}
+        shared: List[NodeRow] = []
+        module_of: Dict[str, str] = {}  # node value → owning module
+        for n in rows.nodes:
+            m = n.props.get("_module")
+            if isinstance(m, str):
+                by_module.setdefault(m, []).append(n)
+                module_of[n.value] = m
+            else:
+                shared.append(n)
+
+        # 2. diff content_hash.
+        db_hash: Dict[str, Optional[str]] = {}
+        with session() as s:
+            res = s.run("MATCH (m:PyModule) RETURN m.file_key AS k, m.content_hash AS h")
+            for rec in res:
+                db_hash[rec["k"]] = rec["h"]
+        changed = set()
+        for m, nodes in by_module.items():
+            row_hash = _hash_of(nodes, m)
+            if m not in db_hash or row_hash is None or row_hash != db_hash.get(m):
+                changed.add(m)
+        logger.info(
+            f"neo4j(bolt): {len(by_module)} modules ({len(changed)} changed), "
+            f"{len(shared)} shared nodes, {len(rows.edges)} edges"
+        )
+
+        # 3. shared nodes are always upserted (MERGE-only).
+        _upsert_nodes(session, neo4j, shared)
+
+        # 4. per changed module: purge owned edges + vanished decls, then upsert its nodes.
+        for m in changed:
+            nodes = by_module[m]
+            keys = [n.value for n in nodes]
+            with session() as s:
+                def _purge(tx, module=m, node_keys=keys):
+                    tx.run("MATCH (x {_module: $m})-[r]->() DELETE r", m=module)
+                    tx.run(
+                        "MATCH (x {_module: $m}) "
+                        "WHERE NOT coalesce(x.signature, x.id, x.file_key) IN $keys "
+                        "DETACH DELETE x",
+                        m=module,
+                        keys=node_keys,
+                    )
+
+                s.execute_write(_purge)
+            _upsert_nodes(session, neo4j, nodes)
+
+        # 5. upsert edges owned by a changed module (owner = source node's module) or shared.
+        edges = [
+            e
+            for e in rows.edges
+            if module_of.get(e.from_ref.value) is None or module_of.get(e.from_ref.value) in changed
+        ]
+        _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:
+            present = list(by_module.keys())
+            with session() as s:
+                res = s.run(
+                    "MATCH (m:PyModule) WHERE NOT m.file_key IN $present "
+                    f"OPTIONAL MATCH (m)-{DESCENDANTS}->(x) DETACH DELETE x, m "
+                    "RETURN count(m) AS pruned",
+                    present=present,
+                )
+                pruned = res.single()
+                pruned_count = pruned["pruned"] if pruned else 0
+                logger.info(f"neo4j(bolt): pruned {pruned_count} vanished module(s)")
+        else:
+            logger.info(
+                "neo4j(bolt): targeted run — orphan pruning skipped (deleted files not removed)"
+            )
+    finally:
+        driver.close()
+
+
+# ----------------------------------------------------------------------------------------------
+# Batched upserts
+# ----------------------------------------------------------------------------------------------
+
+
+def _upsert_nodes(session, neo4j, nodes: List[NodeRow]) -> None:
+    groups: Dict[str, List[NodeRow]] = {}
+    for n in nodes:
+        groups.setdefault(f"{':'.join(n.labels)}|{n.key_prop}", []).append(n)
+
+    for group in groups.values():
+        labels = group[0].labels
+        key_prop = group[0].key_prop
+        set_labels = f", n:{':'.join(labels[1:])}" if len(labels) > 1 else ""
+        cypher = (
+            f"UNWIND $rows AS row MERGE (n:{labels[0]} {{{key_prop}: row.k}}) "
+            f"SET n += row.p{set_labels}"
+        )
+        for batch in chunk(group, BATCH):
+            payload = [{"k": n.value, "p": _to_params(n.props, neo4j)} for n in batch]
+            with session() as s:
+                s.run(cypher, rows=payload)
+
+
+def _upsert_edges(session, neo4j, edges: List[EdgeRow]) -> None:
+    groups: Dict[str, List[EdgeRow]] = {}
+    for e in edges:
+        key = f"{e.type}|{e.from_ref.label}.{e.from_ref.key_prop}|{e.to_ref.label}.{e.to_ref.key_prop}"
+        groups.setdefault(key, []).append(e)
+
+    for group in groups.values():
+        first = group[0]
+        from_ref, to_ref = first.from_ref, first.to_ref
+        cypher = (
+            f"UNWIND $rows AS row "
+            f"MATCH (a:{from_ref.label} {{{from_ref.key_prop}: row.f}}) "
+            f"MATCH (b:{to_ref.label} {{{to_ref.key_prop}: row.t}}) "
+            f"MERGE (a)-[r:{first.type}]->(b) SET r += row.p"
+        )
+        for batch in chunk(group, BATCH):
+            payload = [
+                {"f": e.from_ref.value, "t": e.to_ref.value, "p": _to_params(e.props, neo4j)}
+                for e in batch
+            ]
+            with session() as s:
+                s.run(cypher, rows=payload)
+
+
+# ----------------------------------------------------------------------------------------------
+# Helpers
+# ----------------------------------------------------------------------------------------------
+
+
+def _hash_of(nodes: List[NodeRow], file_key: str) -> Optional[str]:
+    for n in nodes:
+        if n.labels[0] == "PyModule" and n.value == file_key:
+            h = n.props.get("content_hash")
+            return h if isinstance(h, str) else None
+    return None
+
+
+def _to_params(props, neo4j) -> dict:
+    """Map props to driver params. The Python driver already distinguishes int
+    from float, so unlike the JS driver no integer coercion is needed — this is a
+    straight passthrough kept symmetric with the snapshot writer's shape."""
+    return dict(props)