@ygorazambuja/sauron 1.0.0

package/src/index.ts

@@ -0,0 +1,47 @@
+import { main } from "./cli/main";
+
+export {
+	parseArgs,
+	parseCommand,
+	showHelp,
+} from "./cli/args";
+
+export {
+	createGeneratedFileHeader,
+	initConfigFile,
+	loadSauronConfig,
+	mergeOptionsWithConfig,
+} from "./cli/config";
+
+export { getOutputPaths, isAngularProject } from "./cli/project";
+export type { CliOptions, SauronConfig } from "./cli/types";
+
+export { generateAngularService } from "./generators/angular";
+export {
+	createFetchHttpMethods,
+	extractMethodParameters,
+	extractResponseType,
+	generateFetchService,
+	generateMethodName,
+} from "./generators/fetch";
+export {
+	createMissingSwaggerDefinitionsReport,
+	generateMissingSwaggerDefinitionsFile,
+} from "./generators/missing-definitions";
+export {
+	createTypeCoverageReport,
+	generateTypeCoverageReportFile,
+} from "./generators/type-coverage";
+export {
+	BUILTIN_PLUGIN_IDS,
+	createDefaultPluginRegistry,
+	createPluginRegistry,
+} from "./plugins/registry";
+export { runHttpPlugins } from "./plugins/runner";
+export type { PluginContext, SauronPlugin } from "./plugins/types";
+
+export { main };
+
+if (import.meta.main) {
+	main();
+}

package/src/plugins/builtin/angular.ts

@@ -0,0 +1,146 @@
+import { join } from "node:path";
+import { generateAngularService } from "../../generators/angular";
+import {
+	createMissingSwaggerDefinitionsReport,
+	generateMissingSwaggerDefinitionsFile,
+} from "../../generators/missing-definitions";
+import {
+	createTypeCoverageReport,
+	generateTypeCoverageReportFile,
+} from "../../generators/type-coverage";
+import { createAngularHttpClientMethods } from "../../utils";
+import type {
+	PluginCanRunResult,
+	PluginContext,
+	PluginGenerateResult,
+	PluginOutputPaths,
+	SauronPlugin,
+} from "../types";
+
+/**
+ * Create angular plugin.
+ * @returns Create angular plugin output as `SauronPlugin`.
+ * @example
+ * ```ts
+ * const result = createAngularPlugin();
+ * // result: SauronPlugin
+ * ```
+ */
+export function createAngularPlugin(): SauronPlugin {
+	return {
+		id: "angular",
+		aliases: ["ng"],
+		kind: "http-client",
+		canRun,
+		resolveOutputs,
+		generate,
+	};
+}
+
+/**
+ * Can run angular plugin.
+ * @param context Input parameter `context`.
+ * @returns Can run angular plugin output as `PluginCanRunResult`.
+ * @example
+ * ```ts
+ * const result = canRun({ isAngularProject: true } as PluginContext);
+ * // result: PluginCanRunResult
+ * ```
+ */
+function canRun(context: PluginContext): PluginCanRunResult {
+	if (context.isAngularProject) {
+		return { ok: true };
+	}
+
+	return {
+		ok: false,
+		reason:
+			"⚠️  Angular plugin requested but Angular project not detected. Falling back to fetch plugin.",
+		fallbackPluginId: "fetch",
+	};
+}
+
+/**
+ * Resolve angular plugin outputs.
+ * @param context Input parameter `context`.
+ * @returns Resolve angular plugin outputs output as `PluginOutputPaths`.
+ * @example
+ * ```ts
+ * const result = resolveOutputs({ baseOutputPath: "src/app/sauron" } as PluginContext);
+ * // result: PluginOutputPaths
+ * ```
+ */
+function resolveOutputs(context: PluginContext): PluginOutputPaths {
+	const serviceDirectory = join(context.baseOutputPath, "angular-http-client");
+	return {
+		servicePath: join(serviceDirectory, "sauron-api.service.ts"),
+		reportPath: join(serviceDirectory, "missing-swagger-definitions.json"),
+		typeCoverageReportPath: join(serviceDirectory, "type-coverage-report.json"),
+	};
+}
+
+/**
+ * Generate angular plugin files.
+ * @param context Input parameter `context`.
+ * @returns Generate angular plugin files output as `Promise<PluginGenerateResult>`.
+ * @example
+ * ```ts
+ * const result = await generate({} as PluginContext);
+ * // result: PluginGenerateResult
+ * ```
+ */
+async function generate(
+	context: PluginContext,
+): Promise<PluginGenerateResult> {
+	const {
+		methods: angularMethods,
+		imports: angularImports,
+		paramsInterfaces: angularParamsInterfaces,
+	} = createAngularHttpClientMethods(
+		context.schema,
+		context.operationTypes,
+		context.typeNameMap,
+	);
+	const angularService = generateAngularService(
+		angularMethods,
+		angularImports,
+		true,
+		angularParamsInterfaces,
+	);
+	const outputPaths = resolveOutputs(context);
+
+	const missingDefinitionsReport = createMissingSwaggerDefinitionsReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const reportFileContent = generateMissingSwaggerDefinitionsFile(
+		missingDefinitionsReport,
+	);
+	const typeCoverageReport = createTypeCoverageReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const typeCoverageFileContent =
+		generateTypeCoverageReportFile(typeCoverageReport);
+	const files = [
+		{
+			path: outputPaths.servicePath,
+			content: `${context.fileHeader}\n${angularService}`,
+		},
+		{
+			path: outputPaths.reportPath,
+			content: reportFileContent,
+		},
+	];
+	if (outputPaths.typeCoverageReportPath) {
+		files.push({
+			path: outputPaths.typeCoverageReportPath,
+			content: typeCoverageFileContent,
+		});
+	}
+
+	return {
+		files,
+		methodCount: angularMethods.length,
+	};
+}

package/src/plugins/builtin/axios.ts

@@ -0,0 +1,307 @@
+import { join } from "node:path";
+import {
+	createMissingSwaggerDefinitionsReport,
+	generateMissingSwaggerDefinitionsFile,
+} from "../../generators/missing-definitions";
+import { createFetchHttpMethods } from "../../generators/fetch";
+import {
+	createTypeCoverageReport,
+	generateTypeCoverageReportFile,
+} from "../../generators/type-coverage";
+import type {
+	PluginCanRunResult,
+	PluginContext,
+	PluginGenerateResult,
+	PluginOutputPaths,
+	SauronPlugin,
+} from "../types";
+
+/**
+ * Create axios plugin.
+ * @returns Create axios plugin output as `SauronPlugin`.
+ * @example
+ * ```ts
+ * const result = createAxiosPlugin();
+ * // result: SauronPlugin
+ * ```
+ */
+export function createAxiosPlugin(): SauronPlugin {
+	return {
+		id: "axios",
+		aliases: ["ax"],
+		kind: "http-client",
+		canRun,
+		resolveOutputs,
+		generate,
+	};
+}
+
+/**
+ * Can run axios plugin.
+ * @param _context Input parameter `_context`.
+ * @returns Can run axios plugin output as `PluginCanRunResult`.
+ * @example
+ * ```ts
+ * const result = canRun({} as PluginContext);
+ * // result: PluginCanRunResult
+ * ```
+ */
+function canRun(_context: PluginContext): PluginCanRunResult {
+	return { ok: true };
+}
+
+/**
+ * Resolve axios plugin outputs.
+ * @param context Input parameter `context`.
+ * @returns Resolve axios plugin outputs output as `PluginOutputPaths`.
+ * @example
+ * ```ts
+ * const result = resolveOutputs({ baseOutputPath: "outputs" } as PluginContext);
+ * // result: PluginOutputPaths
+ * ```
+ */
+function resolveOutputs(context: PluginContext): PluginOutputPaths {
+	const serviceDirectory = join(context.baseOutputPath, "http-client");
+	return {
+		servicePath: join(serviceDirectory, "sauron-api.axios-client.ts"),
+		reportPath: join(
+			serviceDirectory,
+			"missing-swagger-definitions.axios.json",
+		),
+		typeCoverageReportPath: join(
+			serviceDirectory,
+			"type-coverage-report.axios.json",
+		),
+	};
+}
+
+/**
+ * Generate axios plugin files.
+ * @param context Input parameter `context`.
+ * @returns Generate axios plugin files output as `Promise<PluginGenerateResult>`.
+ * @example
+ * ```ts
+ * const result = await generate({} as PluginContext);
+ * // result: PluginGenerateResult
+ * ```
+ */
+async function generate(
+	context: PluginContext,
+): Promise<PluginGenerateResult> {
+	const usedTypes = new Set<string>();
+	const {
+		methods: fetchMethods,
+		paramsInterfaces,
+	} = createFetchHttpMethods(
+		context.schema,
+		usedTypes,
+		context.operationTypes,
+		context.typeNameMap,
+	);
+	const axiosMethods = fetchMethods.map((method) =>
+		convertFetchMethodToAxios(method),
+	);
+	const axiosService = generateAxiosService(
+		axiosMethods,
+		usedTypes,
+		paramsInterfaces,
+	);
+	const outputPaths = resolveOutputs(context);
+
+	const missingDefinitionsReport = createMissingSwaggerDefinitionsReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const reportFileContent = generateMissingSwaggerDefinitionsFile(
+		missingDefinitionsReport,
+	);
+	const typeCoverageReport = createTypeCoverageReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const typeCoverageFileContent =
+		generateTypeCoverageReportFile(typeCoverageReport);
+	const files = [
+		{
+			path: outputPaths.servicePath,
+			content: `${context.fileHeader}\n${axiosService}`,
+		},
+		{
+			path: outputPaths.reportPath,
+			content: reportFileContent,
+		},
+	];
+	if (outputPaths.typeCoverageReportPath) {
+		files.push({
+			path: outputPaths.typeCoverageReportPath,
+			content: typeCoverageFileContent,
+		});
+	}
+
+	return {
+		files,
+		methodCount: axiosMethods.length,
+	};
+}
+
+/**
+ * Convert fetch method to axios adapter method.
+ * @param fetchMethod Input parameter `fetchMethod`.
+ * @returns Convert fetch method to axios adapter method output as `string`.
+ * @example
+ * ```ts
+ * const result = convertFetchMethodToAxios("const response = await fetch(url, {});");
+ * // result: string
+ * ```
+ */
+function convertFetchMethodToAxios(fetchMethod: string): string {
+	return fetchMethod.replace(
+		"const response = await fetch(",
+		"const response = await this.fetchWithAxios(",
+	);
+}
+
+/**
+ * Generate axios service.
+ * @param methods Input parameter `methods`.
+ * @param usedTypes Input parameter `usedTypes`.
+ * @param paramsInterfaces Input parameter `paramsInterfaces`.
+ * @returns Generate axios service output as `string`.
+ * @example
+ * ```ts
+ * const result = generateAxiosService([], new Set<string>(), []);
+ * // result: string
+ * ```
+ */
+function generateAxiosService(
+	methods: string[],
+	usedTypes: Set<string>,
+	paramsInterfaces: string[],
+): string {
+	const importStatement = buildModelImportStatement(usedTypes);
+	const interfacesBlock = buildInterfacesBlock(paramsInterfaces);
+
+	return `// Generated axios-based HTTP client
+import axios, { type AxiosError, type AxiosInstance } from "axios";
+import qs from "query-string";
+${importStatement}
+${interfacesBlock}
+
+type AxiosFetchConfig = {
+  method?: string;
+  headers?: Record<string, string>;
+  body?: string;
+};
+
+type AxiosLikeResponse = {
+  ok: boolean;
+  status: number;
+  json(): Promise<unknown>;
+};
+
+function createAxiosLikeResponse(status: number, data: unknown, ok: boolean): AxiosLikeResponse {
+  return {
+    ok,
+    status,
+    async json() {
+      return data;
+    },
+  };
+}
+
+export class SauronAxiosApiClient {
+  private baseUrl = "";
+  private readonly httpClient: AxiosInstance;
+
+  constructor(baseUrl?: string, httpClient: AxiosInstance = axios.create()) {
+    this.httpClient = httpClient;
+    if (baseUrl) {
+      this.baseUrl = baseUrl;
+    }
+  }
+
+  setBaseUrl(baseUrl: string): void {
+    this.baseUrl = baseUrl;
+  }
+
+  private buildUrl(path: string): string {
+    if (/^(https?:)?\\/\\//i.test(path)) {
+      return path;
+    }
+
+    const normalizedBase = this.baseUrl.replace(/\\/+$/, "");
+    const normalizedPath = path.startsWith("/") ? path : \`/\${path}\`;
+
+    if (!normalizedBase) {
+      return normalizedPath;
+    }
+
+    return \`\${normalizedBase}\${normalizedPath}\`;
+  }
+
+  private async fetchWithAxios(
+    url: string,
+    config: AxiosFetchConfig,
+  ): Promise<AxiosLikeResponse> {
+    try {
+      const response = await this.httpClient.request({
+        url,
+        method: config.method,
+        headers: config.headers,
+        data: config.body,
+      });
+      return createAxiosLikeResponse(response.status, response.data, true);
+    } catch (error) {
+      const axiosError = error as AxiosError;
+      const response = axiosError.response;
+      if (response) {
+        return createAxiosLikeResponse(response.status, response.data, false);
+      }
+
+      throw error;
+    }
+  }
+
+${methods.join("\n\n")}
+}
+
+export const sauronAxiosApi = new SauronAxiosApiClient();
+`;
+}
+
+/**
+ * Build model import statement.
+ * @param usedTypes Input parameter `usedTypes`.
+ * @returns Build model import statement output as `string`.
+ * @example
+ * ```ts
+ * const result = buildModelImportStatement(new Set<string>());
+ * // result: string
+ * ```
+ */
+function buildModelImportStatement(usedTypes: Set<string>): string {
+	if (usedTypes.size === 0) {
+		return "";
+	}
+
+	const importList = Array.from(usedTypes).join(", ");
+	return `import { ${importList} } from "../models";`;
+}
+
+/**
+ * Build interfaces block.
+ * @param paramsInterfaces Input parameter `paramsInterfaces`.
+ * @returns Build interfaces block output as `string`.
+ * @example
+ * ```ts
+ * const result = buildInterfacesBlock([]);
+ * // result: string
+ * ```
+ */
+function buildInterfacesBlock(paramsInterfaces: string[]): string {
+	if (paramsInterfaces.length === 0) {
+		return "";
+	}
+
+	return `${paramsInterfaces.join("\n\n")}\n`;
+}

package/src/plugins/builtin/fetch.ts

@@ -0,0 +1,140 @@
+import { join } from "node:path";
+import {
+	createMissingSwaggerDefinitionsReport,
+	generateMissingSwaggerDefinitionsFile,
+} from "../../generators/missing-definitions";
+import {
+	createTypeCoverageReport,
+	generateTypeCoverageReportFile,
+} from "../../generators/type-coverage";
+import {
+	createFetchHttpMethods,
+	generateFetchService,
+} from "../../generators/fetch";
+import type {
+	PluginCanRunResult,
+	PluginContext,
+	PluginGenerateResult,
+	PluginOutputPaths,
+	SauronPlugin,
+} from "../types";
+
+/**
+ * Create fetch plugin.
+ * @returns Create fetch plugin output as `SauronPlugin`.
+ * @example
+ * ```ts
+ * const result = createFetchPlugin();
+ * // result: SauronPlugin
+ * ```
+ */
+export function createFetchPlugin(): SauronPlugin {
+	return {
+		id: "fetch",
+		aliases: ["http", "http-client"],
+		kind: "http-client",
+		canRun,
+		resolveOutputs,
+		generate,
+	};
+}
+
+/**
+ * Can run fetch plugin.
+ * @param _context Input parameter `_context`.
+ * @returns Can run fetch plugin output as `PluginCanRunResult`.
+ * @example
+ * ```ts
+ * const result = canRun({} as PluginContext);
+ * // result: PluginCanRunResult
+ * ```
+ */
+function canRun(_context: PluginContext): PluginCanRunResult {
+	return { ok: true };
+}
+
+/**
+ * Resolve fetch plugin outputs.
+ * @param context Input parameter `context`.
+ * @returns Resolve fetch plugin outputs output as `PluginOutputPaths`.
+ * @example
+ * ```ts
+ * const result = resolveOutputs({ baseOutputPath: "outputs" } as PluginContext);
+ * // result: PluginOutputPaths
+ * ```
+ */
+function resolveOutputs(context: PluginContext): PluginOutputPaths {
+	const serviceDirectory = join(context.baseOutputPath, "http-client");
+	return {
+		servicePath: join(serviceDirectory, "sauron-api.client.ts"),
+		reportPath: join(serviceDirectory, "missing-swagger-definitions.json"),
+		typeCoverageReportPath: join(serviceDirectory, "type-coverage-report.json"),
+	};
+}
+
+/**
+ * Generate fetch plugin files.
+ * @param context Input parameter `context`.
+ * @returns Generate fetch plugin files output as `Promise<PluginGenerateResult>`.
+ * @example
+ * ```ts
+ * const result = await generate({} as PluginContext);
+ * // result: PluginGenerateResult
+ * ```
+ */
+async function generate(
+	context: PluginContext,
+): Promise<PluginGenerateResult> {
+	const usedTypes = new Set<string>();
+	const {
+		methods: fetchMethods,
+		paramsInterfaces: fetchParamsInterfaces,
+	} = createFetchHttpMethods(
+		context.schema,
+		usedTypes,
+		context.operationTypes,
+		context.typeNameMap,
+	);
+	const fetchService = generateFetchService(
+		fetchMethods,
+		context.modelsPath,
+		usedTypes,
+		fetchParamsInterfaces,
+	);
+	const outputPaths = resolveOutputs(context);
+
+	const missingDefinitionsReport = createMissingSwaggerDefinitionsReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const reportFileContent = generateMissingSwaggerDefinitionsFile(
+		missingDefinitionsReport,
+	);
+	const typeCoverageReport = createTypeCoverageReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const typeCoverageFileContent =
+		generateTypeCoverageReportFile(typeCoverageReport);
+	const files = [
+		{
+			path: outputPaths.servicePath,
+			content: `${context.fileHeader}\n${fetchService}`,
+		},
+		{
+			path: outputPaths.reportPath,
+			content: reportFileContent,
+		},
+	];
+	if (outputPaths.typeCoverageReportPath) {
+		files.push({
+			path: outputPaths.typeCoverageReportPath,
+			content: typeCoverageFileContent,
+		});
+	}
+
+	return {
+		files,
+		methodCount: fetchMethods.length,
+	};
+}

package/src/plugins/registry.ts

@@ -0,0 +1,84 @@
+import { createAngularPlugin } from "./builtin/angular";
+import { createAxiosPlugin } from "./builtin/axios";
+import { createFetchPlugin } from "./builtin/fetch";
+import type { SauronPlugin } from "./types";
+
+/**
+ * Built-in plugin IDs.
+ */
+export const BUILTIN_PLUGIN_IDS = ["fetch", "angular", "axios"] as const;
+
+/**
+ * Plugin registry.
+ */
+export type PluginRegistry = {
+	getAll(): SauronPlugin[];
+	resolve(idOrAlias: string): SauronPlugin | undefined;
+};
+
+/**
+ * Create plugin registry.
+ * @param plugins Input parameter `plugins`.
+ * @returns Create plugin registry output as `PluginRegistry`.
+ * @example
+ * ```ts
+ * const result = createPluginRegistry([]);
+ * // result: PluginRegistry
+ * ```
+ */
+export function createPluginRegistry(plugins: SauronPlugin[]): PluginRegistry {
+	const allPlugins = [...plugins];
+	const idMap = createPluginIdMap(allPlugins);
+
+	return {
+		getAll: () => [...allPlugins],
+		resolve: (idOrAlias: string) => {
+			const normalized = idOrAlias.trim().toLowerCase();
+			if (!normalized) {
+				return undefined;
+			}
+			return idMap.get(normalized);
+		},
+	};
+}
+
+/**
+ * Create default plugin registry.
+ * @returns Create default plugin registry output as `PluginRegistry`.
+ * @example
+ * ```ts
+ * const result = createDefaultPluginRegistry();
+ * // result: PluginRegistry
+ * ```
+ */
+export function createDefaultPluginRegistry(): PluginRegistry {
+	return createPluginRegistry([
+		createFetchPlugin(),
+		createAngularPlugin(),
+		createAxiosPlugin(),
+	]);
+}
+
+/**
+ * Create plugin ID map.
+ * @param plugins Input parameter `plugins`.
+ * @returns Create plugin ID map output as `Map<string, SauronPlugin>`.
+ * @example
+ * ```ts
+ * const result = createPluginIdMap([]);
+ * // result: Map<string, SauronPlugin>
+ * ```
+ */
+function createPluginIdMap(plugins: SauronPlugin[]): Map<string, SauronPlugin> {
+	const idMap = new Map<string, SauronPlugin>();
+
+	for (const plugin of plugins) {
+		idMap.set(plugin.id.toLowerCase(), plugin);
+		const aliases = plugin.aliases ?? [];
+		for (const alias of aliases) {
+			idMap.set(alias.toLowerCase(), plugin);
+		}
+	}
+
+	return idMap;
+}