[feat] doccov: README<->builtin doc-consistency gate#5
Merged
Conversation
Adds doccov, a static gate that fails when a module exposes a Starlark builtin (starlark.NewBuiltin) that is not documented in its README — so docs cannot silently drift behind the code. - doccov/main.go: AST-scan non-test *.go for NewBuiltin first-arg names (handles "module.fn" and ModuleName+".fn"), check each appears as a backtick word in README.md; exit non-zero on omission. Stdlib only. - doccov/main_test.go + testdata: surface extraction, backtick coverage, pass/fail/no-builtins/ignore/missing-readme cases. - go.mod: meta becomes module github.com/1set/meta (go 1.19), so the tool is runnable as `go run github.com/1set/meta/doccov@master .`. - go-ci.yml: opt-in `doc-coverage` input + a gating step on the checks leg (fetched with `go run`, like govulncheck). Off by default; core libs unaffected. - selftest.yml: a job that runs `go test -race ./doccov/`. Validated against real modules: sqlite passes (29/29); markdown and qrcode each surface a genuine undocumented builtin (custom_converter, pure_ascii). Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
Adds doccov, the documentation-consistency gate for the Star* ecosystem, living here in
metaso all repos share it.A Star* module exposes its script-facing API as Starlark builtins, each built with
starlark.NewBuiltin("<name>", fn). doccov statically scans a module's Go source for those builtins and fails if any is not documented in the module's README — so docs can never silently drift behind the code.Pieces
doccov/main.go— AST-scans non-test*.gofor everystarlark.NewBuiltin(...)first argument (handles"module.fn"and theModuleName + ".fn"form), reduces to the short name, and checks it appears as a backtick word inREADME.md. Exit non-zero on omission or a missing README; exit zero when no builtins are found (repo doesn't opt in). Stdlib only.doccov/main_test.go+testdata/— surface extraction, backtick coverage, and pass / fail / no-builtins / ignore / missing-readme end-to-end cases.go.mod—metabecomesmodule github.com/1set/meta(go 1.19), so the tool runs asgo run github.com/1set/meta/doccov@master ..go-ci.yml— opt-indoc-coverageinput + a gating step on the checks leg (fetched withgo run, like govulncheck). Off by default; core libs unaffected.selftest.yml— adoccovjob runninggo test -race ./doccov/.Validation
Run against real ecosystem modules:
starpkg/sqlitestarpkg/markdowncustom_converter→ fail (real gap)starpkg/qrcodepure_ascii→ fail (real gap)Tool passes
go test -race -count=2locally andgo teston the go1.19 floor in Docker.Rollout
Consuming starpkg domain modules opt in per-repo (re-pin +
doc-coverage: true) alongside their doc fixes. GoDoc completeness stays covered byrevive'sexportedrule in the Analyze step.🤖 Generated with Claude Code