@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.

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 devDependencies of package.json, and preferredVersion in src/metadata.ts (it tracks @stoplight/spectral-core)
2. Run pnpm install
3. Run pnpm generate-payloads spectral-1 from the repo root to re-pin payload/package.json and regenerate its lockfile
4. Run pnpm prefetch to check for new/removed rules
5. Run pnpm test to verify compatibility
6. 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 adapter detects AsyncAPI specs by checking for a top-level asyncapi key in the file content, and uses the asyncapi ruleset from @stoplight/spectral-rulesets. All other files use the OAS (OpenAPI) ruleset.
• checkAvailability dynamically imports @stoplight/spectral-core and creates an instance.
• The tool is an npm payload, not a dependency: it is resolved at run time (a Codacy-managed install under ~/.codacy/tools/<id>/, a CODACY_TOOL_ROOT_<ID> root, or this package's own node_modules in the monorepo) and install runs npm ci against the committed payload/package-lock.json. See src/payload.ts.