Files
ersatztv/scripts/generate-endpoint-index.py
T
timothy 18b2a46beb feat(780): commit a ruff config and enforce it in CI
Python lint here was a property of the operator's laptop, not of the repo: the
global instructions say to run `ruff check`/`ruff format --check`/`pyright`, no
workflow or hook ran any of them, and with no committed config ruff fell back to
whichever `~/.config/ruff/ruff.toml` the machine happened to have. A second
machine lints this repo differently, or not at all — Family E in
docs/defect-shapes-773.md, in our own toolchain.

Option 1 from the issue:

- `ruff.toml` at the root (the operator's global settings, pinned here — that is
  what the tree was de-facto written against, so adopting it cost a mechanical
  reformat rather than a rewrite).
- The `script-tests` job installs a PINNED `ruff==0.12.11` and runs
  `ruff check .` + `ruff format --check .` before pytest, so a style red arrives
  in seconds instead of after the four-minute suite. The pin is the second half
  of the fix: an unpinned install re-introduces the same divergence one layer up.
  Renamed the job to `Script lint and tests (ruff + pytest)` so a lint red is not
  triaged under a name that says pytest.
- Tree made clean: 72 errors and 20 files needing reformatting. Everything fixed
  except two config-level exemptions with reasons in the config (`S101`, `S105`
  under `scripts/tests/**` — the stub credentials that fire `S105` have no true
  positive anywhere in the tree) and two per-site `# noqa`s that carry their
  reason inline.

`pyright` stays ungated: its only findings are `reportMissingImports` for
`etv_client` in scripts/scripted-schedules/entrypoint.py, resolvable only in that
script's deploy environment, and gating it would put a node toolchain on the
git-only `small` lane to find nothing.

Population is what `ruff check .` discovers from the root, so a new `.py`
anywhere is covered without the job enumerating anything.

Docs: new record `ci.python-lint-ruff-config-committed`, cross-ref from
`ci.script-tests-job`, `docs/ci-cd.md` script-tests section, and
`docs/defect-shapes-773.md` §5.2 marked resolved with the measured numbers.

Refs: #780
Decisions-Edit: yes
2026-08-21 22:47:22 +02:00

92 lines
2.9 KiB
Python
Executable File

#!/usr/bin/env python3
"""Generate docs/endpoint-index.md from the OpenAPI spec.
Do not edit docs/endpoint-index.md by hand -- it is generated by this script
from ErsatzTV/wwwroot/openapi/v1.json. Regenerated automatically as part of
scripts/update-openapi.sh.
"""
import json
from pathlib import Path
HTTP_METHODS = ("get", "put", "post", "delete", "options", "head", "patch", "trace")
REPO_ROOT = Path(__file__).resolve().parent.parent
SPEC_PATH = REPO_ROOT / "ErsatzTV" / "wwwroot" / "openapi" / "v1.json"
OUTPUT_PATH = REPO_ROOT / "docs" / "endpoint-index.md"
UNTAGGED = "(untagged)"
def load_operations(spec: dict) -> list[dict]:
"""Flatten the OpenAPI paths object into a list of per-operation records."""
operations = []
for path, path_item in spec.get("paths", {}).items():
for method, operation in path_item.items():
if method.lower() not in HTTP_METHODS:
continue
operations.append(
{
"path": path,
"method": method.upper(),
"operationId": operation.get("operationId", ""),
"summary": operation.get("summary", "") or "",
"tags": operation.get("tags") or [UNTAGGED],
}
)
return operations
def group_by_tag(operations: list[dict]) -> dict[str, list[dict]]:
grouped: dict[str, list[dict]] = {}
for op in operations:
for tag in op["tags"]:
grouped.setdefault(tag, []).append(op)
return grouped
def render(spec: dict) -> str:
operations = load_operations(spec)
grouped = group_by_tag(operations)
tags = sorted(t for t in grouped if t != UNTAGGED)
if UNTAGGED in grouped:
tags.append(UNTAGGED)
lines = []
lines.append("# API endpoint index")
lines.append("")
lines.append(
"*Generated by `scripts/generate-endpoint-index.py` from "
"`ErsatzTV/wwwroot/openapi/v1.json`. Do not edit by hand -- regenerated by "
"`scripts/update-openapi.sh`.*"
)
lines.append("")
lines.append(f"{len(spec.get('paths', {}))} endpoints, {len(operations)} operations.")
lines.append("")
for tag in tags:
lines.append(f"## {tag}")
lines.append("")
lines.append("| Method | Path | Operation | Summary |")
lines.append("|---|---|---|---|")
for op in sorted(grouped[tag], key=lambda o: (o["path"], o["method"])):
lines.append(f"| {op['method']} | `{op['path']}` | {op['operationId']} | {op['summary']} |")
lines.append("")
return "\n".join(lines).rstrip("\n") + "\n"
def main() -> None:
spec = json.loads(SPEC_PATH.read_text())
OUTPUT_PATH.write_text(render(spec))
operations = load_operations(spec)
print(
f"Wrote {OUTPUT_PATH.relative_to(REPO_ROOT)}: "
f"{len(spec.get('paths', {}))} endpoints, {len(operations)} operations."
)
if __name__ == "__main__":
main()