Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
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.ymlindex 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 0diff --git a/README.md b/README.mdindex 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 riskrepowise impacted-tests # only the tests a diff actually exercisesrepowise dead-code # unreachable-code reportrepowise decision list # architectural decisions+repowise export --format structurizr # the architecture as Structurizr DSL, no LLMrepowise distill pytest # compact, errors-first, reversible command outputrepowise saved # tokens and dollars saved by distillationrepowise workspace add # multi-repo workspace managementdiff --git a/docs/README.md b/docs/README.mdindex 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.mdindex 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.mdnew file mode 100644index 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.mdindex 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 |```bashrepowise exportrepowise export --format json --fullrepowise 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 Commandsdiff --git a/docs/reference/UPGRADING.md b/docs/reference/UPGRADING.mdindex cc5d9714e..3d428d554 100644--- a/docs/reference/UPGRADING.md+++ b/docs/reference/UPGRADING.md@@ -31,6 +31,36 @@ Reindex recommended: repowise init --forceIt 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.tsindex 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.pyindex 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 annotationsfrom 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.pyindex 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 selectfrom repowise.core.persistence.models import DecisionRecord+ from repowise.core.persistence.sql import LIKE_ESCAPE, escape_likeresult = 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.pyindex 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.pynew file mode 100644index 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 0diff --git a/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.py b/packages/core/src/repowise/core/analysis/dead_code/dynamic_markers.pyindex 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 annotationsfrom 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:continueendpoint_str = str(endpoint)- if endpoint_str.startswith("external:"):+ if is_external(endpoint_str):continuenode_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.pyindex 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, fieldimport networkx as nximport 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.pyindex 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'sseverity (typically a *demotion*, e.g. ``complex_method`` → ``low``) so ateam 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 fnmatchimport json+import refrom dataclasses import dataclass, fieldfrom pathlib import Path+from typing import Anyimport 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([])++@dataclassclass 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: strdisabled_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 = Noneif 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] = overridesdiff --git a/packages/core/src/repowise/core/analysis/kg_curation.py b/packages/core/src/repowise/core/analysis/kg_curation.pyindex 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_externalfrom 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 += 1else: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):continuenames = 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.pyindex 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 annotationsimport hashlibimport json+import loggingimport refrom dataclasses import dataclass, fieldfrom pathlib import Path, PurePosixPathfrom 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+@dataclassclass 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:@classmethoddef 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 Nonereturn 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.pyindex 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 Anyimport structlog+from repowise.core.ids import file_path_of, is_externalfrom repowise.core.ingestion.models import ParsedFile, RepoStructure, Symbolfrom ..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 namesother 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.pyindex 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 Pathimport 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.pyindex 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 refrom collections import Counter, defaultdictfrom 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.pyindex 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 Anyimport 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.pyindex 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 defaultdictfrom collections.abc import Iterable, Mappingfrom pathlib import PurePosixPath+from repowise.core.ids import is_externalfrom repowise.core.ingestion.languages.registry import REGISTRY as _LANG_REGISTRYfrom 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):continuels = 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 layerin_deg: dict[str, int] = defaultdict(int) # edges entering the layerfor src, dst in import_edges:- if src.startswith("external:") or dst.startswith("external:"):+ if is_external(src) or is_external(dst):continuels = 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.pyindex 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 hashlibimport reimport 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 = Falsefor 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:continuelabel = text[i + len(opener) : end]@@ -138,22 +268,52 @@ def _quote_labels(body: str) -> str:i += 1return "".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.pyindex 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, Anyimport structlog+from repowise.core.ids import is_external+from ...analysis.knowledge_graph import _slugifyfrom .. import onboarding as _onboardingfrom ..context_assembler import FilePageContext@@ -113,7 +115,7 @@ async def _prefetch_dependency_summaries(run: _GenerationRun) -> None:if path_ not in run.graph:continuefor dep in run.graph.successors(path_):- if dep.startswith("external:"):+ if is_external(dep):continueif dep in run.completed_page_summaries:continuediff --git a/packages/core/src/repowise/core/generation/tour.py b/packages/core/src/repowise/core/generation/tour.pyindex 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 Anyfrom repowise.core.generation.entry_points import is_glue_leaffrom repowise.core.generation.layers import ADJACENT_LAYERS, infer_layer, is_support_path+from repowise.core.ids import is_externalfrom 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):continueadjacency[src].append(dst)fan_in[dst] += 1diff --git a/packages/core/src/repowise/core/ids.py b/packages/core/src/repowise/core/ids.pynew file mode 100644index 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 Nonediff --git a/packages/core/src/repowise/core/ingestion/graph/__init__.py b/packages/core/src/repowise/core/ingestion/graph/__init__.pyindex 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.pyindex 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 Pathfrom typing import Anyimport 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.pyindex 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_likefrom ._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.pyindex 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 jsonfrom sqlalchemy import delete, selectfrom 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.pynew file mode 100644index 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.pyindex 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_itemsdiff --git a/packages/core/src/repowise/core/sessions/miners/demand.py b/packages/core/src/repowise/core/sessions/miners/demand.pyindex 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 Anyimport structlog+from repowise.core.ids import file_path_offrom repowise.core.sessions import ClaudeCodeAdapter, Eventlogger = 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.pyindex 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_REGISTRfrom 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: F401from 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.pyindex 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 Noneif 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.pyindex 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_likefrom 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) -> bbase = 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.pyindex 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_sessionfrom repowise.core.persistence.models import GraphNode, Page, WikiSymbolfrom repowise.core.test_paths import is_test_path, is_test_related_pathfrom 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.pyindex 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[WikiSymWikiSymbol.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.pyindex 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_dslrouter = 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.pyindex 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.pyindex 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 AsyncSessionfrom fastapi import APIRouter, Depends, Queryfrom repowise.core.persistence import crudfrom repowise.core.persistence.models import GraphEdge, GraphNode+from repowise.core.persistence.sql import LIKE_ESCAPE, escape_likefrom repowise.server.deps import get_db_sessionfrom 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_repofrom repowise.server.schemas import GraphExportResponse, NodeSearchResultfrom repowise.server.services.graph_views import edge_responsefrom 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.pyindex 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_likefrom repowise.server.deps import get_db_session, verify_api_keyfrom repowise.server.schemas import Paginated, SymbolImportanceComponents, SymbolResponsefrom 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__.pyindex 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 replacefrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.ids import ExternalSystemId, SystemId, file_path_of, parse, renderfrom 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, GitMetadatafrom .actors import derive_actors-from .components import detect_components+from .components import detect_components, detect_components_for_allfrom .containers import container_id, detect_containersfrom .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.pyindex 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 annotationsfrom 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.pyindex 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 selectfrom sqlalchemy.exc import IntegrityErrorfrom sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker+from repowise.core.ids import ExternalSystemId, file_path_of, renderfrom 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.pyindex 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 loggingfrom collections import defaultdictfrom collections.abc import Iterablefrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.ids import ComponentId, InvalidNodeIdError, renderfrom repowise.core.persistence import GraphNodefrom .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 directoryfall 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, basename = 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 Noneasync 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 = resolvedbucket[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.pyindex 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 Iterablefrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.ids import ContainerId, renderfrom repowise.core.persistence import ExternalSystem, GraphNodefrom .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.pyindex 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.pyindex 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 defaultdictfrom sqlalchemy import selectfrom sqlalchemy.ext.asyncio import AsyncSession+from repowise.core.ids import ExternalSystemId, renderfrom repowise.core.persistence import ExternalSystem, GraphEdge, GraphNodefrom .labels import coupling_strength, relation_labelfrom .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 alsoemitted (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.pyindex 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, defaultdictfrom 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] += 1return {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 outdiff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/__init__.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/__init__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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 outdiff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/metadata.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/metadata.pynew file mode 100644index 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 Truediff --git a/packages/server/src/repowise/server/services/c4_builder/structurizr/relationships.py b/packages/server/src/repowise/server/services/c4_builder/structurizr/relationships.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.tsnew file mode 100644index 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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.tsxindex 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.tsxindex 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.tsxindex 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.tsxindex 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 = (<><spanclassName={`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>) : (<adiff --git a/packages/ui/src/files/file-overview-tab.tsx b/packages/ui/src/files/file-overview-tab.tsxindex 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 }: FileOverviewTabPDependencies ({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 (<pkey={`out-${n.node_id}`}diff --git a/packages/ui/src/graph/sigma/graphology-adapter.ts b/packages/ui/src/graph/sigma/graphology-adapter.tsindex 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.tsxindex 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: stitle="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.tsxnew file mode 100644index 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.pynew file mode 100644index 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.jsonnew file mode 100644index 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.pyindex 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 == 0assert 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.pyindex 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 annotationsimport json+import logging++import pytestfrom 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 Noneassert 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 nxg = nx.DiGraph()diff --git a/tests/unit/cli/test_export_structurizr.py b/tests/unit/cli/test_export_structurizr.pynew file mode 100644index 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 Nonediff --git a/tests/unit/generation/test_context_assembler.py b/tests/unit/generation/test_context_assembler.pyindex 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.pyindex 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"], nameddiff --git a/tests/unit/generation/test_layers.py b/tests/unit/generation/test_layers.pyindex 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.pyindex 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 == 1assert "pkg/x.py" not in changed.contentassert 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 """ 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 outdiff --git a/tests/unit/health/test_health_config.py b/tests/unit/health/test_health_config.pyindex 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 annotationsimport jsonfrom 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.pyindex 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 asynciofrom datetime import datetimefrom 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.pynew file mode 100644index 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.pyindex 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_typeassert _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 Falsediff --git a/tests/unit/server/test_architecture_builder.py b/tests/unit/server/test_architecture_builder.pyindex 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) -> Noasync 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.pyindex 7f8690de7..8be35239c 100644--- a/tests/unit/server/test_c4.py+++ b/tests/unit/server/test_c4.py@@ -7,6 +7,7 @@ from pathlib import Pathfrom httpx import AsyncClient+from repowise.core.ids import ComponentId, parsefrom 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 outassert {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.pynew file mode 100644index 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 == 0diff --git a/tests/unit/server/test_c4_model.py b/tests/unit/server/test_c4_model.pynew file mode 100644index 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 Nonediff --git a/tests/unit/server/test_structurizr_export.py b/tests/unit/server/test_structurizr_export.pynew file mode 100644index 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 dsldiff --git a/tests/unit/server/test_symbols.py b/tests/unit/server/test_symbols.pyindex 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"] == 0diff --git a/tests/unit/test_ids.py b/tests/unit/test_ids.pynew file mode 100644index 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