Skip to content

Commit bebee98

Browse files
tzhouamclaude
andcommitted
Add depth-bounded module scan and route coverage metrics for kb init
kb init (design v3 section 7) measures how much of a repository its knowledge routes reach, first per module, then weighted by merged-PR churn. profiles/establish.scan_modules_at_depth: directory modules at most `depth` levels below each source root; modules under `min_loc` non-blank lines fold into their parent until stable; roots never fold; nested roots own their files; hidden and non-code dirs skipped at every level; exclude globs; unknown language scans nothing. kb_service/init_coverage: load_owners (_routes.yaml owners), routes_file, module_coverage (every file routed), make_include, pr_weighted_coverage (once per PR; routed and rule-bearing ratios; uncovered hot paths), churn_by_module (longest module prefix). Pure, no repo literals. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 8cb9045 commit bebee98

5 files changed

Lines changed: 449 additions & 5 deletions

File tree

‎doc/architecture/SPEC/kb_service.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -322,3 +322,14 @@ x 必须为正。因阈值停下的调用(`stop_reason="max_budget"`)→ `Mo
322322
((0, 1],缺省 0.85)、`budget_usd`(>0,缺省 30)、`judge_call_usd`(≥0,缺省 0.50)。`validate_seeds(init,
323323
knowledge_root)` 是运行时检查:种子必须是知识树中已存在的文件或目录,解析后不得逃出知识根目录,逐条返回问题。
324324
解析只做静态校验,不读知识树。测试:`test_kb_init_config.py`。
325+
326+
## 2026-09-30 kb init:覆盖率度量
327+
`init_coverage`(纯函数,stdlib + PyYAML,不调模型):`load_owners(routes_yaml_text)` 读 `_routes.yaml` 的 `owners`
328+
(schema_version 1;`models` 按名称匹配,不参与覆盖率;格式错误抛 `ValueError`);`routes_file(path, owners)` 按
329+
`scope_prefixes` 前缀匹配、保持路由顺序;`module_coverage(modules, owners)` —— 模块内**每个**源文件都被某个 owner 前缀
330+
覆盖才算覆盖;`make_include(source_roots, exclude, suffixes=())` 构造变更路径过滤器(测试/文档等一律由调用方的
331+
`exclude` glob 表达,不内置任何仓库字面量);`pr_weighted_coverage(prs, owners, include=, rule_pages=)` —— 每个 PR
332+
改动的每个文件计一次,`routed` = 被某 owner 覆盖,`rule_bearing` = 覆盖它的 owner 页在 `rule_pages`(含有效规则的页)
333+
中,`uncovered_hot` 按次数降序、路径升序;`churn_by_module(prs, modules)` 按最长模块前缀归属(已折叠目录归到折入的
334+
祖先),降序。空集合的比例记为 1.0(没有可漏的路由)。`ROOT_MODULE` 与 `profiles.establish.ROOT_MODULE` 相同,
335+
由测试钉住(本包不依赖 `profiles`)。源根与变更路径按与 `profiles.establish.normalize_root` 相同的规则规范化(`.`、`./` 表示仓库根,接纳一切路径)。测试:`test_kb_init_coverage.py`。

‎doc/architecture/SPEC/profiles/establish.md‎

Lines changed: 7 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,24 @@
11
# profiles/establish.py —— 规范
22

3-
<!-- verified-against: 2026-08-18 -->
3+
<!-- verified-against: 2026-09-30 -->
44

5-
`LOC ~107 · profile(Stage 0–1.5 helper) · refactor-status: ok`
5+
`LOC ~180 · profile(Stage 0–1.5 helper) · refactor-status: ok`
66

77
## 职责
88
确定性的建立期 helper。
99

1010
## 公开契约
1111
`fact_id`、`build_doc_corpus`、`is_redundant`、`extract_directives`、
12-
`scan_modules`、`HUMAN_DOC_NAMES`。
12+
`scan_modules`、`scan_modules_at_depth`、`normalize_root`、`ROOT_MODULE`、`HUMAN_DOC_NAMES`。
1313

1414
## 不变量
1515
- `is_redundant`(对 README+docs 做 6 词 shingle)会丢弃任何**仓库自己的文档已经写过**
1616
的 briefing 行(ETH 研究那条规则,**D5**)。
1717
- `scan_modules` 是确定性的、按语言索引的,跳过非代码目录。
1818
- `extract_directives` 限制行长(只收短祈使句)。
19+
- `scan_modules_at_depth`(kb init 的模块定义):源根以下至多 `depth` 层目录为模块,更深的文件归最深的那层祖先;
20+
非空行少于 `min_loc` 的模块由深到浅折入父目录模块,直到稳定;源根永不折叠(`normalize_root` 先把 `.`、`./pkg`、`/pkg/` 等写法规范化,仓库根为 `""` 且包含其他根,保证折叠必然终止);嵌套源根各自拥有自己的文件;
21+
每一层都跳过隐藏目录与非代码目录;`exclude` 按仓库相对路径做 fnmatch;未知语言返回 `{}`;结果确定、有序。
1922

2023
## 边界 —— 不属于这里
2124
纯确定性 helper —— 不含 LLM、不写 store、不含 step 逻辑。
@@ -24,7 +27,7 @@
2427
仅 stdlib。
2528

2629
## 测试
27-
`test_profile_steps.py`(冗余过滤、模块扫描、指令抽取)。
30+
`test_profile_steps.py`(冗余过滤、模块扫描、指令抽取);`test_kb_init_coverage.py`(按深度的模块扫描)。
2831

2932
## 重构备注
3033
纯函数 —— 易测、易复用。冗余过滤器是承载 ETH 研究结论的关键防线;**保持它确定性**。
Lines changed: 168 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,168 @@
1+
"""Coverage metrics for ``kb init`` (design: kb-init v3 §7).
2+
3+
Pure and deterministic. Two measures of how much of a repository its
4+
knowledge routes reach:
5+
6+
* **module coverage** — the share of modules (``profiles.establish.
7+
scan_modules_at_depth``) whose every source file matches some owner's
8+
``scope_prefixes`` in ``_routes.yaml``;
9+
* **PR-weighted coverage** — over a window of merged PRs, the share of changed
10+
source files (counted once per PR that changed them) that route to an owner
11+
(*routed*), and to an owner whose page carries rules (*rule-bearing*).
12+
13+
An empty population counts as fully covered (ratio 1.0): there is nothing a
14+
route could miss.
15+
"""
16+
17+
from __future__ import annotations
18+
19+
import fnmatch
20+
from collections import Counter
21+
from dataclasses import dataclass
22+
from pathlib import PurePosixPath
23+
from typing import Callable, Mapping, Sequence
24+
25+
import yaml
26+
27+
# equals profiles.establish.ROOT_MODULE (kb_service stays free of profile
28+
# imports; a test pins the two together)
29+
ROOT_MODULE = "./"
30+
31+
32+
@dataclass(frozen=True)
33+
class Owner:
34+
owner: str
35+
path: str
36+
prefixes: tuple[str, ...]
37+
38+
39+
@dataclass(frozen=True)
40+
class Coverage:
41+
covered: list[str]
42+
uncovered: list[str]
43+
ratio: float
44+
45+
46+
@dataclass(frozen=True)
47+
class PrCoverage:
48+
total: int
49+
routed: int
50+
rule_bearing: int
51+
routed_ratio: float
52+
rule_bearing_ratio: float
53+
uncovered_hot: list[tuple[str, int]]
54+
55+
56+
def load_owners(routes_yaml_text: str) -> list[Owner]:
57+
"""The ``owners`` of a ``_routes.yaml`` (schema_version 1); ``models`` are
58+
name-matched, not path-matched, and play no part in coverage."""
59+
data = yaml.safe_load(routes_yaml_text) or {}
60+
if not isinstance(data, dict):
61+
raise ValueError("_routes.yaml must be a mapping")
62+
if data.get("schema_version", 1) != 1:
63+
raise ValueError(f"unsupported _routes.yaml schema_version {data.get('schema_version')!r}")
64+
owners = data.get("owners") or []
65+
if not isinstance(owners, list):
66+
raise ValueError("_routes.yaml owners must be a list")
67+
out = []
68+
for item in owners:
69+
if not isinstance(item, dict) or not item.get("owner") or not item.get("path"):
70+
raise ValueError(f"malformed _routes.yaml owner: {item!r}")
71+
prefixes = item.get("scope_prefixes") or []
72+
if not isinstance(prefixes, list) or any(not isinstance(p, str) or not p for p in prefixes):
73+
raise ValueError(f"{item['owner']}: scope_prefixes must be a list of non-empty strings")
74+
out.append(Owner(str(item["owner"]), str(item["path"]), tuple(prefixes)))
75+
return out
76+
77+
78+
def routes_file(path: str, owners: Sequence[Owner]) -> list[Owner]:
79+
"""Every owner whose scope prefixes reach ``path``, in routing order."""
80+
return [o for o in owners if any(path.startswith(p) for p in o.prefixes)]
81+
82+
83+
def module_coverage(modules: Mapping[str, Mapping], owners: Sequence[Owner]) -> Coverage:
84+
covered, uncovered = [], []
85+
for key in sorted(modules):
86+
files = modules[key].get("files") or []
87+
(covered if all(routes_file(f, owners) for f in files) else uncovered).append(key)
88+
total = len(covered) + len(uncovered)
89+
return Coverage(covered, uncovered, len(covered) / total if total else 1.0)
90+
91+
92+
def _normalize(path: str) -> str:
93+
"""Repo-relative POSIX form without leading ``./`` or slashes; the repository
94+
root is ``""`` (same rule as ``profiles.establish.normalize_root``)."""
95+
text = PurePosixPath(path.strip().strip("/") or ".").as_posix()
96+
return "" if text == "." else text
97+
98+
99+
def make_include(source_roots: Sequence[str], exclude: Sequence[str],
100+
suffixes: Sequence[str] = ()) -> Callable[[str], bool]:
101+
"""A filter for changed paths: under a source root (any path when none are
102+
given), with a source suffix (any when none are given), matching no
103+
``exclude`` fnmatch glob. Tests, docs and generated files are the caller's
104+
``exclude`` globs; nothing repository-specific is built in."""
105+
normalized = {_normalize(r) for r in source_roots}
106+
# the repository root (".", "./", "") admits every path
107+
roots = () if "" in normalized else tuple(sorted(r + "/" for r in normalized))
108+
sfx = tuple(suffixes)
109+
110+
def include(path: str) -> bool:
111+
path = _normalize(path)
112+
if roots and not path.startswith(roots):
113+
return False
114+
if sfx and not path.endswith(sfx):
115+
return False
116+
return not any(fnmatch.fnmatch(path, glob) for glob in exclude)
117+
118+
return include
119+
120+
121+
def pr_weighted_coverage(prs: Sequence[Sequence[str]], owners: Sequence[Owner], *,
122+
include: Callable[[str], bool],
123+
rule_pages: set[str] | None = None) -> PrCoverage:
124+
"""Each file a PR changes counts once for that PR. ``rule_pages`` are the
125+
knowledge paths (as ``_routes.yaml`` names them) holding at least one
126+
active rule; without them nothing is rule-bearing."""
127+
pages = rule_pages or set()
128+
total = routed = rule_bearing = 0
129+
missed: Counter[str] = Counter()
130+
for files in prs:
131+
for path in sorted({_normalize(f) for f in files}):
132+
if not include(path):
133+
continue
134+
total += 1
135+
hits = routes_file(path, owners)
136+
if hits:
137+
routed += 1
138+
if any(o.path in pages for o in hits):
139+
rule_bearing += 1
140+
else:
141+
missed[path] += 1
142+
hot = sorted(missed.items(), key=lambda item: (-item[1], item[0]))
143+
return PrCoverage(total, routed, rule_bearing,
144+
routed / total if total else 1.0,
145+
rule_bearing / total if total else 1.0, hot)
146+
147+
148+
def module_of(path: str, modules: Mapping[str, Mapping]) -> str | None:
149+
"""The module owning ``path``: the longest module key that prefixes it (a
150+
file in a folded directory belongs to the ancestor it folded into)."""
151+
best = None
152+
for key in modules:
153+
prefix = "" if key == ROOT_MODULE else key
154+
if path.startswith(prefix) and (best is None or len(prefix) > len(best[1])):
155+
best = (key, prefix)
156+
return best[0] if best else None
157+
158+
159+
def churn_by_module(prs: Sequence[Sequence[str]], modules: Mapping[str, Mapping]) -> list[tuple[str, int]]:
160+
"""File changes per module over the PR window, highest first (ties by
161+
module path). Paths no module owns are not counted."""
162+
counts: Counter[str] = Counter()
163+
for files in prs:
164+
for path in sorted({_normalize(f) for f in files}):
165+
key = module_of(path, modules)
166+
if key is not None:
167+
counts[key] += 1
168+
return sorted(counts.items(), key=lambda item: (-item[1], item[0]))

‎src/infermatrix_copilot/profiles/establish.py‎

Lines changed: 88 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -7,9 +7,11 @@
77

88
from __future__ import annotations
99

10+
import fnmatch
1011
import hashlib
1112
import re
12-
from pathlib import Path
13+
from pathlib import Path, PurePosixPath
14+
from typing import Sequence
1315

1416
# human-authored agent instruction files: highest-trust briefing input,
1517
# ingested rather than re-derived
@@ -100,3 +102,88 @@ def scan_modules(repo: Path, language: str, *, min_files: int = 3) -> dict:
100102
modules[entry.name] = {"local_paths": [f"{entry.name}/"],
101103
"wave": wave}
102104
return modules
105+
106+
107+
ROOT_MODULE = "./" # the key of the module holding files directly in the repo root
108+
109+
110+
def _loc(path: Path) -> int:
111+
try:
112+
text = path.read_text(encoding="utf-8", errors="replace")
113+
except OSError:
114+
return 0
115+
return sum(1 for line in text.splitlines() if line.strip())
116+
117+
118+
def normalize_root(root: str) -> str:
119+
"""A source root as a repo-relative POSIX directory without leading ``./``
120+
or slashes (``"src/pkg"``); the repository root itself is ``""``."""
121+
text = PurePosixPath(root.strip().strip("/") or ".").as_posix()
122+
return "" if text == "." else text
123+
124+
125+
def _module_parent(key: str) -> str:
126+
parent = str(PurePosixPath(key.rstrip("/")).parent)
127+
return ROOT_MODULE if parent == "." else parent + "/"
128+
129+
130+
def scan_modules_at_depth(repo: Path, language: str, *, source_roots: Sequence[str],
131+
depth: int, min_loc: int,
132+
exclude: Sequence[str] = ()) -> dict[str, dict]:
133+
"""Deterministic directory-level modules for knowledge coverage.
134+
135+
Every source file under a source root belongs to the module of its deepest
136+
ancestor directory at most ``depth`` levels below that root (the root is
137+
level 0). A module under ``min_loc`` non-blank lines folds into its parent
138+
directory's module, deepest first and until stable; a source root never
139+
folds. Returns ``{"pkg/sub/": {"files": [...], "loc": n}}`` (files directly
140+
in the repo root: ``ROOT_MODULE``). Hidden and non-code directories are
141+
skipped at every level, ``exclude`` fnmatch globs apply to repo-relative
142+
file paths, and an unknown language scans nothing rather than guessing."""
143+
from .languages import suffixes as _suffixes
144+
145+
sfx = _suffixes(language)
146+
if not sfx or depth < 0:
147+
return {}
148+
roots = sorted({normalize_root(r) for r in source_roots}) or [""]
149+
if "" in roots:
150+
roots = [""] # the repository root already holds every other root
151+
modules: dict[str, dict] = {}
152+
seen: set[str] = set()
153+
root_keys: set[str] = set()
154+
# longest root first, so a nested root owns its own files
155+
for root in sorted(roots, key=lambda r: (-len(r), r)):
156+
base = repo / root if root else repo
157+
if not base.is_dir():
158+
continue
159+
root_key = f"{root}/" if root else ROOT_MODULE
160+
root_keys.add(root_key)
161+
for path in sorted(base.rglob("*")):
162+
if not path.is_file() or path.suffix not in sfx:
163+
continue
164+
rel = path.relative_to(repo).as_posix()
165+
if rel in seen or any(fnmatch.fnmatch(rel, glob) for glob in exclude):
166+
continue
167+
parts = path.relative_to(base).parts[:-1]
168+
if any(p.startswith(".") or p in _NON_MODULE_DIRS for p in parts):
169+
continue
170+
seen.add(rel)
171+
key = (f"{root}/" if root else "") + "".join(f"{p}/" for p in parts[:depth])
172+
entry = modules.setdefault(key or ROOT_MODULE, {"files": [], "loc": 0})
173+
entry["files"].append(rel)
174+
entry["loc"] += _loc(path)
175+
folding = True
176+
while folding: # one fold per pass, deepest first: a folded child counts toward its parent
177+
folding = False
178+
for key in sorted(modules, key=lambda k: (-k.count("/"), k)):
179+
parent = _module_parent(key)
180+
if key in root_keys or parent == key or modules[key]["loc"] >= min_loc:
181+
continue
182+
entry = modules.pop(key)
183+
target = modules.setdefault(parent, {"files": [], "loc": 0})
184+
target["files"].extend(entry["files"])
185+
target["loc"] += entry["loc"]
186+
folding = True
187+
break
188+
return {key: {"files": sorted(entry["files"]), "loc": entry["loc"]}
189+
for key, entry in sorted(modules.items()) if entry["files"]}

0 commit comments

Comments
 (0)