repowiki-cli 0.5.0__py3-none-any.whl

repowiki/plan.py

@@ -0,0 +1,140 @@
+"""``repowiki plan``: scan the repo and lay down the task manifest."""
+
+from __future__ import annotations
+
+import json
+import shutil
+
+from .errors import UsageError
+from .i18n import SUPPORTED, detect_locale, strings
+from .output import emit
+from .paths import WikiPaths
+from . import tasks
+from .catalog import validate_catalog, flatten
+from .scanner import scan
+from .state import TaskStore
+
+MIN_CODE_FILES = 10
+
+
+def _load_catalog(paths: WikiPaths) -> dict | None:
+    if not paths.catalog_file.exists():
+        return None
+    try:
+        return json.loads(paths.catalog_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+
+
+def _resolve_locale(paths: WikiPaths, locale_flag: str, inv) -> str:
+    """Explicit --locale wins; else a persisted state/locale; else detect."""
+    if locale_flag != "auto":
+        return locale_flag
+    if (paths.state_dir / "locale").exists():
+        return paths.locale  # lazy property reads the persisted value
+    return detect_locale(paths.repo_root, [f.path for f in inv.files if f.is_code])
+
+
+def run_plan(paths: WikiPaths, replan: bool = False, max_pages: int | None = None,
+             knowledge: bool = False, force: bool = False, as_json: bool = False,
+             locale: str = "auto") -> int:
+    if replan and paths.root.exists():
+        busy = _busy_tasks(paths)
+        if busy is None and not force:
+            raise UsageError(
+                "state/index.json 无法解析，无法确认是否有任务在执行；"
+                "replan 会删除现有状态与规格，确认放弃恢复请加 --force"
+            )
+        if busy and not force:
+            raise UsageError(
+                f"检测到 {len(busy)} 个 in_progress 任务（{', '.join(busy[:5])}），"
+                "replan 会删除正在被写入的产物；确认请加 --force"
+            )
+        shutil.rmtree(paths.root)
+    store = TaskStore(paths)
+    inv = scan(paths.repo_root)
+
+    if inv.code_file_count < MIN_CODE_FILES:
+        raise UsageError(
+            f"代码文件数 {inv.code_file_count} < {MIN_CODE_FILES}，仓库太小，不适合生成 RepoWiki"
+        )
+
+    # locale must be resolved before ensure(): the locale decides which
+    # <locale>/content and <locale>/meta directories get created
+    resolved = _resolve_locale(paths, locale, inv)
+    persisted = (paths.state_dir / "locale").exists()
+    if not persisted or locale != "auto":
+        paths.persist_locale(resolved)
+    paths.ensure()
+
+    warnings: list[str] = []
+    added: list[str] = []
+    catalog = _load_catalog(paths)
+    if catalog is not None:
+        errors, warns = validate_catalog(catalog, inv.known_paths())
+        warnings.extend(warns)
+        if errors:
+            warnings.append("已有 catalog.json 校验失败，将重新规划: " + "; ".join(errors[:5]))
+            catalog = None
+
+    if catalog is None:
+        added += store.add_tasks([tasks.build_catalog_task(paths, inv)])
+    else:
+        nodes = flatten(catalog, resolved)
+        added += store.add_tasks(tasks.build_page_tasks(paths, nodes, inv, max_pages))
+        warnings.extend(_warn_dangling_outputs(paths, nodes))
+
+    if knowledge:
+        added += store.add_tasks([tasks.build_knowledge_plan_task(paths, inv)])
+
+    stats = store.stats()
+    result = {
+        "repo": str(paths.repo_root),
+        "locale": resolved,
+        "code_file_count": inv.code_file_count,
+        "tasks_added": added,
+        "tasks_total": stats["total"],
+        "by_status": stats["by_status"],
+        "current_phase": stats["current_phase"],
+        "warnings": warnings,
+        "next": "执行 `repowiki next <repo> --claim` 领取任务",
+    }
+    emit(result, _plan_human, as_json)
+    return 0
+
+
+def _plan_human(r: dict) -> str:
+    lines = [
+        f"仓库：{r['repo']}（代码文件 {r['code_file_count']} 个，产出语言：{strings(r['locale'])['name']}）",
+        f"新增任务 {len(r['tasks_added'])} 个，总任务 {r['tasks_total']} 个，当前阶段 {r['current_phase']}",
+        *[f"  ⚠ {w}" for w in r["warnings"]],
+        r["next"],
+    ]
+    return "\n".join(lines)
+
+
+def _busy_tasks(paths: WikiPaths) -> list[str] | None:
+    """Ids of in_progress tasks; None when the index exists but is unreadable."""
+    if not paths.index_file.exists():
+        return []
+    try:
+        data = json.loads(paths.index_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return None
+    return [tid for tid, t in data.get("tasks", {}).items() if t.get("status") == "in_progress"]
+
+
+def _warn_dangling_outputs(paths: WikiPaths, nodes: list[dict]) -> list[str]:
+    """Pages already on disk but no longer in the catalog (stale leftovers)."""
+    expected = {n.output for n in nodes}
+    dangling: list[str] = []
+    content = paths.content_dir
+    if not content.exists():
+        return dangling
+    for p in content.rglob("*.md"):
+        rel = f"{paths.locale}/content/" + p.relative_to(content).as_posix()
+        if rel not in expected:
+            dangling.append(rel)
+    if dangling:
+        return [f"{len(dangling)} 个已生成页面不在当前 catalog 中（可能为旧残留）: " + ", ".join(dangling[:5])]
+    return []

repowiki/scanner.py

@@ -0,0 +1,170 @@
+"""Repository scanner: deterministic file inventory for planning.
+
+Uses ``git ls-files`` when available (accurate .gitignore handling), else
+falls back to a manual walk. Skips binaries, VCS/build/vendor directories
+and the tool's own output (``.repowiki``).
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from .gitutil import run_git
+
+CODE_EXTS = {
+    "py", "ts", "tsx", "js", "jsx", "mjs", "cjs", "go", "rs", "java", "kt",
+    "rb", "c", "h", "cc", "cpp", "hpp", "cs", "swift", "scala", "sh", "bash",
+    "sql", "php", "vue", "svelte", "dart", "lua", "pl",
+}
+
+LANG_BY_EXT = {
+    "py": "python", "ts": "typescript", "tsx": "typescript", "js": "javascript",
+    "jsx": "javascript", "mjs": "javascript", "cjs": "javascript", "go": "go",
+    "rs": "rust", "java": "java", "kt": "kotlin", "rb": "ruby", "c": "c",
+    "h": "c", "cc": "cpp", "cpp": "cpp", "hpp": "cpp", "cs": "csharp",
+    "swift": "swift", "scala": "scala", "sh": "shell", "bash": "shell",
+    "sql": "sql", "php": "php", "vue": "vue", "svelte": "svelte",
+    "dart": "dart", "lua": "lua", "pl": "perl",
+    "md": "markdown", "rst": "markdown", "txt": "text",
+    "yaml": "yaml", "yml": "yaml", "toml": "toml", "json": "json",
+    "ini": "ini", "cfg": "ini", "html": "html", "css": "css", "scss": "scss",
+    "xml": "xml",
+}
+
+IGNORE_DIRS = {
+    ".git", "node_modules", "venv", ".venv", "env", "dist", "target", "build",
+    "out", "__pycache__", ".repowiki", ".idea", ".vscode", ".next", ".tox",
+    ".eggs", "coverage", ".mypy_cache", ".pytest_cache", "site-packages",
+    ".ruff_cache", ".hypothesis",
+}
+
+KEY_FILE_GLOBS = [
+    "README*", "pyproject.toml", "setup.py", "setup.cfg", "package.json",
+    "go.mod", "Cargo.toml", "docker-compose*.yml", "docker-compose*.yaml",
+    "Makefile", "requirements*.txt", "pom.xml", "build.gradle", "*.gemspec",
+]
+
+MAX_TEXT_BYTES = 2 * 1024 * 1024  # larger files are listed but not counted by LOC
+_PER_DIR_CAP = 20
+_MAX_SUMMARY_LINES = 400
+
+
+@dataclass
+class FileEntry:
+    path: str
+    loc: int
+    lang: str
+    is_code: bool
+
+
+@dataclass
+class Inventory:
+    repo_root: str
+    files: list[FileEntry] = field(default_factory=list)
+    key_files: list[str] = field(default_factory=list)
+    tree_summary: str = ""
+    code_file_count: int = 0
+
+    def known_paths(self) -> set[str]:
+        return {f.path for f in self.files}
+
+
+def _git_ls_files(root: Path) -> list[str] | None:
+    if not (root / ".git").exists():
+        return None
+    out = run_git(root, "ls-files", "-z", timeout=120)
+    if out is None:
+        return None
+    return [p for p in out.split("\0") if p]
+
+
+def _walk_files(root: Path) -> list[str]:
+    found: list[str] = []
+    for dirpath, dirnames, filenames in os_walk_pruned(root):
+        for name in filenames:
+            rel = (Path(dirpath) / name).relative_to(root).as_posix()
+            found.append(rel)
+    return sorted(found)
+
+
+def os_walk_pruned(root: Path):
+    for dirpath, dirnames, filenames in os.walk(root):
+        dirnames[:] = [d for d in dirnames if d not in IGNORE_DIRS and not d.startswith(".git")]
+        yield dirpath, dirnames, filenames
+
+
+def _is_binary(path: Path) -> bool:
+    try:
+        with open(path, "rb") as fh:
+            return b"\0" in fh.read(8192)
+    except OSError:
+        return True
+
+
+def _count_loc(path: Path, size: int) -> int:
+    if size > MAX_TEXT_BYTES:
+        return 0
+    try:
+        with open(path, "rb") as fh:
+            return fh.read().count(b"\n")
+    except OSError:
+        return 0
+
+
+def scan(repo_root: str | Path) -> Inventory:
+    root = Path(repo_root).resolve()
+    rels = _git_ls_files(root)
+    if rels is None:
+        rels = _walk_files(root)
+    else:
+        rels = [r for r in rels if not any(part in IGNORE_DIRS for part in Path(r).parts[:-1])]
+
+    files: list[FileEntry] = []
+    for rel in sorted(rels):
+        p = root / rel
+        if not p.is_file() or _is_binary(p):
+            continue
+        size = p.stat().st_size
+        ext = p.suffix.lstrip(".").lower()
+        no_ext = p.name.lower()
+        lang = LANG_BY_EXT.get(ext, "" )
+        if not lang and no_ext in {"dockerfile", "makefile", "procfile"}:
+            lang = no_ext.lower()
+        is_code = ext in CODE_EXTS
+        files.append(FileEntry(path=rel, loc=_count_loc(p, size), lang=lang, is_code=is_code))
+
+    inv = Inventory(
+        repo_root=str(root),
+        files=files,
+        code_file_count=sum(1 for f in files if f.is_code),
+    )
+    inv.key_files = sorted(
+        {f.path for f in files for pat in KEY_FILE_GLOBS if Path(f.path).parent == Path(".") and Path(f.path).match(pat)}
+    )
+    inv.tree_summary = _render_tree(files)
+    return inv
+
+
+def _render_tree(files: list[FileEntry]) -> str:
+    """Compact repo tree, capped per directory and in total size."""
+    by_dir: dict[str, list[str]] = {}
+    for f in files:
+        by_dir.setdefault(str(Path(f.path).parent) if str(Path(f.path).parent) != "." else "", []).append(Path(f.path).name)
+
+    lines: list[str] = ["<repo>/"]
+    dirs = sorted(by_dir)
+    for i, d in enumerate(dirs):
+        names = by_dir[d]
+        shown = names[:_PER_DIR_CAP]
+        prefix = "" if d == "" else f"{d}/"
+        lines.append(f"{prefix} ({len(names)} files)")
+        for name in shown:
+            lines.append(f"  {name}")
+        if len(names) > _PER_DIR_CAP:
+            lines.append(f"  … (+{len(names) - _PER_DIR_CAP} more)")
+        if len(lines) > _MAX_SUMMARY_LINES:
+            lines.append(f"… (tree truncated at {_MAX_SUMMARY_LINES} lines, {len(dirs) - i - 1} dirs omitted)")
+            break
+    return "\n".join(lines)

repowiki/site.py

@@ -0,0 +1,384 @@
+"""``repowiki site``: render the finished wiki into one self-contained HTML file.
+
+Reads every generated page plus the overview, embeds the source lines behind
+each ``file://`` reference, and inlines the vendored markdown/mermaid JS.
+Knowledge module docs and cards (``knowledge/<locale>/``) are included as
+regular pages under a dedicated nav chapter.
+The result (``<locale>/wiki.html``) opens in any browser with zero network
+and zero server — double-click, or share the single file.
+The same page collection is also exported as ``llms.txt`` /
+``llms-full.txt`` (llmstxt.org convention) for direct agent consumption.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import webbrowser
+from pathlib import Path
+
+import yaml
+
+from . import templates
+from .catalog import FlatNode, flatten
+from .errors import UsageError
+from .i18n import strings
+from .llms import write_llms
+from .output import emit
+from .paths import WikiPaths, sanitize_component
+from .state import now_iso
+from .validate import extract_refs
+
+MAX_SNIPPET_LINES = 20_000  # larger spans are skipped rather than bloating the file
+
+
+def run_site(paths: WikiPaths, open_browser: bool, as_json: bool) -> int:
+    if not paths.metadata_file.is_file():
+        raise UsageError(
+            f"未找到 {paths.metadata_file}：请先完成全部任务并运行 `repowiki finalize <repo>`"
+        )
+    try:
+        metadata = json.loads(paths.metadata_file.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise UsageError(f"repowiki-metadata.json 损坏（{e}）：请重新运行 `repowiki finalize <repo>`") from e
+
+    nodes = _ordered_nodes(paths)
+    pages = _collect_pages(paths, metadata, nodes)
+    if not pages:
+        raise UsageError(f"未找到任何已生成的 wiki 页面（{paths.content_dir} 为空）")
+    knowledge_pages, knowledge_nav = _collect_knowledge(paths, base=len(pages))
+    pages.extend(knowledge_pages)
+    nav = _build_nav(paths, pages, nodes)
+    if knowledge_nav:
+        nav.append(knowledge_nav)
+    snippets = _collect_snippets(paths.repo_root, pages)
+
+    payload = {
+        "repo": _repo_name(paths, metadata),
+        "locale": paths.locale,
+        "generatedAt": now_iso(),
+        "ui": strings(paths.locale)["site"],
+        "nav": nav,
+        "pages": pages,
+        "snippets": snippets,
+    }
+    html = _render_html(payload, paths.locale)
+
+    out = paths.site_file
+    out.parent.mkdir(parents=True, exist_ok=True)
+    tmp = out.with_name(f".{out.name}.{os.getpid()}.tmp")
+    tmp.write_text(html, encoding="utf-8")
+    os.replace(tmp, out)
+    write_llms(paths, payload["repo"], pages, nav)
+    if open_browser:
+        webbrowser.open(out.as_uri())
+
+    summary = {
+        "ok": True,
+        "site": str(out),
+        "pages": len(pages),
+        "knowledge_pages": len(knowledge_pages),
+        "snippets": len(snippets),
+        "size_mb": round(out.stat().st_size / 1024 / 1024, 2),
+        "llms": str(paths.llms_file),
+        "llms_full": str(paths.llms_full_file),
+    }
+    emit(summary, _site_human, as_json)
+    return 0
+
+
+def _site_human(r: dict) -> str:
+    return (
+        f"✓ 站点已生成: {r['site']}\n"
+        f"  页面 {r['pages']}（含知识页 {r['knowledge_pages']}）· 源码片段 {r['snippets']} · 体积 {r['size_mb']} MB\n"
+        f"  agent 索引：{r['llms']} 与 {r['llms_full']}\n"
+        f"  单文件离线可用：浏览器直接打开即可（--open 自动打开）"
+    )
+
+
+# --- content assembly ---
+
+def _repo_name(paths: WikiPaths, metadata: dict) -> str:
+    return (metadata.get("wiki_repo") or {}).get("name") or paths.repo_root.name
+
+
+def _collect_pages(paths: WikiPaths, metadata: dict, nodes: list[FlatNode]) -> list[dict]:
+    site = strings(paths.locale)["site"]
+    pages: list[dict] = []
+
+    overview = metadata.get("wiki_overview") or ""
+    if not overview and paths.overview_file.is_file():
+        overview = paths.overview_file.read_text(encoding="utf-8")
+    if overview and overview != "No overview yet.":
+        pages.append({
+            "id": "overview",
+            "title": site["overview_label"],
+            "path": paths.overview_file.relative_to(paths.root).as_posix(),
+            "md": overview,
+        })
+
+    for node in nodes:
+        f = paths.root / node.output
+        if not f.is_file():
+            continue
+        pages.append({
+            "id": node.id,
+            "title": node.title,
+            "path": node.output,
+            "md": f.read_text(encoding="utf-8"),
+        })
+    return pages
+
+
+def _ordered_nodes(paths: WikiPaths) -> list[FlatNode]:
+    """Plan order from state/catalog.json; after `repowiki clean`, degrade to
+    the on-disk directory layout so the site stays buildable."""
+    if paths.catalog_file.is_file():
+        try:
+            catalog = json.loads(paths.catalog_file.read_text(encoding="utf-8"))
+        except json.JSONDecodeError:
+            catalog = None
+        if catalog is not None:
+            return flatten(catalog, paths.locale)
+    return _nodes_from_disk(paths)
+
+
+def _nodes_from_disk(paths: WikiPaths) -> list[FlatNode]:
+    """Chapter per sub-directory, page per .md file — plan order is lost,
+    but the site stays buildable after `repowiki clean`."""
+    nodes: list[FlatNode] = []
+    content = paths.content_dir
+    if not content.is_dir():
+        return nodes
+
+    def page_node(f: Path, parent_id: str | None) -> FlatNode:
+        return FlatNode(
+            id=f.stem, title=f.stem, slug=f.stem, summary="", kind="page",
+            dependent_files=[], page_brief="", parent_id=parent_id, depth=2,
+            output=f.relative_to(paths.root).as_posix(),
+        )
+
+    for entry in sorted(content.iterdir(), key=lambda p: p.name):
+        if entry.is_dir() and any(entry.glob("*.md")):
+            nodes.append(FlatNode(
+                id=entry.name, title=entry.name, slug=entry.name, summary="", kind="chapter",
+                dependent_files=[], page_brief="", parent_id=None, depth=1,
+                output=f"{entry.relative_to(paths.root).as_posix()}/__chapter__.md",
+            ))
+            for f in sorted(entry.glob("*.md")):
+                nodes.append(page_node(f, entry.name))
+        elif entry.is_file() and entry.suffix == ".md":
+            nodes.append(page_node(entry, None))
+    return nodes
+
+
+def _build_nav(paths: WikiPaths, pages: list[dict], nodes: list[FlatNode]) -> list[dict]:
+    site = strings(paths.locale)["site"]
+    by_output = {p["path"]: i for i, p in enumerate(pages)}
+    children_of: dict[str | None, list[FlatNode]] = {}
+    for n in nodes:
+        children_of.setdefault(n.parent_id, []).append(n)
+
+    def descendants(node_id: str) -> list[FlatNode]:
+        out: list[FlatNode] = []
+        for k in children_of.get(node_id, []):
+            out.append(k)
+            out.extend(descendants(k.id))
+        return out
+
+    entries: list[dict] = []
+    for i, p in enumerate(pages):
+        if p["id"] == "overview":
+            entries.append({"title": site["overview_label"], "page": i})
+            break
+
+    for top in children_of.get(None, []):
+        own = [{"title": top.title, "page": by_output[top.output]}] if top.output in by_output else []
+        kids = [
+            {"title": k.title, "page": by_output[k.output]}
+            for k in descendants(top.id) if k.output in by_output
+        ]
+        if not kids:
+            if own:  # standalone top-level page (with or without a chapter wrapper)
+                entries.append({"title": top.title, "page": own[0]["page"]})
+            continue
+        entries.append({"title": top.title, "children": own + kids})
+    return entries
+
+
+# --- knowledge pages ---
+
+_FM_RE = re.compile(r"^---\s*\n(.*?)\n---\s*\n", re.S)
+_H1_RE = re.compile(r"^#\s+(.+)$", re.M)
+
+
+def _collect_knowledge(paths: WikiPaths, base: int) -> tuple[list[dict], dict | None]:
+    """Module docs + cards under knowledge/<locale>/ as site pages.
+
+    Returns (pages, nav_entry); nav children reference absolute page indexes
+    starting at ``base``. Order follows state/knowledge.json (modules then
+    cards, by sanitized title) and degrades to on-disk sorting.
+    """
+    site = strings(paths.locale)["site"]
+    kdir = paths.knowledge_dir
+    if not kdir.is_dir():
+        return [], None
+    dirs = sorted(d for d in kdir.iterdir() if d.is_dir())
+    if not dirs:
+        return [], None
+
+    module_files = set(strings(paths.locale)["module_required_files"])
+    rank = _knowledge_plan_order(paths)
+
+    def sort_key(d: Path) -> tuple:
+        return (rank.get(d.name, len(rank)), d.name)
+    dirs.sort(key=sort_key)
+
+    module_title_of: dict[str, str] = {}
+    pages: list[dict] = []
+    children: list[dict] = []
+    for d in dirs:
+        docs = sorted(f for f in d.glob("*.md") if f.name in module_files)
+        if docs:
+            title = _module_title(paths, d)
+            module_title_of[d.name] = title
+            for f in docs:
+                pages.append({
+                    "id": f"kb:{d.name}/{f.name}",
+                    "title": f"{title} · {f.stem}",
+                    "path": f.relative_to(paths.root).as_posix(),
+                    "md": f.read_text(encoding="utf-8"),
+                })
+                children.append({"title": f"{title} · {f.stem}", "page": base + len(pages) - 1})
+            continue
+        card = d / f"{d.name}.md"
+        if card.is_file():
+            md, title = _card_body(card.read_text(encoding="utf-8"), d.name)
+            pages.append({
+                "id": f"kb:{d.name}/{d.name}.md",
+                "title": title,
+                "path": card.relative_to(paths.root).as_posix(),
+                "md": md,
+            })
+            children.append({"title": title, "page": base + len(pages) - 1})
+    if not pages:
+        return [], None
+    return pages, {"title": site["knowledge_label"], "children": children}
+
+
+def _knowledge_plan_order(paths: WikiPaths) -> dict[str, int]:
+    """Directory-name -> plan rank, from state/knowledge.json item titles."""
+    f = paths.knowledge_plan_file
+    if not f.is_file():
+        return {}
+    try:
+        plan = json.loads(f.read_text(encoding="utf-8"))
+    except json.JSONDecodeError:
+        return {}
+    rank: dict[str, int] = {}
+    if not isinstance(plan, dict):
+        return rank
+    i = 0
+    for kind in ("modules", "cards"):
+        for item in plan.get(kind) or []:
+            if isinstance(item, dict) and item.get("title"):
+                rank.setdefault(sanitize_component(item["title"]), i)
+                i += 1
+    return rank
+
+
+def _module_title(paths: WikiPaths, d: Path) -> str:
+    f = d / "_module.yaml"
+    if f.is_file():
+        try:
+            meta = yaml.safe_load(f.read_text(encoding="utf-8")) or {}
+            if isinstance(meta, dict) and meta.get("title"):
+                return str(meta["title"])
+        except yaml.YAMLError:
+            pass
+    return d.name
+
+
+def _card_body(raw: str, dirname: str) -> tuple[str, str]:
+    """Strip YAML front matter for display; title = fm name / first H1 / dir."""
+    title = dirname
+    body = raw
+    fm = _FM_RE.match(raw)
+    meta = {}
+    if fm:
+        body = raw[fm.end():]
+        try:
+            meta = yaml.safe_load(fm.group(1)) or {}
+        except yaml.YAMLError:
+            meta = {}
+        if isinstance(meta, dict) and meta.get("name"):
+            title = str(meta["name"])
+    if title == dirname:
+        h1 = _H1_RE.search(body)
+        if h1:
+            title = h1.group(1).strip()
+    return body, title
+
+
+# --- source snippet extraction ---
+
+def _collect_snippets(repo_root: Path, pages: list[dict]) -> dict:
+    snippets: dict = {}
+    for p in pages:
+        for path, start, end in extract_refs(p["md"]):
+            if start is None:
+                key, s, e = path, 1, None
+            else:
+                key, s, e = f"{path}#L{start}-L{end}", start, end
+            if key in snippets:
+                continue
+            lines = _read_lines(repo_root / path)
+            if lines is None:
+                snippets[key] = {"path": path, "missing": True}
+                continue
+            e = min(e or len(lines), len(lines))
+            s = max(1, min(s, e))
+            if e - s + 1 > MAX_SNIPPET_LINES:
+                snippets[key] = {"path": path, "missing": True}
+                continue
+            snippets[key] = {"path": path, "start": s, "end": e, "lines": lines[s - 1:e]}
+    return snippets
+
+
+def _read_lines(p: Path) -> list[str] | None:
+    try:
+        if not p.is_file():
+            return None
+        data = p.read_bytes()
+        if b"\0" in data[:8192]:  # binary file
+            return None
+        return data.decode("utf-8", "replace").splitlines()
+    except OSError:
+        return None
+
+
+# --- HTML assembly ---
+
+def _render_html(payload: dict, locale: str) -> str:
+    payload_js = json.dumps(payload, ensure_ascii=False).replace("<", "\\u003c")
+    shell = (templates.TEMPLATE_DIR / "site.html").read_text(encoding="utf-8")
+    app_js = _script_safe((templates.TEMPLATE_DIR / "site" / "app.js").read_text(encoding="utf-8"))
+    return templates.render(
+        shell,
+        SITE_PAYLOAD=payload_js,
+        MARKED_JS=_vendor("marked.min.js"),
+        MERMAID_JS=_vendor("mermaid.min.js"),
+        APP_JS=app_js,
+    )
+
+
+def _vendor(name: str) -> str:
+    js = (Path(__file__).parent / "vendor" / name).read_text(encoding="utf-8")
+    return _script_safe(js)
+
+
+def _script_safe(js: str) -> str:
+    # Inside an inline <script> the literal `</script` would close the tag;
+    # `<\/script` is an equivalent escape inside JS strings and regexes.
+    return js.replace("</script", "<\\/script")