kumi 0.0.7 → 0.0.9

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec2c56684edac64e9818bbf85de98e9855c3d50df80c490c8f868b3e9b701dab
-  data.tar.gz: d5246f98e10b0365b47f6a67fed5c3a4cbc77d5ad15905d93b046251965135f5
+  metadata.gz: c5f9f087001a482c906f041da8cb229511966a11c56e3ced99930b59d4141543
+  data.tar.gz: fe5fafe03a5ca1e414b5bc3af9eccd830553aa8f44762e9d9b38e589fa342fd1
 SHA512:
-  metadata.gz: f71ba6867b72145247b5c1ea4c3b197f831996bf078798c6a9decdb4e047f83859e062e6a6411e2311d279f8a8cc03ca7e16ac194c9a27b84f8a55b67faa3fcb
-  data.tar.gz: 70c4dab6bf036da2d507f89c2d8e9d65a24da2685412d3e517a2b3c1696d200c294c512786c85bfccf9feca301e90e70a26999f5ed1528221331b55f77175c8d
+  metadata.gz: b26279c08a9387616104252d24147c920f27b0f66574cde1987024325c5fd1ba87aff876b39fdc3d4f472d9aba2c713b19a5105890b66ac3ef10a3018a0b1bca
+  data.tar.gz: d4c8db755880cd7088fd4b6087d2f38e86a4fdee11f867d58a480e143494ca2b85440abd9249b8c02a469a9ad21642c287d5ef8f30948bdc6d67695a895c1c13

data/CLAUDE.md

@@ -62,7 +62,7 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 **Compiler** (`lib/kumi/compiler.rb`):
 - Transforms analyzed syntax tree into executable lambda functions
 - Maps each expression type to a compilation method
-- Handles function calls via `FunctionRegistry`
+- Handles function calls via `Kumi::Registry`
 - Produces `CompiledSchema` with executable bindings
 
 **Function Registry** (`lib/kumi/function_registry.rb`):

data/README.md

@@ -8,7 +8,6 @@ Kumi is a Declarative logic and rules engine framework with static analysis for
 It is well-suited for scenarios with complex, interdependent calculations, enforcing validation and consistency across your business rules while maintaining performance.
 
 
-
 ## What can you build?
 
 Calculate U.S. federal taxes:
@@ -118,16 +117,14 @@ value :monthly_payment, fn(:pmt, rate: 0.05/12, nper: 36, pv: -loan_amount)
 ```
 Note: You can find a list all core functions in [docs/FUNCTIONS.md](docs/FUNCTIONS.md)
 
-These primitives are statically analyzed during schema definition to catch logical errors before runtime.
-
 </details>
 
 <details>
-<summary><strong>🔍 Static Analysis</strong> - Catch business logic errors at definition time</summary>
+<summary><strong>🔍 Static Analysis</strong> - Catch errors at definition time and provides rich metadata</summary>
 
 ### Static Analysis
 
-Kumi catches business logic errors that cause runtime failures or silent bugs:
+Kumi catches many types of business logic errors that cause runtime failures or silent bugs:
 
 ```ruby
 module InsurancePolicyPricer
@@ -328,6 +325,19 @@ Kumi::Explain.call(FederalTax2024, :fed_tax, inputs: {income: 100_000, filing_st
 #    = 15,099.50
 ```
 
+**Debug AST Structure**: Visualize the parsed schema as S-expressions:
+
+```ruby
+puts Kumi::Support::SExpressionPrinter.print(FederalTax2024.__syntax_tree__)
+# => (Root
+#      inputs: [
+#        (InputDeclaration :income :float)
+#        (InputDeclaration :filing_status :string domain: ["single", "married_joint"])
+#      ]
+#      traits: [...]
+#      attributes: [...])
+```
+
 </details>
 
 <details>
@@ -361,6 +371,12 @@ The SchemaMetadata interface provides both processed metadata for tool developme
 
 </details>
 
+## Beyond Rules: What the Metadata Unlocks
+* **Auto-generated forms** – compile schema → field spec → React form
+* **Scenario explorer** – derive all trait combinations, Monte Carlo outcomes
+* **Coverage dashboard** – flag branches never hit in prod
+* **Schema diff** – highlight behaviour changes across versions
+
 ## Usage
 
 **Suitable for:**

data/docs/AST.md

@@ -39,6 +39,13 @@ InputReference = Struct.new(:name)
 # Has operator methods: >=, <=, >, <, ==, != that create CallExpression nodes
 ```
 
+**InputElementReference**: Access of nested input fields (`input.field_name.element.subelement.subsubelement`)
+```ruby
+InputElementReference = Struct.new(:path)
+# Represents nested input access
+# DSL: input.address.street → InputElementReference([:address, :street])
+```
+
 **DeclarationReference**: References to other declarations
 ```ruby
 DeclarationReference = Struct.new(:name)

data/docs/features/README.md

@@ -37,6 +37,13 @@ Processes large schemas with optimized algorithms.
 - Result caching
 - Selective evaluation
 
+### [S-Expression Printer](s-expression-printer.md)
+Debug and inspect AST structures with readable S-expression notation output.
+
+- Visitor pattern implementation for all node types
+- Proper indentation and hierarchical structure
+- Useful for debugging schema parsing and AST analysis
+
 ## Integration
 
 - Type inference uses input declarations

data/docs/features/s-expression-printer.md

@@ -0,0 +1,77 @@
+# S-Expression Printer
+
+Debug and inspect Kumi AST structures with readable S-expression notation output.
+
+## Overview
+
+The S-Expression Printer provides a clean, structured way to visualize Kumi's Abstract Syntax Tree (AST) nodes in traditional Lisp-style S-expression format. This is particularly useful for debugging schema parsing, understanding AST structure, and analyzing complex expressions.
+
+## Usage
+
+```ruby
+require 'kumi/support/s_expression_printer'
+
+# Print any AST node
+Kumi::Support::SExpressionPrinter.print(node)
+
+# Print a complete schema AST
+module MySchema
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      integer :age
+      string :name
+    end
+    
+    trait :adult, (input.age >= 18)
+    value :greeting, fn(:concat, "Hello ", input.name)
+  end
+end
+
+puts Kumi::Support::SExpressionPrinter.print(MySchema.__syntax_tree__)
+```
+
+## Output Format
+
+The printer produces indented S-expressions that clearly show the hierarchical structure:
+
+```lisp
+(Root
+  inputs: [
+    (InputDeclaration :age :integer)
+    (InputDeclaration :name :string)
+  ]
+  attributes: [
+    (ValueDeclaration :greeting
+      (CallExpression :concat
+        (Literal "Hello ")
+        (InputReference :name)
+      )
+    )
+  ]
+  traits: [
+    (TraitDeclaration :adult
+      (CallExpression :>=
+        (InputReference :age)
+        (Literal 18)
+      )
+    )
+  ]
+)
+```
+
+## Supported Node Types
+
+The printer handles all Kumi AST node types:
+
+- **Root** - Schema container with inputs, attributes, and traits
+- **Declarations** - InputDeclaration, ValueDeclaration, TraitDeclaration
+- **Expressions** - CallExpression, ArrayExpression, CascadeExpression, CaseExpression
+- **References** - InputReference, InputElementReference, DeclarationReference
+- **Literals** - Literal values (strings, numbers, booleans)
+- **Collections** - Arrays and HashExpression nodes
+
+## Implementation
+
+Built as a visitor pattern class that traverses AST nodes recursively, with each node type having its own specialized formatting method. The printer preserves proper indentation and handles nested structures gracefully.

data/examples/game_of_life.rb

@@ -13,7 +13,7 @@ begin
       cells[neighbor_index]
     end.sum
   end
-  Kumi::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+  Kumi::Core::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
                                                 return_type: :integer, arity: 5,
                                                 param_types: %i[array integer integer integer integer],
                                                 description: "Get neighbor cells for Conway's Game of Life")

data/examples/static_analysis_errors.rb

@@ -22,7 +22,7 @@ begin
       value :yearly_rate, monthly_rate * 12
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -48,7 +48,7 @@ begin
       end
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -71,7 +71,7 @@ begin
       value :invalid_sum, input.name + input.age
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -94,7 +94,7 @@ begin
       trait :impossible_score, input.score == 150
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -114,7 +114,7 @@ begin
       value :result, ref(:nonexistent_trait) ? 100 : 0
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -134,7 +134,7 @@ begin
       value :result, fn(:nonexistent_function, input.text)
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -162,7 +162,7 @@ begin
       value :result, ref(:undefined_declaration)
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → " + e.message.split("\n").join("\n   → ")
 end
 

data/lib/kumi/analyzer.rb

@@ -7,21 +7,21 @@ module Kumi
     module_function
 
     DEFAULT_PASSES = [
-      Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
-      Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
-      Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
-      Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
-      Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
-      Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
-      Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
-      Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
-      Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
-      Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
-      Passes::TypeChecker                      # 11. Validates types using inferred information.
+      Core::Analyzer::Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
+      Core::Analyzer::Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
+      Core::Analyzer::Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
+      Core::Analyzer::Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
+      Core::Analyzer::Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
+      Core::Analyzer::Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
+      Core::Analyzer::Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
+      Core::Analyzer::Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
+      Core::Analyzer::Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
+      Core::Analyzer::Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
+      Core::Analyzer::Passes::TypeChecker                      # 11. Validates types using inferred information.
     ].freeze
 
-    def analyze!(schema, passes: DEFAULT_PASSES, **opts)
-      state = AnalysisState.new(opts)
+    def self.analyze!(schema, passes: DEFAULT_PASSES, **opts)
+      state = Core::Analyzer::AnalysisState.new(opts)
       errors = []
 
       state = run_analysis_passes(schema, passes, state, errors)
@@ -35,7 +35,7 @@ module Kumi
         begin
           state = pass_instance.run(errors)
         rescue StandardError => e
-          errors << ErrorReporter.create_error(e.message, location: nil, type: :semantic)
+          errors << Core::ErrorReporter.create_error(e.message, location: nil, type: :semantic)
         end
       end
       state
@@ -62,7 +62,7 @@ module Kumi
     end
 
     # Handle both old and new error formats for backward compatibility
-    def format_errors(errors)
+    def self.format_errors(errors)
       return "" if errors.empty?
 
       errors.map(&:to_s).join("\n")

data/lib/kumi/compiler.rb

@@ -158,7 +158,7 @@ module Kumi
         compile_declaration(decl)
       end
 
-      CompiledSchema.new(@bindings.freeze)
+      Core::CompiledSchema.new(@bindings.freeze)
     end
 
     private
@@ -218,7 +218,7 @@ module Kumi
       return false unless broadcast_meta
 
       # Reduction functions are NOT vectorized operations - they consume arrays
-      return false if FunctionRegistry.reducer?(expr.fn_name)
+      return false if Kumi::Registry.reducer?(expr.fn_name)
 
       expr.args.any? do |arg|
         case arg
@@ -244,7 +244,7 @@ module Kumi
         vectorized_function_call(name, values)
       else
         # All arguments are scalars - regular function call
-        fn = FunctionRegistry.fetch(name)
+        fn = Kumi::Registry.fetch(name)
         fn.call(*values)
       end
     rescue StandardError => e
@@ -257,7 +257,7 @@ module Kumi
 
     def vectorized_function_call(fn_name, values)
       # Get the function from registry
-      fn = FunctionRegistry.fetch(fn_name)
+      fn = Kumi::Registry.fetch(fn_name)
 
       # Find array dimensions for broadcasting
       array_values = values.select { |v| v.is_a?(Array) }
@@ -276,14 +276,14 @@ module Kumi
     end
 
     def invoke_function(name, arg_fns, ctx, loc)
-      fn = FunctionRegistry.fetch(name)
+      fn = Kumi::Registry.fetch(name)
       values = arg_fns.map { |fn| fn.call(ctx) }
       fn.call(*values)
     rescue StandardError => e
       # Preserve original error class and backtrace while adding context
       enhanced_message = "Error calling fn(:#{name}) at #{loc}: #{e.message}"
 
-      if e.is_a?(Kumi::Errors::Error)
+      if e.is_a?(Kumi::Core::Errors::Error)
         # Re-raise Kumi errors with enhanced message but preserve type
         e.define_singleton_method(:message) { enhanced_message }
         raise e

data/lib/kumi/core/analyzer/analysis_state.rb

@@ -0,0 +1,39 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      # Simple immutable state wrapper to prevent accidental mutations between passes
+      class AnalysisState
+        def initialize(data = {})
+          @data = data.dup.freeze
+        end
+
+        # Get a value (same as hash access)
+        def [](key)
+          @data[key]
+        end
+
+        # Check if key exists (same as hash)
+        def key?(key)
+          @data.key?(key)
+        end
+
+        # Get all keys (same as hash)
+        def keys
+          @data.keys
+        end
+
+        # Create new state with additional data (simple and clean)
+        def with(key, value)
+          AnalysisState.new(@data.merge(key => value))
+        end
+
+        # Convert back to hash for final result
+        def to_h
+          @data.dup
+        end
+      end
+    end
+  end
+end

data/lib/kumi/core/analyzer/constant_evaluator.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Core
+    module Analyzer
+      class ConstantEvaluator
+        include Syntax
+
+        def initialize(definitions)
+          @definitions = definitions
+          @memo = {}
+        end
+
+        OPERATORS = {
+          add: :+,
+          subtract: :-,
+          multiply: :*,
+          divide: :/
+        }.freeze
+
+        def evaluate(node, visited = Set.new)
+          return :unknown unless node
+          return @memo[node] if @memo.key?(node)
+          return node.value if node.is_a?(Literal)
+
+          result = case node
+                   when DeclarationReference then evaluate_binding(node, visited)
+                   when CallExpression then evaluate_call_expression(node, visited)
+                   else :unknown
+                   end
+
+          @memo[node] = result unless result == :unknown
+          result
+        end
+
+        private
+
+        def evaluate_binding(node, visited)
+          return :unknown if visited.include?(node.name)
+
+          visited << node.name
+          definition = @definitions[node.name]
+          return :unknown unless definition
+
+          evaluate(definition.expression, visited)
+        end
+
+        def evaluate_call_expression(node, visited)
+          return :unknown unless OPERATORS.key?(node.fn_name)
+
+          args = node.args.map { |arg| evaluate(arg, visited) }
+          return :unknown if args.any?(:unknown)
+
+          args.reduce(OPERATORS[node.fn_name])
+        end
+      end
+    end
+  end
+end