kumi 0.0.26 → 0.0.28

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/frontends/text.rb

@@ -13,20 +13,48 @@ module Kumi
         raise ArgumentError, "provide either :path or :src" if (path.nil? && src.nil?) || (path && src)
 
         src ||= File.read(path)
-        file_label = path || "(string)"
+        file_label = path || "schema"
 
         begin
           require "kumi-parser"
-          ast = Kumi::Parser::TextParser.parse(src)
+          ast = Kumi::Parser::TextParser.parse(src, source_file: path || "schema")
           Core::Analyzer::Debug.info(:parse, kind: :text, file: file_label, ok: true) if Core::Analyzer::Debug.enabled?
           [ast, inputs]
         rescue LoadError
           raise "kumi-parser gem not available. Install: gem install kumi-parser"
         rescue StandardError => e
-          loc = (e.respond_to?(:location) && e.location) || {}
-          line, col = loc.values_at(:line, :column)
+          # Try to extract line/column from exception object first
+          line, col = extract_line_column(e)
           snippet = code_frame(src, line, col)
-          raise StandardError, "#{file_label}:#{line || '?'}:#{col || '?'}: #{e.message}\n#{snippet}"
+
+          # Strip file:line:col prefix from e.message if it exists (from parser)
+          # Also strip embedded "at FILE line=N column=M" to avoid duplication
+          error_message = e.message
+            .sub(/^\S+:\d+:\d+:\s+/, '')
+            .gsub(/\s+at\s+\S+\s+line=\d+\s+column=\d+/, '')
+            .strip
+          raise StandardError, "#{file_label}:#{line || '?'}:#{col || '?'}: #{error_message}\n#{snippet}"
+        end
+      end
+
+      def self.extract_line_column(exception)
+        # Try to access Location object from exception
+        if exception.respond_to?(:location) && exception.location
+          loc = exception.location
+          if loc.respond_to?(:line) && loc.respond_to?(:column)
+            return [loc.line, loc.column]
+          end
+        end
+
+        # Fall back to parsing error message if no Location object
+        extract_line_column_from_message(exception.message)
+      end
+
+      def self.extract_line_column_from_message(message)
+        if message =~ /line=(\d+)\s+column=(\d+)/
+          [::Regexp.last_match(1).to_i, ::Regexp.last_match(2).to_i]
+        else
+          [nil, nil]
         end
       end
 

data/lib/kumi/syntax/location.rb

@@ -1,5 +1,9 @@
 module Kumi
   module Syntax
-    Location = Struct.new(:file, :line, :column, keyword_init: true)
+    class Location < Struct.new(:file, :line, :column, keyword_init: true)
+      def to_s
+        "#{file} line=#{line} column=#{column}"
+      end
+    end
   end
 end

data/lib/kumi/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Kumi
-  VERSION = "0.0.26"
+  VERSION = "0.0.28"
 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.

data/vscode-extension/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "kumi-language-support",
+  "displayName": "Kumi Language Support",
+  "description": "Language support for Kumi DSL with autocomplete and hover information",
+  "version": "0.1.0",
+  "publisher": "kumi",
+  "engines": {
+    "vscode": "^1.80.0"
+  },
+  "categories": [
+    "Programming Languages",
+    "Snippets"
+  ],
+  "activationEvents": [
+    "onLanguage:ruby",
+    "onLanguage:kumi"
+  ],
+  "main": "./out/extension.js",
+  "contributes": {
+    "languages": [
+      {
+        "id": "kumi",
+        "aliases": [
+          "Kumi",
+          "kumi"
+        ],
+        "extensions": [
+          ".kumi"
+        ],
+        "configuration": "./language-configuration.json"
+      }
+    ],
+    "grammars": [
+      {
+        "language": "kumi",
+        "scopeName": "source.kumi",
+        "path": "./syntaxes/kumi.tmLanguage.json"
+      }
+    ]
+  },
+  "scripts": {
+    "vscode:prepublish": "npm run compile",
+    "compile": "tsc -p ./",
+    "watch": "tsc -watch -p ./"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/vscode": "^1.80.0",
+    "typescript": "^5.0.0"
+  }
+}