kumi 0.0.0 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ed9109766ab10fdf560d0597cea8ea62745e031f0b520d5e491e630d2114247
-  data.tar.gz: 1aef5090952191e3d6c3a67a80e64d0c826749e1f9d6be277c9704904ef96a30
+  metadata.gz: 243e6f2e2f7f65919f41fae1eddf877796e6221674e41dc5d32a36c708efab03
+  data.tar.gz: 8649def0a1299dd416d00480daa9fb0dfe3b6e418c4ea6c1ad869c873ad3eedf
 SHA512:
-  metadata.gz: 4c4337723f1a6aa34a7e64ecbbb303d5e6cd295a812248e6a9afde8bfd4718bb9f4668ae9c9dc039156c344b4b06fa6e8cc789cd93892fb2f4c3eb3a11749d31
-  data.tar.gz: 51efeb943d1c0dc9d1eb8f3de4521248b6d3f3ae2fff8a1172f37d5932a816c63a28b2ce068d2c2d594c06ecc3c2a479ae46835ef089cbe6f785543cbf0ae543
+  metadata.gz: e677d95d1ef34f8144b1f829259ad716e8f3822ab216957cf34a0058b4f7651843232202dc485a62e4c44077761a91b4db419963b649fae4a429042bf49be410
+  data.tar.gz: 3e7795238333d362f35c71b9478b01f4ff396110dc517a320dc304288a1ab8deac0a3af8b99c3d8f87cfd47a9a91f1bbd46509eb0055db4faa042b9b6ca14bd9

data/.rubocop.yml

@@ -1,8 +1,118 @@
+plugins:
+  - rubocop-performance
+  - rubocop-rspec
+
 AllCops:
-  TargetRubyVersion: 3.1
+  NewCops: enable
+  TargetRubyVersion: 3.0
+  SuggestExtensions: false
+  Exclude:
+    - 'bin/*'          
+    - 'spec/fixtures/**/*'
+    - 'examples/**/*'  # Examples may use deprecated syntax
+    - '*.txt'
+    - 'test_*.rb'      # Temporary test files
+    - 'spec/integration/performance_spec.rb'
 
+# Common stylistic choices
 Style/StringLiterals:
   EnforcedStyle: double_quotes
 
-Style/StringLiteralsInInterpolation:
-  EnforcedStyle: double_quotes
+Style/Documentation:
+  Enabled: false
+
+Style/OpenStructUse:
+  Enabled: false  # Used in AST nodes and test fixtures
+
+# Naming conventions - allow underscores in symbols for tax codes, etc.
+Naming/VariableNumber:
+  Enabled: false
+
+# Layout
+Layout/LineLength:
+  Max: 140
+
+# Metrics - Reasonable limits for a DSL/compiler project
+Metrics/MethodLength:
+  Max: 20
+  Exclude:
+    - 'lib/kumi/function_registry.rb'    # Large function registry
+    - 'lib/kumi/function_registry/**/*'  # Function registry modules with data definitions
+    - 'lib/kumi/analyzer/passes/**/*'    # Analyzer passes often need longer methods
+    - 'lib/kumi/types.rb'                # Type system operations
+    - 'lib/kumi/types/**/*'              # Type system modules
+    - 'lib/kumi/runner.rb'               # Complex runner methods
+    - 'spec/**/*'                        # Test files often need longer methods
+
+Metrics/AbcSize:
+  Max: 20
+  Exclude:
+    - 'lib/kumi/function_registry.rb'    # Large function registry
+    - 'lib/kumi/function_registry/**/*'  # Function registry modules with data definitions
+    - 'lib/kumi/analyzer/passes/**/*'    # Complex analyzer logic
+    - 'lib/kumi/types.rb'                # Type system operations
+    - 'lib/kumi/types/**/*'              # Type system modules
+    - 'lib/kumi/runner.rb'               # Complex runner methods
+    - 'spec/**/*'                        # Test files often have higher ABC
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+  Exclude:
+    - 'lib/kumi/analyzer/passes/**/*'    # Complex analyzer logic
+    - 'lib/kumi/types.rb'                # Type system operations
+    - 'lib/kumi/types/**/*'              # Type system modules
+    - 'lib/kumi/runner.rb'               # Complex runner methods
+
+Metrics/PerceivedComplexity:
+  Max: 10
+  Exclude:
+    - 'lib/kumi/analyzer/passes/**/*'    # Complex analyzer logic  
+    - 'lib/kumi/types.rb'                # Type system operations
+    - 'lib/kumi/types/**/*'              # Type system modules
+
+Metrics/ParameterLists:
+  Max: 6
+  Exclude:
+    - 'lib/kumi/analyzer/passes/dependency_resolver.rb'  # Complex dependency analysis
+    - 'lib/kumi/function_registry.rb'                    # Metadata registration
+
+Metrics/ModuleLength:
+  Max: 150
+  Exclude:
+    - 'lib/kumi/function_registry.rb'  # Large function registry
+
+# Allow missing super in base classes that are designed for inheritance
+Lint/MissingSuper:
+  Exclude:
+    - 'lib/kumi/analyzer/passes/pass_base.rb'  # Base class for analyzer passes
+    - 'lib/kumi/types.rb'                      # Type system value objects
+
+# RSpec-specific configuration
+RSpec:
+  Enabled: true
+
+RSpec/MultipleExpectations:
+  Enabled: false
+
+RSpec/ExampleLength:
+  Max: 30
+  Exclude:
+    - 'spec/kumi/export/comprehensive_integration_spec.rb'  # Comprehensive integration tests need longer examples
+
+RSpec/MultipleMemoizedHelpers:
+  Max: 10
+
+RSpec/VerifiedDoubleReference:
+  Enabled: false  # May require significant test refactoring
+
+RSpec/DescribeClass:
+  Enabled: false  # Integration tests don't always test specific classes
+
+RSpec/ContextWording:
+  Enabled: false  # Allow flexible context naming
+
+RSpec/ExpectActual:
+  Enabled: true   # Keep this - it's a good practice
+
+RSpec/IdenticalEqualityAssertion:
+  Enabled: false  # Sometimes needed for testing type systems

data/CHANGELOG.md

@@ -1,5 +1,25 @@
 ## [Unreleased]
 
-## [0.1.0] - 2025-07-06
+### Changed
+- **BREAKING**: Replaced `StrictCycleChecker` with `AtomUnsatSolver` for stack-safe UNSAT detection
+- Refactored cycle detection to use iterative Kahn's topological sort algorithm instead of recursive DFS
+- Added support for always-false comparison detection (e.g., `100 < 100`)
+
+### Added  
+- **Evaluation memoization**: `EvaluationWrapper` struct with `@__schema_cache__` provides automatic caching of computed bindings
+- **Massive performance improvements**: 369x-1,379x speedup on deep dependency chains through intelligent memoization
+- Depth-safe UNSAT detection handles 30k+ node graphs without stack overflow
+- Comprehensive test suite for large graph scenarios (acyclic ladders, cycles, mixed constraints)
+- Enhanced documentation with YARD comments for `AtomUnsatSolver` module
+- Extracted `StrictInequalitySolver` module for clear separation of cycle detection logic
+
+### Performance
+- **Stack-safe UNSAT detection**: Eliminates `SystemStackError` in constraint analysis for 30k+ node graphs
+- **Fixed gather_atoms recursion**: Made AST traversal iterative to handle deep dependency chains
+- Sub-millisecond performance on 10k-20k node constraint graphs with cycle detection
+- Maintained identical UNSAT detection correctness for all existing scenarios
+- **Note**: Deep schemas (2500+ dependencies) may still hit Ruby stack limits in compilation/evaluation phases
+
+## [0.1.0] - 2025-07-01
 
 - Initial release

data/CLAUDE.md

@@ -0,0 +1,387 @@
+# CLAUDE.md
+
+!! Remember, this gem is not on production yet, so no backward compatilibity is necessary. But do not change the public interfaces (e.g. DSL, Schema) without explicitly requested or demanded. 
+!! We are using zeitwerk, i.e.: no requires
+!! Do not care about linter or coverage unless asked to do so.
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Kumi is a declarative decision-modeling compiler for Ruby that transforms complex business rules into executable dependency graphs. It features a multi-pass analyzer that validates rule interdependencies, detects cycles, infers types, and generates optimized evaluation functions. The system separates input field declarations from business logic through an explicit input block syntax.
+
+## Development Commands
+
+### Testing
+- `bundle exec rspec` - Run all tests
+- `bundle exec rspec spec/path/to/specific_spec.rb` - Run specific test file
+- `bundle exec rspec spec/path/to/specific_spec.rb:123` - Run specific test at line
+
+### Linting & Code Quality
+- `bundle exec rubocop` - Run RuboCop linter
+- `bundle exec rubocop -a` - Auto-fix RuboCop issues where possible
+- `rake` - Run default task (includes rspec and rubocop)
+
+### Gem Management
+- `bundle install` - Install dependencies
+- `gem build kumi.gemspec` - Build the gem
+- `gem install ./kumi-*.gem` - Install locally built gem
+
+## Architecture Overview
+
+### Core Components
+
+**Schema System** (`lib/kumi/schema.rb`):
+- Entry point that ties together parsing, analysis, and compilation
+- Provides the `schema(&block)` DSL method that builds the syntax tree, runs analysis, and compiles to executable form
+- Generates a `Runner` instance for executing queries against input data
+
+**Parser** (`lib/kumi/parser/`):
+- `dsl.rb` - Main DSL parser that converts Ruby block syntax into AST nodes
+- `dsl_builder_context.rb` - Context for building DSL elements with input/value/trait methods
+- `dsl_cascade_builder.rb` - Specialized builder for cascade expressions
+- `dsl_proxy.rb` - Proxy object for method delegation during parsing
+- `input_dsl_proxy.rb` - Proxy for input block DSL supporting both `key` method and type-specific DSL methods
+- `input_proxy.rb` - Proxy for `input.field_name` references in expressions
+
+**Syntax Tree** (`lib/kumi/syntax/`):
+- `node.rb` - Base node class with location tracking
+- `root.rb` - Root schema node containing inputs, attributes, and traits
+- `declarations.rb` - Attribute and trait declaration nodes  
+- `expressions.rb` - Expression nodes (calls, lists, cascades)
+- `terminal_expressions.rb` - Terminal nodes (literals, field references, bindings, field declarations)
+
+**Analyzer** (`lib/kumi/analyzer.rb`):
+- Multi-pass analysis system that validates schemas and builds dependency graphs
+- **Pass 1**: `name_indexer.rb` - Find all names, check for duplicates
+- **Pass 2**: `input_collector.rb` - Collect field metadata, validate conflicts
+- **Pass 3**: `definition_validator.rb` - Validate basic structure
+- **Pass 4**: `dependency_resolver.rb` - Build dependency graph
+- **Pass 5**: `cycle_detector.rb` - Find circular dependencies
+- **Pass 6**: `toposorter.rb` - Create evaluation order
+- **Pass 7**: `type_inferencer.rb` - Infer types for all declarations
+- **Pass 8**: `type_checker.rb` - Validate function types and compatibility using inferred types
+
+**Compiler** (`lib/kumi/compiler.rb`):
+- Transforms analyzed syntax tree into executable lambda functions
+- Maps each expression type to a compilation method
+- Handles function calls via `FunctionRegistry`
+- Produces `CompiledSchema` with executable bindings
+
+**Function Registry** (`lib/kumi/function_registry.rb`):
+- Registry of available functions (operators, math, string, logical, collection operations)
+- Supports custom function registration with comprehensive type metadata
+- Each function includes param_types, return_type, arity, and description
+- Core functions include: `==`, `>`, `<`, `add`, `multiply`, `and`, `or`, `clamp`, etc.
+- Maintains backward compatibility with legacy type checking system
+- Function documents are generated by the script ./scripts/generate_function_docs.rb
+
+**Runner** (`lib/kumi/runner.rb`):
+- Executes compiled schemas against input data
+- Provides `fetch(key)` for individual value retrieval with caching
+- Provides `slice(*keys)` for batch evaluation
+- Provides `explain(key)` for detailed execution tracing
+
+**Input Validation System** (`lib/kumi/input/` and `lib/kumi/domain/`):
+- `input/validator.rb` - Main validation coordinator for type and domain checking
+- `input/type_matcher.rb` - Type validation logic for primitive and complex types
+- `input/violation_creator.rb` - Creates standardized violation objects with detailed messages
+- `domain/validator.rb` - Domain constraint validation (ranges, arrays, procs)
+- `domain/range_analyzer.rb` - Range domain analysis and validation
+- `domain/enum_analyzer.rb` - Enumeration domain analysis and validation
+- `domain/violation_formatter.rb` - Formats domain violation error messages
+
+### Key Patterns
+
+**DSL Structure**:
+```ruby
+schema do
+  input do
+    # Recommended type-specific DSL methods
+    string  :field_name
+    integer :number_field, domain: 0..100
+    array   :scores, elem: { type: :float }
+    hash    :metadata, key: { type: :string }, val: { type: :any }
+
+    # Fields with no declared type
+    any     :misc_field
+  end
+
+  trait :name, (expression)  # Boolean conditions with new syntax
+  value :name, expression    # Computed values
+  value :name do             # Conditional logic
+    on condition, result
+    base default_result
+  end
+end
+```
+
+**IMPORTANT CASCADE CONDITION SYNTAX:**
+In cascade expressions (`value :name do ... end`), trait references use **symbols**, not bare identifiers:
+```ruby
+value :status do
+  on :adult, "Adult Status"      # ✅ Correct - use :trait_name symbol
+  on :verified, "Verified User"
+  base "Unverified"
+end
+
+# NOT this:
+value :status do
+  on adult, "Adult Status"       # ❌ Wrong - don't use bare identifier in cascade
+  on verified, "Verified User"   # ❌ Wrong
+  base "Unverified"
+end
+```
+
+**Input Block System**:
+- **Required**: All schemas must have an `input` block declaring expected fields
+- **Type Declarations**: Preferred via type-specific methods (e.g. `integer :field`, `string :name`, `any :field` for untyped fields)
+- **Complex Types**: Use helper functions: `array(:element_type)` and `hash(:key_type, :value_type)`
+- **Domain Constraints**: Fields can have domains: `integer :age, domain: 18..65` (validated at runtime)
+- **Field Access**: Use `input.field_name` to reference input fields in expressions
+- **Separation**: Input metadata (types, domains) is separate from business logic
+
+**Expression Types**:
+- `input.field_name` - Access input data with operator methods (>=, <=, >, <, ==, !=)
+- `ref(:name)` - Reference other declarations
+- `fn(:name, args...)` - Function calls
+- `(expr1) & (expr2)` - Logical AND chaining
+- `[element1, element2]` - Lists
+- Literals (numbers, strings, booleans)
+
+**Analysis Flow**:
+1. Parse DSL → Syntax Tree
+2. Analyze Syntax Tree → Analysis Result (dependency graph, type information, topo order)
+3. Compile → Executable Schema  
+4. Execute with Runner
+
+**Type System** (`lib/kumi/types.rb`):
+- Simple symbol-based type system for clean and intuitive declaration
+- **Dual Type System**: Declared types (from input blocks) and inferred types (from expressions)
+- Automatic type inference for all declarations based on expression analysis
+- Type primitives: `:string`, `:integer`, `:float`, `:boolean`, `:any`, `:symbol`, `:regexp`, `:time`, `:date`, `:datetime`
+- Collection types: `array(:element_type)` and `hash(:key_type, :value_type)` helper functions
+- Type compatibility checking and unification algorithms for numeric types
+- Enhanced error messages showing type provenance (declared vs inferred)
+- Legacy compatibility constants maintained for backward compatibility
+
+### Examples Directory
+
+The `examples/` directory contains comprehensive examples showing Kumi usage patterns:
+- `cascade_demonstration.rb` - Demonstrates cascade logic with UnsatDetector fixes (working)
+- `working_comprehensive_schema.rb` - Complete feature showcase (current best practices, working)
+- `federal_tax_calculator_2024.rb` - Real-world tax calculation example (working)
+- `tax_2024.rb` - Simple tax example with explain functionality (working)
+- `wide_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for wide schemas (compilation and evaluation scaling)
+- `deep_schema_compilation_and_evaluation_benchmark.rb` - Performance benchmark for deep dependency chains (stack-safe evaluation)
+- `comprehensive_god_schema.rb` - Complex example (currently has UnsatDetector semantic errors)
+
+*Note: Some examples may use deprecated syntax and should be updated to use the new input block system.*
+
+## Test Structure
+
+- `spec/kumi/` - Unit tests for core components
+- `spec/integration/` - Integration tests for full workflows
+- `spec/fixtures/` - Test fixtures and sample schemas
+- `spec/support/` - Test helpers (`ast_factory.rb`, `schema_generator.rb`)
+
+## Key Files for Understanding
+
+1. `lib/kumi/schema.rb` - Start here to understand the main API
+2. `examples/input_block_typing_showcase.rb` - Comprehensive example of current features
+3. `lib/kumi/analyzer.rb` - Core analysis pipeline with multi-pass system
+4. `lib/kumi/types.rb` - Static type system implementation
+5. `lib/kumi/function_registry.rb` - Available functions and extension patterns
+6. `lib/kumi/analyzer/passes/type_inferencer.rb` - Type inference algorithm
+7. `lib/kumi/analyzer/passes/type_checker.rb` - Type validation with enhanced error messages
+8. `spec/kumi/input_block_spec.rb` - Input block syntax and behavior
+9. `spec/integration/compiler_integration_spec.rb` - End-to-end test examples
+10. `documents/DSL.md` - Concise DSL syntax reference
+11. `documents/AST.md` - AST node types and structure reference
+12. `documents/SYNTAX.md` - Comprehensive sugar vs sugar-free syntax comparison with examples
+
+## Input Block System Details
+
+### Required Input Blocks
+- **All schemas must have an input block** - This is now mandatory
+- Input blocks declare expected fields with optional type and domain constraints
+- **Empty input blocks are allowed** - Use `input {}` for schemas that don't require external data
+- Fields are accessed via `input.field_name` syntax (replaces deprecated `key(:field)`)
+
+### Type System Integration
+- **Declared Types**: Explicit type declarations in input blocks (e.g. `integer :field`, `string :name`, `any :field`)
+- **Inferred Types**: Types automatically inferred from expression analysis
+- **Type Checking**: Validates compatibility between declared and inferred types
+- **Enhanced Errors**: Error messages show type provenance (declared vs inferred)
+- **Helper Functions**: Use `array(:type)` and `hash(:key_type, :value_type)` for complex types
+
+### Parser Components
+- `input_dsl_proxy.rb` - Supports type-specific DSL methods (`integer`, `float`, `string`, `boolean`, `array`, `hash`, `any`)
+- `input_proxy.rb` - Handles `input.field_name` references in expressions
+- `input_collector.rb` - Collects and validates field metadata consistency
+
+### Domain Constraints
+- Can be declared: `integer :age, domain: 18..65`
+- **Implemented**: Domain validation is active and enforced at runtime
+- Supports Range domains (`18..65`), Array domains (`%w[active inactive]`), and Proc domains for custom validation
+- Field metadata includes domain information and runtime validation occurs during `Schema.from()`
+
+### Type Examples
+```ruby
+input do
+  # New type-specific DSL methods (recommended)
+  string       :name
+  integer      :age, domain: 18..65
+  hash         :metadata, key: { type: :string }, val: { type: :any }
+
+  # For untyped/any fields
+  any          :misc
+end
+```
+
+### Trait Syntax Evolution
+
+**Current Syntax** (recommended):
+```ruby
+trait :adult, (input.age >= 18)
+trait :qualified, (input.age >= 21) & (input.score > 80) & (input.verified == true)
+```
+
+**Composite Trait Syntax** (NEW - bare identifier references):
+```ruby
+# Base traits
+trait :adult, (input.age >= 18)
+trait :verified, (input.verified == true)
+trait :high_score, (input.score > 80)
+
+# Composite traits using bare identifier syntax
+trait :eligible, adult & verified & high_score
+trait :mixed, adult & (input.income > 50_000) & verified
+
+# Backward compatibility - both syntaxes work together
+trait :legacy_mix, adult & ref(:verified) & (input.score > 90)
+```
+
+**Deprecated Syntax** (with warnings):
+```ruby
+trait :adult, input.age, :>=, 18                    # OLD - shows deprecation warning
+trait :qualified, input.age, :>=, 21, input.score  # OLD - shows deprecation warning
+```
+
+**Key Changes**:
+- **NEW**: Bare identifier syntax allows direct trait reference: `adult` instead of `ref(:adult)`
+- New syntax uses parenthesized expressions: `trait :name, (expression)`  
+- FieldRef nodes have operator methods that create CallExpression nodes
+- Logical AND chaining via `&` operator (Ruby limitation prevents `&&`)
+- Only AND operations supported to maintain constraint satisfaction system
+- **Backward Compatible**: Both `trait_name` and `ref(:trait_name)` work together
+- Old syntax maintained with deprecation warnings for backward compatibility
+
+## Common Development Tasks
+
+### Adding New Analyzer Passes
+1. Create pass class inheriting from `PassBase` in `lib/kumi/analyzer/passes/`
+2. Implement `run(errors)` method that calls `set_state(key, value)` to store results
+3. Add pass to `PASSES` array in `lib/kumi/analyzer.rb` in correct order
+4. Consider dependencies on other passes (e.g., TypeChecker needs TypeInferencer)
+
+### Working with AST Nodes
+- All nodes include `Node` module for location tracking
+- Use `spec/support/ast_factory.rb` helpers in tests
+- Field declarations use `FieldDecl` nodes with name, domain, and type
+- Field references use `FieldRef` nodes (from `input.field_name`) with operator methods
+- FieldRef operator methods (>=, <=, >, <, ==, !=) create CallExpression nodes
+- CallExpression `&` method enables logical AND chaining
+
+### Testing Input Block Features
+- See `spec/kumi/input_block_spec.rb` for comprehensive input block tests
+- Use `schema_generator.rb` helper for creating test schemas
+- All integration tests now require input blocks
+
+## Architecture Design Principles
+
+- **Multi-pass Analysis**: Each analysis pass has a single responsibility and builds on previous passes
+- **Immutable Syntax Tree**: AST nodes are immutable; analysis results stored separately in analyzer state
+- **Dependency-driven Evaluation**: All computation follows dependency graph to ensure correct order
+- **Type Safety**: Optional but comprehensive type checking without breaking existing schemas
+- **Backward Compatibility**: New features maintain compatibility with existing DSL and APIs
+- **Ruby Integration**: Leverages Ruby's metaprogramming while providing structured analysis
+- **Separation of Concerns**: Input metadata (types, domains) separated from business logic
+- **Class Decomposition**: Large classes split into focused, single-responsibility components following RuboCop guidelines
+- **Delegation Pattern**: Complex operations delegated to specialized analyzer and formatter classes
+- **Unified Error Reporting**: Consistent, localized error messages throughout the system with clear interface patterns
+
+## Code Organization Patterns
+
+### Modular Validation Architecture
+- **Coordinator Classes**: Main classes like `Input::Validator` and `Domain::Validator` coordinate but delegate complex logic
+- **Specialized Analyzers**: Domain-specific classes like `RangeAnalyzer` and `EnumAnalyzer` handle specific constraint types
+- **Formatter Classes**: Dedicated classes like `ViolationFormatter` handle message formatting with consistent patterns
+- **Creator Classes**: Classes like `ViolationCreator` centralize object creation with standardized structure
+
+### Testing Best Practices
+- **Spec Organization**: Tests organized by component with clear separation between unit and integration tests
+- **Error Variable Extraction**: RSpec patterns avoid multiline block chains by extracting error variables for assertion
+- **Shared Contexts**: Use `schema_generator` and other shared contexts for consistent test setup
+
+### RuboCop Compliance
+- **Method Length**: Keep methods under 10 lines through extraction and delegation
+- **Class Length**: Break classes over 100 lines into focused components
+- **Complexity Metrics**: Reduce cyclomatic and ABC complexity through single-responsibility design
+- **Style Consistency**: Follow Ruby style guidelines for readability and maintainability
+
+### Error Reporting Architecture
+- **Unified Interface**: Use `ErrorReporter` module and `ErrorReporting` mixin for consistent error handling
+- **Location Information**: All errors must include proper file:line:column location data
+- **Precise Location Tracking**: Error objects preserve location data in `.location` attribute for programmatic access
+- **User Code Location**: Errors point to actual user DSL code, not internal library files
+- **Backward Compatibility**: Support both legacy `[location, message]` and new `ErrorEntry` formats
+- **Type Categorization**: Errors categorized as `:syntax`, `:semantic`, `:type`, `:runtime`
+- **Enhanced Messaging**: Support for error suggestions, context, and similar name detection
+
+## Development Guides and Standards
+
+### Error Reporting Standards
+**For Parser Classes**:
+```ruby
+class MyParser
+  include ErrorReporting
+  
+  def parse_something
+    # Immediate error raising
+    raise_syntax_error("Invalid syntax", location: current_location)
+  end
+end
+```
+
+**For Analyzer Passes**:
+```ruby
+class MyAnalyzerPass < PassBase
+  def run(errors)
+    # Error accumulation with enhanced location
+    report_error(errors, "semantic error", location: node.loc, type: :semantic)
+    
+    # Backward compatible method
+    add_error(errors, node.loc, "legacy format error")
+  end
+end
+```
+### Testing Error Scenarios
+- Use `spec/integration/dsl_breakage_spec.rb` patterns for comprehensive error testing
+- Use `spec/integration/potential_breakage_spec.rb` for edge cases break
+- Use `spec/fixtures/location_tracking_test_schema.rb` fixture for testing different syntax error types  
+- Test backward compatibility with existing analyzer pass specs
+
+### Key Development Files
+12. `lib/kumi/error_reporter.rb` - Central error reporting functionality
+13. `lib/kumi/error_reporting.rb` - Mixin for consistent error interfaces  
+14. `spec/integration/location_tracking_spec.rb` - Comprehensive tests for error location accuracy
+15. `spec/fixtures/location_tracking_test_schema.rb` - Fixture with intentional syntax errors for location testing
+16. `ERROR_REPORTING_INTERFACE.md` - Detailed error reporting implementation guide
+17. `ON_ERRORS.md` - Comprehensive analysis of DSL breakage scenarios and error quality
+18. `spec/integration/dsl_breakage_spec.rb` - Integration tests for all DSL breakage scenarios
+19. `spec/integration/potential_breakage_spec.rb` - Edge cases that should break but might not
+20. `docs/development/README.md` - Development guides directory index
+21. `docs/development/error-reporting.md` - Comprehensive error reporting standards and patterns
+
+#