doxy_report.py

Go to the documentation of this file.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""The audit-only report: docs/DOXYGEN_GAPS.csv and docs/DOXYGEN_GAPS.md.
 
Separate from the gate because it answers a different question.  The gate asks
"is the tree clean" and exits non-zero; this asks "where is the remaining work
and how much of it is there", writes two artefacts, and always exits 0.
 
It walks the same files the gate does, through
:func:`doxy_scope.function_files`, so the report can never describe a
different set of files than the gate enforces over -- the two used to carry
the same walk inline, twice.  That accessor also carries the shared vacuity
floor: "always exits 0" is about findings, not about infrastructure, and a
report sized from a collapsed walk would understate the remaining work as
zero.
"""
 
from __future__ import annotations
 
from collections import Counter
 
from doxy_functions import audit_file
from doxy_scope import MODULE_PATH_MIN_DEPTH, function_files, repo_root
 
# Maximum number of lines in the generated Markdown report (keep pre-commit
# output brief).
MD_REPORT_LINE_CAP = 200
 
#: Worst-offender table sizes in the Markdown report.
TOP_MODULES = 10
TOP_FILES = 30
 
 
def collect_rows() -> list:
    """Audit every in-scope file, sorted by path then line."""
    rows = []
    for path in function_files():
        rows.extend(audit_file(path))
    rows.sort(key=lambda r: (r[0], r[1]))
    return rows
 
 
def _write_csv(gap_rows: list) -> None:
    """Write the full row-per-function gap table."""
    csv_path = repo_root() / "docs" / "DOXYGEN_GAPS.csv"
    with csv_path.open("w", encoding="ascii") as f:
        f.write("source_file,line,function_name,missing_tags,severity\n")
        for src, line, name, missing, sev in gap_rows:
            f.write(f"{src},{line},{name},{';'.join(missing)},{sev}\n")
 
 
def _tag_frequency(gap_rows: list) -> Counter:
    """Count missing tags, collapsing per-instance spellings into their family.
 
    ``@param[buf]`` and ``@param[len]`` are two instances of one missing tag,
    and ``@pre(<2:1)`` records a count rather than a distinct tag; without the
    collapse the frequency table lists every parameter name in the tree.
    """
    counter: Counter = Counter()
    for r in gap_rows:
        for t in r[3]:
            if t.startswith("@param["):
                counter["@param"] += 1
            elif t.startswith("@pre"):
                counter["@pre"] += 1
            elif t.startswith("@post"):
                counter["@post"] += 1
            else:
                counter[t] += 1
    return counter
 
 
def _module_of(path: str) -> str:
    """Two-segment module label for a repo-relative path (e.g. "libs/ra8_hal")."""
    parts = path.split("/")
    if len(parts) >= MODULE_PATH_MIN_DEPTH:
        return f"{parts[0]}/{parts[1]}"
    return parts[0]
 
 
def _table(title: str, header: str, sep: str, rows: list[tuple[str, int]]) -> list[str]:
    """One Markdown section: a heading and a two-column count table.
 
    ``sep`` is passed rather than generated so the emitted report stays
    byte-identical to the committed docs/DOXYGEN_GAPS.md -- the dash widths
    are cosmetic to a renderer but a spurious diff to a reviewer.
    """
    out = [f"## {title}", "", header, sep]
    out.extend(f"| `{label}` | {count} |" for label, count in rows)
    out.append("")
    return out
 
 
def _render_markdown(rows: list, gap_rows: list) -> str:
    """Build the human-readable summary report."""
    total_funcs = len(rows)
    total_gaps = len(gap_rows)
    total_missing_tags = sum(len(r[3]) for r in gap_rows)
 
    lines = [
        "# Doxygen Documentation Gap Report",
        "",
        "Audit-only report generated by `scripts/checks/doxy_audit.py` against the",
        "Doxygen Documentation Requirements in `CLAUDE.md`. Scope: `libs/`,",
        "`port/` and all of `tools/` (excluding vendored and generated",
        "code).",
        "",
        "## Summary",
        "",
        f"- Total functions audited: {total_funcs}",
        f"- Functions with gaps: {total_gaps}",
        f"- Total missing-tag instances: {total_missing_tags}",
        "",
    ]
    lines += _table(
        "Most-frequently-missing tags",
        "| Tag | Count |",
        "|-----|-------|",
        _tag_frequency(gap_rows).most_common(),
    )
    lines += _table(
        f"Worst {TOP_MODULES} modules by gap count",
        "| Module | Functions with gaps |",
        "|--------|---------------------|",
        Counter(_module_of(r[0]) for r in gap_rows).most_common(TOP_MODULES),
    )
    lines += _table(
        f"Top {TOP_FILES} files by gap count",
        "| File | Functions with gaps |",
        "|------|---------------------|",
        Counter(r[0] for r in gap_rows).most_common(TOP_FILES),
    )
    lines += [
        "## Severity legend",
        "",
        "- `high`: missing `@brief` or any `@param[...]`",
        "- `medium`: missing `@return` / `@retval` / `@pre` / `@post`",
        "- `low`: only optional / informational tags missing (`@note`, `@since`, ...)",
        "",
        "See `docs/DOXYGEN_GAPS.csv` for the full row-by-row data.",
        "",
        "## Audit history",
        "",
        "| Date | Functions with gaps | Missing-tag instances |",
        "|------|---------------------|-----------------------|",
        "| 2026-05-02 (original)                 | 2557 | 20328 |",
        "| 2026-05-02 (refresh)                  | 663  | 4935  |",
        f"| 2026-05-02 (auditor false-pos fix)    | {total_gaps} | {total_missing_tags} |",
        "",
    ]
    # Cap the report so it stays browsable in a pre-commit log.
    return "\n".join(lines[:MD_REPORT_LINE_CAP])
 
 
def run_report() -> int:
    """Write both artefacts and print the headline counts. Always exits 0."""
    rows = collect_rows()
    gap_rows = [r for r in rows if r[3]]
 
    _write_csv(gap_rows)
    md_path = repo_root() / "docs" / "DOXYGEN_GAPS.md"
    md_path.write_text(_render_markdown(rows, gap_rows), encoding="ascii")
 
    total_missing_tags = sum(len(r[3]) for r in gap_rows)
    print(f"functions={len(rows)} gaps={len(gap_rows)} missing_tags={total_missing_tags}")
    return 0