{"id":42697434,"url":"https://github.com/LukasParke/aperture","last_synced_at":"2026-02-09T02:01:35.990Z","repository":{"id":332886135,"uuid":"1063572470","full_name":"LukasParke/aperture","owner":"LukasParke","description":"A VS Code plugin for linting OpenAPI files","archived":false,"fork":false,"pushed_at":"2026-01-01T21:19:10.000Z","size":230,"stargazers_count":0,"open_issues_count":4,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-20T23:54:59.251Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/LukasParke.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-24T20:16:09.000Z","updated_at":"2025-09-25T01:38:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/LukasParke/aperture","commit_stats":null,"previous_names":["lukasparke/aperture"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/LukasParke/aperture","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Faperture","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Faperture/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Faperture/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Faperture/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/LukasParke","download_url":"https://codeload.github.com/LukasParke/aperture/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/LukasParke%2Faperture/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29254302,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-09T01:52:29.835Z","status":"online","status_checked_at":"2026-02-09T02:00:09.501Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-29T14:00:32.941Z","updated_at":"2026-02-09T02:01:35.985Z","avatar_url":"https://github.com/LukasParke.png","language":"TypeScript","funding_links":[],"categories":["Uncategorized"],"sub_categories":["Uncategorized"],"readme":"# Aperture - OpenAPI IntelliSense Extension\n\nA VS Code extension that provides **schema-driven IntelliSense** (hover, validation, completions) for OpenAPI **JSON and YAML** files with **custom linting rules**.\n\n## Features\n\n### ✅ **Schema-Driven IntelliSense**\n- **Hover support** with rich descriptions from OpenAPI schemas\n- **Auto-completion** for OpenAPI properties and values\n- **Schema validation** with precise error reporting\n- **Multi-version support** (OpenAPI 3.2, 3.1, 3.0, Swagger 2.0)\n\n### ✅ **Custom Rule Engine**\n- **Root validation**: Ensures required `info` section\n- **Schema naming**: Enforces PascalCase for schema names\n- **Operation ID validation**: Prevents duplicate operation IDs\n- **Path parameter validation**: Ensures path parameters are declared\n- **Precise diagnostics**: Errors highlight exact offending nodes\n\n### ✅ **Multi-File Awareness**\n- **$ref resolution**: Follows references across multiple files\n- **Cross-document validation**: Validates entire reference graphs\n- **File watching**: Re-validates when referenced files change\n- **Circular reference detection**: Prevents infinite loops\n\n### ✅ **Performance Optimized**\n- **Debounced validation**: Configurable delay (default 300ms)\n- **File size limits**: Configurable maximum file size (default 5MB)\n- **Intelligent caching**: Reduces redundant processing\n- **Memory management**: Automatic cache cleanup\n\n### ✅ **Settings \u0026 Configuration**\n- **Version preference**: Auto-detect or force specific OpenAPI version\n- **Type profile checking**: Optional TypeScript-based validation\n- **Custom rules**: Enable/disable specific validation rules\n- **Performance tuning**: Adjust debounce delay and file size limits\n\n## Installation\n\n1. Download the `.vsix` file from the releases\n2. In VS Code, go to Extensions → Install from VSIX\n3. Select the `aperture-0.0.1.vsix` file\n4. Reload VS Code\n\n## Usage\n\n### Basic Usage\n1. Open any OpenAPI YAML or JSON file\n2. The extension automatically detects the OpenAPI version\n3. IntelliSense and validation work immediately\n4. Check the Problems panel for validation errors\n\n### Settings Configuration\n\nOpen VS Code settings and search for \"Aperture\":\n\n```json\n{\n  \"openapiLsp.versionPreference\": \"auto\",        // \"auto\" | \"3.2\" | \"3.1\" | \"3.0\" | \"2.0\"\n  \"openapiLsp.enableTypeProfile\": false,         // Enable TypeScript type checking\n  \"openapiLsp.enableCustomRules\": true,          // Enable custom validation rules\n  \"openapiLsp.maxFileSize\": 5,                  // Maximum file size in MB\n  \"openapiLsp.debounceDelay\": 300               // Validation delay in milliseconds\n}\n```\n\n### Supported File Types\n- `.yaml` / `.yml` files\n- `.json` files\n- OpenAPI 3.2, 3.1, 3.0 specifications\n- Swagger 2.0 specifications\n\n## Architecture\n\n### **Client-Server Architecture**\n- **Client**: VS Code extension host using `vscode-languageclient`\n- **Server**: LSP server with custom OpenAPI validation\n- **Communication**: IPC-based language server protocol\n\n### **Core Components**\n- **Schema Loader**: Reads schemas from external types package\n- **Ref Graph Builder**: Resolves `$ref` references across files\n- **Custom Rule Engine**: Implements OpenAPI-specific validation rules\n- **Range Mapper**: Maps JSON pointers to precise document ranges\n- **Performance Manager**: Handles caching and debouncing\n\n### **External Dependencies**\n- **@your/openapi-types**: External package providing schemas and types\n- **vscode-json-languageservice**: JSON schema validation\n- **yaml-language-server**: YAML parsing and validation\n- **jsonc-parser**: JSON with comments support\n\n## Development\n\n### Building the Extension\n```bash\nnpm install\nnpm run build\n```\n\n### Packaging\n```bash\nnpm run package\n```\n\n### Development Mode\n1. Open the project in VS Code\n2. Press F5 to launch Extension Development Host\n3. Test with the example files in `/examples`\n\n## Test Scenarios\n\nThe extension includes comprehensive test scenarios:\n\n### Valid Examples\n- `examples/openapi-3.2.yaml` - OpenAPI 3.2 specification\n- `examples/openapi-3.1.yaml` - OpenAPI 3.1 specification  \n- `examples/swagger-2.0.yaml` - Swagger 2.0 specification\n\n### Invalid Examples (for testing validation)\n- `examples/invalid-missing-info.yaml` - Missing info section\n- `examples/invalid-schema-naming.yaml` - Incorrect schema naming\n- `examples/invalid-duplicate-operation-id.yaml` - Duplicate operation IDs\n- `examples/invalid-path-parameters.yaml` - Undeclared path parameters\n\n## Custom Rules\n\n### Root Info Rule\n- **Rule**: `root-info`\n- **Description**: Root object must contain info section\n- **Severity**: Error\n\n### Schema Naming Rule\n- **Rule**: `schema-naming`\n- **Description**: Schema names should be PascalCase\n- **Severity**: Warning\n\n### Operation ID Rule\n- **Rule**: `operation-id`\n- **Description**: Operations should have unique operationId\n- **Severity**: Warning\n\n### Path Parameter Rule\n- **Rule**: `path-parameter`\n- **Description**: Path parameters must be declared in the path\n- **Severity**: Warning\n\n## Performance Features\n\n### Caching\n- **Document cache**: Caches parsed documents with version tracking\n- **Schema cache**: Caches loaded schemas for reuse\n- **Range cache**: Caches pointer-to-range mappings\n\n### Debouncing\n- **Configurable delay**: Default 300ms, adjustable via settings\n- **Per-document timeouts**: Each document has its own debounce timer\n- **Automatic cleanup**: Timeouts are cleared when documents close\n\n### File Size Management\n- **Size limits**: Configurable maximum file size (default 5MB)\n- **Graceful degradation**: Large files show warning instead of crashing\n- **Memory protection**: Prevents excessive memory usage\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests for new functionality\n5. Submit a pull request\n\n## License\n\nMIT License - see LICENSE file for details\n\n## Changelog\n\n### v0.0.1\n- Initial release\n- Schema-driven IntelliSense for OpenAPI files\n- Custom rule engine with 4 validation rules\n- Multi-file $ref resolution\n- Performance optimizations and caching\n- Comprehensive settings configuration\n- Test scenarios and examples","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLukasParke%2Faperture","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FLukasParke%2Faperture","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FLukasParke%2Faperture/lists"}