kumi 0.0.18 → 0.0.19

data/docs/schema_metadata/declarations.md

@@ -1,54 +0,0 @@
-# Declarations Metadata
-
-Processed declaration metadata for all schema declarations (traits and values) with clean, serializable information.
-
-## Access
-
-```ruby
-metadata = MySchema.schema_metadata
-declarations = metadata.declarations
-```
-
-## Structure
-
-```ruby
-# Returns Hash<Symbol, Hash>
-{
-  declaration_name => {
-    type: :trait | :value,  # Declaration type
-    expression: String      # Human-readable expression
-  }
-}
-```
-
-## Example
-
-```ruby
-metadata.declarations
-# => {
-#   :adult => { type: :trait, expression: ">=(input.age, 18)" },
-#   :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" },
-#   :status => { type: :value, expression: "cascade" }
-# }
-```
-
-## Raw AST Access
-
-For advanced use cases requiring direct AST manipulation:
-
-```ruby
-raw_declarations = metadata.analyzer_state[:declarations]
-# => { :adult => #<TraitDeclaration...>, :tax_amount => #<ValueDeclaration...> }
-```
-
-## AST Node Types
-
-- **TraitDeclaration**: Boolean conditions  
-- **ValueDeclaration**: Computed values or cascades
-
-## Usage
-
-- Dependency analysis
-- Code generation  
-- AST traversal
-- Type inference

data/docs/schema_metadata/dependencies.md

@@ -1,57 +0,0 @@
-# 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

@@ -1,29 +0,0 @@
-# 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

@@ -1,95 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-# 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

@@ -1,86 +0,0 @@
-# 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

@@ -1,108 +0,0 @@
-# Schema Metadata
-
-Kumi's SchemaMetadata interface accesses 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 API documentation in the SchemaMetadata class for 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)"
-#   }
-# }
-```
-
-### Public Interface Examples
-```ruby
-# Processed dependency information
-metadata.dependencies
-# => { :tax_amount => [{ to: :income, conditional: false }, { to: :tax_rate, conditional: false }] }
-
-# Processed declaration metadata
-metadata.declarations  
-# => { :adult => { type: :trait, expression: ">=(input.age, 18)" }, :tax_amount => { type: :value, expression: "multiply(input.income, tax_rate)" } }
-
-# Type inference results
-metadata.inferred_types
-# => { :adult => :boolean, :tax_amount => :float, :item_totals => { array: :float } }
-```
-
-### Raw Analyzer State (Advanced Usage)
-```ruby
-# 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/golden/mixed_nesting/schema.kumi

@@ -1,42 +0,0 @@
-schema do
-    input do
-    hash :organization do
-        string :name
-        array :regions do
-        string :region_name
-        hash :headquarters do
-            string :city
-            array :buildings do
-            string :building_name
-            hash :facilities do
-                string :facility_type
-                integer :capacity
-                float :utilization_rate
-            end
-            end
-        end
-        end
-    end
-    end
-    
-    # Deep access across 5 levels
-    value :org_name, input.organization.name
-    value :region_names, input.organization.regions.region_name
-    value :hq_cities, input.organization.regions.headquarters.city
-    value :building_names, input.organization.regions.headquarters.buildings.building_name
-    value :facility_types, input.organization.regions.headquarters.buildings.facilities.facility_type
-    value :capacities, input.organization.regions.headquarters.buildings.facilities.capacity
-    value :utilization_rates, input.organization.regions.headquarters.buildings.facilities.utilization_rate
-    
-    # Traits using deep nesting - avoiding cross-scope issues
-    trait :large_organization, fn(:size, input.organization.regions) > 1
-    
-    # Simple cascade using traits that work within same scope
-    value :org_classification do
-    on large_organization, "Enterprise"
-    base "Standard"
-    end
-    
-    # Aggregations that work properly
-    value :total_capacity, fn(:sum, input.organization.regions.headquarters.buildings.facilities.capacity)
-end