@opsydyn/elysia-spectral 0.5.2 → 1.0.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## [1.0.0](https://github.com/opsydyn/elysia-spectral/compare/v0.5.2...v1.0.0) (2026-04-15)
+
+
+### ⚠ BREAKING CHANGES
+
+* result.artifacts paths are now relative (e.g. "./artifacts/openapi-lint.json") rather than absolute. Callers that used the path directly to open the file should resolve it with path.resolve().
+
+### Features
+
+* add durationMs, failOn to LintRunResult; relativise artifact paths ([421a20f](https://github.com/opsydyn/elysia-spectral/commit/421a20f6bf655432bceff8369c63bf4762edbc24))
+
 ## [0.5.2](https://github.com/opsydyn/elysia-spectral/compare/v0.5.1...v0.5.2) (2026-04-15)
 
 

package/README.md

@@ -63,6 +63,35 @@ Current package scope:
 - reusable runtime for CI and tests
 - opt-in healthcheck endpoint for cached and fresh runs
 
+## Data flow
+
+```mermaid
+flowchart TD
+    A["Elysia routes\n(TypeScript + t.Object schemas)"]
+    B["@elysiajs/openapi\ngenerates OpenAPI spec at runtime"]
+    C["PublicSpecProvider\nfetches /openapi/json"]
+    D["lintOpenApi\nSpectral rules engine"]
+    E["LintRunResult\n{ ok, source, summary, findings }"]
+
+    F["Console output"]
+    G["JSON report\nopenapi-lint.json"]
+    H["OpenAPI snapshot\n*.open-api.json"]
+    I["SARIF\nGitHub code scanning"]
+    J["JUnit\nCI test reporters"]
+    K["Bruno collection\n.yml / .json"]
+
+    A -->|"route schemas are\nthe source of truth"| B
+    B -->|"spec JSON"| C
+    C -->|"spec JSON"| D
+    D -->|"findings + summary"| E
+    E --> F
+    E --> G
+    E --> H
+    E --> I
+    E --> J
+    E --> K
+```
+
 ## Tutorial
 
 ### Add OpenAPI linting to an Elysia app
@@ -153,6 +182,10 @@ bun run src/index.ts
 - `./artifacts/openapi-lint.json` contains the full lint result
 - `./<package-name>.open-api.json` contains the generated OpenAPI snapshot
 
+A passing run:
+
+![OpenAPI lint pass banner](ship-it.png)
+
 If startup fails, the terminal output includes:
 
 - the failing rule code
@@ -160,6 +193,8 @@ If startup fails, the terminal output includes:
 - a fix hint when one is known
 - a spec reference in `open-api.json#/json/pointer` form
 
+![OpenAPI lint error output](errrors.png)
+
 ### Choose a preset
 
 Three first-party presets are available. Import them directly or set `preset` in the plugin options.

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { a as createOpenApiLintRuntime, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver } from "../index-11HnbLDN.mjs";
+import { a as createOpenApiLintRuntime, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver } from "../index--_yjTKg8.mjs";
 export { LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, shouldFail };

package/dist/core/index.mjs

@@ -1,2 +1,2 @@
-import { a as enforceThreshold, d as RulesetLoadError, f as defaultRulesetResolvers, g as lintOpenApi, i as OpenApiLintThresholdError, m as loadRuleset, n as createOpenApiLintRuntime, o as shouldFail, p as loadResolvedRuleset, t as OpenApiLintArtifactWriteError } from "../core-DTKNy6TU.mjs";
+import { a as enforceThreshold, d as RulesetLoadError, f as defaultRulesetResolvers, g as lintOpenApi, i as OpenApiLintThresholdError, m as loadRuleset, n as createOpenApiLintRuntime, o as shouldFail, p as loadResolvedRuleset, t as OpenApiLintArtifactWriteError } from "../core-BIi33eA1.mjs";
 export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, shouldFail };

package/dist/{core-DTKNy6TU.mjs → core-BIi33eA1.mjs}

@@ -55,6 +55,8 @@ const normalizeFindings = (diagnostics, spec) => {
 		ok: summary.error === 0,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
 		source: "manual",
+		failOn: "error",
+		durationMs: null,
 		summary,
 		findings
 	};
@@ -1198,7 +1200,8 @@ const createOpenApiLintRuntime = (options = {}) => {
 					else if (loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint loaded ruleset ${loadedRuleset.source.path}.`);
 					const result = await lintOpenApi(spec, loadedRuleset.ruleset);
 					result.source = source;
-					result.ok = !shouldFail(result, options.failOn ?? "error");
+					result.failOn = options.failOn ?? "error";
+					result.ok = !shouldFail(result, result.failOn);
 					await writeOutputSinks(result, spec, options, artifactWriteFailureMode);
 					runtime.latest = result;
 					reporter.complete("OpenAPI lint completed.");
@@ -1206,6 +1209,7 @@ const createOpenApiLintRuntime = (options = {}) => {
 					runtime.status = "passed";
 					runtime.lastSuccess = result;
 					finalizeRuntimeRun(runtime, startedAt);
+					result.durationMs = runtime.durationMs;
 					return result;
 				} catch (error) {
 					runtime.status = "failed";
@@ -1264,9 +1268,18 @@ const writeOutputSinks = async (result, spec, options, artifactWriteFailureMode)
 		throw error;
 	}
 };
+const relativiseArtifacts = (artifacts) => {
+	const cwd = process.cwd();
+	const result = {};
+	for (const [key, value] of Object.entries(artifacts)) if (typeof value === "string" && path.isAbsolute(value)) {
+		const rel = path.relative(cwd, value);
+		result[key] = rel.startsWith(".") ? rel : `./${rel}`;
+	} else result[key] = value;
+	return result;
+};
 const mergeArtifacts = (current, next) => ({
 	...current,
-	...next
+	...relativiseArtifacts(next)
 });
 const resolveStartupMode = (options = {}) => {
 	if (options.startup?.mode) return options.startup.mode;

package/dist/{index-11HnbLDN.d.mts → index--_yjTKg8.d.mts}

@@ -85,6 +85,8 @@ type LintRunResult = {
   ok: boolean;
   generatedAt: string;
   source: LintRunSource;
+  failOn: SeverityThreshold;
+  durationMs: number | null;
   summary: {
     error: number;
     warn: number;

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SpectralLogger, C as OpenApiLintRuntime, D as OpenApiLintSinkContext, E as OpenApiLintSink, M as StartupLintMode, O as PresetName, S as OpenApiLintArtifacts, T as OpenApiLintRuntimeStatus, _ as ArtifactWriteFailureMode, a as createOpenApiLintRuntime, b as LintRunSource, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, j as SpectralPluginOptions, k as SeverityThreshold, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver, v as LintFinding, w as OpenApiLintRuntimeFailure, x as LintSeverity, y as LintRunResult } from "./index-11HnbLDN.mjs";
+import { A as SpectralLogger, C as OpenApiLintRuntime, D as OpenApiLintSinkContext, E as OpenApiLintSink, M as StartupLintMode, O as PresetName, S as OpenApiLintArtifacts, T as OpenApiLintRuntimeStatus, _ as ArtifactWriteFailureMode, a as createOpenApiLintRuntime, b as LintRunSource, c as ResolvedRulesetCandidate, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, j as SpectralPluginOptions, k as SeverityThreshold, l as RulesetLoadError, m as loadResolvedRuleset, n as enforceThreshold, o as LoadResolvedRulesetOptions, p as defaultRulesetResolvers, r as shouldFail, s as LoadedRuleset, t as OpenApiLintThresholdError, u as RulesetResolver, v as LintFinding, w as OpenApiLintRuntimeFailure, x as LintSeverity, y as LintRunResult } from "./index--_yjTKg8.mjs";
 import { RulesetDefinition } from "@stoplight/spectral-core";
 import { Elysia } from "elysia";
 

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as enforceThreshold, c as strict, d as RulesetLoadError, f as defaultRulesetResolvers, g as lintOpenApi, h as recommended, i as OpenApiLintThresholdError, l as server, m as loadRuleset, n as createOpenApiLintRuntime, o as shouldFail, p as loadResolvedRuleset, r as resolveStartupMode, s as presets, t as OpenApiLintArtifactWriteError, u as resolveReporter } from "./core-DTKNy6TU.mjs";
+import { a as enforceThreshold, c as strict, d as RulesetLoadError, f as defaultRulesetResolvers, g as lintOpenApi, h as recommended, i as OpenApiLintThresholdError, l as server, m as loadRuleset, n as createOpenApiLintRuntime, o as shouldFail, p as loadResolvedRuleset, r as resolveStartupMode, s as presets, t as OpenApiLintArtifactWriteError, u as resolveReporter } from "./core-BIi33eA1.mjs";
 import { Elysia } from "elysia";
 //#region src/plugin.ts
 const spectralPlugin = (options = {}) => {

package/package.json

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