@opsydyn/elysia-spectral 1.5.0 → 1.5.1

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [1.5.1](https://github.com/opsydyn/elysia-spectral/compare/v1.5.0...v1.5.1) (2026-05-12)
+
+
+### Bug Fixes
+
+* harden spectral import startup path ([024fedf](https://github.com/opsydyn/elysia-spectral/commit/024fedf7fe294fc7919f9d17d7727029e2a04fae))
+
 ## [1.5.0](https://github.com/opsydyn/elysia-spectral/compare/v1.4.0...v1.5.0) (2026-04-28)
 
 

package/README.md

@@ -6,6 +6,8 @@
 
 Thin Elysia plugin that lints the OpenAPI document generated by `@elysiajs/openapi` with Spectral.
 
+`@opsydyn/elysia-spectral` does not generate OpenAPI documents by itself. Your app must expose an OpenAPI JSON document — most commonly by mounting `@elysiajs/openapi`, or by configuring `source.specPath` / `source.baseUrl` to point at an equivalent route.
+
 ## What Is Elysia?
 
 Elysia is a fast, ergonomic TypeScript web framework for Bun. It uses a plugin model for composing functionality and integrates with `@elysiajs/openapi` to generate OpenAPI documentation directly from route schemas — no separate spec file or annotation layer required.
@@ -109,6 +111,8 @@ bun add elysia @elysiajs/openapi @opsydyn/elysia-spectral
 npm install elysia @elysiajs/openapi @opsydyn/elysia-spectral
 ```
 
+`@elysiajs/openapi` is the recommended generator because it exposes the default `/openapi/json` route this package expects. If your app uses a different OpenAPI generator or serves the JSON at a different path, configure `source.specPath` accordingly.
+
 2. Add `@elysiajs/openapi` and `spectralPlugin` to your app with the `strict` preset.
 
 ```ts
@@ -217,6 +221,34 @@ spectralPlugin({ ruleset: strict })
 
 When `preset` is set, autodiscovered `spectral.yaml` overrides merge on top of the preset rather than the package default. This lets you tighten or loosen individual rules without losing the preset baseline.
 
+### Provide an OpenAPI JSON route
+
+`@opsydyn/elysia-spectral` needs a public OpenAPI JSON document to lint. By default it looks for `/openapi/json` via `app.handle(new Request(...))`.
+
+The recommended setup is to mount `@elysiajs/openapi`:
+
+```ts
+import { Elysia } from 'elysia'
+import { openapi } from '@elysiajs/openapi'
+import { spectralPlugin } from '@opsydyn/elysia-spectral'
+
+new Elysia()
+  .use(openapi())
+  .use(spectralPlugin())
+```
+
+If your app exposes the OpenAPI JSON document somewhere else, point the plugin at that route:
+
+```ts
+spectralPlugin({
+  source: {
+    specPath: '/docs/openapi.json'
+  }
+})
+```
+
+If the route is missing, the runtime throws an actionable provider error explaining that an OpenAPI generator (for example `@elysiajs/openapi`) must be installed and mounted, or that `source.specPath` should be updated.
+
 ## How-to Guides
 
 ### Use a repo-level ruleset
@@ -386,9 +418,10 @@ What it surfaces:
 
 Keyboard shortcuts: `r` re-runs, `/` focuses the filter, `Enter`/`Space` toggles the focused severity chip.
 
-Three dark themes ship with the dashboard, selectable from the header dropdown and persisted per-browser via `localStorage`:
+Four dark themes ship with the dashboard, selectable from the header dropdown and persisted per-browser via `localStorage`:
 
 - **Astro Houston** (default) — purple / blue gradient
+- **Elysia** — pink on deep purple, sourced from the Scalar palette
 - **Tron Legacy** — cyan neon on near-black
 - **Detroit 808** — TR-808 amber, red, and yellow
 
@@ -523,6 +556,8 @@ Use `'warn'` for local development and `'error'` when artifact generation is req
 
 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.
 
+Before using the runtime, make sure the app instance mounts an OpenAPI generator (typically `@elysiajs/openapi`) or otherwise serves a reachable OpenAPI JSON route.
+
 Create a script at `scripts/lint-openapi.ts`:
 
 ```ts
@@ -760,7 +795,9 @@ type SpectralPluginOptions = {
     sinks?: OpenApiLintSink[]
   }
   source?: {
+    /** Public OpenAPI JSON route. Defaults to '/openapi/json'. Mount @elysiajs/openapi or serve an equivalent route yourself. */
     specPath?: string
+    /** Optional base URL fallback when the OpenAPI document is only reachable over HTTP. */
     baseUrl?: string
   }
   /**
@@ -1000,7 +1037,7 @@ Example successful response:
 - 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
+- missing OpenAPI generator / missing OpenAPI JSON route, 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
@@ -1022,6 +1059,8 @@ The convenience options compile down to built-in sinks so the current API stays
 
 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`.
 
+`@elysiajs/openapi` is the default and recommended source for that document, but it is not the only supported source. Any equivalent OpenAPI JSON route works as long as `source.specPath` and, when needed, `source.baseUrl` point to it.
+
 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
@@ -1057,4 +1096,4 @@ Production-grade linting needs more than a pass/fail boolean. The runtime tracks
 
 ### Project status
 
-The package is actively developed toward a stable `v1`. Milestones 0.2 through 0.6 are complete. Ongoing work is tracked in [roadmap.md](../../roadmap.md).
+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).

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-CyJXdIRT.mjs";
+import { a as createOpenApiLintRuntime, c as LoadedRuleset, d as RulesetResolverContext, f as RulesetResolverInput, g as lintOpenApi, h as loadRuleset, i as OpenApiLintArtifactWriteError, l as ResolvedRulesetCandidate, m as loadResolvedRuleset, n as enforceThreshold, o as RulesetLoadError, p as defaultRulesetResolvers, r as shouldFail, s as LoadResolvedRulesetOptions, t as OpenApiLintThresholdError, u as RulesetResolver } from "../index-DzJWrqPA.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,5 @@
-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-BLJeXQ15.mjs";
+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 { 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-CyJXdIRT.d.mts → index-DzJWrqPA.d.mts}

@@ -1,5 +1,5 @@
-import { RulesetDefinition } from "@stoplight/spectral-core";
 import { AnyElysia } from "elysia";
+import { RulesetDefinition } from "@stoplight/spectral-core";
 
 //#region src/types.d.ts
 type PresetName = 'recommended' | 'server' | 'strict';
@@ -147,14 +147,16 @@ type LoadResolvedRulesetOptions = {
   mergeAutodiscoveredWithDefault?: boolean; /** Override the ruleset used as the merge base for autodiscovery and the fallback when no ruleset is configured. Defaults to the package default (recommended preset). */
   defaultRuleset?: RulesetDefinition;
 };
+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/ruleset-load-error.d.ts
 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/runtime.d.ts
 declare const createOpenApiLintRuntime: (options?: SpectralPluginOptions) => OpenApiLintRuntime;
@@ -173,4 +175,4 @@ declare class OpenApiLintThresholdError extends Error {
 declare const shouldFail: (result: LintRunResult, threshold: SeverityThreshold) => boolean;
 declare const enforceThreshold: (result: LintRunResult, threshold: SeverityThreshold) => void;
 //#endregion
-export { SpectralLogger as A, OpenApiLintRuntime as C, OpenApiLintSinkContext as D, OpenApiLintSink as E, StartupLintMode as M, PresetName as O, OpenApiLintArtifacts as S, OpenApiLintRuntimeStatus as T, ArtifactWriteFailureMode as _, createOpenApiLintRuntime as a, LintRunSource as b, ResolvedRulesetCandidate as c, RulesetResolverContext as d, RulesetResolverInput as f, lintOpenApi as g, loadRuleset as h, OpenApiLintArtifactWriteError as i, SpectralPluginOptions as j, SeverityThreshold as k, RulesetLoadError as l, loadResolvedRuleset as m, enforceThreshold as n, LoadResolvedRulesetOptions as o, defaultRulesetResolvers as p, shouldFail as r, LoadedRuleset as s, OpenApiLintThresholdError as t, RulesetResolver as u, LintFinding as v, OpenApiLintRuntimeFailure as w, LintSeverity as x, LintRunResult as y };
+export { SpectralLogger as A, OpenApiLintRuntime as C, OpenApiLintSinkContext as D, OpenApiLintSink as E, StartupLintMode as M, PresetName as O, OpenApiLintArtifacts as S, OpenApiLintRuntimeStatus as T, ArtifactWriteFailureMode as _, createOpenApiLintRuntime as a, LintRunSource as b, LoadedRuleset as c, RulesetResolverContext as d, RulesetResolverInput as f, lintOpenApi as g, loadRuleset as h, OpenApiLintArtifactWriteError as i, SpectralPluginOptions as j, SeverityThreshold as k, ResolvedRulesetCandidate as l, loadResolvedRuleset as m, enforceThreshold as n, RulesetLoadError as o, defaultRulesetResolvers as p, shouldFail as r, LoadResolvedRulesetOptions as s, OpenApiLintThresholdError as t, RulesetResolver as u, LintFinding as v, OpenApiLintRuntimeFailure as w, LintSeverity as x, LintRunResult as y };

package/dist/index.d.mts

@@ -1,6 +1,6 @@
-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-CyJXdIRT.mjs";
-import { RulesetDefinition } from "@stoplight/spectral-core";
+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 LoadedRuleset, d as RulesetResolverContext, f as RulesetResolverInput, i as OpenApiLintArtifactWriteError, j as SpectralPluginOptions, k as SeverityThreshold, l as ResolvedRulesetCandidate, n as enforceThreshold, o as RulesetLoadError, r as shouldFail, s as LoadResolvedRulesetOptions, t as OpenApiLintThresholdError, u as RulesetResolver, v as LintFinding, w as OpenApiLintRuntimeFailure, x as LintSeverity, y as LintRunResult } from "./index-DzJWrqPA.mjs";
 import { Elysia } from "elysia";
+import { RulesetDefinition } from "@stoplight/spectral-core";
 
 //#region src/plugin.d.ts
 declare const spectralPlugin: (options?: SpectralPluginOptions) => Elysia<"", {
@@ -72,4 +72,9 @@ declare const strict: RulesetDefinition;
 //#region src/presets/index.d.ts
 declare const presets: Record<PresetName, RulesetDefinition>;
 //#endregion
-export { ArtifactWriteFailureMode, LintFinding, LintRunResult, LintRunSource, LintSeverity, LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintArtifacts, OpenApiLintRuntime, OpenApiLintRuntimeFailure, OpenApiLintRuntimeStatus, OpenApiLintSink, OpenApiLintSinkContext, OpenApiLintThresholdError, PresetName, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, SeverityThreshold, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };
+//#region src/index.d.ts
+declare const loadRuleset: (input?: RulesetResolverInput, baseDirOrOptions?: string | LoadResolvedRulesetOptions) => Promise<RulesetDefinition>;
+declare const loadResolvedRuleset: (input?: RulesetResolverInput, baseDirOrOptions?: string | LoadResolvedRulesetOptions) => Promise<LoadedRuleset>;
+declare const lintOpenApi: (spec: Record<string, unknown>, ruleset: RulesetDefinition) => Promise<LintRunResult>;
+//#endregion
+export { ArtifactWriteFailureMode, LintFinding, LintRunResult, LintRunSource, LintSeverity, type LoadResolvedRulesetOptions, type LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintArtifacts, OpenApiLintRuntime, OpenApiLintRuntimeFailure, OpenApiLintRuntimeStatus, OpenApiLintSink, OpenApiLintSinkContext, OpenApiLintThresholdError, PresetName, type ResolvedRulesetCandidate, RulesetLoadError, type RulesetResolver, type RulesetResolverContext, type RulesetResolverInput, SeverityThreshold, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };

package/dist/index.mjs

@@ -1,4 +1,7 @@
-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-BLJeXQ15.mjs";
+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 { 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";
 //#region \0inline-text:3.mjs
 var _inline_text_3_default = "(() => {\n  const THEME_KEY = 'elysia-spectral-theme';\n  const THEMES = ['astro', 'elysia', 'tron', '808'];\n  let stored = null;\n  try {\n    stored = localStorage.getItem(THEME_KEY);\n  } catch {}\n  const initial = THEMES.includes(stored) ? stored : 'astro';\n  document.documentElement.dataset.theme = initial;\n\n  const themeSel = document.querySelector('[data-theme-switcher]');\n  if (themeSel) {\n    themeSel.value = initial;\n    themeSel.addEventListener('change', () => {\n      const next = THEMES.includes(themeSel.value) ? themeSel.value : 'astro';\n      document.documentElement.dataset.theme = next;\n      try {\n        localStorage.setItem(THEME_KEY, next);\n      } catch {}\n    });\n  }\n\n  const rel = (iso) => {\n    const t = Date.parse(iso);\n    if (Number.isNaN(t)) return '';\n    const s = Math.round((Date.now() - t) / 1000);\n    if (s < 60) return s + 's ago';\n    if (s < 3600) return Math.round(s / 60) + 'm ago';\n    if (s < 86400) return Math.round(s / 3600) + 'h ago';\n    return Math.round(s / 86400) + 'd ago';\n  };\n  for (const el of document.querySelectorAll('[data-relative-time]')) {\n    el.textContent = rel(el.getAttribute('data-relative-time'));\n  }\n\n  const rows = Array.from(document.querySelectorAll('[data-findings] tr'));\n  const search = document.querySelector('[data-search]');\n  const empty = document.querySelector('[data-empty-findings]');\n  const chips = Array.from(document.querySelectorAll('[data-filter]'));\n  let activeSeverity = 'all';\n  let query = '';\n\n  const apply = () => {\n    let visible = 0;\n    for (const tr of rows) {\n      const sev = tr.getAttribute('data-severity');\n      const hay = tr.getAttribute('data-haystack') || '';\n      const sevOk = activeSeverity === 'all' || sev === activeSeverity;\n      const qOk = !query || hay.includes(query);\n      const show = sevOk && qOk;\n      tr.classList.toggle('is-hidden', !show);\n      if (show) visible += 1;\n    }\n    if (empty)\n      empty.classList.toggle('hidden', visible !== 0 || rows.length === 0);\n  };\n\n  for (const chip of chips) {\n    const select = () => {\n      activeSeverity = chip.getAttribute('data-filter') || 'all';\n      for (const c of chips) c.classList.toggle('is-active', c === chip);\n      apply();\n    };\n    chip.addEventListener('click', select);\n    chip.addEventListener('keydown', (e) => {\n      if (e.key === 'Enter' || e.key === ' ') {\n        e.preventDefault();\n        select();\n      }\n    });\n  }\n\n  if (search) {\n    search.addEventListener('input', () => {\n      query = search.value.trim().toLowerCase();\n      apply();\n    });\n  }\n\n  for (const btn of document.querySelectorAll('[data-copy]')) {\n    btn.addEventListener('click', async () => {\n      const value = btn.getAttribute('data-copy') || '';\n      try {\n        await navigator.clipboard.writeText(value);\n        btn.classList.add('copied');\n        btn.textContent = 'copied';\n        setTimeout(() => {\n          btn.classList.remove('copied');\n          btn.textContent = 'copy';\n        }, 1200);\n      } catch {}\n    });\n  }\n\n  document.addEventListener('keydown', (e) => {\n    if (\n      e.target &&\n      (e.target.tagName === 'INPUT' ||\n        e.target.tagName === 'TEXTAREA' ||\n        e.target.tagName === 'SELECT')\n    )\n      return;\n    if (e.key === 'r') {\n      const link = document.querySelector('[data-refresh]');\n      if (link) link.click();\n    }\n    if (e.key === '/' && search) {\n      e.preventDefault();\n      search.focus();\n    }\n  });\n})();\n";
@@ -239,4 +242,15 @@ const spectralPlugin = (options = {}) => {
 	return plugin;
 };
 //#endregion
-export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };
+//#region src/index.ts
+const loadRuleset = async (input, baseDirOrOptions = process.cwd()) => {
+	return await (await import("./load-ruleset-CiikrzWx.mjs").then((n) => n.i)).loadRuleset(input, baseDirOrOptions);
+};
+const loadResolvedRuleset = async (input, baseDirOrOptions = process.cwd()) => {
+	return await (await import("./load-ruleset-CiikrzWx.mjs").then((n) => n.i)).loadResolvedRuleset(input, baseDirOrOptions);
+};
+const lintOpenApi = async (spec, ruleset) => {
+	return await (await import("./lint-openapi-D76sC7S5.mjs").then((n) => n.n)).lintOpenApi(spec, ruleset);
+};
+//#endregion
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };

package/dist/lint-openapi-D76sC7S5.mjs

@@ -0,0 +1,122 @@
+import { t as __exportAll } from "./rolldown-runtime-wcPFST8Q.mjs";
+import { a as getSpectralConstructor, r as loadRuleset } from "./load-ruleset-CiikrzWx.mjs";
+//#region src/core/finding-guidance.ts
+const guidanceByCode = {
+	"elysia-operation-summary": "Add detail.summary to the Elysia route options so generated docs and clients have a short operation label.",
+	"elysia-operation-tags": "Add detail.tags with at least one stable tag, for example ['Users'] or ['Dev'].",
+	"operation-description": "Add detail.description with a short user-facing explanation of what the route does.",
+	"operation-tags": "Add a non-empty detail.tags array on the route so the OpenAPI operation is grouped consistently.",
+	"operation-operationId": "Add detail.operationId with a unique camelCase identifier so generated clients and SDKs have stable method names.",
+	"operation-success-response": "Add at least one 2xx response schema to the route, for example response: { 200: t.Object(...) }.",
+	"oas3-api-servers": "Add a servers array to the OpenAPI documentation config with at least one base URL.",
+	"info-contact": "Add an info.contact object to the OpenAPI documentation config with a name and url or email.",
+	"rfc9457-problem-details": "Add an \"application/problem+json\" content entry to the error response. See RFC 9457 for the Problem Details schema."
+};
+const getFindingRecommendation = (code, message) => {
+	const direct = guidanceByCode[code];
+	if (direct) return direct;
+	if (code === "oas3-schema" && message.includes("required property \"responses\"")) return "Add a response schema to the route, for example response: { 200: t.Object(...) } or response: { 200: t.Array(...) }.";
+	if (code.startsWith("operation-")) return "Add the missing operation metadata under detail on the Elysia route options.";
+};
+//#endregion
+//#region src/core/normalize-findings.ts
+const httpMethods = new Set([
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+]);
+const normalizeFindings = (diagnostics, spec) => {
+	const findings = diagnostics.map((diagnostic) => normalizeFinding(diagnostic, spec));
+	const summary = findings.reduce((current, finding) => {
+		current[finding.severity] += 1;
+		current.total += 1;
+		return current;
+	}, {
+		error: 0,
+		warn: 0,
+		info: 0,
+		hint: 0,
+		total: 0
+	});
+	return {
+		ok: summary.error === 0,
+		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		source: "manual",
+		failOn: "error",
+		durationMs: null,
+		summary,
+		findings
+	};
+};
+const normalizeFinding = (diagnostic, spec) => {
+	const path = [...diagnostic.path];
+	const finding = {
+		code: String(diagnostic.code),
+		message: diagnostic.message,
+		severity: toLintSeverity(diagnostic.severity),
+		path,
+		documentPointer: toDocumentPointer(path)
+	};
+	const recommendation = getFindingRecommendation(String(diagnostic.code), diagnostic.message);
+	if (recommendation) finding.recommendation = recommendation;
+	if (diagnostic.source !== void 0) finding.source = diagnostic.source;
+	if (diagnostic.range) finding.range = {
+		start: diagnostic.range.start,
+		end: diagnostic.range.end
+	};
+	const operation = inferOperation(path, spec);
+	if (operation) finding.operation = operation;
+	return finding;
+};
+const toLintSeverity = (severity) => {
+	switch (severity) {
+		case 0: return "error";
+		case 1: return "warn";
+		case 2: return "info";
+		default: return "hint";
+	}
+};
+const toDocumentPointer = (path) => {
+	if (path.length === 0) return "";
+	return `/${path.map((segment) => String(segment).replace(/~/g, "~0").replace(/\//g, "~1")).join("/")}`;
+};
+const inferOperation = (path, spec) => {
+	if (path[0] !== "paths") return;
+	const routePath = typeof path[1] === "string" ? path[1] : void 0;
+	const method = typeof path[2] === "string" && httpMethods.has(path[2]) ? path[2] : void 0;
+	if (!routePath && !method) return;
+	const operationRecord = routePath && method ? getNestedValue(spec, [
+		"paths",
+		routePath,
+		method
+	]) : void 0;
+	const operation = {};
+	if (routePath !== void 0) operation.path = routePath;
+	if (method !== void 0) operation.method = method;
+	if (operationRecord && typeof operationRecord === "object" && "operationId" in operationRecord) operation.operationId = String(operationRecord.operationId);
+	return operation;
+};
+const getNestedValue = (value, path) => {
+	let current = value;
+	for (const segment of path) {
+		if (current === null || typeof current !== "object") return;
+		current = current[segment];
+	}
+	return current;
+};
+//#endregion
+//#region src/core/lint-openapi.ts
+var lint_openapi_exports = /* @__PURE__ */ __exportAll({ lintOpenApi: () => lintOpenApi });
+const lintOpenApi = async (spec, ruleset) => {
+	const [Spectral, resolvedRuleset] = await Promise.all([getSpectralConstructor(), loadRuleset(ruleset, { baseDir: process.cwd() })]);
+	const spectral = new Spectral();
+	spectral.setRuleset(resolvedRuleset);
+	return normalizeFindings(await spectral.run(spec, { ignoreUnknownFormat: false }), spec);
+};
+//#endregion
+export { lint_openapi_exports as n, lintOpenApi as t };

package/dist/load-ruleset-CiikrzWx.mjs

@@ -0,0 +1,301 @@
+import { t as __exportAll } from "./rolldown-runtime-wcPFST8Q.mjs";
+import { t as RulesetLoadError } from "./ruleset-load-error-CogUOC7W.mjs";
+import { t as recommended } from "./recommended-DgrTqq-3.mjs";
+import path from "node:path";
+import { access, readFile } from "node:fs/promises";
+import YAML from "yaml";
+import { pathToFileURL } from "node:url";
+//#region src/rulesets/default-ruleset.ts
+const defaultRuleset = recommended;
+//#endregion
+//#region src/core/stoplight-runtime.ts
+let runtimeBindingsPromise = null;
+const loadStoplightRuntimeBindings = async () => {
+	const [spectralCore, { default: spectralFunctions }, { default: spectralRulesets }] = await Promise.all([
+		import("@stoplight/spectral-core"),
+		import("@stoplight/spectral-functions"),
+		import("@stoplight/spectral-rulesets")
+	]);
+	const { alphabetical, casing, defined, enumeration, falsy, length, or, pattern, schema, truthy, undefined: undefinedFunction, unreferencedReusableObject, xor } = spectralFunctions;
+	const { oas } = spectralRulesets;
+	return {
+		Spectral: spectralCore.Spectral,
+		extendsMap: { "spectral:oas": oas },
+		functionMap: {
+			alphabetical,
+			casing,
+			defined,
+			enumeration,
+			falsy,
+			length,
+			or,
+			pattern,
+			schema,
+			truthy,
+			undefined: undefinedFunction,
+			unreferencedReusableObject,
+			xor
+		}
+	};
+};
+const getStoplightRuntimeBindings = async () => {
+	if (runtimeBindingsPromise === null) runtimeBindingsPromise = loadStoplightRuntimeBindings();
+	return await runtimeBindingsPromise;
+};
+const getBuiltInFunctionMap = async () => (await getStoplightRuntimeBindings()).functionMap;
+const getExtendsMap = async () => (await getStoplightRuntimeBindings()).extendsMap;
+const getSpectralConstructor = async () => (await getStoplightRuntimeBindings()).Spectral;
+//#endregion
+//#region src/core/load-ruleset.ts
+var load_ruleset_exports = /* @__PURE__ */ __exportAll({
+	defaultRulesetResolvers: () => defaultRulesetResolvers,
+	loadResolvedRuleset: () => loadResolvedRuleset,
+	loadRuleset: () => loadRuleset
+});
+const autodiscoverRulesetFilenames = [
+	"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"
+];
+const loadRuleset = async (input, baseDirOrOptions = process.cwd()) => {
+	return (await loadResolvedRuleset(input, baseDirOrOptions)).ruleset;
+};
+const loadResolvedRuleset = async (input, baseDirOrOptions = process.cwd()) => {
+	const options = normalizeLoadResolvedRulesetOptions(baseDirOrOptions);
+	const context = {
+		baseDir: options.baseDir,
+		defaultRuleset: options.defaultRuleset,
+		mergeAutodiscoveredWithDefault: options.mergeAutodiscoveredWithDefault
+	};
+	for (const resolver of options.resolvers) {
+		const loaded = await resolver(input, context);
+		if (loaded) {
+			const normalized = { ruleset: await normalizeRulesetDefinition(loaded.ruleset) };
+			if (loaded.source) normalized.source = loaded.source;
+			return normalized;
+		}
+	}
+	if (input === void 0) return { ruleset: await normalizeRulesetDefinition(options.defaultRuleset) };
+	throw new RulesetLoadError("Ruleset input could not be resolved.");
+};
+const normalizeLoadResolvedRulesetOptions = (value) => {
+	if (typeof value === "string") return {
+		baseDir: value,
+		resolvers: defaultRulesetResolvers,
+		mergeAutodiscoveredWithDefault: true,
+		defaultRuleset
+	};
+	return {
+		baseDir: value.baseDir ?? process.cwd(),
+		resolvers: value.resolvers ?? defaultRulesetResolvers,
+		mergeAutodiscoveredWithDefault: value.mergeAutodiscoveredWithDefault ?? true,
+		defaultRuleset: value.defaultRuleset ?? defaultRuleset
+	};
+};
+const resolveAutodiscoveredRuleset = async (input, context) => {
+	if (input !== void 0) return;
+	const autodiscoveredPath = await findAutodiscoveredRulesetPath(context.baseDir);
+	if (!autodiscoveredPath) return;
+	const loaded = await loadResolvedPathRuleset(autodiscoveredPath, context);
+	if (!context.mergeAutodiscoveredWithDefault) return {
+		...loaded,
+		source: {
+			path: autodiscoveredPath,
+			autodiscovered: true,
+			mergedWithDefault: false
+		}
+	};
+	return {
+		ruleset: mergeRulesets(context.defaultRuleset, loaded.ruleset),
+		source: {
+			path: autodiscoveredPath,
+			autodiscovered: true,
+			mergedWithDefault: true
+		}
+	};
+};
+const resolvePathRuleset = async (input, context) => {
+	if (typeof input !== "string") return;
+	return await loadResolvedPathRuleset(input, context);
+};
+const resolveInlineRuleset = async (input) => {
+	if (input === void 0 || typeof input === "string") return;
+	return { ruleset: input };
+};
+const defaultRulesetResolvers = [
+	resolveAutodiscoveredRuleset,
+	resolvePathRuleset,
+	resolveInlineRuleset
+];
+const loadResolvedPathRuleset = async (inputPath, context) => {
+	const resolvedPath = path.resolve(context.baseDir, inputPath);
+	if (isYamlRulesetPath(resolvedPath)) return {
+		ruleset: await loadYamlRuleset(resolvedPath),
+		source: {
+			path: inputPath,
+			autodiscovered: false,
+			mergedWithDefault: false
+		}
+	};
+	if (!isModuleRulesetPath(resolvedPath)) throw new RulesetLoadError(`Unsupported ruleset path: ${inputPath}. Supported local rulesets are .yaml, .yml, .js, .mjs, .cjs, .ts, .mts, and .cts.`);
+	return {
+		ruleset: await loadModuleRuleset(resolvedPath),
+		source: {
+			path: inputPath,
+			autodiscovered: false,
+			mergedWithDefault: false
+		}
+	};
+};
+const findAutodiscoveredRulesetPath = async (baseDir) => {
+	for (const filename of autodiscoverRulesetFilenames) {
+		const candidatePath = path.resolve(baseDir, filename);
+		try {
+			await access(candidatePath);
+			return `./${filename}`;
+		} catch (error) {
+			if (error.code !== "ENOENT") throw error;
+		}
+	}
+};
+const loadYamlRuleset = async (resolvedPath) => {
+	let fileContents;
+	try {
+		fileContents = await readFile(resolvedPath, "utf8");
+	} catch (error) {
+		throw new RulesetLoadError(`Unable to read ruleset at ${resolvedPath}.`, { cause: error });
+	}
+	let parsed;
+	try {
+		parsed = YAML.parse(fileContents);
+	} catch (error) {
+		throw new RulesetLoadError(`Unable to parse YAML ruleset at ${resolvedPath}.`, { cause: error });
+	}
+	return parsed;
+};
+const loadModuleRuleset = async (resolvedPath) => {
+	let imported;
+	try {
+		imported = await import(pathToFileURL(resolvedPath).href);
+	} catch (error) {
+		throw new RulesetLoadError(`Unable to import module ruleset at ${resolvedPath}.`, { cause: error });
+	}
+	const resolvedRuleset = resolveModuleRulesetValue(imported);
+	if (resolvedRuleset === void 0) throw new RulesetLoadError(`Module ruleset at ${resolvedPath} must export a ruleset as the default export or a named "ruleset" export.`);
+	return await normalizeRulesetDefinition(resolvedRuleset, {
+		...await getBuiltInFunctionMap(),
+		...resolveModuleFunctions(imported)
+	});
+};
+const resolveModuleRulesetValue = (imported) => {
+	if (!isRecord(imported)) return;
+	if ("default" in imported) return imported.default;
+	if ("ruleset" in imported) return imported.ruleset;
+};
+const resolveModuleFunctions = (imported) => {
+	if (!isRecord(imported) || !("functions" in imported)) return {};
+	const { functions } = imported;
+	if (!isRecord(functions)) throw new RulesetLoadError("Module ruleset \"functions\" export must be an object map of function names to Spectral functions.");
+	const entries = Object.entries(functions).filter(([, value]) => typeof value === "function");
+	return Object.fromEntries(entries);
+};
+const isYamlRulesetPath = (value) => value.endsWith(".yaml") || value.endsWith(".yml");
+const isModuleRulesetPath = (value) => value.endsWith(".js") || value.endsWith(".mjs") || value.endsWith(".cjs") || value.endsWith(".ts") || value.endsWith(".mts") || value.endsWith(".cts");
+const normalizeRulesetDefinition = async (input, availableFunctions) => {
+	if (!isRecord(input)) throw new RulesetLoadError("Ruleset must be an object.");
+	const resolvedAvailableFunctions = availableFunctions ?? await getBuiltInFunctionMap();
+	const normalized = { ...input };
+	if ("extends" in normalized) normalized.extends = await normalizeExtends(normalized.extends);
+	if ("rules" in normalized) normalized.rules = await normalizeRules(normalized.rules, resolvedAvailableFunctions);
+	return normalized;
+};
+const mergeRuleEntry = (base, override) => {
+	if (!isRecord(override)) return override;
+	if ("given" in override || "then" in override) return override;
+	if (isRecord(base) && ("given" in base || "then" in base)) return {
+		...base,
+		...override
+	};
+	const keys = Object.keys(override);
+	if (keys.length === 1 && keys[0] === "severity") return override.severity;
+	return override;
+};
+const mergeRulesets = (baseRuleset, overrideRuleset) => {
+	const mergedBase = baseRuleset;
+	const mergedOverride = overrideRuleset;
+	const baseRules = isRecord(mergedBase.rules) ? mergedBase.rules : {};
+	const overrideRules = isRecord(mergedOverride.rules) ? mergedOverride.rules : {};
+	const mergedRules = { ...baseRules };
+	for (const [name, overrideRule] of Object.entries(overrideRules)) mergedRules[name] = mergeRuleEntry(baseRules[name], overrideRule);
+	const baseExtends = toExtendsArray(mergedBase.extends);
+	const overrideExtends = toExtendsArray(mergedOverride.extends);
+	const mergedExtends = [...baseExtends, ...overrideExtends];
+	const merged = {
+		...mergedBase,
+		...mergedOverride
+	};
+	delete merged.extends;
+	delete merged.rules;
+	if (mergedExtends.length > 0) merged.extends = mergedExtends;
+	if (Object.keys(mergedRules).length > 0) merged.rules = mergedRules;
+	return merged;
+};
+const toExtendsArray = (value) => {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? [...value] : [value];
+};
+const normalizeExtends = async (value) => {
+	if (typeof value === "string") return await resolveExtendsEntry(value);
+	if (!Array.isArray(value)) return value;
+	return await Promise.all(value.map(async (entry) => {
+		if (typeof entry === "string") return await resolveExtendsEntry(entry);
+		if (Array.isArray(entry) && entry.length >= 1 && typeof entry[0] === "string") return [await resolveExtendsEntry(entry[0]), entry[1]];
+		return entry;
+	}));
+};
+const resolveExtendsEntry = async (value) => {
+	const resolved = (await getExtendsMap())[value];
+	if (!resolved) throw new RulesetLoadError(`Unsupported ruleset extend target: "${value}". Supported extend targets: spectral:oas.`);
+	return resolved;
+};
+const normalizeRules = async (value, availableFunctions) => {
+	if (!isRecord(value)) return value;
+	const entries = await Promise.all(Object.entries(value).map(async ([ruleName, ruleValue]) => [ruleName, await normalizeRule(ruleValue, availableFunctions)]));
+	return Object.fromEntries(entries);
+};
+const normalizeRule = async (value, availableFunctions) => {
+	if (!isRecord(value)) return value;
+	const normalized = { ...value };
+	if ("then" in normalized) normalized.then = await normalizeThen(normalized.then, availableFunctions);
+	return normalized;
+};
+const normalizeThen = async (value, availableFunctions) => {
+	if (Array.isArray(value)) return await Promise.all(value.map((entry) => normalizeThenEntry(entry, availableFunctions)));
+	return await normalizeThenEntry(value, availableFunctions);
+};
+const normalizeThenEntry = async (value, availableFunctions) => {
+	if (!isRecord(value)) return value;
+	const normalized = { ...value };
+	if (typeof normalized.function === "string") {
+		const resolved = availableFunctions[normalized.function];
+		if (!resolved) throw new RulesetLoadError(`Unsupported Spectral function: ${String(normalized.function)}.`);
+		normalized.function = resolved;
+	}
+	return normalized;
+};
+const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+//#endregion
+export { getSpectralConstructor as a, load_ruleset_exports as i, loadResolvedRuleset as n, loadRuleset as r, defaultRulesetResolvers as t };