@stackonward/cli 0.0.1 → 1.0.0

package/dist/resources/templates/go-backend/internal/core/config/contract/verify.go

@@ -0,0 +1,424 @@
+package configcontract
+
+import (
+	"bufio"
+	"bytes"
+	"encoding/json"
+	"errors"
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"regexp"
+	"slices"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/subosito/gotenv"
+
+	"{{module}}/internal/core/config"
+)
+
+var (
+	environmentVariableNamePattern = regexp.MustCompile(`^[A-Z][A-Z0-9_]*$`)
+	secretTemplateMarkerPattern    = regexp.MustCompile(`^<[a-z0-9][a-z0-9-]{2,127}>$`)
+	jsonNumberPattern              = regexp.MustCompile(`^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$`)
+)
+
+type composeConfig struct {
+	Services map[string]composeService `json:"services"`
+}
+
+type composeService struct {
+	Environment composeEnvironment `json:"environment"`
+	Volumes     []composeVolume    `json:"volumes"`
+}
+
+// composeEnvironment 限制 Compose 环境值只能是 JSON 标量。
+type composeEnvironment map[string]composeEnvironmentValue
+
+type composeEnvironmentValue struct {
+	value string
+	null  bool
+}
+
+func (value *composeEnvironmentValue) UnmarshalJSON(data []byte) error {
+	if bytes.Equal(data, []byte("null")) {
+		value.value = ""
+		value.null = true
+		return nil
+	}
+	var stringValue string
+	if err := json.Unmarshal(data, &stringValue); err == nil {
+		value.value = stringValue
+		value.null = false
+		return nil
+	}
+	raw := string(data)
+	if raw == "true" || raw == "false" || jsonNumberPattern.MatchString(raw) {
+		value.value = raw
+		value.null = false
+		return nil
+	}
+	return fmt.Errorf("Compose environment value must be a string, number, boolean, or null")
+}
+
+func (value composeEnvironmentValue) MarshalJSON() ([]byte, error) {
+	if value.null {
+		return []byte("null"), nil
+	}
+	return json.Marshal(value.value)
+}
+
+func (value composeEnvironmentValue) String() string {
+	if value.null {
+		return ""
+	}
+	return value.value
+}
+
+func newComposeEnvironmentValue(value string) composeEnvironmentValue {
+	return composeEnvironmentValue{value: value}
+}
+
+type composeVolume struct {
+	Type     string `json:"type"`
+	Source   string `json:"source"`
+	Target   string `json:"target"`
+	ReadOnly bool   `json:"read_only"`
+}
+
+func runVerify(args []string, stdout, stderr io.Writer) error {
+	flags := flag.NewFlagSet("config-contract verify", flag.ContinueOnError)
+	flags.SetOutput(stderr)
+	surfaceValue := flags.String("surface", "", "deployment surface: dev, test, or prod")
+	envExample := flags.String("env-example", "", "environment example path")
+	composeJSON := flags.String("compose-json", "", "resolved Docker Compose JSON path")
+	if err := flags.Parse(args); err != nil {
+		return err
+	}
+	if flags.NArg() != 0 {
+		return fmt.Errorf("verify command does not accept positional arguments")
+	}
+
+	surface, err := parseDeploymentSurface(*surfaceValue)
+	if err != nil {
+		return err
+	}
+	if strings.TrimSpace(*envExample) == "" || strings.TrimSpace(*composeJSON) == "" {
+		return fmt.Errorf("verify requires --env-example and --compose-json")
+	}
+	metadata := config.DocumentationEnvironmentVariables()
+	if err := validateMetadata(metadata); err != nil {
+		return err
+	}
+	environment, err := readEnvironmentExample(*envExample)
+	if err != nil {
+		return err
+	}
+	resolved, err := readComposeConfig(*composeJSON)
+	if err != nil {
+		return err
+	}
+	violations := verifyContract(metadata, surface, environment, resolved)
+	if len(violations) != 0 {
+		return errors.New("configuration contract violations:\n- " + strings.Join(violations, "\n- "))
+	}
+	_, _ = fmt.Fprintf(stdout, "%s: configuration contract passed\n", surface)
+	return nil
+}
+
+func parseDeploymentSurface(value string) (config.DeploymentSurface, error) {
+	surface := config.DeploymentSurface(strings.TrimSpace(value))
+	switch surface {
+	case config.DeploymentSurfaceDev,
+		config.DeploymentSurfaceTest,
+		config.DeploymentSurfaceProd:
+		return surface, nil
+	default:
+		return "", fmt.Errorf("unsupported deployment surface %q", value)
+	}
+}
+
+func readEnvironmentExample(path string) (map[string]string, error) {
+	body, err := os.ReadFile(path)
+	if err != nil {
+		return nil, fmt.Errorf("read environment example %s: %w", path, err)
+	}
+	if err := validateEnvironmentExampleKeys(body); err != nil {
+		return nil, fmt.Errorf("parse environment example %s: %w", path, err)
+	}
+	environment, err := gotenv.StrictParse(bytes.NewReader(body))
+	if err != nil {
+		return nil, fmt.Errorf("parse environment example %s: %w", path, err)
+	}
+	return environment, nil
+}
+
+func validateEnvironmentExampleKeys(body []byte) error {
+	seen := make(map[string]struct{})
+	scanner := bufio.NewScanner(bytes.NewReader(body))
+	for scanner.Scan() {
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" || strings.HasPrefix(line, "#") {
+			continue
+		}
+		line = strings.TrimSpace(strings.TrimPrefix(line, "export "))
+		name, _, exists := strings.Cut(line, "=")
+		name = strings.TrimSpace(name)
+		if !exists || !environmentVariableNamePattern.MatchString(name) {
+			continue
+		}
+		if _, duplicate := seen[name]; duplicate {
+			return fmt.Errorf("environment variable %s is duplicated", name)
+		}
+		seen[name] = struct{}{}
+	}
+	if err := scanner.Err(); err != nil {
+		return fmt.Errorf("scan environment example: %w", err)
+	}
+	return nil
+}
+
+func readComposeConfig(path string) (composeConfig, error) {
+	body, err := os.ReadFile(path)
+	if err != nil {
+		return composeConfig{}, fmt.Errorf("read Compose JSON %s: %w", path, err)
+	}
+	var resolved composeConfig
+	decoder := json.NewDecoder(bytes.NewReader(body))
+	if err := decoder.Decode(&resolved); err != nil {
+		return composeConfig{}, fmt.Errorf("decode Compose JSON %s: %w", path, err)
+	}
+	if err := decoder.Decode(&struct{}{}); !errors.Is(err, io.EOF) {
+		return composeConfig{}, fmt.Errorf("decode Compose JSON %s: trailing data", path)
+	}
+	if len(resolved.Services) == 0 {
+		return composeConfig{}, fmt.Errorf("Compose JSON %s has no services", path)
+	}
+	return resolved, nil
+}
+
+func validateMetadata(metadata []config.EnvironmentVariableMetadata) error {
+	return config.ValidateDocumentationEnvironmentVariables(metadata)
+}
+
+func verifyContract(
+	metadata []config.EnvironmentVariableMetadata,
+	surface config.DeploymentSurface,
+	environment map[string]string,
+	resolved composeConfig,
+) []string {
+	violations := make([]string, 0)
+	registeredVariables := make(map[string]struct{}, len(metadata))
+	for index := range metadata {
+		variable := &metadata[index]
+		registeredVariables[variable.Name] = struct{}{}
+	}
+	for index := range metadata {
+		variable := &metadata[index]
+		value, exists := environment[variable.Name]
+		if slices.Contains(variable.RequiredSurfaces, surface) && (!exists || strings.TrimSpace(value) == "") {
+			violations = append(violations, fmt.Sprintf("%s is required in %s", variable.Name, surface))
+		}
+		if exists && strings.TrimSpace(value) != "" {
+			if err := validateEnvironmentValue(variable, surface, value, environment, registeredVariables); err != nil {
+				violations = append(violations, err.Error())
+			}
+		}
+
+		allowed := stringSet(variable.AllowedConsumers)
+		for serviceName, service := range resolved.Services {
+			composeValue, injected := service.Environment[variable.Name]
+			if !injected {
+				continue
+			}
+			canonical := canonicalServiceName(serviceName)
+			if _, accepted := allowed[canonical]; !accepted {
+				violations = append(
+					violations,
+					fmt.Sprintf("%s is injected into unauthorized service %s", variable.Name, serviceName),
+				)
+			}
+			if exists && composeValue.String() != value {
+				violations = append(
+					violations,
+					fmt.Sprintf("%s in service %s differs from the environment example", variable.Name, serviceName),
+				)
+			}
+		}
+		for _, required := range variable.RequiredConsumers {
+			serviceInstances := composeServiceInstances(resolved, required)
+			if len(serviceInstances) == 0 {
+				violations = append(violations, fmt.Sprintf("required consumer %s is absent from Compose", required))
+				continue
+			}
+			for _, serviceName := range serviceInstances {
+				service := resolved.Services[serviceName]
+				if _, injected := service.Environment[variable.Name]; !injected {
+					violations = append(
+						violations,
+						fmt.Sprintf("%s is missing from required consumer %s", variable.Name, serviceName),
+					)
+				}
+				if variable.MountSourceVariable != "" && value != "" && environment[variable.MountSourceVariable] != "" {
+					violations = append(violations, verifyMountContract(variable, value, environment, serviceName, service)...)
+				}
+				referenceTarget := environmentReferenceTarget(variable, value)
+				if referenceTarget == "" {
+					continue
+				}
+				if _, governedByRegistry := registeredVariables[referenceTarget]; governedByRegistry {
+					continue
+				}
+				targetValue := environment[referenceTarget]
+				resolvedTarget, injected := service.Environment[referenceTarget]
+				if !injected || strings.TrimSpace(resolvedTarget.String()) == "" {
+					violations = append(
+						violations,
+						fmt.Sprintf(
+							"%s referenced by %s is missing from required consumer %s",
+							referenceTarget,
+							variable.Name,
+							serviceName,
+						),
+					)
+				} else if resolvedTarget.String() != targetValue {
+					violations = append(
+						violations,
+						fmt.Sprintf(
+							"%s referenced by %s differs in required consumer %s",
+							referenceTarget,
+							variable.Name,
+							serviceName,
+						),
+					)
+				}
+			}
+		}
+	}
+	sort.Strings(violations)
+	return violations
+}
+
+func verifyMountContract(
+	variable *config.EnvironmentVariableMetadata,
+	target string,
+	environment map[string]string,
+	serviceName string,
+	service composeService,
+) []string {
+	if variable.MountSourceVariable == "" {
+		return nil
+	}
+	source := environment[variable.MountSourceVariable]
+	for _, volume := range service.Volumes {
+		if volume.Target != target {
+			continue
+		}
+		violations := make([]string, 0, 3)
+		if volume.Type != "bind" {
+			violations = append(violations, fmt.Sprintf("%s mount in %s must be a bind mount", variable.Name, serviceName))
+		}
+		if volume.Source != source {
+			violations = append(
+				violations,
+				fmt.Sprintf("%s mount source in %s differs from %s", variable.Name, serviceName, variable.MountSourceVariable),
+			)
+		}
+		if variable.MountReadOnly && !volume.ReadOnly {
+			violations = append(violations, fmt.Sprintf("%s mount in %s must be read-only", variable.Name, serviceName))
+		}
+		return violations
+	}
+	return []string{fmt.Sprintf("%s mount target %s is missing from required consumer %s", variable.Name, target, serviceName)}
+}
+
+func environmentReferenceTarget(variable *config.EnvironmentVariableMetadata, value string) string {
+	if variable.ValueType != config.ConfigValueTypeSecretReference || !strings.HasPrefix(value, "env://") {
+		return ""
+	}
+	target := strings.TrimPrefix(value, "env://")
+	if !environmentVariableNamePattern.MatchString(target) {
+		return ""
+	}
+	return target
+}
+
+func validateEnvironmentValue(
+	variable *config.EnvironmentVariableMetadata,
+	surface config.DeploymentSurface,
+	value string,
+	environment map[string]string,
+	registeredVariables map[string]struct{},
+) error {
+	if err := variable.ValidateValue(value, config.ConfigValueValidationDeployment); err != nil {
+		return err
+	}
+	if variable.Sensitive {
+		return validateSecretExample(variable.Name, surface, value)
+	}
+	target := environmentReferenceTarget(variable, value)
+	if target == "" {
+		return nil
+	}
+	targetValue, exists := environment[target]
+	if !exists || strings.TrimSpace(targetValue) == "" {
+		return fmt.Errorf("%s references missing environment variable %s", variable.Name, target)
+	}
+	if _, governedByRegistry := registeredVariables[target]; governedByRegistry {
+		return nil
+	}
+	if err := validateSecretExample(target, surface, targetValue); err != nil {
+		return err
+	}
+	return nil
+}
+
+func validateSecretExample(name string, surface config.DeploymentSurface, value string) error {
+	if secretTemplateMarkerPattern.MatchString(value) {
+		return nil
+	}
+	if surface == config.DeploymentSurfaceProd {
+		return fmt.Errorf("%s must use a descriptive redacted marker in production examples", name)
+	}
+	lower := strings.ToLower(value)
+	if len(value) < 32 || !strings.Contains(lower, "do-not-use") ||
+		(surface == config.DeploymentSurfaceDev && !strings.Contains(lower, "dev")) ||
+		(surface == config.DeploymentSurfaceTest && !strings.Contains(lower, "test")) {
+		return fmt.Errorf("%s must use an explicit non-production value or redacted marker", name)
+	}
+	return nil
+}
+
+func composeServiceInstances(resolved composeConfig, canonical string) []string {
+	instances := make([]string, 0)
+	for serviceName := range resolved.Services {
+		if canonicalServiceName(serviceName) == canonical {
+			instances = append(instances, serviceName)
+		}
+	}
+	sort.Strings(instances)
+	return instances
+}
+
+func canonicalServiceName(name string) string {
+	separator := strings.LastIndexByte(name, '-')
+	if separator < 0 {
+		return name
+	}
+	replica, err := strconv.Atoi(name[separator+1:])
+	if err == nil && replica >= 2 {
+		return name[:separator]
+	}
+	return name
+}
+
+func stringSet(values []string) map[string]struct{} {
+	result := make(map[string]struct{}, len(values))
+	for _, value := range values {
+		result[value] = struct{}{}
+	}
+	return result
+}

package/dist/resources/templates/go-backend/internal/core/config/enum.go

@@ -0,0 +1,46 @@
+package config
+
+// ConfigValueType 定义环境变量在配置契约中的解析语义。
+type ConfigValueType string
+
+const (
+	ConfigValueTypeString          ConfigValueType = "string"
+	ConfigValueTypeExecutable      ConfigValueType = "executable"
+	ConfigValueTypeInteger         ConfigValueType = "integer"
+	ConfigValueTypeDuration        ConfigValueType = "duration"
+	ConfigValueTypeHTTPURL         ConfigValueType = "http_url"
+	ConfigValueTypePath            ConfigValueType = "path"
+	ConfigValueTypeSecretReference ConfigValueType = "secret_reference"
+	ConfigValueTypeSecret          ConfigValueType = "secret"
+	ConfigValueTypeEndpointList    ConfigValueType = "endpoint_list"
+)
+
+// ConfigValueValidationContext 区分代码运行时配置与部署样例的路径约束。
+type ConfigValueValidationContext string
+
+const (
+	ConfigValueValidationRuntime    ConfigValueValidationContext = "runtime"
+	ConfigValueValidationDeployment ConfigValueValidationContext = "deployment"
+)
+
+// DeploymentSurface 标识由同一配置契约治理的部署面。
+type DeploymentSurface string
+
+const (
+	DeploymentSurfaceDev  DeploymentSurface = "dev"
+	DeploymentSurfaceTest DeploymentSurface = "test"
+	DeploymentSurfaceProd DeploymentSurface = "prod"
+)
+
+const (
+	configDefaultValueUnset uint8 = iota
+	configDefaultValueString
+	configDefaultValueInteger
+)
+
+const (
+	documentationRuntimeGroupCompiler = "compiler"
+	documentationRuntimeGroupPrivacy  = "privacy"
+	documentationRuntimeGroupDomain   = "domain"
+	documentationRuntimeGroupInternal = "internal"
+)