@opsydyn/elysia-spectral 0.2.4

package/dist/index-BrFQCFDI.d.mts

@@ -0,0 +1,172 @@
+import { ISpectralDiagnostic, RulesetDefinition } from "@stoplight/spectral-core";
+import { AnyElysia } from "elysia";
+
+//#region src/types.d.ts
+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 ArtifactWriteFailureMode = 'warn' | 'error';
+type SpectralLogger = {
+  info: (message: string) => void;
+  warn: (message: string) => void;
+  error: (message: string) => void;
+};
+type OpenApiLintArtifacts = {
+  jsonReportPath?: string;
+  junitReportPath?: string;
+  sarifReportPath?: string;
+  specSnapshotPath?: string;
+};
+type OpenApiLintSinkContext = {
+  spec: Record<string, unknown>;
+  logger: SpectralLogger;
+};
+type OpenApiLintSink = {
+  name: string;
+  write: (result: LintRunResult, context: OpenApiLintSinkContext) => undefined | Partial<OpenApiLintArtifacts> | Promise<undefined | Partial<OpenApiLintArtifacts>>;
+};
+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?: SpectralLogger;
+};
+type LintFinding = {
+  code: string;
+  message: string;
+  severity: LintSeverity;
+  path: Array<string | number>;
+  documentPointer?: string;
+  recommendation?: string;
+  source?: string;
+  range?: {
+    start?: {
+      line: number;
+      character: number;
+    };
+    end?: {
+      line: number;
+      character: number;
+    };
+  };
+  operation?: {
+    method?: string;
+    path?: string;
+    operationId?: string;
+  };
+};
+type LintRunResult = {
+  ok: boolean;
+  generatedAt: string;
+  summary: {
+    error: number;
+    warn: number;
+    info: number;
+    hint: number;
+    total: number;
+  };
+  artifacts?: OpenApiLintArtifacts;
+  findings: LintFinding[];
+};
+interface SpecProvider {
+  getSpec(): Promise<unknown>;
+}
+type OpenApiLintRuntimeFailure = {
+  name: string;
+  message: string;
+  generatedAt: string;
+};
+type OpenApiLintRuntime = {
+  status: OpenApiLintRuntimeStatus;
+  startedAt: string | null;
+  completedAt: string | null;
+  durationMs: number | null;
+  latest: LintRunResult | null;
+  lastSuccess: LintRunResult | null;
+  lastFailure: OpenApiLintRuntimeFailure | null;
+  running: boolean;
+  run: (app: AnyElysia) => Promise<LintRunResult>;
+};
+//#endregion
+//#region src/core/lint-openapi.d.ts
+declare const lintOpenApi: (spec: Record<string, unknown>, ruleset: RulesetDefinition) => Promise<LintRunResult>;
+//#endregion
+//#region src/core/load-ruleset.d.ts
+type LoadedRuleset = {
+  ruleset: RulesetDefinition;
+  source?: {
+    path: string;
+    autodiscovered: boolean;
+    mergedWithDefault: boolean;
+  };
+};
+type ResolvedRulesetCandidate = {
+  ruleset: unknown;
+  source?: LoadedRuleset['source'];
+};
+type RulesetResolverInput = string | RulesetDefinition | Record<string, unknown> | undefined;
+type RulesetResolverContext = {
+  baseDir: string;
+  defaultRuleset: RulesetDefinition;
+  mergeAutodiscoveredWithDefault: boolean;
+};
+type RulesetResolver = (input: RulesetResolverInput, context: RulesetResolverContext) => Promise<ResolvedRulesetCandidate | undefined>;
+type LoadResolvedRulesetOptions = {
+  baseDir?: string;
+  resolvers?: RulesetResolver[];
+  mergeAutodiscoveredWithDefault?: boolean;
+};
+declare class RulesetLoadError extends Error {
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
+}
+declare const loadRuleset: (input?: RulesetResolverInput, baseDirOrOptions?: string | LoadResolvedRulesetOptions) => Promise<RulesetDefinition>;
+declare const loadResolvedRuleset: (input?: RulesetResolverInput, baseDirOrOptions?: string | LoadResolvedRulesetOptions) => Promise<LoadedRuleset>;
+declare const defaultRulesetResolvers: RulesetResolver[];
+//#endregion
+//#region src/core/normalize-findings.d.ts
+declare const normalizeFindings: (diagnostics: ISpectralDiagnostic[], spec: unknown) => LintRunResult;
+//#endregion
+//#region src/core/runtime.d.ts
+declare const createOpenApiLintRuntime: (options?: SpectralPluginOptions) => OpenApiLintRuntime;
+declare class OpenApiLintArtifactWriteError extends Error {
+  readonly artifact: string;
+  readonly cause: unknown;
+  constructor(artifact: string, cause: unknown);
+}
+declare const isEnabled: (options?: SpectralPluginOptions) => boolean;
+declare const resolveStartupMode: (options?: SpectralPluginOptions) => StartupLintMode;
+//#endregion
+//#region src/core/thresholds.d.ts
+declare class OpenApiLintThresholdError extends Error {
+  readonly threshold: SeverityThreshold;
+  readonly result: LintRunResult;
+  constructor(threshold: SeverityThreshold, result: LintRunResult);
+}
+declare const exceedsThreshold: (severity: LintSeverity, threshold: SeverityThreshold) => boolean;
+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, StartupLintMode as F, SpecProvider as M, SpectralLogger as N, OpenApiLintRuntimeStatus as O, SpectralPluginOptions 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, SeverityThreshold 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 };

package/dist/index.d.mts

@@ -0,0 +1,36 @@
+import { A as OpenApiLintSinkContext, C as LintRunResult, D as OpenApiLintRuntimeFailure, E as OpenApiLintRuntime, F as StartupLintMode, M as SpecProvider, N as SpectralLogger, O as OpenApiLintRuntimeStatus, P as SpectralPluginOptions, 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 SeverityThreshold, 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-BrFQCFDI.mjs";
+import { Elysia } from "elysia";
+
+//#region src/plugin.d.ts
+declare const spectralPlugin: (options?: SpectralPluginOptions) => Elysia<"", {
+  decorator: {};
+  store: {
+    openApiLint: OpenApiLintRuntime;
+  };
+  derive: {};
+  resolve: {};
+}, {
+  typebox: {};
+  error: {};
+}, {
+  schema: {};
+  standaloneSchema: {};
+  macro: {};
+  macroFn: {};
+  parser: {};
+  response: {};
+}, {}, {
+  derive: {};
+  resolve: {};
+  schema: {};
+  standaloneSchema: {};
+  response: {};
+}, {
+  derive: {};
+  resolve: {};
+  schema: {};
+  standaloneSchema: {};
+  response: {};
+}>;
+//#endregion
+export { ArtifactWriteFailureMode, LintFinding, LintRunResult, LintSeverity, LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintArtifacts, OpenApiLintRuntime, OpenApiLintRuntimeFailure, OpenApiLintRuntimeStatus, OpenApiLintSink, OpenApiLintSinkContext, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, SeverityThreshold, SpecProvider, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail, spectralPlugin };

package/dist/index.mjs

@@ -0,0 +1,85 @@
+import { a as OpenApiLintThresholdError, c as shouldFail, d as defaultRulesetResolvers, f as loadResolvedRuleset, h as normalizeFindings, i as resolveStartupMode, l as resolveReporter, 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";
+import { Elysia } from "elysia";
+//#region src/plugin.ts
+const spectralPlugin = (options = {}) => {
+	const runtime = createOpenApiLintRuntime(options);
+	const hostAppRef = { current: null };
+	const reporter = resolveReporter(options.logger);
+	let plugin = new Elysia({ name: "@opsydyn/elysia-spectral" }).state("openApiLint", runtime).onStart(async (context) => {
+		const app = context.app ?? context;
+		hostAppRef.current = app;
+		const startupMode = resolveStartupMode(options);
+		if (startupMode === "off") return;
+		try {
+			await runtime.run(app);
+		} 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".`);
+				return;
+			}
+			throw error;
+		}
+	});
+	if (options.healthcheck) {
+		const healthcheckPath = options.healthcheck.path ?? "/__openapi/health";
+		plugin = plugin.get(healthcheckPath, async ({ request, set }) => {
+			const fresh = new URL(request.url).searchParams.get("fresh") === "1";
+			const threshold = options.failOn ?? "error";
+			const currentApp = hostAppRef.current;
+			if (!currentApp) {
+				set.status = 503;
+				return {
+					ok: false,
+					cached: false,
+					threshold,
+					error: "OpenAPI lint runtime is not initialized yet."
+				};
+			}
+			try {
+				const usedCache = !fresh && (runtime.latest !== null || runtime.running);
+				const result = usedCache ? runtime.latest ?? await runtime.run(currentApp) : await runtime.run(currentApp);
+				if (result === null) {
+					set.status = 500;
+					return {
+						ok: false,
+						cached: false,
+						threshold,
+						error: "OpenAPI lint returned no result."
+					};
+				}
+				const healthy = !shouldFail(result, threshold);
+				set.status = healthy ? 200 : 503;
+				return {
+					ok: healthy,
+					cached: usedCache,
+					threshold,
+					result
+				};
+			} catch (error) {
+				if (error instanceof OpenApiLintThresholdError) {
+					set.status = 503;
+					return {
+						ok: false,
+						cached: false,
+						threshold,
+						result: error.result,
+						error: error.message
+					};
+				}
+				set.status = 500;
+				return {
+					ok: false,
+					cached: false,
+					threshold,
+					error: error instanceof Error ? error.message : String(error)
+				};
+			}
+		}, { detail: {
+			hide: true,
+			summary: "OpenAPI lint healthcheck"
+		} });
+	}
+	return plugin;
+};
+//#endregion
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail, spectralPlugin };

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@opsydyn/elysia-spectral",
+  "version": "0.2.4",
+  "description": "Thin Elysia plugin that lints generated OpenAPI documents with Spectral.",
+  "packageManager": "bun@1.2.9",
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.mts",
+      "import": "./dist/core/index.mjs"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "core": [
+        "./dist/core/index.d.mts"
+      ]
+    }
+  },
+  "files": [
+    "CHANGELOG.md",
+    "dist",
+    "README.md",
+    "spectral.yaml"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "typecheck": "tsc --noEmit",
+    "test": "bun test",
+    "test:watch": "bun test --watch"
+  },
+  "keywords": [
+    "elysia",
+    "openapi",
+    "spectral",
+    "lint",
+    "bun"
+  ],
+  "author": "Alan P Currie",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/opsydyn/elysia-spectral.git",
+    "directory": "packages/elysia-spectral"
+  },
+  "homepage": "https://github.com/opsydyn/elysia-spectral#readme",
+  "bugs": {
+    "url": "https://github.com/opsydyn/elysia-spectral/issues"
+  },
+  "engines": {
+    "node": ">=22.0.0",
+    "bun": ">=1.3.0"
+  },
+  "peerDependencies": {
+    "elysia": "^1.4.0"
+  },
+  "dependencies": {
+    "@stoplight/spectral-core": "^1.22.0",
+    "@stoplight/spectral-formats": "^1.8.0",
+    "@stoplight/spectral-functions": "^1.10.2",
+    "@stoplight/spectral-parsers": "^1.0.4",
+    "@stoplight/spectral-rulesets": "^1.22.1",
+    "signale": "^1.4.0",
+    "yaml": "^2.8.1"
+  },
+  "devDependencies": {
+    "@elysiajs/openapi": "^1.4.0",
+    "@types/bun": "^1.3.12",
+    "@types/node": "^25.6.0",
+    "@types/signale": "^1.4.7",
+    "elysia": "^1.4.0",
+    "tsdown": "^0.21.8",
+    "typescript": "^5.8.3"
+  }
+}

package/spectral.yaml

@@ -0,0 +1,25 @@
+extends:
+  - spectral:oas
+rules:
+  oas3-api-servers: off
+  info-contact: off
+
+  elysia-operation-summary:
+    description: Operations should define a summary for generated docs and clients.
+    severity: warn
+    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
+    then:
+      field: summary
+      function: truthy
+
+  elysia-operation-tags:
+    description: Operations should declare at least one tag for grouping and downstream tooling.
+    severity: warn
+    given: $.paths[*][get,put,post,delete,options,head,patch,trace]
+    then:
+      field: tags
+      function: schema
+      functionOptions:
+        schema:
+          type: array
+          minItems: 1