feat!: Rego -> RVM Compiler and extensive testsuite (#506)

# RVM compiler test cases

Coverage:
- arithmetic
- arrays
- chained lookups
- comparisons
- comprehensions
- default rules
- destructuring
- function rules
- loops/quantifiers
- multiple entrypoints
- objects/sets
- variables
- negative/edge scenarios such as data/rule conflicts
- virtual data lookups
- etc

 # Modify interpreter and compiled policy for RVM Compilation

- Interpreter::eval_default_rule_for_compiler:
   evaluates a named default rule in isolation - allows compiler to emit a constant value instead of instructions
   for the default value

#  feat: Rego Compiler Scaffolding

- Introduce the rego::compiler module surface and entry point wiring
- Add the core compiler concepts:
  - register allocator
  - scope tracking
  - literal/builtin tables
  - rule worklists
  - instruction emit helpers
  - compiler-specific error types
  - context structs for rules, comprehensions, and loops to support later lowering passes.

# feat: Compile Rules/Queries

- add compiler::compile_from_policy workflow plus rule worklist, entry-point wiring, and recursion checks
- implement query lowering:
  - scheduling-aware statement ordering
  - loop hoisting
  - “every/some” semantics
  - context yields
  -  literal assertions
- finalize Program construction

# feat: Expression Lowering

- add compile_rego_expr and helpers to translate every AST expression into RVM instructions,
- interop with binding plans, comprehensions, and membership checks.
- implement collection literal builders (ArrayCreate, SetCreate, ObjectCreate)
  - dedupe literal keys and handle mixed literal/dynamic fields via instruction data blocks.
- operations:
  - arithmetic/boolean/bin operators
  - membership
  - unary minus
  - set unions/intersections
  - etc
- user-defined and builtin function calls
- reference handling
  - analyse chained refs
  - distinguishe data/input/local roots
  - perform rule dispatch or virtual document lookups
  - emits optimized Index/ChainedIndex instructions.

# feat: Comprehensions & Loops

- shared comprehension emitter
 - wraps array/set/object comprehensions with ComprehensionBegin/End
 - context management
- loop lowering utilities
 - read hoisting metadata
 - emit LoopStart/LoopNext
 - some in lowering
 - every quantifiers
 - index iteration
 - propagate binding plans into stored registers so downstream statements see bound variables.

# feat: Destructuring Lowering

- destructuring planner integration
 - assignment/parameter/loop bindings use hoisted plans instead of re-walking ASTs.
- handle :=, =, wildcard matches, and equality
 - evaluate RHS
 - applying destructuring plans
 - emit assert condition as needed
- support nested array/object destructuring, dynamic keys, and some ... in forms

# test: Shared Testing + RVM Suites

- move YAML test helpers into test_utils.rs and re-export via common.rs for use by interpreter and vm test suites
- comprehensive compiler test suite
  - compiles policies with the new Rego→RVM compiler
  - runs them through RegoVM
  - compares against interpreter behavior
  - supports multiple entry points
  - provides assembly listings
  - filterable YAML suites.

Signed-off-by: Anand Krishnamoorthi <anakrish@microsoft.com>

src/languages/rego/compiler/program.rs

@@ -0,0 +1,161 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+use super::{Compiler, Result};
+use crate::interpreter::Interpreter;
+use crate::rvm::program::{Program, RuleType, SpanInfo};
+use crate::rvm::Instruction;
+use crate::Rc;
+use crate::Value;
+use alloc::collections::BTreeMap;
+use alloc::format;
+use alloc::string::{String, ToString};
+use alloc::vec;
+use alloc::vec::Vec;
+
+impl<'a> Compiler<'a> {
+    pub(super) fn emit_return(&mut self, result_reg: super::Register) {
+        self.program
+            .instructions
+            .push(Instruction::Return { value: result_reg });
+        self.spans.push(SpanInfo::new(0, 0, 0, 0));
+    }
+
+    pub(super) fn emit_call_rule(&mut self, dest: super::Register, rule_index: u16) {
+        self.program
+            .instructions
+            .push(Instruction::CallRule { dest, rule_index });
+        self.spans.push(SpanInfo::new(0, 0, 0, 0));
+    }
+
+    pub(super) fn finish(mut self) -> Result<Program> {
+        self.program.main_entry_point = 0;
+
+        self.program.max_rule_window_size =
+            self.rule_num_registers.iter().cloned().max().unwrap_or(0) as usize;
+        self.program.dispatch_window_size = self.register_counter as usize;
+
+        let mut rule_infos_map = BTreeMap::new();
+
+        let function_rule_indices: Vec<u16> = self
+            .rule_index_map
+            .values()
+            .copied()
+            .filter(|&rule_index| self.rule_function_param_count[rule_index as usize].is_some())
+            .collect();
+
+        let mut all_destructuring_blocks = BTreeMap::new();
+        for rule_index in function_rule_indices {
+            let destructuring_blocks = self.extract_destructuring_blocks(rule_index);
+            all_destructuring_blocks.insert(rule_index, destructuring_blocks);
+        }
+
+        for (rule_path, &rule_index) in &self.rule_index_map {
+            let definitions = self.rule_definitions[rule_index as usize].clone();
+            let rule_type = self.rule_types[rule_index as usize].clone();
+            let function_param_count = &self.rule_function_param_count[rule_index as usize];
+            let result_register = self.rule_result_registers[rule_index as usize];
+            let num_registers = self.rule_num_registers[rule_index as usize];
+
+            let destructuring_blocks = all_destructuring_blocks
+                .get(&rule_index)
+                .cloned()
+                .unwrap_or_else(|| vec![None; definitions.len()]);
+
+            let mut rule_info = match function_param_count {
+                Some(param_count) => {
+                    let definition_params =
+                        &self.rule_definition_function_params[rule_index as usize];
+                    let param_names =
+                        if let Some(Some(first_def_params)) = definition_params.first() {
+                            first_def_params.clone()
+                        } else {
+                            (0..*param_count).map(|i| format!("param_{}", i)).collect()
+                        };
+
+                    crate::rvm::program::RuleInfo::new_function(
+                        rule_path.clone(),
+                        rule_type,
+                        Rc::new(definitions),
+                        param_names,
+                        result_register,
+                        num_registers,
+                    )
+                }
+                None => crate::rvm::program::RuleInfo::new(
+                    rule_path.clone(),
+                    rule_type,
+                    Rc::new(definitions),
+                    result_register,
+                    num_registers,
+                ),
+            };
+
+            rule_info.destructuring_blocks = destructuring_blocks;
+            rule_infos_map.insert(rule_index as usize, rule_info);
+        }
+
+        let rule_paths_to_evaluate: Vec<(String, usize)> = self
+            .rule_index_map
+            .iter()
+            .filter_map(|(rule_path, &rule_index)| {
+                let rule_type = &self.rule_types[rule_index as usize];
+                if *rule_type == RuleType::Complete {
+                    Some((rule_path.clone(), rule_index as usize))
+                } else {
+                    None
+                }
+            })
+            .collect();
+
+        for (rule_path, rule_index) in rule_paths_to_evaluate {
+            if let Some(default_literal_index) = self.evaluate_default_rule(&rule_path) {
+                if let Some(rule_info) = rule_infos_map.get_mut(&rule_index) {
+                    rule_info.set_default_literal_index(default_literal_index);
+                }
+            }
+        }
+
+        self.program.rule_infos = rule_infos_map.into_values().collect();
+
+        for module in self.policy.get_modules().iter() {
+            let source = &module.package.refr.span().source;
+            let source_path = source.get_path().to_string();
+            let source_content = source.get_contents().to_string();
+            self.program.add_source(source_path, source_content);
+        }
+
+        self.program.instruction_spans = self.spans.into_iter().map(Some).collect();
+        self.program.entry_points = self.entry_points;
+
+        if !self.program.builtin_info_table.is_empty() {
+            self.program.initialize_resolved_builtins()?;
+        }
+
+        Ok(self.program)
+    }
+
+    fn evaluate_default_rule(&mut self, rule_path: &str) -> Option<u16> {
+        if !self.policy.inner.default_rules.contains_key(rule_path) {
+            return None;
+        }
+
+        let mut interpreter = Interpreter::new_from_compiled_policy(self.policy.inner.clone());
+
+        match interpreter.eval_default_rule_for_compiler(rule_path) {
+            Ok(computed_value) => {
+                if computed_value != Value::Undefined {
+                    let literal_index = self.add_literal(computed_value);
+                    return Some(literal_index);
+                }
+            }
+            Err(_e) => {}
+        }
+
+        None
+    }
+
+    fn extract_destructuring_blocks(&self, rule_index: u16) -> Vec<Option<u32>> {
+        self.rule_definition_destructuring_patterns[rule_index as usize].clone()
+    }
+}