repowiki-cli 0.6.1__tar.gz → 0.7.0__tar.gz

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repowiki-cli
-Version: 0.6.1
+Version: 0.7.0
 Summary: Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en).
 Author: luomsis
 License-Expression: MIT

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "repowiki-cli"
-version = "0.6.1"
+version = "0.7.0"
 description = "Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en)."
 readme = "README.md"
 requires-python = ">=3.10"

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/coverage.py

@@ -63,12 +63,16 @@ def run_coverage(paths: WikiPaths, as_json: bool) -> int:
     uncited = sorted(known - cited)
     total = len(known)
     covered = total - len(uncited)
+    breakdown = _classify_uncited(uncited, cited, paths.locale)
+    eff_total = total - len(breakdown["vendor"]) - len(breakdown["locale_mirror"])
     result = {
         "ok": True,
         "repo_files": total,
         "cited_files": covered,
         "coverage": round(covered / total, 4) if total else 1.0,
+        "effective_coverage": round(covered / eff_total, 4) if eff_total else 1.0,
         "uncited_files": uncited,
+        "uncited_breakdown": breakdown,
         "knowledge_files": sorted(knowledge_files),
         "pages": pages,
     }
@@ -76,15 +80,60 @@ def run_coverage(paths: WikiPaths, as_json: bool) -> int:
     return 0
 
 
+def _locale_mirrors(p: str, locale: str) -> set[str]:
+    """Candidate paths of the other-locale twin of ``p`` (deterministic)."""
+    out: set[str] = set()
+    for old, new in (
+        (f"/{locale}/", "/en/"), ("/en/", f"/{locale}/"),
+        (f".{locale}.", ".en."), (".en.", f".{locale}."), (".en.", "."),
+    ):
+        if old in p:
+            out.add(p.replace(old, new, 1))
+    return out
+
+
+def _classify_uncited(uncited: list[str], cited: set[str], locale: str) -> dict[str, list[str]]:
+    """Bucket uncited files: vendored third-party code, other-locale mirrors
+    of already-cited files, and the rest (the actionable residue)."""
+    vendor: list[str] = []
+    mirror: list[str] = []
+    other: list[str] = []
+    for p in uncited:
+        if "/vendor/" in f"/{p}":
+            vendor.append(p)
+        elif _locale_mirrors(p, locale) & cited:
+            mirror.append(p)
+        else:
+            other.append(p)
+    return {"vendor": sorted(vendor), "locale_mirror": sorted(mirror), "other": sorted(other)}
+
+
 def _coverage_human(r: dict) -> str:
     lines = [
         f"覆盖率 {r['cited_files']}/{r['repo_files']}（{r['coverage'] * 100:.1f}%）"
         "——被 wiki 页面/总览/知识卡片引用过的仓库文件占比"
     ]
+    if r.get("effective_coverage") != r["coverage"]:
+        lines.append(
+            f"有效覆盖率 {r['effective_coverage'] * 100:.1f}%"
+            "（剔除 vendor 与其他语言镜像后的口径）"
+        )
     uncited = r["uncited_files"]
     if uncited:
-        lines.append(f"未被引用 {len(uncited)} 个（至多列出 {MAX_LISTING} 个，JSON 输出含全量）:")
-        lines += [f"  → {p}" for p in uncited[:MAX_LISTING]]
+        bd = r.get("uncited_breakdown") or {}
+        mirror = bd.get("locale_mirror", [])
+        vendored = bd.get("vendor", [])
+        actionable = bd.get("other", uncited)
+        lines.append(f"未被引用 {len(uncited)} 个（JSON 输出含全量分组）:")
+        if mirror:
+            lines.append(f"  其他语言镜像（无需引用）: {', '.join(mirror[:5])}"
+                         + (f" 等 {len(mirror)} 个" if len(mirror) > 5 else ""))
+        if vendored:
+            lines.append(f"  vendor 第三方（无需引用）: {', '.join(vendored[:5])}"
+                         + (f" 等 {len(vendored)} 个" if len(vendored) > 5 else ""))
+        show = actionable[:MAX_LISTING]
+        lines.append(f"  值得补引用 {len(actionable)} 个（至多列出 {MAX_LISTING} 个）:")
+        lines += [f"  → {p}" for p in show]
     else:
         lines.append("仓库全部文件都被引用 ✓")
     zero = [p for p in r["pages"] if p["cited_files"] == 0]

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/dispatch.py

@@ -292,7 +292,8 @@ def _check_readonly(paths: WikiPaths, task: dict, inv) -> dict:
         node_id = task["id"][:-len("-update")] if task["id"].endswith("-update") else task["id"]
         res = check_page(raw, task["title"].replace("（增量更新）", ""), paths.repo_root,
                          is_update=(task["kind"] == "page_update"), locale=paths.locale,
-                         archetype=_node_archetype(paths, node_id))
+                         archetype=_node_archetype(paths, node_id),
+                         known_paths=inv.known_paths())
         return {**base, "ok": res.ok, "readonly": True, "errors": res.errors,
                 "fixed": [], "warnings": res.warnings,
                 "note": "done 为终态，此结果仅供参考，状态未改变"}
@@ -352,7 +353,8 @@ def _check_one(paths: WikiPaths, store: TaskStore, task: dict, inv) -> dict:
             node_id = tid[:-len("-update")] if tid.endswith("-update") else tid
             res = check_page(raw, task["title"].replace("（增量更新）", ""), paths.repo_root,
                              is_update=(kind == "page_update"), locale=paths.locale,
-                             archetype=_node_archetype(paths, node_id))
+                             archetype=_node_archetype(paths, node_id),
+                             known_paths=inv.known_paths())
         if res.fixed and res.text != raw:
             out_file.write_text(res.text, encoding="utf-8")
         status = "done" if res.ok else "failed"

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/i18n.py

@@ -32,6 +32,7 @@ STRINGS: dict[str, dict] = {
             ("结论", "exact"),
         ],
         "update_extra": ("更新摘要", "exact"),
+        "section_sources": "章节来源",
         "flow_sections": [
             ("简介", "exact"),
             ("流程总览", "exact"),
@@ -74,6 +75,7 @@ STRINGS: dict[str, dict] = {
             ("Conclusion", "exact"),
         ],
         "update_extra": ("Update Summary", "exact"),
+        "section_sources": "Section sources",
         "flow_sections": [
             ("Introduction", "exact"),
             ("Flow Overview", "exact"),

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/skills/repowiki/SKILL.en.md

@@ -131,10 +131,12 @@ code 3 (it created the overview task — normal progress).
   source code.
 - Pages follow the template and STYLE guide embedded in the spec: all required sections
   present, "Section sources" at the end of every section, "Diagram sources" after every
-  mermaid diagram, `[path:Lx-Ly](file://path#Lx-Ly)` format, line numbers within bounds,
+  mermaid diagram, `[path:Lx-Ly](file://path#Lx-Ly)` format, line numbers within bounds
+  (a start past EOF or an inverted range is rejected; only an overhanging end is clamped),
   zero cross-page links, no emoji/tables.
-- Deterministic defects caught by `check` (anchors/line numbers/H1) are auto-repaired —
-  no manual handling needed; only fix the semantic issues listed in `errors`.
+- Deterministic defects caught by `check` (anchors/H1/overhanging line-range ends) are
+  auto-repaired — no manual handling needed; only fix the semantic issues listed in
+  `errors`.
 - Output lives in `<repo>/.repowiki/` (`<locale>/content` pages, `<locale>/meta`
   metadata, `knowledge/<locale>/` knowledge cards, `<locale>/wiki.html` single-file
   viewer; locale was fixed at plan time).

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/skills/repowiki/SKILL.md

@@ -102,6 +102,6 @@ loop:
 ## 硬性规则
 
 - **只写任务规格指定的 output 文件**，绝不改动仓库源码。
-- 页面遵循规格内嵌的模板与 STYLE 规范：必备小节齐全、每节末尾「Section sources/章节来源」、每个 mermaid 图后「Diagram sources/图表来源」、`[path:Lx-Ly](file://path#Lx-Ly)` 格式、行号不越界、页间零链接、不用 emoji/表格。
-- `check` 的确定性缺陷（锚点/行号/H1）会被自动修复，无需手动处理；只需修复 `errors` 列出的语义问题。
+- 页面遵循规格内嵌的模板与 STYLE 规范：必备小节齐全、每节末尾「Section sources/章节来源」、每个 mermaid 图后「Diagram sources/图表来源」、`[path:Lx-Ly](file://path#Lx-Ly)` 格式、行号不越界（起点越界/区间倒置会被打回，仅终点越界自动钳制）、页间零链接、不用 emoji/表格。
+- `check` 的确定性缺陷（锚点/H1/越界的行区间终点）会被自动修复，无需手动处理；只需修复 `errors` 列出的语义问题。
 - 输出位于 `<repo>/.repowiki/`（`<locale>/content` 页面、`<locale>/meta` 元数据、`knowledge/<locale>/` 知识卡片、`<locale>/wiki.html` 单文件查看站点；locale 已在 plan 时确定）。

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/en/STYLE.md

@@ -6,7 +6,7 @@
 
 ## Section Sources & Diagram Sources (citation format, mandatory)
 - Every body section ends with a "Section sources" list; every mermaid diagram is followed by a "Diagram sources" list.
-- Link format (paths relative to the repo root, forward slashes, line ranges must not exceed the file's real length):
+- Link format (paths relative to the repo root, forward slashes, line ranges must not exceed the file's real length; only an overhanging end is auto-clamped, while a start past EOF or an inverted range is rejected by `check`):
   - `[README.md:1-120](file://README.md#L1-L120)`
   - `src/graphiti/graphiti.py:146-283` → `[graphiti/graphiti.py:146-283](file://graphiti/graphiti.py#L146-L283)`
 - Whole-file references may use the shorter form `[nodes.py](file://graphiti_core/nodes.py)` (inside the `<cite>` block).

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/en/page_task.md

@@ -35,7 +35,7 @@ Write the finished page to: <b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT}}).
 1. Exactly one H1, equal to "{{TITLE}}".
 2. The `<cite>` block lists the files this page actually references (`[file name](file://repo-relative path)` format, 3~15 files).
 3. The "Contents" anchors must match the real section headings (GitHub-style anchors: lowercase, punctuation dropped, spaces → `-`).
-4. After the Introduction, every section ends with "Section sources"; every mermaid diagram is followed by "Diagram sources"; link format `[path:Lx-Ly](file://path#Lx-Ly)` with line numbers within the file's real length.
+4. After the Introduction, every section ends with "Section sources"; every mermaid diagram is followed by "Diagram sources"; link format `[path:Lx-Ly](file://path#Lx-Ly)` with line numbers within the file's real length (a start past EOF or an inverted range is rejected; only an overhanging end is auto-clamped).
 5. At least 2 mermaid diagrams (a structure diagram + a sequence/dependency diagram).
 6. Beyond the required sections above you may add "Appendix: <topic>" sections as needed.
 7. Never link any other page under `.repowiki/`.

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/en/update_task.md

@@ -25,7 +25,7 @@ Rewrite the full updated page to: <b>{{OUTPUT_ABS}}</b> (repo-relative: {{OUTPUT
 ```
 
 ## Update rules
-1. Right after the `<cite>` block and before the table of contents, insert one section:
+1. Right after the H1 and before the table of contents, insert one section:
 
    ```markdown
    ## Update Summary

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/zh/STYLE.md

@@ -7,7 +7,7 @@
 
 ## 章节来源与图表来源（引用格式，强制）
 - 每个正文章节末尾附「章节来源」列表；每个 mermaid 图后附「图表来源」列表。
-- 链接格式（路径相对仓库根目录，统一正斜杠，行号区间不得超出文件实际行数）：
+- 链接格式（路径相对仓库根目录，统一正斜杠，行号区间不得超出文件实际行数；仅终点越界会被自动钳制到文件末尾，起点越界或区间倒置会被 `check` 打回重写）：
   - `[README.md:1-120](file://README.md#L1-L120)`
   - `[graphiti_core/graphiti.py:146-283](file://graphiti_core/graphiti.py#L146-L283)`
 - 仅供整文件引用时可用 `[nodes.py](file://graphiti_core/nodes.py)` 形式（`<cite>` 块内）。

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/zh/page_task.md

@@ -35,7 +35,7 @@ hint_files:
 1. H1 必须且只能是「{{TITLE}}」。
 2. `<cite>` 块内列出本文实际引用的文件（`[文件名](file://仓库相对路径)` 格式，3~15 个）。
 3. 「目录」的锚点必须与实际章节标题对应（GitHub 中文锚点：去 `：` 等标点、空格转 `-`）。
-4. 简介之后每个小节末尾都有「章节来源」；每个 mermaid 图后都有「图表来源」；链接格式 `[path:Lx-Ly](file://path#Lx-Ly)`，行号不得超出文件实际行数。
+4. 简介之后每个小节末尾都有「章节来源」；每个 mermaid 图后都有「图表来源」；链接格式 `[path:Lx-Ly](file://path#Lx-Ly)`，行号不得超出文件实际行数（起点越界/区间倒置会被打回，仅终点越界自动钳制）。
 5. 至少 2 个 mermaid 图（结构图 + 时序/依赖图）。
 6. 除模板列出的必备小节外，可按需增加「附录：<主题>」小节。
 7. 禁止链接任何 `.repowiki/` 下的其他页面。

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/zh/update_task.md

@@ -25,7 +25,7 @@ hint_files:
 ```
 
 ## 更新规则
-1. 在 `<cite>` 块之后、「目录」之前插入一个小节：
+1. 在 H1 之后、「目录」之前插入一个小节：
 
    ```markdown
    ## 更新摘要

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/validate.py

@@ -1,8 +1,11 @@
 """Output validation: rule engine with deterministic auto-fix.
 
-Anything computable (anchors, line ranges, H1, path separators) is fixed
-silently and reported under ``fixed``; only semantic defects (missing
-sections, dangling file references, broken fences) fail the task.
+Anything computable (anchors, H1, path separators, overhanging range ends)
+is fixed silently and reported under ``fixed``; structural defects —
+impossible line ranges (start past EOF, inverted), blank cited slices,
+missing/empty sections, dangling file references, broken fences — fail the
+task. Whether a citation's *content* supports the claim it anchors remains
+the writer's responsibility; these rules only catch what is computable.
 """
 
 from __future__ import annotations
@@ -75,7 +78,8 @@ def _strip_code(text: str) -> str:
     return re.sub(r"`[^`\n]*`", " ", "".join(out))
 
 
-def _file_loc(repo_root: Path, rel: str) -> int | None:
+def _file_loc(repo_root: Path, rel: str) -> tuple[int, list[str]] | None:
+    """Line count and decoded lines of a repo file; None if missing/binary."""
     p = repo_root / rel
     try:
         if not p.is_file():
@@ -83,13 +87,22 @@ def _file_loc(repo_root: Path, rel: str) -> int | None:
         data = p.read_bytes()
         if b"\0" in data[:8192]:
             return None
-        return max(data.count(b"\n"), 1)
+        lines = data.decode("utf-8", errors="replace").splitlines()
+        return max(len(lines), 1), lines
     except OSError:
         return None
 
 
+# file-looking tokens inside mermaid node labels (checked against the inventory)
+_MERMAID_BLOCK_RE = re.compile(r"```mermaid\n(.*?)```", re.S)
+_FILEISH_TOKEN_RE = re.compile(
+    r"[A-Za-z0-9_][\w./\\-]*\.(?:py|md|toml|ya?ml|json|js|jsx?|tsx?|sh|html|txt)\b"
+)
+
+
 def check_page(raw: str, title: str, repo_root: Path, is_update: bool = False,
-               locale: str = "zh", archetype: str = "module") -> CheckResult:
+               locale: str = "zh", archetype: str = "module",
+               known_paths: set[str] | None = None) -> CheckResult:
     res = CheckResult(text=raw)
     text = raw
     lang = strings(locale)
@@ -128,7 +141,7 @@ def check_page(raw: str, title: str, repo_root: Path, is_update: bool = False,
     # <cite> block
     cite = _CITE_RE.search(text)
     if not cite:
-        res.fail("缺少 <cite>…</cite> 引用块（应位于 H1 之后、「目录」之前）")
+        res.fail("缺少 <cite>…</cite> 引用块（应位于页面末尾）")
     else:
         cite_links = _FILE_LINK_RE.findall(cite.group("body"))
         if not cite_links:
@@ -142,7 +155,7 @@ def check_page(raw: str, title: str, repo_root: Path, is_update: bool = False,
     if len(mermaid_blocks) < MIN_MERMAID:
         res.fail(f"mermaid 图数量 {len(mermaid_blocks)} < {MIN_MERMAID}（至少需要结构图与时序/依赖图各一）")
 
-    # file:// links: existence (error) + line-range clamp / separator fix (auto-fix)
+    # file:// links: existence + line-range sanity (errors) / clamp + separator fix (auto-fix)
     cited_paths: list[str] = []
     missing: set[str] = set()
 
@@ -151,24 +164,39 @@ def check_page(raw: str, title: str, repo_root: Path, is_update: bool = False,
         path = orig_path.replace("\\", "/")
         label = m.group("text").replace("\\", "/")
         start, end = m.group("start"), m.group("end")
-        loc = _file_loc(repo_root, path)
-        if loc is None:
+        located = _file_loc(repo_root, path)
+        if located is None:
             missing.add(orig_path)
             return m.group(0)
+        loc, lines = located
         changed = False
         if path != orig_path or label != m.group("text"):
             changed = True
             res.fixed.append(f"链接路径分隔符归一：{orig_path} → {path}")
         if start:
-            s = max(1, min(int(start), loc))
-            e = max(1, min(int(end or start), loc))
-            if str(s) != start or str(e or s) != (end or start):
-                changed = True
+            s = max(1, int(start))
+            e = max(1, int(end or start))
+            if s > loc:
+                # anchor points past EOF — almost certainly a hallucinated line number
+                res.fail(f"引用行号起点越界：{path} 共 {loc} 行，引用却从 L{s} 开始，请核对行号")
+                cited_paths.append(path)
+                return f"[{label}](file://{path})" if changed else m.group(0)
+            if e < s:
+                res.fail(f"行区间倒置：{path}#L{s}-L{e}（起点大于终点），请核对行号")
+                cited_paths.append(path)
+                return f"[{label}](file://{path})" if changed else m.group(0)
+            cited_paths.append(path)
+            e2 = min(e, loc)
+            if not any(ln.strip() for ln in lines[s - 1:e2]):
+                res.fail(f"引用区间全为空行：{path}#L{s}-{e2} 无法支撑任何论断，请核对行号")
+                return f"[{label}](file://{path})" if changed else m.group(0)
+            clamped = e2 != e or str(s) != start or str(e2) != (end or start)
+            if clamped:
                 res.fixed.append(
-                    f"行区间钳制：{path}:{start}-{end or start} → {s}-{e}（文件共 {loc} 行）"
+                    f"行区间钳制：{path}:{start}-{end or start} → {s}-{e2}（文件共 {loc} 行）"
                 )
-            cited_paths.append(path)
-            return f"[{path}:{s}-{e}](file://{path}#L{s}-L{e})" if changed else m.group(0)
+                return f"[{path}:{s}-{e2}](file://{path}#L{s}-L{e2})"
+            return f"[{path}:{s}-{e2}](file://{path}#L{s}-L{e2})" if changed else m.group(0)
         cited_paths.append(path)
         return f"[{label}](file://{path})" if changed else m.group(0)
 
@@ -178,6 +206,39 @@ def check_page(raw: str, title: str, repo_root: Path, is_update: bool = False,
     if len(set(cited_paths)) > MAX_CITED_FILES:
         res.warnings.append(f"单页引用文件 {len(set(cited_paths))} 个 > {MAX_CITED_FILES}")
 
+    # mermaid node labels naming a file should reference real repo files.
+    # Label shorthand ("main.py") matches by basename; conceptual labels
+    # without a file extension never trigger this. Warn only.
+    if known_paths:
+        suspicious: set[str] = set()
+        for block in _MERMAID_BLOCK_RE.findall(text):
+            for token in _FILEISH_TOKEN_RE.findall(block):
+                norm = token.replace("\\", "/")
+                if norm not in known_paths and not any(
+                    k == norm or k.endswith("/" + norm) for k in known_paths
+                ):
+                    suspicious.add(norm)
+        if suspicious:
+            res.warnings.append(
+                "mermaid 图节点引用了仓库中不存在的文件名（概念命名可忽略）: "
+                + ", ".join(sorted(suspicious)[:5])
+            )
+
+    # per-section rules: every ## section (except the TOC / update summary)
+    # must be non-empty and carry a sources marker (auto-fix never applies)
+    src_marker = lang.get("section_sources", "章节来源")
+    skip_sections = {lang["toc"]}
+    if is_update:
+        skip_sections.add(lang["update_extra"][0])
+    parts = re.split(r"^## (.+?)\s*$", text, flags=re.M)
+    for h, body in zip(parts[1::2], parts[2::2]):
+        if h.strip() in skip_sections:
+            continue
+        if not _strip_code(body).strip():
+            res.fail(f"小节「{h.strip()}」内容为空")
+        elif src_marker not in body:
+            res.fail(f"小节「{h.strip()}」缺少「{src_marker}」来源列表")
+
     # wiki-to-wiki links (warn only)
     wiki_refs = [m.group(1) for m in _WIKI_LINK_RE.finditer(text)]
     if wiki_refs:

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki_cli.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: repowiki-cli
-Version: 0.6.1
+Version: 0.7.0
 Summary: Deterministic repo wiki build system, driven by any coding agent. Output language follows the repository (zh/en).
 Author: luomsis
 License-Expression: MIT

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/tests/test_coverage.py

@@ -87,3 +87,28 @@ def test_coverage_ignores_citations_to_deleted_files(repo, capsys):
     assert run("coverage", str(repo), "--json") == 0
     data = json.loads(capsys.readouterr().out)
     assert data["cited_files"] == 2  # api.py no longer in the inventory
+
+
+def test_coverage_breakdown_and_effective_rate(repo, capsys):
+    paths = setup(repo)
+    (repo / "src/demo/vendor").mkdir()
+    (repo / "src/demo/vendor/lib.py").write_text("x = 1\n", encoding="utf-8")
+    (repo / "docs/zh").mkdir(parents=True)
+    (repo / "docs/zh/CONTEXT.md").write_text("背景\n", encoding="utf-8")
+    (repo / "docs/en").mkdir(parents=True)
+    (repo / "docs/en/CONTEXT.md").write_text("context\n", encoding="utf-8")
+    # cite the zh twin so the en file classifies as a locale mirror
+    page = paths.root / "zh/content/快速开始.md"
+    page.write_text(
+        valid_page("快速开始").replace(
+            "</cite>", "- [docs/zh/CONTEXT.md](file://docs/zh/CONTEXT.md)\n</cite>"
+        ),
+        encoding="utf-8",
+    )
+    assert run("coverage", str(repo), "--json") == 0
+    data = json.loads(capsys.readouterr().out)
+    assert "src/demo/vendor/lib.py" in data["uncited_breakdown"]["vendor"]
+    assert "docs/en/CONTEXT.md" in data["uncited_breakdown"]["locale_mirror"]
+    assert "docs/zh/CONTEXT.md" not in data["uncited_files"]
+    # effective coverage excludes vendor + mirrors from the denominator
+    assert data["effective_coverage"] > data["coverage"]

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/tests/test_i18n.py

@@ -65,6 +65,9 @@ def en_page(title: str = "Project Overview") -> str:
 ## Introduction
 demo is a tiny sample service.
 
+Section sources
+- [README.md:1-3](file://README.md#L1-L3)
+
 ## Project Structure
 - src/demo: core package
 

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/tests/test_validate.py

@@ -69,6 +69,56 @@ class TestPageRules:
         # README.md is 3 lines in the fixture; the out-of-range 9999 gets clamped
         assert "README.md:1-3" in res.text
 
+    def test_start_beyond_eof_fails(self, repo):
+        # start past EOF is a hallucinated anchor: error, not a silent clamp
+        text = valid_page().replace(
+            "[README.md:1-2](file://README.md#L1-L2)", "[README.md:50-60](file://README.md#L50-L60)", 1
+        )
+        res = check_page(text, "项目概述", repo)
+        assert not res.ok and any("起点越界" in e for e in res.errors)
+
+    def test_inverted_range_fails(self, repo):
+        text = valid_page().replace(
+            "[src/demo/main.py:1-7](file://src/demo/main.py#L1-L7)",
+            "[src/demo/main.py:7-1](file://src/demo/main.py#L7-L1)", 1
+        )
+        res = check_page(text, "项目概述", repo)
+        assert not res.ok and any("倒置" in e for e in res.errors)
+
+    def test_blank_cited_slice_fails(self, repo):
+        # line 2 of the fixture README.md is blank: nothing to anchor a claim to
+        text = valid_page().replace(
+            "[README.md:1-2](file://README.md#L1-L2)", "[README.md:2-2](file://README.md#L2-L2)", 1
+        )
+        res = check_page(text, "项目概述", repo)
+        assert not res.ok and any("空行" in e for e in res.errors)
+
+    def test_mermaid_unknown_filename_warns(self, repo):
+        text = valid_page().replace('A["api.py"] --> B["models.py"]', 'A["engine.py"] --> B["models.py"]', 1)
+        known = {"src/demo/api.py", "src/demo/models.py", "src/demo/main.py"}
+        res = check_page(text, "项目概述", repo, known_paths=known)
+        assert res.ok and any("engine.py" in w for w in res.warnings)
+
+    def test_mermaid_known_filenames_no_warning(self, repo):
+        # label shorthand ("api.py") matches by basename against the inventory
+        known = {"src/demo/api.py", "src/demo/models.py", "src/demo/main.py"}
+        res = check_page(valid_page(), "项目概述", repo, known_paths=known)
+        assert res.ok and not any("不存在" in w for w in res.warnings)
+
+    def test_section_without_sources_fails(self, repo):
+        text = valid_page().replace("- 启动失败：检查依赖\n\n章节来源", "- 启动失败：检查依赖", 1)
+        res = check_page(text, "项目概述", repo)
+        assert not res.ok and any("章节来源" in e for e in res.errors)
+
+    def test_empty_section_fails(self, repo):
+        text = valid_page().replace(
+            "## 性能与一致性考量\n- 单进程内存列表，无并发保障\n\n章节来源"
+            "\n- [src/demo/api.py:1-8](file://src/demo/api.py#L1-L8)",
+            "## 性能与一致性考量", 1,
+        )
+        res = check_page(text, "项目概述", repo)
+        assert not res.ok and any("内容为空" in e for e in res.errors)
+
     def test_backslash_path_normalized(self, repo):
         text = valid_page().replace("file://src/demo/main.py", "file://src\\demo\\main.py")
         res = check_page(text, "项目概述", repo)

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/en/flow_template.md

@@ -1,11 +1,5 @@
 # {{TITLE}}
 
-<cite>
-**Files referenced**
-- [<file name>](file://<repo-relative path>)
-- [<file name>](file://<repo-relative path>)
-</cite>
-
 ## Contents
 1. [Introduction](#introduction)
 2. [Flow Overview](#flow-overview)
@@ -85,3 +79,9 @@ Section sources
 
 Section sources
 - [<path>:<from>-<to>](file://<path>#L<from>-L<to>)
+
+<cite>
+**Files referenced**
+- [<file name>](file://<repo-relative path>)
+- [<file name>](file://<repo-relative path>)
+</cite>

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/en/page_template.md

@@ -1,11 +1,5 @@
 # {{TITLE}}
 
-<cite>
-**Files referenced by this page**
-- [<file name>](file://<repo-relative path>)
-- [<file name>](file://<repo-relative path>)
-</cite>
-
 ## Contents
 1. [Introduction](#introduction)
 2. [Project Structure](#project-structure)
@@ -111,3 +105,9 @@ Section sources
 
 Section sources
 - [<path>:<start>-<end>](file://<path>#L<start>-L<end>)
+
+<cite>
+**Files referenced by this page**
+- [<file name>](file://<repo-relative path>)
+- [<file name>](file://<repo-relative path>)
+</cite>

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/zh/flow_template.md

@@ -1,11 +1,5 @@
 # {{TITLE}}
 
-<cite>
-**本文引用的文件**
-- [<文件名>](file://<仓库相对路径>)
-- [<文件名>](file://<仓库相对路径>)
-</cite>
-
 ## 目录
 1. [简介](#简介)
 2. [流程总览](#流程总览)
@@ -85,3 +79,9 @@ B -->|"完成"| C["终态"]
 
 章节来源
 - [<path>:<起>-<止>](file://<path>#L<起>-L<止>)
+
+<cite>
+**本文引用的文件**
+- [<文件名>](file://<仓库相对路径>)
+- [<文件名>](file://<仓库相对路径>)
+</cite>

{repowiki_cli-0.6.1 → repowiki_cli-0.7.0}/src/repowiki/templates/zh/page_template.md

@@ -1,11 +1,5 @@
 # {{TITLE}}
 
-<cite>
-**本文引用的文件**
-- [<文件名>](file://<仓库相对路径>)
-- [<文件名>](file://<仓库相对路径>)
-</cite>
-
 ## 目录
 1. [简介](#简介)
 2. [项目结构](#项目结构)
@@ -111,3 +105,9 @@ B --> C["外部依赖"]
 
 章节来源
 - [<path>:<起>-<止>](file://<path>#L<起>-L<止>)
+
+<cite>
+**本文引用的文件**
+- [<文件名>](file://<仓库相对路径>)
+- [<文件名>](file://<仓库相对路径>)
+</cite>