@0kmpo/openapi-clean-arch-generator 1.3.14 → 1.4.0

package/README.md

@@ -75,18 +75,41 @@ Options:
   -i, --input <file>         OpenAPI/Swagger file (yaml or json) [default: swagger.yaml]
   -o, --output <dir>         Output directory [default: ./src/app]
   -t, --templates <dir>      Custom templates directory [default: ./templates]
+  -k, --base-name <name>     Base name for generated folders (defaults to swagger filename)
   -s, --select-endpoints     Interactively select tags and endpoints to generate
+  -c, --config <file>        Use a JSON configuration file (skips interactive prompts)
+  --init-config [file]       Generate a JSON configuration file instead of generating code
   --skip-install             Skip dependency installation
+  --skip-lint                Skip post-generation linting and formatting
   --dry-run                  Simulate without writing files
   -h, --help                 Show help
 ```
 
+### Base name (`-k`)
+
+The generator organises output into subfolders based on a **base name** derived from your OpenAPI file. By default it extracts the token immediately before `-swagger` in the filename:
+
+| Filename | Derived base name |
+|---|---|
+| `my-app-swagger.yaml` | `app` |
+| `ecommerce-swagger.yaml` | `ecommerce` |
+| `backoffice.yaml` | `backoffice` (+ warning) |
+
+Use `-k` to override this value:
+
+```bash
+generate-clean-arch -i api.yaml -k example1   # all files go under example1/
+```
+
 ### Examples
 
 ```bash
 # Generate from swagger.yaml into src/app
 generate-clean-arch -i swagger.yaml -o ./src/app
 
+# Override base name (folder organisation)
+generate-clean-arch -i ecommerce-api-swagger.yaml -o src/app -k ecommerce
+
 # Interactively select tags/endpoints
 generate-clean-arch -i api.yaml -s
 
@@ -96,69 +119,72 @@ generate-clean-arch -i api.yaml -t ./my-templates
 # Dry run (no files written)
 generate-clean-arch -i swagger.yaml --dry-run
 
+# Skip linting after generation
+generate-clean-arch -i swagger.yaml --skip-lint
+
+# Generate a config file to reuse later
+generate-clean-arch --init-config generation-config.json
+
+# Run using a config file (no interactive prompts)
+generate-clean-arch -c generation-config.json
+
 # Full example with all options
-generate-clean-arch -i ./docs/api.yaml -o ./frontend/src/app -t ./custom-templates
+generate-clean-arch -i ./docs/api.yaml -o ./frontend/src/app -t ./custom-templates -k myapp
 ```
 
 ## 📁 Generated Structure
 
-The generator creates the following structure following Clean Architecture:
+The generator creates the following structure following Clean Architecture. All artefacts are organised under a **base name** folder (derived from the OpenAPI filename or set with `-k`), and within each layer further grouped by **tag subfolders** (one per API tag, or `shared` for types used across multiple tags):
 
 ```
 src/app/
-├── data/                          # Data layer
-│   ├── dtos/                      # Data Transfer Objects
-│   │   ├── node/
-│   │   │   ├── node.dto.ts
-│   │   │   └── node.dto.mock.ts
-│   │   ├── order-type/
-│   │   │   ├── order-type.dto.ts
-│   │   │   └── order-type.dto.mock.ts
-│   │   └── supply-mode/
-│   │       ├── 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
-│   │   ├── 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
-│       ├── order-type.mapper.spec.ts
+├── <baseName>/                          # Base name folder (e.g. "ecommerce")
+│   ├── <tag1>/                          # Tag subfolder (camelCase, e.g. "user")
+│   │   ├── data/dtos/                   # Data Transfer Objects
+│   │   │   ├── user.dto.ts
+│   │   │   ├── user.dto.mock.ts
+│   │   │   └── ...
+│   │   ├── data/repositories/           # Repository implementations
+│   │   │   ├── user.repository.impl.ts
+│   │   │   ├── user.repository.impl.mock.ts
+│   │   │   └── user.repository.impl.spec.ts
+│   │   ├── data/mappers/                # DTO → Entity transformers
+│   │   │   ├── user.mapper.ts
+│   │   │   └── user.mapper.spec.ts
+│   │   ├── domain/repositories/         # Repository contracts
+│   │   │   └── user.repository.contract.ts
+│   │   ├── domain/use-cases/            # Use cases
+│   │   │   ├── user.use-cases.contract.ts
+│   │   │   ├── user.use-cases.impl.ts
+│   │   │   ├── user.use-cases.mock.ts
+│   │   │   └── user.use-cases.impl.spec.ts
+│   │   ├── di/repositories/             # Repository DI providers
+│   │   │   ├── user.repository.provider.ts
+│   │   │   └── user.repository.provider.mock.ts
+│   │   └── di/use-cases/                # Use case DI providers
+│   │       ├── user.use-cases.provider.ts
+│   │       └── user.use-cases.provider.mock.ts
+│   ├── <tag2>/                          # Another tag (e.g. "productFormat")
+│   │   └── ...                          # Same internal structure
+│   └── shared/                          # Shared types (used by 0 or multiple tags)
 │       └── ...
-├── domain/                        # Domain layer
-│   ├── repositories/              # Repository contracts
-│   │   ├── node.repository.contract.ts
-│   │   └── ...
-│   └── use-cases/                 # Use cases
-│       ├── node/
-│       │   ├── node.use-cases.contract.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
-│   │   ├── node.repository.provider.mock.ts
-│   │   └── ...
-│   └── use-cases/                 # Use case providers
-│       ├── node.use-cases.provider.ts
-│       ├── node.use-cases.provider.mock.ts
-│       └── ...
-└── entities/                      # Domain entities
+└── entities/                            # Domain entities (outside baseName)
     └── models/
-        ├── node.model.ts
-        ├── node.model.mock.ts
-        ├── node.model.spec.ts
-        └── ...
+        ├── <tag1>/
+        │   ├── user.model.ts
+        │   ├── user.model.mock.ts
+        │   └── user.model.spec.ts
+        └── shared/
+            └── ...
 ```
 
+### How the folder organisation works
+
+1. **Base name** — derived from the OpenAPI filename (token before `-swagger`) or overridden with `-k`
+2. **Tag subfolders** — each API tag gets its own camelCase folder (e.g. `User` → `user`, `Product Format` → `productFormat`)
+3. **Shared types** — schemas used by zero or multiple tags land in `shared/`
+4. **Layer grouping** — each tag subfolder mirrors the full Clean Architecture layers (`data/`, `domain/`, `di/`, `entities/`)
+
 ## 🔧 Template Customization
 
 Templates live in `templates/` and use [Mustache](https://mustache.github.io/) syntax. Override them by passing your own directory with `-t`.
@@ -219,6 +245,20 @@ After each run a `generation-report.json` file is created:
     "prettier": { "ran": true, "filesFormatted": 42 },
     "eslint": { "ran": true, "filesFixed": 42 }
   },
+  "warnings": {
+    "total": 2,
+    "exampleMismatches": [
+      {
+        "schemaName": "UserDto",
+        "propertyName": "age",
+        "declaredType": "string",
+        "exampleValue": 25,
+        "exampleJsType": "number",
+        "action": "coerced",
+        "coercedValue": "25"
+      }
+    ]
+  },
   "structure": {
     "dtos": 15,
     "repositories": 9,
@@ -231,27 +271,35 @@ After each run a `generation-report.json` file is created:
 }
 ```
 
+The report includes **example/type mismatch warnings** — when your OpenAPI schema declares a type (e.g. `string`) but the `example` value has a different JS type (e.g. a number). The generator either coerces the value or falls back to a type default and logs it here.
+
 ## 🎯 Angular Integration Example
 
 ### 1. Generate code
 
 ```bash
-generate-clean-arch -i ./docs/api.yaml -o ./src/app
+generate-clean-arch -i ./docs/api.yaml -o ./src/app -k myapp
 ```
 
+### Automatic environment API key detection
+
+During generation the tool automatically searches for an `environment.ts` file (up to 8 levels deep, skipping `node_modules`, `.git`, `dist`, etc.). It extracts keys containing "api" and offers them for selection per tag. If no file or no matching keys are found, you'll be prompted to enter them manually.
+
+Each tag's repositories use the selected environment key to configure the base URL for HTTP calls (e.g. `environment.apiUrl`).
+
 ### 2. Register providers
 
 In your `app.config.ts` (Angular 17+ standalone):
 
 ```typescript
 import { ApplicationConfig } from '@angular/core';
-import { NodeRepositoryProvider } from './di/repositories/node.repository.provider';
-import { NodeUseCasesProvider } from './di/use-cases/node.use-cases.provider';
+import { UserRepositoryProvider } from './myapp/user/di/repositories/user.repository.provider';
+import { UserUseCasesProvider } from './myapp/user/di/use-cases/user.use-cases.provider';
 
 export const appConfig: ApplicationConfig = {
   providers: [
-    NodeRepositoryProvider,
-    NodeUseCasesProvider,
+    UserRepositoryProvider,
+    UserUseCasesProvider,
     // ... rest of generated providers
   ]
 };
@@ -261,18 +309,18 @@ export const appConfig: ApplicationConfig = {
 
 ```typescript
 import { Component, inject } from '@angular/core';
-import { NODE_USE_CASES } from './domain/use-cases/node/node.use-cases.contract';
+import { USER_USE_CASES } from './domain/use-cases/myapp/user/user.use-cases.contract';
 
 @Component({
-  selector: 'app-nodes',
+  selector: 'app-users',
   template: `...`
 })
-export class NodesComponent {
-  readonly #nodeUseCases = inject(NODE_USE_CASES);
+export class UsersComponent {
+  readonly #userUseCases = inject(USER_USE_CASES);
 
-  loadNodes(): void {
-    this.#nodeUseCases.getNodes().subscribe((nodes) => {
-      console.log(nodes);
+  loadUsers(): void {
+    this.#userUseCases.getUsers().subscribe((users) => {
+      console.log(users);
     });
   }
 }
@@ -296,6 +344,18 @@ Specify the correct path with `-i`:
 generate-clean-arch -i ./path/to/your/api.yaml
 ```
 
+### Base name warning
+
+If your OpenAPI file doesn't contain `-swagger` in the filename (e.g. `backoffice.yaml`), the generator uses the last token and emits a warning. Use `-k` to set it explicitly, or define it in your config file:
+
+```bash
+# Via CLI
+generate-clean-arch -i backoffice.yaml -k backoffice
+
+# Via config file (-c)
+generate-clean-arch -c generation-config.json   # with "baseName": "backoffice" in the JSON
+```
+
 ### Path aliases `@/` not resolving
 
 Configure the aliases in your Angular project's `tsconfig.json`:
@@ -316,12 +376,21 @@ Configure the aliases in your Angular project's `tsconfig.json`:
 2. Check the Mustache syntax
 3. Use `--dry-run` to simulate without writing files
 
+### Example/type mismatch warnings
+
+When your OpenAPI schema declares a type (e.g. `type: string`) but the `example` value is a different JS type (e.g. `example: 25` — a number), the generator either coerces it or uses a type default. Check `generation-report.json` under `warnings.exampleMismatches` for details.
+
 ## 📝 Notes
 
 - The generator produces ready-to-use `.ts` files, it does not compile them
 - Providers must be registered manually in your Angular module or config
 - Requires Angular 17+ (uses the `inject()` function)
 - Compatible with both standalone and module-based projects
+- **Base name**: derived from the OpenAPI filename (token before `-swagger`), overridden with `-k`, or set in the config file (`-c`) as `"baseName"`
+- **Tag organisation**: each API tag gets its own subfolder; shared types go in `shared/`
+- **Environment detection**: automatically finds `environment.ts` and offers API keys per tag
+- **Example validation**: type mismatches between declared types and example values are detected, coerced when possible, and reported in `generation-report.json`
+- **Config workflow**: use `--init-config` to generate a `generation-config.json`, edit it to customise tags/endpoints/baseUrls/baseName, then reuse with `-c`
 
 ## 🤝 Contributing
 

package/dist/main.js

@@ -17,8 +17,10 @@ const clean_arch_generator_1 = require("./src/generators/clean-arch.generator");
 const report_generator_1 = require("./src/generators/report.generator");
 const lint_generator_1 = require("./src/generators/lint.generator");
 const environment_finder_1 = require("./src/utils/environment-finder");
+const example_validator_1 = require("./src/utils/example-validator");
 const prompt_1 = require("./src/utils/prompt");
 const config_1 = require("./src/utils/config");
+const name_formatter_1 = require("./src/utils/name-formatter");
 const package_json_1 = __importDefault(require("./package.json"));
 // Disable HTML escaping so that < and > produce valid TypeScript generic types.
 mustache_1.default.escape = function (text) {
@@ -36,6 +38,7 @@ commander_1.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('-k, --base-name <name>', 'Base name for generated folders (defaults to swagger filename)')
     .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);
@@ -62,6 +65,8 @@ async function main() {
             options.skipInstall = generationConfig.skipInstall;
         if (generationConfig.skipLint !== undefined)
             options.skipLint = generationConfig.skipLint;
+        if (generationConfig.baseName)
+            options.baseName = generationConfig.baseName;
         (0, logger_1.logDetail)('config', `Using configuration file: ${configFile}`);
     }
     (0, logger_1.logDetail)('config', `Input: ${options.input}`);
@@ -71,6 +76,8 @@ async function main() {
         (0, logger_1.logError)(`File not found: ${options.input}`);
         process.exit(1);
     }
+    const baseName = options.baseName ?? (0, name_formatter_1.deriveBaseName)(options.input);
+    (0, logger_1.logDetail)('config', `Base name: ${baseName}`);
     if (options.dryRun) {
         (0, logger_1.logWarning)('DRY RUN mode — no files will be generated');
     }
@@ -109,6 +116,7 @@ async function main() {
         return;
     }
     (0, filesystem_1.createDirectoryStructure)(options.output);
+    (0, example_validator_1.clearExampleMismatches)();
     // ── SELECTION: tags and endpoints ─────────────────────────────────────────
     let selectionFilter = {};
     let tagApiKeyMap;
@@ -150,10 +158,27 @@ async function main() {
     }
     // ──────────────────────────────────────────────────────────────────────────
     const tempDir = (0, dto_generator_1.generateCode)(options.input, options.templates);
-    (0, dto_generator_1.organizeFiles)(tempDir, options.output);
-    (0, dto_generator_1.addDtoImports)(options.output);
-    (0, clean_arch_generator_1.generateCleanArchitecture)(analysis, options.output, options.templates, tagApiKeyMap, selectionFilter);
+    // Compute schema→tag map before organizeFiles so DTOs land in the right subfolder
+    const tagsMapForSchema = (0, clean_arch_generator_1.buildTagsMapFromAnalysis)(analysis, selectionFilter);
+    const schemaTagMap = (0, clean_arch_generator_1.buildSchemaTagMap)(analysis.swagger.components
+        ?.schemas || {}, tagsMapForSchema);
+    (0, dto_generator_1.organizeFiles)(tempDir, options.output, schemaTagMap, baseName);
+    (0, dto_generator_1.addDtoImports)(options.output, baseName);
+    (0, clean_arch_generator_1.generateCleanArchitecture)(analysis, options.output, options.templates, tagApiKeyMap, selectionFilter, schemaTagMap, baseName);
     (0, filesystem_1.cleanup)(tempDir);
+    // ── EXAMPLE/TYPE MISMATCH WARNINGS ─────────────────────────────────────────
+    const mismatches = (0, example_validator_1.getExampleMismatches)();
+    if (mismatches.length > 0) {
+        console.log('');
+        (0, logger_1.logWarning)(`${mismatches.length} example/type mismatch(es) detected in OpenAPI schemas:`);
+        for (const m of mismatches) {
+            const action = m.action === 'coerced'
+                ? `→ coerced to ${JSON.stringify(m.coercedValue)}`
+                : '→ example ignored, using type default';
+            (0, logger_1.logWarning)(`  ${m.schemaName}.${m.propertyName}: type '${m.declaredType}' but example is ${m.exampleJsType} (${JSON.stringify(m.exampleValue)}) ${action}`);
+            (0, logger_1.logDetail)('VALIDATE', `${m.schemaName}.${m.propertyName}: declared=${m.declaredType} example=${JSON.stringify(m.exampleValue)} (${m.exampleJsType}) action=${m.action}`);
+        }
+    }
     const noLintResult = {
         prettier: { ran: false, filesFormatted: 0 },
         eslint: { ran: false, filesFixed: 0 }
@@ -170,6 +195,9 @@ async function main() {
     console.log(`   - Use Cases:        ${report.structure.useCases}`);
     console.log(`   - Providers:        ${report.structure.providers}`);
     console.log(`   - Mocks:            ${report.structure.mocks}`);
+    if (report.warnings.total > 0) {
+        console.log(`\n   ${logger_1.colors.yellow}⚠️  ${report.warnings.total} example/type mismatch(es) (see above)${logger_1.colors.reset}`);
+    }
     console.log(`\n📁 Files generated in: ${logger_1.colors.cyan}${options.output}${logger_1.colors.reset}\n`);
 }
 main().catch((error) => {

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@0kmpo/openapi-clean-arch-generator",
-    "version": "1.3.14",
+    "version": "1.4.0",
     "description": "Angular Clean Architecture generator from OpenAPI/Swagger",
     "main": "dist/main.js",
     "bin": {