Skip to content

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

feat(workspace): group services into systems (tag, name family, linkage) (#4600)

Raghav Chamadiya99260ec70e4f
diff --git a/docs/scale/WORKSPACES.md b/docs/scale/WORKSPACES.md
index 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 Diagnostics
diff --git a/packages/core/src/repowise/core/workspace/config.py b/packages/core/src/repowise/core/workspace/config.py
index 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 Any
import 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.py
index 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 call
build += 1
else:
runtime += 1
diff --git a/packages/core/src/repowise/core/workspace/grouping.py b/packages/core/src/repowise/core/workspace/grouping.py
new file mode 100644
index 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.py
index 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_services
from repowise.core.workspace.origins import LinkStrategy, legacy_strategy
if 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 consumes
is_orphan_consumer: bool = False # consumes contracts that never matched
is_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 = None
def 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
@classmethod
def 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
@classmethod
def 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 the
repo 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.py
index 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 annotations
from typing import Any, Literal
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, model_validator
class WorkspaceRepoRemovedResponse(BaseModel):
@@ -325,6 +325,15 @@ class WorkspaceSystemNode(BaseModel):
is_orphan_provider: bool = False
is_orphan_consumer: bool = False
is_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 = 0
class 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 self
class 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.ts
index 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.ts
index 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.py
index 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 -> provider
assert ("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 data
assert 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.asyncio
async 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 None
assert http["ref_count"] == 1
+ assert lean["groups"] == full["groups"]
+ assert all("family" in e for e in lean["edges"])
@pytest.mark.asyncio
async 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 == 422
diff --git a/tests/unit/workspace/test_contract_config.py b/tests/unit/workspace/test_contract_config.py
index 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.py
new file mode 100644
index 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.py
index 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")