kumi 0.0.26 → 0.0.28

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b422f7930abf2d8300bcc0a6f565a4adf1505cb722f1d51abf42e776617eb255
-  data.tar.gz: b9920b8399e8521eb7517427a36118b0ccbdd9fb1d92644db822d9dbc755b0b6
+  metadata.gz: 644df492ff48a0f3490909636f678554b93cfea464e7c133366609743d6ac8a8
+  data.tar.gz: df9b82c1e0e29466e033fac43dafda4ad990402d005d606acdf41133c3860f25
 SHA512:
-  metadata.gz: d541c8a5839a7f8e8f5cd2c4e9e8e1418e474bca0d81152f4e0043a09e059ab4839bda084aa32c141938dfb3971815071219daa2e3d5733590ba8e2d84f830ba
-  data.tar.gz: 72f061aa65ec67d5f0d99812d5429225f5a623e0a5f49fdad27260fc6335629b85ae69dada088f05aef24b00a22c912194c8075c9d7373b43fbf433954f417ca
+  metadata.gz: 71555d229915f8a71d47fe719f976c3d0e212576f1bbf5061463ede08c0e49e7126b338646036eb2573e3f1492297da8e42bc40331ce02289d4112b9d71be6f2
+  data.tar.gz: '09cd854fca02d7e15f52ea51f7153e9105075d4509b19219cd4cc0924c25048126df97de350e06d845ab6d65c5027e23e710ef2cf0a1ca59922fea3cefb45a3a'

data/CHANGELOG.md

@@ -1,5 +1,22 @@
 ## [Unreleased]
 
+## [0.0.28] – 2025-10-20
+### Changed
+- Error location formatting now uses explicit `line=` and `column=` keywords for clarity
+- Location extraction prioritizes structured Location objects over message parsing
+- Default file label changed from "(string)" to "schema" for better UX
+
+### Fixed
+- Removed redundant location information from error messages
+- Parse error messages now properly format location details
+
+## [0.0.27] – 2025-10-20
+### Added
+- Decimal type system for precise money/bignum calculations
+- Conversion functions (to_decimal, to_integer, to_float, to_string)
+- Automatic documentation generation system for IDE support
+- VSCode extension with schema block detection
+
 ## [0.0.26] – 2025-10-17
 ### Added
 - UNSAT detection via constraint propagation through operations

data/CLAUDE.md

@@ -25,6 +25,10 @@ Axes align by identity (lineage), not by name
 `bin/kumi golden verify [name]` - Verify current vs expected
 `bin/kumi golden diff <name>` - Show diffs when verification fails
 
+# Documentation Generation
+`bin/kumi-doc-gen` - Generate IDE-friendly JSON + Markdown docs from function/kernel definitions
+See docs/DEVELOPMENT.md for details
+
 # Kernels Invariants
 All reducers are pure binary combiner f : T × T → T applied over the last axis of a value. Example: agg.sum(a,b) = a+b.
 

data/README.md

@@ -7,24 +7,37 @@
 
 ---
 
-**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
+## What is Kumi?
 
-**Feedback**: have a use case or a paper cut? Open an issue or reach out.
+Kumi is a **declarative DSL for building calculation systems** that are:
+- **Typed & verifiable at compile time** (catch errors before they hit production)
+- **Vectorized** (arrays and nested data structures work naturally)
+- **Transparent** (inspect generated code and execution order)
+- **Portable** (compile the same schema to Ruby or JavaScript)
 
----
+Instead of writing procedural formulas, you declare *what* values depend on *what*, and Kumi figures out the computation order, validates types, detects impossible constraints, and generates efficient code.
+
+## Why Kumi Exists
+
+Calculation systems are everywhere: tax engines, pricing models, financial projections, compliance checks. They're usually:
+- Hard to verify (logic spread across multiple files)
+- Fragile (changing one formula breaks hidden dependencies)
+- Duplicated (same logic needed in backend and frontend)
+- Opaque (hard to audit which rules applied to which data)
 
+Kumi makes them explicit, testable, and portable.
 
-**Declarative calculation DSL for Ruby.** Write business rules once, run them anywhere.
+---
 
-Kumi compiles high-level schemas into standalone Ruby and JavaScript with no runtime dependencies. Includes static analysis to catch impossible constraints before runtime.
+**Status**: experimental. Public API may change. Typing and some static checks are still evolving.
 
-**Built for:** finance, tax, pricing, insurance, payroll, analytics—domains where correctness and transparency matter.
+**Feedback**: have a use case or hit a rough edge? Open an issue or reach out.
 
 ---
 
 ## Example: US Tax Calculator (2024)
 
-See the [interactive demo](https://kumi-play-web.fly.dev/) or browse the [golden test files](golden/us_tax_2024/) (schema, input, expected output, generated code).
+A single schema computes federal, state, FICA taxes across multiple filing statuses—all types verified at compile time. Try it in the [interactive demo](https://kumi-play-web.fly.dev/) or inspect the [full schema, input, output, and generated code](golden/us_tax_2024/).
 
 <details>
 <summary><strong>Schema</strong></summary>
@@ -122,10 +135,6 @@ Requires Ruby 3.1+. No external dependencies.
 ```ruby
 require 'kumi'
 
-Kumi.configure do |config|
-  config.compilation_mode = :jit
-end
-
 module Double
   extend Kumi::Schema
 
@@ -139,10 +148,25 @@ end
 result = Double.from(x: 5)
 result[:doubled]  # => 10
 
-# Export to JavaScript
+# Export to JavaScript (same logic)
 Double.write_source("output.mjs", platform: :javascript)
 ```
 
+Try the [interactive demo](https://kumi-play-web.fly.dev/) (no setup required).
+
+---
+
+## Documentation
+
+Auto-generated reference for all functions and kernels:
+
+- **[Functions Reference](docs/FUNCTIONS.md)** - Human-readable docs with parameters and kernels
+- **[functions-reference.json](docs/functions-reference.json)** - Machine-readable format for IDEs (VSCode, Monaco, etc.)
+
+To regenerate: `bin/kumi-doc-gen`
+
+See [docs/DEVELOPMENT.md](docs/DEVELOPMENT.md) for development workflows.
+
 ---
 
 ## License

data/data/functions/core/arithmetic.yaml

@@ -9,7 +9,9 @@ functions:
 
   - id: core.add
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
     dtype:
       rule: promote
       params: [left_operand, right_operand]
@@ -33,15 +35,19 @@ functions:
 
   - id: core.sub
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
     dtype:
       rule: promote
       params: [left_operand, right_operand]
     aliases: ["sub", "subtract"]
 
-  - id: core.mul
+  - id: core.mul:numeric
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
     dtype:
       rule: promote
       params: [left_operand, right_operand]
@@ -63,9 +69,21 @@ functions:
         # For multiplication: divide by absolute values considering sign changes
         range: "derive from result bounds and operand bounds considering sign combinations"
 
+  - id: core.mul:string_repeat
+    kind: elementwise
+    params:
+      - { name: string_value, dtype: string }
+      - { name: repeat_count, dtype: integer }
+    dtype:
+      rule: scalar
+      kind: string
+    aliases: ["mul", "multiply"]
+
   - id: core.pow
     kind: elementwise
-    params: [{ name: base }, { name: exponent }]
+    params:
+      - { name: base, dtype: numeric }
+      - { name: exponent, dtype: numeric }
     dtype:
       rule: promote
       params: [base, exponent]
@@ -73,7 +91,9 @@ functions:
 
   - id: core.div
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
     dtype:
       rule: scalar
       kind: float
@@ -82,8 +102,8 @@ functions:
   - id: core.mod
     kind: elementwise
     params:
-      - { name: left_operand }
-      - { name: right_operand }
+      - { name: left_operand, dtype: numeric }
+      - { name: right_operand, dtype: numeric }
     dtype:
       rule: promote
       params: [left_operand, right_operand]

data/data/functions/core/boolean.yaml

@@ -1,7 +1,9 @@
 functions:
   - id: core.and
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: boolean }
+      - { name: right_operand, dtype: boolean }
     dtype:
       rule: scalar
       kind: boolean
@@ -9,7 +11,9 @@ functions:
 
   - id: core.or
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: boolean }
+      - { name: right_operand, dtype: boolean }
     dtype:
       rule: scalar
       kind: boolean
@@ -17,7 +21,8 @@ functions:
 
   - id: core.not
     kind: elementwise
-    params: [{ name: operand }]
+    params:
+      - { name: operand, dtype: boolean }
     dtype:
       rule: scalar
       kind: boolean

data/data/functions/core/comparison.yaml

@@ -1,7 +1,9 @@
 functions:
   - id: core.gte
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: orderable }
+      - { name: right_operand, dtype: orderable }
     dtype:
       rule: scalar
       kind: boolean
@@ -10,7 +12,9 @@ functions:
 
   - id: core.gt
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: orderable }
+      - { name: right_operand, dtype: orderable }
     dtype:
       rule: scalar
       kind: boolean
@@ -19,7 +23,9 @@ functions:
 
   - id: core.lte
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: orderable }
+      - { name: right_operand, dtype: orderable }
     dtype:
       rule: scalar
       kind: boolean
@@ -28,7 +34,9 @@ functions:
 
   - id: core.lt
     kind: elementwise
-    params: [{ name: left_operand }, { name: right_operand }]
+    params:
+      - { name: left_operand, dtype: orderable }
+      - { name: right_operand, dtype: orderable }
     dtype:
       rule: scalar
       kind: boolean

data/data/functions/core/conversion.yaml

@@ -0,0 +1,32 @@
+functions:
+  - id: core.to_decimal
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: decimal
+    aliases: ["to_decimal"]
+
+  - id: core.to_integer
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: integer
+    aliases: ["to_integer", "to_int"]
+
+  - id: core.to_float
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: float
+    aliases: ["to_float"]
+
+  - id: core.to_string
+    kind: elementwise
+    params: [{ name: value }]
+    dtype:
+      rule: scalar
+      kind: string
+    aliases: ["to_string", "to_str"]

data/data/kernels/javascript/core/arithmetic.yaml

@@ -15,10 +15,14 @@ kernels:
     fn: core.sub
     inline: "= $0 - $1"
 
-  - id: mul:javascript:v1
-    fn: core.mul
+  - id: mul:numeric:javascript:v1
+    fn: core.mul:numeric
     inline: "= $0 * $1"
 
+  - id: mul:string_repeat:javascript:v1
+    fn: core.mul:string_repeat
+    inline: "= $0.repeat($1)"
+
   - id: pow:javascript:v1
     fn: core.pow
     inline: "= Math.pow($0, $1)"

data/data/kernels/javascript/core/coercion.yaml

@@ -0,0 +1,20 @@
+kernels:
+  - id: to_decimal:javascript:v1
+    fn: core.to_decimal
+    inline: "= typeof $0 === 'string' ? parseFloat($0) : Number($0)"
+    impl: "(value) {\n  if (typeof value === 'string') return parseFloat(value);\n  return Number(value);\n}"
+
+  - id: to_integer:javascript:v1
+    fn: core.to_integer
+    inline: "= parseInt($0)"
+    impl: "(value) { return parseInt(value); }"
+
+  - id: to_float:javascript:v1
+    fn: core.to_float
+    inline: "= parseFloat($0)"
+    impl: "(value) { return parseFloat(value); }"
+
+  - id: to_string:javascript:v1
+    fn: core.to_string
+    inline: "= String($0)"
+    impl: "(value) { return String(value); }"

data/data/kernels/ruby/core/arithmetic.yaml

@@ -17,11 +17,16 @@ kernels:
     inline: "= $0 - $1"
     impl: "(a, b)\n  a - b"
 
-  - id: mul:ruby:v1
-    fn: core.mul
+  - id: mul:numeric:ruby:v1
+    fn: core.mul:numeric
     inline: "= $0 * $1"
     impl: "(a, b)\n  a * b"
 
+  - id: mul:string_repeat:ruby:v1
+    fn: core.mul:string_repeat
+    inline: "= $0 * $1"
+    impl: "(str, count)\n  str * count"
+
   - id: pow:ruby:v1
     fn: core.pow
     inline: "= $0 ** $1"

data/data/kernels/ruby/core/coercion.yaml

@@ -0,0 +1,20 @@
+kernels:
+  - id: to_decimal:ruby:v1
+    fn: core.to_decimal
+    inline: "= $0.is_a?(BigDecimal) ? $0 : BigDecimal($0.to_s)"
+    impl: "(value)\n  case value\n  when BigDecimal then value\n  when String then BigDecimal(value)\n  when Numeric then BigDecimal(value.to_s)\n  else raise TypeError, \"Cannot coerce #{value.class} to Decimal\"\n  end"
+
+  - id: to_integer:ruby:v1
+    fn: core.to_integer
+    inline: "= $0.to_i"
+    impl: "(value)\n  value.to_i"
+
+  - id: to_float:ruby:v1
+    fn: core.to_float
+    inline: "= $0.to_f"
+    impl: "(value)\n  value.to_f"
+
+  - id: to_string:ruby:v1
+    fn: core.to_string
+    inline: "= $0.to_s"
+    impl: "(value)\n  value.to_s"

data/docs/ARCHITECTURE.md

@@ -0,0 +1,277 @@
+# Kumi Documentation & IDE Architecture
+
+## Overview
+
+This document describes the automatic documentation generation system and IDE support infrastructure for Kumi functions and kernels.
+
+## System Architecture
+
+```
+┌─────────────────────────────────────┐
+│  Function & Kernel Definitions      │
+├─────────────────────────────────────┤
+│  data/functions/*.yaml              │
+│  data/kernels/**/*.yaml             │
+└──────────────┬──────────────────────┘
+               │
+        ┌──────▼──────┐
+        │ bin/kumi-   │
+        │ doc-gen     │
+        └──────┬──────┘
+               │
+      ┌────────┴────────┐
+      │                 │
+   ┌──▼───┐      ┌─────▼──────┐
+   │ JSON │      │  Markdown  │
+   │ Data │      │  Reference │
+   └──┬───┘      └─────┬──────┘
+      │                │
+  ┌───▼──────────┐ ┌───▼─────────────────┐
+  │ IDE Tools    │ │ Developers/Docs     │
+  ├──────────────┤ ├─────────────────────┤
+  │ VSCode       │ │ docs/FUNCTIONS.md   │
+  │ Monaco       │ │ GitHub Reference    │
+  │ LSP Servers  │ │ API Documentation   │
+  └──────────────┘ └─────────────────────┘
+```
+
+## Core Components
+
+### 1. Data Sources
+
+**Function Definitions** (`data/functions/*.yaml`)
+```yaml
+functions:
+  - id: agg.sum
+    kind: reduce
+    params: [{ name: source_value }]
+    dtype: { rule: same_as, param: source_value }
+    reduction_strategy: identity  # KEY: Identity-based reducer
+    aliases: ["sum"]
+
+  - id: agg.min
+    kind: reduce
+    params: [{ name: source_value }]
+    dtype: { rule: element_of, param: source_value }
+    reduction_strategy: first_element  # KEY: First-element reducer
+    aliases: ["min"]
+```
+
+**Kernel Implementations** (`data/kernels/ruby/*.yaml`)
+```yaml
+kernels:
+  - id: agg.sum:ruby:v1
+    fn: agg.sum
+    inline: "+= $1"
+    impl: "(a,b)\n  a + b"
+    fold_inline: "= $0.sum"
+    identity:
+      float: 0.0
+      integer: 0
+```
+
+### 2. Doc Generator Module
+
+**Location:** `lib/kumi/doc_generator/`
+
+#### Loader
+- Parses YAML files from `data/functions/` and `data/kernels/`
+- Returns raw function and kernel definitions
+- No transformation or filtering
+
+#### Merger
+- Combines function definitions with kernel implementations
+- Creates entries indexed by function aliases (so `sum`, `add`, `sub` all resolvable)
+- Extracts important metadata:
+  - `reduction_strategy` - How the reducer initializes
+  - `dtype` - Type inference rules
+  - `arity` - Parameter count
+  - `kernels` - Available implementations
+
+#### Formatters
+
+**Json Formatter**
+- Output: `docs/functions-reference.json`
+- Consumer: IDE plugins (VSCode, Monaco, etc.)
+- Data:
+  - Function ID and aliases
+  - Arity and parameter info
+  - Type information
+  - Kernel availability
+  - **Reduction strategy** (for reducer distinction)
+
+**Markdown Formatter**
+- Output: `docs/FUNCTIONS.md`
+- Consumer: Developers, documentation sites
+- Presentation:
+  - Human-readable function descriptions
+  - Inline operations (`$0 = accumulator, $1 = element`)
+  - Actual implementation code
+  - Fold strategies
+  - Identity values (when applicable)
+  - **Reduction semantics** (monoid vs first-element)
+
+### 3. VSCode Extension
+
+**Location:** `vscode-extension/`
+
+**Features:**
+- Autocomplete for functions when typing `fn(:`
+- Hover tooltips with signatures
+- Schema block context detection (Ruby files only)
+- Works with `.kumi` and `.rb` files
+
+**Components:**
+- `FunctionCompletionProvider` - Offers suggestions
+- `FunctionHoverProvider` - Shows detailed information
+- `isInSchemaBlock()` - Detects if inside `schema do...end` block (Ruby files)
+
+## Key Design Decisions
+
+### 1. Reduction Strategy Distinction
+
+**Problem:** Min/Max don't have identity values like Sum/Count do.
+
+**Solution:** Capture `reduction_strategy` from YAML:
+- `identity` → Monoid operation, can use identity element
+- `first_element` → First array element initializes accumulator
+
+**Display:**
+- Markdown shows: "Monoid operation with identity element" or "First element is initial value"
+- JSON includes: `"reduction_strategy": "identity" | "first_element"`
+
+### 2. Kernel Implementation Visibility
+
+**Decision:** Show actual kernel code inline in markdown.
+
+**Benefits:**
+- Developers see what the function actually does
+- Inline operations (`+= $1` vs `= $1 if $1 < $0`) show the pattern
+- Implementation code is actual Ruby/JavaScript
+
+**Format:**
+```markdown
+**Inline:** `+= $1` ($0 = accumulator, $1 = element)
+**Implementation:**
+```ruby
+(a,b)
+  a + b
+```
+**Fold:** `= $0.sum`
+**Identity:** float: 0.0, integer: 0
+```
+
+### 3. Single Source of Truth
+
+**Flow:**
+```
+YAML definitions
+    ↓
+bin/kumi-doc-gen (one command)
+    ↓
+    ├→ docs/FUNCTIONS.md (auto-generated)
+    ├→ docs/functions-reference.json (auto-generated)
+    └→ IDE/Tools consume JSON
+```
+
+Changes to function definitions automatically flow to:
+- IDE completions
+- Markdown reference
+- JSON API
+
+### 4. Context-Aware IDE Support
+
+**Ruby files:** Only offer completions inside `schema do...end` blocks
+- Prevents noise from unrelated `fn(:` calls
+- Tracks brace nesting to detect context
+
+**Kumi files:** Always available
+- Native language file type
+
+## Data Model
+
+### Function Entry (After Merge)
+```json
+{
+  "id": "agg.sum",
+  "kind": "reduce",
+  "arity": 1,
+  "params": [{ "name": "source_value" }],
+  "dtype": { "rule": "same_as", "param": "source_value" },
+  "aliases": ["sum"],
+  "reduction_strategy": "identity",
+  "kernels": {
+    "ruby": {
+      "id": "agg.sum:ruby:v1",
+      "inline": "+= $1",
+      "impl": "(a,b)\n  a + b",
+      "fold_inline": "= $0.sum",
+      "identity": { "float": 0.0, "integer": 0 }
+    }
+  }
+}
+```
+
+## Usage Workflows
+
+### For End Users
+
+**View function reference:**
+```bash
+# Markdown documentation
+open docs/FUNCTIONS.md
+
+# IDE support (VSCode)
+cd vscode-extension && npm install && npm run compile
+# Press F5 in VSCode
+```
+
+### For Developers
+
+**Modify functions:**
+1. Update `data/functions/category/*.yaml`
+2. Run `bin/kumi-doc-gen`
+3. Commit both YAML and generated files
+
+**Add new reducer:**
+```yaml
+- id: agg.product
+  kind: reduce
+  params: [{ name: source_value }]
+  reduction_strategy: identity
+  aliases: ["product"]
+```
+Add kernel in `data/kernels/ruby/agg/numeric.yaml`, then regenerate docs.
+
+## Extension Points
+
+The architecture supports adding:
+
+1. **New formatters** (HTML, PDF, LSP protocol)
+2. **New generators** (TypeScript definitions, GraphQL schema)
+3. **New IDE support** (Neovim, Emacs plugins via LSP)
+4. **Validation** (against declared types/arity)
+
+All through the same YAML source data.
+
+## Testing
+
+- 8 comprehensive tests for doc generation
+- All 944 existing Kumi tests pass
+- No regression in core functionality
+
+## Performance
+
+- **Generation time:** <100ms for all functions
+- **File sizes:**
+  - FUNCTIONS.md: ~950 lines
+  - functions-reference.json: ~1800 lines
+- **IDE load time:** Instant (JSON loaded once on activation)
+
+## Future Improvements
+
+1. **LSP Server**: Standalone language server for any editor
+2. **Type validation**: Check function call arity at compile time
+3. **IDE diagnostics**: Show type mismatches as you type
+4. **Documentation linking**: Cross-reference related functions
+5. **Kernel visualization**: Show kernel implementations side-by-side