kumi 0.0.18 → 0.0.20

data/docs/AST.md

@@ -1,133 +0,0 @@
-# Kumi AST Reference
-
-## Core Node Types
-
-**Root**: Schema container
-```ruby
-Root = Struct.new(:inputs, :attributes, :traits)
-```
-
-**InputDeclaration**: Input field metadata  
-```ruby
-InputDeclaration = Struct.new(:name, :domain, :type)
-# DSL: integer :age, domain: 18..65 → InputDeclaration(:age, 18..65, :integer)
-```
-
-**TraitDeclaration**: Boolean predicate
-```ruby  
-TraitDeclaration = Struct.new(:name, :expression)
-# DSL: trait :adult, (input.age >= 18) → TraitDeclaration(:adult, CallExpression(...))
-```
-
-**ValueDeclaration**: Computed value
-```ruby
-ValueDeclaration = Struct.new(:name, :expression)  
-# DSL: value :total, fn(:add, a, b) → ValueDeclaration(:total, CallExpression(:add, [...]))
-```
-
-## Expression Nodes
-
-**CallExpression**: Function calls and operators
-```ruby
-CallExpression = Struct.new(:fn_name, :args)
-def &(other) = CallExpression.new(:and, [self, other])  # Enable chaining
-```
-
-**InputReference**: Field access (`input.field_name`)
-```ruby
-InputReference = Struct.new(:name)
-# Has operator methods: >=, <=, >, <, ==, != that create CallExpression nodes
-```
-
-**InputElementReference**: Access of nested input fields (`input.field_name.element.subelement.subsubelement`)
-```ruby
-InputElementReference = Struct.new(:path)
-# Represents nested input access
-# DSL: input.address.street → InputElementReference([:address, :street])
-```
-
-**DeclarationReference**: References to other declarations
-```ruby
-DeclarationReference = Struct.new(:name)
-# Created by: ref(:name) OR bare identifier (trait_name) in composite traits
-# DSL: ref(:adult) → DeclarationReference(:adult)
-# DSL: adult & verified → CallExpression(:and, [DeclarationReference(:adult), DeclarationReference(:verified)])
-```
-
-**Literal**: Constants (`18`, `"text"`, `true`) 
-```ruby
-Literal = Struct.new(:value)
-```
-
-**ArrayExpression**: Arrays (`[1, 2, 3]`)
-```ruby
-ArrayExpression = Struct.new(:elements)
-```
-
-## Cascade Expressions (Conditional Values)
-
-**CascadeExpression**: Container for conditional logic
-```ruby
-CascadeExpression = Struct.new(:cases)
-```
-
-**CaseExpression**: Individual conditions
-```ruby
-CaseExpression = Struct.new(:condition, :result)
-```
-
-**Case type mappings**:
-- `on :a, :b, result` → `condition: fn(:cascade_and, ref(:a), ref(:b))`  
-- `on_any :a, :b, result` → `condition: fn(:any?, ref(:a), ref(:b))`
-- `base result` → `condition: literal(true)`
-
-## Key Nuances
-
-**Operator methods on InputReference**: Enable `input.age >= 18` syntax by defining operators that create `CallExpression` nodes
-
-**CallExpression `&` method**: Enables expression chaining like `(expr1) & (expr2)`
-
-**Node immutability**: AST nodes are frozen after construction; analysis results stored separately
-
-**Location tracking**: All nodes include file/line/column for error reporting
-
-**Tree traversal**: Each node defines `children` method for recursive processing
-
-**Expression wrapping**: During parsing, raw values auto-convert to `Literal` nodes via `ensure_syntax()`
-
-## Common Expression Trees
-
-**Simple**: `(input.age >= 18)`
-```
-CallExpression(:>=, [InputReference(:age), Literal(18)])
-```
-
-**Chained AND**: `(input.age >= 21) & (input.verified == true)`  
-```
-CallExpression(:and, [
-  CallExpression(:>=, [InputReference(:age), Literal(21)]),
-  CallExpression(:==, [InputReference(:verified), Literal(true)])
-])
-```
-
-**Composite Trait**: `adult & verified & high_income`
-```
-CallExpression(:and, [
-  CallExpression(:and, [
-    DeclarationReference(:adult),
-    DeclarationReference(:verified)
-  ]),
-  DeclarationReference(:high_income)
-])
-```
-
-**Mixed Composition**: `adult & (input.score > 80) & verified`
-```
-CallExpression(:and, [
-  CallExpression(:and, [
-    DeclarationReference(:adult),
-    CallExpression(:>, [InputReference(:score), Literal(80)])
-  ]),
-  DeclarationReference(:verified)
-])
-```

data/docs/DSL.md

@@ -1,154 +0,0 @@
-# Kumi DSL Reference
-
-Kumi is a declarative language for defining, analyzing, and executing complex business logic. It compiles rules into a verifiable dependency graph, ensuring that logic is **sound, maintainable, and free of contradictions** before execution (as much as possible given the current library implementation).
-
------
-
-## Guiding Principles
-
-Kumi's design is opinionated and guides you toward creating robust and analyzable business logic.
-
-  * **Logic as Code, Not Just Configuration**: Rules are expressed in a clean, readable DSL that can be version-controlled and tested.
-  * **Provable Correctness**: A multi-pass analyzer statically verifies your schema, detecting duplicates, circular dependencies, type errors, and even **logically impossible conditions** (e.g., `age < 25 AND age > 65`) at compile time.
-  * **Explicit Data Contracts**: The mandatory `input` block serves as a formal, self-documenting contract for the data your schema expects, enabling runtime validation of types and domain constraints.
-  * **Composition Over Complexity**: Complex rules are built by composing simpler, named concepts (`trait`s), rather than creating large, monolithic blocks of logic.
-
------
-
-## Core Syntax
-
-A Kumi schema contains an `input` block to declare its data contract, followed by `trait` and `value` definitions.
-
-```ruby
-schema do
-  # 1. Define the data contract for this schema.
-  input do
-    # ... field declarations
-  end
-
-  # 2. Define reusable boolean predicates (traits).
-  # ... trait definitions
-
-  # 3. Define computed fields (values).
-  # ... value definitions
-end
-```
-
------
-
-## Input Fields: The Data Contract
-
-The `input` block declares the schema's data dependencies. All external data must be accessed via the `input` object (e.g., `input.age`).
-
-### **Declaration Methods**
-
-The preferred way to declare fields is with **type-specific methods**, which provide compile-time type checking and runtime validation.
-
-  * **Primitives**:
-    ```ruby
-    string  :name
-    integer :age, domain: 18..65
-    float   :score, domain: 0.0..100.0
-    boolean :is_active
-    ```
-  * **Collections**:
-    ```ruby
-    array :tags, elem: { type: :string }
-    hash  :metadata, key: { type: :string }, val: { type: :any }
-    ```
-
-### **Domain Constraints**
-
-Attach validation rules directly to input fields using `domain:`. These are checked when data is loaded.
-
-  * **Range**: `domain: 1..100` or `0.0...1.0` (exclusive end)
-  * **Enumeration**: `domain: %w[pending active archived]`
-  * **Custom Logic**: `domain: ->(value) { value.even? }`
-
------
-
-## Traits: Named Logical Predicates
-
-A **`trait`** is a named expression that **must evaluate to a boolean**. Traits are the fundamental building blocks of logic, defining reusable, verifiable conditions.
-
-### **Defining & Composing Traits**
-
-Traits are defined with a parenthesized expression and composed using the `&` operator. This composition is strictly **conjunctive (logical AND)**, a key constraint that enables Kumi's powerful static analysis.
-
-```ruby
-# Base Traits
-trait :is_adult, (input.age >= 18)
-trait :is_verified, (input.status == "verified")
-
-# Composite Trait (is_adult AND is_verified)
-trait :can_proceed, is_adult & is_verified
-
-# Mix bare trait names with inline expressions
-trait :is_eligible, is_adult & is_verified & (input.score > 50)
-```
-
------
-
-## Values: Computed Fields
-
-A **`value`** is a named expression that computes a field of any type.
-
-### **Simple Values**
-
-Values can be defined with expressions using `input` fields, functions (`fn`), and references to other values.
-
-```ruby
-value :full_name, fn(:concat, input.first_name, " ", input.last_name)
-value :discounted_price, fn(:multiply, input.base_price, 0.8)
-```
-
-### **Conditional Values (Cascades)**
-
-For conditional logic, a `value` takes a block to create a **cascade**. Cascades select a result based on a series of conditions, which **must reference named `trait`s**. This enforces clarity by separating the *what* (the condition's name) from the *how* (its implementation).
-
-```ruby
-value :access_level do
-  # `on` implies AND: user must be :premium AND :verified.
-  on premium,verified, "Full Access"
-
-  # `on_any` implies OR: user can be :staff OR :admin.
-  on_any staff,admin, "Elevated Access"
-
-  # `on_none` implies NOT (A OR B): user is neither :blocked NOR :suspended.
-  on_none blocked,suspended, "Limited Access"
-
-  # `base` is the default if no other conditions match.
-  base "No Access"
-end
-```
-
------
-
-## The Kumi Pattern: Separating AND vs. OR Logic
-
-Kumi intentionally enforces a pattern for handling different types of logic to maximize clarity and analyzability.
-
-  * **`trait`s and `&` are for AND logic**: Use `trait` composition to build up a set of conditions that must *all* be true. This is your primary tool for defining constraints.
-
-  * **`value` cascades are for OR logic**: Use `on_any` within a `value` cascade to handle conditions where *any* one of several predicates is sufficient. This is the idiomatic way to express disjunctive logic.
-
-This separation forces complex `OR` conditions to be handled within the clear, readable structure of a cascade, rather than being hidden inside a complex `trait` definition.
-
------
-
-## Best Practices
-
-  * **Prefer Small, Composable Traits**: Avoid creating large, monolithic traits with many `&` conditions. Instead, define smaller, named traits and compose them.
-
-    ```ruby
-    # AVOID: Hard to read and reuse
-    trait :eligible, (input.age >= 18) & (input.status == "active") & (input.score > 50)
-
-    # PREFER: Clear, reusable, and self-documenting
-    trait :is_adult, (input.age >= 18)
-    trait :is_active, (input.status == "active")
-    trait :has_good_score, (input.score > 50)
-    trait :is_eligible, is_adult & is_active & has_good_score
-    ```
-
-  * **Name All Conditions**: If you need to use a condition in a `value` cascade, define it as a `trait` first. This gives the condition a clear business name and makes the cascade easier to read.

data/docs/FUNCTIONS.md

@@ -1,176 +0,0 @@
-# Kumi Standard Function Library Reference
-
-Kumi provides a rich library of built-in functions for use within `value` and `trait` expressions via `fn(...)`.
-
-## Logical Functions
-
-* **`all?`**: Check if all elements in collection are truthy
-  * **Usage**: `fn(:all?, array(any) arg1)` → `boolean`
-* **`and`**: Logical AND of multiple conditions
-  * **Usage**: `fn(:and, boolean1, boolean2, ...)` → `boolean`
-* **`any?`**: Check if any element in collection is truthy
-  * **Usage**: `fn(:any?, array(any) arg1)` → `boolean`
-* **`cascade_and`**: Element-wise AND for arrays with same nested structure
-  * **Usage**: `fn(:cascade_and, boolean1, boolean2, ...)` → `boolean`
-* **`none?`**: Check if no elements in collection are truthy
-  * **Usage**: `fn(:none?, array(any) arg1)` → `boolean`
-* **`not`**: Logical NOT
-  * **Usage**: `fn(:not, boolean arg1)` → `boolean`
-* **`or`**: Logical OR of multiple conditions
-  * **Usage**: `fn(:or, boolean1, boolean2, ...)` → `boolean`
-
-## Comparison Functions
-
-* **`!=`**: Inequality comparison
-  * **Usage**: `fn(:!=, any arg1, any arg2)` → `boolean`
-* **`<`**: Less than comparison
-  * **Usage**: `fn(:<, float arg1, float arg2)` → `boolean`
-* **`<=`**: Less than or equal comparison
-  * **Usage**: `fn(:<=, float arg1, float arg2)` → `boolean`
-* **`==`**: Equality comparison
-  * **Usage**: `fn(:==, any arg1, any arg2)` → `boolean`
-* **`>`**: Greater than comparison
-  * **Usage**: `fn(:>, float arg1, float arg2)` → `boolean`
-* **`>=`**: Greater than or equal comparison
-  * **Usage**: `fn(:>=, float arg1, float arg2)` → `boolean`
-* **`between?`**: Check if value is between min and max
-  * **Usage**: `fn(:between?, float arg1, float arg2, float arg3)` → `boolean`
-
-## Math Functions
-
-* **`abs`**: Absolute value
-  * **Usage**: `fn(:abs, float arg1)` → `float`
-* **`add`**: Add two numbers
-  * **Usage**: `fn(:add, float arg1, float arg2)` → `float`
-* **`ceil`**: Ceiling of number
-  * **Usage**: `fn(:ceil, float arg1)` → `integer`
-* **`clamp`**: Clamp value between min and max
-  * **Usage**: `fn(:clamp, float arg1, float arg2, float arg3)` → `float`
-* **`divide`**: Divide first number by second
-  * **Usage**: `fn(:divide, float arg1, float arg2)` → `float`
-* **`floor`**: Floor of number
-  * **Usage**: `fn(:floor, float arg1)` → `integer`
-* **`modulo`**: Modulo operation
-  * **Usage**: `fn(:modulo, float arg1, float arg2)` → `float`
-* **`multiply`**: Multiply two numbers
-  * **Usage**: `fn(:multiply, float arg1, float arg2)` → `float`
-* **`piecewise_sum`**: Accumulate over tiered ranges; returns [sum, marginal_rate]
-  * **Usage**: `fn(:piecewise_sum, float arg1, array(float) arg2, array(float) arg3)` → `array(float)`
-* **`power`**: Raise first number to power of second
-  * **Usage**: `fn(:power, float arg1, float arg2)` → `float`
-* **`round`**: Round number to specified precision
-  * **Usage**: `fn(:round, float1, float2, ...)` → `float`
-* **`subtract`**: Subtract second number from first
-  * **Usage**: `fn(:subtract, float arg1, float arg2)` → `float`
-
-## String Functions
-
-* **`capitalize`**: Capitalize first letter of string
-  * **Usage**: `fn(:capitalize, string arg1)` → `string`
-* **`concat`**: Concatenate multiple strings
-  * **Usage**: `fn(:concat, string1, string2, ...)` → `string`
-* **`contains?`**: Check if string contains substring
-  * **Usage**: `fn(:contains?, string arg1, string arg2)` → `boolean`
-* **`downcase`**: Convert string to lowercase
-  * **Usage**: `fn(:downcase, string arg1)` → `string`
-* **`end_with?`**: Check if string ends with suffix
-  * **Usage**: `fn(:end_with?, string arg1, string arg2)` → `boolean`
-* **`includes?`**: Check if string contains substring
-  * **Usage**: `fn(:includes?, string arg1, string arg2)` → `boolean`
-* **`length`**: Get string length
-  * **Usage**: `fn(:length, string arg1)` → `integer`
-* **`start_with?`**: Check if string starts with prefix
-  * **Usage**: `fn(:start_with?, string arg1, string arg2)` → `boolean`
-* **`string_include?`**: Check if string contains substring
-  * **Usage**: `fn(:string_include?, string arg1, string arg2)` → `boolean`
-* **`string_length`**: Get string length
-  * **Usage**: `fn(:string_length, string arg1)` → `integer`
-* **`strip`**: Remove leading and trailing whitespace
-  * **Usage**: `fn(:strip, string arg1)` → `string`
-* **`upcase`**: Convert string to uppercase
-  * **Usage**: `fn(:upcase, string arg1)` → `string`
-
-## Collection Functions
-
-* **`all_across`**: Check if all elements are truthy across all nested levels
-  * **Usage**: `fn(:all_across, array(any) arg1)` → `boolean`
-* **`any_across`**: Check if any element is truthy across all nested levels
-  * **Usage**: `fn(:any_across, array(any) arg1)` → `boolean`
-* **`avg_if`**: Average values where corresponding condition is true
-  * **Usage**: `fn(:avg_if, array(float) arg1, array(boolean) arg2)` → `float`
-* **`build_array`**: Build array of given size with index values
-  * **Usage**: `fn(:build_array, integer arg1)` → `array(any)`
-* **`count_across`**: Count total elements across all nested levels
-  * **Usage**: `fn(:count_across, array(any) arg1)` → `integer`
-* **`count_if`**: Count number of true values in boolean array
-  * **Usage**: `fn(:count_if, array(boolean) arg1)` → `integer`
-* **`each_slice`**: Group array elements into subarrays of given size
-  * **Usage**: `fn(:each_slice, array arg1, integer arg2)` → `array(array)`
-* **`empty?`**: Check if collection is empty
-  * **Usage**: `fn(:empty?, array(any) arg1)` → `boolean`
-* **`first`**: Get first element of collection
-  * **Usage**: `fn(:first, array(any) arg1)` → `any`
-* **`flatten`**: Flatten nested arrays into a single array
-  * **Usage**: `fn(:flatten, array(any) arg1)` → `array(any)`
-* **`flatten_deep`**: Recursively flatten all nested arrays (alias for flatten)
-  * **Usage**: `fn(:flatten_deep, array(any) arg1)` → `array(any)`
-* **`flatten_one`**: Flatten nested arrays by one level only
-  * **Usage**: `fn(:flatten_one, array(any) arg1)` → `array(any)`
-* **`include?`**: Check if collection includes element
-  * **Usage**: `fn(:include?, array(any) arg1, any arg2)` → `boolean`
-* **`indices`**: Generate array of indices for the collection
-  * **Usage**: `fn(:indices, array(any) arg1)` → `array(integer)`
-* **`join`**: Join array elements into string with separator
-  * **Usage**: `fn(:join, array arg1, string arg2)` → `string`
-* **`last`**: Get last element of collection
-  * **Usage**: `fn(:last, array(any) arg1)` → `any`
-* **`map_add`**: Add value to each element
-  * **Usage**: `fn(:map_add, array(float) arg1, float arg2)` → `array(float)`
-* **`map_conditional`**: Transform elements based on condition: if element == condition_value then true_value else false_value
-  * **Usage**: `fn(:map_conditional, array arg1, any arg2, any arg3, any arg4)` → `array`
-* **`map_join_rows`**: Join 2D array into string with row and column separators
-  * **Usage**: `fn(:map_join_rows, array(array) arg1, string arg2, string arg3)` → `string`
-* **`map_multiply`**: Multiply each element by factor
-  * **Usage**: `fn(:map_multiply, array(float) arg1, float arg2)` → `array(float)`
-* **`map_with_index`**: Map collection elements to [element, index] pairs
-  * **Usage**: `fn(:map_with_index, array(any) arg1)` → `array(any)`
-* **`max`**: Find maximum value in numeric collection
-  * **Usage**: `fn(:max, array(float) arg1)` → `float`
-* **`min`**: Find minimum value in numeric collection
-  * **Usage**: `fn(:min, array(float) arg1)` → `float`
-* **`range`**: Generate range of integers from start to finish (exclusive)
-  * **Usage**: `fn(:range, integer arg1, integer arg2)` → `array(integer)`
-* **`reverse`**: Reverse collection order
-  * **Usage**: `fn(:reverse, array(any) arg1)` → `array(any)`
-* **`size`**: Get collection size
-  * **Usage**: `fn(:size, array(any) arg1)` → `integer`
-* **`sort`**: Sort collection
-  * **Usage**: `fn(:sort, array(any) arg1)` → `array(any)`
-* **`sum`**: Sum all numeric elements in collection
-  * **Usage**: `fn(:sum, array(float) arg1)` → `float`
-* **`sum_if`**: Sum values where corresponding condition is true
-  * **Usage**: `fn(:sum_if, array(float) arg1, array(boolean) arg2)` → `float`
-* **`unique`**: Remove duplicate elements from collection
-  * **Usage**: `fn(:unique, array(any) arg1)` → `array(any)`
-
-## Conditional Functions
-
-* **`coalesce`**: Return first non-nil value
-  * **Usage**: `fn(:coalesce, any1, any2, ...)` → `any`
-* **`conditional`**: Ternary conditional operator
-  * **Usage**: `fn(:conditional, boolean arg1, any arg2, any arg3)` → `any`
-* **`if`**: If-then-else conditional
-  * **Usage**: `fn(:if, boolean1, boolean2, ...)` → `any`
-
-## Type & Hash Functions
-
-* **`at`**: Get element at index from array
-  * **Usage**: `fn(:at, array(any) arg1, integer arg2)` → `any`
-* **`fetch`**: Fetch value from hash with optional default
-  * **Usage**: `fn(:fetch, hash(any, any)1, hash(any, any)2, ...)` → `any`
-* **`has_key?`**: Check if hash has the given key
-  * **Usage**: `fn(:has_key?, hash(any, any) arg1, any arg2)` → `boolean`
-* **`keys`**: Get all keys from hash
-  * **Usage**: `fn(:keys, hash(any, any) arg1)` → `array(any)`
-* **`values`**: Get all values from hash
-  * **Usage**: `fn(:values, hash(any, any) arg1)` → `array(any)`