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
92 lines
2.9 KiB
Python
Executable File
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()
|