You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: astro.config.mjs
+4-11Lines changed: 4 additions & 11 deletions
Original file line number
Diff line number
Diff line change
@@ -24,7 +24,7 @@ export default defineConfig({
24
24
"codeanalyzer-python turns a Python project into one typed artifact — symbol table, call graph, and framework entrypoints — using Jedi, CodeQL, and Tree-sitter. The Python backend behind CLDK.",
description: codeanalyzer-python is built to be taught new frameworks and dispatch mechanisms without forking it. Entrypoint finders and analysis passes are the two extension points — both areas where contributions are welcome.
<Badgetext="Work in progress"variant="caution" />{""}
10
+
<Badgetext="Help wanted"variant="note" />
11
+
</p>
12
+
13
+
After the symbol table and base call graph are built, codeanalyzer runs a pipeline of **analysis passes** — whole-application steps that contribute framework-dispatched **entrypoints** and **synthetic call edges** the static graph can't observe. Out-of-tree packages register their own through the `codeanalyzer.analysis_passes` entry-point group, so you can teach codeanalyzer a new framework or a new dispatch mechanism **without forking it**.
14
+
15
+
This is the youngest part of codeanalyzer-python: the **mechanism** exists, but **no concrete framework finder ships yet**. `BUILTIN_PASS_FACTORIES` is empty, so until a finder is written, `PyApplication.entrypoints` comes back empty. The frameworks named on this page (Flask, FastAPI, Celery, Click, gRPC, …) are the **roadmap** — the shapes finders will target — not detection that runs today. Writing the first finder for a framework is itself the contribution.
16
+
17
+
## The two extension points
18
+
19
+
<CardGrid>
20
+
<LinkCard
21
+
title="Entrypoint detection"
22
+
description="Surface framework-dispatched roots — Flask, FastAPI, Celery, Click, gRPC — as PyEntrypoint records, JackEE-style. Write an AbstractEntrypointFinder to cover a new framework."
23
+
href="/codeanalyzer-python/guides/entrypoints/"
24
+
/>
25
+
<LinkCard
26
+
title="Analysis passes"
27
+
description="The AnalysisPass contract: emit entrypoints and synthetic call edges, registered via entry points. The general extension mechanism behind entrypoint finding."
<Asidetype="caution"title="What exists vs. what's planned">
35
+
**Built today:** the analysis-pass pipeline, the `AbstractEntrypointFinder` base class (a JackEE-style port of the Java analyzer's entrypoint architecture), pass discovery and topological ordering, and out-of-tree registration via the `codeanalyzer.analysis_passes` entry-point group. The extension API is the part you can rely on.
36
+
37
+
**Not built yet:** any concrete finder. No framework — Flask, FastAPI, Celery, Click, gRPC, Django, or otherwise — is detected out of the box. Synthetic-edge passes are likewise scaffolding-only. Everything framework-specific is roadmap.
38
+
</Aside>
39
+
40
+
<Asidetype="tip"title="Help wanted">
41
+
The first concrete finder is the contribution. Good starting points: an `AbstractEntrypointFinder` for a framework you use, a synthetic-edge pass for an ORM or dispatch pattern the static graph misses, or test fixtures to pin a finder's behavior. Open an issue or PR on [GitHub](https://github.com/codellm-devkit/codeanalyzer-python), or come talk it through on [Discord](https://discord.gg/zEjz9YrmqN).
<Badgetext="Work in progress"variant="caution" />{""}
10
+
<Badgetext="Help wanted"variant="note" />
11
+
</p>
12
+
13
+
<Asidetype="caution"title="Design, not shipped behavior">
14
+
The `PyEntrypoint` schema and the `AbstractEntrypointFinder` contract described here are implemented, but **no concrete finder ships yet** — `BUILTIN_PASS_FACTORIES` is empty. Until a finder is written, `PyApplication.entrypoints` comes back empty for every framework. Read this page as the shape finders target and the API you'd write one against, not as detection that runs out of the box. See [Extending → Overview](/codeanalyzer-python/extending/overview/).
15
+
</Aside>
7
16
8
17
An **entrypoint** is a function the framework calls that your own code never calls directly: a Flask route handler, a FastAPI endpoint, a Celery task, a Click command, a gRPC servicer method. Static call-graph analysis can't see these edges — the framework wires them up at runtime — so without help, those handlers look like dead code, and reachability from "where execution actually enters" is unanswerable.
9
18
10
-
codeanalyzer-python detects entrypoints with a layer modeled on **JackEE** (Antoniadis et al., PLDI 2020) — the same framework-independent entrypoint architecture the Java analyzer uses. Each detected root becomes a `PyEntrypoint` in `PyApplication.entrypoints`, keyed by framework name.
19
+
codeanalyzer-python is designed to surface entrypoints with a layer modeled on **JackEE** (Antoniadis et al., PLDI 2020) — the same framework-independent entrypoint architecture the Java analyzer uses. Each detected root becomes a `PyEntrypoint` in `PyApplication.entrypoints`, keyed by framework name. The detection sources and framework-specific fields below define what a finder *can* record; which of them are populated depends entirely on which finders are installed.
description: Turn a Python project into one typed artifact — symbol table, call graph, and framework entrypoints — with Jedi, CodeQL, and Tree-sitter. The Python backend behind CLDK.
4
-
template: splash
4
+
template: doc
5
5
hero:
6
6
tagline: Point it at a Python project and get back one typed artifact — symbol table, call graph, and framework entrypoints. Program analysis your agents can call.
Point `codeanalyzer` at a project and it emits a single **`analysis.json`** — a typed model of every module, class, method, and call edge, plus the framework entrypoints that reach them. One artifact, schema-stable, ready to load into a graph or hand to a code LLM. It's the Python backend behind [CLDK](https://github.com/codellm-devkit/python-sdk), usable standalone as a CLI or a library.
<ulclass="cldk-capability__examples"><li>Detect a new framework</li><li>Synthesize ORM-dispatch edges</li></ul>
71
-
</a>
72
-
</ul>
73
-
74
-
<divclass="cldk-agent-band">
75
-
76
-
## One artifact, three engines
77
-
78
-
Jedi resolves the symbol table and a lexical call graph on every run — no setup beyond a Python interpreter. Tree-sitter backs the syntactic extraction. CodeQL is opt-in: when you pass `--codeql`, codeanalyzer downloads the CLI on first use, builds a database, and merges its resolved edges with Jedi's — recovering RPC, third-party, and dynamically-dispatched targets that lexical analysis misses. Every edge records its `provenance`, so you always know which engine saw it.
79
-
80
-
```bash
81
-
# Jedi only (default) — fast, zero external tooling
82
-
codeanalyzer --input ./proj
83
-
84
-
# Add CodeQL — deeper resolution, downloaded and cached per project
85
-
codeanalyzer --input ./proj --codeql
86
-
```
87
-
88
-
```mermaid
89
-
flowchart LR
90
-
A[Python project] --> B["codeanalyzer --input"]
91
-
B --> C[Jedi + Tree-sitter]
92
-
B -.->|--codeql| D[CodeQL]
93
-
C --> E[merge edges]
94
-
D -.-> E
95
-
E --> F["analysis.json
96
-
symbol table + call graph + entrypoints"]
97
-
```
98
-
99
-
[See how the call graph is built →](/codeanalyzer-python/guides/concepts/#call-graph)
100
-
101
-
</div>
24
+
Point `codeanalyzer` at a project and it emits a single **`analysis.json`** — a typed model of every module, class, method, and call edge, plus the framework entrypoints that reach them. It's the Python backend behind [CLDK](https://github.com/codellm-devkit/python-sdk), usable standalone as a CLI or a library.
102
25
103
26
## Start building
104
27
105
28
<CardGrid>
106
29
<LinkCardtitle="Quickstart"description="Install the CLI and produce your first analysis.json in a couple of minutes."href="/codeanalyzer-python/quickstart/" />
107
30
<LinkCardtitle="What is codeanalyzer-python?"description="The mental model: project in → one typed PyApplication artifact out."href="/codeanalyzer-python/what-is-codeanalyzer/" />
108
31
<LinkCardtitle="CLI usage"description="Every flag, with worked examples: output formats, caching, single-file mode."href="/codeanalyzer-python/guides/cli-usage/" />
109
-
<LinkCardtitle="Entrypoint detection"description="JackEE-style finders that surface Flask, FastAPI, Celery, Click, and gRPC roots."href="/codeanalyzer-python/guides/entrypoints/" />
32
+
<LinkCardtitle="Entrypoint detection"description="The planned JackEE-style finder layer for Flask, FastAPI, Celery, Click, and gRPC roots (work in progress)."href="/codeanalyzer-python/guides/entrypoints/" />
<LinkCardtitle="CodeQL analysis"description="What --codeql adds, how the database is cached, and the resolution ladder."href="/codeanalyzer-python/guides/codeql/" />
118
41
<LinkCardtitle="Analysis passes"description="Write your own pass: detect a framework or synthesize edges the static graph can't see."href="/codeanalyzer-python/extending/analysis-passes/" />
Copy file name to clipboardExpand all lines: src/content/docs/quickstart.mdx
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -91,6 +91,6 @@ The first `--codeql` run downloads the CodeQL CLI and builds a database, so it t
91
91
<CardGrid>
92
92
<LinkCardtitle="CLI usage"description="Output formats, caching, single-file mode, verbosity — every flag with examples."href="/codeanalyzer-python/guides/cli-usage/" />
93
93
<LinkCardtitle="Core concepts"description="What the symbol table, call graph, and entrypoints actually contain."href="/codeanalyzer-python/guides/concepts/" />
<LinkCardtitle="Entrypoint detection"description="The planned JackEE-style finder layer for Flask, FastAPI, Celery, Click, and gRPC roots (work in progress)."href="/codeanalyzer-python/guides/entrypoints/" />
95
95
<LinkCardtitle="Output schema"description="The PyApplication data model, field by field."href="/codeanalyzer-python/reference/schema/" />
0 commit comments