mirror of
https://github.com/hanzoai/ai.git
synced 2026-11-21 11:09:56 +00:00
This surface reaches api.hanzo.ai through ONE `app.All("/v1/*")` in the host, so
reading the host's router alone published `/v1/{wildcard1}` and seven operations
for the whole model API. No generated SDK carried chat completions, no MCP tool
list carried one, and hanzoai/cli grew a `{wildcard1}` command because that is what
the document named. The host can ask what is behind its own door — App.Patterns
already answers the address and the verb — but a published operation owes a reader
a third thing, and there was nowhere to get it: 190 patterns, 295 registrations,
0 sentences reachable from outside this package.
Go drops comments at compile time, so a running program cannot read the sentence
its own handler was documented with. cmd/routerdoc lifts it before the build, from
the one place it already lives: `App.Router(path, &controllers.X{}, "GET:Fn")` names
the handler machine-readably in the same call that names the address, and 67 of 68
handlers already carried a doc comment. Nothing new is declared and there is no
table to keep in step — same law, and the same identifier strip, as zip's
cmd/zipdoc for typed handlers.
routers.Prose() 295 of 295 registrations: 87 rows lifted from handler doc
comments, plus the resource half routers/openapi.go already
derives from the same table that registers it
82 of those are the bare /v1 inference surface — chat/completions, models,
embeddings, messages, rerank, audio/speech, images/generations and the rest
Two tests, one bijection: every route App registers has a sentence, and every
sentence is about a route App registers. A missing one is an operation no SDK, MCP
tool or CLI command can describe; an extra one is a phantom. cmd/routerdoc's own
test re-derives wired_gen.go and compares, because an artifact checked against
itself passes while the comment it was lifted from moves on.
Six doc comments are rewritten so the sentence leads rather than the address:
ReloadModelConfig documented `/api/reload-model-config`, a prefix this service has
never served, and four in model_access.go opened mid-clause ("(GET /v1/models/…)
returns …"). The strip drops a leading subject WITH its copula, so godoc's idiomatic
"AudioSpeech is the OpenAI-compatible TTS endpoint" reads as "The OpenAI-compatible
TTS endpoint" once it is out of Go's namespace.
Co-authored-by: Hanzo Dev <[email protected]>
381 lines
12 KiB
Go
381 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 `X.Router("path", &pkg.Ctrl{}, "VERB:Handler;…")` whose
|
|
// path and spec are literals, sorted by (path, method) so the output is stable.
|
|
//
|
|
// 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
|
|
}
|
|
sel, ok := call.Fun.(*ast.SelectorExpr)
|
|
if !ok || sel.Sel.Name != "Router" {
|
|
return true
|
|
}
|
|
path, ok := literal(call.Args[0])
|
|
if !ok {
|
|
return true
|
|
}
|
|
spec, ok := literal(call.Args[2])
|
|
if !ok {
|
|
return true
|
|
}
|
|
ctrl := controllerName(call.Args[1])
|
|
if ctrl == "" {
|
|
return true
|
|
}
|
|
for _, pair := range strings.Split(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
|
|
}
|
|
|
|
// controllerName is the type name in `&controllers.ApiController{}`.
|
|
func controllerName(e ast.Expr) string {
|
|
unary, ok := e.(*ast.UnaryExpr)
|
|
if !ok || unary.Op != token.AND {
|
|
return ""
|
|
}
|
|
comp, ok := unary.X.(*ast.CompositeLit)
|
|
if !ok {
|
|
return ""
|
|
}
|
|
switch t := comp.Type.(type) {
|
|
case *ast.SelectorExpr:
|
|
return t.Sel.Name
|
|
case *ast.Ident:
|
|
return t.Name
|
|
}
|
|
return ""
|
|
}
|
|
|
|
// 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
|
|
}
|