#!/usr/bin/env python3
"""Validate the machine-checkable book authoring contract."""

from __future__ import annotations

import argparse
import json
import re
import subprocess
import sys
from collections import Counter
from pathlib import Path
from typing import Any, Iterable

from summary import chapter_paths

CJK = r"\u3400-\u4dbf\u4e00-\u9fff\uf900-\ufaff"
ASCII_WORD = r"A-Za-z0-9"
MISSING_SPACE_RE = re.compile(
    rf"(?<=[{CJK}])(?=[{ASCII_WORD}])|(?<=[{ASCII_WORD}])(?=[{CJK}])"
)
EXTRA_SPACE_RE = re.compile(
    rf"(?:[{CJK}] {{2,}}[{ASCII_WORD}]|[{ASCII_WORD}] {{2,}}[{CJK}])"
)
PLACEHOLDER_RE = re.compile(
    r"(?:TBD|TODO|FIXME|XXX|待补充|待填|\{\{[^{}]+\}\})", re.IGNORECASE
)
SLOT_RE = re.compile(r"^<!--\s*slot:\s*([^>]+?)\s*-->$")
SLOT_RAW_RE = re.compile(r"<!--\s*slot:\s*([^>]+?)\s*-->")
CHECKER_FORBID_RE = re.compile(
    r"^<!-- checker-forbid: (?P<phrase>.*) -->$"
)
CHECKER_FORBID_PREFIX = "<!-- checker-forbid:"
ALLOWED_LANGUAGES = {
    "yaml",
    "bash",
    "text",
    "go",
    "json",
    "typescript",
    "tsx",
    "sql",
    "mermaid",
}
ALLOWED_CALLOUTS = {"💡 提示：", "⚠️ 注意：", "❌ 反例：", "✅ 正例：", "🔧 进阶："}
REQUIRED_SLOTS = {
    "目标",
    "边界",
    "提示词",
    "流程",
    "配置",
    "异常",
    "审批",
    "外部系统",
    "验收",
    "媒体槽位",
}


def pandoc_ast(path: Path) -> dict[str, Any]:
    result = subprocess.run(
        [
            "pandoc",
            "--from=markdown+yaml_metadata_block+fenced_divs+link_attributes",
            "--to=json",
            str(path),
        ],
        check=False,
        capture_output=True,
        text=True,
    )
    if result.returncode != 0:
        raise ValueError(f"{path}: Pandoc parse failed: {result.stderr.strip()}")
    return json.loads(result.stdout)


def nodes(value: Any, kind: str) -> Iterable[dict[str, Any]]:
    if isinstance(value, dict):
        if value.get("t") == kind:
            yield value
        for child in value.values():
            yield from nodes(child, kind)
    elif isinstance(value, list):
        for child in value:
            yield from nodes(child, kind)


def prose(value: Any) -> str:
    if isinstance(value, dict):
        kind = value.get("t")
        if kind in {"Code", "CodeBlock", "RawInline", "RawBlock", "Image"}:
            return ""
        if kind == "Str":
            return str(value.get("c", ""))
        if kind in {"Space", "SoftBreak", "LineBreak"}:
            return " "
        return "".join(prose(child) for child in value.values())
    if isinstance(value, list):
        return "".join(prose(child) for child in value)
    return ""


def prose_fragments(value: Any) -> Iterable[str]:
    if isinstance(value, dict):
        if value.get("t") in {"Para", "Plain", "Header"}:
            yield prose(value)
            return
        if value.get("t") in {"Code", "CodeBlock", "RawInline", "RawBlock", "Image"}:
            return
        for child in value.values():
            yield from prose_fragments(child)
    elif isinstance(value, list):
        for child in value:
            yield from prose_fragments(child)


def header_text(header: dict[str, Any]) -> str:
    return prose(header["c"][2]).strip()


def callout_label(block_quote: dict[str, Any]) -> str | None:
    blocks = block_quote.get("c", [])
    if not blocks or blocks[0].get("t") not in {"Para", "Plain"}:
        return None
    inlines = blocks[0].get("c", [])
    if not inlines or inlines[0].get("t") != "Strong":
        return None
    label = prose(inlines[0].get("c", [])).strip()
    if not label.endswith("："):
        return None
    return label


def validate_links(book_dir: Path, path: Path, ast: dict[str, Any]) -> list[str]:
    errors: list[str] = []
    relative = path.relative_to(book_dir)
    for link in nodes(ast, "Link"):
        raw_target = link["c"][2][0].strip()
        if (
            not raw_target
            or raw_target.startswith("#")
            or "://" in raw_target
            or raw_target.startswith(("mailto:", "tel:"))
        ):
            continue
        target_text = raw_target.split("#", 1)[0]
        resolved = (path.parent / target_text).resolve()
        try:
            resolved.relative_to(book_dir)
        except ValueError:
            errors.append(f"{relative}: link leaves book directory: {raw_target}")
            continue
        if not resolved.exists():
            errors.append(f"{relative}: missing link target: {raw_target}")
    return errors


def needs_slots(book_dir: Path, path: Path) -> bool:
    relative = path.relative_to(book_dir).as_posix()
    return (
        relative.startswith("manuscript/")
        and not relative.startswith("manuscript/00-frontmatter/")
        and not relative.endswith("/index.md")
    )


def checker_forbidden_phrases(book_dir: Path) -> tuple[list[str], list[str]]:
    """Read strict, exact-match markers without interpreting prose tables."""
    terminology = book_dir / "TERMINOLOGY.md"
    if not terminology.is_file():
        return [], []

    errors: list[str] = []
    phrases: list[str] = []
    seen: set[str] = set()
    for line_number, line in enumerate(
        terminology.read_text(encoding="utf-8").splitlines(), 1
    ):
        if CHECKER_FORBID_PREFIX not in line:
            continue
        match = CHECKER_FORBID_RE.fullmatch(line)
        if not match:
            errors.append(
                f"TERMINOLOGY.md:{line_number}: malformed checker-forbid marker"
            )
            continue
        phrase = match.group("phrase")
        if not phrase.strip():
            errors.append(
                f"TERMINOLOGY.md:{line_number}: checker-forbid phrase is empty"
            )
        elif phrase != phrase.strip():
            errors.append(
                f"TERMINOLOGY.md:{line_number}: checker-forbid phrase has "
                "surrounding whitespace"
            )
        elif phrase in seen:
            errors.append(
                f"TERMINOLOGY.md:{line_number}: duplicate checker-forbid phrase: "
                f"{phrase}"
            )
        else:
            seen.add(phrase)
            phrases.append(phrase)
    return phrases, errors


def markdown_prose_lines(raw: str) -> Iterable[str]:
    """Yield source prose with code and HTML comments removed.

    Pandoc normalizes repeated spaces, so the raw source is needed for the
    "exactly one CJK/ASCII space" rule. This scanner deliberately handles only
    exclusions declared by STYLE.md: fenced code, inline code, and comments.
    """
    in_fence = False
    fence_marker = ""
    in_comment = False
    for line in raw.splitlines():
        stripped = line.lstrip()
        if in_fence:
            if stripped.startswith(fence_marker):
                in_fence = False
            yield ""
            continue
        fence = re.match(r"^(`{3,}|~{3,})", stripped)
        if fence:
            in_fence = True
            fence_marker = fence.group(1)[0] * len(fence.group(1))
            yield ""
            continue

        result: list[str] = []
        index = 0
        while index < len(line):
            if in_comment:
                end = line.find("-->", index)
                if end == -1:
                    index = len(line)
                    continue
                in_comment = False
                index = end + 3
                continue
            if line.startswith("<!--", index):
                in_comment = True
                index += 4
                continue
            if line[index] == "`":
                marker_length = 1
                while (
                    index + marker_length < len(line)
                    and line[index + marker_length] == "`"
                ):
                    marker_length += 1
                marker = "`" * marker_length
                end = line.find(marker, index + marker_length)
                if end == -1:
                    index += marker_length
                else:
                    index = end + marker_length
                continue
            result.append(line[index])
            index += 1
        yield "".join(result)


def yaml_blocks(
    path: Path, ast: dict[str, Any], *, plans_only: bool = False
) -> tuple[list[dict[str, str]], list[str]]:
    candidates: list[dict[str, str]] = []
    errors: list[str] = []
    for index, block in enumerate(nodes(ast, "CodeBlock"), 1):
        attributes, source = block["c"]
        classes = attributes[1]
        if not classes:
            errors.append(f"{path}: fenced code block {index} has no language")
            continue
        language = classes[0]
        if language not in ALLOWED_LANGUAGES:
            errors.append(
                f"{path}: fenced code block {index} uses unsupported language: "
                f"{language}"
            )
        if language == "yaml" and (
            not plans_only or "apiVersion: loop.plan/v1" in source
        ):
            candidates.append(
                {"path": f"{path}:yaml-block-{index}", "source": source}
            )
    return candidates, errors


def validate_yaml(book_dir: Path, blocks: list[dict[str, str]]) -> list[str]:
    if not blocks:
        return []
    source_book_dir = Path(__file__).resolve().parents[1]
    repository = source_book_dir.parents[1]
    try:
        result = subprocess.run(
            ["go", "run", "./books/_infra/scripts/plancheck"],
            cwd=repository,
            input=json.dumps(blocks, ensure_ascii=False),
            capture_output=True,
            text=True,
            check=False,
        )
    except FileNotFoundError:
        return [
            "Plan checker failed: Go 1.25+ is required; "
            "run `make bootstrap` for installation guidance"
        ]
    if result.returncode != 0:
        return [f"Plan checker failed: {result.stderr.strip()}"]
    return [
        f"{item['path']}: {item['code']}: {item['message']}"
        for item in json.loads(result.stdout)
    ]


def validate_book(book_dir: Path) -> list[str]:
    errors: list[str] = []
    try:
        chapters = chapter_paths(book_dir)
    except (OSError, ValueError) as error:
        return [str(error)]

    listed = {path.resolve() for path in chapters}
    manuscript = {
        path.resolve() for path in (book_dir / "manuscript").rglob("*.md")
    }
    for path in sorted(manuscript - listed):
        errors.append(f"unlisted manuscript: {path.relative_to(book_dir)}")
    for path in sorted(listed - manuscript):
        errors.append(
            f"SUMMARY.md entry is outside manuscript/: {path.relative_to(book_dir)}"
        )

    forbidden_phrases, marker_errors = checker_forbidden_phrases(book_dir)
    errors.extend(marker_errors)

    plan_candidates: list[dict[str, str]] = []
    referenced_media: set[Path] = set()

    for path in chapters:
        relative = path.relative_to(book_dir)
        raw = path.read_text(encoding="utf-8")
        if raw and not raw.endswith("\n"):
            errors.append(f"{relative}: file must end with one newline")
        if raw.endswith("\n\n"):
            errors.append(f"{relative}: file must end with exactly one newline")
        for line_number, line in enumerate(raw.splitlines(), 1):
            if line.endswith((" ", "\t")):
                errors.append(f"{relative}:{line_number}: trailing whitespace")

        try:
            ast = pandoc_ast(path)
        except ValueError as error:
            errors.append(str(error))
            continue

        previous_level = 0
        seen_headers: set[str] = set()
        for header in nodes(ast, "Header"):
            level = int(header["c"][0])
            text = header_text(header)
            if previous_level and level > previous_level + 1:
                errors.append(
                    f"{relative}: heading jumps from H{previous_level} to H{level}: {text}"
                )
            previous_level = level
            normalized = text.casefold()
            if normalized in seen_headers:
                errors.append(f"{relative}: duplicate heading: {text}")
            seen_headers.add(normalized)

        source_prose = list(markdown_prose_lines(raw))
        for visible in prose_fragments(ast):
            if match := PLACEHOLDER_RE.search(visible):
                errors.append(
                    f"{relative}: unfinished placeholder in prose: {match.group(0)}"
                )
            if MISSING_SPACE_RE.search(visible):
                errors.append(f"{relative}: missing space at a CJK/ASCII boundary")
            if EXTRA_SPACE_RE.search(visible):
                errors.append(f"{relative}: multiple spaces at a CJK/ASCII boundary")
            for phrase in forbidden_phrases:
                if phrase in visible:
                    errors.append(
                        f"{relative}: forbidden terminology phrase: {phrase}"
                    )
        for visible in source_prose:
            if EXTRA_SPACE_RE.search(visible):
                errors.append(f"{relative}: multiple spaces at a CJK/ASCII boundary")
                break

        candidates, block_errors = yaml_blocks(relative, ast)
        plan_candidates.extend(candidates)
        errors.extend(block_errors)

        slots: Counter[str] = Counter()
        for block in nodes(ast, "RawBlock"):
            raw_format, content = block["c"]
            match = SLOT_RE.match(content.strip())
            if raw_format == "html" and match:
                slots[match.group(1).strip()] += 1
        raw_slots = Counter(name.strip() for name in SLOT_RAW_RE.findall(raw))
        # Slot enforcement begins once approved canonical templates are merged.
        # Existing pre-template sample chapters remain valid build fixtures.
        templates_available = (
            (book_dir / "templates/chapter.md").is_file()
            and (book_dir / "templates/case.md").is_file()
        )
        if templates_available and needs_slots(book_dir, path) and (
            set(slots) != REQUIRED_SLOTS
            or any(count != 1 for count in slots.values())
            or raw_slots != slots
        ):
            errors.append(
                f"{relative}: expected each canonical slot exactly once in "
                "Pandoc AST and raw Markdown; "
                f"AST={dict(sorted(slots.items()))}, "
                f"raw={dict(sorted(raw_slots.items()))}"
            )

        for image in nodes(ast, "Image"):
            target = image["c"][2][0].split("#", 1)[0]
            if "://" in target:
                continue
            resolved = (path.parent / target).resolve()
            try:
                media_relative = resolved.relative_to(book_dir)
            except ValueError:
                errors.append(f"{relative}: image leaves book directory: {target}")
                continue
            if not resolved.is_file():
                errors.append(f"{relative}: missing image: {target}")
            elif (
                len(media_relative.parts) < 2
                or media_relative.parts[0] != "media"
                or media_relative.parts[1] not in {"shared", "chapters", "cases"}
            ):
                errors.append(
                    f"{relative}: image is not published media: {media_relative}"
                )
            else:
                referenced_media.add(resolved)

        for block_quote in nodes(ast, "BlockQuote"):
            callout = callout_label(block_quote)
            if callout is not None and callout not in ALLOWED_CALLOUTS:
                errors.append(
                    f"{relative}: unsupported callout: {callout}"
                )
        errors.extend(validate_links(book_dir, path, ast))

    published_media: set[Path] = set()
    for directory in ("shared", "chapters", "cases"):
        root = book_dir / "media" / directory
        if root.exists():
            published_media.update(
                path.resolve() for path in root.rglob("*") if path.is_file()
            )
    for path in sorted(published_media - referenced_media):
        errors.append(f"unreferenced published media: {path.relative_to(book_dir)}")

    templates = book_dir / "templates"
    if templates.is_dir():
        for path in sorted(templates.rglob("*.md")):
            relative = path.relative_to(book_dir)
            try:
                ast = pandoc_ast(path)
            except ValueError as error:
                errors.append(str(error))
                continue
            candidates, _ = yaml_blocks(relative, ast, plans_only=True)
            plan_candidates.extend(candidates)

    errors.extend(validate_yaml(book_dir, plan_candidates))
    return errors


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument(
        "--book-dir", type=Path, default=Path(__file__).resolve().parents[1]
    )
    args = parser.parse_args()
    book_dir = args.book_dir.resolve()
    errors = validate_book(book_dir)
    if errors:
        for error in errors:
            print(f"error: {error}", file=sys.stderr)
        return 1
    print(
        f"Validated {len(chapter_paths(book_dir))} manuscript files "
        "against the book authoring contract."
    )
    return 0


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