@ygorazambuja/sauron 1.0.0

package/docs/plugins.md

@@ -0,0 +1,154 @@
+# Plugin Development Guide
+
+Este guia descreve como criar um novo plugin HTTP no Sauron.
+
+## Visao geral
+
+O plugin system atual cobre geracao HTTP. O fluxo principal esta em:
+
+- `src/plugins/types.ts`
+- `src/plugins/registry.ts`
+- `src/plugins/runner.ts`
+- `src/plugins/builtin/`
+
+O `main` gera models no core e delega clientes HTTP ao `runHttpPlugins`.
+
+## Contrato do plugin
+
+Todo plugin deve implementar `SauronPlugin` (em `src/plugins/types.ts`):
+
+- `id: string`
+- `aliases?: string[]`
+- `kind: "http-client"`
+- `canRun(context): { ok: true } | { ok: false; reason: string; fallbackPluginId?: string }`
+- `resolveOutputs(context): { servicePath: string; reportPath: string }`
+- `generate(context): Promise<{ files: Array<{ path: string; content: string }>; methodCount: number }>`
+
+`PluginContext` oferece os dados necessarios:
+
+- schema OpenAPI validado (`schema`)
+- tipos derivados por operacao (`operationTypes`, `typeNameMap`)
+- opcoes resolvidas (`options`)
+- caminhos de saida (`baseOutputPath`, `modelsPath`)
+- cabecalho padrao (`fileHeader`)
+- status de projeto Angular (`isAngularProject`)
+- escritor formatado (`writeFormattedFile`)
+
+## Passo a passo para criar um plugin
+
+1. Criar arquivo em `src/plugins/builtin/<nome>.ts`.
+2. Implementar `create<Nome>Plugin(): SauronPlugin`.
+3. Definir `canRun`.
+4. Definir `resolveOutputs` com paths estaveis do plugin.
+5. Definir `generate` para retornar todos os arquivos do plugin.
+6. Incluir relatorio de definicoes ausentes no `generate`.
+7. Registrar plugin em `src/plugins/registry.ts`.
+8. Atualizar ajuda de CLI em `src/cli/args.ts` (opcoes de `--plugin`).
+9. Adicionar/atualizar testes de registry e main.
+
+## Template minimo
+
+```ts
+import { join } from "node:path";
+import {
+	createMissingSwaggerDefinitionsReport,
+	generateMissingSwaggerDefinitionsFile,
+} from "../../generators/missing-definitions";
+import type {
+	PluginCanRunResult,
+	PluginContext,
+	PluginGenerateResult,
+	PluginOutputPaths,
+	SauronPlugin,
+} from "../types";
+
+export function createExamplePlugin(): SauronPlugin {
+	return {
+		id: "example",
+		aliases: ["ex"],
+		kind: "http-client",
+		canRun,
+		resolveOutputs,
+		generate,
+	};
+}
+
+function canRun(_context: PluginContext): PluginCanRunResult {
+	return { ok: true };
+}
+
+function resolveOutputs(context: PluginContext): PluginOutputPaths {
+	const serviceDirectory = join(context.baseOutputPath, "http-client");
+	return {
+		servicePath: join(serviceDirectory, "sauron-api.example-client.ts"),
+		reportPath: join(serviceDirectory, "missing-swagger-definitions.example.json"),
+	};
+}
+
+async function generate(context: PluginContext): Promise<PluginGenerateResult> {
+	const serviceSource = `export class ExampleClient {}`;
+	const outputPaths = resolveOutputs(context);
+
+	const missingDefinitionsReport = createMissingSwaggerDefinitionsReport(
+		context.schema,
+		context.operationTypes,
+	);
+	const reportFileContent = generateMissingSwaggerDefinitionsFile(
+		missingDefinitionsReport,
+	);
+
+	return {
+		files: [
+			{
+				path: outputPaths.servicePath,
+				content: `${context.fileHeader}\n${serviceSource}`,
+			},
+			{
+				path: outputPaths.reportPath,
+				content: reportFileContent,
+			},
+		],
+		methodCount: 0,
+	};
+}
+```
+
+## Registro do plugin
+
+Em `src/plugins/registry.ts`:
+
+1. Importar `createExamplePlugin`.
+2. Adicionar o id em `BUILTIN_PLUGIN_IDS`.
+3. Incluir instancia no `createDefaultPluginRegistry`.
+
+## Fallbacks
+
+Use fallback quando o plugin nao puder rodar no contexto atual.
+
+Exemplo (plugin angular):
+
+- `canRun` retorna `{ ok: false, reason: "...", fallbackPluginId: "fetch" }`
+- runner resolve automaticamente o fallback
+
+## Testes recomendados
+
+- `src/plugins/registry.spec.ts`
+- `src/plugins/runner.spec.ts`
+- `src/cli/main.spec.ts`
+
+Cenarios minimos:
+
+- resolve por `id`
+- resolve por `alias`
+- erro para plugin desconhecido
+- geracao de arquivo do novo plugin
+- fallback (se aplicavel)
+- compatibilidade com aliases de CLI (`--http`, `--angular`)
+
+## Boas praticas
+
+- Reaproveitar geradores existentes sempre que possivel.
+- Manter o plugin focado em uma responsabilidade (geracao HTTP).
+- Gerar caminho de output previsivel e estavel.
+- Incluir o relatorio de definicoes ausentes em todos os plugins HTTP.
+- Evitar quebrar comportamento legado sem migracao clara.

package/package.json

@@ -0,0 +1,59 @@
+{
+	"name": "@ygorazambuja/sauron",
+	"version": "1.0.0",
+	"description": "OpenAPI to TypeScript/Angular Converter - Generate TypeScript interfaces and Angular HTTP services from Swagger/OpenAPI specs",
+	"main": "src/index.ts",
+	"files": [
+		"bin.ts",
+		"src/**/*.ts",
+		"!src/**/*.spec.ts",
+		"!src/**/*.test.ts",
+		"!src/app/sauron/**",
+		"README.md",
+		"docs/plugins.md"
+	],
+	"bin": {
+		"sauron": "./bin.ts"
+	},
+	"engines": {
+		"bun": ">=1.3.0"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"start": "bun run src/index.ts",
+		"dev": "bun run src/index.ts",
+		"test": "bun test",
+		"test:watch": "bun test --watch",
+		"test:coverage": "bun test --coverage",
+		"build": "bun build --compile ./src/index.ts --outfile sauron",
+		"cli": "bun run ./bin.ts",
+		"format": "biome check --fix"
+	},
+	"keywords": [
+		"openapi",
+		"swagger",
+		"typescript",
+		"angular",
+		"http-client",
+		"api-client",
+		"code-generator"
+	],
+	"author": "Ygor Correa Azambuja",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/ygorazambuja/sauron"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.3.15",
+		"@types/bun": "^1.3.9",
+		"bun-types": "^1.3.9"
+	},
+	"dependencies": {
+		"prettier": "^3.8.1",
+		"query-string": "^9.3.1",
+		"zod": "^4.3.6"
+	}
+}

package/src/cli/args.ts

@@ -0,0 +1,196 @@
+import { parseArgs as parseCliArgs } from "node:util";
+import type { CliOptions } from "./types";
+
+/**
+ * Parse command.
+ * @returns Parse command output as `"generate" | "init"`.
+ * @example
+ * ```ts
+ * const result = parseCommand();
+ * // result: "generate" | "init"
+ * ```
+ */
+export function parseCommand(): "generate" | "init" {
+	const { positionals } = parseCliArgs({
+		args: Bun.argv,
+		options: {},
+		strict: false,
+		allowPositionals: true,
+	});
+
+	const command = positionals.slice(2)[0];
+	return command === "init" ? "init" : "generate";
+}
+
+/**
+ * Parse args.
+ * @returns Parse args output as `CliOptions`.
+ * @example
+ * ```ts
+ * const result = parseArgs();
+ * // result: CliOptions
+ * ```
+ */
+export function parseArgs(): CliOptions {
+	const { values, positionals } = parseCliArgs({
+		args: Bun.argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+			},
+			url: {
+				type: "string",
+				short: "u",
+			},
+			angular: {
+				type: "boolean",
+				short: "a",
+			},
+			http: {
+				type: "boolean",
+				short: "t",
+			},
+			plugin: {
+				type: "string",
+				short: "p",
+				multiple: true,
+			},
+			output: {
+				type: "string",
+				short: "o",
+			},
+			config: {
+				type: "string",
+				short: "c",
+			},
+			help: {
+				type: "boolean",
+				short: "h",
+			},
+		},
+		strict: true,
+		allowPositionals: true,
+	});
+
+	const options: CliOptions = {
+		input: "swagger.json",
+		angular: false,
+		http: false,
+		help: false,
+	};
+
+	if (values.input) {
+		options.input = values.input;
+	}
+	if (values.url) {
+		options.url = values.url;
+	}
+	if (values.angular) {
+		options.angular = values.angular;
+	}
+	if (values.http) {
+		options.http = values.http;
+	}
+	if (values.plugin) {
+		options.plugin = normalizePluginValues(values.plugin);
+	}
+	if (values.output) {
+		options.output = values.output;
+	}
+	if (values.config) {
+		options.config = values.config;
+	}
+	if (values.help) {
+		options.help = values.help;
+	}
+
+	for (const positional of positionals.slice(2)) {
+		if (positional === "init") {
+			continue;
+		}
+		if (positional.endsWith(".json")) {
+			options.input = positional;
+		}
+	}
+
+	return options;
+}
+
+/**
+ * Show help.
+ * @example
+ * ```ts
+ * showHelp();
+ * ```
+ */
+export function showHelp(): void {
+	console.log(`
+Sauron - OpenAPI to TypeScript/Angular Converter
+
+USAGE:
+  sauron [COMMAND] [OPTIONS] [INPUT_FILE]
+
+OPTIONS:
+  -i, --input <file>     Input OpenAPI/Swagger JSON file (default: swagger.json)
+  -u, --url <url>        Download OpenAPI/Swagger JSON from URL
+  -a, --angular          Generate Angular service in src/app/sauron (requires Angular project)
+  -t, --http             Generate HTTP client/service methods
+  -p, --plugin <id>      HTTP plugin to run (repeatable: fetch, angular, axios)
+  -o, --output <dir>     Output directory (default: outputs or src/app/sauron)
+  -c, --config <file>    Config file path (default: sauron.config.ts)
+  -h, --help            Show this help message
+
+COMMANDS:
+  init                   Create sauron.config.ts with default settings
+
+EXAMPLES:
+  sauron init
+  sauron --config ./sauron.config.ts
+  sauron swagger.json
+  sauron --input swaggerAfEstoque.json --angular --http
+  sauron --url https://api.example.com/swagger.json --http
+  sauron --http -i api.json -o ./generated
+  sauron --plugin fetch -i api.json
+  sauron --plugin axios -i api.json
+  sauron --plugin angular --plugin fetch -i api.json
+
+When --angular flag is used, the tool will:
+1. Detect if current directory is an Angular project
+2. Generate models in src/app/sauron/models/
+3. Generate Angular service in src/app/sauron/sauron-api.service.ts
+
+When --http flag is used without --angular:
+1. Generate fetch-based HTTP methods in outputs/http-client/
+2. Generate models in outputs/models/
+
+Without flags, generates only TypeScript models.
+`);
+}
+
+/**
+ * Normalize plugin values.
+ * @param pluginValues Input parameter `pluginValues`.
+ * @returns Normalize plugin values output as `string[]`.
+ * @example
+ * ```ts
+ * const result = normalizePluginValues(["fetch", "angular"]);
+ * // result: string[]
+ * ```
+ */
+function normalizePluginValues(
+	pluginValues: string | string[],
+): string[] {
+	if (Array.isArray(pluginValues)) {
+		return pluginValues
+			.map((plugin) => plugin.trim())
+			.filter((plugin) => plugin.length > 0);
+	}
+
+	const normalizedPlugin = pluginValues.trim();
+	if (!normalizedPlugin) {
+		return [];
+	}
+
+	return [normalizedPlugin];
+}

package/src/cli/config.ts

@@ -0,0 +1,228 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import type { z } from "zod";
+import type { SwaggerOrOpenAPISchema } from "../schemas/swagger";
+import { isAngularProject } from "./project";
+import {
+	type CliOptions,
+	DEFAULT_CONFIG_FILE,
+	DEFAULT_SAURON_VERSION,
+	type SauronConfig,
+} from "./types";
+
+/**
+ * Format generated file.
+ * @param content Input parameter `content`.
+ * @param filePath Input parameter `filePath`.
+ * @returns Format generated file output as `Promise<string>`.
+ * @example
+ * ```ts
+ * const result = await formatGeneratedFile("value", "value");
+ * // result: string
+ * ```
+ */
+export async function formatGeneratedFile(
+	content: string,
+	filePath: string,
+): Promise<string> {
+	try {
+		const prettier = await import("prettier");
+		return await prettier.format(content, { filepath: filePath });
+	} catch (error) {
+		console.warn(
+			`⚠️  Could not format ${filePath} with Prettier. Writing unformatted output.`,
+			error,
+		);
+		return content;
+	}
+}
+
+/**
+ * Get sauron version.
+ * @returns Get sauron version output as `string`.
+ * @example
+ * ```ts
+ * const result = getSauronVersion();
+ * // result: string
+ * ```
+ */
+function getSauronVersion(): string {
+	try {
+		const packageJsonPath = resolve(
+			import.meta.dir,
+			"..",
+			"..",
+			"package.json",
+		);
+		const packageJsonContent = readFileSync(packageJsonPath, "utf-8");
+		const packageJson = JSON.parse(packageJsonContent) as { version?: unknown };
+		if (
+			typeof packageJson.version === "string" &&
+			packageJson.version.length > 0
+		) {
+			return packageJson.version;
+		}
+	} catch {
+		// Fallback to default version when package metadata cannot be read.
+	}
+
+	return DEFAULT_SAURON_VERSION;
+}
+
+/**
+ * Create generated file header.
+ * @param schema Input parameter `schema`.
+ * @param generatedAt Input parameter `generatedAt`.
+ * @returns Create generated file header output as `string`.
+ * @example
+ * ```ts
+ * const result = createGeneratedFileHeader({}, {});
+ * // result: string
+ * ```
+ */
+export function createGeneratedFileHeader(
+	schema: z.infer<typeof SwaggerOrOpenAPISchema>,
+	generatedAt = new Date().toISOString(),
+): string {
+	return `/**
+ * Gerado por Sauron v${getSauronVersion()}
+ * Timestamp: ${generatedAt}
+ * Nao edite manualmente.
+ * ${schema.info.title}
+ * OpenAPI spec version: ${schema.info.version}
+ */
+`;
+}
+
+/**
+ * Init config file.
+ * @param configFilePath Input parameter `configFilePath`.
+ * @returns Init config file output as `Promise<void>`.
+ * @example
+ * ```ts
+ * const result = await initConfigFile({});
+ * // result: void
+ * ```
+ */
+export async function initConfigFile(
+	configFilePath = DEFAULT_CONFIG_FILE,
+): Promise<void> {
+	const resolvedConfigPath = resolve(configFilePath);
+	if (existsSync(resolvedConfigPath)) {
+		console.warn(`⚠️  Config file already exists: ${configFilePath}`);
+		return;
+	}
+	const angularProjectDetected = isAngularProject();
+	const defaultOutput = angularProjectDetected ? "src/app/sauron" : "outputs";
+
+	const template = `import type { SauronConfig } from "@ygorazambuja/sauron";
+
+export default {
+  // Use either "input" or "url". If both are set, "url" takes precedence.
+  input: "swagger.json",
+  // url: "https://example.com/openapi.json",
+  // plugin: ["fetch"],
+  output: "${defaultOutput}",
+  angular: ${angularProjectDetected},
+  http: true,
+} satisfies SauronConfig;
+`;
+
+	const formattedTemplate = await formatGeneratedFile(
+		template,
+		resolvedConfigPath,
+	);
+	writeFileSync(resolvedConfigPath, formattedTemplate);
+	console.log(`✅ Created config file: ${configFilePath}`);
+}
+
+/**
+ * Load sauron config.
+ * @param configFilePath Input parameter `configFilePath`.
+ * @returns Load sauron config output as `Promise<SauronConfig | null>`.
+ * @example
+ * ```ts
+ * const result = await loadSauronConfig({});
+ * // result: SauronConfig | null
+ * ```
+ */
+export async function loadSauronConfig(
+	configFilePath = DEFAULT_CONFIG_FILE,
+): Promise<SauronConfig | null> {
+	const resolvedConfigPath = resolve(configFilePath);
+	if (!existsSync(resolvedConfigPath)) {
+		return null;
+	}
+
+	const configModule = await import(
+		`${pathToFileURL(resolvedConfigPath).href}?t=${Date.now()}`
+	);
+	const loadedConfig = configModule.default;
+
+	if (!loadedConfig || typeof loadedConfig !== "object") {
+		throw new Error(
+			`Invalid config file format in ${configFilePath}. Expected a default exported object.`,
+		);
+	}
+
+	return loadedConfig as SauronConfig;
+}
+
+/**
+ * Merge options with config.
+ * @param options Input parameter `options`.
+ * @param config Input parameter `config`.
+ * @returns Merge options with config output as `CliOptions`.
+ * @example
+ * ```ts
+ * const result = mergeOptionsWithConfig({}, {});
+ * // result: CliOptions
+ * ```
+ */
+export function mergeOptionsWithConfig(
+	options: CliOptions,
+	config: SauronConfig,
+): CliOptions {
+	const mergedPlugins = resolveMergedPlugins(options.plugin, config.plugin);
+
+	return {
+		input:
+			options.input !== "swagger.json"
+				? options.input
+				: (config.input ?? "swagger.json"),
+		url: options.url ?? config.url,
+		angular: options.angular || !!config.angular,
+		http: options.http || !!config.http,
+		plugin: mergedPlugins,
+		output: options.output ?? config.output,
+		config: options.config,
+		help: options.help,
+	};
+}
+
+/**
+ * Resolve merged plugins.
+ * @param cliPlugins Input parameter `cliPlugins`.
+ * @param configPlugins Input parameter `configPlugins`.
+ * @returns Resolve merged plugins output as `string[] | undefined`.
+ * @example
+ * ```ts
+ * const result = resolveMergedPlugins(["fetch"], ["angular"]);
+ * // result: string[] | undefined
+ * ```
+ */
+function resolveMergedPlugins(
+	cliPlugins?: string[],
+	configPlugins?: string[],
+): string[] | undefined {
+	if (Array.isArray(cliPlugins) && cliPlugins.length > 0) {
+		return [...cliPlugins];
+	}
+
+	if (Array.isArray(configPlugins) && configPlugins.length > 0) {
+		return [...configPlugins];
+	}
+
+	return undefined;
+}