Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

docs: rewrite the language-support pages, add a graph layer page, and correct the claims that pointed at them (#1689)

Raghav Chamadiya5f2ed883aff3
diff --git a/.github/CONTRIBUTING.md b/.github/CONTRIBUTING.md
index 97ff03493..2421b7a46 100644
--- a/.github/CONTRIBUTING.md
+++ b/.github/CONTRIBUTING.md
@@ -18,7 +18,7 @@ Thanks for your interest in contributing to Repowise! This guide will help you g
git clone https://github.com/repowise-dev/repowise.git
cd repowise
-# Install Python dependencies (uv workspace — installs all packages)
+# Install Python dependencies (uv workspace, installs all packages)
uv sync --all-packages
# Install web frontend dependencies
@@ -94,8 +94,11 @@ are the only people who use repowise on repowise with fresh eyes.
Cycle, and so on) with the blast radius attached. Each card has a copy-to-agent
button. Picking one off that list is a genuinely useful contribution, and it is the
fastest way to learn how the health layer thinks.
-- **Language support.** Adding a language is one `.scm` query file and one config entry.
- See [docs/layers/LANGUAGE_SUPPORT.md](../docs/layers/LANGUAGE_SUPPORT.md).
+- **Language support.** A new language is five small steps: a `LanguageSpec`, a tag,
+ a `.scm` query file, a parser config and the grammar dependency, with no changes to
+ the parser core. Optional extractors and call-resolution seams add depth on top.
+ Recipe: [docs/architecture/language-support.md](../docs/architecture/language-support.md).
+ Current coverage: [docs/layers/LANGUAGE_SUPPORT.md](../docs/layers/LANGUAGE_SUPPORT.md).
### Claiming an issue
@@ -132,7 +135,7 @@ current ones. Changes there are welcome, but expect closer review and bring test
```bash
git checkout -b feat/your-feature
```
-3. **Make your changes** — keep commits focused and well-described
+3. **Make your changes**: keep commits focused and well-described
4. **Run tests** before pushing:
```bash
uv run pytest tests/unit/
@@ -198,22 +201,22 @@ repowise/
- For local CLI providers, use `asyncio.create_subprocess_exec` (never `shell=True`), validate user-supplied model names against a safe character set, and resolve paths with `Path.resolve()`
- See `opencode.py` for a clean reference implementation
-2. **Register** in `registry.py` — add to `_BUILTIN_PROVIDERS` and the `_missing` package map
+2. **Register** in `registry.py`: add to `_BUILTIN_PROVIDERS` and the `_missing` package map
3. **Wire up configuration** in these files:
- - `rate_limiter.py` — add `RateLimitConfig` to `PROVIDER_DEFAULTS`
- - `provider_config.py` — add entry to `PROVIDER_CATALOG`
- - `provider_selection.py` — add to `_PROVIDER_DEFAULTS`, `_PROVIDER_ENV`, `_PROVIDER_SIGNUP`, and detection
- - `helpers.py` — add validation in `validate_provider_config()`
+ - `rate_limiter.py`, add `RateLimitConfig` to `PROVIDER_DEFAULTS`
+ - `provider_config.py`, add entry to `PROVIDER_CATALOG`
+ - `provider_selection.py`, add to `_PROVIDER_DEFAULTS`, `_PROVIDER_ENV`, `_PROVIDER_SIGNUP`, and detection
+ - `helpers.py`, add validation in `validate_provider_config()`
-4. **Update the web UI** — add to `PROVIDERS`, `MODEL_PLACEHOLDERS`, and `PROVIDER_ENV_VARS` in `provider-section.tsx` and `run-config-form.tsx`
+4. **Update the web UI**: add to `PROVIDERS`, `MODEL_PLACEHOLDERS`, and `PROVIDER_ENV_VARS` in `provider-section.tsx` and `run-config-form.tsx`
-5. **Add tests** in `tests/unit/test_providers/` — mock the subprocess, test success/error/timeout paths (see `test_codex_cli_provider.py` for the pattern)
+5. **Add tests** in `tests/unit/test_providers/`: mock the subprocess, test success/error/timeout paths (see `test_codex_cli_provider.py` for the pattern)
-6. **Write docs** — `docs/<NAME>.md` and `website/<name>.md`, following `docs/agent/CODEX.md` and `docs/agent/OPENCODE.md`.
+6. **Write docs**: `docs/<NAME>.md` and `website/<name>.md`, following `docs/agent/CODEX.md` and `docs/agent/OPENCODE.md`.
-Adding a new language or LLM provider has a dedicated recipe — see
-[docs/layers/LANGUAGE_SUPPORT.md](../docs/layers/LANGUAGE_SUPPORT.md).
+Adding a new language has a dedicated recipe, see
+[docs/architecture/language-support.md](../docs/architecture/language-support.md).
## Testing
diff --git a/README.md b/README.md
index 12c9277e7..9613b590e 100644
--- a/README.md
+++ b/README.md
@@ -101,7 +101,7 @@ Because the exploration work is already done, that phase mostly disappears. Load
one commit's context through `get_context` costs **393 tokens instead of 13,984**
raw, 35.6x fewer. In a measured agent loop, across 43 questions on `django/django`,
that is worth **-31.6% of the agent's own output tokens** (p&lt;0.0001), reached in
-**3.8 tool calls against a bare agent's 7.2** — roughly one answered question
+**3.8 tool calls against a bare agent's 7.2**, roughly one answered question
replacing six greps. The saving grows with how much of the codebase the task
touches. CodeGraph is a genuine second here at -24.4%: we lead a field in which
more than one tool works.
@@ -128,7 +128,7 @@ queryable from the CLI, the MCP tools, and the local dashboard.
| Layer | What it gives you | Edge |
|---|---|---|
-| **◈ Graph** | Dependency graph across 19 languages · file + symbol nodes · 3-tier call resolution · Leiden communities · PageRank and execution flows · route→handler edges across 22 frameworks | A real graph most tools never build |
+| **◈ Graph** | Dependency graph across 19 languages · file + symbol nodes · confidence-scored call resolution · Leiden communities · PageRank and execution flows · route→handler edges across 22 frameworks | A real graph most tools never build |
| **◈ Git** | Hotspots (decayed churn + activity floors) · ownership % · co-change pairs (hidden coupling) · bus factor · which files actually get bug-fixed, and how recently | Behavioural signals static analysis cannot see |
| **◈ Docs** | A generated wiki page per module and file · rebuilt incrementally every commit · freshness and confidence scoring · hybrid search (full-text + vector) · selectable style and output language | Stays current instead of rotting |
| **◈ Decisions** | Architectural decisions mined from five sources, evidence-backed, each traced to a verbatim source span and stamped exact / fuzzy / unverified | **★ Captured nowhere else** |
@@ -144,6 +144,8 @@ from the CLI or right in the dashboard with the cost shown before you confirm.
during doc generation needs a provider.)
Full detail on every layer: **[docs/layers/INTELLIGENCE_LAYERS.md →](docs/layers/INTELLIGENCE_LAYERS.md)**
+How the graph resolves an edge, and how much to trust one:
+**[docs/layers/GRAPH.md →](docs/layers/GRAPH.md)**
---
@@ -249,14 +251,14 @@ every file, locates where the risk concentrates, and then names the specific fix
Every file is scored 1-10 by **49 deterministic detectors** (McCabe complexity, brain
methods, LCOM4 cohesion, god classes, native Rabin-Karp clone detection, untested
hotspots, change entropy, prior-defect history and more), split into three lenses:
-**defect risk**, **maintainability**, and **performance** — static N+1 and I/O-in-loop
+**defect risk**, **maintainability**, and **performance**: static N+1 and I/O-in-loop
risk traced *across* files through the call graph, where file-local linters found **0**
of the cross-function cases and repowise surfaced ~90. Only **26** of the 49 are
permitted to move the defect number, because that is the number carrying published
accuracy claims.
> **Zero LLM calls, zero cloud, zero new runtime dependencies.** Pure Python over
-> tree-sitter and git data, **under 30 seconds** on a 3,000-file repo — a budget
+> tree-sitter and git data, **under 30 seconds** on a 3,000-file repo, a budget
> enforced by a CI test, not an estimate. Marker weights are **calibrated against a
> real defect corpus, not hand-tuned**: every file scored at a commit preceding the
> bug window so nothing leaks backward, and an L2-logistic fit with file size as an
@@ -267,7 +269,7 @@ accuracy claims.
repowise checks its own flags against your git history and reports what it found:
*"16 of the 20 lowest-health files had a bug fix in the last 6 months, 3.3x the 24%
baseline."* If that number is bad on your codebase, you will see it. (It is an
-association on your indexed history, not a forward prediction — the leakage-free
+association on your indexed history, not a forward prediction, the leakage-free
version is [in the benchmarks](docs/BENCHMARKS.md#5-code-health-predicts-defects).)
Then it names the fix. Not "this class is too big", but **Extract Class**, **Extract
@@ -439,9 +441,15 @@ dependencies (including `index.html` → `src/main.ts`), and OpenAPI, Protobuf,
GraphQL, Dockerfile, Terraform and friends get dedicated handlers. Anything else is
still tracked through git history: blame, hotspots, co-change.
-Adding a language takes **one `.scm` query file and one config entry**, with no changes
-to the parser core. Full matrix and the contributor recipe:
-**[docs/layers/LANGUAGE_SUPPORT.md →](docs/layers/LANGUAGE_SUPPORT.md)**
+Every call edge is stamped with **how it was resolved and how much to trust it**, from
+`same_file` at 0.95 down to a repo-wide name match at 0.50, labelled as the guess it is
+([how that works](docs/layers/GRAPH.md)).
+Adding a language takes five small steps and **no changes to the parser core**.
+
+Full matrix: **[docs/layers/LANGUAGE_SUPPORT.md →](docs/layers/LANGUAGE_SUPPORT.md)** ·
+The graph itself: **[docs/layers/GRAPH.md →](docs/layers/GRAPH.md)** ·
+Contributor recipe and internals:
+**[docs/architecture/language-support.md →](docs/architecture/language-support.md)**
---
@@ -615,7 +623,7 @@ The full page carries the rows we lose beside the rows we win.
at -24.4%: more than one tool here works, and we lead the field rather than
being alone in it.
- **Fewer steps to get there.** 3.8 tool calls where the bare agent needed 7.2,
- and 3.0 files opened instead of 7.2 — the mechanism behind the token saving,
+ and 3.0 files opened instead of 7.2, the mechanism behind the token saving,
visible directly rather than inferred.
**[The full results, the methodology, and the rows we lose →](docs/BENCHMARKS.md)**
@@ -670,7 +678,7 @@ August 2026. Unmarked rows are capability presence, not measurements.</sub>
| **Defects found at a 20% review budget** *([measured](docs/BENCHMARKS.md#5-code-health-predicts-defects), 2,770 files)* | ✅ **0.173** | 0.074 |
| **Effort-aware ranking, Popt** *(measured, p=0.003)* | ✅ **0.607** | 0.462 |
| **Precision at that budget** *(measured)* | 0.580 | ✅ **0.636**, a shorter list |
-| **Discrimination, ROC AUC** *(measured, paired)* | 0.731 | 0.705 — *p=0.054, not significant* |
+| **Discrimination, ROC AUC** *(measured, paired)* | 0.731 | 0.705, *p=0.054, not significant* |
| Defect-prediction AUC, published and reproducible | ✅ 0.737 over 21 repos, held-out 0.76-0.78 | ✅ Code Red study |
| Business impact (resolution time) | ❌ *we could not replicate this on open data* | ✅ Code Red study |
| Git intelligence (hotspots, ownership, co-change) | ✅ | ✅ |
diff --git a/docs/README.md b/docs/README.md
index 50a073a44..370247479 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -55,9 +55,10 @@ your agent in under five minutes, with no API key.
| [layers/CHANGE_RISK.md](layers/CHANGE_RISK.md) | Score any commit or `base..HEAD` range 0-10 for defect risk |
| [layers/BUG_HISTORY.md](layers/BUG_HISTORY.md) | Which files and symbols actually get bug-fixed, and how recently |
| [layers/TEST_INTELLIGENCE.md](layers/TEST_INTELLIGENCE.md) | Coverage ingestion, untested hotspots, and running only the tests a diff touches |
+| [layers/GRAPH.md](layers/GRAPH.md) | The dependency graph: what is in it, how every edge is resolved, and how much to trust each one |
| [layers/DECISIONS.md](layers/DECISIONS.md) | Architectural decisions mined from your repo and from your own agent sessions |
| [layers/DEAD_CODE.md](layers/DEAD_CODE.md) | Unreachable files, unused exports, and zombie packages by confidence tier |
-| [layers/LANGUAGE_SUPPORT.md](layers/LANGUAGE_SUPPORT.md) | What works per language, across 18 parsed languages and 13 at the Full tier |
+| [layers/LANGUAGE_SUPPORT.md](layers/LANGUAGE_SUPPORT.md) | What works per language, across 19 parsed languages and 13 at the Full tier |
| [layers/WIKI.md](layers/WIKI.md) | The generated wiki: page types, what `update` re-renders, styles, output language |
## Scale it
diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md
index ff2fee4aa..5da0f2a07 100644
--- a/docs/architecture/ARCHITECTURE.md
+++ b/docs/architecture/ARCHITECTURE.md
@@ -14,10 +14,10 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
| Package | README | What it covers |
|---------|--------|----------------|
-| `packages/core` | [`packages/core/README.md`](../../packages/core/README.md) | Ingestion, generation, persistence, providers — all key classes with code examples |
+| `packages/core` | [`packages/core/README.md`](../../packages/core/README.md) | Ingestion, generation, persistence, providers; all key classes with code examples |
| `packages/cli` | [`packages/cli/README.md`](../../packages/cli/README.md) | CLI entrypoints and flags; full surface in [`CLI_REFERENCE.md`](../reference/CLI_REFERENCE.md) |
| `packages/server` | [`packages/server/README.md`](../../packages/server/README.md) | All REST API endpoints, 11 MCP tools, webhook setup, scheduler jobs |
-| `packages/web` | [`packages/web/README.md`](../../packages/web/README.md) | Every frontend file with purpose — API client, hooks, components, pages |
+| `packages/web` | [`packages/web/README.md`](../../packages/web/README.md) | Every frontend file with purpose, API client, hooks, components, pages |
---
@@ -27,8 +27,8 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
2. [Repository Structure](#2-repository-structure)
3. [The Three Stores](#3-the-three-stores)
4. [Provider Abstraction Layer](#4-provider-abstraction-layer)
-5. [Init Path — First-Time Documentation](#5-init-path--first-time-documentation)
-6. [Maintenance Path — Keeping Docs in Sync](#6-maintenance-path--keeping-docs-in-sync)
+5. [Init Path: First-Time Documentation](#5-init-path-first-time-documentation)
+6. [Maintenance Path: Keeping Docs in Sync](#6-maintenance-path-keeping-docs-in-sync)
7. [Git Intelligence](#7-git-intelligence)
8. [Dead Code Detection](#8-dead-code-detection)
9. [Decision Intelligence](#9-decision-intelligence)
@@ -94,9 +94,9 @@ For per-package detail (installation, full API reference, all CLI flags, file ma
repowise has two operational modes that share the same core engine but follow
different strategies:
-- **Init** — first-time documentation of an existing codebase. May take minutes
+- **Init**: first-time documentation of an existing codebase. May take minutes
to hours on large repos. Resumable. Supports batch API for cheaper generation.
-- **Maintenance** — incremental updates triggered by git commits. Runs in seconds
+- **Maintenance**: incremental updates triggered by git commits. Runs in seconds
to minutes. Uses change propagation through the dependency graph to only regenerate
what actually changed.
@@ -111,10 +111,10 @@ repowise/
│ │ ├── src/repowise/core/
│ │ │ ├── ingestion/
│ │ │ │ ├── traverser.py # file tree walking + gitignore + per-dir .repowiseIgnore + extra exclude patterns
-│ │ │ │ ├── parser.py # ASTParser — one class, all languages; _extract_calls(), _extract_import_bindings()
+│ │ │ │ ├── parser.py # ASTParser: one class, all languages; _extract_calls(), _extract_import_bindings()
│ │ │ │ ├── parsers/ # per-language parser helpers
│ │ │ │ ├── graph.py # NetworkX dep graph builder; add_file(), _resolve_calls(), file_subgraph()
-│ │ │ │ ├── call_resolver.py # CallResolver — 3-tier call resolution engine (NEW)
+│ │ │ │ ├── call_resolver.py # CallResolver: origin-stamped call resolution
│ │ │ │ ├── change_detector.py # git diff + change propagation
│ │ │ │ ├── git_indexer.py # git history mining → git_metadata table
│ │ │ │ ├── special_handlers.py # OpenAPI, Protobuf, GraphQL, Dockerfile, CI YAML
@@ -135,7 +135,7 @@ repowise/
│ │ │ │ └── claude_md.py # ClaudeMdGenerator subclass
│ │ │ ├── pipeline/
│ │ │ │ ├── orchestrator.py # run_pipeline(), PipelineResult
-│ │ │ │ ├── persist.py # persist_pipeline_result() — shared by CLI + server
+│ │ │ │ ├── persist.py # persist_pipeline_result(): shared by CLI + server
│ │ │ │ └── progress.py # ProgressCallback protocol + LoggingProgressCallback
│ │ │ ├── persistence/
│ │ │ │ ├── models.py # SQLAlchemy ORM models
@@ -174,7 +174,7 @@ repowise/
│ │ ├── routers/ # FastAPI routers (repos, pages, jobs, symbols, graph, git, dead-code, decisions, search, claude-md)
│ │ ├── mcp_server/ # MCP server package (11 default tools, split into focused modules)
│ │ ├── webhooks/ # GitHub + GitLab handlers
-│ │ ├── job_executor.py # Background pipeline executor — bridges REST endpoints to core pipeline
+│ │ ├── job_executor.py # Background pipeline executor: bridges REST to core pipeline
│ │ └── scheduler.py # APScheduler background jobs
│ │
│ ├── cli/ # Python: repowise CLI (click + rich)
@@ -208,7 +208,7 @@ repowise/
## 3. The Three Stores
-repowise uses three separate storage systems. They are not redundant — each answers
+repowise uses three separate storage systems. They are not redundant; each answers
a fundamentally different kind of question that the other two cannot answer efficiently.
### 3.1 SQL Store (SQLAlchemy + SQLite / PostgreSQL)
@@ -217,7 +217,7 @@ a fundamentally different kind of question that the other two cannot answer effi
The source of truth for all structured data. SQLite in development and single-server
deployments; PostgreSQL for multi-worker production deployments. The schema is identical
-for both — SQLAlchemy abstracts the difference.
+for both, SQLAlchemy abstracts the difference.
Key tables:
@@ -244,8 +244,8 @@ If you delete the SQL store, you lose everything and must re-run `repowise init`
repowise uses a `VectorStore` abstraction with two backends, selected automatically
based on the configured SQL backend:
-**LanceDB (default — SQLite mode)**
-LanceDB runs embedded as a library — no separate server process. Data is stored in
+**LanceDB (default: SQLite mode)**
+LanceDB runs embedded as a library, no separate server process. Data is stored in
`.repowise/lancedb/` using the Lance columnar format. This makes self-hosting trivial
and keeps the Docker setup simple. LanceDB is significantly faster than ChromaDB on
both write throughput (batch embedding) and ANN query latency, and it requires no
@@ -254,7 +254,7 @@ C++ build tools to install.
**pgvector (PostgreSQL mode)**
When repowise is configured with a PostgreSQL database, the `wiki_pages` table gains
an `embedding vector(N)` column via the `pgvector` PostgreSQL extension. Embeddings
-are stored directly in the same SQL database — no second storage system required.
+are stored directly in the same SQL database, no second storage system required.
Vector similarity search uses `<=>` (cosine distance) with an HNSW index. This is
the preferred backend for multi-worker production deployments.
@@ -264,7 +264,7 @@ The vector store is used in two distinct ways:
**During generation (RAG context):** When generating a wiki page for file A, the
`ContextAssembler` queries the vector store with A's exported symbol names to find
pages for files that A imports from. These are included as context in the generation
-prompt. Each generated page is aware of what its dependencies actually *do* —
+prompt. Each generated page is aware of what its dependencies actually *do*,
not just their names. See [Section 5.4](#54-context-assembly) for details.
**During search and MCP queries:** The `search_codebase` MCP tool and the web UI
@@ -273,9 +273,9 @@ natural language query. This is better than full-text search for questions like
"how does authentication work?" or "where is rate limiting handled?".
If you delete the vector store (LanceDB directory or pgvector embeddings), search
-quality degrades and generation context becomes shallower — rebuild it by running
+quality degrades and generation context becomes shallower; rebuild it by running
`repowise reindex` which re-embeds all existing SQL pages into LanceDB using
-the configured embedder (Gemini or OpenAI). No LLM calls — only embedding API calls.
+the configured embedder (Gemini or OpenAI). No LLM calls, only embedding API calls.
### 3.3 Graph Store (NetworkX / SQLite-backed)
@@ -295,22 +295,22 @@ table includes a `kind` column (file, symbol, package, external) and `confidence
The graph is used for:
-- **Generation ordering** — topological sort determines what to generate first
+- **Generation ordering**: topological sort determines what to generate first
(files with no dependents get generated before files that import them, so the
richer context is available via RAG when the importing file is generated)
-- **Change propagation** — when a file changes, walk the graph to find all
+- **Change propagation**: when a file changes, walk the graph to find all
pages that reference its symbols and mark them as stale
-- **PageRank** — runs on `file_subgraph()` (file + package nodes only) to identify
+- **PageRank**: runs on `file_subgraph()` (file + package nodes only) to identify
the most central files; these get "spotlight" wiki pages and richer generation prompts
-- **SCC detection** — circular dependency clusters require a special generation
- strategy (see [Section 5.3](#53-circular-dependencies))
-- **Co-change edges** — temporal coupling from git history. Files that frequently
+- **SCC detection**: circular dependency clusters require a special generation
+ strategy (see [Section 5.3](#53-dependency-graph-construction))
+- **Co-change edges**: temporal coupling from git history. Files that frequently
change together (but may have no import relationship) get `co_changes` edges.
These participate in change propagation and are shown in the graph visualization
as dashed purple lines. They do NOT affect PageRank.
-- **Dead code detection** — files with `in_degree == 0` (no importers) are
+- **Dead code detection**: files with `in_degree == 0` (no importers) are
candidates for unreachable file detection
-- **MCP `get_dependency_path` tool** *(opt-in)* — answers "how is module A connected to module B?"
+- **MCP `get_dependency_path` tool** *(opt-in)*: answers "how is module A connected to module B?"
- **D3 graph visualization** in the web UI
If you delete the graph, repowise loses change propagation and generation ordering.
@@ -368,11 +368,11 @@ on large repos is typically 60–90%.
### 4.3 Adding a Provider
Implement `LLMProvider`, add an entry to `LANGUAGE_CONFIGS` in `providers/registry.py`,
-and add a section to `.repowise/config.yaml`. See [Section 12](#12-adding-a-new-llm-provider).
+and add a section to `.repowise/config.yaml`. See [Section 17](#17-adding-a-new-llm-provider).
---
-## 5. Init Path — First-Time Documentation
+## 5. Init Path: First-Time Documentation
`repowise init` runs when documenting a codebase for the first time. It is the
expensive, one-time operation that builds the full wiki from scratch.
@@ -385,12 +385,12 @@ priority order:
1. `.gitignore` (parsed with `pathspec`, not simple glob matching)
2. Root `.repowiseIgnore` (same syntax, user-defined at repo root)
-3. **Per-directory `.repowiseIgnore`** — loaded from each directory visited during
+3. **Per-directory `.repowiseIgnore`**: loaded from each directory visited during
the `os.walk`. Patterns are relative to the directory containing the file (like
git's per-directory `.gitignore`). A spec per directory is loaded once and cached
for the traversal. Example: `generated/` in `src/.repowiseIgnore` skips
`src/generated/` without affecting other directories with the same name.
-4. **`extra_exclude_patterns`** (constructor param) — additional gitignore-style
+4. **`extra_exclude_patterns`** (constructor param): additional gitignore-style
patterns passed at runtime from `--exclude/-x` CLI flags or
`repo.settings["exclude_patterns"]` (set via Web UI or REST API PATCH). Applied
to both directory pruning (entire subtree skipped) and individual file filtering.
@@ -453,16 +453,16 @@ per-language subclasses.
**The `.scm` query files** use standard tree-sitter S-expression syntax with
consistent capture name conventions across all languages:
-- `@symbol.def` — the full symbol node
-- `@symbol.name` — the name identifier
-- `@symbol.params` — parameter list
-- `@symbol.return_type` — return type annotation
-- `@symbol.docstring` — existing docstring (expanded, not repeated, by the LLM)
-- `@import.statement` — full import node
-- `@import.module` — the module being imported
+- `@symbol.def`: the full symbol node
+- `@symbol.name`: the name identifier
+- `@symbol.params`: parameter list
+- `@symbol.return_type`: return type annotation
+- `@symbol.docstring`: existing docstring (expanded, not repeated, by the LLM)
+- `@import.statement`: full import node
+- `@import.module`: the module being imported
**Adding a new language** = write one `.scm` file + add one entry to `LANGUAGE_CONFIGS`.
-No changes to `ASTParser` itself. See [Section 11](#11-adding-a-new-language).
+No changes to `ASTParser` itself. See [Section 16](#16-adding-a-new-language).
**Special handlers** live in `core/special_handlers/` and are separate from `ASTParser`.
They handle file types that are not programming languages (OpenAPI specs, Dockerfiles,
@@ -475,37 +475,60 @@ instead of tree-sitter.
`GraphBuilder` takes all `ParsedFile` outputs and builds a `networkx.DiGraph`.
**Node types:**
-- `file` — every source file
-- `symbol` — every function, class, method, interface, etc. (added via `add_file()`)
-- `package` — every package/module directory
-- `external` — third-party packages (lightweight node, not fully documented)
-
-**Edge types:**
-- `imports` — file A imports from file B
-- `DEFINES` — file A defines symbol B
-- `HAS_METHOD` — class A has method B
-- `CALLS` — symbol A calls symbol B (with confidence score 0.0–1.0)
-- `inherits` — class A extends class B
-- `implements` — class A implements interface B
-- `instantiates` — code in A creates an instance of B
-- `references` — looser reference (type annotation, generic, etc.)
-- `re-exports` — A re-exports symbols from B (barrel files)
-- `inter_package` — edge crossing package boundary (monorepos)
-- `co_changes` — A and B frequently change in the same commit (from git history,
+- `file`: every source file
+- `symbol`: every function, class, method, interface, etc. (added via `add_file()`)
+- `package`: every package/module directory
+- `external`: third-party packages (lightweight node, not fully documented)
+
+**Edge types.** User-facing walkthrough: [docs/layers/GRAPH.md](../layers/GRAPH.md).
+`EdgeType` in `ingestion/models.py` is the source of truth, a
+closed `Literal` of 17 values, with `EDGE_TYPE_VALUES` derived from it at runtime
+and pinned by `tests/unit/ingestion/test_edge_type_vocabulary.py`. The ones whose
+meaning is easy to get wrong:
+
+- `imports`: file A imports from file B
+- `defines` / `has_method`: file A defines symbol B; class A has method B
+- `calls`: symbol A calls symbol B. Carries a confidence and a
+ `ResolutionOrigin` naming how it was resolved
+- `extends` / `implements` / `method_implements`: heritage, implementor →
+ interface
+- `dispatches_to`: base method → an implementation that *could* answer for it.
+ Points the other way from `method_implements`, and compares no signature, so it
+ is a possible dispatch target rather than a proven override
+- `references`: something holds a handle to a function (dispatch table, callback
+ field, registration macro). Not a claim that it is ever invoked
+- `framework` / `framework_binds`: framework wiring, file-level and symbol-level.
+ Deliberately never `calls`: nothing here is source the parser could have seen
+- `reads`: a data reference, file → file (C# member access). File-level only
+- `type_use`: file → file, from a constructor / method / delegate / record
+ parameter type reference. Weighted below `imports`
+- `dynamic_uses` / `dynamic_imports` / `dynamic_url_route`: dynamic-dispatch
+ hints, prefixed by kind. A consumer matching bare `"dynamic"` matches none
+- `co_changes`: A and B frequently change in the same commit (from git history,
added by `GitIndexer` after graph construction). Weight = co-change count.
Filtered out of PageRank but included in change propagation and visualization.
**Call resolution** is handled by the `CallResolver` module (`ingestion/call_resolver.py`),
-which runs after the static import graph is built. It operates in three tiers:
-
-1. **Same-file resolution** (confidence 0.95) — call target defined in the same file
-2. **Import-scoped resolution** (confidence 0.85–0.93) — target matched via named bindings
- from the file's import list
-3. **Global unique match** (confidence 0.50) — target is unique across the whole repo
-
-Call sites are extracted by tree-sitter for all 14 supported languages (Python, TypeScript,
-JavaScript, Go, Rust, Java, C++, C, Kotlin, Ruby, C#, Swift, Scala, PHP) using per-language `.scm` query files. Results are stored
-as `CallSite` dataclasses and become `CALLS` edges in the graph.
+which runs after the static import graph is built. Every edge it emits is stamped
+with a `ResolutionOrigin`, a closed vocabulary of 29 values in
+`ingestion/models.py`, each carrying exactly one confidence, so the origin
+distribution and the confidence histogram are two views of the same data. The
+span runs from `same_file` and `self_scope` at 0.95, through import- and
+package-scoped origins at 0.88–0.90, down to `global_unique` at 0.50, a
+repo-wide name match, which the source comments label as a guess.
+
+Twelve of the 29 are **receiver-typing** origins: they resolve a call on a
+variable by reading the variable's declaration (a local, a parameter, an
+enclosing class's field, or a type a framework decorator imposed), then resolving
+the method on that type. Registered for Java, C#, Python, Go, Kotlin and Swift.
+Language-specific tiers live behind the `_LANGUAGE_CALL_STRATEGIES` seam, so a
+package tier can claim `pkg.Func()` before a weaker shared tier reaches it.
+
+Call sites are extracted by tree-sitter for every AST-parsed language using
+per-language `.scm` query files. Results are stored as `CallSite` dataclasses and
+become `calls` edges in the graph. See
+[language-support.md](language-support.md#call-resolution) for the full
+architecture.
**Named binding resolution** (`NamedBinding` dataclass in `ingestion/models.py`) ensures
that aliased imports, barrel re-exports, and namespace imports resolve to the correct
@@ -523,13 +546,13 @@ scores.
After graph construction, the builder computes:
-- **PageRank** — nodes with high PageRank are central and well-connected.
+- **PageRank**: nodes with high PageRank are central and well-connected.
Used to decide generation priority and which symbols get spotlight pages.
-- **Strongly Connected Components (SCCs)** — groups of files with circular imports.
+- **Strongly Connected Components (SCCs)**: groups of files with circular imports.
Logged as warnings. Require special generation handling (see below).
-- **Betweenness centrality** — identifies "bridge" symbols whose removal would
+- **Betweenness centrality**: identifies "bridge" symbols whose removal would
disconnect the graph. These are the most critical to document well.
-- **Community detection (Louvain)** — discovers logical modules even when the
+- **Community detection (Louvain)**: discovers logical modules even when the
directory structure doesn't reflect them. These communities become module pages.
**Circular dependency handling:**
@@ -549,44 +572,44 @@ For repos with fewer than 30K nodes, the graph lives in memory as a NetworkX
For repos exceeding 30K nodes (configurable via `graph_backend: sqlite`), repowise
switches to `networkit` with SQLite backing via the `graph_nodes` and `graph_edges`
tables. Only the subgraph needed for each operation is loaded into memory. The
-API is identical — this is transparent to all callers.
+API is identical; this is transparent to all callers.
### 5.4 Context Assembly
This is the most important quality driver in the system. The `ContextAssembler`
-builds the prompt context for each generation call — it does not just dump the
+builds the prompt context for each generation call; it does not just dump the
raw source file.
For a given file page, it assembles context in this priority order (dropping
lower-priority items if the token budget is exceeded):
-1. **Source code** — full source (or chunked if file is large)
-2. **Symbol signatures** — all symbols extracted from this file with their
+1. **Source code**: full source (or chunked if file is large)
+2. **Symbol signatures**: all symbols extracted from this file with their
signatures and existing docstrings
-3. **Graph context** — PageRank score, cluster membership, which module this
+3. **Graph context**: PageRank score, cluster membership, which module this
belongs to, entry point status
-4. **Git context** — ownership, significant commit messages explaining *why* code
+4. **Git context**: ownership, significant commit messages explaining *why* code
evolved, hotspot/stable classification, co-change partners. This transforms
documentation from "here is what this code does" into "here is what it does
and why it was written this way." Git context is the last thing dropped when
- over budget — it is more valuable than import summaries.
-5. **Import summaries** — for each file this file imports from: the summary of
+ over budget; it is more valuable than import summaries.
+5. **Import summaries**: for each file this file imports from: the summary of
that file's already-generated wiki page (if available), or just its public
API signatures (if not yet generated)
-6. **RAG context** — vector store similarity search (LanceDB or pgvector) using this file's top exported
+6. **RAG context**: vector store similarity search (LanceDB or pgvector) using this file's top exported
symbols as the query. Returns the top 3 most relevant already-generated pages.
This propagates understanding upward: `AuthService`'s page will know what
`UserRepository` actually does, not just that it imports from it.
-7. **Co-change context** — wiki pages for co-change partners (files that change
+7. **Co-change context**: wiki pages for co-change partners (files that change
together without an import relationship). Reveals hidden coupling.
-8. **Dead code findings** — symbols in this file flagged as unused (if any).
+8. **Dead code findings**: symbols in this file flagged as unused (if any).
Listed in the generation prompt so the LLM notes them as cleanup candidates.
-9. **Reverse import context** — which files import *this* file, and what they
+9. **Reverse import context**: which files import *this* file, and what they
use from it. Helps the LLM understand how this file is used in practice.
Token budget: the total assembled context targets 12K tokens, leaving room for
the generation output. Items are dropped in reverse priority order when over budget.
-The source code is never dropped — it is chunked instead if too large.
+The source code is never dropped; it is chunked instead if too large.
**Large file chunking:**
@@ -599,7 +622,7 @@ Pages generated from chunks are tagged `chunked: true` in metadata.
### 5.5 Hierarchical Generation Order
-Generation must follow a strict dependency-aware order. This is not optional —
+Generation must follow a strict dependency-aware order. This is not optional,
generating a module page before its file pages means the module page has no
content to draw from.
@@ -647,10 +670,10 @@ Init on a 50K-file repo can take 30–90 minutes. A crash or network interruptio
should not require starting over.
The `JobSystem` persists checkpoint state after every completed page:
-- `checkpoint_level` — which generation level is currently active
-- `checkpoint_file_index` — position within the current level
-- `completed_page_ids` — list of already-generated page IDs
-- `failed_page_ids` — pages that failed (retried on resume)
+- `checkpoint_level`: which generation level is currently active
+- `checkpoint_file_index`: position within the current level
+- `completed_page_ids`: list of already-generated page IDs
+- `failed_page_ids`: pages that failed (retried on resume)
On `repowise init --resume`, the set of already-written pages is read from the
vector store rather than from the checkpoint, because the store is the one
@@ -670,7 +693,7 @@ Running it after a partial previous run completes only the remaining pages.
The persistence logic for storing a `PipelineResult` into the database (graph nodes,
edges, symbols, pages, git metadata, dead code findings, decision records) was
extracted from the CLI's `init_cmd.py` into `core/pipeline/persist.py`. Both the
-CLI and the server's background job executor call `persist_pipeline_result()` — zero
+CLI and the server's background job executor call `persist_pipeline_result()`, zero
duplication.
FTS indexing is intentionally excluded from this function. Callers must run it
@@ -707,7 +730,7 @@ The pipeline orchestrator now keeps the event loop responsive during CPU-bound w
---
-## 6. Maintenance Path — Keeping Docs in Sync
+## 6. Maintenance Path: Keeping Docs in Sync
`repowise update` runs after a git push (triggered by webhook, GitHub Action, or
polling fallback). It is fast, targeted, and avoids regenerating pages that
@@ -802,7 +825,7 @@ uses a two-layer sync strategy:
**Layer 1 (real-time):** GitHub/GitLab webhook → `POST /api/webhooks/github` →
signature verification → store in `webhook_events` → enqueue `GenerationJob`.
-Response is always `200 OK` immediately — processing is async.
+Response is always `200 OK` immediately; processing is async.
**Layer 2 (polling fallback):** APScheduler job runs every 15 minutes (configurable).
Compares `repos.last_sync_commit` against actual `HEAD` via GitHub API or GitPython.
@@ -840,26 +863,26 @@ On merge, the actual incremental update runs.
repowise mines git history to make documentation significantly richer and more useful.
The `GitIndexer` runs once during `repowise init` (after graph construction, before
generation) and incrementally during `repowise update`. All git features degrade
-gracefully when git metadata is unavailable — they simply skip git-enriched context.
+gracefully when git metadata is unavailable; they simply skip git-enriched context.
### 7.1 GitIndexer (`packages/core/ingestion/git_indexer.py`)
The `GitIndexer` class mines git history into the `git_metadata` SQL table. For each
tracked file, it computes:
-- **Commit volume** — total, last 90 days, last 30 days (churn signals)
-- **Timeline** — first and last commit dates (file age)
-- **Ownership** — primary owner from `git blame` (who wrote the most lines),
+- **Commit volume**: total, last 90 days, last 30 days (churn signals)
+- **Timeline**: first and last commit dates (file age)
+- **Ownership**: primary owner from `git blame` (who wrote the most lines),
top 3 contributors by commit count
-- **Significant commits** — up to 50 meaningful commit messages (filtered: no merges,
+- **Significant commits**: up to 50 meaningful commit messages (filtered: no merges,
no dependency bumps, no chore/ci, messages > 20 chars). These explain *why*
the code evolved this way and are included in generation prompts.
-- **Co-change partners** — files that changed in the same commit >= 3 times, even
+- **Co-change partners**: files that changed in the same commit >= 3 times, even
without an import relationship. Reveals hidden structural coupling.
-- **Derived signals** — `is_hotspot` (top-quartile decayed churn AND absolute
+- **Derived signals**: `is_hotspot` (top-quartile decayed churn AND absolute
activity floors: >= 3 commits in 90d with real line movement), `is_stable`
(>10 commits, 0 in 90 days), `churn_percentile` (0.0–1.0 **as stored**;
- normalized to 0–100 at the HTTP and MCP boundaries — see
+ normalized to 0–100 at the HTTP and MCP boundaries; see
`code-health.md` §5.1. The one exception is `get_risk.hotspot_score`, which
deliberately passes the stored 0–1 through under its own name.)
@@ -914,7 +937,7 @@ hotspot count, stable file count, top churn files, oldest file.
## 8. Dead Code Detection
repowise detects unreachable files, unused exports, and zombie packages using
-graph traversal and SQL queries. No LLM calls — the analysis completes in < 10
+graph traversal and SQL queries. No LLM calls; the analysis completes in < 10
seconds for any repo size.
### 8.1 DeadCodeAnalyzer (`packages/core/analysis/dead_code.py`)
@@ -923,12 +946,12 @@ The analyzer runs after `GitIndexer` during init (Step 3.6) and optionally durin
`repowise update`. It produces findings with confidence scores:
**Finding types:**
-- `unreachable_file` — file with `in_degree == 0`, not an entry point, test, or config
-- `unused_export` — public symbol with no incoming edges (but file IS imported)
-- `unused_internal` — private symbol with no `calls` edges from same file
-- `zombie_package` — monorepo package with no incoming `inter_package` edges
+- `unreachable_file`: file with `in_degree == 0`, not an entry point, test, or config
+- `unused_export`: public symbol with no incoming edges (but file IS imported)
+- `unused_internal`: private symbol with no `calls` edges from same file
+- `zombie_package`: monorepo package with no incoming `inter_package` edges
-**Confidence scoring (conservative — when in doubt, do NOT flag):**
+**Confidence scoring (conservative: when in doubt, do NOT flag):**
- Unreachable + no commits in 90d + last commit > 1 year → 1.0
- Unreachable + no commits in 90d + last commit > 6 months → 0.9
- Unreachable + no commits in 90d + last commit > 90 days → 0.8
@@ -943,7 +966,7 @@ The analyzer runs after `GitIndexer` during init (Step 3.6) and optionally durin
**Never flagged as dead:**
- `__init__.py` public re-exports
-- `@pytest.fixture`, `@pytest.mark.*` symbols
+- `@pytest.fixture`: `@pytest.mark.*` symbols
- Files matching `*migrations*`, `*schema*`, `*seed*`
- TypeScript `.d.ts` files
- Files where `is_api_contract == True`
@@ -985,7 +1008,7 @@ dashed borders to dead code nodes.
## 9. Decision Intelligence
-The Decision Intelligence layer captures **architectural decisions** — the *why* behind how
+The Decision Intelligence layer captures **architectural decisions**, the *why* behind how
the system is built, what alternatives were rejected, and what constraints exist. While documentation
describes *what*, decisions capture *why*.
@@ -1015,8 +1038,8 @@ are flagged as stale.
### MCP Tools
-- `get_why(query?)` — three modes: natural language search over decisions, path-based lookup for decisions governing a file, or no-arg for decision health dashboard (stale decisions, ungoverned hotspots, proposed decisions needing review)
-- `get_context(targets, include?)` — includes decisions governing each target in its response
+- `get_why(query?)`: natural language search over decisions, path-based lookup for decisions governing a file, or no-arg for decision health dashboard (stale decisions, ungoverned hotspots, proposed decisions needing review)
+- `get_context(targets, include?)`: includes decisions governing each target in its response
### CLI Commands
@@ -1055,8 +1078,8 @@ Instead of calling 5 tools one at a time, it calls `get_context(["src/auth/servi
The server is implemented using the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
and supports two transports:
-- **stdio** — for Claude Code, Cursor, Cline (add to their MCP config)
-- **SSE** — for web-based MCP clients (served on port 7338)
+- **stdio**: for Claude Code, Cursor, Cline (add to their MCP config)
+- **SSE**: for web-based MCP clients (served on port 7338)
### Tools (11 default in single-repo mode)
@@ -1097,26 +1120,26 @@ which client was wired up and how Cursor or Codex connect (`repowise mcp .`).
Served on port `7337` alongside the web UI. All endpoints are prefixed with `/api/`.
Key routers:
-- `/api/repos` — register repos, trigger sync, full-resync (now launches background pipeline jobs with concurrent-run prevention)
-- `/api/pages` — read pages, version history, force-regenerate single page
-- `/api/search` — semantic (LanceDB or pgvector) and full-text (SQLite FTS5 / PostgreSQL tsvector) search
-- `/api/jobs` — job status, SSE stream for live progress updates
-- `/api/symbols` — symbol lookup, dependency path queries
-- `/api/graph` — graph export in D3-compatible JSON format
-- `/api/webhooks/github` — GitHub webhook handler with HMAC verification
-- `/api/webhooks/gitlab` — GitLab webhook handler
-- `/api/repos/{id}/git-metadata` — per-file git metadata
-- `/api/repos/{id}/hotspots` — high-churn + high-complexity files
-- `/api/repos/{id}/ownership` — ownership breakdown (file/module/package granularity)
-- `/api/repos/{id}/co-changes` — co-change partners for a file
-- `/api/repos/{id}/git-summary` — aggregate git health signals for dashboard
-- `/api/repos/{id}/dead-code` — dead code findings (GET list, POST trigger analysis)
-- `/api/repos/{id}/dead-code/summary` — aggregate dead code stats
-- `/api/dead-code/{finding_id}` — PATCH to resolve/acknowledge findings
-- `/api/repos/{id}/claude-md` — GET preview of generated CLAUDE.md section (JSON, no disk write)
-- `/api/repos/{id}/claude-md/generate` — POST to regenerate and write CLAUDE.md to disk
-- `/health` — liveness + readiness (checks DB + provider)
-- `/metrics` — Prometheus-compatible metrics (job counts, token totals, stale count)
+- `/api/repos`: register repos, trigger sync, full-resync (now launches background pipeline jobs with concurrent-run prevention)
+- `/api/pages`: read pages, version history, force-regenerate single page
+- `/api/search`: semantic (LanceDB or pgvector) and full-text (SQLite FTS5 / PostgreSQL tsvector) search
+- `/api/jobs`: job status, SSE stream for live progress updates
+- `/api/symbols`: symbol lookup, dependency path queries
+- `/api/graph`: graph export in D3-compatible JSON format
+- `/api/webhooks/github`: GitHub webhook handler with HMAC verification
+- `/api/webhooks/gitlab`: GitLab webhook handler
+- `/api/repos/{id}/git-metadata`: per-file git metadata
+- `/api/repos/{id}/hotspots`: high-churn + high-complexity files
+- `/api/repos/{id}/ownership`: ownership breakdown (file/module/package granularity)
+- `/api/repos/{id}/co-changes`: co-change partners for a file
+- `/api/repos/{id}/git-summary`: aggregate git health signals for dashboard
+- `/api/repos/{id}/dead-code`: dead code findings (GET list, POST trigger analysis)
+- `/api/repos/{id}/dead-code/summary`: aggregate dead code stats
+- `/api/dead-code/{finding_id}`: PATCH to resolve/acknowledge findings
+- `/api/repos/{id}/claude-md`: GET preview of generated CLAUDE.md section (JSON, no disk write)
+- `/api/repos/{id}/claude-md/generate`: POST to regenerate and write CLAUDE.md to disk
+- `/health`: liveness + readiness (checks DB + provider)
+- `/metrics`: Prometheus-compatible metrics (job counts, token totals, stale count)
**Server lifecycle:**
- On startup, any jobs left in `running` state from a previous server instance are
@@ -1135,15 +1158,15 @@ Served from the same port as the API. All routes under `/`:
|-------|---------|
| `/` | Dashboard: all repos, recent jobs, stale page counts, token usage |
| `/repos/[id]` | Repo layout with file tree sidebar |
-| `/repos/[id]/overview` | **Overview dashboard** — health score ring, attention panel, language donut, ownership treemap, hotspots mini, decisions timeline, module minimap, quick actions, active job banner |
+| `/repos/[id]/overview` | **Overview dashboard**: health score ring, attention panel, language donut, ownership treemap, hotspots mini, decisions timeline, module minimap, quick actions, active job banner |
| `/repos/[id]/wiki/[...slug]` | Individual wiki page with MDX rendering |
| `/repos/[id]/search` | Semantic search results |
| `/repos/[id]/graph` | D3 force-directed dependency graph |
| `/repos/[id]/symbols` | Full symbol index, sortable by PageRank |
| `/repos/[id]/coverage` | Documentation coverage metrics |
-| `/repos/[id]/ownership` | Ownership treemap — files colored by primary owner, sized by LOC |
-| `/repos/[id]/hotspots` | Hotspot list — top 20 files with churn + complexity bars |
-| `/repos/[id]/dead-code` | Dead code report — three tabs: Files, Exports, Internals |
+| `/repos/[id]/ownership` | Ownership treemap: files colored by primary owner, sized by LOC |
+| `/repos/[id]/hotspots` | Hotspot list: top 20 files with churn + complexity bars |
+| `/repos/[id]/dead-code` | Dead code report; three tabs: Files, Exports, Internals |
| `/repos/[id]/decisions` | Architectural decision records |
| `/repos/[id]/chat` | Codebase chat with streaming LLM responses |
| `/settings` | Provider config, polling interval, cascade budget |
@@ -1173,7 +1196,7 @@ repowise includes an interactive chat interface that lets users ask questions ab
their codebase and receive answers grounded in the wiki, dependency graph, git
history, and architectural decisions. The chat agent uses whichever LLM provider
the user has configured and has access to **7 tools** from the MCP surface
-(see [`chat.md`](chat.md) — not the full 11-tool MCP default).
+(see [`chat.md`](chat.md), not the full 11-tool MCP default).
See [`docs/architecture/chat.md`](chat.md) for the full technical reference covering the
backend agentic loop, SSE streaming protocol, provider abstraction extensions,
@@ -1181,18 +1204,18 @@ database schema, frontend component architecture, and artifact rendering system.
**Key design points:**
-- **Provider-agnostic** — the chat agent goes through the same provider abstraction
+- **Provider-agnostic**: the chat agent goes through the same provider abstraction
as documentation generation. A `ChatProvider` protocol extends `BaseProvider` with
`stream_chat()` for streaming + tool use without breaking existing callers.
-- **Tool reuse** — the 7 chat tools are called directly as Python functions (no
+- **Tool reuse**: the 7 chat tools are called directly as Python functions (no
subprocess round-trip). Tool schemas are defined once in `chat_tools.py` and
fed to both the LLM and the executor.
-- **SSE streaming** — `POST /api/repos/{repo_id}/chat/messages` runs the agentic
+- **SSE streaming**: `POST /api/repos/{repo_id}/chat/messages` runs the agentic
loop and streams back Server-Sent Events (`text_delta`, `tool_start`,
`tool_result`, `done`, `error`).
-- **Conversation persistence** — chat history is stored in `conversations` and
+- **Conversation persistence**: chat history is stored in `conversations` and
`chat_messages` tables, allowing replay and continuation across page refreshes.
-- **Artifact panel** — tool results with rich content (wiki pages, Mermaid diagrams,
+- **Artifact panel**: tool results with rich content (wiki pages, Mermaid diagrams,
search results, risk reports) open in a slide-in artifact panel that reuses
existing frontend components.
@@ -1230,7 +1253,7 @@ GitIndexer (if git.enabled)
▼
DeadCodeAnalyzer (if dead_code.enabled)
graph traversal + SQL: unreachable files, unused exports, zombie packages
- pure analysis — no LLM calls, < 10 seconds
+ pure analysis, no LLM calls, < 10 seconds
│
▼
JobSystem
@@ -1253,7 +1276,7 @@ JobSystem
│ ▼
│ WikiPage stored:
│ → SQL (content, metadata, confidence=1.0)
- │ → VectorStore (LanceDB or pgvector — embedding for RAG)
+ │ → VectorStore (LanceDB or pgvector: embedding for RAG)
│ → Graph (node.page_id linked)
│
├── Level 2: file pages (parallel, RAG pool growing with each completed page)
@@ -1383,36 +1406,36 @@ instead of reading 40 files
repowise offers three complementary ways to skip paths during traversal, each solving
a different problem:
-1. **Root `.repowiseIgnore`** — project-wide exclusions committed to the repo (like
+1. **Root `.repowiseIgnore`**: project-wide exclusions committed to the repo (like
`.gitignore`). Shared across all users, version-controlled.
-2. **Per-directory `.repowiseIgnore`** — exclusions that only apply within a subtree.
+2. **Per-directory `.repowiseIgnore`**: exclusions that only apply within a subtree.
Lets a monorepo package owner exclude its own generated output without polluting
the root ignore file. Patterns are relative to the directory, matching git semantics.
Specs are loaded once per directory during `os.walk` and cached by absolute path;
the root spec is pre-seeded in the cache to avoid reading it twice.
-3. **`extra_exclude_patterns` (runtime)** — patterns injected without touching any
+3. **`extra_exclude_patterns` (runtime)**: patterns injected without touching any
file on disk: from `--exclude/-x` CLI flags (dev workflow), from
`config.yaml exclude_patterns` (persisted per repo), or from
`repo.settings["exclude_patterns"]` (Web UI / REST API). This lets teams configure
exclusions through the UI without git access to the target repo.
-All three layers use `pathspec` with `gitwildmatch` semantics — the same library used
-for `.gitignore` parsing — so the full gitignore syntax works everywhere.
+All three layers use `pathspec` with `gitwildmatch` semantics, the same library used
+for `.gitignore` parsing, so the full gitignore syntax works everywhere.
### `save_config()` round-trips YAML, not overwrites
The original `save_config()` wrote a fixed three-key file (`provider`, `model`,
-`embedder`). This meant any other keys — such as `exclude_patterns` set via the Web UI
-— would be silently dropped the next time `repowise init` ran. The updated function
+`embedder`). This meant any other keys, such as `exclude_patterns` set via the Web UI
+, would be silently dropped the next time `repowise init` ran. The updated function
loads the existing config, merges in the new values, then writes the result back.
This ensures all config sources (CLI, Web UI, REST API, manual edits) coexist safely.
### One `ASTParser` class, not one per language
Per-language differences live in `.scm` query files and `LANGUAGE_CONFIGS` dict entries.
-This means adding a new language requires no changes to Python business logic — just
+This means adding a new language requires no changes to Python business logic, just
a new `.scm` file and a config entry. The `ASTParser` class itself never has
`if lang == "python"` branches.
@@ -1422,13 +1445,13 @@ ChromaDB was the original choice but has notable drawbacks: slow write throughpu
large repos, heavy C++ build dependencies (`chroma-hnswlib`), and a bloated dependency
tree. LanceDB replaces it as the default embedded vector store:
-- **No build step** — pure Python wheel, no C++ compiler required on Windows
-- **Faster writes** — Lance columnar format is optimised for batch appends; embedding
+- **No build step**: pure Python wheel, no C++ compiler required on Windows
+- **Faster writes**: Lance columnar format is optimised for batch appends; embedding
50K pages during `repowise init` is measurably faster
-- **Faster queries** — IVF-PQ and HNSW index support with sub-millisecond ANN search
-- **Simpler data model** — tables are Arrow-native; filtering by `repo_id` or `page_type`
+- **Faster queries**: IVF-PQ and HNSW index support with sub-millisecond ANN search
+- **Simpler data model**: tables are Arrow-native; filtering by `repo_id` or `page_type`
uses SQL-style predicates alongside the vector search, no separate metadata store needed
-- **Zero server process** — same embedded story as ChromaDB: data lives in
+- **Zero server process**: same embedded story as ChromaDB: data lives in
`.repowise/lancedb/`, no container needed
When PostgreSQL is already in use (multi-worker prod), **pgvector** is preferred because
@@ -1474,7 +1497,7 @@ catches everything the cascade budget missed.
### Git metadata in generation prompts, not just for display
-The highest-value use of git metadata is enriching the LLM's generation context —
+The highest-value use of git metadata is enriching the LLM's generation context,
not just showing ownership in a sidebar. By including significant commit messages
in the prompt, the LLM can explain *why* code is structured a certain way (e.g.,
"this was refactored in March 2024 to separate auth concerns from the request
@@ -1482,7 +1505,7 @@ pipeline"). This context is unavailable from static analysis alone.
### Co-change edges as a separate graph layer
-Co-change relationships are temporal coupling — they cannot be detected by AST
+Co-change relationships are temporal coupling; they cannot be detected by AST
parsing. repowise adds them as `co_changes` edges after `GitIndexer` runs, but
deliberately filters them out of PageRank computation (they would skew it
artificially toward files that are often edited together for process reasons, not
@@ -1493,7 +1516,7 @@ architectural ones). They participate in change propagation and visualization on
repowise's dead code detector errs heavily toward false negatives. `safe_to_delete`
is set to `True` only at confidence >= 0.7 and after excluding dynamically-loaded
patterns. Dead code analysis is pure graph traversal + SQL (no LLM calls), so it
-completes in seconds and can be re-run cheaply. repowise surfaces candidates —
+completes in seconds and can be re-run cheaply. repowise surfaces candidates,
humans decide before deleting anything.
### Async-first throughout
@@ -1511,7 +1534,7 @@ architecture, all data sources, how the marker-merge system works, and how to ad
support for a new editor file (cursor.md, copilot-instructions.md, etc.).
**Quick summary:** repowise can generate and maintain AI-editor configuration files
-(CLAUDE.md, cursor.md, etc.) from the already-indexed codebase data — no LLM calls.
+(CLAUDE.md, cursor.md, etc.) from the already-indexed codebase data, no LLM calls.
The system uses HTML comment markers to split the file into a user-owned section and
a Repowise-managed section. The user section is never touched.
@@ -1533,11 +1556,11 @@ Key files:
| File | Purpose |
|------|---------|
-| `core/generation/editor_files/base.py` | `BaseEditorFileGenerator` — marker-merge logic shared by all editor-file generators |
-| `core/generation/editor_files/data.py` | `EditorFileData` frozen dataclass — the data contract between fetcher and template |
-| `core/generation/editor_files/fetcher.py` | `EditorFileDataFetcher` — queries DB for architecture summary, modules, hotspots, decisions |
+| `core/generation/editor_files/base.py` | `BaseEditorFileGenerator`, marker-merge logic shared by all editor-file generators |
+| `core/generation/editor_files/data.py` | `EditorFileData` frozen dataclass, the data contract between fetcher and template |
+| `core/generation/editor_files/fetcher.py` | `EditorFileDataFetcher`, queries DB for architecture summary, modules, hotspots, decisions |
| `core/generation/editor_files/tech_stack.py` | Filesystem scan for languages, frameworks, build commands |
-| `core/generation/editor_files/claude_md.py` | `ClaudeMdGenerator` — 30-line subclass that binds filename + template |
+| `core/generation/editor_files/claude_md.py` | `ClaudeMdGenerator`, 30-line subclass that binds filename + template |
| `core/generation/templates/claude_md.j2` | Jinja2 template for the Repowise-managed section |
| `cli/commands/claude_md_cmd.py` | `repowise generate-claude-md` CLI command |
| `server/routers/claude_md.py` | `GET/POST /api/repos/{id}/claude-md` REST endpoints |
@@ -1546,51 +1569,21 @@ Key files:
## 16. Adding a New Language
-1. **Write `packages/core/queries/<language>.scm`**
-
- Use tree-sitter S-expression syntax. Follow the capture name conventions:
- `@symbol.def`, `@symbol.name`, `@symbol.params`, `@symbol.return_type`,
- `@symbol.docstring`, `@import.statement`, `@import.module`, `@import.names`.
-
- Check the tree-sitter playground for your language's node type names:
- `https://tree-sitter.github.io/tree-sitter/playground`
-
-2. **Add a `LanguageConfig` entry to `LANGUAGE_CONFIGS` in `parser.py`**
-
- ```python
- "mylang": LanguageConfig(
- symbol_node_types={
- "function_definition": "function",
- "class_definition": "class",
- },
- import_node_types=["import_statement"],
- export_node_types=[],
- visibility_fn=lambda name, mods: "private" if name.startswith("_") else "public",
- entry_point_patterns=["main.ml", "app.ml"],
- ),
- ```
-
-3. **Add a `LanguageSpec` to `LanguageRegistry`** in `ingestion/languages/registry.py`
-
- This registers the language's identity data (extensions, entry points, manifest files,
- builtin calls, heritage node types, etc.) centrally.
-
-4. **Add the grammar dependency to `pyproject.toml`**
-
- ```toml
- "tree-sitter-mylang>=0.23,<1",
- ```
-
-5. **Add test files to `tests/fixtures/sample_repo/`**
-
- At minimum: one file with a function, one with a class, one with imports.
-
-6. **(Optional) Add per-language extractors** for bindings, heritage, visibility, docstrings,
- and a dedicated import resolver in `resolvers/mylang.py`.
+The full recipe lives in
+**[architecture/language-support.md](language-support.md#adding-a-new-language)**,
+five required steps, three optional extractors, and three call-resolution seams,
+each with the file it registers in and what you lose by skipping it.
-7. **Run `pytest tests/unit/test_parser.py -k mylang`** to verify extraction.
+Two things worth knowing before you start:
-8. **Open a PR.** That's it — no other changes needed.
+- **You never edit `parser.py` or `registry.py`.** Language identity goes in
+ `ingestion/languages/specs/<lang>.py` and is slotted into `ALL_SPECS`; parser
+ configuration goes in `ingestion/language_configs.py`. The one unavoidable
+ core edit is adding your tag to the `LanguageTag` Literal in
+ `ingestion/models.py`, which cannot be derived from runtime data.
+- **Add fixtures to `tests/fixtures/sample_repo/`**: at minimum one file with a
+ function, one with a class, and one with imports, then run
+ `pytest tests/ -k "<lang> or sample_repo" -x`.
---
@@ -1678,7 +1671,7 @@ dead_code:
enabled: true # detect unreachable files, unused exports, zombie packages
detect_unreachable_files: true
detect_unused_exports: true
- detect_unused_internals: false # off by default — higher false positive rate
+ detect_unused_internals: false # off by default, higher false positive rate
detect_zombie_packages: true
min_confidence: 0.4
safe_to_delete_threshold: 0.7
diff --git a/docs/architecture/graph-algorithms.md b/docs/architecture/graph-algorithms.md
index b3e6747ae..c8c946653 100644
--- a/docs/architecture/graph-algorithms.md
+++ b/docs/architecture/graph-algorithms.md
@@ -1,7 +1,9 @@
-# Graph Algorithms in Repowise — Complete Guide
+# Graph Algorithms in Repowise: Complete Guide
This document covers every graph algorithm used in Repowise: what it does, the intuition behind it, the actual math, and why Repowise chose it.
+For what the graph *contains* rather than what runs over it, including the edge vocabulary and how each call edge is resolved, see [docs/layers/GRAPH.md](../layers/GRAPH.md).
+
---
## The Foundation: What Is the Graph?
@@ -22,13 +24,16 @@ Symbol-level edges (all carry a `confidence` score from 0.0 to 1.0):
| Edge type | Source | Example |
|-----------|--------|---------|
-| `DEFINES` | GraphBuilder `add_file()` | `login.py` DEFINES `validate_token` |
-| `HAS_METHOD` | GraphBuilder `add_file()` | `AuthService` HAS_METHOD `login` |
-| `CALLS` | `CallResolver` (3-tier resolution) | `validate_token` CALLS `hash_password` |
+| `defines` | GraphBuilder `add_file()` | `login.py` defines `validate_token` |
+| `has_method` | GraphBuilder `add_file()` | `AuthService` has_method `login` |
+| `calls` | `CallResolver` (29 named resolution origins, each with a fixed confidence) | `validate_token` calls `hash_password` |
+| `dispatches_to` | Heritage pass | base `Handler.run` dispatches_to `JsonHandler.run` |
+| `references` | `@reference.name` captures | a dispatch table names `on_signal` without calling it |
+| `framework_binds` | Framework handlers | a pytest fixture binds to the test that requests it |
Framework edges are detected automatically when the tech stack includes Django, FastAPI, Flask, or pytest. They capture real runtime dependencies that static import resolution misses (e.g., `conftest.py` fixtures are loaded by pytest, not imported directly by test files).
-**`file_subgraph()` — keeping metrics accurate across both tiers**
+**`file_subgraph()`: keeping metrics accurate across both tiers**
All centrality algorithms (PageRank, betweenness, SCCs, Louvain) operate on the file-level subgraph, not the full graph. `file_subgraph()` returns a view of the `DiGraph` containing only `file` and `package` nodes. Without this isolation, the large number of symbol nodes would inflate degree counts and distort every metric. Call `file_subgraph()` before running any file-level algorithm; call the full graph when you need symbol-level traversal.
@@ -46,7 +51,7 @@ A file is important if many files depend on it, especially if _those_ files are
### The intuition
-Imagine a new developer joins the team. They pick a random file, start reading it, and follow one of its imports to the next file. They keep doing this — open a file, pick a random import, jump there. Over weeks of doing this, some files keep appearing again and again. Those files are the important ones.
+Imagine a new developer joins the team. They pick a random file, start reading it, and follow one of its imports to the next file. They keep doing this: open a file, pick a random import, jump there. Over weeks of doing this, some files keep appearing again and again. Those files are the important ones.
PageRank simulates exactly this. It's a model of a random person browsing through the import graph, counting how often they land on each file.
@@ -78,8 +83,8 @@ score(B) = (1 - α) / N + α × Σ [ score(A) / out_degree(A) ]
Breaking this down:
-- **`(1 - α) / N`** — the "teleport" component. Everyone gets this baseline. With α = 0.85, this is `0.15 / N`.
-- **`α × Σ [ score(A) / out_degree(A) ]`** — the "follow edges" component. For each file A that imports B, B gets a share of A's score divided by how many files A imports.
+- **`(1 - α) / N`**: the "teleport" component. Everyone gets this baseline. With α = 0.85, this is `0.15 / N`.
+- **`α × Σ [ score(A) / out_degree(A) ]`**: the "follow edges" component. For each file A that imports B, B gets a share of A's score divided by how many files A imports.
**Why divide by `out_degree(A)`?** If `auth.py` imports 10 files, it splits its "vote" evenly across all 10. If it only imports 2 files, each gets a bigger share. A focused file that imports few things gives a stronger signal per import.
@@ -109,7 +114,7 @@ This is the probability of following an import edge vs. teleporting to a random
**Why teleport at all?** Two problems without it:
-**Problem 1 — Disconnected components.** If your codebase has two isolated clusters with no imports between them, the random walker gets trapped in whichever cluster it starts in. Files in the other cluster get score = 0. That's wrong — they're still important within their cluster.
+**Problem 1: Disconnected components.** If your codebase has two isolated clusters with no imports between them, the random walker gets trapped in whichever cluster it starts in. Files in the other cluster get score = 0. That's wrong; they're still important within their cluster.
```
# Cluster A # Cluster B
@@ -121,7 +126,7 @@ No edges between clusters. Without teleport, starting
in A means you never visit B. B's scores = 0.
```
-**Problem 2 — Dead ends.** A file that imports nothing traps the walker. There are no edges to follow.
+**Problem 2: Dead ends.** A file that imports nothing traps the walker. There are no edges to follow.
```
helpers.py ──→ (nothing)
@@ -142,7 +147,7 @@ except nx.PowerIterationFailedConvergence:
return {node: 1.0 / n for node in filtered.nodes()}
```
-If PageRank doesn't converge, every file gets equal score `1/N`. This is safe — no file gets unfairly prioritized.
+If PageRank doesn't converge, every file gets equal score `1/N`. This is safe; no file gets unfairly prioritized.
### Why co-change edges and symbol edges are excluded
@@ -154,7 +159,7 @@ Repowise's graph has several edge types. PageRank runs only on `imports` edges w
- Every bug fix touches `handler.py` and `test_handler.py`. The test file isn't architecturally important just because it changes alongside the handler.
- A release process updates `CHANGELOG.md`, `version.py`, and `setup.cfg` together. None import each other.
-If co-change edges fed into PageRank, files that happen to change alongside many others would appear "important" even when nothing imports them. PageRank should answer "if this file breaks, what else breaks?" — that's a structural question, answered only by import edges.
+If co-change edges fed into PageRank, files that happen to change alongside many others would appear "important" even when nothing imports them. PageRank should answer "if this file breaks, what else breaks?"; that's a structural question, answered only by import edges.
**Symbol edges** (`DEFINES`, `HAS_METHOD`, `CALLS`) are also excluded from file-level PageRank for a different reason: they operate at a finer granularity than files. Including them would give outsized weight to files that define many small functions. `file_subgraph()` filters them out before any file-level metric runs. Symbol-level PageRank (when needed) runs on the full graph separately.
@@ -163,7 +168,7 @@ If co-change edges fed into PageRank, files that happen to change alongside many
1. **Documentation priority**: High PageRank files get wiki pages generated first. If budget is limited, the most depended-on files are documented.
2. **Generation depth**: Low PageRank + low git churn → "minimal" docs (saves LLM tokens and cost).
3. **Significant file selection**: Files above the PageRank threshold get detailed Level 2 wiki pages. Files below get summarized in module-level pages.
-4. **CLAUDE.md generation**: When generating editor context files, the key-modules list is sorted by PageRank descending — the most depended-on modules appear first for AI coding assistants. The entry-point list is the exception and is ranked on execution-start evidence, because centrality rewards fan-in and would float a sink above the front door.
+4. **CLAUDE.md generation**: When generating editor context files, the key-modules list is sorted by PageRank descending; the most depended-on modules appear first for AI coding assistants. The entry-point list is the exception and is ranked on execution-start evidence, because centrality rewards fan-in and would float a sink above the front door.
---
@@ -177,7 +182,7 @@ A file with high betweenness sits on the shortest paths connecting many pairs of
### The intuition
-Think of a road network. Some roads are highways that connect neighborhoods. If a highway closes, traffic between those neighborhoods has to take long detours. Other roads are cul-de-sacs — nobody drives through them to get somewhere else.
+Think of a road network. Some roads are highways that connect neighborhoods. If a highway closes, traffic between those neighborhoods has to take long detours. Other roads are cul-de-sacs; nobody drives through them to get somewhere else.
Betweenness centrality measures which files are the "highways." They may not be the most imported files (that's PageRank), but they're the ones that connect otherwise separate areas.
@@ -213,7 +218,7 @@ where:
σ_st(v) = number of those shortest paths that pass through v
```
-Then normalize to [0, 1] by dividing by `(N-1)(N-2)` — the maximum possible pairs.
+Then normalize to [0, 1] by dividing by `(N-1)(N-2)`, the maximum possible pairs.
**Worked example:**
@@ -236,7 +241,7 @@ For node B:
`betweenness(B)` = 1/2 (before normalization)
-`betweenness(C)` = 1/2 (symmetric — same structure)
+`betweenness(C)` = 1/2 (symmetric, same structure)
Both B and C are equally "bridge-like" because there are two parallel paths through the graph.
@@ -244,7 +249,7 @@ Now if we remove C:
```
A ──→ B ──→ D
```
-`betweenness(B)` = 1 — B is the only bridge. All traffic flows through it.
+`betweenness(B)` = 1; B is the only bridge. All traffic flows through it.
### The complexity problem and sampling
@@ -258,15 +263,15 @@ if n > 30_000: # _LARGE_REPO_THRESHOLD
return nx.betweenness_centrality(g, k=k, normalized=True)
```
-Instead of computing exact betweenness using all N×N pairs, it samples 500 random source nodes and approximates. Research shows this gives good results — the ranking of "which files are most bridge-like" stays accurate even with sampling, just the exact scores shift slightly.
+Instead of computing exact betweenness using all N×N pairs, it samples 500 random source nodes and approximates. Research shows this gives good results; the ranking of "which files are most bridge-like" stays accurate even with sampling, just the exact scores shift slightly.
For repos under 30,000 nodes, exact computation is used.
### How Repowise uses betweenness
-1. **Significant file selection**: A file with high betweenness gets Level 2 docs even if its PageRank isn't high. Bridge files deserve documentation because they're coupling points — if someone changes them, ripple effects cross component boundaries.
+1. **Significant file selection**: A file with high betweenness gets Level 2 docs even if its PageRank isn't high. Bridge files deserve documentation because they're coupling points; if someone changes them, ripple effects cross component boundaries.
2. **File page context**: Betweenness is passed to the LLM in the file page template. The LLM can note "this file bridges the auth and database modules" in its generated documentation.
-3. **Risk assessment**: High betweenness + high git churn = dangerous file. It's a bottleneck that changes frequently — a maintenance risk.
+3. **Risk assessment**: High betweenness + high git churn = dangerous file. It's a bottleneck that changes frequently, a maintenance risk.
---
@@ -300,7 +305,7 @@ The algorithm:
- If unvisited: recurse, then update current node's low-link = min(own low-link, child's low-link)
- If on stack: update current node's low-link = min(own low-link, neighbor's discovery index)
4. After processing all neighbors: if low-link == discovery index, this node is the "root" of an SCC.
- Pop everything from the stack down to this node — that's one SCC.
+ Pop everything from the stack down to this node; that's one SCC.
```
**Worked example:**
@@ -328,7 +333,7 @@ DFS starting at A:
Result: Three SCCs: {A,B,C}, {D}, {E}. Only {A,B,C} has size > 1, meaning it's a circular dependency.
-**Time complexity:** O(N + E) — each node and edge is visited exactly once. Very fast.
+**Time complexity:** O(N + E); each node and edge is visited exactly once. Very fast.
### What counts as a circular dependency
@@ -366,7 +371,7 @@ Repowise converts the directed graph to undirected before running Louvain:
communities = nx.community.louvain_communities(g.to_undirected(), seed=42)
```
-Why? Import direction doesn't matter for clustering. If `auth.py` imports `crypto.py`, they're related — regardless of which one depends on which. The question isn't "who depends on whom" (that's PageRank's job) but "who belongs with whom."
+Why? Import direction doesn't matter for clustering. If `auth.py` imports `crypto.py`, they're related, regardless of which one depends on which. The question isn't "who depends on whom" (that's PageRank's job) but "who belongs with whom."
### The math: Modularity
@@ -399,7 +404,7 @@ So modularity = sum of "surprising connections" within communities. High Q means
The Louvain algorithm maximizes Q using a two-phase greedy approach:
-**Phase 1 — Local moves:**
+**Phase 1: Local moves**
1. Start with each node in its own community (N communities)
2. For each node, compute the modularity gain of moving it to each neighbor's community
3. Move the node to the community that gives the biggest gain (if positive)
@@ -420,7 +425,7 @@ where:
You don't need to memorize this. The key insight: it's cheap to compute (looks only at the node's neighbors), which is why Louvain is fast.
-**Phase 2 — Aggregation:**
+**Phase 2: Aggregation**
1. Collapse each community into a single super-node
2. Sum the edges between communities to create a smaller graph
3. Go back to Phase 1 on the smaller graph
@@ -429,14 +434,14 @@ This repeats until Q stops improving. Each round of aggregation discovers larger
**Time complexity:** Nearly O(N) in practice (each node is moved a small constant number of times). This makes it suitable for large codebases.
-**Why `seed=42`?** Louvain is non-deterministic — the order you process nodes affects the result. Fixing the random seed makes results reproducible across runs. 42 is a conventional choice (from The Hitchhiker's Guide).
+**Why `seed=42`?** Louvain is non-deterministic; the order you process nodes affects the result. Fixing the random seed makes results reproducible across runs. 42 is a conventional choice (from The Hitchhiker's Guide).
### How Repowise uses communities
1. **Architecture diagram**: Communities are listed in the generated architecture overview template, showing the LLM which files form natural subsystems so it can describe the high-level structure.
2. **Frontend graph visualization**: The graph UI has a "color by community" mode. Each community gets a distinct color, making clusters visually obvious.
3. **File page context**: Each file's community_id is included in the LLM prompt template when generating file documentation, helping the LLM explain which subsystem a file belongs to.
-4. **Path finder diagnostics**: When no shortest path exists between two files, the system checks if they're in the same community. If they're in different communities, it suggests "bridge nodes" — files that have connections to both communities.
+4. **Path finder diagnostics**: When no shortest path exists between two files, the system checks if they're in the same community. If they're in different communities, it suggests "bridge nodes", files that have connections to both communities.
---
@@ -448,7 +453,7 @@ This repeats until Q stops improving. Each round of aggregation discovers larger
### The intuition
-Given two files, trace the chain of imports connecting them. Like asking "how do I get from this API endpoint to that database model?" — the answer is a chain: `endpoint.py → service.py → repository.py → model.py`.
+Given two files, trace the chain of imports connecting them. Like asking "how do I get from this API endpoint to that database model?". The answer is a chain: `endpoint.py → service.py → repository.py → model.py`.
### The math
@@ -470,7 +475,7 @@ If no directed path exists from A to B, Repowise doesn't just say "not found." I
3. **Shared neighbors**: Files that are directly connected to both A and B.
4. **Community analysis**: Are A and B in the same community? If not, suggest bridge nodes (high-PageRank files connected to both communities).
-This is a practical design choice — rather than a binary "connected or not," the system gives you the relationships that do exist.
+This is a practical design choice: rather than a binary "connected or not," the system gives you the relationships that do exist.
---
@@ -489,7 +494,7 @@ When you're exploring a file, you want to see its neighborhood: what it imports,
Uses `nx.ego_graph(graph, node, radius=hops, undirected=True)`:
1. Start at the center node
-2. Find all nodes within `hops` steps in either direction (ignoring edge direction — both importers and importees count)
+2. Find all nodes within `hops` steps in either direction (ignoring edge direction; both importers and importees count)
3. Return the subgraph induced by those nodes
With hops=2 (default), you see:
@@ -513,7 +518,7 @@ This is BFS with a depth limit, time complexity O(branching_factor^hops).
paths = nx.single_source_shortest_path_length(graph, ep.node_id, cutoff=3)
```
-Starting from each entry point (e.g., `main.py`, `app.py`), this computes the distance to every reachable file within 3 hops. The union of all reachable files forms the "architecture view" — the parts of the codebase that are actually exercised from entry points.
+Starting from each entry point (e.g., `main.py`, `app.py`), this computes the distance to every reachable file within 3 hops. The union of all reachable files forms the "architecture view", the parts of the codebase that are actually exercised from entry points.
Files NOT reachable from any entry point within 3 hops are candidates for dead code or library code that's only indirectly used.
@@ -558,7 +563,7 @@ After filtering, Repowise scores confidence using git metadata:
## How the Algorithms Connect
-These algorithms aren't isolated — they feed into each other to create a complete picture:
+These algorithms aren't isolated; they feed into each other to create a complete picture:
```
Import Graph
@@ -618,7 +623,7 @@ These algorithms aren't isolated — they feed into each other to create a compl
|-----------|----------------|-------|-----------------------|
| PageRank | O(E × iterations) ≈ O(E × 50) | O(N) | Converge fallback to uniform |
| Betweenness | O(N × E) | O(N + E) | Sample k=500 for repos > 30k nodes |
-| SCCs (Tarjan) | O(N + E) | O(N) | None needed — already linear |
+| SCCs (Tarjan) | O(N + E) | O(N) | None needed, already linear |
| Louvain | ~O(N) empirically | O(N + E) | Seed=42 for determinism |
| BFS shortest path | O(N + E) | O(N) | Cutoff=3 for entry-point views |
| In-degree | O(1) per node | O(1) | None needed |
diff --git a/docs/architecture/language-support.md b/docs/architecture/language-support.md
index e3db7b4ab..f6ded9161 100644
--- a/docs/architecture/language-support.md
+++ b/docs/architecture/language-support.md
@@ -4,15 +4,36 @@ How the language pipeline is built, and how to add a new language. For the
user-facing "what works today" matrix, see
[docs/layers/LANGUAGE_SUPPORT.md](../layers/LANGUAGE_SUPPORT.md).
-The pipeline is fully modular. Language identity data lives in a centralised
-`LanguageRegistry`; per-language extraction logic lives in `extractors/`;
-per-language import resolution lives in `resolvers/`. Adding a language means
-dropping one file into each relevant subpackage and registering it in that
-subpackage's dispatcher, with **zero changes** to `parser.py`, `graph.py`,
+The pipeline is modular by construction. Language identity lives in a
+centralised `LanguageRegistry`; per-language extraction logic lives in
+`extractors/`; per-language import resolution lives in `resolvers/`; per-language
+call-resolution strategy lives behind a seam in `call_resolver.py`. Adding a
+language means dropping one file into each relevant subpackage and registering it
+in that subpackage's dispatcher. No edits are needed to `parser.py`, `graph.py`,
`traverser.py`, or any analysis core file.
---
+## Contents
+
+**Orientation**
+- [How the pipeline processes a file](#how-the-pipeline-processes-a-file)
+- [Module layout](#module-layout)
+
+**Contributor recipe**
+- [Adding a new language](#adding-a-new-language) · [required steps](#the-five-required-steps) · [optional depth](#optional-depth-per-language-extractors) · [call resolution](#opting-into-call-resolution)
+- [What a new language does *not* get for free](#what-a-new-language-does-not-get-for-free)
+
+**Deep dives**
+- [Call resolution](#call-resolution) · [the strategy seam](#the-per-language-strategy-seam) · [resolution origins](#resolution-origins) · [receiver typing](#receiver-typing) · [inherited dispatch](#inherited-dispatch)
+- [The edge vocabulary](#the-edge-vocabulary)
+- [Multi-language files (the SFC pattern)](#multi-language-files-the-sfc-pattern)
+- [Optional language-specific passes](#optional-language-specific-passes)
+- [The three code-health dialect registries](#the-three-code-health-dialect-registries)
+- [Workspace contract extraction](#workspace-contract-extraction)
+
+---
+
## How the pipeline processes a file
```
@@ -31,7 +52,7 @@ Extension/filename -> LanguageTag (via LanguageRegistry)
.scm query extracts:
@symbol.def / @symbol.name -> Symbol nodes
@import.statement / @import.module -> Import edges
- @call.target / @call.receiver -> Call edges
+ @call.target / @call.receiver -> Call sites
|
v
Per-language extractors:
@@ -60,6 +81,10 @@ Extension/filename -> LanguageTag (via LanguageRegistry)
Other: stem-map fallback (filename matching)
|
v
+ CallResolver turns each call site into an edge, stamped with
+ the ResolutionOrigin that produced it (see "Call resolution")
+ |
+ v
Graph analysis:
PageRank, community detection, dead code, execution flows
```
@@ -78,8 +103,9 @@ ingestion/
registry.py # LanguageRegistry lookup interface + REGISTRY singleton
specs/ # one module per language, each exporting `SPEC`
__init__.py # aggregates every SPEC into ordered `ALL_SPECS`
- python.py typescript.py go.py rust.py csharp.py … (44 tags)
+ python.py typescript.py go.py rust.py csharp.py …
python_modules.py # dotted-module <-> file index (src / monorepo / PEP 420)
+ receiver_types.py # per-language receiver-declaration patterns (see below)
extractors/ # Per-language AST extraction
visibility.py # symbol visibility (public/private/protected)
signatures.py # human-readable signature building
@@ -107,6 +133,7 @@ ingestion/
php.py # namespace/PSR-4 resolution
sql.py # dbt ref()/source() lineage
generic.py # stem-matching fallback
+ call_resolver.py # CallResolver: call site -> edge, per-language strategy seam
framework_edges/ # Framework convention edges (one module per framework + base.py)
# __init__.py re-exports add_framework_edges; iterates FrameworkHandler list
# django/fastapi/flask/aspnet/rails/laravel/spring/express/go/rust/typo3
@@ -121,6 +148,7 @@ ingestion/
graph.py # GraphBuilder (import/call/heritage resolution)
analysis/
+ execution_flows.py # Flow walk + the closed FlowTermination vocabulary
dead_code/ # Dead code detection
analyzer.py # DeadCodeAnalyzer class + detection passes
models.py # DeadCodeKind, DeadCodeFindingData, DeadCodeReport
@@ -128,24 +156,31 @@ analysis/
dynamic_markers.py # per-language source-text dynamic markers
```
-The source-of-truth registry is
-`ingestion/languages/specs/__init__.py`, which builds `ALL_SPECS`
-(order-significant, first-spec-wins extension map) from one `specs/<tag>.py`
-module per language. `LanguageSpec`'s `import_support` field
-(`"full" | "partial" | "none"`) is the closest formal signal to a "tier";
-the tier names in the user-facing doc are a documentation grouping layered on
-top of `import_support` plus the presence of binding / heritage / resolver
-modules. (The section-header comments inside `specs/__init__.py` predate the
-current state and should not be treated as a live tier reference.)
+The source-of-truth registry is `ingestion/languages/specs/__init__.py`, which
+builds `ALL_SPECS` (order-significant, first-spec-wins extension map) from one
+`specs/<tag>.py` module per language. `LanguageSpec`'s `import_support` field
+(`"full" | "partial" | "none"`) is the closest formal signal to a "tier"; the
+tier names in the user-facing doc are a documentation grouping layered on top of
+`import_support` plus the presence of binding / heritage / resolver modules. (The
+section-header comments inside `specs/__init__.py` predate the current state and
+should not be treated as a live tier reference.)
---
## Adding a new language
-### Step 1: Add a `LanguageSpec` module
+**Five steps are required, three more buy depth, and three more buy call
+resolution.** The often-quoted "one `.scm` file and one config entry" is the
+*shape* of the work, not the count: two of the five required steps are one-line
+registrations, and one is a manual edit to a `Literal` type that cannot be
+derived.
+
+### The five required steps
-Language identity data lives in `languages/specs/`, **one module per
-language**. Create
+#### Step 1: Add a `LanguageSpec` module
+
+Language identity data lives in `languages/specs/`, **one module per language**.
+Create
`packages/core/src/repowise/core/ingestion/languages/specs/mylang.py`
exporting a single `SPEC`:
@@ -163,7 +198,7 @@ SPEC = LanguageSpec(
heritage_node_types=frozenset({"class_declaration"}),
entry_point_patterns=("main.ml",),
manifest_files=("mylang.toml", "mylang.build.json"),
- build_config_manifests=("mylang.build.json",), # usually empty — see below
+ build_config_manifests=("mylang.build.json",), # usually empty, see below
shebang_tokens=("mylang",),
builtin_calls=frozenset({"print", "len"}), # filter from call graph
builtin_parents=frozenset({"Object"}), # filter from heritage
@@ -171,52 +206,54 @@ SPEC = LanguageSpec(
)
```
-#### `manifest_files` also decides package boundaries
+Then register it in `languages/specs/__init__.py` by importing the module and
+slotting it into the `ALL_SPECS` tuple. **Order matters**: `LanguageRegistry`
+builds its extension map first-spec-wins, so place more specific languages ahead
+of ones that share an extension (e.g. TypeScript before JavaScript). A spec using
+`shares_grammar_with` must also come *after* the spec it borrows from, which is
+resolved against the registry built so far. You never edit `registry.py` itself.
+
+<details>
+<summary><strong><code>manifest_files</code> also decides package boundaries</strong></summary>
Every name in `manifest_files` that is *not* in `build_config_manifests` marks
its directory as a **package root**. That drives two things beyond ingestion:
monorepo detection (`RepoStructure.packages`), and code health's `module`
-attribution — the label the dashboard, the module rollups and `module:` target
+attribution, the label the dashboard, the module rollups and `module:` target
expansion all group on. Declaring your manifests is therefore all it takes to
give a monorepo in your language proper per-package health; there is no second
list to edit. `REGISTRY.package_manifest_filenames()` is the single source of
truth, and both consumers read it.
-`build_config_manifests` defaults to empty, which is nearly always right. Add
-to it only when a name in `manifest_files` configures a build rather than
-declaring a distributable unit, because such files appear in directories that
-are not packages and each one becomes a false root that fragments the rollup.
-The shipped cases are the .NET `Directory.Build.props` / `global.json` family
-(measured in 135 non-package directories), `vite.config.js` / `nuxt.config.ts`,
+`build_config_manifests` defaults to empty, which is nearly always right. Add to
+it only when a name in `manifest_files` configures a build rather than declaring
+a distributable unit, because such files appear in directories that are not
+packages and each one becomes a false root that fragments the rollup. The shipped
+cases are the .NET `Directory.Build.props` / `global.json` family (measured in
+135 non-package directories), `vite.config.js` / `nuxt.config.ts`,
`svelte.config.js`, Cabal's `Setup.hs`, and `lean-toolchain`.
`manifest_files` holds exact filenames only, so a language whose package file is
-a *pattern* cannot be expressed. .NET is the live example: `*.csproj` is the
-real package declaration, everything C# declares is build configuration, and a
-.NET monorepo therefore still falls back to the top-level directory.
+a *pattern* cannot be expressed. .NET is the live example: `*.csproj` is the real
+package declaration, everything C# declares is build configuration, and a .NET
+monorepo therefore still falls back to the top-level directory.
One caveat worth knowing: package roots are read from a **directory scan**, not
-from the indexed file list, because the traverser only emits files whose
-language it can detect and drops 18 manifest names on that rule (`go.mod`,
-`pom.xml`, `build.gradle`, `Gemfile`, `build.sbt` among them). So a manifest
-counts as a package root whether or not your language's files parse.
-
-Then register it in `languages/specs/__init__.py` by importing the module and
-slotting it into the `ALL_SPECS` tuple. **Order matters**: `LanguageRegistry`
-builds its extension map first-spec-wins, so place more specific languages
-ahead of ones that share an extension (e.g. TypeScript before JavaScript). A
-spec using `shares_grammar_with` must also come *after* the spec it borrows
-from, which is resolved against the registry built so far. You never edit
-`registry.py` itself.
+from the indexed file list, because the traverser only emits files whose language
+it can detect and drops 18 manifest names on that rule (`go.mod`, `pom.xml`,
+`build.gradle`, `Gemfile`, `build.sbt` among them). So a manifest counts as a
+package root whether or not your language's files parse.
+</details>
-### Step 2: Add the `LanguageTag`
+#### Step 2: Add the `LanguageTag`
Add `"mylang"` to the `LanguageTag` Literal type in
-`packages/core/src/repowise/core/ingestion/models.py`. (`EXTENSION_TO_LANGUAGE`
-and `SPECIAL_FILENAMES` are derived from the registry filtered to these tags,
-so this remains a required manual step.)
+`packages/core/src/repowise/core/ingestion/models.py`. `EXTENSION_TO_LANGUAGE`
+and `SPECIAL_FILENAMES` are derived from the registry filtered to these tags, so
+this remains a required manual step: a `Literal` cannot be built from runtime
+data.
-### Step 3: Write a tree-sitter query file
+#### Step 3: Write a tree-sitter query file
Create `packages/core/src/repowise/core/ingestion/queries/mylang.scm` using
tree-sitter S-expression syntax. Follow the capture-name conventions:
@@ -231,19 +268,26 @@ tree-sitter S-expression syntax. Follow the capture-name conventions:
| `@import.statement` | Full import node | Yes |
| `@import.module` | Module path being imported | Yes |
| `@call.target` | Function/method being called | No (enables call graph) |
-| `@call.receiver` | Object the call is made on | No |
+| `@call.receiver` | Object the call is made on | No (enables receiver typing) |
| `@call.arguments` | Call arguments | No |
+| `@reference.name` | A function named without being called | No (mints `references`) |
+| `@param.type` | Parameter type annotation | No (mints `type_use`) |
`python.scm` and `typescript.scm` are good starting points. A language whose
syntax *is* another's can skip this step entirely by pointing `scm_file` at the
-existing query file — that field names the query to load, so `svelte` declares
+existing query file. That field names the query to load, so `svelte` declares
`scm_file="typescript.scm"` and writes no `.scm` of its own.
-### Step 4: Add a `LanguageConfig` entry
+**`@call.receiver` is the highest-leverage optional capture.** Without it every
+member call falls back to matching a bare method name across the repo, which is
+the `global_unique` origin, which is a guess. With it, the language becomes eligible for
+receiver typing (step 9).
+
+#### Step 4: Add a `LanguageConfig` entry
Add a parser configuration to `LANGUAGE_CONFIGS` in
-`packages/core/src/repowise/core/ingestion/language_configs.py` (re-exported
-from `parser.py` for back-compat):
+`packages/core/src/repowise/core/ingestion/language_configs.py` (re-exported from
+`parser.py` for back-compat):
```python
"mylang": LanguageConfig(
@@ -260,9 +304,7 @@ from `parser.py` for back-compat):
),
```
-### Step 5: Add the tree-sitter grammar dependency
-
-Add the grammar package to `pyproject.toml`:
+#### Step 5: Add the tree-sitter grammar dependency
```toml
[project]
@@ -272,25 +314,33 @@ dependencies = [
]
```
-### Step 6 (optional): Binding extractor
+### Optional depth: per-language extractors
+
+Each of these is one module plus one dispatcher entry. Skipping one degrades to
+silence, never to a wrong answer.
-For full-tier support, add an extractor module under
-`extractors/bindings/mylang.py` and register it in the
-`extract_import_bindings()` dispatcher. Without this, imports are still
-resolved but named-binding-level call resolution won't work.
+| Step | Module | Register in | Without it |
+|---|---|---|---|
+| 6 | `extractors/bindings/mylang.py` | `extract_import_bindings()` | Imports still resolve, but named-binding-level call resolution does not |
+| 7 | `extractors/heritage/mylang.py` | `HERITAGE_EXTRACTORS` | Inheritance chains never appear in the graph |
+| 8 | `resolvers/mylang.py` | `_RESOLVERS` in `resolvers/__init__.py` | Imports fall back to the generic stem-map (filename matching) |
-### Step 7 (optional): Heritage extractor
+### Opting into call resolution
-Add a module under `extractors/heritage/mylang.py` and register it in the
-`HERITAGE_EXTRACTORS` dict. Without this, inheritance chains won't appear in
-the graph.
+These three seams postdate the original recipe and are where a language goes from
+"has a call graph" to "has a call graph you can trust". All three live in
+`ingestion/call_resolver.py` and `ingestion/languages/receiver_types.py`; see
+[Call resolution](#call-resolution) for what each one does.
-### Step 8 (optional): Import resolver
+| Step | Register in | Buys |
+|---|---|---|
+| 9 | `_LANGUAGE_CALL_STRATEGIES` | Language-specific tiers (a package tier, a same-package tier) and the `_resolve_typed_receiver` fallback |
+| 10 | `_LANGUAGE_PATTERNS` in `receiver_types.py` | Receiver typing: the declaration shapes that name a local, parameter or field's type |
+| 11 | `IMPLICIT_FIELD_LANGUAGES` / `_INHERITED_LANGUAGES` | Field-typed receivers, and calls that dispatch to an inherited method |
-If the language has a non-trivial import system, create a resolver in
-`resolvers/mylang.py` and register it in the `_RESOLVERS` dict in
-`resolvers/__init__.py`. For simple languages, the generic stem-map fallback
-(matching by filename) works out of the box.
+**Do not register a language in these until you have measured it.** Every entry
+in all three sets was gated on a sampled precision audit before it shipped, and
+several languages are deliberately absent because they failed one.
### Verify
@@ -303,8 +353,213 @@ repowise init /path/to/mylang-project
```
No changes are needed to `traverser.py`, `dead_code.py`, `page_generator.py`,
-`cost_estimator.py`, or any other consumer file, they all derive their
-language sets from the registry automatically.
+`cost_estimator.py`, or any other consumer file: they all derive their language
+sets from the registry automatically.
+
+---
+
+## What a new language does *not* get for free
+
+Steps 1–5 give you symbols, imports and a call graph. They do **not** give you:
+
+- **Code-health markers.** The complexity walker uses its own per-language
+ node-type map (`analysis/health/complexity/languages.py`), independent of your
+ `.scm`. A language can parse perfectly for the graph and still produce zero
+ health findings. This is the single reason a language sits at Good rather than
+ Full.
+- **Performance or dataflow signal.** Two further registries
+ (`PERF_DIALECTS`, `DEFUSE_DIALECTS`), each with its own prerequisites on the
+ node map. See [the three registries](#the-three-code-health-dialect-registries).
+- **Receiver typing.** Steps 9–11 above, and each is gated on measurement.
+- **Framework edges.** One module per framework under `framework_edges/`.
+- **Class-level metrics, if the language does not nest method bodies in the
+ type.** Go's external receivers and Object Pascal's split
+ declaration/implementation sections both fail this, and both are deliberately
+ left unmapped rather than emitting a `ClassComplexity` with
+ `method_count == 0`.
+- **Dataflow, if the grammar does not label control-flow fields.** The CFG
+ builder resolves bodies and branches through *field names* (`body`,
+ `consequence`, `alternative`) and *node types* (`break_kinds`,
+ `continue_kinds`). tree-sitter-kotlin labels none of them and parses a bare
+ `break` as a plain `identifier`, which is why Kotlin has no dataflow: the
+ slicer refuses any span containing a jump, so an invisible jump would license
+ an extraction that silently changes control flow. A wrong suggestion is worse
+ than a missing one.
+
+---
+
+## Call resolution
+
+`ingestion/call_resolver.py` turns each captured call site into an edge. It is
+the part of the pipeline that most determines whether the graph is trustworthy,
+and it is built around one rule: **an edge is not a fact, so every edge says how
+it was produced.**
+
+### The per-language strategy seam
+
+`_LANGUAGE_CALL_STRATEGIES` maps a language tag to three ordered tuples of
+strategy method names:
+
+```python
+_LanguageCallStrategies(
+ free=(...), # bare call: foo()
+ member=(...), # member call: recv.foo()
+ member_fallback=(...), # member call, after the language tiers declined
+)
+```
+
+A language absent from the dict runs only the shared tiers. The seam exists so a
+language-specific tier can claim a call *before* a weaker shared one gets it.
+Go's package tier is the load-bearing example: `pkg.Func()` is claimed outright
+by `_resolve_go_package_call`, so a package qualifier never reaches the typed
+fallback and cannot be mistaken for a variable.
+
+Registered today:
+
+| Language | `free` | `member` | `member_fallback` |
+|---|---|---|---|
+| Go | same-package | package call | typed receiver |
+| Java / Kotlin | JVM same-package | JVM receiver same-package | typed receiver |
+| C# / Python / Swift | — | — | typed receiver |
+| C / C++ | same build target | — | — |
+
+Rust's crate-root strategy is deliberately *not* in the dict: it runs for every
+language, and gating it per-language would drop crate-name receivers in mixed
+repos.
+
+### Resolution origins
+
+`ResolutionOrigin` in `ingestion/models.py` is a closed `Literal` vocabulary,
+held shut by the same test that pins `EdgeType`. **Every origin has exactly one
+confidence**, so the origin distribution and the confidence histogram are two
+views of the same data, and that is what makes the stamping checkable against the
+existing numbers. A `NULL` origin on an edge means the row predates the
+vocabulary, not "unknown".
+
+The tiers, highest evidence first:
+
+| Confidence | Origins | Evidence |
+|:---:|---|---|
+| 0.95 | `same_file`, `self_scope`, `enclosing_class` | The callee is in this file, or on the caller's own class |
+| 0.93 | `receiver_same_file`, `receiver_typed_same_file`, `receiver_field_same_file`, `receiver_framework_same_file` | The receiver names a type declared in this file |
+| 0.90 | `same_package`, `import_scoped`, `receiver_same_package`, the three `*_same_package` typed variants, `self_inherited`, `enclosing_inherited` | A sibling file needing no import, or an explicit import |
+| 0.88 | `package_alias`, `module_alias`, `crate_root`, `receiver_import`, the three `*_import` typed variants | The receiver resolved through an imported file |
+| 0.85 | `import_merged`, `same_target` | In *some* imported file, or some sibling translation unit; which one is unattributed |
+| 0.75 | `receiver_global`, the three `*_global` typed variants | The `(class, method)` pair exists somewhere in the repo |
+| 0.50 | `global_unique` | The name is unique repo-wide. **A guess** |
+
+The typed variants come in three parallel families of four, one per *scope*,
+because they are three different scans over three different scopes:
+
+- `receiver_typed_*`: the type was read from the **calling body** (a local or a
+ parameter declaration)
+- `receiver_field_*`: the type was read from the **enclosing class's fields**
+- `receiver_framework_*`: the type came from a **framework decorator table**
+
+They deliberately share their untyped twin's confidence: the inferred type had to
+declare the method before an edge was emitted, so the evidence is no weaker. What
+differs is *how the receiver was named*, and that is precisely what an origin is
+for. Keeping the three families apart is what makes each one separately
+auditable: an origin that cannot separate them cannot be measured.
+
+### Receiver typing
+
+`_resolve_typed_receiver` answers "what type is `user` in `user.save()`" by
+reading the receiver's declaration, then resolving `save` on that type through
+the same four scopes as an explicit receiver.
+
+The per-language declaration patterns live in
+`ingestion/languages/receiver_types.py` as `_LANGUAGE_PATTERNS`, keyed by tag.
+They are **regexes over comment-stripped source**, not an AST walk. That is a deliberate
+shortcut. The ceiling is that a declaration a regex cannot see is a receiver that
+does not get typed; the upgrade path is an AST-backed local-scope table, which
+was not built because the pattern families cover the idiomatic shapes and the
+measured miss rate did not justify the cost.
+
+Pattern families today:
+
+| Family | Languages | Shapes |
+|---|---|---|
+| C-family | Java, C#, Kotlin (partly), Swift (partly) | `Type name`, `var name = new Type()` |
+| Go | Go | parameters, `name := Type{}`, `var name Type` |
+| Kotlin | Kotlin | `name: Type`, `= Type(...)` |
+| Swift | Swift | `name: Type`, `= Type(...)` |
+| Python | Python | annotations, `name = Type(...)`, target lists |
+
+Two further sets gate the harder half:
+
+- **`IMPLICIT_FIELD_LANGUAGES`** = `{csharp, java, kotlin, swift}`. Only these
+ look up an unbound receiver among the *enclosing class's fields*. Go is
+ deliberately excluded even though its locals and parameters are typed: its
+ package-level `var` is a wider scope than a field, and the shape is a rounding
+ error of reachable calls.
+- **`_INHERITED_LANGUAGES`** = `{kotlin, python, typescript, swift, csharp}`,
+ see below.
+
+A distinct table, `_FRAMEWORK_DECORATOR_TYPES`, records the type a framework
+decorator turns its target into (`@shared_task def add` makes `add` a `Task`, so
+`add.s()` is `Task::s`). It is a per-language tuple of `(pattern, type)` pairs,
+and its ceiling is stated in the source: an entry only holds for the framework as
+an application imports it, not as a vendored fork might redefine it.
+
+### Inherited dispatch
+
+Two directions, deliberately separate:
+
+- **Reverse**: the caller's own class does not declare the method, but exactly
+ one ancestor does. Emits `self_inherited` / `enclosing_inherited` at 0.90,
+ below the two same-class origins because the walk compares no signature and
+ reads no visibility, so it can reach a method the language would not actually
+ dispatch to. Gated on `_INHERITED_LANGUAGES`.
+- **Forward**: `dispatches_to`, a base method → an implementation that can
+ answer for it. Named for what it asserts rather than for a heritage relation:
+ the pass matches by method name and compares no signature, so it is a
+ *possible* dispatch target, not a proven override. `method_implements` could
+ not be reused, it runs implementor → interface, and this edge has to point the
+ other way for a traversal starting at the base to reach the implementation.
+
+---
+
+## The edge vocabulary
+
+`EdgeType` in `ingestion/models.py` is a closed `Literal`, with
+`EDGE_TYPE_VALUES` derived from it at runtime, never hand-copied, because a
+second hand-written copy is exactly the failure mode the vocabulary exists to
+remove. The distinctions that matter most when consuming the graph:
+
+| Edge | Means | Explicitly does *not* mean |
+|---|---|---|
+| `calls` | The parser saw a call expression and resolved its callee | — |
+| `references` | Something holds a handle to this function: a dispatch-table entry, a callback field, a registration-macro argument | That it is ever invoked. Enough to make deletion unsafe, not enough to claim a call |
+| `dispatches_to` | Base method → an implementation that could answer for it | A proven override; no signature is compared |
+| `framework_binds` | A framework wires these two symbols together (pytest fixture injection, Spring field/constructor injection) | A call. Nothing here is source the parser could have seen, and letting it read as a call would put an inferred hop into an execution flow |
+| `type_use` | File → file, from a constructor / method / delegate / record parameter type reference | An import. Weighted lower, and its provenance is surfaced separately |
+| `reads` | A data reference, file → file (C# member access) | Anything symbol-level. Its former symbol → symbol producer now emits `framework_binds` |
+| `dynamic_*` | A dynamic-dispatch hint, prefixed by kind (`dynamic_url_route`, `dynamic_uses`, `dynamic_imports`) | A static edge. Note the prefix: a consumer matching bare `"dynamic"` matches none of these |
+
+Three derived sets are what consumers should read rather than re-deriving their
+own filter: `FILE_CODE_EDGE_TYPES`, `SYMBOL_USE_EDGE_TYPES`, and
+`REACHABILITY_USE_EDGE_TYPES` (the symbol set plus `type_use`).
+
+### Flow termination
+
+`analysis/execution_flows.py` carries a matching closed vocabulary for why a
+trace stopped, because a trace that just ends reads as "execution ends here"
+whether it does or whether the walk ran out of things it could follow. One value
+per flow, first match wins in this order:
+
+| Value | Meaning |
+|---|---|
+| `depth_limit` | The hop budget ran out; nothing is known beyond it |
+| `callees_truncated` | Callee rows were cut before the walk saw them, so the three "every successor" values below are not available |
+| `cycle` | Every walkable successor was already on this trace: recursion or a mutual call |
+| `confidence_filtered` | Every successor sat below the confidence floor; `termination_detail` carries which origins were declined |
+| `excluded_target` | Every successor was a test/demo/fixture node |
+| `no_callees` | No outgoing call edges recorded. **Deliberately not called a leaf**: a symbol whose calls we failed to resolve looks exactly like this, and asserting the code has no callees is the claim we cannot make |
+
+`classify_termination` is shared by both walks (the in-process one and the
+query-time one in `mcp_server/_graph_utils`), so the two cannot describe one stop
+with different words.
---
@@ -312,15 +567,15 @@ language sets from the registry automatically.
Some file types hold more than one language. A `.svelte` or `.vue` component is
TS/JS in its `<script>` blocks, framework-flavoured HTML in its markup, and CSS
-in `<style>`. The markup grammars parse the file but return each `<script>`
-body as one opaque `raw_text` node, so a `.scm` query against them captures no
-symbol, import, or call — a grammar alone cannot support such a language.
+in `<style>`. The markup grammars parse the file but return each `<script>` body
+as one opaque `raw_text` node, so a `.scm` query against them captures no symbol,
+import, or call: a grammar alone cannot support such a language.
`ingestion/sfc_source.py` solves this with a **byte-preserving projection**
rather than a second coordinate space:
-1. a markup grammar *locates* the JS-bearing regions — every `<script>` body
- and every markup expression;
+1. a markup grammar *locates* the JS-bearing regions: every `<script>` body and
+ every markup expression;
2. every byte outside those regions is blanked to a space, with newlines kept;
3. each kept markup expression is fenced by rewriting its two surrounding
delimiter bytes to `;`, so adjacent expressions cannot run together and an
@@ -333,29 +588,29 @@ declares `shares_grammar_with="typescript"` and `scm_file="typescript.scm"`, the
`LanguageConfig` is an alias of TypeScript's, and the three health dialect
registries alias the TS entries. Each consumer that hands raw bytes to a
tree-sitter `Parser` calls `prepare_source(language, source, path=abs_path)`
-first — the ingestion parser plus the complexity, dataflow, and duplication
+first, the ingestion parser plus the complexity, dataflow, and duplication
walkers. It is a no-op for every language without a registered locator or
sanitizer.
-`prepare_source` also carries per-language byte-preserving sanitizers that
-aren't about multi-language files at all — a construct a grammar can't parse,
-where hitting it corrupts everything downstream. Object Pascal is the current
-example: `.dpr`/`.dpk`/`.lpr` project files write `unit in 'path.pas'` clauses
-in their `uses` list, a syntax tree-sitter-pascal has no rule for, and hitting
-one used to corrupt every unit named after it in the same clause. Its
-sanitizer (`prepare_pascal_source` in `ingestion/parser_helpers.py`) is gated
-on `path`'s extension — that syntax is invalid in a plain `.pas`/`.pp` unit
-file — and is a no-op everywhere else, same contract as the `_LOCATORS` path.
-Registering a sanitizer this way, rather than as an if-block in `parser.py`,
-means it stays "zero changes to `parser.py`" for a new language and the health
-walkers get the same clean projection the ingestion parser does.
+`prepare_source` also carries per-language byte-preserving sanitizers that aren't
+about multi-language files at all. They handle a construct a grammar can't
+parse, where hitting it corrupts everything downstream. Object Pascal is the current example:
+`.dpr`/`.dpk`/`.lpr` project files write `unit in 'path.pas'` clauses in their
+`uses` list, a syntax tree-sitter-pascal has no rule for, and hitting one used to
+corrupt every unit named after it in the same clause. Its sanitizer
+(`prepare_pascal_source` in `ingestion/parser_helpers.py`) is gated on `path`'s
+extension (that syntax is invalid in a plain `.pas`/`.pp` unit file) and is a
+no-op everywhere else, same contract as the `_LOCATORS` path. Registering a
+sanitizer this way, rather than as an if-block in `parser.py`, means it stays
+"zero changes to `parser.py`" for a new language and the health walkers get the
+same clean projection the ingestion parser does.
### The locator registry
Only step 1 differs per language, so it lives behind `_LOCATORS`, a dict of
-`Locator(grammar_module, visit, component_name)`. The blanking, fencing,
-caching and offset invariants are shared; adding a markup language means adding
-a `Locator`, not a second copy of the walker.
+`Locator(grammar_module, visit, component_name)`. The blanking, fencing, caching
+and offset invariants are shared; adding a markup language means adding a
+`Locator`, not a second copy of the walker.
| | Svelte | Vue |
|---|---|---|
@@ -365,35 +620,34 @@ a `Locator`, not a second copy of the walker.
| Skipped binding forms | `{#each}`, `{#await}` heads | `v-for`, `v-slot` / `#default` |
| Non-component tags | the `svelte:*` namespace | `<KeepAlive>`, `<Transition>`, `<RouterView>`, … in either spelling |
-There is no `tree-sitter-vue` on PyPI. The HTML grammar parses a Vue SFC
-cleanly anyway, because `<template>`, `<script>` and `<style>` are ordinary
-elements to it — so one dependency covers both Vue and plain HTML.
+There is no `tree-sitter-vue` on PyPI. The HTML grammar parses a Vue SFC cleanly
+anyway, because `<template>`, `<script>` and `<style>` are ordinary elements to
+it, so one dependency covers both Vue and plain HTML.
**Plain HTML deliberately has no locator.** It reuses the same grammar but not
the projection, and the distinction is the point: a projection exists to turn a
-`<script>` block into analysable TypeScript, which is worth it when that block
-is where the component lives. A plain `.html` file's inline script almost never
-carries a module import — 13 of the 6162 `.html` files in the validation corpus
-(0.2%) — so projecting would buy a rounding error and would mint symbols,
+`<script>` block into analysable TypeScript, which is worth it when that block is
+where the component lives. A plain `.html` file's inline script almost never
+carries a module import (13 of the 6162 `.html` files in the validation corpus,
+0.2%), so projecting would buy a rounding error and would mint symbols,
contradicting HTML's import-only tier. Its `<script src>` / `<link href>`
-attributes are read directly in
-`lightweight_imports/html.py`, which is extractor work, not projection work.
-Adding a `Locator` for HTML purely for symmetry with Vue and Svelte would be a
-mistake; `_LOCATORS` is for languages whose *script blocks* need projecting.
+attributes are read directly in `lightweight_imports/html.py`, which is extractor
+work, not projection work. Adding a `Locator` for HTML purely for symmetry with
+Vue and Svelte would be a mistake; `_LOCATORS` is for languages whose *script
+blocks* need projecting.
Vue's expressions live in attribute *values*, which is why the fence bytes are
-quotes rather than braces, and why only directive attributes (`:`, `@`, `v-`)
-are projected: `class="btn primary"` is a literal string, and projecting it
-would put two juxtaposed identifiers at statement position.
+quotes rather than braces, and why only directive attributes (`:`, `@`, `v-`) are
+projected: `class="btn primary"` is a literal string, and projecting it would put
+two juxtaposed identifiers at statement position.
Two things markup carries that the projection cannot express are minted
separately: the component symbol itself (via
`extractors/synthetic_symbols/sfc_component.py`, since the filename is the only
thing that names a component) and `<Foo />` instantiation call edges (via
`component_call_sites`, the analogue of `tsx.scm`'s JSX captures). For Vue both
-run the filename and the tag through the *same* normaliser, so
-`back-to-top.vue` and `<back-to-top />` cannot disagree about the name
-`BackToTop`.
+run the filename and the tag through the *same* normaliser, so `back-to-top.vue`
+and `<back-to-top />` cannot disagree about the name `BackToTop`.
The same steps would fit Astro components; only the locator changes.
@@ -404,97 +658,106 @@ The same steps would fit Astro components; only the locator changes.
Several pluggable hooks let a language opt into deeper resolution without
touching the shared pipeline files:
-- **`graph_warmups.py`**, register a one-time pre-import warmup (e.g. building
- a project index) so its cost shows up as its own phase instead of inflating
+- **`graph_warmups.py`**: register a one-time pre-import warmup (e.g. building a
+ project index) so its cost shows up as its own phase instead of inflating
`graph.imports`. Warmups can also set `is_never_flag=True` on file nodes a
build manifest declares secondary (the dead-code analyzer consults this in
`_should_never_flag`), so each repo's own build files teach the analyzer what
to ignore without extending the hardcoded glob list. Used today by
`_warmup_jvm` to exempt Gradle non-`main` source sets automatically.
-- **`type_ref_resolution._STRATEGIES`**, register a strategy that resolves
- parameter-type captures (`@param.type`) to file-level `type_use` edges.
- Drives DI-aware analysis and keeps type-only interfaces off the dead list.
-- **`languages/<lang>_member_reads.py`**, emit `reads` edges for property /
+- **`type_ref_resolution._STRATEGIES`**: register a strategy that resolves
+ parameter-type captures (`@param.type`) to file-level `type_use` edges. Drives
+ DI-aware analysis and keeps type-only interfaces off the dead list.
+- **`languages/<lang>_member_reads.py`**: emit `reads` edges for property /
member access. Used today for C# `var x = new T()` locals; the same shape
applies to any statically-typed language.
-- **`extractors/synthetic_symbols.py`**, recognise source-generator attributes
+- **`extractors/synthetic_symbols.py`**: recognise source-generator attributes
and emit the symbols the generator would produce at compile time. Used today
for CommunityToolkit MVVM (`[ObservableProperty]`, `[RelayCommand]`) and JVM
Lombok / `record` / Kotlin `data class`; the same shape fits Kotlin
`@Parcelize`, etc.
-- **`extractors/visibility.py::refine_<lang>_visibility`**, node-aware
- visibility refinement for languages where access is dictated by AST context
- (C/C++ access specifiers, storage class, export attributes) rather than
- modifier text alone.
-
-The three code-health signal layers are each driven by the same
-per-language plugin pattern, registered in a dict exactly like `resolvers/`:
-
-- **`analysis/health/complexity/languages.py`** (`LANGUAGE_MAPS`), the
- code-health complexity walker's per-language node-type map, independent of the
- ingestion `.scm` queries. A map gives McCabe complexity, nesting, cognitive
- complexity, and per-function markers; optional `class_kinds` /
- `self_identifiers` / `member_access_kinds` add class-level metrics (LCOM4,
- god-class), and `assert_kinds` / `assert_call_kinds` add assertion-block
- smells. Ships for the 11 Full languages plus Dart. See `complexity/README.md`.
-- **`analysis/health/perf/dialects/`** (`PERF_DIALECTS`), the **performance**
- signal. A `PerfDialect` owns callee extraction (the per-grammar seam), the
- execution-sink lexicon (`sink_kind`), the constant-loop / string-concat /
- async predicates, and its own marker list, so Go contributes `defer_in_loop`,
- Java/Go contribute `regex_compile_in_loop`, C# contributes
- `blocking_sync_in_async`, and the Phase-7a loop markers are opt-in per
- dialect. Every method has a safe "no signal" default.
-
- Three hooks answer questions that recur in every language, so a new dialect
- reuses them instead of re-deriving them:
- - `block_loop_body(node)` — the per-iteration body when the language's real
- iteration idiom is a call taking a block/lambda (Ruby `items.each do … end`,
- Kotlin `ids.forEach { … }`). The walker then applies every loop rule (body
- scoping, constant-bound skip, nesting, the same-collection quadratic gate)
- to it exactly as to a native loop. A lambda returned this way is *not*
- treated as a deferred scope, so `loop_depth` survives the boundary.
- - `loop_body(node)` — the per-iteration body of a *native* loop, defaulting to
- the `body` field. Only tree-sitter-kotlin leaves that field unlabeled; the
- override is what keeps a sink in a `for (u in repo.findAll())` **header**
- from reading as a sink inside the loop.
- - `resets_per_iteration(node, name, loop_kinds)` + `binds_name(node, name)` —
- the shared answer to the top `string_concat_in_loop` false positive, an
- accumulator declared fresh each pass (`var s = ""; s += part`) which is
- bounded per iteration rather than an O(n²) rebuild. The traversal is shared;
- only the "does this statement bind the name" question is per-grammar. (The
- Python, Ruby and Dart dialects predate the hook and keep their own tuned
- versions.)
-- **`analysis/health/dataflow/dialects/`** (`DEFUSE_DIALECTS`), the
- **dataflow** layer (intra-procedural CFG + def/use + reaching definitions,
- powering **Extract Method**). A `DefUseDialect` owns the read-vs-write
- classification of each statement and the parameter binders; the CFG builder,
- the reaching-definitions fixpoint, and the Extract Method slicer stay
- language-agnostic (the control-flow grammar they branch on lives on the
- `LanguageNodeMap`). The full pass runs only for functions a structural marker
- already flagged (`large_method` / `brain_method` / `complex_method`), so it
- stays within the health-pass budget.
-
- A dialect is only half the requirement: the CFG builder resolves bodies,
- conditions and jumps through *field names* (`body` / `consequence` /
- `alternative`) and *node types* (`break_kinds` / `continue_kinds`), so a
- grammar that labels none of them cannot be served by a dialect alone. The
- slicer additionally refuses any span containing a jump — which means an
- untyped jump is worse than no signal, because it would license an extraction
- that silently changes control flow. `find_extractions` also refuses a function
- whose subtree carries a parse error (`Node.has_error`): macro-heavy C/C++
- headers make tree-sitter emit one bogus `function_definition` spanning a whole
- class, and proposing to lift "statements" out of that is a wrong suggestion.
-
-All tiers are purely additive and degrade to silence: an unmapped language
-produces no findings rather than wrong ones.
+- **`extractors/visibility.py::refine_<lang>_visibility`**: node-aware visibility
+ refinement for languages where access is dictated by AST context (C/C++ access
+ specifiers, storage class, export attributes) rather than modifier text alone.
+
+---
+
+## The three code-health dialect registries
+
+Each is a dict keyed by `LanguageTag`, registered exactly like `resolvers/`, and
+each has a safe "no signal" default. They are **independent of the `.scm`
+queries** and of each other, and they stack: perf and dataflow both have
+prerequisites on the complexity map.
+
+### 1. Complexity: `analysis/health/complexity/languages.py` (`LANGUAGE_MAPS`)
+
+The per-language node-type map. A map alone gives McCabe complexity, nesting,
+cognitive complexity and per-function markers. Optional additions widen it:
+`class_kinds` / `self_identifiers` / `member_access_kinds` add class-level
+metrics (LCOM4, god-class); `assert_kinds` / `assert_call_kinds` add
+assertion-block smells. See `complexity/README.md`.
+
+Note that C has **no map at all**, despite sharing the C++ grammar, so
+`get_language_map("c")` is `None` and the health pass never reaches a dialect for
+it. Registering C in the downstream registries would be dead configuration.
+
+### 2. Performance: `analysis/health/perf/dialects/` (`PERF_DIALECTS`)
+
+A `PerfDialect` owns callee extraction (the per-grammar seam), the execution-sink
+lexicon (`sink_kind`), the constant-loop / string-concat / async predicates, and
+its own marker list, so Go contributes `defer_in_loop`, Java and Go contribute
+`regex_compile_in_loop`, and C# contributes `blocking_sync_in_async`. Requires
+`call_kinds` (and any `async_function_kinds`) on the language's `LanguageNodeMap`.
+
+Three shared hooks answer questions that recur in every language, so a new
+dialect reuses them instead of re-deriving them:
+
+- **`block_loop_body(node)`**: the per-iteration body when the language's real
+ iteration idiom is a call taking a block or lambda (Ruby `items.each do … end`,
+ Kotlin `ids.forEach { … }`). The walker then applies every loop rule (body
+ scoping, constant-bound skip, nesting, the same-collection quadratic gate) to
+ it exactly as to a native loop. A lambda returned this way is *not* treated as
+ a deferred scope, so `loop_depth` survives the boundary.
+- **`loop_body(node)`**: the per-iteration body of a *native* loop, defaulting to
+ the `body` field. Only tree-sitter-kotlin leaves that field unlabeled; the
+ override is what keeps a sink in a `for (u in repo.findAll())` **header** from
+ reading as a sink inside the loop.
+- **`resets_per_iteration(node, name, loop_kinds)`** + **`binds_name(node, name)`**: the shared answer to the top `string_concat_in_loop` false positive: an
+ accumulator declared fresh each pass (`var s = ""; s += part`) is bounded per
+ iteration rather than an O(n²) rebuild. The traversal is shared; only the "does
+ this statement bind the name" question is per-grammar. (The Python, Ruby and
+ Dart dialects predate the hook and keep their own tuned versions.)
+
+### 3. Dataflow: `analysis/health/dataflow/dialects/` (`DEFUSE_DIALECTS`)
+
+Intra-procedural CFG + def/use + reaching definitions, powering **Extract
+Method**. A `DefUseDialect` owns the read-vs-write classification of each
+statement and the parameter binders; the CFG builder, the reaching-definitions
+fixpoint and the Extract Method slicer stay language-agnostic (the control-flow
+grammar they branch on lives on the `LanguageNodeMap`). Requires
+`assignment_kinds` / `augmented_assign_kinds` / `local_decl_kinds` on that map.
+The full pass runs only for functions a structural marker already flagged
+(`large_method` / `brain_method` / `complex_method`), so it stays within the
+health-pass budget.
+
+A dialect is only half the requirement. See
+[what a new language does not get for free](#what-a-new-language-does-not-get-for-free)
+for the grammar-shaped reasons a dialect alone cannot serve a language.
+`find_extractions` also refuses a function whose subtree carries a parse error
+(`Node.has_error`): macro-heavy C/C++ headers make tree-sitter emit one bogus
+`function_definition` spanning a whole class, and proposing to lift "statements"
+out of that is a wrong suggestion.
+
+All three registries are purely additive and degrade to silence: an unmapped
+language produces no findings rather than wrong ones.
---
## Workspace contract extraction
In workspace mode (multiple repos indexed together), repowise links
-service-to-service API contracts (HTTP routes, gRPC services, and DB tables) so
-a provider endpoint in one repo connects to its consumers in another. The
+service-to-service API contracts (HTTP routes, gRPC services, and DB tables) so a
+provider endpoint in one repo connects to its consumers in another. The
extractors live in `core/workspace/extractors/` and follow the same
dialect-plugin shape: the orchestrator owns only the file walk, and each
framework / client library is an independent module registered in a tuple.
@@ -517,12 +780,12 @@ workspace/extractors/
data/ # table providers (DDL / ORM entities) <-> SQL consumers
```
-A dialect declares the file extensions it understands (via `langs.py`) and
-turns regex matches into `Contract`s through shared builders, so every dialect
-emits identically-shaped providers/consumers and path-normalization lives in
-one place. **Adding a framework or client** means dropping one module into
-`http/`, `grpc/`, or `data/` and appending its dialect to the relevant registry
-tuple, no orchestrator edits.
+A dialect declares the file extensions it understands (via `langs.py`) and turns
+regex matches into `Contract`s through shared builders, so every dialect emits
+identically-shaped providers/consumers and path-normalization lives in one place.
+**Adding a framework or client** means dropping one module into `http/`, `grpc/`,
+or `data/` and appending its dialect to the relevant registry tuple, with no
+orchestrator edits.
| Contract | Providers | Consumers |
|----------|-----------|-----------|
@@ -530,13 +793,15 @@ tuple, no orchestrator edits.
| **gRPC** | `.proto` IDL, Go, Java, Python, NestJS (`@GrpcMethod`), C# (gRPC-dotnet) | Go, Java, Python, C# |
| **Data** | DDL `CREATE`/`ALTER`, Alembic `op.create_table`, ORM entities (SQLAlchemy, SQLModel, Django, JPA, EF Core, ActiveRecord, Eloquent) | SQL string literals in app code (sqlglot-parsed, verb-anchored-regex fallback) |
-See [docs/scale/WORKSPACES.md](../scale/WORKSPACES.md) for the user-facing workspace guide.
+See [docs/scale/WORKSPACES.md](../scale/WORKSPACES.md) for the user-facing
+workspace guide.
---
## See also
-- [docs/layers/LANGUAGE_SUPPORT.md](../layers/LANGUAGE_SUPPORT.md), user-facing support matrix
-- [docs/layers/CODE_HEALTH.md](../layers/CODE_HEALTH.md), code-health markers and per-language precision hazards
-- [architecture/code-health.md](code-health.md), code-health layer internals
-- [architecture/ARCHITECTURE.md](ARCHITECTURE.md), full system architecture
+- [docs/layers/GRAPH.md](../layers/GRAPH.md) · user-facing graph page: edge vocabulary, origins, flows
+- [docs/layers/LANGUAGE_SUPPORT.md](../layers/LANGUAGE_SUPPORT.md) · user-facing support matrix
+- [docs/layers/CODE_HEALTH.md](../layers/CODE_HEALTH.md) · code-health markers and per-language precision hazards
+- [architecture/code-health.md](code-health.md) · code-health layer internals
+- [architecture/ARCHITECTURE.md](ARCHITECTURE.md) · full system architecture
diff --git a/docs/business/COMMERCIAL.md b/docs/business/COMMERCIAL.md
index 016433f55..fa60337d6 100644
--- a/docs/business/COMMERCIAL.md
+++ b/docs/business/COMMERCIAL.md
@@ -1,8 +1,8 @@
-# Repowise — Commercial Offering
+# Repowise: Commercial Offering
Repowise is dual-licensed: the core engine is **AGPL-3.0 and free** for individuals,
teams, and companies using it internally; a **commercial license** adds the
-enterprise security, compliance, governance, and operations layer — and removes the
+enterprise security, compliance, governance, and operations layer, and removes the
AGPL obligations for anyone embedding Repowise in their own product.
This document covers what the open-source distribution includes, what the commercial
@@ -18,7 +18,7 @@ models. Specific pricing figures are provided in a separate proposal.
## 1. Who the commercial license is for
-The open-source distribution covers the full developer-experience surface — the five
+The open-source distribution covers the full developer-experience surface: the five
intelligence layers, the eleven MCP tools, multi-repo workspaces, the local dashboard,
auto-sync, and auto-generated `CLAUDE.md`. That is everything an engineer or a team
needs to make their AI coding agents codebase-aware.
@@ -26,7 +26,7 @@ needs to make their AI coding agents codebase-aware.
The commercial license is for organizations that need to roll Repowise out **at
scale, in a regulated or security-sensitive environment**:
-- Large, long-lived codebases — often multi-language, multi-repo, with deep tribal
+- Large, long-lived codebases, often multi-language, multi-repo, with deep tribal
knowledge that walks out the door when senior engineers leave.
- Security and compliance obligations (PCI-DSS, SOC 2, audit trails, SBOMs) that
demand traceable rationale for architectural change, not just code diffs.
@@ -41,7 +41,7 @@ scale, in a regulated or security-sensitive environment**:
All of the following ship in `pip install repowise` today, free for internal use.
-- **Five intelligence layers** — Graph (tree-sitter AST across 18 languages, two-tier
+- **Five intelligence layers**: Graph (tree-sitter AST across 19 languages, two-tier
dependency graph, call resolution, heritage extraction, Leiden communities,
PageRank / betweenness / SCC), Git (hotspots, ownership, co-change pairs, bus
factor, significant commits, contributor profiles, module health), Documentation
@@ -49,26 +49,26 @@ All of the following ship in `pip install repowise` today, free for internal use
decision records linked to graph nodes, staleness tracking), and Code Health
(49 deterministic detectors, 1–10 score per file, coverage ingestion, trend
alerts).
-- **Ten task-shaped MCP tools** — `get_overview`, `get_answer`, `get_context`,
+- **Ten task-shaped MCP tools**: `get_overview`, `get_answer`, `get_context`,
`get_symbol`, `search_codebase`, `get_risk`, `get_change_risk`, `get_why`,
`get_dead_code`, `get_health`. Benchmarked at **−33.5 % cost per question**
against a bare agent, cheaper on 13 of 15 questions (n=15, p=0.007), and
**−49 % to −70 % tool calls** across paired runs on `pallets/flask` and
`scikit-learn`. See [docs/BENCHMARKS.md](../BENCHMARKS.md) for the sample
sizes, the tests, and the runs where the cost saving did not replicate.
-- **Multi-repo workspace intelligence** — cross-repo co-changes, API contract
+- **Multi-repo workspace intelligence**: cross-repo co-changes, API contract
extraction (HTTP / gRPC / topics) with provider↔consumer matching, package
dependency mapping, federated MCP queries (`repo="all"`), workspace dashboard and
`CLAUDE.md`.
-- **Proactive agent hooks** — SessionStart freshness/trust context, plus
+- **Proactive agent hooks**: SessionStart freshness/trust context, plus
PostToolUse enrichment after agent tool use (Bash / Grep / Glob / Read /
Edit / Write / Repowise MCP). No LLM calls, pure local SQLite.
-- **Auto-sync** — post-commit hook, file watcher, GitHub webhook, GitLab webhook,
+- **Auto-sync**: post-commit hook, file watcher, GitHub webhook, GitLab webhook,
polling fallback. Typical incremental update touches 3–10 pages in under 30 s.
-- **Local dashboard** — Chat, Docs, Graph, C4, Search, Symbols, Coverage, Risk,
+- **Local dashboard**: Chat, Docs, Graph, C4, Search, Symbols, Coverage, Risk,
Contributors, Module Health, Hotspots, Dead Code, Decisions, Costs, Blast Radius,
Security (local pattern scan), Knowledge Map, and the workspace views.
-- **Dead-code detection** — pure graph traversal, confidence-tiered, framework-aware
+- **Dead-code detection**: pure graph traversal, confidence-tiered, framework-aware
(ASP.NET, Django, FastAPI, Flask, Rails, Laravel), dynamic-import aware.
- **Privacy** (self-hosted): source never leaves your infrastructure, BYOK or fully
offline via Ollama. Anonymous, opt-out usage telemetry (command names and coarse
@@ -87,7 +87,8 @@ Repowise treats **13 languages at Full tier** (Python, TypeScript, JavaScript, S
Vue, Java, Kotlin, Go, Rust, C++, **C#**, Scala, and Ruby) with AST parsing, import
resolution, named bindings, call resolution, heritage extraction, multi-project
workspace resolvers, framework-aware edges, per-language dynamic-hint extractors, and
-code-health markers. A further 4 languages (C, Swift, PHP, Dart) sit at Good tier,
+code-health markers. A further 5 languages (C, Swift, PHP, Dart, Object Pascal/Delphi)
+sit at Good tier,
and Luau is partial. SQL/dbt, shell, HTML, and the config formats are handled by
dedicated extractors on top of that.
@@ -105,17 +106,17 @@ worth calling out. For **.NET**, as one example:
| Dead code | Confidence-tiered, respecting ASP.NET / EF Core decorators and DI registrations |
The same depth exists for the other Full-tier languages. The language pipeline is
-modular by design — adding or deepening a language touches per-language subpackages,
-not the parser core — which is what makes the **custom language / framework
+modular by design; adding or deepening a language touches per-language subpackages,
+not the parser core, which is what makes the **custom language / framework
extensions** in §5.4 a tractable commercial offering.
---
-## 4. Commercial capabilities — at a glance
+## 4. Commercial capabilities: at a glance
Status is honest: **GA** (generally available today), **dev** (working internals,
limited customer-facing surface), or **planned** (near-term roadmap). Sequencing
-against your procurement timeline is agreed as part of the commercial proposal —
+against your procurement timeline is agreed as part of the commercial proposal,
the items that matter most to you can be prioritized.
| Capability | Open Source (AGPL) | Commercial License |
@@ -132,14 +133,14 @@ the items that matter most to you can be prioritized.
| Language-specific security rulesets | — | ✅ *(dev)* |
| CVE-aware dependency analysis (KEV / EPSS / priority-scored) | — | ✅ *(GA on hosted)* |
| Usage-aware CVE triage (imports × dead code) | — | ✅ *(GA on hosted)* |
-| Function-level reachability triage | — | ✅ *(GA on hosted — per-language coverage)* |
+| Function-level reachability triage | — | ✅ *(GA on hosted, per-language coverage)* |
| Hosted secret detection (fingerprint store, incremental re-scans) | — | ✅ *(GA on hosted)* |
| SBOM generation (CycloneDX) + VEX export + diffs | — | ✅ *(GA on hosted)* |
-| Compliance reporting (PCI-DSS / SOC 2) | — | ✅ *(GA on hosted — Teams)* |
-| Audit trail (in-product + JSON / CSV export + webhook stream) | — | ✅ *(GA on hosted — security surface)* |
-| Jira / Confluence integration | — | ✅ *(GA on hosted — Teams)* |
+| Compliance reporting (PCI-DSS / SOC 2) | — | ✅ *(GA on hosted, Teams)* |
+| Audit trail (in-product + JSON / CSV export + webhook stream) | — | ✅ *(GA on hosted, security surface)* |
+| Jira / Confluence integration | — | ✅ *(GA on hosted, Teams)* |
| GitHub Enterprise / Azure DevOps / GitLab / Bitbucket | — | ✅ *(rolling out)* |
-| Slack / Teams security alerting (signed webhooks) | — | ✅ *(GA on hosted — Teams)* |
+| Slack / Teams security alerting (signed webhooks) | — | ✅ *(GA on hosted, Teams)* |
| SAML / OIDC SSO + SCIM | — | ✅ *(rolling out)* |
| RBAC + multi-tenant | — | ✅ *(planned)* |
| Air-gapped install bundle | — | ✅ *(planned)* |
@@ -151,12 +152,12 @@ the items that matter most to you can be prioritized.
---
-## 5. Commercial capabilities — in detail
+## 5. Commercial capabilities: in detail
### 5.1 Security & Compliance
- **Security scanning layer** *(GA: local pattern scan; GA on hosted:
- graph-aware enrichment)* — pattern-based detection for dangerous APIs
+ graph-aware enrichment)*: pattern-based detection for dangerous APIs
(`eval`/`exec`, `pickle.loads`, `shell=True`, `os.system`, hardcoded secrets,
concat / f-string SQL, `verify=False`, weak hashes) runs locally today in the
dashboard's Security view. On the hosted platform, findings are graph-aware:
@@ -164,27 +165,27 @@ the items that matter most to you can be prioritized.
code graph (feeding a bounded priority bump), and AI agents see security
state before modifying a file through the hosted `get_security` MCP tool and
the security section `get_risk` attaches.
-- **Language-specific security rulesets** *(dev)* — rulesets built on top of the
+- **Language-specific security rulesets** *(dev)*: rulesets built on top of the
per-language dynamic-hint extractors and framework edges. For .NET, planned checks
include `[Authorize]` coverage on controllers and Minimal API endpoints,
`IConfiguration` secret leakage, EF Core raw-SQL risk, `HttpClient` lifetime
issues, and `AllowAnonymous` on sensitive routes. Each language's ruleset ships as
a focused subset, then expands on customer feedback.
-- **CVE-aware dependency analysis** *(available on the hosted platform, Pro+)* —
+- **CVE-aware dependency analysis** *(available on the hosted platform, Pro+)*:
full dependency inventory from manifests and lock files (all major ecosystems,
transitive deps included) matched against the OSV.dev database (which aggregates
GitHub Advisory and NVD-derived data), enriched with CISA KEV listing, EPSS
exploitation probability, and fix availability, then ranked by a composed
priority score. A nightly refresh re-matches stored inventories so new
advisories surface without re-indexing, with in-product notifications.
-- **Usage-aware CVE triage** *(available on the hosted platform, Pro+)* — every
+- **Usage-aware CVE triage** *(available on the hosted platform, Pro+)*: every
CVE is labeled by whether your code actually imports the vulnerable package,
imports it only from dead code, or doesn't import it at all (with the import
sites as clickable evidence), cross-referencing the existing parse and
- dead-code layers. Unmappable packages are labeled `unknown` honestly — never
+ dead-code layers. Unmappable packages are labeled `unknown` honestly, never
guessed.
- **Function-level reachability triage** *(available on the hosted platform,
- Pro+)* — classifies CVEs by whether the advisory's affected packages or
+ Pro+)*: classifies CVEs by whether the advisory's affected packages or
symbols are actually imported, crossing OSV symbol data with the per-import
names the indexer captures. Coverage is per-ecosystem and reported honestly
in-product: Go is import-path-reliable (the Go vulndb lists affected
@@ -192,68 +193,68 @@ the items that matter most to you can be prioritized.
advisory and the code name symbols, and other ecosystems stay at
package-level triage. Provably-unreachable findings are discounted, never
hidden; nothing is ever claimed without evidence on both sides.
-- **SBOM generation + VEX export** *(available on the hosted platform, Pro+)* —
+- **SBOM generation + VEX export** *(available on the hosted platform, Pro+)*,
CycloneDX 1.6 SBOM per snapshot with per-dependency license detection and
license-risk classification, downloadable in-product, plus dependency diffs
- between any two snapshots — and a CycloneDX 1.6 **VEX** document that maps
+ between any two snapshots, and a CycloneDX 1.6 **VEX** document that maps
the platform's triage, reachability, and human status decisions onto the
standard impact-analysis states, generated fresh at download so it always
reflects current triage. SPDX and cross-format conversion on the extended
roadmap.
-- **Compliance reporting** *(available on the hosted platform, Teams+)* —
+- **Compliance reporting** *(available on the hosted platform, Teams+)*,
**PCI-DSS 4.0** and **SOC 2** control-coverage reports derived from the live
security findings, with per-control evidence drill-ins and JSON / Markdown
export. Framed honestly in-product and in every export: coverage signals,
- not an audit or certification — controls automated findings cannot evidence
+ not an audit or certification: controls automated findings cannot evidence
are marked for manual attestation rather than silently passed. ISO 27001
- Annex A and GDPR / data-residency mappings on the extended roadmap — we'd
+ Annex A and GDPR / data-residency mappings on the extended roadmap; we'd
rather ship two solid mappings than four shallow ones.
- **Audit trail** *(available on the hosted platform for the security surface,
- Teams+)* — security reads and actions (scans triggered, vulnerability and
+ Teams+)*: security reads and actions (scans triggered, vulnerability and
secret views, SBOM / VEX exports, compliance views, finding-status changes,
and MCP reads by AI agents) logged insert-only with user, IP, and timestamp,
- queryable in-product and exportable to JSON / CSV — plus an opt-in
+ queryable in-product and exportable to JSON / CSV, plus an opt-in
SIEM-lite stream that forwards audit events to any HTTPS endpoint as signed
webhooks. Coverage beyond the security surface (decisions, overrides) is in
development; native Splunk / Datadog / Elastic connectors on the roadmap.
-- **Secret-in-code detection** — **OSS / self-hosted:** `repowise security scan
+- **Secret-in-code detection**: **OSS / self-hosted:** `repowise security scan
--history` walks full git history with the same local pattern registry used
during `init` / `update` (working-tree scanning), and persists findings
locally. **Hosted platform (Pro+):** fingerprint + redacted-preview storage,
- live-at-`HEAD` flagging, and incremental re-scans — never the secret value.
+ live-at-`HEAD` flagging, and incremental re-scans, never the secret value.
Graph integration (which services / modules referenced a leaked secret) is on
the roadmap.
### 5.2 Workflow Integrations *(rolling out)*
-The plumbing these sit on — audit trail, RBAC, the commercial event bus — is in
+The plumbing these sit on (audit trail, RBAC, the commercial event bus) is in
development. The connectors themselves are sequenced by customer demand; additional
integrations beyond this list are available on request.
-- **Jira** *(available on the hosted platform, Teams+)* — architectural decisions
+- **Jira** *(available on the hosted platform, Teams+)*: architectural decisions
linked to the Jira issues that motivated them: links are mined from decision
evidence commits (validated against the site's real project keys) or added
manually by key, with live-ish status on the decision pages and in `get_why`,
so AI agents see the originating ticket next to the rationale. Risk-finding
links and PR-impact auto-comments on linked issues are on the roadmap.
-- **Confluence** *(available on the hosted platform, Teams+)* — scheduled (weekly
+- **Confluence** *(available on the hosted platform, Teams+)*: scheduled (weekly
or on-demand) publication of the Repowise wiki to a nominated space and parent
page, updated in place and never duplicated; every page carries a link-back and
a freshness banner stating the exact source commit, with an explicit stale
warning when the snapshot trails the repository head.
-- **GitHub Enterprise / Azure DevOps / GitLab / Bitbucket** — managed webhooks, a
+- **GitHub Enterprise / Azure DevOps / GitLab / Bitbucket**: managed webhooks, a
PR-comment bot that posts blast-radius and reviewer suggestions, and a
branch-protection check that blocks merges touching hotspots without a reviewer
from the ownership list.
-- **Slack & Microsoft Teams** — security alerting is available today on the
+- **Slack & Microsoft Teams**: security alerting is available today on the
hosted platform (Teams+) as HMAC-signed webhooks with a Slack-compatible
format (works with Slack, Microsoft Teams, and Mattermost inbound
webhooks): new critical CVEs, live secrets, failed scans, and
rotation-overdue reminders, plus the opt-in audit-event stream. Alerts on
hotspot drift, bus-factor warnings, and decision staleness are rolling out
on the same plumbing, routed by ownership.
-- **SAML / OIDC SSO** — Okta, Entra ID, Auth0, Google Workspace, generic SAML 2.0.
-- **SCIM provisioning** — automatic user / group lifecycle.
+- **SAML / OIDC SSO**: Okta, Entra ID, Auth0, Google Workspace, generic SAML 2.0.
+- **SCIM provisioning**: automatic user / group lifecycle.
### 5.3 Engineering Leadership & Governance
@@ -261,41 +262,41 @@ The underlying signals (ownership, bus factor, hotspot trends, decision stalenes
are already computed and queryable today via the OSS dashboard; the leadership-facing
presentation and policy layer is what's rolling out commercially.
-- **Engineering leader dashboard** *(rolling out)* — bus-factor trends, hotspot
+- **Engineering leader dashboard** *(rolling out)*: bus-factor trends, hotspot
evolution over time, cross-repo dead code, ownership drift, decision-staleness
curves, scheduled email digests (weekly / sprint / monthly / executive).
-- **Session intelligence harvesting** *(planned)* — architectural decisions surfaced
+- **Session intelligence harvesting** *(planned)*: architectural decisions surfaced
from AI coding sessions and proposed to the team knowledge base, so tribal
knowledge generated *during* AI-assisted work doesn't evaporate when the session
ends.
-- **Shared team context layer** *(dev)* — one `CLAUDE.md` backed by the full graph
+- **Shared team context layer** *(dev)*: one `CLAUDE.md` backed by the full graph
and decision layer, auto-injected into every team member's IDE / agent session via
MCP. Every engineer's agent starts from the same institutional context.
-- **Cross-repo intelligence at scale** *(dev)* — hotspots, dead code, and ownership
+- **Cross-repo intelligence at scale** *(dev)*: hotspots, dead code, and ownership
across the entire estate with centralized dashboards (beyond the local-workspace
scope already shipping in OSS).
-- **Custom decision policies** *(planned)* — required-reviewer rules, mandatory
+- **Custom decision policies** *(planned)*: required-reviewer rules, mandatory
`get_why` checks for governed paths, and merge-gating policies tied to Repowise
findings.
### 5.4 Enterprise Operations
-- **Role-based access control** *(planned)* — repo-, module-, and decision-level
+- **Role-based access control** *(planned)*: repo-, module-, and decision-level
permissions; SCIM group mapping.
-- **Multi-tenant deployment** *(planned)* — segregate engineering orgs / product
+- **Multi-tenant deployment** *(planned)*: segregate engineering orgs / product
lines while sharing cross-cutting infrastructure repos.
-- **Air-gapped install bundle** *(planned)* — packaged install with bundled grammars,
+- **Air-gapped install bundle** *(planned)*: packaged install with bundled grammars,
embedding model, and optional Ollama runtime for fully offline environments.
- **Reference HA topology** *(GA on customer infra; managed scaling tooling:
- planned)* — Postgres-backed metadata store, S3-compatible artefact storage, and
+ planned)*, Postgres-backed metadata store, S3-compatible artefact storage, and
horizontally scalable MCP servers.
-- **Backup & restore tooling** *(planned)* — point-in-time snapshots of the
+- **Backup & restore tooling** *(planned)*: point-in-time snapshots of the
intelligence layers.
-- **Priority support & SLA** *(GA)* — named support contact, response-time SLA, and a
+- **Priority support & SLA** *(GA)*: named support contact, response-time SLA, and a
quarterly architecture-review session.
-- **Custom language / framework extensions** *(GA)* — bespoke tree-sitter grammars or
+- **Custom language / framework extensions** *(GA)*: bespoke tree-sitter grammars or
framework edges, packaged and maintained by the Repowise team.
-- **IP indemnification** *(GA)* — protection against third-party IP claims related to
+- **IP indemnification** *(GA)*: protection against third-party IP claims related to
the Repowise software.
- **Defensive patent grant** *(GA)*.
@@ -305,18 +306,18 @@ presentation and policy layer is what's rolling out commercially.
A self-hosted commercial install runs as a set of containers on your own
infrastructure. The reference topology is Kubernetes-based, but the same containers
-run on Nomad or plain Docker — a Helm chart is on the near-term roadmap.
+run on Nomad or plain Docker; a Helm chart is on the near-term roadmap.
-1. **Containerised services** — Repowise API server (FastAPI), indexer workers, and
+1. **Containerised services**: Repowise API server (FastAPI), indexer workers, and
dashboard (Next.js), backed by Postgres for metadata and LanceDB (or pgvector) for
embeddings. An optional Ollama container provides fully-offline LLM use.
2. **Webhook receivers** for GitHub Enterprise / GitLab self-managed / Azure DevOps,
configured against each tracked repository.
3. **SSO** wired through your existing Entra ID / Okta tenant (per §5.2 availability).
-4. **Outbound integrations** (Jira, Confluence, Slack / Teams — per §5.2
+4. **Outbound integrations** (Jira, Confluence, Slack / Teams, per §5.2
availability) configured via signed service tokens stored in the Repowise secret
store.
-5. **BYOK** for the LLM — your Anthropic / OpenAI enterprise contract, Azure OpenAI in
+5. **BYOK** for the LLM: your Anthropic / OpenAI enterprise contract, Azure OpenAI in
your tenant, or fully offline Ollama. The choice can be made per-repository, so
sensitive repos run fully offline while less sensitive tooling repos use a hosted
model.
@@ -324,7 +325,7 @@ run on Nomad or plain Docker — a Helm chart is on the near-term roadmap.
**Topology at a glance:** all Repowise services run inside your VPC or air-gapped
network, backed by Postgres for metadata, LanceDB (or pgvector) for embeddings, and
an in-memory NetworkX graph. The LLM provider and the git server sit alongside
-Repowise in the same network boundary — no outbound connectivity is required in
+Repowise in the same network boundary; no outbound connectivity is required in
air-gapped mode.
**Indexing:** the graph, git, dead-code, and code-health layers build in minutes with
@@ -338,28 +339,28 @@ updates after each commit complete in under 30 seconds.
### 7.1 What the commercial license grants
-1. **Proprietary modification rights** — modify Repowise source without releasing
+1. **Proprietary modification rights**: modify Repowise source without releasing
modifications under AGPL.
-2. **Embedding rights** — embed Repowise intelligence in your internal tooling and
+2. **Embedding rights**: embed Repowise intelligence in your internal tooling and
developer platforms.
-3. **Patent grant** — defensive patent grant covering Repowise's methods and
+3. **Patent grant**: defensive patent grant covering Repowise's methods and
algorithms.
-4. **IP indemnification** — protection against third-party IP claims.
-5. **Support & maintenance** — dedicated engineering support with SLA-backed response
+4. **IP indemnification**: protection against third-party IP claims.
+5. **Support & maintenance**: dedicated engineering support with SLA-backed response
times.
-6. **Update rights** — all updates and new features during the license term.
-7. **Audit rights** — right to audit Repowise's security and compliance practices.
+6. **Update rights**: all updates and new features during the license term.
+7. **Audit rights**: right to audit Repowise's security and compliance practices.
### 7.2 Pricing models
-Commercial pricing is **flexible across three models** — pick whichever maps best to
+Commercial pricing is **flexible across three models**; pick whichever maps best to
your procurement and org structure. Specific figures are provided in a separate
proposal.
| Model | How it scales | Best for |
|-------|---------------|----------|
| **Per-seat** | Priced per engineer with dashboard / API / MCP access. Inactive seats reclaimable. SCIM-managed lifecycle. | Spend tracks headcount; clean alignment with existing dev-tools billing (IDE licences, Copilot, etc.). |
-| **Per-repo** | Priced per indexed repository (workspace cross-repo intelligence included). Seats unlimited within the licensed repo set. | The value driver is codebase footprint, not headcount — useful when Repowise is consumed primarily via AI agents and CI rather than human dashboard use. |
+| **Per-repo** | Priced per indexed repository (workspace cross-repo intelligence included). Seats unlimited within the licensed repo set. | The value driver is codebase footprint, not headcount; useful when Repowise is consumed primarily via AI agents and CI rather than human dashboard use. |
| **Enterprise-wide** | Unlimited seats, unlimited repos, all commercial features, on-prem / air-gapped, named support, MFC clause. | Org-wide standardisation. Removes per-repo accounting overhead and aligns with single-procurement contracts. |
All three models include the full set of §5 commercial features; the difference is
diff --git a/docs/layers/GRAPH.md b/docs/layers/GRAPH.md
new file mode 100644
index 000000000..bd9a1a4f9
--- /dev/null
+++ b/docs/layers/GRAPH.md
@@ -0,0 +1,282 @@
+# Graph Intelligence
+
+Most tools that draw a code graph will tell you `A calls B`. Very few will tell
+you *how sure they are*, and none of the interesting questions can be answered
+without that.
+
+repowise builds a two-tier graph of your codebase, files and symbols, with no
+model calls and no network. What makes it worth trusting is not its size. It is
+that **every edge carries its own evidence**.
+
+<p>
+ <img src="https://img.shields.io/badge/17-edge_types-3178C6?style=flat-square&labelColor=0A0A0A" alt="17 edge types" />
+ <img src="https://img.shields.io/badge/29-resolution_origins-059669?style=flat-square&labelColor=0A0A0A" alt="29 resolution origins" />
+ <img src="https://img.shields.io/badge/19-languages-F59520?style=flat-square&labelColor=0A0A0A" alt="19 languages" />
+ <img src="https://img.shields.io/badge/22-framework_detectors-7F52FF?style=flat-square&labelColor=0A0A0A" alt="22 framework detectors" />
+ <img src="https://img.shields.io/badge/0-LLM_calls-1E293B?style=flat-square&labelColor=0A0A0A" alt="zero LLM calls" />
+</p>
+
+**Contents:** [The problem with a plain arrow](#the-problem-with-a-plain-arrow) ·
+[What is in the graph](#what-is-in-the-graph) ·
+[Every edge says how it got there](#every-edge-says-how-it-got-there) ·
+[Typing the receiver](#typing-the-receiver) ·
+[Seventeen edge types](#seventeen-edge-types-because-calls-was-doing-too-many-jobs) ·
+[Flows that say why they stopped](#flows-that-say-why-they-stopped) ·
+[What the graph powers](#what-the-graph-powers) ·
+[Seeing it yourself](#seeing-it-yourself) ·
+[Honest ceilings](#honest-ceilings)
+
+---
+
+## The problem with a plain arrow
+
+Consider one line of Python:
+
+```python
+user.save()
+```
+
+To draw an edge, a tool has to answer "what is `user`?". There are three ways to
+do it, and they are not equally good:
+
+1. **Give up.** Emit nothing. The edge is missing, so a dead-code pass now
+ thinks `save` is unused and offers to delete it.
+2. **Guess.** Find every method named `save` in the repo and pick one. If your
+ codebase has `User.save`, `Draft.save` and `Session.save`, you have a two in
+ three chance of drawing an arrow to the wrong file.
+3. **Work out what `user` is**, then resolve `save` on that type.
+
+Most graphs do (2) and present the result identically to an edge they were
+certain about. That is the actual problem. A wrong arrow is worse than a missing
+one, because a missing arrow looks like missing information and a wrong arrow
+looks like an answer.
+
+repowise does (3) where it can, falls back to (2) where it must, and **labels
+which one happened, every time**.
+
+---
+
+## What is in the graph
+
+**Two tiers of node.** Files and packages on one tier; functions, classes,
+methods and interfaces on the other. Third-party packages appear as lightweight
+external nodes so a dependency is visible without being documented.
+
+**Two families of edge.** Structure the parser can see (imports, calls,
+inheritance) and structure only history can see (files that keep changing
+together without importing each other). They are kept apart on purpose: a
+co-change edge is real signal, but treating it as a dependency would put
+"these two files were edited in the same commit" into your import graph.
+
+Consumers never hand-roll a filter over this. Three named views are derived
+from the vocabulary and shared:
+
+| View | Answers |
+|------|---------|
+| `FILE_DEPENDENCY_EDGE_TYPES` | "what does this file depend on?" Used for communities, cycles, coupling |
+| `SYMBOL_USE_EDGE_TYPES` | "what reaches this symbol?" Containment excluded, since a class holding a method is not a use of it |
+| `REACHABILITY_USE_EDGE_TYPES` | "does anything use this at all?" The dead-code view |
+
+Before those views existed, four different places each wrote their own edge
+filter, and two of them silently counted co-change edges as imports.
+
+---
+
+## Every edge says how it got there
+
+Each `calls` edge is stamped with a **resolution origin**: the named strategy
+that produced it. There are 29, drawn from a closed vocabulary, and each one
+carries exactly one confidence.
+
+| Confidence | Origin | What was actually established |
+|:---:|---|---|
+| **0.95** | `same_file` | The callee is defined in the calling file. A certainty |
+| **0.95** | `self_scope` | `self` / `this`, a method on the caller's own class |
+| **0.93** | `receiver_same_file` | The receiver names a type declared right here |
+| **0.90** | `import_scoped` | The name was imported from the file that defines it |
+| **0.90** | `same_package` | A sibling file that needs no import (Go, JVM) |
+| **0.88** | `receiver_import` | The receiver's type was found in an imported file |
+| **0.85** | `import_merged` | It is in *one* of the imported files. Which one is unattributed |
+| **0.75** | `receiver_global` | The `(class, method)` pair exists somewhere in the repo |
+| **0.50** | `global_unique` | The name is unique repo-wide. **A guess, and stored as one** |
+
+Because every origin has exactly one confidence, the origin distribution and the
+confidence histogram are two views of the same data, which is what makes the
+stamping checkable rather than decorative.
+
+**Why this matters in practice.** An agent tracing an execution flow can decline
+anything below a threshold and know what it declined. A reviewer looking at a
+blast radius can tell "this definitely breaks" from "this shares a method name
+with something that breaks". And when the graph is wrong, the origin tells you
+*which strategy* was wrong, so it can be fixed once rather than patched per
+call site.
+
+---
+
+## Typing the receiver
+
+Twelve of the 29 origins exist to answer the `user.save()` question properly.
+Rather than matching a bare method name, repowise reads the receiver's
+**declaration** and resolves the method on that type.
+
+```java
+void handle(UserRepo repo) { // parameter declares the type
+ var draft = new Draft(); // constructor declares the type
+ repo.save(draft); // -> UserRepo.save, not Draft.save
+ this.cache.evict(draft.id); // field on the enclosing class
+}
+```
+
+Five receiver shapes are covered, each a separate origin family so each can be
+measured on its own:
+
+| Shape | Example |
+|---|---|
+| Locals and parameters | `var repo = new UserRepo()`, `fun f(r: UserRepo)` |
+| Fields of the enclosing class | `this.cache.evict(...)` |
+| Freshly constructed receivers | `new Foo().bar()` |
+| The method's own receiver | Go's `func (s *Server) handle()` |
+| Framework-retyped symbols | `@shared_task def add` makes `add` a `Task`, so `add.s()` is `Task::s` |
+
+Shipped for **Java, C#, Python, Go, Kotlin and Swift**. The typed origins share
+their untyped twin's confidence deliberately: the inferred type had to declare
+the method before any edge was emitted, so the evidence is no weaker. What
+differs is how the receiver was named, and naming that difference is the entire
+point of an origin.
+
+Languages are added here one at a time, each gated on a sampled precision audit
+before it ships. Several are deliberately absent because they failed that gate.
+An unsupported language falls back to the weaker origins and says so, which is
+the correct degradation.
+
+---
+
+## Seventeen edge types, because `calls` was doing too many jobs
+
+An edge type is a claim. If one type carries several different claims, every
+consumer downstream has to guess which one it is looking at.
+
+| Edge | Claims | Explicitly does **not** claim |
+|---|---|---|
+| `calls` | The parser saw a call expression and resolved its callee | |
+| `references` | Something holds a handle to this function: a dispatch-table entry, a callback field, a registration macro | That it is ever invoked. Enough to make deleting it unsafe, not enough to call it a call |
+| `dispatches_to` | A base method points at an implementation that could answer for it | A proven override. No signature is compared |
+| `framework_binds` | A framework wires these two symbols together: a pytest fixture, a Spring injection | A call. Nothing here is source a parser could have seen |
+| `type_use` | A type is referenced in a constructor, method, delegate or record parameter | An import. Weighted below one |
+| `co_changes` | These files keep changing in the same commit | Any code dependency at all |
+
+The `references` distinction is not academic. A handler sitting in a dispatch
+table is never called anywhere a parser can see. Counting that as "no use"
+reported entire registration layers as safe to delete.
+
+`framework_binds` is separated from `calls` for the same reason in reverse. A
+fixture nobody calls and a collaborator nobody constructs are both genuinely
+used, by the container. But an inferred wiring hop is not source, and letting it
+render as a call would put it into an execution flow as though someone had
+written it.
+
+---
+
+## Flows that say why they stopped
+
+An execution flow walks the call graph from an entry point. Every walk ends, and
+a trace that just stops reads identically whether execution really ends there or
+the walker ran out of things it could follow.
+
+So a flow never simply ends. It terminates with one of six reasons:
+
+| Termination | Meaning |
+|---|---|
+| `no_callees` | No outgoing call edges recorded |
+| `cycle` | Every successor was already on this trace: recursion or mutual calls |
+| `depth_limit` | The hop budget ran out. Nothing is known beyond it |
+| `confidence_filtered` | Every successor sat below the confidence floor |
+| `excluded_target` | Every successor was a test, demo or fixture node |
+| `callees_truncated` | Rows were cut before the walk saw them |
+
+Two details carry most of the value. `no_callees` is **deliberately not called a
+leaf**, because a symbol whose calls we failed to resolve looks exactly like a
+function that genuinely calls nothing, and asserting the second is a claim the
+graph cannot support. And when a confidence floor is what stopped the walk, the
+flow reports *which origins it declined*, which is the part you can act on.
+
+---
+
+## What the graph powers
+
+The graph is not the product. These are:
+
+- **Blast radius.** Change a file, walk the dependency edges, get the set of
+ things that can break. Confidence travels with it, so a speculative hop is
+ visible as one.
+- **Dead code.** Reachability over the union view, not over `calls` alone. A
+ symbol reached only by a framework, a dispatch table or a type reference is
+ not dead, and each of those is a different edge type for exactly this reason.
+- **Communities.** Leiden clustering (Louvain as fallback) finds the modules
+ your codebase actually has, which is frequently not the directory layout.
+- **Centrality.** PageRank over the file tier ranks what everything depends on.
+ Betweenness finds the bridges whose removal splits the graph. Neither is fed
+ co-change edges, because "changes alongside many things" is not "many things
+ depend on it".
+- **Cycles.** Strongly connected components, which need their own documentation
+ strategy because nothing in them can be explained before the others.
+- **Execution flows.** Entry point to leaf, ranked, with the termination reason
+ attached.
+- **Framework wiring.** 22 detectors connect routes to handlers, DI
+ registrations to implementations, and ORM entities to their relationships,
+ across Django, FastAPI, Flask, Spring, ASP.NET, Rails, Laravel, Next.js,
+ Express, Axum, Gin and more.
+
+---
+
+## Seeing it yourself
+
+**For your agent**, via MCP:
+
+| Tool | Gives you |
+|---|---|
+| `get_context(targets)` | Dependencies, dependents and co-change partners for a file or symbol |
+| `get_risk(targets)` | What history and the graph say about touching these paths |
+| `get_execution_flows()` | Traced flows with their termination reason |
+| `get_dead_code()` | Unreachable files, unused exports and zombie packages, by confidence tier |
+| `get_blast_radius()` | Cross-repo impact, in workspace mode |
+
+**In the dashboard**, `repowise serve` gives you the graph, architecture,
+coupling, blast-radius, knowledge-graph and dead-code views.
+
+**Everything above is computed without a single model call.** An LLM is an
+optional upgrade for prose quality in the wiki. It is never part of building the
+graph, which is why the graph is reproducible and why indexing needs no API key.
+
+---
+
+## Honest ceilings
+
+- **Resolution quality varies by language**, and the [language support
+ page](LANGUAGE_SUPPORT.md) says how per language. Statically typed languages
+ with explicit declarations resolve best. Dynamically typed and heavily
+ reflective code resolves worst, and falls back to the low-confidence origins
+ rather than pretending.
+- **Receiver typing reads declarations with per-language patterns**, not a full
+ type checker. A declaration the patterns cannot see is a receiver that does
+ not get typed, and the call falls back to a weaker origin.
+- **`dispatches_to` compares no signature.** It matches by method name, so it
+ names a possible dispatch target rather than a proven override.
+- **A repo-wide unique name is still a guess**, and `global_unique` at 0.50 is
+ where that lives. It is kept because a labelled guess beats a missing edge for
+ reachability, and it is labelled so nothing downstream can mistake it for a
+ fact.
+- **Method-level dead-code detection is not shipped**, for any language. It was
+ measured, precision failed, and shipping it would have meant confidently
+ recommending deletions that were wrong.
+
+---
+
+## See also
+
+- [LANGUAGE_SUPPORT.md](LANGUAGE_SUPPORT.md) · what works per language, and the tier each one sits in
+- [architecture/language-support.md](../architecture/language-support.md) · call resolution internals and the contributor recipe
+- [architecture/graph-algorithms.md](../architecture/graph-algorithms.md) · PageRank, Leiden, betweenness and SCC in detail
+- [DEAD_CODE.md](DEAD_CODE.md) · how reachability becomes a confidence-tiered report
+- [CHANGE_RISK.md](CHANGE_RISK.md) · how the graph feeds a per-change risk score
+- [reference/COMPUTED_GLOSSARY.md](../reference/COMPUTED_GLOSSARY.md) · every derived metric, defined
diff --git a/docs/layers/INTELLIGENCE_LAYERS.md b/docs/layers/INTELLIGENCE_LAYERS.md
index 43e02398a..3892c8266 100644
--- a/docs/layers/INTELLIGENCE_LAYERS.md
+++ b/docs/layers/INTELLIGENCE_LAYERS.md
@@ -21,7 +21,7 @@ searchable in natural language.
4. [Decision Intelligence](#decision-intelligence)
5. [Code Health Intelligence](#code-health-intelligence)
-**Derived** — built on the five, each with its own reference page
+**Derived**: built on the five, each with its own reference page
6. [Change Risk](#change-risk) · [Test Intelligence](#test-intelligence) ·
[Bug History](#bug-history) · [Security](#security) ·
@@ -41,15 +41,29 @@ upgrade for prose quality in the docs layer, never a requirement for the index.
## Graph Intelligence
tree-sitter parses your source into a **two-tier dependency graph**: file nodes
-and symbol nodes (functions, classes, methods). 18 languages parse to a full
+and symbol nodes (functions, classes, methods). 19 languages parse to a full
AST; see [`LANGUAGE_SUPPORT.md`](LANGUAGE_SUPPORT.md) for per-language tiers.
-A **3-tier call resolver with confidence scoring** handles import aliases,
-barrel re-exports and namespace imports: same-file resolution at 0.95,
-import-scoped at 0.90, globally-unique at 0.50, with language-specific pre-tiers
-for Go packages, JVM same-package and C++ same-target. Heritage extraction
-covers `extends`, `implements` and trait impls.
-
+A **confidence-scored call resolver** handles import aliases, barrel
+re-exports and namespace imports. Every `calls` edge is stamped with one of 29
+named resolution origins (`ResolutionOrigin` in `ingestion/models.py`), each
+carrying a fixed confidence from 0.95 (`same_file`) down to 0.50
+(`global_unique`, a repo-wide name match, labelled as the guess it is). That
+includes per-language tiers for Go packages, JVM same-package and C++
+same-target, and twelve receiver-typing origins that resolve a call on a
+variable by reading the variable's declaration (Java, C#, Python, Go, Kotlin,
+Swift). Heritage extraction covers `extends`, `implements` and trait impls.
+
+- **A closed edge vocabulary** keeps inference from reading as fact. A
+ `calls` edge means the parser saw a call; `references` means something only
+ holds a handle to the function; `dispatches_to` names an implementation that
+ *could* answer for a base method; `framework_binds` is wiring a framework
+ performs and no parser could have seen. Consumers read the derived edge sets
+ rather than re-deriving their own filter.
+- **An execution flow says why it stopped**, from a six-value vocabulary: a real
+ end, a cycle, an exhausted hop budget, an all-excluded successor set, a
+ confidence-filtered one, or calls that failed to resolve. A trace that simply
+ ends is the one thing it never reports.
- **Leiden community detection** (Louvain fallback) finds logical modules even
when your directory structure doesn't reflect them.
- **PageRank, betweenness centrality, SCC analysis, and execution-flow tracing**
@@ -61,7 +75,9 @@ covers `extends`, `implements` and trait impls.
Gin/Echo/Chi, Axum/Actix/Rocket, Rails, Laravel, TYPO3, Flutter and the
pytest/gtest test runners.
-Every derived metric is defined in
+Full detail, including the resolution-origin table, receiver typing worked
+through, and what each edge type does and does not claim:
+[`GRAPH.md`](GRAPH.md). Every derived metric is defined in
[`COMPUTED_GLOSSARY.md`](../reference/COMPUTED_GLOSSARY.md).
---
@@ -72,7 +88,7 @@ repowise mines your git history to produce signals no static analysis can find.
**Hotspots**: files in the top quartile of *decayed* churn (exponential
half-life, so last month outweighs last year) that also clear minimum-activity
-floors — at least 3 commits in 90 days and a meaningful temporal score. Churn
+floors, at least 3 commits in 90 days and a meaningful temporal score. Churn
alone would flag every file a bulk refactor touched; the floors keep the list
about sustained activity. Surfaced by `get_risk()` before your agent edits.
@@ -86,12 +102,12 @@ co-change partners alongside direct dependencies.
**Bus factor**: how many authors it takes to cover 80% of a file's commits. A
bus factor of 1 is the classic single-owner risk, surfaced in `CLAUDE.md`.
-**Significant commits**: up to 50 meaningful commit messages per file — merges,
-dependency bumps, lint-only and bot commits filtered out — with the commit body
+**Significant commits**: up to 50 meaningful commit messages per file, merges,
+dependency bumps, lint-only and bot commits filtered out, with the commit body
retained when it carries decision intent. These feed generation prompts, so the
wiki can explain *why* code is structured the way it is.
-**Contributor profiles**: every author gets a page — modules they own, top
+**Contributor profiles**: every author gets a page, modules they own, top
files, co-authors, commit category mix, silo modules, bus-factor risk files, and
dead-code burden.
@@ -172,8 +188,8 @@ your own repo six months later. This keeps it in the codebase.
## Code Health Intelligence
-repowise scores **every file 1–10** on three co-equal signals — defect risk,
-maintainability, and performance risk — from a roster of **49 deterministic
+repowise scores **every file 1–10** on three co-equal signals (defect risk,
+maintainability, and performance risk) from a roster of **49 deterministic
detectors**, of which only **26 are permitted to move the defect number**. Pure
static analysis over tree-sitter and git data, budgeted (and CI-tested) to
finish in **under 30 seconds on a 3,000-file repo**.
@@ -188,7 +204,7 @@ Validated leakage-free across **21 repositories, 9 languages, 2,826 files** at
mean ROC AUC **0.737**, and **0.76–0.78** on the public PROMISE/jEdit dataset
that played no part in calibration.
-It does not stop at scoring — the layer closes the loop into concrete,
+It does not stop at scoring; the layer closes the loop into concrete,
graph-aware refactoring plans an agent can execute: Extract Class, Extract
Method, Extract Helper, Move Method, Break Cycle and Split File, each with its
plan, recovered impact and blast radius.
@@ -207,7 +223,7 @@ Full guide, the calibration story and the head-to-head against CodeScene:
## Change Risk
A calibrated 0–10 defect-risk score for **a whole commit or `base..head`
-range**, computed from the diff's shape against the live checkout — no index
+range**, computed from the diff's shape against the live checkout, no index
lookup, no model call. Distinct from `get_risk()`, which scores indexed files by
path. Lead with `risk_percentile`, which ranks the change against sampled recent
commits in the same repo.
@@ -241,7 +257,7 @@ Reference: [`TEST_INTELLIGENCE.md`](TEST_INTELLIGENCE.md).
Bug-fix commits attributed back to the files and functions they repaired, giving
each file a fix count, a last-fixed age, and a "bug magnet" flag. This is why the
generated `CLAUDE.md` orders its *files that need care* by **bug-fix history
-first, then churn** — a file that keeps breaking is a better warning than a file
+first, then churn**: a file that keeps breaking is a better warning than a file
that merely changes often.
Reference: [`BUG_HISTORY.md`](BUG_HISTORY.md).
@@ -284,7 +300,7 @@ Reference: [`DEAD_CODE.md`](DEAD_CODE.md).
## Proactive context enrichment: hooks
-Most MCP tools are passive — the agent has to know to call them. repowise hooks
+Most MCP tools are passive; the agent has to know to call them. repowise hooks
are active: they act on what the agent is already doing. No LLM calls, no
network, pure local SQLite queries. Installed automatically during
`repowise init`.
@@ -294,28 +310,28 @@ version enriched every `Grep`/`Glob` before it ran and was removed: it added
noise on the majority of searches where the agent had already found what it
wanted. What ships now fires on evidence that the agent needs help:
-- **Zero-result rescue** — a grep found nothing, so wiki full-text, fuzzy symbol
+- **Zero-result rescue**: a grep found nothing, so wiki full-text, fuzzy symbol
and decision matches surface the closest real hit.
-- **Flood digest and triage** — a search returning far too much is replaced with
+- **Flood digest and triage**: a search returning far too much is replaced with
a compact per-file digest of match counts and anchor lines, plus the top files
by PageRank.
-- **Wrong-path rescue** — a failed `Read`/`Edit`/`Write` path is resolved against
+- **Wrong-path rescue**: a failed `Read`/`Edit`/`Write` path is resolved against
the index to the file you almost certainly meant.
-- **Read skeleton** — an unbounded read of a large indexed file is served as its
+- **Read skeleton**: an unbounded read of a large indexed file is served as its
skeleton with 1-indexed ranges, once per file per session.
-- **Stale-read notice** — a file was edited after this session read it earlier.
-- **Decision injection** — editing a file with a governing decision surfaces it
+- **Stale-read notice**: a file was edited after this session read it earlier.
+- **Decision injection**: editing a file with a governing decision surfaces it
in one line.
-- **Session start** — index freshness, the trust protocol, and standing
+- **Session start**: index freshness, the trust protocol, and standing
decisions.
-- **Post-commit staleness** — after a successful commit, merge, rebase,
+- **Post-commit staleness**: after a successful commit, merge, rebase,
cherry-pick or pull, a notice if the wiki has drifted from HEAD.
Claude Code and Codex are both supported.
> **Related capability:** [Distill](../agent/DISTILL.md) reuses the index
> (symbol bounds, centrality, hotspots) to compress noisy command output and
-> large reads before the agent sees them — built *on* the layers, not a layer.
+> large reads before the agent sees them, built *on* the layers, not a layer.
---
diff --git a/docs/layers/LANGUAGE_SUPPORT.md b/docs/layers/LANGUAGE_SUPPORT.md
index 149b815f5..b44f7b67a 100644
--- a/docs/layers/LANGUAGE_SUPPORT.md
+++ b/docs/layers/LANGUAGE_SUPPORT.md
@@ -1,62 +1,161 @@
# Language Support
-repowise parses **19 languages to a full AST**, resolves imports and call
-graphs across them, and scores **13 at the Full tier** with code-health markers.
-Everything else in your repo is still tracked through git history and appears in
-the wiki. This page is the "what works for my language today" reference.
-
-> **How to add a language, and how the pipeline works internally:** see
-> [architecture/language-support.md](../architecture/language-support.md). Adding
-> a language needs one `.scm` query file and one config entry, with no changes
-> to the parser core.
-
-**Contents:** [Tiers at a glance](#tiers-at-a-glance) ·
-[Full tier](#full-tier) · [Good tier](#good-tier) · [SQL + dbt](#sql--dbt) ·
-[Lightweight, Partial, Structural](#lightweight-partial-and-structural-tiers) ·
-[Code-health coverage](#code-health-coverage) · [Roadmap](#roadmap) ·
-[See also](#see-also)
+**19 languages parsed to a full AST · 13 at the Full tier · framework-aware
+across all of them.** Everything else in your repo still appears in the wiki and
+is tracked through git history. This page is the "what works for my language
+today" reference.
+
+<p>
+ <strong>Full tier &nbsp;</strong>
+ <img src="https://img.shields.io/badge/Python-3776AB?style=flat-square&logo=python&logoColor=white" alt="Python" />
+ <img src="https://img.shields.io/badge/TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" />
+ <img src="https://img.shields.io/badge/JavaScript-F7DF1E?style=flat-square&logo=javascript&logoColor=black" alt="JavaScript" />
+ <img src="https://img.shields.io/badge/Svelte-FF3E00?style=flat-square&logo=svelte&logoColor=white" alt="Svelte" />
+ <img src="https://img.shields.io/badge/Vue-42B883?style=flat-square&logo=vuedotjs&logoColor=white" alt="Vue" />
+ <img src="https://img.shields.io/badge/Java-ED8B00?style=flat-square&logo=openjdk&logoColor=white" alt="Java" />
+ <img src="https://img.shields.io/badge/Kotlin-7F52FF?style=flat-square&logo=kotlin&logoColor=white" alt="Kotlin" />
+ <img src="https://img.shields.io/badge/Go-00ADD8?style=flat-square&logo=go&logoColor=white" alt="Go" />
+ <img src="https://img.shields.io/badge/Rust-000000?style=flat-square&logo=rust&logoColor=white" alt="Rust" />
+ <img src="https://img.shields.io/badge/C++-00599C?style=flat-square&logo=cplusplus&logoColor=white" alt="C++" />
+ <img src="https://img.shields.io/badge/C%23-512BD4?style=flat-square&logo=csharp&logoColor=white" alt="C#" />
+ <img src="https://img.shields.io/badge/Scala-DC322F?style=flat-square&logo=scala&logoColor=white" alt="Scala" />
+ <img src="https://img.shields.io/badge/Ruby-CC342D?style=flat-square&logo=ruby&logoColor=white" alt="Ruby" />
+</p>
+<p>
+ <strong>Good tier &nbsp;</strong>
+ <img src="https://img.shields.io/badge/C-A8B9CC?style=flat-square&logo=c&logoColor=black" alt="C" />
+ <img src="https://img.shields.io/badge/Swift-F05138?style=flat-square&logo=swift&logoColor=white" alt="Swift" />
+ <img src="https://img.shields.io/badge/PHP-777BB4?style=flat-square&logo=php&logoColor=white" alt="PHP" />
+ <img src="https://img.shields.io/badge/Dart-0175C2?style=flat-square&logo=dart&logoColor=white" alt="Dart" />
+ <img src="https://img.shields.io/badge/Delphi-EE1F35?style=flat-square&logo=delphi&logoColor=white" alt="Object Pascal / Delphi" />
+ &nbsp;<strong>· Partial &nbsp;</strong>
+ <img src="https://img.shields.io/badge/Luau-00A2FF?style=flat-square&logo=lua&logoColor=white" alt="Luau" />
+</p>
+
+**Contents:** [Tiers](#tiers) ·
+[What the pipeline gives each tier](#what-the-pipeline-gives-each-tier) ·
+[Why these graphs are different](#why-these-graphs-are-different) ·
+[Full tier](#full-tier) · [Good tier](#good-tier) ·
+[Beyond code files](#beyond-code-files) ·
+[Code-health coverage](#code-health-coverage) ·
+[Known ceilings](#known-ceilings) · [Roadmap](#roadmap)
---
-## Tiers at a glance
+## Tiers
-Every language falls into one tier. The tier determines which pipeline stages
+Every language lands in one tier, and the tier decides which pipeline stages
produce meaningful output.
-| Tier | Languages | What works |
-|------|-----------|------------|
-| [**Full**](#full-tier) | Python · TypeScript · JavaScript · Svelte · Vue · Java · Kotlin · Go · Rust · C++ · C# · Scala · Ruby | AST parsing, import resolution, named bindings, call resolution, heritage, docstrings, framework-aware edges, dynamic-hint extractors, and **code-health markers** |
-| [**Good**](#good-tier) | C · Swift · PHP · Dart · Object Pascal | Everything above except code-health markers (C, Swift, PHP; Dart and Object Pascal *do* get health markers). Dedicated workspace resolvers and framework edges per language, except Object Pascal, which resolves imports via the generic stem-map fallback (see [Known gaps](#object-pascal-known-gaps)) |
-| [**SQL / dbt**](#sql--dbt) | `.sql` via sqlglot | Tables / views / functions / procedures as symbols with wiki pages; dbt projects get real `ref()` / `source()` lineage |
-| **Shell** | `.sh` `.bash` `.zsh` | Function definitions as symbols, `source` / `.` import edges (incl. `$SCRIPT_DIR` / `dirname` / `$BATS_ROOT` idioms), and function-level code-health complexity (CCN, nesting, cognitive). No class metrics, heritage, bindings, or dead-code flagging |
-| **Config / data** | OpenAPI · Protobuf · GraphQL · Dockerfile · Makefile · YAML · JSON · TOML · Terraform · Markdown | In the file tree and wiki; special handlers extract endpoints / targets where applicable |
-| [**Lightweight**](#lightweight-partial-and-structural-tiers) | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# · HTML | File-level import graph only (no symbols/calls). Honest file-to-file dependencies, no symbol-level claims |
-| [**Partial**](#lightweight-partial-and-structural-tiers) | Luau / Roblox | AST symbols + `require()` resolution (Rojo / `.luaurc` aware); no health markers yet |
-| [**Structural**](#lightweight-partial-and-structural-tiers) | Objective-C · R · Zig · Julia · Elm · OCaml · Crystal · Nim · D | Git history only (blame, hotspots, co-change). No AST parsing |
-
-**Pipeline stage coverage:**
-
-| Stage | Full | Good | Lightweight | Structural | Config / Data |
-|-------|:----:|:----:|:-----------:|:----------:|:-------------:|
+| Tier | Languages | What you get |
+|------|-----------|--------------|
+| **Full** | Python · TypeScript · JavaScript · Svelte · Vue · Java · Kotlin · Go · Rust · C++ · C# · Scala · Ruby | The whole pipeline: AST symbols, import resolution, a resolved call graph, heritage, docstrings, framework edges, **and code-health markers** |
+| **Good** | C · Swift · PHP · Dart · Object Pascal | Everything above except the full health suite. Dart and Object Pascal *do* get health markers; C, Swift and PHP don't yet |
+| **Partial** | Luau / Roblox | AST symbols and `require()` resolution (Rojo / `.luaurc` aware). No health markers yet |
+| **Lightweight** | Elixir · Clojure · Haskell · Lean 4 · Erlang · F# · HTML | A real file-to-file import graph, no symbol-level claims |
+| **Structural** | Objective-C · R · Zig · Julia · Elm · OCaml · Crystal · Nim · D | Git history only: blame, hotspots, co-change. No AST parsing |
+
+[**SQL / dbt**](#sql--dbt) and [**shell**](#shell) sit outside this ladder on
+purpose: each has a coverage shape the tiers cannot describe. SQL is parsed by
+sqlglot rather than tree-sitter and gets symbols, wiki pages and health markers
+but no call graph, with import edges only inside a dbt project. Shell gets
+symbols, `source` edges and function-level complexity, but reachability is
+meaningless for a script invoked by name. See
+[Beyond code files](#beyond-code-files), along with
+[config and data formats](#config-and-data).
+
+## What the pipeline gives each tier
+
+| Stage | Full | Good | Partial | Lightweight | Structural |
+|-------|:----:|:----:|:-------:|:-----------:|:----------:|
| File discovery & git history | ✅ | ✅ | ✅ | ✅ | ✅ |
-| AST symbol extraction | ✅ | ✅ | - | - | - |
-| Import resolution | ✅¹ | ✅ | file-level³ | - | - |
-| Call graph edges | ✅ | ✅ | - | - | - |
-| Heritage (extends/implements) | ✅ | ✅ | - | - | - |
-| Named bindings | ✅ | ✅ | - | - | - |
-| Code-health markers | ✅² | Dart, Object Pascal | - | - | - |
-| Dead code detection | ✅ | ✅ | ✅ | ✅ | - |
+| AST symbol extraction | ✅ | ✅ | ✅ | — | — |
+| Import resolution | ✅ | ✅ | ✅ | file-level | — |
+| Call graph edges | ✅ | ✅ | ✅ | — | — |
+| Heritage (extends / implements) | ✅ | ✅ | — | — | — |
+| Named bindings | ✅ | ✅ | — | — | — |
+| Code-health markers | ✅ | Dart, Pascal | — | — | — |
+| Dead code detection | ✅ | ✅ | ✅ | ✅ | ✅ |
| Semantic search & wiki pages | ✅ | ✅ | ✅ | ✅ | ✅ |
-¹ Scala's import resolution is partial (shared JVM index with SBT/Mill
-build-file fallback); every other Full and Good language resolves imports
-fully.
-² See [code-health coverage](#code-health-coverage), a language is only "Full"
-once it clears the health checklist.
-³ File-to-file only, no symbol resolution. Regex-extracted for every
-Lightweight language except HTML, which uses the `tree-sitter-html` grammar.
-Dead-code detection covers the Lightweight tier except HTML, which is never
-flagged (see below).
+Scala's import resolution is partial: it shares the JVM index with Java and
+Kotlin and falls back to parsing SBT / Mill build files. Every other Full and
+Good language resolves imports outright.
+
+---
+
+## Why these graphs are different
+
+Plenty of tools will hand you a call graph. Three things separate a graph you
+can act on from a picture of arrows. This is the short version; the full story,
+with the complete origin table and worked examples, is in
+[GRAPH.md](GRAPH.md).
+
+### Every call edge says how it was resolved, and how much to trust it
+
+Most graphs give you an unlabelled arrow. `A calls B`, but was `B` the only
+match in the entire repo, or was it right there in the same file? Those are
+wildly different claims, and a tool that renders them identically is asking you
+to trust its weakest guess as much as its strongest fact.
+
+Every `calls` edge repowise emits carries a **resolution origin** from a closed
+vocabulary, and every origin has exactly one confidence:
+
+| Origin | Confidence | What it means |
+|--------|:---:|---|
+| `same_file` | 0.95 | Defined in the calling file. A certainty |
+| `self_scope` | 0.95 | `self` / `this`, a method on the caller's own class |
+| `import_scoped` | 0.90 | The name was imported from the file that defines it |
+| `receiver_typed_import` | 0.88 | The receiver's type was read off its declaration, then found in an imported file |
+| `receiver_global` | 0.75 | The `(class, method)` pair exists *somewhere* in the repo |
+| `global_unique` | 0.50 | The name is unique repo-wide. **A guess, and labelled as one** |
+
+That is six of 29. You can filter a graph by confidence, and both
+the MCP tools and the web UI surface which origin produced an edge, so an agent
+reading an execution flow can tell a fact from an inference instead of treating
+both as source.
+
+### A call on a variable resolves by typing the variable
+
+`user.save()` is only a useful edge if something worked out what `user` is. The
+naive approach matches `save` against every method named `save` in the repo and
+picks one, which is how graphs end up confidently wrong.
+
+repowise instead reads the receiver's **declaration** and resolves the method on
+that type. It covers the receiver shapes that actually occur:
+
+- **locals and parameters**: `var repo = new UserRepo()`, `fun f(r: UserRepo)`
+- **fields**: a call on `this.repo`, typed from the enclosing class
+- **freshly constructed receivers**: `new Foo().bar()`
+- **the method's own receiver**: Go's `func (s *Server) handle()`
+- **framework-retyped symbols**: `@shared_task def add` makes `add` a `Task`,
+ so `add.s()` resolves to `Task::s`
+
+Shipped for **Java, C#, Python, Go, Kotlin and Swift**. Each language was gated
+on measured precision before it shipped, and the ones that failed the gate are
+recorded as unsupported rather than shipped loose.
+
+### It reports silence instead of guessing
+
+Every capability degrades to *no signal* rather than a wrong one, and each
+degradation is deliberate:
+
+- **An execution flow says why it stopped.** A trace that just ends reads the
+ same whether execution really ends there or the walker ran out of things it
+ could follow. Six terminations are named separately: a real end, a cycle, an
+ exhausted hop budget, an all-excluded successor set, a confidence-filtered one,
+ and calls that failed to resolve. Where a confidence floor stopped the walk, it
+ reports which origins it declined.
+- **A `calls` edge means the callee is callable.** Edges pointing at properties,
+ constants and modules were withdrawn and re-minted as `references`: "something
+ holds a handle to this", which is enough to make deleting it unsafe and not
+ enough to claim it is invoked.
+- **Framework wiring is its own edge type.** A pytest fixture injection or a
+ Spring `@Autowired` field is a `framework_binds` edge, never a `calls` edge.
+ Nothing there is a call the parser could have seen, and letting it read as one
+ would put an inferred hop into an execution flow as if it were source.
+- **An unmapped language produces no findings, not bad ones.** A language reaches
+ a health dialect or it stays silent. There is no "best effort" middle.
---
@@ -64,412 +163,231 @@ flagged (see below).
Complete pipeline coverage: AST parsing, import resolution, call resolution,
named bindings, heritage, docstrings, framework-aware edges, dynamic-hint
-extractors, and code-health markers.
+extractors and code-health markers.
-| Language | Extensions | Import style |
+| Language | Extensions | Import resolution |
|----------|-----------|--------------|
-| **Python** | `.py` `.pyi` | `import x` / `from x import y`; source-root-aware module index (src/, monorepo `packages/*/src`, PEP 420), `__init__.py` re-export barrels |
-| **TypeScript** | `.ts` `.tsx` | ESM / `require()` with tsconfig path aliases, npm/yarn/pnpm workspaces, `export * from` barrels, optional `.vue`/`.svelte`/`.astro` probing |
+| **Python** | `.py` `.pyi` | Source-root-aware module index (`src/`, monorepo `packages/*/src`, PEP 420), `__init__.py` re-export barrels |
+| **TypeScript** | `.ts` `.tsx` | ESM / `require()`, tsconfig path aliases, npm/yarn/pnpm workspaces, `export * from` barrels |
| **JavaScript** | `.js` `.jsx` `.mjs` `.cjs` | `import` / `require()` including CommonJS re-export shapes and member picks |
-| **Svelte** | `.svelte` | Same resolver as TS/JS, plus SvelteKit's `$lib` alias and Node `#`-prefixed subpath imports; `$app/*` / `$env/*` stay external (virtual modules) |
-| **Vue** | `.vue` | Same resolver as TS/JS, including `jsconfig`/`tsconfig` path aliases (`@/* → src/*`), directory-index components (`./Foo` → `Foo/index.vue`), and router `import()` specifiers |
-| **Java** | `.java` | `import pkg.Class` / `.*` / `import static` with Maven + Gradle reactor discovery, JPMS recognition, package fan-out |
-| **Kotlin** | `.kt` `.kts` | Shares the JVM workspace index with Java (cross-language resolution); `.kt` under `src/main/java` recognised |
-| **Go** | `.go` | `import "path"` with multi-module `go.mod` discovery; a package import fans out to every file in the package |
+| **Svelte** | `.svelte` | The TS/JS resolver plus SvelteKit's `$lib` and Node `#`-prefixed subpath imports |
+| **Vue** | `.vue` | The TS/JS resolver plus `jsconfig`/`tsconfig` aliases, directory-index components, router `import()` specifiers |
+| **Java** | `.java` | `import` / `.*` / `import static` with Maven + Gradle reactor discovery, JPMS, package fan-out |
+| **Kotlin** | `.kt` `.kts` | Shares the JVM workspace index with Java, so resolution is cross-language |
+| **Go** | `.go` | Multi-module `go.mod` discovery; a package import fans out to every file in the package |
| **Rust** | `.rs` | `use crate::` / `super::` / `self::` with `Cargo.toml` |
-| **C++** | `.cpp` `.cc` `.cxx` `.h` `.hpp` `.hxx` | `#include` via `compile_commands.json` + CMake / Bazel workspace header maps, header↔implementation pairing |
-| **C#** | `.cs` | `using` / `global using` / `using static` / aliases with `.csproj` / `.sln` resolution; MSBuild project graph; `partial` class linking |
-| **Scala** | `.scala` | `import pkg.Foo`, brace/wildcard/package imports via the shared JVM index (cross-language with Java/Kotlin); SBT / Mill build parsing as fallback (partial import resolution¹) |
-| **Ruby** | `.rb` | `require` / `require_relative` with `$LOAD_PATH` probing, Gemfile externals, RSpec mirror edges, Rails / Zeitwerk autoloading |
-
-All thirteen also support three-tier call resolution (same-file, cross-file,
-global stem match) and docstring extraction (Python, Ruby comments, JSDoc,
-GoDoc, Rustdoc, Javadoc, Scaladoc, Doxygen, XML doc).
-
-**Single-file components** (`.svelte`, `.vue`) are three languages in one file,
-so they get a shared projection rather than a grammar of their own. A markup
-grammar locates the `<script>` blocks and the markup expressions; everything
-else (markup, `<style>`) is blanked to spaces with newlines preserved, and the
-result is parsed as TypeScript at **byte-identical offsets**. So a component
-reuses the TypeScript queries, config, and all three health dialects verbatim,
-and every line number points at the real source file. Only the region-location
-step differs per language, behind a small locator registry in `sfc_source.py`.
-
-Vue has no grammar on PyPI, but `tree-sitter-html` parses an SFC cleanly —
-`<template>`, `<script>` and `<style>` are just elements to it — so one
-dependency covers both Vue and plain HTML.
-
-| | Svelte | Vue |
-|---|---|---|
-| Script blocks | `<script>`, `<script context="module">` | `<script>`, `<script setup>` |
-| Markup expressions | `{expr}`, `on:click={inc}`, `{#if}` heads | `:class="c"`, `@click="inc"`, `v-if="ok"`, `{{ interp }}` |
-| Expression fence | the surrounding `{` `}` | the surrounding attribute quotes |
-| Skipped binding forms | `{#each x as y}`, `{#await}` | `v-for="x in xs"`, `v-slot` / `#default` |
-
-Three pieces sit on top for both:
-
-- the **component itself** becomes a class-kind symbol named after the file
- (`Button.svelte` → `Button`), since nothing in the source names it. Vue
- normalises the stem the same way it normalises a tag, so `warningBar.vue`,
- `back-to-top.vue` and `Logo/index.vue` declare `WarningBar`, `BackToTop` and
- `Logo` — which is what a parent actually imports and writes;
-- **`<Foo />` in markup** mints a call edge on `Foo`, the same way `tsx.scm`
- treats a JSX element. Framework intrinsics never do: Svelte's `svelte:*`
- namespace, and Vue's `<KeepAlive>` / `<Transition>` / `<RouterView>` in
- either the PascalCase or kebab spelling;
-- **markup expressions are kept**, so a handler referenced only from
- `on:click={inc}` or `@click="inc"` still carries an edge instead of reading
- as dead code.
-
-Deliberate ceilings. Binding forms (the table above) *parse* as JS but mean
-something else, so they are skipped — a parse that succeeds with the wrong
-meaning is worse than a skip. Object-literal attributes (`use:action={{ a, b }}`,
-`#default="{ row }"`) read as a block at statement position and are dropped. A
-component's props are set by the parent as markup attributes and never imported
-by name, so the unused-export pass is suppressed for both languages — the
-alternative flags every prop, and every component, in the repo.
-
-One ceiling is Vue-specific: an Options-API member spelled
-`foo: function () {}` or `foo: () => {}` is not captured, because
-`typescript.scm` has no pattern for a `pair` with a function value. The
-shorthand `foo() {}` spelling **is** captured, which covers 1,588 of 1,592
-member functions (99.7%) across the 275 Options-API files in the validation
-corpus. The remaining 0.3% is a general TS/JS object-literal gap, not a Vue
-one, so lifting it belongs in `typescript.scm`.
-
-**Framework-aware edges** connect routes to handlers, DI registrations to
-implementations, and ORM entities to relationships:
+| **C++** | `.cpp` `.cc` `.cxx` `.h` `.hpp` `.hxx` `.inl` `.ipp` `.tpp` | `#include` via `compile_commands.json` plus CMake / Bazel header maps, header↔implementation pairing |
+| **C#** | `.cs` | `using` / `global using` / aliases via `.csproj` / `.sln`, MSBuild project graph, `partial` class linking |
+| **Scala** | `.scala` | The shared JVM index (cross-language with Java/Kotlin), SBT / Mill build parsing as fallback |
+| **Ruby** | `.rb` | `require` / `require_relative` with `$LOAD_PATH` probing, Gemfile externals, Rails / Zeitwerk autoloading |
+
+All thirteen also get docstring extraction: Python, Ruby comments, JSDoc,
+GoDoc, Rustdoc, Javadoc, Scaladoc, Doxygen and XML doc.
+
+### Framework-aware edges
+
+Routes connect to handlers, DI registrations to implementations, ORM entities to
+their relationships:
| Language | Frameworks |
|----------|-----------|
-| Python | Django, FastAPI, Flask, pytest fixtures |
-| Ruby | Rails (routes → controller actions, Zeitwerk autoloading), RSpec mirror edges |
+| Python | Django, FastAPI, Flask, Celery, pytest fixtures |
+| Ruby | Rails (routes → controller actions, Zeitwerk), RSpec mirror edges |
| Java / Kotlin | Spring (stereotypes, `@RequestMapping`, Spring Data, `@Bean`), Jakarta / JPA, Quarkus, Micronaut, Android manifest |
-| C# | ASP.NET (attribute + minimal API), EF Core, gRPC-dotnet, host-builder extension methods, CommunityToolkit MVVM |
+| C# | ASP.NET (attribute + minimal API), EF Core, gRPC-dotnet, host-builder extensions, CommunityToolkit MVVM |
| Go | net/http, gin, echo, chi, gRPC server registration |
| Rust | Axum, Actix route → handler |
-| JS / TS / Svelte | Next.js App Router, Hono / Fastify / Koa / Elysia, Remix / SvelteKit (`+page.svelte`, `+layout.svelte` and their `.ts` siblings) / Astro, tRPC, Express / NestJS |
+| JS / TS / Svelte | Next.js App Router, Hono / Fastify / Koa / Elysia, Remix / SvelteKit / Astro, tRPC, Express / NestJS |
| C++ | GoogleTest, Catch2, Boost.Test, doctest, Google Benchmark, libFuzzer |
-The dead-code analyzer understands each ecosystem's entry points, generated-file
-conventions, and never-flag globs so build products and framework-invoked code
-aren't reported as unreachable. (Full per-language detail:
-[architecture/language-support.md](../architecture/language-support.md).)
+The dead-code analyzer knows each ecosystem's entry points, generated-file
+conventions and never-flag globs, so build products and framework-invoked code
+are not reported as unreachable.
+
+### Single-file components (Svelte, Vue)
+
+A `.svelte` or `.vue` file is three languages at once, so it gets a shared
+projection rather than a grammar of its own: a markup grammar locates the
+`<script>` blocks and the markup expressions, everything else is blanked to
+spaces with newlines preserved, and the result is parsed as TypeScript at
+**byte-identical offsets**.
+
+That one property is what makes the rest free: a component reuses the
+TypeScript queries, config and all three health dialects verbatim, and every line
+number points at the real source file. On top of it: the component itself becomes
+a symbol named after the file (`back-to-top.vue` declares `BackToTop`, which is
+what a parent actually writes), `<Foo />` in markup mints a call edge, and a
+handler referenced only from `on:click={inc}` or `@click="inc"` carries an edge
+instead of reading as dead code.
---
## Good tier
AST parsing, symbol extraction, import resolution, call resolution, named
-bindings, and heritage (Swift extension conformance, PHP trait use, Dart
-mixins). Dedicated workspace resolvers per language.
+bindings and heritage, with a dedicated workspace resolver per language.
-| Language | Extensions | Import style |
+| Language | Extensions | Import resolution |
|----------|-----------|--------------|
-| **C** | `.c` | `#include` via `compile_commands.json` (shares C++ grammar) |
-| **Swift** | `.swift` | `import` with SPM `Package.swift` target → directory mapping; intra-module type references; `@main` entry points |
+| **C** | `.c` | `#include` via `compile_commands.json` (shares the C++ grammar) |
+| **Swift** | `.swift` | SPM `Package.swift` target → directory mapping, intra-module type references, `@main` entry points |
| **PHP** | `.php` | `use Foo\Bar\Baz` with composer.json PSR-4 longest-prefix resolution; Laravel, TYPO3 edges |
-| **Dart** | `.dart` | `import` / `export` / `part` URIs; `package:` via every `pubspec.yaml`; Flutter route tables and `runApp()` edges; **code-health markers** |
-| **Object Pascal** | `.pas` `.pp` `.dpr` `.dpk` `.lpr` `.inc` | `uses UnitA, UnitB;` resolved via the generic unit-name → file-stem fallback (no dedicated resolver); `.dpr`/`.dpk`/`.lpr` project files as entry points; **code-health markers** |
-
-### Object Pascal known gaps
-
-Delphi (`.pas`/`.dpr`/`.dpk`) and Free Pascal/Lazarus (`.pas`/`.pp`/`.lpr`) via
-`tree-sitter-pascal`. Newest AST-parsed language in this tier, so its ceilings
-are less battle-tested than C/Swift/PHP/Dart's:
-
-- **Type kind collapses to `"class"`.** `record` / `interface` / class-helper /
- enum / plain type alias are all reported as `kind="class"` — the query
- captures the declaration but not which of the five forms it is.
-- **`extends`/`implements` heritage split is best-effort.** Delphi's
- `class(TBase, IFoo, IBar)` ancestor list doesn't itself distinguish a base
- class from an implemented interface; the heritage extractor infers it from
- naming convention (`I`-prefixed identifiers), which is the real-world Delphi
- convention but not a language guarantee.
-- **No dedicated import resolver.** Unlike C/Swift/PHP/Dart, `uses` clauses
- resolve through the same generic unit-name → file-stem fallback as the
- Lightweight tier, rather than a project-file-aware resolver — accurate for
- the near-universal "unit name equals file stem" convention, wrong when it
- doesn't hold.
-- **No class-level metrics (LCOM4 / god-class).** Pascal splits a class into
- an interface-only declaration (method signatures, no bodies) and a fully
- separate implementation section where each qualified method (`TFoo.Bar`) is
- its own top-level node — there is no single AST node that groups a type's
- method *bodies* the way class-level analysis expects. Same posture as Go
- (external-receiver methods): left unmapped rather than emitting classes
- with `method_count == 0`. Function-level complexity/nesting and duplication
- are unaffected — see [code-health coverage](#code-health-coverage).
-- **No assertion-smell or performance-risk markers yet** (no assert-call or
- call-node kinds registered).
-- **No Extract Method (dataflow) support yet** — the CFG builder has real
- branch/loop/try node kinds, but no `DefUseDialect` is registered, so
- def/use and reaching-definitions stay silent (the same "later" state as
- C# / Kotlin / Scala / Ruby).
-- **One known grammar gap left unhandled deliberately:** an anonymous
- `array[...] of record ... end` element type has no tree-sitter-pascal rule
- and degrades to a wrong `parent_name` for whatever the same class declares
- afterward — contained to that one class, not fixed, since a correct fix
- needs a nesting-aware scanner for one construct seen once in the validation
- corpus. See `prepare_pascal_source` in `ingestion/parser_helpers.py`.
-
----
-
-## SQL + dbt
-
-SQL is parsed by a dedicated sqlglot handler (multi-dialect, error-tolerant)
-rather than tree-sitter, plus the lightweight import tier for dbt lineage.
-
-- **DDL symbols** (any `.sql` file), `CREATE TABLE` / `VIEW` /
- `MATERIALIZED VIEW` become class-kind symbols with columns in the signature;
- `CREATE FUNCTION` / `PROCEDURE` become function-kind symbols, with wiki pages
- and `get_symbol` lookups. Set `sql_dialect` in config for dialect-specific
- syntax (`postgres`, `mysql`, `tsql`, `clickhouse`, …). Any parse problem
- degrades the file to passthrough, never a crash, never a guess.
-- **dbt lineage** (gated on `dbt_project.yml`), `{{ ref('model') }}` and
- `{{ source('schema', 'table') }}` become real import edges resolved against a
- per-project model-name index, so model-level lineage, hotspots, co-change,
- ownership, and communities all fall out free.
-- **App-to-database contracts** (workspace mode), pairs table *providers* (DDL,
- Alembic, ORM entities) with table *consumers* (SQL string literals in app
- code) into `data` contracts on the Live System Map. See
- [WORKSPACES.md](../scale/WORKSPACES.md).
-- **Health markers**, stored routines get cyclomatic complexity;
- `sql_select_star`, `sql_update_delete_without_where`, and `sql_cartesian_join`
- ride the sqlglot AST. All uncalibrated by construction and never move the
- defect headline. See [CODE_HEALTH.md](CODE_HEALTH.md).
+| **Dart** | `.dart` | `import` / `export` / `part` URIs, `package:` via every `pubspec.yaml`, Flutter route tables and `runApp()` edges. **Health markers included** |
+| **Object Pascal** | `.pas` `.pp` `.dpr` `.dpk` `.lpr` `.inc` | `uses` clauses via the generic unit-name → file-stem fallback; project files as entry points. **Health markers included** |
---
-## Lightweight, Partial, and Structural tiers
-
-**Lightweight** (Elixir, Clojure, Haskell, Lean 4, Erlang, F#, HTML), no symbol
-extraction, but a real file-level import graph: import statements are extracted
-per-language and resolved against a declared module-name index. The knowledge
-graph runs in flow/sparse mode on the result: honest file-to-file dependencies,
-no symbol-level claims. F# additionally honours the fsproj `<Compile Include>`
-compile-order spine. All of these use a regex tier except HTML, which uses the
-`tree-sitter-html` grammar repowise already ships for Vue.
-
-**HTML** (`.html` / `.htm`) is import-tier *only*, and deliberately so: HTML has
-no functions, classes or calls, so there are no symbols to claim. What it does
-carry is `<script src>` and `<link href>`, which become file-level edges —
-including the one every Vite/webpack SPA depends on, `index.html` →
-`src/main.ts`. References are resolved as document- or root-relative asset
-paths, never as module specifiers: there is no extension inference and no
-`index.*` lookup, because `src="./app"` in a browser fetches a file literally
-named `app`. A root-relative `/src/main.tsx` is anchored first at the
-referencing page's own directory (the bundler convention), then at its
-`public/`, then by unique path suffix; a tie yields no edge rather than a
-guessed one. CDN and `data:` references are external and mint no edge.
-
-`.html` files are **never flagged as dead code**. Whether a page is reachable
-is not statically decidable — a server serves it, a human navigates to it, a
-build copies it — and checked-in generated HTML is everywhere. Their outbound
-edges still anchor everything they reference.
-
-The known ceiling is **template dialects**. Django/Jinja, Go templates, ERB,
-Handlebars, Blade, Thymeleaf and Angular's `*ngIf` are invisible to an HTML
-parser: `{% extends "base.html" %}` is plain text, so such a file parses
-cleanly and yields nothing. Measured on the validation corpus, 744 of 749
-template-dialect files (99.3%) produce no edges at all. Covering them needs a
-per-dialect regex tier gated on a framework manifest — a different mechanism,
-not yet built.
-
-**Partial** (Luau / Roblox), AST symbols, Luau type aliases, and `require(...)`
-capture are wired. Import resolution handles string literals, `script` relative
-instance paths (including `:WaitForChild` idioms), absolute Roblox paths via
-Rojo's `default.project.json`, and `@alias` requires via `.luaurc`. No health
-markers yet.
-
-**Shell** (`.sh` / `.bash` / `.zsh`), function definitions (both `foo()` and
-`function foo` forms) become symbols, `source` / `.` statements become import
-edges, and calls to functions defined in the same or a sourced file resolve to
-call edges (external binaries like `grep` mint no edge). Import resolution
-covers literal relative paths plus the common directory-anchor idioms
-(`$SCRIPT_DIR/x.sh`, `$(dirname "$0")/x.sh`, `${BASH_SOURCE%/*}/x.sh`) and
-project-root anchors (`$BATS_ROOT/$LIBDIR/lib/x.sh`) via a unique path-suffix
-match; genuinely dynamic paths (`source "$1"`) stay external. Shell also gets
-**function-level complexity** markers (CCN / nesting / cognitive, with `&&` /
-`||` command lists counted). tree-sitter-bash parses the bash/POSIX subset, so
-zsh mostly works and fish does not; any parse error degrades that file to
-passthrough. No class metrics, heritage, bindings, or dead-code flagging (shell
-scripts are invoked by name, so static reachability is meaningless).
-
-**Structural** (Objective-C, R, Zig, Julia, Elm, OCaml, Crystal, Nim, D) -
-tracked in git history (blame, hotspots, co-change) but no AST parsing. Files
-appear in the wiki as traversal-level entries, and the knowledge graph runs in
-structural mode: it orients by directory structure, naming, and git evidence,
-and never claims an execution flow it cannot see.
+## Beyond code files
+
+### SQL + dbt
+
+Parsed by a dedicated sqlglot handler (multi-dialect, error-tolerant) rather
+than tree-sitter.
+
+- **DDL symbols**: `CREATE TABLE` / `VIEW` become class-kind symbols with their
+ columns in the signature; `CREATE FUNCTION` / `PROCEDURE` become function-kind
+ symbols. Both get wiki pages and `get_symbol` lookups. Set `sql_dialect` in
+ config for dialect-specific syntax. Any parse problem degrades the file to
+ passthrough, never a crash, never a guess.
+- **dbt lineage**: `{{ ref('model') }}` and `{{ source(...) }}` become real
+ import edges, so model-level lineage, hotspots, co-change, ownership and
+ communities all fall out free.
+- **App-to-database contracts** (workspace mode), table *providers* (DDL,
+ Alembic, ORM entities) pair with table *consumers* (SQL literals in app code)
+ on the Live System Map. See [WORKSPACES.md](../scale/WORKSPACES.md).
+- **Health markers**: stored routines get cyclomatic complexity, plus
+ `sql_select_star`, `sql_update_delete_without_where` and `sql_cartesian_join`.
+ All of them are **uncalibrated by construction** (no defect corpus covers
+ procedural SQL), so they surface as findings and never move the defect
+ headline score.
+
+SQL is not placed in a tier because it would misreport in both directions:
+Partial would understate the health markers, and any higher tier would claim a
+call graph and heritage that a DDL file does not have. Outside a dbt project,
+`.sql` files get symbols and pages but no import edges at all.
+
+### Shell
+
+`.sh` / `.bash` / `.zsh`. Function definitions become symbols, `source` / `.`
+statements become import edges, and calls to functions defined in the same or a
+sourced file resolve to call edges; external binaries like `grep` mint nothing.
+Resolution covers literal paths plus the common directory-anchor idioms
+(`$SCRIPT_DIR/x.sh`, `$(dirname "$0")/x.sh`, `$BATS_ROOT/lib/x.sh`); genuinely
+dynamic paths stay external. Shell also gets **function-level complexity**, with
+`&&` / `||` command lists counted toward CCN. No class metrics, heritage or
+dead-code flagging: shell scripts are invoked by name, so static reachability is
+meaningless.
+
+### Lightweight tier
+
+Elixir, Clojure, Haskell, Lean 4, Erlang, F# and HTML get a real file-level
+import graph: imports extracted per language and resolved against a declared
+module-name index. The knowledge graph runs in flow/sparse mode on the result:
+honest file-to-file dependencies, no symbol-level claims. F# additionally honours
+the fsproj `<Compile Include>` compile order.
+
+**HTML** is import-tier on purpose. It has no functions, classes or calls, so
+there are no symbols to claim, but its `<script src>` and `<link href>` become
+file-level edges, including the one every Vite/webpack SPA depends on:
+`index.html` → `src/main.ts`. References resolve as document- or root-relative
+asset paths, never as module specifiers, and a tie yields no edge rather than a
+guessed one. `.html` files are **never flagged as dead code**: whether a page is
+reachable is not statically decidable.
+
+### Config and data
+
+OpenAPI, Protobuf, GraphQL, Dockerfile, Makefile, YAML, JSON, TOML, Terraform and
+Markdown appear in the file tree and the wiki, with special handlers extracting
+endpoints and targets where applicable.
---
## Code-health coverage
-Code-health markers run off a per-language complexity-walker map that is
-**independent** of `.scm` parsing, a language can parse perfectly for the graph
-yet still need this map before health markers fire. This table is why a language
-is "Full" vs "Good".
+Health markers run off a per-language walker map that is **independent** of
+`.scm` parsing: a language can parse perfectly for the graph and still need this
+map before markers fire. This table is why a language is Full rather than Good.
-| Language | Complexity / nesting | Class metrics (LCOM4, god-class) | Assertion smells | Extract Method (dataflow) | Performance risk |
+| Language | Complexity / nesting | Class metrics | Assertion smells | Extract Method | Performance risk |
|----------|:---:|:---:|:---:|:---:|:---:|
| Python | ✅ | ✅ | ✅ | ✅ | ✅ |
| TypeScript / JavaScript | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Svelte | ✅¹⁰ | ✅ | ✅ | ✅ | ✅ |
-| Vue | ✅¹⁰ | ✅ | ✅ | ✅ | ✅ |
+| Svelte · Vue | ✅ | ✅ | ✅ | ✅ | ✅ |
| Java | ✅ | ✅ | ✅ | ✅ | ✅ |
-| Go | ✅ | n/a¹ | ✅ | ✅ | ✅ |
-| Rust | ✅ | ✅ | ✅ | ✅ | ✅² |
+| Go | ✅ | n/a | ✅ | ✅ | ✅ |
+| Rust | ✅ | ✅ | ✅ | ✅ | ✅ |
+| C++ | ✅ | ✅ | ✅ | ✅ | ✅ |
| C# | ✅ | ✅ | ✅ | later | ✅ |
-| Kotlin | ✅ | ✅ | ✅ | later | ✅¹¹ |
-| C++ | ✅ | ✅ | ✅ | ✅ | ✅¹² |
-| Dart | ✅ | n/a³ | ✅ | later | ✅ |
-| Scala | ✅ | ✅ | ✅⁴ | later | ✅⁵ |
-| Ruby | ✅ | ✅⁶ | ✅⁷ | later | ✅⁸ |
-| Shell | ✅⁹ | n/a | n/a | n/a | n/a |
-| Object Pascal | ✅ | n/a¹⁴ | later | later | n/a |
-
-¹ Go methods attach to a type via an external receiver rather than nesting in a
-class body, so class-level metrics aren't computable; Go gets the function- and
-assertion-level markers.
-² Rust omits `string_concat_in_loop` by design (`String::push_str` is amortized
-O(1), so it would be a guaranteed false positive).
-³ Dart assertion smells cover `assert` statements only; `expect()` calls have no
-call-node type to key on.
-⁴ Plain `assert(...)` and munit/JUnit-style `assert*` calls are counted;
-ScalaTest's infix DSL (`x shouldBe y`) has no assert-prefixed callee and is not.
-⁵ Rides the JVM sink lexicon (JDBC / JPA / Spring-Data interop) plus
-Scala-native boundaries (`scala.io.Source`, os-lib, sttp / http4s, Slick /
-doobie). Scala-specific markers: `"...".r` regex recompile in a loop and
-`Await.result` / `Thread.sleep` inside a `Future`-returning def
-(`blocking_sync_in_async`). Combinator iteration (`.map` / `.foreach`) is not
-loop-tracked yet; loops are `while` / `do-while` / for-comprehensions.
-⁶ Class size / method-count / god-class facts only. LCOM4 deliberately sits at
-its "no signal" valve: idiomatic Ruby reaches state via receiver-less `@ivar`
-reads and bare sibling-method calls, so the only mappable shape (`self.member`)
-is too sparse to build an honest cohesion graph on. `@ivar` text grouping is a
-possible follow-up.
-⁷ Bare `assert` and minitest `assert_*` calls plus RSpec `expect(...)` chains
-are counted; minitest's `refute_*` family is not (no assert/expect prefix), and
-RSpec examples (`it ... do` blocks) are not methods, so assertion-run smells
-fire on minitest-style test methods only.
-⁸ **Loops include Ruby's real iteration idiom**: a combinator call with an
-inline block (`.each` / `.map` / `.times` / `find_each` …) counts as a loop
-scope — the block body is per-iteration, the receiver runs once, and
-literal-receiver bounds (`3.times`, `[1, 2].each`, `ALL_CAPS.each`) are
-constant-suppressed. ActiveRecord sinks are stratified: distinctive verbs
-(`find_by` / `pluck` / `update_all` / bang persistence `create!`…) fire
-ungated, `where` needs a constant-rooted receiver, and collision-prone verbs
-(`find` / `first` / `count` / `save`…) need a classified db `require` — which
-Zeitwerk-autoloaded Rails files rarely carry, a deliberate recall ceiling that
-keeps in-memory `Registry.find(name)` lookups silent. Backticks / `system` /
-`Open3` are subprocess sinks; `s += "…"` in a loop is flagged while `s << x`
-(amortized append) never is.
-
-¹⁰ Svelte and Vue ride the TypeScript dialect on all three health layers, because a
-component reaches them as a TypeScript buffer. Markers therefore cover the
-`<script>` blocks and markup expressions — the parts that *are* JS. Markup
-structure and `<style>` carry no health signal, so a component's markers
-describe its logic, not its template size.
-
-¹¹ Kotlin rides the JVM sink lexicon (JDBC / JPA / Spring-Data interop) plus
-Kotlin-native boundaries (JetBrains Exposed, `File`-only `kotlin.io`
-extensions). **Loops include combinator iteration**: a call with a trailing
-lambda whose method is a full-iteration combinator (`forEach` / `map` /
-`filter` / `fold` …) is a loop scope via the shared `block_loop_body` hook Ruby
-established — scope functions (`let` / `apply` / `run`) and early-exit searches
-(`firstOrNull`) deliberately are not. `suspend` is a modifier *token*, so
-`blocking_sync_in_async` fires on `runBlocking` / `Thread.sleep` inside a
-`suspend fun`. Three deliberate recall ceilings, each set after a false
-positive on a real corpus: bare HTTP verbs are excluded (they are the
-route-registration DSL of every Kotlin web framework), the generic
-`kotlin.io` stream verbs `readText` / `writeText` / `readBytes` / `copyTo` are
-excluded (`kotlinx-io` reuses them on in-memory buffers), and the ambiguous db
-stratum drops `find` / `get` / `count` (they are stdlib collection
-combinators here, unlike in Java). A regex pattern containing a string
-template is not reported, because it is not hoistable.
-
-¹² C++ is deliberately narrow, and omits three markers other languages carry
-because each would be a guaranteed false positive: `string_concat_in_loop`
-(`std::string::operator+=` appends in place into a geometrically-grown buffer —
-amortized O(1), the same reason Rust omits it), `resource_construction_in_loop`
-(a loop-built `std::ifstream` is opened over a per-iteration *path*, and
-`std::thread` in a loop is how a thread pool is built), and
-`blocking_io_under_lock` (an RAII `lock_guard` holds to the end of the
-*enclosing* block, so no node's body is the held region). What remains:
-`io_in_loop` over POSIX / `std::filesystem` / libcurl / sqlite3 / MySQL /
-libpq entry points, `regex_compile_in_loop` on a constant-pattern `std::regex`,
-and `lock_in_loop`. Two ceilings: a C free function classifies only when
-*truly unqualified* (a namespaced call merely sharing a POSIX name — `json::accept`,
-`std::fprintf` — never does), and the socket verbs that double as plausible
-member names (`send` / `recv` / `connect` / `bind` / `listen` / `accept`) are
-excluded, because an implicit-`this` member call is spelled identically. C has
-no `LanguageNodeMap` at all, so it reaches no dialect despite sharing the
-grammar.
-
-¹³ **Kotlin dataflow is blocked on tree-sitter-kotlin, not merely unscheduled.**
-The def/use dialect itself would be routine; the CFG builder and the Extract
-Method slicer are what the grammar defeats, in four independent places:
-`function_declaration` labels no `body` field (and wraps its block in a
-`function_body` sibling, so the existing single-child unwrap misses it);
-`for_statement` / `while_statement` label no `body` field either;
-`if_expression` labels no `alternative` field and has no `else_clause` node, so
-an `else` body would be silently dropped from the CFG; and a bare `break` /
-`continue` parses as a plain `identifier`, with no node type to key on. That
-last one is the blocker that matters: the slicer refuses any span containing a
-jump, so invisible jumps would let it propose an Extract Method that silently
-changes control flow — a wrong suggestion, not a missing one. Kotlin therefore
-stays at "no dataflow signal", which is the correct degradation. Reviving this
-needs either a grammar upgrade or a text-based jump seam plus positional
-body/else resolution in the CFG core.
-
-⁹ Shell gets function-level complexity only (CCN / nesting / cognitive / NLOC).
-`&&` / `||` command lists count toward CCN (`cmd || exit 1` is +1), which is
-honest: shell branching is chained command lists. There are no classes,
-assertions, dataflow, or perf dialect for shell.
-
-¹⁴ **Pascal has no single node grouping a type's method bodies.** A class
-declaration (`declType` → `declClass`) holds only method *signatures*
-(`declProc`, no body); the implementation of each qualified method
-(`TFoo.Bar`) is a separate top-level node keyed by name, not nested inside
-the class. Class-level analysis expects methods physically nested in the
-class node, so mapping it here would silently emit a `ClassComplexity` with
-`method_count == 0` for every class — same posture as Go's external-receiver
-methods (footnote 1): left unmapped rather than emit a misleading zero.
-Function-level complexity/nesting/cognitive and the CFG (branch/loop/try/with,
-raise) are unaffected; no `DefUseDialect` is registered yet, so Extract Method
-stays at "no signal" like C# / Kotlin / Scala / Ruby.
-
-The **performance** signal (`io_in_loop`, `string_concat_in_loop`,
-`resource_construction_in_loop`, language-specific markers like Go
-`defer_in_loop` and C# sync-over-async) and the **dataflow** layer (powering
-Extract Method) each roll out per language in value order, degrading to silence
-where a dialect isn't wired yet. Per-marker mechanics and precision hazards:
-[CODE_HEALTH.md](CODE_HEALTH.md).
+| Kotlin | ✅ | ✅ | ✅ | blocked | ✅ |
+| Scala | ✅ | ✅ | ✅ | later | ✅ |
+| Ruby | ✅ | ✅ | ✅ | later | ✅ |
+| Dart | ✅ | n/a | ✅ | later | ✅ |
+| Object Pascal | ✅ | n/a | later | later | n/a |
+| Shell | ✅ | n/a | n/a | n/a | n/a |
+
+Every cell is a deliberate call, not an oversight. Go and Object Pascal have no
+class metrics because neither language nests a type's method *bodies* inside the
+type; mapping them anyway would emit a class with `method_count == 0` for every
+class in the repo. Kotlin's Extract Method is **blocked on the grammar**, not
+unscheduled: tree-sitter-kotlin parses a bare `break` as a plain identifier, and
+a slicer that cannot see a jump would propose an extraction that silently changes
+control flow. Rust and C++ omit `string_concat_in_loop` because both append in
+amortized O(1), so it would be a guaranteed false positive.
+
+Per-marker mechanics, every per-language precision ceiling and the reasoning
+behind each `n/a`: [CODE_HEALTH.md](CODE_HEALTH.md) and
+[architecture/language-support.md](../architecture/language-support.md).
+
+---
+
+## Known ceilings
+
+Stated plainly, because a ceiling you know about is worth more than a claim you
+cannot check.
+
+- **Template dialects are invisible.** Django/Jinja, Go templates, ERB,
+ Handlebars, Blade and Thymeleaf parse cleanly as HTML and yield nothing:
+ `{% extends "base.html" %}` is plain text to an HTML parser. Covering them
+ needs a per-dialect regex tier gated on a framework manifest.
+- **Svelte and Vue binding forms are skipped.** `{#each x as y}` and
+ `v-for="x in xs"` *parse* as JS but mean something else, so they are skipped: a
+ parse that succeeds with the wrong meaning is worse than a skip. Component
+ props are set by the parent as markup attributes and never imported by name, so
+ the unused-export pass is suppressed for both.
+- **Object Pascal type kinds collapse.** `record` / `interface` / class-helper /
+ enum / type alias all report as `kind="class"`, and its `extends` vs
+ `implements` split is inferred from the `I`-prefix naming convention rather
+ than guaranteed by the language.
+- **C has no health dialect.** It shares the C++ grammar for parsing but reaches
+ no health walker map, so it gets graph coverage without markers.
+- **Scala import resolution is partial**, and ScalaTest's infix DSL
+ (`x shouldBe y`) is not counted as an assertion: there is no assert-prefixed
+ callee to key on.
---
## Roadmap
-| Language | Target tier | Status |
-|----------|------------|--------|
-| Vue | Full | Shipped: TS projection of `<script>` / `<script setup>` + template expressions, component symbols with tag-consistent naming, `<Foo />` call edges, alias + directory-index + dynamic-`import()` resolution, all three health dialects. Next: Options-API `pair`-function members, `v-for` head bindings |
-| Svelte | Full | Shipped: TS projection of `<script>` + markup expressions, component symbols, `<Foo />` call edges, `$lib` / `#`-subpath resolution, SvelteKit route edges, all three health dialects. Next: `{#each}` head bindings, object-literal attributes, `.svelte.ts` rune modules |
-| Dart | Good | Shipped: AST, health control-flow + class facts, perf dialect, Flutter edges. Next: riverpod/get_it dynamic hints, dataflow dialect |
-| Scala | Full (health) | Shipped: complexity/class/assertion markers + perf dialect (JVM lexicon, `.r` recompile, sync-over-Future). Next: dataflow dialect, combinator (`.map`/`.foreach`) loop tracking via the shared `block_loop_body` hook Ruby established |
-| Ruby | Full (health) | Shipped: complexity/class/assertion markers + perf dialect with block-iteration loops (`.each`/`.map` blocks) and the stratified ActiveRecord N+1 lexicon. Next: dataflow dialect, LCOM4 via `@ivar` grouping |
-| Kotlin | Full (health) | Shipped: complexity/class/assertion markers + perf dialect (JVM lexicon, Exposed, combinator loops via `block_loop_body`, `suspend` sync-in-async). Dataflow is **blocked on the grammar**, not unstarted — see ¹³ |
-| C++ | Full | Shipped: complexity/class/assertion markers, perf dialect (POSIX / `std::filesystem` / sqlite3 sinks, constant-pattern `std::regex` recompile, `lock_in_loop`), and the dataflow dialect powering Extract Method |
-| C# | Full (health) | Dataflow dialect pending; perf shipped |
-| Elixir | Good | Lightweight tier shipped; AST upgrade planned (`tree-sitter-elixir` available) |
-| F# | Good | Lightweight tier shipped; AST upgrade planned (`tree-sitter-f-sharp` available) |
-| SQL / dbt | - | DDL symbols, dbt lineage, app-to-database contracts, health markers shipped. Next: column-level blast radius |
-| Shell | - | Function symbols, `source` import edges, function-level complexity shipped. Next: shebang-based detection of extensionless executables (a traverser capability) |
-| HTML | Lightweight | Shipped: `<script src>` / `<link href>` edges with document-, `public/`- and root-relative resolution; never dead-code flagged. Stays import-tier — HTML has no symbols. Next: a regex import tier for template dialects (Django/Jinja, Go templates, ERB, Handlebars), gated on a framework manifest |
+| Language | Target | Next |
+|----------|--------|------|
+| Vue | Full | Options-API `pair`-function members, `v-for` head bindings |
+| Svelte | Full | `{#each}` head bindings, object-literal attributes, `.svelte.ts` rune modules |
+| Kotlin | Full (health) | Dataflow is **blocked on the grammar** and needs a grammar upgrade or a text-based jump seam |
+| Scala | Full (health) | Dataflow dialect, combinator (`.map` / `.foreach`) loop tracking |
+| Ruby | Full (health) | Dataflow dialect, LCOM4 via `@ivar` grouping |
+| C# | Full (health) | Dataflow dialect |
+| Dart | Good | riverpod / get_it dynamic hints, dataflow dialect |
+| Object Pascal | Good | Assertion and performance markers, a dedicated `uses` resolver |
+| Elixir · F# | Good | AST upgrade (both grammars are available on PyPI) |
+| SQL / dbt | — | Column-level blast radius |
+| Shell | — | Shebang detection for extensionless executables |
+| HTML | Lightweight | A regex import tier for template dialects, gated on a framework manifest |
---
## See also
-- [architecture/language-support.md](../architecture/language-support.md), pipeline internals + how to add a language
-- [CODE_HEALTH.md](CODE_HEALTH.md), code-health markers and per-language precision
-- [WORKSPACES.md](../scale/WORKSPACES.md), cross-repo contracts and co-change
+- **[GRAPH.md](GRAPH.md)** · the graph itself: edge vocabulary, resolution origins, execution flows
+- **[architecture/language-support.md](../architecture/language-support.md)** · pipeline internals, the call-resolution architecture, and the contributor recipe for adding a language
+- [CODE_HEALTH.md](CODE_HEALTH.md) · health markers and per-language precision
+- [WORKSPACES.md](../scale/WORKSPACES.md) · cross-repo contracts and co-change
diff --git a/docs/reference/COMPUTED_GLOSSARY.md b/docs/reference/COMPUTED_GLOSSARY.md
index 9051f97c0..67759c15f 100644
--- a/docs/reference/COMPUTED_GLOSSARY.md
+++ b/docs/reference/COMPUTED_GLOSSARY.md
@@ -393,7 +393,7 @@ workspace overlays, MCP responses, and CLI output.
| Dead-code status | `open`, `acknowledged`, `resolved`, `false_positive` |
| Security severity | `high`, `med`, `low` |
| Security kind | `eval_call`, `exec_call`, `pickle_loads`, `subprocess_shell_true`, `os_system`, `hardcoded_password`, `hardcoded_secret`, `fstring_sql`, `concat_sql`, `tls_verify_false`, `weak_hash`, `security_sensitive_symbol` |
-| Edge type | `imports`, `defines`, `calls`, `has_method`, `extends`, `implements`, `method_implements`, `co_changes`, `framework`, `reads`, `type_use`, `dynamic_uses`, `dynamic_imports`, `dynamic_url_route` — the complete list, declared as `EdgeType` in `ingestion/models.py` and enforced by `tests/unit/ingestion/test_edge_type_vocabulary.py` |
+| Edge type | `imports`, `defines`, `calls`, `has_method`, `extends`, `implements`, `method_implements`, `dispatches_to`, `co_changes`, `framework`, `framework_binds`, `reads`, `type_use`, `dynamic_uses`, `dynamic_imports`, `dynamic_url_route`, `references`; all 17, declared as `EdgeType` in `ingestion/models.py` and enforced by `tests/unit/ingestion/test_edge_type_vocabulary.py`. `reads` is file-to-file only; its former symbol-level producer emits `framework_binds` |
| Node type | `file`, `symbol`, `external` |
| Search type | `vector`, `fulltext` |
| Contract type | `http`, `grpc`, `topic` |