kumi 0.0.5 → 0.0.7

data/docs/schema_metadata/examples.md

@@ -0,0 +1,95 @@
+# Schema Metadata Examples
+
+For comprehensive API documentation with detailed examples, see the YARD documentation in the SchemaMetadata class.
+
+## Basic Usage
+
+```ruby
+class TaxSchema
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :income, domain: 0..1_000_000
+      string :filing_status, domain: %w[single married]
+      integer :age, domain: 18..100
+    end
+
+    trait :adult, (input.age >= 18)
+    trait :high_income, (input.income > 100_000)
+
+    value :tax_rate do
+      on high_income, 0.25
+      base 0.15
+    end
+
+    value :tax_amount, input.income * tax_rate
+  end
+end
+
+# Access schema metadata - clean object interface!
+metadata = TaxSchema.schema_metadata
+
+# Processed semantic metadata (rich, transformed from AST)
+puts metadata.inputs
+# => { :income => { type: :integer, domain: {...}, required: true }, ... }
+
+puts metadata.values
+# => { :tax_rate => { type: :float, cascade: {...} }, ... }
+
+puts metadata.traits  
+# => { :adult => { type: :boolean, condition: "input.age >= 18" }, ... }
+
+# Raw analyzer state (direct from analysis passes)
+puts metadata.evaluation_order
+# => [:adult, :high_income, :tax_rate, :tax_amount]
+
+puts metadata.dependencies
+# => { :tax_amount => [#<Edge to: :tax_rate>, #<Edge to: :income>], ... }
+
+puts metadata.inferred_types
+# => { :adult => :boolean, :tax_rate => :float, :tax_amount => :float }
+
+# Serializable processed hash
+processed_hash = metadata.to_h
+puts processed_hash.keys
+# => [:inputs, :values, :traits, :functions]
+
+# Raw analyzer state (contains AST nodes)
+raw_state = metadata.analyzer_state
+puts raw_state.keys
+# => [:declarations, :inputs, :dependencies, :dependents, :leaves, :evaluation_order, :inferred_types, :cascades, :broadcasts]
+```
+
+## Tool Integration
+
+```ruby
+# Form generator example
+def generate_form_fields(schema_class)
+  metadata = schema_class.schema_metadata
+  
+  metadata.inputs.map do |field_name, field_info|
+    case field_info[:type]
+    when :integer
+      create_number_input(field_name, field_info[:domain])
+    when :string
+      create_select_input(field_name, field_info[:domain])
+    when :boolean
+      create_checkbox_input(field_name)
+    end
+  end
+end
+
+# Dependency analysis example  
+def analyze_field_dependencies(schema_class, field_name)
+  metadata = schema_class.schema_metadata
+  
+  # Find what depends on this field
+  dependents = metadata.dependents[field_name] || []
+  
+  # Find what this field depends on
+  dependencies = metadata.dependencies[field_name]&.map(&:to) || []
+  
+  { affects: dependents, requires: dependencies }
+end
+```

data/docs/schema_metadata/inferred_types.md

@@ -0,0 +1,46 @@
+# Inferred Types Metadata
+
+Type inference results for all declarations based on expression analysis.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+types = metadata.inferred_types
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Object>
+{
+  declaration_name => type_specification
+}
+```
+
+## Example
+
+```ruby
+metadata.inferred_types
+# => {
+#   :adult => :boolean,
+#   :age_group => :string, 
+#   :tax_rate => :float,
+#   :count => :integer,
+#   :item_prices => { array: :float },
+#   :categories => { array: :string }
+# }
+```
+
+## Type Values
+
+- `:boolean`, `:string`, `:integer`, `:float`, `:any`
+- `{ array: element_type }` for arrays
+- `{ hash: { key: key_type, value: value_type } }` for hashes
+
+## Usage
+
+- Type checking
+- Code generation
+- Editor support
+- Runtime validation

data/docs/schema_metadata/inputs.md

@@ -0,0 +1,86 @@
+# Input Metadata
+
+Raw input field metadata extracted from `input` blocks during analysis.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+
+# Processed input metadata (recommended for tools)
+inputs = metadata.inputs
+
+# Raw input metadata (advanced usage)
+raw_inputs = metadata.analyzer_state[:inputs]
+```
+
+## Raw Structure
+
+```ruby
+# Raw analyzer state format
+{
+  field_name => {
+    type: Symbol,           # :integer, :string, :float, :boolean, :array, etc. 
+    domain: Range|Array,    # optional domain constraints
+    children: Hash          # for array/hash types
+  }
+}
+```
+
+## Processed Structure
+
+```ruby 
+# Processed metadata format (via metadata.inputs)
+{
+  field_name => {
+    type: Symbol,           # normalized type
+    domain: Hash,           # normalized domain metadata
+    required: Boolean       # always true currently
+  }
+}
+```
+
+## Examples
+
+**Processed Input Metadata:**
+```ruby
+metadata.inputs
+# => {
+#   :age => { 
+#     type: :integer, 
+#     domain: { type: :range, min: 0, max: 120, exclusive_end: false },
+#     required: true 
+#   },
+#   :name => { type: :string, required: true },
+#   :active => { type: :boolean, required: true }
+# }
+```
+
+**Raw Input Metadata:**
+```ruby
+metadata.analyzer_state[:inputs]
+# => {
+#   :age => { type: :integer, domain: 0..120 },
+#   :name => { type: :string },
+#   :line_items => {
+#     type: :array,
+#     children: {
+#       :price => { type: :float, domain: 0..Float::INFINITY },
+#       :quantity => { type: :integer, domain: 1..100 }
+#     }
+#   }
+# }
+```
+
+**Domain Types:**
+- Range: `18..65`, `0..Float::INFINITY`
+- Array: `%w[active inactive suspended]`  
+- Proc: Custom validation functions
+
+## Usage
+
+Form generators use this metadata to:
+- Create appropriate input controls
+- Set validation rules  
+- Build nested forms for arrays
+- Generate type-safe schemas

data/docs/schema_metadata.md

@@ -0,0 +1,108 @@
+# Schema Metadata
+
+Kumi's SchemaMetadata interface provides structured access to analyzed schema information for building external tools like form generators, documentation systems, and analysis utilities.
+
+## Primary Interface
+
+SchemaMetadata is the main interface for extracting metadata from Kumi schemas:
+
+```ruby
+metadata = MySchema.schema_metadata
+```
+
+See the comprehensive API documentation in the SchemaMetadata class for detailed method documentation, examples, and usage patterns.
+
+## Processed Metadata (Tool-Friendly)
+
+These methods return clean, serializable data structures:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `inputs` | Hash | Input field metadata with normalized types and domains |
+| `values` | Hash | Value declarations with dependencies and expressions |
+| `traits` | Hash | Trait conditions with dependency information |
+| `functions` | Hash | Function registry info for functions used in schema |
+| `to_h` | Hash | Complete processed metadata (inputs, values, traits, functions) |
+| `to_json` | String | JSON serialization of processed metadata |
+| `to_json_schema` | Hash | JSON Schema document for input validation |
+
+## Raw Analyzer State (Advanced)
+
+Direct access to internal analyzer results:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| [`declarations`](schema_metadata/declarations.md) | Hash | Raw AST declaration nodes by name |
+| [`dependencies`](schema_metadata/dependencies.md) | Hash | Dependency graph with Edge objects |
+| `dependents` | Hash | Reverse dependency lookup |
+| `leaves` | Hash | Leaf nodes (no dependencies) by type |
+| [`evaluation_order`](schema_metadata/evaluation_order.md) | Array | Topologically sorted evaluation order |
+| [`inferred_types`](schema_metadata/inferred_types.md) | Hash | Type inference results for declarations |
+| [`cascades`](schema_metadata/cascades.md) | Hash | Cascade mutual exclusion analysis |
+| [`broadcasts`](schema_metadata/broadcasts.md) | Hash | Array broadcasting operation metadata |
+| `analyzer_state` | Hash | Complete raw analyzer state with AST nodes |
+
+Note: Raw `inputs` metadata is available via `analyzer_state[:inputs]` but the processed `inputs` method is recommended for tool development.
+
+## Usage Patterns
+
+```ruby
+# Tool development - use processed metadata
+metadata = MySchema.schema_metadata
+form_fields = metadata.inputs.map { |name, info| create_field(name, info) }
+documentation = metadata.values.map { |name, info| document_value(name, info) }
+
+# Advanced analysis - use raw state when needed  
+dependency_graph = metadata.dependencies
+ast_nodes = metadata.declarations
+evaluation_sequence = metadata.evaluation_order
+```
+
+## Data Structure Examples
+
+### Processed Input Metadata
+```ruby
+metadata.inputs
+# => {
+#   :age => { type: :integer, domain: { type: :range, min: 18, max: 65 }, required: true },
+#   :name => { type: :string, required: true },
+#   :items => { type: :array, required: true }
+# }
+```
+
+### Processed Value Metadata
+```ruby
+metadata.values
+# => {
+#   :tax_amount => {
+#     type: :float,
+#     dependencies: [:income, :tax_rate],
+#     computed: true,
+#     expression: "multiply(input.income, tax_rate)"
+#   }
+# }
+```
+
+### Clean Public Interface Examples
+```ruby
+# Processed dependency information (clean hashes)
+metadata.dependencies
+# => { :tax_amount => [{ to: :income, conditional: false }, { to: :tax_rate, conditional: false }] }
+
+# Processed declaration metadata (clean hashes)
+metadata.declarations  
+# => { :adult => { type: :trait, expression: ">=(input.age, 18)" }, :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" } }
+
+# Type inference results (clean data)
+metadata.inferred_types
+# => { :adult => :boolean, :tax_amount => :float, :item_totals => { array: :float } }
+```
+
+### Raw Analyzer State (Advanced Usage)
+```ruby
+# Complete raw state hash with internal objects (AST nodes, Edge objects)
+metadata.analyzer_state
+# => { declarations: {AST nodes...}, dependencies: {Edge objects...}, ... }
+```
+
+See `docs/schema_metadata/` for detailed examples.

data/examples/federal_tax_calculator_2024.rb

@@ -28,7 +28,7 @@ module FederalTaxCalculator
   schema do
     input do
       float  :income
-      string :filing_status, domain: %(single married_joint married_separate head_of_household)
+      string :filing_status, domain: %w[single married_joint married_separate head_of_household]
     end
 
     # ── standard deduction table ───────────────────────────────────────
@@ -59,7 +59,7 @@ module FederalTaxCalculator
 
     value :fed_tax,       fed_calc[0]
     value :fed_marginal,  fed_calc[1]
-    value :fed_eff,       fed_tax / f[input.income, 1.0].max
+    value :fed_eff,       fed_tax / [input.income, 1.0].max
 
     # ── FICA (employee share) ─────────────────────────────────────────────
     value :ss_wage_base, 168_600.0
@@ -96,10 +96,11 @@ module FederalTaxCalculator
   end
 end
 
-def calculate_tax(calculator, income: 1_000_000, status: "single")
+def print_tax_summary(args)
+  r = FederalTaxCalculator.from(args)
   puts "\n=== 2024 U.S. Income‑Tax Example ==="
-  printf "Income:                      $%0.2f\n", income
-  puts   "Filing status:               #{status}\n\n"
+  printf "Income:                      $%0.2f\n", args[:income]
+  puts   "Filing status:               #{args[:filing_status]}\n\n"
 
   puts "Federal tax:             $#{r[:fed_tax].round(2)} (#{(r[:fed_eff] * 100).round(2)}% effective)"
   puts "FICA tax:                $#{r[:fica_tax].round(2)} (#{(r[:fica_eff] * 100).round(2)}% effective)"
@@ -107,4 +108,8 @@ def calculate_tax(calculator, income: 1_000_000, status: "single")
   puts "After-tax income:        $#{r[:after_tax].round(2)}"
 end
 
-calculate_tax(FederalTaxCalculator, income: 1_000_000, status: "single")
+
+input = {  income: 1_000_000,
+  filing_status: "single"
+}
+print_tax_summary(input)

data/lib/kumi/analyzer/constant_evaluator.rb

@@ -23,7 +23,7 @@ module Kumi
         return node.value if node.is_a?(Literal)
 
         result = case node
-                 when Binding then evaluate_binding(node, visited)
+                 when DeclarationReference then evaluate_binding(node, visited)
                  when CallExpression then evaluate_call_expression(node, visited)
                  else :unknown
                  end

data/lib/kumi/analyzer/passes/broadcast_detector.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # Detects which operations should be broadcast over arrays
+      # DEPENDENCIES: :inputs, :declarations
+      # PRODUCES: :broadcasts
+      class BroadcastDetector < PassBase
+        def run(errors)
+          input_meta = get_state(:inputs) || {}
+          definitions = get_state(:declarations) || {}
+
+          # Find array fields with their element types
+          array_fields = find_array_fields(input_meta)
+
+          # Build compiler metadata
+          compiler_metadata = {
+            array_fields: array_fields,
+            vectorized_operations: {},
+            reduction_operations: {}
+          }
+
+          # Track which values are vectorized for type inference
+          vectorized_values = {}
+
+          # Analyze traits first, then values (to handle dependencies)
+          traits = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::TraitDeclaration) }
+          values = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::ValueDeclaration) }
+
+          (traits.to_a + values.to_a).each do |name, decl|
+            result = analyze_value_vectorization(name, decl.expression, array_fields, vectorized_values, errors)
+
+            case result[:type]
+            when :vectorized
+              compiler_metadata[:vectorized_operations][name] = result[:info]
+              # Store array source information for dimension checking
+              array_source = extract_array_source(result[:info], array_fields)
+              vectorized_values[name] = { vectorized: true, array_source: array_source }
+            when :reduction
+              compiler_metadata[:reduction_operations][name] = result[:info]
+              # Reduction produces scalar, not vectorized
+              vectorized_values[name] = { vectorized: false }
+            end
+          end
+
+          state.with(:broadcasts, compiler_metadata.freeze)
+        end
+
+        private
+
+        def find_array_fields(input_meta)
+          result = {}
+          input_meta.each do |name, meta|
+            next unless meta[:type] == :array && meta[:children]
+
+            result[name] = {
+              element_fields: meta[:children].keys,
+              element_types: meta[:children].transform_values { |v| v[:type] || :any }
+            }
+          end
+          result
+        end
+
+        def analyze_value_vectorization(name, expr, array_fields, vectorized_values, errors)
+          case expr
+          when Kumi::Syntax::InputElementReference
+            if array_fields.key?(expr.path.first)
+              { type: :vectorized, info: { source: :array_field_access, path: expr.path } }
+            else
+              { type: :scalar }
+            end
+
+          when Kumi::Syntax::DeclarationReference
+            # Check if this references a vectorized value
+            vector_info = vectorized_values[expr.name]
+            if vector_info && vector_info[:vectorized]
+              { type: :vectorized, info: { source: :vectorized_declaration, name: expr.name } }
+            else
+              { type: :scalar }
+            end
+
+          when Kumi::Syntax::CallExpression
+            analyze_call_vectorization(name, expr, array_fields, vectorized_values, errors)
+
+          when Kumi::Syntax::CascadeExpression
+            analyze_cascade_vectorization(name, expr, array_fields, vectorized_values, errors)
+
+          else
+            { type: :scalar }
+          end
+        end
+
+        def analyze_call_vectorization(_name, expr, array_fields, vectorized_values, errors)
+          # Check if this is a reduction function using function registry metadata
+          if FunctionRegistry.reducer?(expr.fn_name)
+            # Only treat as reduction if the argument is actually vectorized
+            arg_info = analyze_argument_vectorization(expr.args.first, array_fields, vectorized_values)
+            if arg_info[:vectorized]
+              { type: :reduction, info: { function: expr.fn_name, source: arg_info[:source] } }
+            else
+              # Not a vectorized reduction - just a regular function call
+              { type: :scalar }
+            end
+
+          else
+            # Special case: all?, any?, none? functions with vectorized trait arguments should be treated as vectorized
+            # for cascade condition purposes (they get transformed during compilation)
+            if %i[all? any? none?].include?(expr.fn_name) && expr.args.length == 1
+              arg = expr.args.first
+              if arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.length == 1
+                trait_ref = arg.elements.first
+                if trait_ref.is_a?(Kumi::Syntax::DeclarationReference) && vectorized_values[trait_ref.name]&.[](:vectorized)
+                  return { type: :vectorized, info: { source: :cascade_condition_with_vectorized_trait, trait: trait_ref.name } }
+                end
+              end
+            end
+
+            # ANY function with vectorized arguments becomes vectorized (with broadcasting)
+            arg_infos = expr.args.map { |arg| analyze_argument_vectorization(arg, array_fields, vectorized_values) }
+
+            if arg_infos.any? { |info| info[:vectorized] }
+              # Check for dimension mismatches when multiple arguments are vectorized
+              vectorized_sources = arg_infos.select { |info| info[:vectorized] }.filter_map { |info| info[:array_source] }.uniq
+
+              if vectorized_sources.length > 1
+                # Multiple different array sources - this is a dimension mismatch
+                # Generate enhanced error message with type information
+                enhanced_message = build_dimension_mismatch_error(expr, arg_infos, array_fields, vectorized_sources)
+
+                report_error(errors, enhanced_message, location: expr.loc, type: :semantic)
+                return { type: :scalar } # Treat as scalar to prevent further errors
+              end
+
+              # This is a vectorized operation - ANY function supports broadcasting
+              { type: :vectorized, info: {
+                operation: expr.fn_name,
+                vectorized_args: arg_infos.map.with_index { |info, i| [i, info[:vectorized]] }.to_h
+              } }
+            else
+              { type: :scalar }
+            end
+          end
+        end
+
+        def analyze_argument_vectorization(arg, array_fields, vectorized_values)
+          case arg
+          when Kumi::Syntax::InputElementReference
+            if array_fields.key?(arg.path.first)
+              { vectorized: true, source: :array_field, array_source: arg.path.first }
+            else
+              { vectorized: false }
+            end
+
+          when Kumi::Syntax::DeclarationReference
+            # Check if this references a vectorized value
+            vector_info = vectorized_values[arg.name]
+            if vector_info && vector_info[:vectorized]
+              array_source = vector_info[:array_source]
+              { vectorized: true, source: :vectorized_value, array_source: array_source }
+            else
+              { vectorized: false }
+            end
+
+          when Kumi::Syntax::CallExpression
+            # Recursively check
+            result = analyze_value_vectorization(nil, arg, array_fields, vectorized_values, [])
+            { vectorized: result[:type] == :vectorized, source: :expression }
+
+          else
+            { vectorized: false }
+          end
+        end
+
+        def extract_array_source(info, _array_fields)
+          case info[:source]
+          when :array_field_access
+            info[:path]&.first
+          when :cascade_condition_with_vectorized_trait
+            # For cascades, we'd need to trace back to the original source
+            nil # TODO: Could be enhanced to trace through trait dependencies
+          end
+        end
+
+        def analyze_cascade_vectorization(_name, expr, array_fields, vectorized_values, errors)
+          # A cascade is vectorized if:
+          # 1. Any of its result expressions are vectorized, OR
+          # 2. Any of its conditions reference vectorized values (traits or arrays)
+          vectorized_results = []
+          vectorized_conditions = []
+
+          expr.cases.each do |case_expr|
+            # Check if result is vectorized
+            result_info = analyze_value_vectorization(nil, case_expr.result, array_fields, vectorized_values, errors)
+            vectorized_results << (result_info[:type] == :vectorized)
+
+            # Check if condition is vectorized
+            condition_info = analyze_value_vectorization(nil, case_expr.condition, array_fields, vectorized_values, errors)
+            vectorized_conditions << (condition_info[:type] == :vectorized)
+          end
+
+          if vectorized_results.any? || vectorized_conditions.any?
+            { type: :vectorized, info: { source: :cascade_with_vectorized_conditions_or_results } }
+          else
+            { type: :scalar }
+          end
+        end
+
+        def build_dimension_mismatch_error(_expr, arg_infos, array_fields, vectorized_sources)
+          # Build detailed error message with type information
+          summary = "Cannot broadcast operation across arrays from different sources: #{vectorized_sources.join(', ')}. "
+
+          problem_desc = "Problem: Multiple operands are arrays from different sources:\n"
+
+          vectorized_args = arg_infos.select { |info| info[:vectorized] }
+          vectorized_args.each_with_index do |arg_info, index|
+            array_source = arg_info[:array_source]
+            next unless array_source && array_fields[array_source]
+
+            # Determine the type based on array field metadata
+            type_desc = determine_array_type(array_source, array_fields)
+            problem_desc += "  - Operand #{index + 1} resolves to #{type_desc} from array '#{array_source}'\n"
+          end
+
+          explanation = "Direct operations on arrays from different sources is ambiguous and not supported. " \
+                        "Vectorized operations can only work on fields from the same array input."
+
+          "#{summary}#{problem_desc}#{explanation}"
+        end
+
+        def determine_array_type(array_source, array_fields)
+          field_info = array_fields[array_source]
+          return "array(any)" unless field_info[:element_types]
+
+          # For nested arrays (like items.name where items is an array), this represents array(element_type)
+          element_types = field_info[:element_types].values.uniq
+          if element_types.length == 1
+            "array(#{element_types.first})"
+          else
+            "array(mixed)"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/analyzer/passes/{definition_validator.rb → declaration_validator.rb}

@@ -7,7 +7,7 @@ module Kumi
       # DEPENDENCIES: :definitions
       # PRODUCES: None (validation only)
       # INTERFACE: new(schema, state).run(errors)
-      class DefinitionValidator < VisitorPass
+      class DeclarationValidator < VisitorPass
         def run(errors)
           each_decl do |decl|
             visit(decl) { |node| validate_node(node, errors) }
@@ -19,9 +19,9 @@ module Kumi
 
         def validate_node(node, errors)
           case node
-          when Declarations::Attribute
+          when Kumi::Syntax::ValueDeclaration
             validate_attribute(node, errors)
-          when Declarations::Trait
+          when Kumi::Syntax::TraitDeclaration
             validate_trait(node, errors)
           end
         end
@@ -33,7 +33,7 @@ module Kumi
         end
 
         def validate_trait(node, errors)
-          return if node.expression.is_a?(Expressions::CallExpression)
+          return if node.expression.is_a?(Kumi::Syntax::CallExpression)
 
           report_error(errors, "trait `#{node.name}` must wrap a CallExpression", location: node.loc)
         end