Files
zeekayandHanzo Dev 0c08bd1d94 Go 1.27.1, and the code it can say more simply
Modules declare go 1.27.1 and the build images follow. go fix applied the
modernizers; omitzero is not applied, since it changes what the JSON says.

Co-authored-by: Hanzo Dev <[email protected]>
2026-09-17 01:01:10 -07:00

363 lines
12 KiB
Go

// Copyright 2023-2026 Hanzo AI Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
// Command routerdoc lifts each hand-written route's sentence out of the Go doc
// comment on the handler it names, into routers/wired_gen.go.
//
// go run ./cmd/routerdoc # write routers/wired_gen.go
// go run ./cmd/routerdoc -verify # fail if it would differ
//
// # Why a build-time pass and not a table
//
// Go DROPS COMMENTS AT COMPILE TIME, so a running program cannot read the sentence
// its own handler was documented with. Every projection that needs one — the
// published OpenAPI document, the MCP tool list, the generated SDKs, the CLI's
// help — therefore either gets it lifted before the build or gets it from a second
// place. A second place is the disease: prose written beside the route drifts from
// the handler it describes, silently, in the direction that hurts, because the
// spec is what customers believe.
//
// So the sentence has ONE home — the doc comment on the handler — and this reads
// it there. `App.Router(path, &controllers.X{}, "GET:Fn")` already names the
// handler, machine-readably, in the same call that names the address; nothing new
// is declared and there is nothing to keep in step.
//
// It is the same law hanzoai/cloud's zipdoc obeys for typed zip handlers, and the
// same identifier strip: Go's "Fn does X" convention is right for godoc and noise
// in a description projected out of Go's namespace.
//
// # What it reads, and what it refuses
//
// Only calls whose path and method-spec are STRING LITERALS: the resource table in
// routers/resources.go computes both, and its surface is already described by
// routers/openapi.go from that same table. A route that is registered but whose
// handler has no doc comment is a build failure naming the file, because a
// published operation that says nothing about itself is exactly what this exists
// to prevent, and only the person writing the handler can fix it.
package main
import (
"bytes"
"flag"
"fmt"
"go/ast"
"go/format"
"go/parser"
"go/token"
"os"
"path/filepath"
"sort"
"strconv"
"strings"
"unicode"
"unicode/utf8"
)
func main() {
verify := flag.Bool("verify", false, "fail if the generated file is not up to date")
dir := flag.String("C", ".", "module root")
flag.Parse()
out := filepath.Join(*dir, "routers", "wired_gen.go")
got, err := render(*dir)
if err != nil {
fmt.Fprintln(os.Stderr, "routerdoc:", err)
os.Exit(1)
}
if *verify {
want, err := os.ReadFile(out)
if err != nil || !bytes.Equal(want, got) {
fmt.Fprintf(os.Stderr, "routerdoc: %s is stale — run `go generate ./routers`\n", out)
os.Exit(1)
}
return
}
if err := os.WriteFile(out, got, 0o644); err != nil {
fmt.Fprintln(os.Stderr, "routerdoc:", err)
os.Exit(1)
}
}
// route is one registration: an address, a verb, and the handler that answers it.
type route struct{ path, method, ctrl, handler string }
func render(dir string) ([]byte, error) {
routes, err := registrations(filepath.Join(dir, "routers"))
if err != nil {
return nil, err
}
docs, err := handlerDocs(filepath.Join(dir, "controllers"))
if err != nil {
return nil, err
}
var bare []string
var b bytes.Buffer
b.WriteString("// Code generated by cmd/routerdoc; DO NOT EDIT.\n\npackage routers\n\n" +
"// wired is every hand-written route in this package, with the sentence lifted\n" +
"// from the Go doc comment on the handler it names. See cmd/routerdoc.\n" +
"var wired = []wire{\n")
for _, r := range routes {
doc, ok := docs[r.ctrl+"."+r.handler]
summary, description := prose(doc, r.handler)
if !ok || summary == "" {
bare = append(bare, fmt.Sprintf(" %s %s -> (*%s).%s", r.method, r.path, r.ctrl, r.handler))
continue
}
fmt.Fprintf(&b, "\t{%q, %q, %q, %q, %q},\n", r.path, r.method, r.handler, summary, description)
}
b.WriteString("}\n")
if len(bare) > 0 {
sort.Strings(bare)
return nil, fmt.Errorf("%d registered route(s) name a handler with no doc comment:\n%s\n\n"+
"Every operation states what it does for the person calling it, and that sentence has one home: "+
"the Go doc comment on the handler. It is lifted from there into the published route table, the "+
"MCP tool list, every generated SDK and the CLI's help — nothing downstream can supply it. Write "+
"it where the handler lives, or delete the route",
len(bare), strings.Join(bare, "\n"))
}
return format.Source(b.Bytes())
}
// registrations reads every `route(app, "path", "VERB:Handler;…")` whose path and
// mapping are literals, sorted by (path, method) so the output is stable.
//
// The controller is not an argument to read: serve (routers/route.go) resolves every
// mapped name as a method on controllers.ApiController, so there is exactly one
// receiver, and naming it here reads the registration rather than guessing at it.
//
// Non-literal arguments are the resource table's, and are skipped rather than
// approximated: routers/openapi.go already describes that half from the same table
// that registers it, so guessing here would be a second answer to a settled
// question.
func registrations(dir string) ([]route, error) {
fset := token.NewFileSet()
pkgs, err := parser.ParseDir(fset, dir, func(fi os.FileInfo) bool {
return !strings.HasSuffix(fi.Name(), "_test.go")
}, 0)
if err != nil {
return nil, err
}
var out []route
for _, pkg := range pkgs {
for _, f := range pkg.Files {
ast.Inspect(f, func(n ast.Node) bool {
call, ok := n.(*ast.CallExpr)
if !ok || len(call.Args) != 3 {
return true
}
fn, ok := call.Fun.(*ast.Ident)
if !ok || fn.Name != "route" {
return true
}
path, ok := literal(call.Args[1])
if !ok {
return true
}
spec, ok := literal(call.Args[2])
if !ok {
return true
}
const ctrl = "ApiController"
for pair := range strings.SplitSeq(spec, ";") {
verb, handler, found := strings.Cut(pair, ":")
if !found {
continue
}
out = append(out, route{path, strings.ToUpper(strings.TrimSpace(verb)), ctrl, strings.TrimSpace(handler)})
}
return true
})
}
}
sort.Slice(out, func(i, j int) bool {
if out[i].path != out[j].path {
return out[i].path < out[j].path
}
return out[i].method < out[j].method
})
return out, nil
}
// literal is a plain string literal's value, or false for anything computed.
func literal(e ast.Expr) (string, bool) {
lit, ok := e.(*ast.BasicLit)
if !ok || lit.Kind != token.STRING {
return "", false
}
s, err := strconv.Unquote(lit.Value)
return s, err == nil
}
// handlerDocs is every method's doc comment, keyed "Receiver.Method".
func handlerDocs(dir string) (map[string]string, error) {
fset := token.NewFileSet()
pkgs, err := parser.ParseDir(fset, dir, func(fi os.FileInfo) bool {
return !strings.HasSuffix(fi.Name(), "_test.go")
}, parser.ParseComments)
if err != nil {
return nil, err
}
out := map[string]string{}
for _, pkg := range pkgs {
for _, f := range pkg.Files {
for _, d := range f.Decls {
fn, ok := d.(*ast.FuncDecl)
if !ok || fn.Recv == nil || len(fn.Recv.List) != 1 || fn.Doc == nil {
continue
}
recv := ""
switch t := fn.Recv.List[0].Type.(type) {
case *ast.StarExpr:
if id, ok := t.X.(*ast.Ident); ok {
recv = id.Name
}
case *ast.Ident:
recv = t.Name
}
if recv != "" {
out[recv+"."+fn.Name.Name] = fn.Doc.Text()
}
}
}
}
return out, nil
}
// prose turns a handler's doc comment into (summary, description).
//
// Two comment shapes exist in this repo and both are the handler's own words, so
// both are read rather than one being declared canonical and the other's prose
// thrown away:
//
// - a Go doc comment ("Embeddings implements POST /v1/embeddings …"), which is
// the shape to write;
// - a swagger-annotated block whose only sentence is on `@Description` lines,
// which is the shape this repo inherited.
//
// The annotations themselves (@Title, @Param, @Success, @router, …) are a
// generator's input, not prose, and are dropped — including `@router`, which
// states an address the router already states and has drifted from it (`/chat`
// where the route is `/v1/chat`).
func prose(text, handler string) (summary, description string) {
lines := strings.Split(text, "\n")
// The Go doc comment is everything before the first annotation.
cut := len(lines)
for i, line := range lines {
if strings.HasPrefix(strings.TrimSpace(line), "@") {
cut = i
break
}
}
body := strings.TrimSpace(strings.Join(lines[:cut], "\n"))
if body == handler {
body = "" // the identifier and nothing else says nothing
}
// Only then the annotations, and only @Description — with its continuation.
// gofmt indents a wrapped annotation line, which makes it a godoc CODE BLOCK
// and is why reading the non-annotation lines alone produced sentences that
// began mid-clause ("(enabled/primary/keyPresent/modelCount)."). The
// continuation belongs to the annotation above it, so it is read with it and
// its indentation is dropped.
if body == "" {
var desc []string
for i := cut; i < len(lines); i++ {
rest, ok := strings.CutPrefix(strings.TrimSpace(lines[i]), "@Description")
if !ok {
continue
}
desc = append(desc, strings.TrimSpace(rest))
for i+1 < len(lines) && !strings.HasPrefix(strings.TrimSpace(lines[i+1]), "@") {
i++
if t := strings.TrimSpace(lines[i]); t != "" {
desc = append(desc, t)
}
}
}
body = strings.TrimSpace(strings.Join(desc, "\n"))
}
body = stripSelf(body, handler)
if body == "" {
return "", ""
}
// A sentence starts with a capital. The annotated shape's text is a fragment
// written to follow "@Description", so it arrives lower-cased ("check if the
// system is live") and is read by a person as the first thing an operation says.
r, size := utf8.DecodeRuneInString(body)
if r != utf8.RuneError {
body = string(unicode.ToUpper(r)) + body[size:]
}
return firstSentence(body), body
}
// stripSelf drops the leading identifier Go's doc convention requires — "RevokeKey
// revokes …" — when the comment is projected OUT of Go's namespace, where the
// function name is noise. Only an exact leading match of the handler's own name is
// dropped, so prose that merely opens with a camel-case word keeps it. Same rule,
// and same reason, as zip's cmd/zipdoc.
// A COPULA goes with it: "AudioSpeech is the OpenAI-compatible TTS endpoint" is
// idiomatic godoc and becomes "Is the OpenAI-compatible TTS endpoint" if only the
// name is dropped. The subject was the name, so removing the subject removes its
// verb — "The OpenAI-compatible TTS endpoint". Same rule the fleet already applies
// to a package's "Package x is …" line.
func stripSelf(text, name string) string {
rest, ok := strings.CutPrefix(text, name+" ")
if !ok {
return text
}
for _, copula := range []string{"is ", "are "} {
if after, ok := strings.CutPrefix(rest, copula); ok {
rest = after
break
}
}
r, size := utf8.DecodeRuneInString(rest)
if r == utf8.RuneError {
return text
}
return string(unicode.ToUpper(r)) + rest[size:]
}
// firstSentence is the summary: one sentence, on one line.
//
// The boundary is a period followed by whitespace or the end, so "v1.2" and
// "hanzo.ai" do not end one, and the result is whitespace-collapsed — a source
// line break is a fact about the source, never about the operation.
func firstSentence(s string) string {
if i := sentenceEnd(s); i >= 0 {
s = s[:i+1]
} else if i := strings.IndexByte(s, '\n'); i >= 0 {
s = s[:i]
}
return strings.Join(strings.Fields(s), " ")
}
func sentenceEnd(s string) int {
for i := strings.IndexByte(s, '.'); i >= 0; {
if i+1 == len(s) || s[i+1] == ' ' || s[i+1] == '\n' || s[i+1] == '\t' || s[i+1] == '\r' {
return i
}
next := strings.IndexByte(s[i+1:], '.')
if next < 0 {
return -1
}
i += 1 + next
}
return -1
}