Metadata-Version: 2.5
Name: svarupa
Version: 2026.11.1
Summary: Verified architecture diagrams and a queryable knowledge graph, derived from your codebase. Every box points at a line of code.
Project-URL: Homepage, https://github.com/aiwithvd/svarupa
Project-URL: Repository, https://github.com/aiwithvd/svarupa
Project-URL: Issues, https://github.com/aiwithvd/svarupa/issues
License-Expression: MIT
License-File: LICENSE
Keywords: architecture,diagrams,knowledge-graph,static-analysis,tree-sitter
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Documentation
Requires-Python: >=3.10
Requires-Dist: networkx<4,>=3.2
Requires-Dist: pathspec<2,>=0.12
Requires-Dist: pyyaml<7,>=6
Requires-Dist: tomli>=2; python_version < '3.11'
Requires-Dist: tree-sitter-c-sharp==0.23.5
Requires-Dist: tree-sitter-go==0.25.0
Requires-Dist: tree-sitter-java==0.23.5
Requires-Dist: tree-sitter-python==0.25.0
Requires-Dist: tree-sitter-rust==0.24.2
Requires-Dist: tree-sitter-typescript==0.23.2
Requires-Dist: tree-sitter<0.27,>=0.26
Provides-Extra: leiden
Requires-Dist: leidenalg>=0.10; extra == 'leiden'
Requires-Dist: python-igraph>=0.11; extra == 'leiden'
Provides-Extra: mcp
Requires-Dist: mcp>=2; extra == 'mcp'
Description-Content-Type: text/markdown

# Svarupa

**स्वरूप** — *"its own true form."*

Svarupa reads a codebase and produces a **verified** map of it: a queryable
knowledge graph plus six types of architecture diagram (architecture, module
dependencies, data flow, request flow, deploy topology, ERD), delivered as one
interactive HTML artifact. A type the evidence cannot produce is named as
absent, never fabricated.

The defining constraint: **every node and every edge in every diagram carries
`file:line` evidence, or it does not render.** Not a heuristic guess, not a
model's plausible story. A claim you can click through to the source line that
proves it.

The name states the thesis. Svarupa is a thing's actual form, not its intended
one. Architecture documents describe what someone meant to build. Svarupa
renders what exists.

> **Status: alpha.** The evidence contract is stable; flags and output
> formats may still change between minor versions.

---

## Quickstart

```bash
uv tool install svarupa     # or: pipx install svarupa / pip install svarupa
svarupa .                   # scans the repo, writes .svarupa/
open .svarupa/index.html
```

That is the whole setup — no configuration file, no daemon, no account. The
first run of a typical repository takes seconds.

`python -m svarupa` is the same command; `--out ./map` writes the artifact
somewhere other than `<repo>/.svarupa/`. The artifact holds:

- `index.html`: every diagram type as a tab. Click a box for its passport
  (kind, connections, reach, cited source lines); double-click a drillable box,
  or click its chevron, to open it in place down to component and code level.
- `graph.json`: the knowledge graph. `svarupa query <dir> get_node <label>`,
  `get_neighbors`, `shortest_path`, `affected`, `god_nodes`, `graph_stats`, `get_health`, `get_design_rules`,
  `query_graph`; `svarupa mcp <dir>` serves the same over MCP.
- `REPORT.md`: the resolution scorecard and every finding, with its code.
- Health: nine maintainability checks with published thresholds (complexity,
  length, parameters, nesting, file and class size, duplication, import cycles,
  hub modules), graded with the SQALE model, in the CLI, REPORT.md, a Health tab,
  `graph.json` and `get_health`. See `docs/health.md`.
- Declared environments (production, staging, qa, development) are extracted
  with `file:line` evidence and surface in the CLI summary, a REPORT.md
  section, `graph.json` nodes, and a cited strip on the deploy topology.
- `--lock` writes the committed architecture lockfile; `--diff` prints the
  architecture delta against a base lockfile; add `--fail-on-change` to exit
  3 when that delta is not empty. `svarupa setup ci_github` (or `ci_gitlab`)
  installs the per-pull-request workflow. The architecture delta is
  informational by default (add `--fail-on-change` to gate it); the health
  step fails the job on new problems (new violations or a worse grade), and
  the file describes the one-line change that makes it report-only.
- `svarupa setup ide` teaches your AI coding tools (Claude Code, Cursor,
  GitHub Copilot, Windsurf, and AGENTS.md readers such as Codex) the Svarupa
  workflow and this repository's rules. It adds Svarupa's MCP server to the
  project configs of Claude Code, Cursor and Copilot, and prints it as a
  snippet to add for Windsurf and Codex (their configs are global). It only edits text between
  `<!-- svarupa:begin -->` and `<!-- svarupa:end -->`; refresh with `--update`, preview with `--dry-run`.
  Windsurf gets a shorter version, because Windsurf limits rule files to 6,000
  characters each (12,000 in total).
- Code facts come from language packs: Python, TypeScript, JavaScript, Go,
  Java, C# and Rust today. JavaScript is experimental; the others are
  stable.
  Other detected languages are listed as detected but not analyzed
  (SVA-X-012), never guessed. Known gaps per
  language are in `docs/health.md`.

![The architecture tab of the demo repository](docs/images/demo-architecture.png)

![The deploy topology tab, with the declared-environments strip on top](docs/images/demo-deploy-topology.png)

Declared environments — production, staging, qa, development — are extracted
with `file:line` evidence and shown as a cited strip above the topology.

---

## Why

Every tool in this space sits on one side of a divide and cannot cross it.

| Tool | Analyzes code | Draws formal diagrams |
|---|---|---|
| Graphify | Deeply, 25+ languages | No — force-directed node-link graphs only |
| Understand-Anything | Yes, AST + LLM | No — force layouts only |
| Archify | No — reads nothing | Yes, five types, excellent quality |
| Cocoon-AI | No — prompt-to-diagram | Yes, architecture only |

Nobody closes the loop `code → AST → derived formal diagram`. The analyzers
produce blobs; the drawers produce unverifiable pictures.

### The larger thesis: continuous architecture governance

Graphify and Understand-Anything are *onboarding* tools. You run one when you
join a project, look at the graph, and never open it again.

Because Svarupa's output is deterministic and evidence-backed, it runs in CI on
every pull request: diff the architecture, comment the impact, fail the build
on policy violations. **Cross-language architecture linting is a category
nobody occupies.**

```
Architecture impact of #482

  + 2 components    billing.refunds, billing.webhooks
  + 1 datastore     redis (compose.yml:31)
  ! NEW DEPENDENCY  billing -> auth.internal
                    via billing/refunds.py:44
  + 4 endpoints     POST /refunds, GET /refunds/{id}, ...
```

---

## Design principles

**Fail-closed on evidence.** An element without a source location is not
emitted. When Python's dynamic dispatch means a call target cannot be pinned,
no edge is written and the gap is counted in the report, rather than papered
over with a plausible one.

**Three-bin honesty.** The resolution scorecard reports *resolved*,
*known-external*, and **unresolved-unknown**. Counting every failure as
"external" would launder resolver bugs into a number that looks like honesty.

**Deterministic by contract.** Same commit, same bytes, on any machine.
Canonical ordering, `==`-pinned grammars, NFC-normalized paths, no timestamps,
no locale-dependent formatting. Verified in CI across Linux and macOS on Python
3.10 through 3.13 with `PYTHONHASHSEED` varied.

**Identity comes from structure, not from clustering.** Lockfile modules are
directories, packages, and workspace members. Community detection is
chaotically sensitive to input perturbation — measured: one added import flips
25-38% of community assignments — so it is used for visual grouping only and
never reaches anything committed.

**Measured, not assumed.** Function-level sequence diagrams were cut after
measurement showed call resolution at ~20% on service code with median chain
depth 0-1. Replaying this repository's own real history (15 commits of actual
development: license swaps, viewer work, layout fixes) produced a median of
**0 lockfile lines per commit** — the diff moves only when the architecture
moves, not when code churns. See `docs/reviews/` for the numbers and the
reasoning.

**Benchmarked.** Every pull request is scored on 15 pinned public
repositories (Python, TypeScript, JavaScript, Go, Java, C#, Rust) against facts checked
by reading their source; a change that loses a found fact fails CI. A
language pack is labelled stable only when two of its repositories reach 90%
recall with no false fact. Recall covers what Svarupa claims to extract
(modules, dependencies, compose services, calls, and routes for FastAPI,
Flask, Express and NestJS), not features it does not extract yet. The Rust
pack is stable: its two repositories score 98% (rust-web-app) and 93%
(zero-to-production). See `benchmark/`.

---

## Development

```bash
uv sync
uv run pytest
uv run ruff check svarupa
uv run pyright svarupa
```

Design and review history:

- `docs/superpowers/specs/` — the design, with a decision log carrying the
  reasoning behind each choice
- `docs/reviews/` — adversarial reviews, raw and triaged. Every finding is
  marked Accepted, Rejected, or Deferred **with a recorded why**, because a
  rejected finding needs its reasoning kept just as much as an accepted one

### Releasing

Versions are calendar based, `YYYY.M.N` (see `docs/adr/0001-calendar-versioning.md`).
A release is two commands, with a reviewed pull request in between:

```bash
git switch main && git pull --ff-only
scripts/release.sh prepare        # next version, bump, draft notes, checks, release PR
# edit docs/releases/vX.md in the PR, resolve every TODO:, merge
git switch main && git pull --ff-only
scripts/release.sh publish        # tag, PyPI via trusted publishing, GitHub Release, install check
```

`publish` pushes the tag and the `release` workflow uploads to PyPI with no
token. It then creates the GitHub Release from the notes file and opens a small
PR that moves the dogfood workflow pin to the new version. If the workflow
had to be re-run by hand, finish with `scripts/release.sh publish-finish`.

---

## License

MIT. See `LICENSE`.

