G: G4 Drift guard and docs commit the spec and fail tests on drift

This commit is contained in:
ari committed 2026-10-20 15:54:13 -04:00
1 parent 869b6818e9
commit 34a1e1644c
5 files changed
+1986

No files matched your search

+6
View File
@@ -37,3 +37,9 @@ Reuse existing DTOs, do not duplicate types for the doc. Read-only, no secrets i
- 2026-10-20: **G3 Serving and CLI.** `document(peers)` now returns a cached `Arc<OpenApi>` (one `OnceLock` per mode; generation walks every DTO and the whole tool router, and the result cannot change while the process runs), with `build`/`to_pretty_json` behind it so one function is shared by every consumer. `GET /api/v1/openapi.json` is mounted in `api::router`, i.e. under `/api/v1` and therefore behind the existing auth layer; no new public route, no change to `server::build_router` or `/healthz`. It serves the mode of the running instance (`state.peers.is_some()`), so a peer-less instance advertises no peer paths. New `slinuxm openapi [--peers]` (`src/cli.rs`, `Command::Openapi`) prints the pretty document; `main` returns before `Config::load`, so it needs no config file, no token file and no socket and cannot start a server or bind a port. `--print-config` still wins if combined. The `peers::cli` import in `main.rs` is now aliased to `peer_cli` because `cli` is the new module.
Tests: `render_is_valid_json_for_both_modes`, `generation_is_deterministic` (bytes, not just values, because the committed file is compared) in the unit tests; `openapi_route_is_authenticated_and_serves_the_document` (401 without a token, 200 with one, body equals the generated peers-on document, `application/json`) and `cli_prints_the_same_document_offline` (real binary, `--config /nonexistent/...`, both modes, output equals the generated document) in `tests/openapi.rs`.
- 2026-10-20: **G4 Drift guard and docs.** `docs/openapi.json` is committed (peers on, pretty-printed by `slinuxm openapi --peers`, 15 paths and 10 tools). `tests/openapi.rs` now holds the guards: `committed_spec_matches_the_code` compares the file byte for byte with `cli::render(true)` and prints the regeneration command (`cargo run -- openapi --peers > docs/openapi.json`) on failure; `every_router_route_is_documented` scans every `.route(...)` literal in `src/api/**` and `src/server.rs` plus the `/mcp` mount and requires each path in the document (verified by adding a throwaway route: the test failed with `/api/v1/ping/extra is routed but missing from the OpenAPI document`); `every_documented_path_is_routed` sends one request per documented path through the assembled router and fails if it hits the fallback's `no such route`; `mcp_tools_match_the_tool_router` requires every tool of the router in `x-mcp-tools` with the same description and input schema (a new or gated-off tool changes the spec and then fails the staleness check); `every_operation_is_read_only` keeps every operation a GET except `POST /mcp`; `operation_ids_and_tags_are_declared` catches duplicate ids and undeclared tags. A crate version bump changes `info.version`, so it also needs the regeneration in the same commit; that is deliberate (the file is the artifact that is published).
Docs: `docs/api.md` gains a "Generated reference (OpenAPI)" section (what the file contains, `GET /api/v1/openapi.json`, `slinuxm openapi [--peers]`, regeneration, what the tests guard) and a route-table row; `README.md` gets a short paragraph in the REST section. `config.example.toml` needs nothing (no new key). `docs/README.md` does not list `docs/openapi.json` yet; it is outside this workstream's owned files, so the merger should add the row.
Verification: `cargo fmt --check`, `cargo clippy --all-targets -- -D warnings`, `cargo test` green (10 tests in `tests/openapi.rs`, 12 unit tests in `src/openapi.rs`/`src/cli.rs`); `cargo tree -i openssl` empty; the committed spec contains no token, token-file path or URL other than the documented default server. No nix build was run; no VM test is involved in this workstream.