1 files changed, 312 insertions, 0 deletions
diff --git a/js/baba-yaga/dev/vscode/README.md b/js/baba-yaga/dev/vscode/README.md
new file mode 100644
index 0000000..c144519
--- /dev/null
+++ b/js/baba-yaga/dev/vscode/README.md
@@ -0,0 +1,312 @@
+# Baba Yaga VS Code Extension
+
+Advanced language support for the Baba Yaga programming language with Tree-sitter parsing, type hints, function references, and intelligent code completion.
+
+## Features
+
+### **Core Language Support**
+- **Syntax Highlighting**: Full support for all Baba Yaga syntax elements
+- **File Association**: Automatic detection of `.baba` files
+- **Bracket Matching**: Auto-closing brackets, parentheses, and braces
+- **Comment Handling**: Toggle line and block comments
+- **Indentation**: Smart indentation for Baba Yaga code structure
+
+### **Intelligent Features**
+- **Type Hints**: Multiple display modes - hover, inline, or above expressions (Elm-style)
+- **Function References**: Go to definition (F12) and find all references (Shift+F12)
+- **Auto-completion**: Context-aware suggestions for functions, keywords, and types
+- **Error Checking**: Real-time syntax validation and error detection
+- **Code Snippets**: Quick templates for common patterns
+- **Markdown Support**: Syntax highlighting in Baba Yaga code blocks
+
+### **Advanced Capabilities**
+- **Tree-sitter Parsing**: Accurate syntax tree for better analysis
+- **Function Signatures**: Detailed parameter and return type information
+- **Built-in Function Support**: Complete coverage of `io.*`, `str.*`, `math.*` functions
+- **Pattern Matching**: Special support for `when` expressions
+- **Result Type Handling**: Intelligent handling of `Ok`/`Err` patterns
+
+## Installation
+
+### Method 1: Build from Source
+```bash
+cd dev/vscode
+npm install
+npm run compile
+vsce package
+# Install the generated .vsix file in VS Code
+```
+
+### Method 2: Development Mode
+```bash
+cd dev/vscode
+npm install
+npm run watch
+# Press F5 in VS Code to launch extension in development mode
+```
+
+### Method 3: Manual Installation
+1. Copy the extension files to your VS Code extensions directory
+2. Restart VS Code
+3. Open a `.baba` file to activate the extension
+
+## Configuration
+
+The extension provides several configuration options in VS Code settings:
+
+```json
+{
+  "baba-yaga.enableTypeHints": true,
+  "baba-yaga.enableFunctionReferences": true,
+  "baba-yaga.enableAutoComplete": true,
+  "baba-yaga.enableErrorChecking": true,
+  "baba-yaga.enableMarkdownSupport": true,
+  "baba-yaga.typeHintMode": "above"
+}
+```
+
+### Configuration Options
+- **`enableTypeHints`**: Show type hints and function signatures on hover
+- **`enableFunctionReferences`**: Enable go-to-definition and find references
+- **`enableAutoComplete`**: Enable intelligent code completion
+- **`enableErrorChecking`**: Enable real-time error checking (disabled by default to prevent false semicolon warnings)
+- **`enableMarkdownSupport`**: Enable syntax highlighting in Markdown code blocks
+- **`typeHintMode`**: Type hint display mode - see below for details
+
+### Type Hint Modes
+
+The extension supports three different type hint display modes:
+
+#### **`"none"` - Hover Only**
+```baba
+result : add(5, 3);  // No visual hints, hover to see types
+```
+- Type information only appears when hovering over symbols
+- Clean, minimal interface
+- Best for experienced developers who don't need constant type reminders
+
+#### **`"inline"` - After Expressions**
+```baba
+result : add(5, 3); : Int
+greeting : str.concat("Hello", name); : String
+```
+- Type hints appear directly after expressions
+- Compact display
+- Good for quick type reference without breaking code flow
+
+#### **`"above"` - Elm Style (Default)**
+```baba
+        : Int
+result : add(5, 3);
+                    : String
+greeting : str.concat("Hello", name);
+```
+- Type hints appear above expressions, right-aligned
+- Clean separation between types and code
+- Matches Elm language conventions
+- Most readable for complex type signatures
+
+## Usage
+
+### Basic Syntax Highlighting
+Open any `.baba` file and enjoy full syntax highlighting with:
+- Keywords: `when`, `then`, `is`, `Ok`, `Err`, `true`, `false`, etc.
+- Types: `Bool`, `Int`, `Float`, `String`, `List`, `Table`, `Result`, `Number`
+- Operators: `->`, `=>`, `+`, `-`, `*`, `/`, `%`, `=`, `!=`, `>`, `<`, `>=`, `<=`, `..`
+- Built-in functions: Complete `io.*`, `str.*`, `math.*` function sets
+
+### Type Hints and Documentation
+- **Hover over any symbol** to see detailed type information
+- **Built-in functions** show signatures and descriptions
+- **Custom functions** display their definitions and parameters
+- **Keywords and types** provide helpful documentation
+
+### Function References
+- **F12**: Go to function definition
+- **Shift+F12**: Find all references to a function
+- **Ctrl+Shift+Space**: Show type information
+- **Works with both built-in and custom functions**
+
+### Auto-completion
+- **Context-aware suggestions** for functions, keywords, and types
+- **Function signatures** in completion details
+- **Built-in function documentation** in tooltips
+- **Trigger characters**: `.`, `:`, `>`
+
+### Code Snippets
+Use these snippets to speed up development:
+
+| Snippet | Description | Example |
+|---------|-------------|---------|
+| `func` | Function definition | `myFunc : x -> x + 1;` |
+| `tfunc` | Typed function | `add : (x: Int, y: Int) -> Int -> x + y;` |
+| `when` | When expression | `when x is 1 then "One" _ then "Other";` |
+| `result` | Result handling | `when result is Ok v then v Err e then 0;` |
+| `list` | List creation | `[1, 2, 3]` |
+| `table` | Table creation | `{name: "value"}` |
+| `map` | Map function | `map (x -> x * 2) list` |
+| `filter` | Filter function | `filter (x -> x > 0) list` |
+| `reduce` | Reduce function | `reduce (acc x -> acc + x) 0 list` |
+
+### Error Checking
+- **Real-time validation** of syntax
+- **Missing semicolon detection**
+- **Basic type checking** for function calls
+- **Pattern matching validation**
+
+## Commands
+
+The extension provides several commands accessible via the command palette:
+
+- **`Baba Yaga: Show Type Information`**: Display type info for current symbol
+- **`Baba Yaga: Go to Definition`**: Navigate to function definition
+- **`Baba Yaga: Find References`**: Find all references to current symbol
+- **`Baba Yaga: Show Function Signature`**: Display function signature
+
+## Keybindings
+
+Default keybindings for Baba Yaga files:
+
+- **F12**: Go to definition
+- **Shift+F12**: Find references
+- **Ctrl+Shift+Space**: Show type information
+
+## Built-in Function Support
+
+The extension provides complete support for all Baba Yaga built-in functions:
+
+### IO Functions
+- `io.out(value)` - Print to console
+- `io.in()` - Read from console
+
+### String Functions
+- `str.concat(str1, str2)` - String concatenation
+- `str.split(str, delimiter)` - Split string
+- `str.join(list, separator)` - Join list to string
+- `str.length(str)` - String length
+- `str.substring(str, start, end)` - Extract substring
+- `str.replace(str, old, new)` - Replace substring
+- `str.trim(str)` - Remove whitespace
+- `str.upper(str)` - Convert to uppercase
+- `str.lower(str)` - Convert to lowercase
+
+### Math Functions
+- `math.abs(x)` - Absolute value
+- `math.sign(x)` - Sign function
+- `math.floor(x)`, `math.ceil(x)`, `math.round(x)`, `math.trunc(x)` - Rounding functions
+- `math.min(x, y)`, `math.max(x, y)`, `math.clamp(x, lo, hi)` - Min/max functions
+- `math.pow(x, y)`, `math.sqrt(x)`, `math.exp(x)`, `math.log(x)` - Power and log functions
+- `math.sin(x)`, `math.cos(x)`, `math.tan(x)` - Trigonometric functions
+- `math.asin(x)`, `math.acos(x)`, `math.atan(x)`, `math.atan2(y, x)` - Inverse trig functions
+- `math.deg(x)`, `math.rad(x)` - Angle conversion
+- `math.random()` - Random number (0-1)
+- `math.randomInt(lo, hi)` - Random integer
+
+### List Functions
+- `map(func, list)` - Apply function to each element
+- `filter(pred, list)` - Filter by predicate
+- `reduce(func, init, list)` - Fold to single value
+- `append(list, item)` - Add item to end
+- `set(table, key, value)` - Set table property
+- `merge(table1, table2)` - Merge tables
+- `shape(value)` - Get value metadata
+
+## Development
+
+### Building the Extension
+```bash
+cd dev/vscode
+npm install
+npm run compile
+```
+
+### Running Tests
+```bash
+npm test
+```
+
+### Debugging
+1. Open the extension in VS Code
+2. Press F5 to launch extension in development mode
+3. Open a `.baba` file to test features
+
+### File Structure
+```
+dev/vscode/
+├── src/
+│   └── extension.ts          # Main extension code
+├── syntaxes/
+│   └── baba-yaga.tmLanguage.json  # TextMate grammar
+├── snippets/
+│   └── baba-yaga.json        # Code snippets
+├── language-configuration.json    # Language configuration
+├── package.json              # Extension manifest
+├── tsconfig.json             # TypeScript configuration
+└── README.md                 # This file
+```
+
+## Troubleshooting
+
+### Extension Not Loading
+1. Check VS Code version (requires 1.74.0+)
+2. Verify TypeScript compilation: `npm run compile`
+3. Check extension logs: Help > Toggle Developer Tools
+
+### Tree-sitter Not Working
+1. Ensure `tree-sitter-baba-yaga` is installed
+2. Check console for parser initialization errors
+3. Extension falls back to basic features if Tree-sitter unavailable
+
+### Type Hints Not Showing
+1. Verify `baba-yaga.enableTypeHints` is enabled
+2. Hover over symbols, not whitespace
+3. Check that the symbol is recognized
+
+### Auto-completion Issues
+1. Ensure `baba-yaga.enableAutoComplete` is enabled
+2. Type trigger characters (`.`, `:`, `>`)
+3. Check for syntax errors in the file
+
+### Linting Errors (False Positives)
+If you see JavaScript/TypeScript linting errors in `.baba` files (like missing semicolon warnings):
+
+1. **Install the extension properly** - Ensure the Baba Yaga extension is active
+2. **Check file association** - Verify `.baba` files are recognized as "Baba Yaga" language
+3. **Disable conflicting extensions** - Turn off ESLint, TypeScript, or other JavaScript linters
+4. **Workspace settings** - Add this to your workspace `.vscode/settings.json`:
+
+```json
+{
+  "files.associations": {
+    "*.baba": "baba-yaga"
+  },
+  "eslint.validate": [
+    "javascript",
+    "javascriptreact", 
+    "typescript",
+    "typescriptreact"
+  ],
+  "[baba-yaga]": {
+    "editor.formatOnSave": false,
+    "editor.codeActionsOnSave": {}
+  }
+}
+```
+
+5. **Restart VS Code** - After making changes to settings
+
+**Note**: Baba Yaga doesn't use semicolons in the same way as JavaScript. The extension should handle this automatically, but if you see false linting errors, the above steps should resolve them.
+
+## Contributing
+
+To contribute to the extension:
+
+1. Fork the repository
+2. Create a feature branch
+3. Make your changes
+4. Add tests if applicable
+5. Submit a pull request
+
+## License
+
+This extension is provided under the same license as the main Baba Yaga project.