kumi 0.0.6 → 0.0.8

data/docs/schema_metadata/dependencies.md

@@ -0,0 +1,57 @@
+# Dependencies Metadata
+
+Processed dependency information showing relationships between declarations with clean, serializable data.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+dependencies = metadata.dependencies
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Array<Hash>>
+{
+  declaration_name => [
+    {
+      to: Symbol,           # Target declaration name
+      conditional: Boolean, # True if dependency is conditional (cascade branch)
+      cascade_owner: Symbol # Optional: cascade that owns this conditional edge
+    }
+  ]
+}
+```
+
+## Example
+
+```ruby
+metadata.dependencies
+# => {
+#   :tax_amount => [
+#     { to: :income, conditional: false },
+#     { to: :deductions, conditional: false }
+#   ],
+#   :status => [
+#     { to: :adult, conditional: true, cascade_owner: :status },
+#     { to: :verified, conditional: true, cascade_owner: :status }
+#   ]
+# }
+```
+
+## Raw Edge Objects
+
+For advanced use cases requiring direct Edge object access:
+
+```ruby
+raw_dependencies = metadata.analyzer_state[:dependencies]
+# => { :tax_amount => [#<Edge to: :income>, #<Edge to: :deductions>] }
+```
+
+## Usage
+
+- Topological sorting
+- Cycle detection  
+- Evaluation planning
+- Dependency visualization

data/docs/schema_metadata/evaluation_order.md

@@ -0,0 +1,29 @@
+# Evaluation Order Metadata
+
+Topologically sorted order for safe declaration evaluation.
+
+## Structure
+
+```ruby
+state[:evaluation_order] = [:name1, :name2, :name3, ...]
+```
+
+## Example
+
+```ruby
+[:income, :deductions, :taxable_income, :tax_rate, :tax_amount, :adult, :status]
+```
+
+## Properties
+
+- Dependencies appear before dependents  
+- Handles conditional cycles in cascades
+- Deterministic ordering
+- Leaf nodes typically appear first
+
+## Usage
+
+- Compilation order
+- Evaluation sequencing  
+- Optimization planning
+- Parallel execution grouping

data/docs/schema_metadata/examples.md

@@ -0,0 +1,95 @@
+# Schema Metadata Examples
+
+For comprehensive API documentation with detailed examples, see the YARD documentation in the SchemaMetadata class.
+
+## Basic Usage
+
+```ruby
+class TaxSchema
+  extend Kumi::Schema
+
+  schema do
+    input do
+      integer :income, domain: 0..1_000_000
+      string :filing_status, domain: %w[single married]
+      integer :age, domain: 18..100
+    end
+
+    trait :adult, (input.age >= 18)
+    trait :high_income, (input.income > 100_000)
+
+    value :tax_rate do
+      on high_income, 0.25
+      base 0.15
+    end
+
+    value :tax_amount, input.income * tax_rate
+  end
+end
+
+# Access schema metadata - clean object interface!
+metadata = TaxSchema.schema_metadata
+
+# Processed semantic metadata (rich, transformed from AST)
+puts metadata.inputs
+# => { :income => { type: :integer, domain: {...}, required: true }, ... }
+
+puts metadata.values
+# => { :tax_rate => { type: :float, cascade: {...} }, ... }
+
+puts metadata.traits  
+# => { :adult => { type: :boolean, condition: "input.age >= 18" }, ... }
+
+# Raw analyzer state (direct from analysis passes)
+puts metadata.evaluation_order
+# => [:adult, :high_income, :tax_rate, :tax_amount]
+
+puts metadata.dependencies
+# => { :tax_amount => [#<Edge to: :tax_rate>, #<Edge to: :income>], ... }
+
+puts metadata.inferred_types
+# => { :adult => :boolean, :tax_rate => :float, :tax_amount => :float }
+
+# Serializable processed hash
+processed_hash = metadata.to_h
+puts processed_hash.keys
+# => [:inputs, :values, :traits, :functions]
+
+# Raw analyzer state (contains AST nodes)
+raw_state = metadata.analyzer_state
+puts raw_state.keys
+# => [:declarations, :inputs, :dependencies, :dependents, :leaves, :evaluation_order, :inferred_types, :cascades, :broadcasts]
+```
+
+## Tool Integration
+
+```ruby
+# Form generator example
+def generate_form_fields(schema_class)
+  metadata = schema_class.schema_metadata
+  
+  metadata.inputs.map do |field_name, field_info|
+    case field_info[:type]
+    when :integer
+      create_number_input(field_name, field_info[:domain])
+    when :string
+      create_select_input(field_name, field_info[:domain])
+    when :boolean
+      create_checkbox_input(field_name)
+    end
+  end
+end
+
+# Dependency analysis example  
+def analyze_field_dependencies(schema_class, field_name)
+  metadata = schema_class.schema_metadata
+  
+  # Find what depends on this field
+  dependents = metadata.dependents[field_name] || []
+  
+  # Find what this field depends on
+  dependencies = metadata.dependencies[field_name]&.map(&:to) || []
+  
+  { affects: dependents, requires: dependencies }
+end
+```

data/docs/schema_metadata/inferred_types.md

@@ -0,0 +1,46 @@
+# Inferred Types Metadata
+
+Type inference results for all declarations based on expression analysis.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+types = metadata.inferred_types
+```
+
+## Structure
+
+```ruby
+# Returns Hash<Symbol, Object>
+{
+  declaration_name => type_specification
+}
+```
+
+## Example
+
+```ruby
+metadata.inferred_types
+# => {
+#   :adult => :boolean,
+#   :age_group => :string, 
+#   :tax_rate => :float,
+#   :count => :integer,
+#   :item_prices => { array: :float },
+#   :categories => { array: :string }
+# }
+```
+
+## Type Values
+
+- `:boolean`, `:string`, `:integer`, `:float`, `:any`
+- `{ array: element_type }` for arrays
+- `{ hash: { key: key_type, value: value_type } }` for hashes
+
+## Usage
+
+- Type checking
+- Code generation
+- Editor support
+- Runtime validation

data/docs/schema_metadata/inputs.md

@@ -0,0 +1,86 @@
+# Input Metadata
+
+Raw input field metadata extracted from `input` blocks during analysis.
+
+## Access
+
+```ruby
+metadata = MySchema.schema_metadata
+
+# Processed input metadata (recommended for tools)
+inputs = metadata.inputs
+
+# Raw input metadata (advanced usage)
+raw_inputs = metadata.analyzer_state[:inputs]
+```
+
+## Raw Structure
+
+```ruby
+# Raw analyzer state format
+{
+  field_name => {
+    type: Symbol,           # :integer, :string, :float, :boolean, :array, etc. 
+    domain: Range|Array,    # optional domain constraints
+    children: Hash          # for array/hash types
+  }
+}
+```
+
+## Processed Structure
+
+```ruby 
+# Processed metadata format (via metadata.inputs)
+{
+  field_name => {
+    type: Symbol,           # normalized type
+    domain: Hash,           # normalized domain metadata
+    required: Boolean       # always true currently
+  }
+}
+```
+
+## Examples
+
+**Processed Input Metadata:**
+```ruby
+metadata.inputs
+# => {
+#   :age => { 
+#     type: :integer, 
+#     domain: { type: :range, min: 0, max: 120, exclusive_end: false },
+#     required: true 
+#   },
+#   :name => { type: :string, required: true },
+#   :active => { type: :boolean, required: true }
+# }
+```
+
+**Raw Input Metadata:**
+```ruby
+metadata.analyzer_state[:inputs]
+# => {
+#   :age => { type: :integer, domain: 0..120 },
+#   :name => { type: :string },
+#   :line_items => {
+#     type: :array,
+#     children: {
+#       :price => { type: :float, domain: 0..Float::INFINITY },
+#       :quantity => { type: :integer, domain: 1..100 }
+#     }
+#   }
+# }
+```
+
+**Domain Types:**
+- Range: `18..65`, `0..Float::INFINITY`
+- Array: `%w[active inactive suspended]`  
+- Proc: Custom validation functions
+
+## Usage
+
+Form generators use this metadata to:
+- Create appropriate input controls
+- Set validation rules  
+- Build nested forms for arrays
+- Generate type-safe schemas

data/docs/schema_metadata.md

@@ -0,0 +1,108 @@
+# Schema Metadata
+
+Kumi's SchemaMetadata interface provides structured access to analyzed schema information for building external tools like form generators, documentation systems, and analysis utilities.
+
+## Primary Interface
+
+SchemaMetadata is the main interface for extracting metadata from Kumi schemas:
+
+```ruby
+metadata = MySchema.schema_metadata
+```
+
+See the comprehensive API documentation in the SchemaMetadata class for detailed method documentation, examples, and usage patterns.
+
+## Processed Metadata (Tool-Friendly)
+
+These methods return clean, serializable data structures:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `inputs` | Hash | Input field metadata with normalized types and domains |
+| `values` | Hash | Value declarations with dependencies and expressions |
+| `traits` | Hash | Trait conditions with dependency information |
+| `functions` | Hash | Function registry info for functions used in schema |
+| `to_h` | Hash | Complete processed metadata (inputs, values, traits, functions) |
+| `to_json` | String | JSON serialization of processed metadata |
+| `to_json_schema` | Hash | JSON Schema document for input validation |
+
+## Raw Analyzer State (Advanced)
+
+Direct access to internal analyzer results:
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| [`declarations`](schema_metadata/declarations.md) | Hash | Raw AST declaration nodes by name |
+| [`dependencies`](schema_metadata/dependencies.md) | Hash | Dependency graph with Edge objects |
+| `dependents` | Hash | Reverse dependency lookup |
+| `leaves` | Hash | Leaf nodes (no dependencies) by type |
+| [`evaluation_order`](schema_metadata/evaluation_order.md) | Array | Topologically sorted evaluation order |
+| [`inferred_types`](schema_metadata/inferred_types.md) | Hash | Type inference results for declarations |
+| [`cascades`](schema_metadata/cascades.md) | Hash | Cascade mutual exclusion analysis |
+| [`broadcasts`](schema_metadata/broadcasts.md) | Hash | Array broadcasting operation metadata |
+| `analyzer_state` | Hash | Complete raw analyzer state with AST nodes |
+
+Note: Raw `inputs` metadata is available via `analyzer_state[:inputs]` but the processed `inputs` method is recommended for tool development.
+
+## Usage Patterns
+
+```ruby
+# Tool development - use processed metadata
+metadata = MySchema.schema_metadata
+form_fields = metadata.inputs.map { |name, info| create_field(name, info) }
+documentation = metadata.values.map { |name, info| document_value(name, info) }
+
+# Advanced analysis - use raw state when needed  
+dependency_graph = metadata.dependencies
+ast_nodes = metadata.declarations
+evaluation_sequence = metadata.evaluation_order
+```
+
+## Data Structure Examples
+
+### Processed Input Metadata
+```ruby
+metadata.inputs
+# => {
+#   :age => { type: :integer, domain: { type: :range, min: 18, max: 65 }, required: true },
+#   :name => { type: :string, required: true },
+#   :items => { type: :array, required: true }
+# }
+```
+
+### Processed Value Metadata
+```ruby
+metadata.values
+# => {
+#   :tax_amount => {
+#     type: :float,
+#     dependencies: [:income, :tax_rate],
+#     computed: true,
+#     expression: "multiply(input.income, tax_rate)"
+#   }
+# }
+```
+
+### Clean Public Interface Examples
+```ruby
+# Processed dependency information (clean hashes)
+metadata.dependencies
+# => { :tax_amount => [{ to: :income, conditional: false }, { to: :tax_rate, conditional: false }] }
+
+# Processed declaration metadata (clean hashes)
+metadata.declarations  
+# => { :adult => { type: :trait, expression: ">=(input.age, 18)" }, :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" } }
+
+# Type inference results (clean data)
+metadata.inferred_types
+# => { :adult => :boolean, :tax_amount => :float, :item_totals => { array: :float } }
+```
+
+### Raw Analyzer State (Advanced Usage)
+```ruby
+# Complete raw state hash with internal objects (AST nodes, Edge objects)
+metadata.analyzer_state
+# => { declarations: {AST nodes...}, dependencies: {Edge objects...}, ... }
+```
+
+See `docs/schema_metadata/` for detailed examples.

data/examples/game_of_life.rb

@@ -13,7 +13,7 @@ begin
       cells[neighbor_index]
     end.sum
   end
-  Kumi::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
+  Kumi::Core::FunctionRegistry.register_with_metadata(:neighbor_cells_sum, method(:neighbor_cells_sum_method),
                                                 return_type: :integer, arity: 5,
                                                 param_types: %i[array integer integer integer integer],
                                                 description: "Get neighbor cells for Conway's Game of Life")

data/examples/static_analysis_errors.rb

@@ -22,7 +22,7 @@ begin
       value :yearly_rate, monthly_rate * 12
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -48,7 +48,7 @@ begin
       end
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -71,7 +71,7 @@ begin
       value :invalid_sum, input.name + input.age
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -94,7 +94,7 @@ begin
       trait :impossible_score, input.score == 150
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -114,7 +114,7 @@ begin
       value :result, ref(:nonexistent_trait) ? 100 : 0
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → #{e.message}"
 end
 
@@ -134,7 +134,7 @@ begin
       value :result, fn(:nonexistent_function, input.text)
     end
   end
-rescue Kumi::Errors::TypeError => e
+rescue Kumi::Core::Errors::TypeError => e
   puts "   → #{e.message}"
 end
 
@@ -162,7 +162,7 @@ begin
       value :result, ref(:undefined_declaration)
     end
   end
-rescue Kumi::Errors::SemanticError => e
+rescue Kumi::Core::Errors::SemanticError => e
   puts "   → " + e.message.split("\n").join("\n   → ")
 end
 

data/lib/kumi/analyzer.rb

@@ -7,21 +7,21 @@ module Kumi
     module_function
 
     DEFAULT_PASSES = [
-      Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
-      Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
-      Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
-      Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
-      Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
-      Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
-      Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
-      Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
-      Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
-      Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
-      Passes::TypeChecker                      # 11. Validates types using inferred information.
+      Core::Analyzer::Passes::NameIndexer,                     # 1. Finds all names and checks for duplicates.
+      Core::Analyzer::Passes::InputCollector,                  # 2. Collects field metadata from input declarations.
+      Core::Analyzer::Passes::DeclarationValidator,            # 3. Checks the basic structure of each rule.
+      Core::Analyzer::Passes::SemanticConstraintValidator,     # 4. Validates DSL semantic constraints at AST level.
+      Core::Analyzer::Passes::DependencyResolver,              # 5. Builds the dependency graph with conditional dependencies.
+      Core::Analyzer::Passes::UnsatDetector,                   # 6. Detects unsatisfiable constraints and analyzes cascade mutual exclusion.
+      Core::Analyzer::Passes::Toposorter,                      # 7. Creates the final evaluation order, allowing safe cycles.
+      Core::Analyzer::Passes::BroadcastDetector, # 8. Detects which operations should be broadcast over arrays (must run before type inference).
+      Core::Analyzer::Passes::TypeInferencer,                  # 9. Infers types for all declarations (uses vectorization metadata).
+      Core::Analyzer::Passes::TypeConsistencyChecker,          # 10. Validates declared vs inferred type consistency.
+      Core::Analyzer::Passes::TypeChecker                      # 11. Validates types using inferred information.
     ].freeze
 
-    def analyze!(schema, passes: DEFAULT_PASSES, **opts)
-      state = AnalysisState.new(opts)
+    def self.analyze!(schema, passes: DEFAULT_PASSES, **opts)
+      state = Core::Analyzer::AnalysisState.new(opts)
       errors = []
 
       state = run_analysis_passes(schema, passes, state, errors)
@@ -35,7 +35,7 @@ module Kumi
         begin
           state = pass_instance.run(errors)
         rescue StandardError => e
-          errors << ErrorReporter.create_error(e.message, location: nil, type: :semantic)
+          errors << Core::ErrorReporter.create_error(e.message, location: nil, type: :semantic)
         end
       end
       state
@@ -52,17 +52,17 @@ module Kumi
 
     def self.create_analysis_result(state)
       Result.new(
-        definitions: state[:definitions],
-        dependency_graph: state[:dependency_graph],
-        leaf_map: state[:leaf_map],
-        topo_order: state[:topo_order],
-        decl_types: state[:decl_types],
+        definitions: state[:declarations],
+        dependency_graph: state[:dependencies],
+        leaf_map: state[:leaves],
+        topo_order: state[:evaluation_order],
+        decl_types: state[:inferred_types],
         state: state.to_h
       )
     end
 
     # Handle both old and new error formats for backward compatibility
-    def format_errors(errors)
+    def self.format_errors(errors)
       return "" if errors.empty?
 
       errors.map(&:to_s).join("\n")