Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
feat(release): attach a labelled openapi.json to every GitHub release (#3948)
Raghav Chamadiyaca5263f66034
diff --git a/.github/workflows/publish.yml b/.github/workflows/publish.ymlindex 7985cdb75..82a50aa1b 100644--- a/.github/workflows/publish.yml+++ b/.github/workflows/publish.yml@@ -85,6 +85,34 @@ jobs:name: distpath: dist/+ # ---------------------------------------------------------------------------+ # Export the server's OpenAPI document, labelled stable or internal per route+ # ---------------------------------------------------------------------------+ build-openapi:+ name: Export OpenAPI document+ runs-on: ubuntu-latest++ steps:+ - uses: actions/checkout@v4++ - name: Install uv+ uses: astral-sh/setup-uv@v3+ with:+ version: "latest"+ enable-cache: true++ - name: Install dependencies+ run: uv sync --all-packages++ - name: Export openapi.json+ run: uv run python scripts/export_openapi.py --out openapi.json++ - name: Upload OpenAPI artifact+ uses: actions/upload-artifact@v4+ with:+ name: openapi+ path: openapi.json+# ---------------------------------------------------------------------------# Create GitHub release with web UI tarball# ---------------------------------------------------------------------------@@ -114,6 +142,27 @@ jobs:dist/*generate_release_notes: true+ # ---------------------------------------------------------------------------+ # Attach openapi.json after the release exists, so a failed export never+ # holds back the web tarball that `repowise serve` downloads+ # ---------------------------------------------------------------------------+ attach-openapi:+ name: Attach OpenAPI document+ needs: [release, build-openapi]+ runs-on: ubuntu-latest++ steps:+ - name: Download OpenAPI document+ uses: actions/download-artifact@v4+ with:+ name: openapi+ path: ./openapi/++ - name: Attach to release+ uses: softprops/action-gh-release@v2+ with:+ files: openapi/openapi.json+# ---------------------------------------------------------------------------# Publish to PyPI# ---------------------------------------------------------------------------diff --git a/docs/reference/API_REFERENCE.md b/docs/reference/API_REFERENCE.mdindex 1fa7093b9..c81caa287 100644--- a/docs/reference/API_REFERENCE.md+++ b/docs/reference/API_REFERENCE.md@@ -11,6 +11,12 @@ how authentication behaves, the shape of an error, how the two SSE streams aresequenced, and the conventions several routes share. Start at `/docs` for aspecific endpoint; come back here for the things a schema cannot state.+Each GitHub release also carries the same document as an `openapi.json` asset+(`https://github.com/repowise-dev/repowise/releases/latest/download/openapi.json`).+Every operation in it has `x-repowise-stability`: `stable` routes are the+integration surface, and breaking changes to them are named in the changelog;+`internal` routes serve the bundled dashboard and can change in any release.+Nothing in this document duplicates a route table on purpose. Where a factbelow is derived from code, the file is named so the claim can be re-checked.The default API address is `http://127.0.0.1:7337` (`docs/reference/CLI_REFERENCE.md`).diff --git a/scripts/export_openapi.py b/scripts/export_openapi.pynew file mode 100644index 000000000..7c13a1620--- /dev/null+++ b/scripts/export_openapi.py@@ -0,0 +1,117 @@+"""Export the server's OpenAPI document for a release, with a stability label per route.++The release workflow attaches the output to each GitHub release as+``openapi.json``, so anyone building on ``repowise serve`` can fetch one file+that matches the version they run.++Every operation gets ``x-repowise-stability``:++- ``stable``: an integration surface. Breaking changes are named in the+ changelog.+- ``internal``: a payload shaped for the bundled dashboard. It can change in+ any release without notice.++The label comes from the operation's first tag. A tag missing from both sets+fails the export, so a new router has to be classified before it ships.++Run ``python scripts/export_openapi.py --out openapi.json``.+"""++from __future__ import annotations++import argparse+import json+import pathlib+import sys+from typing import Any++STABLE_TAGS = frozenset(+ {+ "blast-radius",+ "c4",+ "changes",+ "chat",+ "code-health",+ "coupling",+ "dead-code",+ "decisions",+ "doc-drift",+ "events",+ "external-systems",+ "git",+ "graph",+ "health",+ "jobs",+ "pages",+ "refactoring",+ "repos",+ "search",+ "security",+ "symbols",+ "webhooks",+ "workspace",+ }+)++INTERNAL_TAGS = frozenset(+ {+ "actions",+ "areas",+ "claude-md",+ "costs",+ "episodes",+ "feedback",+ "files",+ "history",+ "knowledge-map",+ "mcp",+ "meta",+ "modules",+ "overview",+ "owners",+ "platform",+ "providers",+ "stats",+ }+)++_HTTP_METHODS = frozenset({"get", "put", "post", "delete", "patch", "options", "head", "trace"})+++def label(spec: dict[str, Any]) -> dict[str, Any]:+ """Stamp each operation with its stability, in place. Raise on an unclassified tag."""+ unclassified: set[str] = set()+ for item in spec.get("paths", {}).values():+ for method, op in item.items():+ if method not in _HTTP_METHODS:+ continue+ tags = op.get("tags") or []+ tag = tags[0] if tags else "(untagged)"+ if tag in STABLE_TAGS:+ op["x-repowise-stability"] = "stable"+ elif tag in INTERNAL_TAGS:+ op["x-repowise-stability"] = "internal"+ else:+ unclassified.add(tag)+ if unclassified:+ raise ValueError(+ "Classify these OpenAPI tags in scripts/export_openapi.py: " + ", ".join(sorted(unclassified))+ )+ return spec+++def main(argv: list[str] | None = None) -> int:+ parser = argparse.ArgumentParser(description=__doc__)+ parser.add_argument("--out", type=pathlib.Path, default=pathlib.Path("openapi.json"))+ args = parser.parse_args(argv)++ from repowise.server.app import create_app++ spec = label(create_app().openapi())+ args.out.write_text(json.dumps(spec, indent=2, sort_keys=False) + "\n", encoding="utf-8")+ print(f"wrote {args.out} ({len(spec.get('paths', {}))} paths)", file=sys.stderr)+ return 0+++if __name__ == "__main__":+ raise SystemExit(main())diff --git a/tests/unit/server/test_export_openapi.py b/tests/unit/server/test_export_openapi.pynew file mode 100644index 000000000..31844568e--- /dev/null+++ b/tests/unit/server/test_export_openapi.py@@ -0,0 +1,45 @@+"""Every route in the released OpenAPI document carries a stability label."""++from __future__ import annotations++import importlib.util+import pathlib++import pytest++_SCRIPT = pathlib.Path(__file__).resolve().parents[3] / "scripts/export_openapi.py"+++def _exporter():+ spec = importlib.util.spec_from_file_location("_export_openapi", _SCRIPT)+ assert spec and spec.loader+ module = importlib.util.module_from_spec(spec)+ spec.loader.exec_module(module)+ return module+++def test_every_live_route_is_labelled() -> None:+ from repowise.server.app import create_app++ exporter = _exporter()+ spec = exporter.label(create_app().openapi())++ labels = {+ op["x-repowise-stability"]+ for item in spec["paths"].values()+ for method, op in item.items()+ if method in exporter._HTTP_METHODS+ }+ assert labels == {"stable", "internal"}+++def test_a_tag_in_both_sets_is_impossible() -> None:+ exporter = _exporter()+ assert not exporter.STABLE_TAGS & exporter.INTERNAL_TAGS+++def test_an_unclassified_tag_fails_the_export() -> None:+ exporter = _exporter()+ spec = {"paths": {"/x": {"get": {"tags": ["brand-new"]}}}}+ with pytest.raises(ValueError, match="brand-new"):+ exporter.label(spec)