feat(docs): drift gate — docs frontmatter validated against real routes
Every API doc that declares frontmatter (method/path/auth/area) is now checked by a unit test against three sources of truth: 1. Route registration: internal/router/*.go is parsed the way echo resolves it (group prefixes concatenate; scanner.go's parameterized groups seeded). Doc paths that no longer exist fail. (This is the check that would have caught the /api/api/admin/hash-conflicts split.) 2. Auth: frontmatter auth label must match the middleware chain (none|jwt|jwt+admin|device-token|optional-jwt). 3. Shapes: internal/docs/schema.go registry — example-request decoded with unknown fields DISALLOWED (typo guard), required-by-validate fields must appear (staleness guard), example-response top-level key set compared both directions against the marshaled handler type (or a RawMessage pin for hand-built map responses). Five collections docs are the pilots with real handler shapes; notable corrections they pin: update returns 201 (not 200), list excludes smart collections unless include_auto=true, rule priority is 1-10 higher-wins (docs claimed 1=highest), created_at is Go time.String() not RFC3339, hide_finished/show_up_next toggles documented. CollectionResponse hoisted out of GetCollections/GetBookCollections as CollectionSummary / BookCollectionSummary so the registry can pin real types. The gate fails on missing registry entries by design — that is the maintenance contract. Known pre-existing (not this commit): vet copy-lock warnings in media.go.
This commit is contained in:
John O'Keefe committed
1 parent
994e0f86c4
commit
cc893f758e
8 files changed
+824
-168
No files matched your search
@@ -0,0 +1,386 @@
|
||||
package docs
|
||||
|
||||
import (
|
||||
"bytes"
|
||||
"encoding/json"
|
||||
"os"
|
||||
"path/filepath"
|
||||
"reflect"
|
||||
"regexp"
|
||||
"strings"
|
||||
"testing"
|
||||
)
|
||||
|
||||
// The drift gate: every doc that declares an endpoint in frontmatter must
|
||||
// (1) match a real route registration, (2) match its middleware-derived auth
|
||||
// label, and (3) have request/response examples compatible with the schema
|
||||
// registry. Docs without frontmatter (overviews, contracts) are out of scope.
|
||||
//
|
||||
// Run verbose to see UNVERIFIED markers left by drafting passes:
|
||||
//
|
||||
// go test ./internal/docs/ -run TestDocsMatchRoutes -v
|
||||
|
||||
// ---------- route extraction ----------
|
||||
|
||||
type extractedRoute struct {
|
||||
method string
|
||||
path string
|
||||
middleware []string
|
||||
}
|
||||
|
||||
var (
|
||||
groupRe = regexp.MustCompile(`^(\w+)\s*:=\s*(\S+)\.Group\("([^"]*)"(?:,\s*(.+))?\)`)
|
||||
echoRouteRe = regexp.MustCompile(`^(?:e|cfg\.Echo)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
|
||||
groupRouteRe = regexp.MustCompile(`^(\w+)\.(GET|POST|PUT|PATCH|DELETE)\("([^"]*)"(?:,\s*(.+))?\)`)
|
||||
)
|
||||
|
||||
// extractRoutesFromRouterSource parses internal/router/*.go the way the echo
|
||||
// router resolves them: group prefixes concatenate, and some files receive
|
||||
// their group as a function parameter (registerScannerRoutes(protected, ...)).
|
||||
// This is a test — if it drifts from reality, a doc vs route mismatch shows up
|
||||
// in live behavior; treat failures here as "the parser needs updating", never
|
||||
// as license to edit docs to match the parser.
|
||||
func extractRoutesFromRouterSource(t *testing.T) map[string]extractedRoute {
|
||||
t.Helper()
|
||||
type group struct {
|
||||
prefix string
|
||||
middleware []string
|
||||
}
|
||||
groups := map[string]group{
|
||||
"e": {},
|
||||
"cfg.Echo": {},
|
||||
}
|
||||
|
||||
files, err := filepath.Glob("../router/*.go")
|
||||
if err != nil || len(files) == 0 {
|
||||
t.Fatalf("cannot read router sources: %v", err)
|
||||
}
|
||||
|
||||
routes := map[string]extractedRoute{}
|
||||
add := func(method, path string, mw []string) {
|
||||
routes[method+" "+path] = extractedRoute{method, path, mw}
|
||||
}
|
||||
|
||||
for _, file := range files {
|
||||
base := filepath.Base(file)
|
||||
if strings.HasSuffix(base, "_test.go") {
|
||||
continue
|
||||
}
|
||||
// registerScannerRoutes receives its groups as parameters; seed the
|
||||
// names the call site actually passes (router.go: protected=/api jwt,
|
||||
// admin=/api jwt+admin).
|
||||
if base == "scanner.go" {
|
||||
groups["protected"] = group{prefix: "/api", middleware: []string{"jwt"}}
|
||||
groups["admin"] = group{prefix: "/api", middleware: []string{"jwt", "admin"}}
|
||||
}
|
||||
raw, err := os.ReadFile(file)
|
||||
if err != nil {
|
||||
t.Fatalf("read %s: %v", file, err)
|
||||
}
|
||||
for _, line := range strings.Split(string(raw), "\n") {
|
||||
s := strings.TrimSpace(line)
|
||||
|
||||
if m := groupRe.FindStringSubmatch(s); m != nil {
|
||||
varname, parent, prefix, mwArg := m[1], m[2], m[3], m[4]
|
||||
parentInfo := groups[parent]
|
||||
g := group{
|
||||
prefix: strings.TrimSuffix(parentInfo.prefix+prefix, "/"),
|
||||
middleware: append(append([]string{}, parentInfo.middleware...), splitMW(mwArg)...),
|
||||
}
|
||||
groups[varname] = g
|
||||
continue
|
||||
}
|
||||
|
||||
if m := echoRouteRe.FindStringSubmatch(s); m != nil {
|
||||
add(m[1], m[2], splitMW(m[3]))
|
||||
continue
|
||||
}
|
||||
|
||||
if m := groupRouteRe.FindStringSubmatch(s); m != nil {
|
||||
g, ok := groups[m[1]]
|
||||
if !ok {
|
||||
continue
|
||||
}
|
||||
full := strings.TrimSuffix(g.prefix+m[3], "/")
|
||||
add(m[2], full, append(append([]string{}, g.middleware...), splitMW(m[4])...))
|
||||
}
|
||||
}
|
||||
}
|
||||
return routes
|
||||
}
|
||||
|
||||
func splitMW(s string) []string {
|
||||
if strings.TrimSpace(s) == "" {
|
||||
return nil
|
||||
}
|
||||
var out []string
|
||||
for _, part := range strings.Split(s, ",") {
|
||||
out = append(out, strings.TrimSpace(part))
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// authLabel reduces a middleware chain to the frontmatter auth vocabulary.
|
||||
func authLabel(chain []string) string {
|
||||
has := func(needle string) bool {
|
||||
for _, c := range chain {
|
||||
if strings.Contains(c, needle) {
|
||||
return true
|
||||
}
|
||||
}
|
||||
return false
|
||||
}
|
||||
switch {
|
||||
case has("AdminMiddleware"):
|
||||
return "jwt+admin"
|
||||
case has("DeviceAuthMiddleware"):
|
||||
return "device-token"
|
||||
case has("createOptionalAuthMiddleware"):
|
||||
return "optional-jwt"
|
||||
case has("jwt"):
|
||||
return "jwt"
|
||||
default:
|
||||
return "none"
|
||||
}
|
||||
}
|
||||
|
||||
// parseHandlerMiddleware extracts per-route middleware markers from the
|
||||
// registration's argument list (wrappers like rateLimitMiddleware(handler)).
|
||||
func parseHandlerMiddleware(rest string) []string {
|
||||
if rest == "" {
|
||||
return nil
|
||||
}
|
||||
var mw []string
|
||||
if strings.HasPrefix(strings.TrimSpace(rest), "rateLimitMiddleware") {
|
||||
mw = append(mw, "rateLimit")
|
||||
}
|
||||
if strings.Contains(rest, "AdminMiddleware") {
|
||||
mw = append(mw, "admin")
|
||||
}
|
||||
if strings.Contains(rest, "DeviceAuthMiddleware") {
|
||||
mw = append(mw, "device-token")
|
||||
}
|
||||
if strings.Contains(rest, "createJWTMiddleware") {
|
||||
mw = append(mw, "jwt")
|
||||
}
|
||||
return mw
|
||||
}
|
||||
|
||||
// ---------- the gate ----------
|
||||
|
||||
func TestDocsMatchRoutes(t *testing.T) {
|
||||
routes := extractRoutesFromRouterSource(t)
|
||||
|
||||
docsDir := "../../docs/developer/api"
|
||||
docs, err := LoadAPIDocs(docsDir)
|
||||
if err != nil {
|
||||
t.Fatalf("walk %s: %v", docsDir, err)
|
||||
}
|
||||
if len(docs) == 0 {
|
||||
t.Fatal("no frontmatter'd endpoint docs found — the gate is checking nothing")
|
||||
}
|
||||
|
||||
for _, doc := range docs {
|
||||
key := doc.Frontmatter.Method + " " + doc.Frontmatter.Path
|
||||
|
||||
route, ok := routes[key]
|
||||
if !ok {
|
||||
t.Errorf("%s: frontmatter declares %q but no such route is registered (wrong path, method, or the route moved)", doc.RelPath, key)
|
||||
continue
|
||||
}
|
||||
|
||||
if want := authLabel(route.middleware); doc.Frontmatter.Auth != want {
|
||||
t.Errorf("%s: frontmatter auth=%q but route middleware resolves to %q", doc.RelPath, doc.Frontmatter.Auth, want)
|
||||
}
|
||||
|
||||
for _, marker := range doc.Unverified {
|
||||
t.Logf("UNVERIFIED in %s: %s", doc.RelPath, marker)
|
||||
}
|
||||
|
||||
schema, registered := Schemas[key]
|
||||
if !registered {
|
||||
t.Errorf("%s: route %q has no internal/docs schema registry entry — add one in the same change", doc.RelPath, key)
|
||||
continue
|
||||
}
|
||||
|
||||
validateRequestExample(t, &doc, schema)
|
||||
validateResponseExample(t, &doc, schema)
|
||||
}
|
||||
}
|
||||
|
||||
func validateRequestExample(t *testing.T, doc *APIDoc, schema Schema) {
|
||||
t.Helper()
|
||||
if schema.Request == nil {
|
||||
if len(doc.ExampleRequest) > 0 {
|
||||
t.Errorf("%s: route takes no request body but the doc has an example-request block", doc.RelPath)
|
||||
}
|
||||
return
|
||||
}
|
||||
if len(doc.ExampleRequest) == 0 {
|
||||
t.Errorf("%s: no example-request block — required for routes with a body", doc.RelPath)
|
||||
return
|
||||
}
|
||||
|
||||
// Typo guard: field names must exist on the bind struct.
|
||||
dec := json.NewDecoder(bytes.NewReader(doc.ExampleRequest))
|
||||
dec.DisallowUnknownFields()
|
||||
v := reflect.New(reflect.TypeOf(schema.Request)).Interface()
|
||||
if err := dec.Decode(v); err != nil {
|
||||
t.Errorf("%s: example-request is not compatible with %T: %v", doc.RelPath, schema.Request, err)
|
||||
return
|
||||
}
|
||||
|
||||
// Staleness guard: required fields must be present in the example.
|
||||
for _, field := range requiredJSONFields(reflect.TypeOf(schema.Request)) {
|
||||
if !jsonHasKey(doc.ExampleRequest, field) {
|
||||
t.Errorf("%s: example-request missing required field %q", doc.RelPath, field)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
func validateResponseExample(t *testing.T, doc *APIDoc, schema Schema) {
|
||||
t.Helper()
|
||||
if schema.Response == nil {
|
||||
if doc.HasExampleResponse {
|
||||
t.Errorf("%s: route returns no JSON body but the doc has an example-response block", doc.RelPath)
|
||||
}
|
||||
return
|
||||
}
|
||||
if !doc.HasExampleResponse {
|
||||
t.Errorf("%s: no example-response block — required for JSON routes", doc.RelPath)
|
||||
return
|
||||
}
|
||||
|
||||
want := responseTopLevelKeys(t, schema.Response)
|
||||
got := topLevelKeys(doc.ExampleResponse)
|
||||
|
||||
for _, k := range sortedKeys(want) {
|
||||
if !got[k] {
|
||||
t.Errorf("%s: example-response missing key %q (the handler emits it)", doc.RelPath, k)
|
||||
}
|
||||
}
|
||||
for _, k := range sortedKeys(got) {
|
||||
if !want[k] {
|
||||
t.Errorf("%s: example-response has key %q but the handler does not emit it", doc.RelPath, k)
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
// requiredJSONFields lists json field names of struct type whose validate tag
|
||||
// marks them required.
|
||||
func requiredJSONFields(rt reflect.Type) []string {
|
||||
if rt.Kind() == reflect.Ptr {
|
||||
rt = rt.Elem()
|
||||
}
|
||||
var out []string
|
||||
for i := 0; i < rt.NumField(); i++ {
|
||||
f := rt.Field(i)
|
||||
jsonTag := strings.Split(f.Tag.Get("json"), ",")[0]
|
||||
if jsonTag == "" || jsonTag == "-" {
|
||||
continue
|
||||
}
|
||||
for _, rule := range strings.Split(f.Tag.Get("validate"), ",") {
|
||||
if strings.TrimSpace(rule) == "required" {
|
||||
out = append(out, jsonTag)
|
||||
break
|
||||
}
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
func jsonHasKey(data []byte, key string) bool {
|
||||
var m map[string]json.RawMessage
|
||||
if err := json.Unmarshal(data, &m); err != nil {
|
||||
return false
|
||||
}
|
||||
_, ok := m[key]
|
||||
return ok
|
||||
}
|
||||
|
||||
func topLevelKeys(data []byte) map[string]bool {
|
||||
var m map[string]json.RawMessage
|
||||
if err := json.Unmarshal(data, &m); err != nil {
|
||||
return nil
|
||||
}
|
||||
out := make(map[string]bool, len(m))
|
||||
for k := range m {
|
||||
out[k] = true
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// responseTopLevelKeys derives the expected top-level key set from the
|
||||
// registered Response: marshal a struct (or its element for slices), or use a
|
||||
// RawMessage pin verbatim.
|
||||
func responseTopLevelKeys(t *testing.T, resp any) map[string]bool {
|
||||
t.Helper()
|
||||
if raw, ok := resp.(json.RawMessage); ok {
|
||||
return topLevelKeys(raw)
|
||||
}
|
||||
rt := reflect.TypeOf(resp)
|
||||
if rt == nil {
|
||||
return nil
|
||||
}
|
||||
if rt.Kind() == reflect.Slice {
|
||||
if rt.Elem().Kind() == reflect.Uint8 {
|
||||
return topLevelKeys(reflect.ValueOf(resp).Bytes()) // []byte payloads
|
||||
}
|
||||
rt = rt.Elem()
|
||||
}
|
||||
if rt.Kind() == reflect.Ptr {
|
||||
rt = rt.Elem()
|
||||
}
|
||||
if rt.Kind() != reflect.Struct {
|
||||
t.Fatalf("schema response %T: unsupported kind %s (use a struct, slice of struct, or json.RawMessage)", resp, rt.Kind())
|
||||
}
|
||||
b, err := json.Marshal(reflect.New(rt).Interface())
|
||||
if err != nil {
|
||||
t.Fatalf("marshal schema response %T: %v", resp, err)
|
||||
}
|
||||
return topLevelKeys(b)
|
||||
}
|
||||
|
||||
func sortedKeys(m map[string]bool) []string {
|
||||
out := make([]string, 0, len(m))
|
||||
for k := range m {
|
||||
out = append(out, k)
|
||||
}
|
||||
// deterministic order for stable failure messages
|
||||
for i := 1; i < len(out); i++ {
|
||||
for j := i; j > 0 && out[j] < out[j-1]; j-- {
|
||||
out[j], out[j-1] = out[j-1], out[j]
|
||||
}
|
||||
}
|
||||
return out
|
||||
}
|
||||
|
||||
// Sanity: the extraction itself must find the pilot routes, otherwise the
|
||||
// gate would pass vacuously if the parser ever broke.
|
||||
func TestRouteExtractionFindsPilots(t *testing.T) {
|
||||
routes := extractRoutesFromRouterSource(t)
|
||||
for _, key := range []string{
|
||||
"POST /api/collections",
|
||||
"GET /api/collections",
|
||||
"GET /api/collections/:id",
|
||||
"PUT /api/collections/:id",
|
||||
"DELETE /api/collections/:id",
|
||||
"GET /api/admin/hash-conflicts",
|
||||
"POST /api/admin/hash-conflicts/:id/resolve",
|
||||
"POST /api/sync/kobo/:token/markup",
|
||||
"POST /api/auth/login",
|
||||
} {
|
||||
if _, ok := routes[key]; !ok {
|
||||
t.Errorf("route extraction missing %q (parser drift — fix extractRoutesFromRouterSource, do not edit docs to match)", key)
|
||||
}
|
||||
}
|
||||
if label := authLabel(routes["GET /api/admin/hash-conflicts"].middleware); label != "jwt+admin" {
|
||||
t.Errorf("hash-conflicts auth label = %q, want jwt+admin", label)
|
||||
}
|
||||
if label := authLabel(routes["POST /api/sync/kobo/:token/markup"].middleware); label != "device-token" {
|
||||
t.Errorf("kobo markup auth label = %q, want device-token", label)
|
||||
}
|
||||
if label := authLabel(routes["POST /api/auth/login"].middleware); label != "none" {
|
||||
t.Errorf("login auth label = %q, want none (public, rate-limited)", label)
|
||||
}
|
||||
}
|
||||
Reference in new issue
Block a user