Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(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.mdindex 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.mdindex 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. Noisediff --git a/docs/reference/CONFIG.md b/docs/reference/CONFIG.mdindex 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 aa confirmed (`active`) decision is never walked back to `proposed` by are-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:` blockSecret shapes of your own for `repowise security check`.diff --git a/examples/README.md b/examples/README.mdindex 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.mdnew file mode 100644index 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.yamlnew file mode 100644index 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.pynew file mode 100644index 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.pyindex 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__.pynew file mode 100644index 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.pynew file mode 100644index 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 Nonediff --git a/packages/core/src/repowise/core/components/check.py b/packages/core/src/repowise/core/components/check.pynew file mode 100644index 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 issuesdiff --git a/packages/core/src/repowise/core/components/resolve.py b/packages/core/src/repowise/core/components/resolve.pynew file mode 100644index 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 bestdiff --git a/packages/core/src/repowise/core/components/rollup.py b/packages/core/src/repowise/core/components/rollup.pynew file mode 100644index 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 outdiff --git a/packages/core/src/repowise/core/components/store.py b/packages/core/src/repowise/core/components/store.pynew file mode 100644index 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.pynew file mode 100644index 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 blockdiff --git a/packages/server/src/repowise/server/mcp_server/tool_context/context.py b/packages/server/src/repowise/server/mcp_server/tool_context/context.pyindex 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 ToolRecipefrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server import _statefrom repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server._components import component_cards, is_component_targetfrom repowise.server.mcp_server._episodes import enrich_episode_counts as _enrich_episodesfrom 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.pyindex 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 GitMetadatafrom repowise.core.registry import mcp_tool_registry as mcpfrom repowise.server.mcp_server import _statefrom repowise.server.mcp_server._budget import OmissionCollector+from repowise.server.mcp_server._components import component_listfrom 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 = NoneReturns the overview summary, key modules, entry points, architecturelayers 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 summarysection, 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 = Nonecollector = 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.pyindex 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.pynew file mode 100644index 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"] == 0diff --git a/tests/unit/cli/test_lazy_commands.py b/tests/unit/cli/test_lazy_commands.pyindex 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.pynew file mode 100644index 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.pynew file mode 100644index 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"] == 2diff --git a/tests/unit/server/mcp/test_components_mcp.py b/tests/unit/server/mcp/test_components_mcp.pynew file mode 100644index 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)