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
feat(workspace): service-granular system graph and extraction diagnostics (#511)
Raghav Chamadiya6482ca12e611
diff --git a/docs/CLI_REFERENCE.md b/docs/CLI_REFERENCE.mdindex 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.mdindex 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 UIStart the web server:@@ -240,6 +291,7 @@ my-workspace/.repowise-workspace/ # Shared cross-repo datacross_repo_edges.json # Co-change pairs and package depscontracts.json # Extracted API contracts and links+ system_graph.json # Service-granular system graph + diagnostics.claude/CLAUDE.md # Workspace-level CLAUDE.md for AI editorsbackend/diff --git a/packages/cli/src/repowise/cli/commands/workspace_cmd.py b/packages/cli/src/repowise/cli/commands/workspace_cmd.pyindex 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 repoif 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 nameif 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 = Falsedocs_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__.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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 graphdiff --git a/packages/core/src/repowise/core/workspace/update.py b/packages/core/src/repowise/core/workspace/update.pyindex 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.pyindex 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_FILENAMEfrom repowise.server.mcp_server._enrichment import CrossRepoEnrichercross_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 = enricherlogger.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.pyindex 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_pathself._contracts_path = contracts_path+ self._system_graph_path = system_graph_pathself._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_repoself._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)returnself._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 = Noneself._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.pyindex 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_DIRfrom repowise.core.workspace.contracts import CONTRACTS_FILENAME+ from repowise.core.workspace.system_graph import SYSTEM_GRAPH_FILENAMEfrom repowise.server.mcp_server._enrichment import CrossRepoEnrichercross_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.pyindex 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 0except 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_changesif 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__.pyindex 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.pyindex 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.tsindex 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.pyindex 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.outputdiff --git a/tests/unit/server/test_workspace_router.py b/tests/unit/server/test_workspace_router.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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