kumi 0.0.0 → 0.0.3

data/README.md

@@ -1,39 +1,276 @@
-# Kumi
+# Kumi 
 
-TODO: Delete this and the text below, and describe your gem
+Kumi is a declarative rule‑and‑calculation DSL for Ruby that turns scattered business logic into a statically‑checked dependency graph.
 
-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.
+Every input, trait, and formula is compiled into a typed AST node, so the entire graph is explicit and introspectable.
 
-## Installation
+## Example
 
-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.
+**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
+```
 
-Install the gem and add to the application's Gemfile by executing:
+**You can write:**
+```ruby
+module LoanApproval
+  extend Kumi::Schema
 
-```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+  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
 ```
 
-If bundler is not being used to manage dependencies, install the gem by executing:
+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
 
-```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+## Static Analysis & Safety
+
+Kumi analyzes your rules to catch logical impossibilities:
+
+```ruby
+module ImpossibleLogic
+  extend Kumi::Schema
+
+  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
+```
+
+Cycle detection:
+```ruby
+module CircularDependency
+  extend Kumi::Schema
+
+  schema do
+    input { float :base }
+
+    # 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)
+```
+
+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
+
+## 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...
 ```
 
-## Usage
+### Cascade Logic
+```ruby
+module ShippingCost
+  extend Kumi::Schema
 
-TODO: Write usage instructions here
+  schema do
+    input do
+      float :order_total
+      string :membership_level
+    end
 
-## Development
+    trait :premium_member, input.membership_level == "premium"
+    trait :large_order, input.order_total >= 100
 
-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.
+    value :shipping_cost do
+      on :premium_member, 0.0
+      on :large_order, 5.0
+      base 15.0
+    end
+  end
+end
 
-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).
+runner = ShippingCost.from(order_total: 75, membership_level: "standard")
+puts runner[:shipping_cost]  # => 15.0
+```
 
-## Contributing
+### Functions
+```ruby
+module Statistics
+  extend Kumi::Schema
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/kumi.
+  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.