#!/usr/bin/env python3
"""Query bundled TSL API reference data."""
import argparse
import re
import sys
import unicodedata
from pathlib import Path

TOP_LEVEL_RE = re.compile(r"^##(?!#)\s+`(.+?)`\s*$")
PLAIN_H2_RE = re.compile(r"^##(?!#)\s+")
BARE_ENTRY_RE = re.compile(r"^(#{3,4})(?!#)\s+`(.+?)`\s*$")
HEADING_RE = re.compile(r"^(#{1,6})(?!#)\s+")
H3_RE = re.compile(r"^###(?!#)\s+")
DECLARATION_RE = re.compile(r"^声明：(.*?)\s*$")
TOP_LEVEL_TYPES = {"function", "class", "unit"}
FENCE_RE = re.compile(r"^\s*(```|~~~)")
CLASS_MEMBER_LABELS = {
    "function",
    "class function",
    "property",
    "field",
    "static field",
    "const",
    "static const",
}
UNIT_DIRECT_LABELS = {"function", "var", "const", "class"}
SKILL_ROOT = Path(__file__).resolve().parents[1]
DEFAULT_TSV = SKILL_ROOT / "data" / "function_index.tsv"
DEFAULT_CODEGEN_ROOT = SKILL_ROOT / "references" / "codegen"
REQUIRED_COLUMNS = (
    "name",
    "scope",
    "module",
    "signature",
    "page",
    "anchor",
    "tags",
    "summary",
)
OPTIONAL_COLUMNS = (
    "kind",
    "binding",
    "visibility",
    "owner",
    "qualified_name",
)
SEARCH_FIELD_WEIGHTS = (
    ("name", 120),
    ("qualified_name", 120),
    ("signature", 90),
    ("tags", 70),
    ("summary", 50),
    ("module", 30),
    ("scope", 30),
    ("owner", 25),
    ("kind", 20),
    ("binding", 20),
    ("visibility", 20),
)
# Complete coverage in curated semantic text must outrank incidental short
# aliases in composite identifiers, such as "index" and "max".
SEMANTIC_COVERAGE_BONUSES = (
    ("tags", 240),
    ("summary", 200),
)

HELP_EPILOG = """\
检索分两步，--kw 的摘要不能直接作为 API 事实：

  1. 先按关键词取候选（只有摘要表格，不含条目正文）
     lookup.py --kw 数组 去重
  2. 再按候选里的 qualified_name 取回条目正文
     lookup.py --name arrDropDuplicate

已知确切名称时可以直接用 --name，跳过第 1 步。
只查询一个 API scope 时使用 --scope，例如 --scope builtin 或 --scope dotnet。

退出码：
  0  取回成功；--name 无匹配也是 0（打印提示，不算错误）
  1  function_index.tsv 缺失、格式错误，或候选指向的条目正文找不到
  2  参数不合法（缺少动作、空值、--limit 小于 1、使用短选项或缩写）
"""


def non_empty(value):
    if not value.strip():
        raise argparse.ArgumentTypeError("must not be empty")
    return value


def load_rows(tsv_path):
    lines = tsv_path.read_text(encoding="utf-8").splitlines()
    if not lines:
        return []
    header = lines[0].split("\t")
    missing = [column for column in REQUIRED_COLUMNS if column not in header]
    if missing:
        raise ValueError(f"missing required columns: {', '.join(missing)}")
    if len(header) != len(set(header)):
        raise ValueError("duplicate column names")
    rows = []
    for line_number, line in enumerate(lines[1:], start=2):
        if not line.strip():
            continue
        values = line.split("\t")
        if len(values) != len(header):
            raise ValueError(
                f"line {line_number} has {len(values)} columns; "
                f"expected {len(header)}"
            )
        row = dict(zip(header, values))
        for column in OPTIONAL_COLUMNS:
            row.setdefault(column, "")
        rows.append(row)
    return rows


def normalize(value):
    return unicodedata.normalize("NFKC", value).casefold().strip()


def field_match_score(value, variant, weight):
    normalized = normalize(value)
    if not normalized or not variant:
        return 0
    if normalized == variant:
        return weight + 20
    if variant in normalized:
        return weight
    return 0


def term_score(row, term):
    best = 0
    for field, weight in SEARCH_FIELD_WEIGHTS:
        score = field_match_score(row.get(field, ""), term, weight)
        if score:
            best = max(best, score)
    return best


def field_covers_terms(row, field, terms):
    value = normalize(row.get(field, ""))
    return bool(value) and all(term in value for term in terms)


def keyword_sort_key(row):
    return (
        normalize(row.get("qualified_name", "") or row.get("name", "")),
        normalize(row.get("signature", "")),
        normalize(row.get("scope", "")),
        row.get("page", ""),
        row.get("anchor", ""),
    )


def search_exact(rows, name):
    key = name.casefold()
    return [
        row
        for row in rows
        if key
        in {
            row.get("name", "").casefold(),
            row.get("qualified_name", "").casefold(),
        }
    ]


def search_keyword(rows, terms):
    normalized_terms = [normalize(term) for term in terms]
    ranked = []
    for row in rows:
        scores = [term_score(row, term) for term in normalized_terms]
        if scores and all(scores):
            coverage_bonus = sum(
                bonus
                for field, bonus in SEMANTIC_COVERAGE_BONUSES
                if field_covers_terms(row, field, normalized_terms)
            )
            ranked.append((sum(scores) + coverage_bonus, row))
    ranked.sort(key=lambda item: (-item[0], *keyword_sort_key(item[1])))
    return [row for _, row in ranked]


def slug(text):
    return re.sub(r"[^a-z0-9_]", "", text.casefold())


def fence_flags(lines):
    flags = []
    in_fence = False
    marker = ""
    for line in lines:
        stripped = line.lstrip()
        if not in_fence and FENCE_RE.match(line):
            marker = stripped[:3]
            flags.append(True)
            in_fence = True
            continue
        flags.append(in_fence)
        if in_fence and stripped.startswith(marker):
            in_fence = False
            marker = ""
    return flags


def top_level_header_end(lines, start, flags):
    for index in range(start + 1, len(lines)):
        if flags[index]:
            continue
        if HEADING_RE.match(lines[index]):
            return index
    return len(lines)


def declaration_type(lines, start, end, flags):
    for index in range(start + 1, end):
        if flags[index]:
            continue
        stripped = lines[index].strip()
        if not stripped:
            continue
        match = DECLARATION_RE.fullmatch(stripped)
        return match.group(1).strip().casefold() if match else ""
    return ""


def markdown_heading(
    lines, index, root_kind, unit_class_open, flags
):
    """Return level, visible title, signature, and anchor base for one API."""
    bare = BARE_ENTRY_RE.match(lines[index])
    if not bare:
        return None
    level = len(bare.group(1))
    signature = bare.group(2)
    end = top_level_header_end(lines, index, flags)
    declaration = declaration_type(lines, index, end, flags)
    if declaration == "static function":
        return None
    if root_kind == "class":
        if level != 3 or declaration not in CLASS_MEMBER_LABELS:
            return None
    elif root_kind == "unit":
        if level == 3 and declaration not in UNIT_DIRECT_LABELS:
            return None
        if level == 4 and (
            not unit_class_open or declaration not in CLASS_MEMBER_LABELS
        ):
            return None
        if level not in {3, 4}:
            return None
    else:
        return None
    return level, signature, signature, slug(signature)


def iter_markdown_api_headings(lines):
    flags = fence_flags(lines)
    root_kind = ""
    unit_class_open = False
    for index, line in enumerate(lines):
        if flags[index]:
            continue
        if PLAIN_H2_RE.match(line):
            root_kind = ""
            unit_class_open = False
            top_level = TOP_LEVEL_RE.match(line)
            if not top_level:
                continue
            signature = top_level.group(1)
            end = top_level_header_end(lines, index, flags)
            root_kind = declaration_type(lines, index, end, flags)
            if root_kind:
                yield index, (
                    2,
                    signature,
                    signature,
                    slug(signature.split("(", 1)[0]),
                )
            continue
        if not root_kind:
            continue
        if root_kind == "unit" and H3_RE.match(line):
            unit_class_open = False
        bare = BARE_ENTRY_RE.match(line)
        if root_kind == "unit" and bare and len(bare.group(1)) == 3:
            end = top_level_header_end(lines, index, flags)
            unit_class_open = (
                declaration_type(lines, index, end, flags) == "class"
            )
        heading = markdown_heading(
            lines, index, root_kind, unit_class_open, flags
        )
        if heading:
            yield index, heading


def slice_entry(codegen_root, page, signature, anchor):
    md = codegen_root / page
    if not md.is_file():
        return ""
    lines = md.read_text(encoding="utf-8").splitlines()
    start = None
    seen_anchors = {}
    for idx, heading in iter_markdown_api_headings(lines):
        level, _, entry_signature, base_anchor = heading
        occurrence = seen_anchors.get(base_anchor, 0)
        seen_anchors[base_anchor] = occurrence + 1
        entry_anchor = base_anchor if occurrence == 0 else f"{base_anchor}-{occurrence}"
        if entry_anchor == anchor and entry_signature == signature:
            start = idx
            start_level = level
            break
    if start is None:
        return ""

    end = len(lines)
    flags = fence_flags(lines)
    for idx in range(start + 1, len(lines)):
        if flags[idx]:
            continue
        heading_match = HEADING_RE.match(lines[idx])
        if heading_match and len(heading_match.group(1)) <= start_level:
            end = idx
            break
    block = lines[start:end]
    while block and not block[-1].strip():
        block.pop()
    return "\n".join(block)


def declaration_term(row):
    kind = row.get("kind", "") or "function"
    binding = row.get("binding", "")
    mapped = {
        ("method", "instance"): "function",
        ("method", "class"): "class function",
        ("field", "static"): "static field",
        ("constant", "static"): "static const",
    }.get((kind, binding))
    if mapped:
        return mapped
    return {
        "constant": "const",
        "variable": "var",
    }.get(kind, kind)


def format_row(row):
    return "\t".join(
        [
            row.get("qualified_name", "") or row.get("name", ""),
            declaration_term(row),
            row.get("signature", ""),
            f"{row.get('page', '')}#{row.get('anchor', '')}",
            row.get("summary", ""),
        ]
    )


def codegen_root_for_tsv(tsv_path):
    if tsv_path.parent.name == "data":
        candidate = tsv_path.parent.parent / "references" / "codegen"
        if candidate.is_dir():
            return candidate
    if tsv_path.parent.name == "codegen":
        return tsv_path.parent
    candidate = tsv_path.parent / "references" / "codegen"
    if candidate.is_dir():
        return candidate
    return DEFAULT_CODEGEN_ROOT


def main(argv=None):
    if hasattr(sys.stdout, "reconfigure"):
        sys.stdout.reconfigure(encoding="utf-8")
    parser = argparse.ArgumentParser(
        description="检索 TSL API 参考数据，取回 API 的签名、参数与返回值事实。",
        epilog=HELP_EPILOG,
        formatter_class=argparse.RawDescriptionHelpFormatter,
        # 只接受完整拼写的长选项：不提供 -h 短选项，也不接受 --na / --li 这类
        # 缩写。缩写打错时会静默命中另一个选项并以 rc=0 返回，看不出写错了。
        add_help=False,
        allow_abbrev=False,
    )
    parser.add_argument(
        "--help",
        action="help",
        help="显示本帮助并退出（不提供 -h 短选项）",
    )
    group = parser.add_argument_group("动作（必选其一）").add_mutually_exclusive_group(
        required=True
    )
    group.add_argument(
        "--name",
        type=non_empty,
        help="按 API 名称精确取回条目正文；同时匹配简单名称与 qualified_name，"
        "大小写不敏感。简单成员名会返回所有 owner 下的同名 API，"
        "用完整限定名（如 DemoUnit.Document.Save）缩小到指定 class/unit。"
        "这是唯一的事实来源",
    )
    group.add_argument(
        "--kw",
        nargs="+",
        type=non_empty,
        help="按关键词检索候选清单：多个查询词是 AND 关系；"
        "逐词在 name、signature、tags、summary、module、scope、kind、binding、"
        "visibility、owner 和 qualified_name 中做字面子串匹配，按字段加权并稳定排序。"
        "同义词由索引的 tags 字段提供。"
        "大小写不敏感，只返回摘要表格，不含条目正文",
    )
    parser.add_argument(
        "--tsv",
        metavar="PATH",
        help="显式指定 function_index.tsv；默认只使用本 skill 内置的 "
        "data/function_index.tsv，不从工作目录回退查找旧索引",
    )
    parser.add_argument(
        "--scope",
        type=non_empty,
        metavar="SCOPE",
        help="只查询指定 scope，大小写不敏感；作用于 --name 和 --kw。"
        "内置索引当前提供 builtin 与 dotnet",
    )
    parser.add_argument(
        "--limit",
        type=int,
        default=50,
        metavar="N",
        help="--kw 输出的候选条数上限，取值 >= 1（默认 %(default)s）；"
        "--name 取回正文时不受该上限影响",
    )
    args = parser.parse_args(argv)
    if args.limit < 1:
        parser.error("--limit must be >= 1")

    tsv_path = Path(args.tsv) if args.tsv else DEFAULT_TSV
    if not tsv_path.is_file():
        print(
            "ERROR: function_index.tsv not found; reinstall tsl-api-reference "
            "or pass --tsv PATH",
            file=sys.stderr,
        )
        return 1

    try:
        rows = load_rows(tsv_path)
    except (OSError, UnicodeError, ValueError) as error:
        print(f"ERROR: failed to load {tsv_path}: {error}", file=sys.stderr)
        return 1
    if not rows:
        print(
            f"ERROR: {tsv_path} has no entries; reinstall tsl-api-reference "
            "or pass --tsv PATH",
            file=sys.stderr,
        )
        return 1
    if args.scope is not None:
        requested_scope = normalize(args.scope)
        available_scopes = sorted(
            {row["scope"] for row in rows if row.get("scope")},
            key=normalize,
        )
        if requested_scope not in {normalize(scope) for scope in available_scopes}:
            print(
                f"ERROR: unknown scope {args.scope!r}; available scopes: "
                f"{', '.join(available_scopes)}",
                file=sys.stderr,
            )
            return 2
        rows = [row for row in rows if normalize(row["scope"]) == requested_scope]
    codegen_root = codegen_root_for_tsv(tsv_path)

    if args.name is not None:
        matches = search_exact(rows, args.name)
        if not matches:
            print(f"No TSL API named '{args.name}'. Try: --kw <中文关键词>")
            return 0
        entries = []
        for row in matches:
            body = slice_entry(
                codegen_root, row["page"], row["signature"], row["anchor"]
            )
            if not body:
                print(
                    f"ERROR: entry body not found: "
                    f"{row['page']}#{row['anchor']} ({row['signature']})",
                    file=sys.stderr,
                )
                return 1
            entries.append((row, body))
        for row, body in entries:
            print(body)
            print(
                f"\n<!-- {row['scope']}/{row['module']} · "
                f"{row['page']}#{row['anchor']} -->\n"
            )
        return 0

    matches = search_keyword(rows, args.kw)
    print(f"# {len(matches)} matches for: {' '.join(args.kw)}")
    print("qualified_name\tdeclaration\tsignature\tpage#anchor\tsummary")
    for row in matches[: args.limit]:
        print(format_row(row))
    if len(matches) > args.limit:
        print(f"... {len(matches) - args.limit} more; refine keywords or raise --limit")
    if not matches:
        print("No matching API candidates; do not infer an API name.")
    return 0


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