XCEngine/docs/api/_tools/audit_api_docs.py

from __future__ import annotations

import argparse
import re
from collections import defaultdict
from dataclasses import dataclass
from datetime import datetime
from pathlib import Path


SCRIPT_DIR = Path(__file__).resolve().parent
DOC_ROOT = SCRIPT_DIR.parent if SCRIPT_DIR.name == "_tools" else SCRIPT_DIR
REPO_ROOT = DOC_ROOT.parents[1]
INCLUDE_ROOT = REPO_ROOT / "engine" / "include"
PUBLIC_INCLUDE_ROOT = INCLUDE_ROOT / "XCEngine"
EDITOR_SOURCE_ROOT = REPO_ROOT / "editor" / "src"
PARALLEL_ROOT = DOC_ROOT / "XCEngine"
META_ROOT = DOC_ROOT / "_meta"
DEFAULT_REPORT = META_ROOT / "rebuild-status.md"

HEADER_RE = re.compile(r"^\*\*头文件\*\*:\s*`([^`]+\.h)`", re.MULTILINE)
SOURCE_FILE_RE = re.compile(r"^\*\*源文件\*\*:\s*`([^`]+\.(?:h|hpp))`", re.MULTILINE)
NAMESPACE_RE = re.compile(r"^\*\*命名空间\*\*:\s*`[^`]+`", re.MULTILINE)
TYPE_RE = re.compile(r"^\*\*类型\*\*:\s*`[^`]+`", re.MULTILINE)
DESCRIPTION_RE = re.compile(r"^\*\*描述\*\*:\s*.+$", re.MULTILINE)
MD_LINK_RE = re.compile(r"\[([^\]]+)\]\(([^)]+)\)")
LEGACY_SECTION_RE = re.compile(r"^## (Syntax|Remarks|See Also|Examples)$", re.MULTILINE)
FENCED_CODE_BLOCK_RE = re.compile(r"```.*?```", re.DOTALL)
ACCESS_SPECIFIER_RE = re.compile(r"^(public|private|protected)\s*:\s*$")
IMPORTER_VERSION_RE = re.compile(r"kCurrentImporterVersion\s*=\s*(\d+)")
STALE_EDITOR_DOC_TOKENS: tuple[tuple[str, str], ...] = (
    ("MakeMigrateSceneAssetReferencesAction", "已删除的 Editor action helper"),
    ("ExecuteMigrateSceneAssetReferences", "已删除的主菜单动作"),
    ("CanMigrateSceneAssetReferences", "已删除的 ProjectCommands guard"),
    ("MigrateSceneAssetReferences", "已删除的迁移 API"),
    ("SceneAssetReferenceMigrationReport", "已删除的迁移报告类型"),
    ("Migrate Scene AssetRefs", "已删除的主菜单项文案"),
    (
        "ProjectCommandsMigrateSceneAssetReferencesRewritesLegacyScenePayloads",
        "已删除的相关测试锚点",
    ),
)
STALE_EDITOR_PAGE_TOKENS: tuple[tuple[str, str, str], ...] = (
    (
        "XCEngine/Editor/Core/EditorConsoleSink/",
        "fallback 实例",
        "与当前 EditorConsoleSink::GetInstance 生命周期不符的旧描述",
    ),
    (
        "XCEngine/Editor/Core/EditorConsoleSink/",
        "不会返回空指针",
        "与当前 EditorConsoleSink::GetInstance 可返回 nullptr 的实现不符",
    ),
    (
        "XCEngine/Editor/Core/EditorConsoleSink/",
        "不会返回 `nullptr`",
        "与当前 EditorConsoleSink::GetInstance 可返回 nullptr 的实现不符",
    ),
    (
        "XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/",
        "static SceneViewportOverlayFrameData Build(",
        "SceneViewportOverlayBuilder 已改为实例方法 Build(...) + provider registry 驱动，不应再写成 static Build。",
    ),
    (
        "XCEngine/Editor/Viewport/SceneViewportOverlayBuilder/",
        "无状态构建器",
        "SceneViewportOverlayBuilder 当前持有 provider registry，不再是无状态 helper。",
    ),
)
STALE_CANONICAL_PAGE_TOKENS: tuple[tuple[str, str, str], ...] = (
    (
        "XCEngine/Rendering/CameraRenderRequest/",
        "builtinPostProcess",
        "与当前 CameraRenderRequest 已删除该字段的实现不符",
    ),
    (
        "XCEngine/Rendering/CameraRenderRequest/",
        "BuiltinPostProcessRequest",
        "与当前 CameraRenderRequest 已删除该子请求对象的实现不符",
    ),
    (
        "XCEngine/Rendering/CameraRenderer/",
        "m_builtinPostProcessBuilder",
        "与当前 CameraRenderer 已删除该成员的实现不符",
    ),
    (
        "XCEngine/Core/Asset/ArtifactFormats/",
        "kMaterialArtifactSchemaVersion = 1",
        "与当前材质 artifact schema 已升级到 v2 的实现不符",
    ),
    (
        "XCEngine/Core/Asset/ArtifactFormats/",
        "XCMAT01",
        "与当前材质 artifact magic `XCMAT02` 的实现不符",
    ),
    (
        "XCEngine/Rendering/Pipelines/BuiltinForwardPipeline/",
        "逐材质常量目前只写入 `baseColorFactor`",
        "与当前 BuiltinForwardPipeline 优先消费 shader schema 常量 payload、仅在缺失时回退到 `baseColorFactor` 的实现不符",
    ),
    (
        "XCEngine/Rendering/RenderMaterialUtility/RenderMaterialUtility.md",
        "BuildBuiltinForwardMaterialData() 当前只打包 `baseColorFactor`；贴图仍由调用方单独通过 [ResolveBuiltinBaseColorTexture](ResolveBuiltinBaseColorTexture.md) 解析。",
        "与当前 BuiltinForwardPipeline 已优先通过 `ResolveSchemaMaterialConstantPayload()` 消费 schema-driven 材质常量 payload 的实现不符",
    ),
)
STALE_EDITOR_CANONICAL_PAGES: tuple[tuple[str, str], ...] = (
    (
        "XCEngine/Editor/Managers/ProjectManager/MigrateSceneAssetReferences.md",
        "已删除 API 的残留 canonical 页面",
    ),
)


@dataclass
class EditorRiskEntry:
    doc_page: str
    source_file: str
    direct_page_count: int
    public_method_count: int
    implementation_line_count: int


@dataclass
class ModuleCoverage:
    module: str
    public_headers: int
    documented_headers: int

    @property
    def missing_headers(self) -> int:
        return self.public_headers - self.documented_headers


@dataclass
class StaleDocTokenMatch:
    doc_page: str
    token: str
    reason: str
    line_number: int
    line_text: str


@dataclass
class StaleCanonicalPageMatch:
    doc_page: str
    reason: str


def normalize_rel_path(path: str) -> str:
    return path.replace("\\", "/")


def iter_markdown_files() -> list[Path]:
    return sorted(
        path
        for path in DOC_ROOT.rglob("*.md")
        if path.name != DEFAULT_REPORT.name
    )


def iter_canonical_markdown_files() -> list[Path]:
    return sorted(
        path
        for path in PARALLEL_ROOT.rglob("*.md")
    )


def iter_public_headers() -> list[str]:
    return sorted(
        normalize_rel_path(path.relative_to(INCLUDE_ROOT).as_posix())
        for path in PUBLIC_INCLUDE_ROOT.rglob("*.h")
    )


def iter_editor_source_headers() -> list[str]:
    return sorted(
        normalize_rel_path(path.relative_to(REPO_ROOT).as_posix())
        for path in EDITOR_SOURCE_ROOT.rglob("*.h")
    )


def iter_public_include_dirs() -> list[str]:
    dirs = ["XCEngine"]
    dirs.extend(
        f"XCEngine/{path.relative_to(PUBLIC_INCLUDE_ROOT).as_posix()}"
        for path in sorted(PUBLIC_INCLUDE_ROOT.rglob("*"))
        if path.is_dir()
    )
    return dirs


def dir_index_name(relative: str) -> str:
    return f"{Path(relative).name}.md"


def dir_index_doc_path(relative: str) -> Path:
    return DOC_ROOT / relative / dir_index_name(relative)


def resolve_md_target(source: Path, target: str) -> Path:
    clean = target.split("#", 1)[0].replace("\\", "/")
    return (source.parent / clean).resolve()


def strip_fenced_code_blocks(content: str) -> str:
    return FENCED_CODE_BLOCK_RE.sub("", content)


def count_non_empty_source_lines(path: Path) -> int:
    if not path.exists():
        return 0

    count = 0
    for line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
        stripped = line.strip()
        if not stripped or stripped.startswith("//"):
            continue
        count += 1
    return count


def count_public_method_like_declarations(path: Path) -> int:
    if not path.exists():
        return 0

    in_public_block = False
    pending: list[str] = []
    count = 0

    for raw_line in path.read_text(encoding="utf-8", errors="ignore").splitlines():
        line = raw_line.strip()
        if not line or line.startswith("//"):
            continue

        access_match = ACCESS_SPECIFIER_RE.match(line)
        if access_match:
            in_public_block = access_match.group(1) == "public"
            pending.clear()
            continue

        if not in_public_block:
            continue

        pending.append(line)
        if not any(token in line for token in (";", "{")):
            continue

        declaration = " ".join(pending)
        pending.clear()

        if "(" not in declaration or ")" not in declaration:
            continue
        if declaration.startswith(("using ", "friend ", "static_assert", "#")):
            continue
        if declaration.startswith(("return ", "if ", "for ", "while ", "switch ")):
            continue

        count += 1

    return count


def is_dir_index_page(page: Path) -> bool:
    if not page.is_relative_to(PARALLEL_ROOT):
        return False
    if page.stem != page.parent.name:
        return False

    relative_dir = page.parent.relative_to(PARALLEL_ROOT)
    source_dir = PUBLIC_INCLUDE_ROOT / relative_dir
    return source_dir.exists() and source_dir.is_dir()


def is_flat_header_page(page: Path, rel_page: str) -> bool:
    if not rel_page.startswith("XCEngine/"):
        return False
    if is_dir_index_page(page):
        return False
    return (INCLUDE_ROOT / Path(rel_page).with_suffix(".h")).exists()


def build_editor_module_coverages(
    editor_headers: list[str],
    documented_sources: set[str],
) -> list[ModuleCoverage]:
    source_by_module: dict[str, list[str]] = defaultdict(list)
    documented_by_module: dict[str, set[str]] = defaultdict(set)

    for source in editor_headers:
        relative = Path(source).relative_to("editor/src").as_posix()
        module = relative.split("/", 1)[0] if "/" in relative else "(root)"
        source_by_module[module].append(source)

    for source in documented_sources:
        relative = Path(source).relative_to("editor/src").as_posix()
        module = relative.split("/", 1)[0] if "/" in relative else "(root)"
        documented_by_module[module].add(source)

    return [
        ModuleCoverage(
            module=module,
            public_headers=len(headers),
            documented_headers=len(documented_by_module.get(module, set())),
        )
        for module, headers in sorted(source_by_module.items())
    ]


def collect_editor_risk_entries(
    source_pages: dict[str, list[str]],
) -> list[EditorRiskEntry]:
    entries: list[EditorRiskEntry] = []

    for source_file, doc_pages in sorted(source_pages.items()):
        for rel_page in doc_pages:
            page_path = DOC_ROOT / rel_page
            direct_page_count = len(list(page_path.parent.glob("*.md")))
            header_path = REPO_ROOT / source_file
            implementation_path = header_path.with_suffix(".cpp")
            public_method_count = count_public_method_like_declarations(header_path)
            implementation_line_count = count_non_empty_source_lines(implementation_path)

            if direct_page_count > 1:
                continue
            if implementation_line_count < 200 and not (
                implementation_line_count >= 50 and public_method_count >= 8
            ):
                continue

            entries.append(
                EditorRiskEntry(
                    doc_page=rel_page,
                    source_file=source_file,
                    direct_page_count=direct_page_count,
                    public_method_count=public_method_count,
                    implementation_line_count=implementation_line_count,
                )
            )

    entries.sort(
        key=lambda entry: (
            entry.direct_page_count,
            -entry.implementation_line_count,
            -entry.public_method_count,
            entry.doc_page,
        )
    )
    return entries


def collect_stale_editor_doc_token_matches(
    rel_page: str,
    content: str,
) -> list[StaleDocTokenMatch]:
    if not rel_page.startswith("XCEngine/Editor/"):
        return []

    matches: list[StaleDocTokenMatch] = []
    for line_number, raw_line in enumerate(content.splitlines(), start=1):
        line = raw_line.strip()
        if not line:
            continue

        for token, reason in STALE_EDITOR_DOC_TOKENS:
            if token not in raw_line:
                continue

            matches.append(
                StaleDocTokenMatch(
                    doc_page=rel_page,
                    token=token,
                    reason=reason,
                    line_number=line_number,
                    line_text=line,
                )
            )

        for page_prefix, token, reason in STALE_EDITOR_PAGE_TOKENS:
            if not rel_page.startswith(page_prefix):
                continue
            if token not in raw_line:
                continue

            matches.append(
                StaleDocTokenMatch(
                    doc_page=rel_page,
                    token=token,
                    reason=reason,
                    line_number=line_number,
                    line_text=line,
                )
            )

    return matches


def collect_stale_canonical_doc_token_matches(
    rel_page: str,
    content: str,
) -> list[StaleDocTokenMatch]:
    if not rel_page.startswith("XCEngine/"):
        return []

    matches: list[StaleDocTokenMatch] = []
    for line_number, raw_line in enumerate(content.splitlines(), start=1):
        line = raw_line.strip()
        if not line:
            continue

        for page_prefix, token, reason in STALE_CANONICAL_PAGE_TOKENS:
            if not rel_page.startswith(page_prefix):
                continue
            if token not in raw_line:
                continue

            matches.append(
                StaleDocTokenMatch(
                    doc_page=rel_page,
                    token=token,
                    reason=reason,
                    line_number=line_number,
                    line_text=line,
                )
            )

    return matches


def collect_dynamic_canonical_doc_token_matches(
    rel_page: str,
    content: str,
) -> list[StaleDocTokenMatch]:
    if rel_page != "XCEngine/Core/Asset/AssetDatabase/AssetDatabase.md":
        return []

    header_path = INCLUDE_ROOT / "XCEngine/Core/Asset/AssetDatabase.h"
    if not header_path.exists():
        return []

    header_content = header_path.read_text(encoding="utf-8", errors="ignore")
    header_match = IMPORTER_VERSION_RE.search(header_content)
    doc_match = IMPORTER_VERSION_RE.search(content)
    if not header_match or not doc_match:
        return []

    current_version = header_match.group(1)
    documented_version = doc_match.group(1)
    if current_version == documented_version:
        return []

    matches: list[StaleDocTokenMatch] = []
    for line_number, raw_line in enumerate(content.splitlines(), start=1):
        if documented_version not in raw_line or "kCurrentImporterVersion" not in raw_line:
            continue

        matches.append(
            StaleDocTokenMatch(
                doc_page=rel_page,
                token=f"kCurrentImporterVersion = {documented_version}",
                reason=f"与当前 AssetDatabase 头文件中的 importer 版本 `{current_version}` 不符",
                line_number=line_number,
                line_text=raw_line.strip(),
            )
        )
        break

    return matches


def collect_doc_state(report_path: Path) -> dict[str, object]:
    markdown_files = iter_markdown_files()
    canonical_markdown_files = iter_canonical_markdown_files()
    public_headers = iter_public_headers()
    editor_headers = iter_editor_source_headers()
    public_include_dirs = iter_public_include_dirs()

    declared_header_refs: set[str] = set()
    valid_header_refs: set[str] = set()
    canonical_valid_header_refs: set[str] = set()
    invalid_header_refs: list[tuple[str, str]] = []
    declared_source_refs: set[str] = set()
    valid_source_refs: set[str] = set()
    canonical_valid_source_refs: set[str] = set()
    invalid_source_refs: list[tuple[str, str]] = []
    broken_md_links: list[tuple[str, str]] = []
    non_md_relative_links: list[tuple[str, str]] = []
    old_template_pages: list[str] = []
    flat_header_pages: list[str] = []
    editor_source_pages: dict[str, list[str]] = defaultdict(list)
    stale_canonical_doc_token_matches: list[StaleDocTokenMatch] = []
    stale_editor_doc_token_matches: list[StaleDocTokenMatch] = []
    stale_editor_canonical_page_matches: list[StaleCanonicalPageMatch] = []

    metadata_counts = {
        "namespace": 0,
        "type": 0,
        "description": 0,
        "header": 0,
        "source_file": 0,
    }

    for page in markdown_files:
        if page.resolve() == report_path.resolve():
            continue
        rel_page = normalize_rel_path(page.relative_to(DOC_ROOT).as_posix())
        content = page.read_text(encoding="utf-8")
        is_canonical_page = rel_page.startswith("XCEngine/")

        if is_canonical_page and NAMESPACE_RE.search(content):
            metadata_counts["namespace"] += 1
        if is_canonical_page and TYPE_RE.search(content):
            metadata_counts["type"] += 1
        if is_canonical_page and DESCRIPTION_RE.search(content):
            metadata_counts["description"] += 1
        if is_canonical_page and HEADER_RE.search(content):
            metadata_counts["header"] += 1
        if is_canonical_page and SOURCE_FILE_RE.search(content):
            metadata_counts["source_file"] += 1

        if is_canonical_page and LEGACY_SECTION_RE.search(content):
            old_template_pages.append(rel_page)

        if is_flat_header_page(page, rel_page):
            flat_header_pages.append(rel_page)

        for stale_page, reason in STALE_EDITOR_CANONICAL_PAGES:
            if rel_page == stale_page:
                stale_editor_canonical_page_matches.append(
                    StaleCanonicalPageMatch(
                        doc_page=rel_page,
                        reason=reason,
                    )
                )

        stale_editor_doc_token_matches.extend(
            collect_stale_editor_doc_token_matches(rel_page, content)
        )
        stale_canonical_doc_token_matches.extend(
            collect_stale_canonical_doc_token_matches(rel_page, content)
        )
        stale_canonical_doc_token_matches.extend(
            collect_dynamic_canonical_doc_token_matches(rel_page, content)
        )

        for match in HEADER_RE.finditer(content):
            header = normalize_rel_path(match.group(1))
            declared_header_refs.add(header)
            if (INCLUDE_ROOT / header).exists():
                valid_header_refs.add(header)
                if is_canonical_page:
                    canonical_valid_header_refs.add(header)
            elif is_canonical_page:
                invalid_header_refs.append((rel_page, header))

        for match in SOURCE_FILE_RE.finditer(content):
            source_file = normalize_rel_path(match.group(1))
            declared_source_refs.add(source_file)
            if source_file.startswith("editor/src/") and (REPO_ROOT / source_file).exists():
                valid_source_refs.add(source_file)
                if rel_page.startswith("XCEngine/Editor/"):
                    canonical_valid_source_refs.add(source_file)
                    editor_source_pages[source_file].append(rel_page)
            elif rel_page.startswith("XCEngine/Editor/"):
                invalid_source_refs.append((rel_page, source_file))

        if is_canonical_page or rel_page.startswith(("_meta/", "_tools/")):
            link_scan_content = strip_fenced_code_blocks(content)
            for _, target in MD_LINK_RE.findall(link_scan_content):
                if target.startswith(("http://", "https://", "mailto:", "#")):
                    continue

                normalized = target.replace("\\", "/")
                if normalized.endswith(".md") or ".md#" in normalized:
                    resolved = resolve_md_target(page, normalized)
                    if not resolved.exists() and resolved != report_path.resolve():
                        broken_md_links.append((rel_page, target))
                    continue

                non_md_relative_links.append((rel_page, target))

    public_by_module: dict[str, list[str]] = defaultdict(list)
    documented_by_module: dict[str, set[str]] = defaultdict(set)

    for header in public_headers:
        module = header.split("/", 2)[1]
        public_by_module[module].append(header)

    for header in canonical_valid_header_refs:
        if not header.startswith("XCEngine/"):
            continue
        module = header.split("/", 2)[1]
        documented_by_module[module].add(header)

    module_coverages = [
        ModuleCoverage(
            module=module,
            public_headers=len(headers),
            documented_headers=len(documented_by_module.get(module, set())),
        )
        for module, headers in sorted(public_by_module.items())
    ]
    editor_module_coverages = build_editor_module_coverages(
        editor_headers,
        canonical_valid_source_refs,
    )

    missing_headers = [
        header for header in public_headers if header not in canonical_valid_header_refs
    ]
    missing_editor_headers = [
        header for header in editor_headers if header not in canonical_valid_source_refs
    ]
    missing_parallel_indexes = [
        relative
        for relative in public_include_dirs
        if not dir_index_doc_path(relative).exists()
    ]
    editor_risk_entries = collect_editor_risk_entries(editor_source_pages)
    support_top_dirs = sorted(
        path.name
        for path in DOC_ROOT.iterdir()
        if path.is_dir() and path.name in {"_meta", "_tools"}
    )

    return {
        "generated_at": datetime.now(),
        "markdown_files": markdown_files,
        "canonical_markdown_files": canonical_markdown_files,
        "public_headers": public_headers,
        "public_include_dirs": public_include_dirs,
        "declared_header_refs": sorted(declared_header_refs),
        "valid_header_refs": sorted(valid_header_refs),
        "canonical_valid_header_refs": sorted(canonical_valid_header_refs),
        "invalid_header_refs": invalid_header_refs,
        "declared_source_refs": sorted(declared_source_refs),
        "valid_source_refs": sorted(valid_source_refs),
        "canonical_valid_source_refs": sorted(canonical_valid_source_refs),
        "invalid_source_refs": invalid_source_refs,
        "broken_md_links": broken_md_links,
        "non_md_relative_links": non_md_relative_links,
        "old_template_pages": sorted(old_template_pages),
        "flat_header_pages": sorted(flat_header_pages),
        "stale_canonical_doc_token_matches": stale_canonical_doc_token_matches,
        "stale_editor_doc_token_matches": stale_editor_doc_token_matches,
        "stale_editor_canonical_page_matches": stale_editor_canonical_page_matches,
        "missing_headers": missing_headers,
        "editor_headers": editor_headers,
        "editor_module_coverages": editor_module_coverages,
        "missing_editor_headers": missing_editor_headers,
        "editor_risk_entries": editor_risk_entries,
        "module_coverages": module_coverages,
        "metadata_counts": metadata_counts,
        "support_top_dirs": support_top_dirs,
        "missing_parallel_indexes": missing_parallel_indexes,
    }


def format_pairs_table(headers: tuple[str, str], rows: list[tuple[str, str]]) -> list[str]:
    output = [
        f"| {headers[0]} | {headers[1]} |",
        "|------|------|",
    ]
    for left, right in rows:
        output.append(f"| `{left}` | `{right}` |")
    return output


def build_report(state: dict[str, object]) -> str:
    generated_at: datetime = state["generated_at"]  # type: ignore[assignment]
    markdown_files: list[Path] = state["markdown_files"]  # type: ignore[assignment]
    canonical_markdown_files: list[Path] = state["canonical_markdown_files"]  # type: ignore[assignment]
    public_headers: list[str] = state["public_headers"]  # type: ignore[assignment]
    editor_headers: list[str] = state["editor_headers"]  # type: ignore[assignment]
    public_include_dirs: list[str] = state["public_include_dirs"]  # type: ignore[assignment]
    valid_header_refs: list[str] = state["valid_header_refs"]  # type: ignore[assignment]
    canonical_valid_header_refs: list[str] = state["canonical_valid_header_refs"]  # type: ignore[assignment]
    invalid_header_refs: list[tuple[str, str]] = state["invalid_header_refs"]  # type: ignore[assignment]
    valid_source_refs: list[str] = state["valid_source_refs"]  # type: ignore[assignment]
    canonical_valid_source_refs: list[str] = state["canonical_valid_source_refs"]  # type: ignore[assignment]
    invalid_source_refs: list[tuple[str, str]] = state["invalid_source_refs"]  # type: ignore[assignment]
    broken_md_links: list[tuple[str, str]] = state["broken_md_links"]  # type: ignore[assignment]
    non_md_relative_links: list[tuple[str, str]] = state["non_md_relative_links"]  # type: ignore[assignment]
    old_template_pages: list[str] = state["old_template_pages"]  # type: ignore[assignment]
    flat_header_pages: list[str] = state["flat_header_pages"]  # type: ignore[assignment]
    stale_canonical_doc_token_matches: list[StaleDocTokenMatch] = state["stale_canonical_doc_token_matches"]  # type: ignore[assignment]
    stale_editor_doc_token_matches: list[StaleDocTokenMatch] = state["stale_editor_doc_token_matches"]  # type: ignore[assignment]
    stale_editor_canonical_page_matches: list[StaleCanonicalPageMatch] = state["stale_editor_canonical_page_matches"]  # type: ignore[assignment]
    missing_headers: list[str] = state["missing_headers"]  # type: ignore[assignment]
    missing_editor_headers: list[str] = state["missing_editor_headers"]  # type: ignore[assignment]
    editor_module_coverages: list[ModuleCoverage] = state["editor_module_coverages"]  # type: ignore[assignment]
    editor_risk_entries: list[EditorRiskEntry] = state["editor_risk_entries"]  # type: ignore[assignment]
    module_coverages: list[ModuleCoverage] = state["module_coverages"]  # type: ignore[assignment]
    metadata_counts: dict[str, int] = state["metadata_counts"]  # type: ignore[assignment]
    support_top_dirs: list[str] = state["support_top_dirs"]  # type: ignore[assignment]
    missing_parallel_indexes: list[str] = state["missing_parallel_indexes"]  # type: ignore[assignment]

    lines: list[str] = []
    lines.append("# API 文档重构状态")
    lines.append("")
    lines.append(f"**生成时间**: `{generated_at.strftime('%Y-%m-%d %H:%M:%S')}`")
    lines.append("")
    lines.append("**来源**: `docs/api/_tools/audit_api_docs.py`")
    lines.append("")
    lines.append("## 摘要")
    lines.append("")
    lines.append(f"- Markdown 页面数（全部）: `{len(markdown_files)}`")
    lines.append(f"- Markdown 页面数（canonical）: `{len(canonical_markdown_files)}`")
    lines.append(f"- Public headers 数: `{len(public_headers)}`")
    lines.append(f"- Editor source headers 数: `{len(editor_headers)}`")
    lines.append(f"- 有效头文件引用数（全部）: `{len(valid_header_refs)}`")
    lines.append(f"- 有效头文件引用数（canonical）: `{len(canonical_valid_header_refs)}`")
    lines.append(f"- 无效头文件引用数: `{len(invalid_header_refs)}`")
    lines.append(f"- 有效源文件引用数（全部）: `{len(valid_source_refs)}`")
    lines.append(f"- 有效源文件引用数（Editor canonical）: `{len(canonical_valid_source_refs)}`")
    lines.append(f"- 无效源文件引用数: `{len(invalid_source_refs)}`")
    lines.append(f"- 失效 `.md` 链接数: `{len(broken_md_links)}`")
    lines.append(f"- 非 `.md` 相对链接数: `{len(non_md_relative_links)}`")
    lines.append(f"- 旧模板页面数: `{len(old_template_pages)}`")
    lines.append(f"- 扁平 header 页面数: `{len(flat_header_pages)}`")
    lines.append(f"- Canonical 显式过期符号残留数: `{len(stale_canonical_doc_token_matches)}`")
    lines.append(f"- Editor 显式过期符号残留数: `{len(stale_editor_doc_token_matches)}`")
    lines.append(f"- Editor 残留 canonical 旧页面数: `{len(stale_editor_canonical_page_matches)}`")
    lines.append(f"- Editor 高风险单页目录数: `{len(editor_risk_entries)}`")
    lines.append("")
    lines.append("## 平行目录")
    lines.append("")
    lines.append(f"- Canonical 根目录: `{PARALLEL_ROOT.relative_to(DOC_ROOT).as_posix()}`")
    lines.append(f"- 源码目录节点数: `{len(public_include_dirs)}`")
    lines.append(
        f"- 已生成目录总览页节点数: `{len(public_include_dirs) - len(missing_parallel_indexes)}`"
    )
    lines.append(f"- 缺失目录总览页节点数: `{len(missing_parallel_indexes)}`")
    if support_top_dirs:
        lines.append(f"- 支撑目录: `{', '.join(support_top_dirs)}`")
    lines.append("")
    lines.append("## 模块覆盖")
    lines.append("")
    lines.append("| 模块 | Public headers | 已覆盖 | 未覆盖 |")
    lines.append("|------|----------------|--------|--------|")
    for coverage in module_coverages:
        lines.append(
            f"| `{coverage.module}` | `{coverage.public_headers}` | "
            f"`{coverage.documented_headers}` | `{coverage.missing_headers}` |"
        )
    lines.append("")
    lines.append("## Editor 源文件页覆盖")
    lines.append("")
    lines.append("| 模块 | Source headers | 已覆盖 | 未覆盖 |")
    lines.append("|------|----------------|--------|--------|")
    for coverage in editor_module_coverages:
        lines.append(
            f"| `{coverage.module}` | `{coverage.public_headers}` | "
            f"`{coverage.documented_headers}` | `{coverage.missing_headers}` |"
        )
    lines.append("")
    lines.append("## 元信息覆盖")
    lines.append("")
    lines.append("| 字段 | 页面数 |")
    lines.append("|------|--------|")
    lines.append(f"| `命名空间` | `{metadata_counts['namespace']}` |")
    lines.append(f"| `类型` | `{metadata_counts['type']}` |")
    lines.append(f"| `描述` | `{metadata_counts['description']}` |")
    lines.append(f"| `头文件` | `{metadata_counts['header']}` |")
    lines.append(f"| `源文件` | `{metadata_counts['source_file']}` |")
    lines.append("")

    if missing_parallel_indexes:
        lines.append("## 缺失的平行目录总览页")
        lines.append("")
        for relative in missing_parallel_indexes:
            lines.append(f"- `{relative}`")
        lines.append("")

    if invalid_header_refs:
        lines.append("## 无效头文件引用")
        lines.append("")
        lines.extend(format_pairs_table(("文档", "头文件"), invalid_header_refs[:50]))
        lines.append("")

    if invalid_source_refs:
        lines.append("## 无效源文件引用")
        lines.append("")
        lines.extend(format_pairs_table(("文档", "源文件"), invalid_source_refs[:50]))
        lines.append("")

    if broken_md_links:
        lines.append("## 失效 Markdown 链接")
        lines.append("")
        lines.extend(format_pairs_table(("文档", "目标"), broken_md_links[:50]))
        lines.append("")

    if non_md_relative_links:
        lines.append("## 非 `.md` 相对链接")
        lines.append("")
        lines.extend(format_pairs_table(("文档", "目标"), non_md_relative_links[:50]))
        lines.append("")

    if old_template_pages:
        lines.append("## 旧模板页面")
        lines.append("")
        for page in old_template_pages[:80]:
            lines.append(f"- `{page}`")
        if len(old_template_pages) > 80:
            lines.append(f"- 其余 `{len(old_template_pages) - 80}` 个页面请直接运行脚本查看。")
        lines.append("")

    if flat_header_pages:
        lines.append("## 扁平 header 页面")
        lines.append("")
        for page in flat_header_pages[:120]:
            lines.append(f"- `{page}`")
        if len(flat_header_pages) > 120:
            lines.append(f"- 其余 `{len(flat_header_pages) - 120}` 个页面请直接运行脚本查看。")
        lines.append("")

    if stale_canonical_doc_token_matches:
        lines.append("## Canonical 显式过期符号残留")
        lines.append("")
        lines.append("| 文档页 | 过期符号 | 原因 | 行号 | 行内容 |")
        lines.append("|------|----------|------|------|--------|")
        for entry in stale_canonical_doc_token_matches[:80]:
            safe_line_text = entry.line_text.replace("|", "\\|")
            lines.append(
                f"| `{entry.doc_page}` | `{entry.token}` | `{entry.reason}` | "
                f"`{entry.line_number}` | `{safe_line_text}` |"
            )
        if len(stale_canonical_doc_token_matches) > 80:
            lines.append(
                f"| `...` | `...` | `...` | `...` | 其余 `{len(stale_canonical_doc_token_matches) - 80}` 项请直接运行脚本查看 |"
            )
        lines.append("")

    if stale_editor_doc_token_matches:
        lines.append("## Editor 显式过期符号残留")
        lines.append("")
        lines.append("| 文档页 | 过期符号 | 原因 | 行号 | 行内容 |")
        lines.append("|------|----------|------|------|--------|")
        for entry in stale_editor_doc_token_matches[:80]:
            safe_line_text = entry.line_text.replace("|", "\\|")
            lines.append(
                f"| `{entry.doc_page}` | `{entry.token}` | `{entry.reason}` | "
                f"`{entry.line_number}` | `{safe_line_text}` |"
            )
        if len(stale_editor_doc_token_matches) > 80:
            lines.append(
                f"| `...` | `...` | `...` | `...` | 其余 `{len(stale_editor_doc_token_matches) - 80}` 项请直接运行脚本查看 |"
            )
        lines.append("")

    if stale_editor_canonical_page_matches:
        lines.append("## Editor 残留 canonical 旧页面")
        lines.append("")
        lines.append("| 文档页 | 原因 |")
        lines.append("|------|------|")
        for entry in stale_editor_canonical_page_matches:
            lines.append(f"| `{entry.doc_page}` | `{entry.reason}` |")
        lines.append("")

    if missing_headers:
        lines.append("## 未覆盖的 public headers")
        lines.append("")
        for header in missing_headers[:120]:
            lines.append(f"- `{header}`")
        if len(missing_headers) > 120:
            lines.append(f"- 其余 `{len(missing_headers) - 120}` 个 header 请直接运行脚本查看。")
        lines.append("")

    if missing_editor_headers:
        lines.append("## 未覆盖的 Editor 源文件页")
        lines.append("")
        for header in missing_editor_headers[:120]:
            lines.append(f"- `{header}`")
        if len(missing_editor_headers) > 120:
            lines.append(f"- 其余 `{len(missing_editor_headers) - 120}` 个源文件请直接运行脚本查看。")
        lines.append("")

    if editor_risk_entries:
        lines.append("## Editor 高风险单页目录")
        lines.append("")
        lines.append("| 文档页 | 源文件 | 目录内直系页面数 | public 成员函数数 | 对应 `.cpp` 有效行数 |")
        lines.append("|------|--------|------------------|-------------------|----------------------|")
        for entry in editor_risk_entries[:40]:
            lines.append(
                f"| `{entry.doc_page}` | `{entry.source_file}` | "
                f"`{entry.direct_page_count}` | `{entry.public_method_count}` | "
                f"`{entry.implementation_line_count}` |"
            )
        if len(editor_risk_entries) > 40:
            lines.append(
                f"| `...` | `...` | `...` | `...` | 其余 `{len(editor_risk_entries) - 40}` 项请直接运行脚本查看 |"
            )
        lines.append("")

    return "\n".join(lines).rstrip() + "\n"


def main() -> int:
    parser = argparse.ArgumentParser(description="Audit XCEngine API documentation.")
    parser.add_argument(
        "--report",
        default=str(DEFAULT_REPORT),
        help="Markdown report output path.",
    )
    args = parser.parse_args()

    report_path = Path(args.report)
    report_path.parent.mkdir(parents=True, exist_ok=True)
    state = collect_doc_state(report_path)
    report_path.write_text(build_report(state), encoding="utf-8")

    print(f"Markdown pages (all): {len(state['markdown_files'])}")
    print(f"Markdown pages (canonical): {len(state['canonical_markdown_files'])}")
    print(f"Public headers: {len(state['public_headers'])}")
    print(f"Editor source headers: {len(state['editor_headers'])}")
    print(f"Valid header refs (all): {len(state['valid_header_refs'])}")
    print(f"Valid header refs (canonical): {len(state['canonical_valid_header_refs'])}")
    print(f"Invalid header refs: {len(state['invalid_header_refs'])}")
    print(f"Valid source refs (all): {len(state['valid_source_refs'])}")
    print(f"Valid source refs (Editor canonical): {len(state['canonical_valid_source_refs'])}")
    print(f"Invalid source refs: {len(state['invalid_source_refs'])}")
    print(f"Broken .md links: {len(state['broken_md_links'])}")
    print(f"Non-.md relative links: {len(state['non_md_relative_links'])}")
    print(f"Old template pages: {len(state['old_template_pages'])}")
    print(f"Flat header pages: {len(state['flat_header_pages'])}")
    print(f"Stale canonical doc tokens: {len(state['stale_canonical_doc_token_matches'])}")
    print(f"Stale editor doc tokens: {len(state['stale_editor_doc_token_matches'])}")
    print(f"Stale editor canonical pages: {len(state['stale_editor_canonical_page_matches'])}")
    print(f"Missing directory index pages: {len(state['missing_parallel_indexes'])}")
    print(f"Editor high-risk single-page dirs: {len(state['editor_risk_entries'])}")
    print(f"Report written to: {report_path}")
    return 0


if __name__ == "__main__":
    raise SystemExit(main())