@opsydyn/elysia-spectral 0.5.1 → 0.5.2

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [0.5.2](https://github.com/opsydyn/elysia-spectral/compare/v0.5.1...v0.5.2) (2026-04-15)
+
+
+### Bug Fixes
+
+* replace export * with named exports in core/index.ts for stable public API ([d0ef1c9](https://github.com/opsydyn/elysia-spectral/commit/d0ef1c95618ecd5a83e8224f2ba831b226a7ab38))
+
 ## [0.5.1](https://github.com/opsydyn/elysia-spectral/compare/v0.5.0...v0.5.1) (2026-04-15)
 
 

package/README.md

@@ -565,17 +565,19 @@ git commit -m "chore: add openapi snapshot"
 
 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.
 
-### Generate a typed client with openapi-ts
+### Generate a typed client
 
-Use the committed OpenAPI snapshot as input to [`openapi-ts`](https://openapi-ts.dev) to keep a generated TypeScript client in sync with the API surface.
+**If your consumer is a TypeScript project that can import from your Elysia app, use [Eden Treaty](https://elysiajs.com/eden/treaty/overview) instead.** It derives types directly from the app instance with no codegen, no snapshot, and no drift.
 
-1. Install `openapi-ts`:
+```ts
+import { treaty } from '@elysiajs/eden'
+import type { App } from '../server'
 
-```bash
-bun add -d @hey-api/openapi-ts
+const client = treaty<App>('localhost:3000')
+// fully typed — zero codegen
 ```
 
-2. Add a codegen script to `package.json`:
+For vendor-agnostic consumers — cross-repo TypeScript, non-TypeScript clients, or a published SDK — use the committed OpenAPI snapshot as input to [`openapi-ts`](https://openapi-ts.dev):
 
 ```json
 {
@@ -585,7 +587,7 @@ bun add -d @hey-api/openapi-ts
 }
 ```
 
-3. Chain it after the lint step in CI:
+Chain it after the lint step in CI and guard against drift:
 
 ```yaml
 - name: Lint OpenAPI spec
@@ -598,7 +600,7 @@ bun add -d @hey-api/openapi-ts
   run: git diff --exit-code src/generated/client/
 ```
 
-The lint gate runs first — if the spec is invalid the codegen step never runs. The drift check ensures the committed client always matches the current spec.
+The lint gate runs first — if the spec is invalid the codegen step never runs.
 
 ### Work on this repository locally
 
@@ -630,66 +632,38 @@ That example uses `startup.mode: 'report'`, so the app still boots while the pac
 ### Package API
 
 ```ts
-type PresetName = 'recommended' | 'server' | 'strict'
+// ── Vocabulary types ──────────────────────────────────────────────────────────
 
+type PresetName = 'recommended' | 'server' | 'strict'
+type LintSeverity = 'error' | 'warn' | 'info' | 'hint'
 type SeverityThreshold = 'error' | 'warn' | 'info' | 'hint' | 'never'
-
 type StartupLintMode = 'enforce' | 'report' | 'off'
-
+type LintRunSource = 'startup' | 'healthcheck' | 'manual'
 type ArtifactWriteFailureMode = 'warn' | 'error'
+type OpenApiLintRuntimeStatus = 'idle' | 'running' | 'passed' | 'failed'
 
-type OpenApiLintArtifacts = {
-  jsonReportPath?: string
-  junitReportPath?: string
-  sarifReportPath?: string
-  specSnapshotPath?: string
-  brunoCollectionPath?: string
-}
-
-type OpenApiLintSink = {
-  name: string
-  write: (
-    result: LintRunResult,
-    context: {
-      spec: Record<string, unknown>
-      logger: SpectralLogger
-    }
-  ) => undefined | Partial<OpenApiLintArtifacts> | Promise<undefined | Partial<OpenApiLintArtifacts>>
-}
-
-type RulesetResolver = (
-  input: string | RulesetDefinition | Record<string, unknown> | undefined,
-  context: {
-    baseDir: string
-    defaultRuleset: RulesetDefinition
-    mergeAutodiscoveredWithDefault: boolean
-  }
-) => Promise<LoadedRuleset | undefined>
-
-type LoadResolvedRulesetOptions = {
-  baseDir?: string
-  resolvers?: RulesetResolver[]
-  mergeAutodiscoveredWithDefault?: boolean
-  /** Override the base ruleset used for autodiscovery merging and the fallback when no ruleset is configured. */
-  defaultRuleset?: RulesetDefinition
-}
+// ── Plugin options ────────────────────────────────────────────────────────────
 
 type SpectralPluginOptions = {
   /** First-party governance preset. Sets the base ruleset and autodiscovery merge target. */
   preset?: PresetName
   /** Custom ruleset path, object, or inline definition. Merged on top of preset when both are set. */
   ruleset?: string | RulesetDefinition | Record<string, unknown>
+  /** Severity level at which the lint run is considered failed. Defaults to 'error'. */
   failOn?: SeverityThreshold
   healthcheck?: false | { path?: string }
   output?: {
+    /** Print findings to the console. Default: true. */
     console?: boolean
     jsonReportPath?: string
     junitReportPath?: string
     sarifReportPath?: string
+    /** true derives the path from the consuming app's package name. */
     specSnapshotPath?: string | true
     /** .yml/.yaml → OpenCollection YAML (Bruno v3+), .json → Bruno collection JSON */
     brunoCollectionPath?: string
     pretty?: boolean
+    /** Whether artifact write failures throw or warn. Default: 'warn'. */
     artifactWriteFailures?: ArtifactWriteFailureMode
     sinks?: OpenApiLintSink[]
   }
@@ -697,16 +671,160 @@ type SpectralPluginOptions = {
     specPath?: string
     baseUrl?: string
   }
-  enabled?: boolean | ((env: Record<string, string | undefined>) => boolean)
+  /**
+   * Controls startup lint behaviour.
+   * startup.mode takes precedence over the legacy enabled option.
+   *   'enforce' — lint runs at startup and throws on threshold failure (default)
+   *   'report'  — lint runs at startup, prints findings, but never blocks boot
+   *   'off'     — startup lint is skipped entirely
+   */
   startup?: {
     mode?: StartupLintMode
   }
-  logger?: {
-    info: (message: string) => void
-    warn: (message: string) => void
-    error: (message: string) => void
+  /**
+   * Legacy enable flag. Prefer startup.mode for new code.
+   * false or () => false is equivalent to startup.mode: 'off'.
+   * The function form receives process.env for environment-based toggling.
+   */
+  enabled?: boolean | ((env: Record<string, string | undefined>) => boolean)
+  logger?: SpectralLogger
+}
+
+// ── Result types ──────────────────────────────────────────────────────────────
+
+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 = {
+  /** True when no findings meet or exceed the configured failOn threshold. */
+  ok: boolean
+  generatedAt: string
+  /** Where the lint run was triggered from. */
+  source: LintRunSource
+  summary: {
+    error: number
+    warn: number
+    info: number
+    hint: number
+    total: number
+  }
+  artifacts?: OpenApiLintArtifacts
+  findings: LintFinding[]
+}
+
+type OpenApiLintArtifacts = {
+  jsonReportPath?: string
+  junitReportPath?: string
+  sarifReportPath?: string
+  specSnapshotPath?: string
+  brunoCollectionPath?: string
+}
+
+type OpenApiLintRuntimeFailure = {
+  name: string
+  message: string
+  generatedAt: string
+}
+
+// ── Runtime ───────────────────────────────────────────────────────────────────
+
+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, source?: LintRunSource) => Promise<LintRunResult>
+}
+
+function createOpenApiLintRuntime(options?: SpectralPluginOptions): OpenApiLintRuntime
+
+// ── Extension points (advanced) ───────────────────────────────────────────────
+
+type SpectralLogger = {
+  info: (message: string) => void
+  warn: (message: string) => void
+  error: (message: string) => void
+}
+
+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 RulesetResolver = (
+  input: string | RulesetDefinition | Record<string, unknown> | undefined,
+  context: RulesetResolverContext,
+) => Promise<ResolvedRulesetCandidate | undefined>
+
+type RulesetResolverContext = {
+  baseDir: string
+  defaultRuleset: RulesetDefinition
+  mergeAutodiscoveredWithDefault: boolean
+}
+
+type ResolvedRulesetCandidate = {
+  ruleset: unknown
+  source?: LoadedRuleset['source']
+}
+
+type LoadedRuleset = {
+  ruleset: RulesetDefinition
+  source?: {
+    path: string
+    autodiscovered: boolean
+    mergedWithDefault: boolean
   }
 }
+
+type LoadResolvedRulesetOptions = {
+  baseDir?: string
+  resolvers?: RulesetResolver[]
+  mergeAutodiscoveredWithDefault?: boolean
+  /** Override the base ruleset used for autodiscovery merging and the fallback when no ruleset is configured. */
+  defaultRuleset?: RulesetDefinition
+}
+
+// ── Error classes ─────────────────────────────────────────────────────────────
+
+class OpenApiLintThresholdError extends Error {
+  readonly threshold: SeverityThreshold
+  readonly result: LintRunResult
+}
+
+class OpenApiLintArtifactWriteError extends Error {
+  readonly artifact: string
+  readonly cause: unknown
+}
+
+class RulesetLoadError extends Error {}
 ```
 
 ### Presets

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { _ as lintOpenApi, a as createOpenApiLintRuntime, c as LoadedRuleset, d as RulesetResolver, f as RulesetResolverContext, g as loadRuleset, h as loadResolvedRuleset, i as OpenApiLintArtifactWriteError, l as ResolvedRulesetCandidate, m as defaultRulesetResolvers, n as enforceThreshold, o as resolveStartupMode, p as RulesetResolverInput, r as shouldFail, s as LoadResolvedRulesetOptions, t as OpenApiLintThresholdError, u as RulesetLoadError } from "../index-B4fxn0G6.mjs";
-export { LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, resolveStartupMode, shouldFail };
+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";
+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, r as resolveStartupMode, t as OpenApiLintArtifactWriteError } from "../core-DTKNy6TU.mjs";
-export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, resolveStartupMode, shouldFail };
+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";
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, shouldFail };

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

@@ -157,7 +157,6 @@ declare class OpenApiLintArtifactWriteError extends Error {
   readonly cause: unknown;
   constructor(artifact: string, cause: unknown);
 }
-declare const resolveStartupMode: (options?: SpectralPluginOptions) => StartupLintMode;
 //#endregion
 //#region src/core/thresholds.d.ts
 declare class OpenApiLintThresholdError extends Error {
@@ -168,4 +167,4 @@ declare class OpenApiLintThresholdError extends Error {
 declare const shouldFail: (result: LintRunResult, threshold: SeverityThreshold) => boolean;
 declare const enforceThreshold: (result: LintRunResult, threshold: SeverityThreshold) => void;
 //#endregion
-export { SeverityThreshold as A, OpenApiLintArtifacts as C, OpenApiLintSink as D, OpenApiLintRuntimeStatus as E, SpectralPluginOptions as M, StartupLintMode as N, OpenApiLintSinkContext as O, LintSeverity as S, OpenApiLintRuntimeFailure as T, lintOpenApi as _, createOpenApiLintRuntime as a, LintRunResult as b, LoadedRuleset as c, RulesetResolver as d, RulesetResolverContext as f, loadRuleset as g, loadResolvedRuleset as h, OpenApiLintArtifactWriteError as i, SpectralLogger as j, PresetName as k, ResolvedRulesetCandidate as l, defaultRulesetResolvers as m, enforceThreshold as n, resolveStartupMode as o, RulesetResolverInput as p, shouldFail as r, LoadResolvedRulesetOptions as s, OpenApiLintThresholdError as t, RulesetLoadError as u, ArtifactWriteFailureMode as v, OpenApiLintRuntime as w, LintRunSource as x, LintFinding 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, 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 };

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { A as SeverityThreshold, C as OpenApiLintArtifacts, D as OpenApiLintSink, E as OpenApiLintRuntimeStatus, M as SpectralPluginOptions, N as StartupLintMode, O as OpenApiLintSinkContext, S as LintSeverity, T as OpenApiLintRuntimeFailure, _ as lintOpenApi, a as createOpenApiLintRuntime, b as LintRunResult, c as LoadedRuleset, d as RulesetResolver, f as RulesetResolverContext, g as loadRuleset, h as loadResolvedRuleset, i as OpenApiLintArtifactWriteError, j as SpectralLogger, k as PresetName, l as ResolvedRulesetCandidate, m as defaultRulesetResolvers, n as enforceThreshold, o as resolveStartupMode, p as RulesetResolverInput, r as shouldFail, s as LoadResolvedRulesetOptions, t as OpenApiLintThresholdError, u as RulesetLoadError, v as ArtifactWriteFailureMode, w as OpenApiLintRuntime, x as LintRunSource, y as LintFinding } from "./index-B4fxn0G6.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-11HnbLDN.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, 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, 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, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };

package/dist/index.mjs

@@ -82,4 +82,4 @@ const spectralPlugin = (options = {}) => {
 	return plugin;
 };
 //#endregion
-export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, resolveStartupMode, server, shouldFail, spectralPlugin, strict };
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, lintOpenApi, loadResolvedRuleset, loadRuleset, presets, recommended, server, shouldFail, spectralPlugin, strict };

package/package.json

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