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

package/README.md

@@ -75,6 +75,7 @@ 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
@@ -84,12 +85,31 @@ Options:
   -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
 
@@ -109,68 +129,62 @@ generate-clean-arch --init-config generation-config.json
 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
-│       └── ...
-├── 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
+├── <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)
 │       └── ...
-├── 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`.
@@ -231,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,
@@ -243,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
   ]
 };
@@ -273,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);
     });
   }
 }
@@ -308,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`:
@@ -328,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

@@ -20,6 +20,7 @@ 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) {
@@ -37,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);
@@ -63,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}`);
@@ -72,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');
     }
@@ -156,9 +162,9 @@ async function main() {
     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);
-    (0, dto_generator_1.addDtoImports)(options.output);
-    (0, clean_arch_generator_1.generateCleanArchitecture)(analysis, options.output, options.templates, tagApiKeyMap, selectionFilter, schemaTagMap);
+    (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)();

package/dist/package.json

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

package/dist/src/generators/clean-arch.generator.js

@@ -191,7 +191,7 @@ function buildSchemaTagMap(schemas, tagsMap) {
     return result;
 }
 /** Generates all Clean Architecture artefacts (models, mappers, repos, use cases, providers) using Mustache. */
-function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyMap = {}, selectionFilter = {}, precomputedSchemaTagMap = {}) {
+function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyMap = {}, selectionFilter = {}, precomputedSchemaTagMap = {}, baseName = '') {
     (0, logger_1.logStep)('Generating Clean Architecture artefacts using Mustache...');
     const generatedCount = {
         models: 0,
@@ -212,8 +212,9 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
         : buildSchemaTagMap(schemas, tagsMap);
     // 1. Generate Models, Entities and Mappers from Schemas
     Object.keys(schemas).forEach((schemaName) => {
-        const baseName = schemaName.replace(/Dto$/, '');
-        const tagFilename = schemaTagMap[baseName] || 'shared';
+        const schemaBaseName = schemaName.replace(/Dto$/, '');
+        const tagFilename = schemaTagMap[schemaBaseName] || 'shared';
+        const tagFolderPath = baseName ? `${baseName}/${tagFilename}` : tagFilename;
         const schemaObj = schemas[schemaName];
         const rawProperties = schemaObj.properties || {};
         const requiredProps = schemaObj.required || [];
@@ -248,16 +249,20 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
         const modelImports = [...referencedTypes].filter(Boolean).map((name) => ({
             classname: name,
             classFilename: (0, name_formatter_1.toCamelCase)(name),
-            tagFilename: schemaTagMap[name] || 'shared'
+            tagFilename: schemaTagMap[name] || 'shared',
+            tagFolderPath: baseName
+                ? `${baseName}/${schemaTagMap[name] || 'shared'}`
+                : schemaTagMap[name] || 'shared'
         }));
         const modelViewData = {
             tagFilename,
+            tagFolderPath,
             models: [
                 {
                     model: {
-                        classname: baseName,
-                        classFilename: (0, name_formatter_1.toCamelCase)(baseName),
-                        classVarName: (0, name_formatter_1.toCamelCase)(baseName),
+                        classname: schemaBaseName,
+                        classFilename: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                        classVarName: (0, name_formatter_1.toCamelCase)(schemaBaseName),
                         description: schemaObj.description || '',
                         imports: modelImports,
                         vars: varsMap
@@ -272,10 +277,11 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 apis: [
                     {
                         operations: {
-                            classname: baseName,
-                            classFilename: (0, name_formatter_1.toCamelCase)(baseName),
-                            classVarName: (0, name_formatter_1.toCamelCase)(baseName),
-                            tagFilename
+                            classname: schemaBaseName,
+                            classFilename: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                            classVarName: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                            tagFilename,
+                            tagFolderPath
                         }
                     }
                 ]
@@ -286,7 +292,7 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
         if (fs_extra_1.default.existsSync(modelTemplatePath)) {
             const template = fs_extra_1.default.readFileSync(modelTemplatePath, 'utf8');
             const output = mustache_1.default.render(template, modelViewData);
-            const destPath = path_1.default.join(outputDir, 'entities/models', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.model.ts`);
+            const destPath = path_1.default.join(outputDir, 'entities/models', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.model.ts`);
             fs_extra_1.default.ensureDirSync(path_1.default.dirname(destPath));
             fs_extra_1.default.writeFileSync(destPath, output);
             generatedCount.models++;
@@ -297,7 +303,7 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
         if (fs_extra_1.default.existsSync(mapperTemplatePath)) {
             const template = fs_extra_1.default.readFileSync(mapperTemplatePath, 'utf8');
             const output = mustache_1.default.render(template, mapperViewData);
-            const destPath = path_1.default.join(outputDir, 'data/mappers', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.mapper.ts`);
+            const destPath = path_1.default.join(outputDir, 'data/mappers', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.mapper.ts`);
             fs_extra_1.default.ensureDirSync(path_1.default.dirname(destPath));
             fs_extra_1.default.writeFileSync(destPath, output);
             generatedCount.mappers++;
@@ -315,45 +321,50 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 classname: name,
                 classFilename: (0, name_formatter_1.toCamelCase)(name),
                 tagFilename: targetTag,
+                tagFolderPath: baseName ? `${baseName}/${targetTag}` : targetTag,
                 importPath
             };
         });
         const dtoMockViewData = {
             tagFilename,
+            tagFolderPath,
             models: [
                 {
                     model: {
-                        classname: baseName,
-                        classFilename: (0, name_formatter_1.toCamelCase)(baseName),
-                        classVarName: (0, name_formatter_1.toCamelCase)(baseName),
+                        classname: schemaBaseName,
+                        classFilename: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                        classVarName: (0, name_formatter_1.toCamelCase)(schemaBaseName),
                         mockImports: dtoMockImports,
                         vars: dtoMockVarsMap
                     }
                 }
             ]
         };
-        renderTemplate(templatesDir, 'dto.mock.mustache', dtoMockViewData, path_1.default.join(outputDir, 'data/dtos', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.dto.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'dto.mock.mustache', dtoMockViewData, path_1.default.join(outputDir, 'data/dtos', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.dto.mock.ts`), generatedCount, 'mocks');
         // Model mock — delegates to mapper + DTO mock (no property values needed)
-        renderTemplate(templatesDir, 'model.mock.mustache', modelViewData, path_1.default.join(outputDir, 'entities/models', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.model.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'model.mock.mustache', modelViewData, path_1.default.join(outputDir, 'entities/models', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.model.mock.ts`), generatedCount, 'mocks');
         // Model spec
-        renderTemplate(templatesDir, 'model-entity.spec.mustache', modelViewData, path_1.default.join(outputDir, 'entities/models', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.model.spec.ts`), generatedCount, 'specs');
+        renderTemplate(templatesDir, 'model-entity.spec.mustache', modelViewData, path_1.default.join(outputDir, 'entities/models', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.model.spec.ts`), generatedCount, 'specs');
         // Mapper spec
-        renderTemplate(templatesDir, 'mapper.spec.mustache', mapperViewData, path_1.default.join(outputDir, 'data/mappers', tagFilename, `${(0, name_formatter_1.toCamelCase)(baseName)}.mapper.spec.ts`), generatedCount, 'specs');
+        renderTemplate(templatesDir, 'mapper.spec.mustache', mapperViewData, path_1.default.join(outputDir, 'data/mappers', tagFolderPath, `${(0, name_formatter_1.toCamelCase)(schemaBaseName)}.mapper.spec.ts`), generatedCount, 'specs');
     });
     // 2. Generate Use Cases and Repositories from Paths/Tags
     // Generate per tag
     Object.keys(tagsMap).forEach((tag) => {
         const tagFilename = (0, name_formatter_1.toCamelCase)(tag);
+        const tagFolderPath = baseName ? `${baseName}/${tagFilename}` : tagFilename;
         const returnImports = [];
         const paramImports = [];
         Object.keys(schemas).forEach((s) => {
             const usedAsReturn = tagsMap[tag].some((op) => op.returnType === s || op.returnType === `${s}[]`);
             const usedAsParam = tagsMap[tag].some((op) => op.allParams.some((p) => p.dataType === s || p.dataType === `${s}[]`));
+            const schemaTag = schemaTagMap[s] || 'shared';
             const entry = {
                 classname: s,
                 classFilename: (0, name_formatter_1.toCamelCase)(s),
                 classVarName: (0, name_formatter_1.toCamelCase)(s),
-                tagFilename: schemaTagMap[s] || 'shared'
+                tagFilename: schemaTag,
+                tagFolderPath: baseName ? `${baseName}/${schemaTag}` : schemaTag
             };
             if (usedAsReturn) {
                 returnImports.push(entry);
@@ -371,6 +382,7 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                             classname: (0, name_formatter_1.toPascalCase)(tag),
                             classFilename: tagFilename,
                             classVarName: tagFilename,
+                            tagFolderPath,
                             constantName: tag.toUpperCase().replace(/[^A-Z0-9]/g, '_'),
                             operation: tagsMap[tag],
                             imports: [...returnImports, ...paramImports],
@@ -382,21 +394,21 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 ]
             }
         };
-        renderTemplate(templatesDir, 'api.use-cases.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFilename, `${tagFilename}.use-cases.contract.ts`), generatedCount, 'useCases');
-        renderTemplate(templatesDir, 'api.use-cases.impl.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFilename, `${tagFilename}.use-cases.impl.ts`), generatedCount, 'useCases');
-        renderTemplate(templatesDir, 'api.repository.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/repositories', tagFilename, `${tagFilename}.repository.contract.ts`), generatedCount, 'repositories');
-        renderTemplate(templatesDir, 'api.repository.impl.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFilename, `${tagFilename}.repository.impl.ts`), generatedCount, 'repositories');
-        renderTemplate(templatesDir, 'use-cases.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', tagFilename, `${tagFilename}.use-cases.provider.ts`), generatedCount, 'providers');
-        renderTemplate(templatesDir, 'repository.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', tagFilename, `${tagFilename}.repository.provider.ts`), generatedCount, 'providers');
+        renderTemplate(templatesDir, 'api.use-cases.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFolderPath, `${tagFilename}.use-cases.contract.ts`), generatedCount, 'useCases');
+        renderTemplate(templatesDir, 'api.use-cases.impl.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFolderPath, `${tagFilename}.use-cases.impl.ts`), generatedCount, 'useCases');
+        renderTemplate(templatesDir, 'api.repository.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/repositories', tagFolderPath, `${tagFilename}.repository.contract.ts`), generatedCount, 'repositories');
+        renderTemplate(templatesDir, 'api.repository.impl.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFolderPath, `${tagFilename}.repository.impl.ts`), generatedCount, 'repositories');
+        renderTemplate(templatesDir, 'use-cases.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', tagFolderPath, `${tagFilename}.use-cases.provider.ts`), generatedCount, 'providers');
+        renderTemplate(templatesDir, 'repository.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', tagFolderPath, `${tagFilename}.repository.provider.ts`), generatedCount, 'providers');
         // Mocks
-        renderTemplate(templatesDir, 'api.repository.impl.mock.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFilename, `${tagFilename}.repository.impl.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'api.use-cases.mock.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFilename, `${tagFilename}.use-cases.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'repository.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', tagFilename, `${tagFilename}.repository.provider.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'use-cases.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', tagFilename, `${tagFilename}.use-cases.provider.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'api.repository.impl.mock.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFolderPath, `${tagFilename}.repository.impl.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'api.use-cases.mock.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFolderPath, `${tagFilename}.use-cases.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'repository.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', tagFolderPath, `${tagFilename}.repository.provider.mock.ts`), generatedCount, 'mocks');
+        renderTemplate(templatesDir, 'use-cases.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', tagFolderPath, `${tagFilename}.use-cases.provider.mock.ts`), generatedCount, 'mocks');
         // Repository impl spec
-        renderTemplate(templatesDir, 'api.repository.impl.spec.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFilename, `${tagFilename}.repository.impl.spec.ts`), generatedCount, 'specs');
+        renderTemplate(templatesDir, 'api.repository.impl.spec.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', tagFolderPath, `${tagFilename}.repository.impl.spec.ts`), generatedCount, 'specs');
         // Use-cases impl spec
-        renderTemplate(templatesDir, 'api.use-cases.impl.spec.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFilename, `${tagFilename}.use-cases.impl.spec.ts`), generatedCount, 'specs');
+        renderTemplate(templatesDir, 'api.use-cases.impl.spec.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', tagFolderPath, `${tagFilename}.use-cases.impl.spec.ts`), generatedCount, 'specs');
     });
     (0, logger_1.logSuccess)(`${generatedCount.models} Models, ${generatedCount.repositories} Repos, ${generatedCount.useCases} Use Cases, ${generatedCount.mappers} Mappers, ${generatedCount.providers} Providers, ${generatedCount.mocks} Mocks, ${generatedCount.specs} Specs generated`);
     return generatedCount;

package/dist/src/generators/dto.generator.js

@@ -39,7 +39,7 @@ function generateCode(swaggerFile, templatesDir) {
     }
 }
 /** Copies the generated DTOs from the temporary directory to the output directory, organised by tag subfolder. */
-function organizeFiles(tempDir, outputDir, schemaTagMap = {}) {
+function organizeFiles(tempDir, outputDir, schemaTagMap = {}, baseName = '') {
     (0, logger_1.logStep)('Organising generated DTO files...');
     const sourceDir = path_1.default.join(tempDir, 'model');
     const destDir = path_1.default.join(outputDir, 'data/dtos');
@@ -53,7 +53,9 @@ function organizeFiles(tempDir, outputDir, schemaTagMap = {}) {
             const pascalName = (0, name_formatter_1.toPascalCase)(camelName);
             const tagFolder = schemaTagMap[pascalName] || 'shared';
             const sourcePath = path_1.default.join(sourceDir, file);
-            const destPath = path_1.default.join(destDir, tagFolder, file);
+            const destPath = baseName
+                ? path_1.default.join(destDir, baseName, tagFolder, file)
+                : path_1.default.join(destDir, tagFolder, file);
             fs_extra_1.default.ensureDirSync(path_1.default.dirname(destPath));
             fs_extra_1.default.copySync(sourcePath, destPath);
             filesMoved++;
@@ -63,9 +65,11 @@ function organizeFiles(tempDir, outputDir, schemaTagMap = {}) {
     (0, logger_1.logSuccess)(`${filesMoved} DTOs moved successfully`);
 }
 /** Post-processes the generated DTOs: adds cross-DTO imports and normalises Array<T> → T[]. */
-function addDtoImports(outputDir) {
+function addDtoImports(outputDir, baseName = '') {
     (0, logger_1.logStep)('Post-processing generated DTOs...');
-    const dtosDir = path_1.default.join(outputDir, 'data/dtos');
+    const dtosDir = baseName
+        ? path_1.default.join(outputDir, 'data/dtos', baseName)
+        : path_1.default.join(outputDir, 'data/dtos');
     if (!fs_extra_1.default.existsSync(dtosDir))
         return;
     // Collect all .dto.ts files from all subfolders (1 level deep)

package/dist/src/utils/config.js

@@ -66,6 +66,9 @@ function generateDefaultConfig(analysis, tagSummaries, cliOptions, apiKeys) {
     if (cliOptions.templates) {
         config.templates = cliOptions.templates;
     }
+    if (cliOptions.baseName) {
+        config.baseName = cliOptions.baseName;
+    }
     return config;
 }
 /**

package/dist/src/utils/name-formatter.js

@@ -1,9 +1,15 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.toPascalCase = toPascalCase;
 exports.toCamelCase = toCamelCase;
 exports.isReservedWord = isReservedWord;
 exports.safePropertyName = safePropertyName;
+exports.deriveBaseName = deriveBaseName;
+const path_1 = __importDefault(require("path"));
+const logger_1 = require("./logger");
 /**
  * Converts a string to PascalCase, handling spaces, hyphens and underscores.
  * Used to derive class names from schema/tag names.
@@ -111,3 +117,31 @@ function isReservedWord(name) {
 function safePropertyName(name) {
     return isReservedWord(name) ? `_${name}` : name;
 }
+/**
+ * Derives a baseName from a swagger file path, used as the top-level folder
+ * that groups all generated artefacts for that contract.
+ *
+ * Primary rule: takes the token immediately before `-swagger` (case-insensitive).
+ * Fallback: takes the last token of the basename and emits a warning.
+ *
+ * @example
+ * deriveBaseName('my-app-swagger.yaml')      // 'app'
+ * deriveBaseName('aprovalm-swagger.yaml')    // 'aprovalm'
+ * deriveBaseName('backoffice.yaml')          // 'backoffice'  + warning
+ * deriveBaseName('my-backoffice.yaml')       // 'backoffice'  + warning
+ */
+function deriveBaseName(filepath) {
+    const base = path_1.default.basename(filepath, path_1.default.extname(filepath));
+    const tokens = base.split(/[-_]+/);
+    const swaggerIdx = tokens.findIndex((t) => t.toLowerCase() === 'swagger');
+    let raw;
+    if (swaggerIdx > 0) {
+        raw = tokens[swaggerIdx - 1];
+    }
+    else {
+        raw = tokens[tokens.length - 1];
+        (0, logger_1.logWarning)(`Could not find "-swagger" segment in "${base}". ` +
+            `Using "${raw}" as baseName. Use -k to override.`);
+    }
+    return toCamelCase(raw);
+}

package/dist/templates/api.repository.contract.mustache

@@ -4,7 +4,7 @@
 import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 {{#imports}}
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 {{/imports}}
 
 /**

package/dist/templates/api.repository.impl.mock.mustache

@@ -4,9 +4,9 @@
 import { MockService } from 'ng-mocks';
 import { of } from 'rxjs';
 
-import { {{classname}}RepositoryImpl } from '@/data/repositories/{{classFilename}}/{{classFilename}}.repository.impl';
+import { {{classname}}RepositoryImpl } from '@/data/repositories/{{tagFolderPath}}/{{classFilename}}.repository.impl';
 {{#returnImports}}
-import { mock{{classname}}Model } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model.mock';
+import { mock{{classname}}Model } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model.mock';
 {{/returnImports}}
 
 export const mock{{classname}}RepositoryImpl = () =>

package/dist/templates/api.repository.impl.mustache

@@ -9,14 +9,14 @@ import { environment } from '@environment';
 
 import { MRepository } from '@mercadona/core/utils/repository';
 
-import { {{classname}}Repository } from '@/domain/repositories/{{classFilename}}/{{classFilename}}.repository.contract';
+import { {{classname}}Repository } from '@/domain/repositories/{{tagFolderPath}}/{{classFilename}}.repository.contract';
 {{#returnImports}}
-import { {{classname}}Dto } from '@/dtos/{{tagFilename}}/{{classFilename}}.dto';
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
-import { {{classVarName}}Mapper } from '@/mappers/{{tagFilename}}/{{classFilename}}.mapper';
+import { {{classname}}Dto } from '@/dtos/{{tagFolderPath}}/{{classFilename}}.dto';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
+import { {{classVarName}}Mapper } from '@/mappers/{{tagFolderPath}}/{{classFilename}}.mapper';
 {{/returnImports}}
 {{#paramImports}}
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 {{/paramImports}}
 
 /**

package/dist/templates/api.repository.impl.spec.mustache

@@ -6,8 +6,8 @@ import { TestBed } from '@angular/core/testing';
 
 import { {{classname}}RepositoryImpl } from './{{classFilename}}.repository.impl';
 {{#returnImports}}
-import { mock{{classname}}Dto } from '@/dtos/{{tagFilename}}/{{classFilename}}.dto.mock';
-import { mock{{classname}}Model } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model.mock';
+import { mock{{classname}}Dto } from '@/dtos/{{tagFolderPath}}/{{classFilename}}.dto.mock';
+import { mock{{classname}}Model } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model.mock';
 {{/returnImports}}
 
 describe('{{classname}}RepositoryImpl', () => {

package/dist/templates/api.use-cases.contract.mustache

@@ -4,7 +4,7 @@
 import { InjectionToken } from '@angular/core';
 import { Observable } from 'rxjs';
 {{#imports}}
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 {{/imports}}
 
 /**

package/dist/templates/api.use-cases.impl.mustache

@@ -6,9 +6,9 @@ import { Observable } from 'rxjs';
 
 import { {{classname}}UseCases } from './{{classFilename}}.use-cases.contract';
 
-import { {{constantName}}_REPOSITORY, {{classname}}Repository } from '@/domain/repositories/{{classFilename}}/{{classFilename}}.repository.contract';
+import { {{constantName}}_REPOSITORY, {{classname}}Repository } from '@/domain/repositories/{{tagFolderPath}}/{{classFilename}}.repository.contract';
 {{#imports}}
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 {{/imports}}
 
 /**

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

@@ -6,9 +6,9 @@ import { of } from 'rxjs';
 
 import { {{classname}}UseCasesImpl } from './{{classFilename}}.use-cases.impl';
 
-import { {{constantName}}_REPOSITORY, {{classname}}Repository } from '@/domain/repositories/{{classFilename}}/{{classFilename}}.repository.contract';
+import { {{constantName}}_REPOSITORY, {{classname}}Repository } from '@/domain/repositories/{{tagFolderPath}}/{{classFilename}}.repository.contract';
 {{#returnImports}}
-import { mock{{classname}}Model } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model.mock';
+import { mock{{classname}}Model } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model.mock';
 {{/returnImports}}
 
 describe('{{classname}}UseCasesImpl', () => {

package/dist/templates/api.use-cases.mock.mustache

@@ -4,9 +4,9 @@
 import { MockService } from 'ng-mocks';
 import { of } from 'rxjs';
 
-import { {{classname}}UseCasesImpl } from '@/domain/use-cases/{{classFilename}}/{{classFilename}}.use-cases.impl';
+import { {{classname}}UseCasesImpl } from '@/domain/use-cases/{{tagFolderPath}}/{{classFilename}}.use-cases.impl';
 {{#returnImports}}
-import { mock{{classname}}Model } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model.mock';
+import { mock{{classname}}Model } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model.mock';
 {{/returnImports}}
 
 export const mock{{classname}}UseCasesImpl = () =>

package/dist/templates/mapper.mustache

@@ -4,8 +4,8 @@
 import { MapFromFn } from '@mercadona/common/public';
 import { Builder } from '@mercadona/common/utils';
 
-import { {{classname}}Dto } from '@/dtos/{{tagFilename}}/{{classFilename}}.dto';
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}}Dto } from '@/dtos/{{tagFolderPath}}/{{classFilename}}.dto';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 
 /**
  * {{classname}} Mapper

package/dist/templates/mapper.spec.mustache

@@ -2,8 +2,8 @@
 {{#model}}
 import { {{classVarName}}Mapper } from './{{classFilename}}.mapper';
 
-import { mock{{classname}}Dto } from '@/dtos/{{tagFilename}}/{{classFilename}}.dto.mock';
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { mock{{classname}}Dto } from '@/dtos/{{tagFolderPath}}/{{classFilename}}.dto.mock';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 
 describe('{{classVarName}}Mapper', () => {
 {{#vars}}

package/dist/templates/model-entity.mustache

@@ -1,7 +1,7 @@
 {{#models}}
 {{#model}}
 {{#imports}}
-import { {{classname}} } from '@/entities/models/{{tagFilename}}/{{classFilename}}.model';
+import { {{classname}} } from '@/entities/models/{{tagFolderPath}}/{{classFilename}}.model';
 {{/imports}}
 
 /**

package/dist/templates/model.mock.mustache

@@ -1,8 +1,8 @@
 {{#models}}
 {{#model}}
 import { {{classname}} } from './{{classFilename}}.model';
-import { {{classVarName}}Mapper } from '@/mappers/{{tagFilename}}/{{classFilename}}.mapper';
-import { mock{{classname}}Dto } from '@/dtos/{{tagFilename}}/{{classFilename}}.dto.mock';
+import { {{classVarName}}Mapper } from '@/mappers/{{tagFolderPath}}/{{classFilename}}.mapper';
+import { mock{{classname}}Dto } from '@/dtos/{{tagFolderPath}}/{{classFilename}}.dto.mock';
 
 export const mock{{classname}}Model = (overrides: Partial<{{classname}}> = {}): {{classname}} =>
   Object.assign(new {{classname}}(), {

package/dist/templates/repository.provider.mock.mustache

@@ -3,8 +3,8 @@
 {{#operations}}
 import { Provider } from '@angular/core';
 
-import { {{constantName}}_REPOSITORY } from '@/domain/repositories/{{classFilename}}/{{classFilename}}.repository.contract';
-import { mock{{classname}}RepositoryImpl } from '@/data/repositories/{{classFilename}}/{{classFilename}}.repository.impl.mock';
+import { {{constantName}}_REPOSITORY } from '@/domain/repositories/{{tagFolderPath}}/{{classFilename}}.repository.contract';
+import { mock{{classname}}RepositoryImpl } from '@/data/repositories/{{tagFolderPath}}/{{classFilename}}.repository.impl.mock';
 
 export function mock{{classname}}Repository(): Provider[] {
   return [

package/dist/templates/repository.provider.mustache

@@ -3,8 +3,8 @@
 {{#operations}}
 import { EnvironmentProviders, makeEnvironmentProviders } from '@angular/core';
 
-import { {{constantName}}_REPOSITORY } from '@/domain/repositories/{{classFilename}}/{{classFilename}}.repository.contract';
-import { {{classname}}RepositoryImpl } from '@/data/repositories/{{classFilename}}/{{classFilename}}.repository.impl';
+import { {{constantName}}_REPOSITORY } from '@/domain/repositories/{{tagFolderPath}}/{{classFilename}}.repository.contract';
+import { {{classname}}RepositoryImpl } from '@/data/repositories/{{tagFolderPath}}/{{classFilename}}.repository.impl';
 
 /**
  * {{classname}} Repository Provider

package/dist/templates/use-cases.provider.mock.mustache

@@ -3,8 +3,8 @@
 {{#operations}}
 import { Provider } from '@angular/core';
 
-import { {{constantName}}_USE_CASES } from '@/domain/use-cases/{{classFilename}}/{{classFilename}}.use-cases.contract';
-import { mock{{classname}}UseCasesImpl } from '@/domain/use-cases/{{classFilename}}/{{classFilename}}.use-cases.mock';
+import { {{constantName}}_USE_CASES } from '@/domain/use-cases/{{tagFolderPath}}/{{classFilename}}.use-cases.contract';
+import { mock{{classname}}UseCasesImpl } from '@/domain/use-cases/{{tagFolderPath}}/{{classFilename}}.use-cases.mock';
 
 export function mock{{classname}}UseCases(): Provider[] {
   return [

package/dist/templates/use-cases.provider.mustache

@@ -3,8 +3,8 @@
 {{#operations}}
 import { EnvironmentProviders, makeEnvironmentProviders } from '@angular/core';
 
-import { {{constantName}}_USE_CASES } from '@/domain/use-cases/{{classFilename}}/{{classFilename}}.use-cases.contract';
-import { {{classname}}UseCasesImpl } from '@/domain/use-cases/{{classFilename}}/{{classFilename}}.use-cases.impl';
+import { {{constantName}}_USE_CASES } from '@/domain/use-cases/{{tagFolderPath}}/{{classFilename}}.use-cases.contract';
+import { {{classname}}UseCasesImpl } from '@/domain/use-cases/{{tagFolderPath}}/{{classFilename}}.use-cases.impl';
 
 /**
  * {{classname}} Use Cases Provider

package/package.json

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