Metadata-Version: 2.4
Name: codeatlas-rs
Version: 0.8.1
Classifier: Development Status :: 3 - Alpha
Classifier: Programming Language :: Rust
Classifier: Programming Language :: Python
Classifier: Topic :: Software Development :: Documentation
License-File: LICENSE
License-File: NOTICE
Summary: Rust-native architecture maps for codebases
Keywords: architecture,diagrams,static-analysis,code-visualization,rust
Author: Mullassery
License: MIT
Requires-Python: >=3.9
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM

# CodeAtlas

Rust-native architecture maps for codebases. CodeAtlas scans a repository, extracts symbols and
relationships with deterministic static analysis (tree-sitter), groups code into components, and
documents the architecture as `analysis.json`, Markdown/Mermaid, HTML (Cytoscape), MDX, or
reStructuredText. An optional LLM step names and describes components.

## What works today

- `codeatlas full --local <repo>` produces `.codeatlas/analysis.json` + `fingerprint.json`
  (schema-compatible output) with deterministic, directory-derived component names.
- `codeatlas-render` (or `--render md|html|mdx|rst`) renders overview + per-component docs, with a
  manifest that reconciles stale files and refuses to overwrite unowned files.
- Optional component naming/description via an OpenAI-compatible provider (OpenAI, Ollama,
  OpenRouter, DeepSeek, LiteLLM, LM Studio). Without a provider, analysis still succeeds with
  deterministic names.
- Languages: **Python**, **Rust**, **Go**, **JavaScript/TypeScript**, **Java**,
  **PHP**, and **C#** (tree-sitter).

## Quick start

```bash
pip install codeatlas-rs
codeatlas full --local /path/to/repo
codeatlas full --local /path/to/repo --render md
codeatlas-render /path/to/repo/.codeatlas/analysis.json --format html
codeatlas diff old/.codeatlas/analysis.json new/.codeatlas/analysis.json --fail-on-change
```

Output is written to `<repo>/.codeatlas/`. Configure an optional provider via
`OPENAI_API_KEY` (+ `OPENAI_BASE_URL`, `AGENT_MODEL`); see `codeatlas_rs.llm`.

**Wheels:** `codeatlas-rs` ships `abi3-py39` wheels, so one wheel covers
CPython 3.9+. The release workflow builds manylinux (x86_64/aarch64),
musllinux (x86_64/aarch64), macOS universal2, and Windows x86_64 wheels plus
an sdist. Each wheel is installed and imported before upload. PyPI 0.8.0
ships a macOS arm64 wheel + sdist; the remaining targets are built and
smoke-tested by the release workflow and reach PyPI when its upload job runs.

## PR architecture diff

`codeatlas diff` compares two architecture maps, and
`.github/actions/architecture-diff` runs it as a PR check. See
[`docs/PR_DIFF.md`](docs/PR_DIFF.md).

## Query the call graph

`codeatlas full` also writes `.codeatlas/call_graph.json` with the merged
symbols and call/reference edges. Query it locally without re-analysis or an
LLM:

```bash
codeatlas query /path/to/repo helper
codeatlas query /path/to/repo helper --direction callers --format json
```

`analysis.json` keeps its established schema; the call graph is a sidecar so
local agents and editors can fetch precise symbol context. See
[`docs/CALL_GRAPH_QUERY.md`](docs/CALL_GRAPH_QUERY.md) for the schema and the
Python API.

## Audit findings

The 2026-10-19 implementation audit — including the Java extractor work,
verification results, and remaining gaps — is recorded in
[`AUDIT_FINDINGS.md`](AUDIT_FINDINGS.md).

## Status & roadmap

The deterministic core is implemented end-to-end (discovery → tree-sitter extraction → cross-file
resolution → clustering → `analysis.json` → rendering). See `docs/FEATURE_PARITY.md` for what is
implemented vs. deferred, and `docs/IMPLEMENTATION_ROADMAP.md` for the milestone plan. Documented
limitations: tree-sitter resolution is intentionally simpler than an LSP pipeline
(`docs/audit/KNOWN_GAPS.md`) and clustering is a simplified deterministic directory partition.

## Bundle into any repository

`codeatlas-bundle` versions the architecture map inside a repository: it runs the analysis, renders
the docs, and (optionally) commits them so the map evolves with the code. See
[`packages/codeatlas-bundle`](packages/codeatlas-bundle).

```bash
pip install codeatlas-rs codeatlas-bundle
cd my-repo && codeatlas-bundle init && codeatlas-bundle build --commit
```

## Layout

- `crates/core` — pure-Rust analysis engine (no Python, no network, no LLM).
- `crates/py` — PyO3 bindings (`codeatlas_rs._core`).
- `python/codeatlas_rs` — the Python wrapper (CLI, rendering, optional LLM).
- `packages/codeatlas-bundle` — pure-Python package that bundles the docs into other repositories.

## Development

```bash
# Rust core (no Python needed)
cargo test -p codeatlas-core

# Rust workspace (needs a Python with a shared library, e.g. `export PYO3_PYTHON=$(which python3.12)`)
cargo build --workspace && cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings
cargo fmt --all --check

# Python package
maturin build --release --interpreter python3.12 --out dist
maturin develop --interpreter python3.12
python -m pytest tests
```

Requires Rust (stable) and Python 3.9+ (3.12 recommended), with `maturin` for the Python package.

## Known issues and deferred work

**Blocked / failed:**
- Kotlin extractor (grammar incompatible with tree-sitter 0.25); Linux/Windows wheels.

**Rejected / deferred:**
- Chat UI; LSP-level resolution now.

Full shipped/blocked/rejected detail: [`QUEUE_STATUS.md`](QUEUE_STATUS.md).

## License

MIT. See `LICENSE` and `NOTICE`.
## Incremental workflow cache

`codeatlas full --cache` fingerprints repository source content (git HEAD/status
plus file metadata) and reuses the previous analysis when nothing changed:

```bash
codeatlas full --local . --cache --render md
```

The first run stores analysis/fingerprint/coverage under `.codeatlas/cache/`;
subsequent unchanged runs skip the Rust pipeline and reuse the artifacts. This
is a whole-repository workflow cache, not per-file re-analysis.


