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): group services into systems (tag, name family, linkage) (#4600)
Raghav Chamadiya99260ec70e4f
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.mdindex fa1571c74..9f42173e0 100644--- a/docs/scale/WORKSPACES.md+++ b/docs/scale/WORKSPACES.md@@ -317,11 +317,14 @@ The contracts, package dependencies, and co-changes above are each a flat list.- a `kind`, `http`, `grpc`, `event`, `package`, `co_change`, or `db`;- a `match_type`, `exact`, `candidate`, `manual`, or `inferred`;- a `strategy`, the [matching rule](../reference/WORKSPACE_CONTRACTS.md#how-a-contract-and-a-link-were-made) of the link that gave the edge its confidence (`manifest` for a package dependency, none for co-change);+- a `family`, `runtime` (http, grpc, socket, event), `data` (db), `build` (package) or `history` (co-change); a kind outside that table is `history`, so it is never walked as a dependency;- 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".+**Large estates are grouped into systems.** Past 40 services, each service joins at most one group, recorded as `group` on the node and summarised in a top-level `groups` list (`id`, `label`, `source`, `member_count`). Groups come from, in order: an explicit `group:<name>` repo tag (`tags: [group:checkout]`; other tags such as `backend` serve conformance rules and never form a group), a shared alias prefix across 2+ repos and under half the estate (`ordering.api`, `ordering.worker`), then seeded community detection over runtime and data edges (a linked group's id names its smallest member, its label the member most services call). A group needs 2+ services, and groups are written only when at least two form; smaller estates carry no `group` or `groups` keys.+Fetch it over REST with `GET /api/workspace/system-graph`, or explore it visually in the [Live System Map](#live-system-map).## Extraction Diagnosticsdiff --git a/packages/core/src/repowise/core/workspace/config.py b/packages/core/src/repowise/core/workspace/config.pyindex a486a7569..56da36db6 100644--- a/packages/core/src/repowise/core/workspace/config.py+++ b/packages/core/src/repowise/core/workspace/config.py@@ -17,6 +17,8 @@ from typing import Anyimport yaml+from repowise.core.workspace.grouping import declared_group+_log = logging.getLogger("repowise.workspace.config")# ---------------------------------------------------------------------------@@ -52,6 +54,8 @@ class RepoEntry:# Free-form labels (e.g. "frontend", "tier:edge", "legacy") that group repos# for architecture conformance rules. A rule like ``frontend !-> db`` matches# by tag via ``tag:<name>``; every service node in this repo inherits these.+ # On a large estate a ``group:<name>`` tag also names the system the repo's+ # services are grouped under (see ``grouping.py``); other tags never do.tags: list[str] = field(default_factory=list)def to_dict(self) -> dict[str, Any]:@@ -315,9 +319,14 @@ class WorkspaceConfig:"""Hash of the settings the cross-repo analysis reads.Compared with the one the last analysis run stamped, so editing the- ``contracts:`` or ``conformance:`` block re-runs it with no repo changed.+ ``contracts:`` or ``conformance:`` block, or a repo's declared service+ group (its ``group:<name>`` tag), re-runs it with no repo changed. Other+ tags stay out, so editing a conformance tag never forces a re-analysis."""- payload = [self.contracts.to_dict(), self.conformance.to_dict()]+ payload: list[Any] = [self.contracts.to_dict(), self.conformance.to_dict()]+ groups = {r.alias: name for r in self.repos if (name := declared_group(r.tags))}+ if groups: # only when declared, so every other workspace keeps its stamp+ payload.append(groups)return hashlib.sha256(json.dumps(payload, sort_keys=True).encode()).hexdigest()[:16]def save(self, workspace_root: Path) -> Path:diff --git a/packages/core/src/repowise/core/workspace/graph_evidence.py b/packages/core/src/repowise/core/workspace/graph_evidence.pyindex 738744d45..3f4c528d8 100644--- a/packages/core/src/repowise/core/workspace/graph_evidence.py+++ b/packages/core/src/repowise/core/workspace/graph_evidence.py@@ -29,10 +29,6 @@ EVIDENCE_MEASURED = "measured"EVIDENCE_PARTIAL = "partial"EVIDENCE_INSUFFICIENT = "insufficient"-#: Edge kinds that record a build-time reference (a manifest dependency, a-#: project reference, a published-package import), not a runtime call.-BUILD_EDGE_KINDS: frozenset[str] = frozenset({"package"})-#: Cap on the names a reason lists; its count is always the true one._MAX_NAMED = 8@@ -203,7 +199,7 @@ def _facts(graph: SystemGraph) -> _Facts:for edge in graph.edges:if not edge.structural or edge.source not in known or edge.target not in known:continue- if edge.kind in BUILD_EDGE_KINDS:+ if edge.family == "build": # a manifest or package reference, not a callbuild += 1else:runtime += 1diff --git a/packages/core/src/repowise/core/workspace/grouping.py b/packages/core/src/repowise/core/workspace/grouping.pynew file mode 100644index 000000000..2368ec209--- /dev/null+++ b/packages/core/src/repowise/core/workspace/grouping.py@@ -0,0 +1,281 @@+"""Service groups: fold a large estate's services into a few named systems.++A map of 300 services is a wall of cards. Grouping gives it a first level to+read: each service joins at most one group, found by three sources in priority+order, each claiming only what the earlier ones left:++1. **tag**: the repo declares a ``group:<name>`` tag in+ ``.repowise-workspace.yaml``. Other tags (``backend``, ``team:x``) serve+ conformance rules and never make a group.+2. **name**: a shared leading name of repo aliases (``ordering.api``,+ ``ordering.worker`` -> ``ordering``), kept only when it spans 2+ repos and+ under half the estate's repos. A prefix that covers half the estate is an+ organisation prefix, not a system, so the family is split on its next name+ token instead (``acme-billing-*`` inside ``acme-*``), up to+ :data:`MAX_NAME_DEPTH` tokens.+3. **linked**: community detection over runtime and data edges among the+ services still ungrouped, labelled by the member most services call. Its+ id comes from the smallest member id, so a new caller can relabel a linked+ group but never renames it.++A group is kept only with 2+ members; a lone service falls through to the next+source and may end ungrouped. Groups are emitted only when they reduce+something: more than :data:`MIN_SERVICES_TO_GROUP` services and at least two+groups. Below that every service is drawn on its own and no node carries a+group.++Pure and deterministic: inputs are walked in sorted order and the community+detection is seeded, so the same graph always yields the same groups. It reads+only node and edge attributes, so a caller holding a stored ``system_graph.json``+can run it through :meth:`SystemGraph.from_dict`.+"""++from __future__ import annotations++import logging+import re+from collections.abc import Callable, Iterable, Mapping+from dataclasses import dataclass+from typing import TYPE_CHECKING, Any++if TYPE_CHECKING:+ from repowise.core.workspace.system_graph import SystemEdge, SystemNode++_log = logging.getLogger("repowise.workspace.grouping")++#: Groups appear only above this many services; a smaller map reads fine flat.+#: This gate and :data:`MIN_GROUPS` live only here: a view treats a non-empty+#: ``groups`` list as the answer and never re-derives it.+MIN_SERVICES_TO_GROUP = 40++#: ...and only when at least this many groups (each 2+ members) form.+MIN_GROUPS = 2++#: A name family must stay under this share of the estate's repos.+MAX_NAME_FAMILY_SHARE = 0.5++#: Deepest alias prefix a name family may use (``a``, ``a-b``, ``a-b-c``).+MAX_NAME_DEPTH = 3++#: Edge families (``SystemEdge.family``) the linkage source clusters on: what+#: services call or share at run time. Build edges fan into library hubs and+#: would pull every service toward the shared libraries; history (co-change)+#: is correlation, not a dependency.+LINKAGE_FAMILIES: frozenset[str] = frozenset({"runtime", "data"})++#: Linkage is skipped (those services stay ungrouped) past this many linked+#: service pairs. Louvain is near-linear in edges; at this size it runs well+#: under a second. Ceiling: an estate past it needs a declared ``group:`` tag+#: or a faster partitioner.+MAX_LINKAGE_PAIRS = 50_000++#: Fixed seed for the community detection, the same one file communities use.+LINKAGE_SEED = 42++_GROUP_TAG_PREFIX = "group:"++#: A group a source found: ``(group id, label, members)``.+_Found = tuple[str, str, list["SystemNode"]]+_TOKEN = re.compile(r"[A-Za-z0-9]+")+++@dataclass(frozen=True)+class ServiceGroup:+ """One group of services: what the map draws as a single card."""++ #: ``tag:<name>``, ``name:<prefix>`` or ``linked:<smallest member id>``.+ id: str+ label: str+ source: str # tag | name | linked+ member_count: int++ def to_dict(self) -> dict[str, Any]:+ return {+ "id": self.id,+ "label": self.label,+ "source": self.source,+ "member_count": self.member_count,+ }++ @classmethod+ def from_dict(cls, data: dict[str, Any]) -> ServiceGroup:+ return cls(+ id=data["id"],+ label=data.get("label", data["id"]),+ source=data.get("source", ""),+ member_count=data.get("member_count", 0),+ )+++# ---------------------------------------------------------------------------+# Sources+# ---------------------------------------------------------------------------+++def declared_group(tags: Iterable[str]) -> str | None:+ """The repo's declared service group: its first non-empty ``group:<name>`` tag.++ The prefix matches in any case; the name keeps its own, as conformance's+ ``tag:<name>`` matcher does. The one reader of the ``group:`` convention.+ """+ for tag in (t.strip() for t in tags if t):+ name = tag[len(_GROUP_TAG_PREFIX) :].strip()+ if tag.lower().startswith(_GROUP_TAG_PREFIX) and name:+ return name+ return None+++def _by_tag(nodes: list[SystemNode], repo_tags: Mapping[str, Iterable[str]]) -> list[_Found]:+ """Declared groups of 2+ services."""+ groups: dict[str, list[SystemNode]] = {}+ for node in nodes:+ name = declared_group(repo_tags.get(node.repo, ()))+ if name is not None:+ groups.setdefault(name, []).append(node)+ return [(f"tag:{name}", name, m) for name, m in sorted(groups.items()) if len(m) >= 2]+++def _alias_prefix(alias: str, depth: int) -> tuple[str, str] | None:+ """``(key, label)`` for the first *depth* name tokens of *alias*.++ None when the alias has fewer tokens. An alias of exactly *depth* tokens+ joins the family its whole name starts (``ordering`` with ``ordering.api``).+ """+ tokens = list(_TOKEN.finditer(alias))+ if len(tokens) < depth:+ return None+ key = ".".join(t.group().lower() for t in tokens[:depth])+ return key, alias[tokens[0].start() : tokens[depth - 1].end()]+++def _families_at(+ pool: list[SystemNode], depth: int+) -> dict[str, tuple[str, list[SystemNode]]]:+ """Split *pool* by the first *depth* alias tokens: ``{key: (label, members)}``."""+ families: dict[str, tuple[str, list[SystemNode]]] = {}+ for node in pool:+ prefix = _alias_prefix(node.repo, depth)+ if prefix is not None:+ families.setdefault(prefix[0], (prefix[1], []))[1].append(node)+ return families+++def _by_name(nodes: list[SystemNode], estate_repos: int) -> list[_Found]:+ """Name families of 2+ repos and under half the estate, widest prefix first."""+ max_repos = estate_repos * MAX_NAME_FAMILY_SHARE+ found: dict[str, tuple[str, list[SystemNode]]] = {}+ pending: list[list[SystemNode]] = [nodes]+ for depth in range(1, MAX_NAME_DEPTH + 1):+ families = [f for pool in pending for f in _families_at(pool, depth).items()]+ too_wide: list[list[SystemNode]] = []+ for key, (label, members) in families:+ repos = len({m.repo for m in members})+ if 2 <= repos < max_repos:+ found[key] = (label, members)+ elif repos >= 2:+ too_wide.append(members)+ pending = too_wide+ return [(f"name:{key}", label, m) for key, (label, m) in sorted(found.items())]+++def _linkage_pairs(ids: set[str], edges: list[SystemEdge]) -> dict[tuple[str, str], int]:+ """Summed edge weight per unordered pair of *ids* over :data:`LINKAGE_FAMILIES`."""+ pair_weight: dict[tuple[str, str], int] = {}+ for edge in edges:+ if edge.family not in LINKAGE_FAMILIES or edge.source == edge.target:+ continue+ if edge.source in ids and edge.target in ids:+ pair = (min(edge.source, edge.target), max(edge.source, edge.target))+ pair_weight[pair] = pair_weight.get(pair, 0) + max(edge.weight, 1)+ return pair_weight+++def _communities(pair_weight: dict[tuple[str, str], int]) -> list[set[str]]:+ """Seeded Louvain over the weighted pairs.++ Louvain because it needs no target group count, is near-linear, ships with+ networkx (a core dependency, unlike Leiden's graspologic, which would make+ the result depend on what is installed), and is deterministic under a fixed+ seed and a fixed insertion order. A networkx upgrade may still move a+ borderline service between linked groups; tag and name groups never move.+ """+ import networkx as nx # deferred: only estates past the size gate pay the import++ graph = nx.Graph()+ graph.add_nodes_from(sorted({n for pair in pair_weight for n in pair}))+ graph.add_weighted_edges_from((a, b, w) for (a, b), w in sorted(pair_weight.items()))+ return nx.community.louvain_communities(graph, weight="weight", seed=LINKAGE_SEED)+++def _by_linkage(nodes: list[SystemNode], edges: list[SystemEdge]) -> list[_Found]:+ """Linked communities of 2+ services.++ Each is labelled by its most-called member, and its id names its smallest+ member id: the label may move as callers change, the id only when the+ smallest member leaves the community.+ """+ by_id = {n.id: n for n in nodes}+ pair_weight = _linkage_pairs(set(by_id), edges)+ if len(pair_weight) > MAX_LINKAGE_PAIRS:+ _log.info(+ "Skipping linkage grouping: %d linked service pairs exceeds the %d cap",+ len(pair_weight),+ MAX_LINKAGE_PAIRS,+ )+ return []+ communities = [c for c in _communities(pair_weight) if len(c) >= 2] if pair_weight else []+ fan_in = _fan_in(edges) if communities else {}+ found: list[_Found] = []+ for community in communities:+ members = [by_id[nid] for nid in sorted(community)]+ anchor = min(members, key=lambda m: (-fan_in.get(m.id, 0), m.name, m.id))+ found.append((f"linked:{members[0].id}", anchor.name, members))+ return found+++def _fan_in(edges: list[SystemEdge]) -> dict[str, int]:+ """How many distinct services call each service over :data:`LINKAGE_FAMILIES`."""+ callers: dict[str, set[str]] = {}+ for edge in edges:+ if edge.family in LINKAGE_FAMILIES and edge.source != edge.target:+ callers.setdefault(edge.target, set()).add(edge.source)+ return {nid: len(sources) for nid, sources in callers.items()}+++# ---------------------------------------------------------------------------+# Entry point+# ---------------------------------------------------------------------------+++def group_services(+ nodes: list[SystemNode],+ edges: list[SystemEdge],+ repo_tags: Mapping[str, Iterable[str]] | None = None,+) -> tuple[dict[str, str], list[ServiceGroup]]:+ """Assign services to groups: ``({node_id: group_id}, groups)``.++ Both are empty when the estate is at or under+ :data:`MIN_SERVICES_TO_GROUP` services or fewer than :data:`MIN_GROUPS`+ groups form. *repo_tags* maps a repo alias to its declared tags.+ """+ if len(nodes) <= MIN_SERVICES_TO_GROUP:+ return {}, []++ remaining = sorted(nodes, key=lambda n: n.id)+ estate_repos = len({n.repo for n in remaining})+ sources: tuple[tuple[str, Callable[[list[SystemNode]], list[_Found]]], ...] = (+ ("tag", lambda pool: _by_tag(pool, repo_tags or {})),+ ("name", lambda pool: _by_name(pool, estate_repos)),+ ("linked", lambda pool: _by_linkage(pool, edges)),+ )+ groups: list[ServiceGroup] = []+ assignment: dict[str, str] = {}+ for source, find in sources:+ for group_id, label, members in find(remaining):+ groups.append(ServiceGroup(group_id, label, source, len(members)))+ assignment.update((m.id, group_id) for m in members)+ remaining = [n for n in remaining if n.id not in assignment]++ if len(groups) < MIN_GROUPS:+ return {}, []+ return assignment, sorted(groups, key=lambda g: (-g.member_count, g.id))diff --git a/packages/core/src/repowise/core/workspace/system_graph.py b/packages/core/src/repowise/core/workspace/system_graph.pyindex 0da1f1158..d5c78ed45 100644--- a/packages/core/src/repowise/core/workspace/system_graph.py+++ b/packages/core/src/repowise/core/workspace/system_graph.py@@ -53,6 +53,7 @@ from repowise.core.workspace.extractors.service_boundary import (assign_service,detect_service_boundaries,)+from repowise.core.workspace.grouping import ServiceGroup, group_servicesfrom repowise.core.workspace.origins import LinkStrategy, legacy_strategyif TYPE_CHECKING:@@ -79,10 +80,27 @@ _CONTRACT_TYPE_TO_EDGE_KIND: dict[str, str] = {"code": "package",}-#: All edge kinds the graph can carry. ``db`` carries the shared-table-#: (``data``) contracts; the taxonomy is fixed so views render consistently.+#: Every edge kind the graph can carry, mapped to its family: ``runtime`` (a+#: call or message at run time), ``data`` (a shared store; ``db`` carries the+#: ``data`` contracts), ``build`` (a manifest or package reference) or+#: ``history`` (correlated change). The one owner of kind-to-family: views read+#: the ``family`` each edge carries, and grouping clusters on it.+EDGE_KIND_FAMILY: dict[str, str] = {+ "http": "runtime",+ "grpc": "runtime",+ "socket": "runtime",+ "event": "runtime",+ "db": "data",+ "package": "build",+ "co_change": "history",+}++#: All edge kinds the graph can carry; the taxonomy is fixed so views render consistently.EDGE_KINDS: tuple[str, ...] = ("http", "grpc", "socket", "event", "package", "co_change", "db")+#: Families in display order.+EDGE_FAMILIES: tuple[str, ...] = ("runtime", "data", "build", "history")+#: ``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] = {@@ -100,7 +118,9 @@ 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", "socket", "event", "package", "db"})+_STRUCTURAL_KINDS: frozenset[str] = frozenset(+ kind for kind, family in EDGE_KIND_FAMILY.items() if family != "history"+)#: Structural kinds whose dependency is asynchronous: the subscriber depends on#: the message shape, not on the publisher answering. Still a dependency (a@@ -109,6 +129,16 @@ _STRUCTURAL_KINDS: frozenset[str] = frozenset({"http", "grpc", "socket", "event"ASYNC_EDGE_KINDS: frozenset[str] = frozenset({"event"})+def edge_family(kind: str) -> str:+ """The family of an edge *kind*.++ A kind missing from :data:`EDGE_KIND_FAMILY` is ``history``: the builder+ already treats a kind outside :data:`_STRUCTURAL_KINDS` as non-structural+ (undirected, never walked), so it is never drawn or grouped as a dependency.+ """+ return EDGE_KIND_FAMILY.get(kind, "history")++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)@@ -134,9 +164,12 @@ class SystemNode:is_orphan_provider: bool = False # exposes providers nobody consumesis_orphan_consumer: bool = False # consumes contracts that never matchedis_isolated: bool = False # participates in no edges+ #: Id of the :class:`.grouping.ServiceGroup` this service belongs to; None+ #: when ungrouped, which every node is on an estate too small to group.+ group: str | None = Nonedef to_dict(self) -> dict[str, Any]:- return {+ data: dict[str, Any] = {"id": self.id,"repo": self.repo,"service_path": self.service_path,@@ -149,6 +182,9 @@ class SystemNode:"is_orphan_consumer": self.is_orphan_consumer,"is_isolated": self.is_isolated,}+ if self.group is not None:+ data["group"] = self.group+ return data@classmethoddef from_dict(cls, data: dict[str, Any]) -> SystemNode:@@ -164,6 +200,7 @@ class SystemNode: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),+ group=data.get("group"),)@@ -184,12 +221,18 @@ class SystemEdge:#: confidence. None on a co-change edge, which no link made.strategy: str | None = None+ @property+ def family(self) -> str:+ """``runtime`` | ``data`` | ``build`` | ``history``; see :func:`edge_family`."""+ return edge_family(self.kind)+def to_dict(self) -> dict[str, Any]:return {"id": self.id,"source": self.source,"target": self.target,"kind": self.kind,+ "family": self.family,"match_type": self.match_type,"confidence": self.confidence,"weight": self.weight,@@ -230,9 +273,11 @@ class SystemGraph:edges: list[SystemEdge] = field(default_factory=list)diagnostics: ExtractionDiagnostics = field(default_factory=ExtractionDiagnostics)repo_provenance: dict[str, dict[str, str]] = field(default_factory=dict)+ #: Service groups (see :mod:`.grouping`); empty on an estate too small to group.+ groups: list[ServiceGroup] = field(default_factory=list)def to_dict(self) -> dict[str, Any]:- return {+ data: dict[str, Any] = {"version": self.version,"generated_at": self.generated_at,"repo_provenance": self.repo_provenance,@@ -240,6 +285,9 @@ class SystemGraph:"edges": [e.to_dict() for e in self.edges],"diagnostics": self.diagnostics.to_dict(),}+ if self.groups:+ data["groups"] = [g.to_dict() for g in self.groups]+ return data@classmethoddef from_dict(cls, data: dict[str, Any]) -> SystemGraph:@@ -250,6 +298,7 @@ class SystemGraph: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", {})),+ groups=[ServiceGroup.from_dict(g) for g in data.get("groups", [])],)def adjacency(@@ -463,6 +512,7 @@ def build_system_graph(generated_at: str = "",repo_provenance: dict[str, dict[str, str]] | None = None,service_links: list[ContractLink] | None = None,+ repo_tags: dict[str, list[str]] | None = None,) -> SystemGraph:"""Assemble the service-granular system graph (pure, no I/O).@@ -470,7 +520,8 @@ def build_system_graph(contract links (consumer→provider), service-level links (a consumer to therepo its host names, no route known; :attr:`.origins.LinkStrategy.HOST_ONLY`),package dependencies (dependent→dependency), and cross-repo co-changes- (undirected, behavioral).+ (undirected, behavioral). Services are then grouped (:mod:`.grouping`),+ reading declared groups from *repo_tags* (repo alias to its tags)."""if diagnostics is None:diagnostics = build_diagnostics(contracts, links)@@ -528,6 +579,9 @@ def build_system_graph()nodes, edges = builder.finalize(diagnostics)+ assignment, groups = group_services(nodes, edges, repo_tags)+ for node in nodes:+ node.group = assignment.get(node.id)return SystemGraph(version=version,generated_at=generated_at,@@ -535,6 +589,7 @@ def build_system_graph(nodes=nodes,edges=edges,diagnostics=diagnostics,+ groups=groups,)@@ -614,6 +669,7 @@ async def run_system_graph_build(generated_at=datetime.now(UTC).isoformat(),repo_provenance=store.repo_provenance,service_links=store.service_links,+ repo_tags={entry.alias: entry.tags for entry in ws_config.repos},)out_path = save_system_graph(graph, workspace_root)diff --git a/packages/server/src/repowise/server/schemas/workspace.py b/packages/server/src/repowise/server/schemas/workspace.pyindex ec763a240..b6c9d472e 100644--- a/packages/server/src/repowise/server/schemas/workspace.py+++ b/packages/server/src/repowise/server/schemas/workspace.py@@ -4,7 +4,7 @@ from __future__ import annotationsfrom typing import Any, Literal-from pydantic import BaseModel, ConfigDict, Field+from pydantic import BaseModel, ConfigDict, Field, model_validatorclass WorkspaceRepoRemovedResponse(BaseModel):@@ -325,6 +325,15 @@ class WorkspaceSystemNode(BaseModel):is_orphan_provider: bool = Falseis_orphan_consumer: bool = Falseis_isolated: bool = False+ #: Id of the service group this node belongs to; None when ungrouped.+ group: str | None = None+++class WorkspaceServiceGroup(BaseModel):+ id: str+ label: str+ source: str # tag | name | linked+ member_count: int = 0class WorkspaceSystemEdge(BaseModel):@@ -340,6 +349,17 @@ class WorkspaceSystemEdge(BaseModel):#: Strategy of the link that gave the edge its confidence (``manifest`` on#: a package edge); None on a co-change edge.strategy: str | None = None+ #: runtime | data | build | history, from core's one kind-to-family table.+ #: Filled from ``kind`` for an artifact written before edges carried it.+ family: str | None = None++ @model_validator(mode="after")+ def _fill_family(self) -> WorkspaceSystemEdge:+ if self.family is None:+ from repowise.core.workspace.system_graph import edge_family++ self.family = edge_family(self.kind)+ return selfclass WorkspaceRepoDiagnostics(BaseModel):@@ -483,6 +503,8 @@ class WorkspaceSystemGraphResponse(BaseModel):nodes: list[WorkspaceSystemNode] = []edges: list[WorkspaceSystemEdge] = []diagnostics: WorkspaceExtractionDiagnostics = WorkspaceExtractionDiagnostics()+ #: Service groups; empty when the estate is too small to group.+ groups: list[WorkspaceServiceGroup] = []class WorkspaceSystemMapEdge(WorkspaceSystemEdge):@@ -502,6 +524,8 @@ class WorkspaceSystemGraphMapResponse(BaseModel):generated_at: str = ""nodes: list[WorkspaceSystemNode] = []edges: list[WorkspaceSystemMapEdge] = []+ #: Service groups; empty when the estate is too small to group.+ groups: list[WorkspaceServiceGroup] = []# ---------------------------------------------------------------------------diff --git a/packages/types/src/generated/http.ts b/packages/types/src/generated/http.tsindex 1042856ab..f88574a37 100644--- a/packages/types/src/generated/http.ts+++ b/packages/types/src/generated/http.ts@@ -4941,6 +4941,13 @@ export interface WorkspaceSchemaCoverage {recovered_ratio_eligible?: number | null;}+export interface WorkspaceServiceGroup {+ id: string;+ label: string;+ source: string;+ member_count?: number;+}+/*** One piece of evidence behind an edge between two services.*@@ -4997,6 +5004,7 @@ export interface WorkspaceSystemEdge {structural?: boolean;contract_refs?: string[];strategy?: string | null;+ family?: string | null;}/** ``GET /api/workspace/system-graph?view=map``: the graph without diagnostics. */@@ -5005,6 +5013,7 @@ export interface WorkspaceSystemGraphMapResponse {generated_at?: string;nodes?: WorkspaceSystemNode[];edges?: WorkspaceSystemMapEdge[];+ groups?: WorkspaceServiceGroup[];}export interface WorkspaceSystemGraphResponse {@@ -5013,6 +5022,7 @@ export interface WorkspaceSystemGraphResponse {nodes?: WorkspaceSystemNode[];edges?: WorkspaceSystemEdge[];diagnostics?: WorkspaceExtractionDiagnostics;+ groups?: WorkspaceServiceGroup[];}/** An edge of the map's lean view. Mirrors ``core.workspace.system_map_view``. */@@ -5027,6 +5037,7 @@ export interface WorkspaceSystemMapEdge {structural?: boolean;contract_refs?: string[] | null;strategy?: string | null;+ family?: string | null;ref_count?: number;}@@ -5042,6 +5053,7 @@ export interface WorkspaceSystemNode {is_orphan_provider?: boolean;is_orphan_consumer?: boolean;is_isolated?: boolean;+ group?: string | null;}/** One consumer file the join looked at, and the state it ended in. */diff --git a/packages/types/src/workspace.ts b/packages/types/src/workspace.tsindex c8087b12e..5dc857795 100644--- a/packages/types/src/workspace.ts+++ b/packages/types/src/workspace.ts@@ -204,6 +204,13 @@ export type SystemEdgeKind =| "co_change"| "db";+/**+ * What an edge kind means at the system level. Mirrors core's+ * `EDGE_KIND_FAMILY` (`repowise.core.workspace.system_graph`), the one owner of+ * kind-to-family; read `SystemEdge.family` rather than mapping kinds here.+ */+export type SystemEdgeFamily = "runtime" | "data" | "build" | "history";+/** How confidently an edge was matched. Behavioral co-change edges are `inferred`. */export type SystemEdgeMatchType = "exact" | "candidate" | "manual" | "inferred";@@ -227,6 +234,25 @@ export interface SystemNode {is_orphan_consumer: boolean;/** Participates in no edges. */is_isolated: boolean;+ /** Id of the `ServiceGroup` this service belongs to; absent or null when ungrouped. */+ group?: string | null;+}++/** Where a service group came from: a declared repo tag, a shared alias prefix, or linkage. */+export type ServiceGroupSource = "tag" | "name" | "linked";++/**+ * A group of services the map can draw as one card. Mirrors+ * `repowise.core.workspace.grouping.ServiceGroup`. Core alone decides when to+ * group (`MIN_SERVICES_TO_GROUP`, `MIN_GROUPS`): a non-empty `groups` list is+ * the answer, so a view never re-derives the gate.+ */+export interface ServiceGroup {+ /** `tag:<name>`, `name:<prefix>` or `linked:<smallest member id>`. */+ id: string;+ label: string;+ source: ServiceGroupSource;+ member_count: number;}/** A typed, directed relationship between two services (`source` → `target`). */@@ -250,6 +276,8 @@ export interface SystemEdge {ref_count?: number;/** Strategy of the link that gave the edge its confidence; null on a co-change edge. */strategy?: LinkStrategyWire | null;+ /** The kind's family, set by core (an unknown kind is `history`). */+ family?: SystemEdgeFamily | null;}export interface SystemGraph {@@ -259,6 +287,8 @@ export interface SystemGraph {edges: SystemEdge[];/** Absent from the map's lean view, which reads `/api/workspace/diagnostics`. */diagnostics?: ExtractionDiagnostics;+ /** Service groups; absent or empty when the estate is too small to group. */+ groups?: ServiceGroup[];}// ---------------------------------------------------------------------------diff --git a/tests/unit/server/test_workspace_router.py b/tests/unit/server/test_workspace_router.pyindex 8a87bc596..2e574bf74 100644--- a/tests/unit/server/test_workspace_router.py+++ b/tests/unit/server/test_workspace_router.py@@ -1202,9 +1202,70 @@ class TestGetSystemGraph:kinds = {(e["source"], e["target"], e["kind"]) for e in data["edges"]}assert ("frontend", "backend", "http") in kinds # consumer -> providerassert ("frontend", "backend", "package") in kinds # dependent -> dependency+ assert {(e["kind"], e["family"]) for e in data["edges"]} == {+ ("http", "runtime"),+ ("package", "build"),+ }+ assert data["groups"] == [] # two services: too few to group+ assert {n["group"] for n in data["nodes"]} == {None}assert "diagnostics" in dataassert all("contract_refs" in e and "ref_count" not in e for e in data["edges"])+ @pytest.mark.asyncio+ async def test_fills_family_on_an_older_artifact(self, tmp_path: Path) -> None:+ _make_system_graph_enricher(tmp_path)+ path = tmp_path / "system_graph.json"+ raw = json.loads(path.read_text(encoding="utf-8"))+ for edge in raw["edges"]:+ del edge["family"]+ _write_json(path, raw)+ enricher = CrossRepoEnricher(tmp_path / "cross_repo_edges.json", system_graph_path=path)+ app = _make_workspace_app(ws_config=_make_ws_config(), enricher=enricher)+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:+ data = (await c.get("/api/workspace/system-graph")).json()+ assert {(e["kind"], e["family"]) for e in data["edges"]} == {+ ("http", "runtime"),+ ("package", "build"),+ }++ @pytest.mark.asyncio+ async def test_returns_service_groups(self, tmp_path: Path) -> None:+ from repowise.core.workspace.contracts import Contract+ from repowise.core.workspace.cross_repo import CrossRepoOverlay+ from repowise.core.workspace.system_graph import build_system_graph++ repos = [f"{fam}-{i}" for fam in ("billing", "search", "misc") for i in range(15)]+ contracts = [+ Contract(+ repo=r,+ contract_id=f"http::GET::/{r}",+ contract_type="http",+ role="provider",+ file_path="h.py",+ symbol_name="h",+ confidence=0.9,+ )+ for r in repos+ ]+ graph = build_system_graph(contracts, [], CrossRepoOverlay(), {})+ _write_json(tmp_path / "system_graph.json", graph.to_dict())+ enricher = CrossRepoEnricher(+ tmp_path / "cross_repo_edges.json", system_graph_path=tmp_path / "system_graph.json"+ )+ app = _make_workspace_app(ws_config=_make_ws_config(), enricher=enricher)+ async with AsyncClient(transport=ASGITransport(app=app), base_url="http://test") as c:+ data = (await c.get("/api/workspace/system-graph")).json()+ assert [g["id"] for g in data["groups"]] == ["name:billing", "name:misc", "name:search"]+ assert data["groups"][0] == {+ "id": "name:billing",+ "label": "billing",+ "source": "name",+ "member_count": 15,+ }+ assert {n["group"] for n in data["nodes"] if n["repo"].startswith("search")} == {+ "name:search"+ }+@pytest.mark.asyncioasync def test_map_view_is_lean(self, tmp_path: Path) -> None:enricher = _make_system_graph_enricher(tmp_path)@@ -1221,6 +1282,8 @@ class TestGetSystemGraph:http = next(e for e in lean["edges"] if e["kind"] == "http")assert http["contract_refs"] is Noneassert http["ref_count"] == 1+ assert lean["groups"] == full["groups"]+ assert all("family" in e for e in lean["edges"])@pytest.mark.asyncioasync def test_map_view_empty_when_no_graph(self) -> None:@@ -1230,7 +1293,7 @@ class TestGetSystemGraph:resp = await c.get("/api/workspace/system-graph", params={"view": "map"})bad = await c.get("/api/workspace/system-graph", params={"view": "nope"})assert resp.status_code == 200- assert resp.json() == {"version": 1, "generated_at": "", "nodes": [], "edges": []}+ assert resp.json() == {"version": 1, "generated_at": "", "nodes": [], "edges": [], "groups": []}assert bad.status_code == 422diff --git a/tests/unit/workspace/test_contract_config.py b/tests/unit/workspace/test_contract_config.pyindex fc1be8b0a..c66c587f9 100644--- a/tests/unit/workspace/test_contract_config.py+++ b/tests/unit/workspace/test_contract_config.py@@ -198,3 +198,23 @@ class TestSettingStages:)assert base.analysis_fingerprint() == moved.analysis_fingerprint()assert base.analysis_fingerprint() != edited.analysis_fingerprint()++ def test_analysis_fingerprint_follows_declared_groups_only(self) -> None:+ import hashlib+ import json++ def ws(*tags: str) -> WorkspaceConfig:+ return WorkspaceConfig(repos=[RepoEntry(path="a", alias="a", tags=list(tags))])++ base = ws()+ # Without a group tag the payload is the one stamped before groups+ # counted, so existing stamps (conformance tags included) stay valid.+ old = [base.contracts.to_dict(), base.conformance.to_dict()]+ expected = hashlib.sha256(json.dumps(old, sort_keys=True).encode()).hexdigest()[:16]+ assert base.analysis_fingerprint() == expected+ assert ws("backend", "team:x").analysis_fingerprint() == expected+ assert ws("group:core").analysis_fingerprint() != expected+ assert ws("backend", "group:core").analysis_fingerprint() == ws(+ "group:core", "python"+ ).analysis_fingerprint()+ assert ws("group:core").analysis_fingerprint() != ws("group:edge").analysis_fingerprint()diff --git a/tests/unit/workspace/test_grouping.py b/tests/unit/workspace/test_grouping.pynew file mode 100644index 000000000..c7236a239--- /dev/null+++ b/tests/unit/workspace/test_grouping.py@@ -0,0 +1,284 @@+"""Tests for service grouping: tag, name family and linkage sources, the size gate, determinism."""++from __future__ import annotations++import random++from repowise.core.workspace import grouping+from repowise.core.workspace.contracts import Contract+from repowise.core.workspace.cross_repo import CrossRepoOverlay+from repowise.core.workspace.grouping import MIN_SERVICES_TO_GROUP, group_services+from repowise.core.workspace.system_graph import (+ SystemEdge,+ SystemGraph,+ SystemNode,+ build_system_graph,+)+++def _node(repo: str) -> SystemNode:+ return SystemNode(id=repo, repo=repo, service_path=None, name=repo)+++def _edge(source: str, target: str, kind: str = "http", weight: int = 1) -> SystemEdge:+ return SystemEdge(+ id=f"{source}->{target}:{kind}",+ source=source,+ target=target,+ kind=kind,+ match_type="exact",+ confidence=0.9,+ weight=weight,+ structural=kind != "co_change",+ )+++def _filler(count: int, prefix: str = "solo") -> list[SystemNode]:+ """Services that share no name and no link: they group under no source."""+ return [_node(f"{prefix}{i:03d}") for i in range(count)]+++def _family(name: str, size: int, sep: str = "-") -> list[SystemNode]:+ return [_node(f"{name}{sep}svc{i}") for i in range(size)]+++# ---------------------------------------------------------------------------+# Size gate+# ---------------------------------------------------------------------------+++def test_estate_at_the_threshold_is_never_grouped():+ nodes = _family("ordering", 5) + _family("catalog", 5) + _filler(MIN_SERVICES_TO_GROUP - 10)+ assert len(nodes) == MIN_SERVICES_TO_GROUP+ assert group_services(nodes, []) == ({}, [])+++def test_one_group_is_not_enough():+ nodes = _family("ordering", 5) + _filler(50)+ assert group_services(nodes, []) == ({}, [])+++def test_eshop_sized_estate_stays_flat():+ # 18 services in 18 repos, name families and runtime links present.+ nodes = (+ _family("ordering", 4, ".")+ + _family("catalog", 3, ".")+ + _family("basket", 2, ".")+ + _filler(9)+ )+ edges = [_edge("ordering.svc0", "catalog.svc0"), _edge("basket.svc0", "catalog.svc1")]+ assert group_services(nodes, edges, {"ordering.svc0": ["group:ordering"]}) == ({}, [])+++# ---------------------------------------------------------------------------+# Sources+# ---------------------------------------------------------------------------+++def test_only_a_group_tag_declares_a_group():+ nodes = [_node(a) for a in ("api-a", "api-b", "web-a", "web-b", "job", "cron")]+ nodes += _filler(40)+ tags = {+ "api-a": ["edge", "group:checkout"],+ "web-a": ["group:checkout"],+ "api-b": ["backend", "Group: Billing"],+ "web-b": ["group:Billing", "legacy"],+ # Conformance tags shared by two repos never make a group.+ "job": ["backend", "python"],+ "cron": ["backend", "python"],+ }+ assignment, groups = group_services(nodes, [], tags)+ assert assignment == {+ "api-a": "tag:checkout",+ "web-a": "tag:checkout",+ "api-b": "tag:Billing",+ "web-b": "tag:Billing",+ }+ assert {(g.id, g.label, g.source, g.member_count) for g in groups} == {+ ("tag:checkout", "checkout", "tag", 2),+ ("tag:Billing", "Billing", "tag", 2),+ }+++def test_declared_name_reads_only_group_tags():+ assert grouping.declared_group(["group:", " web "]) is None+ assert grouping.declared_group(["backend"]) is None+ assert grouping.declared_group(["group:", "group: core "]) == "core"+ assert grouping.declared_group(["edge", "Group: Checkout"]) == "Checkout"+ assert grouping.declared_group([]) is None+++def test_lone_tag_falls_through_to_name_family():+ nodes = _family("ordering", 3) + _family("catalog", 3) + _filler(40)+ assignment, _ = group_services(nodes, [], {"ordering-svc0": ["group:solo"]})+ assert assignment["ordering-svc0"] == "name:ordering"+++def test_name_family_needs_two_repos_and_under_half_the_estate():+ nodes = _family("ordering", 3) + _family("catalog", 2) + _filler(40)+ # A monorepo's services share one repo: never a family on their own.+ nodes += [+ SystemNode(id=f"mono::svc{i}", repo="mono-repo", service_path=f"svc{i}", name=f"svc{i}")+ for i in range(3)+ ]+ assignment, groups = group_services(nodes, [])+ assert {g.id for g in groups} == {"name:ordering", "name:catalog"}+ assert not any(nid.startswith("mono::") for nid in assignment)+ assert not any(nid.startswith("solo") for nid in assignment)+++def test_bare_alias_joins_the_family_its_name_starts():+ nodes = [_node("ordering"), *_family("ordering", 2, "."), *_family("catalog", 2), *_filler(40)]+ assignment, _ = group_services(nodes, [])+ assert assignment["ordering"] == "name:ordering"+++def test_organisation_prefix_splits_on_the_next_token():+ # "acme" covers every repo, so families come from the second token.+ nodes = (+ [_node(f"acme-billing-{i}") for i in range(4)]+ + [_node(f"acme-search-{i}") for i in range(4)]+ + [_node(f"acme-misc{i}") for i in range(40)]+ )+ assignment, groups = group_services(nodes, [])+ assert {(g.id, g.label) for g in groups} == {+ ("name:acme.billing", "acme-billing"),+ ("name:acme.search", "acme-search"),+ }+ assert "acme-misc0" not in assignment+++def test_linkage_clusters_ungrouped_services_on_runtime_edges():+ left = [_node(f"l{i}") for i in range(4)]+ right = [_node(f"r{i}") for i in range(4)]+ nodes = left + right + _filler(40)+ edges = [_edge(f"l{i}", "l0") for i in range(1, 4)] + [_edge("l1", "l2", "event")]+ edges += [_edge(f"r{i}", "r3", "grpc") for i in range(3)] + [_edge("r0", "r1", "db")]+ # Build and history edges never pull services together.+ edges += [_edge("l1", "r1", "package"), _edge("l2", "r2", "co_change")]+ edges += [_edge(f"solo{i:03d}", "l0", "package") for i in range(40)]+ assignment, groups = group_services(nodes, edges)+ assert {(g.id, g.label, g.source, g.member_count) for g in groups} == {+ ("linked:l0", "l0", "linked", 4),+ ("linked:r0", "r3", "linked", 4),+ }+ assert all(assignment[n.id] == "linked:l0" for n in left)+ assert not any(nid.startswith("solo") for nid in assignment)+++def test_linked_id_survives_a_new_caller():+ def linked(extra: list[SystemEdge]) -> list[tuple[str, str]]:+ nodes = _family("ordering", 3) + [_node(f"x{c}") for c in "abcd"] + _filler(40)+ pairs = ("ad", "bd", "cd", "ab", "bc", "ac")+ edges = [_edge(f"x{s}", f"x{t}") for s, t in pairs] + extra+ return [(g.id, g.label) for g in group_services(nodes, edges)[1] if g.source == "linked"]++ # The id names the smallest member; the label the most-called one.+ assert linked([]) == [("linked:xa", "xd")]+ # xc gains a caller and ties xd: the label moves, the id does not.+ assert linked([_edge("xd", "xc")]) == [("linked:xa", "xc")]+++def test_unknown_edge_kind_is_history_and_never_links():+ nodes = _family("ordering", 3) + [_node(f"x{i}") for i in range(3)] + _filler(40)+ edges = [_edge("x1", "x0", "carrier_pigeon"), _edge("x2", "x0", "carrier_pigeon")]+ assert edges[0].family == "history"+ assert group_services(nodes, edges) == ({}, [])+++def test_linkage_skips_services_already_grouped():+ nodes = _family("ordering", 3) + [_node(f"x{i}") for i in range(3)] + _filler(40)+ edges = [_edge("x1", "x0"), _edge("x2", "x0"), _edge("ordering-svc0", "x0")]+ assignment, _ = group_services(nodes, edges)+ assert assignment["ordering-svc0"] == "name:ordering"+ assert {assignment[f"x{i}"] for i in range(3)} == {"linked:x0"}+++def test_linkage_past_the_pair_cap_is_skipped(monkeypatch):+ monkeypatch.setattr(grouping, "MAX_LINKAGE_PAIRS", 2)+ nodes = _family("ordering", 3) + [_node(f"x{i}") for i in range(4)] + _filler(40)+ edges = [_edge("x1", "x0"), _edge("x2", "x0"), _edge("x3", "x0")]+ assert group_services(nodes, edges) == ({}, [])+++# ---------------------------------------------------------------------------+# Determinism+# ---------------------------------------------------------------------------+++def _mixed_estate() -> tuple[list[SystemNode], list[SystemEdge], dict[str, list[str]]]:+ nodes = _family("ordering", 4) + _family("catalog", 3) + _filler(60)+ edges = [+ _edge(f"solo{i:03d}", f"solo{(i * 7 + 3) % 60:03d}", "http", weight=i % 4 + 1)+ for i in range(60)+ ]+ tags = {"solo001": ["group:core"], "solo002": ["team:x", "group:core"]}+ return nodes, edges, tags+++def test_same_estate_in_any_order_groups_the_same():+ nodes, edges, tags = _mixed_estate()+ expected = group_services(nodes, edges, tags)+ assert expected[1], "the fixture must form groups"+ rng = random.Random(7)+ for _ in range(5):+ shuffled_nodes, shuffled_edges = nodes[:], edges[:]+ rng.shuffle(shuffled_nodes)+ rng.shuffle(shuffled_edges)+ assert group_services(shuffled_nodes, shuffled_edges, tags) == expected+++# ---------------------------------------------------------------------------+# Through the system graph+# ---------------------------------------------------------------------------+++def _provider(repo: str) -> Contract:+ return Contract(+ repo=repo,+ contract_id=f"http::GET::/{repo}",+ contract_type="http",+ role="provider",+ file_path="src/h.py",+ symbol_name="h",+ confidence=0.9,+ )+++def test_synthetic_120_service_estate_groups_by_name_family():+ families = ("ordering", "catalog", "basket", "identity", "payments", "shipping")+ repos = [f"{fam}-{part}" for fam in families for part in range(20)]+ graph = build_system_graph([_provider(r) for r in repos], [], CrossRepoOverlay(), {})+ assert len(graph.nodes) == 120+ assert [(g.id, g.source, g.member_count) for g in graph.groups] == [+ (f"name:{fam}", "name", 20) for fam in sorted(families)+ ]+ assert all(n.group == f"name:{n.repo.split('-')[0]}" for n in graph.nodes)++ data = graph.to_dict()+ assert data["groups"][0] == {+ "id": "name:basket",+ "label": "basket",+ "source": "name",+ "member_count": 20,+ }+ assert SystemGraph.from_dict(data).to_dict() == data+++def test_declared_tags_reach_the_graph_through_build():+ repos = [f"svc{i:03d}" for i in range(45)]+ tags = {r: ["group:front"] for r in repos[:3]} | {r: ["group:back"] for r in repos[3:6]}+ graph = build_system_graph(+ [_provider(r) for r in repos], [], CrossRepoOverlay(), {}, repo_tags=tags+ )+ assert {g.id for g in graph.groups} == {"tag:front", "tag:back"}+ assert sum(1 for n in graph.nodes if n.group) == 6+++def test_flat_graph_serializes_without_group_keys():+ graph = build_system_graph(+ [_provider(f"svc{i}") for i in range(10)], [], CrossRepoOverlay(), {}+ )+ data = graph.to_dict()+ assert "groups" not in data+ assert all("group" not in n for n in data["nodes"])diff --git a/tests/unit/workspace/test_system_graph.py b/tests/unit/workspace/test_system_graph.pyindex 5bebefc1e..a9d2780d9 100644--- a/tests/unit/workspace/test_system_graph.py+++ b/tests/unit/workspace/test_system_graph.py@@ -334,6 +334,7 @@ def test_system_graph_json_shape_is_locked():"structural","contract_refs","strategy",+ "family",}assert set(data["diagnostics"]) == {"total_providers",@@ -360,6 +361,36 @@ def test_system_graph_json_shape_is_locked():}+def test_every_edge_kind_has_one_family():+ from repowise.core.workspace.system_graph import (+ EDGE_FAMILIES,+ EDGE_KIND_FAMILY,+ EDGE_KINDS,+ edge_family,+ )++ assert set(EDGE_KIND_FAMILY) == set(EDGE_KINDS)+ assert set(EDGE_KIND_FAMILY.values()) == set(EDGE_FAMILIES)+ assert [edge_family(k) for k in ("http", "db", "package", "co_change")] == [+ "runtime",+ "data",+ "build",+ "history",+ ]+ # An unmapped kind is non-structural in the builder, so it is history here.+ assert edge_family("carrier_pigeon") == "history"+++def test_edges_serialize_their_family():+ 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 [e.to_dict()["family"] for e in graph.edges] == ["runtime"]++def test_round_trip_serialization():contracts = [_provider("api", "http::GET::/users", file="api/h.py")]graph = build_system_graph(contracts, [], CrossRepoOverlay(), {}, generated_at="t")