@opsydyn/elysia-spectral 0.2.4

package/CHANGELOG.md

@@ -0,0 +1,47 @@
+# Changelog
+
+## [0.2.4](https://github.com/opsydyn/elysia-spectral/compare/v0.2.3...v0.2.4) (2026-04-14)
+
+
+### Bug Fixes
+
+* clarify bun and npm install commands in tutorial ([535ca1e](https://github.com/opsydyn/elysia-spectral/commit/535ca1e77568801dbdc85a7b4e733ed9eb4e0486))
+
+## [0.2.3](https://github.com/opsydyn/elysia-spectral/compare/v0.2.2...v0.2.3) (2026-04-14)
+
+
+### Bug Fixes
+
+* :wrench: remove stale biome suppressions and unused import ([e81e392](https://github.com/opsydyn/elysia-spectral/commit/e81e3925c66687678be5c9834bdb76880399753c))
+
+## [0.2.2](https://github.com/opsydyn/elysia-spectral/compare/v0.2.1...v0.2.2) (2026-04-14)
+
+
+### Bug Fixes
+
+* :wrench: migrate biome config to 2.4.11 and pin version ([327d089](https://github.com/opsydyn/elysia-spectral/commit/327d08969af3e394ef6ea992cdba9e5189129f39))
+
+## [0.2.1](https://github.com/opsydyn/elysia-spectral/compare/v0.2.0...v0.2.1) (2026-04-14)
+
+
+### Bug Fixes
+
+* :wrench: resolve all biome lint and format errors ([cb3ff8d](https://github.com/opsydyn/elysia-spectral/commit/cb3ff8dd5464b5a7036861c5550390dbf79f2dd5))
+
+## [0.2.0](https://github.com/opsydyn/elysia-spectral/compare/v0.1.0...v0.2.0) (2026-04-14)
+
+
+### Features
+
+* :memo: update readme ([721a832](https://github.com/opsydyn/elysia-spectral/commit/721a832aa5a2596cb7fd26b02a575be495cc316a))
+* :sparkles: cli enhance ([aa97001](https://github.com/opsydyn/elysia-spectral/commit/aa970015e18af9b7a5aff8d5242f2fad787ef17d))
+* :sparkles: enhance logging ([bfbc5bb](https://github.com/opsydyn/elysia-spectral/commit/bfbc5bbfd828b07d26c6b69fcf27676b58754b31))
+* :sparkles: healthcheck pkg opt in ([41df9dd](https://github.com/opsydyn/elysia-spectral/commit/41df9ddd1ba8f1b2dbcd7b90bec6fdeef3ed3cd8))
+* :sparkles: logging refactor ([4a0f98c](https://github.com/opsydyn/elysia-spectral/commit/4a0f98c09f1f3e6a71b5ba20ad11fdb35f5c42e4))
+* :sparkles: plugin bootstrap ([a1bcdd4](https://github.com/opsydyn/elysia-spectral/commit/a1bcdd48f5a105735d97bbfacec8159ff58816a3))
+* :sparkles: rename to @opsydyn/elysia-spectral and prep for npm publish ([87ffdda](https://github.com/opsydyn/elysia-spectral/commit/87ffdda2d1c844753ee50d8e3c1800d0cafdda99))
+* :sparkles: rule set update ([efb85c6](https://github.com/opsydyn/elysia-spectral/commit/efb85c62edabb17a9852b43009d9fbc044345a9c))
+
+## Changelog
+
+All notable changes to this package will be documented in this file.

package/README.md

@@ -0,0 +1,637 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/opsydyn/elysia-spectral/main/api-lint-repo-logo.png" alt="@opsydyn/elysia-spectral" width="480" />
+</p>
+
+# @opsydyn/elysia-spectral
+
+Thin Elysia plugin that lints the OpenAPI document generated by `@elysiajs/openapi` with Spectral.
+
+## What Is Spectral?
+
+Spectral is an open-source linter and style guide engine for API descriptions. It was built with OpenAPI, AsyncAPI, and JSON Schema in mind, and is commonly used to enforce API style guides, catch weak or inconsistent contract definitions, and improve the usefulness of generated API descriptions.
+
+For API teams, that matters because a spec can be technically valid while still being poor for:
+
+- generated documentation
+- client generation
+- contract testing
+- consistency across teams and services
+- long-term API governance
+
+`@opsydyn/elysia-spectral` uses Spectral to turn the OpenAPI document generated by `@elysiajs/openapi` into an automated quality gate for Elysia apps.
+
+Official Spectral references:
+
+- Stoplight overview: <https://stoplight.io/open-source/spectral>
+- GitHub repository: <https://github.com/stoplightio/spectral>
+
+This README is organized using the Diataxis documentation model:
+
+- Tutorial: learn by building a working setup
+- How-to guides: solve specific tasks
+- Reference: look up exact behavior and API shape
+- Explanation: understand the design choices
+
+Current package scope:
+
+- startup linting
+- threshold-based failure
+- repo-level and local rulesets
+- YAML, JS, TS, and in-memory rulesets
+- resolver pipeline for advanced ruleset loading
+- console output
+- JSON report output
+- JUnit report output
+- SARIF report output
+- OpenAPI snapshot output
+- reusable runtime for CI and tests
+- opt-in healthcheck endpoint for cached and fresh runs
+
+## Tutorial
+
+### Add OpenAPI linting to an Elysia app
+
+This tutorial takes a minimal Elysia app and adds startup OpenAPI linting with a repo-level ruleset and JSON artifacts.
+
+1. Install the dependencies.
+
+```bash
+# bun
+bun add elysia @elysiajs/openapi @opsydyn/elysia-spectral
+
+# npm
+npm install elysia @elysiajs/openapi @opsydyn/elysia-spectral
+```
+
+2. Create a repo-level `spectral.yaml`.
+
+```yaml
+extends:
+  - spectral:oas
+
+rules:
+  operation-description:
+    severity: error
+
+  operation-tags:
+    severity: warn
+
+  elysia-operation-summary:
+    severity: error
+```
+
+3. Add `@elysiajs/openapi` and `spectralPlugin` to your app.
+
+```ts
+import { Elysia, t } from 'elysia'
+import { openapi } from '@elysiajs/openapi'
+import { spectralPlugin } from '@opsydyn/elysia-spectral'
+
+new Elysia()
+  .use(
+    openapi({
+      documentation: {
+        info: {
+          title: 'Example API',
+          version: '1.0.0'
+        },
+        tags: [{ name: 'Users', description: 'User operations' }]
+      }
+    })
+  )
+  .use(
+    spectralPlugin({
+      failOn: 'error',
+      startup: {
+        mode: 'enforce'
+      },
+      output: {
+        console: true,
+        jsonReportPath: './artifacts/openapi-lint.json',
+        specSnapshotPath: true
+      }
+    })
+  )
+  .get('/users', () => [{ id: '1', name: 'Ada Lovelace' }], {
+    response: {
+      200: t.Array(
+        t.Object({
+          id: t.String(),
+          name: t.String()
+        })
+      )
+    },
+    detail: {
+      summary: 'List users',
+      description: 'Return all users.',
+      operationId: 'listUsers',
+      tags: ['Users']
+    }
+  })
+  .listen(3000)
+```
+
+4. Start the app.
+
+```bash
+bun run src/index.ts
+```
+
+5. Confirm the outcome.
+
+- the app serves OpenAPI JSON at `/openapi/json`
+- the plugin lints that generated document during startup
+- a clean run prints Signale-style success and hype lines in the terminal
+- `./artifacts/openapi-lint.json` contains the lint result
+- `./<package-name>.open-api.json` contains the generated OpenAPI snapshot
+
+If startup fails, the terminal output includes:
+
+- the failing rule code
+- the affected operation
+- a fix hint when one is known
+- a spec reference in `open-api.json#/json/pointer` form
+
+## How-to Guides
+
+### Use a repo-level ruleset
+
+Use a ruleset file at the consuming app root:
+
+```ts
+spectralPlugin({
+  ruleset: './spectral.yaml'
+})
+```
+
+Or let the plugin autodiscover a standard ruleset filename:
+
+```ts
+spectralPlugin()
+```
+
+Autodiscovery looks for these files in order:
+
+- `spectral.yaml`
+- `spectral.yml`
+- `spectral.ts`
+- `spectral.mts`
+- `spectral.cts`
+- `spectral.js`
+- `spectral.mjs`
+- `spectral.cjs`
+- `spectral.config.yaml`
+- `spectral.config.yml`
+- `spectral.config.ts`
+- `spectral.config.mts`
+- `spectral.config.cts`
+- `spectral.config.js`
+- `spectral.config.mjs`
+- `spectral.config.cjs`
+
+Autodiscovered repo-level rulesets are merged with the package default ruleset.
+
+### Use a JS or TS ruleset module
+
+Module rulesets can export the ruleset as the default export or as a named `ruleset` export.
+
+```ts
+export default {
+  extends: ['spectral:oas'],
+  rules: {
+    operation-description: {
+      severity: 'error'
+    }
+  }
+}
+```
+
+Module rulesets can also export custom Spectral functions:
+
+```ts
+const startsWithPrefix = (input, options) => {
+  if (typeof input !== 'string' || !input.startsWith(options.prefix)) {
+    return [{ message: `OperationId must start with "${options.prefix}".` }]
+  }
+}
+
+export const functions = {
+  startsWithPrefix
+}
+
+export default {
+  extends: ['spectral:oas'],
+  rules: {
+    'operation-id-prefix': {
+      given: '$.paths[*][get,put,post,delete,options,head,patch,trace]',
+      then: {
+        field: 'operationId',
+        function: 'startsWithPrefix',
+        functionOptions: { prefix: 'fetch' }
+      }
+    }
+  }
+}
+```
+
+### Keep the app running when lint fails at startup
+
+Use `startup.mode: 'report'` when you want the full package-owned terminal report but do not want lint findings to block boot.
+
+```ts
+spectralPlugin({
+  failOn: 'warn',
+  startup: {
+    mode: 'report'
+  }
+})
+```
+
+This is useful for local development and intentionally broken fixtures.
+
+### Disable startup lint entirely
+
+Use `startup.mode: 'off'` when you only want manual or healthcheck-triggered runs.
+
+```ts
+spectralPlugin({
+  startup: {
+    mode: 'off'
+  }
+})
+```
+
+`enabled: false` is still supported as a backwards-compatible way to disable startup lint.
+
+### Add a lint healthcheck endpoint
+
+The healthcheck route is opt-in.
+
+```ts
+spectralPlugin({
+  healthcheck: {
+    path: '/health/openapi-lint'
+  }
+})
+```
+
+Behavior:
+
+- `GET /health/openapi-lint` returns the cached startup result when available
+- `GET /health/openapi-lint?fresh=1` forces a fresh lint run
+- the route returns `200` when findings stay below `failOn`
+- the route returns `503` when findings meet or exceed `failOn`
+- the route is hidden from generated OpenAPI docs
+
+### Persist JSON reports and OpenAPI snapshots
+
+```ts
+spectralPlugin({
+  output: {
+    jsonReportPath: './artifacts/openapi-lint.json',
+    specSnapshotPath: true
+  }
+})
+```
+
+Snapshot behavior:
+
+- `specSnapshotPath: true` derives `./<package-name>.open-api.json` from the consuming app's `package.json` name
+- `specSnapshotPath: './contracts/openapi.json'` writes to the exact relative path you provide
+- scoped package names are sanitized, so `@acme/orders-api` becomes `./acme-orders-api.open-api.json`
+
+All report and snapshot paths resolve from the consuming app's `process.cwd()`.
+
+### Emit SARIF for code scanning tools
+
+```ts
+spectralPlugin({
+  output: {
+    sarifReportPath: './artifacts/openapi-lint.sarif'
+  }
+})
+```
+
+SARIF is useful when you want lint results in a standard machine-readable format for platforms such as GitHub code scanning and other static analysis tooling.
+
+### Emit JUnit XML for CI test reporting
+
+```ts
+spectralPlugin({
+  output: {
+    junitReportPath: './artifacts/openapi-lint.junit.xml'
+  }
+})
+```
+
+JUnit is useful when your CI system expects test-style XML output and you want lint findings to appear in standard test reports.
+
+### Add a custom sink
+
+The existing `output` convenience flags are built on top of sink abstractions. You can add your own sink for custom reporting or automation:
+
+```ts
+spectralPlugin({
+  output: {
+    sinks: [
+      {
+        name: 'capture',
+        async write(result, context) {
+          console.log(result.summary.total)
+          console.log(context.spec.openapi)
+        }
+      }
+    ]
+  }
+})
+```
+
+Custom sinks run after linting and can read:
+
+- the normalized lint result
+- the resolved OpenAPI document
+- artifact paths already produced by earlier built-in sinks
+
+### Use a custom ruleset resolver pipeline
+
+If you use the runtime programmatically, you can provide your own resolver pipeline to `loadRuleset` or `loadResolvedRuleset`.
+
+```ts
+import { loadRuleset } from '@opsydyn/elysia-spectral/core'
+
+const ruleset = await loadRuleset('virtual://team-ruleset', {
+  resolvers: [
+    async (input) =>
+      input === 'virtual://team-ruleset'
+        ? {
+            ruleset: {
+              extends: ['spectral:oas'],
+              rules: {
+                'team-summary': {
+                  given: '$.paths[*][get,put,post,delete,options,head,patch,trace]',
+                  then: {
+                    field: 'summary',
+                    function: 'truthy'
+                  }
+                }
+              }
+            }
+          }
+        : undefined
+  ]
+})
+```
+
+This is an advanced extension point. Most apps should continue using repo-level `spectral.*` files.
+
+### Make artifact write failures fatal in CI
+
+Artifact writes are non-fatal by default. In CI, set them to fatal:
+
+```ts
+spectralPlugin({
+  output: {
+    jsonReportPath: './artifacts/openapi-lint.json',
+    specSnapshotPath: true,
+    artifactWriteFailures: 'error'
+  }
+})
+```
+
+Use `'warn'` for local development and `'error'` when artifact generation is required.
+
+### Run the runtime in CI or tests
+
+```ts
+import { Elysia } from 'elysia'
+import { openapi } from '@elysiajs/openapi'
+import { createOpenApiLintRuntime } from '@opsydyn/elysia-spectral'
+
+const app = new Elysia().use(openapi())
+
+const runtime = createOpenApiLintRuntime({
+  ruleset: './spectral.yaml',
+  failOn: 'error',
+  output: {
+    console: true,
+    jsonReportPath: './artifacts/openapi-lint.json',
+    specSnapshotPath: true,
+    artifactWriteFailures: 'error'
+  }
+})
+
+await runtime.run(app)
+```
+
+### Work on this repository locally
+
+From the monorepo root:
+
+```bash
+bun install
+bun run dev
+```
+
+That starts `apps/dev-app` with:
+
+- OpenAPI UI at `/openapi`
+- raw OpenAPI JSON at `/openapi/json`
+- opt-in lint healthcheck at `/health/openapi-lint`
+- JSON lint report output at `./artifacts/openapi-lint.json`
+- OpenAPI snapshot output at `./elysia-spectral-dev-app.open-api.json`
+
+To run an intentionally failing fixture:
+
+```bash
+bun run dev:unhappy
+```
+
+That example uses `startup.mode: 'report'`, so the app still boots while the package prints the full lint report during startup.
+
+## Reference
+
+### Package API
+
+```ts
+type SeverityThreshold = 'error' | 'warn' | 'info' | 'hint' | 'never'
+
+type StartupLintMode = 'enforce' | 'report' | 'off'
+
+type ArtifactWriteFailureMode = 'warn' | 'error'
+
+type OpenApiLintArtifacts = {
+  jsonReportPath?: string
+  junitReportPath?: string
+  sarifReportPath?: string
+  specSnapshotPath?: string
+}
+
+type OpenApiLintSink = {
+  name: string
+  write: (
+    result: LintRunResult,
+    context: {
+      spec: Record<string, unknown>
+      logger: SpectralLogger
+    }
+  ) => void | Partial<OpenApiLintArtifacts> | Promise<void | Partial<OpenApiLintArtifacts>>
+}
+
+type RulesetResolver = (
+  input: string | RulesetDefinition | Record<string, unknown> | undefined,
+  context: {
+    baseDir: string
+    defaultRuleset: RulesetDefinition
+    mergeAutodiscoveredWithDefault: boolean
+  }
+) => Promise<LoadedRuleset | undefined>
+
+type LoadResolvedRulesetOptions = {
+  baseDir?: string
+  resolvers?: RulesetResolver[]
+  mergeAutodiscoveredWithDefault?: boolean
+}
+
+type SpectralPluginOptions = {
+  ruleset?: string | RulesetDefinition | Record<string, unknown>
+  failOn?: SeverityThreshold
+  healthcheck?: false | { path?: string }
+  output?: {
+    console?: boolean
+    jsonReportPath?: string
+    junitReportPath?: string
+    sarifReportPath?: string
+    specSnapshotPath?: string | true
+    pretty?: boolean
+    artifactWriteFailures?: ArtifactWriteFailureMode
+    sinks?: OpenApiLintSink[]
+  }
+  source?: {
+    specPath?: string
+    baseUrl?: string
+  }
+  enabled?: boolean | ((env: Record<string, string | undefined>) => boolean)
+  startup?: {
+    mode?: StartupLintMode
+  }
+  logger?: {
+    info: (message: string) => void
+    warn: (message: string) => void
+    error: (message: string) => void
+  }
+}
+```
+
+### Runtime state
+
+The runtime object exposes:
+
+- `status`: `idle | running | passed | failed`
+- `startedAt`: ISO timestamp for the most recent run start
+- `completedAt`: ISO timestamp for the most recent run completion
+- `durationMs`: duration of the most recent run
+- `latest`: last completed lint result
+- `lastSuccess`: last successful lint result
+- `lastFailure`: last thrown runtime error summary
+- `running`: boolean convenience flag
+
+When used as a plugin, the runtime is also available on `app.store.openApiLint`.
+
+### Healthcheck response shape
+
+Example successful response:
+
+```json
+{
+  "ok": true,
+  "cached": true,
+  "threshold": "error",
+  "result": {
+    "ok": true,
+    "generatedAt": "2026-04-06T12:00:00.000Z",
+    "summary": {
+      "error": 0,
+      "warn": 0,
+      "info": 0,
+      "hint": 0,
+      "total": 0
+    },
+    "findings": []
+  }
+}
+```
+
+### Ruleset resolution
+
+- ruleset paths resolve from the consuming app's `process.cwd()`
+- in a typical service repo, `./spectral.yaml` means the repo root
+- in this monorepo, `apps/dev-app` resolves `./spectral.yaml` from `apps/dev-app`
+- supported local ruleset files are `.yaml`, `.yml`, `.js`, `.mjs`, `.cjs`, `.ts`, `.mts`, and `.cts`
+- module rulesets may export the ruleset as the default export or a named `ruleset` export
+- module rulesets may export `functions` to register custom Spectral functions
+- in-memory ruleset objects are supported
+- `loadRuleset` and `loadResolvedRuleset` also accept an options object with a custom `resolvers` pipeline
+- autodiscovered rulesets merge with the package default ruleset by default and can opt out with `mergeAutodiscoveredWithDefault: false`
+
+### Error behavior
+
+- startup mode `enforce` throws on threshold failures
+- startup mode `report` prints the same lint report but allows boot to continue on threshold failures
+- startup mode `off` skips startup lint
+- bad `source.specPath` or invalid spec JSON produces an actionable provider error
+- artifact writes warn by default and can be made fatal with `output.artifactWriteFailures: 'error'`
+
+### Output model
+
+The current output model has two layers:
+
+- convenience options such as `jsonReportPath`, `junitReportPath`, `specSnapshotPath`, and `sarifReportPath`
+- sink abstractions under `output.sinks`
+
+The convenience options compile down to built-in sinks so the current API stays simple while the internal output model becomes extensible.
+
+## Explanation
+
+### Why this package exists
+
+`@opsydyn/elysia-spectral` is meant to add contract-quality feedback to Elysia APIs without inventing a second schema system. The source of truth remains the route metadata and response schemas you already define for `@elysiajs/openapi`.
+
+### How it works
+
+The plugin does not inspect private `@elysiajs/openapi` internals. It resolves the generated OpenAPI JSON document through Elysia's public `app.handle(new Request(...))` API, using `source.specPath` or the default `/openapi/json`.
+
+If `source.baseUrl` is configured, the provider can also fall back to loopback HTTP fetch. This keeps spec resolution on public surfaces rather than framework internals.
+
+### Why startup and healthcheck are separate
+
+Startup linting and route exposure solve different problems:
+
+- startup linting protects boot and local feedback loops
+- healthchecks expose operational state to external callers
+
+Separating them avoids a production surprise where enabling linting also adds a route you did not intend to expose.
+
+### Why repo-level rulesets are the default customization path
+
+Teams usually want policy to live with the service, not inside library code. A repo-level ruleset keeps API governance close to the app, easy to review in pull requests, and easy to override without forking this package.
+
+That is why `spectralPlugin()` can autodiscover a repo-level ruleset and merge it with the package defaults.
+
+### Why the runtime is exported separately
+
+The runtime exists so the same linting behavior can run in:
+
+- app startup
+- healthcheck-triggered manual runs
+- CI pipelines
+- tests
+
+That keeps the plugin thin while still giving teams a stable programmatic surface for automation.
+
+### Why runtime state is tracked explicitly
+
+Production-grade linting needs more than a pass/fail boolean. The runtime tracks status, timestamps, last success, and last failure so operators and automated systems can understand what happened without re-running lint blindly.
+
+### Project status
+
+This package currently implements the narrowed v0.1 scope from [project.md](../../project.md) and the ongoing hardening work tracked in [roadmap.md](../../roadmap.md).

package/dist/core/index.d.mts

@@ -0,0 +1,2 @@
+import { _ as defaultRulesetResolvers, a as OpenApiLintArtifactWriteError, b as lintOpenApi, c as resolveStartupMode, d as LoadedRuleset, f as ResolvedRulesetCandidate, g as RulesetResolverInput, h as RulesetResolverContext, i as shouldFail, l as normalizeFindings, m as RulesetResolver, n as enforceThreshold, o as createOpenApiLintRuntime, p as RulesetLoadError, r as exceedsThreshold, s as isEnabled, t as OpenApiLintThresholdError, u as LoadResolvedRulesetOptions, v as loadResolvedRuleset, y as loadRuleset } from "../index-BrFQCFDI.mjs";
+export { LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail };

package/dist/core/index.mjs

@@ -0,0 +1,2 @@
+import { a as OpenApiLintThresholdError, c as shouldFail, d as defaultRulesetResolvers, f as loadResolvedRuleset, h as normalizeFindings, i as resolveStartupMode, m as lintOpenApi, n as createOpenApiLintRuntime, o as enforceThreshold, p as loadRuleset, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, u as RulesetLoadError } from "../core-Czin3kvK.mjs";
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail };