risk-nexus/tools/register_index.py

#!/usr/bin/env python3
"""Generate REGISTER.md from the finding front-matter.

RISK-WP-0001-T05. The index is generated because a hand-maintained one
drifts and then lies. Edit the findings, re-run `make register`.
"""
from __future__ import annotations

import datetime as dt
import sys

import register_lib as lib

TODAY = dt.date.today()


def date(value) -> dt.date | None:
    if isinstance(value, dt.date):
        return value
    if isinstance(value, str) and value not in ("", "unset"):
        return dt.date.fromisoformat(value)
    return None


def review_cell(f: dict) -> str:
    due = date(f.get("review_by"))
    if due is None:
        return "—"
    late = (TODAY - due).days
    if late > 0:
        return f"**{due} (overdue {late}d)**"
    return str(due)


def sev_cell(f: dict) -> str:
    sev = f.get("severity", "unset")
    return f"**{sev}**" if sev in ("critical", "high") else sev


def esc_cell(f: dict) -> str:
    esc = f.get("escalation", "unset")
    if esc in ("none", "unset"):
        return esc
    trigger = f.get("escalation_trigger")
    status = f.get("escalation_status", "")
    tail = f" (t{trigger}{', ' + status if status else ''})" if trigger else ""
    return f"**{esc}**{tail}"


def render() -> str:
    fs = lib.findings()
    ns = lib.notes()
    open_fs = [f for f in fs if f.get("status") == "open"]

    out = [
        "# Register",
        "",
        f"Generated by `tools/register_index.py` from `findings/`. Do not edit by hand. Last built {TODAY}.",
        "",
        f"{len(open_fs)} open of {len(fs)} findings; {len(ns)} notes below the floor.",
        "",
        "## Findings",
        "",
        "| ID | Finding | System | Severity | Disclosure | Escalation | Fix owner | Status | Review by |",
        "| --- | --- | --- | --- | --- | --- | --- | --- | --- |",
    ]
    for f in fs:
        out.append(
            "| [{id}]({path}) | {title} | {system} | {sev} | {disc} | {esc} | {owner} | {status} | {review} |".format(
                id=f["id"],
                path=f["_path"].relative_to(lib.REPO),
                title=str(f.get("title", "")).strip('"'),
                system=f.get("system", "—"),
                sev=sev_cell(f),
                disc=f.get("disclosure", "unset"),
                esc=esc_cell(f),
                owner=f.get("fix_owner", "—"),
                status=f.get("status", "—"),
                review=review_cell(f),
            )
        )

    constraints = [f for f in fs if f.get("constraint")]
    if constraints:
        out += ["", "## Constraints", "",
                "Hazards created by acting in the wrong order. Each binds another finding's remediation.",
                "", "| From | Binds | Severity | Constraint |", "| --- | --- | --- | --- |"]
        for f in constraints:
            out.append("| {id} | {on} | **{sev}** | {text} |".format(
                id=f["id"], on=f.get("constraint_on", "—"),
                sev=f.get("constraint_severity", "—"), text=f["constraint"]))

    embargoed = [f for f in fs if f.get("disclosure") == "embargoed"]
    if embargoed:
        out += ["", "## Embargoes", "",
                "Held from publication with a stated condition. A hold with no moving condition is a stall.",
                "", "| Finding | Since | Lifts when | Re-decided |", "| --- | --- | --- | --- |"]
        for f in embargoed:
            out.append("| {id} | {since} | {cond} | {rev} |".format(
                id=f["id"], since=f.get("embargo_since", "—"),
                cond=f.get("embargo_condition", "—"), rev=f.get("embargo_review", "—")))

    if ns:
        out += ["", "## Notes (below the floor)", "",
                "Seen, deliberately not findings. Not graded, not reviewed, not published.",
                "", "| ID | Note | Why below the floor |", "| --- | --- | --- |"]
        for n in ns:
            out.append("| [{id}]({path}) | {title} | {why} |".format(
                id=n["id"], path=n["_path"].relative_to(lib.REPO),
                title=str(n.get("title", "")).strip('"'),
                why=str(n.get("floor_reason", "—")).strip('"')))

    out += ["", "## How to read this", "",
            "Severity is `docs/method/severity.md`; disclosure `docs/method/disclosure.md`;",
            "escalation `docs/method/escalation.md`; review dates `docs/method/review.md`.",
            "A constraint may be graded higher than the finding that carries it — read both.",
            ""]
    return "\n".join(out)


if __name__ == "__main__":
    text = render()
    target = lib.REPO / "REGISTER.md"
    if "--check" in sys.argv:
        current = target.read_text(encoding="utf-8") if target.exists() else ""
        if current != text:
            print("REGISTER.md is stale — run `make register`")
            raise SystemExit(1)
        print("REGISTER.md is current")
    else:
        target.write_text(text, encoding="utf-8")
        print(f"wrote {target.relative_to(lib.REPO)}")