@ygorazambuja/sauron 1.0.0

package/src/plugins/runner.ts

@@ -0,0 +1,174 @@
+import { dirname } from "node:path";
+import { mkdirSync } from "node:fs";
+import { createDefaultPluginRegistry, type PluginRegistry } from "./registry";
+import type {
+	PluginCanRunFailure,
+	PluginContext,
+	PluginExecutionResult,
+	PluginFile,
+	SauronPlugin,
+} from "./types";
+
+/**
+ * Run HTTP plugins.
+ * @param requestedPluginIds Input parameter `requestedPluginIds`.
+ * @param context Input parameter `context`.
+ * @param registry Input parameter `registry`.
+ * @returns Run HTTP plugins output as `Promise<PluginExecutionResult[]>`.
+ * @example
+ * ```ts
+ * const result = await runHttpPlugins([], {} as PluginContext);
+ * // result: PluginExecutionResult[]
+ * ```
+ */
+export async function runHttpPlugins(
+	requestedPluginIds: string[],
+	context: PluginContext,
+	registry = createDefaultPluginRegistry(),
+): Promise<PluginExecutionResult[]> {
+	if (requestedPluginIds.length === 0) {
+		return [];
+	}
+
+	const results: PluginExecutionResult[] = [];
+	for (const requestedPluginId of requestedPluginIds) {
+		const requestedPlugin = resolvePluginOrThrow(requestedPluginId, registry);
+		const executablePlugin = resolveRunnablePlugin(
+			requestedPlugin,
+			context,
+			registry,
+			new Set<string>(),
+		);
+		const outputPaths = executablePlugin.resolveOutputs(context);
+		const generated = await executablePlugin.generate(context);
+		await writePluginFiles(generated.files, context);
+		const result: PluginExecutionResult = {
+			requestedPluginId,
+			executedPluginId: executablePlugin.id,
+			methodCount: generated.methodCount,
+			servicePath: outputPaths.servicePath,
+			reportPath: outputPaths.reportPath,
+		};
+		if (outputPaths.typeCoverageReportPath) {
+			result.typeCoverageReportPath = outputPaths.typeCoverageReportPath;
+		}
+		results.push(result);
+	}
+
+	return results;
+}
+
+/**
+ * Resolve runnable plugin.
+ * @param plugin Input parameter `plugin`.
+ * @param context Input parameter `context`.
+ * @param registry Input parameter `registry`.
+ * @param visitedPluginIds Input parameter `visitedPluginIds`.
+ * @returns Resolve runnable plugin output as `SauronPlugin`.
+ * @example
+ * ```ts
+ * const result = resolveRunnablePlugin(
+ *  { id: "fetch", kind: "http-client", canRun: () => ({ ok: true }), resolveOutputs: () => ({ servicePath: "", reportPath: "" }), generate: async () => ({ files: [], methodCount: 0 }) },
+ *  {} as PluginContext,
+ *  createDefaultPluginRegistry(),
+ *  new Set<string>(),
+ * );
+ * // result: SauronPlugin
+ * ```
+ */
+function resolveRunnablePlugin(
+	plugin: SauronPlugin,
+	context: PluginContext,
+	registry: PluginRegistry,
+	visitedPluginIds: Set<string>,
+): SauronPlugin {
+	if (visitedPluginIds.has(plugin.id)) {
+		throw new Error(
+			`Circular fallback detected while resolving plugin "${plugin.id}".`,
+		);
+	}
+
+	visitedPluginIds.add(plugin.id);
+	const canRunResult = plugin.canRun(context);
+	if (canRunResult.ok) {
+		return plugin;
+	}
+
+	warnPluginFailure(canRunResult);
+	if (!canRunResult.fallbackPluginId) {
+		throw new Error(
+			`Plugin "${plugin.id}" cannot run: ${canRunResult.reason}`,
+		);
+	}
+
+	const fallbackPlugin = resolvePluginOrThrow(
+		canRunResult.fallbackPluginId,
+		registry,
+	);
+	return resolveRunnablePlugin(
+		fallbackPlugin,
+		context,
+		registry,
+		visitedPluginIds,
+	);
+}
+
+/**
+ * Resolve plugin or throw.
+ * @param pluginId Input parameter `pluginId`.
+ * @param registry Input parameter `registry`.
+ * @returns Resolve plugin or throw output as `SauronPlugin`.
+ * @example
+ * ```ts
+ * const result = resolvePluginOrThrow("fetch", createDefaultPluginRegistry());
+ * // result: SauronPlugin
+ * ```
+ */
+function resolvePluginOrThrow(
+	pluginId: string,
+	registry: PluginRegistry,
+): SauronPlugin {
+	const plugin = registry.resolve(pluginId);
+	if (plugin) {
+		return plugin;
+	}
+
+	throw new Error(`Unknown plugin "${pluginId}".`);
+}
+
+/**
+ * Warn plugin failure.
+ * @param canRunFailure Input parameter `canRunFailure`.
+ * @example
+ * ```ts
+ * warnPluginFailure({ ok: false, reason: "fallback", fallbackPluginId: "fetch" });
+ * ```
+ */
+function warnPluginFailure(canRunFailure: PluginCanRunFailure): void {
+	if (!canRunFailure.reason) {
+		return;
+	}
+
+	console.warn(canRunFailure.reason);
+}
+
+/**
+ * Write plugin files.
+ * @param files Input parameter `files`.
+ * @param context Input parameter `context`.
+ * @returns Write plugin files output as `Promise<void>`.
+ * @example
+ * ```ts
+ * const result = await writePluginFiles([], {} as PluginContext);
+ * // result: void
+ * ```
+ */
+async function writePluginFiles(
+	files: PluginFile[],
+	context: PluginContext,
+): Promise<void> {
+	for (const file of files) {
+		mkdirSync(dirname(file.path), { recursive: true });
+		await context.writeFormattedFile(file.path, file.content);
+	}
+}

package/src/plugins/types.ts

@@ -0,0 +1,97 @@
+import type { z } from "zod";
+import type { CliOptions } from "../cli/types";
+import type { SwaggerOrOpenAPISchema } from "../schemas/swagger";
+import type { OperationTypeMap, TypeNameMap } from "../utils";
+
+/**
+ * Plugin kind.
+ */
+export type PluginKind = "http-client";
+
+/**
+ * Plugin can run success result.
+ */
+export type PluginCanRunSuccess = {
+	ok: true;
+};
+
+/**
+ * Plugin can run failure result.
+ */
+export type PluginCanRunFailure = {
+	ok: false;
+	reason: string;
+	fallbackPluginId?: string;
+};
+
+/**
+ * Plugin can run result.
+ */
+export type PluginCanRunResult = PluginCanRunSuccess | PluginCanRunFailure;
+
+/**
+ * Generated plugin file.
+ */
+export type PluginFile = {
+	path: string;
+	content: string;
+};
+
+/**
+ * Plugin output paths.
+ */
+export type PluginOutputPaths = {
+	servicePath: string;
+	reportPath: string;
+	typeCoverageReportPath?: string;
+};
+
+/**
+ * Plugin generation result.
+ */
+export type PluginGenerateResult = {
+	files: PluginFile[];
+	methodCount: number;
+};
+
+/**
+ * Plugin context.
+ */
+export type PluginContext = {
+	schema: z.infer<typeof SwaggerOrOpenAPISchema>;
+	options: CliOptions;
+	baseOutputPath: string;
+	modelsPath: string;
+	fileHeader: string;
+	operationTypes: OperationTypeMap;
+	typeNameMap: TypeNameMap;
+	isAngularProject: boolean;
+	writeFormattedFile: (
+		filePath: string,
+		content: string,
+	) => Promise<void>;
+};
+
+/**
+ * Sauron plugin definition.
+ */
+export interface SauronPlugin {
+	id: string;
+	aliases?: string[];
+	kind: PluginKind;
+	canRun(context: PluginContext): PluginCanRunResult;
+	resolveOutputs(context: PluginContext): PluginOutputPaths;
+	generate(context: PluginContext): Promise<PluginGenerateResult>;
+}
+
+/**
+ * Plugin execution result.
+ */
+export type PluginExecutionResult = {
+	requestedPluginId: string;
+	executedPluginId: string;
+	methodCount: number;
+	servicePath: string;
+	reportPath: string;
+	typeCoverageReportPath?: string;
+};

package/src/schemas/swagger.ts

@@ -0,0 +1,134 @@
+import { z } from "zod";
+
+// --- 1. Schemas de Nível Mais Baixo (Responses, Methods) ---
+
+/**
+ * Representa o Response Object (OpenAPI 3.0)
+ * Foca apenas na descrição, que é obrigatória.
+ */
+const ResponseSchema = z
+	.object({
+		description: z.string().min(1, "A descrição da resposta é obrigatória."),
+		// Campos como 'content' e 'headers' seriam adicionados aqui
+	})
+	.passthrough();
+
+/**
+ * Representa o Operation Object (OpenAPI 3.0), como 'get', 'post', etc.
+ * Foca em 'responses' (opcional para tolerar specs incompletos).
+ */
+const HttpMethodSchema = z
+	.object({
+		tags: z.array(z.string()).optional(),
+		responses: z
+			.record(
+				z.string().regex(/^(\d{3}|default)$/), // Chave é o código de status HTTP (ex: "200") ou "default" para Swagger 2.0
+				ResponseSchema,
+			)
+			.optional(),
+		// Campos como 'parameters' e 'requestBody' seriam opcionais aqui
+	})
+	.passthrough();
+
+/**
+ * Representa o Path Item Object (OpenAPI 3.0)
+ * Contém os métodos HTTP permitidos para um único caminho (path).
+ */
+const PathItemSchema = z
+	.object({
+		get: HttpMethodSchema.optional(),
+		post: HttpMethodSchema.optional(),
+		put: HttpMethodSchema.optional(),
+		delete: HttpMethodSchema.optional(),
+		// Adicione outros métodos se necessário, como head, patch, etc.
+	})
+	.partial(); // Usamos .partial() para que os métodos sejam opcionais no Path Item
+
+// --- 2. Schemas de Nível Superior (Info, Paths) ---
+
+/**
+ * Representa o Info Object (OpenAPI 3.0)
+ * Requer 'title' e 'version'.
+ */
+const InfoSchema = z
+	.object({
+		title: z.string().min(1, "O título da API é obrigatório."),
+		version: z.string().min(1, "A versão da API é obrigatória."),
+		// Campos como 'description' e 'license' seriam opcionais
+	})
+	.passthrough();
+
+/**
+ * Representa o Paths Object (OpenAPI 3.0)
+ * É um mapa (record) onde a chave é o path e o valor é o PathItemSchema.
+ */
+export const PathsSchema = z.record(
+	z.string().startsWith("/"), // A chave deve ser uma string de path (ex: "/users")
+	PathItemSchema,
+);
+
+export const ComponentsSchema = z
+	.object({
+		schemas: z.record(z.string(), z.any()), // Onde os DTOs reais seriam validados
+		securitySchemes: z.record(z.string(), z.any()).optional(),
+		// Simplificado. Adicione mais componentes se precisar de validação rigorosa.
+	})
+	.passthrough();
+
+// --- 3. Schemas Raiz (OpenAPI e Swagger Objects) ---
+
+/**
+ * Representa o Objeto Swagger 2.0 Raiz (swagger.json)
+ * Valida os campos obrigatórios e essenciais para Swagger 2.0.
+ */
+export const SwaggerBasicSchema = z
+	.object({
+		swagger: z.string().startsWith("2.0", "Deve ser uma versão Swagger 2.0."), // Garante a versão 2.0
+		info: InfoSchema,
+		host: z.string().optional(),
+		basePath: z.string().optional(),
+		schemes: z.array(z.string()).optional(),
+		consumes: z.array(z.string()).optional(),
+		produces: z.array(z.string()).optional(),
+		paths: PathsSchema,
+		definitions: z.record(z.string(), z.any()).optional(), // Swagger 2.0 usa 'definitions' em vez de 'components.schemas'
+		parameters: z.record(z.string(), z.any()).optional(),
+		responses: z.record(z.string(), z.any()).optional(),
+		securityDefinitions: z.record(z.string(), z.any()).optional(),
+		security: z.array(z.any()).optional(),
+		tags: z
+			.array(
+				z.object({
+					name: z.string(),
+					description: z.string().optional(),
+					externalDocs: z.any().optional(),
+				}),
+			)
+			.optional(),
+		externalDocs: z.any().optional(),
+		// Outros campos opcionais do Swagger 2.0
+	})
+	.passthrough();
+
+/**
+ * Representa o Objeto OpenAPI 3.0+ Raiz (swagger.json)
+ * Valida os campos obrigatórios e essenciais.
+ */
+export const OpenAPIBasicSchema = z
+	.object({
+		openapi: z.string().startsWith("3.0", "Deve ser uma versão OpenAPI 3.x.x."), // Garante a versão 3.x.x
+		info: InfoSchema,
+		paths: PathsSchema,
+		components: ComponentsSchema.optional(),
+		// components: ... Adicione a validação dos componentes se necessário
+		// security: ...
+	})
+	.passthrough();
+
+/**
+ * Union schema que aceita tanto OpenAPI 3.0+ quanto Swagger 2.0
+ */
+export const SwaggerOrOpenAPISchema = z.union([
+	OpenAPIBasicSchema,
+	SwaggerBasicSchema,
+]);