@descryy/adapter-go 0.4.1 → 0.5.1

package/goshapes/main.go

@@ -0,0 +1,596 @@
+// Command goshapes is descry-adapters' R3 evidence source for Go: real
+// type-checker output, not a heuristic. It loads a target Go module with
+// golang.org/x/tools/go/packages (which shells out to `go list`/the Go
+// toolchain already on the analysing machine), and for every function whose
+// signature matches a recognised HTTP-framework handler, walks the
+// function's own body — through go/types' resolved type information, not
+// syntax alone — to find which named struct type it decodes an inbound
+// request into and which it encodes as the response.
+//
+// That join (handler -> request/response struct) is exactly the capability
+// gap `descry-adapters`' prior investigation named: Go carries no written
+// annotation the way Python's Pydantic or Java's JSON libraries do, so
+// finding it requires tracing what a variable holds through a Decode/Bind or
+// Encode/JSON call — a data-flow fact only a type checker can state
+// honestly. Nothing here is invented when the evidence is ambiguous: more
+// than one candidate shape for one handler's request (or response) is
+// reported as unresolved rather than guessed, matching this project's
+// precision-over-recall rule.
+//
+// Output is one JSON object on stdout, always exit 0 (including on
+// failure — failure is a value in the JSON, `"ok": false`, not a process
+// exit code the caller has to distinguish from "the helper itself crashed").
+package main
+
+import (
+	"encoding/json"
+	"fmt"
+	"go/ast"
+	"go/token"
+	"go/types"
+	"os"
+	"reflect"
+	"strings"
+
+	"golang.org/x/tools/go/packages"
+)
+
+// --- Output contract ---------------------------------------------------
+//
+// Mirrors what `packages/adapter-go/src/go-types.ts` decodes. Keep the two
+// in lockstep by hand; there is no shared schema source between a Go program
+// and a TypeScript one.
+
+type shapeRef struct {
+	ImportPath string `json:"importPath"`
+	Name       string `json:"name"`
+}
+
+type field struct {
+	Name     string `json:"name"`
+	JSONName string `json:"jsonName,omitempty"`
+	Type     string `json:"type"`
+	Embedded bool   `json:"embedded,omitempty"`
+	Skip     bool   `json:"skip,omitempty"`
+}
+
+type structShape struct {
+	ImportPath string  `json:"importPath"`
+	Name       string  `json:"name"`
+	Fields     []field `json:"fields"`
+}
+
+type handler struct {
+	ImportPath string     `json:"importPath"`
+	Receiver   string     `json:"receiver,omitempty"`
+	FuncName   string     `json:"funcName"`
+	File       string     `json:"file"`
+	Line       int        `json:"line"`
+	Framework  string     `json:"framework"`
+	Request    *shapeRef  `json:"request,omitempty"`
+	Response   *shapeRef  `json:"response,omitempty"`
+}
+
+type output struct {
+	OK       bool          `json:"ok"`
+	Error    string        `json:"error,omitempty"`
+	Structs  []structShape `json:"structs"`
+	Handlers []handler     `json:"handlers"`
+}
+
+func main() {
+	out := run()
+	enc := json.NewEncoder(os.Stdout)
+	enc.SetEscapeHTML(false)
+	if err := enc.Encode(out); err != nil {
+		// Nothing left to report through — the JSON contract itself
+		// could not be written. Fail loudly on stderr; the TypeScript
+		// side treats a stdout that fails to parse as a failure of its
+		// own, but this at least explains why to a human reading logs.
+		fmt.Fprintln(os.Stderr, "goshapes: failed to encode output:", err)
+		os.Exit(1)
+	}
+}
+
+// run never panics past this point — a bug in this file must degrade to a
+// disclosed `ok: false`, never a hung or garbled process the caller cannot
+// interpret (the project's "honest degradation" rule applies to this helper
+// exactly as it applies to the TypeScript adapter that calls it).
+func run() (result output) {
+	defer func() {
+		if r := recover(); r != nil {
+			result = output{OK: false, Error: fmt.Sprintf("panic: %v", r)}
+		}
+	}()
+
+	if len(os.Args) < 2 {
+		return output{OK: false, Error: "usage: goshapes <target-module-directory>"}
+	}
+	dir := os.Args[1]
+
+	cfg := &packages.Config{
+		Dir: dir,
+		Mode: packages.NeedName | packages.NeedFiles | packages.NeedCompiledGoFiles |
+			packages.NeedImports | packages.NeedTypes | packages.NeedTypesInfo |
+			packages.NeedSyntax | packages.NeedModule,
+		Tests: false,
+	}
+	pkgs, err := packages.Load(cfg, "./...")
+	if err != nil {
+		return output{OK: false, Error: "packages.Load: " + err.Error()}
+	}
+	if len(pkgs) == 0 {
+		return output{OK: false, Error: "no Go packages found under " + dir}
+	}
+
+	// Load errors are per-package (a broken sibling package must not blind
+	// this run to every package that DID load — the same "one file's gap,
+	// not the run's" standard `adapter-go`'s own TypeScript holds for a
+	// tree-walk throw). Collected for disclosure only; loading continues.
+	var loadErrors []string
+	packages.Visit(pkgs, nil, func(p *packages.Package) {
+		for _, e := range p.Errors {
+			loadErrors = append(loadErrors, p.PkgPath+": "+e.Error())
+		}
+	})
+
+	extractor := newExtractor()
+	for _, pkg := range pkgs {
+		if pkg.TypesInfo == nil || pkg.Types == nil {
+			continue
+		}
+		extractor.visitPackage(pkg)
+	}
+
+	structs, handlers := extractor.finish()
+	out := output{OK: true, Structs: structs, Handlers: handlers}
+	if len(loadErrors) > 0 && len(structs) == 0 && len(handlers) == 0 {
+		// Every package that mattered failed to load and nothing else
+		// stepped in — an honest failure, not a quiet empty result.
+		out = output{OK: false, Error: "no package loaded cleanly: " + loadErrors[0]}
+	}
+	return out
+}
+
+// --- Framework recognition ----------------------------------------------
+//
+// Deliberately the same closed set `packages/adapter-go/src/routes.ts`
+// already recognises syntactically (its `FRAMEWORKS` map's header explains
+// why a closed, auditable set is the right shape for this kind of table).
+// chi and gorilla/mux both register ordinary `func(http.ResponseWriter,
+// *http.Request)` handlers, so they need no entry of their own here — the
+// "net/http" signature check already covers them, exactly as it does in
+// `routes.ts`.
+
+const (
+	frameworkNetHTTP = "net/http"
+	frameworkGin     = "github.com/gin-gonic/gin"
+	frameworkEcho    = "github.com/labstack/echo"
+	frameworkEchoV4  = "github.com/labstack/echo/v4"
+	frameworkFiberV1 = "github.com/gofiber/fiber"
+	frameworkFiberV2 = "github.com/gofiber/fiber/v2"
+)
+
+// ctxParamOf reports the single-context-parameter frameworks' own parameter
+// object, when `sig` is shaped like that framework's handler. Returns nil
+// for anything else, including a signature with the right type in the wrong
+// position or arity — an exact match only, never a guess (the same "a
+// verb-shaped call is not a route" discipline `routes.ts` applies to
+// syntax, applied here to a checked signature).
+func ctxParamOf(sig *types.Signature, wantType string) *types.Var {
+	if sig.Params().Len() != 1 {
+		return nil
+	}
+	p := sig.Params().At(0)
+	if typeString(p.Type()) != wantType {
+		return nil
+	}
+	return p
+}
+
+// handlerShapeOf classifies one function's signature against every
+// recognised framework, returning the framework name and the request
+// object(s) whose method calls are this handler's own (for gin/echo/fiber,
+// the single context parameter; for net/http-shaped handlers, both the
+// ResponseWriter and the *Request are candidate receivers, but neither
+// carries bind/JSON methods this reader looks for beyond the request body
+// itself, read directly).
+func handlerShapeOf(sig *types.Signature) (framework string, ctx *types.Var, ok bool) {
+	if sig.Params().Len() == 2 {
+		w := sig.Params().At(0)
+		r := sig.Params().At(1)
+		if typeString(w.Type()) == "net/http.ResponseWriter" && typeString(r.Type()) == "*net/http.Request" {
+			return frameworkNetHTTP, nil, true
+		}
+	}
+	if v := ctxParamOf(sig, "*github.com/gin-gonic/gin.Context"); v != nil {
+		return frameworkGin, v, true
+	}
+	if v := ctxParamOf(sig, "github.com/labstack/echo.Context"); v != nil {
+		return frameworkEcho, v, true
+	}
+	if v := ctxParamOf(sig, "github.com/labstack/echo/v4.Context"); v != nil {
+		return frameworkEchoV4, v, true
+	}
+	if v := ctxParamOf(sig, "*github.com/gofiber/fiber.Ctx"); v != nil {
+		return frameworkFiberV1, v, true
+	}
+	if v := ctxParamOf(sig, "*github.com/gofiber/fiber/v2.Ctx"); v != nil {
+		return frameworkFiberV2, v, true
+	}
+	return "", nil, false
+}
+
+// typeString renders a type the same, stable way everywhere in this file —
+// `types.TypeString` with no qualifier function, so every named type prints
+// fully qualified by its import path. That is what makes it safe to compare
+// against a literal like "*net/http.Request" instead of resolving the
+// framework's own package object first.
+func typeString(t types.Type) string {
+	return types.TypeString(t, nil)
+}
+
+// --- Struct shape extraction ---------------------------------------------
+
+// namedStructOf reports the declared struct type's own field list, `nil`
+// when `t` (after stripping at most one pointer) is not a named struct.
+// Reading through `types.Struct` rather than the AST's field list is the
+// entire reason this helper exists rather than a syntactic reader: it is
+// go/types that flattens an anonymous embed and resolves a field's type
+// across package boundaries, both of which `adapter-go`'s own tree-sitter
+// reader (`GoType.fields`, `parse.ts`) discloses it cannot do.
+func namedStructOf(t types.Type) (named *types.Named, st *types.Struct, ok bool) {
+	if ptr, isPtr := t.(*types.Pointer); isPtr {
+		t = ptr.Elem()
+	}
+	n, isNamed := t.(*types.Named)
+	if !isNamed {
+		return nil, nil, false
+	}
+	s, isStruct := n.Underlying().(*types.Struct)
+	if !isStruct {
+		return nil, nil, false
+	}
+	return n, s, true
+}
+
+func shapeRefOf(named *types.Named) shapeRef {
+	pkg := named.Obj().Pkg()
+	importPath := ""
+	if pkg != nil {
+		importPath = pkg.Path()
+	}
+	return shapeRef{ImportPath: importPath, Name: named.Obj().Name()}
+}
+
+func fieldsOf(st *types.Struct) []field {
+	out := make([]field, 0, st.NumFields())
+	for i := 0; i < st.NumFields(); i++ {
+		v := st.Field(i)
+		f := field{Name: v.Name(), Type: typeString(v.Type()), Embedded: v.Embedded()}
+		tag := parseJSONTag(st.Tag(i))
+		if tag == "-" {
+			f.Skip = true
+		} else if tag != "" {
+			f.JSONName = tag
+		}
+		out = append(out, f)
+	}
+	return out
+}
+
+// parseJSONTag reads only the `json:"..."` tag's name segment — omitempty
+// and the other comma-separated options are encoding/json's own concern,
+// not identity this adapter reports. `""` when there is no json tag at all,
+// distinct from `"-"` (explicitly excluded from the wire shape).
+// `reflect.StructTag` is the standard library's own tag parser — this file
+// does not reimplement Go's tag grammar.
+func parseJSONTag(tag string) string {
+	raw := reflect.StructTag(tag).Get("json")
+	if raw == "" {
+		return ""
+	}
+	if comma := strings.IndexByte(raw, ','); comma != -1 {
+		return raw[:comma]
+	}
+	return raw
+}
+
+// --- Handler body walk -----------------------------------------------------
+
+// candidate is one shape this reader found written into a handler's body,
+// with enough left to decide ambiguity — more than one DISTINCT candidate
+// for one role (request or response) is refused, not guessed.
+type candidate struct {
+	named *types.Named
+	st    *types.Struct
+}
+
+type extractor struct {
+	// pkgPath::Name -> the struct, recorded only when a handler actually
+	// names it — matches this project's "promote, don't dump" precision
+	// stance the way `adapter-python`'s DTO promotion only ever emits a
+	// class that some route's own contract names.
+	wanted   map[string]structShape
+	handlers []handler
+}
+
+func newExtractor() *extractor {
+	return &extractor{wanted: map[string]structShape{}}
+}
+
+func (e *extractor) finish() ([]structShape, []handler) {
+	structs := make([]structShape, 0, len(e.wanted))
+	for _, s := range e.wanted {
+		structs = append(structs, s)
+	}
+	return structs, e.handlers
+}
+
+func (e *extractor) remember(named *types.Named, st *types.Struct) shapeRef {
+	ref := shapeRefOf(named)
+	key := ref.ImportPath + "." + ref.Name
+	if _, ok := e.wanted[key]; !ok {
+		e.wanted[key] = structShape{ImportPath: ref.ImportPath, Name: ref.Name, Fields: fieldsOf(st)}
+	}
+	return ref
+}
+
+func (e *extractor) visitPackage(pkg *packages.Package) {
+	fset := pkg.Fset
+	info := pkg.TypesInfo
+	for _, file := range pkg.Syntax {
+		for _, decl := range file.Decls {
+			fn, isFunc := decl.(*ast.FuncDecl)
+			if !isFunc || fn.Body == nil {
+				continue
+			}
+			obj, isObj := info.Defs[fn.Name].(*types.Func)
+			if !isObj {
+				continue
+			}
+			sig, isSig := obj.Type().(*types.Signature)
+			if !isSig {
+				continue
+			}
+			framework, ctx, matched := handlerShapeOf(sig)
+			if !matched {
+				continue
+			}
+
+			receiver := ""
+			if fn.Recv != nil && len(fn.Recv.List) == 1 {
+				receiver = receiverTypeName(fn.Recv.List[0].Type)
+			}
+
+			reqCandidates, respCandidates := e.bodyShapesOf(fn.Body, info, ctx, framework)
+			req := e.resolveOne(reqCandidates)
+			resp := e.resolveOne(respCandidates)
+			if req == nil && resp == nil {
+				// A confirmed handler signature with no discernible
+				// request/response shape is real but out of this
+				// helper's scope — see the file header. Nothing to
+				// report; the TypeScript side gains nothing from a
+				// handler row that names no shape.
+				continue
+			}
+
+			pos := fset.Position(fn.Pos())
+			e.handlers = append(e.handlers, handler{
+				ImportPath: pkg.PkgPath,
+				Receiver:   receiver,
+				FuncName:   fn.Name.Name,
+				File:       pos.Filename,
+				Line:       pos.Line,
+				Framework:  framework,
+				Request:    req,
+				Response:   resp,
+			})
+		}
+	}
+}
+
+func receiverTypeName(expr ast.Expr) string {
+	if star, isStar := expr.(*ast.StarExpr); isStar {
+		expr = star.X
+	}
+	if ident, isIdent := expr.(*ast.Ident); isIdent {
+		return ident.Name
+	}
+	return ""
+}
+
+// resolveOne applies the ambiguity rule: zero candidates is `nil` (nothing
+// found, disclosed by simple absence); exactly one DISTINCT named type
+// across every candidate is that type; more than one distinct type is
+// `nil` too — refused, the same as zero, because this reader cannot say
+// which of them the caller meant and a wrong shape claim is worse than a
+// missing one (rule 2).
+func (e *extractor) resolveOne(candidates []candidate) *shapeRef {
+	if len(candidates) == 0 {
+		return nil
+	}
+	first := candidates[0]
+	firstRef := shapeRefOf(first.named)
+	for _, c := range candidates[1:] {
+		ref := shapeRefOf(c.named)
+		if ref != firstRef {
+			return nil
+		}
+	}
+	ref := e.remember(first.named, first.st)
+	return &ref
+}
+
+// bodyShapesOf walks one handler's body for the framework's own
+// decode/bind and encode/JSON idioms. `ctx` is the single context
+// parameter for gin/echo/fiber, `nil` for net/http (whose two parameters
+// are read straight off `info.Uses`, not through a shared receiver).
+func (e *extractor) bodyShapesOf(
+	body *ast.BlockStmt,
+	info *types.Info,
+	ctx *types.Var,
+	framework string,
+) (requests []candidate, responses []candidate) {
+	ast.Inspect(body, func(n ast.Node) bool {
+		call, isCall := n.(*ast.CallExpr)
+		if !isCall {
+			return true
+		}
+		sel, isSel := call.Fun.(*ast.SelectorExpr)
+		if !isSel {
+			return true
+		}
+		method := sel.Sel.Name
+
+		// `json.NewDecoder(r.Body).Decode(&x)` / `json.NewEncoder(w).Encode(x)`
+		// — the receiver is itself a call, so the method is read off the
+		// call's own resolved type rather than an identifier.
+		if method == "Decode" || method == "Encode" {
+			if isJSONDecoderOrEncoder(sel.X, info, method) {
+				if method == "Decode" && len(call.Args) == 1 {
+					if c, ok := candidateFromPointerArg(call.Args[0], info); ok {
+						requests = append(requests, c)
+					}
+				}
+				if method == "Encode" && len(call.Args) == 1 {
+					if c, ok := candidateFromValueArg(call.Args[0], info); ok {
+						responses = append(responses, c)
+					}
+				}
+			}
+			return true
+		}
+
+		// `json.Unmarshal(data, &x)` — a package-level call, not a method
+		// on a receiver this reader tracks; `sel.X` is the `json`
+		// identifier itself.
+		if method == "Unmarshal" && isPackageIdent(sel.X, info, "encoding/json") && len(call.Args) == 2 {
+			if c, ok := candidateFromPointerArg(call.Args[1], info); ok {
+				requests = append(requests, c)
+			}
+			return true
+		}
+
+		// Every remaining idiom is a method called on the handler's own
+		// context parameter — confirm the receiver really is that
+		// parameter (`info.Uses[recv] == ctx`) before trusting the
+		// method name at all. A same-named method on an unrelated value
+		// is not this framework's bind/JSON call.
+		if ctx == nil {
+			return true
+		}
+		recvIdent, isIdent := sel.X.(*ast.Ident)
+		if !isIdent || info.Uses[recvIdent] != ctx {
+			return true
+		}
+
+		switch framework {
+		case frameworkGin:
+			switch method {
+			case "BindJSON", "ShouldBindJSON", "Bind", "ShouldBind":
+				if len(call.Args) == 1 {
+					if c, ok := candidateFromPointerArg(call.Args[0], info); ok {
+						requests = append(requests, c)
+					}
+				}
+			case "JSON":
+				if len(call.Args) == 2 {
+					if c, ok := candidateFromValueArg(call.Args[1], info); ok {
+						responses = append(responses, c)
+					}
+				}
+			}
+		case frameworkEcho, frameworkEchoV4:
+			switch method {
+			case "Bind":
+				if len(call.Args) == 1 {
+					if c, ok := candidateFromPointerArg(call.Args[0], info); ok {
+						requests = append(requests, c)
+					}
+				}
+			case "JSON":
+				if len(call.Args) == 2 {
+					if c, ok := candidateFromValueArg(call.Args[1], info); ok {
+						responses = append(responses, c)
+					}
+				}
+			}
+		case frameworkFiberV1, frameworkFiberV2:
+			switch method {
+			case "BodyParser":
+				if len(call.Args) == 1 {
+					if c, ok := candidateFromPointerArg(call.Args[0], info); ok {
+						requests = append(requests, c)
+					}
+				}
+			case "JSON":
+				if len(call.Args) == 1 {
+					if c, ok := candidateFromValueArg(call.Args[0], info); ok {
+						responses = append(responses, c)
+					}
+				}
+			}
+		}
+		return true
+	})
+	return requests, responses
+}
+
+// isJSONDecoderOrEncoder reports whether `expr` (the receiver of a
+// `.Decode`/`.Encode` call) is itself a call to `json.NewDecoder`/
+// `json.NewEncoder` — resolved off the call's own result type
+// (`*encoding/json.Decoder` / `*encoding/json.Encoder`), which is a
+// stronger check than matching the source text and is exactly what a type
+// checker is for.
+func isJSONDecoderOrEncoder(expr ast.Expr, info *types.Info, method string) bool {
+	call, isCall := expr.(*ast.CallExpr)
+	if !isCall {
+		return false
+	}
+	t := info.TypeOf(call)
+	if t == nil {
+		return false
+	}
+	want := "*encoding/json.Decoder"
+	if method == "Encode" {
+		want = "*encoding/json.Encoder"
+	}
+	return typeString(t) == want
+}
+
+func isPackageIdent(expr ast.Expr, info *types.Info, importPath string) bool {
+	ident, isIdent := expr.(*ast.Ident)
+	if !isIdent {
+		return false
+	}
+	pkgName, isPkgName := info.Uses[ident].(*types.PkgName)
+	return isPkgName && pkgName.Imported().Path() == importPath
+}
+
+// candidateFromPointerArg reads `&x` — the shape every Decode/Bind idiom
+// this file recognises takes its target as. Anything else (a bare name
+// with no `&`, an expression) names no addressable local this reader
+// resolves a struct from, and is silently not a candidate rather than a
+// refusal: the surrounding call may still be a real Decode of something
+// this reader simply does not follow (a field of a struct, an interface
+// value), which is a recall gap, never a precision one.
+func candidateFromPointerArg(arg ast.Expr, info *types.Info) (candidate, bool) {
+	unary, isUnary := arg.(*ast.UnaryExpr)
+	if !isUnary || unary.Op != token.AND {
+		return candidate{}, false
+	}
+	return candidateFromValueArg(unary.X, info)
+}
+
+func candidateFromValueArg(arg ast.Expr, info *types.Info) (candidate, bool) {
+	t := info.TypeOf(arg)
+	if t == nil {
+		return candidate{}, false
+	}
+	named, st, ok := namedStructOf(t)
+	if !ok {
+		return candidate{}, false
+	}
+	return candidate{named: named, st: st}, true
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@descryy/adapter-go",
-  "version": "0.4.1",
+  "version": "0.5.1",
   "type": "module",
   "description": "Go adapter, breadth tier. One grammar and one rule set over the shared tree-sitter harness — the second language to use it, and the measurement of whether that harness was worth building.",
   "license": "UNLICENSED",
@@ -23,7 +23,8 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "goshapes"
   ],
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
@@ -34,11 +35,11 @@
     "build:assets": "node -e \"require('fs').copyFileSync(require.resolve('tree-sitter-go/tree-sitter-go.wasm'),'dist/tree-sitter-go.wasm')\""
   },
   "dependencies": {
-    "@descryy/adapter-common": "0.3.0",
-    "@descryy/adapter-sql": "0.4.1",
-    "@descryy/adapter-treesitter": "0.2.0",
-    "@descryy/ir": "0.7.0",
+    "@descryy/adapter-common": "0.3.1",
+    "@descryy/adapter-sql": "0.5.1",
+    "@descryy/adapter-treesitter": "0.2.1",
+    "@descryy/ir": "0.10.0",
     "tree-sitter-go": "0.25.0",
-    "@descryy/adapter-openapi": "0.4.1"
+    "@descryy/adapter-openapi": "0.5.1"
   }
 }