# RSpade VS Code Extension

This directory contains the Visual Studio Code extension for the RSpade framework, providing enhanced development experience with automatic code folding, namespace management, and integrated formatting.

## Purpose

The RSpade extension enhances VS Code for RSpade framework development by:
- Automatically folding LLMDIRECTIVE blocks to reduce visual clutter
- Providing visual indicators and warnings for auto-generated RSX:USE sections
- Updating PHP namespaces automatically when files are moved or renamed
- Integrating PHP formatting directly into VS Code (replacing RunOnSave)
- Auto-renaming files to match RSX naming conventions (optional, configurable)

## Architecture

The extension is built with TypeScript and follows VS Code extension best practices:

### Core Components

1. **extension.ts** - Main entry point that activates providers and registers commands
2. **folding_provider.ts** - Implements automatic folding for LLMDIRECTIVE blocks
3. **decoration_provider.ts** - Adds visual indicators to RSX:USE sections
4. **file_watcher.ts** - Monitors file moves/renames and triggers namespace updates
5. **formatting_provider.ts** - Integrates with the main formatter for PHP formatting
6. **auto_rename_provider.ts** - Automatically renames files to match RSX naming conventions
7. **config.ts** - Centralized configuration management

### Key Features

1. **Code Folding**
   - Automatically identifies and folds LLMDIRECTIVE blocks
   - Uses VS Code's FoldingRangeProvider API
   - Can be toggled via command or settings

2. **Protected Region Indicators**
   - Highlights RSX:USE sections with yellow background
   - Shows warning icons and hover messages
   - Alerts users when editing auto-generated code

3. **Smart File Handling**
   - Detects file moves and renames
   - Automatically updates PHP namespaces for RSX files
   - Works with drag-and-drop in VS Code explorer

4. **Integrated Formatting**
   - Docker-first formatting via `/_idehelper/codeformat` endpoint
   - Falls back to local PHP execution if Docker unavailable
   - Uses the main formatter at `./bin/rsx-format`
   - Graceful degradation - warns but allows save if formatting fails
   - Works even when Laravel is broken (bypasses framework)

5. **Auto-Rename Files** (Optional - disabled by default)
   - Automatically renames files in `./rsx` to match RSX naming conventions on save
   - Supports PHP classes, JavaScript classes, .blade.php files with @rsx_id, and .jqhtml components
   - Only renames if the correct filename doesn't already exist
   - Respects short-name conventions (directory-based prefixes)
   - Files containing `@FILENAME-CONVENTION-EXCEPTION` are skipped
   - Enable via `config/rsx.php`: `'development' => ['auto_rename_files' => true]`

   **Naming Conventions Applied:**
   - **PHP classes in rsx/**: Lowercase, optional short name
   - **JS classes in rsx/**: Lowercase, snake_case for Component subclasses
   - **.blade.php with @rsx_id**: Lowercase, optional short name
   - **.jqhtml components**: snake_case (lowercase with underscores)

   **Short Names:** If class is `Foo_Bar_Baz_Bom` in directory `./rsx/app/foo/bar/`, filename can be `baz_bom.php` instead of `foo_bar_baz_bom.php`

## Development

### Setup
```bash
npm install
npm run compile
```

### Testing
Press F5 in VS Code to launch a development instance with the extension loaded.

### Building
```bash
npm install -g vsce
vsce package
```

## Configuration

Users can configure the extension through VS Code settings:
- `rspade.enableCodeFolding` - Toggle LLMDIRECTIVE folding
- `rspade.enableReadOnlyRegions` - Toggle RSX:USE visual indicators
- `rspade.enableFormatOnMove` - Toggle automatic namespace updates

## Integration

The extension integrates with the existing RSpade formatting infrastructure:
- Format-on-save handled by RunOnSave extension configured in `.vscode/settings.json`
- Uses the main formatter at `./bin/rsx-format`
- PHP formatting via `./bin/formatters/php-formatter`
- JSON formatting via `./bin/formatters/json-formatter`
- Maintains compatibility with existing VS Code tasks and settings