@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/core/apicontract/document.go

@@ -0,0 +1,269 @@
+package apicontract
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"strings"
+)
+
+const runtimeContractMediaType = "application/vnd.onex.runtime-contract+json;version=2"
+
+var openAPIHTTPMethods = map[string]struct{}{
+	"delete":  {},
+	"get":     {},
+	"head":    {},
+	"options": {},
+	"patch":   {},
+	"post":    {},
+	"put":     {},
+	"trace":   {},
+}
+
+// Metadata 描述当前服务内嵌的不可变 OpenAPI 制品。
+type Metadata struct {
+	Service        string
+	DisplayName    string
+	APIVersion     string
+	SHA256         string
+	OperationCount int
+}
+
+// Document 保存单个服务已校验的 OpenAPI 契约与精确运行时路由集合。
+type Document struct {
+	metadata        Metadata
+	json            []byte
+	routes          map[routeIdentity]struct{}
+	routeExclusions map[string]struct{}
+}
+
+type routeIdentity struct {
+	method string
+	path   string
+}
+
+type openAPIDocument struct {
+	OpenAPI           string                                `json:"openapi"`
+	JSONSchemaDialect string                                `json:"jsonSchemaDialect"`
+	Info              openAPIInfo                           `json:"info"`
+	Paths             map[string]map[string]json.RawMessage `json:"paths"`
+}
+
+type openAPIInfo struct {
+	Version string `json:"version"`
+}
+
+type openAPIOperation struct {
+	OperationID       string `json:"operationId"`
+	DelegatedContract string `json:"x-onex-delegated-contract"`
+}
+
+type runtimeContract struct {
+	SchemaVersion        int                        `json:"schema_version"`
+	MediaType            string                     `json:"media_type"`
+	Service              string                     `json:"service"`
+	DisplayName          string                     `json:"display_name"`
+	APIVersion           string                     `json:"api_version"`
+	SHA256               string                     `json:"sha256"`
+	OperationCount       int                        `json:"operation_count"`
+	NativeOperationCount int                        `json:"native_operation_count"`
+	RouteExclusions      []string                   `json:"route_exclusions"`
+	DelegatedContracts   []runtimeDelegatedContract `json:"delegated_contracts"`
+	Routes               []runtimeRoute             `json:"routes"`
+}
+
+type runtimeDelegatedContract struct {
+	ID             string `json:"id"`
+	OperationCount int    `json:"operation_count"`
+}
+
+type runtimeRoute struct {
+	Method string `json:"method"`
+	Path   string `json:"path"`
+}
+
+// NewDocument 从生成制品构造只读服务契约。
+func NewDocument(specJSON, runtimeJSON []byte) (Document, error) {
+	var runtime runtimeContract
+	if err := json.Unmarshal(runtimeJSON, &runtime); err != nil {
+		return Document{}, fmt.Errorf("decode runtime contract: %w", err)
+	}
+	if err := validateRuntimeContract(runtime); err != nil {
+		return Document{}, err
+	}
+
+	digest := sha256.Sum256(specJSON)
+	if hex.EncodeToString(digest[:]) != runtime.SHA256 {
+		return Document{}, fmt.Errorf("OpenAPI artifact SHA-256 does not match runtime metadata")
+	}
+
+	var spec openAPIDocument
+	if err := json.Unmarshal(specJSON, &spec); err != nil {
+		return Document{}, fmt.Errorf("decode OpenAPI artifact: %w", err)
+	}
+	if spec.OpenAPI != "3.1.1" || spec.JSONSchemaDialect != "https://json-schema.org/draft/2020-12/schema" {
+		return Document{}, fmt.Errorf("OpenAPI artifact must use 3.1.1 and JSON Schema 2020-12")
+	}
+	if spec.Info.Version != runtime.APIVersion {
+		return Document{}, fmt.Errorf("OpenAPI version does not match runtime metadata")
+	}
+
+	document := Document{
+		metadata: Metadata{
+			Service:        runtime.Service,
+			DisplayName:    runtime.DisplayName,
+			APIVersion:     runtime.APIVersion,
+			SHA256:         runtime.SHA256,
+			OperationCount: runtime.OperationCount,
+		},
+		json:            append([]byte(nil), specJSON...),
+		routes:          make(map[routeIdentity]struct{}, runtime.OperationCount),
+		routeExclusions: make(map[string]struct{}, len(runtime.RouteExclusions)),
+	}
+	for _, path := range runtime.RouteExclusions {
+		canonicalPath := canonicalRoutePath(path)
+		if _, exists := document.routeExclusions[canonicalPath]; exists {
+			return Document{}, fmt.Errorf("runtime contract has duplicate route exclusion shape %s", canonicalPath)
+		}
+		document.routeExclusions[canonicalPath] = struct{}{}
+	}
+
+	delegatedCounts := make(map[string]int, len(runtime.DelegatedContracts))
+	for _, delegated := range runtime.DelegatedContracts {
+		delegatedCounts[delegated.ID] = 0
+	}
+	nativeOperationCount := 0
+	for path, pathItem := range spec.Paths {
+		for method, raw := range pathItem {
+			if _, ok := openAPIHTTPMethods[strings.ToLower(method)]; !ok {
+				continue
+			}
+			var operation openAPIOperation
+			if err := json.Unmarshal(raw, &operation); err != nil {
+				return Document{}, fmt.Errorf("decode %s %s operation: %w", strings.ToUpper(method), path, err)
+			}
+			if operation.OperationID == "" {
+				return Document{}, fmt.Errorf("%s %s has no operationId", strings.ToUpper(method), path)
+			}
+			identity := routeIdentity{method: strings.ToUpper(method), path: path}
+			if _, exists := document.routes[identity]; exists {
+				return Document{}, fmt.Errorf("OpenAPI artifact has duplicate route %s %s", identity.method, identity.path)
+			}
+			document.routes[identity] = struct{}{}
+			if operation.DelegatedContract == "" {
+				nativeOperationCount++
+				continue
+			}
+			if _, ok := delegatedCounts[operation.DelegatedContract]; !ok {
+				return Document{}, fmt.Errorf("%s %s uses undeclared delegated contract %s", identity.method, path, operation.DelegatedContract)
+			}
+			delegatedCounts[operation.DelegatedContract]++
+		}
+	}
+	if len(document.routes) != runtime.OperationCount {
+		return Document{}, fmt.Errorf("OpenAPI operation count %d does not match runtime metadata %d", len(document.routes), runtime.OperationCount)
+	}
+	if nativeOperationCount != runtime.NativeOperationCount {
+		return Document{}, fmt.Errorf("OpenAPI native operation count %d does not match runtime metadata %d", nativeOperationCount, runtime.NativeOperationCount)
+	}
+	for _, delegated := range runtime.DelegatedContracts {
+		if delegatedCounts[delegated.ID] != delegated.OperationCount {
+			return Document{}, fmt.Errorf("delegated contract %s operation count %d does not match runtime metadata %d", delegated.ID, delegatedCounts[delegated.ID], delegated.OperationCount)
+		}
+	}
+	for _, route := range runtime.Routes {
+		identity := routeIdentity{method: route.Method, path: route.Path}
+		if _, ok := document.routes[identity]; !ok {
+			return Document{}, fmt.Errorf("runtime contract route is absent from OpenAPI: %s %s", route.Method, route.Path)
+		}
+	}
+	if len(runtime.Routes) != len(document.routes) {
+		return Document{}, fmt.Errorf("runtime contract route count does not match OpenAPI")
+	}
+	return document, nil
+}
+
+// Metadata 返回不可变制品的身份信息。
+func (d Document) Metadata() Metadata {
+	return d.metadata
+}
+
+// JSON 返回 OpenAPI JSON 的防御性副本。
+func (d Document) JSON() []byte {
+	return append([]byte(nil), d.json...)
+}
+
+func validateRuntimeContract(runtime runtimeContract) error {
+	if runtime.SchemaVersion != 2 || runtime.MediaType != runtimeContractMediaType || runtime.Service == "" || runtime.DisplayName == "" || runtime.APIVersion == "" {
+		return fmt.Errorf("runtime contract identity is incomplete")
+	}
+	if _, err := hex.DecodeString(runtime.SHA256); err != nil || len(runtime.SHA256) != sha256.Size*2 || runtime.OperationCount < 1 || runtime.NativeOperationCount < 0 {
+		return fmt.Errorf("runtime contract artifact metadata is invalid")
+	}
+	if !sort.StringsAreSorted(runtime.RouteExclusions) {
+		return fmt.Errorf("runtime contract route exclusions must be sorted")
+	}
+	seenExclusions := make(map[string]struct{}, len(runtime.RouteExclusions))
+	for _, path := range runtime.RouteExclusions {
+		if !strings.HasPrefix(path, "/") || isBusinessPath(path) {
+			return fmt.Errorf("runtime contract has forbidden route exclusion %s", path)
+		}
+		if _, exists := seenExclusions[path]; exists {
+			return fmt.Errorf("runtime contract has duplicate route exclusion %s", path)
+		}
+		seenExclusions[path] = struct{}{}
+	}
+
+	seenDelegated := make(map[string]struct{}, len(runtime.DelegatedContracts))
+	delegatedIDs := make([]string, 0, len(runtime.DelegatedContracts))
+	delegatedOperationCount := 0
+	for _, delegated := range runtime.DelegatedContracts {
+		if delegated.ID == "" || delegated.OperationCount < 1 {
+			return fmt.Errorf("runtime delegated contract is invalid")
+		}
+		if _, exists := seenDelegated[delegated.ID]; exists {
+			return fmt.Errorf("runtime contract has duplicate delegated contract %s", delegated.ID)
+		}
+		seenDelegated[delegated.ID] = struct{}{}
+		delegatedIDs = append(delegatedIDs, delegated.ID)
+		delegatedOperationCount += delegated.OperationCount
+	}
+	if !sort.StringsAreSorted(delegatedIDs) {
+		return fmt.Errorf("runtime delegated contracts must be sorted")
+	}
+	if runtime.NativeOperationCount+delegatedOperationCount != runtime.OperationCount {
+		return fmt.Errorf("runtime operation counts are inconsistent")
+	}
+
+	seenRoutes := make(map[routeIdentity]struct{}, len(runtime.Routes))
+	previousKey := ""
+	for index, route := range runtime.Routes {
+		method := strings.ToLower(route.Method)
+		if route.Method != strings.ToUpper(route.Method) {
+			return fmt.Errorf("runtime route method must be uppercase: %s", route.Method)
+		}
+		if _, ok := openAPIHTTPMethods[method]; !ok || !strings.HasPrefix(route.Path, "/") || strings.Contains(route.Path, "*") {
+			return fmt.Errorf("runtime route is invalid: %s %s", route.Method, route.Path)
+		}
+		identity := routeIdentity{method: route.Method, path: route.Path}
+		if _, exists := seenRoutes[identity]; exists {
+			return fmt.Errorf("runtime contract has duplicate route %s %s", route.Method, route.Path)
+		}
+		seenRoutes[identity] = struct{}{}
+		key := route.Path + "\x00" + method
+		if index > 0 && key < previousKey {
+			return fmt.Errorf("runtime contract routes must be sorted")
+		}
+		previousKey = key
+	}
+	if len(runtime.Routes) != runtime.OperationCount {
+		return fmt.Errorf("runtime route count does not match operation count")
+	}
+	return nil
+}
+
+func isBusinessPath(path string) bool {
+	return strings.HasPrefix(path, "/api/") || strings.HasPrefix(path, "/admin/") || strings.HasPrefix(path, "/internal/")
+}

package/dist/resources/templates/go-backend/internal/core/apicontract/document_test.go

@@ -0,0 +1,104 @@
+package apicontract
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"testing"
+)
+
+func TestNewDocumentValidatesMetadataAndReturnsDefensiveJSON(t *testing.T) {
+	spec := fixtureSpec(t)
+	runtime := fixtureRuntime(t, spec)
+	document, err := NewDocument(spec, runtime)
+	if err != nil {
+		t.Fatalf("NewDocument() error = %v", err)
+	}
+
+	if document.Metadata().OperationCount != 2 {
+		t.Fatalf("OperationCount = %d, want 2", document.Metadata().OperationCount)
+	}
+	copyJSON := document.JSON()
+	copyJSON[0] = 'x'
+	if document.JSON()[0] == 'x' {
+		t.Fatal("JSON() exposed the document backing bytes")
+	}
+}
+
+func TestNewDocumentRejectsArtifactDrift(t *testing.T) {
+	spec := fixtureSpec(t)
+	runtime := fixtureRuntime(t, spec)
+	spec[len(spec)-2] = ' '
+
+	if _, err := NewDocument(spec, runtime); err == nil {
+		t.Fatal("NewDocument() accepted an artifact with a different digest")
+	}
+}
+
+func TestNewDocumentRejectsDuplicateRouteExclusionShapes(t *testing.T) {
+	spec := fixtureSpec(t)
+	var runtime runtimeContract
+	if err := json.Unmarshal(fixtureRuntime(t, spec), &runtime); err != nil {
+		t.Fatalf("decode fixture runtime: %v", err)
+	}
+	runtime.RouteExclusions = []string{
+		"/_onex/documentation/origin/{environment}/*assetPath",
+		"/_onex/documentation/origin/{stage}/*path",
+	}
+	runtimeJSON, err := json.Marshal(runtime)
+	if err != nil {
+		t.Fatalf("encode fixture runtime: %v", err)
+	}
+
+	if _, err := NewDocument(spec, runtimeJSON); err == nil {
+		t.Fatal("NewDocument() accepted duplicate positional route exclusion shapes")
+	}
+}
+
+func fixtureSpec(t *testing.T) []byte {
+	t.Helper()
+	value := map[string]any{
+		"openapi":           "3.1.1",
+		"jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
+		"info":              map[string]any{"title": "Fixture", "version": "1.0.0"},
+		"paths": map[string]any{
+			"/api/v1/widgets/{id}": map[string]any{"get": map[string]any{"operationId": "getWidget"}},
+			"/api/v1/data/items": map[string]any{"get": map[string]any{
+				"operationId": "getDataItems", "x-onex-delegated-contract": "data-service",
+			}},
+		},
+	}
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	return encoded
+}
+
+func fixtureRuntime(t *testing.T, spec []byte) []byte {
+	t.Helper()
+	digest := sha256.Sum256(spec)
+	value := runtimeContract{
+		SchemaVersion:        2,
+		MediaType:            runtimeContractMediaType,
+		Service:              "fixture-api",
+		DisplayName:          "Fixture API",
+		APIVersion:           "1.0.0",
+		SHA256:               hex.EncodeToString(digest[:]),
+		OperationCount:       2,
+		NativeOperationCount: 1,
+		RouteExclusions:      []string{"/docs", "/health"},
+		DelegatedContracts: []runtimeDelegatedContract{{
+			ID: "data-service", OperationCount: 1,
+		}},
+		Routes: []runtimeRoute{
+			{Method: "GET", Path: "/api/v1/data/items"},
+			{Method: "GET", Path: "/api/v1/widgets/{id}"},
+		},
+	}
+	encoded, err := json.Marshal(value)
+	if err != nil {
+		t.Fatalf("json.Marshal() error = %v", err)
+	}
+	return encoded
+}

package/dist/resources/templates/go-backend/internal/core/apicontract/route_validator.go

@@ -0,0 +1,78 @@
+package apicontract
+
+import (
+	"fmt"
+	"sort"
+	"strings"
+
+	"github.com/gin-gonic/gin"
+)
+
+// ValidateRoutes 对 Gin 运行时路由与内嵌 OpenAPI 契约执行精确集合比较。
+func (d Document) ValidateRoutes(routes gin.RoutesInfo) error {
+	runtimeRoutes := make(map[routeIdentity]struct{}, len(routes))
+	errors := make([]string, 0)
+	for _, route := range routes {
+		path := canonicalRoutePath(route.Path)
+		identity := routeIdentity{method: strings.ToUpper(route.Method), path: path}
+		if _, excluded := d.routeExclusions[path]; excluded {
+			continue
+		}
+		if strings.Contains(path, "*") {
+			errors = append(errors, fmt.Sprintf("undeclared wildcard route %s %s", identity.method, path))
+			continue
+		}
+		runtimeRoutes[identity] = struct{}{}
+	}
+
+	documentedRoutes := make(map[routeIdentity]struct{}, len(d.routes))
+	for route := range d.routes {
+		identity := routeIdentity{method: route.method, path: canonicalRoutePath(route.path)}
+		if _, exists := documentedRoutes[identity]; exists {
+			errors = append(errors, fmt.Sprintf("OpenAPI routes have duplicate runtime shape: %s %s", identity.method, identity.path))
+			continue
+		}
+		documentedRoutes[identity] = struct{}{}
+	}
+
+	for identity := range documentedRoutes {
+		if _, ok := runtimeRoutes[identity]; !ok {
+			errors = append(errors, fmt.Sprintf("OpenAPI route is not registered: %s %s", identity.method, identity.path))
+		}
+	}
+	for identity := range runtimeRoutes {
+		if _, ok := documentedRoutes[identity]; !ok {
+			errors = append(errors, fmt.Sprintf("Gin route is not documented: %s %s", identity.method, identity.path))
+		}
+	}
+	if len(errors) == 0 {
+		return nil
+	}
+	sort.Strings(errors)
+	const previewLimit = 30
+	preview := errors
+	if len(preview) > previewLimit {
+		preview = preview[:previewLimit]
+	}
+	message := strings.Join(preview, "\n- ")
+	if len(errors) > len(preview) {
+		message += fmt.Sprintf("\n- ... %d more route mismatches", len(errors)-len(preview))
+	}
+	return fmt.Errorf("%s route contract validation failed:\n- %s", d.metadata.Service, message)
+}
+
+func canonicalRoutePath(path string) string {
+	segments := strings.Split(path, "/")
+	for index, segment := range segments {
+		if strings.HasPrefix(segment, ":") || isOpenAPIPathParameter(segment) {
+			segments[index] = fmt.Sprintf("{p%d}", index)
+		} else if strings.HasPrefix(segment, "*") {
+			segments[index] = fmt.Sprintf("*p%d", index)
+		}
+	}
+	return strings.Join(segments, "/")
+}
+
+func isOpenAPIPathParameter(segment string) bool {
+	return len(segment) > 2 && segment[0] == '{' && segment[len(segment)-1] == '}'
+}

package/dist/resources/templates/go-backend/internal/core/apicontract/route_validator_test.go

@@ -0,0 +1,108 @@
+package apicontract
+
+import (
+	"encoding/json"
+	"net/http"
+	"strings"
+	"testing"
+
+	"github.com/gin-gonic/gin"
+)
+
+func TestValidateRoutesAcceptsExactNativeAndDelegatedGraphs(t *testing.T) {
+	document := fixtureDocument(t)
+	routes := gin.RoutesInfo{
+		{Method: http.MethodGet, Path: "/api/v1/widgets/:id"},
+		{Method: http.MethodGet, Path: "/api/v1/data/items"},
+		{Method: http.MethodGet, Path: "/health"},
+	}
+
+	if err := document.ValidateRoutes(routes); err != nil {
+		t.Fatalf("ValidateRoutes() error = %v", err)
+	}
+}
+
+func TestValidateRoutesMatchesPathParametersByRoutePosition(t *testing.T) {
+	document := fixtureDocument(t)
+	routes := gin.RoutesInfo{
+		{Method: http.MethodGet, Path: "/api/v1/widgets/:p4"},
+		{Method: http.MethodGet, Path: "/api/v1/data/items"},
+	}
+
+	if err := document.ValidateRoutes(routes); err != nil {
+		t.Fatalf("ValidateRoutes() error = %v", err)
+	}
+}
+
+func TestValidateRoutesRejectsDuplicateOpenAPIParameterShapes(t *testing.T) {
+	document := fixtureDocument(t)
+	document.routes[routeIdentity{method: http.MethodGet, path: "/api/v1/widgets/{widget_id}"}] = struct{}{}
+	err := document.ValidateRoutes(gin.RoutesInfo{
+		{Method: http.MethodGet, Path: "/api/v1/widgets/:id"},
+		{Method: http.MethodGet, Path: "/api/v1/data/items"},
+	})
+	if err == nil || !strings.Contains(err.Error(), "duplicate runtime shape") {
+		t.Fatalf("ValidateRoutes() error = %v, want duplicate runtime shape rejection", err)
+	}
+}
+
+func TestValidateRoutesReportsMissingAndUndocumentedRoutes(t *testing.T) {
+	document := fixtureDocument(t)
+	err := document.ValidateRoutes(gin.RoutesInfo{{Method: http.MethodPost, Path: "/api/v1/widgets"}})
+	if err == nil {
+		t.Fatal("ValidateRoutes() accepted a mismatched graph")
+	}
+	for _, expected := range []string{"OpenAPI route is not registered", "Gin route is not documented"} {
+		if !strings.Contains(err.Error(), expected) {
+			t.Fatalf("ValidateRoutes() error = %q, want %q", err, expected)
+		}
+	}
+}
+
+func TestValidateRoutesRejectsWildcardRoutes(t *testing.T) {
+	document := fixtureDocument(t)
+	err := document.ValidateRoutes(gin.RoutesInfo{{Method: http.MethodGet, Path: "/api/v1/data/*path"}})
+	if err == nil || !strings.Contains(err.Error(), "undeclared wildcard route") {
+		t.Fatalf("ValidateRoutes() error = %v, want wildcard rejection", err)
+	}
+}
+
+func TestValidateRoutesAcceptsDeclaredWildcardRouteWithPositionalParameterIdentity(t *testing.T) {
+	spec := fixtureSpec(t)
+	var runtime runtimeContract
+	if err := json.Unmarshal(fixtureRuntime(t, spec), &runtime); err != nil {
+		t.Fatalf("decode fixture runtime: %v", err)
+	}
+	runtime.RouteExclusions = []string{
+		"/_onex/documentation/origin/{environment}/*assetPath",
+		"/docs",
+		"/health",
+	}
+	runtimeJSON, err := json.Marshal(runtime)
+	if err != nil {
+		t.Fatalf("encode fixture runtime: %v", err)
+	}
+	document, err := NewDocument(spec, runtimeJSON)
+	if err != nil {
+		t.Fatalf("NewDocument() error = %v", err)
+	}
+	routes := gin.RoutesInfo{
+		{Method: http.MethodGet, Path: "/api/v1/widgets/:id"},
+		{Method: http.MethodGet, Path: "/api/v1/data/items"},
+		{Method: http.MethodGet, Path: "/_onex/documentation/origin/:stage/*path"},
+		{Method: http.MethodHead, Path: "/_onex/documentation/origin/:stage/*path"},
+	}
+
+	if err := document.ValidateRoutes(routes); err != nil {
+		t.Fatalf("ValidateRoutes() error = %v", err)
+	}
+}
+
+func fixtureDocument(t *testing.T) Document {
+	t.Helper()
+	document, err := NewDocument(fixtureSpec(t), fixtureRuntime(t, fixtureSpec(t)))
+	if err != nil {
+		t.Fatalf("NewDocument() error = %v", err)
+	}
+	return document
+}