Initial commit of the Aperture VS Code extension, including core functionality for OpenAPI JSON/YAML IntelliSense, custom linting rules, and comprehensive test scenarios. Added configuration files, package dependencies, and example OpenAPI documents.

2025-12-06 04:19:09 +00:00 · 2025-09-25 01:38:44 +00:00
parent 91dbd9994e
commit 639477015d
31 changed files with 7770 additions and 14 deletions
--- a/README.md
+++ b/README.md
@@ -1,15 +1,186 @@
-# aperture
+# Aperture - OpenAPI IntelliSense Extension

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

-```bash
-bun install
+## 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
+}
 ```

-To run:
+### 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
-bun run index.ts
+npm install
+npm run build
 ```

-This project was created using `bun init` in bun v1.2.21. [Bun](https://bun.com) is a fast all-in-one JavaScript runtime.
+### 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