@stackonward/cli 0.0.1 → 1.0.1

package/dist/resources/templates/go-backend/internal/common/ruleexpression/schema.go

@@ -0,0 +1,412 @@
+package ruleexpression
+
+import "fmt"
+
+// Stage 标识消费方执行 Requirement Expression 的事实阶段。
+type Stage string
+
+const (
+	StageProductContext Stage = "product_context"
+	StageCapability     Stage = "capability"
+	StageDataset        Stage = "dataset"
+)
+
+// NodeChildShape 描述节点承载后继内容的结构。
+type NodeChildShape string
+
+const (
+	NodeChildShapeChildren  NodeChildShape = "children"
+	NodeChildShapeChild     NodeChildShape = "child"
+	NodeChildShapePredicate NodeChildShape = "predicate"
+)
+
+// KeyShape 描述 predicate key 的封闭输入结构。
+type KeyShape string
+
+const (
+	KeyShapeFixed          KeyShape = "fixed"
+	KeyShapeSnakeCode      KeyShape = "snake_code"
+	KeyShapeNamespacedCode KeyShape = "namespaced_code"
+)
+
+// ValueShape 描述 operator 接受的值结构。
+type ValueShape string
+
+const (
+	ValueShapeNone            ValueShape = "none"
+	ValueShapeComparable      ValueShape = "comparable"
+	ValueShapeStringArray     ValueShape = "string_array"
+	ValueShapePositiveInteger ValueShape = "positive_integer"
+)
+
+// ValueType 描述 scalar 允许的 JSON 值类型。
+type ValueType string
+
+const (
+	ValueTypeBoolean     ValueType = "boolean"
+	ValueTypeNumber      ValueType = "number"
+	ValueTypeString      ValueType = "string"
+	ValueTypeStringArray ValueType = "string_array"
+)
+
+// EditorSchema 是 Requirement Expression 编辑器的完整可执行契约。
+type EditorSchema struct {
+	SchemaVersion int                  `json:"schema_version"`
+	Nodes         []NodeDefinition     `json:"nodes"`
+	Subjects      []SubjectDefinition  `json:"subjects"`
+	Operators     []OperatorDefinition `json:"operators"`
+	Limits        LimitsDefinition     `json:"limits"`
+	Stages        []StageDefinition    `json:"stages"`
+}
+
+// NodeDefinition 描述 AST 节点及其后继结构。
+type NodeDefinition struct {
+	Kind       NodeKind       `json:"kind"`
+	Label      string         `json:"label"`
+	ChildShape NodeChildShape `json:"child_shape"`
+}
+
+// KeyOption 描述固定 key 选项。
+type KeyOption struct {
+	Value string `json:"value"`
+	Label string `json:"label"`
+}
+
+// SubjectDefinition 描述 subject 的 key 约束和 operator 集合。
+type SubjectDefinition struct {
+	Value        Subject                     `json:"value"`
+	Label        string                      `json:"label"`
+	KeyShape     KeyShape                    `json:"key_shape"`
+	KeyMaxLength int                         `json:"key_max_length"`
+	FixedKeys    []KeyOption                 `json:"fixed_keys"`
+	Operators    []SubjectOperatorDefinition `json:"operators"`
+}
+
+// SubjectOperatorDefinition 描述 operator 在特定 subject 下的值约束。
+type SubjectOperatorDefinition struct {
+	Value      Operator    `json:"value"`
+	Label      string      `json:"label"`
+	ValueShape ValueShape  `json:"value_shape"`
+	ValueTypes []ValueType `json:"value_types"`
+}
+
+// OperatorDefinition 描述全局 operator 展示元数据。
+type OperatorDefinition struct {
+	Value Operator `json:"value"`
+	Label string   `json:"label"`
+}
+
+// LimitsDefinition 描述 parser 和 validator 的资源边界。
+type LimitsDefinition struct {
+	MaxJSONBytes          int `json:"max_json_bytes"`
+	MaxDepth              int `json:"max_depth"`
+	MaxNodes              int `json:"max_nodes"`
+	MaxChildren           int `json:"max_children"`
+	MaxStringLength       int `json:"max_string_length"`
+	MaxStringArrayItems   int `json:"max_string_array_items"`
+	MaxFreshWithinSeconds int `json:"max_fresh_within_seconds"`
+}
+
+// StageDefinition 描述事实阶段允许使用的 subject。
+type StageDefinition struct {
+	Value    Stage     `json:"value"`
+	Label    string    `json:"label"`
+	Subjects []Subject `json:"subjects"`
+}
+
+// EditorSchemaV1 返回与 V1 validator 同源的编辑器契约。
+func EditorSchemaV1() EditorSchema {
+	return EditorSchema{
+		SchemaVersion: SchemaVersionV1,
+		Nodes: []NodeDefinition{
+			nodeDefinition(NodeKindAll),
+			nodeDefinition(NodeKindAny),
+			nodeDefinition(NodeKindNot),
+			nodeDefinition(NodeKindPredicate),
+		},
+		Subjects: []SubjectDefinition{
+			mustSubjectDefinition(SubjectProduct),
+			mustSubjectDefinition(SubjectAttribute),
+			mustSubjectDefinition(SubjectCapability),
+			mustSubjectDefinition(SubjectInsightsMetric),
+			mustSubjectDefinition(SubjectProductDataset),
+		},
+		Operators: []OperatorDefinition{
+			operatorDefinition(OperatorEqual),
+			operatorDefinition(OperatorNotEqual),
+			operatorDefinition(OperatorIn),
+			operatorDefinition(OperatorNotIn),
+			operatorDefinition(OperatorExists),
+			operatorDefinition(OperatorActive),
+			operatorDefinition(OperatorInactive),
+			operatorDefinition(OperatorAvailable),
+			operatorDefinition(OperatorFreshWithinSeconds),
+		},
+		Limits: LimitsDefinition{
+			MaxJSONBytes:          MaxJSONBytes,
+			MaxDepth:              MaxDepth,
+			MaxNodes:              MaxNodes,
+			MaxChildren:           MaxChildren,
+			MaxStringLength:       MaxStringLength,
+			MaxStringArrayItems:   MaxStringArrayItems,
+			MaxFreshWithinSeconds: MaxFreshWithinSeconds,
+		},
+		Stages: []StageDefinition{
+			mustStageDefinition(StageProductContext),
+			mustStageDefinition(StageCapability),
+			mustStageDefinition(StageDataset),
+		},
+	}
+}
+
+// AllowedSubjectsForStage 返回阶段允许的 subject 副本。
+func AllowedSubjectsForStage(stage Stage) ([]Subject, error) {
+	definition, ok := stageDefinition(stage)
+	if !ok {
+		return nil, newError(ErrorCodeInvalidPredicate, "$.stage", fmt.Sprintf("stage %q is not supported", stage))
+	}
+	return append([]Subject(nil), definition.Subjects...), nil
+}
+
+// ValidateStage 校验完整表达式及其事实阶段边界。
+func ValidateStage(expression ExpressionV1, stage Stage) error {
+	if err := validateExpression(expression); err != nil {
+		return err
+	}
+	allowed, err := AllowedSubjectsForStage(stage)
+	if err != nil {
+		return err
+	}
+	allowedSet := make(map[Subject]struct{}, len(allowed))
+	for _, subject := range allowed {
+		allowedSet[subject] = struct{}{}
+	}
+	return validateStageNode(expression.Root, "$.root", stage, allowedSet)
+}
+
+func validateStageNode(node Node, path string, stage Stage, allowed map[Subject]struct{}) error {
+	switch current := node.(type) {
+	case *AllNode:
+		for i := range current.Children {
+			if err := validateStageNode(current.Children[i], fmt.Sprintf("%s.children[%d]", path, i), stage, allowed); err != nil {
+				return err
+			}
+		}
+	case *AnyNode:
+		for i := range current.Children {
+			if err := validateStageNode(current.Children[i], fmt.Sprintf("%s.children[%d]", path, i), stage, allowed); err != nil {
+				return err
+			}
+		}
+	case *NotNode:
+		return validateStageNode(current.Child, path+".child", stage, allowed)
+	case *PredicateNode:
+		if _, ok := allowed[current.Subject]; !ok {
+			return newError(
+				ErrorCodeInvalidPredicate,
+				path+".subject",
+				fmt.Sprintf("subject %q is not allowed in stage %q", current.Subject, stage),
+			)
+		}
+	default:
+		return newError(ErrorCodeInvalidNode, path, "node kind is not supported")
+	}
+	return nil
+}
+
+func nodeDefinition(kind NodeKind) NodeDefinition {
+	switch kind {
+	case NodeKindAll:
+		return NodeDefinition{Kind: kind, Label: "全部满足", ChildShape: NodeChildShapeChildren}
+	case NodeKindAny:
+		return NodeDefinition{Kind: kind, Label: "任一满足", ChildShape: NodeChildShapeChildren}
+	case NodeKindNot:
+		return NodeDefinition{Kind: kind, Label: "条件取反", ChildShape: NodeChildShapeChild}
+	case NodeKindPredicate:
+		return NodeDefinition{Kind: kind, Label: "判断条件", ChildShape: NodeChildShapePredicate}
+	default:
+		panic(fmt.Sprintf("unsupported requirement node kind %q", kind))
+	}
+}
+
+func subjectDefinition(subject Subject) (SubjectDefinition, bool) {
+	switch subject {
+	case SubjectProduct:
+		return SubjectDefinition{
+			Value: subject, Label: "产品", KeyShape: KeyShapeFixed, KeyMaxLength: MaxStringLength,
+			FixedKeys: []KeyOption{{Value: "code", Label: "产品编码"}, {Value: "lifecycle_status", Label: "生命周期状态"}},
+			Operators: subjectOperatorDefinitions(subject),
+		}, true
+	case SubjectAttribute:
+		return SubjectDefinition{
+			Value: subject, Label: "产品属性", KeyShape: KeyShapeSnakeCode, KeyMaxLength: maxCatalogCodeLength,
+			FixedKeys: []KeyOption{}, Operators: subjectOperatorDefinitions(subject),
+		}, true
+	case SubjectCapability:
+		return SubjectDefinition{
+			Value: subject, Label: "产品能力", KeyShape: KeyShapeSnakeCode, KeyMaxLength: maxCatalogCodeLength,
+			FixedKeys: []KeyOption{},
+			Operators: subjectOperatorDefinitions(subject),
+		}, true
+	case SubjectInsightsMetric:
+		return SubjectDefinition{
+			Value: subject, Label: "洞察指标", KeyShape: KeyShapeNamespacedCode, KeyMaxLength: MaxStringLength,
+			FixedKeys: []KeyOption{}, Operators: subjectOperatorDefinitions(subject),
+		}, true
+	case SubjectProductDataset:
+		return SubjectDefinition{
+			Value: subject, Label: "产品数据集", KeyShape: KeyShapeNamespacedCode, KeyMaxLength: MaxStringLength,
+			FixedKeys: []KeyOption{}, Operators: subjectOperatorDefinitions(subject),
+		}, true
+	default:
+		return SubjectDefinition{}, false
+	}
+}
+
+func mustSubjectDefinition(subject Subject) SubjectDefinition {
+	definition, ok := subjectDefinition(subject)
+	if !ok {
+		panic(fmt.Sprintf("unsupported requirement subject %q", subject))
+	}
+	return definition
+}
+
+type valueTypeMask uint8
+
+const (
+	valueTypeMaskBoolean valueTypeMask = 1 << iota
+	valueTypeMaskNumber
+	valueTypeMaskString
+	valueTypeMaskStringArray
+)
+
+func subjectOperatorDefinition(subject Subject, operator Operator) SubjectOperatorDefinition {
+	shape, valueTypes, ok := operatorConstraint(subject, operator)
+	if !ok {
+		panic(fmt.Sprintf("operator %q is not supported for requirement subject %q", operator, subject))
+	}
+	return SubjectOperatorDefinition{
+		Value: operator, Label: operatorDefinition(operator).Label, ValueShape: shape,
+		ValueTypes: valueTypesForMask(valueTypes),
+	}
+}
+
+func subjectOperatorDefinitions(subject Subject) []SubjectOperatorDefinition {
+	var operators []Operator
+	switch subject {
+	case SubjectProduct:
+		operators = []Operator{OperatorEqual, OperatorNotEqual, OperatorIn, OperatorNotIn}
+	case SubjectAttribute:
+		operators = []Operator{OperatorExists, OperatorEqual, OperatorNotEqual, OperatorIn, OperatorNotIn}
+	case SubjectCapability:
+		operators = []Operator{OperatorActive, OperatorInactive}
+	case SubjectInsightsMetric, SubjectProductDataset:
+		operators = []Operator{OperatorAvailable, OperatorFreshWithinSeconds}
+	default:
+		panic(fmt.Sprintf("unsupported requirement subject %q", subject))
+	}
+	definitions := make([]SubjectOperatorDefinition, 0, len(operators))
+	for _, operator := range operators {
+		definitions = append(definitions, subjectOperatorDefinition(subject, operator))
+	}
+	return definitions
+}
+
+func operatorConstraint(subject Subject, operator Operator) (ValueShape, valueTypeMask, bool) {
+	switch subject {
+	case SubjectProduct:
+		switch operator {
+		case OperatorEqual, OperatorNotEqual:
+			return ValueShapeComparable, valueTypeMaskString, true
+		case OperatorIn, OperatorNotIn:
+			return ValueShapeStringArray, valueTypeMaskString, true
+		}
+	case SubjectAttribute:
+		switch operator {
+		case OperatorExists:
+			return ValueShapeNone, 0, true
+		case OperatorEqual, OperatorNotEqual:
+			return ValueShapeComparable, valueTypeMaskBoolean | valueTypeMaskNumber | valueTypeMaskString | valueTypeMaskStringArray, true
+		case OperatorIn, OperatorNotIn:
+			return ValueShapeStringArray, valueTypeMaskString, true
+		}
+	case SubjectCapability:
+		if operator == OperatorActive || operator == OperatorInactive {
+			return ValueShapeNone, 0, true
+		}
+	case SubjectInsightsMetric, SubjectProductDataset:
+		switch operator {
+		case OperatorAvailable:
+			return ValueShapeNone, 0, true
+		case OperatorFreshWithinSeconds:
+			return ValueShapePositiveInteger, valueTypeMaskNumber, true
+		}
+	}
+	return "", 0, false
+}
+
+func valueTypesForMask(mask valueTypeMask) []ValueType {
+	result := make([]ValueType, 0, 4)
+	for _, candidate := range []struct {
+		mask      valueTypeMask
+		valueType ValueType
+	}{
+		{valueTypeMaskBoolean, ValueTypeBoolean},
+		{valueTypeMaskNumber, ValueTypeNumber},
+		{valueTypeMaskString, ValueTypeString},
+		{valueTypeMaskStringArray, ValueTypeStringArray},
+	} {
+		if mask&candidate.mask != 0 {
+			result = append(result, candidate.valueType)
+		}
+	}
+	return result
+}
+
+func operatorDefinition(operator Operator) OperatorDefinition {
+	var label string
+	switch operator {
+	case OperatorEqual:
+		label = "等于"
+	case OperatorNotEqual:
+		label = "不等于"
+	case OperatorIn:
+		label = "属于"
+	case OperatorNotIn:
+		label = "不属于"
+	case OperatorExists:
+		label = "存在"
+	case OperatorActive:
+		label = "已启用"
+	case OperatorInactive:
+		label = "未启用"
+	case OperatorAvailable:
+		label = "可用"
+	case OperatorFreshWithinSeconds:
+		label = "新鲜度不超过"
+	default:
+		panic(fmt.Sprintf("unsupported requirement operator %q", operator))
+	}
+	return OperatorDefinition{Value: operator, Label: label}
+}
+
+func stageDefinition(stage Stage) (StageDefinition, bool) {
+	switch stage {
+	case StageProductContext:
+		return StageDefinition{Value: stage, Label: "产品上下文", Subjects: []Subject{SubjectProduct, SubjectAttribute}}, true
+	case StageCapability:
+		return StageDefinition{Value: stage, Label: "产品能力", Subjects: []Subject{SubjectCapability}}, true
+	case StageDataset:
+		return StageDefinition{Value: stage, Label: "数据集", Subjects: []Subject{SubjectInsightsMetric, SubjectProductDataset}}, true
+	default:
+		return StageDefinition{}, false
+	}
+}
+
+func mustStageDefinition(stage Stage) StageDefinition {
+	definition, ok := stageDefinition(stage)
+	if !ok {
+		panic(fmt.Sprintf("unsupported requirement stage %q", stage))
+	}
+	return definition
+}

package/dist/resources/templates/go-backend/internal/common/ruleexpression/schema_test.go

@@ -0,0 +1,164 @@
+package ruleexpression
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestEditorSchemaV1MatchesPredicateValidator(t *testing.T) {
+	schema := EditorSchemaV1()
+	if schema.SchemaVersion != SchemaVersionV1 {
+		t.Fatalf("schema version = %d", schema.SchemaVersion)
+	}
+	if schema.Limits.MaxJSONBytes != MaxJSONBytes ||
+		schema.Limits.MaxDepth != MaxDepth ||
+		schema.Limits.MaxNodes != MaxNodes ||
+		schema.Limits.MaxChildren != MaxChildren ||
+		schema.Limits.MaxStringLength != MaxStringLength ||
+		schema.Limits.MaxStringArrayItems != MaxStringArrayItems ||
+		schema.Limits.MaxFreshWithinSeconds != MaxFreshWithinSeconds {
+		t.Fatalf("schema limits do not match validator constants: %+v", schema.Limits)
+	}
+
+	for _, subject := range schema.Subjects {
+		key := validSchemaKey(t, subject)
+		for _, operator := range subject.Operators {
+			valueTypes := operator.ValueTypes
+			if len(valueTypes) == 0 {
+				valueTypes = []ValueType{""}
+			}
+			for _, valueType := range valueTypes {
+				predicate := &PredicateNode{
+					Subject:  subject.Value,
+					Key:      key,
+					Operator: operator.Value,
+					Value:    validSchemaValue(operator.ValueShape, valueType),
+				}
+				expression := ExpressionV1{SchemaVersion: SchemaVersionV1, Root: predicate}
+				if err := validateExpression(expression); err != nil {
+					t.Fatalf("schema combination %s/%s/%s rejected: %v", subject.Value, operator.Value, valueType, err)
+				}
+			}
+		}
+	}
+}
+
+func TestEditorSchemaV1ReturnsIndependentDeterministicValues(t *testing.T) {
+	first := EditorSchemaV1()
+	second := EditorSchemaV1()
+	firstJSON, err := json.Marshal(first)
+	if err != nil {
+		t.Fatalf("marshal first schema: %v", err)
+	}
+	secondJSON, err := json.Marshal(second)
+	if err != nil {
+		t.Fatalf("marshal second schema: %v", err)
+	}
+	if string(firstJSON) != string(secondJSON) {
+		t.Fatalf("schema output is not deterministic\nfirst: %s\nsecond: %s", firstJSON, secondJSON)
+	}
+
+	first.Nodes[0].Label = "changed"
+	first.Subjects[0].FixedKeys[0].Value = "changed"
+	first.Subjects[0].Operators[0].ValueTypes[0] = ValueTypeBoolean
+	first.Stages[0].Subjects[0] = SubjectCapability
+	third := EditorSchemaV1()
+	if third.Nodes[0].Label == "changed" ||
+		third.Subjects[0].FixedKeys[0].Value == "changed" ||
+		third.Subjects[0].Operators[0].ValueTypes[0] == ValueTypeBoolean ||
+		third.Stages[0].Subjects[0] == SubjectCapability {
+		t.Fatal("schema output shares mutable slices across calls")
+	}
+}
+
+func TestValidateStageUsesPublishedStageMatrix(t *testing.T) {
+	schema := EditorSchemaV1()
+	for _, stage := range schema.Stages {
+		allowed, err := AllowedSubjectsForStage(stage.Value)
+		if err != nil {
+			t.Fatalf("allowed subjects for %s: %v", stage.Value, err)
+		}
+		if len(allowed) != len(stage.Subjects) {
+			t.Fatalf("allowed subjects for %s = %v, schema = %v", stage.Value, allowed, stage.Subjects)
+		}
+		for _, subject := range stage.Subjects {
+			definition := schemaSubject(t, schema, subject)
+			operator := definition.Operators[0]
+			var valueType ValueType
+			if len(operator.ValueTypes) > 0 {
+				valueType = operator.ValueTypes[0]
+			}
+			expression := ExpressionV1{SchemaVersion: SchemaVersionV1, Root: &PredicateNode{
+				Subject:  subject,
+				Key:      validSchemaKey(t, definition),
+				Operator: operator.Value,
+				Value:    validSchemaValue(operator.ValueShape, valueType),
+			}}
+			if err := ValidateStage(expression, stage.Value); err != nil {
+				t.Fatalf("stage %s rejected published subject %s: %v", stage.Value, subject, err)
+			}
+		}
+	}
+
+	capability := ExpressionV1{SchemaVersion: SchemaVersionV1, Root: &PredicateNode{
+		Subject: SubjectCapability, Key: "billing", Operator: OperatorActive,
+	}}
+	if err := ValidateStage(capability, StageProductContext); err == nil {
+		t.Fatal("product_context accepted capability subject")
+	}
+	if err := ValidateStage(capability, Stage("unknown")); err == nil {
+		t.Fatal("unknown stage was accepted")
+	}
+}
+
+func validSchemaKey(t *testing.T, definition SubjectDefinition) string {
+	t.Helper()
+	switch definition.KeyShape {
+	case KeyShapeFixed:
+		if len(definition.FixedKeys) == 0 {
+			t.Fatalf("fixed subject %s has no keys", definition.Value)
+		}
+		return definition.FixedKeys[0].Value
+	case KeyShapeSnakeCode:
+		return "sample_code"
+	case KeyShapeNamespacedCode:
+		return "sample.metric"
+	default:
+		t.Fatalf("unsupported key shape %s", definition.KeyShape)
+		return ""
+	}
+}
+
+func validSchemaValue(shape ValueShape, valueType ValueType) Value {
+	switch shape {
+	case ValueShapeNone:
+		return nil
+	case ValueShapeStringArray:
+		return &StringArrayValue{Values: []string{"sample"}}
+	case ValueShapePositiveInteger:
+		return &NumberValue{Value: 60}
+	case ValueShapeComparable:
+		switch valueType {
+		case ValueTypeBoolean:
+			return &BooleanValue{Value: true}
+		case ValueTypeNumber:
+			return &NumberValue{Value: 1}
+		case ValueTypeString:
+			return &StringValue{Value: "sample"}
+		case ValueTypeStringArray:
+			return &StringArrayValue{Values: []string{"sample"}}
+		}
+	}
+	return nil
+}
+
+func schemaSubject(t *testing.T, schema EditorSchema, subject Subject) SubjectDefinition {
+	t.Helper()
+	for _, definition := range schema.Subjects {
+		if definition.Value == subject {
+			return definition
+		}
+	}
+	t.Fatalf("subject %s is missing from schema", subject)
+	return SubjectDefinition{}
+}