types: generate a table of config field docs

Updates #1926
This commit is contained in:
Kristoffer Dalby committed 2026-11-11 12:19:28 +01:00
1 parent caecddd249
commit 0578c2a571
11 files changed
+1260 -187

No files matched your search

+8 -7
View File
@@ -13,13 +13,14 @@ import (
// outside it means a generator reached further than expected, and the area is
// dropped rather than committed.
var generatedPaths = map[string]bool{
"hscontrol/types/types_clone.go": true,
"hscontrol/types/types_view.go": true,
"hscontrol/capver/capver_generated.go": true,
"hscontrol/capver/capver_test_data.go": true,
"gen/client/v1/client.gen.go": true,
"gen/client/v2/client.gen.go": true,
".github/workflows/test-integration.yaml": true,
"hscontrol/types/types_clone.go": true,
"hscontrol/types/types_view.go": true,
"hscontrol/types/config_docs_generated.go": true,
"hscontrol/capver/capver_generated.go": true,
"hscontrol/capver/capver_test_data.go": true,
"gen/client/v1/client.gen.go": true,
"gen/client/v2/client.gen.go": true,
".github/workflows/test-integration.yaml": true,
}
// oapiPin finds the oapi-codegen version the Makefile pins, so the clients are
+277
View File
@@ -0,0 +1,277 @@
// Command configgen writes files generated from the configuration's Go
// source. `configgen table <pkgdir> <out.go>` writes the doc comments of
// the configuration fields and enum values as Go maps, so the binary can
// print them; out.go is not read.
package main
import (
"bytes"
"errors"
"fmt"
"go/ast"
"go/format"
"go/parser"
"go/token"
"log"
"maps"
"os"
"path/filepath"
"reflect"
"slices"
"strconv"
"strings"
"unicode"
"unicode/utf8"
)
var (
errUsage = errors.New("usage: configgen table <pkgdir> <out.go>")
errEnumValue = errors.New("value must be a string literal with an explicit type")
errNameOnly = errors.New("doc comment says nothing after the Go name")
)
func main() {
if len(os.Args) != 4 || os.Args[1] != "table" {
log.Fatal(errUsage)
}
err := generate(os.Args[2], os.Args[3])
if err != nil {
log.Fatal(err)
}
}
// generate writes the table of the package in dir to out.
func generate(dir, out string) error {
src, err := table(dir, out)
if err != nil {
return err
}
return os.WriteFile(out, src, 0o600)
}
// table is the generated Go file holding the docs of the package in dir,
// whose sources other than out it reads.
func table(dir, out string) ([]byte, error) {
paths, err := filepath.Glob(filepath.Join(dir, "*.go"))
if err != nil {
return nil, err
}
outAbs, err := filepath.Abs(out)
if err != nil {
return nil, err
}
// The previous output is no input: a conflicted or stale one must not
// stop its own regeneration.
paths = slices.DeleteFunc(paths, func(p string) bool {
abs, _ := filepath.Abs(p)
return strings.HasSuffix(p, "_test.go") || abs == outAbs
})
fields, values, err := extractDocs(paths...)
if err != nil {
return nil, err
}
var b bytes.Buffer
b.WriteString("// Code generated by tools/configgen from hscontrol/types/config.go; DO NOT EDIT.\n\npackage types\n")
writeMap(&b, "configFieldDocs", fields)
writeMap(&b, "configValueDocs", values)
return format.Source(b.Bytes())
}
func writeMap(b *bytes.Buffer, name string, m map[string]string) {
fmt.Fprintf(b, "\nvar %s = map[string]string{\n", name)
for _, k := range slices.Sorted(maps.Keys(m)) {
fmt.Fprintf(b, "%q: %q,\n", k, m[k])
}
b.WriteString("}\n")
}
// extractDocs reads the docs of every struct field with a koanf tag other
// than "-", keyed "<Type>.<Field>", and of every documented constant of a
// type with an Allowed method, keyed "<Type>=<value>".
func extractDocs(paths ...string) (map[string]string, map[string]string, error) {
fset := token.NewFileSet()
var decls []*ast.GenDecl
enums := map[string]bool{}
for _, p := range paths {
f, err := parser.ParseFile(fset, p, nil, parser.ParseComments)
if err != nil {
return nil, nil, err
}
for _, d := range f.Decls {
switch d := d.(type) {
case *ast.GenDecl:
decls = append(decls, d)
case *ast.FuncDecl:
if d.Name.Name == "Allowed" && d.Recv != nil {
enums[typeName(d.Recv.List[0].Type)] = true
}
}
}
}
fields := map[string]string{}
values := map[string]string{}
for _, d := range decls {
for _, s := range d.Specs {
switch s := s.(type) {
case *ast.TypeSpec:
st, ok := s.Type.(*ast.StructType)
if !ok {
continue
}
for _, f := range st.Fields.List {
if !hasKoanfKey(f) {
continue
}
for _, n := range f.Names {
key := s.Name.Name + "." + n.Name
text, err := docText(f.Doc, n.Name)
if err != nil {
return nil, nil, fmt.Errorf("%s: %s: %w", fset.Position(n.Pos()), key, err)
}
fields[key] = text
}
}
case *ast.ValueSpec:
doc := s.Doc
if doc == nil && !d.Lparen.IsValid() {
doc = d.Doc
}
if d.Tok != token.CONST || doc == nil {
continue
}
for i, n := range s.Names {
typ := typeName(s.Type)
var val ast.Expr
if i < len(s.Values) {
val = ast.Unparen(s.Values[i])
}
if call, ok := val.(*ast.CallExpr); ok && typ == "" {
typ = typeName(call.Fun)
}
if !enums[typ] {
continue
}
// Only a typed literal is read; any other form fails
// rather than drop the value's doc.
lit, ok := val.(*ast.BasicLit)
if s.Type == nil || !ok || lit.Kind != token.STRING {
return nil, nil, fmt.Errorf("%s: constant %s: %w", fset.Position(n.Pos()), n.Name, errEnumValue)
}
v, err := strconv.Unquote(lit.Value)
if err != nil {
return nil, nil, err
}
text, err := docText(doc, n.Name)
if err != nil {
return nil, nil, fmt.Errorf("%s: constant %s: %w", fset.Position(n.Pos()), n.Name, err)
}
values[typ+"="+v] = text
}
}
}
}
return fields, values, nil
}
// typeName is the name of a type expression T or *T, or "".
func typeName(e ast.Expr) string {
if s, ok := ast.Unparen(e).(*ast.StarExpr); ok {
e = s.X
}
if id, ok := ast.Unparen(e).(*ast.Ident); ok {
return id.Name
}
return ""
}
func hasKoanfKey(f *ast.Field) bool {
if f.Tag == nil {
return false
}
tag, err := strconv.Unquote(f.Tag.Value)
if err != nil {
return false
}
key := reflect.StructTag(tag).Get("koanf")
return key != "" && key != "-"
}
// docText is a doc comment as paragraphs joined by a blank line, without
// a leading Go name and its "is" or "are": "Addr is the host:port" becomes
// "The host:port". A prose paragraph is put on one line; one with an
// indented line, a list or code, keeps its lines.
func docText(doc *ast.CommentGroup, name string) (string, error) {
paras := strings.Split(strings.TrimSuffix(doc.Text(), "\n"), "\n\n")
for i, p := range paras {
lines := strings.Split(p, "\n")
if !slices.ContainsFunc(lines, func(l string) bool { return strings.HasPrefix(l, " ") || strings.HasPrefix(l, "\t") }) {
paras[i] = strings.Join(lines, " ")
}
}
// Only the opening prose paragraph can start with the name; the strip
// never crosses into a list or code block below it.
rest, ok := cutWord(paras[0], name)
if ok {
if r, ok := cutWord(rest, "is"); ok {
rest = r
} else if r, ok := cutWord(rest, "are"); ok {
rest = r
}
if rest == "" {
return "", errNameOnly
}
r, size := utf8.DecodeRuneInString(rest)
paras[0] = string(unicode.ToUpper(r)) + rest[size:]
}
return strings.Join(paras, "\n\n"), nil
}
// cutWord cuts the word w and the spaces after it from the start of s.
func cutWord(s, w string) (string, bool) {
rest, ok := strings.CutPrefix(s, w)
if !ok || rest != "" && rest[0] != ' ' {
return s, false
}
return strings.TrimLeft(rest, " "), true
}
+163
View File
@@ -0,0 +1,163 @@
package main
import (
"os"
"path/filepath"
"testing"
"github.com/google/go-cmp/cmp"
"github.com/stretchr/testify/require"
)
func TestExtractDocs(t *testing.T) {
fields, values, err := extractDocs("testdata/fixture.go.txt")
require.NoError(t, err)
tests := []struct {
name string
got map[string]string
want map[string]string
}{
{
name: "fields",
got: fields,
want: map[string]string{
"Server.Addr": "The host:port the server listens on.",
"Server.Commands": "Run in order:\n\n\tfirst command\n\tsecond command",
"Server.Enabled": "Lets nodes connect.",
"Server.Notes": "Two paragraphs, still the first.\n\nThe second paragraph.",
"Server.Choices": "Listed:\n\n - first choice\n - second choice\n\nRun:\n\n\tfirst command\n\t indented more",
"Server.Retries": "How often to retry; Retries is not the first word.",
},
},
{
name: "values",
got: values,
want: map[string]string{
"Mode=fast": "The quick path.",
"Mode=slow": "Takes its time.",
"Mode=paren": "Has its type in parentheses.",
},
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
if diff := cmp.Diff(tt.want, tt.got); diff != "" {
t.Errorf("(-want +got):\n%s", diff)
}
})
}
}
func TestExtractDocsErrors(t *testing.T) {
const enum = "package fixture\n\ntype Mode string\n\nfunc (Mode) Allowed() []string { return nil }\n\n"
tests := []struct {
name string
src string
wantErr string
}{
{
name: "enum value is an expression",
src: enum + "const (\n\t// ModeSlow is slow.\n\tModeSlow Mode = \"sl\" + \"ow\"\n)\n",
wantErr: "constant ModeSlow: value must be a string literal with an explicit type",
},
{
name: "enum type is inferred",
src: enum + "const (\n\t// ModeAlias is an alias.\n\tModeAlias = Mode(\"alias\")\n)\n",
wantErr: "constant ModeAlias: value must be a string literal with an explicit type",
},
{
name: "enum conversion in parentheses",
src: enum + "const (\n\t// ModeParen is in parentheses.\n\tModeParen = (Mode(\"paren\"))\n)\n",
wantErr: "constant ModeParen: value must be a string literal with an explicit type",
},
{
name: "opening paragraph is only the Go name",
src: "package fixture\n\ntype Server struct {\n\t// Choices are\n\t//\n\t//\tfirst command\n\t//\tsecond command\n\tChoices string `koanf:\"choices\"`\n}\n",
wantErr: "Server.Choices: doc comment says nothing after the Go name",
},
{
name: "doc is only the Go name",
src: "package fixture\n\ntype Server struct {\n\t// Addr is\n\tAddr string `koanf:\"addr\"`\n}\n",
wantErr: "Server.Addr: doc comment says nothing after the Go name",
},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
path := filepath.Join(t.TempDir(), "fixture.go")
require.NoError(t, os.WriteFile(path, []byte(tt.src), 0o600))
_, _, err := extractDocs(path)
require.ErrorContains(t, err, tt.wantErr)
})
}
}
// TestGenerate: the output file is not an input, so a conflicted or
// deleted table regenerates; a broken source file still fails.
func TestGenerate(t *testing.T) {
fixture, err := os.ReadFile("testdata/fixture.go.txt")
require.NoError(t, err)
clean := t.TempDir()
require.NoError(t, os.WriteFile(filepath.Join(clean, "fixture.go"), fixture, 0o600))
want, err := table(clean, filepath.Join(clean, "docs_generated.go"))
require.NoError(t, err)
const conflicted = "<<<<<<< HEAD\npackage types\n=======\n>>>>>>> other\n"
tests := []struct {
name string
files map[string]string // besides fixture.go
wantErr string
}{
{name: "deleted output"},
{name: "conflicted output", files: map[string]string{"docs_generated.go": conflicted}},
{name: "conflicted source", files: map[string]string{"other.go": conflicted}, wantErr: "other.go"},
}
for _, tt := range tests {
t.Run(tt.name, func(t *testing.T) {
dir := t.TempDir()
require.NoError(t, os.WriteFile(filepath.Join(dir, "fixture.go"), fixture, 0o600))
for name, src := range tt.files {
require.NoError(t, os.WriteFile(filepath.Join(dir, name), []byte(src), 0o600))
}
out := filepath.Join(dir, "docs_generated.go")
err := generate(dir, out)
if tt.wantErr != "" {
require.ErrorContains(t, err, tt.wantErr)
return
}
require.NoError(t, err)
got, err := os.ReadFile(out)
require.NoError(t, err)
if diff := cmp.Diff(string(want), string(got)); diff != "" {
t.Errorf("(-want +got):\n%s", diff)
}
})
}
}
func TestTableFresh(t *testing.T) {
got, err := table("../../hscontrol/types", "../../hscontrol/types/config_docs_generated.go")
require.NoError(t, err)
want, err := os.ReadFile("../../hscontrol/types/config_docs_generated.go")
require.NoError(t, err)
if diff := cmp.Diff(string(want), string(got)); diff != "" {
t.Errorf("hscontrol/types/config_docs_generated.go is stale, run go generate ./hscontrol/types/ (-committed +extracted):\n%s", diff)
}
}
+70
View File
@@ -0,0 +1,70 @@
package fixture
// Mode has an Allowed method, so its documented constants are values.
type Mode string
func (Mode) Allowed() []string { return []string{string(ModeFast), string(ModeSlow)} }
const (
// ModeFast is the quick path.
ModeFast Mode = "fast"
// ModeSlow takes its time.
ModeSlow Mode = "slow"
ModeOff Mode = "off"
// ModeParen has its type in parentheses.
ModeParen (Mode) = ("paren")
)
// Other has no Allowed method.
type Other string
const (
// OtherValue is not a value of an enum.
OtherValue Other = "value"
// OtherConverted is not a value of an enum either.
OtherConverted = Other("converted")
)
type Server struct {
// Addr is the host:port the server listens on.
Addr string `koanf:"addr"`
// Enabled lets nodes connect.
Enabled bool `koanf:"enabled"`
// Notes are two paragraphs,
// still the first.
//
// The second paragraph.
Notes []string `koanf:"notes"`
// Choices are listed:
//
// - first choice
// - second choice
//
// Run:
//
// first command
// indented more
Choices string `koanf:"choices"`
// Commands are run in order:
//
// first command
// second command
Commands []string `koanf:"commands"`
// How often to retry; Retries is not the first word.
Retries int `koanf:"retries"`
// Untagged has no koanf tag.
Untagged string
// Skipped is tagged out.
Skipped string `koanf:"-"`
}