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): 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.mdindex 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 fullexample is in [examples/components](../../examples/components/components.yaml).## Declared owners against recent activitydiff --git a/packages/cli/src/repowise/cli/commands/components_cmd.py b/packages/cli/src/repowise/cli/commands/components_cmd.pyindex 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_flatfrom repowise.core.components.store import load_repo_components, workspace_servicesasync 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.pyindex 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 = Nonetags: 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@propertydiff --git a/packages/core/src/repowise/core/components/resolve.py b/packages/core/src/repowise/core/components/resolve.pyindex 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 hashlibimport refrom collections.abc import Iterablefrom dataclasses import dataclass, field, replace+from functools import cacheimport pathspecfrom 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.pyindex 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.pyindex 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.pyindex 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 Iterablefrom typing import Anyfrom 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.pyindex 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 rowsassert data["catalog_errors"] == 0diff --git a/tests/unit/core/test_components_resolve.py b/tests/unit/core/test_components_resolve.pyindex 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.pyindex 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_flatfrom repowise.core.inventory.components import component_inventoryfrom repowise.core.inventory.cyclonedx import cyclonedx_bom, purlfrom 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_passert legacy["owners"] == [] # an individual CODEOWNERS entry is never namedassert legacy["owner_counts"] == {"individual": 1} # but it is countedassert "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"] == wholeassert 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: F811diff --git a/tests/unit/core/test_report.py b/tests/unit/core/test_report.pyindex 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, monkitems = 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.pyindex 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_flatfrom repowise.core.report.build import available_sections, collect_repofrom repowise.core.report.model import ReportContextfrom 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.pyindex 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": [