@codacy/tools-spectral-1

Table of Contents

• Overview
• Updating patterns
• Updating the Spectral version
• Development
• Notes for maintainers

Overview

OpenAPI and AsyncAPI linter using Spectral. Uses the Library execution strategy — calls the @stoplight/spectral-core API directly rather than spawning a subprocess.

| Property | Value | |----------|-------| | Tool ID | spectral | | Codacy UUID | fb60ff64-3d91-11ec-9bbc-0242ac130002 | | Strategy | Library | | Languages | JSON, YAML | | Dependency | @stoplight/spectral-core (v1.x) | | File patterns | **/*.yaml, **/*.yml, **/*.json |

Updating patterns

# Re-fetch pattern metadata from the Codacy API
pnpm prefetch

# Commit the result
git add src/patterns.json

Pattern IDs follow the format spectral_operation-operationId, spectral_info-contact, etc.

Updating the Spectral version

1. Update @stoplight/spectral-core and related packages in package.json
2. Run pnpm install
3. Run pnpm prefetch to check for new/removed rules
4. Run pnpm test to verify compatibility
5. If the major version changes, create a new adapter package (spectral-2/)

Development

pnpm build    # Build with tsup
pnpm test     # Run tests

Notes for maintainers

• Spectral diagnostics use 0-based line and column numbers. The adapter adds 1 to both to produce 1-based Codacy Issues.
• The adapter processes files one at a time, creating a new Spectral instance per file. This avoids state leakage between files.
• Not all YAML/JSON files are API specs. Non-spec files may produce parse errors from Spectral — the adapter captures these as warnings and continues.
• The default ruleset is spectral:oas (OpenAPI). AsyncAPI support can be added by detecting the asyncapi key in the document.
• checkAvailability dynamically imports @stoplight/spectral-core and creates an instance.
• install is a no-op — the npm dependency handles installation.