feat: Implement Clean Architecture code generation with Mustache templates

- Added `clean-arch.generator.ts` for generating models, mappers, repositories, use cases, and providers based on OpenAPI specs.
- Introduced `dto.generator.ts` to invoke `openapi-generator-cli` for generating DTOs and organizing them.
- Created `report.generator.ts` to generate a JSON report of the generation process.
- Implemented `analyzer.ts` for parsing OpenAPI/Swagger files and extracting relevant data.
- Defined new types in `cli.types.ts`, `generation.types.ts`, `openapi.types.ts`, and `swagger.types.ts` for better type safety.
- Added utility functions in `filesystem.ts` for creating directory structures and cleaning up temporary files.
- Developed logging utilities in `logger.ts` for better console output.
- Included OpenAPI generator checks and installation in `openapi-generator.ts`.
- Added type mapping utility in `type-mapper.ts` for converting OpenAPI types to TypeScript types.
- Updated `package.json` scripts to lint all TypeScript files.
- Modified `tsconfig.json` to include all TypeScript files in the project.

src/generators/clean-arch.generator.ts

@@ -0,0 +1,294 @@
+import fs from 'fs-extra';
+import path from 'path';
+import mustache from 'mustache';
+import { logStep, logSuccess, logInfo } from '../utils/logger';
+import { mapSwaggerTypeToTs } from '../utils/type-mapper';
+import type {
+  SwaggerAnalysis,
+  OpenApiSchema,
+  OpenApiOperation,
+  TagOperation,
+  GeneratedCount
+} from '../types';
+
+/** Genera todos los artefactos de Clean Architecture (modelos, mappers, repos, use cases, providers) usando Mustache. */
+export function generateCleanArchitecture(
+  analysis: SwaggerAnalysis,
+  outputDir: string,
+  templatesDir: string
+): GeneratedCount {
+  logStep('Generando artefactos de Clean Architecture usando Mustache...');
+  const generatedCount: GeneratedCount = {
+    models: 0,
+    repositories: 0,
+    mappers: 0,
+    useCases: 0,
+    providers: 0
+  };
+
+  const schemas =
+    (analysis.swagger as { components?: { schemas?: Record<string, unknown> } }).components
+      ?.schemas || {};
+
+  // 1. Generar Modelos, Entidades y Mappers a partir de Schemas
+  Object.keys(schemas).forEach((schemaName) => {
+    const baseName = schemaName.replace(/Dto$/, '');
+
+    const schemaObj = schemas[schemaName] as OpenApiSchema;
+    const rawProperties = schemaObj.properties || {};
+    const requiredProps: string[] = schemaObj.required || [];
+
+    const varsMap = Object.keys(rawProperties).map((k) => {
+      let tsType = mapSwaggerTypeToTs(rawProperties[k].type);
+      if (rawProperties[k].$ref) {
+        tsType = rawProperties[k].$ref.split('/').pop() || 'unknown';
+      } else if (rawProperties[k].type === 'array' && rawProperties[k].items?.$ref) {
+        tsType = `Array<${rawProperties[k].items.$ref.split('/').pop()}>`;
+      }
+      return {
+        name: k,
+        dataType: tsType,
+        description: rawProperties[k].description || '',
+        required: requiredProps.includes(k)
+      };
+    });
+
+    const modelViewData = {
+      models: [
+        {
+          model: {
+            classname: baseName,
+            classFilename: baseName.toLowerCase(),
+            classVarName: baseName.charAt(0).toLowerCase() + baseName.slice(1),
+            description: schemaObj.description || '',
+            vars: varsMap
+          }
+        }
+      ],
+      allModels: [{ model: { vars: varsMap } }]
+    };
+
+    const mapperViewData = {
+      ...modelViewData,
+      apiInfo: {
+        apis: [
+          {
+            operations: {
+              classname: baseName,
+              classFilename: baseName.toLowerCase(),
+              classVarName: baseName.charAt(0).toLowerCase() + baseName.slice(1)
+            }
+          }
+        ]
+      }
+    };
+
+    // Model (Entities)
+    const modelTemplatePath = path.join(templatesDir, 'model-entity.mustache');
+    if (fs.existsSync(modelTemplatePath)) {
+      const template = fs.readFileSync(modelTemplatePath, 'utf8');
+      const output = mustache.render(template, modelViewData);
+      const destPath = path.join(
+        outputDir,
+        'entities/models',
+        `${baseName.toLowerCase()}.model.ts`
+      );
+      fs.writeFileSync(destPath, output);
+      generatedCount.models++;
+      logInfo(`  ${baseName.toLowerCase()}.model.ts → ${path.relative(process.cwd(), destPath)}`);
+    }
+
+    // Mapper
+    const mapperTemplatePath = path.join(templatesDir, 'mapper.mustache');
+    if (fs.existsSync(mapperTemplatePath)) {
+      const template = fs.readFileSync(mapperTemplatePath, 'utf8');
+      const output = mustache.render(template, mapperViewData);
+      const destPath = path.join(outputDir, 'data/mappers', `${baseName.toLowerCase()}.mapper.ts`);
+      fs.writeFileSync(destPath, output);
+      generatedCount.mappers++;
+    }
+  });
+
+  // 2. Generar Casos de Uso y Repositorios a partir de Paths/Tags
+  const tagsMap: Record<string, TagOperation[]> = {};
+
+  Object.keys(analysis.paths).forEach((pathKey) => {
+    const pathObj = analysis.paths[pathKey] as Record<string, unknown>;
+    Object.keys(pathObj).forEach((method) => {
+      const op = pathObj[method] as OpenApiOperation;
+      if (op.tags && op.tags.length > 0) {
+        const tag = op.tags[0];
+        if (!tagsMap[tag]) tagsMap[tag] = [];
+
+        const allParams = (op.parameters || []).map((p) => ({
+          paramName: p.name,
+          dataType: mapSwaggerTypeToTs(p.schema?.type || ''),
+          description: p.description || '',
+          required: p.required
+        }));
+
+        if (op.requestBody) {
+          let bodyType = 'unknown';
+          const content = op.requestBody.content?.['application/json']?.schema;
+          if (content) {
+            if (content.$ref) bodyType = content.$ref.split('/').pop() || 'unknown';
+            else if (content.type) bodyType = mapSwaggerTypeToTs(content.type);
+          }
+          allParams.push({
+            paramName: 'body',
+            dataType: bodyType,
+            description: op.requestBody.description || '',
+            required: true
+          });
+        }
+
+        let returnType = 'void';
+        let returnBaseType = 'void';
+        let isListContainer = false;
+        const responseSchema = op.responses?.['200']?.content?.['application/json']?.schema;
+        if (responseSchema) {
+          if (responseSchema.$ref) {
+            returnType = responseSchema.$ref.split('/').pop() || 'unknown';
+            returnBaseType = returnType;
+          } else if (responseSchema.type === 'array' && responseSchema.items?.$ref) {
+            returnBaseType = responseSchema.items.$ref.split('/').pop() || 'unknown';
+            returnType = `Array<${returnBaseType}>`;
+            isListContainer = true;
+          }
+        }
+
+        tagsMap[tag].push({
+          nickname: op.operationId || `${method}${pathKey.replace(/\//g, '_')}`,
+          summary: op.summary || '',
+          notes: op.description || '',
+          httpMethod: method.toLowerCase(),
+          path: pathKey,
+          allParams: allParams.map((p, i: number) => ({
+            ...p,
+            '-last': i === allParams.length - 1
+          })),
+          hasQueryParams: (op.parameters || []).some((p) => p.in === 'query'),
+          queryParams: (op.parameters || [])
+            .filter((p) => p.in === 'query')
+            .map((p, i: number, arr: unknown[]) => ({
+              paramName: p.name,
+              '-last': i === arr.length - 1
+            })),
+          hasBodyParam: !!op.requestBody,
+          bodyParam: 'body',
+          returnType: returnType !== 'void' ? returnType : false,
+          returnBaseType: returnBaseType !== 'void' ? returnBaseType : false,
+          isListContainer: isListContainer,
+          vendorExtensions: {}
+        });
+      }
+    });
+  });
+
+  // Generar por cada Tag
+  Object.keys(tagsMap).forEach((tag) => {
+    const imports: { classname: string; classFilename: string; classVarName: string }[] = [];
+    Object.keys(schemas).forEach((s) => {
+      if (tagsMap[tag].some((op) => op.returnType === s || op.returnType === `Array<${s}>`)) {
+        imports.push({
+          classname: s,
+          classFilename: s.toLowerCase(),
+          classVarName: s.charAt(0).toLowerCase() + s.slice(1)
+        });
+      }
+    });
+
+    const apiViewData = {
+      apiInfo: {
+        apis: [
+          {
+            operations: {
+              classname: tag,
+              classFilename: tag.toLowerCase(),
+              constantName: tag.toUpperCase().replace(/[^A-Z0-9]/g, '_'),
+              operation: tagsMap[tag],
+              imports: imports
+            }
+          }
+        ]
+      }
+    };
+
+    renderTemplate(
+      templatesDir,
+      'api.use-cases.contract.mustache',
+      apiViewData,
+      path.join(outputDir, 'domain/use-cases', `${tag.toLowerCase()}.use-cases.contract.ts`),
+      generatedCount,
+      'useCases'
+    );
+
+    renderTemplate(
+      templatesDir,
+      'api.use-cases.impl.mustache',
+      apiViewData,
+      path.join(outputDir, 'domain/use-cases', `${tag.toLowerCase()}.use-cases.impl.ts`),
+      generatedCount,
+      'useCases'
+    );
+
+    renderTemplate(
+      templatesDir,
+      'api.repository.contract.mustache',
+      apiViewData,
+      path.join(outputDir, 'domain/repositories', `${tag.toLowerCase()}.repository.contract.ts`),
+      generatedCount,
+      'repositories'
+    );
+
+    renderTemplate(
+      templatesDir,
+      'api.repository.impl.mustache',
+      apiViewData,
+      path.join(outputDir, 'data/repositories', `${tag.toLowerCase()}.repository.impl.ts`),
+      generatedCount,
+      'repositories'
+    );
+
+    renderTemplate(
+      templatesDir,
+      'use-cases.provider.mustache',
+      apiViewData,
+      path.join(outputDir, 'di/use-cases', `${tag.toLowerCase()}.use-cases.provider.ts`),
+      generatedCount,
+      'providers'
+    );
+
+    renderTemplate(
+      templatesDir,
+      'repository.provider.mustache',
+      apiViewData,
+      path.join(outputDir, 'di/repositories', `${tag.toLowerCase()}.repository.provider.ts`),
+      generatedCount,
+      'providers'
+    );
+  });
+
+  logSuccess(
+    `${generatedCount.models} Models, ${generatedCount.repositories} Repos, ${generatedCount.useCases} Use Cases, ${generatedCount.mappers} Mappers, ${generatedCount.providers} Providers generados con Mustache`
+  );
+  return generatedCount;
+}
+
+/** Renderiza un template Mustache e incrementa el contador correspondiente. */
+function renderTemplate(
+  templatesDir: string,
+  templateName: string,
+  viewData: unknown,
+  destPath: string,
+  counter: GeneratedCount,
+  key: keyof GeneratedCount
+): void {
+  const templatePath = path.join(templatesDir, templateName);
+  if (fs.existsSync(templatePath)) {
+    const template = fs.readFileSync(templatePath, 'utf8');
+    const output = mustache.render(template, viewData);
+    fs.writeFileSync(destPath, output);
+    counter[key]++;
+  }
+}

src/generators/dto.generator.ts

@@ -0,0 +1,62 @@
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+import { logStep, logSuccess, logError, logInfo } from '../utils/logger';
+
+/** Invoca `openapi-generator-cli` para generar DTOs en un directorio temporal. */
+export function generateCode(swaggerFile: string, templatesDir: string): string {
+  logStep('Generando código desde OpenAPI...');
+
+  const tempDir = path.join(process.cwd(), '.temp-generated');
+
+  if (fs.existsSync(tempDir)) {
+    fs.removeSync(tempDir);
+  }
+
+  try {
+    const command = `openapi-generator-cli generate \
+      -i "${swaggerFile}" \
+      -g typescript-angular \
+      --global-property models \
+      -t "${templatesDir}" \
+      -o "${tempDir}" \
+      --additional-properties=ngVersion=17.0.0,modelFileSuffix=.dto`;
+
+    execSync(command, { stdio: 'inherit' });
+    logSuccess('Código generado correctamente');
+
+    return tempDir;
+  } catch (_error) {
+    logError('Error al generar código');
+    if (fs.existsSync(tempDir)) {
+      fs.removeSync(tempDir);
+    }
+    process.exit(1);
+  }
+}
+
+/** Copia los DTOs generados desde el directorio temporal al directorio de salida. */
+export function organizeFiles(tempDir: string, outputDir: string): void {
+  logStep('Organizando archivos DTO generados...');
+
+  const sourceDir = path.join(tempDir, 'model');
+  const destDir = path.join(outputDir, 'data/dtos');
+  let filesMoved = 0;
+
+  if (fs.existsSync(sourceDir)) {
+    fs.ensureDirSync(destDir);
+
+    const files = fs.readdirSync(sourceDir).filter((file) => file.endsWith('.dto.ts'));
+
+    files.forEach((file) => {
+      const sourcePath = path.join(sourceDir, file);
+      const destPath = path.join(destDir, file);
+
+      fs.copySync(sourcePath, destPath);
+      filesMoved++;
+      logInfo(`  ${file} → ${path.relative(process.cwd(), destPath)}`);
+    });
+  }
+
+  logSuccess(`${filesMoved} DTOs movidos correctamente`);
+}

src/generators/report.generator.ts

@@ -0,0 +1,32 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { logStep, logSuccess } from '../utils/logger';
+import type { SwaggerAnalysis, GenerationReport } from '../types';
+
+/** Genera y persiste el reporte `generation-report.json` con las estadísticas del proceso. */
+export function generateReport(outputDir: string, analysis: SwaggerAnalysis): GenerationReport {
+  logStep('Generando reporte de generación...');
+
+  const report: GenerationReport = {
+    timestamp: new Date().toISOString(),
+    tags: analysis.tags.length,
+    endpoints: Object.keys(analysis.paths).length,
+    outputDirectory: outputDir,
+    structure: {
+      dtos: fs.readdirSync(path.join(outputDir, 'data/dtos')).length,
+      repositories: fs.readdirSync(path.join(outputDir, 'data/repositories')).length,
+      mappers: fs.readdirSync(path.join(outputDir, 'data/mappers')).length,
+      useCases: fs.readdirSync(path.join(outputDir, 'domain/use-cases')).length,
+      providers:
+        fs.readdirSync(path.join(outputDir, 'di/repositories')).length +
+        fs.readdirSync(path.join(outputDir, 'di/use-cases')).length
+    }
+  };
+
+  const reportPath = path.join(process.cwd(), 'generation-report.json');
+  fs.writeJsonSync(reportPath, report, { spaces: 2 });
+
+  logSuccess(`Reporte guardado en: ${reportPath}`);
+
+  return report;
+}

src/swagger/analyzer.ts

@@ -0,0 +1,31 @@
+import fs from 'fs-extra';
+import yaml from 'js-yaml';
+import { logStep, logInfo, logError } from '../utils/logger';
+import type { SwaggerAnalysis } from '../types';
+
+/** Parsea un archivo OpenAPI/Swagger y extrae tags, paths y el documento completo. */
+export function analyzeSwagger(swaggerFile: string): SwaggerAnalysis {
+  logStep('Analizando archivo OpenAPI...');
+
+  try {
+    const fileContent = fs.readFileSync(swaggerFile, 'utf8');
+    const swagger = yaml.load(fileContent) as Record<string, unknown>;
+
+    const tags = Array.isArray(swagger.tags) ? swagger.tags : [];
+    const paths = (swagger.paths as Record<string, unknown>) || {};
+
+    logInfo(`Encontrados ${tags.length} tags en el API`);
+    logInfo(`Encontrados ${Object.keys(paths).length} endpoints`);
+
+    tags.forEach((tag: unknown) => {
+      const t = tag as { name: string; description?: string };
+      logInfo(`  - ${t.name}: ${t.description || 'Sin descripción'}`);
+    });
+
+    return { tags, paths, swagger };
+  } catch (error: unknown) {
+    const err = error as Error;
+    logError(`Error al leer el archivo Swagger: ${err.message}`);
+    process.exit(1);
+  }
+}

src/types/cli.types.ts

@@ -0,0 +1,11 @@
+/**
+ * Opciones recibidas desde la línea de comandos (Commander).
+ * Desacoplada del framework CLI para permitir su uso desde un backend u otro entrypoint.
+ */
+export interface CliOptions {
+  input: string;
+  output: string;
+  templates: string;
+  skipInstall?: boolean;
+  dryRun?: boolean;
+}

src/types/generation.types.ts

@@ -0,0 +1,27 @@
+/**
+ * Contadores acumulativos de artefactos generados durante el proceso.
+ */
+export interface GeneratedCount {
+  models: number;
+  repositories: number;
+  mappers: number;
+  useCases: number;
+  providers: number;
+}
+
+/**
+ * Reporte final de generación que se persiste como `generation-report.json`.
+ */
+export interface GenerationReport {
+  timestamp: string;
+  tags: number;
+  endpoints: number;
+  outputDirectory: string;
+  structure: {
+    dtos: number;
+    repositories: number;
+    mappers: number;
+    useCases: number;
+    providers: number;
+  };
+}

src/types/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @module types
+ * @description Barrel que re-exporta todos los tipos e interfaces compartidos del proyecto.
+ */
+export * from './cli.types';
+export * from './swagger.types';
+export * from './openapi.types';
+export * from './generation.types';

src/types/openapi.types.ts

@@ -0,0 +1,83 @@
+/**
+ * Representación simplificada de un schema de componente OpenAPI.
+ * Se utiliza para generar modelos (entidades) y mappers.
+ */
+export interface OpenApiSchema {
+  properties?: Record<
+    string,
+    {
+      type?: string;
+      description?: string;
+      $ref?: string;
+      items?: { $ref?: string };
+    }
+  >;
+  required?: string[];
+  description?: string;
+}
+
+/**
+ * Representación de una operación OpenAPI (GET, POST, etc.) dentro de un path.
+ * Contiene la información necesaria para generar repositorios y casos de uso.
+ */
+export interface OpenApiOperation {
+  tags?: string[];
+  operationId?: string;
+  summary?: string;
+  description?: string;
+  parameters?: Array<{
+    name: string;
+    in: string;
+    required: boolean;
+    description?: string;
+    schema?: { type?: string };
+  }>;
+  requestBody?: {
+    description?: string;
+    content?: Record<
+      string,
+      {
+        schema?: {
+          $ref?: string;
+          type?: string;
+        };
+      }
+    >;
+  };
+  responses?: Record<
+    string,
+    {
+      content?: Record<
+        string,
+        {
+          schema?: {
+            $ref?: string;
+            type?: string;
+            items?: { $ref?: string };
+          };
+        }
+      >;
+    }
+  >;
+}
+
+/**
+ * Operación normalizada y lista para ser consumida por los templates Mustache.
+ * Cada instancia representa un endpoint agrupado bajo un tag del API.
+ */
+export interface TagOperation {
+  nickname: string;
+  summary: string;
+  notes: string;
+  httpMethod: string;
+  path: string;
+  allParams: unknown[];
+  hasQueryParams: boolean;
+  queryParams: unknown[];
+  hasBodyParam: boolean;
+  bodyParam: string;
+  returnType: string | boolean;
+  returnBaseType: string | boolean;
+  isListContainer: boolean;
+  vendorExtensions: Record<string, unknown>;
+}

src/types/swagger.types.ts

@@ -0,0 +1,9 @@
+/**
+ * Resultado del análisis de un archivo OpenAPI/Swagger.
+ * Contiene las estructuras crudas extraídas del spec para su posterior procesamiento.
+ */
+export interface SwaggerAnalysis {
+  tags: unknown[];
+  paths: Record<string, unknown>;
+  swagger: unknown;
+}

src/utils/filesystem.ts

@@ -0,0 +1,31 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { logSuccess, logInfo } from './logger';
+
+/** Crea la estructura de directorios necesaria para Clean Architecture (idempotente). */
+export function createDirectoryStructure(baseDir: string): void {
+  const dirs = [
+    path.join(baseDir, 'data/dtos'),
+    path.join(baseDir, 'data/repositories'),
+    path.join(baseDir, 'data/mappers'),
+    path.join(baseDir, 'domain/repositories'),
+    path.join(baseDir, 'domain/use-cases'),
+    path.join(baseDir, 'di/repositories'),
+    path.join(baseDir, 'di/use-cases'),
+    path.join(baseDir, 'entities/models')
+  ];
+
+  dirs.forEach((dir) => {
+    fs.ensureDirSync(dir);
+  });
+
+  logSuccess('Estructura de directorios creada');
+}
+
+/** Elimina un directorio temporal y todo su contenido. */
+export function cleanup(tempDir: string): void {
+  if (fs.existsSync(tempDir)) {
+    fs.removeSync(tempDir);
+    logInfo('Archivos temporales eliminados');
+  }
+}

src/utils/logger.ts

@@ -0,0 +1,43 @@
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  green: '\x1b[32m',
+  blue: '\x1b[34m',
+  yellow: '\x1b[33m',
+  red: '\x1b[31m',
+  cyan: '\x1b[36m'
+} as const;
+
+type Color = keyof typeof colors;
+
+/** Imprime un mensaje en consola con el color ANSI indicado. */
+export function log(message: string, color: Color = 'reset'): void {
+  console.log(`${colors[color]}${message}${colors.reset}`);
+}
+
+/** Imprime un mensaje de éxito (verde). */
+export function logSuccess(message: string): void {
+  log(`✅ ${message}`, 'green');
+}
+
+/** Imprime un mensaje informativo (azul). */
+export function logInfo(message: string): void {
+  log(`ℹ️  ${message}`, 'blue');
+}
+
+/** Imprime un mensaje de advertencia (amarillo). */
+export function logWarning(message: string): void {
+  log(`⚠️  ${message}`, 'yellow');
+}
+
+/** Imprime un mensaje de error (rojo). */
+export function logError(message: string): void {
+  log(`❌ ${message}`, 'red');
+}
+
+/** Imprime un encabezado de paso/etapa (cian). */
+export function logStep(message: string): void {
+  log(`\n🚀 ${message}`, 'cyan');
+}
+
+export { colors };

src/utils/openapi-generator.ts

@@ -0,0 +1,24 @@
+import { execSync } from 'child_process';
+import { logStep, logSuccess, logError } from './logger';
+
+/** Verifica si `openapi-generator-cli` está disponible en el PATH. */
+export function checkOpenApiGenerator(): boolean {
+  try {
+    execSync('openapi-generator-cli version', { stdio: 'ignore' });
+    return true;
+  } catch (_error) {
+    return false;
+  }
+}
+
+/** Instala `@openapitools/openapi-generator-cli` de forma global vía npm. */
+export function installOpenApiGenerator(): void {
+  logStep('Instalando @openapitools/openapi-generator-cli...');
+  try {
+    execSync('npm install -g @openapitools/openapi-generator-cli', { stdio: 'inherit' });
+    logSuccess('OpenAPI Generator CLI instalado correctamente');
+  } catch (_error) {
+    logError('Error al instalar OpenAPI Generator CLI');
+    process.exit(1);
+  }
+}

src/utils/type-mapper.ts

@@ -0,0 +1,14 @@
+/** Traduce un tipo primitivo de OpenAPI/Swagger al equivalente TypeScript. */
+export function mapSwaggerTypeToTs(type?: string): string {
+  if (!type) return 'unknown';
+
+  const typeMap: Record<string, string> = {
+    integer: 'number',
+    string: 'string',
+    boolean: 'boolean',
+    number: 'number',
+    array: 'Array<unknown>',
+    object: 'unknown'
+  };
+  return typeMap[type] || 'unknown';
+}