@opsydyn/elysia-spectral 0.2.4

package/dist/core-Czin3kvK.mjs

@@ -0,0 +1,1099 @@
+import spectralCore from "@stoplight/spectral-core";
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import spectralFunctions from "@stoplight/spectral-functions";
+import spectralRulesets from "@stoplight/spectral-rulesets";
+import YAML from "yaml";
+import signale from "signale";
+import { styleText } from "node:util";
+//#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."
+};
+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(),
+		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
+const { Spectral } = spectralCore;
+const lintOpenApi = async (spec, ruleset) => {
+	const spectral = new Spectral();
+	spectral.setRuleset(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"]],
+	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,
+			then: {
+				field: "summary",
+				function: truthy$1
+			}
+		},
+		"elysia-operation-tags": {
+			description: "Operations should declare at least one tag for grouping and downstream tooling.",
+			severity: "warn",
+			given: operationSelector,
+			then: {
+				field: "tags",
+				function: schema$1,
+				functionOptions: { schema: {
+					type: "array",
+					minItems: 1
+				} }
+			}
+		}
+	}
+};
+//#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 functionMap = {
+	alphabetical,
+	casing,
+	defined,
+	enumeration,
+	falsy,
+	length,
+	or,
+	pattern,
+	schema,
+	truthy,
+	undefined: undefinedFunction,
+	unreferencedReusableObject,
+	xor
+};
+const extendsMap = { "spectral:oas": oas };
+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"
+];
+var RulesetLoadError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "RulesetLoadError";
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+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,
+		mergeAutodiscoveredWithDefault: options.mergeAutodiscoveredWithDefault
+	};
+	for (const resolver of options.resolvers) {
+		const loaded = await resolver(input, context);
+		if (loaded) {
+			const normalized = { ruleset: normalizeRulesetDefinition(loaded.ruleset) };
+			if (loaded.source) normalized.source = loaded.source;
+			return normalized;
+		}
+	}
+	if (input === void 0) return { ruleset: defaultRuleset };
+	throw new RulesetLoadError("Ruleset input could not be resolved.");
+};
+const normalizeLoadResolvedRulesetOptions = (value) => {
+	if (typeof value === "string") return {
+		baseDir: value,
+		resolvers: defaultRulesetResolvers,
+		mergeAutodiscoveredWithDefault: true
+	};
+	return {
+		baseDir: value.baseDir ?? process.cwd(),
+		resolvers: value.resolvers ?? defaultRulesetResolvers,
+		mergeAutodiscoveredWithDefault: value.mergeAutodiscoveredWithDefault ?? true
+	};
+};
+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: normalizeRulesetDefinition(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 normalizeRulesetDefinition(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 normalizeRulesetDefinition(resolvedRuleset, {
+		...functionMap,
+		...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 = (input, availableFunctions = functionMap) => {
+	if (!isRecord(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 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,
+		...overrideRules
+	};
+	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 = (value) => {
+	if (typeof value === "string") return resolveExtendsEntry(value);
+	if (!Array.isArray(value)) return value;
+	return value.map((entry) => {
+		if (typeof entry === "string") return resolveExtendsEntry(entry);
+		if (Array.isArray(entry) && entry.length >= 1 && typeof entry[0] === "string") return [resolveExtendsEntry(entry[0]), entry[1]];
+		return entry;
+	});
+};
+const resolveExtendsEntry = (value) => {
+	const resolved = extendsMap[value];
+	if (!resolved) throw new RulesetLoadError(`Unsupported ruleset extend target: ${value}. v0.1 supports spectral:oas.`);
+	return resolved;
+};
+const normalizeRules = (value, availableFunctions) => {
+	if (!isRecord(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;
+	const normalized = { ...value };
+	if ("then" in normalized) normalized.then = normalizeThen(normalized.then, availableFunctions);
+	return normalized;
+};
+const normalizeThen = (value, availableFunctions) => {
+	if (Array.isArray(value)) return value.map((entry) => normalizeThenEntry(entry, availableFunctions));
+	return normalizeThenEntry(value, availableFunctions);
+};
+const normalizeThenEntry = (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
+//#region src/output/terminal-format.ts
+const severityStyles = {
+	error: [
+		"bold",
+		"white",
+		"bgRed"
+	],
+	warn: [
+		"bold",
+		"black",
+		"bgYellow"
+	],
+	info: ["bold", "cyan"],
+	hint: ["bold", "gray"]
+};
+const formatSeverityLabel = (severity) => ` ${styleText(severityStyles[severity], severity.toUpperCase())} `;
+const formatPassCard = (summary) => {
+	return styleText("green", buildCard([
+		`${styleText(["bold", "white"], "OPENAPI LINT")}  ${styleText([
+			"bold",
+			"white",
+			"bgGreen"
+		], "PASS")}`,
+		`${styleText(["bold", "green"], String(summary.error))} errors  ${styleText(["bold", "green"], String(summary.warn))} warns  ${styleText(["bold", "green"], String(summary.info))} info`,
+		styleText(["bold", "green"], "SPEC IS TIGHT, SHIP IT RIGHT")
+	]));
+};
+const formatSectionHeading = (value, severity) => {
+	if (!severity) return styleText([
+		"bold",
+		"white",
+		"bgBlue"
+	], ` ${value} `);
+	switch (severity) {
+		case "error": return styleText([
+			"bold",
+			"white",
+			"bgRed"
+		], ` ${value} `);
+		case "warn": return styleText([
+			"bold",
+			"black",
+			"bgYellow"
+		], ` ${value} `);
+		case "info": return styleText([
+			"bold",
+			"white",
+			"bgBlue"
+		], ` ${value} `);
+		case "hint": return styleText([
+			"bold",
+			"white",
+			"bgBlack"
+		], ` ${value} `);
+	}
+};
+const formatKey = (kind) => {
+	switch (kind) {
+		case "issue": return styleText(["bold", "cyan"], "Issue");
+		case "fix": return styleText(["bold", "green"], "Fix");
+		case "spec": return styleText(["bold", "magenta"], "Spec");
+		case "threshold": return styleText(["bold", "yellow"], "Threshold");
+	}
+};
+const formatDivider = () => styleText("gray", "------------------------------------------------------------");
+const formatCount = (value, severity) => {
+	switch (severity) {
+		case "error": return styleText(["bold", "red"], String(value));
+		case "warn": return styleText(["bold", "yellow"], String(value));
+		case "info": return styleText(["bold", "cyan"], String(value));
+		default: return styleText(["bold", "gray"], String(value));
+	}
+};
+const formatSummaryCounts = (summary) => [
+	`${formatCount(summary.error, "error")} error(s)`,
+	`${formatCount(summary.warn, "warn")} warning(s)`,
+	`${formatCount(summary.info, "info")} info finding(s)`,
+	`${formatCount(summary.hint, "hint")} hint(s)`
+].join("  ");
+const formatCompactSummaryCounts = (summary) => [
+	`${formatCount(summary.error, "error")} errors`,
+	`${formatCount(summary.warn, "warn")} warnings`,
+	`${formatCount(summary.info, "info")} info`,
+	`${formatCount(summary.hint, "hint")} hints`
+].join("  ");
+const formatSpecReference = (value) => {
+	const [filePath, pointer] = value.split("#", 2);
+	if (!filePath) return value;
+	const shortPath = path.isAbsolute(filePath) ? path.relative(process.cwd(), filePath) || path.basename(filePath) : filePath;
+	return pointer ? `${shortPath}#${pointer}` : shortPath;
+};
+const formatFindingTitle = (finding) => {
+	const location = finding.operation?.method && finding.operation?.path ? `${finding.operation.method.toUpperCase()} ${finding.operation.path}` : finding.documentPointer ?? "(document)";
+	return `${formatSeverityLabel(finding.severity)} ${styleText("bold", finding.code)}  ${location}`;
+};
+const buildCard = (lines) => {
+	const innerWidth = Math.max(...lines.map((line) => stripAnsi(line).length)) + 2;
+	const top = `┌${"─".repeat(innerWidth)}┐`;
+	const bottom = `└${"─".repeat(innerWidth)}┘`;
+	return [
+		top,
+		...lines.map((line) => padCardLine(line, innerWidth)),
+		bottom
+	].join("\n");
+};
+const padCardLine = (content, innerWidth) => {
+	const plainLength = stripAnsi(content).length;
+	const padding = Math.max(innerWidth - plainLength - 1, 0);
+	return `│ ${content}${" ".repeat(padding)}│`;
+};
+const stripAnsi = (value) => value.replace(/\u001B\[[0-9;]*m/g, "");
+//#endregion
+//#region src/output/console-reporter.ts
+const { Signale } = signale;
+const defaultSignale = new Signale({
+	scope: "elysia-spectral",
+	interactive: false,
+	types: {
+		artifact: {
+			badge: "◆",
+			color: "cyan",
+			label: "artifact",
+			logLevel: "info"
+		},
+		ruleset: {
+			badge: "◌",
+			color: "blue",
+			label: "ruleset",
+			logLevel: "info"
+		},
+		report: {
+			badge: "↺",
+			color: "magenta",
+			label: "report",
+			logLevel: "warn"
+		},
+		hype: {
+			badge: "▲",
+			color: "magenta",
+			label: "hype",
+			logLevel: "info"
+		}
+	}
+});
+const defaultReporter = {
+	info: (message) => defaultSignale.log(message),
+	warn: (message) => defaultSignale.warn(message),
+	error: (message) => defaultSignale.error(message),
+	log: (message) => defaultSignale.log(message),
+	note: (message) => defaultSignale.note(message),
+	start: (message) => defaultSignale.start(message),
+	complete: (message) => defaultSignale.complete(message),
+	success: (message) => defaultSignale.success(message),
+	awaiting: (message) => defaultSignale.await(message),
+	artifact: (message) => defaultSignale.artifact(message),
+	ruleset: (message) => defaultSignale.ruleset(message),
+	report: (message) => defaultSignale.report(message),
+	hype: (message) => defaultSignale.hype(message)
+};
+const resolveReporter = (logger) => {
+	if (!logger) return defaultReporter;
+	return {
+		...logger,
+		log: (message) => logger.info(message),
+		note: (message) => logger.info(message),
+		start: (message) => logger.info(message),
+		complete: (message) => logger.info(message),
+		success: (message) => logger.info(message),
+		awaiting: (message) => logger.info(message),
+		artifact: (message) => logger.info(message),
+		ruleset: (message) => logger.info(message),
+		report: (message) => logger.warn(message),
+		hype: (message) => logger.info(message)
+	};
+};
+const reportToConsole = (result, logger = defaultReporter) => {
+	const reporter = resolveReporter(logger);
+	const summaryCounts = formatSummaryCounts(result.summary);
+	if (result.summary.total === 0) {
+		reporter.success("OpenAPI lint passed.");
+		reporter.note(formatCompactSummaryCounts(result.summary));
+		reporter.hype(formatPassCard(result.summary));
+		return;
+	}
+	if (result.summary.error > 0) reporter.error(`OpenAPI lint found contract failures. ${summaryCounts}`);
+	else reporter.warn(`OpenAPI lint found warnings. ${summaryCounts}`);
+	reporter.log(formatDivider());
+	const sections = [
+		{
+			severity: "error",
+			title: `ERRORS (${result.summary.error})`,
+			findings: result.findings.filter((finding) => finding.severity === "error")
+		},
+		{
+			severity: "warn",
+			title: `WARNINGS (${result.summary.warn})`,
+			findings: result.findings.filter((finding) => finding.severity === "warn")
+		},
+		{
+			severity: "info",
+			title: `INFO (${result.summary.info})`,
+			findings: result.findings.filter((finding) => finding.severity === "info")
+		},
+		{
+			severity: "hint",
+			title: `HINTS (${result.summary.hint})`,
+			findings: result.findings.filter((finding) => finding.severity === "hint")
+		}
+	].filter((section) => section.findings.length > 0);
+	for (const section of sections) {
+		reporter.log(formatSectionHeading(section.title, section.severity));
+		reporter.log(formatDivider());
+		for (const finding of section.findings) logFinding(finding, reporter, result.artifacts?.specSnapshotPath);
+	}
+	reporter.note(`Summary: ${summaryCounts}`);
+};
+const logFinding = (finding, reporter, specSnapshotPath) => {
+	const specReference = buildSpecReference(finding, specSnapshotPath);
+	const title = formatFindingTitle(finding);
+	reporter.log(title);
+	reporter.log(`  ${formatKey("issue")} ${finding.message}`);
+	if (finding.recommendation) reporter.log(`  ${formatKey("fix")}   ${finding.recommendation}`);
+	if (specReference) reporter.log(`  ${formatKey("spec")}  ${formatSpecReference(specReference)}`);
+	reporter.log(formatDivider());
+};
+const buildSpecReference = (finding, specSnapshotPath) => {
+	if (!finding.documentPointer) return specSnapshotPath;
+	if (!specSnapshotPath) return `openapi.json#${finding.documentPointer}`;
+	return `${specSnapshotPath}#${finding.documentPointer}`;
+};
+//#endregion
+//#region src/output/json-reporter.ts
+const DEFAULT_SPEC_SNAPSHOT_FILENAME = "open-api.json";
+const writeJsonArtifact = async (artifactPath, payload, pretty = true) => {
+	const resolvedPath = path.resolve(process.cwd(), artifactPath);
+	await mkdir(path.dirname(resolvedPath), { recursive: true });
+	await writeFile(resolvedPath, `${JSON.stringify(payload, null, pretty ? 2 : 0)}\n`, "utf8");
+	return resolvedPath;
+};
+const writeJsonReport = async (reportPath, result, pretty = true) => writeJsonArtifact(reportPath, result, pretty);
+const writeSpecSnapshot = async (snapshotPath, spec, pretty = true) => writeJsonArtifact(snapshotPath, spec, pretty);
+const sanitizePackageNameForFilename = (packageName) => packageName.replace(/^@/, "").replace(/\//g, "-");
+const resolveDefaultSpecSnapshotPath = async () => {
+	try {
+		const packageJsonPath = path.resolve(process.cwd(), "package.json");
+		const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+		if (typeof packageJson.name === "string" && packageJson.name.length > 0) return `./${sanitizePackageNameForFilename(packageJson.name)}.open-api.json`;
+	} catch {}
+	return `./${DEFAULT_SPEC_SNAPSHOT_FILENAME}`;
+};
+//#endregion
+//#region src/output/junit-reporter.ts
+const escapeXml = (value) => value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("'", "&apos;");
+const writeJunitReport = async (reportPath, result) => {
+	const resolvedPath = path.resolve(process.cwd(), reportPath);
+	await mkdir(path.dirname(resolvedPath), { recursive: true });
+	await writeFile(resolvedPath, `${buildJunitReport(result)}\n`, "utf8");
+	return resolvedPath;
+};
+const buildJunitReport = (result) => {
+	const testCases = result.findings.length === 0 ? [buildPassingTestCase()] : result.findings.map((finding) => buildFailingTestCase(finding));
+	const tests = testCases.length;
+	const failures = result.findings.length;
+	const timestamp = escapeXml(result.generatedAt);
+	return [
+		"<?xml version=\"1.0\" encoding=\"UTF-8\"?>",
+		`<testsuites tests="${tests}" failures="${failures}" errors="0" skipped="0" time="0">`,
+		`  <testsuite name="OpenAPI lint" tests="${tests}" failures="${failures}" errors="0" skipped="0" time="0" timestamp="${timestamp}">`,
+		...testCases.map((testCase) => `    ${testCase}`),
+		"  </testsuite>",
+		"</testsuites>"
+	].join("\n");
+};
+const buildPassingTestCase = () => "<testcase classname=\"openapi.lint\" name=\"OpenAPI lint\" time=\"0\" />";
+const buildFailingTestCase = (finding) => {
+	const className = escapeXml(finding.operation?.path ? `openapi${finding.operation.path.replaceAll("/", ".")}` : "openapi.document");
+	const name = escapeXml(buildTestName(finding));
+	const failureType = escapeXml(finding.severity);
+	const failureMessage = escapeXml(finding.message);
+	const body = escapeXml(buildFailureBody(finding));
+	return [
+		`<testcase classname="${className}" name="${name}" time="0">`,
+		`      <failure type="${failureType}" message="${failureMessage}">${body}</failure>`,
+		"    </testcase>"
+	].join("\n");
+};
+const buildTestName = (finding) => {
+	return `${finding.code} ${finding.operation?.path ? `${finding.operation.method?.toUpperCase() ?? "DOC"} ${finding.operation.path}` : "document"}`;
+};
+const buildFailureBody = (finding) => {
+	const lines = [`Issue: ${finding.message}`];
+	if (finding.recommendation) lines.push(`Fix: ${finding.recommendation}`);
+	if (finding.documentPointer) lines.push(`Spec: openapi.json#${finding.documentPointer}`);
+	return lines.join("\n");
+};
+//#endregion
+//#region src/output/sarif-reporter.ts
+const SARIF_SCHEMA_URI = "https://docs.oasis-open.org/sarif/sarif/v2.1.0/cs01/schemas/sarif-schema-2.1.0.json";
+const writeSarifReport = async (reportPath, result, pretty = true) => {
+	const resolvedPath = path.resolve(process.cwd(), reportPath);
+	await mkdir(path.dirname(resolvedPath), { recursive: true });
+	await writeFile(resolvedPath, `${JSON.stringify(buildSarifReport(result), null, pretty ? 2 : 0)}\n`, "utf8");
+	return resolvedPath;
+};
+const buildSarifReport = (result) => {
+	const defaultArtifactPath = result.artifacts?.specSnapshotPath && result.artifacts.specSnapshotPath.length > 0 ? toSarifArtifactUri(result.artifacts.specSnapshotPath) : "openapi.json";
+	const rulesById = buildSarifRules(result.findings);
+	return {
+		$schema: SARIF_SCHEMA_URI,
+		version: "2.1.0",
+		runs: [{
+			automationDetails: { id: "@opsydyn/elysia-spectral/openapi-lint" },
+			originalUriBaseIds: { "%SRCROOT%": { uri: pathToFileURL(`${process.cwd()}${path.sep}`).href } },
+			tool: { driver: {
+				name: "@opsydyn/elysia-spectral",
+				informationUri: "https://github.com/stoplightio/spectral",
+				rules: [...rulesById.values()]
+			} },
+			results: result.findings.map((finding) => buildSarifResult(finding, defaultArtifactPath, rulesById))
+		}]
+	};
+};
+const buildSarifRules = (findings) => {
+	const findingsById = /* @__PURE__ */ new Map();
+	for (const finding of findings) if (!findingsById.has(finding.code)) findingsById.set(finding.code, finding);
+	return new Map([...findingsById.values()].map((finding) => [finding.code, {
+		id: finding.code,
+		name: finding.code,
+		shortDescription: { text: finding.message },
+		helpUri: "https://github.com/stoplightio/spectral",
+		defaultConfiguration: { level: toSarifLevel(finding.severity) },
+		help: finding.recommendation ? { text: finding.recommendation } : void 0,
+		properties: { tags: [
+			"openapi",
+			"spectral",
+			finding.severity
+		] }
+	}]));
+};
+const buildSarifResult = (finding, defaultArtifactPath, rulesById) => {
+	const location = buildSarifLocation(finding, defaultArtifactPath);
+	return {
+		ruleId: finding.code,
+		ruleIndex: [...rulesById.keys()].indexOf(finding.code),
+		level: toSarifLevel(finding.severity),
+		message: { text: finding.message },
+		locations: location ? [location] : void 0,
+		partialFingerprints: { primaryLocationLineHash: [
+			finding.code,
+			finding.documentPointer ?? "(document)",
+			finding.message
+		].join(":") },
+		properties: {
+			severity: finding.severity,
+			documentPointer: finding.documentPointer,
+			operationId: finding.operation?.operationId
+		}
+	};
+};
+const buildSarifLocation = (finding, defaultArtifactPath) => {
+	const region = finding.range?.start && finding.range?.end ? {
+		startLine: finding.range.start.line + 1,
+		startColumn: finding.range.start.character + 1,
+		endLine: finding.range.end.line + 1,
+		endColumn: finding.range.end.character + 1
+	} : void 0;
+	const uri = defaultArtifactPath;
+	if (!uri) return;
+	return {
+		physicalLocation: {
+			artifactLocation: {
+				uri,
+				uriBaseId: "%SRCROOT%"
+			},
+			region
+		},
+		logicalLocations: finding.operation?.path ? [{
+			name: finding.operation.method && finding.operation.path ? `${finding.operation.method.toUpperCase()} ${finding.operation.path}` : finding.operation.path,
+			fullyQualifiedName: finding.operation.operationId
+		}] : void 0
+	};
+};
+const toSarifLevel = (severity) => {
+	switch (severity) {
+		case "error": return "error";
+		case "warn": return "warning";
+		default: return "note";
+	}
+};
+const toSarifArtifactUri = (value) => {
+	if (!path.isAbsolute(value)) return value;
+	return path.relative(process.cwd(), value) || path.basename(value);
+};
+//#endregion
+//#region src/output/sinks.ts
+const createOutputSinks = (options) => {
+	const reporter = resolveReporter(options.logger);
+	const sinks = [];
+	const configuredSpecSnapshotPath = options.output?.specSnapshotPath;
+	const configuredJsonReportPath = options.output?.jsonReportPath;
+	const configuredJunitReportPath = options.output?.junitReportPath;
+	const configuredSarifReportPath = options.output?.sarifReportPath;
+	if (configuredSpecSnapshotPath) sinks.push({
+		name: "spec snapshot",
+		kind: "artifact",
+		async write(_result, context) {
+			const writtenSpecSnapshotPath = await writeSpecSnapshot(configuredSpecSnapshotPath === true ? await resolveDefaultSpecSnapshotPath() : configuredSpecSnapshotPath, context.spec, options.output?.pretty !== false);
+			reporter.artifact(`OpenAPI lint wrote spec snapshot to ${writtenSpecSnapshotPath}.`);
+			return { specSnapshotPath: writtenSpecSnapshotPath };
+		}
+	});
+	if (configuredJsonReportPath) sinks.push({
+		name: "JSON report",
+		kind: "artifact",
+		async write(result) {
+			const writtenJsonReportPath = await writeJsonReport(configuredJsonReportPath, result, options.output?.pretty !== false);
+			reporter.artifact(`OpenAPI lint wrote JSON report to ${writtenJsonReportPath}.`);
+			return { jsonReportPath: writtenJsonReportPath };
+		}
+	});
+	if (configuredJunitReportPath) sinks.push({
+		name: "JUnit report",
+		kind: "artifact",
+		async write(result) {
+			const writtenJunitReportPath = await writeJunitReport(configuredJunitReportPath, result);
+			reporter.artifact(`OpenAPI lint wrote JUnit report to ${writtenJunitReportPath}.`);
+			return { junitReportPath: writtenJunitReportPath };
+		}
+	});
+	if (configuredSarifReportPath) sinks.push({
+		name: "SARIF report",
+		kind: "artifact",
+		async write(result) {
+			const writtenSarifReportPath = await writeSarifReport(configuredSarifReportPath, result, options.output?.pretty !== false);
+			reporter.artifact(`OpenAPI lint wrote SARIF report to ${writtenSarifReportPath}.`);
+			return { sarifReportPath: writtenSarifReportPath };
+		}
+	});
+	for (const sink of options.output?.sinks ?? []) sinks.push({
+		name: sink.name,
+		kind: "custom",
+		write: async (result, context) => await Promise.resolve(sink.write(result, context))
+	});
+	if (options.output?.console !== false) sinks.push({
+		name: "console",
+		kind: "report",
+		async write(result) {
+			reportToConsole(result, reporter);
+		}
+	});
+	return sinks;
+};
+//#endregion
+//#region src/providers/spec-provider.ts
+var BaseSpecProvider = class {
+	constructor(app, options = {}) {
+		this.app = app;
+		this.options = options;
+	}
+	get specPath() {
+		return normalizeSpecPath(this.options?.specPath ?? "/openapi/json");
+	}
+};
+const normalizeSpecPath = (value) => {
+	if (value.length === 0) return "/openapi/json";
+	return value.startsWith("/") ? value : `/${value}`;
+};
+const createInProcessRequest = (specPath) => new Request(new URL(specPath, "http://localhost").toString());
+//#endregion
+//#region src/providers/public-spec-provider.ts
+var PublicSpecProviderError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "PublicSpecProviderError";
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+var PublicSpecProvider = class extends BaseSpecProvider {
+	constructor(app, options = {}) {
+		super(app, options);
+	}
+	async getSpec() {
+		const inProcessRequest = createInProcessRequest(this.specPath);
+		const sourceLabel = `app.handle(Request) at ${this.specPath}`;
+		try {
+			const response = await this.app.handle(inProcessRequest);
+			if (response.ok) return await parseSpecResponse(response, sourceLabel, this.specPath);
+			if (this.options?.baseUrl) return await this.fetchViaLoopback();
+			const body = await safeReadBody(response);
+			throw new PublicSpecProviderError([`Unable to load OpenAPI JSON from ${this.specPath} via ${sourceLabel}: received ${describeResponse(response)}${body ? ` with body ${body}.` : "."}`, `Fix: ensure @elysiajs/openapi is mounted and exposing "${this.specPath}", or update source.specPath to the correct OpenAPI JSON route.`].join(" "));
+		} catch (error) {
+			if (this.options?.baseUrl) return await this.fetchViaLoopback(error);
+			if (error instanceof PublicSpecProviderError) throw error;
+			throw new PublicSpecProviderError([`Unable to resolve OpenAPI JSON from ${this.specPath} via ${sourceLabel}.`, "Fix: ensure the app can serve the configured OpenAPI JSON route, or set source.baseUrl if the document is only reachable over HTTP."].join(" "), { cause: error });
+		}
+	}
+	async fetchViaLoopback(cause) {
+		const baseUrl = this.options?.baseUrl;
+		if (!baseUrl) throw new PublicSpecProviderError("Loopback fetch requires source.baseUrl.", { cause });
+		const url = new URL(this.specPath, ensureTrailingSlash(baseUrl)).toString();
+		const response = await fetch(url);
+		if (!response.ok) {
+			const body = await safeReadBody(response);
+			throw new PublicSpecProviderError([`Unable to load OpenAPI JSON from ${url}: received ${describeResponse(response)}${body ? ` with body ${body}.` : "."}`, "Fix: ensure the HTTP endpoint is reachable and returns the generated OpenAPI JSON, or update source.baseUrl/source.specPath."].join(" "), { cause });
+		}
+		return parseSpecResponse(response, url, this.specPath);
+	}
+};
+const parseSpecResponse = async (response, sourceLabel, specPath) => {
+	const body = await response.text();
+	try {
+		return JSON.parse(body);
+	} catch (error) {
+		throw new PublicSpecProviderError([`Unable to parse OpenAPI JSON from ${sourceLabel}: response was not valid JSON${body.trim() ? ` (body preview: ${formatBodyPreview(body)}).` : "."}`, `Fix: ensure the configured endpoint for "${specPath}" returns the generated OpenAPI document as JSON.`].join(" "), { cause: error });
+	}
+};
+const ensureTrailingSlash = (value) => value.endsWith("/") ? value : `${value}/`;
+const safeReadBody = async (response) => {
+	try {
+		const body = await response.text();
+		return body.trim() ? formatBodyPreview(body) : "";
+	} catch {
+		return "";
+	}
+};
+const describeResponse = (response) => response.statusText ? `${response.status} ${response.statusText}` : String(response.status);
+const formatBodyPreview = (value) => {
+	const normalized = value.replace(/\s+/g, " ").trim();
+	if (normalized.length <= 120) return JSON.stringify(normalized);
+	return JSON.stringify(`${normalized.slice(0, 117)}...`);
+};
+//#endregion
+//#region src/core/thresholds.ts
+const severityRank = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	hint: 3
+};
+const thresholdRank = {
+	error: 0,
+	warn: 1,
+	info: 2,
+	hint: 3
+};
+var OpenApiLintThresholdError = class extends Error {
+	constructor(threshold, result) {
+		super(buildThresholdMessage(threshold, result));
+		this.threshold = threshold;
+		this.result = result;
+		this.name = "OpenApiLintThresholdError";
+	}
+};
+const exceedsThreshold = (severity, threshold) => {
+	if (threshold === "never") return false;
+	return severityRank[severity] <= thresholdRank[threshold];
+};
+const shouldFail = (result, threshold) => {
+	if (threshold === "never") return false;
+	return result.findings.some((finding) => exceedsThreshold(finding.severity, threshold));
+};
+const enforceThreshold = (result, threshold) => {
+	if (shouldFail(result, threshold)) throw new OpenApiLintThresholdError(threshold, result);
+};
+const buildThresholdMessage = (threshold, result) => {
+	const topFindings = result.findings.filter((finding) => exceedsThreshold(finding.severity, threshold)).slice(0, 5).map((finding) => {
+		const operation = finding.operation?.method && finding.operation?.path ? ` ${finding.operation.method.toUpperCase()} ${finding.operation.path}` : "";
+		return `[${finding.severity}] ${finding.code}${operation}: ${finding.message}`;
+	});
+	const lines = [`OpenAPI lint failed at threshold "${threshold}".`, `Summary: ${result.summary.error} error(s), ${result.summary.warn} warning(s), ${result.summary.info} info finding(s), ${result.summary.hint} hint(s).`];
+	if (topFindings.length > 0) {
+		lines.push("Top findings:");
+		lines.push(...topFindings);
+	}
+	return lines.join("\n");
+};
+//#endregion
+//#region src/core/runtime.ts
+const createOpenApiLintRuntime = (options = {}) => {
+	const reporter = resolveReporter(options.logger);
+	const artifactWriteFailureMode = options.output?.artifactWriteFailures ?? "warn";
+	let inFlight = null;
+	const runtime = {
+		status: "idle",
+		startedAt: null,
+		completedAt: null,
+		durationMs: null,
+		latest: null,
+		lastSuccess: null,
+		lastFailure: null,
+		running: false,
+		async run(app) {
+			if (inFlight) return await inFlight;
+			inFlight = (async () => {
+				const startedAt = /* @__PURE__ */ new Date();
+				runtime.running = true;
+				runtime.status = "running";
+				runtime.startedAt = startedAt.toISOString();
+				runtime.completedAt = null;
+				runtime.durationMs = null;
+				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.`);
+					else if (loadedRuleset.source?.path) reporter.ruleset(`OpenAPI lint loaded ruleset ${loadedRuleset.source.path}.`);
+					const result = await lintOpenApi(spec, loadedRuleset.ruleset);
+					await writeOutputSinks(result, spec, options, artifactWriteFailureMode);
+					runtime.latest = result;
+					reporter.complete("OpenAPI lint completed.");
+					enforceThreshold(result, options.failOn ?? "error");
+					runtime.status = "passed";
+					runtime.lastSuccess = result;
+					finalizeRuntimeRun(runtime, startedAt);
+					return result;
+				} catch (error) {
+					runtime.status = "failed";
+					runtime.lastFailure = toRuntimeFailure(error);
+					finalizeRuntimeRun(runtime, startedAt);
+					throw error;
+				}
+			})();
+			try {
+				return await inFlight;
+			} finally {
+				runtime.running = false;
+				inFlight = null;
+			}
+		}
+	};
+	return runtime;
+};
+const finalizeRuntimeRun = (runtime, startedAt) => {
+	const completedAt = /* @__PURE__ */ new Date();
+	runtime.completedAt = completedAt.toISOString();
+	runtime.durationMs = completedAt.getTime() - startedAt.getTime();
+};
+const toRuntimeFailure = (error) => ({
+	name: error instanceof Error ? error.name : "Error",
+	message: error instanceof Error ? error.message : String(error),
+	generatedAt: (/* @__PURE__ */ new Date()).toISOString()
+});
+var OpenApiLintArtifactWriteError = class extends Error {
+	constructor(artifact, cause) {
+		super(`OpenAPI lint could not write ${artifact}: ${cause instanceof Error ? cause.message : String(cause)}`);
+		this.artifact = artifact;
+		this.cause = cause;
+		this.name = "OpenApiLintArtifactWriteError";
+	}
+};
+const handleArtifactWriteFailure = (artifact, error, mode, reporter) => {
+	const wrappedError = new OpenApiLintArtifactWriteError(artifact, error);
+	if (mode === "error") throw wrappedError;
+	reporter.warn(wrappedError.message);
+};
+const writeOutputSinks = async (result, spec, options, artifactWriteFailureMode) => {
+	const reporter = resolveReporter(options.logger);
+	const sinks = createOutputSinks(options);
+	for (const sink of sinks) try {
+		const artifacts = await sink.write(result, {
+			spec,
+			logger: reporter
+		});
+		if (artifacts) result.artifacts = mergeArtifacts(result.artifacts, artifacts);
+	} catch (error) {
+		if (sink.kind === "artifact") {
+			handleArtifactWriteFailure(sink.name, error, artifactWriteFailureMode, reporter);
+			continue;
+		}
+		throw error;
+	}
+};
+const mergeArtifacts = (current, next) => ({
+	...current,
+	...next
+});
+const isEnabled = (options = {}) => {
+	return resolveStartupMode(options) !== "off";
+};
+const resolveStartupMode = (options = {}) => {
+	if (options.startup?.mode) return options.startup.mode;
+	if (typeof options.enabled === "function") return options.enabled(process.env) ? "enforce" : "off";
+	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 };