Skip to content

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

feat(components): one repo-wide component for flat or layout-only repos, and contracts outside every component are counted (#4552)

Raghav Chamadiyacb13183027d5
diff --git a/docs/layers/COMPONENTS.md b/docs/layers/COMPONENTS.md
index f36186d6c..313992768 100644
--- a/docs/layers/COMPONENTS.md
+++ b/docs/layers/COMPONENTS.md
@@ -28,7 +28,9 @@ spec:
```
With no file, components are derived from workspace services, module pages or
-top-level directories, so every repository has them from the first index. A full
+top-level directories, so every repository has them from the first index. A repo
+those do not divide (every file at the root, or only layout and test directories
+such as `src` and `test`) is one component named after the repo. A full
example is in [examples/components](../../examples/components/components.yaml).
## Declared owners against recent activity
diff --git a/packages/cli/src/repowise/cli/commands/components_cmd.py b/packages/cli/src/repowise/cli/commands/components_cmd.py
index 31c01b16d..bb4048b76 100644
--- a/packages/cli/src/repowise/cli/commands/components_cmd.py
+++ b/packages/cli/src/repowise/cli/commands/components_cmd.py
@@ -91,7 +91,7 @@ def components_check(repo: str | None, fmt: str) -> None:
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.resolve import derive_from_directories, repo_wide_when_flat
from repowise.core.components.store import load_repo_components, workspace_services
async with repo_index_session(root) as opened:
@@ -103,7 +103,8 @@ async def _list(root: Path) -> dict[str, Any]:
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)
+ derived = repo_wide_when_flat(derive_from_directories(files), files, root.resolve().name)
+ resolved = resolve_components(catalog.components, derived, files)
return {"indexed": False, "catalog": catalog, "resolved": resolved}
@@ -159,7 +160,10 @@ def components_list(repo: str | None, fmt: str) -> None:
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]")
+ console.print(
+ "[dim]No index found: derived components are top-level directories, "
+ "or the whole repo when it is flat.[/dim]"
+ )
if data["catalog"].errors:
console.print("[yellow]The catalog has errors; run `repowise components check`.[/yellow]")
diff --git a/packages/core/src/repowise/core/components/catalog.py b/packages/core/src/repowise/core/components/catalog.py
index edc269b0e..7dc7ac0eb 100644
--- a/packages/core/src/repowise/core/components/catalog.py
+++ b/packages/core/src/repowise/core/components/catalog.py
@@ -96,11 +96,13 @@ class Component:
criticality: str | None = None
tags: tuple[str, ...] = ()
capability: str | None = None
- #: "declared", or how a derived one was found: "service", "module", "directory".
+ #: "declared", or how a derived one was found: "service", "module", "directory",
+ #: or "repo" for one component covering a repo nothing else divides.
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.
+ #: Directory a derived component covers (``"."`` for the whole repo); files
+ #: go to the deepest one.
root: str | None = None
@property
diff --git a/packages/core/src/repowise/core/components/resolve.py b/packages/core/src/repowise/core/components/resolve.py
index 1bd4f6022..71d27c083 100644
--- a/packages/core/src/repowise/core/components/resolve.py
+++ b/packages/core/src/repowise/core/components/resolve.py
@@ -7,6 +7,12 @@ knows, first source that yields any:
2. module pages of the structural wiki (``module``),
3. top-level directories, the module-health bucket (``directory``).
+A repo those sources cannot divide gets one component named after the repo
+(``repo``): no derived component that names a place claims a file (a flat
+repo, or only layout and test directories such as ``src`` and ``test``), most
+files sit at the repo root, or more code sits at the root than under every
+place (a root-level service beside ``docs/`` or ``deploy/``).
+
Declared components merge over derived ones:
* A declared component claims every file its ``repowise.dev/paths`` globs
@@ -26,6 +32,7 @@ import hashlib
import re
from collections.abc import Iterable
from dataclasses import dataclass, field, replace
+from functools import cache
import pathspec
from pathspec.patterns.gitwildmatch import GitWildMatchPatternError
@@ -77,6 +84,46 @@ def derive_from_directories(file_paths: Iterable[str]) -> list[Component]:
return _derived(((d, None) for d in sorted(dirs)), "directory")
+def repo_wide_when_flat(
+ derived: list[Component], file_paths: Iterable[str], repo_name: str
+) -> list[Component]:
+ """*derived*, or one component for the whole repo when *derived* does not
+ divide it (see the module docstring). Dot-directories and root dot-files
+ stay unassigned, as they do under directory derivation."""
+ files = [p for p in file_paths if not p.startswith(".")]
+ if not files:
+ return derived
+ at_root = sum(1 for p in files if "/" not in p)
+ places = [c for c in derived if _names_place(c.root)]
+ placed = [p for p in files if any(_under(p, c.root) for c in places)]
+ code = _code_suffixes()
+ root_code = sum(1 for p in files if "/" not in p and p.lower().endswith(code))
+ placed_code = sum(1 for p in placed if p.lower().endswith(code))
+ if placed and at_root * 2 <= len(files) and root_code <= placed_code:
+ return derived
+ return [
+ Component(
+ name=_slug(repo_name) or "repo",
+ paths=("**", "!/.*"),
+ source="repo",
+ root=REPO_ROOT,
+ )
+ ]
+
+
+@cache
+def _code_suffixes() -> tuple[str, ...]:
+ from repowise.core.ingestion.languages.registry import REGISTRY
+
+ return tuple(sorted(s.lower() for s in REGISTRY.all_code_extensions()))
+
+
+def _names_place(root: str | None) -> bool:
+ """Whether *root*'s last place segment says more than layout or tests."""
+ parts = [p for p in (root or "").split("/") if p and not _ROUTE_SEGMENT.match(p)]
+ return bool(parts) and parts[-1].lower() not in _CODEBASE_SEGMENTS | _TEST_SEGMENTS
+
+
def _derived(roots: Iterable[tuple[str, str | None]], source: str) -> list[Component]:
cleaned: dict[str, str | None] = {}
for root, title in roots:
@@ -141,6 +188,12 @@ def _assign_names(roots: list[str]) -> dict[str, str]:
_ROUTE_SEGMENT = re.compile(r"^(\[.*\]|\(.*\)|\{[\w.-]+\}|[:$][\w-]+)$")
#: Layout directories too generic to tell two same-named components apart.
_LAYOUT_SEGMENTS = frozenset({"src", "lib", "app", "apps", "packages", "pkg", "internal", "source"})
+#: Layout directories that hold one codebase (``packages`` or ``apps`` hold several).
+_CODEBASE_SEGMENTS = frozenset({"src", "source", "lib", "app"})
+#: Directories that hold a repo's tests rather than a part of it.
+_TEST_SEGMENTS = frozenset({"test", "tests", "spec", "specs", "__tests__", "e2e"})
+#: The ``root`` of a repo-wide component: every path outside a dot-directory.
+REPO_ROOT = "."
def _names(root: str) -> list[str]:
@@ -210,6 +263,8 @@ def resolve_components(
def _under(path: str, root: str | None) -> bool:
+ if root == REPO_ROOT:
+ return not path.startswith(".")
return bool(root) and path.startswith(f"{root}/")
diff --git a/packages/core/src/repowise/core/components/store.py b/packages/core/src/repowise/core/components/store.py
index f268b2187..7094014d9 100644
--- a/packages/core/src/repowise/core/components/store.py
+++ b/packages/core/src/repowise/core/components/store.py
@@ -18,6 +18,7 @@ from repowise.core.components.resolve import (
derive_from_directories,
derive_from_modules,
derive_from_services,
+ repo_wide_when_flat,
resolve_components,
)
from repowise.core.components.rollup import rollup_component
@@ -104,9 +105,10 @@ async def load_repo_components(
)
)
).all()
- derived = derive_from_modules((m[0], m[1]) for m in modules)
- if not derived:
- derived = derive_from_directories(files)
+ derived = derive_from_modules((m[0], m[1]) for m in modules) or derive_from_directories(
+ files
+ )
+ derived = repo_wide_when_flat(derived, files, Path(repo_root).resolve().name)
return RepoComponents(
catalog=catalog,
resolved=resolve_components(catalog.components, derived, files),
diff --git a/packages/core/src/repowise/core/report/sections/components.py b/packages/core/src/repowise/core/report/sections/components.py
index d999e374d..b0d384339 100644
--- a/packages/core/src/repowise/core/report/sections/components.py
+++ b/packages/core/src/repowise/core/report/sections/components.py
@@ -48,7 +48,8 @@ def _map_item(found: Any, comps: list, directory_issues: list[str]) -> dict[str,
],
method=(
"components declared in .repowise/components.yaml or catalog-info.yaml, "
- "else derived from workspace services, module pages or top-level directories"
+ "else derived from workspace services, module pages or top-level directories, "
+ "or the whole repo when those do not divide it"
),
basis="declared" if catalog.sources else "inferred",
data={
diff --git a/packages/core/src/repowise/core/report/sections/contracts.py b/packages/core/src/repowise/core/report/sections/contracts.py
index 98269bc7a..7296d2fa6 100644
--- a/packages/core/src/repowise/core/report/sections/contracts.py
+++ b/packages/core/src/repowise/core/report/sections/contracts.py
@@ -2,10 +2,13 @@
from __future__ import annotations
+from collections.abc import Iterable
from typing import Any
from repowise.core.report.model import ReportContext, Section, capped, check, report_sections
+#: The row for provider files outside every component.
+_OUTSIDE = "(no component)"
_METHOD = "provider contracts from the workspace contract store and their cross-repo consumer links"
@@ -27,21 +30,28 @@ async def collect(ctx: ReportContext) -> list[dict[str, Any]]:
]
found = await ctx.components()
out = []
- total = 0
+ outside = 0
+ # Distinct ids: a contract served from files in two components is one.
+ every: set[str] = set()
quiet: list[str] = []
- for comp in found.resolved.components:
- provided: dict[str, int] = {}
- for path in found.resolved.files.get(comp.name, ()):
- for cid, consumers in contracts.get(path, {}).items():
- provided[cid] = provided.get(cid, 0) + consumers
+ rows = [(c.name, found.resolved.files.get(c.name, ())) for c in found.resolved.components]
+ owned = {path for _name, paths in rows for path in paths}
+ # Provider files no component claims (root files of a divided repo, or
+ # files the index left out) still count, under a row of their own.
+ rows.append((_OUTSIDE, [path for path in contracts if path not in owned]))
+ for name, paths in rows:
+ provided = _provided(paths, contracts)
if not provided:
- quiet.append(comp.name)
+ if name != _OUTSIDE:
+ quiet.append(name)
continue
- total += len(provided)
+ every.update(provided)
+ if name == _OUTSIDE:
+ outside = len(provided)
consumed = sum(1 for n in provided.values() if n)
out.append(
check(
- f"contracts:{comp.name}",
+ f"contracts:{name}",
reason=f"{len(provided)} provided contract(s), {consumed} with consumers elsewhere",
details=capped(
[f"{cid}: {n} consumer link(s)" for cid, n in sorted(provided.items())]
@@ -51,12 +61,15 @@ async def collect(ctx: ReportContext) -> list[dict[str, Any]]:
data={"provided": dict(sorted(provided.items()))},
)
)
+ total = len(every)
out.insert(
0,
check(
"contracts",
reason=(
- f"{total} provided contract(s) detected across {len(out)} component(s)"
+ f"{total} provided contract(s) detected across "
+ f"{len(out) - bool(outside)} component(s)"
+ + (f", {outside} outside every component" if outside else "")
+ ("; zero may mean none were detected, not that none exist" if not total else "")
),
details=[f"none detected: {', '.join(quiet)}"] if quiet else [],
@@ -68,6 +81,15 @@ async def collect(ctx: ReportContext) -> list[dict[str, Any]]:
return out
+def _provided(paths: Iterable[str], contracts: dict[str, dict[str, int]]) -> dict[str, int]:
+ """Consumer links per contract id provided in *paths*."""
+ provided: dict[str, int] = {}
+ for path in paths:
+ for cid, consumers in contracts.get(path, {}).items():
+ provided[cid] = provided.get(cid, 0) + consumers
+ return provided
+
+
report_sections.register(
"contracts",
Section(
diff --git a/tests/unit/cli/test_components_cmd.py b/tests/unit/cli/test_components_cmd.py
index c954e5b61..1cf545e85 100644
--- a/tests/unit/cli/test_components_cmd.py
+++ b/tests/unit/cli/test_components_cmd.py
@@ -87,8 +87,10 @@ def test_list_without_an_index_uses_directories_and_the_catalog(repo):
"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
+ # Only the layout directory "src" divides the repo, so the derived component
+ # is the whole repo, keeping the files the declared component did not claim.
+ (whole,) = [r for r in data["components"] if r["source"] == "repo"]
+ assert whole["files"] == 2 and "src" not in rows
assert data["catalog_errors"] == 0
diff --git a/tests/unit/core/test_components_resolve.py b/tests/unit/core/test_components_resolve.py
index aa59dd534..649efc83b 100644
--- a/tests/unit/core/test_components_resolve.py
+++ b/tests/unit/core/test_components_resolve.py
@@ -11,6 +11,7 @@ from repowise.core.components.resolve import (
derive_from_directories,
derive_from_modules,
derive_from_services,
+ repo_wide_when_flat,
resolve_components,
)
from repowise.core.components.rollup import rollup_component
@@ -34,6 +35,55 @@ def test_directories_are_the_fallback_and_root_files_stay_unassigned():
assert resolved.unassigned == ["README.md"]
+ "files",
+ [FILES, ["README.md", "packages/a/x.py", "packages/b/y.py", "apps/w/z.py"]],
+)
+def test_a_repo_with_places_keeps_its_derived_components(files):
+ derived = derive_from_directories(files)
+ assert repo_wide_when_flat(derived, files, "shop") is derived
+
+
+ "files",
+ [
+ # Flat: every file at the root (a small Go or Node service).
+ [".github/ci.yml", "main.go", "handlers.go", "go.mod"],
+ # Layout and test directories only.
+ ["README.md", "src/main/java/App.java", "src/main/java/Api.java", "test/AppTest.java"],
+ # Most files at the root, beside a directory that names a place.
+ ["a.go", "b.go", "c.go", "cmd/svc/main.go"],
+ # Code at the root, beside a larger folder of docs that names a place.
+ ["a.go", "b.go", "c.go", "d.go", "e.go", *(f"docs/p{i}.md" for i in range(6))],
+ ],
+)
+def test_a_flat_or_layout_only_repo_is_one_repo_wide_component(files):
+ derived = repo_wide_when_flat(derive_from_directories(files), files, "Cart Service")
+ resolved = resolve_components([], derived, files)
+
+ (comp,) = resolved.components
+ assert (comp.name, comp.source) == ("Cart-Service", "repo")
+ assert resolved.files[comp.name] == sorted(p for p in files if not p.startswith("."))
+ assert resolved.unassigned == sorted(p for p in files if p.startswith("."))
+
+
+def test_a_module_page_matching_no_file_does_not_divide_the_repo():
+ # The structural wiki's "root" module names root-level files, not a directory.
+ files = ["service.go", "transport.go", "cmd/svc/main.go", "test/unit.py"]
+ derived = repo_wide_when_flat(derive_from_modules([("root", "Root")]), files, "catalogue")
+ assert [c.name for c in resolve_components([], derived, files).components] == ["catalogue"]
+
+
+def test_a_declared_twin_of_the_repo_wide_component_claims_the_repo():
+ files = ["main.go", "test/main_test.go"]
+ derived = repo_wide_when_flat(derive_from_directories(files), files, "cart")
+ declared = [Component(name="cart", owner="group:default/shop")]
+ resolved = resolve_components(declared, derived, files)
+
+ assert [(c.name, c.owner) for c in resolved.components] == [("cart", "group:default/shop")]
+ assert resolved.files["cart"] == files
+
+
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")]
diff --git a/tests/unit/core/test_package_usage.py b/tests/unit/core/test_package_usage.py
index 2137c7d11..95c2d887c 100644
--- a/tests/unit/core/test_package_usage.py
+++ b/tests/unit/core/test_package_usage.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+from repowise.core.components.resolve import repo_wide_when_flat
from repowise.core.inventory.components import component_inventory
from repowise.core.inventory.cyclonedx import cyclonedx_bom, purl
from repowise.core.inventory.usage import package_usage, package_usages, parse_query
@@ -48,7 +49,10 @@ async def test_sites_carry_line_component_owners_and_reachability(session, tmp_p
assert legacy["owners"] == [] # an individual CODEOWNERS entry is never named
assert legacy["owner_counts"] == {"individual": 1} # but it is counted
assert "owner_counts" not in util
- assert legacy["component"] == "src" # the derived top-level directory
+ # Only src/ and tests/ divide the repo, so what the catalog leaves goes to
+ # the derived component for the whole repo.
+ whole = repo_wide_when_flat([], ["x.py"], tmp_path.name)[0].name
+ assert legacy["component"] == whole
assert sites["tests/test_util.py"]["reachability"]["state"] == "test"
assert doc["summary"]["reachability"] == {
@@ -57,7 +61,7 @@ async def test_sites_carry_line_component_owners_and_reachability(session, tmp_p
"test": 1,
"unknown": 1,
}
- assert [c["name"] for c in doc["components"]] == ["app", "jobs", "src", "tests"]
+ assert sorted(c["name"] for c in doc["components"]) == sorted(["app", "jobs", whole])
async def test_import_name_alone_is_inferred_and_ecosystem_scoped(session, tmp_path): # noqa: F811
diff --git a/tests/unit/core/test_report.py b/tests/unit/core/test_report.py
index 3ccc50f7e..5578d9bc0 100644
--- a/tests/unit/core/test_report.py
+++ b/tests/unit/core/test_report.py
@@ -289,6 +289,29 @@ async def test_contracts_unavailable_outside_a_workspace_then_measured(ctx, monk
items = await _section("contracts", ctx)
assert items["contracts:api"]["data"]["provided"] == {"http::GET::/x": 2}
assert items["contracts"]["data"]["provided"] == 1
+ assert "outside" not in items["contracts"]["reason"]
+
+
+async def test_contracts_count_providers_outside_every_component(ctx, monkeypatch):
+ from repowise.core.events import snapshot
+
+ store = {
+ "api/a.py": {"http::GET::/x": 2},
+ "web/W.java": {"http::GET::/x": 0},
+ "main.py": {"http::GET::/health": 0, "http::GET::/x": 0},
+ }
+ monkeypatch.setattr(snapshot, "provided_contracts", lambda *_a: store)
+ items = await _section("contracts", ctx)
+ assert items["contracts:(no component)"]["data"]["provided"] == {
+ "http::GET::/health": 0,
+ "http::GET::/x": 0,
+ }
+ head = items["contracts"]
+ # Distinct ids, as the store holds them: /x in three places is one contract.
+ assert head["data"]["provided"] == 2
+ assert head["reason"] == (
+ "2 provided contract(s) detected across 2 component(s), 2 outside every component"
+ )
async def test_decisions_per_component_with_stale(ctx, monkeypatch):
diff --git a/tests/unit/core/test_report_inventory.py b/tests/unit/core/test_report_inventory.py
index b0f77b413..febbf96ae 100644
--- a/tests/unit/core/test_report_inventory.py
+++ b/tests/unit/core/test_report_inventory.py
@@ -2,6 +2,7 @@
from __future__ import annotations
+from repowise.core.components.resolve import repo_wide_when_flat
from repowise.core.report.build import available_sections, collect_repo
from repowise.core.report.model import ReportContext
from tests.unit.core.inventory_fixture import REPO, session # noqa: F401 (fixture)
@@ -24,6 +25,7 @@ async def test_inventory_report_section(session, tmp_path): # noqa: F811
# Only components with no declared owner team get an item of their own.
assert "inventory:app" not in checks and "inventory:jobs" not in checks
- src = checks["inventory:src"]
+ # src/ and tests/ are layout, so the rest of the repo is one derived component.
+ src = checks[f"inventory:{repo_wide_when_flat([], ['x.py'], tmp_path.name)[0].name}"]
assert "no declared owner team" in src["reason"]
assert "package: pypi:requests (1 file(s))" in src["details"]
diff --git a/tests/unit/workspace/test_store.py b/tests/unit/workspace/test_store.py
index d11d87ba2..a50856f04 100644
--- a/tests/unit/workspace/test_store.py
+++ b/tests/unit/workspace/test_store.py
@@ -133,8 +133,9 @@ async def test_refresh_builds_every_table_from_the_repo_indexes(tmp_path):
("web", "pr-7", "web change")
]
# Derived components (top-level directories here) per repo.
- assert ("api", "src") in rows(path, "SELECT alias, name FROM components")
- assert lookup_symbols(path, [], components_of="api") == ({}, {"src"})
+ # A repo with only src/ is one component named after the repo.
+ assert ("api", "api") in rows(path, "SELECT alias, name FROM components")
+ assert lookup_symbols(path, [], components_of="api") == ({}, {"api"})
assert symbols(path, ["serve", "App.run", "run", "missing"]) == {
"serve": [