@ihelpee/prumo-plugin-go-gin 0.0.0-stage → 0.9.0

package/go-extractor/cmd/prumo-go-extractor/main.go

@@ -0,0 +1,596 @@
+// prumo-go-extractor — fatos de AST Go em JSON canônico v1.
+//
+// Este programa é PARSER, não implementador da lei (spec
+// docs/especificacao-prumo-go-gin.md §4.2): ele serializa fatos sintáticos
+// e nunca decide "isto é violação?". A decisão vive 100% no core Node.
+//
+// R1.1: apenas stdlib Go. Qualquer import externo aqui é falha de build.
+// R1.2: nunca executa o código analisado; apenas parser.ParseFile — parse
+// puramente sintático, sem go build, sem go list, sem rede.
+package main
+
+import (
+	"encoding/json"
+	"flag"
+	"fmt"
+	"go/ast"
+	"go/format"
+	"go/parser"
+	"go/token"
+	"os"
+	"path/filepath"
+	"reflect"
+	"strconv"
+	"strings"
+)
+
+// ---------------------------------------------------------------------------
+// Contrato JSON v1 (spec §1.4) — congelado.
+// ---------------------------------------------------------------------------
+
+type ImportInfo struct {
+	Path  string `json:"path"`
+	Alias string `json:"alias"`
+	Line  int    `json:"line"`
+}
+
+type EngineRoot struct {
+	Name string `json:"name"`
+	Line int    `json:"line"`
+}
+
+type RouteInfo struct {
+	Method       string   `json:"method"`
+	Path         string   `json:"path"`
+	Handler      string   `json:"handler"`
+	Receiver     string   `json:"receiver"`
+	InlineGuards []string `json:"inlineGuards"`
+	Line         int      `json:"line"`
+}
+
+type GroupDef struct {
+	Var    string   `json:"var"`
+	Parent string   `json:"parent"`
+	Path   string   `json:"path"`
+	Guards []string `json:"guards"`
+	Line   int      `json:"line"`
+}
+
+type UseCall struct {
+	Receiver string   `json:"receiver"`
+	Guards   []string `json:"guards"`
+	Line     int      `json:"line"`
+}
+
+type BindingInfo struct {
+	Func    string `json:"func"`
+	ArgExpr string `json:"argExpr"`
+	VarName string `json:"varName"`
+	Line    int    `json:"line"`
+}
+
+type FieldInfo struct {
+	Name       string `json:"name"`
+	Type       string `json:"type"`
+	BindingTag string `json:"bindingTag"`
+	HasBinding bool   `json:"hasBinding"`
+}
+
+type StructInfo struct {
+	Name   string      `json:"name"`
+	Line   int         `json:"line"`
+	Fields []FieldInfo `json:"fields"`
+}
+
+type VarType struct {
+	Var  string `json:"var"`
+	Type string `json:"type"`
+	Line int    `json:"line"`
+}
+
+type ErrSite struct {
+	Expr string `json:"expr"`
+	Line int    `json:"line"`
+}
+
+type ErrorHandling struct {
+	ExplicitDiscards  []ErrSite `json:"explicitDiscards"`
+	UncheckedErrCalls []ErrSite `json:"uncheckedErrCalls"`
+}
+
+type FileModel struct {
+	Path           string         `json:"path"`
+	Package        string         `json:"package"`
+	IsTest         bool           `json:"isTest"`
+	IsInternal     bool           `json:"isInternal"`
+	Imports        []ImportInfo   `json:"imports"`
+	DynamicImports []string       `json:"dynamicImports"`
+	EngineRoots    []EngineRoot   `json:"engineRoots"`
+	Routes         []RouteInfo    `json:"routes"`
+	GroupDefs      []GroupDef     `json:"groupDefs"`
+	UseCalls       []UseCall      `json:"useCalls"`
+	Bindings       []BindingInfo  `json:"bindings"`
+	Structs        []StructInfo   `json:"structs"`
+	VarTypes       []VarType      `json:"varTypes"`
+	UsesErr        bool           `json:"usesErr"`
+	// Fatos p/ heurística R3.8 (a decisão é do core): nomes das funções
+	// chamadas cujo resultado foi atribuído a uma variável de erro
+	// (`err := f()`, `x, err := f()`) — "esta chamada já aparece com err
+	// neste arquivo".
+	CheckedCallees []string       `json:"checkedCallees"`
+	ErrorHandling  ErrorHandling  `json:"errorHandling"`
+	// R1.3: arquivo com erro de parse não derruba o run.
+	Error string `json:"error,omitempty"`
+}
+
+type Model struct {
+	Version int         `json:"version"`
+	Module  *string     `json:"module"`
+	Files   []FileModel `json:"files"`
+}
+
+// ---------------------------------------------------------------------------
+// Léxicos de reconhecimento (fatos sintáticos; a LEI dos símbolos é do core)
+// ---------------------------------------------------------------------------
+
+var routeMethods = map[string]string{
+	"GET":     "GET",
+	"POST":    "POST",
+	"PUT":     "PUT",
+	"PATCH":   "PATCH",
+	"DELETE":  "DELETE",
+	"HEAD":    "HEAD",
+	"OPTIONS": "OPTIONS",
+	"Any":     "ANY",
+}
+
+var bindFuncs = map[string]bool{
+	"ShouldBindJSON": true, "BindJSON": true,
+	"ShouldBind": true, "Bind": true,
+	"ShouldBindWith": true, "BindWith": true,
+	"ShouldBindQuery": true, "BindQuery": true,
+	"ShouldBindQueryWith": true, "BindQueryWith": true,
+	"ShouldBindUri": true, "BindUri": true,
+	"ShouldBindUriWith": true, "BindUriWith": true,
+	"ShouldBindHeader": true, "BindHeader": true,
+	"ShouldBindForm": true, "BindForm": true,
+	"ShouldBindYAML": true, "BindYAML": true,
+	"ShouldBindXML": true, "BindXML": true,
+	"ShouldBindMsgPack": true, "BindMsgPack": true,
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+func exprText(fset *token.FileSet, n ast.Node) string {
+	var sb strings.Builder
+	if err := format.Node(&sb, fset, n); err != nil {
+		return ""
+	}
+	return sb.String()
+}
+
+// callName extrai o nome canônico de um guard/handler: Auth -> "Auth",
+// gin.Recovery -> "gin.Recovery", Auth("realm") -> "Auth".
+func callName(e ast.Expr) string {
+	switch v := e.(type) {
+	case *ast.Ident:
+		return v.Name
+	case *ast.SelectorExpr:
+		return callName(v.X) + "." + v.Sel.Name
+	case *ast.CallExpr:
+		return callName(v.Fun)
+	case *ast.IndexExpr:
+		return callName(v.X)
+	case *ast.IndexListExpr:
+		return callName(v.X)
+	case *ast.ParenExpr:
+		return callName(v.X)
+	}
+	return ""
+}
+
+func stringLit(e ast.Expr) (string, bool) {
+	lit, ok := e.(*ast.BasicLit)
+	if !ok || lit.Kind != token.STRING {
+		return "", false
+	}
+	s, err := strconv.Unquote(lit.Value)
+	if err != nil {
+		return "", false
+	}
+	return s, true
+}
+
+func isIdent(e ast.Expr, name string) bool {
+	id, ok := e.(*ast.Ident)
+	return ok && id.Name == name
+}
+
+// selectorCall reconhece `X.Sel(args...)` e retorna (X, args).
+func selectorCall(call *ast.CallExpr, sel string) (ast.Expr, []ast.Expr, bool) {
+	se, ok := call.Fun.(*ast.SelectorExpr)
+	if !ok || se.Sel.Name != sel {
+		return nil, nil, false
+	}
+	return se.X, call.Args, true
+}
+
+// ---------------------------------------------------------------------------
+// go.mod do alvo: apenas o module path (ler go.mod NÃO é resolver deps).
+// ---------------------------------------------------------------------------
+
+func modulePath(root string) *string {
+	data, err := os.ReadFile(filepath.Join(root, "go.mod"))
+	if err != nil {
+		return nil
+	}
+	for _, line := range strings.Split(string(data), "\n") {
+		trimmed := strings.TrimSpace(line)
+		if rest, ok := strings.CutPrefix(trimmed, "module "); ok {
+			mod := strings.TrimSpace(strings.SplitN(rest, "//", 2)[0])
+			mod = strings.Trim(mod, "\"")
+			if mod != "" {
+				return &mod
+			}
+		}
+	}
+	return nil
+}
+
+// ---------------------------------------------------------------------------
+// Extração por arquivo
+// ---------------------------------------------------------------------------
+
+func extractFile(root, rel string) FileModel {
+	fm := FileModel{
+		Path:           rel,
+		IsTest:         strings.HasSuffix(rel, "_test.go"),
+		IsInternal:     strings.Contains("/"+filepath.ToSlash(rel), "/internal/"),
+		Imports:        []ImportInfo{},
+		DynamicImports: []string{},
+		EngineRoots:    []EngineRoot{},
+		Routes:         []RouteInfo{},
+		GroupDefs:      []GroupDef{},
+		UseCalls:       []UseCall{},
+		Bindings:       []BindingInfo{},
+		Structs:        []StructInfo{},
+		VarTypes:       []VarType{},
+		CheckedCallees: []string{},
+		ErrorHandling:  ErrorHandling{ExplicitDiscards: []ErrSite{}, UncheckedErrCalls: []ErrSite{}},
+	}
+
+	fset := token.NewFileSet()
+	af, err := parser.ParseFile(fset, filepath.Join(root, rel), nil, parser.SkipObjectResolution)
+	if err != nil {
+		fm.Error = "parse"
+		return fm
+	}
+	fm.Package = af.Name.Name
+
+	ast.Inspect(af, func(n ast.Node) bool {
+		switch node := n.(type) {
+
+		// imports (R2.1–R2.4: alias, dot e blank são todos arestas)
+		case *ast.GenDecl:
+			if node.Tok == token.IMPORT {
+				for _, spec := range node.Specs {
+					is, ok := spec.(*ast.ImportSpec)
+					if !ok {
+						continue
+					}
+					path, ok := stringLit(is.Path)
+					if !ok {
+						continue
+					}
+					alias := ""
+					if is.Name != nil {
+						alias = is.Name.Name // inclui "." e "_"
+					}
+					fm.Imports = append(fm.Imports, ImportInfo{
+						Path: path, Alias: alias, Line: fset.Position(is.Pos()).Line,
+					})
+				}
+			}
+			if node.Tok == token.TYPE {
+				for _, spec := range node.Specs {
+					ts, ok := spec.(*ast.TypeSpec)
+					if !ok {
+						continue
+					}
+					st, ok := ts.Type.(*ast.StructType)
+					if !ok {
+						continue
+					}
+					fm.Structs = append(fm.Structs, extractStruct(fset, ts, st))
+				}
+			}
+			if node.Tok == token.VAR {
+				for _, spec := range node.Specs {
+					vs, ok := spec.(*ast.ValueSpec)
+					if !ok || vs.Type == nil {
+						continue
+					}
+					ty := exprText(fset, vs.Type)
+					for _, name := range vs.Names {
+						if name.Name == "_" {
+							continue
+						}
+						fm.VarTypes = append(fm.VarTypes, VarType{
+							Var: name.Name, Type: ty, Line: fset.Position(name.Pos()).Line,
+						})
+					}
+				}
+			}
+
+		// engineRoots: r := gin.Default() / r := gin.New()
+		case *ast.AssignStmt:
+			handleAssign(fset, node, &fm)
+
+		case *ast.CallExpr:
+			handleCall(fset, node, &fm)
+
+		case *ast.FuncDecl:
+			if node.Type.Params != nil {
+				for _, p := range node.Type.Params.List {
+					ty := exprText(fset, p.Type)
+					for _, name := range p.Names {
+						if name.Name == "_" {
+							continue
+						}
+						fm.VarTypes = append(fm.VarTypes, VarType{
+							Var: name.Name, Type: ty, Line: fset.Position(name.Pos()).Line,
+						})
+					}
+				}
+			}
+
+		case *ast.Ident:
+			if node.Name == "err" {
+				fm.UsesErr = true
+			}
+		}
+		return true
+	})
+
+	return fm
+}
+
+func extractStruct(fset *token.FileSet, ts *ast.TypeSpec, st *ast.StructType) StructInfo {
+	si := StructInfo{Name: ts.Name.Name, Line: fset.Position(ts.Pos()).Line, Fields: []FieldInfo{}}
+	if st.Fields == nil {
+		return si
+	}
+	for _, f := range st.Fields.List {
+		ty := exprText(fset, f.Type)
+		tag := ""
+		hasBinding := false
+		if f.Tag != nil {
+			if raw, err := strconv.Unquote(f.Tag.Value); err == nil {
+				tag = strings.TrimSpace(reflect.StructTag(raw).Get("binding"))
+				hasBinding = tag != ""
+			}
+		}
+		if len(f.Names) == 0 { // campo embutido
+			name := ty
+			if idx := strings.LastIndexByte(name, '.'); idx >= 0 {
+				name = name[idx+1:]
+			}
+			name = strings.TrimPrefix(name, "*")
+			si.Fields = append(si.Fields, FieldInfo{Name: name, Type: ty, BindingTag: tag, HasBinding: hasBinding})
+			continue
+		}
+		for _, n := range f.Names {
+			si.Fields = append(si.Fields, FieldInfo{Name: n.Name, Type: ty, BindingTag: tag, HasBinding: hasBinding})
+		}
+	}
+	return si
+}
+
+func handleAssign(fset *token.FileSet, as *ast.AssignStmt, fm *FileModel) {
+	line := fset.Position(as.Pos()).Line
+
+	// engineRoots / groupDefs / varTypes por :=
+	if as.Tok == token.DEFINE && len(as.Lhs) == 1 && len(as.Rhs) == 1 {
+		if id, ok := as.Lhs[0].(*ast.Ident); ok && id.Name != "_" {
+			if call, ok := as.Rhs[0].(*ast.CallExpr); ok {
+				// r := gin.Default() | gin.New()
+				if x, _, ok := selectorCall(call, "Default"); ok && isIdent(x, "gin") {
+					fm.EngineRoots = append(fm.EngineRoots, EngineRoot{Name: id.Name, Line: line})
+				}
+				if x, _, ok := selectorCall(call, "New"); ok && isIdent(x, "gin") {
+					fm.EngineRoots = append(fm.EngineRoots, EngineRoot{Name: id.Name, Line: line})
+				}
+				// api := r.Group("/api", Middleware())
+				if parent, args, ok := selectorCall(call, "Group"); ok && len(args) >= 1 {
+					path, _ := stringLit(args[0])
+					guards := []string{}
+					for _, a := range args[1:] {
+						if g := callName(a); g != "" {
+							guards = append(guards, g)
+						}
+					}
+					fm.GroupDefs = append(fm.GroupDefs, GroupDef{
+						Var: id.Name, Parent: exprText(fset, parent), Path: path, Guards: guards, Line: line,
+					})
+				}
+			}
+			// req := T{} / req := &T{}
+			switch rhs := as.Rhs[0].(type) {
+			case *ast.CompositeLit:
+				if rhs.Type != nil {
+					fm.VarTypes = append(fm.VarTypes, VarType{Var: id.Name, Type: exprText(fset, rhs.Type), Line: line})
+				}
+			case *ast.UnaryExpr:
+				if rhs.Op == token.AND {
+					if cl, ok := rhs.X.(*ast.CompositeLit); ok && cl.Type != nil {
+						fm.VarTypes = append(fm.VarTypes, VarType{Var: id.Name, Type: exprText(fset, cl.Type), Line: line})
+					}
+				}
+			}
+		}
+	}
+
+	// Fato R3.8: `err := f()` / `x, err := f()` — a chamada f aparece com
+	// err neste arquivo. O core usa isso para reduzir falso-positivo do
+	// sub-caso heurístico; a decisão de violar é do core.
+	for _, l := range as.Lhs {
+		if id, ok := l.(*ast.Ident); ok && (id.Name == "err" || strings.HasPrefix(id.Name, "err")) {
+			if call, ok := as.Rhs[0].(*ast.CallExpr); ok {
+				if n := callName(call.Fun); n != "" {
+					fm.CheckedCallees = append(fm.CheckedCallees, n)
+				}
+			}
+			break
+		}
+	}
+
+	// R3.7 (fatos): descarte explícito — `_ = err`, `_ = f()`, `x, _ := f()`.
+	hasBlank := false
+	for _, l := range as.Lhs {
+		if isIdent(l, "_") {
+			hasBlank = true
+			break
+		}
+	}
+	if hasBlank {
+		discard := false
+		if len(as.Lhs) > 1 {
+			_, isCall := as.Rhs[0].(*ast.CallExpr)
+			discard = isCall
+		} else if len(as.Lhs) == 1 {
+			switch r := as.Rhs[0].(type) {
+			case *ast.CallExpr:
+				discard = true
+			case *ast.Ident:
+				discard = r.Name == "err" || strings.HasPrefix(r.Name, "err")
+			}
+		}
+		if discard {
+			fm.ErrorHandling.ExplicitDiscards = append(fm.ErrorHandling.ExplicitDiscards, ErrSite{
+				Expr: exprText(fset, as), Line: line,
+			})
+		}
+	}
+}
+
+func handleCall(fset *token.FileSet, call *ast.CallExpr, fm *FileModel) {
+	line := fset.Position(call.Pos()).Line
+
+	// rotas Gin: r.POST("/x", Guard(), Handler)
+	if se, ok := call.Fun.(*ast.SelectorExpr); ok {
+		method, isRoute := routeMethods[se.Sel.Name]
+		if isRoute && len(call.Args) >= 2 {
+			path, okPath := stringLit(call.Args[0])
+			if okPath {
+				handler := ""
+				if len(call.Args) >= 1 {
+					handler = callName(call.Args[len(call.Args)-1])
+				}
+				guards := []string{}
+				for _, a := range call.Args[1 : len(call.Args)-1] {
+					if g := callName(a); g != "" {
+						guards = append(guards, g)
+					}
+				}
+				fm.Routes = append(fm.Routes, RouteInfo{
+					Method: method, Path: path, Handler: handler,
+					Receiver: exprText(fset, se.X), InlineGuards: guards, Line: line,
+				})
+			}
+		}
+
+		// r.Use(A(), B())
+		if recv, args, ok := selectorCall(call, "Use"); ok {
+			guards := []string{}
+			for _, a := range args {
+				if g := callName(a); g != "" {
+					guards = append(guards, g)
+				}
+			}
+			fm.UseCalls = append(fm.UseCalls, UseCall{Receiver: exprText(fset, recv), Guards: guards, Line: line})
+		}
+
+		// c.ShouldBindJSON(&req)
+		if bindFuncs[se.Sel.Name] && len(call.Args) >= 1 {
+			argExpr := exprText(fset, call.Args[0])
+			varName := strings.TrimPrefix(argExpr, "&")
+			fm.Bindings = append(fm.Bindings, BindingInfo{
+				Func: se.Sel.Name, ArgExpr: argExpr, VarName: varName, Line: line,
+			})
+		}
+	}
+
+}
+
+func main() {
+	root := flag.String("root", ".", "raiz do projeto-alvo")
+	filesFlag := flag.String("files", "", "caminhos relativos .go separados por vírgula")
+	flag.Parse()
+
+	// R1.1: stdlib-only. go.mod sem require é a prova mecânica.
+	model := Model{Version: 1, Module: modulePath(*root), Files: []FileModel{}}
+
+	var rels []string
+	for _, f := range strings.Split(*filesFlag, ",") {
+		f = strings.TrimSpace(f)
+		if f != "" {
+			rels = append(rels, filepath.FromSlash(f))
+		}
+	}
+
+	for _, rel := range rels {
+		model.Files = append(model.Files, extractFile(*root, rel))
+	}
+
+	// ExprStmt puro: precisa do contexto de statement, então uma passada
+	// dedicada por arquivo após o Inspect principal seria redundante — o
+	// Inspect acima não vê o wrapper ExprStmt. Refazemos com DeclFiles.
+	for i, rel := range rels {
+		if model.Files[i].Error != "" {
+			continue
+		}
+		fset := token.NewFileSet()
+		af, err := parser.ParseFile(fset, filepath.Join(*root, rel), nil, parser.SkipObjectResolution)
+		if err != nil {
+			continue
+		}
+		for _, decl := range af.Decls {
+			fd, ok := decl.(*ast.FuncDecl)
+			if !ok || fd.Body == nil {
+				continue
+			}
+			for _, stmt := range fd.Body.List {
+				es, ok := stmt.(*ast.ExprStmt)
+				if !ok {
+					continue
+				}
+				call, isCall := es.X.(*ast.CallExpr)
+				if !isCall {
+					continue
+				}
+				// Fato sintático: registro de rota/middleware Gin nunca é
+				// candidato a "retorno de error ignorado" (retorna *Router).
+				if se, ok := call.Fun.(*ast.SelectorExpr); ok {
+					if _, isRoute := routeMethods[se.Sel.Name]; isRoute {
+						continue
+					}
+					if se.Sel.Name == "Use" || se.Sel.Name == "Group" || se.Sel.Name == "Static" || se.Sel.Name == "StaticFile" || se.Sel.Name == "StaticFS" || se.Sel.Name == "NoRoute" || se.Sel.Name == "NoMethod" {
+						continue
+					}
+				}
+				model.Files[i].ErrorHandling.UncheckedErrCalls = append(
+					model.Files[i].ErrorHandling.UncheckedErrCalls,
+					ErrSite{Expr: exprText(fset, es.X), Line: fset.Position(es.Pos()).Line},
+				)
+			}
+		}
+	}
+
+	enc := json.NewEncoder(os.Stdout)
+	if err := enc.Encode(model); err != nil {
+		fmt.Fprintln(os.Stderr, "encode:", err)
+		os.Exit(1)
+	}
+}

package/go-extractor/go.mod

@@ -0,0 +1,3 @@
+module ihelpee.dev/prumo-go-extractor
+
+go 1.21

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@ihelpee/prumo-plugin-go-gin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.9.0",
+  "type": "module",
+  "description": "Go/Gin plugin for Prumo: mutation route guards (inline/Group.Use/Engine.Use), error-handling enforcement, payload binding validation, and Go-native oracle isolation.",
+  "author": "Alex Gotardi <alexgotardi@gmail.com>",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "go-extractor",
+    "package.json",
+    "README.md"
+  ],
+  "sideEffects": false,
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ihelpee/prumo.git"
+  },
+  "engines": {
+    "node": ">=20.11",
+    "go": ">=1.21"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@ihelpee/prumo": "0.9.0"
+  }
 }