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(changes): treat files outside every component as known, and re-resolve kept components after a catalog edit (#4494)

Raghav Chamadiyab3ee7e68f76b
diff --git a/packages/core/src/repowise/core/changes/collect.py b/packages/core/src/repowise/core/changes/collect.py
index e5b758a86..a6088e765 100644
--- a/packages/core/src/repowise/core/changes/collect.py
+++ b/packages/core/src/repowise/core/changes/collect.py
@@ -13,6 +13,8 @@ the ``index_commit`` it read, rebuilt only on request (``refresh``). The
``outcomes`` item is the exception: it describes history after the change, so
a kept checklist has that one item rebuilt when HEAD moves
(:func:`with_current_outcomes`), which costs one history read per HEAD.
+Components and owners are resolved again on read when the component catalog
+changed since the checklist was kept (:func:`with_current_components`).
"""
from __future__ import annotations
@@ -21,6 +23,7 @@ import asyncio
import json
import re
from collections.abc import Sequence
+from dataclasses import replace
from pathlib import Path
from types import SimpleNamespace
from typing import TYPE_CHECKING, Any
@@ -29,6 +32,7 @@ import structlog
from repowise.core.changes.evidence import (
EVIDENCE_SCHEMA_VERSION,
+ KINDS,
SUMMARY_SKIPPED_KINDS,
ChangeEvidence,
EvidenceInputs,
@@ -36,6 +40,7 @@ from repowise.core.changes.evidence import (
Unavailable,
build_change_evidence,
)
+from repowise.core.components.catalog import catalog_digest
from repowise.core.ownership.codeowners import (
CodeownersMatcher,
parse_codeowners,
@@ -169,9 +174,10 @@ async def evidence_for_revspec(
decisions=gone,
provenance=gone,
)
- index_commit = None
+ index_commit = digest = None
else:
shas = await asyncio.to_thread(_change_commits, root, revspec, row)
+ digest = await asyncio.to_thread(catalog_digest, root)
inputs = await gather_inputs(
session,
repo_id,
@@ -181,9 +187,12 @@ async def evidence_for_revspec(
row=row,
)
index_commit = getattr(await get_repository(session, repo_id), "head_commit", None)
- return build_change_evidence(
+ evidence = build_change_evidence(
bundle, inputs, change_id=change_id, revspec=revspec, index_commit=index_commit
)
+ if isinstance(inputs.components, Unavailable):
+ digest = None # not resolved: the next read resolves again
+ return replace(evidence, catalog_digest=digest)
# -- stored changes -------------------------------------------------------------
@@ -233,24 +242,30 @@ async def change_evidence(
risk: Any = None,
health: Any = None,
key: OutcomesKey | None = None,
+ catalog: str | None = None,
) -> ChangeEvidence:
"""The stored change's checklist: the kept one, or built and kept now.
A kept one whose outcomes were read at another HEAD has that item read
again and merged into what is stored (:func:`keep_outcomes`). *key* is the
- HEAD and window to read at, when the caller already has them.
+ HEAD and window to read at, when the caller already has them. A kept one
+ resolved under another component catalog has its components resolved
+ again (:func:`with_current_components`); *catalog* is the catalog's
+ digest now, when the caller already has it.
"""
from repowise.core.persistence.crud.changes import dump_evidence
if not refresh and (cached := cached_evidence(row)) is not None:
key = key or await outcomes_key(repo_root)
- if not await outcomes_stale(repo_root, cached, key):
- return cached
- item = await outcomes_item(session, repo_id, repo_root, row, key)
- await session.flush()
- merged = await keep_outcomes(session, repo_id, row.change_id, item)
- session.expire(row, ["evidence_json"])
- return merged or with_item(cached, item)
+ if await outcomes_stale(repo_root, cached, key):
+ item = await outcomes_item(session, repo_id, repo_root, row, key)
+ await session.flush()
+ merged = await keep_outcomes(session, repo_id, row.change_id, item)
+ session.expire(row, ["evidence_json"])
+ cached = merged or with_item(cached, item)
+ return await with_current_components(
+ session, repo_id, repo_root, row, cached, catalog=catalog
+ )
evidence = await build_stored_evidence(
session, repo_id, repo_root, row, risk=risk, health=health
)
@@ -314,11 +329,14 @@ async def outcomes_item(
return _outcomes(EvidenceInputs(outcomes=found))
-def with_item(evidence: ChangeEvidence, item: EvidenceItem) -> ChangeEvidence:
- """*evidence* with *item* in place of its ``outcomes`` item."""
- from dataclasses import replace
-
- return replace(evidence, items=[i for i in evidence.items if i.kind != "outcomes"] + [item])
+def with_item(evidence: ChangeEvidence, *items: EvidenceItem) -> ChangeEvidence:
+ """*evidence* with each of *items* in place of its item of that kind, or added
+ in :data:`~.evidence.KINDS` order."""
+ new = {i.kind: i for i in items}
+ merged = [new.pop(i.kind, i) for i in evidence.items] + list(new.values())
+ rank = {kind: n for n, kind in enumerate(KINDS)}
+ merged.sort(key=lambda i: rank.get(i.kind, len(rank)))
+ return replace(evidence, items=merged)
async def with_current_outcomes(
@@ -350,6 +368,21 @@ async def keep_outcomes(
read at the same HEAD and window is left as it is. ``None`` when no
checklist is stored.
"""
+ return await _merge_kept(
+ session,
+ repo_id,
+ change_id,
+ lambda stored: (
+ None if _stamp(stored.item("outcomes")) == _stamp(item) else with_item(stored, item)
+ ),
+ )
+
+
+async def _merge_kept(
+ session: Any, repo_id: str, change_id: str, merge: Any
+) -> ChangeEvidence | None:
+ """Read the checklist stored now, keep ``merge(stored)`` unless it is ``None``
+ (nothing to change), and return what is kept. ``None`` when none is stored."""
from sqlalchemy import select, update
from repowise.core.persistence.crud.changes import dump_evidence
@@ -360,15 +393,131 @@ async def keep_outcomes(
stored = cached_evidence(SimpleNamespace(evidence_json=raw))
if stored is None:
return None
- if _stamp(stored.item("outcomes")) == _stamp(item):
+ merged = merge(stored)
+ if merged is None:
return stored
- merged = with_item(stored, item)
await session.execute(
update(Change).where(*where).values(evidence_json=dump_evidence(merged.to_dict()))
)
return merged
+#: Why a kept checklist's components are not read under the catalog now.
+CATALOG_CHANGED = (
+ "not resolved against the current component catalog, and the change's file list "
+ "is not kept in full; --refresh rebuilds it"
+)
+
+
+async def components_stale(
+ repo_root: Path | str, evidence: ChangeEvidence, catalog: str | None = None
+) -> bool:
+ """Whether *evidence* was resolved under another component catalog, or before
+ the catalog was recorded on it."""
+ catalog = catalog or await asyncio.to_thread(catalog_digest, repo_root)
+ return evidence.catalog_digest != catalog
+
+
+def _stored_paths(row: Any) -> list[str] | None:
+ """The change's files as kept on its row; ``None`` when the list was capped."""
+ try:
+ files = json.loads(row.files_json or "[]")
+ except (TypeError, ValueError):
+ return None
+ if len(files) < (row.files_changed or 0):
+ return None
+ return [f["path"] for f in files if isinstance(f, dict) and f.get("path")]
+
+
+async def with_current_components(
+ session: Any,
+ repo_id: str,
+ repo_root: Path | str,
+ row: Any,
+ evidence: ChangeEvidence,
+ *,
+ catalog: str | None = None,
+) -> ChangeEvidence:
+ """*evidence* with its components and owners resolved under the catalog now.
+
+ Path globs are cheap, so a catalog edit is applied on read from the files
+ kept on the change's row, and kept. When that list was capped the catalog
+ is stamped as read: a checklist kept before digests were recorded keeps its
+ components, and one resolved under another catalog has its components item
+ kept as unknown, naming ``--refresh``.
+ """
+ catalog = catalog or await asyncio.to_thread(catalog_digest, repo_root)
+ if evidence.catalog_digest == catalog:
+ return evidence
+ paths = _stored_paths(row)
+ if paths is None:
+ return await _stamp_capped(session, repo_id, row, evidence, catalog)
+ return await _resolve_kept(session, repo_id, repo_root, row, evidence, catalog, paths)
+
+
+async def _stamp_capped(
+ session: Any, repo_id: str, row: Any, evidence: ChangeEvidence, catalog: str
+) -> ChangeEvidence:
+ """A capped checklist under *catalog*: kept, so the next read does no work."""
+ from repowise.core.changes.evidence import _unknown
+
+ item = _unknown("components_touched", "Components touched", CATALOG_CHANGED, "components")
+ # No digest: built before digests were recorded, likely under this catalog.
+ items = () if evidence.catalog_digest is None else (item,)
+ return await _keep_resolved(session, repo_id, row, evidence, catalog, items)
+
+
+async def _keep_resolved(
+ session: Any,
+ repo_id: str,
+ row: Any,
+ evidence: ChangeEvidence,
+ catalog: str,
+ items: Sequence[EvidenceItem],
+) -> ChangeEvidence:
+ """*items* merged into what is stored, stamped with *catalog*, and kept."""
+ current = replace(with_item(evidence, *items), catalog_digest=catalog)
+ await session.flush()
+ kept = await _merge_kept(
+ session,
+ repo_id,
+ row.change_id,
+ lambda stored: (
+ None
+ if stored.catalog_digest == catalog
+ else replace(with_item(stored, *items), catalog_digest=catalog)
+ ),
+ )
+ session.expire(row, ["evidence_json"])
+ return kept or current
+
+
+async def _resolve_kept(
+ session: Any,
+ repo_id: str,
+ repo_root: Path | str,
+ row: Any,
+ evidence: ChangeEvidence,
+ catalog: str,
+ paths: list[str],
+) -> ChangeEvidence:
+ """Components and owners resolved again over *paths*, and kept."""
+ from repowise.core.changes.evidence import _components as components_item
+ from repowise.core.changes.evidence import _owners as owners_item
+
+ root = Path(repo_root)
+ components = await _guard(_components(session, repo_id, root, paths))
+ owners, sources = await _guard_pair(_owners(root, paths, components))
+ code = _code_paths(paths)
+ inputs = EvidenceInputs(
+ code_paths=code, components=components, owners=owners, owner_sources=sources
+ )
+ items = (components_item(inputs), owners_item(inputs, code))
+ if isinstance(components, Unavailable):
+ return with_item(evidence, *items) # not kept: the next read tries again
+ return await _keep_resolved(session, repo_id, row, evidence, catalog, items)
+
+
def cached_evidence(row: Any) -> ChangeEvidence | None:
"""The kept checklist, or ``None`` when there is none in this schema."""
raw = getattr(row, "evidence_json", None)
@@ -522,6 +671,10 @@ async def _components(
"bus_factor": int(bus["value"]) if bus.get("basis") == "measured" else None,
}
)
+ if mine.unassigned:
+ # Resolution ran and these files belong to no component: a known answer.
+ catalog = "declared" if loaded.catalog.components else "derived"
+ rows.append({"outside": True, "source": catalog, "files": mine.unassigned})
return rows
@@ -826,6 +979,7 @@ __all__ = [
"build_stored_evidence",
"cached_evidence",
"change_evidence",
+ "components_stale",
"evidence_for_revspec",
"gather_inputs",
"keep_outcomes",
@@ -834,6 +988,7 @@ __all__ = [
"outcomes_stale",
"save_evidence",
"stored_change_at",
+ "with_current_components",
"with_current_outcomes",
"with_item",
]
diff --git a/packages/core/src/repowise/core/changes/evidence.py b/packages/core/src/repowise/core/changes/evidence.py
index ab9786c62..4605badc9 100644
--- a/packages/core/src/repowise/core/changes/evidence.py
+++ b/packages/core/src/repowise/core/changes/evidence.py
@@ -17,7 +17,9 @@ Detail rows a policy reads have fixed keys (the local change policy in
* ``components_touched``: ``{name, source, owner, criticality, tags, files,
bus_factor}``; ``owner`` is a team name or ``None``, ``bus_factor`` an int
- when measured, else ``None``;
+ when measured, else ``None``; then one ``{outside: true, source, files}`` row
+ for the changed files no component holds (``source`` is ``declared`` when
+ a catalog is declared, else ``derived``). A reader of components skips it;
* ``reaching_tests``: one row per changed source file, ``{path, tests, ...}``;
``tests`` lists test ids, ``[]`` only for a measured absence, ``None`` when
nothing knows;
@@ -126,12 +128,15 @@ class ChangeEvidence:
schema_version: int = EVIDENCE_SCHEMA_VERSION
#: The indexed commit the index facts were read at; ``None`` when unknown.
index_commit: str | None = None
+ #: The component catalog's digest when components were resolved
+ #: (``components.catalog.catalog_digest``); ``None`` when not recorded.
+ catalog_digest: str | None = None
def item(self, kind: str) -> EvidenceItem | None:
return next((i for i in self.items if i.kind == kind), None)
def to_dict(self) -> dict[str, Any]:
- return {
+ out = {
"schema_version": self.schema_version,
"change_id": self.change_id,
"revspec": self.revspec,
@@ -139,6 +144,9 @@ class ChangeEvidence:
"index_commit": self.index_commit,
"items": [i.to_dict() for i in self.items],
}
+ if self.catalog_digest is not None:
+ out["catalog_digest"] = self.catalog_digest
+ return out
@classmethod
def from_dict(cls, data: Mapping[str, Any]) -> ChangeEvidence:
@@ -148,6 +156,7 @@ class ChangeEvidence:
revspec=data.get("revspec"),
generated_at=data["generated_at"],
index_commit=data.get("index_commit"),
+ catalog_digest=data.get("catalog_digest"),
items=[EvidenceItem.from_dict(i) for i in data.get("items") or []],
)
@@ -261,7 +270,7 @@ def _components(inputs: EvidenceInputs) -> EvidenceItem:
label,
"ok",
"declared" if declared else "inferred",
- [r["name"] for r in rows],
+ [r["name"] for r in rows if not r.get("outside")],
rows,
source,
)
@@ -585,6 +594,13 @@ def _named_list(kind: str, value: Any, rows: list[Mapping[str, Any]]) -> _Line |
return (kind, {"count": len(value), **_names(value)}) if isinstance(value, list) else None
+def _components_line(kind: str, value: Any, rows: list[Mapping[str, Any]]) -> _Line | None:
+ if value == []:
+ files = sum(len(r.get("files") or ()) for r in rows if r.get("outside"))
+ return "components_outside", {"files": files}
+ return _named_list(kind, value, rows)
+
+
def _owners_line(kind: str, value: Any, rows: list[Mapping[str, Any]]) -> _Line | None:
if not isinstance(value, list):
return None
@@ -649,7 +665,7 @@ def _outcomes_line(kind: str, value: Any, rows: list[Mapping[str, Any]]) -> _Lin
#: Each kind's line from its value and rows; ``None`` reads as unknown.
_LINES: dict[str, Any] = {
- "components_touched": _named_list,
+ "components_touched": _components_line,
"suggested_reviewers": _named_list,
"owners": _owners_line,
"reaching_tests": _tests_line,
@@ -739,6 +755,7 @@ def _outcomes_text(key: str, p: Mapping[str, Any]) -> str:
_TEXT: dict[str, Any] = {
"unknown": lambda k, p: f"Not known: {p['reason']}" if p["reason"] else "Not known",
"components_touched": lambda k, p: f"{_n(p['count'], 'component')}: {_listed(p)}",
+ "components_outside": lambda k, p: f"Outside every component ({_n(p['files'], 'changed file')})",
"suggested_reviewers": lambda k, p: _listed(p),
"owners": _owners_text,
"reaching_tests": _tests_text,
diff --git a/packages/core/src/repowise/core/changes/period.py b/packages/core/src/repowise/core/changes/period.py
index 85d81bce8..64ac8ff77 100644
--- a/packages/core/src/repowise/core/changes/period.py
+++ b/packages/core/src/repowise/core/changes/period.py
@@ -5,7 +5,7 @@
(ids only), so changes indexed while it runs neither shift nor repeat a page.
A kept checklist is read back as
:func:`~repowise.core.changes.collect.change_evidence` reads it (its outcomes
-follow HEAD); a missing one is built and kept. What every build would repeat
+follow HEAD, its components the catalog); a missing one is built and kept. What every build would repeat
is done once for the period: the HEAD and window outcomes are read at, and the
deep fix-history walk the risk item stands on (one ``git log`` primes every
change's walk, see
@@ -215,21 +215,24 @@ async def _page_rows(run: _Pass, ids: list[str]) -> list[Any]:
async def _read_kept(
- run: _Pass, rows: Sequence[Any], key: Any
+ run: _Pass, rows: Sequence[Any], key: Any, catalog: str
) -> dict[str, ChangeEvidence | None]:
"""Each row's kept checklist (``None`` when none is kept), from the page
- already read. Only a checklist whose outcomes were read at another HEAD
- is read again, since that needs git for the change."""
+ already read. Only a checklist whose outcomes were read at another HEAD,
+ or whose components were resolved under another catalog, is read again."""
kept = {r.change_id: collect.cached_evidence(r) for r in rows}
stale = [
r
for r in rows
- if kept[r.change_id] is not None
- and await collect.outcomes_stale(run.root, kept[r.change_id], key)
+ if (got := kept[r.change_id]) is not None
+ and (
+ await collect.outcomes_stale(run.root, got, key)
+ or await collect.components_stale(run.root, got, catalog)
+ )
]
for row in stale:
kept[row.change_id] = await collect.change_evidence(
- run.session, run.repo_id, run.root, row, key=key
+ run.session, run.repo_id, run.root, row, key=key, catalog=catalog
)
return kept
@@ -249,6 +252,7 @@ async def period_evidence(
to_build = sum(request.refresh or not kept for _cid, kept in keys)
request.plan(to_build if request.build else 0, run.total)
key = await collect.outcomes_key(run.root)
+ catalog = await asyncio.to_thread(collect.catalog_digest, run.root)
prime = _Prime(str(run.root))
for start in range(0, run.total, PAGE):
ids = [cid for cid, _kept in keys[start : start + PAGE]]
@@ -260,7 +264,9 @@ async def period_evidence(
built = await _build_page(
run, missing, lambda r, s=start, ids=ids: s + ids.index(r.change_id) + 1
)
- kept = await _read_kept(run, [r for r in rows if r.change_id not in built], key)
+ kept = await _read_kept(
+ run, [r for r in rows if r.change_id not in built], key, catalog
+ )
await session.commit()
for row in rows:
yield row, built.get(row.change_id) or kept.get(row.change_id)
diff --git a/packages/core/src/repowise/core/components/catalog.py b/packages/core/src/repowise/core/components/catalog.py
index 0329b5ef2..edc269b0e 100644
--- a/packages/core/src/repowise/core/components/catalog.py
+++ b/packages/core/src/repowise/core/components/catalog.py
@@ -19,6 +19,7 @@ left out of the catalog.
from __future__ import annotations
+import hashlib
import re
from dataclasses import dataclass, field
from pathlib import Path
@@ -165,6 +166,20 @@ def read_catalog(repo_root: Path | str) -> Catalog:
return catalog
+def catalog_digest(repo_root: Path | str) -> str:
+ """A digest of the catalog files as they are on disk; one value when there are none."""
+ digest = hashlib.sha256()
+ root = Path(repo_root)
+ for rel in CATALOG_FILES:
+ try:
+ data = (root / rel).read_bytes()
+ except OSError:
+ continue
+ digest.update(f"{rel}\0{len(data)}\0".encode())
+ digest.update(data)
+ return digest.hexdigest()[:16]
+
+
def parse_into(catalog: Catalog, text: str, source: str) -> None:
"""Add the entities of one multi-document YAML file to *catalog*."""
try:
diff --git a/packages/core/src/repowise/core/policy/rules.py b/packages/core/src/repowise/core/policy/rules.py
index 1c91f25eb..666796011 100644
--- a/packages/core/src/repowise/core/policy/rules.py
+++ b/packages/core/src/repowise/core/policy/rules.py
@@ -12,7 +12,7 @@ revspec, generated_at, items: [{kind, label, status, basis, value, details,
source}]}``, and only these detail fields:
* ``components_touched``: rows ``{name, criticality, tags, owner, files,
- bus_factor}``;
+ bus_factor}``, and an ``{outside: true, files}`` row that names no component;
* ``provenance``: ``value`` is the change's label (``agent``,
``human_attested`` or ``unknown``), or a mapping holding it as ``label``;
rows ``{sha, label, tier}``;
@@ -390,7 +390,8 @@ def _rows(item: Mapping[str, Any] | None) -> list[Mapping[str, Any]]:
def _rule_result(rule: Rule, items: Mapping[str, Mapping[str, Any]]) -> RuleResult:
comps_item = items.get("components_touched")
- touched = _rows(comps_item) if _known(comps_item) else []
+ # The row for files outside every component is no component.
+ touched = [r for r in _rows(comps_item) if not r.get("outside")] if _known(comps_item) else []
used: dict[str, str] = {}
if rule.match or rule.exclude:
if not _known(comps_item):
diff --git a/packages/core/src/repowise/core/report/change_answers.py b/packages/core/src/repowise/core/report/change_answers.py
index b0b8dcfef..6a44f1d12 100644
--- a/packages/core/src/repowise/core/report/change_answers.py
+++ b/packages/core/src/repowise/core/report/change_answers.py
@@ -295,7 +295,11 @@ def _components(items: dict[str, Any]) -> list[dict[str, Any]]:
comps = items.get("components_touched")
if not _known(comps):
return []
- return [{"name": r["name"], "team": r.get("owner")} for r in comps.get("details") or ()]
+ return [
+ {"name": r["name"], "team": r.get("owner")}
+ for r in comps.get("details") or ()
+ if not r.get("outside")
+ ]
def _checklist(evidence: dict[str, Any], kept: bool) -> dict[str, Any]:
@@ -342,6 +346,7 @@ def entry(
kept = evidence is not None
evidence = evidence or {"items": []}
answers = _answers(record, evidence, kept, context)
+ items = {i["kind"]: i for i in evidence.get("items") or ()}
return {
"id": record["id"],
"ref": record["forge_ref"] or record["id"],
@@ -352,7 +357,9 @@ def entry(
"files_changed": record["files_changed"],
"lines_added": record["lines_added"],
"lines_deleted": record["lines_deleted"],
- "components": _components({i["kind"]: i for i in evidence.get("items") or ()}),
+ "components": _components(items),
+ # Known and empty: every file is outside every component.
+ "components_known": _known(items.get("components_touched")),
**answers,
"complete": all(answers[k]["status"] == "known" for k in ANSWERS),
"checklist": _checklist(evidence, kept),
diff --git a/packages/core/src/repowise/core/report/sections/changes.py b/packages/core/src/repowise/core/report/sections/changes.py
index f684bdc71..2929052f1 100644
--- a/packages/core/src/repowise/core/report/sections/changes.py
+++ b/packages/core/src/repowise/core/report/sections/changes.py
@@ -221,7 +221,8 @@ def _change_lines(e: dict[str, Any]) -> dict[str, str]:
for c in e["components"]
)
return {
- "components": comps or "none known",
+ "components": comps
+ or ("outside every component" if e.get("components_known") else "none known"),
"accountable": e["accountable"]["text"],
"review": e["review"]["text"],
"tests": e["tests"]["text"],
@@ -407,9 +408,10 @@ def _outcome_summary(entries: list[dict[str, Any]]) -> dict[str, Any]:
def _component_summary(entries: list[dict[str, Any]]) -> dict[str, Any]:
per: dict[str, dict[str, Any]] = {}
- untouched = 0
+ untouched = outside = 0
for e in entries:
untouched += not e["components"]
+ outside += not e["components"] and bool(e.get("components_known"))
for c in e["components"]:
slot = per.setdefault(c["name"], {"changes": 0, "teams": set()})
slot["changes"] += 1
@@ -417,7 +419,10 @@ def _component_summary(entries: list[dict[str, Any]]) -> dict[str, Any]:
rows = sorted(per.items(), key=lambda kv: (-kv[1]["changes"], kv[0]))
return check(
"components",
- reason=f"{len(per)} component(s) changed; {untouched} change(s) with no known component",
+ reason=(
+ f"{len(per)} component(s) changed; {outside} change(s) outside every component, "
+ f"{untouched - outside} with components not known"
+ ),
details=capped(
[
f"{name}: {v['changes']} change(s); "
@@ -430,6 +435,7 @@ def _component_summary(entries: list[dict[str, Any]]) -> dict[str, Any]:
data={
"components": {n: {"changes": v["changes"], "teams": sorted(v["teams"])} for n, v in rows},
"without_component": untouched,
+ "outside_every_component": outside,
},
)
@@ -563,7 +569,8 @@ def _snapshot_reason(ctx: ReportContext) -> str:
return (
"Each checklist is kept from its first build, stamped with when it was built and "
f"the indexed commit it read ({head} for this report); outcomes are read again "
- "whenever HEAD moves, and --refresh rebuilds every checklist."
+ "whenever HEAD moves, components and owners whenever the component catalog "
+ "changes, and --refresh rebuilds every checklist."
)
diff --git a/packages/server/src/repowise/server/routers/changes.py b/packages/server/src/repowise/server/routers/changes.py
index a1e033da6..fc97e57a3 100644
--- a/packages/server/src/repowise/server/routers/changes.py
+++ b/packages/server/src/repowise/server/routers/changes.py
@@ -14,6 +14,7 @@ from repowise.core.attribution import attribution_enabled
from repowise.core.changes.collect import (
build_stored_evidence,
cached_evidence,
+ components_stale,
evidence_summary,
keep_outcomes,
list_needing_attention,
@@ -21,6 +22,7 @@ from repowise.core.changes.collect import (
outcomes_key,
outcomes_stale,
save_evidence,
+ with_current_components,
with_item,
)
from repowise.core.changes.evidence import ChangeEvidence, item_line
@@ -197,12 +199,15 @@ async def get_change(
if evidence:
kept = None if refresh else cached_evidence(row)
repo = await crud.get_repository(session, repo_id)
- # A kept checklist is current but for ``outcomes``, which follows HEAD.
+ # A kept checklist is current but for ``outcomes``, which follows HEAD,
+ # and components, which follow the catalog.
task = None
factory = resolve_request_session_factory(request)
if kept is None:
task = _build(factory, repo_id, row.change_id, repo.local_path)
- elif await outcomes_stale(repo.local_path, kept):
+ elif await outcomes_stale(repo.local_path, kept) or await components_stale(
+ repo.local_path, kept
+ ):
task = _build(factory, repo_id, row.change_id, repo.local_path, kept)
if task is not None:
try:
@@ -255,14 +260,20 @@ async def _build_and_keep(factory: Any, repo_id: str, change_id: str, root: str)
async def _outcomes_and_keep(
factory: Any, repo_id: str, change_id: str, root: str, kept: ChangeEvidence
) -> ChangeEvidence:
- """Read the outcomes item, then merge only it into what is stored by then."""
+ """Read the outcomes item, then merge only it into what is stored by then;
+ then resolve components again if the catalog changed."""
key = await outcomes_key(root)
async with get_session(factory) as session:
row = await crud.get_change(session, repo_id, change_id)
item = await outcomes_item(session, repo_id, root, row, key)
async with get_session(factory) as session:
merged = await keep_outcomes(session, repo_id, change_id, item)
- return merged or with_item(kept, item)
+ async with get_session(factory) as session:
+ row = await crud.get_change(session, repo_id, change_id)
+ current = merged or with_item(kept, item)
+ if row is None: # deleted meanwhile
+ return current
+ return await with_current_components(session, repo_id, root, row, current)
def _when(value: str | None, field: str) -> datetime | None:
diff --git a/packages/web/messages/en.json b/packages/web/messages/en.json
index f877211ca..c0b6f59a9 100644
--- a/packages/web/messages/en.json
+++ b/packages/web/messages/en.json
@@ -442,6 +442,7 @@
"unknown": "Not known: {reason}",
"unknownBare": "Not known",
"components_touched": "{count, plural, one {# component} other {# components}}: {names}{more, plural, =0 {} other { and # more}}",
+ "components_outside": "Outside every component ({files, plural, one {# changed file} other {# changed files}})",
"suggested_reviewers": "{names}{more, plural, =0 {} other { and # more}}",
"owners": "{count, plural, =0 {No declared owner} other {{names}{more, plural, =0 {} other { and # more}}}}{unowned, plural, =0 {} one {; # changed file without one} other {; # changed files without one}}",
"reaching_tests": "{files, plural, =0 {No changed source file} one {{reached} of # changed file reached by a test} other {{reached} of # changed files reached by a test}}{absent, plural, =0 {} other {; # with none}}{unknown, plural, =0 {} other {; # not known}}",
diff --git a/packages/web/messages/zh-CN.json b/packages/web/messages/zh-CN.json
index 93651c8e8..59815ab62 100644
--- a/packages/web/messages/zh-CN.json
+++ b/packages/web/messages/zh-CN.json
@@ -442,6 +442,7 @@
"unknown": "未知:{reason}",
"unknownBare": "未知",
"components_touched": "{count} 个组件:{names}{more, plural, =0 {} other {等另外 # 个}}",
+ "components_outside": "不属于任何组件({files} 个变更文件)",
"suggested_reviewers": "{names}{more, plural, =0 {} other {等另外 # 人}}",
"owners": "{count, plural, =0 {无声明的负责人} other {{names}{more, plural, =0 {} other {等另外 # 个}}}}{unowned, plural, =0 {} other {;# 个变更文件无负责人}}",
"reaching_tests": "{files, plural, =0 {没有变更的源文件} other {# 个变更文件中有 {reached} 个被测试覆盖}}{absent, plural, =0 {} other {;# 个没有测试}}{unknown, plural, =0 {} other {;# 个未知}}",
diff --git a/packages/web/src/lib/changes.test.ts b/packages/web/src/lib/changes.test.ts
index 2bd952d4f..795efb6ed 100644
--- a/packages/web/src/lib/changes.test.ts
+++ b/packages/web/src/lib/changes.test.ts
@@ -10,6 +10,7 @@ const LINES: [string, Record<string, unknown>][] = [
["unknown", { reason: "not gathered for this change" }],
["unknown", { reason: "" }],
["components_touched", { count: 2, names: "core, web", more: 0 }],
+ ["components_outside", { files: 3 }],
["suggested_reviewers", { count: 8, names: "a, b, c, d, e, f", more: 2 }],
["owners", { count: 1, names: "@core", more: 0, unowned: 3 }],
["owners", { count: 0, names: "", more: 0, unowned: 1 }],
diff --git a/tests/unit/cli/test_changes_cmd.py b/tests/unit/cli/test_changes_cmd.py
index f55c62741..1337dee1c 100644
--- a/tests/unit/cli/test_changes_cmd.py
+++ b/tests/unit/cli/test_changes_cmd.py
@@ -110,7 +110,7 @@ def _fake_evidence(monkeypatch):
calls: list[str] = []
- async def _evidence(session, repo_id, root, row, *, refresh=False, key=None):
+ async def _evidence(session, repo_id, root, row, *, refresh=False, key=None, catalog=None):
calls.append(row.change_id)
return ChangeEvidence(
change_id=row.change_id,
diff --git a/tests/unit/core/test_change_evidence.py b/tests/unit/core/test_change_evidence.py
index d678344ef..694904579 100644
--- a/tests/unit/core/test_change_evidence.py
+++ b/tests/unit/core/test_change_evidence.py
@@ -629,3 +629,130 @@ async def test_without_an_index_only_git_items_are_filled(repo):
assert by["owners"].details == [{"reason": "the repository has no index"}]
assert by["health_delta"].status in {"ok", "attention"}
assert evidence.index_commit is None
+
+
+def test_files_outside_every_component_are_a_known_answer():
+ outside = {"outside": True, "source": "declared", "files": ["README.md", ".github/ci.yml"]}
+ inputs = dataclasses.replace(_full_inputs(), components=[outside])
+ evidence = build_change_evidence(_bundle(["README.md", ".github/ci.yml"]), inputs, change_id="c", revspec="r")
+ item = evidence.item("components_touched")
+ assert (item.status, item.basis, item.value) == ("ok", "declared", [])
+ assert line_text(item_line(item.to_dict())) == "Outside every component (2 changed files)"
+ mixed = dataclasses.replace(_full_inputs(), components=[*_full_inputs().components, outside])
+ item = build_change_evidence(_bundle(["src/a.py"]), mixed, change_id="c", revspec="r").item(
+ "components_touched"
+ )
+ assert item.value == ["core"] and line_text(item_line(item.to_dict())) == "1 component: core"
+
+
+_CATALOG = """\
+apiVersion: backstage.io/v1alpha1
+kind: Component
+metadata:
+ name: {name}
+ annotations:
+ repowise.dev/paths: {paths}
+spec: {{type: library, lifecycle: production, owner: group:default/{name}-team}}
+"""
+
+
+async def _set_files(factory, repo_id: str, paths: list[str], total: int) -> None:
+ from sqlalchemy import update
+
+ from repowise.core.persistence.database import get_session
+ from repowise.core.persistence.models import Change
+
+ files = json.dumps([{"path": p, "added": 1, "deleted": 0} for p in paths])
+ async with get_session(factory) as session:
+ await session.execute(
+ update(Change)
+ .where(Change.repository_id == repo_id, Change.change_id == "pr-7")
+ .values(files_json=files, files_changed=total)
+ )
+
+
[email protected]("_private_user_config")
+async def test_a_catalog_edit_is_applied_to_a_kept_checklist_on_read(tmp_path, repo):
+ from repowise.core.changes.collect import (
+ CATALOG_CHANGED,
+ cached_evidence,
+ change_evidence,
+ components_stale,
+ )
+ from repowise.core.persistence.crud import get_change
+ from repowise.core.persistence.database import get_session
+
+ root, head = repo
+ catalog = root / ".repowise" / "components.yaml"
+ catalog.parent.mkdir()
+ catalog.write_text(_CATALOG.format(name="core", paths="src/core/**"), encoding="utf-8")
+ engine, factory, repo_id = await _index(tmp_path, root, head)
+ paths = ["src/core/a.py", "src/web.py"]
+ await _set_files(factory, repo_id, paths, len(paths))
+ try:
+ async with get_session(factory) as session:
+ first = await change_evidence(session, repo_id, root, await get_change(session, repo_id, "pr-7"))
+ comps = first.item("components_touched")
+ assert comps.value == ["core"]
+ assert comps.details[-1] == {"outside": True, "source": "declared", "files": ["src/web.py"]}
+
+ # The catalog gains a component for src/web.py: read back without a rebuild.
+ second = _CATALOG.format(name="web", paths="src/web.py")
+ catalog.write_text(catalog.read_text(encoding="utf-8") + "---\n" + second, encoding="utf-8")
+ async with get_session(factory) as session:
+ got = await change_evidence(session, repo_id, root, await get_change(session, repo_id, "pr-7"))
+ comps = got.item("components_touched")
+ assert comps.value == ["core", "web"] and not any(r.get("outside") for r in comps.details)
+ assert got.item("owners").value == ["@team-core", "web-team"]
+ assert got.generated_at == first.generated_at and got.catalog_digest != first.catalog_digest
+ async with get_session(factory) as session:
+ stored = cached_evidence(await get_change(session, repo_id, "pr-7"))
+ assert stored.to_dict() == got.to_dict()
+
+ # A capped file list cannot be resolved again: unknown, naming --refresh,
+ # kept under the new digest so the next read does no work.
+ await _set_files(factory, repo_id, paths, 5000)
+ catalog.write_text(_CATALOG.format(name="core", paths="src/**"), encoding="utf-8")
+ async with get_session(factory) as session:
+ capped = await change_evidence(session, repo_id, root, await get_change(session, repo_id, "pr-7"))
+ comps = capped.item("components_touched")
+ assert comps.status == "unknown" and comps.details == [{"reason": CATALOG_CHANGED}]
+ async with get_session(factory) as session:
+ stored = cached_evidence(await get_change(session, repo_id, "pr-7"))
+ assert stored.to_dict() == capped.to_dict()
+ assert not await components_stale(root, stored)
+ finally:
+ await engine.dispose()
+
+
[email protected]("_private_user_config")
+async def test_a_capped_checklist_kept_before_digests_keeps_its_components(tmp_path, repo):
+ from repowise.core.changes.collect import (
+ cached_evidence,
+ change_evidence,
+ components_stale,
+ save_evidence,
+ )
+ from repowise.core.persistence.crud import get_change
+ from repowise.core.persistence.database import get_session
+
+ root, head = repo
+ engine, factory, repo_id = await _index(tmp_path, root, head)
+ await _set_files(factory, repo_id, ["src/core/a.py"], 5000)
+ comps = EvidenceItem("components_touched", "Components touched", "ok", "inferred", ["core"],
+ [{"name": "core", "source": "directory", "files": ["src/core/a.py"]}], "components")
+ legacy = ChangeEvidence("pr-7", head, "2026-01-01T00:00:00+00:00", [comps])
+ try:
+ async with get_session(factory) as session:
+ await save_evidence(session, repo_id, "pr-7", legacy)
+ async with get_session(factory) as session:
+ got = await change_evidence(session, repo_id, root, await get_change(session, repo_id, "pr-7"))
+ assert got.item("components_touched") == comps
+ async with get_session(factory) as session:
+ stored = cached_evidence(await get_change(session, repo_id, "pr-7"))
+ assert stored.item("components_touched") == comps and stored.catalog_digest is not None
+ assert not await components_stale(root, stored)
+ finally:
+ await engine.dispose()
diff --git a/tests/unit/core/test_change_outcomes.py b/tests/unit/core/test_change_outcomes.py
index b2da7fb5d..adf71696e 100644
--- a/tests/unit/core/test_change_outcomes.py
+++ b/tests/unit/core/test_change_outcomes.py
@@ -480,7 +480,9 @@ async def test_a_legacy_checklist_gains_outcomes_and_a_merge_keeps_a_newer_rebui
async with get_session(factory) as session:
row = await get_change(session, repo_id, "pr-7")
got = await change_evidence(session, repo_id, root, row)
- assert [i.kind for i in got.items] == ["health_delta", "outcomes"]
+ # Kept with no catalog digest, so its components and owners are resolved too.
+ kinds = ["components_touched", "owners", "health_delta", "outcomes"]
+ assert [i.kind for i in got.items] == kinds
assert got.generated_at == legacy.generated_at
async with get_session(factory) as session:
stored = cached_evidence(await get_change(session, repo_id, "pr-7"))
diff --git a/tests/unit/core/test_report_changes.py b/tests/unit/core/test_report_changes.py
index e150e2ecb..fec9fa0d7 100644
--- a/tests/unit/core/test_report_changes.py
+++ b/tests/unit/core/test_report_changes.py
@@ -657,3 +657,18 @@ def test_a_newline_in_a_title_survives_the_csv():
]}]}
(row,) = list(csv.DictReader(io.StringIO(render_csv(doc))))
assert row["title"] == "fix:\nsecond line" and row["reason"] == "line one\n=line two"
+
+
+def test_a_change_outside_every_component_is_told_apart_from_an_unknown_one():
+ from repowise.core.report.sections.changes import _component_summary
+
+ entries = [
+ {"components": [], "components_known": True},
+ {"components": [], "components_known": False},
+ {"components": [{"name": "payments", "team": None}], "components_known": True},
+ ]
+ summary = _component_summary(entries)
+ assert summary["reason"] == (
+ "1 component(s) changed; 1 change(s) outside every component, 1 with components not known"
+ )
+ assert summary["data"]["outside_every_component"] == 1
diff --git a/tests/unit/server/mcp/test_change_risk.py b/tests/unit/server/mcp/test_change_risk.py
index 352990930..4a831d9b0 100644
--- a/tests/unit/server/mcp/test_change_risk.py
+++ b/tests/unit/server/mcp/test_change_risk.py
@@ -831,6 +831,7 @@ async def test_evidence_for_a_stored_change_is_its_kept_record(tmp_path, monkeyp
from sqlalchemy.exc import OperationalError
+ from repowise.core.components.catalog import catalog_digest
from repowise.core.persistence import upsert_repository
from repowise.core.persistence.crud import upsert_changes
@@ -849,6 +850,8 @@ async def test_evidence_for_a_stored_change_is_its_kept_record(tmp_path, monkeyp
"generated_at": "2026-10-14T00:00:00+00:00",
"index_commit": None,
"items": [],
+ # Resolved under the catalog on disk, so components are not read again.
+ "catalog_digest": catalog_digest(repo),
}
async with factory() as session:
row = await upsert_repository(session, name="repo", local_path=str(repo))
diff --git a/tests/unit/server/test_changes_routes.py b/tests/unit/server/test_changes_routes.py
index 3dc9b4522..47412179e 100644
--- a/tests/unit/server/test_changes_routes.py
+++ b/tests/unit/server/test_changes_routes.py
@@ -116,6 +116,7 @@ def _fake_build(monkeypatch, seen: list[str], gate=None):
import asyncio
from repowise.core.changes.evidence import ChangeEvidence, EvidenceItem
+ from repowise.core.components.catalog import catalog_digest
from repowise.server.routers import changes as route
async def _build(session, repo_id, root, row):
@@ -138,6 +139,8 @@ def _fake_build(monkeypatch, seen: list[str], gate=None):
"change health",
)
],
+ # As a real build: resolved under the catalog on disk.
+ catalog_digest=catalog_digest(root),
)
async def _current(_root, _evidence):
diff --git a/tests/unit/test_policy_rules.py b/tests/unit/test_policy_rules.py
index 97151add1..87c038351 100644
--- a/tests/unit/test_policy_rules.py
+++ b/tests/unit/test_policy_rules.py
@@ -179,6 +179,35 @@ def test_exclude_removes_a_matched_component():
assert result.outcome == "not_applicable"
+OUTSIDE = {"outside": True, "source": "declared", "files": [".github/ci.yml", "README.md"]}
+
+
+def test_a_change_outside_every_component_is_not_applicable_to_a_match():
+ # Resolution ran and no component holds the files: known, so the match answers.
+ outside = _item("components_touched", [OUTSIDE], value=[], basis="declared")
+ (result,) = evaluate(parse_policy(PCI_RULE), _evidence(outside, _provenance("agent")))
+ assert result.outcome == "not_applicable"
+ exclude_only = parse_policy(
+ "rules: [{name: x, exclude: {components: {names: [docs]}}, when: {attribution: agent}, action: warn}]"
+ )
+ (result,) = evaluate(exclude_only, _evidence(outside, _provenance("agent")))
+ assert result.outcome == "not_applicable"
+
+
+def test_unresolved_components_keep_a_match_unknown():
+ unresolved = _item(
+ "components_touched", [{"reason": "not gathered"}], status="unknown", basis="unresolved"
+ )
+ (result,) = evaluate(parse_policy(PCI_RULE), _evidence(unresolved, _provenance("agent")))
+ assert result.outcome == "unknown"
+
+
+def test_the_outside_row_is_no_component_to_a_rule_over_the_whole_change():
+ policy = parse_policy("rules: [{name: b, when: {bus_factor_below: 2}, action: warn}]")
+ (result,) = evaluate(policy, _evidence(_components(PAYMENTS, OUTSIDE)))
+ assert result.outcome == "triggered" and result.components == ["payments"]
+
+
def test_unknown_evidence_never_fires():
policy = parse_policy(PCI_RULE)
no_tests = _evidence(