path: root/js/baba-yaga/dev/vscode/README.md

# 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.