Skip to content

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

feat(workspace): service-granular system graph and extraction diagnostics (#511)

Raghav Chamadiya6482ca12e611
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.md
index 7310a5921..1a6bc416e 100644
--- a/docs/CLI_REFERENCE.md
+++ b/docs/CLI_REFERENCE.md
@@ -540,6 +540,16 @@ Re-scan the workspace directory for new repos not yet added.
Change which repo is the default for MCP queries.
+### `repowise workspace diagnostics`
+
+Explain the cross-repo contract link count: per-repo provider/consumer counts, unmatched consumers grouped by reason, and orphan providers (declared but never consumed).
+
+```bash
+repowise workspace diagnostics # human-readable report
+repowise workspace diagnostics --json # raw JSON
+repowise workspace diagnostics --repo api # limit to one repo alias
+```
+
See [Workspaces](WORKSPACES.md) for the full multi-repo guide.
---
diff --git a/docs/WORKSPACES.md b/docs/WORKSPACES.md
index c4561650a..3da418238 100644
--- a/docs/WORKSPACES.md
+++ b/docs/WORKSPACES.md
@@ -169,6 +169,16 @@ Change which repo is the default for MCP queries.
repowise workspace set-default backend
```
+### `repowise workspace diagnostics`
+
+Explain the cross-repo contract link count — per-repo provider/consumer counts, unmatched consumers grouped by reason, and orphan providers. See [Extraction Diagnostics](#extraction-diagnostics).
+
+```bash
+repowise workspace diagnostics # human-readable report
+repowise workspace diagnostics --json # raw JSON
+repowise workspace diagnostics --repo api # limit to one repo
+```
+
---
## Cross-Repo Intelligence
@@ -202,6 +212,47 @@ Reads package manifests (`package.json`, `pyproject.toml`, `go.mod`, `pom.xml`,
---
+## System Graph
+
+The contracts, package dependencies, and co-changes above are each a flat list. repowise folds them into a single normalized **system graph** — the one structure every cross-repo view reads. It is rebuilt automatically on every `repowise update --workspace` and persisted to `.repowise-workspace/system_graph.json`.
+
+**Nodes are services, not repos.** A monorepo with three detected service boundaries (a `package.json` / `go.mod` / `Cargo.toml` sub-directory) shows three nodes; the repo is a grouping attribute on each node. A repo with no sub-boundary collapses to a single repo-root node. Each node carries its provider/consumer counts, the contract types it participates in, and flags for orphan/isolated services.
+
+**Edges are typed and honest.** Every edge carries:
+
+- a `kind` — `http`, `grpc`, `event`, `package`, or `co_change`;
+- a `match_type` — `exact`, `candidate`, `manual`, or `inferred`;
+- a `confidence` and a `weight` (how many underlying contracts / deps / co-changes it aggregates);
+- `contract_refs` back-pointers so any view can drill from an edge to its evidence.
+
+Edge direction is uniform: **`source` depends on / calls `target`.** A consumer points to the provider it calls; a dependent repo points to the repo it imports. Structural edges (contracts, package deps) are flagged distinctly from behavioral co-change edges — repowise never conflates "these change together" with "these call each other".
+
+Fetch it over REST with `GET /api/workspace/system-graph`.
+
+## Extraction Diagnostics
+
+When the cross-repo link count looks low, diagnostics explain why. Computed alongside contract matching, they report — per repo and contract type — how many providers and consumers were found, which consumers went unmatched (and why), and which providers have no consumer at all.
+
+```bash
+repowise workspace diagnostics # human-readable report
+repowise workspace diagnostics --json # raw JSON
+repowise workspace diagnostics --repo api # limit to one repo
+```
+
+The report covers:
+
+- **Provider / consumer counts** per repo, broken down by contract type.
+- **Unmatched consumers**, grouped by reason:
+ - `no_provider` — no provider anywhere declares a matching route/service/topic.
+ - `internal_only` — the only matching provider is in the same repo + service, so the call is intra-service and intentionally not surfaced as a cross-repo link.
+ - `unlinked` — a cross-service provider with a matching id exists, but no link formed (a candidate worth inspecting).
+- **Orphan providers** — endpoints declared but never consumed by any repo.
+- **Weak links** — matched links below the confidence threshold.
+
+The same data is available over REST at `GET /api/workspace/diagnostics` and is embedded in the system graph artifact's `diagnostics` block.
+
+---
+
## Web UI
Start the web server:
@@ -240,6 +291,7 @@ my-workspace/
.repowise-workspace/ # Shared cross-repo data
cross_repo_edges.json # Co-change pairs and package deps
contracts.json # Extracted API contracts and links
+ system_graph.json # Service-granular system graph + diagnostics
.claude/
CLAUDE.md # Workspace-level CLAUDE.md for AI editors
backend/
diff --git a/packages/cli/src/repowise/cli/commands/workspace_cmd.py b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
index 1f5cff875..9b4dde58d 100644
--- a/packages/cli/src/repowise/cli/commands/workspace_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/workspace_cmd.py
@@ -235,9 +235,13 @@ def _format_relative_time(iso_timestamp: str | None) -> str:
"otherwise. Skipped silently when --no-index is passed."
),
)
[email protected]("--provider", "provider_name", default=None, help="LLM provider name (overrides primary's).")
+ "--provider", "provider_name", default=None, help="LLM provider name (overrides primary's)."
+)
@click.option("--model", default=None, help="Model identifier (overrides primary's).")
[email protected]("--concurrency", type=int, default=10, help="Max concurrent LLM calls during doc generation.")
+ "--concurrency", type=int, default=10, help="Max concurrent LLM calls during doc generation."
+)
def workspace_add(
path: str,
alias: str | None,
@@ -270,9 +274,7 @@ def workspace_add(
# Validate it is a git repo
if not (repo_path / ".git").exists():
- raise click.ClickException(
- f"Not a git repository (no .git found): {repo_path}"
- )
+ raise click.ClickException(f"Not a git repository (no .git found): {repo_path}")
# Default alias to directory name
if alias is None:
@@ -500,16 +502,16 @@ def _run_index_for_repo(
if generate_docs:
try:
provider = resolve_provider(
- effective_provider, effective_model, repo_path=repo_path,
+ effective_provider,
+ effective_model,
+ repo_path=repo_path,
)
console.print(
f" Provider: [cyan]{provider.provider_name}[/cyan] / "
f"Model: [cyan]{provider.model_name}[/cyan]"
)
except Exception as exc:
- console.print(
- f" [yellow]Provider unavailable ({exc}); skipping docs.[/yellow]"
- )
+ console.print(f" [yellow]Provider unavailable ({exc}); skipping docs.[/yellow]")
generate_docs = False
docs_skip_reason = f"provider failure: {exc}"
@@ -561,9 +563,7 @@ def _run_index_for_repo(
try:
file_count, symbol_count, _ = run_async(_do_index())
- console.print(
- f" [green]✓[/green] {file_count} files, {symbol_count:,} symbols"
- )
+ console.print(f" [green]✓[/green] {file_count} files, {symbol_count:,} symbols")
except Exception as exc:
console.print(f"[yellow]Warning:[/yellow] Indexing failed for '{alias}': {exc}")
return
@@ -629,12 +629,9 @@ def _run_index_for_repo(
# docs-skipped case.
if not state["docs_enabled"]:
reason = docs_skip_reason or "docs disabled"
+ console.print(f"\n[yellow]Note:[/yellow] '{alias}' indexed without docs ({reason}).")
console.print(
- f"\n[yellow]Note:[/yellow] '{alias}' indexed without docs ({reason})."
- )
- console.print(
- f" Run [bold]repowise update --repo {alias} --docs[/bold] "
- "to generate documentation."
+ f" Run [bold]repowise update --repo {alias} --docs[/bold] to generate documentation."
)
@@ -723,7 +720,9 @@ def _generate_docs_for_added_repo(
sf = create_session_factory(engine)
async with get_session(sf) as session:
repo = await upsert_repository(
- session, name=repo_path.name, local_path=str(repo_path),
+ session,
+ name=repo_path.name,
+ local_path=str(repo_path),
)
for p in pages:
await upsert_page_from_generated(session, p, repo.id)
@@ -755,9 +754,7 @@ def workspace_remove(alias: str) -> None:
entry = ws_config.get_repo(alias)
if entry is None:
available = ", ".join(ws_config.repo_aliases()) or "(none)"
- raise click.ClickException(
- f"No repo with alias '{alias}' found. Available: {available}"
- )
+ raise click.ClickException(f"No repo with alias '{alias}' found. Available: {available}")
is_default = alias == ws_config.default_repo
@@ -775,13 +772,9 @@ def workspace_remove(alias: str) -> None:
f"New default is '{new_default}'."
)
elif is_default:
- console.print(
- "[yellow]Note:[/yellow] Workspace now has no repos and no default."
- )
+ console.print("[yellow]Note:[/yellow] Workspace now has no repos and no default.")
- console.print(
- f" (Indexed data at {removed.path}/.repowise/ was [bold]not[/bold] deleted.)"
- )
+ console.print(f" (Indexed data at {removed.path}/.repowise/ was [bold]not[/bold] deleted.)")
# ---------------------------------------------------------------------------
@@ -810,15 +803,12 @@ def workspace_scan(path: str | None, yes: bool) -> None:
scan_result = scan_for_repos(ws_root)
existing_aliases = set(ws_config.repo_aliases())
- existing_paths = {
- (ws_root / e.path).resolve().as_posix()
- for e in ws_config.repos
- }
+ existing_paths = {(ws_root / e.path).resolve().as_posix() for e in ws_config.repos}
new_repos = [
- r for r in scan_result.repos
- if r.path.as_posix() not in existing_paths
- and r.alias not in existing_aliases
+ r
+ for r in scan_result.repos
+ if r.path.as_posix() not in existing_paths and r.alias not in existing_aliases
]
if not new_repos:
@@ -880,9 +870,7 @@ def workspace_set_default(alias: str) -> None:
entry = ws_config.get_repo(alias)
if entry is None:
available = ", ".join(ws_config.repo_aliases()) or "(none)"
- raise click.ClickException(
- f"No repo with alias '{alias}' found. Available: {available}"
- )
+ raise click.ClickException(f"No repo with alias '{alias}' found. Available: {available}")
previous_default = ws_config.default_repo
@@ -900,3 +888,106 @@ def workspace_set_default(alias: str) -> None:
)
else:
console.print(f"[green]✓[/green] Default repo set to '[bold]{alias}[/bold]'.")
+
+
+# ---------------------------------------------------------------------------
+# workspace diagnostics
+# ---------------------------------------------------------------------------
+
+
+@workspace_group.command("diagnostics")
[email protected]("path", required=False, default=None)
[email protected]("--repo", "repo_alias", default=None, help="Limit the report to one repo alias.")
[email protected]("--json", "as_json", is_flag=True, help="Emit raw diagnostics JSON.")
+def workspace_diagnostics(path: str | None, repo_alias: str | None, as_json: bool) -> None:
+ """Explain the cross-repo contract link count.
+
+ Reports, per repo, how many providers and consumers were found, which
+ consumers went unmatched and why, and which providers have no consumer —
+ the answer to "why are there so few links?". Reads the system graph built
+ during 'repowise update --workspace'.
+ """
+ import json as _json
+
+ from repowise.core.workspace.system_graph import load_system_graph
+
+ start = resolve_repo_path(path)
+ ws_root, _ws_config = _require_workspace(start)
+
+ graph = load_system_graph(ws_root)
+ if graph is None:
+ raise click.ClickException(
+ "No system graph found. Run 'repowise update --workspace' to build "
+ "cross-repo contracts and diagnostics first."
+ )
+
+ diag = graph.diagnostics
+ breakdown = diag.repo_breakdown
+ unmatched = diag.unmatched_consumers
+ orphans = diag.orphan_providers
+ if repo_alias:
+ breakdown = [r for r in breakdown if r.repo == repo_alias]
+ unmatched = [u for u in unmatched if u.repo == repo_alias]
+ orphans = [o for o in orphans if o.repo == repo_alias]
+
+ if as_json:
+ payload = {
+ "total_providers": diag.total_providers,
+ "total_consumers": diag.total_consumers,
+ "total_links": diag.total_links,
+ "weak_link_count": diag.weak_link_count,
+ "repo_breakdown": [r.to_dict() for r in breakdown],
+ "unmatched_consumers": [u.to_dict() for u in unmatched],
+ "unmatched_by_reason": diag.unmatched_by_reason,
+ "orphan_providers": [o.to_dict() for o in orphans],
+ }
+ console.print_json(_json.dumps(payload))
+ return
+
+ # Per-repo provider/consumer breakdown
+ table = Table(title=f"Contract extraction — {ws_root.name}")
+ table.add_column("Repo", style="cyan")
+ table.add_column("Providers", justify="right")
+ table.add_column("Consumers", justify="right")
+ table.add_column("By type", style="dim")
+ for r in breakdown:
+ by_type = ", ".join(
+ f"{t}:{r.providers_by_type.get(t, 0)}/{r.consumers_by_type.get(t, 0)}"
+ for t in sorted(set(r.providers_by_type) | set(r.consumers_by_type))
+ )
+ table.add_row(r.repo, str(r.provider_count), str(r.consumer_count), by_type or "-")
+ console.print(table)
+
+ console.print(
+ f"\n [bold]{diag.total_links}[/bold] cross-repo link(s) matched "
+ f"from {diag.total_providers} provider(s) and {diag.total_consumers} consumer(s)."
+ )
+ if diag.weak_link_count:
+ console.print(f" [yellow]{diag.weak_link_count}[/yellow] weak (low-confidence) link(s).")
+
+ # Unmatched consumers grouped by reason
+ if unmatched:
+ reason_labels = {
+ "no_provider": "no matching provider found",
+ "internal_only": "provider is same repo + service (intra-service)",
+ "unlinked": "matching provider exists but no link formed",
+ }
+ console.print(f"\n [bold]{len(unmatched)}[/bold] unmatched consumer(s):")
+ for reason, count in sorted(diag.unmatched_by_reason.items()):
+ label = reason_labels.get(reason, reason)
+ console.print(f" [yellow]{count}[/yellow] — {label}")
+
+ # Orphan providers
+ if orphans:
+ console.print(
+ f"\n [bold]{len(orphans)}[/bold] orphan provider(s) (declared, never consumed):"
+ )
+ for o in orphans[:20]:
+ console.print(f" [dim]{o.repo}[/dim] {o.contract_id} ([dim]{o.file_path}[/dim])")
+ if len(orphans) > 20:
+ console.print(f" [dim]... and {len(orphans) - 20} more[/dim]")
+
+ if not unmatched and not orphans:
+ console.print(
+ "\n [green]✓[/green] Every consumer matched a provider; no orphan providers."
+ )
diff --git a/packages/core/src/repowise/core/workspace/__init__.py b/packages/core/src/repowise/core/workspace/__init__.py
index 89f691062..377bcee5a 100644
--- a/packages/core/src/repowise/core/workspace/__init__.py
+++ b/packages/core/src/repowise/core/workspace/__init__.py
@@ -49,6 +49,26 @@ from .contracts import (
run_contract_extraction,
save_contract_store,
)
+from .diagnostics import (
+ WEAK_LINK_CONFIDENCE_THRESHOLD,
+ ExtractionDiagnostics,
+ OrphanProvider,
+ RepoDiagnostics,
+ UnmatchedConsumer,
+ UnmatchedReason,
+ build_diagnostics,
+)
+from .system_graph import (
+ EDGE_KINDS,
+ SYSTEM_GRAPH_FILENAME,
+ SystemEdge,
+ SystemGraph,
+ SystemNode,
+ build_system_graph,
+ load_system_graph,
+ run_system_graph_build,
+ save_system_graph,
+)
__all__ = [
# Scanner
@@ -89,4 +109,22 @@ __all__ = [
"load_contract_store",
"run_contract_extraction",
"save_contract_store",
+ # Extraction diagnostics
+ "WEAK_LINK_CONFIDENCE_THRESHOLD",
+ "ExtractionDiagnostics",
+ "OrphanProvider",
+ "RepoDiagnostics",
+ "UnmatchedConsumer",
+ "UnmatchedReason",
+ "build_diagnostics",
+ # System graph
+ "EDGE_KINDS",
+ "SYSTEM_GRAPH_FILENAME",
+ "SystemEdge",
+ "SystemGraph",
+ "SystemNode",
+ "build_system_graph",
+ "load_system_graph",
+ "run_system_graph_build",
+ "save_system_graph",
]
diff --git a/packages/core/src/repowise/core/workspace/diagnostics.py b/packages/core/src/repowise/core/workspace/diagnostics.py
new file mode 100644
index 000000000..0dda3d2cf
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/diagnostics.py
@@ -0,0 +1,284 @@
+"""Extraction diagnostics — explain the cross-repo contract link count.
+
+Derived purely from the contracts + matched links already produced by
+:mod:`repowise.core.workspace.contracts`. Answers the question a workspace
+owner actually asks: *"why are there so few links?"* — by reporting, per repo
+and contract type, how many providers and consumers were found, which consumers
+went unmatched and why, and which providers have no consumer at all.
+
+This module performs no I/O and has no DB dependency. It consumes the same
+:class:`Contract` / :class:`ContractLink` objects the matcher emits, so it is
+cheap to compute alongside contract extraction and trivial to unit test.
+
+The serialized :class:`ExtractionDiagnostics` is embedded in the system-graph
+artifact (see :mod:`repowise.core.workspace.system_graph`) and surfaced through
+``GET /api/workspace/diagnostics`` and ``repowise workspace diagnostics``.
+"""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+from repowise.core.workspace.contracts import (
+ Contract,
+ ContractLink,
+ normalize_contract_id,
+)
+
+# ---------------------------------------------------------------------------
+# Constants (single source of truth)
+# ---------------------------------------------------------------------------
+
+#: Links at or below this confidence are reported as "weak" — a candidate match
+#: or a low-confidence extraction a reviewer may want to eyeball. Kept here so
+#: every consumer (core, server, CLI) reads one cutoff.
+WEAK_LINK_CONFIDENCE_THRESHOLD = 0.4
+
+
+class UnmatchedReason:
+ """Why a consumer contract never formed a cross-repo link."""
+
+ #: No provider anywhere declares a route/service/topic with this id.
+ NO_PROVIDER = "no_provider"
+ #: The only matching provider(s) live in the same repo + service, so the
+ #: call is intra-service and intentionally not surfaced as a cross-repo link.
+ INTERNAL_ONLY = "internal_only"
+ #: A cross-service provider with a matching id exists, but no link was
+ #: formed (e.g. an HTTP path that only the candidate pass could bridge and
+ #: did not). Rare; flags a potential matcher gap worth inspecting.
+ UNLINKED = "unlinked"
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class RepoDiagnostics:
+ """Per-repo provider/consumer breakdown by contract type."""
+
+ repo: str
+ providers_by_type: dict[str, int] = field(default_factory=dict)
+ consumers_by_type: dict[str, int] = field(default_factory=dict)
+ provider_count: int = 0
+ consumer_count: int = 0
+
+ def to_dict(self) -> dict[str, Any]:
+ return asdict(self)
+
+
+@dataclass
+class UnmatchedConsumer:
+ """A consumer contract that did not link to any provider, with the reason."""
+
+ repo: str
+ file_path: str
+ contract_id: str
+ contract_type: str
+ reason: str # one of UnmatchedReason
+
+ def to_dict(self) -> dict[str, Any]:
+ return asdict(self)
+
+
+@dataclass
+class OrphanProvider:
+ """A provider contract that no consumer (in any repo) calls."""
+
+ repo: str
+ file_path: str
+ contract_id: str
+ contract_type: str
+
+ def to_dict(self) -> dict[str, Any]:
+ return asdict(self)
+
+
+@dataclass
+class ExtractionDiagnostics:
+ """Aggregate explanation of contract extraction + matching coverage."""
+
+ total_providers: int = 0
+ total_consumers: int = 0
+ total_links: int = 0
+ weak_link_count: int = 0
+ repo_breakdown: list[RepoDiagnostics] = field(default_factory=list)
+ unmatched_consumers: list[UnmatchedConsumer] = field(default_factory=list)
+ unmatched_by_reason: dict[str, int] = field(default_factory=dict)
+ orphan_providers: list[OrphanProvider] = field(default_factory=list)
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "total_providers": self.total_providers,
+ "total_consumers": self.total_consumers,
+ "total_links": self.total_links,
+ "weak_link_count": self.weak_link_count,
+ "repo_breakdown": [r.to_dict() for r in self.repo_breakdown],
+ "unmatched_consumers": [u.to_dict() for u in self.unmatched_consumers],
+ "unmatched_by_reason": self.unmatched_by_reason,
+ "orphan_providers": [o.to_dict() for o in self.orphan_providers],
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> ExtractionDiagnostics:
+ return cls(
+ total_providers=data.get("total_providers", 0),
+ total_consumers=data.get("total_consumers", 0),
+ total_links=data.get("total_links", 0),
+ weak_link_count=data.get("weak_link_count", 0),
+ repo_breakdown=[
+ RepoDiagnostics(
+ repo=r.get("repo", ""),
+ providers_by_type=r.get("providers_by_type", {}),
+ consumers_by_type=r.get("consumers_by_type", {}),
+ provider_count=r.get("provider_count", 0),
+ consumer_count=r.get("consumer_count", 0),
+ )
+ for r in data.get("repo_breakdown", [])
+ ],
+ unmatched_consumers=[
+ UnmatchedConsumer(
+ repo=u.get("repo", ""),
+ file_path=u.get("file_path", ""),
+ contract_id=u.get("contract_id", ""),
+ contract_type=u.get("contract_type", ""),
+ reason=u.get("reason", UnmatchedReason.NO_PROVIDER),
+ )
+ for u in data.get("unmatched_consumers", [])
+ ],
+ unmatched_by_reason=data.get("unmatched_by_reason", {}),
+ orphan_providers=[
+ OrphanProvider(
+ repo=o.get("repo", ""),
+ file_path=o.get("file_path", ""),
+ contract_id=o.get("contract_id", ""),
+ contract_type=o.get("contract_type", ""),
+ )
+ for o in data.get("orphan_providers", [])
+ ],
+ )
+
+
+# ---------------------------------------------------------------------------
+# Builder
+# ---------------------------------------------------------------------------
+
+
+def _contract_key(repo: str, file_path: str, contract_id: str) -> tuple[str, str, str]:
+ """Stable identity for a contract endpoint, normalized for matching."""
+ return (repo, file_path, normalize_contract_id(contract_id))
+
+
+def _classify_unmatched(
+ consumer: Contract,
+ providers_by_norm_id: dict[str, list[Contract]],
+) -> str:
+ """Return the :class:`UnmatchedReason` for an unmatched *consumer*."""
+ candidates = providers_by_norm_id.get(normalize_contract_id(consumer.contract_id))
+ if not candidates:
+ return UnmatchedReason.NO_PROVIDER
+ # A matching provider exists. If every one shares this consumer's repo AND
+ # service boundary, the call is intra-service and was filtered on purpose.
+ all_internal = all(
+ p.repo == consumer.repo and p.service == consumer.service for p in candidates
+ )
+ return UnmatchedReason.INTERNAL_ONLY if all_internal else UnmatchedReason.UNLINKED
+
+
+def build_diagnostics(
+ contracts: list[Contract],
+ links: list[ContractLink],
+) -> ExtractionDiagnostics:
+ """Compute extraction diagnostics from contracts and matched links.
+
+ Pure and O(contracts + links). The reported orphan/unmatched lists let a
+ workspace owner see exactly which endpoints failed to connect and why,
+ rather than just a bare link total.
+ """
+ providers = [c for c in contracts if c.role == "provider"]
+ consumers = [c for c in contracts if c.role == "consumer"]
+
+ # Per-repo breakdown ----------------------------------------------------
+ repos = sorted({c.repo for c in contracts})
+ breakdown: list[RepoDiagnostics] = []
+ for repo in repos:
+ prov_by_type: dict[str, int] = defaultdict(int)
+ cons_by_type: dict[str, int] = defaultdict(int)
+ for c in contracts:
+ if c.repo != repo:
+ continue
+ if c.role == "provider":
+ prov_by_type[c.contract_type] += 1
+ elif c.role == "consumer":
+ cons_by_type[c.contract_type] += 1
+ breakdown.append(
+ RepoDiagnostics(
+ repo=repo,
+ providers_by_type=dict(sorted(prov_by_type.items())),
+ consumers_by_type=dict(sorted(cons_by_type.items())),
+ provider_count=sum(prov_by_type.values()),
+ consumer_count=sum(cons_by_type.values()),
+ )
+ )
+
+ # Matched endpoint sets (normalized) ------------------------------------
+ matched_consumers: set[tuple[str, str, str]] = set()
+ matched_providers: set[tuple[str, str, str]] = set()
+ weak_links = 0
+ for lk in links:
+ matched_consumers.add(_contract_key(lk.consumer_repo, lk.consumer_file, lk.contract_id))
+ matched_providers.add(_contract_key(lk.provider_repo, lk.provider_file, lk.contract_id))
+ if lk.confidence <= WEAK_LINK_CONFIDENCE_THRESHOLD:
+ weak_links += 1
+
+ providers_by_norm_id: dict[str, list[Contract]] = defaultdict(list)
+ for p in providers:
+ providers_by_norm_id[normalize_contract_id(p.contract_id)].append(p)
+
+ # Unmatched consumers, grouped by reason --------------------------------
+ unmatched: list[UnmatchedConsumer] = []
+ by_reason: dict[str, int] = defaultdict(int)
+ for c in consumers:
+ key = _contract_key(c.repo, c.file_path, c.contract_id)
+ if key in matched_consumers:
+ continue
+ reason = _classify_unmatched(c, providers_by_norm_id)
+ by_reason[reason] += 1
+ unmatched.append(
+ UnmatchedConsumer(
+ repo=c.repo,
+ file_path=c.file_path,
+ contract_id=c.contract_id,
+ contract_type=c.contract_type,
+ reason=reason,
+ )
+ )
+
+ # Orphan providers — declared but never consumed ------------------------
+ orphans: list[OrphanProvider] = []
+ for p in providers:
+ key = _contract_key(p.repo, p.file_path, p.contract_id)
+ if key in matched_providers:
+ continue
+ orphans.append(
+ OrphanProvider(
+ repo=p.repo,
+ file_path=p.file_path,
+ contract_id=p.contract_id,
+ contract_type=p.contract_type,
+ )
+ )
+
+ return ExtractionDiagnostics(
+ total_providers=len(providers),
+ total_consumers=len(consumers),
+ total_links=len(links),
+ weak_link_count=weak_links,
+ repo_breakdown=breakdown,
+ unmatched_consumers=unmatched,
+ unmatched_by_reason=dict(sorted(by_reason.items())),
+ orphan_providers=orphans,
+ )
diff --git a/packages/core/src/repowise/core/workspace/system_graph.py b/packages/core/src/repowise/core/workspace/system_graph.py
new file mode 100644
index 000000000..7a03c2399
--- /dev/null
+++ b/packages/core/src/repowise/core/workspace/system_graph.py
@@ -0,0 +1,500 @@
+"""System graph — the one normalized cross-repo structure every view reads.
+
+Workspace mode already detects contracts, package dependencies, and file-level
+co-changes, but each is a flat list. This module folds them into a single
+service-granular graph:
+
+* **Nodes are services**, not repos. A monorepo with three service boundaries
+ yields three nodes; the repo is a grouping attribute on each node. A repo with
+ no detected sub-boundary collapses to one repo-root node.
+* **Edges are typed and honest.** Every edge carries its ``kind`` (http / grpc /
+ event / package / co_change / db), ``match_type`` (exact / candidate / manual /
+ inferred), a ``confidence``, a ``weight`` (how many underlying contracts /
+ co-changes / deps it aggregates), and ``contract_refs`` back-pointers so any
+ consumer can drill from an edge to its evidence. Structural edges (contracts,
+ package deps) are flagged distinctly from behavioral co-change edges.
+
+Edge direction is uniform: **source depends on / calls target.** A consumer
+points to the provider it calls; a dependent repo points to the repo it imports.
+
+The graph is built once during ``repowise update --workspace`` (where contracts,
+the cross-repo overlay, and service boundaries are all in hand) and persisted to
+``.repowise-workspace/system_graph.json``. The map (Phase 2), blast radius, the
+DSM, and the MCP/CLI surfaces are all *views* over this one artifact — none of
+them re-derives the graph.
+
+Pure and I/O-free except for the thin ``save_system_graph`` / ``load_system_graph``
+helpers and the ``run_system_graph_build`` orchestrator at the bottom.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, field
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+from repowise.core.workspace.config import (
+ WORKSPACE_DATA_DIR,
+ WorkspaceConfig,
+ ensure_workspace_data_dir,
+)
+from repowise.core.workspace.contracts import Contract, ContractLink, ContractStore
+from repowise.core.workspace.cross_repo import CrossRepoOverlay
+from repowise.core.workspace.diagnostics import ExtractionDiagnostics, build_diagnostics
+from repowise.core.workspace.extractors.service_boundary import (
+ ServiceBoundary,
+ assign_service,
+ detect_service_boundaries,
+)
+
+_log = logging.getLogger("repowise.workspace.system_graph")
+
+# ---------------------------------------------------------------------------
+# Constants (single source of truth)
+# ---------------------------------------------------------------------------
+
+SYSTEM_GRAPH_FILENAME = "system_graph.json"
+
+#: Maps a contract's ``contract_type`` to the system-graph edge ``kind``. New
+#: contract transports add one line here, never an ``if/elif`` branch downstream.
+_CONTRACT_TYPE_TO_EDGE_KIND: dict[str, str] = {
+ "http": "http",
+ "grpc": "grpc",
+ "topic": "event",
+}
+
+#: All edge kinds the graph can carry. ``db`` is reserved for a future
+#: shared-table transport; the taxonomy is fixed now so views render consistently.
+EDGE_KINDS: tuple[str, ...] = ("http", "grpc", "event", "package", "co_change", "db")
+
+#: ``match_type`` precedence when several links collapse onto one edge — the most
+#: authoritative wins for display. Higher is stronger.
+_MATCH_TYPE_RANK: dict[str, int] = {
+ "exact": 3,
+ "manual": 2,
+ "candidate": 1,
+ "inferred": 0,
+}
+
+#: Cap on the number of evidence back-pointers stored per edge. ``weight`` always
+#: reflects the true contributor count; this only bounds the drill-down list so a
+#: pathological co-change fan-out can't bloat the artifact.
+MAX_EDGE_REFS = 50
+
+#: Structural edges assert a real dependency; behavioral (co-change) edges only
+#: assert correlated change. Kept distinct so reachability and the map never
+#: conflate "call each other" with "change together".
+_STRUCTURAL_KINDS: frozenset[str] = frozenset({"http", "grpc", "event", "package", "db"})
+
+
+def edge_kind_for_contract_type(contract_type: str) -> str:
+ """Map a contract type to its edge kind, falling back to the type itself."""
+ return _CONTRACT_TYPE_TO_EDGE_KIND.get(contract_type, contract_type)
+
+
+# ---------------------------------------------------------------------------
+# Data models
+# ---------------------------------------------------------------------------
+
+
+@dataclass
+class SystemNode:
+ """A service in the workspace (or a repo-root node when undivided)."""
+
+ id: str # "repo" or "repo::service/path"
+ repo: str # repo alias — the grouping attribute
+ service_path: str | None # None for a whole-repo node
+ name: str # display name (service dir basename, or repo alias)
+ kind: str = "service" # service | frontend | worker | library | external
+ provider_count: int = 0
+ consumer_count: int = 0
+ contract_types: list[str] = field(default_factory=list)
+ is_orphan_provider: bool = False # exposes providers nobody consumes
+ is_orphan_consumer: bool = False # consumes contracts that never matched
+ is_isolated: bool = False # participates in no edges
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "id": self.id,
+ "repo": self.repo,
+ "service_path": self.service_path,
+ "name": self.name,
+ "kind": self.kind,
+ "provider_count": self.provider_count,
+ "consumer_count": self.consumer_count,
+ "contract_types": self.contract_types,
+ "is_orphan_provider": self.is_orphan_provider,
+ "is_orphan_consumer": self.is_orphan_consumer,
+ "is_isolated": self.is_isolated,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> SystemNode:
+ return cls(
+ id=data["id"],
+ repo=data["repo"],
+ service_path=data.get("service_path"),
+ name=data.get("name", data["id"]),
+ kind=data.get("kind", "service"),
+ provider_count=data.get("provider_count", 0),
+ consumer_count=data.get("consumer_count", 0),
+ contract_types=data.get("contract_types", []),
+ is_orphan_provider=data.get("is_orphan_provider", False),
+ is_orphan_consumer=data.get("is_orphan_consumer", False),
+ is_isolated=data.get("is_isolated", False),
+ )
+
+
+@dataclass
+class SystemEdge:
+ """A typed, directed relationship between two services (source → target)."""
+
+ id: str
+ source: str # node id that depends on / calls the target
+ target: str # node id that is depended on / called
+ kind: str # one of EDGE_KINDS
+ match_type: str # exact | candidate | manual | inferred
+ confidence: float
+ weight: int # number of underlying contracts / co-changes / deps
+ structural: bool # True for contract/package, False for co-change
+ contract_refs: list[str] = field(default_factory=list)
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "id": self.id,
+ "source": self.source,
+ "target": self.target,
+ "kind": self.kind,
+ "match_type": self.match_type,
+ "confidence": self.confidence,
+ "weight": self.weight,
+ "structural": self.structural,
+ "contract_refs": self.contract_refs,
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> SystemEdge:
+ return cls(
+ id=data["id"],
+ source=data["source"],
+ target=data["target"],
+ kind=data["kind"],
+ match_type=data.get("match_type", "exact"),
+ confidence=data.get("confidence", 0.0),
+ weight=data.get("weight", 1),
+ structural=data.get("structural", True),
+ contract_refs=data.get("contract_refs", []),
+ )
+
+
+@dataclass
+class SystemGraph:
+ """The versioned cross-repo structure: nodes, typed edges, diagnostics."""
+
+ version: int = 1
+ generated_at: str = ""
+ nodes: list[SystemNode] = field(default_factory=list)
+ edges: list[SystemEdge] = field(default_factory=list)
+ diagnostics: ExtractionDiagnostics = field(default_factory=ExtractionDiagnostics)
+
+ def to_dict(self) -> dict[str, Any]:
+ return {
+ "version": self.version,
+ "generated_at": self.generated_at,
+ "nodes": [n.to_dict() for n in self.nodes],
+ "edges": [e.to_dict() for e in self.edges],
+ "diagnostics": self.diagnostics.to_dict(),
+ }
+
+ @classmethod
+ def from_dict(cls, data: dict[str, Any]) -> SystemGraph:
+ return cls(
+ version=data.get("version", 1),
+ generated_at=data.get("generated_at", ""),
+ nodes=[SystemNode.from_dict(n) for n in data.get("nodes", [])],
+ edges=[SystemEdge.from_dict(e) for e in data.get("edges", [])],
+ diagnostics=ExtractionDiagnostics.from_dict(data.get("diagnostics", {})),
+ )
+
+
+# ---------------------------------------------------------------------------
+# Graph assembly (pure)
+# ---------------------------------------------------------------------------
+
+
+def _node_id(repo: str, service_path: str | None) -> str:
+ return repo if service_path is None else f"{repo}::{service_path}"
+
+
+class _GraphBuilder:
+ """Accumulates nodes and aggregated edges as contracts/edges are walked.
+
+ Edges that share ``(source, target, kind)`` collapse into one weighted edge:
+ weight counts contributors, confidence keeps the max, match_type keeps the
+ most authoritative, and refs accumulate (bounded by :data:`MAX_EDGE_REFS`).
+ """
+
+ def __init__(self, boundaries_by_repo: dict[str, list[ServiceBoundary]]) -> None:
+ self._boundaries = boundaries_by_repo
+ self._nodes: dict[str, SystemNode] = {}
+ self._edges: dict[tuple[str, str, str], SystemEdge] = {}
+
+ # -- nodes ----------------------------------------------------------------
+
+ def resolve_node(self, repo: str, file_path: str | None) -> str:
+ """Return the node id for *file_path* in *repo*, creating it if needed.
+
+ ``file_path is None`` resolves to the repo-root node (repo-level facts
+ like a package dependency on a whole repo).
+ """
+ service = (
+ assign_service(file_path, self._boundaries.get(repo, []))
+ if file_path is not None
+ else None
+ )
+ nid = _node_id(repo, service)
+ if nid not in self._nodes:
+ self._nodes[nid] = SystemNode(
+ id=nid,
+ repo=repo,
+ service_path=service,
+ name=service.rsplit("/", 1)[-1] if service else repo,
+ )
+ return nid
+
+ def count_contract(self, contract: Contract) -> None:
+ nid = self.resolve_node(contract.repo, contract.file_path)
+ node = self._nodes[nid]
+ if contract.role == "provider":
+ node.provider_count += 1
+ elif contract.role == "consumer":
+ node.consumer_count += 1
+ if contract.contract_type not in node.contract_types:
+ node.contract_types.append(contract.contract_type)
+
+ # -- edges ----------------------------------------------------------------
+
+ def add_edge(
+ self,
+ source: str,
+ target: str,
+ kind: str,
+ match_type: str,
+ confidence: float,
+ ref: str,
+ ) -> None:
+ if source == target:
+ return # intra-node calls aren't system-level edges
+ structural = kind in _STRUCTURAL_KINDS
+ if not structural:
+ # Co-change is symmetric — canonicalize direction so A~B and B~A
+ # collapse to a single undirected edge.
+ source, target = sorted((source, target))
+ key = (source, target, kind)
+ existing = self._edges.get(key)
+ if existing is None:
+ self._edges[key] = SystemEdge(
+ id=f"{source}->{target}:{kind}",
+ source=source,
+ target=target,
+ kind=kind,
+ match_type=match_type,
+ confidence=round(confidence, 3),
+ weight=1,
+ structural=structural,
+ contract_refs=[ref] if ref else [],
+ )
+ return
+ existing.weight += 1
+ existing.confidence = round(max(existing.confidence, confidence), 3)
+ if _MATCH_TYPE_RANK.get(match_type, 0) > _MATCH_TYPE_RANK.get(existing.match_type, 0):
+ existing.match_type = match_type
+ if ref and len(existing.contract_refs) < MAX_EDGE_REFS:
+ existing.contract_refs.append(ref)
+
+ # -- finalize -------------------------------------------------------------
+
+ def finalize(
+ self, diagnostics: ExtractionDiagnostics
+ ) -> tuple[list[SystemNode], list[SystemEdge]]:
+ edges = list(self._edges.values())
+
+ endpoints: set[str] = set()
+ contract_targets: set[str] = set() # nodes consumed as a provider
+ contract_sources: set[str] = set() # nodes that call out as a consumer
+ for e in edges:
+ endpoints.add(e.source)
+ endpoints.add(e.target)
+ if e.structural and e.kind != "package":
+ contract_targets.add(e.target)
+ contract_sources.add(e.source)
+
+ for node in self._nodes.values():
+ node.contract_types = sorted(node.contract_types)
+ node.is_isolated = node.id not in endpoints
+ node.is_orphan_provider = node.provider_count > 0 and node.id not in contract_targets
+ node.is_orphan_consumer = node.consumer_count > 0 and node.id not in contract_sources
+
+ nodes = sorted(self._nodes.values(), key=lambda n: n.id)
+ edges.sort(key=lambda e: e.id)
+ return nodes, edges
+
+
+def build_system_graph(
+ contracts: list[Contract],
+ links: list[ContractLink],
+ overlay: CrossRepoOverlay,
+ boundaries_by_repo: dict[str, list[ServiceBoundary]],
+ diagnostics: ExtractionDiagnostics | None = None,
+ *,
+ version: int = 1,
+ generated_at: str = "",
+) -> SystemGraph:
+ """Assemble the service-granular system graph (pure, no I/O).
+
+ Nodes are derived from each contract's service boundary; edges from matched
+ contract links (consumer→provider), package dependencies (dependent→
+ dependency), and cross-repo co-changes (undirected, behavioral).
+ """
+ if diagnostics is None:
+ diagnostics = build_diagnostics(contracts, links)
+
+ builder = _GraphBuilder(boundaries_by_repo)
+
+ # 1. Nodes + provider/consumer counts from every contract.
+ for c in contracts:
+ builder.count_contract(c)
+
+ # 2. Contract edges — the consumer calls the provider.
+ for lk in links:
+ source = builder.resolve_node(lk.consumer_repo, lk.consumer_file)
+ target = builder.resolve_node(lk.provider_repo, lk.provider_file)
+ builder.add_edge(
+ source=source,
+ target=target,
+ kind=edge_kind_for_contract_type(lk.contract_type),
+ match_type=lk.match_type,
+ confidence=lk.confidence,
+ ref=lk.contract_id,
+ )
+
+ # 3. Package-dependency edges — the dependent repo imports the dependency.
+ for dep in overlay.package_deps:
+ source = builder.resolve_node(dep.source_repo, dep.source_manifest)
+ target = builder.resolve_node(dep.target_repo, None)
+ builder.add_edge(
+ source=source,
+ target=target,
+ kind="package",
+ match_type="exact",
+ confidence=1.0,
+ ref=f"{dep.kind}:{dep.source_manifest}",
+ )
+
+ # 4. Co-change edges — behavioral, undirected, lower trust.
+ for cc in overlay.co_changes:
+ source = builder.resolve_node(cc.source_repo, cc.source_file)
+ target = builder.resolve_node(cc.target_repo, cc.target_file)
+ builder.add_edge(
+ source=source,
+ target=target,
+ kind="co_change",
+ match_type="inferred",
+ confidence=cc.strength,
+ ref=f"{cc.source_file}~{cc.target_file}",
+ )
+
+ nodes, edges = builder.finalize(diagnostics)
+ return SystemGraph(
+ version=version,
+ generated_at=generated_at,
+ nodes=nodes,
+ edges=edges,
+ diagnostics=diagnostics,
+ )
+
+
+# ---------------------------------------------------------------------------
+# Persistence
+# ---------------------------------------------------------------------------
+
+
+def save_system_graph(graph: SystemGraph, workspace_root: Path) -> Path:
+ """Write the system graph to ``.repowise-workspace/system_graph.json``."""
+ data_dir = ensure_workspace_data_dir(workspace_root)
+ out_path = data_dir / SYSTEM_GRAPH_FILENAME
+ out_path.write_text(
+ json.dumps(graph.to_dict(), indent=2, ensure_ascii=False),
+ encoding="utf-8",
+ )
+ return out_path
+
+
+def load_system_graph(workspace_root: Path) -> SystemGraph | None:
+ """Load the system graph, or ``None`` if missing/unparseable."""
+ path = workspace_root / WORKSPACE_DATA_DIR / SYSTEM_GRAPH_FILENAME
+ if not path.is_file():
+ return None
+ try:
+ data = json.loads(path.read_text(encoding="utf-8"))
+ return SystemGraph.from_dict(data)
+ except Exception:
+ _log.warning("Failed to load system graph from %s", path, exc_info=True)
+ return None
+
+
+# ---------------------------------------------------------------------------
+# Orchestrator
+# ---------------------------------------------------------------------------
+
+
+def _detect_boundaries_by_repo(
+ ws_config: WorkspaceConfig, workspace_root: Path
+) -> dict[str, list[ServiceBoundary]]:
+ """Detect service boundaries for every indexed repo in the workspace."""
+ boundaries: dict[str, list[ServiceBoundary]] = {}
+ for entry in ws_config.repos:
+ resolved = (workspace_root / entry.path).resolve()
+ if resolved.is_dir() and (resolved / ".repowise").is_dir():
+ boundaries[entry.alias] = detect_service_boundaries(resolved)
+ return boundaries
+
+
+async def run_system_graph_build(
+ ws_config: WorkspaceConfig,
+ workspace_root: Path,
+ store: ContractStore,
+ overlay: CrossRepoOverlay,
+) -> SystemGraph:
+ """Build and persist the system graph from the latest contracts + overlay.
+
+ Called from ``run_cross_repo_hooks`` after contract extraction and
+ cross-repo analysis. Boundary detection (a filesystem walk) runs off-thread.
+ """
+ boundaries_by_repo = await asyncio.to_thread(
+ _detect_boundaries_by_repo, ws_config, workspace_root
+ )
+
+ diagnostics = build_diagnostics(store.contracts, store.contract_links)
+ graph = build_system_graph(
+ store.contracts,
+ store.contract_links,
+ overlay,
+ boundaries_by_repo,
+ diagnostics,
+ generated_at=datetime.now(UTC).isoformat(),
+ )
+
+ out_path = save_system_graph(graph, workspace_root)
+ _log.info(
+ "System graph built: %d nodes, %d edges, %d unmatched consumers → %s",
+ len(graph.nodes),
+ len(graph.edges),
+ len(diagnostics.unmatched_consumers),
+ out_path,
+ )
+ return graph
diff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.py
index 6bf3427f2..de07f953c 100644
--- a/packages/core/src/repowise/core/workspace/update.py
+++ b/packages/core/src/repowise/core/workspace/update.py
@@ -683,17 +683,26 @@ async def run_cross_repo_hooks(
if len(ws_config.repos) < 2:
return
- from .cross_repo import run_cross_repo_analysis
+ from .contracts import ContractStore, run_contract_extraction
+ from .cross_repo import CrossRepoOverlay, run_cross_repo_analysis
+ from .system_graph import run_system_graph_build
+ overlay = CrossRepoOverlay()
try:
- await run_cross_repo_analysis(ws_config, workspace_root, changed_repos)
+ overlay = await run_cross_repo_analysis(ws_config, workspace_root, changed_repos)
except Exception:
_log.warning("Cross-repo analysis failed", exc_info=True)
# Phase 4: Contract extraction
- from .contracts import run_contract_extraction
-
+ store = ContractStore()
try:
- await run_contract_extraction(ws_config, workspace_root, changed_repos)
+ store = await run_contract_extraction(ws_config, workspace_root, changed_repos)
except Exception:
_log.warning("Contract extraction failed", exc_info=True)
+
+ # System graph — the normalized service-granular structure every workspace
+ # view reads. Built last so it folds in the contracts and overlay above.
+ try:
+ await run_system_graph_build(ws_config, workspace_root, store, overlay)
+ except Exception:
+ _log.warning("System graph build failed", exc_info=True)
diff --git a/packages/server/src/repowise/server/app.py b/packages/server/src/repowise/server/app.py
index 594209bd9..8766a314e 100644
--- a/packages/server/src/repowise/server/app.py
+++ b/packages/server/src/repowise/server/app.py
@@ -309,12 +309,18 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
logger.warning("workspace_stale_job_reset_failed", extra={"error": str(exc)})
from repowise.core.workspace.contracts import CONTRACTS_FILENAME
+ from repowise.core.workspace.system_graph import SYSTEM_GRAPH_FILENAME
from repowise.server.mcp_server._enrichment import CrossRepoEnricher
cross_repo_path = _Path(ws_root) / WORKSPACE_DATA_DIR / "cross_repo_edges.json"
contracts_path = _Path(ws_root) / WORKSPACE_DATA_DIR / CONTRACTS_FILENAME
- enricher = CrossRepoEnricher(cross_repo_path, contracts_path=contracts_path)
- if enricher.has_data or enricher.has_contract_data:
+ system_graph_path = _Path(ws_root) / WORKSPACE_DATA_DIR / SYSTEM_GRAPH_FILENAME
+ enricher = CrossRepoEnricher(
+ cross_repo_path,
+ contracts_path=contracts_path,
+ system_graph_path=system_graph_path,
+ )
+ if enricher.has_data or enricher.has_contract_data or enricher.has_system_graph:
app.state.cross_repo_enricher = enricher
logger.info(
"repowise_workspace_detected",
diff --git a/packages/server/src/repowise/server/mcp_server/_enrichment.py b/packages/server/src/repowise/server/mcp_server/_enrichment.py
index 24aa933db..e8ce07f0e 100644
--- a/packages/server/src/repowise/server/mcp_server/_enrichment.py
+++ b/packages/server/src/repowise/server/mcp_server/_enrichment.py
@@ -22,6 +22,7 @@ class CrossRepoEnricher:
self,
data_path: Path,
contracts_path: Path | None = None,
+ system_graph_path: Path | None = None,
) -> None:
self._co_changes: list[dict] = []
self._package_deps: list[dict] = []
@@ -39,12 +40,19 @@ class CrossRepoEnricher:
self._contract_provider_index: dict[tuple[str, str], list[dict]] = defaultdict(list)
self._contract_consumer_index: dict[tuple[str, str], list[dict]] = defaultdict(list)
+ # System graph — the service-granular structure built during workspace
+ # update. Read-only pass-through; views over it live in core/types.
+ self._system_graph: dict | None = None
+
self._data_path = data_path
self._contracts_path = contracts_path
+ self._system_graph_path = system_graph_path
self._load(data_path)
if contracts_path is not None:
self._load_contracts(contracts_path)
+ if system_graph_path is not None:
+ self._load_system_graph(system_graph_path)
def _load(self, data_path: Path) -> None:
"""Parse JSON and build indexes."""
@@ -107,11 +115,13 @@ class CrossRepoEnricher:
except KeyError:
_log.debug("Skipping malformed package dep entry: %s", pd)
continue
- self._package_dep_index[src_repo].append({
- "target_repo": tgt_repo,
- "source_manifest": pd.get("source_manifest", ""),
- "kind": pd.get("kind", ""),
- })
+ self._package_dep_index[src_repo].append(
+ {
+ "target_repo": tgt_repo,
+ "source_manifest": pd.get("source_manifest", ""),
+ "kind": pd.get("kind", ""),
+ }
+ )
# Reverse: who depends on target_repo
self._package_dep_reverse[tgt_repo].append(src_repo)
@@ -130,9 +140,7 @@ class CrossRepoEnricher:
try:
data = json.loads(contracts_path.read_text(encoding="utf-8"))
except Exception:
- _log.warning(
- "Failed to parse contract data at %s", contracts_path, exc_info=True
- )
+ _log.warning("Failed to parse contract data at %s", contracts_path, exc_info=True)
return
self._contracts = data.get("contracts", [])
@@ -154,6 +162,22 @@ class CrossRepoEnricher:
len(self._contract_links),
)
+ def _load_system_graph(self, system_graph_path: Path) -> None:
+ """Parse ``system_graph.json`` (read-only pass-through to views)."""
+ if not system_graph_path.is_file():
+ _log.debug("No system graph at %s", system_graph_path)
+ return
+ try:
+ self._system_graph = json.loads(system_graph_path.read_text(encoding="utf-8"))
+ except Exception:
+ _log.warning("Failed to parse system graph at %s", system_graph_path, exc_info=True)
+ return
+ _log.debug(
+ "System graph loaded: %d nodes, %d edges",
+ len(self._system_graph.get("nodes", [])),
+ len(self._system_graph.get("edges", [])),
+ )
+
def reload(self) -> None:
"""Re-read JSON files from disk and rebuild all indexes.
@@ -172,10 +196,13 @@ class CrossRepoEnricher:
self._contract_links = []
self._contract_provider_index = defaultdict(list)
self._contract_consumer_index = defaultdict(list)
+ self._system_graph = None
self._load(self._data_path)
if self._contracts_path is not None:
self._load_contracts(self._contracts_path)
+ if self._system_graph_path is not None:
+ self._load_system_graph(self._system_graph_path)
_log.info(
"Cross-repo enricher reloaded: %d co-change edges, %d package deps, %d contract links",
@@ -194,9 +221,22 @@ class CrossRepoEnricher:
"""True if contracts or contract links are available."""
return bool(self._contracts or self._contract_links)
- def get_cross_repo_partners(
- self, repo_alias: str, file_path: str
- ) -> list[dict]:
+ @property
+ def has_system_graph(self) -> bool:
+ """True if a system graph artifact has been loaded."""
+ return self._system_graph is not None
+
+ def get_system_graph(self) -> dict | None:
+ """Return the raw system graph dict (nodes, edges, diagnostics)."""
+ return self._system_graph
+
+ def get_diagnostics(self) -> dict | None:
+ """Return just the extraction diagnostics block of the system graph."""
+ if self._system_graph is None:
+ return None
+ return self._system_graph.get("diagnostics")
+
+ def get_cross_repo_partners(self, repo_alias: str, file_path: str) -> list[dict]:
"""Return cross-repo co-change partners for a file.
Each dict: ``{repo, file, strength, frequency, last_date}``.
@@ -226,10 +266,7 @@ class CrossRepoEnricher:
repo_pairs[pair] += 1 # type: ignore[index]
top_connections = sorted(
- [
- {"repos": list(pair), "edge_count": count}
- for pair, count in repo_pairs.items()
- ],
+ [{"repos": list(pair), "edge_count": count} for pair, count in repo_pairs.items()],
key=lambda x: -x["edge_count"],
)[:5]
@@ -239,18 +276,14 @@ class CrossRepoEnricher:
"top_connections": top_connections,
}
- def has_cross_repo_consumers(
- self, repo_alias: str, file_path: str
- ) -> list[dict]:
+ def has_cross_repo_consumers(self, repo_alias: str, file_path: str) -> list[dict]:
"""Return files in OTHER repos that co-change with this file.
Each dict: ``{repo, file, strength}``.
"""
return self._consumer_index.get((repo_alias, file_path), [])
- def get_affected_repos(
- self, repo_alias: str, file_path: str
- ) -> list[str]:
+ def get_affected_repos(self, repo_alias: str, file_path: str) -> list[str]:
"""Return repo aliases that may be impacted by changes to this file.
Combines co-change partners + package dep consumers + contract links.
@@ -276,15 +309,11 @@ class CrossRepoEnricher:
# Contract queries (Phase 4)
# ------------------------------------------------------------------
- def get_contract_links_as_provider(
- self, repo_alias: str, file_path: str
- ) -> list[dict]:
+ def get_contract_links_as_provider(self, repo_alias: str, file_path: str) -> list[dict]:
"""Contract links where this file is the provider (has consumers)."""
return self._contract_provider_index.get((repo_alias, file_path), [])
- def get_contract_links_as_consumer(
- self, repo_alias: str, file_path: str
- ) -> list[dict]:
+ def get_contract_links_as_consumer(self, repo_alias: str, file_path: str) -> list[dict]:
"""Contract links where this file is the consumer (depends on providers)."""
return self._contract_consumer_index.get((repo_alias, file_path), [])
diff --git a/packages/server/src/repowise/server/mcp_server/_server.py b/packages/server/src/repowise/server/mcp_server/_server.py
index 7d033ade4..16b2108ce 100644
--- a/packages/server/src/repowise/server/mcp_server/_server.py
+++ b/packages/server/src/repowise/server/mcp_server/_server.py
@@ -284,12 +284,18 @@ async def _lifespan(server: FastMCP):
try:
from repowise.core.workspace.config import WORKSPACE_DATA_DIR
from repowise.core.workspace.contracts import CONTRACTS_FILENAME
+ from repowise.core.workspace.system_graph import SYSTEM_GRAPH_FILENAME
from repowise.server.mcp_server._enrichment import CrossRepoEnricher
cross_repo_path = ws_root / WORKSPACE_DATA_DIR / "cross_repo_edges.json"
contracts_path = ws_root / WORKSPACE_DATA_DIR / CONTRACTS_FILENAME
- enricher = CrossRepoEnricher(cross_repo_path, contracts_path=contracts_path)
- if enricher.has_data:
+ system_graph_path = ws_root / WORKSPACE_DATA_DIR / SYSTEM_GRAPH_FILENAME
+ enricher = CrossRepoEnricher(
+ cross_repo_path,
+ contracts_path=contracts_path,
+ system_graph_path=system_graph_path,
+ )
+ if enricher.has_data or enricher.has_system_graph:
_state._cross_repo_enricher = enricher
_log.info(
"Cross-repo enricher loaded: %d co-change edges, %d package deps, %d contract links",
diff --git a/packages/server/src/repowise/server/routers/workspace.py b/packages/server/src/repowise/server/routers/workspace.py
index 0baed1ad8..3dbf2302b 100644
--- a/packages/server/src/repowise/server/routers/workspace.py
+++ b/packages/server/src/repowise/server/routers/workspace.py
@@ -27,11 +27,13 @@ from repowise.server.schemas import (
WorkspaceContractsResponse,
WorkspaceContractSummary,
WorkspaceCrossRepoSummary,
+ WorkspaceExtractionDiagnostics,
WorkspaceGraphEdge,
WorkspaceGraphNode,
WorkspaceGraphResponse,
WorkspaceRepoEntry,
WorkspaceResponse,
+ WorkspaceSystemGraphResponse,
)
from repowise.server.services.module_health import read_repo_health_score
@@ -158,9 +160,7 @@ def _query_repo_stats(db_path: Path) -> dict:
# churn_percentile >= 90 predicate never matched: churn_percentile is
# stored on a 0.0-1.0 scale and only scaled to 0-100 at the API layer.
try:
- row = c.execute(
- "SELECT COUNT(*) FROM git_metadata WHERE is_hotspot = 1"
- ).fetchone()
+ row = c.execute("SELECT COUNT(*) FROM git_metadata WHERE is_hotspot = 1").fetchone()
result["hotspot_count"] = row[0] if row else 0
except sqlite3.OperationalError:
pass # table or column may not exist
@@ -252,7 +252,10 @@ async def get_contracts(
if enricher is None:
return WorkspaceContractsResponse(
- contracts=[], links=[], total_contracts=0, total_links=0,
+ contracts=[],
+ links=[],
+ total_contracts=0,
+ total_links=0,
)
contracts = list(getattr(enricher, "_contracts", []))
@@ -265,8 +268,7 @@ async def get_contracts(
if repo:
contracts = [c for c in contracts if c.get("repo") == repo]
links = [
- lk for lk in links
- if lk.get("provider_repo") == repo or lk.get("consumer_repo") == repo
+ lk for lk in links if lk.get("provider_repo") == repo or lk.get("consumer_repo") == repo
]
if role:
contracts = [c for c in contracts if c.get("role") == role]
@@ -341,7 +343,8 @@ async def get_co_changes(
if repo:
co_changes = [
- cc for cc in co_changes
+ cc
+ for cc in co_changes
if cc.get("source_repo") == repo or cc.get("target_repo") == repo
]
if min_strength > 0:
@@ -476,6 +479,54 @@ async def get_workspace_graph(
return WorkspaceGraphResponse(nodes=nodes, edges=edges)
+# ---------------------------------------------------------------------------
+# GET /api/workspace/system-graph
+# ---------------------------------------------------------------------------
+
+
[email protected]("/system-graph", response_model=WorkspaceSystemGraphResponse)
+async def get_system_graph(
+ ws_config=Depends(get_workspace_config),
+ enricher=Depends(get_cross_repo_enricher),
+):
+ """Service-granular system graph: typed service nodes + directed edges.
+
+ Read straight from the ``system_graph.json`` artifact built during workspace
+ update. Edge direction is uniform — ``source`` depends on / calls ``target``.
+ Returns an empty graph (not 404) when no graph has been built yet.
+ """
+ _require_workspace(ws_config)
+
+ graph = enricher.get_system_graph() if enricher is not None else None
+ if not graph:
+ return WorkspaceSystemGraphResponse()
+ return WorkspaceSystemGraphResponse(**graph)
+
+
+# ---------------------------------------------------------------------------
+# GET /api/workspace/diagnostics
+# ---------------------------------------------------------------------------
+
+
[email protected]("/diagnostics", response_model=WorkspaceExtractionDiagnostics)
+async def get_diagnostics(
+ ws_config=Depends(get_workspace_config),
+ enricher=Depends(get_cross_repo_enricher),
+):
+ """Extraction diagnostics — why the cross-repo link count is what it is.
+
+ Reports per-repo provider/consumer counts, unmatched consumers grouped by
+ reason, orphan providers, and weak links. Sourced from the system graph
+ artifact's ``diagnostics`` block.
+ """
+ _require_workspace(ws_config)
+
+ diagnostics = enricher.get_diagnostics() if enricher is not None else None
+ if not diagnostics:
+ return WorkspaceExtractionDiagnostics()
+ return WorkspaceExtractionDiagnostics(**diagnostics)
+
+
# ---------------------------------------------------------------------------
# POST /api/workspace/sync
# ---------------------------------------------------------------------------
@@ -547,7 +598,9 @@ async def sync_workspace(
WorkspaceSyncResult(
alias=entry.alias,
status="skipped",
- reason="not indexed yet (run `repowise update --repo " + entry.alias + "` from the CLI)",
+ reason="not indexed yet (run `repowise update --repo "
+ + entry.alias
+ + "` from the CLI)",
)
)
continue
@@ -555,9 +608,7 @@ async def sync_workspace(
# Discover repo_id from the per-repo DB.
try:
with sqlite3.connect(str(db_path)) as conn:
- row = conn.execute(
- "SELECT id FROM repositories LIMIT 1"
- ).fetchone()
+ row = conn.execute("SELECT id FROM repositories LIMIT 1").fetchone()
except Exception as exc:
results.append(
WorkspaceSyncResult(
diff --git a/packages/server/src/repowise/server/schemas/__init__.py b/packages/server/src/repowise/server/schemas/__init__.py
index 4b79029d7..cbcc8916c 100644
--- a/packages/server/src/repowise/server/schemas/__init__.py
+++ b/packages/server/src/repowise/server/schemas/__init__.py
@@ -162,13 +162,20 @@ from .workspace import (
WorkspaceContractsResponse,
WorkspaceContractSummary,
WorkspaceCrossRepoSummary,
+ WorkspaceExtractionDiagnostics,
WorkspaceGraphEdge,
WorkspaceGraphNode,
WorkspaceGraphResponse,
+ WorkspaceOrphanProvider,
+ WorkspaceRepoDiagnostics,
WorkspaceRepoEntry,
WorkspaceResponse,
WorkspaceSyncResponse,
WorkspaceSyncResult,
+ WorkspaceSystemEdge,
+ WorkspaceSystemGraphResponse,
+ WorkspaceSystemNode,
+ WorkspaceUnmatchedConsumer,
)
__all__ = [
@@ -292,11 +299,18 @@ __all__ = [
"WorkspaceContractSummary",
"WorkspaceContractsResponse",
"WorkspaceCrossRepoSummary",
+ "WorkspaceExtractionDiagnostics",
"WorkspaceGraphEdge",
"WorkspaceGraphNode",
"WorkspaceGraphResponse",
+ "WorkspaceOrphanProvider",
+ "WorkspaceRepoDiagnostics",
"WorkspaceRepoEntry",
"WorkspaceResponse",
"WorkspaceSyncResponse",
"WorkspaceSyncResult",
+ "WorkspaceSystemEdge",
+ "WorkspaceSystemGraphResponse",
+ "WorkspaceSystemNode",
+ "WorkspaceUnmatchedConsumer",
]
diff --git a/packages/server/src/repowise/server/schemas/workspace.py b/packages/server/src/repowise/server/schemas/workspace.py
index e8c47141f..7fed37484 100644
--- a/packages/server/src/repowise/server/schemas/workspace.py
+++ b/packages/server/src/repowise/server/schemas/workspace.py
@@ -139,3 +139,77 @@ class WorkspaceGraphEdge(BaseModel):
class WorkspaceGraphResponse(BaseModel):
nodes: list[WorkspaceGraphNode] = []
edges: list[WorkspaceGraphEdge] = []
+
+
+# ---------------------------------------------------------------------------
+# System graph (service-granular) + extraction diagnostics
+# Mirrors repowise.core.workspace.{system_graph,diagnostics}.
+# ---------------------------------------------------------------------------
+
+
+class WorkspaceSystemNode(BaseModel):
+ id: str
+ repo: str
+ service_path: str | None = None
+ name: str
+ kind: str = "service"
+ provider_count: int = 0
+ consumer_count: int = 0
+ contract_types: list[str] = []
+ is_orphan_provider: bool = False
+ is_orphan_consumer: bool = False
+ is_isolated: bool = False
+
+
+class WorkspaceSystemEdge(BaseModel):
+ id: str
+ source: str
+ target: str
+ kind: str # http | grpc | event | package | co_change | db
+ match_type: str # exact | candidate | manual | inferred
+ confidence: float = 0.0
+ weight: int = 1
+ structural: bool = True
+ contract_refs: list[str] = []
+
+
+class WorkspaceRepoDiagnostics(BaseModel):
+ repo: str
+ providers_by_type: dict[str, int] = {}
+ consumers_by_type: dict[str, int] = {}
+ provider_count: int = 0
+ consumer_count: int = 0
+
+
+class WorkspaceUnmatchedConsumer(BaseModel):
+ repo: str
+ file_path: str
+ contract_id: str
+ contract_type: str
+ reason: str # no_provider | internal_only | unlinked
+
+
+class WorkspaceOrphanProvider(BaseModel):
+ repo: str
+ file_path: str
+ contract_id: str
+ contract_type: str
+
+
+class WorkspaceExtractionDiagnostics(BaseModel):
+ total_providers: int = 0
+ total_consumers: int = 0
+ total_links: int = 0
+ weak_link_count: int = 0
+ repo_breakdown: list[WorkspaceRepoDiagnostics] = []
+ unmatched_consumers: list[WorkspaceUnmatchedConsumer] = []
+ unmatched_by_reason: dict[str, int] = {}
+ orphan_providers: list[WorkspaceOrphanProvider] = []
+
+
+class WorkspaceSystemGraphResponse(BaseModel):
+ version: int = 1
+ generated_at: str = ""
+ nodes: list[WorkspaceSystemNode] = []
+ edges: list[WorkspaceSystemEdge] = []
+ diagnostics: WorkspaceExtractionDiagnostics = WorkspaceExtractionDiagnostics()
diff --git a/packages/types/src/workspace.ts b/packages/types/src/workspace.ts
index f0068e9c5..5dfd54d9d 100644
--- a/packages/types/src/workspace.ts
+++ b/packages/types/src/workspace.ts
@@ -59,3 +59,105 @@ export interface WorkspacePackageDepEntry {
target_package: string;
kind: string;
}
+
+// ---------------------------------------------------------------------------
+// System graph — the service-granular, typed cross-repo structure that the
+// Live System Map, blast radius, the DSM, and the MCP/CLI surfaces all read.
+// Mirrors `repowise.core.workspace.system_graph` (Python). Edge direction is
+// uniform: `source` depends on / calls `target`.
+// ---------------------------------------------------------------------------
+
+/** Transport of a system-graph edge. `db` is reserved for a future transport. */
+export type SystemEdgeKind = "http" | "grpc" | "event" | "package" | "co_change" | "db";
+
+/** How confidently an edge was matched. Behavioral co-change edges are `inferred`. */
+export type SystemEdgeMatchType = "exact" | "candidate" | "manual" | "inferred";
+
+/** A service in the workspace (or a repo-root node when the repo is undivided). */
+export interface SystemNode {
+ /** Stable id: `"repo"` or `"repo::service/path"`. */
+ id: string;
+ /** Repo alias — the grouping attribute. */
+ repo: string;
+ /** Service boundary path, or null for a whole-repo node. */
+ service_path: string | null;
+ /** Display name (service directory basename, or repo alias). */
+ name: string;
+ kind: "service" | "frontend" | "worker" | "library" | "external";
+ provider_count: number;
+ consumer_count: number;
+ contract_types: string[];
+ /** Exposes provider contracts no consumer calls. */
+ is_orphan_provider: boolean;
+ /** Consumes contracts that never matched a provider. */
+ is_orphan_consumer: boolean;
+ /** Participates in no edges. */
+ is_isolated: boolean;
+}
+
+/** A typed, directed relationship between two services (`source` → `target`). */
+export interface SystemEdge {
+ id: string;
+ source: string;
+ target: string;
+ kind: SystemEdgeKind;
+ match_type: SystemEdgeMatchType;
+ confidence: number;
+ /** Number of underlying contracts / co-changes / deps this edge aggregates. */
+ weight: number;
+ /** True for contract/package edges, false for behavioral co-change edges. */
+ structural: boolean;
+ /** Back-pointers to the underlying evidence, for drill-down (bounded). */
+ contract_refs: string[];
+}
+
+export interface SystemGraph {
+ version: number;
+ generated_at: string;
+ nodes: SystemNode[];
+ edges: SystemEdge[];
+ diagnostics: ExtractionDiagnostics;
+}
+
+// ---------------------------------------------------------------------------
+// Extraction diagnostics — explains the cross-repo link count (providers /
+// consumers found, unmatched-by-reason, orphan providers, weak links).
+// Mirrors `repowise.core.workspace.diagnostics`.
+// ---------------------------------------------------------------------------
+
+/** Why a consumer contract never formed a cross-repo link. */
+export type UnmatchedReason = "no_provider" | "internal_only" | "unlinked";
+
+export interface RepoDiagnostics {
+ repo: string;
+ providers_by_type: Record<string, number>;
+ consumers_by_type: Record<string, number>;
+ provider_count: number;
+ consumer_count: number;
+}
+
+export interface UnmatchedConsumer {
+ repo: string;
+ file_path: string;
+ contract_id: string;
+ contract_type: string;
+ reason: UnmatchedReason;
+}
+
+export interface OrphanProvider {
+ repo: string;
+ file_path: string;
+ contract_id: string;
+ contract_type: string;
+}
+
+export interface ExtractionDiagnostics {
+ total_providers: number;
+ total_consumers: number;
+ total_links: number;
+ weak_link_count: number;
+ repo_breakdown: RepoDiagnostics[];
+ unmatched_consumers: UnmatchedConsumer[];
+ unmatched_by_reason: Record<string, number>;
+ orphan_providers: OrphanProvider[];
+}
diff --git a/tests/unit/cli/test_workspace_cmd.py b/tests/unit/cli/test_workspace_cmd.py
index cd99ffa82..55103a381 100644
--- a/tests/unit/cli/test_workspace_cmd.py
+++ b/tests/unit/cli/test_workspace_cmd.py
@@ -452,3 +452,73 @@ class TestWorkspaceHelp:
def test_workspace_set_default_help(self, runner):
result = runner.invoke(cli, ["workspace", "set-default", "--help"])
assert result.exit_code == 0
+
+
+# ---------------------------------------------------------------------------
+# workspace diagnostics
+# ---------------------------------------------------------------------------
+
+
+class TestWorkspaceDiagnostics:
+ def _setup(self, root: Path) -> None:
+ from repowise.core.workspace.contracts import Contract, ContractLink
+ from repowise.core.workspace.cross_repo import CrossRepoOverlay
+ from repowise.core.workspace.system_graph import build_system_graph, save_system_graph
+
+ (root / "backend").mkdir()
+ (root / "frontend").mkdir()
+ _write_workspace_config(
+ root,
+ repos=[
+ {"path": "backend", "alias": "backend"},
+ {"path": "frontend", "alias": "frontend"},
+ ],
+ default_repo="backend",
+ )
+ contracts = [
+ Contract(repo="backend", contract_id="http::GET::/users", contract_type="http",
+ role="provider", file_path="r.py", symbol_name="h", confidence=0.9),
+ Contract(repo="frontend", contract_id="http::GET::/users", contract_type="http",
+ role="consumer", file_path="c.ts", symbol_name="f", confidence=0.8),
+ Contract(repo="backend", contract_id="http::GET::/orphan", contract_type="http",
+ role="provider", file_path="r.py", symbol_name="o", confidence=0.9),
+ ]
+ links = [
+ ContractLink(contract_id="http::GET::/users", contract_type="http", match_type="exact",
+ confidence=0.72, provider_repo="backend", provider_file="r.py",
+ provider_symbol="h", provider_service=None, consumer_repo="frontend",
+ consumer_file="c.ts", consumer_symbol="f", consumer_service=None),
+ ]
+ graph = build_system_graph(contracts, links, CrossRepoOverlay(), {}, generated_at="t")
+ save_system_graph(graph, root)
+
+ def test_diagnostics_table(self, runner, tmp_path):
+ self._setup(tmp_path)
+ result = runner.invoke(cli, ["workspace", "diagnostics", str(tmp_path)])
+ assert result.exit_code == 0, result.output
+ assert "1 cross-repo link(s) matched" in result.output
+ assert "orphan provider" in result.output
+ assert "http::GET::/orphan" in result.output
+
+ def test_diagnostics_json(self, runner, tmp_path):
+ import json
+
+ self._setup(tmp_path)
+ result = runner.invoke(cli, ["workspace", "diagnostics", str(tmp_path), "--json"])
+ assert result.exit_code == 0, result.output
+ data = json.loads(result.output)
+ assert data["total_links"] == 1
+ assert data["total_providers"] == 2
+ assert len(data["orphan_providers"]) == 1
+
+ def test_diagnostics_missing_graph(self, runner, tmp_path):
+ (tmp_path / "backend").mkdir()
+ _write_workspace_config(tmp_path, repos=[{"path": "backend", "alias": "backend"}])
+ result = runner.invoke(cli, ["workspace", "diagnostics", str(tmp_path)])
+ assert result.exit_code != 0
+ assert "No system graph found" in result.output
+
+ def test_diagnostics_help(self, runner):
+ result = runner.invoke(cli, ["workspace", "diagnostics", "--help"])
+ assert result.exit_code == 0
+ assert "--json" in result.output
diff --git a/tests/unit/server/test_workspace_router.py b/tests/unit/server/test_workspace_router.py
index 8220dd1b4..059fe8a05 100644
--- a/tests/unit/server/test_workspace_router.py
+++ b/tests/unit/server/test_workspace_router.py
@@ -564,3 +564,99 @@ class TestQueryRepoStats:
stats = workspace._query_repo_stats(db_path)
assert stats["hotspot_count"] == 0
+
+
+# ---------------------------------------------------------------------------
+# GET /api/workspace/system-graph + /diagnostics
+# ---------------------------------------------------------------------------
+
+
+def _make_system_graph_enricher(tmp_path: Path) -> CrossRepoEnricher:
+ """Enricher backed by a real, core-built system graph artifact."""
+ from repowise.core.workspace.contracts import Contract, ContractLink
+ from repowise.core.workspace.cross_repo import CrossRepoOverlay, CrossRepoPackageDep
+ from repowise.core.workspace.system_graph import build_system_graph
+
+ contracts = [
+ Contract(repo="backend", contract_id="http::GET::/api/users", contract_type="http",
+ role="provider", file_path="routes.py", symbol_name="get_users", confidence=0.85),
+ Contract(repo="frontend", contract_id="http::GET::/api/users", contract_type="http",
+ role="consumer", file_path="client.ts", symbol_name="fetchUsers", confidence=0.75),
+ Contract(repo="backend", contract_id="http::GET::/orphan", contract_type="http",
+ role="provider", file_path="routes.py", symbol_name="orphan", confidence=0.85),
+ ]
+ links = [
+ ContractLink(contract_id="http::GET::/api/users", contract_type="http", match_type="exact",
+ confidence=0.75, provider_repo="backend", provider_file="routes.py",
+ provider_symbol="get_users", provider_service=None, consumer_repo="frontend",
+ consumer_file="client.ts", consumer_symbol="fetchUsers", consumer_service=None),
+ ]
+ overlay = CrossRepoOverlay(package_deps=[
+ CrossRepoPackageDep(source_repo="frontend", target_repo="backend",
+ source_manifest="package.json", kind="npm_local_path"),
+ ])
+ graph = build_system_graph(contracts, links, overlay, {}, generated_at="t")
+
+ _write_json(tmp_path / "system_graph.json", graph.to_dict())
+ return CrossRepoEnricher(
+ tmp_path / "cross_repo_edges.json",
+ system_graph_path=tmp_path / "system_graph.json",
+ )
+
+
+class TestGetSystemGraph:
+ @pytest.mark.asyncio
+ async def test_not_workspace_mode(self) -> None:
+ app = _make_workspace_app()
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://test") as c:
+ resp = await c.get("/api/workspace/system-graph")
+ assert resp.status_code == 404
+
+ @pytest.mark.asyncio
+ async def test_empty_when_no_graph(self) -> None:
+ app = _make_workspace_app(ws_config=_make_ws_config(), enricher=None)
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://test") as c:
+ resp = await c.get("/api/workspace/system-graph")
+ assert resp.status_code == 200
+ assert resp.json()["nodes"] == []
+
+ @pytest.mark.asyncio
+ async def test_returns_nodes_and_typed_edges(self, tmp_path: Path) -> None:
+ enricher = _make_system_graph_enricher(tmp_path)
+ app = _make_workspace_app(ws_config=_make_ws_config(), enricher=enricher)
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://test") as c:
+ resp = await c.get("/api/workspace/system-graph")
+ assert resp.status_code == 200
+ data = resp.json()
+ assert {n["id"] for n in data["nodes"]} == {"backend", "frontend"}
+ kinds = {(e["source"], e["target"], e["kind"]) for e in data["edges"]}
+ assert ("frontend", "backend", "http") in kinds # consumer -> provider
+ assert ("frontend", "backend", "package") in kinds # dependent -> dependency
+
+
+class TestGetDiagnostics:
+ @pytest.mark.asyncio
+ async def test_not_workspace_mode(self) -> None:
+ app = _make_workspace_app()
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://test") as c:
+ resp = await c.get("/api/workspace/diagnostics")
+ assert resp.status_code == 404
+
+ @pytest.mark.asyncio
+ async def test_reports_orphans_and_counts(self, tmp_path: Path) -> None:
+ enricher = _make_system_graph_enricher(tmp_path)
+ app = _make_workspace_app(ws_config=_make_ws_config(), enricher=enricher)
+ transport = ASGITransport(app=app)
+ async with AsyncClient(transport=transport, base_url="http://test") as c:
+ resp = await c.get("/api/workspace/diagnostics")
+ assert resp.status_code == 200
+ data = resp.json()
+ assert data["total_providers"] == 2
+ assert data["total_consumers"] == 1
+ assert data["total_links"] == 1
+ assert len(data["orphan_providers"]) == 1
+ assert data["orphan_providers"][0]["contract_id"] == "http::GET::/orphan"
diff --git a/tests/unit/workspace/test_diagnostics.py b/tests/unit/workspace/test_diagnostics.py
new file mode 100644
index 000000000..a1c9a5c81
--- /dev/null
+++ b/tests/unit/workspace/test_diagnostics.py
@@ -0,0 +1,150 @@
+"""Tests for extraction diagnostics — provider/consumer counts, unmatched reasons, orphans."""
+
+from __future__ import annotations
+
+from repowise.core.workspace.contracts import Contract, ContractLink
+from repowise.core.workspace.diagnostics import (
+ WEAK_LINK_CONFIDENCE_THRESHOLD,
+ UnmatchedReason,
+ build_diagnostics,
+)
+
+
+def _provider(
+ repo: str, cid: str, ctype: str = "http", file: str = "h.py", service=None
+) -> Contract:
+ return Contract(
+ repo=repo,
+ contract_id=cid,
+ contract_type=ctype,
+ role="provider",
+ file_path=file,
+ symbol_name="handler",
+ confidence=0.9,
+ service=service,
+ )
+
+
+def _consumer(
+ repo: str, cid: str, ctype: str = "http", file: str = "c.py", service=None
+) -> Contract:
+ return Contract(
+ repo=repo,
+ contract_id=cid,
+ contract_type=ctype,
+ role="consumer",
+ file_path=file,
+ symbol_name="call",
+ confidence=0.8,
+ service=service,
+ )
+
+
+def _link(
+ cid: str, p_repo: str, c_repo: str, confidence: float = 0.72, ctype: str = "http"
+) -> ContractLink:
+ return ContractLink(
+ contract_id=cid,
+ contract_type=ctype,
+ match_type="exact",
+ confidence=confidence,
+ provider_repo=p_repo,
+ provider_file="h.py",
+ provider_symbol="handler",
+ provider_service=None,
+ consumer_repo=c_repo,
+ consumer_file="c.py",
+ consumer_symbol="call",
+ consumer_service=None,
+ )
+
+
+def test_empty_workspace_is_all_zero():
+ diag = build_diagnostics([], [])
+ assert diag.total_providers == 0
+ assert diag.total_consumers == 0
+ assert diag.total_links == 0
+ assert diag.repo_breakdown == []
+ assert diag.unmatched_consumers == []
+ assert diag.orphan_providers == []
+
+
+def test_provider_consumer_counts_by_repo_and_type():
+ contracts = [
+ _provider("api", "http::GET::/users"),
+ _provider("api", "grpc::svc/M", ctype="grpc"),
+ _consumer("web", "http::GET::/users"),
+ ]
+ diag = build_diagnostics(contracts, [])
+ assert diag.total_providers == 2
+ assert diag.total_consumers == 1
+
+ by_repo = {r.repo: r for r in diag.repo_breakdown}
+ assert by_repo["api"].provider_count == 2
+ assert by_repo["api"].providers_by_type == {"grpc": 1, "http": 1}
+ assert by_repo["web"].consumer_count == 1
+ assert by_repo["web"].consumers_by_type == {"http": 1}
+
+
+def test_matched_consumer_is_not_unmatched():
+ contracts = [
+ _provider("api", "http::GET::/users"),
+ _consumer("web", "http::GET::/users"),
+ ]
+ links = [_link("http::GET::/users", "api", "web")]
+ diag = build_diagnostics(contracts, links)
+ assert diag.unmatched_consumers == []
+ assert diag.orphan_providers == []
+ assert diag.total_links == 1
+
+
+def test_unmatched_no_provider():
+ contracts = [_consumer("web", "http::GET::/missing")]
+ diag = build_diagnostics(contracts, [])
+ assert len(diag.unmatched_consumers) == 1
+ assert diag.unmatched_consumers[0].reason == UnmatchedReason.NO_PROVIDER
+ assert diag.unmatched_by_reason == {UnmatchedReason.NO_PROVIDER: 1}
+
+
+def test_unmatched_internal_only():
+ # Provider and consumer live in the same repo + service: intra-service call,
+ # intentionally not surfaced as a cross-repo link.
+ contracts = [
+ _provider("api", "http::GET::/users", service="services/x"),
+ _consumer("api", "http::GET::/users", service="services/x"),
+ ]
+ diag = build_diagnostics(contracts, [])
+ assert len(diag.unmatched_consumers) == 1
+ assert diag.unmatched_consumers[0].reason == UnmatchedReason.INTERNAL_ONLY
+
+
+def test_orphan_provider_detected():
+ contracts = [_provider("api", "http::GET::/unused")]
+ diag = build_diagnostics(contracts, [])
+ assert len(diag.orphan_providers) == 1
+ assert diag.orphan_providers[0].contract_id == "http::GET::/unused"
+
+
+def test_weak_link_counted_at_threshold():
+ contracts = [
+ _provider("api", "http::GET::/u"),
+ _consumer("web", "http::GET::/u"),
+ ]
+ weak = [_link("http::GET::/u", "api", "web", confidence=WEAK_LINK_CONFIDENCE_THRESHOLD)]
+ assert build_diagnostics(contracts, weak).weak_link_count == 1
+ strong = [_link("http::GET::/u", "api", "web", confidence=0.9)]
+ assert build_diagnostics(contracts, strong).weak_link_count == 0
+
+
+def test_round_trip_serialization():
+ contracts = [
+ _provider("api", "http::GET::/users"),
+ _consumer("web", "http::GET::/users"),
+ _consumer("web", "http::GET::/missing"),
+ ]
+ links = [_link("http::GET::/users", "api", "web")]
+ from repowise.core.workspace.diagnostics import ExtractionDiagnostics
+
+ diag = build_diagnostics(contracts, links)
+ restored = ExtractionDiagnostics.from_dict(diag.to_dict())
+ assert restored.to_dict() == diag.to_dict()
diff --git a/tests/unit/workspace/test_system_graph.py b/tests/unit/workspace/test_system_graph.py
new file mode 100644
index 000000000..9a82bfc38
--- /dev/null
+++ b/tests/unit/workspace/test_system_graph.py
@@ -0,0 +1,321 @@
+"""Tests for the service-granular system graph — node derivation, typed edges, persistence."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.workspace.contracts import Contract, ContractLink, ContractStore
+from repowise.core.workspace.cross_repo import (
+ CrossRepoCoChange,
+ CrossRepoOverlay,
+ CrossRepoPackageDep,
+)
+from repowise.core.workspace.extractors.service_boundary import ServiceBoundary
+from repowise.core.workspace.system_graph import (
+ SYSTEM_GRAPH_FILENAME,
+ SystemGraph,
+ build_system_graph,
+ edge_kind_for_contract_type,
+ load_system_graph,
+ save_system_graph,
+)
+
+
+def _provider(repo, cid, ctype="http", file="src/handler.py") -> Contract:
+ return Contract(
+ repo=repo,
+ contract_id=cid,
+ contract_type=ctype,
+ role="provider",
+ file_path=file,
+ symbol_name="handler",
+ confidence=0.9,
+ )
+
+
+def _consumer(repo, cid, ctype="http", file="src/client.py") -> Contract:
+ return Contract(
+ repo=repo,
+ contract_id=cid,
+ contract_type=ctype,
+ role="consumer",
+ file_path=file,
+ symbol_name="call",
+ confidence=0.8,
+ )
+
+
+def _link(
+ cid, p_repo, p_file, c_repo, c_file, ctype="http", match="exact", conf=0.72
+) -> ContractLink:
+ return ContractLink(
+ contract_id=cid,
+ contract_type=ctype,
+ match_type=match,
+ confidence=conf,
+ provider_repo=p_repo,
+ provider_file=p_file,
+ provider_symbol="handler",
+ provider_service=None,
+ consumer_repo=c_repo,
+ consumer_file=c_file,
+ consumer_symbol="call",
+ consumer_service=None,
+ )
+
+
+def _nodes_by_id(graph: SystemGraph):
+ return {n.id: n for n in graph.nodes}
+
+
+def _edges_by_key(graph: SystemGraph):
+ return {(e.source, e.target, e.kind): e for e in graph.edges}
+
+
+# ---------------------------------------------------------------------------
+# Node derivation (service granularity — D3)
+# ---------------------------------------------------------------------------
+
+
+def test_empty_graph():
+ graph = build_system_graph([], [], CrossRepoOverlay(), {})
+ assert graph.nodes == []
+ assert graph.edges == []
+ assert graph.diagnostics.total_providers == 0
+
+
+def test_repo_without_boundary_collapses_to_one_node():
+ contracts = [_provider("api", "http::GET::/users", file="app/routes.py")]
+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), {"api": []})
+ nodes = _nodes_by_id(graph)
+ assert set(nodes) == {"api"}
+ assert nodes["api"].service_path is None
+ assert nodes["api"].provider_count == 1
+ assert nodes["api"].name == "api"
+
+
+def test_monorepo_yields_multiple_service_nodes():
+ boundaries = {
+ "mono": [
+ ServiceBoundary(service_path="services/auth", service_name="auth"),
+ ServiceBoundary(service_path="services/billing", service_name="billing"),
+ ]
+ }
+ contracts = [
+ _provider("mono", "http::GET::/login", file="services/auth/handler.py"),
+ _provider("mono", "http::POST::/charge", file="services/billing/handler.py"),
+ ]
+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), boundaries)
+ nodes = _nodes_by_id(graph)
+ assert set(nodes) == {"mono::services/auth", "mono::services/billing"}
+ assert nodes["mono::services/auth"].name == "auth"
+ assert nodes["mono::services/auth"].service_path == "services/auth"
+ assert nodes["mono::services/billing"].name == "billing"
+
+
+# ---------------------------------------------------------------------------
+# Edge kind + direction + match_type
+# ---------------------------------------------------------------------------
+
+
+def test_contract_type_to_edge_kind():
+ assert edge_kind_for_contract_type("http") == "http"
+ assert edge_kind_for_contract_type("grpc") == "grpc"
+ assert edge_kind_for_contract_type("topic") == "event"
+ assert edge_kind_for_contract_type("unknown") == "unknown"
+
+
+def test_contract_edge_direction_is_consumer_to_provider():
+ contracts = [
+ _provider("api", "http::GET::/users", file="api/h.py"),
+ _consumer("web", "http::GET::/users", file="web/c.py"),
+ ]
+ links = [_link("http::GET::/users", "api", "api/h.py", "web", "web/c.py")]
+ graph = build_system_graph(contracts, links, CrossRepoOverlay(), {})
+ assert len(graph.edges) == 1
+ edge = graph.edges[0]
+ assert edge.source == "web" # consumer depends on / calls...
+ assert edge.target == "api" # ...the provider
+ assert edge.kind == "http"
+ assert edge.match_type == "exact"
+ assert edge.structural is True
+ assert edge.contract_refs == ["http::GET::/users"]
+
+
+def test_topic_contract_becomes_event_edge():
+ contracts = [
+ _provider("a", "topic::orders", ctype="topic", file="a/pub.py"),
+ _consumer("b", "topic::orders", ctype="topic", file="b/sub.py"),
+ ]
+ links = [_link("topic::orders", "a", "a/pub.py", "b", "b/sub.py", ctype="topic")]
+ graph = build_system_graph(contracts, links, CrossRepoOverlay(), {})
+ assert graph.edges[0].kind == "event"
+
+
+def test_parallel_links_aggregate_into_one_weighted_edge():
+ contracts = [
+ _provider("api", "http::GET::/a", file="api/h.py"),
+ _provider("api", "http::GET::/b", file="api/h.py"),
+ _consumer("web", "http::GET::/a", file="web/c.py"),
+ _consumer("web", "http::GET::/b", file="web/c.py"),
+ ]
+ links = [
+ _link("http::GET::/a", "api", "api/h.py", "web", "web/c.py", match="exact", conf=0.9),
+ _link("http::GET::/b", "api", "api/h.py", "web", "web/c.py", match="candidate", conf=0.5),
+ ]
+ graph = build_system_graph(contracts, links, CrossRepoOverlay(), {})
+ edges = _edges_by_key(graph)
+ edge = edges[("web", "api", "http")]
+ assert edge.weight == 2
+ assert edge.confidence == 0.9 # max of contributors
+ assert edge.match_type == "exact" # most authoritative wins
+ assert set(edge.contract_refs) == {"http::GET::/a", "http::GET::/b"}
+
+
+# ---------------------------------------------------------------------------
+# Package + co-change edges
+# ---------------------------------------------------------------------------
+
+
+def test_package_dep_edge_points_dependent_to_dependency():
+ overlay = CrossRepoOverlay(
+ package_deps=[
+ CrossRepoPackageDep(
+ source_repo="web",
+ target_repo="shared",
+ source_manifest="package.json",
+ kind="npm_local_path",
+ )
+ ]
+ )
+ graph = build_system_graph([], [], overlay, {})
+ edges = _edges_by_key(graph)
+ edge = edges[("web", "shared", "package")]
+ assert edge.structural is True
+ assert edge.match_type == "exact"
+ assert edge.confidence == 1.0
+
+
+def test_cochange_edge_is_behavioral_and_undirected():
+ overlay = CrossRepoOverlay(
+ co_changes=[
+ CrossRepoCoChange(
+ source_repo="z",
+ source_file="z/a.py",
+ target_repo="a",
+ target_file="a/b.py",
+ strength=0.6,
+ frequency=4,
+ last_date="2026-06-01",
+ )
+ ]
+ )
+ graph = build_system_graph([], [], overlay, {})
+ assert len(graph.edges) == 1
+ edge = graph.edges[0]
+ assert edge.kind == "co_change"
+ assert edge.structural is False
+ # Direction canonicalized to (min, max) of node ids.
+ assert edge.source == "a"
+ assert edge.target == "z"
+
+
+# ---------------------------------------------------------------------------
+# Orphan + isolation flags
+# ---------------------------------------------------------------------------
+
+
+def test_orphan_provider_and_isolation_flags():
+ contracts = [_provider("api", "http::GET::/unused", file="api/h.py")]
+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), {})
+ node = _nodes_by_id(graph)["api"]
+ assert node.is_orphan_provider is True
+ assert node.is_isolated is True
+
+
+def test_connected_provider_is_not_orphan():
+ contracts = [
+ _provider("api", "http::GET::/users", file="api/h.py"),
+ _consumer("web", "http::GET::/users", file="web/c.py"),
+ ]
+ links = [_link("http::GET::/users", "api", "api/h.py", "web", "web/c.py")]
+ graph = build_system_graph(contracts, links, CrossRepoOverlay(), {})
+ nodes = _nodes_by_id(graph)
+ assert nodes["api"].is_orphan_provider is False
+ assert nodes["api"].is_isolated is False
+ assert nodes["web"].is_orphan_consumer is False
+
+
+# ---------------------------------------------------------------------------
+# Schema shape + persistence (snapshot guard)
+# ---------------------------------------------------------------------------
+
+
+def test_system_graph_json_shape_is_locked():
+ contracts = [
+ _provider("api", "http::GET::/users", file="api/h.py"),
+ _consumer("web", "http::GET::/users", file="web/c.py"),
+ ]
+ links = [_link("http::GET::/users", "api", "api/h.py", "web", "web/c.py")]
+ graph = build_system_graph(
+ contracts, links, CrossRepoOverlay(), {}, version=1, generated_at="t"
+ )
+ data = graph.to_dict()
+
+ assert set(data) == {"version", "generated_at", "nodes", "edges", "diagnostics"}
+ assert set(data["nodes"][0]) == {
+ "id",
+ "repo",
+ "service_path",
+ "name",
+ "kind",
+ "provider_count",
+ "consumer_count",
+ "contract_types",
+ "is_orphan_provider",
+ "is_orphan_consumer",
+ "is_isolated",
+ }
+ assert set(data["edges"][0]) == {
+ "id",
+ "source",
+ "target",
+ "kind",
+ "match_type",
+ "confidence",
+ "weight",
+ "structural",
+ "contract_refs",
+ }
+ assert set(data["diagnostics"]) == {
+ "total_providers",
+ "total_consumers",
+ "total_links",
+ "weak_link_count",
+ "repo_breakdown",
+ "unmatched_consumers",
+ "unmatched_by_reason",
+ "orphan_providers",
+ }
+
+
+def test_round_trip_serialization():
+ contracts = [_provider("api", "http::GET::/users", file="api/h.py")]
+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), {}, generated_at="t")
+ restored = SystemGraph.from_dict(graph.to_dict())
+ assert restored.to_dict() == graph.to_dict()
+
+
+def test_save_and_load(tmp_path: Path):
+ contracts = [_provider("api", "http::GET::/users", file="api/h.py")]
+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), {}, generated_at="t")
+ out = save_system_graph(graph, tmp_path)
+ assert out.name == SYSTEM_GRAPH_FILENAME
+
+ loaded = load_system_graph(tmp_path)
+ assert loaded is not None
+ assert loaded.to_dict() == graph.to_dict()
+
+
+def test_load_missing_returns_none(tmp_path: Path):
+ assert load_system_graph(tmp_path) is None