codeanalyzer-python 0.1.14__py3-none-any.whl → 0.2.1__py3-none-any.whl

codeanalyzer/semantic_analysis/codeql/codeql_analysis.py

@@ -32,6 +32,67 @@ from codeanalyzer.semantic_analysis.codeql.codeql_query_runner import CodeQLQuer
 from codeanalyzer.utils import logger
 
 
+class _CallableResolver:
+    """Maps a CodeQL endpoint ``(file, start_line, name, arity)`` to a Jedi
+    ``PyCallable``.
+
+    Resolution ladder:
+      1. exact ``(abs_path, start_line)`` — the precise join;
+      2. on miss, candidates sharing ``(abs_path, short_name)``: a single
+         candidate is taken directly; otherwise prefer those whose
+         parameter count equals the CodeQL positional arity, then the
+         nearest ``start_line``;
+      3. no name match -> ``None`` (caller row skipped / callee becomes
+         a ghost node).
+
+    Step 2 recovers edges the ``(file, line)`` join silently drops when
+    CodeQL and Jedi disagree on a definition's start line (e.g. decorator
+    handling). Jedi's ``parameters`` counts every declared slot (incl.
+    ``*args``/``**kwargs``/keyword-only) whereas CodeQL's arity is
+    positional only, so the arity filter is exact for plain signatures
+    and otherwise yields to the nearest-line tiebreak.
+    """
+
+    def __init__(self) -> None:
+        self._by_loc: Dict[Tuple[str, int], Any] = {}
+        self._by_name: Dict[Tuple[str, str], List[Any]] = {}
+
+    @staticmethod
+    def _abs(path: str) -> str:
+        try:
+            return str(Path(path).resolve())
+        except (OSError, RuntimeError):
+            return path
+
+    @classmethod
+    def from_symbol_table(
+        cls, symbol_table: Dict[str, PyModule]
+    ) -> "_CallableResolver":
+        resolver = cls()
+        for c in iter_callables_in_symbol_table(symbol_table):
+            abs_path = cls._abs(c.path)
+            resolver._by_loc[(abs_path, c.start_line)] = c
+            resolver._by_name.setdefault((abs_path, c.name), []).append(c)
+        return resolver
+
+    def resolve(
+        self, file: str, start_line: int, name: str, arity: int
+    ) -> Any:
+        exact = self._by_loc.get((file, start_line))
+        if exact is not None:
+            return exact
+        if not name:
+            return None
+        candidates = self._by_name.get((file, name))
+        if not candidates:
+            return None
+        if len(candidates) == 1:
+            return candidates[0]
+        arity_matched = [c for c in candidates if len(c.parameters) == arity]
+        pool = arity_matched or candidates
+        return min(pool, key=lambda c: abs(c.start_line - start_line))
+
+
 class CodeQL:
     """A class for building the application view of a Python application using CodeQL.
 
@@ -99,9 +160,14 @@ class CodeQL:
             # codeql/python-all 7.x — it returns the ``CallNode`` (CFG)
             # whose target was resolved to that ``Value``. Cleaner than
             # poking at ``pointsTo`` directly.
-            "from CallNode call, Function caller, FunctionValue calleeVal",
+            # ``callee`` is bound to the FunctionValue's scope so the
+            # endpoint emits the same Function-level facts (name, arity,
+            # location) the post-processor needs for the name+arity
+            # fallback when the (file, start_line) join misses.
+            "from CallNode call, Function caller, FunctionValue calleeVal, Function callee",
             "where",
             "  call.getScope() = caller and",
+            "  callee = calleeVal.getScope() and",
             "  (",
             # Direct function / bound-method call:  foo()  or  obj.foo()
             "    call = calleeVal.getACall()",
@@ -115,15 +181,20 @@ class CodeQL:
             "    )",
             "  )",
             "select",
-            # --- Caller endpoint --- (joins to PyCallable via file + start_line)
+            # --- Caller endpoint --- (joins to PyCallable: exact by
+            #     (file, start_line), else by (file, name) + arity)
             "  caller.getLocation().getFile().getAbsolutePath(),",
             "  caller.getLocation().getStartLine(),",
             "  caller.getQualifiedName(),",
+            "  caller.getName(),",
+            "  count(caller.getArg(_)),",
             # --- Callee endpoint --- (file/line may live in a library stub;
             #     post-processor classifies as in-source or ghost)
-            "  calleeVal.getScope().getLocation().getFile().getAbsolutePath(),",
-            "  calleeVal.getScope().getLocation().getStartLine(),",
+            "  callee.getLocation().getFile().getAbsolutePath(),",
+            "  callee.getLocation().getStartLine(),",
             "  calleeVal.getQualifiedName(),",
+            "  callee.getName(),",
+            "  count(callee.getArg(_)),",
             # --- Call-site location --- (for PyCallsite augmentation)
             "  call.getLocation().getStartLine(),",
             "  call.getLocation().getStartColumn(),",
@@ -149,9 +220,13 @@ class CodeQL:
                     "caller_file",
                     "caller_start_line",
                     "caller_qname",
+                    "caller_name",
+                    "caller_arity",
                     "callee_file",
                     "callee_start_line",
                     "callee_qname",
+                    "callee_name",
+                    "callee_arity",
                     "call_start_line",
                     "call_start_column",
                     "call_end_line",
@@ -162,24 +237,15 @@ class CodeQL:
         return df
 
     @staticmethod
-    def _build_callable_location_index(
+    def _build_callable_resolver(
         symbol_table: Dict[str, PyModule],
-    ) -> Dict[Tuple[str, int], "PyCallable"]:
-        """Build ``(absolute_file_path, start_line) -> PyCallable`` from Jedi.
+    ) -> _CallableResolver:
+        """Build the endpoint -> ``PyCallable`` resolver from Jedi.
 
         Paths are resolved so they match CodeQL's ``getAbsolutePath()``
         regardless of symlinks or the current working directory.
         """
-        from codeanalyzer.schema.py_schema import PyCallable  # local to avoid cycle
-
-        index: Dict[Tuple[str, int], PyCallable] = {}
-        for c in iter_callables_in_symbol_table(symbol_table):
-            try:
-                abs_path = str(Path(c.path).resolve())
-            except (OSError, RuntimeError):
-                abs_path = c.path
-            index[(abs_path, c.start_line)] = c
-        return index
+        return _CallableResolver.from_symbol_table(symbol_table)
 
     def _iter_resolved_rows(
         self, symbol_table: Dict[str, PyModule]
@@ -194,19 +260,27 @@ class CodeQL:
         df = self._query_call_edges()
         if df.empty:
             return
-        location_index = self._build_callable_location_index(symbol_table)
+        resolver = self._build_callable_resolver(symbol_table)
 
         skipped_unknown_caller = 0
         ghost_callees = 0
         for row in df.itertuples(index=False):
-            caller_key = (row.caller_file, int(row.caller_start_line))
-            caller = location_index.get(caller_key)
+            caller = resolver.resolve(
+                row.caller_file,
+                int(row.caller_start_line),
+                row.caller_name,
+                int(row.caller_arity),
+            )
             if caller is None:
                 skipped_unknown_caller += 1
                 continue
 
-            callee_key = (row.callee_file, int(row.callee_start_line))
-            callee = location_index.get(callee_key)
+            callee = resolver.resolve(
+                row.callee_file,
+                int(row.callee_start_line),
+                row.callee_name,
+                int(row.callee_arity),
+            )
             if callee is not None:
                 target_sig = callee.signature
             else:
@@ -267,20 +341,28 @@ class CodeQL:
         Returns:
             Number of ``PyCallsite`` entries augmented.
         """
-        location_index = self._build_callable_location_index(symbol_table)
+        resolver = self._build_callable_resolver(symbol_table)
         df = self._query_call_edges()
         if df.empty:
             return 0
 
         augmented = 0
         for row in df.itertuples(index=False):
-            caller_key = (row.caller_file, int(row.caller_start_line))
-            caller = location_index.get(caller_key)
+            caller = resolver.resolve(
+                row.caller_file,
+                int(row.caller_start_line),
+                row.caller_name,
+                int(row.caller_arity),
+            )
             if caller is None:
                 continue
 
-            callee_key = (row.callee_file, int(row.callee_start_line))
-            callee = location_index.get(callee_key)
+            callee = resolver.resolve(
+                row.callee_file,
+                int(row.callee_start_line),
+                row.callee_name,
+                int(row.callee_arity),
+            )
             resolved_sig = callee.signature if callee is not None else row.callee_qname
 
             call_start = int(row.call_start_line)

codeanalyzer_python-0.2.1.dist-info/METADATA

@@ -0,0 +1,415 @@
+Metadata-Version: 2.4
+Name: codeanalyzer-python
+Version: 0.2.1
+Summary: Static Analysis on Python source code using Jedi, CodeQL and Treesitter — emits analysis.json or a Neo4j property graph.
+Author-email: Rahul Krishna <i.m.ralk@gmail.com>
+License-File: LICENSE
+License-File: NOTICE
+Requires-Python: >=3.9
+Requires-Dist: jedi<0.20.0,>=0.18.0; python_version < '3.11'
+Requires-Dist: jedi<=0.19.2; python_version >= '3.11'
+Requires-Dist: msgpack<1.0.7,>=1.0.0; python_version < '3.11'
+Requires-Dist: msgpack<2.0.0,>=1.0.7; python_version >= '3.11'
+Requires-Dist: networkx<3.2.0,>=2.6.0; python_version < '3.11'
+Requires-Dist: networkx<4.0.0,>=3.0.0; python_version >= '3.11'
+Requires-Dist: numpy<1.24.0,>=1.21.0; python_version < '3.11'
+Requires-Dist: numpy<2.0.0,>=1.24.0; python_version >= '3.11' and python_version < '3.12'
+Requires-Dist: numpy<2.0.0,>=1.26.0; python_version >= '3.12'
+Requires-Dist: packaging>=25.0
+Requires-Dist: pandas<2.0.0,>=1.3.0; python_version < '3.11'
+Requires-Dist: pandas<3.0.0,>=2.0.0; python_version >= '3.11'
+Requires-Dist: pydantic<2.0.0,>=1.8.0; python_version < '3.11'
+Requires-Dist: pydantic<3.0.0,>=2.0.0; python_version >= '3.11'
+Requires-Dist: ray<3.0.0,>=2.10.0; python_version >= '3.11'
+Requires-Dist: ray==2.0.0; python_version < '3.11'
+Requires-Dist: requests<3.0.0,>=2.20.0; python_version >= '3.11'
+Requires-Dist: rich<14.0.0,>=12.6.0; python_version < '3.11'
+Requires-Dist: rich<15.0.0,>=14.0.0; python_version >= '3.11'
+Requires-Dist: typer<1.0.0,>=0.9.0; python_version < '3.11'
+Requires-Dist: typer<2.0.0,>=0.9.0; python_version >= '3.11'
+Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.11'
+Requires-Dist: typing-extensions<6.0.0,>=4.5.0; python_version >= '3.11'
+Requires-Dist: uv>=0.5.0
+Provides-Extra: neo4j
+Requires-Dist: neo4j<6.0.0,>=5.0.0; extra == 'neo4j'
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+<img src="https://github.com/codellm-devkit/codeanalyzer-python/blob/main/docs/assets/logo.png?raw=true" alt="CodeLLM-DevKit" />
+
+# codeanalyzer-python (`canpy`)
+
+**A Python static-analysis toolkit — the CLDK backend that emits a canonical symbol table and call graph, as `analysis.json` or a Neo4j property graph.**
+
+[![PyPI](https://img.shields.io/pypi/v/codeanalyzer-python?style=for-the-badge&logo=pypi&logoColor=white)](https://pypi.org/project/codeanalyzer-python/)
+[![Python](https://img.shields.io/pypi/pyversions/codeanalyzer-python?style=for-the-badge&logo=python&logoColor=white)](https://pypi.org/project/codeanalyzer-python/)
+[![GitHub release](https://img.shields.io/github/v/release/codellm-devkit/codeanalyzer-python?style=for-the-badge&logo=github&label=GitHub&color=2dba4e)](https://github.com/codellm-devkit/codeanalyzer-python/releases/latest)
+[![Release](https://img.shields.io/github/actions/workflow/status/codellm-devkit/codeanalyzer-python/release.yml?style=for-the-badge&label=release&logo=githubactions&logoColor=white)](https://github.com/codellm-devkit/codeanalyzer-python/actions/workflows/release.yml)
+[![License](https://img.shields.io/badge/License-Apache%202.0-blue?style=for-the-badge)](./LICENSE)
+
+</div>
+
+---
+
+`canpy` is a static analyzer for Python built on [Jedi](https://jedi.readthedocs.io/), with optional
+[CodeQL](https://codeql.github.com/)-resolved call edges and
+[Tree-sitter](https://tree-sitter.github.io/) parsing. It produces the canonical CodeLLM-DevKit
+(CLDK) `analysis.json` — a symbol table plus a call graph — and can project that same analysis into a
+**Neo4j property graph**. It is the Python backend behind
+[CLDK](https://github.com/codellm-devkit/python-sdk), mirroring its
+[TypeScript](https://github.com/codellm-devkit/codeanalyzer-typescript) (`cants`) and
+[Java](https://github.com/codellm-devkit/codeanalyzer-java) siblings.
+
+Every run produces a symbol table **and** a call graph. Edges come from Jedi's lexical resolution by
+default; `--codeql` resolves additional edges (RPC / third-party / dynamically-dispatched targets)
+and merges them with the Jedi-derived edges, also backfilling callees Jedi could not resolve.
+
+## Table of Contents
+
+- [Features](#features)
+- [Installation](#installation)
+  - [Prerequisites](#prerequisites)
+  - [Install via pip (PyPI)](#install-via-pip-pypi)
+  - [Install via shell script](#install-via-shell-script)
+  - [Install via Homebrew](#install-via-homebrew)
+  - [Build from source](#build-from-source)
+- [Usage](#usage)
+  - [Options](#options)
+  - [Examples](#examples)
+- [Output targets](#output-targets)
+  - [`analysis.json` (default)](#analysisjson-default)
+  - [Neo4j graph](#neo4j-graph)
+  - [Schema contract](#schema-contract)
+- [Development](#development)
+- [License](#license)
+
+## Features
+
+- **Symbol table** — modules, classes, functions, methods, variables, decorators, imports, and
+  docstrings, with precise source spans.
+- **Call graph** — Jedi's lexical resolver by default, with optional **CodeQL**-resolved edges
+  (`--codeql`) for RPC / third-party / dynamically-dispatched targets, merged with the Jedi edges;
+  CodeQL also backfills callees Jedi could not resolve.
+- **Neo4j output** — project the analysis into a labeled property graph: a self-contained
+  `graph.cypher` snapshot, or an **incremental** push to a live database over Bolt.
+- **Versioned schema** — a machine-readable, version-stamped Neo4j schema contract (`--emit schema`),
+  checked in as `schema.neo4j.json` and shipped with every release.
+- **Incremental cache** — per-file results are cached under `.codeanalyzer`; `--lazy` (default)
+  reuses them, `--eager` forces a clean rebuild. `--ray` distributes the work across cores.
+- **Compact output** — canonical `analysis.json`, or binary `analysis.msgpack` for smaller artifacts.
+
+## Installation
+
+### Prerequisites
+
+- **Python 3.10 or newer.**
+- A C toolchain and the `venv` / development headers — the analyzer builds an isolated virtual
+  environment per project (via Python's `venv`) so Jedi can resolve types and imports:
+
+  ```sh
+  # Ubuntu / Debian
+  sudo apt install python3-venv python3-dev build-essential
+
+  # Fedora / RHEL / CentOS
+  sudo dnf group install "Development Tools" && sudo dnf install python3-venv python3-devel
+
+  # macOS
+  xcode-select --install
+  ```
+
+### Install via pip (PyPI)
+
+```sh
+pip install codeanalyzer-python
+canpy --help
+```
+
+For the optional **live Neo4j push** (`--emit neo4j --neo4j-uri …`), install the `neo4j` extra:
+
+```sh
+pip install 'codeanalyzer-python[neo4j]'
+```
+
+### Install via shell script
+
+Install the CLI as an isolated tool with the one-line installer (provisions via uv / pipx / pip):
+
+```sh
+curl --proto '=https' --tlsv1.2 -LsSf https://github.com/codellm-devkit/codeanalyzer-python/releases/latest/download/canpy-installer.sh | sh
+```
+
+### Install via Homebrew
+
+```sh
+brew install codellm-devkit/tap/codeanalyzer-python
+```
+
+The formula depends on [uv](https://docs.astral.sh/uv/) and installs `canpy` as an isolated,
+version-pinned uv tool (the package and its dependencies are resolved and cached on first run).
+
+### Build from source
+
+This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
+
+```sh
+git clone https://github.com/codellm-devkit/codeanalyzer-python
+cd codeanalyzer-python
+uv sync --all-groups
+uv run canpy --help
+```
+
+## Usage
+
+```sh
+canpy --input /path/to/python/project
+```
+
+With no `--output`, the analysis is printed to stdout as compact JSON; with `--output <dir>` it is
+written to `analysis.json` (or `graph.cypher` for `--emit neo4j`, or `analysis.msgpack` with
+`--format msgpack`) in that directory.
+
+### Options
+
+<!-- BEGIN canpy-help -->
+
+```text
+$ canpy --help
+
+ Usage: canpy [OPTIONS] COMMAND [ARGS]...
+
+ Static Analysis on Python source code using Jedi, CodeQL and Tree sitter.
+
+╭─ Options ────────────────────────────────────────────────────────────────────╮
+│ --input           -i                     PATH              Path to the       │
+│                                                            project root      │
+│                                                            directory (not    │
+│                                                            required for      │
+│                                                            --emit schema).   │
+│ --output          -o                     PATH              Output directory  │
+│                                                            for artifacts.    │
+│ --format          -f                     [json|msgpack]    Output format for │
+│                                                            --emit json: json │
+│                                                            or msgpack.       │
+│                                                            [default: json]   │
+│ --emit                                   [json|neo4j|sche  Output target:    │
+│                                          ma]               json              │
+│                                                            (analysis.json,   │
+│                                                            default) | neo4j  │
+│                                                            (graph.cypher or  │
+│                                                            live Bolt push) | │
+│                                                            schema (the Neo4j │
+│                                                            schema.json       │
+│                                                            contract).        │
+│                                                            [default: json]   │
+│ --app-name                               TEXT              Logical           │
+│                                                            application name  │
+│                                                            for the graph     │
+│                                                            :PyApplication    │
+│                                                            anchor (default:  │
+│                                                            input dir name).  │
+│ --neo4j-uri                              TEXT              Push the graph to │
+│                                                            a live Neo4j over │
+│                                                            Bolt              │
+│                                                            (incremental);    │
+│                                                            omit to write     │
+│                                                            graph.cypher.     │
+│                                                            [env var:         │
+│                                                            NEO4J_URI]        │
+│ --neo4j-user                             TEXT              Neo4j username.   │
+│                                                            [env var:         │
+│                                                            NEO4J_USERNAME]   │
+│                                                            [default: neo4j]  │
+│ --neo4j-password                         TEXT              Neo4j password.   │
+│                                                            Prefer the env    │
+│                                                            var over the flag │
+│                                                            (the flag is      │
+│                                                            visible in shell  │
+│                                                            history / process │
+│                                                            list).            │
+│                                                            [env var:         │
+│                                                            NEO4J_PASSWORD]   │
+│                                                            [default: neo4j]  │
+│ --neo4j-database                         TEXT              Neo4j database    │
+│                                                            name (default:    │
+│                                                            server default).  │
+│                                                            [env var:         │
+│                                                            NEO4J_DATABASE]   │
+│ --codeql              --no-codeql                          Enable            │
+│                                                            CodeQL-based      │
+│                                                            analysis.         │
+│                                                            [default:         │
+│                                                            no-codeql]        │
+│ --ray                 --no-ray                             Enable Ray for    │
+│                                                            distributed       │
+│                                                            analysis.         │
+│                                                            [default: no-ray] │
+│ --eager               --lazy                               Enable eager or   │
+│                                                            lazy analysis.    │
+│                                                            Defaults to lazy. │
+│                                                            [default: lazy]   │
+│ --skip-tests          --include-tests                      Skip test files   │
+│                                                            in analysis.      │
+│                                                            [default:         │
+│                                                            skip-tests]       │
+│ --no-venv             --venv                               Skip virtualenv   │
+│                                                            creation and      │
+│                                                            dependency        │
+│                                                            installation;     │
+│                                                            resolve imports   │
+│                                                            against the       │
+│                                                            ambient Python    │
+│                                                            environment       │
+│                                                            instead.          │
+│                                                            [default: venv]   │
+│ --file-name                              PATH              Analyze only the  │
+│                                                            specified file    │
+│                                                            (relative to      │
+│                                                            input directory). │
+│ --cache-dir       -c                     PATH              Directory to      │
+│                                                            store analysis    │
+│                                                            cache. Defaults   │
+│                                                            to                │
+│                                                            '.codeanalyzer'   │
+│                                                            in the input      │
+│                                                            directory.        │
+│ --clear-cache         --keep-cache                         Clear cache after │
+│                                                            analysis. By      │
+│                                                            default, cache is │
+│                                                            retained.         │
+│                                                            [default:         │
+│                                                            keep-cache]       │
+│                   -v                     INTEGER           Increase          │
+│                                                            verbosity: -v,    │
+│                                                            -vv, -vvv         │
+│                                                            [default: 0]      │
+│ --help                                                     Show this message │
+│                                                            and exit.         │
+╰──────────────────────────────────────────────────────────────────────────────╯
+```
+
+<!-- END canpy-help -->
+
+### Examples
+
+1. **Basic analysis to stdout, or to a file:**
+   ```sh
+   canpy --input ./my-python-project                        # compact JSON on stdout
+   canpy --input ./my-python-project --output ./out         # → ./out/analysis.json
+   ```
+
+2. **Binary output (msgpack):**
+   ```sh
+   canpy --input ./my-python-project --output ./out --format msgpack   # → ./out/analysis.msgpack
+   ```
+
+3. **Resolve extra call edges with CodeQL:**
+   ```sh
+   canpy --input ./my-python-project --codeql
+   ```
+   By default, edges come from Jedi's lexical analysis. Adding `--codeql` resolves additional edges
+   (including RPC / third-party / dynamically-dispatched targets) and merges them with the
+   Jedi-derived edges; CodeQL also backfills resolved callees Jedi could not resolve. CodeQL
+   integration is experimental; the CLI is downloaded into `<cache_dir>/codeql/` on first use.
+
+4. **Emit a Neo4j snapshot, or push to a live database:**
+   ```sh
+   canpy --input ./my-python-project --emit neo4j --output ./out   # → ./out/graph.cypher
+   canpy --input ./my-python-project --emit neo4j \
+     --neo4j-uri bolt://localhost:7687 --neo4j-user neo4j --neo4j-password secret
+   ```
+
+5. **Emit the Neo4j schema contract:**
+   ```sh
+   canpy --emit schema                   # print schema.json to stdout (no project needed)
+   canpy --emit schema --output ./out    # → ./out/schema.json
+   ```
+
+6. **Force a clean rebuild with a custom cache directory:**
+   ```sh
+   canpy --input ./my-python-project --eager --cache-dir /path/to/custom-cache
+   ```
+
+## Output targets
+
+`canpy` builds one analysis in memory and can emit it three ways (`--emit`):
+
+### `analysis.json` (default)
+
+A `PyApplication` document — the canonical CLDK contract:
+
+```jsonc
+{
+  "symbol_table": { /* file path → module (classes, functions, variables, imports, …) */ },
+  "call_graph":   [ /* CALL_DEP edges: { source, target, weight, provenance } keyed by callable signature */ ]
+}
+```
+
+By default this is printed to stdout in JSON; with `--output` it is written to `analysis.json` (or
+`analysis.msgpack` with `--format msgpack`, a more compact binary format).
+
+### Neo4j graph
+
+`--emit neo4j` projects the same analysis into a labeled property graph. Every node label is
+`Py`-prefixed and every relationship type is `PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`) so multiple
+language analyzers can share one database without label or relationship-type collisions. Declarations
+are keyed by their signature under a shared `:PySymbol` label; calls, imports, inheritance,
+decorators, and call sites are relationships:
+
+- **Without `--neo4j-uri`** — writes a self-contained `graph.cypher` (constraints + indexes, a scoped
+  wipe, then batched `MERGE`s). Load it with `cypher-shell < graph.cypher`. Needs no extra
+  dependencies.
+- **With `--neo4j-uri`** — pushes to a live Neo4j over Bolt **incrementally**: only modules whose
+  content hash changed are rewritten, and on a full run modules whose source file vanished are
+  pruned. Requires the `neo4j` extra. Every graph carries a `schema_version` on its `:PyApplication`
+  node.
+
+Call-graph endpoints that aren't present in the symbol table (third-party / framework / RPC targets)
+are materialized as `:PyExternal` ghost nodes, mirroring the analyzer's own ghost-node behaviour.
+
+The connection options also read from the standard Neo4j environment variables — `NEO4J_URI`,
+`NEO4J_USERNAME`, `NEO4J_PASSWORD`, `NEO4J_DATABASE` — when the corresponding flag is omitted (an
+explicit flag wins). Prefer the env var for the password so it doesn't land in shell history or the
+process list:
+
+```sh
+export NEO4J_URI=bolt://localhost:7687
+export NEO4J_PASSWORD=secret
+canpy -i ./my-project --emit neo4j     # credentials picked up from the environment
+```
+
+### Schema contract
+
+`--emit schema` writes the machine-readable, version-stamped Neo4j schema (`schema.json`: node labels,
+relationships, properties, constraints, and indexes). It needs no project and is checked into the repo
+as `schema.neo4j.json` and bundled in every release as a GitHub Release asset, so a consumer can
+validate producer/consumer compatibility without invoking the tool. The shape of the contract matches
+the [`codeanalyzer-typescript`](https://github.com/codellm-devkit/codeanalyzer-typescript) backend.
+
+A UML of the `analysis.json` schema (the `PyApplication` containment tree) is checked in as
+[`schema-uml.drawio`](./schema-uml.drawio), and the property-graph schema as
+[`neo4j-schema.drawio`](./neo4j-schema.drawio).
+
+## Development
+
+This project uses [uv](https://docs.astral.sh/uv/).
+
+```sh
+uv sync --all-groups
+uv run canpy --input /path/to/project           # run from source
+uv run canpy --emit schema > schema.neo4j.json  # regenerate the checked-in schema contract
+uv run python scripts/update_readme.py          # regenerate the canpy --help block above
+uv run pytest                                   # run the test suite
+```
+
+The Neo4j schema-conformance test always runs. The Neo4j **bolt** integration test spins up a real
+Neo4j via [Testcontainers](https://testcontainers.com/) and is **opt-in** — it needs a container
+runtime (Docker or Podman) and is enabled with an environment variable:
+
+```sh
+RUN_CONTAINER_TESTS=1 uv run pytest test/test_neo4j_bolt.py -s
+```
+
+## License
+
+Apache 2.0 — see [LICENSE](./LICENSE).

codeanalyzer_python-0.2.1.dist-info/RECORD

@@ -0,0 +1,39 @@
+codeanalyzer/__init__.py,sha256=BZ3Kuwl-F_F-8H8cepLnVJ4Ku4NNUjjqg0Y6ujPQSsI,108
+codeanalyzer/__main__.py,sha256=UHSBihqrJVQrx-ldp4HBMJQAUouDsiuEakyYt6oWVTw,8444
+codeanalyzer/core.py,sha256=O7hW2Y65hzdxR3Rk1Gt2Mwb63pBGZ-zCk3gyAxb3CRM,33976
+codeanalyzer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codeanalyzer/config/__init__.py,sha256=9XBxAn1oWGRuhg3bEBUuVGs3hFNXEAKrr-Ce7tq9a2k,61
+codeanalyzer/config/config.py,sha256=ZiKzc5uEUCIvih58-6BDtLLI1hPij41wGQjBcj9KNQM,188
+codeanalyzer/jedi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codeanalyzer/jedi/jedi.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codeanalyzer/neo4j/__init__.py,sha256=AcbFNAMuXwkMFWH4h_HCmla6PCKTF3Xe5yNqg8F_kYk,1575
+codeanalyzer/neo4j/bolt.py,sha256=-IFDb_d67IkGwxvmmbLNI6AvSQHY-XsutI3szibWidw,9635
+codeanalyzer/neo4j/catalog.py,sha256=VQWtwcueck2Ug_cu8sitvAoRwbVZ-6KRiexRN8q1Wak,7418
+codeanalyzer/neo4j/cypher.py,sha256=2zIWXA1AADrwCMhSTeqKjEXRgBjbob6o3bme_cwLu0s,5024
+codeanalyzer/neo4j/emit.py,sha256=WtCndN6mA6PIzfzdgv9Xc5S5WP4rHUXCtB_r3G16rkg,3101
+codeanalyzer/neo4j/project.py,sha256=2GDHkFjmWibrpMaOiDMo21K6Lnj3aefl2QPCM7ANA7g,12485
+codeanalyzer/neo4j/rows.py,sha256=5xI3X-l-vwPe_gmKYUg7VuUQARcOlVAZnGmiQr9QyRk,7326
+codeanalyzer/neo4j/schema.py,sha256=5xz8cZVuL73GAF-vs9QtN2TuKxIty0rHEe68nwQmLTY,2136
+codeanalyzer/options/__init__.py,sha256=FNBGxdnESayUb0wEs395MKIJxoWIX7bp-FaLDP6qYUw,123
+codeanalyzer/options/options.py,sha256=JfHGU1NwXL_XCkQQsxMM94iuRL96J8kOYAa0pV5bmBM,1275
+codeanalyzer/schema/__init__.py,sha256=cLPjvowrnz8xzi7tZAsKQeIOjdOKRGHy4I7wbG0jHk8,2024
+codeanalyzer/schema/py_schema.py,sha256=sWJ-hWTYpd02Am1548zNEsp5XKeK3B5MbWTqsXAMC_8,12316
+codeanalyzer/semantic_analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+codeanalyzer/semantic_analysis/call_graph.py,sha256=3hgLA1sL1YFQa4fzUz_ifVbLs1I9V2QFe7ldwN18mcg,10323
+codeanalyzer/semantic_analysis/codeql/__init__.py,sha256=ODMkdGvs3ebJdfIZle8T4VcHoCBhH_ZehWuWFpNh3NI,1022
+codeanalyzer/semantic_analysis/codeql/codeql_analysis.py,sha256=Z5E7Pj__eYsYSWFteOG1B4RTlH4huhEaPAOmTquzCBQ,15434
+codeanalyzer/semantic_analysis/codeql/codeql_exceptions.py,sha256=PnJOasW9rP68SEX158jSqQFdqjW_Q_Fx3vbH6vNiCQs,474
+codeanalyzer/semantic_analysis/codeql/codeql_loader.py,sha256=XFjTx6ERRipzTguwHzSS5BTI6Nzf95fcdK3nLxqHARs,3599
+codeanalyzer/semantic_analysis/codeql/codeql_query_runner.py,sha256=Zr5NPIpQjm8W-up-js8f3Q7Y9YYfSfUalm6yxtdTC90,7768
+codeanalyzer/syntactic_analysis/__init__.py,sha256=EUQkJEh6wHjWx2qTTKbTbUgwSbfKeNieKHNy7RknVXA,476
+codeanalyzer/syntactic_analysis/exceptions.py,sha256=whs_n0vIu655Jkk1a7iOoXY6iIca4pZqJnU40V9Ejaw,537
+codeanalyzer/syntactic_analysis/symbol_table_builder.py,sha256=zmHFt8pN50jG-Ex4fnisvbLmn1XaW05jwbV_xSG4qfU,38177
+codeanalyzer/utils/__init__.py,sha256=hC6VWdR5rerSqBxzu9KQHTASWqwrrYJv-CMDwrTlzkc,137
+codeanalyzer/utils/logging.py,sha256=0vTkGSl5EZN8yhhWa_5Mrn1n_twRCSW53rNwjzQ9RbI,601
+codeanalyzer/utils/progress_bar.py,sha256=ZHJzGiCo5q4dyXq4CtsrJeq9Ip7sD84T3yZjNX7TBys,2443
+codeanalyzer_python-0.2.1.dist-info/METADATA,sha256=UN2Bnyh-t1B3EzvQk708_n86Cp5kAOvyxcLTrk26g5k,22430
+codeanalyzer_python-0.2.1.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+codeanalyzer_python-0.2.1.dist-info/entry_points.txt,sha256=v4Vux0Nnx7sOntVk_CH7W9RX6SkIkvR1FQYq73oVlCQ,105
+codeanalyzer_python-0.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+codeanalyzer_python-0.2.1.dist-info/licenses/NOTICE,sha256=YU0Z9NDWqKY-2jfFcbxeZ6fbnzz0oZeKmnUcO8a-bcQ,901
+codeanalyzer_python-0.2.1.dist-info/RECORD,,