stacklok / toolhive / 30161660472

69%

Build Type

push

github

Committed by web-flow

Commit Message

Make swagger docgen deterministic (dedupe swag's doubled enums)

* Pin swag version for swagger docgen instead of @latest

go.mod already requires github.com/swaggo/swag/v2 v2.0.0-rc5, but
Taskfile.yml and verify-docgen.yml both installed the swag CLI via
@latest, so a future swag release could silently change doc output
underneath the "Verify Swagger Documentation" check with no code
change to review. Pin both install steps to the version already in
go.mod.

This does not fully close out the nondeterminism seen in that check:
swag v2.0.0-rc5 itself has a bug where loadExternalPackage (packages.go)
reparses an external module's package without memoizing by import
path, which can non-deterministically double x-enum-varnames/enum
entries for types defined outside this module (observed for
model.ArgumentType, model.Format, and model.Icon from
github.com/modelcontextprotocol/registry). Confirmed across repeated
runs with this exact pinned binary: some runs match the committed
docs, others don't. See handover notes for follow-up options.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* Dedupe swag's nondeterministic doubled enum arrays

GOMAXPROCS=1 does not make swagger docgen deterministic (confirmed:
even single-threaded, a fresh run can still double enum arrays), so
the nondeterminism isn't a goroutine race — it's driven by Go's
randomized map iteration order inside swag's file-processing loop
(packages.go), which changes which files get walked in what order
each run.

Root cause: swag's loadExternalPackage (packages.go) reparses an
external module's package every time one of its consts needs
evaluating, without memoizing by import path. For types defined
outside this module — model.ArgumentType, model.Format, model.Icon
from github.com/modelcontextprotocol/registry — that can append the
same const declarations twice, doubling the emitted "enum" and
"x-enum-varnames" arrays. Whether that happens depends on map
iteration order, so it varies r... (continued)

Coverage Stats

11 of 52 new or added lines in 1 file covered. (21.15%)

6 existing lines in 2 files now uncovered.

79285 of 114295 relevant lines covered (69.37%)

80.85 hits per line