@opsydyn/elysia-spectral 0.2.5 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [0.4.0](https://github.com/opsydyn/elysia-spectral/compare/v0.3.0...v0.4.0) (2026-04-15)
+
+
+### Features
+
+* add source metadata to LintRunResult ([bdd5a81](https://github.com/opsydyn/elysia-spectral/commit/bdd5a817c00b5fdccf4e1d27c8dbf4c6d4c36d2c))
+
+## [0.3.0](https://github.com/opsydyn/elysia-spectral/compare/v0.2.5...v0.3.0) (2026-04-14)
+
+
+### Features
+
+* add recommended, server, and strict governance presets ([692061e](https://github.com/opsydyn/elysia-spectral/commit/692061e23ba5735fc0ad1a8d1a9110ced1f869fe))
+
 ## [0.2.5](https://github.com/opsydyn/elysia-spectral/compare/v0.2.4...v0.2.5) (2026-04-14)
 
 

package/README.md

@@ -6,6 +6,13 @@
 
 Thin Elysia plugin that lints the OpenAPI document generated by `@elysiajs/openapi` with Spectral.
 
+## 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.
+
+- Official site: <https://elysiajs.com/>
+- `@elysiajs/openapi`: <https://elysiajs.com/plugins/openapi>
+
 ## What Is Spectral?
 
 Spectral is an open-source linter and style guide engine for API descriptions. It was built with OpenAPI, AsyncAPI, and JSON Schema in mind, and is commonly used to enforce API style guides, catch weak or inconsistent contract definitions, and improve the usefulness of generated API descriptions.
@@ -25,6 +32,12 @@ Official Spectral references:
 - Stoplight overview: <https://stoplight.io/open-source/spectral>
 - GitHub repository: <https://github.com/stoplightio/spectral>
 
+## Standards
+
+- RFC 9457 — Problem Details for HTTP APIs: <https://datatracker.ietf.org/doc/html/rfc9457>
+
+The `strict` preset enforces RFC 9457 by requiring that all 4xx and 5xx responses declare `application/problem+json` as their content type.
+
 This README is organized using the Diataxis documentation model:
 
 - Tutorial: learn by building a working setup
@@ -51,7 +64,7 @@ Current package scope:
 
 ### Add OpenAPI linting to an Elysia app
 
-This tutorial takes a minimal Elysia app and adds startup OpenAPI linting with a repo-level ruleset and JSON artifacts.
+This tutorial takes a minimal Elysia app and adds startup OpenAPI linting using the `strict` preset. The `strict` preset is the recommended starting point for teams shipping production APIs — it enforces summaries, descriptions, operation IDs, tags, server declarations, and RFC 9457 Problem Details on error responses.
 
 1. Install the dependencies.
 
@@ -63,24 +76,7 @@ bun add elysia @elysiajs/openapi @opsydyn/elysia-spectral
 npm install elysia @elysiajs/openapi @opsydyn/elysia-spectral
 ```
 
-2. Create a repo-level `spectral.yaml`.
-
-```yaml
-extends:
-  - spectral:oas
-
-rules:
-  operation-description:
-    severity: error
-
-  operation-tags:
-    severity: warn
-
-  elysia-operation-summary:
-    severity: error
-```
-
-3. Add `@elysiajs/openapi` and `spectralPlugin` to your app.
+2. Add `@elysiajs/openapi` and `spectralPlugin` to your app with the `strict` preset.
 
 ```ts
 import { Elysia, t } from 'elysia'
@@ -93,18 +89,19 @@ new Elysia()
       documentation: {
         info: {
           title: 'Example API',
-          version: '1.0.0'
+          version: '1.0.0',
+          contact: { name: 'API Team', url: 'https://example.com/support' }
         },
+        servers: [{ url: 'https://api.example.com' }],
         tags: [{ name: 'Users', description: 'User operations' }]
       }
     })
   )
   .use(
     spectralPlugin({
+      preset: 'strict',
       failOn: 'error',
-      startup: {
-        mode: 'enforce'
-      },
+      startup: { mode: 'enforce' },
       output: {
         console: true,
         jsonReportPath: './artifacts/openapi-lint.json',
@@ -113,36 +110,44 @@ new Elysia()
     })
   )
   .get('/users', () => [{ id: '1', name: 'Ada Lovelace' }], {
-    response: {
-      200: t.Array(
-        t.Object({
-          id: t.String(),
-          name: t.String()
-        })
-      )
-    },
     detail: {
       summary: 'List users',
-      description: 'Return all users.',
+      description: 'Return all registered users.',
       operationId: 'listUsers',
       tags: ['Users']
+    },
+    response: {
+      200: t.Array(
+        t.Object({ id: t.String(), name: t.String() })
+      ),
+      500: t.Object(
+        {
+          type: t.String(),
+          title: t.String(),
+          status: t.Number(),
+          detail: t.String()
+        },
+        { description: 'Internal server error (RFC 9457 Problem Details)' }
+      )
     }
   })
   .listen(3000)
 ```
 
-4. Start the app.
+The `strict` preset requires error responses to use `application/problem+json` (RFC 9457). The `500` response above satisfies that when `@elysiajs/openapi` generates the schema with the correct content type.
+
+3. Start the app.
 
 ```bash
 bun run src/index.ts
 ```
 
-5. Confirm the outcome.
+4. Confirm the outcome.
 
 - the app serves OpenAPI JSON at `/openapi/json`
-- the plugin lints that generated document during startup
-- a clean run prints Signale-style success and hype lines in the terminal
-- `./artifacts/openapi-lint.json` contains the lint result
+- the plugin lints that generated document during startup using the `strict` preset
+- a clean run prints a success banner in the terminal
+- `./artifacts/openapi-lint.json` contains the full lint result
 - `./<package-name>.open-api.json` contains the generated OpenAPI snapshot
 
 If startup fails, the terminal output includes:
@@ -152,6 +157,27 @@ If startup fails, the terminal output includes:
 - a fix hint when one is known
 - a spec reference in `open-api.json#/json/pointer` form
 
+### Choose a preset
+
+Three first-party presets are available. Import them directly or set `preset` in the plugin options.
+
+| Preset | Use case | elysia rules | description / operationId | servers | RFC 9457 |
+|---|---|---|---|---|---|
+| `recommended` | local dev, low friction | warn | — | off | — |
+| `server` | production API gate | error | warn | warn | — |
+| `strict` | full API governance | error | error | error | warn |
+
+```ts
+// simplest — preset string
+spectralPlugin({ preset: 'strict' })
+
+// or import the preset object and pass as ruleset
+import { strict } from '@opsydyn/elysia-spectral'
+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.
+
 ## How-to Guides
 
 ### Use a repo-level ruleset
@@ -400,29 +426,101 @@ spectralPlugin({
 
 Use `'warn'` for local development and `'error'` when artifact generation is required.
 
-### Run the runtime in CI or tests
+### Run the runtime in CI
+
+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.
+
+Create a script at `scripts/lint-openapi.ts`:
 
 ```ts
-import { Elysia } from 'elysia'
-import { openapi } from '@elysiajs/openapi'
+import { app } from '../src/app'
 import { createOpenApiLintRuntime } from '@opsydyn/elysia-spectral'
 
-const app = new Elysia().use(openapi())
-
 const runtime = createOpenApiLintRuntime({
-  ruleset: './spectral.yaml',
+  preset: 'strict',
   failOn: 'error',
   output: {
     console: true,
-    jsonReportPath: './artifacts/openapi-lint.json',
-    specSnapshotPath: true,
-    artifactWriteFailures: 'error'
-  }
+    sarifReportPath: './reports/openapi.sarif',
+    junitReportPath: './reports/openapi.junit.xml',
+    specSnapshotPath: './reports/openapi-snapshot.json',
+    artifactWriteFailures: 'error',
+  },
 })
 
-await runtime.run(app)
+try {
+  await runtime.run(app)
+  process.exit(0)
+} catch {
+  process.exit(1)
+}
 ```
 
+Run it as a CI step:
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+```
+
+### Integrate SARIF with GitHub code scanning
+
+SARIF output maps lint findings to code locations and surfaces them as GitHub code scanning alerts on pull requests.
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Upload SARIF to GitHub code scanning
+  uses: github/codeql-action/upload-sarif@v3
+  with:
+    sarif_file: reports/openapi.sarif
+  if: always()
+```
+
+`if: always()` ensures the SARIF upload runs even when the lint step fails, so findings are visible on failing PRs.
+
+### Report lint findings as JUnit test results
+
+JUnit output lets CI systems that consume test XML (Buildkite, CircleCI, GitLab, GitHub via third-party actions) show lint findings alongside test results.
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Publish lint results
+  uses: dorny/test-reporter@v1
+  with:
+    name: OpenAPI Lint
+    path: reports/openapi.junit.xml
+    reporter: java-junit
+  if: always()
+```
+
+### Track OpenAPI snapshot drift
+
+Commit the generated OpenAPI snapshot and use `git diff --exit-code` to detect when the API surface changes unexpectedly in a PR.
+
+1. Generate and commit the initial snapshot:
+
+```bash
+bun scripts/lint-openapi.ts
+git add reports/openapi-snapshot.json
+git commit -m "chore: add openapi snapshot"
+```
+
+1. In CI, regenerate the snapshot and check for drift:
+
+```yaml
+- name: Lint OpenAPI spec
+  run: bun scripts/lint-openapi.ts
+
+- name: Check for snapshot drift
+  run: git diff --exit-code reports/openapi-snapshot.json
+```
+
+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.
+
 ### Work on this repository locally
 
 From the monorepo root:
@@ -453,6 +551,8 @@ That example uses `startup.mode: 'report'`, so the app still boots while the pac
 ### Package API
 
 ```ts
+type PresetName = 'recommended' | 'server' | 'strict'
+
 type SeverityThreshold = 'error' | 'warn' | 'info' | 'hint' | 'never'
 
 type StartupLintMode = 'enforce' | 'report' | 'off'
@@ -474,7 +574,7 @@ type OpenApiLintSink = {
       spec: Record<string, unknown>
       logger: SpectralLogger
     }
-  ) => void | Partial<OpenApiLintArtifacts> | Promise<void | Partial<OpenApiLintArtifacts>>
+  ) => undefined | Partial<OpenApiLintArtifacts> | Promise<undefined | Partial<OpenApiLintArtifacts>>
 }
 
 type RulesetResolver = (
@@ -490,9 +590,14 @@ 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
 }
 
 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>
   failOn?: SeverityThreshold
   healthcheck?: false | { path?: string }
@@ -522,6 +627,30 @@ type SpectralPluginOptions = {
 }
 ```
 
+### Presets
+
+| Preset | Extends | elysia-operation-summary | elysia-operation-tags | operation-description | operation-operationId | oas3-api-servers | info-contact | rfc9457-problem-details |
+|---|---|---|---|---|---|---|---|---|
+| `recommended` | spectral:oas/recommended | warn | warn | — | — | off | off | — |
+| `server` | spectral:oas/recommended | error | error | warn | warn | warn | off | — |
+| `strict` | spectral:oas/recommended | error | error | error | error | error | warn | warn |
+
+All three presets are exported as `RulesetDefinition` objects and can be passed directly to `ruleset` if you need to compose them:
+
+```ts
+import { strict } from '@opsydyn/elysia-spectral'
+
+spectralPlugin({
+  ruleset: {
+    ...strict,
+    rules: {
+      ...(strict.rules as object),
+      'rfc9457-problem-details': 'error' // escalate to error for this service
+    }
+  }
+})
+```
+
 ### Runtime state
 
 The runtime object exposes:
@@ -549,6 +678,7 @@ Example successful response:
   "result": {
     "ok": true,
     "generatedAt": "2026-04-06T12:00:00.000Z",
+    "source": "startup",
     "summary": {
       "error": 0,
       "warn": 0,

package/dist/core/index.d.mts

@@ -1,2 +1,2 @@
-import { _ 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, 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, y as loadRuleset } from "../index-BrFQCFDI.mjs";
+import { _ 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, 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, y as loadRuleset } from "../index-CMyl_MsI.mjs";
 export { LoadResolvedRulesetOptions, LoadedRuleset, OpenApiLintArtifactWriteError, OpenApiLintThresholdError, ResolvedRulesetCandidate, RulesetLoadError, RulesetResolver, RulesetResolverContext, RulesetResolverInput, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail };

package/dist/core/index.mjs

@@ -1,2 +1,2 @@
-import { a as OpenApiLintThresholdError, c as shouldFail, d as defaultRulesetResolvers, f as loadResolvedRuleset, h as normalizeFindings, i as resolveStartupMode, 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-CTQQBA_q.mjs";
+import { a as OpenApiLintThresholdError, c as shouldFail, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, v as lintOpenApi, y as normalizeFindings } from "../core-D_ro1XEW.mjs";
 export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail };

package/dist/{core-CTQQBA_q.mjs → core-D_ro1XEW.mjs}

@@ -12,7 +12,12 @@ 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-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];
@@ -48,6 +53,7 @@ const normalizeFindings = (diagnostics, spec) => {
 	return {
 		ok: summary.error === 0,
 		generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+		source: "manual",
 		summary,
 		findings
 	};
@@ -117,31 +123,38 @@ const lintOpenApi = async (spec, ruleset) => {
 	return normalizeFindings(await spectral.run(spec, { ignoreUnknownFormat: false }), spec);
 };
 //#endregion
-//#region src/rulesets/default-ruleset.ts
-const { schema: schema$1, truthy: truthy$1 } = spectralFunctions;
-const { oas: oas$1 } = spectralRulesets;
-const operationSelector = "$.paths[*][get,put,post,delete,options,head,patch,trace]";
-const defaultRuleset = {
-	extends: [[oas$1, "recommended"]],
+//#region src/presets/recommended.ts
+const { schema: schema$3, truthy: truthy$3 } = spectralFunctions;
+const { oas: oas$3 } = spectralRulesets;
+const operationSelector$2 = "$.paths[*][get,put,post,delete,options,head,patch,trace]";
+/**
+* Baseline quality preset. Equivalent to the package default ruleset.
+*
+* - Extends spectral:oas/recommended
+* - elysia-operation-summary and elysia-operation-tags at warn
+* - oas3-api-servers and info-contact disabled (local-dev friendly)
+*/
+const recommended = {
+	extends: [[oas$3, "recommended"]],
 	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: operationSelector,
+			given: operationSelector$2,
 			then: {
 				field: "summary",
-				function: truthy$1
+				function: truthy$3
 			}
 		},
 		"elysia-operation-tags": {
 			description: "Operations should declare at least one tag for grouping and downstream tooling.",
 			severity: "warn",
-			given: operationSelector,
+			given: operationSelector$2,
 			then: {
 				field: "tags",
-				function: schema$1,
+				function: schema$3,
 				functionOptions: { schema: {
 					type: "array",
 					minItems: 1
@@ -151,9 +164,12 @@ const defaultRuleset = {
 	}
 };
 //#endregion
+//#region src/rulesets/default-ruleset.ts
+const defaultRuleset = recommended;
+//#endregion
 //#region src/core/load-ruleset.ts
-const { alphabetical, casing, defined, enumeration, falsy, length, or, pattern, schema, truthy, undefined: undefinedFunction, unreferencedReusableObject, xor } = spectralFunctions;
-const { oas } = spectralRulesets;
+const { alphabetical, casing, defined, enumeration, falsy, length, or, pattern, schema: schema$2, truthy: truthy$2, undefined: undefinedFunction, unreferencedReusableObject, xor } = spectralFunctions;
+const { oas: oas$2 } = spectralRulesets;
 const functionMap = {
 	alphabetical,
 	casing,
@@ -163,13 +179,13 @@ const functionMap = {
 	length,
 	or,
 	pattern,
-	schema,
-	truthy,
+	schema: schema$2,
+	truthy: truthy$2,
 	undefined: undefinedFunction,
 	unreferencedReusableObject,
 	xor
 };
-const extendsMap = { "spectral:oas": oas };
+const extendsMap = { "spectral:oas": oas$2 };
 const autodiscoverRulesetFilenames = [
 	"spectral.yaml",
 	"spectral.yml",
@@ -202,7 +218,7 @@ const loadResolvedRuleset = async (input, baseDirOrOptions = process.cwd()) => {
 	const options = normalizeLoadResolvedRulesetOptions(baseDirOrOptions);
 	const context = {
 		baseDir: options.baseDir,
-		defaultRuleset,
+		defaultRuleset: options.defaultRuleset,
 		mergeAutodiscoveredWithDefault: options.mergeAutodiscoveredWithDefault
 	};
 	for (const resolver of options.resolvers) {
@@ -213,19 +229,21 @@ const loadResolvedRuleset = async (input, baseDirOrOptions = process.cwd()) => {
 			return normalized;
 		}
 	}
-	if (input === void 0) return { ruleset: defaultRuleset };
+	if (input === void 0) return { ruleset: 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
+		mergeAutodiscoveredWithDefault: true,
+		defaultRuleset
 	};
 	return {
 		baseDir: value.baseDir ?? process.cwd(),
 		resolvers: value.resolvers ?? defaultRulesetResolvers,
-		mergeAutodiscoveredWithDefault: value.mergeAutodiscoveredWithDefault ?? true
+		mergeAutodiscoveredWithDefault: value.mergeAutodiscoveredWithDefault ?? true,
+		defaultRuleset: value.defaultRuleset ?? defaultRuleset
 	};
 };
 const resolveAutodiscoveredRuleset = async (input, context) => {
@@ -324,30 +342,30 @@ const loadModuleRuleset = async (resolvedPath) => {
 	});
 };
 const resolveModuleRulesetValue = (imported) => {
-	if (!isRecord(imported)) return;
+	if (!isRecord$1(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 {};
+	if (!isRecord$1(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.");
+	if (!isRecord$1(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 = (input, availableFunctions = functionMap) => {
-	if (!isRecord(input)) throw new RulesetLoadError("Ruleset must be an object.");
+	if (!isRecord$1(input)) throw new RulesetLoadError("Ruleset must be an object.");
 	const normalized = { ...input };
 	if ("extends" in normalized) normalized.extends = normalizeExtends(normalized.extends);
 	if ("rules" in normalized) normalized.rules = normalizeRules(normalized.rules, availableFunctions);
 	return normalized;
 };
 const mergeRuleEntry = (base, override) => {
-	if (!isRecord(override)) return override;
+	if (!isRecord$1(override)) return override;
 	if ("given" in override || "then" in override) return override;
-	if (isRecord(base) && ("given" in base || "then" in base)) return {
+	if (isRecord$1(base) && ("given" in base || "then" in base)) return {
 		...base,
 		...override
 	};
@@ -358,8 +376,8 @@ const mergeRuleEntry = (base, 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 baseRules = isRecord$1(mergedBase.rules) ? mergedBase.rules : {};
+	const overrideRules = isRecord$1(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);
@@ -394,12 +412,12 @@ const resolveExtendsEntry = (value) => {
 	return resolved;
 };
 const normalizeRules = (value, availableFunctions) => {
-	if (!isRecord(value)) return value;
+	if (!isRecord$1(value)) return value;
 	const entries = Object.entries(value).map(([ruleName, ruleValue]) => [ruleName, normalizeRule(ruleValue, availableFunctions)]);
 	return Object.fromEntries(entries);
 };
 const normalizeRule = (value, availableFunctions) => {
-	if (!isRecord(value)) return value;
+	if (!isRecord$1(value)) return value;
 	const normalized = { ...value };
 	if ("then" in normalized) normalized.then = normalizeThen(normalized.then, availableFunctions);
 	return normalized;
@@ -409,7 +427,7 @@ const normalizeThen = (value, availableFunctions) => {
 	return normalizeThenEntry(value, availableFunctions);
 };
 const normalizeThenEntry = (value, availableFunctions) => {
-	if (!isRecord(value)) return value;
+	if (!isRecord$1(value)) return value;
 	const normalized = { ...value };
 	if (typeof normalized.function === "string") {
 		const resolved = availableFunctions[normalized.function];
@@ -418,7 +436,7 @@ const normalizeThenEntry = (value, availableFunctions) => {
 	}
 	return normalized;
 };
-const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
+const isRecord$1 = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
 //#endregion
 //#region src/output/terminal-format.ts
 const severityStyles = {
@@ -873,6 +891,133 @@ const createOutputSinks = (options) => {
 	return sinks;
 };
 //#endregion
+//#region src/presets/server.ts
+const { schema: schema$1, truthy: truthy$1 } = spectralFunctions;
+const { oas: oas$1 } = spectralRulesets;
+const operationSelector$1 = "$.paths[*][get,put,post,delete,options,head,patch,trace]";
+/**
+* Production API quality preset. Suitable as a CI gate for teams shipping
+* public or internal APIs where contract quality matters.
+*
+* Tightens recommended:
+* - elysia-operation-summary and elysia-operation-tags escalated to error
+* - operation-description, operation-operationId, operation-success-response at warn
+* - oas3-api-servers at warn (servers should be declared in production specs)
+*/
+const server = {
+	extends: [[oas$1, "recommended"]],
+	rules: {
+		"oas3-api-servers": "warn",
+		"info-contact": "off",
+		"elysia-operation-summary": {
+			description: "Operations should define a summary for generated docs and clients.",
+			severity: "error",
+			given: operationSelector$1,
+			then: {
+				field: "summary",
+				function: truthy$1
+			}
+		},
+		"elysia-operation-tags": {
+			description: "Operations should declare at least one tag for grouping and downstream tooling.",
+			severity: "error",
+			given: operationSelector$1,
+			then: {
+				field: "tags",
+				function: schema$1,
+				functionOptions: { schema: {
+					type: "array",
+					minItems: 1
+				} }
+			}
+		},
+		"operation-description": "warn",
+		"operation-operationId": "warn",
+		"operation-success-response": "warn"
+	}
+};
+//#endregion
+//#region src/presets/strict.ts
+const { schema, truthy } = spectralFunctions;
+const { oas } = spectralRulesets;
+const operationSelector = "$.paths[*][get,put,post,delete,options,head,patch,trace]";
+const isRecord = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+/**
+* Checks that all 4xx/5xx responses declare application/problem+json as
+* their content type, conforming to RFC 9457 Problem Details for HTTP APIs.
+*/
+const checkProblemDetails = (operation) => {
+	if (!isRecord(operation) || !isRecord(operation.responses)) return;
+	const results = [];
+	for (const [statusCode, response] of Object.entries(operation.responses)) {
+		const code = Number(statusCode);
+		if (!Number.isFinite(code) || code < 400) continue;
+		if (!isRecord(response)) continue;
+		const content = response.content;
+		if (!isRecord(content) || !("application/problem+json" in content)) results.push({
+			message: `${statusCode} error response should use "application/problem+json" content type (RFC 9457 Problem Details).`,
+			path: ["responses", statusCode]
+		});
+	}
+	return results.length > 0 ? results : void 0;
+};
+/**
+* Full API governance preset. Suitable for teams with formal API governance
+* requirements, public API programs, or downstream client generation pipelines.
+*
+* Tightens server:
+* - All elysia rules and operation metadata rules escalated to error
+* - info-contact at warn (API ownership should be declared)
+* - oas3-api-servers at error (server declaration is required)
+* - rfc9457-problem-details at warn (error responses should use Problem Details)
+*/
+const strict = {
+	extends: [[oas, "recommended"]],
+	rules: {
+		"oas3-api-servers": "error",
+		"info-contact": "warn",
+		"elysia-operation-summary": {
+			description: "Operations should define a summary for generated docs and clients.",
+			severity: "error",
+			given: operationSelector,
+			then: {
+				field: "summary",
+				function: truthy
+			}
+		},
+		"elysia-operation-tags": {
+			description: "Operations should declare at least one tag for grouping and downstream tooling.",
+			severity: "error",
+			given: operationSelector,
+			then: {
+				field: "tags",
+				function: schema,
+				functionOptions: { schema: {
+					type: "array",
+					minItems: 1
+				} }
+			}
+		},
+		"operation-description": "error",
+		"operation-operationId": "error",
+		"operation-success-response": "error",
+		"rfc9457-problem-details": {
+			description: "Error responses (4xx, 5xx) should use RFC 9457 Problem Details (application/problem+json).",
+			message: "{{error}}",
+			severity: "warn",
+			given: operationSelector,
+			then: { function: checkProblemDetails }
+		}
+	}
+};
+//#endregion
+//#region src/presets/index.ts
+const presets = {
+	recommended,
+	server,
+	strict
+};
+//#endregion
 //#region src/providers/spec-provider.ts
 var BaseSpecProvider = class {
 	constructor(app, options = {}) {
@@ -1011,7 +1156,7 @@ const createOpenApiLintRuntime = (options = {}) => {
 		lastSuccess: null,
 		lastFailure: null,
 		running: false,
-		async run(app) {
+		async run(app, source = "manual") {
 			if (inFlight) return await inFlight;
 			inFlight = (async () => {
 				const startedAt = /* @__PURE__ */ new Date();
@@ -1023,10 +1168,14 @@ const createOpenApiLintRuntime = (options = {}) => {
 				reporter.start("OpenAPI lint started.");
 				try {
 					const spec = await new PublicSpecProvider(app, options.source).getSpec();
-					const loadedRuleset = await loadResolvedRuleset(options.ruleset);
-					if (loadedRuleset.source?.autodiscovered) reporter.ruleset(`OpenAPI lint autodiscovered ruleset ${loadedRuleset.source.path} and merged it with the package default ruleset.`);
+					const loadedRuleset = await loadResolvedRuleset(options.ruleset, { ...options.preset ? { defaultRuleset: presets[options.preset] } : {} });
+					if (loadedRuleset.source?.autodiscovered) {
+						const base = options.preset ? `"${options.preset}" preset` : "package default ruleset";
+						reporter.ruleset(`OpenAPI lint autodiscovered ruleset ${loadedRuleset.source.path} and merged it with the ${base}.`);
+					} else if (options.preset && !loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint using "${options.preset}" preset.`);
 					else if (loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint loaded ruleset ${loadedRuleset.source.path}.`);
 					const result = await lintOpenApi(spec, loadedRuleset.ruleset);
+					result.source = source;
 					await writeOutputSinks(result, spec, options, artifactWriteFailureMode);
 					runtime.latest = result;
 					reporter.complete("OpenAPI lint completed.");
@@ -1105,4 +1254,4 @@ const resolveStartupMode = (options = {}) => {
 	return options.enabled === false ? "off" : "enforce";
 };
 //#endregion
-export { OpenApiLintThresholdError as a, shouldFail as c, defaultRulesetResolvers as d, loadResolvedRuleset as f, normalizeFindings as h, resolveStartupMode as i, resolveReporter as l, lintOpenApi as m, createOpenApiLintRuntime as n, enforceThreshold as o, loadRuleset as p, isEnabled as r, exceedsThreshold as s, OpenApiLintArtifactWriteError as t, RulesetLoadError as u };
+export { recommended as _, OpenApiLintThresholdError as a, shouldFail as c, server as d, resolveReporter as f, loadRuleset as g, loadResolvedRuleset as h, resolveStartupMode as i, presets as l, defaultRulesetResolvers as m, createOpenApiLintRuntime as n, enforceThreshold as o, RulesetLoadError as p, isEnabled as r, exceedsThreshold as s, OpenApiLintArtifactWriteError as t, strict as u, lintOpenApi as v, normalizeFindings as y };

package/dist/{index-BrFQCFDI.d.mts → index-CMyl_MsI.d.mts}

@@ -2,10 +2,12 @@ import { ISpectralDiagnostic, RulesetDefinition } from "@stoplight/spectral-core
 import { AnyElysia } from "elysia";
 
 //#region src/types.d.ts
+type PresetName = 'recommended' | 'server' | 'strict';
 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 LintRunSource = 'startup' | 'healthcheck' | 'manual';
 type ArtifactWriteFailureMode = 'warn' | 'error';
 type SpectralLogger = {
   info: (message: string) => void;
@@ -27,6 +29,7 @@ type OpenApiLintSink = {
   write: (result: LintRunResult, context: OpenApiLintSinkContext) => undefined | Partial<OpenApiLintArtifacts> | Promise<undefined | Partial<OpenApiLintArtifacts>>;
 };
 type SpectralPluginOptions = {
+  preset?: PresetName;
   ruleset?: string | RulesetDefinition | Record<string, unknown>;
   failOn?: SeverityThreshold;
   healthcheck?: false | {
@@ -79,6 +82,7 @@ type LintFinding = {
 type LintRunResult = {
   ok: boolean;
   generatedAt: string;
+  source: LintRunSource;
   summary: {
     error: number;
     warn: number;
@@ -106,7 +110,7 @@ type OpenApiLintRuntime = {
   lastSuccess: LintRunResult | null;
   lastFailure: OpenApiLintRuntimeFailure | null;
   running: boolean;
-  run: (app: AnyElysia) => Promise<LintRunResult>;
+  run: (app: AnyElysia, source?: LintRunSource) => Promise<LintRunResult>;
 };
 //#endregion
 //#region src/core/lint-openapi.d.ts
@@ -135,7 +139,8 @@ type RulesetResolver = (input: RulesetResolverInput, context: RulesetResolverCon
 type LoadResolvedRulesetOptions = {
   baseDir?: string;
   resolvers?: RulesetResolver[];
-  mergeAutodiscoveredWithDefault?: boolean;
+  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 class RulesetLoadError extends Error {
   constructor(message: string, options?: {
@@ -169,4 +174,4 @@ declare const exceedsThreshold: (severity: LintSeverity, threshold: SeverityThre
 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 };
+export { OpenApiLintSink as A, LintRunResult as C, OpenApiLintRuntime as D, OpenApiLintArtifacts as E, SpectralLogger as F, SpectralPluginOptions as I, StartupLintMode as L, PresetName as M, SeverityThreshold as N, OpenApiLintRuntimeFailure as O, SpecProvider as P, LintFinding as S, LintSeverity 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, OpenApiLintSinkContext as j, OpenApiLintRuntimeStatus 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, LintRunSource as w, ArtifactWriteFailureMode as x, loadRuleset as y };

package/dist/index.d.mts

@@ -1,4 +1,5 @@
-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 { A as OpenApiLintSink, C as LintRunResult, D as OpenApiLintRuntime, E as OpenApiLintArtifacts, F as SpectralLogger, I as SpectralPluginOptions, L as StartupLintMode, M as PresetName, N as SeverityThreshold, O as OpenApiLintRuntimeFailure, P as SpecProvider, S as LintFinding, T as LintSeverity, _ 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 OpenApiLintSinkContext, k as OpenApiLintRuntimeStatus, 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 LintRunSource, x as ArtifactWriteFailureMode, y as loadRuleset } from "./index-CMyl_MsI.mjs";
+import { RulesetDefinition } from "@stoplight/spectral-core";
 import { Elysia } from "elysia";
 
 //#region src/plugin.d.ts
@@ -33,4 +34,42 @@ declare const spectralPlugin: (options?: SpectralPluginOptions) => Elysia<"", {
   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 };
+//#region src/presets/recommended.d.ts
+/**
+ * Baseline quality preset. Equivalent to the package default ruleset.
+ *
+ * - Extends spectral:oas/recommended
+ * - elysia-operation-summary and elysia-operation-tags at warn
+ * - oas3-api-servers and info-contact disabled (local-dev friendly)
+ */
+declare const recommended: RulesetDefinition;
+//#endregion
+//#region src/presets/server.d.ts
+/**
+ * Production API quality preset. Suitable as a CI gate for teams shipping
+ * public or internal APIs where contract quality matters.
+ *
+ * Tightens recommended:
+ * - elysia-operation-summary and elysia-operation-tags escalated to error
+ * - operation-description, operation-operationId, operation-success-response at warn
+ * - oas3-api-servers at warn (servers should be declared in production specs)
+ */
+declare const server: RulesetDefinition;
+//#endregion
+//#region src/presets/strict.d.ts
+/**
+ * Full API governance preset. Suitable for teams with formal API governance
+ * requirements, public API programs, or downstream client generation pipelines.
+ *
+ * Tightens server:
+ * - All elysia rules and operation metadata rules escalated to error
+ * - info-contact at warn (API ownership should be declared)
+ * - oas3-api-servers at error (server declaration is required)
+ * - rfc9457-problem-details at warn (error responses should use Problem Details)
+ */
+declare const strict: RulesetDefinition;
+//#endregion
+//#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, SpecProvider, SpectralLogger, SpectralPluginOptions, StartupLintMode, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, presets, recommended, resolveStartupMode, server, shouldFail, spectralPlugin, strict };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-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-CTQQBA_q.mjs";
+import { _ as recommended, a as OpenApiLintThresholdError, c as shouldFail, d as server, f as resolveReporter, g as loadRuleset, h as loadResolvedRuleset, i as resolveStartupMode, l as presets, m as defaultRulesetResolvers, n as createOpenApiLintRuntime, o as enforceThreshold, p as RulesetLoadError, r as isEnabled, s as exceedsThreshold, t as OpenApiLintArtifactWriteError, u as strict, v as lintOpenApi, y as normalizeFindings } from "./core-D_ro1XEW.mjs";
 import { Elysia } from "elysia";
 //#region src/plugin.ts
 const spectralPlugin = (options = {}) => {
@@ -11,7 +11,7 @@ const spectralPlugin = (options = {}) => {
 		const startupMode = resolveStartupMode(options);
 		if (startupMode === "off") return;
 		try {
-			await runtime.run(app);
+			await runtime.run(app, "startup");
 		} 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".`);
@@ -37,7 +37,7 @@ const spectralPlugin = (options = {}) => {
 			}
 			try {
 				const usedCache = !fresh && (runtime.latest !== null || runtime.running);
-				const result = usedCache ? runtime.latest ?? await runtime.run(currentApp) : await runtime.run(currentApp);
+				const result = usedCache ? runtime.latest ?? await runtime.run(currentApp, "healthcheck") : await runtime.run(currentApp, "healthcheck");
 				if (result === null) {
 					set.status = 500;
 					return {
@@ -82,4 +82,4 @@ const spectralPlugin = (options = {}) => {
 	return plugin;
 };
 //#endregion
-export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, resolveStartupMode, shouldFail, spectralPlugin };
+export { OpenApiLintArtifactWriteError, OpenApiLintThresholdError, RulesetLoadError, createOpenApiLintRuntime, defaultRulesetResolvers, enforceThreshold, exceedsThreshold, isEnabled, lintOpenApi, loadResolvedRuleset, loadRuleset, normalizeFindings, presets, recommended, resolveStartupMode, server, shouldFail, spectralPlugin, strict };

package/package.json

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