feature: Implement a @range expression

Author: rg0now

doc/reference-expression.md

@@ -225,6 +225,21 @@ Checks if an element exists within a list.
       - "@map": ["$$.image", "$.spec.containers"]
     ```
 
+#### `@range`
+Generates a list of sequential integers from a start value (inclusive) to an end value (exclusive).
+
+*   **Signature**: `{"@range": [<start_expression>, <end_expression>]}`
+*   **Arguments**:
+    1.  An expression that evaluates to an integer (the start value, inclusive).
+    2.  An expression that evaluates to an integer (the end value, exclusive).
+*   **Returns**: A `list` of integers `[start, start+1, ..., end-1]`. Returns an empty list if `start >= end`.
+*   **Example**:
+```yaml
+    # Generates [0, 1, 2] for a ReplicaSet with 3 replicas
+    podSlots:
+      "@range": [0, "$.spec.replicas"]
+```
+
 ### String Operators
 
 #### `@concat`

pkg/expression/expression.go

@@ -59,7 +59,7 @@ type Expression struct {
 // Evaluate processes an expression.
 func (e *Expression) Evaluate(ctx EvalCtx) (any, error) {
 	if e == nil || len(e.Op) == 0 {
-		return nil, NewInvalidArgumentsError(fmt.Sprintf("empty operator in expession %q", e.String()))
+		return nil, NewInvalidArgumentsError(fmt.Sprintf("empty operator in expression %q", e.String()))
 	}
 
 	switch e.Op {
@@ -1020,6 +1020,23 @@ func (e *Expression) Evaluate(ctx EvalCtx) (any, error) {
 
 			return v, nil
 
+		case "@range":
+			args, err := AsIntList(arg)
+			if err != nil {
+				return nil, NewExpressionError(e, err)
+			}
+			if len(args) != 2 {
+				return nil, NewExpressionError(e, errors.New("expected 2 arguments [start, end]"))
+			}
+			if args[0] > args[1] {
+				args[0] = args[1]
+			}
+			result := make([]any, 0, args[1]-args[0])
+			for i := args[0]; i < args[1]; i++ {
+				result = append(result, i)
+			}
+			return result, nil
+
 		case "@hash":
 			js, err := json.Marshal(arg)
 			if err != nil {

pkg/expression/expression_test.go

@@ -1304,6 +1304,113 @@ var _ = Describe("Expressions", func() {
 			Expect(vs).To(Equal([]any{int64(1), int64(2), int64(3), int64(4), int64(5)}))
 		})
 
+		It("should evaluate a @range sequence from 0 to n-1", func() {
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@int", Literal: int64(0)},
+					{Op: "@int", Literal: int64(5)},
+				}},
+			}
+
+			result, err := expr.Evaluate(EvalCtx{Log: logger})
+			Expect(err).NotTo(HaveOccurred())
+
+			list, ok := result.([]any)
+			Expect(ok).To(BeTrue())
+			Expect(list).To(HaveLen(5))
+			Expect(list).To(Equal([]any{int64(0), int64(1), int64(2), int64(3), int64(4)}))
+		})
+
+		It("should evaluate a @range sequence with custom start", func() {
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@int", Literal: int64(3)},
+					{Op: "@int", Literal: int64(7)},
+				}},
+			}
+
+			result, err := expr.Evaluate(EvalCtx{Log: logger})
+			Expect(err).NotTo(HaveOccurred())
+
+			list, ok := result.([]any)
+			Expect(ok).To(BeTrue())
+			Expect(list).To(HaveLen(4))
+			Expect(list).To(Equal([]any{int64(3), int64(4), int64(5), int64(6)}))
+		})
+
+		It("should return empty list on @range when start equals end", func() {
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@int", Literal: int64(5)},
+					{Op: "@int", Literal: int64(5)},
+				}},
+			}
+
+			result, err := expr.Evaluate(EvalCtx{Log: logger})
+			Expect(err).NotTo(HaveOccurred())
+
+			list, ok := result.([]any)
+			Expect(ok).To(BeTrue())
+			Expect(list).To(BeEmpty())
+		})
+
+		It("should return empty list on @range when start is greater than end", func() {
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@int", Literal: int64(10)},
+					{Op: "@int", Literal: int64(5)},
+				}},
+			}
+
+			result, err := expr.Evaluate(EvalCtx{Log: logger})
+			Expect(err).NotTo(HaveOccurred())
+
+			list, ok := result.([]any)
+			Expect(ok).To(BeTrue())
+			Expect(list).To(BeEmpty())
+		})
+
+		It("should evaluate a @range with JSONPath expressions for end value", func() {
+			obj := map[string]any{
+				"spec": map[string]any{
+					"replicas": int64(3),
+				},
+			}
+
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@int", Literal: int64(0)},
+					{Op: "@string", Literal: "$.spec.replicas"},
+				}},
+			}
+
+			result, err := expr.Evaluate(EvalCtx{Object: obj, Log: logger})
+			Expect(err).NotTo(HaveOccurred())
+
+			list, ok := result.([]any)
+			Expect(ok).To(BeTrue())
+			Expect(list).To(HaveLen(3))
+			Expect(list).To(Equal([]any{int64(0), int64(1), int64(2)}))
+		})
+
+		It("should evaluate a @range with error on non-integer arguments", func() {
+			expr := Expression{
+				Op: "@range",
+				Arg: &Expression{Op: "@list", Literal: []Expression{
+					{Op: "@string", Literal: "not-a-number"},
+					{Op: "@int", Literal: int64(5)},
+				}},
+			}
+
+			_, err := expr.Evaluate(EvalCtx{Log: logger})
+			Expect(err).To(HaveOccurred())
+		})
+
 		// It("should evaluate stacked @map expressions", func() {
 		// 	jsonData := `{"@map":[{"@lte":["$",2]},{"@first":[{"@map":["$.spec.x"]}]}]}`
 		// 	var exp Expression

pkg/expression/marshaler.go

@@ -71,6 +71,10 @@ func (e *Expression) UnmarshalJSON(b []byte) error {
 
 // UnmarshalJSON serializes an expression into JSON.
 func (e *Expression) MarshalJSON() ([]byte, error) {
+	if len(e.Op) == 0 {
+		return []byte("<nil>"), nil
+	}
+
 	switch e.Op {
 	case "@any":
 		return json.Marshal(e.Literal)
@@ -165,6 +169,9 @@ func (e *Expression) MarshalJSON() ([]byte, error) {
 
 // String stringifies an expression.
 func (e *Expression) String() string {
+	if e == nil {
+		return "<invalid>"
+	}
 	b, err := json.Marshal(e)
 	if err != nil {
 		return ""