Merge pull request 'chore: update installation instructions and add mock files to README' (#65) from feat/update-docu into main

Reviewed-on: #65
Reviewed-by: blas <me@blassanto.me>

.gitea/workflows/publish.yml

@@ -62,21 +62,17 @@ jobs:
       - name: Build binaries
         run: bun run binaries
 
-      - name: Configure Gitea registry auth
+      - name: Configure npm registry auth
         run: |
-          echo "@blas:registry=https://git.blassanto.me/api/packages/blas/npm/" >> ~/.npmrc
-          echo "//git.blassanto.me/api/packages/blas/npm/:_authToken=${NODE_AUTH_TOKEN}" >> ~/.npmrc
-          cat >> ~/.bunfig.toml << EOF
-          [install.scopes]
-          "@blas" = { registry = "https://git.blassanto.me/api/packages/blas/npm/", token = "${NODE_AUTH_TOKEN}" }
-          EOF
+          echo "registry=https://registry.npmjs.org" >> ~/.npmrc
+          echo "//registry.npmjs.org/:_authToken=${NODE_AUTH_TOKEN}" >> ~/.npmrc
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
-      - name: Publish to Gitea registry
+      - name: Publish to npm registry
         run: bun publish --access public
         env:
-          NODE_AUTH_TOKEN: ${{ secrets.PUBLISH_TOKEN }}
+          BUN_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
 
       - name: Create Gitea release and upload binaries
         run: |
@@ -89,7 +85,7 @@ jobs:
             -d "{
               \"tag_name\": \"${GITHUB_REF_NAME}\",
               \"name\": \"v${VERSION}\",
-              \"body\": \"## Installation\n\nDownload the binary for your platform or install via the npm registry:\n\n\`\`\`bash\nbun add -g @blas/openapi-clean-arch-generator --registry https://git.blassanto.me/api/packages/blas/npm/\n\`\`\`\",
+              \"body\": \"## Installation\n\nDownload the binary for your platform or install via the npm registry:\n\n\`\`\`bash\nbun add -g @0kmpo/openapi-clean-arch-generator\n\`\`\`\",
               \"draft\": false,
               \"prerelease\": false
             }" | bun -e "let d='';process.stdin.on('data',c=>d+=c).on('end',()=>console.log(JSON.parse(d).id))")

README.md

@@ -15,29 +15,29 @@ Download the binary for your platform from the releases page and run it directly
 
 ```bash
 # macOS (Apple Silicon)
-curl -L <release-url>/generate-clean-arch-macos-arm64 -o generate-clean-arch
+curl -L https://git.blassanto.me/blas/openapi-clean-arch-gen/releases/latest/download/generate-clean-arch-macos-arm64 -o generate-clean-arch
 chmod +x generate-clean-arch && ./generate-clean-arch -i swagger.yaml
 
 # macOS (Intel)
-curl -L <release-url>/generate-clean-arch-macos-x64 -o generate-clean-arch
+curl -L https://git.blassanto.me/blas/openapi-clean-arch-gen/releases/latest/download/generate-clean-arch-macos-x64 -o generate-clean-arch
 chmod +x generate-clean-arch && ./generate-clean-arch -i swagger.yaml
 
 # Linux x64
-curl -L <release-url>/generate-clean-arch-linux-x64 -o generate-clean-arch
+curl -L https://git.blassanto.me/blas/openapi-clean-arch-gen/releases/latest/download/generate-clean-arch-linux-x64 -o generate-clean-arch
 chmod +x generate-clean-arch && ./generate-clean-arch -i swagger.yaml
 
 # Windows (PowerShell)
-curl -L <release-url>/generate-clean-arch-windows-x64.exe -o generate-clean-arch.exe
+curl -L https://git.blassanto.me/blas/openapi-clean-arch-gen/releases/latest/download/generate-clean-arch-windows-x64.exe -o generate-clean-arch.exe
 .\generate-clean-arch.exe -i swagger.yaml
 ```
 
-### Option 1: Install as a global CLI from the registry
+### Option 1: Install as a global CLI from npm
 
 ```bash
-bun add -g @blas/openapi-clean-arch-generator --registry https://git.blassanto.me/api/packages/blas/npm/
+bun add -g @0kmpo/openapi-clean-arch-generator
 ```
 
-Or configure the registry in your `.npmrc` / `bunfig.toml` and then run:
+Then run:
 
 ```bash
 generate-clean-arch -i swagger.yaml
@@ -109,48 +109,54 @@ src/app/
 ├── data/                          # Data layer
 │   ├── dtos/                      # Data Transfer Objects
 │   │   ├── node/
-│   │   │   └── node.dto.ts
+│   │   │   ├── node.dto.ts
+│   │   │   └── node.dto.mock.ts
 │   │   ├── order-type/
-│   │   │   └── order-type.dto.ts
+│   │   │   ├── order-type.dto.ts
+│   │   │   └── order-type.dto.mock.ts
 │   │   └── supply-mode/
-│   │       └── supply-mode.dto.ts
+│   │       ├── supply-mode.dto.ts
+│   │       └── supply-mode.dto.mock.ts
 │   ├── repositories/              # Repository implementations
 │   │   ├── node.repository.impl.ts
+│   │   ├── node.repository.impl.mock.ts
+│   │   ├── node.repository.impl.spec.ts
 │   │   ├── order-type.repository.impl.ts
-│   │   └── supply-mode.repository.impl.ts
+│   │   ├── order-type.repository.impl.mock.ts
+│   │   ├── order-type.repository.impl.spec.ts
+│   │   └── ...
 │   └── mappers/                   # DTO → Entity transformers
 │       ├── node.mapper.ts
+│       ├── node.mapper.spec.ts
 │       ├── order-type.mapper.ts
-│       └── supply-mode.mapper.ts
+│       ├── order-type.mapper.spec.ts
+│       └── ...
 ├── domain/                        # Domain layer
 │   ├── repositories/              # Repository contracts
 │   │   ├── node.repository.contract.ts
-│   │   ├── order-type.repository.contract.ts
-│   │   └── supply-mode.repository.contract.ts
+│   │   └── ...
 │   └── use-cases/                 # Use cases
 │       ├── node/
 │       │   ├── node.use-cases.contract.ts
-│       │   └── node.use-cases.impl.ts
-│       ├── order-type/
-│       │   ├── order-type.use-cases.contract.ts
-│       │   └── order-type.use-cases.impl.ts
-│       └── supply-mode/
-│           ├── supply-mode.use-cases.contract.ts
-│           └── supply-mode.use-cases.impl.ts
+│       │   ├── node.use-cases.impl.ts
+│       │   ├── node.use-cases.mock.ts
+│       │   └── node.use-cases.impl.spec.ts
+│       └── ...
 ├── di/                            # Dependency injection
 │   ├── repositories/              # Repository providers
 │   │   ├── node.repository.provider.ts
-│   │   ├── order-type.repository.provider.ts
-│   │   └── supply-mode.repository.provider.ts
+│   │   ├── node.repository.provider.mock.ts
+│   │   └── ...
 │   └── use-cases/                 # Use case providers
 │       ├── node.use-cases.provider.ts
-│       ├── order-type.use-cases.provider.ts
-│       └── supply-mode.use-cases.provider.ts
+│       ├── node.use-cases.provider.mock.ts
+│       └── ...
 └── entities/                      # Domain entities
     └── models/
         ├── node.model.ts
-        ├── order-type.model.ts
-        └── supply-mode.model.ts
+        ├── node.model.mock.ts
+        ├── node.model.spec.ts
+        └── ...
 ```
 
 ## 🔧 Template Customization
@@ -160,14 +166,24 @@ Templates live in `templates/` and use [Mustache](https://mustache.github.io/) s
 | Template | Generates |
 |---|---|
 | `model.mustache` | DTOs |
+| `model.mock.mustache` | DTO mocks |
+| `dto.mock.mustache` | DTO mocks (alternative) |
 | `model-entity.mustache` | Domain entity models |
+| `model-entity.spec.mustache` | Entity model specs |
 | `mapper.mustache` | DTO → Entity mappers |
+| `mapper.spec.mustache` | Mapper specs |
 | `api.repository.contract.mustache` | Repository contracts |
 | `api.repository.impl.mustache` | Repository implementations |
+| `api.repository.impl.mock.mustache` | Repository mocks |
+| `api.repository.impl.spec.mustache` | Repository specs |
 | `api.use-cases.contract.mustache` | Use case contracts |
 | `api.use-cases.impl.mustache` | Use case implementations |
+| `api.use-cases.mock.mustache` | Use case mocks |
+| `api.use-cases.impl.spec.mustache` | Use case specs |
 | `repository.provider.mustache` | Repository DI providers |
+| `repository.provider.mock.mustache` | Repository provider mocks |
 | `use-cases.provider.mustache` | Use case DI providers |
+| `use-cases.provider.mock.mustache` | Use case provider mocks |
 
 ### Available Mustache variables
 
@@ -194,12 +210,23 @@ After each run a `generation-report.json` file is created:
   "timestamp": "2025-01-15T10:30:00.000Z",
   "tags": 3,
   "endpoints": 8,
+  "tagDetails": [
+    { "name": "User", "description": "User operations", "endpoints": 3 },
+    { "name": "Product", "description": "Product operations", "endpoints": 2 }
+  ],
   "outputDirectory": "./src/app",
+  "linting": {
+    "prettier": { "ran": true, "filesFormatted": 42 },
+    "eslint": { "ran": true, "filesFixed": 42 }
+  },
   "structure": {
     "dtos": 15,
     "repositories": 9,
-    "mappers": 3,
-    "useCases": 6
+    "mappers": 5,
+    "useCases": 6,
+    "providers": 12,
+    "mocks": 18,
+    "specs": 14
   }
 }
 ```

generation-config.json

@@ -0,0 +1,24 @@
+{
+  "input": "example-swagger.yaml",
+  "output": "./src/app",
+  "skipLint": false,
+  "skipInstall": false,
+  "tags": {
+    "User": {
+      "baseUrl": "apiUrl",
+      "endpoints": [
+        "getUsers",
+        "createUser",
+        "getUserById",
+        "deleteUser"
+      ]
+    },
+    "Product": {
+      "baseUrl": "apiUrl",
+      "endpoints": [
+        "getProducts"
+      ]
+    }
+  },
+  "templates": "/Users/bsantome/Downloads/openapi-clean-arch-generator/templates"
+}

main.ts

@@ -26,6 +26,13 @@ import { generateReport } from './src/generators/report.generator';
 import { lintGeneratedFiles } from './src/generators/lint.generator';
 import { findEnvironmentFile, parseApiKeys } from './src/utils/environment-finder';
 import { askApiKeysForTags, askSelectionFilter } from './src/utils/prompt';
+import {
+  loadConfig,
+  generateDefaultConfig,
+  writeConfig,
+  deriveSelectionFilter,
+  deriveTagApiKeyMap
+} from './src/utils/config';
 import type { SelectionFilter, LintResult } from './src/types';
 import type { CliOptions } from './src/types';
 import packageJson from './package.json';
@@ -48,6 +55,8 @@ program
   .option('--dry-run', 'Simulate without generating files')
   .option('--skip-lint', 'Skip post-generation linting and formatting')
   .option('-s, --select-endpoints', 'Interactively select which tags and endpoints to generate')
+  .option('-c, --config <file>', 'Use a JSON configuration file (skips interactive prompts)')
+  .option('--init-config [file]', 'Generate a JSON configuration file instead of generating code')
   .parse(process.argv);
 
 const options = program.opts<CliOptions>();
@@ -62,6 +71,21 @@ async function main(): Promise<void> {
 
   const logPath = path.join(process.cwd(), 'generation.log');
   initGenerationLog(logPath);
+
+  // ── CONFIG FILE: override CLI defaults with config values ─────────────────
+  const configFile = options.config;
+  const generationConfig = configFile ? loadConfig(configFile) : undefined;
+
+  if (generationConfig) {
+    if (generationConfig.input) options.input = generationConfig.input;
+    if (generationConfig.output) options.output = generationConfig.output;
+    if (generationConfig.templates) options.templates = generationConfig.templates;
+    if (generationConfig.skipInstall !== undefined)
+      options.skipInstall = generationConfig.skipInstall;
+    if (generationConfig.skipLint !== undefined) options.skipLint = generationConfig.skipLint;
+    logDetail('config', `Using configuration file: ${configFile}`);
+  }
+
   logDetail('config', `Input: ${options.input}`);
   logDetail('config', `Output: ${options.output}`);
   logDetail('config', `Templates: ${options.templates}`);
@@ -90,6 +114,29 @@ async function main(): Promise<void> {
   }
 
   const analysis = analyzeSwagger(options.input);
+  const tagSummaries = extractTagsWithOperations(analysis);
+
+  // ── INIT CONFIG MODE: generate config file and exit ───────────────────────
+  if (options.initConfig !== undefined) {
+    const envFile = findEnvironmentFile(process.cwd());
+    let apiKeys: ReturnType<typeof parseApiKeys> = [];
+    if (envFile) {
+      const envContent = fs.readFileSync(envFile, 'utf8');
+      apiKeys = parseApiKeys(envContent);
+    }
+
+    const defaultConfig = generateDefaultConfig(analysis, tagSummaries, options, apiKeys);
+    const outputFile =
+      typeof options.initConfig === 'string' ? options.initConfig : 'generation-config.json';
+
+    writeConfig(defaultConfig, outputFile);
+    logSuccess(`Configuration file generated: ${outputFile}`);
+    logDetail(
+      'config',
+      'Edit the file to customise tags, endpoints and baseUrls, then run with --config'
+    );
+    return;
+  }
 
   if (options.dryRun) {
     logWarning('Finishing in DRY RUN mode');
@@ -99,38 +146,50 @@ async function main(): Promise<void> {
   createDirectoryStructure(options.output);
 
   // ── SELECTION: tags and endpoints ─────────────────────────────────────────
-  const tagSummaries = extractTagsWithOperations(analysis);
   let selectionFilter: SelectionFilter = {};
+  let tagApiKeyMap: Record<string, string>;
 
-  if (options.selectEndpoints) {
-    selectionFilter = await askSelectionFilter(tagSummaries);
-  }
-
-  const selectedTags = options.selectEndpoints
-    ? Object.keys(selectionFilter)
-    : tagSummaries.map((t) => t.tag);
-
-  // ── ENVIRONMENT API KEY SELECTION ──────────────────────────────────────────
-  const envFile = findEnvironmentFile(process.cwd());
-  let apiKeys: ReturnType<typeof parseApiKeys> = [];
-
-  if (envFile) {
-    const envContent = fs.readFileSync(envFile, 'utf8');
-    apiKeys = parseApiKeys(envContent);
-    logSuccess(
-      `environment.ts found: ${colors.cyan}${path.relative(process.cwd(), envFile)}${colors.reset}`
-    );
-    if (apiKeys.length === 0) {
-      logWarning('No keys containing "api" found in environment.ts. Will be requested manually.');
-    }
+  if (generationConfig) {
+    // Config-driven: derive everything from the JSON file
+    selectionFilter = deriveSelectionFilter(generationConfig);
+    tagApiKeyMap = deriveTagApiKeyMap(generationConfig);
+    logDetail('config', `Tags from config: ${Object.keys(generationConfig.tags).join(', ')}`);
+    Object.entries(tagApiKeyMap).forEach(([tag, key]) => {
+      logDetail('config', `API key for "${tag}": environment.${key}.url`);
+    });
   } else {
-    logWarning('No environment.ts found. The key will be requested manually per repository.');
+    // Interactive mode (original behaviour)
+    if (options.selectEndpoints) {
+      selectionFilter = await askSelectionFilter(tagSummaries);
+    }
+
+    const selectedTags = options.selectEndpoints
+      ? Object.keys(selectionFilter)
+      : tagSummaries.map((t) => t.tag);
+
+    // ── ENVIRONMENT API KEY SELECTION ────────────────────────────────────────
+    const envFile = findEnvironmentFile(process.cwd());
+    let apiKeys: ReturnType<typeof parseApiKeys> = [];
+
+    if (envFile) {
+      const envContent = fs.readFileSync(envFile, 'utf8');
+      apiKeys = parseApiKeys(envContent);
+      logSuccess(
+        `environment.ts found: ${colors.cyan}${path.relative(process.cwd(), envFile)}${colors.reset}`
+      );
+      if (apiKeys.length === 0) {
+        logWarning('No keys containing "api" found in environment.ts. Will be requested manually.');
+      }
+    } else {
+      logWarning('No environment.ts found. The key will be requested manually per repository.');
+    }
+
+    tagApiKeyMap = await askApiKeysForTags(selectedTags, apiKeys);
+    Object.entries(tagApiKeyMap).forEach(([tag, key]) => {
+      logDetail('config', `API key for "${tag}": environment.${key}.url`);
+    });
   }
 
-  const tagApiKeyMap = await askApiKeysForTags(selectedTags, apiKeys);
-  Object.entries(tagApiKeyMap).forEach(([tag, key]) => {
-    logDetail('config', `API key for "${tag}": environment.${key}.url`);
-  });
   // ──────────────────────────────────────────────────────────────────────────
 
   const tempDir = generateCode(options.input, options.templates);

package.json

@@ -1,6 +1,6 @@
 {
-  "name": "@blas/openapi-clean-arch-generator",
-  "version": "1.3.0",
+  "name": "@0kmpo/openapi-clean-arch-generator",
+  "version": "1.3.9",
   "description": "Angular Clean Architecture generator from OpenAPI/Swagger",
   "main": "dist/main.js",
   "bin": {
@@ -39,9 +39,6 @@
     }
   ],
   "license": "MIT",
-  "publishConfig": {
-    "registry": "https://git.blassanto.me/api/packages/blas/npm/"
-  },
   "dependencies": {
     "chalk": "^4.1.2",
     "commander": "^11.1.0",

src/types/cli.types.ts

@@ -10,4 +10,27 @@ export interface CliOptions {
   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>;
 }

src/utils/config.ts

@@ -0,0 +1,118 @@
+import fs from 'fs-extra';
+import { logInfo, logError } from './logger';
+import type { GenerationConfig, TagConfig } from '../types';
+import type { SwaggerAnalysis } from '../types';
+import type { TagSummary } from '../types';
+import type { ApiKeyInfo } from './environment-finder';
+
+/**
+ * Loads and validates a GenerationConfig from a JSON file.
+ */
+export function loadConfig(filePath: string): GenerationConfig {
+  if (!fs.existsSync(filePath)) {
+    logError(`Configuration file not found: ${filePath}`);
+    process.exit(1);
+  }
+
+  const raw = fs.readFileSync(filePath, 'utf8');
+  let config: GenerationConfig;
+
+  try {
+    config = JSON.parse(raw) as GenerationConfig;
+  } catch {
+    logError(`Invalid JSON in configuration file: ${filePath}`);
+    process.exit(1);
+  }
+
+  if (!config.tags || typeof config.tags !== 'object') {
+    logError('Configuration file must contain a "tags" object');
+    process.exit(1);
+  }
+
+  for (const [tag, tagConfig] of Object.entries(config.tags)) {
+    if (!tagConfig.baseUrl || typeof tagConfig.baseUrl !== 'string') {
+      logError(`Tag "${tag}" must have a "baseUrl" string`);
+      process.exit(1);
+    }
+    if (!Array.isArray(tagConfig.endpoints) || tagConfig.endpoints.length === 0) {
+      logError(`Tag "${tag}" must have a non-empty "endpoints" array`);
+      process.exit(1);
+    }
+  }
+
+  return config;
+}
+
+/**
+ * Builds a default GenerationConfig from a swagger analysis, including all tags
+ * and all endpoints. Useful for --init-config to scaffold a config template.
+ */
+export function generateDefaultConfig(
+  analysis: SwaggerAnalysis,
+  tagSummaries: TagSummary[],
+  cliOptions: {
+    input: string;
+    output: string;
+    templates?: string;
+    skipLint?: boolean;
+    skipInstall?: boolean;
+  },
+  apiKeys: ApiKeyInfo[]
+): GenerationConfig {
+  const tags: Record<string, TagConfig> = {};
+
+  for (const summary of tagSummaries) {
+    const matchingKey = apiKeys.find((k) =>
+      k.key.toLowerCase().includes(summary.tag.toLowerCase())
+    );
+
+    tags[summary.tag] = {
+      baseUrl: matchingKey?.key || 'apiUrl',
+      endpoints: summary.operations.map((op) => op.nickname)
+    };
+  }
+
+  const config: GenerationConfig = {
+    input: cliOptions.input,
+    output: cliOptions.output,
+    skipLint: cliOptions.skipLint ?? false,
+    skipInstall: cliOptions.skipInstall ?? false,
+    tags
+  };
+
+  if (cliOptions.templates) {
+    config.templates = cliOptions.templates;
+  }
+
+  return config;
+}
+
+/**
+ * Writes a GenerationConfig to a JSON file.
+ */
+export function writeConfig(config: GenerationConfig, filePath: string): void {
+  fs.writeFileSync(filePath, JSON.stringify(config, null, 2) + '\n', 'utf8');
+  logInfo(`Configuration file written to: ${filePath}`);
+}
+
+/**
+ * Derives the selectionFilter (tag → endpoint nicknames) from a GenerationConfig.
+ */
+export function deriveSelectionFilter(config: GenerationConfig): Record<string, string[]> {
+  const filter: Record<string, string[]> = {};
+  for (const [tag, tagConfig] of Object.entries(config.tags)) {
+    filter[tag] = [...tagConfig.endpoints];
+  }
+  return filter;
+}
+
+/**
+ * Derives the tagApiKeyMap (tag → baseUrl key) from a GenerationConfig.
+ */
+export function deriveTagApiKeyMap(config: GenerationConfig): Record<string, string> {
+  const map: Record<string, string> = {};
+  for (const [tag, tagConfig] of Object.entries(config.tags)) {
+    map[tag] = tagConfig.baseUrl;
+  }
+  return map;
+}

templates/api.use-cases.impl.spec.mustache

@@ -76,7 +76,10 @@ describe('{{classname}}UseCasesImpl', () => {
       mockRepository.{{nickname}}.and.returnValue(of(undefined));
 
       useCase.{{nickname}}({{#allParams}}{{{testValue}}}{{^-last}}, {{/-last}}{{/allParams}}).subscribe({
-        complete: () => done()
+        complete: () => {
+          expect(mockRepository.{{nickname}}).toHaveBeenCalledOnceWith({{#allParams}}{{{testValue}}}{{^-last}}, {{/-last}}{{/allParams}});
+          done();
+        }
       });
       {{/returnBaseType}}
       {{/isListContainer}}