@opsydyn/elysia-spectral 1.4.0 → 1.5.1

package/dist/load-ruleset-CiikrzWx.mjs

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

package/dist/presets-CCfU_diN.mjs

@@ -0,0 +1,132 @@
+import { t as __exportAll } from "./rolldown-runtime-wcPFST8Q.mjs";
+import { t as recommended } from "./recommended-DgrTqq-3.mjs";
+//#region src/presets/server.ts
+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: [["spectral:oas", "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"
+			}
+		},
+		"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",
+				functionOptions: { schema: {
+					type: "array",
+					minItems: 1
+				} }
+			}
+		},
+		"operation-description": "warn",
+		"operation-operationId": "warn",
+		"operation-success-response": "warn"
+	}
+};
+//#endregion
+//#region src/presets/strict.ts
+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: [["spectral: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
+var presets_exports = /* @__PURE__ */ __exportAll({
+	presets: () => presets,
+	recommended: () => recommended,
+	server: () => server,
+	strict: () => strict
+});
+const presets = {
+	recommended,
+	server,
+	strict
+};
+//#endregion
+export { server as i, presets_exports as n, strict as r, presets as t };

package/dist/recommended-DgrTqq-3.mjs

@@ -0,0 +1,40 @@
+//#region src/presets/recommended.ts
+const operationSelector = "$.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: [["spectral:oas", "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"
+			}
+		},
+		"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",
+				functionOptions: { schema: {
+					type: "array",
+					minItems: 1
+				} }
+			}
+		}
+	}
+};
+//#endregion
+export { recommended as t };

package/dist/rolldown-runtime-wcPFST8Q.mjs

@@ -0,0 +1,13 @@
+//#region \0rolldown/runtime.js
+var __defProp = Object.defineProperty;
+var __exportAll = (all, no_symbols) => {
+	let target = {};
+	for (var name in all) __defProp(target, name, {
+		get: all[name],
+		enumerable: true
+	});
+	if (!no_symbols) __defProp(target, Symbol.toStringTag, { value: "Module" });
+	return target;
+};
+//#endregion
+export { __exportAll as t };

package/dist/ruleset-load-error-CogUOC7W.mjs

@@ -0,0 +1,10 @@
+//#region src/core/ruleset-load-error.ts
+var RulesetLoadError = class extends Error {
+	constructor(message, options) {
+		super(message);
+		this.name = "RulesetLoadError";
+		if (options?.cause !== void 0) this.cause = options.cause;
+	}
+};
+//#endregion
+export { RulesetLoadError as t };