@opsydyn/elysia-spectral 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.4.0](https://github.com/opsydyn/elysia-spectral/compare/v0.3.0...v0.4.0) (2026-04-15)
+
+
+### Features
+
+* add source metadata to LintRunResult ([bdd5a81](https://github.com/opsydyn/elysia-spectral/commit/bdd5a817c00b5fdccf4e1d27c8dbf4c6d4c36d2c))
+
 ## [0.3.0](https://github.com/opsydyn/elysia-spectral/compare/v0.2.5...v0.3.0) (2026-04-14)
 
 

package/README.md

@@ -426,29 +426,101 @@ spectralPlugin({
 
 Use `'warn'` for local development and `'error'` when artifact generation is required.
 
-### Run the runtime in CI or tests
+### Run the runtime in CI
+
+Use `createOpenApiLintRuntime` to run a standalone lint check in CI without starting an HTTP server. Import your Elysia app instance directly — the runtime uses `app.handle()` in-process to retrieve the generated OpenAPI document. No port binding required.
+
+Create a script at `scripts/lint-openapi.ts`:
 
 ```ts
-import { Elysia } from 'elysia'
-import { openapi } from '@elysiajs/openapi'
+import { app } from '../src/app'
 import { createOpenApiLintRuntime } from '@opsydyn/elysia-spectral'
 
-const app = new Elysia().use(openapi())
-
 const runtime = createOpenApiLintRuntime({
-  ruleset: './spectral.yaml',
+  preset: 'strict',
   failOn: 'error',
   output: {
     console: true,
-    jsonReportPath: './artifacts/openapi-lint.json',
-    specSnapshotPath: true,
-    artifactWriteFailures: 'error'
-  }
+    sarifReportPath: './reports/openapi.sarif',
+    junitReportPath: './reports/openapi.junit.xml',
+    specSnapshotPath: './reports/openapi-snapshot.json',
+    artifactWriteFailures: 'error',
+  },
 })
 
-await runtime.run(app)
+try {
+  await runtime.run(app)
+  process.exit(0)
+} catch {
+  process.exit(1)
+}
+```
+
+Run it as a CI step:
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+```
+
+### Integrate SARIF with GitHub code scanning
+
+SARIF output maps lint findings to code locations and surfaces them as GitHub code scanning alerts on pull requests.
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Upload SARIF to GitHub code scanning
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: reports/openapi.sarif
+  if: always()
 ```
 
+`if: always()` ensures the SARIF upload runs even when the lint step fails, so findings are visible on failing PRs.
+
+### Report lint findings as JUnit test results
+
+JUnit output lets CI systems that consume test XML (Buildkite, CircleCI, GitLab, GitHub via third-party actions) show lint findings alongside test results.
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Publish lint results
+  uses: dorny/test-reporter@v1
+  with:
+    name: OpenAPI Lint
+    path: reports/openapi.junit.xml
+    reporter: java-junit
+  if: always()
+```
+
+### Track OpenAPI snapshot drift
+
+Commit the generated OpenAPI snapshot and use `git diff --exit-code` to detect when the API surface changes unexpectedly in a PR.
+
+1. Generate and commit the initial snapshot:
+
+```bash
+bun scripts/lint-openapi.ts
+git add reports/openapi-snapshot.json
+git commit -m "chore: add openapi snapshot"
+```
+
+1. In CI, regenerate the snapshot and check for drift:
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Check for snapshot drift
+  run: git diff --exit-code reports/openapi-snapshot.json
+```
+
+If the snapshot has changed, the CI step fails and the diff is visible in the logs. Deliberate API changes are acknowledged by updating the committed snapshot — accidental ones are caught before they ship.
+
 ### Work on this repository locally
 
 From the monorepo root:
@@ -606,6 +678,7 @@ Example successful response:
   "result": {
     "ok": true,
     "generatedAt": "2026-04-06T12:00:00.000Z",
+    "source": "startup",
     "summary": {
       "error": 0,
       "warn": 0,

package/dist/core/index.d.mts

@@ -1,2 +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-YZElrxnl.mjs";
+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-CMyl_MsI.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

@@ -1,2 +1,2 @@
-import { a as OpenApiLintThresholdError, c as shouldFail, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, v as lintOpenApi, y as normalizeFindings } from "../core-DBjV7-E8.mjs";
+import { a as OpenApiLintThresholdError, c as shouldFail, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, v as lintOpenApi, y as normalizeFindings } from "../core-D_ro1XEW.mjs";
 export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail };

package/dist/{core-DBjV7-E8.mjs → core-D_ro1XEW.mjs}

@@ -53,6 +53,7 @@ const normalizeFindings = (diagnostics, spec) => {
 	return {
 		ok: summary.error === 0,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		source: "manual",
 		summary,
 		findings
 	};
@@ -1155,7 +1156,7 @@ const createOpenApiLintRuntime = (options = {}) => {
 		lastSuccess: null,
 		lastFailure: null,
 		running: false,
-		async run(app) {
+		async run(app, source = "manual") {
 			if (inFlight) return await inFlight;
 			inFlight = (async () => {
 				const startedAt = /* @__PURE__ */ new Date();
@@ -1174,6 +1175,7 @@ const createOpenApiLintRuntime = (options = {}) => {
 					} else if (options.preset && !loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint using "${options.preset}" preset.`);
 					else if (loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint loaded ruleset ${loadedRuleset.source.path}.`);
 					const result = await lintOpenApi(spec, loadedRuleset.ruleset);
+					result.source = source;
 					await writeOutputSinks(result, spec, options, artifactWriteFailureMode);
 					runtime.latest = result;
 					reporter.complete("OpenAPI lint completed.");

package/dist/{index-YZElrxnl.d.mts → index-CMyl_MsI.d.mts}

@@ -7,6 +7,7 @@ type SeverityThreshold = 'error' | 'warn' | 'info' | 'hint' | 'never';
 type LintSeverity = 'error' | 'warn' | 'info' | 'hint';
 type StartupLintMode = 'enforce' | 'report' | 'off';
 type OpenApiLintRuntimeStatus = 'idle' | 'running' | 'passed' | 'failed';
+type LintRunSource = 'startup' | 'healthcheck' | 'manual';
 type ArtifactWriteFailureMode = 'warn' | 'error';
 type SpectralLogger = {
   info: (message: string) => void;
@@ -81,6 +82,7 @@ type LintFinding = {
 type LintRunResult = {
   ok: boolean;
   generatedAt: string;
+  source: LintRunSource;
   summary: {
     error: number;
     warn: number;
@@ -108,7 +110,7 @@ type OpenApiLintRuntime = {
   lastSuccess: LintRunResult | null;
   lastFailure: OpenApiLintRuntimeFailure | null;
   running: boolean;
-  run: (app: AnyElysia) => Promise<LintRunResult>;
+  run: (app: AnyElysia, source?: LintRunSource) => Promise<LintRunResult>;
 };
 //#endregion
 //#region src/core/lint-openapi.d.ts
@@ -172,4 +174,4 @@ declare const exceedsThreshold: (severity: LintSeverity, threshold: SeverityThre
 declare const shouldFail: (result: LintRunResult, threshold: SeverityThreshold) => boolean;
 declare const enforceThreshold: (result: LintRunResult, threshold: SeverityThreshold) => void;
 //#endregion
-export { OpenApiLintSinkContext as A, LintRunResult as C, OpenApiLintRuntimeFailure as D, OpenApiLintRuntime as E, SpectralPluginOptions as F, StartupLintMode as I, SeverityThreshold as M, SpecProvider as N, OpenApiLintRuntimeStatus as O, SpectralLogger as P, LintFinding as S, OpenApiLintArtifacts as T, defaultRulesetResolvers as _, OpenApiLintArtifactWriteError as a, lintOpenApi as b, resolveStartupMode as c, LoadedRuleset as d, ResolvedRulesetCandidate as f, RulesetResolverInput as g, RulesetResolverContext as h, shouldFail as i, PresetName as j, OpenApiLintSink as k, normalizeFindings as l, RulesetResolver as m, enforceThreshold as n, createOpenApiLintRuntime as o, RulesetLoadError as p, exceedsThreshold as r, isEnabled as s, OpenApiLintThresholdError as t, LoadResolvedRulesetOptions as u, loadResolvedRuleset as v, LintSeverity as w, ArtifactWriteFailureMode as x, loadRuleset as y };
+export { OpenApiLintSink as A, LintRunResult as C, OpenApiLintRuntime as D, OpenApiLintArtifacts as E, SpectralLogger as F, SpectralPluginOptions as I, StartupLintMode as L, PresetName as M, SeverityThreshold as N, OpenApiLintRuntimeFailure as O, SpecProvider as P, LintFinding as S, LintSeverity as T, defaultRulesetResolvers as _, OpenApiLintArtifactWriteError as a, lintOpenApi as b, resolveStartupMode as c, LoadedRuleset as d, ResolvedRulesetCandidate as f, RulesetResolverInput as g, RulesetResolverContext as h, shouldFail as i, OpenApiLintSinkContext as j, OpenApiLintRuntimeStatus as k, normalizeFindings as l, RulesetResolver as m, enforceThreshold as n, createOpenApiLintRuntime as o, RulesetLoadError as p, exceedsThreshold as r, isEnabled as s, OpenApiLintThresholdError as t, LoadResolvedRulesetOptions as u, loadResolvedRuleset as v, LintRunSource as w, ArtifactWriteFailureMode as x, loadRuleset as y };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as OpenApiLintSinkContext, C as LintRunResult, D as OpenApiLintRuntimeFailure, E as OpenApiLintRuntime, F as SpectralPluginOptions, I as StartupLintMode, M as SeverityThreshold, N as SpecProvider, O as OpenApiLintRuntimeStatus, P as SpectralLogger, S as LintFinding, T as OpenApiLintArtifacts, _ 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, j as PresetName, k as OpenApiLintSink, 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, w as LintSeverity, x as ArtifactWriteFailureMode, y as loadRuleset } from "./index-YZElrxnl.mjs";
+import { A as OpenApiLintSink, C as LintRunResult, D as OpenApiLintRuntime, E as OpenApiLintArtifacts, F as SpectralLogger, I as SpectralPluginOptions, L as StartupLintMode, M as PresetName, N as SeverityThreshold, O as OpenApiLintRuntimeFailure, P as SpecProvider, S as LintFinding, T as LintSeverity, _ 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, j as OpenApiLintSinkContext, k as OpenApiLintRuntimeStatus, 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, w as LintRunSource, x as ArtifactWriteFailureMode, y as loadRuleset } from "./index-CMyl_MsI.mjs";
 import { RulesetDefinition } from "@stoplight/spectral-core";
 import { Elysia } from "elysia";
 
@@ -72,4 +72,4 @@ declare const strict: RulesetDefinition;
 //#region src/presets/index.d.ts
 declare const presets: Record<PresetName, RulesetDefinition>;
 //#endregion
-export { ArtifactWriteFailureMode, LintFinding, LintRunResult, LintSeverity, LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintArtifacts, OpenApiLintRuntime, OpenApiLintRuntimeFailure, OpenApiLintRuntimeStatus, OpenApiLintSink, OpenApiLintSinkContext, OpenApiLintThresholdError, PresetName, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, SeverityThreshold, SpecProvider, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, presets, recommended, resolveStartupMode, server, shouldFail, spectralPlugin, strict };
+export { ArtifactWriteFailureMode, LintFinding, LintRunResult, LintRunSource, LintSeverity, LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintArtifacts, OpenApiLintRuntime, OpenApiLintRuntimeFailure, OpenApiLintRuntimeStatus, OpenApiLintSink, OpenApiLintSinkContext, OpenApiLintThresholdError, PresetName, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, SeverityThreshold, SpecProvider, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, presets, recommended, resolveStartupMode, server, shouldFail, spectralPlugin, strict };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { _ as recommended, a as OpenApiLintThresholdError, c as shouldFail, d as server, f as resolveReporter, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, l as presets, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, u as strict, v as lintOpenApi, y as normalizeFindings } from "./core-DBjV7-E8.mjs";
+import { _ as recommended, a as OpenApiLintThresholdError, c as shouldFail, d as server, f as resolveReporter, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, l as presets, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, u as strict, v as lintOpenApi, y as normalizeFindings } from "./core-D_ro1XEW.mjs";
 import { Elysia } from "elysia";
 //#region src/plugin.ts
 const spectralPlugin = (options = {}) => {
@@ -11,7 +11,7 @@ const spectralPlugin = (options = {}) => {
 		const startupMode = resolveStartupMode(options);
 		if (startupMode === "off") return;
 		try {
-			await runtime.run(app);
+			await runtime.run(app, "startup");
 		} catch (error) {
 			if (startupMode === "report" && error instanceof OpenApiLintThresholdError) {
 				reporter.report(`OpenAPI lint exceeded the "${options.failOn ?? "error"}" threshold, but startup is continuing because startup.mode is "report".`);
@@ -37,7 +37,7 @@ const spectralPlugin = (options = {}) => {
 			}
 			try {
 				const usedCache = !fresh && (runtime.latest !== null || runtime.running);
-				const result = usedCache ? runtime.latest ?? await runtime.run(currentApp) : await runtime.run(currentApp);
+				const result = usedCache ? runtime.latest ?? await runtime.run(currentApp, "healthcheck") : await runtime.run(currentApp, "healthcheck");
 				if (result === null) {
 					set.status = 500;
 					return {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsydyn/elysia-spectral",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Thin Elysia plugin that lints generated OpenAPI documents with Spectral.",
   "packageManager": "bun@1.2.9",
   "publishConfig": {