kumi 0.0.25 → 0.0.27

data/data/functions/core/select.yaml

@@ -2,6 +2,8 @@ functions:
   - id: __select__
     kind: elementwise
     params: [{ name: condition_mask }, { name: value_when_true }, { name: value_when_false }]
-    dtype: "same_as(value_when_true)"
+    dtype:
+      rule: same_as
+      param: value_when_true
     aliases: ["select", "if"]
     folding_class_method: select

data/data/functions/core/stencil.yaml

@@ -1,8 +1,10 @@
 functions:
   - id: roll
     kind: elementwise
-    params: [{ name: source }, { name: offset }] 
-    dtype: "same_as(source)"
+    params: [{ name: source }, { name: offset }]
+    dtype:
+      rule: same_as
+      param: source
     options:
       policy: wrap          # wrap|clamp
       axis_offset: 0
@@ -10,12 +12,19 @@ functions:
   - id: shift
     kind: elementwise
     params: [{ name: source }, { name: offset }]
-    dtype: "same_as(source)"
+    dtype:
+      rule: same_as
+      param: source
     options:
       policy: zero          # zero|clamp
       axis_offset: 0
+    constraint_semantics:
+      domain_effect: NONE
+      pure_combiner: false
 
   - id: index
     kind: elementwise
-    params: [{name: index_name, dtype: string }]
-    dtype: integer
+    params: [{ name: index_name, dtype: string }]
+    dtype:
+      rule: scalar
+      kind: integer

data/data/functions/core/string.yaml

@@ -2,18 +2,23 @@ functions:
   - id: core.concat
     kind: elementwise
     params: [{ name: left_string }, { name: right_string }]
-    dtype: "string"
+    dtype:
+      rule: scalar
+      kind: string
     aliases: ["concat"]
 
   - id: core.upcase
     kind: elementwise
     params: [{ name: string }]
-    dtype: "string"
+    dtype:
+      rule: scalar
+      kind: string
     aliases: ["upcase"]
 
   - id: core.downcase
     kind: elementwise
     params: [{ name: string }]
-    dtype: "string"
+    dtype:
+      rule: scalar
+      kind: string
     aliases: ["downcase"]
-    

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/agg/numeric.yaml

@@ -4,7 +4,7 @@ kernels:
     inline: "+= $1"
     impl: "(a,b)\n  a + b"
     fold_inline: "= $0.sum"
-    identity: 
+    identity:
       float: 0.0
       integer: 0
       

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

data/docs/DEVELOPMENT.md

@@ -0,0 +1,62 @@
+# Kumi Development Guide
+
+This document covers common development tasks and tools.
+
+## Documentation Generation
+
+### Generating Function Reference
+
+Kumi automatically generates documentation for functions and kernels from YAML definitions:
+
+```bash
+bin/kumi-doc-gen
+```
+
+This generates:
+- **JSON:** `docs/functions-reference.json` - IDE-friendly format with function signatures, parameters, and kernel mappings
+- **Markdown:** `docs/FUNCTIONS.md` - Human-readable function reference
+
+The generated docs can be used by:
+- IDEs (VSCode, Monaco) for autocomplete and hover information
+- API documentation sites
+- LSP servers for language features
+- Custom tooling
+
+Run this whenever you modify function definitions in `data/functions/` or kernels in `data/kernels/`.
+
+### Module: `Kumi::DocGenerator`
+
+Located in `lib/kumi/doc_generator/`, this module provides:
+
+- **`Loader`** - Load function and kernel definitions from YAML
+- **`Merger`** - Combine function metadata with kernel implementations
+- **`Formatters::Json`** - Generate IDE-consumable JSON
+- **`Formatters::Markdown`** - Generate markdown documentation
+
+The module is decoupled from the analyzer and compilation pipeline, making it suitable for independent use.
+
+## IDE Integration
+
+### VSCode Extension
+
+The `vscode-extension/` directory contains a VSCode extension that provides:
+- Autocomplete for Kumi functions
+- Hover tooltips with function signatures
+- Type information and arity display
+
+See [VSCODE_EXTENSION.md](VSCODE_EXTENSION.md) for setup and usage.
+
+Quick start:
+```bash
+cd vscode-extension && npm install && npm run compile
+# Then open in VSCode and press F5
+```
+
+The extension reads from `docs/functions-reference.json`, so always regenerate docs after function changes:
+```bash
+bin/kumi-doc-gen
+```
+
+---
+
+*More development guides coming soon.*