kumi 0.0.0 → 0.0.4

data/README.md

@@ -1,39 +1,289 @@
-# Kumi
+# Kumi 
 
-TODO: Delete this and the text below, and describe your gem
+[![CI](https://github.com/amuta/kumi/workflows/CI/badge.svg)](https://github.com/amuta/kumi/actions)
+[![Gem Version](https://badge.fury.io/rb/kumi.svg)](https://badge.fury.io/rb/kumi)
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/kumi`. To experiment with that code, run `bin/console` for an interactive prompt.
+Kumi is a declarative rule‑and‑calculation DSL for Ruby that turns scattered business logic into a statically‑checked dependency graph.
 
-## Installation
+Every input, trait, and formula is compiled into a typed AST node, so the entire graph is explicit and introspectable.
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+Note: The examples here are small for the sake of readability. I would not recommend using this gem unless you need to keep track of 100+ conditions/variables.
 
-Install the gem and add to the application's Gemfile by executing:
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## How to get started
+
+Install Kumi and try running the examples below or explore the `./examples` directory of this repository.
+```
+gem install kumi
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+## Example
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+**Instead of scattered logic:**
+```ruby
+def calculate_loan_approval(credit_score, income, debt_ratio)
+  good_credit = credit_score >= 700
+  sufficient_income = income >= 50_000  
+  low_debt = debt_ratio <= 0.3
+  
+  if good_credit && sufficient_income && low_debt
+    { approved: true, rate: 3.5 }
+  else
+    { approved: false, rate: nil }
+  end
+end
+```
+
+**You can write:**
+```ruby
+module LoanApproval
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :credit_score
+      float :income
+      float :debt_to_income_ratio
+    end
+
+    trait :good_credit, input.credit_score >= 700
+    trait :sufficient_income, input.income >= 50_000
+    trait :low_debt, input.debt_to_income_ratio <= 0.3
+    trait :approved, good_credit & sufficient_income & low_debt
+    
+    value :interest_rate do
+      on :approved, 3.5
+      base 0.0
+    end
+  end
+end
+
+runner = LoanApproval.from(credit_score: 750, income: 60_000, debt_to_income_ratio: 0.25)
+puts runner[:approved]       # => true
+puts runner[:interest_rate]  # => 3.5
 ```
 
-## Usage
+This gets you:
+- Static analysis catches impossible logic combinations at compile time
+- Automatic dependency tracking prevents circular references  
+- Type safety with domain constraints (age: 0..150, status: %w[active inactive])
+- Microsecond performance not much different than optimized pure ruby
+- Introspectable - see exactly how any value was computed
+
+## Static Analysis & Safety
+
+Kumi analyzes your rules to catch logical impossibilities:
+
+```ruby
+module ImpossibleLogic
+  extend Kumi::Schema
 
-TODO: Write usage instructions here
+  schema do
+    input {}  # No inputs needed
+
+    value :x, 100
+    trait :x_less_than_100, x < 100        # false: 100 < 100
+    
+    value :y, x * 10                       # 1000  
+    trait :y_greater_than_1000, y > 1000   # false: 1000 > 1000
+
+    value :result do
+      # This is impossible
+      on :x_less_than_100 & :y_greater_than_1000, "Impossible!"
+      base "Default"
+    end
+  end
+end
+
+# Kumi::Errors::SemanticError: conjunction `x_less_than_100 AND y_greater_than_1000` is impossible
+```
 
-## Development
+Cycle detection:
+```ruby
+module CircularDependency
+  extend Kumi::Schema
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+  schema do
+    input { float :base }
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+    # These create a circular dependency
+    value :monthly_rate, yearly_rate / 12
+    value :yearly_rate, monthly_rate * 12
+  end
+end
+
+# Kumi::Errors::SemanticError: cycle detected involving: monthly_rate → yearly_rate → monthly_rate
+```
+
+## Performance
+
+Kumi has microsecond evaluation times through automatic memoization:
+
+### Deep Dependency Chains
+```
+=== Evaluation Performance (with Memoization) ===
+eval  50-deep:  817,497 i/s  (1.22 μs/i)
+eval 100-deep:  509,567 i/s  (1.96 μs/i) 
+eval 150-deep:  376,429 i/s  (2.66 μs/i)
+eval 200-deep:  282,243 i/s  (3.54 μs/i)
+```
+
+### Wide Complex Schemas  
+```
+=== Evaluation Performance (with Memoization) ===
+eval  1,000-wide:  127,652 i/s  (7.83 μs/i)
+eval  5,000-wide:   26,604 i/s  (37.59 μs/i) 
+eval 10,000-wide:   13,670 i/s  (73.15 μs/i)
+```
+
+Here's how the memoization works:
+```ruby
+module ProductPricing
+  extend Kumi::Schema
+  
+  schema do
+    input do
+      float :base_price
+      float :tax_rate
+      integer :quantity
+    end
+    
+    value :unit_price_with_tax, input.base_price * (1 + input.tax_rate)
+    value :total_before_discount, unit_price_with_tax * input.quantity
+    value :bulk_discount, input.quantity >= 10 ? 0.1 : 0.0
+    value :final_total, total_before_discount * (1 - bulk_discount)
+  end
+end
+
+runner = ProductPricing.from(base_price: 100.0, tax_rate: 0.08, quantity: 15)
+
+# First access: computes and caches all intermediate values
+puts runner[:final_total]           # => 1458.0 (computed + cached)
+
+# Subsequent accesses: pure cache lookups (microsecond performance)
+puts runner[:unit_price_with_tax]   # => 108.0 (from cache)
+puts runner[:bulk_discount]         # => 0.1 (from cache) 
+puts runner[:final_total]           # => 1458.0 (from cache)
+```
 
-## Contributing
+Architecture notes:
+- Compile-once, evaluate-many: Schema compilation happens once, evaluations are pure computation
+- `EvaluationWrapper` caches computed values automatically for subsequent access
+- Stack-safe algorithms: Iterative cycle detection and dependency resolution prevent stack overflow
+- Type-safe execution: No runtime type checking overhead after compilation
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/kumi.
+## DSL Features
+
+### Domain Constraints
+```ruby
+module UserProfile
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :age, domain: 0..150
+      string :status, domain: %w[active inactive suspended]
+      float :score, domain: 0.0..100.0
+    end
+
+    trait :adult, input.age >= 18
+    trait :active_user, input.status == "active"
+  end
+end
+
+# Valid data works fine
+UserProfile.from(age: 25, status: "active", score: 85.5)
+
+# Invalid data raises detailed errors
+UserProfile.from(age: 200, status: "invalid", score: -10)
+# => Kumi::Errors::DomainViolationError: Domain constraint violations...
+```
+
+### Cascade Logic
+```ruby
+module ShippingCost
+  extend Kumi::Schema
+
+  schema do
+    input do
+      float :order_total
+      string :membership_level
+    end
+
+    trait :premium_member, input.membership_level == "premium"
+    trait :large_order, input.order_total >= 100
+
+    value :shipping_cost do
+      on :premium_member, 0.0
+      on :large_order, 5.0
+      base 15.0
+    end
+  end
+end
+
+runner = ShippingCost.from(order_total: 75, membership_level: "standard")
+puts runner[:shipping_cost]  # => 15.0
+```
+
+### Functions
+```ruby
+module Statistics
+  extend Kumi::Schema
+
+  schema do
+    input do
+      array :scores, elem: { type: :float }
+    end
+
+    value :total, fn(:sum, input.scores)
+    value :count, fn(:size, input.scores)
+    value :average, total / count
+    value :max_score, fn(:max, input.scores)
+  end
+end
+
+runner = Statistics.from(scores: [85.5, 92.0, 78.5, 96.0])
+puts runner[:average]    # => 88.0
+puts runner[:max_score]  # => 96.0
+```
+
+## Introspection
+
+You can see exactly how any value was computed:
+
+```ruby
+module TaxCalculator
+  extend Kumi::Schema
+
+  schema do
+    input do
+      float :income
+      float :tax_rate
+      float :deductions
+    end
+
+    value :taxable_income, input.income - input.deductions
+    value :tax_amount, taxable_income * input.tax_rate
+  end
+end
+
+inputs = { income: 100_000, tax_rate: 0.25, deductions: 12_000 }
+
+puts Kumi::Explain.call(TaxCalculator, :taxable_income, inputs: inputs)
+# => taxable_income = input.income - deductions = (input.income = 100 000) - (deductions = 12 000) => 88 000
+
+puts Kumi::Explain.call(TaxCalculator, :tax_amount, inputs: inputs)  
+# => tax_amount = taxable_income × input.tax_rate = (taxable_income = 88 000) × (input.tax_rate = 0.25) => 22 000
+```
+
+## Try It Yourself
+
+Run the performance benchmarks:
+```bash
+bundle exec ruby examples/wide_schema_compilation_and_evaluation_benchmark.rb
+bundle exec ruby examples/deep_schema_compilation_and_evaluation_benchmark.rb
+```
 
-## License
+## DSL Syntax Reference
 
-The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+See [`documents/SYNTAX.md`](documents/SYNTAX.md) for complete syntax documentation with sugar vs sugar-free examples.

data/docs/development/README.md

@@ -0,0 +1,120 @@
+# Development Guides
+
+This directory contains detailed guides for developing and maintaining Kumi. These guides complement the high-level information in the main `CLAUDE.md` file.
+
+## Guide Index
+
+### Architecture & Design
+- [Error Reporting Standards](error-reporting.md) - Comprehensive guide to unified error reporting
+- [Analyzer Pass Development](analyzer-passes.md) - How to create new analyzer passes
+- [Type System Integration](type-system.md) - Working with Kumi's type inference and checking
+
+### Code Quality & Standards  
+- [Testing Standards](testing-standards.md) - Testing patterns and requirements
+- [Code Organization](code-organization.md) - File structure and class design patterns
+- [RuboCop Guidelines](rubocop-guidelines.md) - Code style and quality requirements
+
+### Common Tasks
+- [Adding New Functions](adding-functions.md) - Extending the FunctionRegistry
+- [DSL Extension Patterns](dsl-extensions.md) - Adding new DSL constructs
+- [Performance Considerations](performance.md) - Guidelines for maintaining performance
+
+### Integration & Compatibility
+- [Backward Compatibility](backward-compatibility.md) - Maintaining compatibility during changes
+- [Migration Patterns](migration-patterns.md) - Safe patterns for evolving APIs
+- [Zeitwerk Integration](zeitwerk.md) - Autoloading patterns and requirements
+
+## Quick Reference
+
+### Key Principles
+1. **Unified Error Reporting**: All errors must provide clear location information
+2. **Multi-pass Analysis**: Each analyzer pass has single responsibility  
+3. **Backward Compatibility**: Changes maintain existing API compatibility
+4. **Type Safety**: Optional but comprehensive type checking
+5. **Ruby Integration**: Leverage Ruby idioms while maintaining structure
+
+### Common Commands
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run specific test categories
+bundle exec rspec spec/integration/
+bundle exec rspec spec/kumi/analyzer/
+
+# Check code quality
+bundle exec rubocop
+bundle exec rubocop -a
+
+# Validate error reporting
+bundle exec ruby test_location_improvements.rb
+```
+
+### File Templates
+
+**New Analyzer Pass**:
+```ruby
+# frozen_string_literal: true
+
+module Kumi
+  module Analyzer
+    module Passes
+      class MyNewPass < PassBase
+        def run(errors)
+          # Implementation with proper error reporting
+          report_error(errors, "message", location: node.loc, type: :semantic)
+        end
+      end
+    end
+  end
+end
+```
+
+**New Integration Test**:
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe "My Feature Integration" do
+  it "validates the feature works correctly" do
+    schema = build_schema do
+      input { integer :field }
+      value :result, input.field * 2
+    end
+    
+    expect(schema.from(field: 5).fetch(:result)).to eq(10)
+  end
+end
+```
+
+## Contributing Guidelines
+
+### Before Making Changes
+1. Check relevant development guide in this directory
+2. Review `CLAUDE.md` for high-level architecture understanding
+3. Run existing tests to ensure baseline functionality
+4. Consider backward compatibility implications
+
+### After Making Changes  
+1. Update relevant development guides if patterns change
+2. Add or update tests for new functionality
+3. Run full test suite: `bundle exec rspec`
+4. Check code quality: `bundle exec rubocop`
+5. Verify error reporting quality with integration tests
+
+### Adding New Guides
+When adding new development guides:
+1. Create focused, actionable guides for specific development tasks
+2. Include code examples and common patterns
+3. Reference related files and tests
+4. Update this README index
+5. Cross-reference from main `CLAUDE.md` if needed
+
+## Guide Maintenance
+
+These guides should be kept up-to-date as the codebase evolves:
+- **Review quarterly** for accuracy and completeness
+- **Update immediately** when patterns or APIs change significantly  
+- **Expand based on common questions** during development
+- **Consolidate** overlapping or redundant information
+
+The goal is to make Kumi development efficient and consistent while maintaining high code quality.