Bookhoard/bookhoard
0
0 Fork 0
Code Issues 1 Pull Requests Actions Packages Projects Releases 54 Wiki Activity

feat(docs): drift gate — docs frontmatter validated against real routes

Browse Source 
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 2026-10-24 14:41:02 -04:00
1 parent 994e0f86c4
commit cc893f758e
8 files changed
+824 -168
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

internal/handlers/collections.go
+28 -24
View File
@@ -75,6 +75,30 @@ type UpdateDeviceMappingRequest struct {
SyncDirection string `json:"sync_direction" validate:"required,oneof=bidirectional book_to_device device_to_book none"`
}
// CollectionSummary is one entry in GET /api/collections. Package-level so
// the docs schema registry (internal/docs) can pin the response shape.
type CollectionSummary struct {
ID uuid.UUID `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Color string `json:"color"`
Icon string `json:"icon"`
AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
CreatedAt string `json:"created_at"`
BookCount int `json:"book_count"`
IsSmart bool `json:"is_smart"`
}
// BookCollectionSummary is one entry in GET /api/collections/:id/books —
// the collections a book belongs to (list view: no rules/count fields).
type BookCollectionSummary struct {
ID uuid.UUID `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Color string `json:"color"`
Icon string `json:"icon"`
}
type SectionData struct {
ID string `json:"id"`
CollectionID string `json:"collection_id"`
@@ -160,19 +184,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
}
type CollectionResponse struct {
ID uuid.UUID `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Color string `json:"color"`
Icon string `json:"icon"`
AutoAssignRules json.RawMessage `json:"auto_assign_rules"`
CreatedAt string `json:"created_at"`
BookCount int `json:"book_count"`
IsSmart bool `json:"is_smart"`
}
response := make([]CollectionResponse, 0, len(collections))
response := make([]CollectionSummary, 0, len(collections))
for _, col := range collections {
isSmart := h.collectionService.IsSmartCollection(col.AutoAssignRules)
if !includeAuto && isSmart {
@@ -211,7 +223,7 @@ func (h *CollectionHandler) GetCollections(c *echo.Context) error {
}
}
response = append(response, CollectionResponse{
response = append(response, CollectionSummary{
ID: col.ID.Bytes,
Name: col.Name,
Description: utils.PgTextString(col.Description),
@@ -768,17 +780,9 @@ func (h *CollectionHandler) GetBookCollections(c *echo.Context) error {
return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
}
type CollectionResponse struct {
ID uuid.UUID `json:"id"`
Name string `json:"name"`
Description string `json:"description"`
Color string `json:"color"`
Icon string `json:"icon"`
}
response := make([]CollectionResponse, 0, len(collections))
response := make([]BookCollectionSummary, 0, len(collections))
for _, col := range collections {
response = append(response, CollectionResponse{
response = append(response, BookCollectionSummary{
ID: col.ID.Bytes,
Name: col.Name,
Description: utils.PgTextString(col.Description),