Add Blue integration for Bex with type matching, node conversion, and tests

Author: piotr-blue

.cz.toml

@@ -2,5 +2,5 @@
 name = "cz_conventional_commits"
 tag_format = "v$version"
 version_scheme = "semver"
-version = "0.1.0"
+version = "0.2.0"
 update_changelog_on_bump = true

README.md

@@ -103,6 +103,102 @@ BexProgramSource source = BexProgramSource.withDefinition(
 );
 ```
 
+## Function Arguments And Blue Patterns
+
+BEX function arguments may declare Blue type or shape patterns. BEX does not
+have a separate type enum or type system; declared argument patterns are Blue
+nodes and runtime values are checked with Blue's node/type matcher.
+
+```yaml
+functions:
+  capture:
+    args:
+      amount:
+        type: Integer
+      hotelOrder:
+        blueId: HotelOrderBlueId
+      request:
+        customerName:
+          type: Text
+          schema:
+            required: true
+        nights:
+          type: Integer
+          schema:
+            required: true
+    expr:
+      amount:
+        $var: amount
+      order:
+        $var: hotelOrder
+```
+
+All declared function arguments are required by the function call ABI for now.
+Unknown functions, extra argument names, and missing declared arguments fail at
+compile time. Typed arguments are checked after their call expressions are
+evaluated; a runtime mismatch throws `BexException`.
+
+Text `"400"` does not match the Blue `Integer` pattern. Use an explicit
+conversion when conversion is intended:
+
+```yaml
+$call:
+  function: capture
+  args:
+    amount:
+      $integer:
+        $event: /message/request/amount
+```
+
+Untyped required arguments remain supported by declaring an empty pattern:
+
+```yaml
+args:
+  input: {}
+```
+
+When BEX converts computed values back to Blue nodes for `$is`, function
+argument checks, or output conversion, Blue language keys keep their Blue
+meaning. For example, this computed value is a node with a `type` field and a
+`status` property, not an object with an ordinary property named `type`:
+
+```yaml
+type:
+  blueId: HotelOrderType
+status: confirmed
+```
+
+A bare `blueId` object is a Blue reference pattern:
+
+```yaml
+blueId: HotelOrderType
+```
+
+Do not combine `blueId` with sibling fields to describe a typed instance. Use
+`type: { blueId: ... }` for typed values.
+
+BEX programs are Blue documents, so BEX syntax must use valid Blue authoring
+forms. For user-defined name containers such as `functions`, `constants`,
+`args`, and `$call.args`, do not use Blue language keys as names. This includes
+`value`, `items`, `blueId`, `type`, `schema`, `name`, `description`,
+`itemType`, `keyType`, `valueType`, `mergePolicy`, `constraints`, `contracts`,
+`properties`, `$previous`, and `$pos`.
+
+For operator bodies, payload/reference/control keys such as `value`, `items`,
+`blueId`, `properties`, `$previous`, and `$pos` cannot be used as ordinary
+multi-field operands. Use BEX operand names such as `node`, `list`, `input`,
+`pattern`, `object`, `key`, `path`, `val`, `cond`, `then`, and `else`.
+
+Metadata keys such as `name`, `description`, `type`, `schema`, `itemType`,
+`keyType`, and `valueType` are legal Blue language fields, but they are not
+ordinary object properties. An operator may use one of them only when the BEX
+compiler explicitly supports that field.
+
+Function argument patterns and `$is.pattern` are static Blue patterns. BEX does
+not evaluate expressions inside those patterns, and it does not emulate Blue
+authoring sugar such as inline `type: Integer` preprocessing for computed type
+fields.
+
 ## Document Views
 
 `BexDocumentView` owns document pointer resolution, canonical reads, resolved
@@ -188,13 +284,24 @@ BEX operators are Blue objects whose single key starts with `$`.
 | Operator | Purpose |
 |---|---|
 | `$unwrap` | Unwrap Blue scalar wrapper values. |
+| `$is` | Return whether a value matches a Blue pattern. |
 | `$text` | Convert to text. |
 | `$integer` | Convert to exact integer. |
 | `$number` | Convert to exact decimal/number. |
 | `$boolean` | Convert to boolean. |
 | `$object` | Require an object, or default undefined to an empty object. |
 | `$list` | Require a list, or default undefined to an empty list. |
 
+`$is.pattern` is static Blue pattern data, not a BEX expression:
+
+```yaml
+$is:
+  node:
+    $event: /message/request/amount
+  pattern:
+    type: Integer
+```
+
 ### Strings
 
 | Operator | Purpose |
@@ -205,6 +312,14 @@ BEX operators are Blue objects whose single key starts with `$`.
 | `$startsWith` | Check a prefix. |
 | `$sliceAfter` | Return text after a prefix. |
 
+```yaml
+$join:
+  list:
+    - a
+    - b
+  separator: ":"
+```
+
 ### Logic And Comparison
 
 | Operator | Purpose |
@@ -254,6 +369,10 @@ BEX operators are Blue objects whose single key starts with `$`.
 | `$call` | Call a local function. |
 | `$literal` | Return payload without compiling nested operators. |
 
+`$literal` prevents normal expression compilation, but BEX still rejects
+BEX-looking operators inside Blue type-definition fields such as `type`,
+`itemType`, `keyType`, `valueType`, `blue`, and `schema`.
+
 ## Statement Operators
 
 | Statement | Purpose |

src/main/java/blue/bex/api/BexEngine.java

@@ -10,6 +10,7 @@
 import blue.bex.result.BexExecutionResult;
 import blue.bex.result.BexMetrics;
 import blue.bex.runtime.BexRuntime;
+import blue.language.Blue;
 
 /**
  * Public entry point for compiling and executing selected BEX programs.
@@ -20,12 +21,14 @@
  * emit events, or perform host actions.</p>
  */
 public final class BexEngine {
+    private final Blue blue;
     private final BexGasSchedule gasSchedule;
     private final BexCompiledProgramCache cache;
     private final BexMetricsSink metricsSink;
     private final BexPointerCache pointerCache = new BexPointerCache();
 
     private BexEngine(Builder builder) {
+        this.blue = builder.blue;
         this.gasSchedule = builder.gasSchedule;
         this.cache = builder.cache;
         this.metricsSink = builder.metricsSink;
@@ -69,7 +72,7 @@ public BexExecutionResult execute(BexCompiledProgram program, BexExecutionContex
 
     private BexExecutionResult execute(BexCompiledProgram program, BexExecutionContext context, BexMetrics metrics) {
         long start = System.nanoTime();
-        BexRuntime runtime = new BexRuntime(program, context, gasSchedule, metrics, pointerCache);
+        BexRuntime runtime = new BexRuntime(program, context, blue, gasSchedule, metrics, pointerCache);
         BexExecutionResult result = runtime.execute();
         metrics.addExecuteNanos(System.nanoTime() - start);
         return new BexExecutionResult(result.value(),
@@ -92,10 +95,16 @@ private BexCompiledProgramKey key(BexProgramSource source) {
     }
 
     public static final class Builder {
+        private Blue blue = new Blue();
         private BexGasSchedule gasSchedule = BexGasSchedule.defaults();
         private BexCompiledProgramCache cache = new LruBexCompiledProgramCache();
         private BexMetricsSink metricsSink = BexMetricsSink.NOOP;
 
+        public Builder blue(Blue blue) {
+            this.blue = blue != null ? blue : new Blue();
+            return this;
+        }
+
         public Builder gasSchedule(BexGasSchedule gasSchedule) {
             this.gasSchedule = gasSchedule;
             return this;

src/main/java/blue/bex/compile/BexCompiledProgram.java

@@ -1,13 +1,16 @@
 package blue.bex.compile;
 
+import blue.bex.BexException;
 import blue.bex.runtime.BexRuntime;
 import blue.bex.runtime.CompiledFrame;
 import blue.bex.runtime.CompiledStatement;
 import blue.bex.runtime.Control;
 import blue.bex.runtime.CompiledExpression;
 import blue.bex.value.BexValue;
 import blue.bex.value.BexValues;
+import blue.language.snapshot.FrozenNode;
 
+import java.util.Collection;
 import java.util.Collections;
 import java.util.LinkedHashMap;
 import java.util.List;
@@ -55,35 +58,42 @@ public BexValue constant(String name) {
      */
     public static final class CompiledFunction {
         private final String name;
-        private final List<String> args;
-        private final Map<String, Integer> argSlotByName;
+        private final List<ArgSpec> args;
+        private final Map<String, ArgSpec> argByName;
+        private final ArgSpec[] argBySlot;
         private final List<CompiledStatement> statements;
         private final CompiledExpression expression;
         private final int frameSize;
 
         public CompiledFunction(String name,
-                                List<String> args,
+                                List<ArgSpec> args,
                                 List<CompiledStatement> statements,
                                 CompiledExpression expression,
                                 int frameSize) {
             this.name = name;
-            this.args = args;
-            LinkedHashMap<String, Integer> argSlots = new LinkedHashMap<>();
-            for (int i = 0; i < args.size(); i++) {
-                argSlots.put(args.get(i), i);
+            this.args = Collections.unmodifiableList(args);
+            LinkedHashMap<String, ArgSpec> argSpecs = new LinkedHashMap<>();
+            this.argBySlot = new ArgSpec[frameSize];
+            for (ArgSpec arg : args) {
+                argSpecs.put(arg.name(), arg);
+                if (arg.slot() >= 0 && arg.slot() < argBySlot.length) {
+                    argBySlot[arg.slot()] = arg;
+                }
             }
-            this.argSlotByName = Collections.unmodifiableMap(argSlots);
+            this.argByName = Collections.unmodifiableMap(argSpecs);
             this.statements = statements;
             this.expression = expression;
             this.frameSize = frameSize;
         }
 
         public String name() { return name; }
-        public List<String> args() { return args; }
+        public Collection<ArgSpec> args() { return args; }
         public int frameSize() { return frameSize; }
+        public boolean hasArg(String name) { return argByName.containsKey(name); }
+        public ArgSpec arg(String name) { return argByName.get(name); }
         public int argSlot(String name) {
-            Integer slot = argSlotByName.get(name);
-            return slot != null ? slot : -1;
+            ArgSpec arg = argByName.get(name);
+            return arg != null ? arg.slot() : -1;
         }
 
         public BexValue invokeRoot(BexRuntime runtime) {
@@ -97,6 +107,14 @@ public BexValue invokePrepared(BexRuntime runtime, CompiledFrame parent, int[] s
             for (int i = 0; i < slots.length; i++) {
                 if (slots[i] >= 0) {
                     BexValue value = values[i];
+                    ArgSpec arg = slots[i] < argBySlot.length ? argBySlot[slots[i]] : null;
+                    if (arg != null && arg.typed()
+                            && !runtime.typeMatcher().matches(value, arg.pattern())) {
+                        throw new BexException("Function " + name
+                                + " argument " + arg.name()
+                                + " does not match declared Blue pattern at "
+                                + arg.sourcePointer());
+                    }
                     frame.set(slots[i], value != null ? value : BexValues.undefined());
                 }
             }
@@ -111,4 +129,26 @@ public BexValue invokePrepared(BexRuntime runtime, CompiledFrame parent, int[] s
             return runtime.defaultResultValue();
         }
     }
+
+    public static final class ArgSpec {
+        private final String name;
+        private final int slot;
+        private final FrozenNode pattern;
+        private final boolean typed;
+        private final String sourcePointer;
+
+        public ArgSpec(String name, int slot, FrozenNode pattern, String sourcePointer) {
+            this.name = name;
+            this.slot = slot;
+            this.pattern = pattern;
+            this.typed = pattern != null && !pattern.isEmptyNode();
+            this.sourcePointer = sourcePointer;
+        }
+
+        public String name() { return name; }
+        public int slot() { return slot; }
+        public FrozenNode pattern() { return pattern; }
+        public boolean typed() { return typed; }
+        public String sourcePointer() { return sourcePointer; }
+    }
 }