kumi 0.0.0 → 0.0.4

data/examples/federal_tax_calculator_2024.rb

@@ -0,0 +1,112 @@
+# U.S. federal income‑tax plus FICA
+
+require_relative "../lib/kumi"
+
+module CompositeTax2024
+  extend Kumi::Schema
+  FED_BREAKS_SINGLE   = [11_600, 47_150, 100_525, 191_950,
+                         243_725, 609_350, Float::INFINITY]
+
+  FED_BREAKS_MARRIED  = [23_200, 94_300, 201_050, 383_900,
+                         487_450, 731_200, Float::INFINITY]
+
+  FED_BREAKS_SEPARATE = [11_600, 47_150, 100_525, 191_950,
+                         243_725, 365_600, Float::INFINITY]
+
+  FED_BREAKS_HOH      = [16_550, 63_100, 100_500, 191_950,
+                         243_700, 609_350, Float::INFINITY]
+  
+  FED_RATES           = [0.10, 0.12, 0.22, 0.24,
+                         0.32, 0.35, 0.37]
+
+  schema do
+    input do
+      float  :income
+      string :filing_status
+    end
+
+    # ── standard deduction table ───────────────────────────────────────
+    trait :single,     input.filing_status == "single"
+    trait :married,    input.filing_status == "married_joint"
+    trait :separate,   input.filing_status == "married_separate"
+    trait :hoh,        input.filing_status == "head_of_household"
+
+    value :std_deduction do
+      on  :single,   14_600
+      on  :married,  29_200
+      on  :separate, 14_600
+      base           21_900 # HOH default
+    end
+
+    value :taxable_income,
+          fn(:max, [input.income - std_deduction, 0])
+
+    # ── FEDERAL brackets (single shown; others similar if needed) ──────
+    value :fed_breaks do
+      on  :single,   FED_BREAKS_SINGLE
+      on  :married,  FED_BREAKS_MARRIED
+      on  :separate, FED_BREAKS_SEPARATE
+      on  :hoh,      FED_BREAKS_HOH
+    end
+
+    value :fed_rates,  FED_RATES
+    value :fed_calc,
+          fn(:piecewise_sum, taxable_income, fed_breaks, fed_rates)
+
+    value :fed_tax,       fed_calc[0]
+    value :fed_marginal,  fed_calc[1]
+    value :fed_eff,       fed_tax / fn(:max, [input.income, 1.0])
+
+    # ── FICA (employee share) ─────────────────────────────────────────────
+    value :ss_wage_base, 168_600.0
+    value :ss_rate,      0.062
+
+    value :med_base_rate, 0.0145
+    value :addl_med_rate, 0.009
+
+    # additional‑Medicare threshold depends on filing status
+    value :addl_threshold do
+      on  :single,   200_000
+      on  :married,  250_000
+      on  :separate, 125_000
+      base           200_000 # HOH same as single
+    end
+
+    # social‑security portion (capped)
+    value :ss_tax,
+          fn(:min, [input.income, ss_wage_base]) * ss_rate
+
+    # medicare (1.45 % on everything)
+    value :med_tax, input.income * med_base_rate
+
+    # additional medicare on income above threshold
+    value :addl_med_tax,
+          fn(:max, [input.income - addl_threshold, 0]) * addl_med_rate
+
+    value :fica_tax,  ss_tax + med_tax + addl_med_tax
+    value :fica_eff,  fica_tax / fn(:max, [input.income, 1.0])
+
+    # ── Totals ─────────────────────────────────────────────────────────
+    value :total_tax,
+          fed_tax + fica_tax
+
+    value :total_eff,   total_tax / fn(:max, [input.income, 1.0])
+    value :after_tax,   input.income - total_tax
+  end
+end
+
+def example(income: 1_000_000, status: "single")
+  # Create a runner for the schema
+  r = CompositeTax2024.from(income: income, filing_status: status)
+  # puts r.inspect
+  puts "\n=== 2024 U.S. Income‑Tax Example ==="
+  printf "Income:                      $%0.2f\n", income
+  puts   "Filing status:               #{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)"
+  puts "Total tax:               $#{r[:total_tax].round(2)} (#{(r[:total_eff] * 100).round(2)}% effective)"
+  puts "After-tax income:        $#{r[:after_tax].round(2)}"
+end
+
+example

data/examples/wide_schema_compilation_and_evaluation_benchmark.rb

@@ -0,0 +1,80 @@
+# Wide Schema Compilation and Evaluation Benchmark
+#
+# This benchmark measures Kumi's performance with increasingly wide schemas
+# to understand how compilation and evaluation times scale with schema complexity.
+#
+# What it tests:
+# - Compilation time for schemas with 1k, 5k, and 10k value declarations  
+# - Evaluation performance for computing aggregated results from many values
+# - Memory efficiency through memoized schema compilation
+#
+# Schema structure:
+# - input: single integer seed
+# - values: v1 = seed + 1, v2 = seed + 2, ..., v_n = seed + n  
+# - aggregations: sum_all, avg_all
+# - trait: large_total (conditional logic)
+# - cascade: final_total (depends on trait evaluation)
+#
+# Usage: bundle exec ruby examples/wide_schema_compilation_and_evaluation_benchmark.rb
+require "benchmark"
+require "benchmark/ips"
+require_relative "../lib/kumi"
+
+# ------------------------------------------------------------------
+# 1. Helper that builds a *sugar‑free* wide‑but‑shallow schema
+# ------------------------------------------------------------------
+def build_wide_schema(width)
+  Class.new do
+    extend Kumi::Schema
+
+    schema do
+      input { integer :seed }
+
+      # width independent leaf nodes: v_i = seed + i
+      1.upto(width) { |i| value :"v#{i}", fn(:add, input.seed, i) }
+
+      # Aggregations
+      value :sum_all, fn(:sum, (1..width).map { |i| ref(:"v#{i}") })
+      value :avg_all, fn(:divide, ref(:sum_all), width)
+
+      trait :large_total,
+            ref(:sum_all), :>, (width * (width + 1) / 2)
+
+      value :final_total do
+        on :large_total, fn(:add, ref(:sum_all), ref(:avg_all))
+        base ref(:sum_all)
+      end
+    end
+  end
+end
+
+WIDTHS = [1_000, 5_000, 10_000]
+
+# ------------------------------------------------------------------
+# 2. Measure compilation once per width
+# ------------------------------------------------------------------
+compile_times = {}
+schemas       = {}
+
+WIDTHS.each do |w|
+  t0 = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+  schemas[w] = build_wide_schema(w)
+  compile_times[w] = Process.clock_gettime(Process::CLOCK_MONOTONIC) - t0
+end
+
+puts "=== compilation times ==="
+compile_times.each do |w, t|
+  puts format("compile %5d‑wide: %6.1f ms", w, t * 1_000)
+end
+puts
+
+# ------------------------------------------------------------------
+# 3. Pure evaluation benchmark – no compilation inside the loop
+# ------------------------------------------------------------------
+Benchmark.ips do |x|
+  schemas.each do |w, schema|
+    runner = schema.from(seed: 0)          # memoised runner
+    x.report("eval #{w}-wide") { runner[:final_total] }
+  end
+  x.compare!
+end

data/lib/generators/trait_engine/templates/schema_spec.rb.erb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+require "rails_helper"
+
+RSpec.describe <%= schema_constant %> do
+  # Single shared instance for every example
+  let(:schema) { described_class }
+
+  # Minimal dummy context so every binding can run
+  let(:ctx) do
+    {
+<% leaf_keys.each do |k| -%>
+      <%= "#{k}:" %> nil,
+<% end -%>
+    }
+  end
+
+<% expose_names.each do |name| -%>
+  describe "<%= name %>" do
+    it "evaluates without raising" do
+      expect {
+        schema.evaluate_binding(:<%= name %>, ctx)
+      }.not_to raise_error
+    end
+  end
+
+<% end -%>
+end

data/lib/kumi/analyzer/constant_evaluator.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Kumi
+  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)
+
+        if node.is_a?(Binding)
+          return :unknown if visited.include?(node.name)
+
+          visited << node.name
+
+          definition = @definitions[node.name]
+          return :unknown unless definition
+
+          @memo[node] = evaluate(definition.expression, visited)
+          return @memo[node]
+        end
+
+        if node.is_a?(CallExpression)
+          return :unknown unless OPERATORS.key?(node.fn_name)
+
+          args = node.args.map { |arg| evaluate(arg, visited) }
+          return :unknown if args.any?(:unknown)
+
+          @memo[node] = args.reduce(OPERATORS[node.fn_name])
+          return @memo[node]
+        end
+
+        :unknown
+      end
+    end
+  end
+end

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

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # RESPONSIBILITY: Perform local structural validation on each declaration
+      # DEPENDENCIES: None (can run independently)
+      # PRODUCES: None (validation only)
+      # INTERFACE: new(schema, state).run(errors)
+      class DefinitionValidator < VisitorPass
+        def run(errors)
+          each_decl do |decl|
+            visit(decl) { |node| validate_node(node, errors) }
+          end
+        end
+
+        private
+
+        def validate_node(node, errors)
+          case node
+          when Declarations::Attribute
+            validate_attribute(node, errors)
+          when Declarations::Trait
+            validate_trait(node, errors)
+          end
+        end
+
+        def validate_attribute(node, errors)
+          return unless node.expression.nil?
+
+          add_error(errors, node.loc, "attribute `#{node.name}` requires an expression")
+        end
+
+        def validate_trait(node, errors)
+          return if node.expression.is_a?(Expressions::CallExpression)
+
+          add_error(errors, node.loc, "trait `#{node.name}` must wrap a CallExpression")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # RESPONSIBILITY: Build dependency graph and leaf map, validate references
+      # DEPENDENCIES: :definitions from NameIndexer
+      # PRODUCES: :dependency_graph - Hash of name → [DependencyEdge], :leaf_map - Hash of name → Set[nodes]
+      # INTERFACE: new(schema, state).run(errors)
+      class DependencyResolver < PassBase
+        # A Struct to hold rich dependency information
+        DependencyEdge = Struct.new(:to, :type, :via, keyword_init: true)
+        include Syntax
+
+        def run(errors)
+          definitions = get_state(:definitions)
+          input_meta = get_state(:input_meta)
+
+          dependency_graph = Hash.new { |h, k| h[k] = [] }
+          leaf_map = Hash.new { |h, k| h[k] = Set.new }
+
+          each_decl do |decl|
+            # Traverse the expression for each declaration, passing context down
+            visit_with_context(decl.expression) do |node, context|
+              process_node(node, decl, dependency_graph, leaf_map, definitions, input_meta, errors, context)
+            end
+          end
+
+          set_state(:dependency_graph, dependency_graph.transform_values(&:freeze).freeze)
+          set_state(:leaf_map, leaf_map.transform_values(&:freeze).freeze)
+        end
+
+        private
+
+        def process_node(node, decl, graph, leaves, definitions, input_meta, errors, context)
+          case node
+          when Binding
+            add_error(errors, node.loc, "undefined reference to `#{node.name}`") unless definitions.key?(node.name)
+            add_dependency_edge(graph, decl.name, node.name, :ref, context[:via])
+          when FieldRef
+            add_error(errors, node.loc, "undeclared input `#{node.name}`") unless input_meta.key?(node.name)
+            add_dependency_edge(graph, decl.name, node.name, :key, context[:via])
+            leaves[decl.name] << node # put it back
+          when Literal
+            leaves[decl.name] << node
+          end
+        end
+
+        def add_dependency_edge(graph, from, to, type, via)
+          edge = DependencyEdge.new(to: to, type: type, via: via)
+          graph[from] << edge
+        end
+
+        # Custom visitor that passes context (like function name) down the tree
+        def visit_with_context(node, context = {}, &block)
+          return unless node
+
+          yield(node, context)
+
+          new_context = if node.is_a?(Expressions::CallExpression)
+                          { via: node.fn_name }
+                        else
+                          context
+                        end
+
+          node.children.each { |child| visit_with_context(child, new_context, &block) }
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # RESPONSIBILITY: Collect field metadata from input declarations and validate consistency
+      # DEPENDENCIES: None
+      # PRODUCES: :input_meta - Hash mapping field names to {type:, domain:} metadata
+      # INTERFACE: new(schema, state).run(errors)
+      class InputCollector < PassBase
+        include Syntax::TerminalExpressions
+
+        def run(errors)
+          input_meta = {}
+
+          schema.inputs.each do |field_decl|
+            unless field_decl.is_a?(FieldDecl)
+              add_error(errors, field_decl.loc, "Expected FieldDecl node, got #{field_decl.class}")
+              next
+            end
+
+            name = field_decl.name
+            existing = input_meta[name]
+
+            if existing
+              # Check for compatibility
+              if existing[:type] != field_decl.type && field_decl.type && existing[:type]
+                add_error(errors, field_decl.loc,
+                          "Field :#{name} declared with conflicting types: #{existing[:type]} vs #{field_decl.type}")
+              end
+
+              if existing[:domain] != field_decl.domain && field_decl.domain && existing[:domain]
+                add_error(errors, field_decl.loc,
+                          "Field :#{name} declared with conflicting domains: #{existing[:domain].inspect} vs #{field_decl.domain.inspect}")
+              end
+
+              # Merge metadata (later declarations override nil values)
+              input_meta[name] = {
+                type: field_decl.type || existing[:type],
+                domain: field_decl.domain || existing[:domain]
+              }
+            else
+              input_meta[name] = {
+                type: field_decl.type,
+                domain: field_decl.domain
+              }
+            end
+          end
+
+          set_state(:input_meta, input_meta.freeze)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # RESPONSIBILITY: Build definitions index and detect duplicate names
+      # DEPENDENCIES: None (first pass in pipeline)
+      # PRODUCES: :definitions - Hash mapping names to declaration nodes
+      # INTERFACE: new(schema, state).run(errors)
+      class NameIndexer < PassBase
+        def run(errors)
+          definitions = {}
+
+          each_decl do |decl|
+            add_error(errors, decl.loc, "duplicated definition `#{decl.name}`") if definitions.key?(decl.name)
+            definitions[decl.name] = decl
+          end
+
+          set_state(:definitions, definitions.freeze)
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # Base class for all analyzer passes providing common functionality
+      # and enforcing consistent interface patterns.
+      class PassBase
+        include Kumi::Syntax
+        include Kumi::ErrorReporting
+
+        # @param schema [Syntax::Root] The schema to analyze
+        # @param state [Hash] Shared analysis state accumulator
+        def initialize(schema, state)
+          @schema = schema
+          @state = state
+        end
+
+        # Main entry point for pass execution
+        # @param errors [Array] Error accumulator array
+        # @abstract Subclasses must implement this method
+        def run(errors)
+          raise NotImplementedError, "#{self.class.name} must implement #run"
+        end
+
+        protected
+
+        attr_reader :schema, :state
+
+        # Iterate over all declarations (attributes and traits) in the schema
+        # @yield [Syntax::Declarations::Attribute|Syntax::Declarations::Trait] Each declaration
+        def each_decl(&block)
+          schema.attributes.each(&block)
+          schema.traits.each(&block)
+        end
+
+        # DEPRECATED: Use report_error instead for consistent error handling
+        # Helper to add standardized error messages
+        # @param errors [Array] Error accumulator
+        # @param location [Syntax::Location] Error location
+        # @param message [String] Error message
+        def add_error(errors, location, message)
+          errors << ErrorReporter.create_error(message, location: location, type: :semantic)
+        end
+
+        # Helper to get required state from previous passes
+        # @param key [Symbol] State key to retrieve
+        # @param required [Boolean] Whether this state is required
+        # @return [Object] The state value
+        # @raise [StandardError] If required state is missing
+        def get_state(key, required: true)
+          value = state[key]
+          raise "Pass #{self.class.name} requires #{key} from previous passes, but it was not found" if required && value.nil?
+
+          value
+        end
+
+        # Helper to set state for subsequent passes
+        # @param key [Symbol] State key to set
+        # @param value [Object] Value to store
+        def set_state(key, value)
+          state[key] = value
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      # RESPONSIBILITY: Compute topological ordering of declarations from dependency graph
+      # DEPENDENCIES: :dependency_graph from DependencyResolver, :definitions from NameIndexer
+      # PRODUCES: :topo_order - Array of declaration names in evaluation order
+      # INTERFACE: new(schema, state).run(errors)
+      class Toposorter < PassBase
+        def run(errors)
+          dependency_graph = get_state(:dependency_graph, required: false) || {}
+          definitions = get_state(:definitions, required: false) || {}
+
+          order = compute_topological_order(dependency_graph, definitions, errors)
+          set_state(:topo_order, order)
+        end
+
+        private
+
+        def compute_topological_order(graph, definitions, errors)
+          temp_marks = Set.new
+          perm_marks = Set.new
+          order = []
+
+          visit_node = lambda do |node|
+            return if perm_marks.include?(node)
+
+            if temp_marks.include?(node)
+              report_unexpected_cycle(temp_marks, node, errors)
+              return
+            end
+
+            temp_marks << node
+            Array(graph[node]).each { |edge| visit_node.call(edge.to) }
+            temp_marks.delete(node)
+            perm_marks << node
+
+            # Only include declaration nodes in the final order
+            order << node if definitions.key?(node)
+          end
+
+          # Visit all nodes in the graph
+          graph.each_key { |node| visit_node.call(node) }
+
+          # Also visit any definitions that aren't in the dependency graph
+          # (i.e., declarations with no dependencies)
+          definitions.each_key { |node| visit_node.call(node) }
+
+          order
+        end
+
+        def report_unexpected_cycle(temp_marks, current_node, errors)
+          cycle_path = temp_marks.to_a.join(" → ") + " → #{current_node}"
+
+          # Try to find the first declaration in the cycle for location info
+          first_decl = find_declaration_by_name(temp_marks.first || current_node)
+          location = first_decl&.loc
+
+          add_error(errors, location, "cycle detected: #{cycle_path}")
+        end
+
+        def find_declaration_by_name(name)
+          return nil unless schema
+
+          schema.attributes.find { |attr| attr.name == name } ||
+            schema.traits.find { |trait| trait.name == name }
+        end
+      end
+    end
+  end
+end