kumi 0.0.18 → 0.0.19

data/docs/development/error-reporting.md

@@ -1,361 +0,0 @@
-# Error Reporting Standards
-
-This guide provides comprehensive standards for error reporting in Kumi, ensuring consistent, localized error messages throughout the system.
-
-## Overview
-
-Kumi uses a unified error reporting interface that:
-- Provides consistent location information (file:line:column)
-- Categorizes errors by type (syntax, semantic, type, runtime)
-- Supports both immediate raising and error accumulation patterns
-- Maintains backward compatibility with existing tests
-- Enables enhanced error messages with suggestions and context
-
-## Core Interface Components
-
-### ErrorReporter Module
-Central error reporting functionality with standardized error entries:
-
-```ruby
-# Create structured error entry
-entry = ErrorReporter.create_error(
-  "Error message",
-  location: node.loc,
-  type: :semantic,
-  context: { additional: "info" }
-)
-
-# Add error to accumulator
-ErrorReporter.add_error(errors, "message", location: node.loc)
-
-# Immediately raise error
-ErrorReporter.raise_error("message", location: node.loc, error_class: Errors::SyntaxError)
-```
-
-### ErrorReporting Mixin
-Convenient methods for classes that need error reporting:
-
-```ruby
-class MyClass
-  include ErrorReporting
-  
-  def process
-    # Accumulated errors (analyzer pattern)
-    report_error(errors, "message", location: node.loc, type: :semantic)
-    
-    # Immediate errors (parser pattern)
-    raise_localized_error("message", location: node.loc, error_class: Errors::SyntaxError)
-  end
-end
-```
-
-## Implementation Patterns
-
-### Parser Classes (Immediate Errors)
-Parser classes should raise errors immediately when encountered:
-
-```ruby
-class DslBuilderContext
-  include ErrorReporting
-  
-  def validate_name(name, type, location)
-    return if name.is_a?(Symbol)
-    
-    raise_syntax_error(
-      "The name for '#{type}' must be a Symbol, got #{name.class}",
-      location: location
-    )
-  end
-  
-  def raise_error(message, location)
-    # Legacy method - delegates to new interface
-    raise_syntax_error(message, location: location)
-  end
-end
-```
-
-### Analyzer Passes (Accumulated Errors)
-Analyzer passes should accumulate errors and report them at the end:
-
-```ruby
-class MyAnalyzerPass < PassBase
-  def run(errors)
-    each_decl do |decl|
-      validate_declaration(decl, errors)
-    end
-  end
-  
-  private
-  
-  def validate_declaration(decl, errors)
-    # New error reporting method
-    report_error(
-      errors, 
-      "Validation failed for #{decl.name}",
-      location: decl.loc,
-      type: :semantic
-    )
-    
-    # Legacy method (backward compatible)
-    add_error(errors, decl.loc, "Legacy format message")
-  end
-end
-```
-
-## Location Resolution Best Practices
-
-### Always Provide Location When Available
-```ruby
-# Good: Specific node location
-report_error(errors, "Type mismatch", location: node.loc)
-
-# Acceptable: Fallback location
-report_error(errors, "Cycle detected", location: first_node&.loc || :cycle)
-
-# Avoid: No location information
-report_error(errors, "Error occurred", location: nil)
-```
-
-### Complex Error Location Resolution
-For errors that span multiple nodes or are contextual:
-
-```ruby
-def report_cycle(cycle_path, errors)
-  # Find first declaration in cycle for location context
-  first_decl = find_declaration_by_name(cycle_path.first)
-  location = first_decl&.loc || :cycle
-  
-  report_error(
-    errors,
-    "cycle detected: #{cycle_path.join(' → ')}",
-    location: location,
-    type: :semantic
-  )
-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
-```
-
-### Location Fallbacks
-When AST location is not available, use meaningful symbolic locations:
-
-```ruby
-# Cycle detection
-location = node.loc || :cycle
-
-# Type inference failures  
-location = decl.loc || :type_inference
-
-# Cross-reference resolution
-location = ref_node.loc || :reference_resolution
-```
-
-## Error Categorization
-
-### Error Types
-- `:syntax` - Parse-time structural errors
-- `:semantic` - Analysis-time logical errors  
-- `:type` - Type system violations
-- `:runtime` - Execution-time failures
-
-### Type-specific Methods
-```ruby
-# Syntax errors (parser)
-report_syntax_error(errors, "Invalid syntax", location: loc)
-raise_syntax_error("Invalid syntax", location: loc)
-
-# Semantic errors (analyzer)  
-report_semantic_error(errors, "Logic error", location: loc)
-
-# Type errors (type checker)
-report_type_error(errors, "Type mismatch", location: loc)
-```
-
-## Enhanced Error Messages
-
-### Basic Enhanced Errors
-```ruby
-report_enhanced_error(
-  errors,
-  "undefined reference to `missing_field`",
-  location: node.loc,
-  similar_names: ["missing_value", "missing_data"],
-  suggestions: [
-    "Check spelling of field name",
-    "Ensure field is declared in input block"
-  ]
-)
-```
-
-### Context-rich Errors
-```ruby
-report_error(
-  errors,
-  "Type mismatch in function call",
-  location: call_node.loc,
-  type: :type,
-  context: {
-    function: call_node.fn_name,
-    expected_type: expected,
-    actual_type: actual,
-    argument_position: position
-  }
-)
-```
-
-## Backward Compatibility
-
-### Legacy Format Support
-The system supports both legacy `[location, message]` arrays and new `ErrorEntry` objects:
-
-```ruby
-# Analyzer.format_errors handles both formats
-def format_errors(errors)
-  errors.map do |error|
-    case error
-    when ErrorReporter::ErrorEntry
-      error.to_s  # New format: "at file.rb:10:5: message"
-    when Array
-      loc, msg = error
-      "at #{loc || '?'}: #{msg}"  # Legacy format
-    end
-  end.join("\n")
-end
-```
-
-### Migration Strategy
-1. **New code**: Use new error reporting methods (`report_error`, `raise_localized_error`)
-2. **Existing code**: No changes required - `add_error` method maintained for compatibility
-3. **Enhanced features**: Migrate to new methods to access suggestions, context, and categorization
-
-## Testing Error Reporting
-
-### Error Location Testing
-```ruby
-RSpec.describe "Error Location Verification" do
-  it "reports errors at correct locations" do
-    schema_code = <<~RUBY
-      Kumi.schema do
-        input { integer :age }
-        trait :adult, (input.age >= 18)
-        trait :adult, (input.age >= 21)  # Line 4: Duplicate
-      end
-    RUBY
-
-    begin
-      eval(schema_code, binding, "test.rb", 1)
-    rescue Kumi::Errors::SemanticError => e
-      expect(e.message).to include("test.rb:4")
-      expect(e.message).to include("duplicated definition")
-    end
-  end
-end
-```
-
-### Error Quality Testing
-```ruby
-it "provides comprehensive error information" do
-  error = expect_semantic_error do
-    schema do
-      input { string :name }
-      value :result, fn(:add, input.name, 5)
-    end
-  end
-  
-  expect(error.message).to include("add")           # Function name
-  expect(error.message).to include("string")        # Actual type
-  expect(error.message).to include("expects")       # Clear expectation
-  expect(error.message).to match(/:\d+:/)          # Line number
-end
-```
-
-### Edge Case Testing
-Use `spec/integration/potential_breakage_spec.rb` patterns:
-
-```ruby
-it "detects edge case that should break" do
-  expect do
-    schema do
-      input { integer :x }
-      # Edge case that might not be caught
-      value :result, some_edge_case_construct
-    end
-  end.to raise_error(Kumi::Errors::SemanticError)
-end
-```
-
-## Performance Considerations
-
-### Error Object Creation
-- ErrorEntry objects are lightweight structs
-- Location formatting is lazy (only when `to_s` is called)
-- Context information is stored efficiently in hashes
-
-### Batch Error Processing
-For analyzer passes processing many nodes:
-
-```ruby
-def run(errors)
-  # Batch process nodes to minimize error object creation
-  invalid_nodes = collect_invalid_nodes
-  
-  invalid_nodes.each do |node|
-    report_error(errors, "Invalid: #{node.name}", location: node.loc)
-  end
-end
-```
-
-## Common Patterns and Anti-patterns
-
-### ✅ Good Patterns
-```ruby
-# Clear, specific error messages
-report_error(errors, "argument 1 of `fn(:add)` expects float, got string", location: arg.loc)
-
-# Proper location resolution
-location = node.loc || fallback_location_for_context
-
-# Type-appropriate error categorization
-report_type_error(errors, "type mismatch", location: node.loc)
-```
-
-### ❌ Anti-patterns
-```ruby
-# Vague error messages
-report_error(errors, "error", location: node.loc)
-
-# Missing location information
-report_error(errors, "something failed", location: nil)
-
-# Wrong error categorization
-report_syntax_error(errors, "type mismatch", location: node.loc)  # Should be type error
-```
-
-## Error Message Guidelines
-
-### Message Format
-- Start with lowercase (automatic capitalization in display)
-- Be specific about what failed and why
-- Include relevant context (function names, types, values)
-- Avoid technical jargon in user-facing messages
-
-### Examples
-```ruby
-# Good messages
-"argument 1 of `fn(:add)` expects float, got input field `name` of declared type string"
-"duplicated definition `adult`"
-"undefined reference to `missing_field`"
-"cycle detected: a → b → a"
-
-# Messages to improve  
-"validation failed"
-"error in processing" 
-"something went wrong"
-```
-
-This error reporting system ensures that users get clear, actionable feedback about issues in their Kumi schemas, with precise location information to help them fix problems quickly.

data/docs/features/README.md

@@ -1,58 +0,0 @@
-# Features
-
-## Core Features
-
-### [Unsatisfiability Detection](analysis-unsat-detection.md)
-Analyzes rule combinations to detect logical impossibilities across dependency chains.
-
-- Detects impossible combinations at compile-time
-- Validates domain constraints
-- Reports multiple errors
-
-### [Type Inference](analysis-type-inference.md)  
-Determines types from expressions and propagates them through dependencies.
-
-- Infers types from literals and function calls
-- Propagates types through dependency graph
-- Validates function arguments
-
-### [Input Declarations](input-declaration-system.md)
-Defines expected inputs with types and constraints.
-
-- Type-specific declaration methods
-- Domain validation at runtime
-- Separates input metadata from business logic
-
-### [Hierarchical Broadcasting](hierarchical-broadcasting.md)
-Automatic vectorization over hierarchical data structures with dual access modes.
-
-- Object access for structured business data
-- Element access for multi-dimensional arrays
-- Mixed access modes in same schema
-
-### [Performance](performance.md)
-Processes large schemas.
-
-- 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
-
-### [JavaScript Transpiler](javascript-transpiler.md)
-Transpiles compiled schemas to standalone JavaScript code.
-
-- Generates bundles with only required functions
-- Supports CommonJS and browser environments
-- Maintains identical behavior across platforms
-
-## Integration
-
-- Type inference uses input declarations
-- Unsatisfiability detection uses type information for validation
-- Cascade mutual exclusion integrates with dependency analysis and cycle detection
-- Performance optimizations apply to all analysis passes

data/docs/features/analysis-type-inference.md

@@ -1,42 +0,0 @@
-# Type Inference
-
-Infers types from expressions and propagates them through dependency chains for compile-time type checking.
-
-## Type Inference Rules
-
-**Literals:**
-- `42` → `:integer`
-- `3.14` → `:float` 
-- `"hello"` → `:string`
-- `true` → `:boolean`
-- `[1, 2, 3]` → `{ array: :integer }`
-
-**Operations:**
-- Integer arithmetic → `:integer`
-- Mixed numeric operations → `:numeric`
-- Comparisons → `:boolean`
-
-**Functions:**
-- Return types defined in function registry
-- Arguments validated against parameter types
-
-## Error Detection
-
-**Type mismatches:**
-```
-TypeError: argument 2 of addition expects numeric, got input field `age` of declared type integer,
-but argument 1 is input field `customer_name` of declared type string
-```
-
-**Function validation:**
-- Arity validation (correct number of arguments)
-- Type compatibility validation
-- Unknown function detection
-
-## Inference Process
-
-- Processes declarations in topological order to resolve dependencies
-- Literal types determined from values
-- Function return types from function registry
-- Array types unified from element types
-- Cascade types inferred from result expressions

data/docs/features/analysis-unsat-detection.md

@@ -1,71 +0,0 @@
-# Unsatisfiability Detection
-
-Analyzes logical relationships across dependency chains to detect impossible rule combinations at compile time.
-
-## Example: Credit Card Approval System
-
-This schema contains impossible rule combinations:
-
-```ruby
-module CreditCardApproval
-  extend Kumi::Schema
-  
-  schema do
-    input do
-      integer :annual_income
-      integer :monthly_debt
-      integer :credit_score, domain: 300..850
-      string  :employment_type, domain: %w[full_time part_time contract self_employed]
-    end
-
-    # Financial calculations
-    value :monthly_income, input.annual_income / 12
-    value :available_monthly, monthly_income - input.monthly_debt
-    value :credit_limit_base, input.annual_income * 0.3
-    value :score_multiplier, (input.credit_score - 600) * 0.01
-    value :final_credit_limit, credit_limit_base * score_multiplier
-    value :employment_stability_factor, 
-          input.employment_type == "full_time" ? 1.0 :
-          input.employment_type == "part_time" ? 0.7 :
-          input.employment_type == "contract" ? 0.5 : 0.3
-    
-    # Business rules
-    trait :stable_income, (input.annual_income >= 60_000)
-    trait :good_credit, (input.credit_score >= 700)
-    trait :high_available_income, (available_monthly >= 4_000)
-    trait :premium_limit_qualified, (final_credit_limit >= 50_000)
-    trait :stable_employment, (input.employment_type == "full_time")
-    trait :high_stability_factor, (employment_stability_factor >= 0.8)
-    trait :excellent_credit, (input.credit_score == 900)
-
-    # Approval tiers - which combinations are impossible?
-    value :approval_tier do
-      on stable_income,good_credit,premium_limit_qualified, "platinum_tier"
-      on stable_employment,high_stability_factor, "executive_tier"  
-      on excellent_credit,good_credit, "perfect_score_tier"
-      on stable_income,good_credit, "standard_tier"
-      base "manual_review"
-    end
-  end
-end
-```
-
-**Detected errors:**
-
-```
-SemanticError: 
-conjunction `excellent_credit AND good_credit` is impossible
-conjunction `excellent_credit` is impossible
-```
-
-**Root cause:**
-- `excellent_credit` requires `credit_score == 900`
-- Input domain constrains `credit_score` to `300..850`
-- Any cascade condition using `excellent_credit` becomes impossible
-
-## Detection Mechanisms
-
-- Domain constraint violations: `field == value` where value is outside declared domain
-- Cascade condition analysis: each `on` condition checked independently  
-- OR expression handling: impossible only if both sides are impossible
-- Cross-variable mathematical constraint analysis