Skip to content

Commit befa05c

Browse files
rahlkrahlk
committed
Rework PyPI README to mirror the main project README
The packaging README is the PyPI long description, so mirror the main repo README (intro, Usage, Output, License) instead of leading with build internals. Drop the Bun prerequisites / install-from-source / development sections (not relevant to a pip user) and move the package-specific docs (platform wheels, build & publish, versioning, SDK integration) below a divider. Also drop the stale 'mirrors the Java jar in the python-sdk wheel' references: that backend's Python packaging is upcoming, not an existing pattern to mirror.
1 parent c77a0a0 commit befa05c

2 files changed

Lines changed: 151 additions & 18 deletions

File tree

‎packaging/python/README.md‎

Lines changed: 149 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1,22 +1,155 @@
1-
# codeanalyzer-typescript (Python distribution)
1+
![logo](https://github.com/codellm-devkit/codeanalyzer-python/blob/main/docs/assets/logo.png?raw=true)
22

3-
This directory packages the compiled `codeanalyzer-typescript` binary as a set of
4-
platform-specific Python wheels, published to PyPI as **`codeanalyzer-typescript`**.
3+
# A TypeScript Static Analysis Toolkit (and Library)
4+
5+
A comprehensive static analysis tool for TypeScript and JavaScript source code that
6+
produces the canonical CodeLLM-DevKit (CLDK) `analysis.json` — a symbol table plus a
7+
resolver-based call graph — using the TypeScript compiler via [ts-morph](https://ts-morph.com/).
8+
It is the TypeScript backend behind [CLDK](https://github.com/codellm-devkit/python-sdk),
9+
mirroring its [Python](https://github.com/codellm-devkit/codeanalyzer-python) and
10+
[Java](https://github.com/codellm-devkit/codeanalyzer-java) siblings.
11+
12+
## Usage
13+
14+
The analyzer provides a command-line interface for performing static analysis on
15+
TypeScript/JavaScript projects.
16+
17+
### Basic Usage
18+
19+
```bash
20+
codeanalyzer-typescript --input /path/to/typescript/project
21+
```
22+
23+
### Command Line Options
24+
25+
To view the available options, run `codeanalyzer-typescript --help`:
26+
27+
```text
28+
Usage: codeanalyzer-typescript [options]
29+
30+
CLDK TypeScript analyzer — emits the canonical analysis.json
31+
(symbol table + resolver call graph).
32+
33+
Options:
34+
-i, --input <path> project root to analyze
35+
-o, --output <dir> output directory for analysis.json
36+
(omit ⇒ compact JSON to stdout)
37+
-f, --format <fmt> output format: json | msgpack (default: "json")
38+
-a, --analysis-level <n> 1 = tsc resolver call graph + RTA (default);
39+
2 = + CodeQL enrichment (default: "1")
40+
-t, --target-files <paths...> restrict analysis to specific files (incremental)
41+
--skip-tests skip test trees (default)
42+
--include-tests include test trees
43+
--eager force a clean rebuild instead of reusing the cache
44+
--lazy reuse the cache (default)
45+
--no-build skip dependency materialization
46+
(use a prepared node_modules)
47+
--no-phantoms disable phantom (external) nodes for imported/
48+
required library calls
49+
-c, --cache-dir <dir> cache/intermediate directory
50+
-v, --verbose increase verbosity (repeatable)
51+
-h, --help display help for command
52+
```
53+
54+
### Examples
55+
56+
1. **Basic analysis (symbol table + call graph):**
57+
```bash
58+
codeanalyzer-typescript --input ./my-ts-project
59+
```
60+
61+
This prints the analysis to stdout as compact JSON. To save it instead, use `--output`:
62+
63+
```bash
64+
codeanalyzer-typescript --input ./my-ts-project --output /path/to/analysis-results
65+
```
66+
67+
The results are written to `analysis.json` in the specified directory.
68+
69+
2. **Change output format to msgpack:**
70+
```bash
71+
codeanalyzer-typescript --input ./my-ts-project --output /path/to/analysis-results --format msgpack
72+
```
573

6-
The CLDK Python SDK depends on this package and calls `codeanalyzer_typescript.bin_path()`
7-
to locate the analyzer binary — the same way it imports `codeanalyzer-python` for the
8-
Python backend. The binary itself is built from this repo's `src/` with
9-
`bun build --compile`, so it is fully self-contained (no Node/Bun needed at runtime).
74+
This saves the results to `analysis.msgpack`, a binary format that is more compact for
75+
storage and transmission.
76+
77+
3. **Deeper analysis with CodeQL enrichment (experimental):**
78+
```bash
79+
codeanalyzer-typescript --input ./my-ts-project --analysis-level 2
80+
```
81+
82+
Every run produces a symbol table **and** a call graph. At level 1, edges come from the
83+
TypeScript compiler's resolver plus Rapid Type Analysis (RTA), with phantom nodes for
84+
calls into imported libraries. Level 2 additionally merges in CodeQL-derived edges.
85+
86+
4. **Incremental analysis of specific files:**
87+
```bash
88+
codeanalyzer-typescript --input ./my-ts-project --target-files src/a.ts src/b.ts
89+
```
90+
91+
Restricts the analysis to the named files, reusing the cached analysis for the rest of
92+
the project.
93+
94+
5. **Force a clean rebuild with a custom cache directory:**
95+
```bash
96+
codeanalyzer-typescript --input ./my-ts-project --eager --cache-dir /path/to/custom-cache
97+
```
98+
99+
`--eager` rebuilds the analysis cache from scratch. If `--cache-dir` is omitted, the cache
100+
defaults to `.codeanalyzer` inside the project root.
101+
102+
## Output
103+
104+
By default, analysis results are printed to stdout as compact JSON. When `--output` is given,
105+
results are saved to `analysis.json` (or `analysis.msgpack` with `--format msgpack`) in the
106+
specified directory.
107+
108+
The output document is a `TSApplication` with the following top-level shape:
109+
110+
```jsonc
111+
{
112+
"symbol_table": { /* file path → module (classes, interfaces, enums,
113+
type aliases, functions, namespaces, variables, …) */ },
114+
"call_graph": [ /* CALL_DEP edges: { source, target, weight,
115+
provenance, tags } keyed by callable signature */ ],
116+
"external_symbols": { /* phantom stubs for call targets outside the project
117+
(imported libraries / Node builtins) */ },
118+
"entrypoints": { /* framework-detected entrypoints (empty at level 1) */ }
119+
}
120+
```
121+
122+
Caller- and callee-side identifiers are produced by a single signature canonicalizer, so call
123+
graph `source`/`target` values byte-match the corresponding `symbol_table` (or
124+
`external_symbols`) keys.
125+
126+
## License
127+
128+
Apache 2.0 — see [LICENSE](./LICENSE).
129+
130+
---
131+
132+
<!-- The sections below document this Python distribution itself; they have no
133+
equivalent in the main repository README. -->
134+
135+
## About this package
136+
137+
This distributes the compiled `codeanalyzer-typescript` binary as a set of
138+
platform-specific Python wheels, published to PyPI as **`codeanalyzer-typescript`**.
139+
The CLDK Python SDK depends on this package and calls
140+
`codeanalyzer_typescript.bin_path()` to locate the analyzer binary. The binary is
141+
built from this repo's `src/` with `bun build --compile`, so it is fully
142+
self-contained (no Node/Bun needed at runtime).
10143

11-
## Why platform wheels?
144+
### Why platform wheels?
12145

13-
Unlike the Java backend (one cross-platform `.jar`), a `bun --compile` binary is
14-
platform-specific and large (~70 MB). So we ship **one wheel per OS/arch**, tagged
15-
`py3-none-<platform>` (the binary is Python-agnostic — no per-Python-version matrix),
16-
and let pip resolve the correct one at install time. There is intentionally no usable
17-
sdist: the binary cannot be built without Bun.
146+
A `bun --compile` binary is platform-specific and large (~70 MB) — there is no single
147+
cross-platform artifact (the way a JVM backend could ship one `.jar`). So we ship **one
148+
wheel per OS/arch**, tagged `py3-none-<platform>` (the binary is Python-agnostic — no
149+
per-Python-version matrix), and let pip resolve the correct one at install time. There
150+
is intentionally no usable sdist: the binary cannot be built without Bun.
18151

19-
## Building & publishing
152+
### Building & publishing
20153

21154
```bash
22155
python -m pip install build wheel hatchling twine
@@ -29,7 +162,7 @@ twine upload dist/*.whl
29162
Bun cross-compiles all targets from a single host, so this does not need a CI runner
30163
matrix.
31164

32-
## Versioning
165+
### Versioning
33166

34167
The released version comes from the **git tag**. A push of `vX.Y.Z` triggers the
35168
release workflow, which derives `X.Y.Z` from the tag, verifies it matches this
@@ -52,7 +185,7 @@ One thing still tracked by hand: the python-sdk pin — `[tool.backend-versions]
52185
codeanalyzer-typescript` and the `dependencies` entry
53186
`codeanalyzer-typescript==<version>` — must be bumped to consume a new release.
54187

55-
## SDK integration
188+
### SDK integration
56189

57190
In the python-sdk, `TSCodeanalyzer._get_codeanalyzer_exec()` resolves the binary in
58191
this order: `analysis_backend_path` → `$CODEANALYZER_TS_BIN` → **this package** →

‎packaging/python/pyproject.toml‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,8 +31,8 @@ Repository = "https://github.com/codellm-devkit/codeanalyzer-ts"
3131
path = "src/codeanalyzer_typescript/__init__.py"
3232

3333
# The compiled binary lives under _bin/ and is gitignored (it is produced per
34-
# platform at build time). `artifacts` re-includes it in the wheel anyway --
35-
# this mirrors how the Java jar is force-included in the python-sdk wheel.
34+
# platform at build time). `artifacts` re-includes it in the wheel anyway, so the
35+
# gitignored binary still ships inside the built wheel.
3636
[tool.hatch.build.targets.wheel]
3737
packages = ["src/codeanalyzer_typescript"]
3838
artifacts = ["src/codeanalyzer_typescript/_bin/*"]

0 commit comments

Comments
 (0)