mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-21 02:05:26 +00:00
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]>
363 lines
12 KiB
Go
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
|
|
}
|