aperture/README.md

# Aperture - OpenAPI IntelliSense Extension

A VS Code extension that provides **schema-driven IntelliSense** (hover, validation, completions) for OpenAPI **JSON and YAML** files with **custom linting rules**.

## Features

### ✅ **Schema-Driven IntelliSense**
- **Hover support** with rich descriptions from OpenAPI schemas
- **Auto-completion** for OpenAPI properties and values
- **Schema validation** with precise error reporting
- **Multi-version support** (OpenAPI 3.2, 3.1, 3.0, Swagger 2.0)

### ✅ **Custom Rule Engine**
- **Root validation**: Ensures required `info` section
- **Schema naming**: Enforces PascalCase for schema names
- **Operation ID validation**: Prevents duplicate operation IDs
- **Path parameter validation**: Ensures path parameters are declared
- **Precise diagnostics**: Errors highlight exact offending nodes

### ✅ **Multi-File Awareness**
- **$ref resolution**: Follows references across multiple files
- **Cross-document validation**: Validates entire reference graphs
- **File watching**: Re-validates when referenced files change
- **Circular reference detection**: Prevents infinite loops

### ✅ **Performance Optimized**
- **Debounced validation**: Configurable delay (default 300ms)
- **File size limits**: Configurable maximum file size (default 5MB)
- **Intelligent caching**: Reduces redundant processing
- **Memory management**: Automatic cache cleanup

### ✅ **Settings & Configuration**
- **Version preference**: Auto-detect or force specific OpenAPI version
- **Type profile checking**: Optional TypeScript-based validation
- **Custom rules**: Enable/disable specific validation rules
- **Performance tuning**: Adjust debounce delay and file size limits

## Installation

1. Download the `.vsix` file from the releases
2. In VS Code, go to Extensions → Install from VSIX
3. Select the `aperture-0.0.1.vsix` file
4. Reload VS Code

## Usage

### Basic Usage
1. Open any OpenAPI YAML or JSON file
2. The extension automatically detects the OpenAPI version
3. IntelliSense and validation work immediately
4. Check the Problems panel for validation errors

### Settings Configuration

Open VS Code settings and search for "Aperture":

```json
{
  "openapiLsp.versionPreference": "auto",        // "auto" | "3.2" | "3.1" | "3.0" | "2.0"
  "openapiLsp.enableTypeProfile": false,         // Enable TypeScript type checking
  "openapiLsp.enableCustomRules": true,          // Enable custom validation rules
  "openapiLsp.maxFileSize": 5,                  // Maximum file size in MB
  "openapiLsp.debounceDelay": 300               // Validation delay in milliseconds
}
```

### Supported File Types
- `.yaml` / `.yml` files
- `.json` files
- OpenAPI 3.2, 3.1, 3.0 specifications
- Swagger 2.0 specifications

## Architecture

### **Client-Server Architecture**
- **Client**: VS Code extension host using `vscode-languageclient`
- **Server**: LSP server with custom OpenAPI validation
- **Communication**: IPC-based language server protocol

### **Core Components**
- **Schema Loader**: Reads schemas from external types package
- **Ref Graph Builder**: Resolves `$ref` references across files
- **Custom Rule Engine**: Implements OpenAPI-specific validation rules
- **Range Mapper**: Maps JSON pointers to precise document ranges
- **Performance Manager**: Handles caching and debouncing

### **External Dependencies**
- **@your/openapi-types**: External package providing schemas and types
- **vscode-json-languageservice**: JSON schema validation
- **yaml-language-server**: YAML parsing and validation
- **jsonc-parser**: JSON with comments support

## Development

### Building the Extension
```bash
npm install
npm run build
```

### Packaging
```bash
npm run package
```

### Development Mode
1. Open the project in VS Code
2. Press F5 to launch Extension Development Host
3. Test with the example files in `/examples`

## Test Scenarios

The extension includes comprehensive test scenarios:

### Valid Examples
- `examples/openapi-3.2.yaml` - OpenAPI 3.2 specification
- `examples/openapi-3.1.yaml` - OpenAPI 3.1 specification  
- `examples/swagger-2.0.yaml` - Swagger 2.0 specification

### Invalid Examples (for testing validation)
- `examples/invalid-missing-info.yaml` - Missing info section
- `examples/invalid-schema-naming.yaml` - Incorrect schema naming
- `examples/invalid-duplicate-operation-id.yaml` - Duplicate operation IDs
- `examples/invalid-path-parameters.yaml` - Undeclared path parameters

## Custom Rules

### Root Info Rule
- **Rule**: `root-info`
- **Description**: Root object must contain info section
- **Severity**: Error

### Schema Naming Rule
- **Rule**: `schema-naming`
- **Description**: Schema names should be PascalCase
- **Severity**: Warning

### Operation ID Rule
- **Rule**: `operation-id`
- **Description**: Operations should have unique operationId
- **Severity**: Warning

### Path Parameter Rule
- **Rule**: `path-parameter`
- **Description**: Path parameters must be declared in the path
- **Severity**: Warning

## Performance Features

### Caching
- **Document cache**: Caches parsed documents with version tracking
- **Schema cache**: Caches loaded schemas for reuse
- **Range cache**: Caches pointer-to-range mappings

### Debouncing
- **Configurable delay**: Default 300ms, adjustable via settings
- **Per-document timeouts**: Each document has its own debounce timer
- **Automatic cleanup**: Timeouts are cleared when documents close

### File Size Management
- **Size limits**: Configurable maximum file size (default 5MB)
- **Graceful degradation**: Large files show warning instead of crashing
- **Memory protection**: Prevents excessive memory usage

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Changelog

### v0.0.1
- Initial release
- Schema-driven IntelliSense for OpenAPI files
- Custom rule engine with 4 validation rules
- Multi-file $ref resolution
- Performance optimizations and caching
- Comprehensive settings configuration
- Test scenarios and examples