kumi 0.0.6 → 0.0.7

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/lib/kumi/analyzer/passes/broadcast_detector.rb

@@ -4,34 +4,33 @@ module Kumi
   module Analyzer
     module Passes
       # Detects which operations should be broadcast over arrays
-      # DEPENDENCIES: :input_meta, :definitions
-      # PRODUCES: :broadcast_metadata
+      # DEPENDENCIES: :inputs, :declarations
+      # PRODUCES: :broadcasts
       class BroadcastDetector < PassBase
         def run(errors)
-          input_meta = get_state(:input_meta) || {}
-          definitions = get_state(:definitions) || {}
-          
+          input_meta = get_state(:inputs) || {}
+          definitions = get_state(:declarations) || {}
+
           # Find array fields with their element types
           array_fields = find_array_fields(input_meta)
-          
+
           # Build compiler metadata
           compiler_metadata = {
             array_fields: array_fields,
             vectorized_operations: {},
             reduction_operations: {}
           }
-          
+
           # Track which values are vectorized for type inference
           vectorized_values = {}
-          
+
           # Analyze traits first, then values (to handle dependencies)
-          traits = definitions.select { |name, decl| decl.is_a?(Kumi::Syntax::TraitDeclaration) }
-          values = definitions.select { |name, decl| decl.is_a?(Kumi::Syntax::ValueDeclaration) }
-          
+          traits = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::TraitDeclaration) }
+          values = definitions.select { |_name, decl| decl.is_a?(Kumi::Syntax::ValueDeclaration) }
+
           (traits.to_a + values.to_a).each do |name, decl|
             result = analyze_value_vectorization(name, decl.expression, array_fields, vectorized_values, errors)
-            
-            
+
             case result[:type]
             when :vectorized
               compiler_metadata[:vectorized_operations][name] = result[:info]
@@ -44,8 +43,8 @@ module Kumi
               vectorized_values[name] = { vectorized: false }
             end
           end
-          
-          state.with(:broadcast_metadata, compiler_metadata.freeze)
+
+          state.with(:broadcasts, compiler_metadata.freeze)
         end
 
         private
@@ -53,12 +52,12 @@ module Kumi
         def find_array_fields(input_meta)
           result = {}
           input_meta.each do |name, meta|
-            if meta[:type] == :array && meta[:children]
-              result[name] = {
-                element_fields: meta[:children].keys,
-                element_types: meta[:children].transform_values { |v| v[:type] || :any }
-              }
-            end
+            next unless meta[:type] == :array && meta[:children]
+
+            result[name] = {
+              element_fields: meta[:children].keys,
+              element_types: meta[:children].transform_values { |v| v[:type] || :any }
+            }
           end
           result
         end
@@ -71,7 +70,7 @@ module Kumi
             else
               { type: :scalar }
             end
-            
+
           when Kumi::Syntax::DeclarationReference
             # Check if this references a vectorized value
             vector_info = vectorized_values[expr.name]
@@ -80,19 +79,19 @@ module Kumi
             else
               { type: :scalar }
             end
-            
+
           when Kumi::Syntax::CallExpression
             analyze_call_vectorization(name, expr, array_fields, vectorized_values, errors)
-            
+
           when Kumi::Syntax::CascadeExpression
             analyze_cascade_vectorization(name, expr, array_fields, vectorized_values, errors)
-            
+
           else
             { type: :scalar }
           end
         end
 
-        def analyze_call_vectorization(name, expr, array_fields, vectorized_values, errors)
+        def analyze_call_vectorization(_name, expr, array_fields, vectorized_values, errors)
           # Check if this is a reduction function using function registry metadata
           if FunctionRegistry.reducer?(expr.fn_name)
             # Only treat as reduction if the argument is actually vectorized
@@ -103,11 +102,11 @@ module Kumi
               # Not a vectorized reduction - just a regular function call
               { type: :scalar }
             end
-            
+
           else
             # Special case: all?, any?, none? functions with vectorized trait arguments should be treated as vectorized
             # for cascade condition purposes (they get transformed during compilation)
-            if [:all?, :any?, :none?].include?(expr.fn_name) && expr.args.length == 1
+            if %i[all? any? none?].include?(expr.fn_name) && expr.args.length == 1
               arg = expr.args.first
               if arg.is_a?(Kumi::Syntax::ArrayExpression) && arg.elements.length == 1
                 trait_ref = arg.elements.first
@@ -116,28 +115,28 @@ module Kumi
                 end
               end
             end
-            
+
             # ANY function with vectorized arguments becomes vectorized (with broadcasting)
             arg_infos = expr.args.map { |arg| analyze_argument_vectorization(arg, array_fields, vectorized_values) }
-            
+
             if arg_infos.any? { |info| info[:vectorized] }
               # Check for dimension mismatches when multiple arguments are vectorized
-              vectorized_sources = arg_infos.select { |info| info[:vectorized] }.map { |info| info[:array_source] }.compact.uniq
-              
+              vectorized_sources = arg_infos.select { |info| info[:vectorized] }.filter_map { |info| info[:array_source] }.uniq
+
               if vectorized_sources.length > 1
                 # Multiple different array sources - this is a dimension mismatch
                 # Generate enhanced error message with type information
                 enhanced_message = build_dimension_mismatch_error(expr, arg_infos, array_fields, vectorized_sources)
-                
+
                 report_error(errors, enhanced_message, location: expr.loc, type: :semantic)
-                return { type: :scalar }  # Treat as scalar to prevent further errors
+                return { type: :scalar } # Treat as scalar to prevent further errors
               end
-              
+
               # This is a vectorized operation - ANY function supports broadcasting
-              { type: :vectorized, info: { 
-                operation: expr.fn_name, 
-                vectorized_args: arg_infos.map.with_index { |info, i| [i, info[:vectorized]] }.to_h 
-              }}
+              { type: :vectorized, info: {
+                operation: expr.fn_name,
+                vectorized_args: arg_infos.map.with_index { |info, i| [i, info[:vectorized]] }.to_h
+              } }
             else
               { type: :scalar }
             end
@@ -152,7 +151,7 @@ module Kumi
             else
               { vectorized: false }
             end
-            
+
           when Kumi::Syntax::DeclarationReference
             # Check if this references a vectorized value
             vector_info = vectorized_values[arg.name]
@@ -162,47 +161,44 @@ module Kumi
             else
               { vectorized: false }
             end
-            
+
           when Kumi::Syntax::CallExpression
             # Recursively check
             result = analyze_value_vectorization(nil, arg, array_fields, vectorized_values, [])
             { vectorized: result[:type] == :vectorized, source: :expression }
-            
+
           else
             { vectorized: false }
           end
         end
 
-        def extract_array_source(info, array_fields)
+        def extract_array_source(info, _array_fields)
           case info[:source]
           when :array_field_access
             info[:path]&.first
           when :cascade_condition_with_vectorized_trait
             # For cascades, we'd need to trace back to the original source
-            nil  # TODO: Could be enhanced to trace through trait dependencies
-          else
-            nil
+            nil # TODO: Could be enhanced to trace through trait dependencies
           end
         end
 
-        def analyze_cascade_vectorization(name, expr, array_fields, vectorized_values, errors)
+        def analyze_cascade_vectorization(_name, expr, array_fields, vectorized_values, errors)
           # A cascade is vectorized if:
           # 1. Any of its result expressions are vectorized, OR
           # 2. Any of its conditions reference vectorized values (traits or arrays)
           vectorized_results = []
           vectorized_conditions = []
-          
+
           expr.cases.each do |case_expr|
             # Check if result is vectorized
             result_info = analyze_value_vectorization(nil, case_expr.result, array_fields, vectorized_values, errors)
             vectorized_results << (result_info[:type] == :vectorized)
-            
+
             # Check if condition is vectorized
             condition_info = analyze_value_vectorization(nil, case_expr.condition, array_fields, vectorized_values, errors)
             vectorized_conditions << (condition_info[:type] == :vectorized)
-            
           end
-          
+
           if vectorized_results.any? || vectorized_conditions.any?
             { type: :vectorized, info: { source: :cascade_with_vectorized_conditions_or_results } }
           else
@@ -213,9 +209,9 @@ module Kumi
         def build_dimension_mismatch_error(_expr, arg_infos, array_fields, vectorized_sources)
           # Build detailed error message with type information
           summary = "Cannot broadcast operation across arrays from different sources: #{vectorized_sources.join(', ')}. "
-          
+
           problem_desc = "Problem: Multiple operands are arrays from different sources:\n"
-          
+
           vectorized_args = arg_infos.select { |info| info[:vectorized] }
           vectorized_args.each_with_index do |arg_info, index|
             array_source = arg_info[:array_source]
@@ -225,10 +221,10 @@ module Kumi
             type_desc = determine_array_type(array_source, array_fields)
             problem_desc += "  - Operand #{index + 1} resolves to #{type_desc} from array '#{array_source}'\n"
           end
-          
+
           explanation = "Direct operations on arrays from different sources is ambiguous and not supported. " \
                         "Vectorized operations can only work on fields from the same array input."
-          
+
           "#{summary}#{problem_desc}#{explanation}"
         end
 
@@ -244,8 +240,7 @@ module Kumi
             "array(mixed)"
           end
         end
-
       end
     end
   end
-end
+end

data/lib/kumi/analyzer/passes/dependency_resolver.rb

@@ -4,8 +4,8 @@ module Kumi
   module Analyzer
     module Passes
       # RESPONSIBILITY: Build dependency graph and detect conditional dependencies in cascades
-      # DEPENDENCIES: :definitions from NameIndexer, :input_meta from InputCollector
-      # PRODUCES: :dependency_graph, :transitive_dependents, :leaf_map - Dependency analysis results
+      # DEPENDENCIES: :declarations from NameIndexer, :inputs from InputCollector
+      # PRODUCES: :dependencies, :dependents, :leaves - Dependency analysis results
       # INTERFACE: new(schema, state).run(errors)
       class DependencyResolver < PassBase
         # Enhanced edge with conditional flag and cascade metadata
@@ -24,8 +24,8 @@ module Kumi
         include Syntax
 
         def run(errors)
-          definitions = get_state(:definitions)
-          input_meta = get_state(:input_meta)
+          definitions = get_state(:declarations)
+          input_meta = get_state(:inputs)
 
           dependency_graph = Hash.new { |h, k| h[k] = [] }
           reverse_dependencies = Hash.new { |h, k| h[k] = [] }
@@ -41,14 +41,14 @@ module Kumi
           # Compute transitive closure of reverse dependencies
           transitive_dependents = compute_transitive_closure(reverse_dependencies)
 
-          state.with(:dependency_graph, dependency_graph.transform_values(&:freeze).freeze)
-               .with(:transitive_dependents, transitive_dependents.freeze)
-               .with(:leaf_map, leaf_map.transform_values(&:freeze).freeze)
+          state.with(:dependencies, dependency_graph.transform_values(&:freeze).freeze)
+               .with(:dependents, transitive_dependents.freeze)
+               .with(:leaves, leaf_map.transform_values(&:freeze).freeze)
         end
 
         private
 
-        def process_node(node, decl, graph, reverse_deps, leaves, definitions, input_meta, errors, context)
+        def process_node(node, decl, graph, reverse_deps, leaves, definitions, _input_meta, errors, context)
           case node
           when DeclarationReference
             report_error(errors, "undefined reference to `#{node.name}`", location: node.loc) unless definitions.key?(node.name)

data/lib/kumi/analyzer/passes/input_collector.rb

@@ -5,7 +5,7 @@ module Kumi
     module Passes
       # RESPONSIBILITY: Collect field metadata from input declarations and validate consistency
       # DEPENDENCIES: :definitions
-      # PRODUCES: :input_meta - Hash mapping field names to {type:, domain:} metadata
+      # PRODUCES: :inputs - Hash mapping field names to {type:, domain:} metadata
       # INTERFACE: new(schema, state).run(errors)
       class InputCollector < PassBase
         def run(errors)
@@ -30,7 +30,7 @@ module Kumi
             end
           end
 
-          state.with(:input_meta, freeze_nested_hash(input_meta))
+          state.with(:inputs, freeze_nested_hash(input_meta))
         end
 
         private

data/lib/kumi/analyzer/passes/name_indexer.rb

@@ -5,7 +5,7 @@ module Kumi
     module Passes
       # RESPONSIBILITY: Build definitions index and detect duplicate names
       # DEPENDENCIES: None (first pass in pipeline)
-      # PRODUCES: :definitions - Hash mapping names to declaration nodes
+      # PRODUCES: :declarations - Hash mapping names to declaration nodes
       # INTERFACE: new(schema, state).run(errors)
       class NameIndexer < PassBase
         def run(errors)
@@ -16,7 +16,7 @@ module Kumi
             definitions[decl.name] = decl
           end
 
-          state.with(:definitions, definitions.freeze)
+          state.with(:declarations, definitions.freeze)
         end
       end
     end