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

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

@@ -5,6 +5,8 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.extractTagsFromAnalysis = extractTagsFromAnalysis;
 exports.extractTagsWithOperations = extractTagsWithOperations;
+exports.buildTagsMapFromAnalysis = buildTagsMapFromAnalysis;
+exports.buildSchemaTagMap = buildSchemaTagMap;
 exports.generateCleanArchitecture = generateCleanArchitecture;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
@@ -57,8 +59,139 @@ function extractTagsWithOperations(analysis) {
     });
     return [...map.values()];
 }
+/**
+ * Builds and returns the tagsMap from the swagger analysis, applying the optional selection filter.
+ * Exported so callers (e.g. main.ts) can compute it before organizeFiles runs.
+ */
+function buildTagsMapFromAnalysis(analysis, selectionFilter = {}) {
+    const tagsMap = {};
+    Object.keys(analysis.paths).forEach((pathKey) => {
+        const pathObj = analysis.paths[pathKey];
+        Object.keys(pathObj).forEach((method) => {
+            const op = pathObj[method];
+            if (op.tags && op.tags.length > 0) {
+                const tag = op.tags[0];
+                if (!tagsMap[tag])
+                    tagsMap[tag] = [];
+                const allParams = (op.parameters || []).map((p) => ({
+                    paramName: p.name,
+                    dataType: (0, type_mapper_1.mapSwaggerTypeToTs)(p.schema?.type || ''),
+                    description: p.description || '',
+                    required: p.required,
+                    testValue: resolveTestParamValue((0, type_mapper_1.mapSwaggerTypeToTs)(p.schema?.type || ''))
+                }));
+                if (op.requestBody) {
+                    let bodyType = 'unknown';
+                    const content = op.requestBody.content?.['application/json']?.schema;
+                    if (content) {
+                        if (content.$ref)
+                            bodyType = content.$ref.split('/').pop() || 'unknown';
+                        else if (content.type)
+                            bodyType = (0, type_mapper_1.mapSwaggerTypeToTs)(content.type);
+                    }
+                    allParams.push({
+                        paramName: 'body',
+                        dataType: bodyType,
+                        description: op.requestBody.description || '',
+                        required: true,
+                        testValue: resolveTestParamValue(bodyType)
+                    });
+                }
+                let returnType = 'void';
+                let returnBaseType = 'void';
+                let isListContainer = false;
+                const successCode = ['200', '201', '202', '203'].find((code) => op.responses?.[code]);
+                const responseSchema = successCode !== undefined
+                    ? op.responses?.[successCode]?.content?.['application/json']?.schema
+                    : undefined;
+                if (responseSchema) {
+                    if (responseSchema.$ref) {
+                        returnType = responseSchema.$ref.split('/').pop() || 'unknown';
+                        returnBaseType = returnType;
+                    }
+                    else if (responseSchema.type === 'array' && responseSchema.items?.$ref) {
+                        returnBaseType = responseSchema.items.$ref.split('/').pop() || 'unknown';
+                        returnType = `${returnBaseType}[]`;
+                        isListContainer = true;
+                    }
+                }
+                const hasQueryParams = (op.parameters || []).some((p) => p.in === 'query');
+                const hasBodyParam = !!op.requestBody;
+                // Sort: required params first, optional params last (TypeScript requirement)
+                allParams.sort((a, b) => {
+                    if (a.required === b.required)
+                        return 0;
+                    return a.required ? -1 : 1;
+                });
+                tagsMap[tag].push({
+                    nickname: op.operationId || `${method}${pathKey.replace(/\//g, '_')}`,
+                    summary: op.summary || '',
+                    notes: op.description || '',
+                    httpMethod: method.toLowerCase(),
+                    uppercaseHttpMethod: method.toUpperCase(),
+                    path: pathKey,
+                    allParams: allParams.map((p, i) => ({
+                        ...p,
+                        '-last': i === allParams.length - 1
+                    })),
+                    hasQueryParams,
+                    queryParams: (op.parameters || [])
+                        .filter((p) => p.in === 'query')
+                        .map((p, i, arr) => ({
+                        paramName: p.name,
+                        '-last': i === arr.length - 1
+                    })),
+                    hasBodyParam,
+                    bodyParam: 'body',
+                    hasOptions: hasQueryParams || hasBodyParam,
+                    hasBothParamsAndBody: hasQueryParams && hasBodyParam,
+                    returnType: returnType !== 'void' ? returnType : false,
+                    returnBaseType: returnBaseType !== 'void' ? returnBaseType : false,
+                    returnTypeVarName: returnType !== 'void' ? (0, name_formatter_1.toCamelCase)(returnType) : false,
+                    returnBaseTypeVarName: returnBaseType !== 'void' ? (0, name_formatter_1.toCamelCase)(returnBaseType) : false,
+                    isListContainer: isListContainer,
+                    vendorExtensions: {}
+                });
+            }
+        });
+    });
+    if (Object.keys(selectionFilter).length > 0) {
+        Object.keys(tagsMap).forEach((tag) => {
+            if (!selectionFilter[tag]) {
+                delete tagsMap[tag];
+            }
+            else {
+                tagsMap[tag] = tagsMap[tag].filter((op) => selectionFilter[tag].includes(op.nickname));
+                if (tagsMap[tag].length === 0)
+                    delete tagsMap[tag];
+            }
+        });
+    }
+    return tagsMap;
+}
+/**
+ * Maps each schema basename to the tag subfolder it belongs to.
+ * Schemas used by exactly one tag → that tag's camelCase name.
+ * Schemas used by 0 or multiple tags → 'shared'.
+ */
+function buildSchemaTagMap(schemas, tagsMap) {
+    const result = {};
+    Object.keys(schemas).forEach((schemaName) => {
+        const baseName = schemaName.replace(/Dto$/, '');
+        const tagsUsing = [];
+        Object.keys(tagsMap).forEach((tag) => {
+            const used = tagsMap[tag].some((op) => op.returnType === baseName ||
+                op.returnType === `${baseName}[]` ||
+                op.allParams.some((p) => p.dataType === baseName || p.dataType === `${baseName}[]`));
+            if (used)
+                tagsUsing.push(tag);
+        });
+        result[baseName] = tagsUsing.length === 1 ? (0, name_formatter_1.toCamelCase)(tagsUsing[0]) : 'shared';
+    });
+    return result;
+}
 /** Generates all Clean Architecture artefacts (models, mappers, repos, use cases, providers) using Mustache. */
-function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyMap = {}, selectionFilter = {}) {
+function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyMap = {}, selectionFilter = {}, precomputedSchemaTagMap = {}, baseName = '') {
     (0, logger_1.logStep)('Generating Clean Architecture artefacts using Mustache...');
     const generatedCount = {
         models: 0,
@@ -71,14 +204,23 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
     };
     const schemas = analysis.swagger.components
         ?.schemas || {};
+    // Build tagsMap first — needed to compute schemaTagMap before the schema loop
+    const tagsMap = buildTagsMapFromAnalysis(analysis, selectionFilter);
+    // Map each schema basename → tag subfolder ('shared' if used by 0 or >1 tags)
+    const schemaTagMap = Object.keys(precomputedSchemaTagMap).length > 0
+        ? precomputedSchemaTagMap
+        : buildSchemaTagMap(schemas, tagsMap);
     // 1. Generate Models, Entities and Mappers from Schemas
     Object.keys(schemas).forEach((schemaName) => {
-        const baseName = schemaName.replace(/Dto$/, '');
+        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 || [];
         const varsMap = Object.keys(rawProperties).map((k) => {
             let tsType = (0, type_mapper_1.mapSwaggerTypeToTs)(rawProperties[k].type);
+            const isInlineObject = rawProperties[k].type === 'object' && !rawProperties[k].$ref;
             if (rawProperties[k].$ref) {
                 tsType = rawProperties[k].$ref.split('/').pop() || 'unknown';
             }
@@ -86,10 +228,12 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 tsType = `${rawProperties[k].items.$ref.split('/').pop()}[]`;
             }
             return {
-                name: k,
+                name: (0, name_formatter_1.safePropertyName)(k),
+                originalName: k,
                 dataType: tsType,
                 description: rawProperties[k].description || '',
-                required: requiredProps.includes(k)
+                required: requiredProps.includes(k),
+                hasMockValue: !isInlineObject
             };
         });
         // Collect imports for types referenced via $ref in properties
@@ -102,16 +246,23 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 referencedTypes.add(prop.items.$ref.split('/').pop() || '');
             }
         });
-        const modelImports = [...referencedTypes]
-            .filter(Boolean)
-            .map((name) => ({ classname: name, classFilename: (0, name_formatter_1.toCamelCase)(name) }));
+        const modelImports = [...referencedTypes].filter(Boolean).map((name) => ({
+            classname: name,
+            classFilename: (0, name_formatter_1.toCamelCase)(name),
+            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
@@ -126,9 +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)
+                            classname: schemaBaseName,
+                            classFilename: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                            classVarName: (0, name_formatter_1.toCamelCase)(schemaBaseName),
+                            tagFilename,
+                            tagFolderPath
                         }
                     }
                 ]
@@ -139,7 +292,8 @@ 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', `${(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++;
             (0, logger_1.logDetail)('generate', `model-entity → ${path_1.default.relative(process.cwd(), destPath)}`);
@@ -149,145 +303,69 @@ 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', `${(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++;
         }
         // DTO mock — values resolved from raw schema (example, format, type)
         const dtoMockVarsMap = Object.keys(rawProperties).map((k) => ({
-            name: k,
-            mockValue: (0, mock_value_resolver_1.resolveMockValue)(k, rawProperties[k], 'dto')
+            name: (0, name_formatter_1.safePropertyName)(k),
+            mockValue: (0, mock_value_resolver_1.resolveMockValue)(k, rawProperties[k], 'dto', schemaName)
         }));
-        const dtoMockImports = [...referencedTypes]
-            .filter(Boolean)
-            .map((name) => ({ classname: name, classFilename: (0, name_formatter_1.toCamelCase)(name) }));
+        const dtoMockImports = [...referencedTypes].filter(Boolean).map((name) => {
+            const targetTag = schemaTagMap[name] || 'shared';
+            const targetFile = `${(0, name_formatter_1.toCamelCase)(name)}.dto.mock`;
+            const importPath = targetTag === tagFilename ? `./${targetFile}` : `../${targetTag}/${targetFile}`;
+            return {
+                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', `${(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', `${(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', `${(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', `${(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
-    const tagsMap = {};
-    Object.keys(analysis.paths).forEach((pathKey) => {
-        const pathObj = analysis.paths[pathKey];
-        Object.keys(pathObj).forEach((method) => {
-            const op = pathObj[method];
-            if (op.tags && op.tags.length > 0) {
-                const tag = op.tags[0];
-                if (!tagsMap[tag])
-                    tagsMap[tag] = [];
-                const allParams = (op.parameters || []).map((p) => ({
-                    paramName: p.name,
-                    dataType: (0, type_mapper_1.mapSwaggerTypeToTs)(p.schema?.type || ''),
-                    description: p.description || '',
-                    required: p.required,
-                    testValue: resolveTestParamValue((0, type_mapper_1.mapSwaggerTypeToTs)(p.schema?.type || ''))
-                }));
-                if (op.requestBody) {
-                    let bodyType = 'unknown';
-                    const content = op.requestBody.content?.['application/json']?.schema;
-                    if (content) {
-                        if (content.$ref)
-                            bodyType = content.$ref.split('/').pop() || 'unknown';
-                        else if (content.type)
-                            bodyType = (0, type_mapper_1.mapSwaggerTypeToTs)(content.type);
-                    }
-                    allParams.push({
-                        paramName: 'body',
-                        dataType: bodyType,
-                        description: op.requestBody.description || '',
-                        required: true,
-                        testValue: resolveTestParamValue(bodyType)
-                    });
-                }
-                let returnType = 'void';
-                let returnBaseType = 'void';
-                let isListContainer = false;
-                const successCode = ['200', '201', '202', '203'].find((code) => op.responses?.[code]);
-                const responseSchema = successCode !== undefined
-                    ? op.responses?.[successCode]?.content?.['application/json']?.schema
-                    : undefined;
-                if (responseSchema) {
-                    if (responseSchema.$ref) {
-                        returnType = responseSchema.$ref.split('/').pop() || 'unknown';
-                        returnBaseType = returnType;
-                    }
-                    else if (responseSchema.type === 'array' && responseSchema.items?.$ref) {
-                        returnBaseType = responseSchema.items.$ref.split('/').pop() || 'unknown';
-                        returnType = `${returnBaseType}[]`;
-                        isListContainer = true;
-                    }
-                }
-                const hasQueryParams = (op.parameters || []).some((p) => p.in === 'query');
-                const hasBodyParam = !!op.requestBody;
-                tagsMap[tag].push({
-                    nickname: op.operationId || `${method}${pathKey.replace(/\//g, '_')}`,
-                    summary: op.summary || '',
-                    notes: op.description || '',
-                    httpMethod: method.toLowerCase(),
-                    uppercaseHttpMethod: method.toUpperCase(),
-                    path: pathKey,
-                    allParams: allParams.map((p, i) => ({
-                        ...p,
-                        '-last': i === allParams.length - 1
-                    })),
-                    hasQueryParams,
-                    queryParams: (op.parameters || [])
-                        .filter((p) => p.in === 'query')
-                        .map((p, i, arr) => ({
-                        paramName: p.name,
-                        '-last': i === arr.length - 1
-                    })),
-                    hasBodyParam,
-                    bodyParam: 'body',
-                    hasOptions: hasQueryParams || hasBodyParam,
-                    hasBothParamsAndBody: hasQueryParams && hasBodyParam,
-                    returnType: returnType !== 'void' ? returnType : false,
-                    returnBaseType: returnBaseType !== 'void' ? returnBaseType : false,
-                    returnTypeVarName: returnType !== 'void' ? (0, name_formatter_1.toCamelCase)(returnType) : false,
-                    returnBaseTypeVarName: returnBaseType !== 'void' ? (0, name_formatter_1.toCamelCase)(returnBaseType) : false,
-                    isListContainer: isListContainer,
-                    vendorExtensions: {}
-                });
-            }
-        });
-    });
-    if (Object.keys(selectionFilter).length > 0) {
-        Object.keys(tagsMap).forEach((tag) => {
-            if (!selectionFilter[tag]) {
-                delete tagsMap[tag];
-            }
-            else {
-                tagsMap[tag] = tagsMap[tag].filter((op) => selectionFilter[tag].includes(op.nickname));
-                if (tagsMap[tag].length === 0)
-                    delete tagsMap[tag];
-            }
-        });
-    }
     // 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 entry = { classname: s, classFilename: (0, name_formatter_1.toCamelCase)(s), classVarName: (0, name_formatter_1.toCamelCase)(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: schemaTag,
+                tagFolderPath: baseName ? `${baseName}/${schemaTag}` : schemaTag
+            };
             if (usedAsReturn) {
                 returnImports.push(entry);
             }
@@ -301,39 +379,36 @@ function generateCleanArchitecture(analysis, outputDir, templatesDir, tagApiKeyM
                 apis: [
                     {
                         operations: {
-                            classname: tag,
-                            classFilename: (0, name_formatter_1.toCamelCase)(tag),
-                            classVarName: (0, name_formatter_1.toCamelCase)(tag),
+                            classname: (0, name_formatter_1.toPascalCase)(tag),
+                            classFilename: tagFilename,
+                            classVarName: tagFilename,
+                            tagFolderPath,
                             constantName: tag.toUpperCase().replace(/[^A-Z0-9]/g, '_'),
                             operation: tagsMap[tag],
-                            // All entity imports (return + param) — for contracts and use-cases
                             imports: [...returnImports, ...paramImports],
-                            // Return-type-only imports — for repo impl (Dto + Entity + Mapper)
                             returnImports,
-                            // Param-only imports — for repo impl (Entity only, no Dto/Mapper)
                             paramImports,
-                            // Environment API key for the repository base URL (e.g. "aprovalmApi")
                             environmentApiKey: tagApiKeyMap[tag] || 'apiUrl'
                         }
                     }
                 ]
             }
         };
-        renderTemplate(templatesDir, 'api.use-cases.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', `${(0, name_formatter_1.toCamelCase)(tag)}.use-cases.contract.ts`), generatedCount, 'useCases');
-        renderTemplate(templatesDir, 'api.use-cases.impl.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', `${(0, name_formatter_1.toCamelCase)(tag)}.use-cases.impl.ts`), generatedCount, 'useCases');
-        renderTemplate(templatesDir, 'api.repository.contract.mustache', apiViewData, path_1.default.join(outputDir, 'domain/repositories', `${(0, name_formatter_1.toCamelCase)(tag)}.repository.contract.ts`), generatedCount, 'repositories');
-        renderTemplate(templatesDir, 'api.repository.impl.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', `${(0, name_formatter_1.toCamelCase)(tag)}.repository.impl.ts`), generatedCount, 'repositories');
-        renderTemplate(templatesDir, 'use-cases.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', `${(0, name_formatter_1.toCamelCase)(tag)}.use-cases.provider.ts`), generatedCount, 'providers');
-        renderTemplate(templatesDir, 'repository.provider.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', `${(0, name_formatter_1.toCamelCase)(tag)}.repository.provider.ts`), generatedCount, 'providers');
-        // Mocks — repository impl, use-cases impl, repository provider, use-cases provider
-        renderTemplate(templatesDir, 'api.repository.impl.mock.mustache', apiViewData, path_1.default.join(outputDir, 'data/repositories', `${(0, name_formatter_1.toCamelCase)(tag)}.repository.impl.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'api.use-cases.mock.mustache', apiViewData, path_1.default.join(outputDir, 'domain/use-cases', `${(0, name_formatter_1.toCamelCase)(tag)}.use-cases.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'repository.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/repositories', `${(0, name_formatter_1.toCamelCase)(tag)}.repository.provider.mock.ts`), generatedCount, 'mocks');
-        renderTemplate(templatesDir, 'use-cases.provider.mock.mustache', apiViewData, path_1.default.join(outputDir, 'di/use-cases', `${(0, name_formatter_1.toCamelCase)(tag)}.use-cases.provider.mock.ts`), generatedCount, 'mocks');
+        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', 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', `${(0, name_formatter_1.toCamelCase)(tag)}.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', `${(0, name_formatter_1.toCamelCase)(tag)}.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;
@@ -344,6 +419,7 @@ function renderTemplate(templatesDir, templateName, viewData, destPath, counter,
     if (fs_extra_1.default.existsSync(templatePath)) {
         const template = fs_extra_1.default.readFileSync(templatePath, 'utf8');
         const output = mustache_1.default.render(template, viewData);
+        fs_extra_1.default.ensureDirSync(path_1.default.dirname(destPath));
         fs_extra_1.default.writeFileSync(destPath, output);
         counter[key]++;
         (0, logger_1.logDetail)('generate', `${templateName.replace('.mustache', '')} → ${path_1.default.relative(process.cwd(), destPath)}`);

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

@@ -10,6 +10,7 @@ const child_process_1 = require("child_process");
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
+const name_formatter_1 = require("../utils/name-formatter");
 /** Invokes `openapi-generator-cli` to generate DTOs into a temporary directory. */
 function generateCode(swaggerFile, templatesDir) {
     (0, logger_1.logStep)('Generating code from OpenAPI spec...');
@@ -37,8 +38,8 @@ function generateCode(swaggerFile, templatesDir) {
         process.exit(1);
     }
 }
-/** Copies the generated DTOs from the temporary directory to the output directory. */
-function organizeFiles(tempDir, outputDir) {
+/** Copies the generated DTOs from the temporary directory to the output directory, organised by tag subfolder. */
+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');
@@ -47,8 +48,15 @@ function organizeFiles(tempDir, outputDir) {
         fs_extra_1.default.ensureDirSync(destDir);
         const files = fs_extra_1.default.readdirSync(sourceDir).filter((file) => file.endsWith('.dto.ts'));
         files.forEach((file) => {
+            // file is like "userResponse.dto.ts" → derive PascalCase schema name to look up tag
+            const camelName = file.replace('.dto.ts', '');
+            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, 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++;
             (0, logger_1.logDetail)('dto', `${file} → ${path_1.default.relative(process.cwd(), destPath)}`);
@@ -57,51 +65,67 @@ function organizeFiles(tempDir, outputDir) {
     (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;
-    const files = fs_extra_1.default.readdirSync(dtosDir).filter((f) => f.endsWith('.dto.ts'));
-    // Build a map of DTO classname → file base name (without .ts)
+    // Collect all .dto.ts files from all subfolders (1 level deep)
+    const allFiles = [];
+    const entries = fs_extra_1.default.readdirSync(dtosDir);
+    entries.forEach((entry) => {
+        const entryPath = path_1.default.join(dtosDir, entry);
+        if (fs_extra_1.default.statSync(entryPath).isDirectory()) {
+            fs_extra_1.default.readdirSync(entryPath)
+                .filter((f) => f.endsWith('.dto.ts'))
+                .forEach((file) => allFiles.push({ subfolder: entry, file, fullPath: path_1.default.join(entryPath, file) }));
+        }
+        else if (entry.endsWith('.dto.ts')) {
+            allFiles.push({ subfolder: '', file: entry, fullPath: entryPath });
+        }
+    });
+    // Build map: ClassName → { subfolder, fileBase }
     const dtoMap = {};
-    files.forEach((file) => {
-        const content = fs_extra_1.default.readFileSync(path_1.default.join(dtosDir, file), 'utf8');
+    allFiles.forEach(({ subfolder, file, fullPath }) => {
+        const content = fs_extra_1.default.readFileSync(fullPath, 'utf8');
         const match = content.match(/export interface (\w+)/);
-        if (match) {
-            dtoMap[match[1]] = file.replace('.ts', '');
-        }
+        if (match)
+            dtoMap[match[1]] = { subfolder, fileBase: file.replace('.ts', '') };
     });
     let filesProcessed = 0;
-    files.forEach((file) => {
-        const filePath = path_1.default.join(dtosDir, file);
-        const originalContent = fs_extra_1.default.readFileSync(filePath, 'utf8');
+    allFiles.forEach(({ subfolder, file, fullPath }) => {
+        const originalContent = fs_extra_1.default.readFileSync(fullPath, '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();
         const typeRegex = /\b(\w+Dto)\b/g;
         let match;
         while ((match = typeRegex.exec(content)) !== null) {
-            if (match[1] !== selfName) {
+            if (match[1] !== selfName)
                 references.add(match[1]);
-            }
         }
-        // Build import lines for each referenced type that exists in the dtoMap
         const imports = [];
         references.forEach((ref) => {
             if (dtoMap[ref]) {
-                imports.push(`import { ${ref} } from './${dtoMap[ref]}';`);
+                const { subfolder: refSubfolder, fileBase: refFileBase } = dtoMap[ref];
+                const fromDir = subfolder ? path_1.default.join(dtosDir, subfolder) : dtosDir;
+                const toFile = refSubfolder
+                    ? path_1.default.join(dtosDir, refSubfolder, refFileBase)
+                    : path_1.default.join(dtosDir, refFileBase);
+                let relPath = path_1.default.relative(fromDir, toFile).replace(/\\/g, '/');
+                if (!relPath.startsWith('.'))
+                    relPath = './' + relPath;
+                imports.push(`import { ${ref} } from '${relPath}';`);
             }
         });
-        if (imports.length > 0) {
+        if (imports.length > 0)
             content = imports.join('\n') + '\n' + content;
-        }
         if (content !== originalContent) {
-            fs_extra_1.default.writeFileSync(filePath, content);
+            fs_extra_1.default.writeFileSync(fullPath, content);
             filesProcessed++;
             (0, logger_1.logDetail)('dto', `Post-processed ${file} (added ${imports.length} import(s))`);
         }

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

@@ -7,6 +7,7 @@ exports.generateReport = generateReport;
 const fs_extra_1 = __importDefault(require("fs-extra"));
 const path_1 = __importDefault(require("path"));
 const logger_1 = require("../utils/logger");
+const example_validator_1 = require("../utils/example-validator");
 /** Counts files ending with `.mock.ts` in a directory (returns 0 if directory does not exist). */
 function countMockFiles(dir) {
     try {
@@ -37,6 +38,7 @@ function generateReport(outputDir, analysis, lintResult) {
         })).length;
         return { name: t.name, description: t.description || '', endpoints: endpointCount };
     });
+    const exampleMismatches = (0, example_validator_1.getExampleMismatches)();
     const report = {
         timestamp: new Date().toISOString(),
         tags: analysis.tags.length,
@@ -44,6 +46,10 @@ function generateReport(outputDir, analysis, lintResult) {
         tagDetails,
         outputDirectory: outputDir,
         linting: lintResult,
+        warnings: {
+            exampleMismatches: exampleMismatches.map((m) => ({ ...m })),
+            total: exampleMismatches.length
+        },
         structure: {
             dtos: fs_extra_1.default.readdirSync(path_1.default.join(outputDir, 'data/dtos')).length,
             repositories: fs_extra_1.default.readdirSync(path_1.default.join(outputDir, 'data/repositories')).length,