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(components): Backstage-shaped component model with derived defaults and rollups (#3722)

Raghav Chamadiyacf3d4352ca6d
diff --git a/docs/agent/MCP_TOOLS.md b/docs/agent/MCP_TOOLS.md
index 1da9a132f..87ec89269 100644
--- a/docs/agent/MCP_TOOLS.md
+++ b/docs/agent/MCP_TOOLS.md
@@ -161,13 +161,15 @@ A triage card for files, modules or symbols: summary, symbols with signatures an
| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
-| `targets` | list[string] | required | File paths, module paths, or `"path::Symbol"` ids |
+| `targets` | list[string] | required | File paths, module paths, `"path::Symbol"` ids, or `"component:<name>"` |
| `include` | list[string] | none | Any of `full_doc`, `ownership`, `last_change`, `callers`, `callees`, `references`, `metrics`, `community`, `decisions`, `skeleton`, `health`, `doc_drift`, `symbols` |
| `compact` | bool | `true` | `false` adds the structure block, imports and docstrings |
| `repo` | string | default repo | Workspace repo alias. `"all"` is not supported (returns an error) |
**Key return fields:** `targets` keyed by target, each with title, summary, symbols, `hotspot`, `fix_history` (files with counted bug fixes), `episodes`, decision titles, `file_preview` (for files with no symbols), `resolved_to` (a symbol miss falling back to its file); `dropped_targets` and `recovery` when the budget forced targets out; `_meta.complete` for whole files served.
+A `component:<name>` target returns the component's declared context (owner, system, criticality, tags) and `facts` rolled up over its files: health, hotspots, bus factor, test reach and dead code, each with a `basis` (`measured`, `inferred` or `unavailable`). Components come from [`.repowise/components.yaml`](../reference/CONFIG.md#repowisecomponentsyaml) or are derived from the index. `include` does not apply to component targets; health and dead code leave out files in gated languages and say how many.
+
A file's compact symbol list holds its top 15 symbols: types (classes, interfaces, structs, traits, enums, type aliases, impls, modules) first, then functions and methods, then the rest, each group by centrality. `symbols_truncated` gives the total, and `include=["symbols"]` lists them all. When the response budget trims the list further, it keeps symbols by kind and name match, not centrality. A row without `symbol_id` is `path::name`; methods and overload variants carry theirs, so pass a row's id to `get_symbol` when it has one.
`full_doc` returns the page as `content_md`, plus `digest_md` on pages that carry an agent digest: the questions the page answers, its concept index, public API and git signals. Both are dropped first when the response is over budget. `skeleton` renders a file with bodies elided: every signature, the imports, and the bodies of its most central symbols, with line ranges on every elision. `doc_drift` lists the documents that name the file and whether they carry drift. An empty `callers` or `callees` list comes with a `*_basis` saying how much of that language's calls the graph resolved; read it before concluding nothing calls a symbol.
@@ -305,7 +307,7 @@ The architecture map: summary, key modules, entry points, layers, code and git h
| Parameter | Type | Default | Meaning |
|-----------|------|---------|---------|
-| `include` | list[string] | none | Any of `content` (full essay), `outline` (wiki page tree), `tour` (guided tour and reading order), `decisions`, `graph` (community clusters), `ownership` (top owners) |
+| `include` | list[string] | none | Any of `content` (full essay), `outline` (wiki page tree), `tour` (guided tour and reading order), `decisions`, `graph` (community clusters), `ownership` (top owners), `components` (declared and derived components with file counts) |
| `repo` | string | default repo | Workspace repo alias, or `"all"` for the cross-repo topology |
**Key return fields:** `title`, `content_md` (summary section by default), `key_modules`, `entry_points`, `architecture` (layers in stack order, plus `dependencies`: the ten heaviest package-to-package edges with `from`, `to`, `verb` and `weight`, and `edges_total` when more exist; absent in a single-package repo), `code_health`, `git_health`, `next_actions`, `more` (names the opt-in blocks), and a `workspace` footer in workspace mode.
diff --git a/docs/reference/CLI_REFERENCE.md b/docs/reference/CLI_REFERENCE.md
index 9f3d7c797..54683cc9c 100644
--- a/docs/reference/CLI_REFERENCE.md
+++ b/docs/reference/CLI_REFERENCE.md
@@ -37,7 +37,8 @@ Grouped by what you're trying to do, not alphabetically. `PATH` and flag details
[`doc-drift`](#repowise-doc-drift-path) ·
[`security`](#repowise-security) ·
[`impacted-tests`](#repowise-impacted-tests-revspec) ·
-[`coverage`](#repowise-coverage)
+[`coverage`](#repowise-coverage) ·
+[`components`](#repowise-components)
**Decisions**
[`decision`](#repowise-decision)
@@ -1579,6 +1580,17 @@ repowise coverage suggest-gates --format json
---
+### `repowise components`
+
+`check` validates `.repowise/components.yaml` and a repo-root `catalog-info.yaml` (Backstage entities, see [CONFIG.md](CONFIG.md#repowisecomponentsyaml)) against the files git tracks, and exits 1 on any error, so it fits a CI step. `list` shows declared and derived components with their file counts.
+
+```bash
+repowise components check [--path PATH] [--format table|json]
+repowise components list [--path PATH] [--format table|json]
+```
+
+---
+
### `repowise distill <command>`
Run a command and print a compact, reversible rendering of its output. Noise
diff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.md
index e8e63ea39..4d57f235a 100644
--- a/docs/reference/CONFIG.md
+++ b/docs/reference/CONFIG.md
@@ -566,6 +566,10 @@ Dismissals are sticky: `repowise decision dismiss` keeps the record as a
a confirmed (`active`) decision is never walked back to `proposed` by a
re-extraction.
+### `.repowise/components.yaml`
+
+Components name the parts of a repository that health, hotspots, bus factor, test reach and dead code roll up to. The file is multi-document Backstage YAML (`Component`, `System` and `Group` on `backstage.io/v1alpha1`), with Repowise data in `repowise.dev/paths` (gitignore-style globs written with `/`, matched case-sensitively), `repowise.dev/criticality` (`low`, `medium`, `high`, `critical`), `repowise.dev/tags` and `repowise.dev/capability` annotations; a repo-root `catalog-info.yaml` is read the same way, so a developer portal and Repowise share one file. Without a file, components are derived from workspace services, then module pages, then top-level directories; a declared component claims the files its globs match (where two match a file, the first declared wins), and one named like a derived component replaces it and, with no paths of its own, keeps its directory. See [examples/components](../../examples/components/components.yaml) and `repowise components check`.
+
### The `security:` block
Secret shapes of your own for `repowise security check`.
diff --git a/examples/README.md b/examples/README.md
index 1681fdc1a..052c61031 100644
--- a/examples/README.md
+++ b/examples/README.md
@@ -8,6 +8,7 @@ self-contained README under `examples/<name>/`.
| Example | What it shows |
|---------|----------------|
| [codex/](codex/) | Codex CLI setup: `repowise init --codex`, smoke checks, local plugin install |
+| [components/](components/) | `repowise components check` and `list`: Backstage-shaped components and per-component facts (no LLM key) |
| [dead-code/](dead-code/) | `repowise dead-code` — unused exports and cleanup candidates (no LLM key) |
| [decisions/](decisions/) | `repowise decision` list/health/confirm — architectural records (no LLM key) |
| [distill/](distill/) | `distill` / `expand` / `saved` — compress command output (no LLM key) |
diff --git a/examples/components/README.md b/examples/components/README.md
new file mode 100644
index 000000000..86623b83a
--- /dev/null
+++ b/examples/components/README.md
@@ -0,0 +1,15 @@
+# Components
+
+Name the parts of your repository and see code facts per part. Copy
+[components.yaml](components.yaml) to `.repowise/components.yaml` (or use its
+documents in a repo-root `catalog-info.yaml`), adjust the paths, then:
+
+```bash
+repowise components check # validate; exits 1 on errors
+repowise components list # declared and derived components with file counts
+```
+
+Agents read the same model through `get_context(targets=["component:payments-api"])`
+and `get_overview(include=["components"])`. No file is needed to start: without
+one, components are derived from the index. The format is described in
+[CONFIG.md](../../docs/reference/CONFIG.md#repowisecomponentsyaml).
diff --git a/examples/components/components.yaml b/examples/components/components.yaml
new file mode 100644
index 000000000..45fcf3683
--- /dev/null
+++ b/examples/components/components.yaml
@@ -0,0 +1,56 @@
+# .repowise/components.yaml: Backstage entities with Repowise data in annotations.
+# The same documents work in a repo-root catalog-info.yaml.
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+ name: checkout
+ description: Everything a customer touches to pay.
+spec:
+ owner: group:default/payments
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: payments-api
+ title: Payments API
+ description: Card authorisation, capture and refunds.
+ annotations:
+ repowise.dev/paths: services/payments/**, libs/money/**
+ repowise.dev/criticality: critical
+ repowise.dev/tags: pci, customer-facing, regulated
+ repowise.dev/capability: Take payments
+spec:
+ type: service
+ lifecycle: production
+ owner: group:default/payments
+ system: checkout
+---
+# No paths: if a derived component is named "web", this one takes its directory.
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: web
+ annotations:
+ repowise.dev/criticality: high
+ repowise.dev/tags: customer-facing, cra-product
+spec:
+ type: website
+ lifecycle: production
+ owner: group:default/frontend
+ system: checkout
+---
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata:
+ name: payments
+spec:
+ type: team
+ children: []
+---
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata:
+ name: frontend
+spec:
+ type: team
+ children: []
diff --git a/packages/cli/src/repowise/cli/commands/components_cmd.py b/packages/cli/src/repowise/cli/commands/components_cmd.py
new file mode 100644
index 000000000..d922ffea6
--- /dev/null
+++ b/packages/cli/src/repowise/cli/commands/components_cmd.py
@@ -0,0 +1,162 @@
+"""``repowise components`` - validate and list the repository's components.
+
+``check`` reads ``.repowise/components.yaml`` and ``catalog-info.yaml`` and
+validates them against the files git tracks; it needs no index and exits
+non-zero on any error, so it fits a CI step. ``list`` shows declared and
+derived components with their file counts, from the index when there is one.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+import click
+
+from repowise.cli.helpers import console, repo_index_session, resolve_command_target, run_async
+from repowise.cli.output import emit_json, format_option
+
+
+def _repo_root(path: str | None) -> Path:
+ target = resolve_command_target(path=path, no_workspace_flag=True)
+ assert target.repo_path is not None
+ return Path(target.repo_path).resolve()
+
+
+def _tracked(root: Path) -> list[str]:
+ """Repo-relative POSIX paths git tracks, or every walked file outside git."""
+ from repowise.core.analysis.decisions.source_files import tracked_files
+ from repowise.core.fs_walk import walk_repo
+
+ tracked = tracked_files(root)
+ if tracked is not None:
+ paths = (p.relative_to(root) for p in tracked if p.is_relative_to(root))
+ else:
+ paths = (
+ (Path(d) / f).relative_to(root) for d, _dirs, names in walk_repo(root) for f in names
+ )
+ return sorted(p.as_posix() for p in paths)
+
+
[email protected]("components")
+def components_group() -> None:
+ """Validate and list the components code facts roll up to."""
+
+
+@components_group.command("check")
[email protected]("--path", "repo", default=None, help="Repo path (defaults to cwd).")
+@format_option()
+def components_check(repo: str | None, fmt: str) -> None:
+ """Validate .repowise/components.yaml and catalog-info.yaml; exit 1 on errors."""
+ from repowise.core.components import check_catalog, read_catalog
+
+ root = _repo_root(repo)
+ catalog = read_catalog(root)
+ issues = check_catalog(catalog, _tracked(root))
+ errors = sum(1 for i in issues if i.severity == "error")
+ if fmt == "json":
+ emit_json(
+ {
+ "sources": catalog.sources,
+ "components": len(catalog.components),
+ "systems": len(catalog.systems),
+ "groups": len(catalog.groups),
+ "errors": errors,
+ "issues": [i.to_dict() for i in issues],
+ }
+ )
+ elif not catalog.sources:
+ console.print(
+ "No catalog file found (.repowise/components.yaml or catalog-info.yaml); "
+ "components are derived from the index."
+ )
+ else:
+ from rich.markup import escape
+
+ console.print(
+ f"Read {', '.join(catalog.sources)}: {len(catalog.components)} component(s), "
+ f"{len(catalog.systems)} system(s), {len(catalog.groups)} group(s)."
+ )
+ for i in issues:
+ colour = "red" if i.severity == "error" else "yellow"
+ where = " ".join(x for x in (i.source, i.entity) if x)
+ console.print(f"[{colour}]{i.severity}[/{colour}] {escape(where)}: {escape(i.message)}")
+ if not issues:
+ console.print("[green]No issues.[/green]")
+ if errors:
+ raise SystemExit(1)
+
+
+async def _list(root: Path) -> dict[str, Any]:
+ from repowise.core.components import read_catalog, resolve_components
+ from repowise.core.components.resolve import derive_from_directories
+ from repowise.core.components.store import load_repo_components, workspace_services
+
+ async with repo_index_session(root) as opened:
+ if opened is not None:
+ session, repo_id = opened
+ found = await load_repo_components(
+ session, repo_id, root, services=workspace_services(root)
+ )
+ return {"indexed": True, "catalog": found.catalog, "resolved": found.resolved}
+ files = _tracked(root)
+ catalog = read_catalog(root)
+ resolved = resolve_components(catalog.components, derive_from_directories(files), files)
+ return {"indexed": False, "catalog": catalog, "resolved": resolved}
+
+
+@components_group.command("list")
[email protected]("--path", "repo", default=None, help="Repo path (defaults to cwd).")
+@format_option()
+def components_list(repo: str | None, fmt: str) -> None:
+ """List declared and derived components with their file counts."""
+ root = _repo_root(repo)
+ data = run_async(_list(root))
+ resolved = data["resolved"]
+ rows = [
+ {
+ "name": c.name,
+ "source": c.source,
+ "files": len(resolved.files[c.name]),
+ **{
+ k: v
+ for k, v in (
+ ("owner", c.owner),
+ ("system", c.system),
+ ("criticality", c.criticality),
+ ("tags", list(c.tags)),
+ )
+ if v
+ },
+ }
+ for c in resolved.components
+ ]
+ if fmt == "json":
+ emit_json(
+ {
+ "components": rows,
+ "unassigned_files": len(resolved.unassigned),
+ "catalog_errors": len(data["catalog"].errors),
+ }
+ )
+ return
+ from rich.markup import escape
+ from rich.table import Table
+
+ table = Table("Component", "Source", "Files", "Owner", "Criticality", "Tags")
+ for r in rows:
+ table.add_row(
+ escape(r["name"]),
+ r["source"],
+ str(r["files"]),
+ escape(r.get("owner") or ""),
+ r.get("criticality") or "",
+ escape(", ".join(r.get("tags") or [])),
+ )
+ console.print(table)
+ if resolved.unassigned:
+ console.print(f"[dim]{len(resolved.unassigned)} file(s) belong to no component.[/dim]")
+ if not data["indexed"]:
+ console.print("[dim]No index found: derived components are top-level directories.[/dim]")
+ if data["catalog"].errors:
+ console.print("[yellow]The catalog has errors; run `repowise components check`.[/yellow]")
diff --git a/packages/cli/src/repowise/cli/main.py b/packages/cli/src/repowise/cli/main.py
index 8205fca71..c6ab185ed 100644
--- a/packages/cli/src/repowise/cli/main.py
+++ b/packages/cli/src/repowise/cli/main.py
@@ -71,6 +71,7 @@ _OSS_COMMANDS: tuple[tuple[str, str], ...] = (
("overlap", "overlap_cmd:overlap_command"),
("decision", "decision_cmd:decision_group"),
("coverage", "coverage_cmd:coverage_group"),
+ ("components", "components_cmd:components_group"),
("impacted-tests", "impacted_tests_cmd:impacted_tests_command"),
("search", "search_cmd:search_command"),
("ask", "ask_cmd:ask_command"),
diff --git a/packages/core/src/repowise/core/components/__init__.py b/packages/core/src/repowise/core/components/__init__.py
new file mode 100644
index 000000000..10fdc86e0
--- /dev/null
+++ b/packages/core/src/repowise/core/components/__init__.py
@@ -0,0 +1,34 @@
+"""Components: named parts of a repository that code facts roll up to.
+
+Declared in Backstage-shaped catalog files (:mod:`.catalog`), derived from the
+index when none are declared (:mod:`.resolve`), validated by
+``repowise components check`` (:mod:`.check`), and summarised per component
+from existing per-file facts (:mod:`.rollup`).
+"""
+
+from __future__ import annotations
+
+from repowise.core.components.catalog import (
+ CATALOG_FILES,
+ Catalog,
+ CatalogIssue,
+ Component,
+ Group,
+ System,
+ read_catalog,
+)
+from repowise.core.components.check import check_catalog
+from repowise.core.components.resolve import ResolvedComponents, resolve_components
+
+__all__ = [
+ "CATALOG_FILES",
+ "Catalog",
+ "CatalogIssue",
+ "Component",
+ "Group",
+ "ResolvedComponents",
+ "System",
+ "check_catalog",
+ "read_catalog",
+ "resolve_components",
+]
diff --git a/packages/core/src/repowise/core/components/catalog.py b/packages/core/src/repowise/core/components/catalog.py
new file mode 100644
index 000000000..0329b5ef2
--- /dev/null
+++ b/packages/core/src/repowise/core/components/catalog.py
@@ -0,0 +1,353 @@
+"""Read declared components from Backstage-shaped catalog files.
+
+Two files are read, in this order: ``.repowise/components.yaml`` and a
+repo-root ``catalog-info.yaml``. Both are multi-document Backstage YAML
+(``apiVersion: backstage.io/v1alpha1``), so a developer portal and Repowise
+share one file. Component, System and Group entities are read; the other
+Backstage kinds (API, Resource, Domain, User, Location, Template) are valid
+and skipped. Repowise data lives only under ``repowise.dev/*`` annotations,
+which keeps the files valid Backstage.
+
+When both files declare the same kind and name, the first one read wins.
+Group entities are ownership inputs only: their name, type and hierarchy are
+kept, ``spec.members`` is never read.
+
+Reading never raises: every problem becomes a :class:`CatalogIssue`, and an
+entity that cannot be identified (no name, unknown kind, wrong apiVersion) is
+left out of the catalog.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+COMPONENTS_FILE = ".repowise/components.yaml"
+CATALOG_INFO_FILE = "catalog-info.yaml"
+#: Read in this order; on a duplicate kind and name the earlier file wins.
+CATALOG_FILES: tuple[str, ...] = (COMPONENTS_FILE, CATALOG_INFO_FILE)
+#: A catalog file above this is refused unparsed: it is hand-written config,
+#: and the tool path re-reads it.
+MAX_CATALOG_BYTES = 1_000_000
+
+API_VERSION = "backstage.io/v1alpha1"
+READ_KINDS = frozenset({"Component", "System", "Group"})
+#: Backstage kinds that are valid in a shared catalog file but carry nothing
+#: Repowise reads. Template is the one kind on ``backstage.io/v1beta2``.
+SKIPPED_KINDS = frozenset({"API", "Resource", "Domain", "User", "Location", "Template"})
+
+ANNOTATION_PREFIX = "repowise.dev/"
+PATHS_ANNOTATION = "repowise.dev/paths"
+CRITICALITY_ANNOTATION = "repowise.dev/criticality"
+TAGS_ANNOTATION = "repowise.dev/tags"
+CAPABILITY_ANNOTATION = "repowise.dev/capability"
+KNOWN_ANNOTATIONS = frozenset(
+ {PATHS_ANNOTATION, CRITICALITY_ANNOTATION, TAGS_ANNOTATION, CAPABILITY_ANNOTATION}
+)
+CRITICALITY_LEVELS: tuple[str, ...] = ("low", "medium", "high", "critical")
+
+#: Backstage's own name rule: 1-63 characters of ``[a-zA-Z0-9]`` separated by
+#: single ``-``, ``_`` or ``.``.
+_NAME_RE = re.compile(r"^[a-zA-Z0-9]+(?:[-_.][a-zA-Z0-9]+)*$")
+_NAME_MAX = 63
+#: The spec fields Backstage requires per kind.
+_REQUIRED_SPEC: dict[str, tuple[str, ...]] = {
+ "Component": ("type", "lifecycle", "owner"),
+ "System": ("owner",),
+ "Group": ("type", "children"),
+}
+
+
+@dataclass(frozen=True)
+class CatalogIssue:
+ severity: str # "error" | "warning"
+ message: str
+ source: str | None = None # the catalog file, repo-relative
+ entity: str | None = None # "Kind:name"
+
+ def to_dict(self) -> dict[str, Any]:
+ out: dict[str, Any] = {"severity": self.severity, "message": self.message}
+ if self.source:
+ out["source"] = self.source
+ if self.entity:
+ out["entity"] = self.entity
+ return out
+
+
+@dataclass(frozen=True)
+class Component:
+ """A component, declared in a catalog file or derived from the index."""
+
+ name: str
+ title: str | None = None
+ description: str | None = None
+ type: str | None = None # spec.type
+ lifecycle: str | None = None
+ owner: str | None = None
+ system: str | None = None
+ #: gitignore-style globs relative to the repository root, written with
+ #: ``/`` and matched case-sensitively on every platform.
+ paths: tuple[str, ...] = ()
+ criticality: str | None = None
+ tags: tuple[str, ...] = ()
+ capability: str | None = None
+ #: "declared", or how a derived one was found: "service", "module", "directory".
+ source: str = "declared"
+ #: The catalog file a declared component came from.
+ declared_in: str | None = None
+ #: Directory a derived component covers; files go to the deepest one.
+ root: str | None = None
+
+ @property
+ def declared(self) -> bool:
+ return self.source == "declared"
+
+
+@dataclass(frozen=True)
+class System:
+ name: str
+ title: str | None = None
+ description: str | None = None
+ owner: str | None = None
+ declared_in: str | None = None
+
+
+@dataclass(frozen=True)
+class Group:
+ """A declared owning team. Membership is never read."""
+
+ name: str
+ title: str | None = None
+ type: str | None = None
+ parent: str | None = None
+ children: tuple[str, ...] = ()
+ declared_in: str | None = None
+
+
+@dataclass
+class Catalog:
+ components: list[Component] = field(default_factory=list)
+ systems: list[System] = field(default_factory=list)
+ groups: list[Group] = field(default_factory=list)
+ issues: list[CatalogIssue] = field(default_factory=list)
+ #: Catalog files found and read, repo-relative.
+ sources: list[str] = field(default_factory=list)
+
+ @property
+ def errors(self) -> list[CatalogIssue]:
+ return [i for i in self.issues if i.severity == "error"]
+
+
+def read_catalog(repo_root: Path | str) -> Catalog:
+ """Every catalog file under *repo_root*, merged in :data:`CATALOG_FILES` order."""
+ catalog = Catalog()
+ root = Path(repo_root)
+ for rel in CATALOG_FILES:
+ path = root / rel
+ if not path.is_file():
+ continue
+ try:
+ if path.stat().st_size > MAX_CATALOG_BYTES:
+ catalog.issues.append(
+ CatalogIssue("error", f"larger than {MAX_CATALOG_BYTES} bytes; not read", rel)
+ )
+ continue
+ text = path.read_text(encoding="utf-8")
+ except (OSError, UnicodeDecodeError) as exc:
+ catalog.issues.append(CatalogIssue("error", f"cannot read: {exc}", rel))
+ continue
+ catalog.sources.append(rel)
+ parse_into(catalog, text, rel)
+ return catalog
+
+
+def parse_into(catalog: Catalog, text: str, source: str) -> None:
+ """Add the entities of one multi-document YAML file to *catalog*."""
+ try:
+ documents = [d for d in yaml.safe_load_all(text) if d is not None]
+ except yaml.YAMLError as exc:
+ catalog.issues.append(CatalogIssue("error", f"invalid YAML: {exc}", source))
+ return
+ seen_here: set[str] = set()
+ for doc in documents:
+ _parse_entity(catalog, doc, source, seen_here)
+
+
+def _parse_entity(catalog: Catalog, doc: Any, source: str, seen_here: set[str]) -> None:
+ def issue(severity: str, message: str, entity: str | None = None) -> None:
+ catalog.issues.append(CatalogIssue(severity, message, source, entity))
+
+ identity = _identify(doc, issue)
+ if identity is None:
+ return
+ kind, name, label, metadata = identity
+ if label in seen_here:
+ issue("error", "declared twice in this file", label)
+ return
+ seen_here.add(label)
+ if _already_declared(catalog, kind, name):
+ issue("warning", "also declared in an earlier catalog file, which wins", label)
+ return
+
+ spec = doc.get("spec") if isinstance(doc.get("spec"), dict) else {}
+ for key in _REQUIRED_SPEC[kind]:
+ if spec.get(key) in (None, ""):
+ issue("error", f"spec.{key} is required for a {kind}", label)
+ annotations = _annotations(metadata, label, issue)
+ if kind == "System":
+ catalog.systems.append(_system(name, metadata, spec, source))
+ elif kind == "Group":
+ catalog.groups.append(_group(name, metadata, spec, source))
+ else:
+ criticality = _criticality(annotations.get(CRITICALITY_ANNOTATION), label, issue)
+ catalog.components.append(
+ _component(name, metadata, spec, annotations, criticality, source)
+ )
+
+
+def _identify(doc: Any, issue: Any) -> tuple[str, str, str, dict] | None:
+ """``(kind, name, label, metadata)`` for an entity Repowise reads, else ``None``.
+
+ Kinds Backstage defines and Repowise skips return ``None`` silently; every
+ other refusal is reported through *issue*.
+ """
+ if not isinstance(doc, dict):
+ issue("error", "a document is not a mapping")
+ return None
+ kind = doc.get("kind")
+ metadata = doc.get("metadata") if isinstance(doc.get("metadata"), dict) else {}
+ name = metadata.get("name")
+ label = f"{kind}:{name}" if name else str(kind)
+ if kind in SKIPPED_KINDS:
+ return None
+ if kind not in READ_KINDS:
+ issue("error", f"unknown kind {kind!r}; expected Component, System or Group", label)
+ return None
+ if doc.get("apiVersion") != API_VERSION:
+ issue("error", f"apiVersion must be {API_VERSION!r}, got {doc.get('apiVersion')!r}", label)
+ return None
+ if not isinstance(name, str) or not name:
+ issue("error", f"{kind} has no metadata.name")
+ return None
+ if len(name) > _NAME_MAX or not _NAME_RE.match(name):
+ issue("error", f"metadata.name {name!r} is not a valid Backstage name", label)
+ return None
+ return kind, name, label, metadata
+
+
+def _system(name: str, metadata: dict, spec: dict, source: str) -> System:
+ return System(
+ name,
+ _text(metadata.get("title")),
+ _text(metadata.get("description")),
+ _text(spec.get("owner")),
+ declared_in=source,
+ )
+
+
+def _group(name: str, metadata: dict, spec: dict, source: str) -> Group:
+ children = spec.get("children") if isinstance(spec.get("children"), list) else []
+ profile = spec.get("profile") if isinstance(spec.get("profile"), dict) else {}
+ return Group(
+ name,
+ _text(metadata.get("title")) or _text(profile.get("displayName")),
+ _text(spec.get("type")),
+ _text(spec.get("parent")),
+ tuple(str(c) for c in children),
+ declared_in=source,
+ )
+
+
+def _criticality(value: str | None, label: str, issue: Any) -> str | None:
+ if value is None:
+ return None
+ level = value.strip().lower()
+ if level in CRITICALITY_LEVELS:
+ return level
+ levels = ", ".join(CRITICALITY_LEVELS)
+ issue("error", f"{CRITICALITY_ANNOTATION} must be one of {levels}", label)
+ return None
+
+
+def _component(
+ name: str,
+ metadata: dict,
+ spec: dict,
+ annotations: dict[str, str],
+ criticality: str | None,
+ source: str,
+) -> Component:
+ meta_tags = metadata.get("tags") if isinstance(metadata.get("tags"), list) else []
+ tags = [str(t).strip().lower() for t in meta_tags]
+ tags += _split(annotations.get(TAGS_ANNOTATION))
+ return Component(
+ name=name,
+ title=_text(metadata.get("title")),
+ description=_text(metadata.get("description")),
+ type=_text(spec.get("type")),
+ lifecycle=_text(spec.get("lifecycle")),
+ owner=_text(spec.get("owner")),
+ system=_text(spec.get("system")),
+ paths=tuple(_split(annotations.get(PATHS_ANNOTATION), lower=False)),
+ criticality=criticality,
+ tags=tuple(dict.fromkeys(t for t in tags if t)),
+ capability=_text(annotations.get(CAPABILITY_ANNOTATION)),
+ declared_in=source,
+ )
+
+
+def _already_declared(catalog: Catalog, kind: str, name: str) -> bool:
+ pool: list[Any] = {
+ "Component": catalog.components,
+ "System": catalog.systems,
+ "Group": catalog.groups,
+ }[kind]
+ return any(e.name == name for e in pool)
+
+
+def _annotations(metadata: dict, label: str, issue: Any) -> dict[str, str]:
+ """``repowise.dev/*`` annotations; unknown keys and non-string values are errors."""
+ raw = metadata.get("annotations")
+ if not isinstance(raw, dict):
+ return {}
+ out: dict[str, str] = {}
+ for key, value in raw.items():
+ if not str(key).startswith(ANNOTATION_PREFIX):
+ continue
+ if key not in KNOWN_ANNOTATIONS:
+ issue("error", f"unknown annotation {key!r}", label)
+ elif not isinstance(value, str):
+ issue("error", f"annotation {key!r} must be a string (Backstage rule)", label)
+ else:
+ out[key] = value
+ return out
+
+
+def _split(value: str | None, *, lower: bool = True) -> list[str]:
+ """A comma- or newline-separated annotation value as a list."""
+ if not value:
+ return []
+ parts = [p.strip() for p in re.split(r"[,\n]", value)]
+ return [p.lower() if lower else p for p in parts if p]
+
+
+def _text(value: Any) -> str | None:
+ if value is None:
+ return None
+ text = str(value).strip()
+ return text or None
+
+
+def owner_group_name(owner: str | None) -> str | None:
+ """The group name in a Backstage owner ref: ``group:default/payments`` is ``payments``."""
+ if not owner:
+ return None
+ kind, sep, rest = owner.partition(":")
+ if sep and kind.lower() != "group":
+ return None
+ ref = rest if sep else owner
+ return ref.rsplit("/", 1)[-1] or None
diff --git a/packages/core/src/repowise/core/components/check.py b/packages/core/src/repowise/core/components/check.py
new file mode 100644
index 000000000..2a3f3a60e
--- /dev/null
+++ b/packages/core/src/repowise/core/components/check.py
@@ -0,0 +1,103 @@
+"""Validate catalog files against the repository they describe.
+
+Parse problems come from :func:`.catalog.read_catalog` (unknown kinds, wrong
+apiVersion, unknown ``repowise.dev/*`` annotations, missing required spec
+fields). This adds what needs the file list: globs that do not compile or
+match no file, and files two declared components both claim (an error, or a
+warning when one component's files nest wholly inside the other's).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+from repowise.core.components.catalog import (
+ PATHS_ANNOTATION,
+ Catalog,
+ CatalogIssue,
+ owner_group_name,
+)
+from repowise.core.components.resolve import compile_globs
+
+
+def check_catalog(catalog: Catalog, file_paths: Iterable[str]) -> list[CatalogIssue]:
+ """Every issue in *catalog*, parse-time ones first."""
+ files = sorted(set(file_paths))
+ issues = list(catalog.issues)
+ matched_by: dict[str, set[str]] = {}
+ for comp in catalog.components:
+ label = f"Component:{comp.name}"
+ if not comp.paths:
+ issues.append(
+ CatalogIssue(
+ "warning",
+ f"no {PATHS_ANNOTATION}: covers files only if a derived component "
+ "has the same name",
+ comp.declared_in,
+ label,
+ )
+ )
+ continue
+ _spec, bad = compile_globs(comp.paths)
+ for glob in bad:
+ issues.append(
+ CatalogIssue("error", f"glob {glob!r} is not valid", comp.declared_in, label)
+ )
+ claimed = matched_by.setdefault(comp.name, set())
+ for glob in comp.paths:
+ if glob in bad:
+ continue
+ single, _ = compile_globs([glob])
+ matched = {f for f in files if single.match_file(f)}
+ if not matched:
+ issues.append(
+ CatalogIssue(
+ "error", f"glob {glob!r} matches no files", comp.declared_in, label
+ )
+ )
+ claimed |= matched
+
+ # Declaration order decides a shared file. A component nested wholly inside
+ # another is a deliberate carve-out (warning); a partial overlap is an error.
+ names = list(matched_by)
+ for i, first in enumerate(names):
+ for second in names[i + 1 :]:
+ a, b = matched_by[first], matched_by[second]
+ shared = a & b
+ if not shared:
+ continue
+ nested = a < b or b < a
+ issues.append(
+ CatalogIssue(
+ "warning" if nested else "error",
+ f"{len(shared)} file(s) claimed by both {first!r} and {second!r}"
+ f"{' (one nests inside the other)' if nested else ''}; "
+ f"{first!r} is declared first and wins",
+ None,
+ f"Component:{second}",
+ )
+ )
+
+ systems = {s.name for s in catalog.systems}
+ groups = {g.name for g in catalog.groups}
+ for comp in catalog.components:
+ if comp.system and systems and comp.system not in systems:
+ issues.append(
+ CatalogIssue(
+ "warning",
+ f"spec.system {comp.system!r} is not a declared System",
+ comp.declared_in,
+ f"Component:{comp.name}",
+ )
+ )
+ group = owner_group_name(comp.owner)
+ if group and groups and group not in groups:
+ issues.append(
+ CatalogIssue(
+ "warning",
+ f"spec.owner {comp.owner!r} is not a declared Group",
+ comp.declared_in,
+ f"Component:{comp.name}",
+ )
+ )
+ return issues
diff --git a/packages/core/src/repowise/core/components/resolve.py b/packages/core/src/repowise/core/components/resolve.py
new file mode 100644
index 000000000..97523cb8d
--- /dev/null
+++ b/packages/core/src/repowise/core/components/resolve.py
@@ -0,0 +1,156 @@
+"""Derived default components, and which component each file belongs to.
+
+With no catalog file, components are derived from what the index already
+knows, first source that yields any:
+
+1. workspace system-graph services for this repo (``service``),
+2. module pages of the structural wiki (``module``),
+3. top-level directories, the module-health bucket (``directory``).
+
+Declared components merge over derived ones:
+
+* A declared component claims every file its ``repowise.dev/paths`` globs
+ match. Where two declared components match a file, the first declared wins
+ (``repowise components check`` reports the overlap as an error).
+* A declared component with the same name as a derived one replaces it. With
+ no paths of its own it inherits the derived component's directory, so a
+ catalog can add an owner or criticality to a derived component without
+ restating its paths.
+* Every file no declared component claims goes to the deepest derived
+ directory containing it. A derived component left with no files is dropped.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable
+from dataclasses import dataclass, field, replace
+
+import pathspec
+from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
+
+from repowise.core.analysis.health.aggregation import module_label
+from repowise.core.components.catalog import Component
+
+
+@dataclass
+class ResolvedComponents:
+ #: Declared components first, in catalog order, then derived ones by name.
+ components: list[Component] = field(default_factory=list)
+ files: dict[str, list[str]] = field(default_factory=dict)
+ unassigned: list[str] = field(default_factory=list)
+
+ def get(self, name: str) -> Component | None:
+ wanted = name.lower()
+ return next((c for c in self.components if c.name.lower() == wanted), None)
+
+
+def compile_globs(globs: Iterable[str]) -> tuple[pathspec.PathSpec, list[str]]:
+ """One spec for *globs*, and the globs that do not compile (they match nothing)."""
+ good: list[str] = []
+ bad: list[str] = []
+ for glob in globs:
+ try:
+ pathspec.PathSpec.from_lines("gitwildmatch", [glob])
+ except (GitWildMatchPatternError, ValueError):
+ bad.append(glob)
+ else:
+ good.append(glob)
+ return pathspec.PathSpec.from_lines("gitwildmatch", good), bad
+
+
+def derive_from_services(services: Iterable[tuple[str, str]]) -> list[Component]:
+ """Components for ``(name, service_path)`` pairs from the system graph."""
+ return _derived(((path, name) for name, path in services), "service")
+
+
+def derive_from_modules(modules: Iterable[tuple[str, str | None]]) -> list[Component]:
+ """Components for ``(target_path, title)`` pairs of module pages."""
+ return _derived(modules, "module")
+
+
+def derive_from_directories(file_paths: Iterable[str]) -> list[Component]:
+ """One component per top-level directory; root-level files and dot-directories
+ (tool config such as ``.github``) stay unassigned."""
+ dirs = {module_label(p) for p in file_paths if "/" in p and not p.startswith(".")}
+ return _derived(((d, None) for d in sorted(dirs)), "directory")
+
+
+def _derived(roots: Iterable[tuple[str, str | None]], source: str) -> list[Component]:
+ cleaned: dict[str, str | None] = {}
+ for root, title in roots:
+ root = (root or "").replace("\\", "/").strip("/")
+ if root and root != ".":
+ cleaned.setdefault(root, title)
+ taken: set[str] = set()
+ out: list[Component] = []
+ # Shallow roots first, so a short name goes to the outer directory.
+ for root in sorted(cleaned, key=lambda r: (r.count("/"), r)):
+ name = _slug(root.rsplit("/", 1)[-1])
+ if not name or name.lower() in taken:
+ name = _slug(root)
+ if name.lower() in taken:
+ continue
+ taken.add(name.lower())
+ out.append(
+ Component(
+ name=name,
+ title=cleaned[root],
+ paths=(f"{root}/**",),
+ source=source,
+ root=root,
+ )
+ )
+ return out
+
+
+def _slug(text: str) -> str:
+ """A valid Backstage name made from a path."""
+ return re.sub(r"[^a-zA-Z0-9]+", "-", text).strip("-")[:63].strip("-")
+
+
+def resolve_components(
+ declared: list[Component], derived: list[Component], file_paths: Iterable[str]
+) -> ResolvedComponents:
+ """Merge *declared* over *derived* and assign every file to at most one component."""
+ by_name = {c.name.lower(): c for c in derived}
+ merged: list[Component] = []
+ for comp in declared:
+ twin = by_name.pop(comp.name.lower(), None)
+ if twin is not None and not comp.paths:
+ comp = replace(comp, root=twin.root)
+ merged.append(comp)
+ remaining = sorted(by_name.values(), key=lambda c: c.name.lower())
+
+ matchers = [(c, compile_globs(c.paths)[0] if c.paths else None) for c in merged]
+ files: dict[str, list[str]] = {c.name: [] for c in [*merged, *remaining]}
+ unassigned: list[str] = []
+ for path in sorted(set(file_paths)):
+ owner = next(
+ (c for c, spec in matchers if (spec and spec.match_file(path)) or _under(path, c.root)),
+ None,
+ ) or _deepest(path, remaining)
+ if owner is None:
+ unassigned.append(path)
+ else:
+ files[owner.name].append(path)
+
+ kept = merged + [c for c in remaining if files[c.name]]
+ return ResolvedComponents(
+ components=kept,
+ files={c.name: files[c.name] for c in kept},
+ unassigned=unassigned,
+ )
+
+
+def _under(path: str, root: str | None) -> bool:
+ return bool(root) and path.startswith(f"{root}/")
+
+
+def _deepest(path: str, derived: list[Component]) -> Component | None:
+ best: Component | None = None
+ for comp in derived:
+ deeper = best is None or len(comp.root or "") > len(best.root or "")
+ if deeper and _under(path, comp.root):
+ best = comp
+ return best
diff --git a/packages/core/src/repowise/core/components/rollup.py b/packages/core/src/repowise/core/components/rollup.py
new file mode 100644
index 000000000..87c2f9e85
--- /dev/null
+++ b/packages/core/src/repowise/core/components/rollup.py
@@ -0,0 +1,199 @@
+"""Per-component figures folded from per-file facts the index already holds.
+
+Sync, no I/O. Every figure carries ``basis`` (``measured``, ``inferred`` or
+``unavailable``) and a ``method`` saying what it rests on. The arithmetic is
+the existing one: health is :func:`module_rollups` over the component's files,
+the bus factor is the repository truck factor (:func:`build_people`) taken
+over the component's files. Health and dead code leave out files in languages
+:data:`LANGUAGE_GATES` holds back on that layer, the same registry the
+``ungated`` SQL filter reads, and say how many. No figure names a person.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping
+from typing import Any
+
+from repowise.core.analysis.finding_registry import gate_for
+from repowise.core.analysis.health.aggregation import module_rollups
+from repowise.core.analysis.health.rows import field
+from repowise.core.analysis.owners import people_resolver
+from repowise.core.stats_highlights import build_people
+
+_TOP_HOTSPOTS = 5
+#: Below this many owned files a truck factor is an anecdote, not a measure.
+_MIN_OWNED_FILES = 5
+
+
+def rollup_component(
+ files: Iterable[str],
+ *,
+ test_files: set[str],
+ git_rows: Mapping[str, Mapping[str, Any]],
+ health_rows: Mapping[str, Any],
+ dead_rows: Iterable[tuple[str, int | None]],
+ dead_code_ran: bool,
+) -> dict[str, Any]:
+ """Figures for one component from rows keyed by file path."""
+ paths = list(files)
+ production = [p for p in paths if p not in test_files]
+ return {
+ "file_count": len(paths),
+ "health": _health(paths, health_rows),
+ "hotspots": _hotspots(paths, git_rows),
+ "bus_factor": _bus_factor(paths, git_rows),
+ "test_reach": _test_reach(production, health_rows),
+ "dead_code": _dead_code(production, health_rows, dead_rows, dead_code_ran),
+ }
+
+
+def _unavailable(reason: str) -> dict[str, Any]:
+ return {"basis": "unavailable", "reason": reason}
+
+
+def _gated_note(count: int) -> str:
+ return f"; {count} file(s) in gated languages excluded" if count else ""
+
+
+def _health(paths: list[str], health_rows: Mapping[str, Any]) -> dict[str, Any]:
+ present = [p for p in paths if p in health_rows]
+ gated = {p for p in present if gate_for("health", p)}
+ rows = [
+ {
+ "file_path": p,
+ "score": field(health_rows[p], "score", None),
+ "nloc": field(health_rows[p], "nloc", 0),
+ "is_test": field(health_rows[p], "is_test", None),
+ "code_origin": field(health_rows[p], "code_origin", None),
+ "module": "component",
+ }
+ for p in present
+ if p not in gated
+ ]
+ rolled = module_rollups(rows)
+ if not rolled:
+ if gated:
+ out = _unavailable("every scored file is in a language health is held back on")
+ out["gated_files"] = len(gated)
+ return out
+ return _unavailable("no file in this component has a health score")
+ top = rolled[0]
+ return {
+ "average": top["average_health"],
+ "scored_files": top["file_count"],
+ "gated_files": len(gated),
+ "worst_path": top["worst_performer_path"],
+ "worst_score": top["worst_performer_score"],
+ "basis": "measured",
+ "method": "NLOC-weighted average of file health scores (1-10)" + _gated_note(len(gated)),
+ }
+
+
+def _hotspots(paths: list[str], git_rows: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
+ rows = [git_rows[p] for p in paths if p in git_rows]
+ if not rows:
+ return _unavailable("no git history indexed for this component's files")
+ hot = sorted(
+ (r for r in rows if r.get("is_hotspot")),
+ key=lambda r: (-(r.get("temporal_hotspot_score") or 0.0), r["file_path"]),
+ )
+ return {
+ "count": len(hot),
+ "top": [r["file_path"] for r in hot[:_TOP_HOTSPOTS]],
+ "basis": "measured",
+ "method": "files git history flags as hotspots (high recent churn)",
+ }
+
+
+def _bus_factor(paths: list[str], git_rows: Mapping[str, Mapping[str, Any]]) -> dict[str, Any]:
+ rows = [git_rows[p] for p in paths if p in git_rows]
+ people = build_people(rows)
+ if people["truck_factor"] is None:
+ return _unavailable("no file in this component has a known primary owner")
+ # Owned the way build_people counts it: a primary owner who is not a bot.
+ resolve = people_resolver(rows)
+ owned = 0
+ for m in rows:
+ name = m.get("primary_owner_name")
+ if name and not resolve.is_bot(resolve(name, m.get("primary_owner_email"))):
+ owned += 1
+ out: dict[str, Any] = {
+ "value": people["truck_factor"],
+ "owned_files": owned,
+ "file_count": len(paths),
+ "coverage": round(owned / len(paths), 2) if paths else 0.0,
+ "single_owner_files": people["single_owner_files"],
+ "basis": "measured",
+ "method": "fewest primary owners who together own over half the owned files",
+ }
+ if owned < _MIN_OWNED_FILES:
+ out["basis"] = "inferred"
+ out["note"] = f"only {owned} owned file(s); too few for a stable figure"
+ return out
+
+
+def _test_reach(production: list[str], health_rows: Mapping[str, Any]) -> dict[str, Any]:
+ rows = [health_rows[p] for p in production if p in health_rows]
+ if not rows:
+ return _unavailable("health analysis has not recorded test pairing for these files")
+ reached = sum(1 for r in rows if field(r, "has_test_file", False))
+ out: dict[str, Any] = {
+ "reached_files": reached,
+ "production_files": len(rows),
+ "share": round(reached / len(rows), 2),
+ "basis": "inferred",
+ "method": (
+ "a test imports the file (directly or through a re-export barrel) or is "
+ "named for it, the file holds inline tests, or a test reaches it in the "
+ "call graph"
+ ),
+ }
+ measured = [r for r in rows if field(r, "line_coverage_pct", None) is not None]
+ if measured:
+ weight = sum(max(int(field(r, "nloc", 0) or 0), 1) for r in measured)
+ pct = (
+ sum(
+ float(field(r, "line_coverage_pct")) * max(int(field(r, "nloc", 0) or 0), 1)
+ for r in measured
+ )
+ / weight
+ )
+ out["line_coverage"] = {
+ "pct": round(pct, 1),
+ "measured_files": len(measured),
+ "basis": "measured",
+ "method": "NLOC-weighted line coverage from ingested coverage reports",
+ }
+ return out
+
+
+def _dead_code(
+ production: list[str],
+ health_rows: Mapping[str, Any],
+ dead_rows: Iterable[tuple[str, int | None]],
+ ran: bool,
+) -> dict[str, Any]:
+ if not ran:
+ return _unavailable("dead-code analysis has not run for this repository")
+ gated = {p for p in production if gate_for("dead_code", p)}
+ served = [p for p in production if p not in gated]
+ if not served:
+ if not gated:
+ return _unavailable("the component has no production files")
+ out = _unavailable("every production file is in a language dead code is held back on")
+ out["gated_files"] = len(gated)
+ return out
+ in_served = set(served)
+ findings = [(p, lines) for p, lines in dead_rows if p in in_served]
+ nloc = sum(int(field(health_rows[p], "nloc", 0) or 0) for p in served if p in health_rows)
+ out = {
+ "findings": len(findings),
+ "files_with_findings": len({p for p, _ in findings}),
+ "lines": sum(int(lines or 0) for _, lines in findings),
+ "gated_files": len(gated),
+ "basis": "inferred",
+ "method": "static reachability findings" + _gated_note(len(gated)),
+ }
+ if nloc:
+ out["share_of_nloc"] = round(min(out["lines"] / nloc, 1.0), 3)
+ return out
diff --git a/packages/core/src/repowise/core/components/store.py b/packages/core/src/repowise/core/components/store.py
new file mode 100644
index 000000000..85e5e8e74
--- /dev/null
+++ b/packages/core/src/repowise/core/components/store.py
@@ -0,0 +1,213 @@
+"""Index reads behind components: the file list, derivation inputs, rollup rows."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+from sqlalchemy import select
+
+from repowise.core.analysis.finding_registry import excluded_types
+from repowise.core.components.catalog import Catalog, read_catalog
+from repowise.core.components.resolve import (
+ ResolvedComponents,
+ derive_from_directories,
+ derive_from_modules,
+ derive_from_services,
+ resolve_components,
+)
+from repowise.core.components.rollup import rollup_component
+from repowise.core.persistence.crud import code_file_rows
+from repowise.core.persistence.crud.repository import ANALYSIS_RAN_KEY
+from repowise.core.persistence.models import (
+ DeadCodeFinding,
+ GitMetadata,
+ GraphNode,
+ HealthFileMetric,
+ Page,
+ Repository,
+)
+
+
+@dataclass
+class RepoComponents:
+ catalog: Catalog
+ resolved: ResolvedComponents
+ test_files: set[str] = field(default_factory=set)
+
+
+def services_from_system_graph(
+ graph: dict[str, Any] | None, alias: str | None
+) -> list[tuple[str, str]]:
+ """``(name, service_path)`` for *alias*'s service nodes in a system-graph dict."""
+ if not graph or not alias:
+ return []
+ return [
+ (str(n.get("name") or n["service_path"]), str(n["service_path"]))
+ for n in graph.get("nodes", [])
+ if isinstance(n, dict) and n.get("repo") == alias and n.get("service_path")
+ ]
+
+
+def workspace_services(repo_root: Path) -> list[tuple[str, str]]:
+ """Services of *repo_root* from the enclosing workspace's system graph, if any."""
+ from repowise.core.workspace.config import WorkspaceConfig, find_workspace_root
+ from repowise.core.workspace.system_graph import load_system_graph
+
+ ws_root = find_workspace_root(repo_root)
+ if ws_root is None:
+ return []
+ try:
+ config = WorkspaceConfig.load(ws_root)
+ except Exception:
+ return []
+ root = repo_root.resolve()
+ alias = next((r.alias for r in config.repos if (ws_root / r.path).resolve() == root), None)
+ graph = load_system_graph(ws_root)
+ return services_from_system_graph(graph.to_dict() if graph else None, alias)
+
+
+async def load_repo_components(
+ session: Any,
+ repository_id: str,
+ repo_root: Path | str,
+ *,
+ services: Iterable[tuple[str, str]] = (),
+ is_excluded: Callable[[str], bool] | None = None,
+) -> RepoComponents:
+ """Declared and derived components for one indexed repository."""
+ catalog = read_catalog(repo_root)
+ rows = (
+ await session.execute(
+ select(GraphNode.node_id, GraphNode.is_test).where(
+ GraphNode.repository_id == repository_id, GraphNode.node_type == "file"
+ )
+ )
+ ).all()
+ rows = [r for r in rows if not (is_excluded and is_excluded(r[0]))]
+ files = [r[0] for r in rows]
+
+ derived = derive_from_services(services)
+ if not derived:
+ modules = (
+ await session.execute(
+ select(Page.target_path, Page.title).where(
+ Page.repository_id == repository_id,
+ Page.page_type == "module_page",
+ Page.freshness_status != "tombstone",
+ )
+ )
+ ).all()
+ derived = derive_from_modules((m[0], m[1]) for m in modules)
+ if not derived:
+ derived = derive_from_directories(files)
+ return RepoComponents(
+ catalog=catalog,
+ resolved=resolve_components(catalog.components, derived, files),
+ test_files={r[0] for r in rows if r[1]},
+ )
+
+
+_GIT_COLUMNS = (
+ GitMetadata.file_path,
+ GitMetadata.is_hotspot,
+ GitMetadata.temporal_hotspot_score,
+ GitMetadata.bus_factor,
+ GitMetadata.primary_owner_name,
+ GitMetadata.primary_owner_email,
+ GitMetadata.top_authors_json,
+)
+
+
+#: Bound parameters per ``IN`` list, well under SQLite's variable limit.
+_CHUNK = 500
+
+
+async def _rows_for(session: Any, query: Any, path_col: Any, files: list[str]) -> list[Any]:
+ """*query* narrowed to *files* in SQL, one chunked ``IN`` at a time."""
+ out: list[Any] = []
+ for i in range(0, len(files), _CHUNK):
+ out.extend((await session.execute(query.where(path_col.in_(files[i : i + _CHUNK])))).all())
+ return out
+
+
+def _stamped(settings_json: str | None, stage: str) -> bool:
+ """Whether *settings_json* carries the success stamp of *stage*."""
+ try:
+ stamps = json.loads(settings_json or "{}").get(ANALYSIS_RAN_KEY)
+ except (TypeError, ValueError, AttributeError):
+ return False # an unreadable settings blob proves nothing either way
+ return isinstance(stamps, dict) and bool(stamps.get(stage))
+
+
+async def dead_code_ran(session: Any, repository_id: str) -> bool:
+ """Whether dead-code analysis ever persisted a result for the repository.
+
+ The stage stamp proves a run that found nothing; finding rows cover indexes
+ written before stamps existed (the rule ``analysis_ran_at`` serves by).
+ """
+ raw = await session.scalar(
+ select(Repository.settings_json).where(Repository.id == repository_id)
+ )
+ if _stamped(raw, "dead_code"):
+ return True
+ found = await session.scalar(
+ select(DeadCodeFinding.id).where(DeadCodeFinding.repository_id == repository_id).limit(1)
+ )
+ return found is not None
+
+
+async def component_rollups(
+ session: Any,
+ repository_id: str,
+ files_by_component: dict[str, list[str]],
+ test_files: set[str],
+) -> dict[str, dict[str, Any]]:
+ """Rollup figures per component name, from one read of each fact table.
+
+ The union of every component's files is read once per table (chunked
+ ``IN``), and the dead-code run status once, whatever the batch size; the
+ rows are then partitioned by file, so each component folds only its own.
+ """
+ files = sorted({f for paths in files_by_component.values() for f in paths})
+ git = await _rows_for(
+ session,
+ select(*_GIT_COLUMNS).where(code_file_rows(repository_id)),
+ GitMetadata.file_path,
+ files,
+ )
+ health = await _rows_for(
+ session,
+ select(HealthFileMetric).where(HealthFileMetric.repository_id == repository_id),
+ HealthFileMetric.file_path,
+ files,
+ )
+ dead = await _rows_for(
+ session,
+ select(DeadCodeFinding.file_path, DeadCodeFinding.lines).where(
+ DeadCodeFinding.repository_id == repository_id,
+ DeadCodeFinding.kind.not_in(excluded_types()),
+ ),
+ DeadCodeFinding.file_path,
+ files,
+ )
+ ran = await dead_code_ran(session, repository_id) if files else False
+ git_rows = {r.file_path: dict(r._mapping) for r in git}
+ health_rows = {r[0].file_path: r[0] for r in health}
+ dead_by_file: dict[str, list[tuple[str, int | None]]] = {}
+ for path, lines in dead:
+ dead_by_file.setdefault(path, []).append((path, lines))
+ return {
+ name: rollup_component(
+ paths,
+ test_files=test_files,
+ git_rows=git_rows,
+ health_rows=health_rows,
+ dead_rows=[row for p in paths for row in dead_by_file.get(p, ())],
+ dead_code_ran=ran,
+ )
+ for name, paths in files_by_component.items()
+ }
diff --git a/packages/server/src/repowise/server/mcp_server/_components.py b/packages/server/src/repowise/server/mcp_server/_components.py
new file mode 100644
index 000000000..ab48e8a6b
--- /dev/null
+++ b/packages/server/src/repowise/server/mcp_server/_components.py
@@ -0,0 +1,206 @@
+"""Component targets for get_context and the component list for get_overview.
+
+Both are opt-in: a ``component:<name>`` target, or ``include=["components"]``.
+Neither runs on a default call. The resolved components are cached per repo,
+index state, catalog file times, workspace graph and exclusion rules, so a
+batch of component targets and a later overview resolve them once.
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+from repowise.core.components.catalog import CATALOG_FILES, Component
+from repowise.core.components.store import (
+ RepoComponents,
+ component_rollups,
+ load_repo_components,
+ services_from_system_graph,
+)
+from repowise.server.mcp_server import _state
+from repowise.server.mcp_server._budget import OmissionCollector
+from repowise.server.mcp_server._helpers import _is_workspace_mode, is_excluded
+from repowise.server.mcp_server._index_state import index_state_key
+
+COMPONENT_PREFIX = "component:"
+_LIST_CAP = 25
+_SAMPLE_FILES = 10
+_FACTS = ("health", "hotspots", "bus_factor", "test_reach", "dead_code")
+
+_CACHE: dict[tuple, RepoComponents] = {}
+_CACHE_LIMIT = 16
+
+
+def reset_cache() -> None:
+ """Drop every cached resolution. For tests and an in-process re-index."""
+ _CACHE.clear()
+
+
+def is_component_target(target: str) -> bool:
+ return target.startswith(COMPONENT_PREFIX)
+
+
+def _catalog_times(repo_root: Any) -> tuple[int, ...]:
+ times = []
+ for rel in CATALOG_FILES:
+ try:
+ times.append(os.stat(os.path.join(str(repo_root), rel)).st_mtime_ns)
+ except OSError:
+ times.append(0)
+ return tuple(times)
+
+
+async def _load(
+ session: Any, repository: Any, repo_root: Any, alias: str | None, exclude_spec: Any
+) -> RepoComponents:
+ graph = None
+ enricher = _state._cross_repo_enricher
+ if enricher is not None and _is_workspace_mode() and enricher.has_system_graph:
+ graph = enricher.get_system_graph()
+ key = (
+ repository.id,
+ index_state_key(repository),
+ str(repo_root),
+ _catalog_times(repo_root),
+ alias,
+ id(graph),
+ id(exclude_spec),
+ )
+ cached = _CACHE.get(key)
+ if cached is not None:
+ return cached
+ found = await load_repo_components(
+ session,
+ repository.id,
+ repo_root,
+ services=services_from_system_graph(graph, alias),
+ is_excluded=(lambda p: is_excluded(p, exclude_spec)) if exclude_spec else None,
+ )
+ if len(_CACHE) >= _CACHE_LIMIT:
+ _CACHE.clear()
+ _CACHE[key] = found
+ return found
+
+
+def _describe(comp: Component) -> dict[str, Any]:
+ """The component's identity and declared context; empty fields left out."""
+ out: dict[str, Any] = {"name": comp.name}
+ if comp.declared:
+ out["source"] = "declared"
+ out["declared_in"] = comp.declared_in
+ else:
+ out["source"] = "derived"
+ out["derived_from"] = comp.source
+ fields = {
+ "title": comp.title,
+ "description": comp.description,
+ "component_type": comp.type,
+ "lifecycle": comp.lifecycle,
+ "owner": comp.owner,
+ "system": comp.system,
+ "criticality": comp.criticality,
+ "tags": list(comp.tags),
+ "capability": comp.capability,
+ "paths": list(comp.paths) or ([f"{comp.root}/**"] if comp.root else []),
+ }
+ out.update((k, v) for k, v in fields.items() if v)
+ return out
+
+
+def _empty_note(comp: Component) -> str:
+ if not comp.paths and not comp.root:
+ return (
+ "Declares no repowise.dev/paths and no derived component has this name, "
+ "so it claims no files."
+ )
+ return "Its paths match no indexed file that an earlier component has not claimed."
+
+
+async def component_cards(
+ session: Any,
+ repository: Any,
+ targets: list[str],
+ *,
+ repo_root: Any,
+ alias: str | None,
+ exclude_spec: Any,
+) -> dict[str, dict[str, Any]]:
+ """get_context cards for ``component:<name>`` *targets*: components resolved
+ once and each fact table read once for the whole batch, in turn on *session*."""
+ found = await _load(session, repository, repo_root, alias, exclude_spec)
+ wanted = {t: found.resolved.get(t[len(COMPONENT_PREFIX) :].strip()) for t in targets}
+ to_fold = {
+ c.name: found.resolved.files[c.name]
+ for c in wanted.values()
+ if c is not None and found.resolved.files[c.name]
+ }
+ rollups = (
+ await component_rollups(session, repository.id, to_fold, found.test_files)
+ if to_fold
+ else {}
+ )
+ cards: dict[str, dict[str, Any]] = {}
+ for target, comp in wanted.items():
+ name = target[len(COMPONENT_PREFIX) :].strip()
+ if comp is None:
+ cards[target] = {
+ "target": target,
+ "error": f"No component named {name!r}.",
+ "available": [c.name for c in found.resolved.components[:_LIST_CAP]],
+ }
+ continue
+ files = found.resolved.files[comp.name]
+ card: dict[str, Any] = {"target": target, "type": "component", **_describe(comp)}
+ card["file_count"] = len(files)
+ if not files:
+ card["note"] = _empty_note(comp)
+ card["facts"] = {
+ k: {"basis": "unavailable", "reason": "the component claims no files"}
+ for k in _FACTS
+ }
+ else:
+ facts = dict(rollups[comp.name])
+ facts.pop("file_count")
+ card["sample_files"] = files[:_SAMPLE_FILES]
+ card["facts"] = facts
+ cards[target] = card
+ return cards
+
+
+async def component_list(
+ session: Any,
+ repository: Any,
+ *,
+ repo_root: Any,
+ alias: str | None,
+ exclude_spec: Any,
+ collector: OmissionCollector,
+) -> dict[str, Any]:
+ """The get_overview ``components`` block: declared first, then derived by size."""
+ found = await _load(session, repository, repo_root, alias, exclude_spec)
+ files = found.resolved.files
+ declared = [c for c in found.resolved.components if c.declared]
+ derived = sorted(
+ (c for c in found.resolved.components if not c.declared),
+ key=lambda c: (-len(files[c.name]), c.name),
+ )
+ rows = []
+ for comp in [*declared, *derived]:
+ row = _describe(comp)
+ for key in ("description", "paths", "declared_in", "title", "capability"):
+ row.pop(key, None)
+ row["file_count"] = len(files[comp.name])
+ rows.append(row)
+ if len(rows) > _LIST_CAP:
+ collector.add(
+ f"components beyond cap={_LIST_CAP} ({len(rows) - _LIST_CAP} dropped)",
+ "\n".join(f"{r['name']}: {r['file_count']} files" for r in rows[_LIST_CAP:]),
+ )
+ block: dict[str, Any] = {"items": rows[:_LIST_CAP], "total": len(rows)}
+ if found.resolved.unassigned:
+ block["unassigned_files"] = len(found.resolved.unassigned)
+ errors = len(found.catalog.errors)
+ if errors:
+ block["catalog_errors"] = errors
+ return block
diff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
index ef89a1de3..4293fa316 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_context/context.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_context/context.py
@@ -55,6 +55,7 @@ from repowise.core.registry import ToolRecipe
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server import _state
from repowise.server.mcp_server._budget import OmissionCollector
+from repowise.server.mcp_server._components import component_cards, is_component_target
from repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodes
from repowise.server.mcp_server._helpers import (
_get_exclude_spec,
@@ -138,7 +139,7 @@ async def get_context(
Include-gated blocks are projections, not omissions.
Args:
- targets: file paths, module paths, or "path::Symbol" ids.
+ targets: paths, "path::Symbol" ids, or "component:<name>".
include: opt-in blocks: full_doc | ownership | last_change | callers
| callees | references | metrics | community | decisions | skeleton
| skeleton+ | health | doc_drift (docs naming this file)
@@ -190,7 +191,12 @@ async def get_context(
# batch. Any exception is converted below into a per-target error
# entry that carries "target", so the comprehension keyed on target
# below never KeyErrors.
- raw_results = await asyncio.gather(
+ # Component targets resolve first, in turn on this session and from one
+ # component load, so they never share the session with the gather.
+ cards = await _component_cards(
+ session, repository, [t for t in targets if is_component_target(t)], ctx, exclude_spec
+ )
+ gathered = await asyncio.gather(
*[
_resolve_one_target(
session,
@@ -204,9 +210,12 @@ async def get_context(
as_of_ts=as_of_ts,
)
for t in targets
+ if not is_component_target(t)
],
return_exceptions=True,
)
+ rest = iter(gathered)
+ raw_results = [cards[t] if is_component_target(t) else next(rest) for t in targets]
# One batched read for every target that asked for it, on the session
# they share, and a no-op for every call that did not. Deliberately
@@ -310,3 +319,22 @@ async def get_context(
attach_ignored_arguments(response, ignored)
collector.attach(response)
return response
+
+
+async def _component_cards(
+ session: Any, repository: Any, targets: list[str], ctx: Any, exclude_spec: Any
+) -> dict[str, Any]:
+ """Cards for the batch's component targets; a failure becomes each one's error."""
+ if not targets:
+ return {}
+ try:
+ return await component_cards(
+ session,
+ repository,
+ targets,
+ repo_root=ctx.path,
+ alias=ctx.alias,
+ exclude_spec=exclude_spec,
+ )
+ except Exception as exc:
+ return {t: exc for t in targets}
diff --git a/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py b/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py
index c9580155c..e0fd943cb 100644
--- a/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py
+++ b/packages/server/src/repowise/server/mcp_server/tool_overview/tool.py
@@ -16,6 +16,7 @@ from repowise.core.persistence.models import GitMetadata
from repowise.core.registry import mcp_tool_registry as mcp
from repowise.server.mcp_server import _state
from repowise.server.mcp_server._budget import OmissionCollector
+from repowise.server.mcp_server._components import component_list
from repowise.server.mcp_server._helpers import (
_get_exclude_spec,
_get_repo,
@@ -65,8 +66,7 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
Returns the overview summary, key modules, entry points, architecture
layers and package dependencies, code health, repo-wide git health, and
``next_actions`` (top work for the week and quarter).
- Skip this on subsequent calls — once you have the map, jump straight to
- ``get_context`` / ``get_answer``.
+ Skip it on later calls; go straight to ``get_context`` / ``get_answer``.
Compact by default: ``content_md`` carries only the overview essay's summary
section, and the outline, onboarding, ownership and graph blocks ship only
@@ -83,7 +83,7 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
- ``repo="<alias>"`` targets one specific repo.
Args:
- repo: Repository alias, path, or ID. Use ``"all"`` for workspace overview.
+ repo: Repository alias, path, or ID, or ``"all"``.
include: Opt-in extras, any combination of:
``"content"`` — the full overview essay instead of its summary.
``"outline"`` — the stored wiki page tree, two rungs deep.
@@ -91,6 +91,7 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
``"decisions"`` — ``key_decisions``; ``get_why`` is richer.
``"graph"`` — ``community_summary``, code-community clusters.
``"ownership"`` — ``knowledge_map``: top 3 owners by files owned.
+ ``"components"`` — component list with file counts.
"""
if repo == "all":
return await _workspace_overview()
@@ -102,9 +103,19 @@ async def get_overview(repo: str | None = None, include: list[str] | None = None
collector = OmissionCollector("get_overview", repo_root=ctx.path)
async with get_session(ctx.session_factory) as session:
repository = await _get_repo(session)
+ want = set(include or [])
result = await _repo_overview(
- session, ctx.session_factory, repository, exclude_spec, set(include or []), collector
+ session, ctx.session_factory, repository, exclude_spec, want, collector
)
+ if "components" in want:
+ result["components"] = await component_list(
+ session,
+ repository,
+ repo_root=ctx.path,
+ alias=ctx.alias,
+ exclude_spec=exclude_spec,
+ collector=collector,
+ )
# Made once per session, so this is where the full scope that every
# other response's compact projection points at is worth its bytes.
diff --git a/tests/conftest.py b/tests/conftest.py
index 6516bcb8b..beb0382b9 100644
--- a/tests/conftest.py
+++ b/tests/conftest.py
@@ -118,7 +118,7 @@ def _fresh_per_index_caches():
so every test's index looks the same to the cache key. Looked up in
``sys.modules`` so a test that never loads the server pays nothing.
"""
- for name in ("_basis", "_scope", "_graph_files", "tool_overview.graph"):
+ for name in ("_basis", "_scope", "_graph_files", "tool_overview.graph", "_components"):
module = sys.modules.get(f"repowise.server.mcp_server.{name}")
if module is not None:
module.reset_cache()
diff --git a/tests/unit/cli/test_components_cmd.py b/tests/unit/cli/test_components_cmd.py
new file mode 100644
index 000000000..c162b647d
--- /dev/null
+++ b/tests/unit/cli/test_components_cmd.py
@@ -0,0 +1,92 @@
+"""``repowise components check`` and ``list`` on a repository with no index."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import pytest
+from click.testing import CliRunner
+
+from repowise.cli.main import cli
+
+_CATALOG = """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: api
+ annotations:
+ repowise.dev/paths: src/api/**
+ repowise.dev/criticality: high
+ repowise.dev/tags: pci
+spec: {type: service, lifecycle: production, owner: group:default/payments}
+"""
+
+
+def repo(tmp_path: Path) -> Path:
+ for rel in ("src/api/routes.py", "src/db/models.py", "README.md"):
+ path = tmp_path / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text("x = 1\n", encoding="utf-8")
+ return tmp_path
+
+
+def _invoke(args: list[str]) -> object:
+ return CliRunner().invoke(cli, args, catch_exceptions=False)
+
+
+def _write_catalog(repo: Path, text: str) -> None:
+ (repo / ".repowise").mkdir(exist_ok=True)
+ (repo / ".repowise" / "components.yaml").write_text(text, encoding="utf-8")
+
+
+def test_check_with_no_catalog_passes(repo):
+ result = _invoke(["components", "check", "--path", str(repo)])
+ assert result.exit_code == 0
+ assert "No catalog file found" in result.output
+
+
+def test_check_passes_a_valid_catalog(repo):
+ _write_catalog(repo, _CATALOG)
+ result = _invoke(["components", "check", "--path", str(repo), "--format", "json"])
+ assert result.exit_code == 0, result.output
+ data = json.loads(result.output)
+ assert data["errors"] == 0 and data["components"] == 1
+ assert data["sources"] == [".repowise/components.yaml"]
+
+
+def test_check_exits_non_zero_on_errors(repo):
+ _write_catalog(
+ repo,
+ _CATALOG.replace("src/api/**", "src/gone/**")
+ + "---\napiVersion: backstage.io/v1alpha1\nkind: Widget\nmetadata: {name: w}\n",
+ )
+ result = _invoke(["components", "check", "--path", str(repo), "--format", "json"])
+ assert result.exit_code == 1
+ messages = [i["message"] for i in json.loads(result.output)["issues"]]
+ assert "glob 'src/gone/**' matches no files" in messages
+ assert any(m.startswith("unknown kind 'Widget'") for m in messages)
+
+ table = _invoke(["components", "check", "--path", str(repo)])
+ assert table.exit_code == 1
+ assert "matches no files" in table.output
+
+
+def test_list_without_an_index_uses_directories_and_the_catalog(repo):
+ _write_catalog(repo, _CATALOG)
+ result = _invoke(["components", "list", "--path", str(repo), "--format", "json"])
+ assert result.exit_code == 0, result.output
+ data = json.loads(result.output)
+ rows = {r["name"]: r for r in data["components"]}
+ assert rows["api"] == {
+ "name": "api",
+ "source": "declared",
+ "files": 1,
+ "owner": "group:default/payments",
+ "criticality": "high",
+ "tags": ["pci"],
+ }
+ # The derived "src" keeps the file the declared component did not claim.
+ assert rows["src"]["source"] == "directory" and rows["src"]["files"] == 1
+ assert data["catalog_errors"] == 0
diff --git a/tests/unit/cli/test_lazy_commands.py b/tests/unit/cli/test_lazy_commands.py
index 60fcf56b1..650f62b14 100644
--- a/tests/unit/cli/test_lazy_commands.py
+++ b/tests/unit/cli/test_lazy_commands.py
@@ -33,7 +33,8 @@ from repowise.core.registry import CLIRegistry, LazyCommand
#: command is meant to require editing it.
_EXPECTED_NAMES = frozenset(
{
- "agents", "ask", "augment", "config", "context", "corrections", "costs", "coverage",
+ "agents", "ask", "augment", "components", "config", "context", "corrections", "costs",
+ "coverage",
"dead-code", "decision", "delete", "distill", "doc-drift", "doctor",
"expand",
"export", "generate", "generate-claude-md", "health", "hook",
diff --git a/tests/unit/core/test_components_catalog.py b/tests/unit/core/test_components_catalog.py
new file mode 100644
index 000000000..50648b570
--- /dev/null
+++ b/tests/unit/core/test_components_catalog.py
@@ -0,0 +1,266 @@
+"""Backstage-shaped catalog files: parsing, merging the two files, and check."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from repowise.core.components import check_catalog, read_catalog
+from repowise.core.components.catalog import owner_group_name
+
+_COMPONENTS = """\
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata:
+ name: checkout
+spec:
+ owner: group:default/payments
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: payments-api
+ title: Payments API
+ description: Card authorisation and refunds.
+ tags: [python, customer-facing]
+ annotations:
+ repowise.dev/paths: services/payments/**, libs/money/**
+ repowise.dev/criticality: Critical
+ repowise.dev/tags: pci, regulated
+ repowise.dev/capability: Take payments
+ backstage.io/techdocs-ref: dir:.
+spec:
+ type: service
+ lifecycle: production
+ owner: group:default/payments
+ system: checkout
+---
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata:
+ name: payments
+spec:
+ type: team
+ profile:
+ displayName: Payments Team
+ children: []
+ members: [alice, bob]
+---
+apiVersion: backstage.io/v1alpha1
+kind: API
+metadata:
+ name: payments-rest
+spec:
+ type: openapi
+"""
+
+
+def _write(root: Path, rel: str, text: str) -> None:
+ path = root / rel
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(text, encoding="utf-8")
+
+
+def test_multi_document_file_reads_components_systems_and_groups(tmp_path):
+ _write(tmp_path, ".repowise/components.yaml", _COMPONENTS)
+ catalog = read_catalog(tmp_path)
+
+ assert catalog.sources == [".repowise/components.yaml"]
+ assert catalog.issues == []
+ (comp,) = catalog.components
+ assert comp.name == "payments-api"
+ assert comp.title == "Payments API"
+ assert comp.paths == ("services/payments/**", "libs/money/**")
+ assert comp.criticality == "critical"
+ # metadata.tags and repowise.dev/tags fold into one list, deduplicated.
+ assert comp.tags == ("python", "customer-facing", "pci", "regulated")
+ assert comp.capability == "Take payments"
+ assert (comp.type, comp.lifecycle, comp.system) == ("service", "production", "checkout")
+ assert comp.declared and comp.declared_in == ".repowise/components.yaml"
+ assert [s.name for s in catalog.systems] == ["checkout"]
+ (group,) = catalog.groups
+ assert (group.name, group.title, group.type) == ("payments", "Payments Team", "team")
+ # Membership is never read: Group carries no member field at all.
+ assert not hasattr(group, "members")
+
+
+def test_catalog_info_is_read_and_components_yaml_wins_on_a_duplicate(tmp_path):
+ _write(tmp_path, ".repowise/components.yaml", _COMPONENTS)
+ _write(
+ tmp_path,
+ "catalog-info.yaml",
+ """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: payments-api
+ annotations:
+ repowise.dev/criticality: low
+spec: {type: service, lifecycle: production, owner: payments}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: web
+spec: {type: website, lifecycle: production, owner: frontend}
+""",
+ )
+ catalog = read_catalog(tmp_path)
+
+ assert catalog.sources == [".repowise/components.yaml", "catalog-info.yaml"]
+ by_name = {c.name: c for c in catalog.components}
+ assert by_name["payments-api"].criticality == "critical"
+ assert by_name["web"].declared_in == "catalog-info.yaml"
+ (dup,) = catalog.issues
+ assert dup.severity == "warning" and dup.entity == "Component:payments-api"
+
+
+def test_parse_errors_name_the_entity_and_drop_unidentifiable_ones(tmp_path):
+ _write(
+ tmp_path,
+ "catalog-info.yaml",
+ """\
+apiVersion: backstage.io/v1alpha1
+kind: Service
+metadata: {name: odd}
+---
+apiVersion: backstage.io/v1beta1
+kind: Component
+metadata: {name: old}
+spec: {type: service, lifecycle: production, owner: x}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: typo
+ annotations:
+ repowise.dev/path: src/**
+ repowise.dev/criticality: urgent
+ repowise.dev/tags: [pci]
+spec: {type: service}
+""",
+ )
+ catalog = read_catalog(tmp_path)
+ messages = {(i.entity, i.message) for i in catalog.errors}
+
+ assert [c.name for c in catalog.components] == ["typo"]
+ assert any(e == "Service:odd" and "unknown kind" in m for e, m in messages)
+ assert any(e == "Component:old" and "apiVersion" in m for e, m in messages)
+ assert any("unknown annotation 'repowise.dev/path'" in m for _, m in messages)
+ assert any("repowise.dev/criticality must be one of" in m for _, m in messages)
+ assert any("must be a string" in m for _, m in messages)
+ assert {m for e, m in messages if e == "Component:typo" and m.startswith("spec.")} == {
+ "spec.lifecycle is required for a Component",
+ "spec.owner is required for a Component",
+ }
+
+
+def test_invalid_yaml_is_one_error_not_an_exception(tmp_path):
+ _write(tmp_path, "catalog-info.yaml", "kind: [unclosed\n")
+ catalog = read_catalog(tmp_path)
+ assert catalog.components == []
+ assert catalog.errors[0].message.startswith("invalid YAML")
+
+
+def test_check_reports_globs_matching_nothing_and_overlaps(tmp_path):
+ _write(
+ tmp_path,
+ ".repowise/components.yaml",
+ """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: api
+ annotations: {repowise.dev/paths: "src/api/**, src/ghost/**"}
+spec: {type: service, lifecycle: production, owner: platform, system: nowhere}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: everything
+ annotations: {repowise.dev/paths: "src/**"}
+spec: {type: service, lifecycle: production, owner: group:default/ghosts}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata: {name: pathless}
+spec: {type: library, lifecycle: production, owner: platform}
+---
+apiVersion: backstage.io/v1alpha1
+kind: System
+metadata: {name: shop}
+spec: {owner: platform}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Group
+metadata: {name: platform}
+spec: {type: team, children: []}
+""",
+ )
+ catalog = read_catalog(tmp_path)
+ issues = check_catalog(catalog, ["src/api/a.py", "src/api/b.py", "src/web/c.py"])
+ by_message = {i.message: i for i in issues}
+
+ assert by_message["glob 'src/ghost/**' matches no files"].severity == "error"
+ # "api" nests wholly inside "everything": a deliberate carve-out, so a warning.
+ nested = by_message[
+ "2 file(s) claimed by both 'api' and 'everything' (one nests inside the other); "
+ "'api' is declared first and wins"
+ ]
+ assert nested.severity == "warning"
+ warnings = {i.message for i in issues if i.severity == "warning"}
+ assert "spec.system 'nowhere' is not a declared System" in warnings
+ assert "spec.owner 'group:default/ghosts' is not a declared Group" in warnings
+ assert any(m.startswith("no repowise.dev/paths") for m in warnings)
+
+
+def test_owner_group_name_reads_backstage_refs():
+ assert owner_group_name("group:default/payments") == "payments"
+ assert owner_group_name("payments") == "payments"
+ assert owner_group_name("user:default/alice") is None
+ assert owner_group_name(None) is None
+
+
+def test_the_documented_example_parses_cleanly(tmp_path):
+ example = Path(__file__).parents[3] / "examples" / "components" / "components.yaml"
+ _write(tmp_path, "catalog-info.yaml", example.read_text(encoding="utf-8"))
+ catalog = read_catalog(tmp_path)
+ assert catalog.issues == []
+ assert [c.name for c in catalog.components] == ["payments-api", "web"]
+
+
+def _component(name: str, globs: str) -> str:
+ return (
+ "apiVersion: backstage.io/v1alpha1\nkind: Component\n"
+ f"metadata:\n name: {name}\n annotations: {{repowise.dev/paths: \"{globs}\"}}\n"
+ "spec: {type: service, lifecycle: production, owner: platform}\n"
+ )
+
+
+def test_a_partial_overlap_is_an_error(tmp_path):
+ _write(
+ tmp_path,
+ "catalog-info.yaml",
+ _component("left", "src/a/**, src/shared/**") + "---\n" + _component("right", "src/b/**, src/shared/**"),
+ )
+ files = ["src/a/x.py", "src/b/y.py", "src/shared/z.py"]
+ (issue,) = [i for i in check_catalog(read_catalog(tmp_path), files) if "claimed" in i.message]
+ assert issue.severity == "error"
+ assert issue.message == "1 file(s) claimed by both 'left' and 'right'; 'left' is declared first and wins"
+
+
+def test_globs_are_case_sensitive(tmp_path):
+ _write(tmp_path, "catalog-info.yaml", _component("api", "SRC/**"))
+ messages = [i.message for i in check_catalog(read_catalog(tmp_path), ["src/a.py"])]
+ assert "glob 'SRC/**' matches no files" in messages
+
+
+def test_an_oversized_catalog_is_refused_unparsed(tmp_path, monkeypatch):
+ from repowise.core.components import catalog as catalog_mod
+
+ monkeypatch.setattr(catalog_mod, "MAX_CATALOG_BYTES", 100)
+ _write(tmp_path, "catalog-info.yaml", _component("api", "src/**") + "# pad\n" * 40)
+ catalog = read_catalog(tmp_path)
+ assert catalog.components == []
+ (issue,) = catalog.issues
+ assert issue.severity == "error" and issue.message == "larger than 100 bytes; not read"
+ assert issue.source == "catalog-info.yaml"
diff --git a/tests/unit/core/test_components_resolve.py b/tests/unit/core/test_components_resolve.py
new file mode 100644
index 000000000..efccf1b8c
--- /dev/null
+++ b/tests/unit/core/test_components_resolve.py
@@ -0,0 +1,253 @@
+"""Derived components, the declared-over-derived merge, and rollup arithmetic."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+from repowise.core.components.catalog import Component
+from repowise.core.components.resolve import (
+ derive_from_directories,
+ derive_from_modules,
+ derive_from_services,
+ resolve_components,
+)
+from repowise.core.components.rollup import rollup_component
+from repowise.core.components.store import services_from_system_graph
+
+FILES = [
+ "README.md",
+ "src/api/routes.py",
+ "src/api/v2/routes.py",
+ "src/db/models.py",
+ "tools/gen.py",
+]
+
+
+def test_directories_are_the_fallback_and_root_files_stay_unassigned():
+ resolved = resolve_components([], derive_from_directories(FILES), FILES)
+
+ assert [c.name for c in resolved.components] == ["src", "tools"]
+ assert all(c.source == "directory" for c in resolved.components)
+ assert resolved.files["tools"] == ["tools/gen.py"]
+ assert resolved.unassigned == ["README.md"]
+
+
+def test_module_pages_assign_each_file_to_the_deepest_module():
+ derived = derive_from_modules(
+ [("src/api", "API"), ("src/api/v2", "API v2"), ("src/db", None), ("src/db", "dup")]
+ )
+ resolved = resolve_components([], derived, FILES)
+
+ assert {c.name: c.title for c in resolved.components} == {
+ "api": "API",
+ "db": None,
+ "v2": "API v2",
+ }
+ assert resolved.files == {
+ "api": ["src/api/routes.py"],
+ "db": ["src/db/models.py"],
+ "v2": ["src/api/v2/routes.py"],
+ }
+ assert resolved.unassigned == ["README.md", "tools/gen.py"]
+
+
+def test_colliding_names_fall_back_to_the_full_path():
+ derived = derive_from_modules([("a/core", None), ("b/core", None)])
+ assert [c.name for c in derived] == ["core", "b-core"]
+
+
+def test_services_come_from_the_repo_s_own_system_graph_nodes():
+ graph = {
+ "nodes": [
+ {"repo": "shop", "service_path": "services/cart", "name": "cart"},
+ {"repo": "shop", "service_path": None, "name": "shop"},
+ {"repo": "other", "service_path": "svc", "name": "svc"},
+ ]
+ }
+ services = services_from_system_graph(graph, "shop")
+ assert services == [("cart", "services/cart")]
+ (comp,) = derive_from_services(services)
+ assert (comp.name, comp.source, comp.root) == ("cart", "service", "services/cart")
+ assert services_from_system_graph(None, "shop") == []
+
+
+def test_declared_paths_claim_first_and_derived_keep_the_rest():
+ declared = [
+ Component(name="routing", paths=("**/routes.py",)),
+ Component(name="db", owner="data", criticality="high"), # no paths: inherits
+ ]
+ derived = derive_from_modules([("src/api", None), ("src/db", None)])
+ resolved = resolve_components(declared, derived, FILES)
+
+ names = [c.name for c in resolved.components]
+ # Declared first in catalog order; "api" lost every file, so it is dropped.
+ assert names == ["routing", "db"]
+ assert resolved.files["routing"] == ["src/api/routes.py", "src/api/v2/routes.py"]
+ db = resolved.get("DB")
+ assert db is not None and db.declared and db.root == "src/db" and db.owner == "data"
+ assert resolved.files["db"] == ["src/db/models.py"]
+
+
+def test_first_declared_wins_an_overlap():
+ declared = [
+ Component(name="one", paths=("src/**",)),
+ Component(name="two", paths=("src/db/**",)),
+ ]
+ resolved = resolve_components(declared, [], FILES)
+ assert resolved.files["two"] == []
+ assert "src/db/models.py" in resolved.files["one"]
+
+
+def test_rollup_folds_existing_per_file_facts():
+ files = ["a.py", "b.py", "c.py", "test_a.py"]
+ git_rows = {
+ "a.py": {
+ "file_path": "a.py",
+ "is_hotspot": True,
+ "temporal_hotspot_score": 0.9,
+ "bus_factor": 1,
+ "primary_owner_name": "Ann",
+ "primary_owner_email": "[email protected]",
+ "top_authors_json": json.dumps([{"name": "Ann", "email": "[email protected]", "count": 3}]),
+ },
+ "b.py": {
+ "file_path": "b.py",
+ "is_hotspot": True,
+ "temporal_hotspot_score": 0.5,
+ "bus_factor": 2,
+ "primary_owner_name": "Ann",
+ "primary_owner_email": "[email protected]",
+ "top_authors_json": "[]",
+ },
+ "c.py": {
+ "file_path": "c.py",
+ "is_hotspot": False,
+ "temporal_hotspot_score": 0.1,
+ "bus_factor": 1,
+ "primary_owner_name": "Ben",
+ "primary_owner_email": "[email protected]",
+ "top_authors_json": "[]",
+ },
+ }
+ health_rows = {
+ "a.py": {"score": 4.0, "nloc": 300, "has_test_file": True, "line_coverage_pct": 50.0},
+ "b.py": {"score": 10.0, "nloc": 100, "has_test_file": False, "line_coverage_pct": None},
+ "c.py": {"score": None, "nloc": 100, "has_test_file": False, "line_coverage_pct": None},
+ "test_a.py": {"score": 9.0, "nloc": 50, "has_test_file": True, "is_test": True},
+ }
+ dead_rows = [("b.py", 20), ("b.py", 5), ("elsewhere.py", 99)]
+
+ facts = rollup_component(
+ files,
+ test_files={"test_a.py"},
+ git_rows=git_rows,
+ health_rows=health_rows,
+ dead_rows=dead_rows,
+ dead_code_ran=True,
+ )
+
+ assert facts["file_count"] == 4
+ health = facts["health"]
+ # NLOC-weighted over scored files: (4*300 + 10*100 + 9*50) / 450.
+ assert health["average"] == pytest.approx(round((1200 + 1000 + 450) / 450, 2))
+ assert health["scored_files"] == 3
+ assert (health["worst_path"], health["basis"]) == ("a.py", "measured")
+ assert facts["hotspots"]["count"] == 2
+ assert facts["hotspots"]["top"] == ["a.py", "b.py"]
+ # Ann owns 2 of 3 files, over half: one owner covers it.
+ assert facts["bus_factor"]["value"] == 1
+ assert facts["bus_factor"]["single_owner_files"] == 2
+ assert (facts["bus_factor"]["owned_files"], facts["bus_factor"]["coverage"]) == (3, 0.75)
+ # Three owned files are too few to measure a truck factor.
+ assert facts["bus_factor"]["basis"] == "inferred" and "too few" in facts["bus_factor"]["note"]
+ reach = facts["test_reach"]
+ assert (reach["reached_files"], reach["production_files"]) == (1, 3)
+ assert reach["share"] == 0.33 and reach["basis"] == "inferred"
+ assert reach["line_coverage"] == {
+ "pct": 50.0,
+ "measured_files": 1,
+ "basis": "measured",
+ "method": reach["line_coverage"]["method"],
+ }
+ dead = facts["dead_code"]
+ assert (dead["findings"], dead["files_with_findings"], dead["lines"]) == (2, 1, 25)
+ assert dead["share_of_nloc"] == 0.05 # 25 / 500 production NLOC
+ assert all("basis" in figure for figure in facts.values() if isinstance(figure, dict))
+ assert "Ann" not in json.dumps(facts) and "ann@" not in json.dumps(facts)
+
+
+def test_rollup_says_unavailable_rather_than_zero():
+ facts = rollup_component(
+ ["a.py"], test_files=set(), git_rows={}, health_rows={}, dead_rows=[],
+ dead_code_ran=False,
+ )
+ for key in ("health", "hotspots", "bus_factor", "test_reach", "dead_code"):
+ assert facts[key]["basis"] == "unavailable", key
+
+
+def _owned(path: str, owner: str) -> dict:
+ return {
+ "file_path": path,
+ "is_hotspot": False,
+ "bus_factor": 1,
+ "primary_owner_name": owner,
+ "primary_owner_email": f"{owner.lower()}@x.io",
+ "top_authors_json": "[]",
+ }
+
+
+def test_bus_factor_is_measured_from_five_owned_files():
+ files = [f"f{i}.py" for i in range(6)]
+ git_rows = {p: _owned(p, "Ann" if i < 4 else "Ben") for i, p in enumerate(files)}
+ facts = rollup_component(
+ files, test_files=set(), git_rows=git_rows, health_rows={}, dead_rows=[],
+ dead_code_ran=True,
+ )
+ bus = facts["bus_factor"]
+ assert (bus["value"], bus["owned_files"], bus["coverage"], bus["basis"]) == (1, 6, 1.0, "measured")
+ assert "note" not in bus
+
+
+def test_dead_code_that_never_ran_is_unavailable_not_zero():
+ facts = rollup_component(
+ ["a.py"], test_files=set(), git_rows={}, health_rows={"a.py": {"score": 8.0, "nloc": 10}},
+ dead_rows=[], dead_code_ran=False,
+ )
+ assert facts["dead_code"] == {
+ "basis": "unavailable",
+ "reason": "dead-code analysis has not run for this repository",
+ }
+ ran = rollup_component(
+ ["a.py"], test_files=set(), git_rows={}, health_rows={"a.py": {"score": 8.0, "nloc": 10}},
+ dead_rows=[], dead_code_ran=True,
+ )
+ assert (ran["dead_code"]["findings"], ran["dead_code"]["basis"]) == (0, "inferred")
+
+
+def test_gated_languages_are_left_out_of_health_and_dead_code():
+ health_rows = {
+ "A.java": {"score": 2.0, "nloc": 100},
+ "b.py": {"score": 8.0, "nloc": 100},
+ }
+ facts = rollup_component(
+ ["A.java", "b.py"], test_files=set(), git_rows={}, health_rows=health_rows,
+ dead_rows=[("A.java", 50), ("b.py", 10)], dead_code_ran=True,
+ )
+ health, dead = facts["health"], facts["dead_code"]
+ assert (health["average"], health["scored_files"], health["gated_files"]) == (8.0, 1, 1)
+ assert health["method"].endswith("; 1 file(s) in gated languages excluded")
+ assert (dead["findings"], dead["lines"], dead["gated_files"]) == (1, 10, 1)
+ assert dead["share_of_nloc"] == 0.1
+ assert dead["method"].endswith("; 1 file(s) in gated languages excluded")
+
+
+def test_only_gated_files_make_health_and_dead_code_unavailable():
+ facts = rollup_component(
+ ["A.java", "B.cs"], test_files=set(), git_rows={},
+ health_rows={"A.java": {"score": 2.0, "nloc": 10}, "B.cs": {"score": 3.0, "nloc": 10}},
+ dead_rows=[("A.java", 5)], dead_code_ran=True,
+ )
+ assert facts["health"]["basis"] == "unavailable" and facts["health"]["gated_files"] == 2
+ assert facts["dead_code"]["basis"] == "unavailable" and facts["dead_code"]["gated_files"] == 2
diff --git a/tests/unit/server/mcp/test_components_mcp.py b/tests/unit/server/mcp/test_components_mcp.py
new file mode 100644
index 000000000..f1a392d99
--- /dev/null
+++ b/tests/unit/server/mcp/test_components_mcp.py
@@ -0,0 +1,224 @@
+"""``component:<name>`` targets in get_context and include=["components"] in get_overview."""
+
+from __future__ import annotations
+
+import json
+
+import pytest
+
+_CATALOG = """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: auth
+ title: Sign-in
+ annotations:
+ repowise.dev/criticality: critical
+ repowise.dev/tags: pci, customer-facing
+spec: {type: service, lifecycle: production, owner: group:default/identity}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: billing
+ annotations:
+ repowise.dev/paths: src/billing/**
+spec: {type: service, lifecycle: experimental, owner: group:default/money}
+---
+apiVersion: backstage.io/v1alpha1
+kind: Gadget
+metadata: {name: nope}
+"""
+
+
+def _write_catalog(root) -> None:
+ (root / ".repowise").mkdir(exist_ok=True)
+ (root / ".repowise" / "components.yaml").write_text(_CATALOG, encoding="utf-8")
+
+
+def _without_meta(payload: dict) -> str:
+ return json.dumps({k: v for k, v in payload.items() if k != "_meta"}, sort_keys=True)
+
+
+async def test_overview_lists_derived_components_only_when_asked(setup_mcp):
+ from repowise.server.mcp_server import get_overview
+
+ default = await get_overview()
+ assert "components" not in default
+ assert "components" not in default["more"]
+
+ block = (await get_overview(include=["components"]))["components"]
+ assert block["items"] == [
+ {"name": "auth", "source": "derived", "derived_from": "module", "file_count": 2},
+ {"name": "db", "source": "derived", "derived_from": "module", "file_count": 1},
+ ]
+ assert block["total"] == 2
+ assert block["unassigned_files"] == 1 # tests/test_service.py sits under no module
+ assert "catalog_errors" not in block
+ assert "hint" not in block
+
+
+async def test_overview_merges_declared_components_over_derived(setup_mcp, tmp_path):
+ from repowise.server.mcp_server import get_overview
+
+ _write_catalog(tmp_path)
+ block = (await get_overview(include=["components"]))["components"]
+ names = [row["name"] for row in block["items"]]
+ assert names == ["auth", "billing", "db"]
+ auth = block["items"][0]
+ assert auth == {
+ "name": "auth",
+ "source": "declared",
+ "owner": "group:default/identity",
+ "component_type": "service",
+ "lifecycle": "production",
+ "criticality": "critical",
+ "tags": ["pci", "customer-facing"],
+ "file_count": 2, # no paths of its own: inherits the derived module's
+ }
+ assert block["items"][1]["file_count"] == 0
+ assert block["catalog_errors"] == 1 # the unknown kind
+
+
+async def test_component_target_rolls_up_existing_facts(setup_mcp, session, tmp_path):
+ from repowise.core.persistence.models import HealthFileMetric
+ from repowise.server.mcp_server import get_context
+
+ session.add_all(
+ [
+ HealthFileMetric(
+ repository_id="repo1",
+ file_path="src/auth/service.py",
+ score=6.0,
+ nloc=100,
+ has_test_file=True,
+ ),
+ HealthFileMetric(
+ repository_id="repo1",
+ file_path="src/auth/middleware.py",
+ score=9.0,
+ nloc=100,
+ has_test_file=False,
+ ),
+ ]
+ )
+ await session.commit()
+ _write_catalog(tmp_path)
+
+ result = await get_context(targets=["component:auth", "src/db/models.py"])
+ card = result["targets"]["component:auth"]
+ assert card["type"] == "component"
+ assert (card["name"], card["source"], card["title"]) == ("auth", "declared", "Sign-in")
+ assert card["declared_in"] == ".repowise/components.yaml"
+ assert card["paths"] == ["src/auth/**"]
+ assert card["file_count"] == 2
+ assert card["sample_files"] == ["src/auth/middleware.py", "src/auth/service.py"]
+ facts = card["facts"]
+ assert facts["health"]["average"] == 7.5
+ assert facts["health"]["worst_path"] == "src/auth/service.py"
+ assert facts["hotspots"]["count"] == 1
+ assert facts["hotspots"]["top"] == ["src/auth/service.py"]
+ assert facts["bus_factor"]["value"] == 1
+ assert facts["bus_factor"]["owned_files"] == 1 # middleware.py has no git row
+ assert facts["bus_factor"]["basis"] == "inferred"
+ assert facts["test_reach"]["share"] == 0.5
+ assert facts["dead_code"]["findings"] == 1 and facts["dead_code"]["lines"] == 20
+ assert all(figure["basis"] for figure in facts.values())
+ assert facts["dead_code"]["basis"] == "inferred" # the fixture has findings, so it ran
+ assert "Alice" not in json.dumps(card)
+ # A file target in the same batch still resolves the ordinary way.
+ assert "src/db/models.py" in result["targets"]
+
+
+async def test_unknown_component_names_the_available_ones(setup_mcp):
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(targets=["component:nope"])
+ card = result["targets"]["component:nope"]
+ assert card["error"] == "No component named 'nope'."
+ assert card["available"] == ["auth", "db"]
+
+
+async def test_default_responses_are_byte_identical_with_a_catalog(setup_mcp, tmp_path):
+ from repowise.server.mcp_server import get_context, get_overview
+
+ overview_before = _without_meta(await get_overview())
+ context_before = _without_meta(await get_context(targets=["src/auth/service.py"]))
+ _write_catalog(tmp_path)
+ (tmp_path / "catalog-info.yaml").write_text(_CATALOG, encoding="utf-8")
+
+ assert _without_meta(await get_overview()) == overview_before
+ assert _without_meta(await get_context(targets=["src/auth/service.py"])) == context_before
+
+
+async def test_a_declared_component_that_claims_nothing_says_why(setup_mcp, tmp_path):
+ from repowise.server.mcp_server import get_context
+
+ (tmp_path / "catalog-info.yaml").write_text(
+ "apiVersion: backstage.io/v1alpha1\nkind: Component\nmetadata: {name: ghost}\n"
+ "spec: {type: service, lifecycle: production, owner: platform}\n",
+ encoding="utf-8",
+ )
+ card = (await get_context(targets=["component:ghost"]))["targets"]["component:ghost"]
+ assert card["file_count"] == 0
+ assert "claims no files" in card["note"]
+ assert {f["basis"] for f in card["facts"].values()} == {"unavailable"}
+ assert "sample_files" not in card
+
+
+async def test_several_component_targets_resolve_components_once(setup_mcp, monkeypatch):
+ from repowise.server.mcp_server import _components, get_context
+
+ calls = []
+ real = _components.load_repo_components
+
+ async def counting(*args, **kwargs):
+ calls.append(1)
+ return await real(*args, **kwargs)
+
+ monkeypatch.setattr(_components, "load_repo_components", counting)
+ result = await get_context(targets=["component:auth", "component:db", "src/db/models.py"])
+ assert set(result["targets"]) == {"component:auth", "component:db", "src/db/models.py"}
+ assert len(calls) == 1
+ await get_context(targets=["component:auth"])
+ assert len(calls) == 1 # cached for the same index and catalog state
+
+
+async def test_a_component_batch_reads_each_fact_table_once(setup_mcp, tmp_path, monkeypatch):
+ from repowise.core.components import store
+
+ (tmp_path / "catalog-info.yaml").write_text(
+ "apiVersion: backstage.io/v1alpha1\nkind: Component\n"
+ "metadata:\n name: middleware\n"
+ " annotations: {repowise.dev/paths: src/auth/middleware.py}\n"
+ "spec: {type: service, lifecycle: production, owner: platform}\n",
+ encoding="utf-8",
+ )
+ reads: list[int] = []
+ runs: list[int] = []
+ real_rows, real_ran = store._rows_for, store.dead_code_ran
+
+ async def rows_for(*args, **kwargs):
+ reads.append(1)
+ return await real_rows(*args, **kwargs)
+
+ async def ran(*args, **kwargs):
+ runs.append(1)
+ return await real_ran(*args, **kwargs)
+
+ monkeypatch.setattr(store, "_rows_for", rows_for)
+ monkeypatch.setattr(store, "dead_code_ran", ran)
+ from repowise.server.mcp_server import get_context
+
+ result = await get_context(targets=["component:auth", "component:db", "component:middleware"])
+ assert all("facts" in result["targets"][t] for t in result["targets"])
+ # git, health and dead-code rows once each, and the run status once, for three components.
+ assert (len(reads), len(runs)) == (3, 1)