@opsydyn/elysia-spectral 1.5.1 → 1.5.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.5.2](https://github.com/opsydyn/elysia-spectral/compare/v1.5.1...v1.5.2) (2026-05-12)
+
+
+### Bug Fixes
+
+* complete self-describing lint reports ([b0917ce](https://github.com/opsydyn/elysia-spectral/commit/b0917ce4c977a1378ba851efc643058a70fea70b))
+
 ## [1.5.1](https://github.com/opsydyn/elysia-spectral/compare/v1.5.0...v1.5.1) (2026-05-12)
 
 

package/README.md

@@ -58,6 +58,7 @@ Current package scope:
 - resolver pipeline for advanced ruleset loading
 - console output
 - JSON report output
+- self-describing JSON report metadata (`failOn`, `durationMs`, relative artifact paths)
 - JUnit report output
 - SARIF report output
 - OpenAPI snapshot output
@@ -846,6 +847,10 @@ type LintRunResult = {
   generatedAt: string
   /** Where the lint run was triggered from. */
   source: LintRunSource
+  /** The configured threshold that produced this result. */
+  failOn: SeverityThreshold
+  /** Duration of the completed lint run in milliseconds. */
+  durationMs: number | null
   summary: {
     error: number
     warn: number
@@ -1008,6 +1013,8 @@ Example successful response:
     "ok": true,
     "generatedAt": "2026-04-06T12:00:00.000Z",
     "source": "startup",
+    "failOn": "error",
+    "durationMs": 42,
     "summary": {
       "error": 0,
       "warn": 0,
@@ -1049,6 +1056,8 @@ The current output model has two layers:
 
 The convenience options compile down to built-in sinks so the current API stays simple while the internal output model becomes extensible.
 
+Persisted JSON reports are self-describing: they embed the configured `failOn` threshold, the completed `durationMs`, and relative artifact paths so the same report shape is portable across CI runners and developer machines.
+
 ## Explanation
 
 ### Why this package exists
@@ -1096,4 +1105,4 @@ Production-grade linting needs more than a pass/fail boolean. The runtime tracks
 
 ### Project status
 
-The package is published to npm and used in production. Ongoing work — additional rules, deeper Elysia integrations, and dashboard polish — is tracked in [roadmap.md](../../roadmap.md).
+The package is published to npm and used in production. The current pre-`1.0` feature roadmap is functionally complete: startup/runtime flows, presets, output sinks, CI workflows, dashboard support, and self-describing result artifacts are all shipped. Remaining work is primarily `1.0` stabilization — public API/package boundaries, backwards-compatibility audit, and migration notes — tracked in [roadmap.md](../../roadmap.md).

package/dist/core/index.mjs

@@ -1,5 +1,5 @@
 import { t as RulesetLoadError } from "../ruleset-load-error-CogUOC7W.mjs";
-import { a as enforceThreshold, i as OpenApiLintThresholdError, n as createOpenApiLintRuntime, o as shouldFail, t as OpenApiLintArtifactWriteError } from "../runtime-4LlfDIZv.mjs";
+import { a as enforceThreshold, i as OpenApiLintThresholdError, n as createOpenApiLintRuntime, o as shouldFail, t as OpenApiLintArtifactWriteError } from "../runtime-PGHAFx-E.mjs";
 import { n as loadResolvedRuleset, r as loadRuleset, t as defaultRulesetResolvers } from "../load-ruleset-CiikrzWx.mjs";
 import { t as lintOpenApi } from "../lint-openapi-D76sC7S5.mjs";
 export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, shouldFail };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 import { t as RulesetLoadError } from "./ruleset-load-error-CogUOC7W.mjs";
-import { a as enforceThreshold, i as OpenApiLintThresholdError, n as createOpenApiLintRuntime, o as shouldFail, r as resolveStartupMode, s as resolveReporter, t as OpenApiLintArtifactWriteError } from "./runtime-4LlfDIZv.mjs";
+import { a as enforceThreshold, i as OpenApiLintThresholdError, n as createOpenApiLintRuntime, o as shouldFail, r as resolveStartupMode, s as resolveReporter, t as OpenApiLintArtifactWriteError } from "./runtime-PGHAFx-E.mjs";
 import { t as recommended } from "./recommended-DgrTqq-3.mjs";
 import { i as server, r as strict, t as presets } from "./presets-CCfU_diN.mjs";
 import { Elysia } from "elysia";

package/dist/{runtime-4LlfDIZv.mjs → runtime-PGHAFx-E.mjs}

@@ -411,6 +411,11 @@ const toSarifArtifactUri = (value) => {
 };
 //#endregion
 //#region src/output/sinks.ts
+const relativiseArtifactPath = (artifactPath) => {
+	const resolvedPath = path.resolve(process.cwd(), artifactPath);
+	const relativePath = path.relative(process.cwd(), resolvedPath);
+	return relativePath.startsWith(".") ? relativePath : `./${relativePath}`;
+};
 const createOutputSinks = (options) => {
 	const reporter = resolveReporter(options.logger);
 	const sinks = [];
@@ -421,24 +426,17 @@ const createOutputSinks = (options) => {
 	if (configuredSpecSnapshotPath) sinks.push({
 		name: "spec snapshot",
 		kind: "artifact",
+		phase: "pre-finalize",
 		async write(_result, context) {
 			const writtenSpecSnapshotPath = await writeSpecSnapshot(configuredSpecSnapshotPath === true ? await resolveDefaultSpecSnapshotPath() : configuredSpecSnapshotPath, context.spec, options.output?.pretty !== false);
 			reporter.artifact(`OpenAPI lint wrote spec snapshot to ${writtenSpecSnapshotPath}.`);
 			return { specSnapshotPath: writtenSpecSnapshotPath };
 		}
 	});
-	if (configuredJsonReportPath) sinks.push({
-		name: "JSON report",
-		kind: "artifact",
-		async write(result) {
-			const writtenJsonReportPath = await writeJsonReport(configuredJsonReportPath, result, options.output?.pretty !== false);
-			reporter.artifact(`OpenAPI lint wrote JSON report to ${writtenJsonReportPath}.`);
-			return { jsonReportPath: writtenJsonReportPath };
-		}
-	});
 	if (configuredJunitReportPath) sinks.push({
 		name: "JUnit report",
 		kind: "artifact",
+		phase: "pre-finalize",
 		async write(result) {
 			const writtenJunitReportPath = await writeJunitReport(configuredJunitReportPath, result);
 			reporter.artifact(`OpenAPI lint wrote JUnit report to ${writtenJunitReportPath}.`);
@@ -449,6 +447,7 @@ const createOutputSinks = (options) => {
 	if (configuredBrunoCollectionPath) sinks.push({
 		name: "Bruno collection",
 		kind: "artifact",
+		phase: "pre-finalize",
 		async write(_result, context) {
 			const writtenPath = await writeBrunoCollection(configuredBrunoCollectionPath, context.spec);
 			reporter.artifact(`OpenAPI lint wrote Bruno collection to ${writtenPath}.`);
@@ -458,6 +457,7 @@ const createOutputSinks = (options) => {
 	if (configuredSarifReportPath) sinks.push({
 		name: "SARIF report",
 		kind: "artifact",
+		phase: "pre-finalize",
 		async write(result) {
 			const writtenSarifReportPath = await writeSarifReport(configuredSarifReportPath, result, options.output?.pretty !== false);
 			reporter.artifact(`OpenAPI lint wrote SARIF report to ${writtenSarifReportPath}.`);
@@ -467,11 +467,29 @@ const createOutputSinks = (options) => {
 	for (const sink of options.output?.sinks ?? []) sinks.push({
 		name: sink.name,
 		kind: "custom",
+		phase: "post-finalize",
 		write: async (result, context) => await Promise.resolve(sink.write(result, context))
 	});
+	if (configuredJsonReportPath) sinks.push({
+		name: "JSON report",
+		kind: "artifact",
+		phase: "post-finalize",
+		async write(result) {
+			const writtenJsonReportPath = await writeJsonReport(configuredJsonReportPath, {
+				...result,
+				artifacts: {
+					...result.artifacts ?? {},
+					jsonReportPath: relativiseArtifactPath(configuredJsonReportPath)
+				}
+			}, options.output?.pretty !== false);
+			reporter.artifact(`OpenAPI lint wrote JSON report to ${writtenJsonReportPath}.`);
+			return { jsonReportPath: writtenJsonReportPath };
+		}
+	});
 	if (options.output?.console !== false) sinks.push({
 		name: "console",
 		kind: "report",
+		phase: "post-finalize",
 		async write(result) {
 			reportToConsole(result, reporter);
 		}
@@ -645,10 +663,12 @@ const createOpenApiLintRuntime = (options = {}) => {
 					result.source = source;
 					result.failOn = options.failOn ?? "error";
 					result.ok = !shouldFail(result, result.failOn);
-					await writeOutputSinks(result, spec, options, artifactWriteFailureMode);
-					runtime.latest = result;
+					const { preFinalizeSinks, postFinalizeSinks } = partitionOutputSinks(createOutputSinks(options));
+					await writeOutputSinks(preFinalizeSinks, result, spec, reporter, artifactWriteFailureMode);
 					finalizeRuntimeRun(runtime, startedAt);
 					result.durationMs = runtime.durationMs;
+					await writeOutputSinks(postFinalizeSinks, result, spec, reporter, artifactWriteFailureMode);
+					runtime.latest = result;
 					reporter.complete("OpenAPI lint completed.");
 					enforceThreshold(result, options.failOn ?? "error");
 					runtime.status = "passed";
@@ -694,9 +714,7 @@ const handleArtifactWriteFailure = (artifact, error, mode, reporter) => {
 	if (mode === "error") throw wrappedError;
 	reporter.warn(wrappedError.message);
 };
-const writeOutputSinks = async (result, spec, options, artifactWriteFailureMode) => {
-	const reporter = resolveReporter(options.logger);
-	const sinks = createOutputSinks(options);
+const writeOutputSinks = async (sinks, result, spec, reporter, artifactWriteFailureMode) => {
 	for (const sink of sinks) try {
 		const artifacts = await sink.write(result, {
 			spec,
@@ -711,6 +729,21 @@ const writeOutputSinks = async (result, spec, options, artifactWriteFailureMode)
 		throw error;
 	}
 };
+const partitionOutputSinks = (sinks) => {
+	const preFinalizeSinks = [];
+	const postFinalizeSinks = [];
+	for (const sink of sinks) {
+		if (sink.phase === "post-finalize") {
+			postFinalizeSinks.push(sink);
+			continue;
+		}
+		preFinalizeSinks.push(sink);
+	}
+	return {
+		preFinalizeSinks,
+		postFinalizeSinks
+	};
+};
 const relativiseArtifacts = (artifacts) => {
 	const cwd = process.cwd();
 	const result = {};

package/package.json

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