go-docs-openapi-spec-drift
Drift found (GAP-002/GAP-003): the README referenced a --db CLI flag that main.go never registered (5 refs), the OpenAPI spec pointed at localhost:8472 while the server actually binds <ip-address>:9734, and the dashboard routes (/dashboard, /api/v1/dashboard/summary) were missing from the spec entirely. All fixes were docs-only (no .go changes), shipped as two commits.
Fix 1 — README: drop phantom --db, document RABBITHOLE_DB_PATH. The binary reads the DB path from the RABBITHOLE_DB_PATH environment variable, not a flag. All 5 stale refs (Usage synopsis, examples, config table ×2, troubleshooting) were removed/replaced:
-## Usage
- rabbithole [--db PATH] [--listen ADDR]
+## Usage
+ rabbithole [--listen ADDR]
+
+The SQLite database location is configured via the `RABBITHOLE_DB_PATH`
+environment variable (defaults to `./rabbithole.db`). Example:
+
+ RABBITHOLE_DB_PATH=/var/lib/rabbithole/data.db rabbithole
-## Configuration
-| Flag | Env | Default | Description |
-|-------------|----------|----------------|--------------------|
-| `--db` | (none) | `./rabbithole.db` | SQLite database | <- removed
-| `--listen` | `RABBITHOLE_LISTEN` | `<ip-address>:9734` | HTTP listen address |
+| Variable | Default | Description |
+|-----------------------|----------------------|-------------------------------------|
+| `RABBITHOLE_DB_PATH` | `./rabbithole.db` | SQLite database path |
+| `RABBITHOLE_LISTEN` | `<ip-address>:9734` | HTTP listen address |
Fix 2 — OpenAPI spec: correct server URL. localhost:8472 is wrong on both host and port; the router binds <ip-address>:9734 (and the env default is RABBITHOLE_LISTEN=<ip-address>:9734):
servers:
- - url: http://localhost:8472
+ - url: http://<ip-address>:9734
Fix 3 — OpenAPI spec: add dashboard routes + DashboardSummary schema, matching the real mux registrations:
paths:
/dashboard:
get:
summary: Render the dashboard HTML page
responses:
"200":
description: Dashboard page (text/html)
"503":
description: Summary data unavailable (DB not initialized)
/api/v1/dashboard/summary:
get:
summary: Dashboard summary metrics
responses:
"200":
description: Summary metrics
content:
application/json:
schema:
$ref: "#/components/schemas/DashboardSummary"
"500":
description: Internal error
components:
schemas:
DashboardSummary:
type: object
required: [total_events, active_pipelines]
properties:
total_events: { type: integer, format: int64 }
active_pipelines: { type: integer, format: int32 }
last_ingest_at: { type: string, format: date-time, nullable: true }
db_events_per_sec: { type: number, format: float }
Committed as two docs-only commits (docs: remove nonexistent --db flag, document RABBITHOLE_DB_PATH and docs(openapi): fix server url and add dashboard routes); git diff HEAD^..HEAD -- . ':!*.md' ':!*.yaml' was empty in both.
Verification performed on each commit:
1. **Flag refs:** `grep -rn -- "--db" README.md` → 5 matches before, 0 after; `grep -rn -- "--db" *.go cmd/` → 0 matches (flag never existed, so no code change needed — docs-only is correct).
2. **Env var documented:** `grep -n RABBITHOLE_DB_PATH README.md` → present; cross-checked against `os.Getenv("RABBITHOLE_DB_PATH")` in source so the name/default match reality.
3. **Server URL:** `grep -n "url:" docs/openapi.yaml` → `http://<ip-address>:9734`; matches the bind address in the server bootstrap and the `RABBITHOLE_LISTEN` default (no `8472` anywhere: `grep -rn 8472 .` → empty).
4. **Routes present:** `grep -nE "/dashboard|/api/v1/dashboard/summary" docs/openapi.yaml` → present; cross-checked every `mux.Handle*` registration in `main.go`/routes — `/dashboard` and `/api/v1/dashboard/summary` are the only dashboard paths and both are now listed (no other unlisted routes remained).
5. **Spec validity & refs:** `yaml`/`openapi` parse succeeded (`go run`-level YAML unmarshal + ref resolution: `$ref: "#/components/schemas/DashboardSummary"` resolves to the new schema).
6. **Edge cases:** case/exact-flag-matching (`--DB`, `-db`, `-d`) — none existed either; README example blocks that embedded `--db` were rewritten wholesale rather than patched line-by-line to avoid leftover fragments; a 503/500 response documented for the summary endpoint since the schema is non-nullable on `total_events`/`active_pipelines`; confirmed the two commits are docs-only via `git show --stat`.
7. **Gates:** guard 4/4 (README flag-ref check, env-var doc check, spec URL check, route-coverage check) and judge PASS 3/3 for each of the two commits.{"model": "deepseek-v4-flash", "problem_class": "go-docs-openapi-spec-drift", "result": "passed", "tests": 10}