kumi 0.0.25 → 0.0.27

data/lib/kumi/doc_generator/formatters/json.rb

@@ -0,0 +1,39 @@
+require 'json'
+
+module Kumi
+  module DocGenerator
+    module Formatters
+      class Json
+        def initialize(docs)
+          @docs = docs
+        end
+
+        def format
+          enriched = @docs.each_with_object({}) do |(alias_name, entry), acc|
+            kernel_ids = extract_kernel_ids(entry['kernels'])
+            acc[alias_name] = {
+              'id' => entry['id'],
+              'kind' => entry['kind'],
+              'arity' => entry['arity'],
+              'params' => entry['params'],
+              'kernels' => kernel_ids,
+              'dtype' => entry['dtype'],
+              'aliases' => entry['aliases'],
+              'reduction_strategy' => entry['reduction_strategy']
+            }
+          end
+
+          JSON.pretty_generate(enriched)
+        end
+
+        private
+
+        def extract_kernel_ids(kernels)
+          kernels.each_with_object({}) do |(target, kernel), acc|
+            acc[target] = kernel.is_a?(Hash) ? kernel['id'] : kernel
+          end
+        end
+      end
+    end
+  end
+end

data/lib/kumi/doc_generator/formatters/markdown.rb

@@ -0,0 +1,175 @@
+module Kumi
+  module DocGenerator
+    module Formatters
+      class Markdown
+        def initialize(docs)
+          @docs = docs
+        end
+
+        def format
+          lines = [
+            "# Kumi Function Reference",
+            "",
+            "Auto-generated documentation for Kumi functions and their kernels.",
+            ""
+          ]
+
+          grouped = group_by_id(@docs)
+
+          grouped.sort.each do |id, aliases|
+            entry = @docs[aliases.first]
+            lines.concat(format_function(id, entry, aliases))
+          end
+
+          lines.join("\n")
+        end
+
+        private
+
+        def group_by_id(docs)
+          result = {}
+          docs.each do |alias_name, entry|
+            id = entry['id']
+            result[id] ||= []
+            result[id] << alias_name
+          end
+          result
+        end
+
+        def format_function(id, entry, aliases)
+          lines = [
+            "## `#{id}`",
+            ""
+          ]
+
+          if aliases.length > 1
+            lines << "**Aliases:** `#{aliases.sort.join('`, `')}`"
+            lines << ""
+          end
+
+          lines << "- **Arity:** #{entry['arity']}"
+
+          if entry['dtype']
+            dtype_str = format_dtype(entry['dtype'])
+            lines << "- **Type:** #{dtype_str}"
+          end
+
+          if is_reducer?(entry)
+            lines << "- **Behavior:** Reduces a dimension `[D] -> T`"
+          end
+          lines << ""
+
+          if entry['params'] && !entry['params'].empty?
+            lines << "### Parameters"
+            lines << ""
+            entry['params'].each do |param|
+              lines << "- `#{param['name']}`#{param['description'] ? ": #{param['description']}" : ""}"
+            end
+            lines << ""
+          end
+
+          if entry['kernels'] && !entry['kernels'].empty?
+            lines << "### Implementations"
+            lines << ""
+            entry['kernels'].each do |target, kernel|
+              lines.concat(format_kernel(target, kernel, entry['reduction_strategy']))
+            end
+          end
+
+          lines
+        end
+
+        def format_kernel(target, kernel, reduction_strategy = nil)
+          lines = []
+
+          if kernel.is_a?(Hash)
+            lines << "#### #{target.capitalize}"
+            lines << ""
+            lines << "`#{kernel['id']}`"
+            lines << ""
+
+            has_identity = kernel['identity'] && !kernel['identity'].empty?
+
+            if kernel['inline'] && has_identity
+              lines << "**Inline:** `#{escape_backticks(kernel['inline'])}` (`$0` = accumulator, `$1` = element)"
+              lines << ""
+            end
+
+            if kernel['impl']
+              lines << "**Implementation:**"
+              lines << ""
+              lines << "```ruby"
+              lines << format_impl(kernel['impl'])
+              lines << "```"
+              lines << ""
+            end
+
+            if kernel['fold_inline']
+              lines << "**Fold:** `#{escape_backticks(kernel['fold_inline'])}`"
+              lines << ""
+            end
+
+            if has_identity
+              lines << "**Identity:**"
+              kernel['identity'].each do |type, value|
+                lines << "- #{type}: `#{value}`"
+              end
+              lines << ""
+            elsif kernel['inline']
+              lines << "_Note: No identity value. First element initializes accumulator._"
+              lines << ""
+            end
+
+            # Show reduction strategy if available
+            if reduction_strategy
+              case reduction_strategy
+              when 'identity'
+                lines << "**Reduction:** Monoid operation with identity element"
+              when 'first_element'
+                lines << "**Reduction:** First element is initial value (no identity)"
+              else
+                lines << "**Reduction:** #{reduction_strategy}"
+              end
+              lines << ""
+            end
+          else
+            lines << "- **#{target}:** `#{kernel}`"
+          end
+
+          lines
+        end
+
+        def format_dtype(dtype)
+          return "any" if dtype.nil?
+
+          case dtype['rule']
+          when 'same_as'
+            "same as `#{dtype['param']}`"
+          when 'scalar'
+            dtype['kind'] || 'scalar'
+          when 'promote'
+            params = Array(dtype['params']).join('`, `')
+            "promoted from `#{params}`"
+          when 'element_of'
+            "element of `#{dtype['param']}`"
+          else
+            dtype['rule']
+          end
+        end
+
+        def format_impl(impl_str)
+          # Clean up multiline strings like "(a,b)\n  a + b"
+          impl_str.gsub('\n', "\n").strip
+        end
+
+        def escape_backticks(str)
+          str.gsub('`', '\`')
+        end
+
+        def is_reducer?(entry)
+          entry['kind'] == 'reduce'
+        end
+      end
+    end
+  end
+end

data/lib/kumi/doc_generator/loader.rb

@@ -0,0 +1,37 @@
+require 'yaml'
+
+module Kumi
+  module DocGenerator
+    class Loader
+      def initialize(functions_dir: nil, kernels_dir: nil)
+        @functions_dir = functions_dir
+        @kernels_dir = kernels_dir
+      end
+
+      def load_functions
+        return [] unless @functions_dir
+        load_yaml_dir(@functions_dir)
+      end
+
+      def load_kernels
+        return [] unless @kernels_dir
+        load_yaml_dir(@kernels_dir)
+      end
+
+      private
+
+      def load_yaml_dir(dir_path)
+        result = []
+        Dir.glob(File.join(dir_path, '**/*.yaml')).each do |file|
+          data = YAML.load_file(file)
+          if data && data['functions']
+            result.concat(data['functions'])
+          elsif data && data['kernels']
+            result.concat(data['kernels'])
+          end
+        end
+        result
+      end
+    end
+  end
+end

data/lib/kumi/doc_generator/merger.rb

@@ -0,0 +1,54 @@
+module Kumi
+  module DocGenerator
+    class Merger
+      def initialize(loader)
+        @loader = loader
+      end
+
+      def merge
+        functions = @loader.load_functions
+        kernels = @loader.load_kernels
+
+        result = {}
+
+        functions.each do |fn|
+          aliases = fn['aliases'] || []
+          aliases.each do |alias_name|
+            result[alias_name] = build_doc_entry(fn, kernels)
+          end
+        end
+
+        result
+      end
+
+      private
+
+      def build_doc_entry(function, kernels)
+        kernel_map = {}
+        kernels.each do |kernel|
+          if kernel['fn'] == function['id']
+            target = extract_target(kernel['id'])
+            kernel_map[target] = kernel
+          end
+        end
+
+        {
+          'id' => function['id'],
+          'kind' => function['kind'],
+          'params' => function['params'] || [],
+          'arity' => (function['params'] || []).length,
+          'kernels' => kernel_map,
+          'dtype' => function['dtype'],
+          'aliases' => function['aliases'] || [],
+          'reduction_strategy' => function['reduction_strategy']
+        }
+      end
+
+      def extract_target(kernel_id)
+        # kernel_id format: "agg.sum:ruby:v1" -> "ruby"
+        parts = kernel_id.split(':')
+        parts[1] if parts.length >= 2
+      end
+    end
+  end
+end

data/lib/kumi/doc_generator.rb

@@ -0,0 +1,4 @@
+module Kumi
+  module DocGenerator
+  end
+end

data/lib/kumi/registry_v2/loader.rb

@@ -7,6 +7,96 @@ module Kumi
     module Loader
       module_function
 
+      # Build dtype rule from YAML specification (structured or legacy string format)
+      def build_dtype_rule_from_yaml(dtype_spec)
+        case dtype_spec
+        when String
+          # Legacy string format: "same_as(x)", "promote(a,b)", "integer", etc.
+          Kumi::Core::Functions::TypeRules.compile_dtype_rule(dtype_spec, [])
+        when Hash
+          # Structured format: { rule: 'same_as', param: 'x' }
+          build_dtype_rule_from_hash(dtype_spec)
+        else
+          raise "Invalid dtype specification: #{dtype_spec.inspect}"
+        end
+      end
+
+      # Build dtype rule from structured hash
+      def build_dtype_rule_from_hash(spec)
+        rule_type = spec.fetch('rule') { raise "dtype hash requires 'rule' key" }
+
+        case rule_type
+        when 'same_as'
+          param = spec.fetch('param') { raise "same_as rule requires 'param' key" }
+          Kumi::Core::Functions::TypeRules.build_same_as(param.to_sym)
+
+        when 'promote'
+          params = spec.fetch('params') { raise "promote rule requires 'params' key" }
+          param_syms = Array(params).map { |p| p.to_sym }
+          Kumi::Core::Functions::TypeRules.build_promote(*param_syms)
+
+        when 'element_of'
+          param = spec.fetch('param') { raise "element_of rule requires 'param' key" }
+          Kumi::Core::Functions::TypeRules.build_element_of(param.to_sym)
+
+        when 'unify'
+          param1 = spec.fetch('param1') { raise "unify rule requires 'param1' key" }
+          param2 = spec.fetch('param2') { raise "unify rule requires 'param2' key" }
+          Kumi::Core::Functions::TypeRules.build_unify(param1.to_sym, param2.to_sym)
+
+        when 'common_type'
+          param = spec.fetch('param') { raise "common_type rule requires 'param' key" }
+          Kumi::Core::Functions::TypeRules.build_common_type(param.to_sym)
+
+        when 'array'
+          if spec.key?('element_type')
+            element_type_spec = spec['element_type']
+            element_type = if element_type_spec.is_a?(Hash)
+                            # Nested structured format
+                            build_dtype_rule_from_hash(element_type_spec).call({})
+                          else
+                            # String or symbol
+                            element_type_spec.to_sym
+                          end
+            Kumi::Core::Functions::TypeRules.build_array(element_type)
+          elsif spec.key?('element_type_param')
+            element_type_param = spec['element_type_param'].to_sym
+            Kumi::Core::Functions::TypeRules.build_array(element_type_param)
+          else
+            raise "array rule requires either 'element_type' or 'element_type_param' key"
+          end
+
+        when 'tuple'
+          if spec.key?('element_types')
+            element_types_spec = spec['element_types']
+            element_types = Array(element_types_spec).map do |et|
+              if et.is_a?(Hash)
+                build_dtype_rule_from_hash(et).call({})
+              else
+                et.to_sym
+              end
+            end
+            Kumi::Core::Functions::TypeRules.build_tuple(*element_types)
+          elsif spec.key?('element_types_param')
+            element_types_param = spec['element_types_param'].to_sym
+            Kumi::Core::Functions::TypeRules.build_tuple(element_types_param)
+          else
+            raise "tuple rule requires either 'element_types' or 'element_types_param' key"
+          end
+
+        when 'scalar'
+          kind = spec.fetch('kind') { raise "scalar rule requires 'kind' key" }
+          kind_sym = kind.to_sym
+          unless Kumi::Core::Types::Validator.valid_kind?(kind_sym)
+            raise "scalar rule has unknown kind: #{kind}"
+          end
+          Kumi::Core::Functions::TypeRules.build_scalar(kind_sym)
+
+        else
+          raise "unknown dtype rule: #{rule_type}"
+        end
+      end
+
       # { "core.mul" => Function(id: "core.mul", kind: :elementwise, params: [...]) }
       def load_functions(dir, func_struct)
         files = Dir.glob(File.join(dir, "**", "*.y{a,}ml")).sort

data/lib/kumi/registry_v2.rb

@@ -22,7 +22,7 @@ module Kumi
       end
 
       def dtype_rule
-        @dtype_rule ||= Core::Functions::TypeRules.compile_dtype_rule(dtype, param_names)
+        @dtype_rule ||= Loader.build_dtype_rule_from_yaml(dtype)
       end
     end
 
@@ -32,6 +32,7 @@ module Kumi
       def initialize(functions_by_id, kernels_by_key)
         @functions = functions_by_id                         # "core.mul" => Function<...>
         @alias     = build_alias(@functions)                 # "count" => "agg.count"
+        @overload_resolver = Core::Functions::OverloadResolver.new(@functions)
         @kernels   = kernels_by_key                          # [fn_id, target_sym] => Kernel
         @by_id     = @kernels.values.to_h { |k| [k.id, k] }
       end
@@ -50,6 +51,12 @@ module Kumi
         end
       end
 
+      # Type-aware function resolution for overloads
+      # Returns the function_id that best matches the given argument types
+      def resolve_function_with_types(alias_or_id, arg_types)
+        @overload_resolver.resolve(alias_or_id, arg_types)
+      end
+
       def function_kind(id)        = function(id).kind
       def function_reduce?(id)     = function(id).reduce?
       def function_elementwise?(id) = function(id).elementwise?
@@ -104,6 +111,16 @@ module Kumi
           func.aliases.each { |al| acc[al] = func.id }
         end
       end
+
+      def build_alias_overloads(functions)
+        # Maps each alias to an array of all function_ids that have that alias
+        functions.values.each_with_object({}) do |func, acc|
+          func.aliases.each do |al|
+            acc[al] ||= []
+            acc[al] << func.id
+          end
+        end
+      end
     end
 
     module_function

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.25"
+  VERSION = "0.0.27"
 end

data/vscode-extension/.gitignore

@@ -0,0 +1,4 @@
+node_modules/
+out/
+*.vsix
+.DS_Store

data/vscode-extension/README.md

@@ -0,0 +1,59 @@
+# Kumi Language Support for VSCode
+
+VSCode extension providing autocomplete, hover information, and documentation for Kumi functions.
+
+## Features
+
+- **Autocomplete** - Function suggestions when typing `fn(:` in Ruby files
+- **Hover Information** - Type signatures, arity, and parameter info on hover
+- **Function Reference** - Auto-generated from `docs/functions-reference.json`
+
+## Installation
+
+1. Build the extension:
+```bash
+npm install
+npm run compile
+```
+
+2. Install in VSCode:
+   - Open VSCode Command Palette: `Cmd+Shift+P` (Mac) or `Ctrl+Shift+P` (Linux/Windows)
+   - Type "Extensions: Install from VSIX"
+   - Select the built `.vsix` file
+
+Or load as development extension:
+   - Open VSCode with this folder
+   - Press `F5` to start debugging
+
+## Usage
+
+While editing a Ruby file with Kumi schemas:
+
+```ruby
+schema do
+  input { float :x }
+
+  # Type `fn(:` and get autocomplete suggestions
+  let :doubled, fn(:mul, input.x, 2)
+
+  # Hover over `mul` to see type info
+  value :result, doubled
+end
+```
+
+## Data Source
+
+Function definitions are loaded from `../../docs/functions-reference.json`, which is auto-generated by:
+
+```bash
+bin/kumi-doc-gen
+```
+
+Always regenerate the JSON after modifying function definitions!
+
+## Development
+
+```bash
+npm run watch   # Watch for TypeScript changes
+npm run compile # Build once
+```

data/vscode-extension/TESTING.md

@@ -0,0 +1,151 @@
+# Testing the Kumi VSCode Extension
+
+## Quick Start
+
+### 1. Build the Extension
+
+```bash
+cd vscode-extension
+npm install
+npm run compile
+```
+
+### 2. Generate Function Data
+
+Before testing, generate the function reference JSON:
+
+```bash
+# From kumi root
+bin/kumi-doc-gen
+```
+
+This creates `docs/functions-reference.json` that the extension reads.
+
+### 3. Launch Extension in Debug Mode
+
+```bash
+# From vscode-extension directory
+code ..
+```
+
+Or just open the kumi repo root in VSCode, then:
+- Press `F5` to start debugging
+- A new VSCode window will open with the extension loaded
+
+### 4. Test Autocomplete and Hover
+
+Open `examples/demo-extension.kumi` in the debug window.
+
+Position cursor after `fn(:` and type to trigger autocomplete:
+
+```kumi
+# Example 1: Basic arithmetic
+let :sum, fn(:add, x, y)
+                 ↑
+                 Type here and wait for suggestions
+```
+
+**Expected behavior:**
+- Autocomplete shows `add`, `sub`, `mul`, `div`, etc.
+- Each suggestion shows arity and function ID
+- Press Escape to close, or select with Enter
+
+### 5. Test Hover Information
+
+Hover over function names to see documentation:
+
+```kumi
+let :sum, fn(:sum, input.values.item.price)
+               ↑
+               Hover here to see type info
+```
+
+**Expected behavior:**
+- Popup shows:
+  - Function name: `agg.sum`
+  - Arity: `1`
+  - Type: `same as source_value`
+  - Parameters: `source_value`
+  - Kernels: `ruby: agg.sum:ruby:v1`
+
+### 6. Test Different Function Types
+
+Try these in the demo file:
+
+**Functions with identity:**
+```kumi
+fn(:sum, ...)    # Shows Inline: += $1
+fn(:count, ...)  # Shows Inline: += 1
+fn(:any, ...)    # Shows Inline: = $0 || $1
+```
+
+**Functions without identity:**
+```kumi
+fn(:min, ...)    # No Inline, shows note about first element
+fn(:max, ...)    # No Inline, shows note about first element
+```
+
+**Functions with multiple aliases:**
+```kumi
+fn(:add, ...)       # Has alias: add
+fn(:mul, ...)       # Has aliases: mul, multiply
+fn(:sum_if, ...)    # Complex aggregation
+```
+
+### 7. Watch for Recompilation
+
+In the debug window, TypeScript changes auto-compile:
+
+```bash
+npm run watch
+```
+
+Make a change to `src/extension.ts`, save, and reload the debug window (Cmd+R / Ctrl+R) to see changes.
+
+## Troubleshooting
+
+### Extension doesn't load
+
+Check the Debug Console for errors:
+- `Cmd+Shift+J` (Mac) or `Ctrl+Shift+J` (Linux/Windows)
+
+### No autocomplete suggestions
+
+1. Verify `docs/functions-reference.json` exists
+2. Check extension loaded: Look for "Kumi functions reference loaded" in Debug Console
+3. Make sure cursor is after `fn(:`
+
+### JSON loading errors
+
+If you see "Could not find functions-reference.json":
+```bash
+# Regenerate the JSON
+bin/kumi-doc-gen
+```
+
+### Type suggestions not showing
+
+1. Ensure you're in a `.kumi` or `.rb` file
+2. Check the file language is recognized (bottom-right of editor shows language)
+3. Try clicking on a function name and pressing `Cmd+K Cmd+I` to force hover
+
+## File Locations
+
+- Extension code: `vscode-extension/src/extension.ts`
+- Function data: `docs/functions-reference.json`
+- Demo file: `examples/demo-extension.kumi`
+- VSCode config: `vscode-extension/package.json`
+
+## Testing on Different File Types
+
+### Kumi Files (.kumi)
+```kumi
+fn(:add, x, y)    # Autocomplete and hover work
+```
+
+### Ruby Files (.rb)
+```ruby
+fn(:add, x, y)    # Also works if inside Kumi schema
+```
+
+Both file types activate the extension and provide completions/hover.