kumi 0.0.26 → 0.0.27

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/version.rb

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

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"
+  }
+}

data/vscode-extension/src/extension.ts

@@ -0,0 +1,295 @@
+import * as vscode from 'vscode';
+import * as fs from 'fs';
+import * as path from 'path';
+
+interface FunctionDef {
+  id: string;
+  arity: number;
+  params: Array<{ name: string }>;
+  dtype: any;
+  kernels: Record<string, string>;
+  aliases: string[];
+  kind?: string;
+}
+
+let functionsData: Record<string, FunctionDef> = {};
+
+export function activate(context: vscode.ExtensionContext) {
+  // Load functions reference JSON from kumi/docs/
+  const refPath = path.join(
+    context.extensionPath,
+    '..',
+    '..',
+    'docs',
+    'functions-reference.json'
+  );
+
+  try {
+    if (fs.existsSync(refPath)) {
+      const content = fs.readFileSync(refPath, 'utf-8');
+      functionsData = JSON.parse(content);
+      console.log('Kumi functions reference loaded');
+    } else {
+      vscode.window.showWarningMessage(
+        'Kumi: functions-reference.json not found. Run "bin/kumi-doc-gen" to generate it.'
+      );
+    }
+  } catch (e) {
+    console.error('Failed to load functions reference:', e);
+    vscode.window.showErrorMessage(
+      'Kumi: Error loading functions reference: ' + String(e)
+    );
+  }
+
+  // Register completion provider for both Ruby and Kumi files
+  const completionProvider = vscode.languages.registerCompletionItemProvider(
+    [
+      { language: 'ruby', scheme: 'file' },
+      { language: 'kumi', scheme: 'file' }
+    ],
+    new FunctionCompletionProvider(),
+    ':'  // trigger on ':'
+  );
+
+  // Register hover provider for both Ruby and Kumi files
+  const hoverProvider = vscode.languages.registerHoverProvider(
+    [
+      { language: 'ruby', scheme: 'file' },
+      { language: 'kumi', scheme: 'file' }
+    ],
+    new FunctionHoverProvider()
+  );
+
+  context.subscriptions.push(completionProvider, hoverProvider);
+}
+
+class FunctionCompletionProvider implements vscode.CompletionItemProvider {
+  provideCompletionItems(
+    document: vscode.TextDocument,
+    position: vscode.Position,
+    token: vscode.CancellationToken,
+    context: vscode.CompletionContext
+  ): vscode.CompletionItem[] {
+    // Check if we're in an fn(:...) context
+    const lineText = document.lineAt(position).text;
+    const beforeCursor = lineText.substring(0, position.character);
+
+    if (!beforeCursor.match(/fn\(\s*:\s*$/)) {
+      return [];
+    }
+
+    // For Ruby files, check if we're inside a schema block
+    if (document.languageId === 'ruby') {
+      if (!this.isInSchemaBlock(document, position)) {
+        return [];
+      }
+    }
+
+    const completions: vscode.CompletionItem[] = [];
+
+    for (const [alias, funcDef] of Object.entries(functionsData)) {
+      const item = new vscode.CompletionItem(
+        alias,
+        vscode.CompletionItemKind.Function
+      );
+
+      item.detail = `${funcDef.id} (arity: ${funcDef.arity})`;
+      item.documentation = new vscode.MarkdownString(
+        this.getDocumentation(funcDef)
+      );
+      item.sortText = alias;
+
+      completions.push(item);
+    }
+
+    return completions;
+  }
+
+  private getDocumentation(funcDef: FunctionDef): string {
+    const lines: string[] = [
+      `**${funcDef.id}**`,
+      '',
+      `**Arity:** ${funcDef.arity}`,
+    ];
+
+    if (funcDef.params && funcDef.params.length > 0) {
+      lines.push('**Parameters:**');
+      funcDef.params.forEach((p) => {
+        lines.push(`- \`${p.name}\``);
+      });
+    }
+
+    if (funcDef.dtype) {
+      lines.push(`**Type:** ${this.formatType(funcDef.dtype)}`);
+    }
+
+    if (funcDef.kernels && Object.keys(funcDef.kernels).length > 0) {
+      lines.push('**Kernels:**');
+      Object.entries(funcDef.kernels).forEach(([target, id]) => {
+        lines.push(`- ${target}: \`${id}\``);
+      });
+    }
+
+    return lines.join('\n');
+  }
+
+  private formatType(dtype: any): string {
+    if (!dtype) return 'unknown';
+
+    switch (dtype.rule) {
+      case 'same_as':
+        return `same as \`${dtype.param}\``;
+      case 'scalar':
+        return dtype.kind || 'scalar';
+      case 'promote':
+        return `promoted from ${dtype.params.map((p: string) => `\`${p}\``).join(', ')}`;
+      case 'element_of':
+        return `element of \`${dtype.param}\``;
+      default:
+        return dtype.rule;
+    }
+  }
+
+  private isInSchemaBlock(document: vscode.TextDocument, position: vscode.Position): boolean {
+    let braceCount = 0;
+    let schemaFound = false;
+
+    // Search backwards from current position to find schema block
+    for (let i = position.line; i >= 0; i--) {
+      const line = document.lineAt(i).text;
+
+      // Count braces from end of line backwards
+      if (i === position.line) {
+        // Only count braces before cursor
+        for (let j = position.character - 1; j >= 0; j--) {
+          if (line[j] === '}') braceCount++;
+          if (line[j] === '{') braceCount--;
+        }
+      } else {
+        // Count all braces in the line (right to left)
+        for (let j = line.length - 1; j >= 0; j--) {
+          if (line[j] === '}') braceCount++;
+          if (line[j] === '{') braceCount--;
+        }
+      }
+
+      // Look for 'schema do' or 'schema {'
+      if (line.match(/\bschema\s+(do|{)/)) {
+        schemaFound = braceCount <= 0;
+        break;
+      }
+    }
+
+    return schemaFound;
+  }
+}
+
+class FunctionHoverProvider implements vscode.HoverProvider {
+  provideHover(
+    document: vscode.TextDocument,
+    position: vscode.Position,
+    token: vscode.CancellationToken
+  ): vscode.ProviderResult<vscode.Hover> {
+    const range = document.getWordRangeAtPosition(position);
+    if (!range) return null;
+
+    const word = document.getText(range);
+
+    // Check if we're in fn(:word, ...)
+    const lineText = document.lineAt(position).text;
+    if (!lineText.match(/fn\s*\(\s*:/)) {
+      return null;
+    }
+
+    // For Ruby files, check if we're inside a schema block
+    if (document.languageId === 'ruby') {
+      if (!this.isInSchemaBlock(document, position)) {
+        return null;
+      }
+    }
+
+    const funcDef = functionsData[word];
+    if (!funcDef) {
+      return null;
+    }
+
+    const markdown = new vscode.MarkdownString();
+    markdown.appendMarkdown(`### \`${funcDef.id}\`\n\n`);
+
+    if (funcDef.aliases && funcDef.aliases.length > 0) {
+      markdown.appendMarkdown(
+        `**Aliases:** ${funcDef.aliases.map((a) => `\`${a}\``).join(', ')}\n\n`
+      );
+    }
+
+    markdown.appendMarkdown(`**Arity:** ${funcDef.arity}\n\n`);
+
+    if (funcDef.dtype) {
+      markdown.appendMarkdown(`**Type:** ${this.formatType(funcDef.dtype)}\n\n`);
+    }
+
+    if (funcDef.params && funcDef.params.length > 0) {
+      markdown.appendMarkdown('**Parameters:**\n\n');
+      funcDef.params.forEach((p) => {
+        markdown.appendMarkdown(`- \`${p.name}\`\n`);
+      });
+      markdown.appendMarkdown('\n');
+    }
+
+    return new vscode.Hover(markdown);
+  }
+
+  private formatType(dtype: any): string {
+    if (!dtype) return 'unknown';
+
+    switch (dtype.rule) {
+      case 'same_as':
+        return `same as \`${dtype.param}\``;
+      case 'scalar':
+        return dtype.kind || 'scalar';
+      case 'promote':
+        return `promoted from ${dtype.params
+          .map((p: string) => `\`${p}\``)
+          .join(', ')}`;
+      case 'element_of':
+        return `element of \`${dtype.param}\``;
+      default:
+        return dtype.rule;
+    }
+  }
+
+  private isInSchemaBlock(document: vscode.TextDocument, position: vscode.Position): boolean {
+    let braceCount = 0;
+    let schemaFound = false;
+
+    // Search backwards from current position to find schema block
+    for (let i = position.line; i >= 0; i--) {
+      const line = document.lineAt(i).text;
+
+      // Count braces from end of line backwards
+      if (i === position.line) {
+        // Only count braces before cursor
+        for (let j = position.character - 1; j >= 0; j--) {
+          if (line[j] === '}') braceCount++;
+          if (line[j] === '{') braceCount--;
+        }
+      } else {
+        // Count all braces in the line (right to left)
+        for (let j = line.length - 1; j >= 0; j--) {
+          if (line[j] === '}') braceCount++;
+          if (line[j] === '{') braceCount--;
+        }
+      }
+
+      // Look for 'schema do' or 'schema {'
+      if (line.match(/\bschema\s+(do|{)/)) {
+        schemaFound = braceCount <= 0;
+        break;
+      }
+    }
+
+    return schemaFound;
+  }
+}
+
+export function deactivate() {}

data/vscode-extension/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "compilerOptions": {
+    "module": "commonjs",
+    "target": "ES2020",
+    "lib": ["ES2020"],
+    "outDir": "./out",
+    "rootDir": "./src",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true
+  },
+  "exclude": ["node_modules", ".vscode-test"]
+}