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.

Typed node ids, and a Structurizr DSL export built on them (#1143)

Swati Ahuja60d52322b661
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 798207bfe..686a01aa0 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -144,3 +144,76 @@ jobs:
- name: Package VSIX (no login required)
run: npm run package --workspace packages/vscode
+
+ # ---------------------------------------------------------------------------
+ # Structurizr DSL — parse the emitter's output with the real parser.
+ #
+ # The unit tests can prove our own invariants (braces balance, no dangling
+ # references, stable identifiers) but not that the result is valid
+ # Structurizr; only Structurizr's parser knows that. Silently invalid DSL is
+ # the one failure mode users would notice before we did.
+ #
+ # Path-gated because it pulls a ~300MB image: it runs when the emitter or the
+ # sample changes, not on every PR.
+ # ---------------------------------------------------------------------------
+ structurizr-dsl:
+ name: Structurizr DSL parses
+ runs-on: ubuntu-latest
+ if: github.event_name == 'push' || github.event_name == 'pull_request'
+
+ steps:
+ - uses: actions/checkout@v4
+
+ - name: Check whether the emitter changed
+ id: changed
+ uses: dorny/paths-filter@v3
+ with:
+ filters: |
+ emitter:
+ - 'packages/server/src/repowise/server/services/c4_builder/**'
+ # Every C4 id is rendered through this, so a change here changes
+ # every identifier in the emitted file.
+ - 'packages/core/src/repowise/core/ids.py'
+ - 'scripts/emit_sample_dsl.py'
+ - 'tests/unit/server/test_structurizr_export.py'
+ - '.github/workflows/ci.yml'
+
+ - name: Install uv
+ if: steps.changed.outputs.emitter == 'true'
+ uses: astral-sh/setup-uv@v3
+ with:
+ version: "latest"
+ enable-cache: true
+
+ - name: Install dependencies
+ if: steps.changed.outputs.emitter == 'true'
+ run: uv sync --all-packages
+
+ - name: Emit a sample workspace and fragment
+ if: steps.changed.outputs.emitter == 'true'
+ run: uv run python scripts/emit_sample_dsl.py dsl-sample
+
+ - name: Validate the standalone workspace
+ if: steps.changed.outputs.emitter == 'true'
+ run: |
+ docker run --rm -v "$PWD/dsl-sample:/work" \
+ structurizr/structurizr:latest validate -workspace /work/workspace.dsl
+
+ - name: Validate the fragment via a host workspace
+ if: steps.changed.outputs.emitter == 'true'
+ run: |
+ docker run --rm -v "$PWD/dsl-sample/fragment:/work" \
+ structurizr/structurizr:latest validate -workspace /work/workspace.dsl
+
+ - name: Render every view
+ if: steps.changed.outputs.emitter == 'true'
+ run: |
+ # The image runs as uid 65532, which cannot write into a checkout
+ # owned by the runner. Give the render its own world-writable
+ # directory rather than letting it write beside the DSL.
+ mkdir -m 777 dsl-sample/rendered
+ docker run --rm -v "$PWD/dsl-sample:/work" \
+ structurizr/structurizr:latest export -workspace /work/workspace.dsl \
+ -format mermaid -output /work/rendered
+ # An exporter that wrote nothing also exits 0.
+ test "$(find dsl-sample/rendered -name '*.mmd' | wc -l)" -gt 0
diff --git a/README.md b/README.md
index ea731efc5..0d2dd5643 100644
--- a/README.md
+++ b/README.md
@@ -550,6 +550,7 @@ repowise risk main..HEAD # score a branch or PR range for defect risk
repowise impacted-tests # only the tests a diff actually exercises
repowise dead-code # unreachable-code report
repowise decision list # architectural decisions
+repowise export --format structurizr # the architecture as Structurizr DSL, no LLM
repowise distill pytest # compact, errors-first, reversible command output
repowise saved # tokens and dollars saved by distillation
repowise workspace add # multi-repo workspace management
diff --git a/docs/README.md b/docs/README.md
index c05938f9e..d2269a06d 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -104,6 +104,7 @@ How repowise is built, for contributors and the curious.
| [architecture/graph-algorithms.md](architecture/graph-algorithms.md) | Every graph algorithm, the intuition plus the math |
| [architecture/language-support.md](architecture/language-support.md) | The language pipeline and how the tiers work |
| [architecture/chat.md](architecture/chat.md) | Codebase chat: agent loop, streaming, artifact panel |
+| [architecture/structurizr-export.md](architecture/structurizr-export.md) | Export the architecture as Structurizr DSL and render it anywhere |
| [architecture/editor-files.md](architecture/editor-files.md) | How `CLAUDE.md` and `AGENTS.md` get generated |
| [architecture/deep-dives.md](architecture/deep-dives.md) | Systems not covered elsewhere |
| [architecture/pluggable-storage.md](architecture/pluggable-storage.md) | The capability seams: storage, graph, vector, CLI, MCP |
diff --git a/docs/architecture/README.md b/docs/architecture/README.md
index ccbb34707..931803364 100644
--- a/docs/architecture/README.md
+++ b/docs/architecture/README.md
@@ -12,6 +12,7 @@ curious; you don't need them to *use* repowise (start with
| [language-support.md](language-support.md) | The language pipeline internals and the step-by-step recipe for adding a new language |
| [graph-algorithms.md](graph-algorithms.md) | The graph algorithms (PageRank, betweenness, Tarjan SCC, Louvain, shortest path) with the math and complexity |
| [chat.md](chat.md) | The Codebase Chat feature: schema, `ChatProvider` protocol, SSE streaming, the agentic loop, and per-provider notes |
+| [structurizr-export.md](structurizr-export.md) | Exporting the architecture as Structurizr DSL: the two-file model, health and layer tags, and how to render it |
| [editor-files.md](editor-files.md) | How `CLAUDE.md` / `AGENTS.md` generation works (no LLM: pure DB + filesystem derivation) and how to add a new editor file |
| [pluggable-storage.md](pluggable-storage.md) | Extension guide for authoring storage / graph / job-store plugins and adding CLI subcommands or MCP tools |
diff --git a/docs/architecture/structurizr-export.md b/docs/architecture/structurizr-export.md
new file mode 100644
index 000000000..96179c23f
--- /dev/null
+++ b/docs/architecture/structurizr-export.md
@@ -0,0 +1,272 @@
+# Structurizr DSL Export
+
+Repowise can emit your architecture as [Structurizr](https://structurizr.com)
+DSL — the C4 model as a text file you commit, diff and render in your own
+toolchain instead of ours.
+
+It is deterministic: no LLM call, no API key, works under `init --index-only`,
+and nothing is added to indexing. The file is built on demand from the graph
+that is already there.
+
+---
+
+## Table of Contents
+
+1. [The two-file mental model](#1-the-two-file-mental-model)
+2. [Getting a file](#2-getting-a-file)
+3. [Seeing it rendered](#3-seeing-it-rendered)
+4. [What is in the model](#4-what-is-in-the-model)
+5. [Health and layers](#5-health-and-layers)
+6. [Styling by health](#6-styling-by-health)
+7. [One view per layer](#7-one-view-per-layer)
+8. [Flags](#8-flags)
+9. [REST API](#9-rest-api)
+10. [Limits](#10-limits)
+
+---
+
+## 1. The two-file mental model
+
+**We own the model. You own the presentation.**
+
+By default the export writes `repowise-model.dsl`, which holds the contents of
+a `model { … }` block and nothing else — no views, no styles, no `workspace`
+line. You include it from your own `workspace.dsl`, where your views, styles,
+documentation and ADRs live:
+
+```
+workspace "your name" {
+ !include repowise-model.dsl
+
+ views {
+ systemContext sys_yourrepo {
+ include *
+ autolayout lr
+ }
+ }
+}
+```
+
+The include has to sit **inside** the `workspace` block; outside it the parser
+fails on line 1.
+
+Because the two files are separate, regenerating the model can never touch
+anything you wrote. Re-export as often as you like — the diff shows what
+changed in the architecture, not in your formatting.
+
+If you have no `workspace.dsl` yet, `--standalone` writes a complete one with
+default views so you get a picture from a single command.
+
+---
+
+## 2. Getting a file
+
+```bash
+repowise export --format structurizr
+```
+
+The command prints the include snippet with your real system identifier
+already filled in, so it pastes verbatim. It also prints counts — `0
+containers` means the index is the problem, not the format.
+
+Write it somewhere specific with `--output`. A path ending in `.dsl` names the
+file; anything else is treated as a directory:
+
+```bash
+repowise export --format structurizr --output docs/architecture/model.dsl
+repowise export --format structurizr --output docs/architecture/
+```
+
+---
+
+## 3. Seeing it rendered
+
+Structurizr Lite renders a workspace directory in the browser:
+
+```bash
+repowise export --format structurizr --standalone --output arch/
+cd arch && docker run --rm -p 8080:8080 \
+ -v .:/usr/local/structurizr structurizr/structurizr local
+```
+
+Then open <http://localhost:8080>.
+
+To export diagrams as files instead of viewing them:
+
+```bash
+docker run --rm -v .:/work structurizr/structurizr:latest \
+ export -workspace /work/workspace.dsl -format mermaid
+```
+
+`-format` also accepts `plantuml`, `dot` and `websequencediagrams` — writing
+the DSL gets you all of them for free.
+
+> The older `structurizr/cli` image is deprecated and now exits 0 without
+> doing anything, including on invalid input. Use `structurizr/structurizr`.
+
+---
+
+## 4. What is in the model
+
+| Repowise | Structurizr |
+|---|---|
+| The repository | `softwareSystem` |
+| A workspace package or top-level directory | `container` |
+| A directory inside a container | `component` (opt-in) |
+| A third-party dependency | `softwareSystem` tagged `External` |
+| How the system is entered (CLI, API, scheduler) | `person` |
+| A rolled-up dependency edge | `->` with the verb as its description |
+
+Descriptions are facts we already have — file and symbol counts, the dominant
+language, a dependency's ecosystem and version. Nothing is invented and no
+model is called, because a wrong description in your committed architecture
+file is worse than a plain one.
+
+Relationships carry the coupling bucket (`Loose` / `Moderate` / `Tight`) as a
+tag, so you can style or filter by how hard an edge is.
+
+---
+
+## 5. Health and layers
+
+This is the part C4 has no vocabulary for, and the reason the export is worth
+having over any tool that can list your directories.
+
+**Tags** on containers and components:
+
+| Tag | Meaning |
+|---|---|
+| `Hotspot` | The box holds at least one churn hotspot |
+| `Dead` | It holds at least one unreachable file |
+| `Layer: <name>` | Its files belong to that curated layer |
+
+**Properties**, all namespaced under `repowise.` so they can never collide
+with your own:
+
+| Property | Meaning |
+|---|---|
+| `repowise.hotspots` | How many hotspot files |
+| `repowise.deadFiles` | How many unreachable files |
+| `repowise.owner` / `repowise.ownerPct` | Who owns most of it, and their share |
+| `repowise.minBusFactor` | The lowest bus factor in the box — the worst case, not the average |
+| `repowise.layers` | Every layer the box's files belong to |
+
+Anything we do not know is **left out** rather than written as zero. A missing
+bus factor emitted as `0` would read as "nobody owns this", which is a much
+louder claim than the gap it actually is.
+
+The curated reading order rides along as a comment at the top of the file. It
+cannot be a Structurizr view, but it is one of the few things in there you
+could not have worked out yourself, so it is not dropped.
+
+---
+
+## 6. Styling by health
+
+Five lines in your `workspace.dsl` colour the health tags. Put them in your
+`views` block:
+
+```
+styles {
+ element "Hotspot" {
+ background #b5432f
+ color #ffffff
+ }
+ element "Dead" {
+ background #6b6b6b
+ color #ffffff
+ }
+ relationship "Tight" {
+ thickness 4
+ }
+}
+```
+
+Tag styles apply in declaration order, so `Hotspot` before `Dead` means a box
+that is both reads as dead — the more actionable of the two.
+
+---
+
+## 7. One view per layer
+
+Layer membership is a tag, so a filtered view is all it takes to see one layer
+at a time:
+
+```
+container sys_yourrepo "Domain layer" {
+ include "element.tag==Layer: Domain"
+ autolayout lr
+}
+```
+
+Same model, different message, different audience — and we neither build nor
+maintain the views. `--standalone` generates one of these per layer so you can
+see the shape before writing your own.
+
+---
+
+## 8. Flags
+
+| Flag | Default | What it does |
+|---|---|---|
+| `--standalone` | off | Emit a complete workspace with default views instead of a model fragment |
+| `--components` | off | Include the component level: one box per directory |
+| `--no-externals` | on (externals included) | Leave third-party dependencies out |
+| `--output PATH` | repo root | Where to write; `.dsl` names the file |
+
+**Why components are off by default.** In a hand-curated Structurizr model a
+component is a grouping somebody chose. Ours is a directory. Architects who
+already keep a curated model — exactly the people who want this export — will
+notice the difference immediately, so you opt in rather than out.
+
+---
+
+## 9. REST API
+
+```
+GET /api/graph/{repo_id}/c4/structurizr?standalone=&components=&externals=
+```
+
+Returns `text/plain` with a `Content-Disposition` filename, built on demand
+from the same builders. The C4 dashboard export menu uses this endpoint.
+
+---
+
+## 10. Limits
+
+- **One way only.** We never read your DSL back to seed our layers. That is a
+ different and much larger project.
+- **Identifiers are stable, and deliberately so.** They derive from the ids
+ themselves, never from iteration order, and the system's identifier comes
+ from the repo name rather than its local database id — otherwise two people
+ exporting the same repo would get files differing in every reference.
+- **No timestamp in the header.** A timestamp would make every regeneration a
+ diff and destroy the point of committing the file.
+- **Component views are capped** at 20 boxes in `--standalone`, because a
+ Structurizr view stops being readable past roughly that many. The cap is
+ stated in a comment rather than applied silently.
+- **Multi-repo workspaces** export one repo at a time today.
+
+---
+
+## 11. How this is verified
+
+Unit tests cover the emitter's own invariants — braces balance, no relationship
+references an element we did not emit, identifiers do not move when unrelated
+elements are added, re-emitting is byte-identical.
+
+None of that proves the output is *valid Structurizr*, because only their
+parser knows that. So CI emits a sample exercising every construct — nested
+components, a `(root)` bucket, a scoped npm package, health tags, layer views,
+a tour comment, an owner name containing quotes — and runs it through the real
+parser, in both the standalone and fragment shapes, then renders every view:
+
+```bash
+uv run python scripts/emit_sample_dsl.py dsl-sample
+docker run --rm -v "$PWD/dsl-sample:/work" \
+ structurizr/structurizr:latest validate -workspace /work/workspace.dsl
+```
+
+The job is path-gated to the emitter, so it costs nothing on unrelated PRs.
+Run those two commands locally after changing anything under
+`c4_builder/structurizr/`.
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index b652edaed..f4678f5c3 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -802,22 +802,31 @@ repowise costs --repo backend # one workspace repo
### `repowise export [PATH]`
-Export wiki pages to files.
+Export wiki pages to files, or the architecture model as Structurizr DSL.
**Options:**
| Flag | Description |
|------|-------------|
-| `--format` | `markdown` (default), `html`, `json` |
-| `--output / -o` | Output directory (default: `.repowise/export`) |
+| `--format` | `markdown` (default), `html`, `json`, `structurizr` |
+| `--output / -o` | Output directory (default: `.repowise/export`). For `structurizr`, a path ending in `.dsl` names the file itself |
| `--full` | Include decisions, dead code, hotspots, provenance metadata (JSON only) |
+| `--standalone` | `structurizr` only: emit a complete workspace with default views instead of a model fragment |
+| `--components` | `structurizr` only: include the component level (one box per directory) |
+| `--no-externals` | `structurizr` only: leave third-party dependencies out |
```bash
repowise export
repowise export --format json --full
repowise export --format html -o ./wiki/
+repowise export --format structurizr # repowise-model.dsl
+repowise export --format structurizr --standalone -o arch/ # renders on its own
```
+The `structurizr` format writes one file describing the architecture rather
+than a directory of pages. See
+[Structurizr DSL export](../architecture/structurizr-export.md).
+
---
## Workspace Commands
diff --git a/docs/reference/UPGRADING.md b/docs/reference/UPGRADING.md
index cc5d9714e..3d428d554 100644
--- a/docs/reference/UPGRADING.md
+++ b/docs/reference/UPGRADING.md
@@ -31,6 +31,36 @@ Reindex recommended: repowise init --force
It is a recommendation, not a requirement. Nothing is wiped until you choose to run it. You can keep using the current index and reindex when convenient.
+## Behaviour changes worth knowing about
+
+### `health-rules.json` globs now match like `.gitignore`
+
+Per-path rules in `.repowise/health-rules.json` used to be matched with
+`fnmatch`, where `*` crossed directory separators. They now use the same
+gitignore matching as `exclude_patterns`, `.gitignore` and the file traverser,
+so one glob means one thing wherever you write it.
+
+**What changes for you:** a single `*` stops at a path segment. A rule written
+as `src/legacy/*` used to silence the whole subtree and now covers one level,
+which means biomarkers you had turned off can start firing again.
+
+**The fix is one character:**
+
+```diff
+- {"path": "src/legacy/*", "disabled_biomarkers": ["complex_method"]}
++ {"path": "src/legacy/**", "disabled_biomarkers": ["complex_method"]}
+```
+
+You do not have to hunt for them. Any affected pattern logs a warning naming
+the pattern when the file is loaded:
+
+```
+health_rules_glob_narrowed pattern=src/legacy/* hint='*' no longer crosses '/' …
+```
+
+Patterns without a `/`, patterns already using `**`, and directory prefixes
+like `vendor/` are unaffected.
+
## Checking your version
- CLI: `repowise --version`, or `repowise doctor` for an update check with the right upgrade command for your install method.
diff --git a/packages/api-client/src/c4.ts b/packages/api-client/src/c4.ts
index f2e9bbb70..8be0d1ba8 100644
--- a/packages/api-client/src/c4.ts
+++ b/packages/api-client/src/c4.ts
@@ -38,6 +38,40 @@ export async function getC4Mermaid(
return res.text();
}
+export interface StructurizrOptions {
+ /** Emit a complete runnable workspace instead of a model fragment. */
+ standalone?: boolean;
+ /** Include the component (L3) level — one box per directory. */
+ components?: boolean;
+ /** Include third-party dependencies. Defaults to true server-side. */
+ externals?: boolean;
+}
+
+/**
+ * Fetch the Structurizr DSL for this repository.
+ *
+ * Text rather than JSON, like `getC4Mermaid` — the DSL is the artefact people
+ * commit and read, so the backend returns it verbatim.
+ */
+export async function getStructurizrDsl(
+ repoId: string,
+ options: StructurizrOptions = {},
+): Promise<string> {
+ const params = new URLSearchParams();
+ if (options.standalone) params.set("standalone", "true");
+ if (options.components) params.set("components", "true");
+ if (options.externals === false) params.set("externals", "false");
+ const query = params.toString();
+ const res = await doFetch(
+ `${BASE_URL}/api/graph/${repoId}/c4/structurizr${query ? `?${query}` : ""}`,
+ { headers: buildHeaders() },
+ );
+ if (!res.ok) {
+ throw new Error(`Failed to fetch Structurizr DSL (${res.status})`);
+ }
+ return res.text();
+}
+
export async function getArchitectureView(
repoId: string,
includeSymbols: boolean = false,
diff --git a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py b/packages/cli/src/repowise/cli/commands/augment_cmd/search.py
index b727636b8..b5b8ad310 100644
--- a/packages/cli/src/repowise/cli/commands/augment_cmd/search.py
+++ b/packages/cli/src/repowise/cli/commands/augment_cmd/search.py
@@ -4,6 +4,8 @@ from __future__ import annotations
from pathlib import Path
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
+
from ._shared import _extract_output_text, _find_repo_root
# Tunables — fixed thresholds keep the fire pattern predictable across
@@ -440,7 +442,9 @@ async def _rescue(
# Build a small set of token variants. Cheap; helps catch case-style
# drift without a heavy similarity index.
variants = _name_variants(clean)
- like_clauses = [WikiSymbol.name.ilike(f"%{v}%") for v in variants]
+ like_clauses = [
+ WikiSymbol.name.ilike(f"%{escape_like(v)}%", escape=LIKE_ESCAPE) for v in variants
+ ]
sym_stmt = (
select(WikiSymbol.name, WikiSymbol.kind, WikiSymbol.file_path, WikiSymbol.start_line)
.where(WikiSymbol.repository_id == repo_id, or_(*like_clauses))
@@ -521,7 +525,7 @@ async def _triage(
select(WikiSymbol.file_path)
.where(
WikiSymbol.repository_id == repo_id,
- WikiSymbol.name.ilike(f"%{clean}%"),
+ WikiSymbol.name.ilike(f"%{escape_like(clean)}%", escape=LIKE_ESCAPE),
)
.distinct()
.limit(50)
@@ -533,7 +537,7 @@ async def _triage(
.where(
GraphNode.repository_id == repo_id,
GraphNode.node_type == "file",
- GraphNode.node_id.ilike(f"%{clean}%"),
+ GraphNode.node_id.ilike(f"%{escape_like(clean)}%", escape=LIKE_ESCAPE),
)
.limit(50)
)
diff --git a/packages/cli/src/repowise/cli/commands/decision_cmd.py b/packages/cli/src/repowise/cli/commands/decision_cmd.py
index e1f20b584..ded20f933 100644
--- a/packages/cli/src/repowise/cli/commands/decision_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/decision_cmd.py
@@ -50,9 +50,12 @@ async def _resolve_decision_id(session, decision_id: str) -> str | None:
from sqlalchemy import select
from repowise.core.persistence.models import DecisionRecord
+ from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
result = await session.execute(
- select(DecisionRecord.id).where(DecisionRecord.id.like(f"{decision_id}%")).limit(2)
+ select(DecisionRecord.id)
+ .where(DecisionRecord.id.like(f"{escape_like(decision_id)}%", escape=LIKE_ESCAPE))
+ .limit(2)
)
ids = [row[0] for row in result.all()]
if len(ids) > 1:
diff --git a/packages/cli/src/repowise/cli/commands/export_cmd.py b/packages/cli/src/repowise/cli/commands/export_cmd.py
index 56a2ab70a..ee592901a 100644
--- a/packages/cli/src/repowise/cli/commands/export_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/export_cmd.py
@@ -22,16 +22,18 @@ from repowise.cli.helpers import (
@click.option(
"--format",
"fmt",
- type=click.Choice(["markdown", "html", "json"]),
+ type=click.Choice(["markdown", "html", "json", "structurizr"]),
default="markdown",
- help="Output format.",
+ help="Output format. 'structurizr' writes one Structurizr DSL file "
+ "describing the architecture rather than a directory of wiki pages.",
)
@click.option(
"--output",
"-o",
"output_dir",
default=None,
- help="Output directory (default: .repowise/export).",
+ help="Output directory (default: .repowise/export). For --format structurizr, "
+ "a path ending in .dsl names the file itself.",
)
@click.option(
"--full",
@@ -40,16 +42,54 @@ from repowise.cli.helpers import (
default=False,
help="Include decisions, dead code, git metadata, and provenance in JSON export.",
)
+ "--standalone",
+ is_flag=True,
+ default=False,
+ help="structurizr only: emit a complete workspace with default views instead "
+ "of a model fragment to include from your own workspace.dsl.",
+)
+ "--components",
+ "include_components",
+ is_flag=True,
+ default=False,
+ help="structurizr only: include the component level (one box per directory).",
+)
+ "--no-externals",
+ "include_externals",
+ flag_value=False,
+ default=True,
+ help="structurizr only: leave third-party dependencies out of the model.",
+)
def export_command(
path: str | None,
fmt: str,
output_dir: str | None,
full_export: bool = False,
+ standalone: bool = False,
+ include_components: bool = False,
+ include_externals: bool = True,
) -> None:
- """Export wiki pages to files."""
+ """Export wiki pages, or the architecture model, to files."""
repo_path = resolve_repo_path(path)
ensure_repowise_dir(repo_path)
+ if fmt == "structurizr":
+ from repowise.cli.commands.export_structurizr import export_structurizr
+
+ code = export_structurizr(
+ repo_path,
+ output=output_dir,
+ standalone=standalone,
+ include_components=include_components,
+ include_externals=include_externals,
+ )
+ if code:
+ raise SystemExit(code)
+ return
+
out = repo_path / ".repowise" / "export" if output_dir is None else Path(output_dir).resolve()
out.mkdir(parents=True, exist_ok=True)
diff --git a/packages/cli/src/repowise/cli/commands/export_structurizr.py b/packages/cli/src/repowise/cli/commands/export_structurizr.py
new file mode 100644
index 000000000..f46e64e67
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/export_structurizr.py
@@ -0,0 +1,209 @@
+"""``repowise export --format structurizr`` — write a Structurizr DSL model.
+
+Split out of ``export_cmd`` because it shares almost nothing with the wiki-page
+exports: one file rather than a directory of pages, and built from the graph
+rather than from generated documentation.
+
+The success message is most of this module on purpose. The default output is a
+model *fragment*, so a user who opens it and finds no ``workspace`` block and
+no views can reasonably conclude it is broken. Everything printed here exists
+to prevent that moment.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.cli.helpers import console, get_db_url_for_repo
+
+#: What we write next to the user's own workspace.dsl.
+FRAGMENT_FILENAME = "repowise-model.dsl"
+
+#: What we write when there is nothing to include it from.
+STANDALONE_FILENAME = "workspace.dsl"
+
+_LITE_COMMAND = (
+ "docker run --rm -p 8080:8080 -v .:/usr/local/structurizr structurizr/structurizr local"
+)
+
+
+def _resolve_output(output: str | None, repo_path: Path, *, standalone: bool) -> Path:
+ """Where to write. A path ending in ``.dsl`` is the file; anything else is
+ a directory to put the default filename in."""
+ default_name = STANDALONE_FILENAME if standalone else FRAGMENT_FILENAME
+ if output is None:
+ return repo_path / default_name
+ candidate = Path(output).resolve()
+ # Case-insensitive: --out MODEL.DSL meant a directory called MODEL.DSL,
+ # and the file landed inside it.
+ if candidate.suffix.lower() == ".dsl":
+ return candidate
+ return candidate / default_name
+
+
+async def _build(repo_path: Path, *, include_components: bool):
+ """Build the model, or ``None`` when this repo has no usable index.
+
+ A missing database and a database with no tables both mean "not indexed
+ yet" to a user, so both return ``None`` rather than surfacing a SQL error
+ from six frames down.
+ """
+ from sqlalchemy.exc import OperationalError
+
+ from repowise.core.persistence import (
+ create_engine,
+ create_session_factory,
+ get_repository_by_path,
+ get_session,
+ )
+ from repowise.server.services.c4_builder import build_model
+
+ engine = create_engine(get_db_url_for_repo(repo_path))
+ session_factory = create_session_factory(engine)
+ try:
+ async with get_session(session_factory) as session:
+ repo = await get_repository_by_path(session, str(repo_path))
+ if repo is None:
+ return None
+ return await build_model(session, repo.id, include_components=include_components)
+ except OperationalError:
+ return None
+ finally:
+ await engine.dispose()
+
+
+def _counts(model, *, include_components: bool, include_externals: bool) -> str:
+ """The sanity check in the success line.
+
+ ``0 containers`` tells a user the problem is their index, not the format —
+ which is the difference between a support question and a re-run.
+ """
+ parts = [f"{len(model.containers)} containers"]
+ if include_components:
+ total = sum(len(v) for v in model.components_by_container.values())
+ parts.append(f"{total} components")
+ if include_externals:
+ parts.append(f"{len(model.external_systems)} external systems")
+ # Count what the file will hold, not one of the two lists it draws from:
+ # the actor edges are always written, and with components on the container
+ # edges that cross our boundary are kept alongside the component ones.
+ relations = set()
+ for relation in model.actor_relations:
+ relations.add((relation.source_id, relation.target_id))
+ for relation in model.component_relations if include_components else ():
+ relations.add((relation.source_id, relation.target_id))
+ external_ids = {e.id for e in model.external_systems}
+ componentless = {
+ container.id
+ for container in model.containers
+ if not model.components_by_container.get(container.id)
+ }
+ for relation in model.container_relations:
+ keeps = (
+ not include_components
+ or relation.source_id in external_ids
+ or relation.target_id in external_ids
+ or relation.source_id in componentless
+ or relation.target_id in componentless
+ )
+ if keeps:
+ relations.add((relation.source_id, relation.target_id))
+ parts.append(f"{len(relations)} relations")
+ return ", ".join(parts)
+
+
+def _line(text: str = "") -> None:
+ """Print without wrapping or markup.
+
+ Every line here is meant to be copied, and Rich will happily break a long
+ docker command across two lines and put a stray dot at the start of the
+ second one.
+ """
+ console.print(text, soft_wrap=True, markup=False, highlight=False)
+
+
+def _print_next_steps(destination: Path, *, standalone: bool, system_id: str) -> None:
+ """Say what to do next, not just what was written."""
+ directory = destination.parent
+ if standalone:
+ _line("\n View it:")
+ _line(f" cd {directory} && {_LITE_COMMAND}\n")
+ return
+
+ _line("\n Add this to your workspace.dsl:\n")
+ _line(' workspace "your name" {')
+ _line(f" !include {destination.name}")
+ _line("")
+ _line(" views {")
+ _line(f" systemContext {system_id} {{")
+ _line(" include *")
+ _line(" autolayout lr")
+ _line(" }")
+ _line(" }")
+ _line(" }\n")
+
+ # Only offered to people who have nothing to include it from — nagging
+ # someone who already keeps a workspace.dsl is how a helpful hint becomes
+ # noise.
+ if not (directory / STANDALONE_FILENAME).exists():
+ _line(" No workspace.dsl yet?")
+ _line(" repowise export --format structurizr --standalone\n")
+
+ _line(" View it:")
+ _line(f" cd {directory} && {_LITE_COMMAND}\n")
+
+
+def export_structurizr(
+ repo_path: Path,
+ *,
+ output: str | None,
+ standalone: bool,
+ include_components: bool,
+ include_externals: bool,
+) -> int:
+ """Write the DSL. Returns a process exit code."""
+ from repowise.cli.helpers import run_async
+ from repowise.server.services.c4_builder.structurizr import (
+ system_identifier,
+ to_dsl,
+ )
+
+ model = run_async(_build(repo_path, include_components=include_components))
+ if model is None:
+ console.print(
+ "[yellow]This repository is not indexed yet. Run 'repowise init' first.[/yellow]"
+ )
+ return 1
+
+ if not model.containers:
+ # A valid but empty file is worse than an error: it looks like the
+ # repo genuinely has no structure.
+ console.print(
+ "[yellow]No containers were detected, so there is nothing to export.[/yellow]\n"
+ "Containers come from package manifests and top-level directories — "
+ "if this repo has them, the index may be stale. Try 'repowise update'."
+ )
+ return 1
+
+ destination = _resolve_output(output, repo_path, standalone=standalone)
+ destination.parent.mkdir(parents=True, exist_ok=True)
+ destination.write_text(
+ to_dsl(
+ model,
+ standalone=standalone,
+ include_components=include_components,
+ include_externals=include_externals,
+ ),
+ encoding="utf-8",
+ )
+
+ summary = _counts(
+ model, include_components=include_components, include_externals=include_externals
+ )
+ console.print(f"\n[bold green]Wrote {destination}[/bold green] ({summary})")
+ _print_next_steps(
+ destination,
+ standalone=standalone,
+ system_id=system_identifier(model, include_components=include_components),
+ )
+ return 0
diff --git a/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.py b/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.py
index 9810938c7..2788b0639 100644
--- a/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.py
+++ b/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.py
@@ -19,6 +19,7 @@ from __future__ import annotations
from pathlib import Path
+from repowise.core.ids import is_external
# Patterns in source that indicate dynamic/runtime imports, keyed by suffix.
_DYNAMIC_IMPORT_MARKERS: dict[str, tuple[str, ...]] = {
@@ -489,7 +490,7 @@ def find_dynamic_edge_files(graph) -> set[str]:
if endpoint is None:
continue
endpoint_str = str(endpoint)
- if endpoint_str.startswith("external:"):
+ if is_external(endpoint_str):
continue
node_data = graph.nodes.get(endpoint, {})
file_path = node_data.get("file_path")
diff --git a/packages/core/src/repowise/core/analysis/execution_flows.py b/packages/core/src/repowise/core/analysis/execution_flows.py
index 4ff1fffac..3e8189154 100644
--- a/packages/core/src/repowise/core/analysis/execution_flows.py
+++ b/packages/core/src/repowise/core/analysis/execution_flows.py
@@ -14,6 +14,8 @@ from dataclasses import dataclass, field
import networkx as nx
import structlog
+from repowise.core.ids import file_path_of
+
log = structlog.get_logger(__name__)
# ---------------------------------------------------------------------------
@@ -114,11 +116,17 @@ def _build_call_degree_maps(
def _is_excluded_node(graph: nx.DiGraph, node_id: str) -> bool:
- """True if the node lives in a test/demo/fixture/script path."""
+ """True if the node lives in a test/demo/fixture/script path.
+
+ Only symbol nodes carry a ``file_path`` attribute, so the id is the
+ fallback. That covers a file node — whose id *is* its path — and an
+ unresolved call target, where the bare name is all we have. Both were
+ previously read as "no path" and so never excluded, which let
+ ``scripts/build.py`` and a mis-resolved ``test_helper`` into traces this
+ function exists to keep production-only.
+ """
data = graph.nodes.get(node_id, {})
- file_path = data.get("file_path") or (
- node_id.split("::", 1)[0] if "::" in node_id else ""
- )
+ file_path = data.get("file_path") or file_path_of(node_id) or ""
return bool(_EXCLUDE_PATH_PATTERNS.search(file_path))
diff --git a/packages/core/src/repowise/core/analysis/health/config.py b/packages/core/src/repowise/core/analysis/health/config.py
index 74a4aba6f..73bf69555 100644
--- a/packages/core/src/repowise/core/analysis/health/config.py
+++ b/packages/core/src/repowise/core/analysis/health/config.py
@@ -6,8 +6,14 @@ detector list. Decisions deliberately kept narrow in v1:
- Repo-wide ``disabled_biomarkers``: detectors that never fire.
- Per-path ``rules``: a list of glob → ``disabled_biomarkers`` entries.
- First matching glob wins. Patterns use ``fnmatch`` semantics over the
- repo-relative POSIX path (``src/legacy/**.py``).
+ **Every** matching glob applies — the disabled sets union, so a path
+ matched by three rules is silenced for the union of their biomarkers
+ (severity remaps merge the same way, last matching rule winning per
+ biomarker). Patterns use **gitignore semantics** over the repo-relative
+ POSIX path (``src/legacy/**``), the same matching as ``exclude_patterns``
+ and ``.gitignore``, so one glob means one thing everywhere. Note that a
+ single ``*`` stops at a path segment: write ``src/legacy/**`` rather than
+ ``src/legacy/*`` to cover a whole subtree.
- Repo-wide and per-path ``severity_overrides``: remap a biomarker's
severity (typically a *demotion*, e.g. ``complex_method`` → ``low``) so a
team can soften a signal it considers advisory without disabling it
@@ -35,10 +41,11 @@ Schema (validated on load, errors logged but never raised):
from __future__ import annotations
-import fnmatch
import json
+import re
from dataclasses import dataclass, field
from pathlib import Path
+from typing import Any
import structlog
@@ -79,6 +86,22 @@ _PROFILES: dict[str, dict[str, Severity]] = {
}
+def _string_list(raw: object, *, field: str) -> list[str]:
+ """Parse a list-of-names field, dropping anything that is not one.
+
+ A string is deliberately rejected rather than iterated: ``"complex_method"``
+ is the natural thing to write instead of a one-element list, and iterating
+ it would silence biomarkers called ``c``, ``o``, ``m``… — a config that
+ looks like it worked.
+ """
+ if raw is None:
+ return []
+ if not isinstance(raw, list | tuple):
+ log.warning("health_rules_field_not_a_list", field=field, got=type(raw).__name__)
+ return []
+ return [str(item) for item in raw if isinstance(item, str)]
+
+
def _coerce_severity_map(raw: object) -> dict[str, Severity]:
"""Parse a ``{biomarker: "severity"}`` dict, dropping invalid entries."""
if not isinstance(raw, dict):
@@ -95,13 +118,101 @@ def _coerce_severity_map(raw: object) -> dict[str, Severity]:
return out
+#: A ``*`` that is not part of ``**``. Under the old ``fnmatch`` matching this
+#: crossed directory separators, so ``src/*`` also matched ``src/a/b.py``.
+#: Under gitignore matching it stops at one segment, which narrows any such
+#: rule — worth telling the user about rather than silently changing what
+#: their file means.
+_LONE_STAR = re.compile(r"(?<!\*)\*(?!\*)")
+
+
+def glob_narrowed_by_gitignore_semantics(pattern: str) -> bool:
+ """True if *pattern* covers less than it did under the old matching.
+
+ Split out from the logging call so the rule itself is testable.
+
+ Three things make a pattern safe:
+
+ * **No path separator.** ``*.generated.ts`` matches at any depth under
+ both engines.
+ * **A ``**`` earlier in the pattern.** Once ``**`` has taken care of the
+ directories, a later single ``*`` cannot narrow the match — which is
+ what makes the common ``**/*.spec.ts`` idiom fine.
+ * **A trailing ``*``.** ``src/legacy/*`` names the directory's entries,
+ and gitignore excludes everything under an excluded directory, so it
+ still covers the whole subtree. Both engines agree, and warning about
+ it told people to rewrite a rule that was never broken — the commonest
+ shape there is.
+
+ What does narrow is a lone ``*`` with pattern text after it: ``src/*.py``
+ stops matching ``src/a/b.py``, and ``src/*/x.py`` stops matching
+ ``src/a/b/x.py``.
+ """
+ if "/" not in pattern:
+ return False
+ head = pattern.split("**", 1)[0]
+ return any(match.end() != len(pattern) for match in _LONE_STAR.finditer(head))
+
+
+def _compile_glob(pattern: str) -> Any:
+ """Compile one path glob to a matcher, using gitignore semantics.
+
+ One engine for every glob a user writes — the same one the exclusion
+ rules and the traverser already use — so a pattern means the same thing
+ wherever it appears.
+
+ An unparseable pattern yields a matcher that matches nothing, rather than
+ raising. ``git`` itself accepts lines ``pathspec`` rejects (a trailing
+ backslash, say), and this file is hand-written: one stray rule must not
+ take down the whole config, which is documented as never raising.
+ """
+ import pathspec
+ from pathspec.patterns.gitwildmatch import (
+ GitWildMatchPattern,
+ GitWildMatchPatternError,
+ )
+
+ if pattern.startswith("!"):
+ # In a .gitignore a leading "!" re-includes something an earlier line
+ # excluded, so it only means anything relative to other lines. Each
+ # rule here compiles to its own single-pattern spec, so a negation
+ # matches nothing at all — the rule silently never applies. Say so.
+ log.warning(
+ "health_rules_negated_glob",
+ pattern=pattern,
+ hint=(
+ "a leading '!' has nothing to negate in a per-rule glob and "
+ "matches nothing — write the paths you do want instead"
+ ),
+ )
+ return pathspec.PathSpec([])
+
+ try:
+ return pathspec.PathSpec([GitWildMatchPattern(pattern)])
+ except GitWildMatchPatternError:
+ log.warning("health_rules_bad_glob", pattern=pattern)
+ return pathspec.PathSpec([])
+
+
@dataclass
class HealthRule:
- """One per-path override entry."""
+ """One per-path override entry.
+
+ ``matcher`` is compiled once at load and reused for every file, so a big
+ repo does not recompile the same pattern thousands of times.
+ """
path_glob: str
disabled_biomarkers: list[str] = field(default_factory=list)
severity_overrides: dict[str, Severity] = field(default_factory=dict)
+ matcher: Any = None
+
+ def __post_init__(self) -> None:
+ if self.matcher is None:
+ self.matcher = _compile_glob(self.path_glob)
+
+ def matches(self, path: str) -> bool:
+ return bool(self.matcher.match_file(path))
@dataclass
@@ -176,7 +287,7 @@ class HealthConfig:
enabled = block.get("enabled")
detectors = block.get("detectors")
disabled_raw = detectors.get("disabled") if isinstance(detectors, dict) else None
- disabled = [str(d) for d in disabled_raw or [] if isinstance(d, str)]
+ disabled = _string_list(disabled_raw, field="refactoring.detectors.disabled")
floor_raw = block.get("min_confidence")
floor = None
if isinstance(floor_raw, str) and floor_raw.strip().lower() in _CONFIDENCE_LEVELS:
@@ -210,11 +321,13 @@ class HealthConfig:
def from_dict(cls, raw: object) -> HealthConfig:
if not isinstance(raw, dict):
return cls()
- disabled: list[str] = [
- str(b) for b in (raw.get("disabled_biomarkers") or []) if isinstance(b, str)
- ]
+ disabled = _string_list(raw.get("disabled_biomarkers"), field="disabled_biomarkers")
rules: list[HealthRule] = []
- for entry in raw.get("rules") or []:
+ raw_rules = raw.get("rules")
+ if raw_rules is not None and not isinstance(raw_rules, list | tuple):
+ log.warning("health_rules_field_not_a_list", field="rules", got=type(raw_rules).__name__)
+ raw_rules = []
+ for entry in raw_rules or []:
if not isinstance(entry, dict):
continue
# ``path`` is canonical; ``path_glob`` and ``glob`` are accepted
@@ -223,9 +336,22 @@ class HealthConfig:
glob = entry.get("path") or entry.get("path_glob") or entry.get("glob")
if not isinstance(glob, str) or not glob:
continue
- disabled_for = [
- str(b) for b in (entry.get("disabled_biomarkers") or []) if isinstance(b, str)
- ]
+ disabled_for = _string_list(
+ entry.get("disabled_biomarkers"), field="rules[].disabled_biomarkers"
+ )
+ # A rule written against the old matching may now cover less than
+ # its author meant, which would quietly un-silence biomarkers they
+ # had turned off. Say so instead of letting them discover it in a
+ # health report.
+ if glob_narrowed_by_gitignore_semantics(glob):
+ log.warning(
+ "health_rules_glob_narrowed",
+ pattern=glob,
+ hint=(
+ "'*' no longer crosses '/' — use '**' to match a whole "
+ "subtree, e.g. 'src/legacy/**'"
+ ),
+ )
rules.append(
HealthRule(
path_glob=glob,
@@ -262,7 +388,7 @@ class HealthConfig:
norm = path.replace("\\", "/")
disabled: set[str] = set()
for rule in self.rules:
- if fnmatch.fnmatchcase(norm, rule.path_glob):
+ if rule.matches(norm):
disabled.update(rule.disabled_biomarkers)
if disabled:
out[path] = disabled
@@ -284,7 +410,7 @@ class HealthConfig:
norm = path.replace("\\", "/")
overrides: dict[str, Severity] = {}
for rule in rules_with_sev:
- if fnmatch.fnmatchcase(norm, rule.path_glob):
+ if rule.matches(norm):
overrides.update(rule.severity_overrides)
if overrides:
out[path] = overrides
diff --git a/packages/core/src/repowise/core/analysis/kg_curation.py b/packages/core/src/repowise/core/analysis/kg_curation.py
index 648a43329..d393ecf13 100644
--- a/packages/core/src/repowise/core/analysis/kg_curation.py
+++ b/packages/core/src/repowise/core/analysis/kg_curation.py
@@ -51,6 +51,7 @@ from repowise.core.generation.tour import (
select_hotspot_stop,
)
from repowise.core.generation.well_known_files import well_known_role
+from repowise.core.ids import is_external
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
# Closing-stop anchors (conftest, spec_helper, test_helper, …) and
@@ -120,7 +121,7 @@ def _graph_mode(dominant_lang: str, lang_by_path: dict[str, str], graph_builder:
for src, dst, data in graph_builder.graph().edges(data=True):
if (data or {}).get("edge_type") in ("imports", "tested_by") and src in dom_files:
edge_count += 1
- if isinstance(dst, str) and dst.startswith("external:"):
+ if isinstance(dst, str) and is_external(dst):
external_targets += 1
else:
internal_targets += 1
@@ -1072,7 +1073,7 @@ def _import_groups(
continue
# Stdlib/external imports say nothing about where a walk can
# go — only repo-internal relationships count.
- if src.startswith("external:") or dst.startswith("external:"):
+ if is_external(src) or is_external(dst):
continue
names = tuple(sorted(data.get("imported_names") or ())) or (dst,)
keyed[(src, names)].append(dst)
@@ -1863,7 +1864,8 @@ def build_portable_kg(kg: KnowledgeGraphResult) -> tuple[dict, KGValidation]:
data = kg.to_dict()
validation = validate_kg(kg)
data["meta"] = {
- "schema_version": data.get("version", "1.0.0"),
+ # The integer the loader gates on, not the "1.0.0" display label.
+ "schema_version": data.get("schema_version", 1),
"generator": "repowise-kg-curation",
"fingerprint": getattr(kg, "fingerprint", ""),
"file_count": validation.metrics.get("file_count", 0),
diff --git a/packages/core/src/repowise/core/analysis/knowledge_graph.py b/packages/core/src/repowise/core/analysis/knowledge_graph.py
index d3815bd71..472b254c3 100644
--- a/packages/core/src/repowise/core/analysis/knowledge_graph.py
+++ b/packages/core/src/repowise/core/analysis/knowledge_graph.py
@@ -10,11 +10,24 @@ from __future__ import annotations
import hashlib
import json
+import logging
import re
from dataclasses import dataclass, field
from pathlib import Path, PurePosixPath
from typing import Any
+_log = logging.getLogger(__name__)
+
+#: Schema version of the ``knowledge-graph.json`` artifact. Bump whenever a
+#: change makes an older file unsafe to load — readers reject anything below
+#: this and callers rebuild from scratch, which is cheaper and safer than
+#: migrating a file the user may have hand-edited. Files written before the
+#: field existed read as 1, matching the shape they actually have.
+#:
+#: Kept separate from the ``"version": "1.0.0"`` string, which is a
+#: human-facing label consumers already read and must not change meaning.
+_KG_SCHEMA_VERSION = 1
+
@dataclass
class KnowledgeGraphResult:
@@ -60,6 +73,7 @@ class KnowledgeGraphResult:
layers = [_canonical_layer(layer) for layer in self.layers]
out = {
"version": "1.0.0",
+ "schema_version": _KG_SCHEMA_VERSION,
"project": self.project,
"nodes": nodes,
"edges": edges,
@@ -76,10 +90,46 @@ class KnowledgeGraphResult:
@classmethod
def from_file(cls, path: Path) -> KnowledgeGraphResult | None:
- """Load a previously-persisted KG from JSON, or None on failure."""
+ """Load a previously-persisted KG from JSON, or None on failure.
+
+ ``None`` also covers an artifact written by an older schema: callers
+ treat it as absent and rebuild, so a stale file can never be read as
+ if it had the current shape.
+
+ A version *above* the current one is deliberately accepted. The gate
+ protects a new reader from an old file, which is the direction that
+ actually happens on upgrade; refusing to read a newer file would only
+ help a downgrade, and would strand the user on a rebuild loop until
+ they deleted the artifact by hand.
+
+ Never raises: this runs inside an index, and a hand-edited file must
+ cost a rebuild rather than the whole run.
+ """
try:
data = json.loads(path.read_text(encoding="utf-8"))
- except (json.JSONDecodeError, OSError):
+ except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+ _log.warning("knowledge-graph.json at %s is unreadable", path, exc_info=True)
+ return None
+ if not isinstance(data, dict):
+ # ``[]``, ``"x"`` and ``5`` are all valid JSON and all reachable
+ # from a hand edit; reading on would raise AttributeError out of
+ # an index run.
+ _log.warning(
+ "Ignoring knowledge-graph.json at %s (expected an object, found %s); rebuilding",
+ path,
+ type(data).__name__,
+ )
+ return None
+ found = data.get("schema_version", 1)
+ # ``bool`` is an ``int`` in Python, and ``True < 1`` is False, so a
+ # version of ``true`` would otherwise sail through the gate.
+ if not isinstance(found, int) or isinstance(found, bool) or found < _KG_SCHEMA_VERSION:
+ _log.info(
+ "Ignoring knowledge-graph.json at %s (schema_version %s < %s); rebuilding",
+ path,
+ found,
+ _KG_SCHEMA_VERSION,
+ )
return None
return cls(
project=data.get("project", {}),
diff --git a/packages/core/src/repowise/core/generation/context/assembler.py b/packages/core/src/repowise/core/generation/context/assembler.py
index 1f71bb25a..2c4552423 100644
--- a/packages/core/src/repowise/core/generation/context/assembler.py
+++ b/packages/core/src/repowise/core/generation/context/assembler.py
@@ -7,6 +7,7 @@ from typing import Any
import structlog
+from repowise.core.ids import file_path_of, is_external
from repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbol
from ..categories import file_category
@@ -44,9 +45,9 @@ def _is_foreign_edge(node: str, path: str) -> bool:
spellings of "this file" are dropped so a dependency list only ever names
other files.
"""
- if node.startswith("external:"):
+ if is_external(node):
return False
- return node != path and node.split("::", 1)[0] != path
+ return node != path and file_path_of(node) != path
# Maximum imports to include before truncating
@@ -265,7 +266,7 @@ class ContextAssembler:
path = parsed.file_info.path
# Callers = files that import the containing file (in-edges)
if path in graph:
- callers = [e for e in graph.predecessors(path) if not e.startswith("external:")]
+ callers = [e for e in graph.predecessors(path) if not is_external(e)]
else:
callers = []
@@ -578,7 +579,7 @@ class ContextAssembler:
top_files = [
_TopFile(path=p, score=s)
for p, s in sorted_pr[:_MAX_TOP_FILES]
- if not p.startswith("external:")
+ if not is_external(p)
]
# SCCs with len > 1 are true circular deps
@@ -661,7 +662,7 @@ class ContextAssembler:
for p, _ in sorted(pagerank.items(), key=lambda x: (-x[1], str(x[0])))[
:max_diagram_nodes
]
- if not str(p).startswith("external:")
+ if not is_external(str(p))
)
nodes = sorted(top_nodes)
@@ -682,7 +683,7 @@ class ContextAssembler:
# Community → members mapping (top-10 communities, cap members to 5)
raw_communities: dict[int, list[str]] = {}
for path, cid in community.items():
- if not path.startswith("external:"):
+ if not is_external(path):
raw_communities.setdefault(cid, []).append(path)
comm_sorted = sorted(
((cid, sorted(members)) for cid, members in raw_communities.items()),
diff --git a/packages/core/src/repowise/core/generation/kg_context.py b/packages/core/src/repowise/core/generation/kg_context.py
index b546cdec8..369384225 100644
--- a/packages/core/src/repowise/core/generation/kg_context.py
+++ b/packages/core/src/repowise/core/generation/kg_context.py
@@ -14,6 +14,8 @@ from pathlib import Path
import structlog
+from repowise.core.ids import file_path_of
+
logger = structlog.get_logger(__name__)
@@ -222,7 +224,7 @@ class KnowledgeGraphContext:
for node_id in layer_node_ids:
for e in self._edges_by_source.get(node_id, []):
if e.get("type") == "imports" and e["target"] not in layer_node_ids:
- target_path = e["target"].removeprefix("file:")
+ target_path = file_path_of(e["target"]) or e["target"]
target_layer = self._file_to_layer.get(target_path, {})
if target_layer:
name = target_layer.get("name", "Unknown")
@@ -230,7 +232,7 @@ class KnowledgeGraphContext:
for e in self._edges_by_target.get(node_id, []):
if e.get("type") == "imports" and e["source"] not in layer_node_ids:
- source_path = e["source"].removeprefix("file:")
+ source_path = file_path_of(e["source"]) or e["source"]
source_layer = self._file_to_layer.get(source_path, {})
if source_layer:
name = source_layer.get("name", "Unknown")
diff --git a/packages/core/src/repowise/core/generation/kg_reviewer/checks.py b/packages/core/src/repowise/core/generation/kg_reviewer/checks.py
index e5afb744e..23dae9d67 100644
--- a/packages/core/src/repowise/core/generation/kg_reviewer/checks.py
+++ b/packages/core/src/repowise/core/generation/kg_reviewer/checks.py
@@ -18,6 +18,8 @@ import re
from collections import Counter, defaultdict
from pathlib import PurePosixPath
+from repowise.core.ids import file_path_of
+
from .findings import Finding, Severity
# Structural / type words that carry no information beyond the file's name and
@@ -58,7 +60,7 @@ def _is_file_node(node: dict) -> bool:
def _node_path(node: dict) -> str:
- return node.get("filePath") or node.get("id", "").removeprefix("file:")
+ return node.get("filePath") or file_path_of(node.get("id", "")) or ""
def _words(text: str) -> list[str]:
diff --git a/packages/core/src/repowise/core/generation/knowledge_graph.py b/packages/core/src/repowise/core/generation/knowledge_graph.py
index 27d6a0f77..e6710b722 100644
--- a/packages/core/src/repowise/core/generation/knowledge_graph.py
+++ b/packages/core/src/repowise/core/generation/knowledge_graph.py
@@ -14,6 +14,8 @@ from typing import Any
import structlog
+from repowise.core.ids import file_path_of, kg_file_path_of
+
logger = structlog.get_logger(__name__)
@@ -185,7 +187,7 @@ async def _enrich_layers(
batch_context = []
for layer in batch:
node_ids = layer.get("nodeIds", [])
- file_paths = [nid.removeprefix("file:") for nid in node_ids if nid.startswith("file:")]
+ file_paths = [p for p in (kg_file_path_of(nid) for nid in node_ids) if p]
top_files = sorted(file_paths, key=lambda p: pagerank.get(p, 0.0), reverse=True)[:20]
batch_context.append({
@@ -286,7 +288,7 @@ async def _generate_tour(
layer_summaries = []
for layer in layers:
node_ids = layer.get("nodeIds", [])
- file_paths = [nid.removeprefix("file:") for nid in node_ids if nid.startswith("file:")]
+ file_paths = [p for p in (kg_file_path_of(nid) for nid in node_ids) if p]
top_in_layer = sorted(file_paths, key=lambda p: pagerank.get(p, 0.0), reverse=True)[:5]
layer_summaries.append({
"name": layer["name"],
@@ -395,7 +397,7 @@ def build_deterministic_tour(
for layer in sorted_layers[:10]:
node_ids = layer.get("nodeIds", [])
- file_paths = [nid.removeprefix("file:") for nid in node_ids if nid.startswith("file:")]
+ file_paths = [p for p in (kg_file_path_of(nid) for nid in node_ids) if p]
top_file = max(
(f for f in file_paths if f not in used_files),
key=lambda p: pagerank.get(p, 0.0),
@@ -435,7 +437,7 @@ def _backfill_summaries(kg_result: Any, generated_pages: list[Any]) -> None:
# *after* this backfill so it never blocks a real page summary.
if not str(node.get("id", "")).startswith("file:"):
continue
- path = node.get("filePath", node["id"].removeprefix("file:"))
+ path = node.get("filePath") or file_path_of(node["id"]) or node["id"]
if path in page_summaries and not node.get("summary"):
node["summary"] = page_summaries[path]
diff --git a/packages/core/src/repowise/core/generation/layers.py b/packages/core/src/repowise/core/generation/layers.py
index f36fe907a..30af5afcd 100644
--- a/packages/core/src/repowise/core/generation/layers.py
+++ b/packages/core/src/repowise/core/generation/layers.py
@@ -25,6 +25,7 @@ from collections import defaultdict
from collections.abc import Iterable, Mapping
from pathlib import PurePosixPath
+from repowise.core.ids import is_external
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
from repowise.core.test_paths import is_test_related_path
@@ -297,7 +298,7 @@ def layer_order_basis(
order — no edge supports it.
"""
for src, dst in import_edges:
- if src.startswith("external:") or dst.startswith("external:"):
+ if is_external(src) or is_external(dst):
continue
ls = file_layers.get(src)
ld = file_layers.get(dst)
@@ -346,7 +347,7 @@ def compute_layer_order(
out_deg: dict[str, int] = defaultdict(int) # edges leaving the layer
in_deg: dict[str, int] = defaultdict(int) # edges entering the layer
for src, dst in import_edges:
- if src.startswith("external:") or dst.startswith("external:"):
+ if is_external(src) or is_external(dst):
continue
ls = file_layers.get(src)
ld = file_layers.get(dst)
diff --git a/packages/core/src/repowise/core/generation/mermaid_safety.py b/packages/core/src/repowise/core/generation/mermaid_safety.py
index 392190a0a..bb8905f5d 100644
--- a/packages/core/src/repowise/core/generation/mermaid_safety.py
+++ b/packages/core/src/repowise/core/generation/mermaid_safety.py
@@ -20,6 +20,7 @@ Pure string work, no LLM call — cheap enough to run on every page.
from __future__ import annotations
+import hashlib
import re
import structlog
@@ -64,6 +65,20 @@ _PATHY_TOKEN_RE = re.compile(
# Label characters that force quoting.
_LABEL_NEEDS_QUOTE_RE = re.compile(r"[()\[\]{}\"<>|/]")
+# A comment or a directive. ``%%`` opens a comment for the rest of the line,
+# and ``%%{...}%%`` is a configuration directive — neither is diagram syntax,
+# and the ``{`` in a directive would otherwise read as a rhombus label.
+_DIRECTIVE_OR_COMMENT_RE = re.compile(r"^\s*%%")
+
+# The text between a pair of pipes on an edge (``A -->|yes/no| B``). It is a
+# label like any other, but it is never bracketed, so both passes below have
+# to be told to leave it alone.
+_PIPE_LABEL_RE = re.compile(r"\|[^|\n]*\|")
+
+# An identifier that mermaid already accepts as-is. Used to reserve names so a
+# slug can never land on a node that is already in the diagram.
+_BARE_ID_RE = re.compile(r"(?<![\w./\\])([A-Za-z_][A-Za-z0-9_]*)(?![\w./\\])")
+
def _slug(raw: str) -> str:
"""Turn an illegal node ID into a clean ``[A-Za-z0-9_]`` slug."""
@@ -76,30 +91,145 @@ def _slug(raw: str) -> str:
return s
+def _split_on_quotes(text: str) -> list[tuple[str, bool]]:
+ """Split *text* into ``(segment, is_quoted)`` runs on double quotes.
+
+ The scanner's "string mode": once a label has been quoted, its contents
+ are prose, and a path inside it must not be treated as a node ID. An
+ unterminated quote makes the rest of the line a string, which is what the
+ mermaid parser does too.
+ """
+ segments: list[tuple[str, bool]] = []
+ buffer: list[str] = []
+ quoted = False
+ for char in text:
+ if char == '"':
+ buffer.append(char)
+ if quoted:
+ segments.append(("".join(buffer), True))
+ buffer = []
+ quoted = False
+ else:
+ # The quote opens a string: flush what came before it, minus
+ # the quote itself, then start the quoted run with it.
+ opening = "".join(buffer[:-1])
+ if opening:
+ segments.append((opening, False))
+ buffer = [char]
+ quoted = True
+ continue
+ buffer.append(char)
+ if buffer:
+ segments.append(("".join(buffer), quoted))
+ return segments
+
+
+def _protected_runs(line: str) -> list[tuple[str, bool]]:
+ """Split *line* into ``(segment, is_protected)`` runs.
+
+ Protected means "this is label text, not diagram syntax": a quoted string,
+ or the text between a pair of pipes on an edge. Neither may be slugged —
+ ``A -->|read/write| B`` is an ordinary edge label, and rewriting it to
+ ``read_write`` corrupts a diagram that rendered perfectly well.
+ """
+ runs: list[tuple[str, bool]] = []
+ for segment, is_quoted in _split_on_quotes(line):
+ if is_quoted:
+ runs.append((segment, True))
+ continue
+ pos = 0
+ for match in _PIPE_LABEL_RE.finditer(segment):
+ if match.start() > pos:
+ runs.append((segment[pos : match.start()], False))
+ runs.append((match.group(0), True))
+ pos = match.end()
+ if pos < len(segment):
+ runs.append((segment[pos:], False))
+ return runs
+
+
+def _is_skippable(line: str) -> bool:
+ """True for a line that carries no diagram syntax at all."""
+ return bool(_DIRECTIVE_OR_COMMENT_RE.match(line))
+
+
+def _disambiguator(raw: str) -> str:
+ """A short suffix derived from the id, for slugs that collide.
+
+ Deliberately not a counter: numbering by order of appearance means adding
+ one unrelated node renames every colliding node after it, so a
+ regenerated diagram churns for no reason.
+ """
+ return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:6]
+
+
def _build_id_map(body: str) -> dict[str, str]:
- """Map every illegal (path/dotted) node ID in *body* to a unique slug."""
+ """Map every illegal (path/dotted) node ID in *body* to a unique slug.
+
+ Only unprotected text is considered — a path inside a label is prose, and
+ rewriting it there is what used to turn a readable ``A["src/main.py"]``
+ into ``A["src_main_py"]``.
+ """
raw_ids: list[str] = []
seen: set[str] = set()
- for m in _PATHY_TOKEN_RE.finditer(body):
- raw = m.group(1)
- if raw not in seen:
- seen.add(raw)
- raw_ids.append(raw)
+ # Identifiers that were already legal. A slug landing on one of these would
+ # merge two distinct nodes into a single box, so they reserve their name
+ # even though they need no rewriting themselves.
+ already_legal: set[str] = set()
+ for line in body.split("\n"):
+ if _is_skippable(line):
+ continue
+ for segment, is_protected in _protected_runs(line):
+ if is_protected:
+ continue
+ for match in _PATHY_TOKEN_RE.finditer(segment):
+ raw = match.group(1)
+ if raw not in seen:
+ seen.add(raw)
+ raw_ids.append(raw)
+ already_legal.update(_BARE_ID_RE.findall(segment))
+
+ by_slug: dict[str, list[str]] = {}
+ for raw in raw_ids:
+ by_slug.setdefault(_slug(raw), []).append(raw)
id_map: dict[str, str] = {}
- used: set[str] = set()
- for raw in raw_ids:
- slug = _slug(raw)
- base = slug
- i = 2
- while slug in used:
- slug = f"{base}_{i}"
- i += 1
- used.add(slug)
- id_map[raw] = slug
+ for slug, owners in by_slug.items():
+ if len(owners) == 1 and slug not in already_legal:
+ id_map[owners[0]] = slug
+ continue
+ # Every owner is suffixed, not just the ones after the first: which id
+ # keeps the bare slug would otherwise depend on document order.
+ for raw in owners:
+ id_map[raw] = f"{slug}_{_disambiguator(raw)}"
return id_map
+def _find_closer(text: str, start: int, opener: str, closer: str) -> int:
+ """Index of the closer matching the opener at *start*, or -1.
+
+ Counts nesting rather than taking the first closer, so a label that
+ contains the same bracket — ``A[run(x[0])]`` — ends where it really ends
+ instead of in the middle.
+ """
+ depth = 1
+ i = start + len(opener)
+ n = len(text)
+ while i < n:
+ if text.startswith(closer, i):
+ depth -= 1
+ if depth == 0:
+ return i
+ i += len(closer)
+ continue
+ if text.startswith(opener, i):
+ depth += 1
+ i += len(opener)
+ continue
+ i += 1
+ return -1
+
+
def _quote_labels(body: str) -> str:
"""Wrap shape labels containing special characters in double quotes."""
@@ -111,7 +241,7 @@ def _quote_labels(body: str) -> str:
matched = False
for opener, closer in _SHAPE_PAIRS:
if text.startswith(opener, i):
- end = text.find(closer, i + len(opener))
+ end = _find_closer(text, i, opener, closer)
if end == -1:
continue
label = text[i + len(opener) : end]
@@ -138,22 +268,52 @@ def _quote_labels(body: str) -> str:
i += 1
return "".join(out)
- return "\n".join(_process(line) for line in body.split("\n"))
+ return "\n".join(
+ line if _is_skippable(line) else _process(line) for line in body.split("\n")
+ )
+
+
+def _rewrite_ids(body: str, id_map: dict[str, str]) -> str:
+ """Replace illegal node IDs with their slugs, outside label text only."""
+ if not id_map:
+ return body
+ patterns = [
+ (
+ re.compile(
+ r"(?<![" + _RAW_ID_CHARS + r"])"
+ + re.escape(raw)
+ + r"(?![" + _RAW_ID_CHARS + r"])"
+ ),
+ slug,
+ )
+ for raw, slug in id_map.items()
+ ]
+
+ out_lines: list[str] = []
+ for line in body.split("\n"):
+ if _is_skippable(line):
+ out_lines.append(line)
+ continue
+ pieces: list[str] = []
+ for segment, is_protected in _protected_runs(line):
+ if not is_protected:
+ for pattern, slug in patterns:
+ segment = pattern.sub(slug, segment)
+ pieces.append(segment)
+ out_lines.append("".join(pieces))
+ return "\n".join(out_lines)
def _rewrite_graph_block(body: str) -> str:
- """Slug illegal node IDs and quote risky labels in a graph/flowchart body."""
- id_map = _build_id_map(body)
- rewritten = body
- for raw, slug in id_map.items():
- # Replace the raw token only when it is a standalone node ID, i.e. not
- # part of a longer path/word. Guards keep ``foo`` inside ``foobar/x``
- # from matching.
- pattern = re.compile(
- r"(?<![" + _RAW_ID_CHARS + r"])" + re.escape(raw) + r"(?![" + _RAW_ID_CHARS + r"])"
- )
- rewritten = pattern.sub(slug, rewritten)
- return _quote_labels(rewritten)
+ """Quote risky labels, then slug illegal node IDs outside those labels.
+
+ Order matters. Rewriting IDs first meant a path inside a label was still
+ bare text, so it was slugged too and ``A[src/main.py]`` came out as
+ ``A[src_main_py]`` — a legal diagram with an unreadable label. Quoting
+ first turns the label into a string the ID pass then skips.
+ """
+ quoted = _quote_labels(body)
+ return _rewrite_ids(quoted, _build_id_map(quoted))
def sanitize_mermaid(markdown: str) -> str:
diff --git a/packages/core/src/repowise/core/generation/page_generator/levels.py b/packages/core/src/repowise/core/generation/page_generator/levels.py
index e6f94ab79..4e74e0ba5 100644
--- a/packages/core/src/repowise/core/generation/page_generator/levels.py
+++ b/packages/core/src/repowise/core/generation/page_generator/levels.py
@@ -13,6 +13,8 @@ from typing import TYPE_CHECKING, Any
import structlog
+from repowise.core.ids import is_external
+
from ...analysis.knowledge_graph import _slugify
from .. import onboarding as _onboarding
from ..context_assembler import FilePageContext
@@ -113,7 +115,7 @@ async def _prefetch_dependency_summaries(run: _GenerationRun) -> None:
if path_ not in run.graph:
continue
for dep in run.graph.successors(path_):
- if dep.startswith("external:"):
+ if is_external(dep):
continue
if dep in run.completed_page_summaries:
continue
diff --git a/packages/core/src/repowise/core/generation/tour.py b/packages/core/src/repowise/core/generation/tour.py
index bf1ca95dc..df1dacfc0 100644
--- a/packages/core/src/repowise/core/generation/tour.py
+++ b/packages/core/src/repowise/core/generation/tour.py
@@ -37,6 +37,7 @@ from typing import Any
from repowise.core.generation.entry_points import is_glue_leaf
from repowise.core.generation.layers import ADJACENT_LAYERS, infer_layer, is_support_path
+from repowise.core.ids import is_external
from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRY
# Filenames that conventionally mark an executable / wiring entry point.
@@ -255,7 +256,7 @@ def build_tour(
adjacency: dict[str, list[str]] = defaultdict(list)
fan_in: dict[str, int] = defaultdict(int)
for src, dst in import_edges:
- if src.startswith("external:") or dst.startswith("external:"):
+ if is_external(src) or is_external(dst):
continue
adjacency[src].append(dst)
fan_in[dst] += 1
diff --git a/packages/core/src/repowise/core/ids.py b/packages/core/src/repowise/core/ids.py
new file mode 100644
index 000000000..36f056d60
--- /dev/null
+++ b/packages/core/src/repowise/core/ids.py
@@ -0,0 +1,293 @@
+"""Typed identifiers for graph and architecture nodes.
+
+Every layer of this codebase writes node ids as strings with a short prefix
+(``file:``, ``external:``, ``pkg:``, ``cmp:``…) and then takes them apart again
+with hand-written ``split``/``startswith``/``removeprefix`` calls. That works
+until two separators meet: a component id built as ``cmp:<path>::root`` puts a
+``::`` — which everywhere else means "symbol inside a file" — inside a
+``:``-prefixed id, and every reader that splits on ``::`` first gets it wrong.
+
+This module is the one place that knows the spelling. :func:`parse` turns a
+raw id into a typed value, :func:`render` turns it back, and the two are exact
+inverses. Two rules keep them that way:
+
+* **The prefix is matched against a fixed table, and it is matched first.** An
+ unknown prefix is not a kind — ``C:\\src\\main.py`` is a Windows path, not a
+ ``C`` node — so anything unrecognised parses as a file.
+* **``::`` separates a file from a symbol, but only in an id with no prefix.**
+ Inside a prefixed id it is ordinary data: Rust import resolution really emits
+ ``external:serde::Deserialize``. :func:`render` raises only for the two
+ unprefixed forms, where a separator genuinely has no unambiguous spelling.
+
+Pure and dependency-free: no database, no filesystem, no imports from the rest
+of the package, so it is safe to use from ingestion, the server and the CLI
+alike.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+#: Separator between a file path and a symbol name. Reserved: no other id
+#: kind may contain it.
+SYMBOL_SEP = "::"
+
+#: Separator between a component path and its synthetic root-bucket marker.
+#: Deliberately not ``::`` — the old ``cmp:<path>::root`` spelling collided
+#: with the symbol separator, so any reader splitting on ``::`` first saw a
+#: file called ``cmp:<path>`` with a symbol called ``root``.
+#:
+#: Reserved at the end of a component path, the same way ``::`` is reserved.
+#: Note ``#`` also delimits a URL fragment: an id put in a URL unencoded
+#: truncates here. Nothing does that today.
+_ROOT_MARKER = "#root"
+
+
+@dataclass(frozen=True)
+class FileId:
+ """A source file, keyed on its repo-relative POSIX path."""
+
+ path: str
+
+
+@dataclass(frozen=True)
+class KgFileId:
+ """A file as spelled in the knowledge-graph artifact (``file:a.py``).
+
+ The artifact prefixes file ids; the dependency graph does not. Keeping
+ them as two types means a conversion between the two surfaces has to be
+ written out, instead of a prefix silently appearing or vanishing.
+ """
+
+ path: str
+
+
+@dataclass(frozen=True)
+class SymbolId:
+ """A named symbol inside a file (``path::Name``)."""
+
+ path: str
+ name: str
+
+
+@dataclass(frozen=True)
+class ExternalId:
+ """A third-party or unresolvable import (``external:react``).
+
+ ``name`` may itself contain colons — ``external:pub:http`` is a real Dart
+ id — so only the first colon separates the prefix.
+ """
+
+ name: str
+
+
+@dataclass(frozen=True)
+class FrameworkId:
+ """A synthetic node standing in for a framework's own code.
+
+ Distinct from :class:`ExternalId` because it is generated by the framework
+ edge passes rather than resolved from an import, and because the checks
+ that special-case third-party code have historically looked for
+ ``external:`` only and missed these entirely.
+ """
+
+ name: str
+
+
+@dataclass(frozen=True)
+class SystemId:
+ """The C4 software system standing for the repository itself."""
+
+ repo: str
+
+
+@dataclass(frozen=True)
+class PersonId:
+ """A C4 actor, keyed on the kind of user it represents."""
+
+ kind: str
+
+
+@dataclass(frozen=True)
+class ContainerId:
+ """A C4 container — a workspace package or top-level directory."""
+
+ path: str
+
+
+@dataclass(frozen=True)
+class ComponentId:
+ """A C4 component — a directory inside a container.
+
+ ``is_root_bucket`` marks the synthetic group holding files that sit at the
+ container root. It is a field rather than a suffix glued onto ``path`` so
+ the root bucket and the container share one path and nothing has to parse
+ a marker back out of the string.
+ """
+
+ path: str
+ is_root_bucket: bool = False
+
+
+@dataclass(frozen=True)
+class ExternalSystemId:
+ """An external dependency as shown in a C4 view (``ext:react``).
+
+ Separate from :class:`ExternalId`: that one names a node in the dependency
+ graph, this one names a box in a diagram, and several graph nodes collapse
+ into one box.
+ """
+
+ name: str
+
+
+NodeId = (
+ FileId
+ | KgFileId
+ | SymbolId
+ | ExternalId
+ | FrameworkId
+ | SystemId
+ | PersonId
+ | ContainerId
+ | ComponentId
+ | ExternalSystemId
+)
+
+#: Prefix → constructor. Order does not matter: a raw id is split on its first
+#: colon and the head looked up here, so no prefix can shadow another.
+_BY_PREFIX: dict[str, type] = {
+ "file": KgFileId,
+ "external": ExternalId,
+ "framework": FrameworkId,
+ "sys": SystemId,
+ "person": PersonId,
+ "pkg": ContainerId,
+ "cmp": ComponentId,
+ "ext": ExternalSystemId,
+}
+
+_PREFIX_BY_TYPE: dict[type, str] = {v: k for k, v in _BY_PREFIX.items()}
+
+
+class InvalidNodeIdError(ValueError):
+ """Raised when a value cannot be rendered as an unambiguous id."""
+
+
+def _reject_separator(kind: str, value: str) -> None:
+ if SYMBOL_SEP in value:
+ raise InvalidNodeIdError(
+ f"{kind} contains the reserved symbol separator {SYMBOL_SEP!r}: {value!r}. "
+ f"Only a symbol id may contain it."
+ )
+
+
+def render(node: NodeId) -> str:
+ """Render a typed id back to its string form.
+
+ Raises :class:`InvalidNodeIdError` rather than emitting a string that would
+ parse back as a different kind — a file genuinely named ``a::b.py`` is
+ legal on disk and has no unambiguous spelling here, and silently
+ mis-parsing it later is worse than failing now.
+
+ Only the *unprefixed* forms can hit that. A prefixed id is read prefix-first
+ (see :func:`parse`), so a separator inside one is just part of the value and
+ survives the round trip untouched.
+ """
+ if isinstance(node, SymbolId):
+ # Only the path is at risk: ``parse`` splits on the FIRST separator, so
+ # the name keeps any further ones. Rust and C++ symbol names need that.
+ _reject_separator("symbol path", node.path)
+ return f"{node.path}{SYMBOL_SEP}{node.name}"
+
+ if isinstance(node, FileId):
+ _reject_separator("file path", node.path)
+ return node.path
+
+ if isinstance(node, ComponentId):
+ if node.path.endswith(_ROOT_MARKER):
+ # ``cmp:packages/foo#root`` already spells the root bucket of
+ # ``packages/foo``, so a directory genuinely named ``foo#root``
+ # has no distinct spelling. Same trap as the symbol separator,
+ # same answer: fail here rather than mis-parse later.
+ raise InvalidNodeIdError(
+ f"component path ends in the reserved root marker {_ROOT_MARKER!r}: "
+ f"{node.path!r}"
+ )
+ marker = _ROOT_MARKER if node.is_root_bucket else ""
+ return f"cmp:{node.path}{marker}"
+
+ prefix = _PREFIX_BY_TYPE.get(type(node))
+ if prefix is None:
+ raise InvalidNodeIdError(f"not a node id: {node!r}")
+ # Every remaining variant carries exactly one string field.
+ (value,) = vars(node).values()
+ return f"{prefix}:{value}"
+
+
+def parse(raw: str) -> NodeId:
+ """Parse a raw node id.
+
+ Anything without a known prefix is a file path, which is what an
+ unprefixed graph node id means and what keeps Windows paths
+ (``C:\\src\\main.py``) from being read as a ``C`` node.
+
+ The prefix is looked up **before** the symbol separator is considered.
+ Testing the separator first made ``external:serde::Deserialize`` — the
+ shape Rust import resolution emits for every crate — read as a symbol
+ inside a file called ``external:serde``, so every check asking "is this
+ third-party code?" answered no and the crate was treated as one of the
+ repository's own files.
+ """
+ prefix, sep, rest = raw.partition(":")
+ ctor = _BY_PREFIX.get(prefix) if sep else None
+ if ctor is not None:
+ if ctor is ComponentId:
+ if rest.endswith(_ROOT_MARKER):
+ return ComponentId(path=rest[: -len(_ROOT_MARKER)], is_root_bucket=True)
+ return ComponentId(path=rest)
+ return ctor(rest) # type: ignore[call-arg]
+
+ if SYMBOL_SEP in raw:
+ path, _, name = raw.partition(SYMBOL_SEP)
+ return SymbolId(path=path, name=name)
+ return FileId(path=raw)
+
+
+def is_external(raw: str) -> bool:
+ """True if *raw* names code we do not own.
+
+ Covers both ``external:`` and ``framework:``. Written once because the
+ hand-rolled checks scattered around the tree test for ``external:`` alone
+ and so miss every framework node.
+ """
+ return isinstance(parse(raw), ExternalId | FrameworkId)
+
+
+def kg_file_path_of(raw: str) -> str | None:
+ """The path of a knowledge-graph file id (``file:a.py``), or ``None``.
+
+ Stricter than :func:`file_path_of`, and deliberately so. The KG artifact
+ spells every file id with the ``file:`` prefix, and its layers and tour
+ steps can also hold ``module:``, ``layer:`` and ``dir:`` ids. Those
+ prefixes are not in the table here, so they parse as bare paths — which
+ means the permissive helper hands them back as if they named files, and
+ they go on to be looked up in PageRank and named in a prompt.
+
+ Use this wherever the old code spelled the rule as
+ ``if nid.startswith("file:")``.
+ """
+ node = parse(raw)
+ return node.path if isinstance(node, KgFileId) else None
+
+
+def file_path_of(raw: str) -> str | None:
+ """The file path *raw* refers to, or ``None`` if it names no file.
+
+ A symbol resolves to the file that holds it; a file resolves to itself;
+ everything else is not a file.
+ """
+ node = parse(raw)
+ if isinstance(node, FileId | KgFileId | SymbolId):
+ return node.path
+ return None
diff --git a/packages/core/src/repowise/core/ingestion/graph/__init__.py b/packages/core/src/repowise/core/ingestion/graph/__init__.py
index 93bbfea1b..ab1c12bee 100644
--- a/packages/core/src/repowise/core/ingestion/graph/__init__.py
+++ b/packages/core/src/repowise/core/ingestion/graph/__init__.py
@@ -28,7 +28,7 @@ Internal layout (kept under the 400-line ceiling):
_metrics.py — centrality / community / degree metrics (+ SQL routing)
_resolvers.py — heritage / member-read / call resolution passes
_edges.py — co-change / dynamic / framework edges
- _serialize.py — node-link JSON + SQLite export
+ _serialize.py — node-link JSON export
_rehydrate.py — rebuild a builder from persisted nodes/edges/metrics
_stem.py — import-stem resolution helpers
"""
diff --git a/packages/core/src/repowise/core/ingestion/graph/_serialize.py b/packages/core/src/repowise/core/ingestion/graph/_serialize.py
index 2f2724470..ff663f3e5 100644
--- a/packages/core/src/repowise/core/ingestion/graph/_serialize.py
+++ b/packages/core/src/repowise/core/ingestion/graph/_serialize.py
@@ -1,15 +1,12 @@
-"""Graph serialisation: node-link JSON + standalone SQLite persistence.
+"""Graph serialisation: node-link JSON.
-Mixed into :class:`GraphBuilder`. The SQLite ``persist`` path is the
-self-contained writer used by the standalone graph export; the main pipeline
-persists through ``persistence.crud`` instead.
+Mixed into :class:`GraphBuilder`. The main pipeline persists through
+``persistence.crud``; this module only produces the in-memory node-link dict
+that callers dump to an artifact.
"""
from __future__ import annotations
-import contextlib
-import json
-from pathlib import Path
from typing import Any
import networkx as nx
@@ -19,90 +16,8 @@ log = structlog.get_logger(__name__)
class SerializeMixin:
- """JSON + SQLite serialisation for :class:`GraphBuilder`."""
+ """JSON serialisation for :class:`GraphBuilder`."""
def to_json(self) -> dict[str, Any]:
"""Serialize the graph to a JSON-compatible dict (node-link format)."""
return nx.node_link_data(self.graph())
-
- async def persist(self, db_path: Path, repo_id: str) -> None:
- """Persist the graph to an SQLite database."""
- import sqlite3
-
- import aiosqlite
-
- pr = self.pagerank()
- bc = self.betweenness_centrality()
- scc_map = self._build_scc_map()
- cd = self.community_detection()
- g = self.graph()
-
- async with aiosqlite.connect(db_path) as db:
- await db.executescript("""
- CREATE TABLE IF NOT EXISTS graph_nodes (
- repo_id TEXT NOT NULL,
- path TEXT NOT NULL,
- language TEXT,
- symbol_count INTEGER,
- has_error INTEGER,
- pagerank REAL,
- betweenness REAL,
- scc_id INTEGER,
- community_id INTEGER DEFAULT 0,
- PRIMARY KEY (repo_id, path)
- );
- CREATE TABLE IF NOT EXISTS graph_edges (
- repo_id TEXT NOT NULL,
- source_path TEXT NOT NULL,
- target_path TEXT NOT NULL,
- imported_names TEXT,
- PRIMARY KEY (repo_id, source_path, target_path)
- );
- """)
-
- with contextlib.suppress(sqlite3.OperationalError):
- await db.execute(
- "ALTER TABLE graph_nodes ADD COLUMN community_id INTEGER DEFAULT 0"
- )
-
- node_rows = [
- (
- repo_id,
- path,
- data.get("language", ""),
- data.get("symbol_count", 0),
- int(data.get("has_error", False)),
- pr.get(path, 0.0),
- bc.get(path, 0.0),
- scc_map.get(path, 0),
- cd.get(path, cd.get(data.get("file_path", ""), 0)),
- )
- for path, data in g.nodes(data=True)
- ]
- await db.executemany(
- "INSERT OR REPLACE INTO graph_nodes VALUES (?,?,?,?,?,?,?,?,?)",
- node_rows,
- )
-
- edge_rows = [
- (
- repo_id,
- src,
- dst,
- json.dumps(data.get("imported_names", [])),
- )
- for src, dst, data in g.edges(data=True)
- ]
- await db.executemany(
- "INSERT OR REPLACE INTO graph_edges VALUES (?,?,?,?)",
- edge_rows,
- )
-
- await db.commit()
-
- log.info(
- "Graph persisted",
- db_path=str(db_path),
- nodes=len(node_rows),
- edges=len(edge_rows),
- )
diff --git a/packages/core/src/repowise/core/persistence/crud/git.py b/packages/core/src/repowise/core/persistence/crud/git.py
index 2a976cdfa..7fa110072 100644
--- a/packages/core/src/repowise/core/persistence/crud/git.py
+++ b/packages/core/src/repowise/core/persistence/crud/git.py
@@ -20,6 +20,7 @@ from ..models import (
_new_uuid,
_now_utc,
)
+from ..sql import LIKE_ESCAPE, escape_like
from ._shared import _BATCH_SIZE, _batch_upsert_keyed
# ---------------------------------------------------------------------------
@@ -402,7 +403,7 @@ async def get_git_commit(session: AsyncSession, repository_id: str, sha: str) ->
result = await session.execute(
select(GitCommit).where(
GitCommit.repository_id == repository_id,
- GitCommit.sha.like(f"{sha}%"),
+ GitCommit.sha.like(f"{escape_like(sha)}%", escape=LIKE_ESCAPE),
)
)
return result.scalars().first()
diff --git a/packages/core/src/repowise/core/persistence/crud/knowledge_graph.py b/packages/core/src/repowise/core/persistence/crud/knowledge_graph.py
index 37dd5191b..6c5e6910d 100644
--- a/packages/core/src/repowise/core/persistence/crud/knowledge_graph.py
+++ b/packages/core/src/repowise/core/persistence/crud/knowledge_graph.py
@@ -11,6 +11,8 @@ import json
from sqlalchemy import delete, select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import file_path_of
+
from ..models import (
KnowledgeGraphLayer,
KnowledgeGraphNodeMeta,
@@ -126,7 +128,7 @@ def file_node_meta_from_kg_nodes(nodes: list[dict]) -> list[dict]:
"""
return [
{
- "node_id": node["id"].removeprefix("file:"),
+ "node_id": file_path_of(node["id"]) or node["id"],
"node_type": node.get("type", "file"),
"summary": node.get("summary", ""),
"tags": node.get("tags", []),
diff --git a/packages/core/src/repowise/core/persistence/sql.py b/packages/core/src/repowise/core/persistence/sql.py
new file mode 100644
index 000000000..05437d200
--- /dev/null
+++ b/packages/core/src/repowise/core/persistence/sql.py
@@ -0,0 +1,25 @@
+"""Small SQL helpers shared by every layer that builds queries by hand.
+
+Kept at the persistence root (rather than inside ``crud``) because the server
+routers and MCP tools build their own ``select`` statements and need the same
+escaping the CRUD layer uses.
+"""
+
+from __future__ import annotations
+
+#: The escape character to pass as ``escape=`` on every ``like``/``ilike``
+#: paired with :func:`escape_like`. SQLite has no default LIKE escape
+#: character, so it has to be declared on the call for the escaping below to
+#: mean anything.
+LIKE_ESCAPE = "\\"
+
+
+def escape_like(value: str) -> str:
+ """Escape LIKE metacharacters (``%``, ``_``) and the escape char itself.
+
+ Always pair with ``escape=LIKE_ESCAPE`` on the ``like``/``ilike`` call.
+ Without this, a value containing ``_`` — which is most Python filenames —
+ matches any single character instead of an underscore, so the query
+ quietly returns rows the caller never asked for.
+ """
+ return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
diff --git a/packages/core/src/repowise/core/pipeline/orchestrator.py b/packages/core/src/repowise/core/pipeline/orchestrator.py
index 174bf9331..51b2e62be 100644
--- a/packages/core/src/repowise/core/pipeline/orchestrator.py
+++ b/packages/core/src/repowise/core/pipeline/orchestrator.py
@@ -541,6 +541,22 @@ async def run_pipeline(
"info",
f" ↳ KG unchanged (fingerprint {new_fingerprint[:8]}…), reusing",
)
+ else:
+ # The fingerprint said the file was reusable but the reader
+ # refused it — unreadable, or written by an older schema. The
+ # rebuild below is correct either way, but it used to happen
+ # in total silence, so a user whose hand-edited file was
+ # rejected got no signal at all.
+ logger.info(
+ "knowledge_graph.reuse_failed",
+ reason="artifact_unreadable_or_outdated",
+ path=str(kg_json_path),
+ )
+ if progress:
+ progress.on_message(
+ "info",
+ " ↳ knowledge-graph.json could not be reused, rebuilding it",
+ )
tech_stack_dicts = [
{"name": t.name, "version": t.version, "category": t.category} for t in tech_items
diff --git a/packages/core/src/repowise/core/sessions/miners/demand.py b/packages/core/src/repowise/core/sessions/miners/demand.py
index 4bfce32f2..bcbdbc1fe 100644
--- a/packages/core/src/repowise/core/sessions/miners/demand.py
+++ b/packages/core/src/repowise/core/sessions/miners/demand.py
@@ -37,6 +37,7 @@ from typing import Any
import structlog
+from repowise.core.ids import file_path_of
from repowise.core.sessions import ClaudeCodeAdapter, Event
logger = structlog.get_logger(__name__)
@@ -117,7 +118,7 @@ def _norm_rel(path: Any) -> str | None:
p = path.strip().replace("\\", "/")
if not p:
return None
- p = p.split("::", 1)[0] # symbol id -> file
+ p = file_path_of(p) or p # symbol id -> file
# Trailing line range on a bare path (``a/b.py:10-40`` or ``a/b.py:10``).
head, sep, tail = p.rpartition(":")
if sep and head and all(c.isdigit() or c == "-" for c in tail):
diff --git a/packages/server/src/repowise/server/mcp_server/_helpers.py b/packages/server/src/repowise/server/mcp_server/_helpers.py
index b540bad89..3e30a5477 100644
--- a/packages/server/src/repowise/server/mcp_server/_helpers.py
+++ b/packages/server/src/repowise/server/mcp_server/_helpers.py
@@ -15,6 +15,10 @@ from repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTR
from repowise.core.persistence.models import (
Repository,
)
+
+# Re-exported: MCP tools import their helpers from here, but the definition
+# lives in core because the CRUD layer needs the same escaping.
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like # noqa: F401
from repowise.server.mcp_server import _state
# ---------------------------------------------------------------------------
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
index cbff34ad0..484cd3250 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/targets.py
@@ -28,7 +28,9 @@ from repowise.core.persistence.models import (
WikiSymbol,
)
from repowise.server.mcp_server._helpers import (
+ LIKE_ESCAPE,
_decision_body,
+ escape_like,
filter_dicts_by_key,
filter_path_list,
is_excluded,
@@ -47,7 +49,6 @@ from repowise.server.mcp_server.tool_context.kg import (
)
from repowise.server.mcp_server.tool_risk.assessment import fix_annotation
-
# Skeleton-by-default threshold for file targets. Measured on this repo: a
# 1,400-line file's default card costs ~2.5k tokens for 16 bare signatures,
# while the smart skeleton costs ~1.7k and carries every signature plus
@@ -57,15 +58,6 @@ from repowise.server.mcp_server.tool_risk.assessment import fix_annotation
_SKELETON_AUTO_MIN_LINES = 80
-def _escape_like(value: str) -> str:
- """Escape LIKE metacharacters (``%``, ``_``) and the escape char itself.
-
- Paired with ``escape="\\"`` on every ``.like()`` so a target containing
- ``_`` or ``%`` is matched literally instead of as a wildcard.
- """
- return value.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-
-
def _synthesize_structural_summary(file_path: str, classes: list[str], functions: list[str]) -> str:
"""Build a deterministic 1-line summary when no LLM-generated summary exists.
@@ -171,16 +163,16 @@ async def _resolve_one_target(
)
is_known_file = file_meta_res.scalar_one_or_none() is not None
if not is_known_file:
- esc = _escape_like(clean_target)
+ esc = escape_like(clean_target)
res = await session.execute(
select(Page).where(
Page.repository_id == repo_id,
Page.page_type == "module_page",
or_(
Page.target_path == clean_target,
- Page.target_path.like(f"%/{esc}", escape="\\"),
- Page.target_path.like(f"{esc}/%", escape="\\"),
- Page.target_path.like(f"%/{esc}/%", escape="\\"),
+ Page.target_path.like(f"%/{esc}", escape=LIKE_ESCAPE),
+ Page.target_path.like(f"{esc}/%", escape=LIKE_ESCAPE),
+ Page.target_path.like(f"%/{esc}/%", escape=LIKE_ESCAPE),
),
)
)
@@ -208,7 +200,7 @@ async def _resolve_one_target(
select(WikiSymbol)
.where(
WikiSymbol.repository_id == repo_id,
- WikiSymbol.name.ilike(f"%{target}%"),
+ WikiSymbol.name.ilike(f"%{escape_like(target)}%", escape=LIKE_ESCAPE),
)
.limit(10)
)
@@ -302,7 +294,7 @@ async def _resolve_one_target(
select(GitMetadata.file_path)
.where(
GitMetadata.repository_id == repo_id,
- GitMetadata.file_path.like(f"{dir_prefix}%"),
+ GitMetadata.file_path.like(f"{escape_like(dir_prefix)}%", escape=LIKE_ESCAPE),
)
.limit(5)
)
@@ -546,7 +538,7 @@ async def _resolve_one_target(
select(Page).where(
Page.repository_id == repo_id,
Page.page_type == "file_page",
- Page.target_path.like(f"{page.target_path}/%"),
+ Page.target_path.like(f"{escape_like(page.target_path)}/%", escape=LIKE_ESCAPE),
)
)
file_pages = res.scalars().all()
diff --git a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
index ce6623508..f58849526 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_risk/assessment.py
@@ -15,6 +15,7 @@ from repowise.core.persistence.models import (
GraphNode,
Repository,
)
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
from repowise.server.mcp_server._helpers import (
filter_dicts_by_key,
)
@@ -202,15 +203,23 @@ async def _check_test_gap(session: AsyncSession, repo_id: str, target: str) -> b
base = os.path.splitext(os.path.basename(target))[0]
ext = os.path.splitext(target)[1].lstrip(".")
- # Build a LIKE pattern broad enough to catch test_<base>, <base>_test, <base>.spec.*
- patterns = [f"%test_{base}%", f"%{base}_test%", f"%{base}.spec.{ext}%"]
+ # Build a LIKE pattern broad enough to catch test_<base>, <base>_test,
+ # <base>.spec.*. Escaped whole: the underscores are ours and meant
+ # literally, and *base* is a filename, where an underscore is the norm.
+ # Unescaped, "%test_my_module%" also matches "testXmyXmodule", and a false
+ # hit here reports a file as tested when nothing tests it.
+ patterns = [
+ f"%{escape_like(f'test_{base}')}%",
+ f"%{escape_like(f'{base}_test')}%",
+ f"%{escape_like(f'{base}.spec.{ext}')}%",
+ ]
for pat in patterns:
res = await session.execute(
select(GraphNode)
.where(
GraphNode.repository_id == repo_id,
GraphNode.is_test == True, # noqa: E712
- GraphNode.node_id.like(pat),
+ GraphNode.node_id.like(pat, escape=LIKE_ESCAPE),
)
.limit(1)
)
diff --git a/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
index 98c9a1fc9..2296e01ab 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_search_symbols.py
@@ -27,8 +27,10 @@ from repowise.core.persistence.database import get_session
from repowise.core.persistence.models import GraphNode, Page, WikiSymbol
from repowise.core.test_paths import is_test_path, is_test_related_path
from repowise.server.mcp_server._helpers import (
+ LIKE_ESCAPE,
_get_exclude_spec,
_get_repo,
+ escape_like,
is_excluded,
)
@@ -68,9 +70,7 @@ def _qual_norm(name: str | None) -> str:
return s.lower()
-def _score_symbol(
- row: WikiSymbol, gnode: GraphNode | None, qtokens: set[str], qnorm: str
-) -> float:
+def _score_symbol(row: WikiSymbol, gnode: GraphNode | None, qtokens: set[str], qnorm: str) -> float:
"""Rank a candidate symbol against the query (higher = better).
Tiers, in priority order: exact name / qualified-name match, the query's
@@ -145,10 +145,13 @@ def _candidate_filter(qtokens: set[str], qnorm: str):
# Case-insensitive equality — WikiSymbol.name keeps original casing and
# SQLite "=" is case-sensitive, so a lowercased qnorm would never match.
clauses.append(func.lower(WikiSymbol.name) == qnorm)
- clauses.append(WikiSymbol.qualified_name.ilike(f"%{qnorm}%"))
+ clauses.append(
+ WikiSymbol.qualified_name.ilike(f"%{escape_like(qnorm)}%", escape=LIKE_ESCAPE)
+ )
for tok in qtokens:
- clauses.append(WikiSymbol.name.ilike(f"%{tok}%"))
- clauses.append(WikiSymbol.qualified_name.ilike(f"%{tok}%"))
+ esc = escape_like(tok)
+ clauses.append(WikiSymbol.name.ilike(f"%{esc}%", escape=LIKE_ESCAPE))
+ clauses.append(WikiSymbol.qualified_name.ilike(f"%{esc}%", escape=LIKE_ESCAPE))
return or_(*clauses) if clauses else None
@@ -278,7 +281,7 @@ async def search_paths_single(ctx: Any, query: str, limit: int) -> list[dict]:
select(Page.id, Page.title, Page.target_path, Page.freshness_status).where(
Page.repository_id == repository.id,
Page.page_type == "file_page",
- Page.target_path.ilike(f"%{qnorm}%"),
+ Page.target_path.ilike(f"%{escape_like(qnorm)}%", escape=LIKE_ESCAPE),
)
)
rows = res.all()
diff --git a/packages/server/src/repowise/server/mcp_server/tool_symbol.py b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
index 8d0540303..f0a3b5a80 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_symbol.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_symbol.py
@@ -458,9 +458,9 @@ async def _resolve_symbol(session, repo_id: str, symbol_id: str) -> list[WikiSym
# boundary, on the bare leaf name. Mirrors get_context's basename ladder
# so both tools accept the same shorthand instead of a dead "not found".
if file_path and name:
- from repowise.server.mcp_server.tool_context.targets import _escape_like
+ from repowise.server.mcp_server._helpers import LIKE_ESCAPE, escape_like
- esc = _escape_like(file_path.strip("/").replace("\\", "/"))
+ esc = escape_like(file_path.strip("/").replace("\\", "/"))
bare = _bare_name(name)
res = await session.execute(
select(WikiSymbol).where(
@@ -468,7 +468,7 @@ async def _resolve_symbol(session, repo_id: str, symbol_id: str) -> list[WikiSym
WikiSymbol.name == bare,
or_(
WikiSymbol.file_path == file_path.strip("/").replace("\\", "/"),
- WikiSymbol.file_path.like(f"%/{esc}", escape="\\"),
+ WikiSymbol.file_path.like(f"%/{esc}", escape=LIKE_ESCAPE),
),
)
)
diff --git a/packages/server/src/repowise/server/routers/c4.py b/packages/server/src/repowise/server/routers/c4.py
index 0029db542..fe23c210d 100644
--- a/packages/server/src/repowise/server/routers/c4.py
+++ b/packages/server/src/repowise/server/routers/c4.py
@@ -51,6 +51,10 @@ from repowise.server.services.c4_builder.serialize import (
build_architecture_view_response,
external_system_response,
)
+from repowise.server.services.c4_builder.structurizr import (
+ DEFAULT_FILENAME as STRUCTURIZR_FILENAME,
+)
+from repowise.server.services.c4_builder.structurizr import to_dsl
router = APIRouter(
prefix="/api/graph",
@@ -138,6 +142,51 @@ async def get_c4_mermaid(
return PlainTextResponse(to_mermaid_l3(view_l3, system_name=system_name))
+ "/{repo_id}/c4/structurizr",
+ response_class=PlainTextResponse,
+ responses={200: {"content": {"text/plain": {}}}},
+)
+async def get_c4_structurizr(
+ repo_id: str,
+ standalone: bool = Query(
+ False, description="Emit a complete runnable workspace instead of a model fragment"
+ ),
+ components: bool = Query(False, description="Include the component (L3) level"),
+ externals: bool = Query(True, description="Include third-party dependencies"),
+ session: AsyncSession = Depends(get_db_session),
+) -> PlainTextResponse:
+ """Structurizr DSL for this repository — open it in Structurizr Lite.
+
+ By default this is the contents of a ``model`` block, meant to be included
+ from the caller's own ``workspace.dsl`` so their views and styles survive
+ regeneration. ``standalone=true`` returns a workspace that renders on its
+ own.
+
+ Built on demand from the persisted graph, like the other C4 endpoints —
+ nothing is written at index time.
+
+ An unknown ``repo_id`` returns 200 and an empty-but-valid model rather
+ than 404, matching the l1/l2/mermaid routes beside it: they all build from
+ whatever rows the id matches, and none of them looks the repository up
+ first. Deliberate rather than drift — a lone 404 here would make this the
+ one C4 route with its own contract. The CLI does guard the case, because
+ there a wrong path is a typo worth naming.
+ """
+ model = await c4_builder.build_model(session, repo_id, include_components=components)
+ dsl = to_dsl(
+ model,
+ standalone=standalone,
+ include_components=components,
+ include_externals=externals,
+ )
+ filename = "workspace.dsl" if standalone else STRUCTURIZR_FILENAME
+ return PlainTextResponse(
+ dsl,
+ headers={"Content-Disposition": f'attachment; filename="{filename}"'},
+ )
+
+
# ---------------------------------------------------------------------------
# Dataclass → Pydantic adapters (kept tiny on purpose)
# ---------------------------------------------------------------------------
diff --git a/packages/server/src/repowise/server/routers/graph/_common.py b/packages/server/src/repowise/server/routers/graph/_common.py
index e6c4c6416..4479e97d2 100644
--- a/packages/server/src/repowise/server/routers/graph/_common.py
+++ b/packages/server/src/repowise/server/routers/graph/_common.py
@@ -28,11 +28,6 @@ async def with_repo(
return repo
-def _escape_like(s: str) -> str:
- """Escape special characters for SQL LIKE patterns."""
- return s.replace("\\", "\\\\").replace("%", "\\%").replace("_", "\\_")
-
-
async def _get_documented_paths(session: AsyncSession, repo_id: str) -> set[str]:
"""Return the set of node_ids (file paths) that have a wiki page."""
result = await session.execute(select(Page.target_path).where(Page.repository_id == repo_id))
diff --git a/packages/server/src/repowise/server/routers/graph/full_graph.py b/packages/server/src/repowise/server/routers/graph/full_graph.py
index 343720d9f..3e0295bc0 100644
--- a/packages/server/src/repowise/server/routers/graph/full_graph.py
+++ b/packages/server/src/repowise/server/routers/graph/full_graph.py
@@ -8,9 +8,10 @@ from sqlalchemy.ext.asyncio import AsyncSession
from fastapi import APIRouter, Depends, Query
from repowise.core.persistence import crud
from repowise.core.persistence.models import GraphEdge, GraphNode
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
from repowise.server.deps import get_db_session
from repowise.server.mcp_server._graph_utils import _node_id_is_excluded
-from repowise.server.routers.graph._common import _escape_like, with_repo
+from repowise.server.routers.graph._common import with_repo
from repowise.server.schemas import GraphExportResponse, NodeSearchResult
from repowise.server.services.graph_views import edge_response
from repowise.server.services.node_signals import (
@@ -93,7 +94,7 @@ async def search_nodes(
select(GraphNode)
.where(
GraphNode.repository_id == repo_id,
- GraphNode.node_id.ilike(f"%{_escape_like(q)}%"),
+ GraphNode.node_id.ilike(f"%{escape_like(q)}%", escape=LIKE_ESCAPE),
)
.order_by(GraphNode.symbol_count.desc(), GraphNode.pagerank.desc())
.limit(limit)
diff --git a/packages/server/src/repowise/server/routers/symbols.py b/packages/server/src/repowise/server/routers/symbols.py
index e8a8ad1c6..db96551f8 100644
--- a/packages/server/src/repowise/server/routers/symbols.py
+++ b/packages/server/src/repowise/server/routers/symbols.py
@@ -18,6 +18,7 @@ from repowise.core.persistence.models import (
GraphNode,
WikiSymbol,
)
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
from repowise.server.deps import get_db_session, verify_api_key
from repowise.server.schemas import Paginated, SymbolImportanceComponents, SymbolResponse
from repowise.server.services.symbol_ranking import (
@@ -219,7 +220,7 @@ async def search_symbols(
base = select(WikiSymbol).where(WikiSymbol.repository_id == repo_id)
if q:
- base = base.where(WikiSymbol.name.ilike(f"%{q}%"))
+ base = base.where(WikiSymbol.name.ilike(f"%{escape_like(q)}%", escape=LIKE_ESCAPE))
if kind:
base = base.where(WikiSymbol.kind == kind)
if language:
@@ -510,7 +511,7 @@ async def lookup_by_name(
select(WikiSymbol)
.where(
WikiSymbol.repository_id == repo_id,
- WikiSymbol.name.ilike(f"%{name}%"),
+ WikiSymbol.name.ilike(f"%{escape_like(name)}%", escape=LIKE_ESCAPE),
)
.limit(10)
)
diff --git a/packages/server/src/repowise/server/services/c4_builder/__init__.py b/packages/server/src/repowise/server/services/c4_builder/__init__.py
index 388601490..0269583ff 100644
--- a/packages/server/src/repowise/server/services/c4_builder/__init__.py
+++ b/packages/server/src/repowise/server/services/c4_builder/__init__.py
@@ -22,31 +22,39 @@ from dataclasses import replace
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import ExternalSystemId, SystemId, file_path_of, parse, render
from repowise.core.persistence import ExternalSystem, Repository
-from repowise.core.persistence.crud import get_kg_project_meta
+from repowise.core.persistence.crud import (
+ get_kg_layers,
+ get_kg_project_meta,
+ get_kg_tour_steps,
+)
from repowise.core.persistence.models import DeadCodeFinding, GitMetadata
from .actors import derive_actors
-from .components import detect_components
+from .components import detect_components, detect_components_for_all
from .containers import container_id, detect_containers
from .models import (
C4L1,
C4L2,
C4L3,
+ C4Model,
Component,
Container,
ExternalSystemView,
Person,
Relation,
System,
+ TourStep,
)
-from .relations import aggregate_relations, external_node_to_system_id
-from .signals import count_box_signals
+from .relations import aggregate_relations, external_node_to_system_id, load_edges
+from .signals import build_box_signals, count_box_signals
__all__ = [
"C4L1",
"C4L2",
"C4L3",
+ "C4Model",
"Component",
"Container",
"ExternalSystemView",
@@ -57,6 +65,7 @@ __all__ = [
"build_l1",
"build_l2",
"build_l3",
+ "build_model",
"container_id",
"load_repo",
]
@@ -92,7 +101,7 @@ async def _external_views(
name_to_id: dict[str, str] = {}
for name in sorted(by_name):
row = by_name[name]
- view_id = f"ext:{name}"
+ view_id = render(ExternalSystemId(name))
views.append(
ExternalSystemView(
id=view_id,
@@ -108,10 +117,15 @@ async def _external_views(
return views, name_to_id
+def _is_external_box(box_id: str) -> bool:
+ """True if a relation endpoint is an external-system box rather than ours."""
+ return isinstance(parse(box_id), ExternalSystemId)
+
+
def _system_for(repo: Repository | None, repo_id: str) -> System:
if repo is None:
- return System(id=f"sys:{repo_id}", name=repo_id)
- return System(id=f"sys:{repo.id}", name=repo.name, description="")
+ return System(id=render(SystemId(repo_id)), name=repo_id)
+ return System(id=render(SystemId(repo.id)), name=repo.name, description="")
# ---------------------------------------------------------------------------
@@ -119,23 +133,33 @@ def _system_for(repo: Repository | None, repo_id: str) -> System:
# ---------------------------------------------------------------------------
+async def _actors_for(
+ session: AsyncSession, repo_id: str, system: System
+) -> tuple[list[Person], list[Relation]]:
+ """The actor set and its edges into the system.
+
+ The two travel together on purpose. A person with no edge to the system is
+ an orphan: Structurizr's context view includes the system plus what is
+ related to it, so an unconnected actor is simply not drawn, and the batched
+ build used to produce exactly that by deriving the people alone.
+
+ Actors are derived from how the system is actually entered (CLI user, API
+ client, scheduled job …) rather than a lone hardcoded "User".
+ """
+ actors = derive_actors(await _curated_entry_points(session, repo_id))
+ people = [
+ Person(id=a.id, name=a.name, description=a.description, kind=a.kind) for a in actors
+ ]
+ relations = [Relation(source_id=a.id, target_id=system.id, label=a.verb) for a in actors]
+ return people, relations
+
+
async def build_l1(session: AsyncSession, repo_id: str) -> C4L1:
repo = await load_repo(session, repo_id)
system = _system_for(repo, repo_id)
externals, _ = await _external_views(session, repo_id)
- # Derive the actor set from how the system is actually entered (CLI user,
- # API client, scheduled job …) rather than a lone hardcoded "User".
- entry_points = await _curated_entry_points(session, repo_id)
- actors = derive_actors(entry_points)
- people = [
- Person(id=a.id, name=a.name, description=a.description, kind=a.kind)
- for a in actors
- ]
-
- relations: list[Relation] = [
- Relation(source_id=a.id, target_id=system.id, label=a.verb) for a in actors
- ]
+ people, relations = await _actors_for(session, repo_id, system)
for ext in externals:
relations.append(
Relation(source_id=system.id, target_id=ext.id, label=ext.category)
@@ -170,7 +194,7 @@ async def build_l2(session: AsyncSession, repo_id: str) -> C4L2:
)
# Only surface externals actually depended on by at least one container.
- used_external_ids = {r.target_id for r in relations if r.target_id.startswith("ext:")}
+ used_external_ids = {r.target_id for r in relations if _is_external_box(r.target_id)}
pruned_externals = [e for e in externals if e.id in used_external_ids]
return C4L2(containers=containers, external_systems=pruned_externals, relations=relations)
@@ -229,8 +253,8 @@ async def build_l3(session: AsyncSession, repo_id: str, container_id_value: str)
]
externals_all, _ = await _external_views(session, repo_id)
- used_external_ids = {r.target_id for r in relations if r.target_id.startswith("ext:")}
- used_external_ids |= {r.source_id for r in relations if r.source_id.startswith("ext:")}
+ used_external_ids = {r.target_id for r in relations if _is_external_box(r.target_id)}
+ used_external_ids |= {r.source_id for r in relations if _is_external_box(r.source_id)}
externals = [e for e in externals_all if e.id in used_external_ids]
return C4L3(
@@ -241,6 +265,169 @@ async def build_l3(session: AsyncSession, repo_id: str, container_id_value: str)
)
+async def build_model(
+ session: AsyncSession, repo_id: str, *, include_components: bool = True
+) -> C4Model:
+ """Build every C4 level in one pass, for callers that need the whole model.
+
+ ``build_l3`` re-reads the graph per container, which is correct for a
+ dashboard showing one at a time and quadratic-feeling for anything walking
+ all of them. Here the file table and the edge table are each read once and
+ sliced in Python.
+
+ Set ``include_components=False`` to stop after containers — the component
+ level is the expensive half and an export may not want it.
+ """
+ repo = await load_repo(session, repo_id)
+ system = _system_for(repo, repo_id)
+ containers = await detect_containers(session, repo_id, root_name=repo.name if repo else None)
+ externals_all, _ = await _external_views(session, repo_id)
+
+ people, actor_relations = await _actors_for(session, repo_id, system)
+
+ file_to_container = await _file_to_container_map(session, repo_id, containers)
+ file_to_external = await external_node_to_system_id(session, repo_id)
+ containers = await _annotate_container_signals(
+ session, repo_id, containers, file_to_container
+ )
+
+ edges = await load_edges(session, repo_id)
+ container_relations = await aggregate_relations(
+ session,
+ repo_id,
+ file_to_box=file_to_container,
+ file_to_external=file_to_external,
+ edges=edges,
+ )
+
+ components_by_container: dict[str, list[Component]] = {}
+ component_relations: list[Relation] = []
+ file_to_component: dict[str, str] = {}
+ if include_components:
+ detected = await detect_components_for_all(session, repo_id, containers)
+ for cid, (components, file_index) in detected.items():
+ components_by_container[cid] = components
+ file_to_component.update(file_index)
+ component_relations = await aggregate_relations(
+ session,
+ repo_id,
+ file_to_box=file_to_component,
+ file_to_external=file_to_external,
+ edges=edges,
+ )
+
+ # An external nobody depends on is noise in every view that shows it.
+ used = {r.target_id for r in container_relations if _is_external_box(r.target_id)}
+ used |= {r.source_id for r in container_relations if _is_external_box(r.source_id)}
+ used |= {r.target_id for r in component_relations if _is_external_box(r.target_id)}
+ used |= {r.source_id for r in component_relations if _is_external_box(r.source_id)}
+ externals = [e for e in externals_all if e.id in used]
+
+ # Every per-file signal is read once here and rolled up to both levels, so
+ # the metadata costs a fixed number of queries rather than one per box.
+ per_file = await _per_file_signals(session, repo_id)
+ box_signals = build_box_signals(file_to_container, **per_file)
+ if file_to_component:
+ box_signals.update(build_box_signals(file_to_component, **per_file))
+
+ return C4Model(
+ system=system,
+ people=people,
+ containers=containers,
+ components_by_container=components_by_container,
+ external_systems=externals,
+ container_relations=container_relations,
+ component_relations=component_relations,
+ actor_relations=actor_relations,
+ box_signals=box_signals,
+ tour=await _tour_steps(session, repo_id),
+ )
+
+
+async def _per_file_signals(session: AsyncSession, repo_id: str) -> dict[str, dict]:
+ """Read the per-file health, ownership and layer sources, once each."""
+ git_rows = (
+ await session.execute(
+ select(
+ GitMetadata.file_path,
+ GitMetadata.is_hotspot,
+ GitMetadata.primary_owner_name,
+ GitMetadata.bus_factor,
+ ).where(GitMetadata.repository_id == repo_id)
+ )
+ ).all()
+ hotspot_paths = [row[0] for row in git_rows if row[1]]
+ file_owners = {row[0]: row[2] for row in git_rows if row[2]}
+ # A real bus factor is at least 1 — the indexer seeds the column with 0 and
+ # only overwrites it for files that have commit history, so 0 means "not
+ # known". Emitting it would read as "nobody owns this", which is a much
+ # louder claim than the gap it actually is.
+ file_bus_factors = {row[0]: row[3] for row in git_rows if row[3]}
+
+ dead_paths = [
+ row[0]
+ for row in (
+ await session.execute(
+ select(DeadCodeFinding.file_path).where(
+ DeadCodeFinding.repository_id == repo_id,
+ DeadCodeFinding.status == "open",
+ DeadCodeFinding.kind == "unreachable_file",
+ )
+ )
+ ).all()
+ ]
+
+ # Layer membership is curated per file; a box inherits the layers of the
+ # files it holds. Layer node ids carry the KG "file:" prefix, the graph
+ # does not, so they are converted rather than compared raw.
+ file_layers: dict[str, str] = {}
+ for layer in await get_kg_layers(session, repo_id):
+ try:
+ node_ids = json.loads(layer.node_ids_json or "[]")
+ except (ValueError, TypeError):
+ continue
+ # Only a decode failure was guarded, but a column holding a valid JSON
+ # string or object parses fine and then iterates: a bare `"abc"` would
+ # yield the file paths "a", "b", "c", and an object its keys.
+ if not isinstance(node_ids, list):
+ continue
+ for node_id in node_ids:
+ path = file_path_of(str(node_id))
+ if path:
+ file_layers.setdefault(path, layer.name)
+
+ return {
+ "hotspot_paths": hotspot_paths,
+ "dead_paths": dead_paths,
+ "file_layers": file_layers,
+ "file_owners": file_owners,
+ "file_bus_factors": file_bus_factors,
+ # No git metadata at all means churn was never measured — every
+ # indexed repo with history has rows here. Without this an
+ # index-only run would report every box as hotspot-free.
+ "churn_measured": bool(git_rows),
+ }
+
+
+async def _tour_steps(session: AsyncSession, repo_id: str) -> list[TourStep]:
+ """The curated reading order, if this repo has one."""
+ layer_names = {
+ layer.layer_id: layer.name for layer in await get_kg_layers(session, repo_id)
+ }
+ steps = await get_kg_tour_steps(session, repo_id)
+ return [
+ TourStep(
+ order=step.step_order,
+ title=step.title,
+ description=step.description or "",
+ reason=step.reason or "",
+ target_path=step.target_path,
+ layer_name=layer_names.get(step.layer_id or ""),
+ )
+ for step in sorted(steps, key=lambda s: s.step_order)
+ ]
+
+
# ---------------------------------------------------------------------------
# Helpers
# ---------------------------------------------------------------------------
diff --git a/packages/server/src/repowise/server/services/c4_builder/actors.py b/packages/server/src/repowise/server/services/c4_builder/actors.py
index 278ac167c..4e97fd2f1 100644
--- a/packages/server/src/repowise/server/services/c4_builder/actors.py
+++ b/packages/server/src/repowise/server/services/c4_builder/actors.py
@@ -16,6 +16,8 @@ from __future__ import annotations
from dataclasses import dataclass
+from repowise.core.ids import PersonId, render
+
# Actor kind -> (display name, what it does to the system). Order here is the
# stable render order when several kinds are present.
_ACTOR_META: dict[str, tuple[str, str]] = {
@@ -106,7 +108,7 @@ def derive_actors(entry_points: list[str]) -> list[Actor]:
name, description = _ACTOR_META[kind]
actors.append(
Actor(
- id=f"person:{kind}",
+ id=render(PersonId(kind)),
kind=kind,
name=name,
description=description,
diff --git a/packages/server/src/repowise/server/services/c4_builder/architecture.py b/packages/server/src/repowise/server/services/c4_builder/architecture.py
index 4eb147cfa..1defa9710 100644
--- a/packages/server/src/repowise/server/services/c4_builder/architecture.py
+++ b/packages/server/src/repowise/server/services/c4_builder/architecture.py
@@ -11,6 +11,7 @@ from sqlalchemy import select
from sqlalchemy.exc import IntegrityError
from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker
+from repowise.core.ids import ExternalSystemId, file_path_of, render
from repowise.core.persistence import (
ExternalSystem,
GraphEdge,
@@ -104,7 +105,7 @@ async def _external_views(
row = by_name[name]
views.append(
ExternalSystemView(
- id=f"ext:{name}",
+ id=render(ExternalSystemId(name)),
name=name,
display_name=row.display_name or name,
category=row.category,
@@ -156,17 +157,59 @@ def _percentile_ranks(values: list[float]) -> dict[int, float]:
def _load_knowledge_graph(path: str) -> dict | None:
+ """Read the curated knowledge-graph artifact, or ``None`` if unusable.
+
+ The file is user-visible and hand-editable, so a trailing comma in it
+ must not become a 500 on the architecture view — returning ``None``
+ drops through to the community/directory rungs of the layer cascade.
+
+ Parsing is not enough: ``"broken"`` and ``[]`` are valid JSON, and the
+ readers below expect an object, so the shape is checked here rather than
+ at every ``.get`` that follows.
+ """
if not path or not os.path.isfile(path):
return None
- with open(path) as f:
- return json.load(f)
+ try:
+ with open(path) as f:
+ data = json.load(f)
+ except (json.JSONDecodeError, OSError, UnicodeDecodeError):
+ logger.warning("kg_file_unreadable path=%s", path, exc_info=True)
+ return None
+ if not isinstance(data, dict):
+ logger.warning("kg_file_not_an_object path=%s found=%s", path, type(data).__name__)
+ return None
+ return data
+
+
+def _entries(raw: object) -> list[dict]:
+ """The dict entries of a curated list, dropping anything that is not one.
+
+ Every list in the artifact is hand-editable, so a scalar where an object
+ belongs is a shape a user can produce. Skipping the bad entry keeps the
+ rest of their curation.
+ """
+ if not isinstance(raw, list):
+ return []
+ return [entry for entry in raw if isinstance(entry, dict)]
+
+
+def _file_paths(node_ids: object) -> list[str]:
+ """Curated KG node ids to repo-relative file paths.
+
+ KG ids carry a ``file:`` prefix the dependency graph does not use, and a
+ layer's member list can also hold non-file ids — those resolve to nothing
+ and are dropped rather than passed through as if they were paths.
+ """
+ if not isinstance(node_ids, list):
+ return []
+ return [p for p in (file_path_of(str(nid)) for nid in node_ids) if p]
-def _sub_groups_from_raw(raw_sub_groups: list[dict] | None, node_ids: set[str]) -> list[dict]:
+def _sub_groups_from_raw(raw_sub_groups: object, node_ids: set[str]) -> list[dict]:
"""Map curated subGroups to plain dicts, dropping ids absent from the graph."""
groups: list[dict] = []
- for sg in raw_sub_groups or []:
- mapped = [nid.removeprefix("file:") for nid in sg.get("nodeIds", sg.get("node_ids", []))]
+ for sg in _entries(raw_sub_groups):
+ mapped = _file_paths(sg.get("nodeIds", sg.get("node_ids", [])))
matched = [nid for nid in mapped if nid in node_ids]
if matched:
groups.append(
@@ -184,9 +227,8 @@ def _layers_from_knowledge_graph(
node_ids: set[str],
) -> list[dict]:
layers = []
- for i, layer in enumerate(kg.get("layers", [])):
- raw_ids = layer.get("nodeIds", [])
- mapped = [nid.removeprefix("file:") for nid in raw_ids]
+ for i, layer in enumerate(_entries(kg.get("layers"))):
+ mapped = _file_paths(layer.get("nodeIds"))
matched = [nid for nid in mapped if nid in node_ids]
layers.append(
{
@@ -218,11 +260,13 @@ def _layers_from_communities(
if cid in meta:
with contextlib.suppress(json.JSONDecodeError, TypeError):
cm = json.loads(meta[cid])
+ # The writer stores only ``label`` and ``cohesion`` in this blob;
+ # there is no description to read back.
layers.append(
{
"id": f"layer:community-{cid}",
- "name": cm.get("name", f"Community {cid}"),
- "description": cm.get("description", ""),
+ "name": cm.get("label") or f"Community {cid}",
+ "description": "",
"node_ids": groups[cid],
}
)
@@ -248,8 +292,8 @@ def _layers_from_directories(nodes: list[GraphNode]) -> list[dict]:
def _tour_from_knowledge_graph(kg: dict) -> list[ArchTourStep]:
steps = []
- for entry in kg.get("tour", []):
- node_ids = [nid.removeprefix("file:") for nid in entry.get("nodeIds", [])]
+ for entry in _entries(kg.get("tour")):
+ node_ids = _file_paths(entry.get("nodeIds"))
target_path = entry.get("target_path")
if not node_ids and target_path:
# Curated steps address one file by path, not a nodeIds list.
@@ -275,7 +319,7 @@ def _layers_from_db(db_layers: list, node_ids: set[str]) -> list[dict]:
layers = []
for i, row in enumerate(db_layers):
raw_ids = json.loads(row.node_ids_json) if row.node_ids_json else []
- mapped = [nid.removeprefix("file:") for nid in raw_ids]
+ mapped = _file_paths(raw_ids)
matched = [nid for nid in mapped if nid in node_ids]
raw_sub_groups_json = getattr(row, "sub_groups_json", None)
raw_sub_groups = json.loads(raw_sub_groups_json) if raw_sub_groups_json else []
@@ -296,7 +340,7 @@ def _tour_from_db(db_steps: list) -> list[ArchTourStep]:
steps = []
for row in db_steps:
node_ids = json.loads(row.node_ids_json) if row.node_ids_json else []
- node_ids = [nid.removeprefix("file:") for nid in node_ids]
+ node_ids = _file_paths(node_ids)
target_path = getattr(row, "target_path", None)
if not node_ids and target_path:
node_ids = [target_path]
diff --git a/packages/server/src/repowise/server/services/c4_builder/components.py b/packages/server/src/repowise/server/services/c4_builder/components.py
index 43c3270cd..b2b6404a2 100644
--- a/packages/server/src/repowise/server/services/c4_builder/components.py
+++ b/packages/server/src/repowise/server/services/c4_builder/components.py
@@ -23,16 +23,20 @@ to component->component edges.
from __future__ import annotations
+import logging
from collections import defaultdict
from collections.abc import Iterable
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import ComponentId, InvalidNodeIdError, render
from repowise.core.persistence import GraphNode
from .containers import container_id
-from .models import Component
+from .models import Component, Container
+
+logger = logging.getLogger(__name__)
# Source-root directories that carry no architectural meaning — skipped so a
# component reflects the real feature directory beneath them. Deliberately only
@@ -40,15 +44,14 @@ from .models import Component
# to surface as their own component if indexed).
_PASS_THROUGH_DIRS = frozenset({"src", "lib", "app", "source"})
-# Display label + id sentinel for the bucket of files that sit at the container
-# root. Chosen so neither ever serializes the old "_root" token.
+# Display label for the bucket of files that sit at the container root.
+# Chosen so it never serializes the old "_root" token.
ROOT_BUCKET_LABEL = "(root)"
-_ROOT_BUCKET_SUFFIX = "::root"
-def component_id(component_path: str) -> str:
+def component_id(component_path: str, *, is_root_bucket: bool = False) -> str:
"""Stable id for a component, keyed on its repo-relative directory."""
- return f"cmp:{component_path or '.'}"
+ return render(ComponentId(component_path or ".", is_root_bucket=is_root_bucket))
def _relative(file_path: str, container_path: str) -> str:
@@ -59,11 +62,15 @@ def _relative(file_path: str, container_path: str) -> str:
def _component_for(
file_path: str, container_path: str, root_label: str
-) -> tuple[str, str, str]:
+) -> tuple[str, str, str] | None:
"""Return ``(component_id, name, path)`` for a file's owning component.
Skips leading pass-through directories; files with no meaningful directory
fall into the ``(root)`` bucket.
+
+ ``None`` when the directory name has no unambiguous id — a directory
+ ending in the reserved root marker. One odd directory costs its own
+ component, not the whole view.
"""
rel = _relative(file_path, container_path)
dirs = rel.split("/")[:-1] # directory segments only (drop the filename)
@@ -74,12 +81,16 @@ def _component_for(
if i >= len(dirs):
base = container_path or "."
- return f"cmp:{base}{_ROOT_BUCKET_SUFFIX}", root_label, container_path or "."
+ return component_id(base, is_root_bucket=True), root_label, base
name = dirs[i]
rel_dir = "/".join(dirs[: i + 1])
path = f"{container_path}/{rel_dir}" if container_path else rel_dir
- return component_id(path), name, path
+ try:
+ return component_id(path), name, path
+ except InvalidNodeIdError:
+ logger.warning("c4_component_path_unrenderable path=%s", path)
+ return None
async def detect_components(
@@ -101,13 +112,85 @@ async def detect_components(
file_nodes = await _files_in(
session, repository_id, container_path, sibling_roots=sibling_roots
)
+ return _bucket_into_components(file_nodes, container_path, root_label)
+
+
+async def detect_components_for_all(
+ session: AsyncSession,
+ repository_id: str,
+ containers: Iterable[Container],
+ *,
+ root_label: str = ROOT_BUCKET_LABEL,
+) -> dict[str, tuple[list[Component], dict[str, str]]]:
+ """Same as :func:`detect_components`, for every container, in one query.
+
+ :func:`detect_components` re-reads the file table per call and throws away
+ everything outside its container, which is right for the dashboard (one
+ container at a time) and wasteful for anything walking the whole model.
+ This reads once and slices in Python; the ownership rules are shared, so
+ the two agree by construction.
+ Returns ``{container_id: (components, file_index)}``.
+ """
+ containers = list(containers)
+ all_files = await _files_in(session, repository_id, "")
+ roots = [c.path for c in containers if c.path]
+
+ # One pass over the files rather than one per container. Walking every
+ # container per file made a large monorepo do millions of prefix checks in
+ # the function whose whole point is being the cheap path.
+ by_root = {c.path: c for c in containers}
+ owned: dict[str, list[GraphNode]] = defaultdict(list)
+ catch_all = next((c for c in containers if not c.path), None)
+ for node in all_files:
+ matches = _matching_roots(node.node_id, roots)
+ if len(matches) == 1:
+ owned[by_root[matches[0]].id].append(node)
+ elif not matches and catch_all is not None:
+ owned[catch_all.id].append(node)
+ # Two roots claiming one file means a container nested inside another,
+ # where the sibling-prefix rule leaves the file unowned. Kept exactly
+ # as the per-container path resolves it: this function's contract is
+ # to agree with it element for element, so the nesting gap is one
+ # decision to take in one place, not a difference between the two.
+
+ out: dict[str, tuple[list[Component], dict[str, str]]] = {}
+ for container in containers:
+ out[container.id] = _bucket_into_components(
+ owned.get(container.id, []), container.path, root_label
+ )
+ return out
+
+
+def _matching_roots(node_id: str, roots: list[str]) -> list[str]:
+ """Every container path that prefixes *node_id*."""
+ return [
+ root for root in roots if node_id == root or node_id.startswith(root + "/")
+ ]
+
+
+def _owned_by(node_id: str, container_path: str, sibling_prefixes: tuple[str, ...]) -> bool:
+ """Whether *node_id* belongs to a container — the rule :func:`_files_in` applies."""
+ if container_path and not (
+ node_id == container_path or node_id.startswith(container_path + "/")
+ ):
+ return False
+ return not node_id.startswith(sibling_prefixes) if sibling_prefixes else True
+
+
+def _bucket_into_components(
+ file_nodes: list[GraphNode], container_path: str, root_label: str
+) -> tuple[list[Component], dict[str, str]]:
+ """Group a container's files into components. Pure — no session."""
bucket: dict[str, list[GraphNode]] = defaultdict(list)
meta: dict[str, tuple[str, str]] = {} # comp_id -> (name, path)
file_owner: dict[str, str] = {}
cid = container_id(container_path)
for node in file_nodes:
- comp_id, name, path = _component_for(node.node_id, container_path, root_label)
+ resolved = _component_for(node.node_id, container_path, root_label)
+ if resolved is None:
+ continue
+ comp_id, name, path = resolved
bucket[comp_id].append(node)
meta[comp_id] = (name, path)
file_owner[node.node_id] = comp_id
@@ -166,4 +249,9 @@ async def _files_in(
return nodes
-__all__ = ["ROOT_BUCKET_LABEL", "component_id", "detect_components"]
+__all__ = [
+ "ROOT_BUCKET_LABEL",
+ "component_id",
+ "detect_components",
+ "detect_components_for_all",
+]
diff --git a/packages/server/src/repowise/server/services/c4_builder/containers.py b/packages/server/src/repowise/server/services/c4_builder/containers.py
index 021f88cea..15a55c515 100644
--- a/packages/server/src/repowise/server/services/c4_builder/containers.py
+++ b/packages/server/src/repowise/server/services/c4_builder/containers.py
@@ -23,6 +23,7 @@ from collections.abc import Iterable
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import ContainerId, render
from repowise.core.persistence import ExternalSystem, GraphNode
from .models import Container
@@ -109,7 +110,7 @@ async def detect_containers(
def container_id(path: str) -> str:
"""Stable id for a container path. Edge sources/targets use this form."""
- return f"pkg:{path}" if path else "pkg:."
+ return render(ContainerId(path or "."))
async def _container_roots_from_manifests(
diff --git a/packages/server/src/repowise/server/services/c4_builder/models.py b/packages/server/src/repowise/server/services/c4_builder/models.py
index 6c1fc5eaa..4e5ec4e4d 100644
--- a/packages/server/src/repowise/server/services/c4_builder/models.py
+++ b/packages/server/src/repowise/server/services/c4_builder/models.py
@@ -114,6 +114,89 @@ class C4L3:
relations: list[Relation]
+@dataclass(frozen=True)
+class BoxSignals:
+ """What we know about a container or component beyond its shape.
+
+ C4 has no vocabulary for any of this — which is the point. Carried
+ per-box so an exporter can attach it without going back to the database,
+ and every field is optional because health data is sparse: ``None`` means
+ "not known", which must not be rendered as a real score of zero.
+ """
+
+ #: ``None`` when churn was never measured for this repo at all — a
+ #: different statement from "measured, found none", and the one a reader
+ #: would otherwise take as a clean bill of health.
+ #:
+ #: ``dead_count`` has no such distinction available: an empty findings
+ #: table means either the pass did not run or it found nothing, and
+ #: nothing in the schema separates them, so zero is reported as zero.
+ hotspot_count: int | None = 0
+ dead_count: int = 0
+ #: Names of the curated layers this box's files belong to. A box can span
+ #: several, so this is a list rather than one label.
+ layers: tuple[str, ...] = ()
+ #: The person owning the most files in this box, and their share of them.
+ primary_owner: str | None = None
+ primary_owner_pct: float | None = None
+ #: Lowest bus factor among the box's files — the worst case, not the mean,
+ #: because one unowned file is the risk a reader cares about.
+ min_bus_factor: int | None = None
+
+
+@dataclass(frozen=True)
+class TourStep:
+ """One step of the curated reading order.
+
+ Structurizr has no concept of a guided tour, so this rides along as a
+ comment. Kept as data rather than a formatted string so the emitter
+ decides how it reads.
+ """
+
+ order: int
+ title: str
+ description: str = ""
+ reason: str = ""
+ target_path: str | None = None
+ layer_name: str | None = None
+
+
+@dataclass(frozen=True)
+class C4Model:
+ """Every C4 level at once, built from one pass over the graph.
+
+ The dashboard views (``C4L1``/``C4L2``/``C4L3``) each answer one question
+ about one level. Anything that has to walk the whole model — an export,
+ say — would otherwise call ``build_l3`` per container and re-read the
+ graph each time. This carries all of it, and nothing below it touches a
+ session, so an emitter is a pure function of this value.
+
+ ``components_by_container`` is empty when components were not requested.
+ ``component_relations`` roll edges up to component granularity across
+ every container, so a cross-container edge names the real component on
+ both ends rather than collapsing into its container.
+ """
+
+ system: System
+ people: list[Person]
+ containers: list[Container]
+ components_by_container: dict[str, list[Component]]
+ external_systems: list[ExternalSystemView]
+ container_relations: list[Relation]
+ component_relations: list[Relation]
+ #: Actor→system edges. Their own field rather than part of
+ #: ``container_relations`` because they belong to no level's box graph and
+ #: must survive every include/exclude flag — a person with no edge to the
+ #: system is not drawn at all in a context view.
+ actor_relations: list[Relation] = field(default_factory=list)
+ #: Health, ownership and layer membership, keyed by container/component id.
+ #: Empty when the repo has none of it — an export must degrade to plain C4
+ #: rather than emitting placeholders.
+ box_signals: dict[str, BoxSignals] = field(default_factory=dict)
+ #: The curated reading order, in step order. Empty when there is no tour.
+ tour: list[TourStep] = field(default_factory=list)
+
+
# ---------------------------------------------------------------------------
# Architecture view (unified model)
# ---------------------------------------------------------------------------
diff --git a/packages/server/src/repowise/server/services/c4_builder/relations.py b/packages/server/src/repowise/server/services/c4_builder/relations.py
index 6d3e0b8b7..e07cbe66d 100644
--- a/packages/server/src/repowise/server/services/c4_builder/relations.py
+++ b/packages/server/src/repowise/server/services/c4_builder/relations.py
@@ -23,18 +23,37 @@ from collections import defaultdict
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession
+from repowise.core.ids import ExternalSystemId, render
from repowise.core.persistence import ExternalSystem, GraphEdge, GraphNode
from .labels import coupling_strength, relation_label
from .models import Relation
+async def load_edges(
+ session: AsyncSession, repository_id: str
+) -> list[tuple[str, str, str | None]]:
+ """Read every graph edge once, as ``(source, target, type)`` rows.
+
+ Split out so a caller rolling the same edges up several ways — by
+ container and by component, say — pays for one read instead of one per
+ aggregation.
+ """
+ result = await session.execute(
+ select(GraphEdge.source_node_id, GraphEdge.target_node_id, GraphEdge.edge_type).where(
+ GraphEdge.repository_id == repository_id
+ )
+ )
+ return list(result.all())
+
+
async def aggregate_relations(
session: AsyncSession,
repository_id: str,
file_to_box: dict[str, str],
*,
file_to_external: dict[str, str] | None = None,
+ edges: list[tuple[str, str, str | None]] | None = None,
) -> list[Relation]:
"""Roll file→file edges up to box→box edges.
@@ -46,17 +65,17 @@ async def aggregate_relations(
Map of ``external:*`` node_id → external-system id (e.g., ``ext:react``).
When provided, edges whose target is an external node are also
emitted (as box → external).
+ edges:
+ Pre-loaded rows from :func:`load_edges`. Omit to read them here.
"""
file_to_external = file_to_external or {}
- result = await session.execute(
- select(GraphEdge.source_node_id, GraphEdge.target_node_id, GraphEdge.edge_type)
- .where(GraphEdge.repository_id == repository_id)
- )
+ if edges is None:
+ edges = await load_edges(session, repository_id)
counts: dict[tuple[str, str], int] = defaultdict(int)
types: dict[tuple[str, str], set[str]] = defaultdict(set)
- for src, tgt, etype in result.all():
+ for src, tgt, etype in edges:
src_box = file_to_box.get(src)
if src_box is None:
continue
@@ -104,4 +123,4 @@ async def external_node_to_system_id(
.join(ExternalSystem, GraphNode.external_system_id == ExternalSystem.id)
.where(GraphNode.repository_id == repository_id)
)
- return {node_id: f"ext:{name}" for node_id, name in result.all()}
+ return {node_id: render(ExternalSystemId(name)) for node_id, name in result.all()}
diff --git a/packages/server/src/repowise/server/services/c4_builder/signals.py b/packages/server/src/repowise/server/services/c4_builder/signals.py
index 3445ed0d2..c283a462a 100644
--- a/packages/server/src/repowise/server/services/c4_builder/signals.py
+++ b/packages/server/src/repowise/server/services/c4_builder/signals.py
@@ -10,9 +10,16 @@ so it unit-tests without a session.
from __future__ import annotations
-from collections import defaultdict
+from collections import Counter, defaultdict
from collections.abc import Iterable, Mapping
+from .models import BoxSignals
+
+#: Least share of a box's files that must carry a known owner before we
+#: describe who owns it. Under this the answer is "we do not know", and the
+#: module's rule is that an unknown is omitted rather than guessed at.
+_MIN_OWNERSHIP_COVERAGE = 0.25
+
def count_box_signals(
file_to_box: Mapping[str, str],
@@ -36,3 +43,86 @@ def count_box_signals(
if path in dead:
dead_by_box[box] += 1
return {box: (hot_by_box[box], dead_by_box[box]) for box in boxes}
+
+
+def build_box_signals(
+ file_to_box: Mapping[str, str],
+ *,
+ hotspot_paths: Iterable[str] = (),
+ dead_paths: Iterable[str] = (),
+ file_layers: Mapping[str, str] | None = None,
+ file_owners: Mapping[str, str] | None = None,
+ file_bus_factors: Mapping[str, int] | None = None,
+ churn_measured: bool = True,
+) -> dict[str, BoxSignals]:
+ """Roll every per-file signal up to its box in one pass.
+
+ Pure, so the aggregation rules are testable without a database and the
+ caller pays for exactly one read of each source table.
+
+ Ownership is the person owning the most files in the box, as a share of
+ *every* file in the box — not of the files git happened to attribute.
+ Dividing by the attributed ones turned a single known owner in a
+ five-hundred-file container into "owns 100% of this". Below
+ :data:`_MIN_OWNERSHIP_COVERAGE` the sample is too thin to describe the box
+ at all, so ownership is omitted rather than reported small.
+
+ Bus factor is the *lowest* among the box's files rather than the mean —
+ one file only one person understands is the risk worth surfacing, and
+ averaging hides it.
+ """
+ hotspots = set(hotspot_paths)
+ dead = set(dead_paths)
+ layers = file_layers or {}
+ owners = file_owners or {}
+ bus_factors = file_bus_factors or {}
+
+ hot_by_box: dict[str, int] = defaultdict(int)
+ dead_by_box: dict[str, int] = defaultdict(int)
+ layers_by_box: dict[str, set[str]] = defaultdict(set)
+ owners_by_box: dict[str, Counter[str]] = defaultdict(Counter)
+ owned_files_by_box: dict[str, int] = defaultdict(int)
+ files_by_box: dict[str, int] = defaultdict(int)
+ bus_by_box: dict[str, int] = {}
+ boxes: set[str] = set()
+
+ for path, box in file_to_box.items():
+ boxes.add(box)
+ files_by_box[box] += 1
+ if path in hotspots:
+ hot_by_box[box] += 1
+ if path in dead:
+ dead_by_box[box] += 1
+ layer = layers.get(path)
+ if layer:
+ layers_by_box[box].add(layer)
+ owner = owners.get(path)
+ if owner:
+ owners_by_box[box][owner] += 1
+ owned_files_by_box[box] += 1
+ bus = bus_factors.get(path)
+ if bus is not None:
+ current = bus_by_box.get(box)
+ bus_by_box[box] = bus if current is None else min(current, bus)
+
+ out: dict[str, BoxSignals] = {}
+ for box in boxes:
+ owner_name: str | None = None
+ owner_pct: float | None = None
+ counts = owners_by_box.get(box)
+ total = files_by_box[box]
+ attributed = owned_files_by_box[box]
+ if counts and total and attributed / total >= _MIN_OWNERSHIP_COVERAGE:
+ # Ties broken by name so a re-export of an unchanged repo produces
+ # an unchanged file.
+ owner_name, owned = max(counts.items(), key=lambda kv: (kv[1], kv[0]))
+ owner_pct = round(100.0 * owned / total, 1)
+ out[box] = BoxSignals(
+ hotspot_count=hot_by_box[box] if churn_measured else None,
+ dead_count=dead_by_box[box],
+ layers=tuple(sorted(layers_by_box.get(box, ()))),
+ primary_owner=owner_name,
+ primary_owner_pct=owner_pct,
+ min_bus_factor=bus_by_box.get(box),
+ )
+ return out
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/__init__.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/__init__.py
new file mode 100644
index 000000000..972d3535c
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/__init__.py
@@ -0,0 +1,331 @@
+"""Emit a Structurizr DSL model from an indexed repository.
+
+One entry point, :func:`to_dsl`, which takes the already-built
+:class:`~..models.C4Model` dataclass and returns text. Nothing below this
+module touches a database — that is what keeps the emitter unit-testable
+without infrastructure, and what keeps emission itself close to free.
+
+Two shapes come out of here:
+
+* **A model fragment** (the default). Just the contents of ``model { … }``,
+ meant to be ``!include``d from the user's own ``workspace.dsl`` where their
+ views, styles and docs live. We own the model, they own the presentation,
+ and regenerating can never clobber hand-written work.
+* **A standalone workspace** (``standalone=True``), for someone who has
+ nothing yet: the same model wrapped in a ``workspace`` block with default
+ views so the file opens and renders on its own.
+
+Identifiers are flat and globally unique, so the fragment resolves inside any
+host workspace without that workspace having to opt into a particular
+identifier mode.
+"""
+
+from __future__ import annotations
+
+from ..models import C4Model
+from .elements import write_container, write_external, write_person
+from .identifiers import identifiers_for
+from .relationships import write_relationships
+from .views import write_views
+from .writer import Writer, quote
+
+__all__ = ["system_identifier", "to_dsl"]
+
+#: Name of the file we tell users to include. Referenced in the header
+#: comment so the file explains itself when it arrives without the terminal
+#: output that produced it.
+DEFAULT_FILENAME = "repowise-model.dsl"
+
+
+def _reference_map(model: C4Model, *, include_components: bool) -> dict[str, str]:
+ """Map every node id to the identifier used to declare and refer to it.
+
+ Identifiers are **flat and globally unique**, which is the DSL's default
+ mode. The alternative, ``!identifiers hierarchical``, gives shorter
+ component names but makes every reference a dotted path that only resolves
+ when the *host* workspace has turned that mode on — and the whole point of
+ shipping a fragment is that it drops into a workspace the user already
+ owns without them changing anything in it. Uniqueness is handled by
+ :func:`~.identifiers.identifiers_for` instead, so nothing is lost but
+ brevity.
+ """
+ # The system's own id is ``sys:<repository uuid>``, which is stable for one
+ # machine and different on every other one — two people exporting the same
+ # repo would get files that differ in every reference. Key it on the repo
+ # name instead, which is the same everywhere. It still goes through the
+ # same allocator, so a name that clashes with something else is handled.
+ system_key = f"sys:{model.system.name}"
+ raw_ids = (
+ [system_key]
+ + [p.id for p in model.people]
+ + [e.id for e in model.external_systems]
+ + [c.id for c in model.containers]
+ )
+ if include_components:
+ raw_ids += [
+ component.id
+ for container in model.containers
+ for component in model.components_by_container.get(container.id, [])
+ ]
+ references = identifiers_for(raw_ids)
+ references[model.system.id] = references.pop(system_key)
+ return references
+
+
+def _disambiguate(items: list, label_of, fallback_of) -> dict[str, str]:
+ """Map each item's id to a name unique within *items*.
+
+ Every member of a colliding group falls back, not just the ones after the
+ first, so which item keeps the short name cannot depend on ordering. The
+ fallback is expected to be unique by construction — a package name, a repo
+ path — so one pass settles it.
+ """
+ counts: dict[str, int] = {}
+ for item in items:
+ counts[label_of(item)] = counts.get(label_of(item), 0) + 1
+ return {
+ item.id: (fallback_of(item) if counts[label_of(item)] > 1 else label_of(item))
+ for item in items
+ }
+
+
+def _display_names(model: C4Model, externals: list) -> dict[str, str]:
+ """Element names, made unique within each scope that requires it.
+
+ Structurizr enforces uniqueness per parent: two top-level elements, two
+ containers in one software system, or two components in one container may
+ not share a name. Our names are not unique in any of those scopes:
+
+ * ``react``, ``@xyflow/react`` and ``@radix-ui/react-dialog`` all present
+ as "React", so they fall back to the package name.
+ * A container is named for its leaf directory, so ``apps/api`` and
+ ``services/api`` both present as "api"; they fall back to the path.
+ * ``src`` and ``lib`` are both pass-through directories, so
+ ``packages/ui/src/health`` and ``packages/ui/lib/health`` both present as
+ "health"; they fall back to the path within their container.
+
+ Components are disambiguated per container, not globally — the same name in
+ two different containers is legal, and widening it would churn names and
+ read worse for no gain.
+ """
+ names: dict[str, str] = {model.system.id: model.system.name}
+ for person in model.people:
+ names[person.id] = person.name
+ names.update(
+ _disambiguate(
+ externals,
+ lambda e: e.display_name or e.name,
+ lambda e: e.name,
+ )
+ )
+
+ # The repository's own name is a top-level element too, so an external
+ # sharing it would collide just as loudly.
+ taken: dict[str, int] = {}
+ for label in names.values():
+ taken[label] = taken.get(label, 0) + 1
+ if taken.get(model.system.name, 0) > 1:
+ for external in externals:
+ if names[external.id] == model.system.name:
+ names[external.id] = f"{external.name} ({external.ecosystem or 'external'})"
+
+ names.update(_disambiguate(list(model.containers), lambda c: c.name, lambda c: c.path))
+ for container in model.containers:
+ components = model.components_by_container.get(container.id, [])
+ names.update(
+ _disambiguate(
+ list(components),
+ lambda c: c.name,
+ lambda c, prefix=f"{container.path}/": (
+ c.path[len(prefix) :] if c.path.startswith(prefix) else c.path
+ ),
+ )
+ )
+ return names
+
+
+def system_identifier(model: C4Model, *, include_components: bool = False) -> str:
+ """The identifier the emitted system is declared under.
+
+ Exposed so callers can print a view snippet the user can paste verbatim
+ instead of one with a placeholder to fill in.
+ """
+ return _reference_map(model, include_components=include_components)[model.system.id]
+
+
+def _write_header(writer: Writer, model: C4Model, *, standalone: bool) -> None:
+ """The comment block a person reads first, in their editor or a diff.
+
+ Deliberately carries no timestamp: a timestamp makes every regeneration a
+ diff, which destroys the "commit it and watch it change meaningfully"
+ workflow this file exists for.
+ """
+ writer.comment(f"Structurizr DSL model for {model.system.name}, generated by Repowise.")
+ writer.comment()
+ writer.comment("Regenerating overwrites this file — do not hand-edit it.")
+ if not standalone:
+ writer.comment("It holds the model only; your views, styles and docs stay in")
+ writer.comment("your own workspace.dsl. Include it from inside the workspace")
+ writer.comment("block — the parser rejects an include that sits outside one:")
+ writer.comment()
+ writer.comment(' workspace "your name" {')
+ writer.comment(f" !include {DEFAULT_FILENAME}")
+ writer.comment()
+ writer.comment(" views {")
+ writer.comment(" ...")
+ writer.comment(" }")
+ writer.comment(" }")
+ writer.comment()
+
+
+def _write_tour(writer: Writer, model: C4Model) -> None:
+ """The curated reading order, as a comment.
+
+ Structurizr has no concept of a guided tour and there is no honest way to
+ force one into a view, but the order is one of the few things in this file
+ a person could not have derived themselves — so it goes at the top where
+ it is read, rather than being dropped.
+ """
+ if not model.tour:
+ return
+ writer.comment("Suggested reading order:")
+ for step in model.tour:
+ location = f" — {step.target_path}" if step.target_path else ""
+ writer.comment(f" {step.order}. {step.title}{location}")
+ detail = step.reason or step.description
+ if detail:
+ writer.comment(f" {' '.join(detail.split())}")
+ writer.comment()
+
+
+def _choose_relations(model: C4Model, *, include_components: bool) -> list:
+ """The relations to emit, with everything Structurizr derives left out.
+
+ Actor edges come first and unconditionally: they belong to no level's box
+ graph, and a person nothing points at is dropped from the context view
+ rather than drawn unconnected.
+
+ With components on, Structurizr derives a container-level relationship from
+ any component-level one that crosses a boundary. The derivation walks up
+ *both* ends' parents, so it applies to an edge leaving our system too: a
+ component pointing at an external implies its container pointing there.
+ Emitting ours as well is a duplicate the parser rejects outright.
+
+ So a container relation survives only when nothing derives it — when
+ neither end has a component carrying the same pair. That keeps an external
+ reached solely at container level connected, without duplicating one the
+ components already reach.
+ """
+ if not include_components:
+ return list(model.actor_relations) + list(model.container_relations)
+
+ container_of: dict[str, str] = {
+ component.id: container_id
+ for container_id, components in model.components_by_container.items()
+ for component in components
+ }
+
+ def _box(node_id: str) -> str:
+ """The container level of a box: a component maps up to its parent."""
+ return container_of.get(node_id, node_id)
+
+ derived = {(_box(r.source_id), _box(r.target_id)) for r in model.component_relations}
+ return (
+ list(model.actor_relations)
+ + list(model.component_relations)
+ + [r for r in model.container_relations if (r.source_id, r.target_id) not in derived]
+ )
+
+
+def to_dsl(
+ model: C4Model,
+ *,
+ standalone: bool = False,
+ include_components: bool = False,
+ include_externals: bool = True,
+ include_metadata: bool = True,
+) -> str:
+ """Render *model* as Structurizr DSL.
+
+ ``include_components`` is off by default. In a hand-curated Structurizr
+ model a component is a grouping somebody chose; ours is a directory, and
+ the architects most likely to want this export are exactly the readers who
+ would notice the difference.
+
+ ``include_metadata`` carries the health, ownership and layer tags. On by
+ default because it is the part no other tool ships; turn it off for a
+ plain C4 model.
+ """
+ writer = Writer()
+ _write_header(writer, model, standalone=standalone)
+ if include_metadata:
+ _write_tour(writer, model)
+
+ externals = list(model.external_systems) if include_externals else []
+ references = _reference_map(model, include_components=include_components)
+ names = _display_names(model, externals)
+ if not include_externals:
+ for external in model.external_systems:
+ references.pop(external.id, None)
+
+ relations = _choose_relations(model, include_components=include_components)
+
+ def write_model_body() -> None:
+ for person in sorted(model.people, key=lambda p: p.name):
+ write_person(writer, person, references[person.id], names[person.id])
+ if model.people:
+ writer.blank()
+
+ system_header = (
+ f"{references[model.system.id]} = softwareSystem {quote(names[model.system.id])}"
+ )
+ if model.system.description:
+ system_header += f" {quote(model.system.description)}"
+ with writer.block(system_header):
+ for index, container in enumerate(sorted(model.containers, key=lambda c: c.path)):
+ if index:
+ writer.blank()
+ components = (
+ sorted(
+ model.components_by_container.get(container.id, []),
+ key=lambda c: c.path,
+ )
+ if include_components
+ else []
+ )
+ write_container(
+ writer,
+ container,
+ references[container.id],
+ components,
+ {c.id: references[c.id] for c in components},
+ model.box_signals if include_metadata else None,
+ names,
+ )
+
+ if externals:
+ writer.blank()
+ for external in sorted(externals, key=lambda e: e.name):
+ write_external(writer, external, references[external.id], names[external.id])
+
+ writer.blank()
+ writer.comment("Relationships")
+ write_relationships(writer, relations, references)
+
+ if not standalone:
+ with writer.block("model"):
+ write_model_body()
+ return writer.render()
+
+ with writer.block(f"workspace {quote(model.system.name)}"):
+ with writer.block("model"):
+ write_model_body()
+ writer.blank()
+ write_views(
+ writer,
+ model,
+ references,
+ include_components=include_components,
+ include_layer_views=include_metadata,
+ )
+ return writer.render()
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/elements.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/elements.py
new file mode 100644
index 000000000..3efc8dcff
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/elements.py
@@ -0,0 +1,134 @@
+"""Emit the ``person`` / ``softwareSystem`` / ``container`` / ``component`` blocks.
+
+Descriptions come from what the index already knows — file and symbol counts,
+the dominant language, the dependency's ecosystem. Nothing here invents prose
+or calls a model: a wrong description in someone's committed architecture file
+is worse than a plain one.
+
+Structurizr tags every element with its own type (``Container``, ``Component``
+…), so those are not repeated here. ``External`` is the exception: it is a
+convention rather than something the parser adds, and it is what a user's
+existing styles will already key on.
+"""
+
+from __future__ import annotations
+
+from ..models import BoxSignals, Component, Container, ExternalSystemView, Person
+from .metadata import properties_for, tags_for, write_metadata
+from .writer import Writer, quote
+
+
+def _plural(count: int, noun: str) -> str:
+ return f"{count} {noun}" if count == 1 else f"{count} {noun}s"
+
+
+def _size_description(file_count: int, symbol_count: int) -> str:
+ parts = [_plural(file_count, "file")]
+ if symbol_count:
+ parts.append(_plural(symbol_count, "symbol"))
+ return ", ".join(parts)
+
+
+def container_description(container: Container) -> str:
+ return _size_description(container.file_count, container.symbol_count)
+
+
+def component_description(component: Component) -> str:
+ return _size_description(component.file_count, component.symbol_count)
+
+
+def external_description(external: ExternalSystemView) -> str:
+ """Ecosystem and version, when the manifest gave us them."""
+ parts = [external.category, external.ecosystem, external.version]
+ return " · ".join(p for p in parts if p)
+
+
+def write_person(writer: Writer, person: Person, identifier: str, name: str | None = None) -> None:
+ writer.line(f"{identifier} = person {quote(name or person.name)} {quote(person.description)}")
+
+
+def write_external(
+ writer: Writer,
+ external: ExternalSystemView,
+ identifier: str,
+ name: str | None = None,
+) -> None:
+ """One external dependency.
+
+ *name* is resolved by the caller, which is the only place that can see
+ whether two packages present under the same display name.
+ """
+ header = (
+ f"{identifier} = softwareSystem {quote(name or external.display_name or external.name)} "
+ f"{quote(external_description(external))}"
+ )
+ with writer.block(header):
+ writer.line('tags "External"')
+
+
+def write_container(
+ writer: Writer,
+ container: Container,
+ identifier: str,
+ components: list[Component],
+ component_identifiers: dict[str, str],
+ signals: dict[str, BoxSignals] | None = None,
+ names: dict[str, str] | None = None,
+) -> None:
+ """One ``container`` block, with its components nested inside it.
+
+ A container with nothing to nest and nothing to say is written as a
+ one-line element rather than an empty block — the shape a person would
+ write by hand.
+
+ *names* is resolved by the caller, which is the only place that can see
+ whether two containers, or two components inside this one, present under
+ the same name.
+ """
+ signals = signals or {}
+ names = names or {}
+ header = (
+ f"{identifier} = container {quote(names.get(container.id, container.name))} "
+ f"{quote(container_description(container))}"
+ )
+ if container.language:
+ header += f" {quote(container.language)}"
+
+ nested = [c for c in components if c.id in component_identifiers]
+ own_metadata = _has_metadata(signals.get(container.id))
+ if not nested and not own_metadata:
+ writer.line(header)
+ return
+
+ with writer.block(header):
+ write_metadata(writer, signals.get(container.id))
+ for component in nested:
+ write_component(
+ writer,
+ component,
+ component_identifiers[component.id],
+ signals.get(component.id),
+ names.get(component.id),
+ )
+
+
+def write_component(
+ writer: Writer,
+ component: Component,
+ identifier: str,
+ signals: BoxSignals | None = None,
+ name: str | None = None,
+) -> None:
+ header = (
+ f"{identifier} = component {quote(name or component.name)} "
+ f"{quote(component_description(component))}"
+ )
+ if not _has_metadata(signals):
+ writer.line(header)
+ return
+ with writer.block(header):
+ write_metadata(writer, signals)
+
+
+def _has_metadata(signals: BoxSignals | None) -> bool:
+ return bool(signals is not None and (tags_for(signals) or properties_for(signals)))
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/identifiers.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/identifiers.py
new file mode 100644
index 000000000..d2dfa78fa
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/identifiers.py
@@ -0,0 +1,83 @@
+"""Turn our node ids into Structurizr identifiers, stably.
+
+Structurizr identifiers are ``[a-zA-Z_0-9]`` only, while ours are shaped like
+``pkg:packages/core`` and ``cmp:packages/core/ingestion``. Sanitising is easy;
+staying stable is the hard part, and it is the requirement that matters —
+people commit the emitted file and read its diff, so an identifier that moves
+between runs makes a correct model look broken.
+
+Two rules give that:
+
+* **Collisions are resolved from the id, never from iteration order.** When
+ two different ids sanitise to the same string, *both* get a suffix derived
+ from a hash of the full original id. Numbering them "1" and "2" in the order
+ they happened to be visited means adding an unrelated file can renumber
+ them, which is exactly the churn we are avoiding.
+* **The whole scope is mapped at once.** :func:`identifiers_for` takes every
+ id in a scope and returns the complete mapping, so whether an id collides
+ cannot depend on when it was asked for.
+
+Pure: knows nothing about C4, the database, or Structurizr's grammar beyond
+the character set. Kept that way so it is reusable if we ever emit a second
+format.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+from collections import defaultdict
+from collections.abc import Iterable
+
+_UNSAFE = re.compile(r"[^a-zA-Z0-9_]+")
+
+#: Hex digits of id hash appended to a colliding identifier. Six keeps the
+#: identifier readable while making an accidental second collision remote.
+_SUFFIX_LEN = 6
+
+#: Prepended when sanitising leaves something that cannot open an identifier.
+_LEADING_PAD = "id_"
+
+
+def sanitize(raw: str) -> str:
+ """Reduce *raw* to Structurizr's identifier character set.
+
+ Lossy and deliberately not injective — ``API Gateway``, ``api/gateway``
+ and ``API-Gateway`` all land on the same string. :func:`identifiers_for`
+ is what makes the result unique; do not use this alone.
+ """
+ cleaned = _UNSAFE.sub("_", raw).strip("_")
+ if not cleaned:
+ return _LEADING_PAD.rstrip("_")
+ if cleaned[0].isdigit():
+ return _LEADING_PAD + cleaned
+ return cleaned
+
+
+def _disambiguator(raw: str) -> str:
+ """A short, stable suffix derived from the whole original id."""
+ return hashlib.sha256(raw.encode("utf-8")).hexdigest()[:_SUFFIX_LEN]
+
+
+def identifiers_for(raw_ids: Iterable[str]) -> dict[str, str]:
+ """Map every id in one scope to a unique Structurizr identifier.
+
+ The result depends only on the *set* of ids, so re-running on an unchanged
+ model produces an unchanged file, and adding one element never renames
+ another.
+ """
+ unique = sorted(set(raw_ids))
+ by_slug: dict[str, list[str]] = defaultdict(list)
+ for raw in unique:
+ by_slug[sanitize(raw)].append(raw)
+
+ out: dict[str, str] = {}
+ for slug, owners in by_slug.items():
+ if len(owners) == 1:
+ out[owners[0]] = slug
+ continue
+ # Every owner is suffixed, not just the ones after the first: which id
+ # "wins" the bare slug would otherwise depend on ordering.
+ for raw in owners:
+ out[raw] = f"{slug}_{_disambiguator(raw)}"
+ return out
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/metadata.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/metadata.py
new file mode 100644
index 000000000..428e9e67c
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/metadata.py
@@ -0,0 +1,108 @@
+"""Health, ownership and layer membership as tags and properties.
+
+This is the half of the export that is ours. Containers are package manifests
+and components are directories — any tool can produce those. What no other
+tool has is which files churn, who owns them, and which curated layer they sit
+in, and C4 has no vocabulary for any of it.
+
+Tags are the escape hatch. A user writes one filtered view per layer, or
+colours hotspots red, using their own styles against tags we merely emit. We
+neither build nor maintain the views; we supply the vocabulary.
+
+Two rules:
+
+* **Namespace every property key** (``repowise.*``) so it can never collide
+ with something the user set themselves.
+* **Omit what is unknown.** Health data is sparse. A missing bus factor
+ emitted as ``0`` reads as "nobody owns this", which is a different and much
+ more alarming claim than "we do not know".
+"""
+
+from __future__ import annotations
+
+from ..models import BoxSignals
+from .writer import Writer, quote
+
+#: Prefix on every property key we emit.
+_NAMESPACE = "repowise"
+
+#: Prefix on a layer tag, so a layer called "Tight" cannot be mistaken for the
+#: coupling tag of the same name.
+_LAYER_TAG_PREFIX = "Layer: "
+
+
+def layer_tag(name: str) -> str:
+ """The tag text a layer is emitted under.
+
+ Shared with the view filter in :mod:`.views`: a filter that selects on a
+ string the element was never tagged with parses fine and then matches
+ nothing, which is harder to spot than a parse error. One function means
+ they cannot drift.
+ """
+ return f"{_LAYER_TAG_PREFIX}{name}"
+
+
+def tags_for(signals: BoxSignals | None) -> list[str]:
+ """Tags for one box, in a stable order.
+
+ ``Hotspot`` and ``Dead`` are deliberately coarse: the count is available
+ as a property for anyone who wants it, but a style rule wants a yes/no.
+ """
+ if signals is None:
+ return []
+ tags: list[str] = []
+ if signals.hotspot_count:
+ tags.append("Hotspot")
+ if signals.dead_count:
+ tags.append("Dead")
+ tags.extend(layer_tag(name) for name in signals.layers)
+ return tags
+
+
+def properties_for(signals: BoxSignals | None) -> dict[str, str]:
+ """Namespaced properties for one box. Values are strings; DSL has no types.
+
+ A count of zero is emitted — we counted, and zero is the answer. A count we
+ never took is omitted: a repo with no churn data at all would otherwise
+ read as a repo with no hotspots, which is the clean bill of health the
+ omit-what-is-unknown rule exists to prevent.
+ """
+ if signals is None:
+ return {}
+ properties: dict[str, str] = {f"{_NAMESPACE}.deadFiles": str(signals.dead_count)}
+ if signals.hotspot_count is not None:
+ properties[f"{_NAMESPACE}.hotspots"] = str(signals.hotspot_count)
+ if signals.primary_owner:
+ properties[f"{_NAMESPACE}.owner"] = signals.primary_owner
+ if signals.primary_owner_pct is not None:
+ properties[f"{_NAMESPACE}.ownerPct"] = f"{signals.primary_owner_pct:g}"
+ if signals.min_bus_factor is not None:
+ properties[f"{_NAMESPACE}.minBusFactor"] = str(signals.min_bus_factor)
+ if signals.layers:
+ properties[f"{_NAMESPACE}.layers"] = ", ".join(signals.layers)
+ return properties
+
+
+def write_metadata(
+ writer: Writer,
+ signals: BoxSignals | None,
+ *,
+ extra_tags: list[str] | None = None,
+) -> bool:
+ """Write the ``tags`` line and ``properties`` block. True if anything was.
+
+ Callers use the return value to decide between a one-line element and a
+ block, so an element with nothing to say does not get an empty body.
+ """
+ tags = (extra_tags or []) + tags_for(signals)
+ properties = properties_for(signals)
+ if not tags and not properties:
+ return False
+
+ if tags:
+ writer.line("tags " + " ".join(quote(tag) for tag in tags))
+ if properties:
+ with writer.block("properties"):
+ for key in sorted(properties):
+ writer.line(f"{quote(key)} {quote(properties[key])}")
+ return True
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/relationships.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/relationships.py
new file mode 100644
index 000000000..b21a7986d
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/relationships.py
@@ -0,0 +1,62 @@
+"""Emit the ``source -> destination`` lines.
+
+The description is the verb the label pass already derived (``imports``,
+``calls``, ``co-changes``…), and the coupling bucket rides along as a tag so a
+user can style or filter by it — Structurizr has no vocabulary for "how hard
+is this edge", but its tags do not care what a tag means.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from ..models import Relation
+from .writer import Writer, quote
+
+#: Coupling bucket → tag. Capitalised to match Structurizr's tag convention
+#: and to read as a proper noun in a style rule.
+_COUPLING_TAGS: dict[str, str] = {
+ "loose": "Loose",
+ "moderate": "Moderate",
+ "tight": "Tight",
+}
+
+
+def write_relationships(
+ writer: Writer,
+ relations: Iterable[Relation],
+ identifiers: dict[str, str],
+) -> int:
+ """Write every relation whose endpoints are both in *identifiers*.
+
+ Returns the number written. Relations pointing at something we did not
+ emit — a component when components are switched off, say — are skipped
+ rather than emitted as a dangling reference the parser would reject.
+
+ Ordering is by the rendered identifiers, so the block diffs cleanly
+ regardless of the order relations were aggregated in.
+ """
+ emitted: list[tuple[str, str, Relation]] = []
+ for relation in relations:
+ source = identifiers.get(relation.source_id)
+ target = identifiers.get(relation.target_id)
+ if source is None or target is None:
+ continue
+ emitted.append((source, target, relation))
+
+ # Coupling is part of the key: two relations alike in every other respect
+ # emit different bodies, so leaving it out let their order fall back to
+ # however the caller happened to build the list.
+ emitted.sort(key=lambda row: (row[0], row[1], row[2].label or "", row[2].coupling or ""))
+ for source, target, relation in emitted:
+ header = f"{source} -> {target} {quote(relation.label or 'depends on')}"
+ tag = _COUPLING_TAGS.get(relation.coupling)
+ if tag is None:
+ writer.line(header)
+ continue
+ # A block rather than the positional tag slot, which would need an
+ # empty technology string in front of it — we have nothing honest to
+ # put there for a code dependency.
+ with writer.block(header):
+ writer.line(f"tags {quote(tag)}")
+ return len(emitted)
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/views.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/views.py
new file mode 100644
index 000000000..617f71b88
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/views.py
@@ -0,0 +1,121 @@
+"""Default views and styles — standalone workspaces only.
+
+The fragment stays presentation-free on purpose: views, styles and docs are
+the user's, and regenerating our model must never touch them. These exist for
+the person who has no workspace yet and wants a picture from one command.
+"""
+
+from __future__ import annotations
+
+from ..models import C4Model
+from .identifiers import identifiers_for
+from .metadata import layer_tag
+from .writer import Writer, quote
+
+#: Above roughly this many boxes a Structurizr view stops being readable, so a
+#: component view is capped and says so in a comment. Silent truncation would
+#: read as "this is everything" when it is not.
+MAX_COMPONENTS_PER_VIEW = 20
+
+
+def _view_key(prefix: str, identifier: str) -> str:
+ return f"{prefix}_{identifier}"
+
+
+def write_views(
+ writer: Writer,
+ model: C4Model,
+ references: dict[str, str],
+ *,
+ include_components: bool,
+ include_layer_views: bool = True,
+) -> None:
+ """Write a ``views`` block: context, containers, and per-container components.
+
+ ``include_layer_views`` follows the caller's metadata flag. The layer views
+ filter on tags the metadata pass emits, so with metadata off they would
+ parse and then select nothing at all.
+ """
+ system_ref = references[model.system.id]
+ with writer.block("views"):
+ with writer.block(f"systemContext {system_ref} {quote('SystemContext')}"):
+ writer.line("include *")
+ writer.line("autolayout lr")
+
+ writer.blank()
+ with writer.block(f"container {system_ref} {quote('Containers')}"):
+ writer.line("include *")
+ writer.line("autolayout lr")
+
+ if include_components:
+ for container in sorted(model.containers, key=lambda c: c.path):
+ components = model.components_by_container.get(container.id, [])
+ if not components:
+ continue
+ writer.blank()
+ container_ref = references[container.id]
+ key = _view_key("components", container_ref)
+ with writer.block(f"component {container_ref} {quote(key)}"):
+ # Ranked by size: the biggest directories are the ones a
+ # reader is orienting by. Same order the model block uses
+ # for ties, so the file stays diff-stable.
+ ranked = sorted(components, key=lambda c: (-c.file_count, c.path))
+ if len(ranked) > MAX_COMPONENTS_PER_VIEW:
+ writer.comment(
+ f"Showing the {MAX_COMPONENTS_PER_VIEW} largest of "
+ f"{len(ranked)} components — a view this size stops "
+ f"being readable. Add the rest by hand if you need them."
+ )
+ for component in ranked[:MAX_COMPONENTS_PER_VIEW]:
+ writer.line(f"include {references[component.id]}")
+ else:
+ writer.line("include *")
+ writer.line("autolayout lr")
+
+ if include_layer_views:
+ _write_layer_views(writer, model, references)
+
+ writer.blank()
+ with writer.block("styles"):
+ with writer.block('element "External"'):
+ writer.line("background #999999")
+ writer.line("color #ffffff")
+ # The health colours. Tag styles are applied in declaration order,
+ # so Hotspot before Dead means a dead hotspot reads as dead — the
+ # more actionable of the two.
+ with writer.block('element "Hotspot"'):
+ writer.line("background #b5432f")
+ writer.line("color #ffffff")
+ with writer.block('element "Dead"'):
+ writer.line("background #6b6b6b")
+ writer.line("color #ffffff")
+ with writer.block('relationship "Tight"'):
+ writer.line("thickness 4")
+ with writer.block('relationship "Loose"'):
+ writer.line("style dashed")
+
+
+def _write_layer_views(writer: Writer, model: C4Model, references: dict[str, str]) -> None:
+ """One container view per curated layer, filtered by its tag.
+
+ This is the grouping that is ours rather than C4's, and a filtered view is
+ the only way it survives into someone else's toolchain.
+
+ Layer names are curated prose, so neither the key nor the filter can take
+ them as they are. Keys go through the same collision-safe allocator the
+ element identifiers use, because two names that reduce to one key is a
+ workspace Structurizr refuses. The filter goes through ``quote`` and is
+ built from :func:`layer_tag`, so it always spells the tag the elements
+ were actually given.
+ """
+ layers = sorted({layer for signals in model.box_signals.values() for layer in signals.layers})
+ if not layers:
+ return
+ system_ref = references[model.system.id]
+ keys = identifiers_for(layers)
+ for layer in layers:
+ writer.blank()
+ key = _view_key("layer", keys[layer])
+ with writer.block(f"container {system_ref} {quote(key)}"):
+ writer.line(f"include {quote(f'element.tag=={layer_tag(layer)}')}")
+ writer.line("autolayout lr")
diff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/writer.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/writer.py
new file mode 100644
index 000000000..f69036840
--- /dev/null
+++ b/packages/server/src/repowise/server/services/c4_builder/structurizr/writer.py
@@ -0,0 +1,79 @@
+"""Block and indentation bookkeeping for the emitted DSL.
+
+The emitted file is read by people in a diff, so it is laid out the way
+someone would write it by hand: four-space indents, one blank line between
+sibling blocks, no trailing whitespace. Pure string work — knows nothing about
+C4 or Structurizr beyond the brace-and-indent shape.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+from contextlib import contextmanager
+
+_INDENT = " " * 4
+
+
+class Writer:
+ """Accumulates indented lines, with nesting handled by a context manager."""
+
+ def __init__(self) -> None:
+ self._lines: list[str] = []
+ self._depth = 0
+
+ def line(self, text: str = "") -> None:
+ """Write one line at the current depth. Empty text writes a blank line.
+
+ Blank lines carry no indentation: trailing whitespace shows up in a
+ diff and in most editors' warnings, and means nothing here.
+ """
+ self._lines.append(f"{_INDENT * self._depth}{text}" if text else "")
+
+ def comment(self, text: str = "") -> None:
+ """Write a ``#`` comment, or a bare ``#`` for a spacer line.
+
+ Line breaks are folded to spaces first. A comment runs to the end of
+ the line, so a newline in the text puts everything after it into the
+ file as a bare token and the parser stops there. Much of what reaches
+ here is curated prose — a tour title, a repo name — and folding at the
+ one place that writes a ``#`` means no caller has to remember.
+
+ Only line breaks are touched. The header's include snippet is indented
+ so it can be pasted as written, and collapsing every run of whitespace
+ would flatten that too.
+ """
+ folded = " ".join(str(text).splitlines()).rstrip()
+ self.line(f"# {folded}" if folded else "#")
+
+ def blank(self) -> None:
+ """One blank line, collapsed if the previous line was already blank."""
+ if self._lines and self._lines[-1] == "":
+ return
+ self.line()
+
+ @contextmanager
+ def block(self, header: str) -> Iterator[None]:
+ """Open ``header {``, indent the body, close with ``}``."""
+ self.line(f"{header} {{")
+ self._depth += 1
+ try:
+ yield
+ finally:
+ self._depth -= 1
+ self.line("}")
+
+ def render(self) -> str:
+ """The finished document, newline-terminated."""
+ body = "\n".join(self._lines).rstrip("\n")
+ return f"{body}\n" if body else ""
+
+
+def quote(text: str) -> str:
+ """Quote a value for the DSL.
+
+ Structurizr string literals are double-quoted with no escape sequence, so
+ an embedded quote is replaced rather than escaped, and newlines are
+ flattened — a literal newline inside a quoted value is a parse error.
+ """
+ flattened = " ".join(str(text).split())
+ return '"' + flattened.replace('"', "'") + '"'
diff --git a/packages/types/__tests__/node-ids.test.ts b/packages/types/__tests__/node-ids.test.ts
new file mode 100644
index 000000000..424cf644c
--- /dev/null
+++ b/packages/types/__tests__/node-ids.test.ts
@@ -0,0 +1,126 @@
+/**
+ * Node-id helpers. These mirror the Python module, so the cases that matter
+ * are the ones that used to be got wrong by hand: hardcoded prefix lengths,
+ * and treating a Windows drive letter as a prefix.
+ */
+import { describe, it, expect } from "vitest";
+import {
+ displayLabel,
+ filePathOf,
+ isExternal,
+ nodeKind,
+ stripPrefix,
+ symbolNameOf,
+} from "../src/node-ids";
+import fixture from "../../../tests/fixtures/node_ids.json";
+
+describe("nodeKind", () => {
+ it("recognises the prefixes the backend emits", () => {
+ expect(nodeKind("external:react")).toBe("external");
+ expect(nodeKind("framework:typo3-core")).toBe("framework");
+ expect(nodeKind("pkg:packages/core")).toBe("pkg");
+ expect(nodeKind("cmp:packages/core/ingestion")).toBe("cmp");
+ expect(nodeKind("file:src/main.py")).toBe("file");
+ });
+
+ it("treats path::Symbol as a symbol", () => {
+ expect(nodeKind("src/main.py::main")).toBe("symbol");
+ });
+
+ it("treats an unknown prefix as a plain path", () => {
+ expect(nodeKind("src/main.py")).toBe("path");
+ expect(nodeKind("C:\\src\\main.py")).toBe("path");
+ expect(nodeKind("mailto:[email protected]")).toBe("path");
+ });
+});
+
+describe("stripPrefix", () => {
+ it("does not depend on the prefix's length", () => {
+ expect(stripPrefix("external:react")).toBe("react");
+ expect(stripPrefix("ext:react")).toBe("react");
+ expect(stripPrefix("pkg:packages/core")).toBe("packages/core");
+ });
+
+ it("leaves an unprefixed id alone", () => {
+ expect(stripPrefix("src/main.py")).toBe("src/main.py");
+ expect(stripPrefix("C:\\src\\main.py")).toBe("C:\\src\\main.py");
+ });
+
+ it("keeps colons that belong to the value", () => {
+ expect(stripPrefix("external:pub:http")).toBe("pub:http");
+ });
+});
+
+describe("filePathOf", () => {
+ it("resolves symbols to their file", () => {
+ expect(filePathOf("src/main.py::main")).toBe("src/main.py");
+ });
+
+ it("resolves file ids and bare paths to themselves", () => {
+ expect(filePathOf("file:src/main.py")).toBe("src/main.py");
+ expect(filePathOf("src/main.py")).toBe("src/main.py");
+ });
+
+ it("returns null for things that are not files", () => {
+ expect(filePathOf("external:react")).toBeNull();
+ expect(filePathOf("pkg:packages/core")).toBeNull();
+ });
+});
+
+describe("symbolNameOf", () => {
+ it("returns the name after the separator", () => {
+ expect(symbolNameOf("src/main.py::main")).toBe("main");
+ expect(symbolNameOf("src/main.py::Klass.method")).toBe("Klass.method");
+ });
+
+ it("returns null when there is no symbol", () => {
+ expect(symbolNameOf("src/main.py")).toBeNull();
+ });
+});
+
+describe("displayLabel", () => {
+ it("prefers the symbol name, then the basename", () => {
+ expect(displayLabel("src/main.py::main")).toBe("main");
+ expect(displayLabel("src/deep/main.py")).toBe("main.py");
+ expect(displayLabel("external:react")).toBe("react");
+ });
+});
+
+describe("isExternal", () => {
+ it("covers frameworks as well as third-party code", () => {
+ expect(isExternal("external:react")).toBe(true);
+ expect(isExternal("framework:typo3-core")).toBe(true);
+ expect(isExternal("src/main.py")).toBe(false);
+ expect(isExternal("pkg:packages/core")).toBe(false);
+ });
+});
+
+// ---------------------------------------------------------------------------
+// The shared fixture. Its Python half lives in tests/unit/test_ids.py and reads
+// the same file, so a rule that holds on one side and not the other fails a
+// build instead of surviving as a live bug in whichever surface is quieter.
+// ---------------------------------------------------------------------------
+
+const FIXTURE = fixture as {
+ cases: {
+ raw: string;
+ kind: string;
+ file_path: string | null;
+ symbol_name: string | null;
+ is_external: boolean;
+ }[];
+ display_labels: { raw: string; label: string }[];
+};
+
+describe("the shared fixture holds in TypeScript", () => {
+ it.each(FIXTURE.cases)("$raw", (item) => {
+ expect(nodeKind(item.raw)).toBe(item.kind);
+ expect(filePathOf(item.raw)).toBe(item.file_path);
+ expect(symbolNameOf(item.raw)).toBe(item.symbol_name);
+ expect(isExternal(item.raw)).toBe(item.is_external);
+ });
+
+ it.each(FIXTURE.display_labels)("label of $raw", (item) => {
+ expect(displayLabel(item.raw)).toBe(item.label);
+ });
+});
diff --git a/packages/types/src/index.ts b/packages/types/src/index.ts
index 44f756282..8d67d2384 100644
--- a/packages/types/src/index.ts
+++ b/packages/types/src/index.ts
@@ -7,6 +7,7 @@
* are also supported via the `exports` map in package.json.
*/
+export * from "./node-ids.js";
export * from "./pagination.js";
export * from "./graph.js";
export * from "./git.js";
diff --git a/packages/types/src/node-ids.ts b/packages/types/src/node-ids.ts
new file mode 100644
index 000000000..c9c04655c
--- /dev/null
+++ b/packages/types/src/node-ids.ts
@@ -0,0 +1,106 @@
+/**
+ * Node-id helpers, mirroring `packages/core/src/repowise/core/ids.py`.
+ *
+ * The backend sends node ids as prefixed strings (`external:react`,
+ * `pkg:packages/core`) or as `path::Symbol`. The UI had been taking them apart
+ * with ad-hoc `split("::")` and hardcoded slice lengths — `label.slice(9)` to
+ * drop `external:` is correct only until somebody renames the prefix.
+ *
+ * Keep this in step with the Python module; the two are small and the rules
+ * are the same:
+ *
+ * - The prefix is matched against a fixed table, and it is matched *first*.
+ * An unknown prefix is not a kind, so a Windows path stays a path.
+ * - `::` separates a file from a symbol, but only in an id with no prefix.
+ * Rust import resolution emits `external:serde::Deserialize`, where the
+ * separator is part of the crate path.
+ *
+ * `tests/fixtures/node_ids.json` holds cases both this module and the Python
+ * one are checked against, so a divergence fails a build rather than living
+ * on in whichever surface is quieter.
+ */
+
+/** Separator between a file path and a symbol name. */
+export const SYMBOL_SEP = "::";
+
+/**
+ * Marks the synthetic bucket of files sitting at a container's root, as in
+ * `cmp:packages/core#root`. Stripped from a label so the marker never reaches
+ * a reader.
+ */
+const ROOT_MARKER = "#root";
+
+const KNOWN_PREFIXES = [
+ "file",
+ "external",
+ "framework",
+ "sys",
+ "person",
+ "pkg",
+ "cmp",
+ "ext",
+] as const;
+
+export type NodeKind = (typeof KNOWN_PREFIXES)[number] | "symbol" | "path";
+
+function prefixOf(raw: string): string | null {
+ const colon = raw.indexOf(":");
+ if (colon < 0) return null;
+ const head = raw.slice(0, colon);
+ return (KNOWN_PREFIXES as readonly string[]).includes(head) ? head : null;
+}
+
+/** What kind of thing this id names. */
+export function nodeKind(raw: string): NodeKind {
+ const prefix = prefixOf(raw);
+ if (prefix !== null) return prefix as NodeKind;
+ return raw.includes(SYMBOL_SEP) ? "symbol" : "path";
+}
+
+/**
+ * The part after the prefix, or the id itself when there is no known prefix.
+ *
+ * Use instead of a hardcoded slice length: `stripPrefix("external:react")`
+ * is "react" and stays correct if the prefix ever changes length.
+ */
+export function stripPrefix(raw: string): string {
+ const prefix = prefixOf(raw);
+ return prefix === null ? raw : raw.slice(prefix.length + 1);
+}
+
+/**
+ * The file path an id refers to, or null when it names no file.
+ *
+ * A symbol resolves to the file holding it; a `file:`-prefixed KG id and a
+ * bare path both resolve to themselves.
+ */
+export function filePathOf(raw: string): string | null {
+ const prefix = prefixOf(raw);
+ if (prefix === "file") return raw.slice("file:".length);
+ if (prefix !== null) return null;
+ if (raw.includes(SYMBOL_SEP)) return raw.split(SYMBOL_SEP)[0] ?? null;
+ return raw;
+}
+
+/** The symbol name in a `path::Symbol` id, or null if it names no symbol. */
+export function symbolNameOf(raw: string): string | null {
+ if (nodeKind(raw) !== "symbol") return null;
+ const index = raw.indexOf(SYMBOL_SEP);
+ return index < 0 ? null : raw.slice(index + SYMBOL_SEP.length);
+}
+
+/** A short display label: the symbol name, or the file's basename. */
+export function displayLabel(raw: string): string {
+ const symbol = symbolNameOf(raw);
+ if (symbol) return symbol;
+ const path = filePathOf(raw);
+ if (path) return path.split("/").pop() || path;
+ const rest = stripPrefix(raw);
+ return rest.endsWith(ROOT_MARKER) ? rest.slice(0, -ROOT_MARKER.length) : rest;
+}
+
+/** True if the id names code we do not own (third-party or framework). */
+export function isExternal(raw: string): boolean {
+ const kind = nodeKind(raw);
+ return kind === "external" || kind === "framework";
+}
diff --git a/packages/ui/__tests__/c4/export-menu-structurizr.test.tsx b/packages/ui/__tests__/c4/export-menu-structurizr.test.tsx
new file mode 100644
index 000000000..15a59baab
--- /dev/null
+++ b/packages/ui/__tests__/c4/export-menu-structurizr.test.tsx
@@ -0,0 +1,116 @@
+/**
+ * The Structurizr entry in the C4 export menu.
+ *
+ * It downloads rather than copies: the DSL is a file people commit, and it
+ * carries a header comment that only survives as a file. The entry is hidden
+ * unless the host supplies a fetcher, matching how Mermaid and JSON behave.
+ */
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import { render, fireEvent, waitFor } from "@testing-library/react";
+import { C4ExportMenu } from "../../src/c4/export/ExportMenu";
+
+const DSL = '# Structurizr DSL model for demo\nmodel {\n sys_demo = softwareSystem "demo"\n}\n';
+
+let createdUrls: string[] = [];
+let lastBlob: Blob | null = null;
+
+beforeEach(() => {
+ createdUrls = [];
+ lastBlob = null;
+ // jsdom implements neither, and the exporter uses both to trigger a save.
+ globalThis.URL.createObjectURL = vi.fn((blob: Blob) => {
+ lastBlob = blob;
+ const url = `blob:mock/${createdUrls.length}`;
+ createdUrls.push(url);
+ return url;
+ }) as unknown as typeof URL.createObjectURL;
+ globalThis.URL.revokeObjectURL = vi.fn() as unknown as typeof URL.revokeObjectURL;
+});
+
+afterEach(() => {
+ vi.restoreAllMocks();
+});
+
+/** jsdom's Blob has no .text(), so read it the way a browser would. */
+function readBlob(blob: Blob): Promise<string> {
+ return new Promise((resolve, reject) => {
+ const reader = new FileReader();
+ reader.onload = () => resolve(String(reader.result));
+ reader.onerror = () => reject(reader.error);
+ reader.readAsText(blob);
+ });
+}
+
+function open(container: HTMLElement) {
+ fireEvent.click(container.querySelector("button")!);
+}
+
+function itemNamed(container: HTMLElement, label: string) {
+ return Array.from(container.querySelectorAll('[role="menuitem"]')).find(
+ (node) => node.textContent?.includes(label),
+ );
+}
+
+describe("C4ExportMenu — Structurizr DSL", () => {
+ it("hides the entry when the host provides no fetcher", () => {
+ const { container } = render(
+ <C4ExportMenu nodes={[]} edges={[]} fileNameStem="demo" />,
+ );
+ open(container);
+ expect(itemNamed(container, "Structurizr DSL")).toBeUndefined();
+ });
+
+ it("shows the entry when a fetcher is supplied", () => {
+ const { container } = render(
+ <C4ExportMenu
+ nodes={[]}
+ edges={[]}
+ fileNameStem="demo"
+ fetchStructurizr={async () => DSL}
+ />,
+ );
+ open(container);
+ expect(itemNamed(container, "Structurizr DSL")).toBeDefined();
+ });
+
+ it("downloads the DSL the host returns, unchanged", async () => {
+ const fetchStructurizr = vi.fn(async () => DSL);
+ const { container } = render(
+ <C4ExportMenu
+ nodes={[]}
+ edges={[]}
+ fileNameStem="demo"
+ fetchStructurizr={fetchStructurizr}
+ />,
+ );
+ open(container);
+ fireEvent.click(itemNamed(container, "Structurizr DSL")!);
+
+ await waitFor(() => expect(fetchStructurizr).toHaveBeenCalledTimes(1));
+ await waitFor(() => expect(createdUrls.length).toBe(1));
+ expect(lastBlob).not.toBeNull();
+ // The header comment is what tells a downloader what the file is, so the
+ // bytes have to arrive exactly as the backend wrote them.
+ await expect(readBlob(lastBlob!)).resolves.toBe(DSL);
+ });
+
+ it("reports a failure instead of failing silently", async () => {
+ const { container } = render(
+ <C4ExportMenu
+ nodes={[]}
+ edges={[]}
+ fileNameStem="demo"
+ fetchStructurizr={async () => {
+ throw new Error("nope");
+ }}
+ />,
+ );
+ open(container);
+ fireEvent.click(itemNamed(container, "Structurizr DSL")!);
+
+ await waitFor(() =>
+ expect(container.textContent).toContain("Export failed"),
+ );
+ expect(createdUrls.length).toBe(0);
+ });
+});
diff --git a/packages/ui/__tests__/dashboard/dependency-heatmap.test.tsx b/packages/ui/__tests__/dashboard/dependency-heatmap.test.tsx
new file mode 100644
index 000000000..bddb26592
--- /dev/null
+++ b/packages/ui/__tests__/dashboard/dependency-heatmap.test.tsx
@@ -0,0 +1,50 @@
+/**
+ * The heatmap's axis labels.
+ *
+ * Labels used to be cut with `slice(9)` — the length of `"external:"` spelled
+ * as a number — so any other prefix lost nine characters off the front of a
+ * real path. It routes through the shared helper now, and this pins that a
+ * module id we do own is not trimmed at all.
+ */
+import { describe, it, expect } from "vitest";
+import { render } from "@testing-library/react";
+import type { ModuleGraph } from "@repowise-dev/types/graph";
+import { DependencyHeatmap } from "../../src/dashboard/dependency-heatmap";
+
+function graphOf(moduleIds: string[]): ModuleGraph {
+ return {
+ nodes: moduleIds.map((module_id) => ({
+ module_id,
+ file_count: 1,
+ loc: 10,
+ language: "python",
+ })),
+ edges: moduleIds.slice(1).map((module_id) => ({
+ source: moduleIds[0]!,
+ target: module_id,
+ weight: 1,
+ })),
+ } as unknown as ModuleGraph;
+}
+
+describe("DependencyHeatmap labels", () => {
+ it("strips a dependency's prefix but not a real path", () => {
+ const { container } = render(
+ <DependencyHeatmap moduleGraph={graphOf(["packages/core", "external:react"])} />,
+ );
+ const text = container.textContent ?? "";
+ expect(text).toContain("react");
+ expect(text).not.toContain("external:");
+ // "packages/core" keeps its last segment whole — nine characters off the
+ // front would have left "s/core".
+ expect(text).toContain("core");
+ expect(text).not.toContain("s/core");
+ });
+
+ it("does not trim a short module id into nothing", () => {
+ const { container } = render(<DependencyHeatmap moduleGraph={graphOf(["api", "db"])} />);
+ const text = container.textContent ?? "";
+ expect(text).toContain("api");
+ expect(text).toContain("db");
+ });
+});
diff --git a/packages/ui/__tests__/graph/external-node-ids.test.ts b/packages/ui/__tests__/graph/external-node-ids.test.ts
new file mode 100644
index 000000000..638fee499
--- /dev/null
+++ b/packages/ui/__tests__/graph/external-node-ids.test.ts
@@ -0,0 +1,29 @@
+/**
+ * The UI's answer to "is this ours?" must match the backend's.
+ *
+ * These sites each tested `startsWith("external:")` by hand, which misses the
+ * `framework:` nodes the framework-edge pass synthesises. The backend excludes
+ * those from layers, callers and tours; the UI was still drawing them as one
+ * of the repository's own files, so the same node was described two ways
+ * depending on which surface you looked at.
+ */
+import { describe, it, expect } from "vitest";
+import { isExternalModuleId } from "../../src/graph/sigma/graphology-adapter";
+
+describe("isExternalModuleId", () => {
+ it("covers both spellings of code we do not own", () => {
+ expect(isExternalModuleId("external:react")).toBe(true);
+ expect(isExternalModuleId("framework:typo3-core")).toBe(true);
+ });
+
+ it("covers a crate whose name carries the symbol separator", () => {
+ // Rust import resolution builds the node id from the raw module path.
+ expect(isExternalModuleId("external:serde::Deserialize")).toBe(true);
+ });
+
+ it("leaves our own modules alone", () => {
+ expect(isExternalModuleId("packages/core")).toBe(false);
+ expect(isExternalModuleId("src/main.py")).toBe(false);
+ expect(isExternalModuleId("src/main.py::run")).toBe(false);
+ });
+});
diff --git a/packages/ui/src/c4/C4Diagram.tsx b/packages/ui/src/c4/C4Diagram.tsx
index be1098a22..51b6e17bc 100644
--- a/packages/ui/src/c4/C4Diagram.tsx
+++ b/packages/ui/src/c4/C4Diagram.tsx
@@ -73,6 +73,12 @@ export interface C4DiagramProps {
*/
fetchMermaid?: (() => Promise<string>) | undefined;
+ /**
+ * Host-provided Structurizr DSL fetcher. When supplied, the export menu
+ * offers "Structurizr DSL". Omit to hide.
+ */
+ fetchStructurizr?: (() => Promise<string>) | undefined;
+
onLevelChange: (level: C4Level) => void;
onDrillInto: (containerId: string) => void;
onDrillOut: () => void;
@@ -98,6 +104,7 @@ function C4DiagramInner({
docsPathSet,
renderInspector,
fetchMermaid,
+ fetchStructurizr,
onLevelChange,
onDrillInto,
onDrillOut,
@@ -188,6 +195,7 @@ function C4DiagramInner({
title={exportTitle(systemName, level, activeContainerPath)}
disabled={nodes.length === 0}
{...(fetchMermaid ? { fetchMermaid } : {})}
+ {...(fetchStructurizr ? { fetchStructurizr } : {})}
/>
</div>
</div>
diff --git a/packages/ui/src/c4/export/ExportMenu.tsx b/packages/ui/src/c4/export/ExportMenu.tsx
index c06097e54..26006442e 100644
--- a/packages/ui/src/c4/export/ExportMenu.tsx
+++ b/packages/ui/src/c4/export/ExportMenu.tsx
@@ -1,7 +1,8 @@
"use client";
/**
- * Toolbar dropdown to export the current C4 view as SVG, PNG, or Mermaid.
+ * Toolbar dropdown to export the current C4 view as SVG, PNG, Mermaid,
+ * Structurizr DSL, or JSON.
*
* SVG/PNG are built locally from the React Flow layout (svg-exporter +
* png-exporter). Mermaid is fetched from the host because the backend has
@@ -26,6 +27,14 @@ export interface C4ExportMenuProps {
title?: string;
/** Host-provided fetcher for the Mermaid source. Hidden if omitted. */
fetchMermaid?: () => Promise<string>;
+ /**
+ * Host-provided fetcher for the Structurizr DSL. Hidden if omitted.
+ *
+ * The file the host returns carries its own header comment explaining that
+ * it is a model fragment and how to include it, so someone who downloads it
+ * without reading any docs still knows what they have.
+ */
+ fetchStructurizr?: () => Promise<string>;
/** Disabled when the diagram is empty / still loading. */
disabled?: boolean;
/** Architecture view data for JSON export. JSON option hidden if omitted. */
@@ -44,6 +53,7 @@ export function C4ExportMenu({
fileNameStem,
title,
fetchMermaid,
+ fetchStructurizr,
disabled,
architectureView,
activeFilters,
@@ -103,6 +113,22 @@ export function C4ExportMenu({
setOpen(false);
}, [architectureView, activeFilters, activePersona, fileNameStem]);
+ const onStructurizr = useCallback(async () => {
+ if (!fetchStructurizr) return;
+ setStatus("working");
+ try {
+ const text = await fetchStructurizr();
+ triggerDownload(
+ new Blob([text], { type: "text/plain;charset=utf-8" }),
+ "repowise-model.dsl",
+ );
+ setStatus("idle");
+ setOpen(false);
+ } catch {
+ setStatus("error");
+ }
+ }, [fetchStructurizr]);
+
const onMermaidDownload = useCallback(async () => {
if (!fetchMermaid) return;
setStatus("working");
@@ -176,6 +202,16 @@ export function C4ExportMenu({
/>
</>
)}
+ {fetchStructurizr && (
+ <>
+ <Divider />
+ <MenuItem
+ icon={<FileType2 size={12} />}
+ label="Structurizr DSL"
+ onClick={onStructurizr}
+ />
+ </>
+ )}
{architectureView && activeFilters && activePersona && (
<>
<Divider />
diff --git a/packages/ui/src/dashboard/dependency-heatmap.tsx b/packages/ui/src/dashboard/dependency-heatmap.tsx
index 03a157c34..78f83f08e 100644
--- a/packages/ui/src/dashboard/dependency-heatmap.tsx
+++ b/packages/ui/src/dashboard/dependency-heatmap.tsx
@@ -4,6 +4,7 @@ import { useMemo, useState, useCallback, Fragment } from "react";
import { Grid3X3 } from "lucide-react";
import { EmptyState } from "../shared/empty-state";
import type { ModuleGraph } from "@repowise-dev/types/graph";
+import { stripPrefix } from "@repowise-dev/types";
interface DependencyHeatmapProps {
moduleGraph: ModuleGraph;
@@ -18,8 +19,9 @@ function heatColor(count: number, max: number): string {
}
function displayLabel(moduleId: string): string {
- let label = moduleId;
- if (label.startsWith("external:")) label = label.slice(9);
+ // stripPrefix rather than a hardcoded slice length: "external:".length was
+ // spelled as 9 here, which is right until a prefix is renamed.
+ const label = stripPrefix(moduleId);
const last = label.split("/").pop() ?? label;
return last.length > 14 ? last.slice(0, 13) + "…" : last;
}
diff --git a/packages/ui/src/files/file-graph-tab.tsx b/packages/ui/src/files/file-graph-tab.tsx
index 2b53c35f4..d2d9bd459 100644
--- a/packages/ui/src/files/file-graph-tab.tsx
+++ b/packages/ui/src/files/file-graph-tab.tsx
@@ -4,6 +4,7 @@ import { Card, CardContent, CardHeader, CardTitle } from "../ui/card";
import { StatGrid, StatTile } from "../shared/stat-grid";
import { truncatePath } from "../lib/format";
import type { FileDetailGraph, FileGraphNeighbor } from "@repowise-dev/types/files";
+import { isExternal, nodeKind } from "@repowise-dev/types";
interface FileGraphTabProps {
graph: FileDetailGraph | null;
@@ -42,16 +43,16 @@ function NeighborList({
) : (
<ul className="space-y-2">
{neighbors.map((n) => {
- const isExternal = n.node_id.startsWith("external:");
- const isSymbol = !isExternal && (n.node_type === "symbol" || n.node_id.includes("::"));
+ const isExternalNode = isExternal(n.node_id);
+ const isSymbol = !isExternalNode && nodeKind(n.node_id) === "symbol";
const href = isSymbol ? symbolHref(n.node_id) : fileHref(n.node_id);
const row = (
<>
<span
className={`font-mono text-xs truncate flex-1 min-w-0 ${
- isExternal ? "text-[var(--color-text-tertiary)]" : "text-[var(--color-text-primary)]"
+ isExternalNode ? "text-[var(--color-text-tertiary)]" : "text-[var(--color-text-primary)]"
}`}
- title={isExternal ? `${n.node_id} (external dependency, not part of this repo)` : n.node_id}
+ title={isExternalNode ? `${n.node_id} (external dependency, not part of this repo)` : n.node_id}
>
{truncatePath(n.node_id, 48)}
</span>
@@ -62,7 +63,7 @@ function NeighborList({
);
return (
<li key={`${n.node_id}-${n.edge_type}`}>
- {isExternal ? (
+ {isExternalNode ? (
<div className="flex items-center gap-2 -mx-2 px-2 py-1 rounded">{row}</div>
) : (
<a
diff --git a/packages/ui/src/files/file-overview-tab.tsx b/packages/ui/src/files/file-overview-tab.tsx
index 34664a017..49e8970b0 100644
--- a/packages/ui/src/files/file-overview-tab.tsx
+++ b/packages/ui/src/files/file-overview-tab.tsx
@@ -1,5 +1,6 @@
import { ArrowRight, Bug, Code2, Network } from "lucide-react";
import type { FileDetailResponse } from "@repowise-dev/types/files";
+import { isExternal, nodeKind } from "@repowise-dev/types";
import { Card, CardContent, CardHeader, CardTitle } from "../ui/card";
import { Badge } from "../ui/badge";
import { StatGrid, StatTile } from "../shared/stat-grid";
@@ -148,9 +149,9 @@ export function FileOverviewTab({ data, symbolHref, fileHref }: FileOverviewTabP
Dependencies ({data.graph.out_degree})
</p>
{data.graph.dependencies.slice(0, 5).map((n) => {
- const isExternal = n.node_id.startsWith("external:");
- const isSymbol = !isExternal && (n.node_type === "symbol" || n.node_id.includes("::"));
- if (isExternal) {
+ const isExternalNode = isExternal(n.node_id);
+ const isSymbol = !isExternalNode && nodeKind(n.node_id) === "symbol";
+ if (isExternalNode) {
return (
<p
key={`out-${n.node_id}`}
diff --git a/packages/ui/src/graph/sigma/graphology-adapter.ts b/packages/ui/src/graph/sigma/graphology-adapter.ts
index 4d3da1a71..2898b2bbb 100644
--- a/packages/ui/src/graph/sigma/graphology-adapter.ts
+++ b/packages/ui/src/graph/sigma/graphology-adapter.ts
@@ -1,4 +1,5 @@
import Graph from "graphology";
+import { isExternal } from "@repowise-dev/types";
import type {
GraphExport,
GraphNode,
@@ -306,9 +307,15 @@ function* buildFileGraph(
return result;
}
-/** External-dependency module ids share the platform-wide `external:` prefix. */
+/**
+ * True for a module id naming code we do not own.
+ *
+ * Delegates rather than testing the prefix by hand: `framework:` nodes are
+ * third-party too, and the hand-rolled check missed them, so a framework's
+ * own code was drawn as one of the repository's modules.
+ */
export function isExternalModuleId(id: string): boolean {
- return id.startsWith("external:");
+ return isExternal(id);
}
export function moduleGraphToGraphology(
diff --git a/packages/web/src/app/repos/[id]/knowledge-graph/page.tsx b/packages/web/src/app/repos/[id]/knowledge-graph/page.tsx
index ff00601c5..11a6bfdd6 100644
--- a/packages/web/src/app/repos/[id]/knowledge-graph/page.tsx
+++ b/packages/web/src/app/repos/[id]/knowledge-graph/page.tsx
@@ -26,6 +26,7 @@ import { ZoomBreadcrumb } from "@/components/zoom/zoom-breadcrumb";
import { ZoomSearch } from "@/components/zoom/zoom-search";
import { ZoomDetailPanel } from "@/components/zoom/zoom-detail-panel";
import { ZoomHint } from "@/components/zoom/zoom-hint";
+import { ZoomExportButton } from "@/components/zoom/zoom-export-button";
export default function KnowledgeGraphPage({ params }: { params: Promise<{ id: string }> }) {
const { id: repoId } = use(params);
@@ -66,6 +67,10 @@ export default function KnowledgeGraphPage({ params }: { params: Promise<{ id: s
title="Knowledge Graph"
icon={<ScanSearch className="h-5 w-5 text-[var(--color-accent-primary)]" />}
description="Explore your codebase like a map: scroll to zoom, drag to pan, and double-click any card to dive into its layers, folders and files, ranked by how the code actually runs."
+ // The export has its own endpoint and does not need the zoom map, but a
+ // map that failed to load is the cheapest signal that this repo has
+ // nothing indexed to export either.
+ actions={<ZoomExportButton repoId={repoId} disabled={isLoading || !!error} />}
maxWidth="wide"
>
{/* Full-bleed canvas (no framing border): the map blends into the page.
diff --git a/packages/web/src/components/zoom/zoom-export-button.tsx b/packages/web/src/components/zoom/zoom-export-button.tsx
new file mode 100644
index 000000000..d3e8a003b
--- /dev/null
+++ b/packages/web/src/components/zoom/zoom-export-button.tsx
@@ -0,0 +1,80 @@
+"use client";
+
+/**
+ * Download this repository's architecture as a Structurizr DSL model.
+ *
+ * The file is a model *fragment* by default — the same artefact
+ * `repowise export --format structurizr` writes — so it drops into a
+ * workspace the user already owns without clobbering their views or styles.
+ * It carries its own header comment explaining that and showing the
+ * `!include` snippet, which is what stops someone who never saw the terminal
+ * output from reading it as broken.
+ *
+ * Note the model is grouped by container and component (package manifests and
+ * directories), not by the layers this page's canvas draws; layer membership
+ * rides along as a tag on every element. Hence the neutral label — this is not
+ * "export what I am looking at".
+ */
+
+import { useCallback, useRef, useState } from "react";
+import { FileType2, Loader2 } from "lucide-react";
+import { toast } from "sonner";
+import { getStructurizrDsl } from "@repowise-dev/api-client/c4";
+import { downloadTextFile } from "@/lib/utils/download";
+
+const FILENAME = "repowise-model.dsl";
+
+export function ZoomExportButton({
+ repoId,
+ disabled,
+}: {
+ repoId: string;
+ disabled?: boolean;
+}) {
+ const [working, setWorking] = useState(false);
+ // `working` is only true after a re-render, and `disabled` follows it, so two
+ // clicks inside one tick both get through and both fetch. A ref is read and
+ // set synchronously, which is the only thing that closes that window.
+ const inFlight = useRef(false);
+
+ const onClick = useCallback(async () => {
+ if (inFlight.current) return;
+ inFlight.current = true;
+ setWorking(true);
+ try {
+ const dsl = await getStructurizrDsl(repoId);
+ downloadTextFile(dsl, FILENAME, "text/plain");
+ toast.success(`Downloaded ${FILENAME}`);
+ } catch (error) {
+ // The client throws with the status code, so a 404 (no such repo) and a
+ // 500 (built and failed) are different problems. Keep it out of the toast
+ // and in the console, where someone debugging will look.
+ console.error("Structurizr DSL export failed", error);
+ toast.error("Couldn't build the Structurizr DSL");
+ } finally {
+ inFlight.current = false;
+ setWorking(false);
+ }
+ }, [repoId]);
+
+ return (
+ <button
+ type="button"
+ onClick={() => void onClick()}
+ disabled={disabled || working}
+ aria-busy={working}
+ title="Download this repository's architecture as a Structurizr DSL model fragment"
+ className="inline-flex items-center gap-1.5 rounded-lg border border-[var(--color-border-default)] px-2.5 py-1.5 text-xs font-medium text-[var(--color-text-secondary)] transition-colors hover:text-[var(--color-text-primary)] disabled:cursor-not-allowed disabled:opacity-50"
+ >
+ {working ? (
+ <Loader2 className="h-3.5 w-3.5 animate-spin" />
+ ) : (
+ <FileType2 className="h-3.5 w-3.5" />
+ )}
+ {/* The label carries the state, not just the icon: lucide marks its
+ glyphs aria-hidden, so a spinner alone tells a screen-reader user
+ nothing happened. */}
+ {working ? "Building…" : "Structurizr DSL"}
+ </button>
+ );
+}
diff --git a/scripts/emit_sample_dsl.py b/scripts/emit_sample_dsl.py
new file mode 100644
index 000000000..592fddb9e
--- /dev/null
+++ b/scripts/emit_sample_dsl.py
@@ -0,0 +1,315 @@
+"""Emit sample Structurizr DSL for the parse check, with no index needed.
+
+The unit tests prove the emitter's own invariants — brace balance, no dangling
+references, stable identifiers. They cannot prove the result is *valid
+Structurizr*, because only Structurizr's parser knows that. This writes a
+model exercising every construct the emitter can produce so CI can feed it to
+the real parser.
+
+ python scripts/emit_sample_dsl.py <output-dir>
+
+Writes ``workspace.dsl`` (standalone) and a ``fragment/`` directory holding
+``repowise-model.dsl`` plus a host workspace that includes it.
+"""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+
+from repowise.server.services.c4_builder.models import (
+ BoxSignals,
+ C4Model,
+ Component,
+ Container,
+ ExternalSystemView,
+ Person,
+ Relation,
+ System,
+ TourStep,
+)
+from repowise.server.services.c4_builder.structurizr import system_identifier, to_dsl
+
+
+def _sample_model() -> C4Model:
+ """A model with every construct: nesting, externals, health, layers, a tour.
+
+ Names deliberately include every awkward case we have actually been bitten
+ by, because the parser is the only thing that can tell us they survive:
+
+ * a component called ``(root)`` and a path that needs slugging;
+ * two containers, and two components inside one container, whose leaf
+ directory is the same word;
+ * two dependencies presenting under the same display name, and one
+ presenting as the repository itself;
+ * two layer names that reduce to the same slug, and one carrying a quote;
+ * a tour title and a description holding newlines;
+ * non-ASCII names, which sanitise to nothing on their own.
+
+ Every one of these produced a file the parser rejected at some point. A
+ case that is not here is a case CI does not check.
+ """
+ core = Container(
+ id="pkg:packages/core",
+ name="core",
+ path="packages/core",
+ language="python",
+ file_count=120,
+ symbol_count=800,
+ hotspot_count=3,
+ dead_count=1,
+ )
+ web = Container(
+ id="pkg:packages/web",
+ name="web",
+ path="packages/web",
+ language="typescript",
+ file_count=40,
+ symbol_count=150,
+ )
+ empty = Container(
+ id="pkg:tools",
+ name="tools",
+ path="tools",
+ language="",
+ file_count=1,
+ symbol_count=0,
+ )
+ # Same leaf directory as ``packages/core``: a monorepo shape that emitted
+ # two `container "core"` blocks and was rejected outright.
+ other_core = Container(
+ id="pkg:services/core",
+ name="core",
+ path="services/core",
+ language="go",
+ file_count=8,
+ symbol_count=20,
+ )
+ # A name that sanitises to nothing on its own, so it leans on the allocator.
+ unicode_pkg = Container(
+ id="pkg:пакет",
+ name="пакет",
+ path="пакет",
+ language="python",
+ file_count=2,
+ symbol_count=3,
+ )
+ components = {
+ core.id: [
+ Component(
+ id="cmp:packages/core#root",
+ name="(root)",
+ path="packages/core",
+ container_id=core.id,
+ file_count=2,
+ symbol_count=4,
+ ),
+ Component(
+ id="cmp:packages/core/ingestion",
+ name="ingestion",
+ path="packages/core/ingestion",
+ container_id=core.id,
+ file_count=30,
+ symbol_count=200,
+ ),
+ ],
+ web.id: [
+ Component(
+ id="cmp:packages/web/app",
+ name="app",
+ path="packages/web/app",
+ container_id=web.id,
+ file_count=12,
+ symbol_count=60,
+ ),
+ # ``src`` and ``lib`` are both pass-through directories, so these
+ # two both present as "health" inside one container.
+ Component(
+ id="cmp:packages/web/src/health",
+ name="health",
+ path="packages/web/src/health",
+ container_id=web.id,
+ file_count=3,
+ symbol_count=9,
+ ),
+ Component(
+ id="cmp:packages/web/lib/health",
+ name="health",
+ path="packages/web/lib/health",
+ container_id=web.id,
+ file_count=2,
+ symbol_count=5,
+ ),
+ ],
+ empty.id: [],
+ other_core.id: [],
+ unicode_pkg.id: [],
+ }
+ return C4Model(
+ system=System(id="sys:abc123", name="sample-repo", description="A demo"),
+ people=[
+ Person(
+ id="person:cli",
+ name="CLI user",
+ description="Runs commands from a terminal",
+ kind="cli",
+ )
+ ],
+ containers=[core, web, empty, other_core, unicode_pkg],
+ components_by_container=components,
+ external_systems=[
+ ExternalSystemView(
+ id="ext:fastapi",
+ name="fastapi",
+ display_name="FastAPI",
+ category="framework",
+ ecosystem="pypi",
+ version="0.110",
+ ),
+ ExternalSystemView(
+ id="ext:@scope/pkg",
+ name="@scope/pkg",
+ display_name="@scope/pkg",
+ category="library",
+ ecosystem="npm",
+ version="^2.0",
+ ),
+ # These three all present as "React", which the parser refuses as
+ # three top-level elements sharing a name.
+ ExternalSystemView(
+ id="ext:react",
+ name="react",
+ display_name="React",
+ category="library",
+ ecosystem="npm",
+ ),
+ ExternalSystemView(
+ id="ext:@xyflow/react",
+ name="@xyflow/react",
+ display_name="React",
+ category="library",
+ ecosystem="npm",
+ ),
+ # And this one presents as the repository itself.
+ ExternalSystemView(
+ id="ext:sample-repo",
+ name="sample-repo-client",
+ display_name="sample-repo",
+ category="library",
+ ecosystem="npm",
+ ),
+ # No category, ecosystem or version: an empty description literal.
+ ExternalSystemView(
+ id="ext:bare", name="bare", display_name="bare", category="", ecosystem=""
+ ),
+ ],
+ container_relations=[
+ Relation(
+ source_id=web.id,
+ target_id=core.id,
+ label="imports",
+ edge_count=60,
+ edge_types=("imports",),
+ coupling="tight",
+ ),
+ Relation(
+ source_id=core.id,
+ target_id="ext:fastapi",
+ label="imports",
+ edge_count=4,
+ edge_types=("imports",),
+ coupling="loose",
+ ),
+ Relation(
+ source_id=empty.id,
+ target_id=core.id,
+ label="calls",
+ edge_count=1,
+ edge_types=("calls",),
+ coupling="loose",
+ ),
+ ],
+ component_relations=[
+ Relation(
+ source_id="cmp:packages/web/app",
+ target_id="cmp:packages/core/ingestion",
+ label="imports",
+ edge_count=12,
+ edge_types=("imports",),
+ coupling="moderate",
+ ),
+ Relation(
+ source_id="cmp:packages/core#root",
+ target_id="ext:@scope/pkg",
+ label="imports",
+ edge_count=2,
+ edge_types=("imports",),
+ coupling="loose",
+ ),
+ ],
+ box_signals={
+ core.id: BoxSignals(
+ hotspot_count=3,
+ dead_count=1,
+ layers=("Domain", "Ingestion"),
+ primary_owner='Ada "Countess" Lovelace',
+ primary_owner_pct=62.5,
+ min_bus_factor=1,
+ ),
+ web.id: BoxSignals(layers=("Data Access",)),
+ # Reduces to the same slug as "Data Access" did.
+ other_core.id: BoxSignals(layers=("Data-Access",)),
+ # A quote has to survive into both the tag and the view filter.
+ unicode_pkg.id: BoxSignals(layers=('Presentation "UI"',)),
+ "cmp:packages/core/ingestion": BoxSignals(hotspot_count=2, layers=("Ingestion",)),
+ },
+ tour=[
+ TourStep(
+ order=1,
+ title="Start at the CLI\nnot a second comment line",
+ reason="Every run enters here",
+ target_path="packages/core/cli.py",
+ layer_name="Domain",
+ ),
+ TourStep(
+ order=2,
+ title="Then ingestion",
+ description="Where files\nbecome symbols",
+ ),
+ ],
+ )
+
+
+def main(destination: Path) -> None:
+ model = _sample_model()
+ destination.mkdir(parents=True, exist_ok=True)
+ (destination / "workspace.dsl").write_text(
+ to_dsl(model, standalone=True, include_components=True), encoding="utf-8"
+ )
+
+ fragment_dir = destination / "fragment"
+ fragment_dir.mkdir(parents=True, exist_ok=True)
+ (fragment_dir / "repowise-model.dsl").write_text(
+ to_dsl(model, include_components=True), encoding="utf-8"
+ )
+ # The host workspace a user would write, with the identifier the CLI tells
+ # them to use — so this also checks the instructions we print are correct.
+ (fragment_dir / "workspace.dsl").write_text(
+ 'workspace "host" {\n'
+ " !include repowise-model.dsl\n"
+ "\n"
+ " views {\n"
+ f" systemContext {system_identifier(model, include_components=True)} {{\n"
+ " include *\n"
+ " autolayout lr\n"
+ " }\n"
+ " }\n"
+ "}\n",
+ encoding="utf-8",
+ )
+ print(f"wrote {destination / 'workspace.dsl'}")
+ print(f"wrote {fragment_dir / 'repowise-model.dsl'}")
+
+
+if __name__ == "__main__":
+ main(Path(sys.argv[1] if len(sys.argv) > 1 else "dsl-sample"))
diff --git a/tests/fixtures/node_ids.json b/tests/fixtures/node_ids.json
new file mode 100644
index 000000000..93bf86843
--- /dev/null
+++ b/tests/fixtures/node_ids.json
@@ -0,0 +1,141 @@
+{
+ "_comment": [
+ "Shared node-id cases, read by both packages/core/.../ids.py's tests and",
+ "packages/types/src/node-ids.ts's tests. The two modules decode the same",
+ "wire data, so a rule that holds in one and not the other is a live bug —",
+ "and nothing but a shared list of cases can fail a build when they drift.",
+ "",
+ "kind: the variant name, lowercased ('file', 'symbol', 'external', ...)",
+ "file_path: the file this id refers to, or null",
+ "symbol_name: the symbol this id names, or null",
+ "is_external: names code we do not own (third-party or framework)"
+ ],
+ "cases": [
+ {
+ "raw": "src/main.py",
+ "kind": "path",
+ "file_path": "src/main.py",
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "C:\\src\\main.py",
+ "kind": "path",
+ "file_path": "C:\\src\\main.py",
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "mailto:[email protected]",
+ "kind": "path",
+ "file_path": "mailto:[email protected]",
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "file:src/main.py",
+ "kind": "file",
+ "file_path": "src/main.py",
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "src/main.py::main",
+ "kind": "symbol",
+ "file_path": "src/main.py",
+ "symbol_name": "main",
+ "is_external": false
+ },
+ {
+ "raw": "src/lib.rs::Foo::bar",
+ "kind": "symbol",
+ "file_path": "src/lib.rs",
+ "symbol_name": "Foo::bar",
+ "is_external": false
+ },
+ {
+ "raw": "external:react",
+ "kind": "external",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": true
+ },
+ {
+ "raw": "external:pub:http",
+ "kind": "external",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": true
+ },
+ {
+ "raw": "external:serde::Deserialize",
+ "kind": "external",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": true
+ },
+ {
+ "raw": "framework:typo3-core",
+ "kind": "framework",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": true
+ },
+ {
+ "raw": "framework:foo::bar",
+ "kind": "framework",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": true
+ },
+ {
+ "raw": "sys:repowise",
+ "kind": "sys",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "person:developer",
+ "kind": "person",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "pkg:packages/core",
+ "kind": "pkg",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "cmp:packages/core/ingestion",
+ "kind": "cmp",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "cmp:packages/core#root",
+ "kind": "cmp",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ },
+ {
+ "raw": "ext:react",
+ "kind": "ext",
+ "file_path": null,
+ "symbol_name": null,
+ "is_external": false
+ }
+ ],
+ "display_labels": [
+ { "raw": "src/main.py::main", "label": "main" },
+ { "raw": "src/dir/main.py", "label": "main.py" },
+ { "raw": "file:src/dir/main.py", "label": "main.py" },
+ { "raw": "external:react", "label": "react" },
+ { "raw": "cmp:packages/core#root", "label": "packages/core" }
+ ]
+}
diff --git a/tests/unit/analysis/test_execution_flows.py b/tests/unit/analysis/test_execution_flows.py
index ef5ac885e..e09d69bf5 100644
--- a/tests/unit/analysis/test_execution_flows.py
+++ b/tests/unit/analysis/test_execution_flows.py
@@ -109,3 +109,49 @@ def test_test_files_never_score_as_entry_points():
report = trace_execution_flows(g, {}, FlowConfig(min_flow_depth=1))
assert report.total_entry_points_scored == 0
assert report.entry_point_scores == {}
+
+
+class TestWhatCountsAsAnExcludedNode:
+ """Only symbol nodes carry ``file_path``; everything else falls back to its id.
+
+ That fallback used to be the empty string, so a file node and an
+ unresolved call target were never excluded however they were named —
+ the opposite of what this filter is for.
+ """
+
+ @staticmethod
+ def _graph(node_id: str, **attrs):
+ import networkx as nx
+
+ g = nx.DiGraph()
+ g.add_node(node_id, **attrs)
+ return g
+
+ def test_a_symbol_node_is_judged_on_its_declared_file(self) -> None:
+ from repowise.core.analysis.execution_flows import _is_excluded_node
+
+ g = self._graph("tests/test_a.py::helper", file_path="tests/test_a.py")
+ assert _is_excluded_node(g, "tests/test_a.py::helper")
+
+ g = self._graph("src/main.py::run", file_path="src/main.py")
+ assert not _is_excluded_node(g, "src/main.py::run")
+
+ def test_a_file_node_is_judged_on_its_own_id(self) -> None:
+ """A file node has no ``file_path`` attribute — its id is the path."""
+ from repowise.core.analysis.execution_flows import _is_excluded_node
+
+ assert _is_excluded_node(self._graph("scripts/build.py"), "scripts/build.py")
+ assert _is_excluded_node(self._graph("tests/test_a.py"), "tests/test_a.py")
+ assert not _is_excluded_node(self._graph("src/main.py"), "src/main.py")
+
+ def test_an_unresolved_call_target_is_judged_on_its_bare_name(self) -> None:
+ """A mis-resolved edge into a test fake is what this filter is for."""
+ from repowise.core.analysis.execution_flows import _is_excluded_node
+
+ assert _is_excluded_node(self._graph("test_helper"), "test_helper")
+ assert not _is_excluded_node(self._graph("fetchall"), "fetchall")
+
+ def test_an_external_is_not_a_path_and_is_never_excluded(self) -> None:
+ from repowise.core.analysis.execution_flows import _is_excluded_node
+
+ assert not _is_excluded_node(self._graph("external:pytest"), "external:pytest")
diff --git a/tests/unit/analysis/test_kg_skip_logic.py b/tests/unit/analysis/test_kg_skip_logic.py
index 31d348a18..d440c6fb9 100644
--- a/tests/unit/analysis/test_kg_skip_logic.py
+++ b/tests/unit/analysis/test_kg_skip_logic.py
@@ -3,14 +3,17 @@
from __future__ import annotations
import json
+import logging
+
+import pytest
from repowise.core.analysis.knowledge_graph import (
+ _KG_SCHEMA_VERSION,
KnowledgeGraphResult,
compute_kg_fingerprint,
should_skip_kg_rebuild,
)
-
# ---------------------------------------------------------------------------
# KnowledgeGraphResult.from_file
# ---------------------------------------------------------------------------
@@ -61,6 +64,64 @@ class TestKGResultFromFile:
assert loaded is not None
assert loaded.fingerprint == ""
+ def test_to_dict_carries_the_schema_version(self):
+ assert KnowledgeGraphResult().to_dict()["schema_version"] == _KG_SCHEMA_VERSION
+
+ def test_rejects_an_older_schema(self, tmp_path, caplog):
+ p = tmp_path / "kg.json"
+ p.write_text(
+ json.dumps({"schema_version": _KG_SCHEMA_VERSION - 1, "nodes": [{"id": "file:a.py"}]}),
+ encoding="utf-8",
+ )
+ with caplog.at_level(logging.INFO):
+ assert KnowledgeGraphResult.from_file(p) is None
+ assert "schema_version" in caplog.text
+
+ def test_rejects_a_non_integer_schema_version(self, tmp_path):
+ p = tmp_path / "kg.json"
+ p.write_text(json.dumps({"schema_version": "1.0.0", "nodes": []}), encoding="utf-8")
+ assert KnowledgeGraphResult.from_file(p) is None
+
+ def test_rejects_a_boolean_schema_version(self, tmp_path):
+ """``True`` is an int in Python, and ``True < 1`` is False, so it loaded."""
+ p = tmp_path / "kg.json"
+ p.write_text(json.dumps({"schema_version": True, "nodes": []}), encoding="utf-8")
+ assert KnowledgeGraphResult.from_file(p) is None
+
+ @pytest.mark.parametrize("payload", ["[]", '"x"', "5", "null", "true"])
+ def test_rejects_valid_json_that_is_not_an_object(self, tmp_path, payload):
+ """All five are valid JSON and all five are reachable from a hand edit.
+
+ The loader called ``.get`` on whatever came back, so these raised
+ AttributeError — which the orchestrator's except tuple does not name,
+ so it escaped and killed the run. That is the failure the guard around
+ this loader exists to stop.
+ """
+ p = tmp_path / "kg.json"
+ p.write_text(payload, encoding="utf-8")
+ assert KnowledgeGraphResult.from_file(p) is None
+
+ def test_accepts_a_file_written_before_the_field_existed(self, tmp_path):
+ """Unversioned files have the current shape, so they still load.
+
+ The gate only bites on a future bump; rejecting today's artifacts
+ would throw away curated layer names for no reason.
+ """
+ p = tmp_path / "kg.json"
+ p.write_text(json.dumps({"nodes": [{"id": "file:a.py"}], "layers": []}), encoding="utf-8")
+ loaded = KnowledgeGraphResult.from_file(p)
+ assert loaded is not None
+ assert len(loaded.nodes) == 1
+
+ def test_accepts_a_newer_schema(self, tmp_path):
+ """Forward compatibility is the writer's problem, not the reader's."""
+ p = tmp_path / "kg.json"
+ p.write_text(
+ json.dumps({"schema_version": _KG_SCHEMA_VERSION + 1, "nodes": []}),
+ encoding="utf-8",
+ )
+ assert KnowledgeGraphResult.from_file(p) is not None
+
# ---------------------------------------------------------------------------
# Fingerprint determinism
@@ -70,6 +131,7 @@ class TestKGResultFromFile:
class TestFingerprintDeterminism:
def _make_graph_builder(self, nodes, edges, communities):
from unittest.mock import MagicMock
+
import networkx as nx
g = nx.DiGraph()
diff --git a/tests/unit/cli/test_export_structurizr.py b/tests/unit/cli/test_export_structurizr.py
new file mode 100644
index 000000000..26be4ead4
--- /dev/null
+++ b/tests/unit/cli/test_export_structurizr.py
@@ -0,0 +1,278 @@
+"""Tests for ``repowise export --format structurizr``.
+
+The model building is covered elsewhere; what matters here is the surface a
+user actually touches — where the file lands, and whether the message tells
+them what to do next when the default output is a fragment that looks
+incomplete on its own.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import pytest
+
+from repowise.cli.commands.export_structurizr import (
+ FRAGMENT_FILENAME,
+ STANDALONE_FILENAME,
+ _counts,
+ _resolve_output,
+ export_structurizr,
+)
+from repowise.server.services.c4_builder.models import (
+ C4Model,
+ Component,
+ Container,
+ ExternalSystemView,
+ Relation,
+ System,
+)
+
+
+def _model(*, containers: bool = True) -> C4Model:
+ core = Container(
+ id="pkg:packages/core",
+ name="core",
+ path="packages/core",
+ language="python",
+ file_count=10,
+ symbol_count=20,
+ )
+ return C4Model(
+ system=System(id="sys:abc", name="demo"),
+ people=[],
+ containers=[core] if containers else [],
+ components_by_container={
+ core.id: [
+ Component(
+ id="cmp:packages/core/ingestion",
+ name="ingestion",
+ path="packages/core/ingestion",
+ container_id=core.id,
+ file_count=4,
+ symbol_count=9,
+ )
+ ]
+ }
+ if containers
+ else {},
+ external_systems=[
+ ExternalSystemView(
+ id="ext:fastapi",
+ name="fastapi",
+ display_name="FastAPI",
+ category="framework",
+ ecosystem="pypi",
+ )
+ ]
+ if containers
+ else [],
+ container_relations=[Relation(source_id=core.id, target_id="ext:fastapi", label="imports")]
+ if containers
+ else [],
+ component_relations=[],
+ )
+
+
+def patched(monkeypatch):
+ """Swap the database build for a fixed model."""
+ model = _model()
+
+ async def fake_build(repo_path, *, include_components):
+ return model
+
+ monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", fake_build)
+ return model
+
+
+# ---------------------------------------------------------------------------
+# Output path
+# ---------------------------------------------------------------------------
+
+
+def test_output_defaults_to_the_repo_root(tmp_path: Path) -> None:
+ assert _resolve_output(None, tmp_path, standalone=False) == tmp_path / FRAGMENT_FILENAME
+ assert _resolve_output(None, tmp_path, standalone=True) == tmp_path / STANDALONE_FILENAME
+
+
+def test_a_dsl_path_names_the_file_and_anything_else_is_a_directory(
+ tmp_path: Path,
+) -> None:
+ named = _resolve_output(str(tmp_path / "arch.dsl"), tmp_path, standalone=False)
+ assert named == tmp_path / "arch.dsl"
+
+ directory = _resolve_output(str(tmp_path / "out"), tmp_path, standalone=False)
+ assert directory == tmp_path / "out" / FRAGMENT_FILENAME
+
+
+# ---------------------------------------------------------------------------
+# Writing
+# ---------------------------------------------------------------------------
+
+
+def test_writes_a_fragment_by_default(tmp_path: Path, patched, capsys) -> None:
+ code = export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert code == 0
+ written = (tmp_path / FRAGMENT_FILENAME).read_text(encoding="utf-8")
+ assert written.lstrip().startswith("#")
+ assert "\nmodel {\n" in written
+ assert "component " not in written
+
+
+def test_standalone_writes_a_whole_workspace(tmp_path: Path, patched) -> None:
+ code = export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=True,
+ include_components=True,
+ include_externals=True,
+ )
+ assert code == 0
+ written = (tmp_path / STANDALONE_FILENAME).read_text(encoding="utf-8")
+ assert "workspace " in written
+ assert "views {" in written
+
+
+def test_a_missing_parent_directory_is_created(tmp_path: Path, patched) -> None:
+ target = tmp_path / "nested" / "deeper" / "arch.dsl"
+ code = export_structurizr(
+ tmp_path,
+ output=str(target),
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert code == 0
+ assert target.is_file()
+
+
+# ---------------------------------------------------------------------------
+# What the user is told
+# ---------------------------------------------------------------------------
+
+
+def test_the_message_says_what_to_do_next(tmp_path: Path, patched, capsys) -> None:
+ """A filename alone leaves the user staring at a file with no views."""
+ export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ out = capsys.readouterr().out
+ assert f"!include {FRAGMENT_FILENAME}" in out
+ assert "workspace" in out
+ # The system identifier is filled in, not left as a placeholder to edit.
+ assert "systemContext sys_demo" in out
+ assert "<system id>" not in out
+ assert "structurizr/structurizr" in out
+
+
+def test_the_standalone_hint_only_appears_when_there_is_no_workspace(
+ tmp_path: Path, patched, capsys
+) -> None:
+ export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert "--standalone" in capsys.readouterr().out
+
+ (tmp_path / STANDALONE_FILENAME).write_text("workspace {}", encoding="utf-8")
+ export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert "--standalone" not in capsys.readouterr().out
+
+
+def test_counts_are_reported_so_an_empty_index_is_obvious() -> None:
+ summary = _counts(_model(), include_components=True, include_externals=True)
+ assert "1 containers" in summary
+ assert "1 components" in summary
+ assert "1 external systems" in summary
+
+
+# ---------------------------------------------------------------------------
+# Failure modes
+# ---------------------------------------------------------------------------
+
+
+def test_an_unindexed_repo_names_the_command_that_fixes_it(
+ tmp_path: Path, monkeypatch, capsys
+) -> None:
+ async def no_model(repo_path, *, include_components):
+ return None
+
+ monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", no_model)
+ code = export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert code == 1
+ assert "repowise init" in capsys.readouterr().out
+ assert not (tmp_path / FRAGMENT_FILENAME).exists()
+
+
+def test_an_empty_model_fails_instead_of_writing_a_useless_file(
+ tmp_path: Path, monkeypatch, capsys
+) -> None:
+ """A valid file with nothing in it reads as "this repo has no structure"."""
+ empty = _model(containers=False)
+
+ async def build_empty(repo_path, *, include_components):
+ return empty
+
+ monkeypatch.setattr("repowise.cli.commands.export_structurizr._build", build_empty)
+ code = export_structurizr(
+ tmp_path,
+ output=None,
+ standalone=False,
+ include_components=False,
+ include_externals=True,
+ )
+ assert code == 1
+ assert "No containers" in capsys.readouterr().out
+ assert not (tmp_path / FRAGMENT_FILENAME).exists()
+
+
+def test_an_uppercase_dsl_suffix_is_still_a_file(tmp_path) -> None:
+ """``--out MODEL.DSL`` used to create a directory of that name."""
+ from repowise.cli.commands.export_structurizr import _resolve_output
+
+ resolved = _resolve_output(str(tmp_path / "MODEL.DSL"), tmp_path, standalone=False)
+ assert resolved.name == "MODEL.DSL"
+ assert resolved.parent == tmp_path.resolve()
+
+
+async def test_a_database_with_no_tables_reads_as_not_indexed(tmp_path) -> None:
+ """The path a fresh clone with a stray .repowise/ dir takes.
+
+ Every other CLI test stubs ``_build`` wholesale, so this branch — the one
+ that turns a raw "no such table: repositories" traceback into the message
+ naming the command that fixes it — had never run.
+ """
+ from repowise.cli.commands.export_structurizr import _build
+
+ repo = tmp_path / "repo"
+ (repo / ".repowise").mkdir(parents=True)
+ # An empty file where the index belongs: opens as SQLite, has no tables.
+ (repo / ".repowise" / "wiki.db").touch()
+
+ assert await _build(repo, include_components=False) is None
diff --git a/tests/unit/generation/test_context_assembler.py b/tests/unit/generation/test_context_assembler.py
index 9a2f998ae..ebafaf274 100644
--- a/tests/unit/generation/test_context_assembler.py
+++ b/tests/unit/generation/test_context_assembler.py
@@ -317,6 +317,27 @@ def test_assemble_repo_overview_top_files_sorted(
assert ctx.top_files_by_pagerank[0].score >= ctx.top_files_by_pagerank[1].score
+def test_assemble_repo_overview_leaves_out_crates_and_frameworks(
+ sample_config, sample_repo_structure
+):
+ """PageRank is computed over the whole graph, externals included.
+
+ A Rust crate arrives as ``external:serde::Deserialize`` — the separator is
+ part of the crate path, not a symbol — and a framework node as
+ ``framework:typo3-core``. Reading either as one of the repository's own
+ files puts a third-party name at the top of the generated overview.
+ """
+ assembler = ContextAssembler(sample_config)
+ pagerank = {
+ "external:serde::Deserialize": 0.9,
+ "framework:typo3-core": 0.8,
+ "external:react": 0.7,
+ "python_pkg/calculator.py": 0.5,
+ }
+ ctx = assembler.assemble_repo_overview(sample_repo_structure, pagerank, [], {})
+ assert [f.path for f in ctx.top_files_by_pagerank] == ["python_pkg/calculator.py"]
+
+
def test_assemble_repo_overview_circular_dep_count(
sample_config, sample_graph, sample_repo_structure
):
diff --git a/tests/unit/generation/test_knowledge_graph_enrichment.py b/tests/unit/generation/test_knowledge_graph_enrichment.py
index d5294f037..884bcf69b 100644
--- a/tests/unit/generation/test_knowledge_graph_enrichment.py
+++ b/tests/unit/generation/test_knowledge_graph_enrichment.py
@@ -445,3 +445,34 @@ class TestEnrichmentSplit:
assert result.layers[0]["name"] == "Renamed Core"
# …but the snapshot generation already holds is untouched.
assert snapshot["layers"][0]["name"] == "heuristic-core"
+
+
+def test_only_file_ids_become_tour_files() -> None:
+ """A layer's member list can hold ids that name no file.
+
+ ``module:``, ``layer:`` and ``dir:`` are all real namespaces here, and none
+ is a known prefix — so each parses as a bare path and the permissive
+ helper handed it back as a file. It then got looked up in PageRank and
+ offered as a tour stop, which is a path that does not exist.
+ """
+ from repowise.core.generation.knowledge_graph import build_deterministic_tour
+
+ layers = [
+ {
+ "id": "layer:api",
+ "name": "API",
+ "nodeIds": [
+ "module:core-ingestion",
+ "layer:api",
+ "dir:packages/core",
+ "file:packages/core/api.py",
+ ],
+ }
+ ]
+ steps = build_deterministic_tour(
+ pagerank={"packages/core/api.py": 0.9, "module:core-ingestion": 0.99},
+ entry_points=[],
+ layers=layers,
+ )
+ named = [nid for step in steps for nid in step.get("nodeIds", [])]
+ assert named == ["file:packages/core/api.py"], named
diff --git a/tests/unit/generation/test_layers.py b/tests/unit/generation/test_layers.py
index 52649c31d..3e78c80ce 100644
--- a/tests/unit/generation/test_layers.py
+++ b/tests/unit/generation/test_layers.py
@@ -8,6 +8,7 @@ from repowise.core.generation.layers import (
compute_layer_order,
infer_layer,
layer_key,
+ layer_order_basis,
)
# ---------------------------------------------------------------------------
@@ -281,6 +282,27 @@ def test_compute_layer_order_ignores_external_and_intra_layer_edges():
assert order.index("API") < order.index("Data")
+def test_compute_layer_order_ignores_frameworks_and_rust_crates():
+ """The two external spellings the plain ``external:`` check used to miss.
+
+ ``framework:`` nodes are synthesised by the framework-edge passes, and Rust
+ externals carry the symbol separator in their name. Either one leaking into
+ the ordering race would let a dependency we do not own decide the stack.
+ """
+ file_layers = {"api/a.py": "API", "data/d.py": "Data"}
+ edges = [
+ ("api/a.py", "framework:typo3-core"),
+ ("api/a.py", "external:serde::Deserialize"),
+ ("framework:typo3-core", "data/d.py"),
+ ("api/a.py", "data/d.py"),
+ ]
+ order = compute_layer_order(file_layers, edges)
+ assert order.index("API") < order.index("Data")
+ # Only the one edge between two files we own counts as evidence.
+ assert layer_order_basis(file_layers, edges) == "imports"
+ assert layer_order_basis(file_layers, edges[:3]) == "canonical"
+
+
def test_compute_layer_order_stable_without_edges():
file_layers = {"a.py": "API", "b.py": "Utility", "c.py": "Data"}
order = compute_layer_order(file_layers, [])
diff --git a/tests/unit/generation/test_mermaid_safety.py b/tests/unit/generation/test_mermaid_safety.py
index 605e8672d..cb325ed6e 100644
--- a/tests/unit/generation/test_mermaid_safety.py
+++ b/tests/unit/generation/test_mermaid_safety.py
@@ -2,6 +2,8 @@
from __future__ import annotations
+import re
+
from repowise.core.generation.mermaid_safety import sanitize_mermaid, sanitize_pages
@@ -81,3 +83,116 @@ def test_sanitize_pages_mutates_and_counts():
assert n == 1
assert "pkg/x.py" not in changed.content
assert unchanged.content == "# clean\n\nno diagram here"
+
+
+# ---------------------------------------------------------------------------
+# Label preservation, nesting, and stable slugs
+# ---------------------------------------------------------------------------
+
+
+def test_a_path_inside_a_label_survives_the_id_pass() -> None:
+ """The label is prose. Slugging it produced a legal but unreadable diagram."""
+ out = sanitize_mermaid(_block("graph TD\n A[src/main.py] --> B[app.run]"))
+ assert '"src/main.py"' in out
+ assert "src_main_py" not in out
+
+
+def test_an_already_quoted_label_is_left_alone_by_the_id_pass() -> None:
+ out = sanitize_mermaid(_block('graph TD\n A["pkg/foo.py handles auth"] --> B'))
+ assert '"pkg/foo.py handles auth"' in out
+
+
+def test_a_bare_path_used_as_a_node_id_is_still_slugged() -> None:
+ """The point of the pass: an unquoted path id breaks the whole diagram."""
+ out = sanitize_mermaid(_block("graph TD\n pkg/foo.py --> pkg/bar.py"))
+ assert "pkg/foo.py -->" not in out
+ assert "pkg_foo_py" in out
+ assert "pkg_bar_py" in out
+
+
+def test_a_label_containing_its_own_bracket_ends_where_it_really_ends() -> None:
+ out = sanitize_mermaid(_block("graph TD\n A[run(x[0])] --> B"))
+ # The whole label is captured and quoted, not cut at the inner bracket.
+ assert '"run(x[0])"' in out
+ assert out.count("-->") == 1
+
+
+def test_colliding_slugs_do_not_depend_on_document_order() -> None:
+ """A counter would renumber everything after an unrelated insertion."""
+ first = sanitize_mermaid(_block("graph TD\n a/b.py --> a.b.py"))
+ second = sanitize_mermaid(_block("graph TD\n a.b.py --> a/b.py"))
+ ids_first = set(re.findall(r"a_b_py\w*", first))
+ ids_second = set(re.findall(r"a_b_py\w*", second))
+ assert ids_first == ids_second
+ assert len(ids_first) == 2
+
+
+def test_output_is_stable_across_runs() -> None:
+ body = _block("graph TD\n src/a.py --> src/b.py\n C[run() -> None] --> src/a.py")
+ assert sanitize_mermaid(body) == sanitize_mermaid(body)
+
+
+def test_a_non_graph_diagram_is_still_left_untouched() -> None:
+ body = _block("sequenceDiagram\n A->>B: calls src/main.py")
+ assert sanitize_mermaid(body) == body
+
+
+class TestThePassNeverMakesADiagramWorse:
+ """The module promises it can only improve a block. Three ways it did not."""
+
+ def test_a_pipe_edge_label_is_not_slugged(self) -> None:
+ """``-->|yes/no|`` is a label, not a node id.
+
+ Labels between pipes are never quoted, so the pathy-token pass ran over
+ them and rewrote ordinary words. ``read/write``, ``true/false`` and
+ ``A/B`` are all everyday edge labels.
+ """
+ md = "```mermaid\ngraph LR\nA -->|yes/no| B\nC -->|read/write| D\n```"
+ out = sanitize_mermaid(md)
+ assert "|yes/no|" in out
+ assert "|read/write|" in out
+ assert "yes_no" not in out
+
+ def test_a_pipe_label_does_not_stop_ids_being_slugged(self) -> None:
+ """Protecting the label must not protect the endpoints around it."""
+ md = "```mermaid\ngraph LR\nsrc/a.py -->|calls| src/b.py\n```"
+ out = sanitize_mermaid(md)
+ assert "|calls|" in out
+ assert "src_a_py" in out
+ assert "src_b_py" in out
+
+ def test_an_init_directive_survives(self) -> None:
+ """``%%{init: ...}%%`` is a directive, not a rhombus label.
+
+ ``{`` is a shape opener, so the directive body was read as a label and
+ its quotes were entity-escaped — turning a diagram that rendered into
+ one that does not.
+
+ The directive is placed after the graph line because that is the case
+ that corrupts: with it on the first line the whole block fails the
+ graph-directive check and is skipped untouched.
+ """
+ md = '```mermaid\ngraph LR\n%%{init: {"theme":"dark"}}%%\nA --> B\n```'
+ out = sanitize_mermaid(md)
+ assert '%%{init: {"theme":"dark"}}%%' in out
+ assert "&quot;" not in out
+
+ def test_a_comment_line_is_left_alone(self) -> None:
+ """``%%`` starts a comment, so nothing in it is diagram syntax."""
+ md = "```mermaid\ngraph LR\n%% see src/main.py for the (real) entry point\nA --> B\n```"
+ out = sanitize_mermaid(md)
+ assert "%% see src/main.py for the (real) entry point" in out
+
+ def test_a_slug_cannot_collide_with_an_id_already_in_the_diagram(self) -> None:
+ """Two distinct nodes must not be merged into one.
+
+ Collisions were only resolved among the ids being slugged, so a slug
+ landing on an identifier that was already legal silently merged the two
+ nodes and turned a real edge into a self-loop.
+ """
+ md = "```mermaid\ngraph LR\nsrc_main_py[Existing]\nsrc/main.py --> src_main_py\n```"
+ out = sanitize_mermaid(md)
+ edge = next(line for line in out.split("\n") if "-->" in line)
+ source, target = (part.strip() for part in edge.split("-->"))
+ assert source != target, edge
+ assert "src_main_py[Existing]" in out
diff --git a/tests/unit/health/test_health_config.py b/tests/unit/health/test_health_config.py
index ed1cd4cfb..f113a248a 100644
--- a/tests/unit/health/test_health_config.py
+++ b/tests/unit/health/test_health_config.py
@@ -5,7 +5,10 @@ from __future__ import annotations
import json
from pathlib import Path
-from repowise.core.analysis.health.config import HealthConfig
+from repowise.core.analysis.health.config import (
+ HealthConfig,
+ glob_narrowed_by_gitignore_semantics,
+)
from repowise.core.analysis.health.models import Severity
@@ -234,3 +237,196 @@ def test_refactoring_block_coexists_with_health_rules(tmp_path: Path):
cfg = HealthConfig.load(tmp_path)
assert cfg.disabled_biomarkers == ["dry_violation"]
assert cfg.disabled_refactorings == ["extract_class"]
+
+
+# ---------------------------------------------------------------------------
+# Glob semantics
+# ---------------------------------------------------------------------------
+
+
+class TestGitignoreGlobSemantics:
+ """Health rules match the way exclude_patterns and .gitignore do.
+
+ This changed: patterns used to be matched with fnmatch, where ``*``
+ crossed directory separators.
+ """
+
+ def test_a_double_star_covers_a_whole_subtree(self) -> None:
+ config = HealthConfig.from_dict(
+ {"rules": [{"path": "src/legacy/**", "disabled_biomarkers": ["complex_method"]}]}
+ )
+ disabled = config.per_file_disabled(
+ ["src/legacy/a.py", "src/legacy/deep/b.py", "src/fresh/c.py"]
+ )
+ assert disabled["src/legacy/a.py"] == {"complex_method"}
+ assert disabled["src/legacy/deep/b.py"] == {"complex_method"}
+ assert "src/fresh/c.py" not in disabled
+
+ def test_a_single_star_stops_at_a_path_segment(self) -> None:
+ """The behaviour change: 'src/*' no longer swallows the whole tree."""
+ config = HealthConfig.from_dict(
+ {"rules": [{"path": "src/*.py", "disabled_biomarkers": ["complex_method"]}]}
+ )
+ disabled = config.per_file_disabled(["src/a.py", "src/deep/b.py"])
+ assert disabled["src/a.py"] == {"complex_method"}
+ assert "src/deep/b.py" not in disabled
+
+ def test_a_bare_extension_glob_matches_at_any_depth(self) -> None:
+ config = HealthConfig.from_dict(
+ {"rules": [{"path": "*.generated.ts", "disabled_biomarkers": ["large_method"]}]}
+ )
+ disabled = config.per_file_disabled(["a.generated.ts", "src/deep/b.generated.ts"])
+ assert set(disabled) == {"a.generated.ts", "src/deep/b.generated.ts"}
+
+ def test_a_directory_prefix_matches_everything_under_it(self) -> None:
+ config = HealthConfig.from_dict(
+ {"rules": [{"path": "vendor/", "disabled_biomarkers": ["dry_violation"]}]}
+ )
+ disabled = config.per_file_disabled(["vendor/lib/a.js", "app/b.js"])
+ assert disabled["vendor/lib/a.js"] == {"dry_violation"}
+ assert "app/b.js" not in disabled
+
+ def test_a_pattern_that_now_covers_less_is_detected(self) -> None:
+ """Silently narrowing a rule would un-silence biomarkers.
+
+ Loading one logs a warning naming the pattern; the rule behind that
+ warning is what is pinned here, since the log call is one line and
+ structlog's sink is reconfigured by other suites.
+
+ What narrows is a lone ``*`` with pattern text after it — the star
+ stops crossing ``/``, so anything the pattern still demands beyond it
+ can no longer be reached.
+ """
+ assert glob_narrowed_by_gitignore_semantics("packages/*/tests")
+ assert glob_narrowed_by_gitignore_semantics("src/*.py")
+ assert glob_narrowed_by_gitignore_semantics("src/*/x.py")
+
+ def test_a_trailing_star_is_not_a_narrowing(self) -> None:
+ """The commonest shape, and the warning was wrong about it.
+
+ ``src/legacy/*`` names the directory's entries, and gitignore excludes
+ everything under an excluded directory — so it still covers the whole
+ subtree, exactly as fnmatch did. Verified against both engines:
+ ``src/legacy/a/b.py`` matches under each. Telling people to rewrite it
+ sent them after a rule that was never broken.
+ """
+ assert not glob_narrowed_by_gitignore_semantics("src/legacy/*")
+ assert not glob_narrowed_by_gitignore_semantics("src/*")
+
+ def test_a_malformed_glob_does_not_take_down_the_config(self) -> None:
+ """The loader is documented as never raising, and this file is hand-written.
+
+ git accepts ignore lines pathspec rejects — a trailing backslash is a
+ real pattern found in the wild — so one stray rule must not lose the
+ rest of somebody's config.
+ """
+ config = HealthConfig.from_dict(
+ {
+ "rules": [
+ {"path": ".godot\\", "disabled_biomarkers": ["complex_method"]},
+ {"path": "src/legacy/**", "disabled_biomarkers": ["dry_violation"]},
+ ]
+ }
+ )
+ assert len(config.rules) == 2
+ disabled = config.per_file_disabled(["src/legacy/a.py", ".godot/x.py"])
+ # The good rule still applies; the broken one matches nothing.
+ assert disabled["src/legacy/a.py"] == {"dry_violation"}
+ assert ".godot/x.py" not in disabled
+
+ def test_unaffected_patterns_are_not_flagged(self) -> None:
+ safe = (
+ "src/legacy/**", # already the broad form
+ "*.generated.ts", # no separator: any depth under both engines
+ "vendor/", # a directory prefix
+ "**/*.spec.ts", # the ** ahead of it has already covered depth
+ "src/**/*.py",
+ )
+ for pattern in safe:
+ assert not glob_narrowed_by_gitignore_semantics(pattern), pattern
+
+ def test_severity_overrides_use_the_same_matching(self) -> None:
+ config = HealthConfig.from_dict(
+ {
+ "rules": [
+ {"path": "src/legacy/**", "severity_overrides": {"complex_method": "low"}}
+ ]
+ }
+ )
+ overrides = config.per_file_severity_overrides(["src/legacy/deep/a.py", "src/new.py"])
+ assert "src/legacy/deep/a.py" in overrides
+ assert "src/new.py" not in overrides
+
+
+class TestAMalformedFieldNeverRaises:
+ """``from_dict`` is documented as never raising, and ``load`` relies on it.
+
+ ``load`` wraps only the JSON parse, and none of its four callers guard the
+ call, so an exception here aborts an index run over a hand-edited file.
+ """
+
+ def test_a_rules_field_that_is_not_a_list(self) -> None:
+ assert HealthConfig.from_dict({"rules": 5}).rules == []
+ assert HealthConfig.from_dict({"rules": "src/**"}).rules == []
+ assert HealthConfig.from_dict({"rules": {"path": "src/**"}}).rules == []
+
+ def test_a_disabled_biomarkers_field_that_is_not_a_list(self) -> None:
+ assert HealthConfig.from_dict({"disabled_biomarkers": 7}).disabled_biomarkers == []
+ assert HealthConfig.from_dict({"disabled_biomarkers": {"a": 1}}).disabled_biomarkers == []
+
+ def test_a_rules_disabled_biomarkers_field_that_is_not_a_list(self) -> None:
+ config = HealthConfig.from_dict(
+ {"rules": [{"path": "src/**", "disabled_biomarkers": 3}]}
+ )
+ assert len(config.rules) == 1
+ assert config.rules[0].disabled_biomarkers == []
+
+ def test_one_bad_field_does_not_cost_the_rest_of_the_file(self) -> None:
+ config = HealthConfig.from_dict(
+ {
+ "disabled_biomarkers": 7,
+ "rules": [
+ {"path": "src/legacy/**", "disabled_biomarkers": ["dry_violation"]},
+ {"path": "src/other/**", "disabled_biomarkers": "complex_method"},
+ ],
+ }
+ )
+ assert config.disabled_biomarkers == []
+ disabled = config.per_file_disabled(["src/legacy/a.py", "src/other/b.py"])
+ assert disabled["src/legacy/a.py"] == {"dry_violation"}
+ assert "src/other/b.py" not in disabled
+
+ def test_a_string_disabled_biomarkers_is_not_read_as_characters(self) -> None:
+ """A string is iterable, so a permissive fix would silence 'c','o','m'…"""
+ config = HealthConfig.from_dict({"disabled_biomarkers": "complex_method"})
+ assert config.disabled_biomarkers == []
+
+ def test_a_refactoring_detectors_field_that_is_not_a_list(self) -> None:
+ """Same shape as the rules fields, one block over in config.yaml."""
+ assert HealthConfig._from_refactoring_block(
+ {"detectors": {"disabled": 4}}
+ ).disabled_refactorings == []
+ # A bare string must not be read as its characters either.
+ assert HealthConfig._from_refactoring_block(
+ {"detectors": {"disabled": "extract_class"}}
+ ).disabled_refactorings == []
+
+ def test_a_negated_glob_is_flagged_rather_than_silently_dead(self) -> None:
+ """A leading '!' has nothing to negate when each rule is its own spec.
+
+ In a .gitignore it re-includes what an earlier line excluded. Here
+ every rule compiles alone, so it matches nothing and the rule quietly
+ never applies — the user's biomarkers stay on and nothing says why.
+ """
+ config = HealthConfig.from_dict(
+ {
+ "rules": [
+ {"path": "!src/keep/**", "disabled_biomarkers": ["complex_method"]},
+ {"path": "src/legacy/**", "disabled_biomarkers": ["dry_violation"]},
+ ]
+ }
+ )
+ disabled = config.per_file_disabled(["src/keep/a.py", "src/legacy/b.py"])
+ assert "src/keep/a.py" not in disabled
+ # The good rule beside it is unaffected.
+ assert disabled["src/legacy/b.py"] == {"dry_violation"}
diff --git a/tests/unit/ingestion/test_graph.py b/tests/unit/ingestion/test_graph.py
index 6aef1af17..5a0ebf082 100644
--- a/tests/unit/ingestion/test_graph.py
+++ b/tests/unit/ingestion/test_graph.py
@@ -2,7 +2,6 @@
from __future__ import annotations
-import asyncio
from datetime import datetime
from pathlib import Path
@@ -631,53 +630,6 @@ class TestToJson:
assert "y.py" in node_ids
-# ---------------------------------------------------------------------------
-# Persistence
-# ---------------------------------------------------------------------------
-
-
-class TestPersist:
- def test_persist_creates_tables(self, tmp_path: Path) -> None:
- import aiosqlite
-
- b = GraphBuilder()
- b.add_file(_parsed("a.py"))
- b.add_file(_parsed("b.py", imports=[_imp("a")]))
- b.build()
-
- db_path = tmp_path / "graph.db"
-
- async def run() -> None:
- await b.persist(db_path, repo_id="test-repo")
- async with aiosqlite.connect(db_path) as db:
- async with db.execute("SELECT * FROM graph_nodes") as cur:
- rows = await cur.fetchall()
- # 2 file nodes + 2 synthetic __module__ symbol nodes
- assert len(rows) == 4
- async with db.execute("SELECT * FROM graph_edges") as cur:
- edges = await cur.fetchall()
- # 1 import edge + 2 defines edges for __module__ symbols
- assert len(edges) == 3
-
- asyncio.run(run())
-
- def test_persist_stores_repo_id(self, tmp_path: Path) -> None:
- import aiosqlite
-
- b = GraphBuilder()
- b.add_file(_parsed("x.py"))
-
- db_path = tmp_path / "graph.db"
-
- async def run() -> None:
- await b.persist(db_path, repo_id="my-project")
- async with aiosqlite.connect(db_path) as db:
- async with db.execute("SELECT repo_id FROM graph_nodes LIMIT 1") as cur:
- row = await cur.fetchone()
- assert row is not None
- assert row[0] == "my-project"
-
-
# ---------------------------------------------------------------------------
# C++ compile_commands.json dependency resolution
# ---------------------------------------------------------------------------
diff --git a/tests/unit/persistence/test_sql_helpers.py b/tests/unit/persistence/test_sql_helpers.py
new file mode 100644
index 000000000..d31069870
--- /dev/null
+++ b/tests/unit/persistence/test_sql_helpers.py
@@ -0,0 +1,67 @@
+"""The shared LIKE escaper.
+
+Every hand-built ``like``/``ilike`` in the tree pairs :func:`escape_like` with
+``escape=LIKE_ESCAPE``. The pairing is the whole point: SQLite declares no
+default escape character, so escaping without passing ``escape=`` does
+nothing at all, which is how the first version of this shipped.
+"""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import select
+
+from repowise.core.persistence.models import GraphNode
+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_like
+from tests.unit.persistence.helpers import insert_repo
+
+
+def test_the_two_like_wildcards_are_escaped() -> None:
+ assert escape_like("a_b") == "a\\_b"
+ assert escape_like("50%") == "50\\%"
+
+
+def test_the_escape_character_itself_is_escaped() -> None:
+ """Otherwise a value ending in a backslash escapes the pattern's own ``%``."""
+ assert escape_like("a\\b") == "a\\\\b"
+ assert escape_like("C:\\src\\main.py") == "C:\\\\src\\\\main.py"
+ # Order matters: escaping the backslash last would double the ones this
+ # function just added.
+ assert escape_like("a\\_b") == "a\\\\\\_b"
+
+
+def test_a_value_with_no_metacharacters_is_untouched() -> None:
+ assert escape_like("src/main.py") == "src/main.py"
+ assert escape_like("") == ""
+
+
+ ("stored", "decoy", "needle"),
+ [
+ ("src/my_module.py", "src/myXmodule.py", "src/my_module.py"),
+ ("docs/50%.md", "docs/50AB.md", "docs/50%.md"),
+ ("src/a\\b.py", "src/aXb.py", "src/a\\b.py"),
+ ],
+)
+async def test_an_escaped_pattern_matches_only_itself(async_session, stored, decoy, needle):
+ """The behaviour the escaping exists for, driven through a real query."""
+ repo = await insert_repo(async_session)
+ for index, node_id in enumerate((stored, decoy)):
+ async_session.add(
+ GraphNode(
+ id=f"gn{index}",
+ repository_id=repo.id,
+ node_id=node_id,
+ node_type="file",
+ language="python",
+ )
+ )
+ await async_session.commit()
+
+ rows = await async_session.execute(
+ select(GraphNode.node_id).where(
+ GraphNode.repository_id == repo.id,
+ GraphNode.node_id.like(f"%{escape_like(needle)}%", escape=LIKE_ESCAPE),
+ )
+ )
+ assert [row[0] for row in rows.all()] == [stored]
diff --git a/tests/unit/server/mcp/test_risk.py b/tests/unit/server/mcp/test_risk.py
index 1bb3dab15..b165c80f3 100644
--- a/tests/unit/server/mcp/test_risk.py
+++ b/tests/unit/server/mcp/test_risk.py
@@ -206,3 +206,44 @@ def test_classify_bus_factor_unknown_team_size_keeps_behaviour():
from repowise.server.mcp_server.tool_risk import _classify_risk_type
assert _classify_risk_type(_bus_factor_meta(), dep_count=1, team_size=None) == "bus-factor-risk"
+
+
+async def test_test_gap_pattern_treats_an_underscore_as_a_literal(session, repo_id):
+ """``_`` is a LIKE wildcard, so an unescaped pattern matched the wrong file.
+
+ The probe builds ``%test_<base>%``. Unescaped, that also matches
+ ``testXbase`` — and for a source file named ``my_module.py`` it matches
+ ``testXmyXmodule`` too. A false hit here makes the tool report a file as
+ tested when nothing tests it, in the directive block reviewers read first.
+ """
+ from repowise.core.persistence.models import GraphNode
+ from repowise.server.mcp_server.tool_risk.assessment import _check_test_gap
+
+ session.add(
+ GraphNode(
+ id="gn-decoy",
+ repository_id=repo_id,
+ node_id="tests/testXmy_module.py",
+ node_type="file",
+ language="python",
+ is_test=True,
+ )
+ )
+ await session.flush()
+
+ # Nothing named test_my_module.py exists, so this is a genuine gap.
+ assert await _check_test_gap(session, repo_id, "src/my_module.py") is True
+
+ session.add(
+ GraphNode(
+ id="gn-real",
+ repository_id=repo_id,
+ node_id="tests/test_my_module.py",
+ node_type="file",
+ language="python",
+ is_test=True,
+ )
+ )
+ await session.flush()
+ assert await _check_test_gap(session, repo_id, "src/my_module.py") is False
diff --git a/tests/unit/server/test_architecture_builder.py b/tests/unit/server/test_architecture_builder.py
index 6a3d2842f..383e69fb8 100644
--- a/tests/unit/server/test_architecture_builder.py
+++ b/tests/unit/server/test_architecture_builder.py
@@ -139,9 +139,9 @@ async def test_layer_assignment_from_communities(client: AsyncClient, app) -> No
async with app.state.session_factory() as session:
nodes = [
- {"node_id": "a/foo.py", "node_type": "file", "language": "python", "symbol_count": 1, "community_id": 1, "community_meta_json": json.dumps({"name": "Group A", "description": "First group"})},
+ {"node_id": "a/foo.py", "node_type": "file", "language": "python", "symbol_count": 1, "community_id": 1, "community_meta_json": json.dumps({"label": "Group A", "cohesion": 0.8})},
{"node_id": "a/bar.py", "node_type": "file", "language": "python", "symbol_count": 2, "community_id": 1},
- {"node_id": "b/baz.py", "node_type": "file", "language": "python", "symbol_count": 3, "community_id": 2, "community_meta_json": json.dumps({"name": "Group B"})},
+ {"node_id": "b/baz.py", "node_type": "file", "language": "python", "symbol_count": 3, "community_id": 2, "community_meta_json": json.dumps({"label": "Group B", "cohesion": 0.5})},
]
await batch_upsert_graph_nodes(session, repo_id, nodes)
await session.commit()
@@ -383,3 +383,76 @@ async def test_backward_compat_c4_endpoints(client: AsyncClient, app) -> None:
params={"container_id": first_cid},
)
assert resp_l3.status_code == 200
+
+
+def test_unreadable_knowledge_graph_file_returns_none(tmp_path: Path) -> None:
+ """A hand-edited artifact must fall through the cascade, not raise.
+
+ The file is user-visible and people do edit it, so a trailing comma has to
+ degrade to the community/directory rungs instead of surfacing as a 500 on
+ the architecture view.
+ """
+ from repowise.server.services.c4_builder.architecture import _load_knowledge_graph
+
+ broken = tmp_path / "knowledge-graph.json"
+ broken.write_text('{"layers": [{"id": "layer:api",}]}')
+ assert _load_knowledge_graph(str(broken)) is None
+
+ truncated = tmp_path / "half.json"
+ truncated.write_text('{"layers": [')
+ assert _load_knowledge_graph(str(truncated)) is None
+
+ missing = tmp_path / "nope.json"
+ assert _load_knowledge_graph(str(missing)) is None
+
+ good = tmp_path / "good.json"
+ good.write_text('{"layers": []}')
+ assert _load_knowledge_graph(str(good)) == {"layers": []}
+
+
+def test_a_knowledge_graph_of_the_wrong_shape_falls_through(tmp_path: Path) -> None:
+ """Valid JSON is not enough — the cascade needs an object with lists in it.
+
+ The loader caught syntax errors but never checked the shape, so a file
+ holding a bare string reached ``kg.get("layers")`` and surfaced as a 500 on
+ the architecture view, which is the thing the loader guard exists to stop.
+ """
+ from repowise.server.services.c4_builder.architecture import _load_knowledge_graph
+
+ for payload in ('"broken"', "[]", "5", "null", "true"):
+ path = tmp_path / f"kg-{abs(hash(payload))}.json"
+ path.write_text(payload)
+ assert _load_knowledge_graph(str(path)) is None, payload
+
+
+def test_malformed_layers_and_tour_entries_are_skipped_not_raised() -> None:
+ """A layer list holding scalars, or a layers value that is not a list.
+
+ Both survive a JSON parse and both used to reach ``.get`` on an int.
+ """
+ from repowise.server.services.c4_builder.architecture import (
+ _layers_from_knowledge_graph,
+ _tour_from_knowledge_graph,
+ )
+
+ assert _layers_from_knowledge_graph({"layers": "abc"}, set()) == []
+ assert _layers_from_knowledge_graph({"layers": [1, 2]}, set()) == []
+ assert _tour_from_knowledge_graph({"tour": "abc"}) == []
+ assert _tour_from_knowledge_graph({"tour": [1, 2]}) == []
+
+ # A good entry beside a bad one still loads.
+ layers = _layers_from_knowledge_graph(
+ {"layers": [7, {"id": "layer:api", "name": "API", "nodeIds": ["file:a.py"]}]},
+ {"a.py"},
+ )
+ assert [layer["id"] for layer in layers] == ["layer:api"]
+ assert layers[0]["node_ids"] == ["a.py"]
+
+
+def test_a_layer_whose_node_ids_are_not_a_list_is_skipped() -> None:
+ from repowise.server.services.c4_builder.architecture import _layers_from_knowledge_graph
+
+ layers = _layers_from_knowledge_graph(
+ {"layers": [{"id": "layer:api", "name": "API", "nodeIds": 5}]}, {"a.py"}
+ )
+ assert layers[0]["node_ids"] == []
diff --git a/tests/unit/server/test_c4.py b/tests/unit/server/test_c4.py
index 7f8690de7..8be35239c 100644
--- a/tests/unit/server/test_c4.py
+++ b/tests/unit/server/test_c4.py
@@ -7,6 +7,7 @@ from pathlib import Path
from httpx import AsyncClient
+from repowise.core.ids import ComponentId, parse
from repowise.core.persistence import (
batch_upsert_graph_edges,
batch_upsert_graph_nodes,
@@ -109,7 +110,12 @@ async def test_l3_endpoint_returns_components_for_container(client: AsyncClient,
# bucket, never the leaky "_root" token.
comp_names = {c["name"] for c in body["components"]}
assert comp_names == {"(root)"}
- assert "_root" not in {c["id"] for c in body["components"]}
+ comp_ids = {c["id"] for c in body["components"]}
+ assert "_root" not in comp_ids
+ # The root bucket must not smuggle the symbol separator into a ``cmp:`` id:
+ # ``cmp:packages/core::root`` parses back as a symbol called ``root``.
+ assert all("::" not in cid for cid in comp_ids)
+ assert all(parse(cid) == ComponentId("packages/core", is_root_bucket=True) for cid in comp_ids)
# Only fastapi (used from packages/core), react is filtered out
assert {e["name"] for e in body["external_systems"]} == {"fastapi"}
@@ -130,3 +136,108 @@ async def test_l1_endpoint_on_empty_repo(client: AsyncClient) -> None:
body = resp.json()
assert body["external_systems"] == []
assert body["system"]["name"] == "test-repo"
+
+
+async def test_structurizr_endpoint_returns_a_model_fragment(
+ client: AsyncClient, app
+) -> None:
+ repo_id = await _seed_two_containers(client, app)
+ resp = await client.get(f"/api/graph/{repo_id}/c4/structurizr")
+ assert resp.status_code == 200
+ assert resp.headers["content-type"].startswith("text/plain")
+ assert 'filename="repowise-model.dsl"' in resp.headers["content-disposition"]
+ body = resp.text
+ assert body.startswith("#")
+ assert "\nmodel {\n" in body
+ assert "container " in body
+
+
+async def test_structurizr_endpoint_standalone_returns_a_workspace(
+ client: AsyncClient, app
+) -> None:
+ repo_id = await _seed_two_containers(client, app)
+ resp = await client.get(
+ f"/api/graph/{repo_id}/c4/structurizr",
+ params={"standalone": "true", "components": "true"},
+ )
+ assert resp.status_code == 200
+ assert 'filename="workspace.dsl"' in resp.headers["content-disposition"]
+ assert "workspace " in resp.text
+ assert "views {" in resp.text
+ assert "component " in resp.text
+
+
+async def test_structurizr_endpoint_can_drop_externals(client: AsyncClient, app) -> None:
+ repo_id = await _seed_two_containers(client, app)
+ resp = await client.get(
+ f"/api/graph/{repo_id}/c4/structurizr", params={"externals": "false"}
+ )
+ assert resp.status_code == 200
+ assert "FastAPI" not in resp.text
+
+
+async def test_structurizr_endpoint_on_an_empty_repo(client: AsyncClient) -> None:
+ repo = await create_test_repo(client)
+ resp = await client.get(f"/api/graph/{repo['id']}/c4/structurizr")
+ assert resp.status_code == 200
+ assert "softwareSystem" in resp.text
+
+
+def test_an_awkward_directory_name_still_yields_a_usable_id() -> None:
+ """A directory named ``a::b`` is legal on POSIX and reaches these helpers.
+
+ The path is repo-derived and lands on the request path with no handler
+ above it, so a raise here would be a 500 on the C4 endpoints and a hard
+ abort of the export. Prefixed ids are unambiguous whatever they contain,
+ so these round-trip instead.
+ """
+ from repowise.core.ids import ComponentId, ContainerId, parse
+ from repowise.server.services.c4_builder.components import component_id
+ from repowise.server.services.c4_builder.containers import container_id
+
+ assert parse(container_id("weird::pkg")) == ContainerId("weird::pkg")
+ assert parse(component_id("weird::dir")) == ComponentId("weird::dir")
+ assert parse(component_id("weird::dir", is_root_bucket=True)) == ComponentId(
+ "weird::dir", is_root_bucket=True
+ )
+
+
+def test_a_directory_named_like_the_root_marker_is_skipped_not_fatal() -> None:
+ """One unspellable directory costs its own component, not the whole view."""
+ from repowise.server.services.c4_builder.components import _bucket_into_components
+
+ class _Node:
+ def __init__(self, node_id: str) -> None:
+ self.node_id = node_id
+ self.symbol_count = 1
+ self.language = "python"
+
+ components, file_index = _bucket_into_components(
+ [_Node("pkg/odd#root/a.py"), _Node("pkg/fine/b.py")],
+ "pkg",
+ "(root)",
+ )
+ names = {c.name for c in components}
+ assert "fine" in names
+ assert not any("#root" in c.path for c in components)
+ assert "pkg/odd#root/a.py" not in file_index
+
+
+def test_the_batched_and_per_container_paths_agree_on_a_nested_container() -> None:
+ """A container inside another is where the two ownership rules could drift.
+
+ ``detect_components`` rejects a file matching any sibling root's prefix, so
+ with containers ``apps`` and ``apps/web`` a file under ``apps/web`` is
+ claimed by neither. That is a real gap, but the batched path's contract is
+ to agree with the per-container one element for element — so it must
+ reproduce it rather than quietly improving on it.
+ """
+ from repowise.server.services.c4_builder.components import _matching_roots, _owned_by
+
+ roots = ["apps", "apps/web"]
+ for node_id in ("apps/x.ts", "apps/web/y.ts", "other/z.ts"):
+ batched = _matching_roots(node_id, roots)
+ for root in roots:
+ siblings = tuple(r + "/" for r in roots if r != root)
+ per_container = _owned_by(node_id, root, siblings)
+ assert per_container is (batched == [root]), (node_id, root)
diff --git a/tests/unit/server/test_c4_box_signals.py b/tests/unit/server/test_c4_box_signals.py
new file mode 100644
index 000000000..ac6c3f08b
--- /dev/null
+++ b/tests/unit/server/test_c4_box_signals.py
@@ -0,0 +1,151 @@
+"""Tests for rolling per-file health signals up to a C4 box.
+
+Pure aggregation, so no database. The rules that matter are the ones that
+would misinform a reader: how ownership is picked, and what "unknown" means
+as distinct from zero.
+"""
+
+from __future__ import annotations
+
+from repowise.server.services.c4_builder.signals import build_box_signals
+
+FILES = {
+ "pkg/a.py": "box:one",
+ "pkg/b.py": "box:one",
+ "pkg/c.py": "box:one",
+ "other/d.py": "box:two",
+}
+
+
+def test_every_box_appears_even_with_no_signals() -> None:
+ signals = build_box_signals(FILES)
+ assert set(signals) == {"box:one", "box:two"}
+ assert signals["box:one"].hotspot_count == 0
+ assert signals["box:one"].primary_owner is None
+
+
+def test_hotspots_and_dead_files_are_counted_per_box() -> None:
+ signals = build_box_signals(
+ FILES, hotspot_paths=["pkg/a.py", "pkg/b.py"], dead_paths=["other/d.py"]
+ )
+ assert signals["box:one"].hotspot_count == 2
+ assert signals["box:one"].dead_count == 0
+ assert signals["box:two"].dead_count == 1
+
+
+def test_a_box_collects_every_layer_its_files_belong_to() -> None:
+ """A directory can straddle layers; picking one would be a guess."""
+ signals = build_box_signals(
+ FILES,
+ file_layers={"pkg/a.py": "Domain", "pkg/b.py": "API", "pkg/c.py": "Domain"},
+ )
+ assert signals["box:one"].layers == ("API", "Domain")
+ assert signals["box:two"].layers == ()
+
+
+def test_the_primary_owner_is_whoever_owns_the_most_files() -> None:
+ signals = build_box_signals(
+ FILES,
+ file_owners={"pkg/a.py": "Ada", "pkg/b.py": "Ada", "pkg/c.py": "Grace"},
+ )
+ assert signals["box:one"].primary_owner == "Ada"
+ assert signals["box:one"].primary_owner_pct == 66.7
+
+
+def test_an_ownership_tie_breaks_by_name_so_re_exports_do_not_churn() -> None:
+ signals = build_box_signals(
+ {"a.py": "box", "b.py": "box"},
+ file_owners={"a.py": "Zoe", "b.py": "Ada"},
+ )
+ first = signals["box"].primary_owner
+ again = build_box_signals(
+ {"b.py": "box", "a.py": "box"},
+ file_owners={"b.py": "Ada", "a.py": "Zoe"},
+ )["box"].primary_owner
+ assert first == again == "Zoe"
+
+
+def test_the_owner_percentage_counts_every_file_in_the_box() -> None:
+ """This used to divide by the attributed files and so always neared 100.
+
+ A reader takes ``repowise.ownerPct`` as "this person owns that much of the
+ box". Dividing by the files git resolved an owner for answers a different
+ question and reads as a much stronger claim than the data supports.
+ """
+ signals = build_box_signals(FILES, file_owners={"pkg/a.py": "Ada"})
+ assert signals["box:one"].primary_owner == "Ada"
+ assert signals["box:one"].primary_owner_pct == 33.3
+
+
+def test_bus_factor_is_the_worst_case_not_the_average() -> None:
+ """One file only one person understands is the risk; a mean hides it."""
+ signals = build_box_signals(
+ FILES, file_bus_factors={"pkg/a.py": 5, "pkg/b.py": 1, "pkg/c.py": 4}
+ )
+ assert signals["box:one"].min_bus_factor == 1
+
+
+def test_missing_signals_stay_none_rather_than_becoming_zero() -> None:
+ signals = build_box_signals(FILES)
+ box = signals["box:one"]
+ assert box.min_bus_factor is None
+ assert box.primary_owner_pct is None
+
+
+def test_a_bus_factor_of_zero_is_taken_at_face_value_here() -> None:
+ """This function trusts its input; dropping the seeded 0 is the caller's job.
+
+ The name this test used to carry claimed it pinned the "0 means unknown"
+ rule, but it never passed a 0 — so it would have passed with that rule
+ deleted. The rule lives in ``_per_file_signals``, and
+ ``test_c4_model.py`` exercises it there. What is worth pinning *here* is
+ that a 0 arriving is not silently reinterpreted, because that is what
+ makes the caller's filter the single place the decision is made.
+ """
+ signals = build_box_signals(
+ FILES, file_bus_factors={"pkg/a.py": 0, "pkg/b.py": 3}
+ )
+ assert signals["box:one"].min_bus_factor == 0
+
+
+def test_ownership_percentage_divides_by_the_whole_box() -> None:
+ """The denominator is the box, not the files git happened to attribute.
+
+ Dividing by files-with-a-known-owner made one attributed file out of four
+ read as "one person owns 100% of this" — a fabricated number, which is
+ worse than the missing one the module's own rule asks for.
+ """
+ signals = build_box_signals(
+ {f"pkg/f{i}.py": "pkg:a" for i in range(4)},
+ file_owners={"pkg/f0.py": "Ada"},
+ )
+ assert signals["pkg:a"].primary_owner == "Ada"
+ assert signals["pkg:a"].primary_owner_pct == 25.0
+
+
+def test_ownership_is_omitted_when_almost_nothing_is_attributed() -> None:
+ """One owner out of five hundred files is not an ownership signal."""
+ signals = build_box_signals(
+ {f"pkg/f{i}.py": "pkg:a" for i in range(500)},
+ file_owners={"pkg/f0.py": "Ada"},
+ )
+ assert signals["pkg:a"].primary_owner is None
+ assert signals["pkg:a"].primary_owner_pct is None
+
+
+def test_a_repo_with_no_churn_data_reports_no_hotspot_count() -> None:
+ """Zero hotspots and never having looked are different claims.
+
+ An index-only run has no git metadata, so every box would otherwise
+ serialize ``repowise.hotspots "0"`` — a clean bill of health nobody
+ measured.
+ """
+ signals = build_box_signals(FILES, churn_measured=False)
+ assert signals["box:one"].hotspot_count is None
+ # Dead code has no such distinction available, so zero stays zero.
+ assert signals["box:one"].dead_count == 0
+
+
+def test_a_measured_zero_is_still_reported() -> None:
+ signals = build_box_signals(FILES, hotspot_paths=())
+ assert signals["box:one"].hotspot_count == 0
diff --git a/tests/unit/server/test_c4_model.py b/tests/unit/server/test_c4_model.py
new file mode 100644
index 000000000..7dc73d951
--- /dev/null
+++ b/tests/unit/server/test_c4_model.py
@@ -0,0 +1,413 @@
+"""Tests for build_model — the one-pass whole-model C4 build.
+
+The point of these is agreement: the batched path must produce exactly what
+looping the per-container path produces, or the export and the dashboard tell
+users different stories about the same repo.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from httpx import AsyncClient
+
+from repowise.core.persistence import (
+ batch_upsert_graph_edges,
+ batch_upsert_graph_nodes,
+ bulk_upsert_external_systems,
+ link_graph_nodes_to_external_systems,
+)
+from repowise.server.services.c4_builder import build_l1, build_l2, build_l3, build_model
+
+
+async def _create_repo(client: AsyncClient) -> dict:
+ repo_dir = Path(tempfile.mkdtemp()) / "test-repo"
+ repo_dir.mkdir(exist_ok=True)
+ (repo_dir / ".git").mkdir(exist_ok=True)
+ resp = await client.post(
+ "/api/repos",
+ json={
+ "index": False,
+ "name": "test-repo",
+ "local_path": str(repo_dir),
+ "url": "https://github.com/example/test-repo",
+ },
+ )
+ assert resp.status_code == 201
+ return resp.json()
+
+
+async def _seed(client: AsyncClient, app) -> str:
+ """A repo with three containers, nested components, and two externals.
+
+ Deliberately includes a file at a container root (the ``(root)`` bucket),
+ a pass-through ``src`` directory, and a container whose path is a prefix
+ of another's name — the three shapes the ownership rules get wrong when
+ they are written twice.
+ """
+ repo = await _create_repo(client)
+ repo_id = repo["id"]
+
+ async with app.state.session_factory() as session:
+ nodes = [
+ # packages/core — files at the root plus a nested feature dir
+ {
+ "node_id": "packages/core/setup.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 1,
+ },
+ {
+ "node_id": "packages/core/src/ingestion/parser.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 5,
+ },
+ {
+ "node_id": "packages/core/src/ingestion/graph.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 3,
+ },
+ {
+ "node_id": "packages/core/src/analysis/health.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 4,
+ },
+ # packages/core-extras — shares a prefix with packages/core
+ {
+ "node_id": "packages/core-extras/plugin.py",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 2,
+ },
+ # packages/web
+ {
+ "node_id": "packages/web/src/pages/index.tsx",
+ "node_type": "file",
+ "language": "typescript",
+ "symbol_count": 2,
+ },
+ {
+ "node_id": "packages/web/package.json",
+ "node_type": "file",
+ "language": "json",
+ "symbol_count": 0,
+ },
+ {
+ "node_id": "external:fastapi",
+ "node_type": "file",
+ "language": "python",
+ "symbol_count": 0,
+ },
+ {
+ "node_id": "external:react",
+ "node_type": "file",
+ "language": "typescript",
+ "symbol_count": 0,
+ },
+ ]
+ await batch_upsert_graph_nodes(session, repo_id, nodes)
+ await batch_upsert_graph_edges(
+ session,
+ repo_id,
+ [
+ {
+ "source_node_id": "packages/web/src/pages/index.tsx",
+ "target_node_id": "packages/core/src/ingestion/graph.py",
+ "edge_type": "imports",
+ },
+ {
+ "source_node_id": "packages/core/src/analysis/health.py",
+ "target_node_id": "packages/core/src/ingestion/graph.py",
+ "edge_type": "imports",
+ },
+ {
+ "source_node_id": "packages/core/src/ingestion/parser.py",
+ "target_node_id": "external:fastapi",
+ "edge_type": "imports",
+ },
+ {
+ "source_node_id": "packages/web/src/pages/index.tsx",
+ "target_node_id": "external:react",
+ "edge_type": "imports",
+ },
+ {
+ "source_node_id": "packages/core-extras/plugin.py",
+ "target_node_id": "packages/core/src/ingestion/parser.py",
+ "edge_type": "imports",
+ },
+ ],
+ )
+ id_map = await bulk_upsert_external_systems(
+ session,
+ repo_id,
+ [
+ {
+ "name": "fastapi",
+ "display_name": "FastAPI",
+ "ecosystem": "pypi",
+ "category": "framework",
+ "version": "0.110",
+ "declared_in": "packages/core/pyproject.toml",
+ "is_dev_dep": False,
+ },
+ {
+ "name": "react",
+ "display_name": "React",
+ "ecosystem": "npm",
+ "category": "framework",
+ "version": "^18",
+ "declared_in": "packages/web/package.json",
+ "is_dev_dep": False,
+ },
+ ],
+ )
+ name_to_id = {n: sid for (n, _), sid in id_map.items()}
+ await link_graph_nodes_to_external_systems(session, repo_id, name_to_id)
+ await session.commit()
+ return repo_id
+
+
+async def test_containers_match_the_per_level_build(client: AsyncClient, app) -> None:
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ l2 = await build_l2(session, repo_id)
+ model = await build_model(session, repo_id)
+
+ assert model.containers == l2.containers
+ assert model.container_relations == l2.relations
+
+
+async def test_components_match_the_per_container_build(client: AsyncClient, app) -> None:
+ """The whole point of the batched path: identical output, one read."""
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo_id)
+ per_container = {}
+ for container in model.containers:
+ l3 = await build_l3(session, repo_id, container.id)
+ assert l3 is not None
+ per_container[container.id] = l3.components
+
+ assert model.components_by_container == per_container
+ # And the fixture actually exercises the interesting shapes.
+ assert per_container, "no containers detected — the fixture proves nothing"
+ every_component = [c for comps in per_container.values() for c in comps]
+ assert any(c.name == "(root)" for c in every_component)
+ assert any(c.name == "ingestion" for c in every_component)
+
+
+async def test_a_shared_path_prefix_does_not_steal_files(client: AsyncClient, app) -> None:
+ """``packages/core`` must not absorb ``packages/core-extras``."""
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo_id)
+
+ by_path = {c.path: c for c in model.containers}
+ if "packages/core" in by_path and "packages/core-extras" in by_path:
+ core_components = model.components_by_container[by_path["packages/core"].id]
+ assert all("core-extras" not in c.path for c in core_components)
+
+
+async def test_component_relations_keep_both_ends_at_component_level(
+ client: AsyncClient, app
+) -> None:
+ """A cross-container edge names the real component, not its container."""
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo_id)
+
+ component_ids = {c.id for comps in model.components_by_container.values() for c in comps}
+ internal = [
+ r
+ for r in model.component_relations
+ if r.source_id in component_ids and r.target_id in component_ids
+ ]
+ assert internal, "expected at least one component-to-component relation"
+
+
+async def test_components_can_be_skipped(client: AsyncClient, app) -> None:
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo_id, include_components=False)
+
+ assert model.containers
+ assert model.components_by_container == {}
+ assert model.component_relations == []
+ # Containers and their relations are unaffected by the opt-out.
+ async with app.state.session_factory() as session:
+ full = await build_model(session, repo_id)
+ assert model.containers == full.containers
+ assert model.container_relations == full.container_relations
+
+
+async def test_externals_are_pruned_to_the_ones_actually_used(client: AsyncClient, app) -> None:
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo_id)
+
+ assert {e.name for e in model.external_systems} == {"fastapi", "react"}
+
+
+async def test_empty_repo_builds_an_empty_model(client: AsyncClient, app) -> None:
+ repo = await _create_repo(client)
+ async with app.state.session_factory() as session:
+ model = await build_model(session, repo["id"])
+
+ assert model.containers == []
+ assert model.components_by_container == {}
+ assert model.external_systems == []
+ assert model.system.name == "test-repo"
+
+
+async def test_actor_relations_match_the_per_level_build(client: AsyncClient, app) -> None:
+ """People without an edge to the system are orphans in every view.
+
+ Structurizr's ``systemContext`` includes the system plus what is *related*
+ to it, so a person nothing points at is simply absent — while the product's
+ own L1 view shows the same actor connected. build_model derived the people
+ and then dropped the edges that make them mean anything.
+ """
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ l1 = await build_l1(session, repo_id)
+ model = await build_model(session, repo_id)
+
+ assert model.people == l1.people
+ assert model.people, "fixture has no actors — the test proves nothing"
+
+ person_ids = {p.id for p in model.people}
+ expected = [r for r in l1.relations if r.source_id in person_ids]
+ assert model.actor_relations == expected
+ assert {r.target_id for r in model.actor_relations} == {model.system.id}
+
+
+async def test_a_seeded_zero_bus_factor_is_read_as_unknown(client: AsyncClient, app) -> None:
+ """The indexer seeds bus_factor at 0 and overwrites it only where there is history.
+
+ So a 0 reaching the rollup would drag every box's minimum to 0 and the
+ export would say "nobody owns this" about a repo it simply has no commit
+ data for. The filter lives in the builder, and nothing exercised it.
+ """
+ from repowise.core.persistence.models import GitMetadata
+
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ session.add_all(
+ [
+ GitMetadata(
+ id="gm-zero",
+ repository_id=repo_id,
+ file_path="packages/core/setup.py",
+ bus_factor=0,
+ primary_owner_name="Ada",
+ ),
+ GitMetadata(
+ id="gm-real",
+ repository_id=repo_id,
+ file_path="packages/core/src/ingestion/parser.py",
+ bus_factor=2,
+ primary_owner_name="Ada",
+ ),
+ ]
+ )
+ await session.commit()
+ model = await build_model(session, repo_id)
+
+ core = next(c for c in model.containers if c.path == "packages/core")
+ assert model.box_signals[core.id].min_bus_factor == 2
+
+
+async def test_a_layer_whose_member_list_is_not_a_list_is_skipped(
+ client: AsyncClient, app
+) -> None:
+ """A bare JSON string parses fine and then iterates into single letters.
+
+ Only a decode failure was guarded, so ``"abc"`` produced three file paths
+ called "a", "b" and "c", each carrying the layer's name.
+ """
+ from repowise.core.persistence.models import KnowledgeGraphLayer
+ from repowise.server.services.c4_builder import _per_file_signals
+
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ session.add_all(
+ [
+ KnowledgeGraphLayer(
+ id="kl-str",
+ repository_id=repo_id,
+ layer_id="layer:str",
+ name="FromString",
+ node_ids_json='"abc"',
+ display_order=0,
+ ),
+ KnowledgeGraphLayer(
+ id="kl-obj",
+ repository_id=repo_id,
+ layer_id="layer:obj",
+ name="FromObject",
+ node_ids_json='{"packages/core/setup.py": 1}',
+ display_order=1,
+ ),
+ KnowledgeGraphLayer(
+ id="kl-good",
+ repository_id=repo_id,
+ layer_id="layer:good",
+ name="Ingestion",
+ node_ids_json='["file:packages/core/src/ingestion/parser.py"]',
+ display_order=2,
+ ),
+ ]
+ )
+ await session.commit()
+ signals = await _per_file_signals(session, repo_id)
+
+ file_layers = signals["file_layers"]
+ assert file_layers == {"packages/core/src/ingestion/parser.py": "Ingestion"}
+
+
+async def test_the_tour_is_ordered_and_carries_its_layer_name(
+ client: AsyncClient, app
+) -> None:
+ """Steps arrive unordered and name a layer by id, not by its display name."""
+ from repowise.core.persistence.models import KnowledgeGraphLayer, KnowledgeGraphTourStep
+
+ repo_id = await _seed(client, app)
+ async with app.state.session_factory() as session:
+ session.add(
+ KnowledgeGraphLayer(
+ id="kl-1",
+ repository_id=repo_id,
+ layer_id="layer:ingestion",
+ name="Ingestion",
+ node_ids_json="[]",
+ display_order=0,
+ )
+ )
+ session.add_all(
+ [
+ KnowledgeGraphTourStep(
+ id="ts-2",
+ repository_id=repo_id,
+ step_order=2,
+ title="Then ingestion",
+ layer_id="layer:ingestion",
+ ),
+ KnowledgeGraphTourStep(
+ id="ts-1",
+ repository_id=repo_id,
+ step_order=1,
+ title="Start here",
+ layer_id=None,
+ ),
+ ]
+ )
+ await session.commit()
+ model = await build_model(session, repo_id)
+
+ assert [step.title for step in model.tour] == ["Start here", "Then ingestion"]
+ assert model.tour[1].layer_name == "Ingestion"
+ assert model.tour[0].layer_name is None
diff --git a/tests/unit/server/test_structurizr_export.py b/tests/unit/server/test_structurizr_export.py
new file mode 100644
index 000000000..696081548
--- /dev/null
+++ b/tests/unit/server/test_structurizr_export.py
@@ -0,0 +1,1009 @@
+"""Tests for the Structurizr DSL emitter.
+
+The emitter takes dataclasses and returns text, so everything here runs
+without a database. The properties that matter to a user who commits the
+output are determinism and identifier stability — those get their own tests
+rather than being implied by a golden file.
+"""
+
+from __future__ import annotations
+
+import random
+import re
+from dataclasses import replace
+
+import pytest
+
+from repowise.server.services.c4_builder.models import (
+ BoxSignals,
+ C4Model,
+ Component,
+ Container,
+ ExternalSystemView,
+ Person,
+ Relation,
+ System,
+ TourStep,
+)
+from repowise.server.services.c4_builder.structurizr import system_identifier, to_dsl
+from repowise.server.services.c4_builder.structurizr.identifiers import (
+ identifiers_for,
+ sanitize,
+)
+
+
+def _model(**overrides) -> C4Model:
+ core = Container(
+ id="pkg:packages/core",
+ name="core",
+ path="packages/core",
+ language="python",
+ file_count=120,
+ symbol_count=800,
+ hotspot_count=3,
+ dead_count=1,
+ )
+ web = Container(
+ id="pkg:packages/web",
+ name="web",
+ path="packages/web",
+ language="typescript",
+ file_count=40,
+ symbol_count=150,
+ )
+ defaults = dict(
+ system=System(id="sys:repo-1", name="repowise", description="Docs engine"),
+ people=[
+ Person(
+ id="person:cli",
+ name="CLI user",
+ description="Runs commands from a terminal",
+ kind="cli",
+ )
+ ],
+ containers=[core, web],
+ components_by_container={
+ core.id: [
+ Component(
+ id="cmp:packages/core/ingestion",
+ name="ingestion",
+ path="packages/core/ingestion",
+ container_id=core.id,
+ file_count=30,
+ symbol_count=200,
+ ),
+ Component(
+ id="cmp:packages/core#root",
+ name="(root)",
+ path="packages/core",
+ container_id=core.id,
+ file_count=2,
+ symbol_count=4,
+ ),
+ ],
+ web.id: [],
+ },
+ external_systems=[
+ ExternalSystemView(
+ id="ext:fastapi",
+ name="fastapi",
+ display_name="FastAPI",
+ category="framework",
+ ecosystem="pypi",
+ version="0.110",
+ )
+ ],
+ container_relations=[
+ Relation(
+ source_id=web.id,
+ target_id=core.id,
+ label="imports",
+ edge_count=60,
+ edge_types=("imports",),
+ coupling="tight",
+ ),
+ Relation(
+ source_id=core.id,
+ target_id="ext:fastapi",
+ label="imports",
+ edge_count=4,
+ edge_types=("imports",),
+ coupling="loose",
+ ),
+ ],
+ component_relations=[
+ Relation(
+ source_id="cmp:packages/core#root",
+ target_id="cmp:packages/core/ingestion",
+ label="calls",
+ edge_count=12,
+ edge_types=("calls",),
+ coupling="moderate",
+ )
+ ],
+ )
+ defaults.update(overrides)
+ return C4Model(**defaults)
+
+
+# ---------------------------------------------------------------------------
+# Identifiers
+# ---------------------------------------------------------------------------
+
+
+def test_sanitize_keeps_only_legal_characters() -> None:
+ assert sanitize("pkg:packages/core") == "pkg_packages_core"
+ assert sanitize("cmp:packages/core#root") == "cmp_packages_core_root"
+ assert sanitize("ext:@scope/pkg") == "ext_scope_pkg"
+
+
+def test_an_identifier_never_starts_with_a_digit() -> None:
+ identifier = sanitize("2fa/handler.py")
+ assert not identifier[0].isdigit()
+
+
+def test_colliding_ids_both_get_a_suffix_derived_from_the_id() -> None:
+ """Not from iteration order — that is what makes re-exports churn."""
+ mapping = identifiers_for(["a/b", "a-b", "a.b"])
+ assert len(set(mapping.values())) == 3
+ # The same set in any order produces the same answer.
+ assert mapping == identifiers_for(["a.b", "a-b", "a/b"])
+ # And nobody keeps the bare slug, so which one "won" cannot change.
+ assert "a_b" not in mapping.values()
+
+
+def test_adding_an_element_never_renames_an_existing_one() -> None:
+ before = identifiers_for(["pkg:packages/core", "pkg:packages/web"])
+ after = identifiers_for(["pkg:packages/core", "pkg:packages/web", "pkg:packages/cli"])
+ for raw, identifier in before.items():
+ assert after[raw] == identifier
+
+
+def test_identifiers_are_unique_across_a_large_scope() -> None:
+ raw = [f"cmp:packages/core/{n}" for n in ("a b", "a-b", "a_b", "a/b", "a.b")]
+ mapping = identifiers_for(raw)
+ assert len(set(mapping.values())) == len(raw)
+
+
+# ---------------------------------------------------------------------------
+# Emission
+# ---------------------------------------------------------------------------
+
+
+def test_fragment_is_a_bare_model_block() -> None:
+ dsl = to_dsl(_model())
+ assert dsl.startswith("#")
+ assert "\nmodel {\n" in dsl
+ # No workspace or views block of its own — only the illustration in the
+ # header comment, which is not code.
+ code = [line for line in dsl.splitlines() if not line.strip().startswith("#")]
+ assert not any("workspace " in line for line in code)
+ assert not any("views {" in line for line in code)
+
+
+def test_fragment_explains_how_to_use_itself() -> None:
+ """Someone who never saw the terminal output still knows what to do."""
+ dsl = to_dsl(_model())
+ assert "!include repowise-model.dsl" in dsl
+ assert "do not hand-edit" in dsl
+ # The include only parses inside the workspace block, so the snippet has
+ # to show that rather than the bare line.
+ assert 'workspace "your name" {' in dsl
+
+
+def test_there_is_no_timestamp_in_the_output() -> None:
+ """A timestamp would make every regeneration a diff."""
+ dsl = to_dsl(_model(), standalone=True, include_components=True)
+ assert not re.search(r"\d{4}-\d{2}-\d{2}", dsl)
+ assert not re.search(r"\d{2}:\d{2}:\d{2}", dsl)
+
+
+def _shuffled(model: C4Model, seed: int) -> C4Model:
+ """The same model with every list rebuilt in a different order.
+
+ Nothing here changes what the model *says* — only the order the builder
+ happened to produce its lists in, which is exactly what an emitter must
+ not be sensitive to.
+ """
+ rng = random.Random(seed)
+
+ def _mix(items):
+ out = list(items)
+ rng.shuffle(out)
+ return out
+
+ return replace(
+ model,
+ people=_mix(model.people),
+ containers=_mix(model.containers),
+ external_systems=_mix(model.external_systems),
+ container_relations=_mix(model.container_relations),
+ component_relations=_mix(model.component_relations),
+ components_by_container={
+ cid: _mix(components) for cid, components in model.components_by_container.items()
+ },
+ )
+
+
[email protected]("standalone", [False, True])
[email protected]("components", [False, True])
+def test_emission_does_not_depend_on_input_order(standalone, components) -> None:
+ """The property a committed file needs: same model in, same bytes out.
+
+ Comparing ``to_dsl(model)`` with itself proves nothing — one object has
+ one list order. Every sort in the emitter could be deleted and that test
+ would still pass. These build the same model several ways round.
+ """
+ base = _signals_model()
+ expected = to_dsl(base, standalone=standalone, include_components=components)
+ for seed in range(5):
+ again = to_dsl(_shuffled(base, seed), standalone=standalone, include_components=components)
+ assert again == expected, seed
+
+
+def test_relations_alike_but_for_coupling_still_have_a_stable_order() -> None:
+ """The sort key left out the one field that changes what is emitted."""
+ pair = [
+ Relation(
+ source_id="pkg:packages/web",
+ target_id="pkg:packages/core",
+ label="imports",
+ edge_count=1,
+ edge_types=("imports",),
+ coupling=coupling,
+ )
+ for coupling in ("tight", "loose")
+ ]
+ assert to_dsl(_model(container_relations=pair)) == to_dsl(
+ _model(container_relations=list(reversed(pair)))
+ )
+
+
+def test_containers_and_externals_are_emitted() -> None:
+ dsl = to_dsl(_model())
+ assert 'container "core" "120 files, 800 symbols" "python"' in dsl
+ assert 'softwareSystem "FastAPI" "framework · pypi · 0.110"' in dsl
+ assert 'tags "External"' in dsl
+ assert 'person "CLI user" "Runs commands from a terminal"' in dsl
+
+
+def test_components_are_off_by_default_and_nest_when_asked_for() -> None:
+ without = to_dsl(_model())
+ assert "component " not in without
+
+ with_components = to_dsl(_model(), include_components=True)
+ assert 'component "ingestion" "30 files, 200 symbols"' in with_components
+ assert 'component "(root)" "2 files, 4 symbols"' in with_components
+
+
+def test_externals_can_be_left_out() -> None:
+ dsl = to_dsl(_model(), include_externals=False)
+ assert "FastAPI" not in dsl
+ # And the relation pointing at it goes too, rather than dangling.
+ assert "ext_fastapi" not in dsl
+
+
+def test_relationships_carry_the_verb_and_the_coupling_tag() -> None:
+ dsl = to_dsl(_model())
+ assert "-> " in dsl
+ assert '"imports"' in dsl
+ assert 'tags "Tight"' in dsl
+ assert 'tags "Loose"' in dsl
+
+
+def test_a_relationship_never_references_an_element_we_did_not_emit() -> None:
+ """A dangling reference is a parse error, not a missing arrow."""
+ dsl = to_dsl(_model(), include_components=False)
+ declared = {line.split(" = ", 1)[0].strip() for line in dsl.splitlines() if " = " in line}
+ for line in dsl.splitlines():
+ stripped = line.strip()
+ if "->" not in stripped or stripped.startswith("#"):
+ continue
+ source, _, rest = stripped.partition(" -> ")
+ target = rest.split(" ", 1)[0].split("{", 1)[0].strip()
+ assert source.strip() in declared, f"undeclared source in: {stripped}"
+ assert target in declared, f"undeclared target in: {stripped}"
+
+
+def test_standalone_wraps_the_model_and_adds_views() -> None:
+ dsl = to_dsl(_model(), standalone=True, include_components=True)
+ assert dsl.count("workspace ") == 1
+ assert "views {" in dsl
+ assert "systemContext " in dsl
+ assert "container " in dsl
+ assert "styles {" in dsl
+ # The fragment's include instruction would be wrong here.
+ assert "!include" not in dsl
+
+
+def test_a_large_component_view_is_capped_and_says_so() -> None:
+ core = Container(
+ id="pkg:packages/big",
+ name="big",
+ path="packages/big",
+ language="python",
+ file_count=500,
+ symbol_count=1,
+ )
+ components = [
+ Component(
+ id=f"cmp:packages/big/mod{n:03d}",
+ name=f"mod{n:03d}",
+ path=f"packages/big/mod{n:03d}",
+ container_id=core.id,
+ file_count=n,
+ symbol_count=n,
+ )
+ for n in range(40)
+ ]
+ dsl = to_dsl(
+ _model(
+ containers=[core],
+ components_by_container={core.id: components},
+ container_relations=[],
+ component_relations=[],
+ external_systems=[],
+ ),
+ standalone=True,
+ include_components=True,
+ )
+ assert "largest of 40 components" in dsl
+
+
+def test_braces_balance() -> None:
+ for standalone in (False, True):
+ for components in (False, True):
+ dsl = to_dsl(_model(), standalone=standalone, include_components=components)
+ body = "\n".join(line for line in dsl.splitlines() if not line.strip().startswith("#"))
+ assert body.count("{") == body.count("}"), (standalone, components)
+
+
+def test_no_line_has_trailing_whitespace() -> None:
+ dsl = to_dsl(_model(), standalone=True, include_components=True)
+ for line in dsl.splitlines():
+ assert line == line.rstrip(), repr(line)
+
+
[email protected]("standalone", [False, True])
+def test_an_empty_model_still_emits_valid_structure(standalone: bool) -> None:
+ empty = C4Model(
+ system=System(id="sys:repo-1", name="empty"),
+ people=[],
+ containers=[],
+ components_by_container={},
+ external_systems=[],
+ container_relations=[],
+ component_relations=[],
+ )
+ dsl = to_dsl(empty, standalone=standalone)
+ assert 'softwareSystem "empty"' in dsl
+ body = "\n".join(line for line in dsl.splitlines() if not line.strip().startswith("#"))
+ assert body.count("{") == body.count("}")
+
+
+def test_quoting_survives_a_name_with_quotes_and_newlines() -> None:
+ model = _model(system=System(id="sys:repo-1", name='we"rd', description="line one\nline two"))
+ dsl = to_dsl(model)
+ system_line = next(line for line in dsl.splitlines() if "softwareSystem" in line)
+ assert "\n" not in system_line
+ assert system_line.count('"') % 2 == 0
+
+
+def test_the_system_identifier_does_not_depend_on_the_local_repo_id() -> None:
+ """Two people exporting the same repo must get the same file.
+
+ The system's node id embeds the local repository UUID, which differs on
+ every machine — keying the identifier on it would make every reference in
+ the file differ between teammates.
+ """
+ mine = to_dsl(_model(system=System(id="sys:aaaaaaaa", name="repowise")))
+ theirs = to_dsl(_model(system=System(id="sys:bbbbbbbb", name="repowise")))
+ assert mine == theirs
+ assert "aaaaaaaa" not in mine
+
+
+# ---------------------------------------------------------------------------
+# Health, ownership and layer metadata
+# ---------------------------------------------------------------------------
+
+
+def _signals_model(**overrides) -> C4Model:
+ base = _model()
+ signals = {
+ "pkg:packages/core": BoxSignals(
+ hotspot_count=3,
+ dead_count=1,
+ layers=("Domain", "Ingestion"),
+ primary_owner="Ada Lovelace",
+ primary_owner_pct=62.5,
+ min_bus_factor=1,
+ ),
+ "pkg:packages/web": BoxSignals(),
+ "cmp:packages/core/ingestion": BoxSignals(hotspot_count=2, layers=("Ingestion",)),
+ }
+ defaults = {"box_signals": signals}
+ defaults.update(overrides)
+ return C4Model(**{**vars(base), **defaults})
+
+
+def test_health_rides_along_as_tags() -> None:
+ dsl = to_dsl(_signals_model())
+ assert '"Hotspot"' in dsl
+ assert '"Dead"' in dsl
+
+
+def test_layer_membership_becomes_a_tag() -> None:
+ """The layer grouping is ours; a tag is how it survives into their tool."""
+ dsl = to_dsl(_signals_model())
+ assert '"Layer: Domain"' in dsl
+ assert '"Layer: Ingestion"' in dsl
+
+
+def test_properties_are_namespaced_so_they_cannot_collide() -> None:
+ dsl = to_dsl(_signals_model())
+ for key in ("repowise.hotspots", "repowise.owner", "repowise.minBusFactor"):
+ assert f'"{key}"' in dsl
+ assert '"Ada Lovelace"' in dsl
+
+
+def test_unknown_ownership_is_omitted_not_zeroed() -> None:
+ """An emitted 0 bus factor reads as "nobody owns this", a different claim."""
+ dsl = to_dsl(_signals_model())
+ web_block = dsl.split('container "web"')[1]
+ assert "repowise.owner" not in web_block
+ assert "repowise.minBusFactor" not in web_block
+
+
+def test_counts_are_emitted_even_when_zero() -> None:
+ """We counted; zero is an answer, unlike a missing owner."""
+ dsl = to_dsl(_signals_model())
+ assert '"repowise.hotspots" "0"' in dsl
+
+
+def test_metadata_can_be_turned_off_for_a_plain_c4_model() -> None:
+ dsl = to_dsl(_signals_model(), include_metadata=False)
+ assert "repowise." not in dsl
+ assert "Layer: " not in dsl
+ assert "Hotspot" not in dsl
+
+
+def test_a_box_with_nothing_to_say_stays_a_one_liner() -> None:
+ plain = C4Model(**{**vars(_model()), "box_signals": {}})
+ dsl = to_dsl(plain)
+ assert 'container "core" "120 files, 800 symbols" "python"\n' in dsl
+
+
+def test_the_tour_rides_along_as_a_comment() -> None:
+ """It cannot be a view, but it is one of the few things we know and C4 does not."""
+ model = C4Model(
+ **{
+ **vars(_model()),
+ "tour": [
+ TourStep(
+ order=1,
+ title="Start at the CLI",
+ reason="Every run enters here",
+ target_path="packages/cli/main.py",
+ ),
+ TourStep(
+ order=2, title="Then the parser", description="Where files\nbecome symbols"
+ ),
+ ],
+ }
+ )
+ dsl = to_dsl(model)
+ assert "Suggested reading order:" in dsl
+ assert "1. Start at the CLI — packages/cli/main.py" in dsl
+ assert "Every run enters here" in dsl
+ # A description with a newline must not break out of the comment.
+ for line in dsl.splitlines():
+ if "become symbols" in line:
+ assert line.strip().startswith("#")
+
+
+def test_layer_views_are_emitted_for_a_standalone_workspace() -> None:
+ dsl = to_dsl(_signals_model(), standalone=True)
+ assert 'include "element.tag==Layer: Domain"' in dsl
+ assert 'element "Hotspot"' in dsl
+
+
+def test_metadata_does_not_break_brace_balance() -> None:
+ for standalone in (False, True):
+ for components in (False, True):
+ dsl = to_dsl(_signals_model(), standalone=standalone, include_components=components)
+ body = "\n".join(line for line in dsl.splitlines() if not line.strip().startswith("#"))
+ assert body.count("{") == body.count("}"), (standalone, components)
+
+
+def test_two_packages_presenting_as_the_same_name_do_not_collide() -> None:
+ """Structurizr rejects two top-level elements sharing a name.
+
+ Real case: `react`, `@xyflow/react` and `@radix-ui/react-dialog` all
+ present as "React" in the index's display names, so the emitted file was
+ rejected outright by the parser.
+ """
+
+ def _ext(node_id: str, name: str, display: str) -> ExternalSystemView:
+ return ExternalSystemView(
+ id=node_id,
+ name=name,
+ display_name=display,
+ category="library",
+ ecosystem="npm",
+ )
+
+ dsl = to_dsl(
+ _model(
+ external_systems=[
+ _ext("ext:react", "react", "React"),
+ _ext("ext:@xyflow/react", "@xyflow/react", "React"),
+ _ext("ext:vite", "vite", "Vite"),
+ ],
+ container_relations=[],
+ component_relations=[],
+ )
+ )
+ declared = [
+ line.split("softwareSystem ", 1)[1].split('"')[1]
+ for line in dsl.splitlines()
+ if "= softwareSystem " in line
+ ]
+ assert len(declared) == len(set(declared)), declared
+ # The unique one keeps its pretty name; the colliding pair falls back to
+ # the package name, which is unique by construction.
+ assert "Vite" in declared
+ assert "react" in declared
+ assert "@xyflow/react" in declared
+
+
+def test_an_external_stays_connected_when_components_are_on() -> None:
+ """Structurizr derives a container edge from a component one, an external one it cannot.
+
+ With components on, only the container edges touching a componentless
+ container survive — and an external system is never componentless, so
+ ``pkg:core -> ext:fastapi`` disappeared and FastAPI was declared with
+ nothing pointing at it.
+ """
+ dsl = to_dsl(_model(component_relations=[]), include_components=True)
+ assert "-> ext_fastapi" in dsl, dsl
+
+
+def test_layer_views_are_not_emitted_when_metadata_is_off() -> None:
+ """The tags they filter on are gone, so every one of them selects nothing."""
+ dsl = to_dsl(_signals_model(), standalone=True, include_metadata=False)
+ assert "Layer: " not in dsl
+ assert '"layer_' not in dsl
+
+
+def test_every_person_is_connected_to_the_system() -> None:
+ """An unconnected person is left out of the context view entirely.
+
+ ``systemContext ... { include * }`` pulls in the system plus what is
+ related to it, so a person nothing points at is simply not drawn — while
+ the product's own L1 view shows the same actor connected.
+ """
+ model = _model(
+ actor_relations=[
+ Relation(
+ source_id="person:cli",
+ target_id="sys:repo-1",
+ label="uses",
+ edge_count=1,
+ edge_types=(),
+ coupling="",
+ )
+ ]
+ )
+ for components in (False, True):
+ dsl = to_dsl(model, include_components=components)
+ system_ref = system_identifier(model, include_components=components)
+ assert f"person_cli -> {system_ref}" in dsl, components
+
+
+def test_a_comment_can_never_span_lines() -> None:
+ """A tour title is curated prose, so it can carry a newline.
+
+ Written into a comment as-is, everything after the newline lands in the
+ file as a bare token and the parser stops there.
+ """
+ dsl = to_dsl(
+ _model(
+ tour=[
+ TourStep(
+ order=1,
+ title="Start here\nnot a comment",
+ description="",
+ reason="because\r\nof reasons",
+ target_path="packages/core/a.py\nb.py",
+ )
+ ]
+ )
+ )
+ header, _, body = dsl.partition("\nmodel {")
+ assert body, dsl
+ for line in header.splitlines():
+ assert not line or line.startswith("#"), line
+ assert "Start here not a comment" in header
+
+
+def test_the_include_snippet_keeps_the_indentation_it_is_pasted_with() -> None:
+ """The header shows a nested block, so folding must not touch indentation.
+
+ Only line breaks are unsafe in a comment; a run of spaces is what makes the
+ snippet readable and pasteable.
+ """
+ dsl = to_dsl(_model())
+ assert "# !include " in dsl, dsl.split("\nmodel {")[0]
+
+
+def test_a_system_name_with_a_newline_cannot_break_the_header() -> None:
+ dsl = to_dsl(_model(system=System(id="sys:x", name="repo\nwise")))
+ header = dsl.split("\nmodel {")[0]
+ for line in header.splitlines():
+ assert not line or line.startswith("#"), line
+
+
+def _layer_view_keys(dsl: str) -> list[str]:
+ return [
+ line.split('"')[1]
+ for line in dsl.splitlines()
+ if line.strip().startswith("container ") and '"layer_' in line
+ ]
+
+
+def _layer_filters(dsl: str) -> list[str]:
+ return [
+ line.strip().split("element.tag==", 1)[1].rstrip('"')
+ for line in dsl.splitlines()
+ if "element.tag==" in line
+ ]
+
+
+def _emitted_tags(dsl: str) -> set[str]:
+ tags: set[str] = set()
+ for line in dsl.splitlines():
+ stripped = line.strip()
+ if stripped.startswith("tags "):
+ tags.update(re.findall(r'"([^"]*)"', stripped))
+ return tags
+
+
+def test_two_layer_names_that_slug_alike_get_different_view_keys() -> None:
+ """A view key must be unique; the layer name it comes from need not be.
+
+ ``Data Access`` and ``Data-Access`` both reduced to ``layer_Data_Access``,
+ and Structurizr rejects a workspace with two views under one key.
+ """
+ dsl = to_dsl(
+ _signals_model(
+ box_signals={
+ "pkg:packages/core": BoxSignals(layers=("Data Access",)),
+ "pkg:packages/web": BoxSignals(layers=("Data-Access",)),
+ }
+ ),
+ standalone=True,
+ )
+ keys = _layer_view_keys(dsl)
+ assert len(keys) == 2, keys
+ assert len(set(keys)) == 2, keys
+
+
+def test_a_layer_name_with_a_quote_cannot_break_the_filter() -> None:
+ """The filter is a string literal, so an unescaped quote ends it early."""
+ dsl = to_dsl(
+ _signals_model(box_signals={"pkg:packages/core": BoxSignals(layers=('Data "Access"',))}),
+ standalone=True,
+ )
+ filter_lines = [line for line in dsl.splitlines() if "element.tag==" in line]
+ assert len(filter_lines) == 1
+ assert filter_lines[0].count('"') == 2, filter_lines[0]
+
+
+def test_a_layer_filter_matches_the_tag_that_was_actually_emitted() -> None:
+ """Quoting rewrites the tag, so the filter has to be rewritten identically.
+
+ Otherwise a layer name carrying a quote yields a view that parses and then
+ selects nothing, which is worse than failing.
+ """
+ dsl = to_dsl(
+ _signals_model(
+ box_signals={
+ "pkg:packages/core": BoxSignals(layers=('Data "Access"', "Multi spaced"))
+ }
+ ),
+ standalone=True,
+ )
+ emitted = _emitted_tags(dsl)
+ for selector in _layer_filters(dsl):
+ assert selector in emitted, (selector, emitted)
+
+
+def _declared(dsl: str, keyword: str) -> list[str]:
+ """The display names of every element declared with *keyword*."""
+ return [
+ line.split(f"{keyword} ", 1)[1].split('"')[1]
+ for line in dsl.splitlines()
+ if f"= {keyword} " in line
+ ]
+
+
+def test_two_containers_with_the_same_basename_do_not_collide() -> None:
+ """A container name only has to be unique inside its software system.
+
+ Container names are the leaf directory, so any monorepo holding both
+ ``apps/api`` and ``services/api`` produced two ``container "api"`` blocks —
+ which Structurizr rejects outright, the same way it rejects two externals
+ sharing a name.
+ """
+
+ def _container(path: str, language: str) -> Container:
+ return Container(
+ id=f"pkg:{path}",
+ name=path.split("/")[-1],
+ path=path,
+ language=language,
+ file_count=3,
+ symbol_count=1,
+ )
+
+ dsl = to_dsl(
+ _model(
+ containers=[
+ _container("apps/api", "typescript"),
+ _container("services/api", "go"),
+ _container("apps/web", "typescript"),
+ ],
+ components_by_container={},
+ container_relations=[],
+ component_relations=[],
+ )
+ )
+ declared = _declared(dsl, "container")
+ assert len(declared) == len(set(declared)), declared
+ # The unique one keeps the short name; the colliding pair falls back to the
+ # path, which is unique by construction.
+ assert "web" in declared
+ assert "apps/api" in declared
+ assert "services/api" in declared
+
+
+def test_two_components_in_one_container_with_the_same_basename_do_not_collide() -> None:
+ """``src`` and ``lib`` are both pass-through directories.
+
+ So ``packages/ui/src/health`` and ``packages/ui/lib/health`` both name a
+ component "health" inside one container, which the parser rejects.
+ """
+ container = Container(
+ id="pkg:packages/ui",
+ name="ui",
+ path="packages/ui",
+ language="typescript",
+ file_count=4,
+ symbol_count=2,
+ )
+
+ def _component(path: str) -> Component:
+ return Component(
+ id=f"cmp:{path}",
+ name=path.split("/")[-1],
+ path=path,
+ container_id=container.id,
+ file_count=2,
+ symbol_count=1,
+ )
+
+ dsl = to_dsl(
+ _model(
+ containers=[container],
+ components_by_container={
+ container.id: [
+ _component("packages/ui/src/health"),
+ _component("packages/ui/lib/health"),
+ _component("packages/ui/src/costs"),
+ ]
+ },
+ container_relations=[],
+ component_relations=[],
+ ),
+ include_components=True,
+ )
+ declared = _declared(dsl, "component")
+ assert len(declared) == len(set(declared)), declared
+ assert "costs" in declared
+ assert "src/health" in declared
+ assert "lib/health" in declared
+
+
+def test_the_same_component_name_in_two_containers_is_left_alone() -> None:
+ """A component name only has to be unique inside its own container.
+
+ Disambiguating across containers would churn names for no reason, and the
+ long form is worse to read.
+ """
+
+ def _container(path: str) -> Container:
+ return Container(
+ id=f"pkg:{path}",
+ name=path.split("/")[-1],
+ path=path,
+ language="python",
+ file_count=2,
+ symbol_count=1,
+ )
+
+ one, two = _container("packages/core"), _container("packages/server")
+
+ def _component(container: Container, leaf: str) -> Component:
+ path = f"{container.path}/{leaf}"
+ return Component(
+ id=f"cmp:{path}",
+ name=leaf,
+ path=path,
+ container_id=container.id,
+ file_count=2,
+ symbol_count=1,
+ )
+
+ dsl = to_dsl(
+ _model(
+ containers=[one, two],
+ components_by_container={
+ one.id: [_component(one, "health")],
+ two.id: [_component(two, "health")],
+ },
+ container_relations=[],
+ component_relations=[],
+ ),
+ include_components=True,
+ )
+ assert _declared(dsl, "component") == ["health", "health"]
+
+
+def test_an_external_sharing_the_repo_name_is_disambiguated() -> None:
+ dsl = to_dsl(
+ _model(
+ system=System(id="sys:abc", name="react"),
+ external_systems=[
+ ExternalSystemView(
+ id="ext:react",
+ name="react",
+ display_name="react",
+ category="library",
+ ecosystem="npm",
+ )
+ ],
+ container_relations=[],
+ component_relations=[],
+ )
+ )
+ declared = [
+ line.split("softwareSystem ", 1)[1].split('"')[1]
+ for line in dsl.splitlines()
+ if "= softwareSystem " in line
+ ]
+ assert len(declared) == len(set(declared)), declared
+
+
+# ---------------------------------------------------------------------------
+# The degenerate inputs. Each of these reached the emitter untested, and each
+# writes something a parser has to accept.
+# ---------------------------------------------------------------------------
+
+
+def test_a_single_non_ascii_name_still_gets_a_usable_identifier() -> None:
+ """Sanitising a non-ASCII name leaves nothing, so the allocator carries it.
+
+ With two such names the hash suffixes make them unique; with *one* there is
+ no collision to resolve, and it is declared under the bare fallback.
+ """
+ identifier = sanitize("\u6a21\u5757")
+ assert identifier and not identifier[0].isdigit()
+ mapping = identifiers_for(["pkg:\u6a21\u5757", "pkg:\u30d1\u30c3\u30b1\u30fc\u30b8"])
+ assert len(set(mapping.values())) == 2, mapping
+
+
+def test_an_external_with_nothing_to_say_still_parses() -> None:
+ """No category, ecosystem or version — the description literal is empty."""
+ dsl = to_dsl(
+ _model(
+ external_systems=[
+ ExternalSystemView(
+ id="ext:bare", name="bare", display_name="bare", category="", ecosystem=""
+ )
+ ],
+ container_relations=[],
+ component_relations=[],
+ )
+ )
+ assert 'softwareSystem "bare" ""' in dsl
+ body = "\n".join(line for line in dsl.splitlines() if not line.strip().startswith("#"))
+ assert body.count('"') % 2 == 0
+
+
+def test_a_relation_with_no_label_falls_back_to_a_verb() -> None:
+ """An unlabelled edge still needs a description; the slot is not optional."""
+ dsl = to_dsl(
+ _model(
+ container_relations=[
+ Relation(
+ source_id="pkg:packages/web",
+ target_id="pkg:packages/core",
+ label="",
+ edge_count=1,
+ edge_types=(),
+ coupling="",
+ )
+ ],
+ component_relations=[],
+ )
+ )
+ assert '"depends on"' in dsl
+
+
+def test_a_container_edge_a_component_already_implies_is_not_repeated() -> None:
+ """Structurizr derives the container edge from the component one.
+
+ The derivation walks up both ends' parents, so it applies to an edge
+ leaving our system too. Emitting ours alongside it is a duplicate the
+ parser rejects — this repo's own export died on exactly that, with the
+ root container and a package both reaching one npm dependency.
+ """
+ core = Container(
+ id="pkg:packages/core",
+ name="core",
+ path="packages/core",
+ language="python",
+ file_count=5,
+ symbol_count=9,
+ )
+ ingestion = Component(
+ id="cmp:packages/core/ingestion",
+ name="ingestion",
+ path="packages/core/ingestion",
+ container_id=core.id,
+ file_count=5,
+ symbol_count=9,
+ )
+ to_external = Relation(source_id=ingestion.id, target_id="ext:fastapi", label="imports")
+ dsl = to_dsl(
+ _model(
+ containers=[core],
+ components_by_container={core.id: [ingestion]},
+ # The same dependency, seen at both levels — which is what the
+ # builder produces for any container whose files import it.
+ container_relations=[
+ Relation(source_id=core.id, target_id="ext:fastapi", label="imports")
+ ],
+ component_relations=[to_external],
+ ),
+ include_components=True,
+ )
+
+ pairs = re.findall(r"^\s*([\w.]+) -> ([\w.]+)", dsl, re.M)
+ assert len(pairs) == len(set(pairs)), [p for p in pairs if pairs.count(p) > 1]
+ # The component keeps the edge; the container's copy of it is dropped
+ # because Structurizr will derive it.
+ assert ("cmp_packages_core_ingestion", "ext_fastapi") in pairs
+ assert ("pkg_packages_core", "ext_fastapi") not in pairs
+
+
+def test_a_container_edge_nothing_derives_is_kept() -> None:
+ """A container with no components has nothing to carry its edges."""
+ core = Container(
+ id="pkg:packages/core",
+ name="core",
+ path="packages/core",
+ language="python",
+ file_count=1,
+ symbol_count=1,
+ )
+ model = _model(
+ containers=[core],
+ components_by_container={core.id: []},
+ container_relations=[Relation(source_id=core.id, target_id="ext:fastapi", label="imports")],
+ component_relations=[],
+ )
+ dsl = to_dsl(model, include_components=True)
+ assert "pkg_packages_core -> ext_fastapi" in dsl
+ # And the external it points at is still declared.
+ assert "= softwareSystem" in dsl and "FastAPI" in dsl
diff --git a/tests/unit/server/test_symbols.py b/tests/unit/server/test_symbols.py
index 8255753a0..4309e5a65 100644
--- a/tests/unit/server/test_symbols.py
+++ b/tests/unit/server/test_symbols.py
@@ -154,3 +154,43 @@ async def test_get_symbol_by_db_id(client: AsyncClient, app) -> None:
async def test_get_symbol_not_found(client: AsyncClient) -> None:
resp = await client.get("/api/symbols/nonexistent")
assert resp.status_code == 404
+
+
+async def test_search_symbols_treats_underscore_literally(client: AsyncClient, app) -> None:
+ """``_`` in a query is a character, not a LIKE single-char wildcard.
+
+ Without escaping, searching ``a_b`` also returns ``axb`` — which reads as
+ the search being broken, and is how most Python names are spelled.
+ """
+ repo = await create_test_repo(client)
+ await _insert_symbol(
+ app.state.session_factory,
+ repo["id"],
+ name="load_config",
+ symbol_id="src/main.py::load_config",
+ qualified_name="src.main.load_config",
+ )
+ await _insert_symbol(
+ app.state.session_factory,
+ repo["id"],
+ name="loadXconfig",
+ symbol_id="src/main.py::loadXconfig",
+ qualified_name="src.main.loadXconfig",
+ )
+
+ resp = await client.get("/api/symbols", params={"repo_id": repo["id"], "q": "load_config"})
+ assert resp.status_code == 200
+ names = {item["name"] for item in resp.json()["items"]}
+ assert names == {"load_config"}
+
+
+async def test_search_symbols_treats_percent_literally(client: AsyncClient, app) -> None:
+ """A bare ``%`` must not turn into "match every symbol"."""
+ repo = await create_test_repo(client)
+ await _insert_symbol(app.state.session_factory, repo["id"])
+
+ resp = await client.get("/api/symbols", params={"repo_id": repo["id"], "q": "%"})
+ assert resp.status_code == 200
+ assert resp.json()["total"] == 0
diff --git a/tests/unit/test_ids.py b/tests/unit/test_ids.py
new file mode 100644
index 000000000..033061fd1
--- /dev/null
+++ b/tests/unit/test_ids.py
@@ -0,0 +1,252 @@
+"""Tests for the typed node-id module."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+
+from repowise.core.ids import (
+ ComponentId,
+ ContainerId,
+ ExternalId,
+ ExternalSystemId,
+ FileId,
+ FrameworkId,
+ InvalidNodeIdError,
+ KgFileId,
+ PersonId,
+ SymbolId,
+ SystemId,
+ file_path_of,
+ is_external,
+ kg_file_path_of,
+ parse,
+ render,
+)
+
+# One value per variant, including the shapes that used to be parsed wrong.
+EVERY_VARIANT = [
+ FileId("src/main.py"),
+ FileId("packages/core/src/repowise/core/ids.py"),
+ FileId("C:\\src\\main.py"),
+ FileId("a b/with space.py"),
+ KgFileId("src/main.py"),
+ SymbolId("src/main.py", "main"),
+ SymbolId("src/main.py", "Klass.method"),
+ ExternalId("react"),
+ ExternalId("pub:http"),
+ ExternalId("serde::Deserialize"),
+ FrameworkId("typo3-core"),
+ SystemId("repowise"),
+ PersonId("developer"),
+ ContainerId("packages/core"),
+ ContainerId("."),
+ ComponentId("packages/core/ingestion"),
+ ComponentId("packages/core", is_root_bucket=True),
+ ComponentId(".", is_root_bucket=True),
+ ComponentId("a#root/b"),
+ FileId(""),
+ ContainerId("паке́т/модуль"),
+ ExternalSystemId("模块"),
+ ExternalSystemId("react"),
+]
+
+
[email protected]("node", EVERY_VARIANT, ids=lambda n: f"{type(n).__name__}-{vars(n)}")
+def test_render_then_parse_is_the_identity(node) -> None:
+ assert parse(render(node)) == node
+
+
[email protected]("node", EVERY_VARIANT, ids=lambda n: f"{type(n).__name__}-{vars(n)}")
+def test_rendering_is_deterministic(node) -> None:
+ assert render(node) == render(node)
+
+
+def test_renders_the_spellings_the_rest_of_the_tree_uses() -> None:
+ assert render(FileId("src/main.py")) == "src/main.py"
+ assert render(KgFileId("src/main.py")) == "file:src/main.py"
+ assert render(SymbolId("src/main.py", "main")) == "src/main.py::main"
+ assert render(ExternalId("react")) == "external:react"
+ assert render(FrameworkId("typo3-core")) == "framework:typo3-core"
+ assert render(SystemId("repowise")) == "sys:repowise"
+ assert render(PersonId("developer")) == "person:developer"
+ assert render(ContainerId("packages/core")) == "pkg:packages/core"
+ assert render(ComponentId("packages/core/ingestion")) == "cmp:packages/core/ingestion"
+
+
+def test_the_root_bucket_no_longer_hides_a_symbol_separator() -> None:
+ """``cmp:packages/core::root`` used to parse as a symbol called ``root``."""
+ rendered = render(ComponentId("packages/core", is_root_bucket=True))
+ assert "::" not in rendered
+ assert parse(rendered) == ComponentId("packages/core", is_root_bucket=True)
+ assert not isinstance(parse(rendered), SymbolId)
+
+
+def test_a_component_named_root_is_not_the_root_bucket() -> None:
+ plain = ComponentId("packages/core/root")
+ assert parse(render(plain)) == plain
+ assert parse(render(plain)).is_root_bucket is False
+
+
+def test_a_windows_path_is_a_file_not_a_prefix() -> None:
+ assert parse("C:\\src\\main.py") == FileId("C:\\src\\main.py")
+ assert parse("D:/work/repo/a.py") == FileId("D:/work/repo/a.py")
+
+
+def test_an_unknown_prefix_is_a_file() -> None:
+ assert parse("mailto:[email protected]") == FileId("mailto:[email protected]")
+ assert parse("src/main.py") == FileId("src/main.py")
+
+
+def test_an_external_name_may_contain_colons() -> None:
+ assert parse("external:pub:http") == ExternalId("pub:http")
+
+
+def test_a_file_whose_name_contains_the_separator_is_rejected_loudly() -> None:
+ """Legal on Linux and macOS, unrepresentable here — so fail at construction.
+
+ The alternative is emitting an id that parses back as a symbol, which is
+ the failure the whole module exists to prevent. Only the two unprefixed
+ forms are at risk: a prefixed id is read prefix-first, so the separator
+ inside it is just data.
+ """
+ with pytest.raises(InvalidNodeIdError):
+ render(FileId("weird::name.py"))
+ with pytest.raises(InvalidNodeIdError):
+ render(SymbolId("weird::dir/a.py", "main"))
+
+
+def test_a_component_path_may_not_end_in_the_root_marker() -> None:
+ """A directory named ``foo#root`` is legal, and unspellable here.
+
+ ``cmp:packages/foo#root`` is already how the synthetic root bucket of
+ ``packages/foo`` is written, so a real directory with that name has no
+ distinct spelling. Structurally the same trap the symbol separator sets,
+ and the same answer: fail at construction rather than mis-parse later.
+ """
+ with pytest.raises(InvalidNodeIdError):
+ render(ComponentId("packages/foo#root"))
+ # The marker only binds at the end, so a path merely containing it is fine.
+ assert parse(render(ComponentId("a#root/b"))) == ComponentId("a#root/b")
+
+
+def test_a_prefixed_id_may_contain_the_symbol_separator() -> None:
+ """Rust import resolution really emits ``external:serde::Deserialize``.
+
+ ``ingestion/resolvers/rust.py`` builds an external node from the raw module
+ path, so the separator lands inside a prefixed id. Reading the prefix first
+ makes it unambiguous, so there is nothing to reject.
+ """
+ assert parse("external:serde::Deserialize") == ExternalId("serde::Deserialize")
+ assert render(ExternalId("serde::Deserialize")) == "external:serde::Deserialize"
+ assert parse("framework:foo::bar") == FrameworkId("foo::bar")
+ assert render(ContainerId("weird::pkg")) == "pkg:weird::pkg"
+ assert parse("cmp:weird::dir") == ComponentId("weird::dir")
+
+
+def test_a_prefixed_id_is_never_read_as_a_symbol() -> None:
+ """The regression this ordering exists to prevent.
+
+ Parsing the separator first turned every Rust external into a symbol whose
+ path was ``external:<crate>``, so ``is_external`` said False and the crate
+ was treated as one of the repository's own files.
+ """
+ for raw in (
+ "external:serde::Deserialize",
+ "framework:foo::bar",
+ "pkg:weird::pkg",
+ "file:weird::name.py",
+ ):
+ assert not isinstance(parse(raw), SymbolId), raw
+
+
+def test_a_symbol_name_may_contain_the_separator() -> None:
+ """Rust and C++ symbol names are path-like; only the first split matters."""
+ assert parse("src/lib.rs::Foo::bar") == SymbolId("src/lib.rs", "Foo::bar")
+ assert render(SymbolId("src/lib.rs", "Foo::bar")) == "src/lib.rs::Foo::bar"
+
+
+def test_is_external_covers_frameworks_too() -> None:
+ assert is_external("external:react")
+ assert is_external("framework:typo3-core")
+ assert not is_external("src/main.py")
+ assert not is_external("src/main.py::main")
+ assert not is_external("pkg:packages/core")
+
+
+def test_is_external_covers_a_name_carrying_the_separator() -> None:
+ """A Cargo repo's externals all look like this."""
+ assert is_external("external:serde::Deserialize")
+ assert is_external("framework:foo::bar")
+ assert file_path_of("external:serde::Deserialize") is None
+
+
+def test_file_path_of() -> None:
+ assert file_path_of("src/main.py") == "src/main.py"
+ assert file_path_of("src/main.py::main") == "src/main.py"
+ assert file_path_of("file:src/main.py") == "src/main.py"
+ assert file_path_of("external:react") is None
+ assert file_path_of("pkg:packages/core") is None
+
+
+# ---------------------------------------------------------------------------
+# The shared fixture — the only thing that can fail a build when the Python
+# and TypeScript decoders drift apart. Its TypeScript half lives in
+# packages/types/__tests__/node-ids.test.ts and reads the same file.
+# ---------------------------------------------------------------------------
+
+_FIXTURE = json.loads(
+ (Path(__file__).resolve().parents[2] / "tests/fixtures/node_ids.json").read_text(
+ encoding="utf-8"
+ )
+)
+
+#: Variant → the ``kind`` string the fixture and the TypeScript side use.
+_KIND_BY_TYPE = {
+ FileId: "path",
+ KgFileId: "file",
+ SymbolId: "symbol",
+ ExternalId: "external",
+ FrameworkId: "framework",
+ SystemId: "sys",
+ PersonId: "person",
+ ContainerId: "pkg",
+ ComponentId: "cmp",
+ ExternalSystemId: "ext",
+}
+
+
+def _symbol_name_of(raw: str) -> str | None:
+ node = parse(raw)
+ return node.name if isinstance(node, SymbolId) else None
+
+
[email protected]("case", _FIXTURE["cases"], ids=lambda c: c["raw"])
+def test_the_shared_fixture_holds_in_python(case) -> None:
+ raw = case["raw"]
+ assert _KIND_BY_TYPE[type(parse(raw))] == case["kind"], raw
+ assert file_path_of(raw) == case["file_path"], raw
+ assert _symbol_name_of(raw) == case["symbol_name"], raw
+ assert is_external(raw) is case["is_external"], raw
+
+
+def test_kg_file_path_of_accepts_only_a_prefixed_file_id() -> None:
+ """The knowledge-graph artifact holds more than file ids in its lists.
+
+ ``module:``, ``layer:`` and ``dir:`` are real namespaces in this codebase
+ and none is in the prefix table, so each parses as a bare path — which the
+ permissive helper hands back as if it named a file. The layer and tour
+ readers looked those up in PageRank and named them in a prompt.
+ """
+ assert kg_file_path_of("file:src/main.py") == "src/main.py"
+ for raw in (
+ "module:core-ingestion",
+ "layer:api",
+ "dir:packages/core",
+ "src/main.py",
+ "src/main.py::run",
+ "external:react",
+ ):
+ assert kg_file_path_of(raw) is None, raw