@0kmpo/openapi-clean-arch-generator 1.3.10

package/src/generators/dto.generator.ts

@@ -0,0 +1,126 @@
+import { execSync } from 'child_process';
+import fs from 'fs-extra';
+import path from 'path';
+import { logStep, logSuccess, logError, logDetail } from '../utils/logger';
+
+/** Invokes `openapi-generator-cli` to generate DTOs into a temporary directory. */
+export function generateCode(swaggerFile: string, templatesDir: string): string {
+  logStep('Generating code from OpenAPI spec...');
+
+  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,modelNameSuffix=Dto`;
+
+    execSync(command, { stdio: 'pipe' });
+    logSuccess('Code generated successfully');
+
+    return tempDir;
+  } catch (_error) {
+    logError('Error generating code');
+    if (fs.existsSync(tempDir)) {
+      fs.removeSync(tempDir);
+    }
+    process.exit(1);
+  }
+}
+
+/** Copies the generated DTOs from the temporary directory to the output directory. */
+export function organizeFiles(tempDir: string, outputDir: string): void {
+  logStep('Organising generated DTO files...');
+
+  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++;
+      logDetail('dto', `${file} → ${path.relative(process.cwd(), destPath)}`);
+    });
+  }
+
+  logSuccess(`${filesMoved} DTOs moved successfully`);
+}
+
+/** Post-processes the generated DTOs: adds cross-DTO imports and normalises Array<T> → T[]. */
+export function addDtoImports(outputDir: string): void {
+  logStep('Post-processing generated DTOs...');
+
+  const dtosDir = path.join(outputDir, 'data/dtos');
+
+  if (!fs.existsSync(dtosDir)) return;
+
+  const files = fs.readdirSync(dtosDir).filter((f) => f.endsWith('.dto.ts'));
+
+  // Build a map of DTO classname → file base name (without .ts)
+  const dtoMap: Record<string, string> = {};
+  files.forEach((file) => {
+    const content = fs.readFileSync(path.join(dtosDir, file), 'utf8');
+    const match = content.match(/export interface (\w+)/);
+    if (match) {
+      dtoMap[match[1]] = file.replace('.ts', '');
+    }
+  });
+
+  let filesProcessed = 0;
+
+  files.forEach((file) => {
+    const filePath = path.join(dtosDir, file);
+    const originalContent = fs.readFileSync(filePath, 'utf8');
+    let content = originalContent;
+
+    const selfMatch = content.match(/export interface (\w+)/);
+    const selfName = selfMatch ? selfMatch[1] : '';
+
+    // Normalize Array<T> → T[] (openapi-generator-cli always outputs Array<T>)
+    content = content.replace(/Array<(\w+)>/g, '$1[]');
+
+    // Find all Dto type references in the file body (excluding the interface name itself)
+    const references = new Set<string>();
+    const typeRegex = /\b(\w+Dto)\b/g;
+    let match;
+    while ((match = typeRegex.exec(content)) !== null) {
+      if (match[1] !== selfName) {
+        references.add(match[1]);
+      }
+    }
+
+    // Build import lines for each referenced type that exists in the dtoMap
+    const imports: string[] = [];
+    references.forEach((ref) => {
+      if (dtoMap[ref]) {
+        imports.push(`import { ${ref} } from './${dtoMap[ref]}';`);
+      }
+    });
+
+    if (imports.length > 0) {
+      content = imports.join('\n') + '\n' + content;
+    }
+
+    if (content !== originalContent) {
+      fs.writeFileSync(filePath, content);
+      filesProcessed++;
+      logDetail('dto', `Post-processed ${file} (added ${imports.length} import(s))`);
+    }
+  });
+
+  logSuccess(`${filesProcessed} DTOs post-processed`);
+}

package/src/generators/lint.generator.ts

@@ -0,0 +1,124 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { spawnSync } from 'child_process';
+import { logStep, logSuccess, logWarning, logDetail } from '../utils/logger';
+import type { LintResult } from '../types';
+
+/**
+ * Walks up the directory tree from `startDir` to find the nearest
+ * directory containing a `package.json` (i.e. the project root).
+ * Returns `null` if none is found before reaching the filesystem root.
+ */
+function findProjectRoot(startDir: string): string | null {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'package.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+/**
+ * Collects all `.ts` files recursively inside a directory.
+ */
+function collectTsFiles(dir: string): string[] {
+  if (!fs.existsSync(dir)) return [];
+  const results: string[] = [];
+  fs.readdirSync(dir).forEach((entry) => {
+    const full = path.join(dir, entry);
+    if (fs.statSync(full).isDirectory()) {
+      results.push(...collectTsFiles(full));
+    } else if (entry.endsWith('.ts')) {
+      results.push(full);
+    }
+  });
+  return results;
+}
+
+/**
+ * Runs a command synchronously. Only prints to console on fatal failure (exit >= 2).
+ * Exit code 1 from ESLint means "warnings remain after --fix" — not a fatal error.
+ * Returns captured output for logging to file.
+ */
+function run(cmd: string, args: string[], cwd: string): { success: boolean; output: string } {
+  const result = spawnSync(cmd, args, { cwd, encoding: 'utf8', shell: true });
+  const output = [result.stdout, result.stderr].filter(Boolean).join('\n').trim();
+  const fatalError = result.status === null || result.status >= 2;
+  if (fatalError) {
+    if (result.stderr) process.stderr.write(result.stderr);
+    if (result.stdout) process.stdout.write(result.stdout);
+  }
+  return { success: !fatalError, output };
+}
+
+/**
+ * Runs Prettier and ESLint (--fix) on all generated `.ts` files inside `outputDir`.
+ * Both tools are looked up via `npx` in the nearest project root so that the
+ * target Angular project's own configuration and plugins are used.
+ *
+ * - Prettier: always attempted; logs a warning if not found.
+ * - ESLint:   optional; silently skipped if no config is found in the project root.
+ *
+ * Returns a `LintResult` with the outcome of each tool for inclusion in the report.
+ */
+export function lintGeneratedFiles(outputDir: string): LintResult {
+  logStep('Linting generated files...');
+
+  const result: LintResult = {
+    prettier: { ran: false, filesFormatted: 0 },
+    eslint: { ran: false, filesFixed: 0 }
+  };
+
+  const projectRoot = findProjectRoot(outputDir);
+  if (!projectRoot) {
+    logWarning('Could not locate a project root (package.json). Skipping lint.');
+    return result;
+  }
+
+  const files = collectTsFiles(outputDir);
+  if (files.length === 0) {
+    logWarning('No TypeScript files found in output directory. Skipping lint.');
+    return result;
+  }
+
+  logDetail('lint', `Project root: ${projectRoot}`);
+  logDetail('lint', `Files to process: ${files.length}`);
+
+  const relativePaths = files.map((f) => path.relative(projectRoot, f));
+
+  // --- Prettier ---
+  const prettier = run('npx', ['prettier', '--write', ...relativePaths], projectRoot);
+  if (prettier.output) logDetail('prettier', prettier.output);
+  if (prettier.success) {
+    result.prettier = { ran: true, filesFormatted: files.length };
+    logSuccess(`Prettier formatted ${files.length} files`);
+  } else {
+    logWarning('Prettier not available or encountered errors. Skipping formatting.');
+  }
+
+  // --- ESLint (only if a config exists in the project root) ---
+  const hasEslintConfig =
+    fs.existsSync(path.join(projectRoot, 'eslint.config.js')) ||
+    fs.existsSync(path.join(projectRoot, 'eslint.config.mjs')) ||
+    fs.existsSync(path.join(projectRoot, '.eslintrc.js')) ||
+    fs.existsSync(path.join(projectRoot, '.eslintrc.json')) ||
+    fs.existsSync(path.join(projectRoot, '.eslintrc.yml')) ||
+    fs.existsSync(path.join(projectRoot, '.eslintrc.yaml'));
+
+  if (!hasEslintConfig) {
+    logWarning('No ESLint config found in project root. Skipping ESLint fix.');
+    return result;
+  }
+
+  const eslint = run('npx', ['eslint', '--fix', ...relativePaths], projectRoot);
+  if (eslint.output) logDetail('eslint', eslint.output);
+  if (eslint.success) {
+    result.eslint = { ran: true, filesFixed: files.length };
+    logSuccess(`ESLint fixed ${files.length} files`);
+  } else {
+    logWarning('ESLint reported errors that could not be auto-fixed. Review the output above.');
+  }
+
+  return result;
+}

package/src/generators/report.generator.ts

@@ -0,0 +1,80 @@
+import fs from 'fs-extra';
+import path from 'path';
+import { logStep, logSuccess } from '../utils/logger';
+import type { SwaggerAnalysis, GenerationReport, LintResult } from '../types';
+
+/** Counts files ending with `.mock.ts` in a directory (returns 0 if directory does not exist). */
+function countMockFiles(dir: string): number {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.mock.ts')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Counts files ending with `.spec.ts` in a directory (returns 0 if directory does not exist). */
+function countSpecFiles(dir: string): number {
+  try {
+    return fs.readdirSync(dir).filter((f) => f.endsWith('.spec.ts')).length;
+  } catch {
+    return 0;
+  }
+}
+
+/** Generates and persists the `generation-report.json` file with process statistics. */
+export function generateReport(
+  outputDir: string,
+  analysis: SwaggerAnalysis,
+  lintResult: LintResult
+): GenerationReport {
+  logStep('Generating report...');
+
+  const tags = Array.isArray(analysis.tags) ? analysis.tags : [];
+  const tagDetails = tags.map((tag: unknown) => {
+    const t = tag as { name: string; description?: string };
+    const endpointCount = Object.values(analysis.paths).filter((pathObj) =>
+      Object.values(pathObj as Record<string, unknown>).some((op) => {
+        const operation = op as { tags?: string[] };
+        return operation.tags?.includes(t.name);
+      })
+    ).length;
+    return { name: t.name, description: t.description || '', endpoints: endpointCount };
+  });
+
+  const report: GenerationReport = {
+    timestamp: new Date().toISOString(),
+    tags: analysis.tags.length,
+    endpoints: Object.keys(analysis.paths).length,
+    tagDetails,
+    outputDirectory: outputDir,
+    linting: lintResult,
+    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,
+      mocks:
+        countMockFiles(path.join(outputDir, 'data/dtos')) +
+        countMockFiles(path.join(outputDir, 'data/repositories')) +
+        countMockFiles(path.join(outputDir, 'di/repositories')) +
+        countMockFiles(path.join(outputDir, 'di/use-cases')) +
+        countMockFiles(path.join(outputDir, 'domain/use-cases')) +
+        countMockFiles(path.join(outputDir, 'entities/models')),
+      specs:
+        countSpecFiles(path.join(outputDir, 'entities/models')) +
+        countSpecFiles(path.join(outputDir, 'data/mappers')) +
+        countSpecFiles(path.join(outputDir, 'data/repositories')) +
+        countSpecFiles(path.join(outputDir, 'domain/use-cases'))
+    }
+  };
+
+  const reportPath = path.join(process.cwd(), 'generation-report.json');
+  fs.writeJsonSync(reportPath, report, { spaces: 2 });
+
+  logSuccess(`Report saved to: ${reportPath}`);
+
+  return report;
+}

package/src/swagger/analyzer.ts

@@ -0,0 +1,32 @@
+import fs from 'fs-extra';
+import yaml from 'js-yaml';
+import { logStep, logSuccess, logError, logDetail } from '../utils/logger';
+import type { SwaggerAnalysis } from '../types';
+
+/** Parses an OpenAPI/Swagger file and extracts tags, paths and the full document. */
+export function analyzeSwagger(swaggerFile: string): SwaggerAnalysis {
+  logStep('Analysing OpenAPI file...');
+
+  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>) || {};
+
+    logDetail('analyze', `Input: ${swaggerFile}`);
+    logDetail('analyze', `Found ${tags.length} tags, ${Object.keys(paths).length} endpoints`);
+    tags.forEach((tag: unknown) => {
+      const t = tag as { name: string; description?: string };
+      logDetail('analyze', `  - ${t.name}: ${t.description || 'No description'}`);
+    });
+
+    logSuccess(`${tags.length} tags, ${Object.keys(paths).length} endpoints found`);
+
+    return { tags, paths, swagger };
+  } catch (error: unknown) {
+    const err = error as Error;
+    logError(`Error reading the Swagger file: ${err.message}`);
+    process.exit(1);
+  }
+}

package/src/types/cli.types.ts

@@ -0,0 +1,36 @@
+/**
+ * Options received from the command line (Commander).
+ * Decoupled from the CLI framework to allow use from a backend or other entry points.
+ */
+export interface CliOptions {
+  input: string;
+  output: string;
+  templates: string;
+  skipInstall?: boolean;
+  dryRun?: boolean;
+  selectEndpoints?: boolean;
+  skipLint?: boolean;
+  config?: string;
+  initConfig?: string | boolean;
+}
+
+/**
+ * Per-tag configuration inside the generation config file.
+ */
+export interface TagConfig {
+  baseUrl: string;
+  endpoints: string[];
+}
+
+/**
+ * JSON configuration file schema.
+ * Allows full non-interactive control of the generation process.
+ */
+export interface GenerationConfig {
+  input: string;
+  output: string;
+  templates?: string;
+  skipInstall?: boolean;
+  skipLint?: boolean;
+  tags: Record<string, TagConfig>;
+}

package/src/types/generation.types.ts

@@ -0,0 +1,50 @@
+/**
+ * Cumulative counters of artifacts generated during the process.
+ */
+export interface GeneratedCount {
+  models: number;
+  repositories: number;
+  mappers: number;
+  useCases: number;
+  providers: number;
+  mocks: number;
+  specs: number;
+}
+
+/**
+ * Result returned by the lint/format step.
+ */
+export interface LintResult {
+  prettier: { ran: boolean; filesFormatted: number };
+  eslint: { ran: boolean; filesFixed: number };
+}
+
+/**
+ * Per-tag summary included in the generation report.
+ */
+export interface TagDetail {
+  name: string;
+  description: string;
+  endpoints: number;
+}
+
+/**
+ * Final generation report persisted as `generation-report.json`.
+ */
+export interface GenerationReport {
+  timestamp: string;
+  tags: number;
+  endpoints: number;
+  tagDetails: TagDetail[];
+  outputDirectory: string;
+  linting: LintResult;
+  structure: {
+    dtos: number;
+    repositories: number;
+    mappers: number;
+    useCases: number;
+    providers: number;
+    mocks: number;
+    specs: number;
+  };
+}

package/src/types/index.ts

@@ -0,0 +1,8 @@
+/**
+ * @module types
+ * @description Barrel that re-exports all shared types and interfaces for the project.
+ */
+export * from './cli.types';
+export * from './swagger.types';
+export * from './openapi.types';
+export * from './generation.types';

package/src/types/openapi.types.ts

@@ -0,0 +1,126 @@
+/**
+ * Summary of a single endpoint for display on the interactive selection screen.
+ */
+export interface OperationSummary {
+  nickname: string;
+  method: string;
+  path: string;
+  summary: string;
+}
+
+/**
+ * Tag with its summarised endpoints, used on the interactive selection screen.
+ */
+export interface TagSummary {
+  tag: string;
+  operations: OperationSummary[];
+}
+
+/**
+ * Selection filter map: tag → array of selected operation nicknames.
+ */
+export type SelectionFilter = Record<string, string[]>;
+
+/**
+ * Simplified representation of an OpenAPI component schema.
+ * Used to generate domain models (entities) and mappers.
+ */
+export interface OpenApiSchema {
+  properties?: Record<
+    string,
+    {
+      type?: string;
+      format?: string;
+      description?: string;
+      example?: unknown;
+      enum?: unknown[];
+      $ref?: string;
+      items?: { $ref?: string; type?: string };
+    }
+  >;
+  required?: string[];
+  description?: string;
+}
+
+/**
+ * Representation of an OpenAPI operation (GET, POST, etc.) within a path.
+ * Contains the information needed to generate repositories and use cases.
+ */
+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 };
+          };
+        }
+      >;
+    }
+  >;
+}
+
+/**
+ * A single parameter of a normalised API operation, ready for Mustache template consumption.
+ */
+export interface TagOperationParam {
+  paramName: string;
+  dataType: string;
+  description: string;
+  required: boolean;
+  '-last': boolean;
+  testValue?: string;
+}
+
+/**
+ * Normalised operation ready to be consumed by Mustache templates.
+ * Each instance represents an endpoint grouped under an API tag.
+ */
+export interface TagOperation {
+  nickname: string;
+  summary: string;
+  notes: string;
+  httpMethod: string;
+  uppercaseHttpMethod: string;
+  path: string;
+  allParams: TagOperationParam[];
+  hasQueryParams: boolean;
+  queryParams: unknown[];
+  hasBodyParam: boolean;
+  bodyParam: string;
+  hasOptions: boolean;
+  hasBothParamsAndBody: boolean;
+  returnType: string | boolean;
+  returnBaseType: string | boolean;
+  returnTypeVarName: string | boolean;
+  returnBaseTypeVarName: string | boolean;
+  isListContainer: boolean;
+  vendorExtensions: Record<string, unknown>;
+}

package/src/types/swagger.types.ts

@@ -0,0 +1,9 @@
+/**
+ * Result of parsing an OpenAPI/Swagger file.
+ * Contains the raw structures extracted from the spec for further processing.
+ */
+export interface SwaggerAnalysis {
+  tags: unknown[];
+  paths: Record<string, unknown>;
+  swagger: unknown;
+}