feat: implement literal argument handling in pipeline operations

Author: ziflex

README.md

@@ -21,20 +21,20 @@ go get github.com/MontFerret/cssx
 package main
 
 import (
-    "fmt"
+	"fmt"
 
-    "github.com/MontFerret/cssx"
+	"github.com/MontFerret/cssx"
 )
 
 func main() {
-    pipeline, err := cssx.Compile(":text(:first(h1))")
-    if err != nil {
-        panic(err)
-    }
-
-    for _, op := range pipeline.Ops {
-        fmt.Printf("%s: %+v\n", op.Kind, op)
-    }
+	pipeline, err := cssx.Compile(`:attr("href", :first(a.cta))`)
+	if err != nil {
+		panic(err)
+	}
+
+	for _, op := range pipeline.Ops {
+		fmt.Printf("%s: %+v\n", op.Kind, op)
+	}
 }
 ```
 
@@ -48,22 +48,26 @@ Humans write nested pseudo calls like:
 
 cssx compiles them into a linear postfix pipeline:
 
-- native CSS selector steps (`Select`)
-- pseudo/function steps (`Call`)
-- constants (`Str`, `Num`)
+- selector steps (`Select`)
+- call steps (`Call`)
+- literal call args embedded in each `Call.Args`
 
 Example:
 
 Input:
 
 ```
-:text(:first(h1))
+:attr("href", :first(a.cta))
 ```
 
 Pipeline:
 
 ```
-[Select("h1"), Call("first",1), Call("text",1)]
+[
+  Select("a.cta"),
+  Call("first", Arity:1, Args:[]),
+  Call("attr", Arity:1, Args:[String("href")]),
+]
 ```
 
 ## Syntax
@@ -113,37 +117,56 @@ Rules:
 Compiles to:
 
 ```
-[Select(".section .item"), Num(2), Call("nth",1), Call("text",0)]
+[
+  Select(".section .item"),
+  Call("nth", Arity:0, Args:[Number(2)]),
+  Call("text", Arity:0, Args:[]),
+]
 ```
 
-## Supported Examples
+## IR Contract
+
+### `Arity`
 
-Plain selectors:
+`Op.Arity` is the number of non-literal expression args consumed from the stack.
 
-- `.product` -> `[Select(".product")]`
-- `.section .item` -> `[Select(".section .item")]`
+### `Args`
 
-Single pseudo:
+`Op.Args` contains only literal arguments (`string` or `number`) in source order.
 
-- `:count(.product)` -> `[Select(".product"), Call("count",1)]`
-- `:first(section)` -> `[Select("section"), Call("first",1)]`
+### `literals-first` rule
 
-Nested pseudos:
+Literal args must come before expression args inside a call.
 
-- `:text(:first(h1))` -> `[Select("h1"), Call("first",1), Call("text",1)]`
-- `:attr("href", :first(a.cta))` -> `[Str("href"), Select("a.cta"), Call("first",1), Call("attr",2)]`
+Valid:
 
-Selectors with commas inside:
+- `:foo("x", 2, :bar(a))`
 
-- `:first(a[href*="x,y"])` -> `[Select("a[href*="x,y"]"), Call("first",1)]`
+Invalid:
 
-Mixed readability:
+- `:foo(:bar(a), "x")`
+- `:foo(1, :bar(a), 2)`
 
-- `:text(:nth(2, .section .item))` -> `[Num(2), Select(".section .item"), Call("nth",2), Call("text",1)]`
+Invalid calls fail at compile time with:
 
-Pipeline sugar:
+- `literal args must precede expression args`
 
-- `.section .item >> :nth(2) >> :text()` -> `[Select(".section .item"), Num(2), Call("nth",1), Call("text",0)]`
+## Supported Examples
+
+- `.product`
+  - `[Select(".product")]`
+- `:count(.product)`
+  - `[Select(".product"), Call("count", Arity:1, Args:[])]`
+- `:text(:first(h1))`
+  - `[Select("h1"), Call("first", Arity:1, Args:[]), Call("text", Arity:1, Args:[])]`
+- `:attr("href", :first(a.cta))`
+  - `[Select("a.cta"), Call("first", Arity:1, Args:[]), Call("attr", Arity:1, Args:[String("href")])]`
+- `:first(a[href*="x,y"])`
+  - `[Select("a[href*=\"x,y\"]"), Call("first", Arity:1, Args:[])]`
+- `:text(:nth(2, .section .item))`
+  - `[Select(".section .item"), Call("nth", Arity:1, Args:[Number(2)]), Call("text", Arity:1, Args:[])]`
+- `.section .item >> :nth(2) >> :text()`
+  - `[Select(".section .item"), Call("nth", Arity:0, Args:[Number(2)]), Call("text", Arity:0, Args:[])]`
 
 ## Public API
 
@@ -167,36 +190,42 @@ Key types:
 
 ```go
 type Pipeline struct {
-    Ops []Op
+	Ops []Op
 }
 
 type Op struct {
-    Kind     OpKind
-    Selector string
-    Name     string
-    Arity    int
-    Str      string
-    Num      float64
+	Kind     OpKind
+	Selector string
+	Name     string
+	Arity    int
+	Args     []CallArg
+}
+
+type CallArg struct {
+	Kind CallArgKind
+	Str  string
+	Num  float64
 }
 
 type ParseError struct {
-    Message string
-    Pos int // byte offset
+	Message string
+	Pos     int // byte offset
 }
 ```
 
 ## Error Handling
 
-All syntax errors return `*ParseError` with a byte offset position.
+All syntax errors and compile-time IR validation errors return `*ParseError` with a byte offset position.
 
 Common error cases:
 
 - `:` (missing identifier)
 - `:text(` (unterminated call)
-- `:text(:first(h1)` (missing `)`)
+- `:text(:first(h1)` (missing `)`) 
 - `:attr("href" :first(a))` (missing comma)
 - empty input (whitespace only)
 - pipeline stage without `:name(...)`
+- mixed call arg order violating literals-first
 
 ## Non-Goals
 

bench_test.go

@@ -16,8 +16,10 @@ var benchInputs = []struct {
 }
 
 func BenchmarkParse(b *testing.B) {
+	b.ReportAllocs()
 	for _, tc := range benchInputs {
 		b.Run(tc.name, func(b *testing.B) {
+			b.ReportAllocs()
 			for i := 0; i < b.N; i++ {
 				if _, err := Parse(tc.input); err != nil {
 					b.Fatal(err)
@@ -28,6 +30,7 @@ func BenchmarkParse(b *testing.B) {
 }
 
 func BenchmarkBuildPipeline(b *testing.B) {
+	b.ReportAllocs()
 	asts := make([]AST, len(benchInputs))
 	for i, tc := range benchInputs {
 		ast, err := Parse(tc.input)
@@ -41,6 +44,7 @@ func BenchmarkBuildPipeline(b *testing.B) {
 	for i, tc := range benchInputs {
 		ast := asts[i]
 		b.Run(tc.name, func(b *testing.B) {
+			b.ReportAllocs()
 			for i := 0; i < b.N; i++ {
 				if _, err := BuildPipeline(ast); err != nil {
 					b.Fatal(err)
@@ -51,8 +55,10 @@ func BenchmarkBuildPipeline(b *testing.B) {
 }
 
 func BenchmarkCompile(b *testing.B) {
+	b.ReportAllocs()
 	for _, tc := range benchInputs {
 		b.Run(tc.name, func(b *testing.B) {
+			b.ReportAllocs()
 			for i := 0; i < b.N; i++ {
 				if _, err := Compile(tc.input); err != nil {
 					b.Fatal(err)

parser_test.go

@@ -47,6 +47,16 @@ func TestParsePipelineSugar(t *testing.T) {
 	}
 }
 
+func TestParseMixedArgOrderAllowed(t *testing.T) {
+	ast, err := Parse(":foo(:bar(a), \"x\")")
+	if err != nil {
+		t.Fatalf("unexpected parse error: %v", err)
+	}
+	if _, ok := ast.Expr.(*CallExpr); !ok {
+		t.Fatalf("expected CallExpr, got %T", ast.Expr)
+	}
+}
+
 func TestParseErrors(t *testing.T) {
 	cases := []string{
 		":",

pipeline.go

@@ -8,8 +8,6 @@ type OpKind int
 const (
 	OpSelect OpKind = iota
 	OpCall
-	OpStr
-	OpNum
 )
 
 func (k OpKind) String() string {
@@ -18,23 +16,33 @@ func (k OpKind) String() string {
 		return "Select"
 	case OpCall:
 		return "Call"
-	case OpStr:
-		return "Str"
-	case OpNum:
-		return "Num"
 	default:
 		return fmt.Sprintf("OpKind(%d)", int(k))
 	}
 }
 
+// CallArgKind identifies the kind of a call literal argument.
+type CallArgKind int
+
+const (
+	CallArgString CallArgKind = iota
+	CallArgNumber
+)
+
+// CallArg is an embedded literal argument for a call operation.
+type CallArg struct {
+	Kind CallArgKind
+	Str  string
+	Num  float64
+}
+
 // Op is a single pipeline operation in postfix order.
 type Op struct {
 	Kind     OpKind
 	Selector string
 	Name     string
 	Arity    int
-	Str      string
-	Num      float64
+	Args     []CallArg
 }
 
 // Pipeline is a linear postfix pipeline representation.
@@ -59,16 +67,11 @@ func buildExpr(expr Expr, p *Pipeline) error {
 	case *SelectorExpr:
 		p.Ops = append(p.Ops, Op{Kind: OpSelect, Selector: e.Raw})
 	case *StringLit:
-		p.Ops = append(p.Ops, Op{Kind: OpStr, Str: e.Value})
+		return &ParseError{Message: "literal values are only allowed as call arguments", Pos: e.Pos()}
 	case *NumberLit:
-		p.Ops = append(p.Ops, Op{Kind: OpNum, Num: e.Value})
+		return &ParseError{Message: "literal values are only allowed as call arguments", Pos: e.Pos()}
 	case *CallExpr:
-		for _, arg := range e.Args {
-			if err := buildExpr(arg, p); err != nil {
-				return err
-			}
-		}
-		p.Ops = append(p.Ops, Op{Kind: OpCall, Name: e.Name, Arity: len(e.Args)})
+		return buildCall(e, p)
 	case *PipelineExpr:
 		if e.Base == nil {
 			return &ParseError{Message: "pipeline missing base selector", Pos: e.Pos()}
@@ -87,6 +90,33 @@ func buildExpr(expr Expr, p *Pipeline) error {
 	return nil
 }
 
+func buildCall(call *CallExpr, p *Pipeline) error {
+	op := Op{Kind: OpCall, Name: call.Name}
+	seenExpr := false
+	for _, arg := range call.Args {
+		switch a := arg.(type) {
+		case *StringLit:
+			if seenExpr {
+				return &ParseError{Message: "literal args must precede expression args", Pos: a.Pos()}
+			}
+			op.Args = append(op.Args, CallArg{Kind: CallArgString, Str: a.Value})
+		case *NumberLit:
+			if seenExpr {
+				return &ParseError{Message: "literal args must precede expression args", Pos: a.Pos()}
+			}
+			op.Args = append(op.Args, CallArg{Kind: CallArgNumber, Num: a.Value})
+		default:
+			seenExpr = true
+			if err := buildExpr(arg, p); err != nil {
+				return err
+			}
+			op.Arity++
+		}
+	}
+	p.Ops = append(p.Ops, op)
+	return nil
+}
+
 // Compile parses input and builds a pipeline.
 func Compile(input string) (Pipeline, error) {
 	ast, err := Parse(input)