codeanalyzer-python 0.2.0__py3-none-any.whl → 0.3.0__py3-none-any.whl
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- codeanalyzer/__main__.py +99 -6
- codeanalyzer/core.py +192 -215
- codeanalyzer/neo4j/bolt.py +13 -2
- codeanalyzer/neo4j/catalog.py +2 -2
- codeanalyzer/neo4j/project.py +18 -10
- codeanalyzer/neo4j/rows.py +10 -5
- codeanalyzer/options/__init__.py +2 -2
- codeanalyzer/options/options.py +21 -1
- codeanalyzer/schema/__init__.py +2 -0
- codeanalyzer/schema/py_schema.py +16 -1
- codeanalyzer/semantic_analysis/call_graph.py +24 -3
- codeanalyzer/semantic_analysis/pycg/__init__.py +20 -0
- codeanalyzer/semantic_analysis/pycg/pycg_analysis.py +1054 -0
- codeanalyzer/semantic_analysis/{codeql/__init__.py → pycg/pycg_exceptions.py} +5 -8
- codeanalyzer/semantic_analysis/pycg/shard_planner.py +401 -0
- codeanalyzer/utils/logging.py +5 -2
- codeanalyzer/utils/progress_bar.py +15 -7
- codeanalyzer_python-0.3.0.dist-info/METADATA +550 -0
- codeanalyzer_python-0.3.0.dist-info/RECORD +38 -0
- codeanalyzer/semantic_analysis/codeql/codeql_analysis.py +0 -382
- codeanalyzer/semantic_analysis/codeql/codeql_exceptions.py +0 -12
- codeanalyzer/semantic_analysis/codeql/codeql_loader.py +0 -91
- codeanalyzer/semantic_analysis/codeql/codeql_query_runner.py +0 -185
- codeanalyzer_python-0.2.0.dist-info/METADATA +0 -393
- codeanalyzer_python-0.2.0.dist-info/RECORD +0 -39
- {codeanalyzer_python-0.2.0.dist-info → codeanalyzer_python-0.3.0.dist-info}/WHEEL +0 -0
- {codeanalyzer_python-0.2.0.dist-info → codeanalyzer_python-0.3.0.dist-info}/entry_points.txt +0 -0
- {codeanalyzer_python-0.2.0.dist-info → codeanalyzer_python-0.3.0.dist-info}/licenses/LICENSE +0 -0
- {codeanalyzer_python-0.2.0.dist-info → codeanalyzer_python-0.3.0.dist-info}/licenses/NOTICE +0 -0
|
@@ -0,0 +1,550 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: codeanalyzer-python
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Static Analysis on Python source code using Jedi, CodeQL and Treesitter — emits analysis.json or a Neo4j property graph.
|
|
5
|
+
Author-email: Rahul Krishna <i.m.ralk@gmail.com>
|
|
6
|
+
License-File: LICENSE
|
|
7
|
+
License-File: NOTICE
|
|
8
|
+
Requires-Python: >=3.9
|
|
9
|
+
Requires-Dist: jedi<0.20.0,>=0.18.0; python_version < '3.11'
|
|
10
|
+
Requires-Dist: jedi<=0.19.2; python_version >= '3.11'
|
|
11
|
+
Requires-Dist: msgpack<1.0.7,>=1.0.0; python_version < '3.11'
|
|
12
|
+
Requires-Dist: msgpack<2.0.0,>=1.0.7; python_version >= '3.11'
|
|
13
|
+
Requires-Dist: networkx<3.2.0,>=2.6.0; python_version < '3.11'
|
|
14
|
+
Requires-Dist: networkx<4.0.0,>=3.0.0; python_version >= '3.11'
|
|
15
|
+
Requires-Dist: numpy<1.24.0,>=1.21.0; python_version < '3.11'
|
|
16
|
+
Requires-Dist: numpy<2.0.0,>=1.24.0; python_version >= '3.11' and python_version < '3.12'
|
|
17
|
+
Requires-Dist: numpy<2.0.0,>=1.26.0; python_version >= '3.12'
|
|
18
|
+
Requires-Dist: packaging>=25.0
|
|
19
|
+
Requires-Dist: pandas<2.0.0,>=1.3.0; python_version < '3.11'
|
|
20
|
+
Requires-Dist: pandas<3.0.0,>=2.0.0; python_version >= '3.11'
|
|
21
|
+
Requires-Dist: pycg>=0.0.6
|
|
22
|
+
Requires-Dist: pydantic<2.0.0,>=1.8.0; python_version < '3.11'
|
|
23
|
+
Requires-Dist: pydantic<3.0.0,>=2.0.0; python_version >= '3.11'
|
|
24
|
+
Requires-Dist: ray<3.0.0,>=2.10.0; python_version >= '3.11'
|
|
25
|
+
Requires-Dist: ray==2.0.0; python_version < '3.11'
|
|
26
|
+
Requires-Dist: requests<3.0.0,>=2.20.0; python_version >= '3.11'
|
|
27
|
+
Requires-Dist: rich<14.0.0,>=12.6.0; python_version < '3.11'
|
|
28
|
+
Requires-Dist: rich<15.0.0,>=14.0.0; python_version >= '3.11'
|
|
29
|
+
Requires-Dist: typer<1.0.0,>=0.9.0; python_version < '3.11'
|
|
30
|
+
Requires-Dist: typer<2.0.0,>=0.9.0; python_version >= '3.11'
|
|
31
|
+
Requires-Dist: typing-extensions<5.0.0,>=4.0.0; python_version < '3.11'
|
|
32
|
+
Requires-Dist: typing-extensions<6.0.0,>=4.5.0; python_version >= '3.11'
|
|
33
|
+
Requires-Dist: uv>=0.5.0
|
|
34
|
+
Provides-Extra: neo4j
|
|
35
|
+
Requires-Dist: neo4j<6.0.0,>=5.0.0; extra == 'neo4j'
|
|
36
|
+
Description-Content-Type: text/markdown
|
|
37
|
+
|
|
38
|
+
<div align="center">
|
|
39
|
+
|
|
40
|
+
<img src="https://github.com/codellm-devkit/codeanalyzer-python/blob/main/docs/assets/logo.png?raw=true" alt="CodeLLM-DevKit" />
|
|
41
|
+
|
|
42
|
+
# codeanalyzer-python (`canpy`)
|
|
43
|
+
|
|
44
|
+
**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.**
|
|
45
|
+
|
|
46
|
+
[](https://pypi.org/project/codeanalyzer-python/)
|
|
47
|
+
[](https://github.com/codellm-devkit/codeanalyzer-python/releases/latest)
|
|
48
|
+
[](https://github.com/codellm-devkit/codeanalyzer-python/actions/workflows/release.yml)
|
|
49
|
+
[](./LICENSE)
|
|
50
|
+
|
|
51
|
+
</div>
|
|
52
|
+
|
|
53
|
+
---
|
|
54
|
+
|
|
55
|
+
`canpy` is a static analyzer for Python built on [Jedi](https://jedi.readthedocs.io/), with optional
|
|
56
|
+
[CodeQL](https://codeql.github.com/)-resolved call edges and
|
|
57
|
+
[Tree-sitter](https://tree-sitter.github.io/) parsing. It produces the canonical CodeLLM-DevKit
|
|
58
|
+
(CLDK) `analysis.json` — a symbol table plus a call graph — and can project that same analysis into a
|
|
59
|
+
**Neo4j property graph**. It is the Python backend behind
|
|
60
|
+
[CLDK](https://github.com/codellm-devkit/python-sdk), mirroring its
|
|
61
|
+
[TypeScript](https://github.com/codellm-devkit/codeanalyzer-typescript) (`cants`) and
|
|
62
|
+
[Java](https://github.com/codellm-devkit/codeanalyzer-java) siblings.
|
|
63
|
+
|
|
64
|
+
Every run produces a symbol table **and** a call graph. Edges come from Jedi's lexical resolution by
|
|
65
|
+
default; `--codeql` resolves additional edges (RPC / third-party / dynamically-dispatched targets)
|
|
66
|
+
and merges them with the Jedi-derived edges, also backfilling callees Jedi could not resolve.
|
|
67
|
+
|
|
68
|
+
## Table of Contents
|
|
69
|
+
|
|
70
|
+
- [Features](#features)
|
|
71
|
+
- [Installation](#installation)
|
|
72
|
+
- [Prerequisites](#prerequisites)
|
|
73
|
+
- [Install via pip (PyPI)](#install-via-pip-pypi)
|
|
74
|
+
- [Install via shell script](#install-via-shell-script)
|
|
75
|
+
- [Install via Homebrew](#install-via-homebrew)
|
|
76
|
+
- [Build from source](#build-from-source)
|
|
77
|
+
- [Usage](#usage)
|
|
78
|
+
- [Options](#options)
|
|
79
|
+
- [Examples](#examples)
|
|
80
|
+
- [Output targets](#output-targets)
|
|
81
|
+
- [`analysis.json` (default)](#analysisjson-default)
|
|
82
|
+
- [Neo4j graph](#neo4j-graph)
|
|
83
|
+
- [Schema contract](#schema-contract)
|
|
84
|
+
- [Development](#development)
|
|
85
|
+
- [License](#license)
|
|
86
|
+
|
|
87
|
+
## Features
|
|
88
|
+
|
|
89
|
+
- **Symbol table** — modules, classes, functions, methods, variables, decorators, imports, and
|
|
90
|
+
docstrings, with precise source spans.
|
|
91
|
+
- **Call graph** — Jedi's lexical resolver by default, with optional **CodeQL**-resolved edges
|
|
92
|
+
(`--codeql`) for RPC / third-party / dynamically-dispatched targets, merged with the Jedi edges;
|
|
93
|
+
CodeQL also backfills callees Jedi could not resolve.
|
|
94
|
+
- **Neo4j output** — project the analysis into a labeled property graph: a self-contained
|
|
95
|
+
`graph.cypher` snapshot, or an **incremental** push to a live database over Bolt.
|
|
96
|
+
- **Versioned schema** — a machine-readable, version-stamped Neo4j schema contract (`--emit schema`),
|
|
97
|
+
checked in as `schema.neo4j.json` and shipped with every release.
|
|
98
|
+
- **Incremental cache** — per-file results are cached under `.codeanalyzer`; `--lazy` (default)
|
|
99
|
+
reuses them, `--eager` forces a clean rebuild. `--ray` distributes the work across cores.
|
|
100
|
+
- **Compact output** — canonical `analysis.json`, or binary `analysis.msgpack` for smaller artifacts.
|
|
101
|
+
|
|
102
|
+
## Installation
|
|
103
|
+
|
|
104
|
+
### Prerequisites
|
|
105
|
+
|
|
106
|
+
- **Python 3.10 or newer.**
|
|
107
|
+
- A C toolchain and the `venv` / development headers — the analyzer builds an isolated virtual
|
|
108
|
+
environment per project (via Python's `venv`) so Jedi can resolve types and imports:
|
|
109
|
+
|
|
110
|
+
```sh
|
|
111
|
+
# Ubuntu / Debian
|
|
112
|
+
sudo apt install python3-venv python3-dev build-essential
|
|
113
|
+
|
|
114
|
+
# Fedora / RHEL / CentOS
|
|
115
|
+
sudo dnf group install "Development Tools" && sudo dnf install python3-venv python3-devel
|
|
116
|
+
|
|
117
|
+
# macOS
|
|
118
|
+
xcode-select --install
|
|
119
|
+
```
|
|
120
|
+
|
|
121
|
+
### Install via pip (PyPI)
|
|
122
|
+
|
|
123
|
+
```sh
|
|
124
|
+
pip install codeanalyzer-python
|
|
125
|
+
canpy --help
|
|
126
|
+
```
|
|
127
|
+
|
|
128
|
+
For the optional **live Neo4j push** (`--emit neo4j --neo4j-uri …`), install the `neo4j` extra:
|
|
129
|
+
|
|
130
|
+
```sh
|
|
131
|
+
pip install 'codeanalyzer-python[neo4j]'
|
|
132
|
+
```
|
|
133
|
+
|
|
134
|
+
### Install via shell script
|
|
135
|
+
|
|
136
|
+
Install the CLI as an isolated tool with the one-line installer (provisions via uv / pipx / pip):
|
|
137
|
+
|
|
138
|
+
```sh
|
|
139
|
+
curl --proto '=https' --tlsv1.2 -LsSf https://github.com/codellm-devkit/codeanalyzer-python/releases/latest/download/canpy-installer.sh | sh
|
|
140
|
+
```
|
|
141
|
+
|
|
142
|
+
### Install via Homebrew
|
|
143
|
+
|
|
144
|
+
```sh
|
|
145
|
+
brew install codellm-devkit/tap/codeanalyzer-python
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
The formula depends on [uv](https://docs.astral.sh/uv/) and installs `canpy` as an isolated,
|
|
149
|
+
version-pinned uv tool (the package and its dependencies are resolved and cached on first run).
|
|
150
|
+
|
|
151
|
+
### Build from source
|
|
152
|
+
|
|
153
|
+
This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
|
|
154
|
+
|
|
155
|
+
```sh
|
|
156
|
+
git clone https://github.com/codellm-devkit/codeanalyzer-python
|
|
157
|
+
cd codeanalyzer-python
|
|
158
|
+
uv sync --all-groups
|
|
159
|
+
uv run canpy --help
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
## Usage
|
|
163
|
+
|
|
164
|
+
```sh
|
|
165
|
+
canpy --input /path/to/python/project
|
|
166
|
+
```
|
|
167
|
+
|
|
168
|
+
With no `--output`, the analysis is printed to stdout as compact JSON; with `--output <dir>` it is
|
|
169
|
+
written to `analysis.json` (or `graph.cypher` for `--emit neo4j`, or `analysis.msgpack` with
|
|
170
|
+
`--format msgpack`) in that directory.
|
|
171
|
+
|
|
172
|
+
### Options
|
|
173
|
+
|
|
174
|
+
<!-- BEGIN canpy-help -->
|
|
175
|
+
|
|
176
|
+
```text
|
|
177
|
+
$ canpy --help
|
|
178
|
+
|
|
179
|
+
Usage: canpy [OPTIONS] COMMAND [ARGS]...
|
|
180
|
+
|
|
181
|
+
Static Analysis on Python source code using Jedi, PyCG and Tree sitter.
|
|
182
|
+
|
|
183
|
+
╭─ Options ────────────────────────────────────────────────────────────────────╮
|
|
184
|
+
│ --input -i PATH Path to the │
|
|
185
|
+
│ project root │
|
|
186
|
+
│ directory (not │
|
|
187
|
+
│ required for │
|
|
188
|
+
│ --emit schema). │
|
|
189
|
+
│ --output -o PATH Output directory │
|
|
190
|
+
│ for artifacts. │
|
|
191
|
+
│ --format -f [json|msgpack] Output format │
|
|
192
|
+
│ for --emit json: │
|
|
193
|
+
│ json or msgpack. │
|
|
194
|
+
│ [default: json] │
|
|
195
|
+
│ --emit [json|neo4j|sche Output target: │
|
|
196
|
+
│ ma] json │
|
|
197
|
+
│ (analysis.json, │
|
|
198
|
+
│ default) | neo4j │
|
|
199
|
+
│ (graph.cypher or │
|
|
200
|
+
│ live Bolt push) │
|
|
201
|
+
│ | schema (the │
|
|
202
|
+
│ Neo4j │
|
|
203
|
+
│ schema.json │
|
|
204
|
+
│ contract). │
|
|
205
|
+
│ [default: json] │
|
|
206
|
+
│ --app-name TEXT Logical │
|
|
207
|
+
│ application name │
|
|
208
|
+
│ for the graph │
|
|
209
|
+
│ :PyApplication │
|
|
210
|
+
│ anchor (default: │
|
|
211
|
+
│ input dir name). │
|
|
212
|
+
│ --neo4j-uri TEXT Push the graph │
|
|
213
|
+
│ to a live Neo4j │
|
|
214
|
+
│ over Bolt │
|
|
215
|
+
│ (incremental); │
|
|
216
|
+
│ omit to write │
|
|
217
|
+
│ graph.cypher. │
|
|
218
|
+
│ [env var: │
|
|
219
|
+
│ NEO4J_URI] │
|
|
220
|
+
│ --neo4j-user TEXT Neo4j username. │
|
|
221
|
+
│ [env var: │
|
|
222
|
+
│ NEO4J_USERNAME] │
|
|
223
|
+
│ [default: neo4j] │
|
|
224
|
+
│ --neo4j-password TEXT Neo4j password. │
|
|
225
|
+
│ Prefer the env │
|
|
226
|
+
│ var over the │
|
|
227
|
+
│ flag (the flag │
|
|
228
|
+
│ is visible in │
|
|
229
|
+
│ shell history / │
|
|
230
|
+
│ process list). │
|
|
231
|
+
│ [env var: │
|
|
232
|
+
│ NEO4J_PASSWORD] │
|
|
233
|
+
│ [default: neo4j] │
|
|
234
|
+
│ --neo4j-database TEXT Neo4j database │
|
|
235
|
+
│ name (default: │
|
|
236
|
+
│ server default). │
|
|
237
|
+
│ [env var: │
|
|
238
|
+
│ NEO4J_DATABASE] │
|
|
239
|
+
│ --analysis-level -a INTEGER RANGE Analysis depth: │
|
|
240
|
+
│ [1<=x<=2] 1=symbol │
|
|
241
|
+
│ table+Jedi call │
|
|
242
|
+
│ graph, 2=+PyCG │
|
|
243
|
+
│ call graph. │
|
|
244
|
+
│ [default: 1] │
|
|
245
|
+
│ --ray --no-ray Enable Ray for │
|
|
246
|
+
│ distributed │
|
|
247
|
+
│ analysis. │
|
|
248
|
+
│ [default: │
|
|
249
|
+
│ no-ray] │
|
|
250
|
+
│ --eager --lazy Enable eager or │
|
|
251
|
+
│ lazy analysis. │
|
|
252
|
+
│ Defaults to │
|
|
253
|
+
│ lazy. │
|
|
254
|
+
│ [default: lazy] │
|
|
255
|
+
│ --skip-tests --include-tests Skip test files │
|
|
256
|
+
│ in analysis. │
|
|
257
|
+
│ [default: │
|
|
258
|
+
│ skip-tests] │
|
|
259
|
+
│ --no-venv --venv Skip virtualenv │
|
|
260
|
+
│ creation and │
|
|
261
|
+
│ dependency │
|
|
262
|
+
│ installation; │
|
|
263
|
+
│ resolve imports │
|
|
264
|
+
│ against the │
|
|
265
|
+
│ ambient Python │
|
|
266
|
+
│ environment │
|
|
267
|
+
│ instead. │
|
|
268
|
+
│ [default: venv] │
|
|
269
|
+
│ --file-name PATH Analyze only the │
|
|
270
|
+
│ specified file │
|
|
271
|
+
│ (relative to │
|
|
272
|
+
│ input │
|
|
273
|
+
│ directory). │
|
|
274
|
+
│ --cache-dir -c PATH Directory to │
|
|
275
|
+
│ store analysis │
|
|
276
|
+
│ cache. Defaults │
|
|
277
|
+
│ to │
|
|
278
|
+
│ '.codeanalyzer' │
|
|
279
|
+
│ in the input │
|
|
280
|
+
│ directory. │
|
|
281
|
+
│ --clear-cache --keep-cache Clear cache │
|
|
282
|
+
│ after analysis. │
|
|
283
|
+
│ By default, │
|
|
284
|
+
│ cache is │
|
|
285
|
+
│ retained. │
|
|
286
|
+
│ [default: │
|
|
287
|
+
│ keep-cache] │
|
|
288
|
+
│ -v INTEGER Increase │
|
|
289
|
+
│ verbosity: -v, │
|
|
290
|
+
│ -vv, -vvv │
|
|
291
|
+
│ [default: 0] │
|
|
292
|
+
│ --pycg-shard --no-pycg-shard Shard PyCG │
|
|
293
|
+
│ call-graph │
|
|
294
|
+
│ analysis by │
|
|
295
|
+
│ Python package │
|
|
296
|
+
│ (level 2 only). │
|
|
297
|
+
│ When the project │
|
|
298
|
+
│ exceeds the │
|
|
299
|
+
│ 500-file │
|
|
300
|
+
│ ceiling, PyCG is │
|
|
301
|
+
│ run │
|
|
302
|
+
│ independently │
|
|
303
|
+
│ per top-level │
|
|
304
|
+
│ package with │
|
|
305
|
+
│ cross-package │
|
|
306
|
+
│ imports treated │
|
|
307
|
+
│ as ghost nodes. │
|
|
308
|
+
│ Without this │
|
|
309
|
+
│ flag, projects │
|
|
310
|
+
│ over the ceiling │
|
|
311
|
+
│ fall back to │
|
|
312
|
+
│ Jedi-only edges. │
|
|
313
|
+
│ [default: │
|
|
314
|
+
│ no-pycg-shard] │
|
|
315
|
+
│ --pycg-shard-cei… INTEGER RANGE Maximum files │
|
|
316
|
+
│ [x>=1] per shard when │
|
|
317
|
+
│ --pycg-shard is │
|
|
318
|
+
│ active (default │
|
|
319
|
+
│ 100). Shards │
|
|
320
|
+
│ exceeding this │
|
|
321
|
+
│ limit are │
|
|
322
|
+
│ skipped; their │
|
|
323
|
+
│ call edges are │
|
|
324
|
+
│ omitted from the │
|
|
325
|
+
│ call graph (Jedi │
|
|
326
|
+
│ edges for those │
|
|
327
|
+
│ packages are │
|
|
328
|
+
│ still included). │
|
|
329
|
+
│ Lower values are │
|
|
330
|
+
│ safer for │
|
|
331
|
+
│ packages with │
|
|
332
|
+
│ deep class │
|
|
333
|
+
│ hierarchies or │
|
|
334
|
+
│ heavy import │
|
|
335
|
+
│ graphs. │
|
|
336
|
+
│ [default: 100] │
|
|
337
|
+
│ --pycg-shard-tim… INTEGER RANGE Per-shard │
|
|
338
|
+
│ [x>=0] wall-clock │
|
|
339
|
+
│ timeout in │
|
|
340
|
+
│ seconds when │
|
|
341
|
+
│ --pycg-shard is │
|
|
342
|
+
│ active (default │
|
|
343
|
+
│ 120). A shard │
|
|
344
|
+
│ that exceeds │
|
|
345
|
+
│ this limit is │
|
|
346
|
+
│ skipped │
|
|
347
|
+
│ gracefully. │
|
|
348
|
+
│ PyCG's fixpoint │
|
|
349
|
+
│ is bimodal: it │
|
|
350
|
+
│ either converges │
|
|
351
|
+
│ quickly or │
|
|
352
|
+
│ diverges │
|
|
353
|
+
│ indefinitely, so │
|
|
354
|
+
│ the timeout acts │
|
|
355
|
+
│ as a final │
|
|
356
|
+
│ safety net after │
|
|
357
|
+
│ the file-count │
|
|
358
|
+
│ ceiling. Set to │
|
|
359
|
+
│ 0 to disable. │
|
|
360
|
+
│ POSIX only │
|
|
361
|
+
│ (macOS / Linux); │
|
|
362
|
+
│ ignored on │
|
|
363
|
+
│ Windows. │
|
|
364
|
+
│ [default: 120] │
|
|
365
|
+
│ --pycg-shard-str… [jedi|package] How --pycg-shard │
|
|
366
|
+
│ groups files │
|
|
367
|
+
│ (level 2 only). │
|
|
368
|
+
│ 'jedi' (default) │
|
|
369
|
+
│ partitions the │
|
|
370
|
+
│ Jedi │
|
|
371
|
+
│ module-dependen… │
|
|
372
|
+
│ graph (SCC + │
|
|
373
|
+
│ Louvain) so │
|
|
374
|
+
│ tightly-coupled │
|
|
375
|
+
│ modules │
|
|
376
|
+
│ co-compute and │
|
|
377
|
+
│ few call edges │
|
|
378
|
+
│ are severed │
|
|
379
|
+
│ between shards; │
|
|
380
|
+
│ import cycles │
|
|
381
|
+
│ are never split. │
|
|
382
|
+
│ 'package' uses │
|
|
383
|
+
│ the legacy │
|
|
384
|
+
│ one-shard-per-p… │
|
|
385
|
+
│ grouping. │
|
|
386
|
+
│ [default: jedi] │
|
|
387
|
+
│ --pycg-max-iter INTEGER RANGE Cap on PyCG's │
|
|
388
|
+
│ [x>=-1] fixpoint passes │
|
|
389
|
+
│ per │
|
|
390
|
+
│ shard/project │
|
|
391
|
+
│ (level 2; │
|
|
392
|
+
│ default 50). │
|
|
393
|
+
│ PyCG iterates │
|
|
394
|
+
│ until its │
|
|
395
|
+
│ points-to state │
|
|
396
|
+
│ stops changing, │
|
|
397
|
+
│ but its │
|
|
398
|
+
│ access-path │
|
|
399
|
+
│ domain has no │
|
|
400
|
+
│ convergence │
|
|
401
|
+
│ bound, so heavy │
|
|
402
|
+
│ metaclass/mixin │
|
|
403
|
+
│ code (e.g. an │
|
|
404
|
+
│ ORM) can loop │
|
|
405
|
+
│ with each pass │
|
|
406
|
+
│ costing seconds. │
|
|
407
|
+
│ The cap returns │
|
|
408
|
+
│ a │
|
|
409
|
+
│ sound-but-incom… │
|
|
410
|
+
│ call graph │
|
|
411
|
+
│ instead of │
|
|
412
|
+
│ looping until │
|
|
413
|
+
│ the timeout │
|
|
414
|
+
│ kills it. Set to │
|
|
415
|
+
│ -1 for PyCG's │
|
|
416
|
+
│ unbounded │
|
|
417
|
+
│ run-to-converge… │
|
|
418
|
+
│ behaviour. │
|
|
419
|
+
│ [default: 50] │
|
|
420
|
+
│ --help Show this │
|
|
421
|
+
│ message and │
|
|
422
|
+
│ exit. │
|
|
423
|
+
╰──────────────────────────────────────────────────────────────────────────────╯
|
|
424
|
+
```
|
|
425
|
+
|
|
426
|
+
<!-- END canpy-help -->
|
|
427
|
+
|
|
428
|
+
### Examples
|
|
429
|
+
|
|
430
|
+
1. **Basic analysis to stdout, or to a file:**
|
|
431
|
+
```sh
|
|
432
|
+
canpy --input ./my-python-project # compact JSON on stdout
|
|
433
|
+
canpy --input ./my-python-project --output ./out # → ./out/analysis.json
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
2. **Binary output (msgpack):**
|
|
437
|
+
```sh
|
|
438
|
+
canpy --input ./my-python-project --output ./out --format msgpack # → ./out/analysis.msgpack
|
|
439
|
+
```
|
|
440
|
+
|
|
441
|
+
3. **Resolve extra call edges with CodeQL:**
|
|
442
|
+
```sh
|
|
443
|
+
canpy --input ./my-python-project --codeql
|
|
444
|
+
```
|
|
445
|
+
By default, edges come from Jedi's lexical analysis. Adding `--codeql` resolves additional edges
|
|
446
|
+
(including RPC / third-party / dynamically-dispatched targets) and merges them with the
|
|
447
|
+
Jedi-derived edges; CodeQL also backfills resolved callees Jedi could not resolve. CodeQL
|
|
448
|
+
integration is experimental; the CLI is downloaded into `<cache_dir>/codeql/` on first use.
|
|
449
|
+
|
|
450
|
+
4. **Emit a Neo4j snapshot, or push to a live database:**
|
|
451
|
+
```sh
|
|
452
|
+
canpy --input ./my-python-project --emit neo4j --output ./out # → ./out/graph.cypher
|
|
453
|
+
canpy --input ./my-python-project --emit neo4j \
|
|
454
|
+
--neo4j-uri bolt://localhost:7687 --neo4j-user neo4j --neo4j-password secret
|
|
455
|
+
```
|
|
456
|
+
|
|
457
|
+
5. **Emit the Neo4j schema contract:**
|
|
458
|
+
```sh
|
|
459
|
+
canpy --emit schema # print schema.json to stdout (no project needed)
|
|
460
|
+
canpy --emit schema --output ./out # → ./out/schema.json
|
|
461
|
+
```
|
|
462
|
+
|
|
463
|
+
6. **Force a clean rebuild with a custom cache directory:**
|
|
464
|
+
```sh
|
|
465
|
+
canpy --input ./my-python-project --eager --cache-dir /path/to/custom-cache
|
|
466
|
+
```
|
|
467
|
+
|
|
468
|
+
## Output targets
|
|
469
|
+
|
|
470
|
+
`canpy` builds one analysis in memory and can emit it three ways (`--emit`):
|
|
471
|
+
|
|
472
|
+
### `analysis.json` (default)
|
|
473
|
+
|
|
474
|
+
A `PyApplication` document — the canonical CLDK contract:
|
|
475
|
+
|
|
476
|
+
```jsonc
|
|
477
|
+
{
|
|
478
|
+
"symbol_table": { /* file path → module (classes, functions, variables, imports, …) */ },
|
|
479
|
+
"call_graph": [ /* CALL_DEP edges: { source, target, weight, provenance } keyed by callable signature */ ]
|
|
480
|
+
}
|
|
481
|
+
```
|
|
482
|
+
|
|
483
|
+
By default this is printed to stdout in JSON; with `--output` it is written to `analysis.json` (or
|
|
484
|
+
`analysis.msgpack` with `--format msgpack`, a more compact binary format).
|
|
485
|
+
|
|
486
|
+
### Neo4j graph
|
|
487
|
+
|
|
488
|
+
`--emit neo4j` projects the same analysis into a labeled property graph. Every node label is
|
|
489
|
+
`Py`-prefixed and every relationship type is `PY_`-prefixed (e.g. `:PyClass`, `PY_CALLS`) so multiple
|
|
490
|
+
language analyzers can share one database without label or relationship-type collisions. Declarations
|
|
491
|
+
are keyed by their signature under a shared `:PySymbol` label; calls, imports, inheritance,
|
|
492
|
+
decorators, and call sites are relationships:
|
|
493
|
+
|
|
494
|
+
- **Without `--neo4j-uri`** — writes a self-contained `graph.cypher` (constraints + indexes, a scoped
|
|
495
|
+
wipe, then batched `MERGE`s). Load it with `cypher-shell < graph.cypher`. Needs no extra
|
|
496
|
+
dependencies.
|
|
497
|
+
- **With `--neo4j-uri`** — pushes to a live Neo4j over Bolt **incrementally**: only modules whose
|
|
498
|
+
content hash changed are rewritten, and on a full run modules whose source file vanished are
|
|
499
|
+
pruned. Requires the `neo4j` extra. Every graph carries a `schema_version` on its `:PyApplication`
|
|
500
|
+
node.
|
|
501
|
+
|
|
502
|
+
Call-graph endpoints that aren't present in the symbol table (third-party / framework / RPC targets)
|
|
503
|
+
are materialized as `:PyExternal` ghost nodes, mirroring the analyzer's own ghost-node behaviour.
|
|
504
|
+
|
|
505
|
+
The connection options also read from the standard Neo4j environment variables — `NEO4J_URI`,
|
|
506
|
+
`NEO4J_USERNAME`, `NEO4J_PASSWORD`, `NEO4J_DATABASE` — when the corresponding flag is omitted (an
|
|
507
|
+
explicit flag wins). Prefer the env var for the password so it doesn't land in shell history or the
|
|
508
|
+
process list:
|
|
509
|
+
|
|
510
|
+
```sh
|
|
511
|
+
export NEO4J_URI=bolt://localhost:7687
|
|
512
|
+
export NEO4J_PASSWORD=secret
|
|
513
|
+
canpy -i ./my-project --emit neo4j # credentials picked up from the environment
|
|
514
|
+
```
|
|
515
|
+
|
|
516
|
+
### Schema contract
|
|
517
|
+
|
|
518
|
+
`--emit schema` writes the machine-readable, version-stamped Neo4j schema (`schema.json`: node labels,
|
|
519
|
+
relationships, properties, constraints, and indexes). It needs no project and is checked into the repo
|
|
520
|
+
as `schema.neo4j.json` and bundled in every release as a GitHub Release asset, so a consumer can
|
|
521
|
+
validate producer/consumer compatibility without invoking the tool. The shape of the contract matches
|
|
522
|
+
the [`codeanalyzer-typescript`](https://github.com/codellm-devkit/codeanalyzer-typescript) backend.
|
|
523
|
+
|
|
524
|
+
A UML of the `analysis.json` schema (the `PyApplication` containment tree) is checked in as
|
|
525
|
+
[`schema-uml.drawio`](./schema-uml.drawio), and the property-graph schema as
|
|
526
|
+
[`neo4j-schema.drawio`](./neo4j-schema.drawio).
|
|
527
|
+
|
|
528
|
+
## Development
|
|
529
|
+
|
|
530
|
+
This project uses [uv](https://docs.astral.sh/uv/).
|
|
531
|
+
|
|
532
|
+
```sh
|
|
533
|
+
uv sync --all-groups
|
|
534
|
+
uv run canpy --input /path/to/project # run from source
|
|
535
|
+
uv run canpy --emit schema > schema.neo4j.json # regenerate the checked-in schema contract
|
|
536
|
+
uv run python scripts/update_readme.py # regenerate the canpy --help block above
|
|
537
|
+
uv run pytest # run the test suite
|
|
538
|
+
```
|
|
539
|
+
|
|
540
|
+
The Neo4j schema-conformance test always runs. The Neo4j **bolt** integration test spins up a real
|
|
541
|
+
Neo4j via [Testcontainers](https://testcontainers.com/) and is **opt-in** — it needs a container
|
|
542
|
+
runtime (Docker or Podman) and is enabled with an environment variable:
|
|
543
|
+
|
|
544
|
+
```sh
|
|
545
|
+
RUN_CONTAINER_TESTS=1 uv run pytest test/test_neo4j_bolt.py -s
|
|
546
|
+
```
|
|
547
|
+
|
|
548
|
+
## License
|
|
549
|
+
|
|
550
|
+
Apache 2.0 — see [LICENSE](./LICENSE).
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
codeanalyzer/__init__.py,sha256=BZ3Kuwl-F_F-8H8cepLnVJ4Ku4NNUjjqg0Y6ujPQSsI,108
|
|
2
|
+
codeanalyzer/__main__.py,sha256=-los-YRXrmZsISNrWh8EjgUcUSkUbSGqEX7yadZuvB8,11920
|
|
3
|
+
codeanalyzer/core.py,sha256=rUKEa4jAbQFtvAnkDKinBGznLpb6VquULLlMVoFjMTU,29533
|
|
4
|
+
codeanalyzer/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
5
|
+
codeanalyzer/config/__init__.py,sha256=9XBxAn1oWGRuhg3bEBUuVGs3hFNXEAKrr-Ce7tq9a2k,61
|
|
6
|
+
codeanalyzer/config/config.py,sha256=ZiKzc5uEUCIvih58-6BDtLLI1hPij41wGQjBcj9KNQM,188
|
|
7
|
+
codeanalyzer/jedi/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
8
|
+
codeanalyzer/jedi/jedi.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
9
|
+
codeanalyzer/neo4j/__init__.py,sha256=AcbFNAMuXwkMFWH4h_HCmla6PCKTF3Xe5yNqg8F_kYk,1575
|
|
10
|
+
codeanalyzer/neo4j/bolt.py,sha256=-IFDb_d67IkGwxvmmbLNI6AvSQHY-XsutI3szibWidw,9635
|
|
11
|
+
codeanalyzer/neo4j/catalog.py,sha256=VQWtwcueck2Ug_cu8sitvAoRwbVZ-6KRiexRN8q1Wak,7418
|
|
12
|
+
codeanalyzer/neo4j/cypher.py,sha256=2zIWXA1AADrwCMhSTeqKjEXRgBjbob6o3bme_cwLu0s,5024
|
|
13
|
+
codeanalyzer/neo4j/emit.py,sha256=WtCndN6mA6PIzfzdgv9Xc5S5WP4rHUXCtB_r3G16rkg,3101
|
|
14
|
+
codeanalyzer/neo4j/project.py,sha256=2GDHkFjmWibrpMaOiDMo21K6Lnj3aefl2QPCM7ANA7g,12485
|
|
15
|
+
codeanalyzer/neo4j/rows.py,sha256=5xI3X-l-vwPe_gmKYUg7VuUQARcOlVAZnGmiQr9QyRk,7326
|
|
16
|
+
codeanalyzer/neo4j/schema.py,sha256=5xz8cZVuL73GAF-vs9QtN2TuKxIty0rHEe68nwQmLTY,2136
|
|
17
|
+
codeanalyzer/options/__init__.py,sha256=Ki4qhHFqpyuUWVsntO-NYJMVWrkeFOzPW4nQ7oxiUVI,155
|
|
18
|
+
codeanalyzer/options/options.py,sha256=5w3DZYlAv-0LVPavF1P5EEJp8XBRrSXidbDusdbXQAo,1976
|
|
19
|
+
codeanalyzer/schema/__init__.py,sha256=cLPjvowrnz8xzi7tZAsKQeIOjdOKRGHy4I7wbG0jHk8,2024
|
|
20
|
+
codeanalyzer/schema/py_schema.py,sha256=6hISjVzoWTq-SHLjT7FsL__uzHT5DY0NYqlpJTLsc9s,12314
|
|
21
|
+
codeanalyzer/semantic_analysis/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
|
|
22
|
+
codeanalyzer/semantic_analysis/call_graph.py,sha256=H3IkfGp1VCkDxI75JPyLSSA-wOaJp_I-NYPsjCY04Bg,11185
|
|
23
|
+
codeanalyzer/semantic_analysis/pycg/__init__.py,sha256=Lsgz25iFM_RGGu_i2psY-LN-KwvYIZQPnKgRPL1JsjU,928
|
|
24
|
+
codeanalyzer/semantic_analysis/pycg/pycg_analysis.py,sha256=22kiZ2Kjpds024iFLu2bPEcCtAKAivdp1Xlr9rfP9lM,45205
|
|
25
|
+
codeanalyzer/semantic_analysis/pycg/pycg_exceptions.py,sha256=n4tRderrSYw9cUYgR2wsn64UqozY56nD1YfDNnaVcAk,968
|
|
26
|
+
codeanalyzer/semantic_analysis/pycg/shard_planner.py,sha256=PTXMG9YcrZX9hgnlnIlpQx6xmWkizP3aQrf0elcrnmw,15865
|
|
27
|
+
codeanalyzer/syntactic_analysis/__init__.py,sha256=EUQkJEh6wHjWx2qTTKbTbUgwSbfKeNieKHNy7RknVXA,476
|
|
28
|
+
codeanalyzer/syntactic_analysis/exceptions.py,sha256=whs_n0vIu655Jkk1a7iOoXY6iIca4pZqJnU40V9Ejaw,537
|
|
29
|
+
codeanalyzer/syntactic_analysis/symbol_table_builder.py,sha256=zmHFt8pN50jG-Ex4fnisvbLmn1XaW05jwbV_xSG4qfU,38177
|
|
30
|
+
codeanalyzer/utils/__init__.py,sha256=hC6VWdR5rerSqBxzu9KQHTASWqwrrYJv-CMDwrTlzkc,137
|
|
31
|
+
codeanalyzer/utils/logging.py,sha256=Fw0tattPAOMs3o0JMjjXhRVLIF64f-SCcygUXF9jqeg,904
|
|
32
|
+
codeanalyzer/utils/progress_bar.py,sha256=C9JtzVdd10lIxTv-KA6PebqjKWueC_vMGwVzAtHuHIw,2818
|
|
33
|
+
codeanalyzer_python-0.3.0.dist-info/METADATA,sha256=l7oUfSjJiPF1mvfQQOmm6JyzIWOBveKKp8xHJF0dw-E,33777
|
|
34
|
+
codeanalyzer_python-0.3.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
|
|
35
|
+
codeanalyzer_python-0.3.0.dist-info/entry_points.txt,sha256=v4Vux0Nnx7sOntVk_CH7W9RX6SkIkvR1FQYq73oVlCQ,105
|
|
36
|
+
codeanalyzer_python-0.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
|
|
37
|
+
codeanalyzer_python-0.3.0.dist-info/licenses/NOTICE,sha256=YU0Z9NDWqKY-2jfFcbxeZ6fbnzz0oZeKmnUcO8a-bcQ,901
|
|
38
|
+
codeanalyzer_python-0.3.0.dist-info/RECORD,,
|