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":

{
  "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

npm install
npm run build

Packaging

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