#!/usr/bin/env python3
"""Generate compliant TSL codegen markdown from a YAML/JSON entry file.

The recording format is one leaf page: a `module` title, a relative `path`, and
an ordered `declarations` list containing function, class, or unit entries. This
script renders it to the markdown the codegen tree stores, matching
tools/tsl-codegen/STANDARD.md.

Rendered Markdown is passed through the repository-pinned Prettier before it is
written, keeping generated pages consistent with the existing codegen tree.

Input dispatch is by extension: .json parses with the stdlib (keeping the
toolchain dependency-free); .yml/.yaml needs pyyaml. If pyyaml is missing the
script says so and points at the JSON path.

Function declaration fields:
    kind       required  `function`
    name       required  must match the signature name case-insensitively
    signature  required  verbatim, underscores/case untouched
    desc       required  description; may contain multiple lines
    tags       optional  list of Chinese keywords -> `<!-- tags: ... -->`
    params     required when the signature takes args; omit for nullary
    returns    required  return type
    example    optional  fenced tsl block, pasted verbatim
Each param: name/type/desc required; optional (bool) -> `可选。` prefix;
values (list of {value, desc}) -> a `**name 取值**` enum section.

Usage (run from repo root):
    python tools/tsl-codegen/scripts/generate.py --file entry.yml
    python tools/tsl-codegen/scripts/generate.py --file entry.json \
        --scope my-project
    python tools/tsl-codegen/scripts/generate.py --dir recordings
"""

import argparse
import json
import os
import shutil
import subprocess
import sys
import tempfile
from pathlib import Path, PureWindowsPath

REPO_ROOT = Path(__file__).resolve().parents[3]
PRETTIER_CONFIG = REPO_ROOT / ".prettierrc.json"
FORMAT_SUFFIXES = {
    None: (".json", ".yaml", ".yml"),
    "json": (".json",),
    "yaml": (".yaml", ".yml"),
}


class ChineseArgumentParser(argparse.ArgumentParser):
    def error(self, message):
        replacements = (
            ("unrecognized arguments:", "无法识别的参数："),
            ("the following arguments are required:", "缺少必需参数："),
            ("expected one argument", "需要一个参数值"),
            ("invalid choice: ", "取值无效："),
        )
        if message.startswith("argument "):
            message = "参数 " + message[len("argument ") :]
        for source, target in replacements:
            message = message.replace(source, target)
        choice_marker = " (choose from "
        if choice_marker in message and message.endswith(")"):
            message = message[:-1].replace(choice_marker, "（可选值：", 1) + "）"
        self.print_usage(sys.stderr)
        self.exit(2, f"{self.prog}: 错误：{message}\n")


class GenerationError(Exception):
    pass


def die(msg):
    raise GenerationError(msg)


def scope_name(value):
    """Validate a user-defined single directory name."""
    if not value or value in {".", ".."} or "/" in value or "\\" in value:
        raise argparse.ArgumentTypeError("scope 必须是单级目录名")
    return value


def resolve_format(path, fmt):
    """Pick the parser: explicit --format wins, else derive from extension."""
    if fmt:
        return fmt
    suffix = path.suffix.lower()
    if suffix == ".json":
        return "json"
    if suffix in (".yml", ".yaml"):
        return "yaml"
    die(
        f"无法根据扩展名 {suffix or '（无扩展名）'} 判断录入格式；"
        "请使用 --format json 或 --format yaml"
    )


def describe_json_error(exc):
    translations = (
        (
            "Expecting property name enclosed in double quotes",
            "对象属性名必须使用双引号",
        ),
        ("Expecting value", "此处缺少有效值"),
        ("Expecting ',' delimiter", "此处缺少逗号分隔符"),
        ("Extra data", "根值之后存在多余内容"),
        ("Unterminated string", "字符串未结束"),
        ("Invalid \\escape", "字符串中包含无效转义"),
        ("Invalid control character", "字符串中包含无效控制字符"),
    )
    for prefix, message in translations:
        if exc.msg.startswith(prefix):
            return message
    return "语法无效"


def load_entries(path, fmt=None):
    """Parse a recording file as JSON (stdlib) or YAML (pyyaml).

    Format is chosen by --format when given, else by file extension.
    """
    try:
        text = path.read_text(encoding="utf-8")
    except UnicodeDecodeError:
        die("文件不是有效的 UTF-8 编码")
    except OSError as exc:
        die(f"读取文件失败：{exc}")
    fmt = resolve_format(path, fmt)
    if fmt == "json":
        try:
            return json.loads(text)
        except json.JSONDecodeError as exc:
            die(
                f"JSON 格式错误：第 {exc.lineno} 行，第 {exc.colno} 列："
                f"{describe_json_error(exc)}"
            )
    if fmt == "yaml":
        try:
            import yaml
        except ImportError:
            die(
                "未安装 pyyaml；请运行 `python -m pip install pyyaml`，"
                "或改用无需额外依赖的 JSON 录入文件"
            )
        try:
            return yaml.safe_load(text)
        except yaml.YAMLError as exc:
            mark = getattr(exc, "problem_mark", None)
            if mark is None:
                die("YAML 格式错误：语法无效")
            die(
                f"YAML 格式错误：第 {mark.line + 1} 行，第 {mark.column + 1} 列："
                "语法无效"
            )
    die(f"不支持的录入格式：{fmt}；只能使用 json 或 yaml")


def escape_cell(text):
    """Escape `|` so a value stays inside one markdown table cell."""
    return str(text).replace("|", "\\|")


def require(cond, msg):
    if not cond:
        die(msg)


def require_mapping(value, where):
    require(isinstance(value, dict), f"{where}：必须是对象")


def reject_unknown(mapping, allowed, where):
    unknown = sorted(set(mapping) - set(allowed))
    require(not unknown, f"{where}：存在未知字段：{', '.join(unknown)}")


def non_empty_string(value, where):
    require(isinstance(value, str) and value.strip(), f"{where}：不能为空")


def optional_draft_string(value, where):
    if value == "":
        return
    non_empty_string(value, where)


def validate_tags(tags, where):
    if tags is None:
        return
    require(isinstance(tags, list) and tags, f"{where}：tags 必须是非空列表")
    for index, tag in enumerate(tags):
        non_empty_string(tag, f"{where}: tags[{index}]")


def signature_names(signature, where):
    non_empty_string(signature, f"{where}: signature")
    left = signature.find("(")
    right = signature.rfind(")")
    require(left > 0 and right == len(signature) - 1, f"{where}：signature 格式无效")
    name = signature[:left]
    non_empty_string(name, f"{where}: signature name")
    raw = signature[left + 1 : right].strip()
    if not raw:
        return name, []
    names = [item.strip() for item in raw.split(",")]
    require(all(names), f"{where}：signature 中存在空参数名")
    require(
        len({item.casefold() for item in names}) == len(names),
        f"{where}：signature 中存在重复参数名",
    )
    return name, names


def validate_values(values, where):
    require(isinstance(values, list) and values, f"{where}：values 必须是非空列表")
    for index, item in enumerate(values):
        item_where = f"{where}[{index}]"
        require_mapping(item, item_where)
        reject_unknown(item, {"value", "desc"}, item_where)
        require("value" in item, f"{item_where}：缺少 value")
        non_empty_string(item.get("desc"), f"{item_where}: desc")


def validate_params(params, expected_names, where):
    if not expected_names:
        require(not params, f"{where}：无参数 signature 不能包含 params")
        return
    require(isinstance(params, list), f"{where}：params 必须是列表")
    require(len(params) == len(expected_names), f"{where}：params 与 signature 不匹配")
    actual_names = []
    for index, param in enumerate(params):
        param_where = f"{where}: params[{index}]"
        require_mapping(param, param_where)
        reject_unknown(
            param, {"name", "type", "desc", "optional", "values"}, param_where
        )
        name = param.get("name")
        non_empty_string(name, f"{param_where}: name")
        non_empty_string(param.get("type"), f"{param_where}: type")
        non_empty_string(param.get("desc"), f"{param_where}: desc")
        if "optional" in param:
            require(
                isinstance(param["optional"], bool),
                f"{param_where}：optional 必须是布尔值",
            )
        if "values" in param:
            validate_values(param["values"], f"{param_where}: values")
        actual_names.append(name)
    require(
        [name.casefold() for name in actual_names]
        == [name.casefold() for name in expected_names],
        f"{where}：params 必须与 signature 中的参数顺序一致",
    )


def validate_examples(examples, where):
    require(
        isinstance(examples, list) and examples, f"{where}：examples 必须是非空列表"
    )
    for index, example in enumerate(examples):
        example_where = f"{where}: examples[{index}]"
        require_mapping(example, example_where)
        reject_unknown(example, {"desc", "code", "output"}, example_where)
        non_empty_string(example.get("desc"), f"{example_where}: desc")
        non_empty_string(example.get("code"), f"{example_where}: code")
        if "output" in example:
            non_empty_string(example["output"], f"{example_where}: output")


def validate_function(fn, where, *, returns_required, extra_fields=()):
    require_mapping(fn, where)
    allowed = {
        "signature",
        "desc",
        "tags",
        "params",
        "returns",
        "example",
        "examples",
        *extra_fields,
    }
    reject_unknown(fn, allowed, where)
    name, names = signature_names(fn.get("signature"), where)
    non_empty_string(fn.get("desc"), f"{where}: desc")
    validate_tags(fn.get("tags"), where)
    validate_params(fn.get("params"), names, where)
    if returns_required:
        non_empty_string(fn.get("returns"), f"{where}：缺少 returns")
    elif "returns" in fn:
        optional_draft_string(fn["returns"], f"{where}: returns")
    require(
        not ("example" in fn and "examples" in fn),
        f"{where}：example 和 examples 不能同时存在",
    )
    if "example" in fn:
        non_empty_string(fn["example"], f"{where}: example")
    if "examples" in fn:
        validate_examples(fn["examples"], where)
    return name


def validate_class_member(member, where):
    require_mapping(member, where)
    kind = member.get("kind")
    require(
        kind in {"method", "property", "field", "constant"},
        f"{where}：未知 kind：{kind}",
    )
    non_empty_string(member.get("name"), f"{where}: name")
    visibility = member.get("visibility")
    require(
        visibility in {"public", "protected"},
        f"{where}：visibility 只能是 public 或 protected",
    )
    non_empty_string(member.get("desc"), f"{where}: desc")
    validate_tags(member.get("tags"), where)

    if kind == "method":
        reject_unknown(
            member,
            {
                "kind",
                "name",
                "visibility",
                "binding",
                "signature",
                "desc",
                "tags",
                "params",
                "returns",
                "modifiers",
                "example",
                "examples",
            },
            where,
        )
        require(
            member.get("binding") in {"instance", "class"},
            f"{where}：binding 无效",
        )
        parsed_name = validate_function(
            member,
            where,
            returns_required=False,
            extra_fields={"kind", "name", "visibility", "binding", "modifiers"},
        )
        require(
            parsed_name.casefold() == member["name"].casefold(),
            f"{where}：name 与 signature 中的名称不一致",
        )
        if "modifiers" in member:
            modifiers = member["modifiers"]
            require(isinstance(modifiers, list), f"{where}：modifiers 必须是列表")
            allowed = {"overload", "virtual", "override"}
            require(
                all(item in allowed for item in modifiers),
                f"{where}：存在无效 modifier",
            )
            require(
                len(set(modifiers)) == len(modifiers), f"{where}：存在重复 modifier"
            )
        return

    common = {"kind", "name", "visibility", "desc", "tags"}
    if kind == "property":
        reject_unknown(member, common | {"type", "params", "access"}, where)
        if "type" in member:
            optional_draft_string(member["type"], f"{where}: type")
        require(
            member.get("access") in {"read", "write", "readwrite"},
            f"{where}：access 无效",
        )
        params = member.get("params")
        if params:
            expected = [param.get("name") for param in params]
            validate_params(params, expected, where)
        return
    if kind == "field":
        reject_unknown(member, common | {"type", "static"}, where)
        non_empty_string(member.get("type"), f"{where}: type")
        if "static" in member:
            require(isinstance(member["static"], bool), f"{where}：static 必须是布尔值")
        return
    reject_unknown(member, common | {"type", "value", "static"}, where)
    require("value" in member and member["value"] is not None, f"{where}：缺少 value")
    if isinstance(member["value"], str):
        non_empty_string(member["value"], f"{where}: value")
    if "type" in member:
        optional_draft_string(member["type"], f"{where}: type")
    if "static" in member:
        require(isinstance(member["static"], bool), f"{where}：static 必须是布尔值")


def validate_class(cls, where):
    require_mapping(cls, where)
    reject_unknown(cls, {"kind", "name", "desc", "tags", "bases", "members"}, where)
    require(cls.get("kind") == "class", f"{where}：kind 必须是 class")
    non_empty_string(cls.get("name"), f"{where}: name")
    non_empty_string(cls.get("desc"), f"{where}: desc")
    validate_tags(cls.get("tags"), where)
    if "bases" in cls:
        require(isinstance(cls["bases"], list), f"{where}：bases 必须是列表")
        for index, base in enumerate(cls["bases"]):
            non_empty_string(base, f"{where}: bases[{index}]")
    require(isinstance(cls.get("members"), list), f"{where}：members 必须是列表")
    for index, member in enumerate(cls["members"]):
        validate_class_member(member, f"{where}: members[{index}]")


def validate_unit_member(member, where):
    require_mapping(member, where)
    kind = member.get("kind")
    require(
        kind in {"function", "variable", "constant", "class"},
        f"{where}：未知 kind：{kind}",
    )
    if kind == "class":
        validate_class(member, where)
        return
    non_empty_string(member.get("name"), f"{where}: name")
    non_empty_string(member.get("desc"), f"{where}: desc")
    validate_tags(member.get("tags"), where)
    if kind == "function":
        parsed_name = validate_function(
            member,
            where,
            returns_required=True,
            extra_fields={"kind", "name"},
        )
        require(
            parsed_name.casefold() == member["name"].casefold(),
            f"{where}：name 与 signature 中的名称不一致",
        )
        return
    common = {"kind", "name", "desc", "tags", "type"}
    if kind == "variable":
        reject_unknown(member, common, where)
        non_empty_string(member.get("type"), f"{where}: type")
        return
    reject_unknown(member, common | {"value"}, where)
    require("value" in member and member["value"] is not None, f"{where}：缺少 value")
    if isinstance(member["value"], str):
        non_empty_string(member["value"], f"{where}: value")
    if "type" in member:
        optional_draft_string(member["type"], f"{where}: type")


def validate_unit(unit, where):
    require_mapping(unit, where)
    reject_unknown(unit, {"kind", "name", "desc", "tags", "members"}, where)
    require(unit.get("kind") == "unit", f"{where}：kind 必须是 unit")
    non_empty_string(unit.get("name"), f"{where}: name")
    non_empty_string(unit.get("desc"), f"{where}: desc")
    validate_tags(unit.get("tags"), where)
    require(
        isinstance(unit.get("members"), list),
        f"{where}：members 必须是列表",
    )
    for index, member in enumerate(unit["members"]):
        validate_unit_member(member, f"{where}: members[{index}]")


def validate_top_level_function(declaration, where):
    require(
        declaration.get("kind") == "function",
        f"{where}：kind 必须是 function",
    )
    non_empty_string(declaration.get("name"), f"{where}: name")
    parsed_name = validate_function(
        declaration,
        where,
        returns_required=True,
        extra_fields={"kind", "name"},
    )
    require(
        parsed_name.casefold() == declaration["name"].casefold(),
        f"{where}：name 与 signature 中的名称不一致",
    )


def validate_declaration(declaration, where):
    require_mapping(declaration, where)
    kind = declaration.get("kind")
    require(
        kind in {"function", "class", "unit"},
        f"{where}：未知 kind：{kind}",
    )
    if kind == "function":
        validate_top_level_function(declaration, where)
    elif kind == "class":
        validate_class(declaration, where)
    else:
        validate_unit(declaration, where)


def validate_declaration_uniqueness(declarations):
    function_signatures = set()
    class_names = set()
    unit_names = set()
    for index, declaration in enumerate(declarations):
        where = f"declarations[{index}]"
        kind = declaration["kind"]
        if kind == "function":
            key = declaration["signature"].casefold()
            require(
                key not in function_signatures,
                f"{where}：function signature 重复",
            )
            function_signatures.add(key)
            continue
        names = class_names if kind == "class" else unit_names
        key = declaration["name"].casefold()
        require(key not in names, f"{where}：{kind} 名称重复")
        names.add(key)


def validate_page(data):
    require_mapping(data, "录入根")
    reject_unknown(data, {"module", "path", "declarations"}, "录入根")
    non_empty_string(data.get("module"), "录入根：module")
    non_empty_string(data.get("path"), "录入根：path")
    declarations = data.get("declarations")
    require(
        isinstance(declarations, list) and declarations,
        "录入根：declarations 必须是非空列表",
    )
    for index, declaration in enumerate(declarations):
        validate_declaration(declaration, f"declarations[{index}]")
    validate_declaration_uniqueness(declarations)
    return declarations


def param_desc(param, where):
    """Description column text: prepend `可选。` for optional params."""
    desc = param.get("desc")
    require(desc, f"{where}：参数 {param.get('name', '?')} 缺少 desc")
    if param.get("optional") and not desc.startswith("可选。"):
        return "可选。" + desc
    return desc


def render_param_table(params, where):
    """Three-column 参数/类型/说明 table with single-space padding."""
    lines = ["| 参数 | 类型 | 说明 |", "| --- | --- | --- |"]
    for param in params:
        name = param.get("name")
        ptype = param.get("type")
        require(name, f"{where}：存在缺少 name 的参数")
        require(ptype, f"{where}：参数 {name} 缺少 type")
        desc = param_desc(param, where)
        lines.append(
            f"| `{escape_cell(name)}` | {escape_cell(ptype)} | {escape_cell(desc)} |"
        )
    return lines


def render_enum_sections(params, heading_level=None):
    """Render value sections, preserving legacy function-page headings."""
    lines = []
    for param in params:
        values = param.get("values")
        if not values:
            continue
        if heading_level is None:
            lines.append(f"**{param['name']} 取值**")
        else:
            lines.append(f"{'#' * heading_level} `{param['name']}` 取值")
        lines.append("")
        for item in values:
            lines.append(f"- `{item['value']}` — {item['desc']}")
        lines.append("")
    return lines


def render_examples(fn, heading_level):
    lines = []
    if "examples" in fn:
        lines.extend([f"{'#' * heading_level} 示例", ""])
        for index, example in enumerate(fn["examples"], start=1):
            lines.append(f"范例{index:02d}：{example['desc']}")
            lines.append("")
            lines.append("```tsl")
            lines.extend(example["code"].rstrip("\n").split("\n"))
            output = example.get("output")
            if output is not None:
                output_lines = output.split("\n")
                if len(output_lines) == 1:
                    lines.append(f"// 输出：{output_lines[0]}")
                else:
                    lines.append("// 输出：")
                    lines.extend(
                        f"// {line}" if line else "//" for line in output_lines
                    )
            lines.append("```")
            lines.append("")
        while lines and not lines[-1]:
            lines.pop()
        return lines
    if fn.get("example"):
        return [
            f"{'#' * heading_level} 示例",
            "",
            "```tsl",
            *fn["example"].rstrip("\n").split("\n"),
            "```",
        ]
    return []


def render_intro(heading, declaration, item):
    lines = [heading, "", f"声明：{declaration}", "", item["desc"], ""]
    tags = item.get("tags")
    if tags:
        lines.extend([f"<!-- tags: {' '.join(tags)} -->", ""])
    return lines


def render_callable(
    fn,
    signature,
    declaration,
    where,
    *,
    level,
    returns_required,
    show_visibility,
):
    validate_function(
        fn,
        where,
        returns_required=returns_required,
        extra_fields={"kind", "name", "visibility", "binding", "modifiers"},
    )
    lines = render_intro(f"{'#' * level} `{signature}`", declaration, fn)
    if show_visibility:
        lines.extend([f"可见性：`{fn['visibility']}`", ""])
    if fn.get("modifiers"):
        rendered = "、".join(f"`{item}`" for item in fn["modifiers"])
        lines.extend([f"修饰符：{rendered}", ""])
    params = fn.get("params") or []
    if params:
        lines.extend(render_param_table(params, where))
        lines.append("")
        lines.extend(render_enum_sections(params, level + 1))
    if fn.get("returns"):
        lines.append(f"返回：{fn['returns']}")
    example_lines = render_examples(fn, level + 1)
    if example_lines:
        lines.extend(["", *example_lines])
    return lines


def render_top_level_function(fn, index):
    """Render one function entry to a list of lines (no trailing blank)."""
    where = f"declarations[{index}]"
    sig = fn["signature"]
    lines = render_intro(f"## `{sig}`", "function", fn)

    params = fn.get("params") or []
    if params:
        lines.extend(render_param_table(params, f"{where} ({sig})"))
        lines.append("")
        lines.extend(render_enum_sections(params))

    lines.append(f"返回：{fn['returns']}")
    examples = render_examples(fn, 3)
    if examples:
        lines.extend(["", *examples])
    return lines


def render_class_member(member, level, where):
    kind = member["kind"]
    if kind == "method":
        declaration = "class function" if member["binding"] == "class" else "function"
        return render_callable(
            member,
            member["signature"],
            declaration,
            where,
            level=level,
            returns_required=False,
            show_visibility=True,
        )
    static_prefix = "static " if member.get("static") else ""
    declaration = {
        "property": "property",
        "field": f"{static_prefix}field",
        "constant": f"{static_prefix}const",
    }[kind]
    signature = member["name"]
    if kind == "property" and member.get("params"):
        signature += "(" + ", ".join(param["name"] for param in member["params"]) + ")"
    lines = render_intro(f"{'#' * level} `{signature}`", declaration, member)
    lines.extend([f"可见性：`{member['visibility']}`", ""])
    if kind == "property":
        if member.get("type"):
            lines.extend([f"类型：{member['type']}", ""])
        access = {"read": "read", "write": "write", "readwrite": "read / write"}[
            member["access"]
        ]
        lines.append(f"访问：{access}")
        params = member.get("params") or []
        if params:
            lines.extend(["", *render_param_table(params, where), ""])
            lines.extend(render_enum_sections(params, level + 1))
    elif kind == "field":
        lines.append(f"类型：{member['type']}")
    else:
        if member.get("type"):
            lines.extend([f"类型：{member['type']}", ""])
        lines.append(f"值：`{render_scalar(member['value'])}`")
    return lines


def render_class(cls, level, where, *, page_root):
    lines = render_intro(f"{'#' * level} `{cls['name']}`", "class", cls)
    if cls.get("bases"):
        lines.extend(["父类：" + "、".join(f"`{base}`" for base in cls["bases"]), ""])
    for index, member in enumerate(cls["members"]):
        lines.extend(
            render_class_member(member, level + 1, f"{where}: members[{index}]")
        )
        lines.append("")
    while lines and not lines[-1]:
        lines.pop()
    return lines


def render_unit_member(member, index, unit_where):
    where = f"{unit_where}: members[{index}]"
    kind = member["kind"]
    if kind == "function":
        return render_callable(
            member,
            member["signature"],
            "function",
            where,
            level=3,
            returns_required=True,
            show_visibility=False,
        )
    if kind == "class":
        return render_class(member, 3, where, page_root=False)
    declaration = "var" if kind == "variable" else "const"
    lines = render_intro(f"### `{member['name']}`", declaration, member)
    if kind == "variable":
        lines.append(f"类型：{member['type']}")
    else:
        if member.get("type"):
            lines.extend([f"类型：{member['type']}", ""])
        lines.append(f"值：`{render_scalar(member['value'])}`")
    return lines


def render_unit(unit, where):
    lines = render_intro(f"## `{unit['name']}`", "unit", unit)
    for index, member in enumerate(unit["members"]):
        lines.extend(render_unit_member(member, index, where))
        lines.append("")
    while lines and not lines[-1]:
        lines.pop()
    return lines


def render_scalar(value):
    if isinstance(value, str):
        return value
    return json.dumps(value, ensure_ascii=False)


def render_declaration(declaration, index):
    kind = declaration["kind"]
    where = f"declarations[{index}]"
    if kind == "function":
        return render_top_level_function(declaration, index)
    if kind == "class":
        return render_class(declaration, 2, where, page_root=True)
    return render_unit(declaration, where)


def render_page(data):
    """Validate and render a whole leaf page."""
    declarations = validate_page(data)
    out = [f"# {data['module']}", ""]
    for index, declaration in enumerate(declarations):
        out.extend(render_declaration(declaration, index))
        out.append("")
    return "\n".join(out).rstrip("\n") + "\n"


def format_markdown(text):
    """Format generated Markdown with the repository-pinned Prettier."""
    npx = shutil.which("npx")
    if not npx:
        die("未找到 Prettier；请先在仓库根目录运行 `npm install`")

    result = subprocess.run(
        [
            npx,
            "--no-install",
            "prettier",
            "--config",
            str(PRETTIER_CONFIG),
            "--parser",
            "markdown",
        ],
        input=text,
        capture_output=True,
        text=True,
        encoding="utf-8",
        cwd=REPO_ROOT,
        check=False,
    )
    if result.returncode != 0:
        detail = result.stderr.strip() or "未知错误"
        die(f"Prettier 格式化失败：{detail}")
    return result.stdout


def output_path(data, scope):
    """Build the leaf-page destination from the recording file's relative path."""
    relative = data.get("path")
    require(relative, "录入数据缺少 path")
    require(isinstance(relative, str), "path 必须是字符串")
    recorded_path = PureWindowsPath(relative)
    require(
        not recorded_path.drive.startswith("\\\\"),
        "path 必须是相对路径，不允许 UNC 路径",
    )
    require(
        not recorded_path.drive,
        "path 必须是相对路径，不允许 Windows 盘符路径",
    )
    require(
        not recorded_path.root,
        "path 必须是相对路径，不能以斜杠或反斜杠开头",
    )
    require(
        bool(recorded_path.parts),
        "path 必须指向具体文档，不能只表示当前目录",
    )
    require(
        ".." not in recorded_path.parts,
        "path 不能包含 '..'，不允许跳转到父目录",
    )
    require(
        recorded_path.suffix == "",
        "path 不能包含 .md 等文件扩展名",
    )
    relative_path = Path(*recorded_path.parts)
    return (
        Path("skills/tsl-api-reference/references/codegen")
        / scope
        / relative_path.with_suffix(".md")
    )


def atomic_write(path, text):
    """Atomically replace path and remove the temporary file on failure."""
    path.parent.mkdir(parents=True, exist_ok=True)
    descriptor, temporary_name = tempfile.mkstemp(
        prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
    )
    temporary_path = Path(temporary_name)
    try:
        with os.fdopen(descriptor, "w", encoding="utf-8", newline="\n") as handle:
            handle.write(text)
            handle.flush()
            os.fsync(handle.fileno())
        os.replace(temporary_path, path)
    finally:
        if temporary_path.exists():
            temporary_path.unlink()


def gather_directory_inputs(directory, fmt):
    try:
        if not directory.is_dir():
            die(f"输入目录不存在或不是目录：{directory}")
        suffixes = FORMAT_SUFFIXES[fmt]
        inputs = sorted(
            (
                path
                for path in directory.iterdir()
                if path.is_file() and path.suffix.lower() in suffixes
            ),
            key=lambda path: (path.name.casefold(), path.name),
        )
    except OSError as exc:
        die(f"读取输入目录失败：{directory}：{exc}")
    if not inputs:
        displayed_suffixes = "、".join(suffixes)
        die(
            f"目录 {directory} 中未找到符合条件的直属录入文件"
            f"（{displayed_suffixes}）"
        )
    return inputs


def prepare_input(in_path, input_format, scope):
    data = load_entries(in_path, input_format)
    try:
        rendered = render_page(data)
    except GenerationError as exc:
        raise GenerationError(f"录入数据校验失败：{exc}") from exc
    try:
        out_path = output_path(data, scope)
    except GenerationError as exc:
        raise GenerationError(f"输出路径无效：{exc}") from exc
    try:
        formatted = format_markdown(rendered)
    except OSError as exc:
        raise GenerationError(f"运行 Prettier 失败：{exc}") from exc
    return in_path, out_path, formatted


def report_input_error(in_path, error):
    print(f"错误：{in_path}：{error}", file=sys.stderr)


def find_output_collisions(prepared):
    owners = {}
    collisions = []
    for in_path, out_path, _ in prepared:
        resolved_output = out_path.resolve()
        first_input = owners.get(resolved_output)
        if first_input is None:
            owners[resolved_output] = in_path
            continue
        collisions.append(
            f"输出目标冲突：{first_input} 和 {in_path} 都会写入 {resolved_output}"
        )
    return collisions


def main(argv=None):
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8")
    parser = ChineseArgumentParser(
        description="从 YAML/JSON 录入文件生成 TSL API 文档",
        usage=(
            "%(prog)s [--help] [--scope SCOPE] [--format {json,yaml}] "
            "(--file INPUT_FILE | --dir INPUT_DIR | INPUT_FILE)"
        ),
        add_help=False,
        allow_abbrev=False,
    )
    parser.add_argument(
        "--help",
        action="help",
        help="显示本帮助并退出（不提供 -h 短选项）",
    )
    parser.add_argument(
        "legacy_input",
        nargs="?",
        metavar="INPUT_FILE",
        help="已废弃，请使用 --file；暂时兼容 YAML/JSON 录入文件路径",
    )
    parser.add_argument(
        "--file",
        dest="input_file",
        metavar="INPUT_FILE",
        help="要生成的单个 YAML/JSON 录入文件",
    )
    parser.add_argument(
        "--dir",
        dest="input_dir",
        metavar="INPUT_DIR",
        help="批量生成目录中的直属 YAML/JSON 录入文件",
    )
    parser.add_argument(
        "--scope",
        type=scope_name,
        default="project",
        help="codegen 下的一级目录，可自定义（默认：project）",
    )
    parser.add_argument(
        "--format",
        choices=["json", "yaml"],
        help="录入文件格式；默认根据文件扩展名判断",
    )
    args = parser.parse_args(argv)

    input_modes = (args.legacy_input, args.input_file, args.input_dir)
    if sum(value is not None for value in input_modes) != 1:
        parser.error("必须且只能指定一种输入方式：INPUT_FILE、--file 或 --dir")
    is_batch = args.input_dir is not None
    try:
        if is_batch:
            input_paths = gather_directory_inputs(Path(args.input_dir), args.format)
            input_format = None
        else:
            in_path = Path(args.input_file or args.legacy_input)
            if not in_path.is_file():
                die(f"输入文件不存在或不是普通文件：{in_path}")
            input_paths = [in_path]
            input_format = args.format
    except GenerationError as exc:
        print(f"错误：{exc}", file=sys.stderr)
        return 1

    prepared = []
    input_errors = []
    for in_path in input_paths:
        try:
            prepared.append(prepare_input(in_path, input_format, args.scope))
        except GenerationError as exc:
            input_errors.append((in_path, exc))

    collisions = find_output_collisions(prepared)
    if input_errors or collisions:
        for in_path, error in input_errors:
            report_input_error(in_path, error)
        for collision in collisions:
            print(f"错误：{collision}", file=sys.stderr)
        if is_batch:
            issue_count = len(input_errors) + len(collisions)
            print(
                f"错误：批量生成已中止：发现 {issue_count} 个问题，"
                f"共检查 {len(input_paths)} 个文件；未写入任何 Markdown 文件",
                file=sys.stderr,
            )
        return 1

    for in_path, out_path, text in prepared:
        try:
            atomic_write(out_path, text)
        except OSError as exc:
            report_input_error(in_path, f"写入 Markdown 失败：{out_path}：{exc}")
            return 1
        print(f"已生成：{in_path} -> {out_path}", file=sys.stderr)
    return 0


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