psxrecomp/tools/gen_tcp_commands.py

#!/usr/bin/env python3
"""Generate the complete TCP debug-command index in docs/TCP_COMMANDS.md.

WHY THIS EXISTS
---------------
docs/TCP_COMMANDS.md carried the instruction "update this file when you add a
handler". As of 2026-07-27 it described 47 commands while the two debug servers
registered 280 between them -- 17% coverage. A hand-maintained inventory of that
size does not stay correct, and a stale reference is worse than an absent one
because people trust it.

The curated table under "## Command inventory" is still hand-written and still
valuable: it carries parameters, prose, and the beetle/native split for the
commands people actually reach for. This script does NOT touch it. It regenerates
only the block between the AUTOGEN markers -- a complete index of every
registered command, flagging which ones the curated table already covers.

Usage:
    python tools/gen_tcp_commands.py            # rewrite the generated block
    python tools/gen_tcp_commands.py --check    # exit 1 if the block is stale

--check is what belongs in CI: it makes "the reference drifted" a build failure
instead of something discovered months later.
"""

from __future__ import annotations

import argparse
import re
import sys
from pathlib import Path

REPO = Path(__file__).resolve().parent.parent

NATIVE_SRC = REPO / "runtime" / "src" / "debug_server.c"
BEETLE_SRC = REPO / "runtime" / "src" / "beetle_debug_server.c"
DOC = REPO / "docs" / "TCP_COMMANDS.md"

BEGIN = "<!-- BEGIN AUTOGENERATED COMMAND INDEX -- edit tools/gen_tcp_commands.py, not this block -->"
END = "<!-- END AUTOGENERATED COMMAND INDEX -->"

# `{ "name", handler },` inside the table. Tolerates arbitrary whitespace.
ENTRY_RE = re.compile(r'\{\s*"([A-Za-z0-9_]+)"\s*,\s*[A-Za-z0-9_]+\s*\}')


def extract_table(path: Path, table_decl: str) -> list[str]:
    """Pull command names out of a `static const CmdEntry <table_decl>` array.

    Reads from the declaration to the closing `};` so unrelated brace-initialised
    literals elsewhere in these very large files cannot leak in.
    """
    if not path.exists():
        raise SystemExit(f"gen_tcp_commands: missing source file {path}")

    text = path.read_text(encoding="utf-8", errors="replace")
    start = text.find(table_decl)
    if start < 0:
        raise SystemExit(
            f"gen_tcp_commands: could not find '{table_decl}' in {path.name}. "
            "The command table was renamed or restructured; update this script "
            "rather than deleting the check."
        )
    end = text.find("};", start)
    if end < 0:
        raise SystemExit(f"gen_tcp_commands: unterminated table in {path.name}")

    names = ENTRY_RE.findall(text[start:end])
    if not names:
        raise SystemExit(f"gen_tcp_commands: parsed 0 commands from {path.name}")
    return names


def documented_in_curated_table(doc_text: str) -> set[str]:
    """Commands the hand-written parts of the doc already describe.

    Picks up markdown table rows (`| `name` | ...`) and `## `name`` headings.
    A row may name aliases -- "`ping` / `frame`", "`get_registers` (`regs`)" --
    so every backticked token on a matching line counts.
    """
    covered: set[str] = set()
    for line in doc_text.splitlines():
        stripped = line.strip()
        if stripped.startswith("|") and "`" in stripped:
            covered.update(re.findall(r"`([A-Za-z0-9_]+)`", stripped))
        elif stripped.startswith("#") and "`" in stripped:
            covered.update(re.findall(r"`([A-Za-z0-9_]+)`", stripped))
    return covered


def build_block(native: list[str], beetle: list[str], covered: set[str]) -> str:
    all_names = sorted(set(native) | set(beetle))
    nset, bset = set(native), set(beetle)

    documented = [n for n in all_names if n in covered]
    undocumented = [n for n in all_names if n not in covered]

    lines: list[str] = [BEGIN, ""]
    lines.append("## Complete command index (generated)")
    lines.append("")
    lines.append(
        f"**{len(all_names)} commands registered** — {len(native)} on the native "
        f"server (`runtime/src/debug_server.c`), {len(beetle)} on the Beetle "
        f"server (`runtime/src/beetle_debug_server.c`)."
    )
    lines.append("")
    lines.append(
        f"{len(documented)} of {len(all_names)} have prose above; "
        f"**{len(undocumented)} are index-only**. An index-only command still "
        "works — it just has no description here yet. Send it `{\"cmd\":\"<name>\"}` "
        "and read the reply, or find its `handle_*` function in the server source."
    )
    lines.append("")
    lines.append(
        "Regenerate with `python tools/gen_tcp_commands.py`; "
        "`--check` fails if this block has drifted from the code."
    )
    lines.append("")
    lines.append("| Command | Native | Beetle | Described above |")
    lines.append("|---|:--:|:--:|:--:|")
    for name in all_names:
        lines.append(
            f"| `{name}` "
            f"| {'✓' if name in nset else ''} "
            f"| {'✓' if name in bset else ''} "
            f"| {'✓' if name in covered else ''} |"
        )
    lines.append("")
    lines.append(END)
    return "\n".join(lines)


def main() -> int:
    ap = argparse.ArgumentParser(description=__doc__)
    ap.add_argument(
        "--check",
        action="store_true",
        help="exit 1 if the generated block is out of date (for CI)",
    )
    args = ap.parse_args()

    native = extract_table(NATIVE_SRC, "s_commands[]")
    beetle = extract_table(BEETLE_SRC, "CMDS[]")

    doc_text = DOC.read_text(encoding="utf-8")

    # Coverage is judged against the hand-written parts only, so a previously
    # generated block can never count itself as documentation.
    curated = doc_text
    if BEGIN in curated:
        head, _, rest = curated.partition(BEGIN)
        _, _, tail = rest.partition(END)
        curated = head + tail

    block = build_block(native, beetle, documented_in_curated_table(curated))

    if BEGIN in doc_text and END in doc_text:
        head, _, rest = doc_text.partition(BEGIN)
        _, _, tail = rest.partition(END)
        updated = head + block + tail
    else:
        updated = doc_text.rstrip("\n") + "\n\n" + block + "\n"

    if args.check:
        if updated != doc_text:
            print(
                "docs/TCP_COMMANDS.md is out of date with the debug-server command "
                "tables.\nRun: python tools/gen_tcp_commands.py",
                file=sys.stderr,
            )
            return 1
        print(f"docs/TCP_COMMANDS.md is current ({len(set(native) | set(beetle))} commands).")
        return 0

    if updated == doc_text:
        print(f"docs/TCP_COMMANDS.md already current ({len(set(native) | set(beetle))} commands).")
        return 0

    # newline="" writes the LF endings assembled above verbatim. The default
    # translates every newline to os.linesep, so on Windows a regeneration
    # rewrote all 585 lines to CRLF and turned a few-line index update into a
    # whole-file diff.
    with open(DOC, "w", encoding="utf-8", newline="") as fh:
        fh.write(updated)
    print(f"docs/TCP_COMMANDS.md updated ({len(set(native) | set(beetle))} commands).")
    return 0


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