@devtrack-solution/codesdd 1.2.2 → 1.2.3

package/dist/core/sdd/devtrack-api-architecture.js

@@ -0,0 +1,608 @@
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+import ts from 'typescript';
+import { parseQualityArchitectureSchema, } from './quality-validation.js';
+export const DEVTRACK_API_ARCHITECTURE_SCHEMA_ID = 'ARCH-GATE-devtrack-api-p0';
+const DEFAULT_SOURCE_ROOTS = ['src', 'prisma'];
+const TYPESCRIPT_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts'];
+const IGNORED_DIRECTORIES = new Set(['.git', 'node_modules', 'dist', 'build', 'coverage', '.turbo']);
+const LEGACY_ENTITY_PATTERN_CONTEXTS = new Set(['pessoas', 'wallets']);
+const PRESENTATION_TRANSPORTS = new Set(['rest', 'graphql', 'cli', 'websocket', 'agent']);
+const DEVTRACK_ALIAS_PREFIXES = [
+    '@domain/',
+    '@application/',
+    '@presentation/',
+    '@infrastructure/',
+    '@infrastructure/adapter/',
+    '@shared/',
+    '@src/',
+];
+export function buildDevTrackApiArchitectureSchema() {
+    return parseQualityArchitectureSchema({
+        schema_version: 1,
+        id: DEVTRACK_API_ARCHITECTURE_SCHEMA_ID,
+        title: 'DevTrack API P0 architecture warning gate',
+        stack: 'typescript-nestjs-typeorm',
+        authority: [
+            {
+                type: 'skill',
+                ref: 'devtrack-api',
+                path: '.sdd/skills/curated/devtrack-api/SKILL.md',
+                update_policy: 'Review when the devtrack-api skill changes.',
+            },
+            {
+                type: 'foundation',
+                ref: 'devtrack-foundation-api',
+                path: '.sdd/skills/curated/devtrack-api/references/foundation-layout.md',
+                update_policy: 'Review when the Foundation layout reference changes.',
+            },
+        ],
+        applies_to: {
+            plugin: 'codesdd-plugin-devtrack-api',
+            project_kind: 'backend-api',
+        },
+        layers: {
+            domain: {
+                path_patterns: ['src/domain/**'],
+                forbidden_file_patterns: ['**/*.orm-entity.ts', '**/*.entity.ts', '**/*.value-object.ts'],
+                forbidden_imports: ['@application/**', '@presentation/**', '@infrastructure/**', '@nestjs/**', 'typeorm', 'class-validator'],
+                required_evidence: ['import_graph'],
+            },
+            application: {
+                path_patterns: ['src/application/**'],
+                forbidden_imports: ['@presentation/**', '@infrastructure/adapters/**', '@src/infrastructure/adapters/**'],
+                required_evidence: ['import_graph'],
+            },
+            presentation: {
+                path_patterns: ['src/presentation/**'],
+                forbidden_imports: ['@infrastructure/adapters/**', '@src/infrastructure/adapters/**', 'typeorm'],
+                required_evidence: ['import_graph'],
+            },
+            infrastructure: {
+                path_patterns: ['src/infrastructure/**'],
+                allowed_file_patterns: [
+                    'src/infrastructure/adapters/orm/entities/**/*.orm-entity.ts',
+                    'src/infrastructure/adapters/orm/repositories/**/*.typeorm-repository.ts',
+                ],
+                forbidden_imports: ['@prisma/**', 'prisma'],
+                required_evidence: ['filesystem_snapshot', 'import_graph'],
+            },
+        },
+        exceptions: {
+            require_adr: true,
+            require_expiration: true,
+            allowed_refs: [],
+        },
+        update_policy: {
+            owner: 'architecture',
+            review_trigger: 'DevTrack API skill, Foundation layout, or TypeORM architecture change',
+            stale_after_days: 90,
+        },
+    });
+}
+export async function collectDevTrackApiImportGraph(input) {
+    const files = await resolveTypeScriptFiles(input);
+    const edges = [];
+    for (const file of files) {
+        const absolutePath = path.resolve(input.projectRoot, file);
+        const sourceText = await fs.readFile(absolutePath, 'utf-8');
+        const imports = input.collector === 'text'
+            ? collectTextImportSpecifiers(sourceText)
+            : collectTypeScriptImportSpecifiers(sourceText, file);
+        for (const importSpecifier of imports) {
+            edges.push({
+                from: file,
+                to: importSpecifier,
+                kind: importKind(importSpecifier),
+            });
+        }
+    }
+    return {
+        nodes: files,
+        edges: edges.sort(compareImportEdges),
+    };
+}
+export async function validateDevTrackApiArchitecture(input) {
+    const importGraph = input.importGraph ?? await collectDevTrackApiImportGraph(input);
+    const files = await resolveArchitectureFiles(input, importGraph);
+    const fileContents = await readExistingFiles(input.projectRoot, files);
+    const findings = [];
+    for (const edge of importGraph.edges) {
+        const fromLayer = layerFromPath(edge.from);
+        const targetLayer = layerFromImport(edge.from, edge.to);
+        if (edge.kind === 'relative') {
+            findings.push(finding('ARCH_RELATIVE_IMPORT_FORBIDDEN', edge.from, edge.to, `Relative import "${edge.to}" is not allowed in ${edge.from}.`, 'Use the DevTrack API aliases such as @domain/*, @application/*, @infrastructure/*, @presentation/*, or @shared/*.'));
+        }
+        if (isPrismaImport(edge.to)) {
+            findings.push(finding('ARCH_PRISMA_IMPORT_FORBIDDEN', edge.from, edge.to, `Prisma import "${edge.to}" is not allowed in DevTrack API code.`, 'Use TypeORM infrastructure adapters and remove Prisma clients, schemas, migrations, or generated imports.'));
+        }
+        if (fromLayer === 'domain') {
+            if (isDomainForbiddenImport(edge.to) || targetLayer === 'application' || targetLayer === 'presentation' || targetLayer === 'infrastructure') {
+                findings.push(finding('ARCH_DOMAIN_FORBIDDEN_IMPORT', edge.from, edge.to, `Domain file ${edge.from} imports a forbidden dependency through "${edge.to}".`, 'Keep domain inward-only: depend on domain/shared primitives and move orchestration, transport, and adapters outward.'));
+            }
+        }
+        if (fromLayer === 'application' && targetLayer === 'presentation') {
+            findings.push(finding('ARCH_APPLICATION_PRESENTATION_IMPORT', edge.from, edge.to, `Application file ${edge.from} imports presentation through "${edge.to}".`, 'Keep transport dependencies in presentation and expose application behavior through use cases or ports.'));
+        }
+        if (fromLayer === 'application' && isConcreteInfrastructureImport(edge.to)) {
+            findings.push(finding('ARCH_APPLICATION_CONCRETE_INFRA_IMPORT', edge.from, edge.to, `Application file ${edge.from} imports concrete infrastructure through "${edge.to}".`, 'Depend on application-owned ports or shared adapter ports instead of concrete infrastructure adapters.'));
+        }
+        if (fromLayer === 'presentation' && (isConcreteInfrastructureImport(edge.to) || edge.to === 'typeorm')) {
+            findings.push(finding('ARCH_PRESENTATION_INFRA_IMPORT', edge.from, edge.to, `Presentation file ${edge.from} imports infrastructure through "${edge.to}".`, 'Keep presentation thin and call application use cases instead of concrete infrastructure or ORM contracts.'));
+        }
+        if (fromLayer !== 'infrastructure' && isTypeOrmImport(edge.to)) {
+            findings.push(finding('ARCH_TYPEORM_IMPORT_OUTSIDE_INFRASTRUCTURE', edge.from, edge.to, `TypeORM import "${edge.to}" appears outside infrastructure in ${edge.from}.`, 'Move TypeORM decorators, repositories, and ORM-specific types into src/infrastructure/adapters/orm/.'));
+        }
+    }
+    for (const [file, content] of fileContents) {
+        const layer = layerFromPath(file);
+        if (isPrismaFile(file, content)) {
+            findings.push(finding('ARCH_PRISMA_FILE_FORBIDDEN', file, undefined, `Prisma artifact or usage was found in ${file}.`, 'Remove Prisma artifacts and model persistence with TypeORM infrastructure adapters only.'));
+        }
+        if (isTypeOrmEntityFile(file, content) && !isCanonicalTypeOrmEntityPath(file)) {
+            findings.push(finding(layer === 'infrastructure' ? 'ARCH_TYPEORM_ENTITY_PATH_INVALID' : 'ARCH_ENTITY_OUTSIDE_INFRASTRUCTURE', file, undefined, `TypeORM entity ${file} is outside src/infrastructure/adapters/orm/entities/.`, 'Move TypeORM decorators and ORM entity files to src/infrastructure/adapters/orm/entities/.'));
+        }
+        if (isTypeOrmEntityLikePath(file, content) && !normalizeSlashes(file).endsWith('.orm-entity.ts')) {
+            findings.push(finding('ARCH_TYPEORM_ENTITY_SUFFIX_INVALID', file, undefined, `TypeORM entity ${file} does not use the .orm-entity.ts suffix.`, 'Rename ORM entity files to <name>.orm-entity.ts.'));
+        }
+        if (isRepositoryImplementationFile(file) && !isCanonicalTypeOrmRepositoryPath(file)) {
+            findings.push(finding(layer === 'infrastructure' ? 'ARCH_TYPEORM_REPOSITORY_PATH_INVALID' : 'ARCH_REPOSITORY_OUTSIDE_INFRASTRUCTURE', file, undefined, `Repository implementation ${file} is outside src/infrastructure/adapters/orm/repositories/.`, 'Keep concrete repositories under src/infrastructure/adapters/orm/repositories/ and keep application repository ports as *-repository.port.ts.'));
+        }
+        if (isRepositoryImplementationFile(file) && !normalizeSlashes(file).endsWith('.typeorm-repository.ts')) {
+            findings.push(finding('ARCH_TYPEORM_REPOSITORY_SUFFIX_INVALID', file, undefined, `Repository implementation ${file} does not use the .typeorm-repository.ts suffix.`, 'Rename concrete ORM repository files to <name>.typeorm-repository.ts.'));
+        }
+        collectDivergenceFindings(file, findings);
+        collectSemanticFindings(file, content, findings);
+    }
+    detectMissingAggregateModules(files, fileContents, findings);
+    detectMissingRuntimePersistence(files, fileContents, findings);
+    const dedupedFindings = dedupeFindings(findings);
+    return {
+        status: dedupedFindings.length > 0 ? 'warning' : 'passed',
+        architecture_schema: buildDevTrackApiArchitectureSchema(),
+        import_graph: importGraph,
+        findings: dedupedFindings,
+    };
+}
+function finding(code, filePath, importSpecifier, message, remediation) {
+    return {
+        code,
+        severity: 'warn',
+        path: filePath,
+        import_specifier: importSpecifier,
+        message,
+        remediation,
+    };
+}
+async function resolveTypeScriptFiles(input) {
+    const files = input.files
+        ? input.files.map((file) => normalizeProjectPath(input.projectRoot, file))
+        : await collectFiles(input.projectRoot, sourceRoots(input), isTypeScriptSourceFile);
+    return unique(files.filter(isTypeScriptSourceFile).filter(isSafeProjectPath)).sort();
+}
+async function resolveArchitectureFiles(input, importGraph) {
+    if (input.files) {
+        return unique(input.files.map((file) => normalizeProjectPath(input.projectRoot, file)).filter(isSafeProjectPath)).sort();
+    }
+    const collected = await collectFiles(input.projectRoot, sourceRoots(input), isArchitectureSourceFile);
+    return unique([...importGraph.nodes, ...collected].filter(isSafeProjectPath)).sort();
+}
+async function collectFiles(projectRoot, roots, includeFile) {
+    const files = [];
+    for (const root of roots) {
+        const safeRoot = normalizeProjectPath(projectRoot, root);
+        if (!isSafeProjectPath(safeRoot))
+            continue;
+        const absoluteRoot = path.resolve(projectRoot, safeRoot);
+        await collectFilesRecursive(projectRoot, absoluteRoot, files, includeFile);
+    }
+    return unique(files).sort();
+}
+async function collectFilesRecursive(projectRoot, directory, files, includeFile) {
+    const entries = await fs.readdir(directory, { withFileTypes: true }).catch(() => []);
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            await collectFilesRecursive(projectRoot, path.join(directory, entry.name), files, includeFile);
+            continue;
+        }
+        if (!entry.isFile())
+            continue;
+        const relativePath = normalizeProjectPath(projectRoot, path.join(directory, entry.name));
+        if (includeFile(relativePath))
+            files.push(relativePath);
+    }
+}
+async function readExistingFiles(projectRoot, files) {
+    const result = new Map();
+    for (const file of files) {
+        if (!isSafeProjectPath(file))
+            continue;
+        const absolutePath = path.resolve(projectRoot, file);
+        const content = await fs.readFile(absolutePath, 'utf-8').catch(() => null);
+        if (content !== null)
+            result.set(file, content);
+    }
+    return result;
+}
+function collectTypeScriptImportSpecifiers(sourceText, filePath) {
+    try {
+        const sourceFile = ts.createSourceFile(filePath, sourceText, ts.ScriptTarget.Latest, true, scriptKind(filePath));
+        const imports = [];
+        const visit = (node) => {
+            if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) &&
+                node.moduleSpecifier &&
+                isStringLiteralLike(node.moduleSpecifier)) {
+                imports.push(node.moduleSpecifier.text);
+            }
+            if (ts.isCallExpression(node)) {
+                const firstArgument = node.arguments[0];
+                if (node.expression.kind === ts.SyntaxKind.ImportKeyword && firstArgument && isStringLiteralLike(firstArgument)) {
+                    imports.push(firstArgument.text);
+                }
+                if (ts.isIdentifier(node.expression) && node.expression.text === 'require' && firstArgument && isStringLiteralLike(firstArgument)) {
+                    imports.push(firstArgument.text);
+                }
+            }
+            if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument) && isStringLiteralLike(node.argument.literal)) {
+                imports.push(node.argument.literal.text);
+            }
+            ts.forEachChild(node, visit);
+        };
+        visit(sourceFile);
+        return unique(imports);
+    }
+    catch {
+        return collectTextImportSpecifiers(sourceText);
+    }
+}
+function collectTextImportSpecifiers(sourceText) {
+    const withoutComments = stripComments(sourceText);
+    const imports = [];
+    const patterns = [
+        /\bimport\s+(?:type\s+)?(?:[^'";]*?\s+from\s+)?['"]([^'"]+)['"]/gmu,
+        /\bexport\s+(?:type\s+)?[^'";]*?\s+from\s+['"]([^'"]+)['"]/gmu,
+        /\bimport\s*\(\s*['"]([^'"]+)['"]\s*\)/gmu,
+        /\brequire\s*\(\s*['"]([^'"]+)['"]\s*\)/gmu,
+    ];
+    for (const pattern of patterns) {
+        for (const match of withoutComments.matchAll(pattern)) {
+            const importSpecifier = match[1];
+            if (importSpecifier)
+                imports.push(importSpecifier);
+        }
+    }
+    return unique(imports);
+}
+function stripComments(sourceText) {
+    return sourceText
+        .replace(/\/\*[\s\S]*?\*\//gu, '')
+        .replace(/(^|[^:])\/\/.*$/gmu, '$1');
+}
+function scriptKind(filePath) {
+    if (filePath.endsWith('.tsx'))
+        return ts.ScriptKind.TSX;
+    if (filePath.endsWith('.jsx'))
+        return ts.ScriptKind.JSX;
+    return ts.ScriptKind.TS;
+}
+function isStringLiteralLike(node) {
+    return ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node);
+}
+function importKind(importSpecifier) {
+    if (importSpecifier.startsWith('.'))
+        return 'relative';
+    if (DEVTRACK_ALIAS_PREFIXES.some((prefix) => importSpecifier.startsWith(prefix)))
+        return 'alias';
+    return 'package';
+}
+function layerFromImport(fromPath, importSpecifier) {
+    const aliasLayer = layerFromAlias(importSpecifier);
+    if (aliasLayer)
+        return aliasLayer;
+    if (!importSpecifier.startsWith('.'))
+        return undefined;
+    const resolved = path.posix.normalize(path.posix.join(path.posix.dirname(fromPath), importSpecifier));
+    return layerFromPath(resolved);
+}
+function layerFromAlias(importSpecifier) {
+    if (importSpecifier.startsWith('@domain/'))
+        return 'domain';
+    if (importSpecifier.startsWith('@application/'))
+        return 'application';
+    if (importSpecifier.startsWith('@presentation/'))
+        return 'presentation';
+    if (importSpecifier.startsWith('@infrastructure/'))
+        return 'infrastructure';
+    if (importSpecifier.startsWith('@shared/'))
+        return 'shared';
+    if (importSpecifier.startsWith('@src/domain/'))
+        return 'domain';
+    if (importSpecifier.startsWith('@src/application/'))
+        return 'application';
+    if (importSpecifier.startsWith('@src/presentation/'))
+        return 'presentation';
+    if (importSpecifier.startsWith('@src/infrastructure/'))
+        return 'infrastructure';
+    if (importSpecifier.startsWith('@src/shared/'))
+        return 'shared';
+    return undefined;
+}
+function layerFromPath(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    if (normalized === 'src/domain' || normalized.startsWith('src/domain/'))
+        return 'domain';
+    if (normalized === 'src/application' || normalized.startsWith('src/application/'))
+        return 'application';
+    if (normalized === 'src/presentation' || normalized.startsWith('src/presentation/'))
+        return 'presentation';
+    if (normalized === 'src/infrastructure' || normalized.startsWith('src/infrastructure/'))
+        return 'infrastructure';
+    if (normalized === 'src/shared' || normalized.startsWith('src/shared/'))
+        return 'shared';
+    return undefined;
+}
+function isPrismaImport(importSpecifier) {
+    const normalized = importSpecifier.toLowerCase();
+    return normalized === 'prisma' || normalized.startsWith('@prisma/') || normalized.includes('/prisma/');
+}
+function isDomainForbiddenImport(importSpecifier) {
+    const normalized = importSpecifier.toLowerCase();
+    return (normalized.startsWith('@nestjs/') ||
+        normalized === 'typeorm' ||
+        normalized === '@nestjs/typeorm' ||
+        normalized === 'class-validator' ||
+        normalized.startsWith('class-validator/'));
+}
+function isConcreteInfrastructureImport(importSpecifier) {
+    return (importSpecifier.startsWith('@infrastructure/adapters/') ||
+        importSpecifier.startsWith('@src/infrastructure/adapters/'));
+}
+function isTypeOrmImport(importSpecifier) {
+    const normalized = importSpecifier.toLowerCase();
+    return normalized === 'typeorm' || normalized === '@nestjs/typeorm' || normalized.includes('/typeorm');
+}
+function isPrismaFile(filePath, content) {
+    const normalized = normalizeSlashes(filePath).toLowerCase();
+    const segments = normalized.split('/');
+    return (normalized.endsWith('.prisma') ||
+        segments.includes('prisma') ||
+        content.includes('@prisma/client') ||
+        /\bPrismaClient\b/u.test(content));
+}
+function isTypeOrmEntityFile(filePath, content) {
+    const normalized = normalizeSlashes(filePath);
+    return (normalized.endsWith('.orm-entity.ts') ||
+        (normalized.endsWith('.entity.ts') && content.includes('typeorm')) ||
+        /@Entity\s*\(/u.test(content));
+}
+function isTypeOrmEntityLikePath(filePath, content) {
+    const normalized = normalizeSlashes(filePath);
+    return normalized.endsWith('.entity.ts') || normalized.endsWith('.orm-entity.ts') || /@Entity\s*\(/u.test(content);
+}
+function isCanonicalTypeOrmEntityPath(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    return normalized.startsWith('src/infrastructure/adapters/orm/entities/') && normalized.endsWith('.orm-entity.ts');
+}
+function isRepositoryImplementationFile(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    const fileName = path.posix.basename(normalized);
+    return (normalized.includes('/repositories/') ||
+        fileName.endsWith('.typeorm-repository.ts') ||
+        (fileName.endsWith('.repository.ts') && !fileName.endsWith('-repository.port.ts')));
+}
+function isCanonicalTypeOrmRepositoryPath(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    return (normalized.startsWith('src/infrastructure/adapters/orm/repositories/') &&
+        normalized.endsWith('.typeorm-repository.ts'));
+}
+const CANONICAL_BO_METHODS = new Set(['toJSON', 'equals', 'fromJSON', 'toPersistence', 'fromPersistence']);
+const CANONICAL_VO_METHODS = new Set(['normalize', 'isValid', 'getValue', 'toString', 'equals']);
+function collectSemanticFindings(filePath, content, findings) {
+    const normalized = normalizeSlashes(filePath);
+    detectFakeTypeOrmRepository(normalized, content, findings);
+    detectPresentationCompositionRoot(normalized, content, findings);
+    detectPortMissingSymbol(normalized, content, findings);
+    detectNonCanonicalBoVo(normalized, content, findings);
+}
+function detectFakeTypeOrmRepository(filePath, content, findings) {
+    if (!filePath.endsWith('.typeorm-repository.ts'))
+        return;
+    const hasInjectRepository = /@InjectRepository\s*\(/u.test(content);
+    const usesRepositoryType = /\bRepository\s*[<]/u.test(content);
+    const hasRepositoryExtends = /\bextends\s+\w*Repository\b/u.test(content);
+    const isRealTypeOrm = hasInjectRepository || usesRepositoryType || hasRepositoryExtends;
+    if (!isRealTypeOrm) {
+        findings.push(finding('ARCH_TYPEORM_REPOSITORY_FAKE', filePath, undefined, `TypeORM repository ${filePath} lacks real TypeORM wiring (no @InjectRepository, no Repository<Entity> usage).`, 'Implement real TypeORM wiring with @InjectRepository(Entity) and Repository<Entity> or rename to reflect it is a prototype/adapter.'));
+        return;
+    }
+    if (/\bnew\s+Map\s*\(/u.test(content)) {
+        findings.push(finding('ARCH_TYPEORM_REPOSITORY_FAKE', filePath, undefined, `TypeORM repository ${filePath} uses in-memory Map persistence, indicating a fake/stub implementation.`, 'Replace in-memory Map with real TypeORM Repository operations or rename to indicate prototype status.'));
+    }
+}
+function detectPresentationCompositionRoot(filePath, content, findings) {
+    if (!filePath.startsWith('src/presentation/'))
+        return;
+    const hasModuleDecorator = /@Module\s*\(\s*\{/u.test(content);
+    if (!hasModuleDecorator)
+        return;
+    const hasServiceInstantiation = /\bnew\s+\w*(?:UseCase|Repository|Adapter|Service|Port)\w*\s*\(/u.test(content);
+    if (hasServiceInstantiation) {
+        findings.push(finding('ARCH_PRESENTATION_COMPOSITION_ROOT', filePath, undefined, `Presentation file ${filePath} directly instantiates application/infrastructure classes.`, 'Inject dependencies through NestJS DI and keep presentation importing only application boundaries.'));
+    }
+}
+function detectPortMissingSymbol(filePath, content, findings) {
+    if (!filePath.endsWith('.port.ts'))
+        return;
+    const hasExportedSymbol = /\bexport\s+(const|let|var)\s+\w+\s*=\s*Symbol\s*\(/u.test(content);
+    if (!hasExportedSymbol) {
+        findings.push(finding('ARCH_PORT_MISSING_SYMBOL', filePath, undefined, `Port file ${filePath} lacks an exported Symbol for the port contract.`, 'Add an exported Symbol for the port, e.g.: export const ORDER_REPOSITORY_PORT = Symbol(\'ORDER_REPOSITORY_PORT\');'));
+    }
+    detectPortGroupedUnrelated(filePath, content, findings);
+}
+function detectPortGroupedUnrelated(filePath, content, findings) {
+    if (filePath.includes('/ports/in/')) {
+        const exportedInterfaces = [...content.matchAll(/\bexport\s+interface\s+(\w+)/gmu)]
+            .map((match) => match[1])
+            .filter(Boolean);
+        const useCasePorts = exportedInterfaces.filter((name) => /(?:UseCase|UseCasePort)$/u.test(name));
+        if (useCasePorts.length > 1) {
+            findings.push(finding('ARCH_PORT_GROUPED_UNRELATED', filePath, undefined, `Input port file ${filePath} groups multiple use-case ports: ${useCasePorts.join(', ')}.`, 'Split input ports by use case so each *.use-case.port.ts file owns one use-case contract plus its exported Symbol.'));
+        }
+    }
+}
+function detectNonCanonicalBoVo(filePath, content, findings) {
+    if (filePath.endsWith('.bo.ts')) {
+        const missingMethods = [];
+        for (const method of CANONICAL_BO_METHODS) {
+            if (!new RegExp(`\\b${method}\\s*\\(`, 'u').test(content)) {
+                missingMethods.push(method);
+            }
+        }
+        if (missingMethods.length >= 2) {
+            findings.push(finding('ARCH_BO_MISSING_METHODS', filePath, undefined, `BO ${filePath} is missing canonical methods: ${missingMethods.join(', ')}.`, `Add at least the following methods to the business object: ${[...CANONICAL_BO_METHODS].join(', ')}.`));
+        }
+    }
+    if (filePath.endsWith('.vo.ts')) {
+        const missingMethods = [];
+        for (const method of CANONICAL_VO_METHODS) {
+            if (!new RegExp(`\\b${method}\\s*\\(`, 'u').test(content)) {
+                missingMethods.push(method);
+            }
+        }
+        if (missingMethods.length >= 2) {
+            findings.push(finding('ARCH_VO_MISSING_METHODS', filePath, undefined, `VO ${filePath} is missing canonical methods: ${missingMethods.join(', ')}.`, `Add at least the following methods to the value object: ${[...CANONICAL_VO_METHODS].join(', ')}.`));
+        }
+    }
+}
+function detectMissingAggregateModules(files, fileContents, findings) {
+    const fileSet = new Set(files.map(f => normalizeSlashes(f)));
+    const hasAppModule = [...fileSet].some(f => f === 'src/application/application.module.ts' ||
+        /^src\/application\/\w+\/application\.module\.ts$/.test(f));
+    if (!hasAppModule) {
+        findings.push(finding('ARCH_AGGREGATE_MODULE_MISSING', 'src/application', undefined, 'Missing aggregate module: src/application/application.module.ts was not found.', 'Create src/application/application.module.ts with @Module({...}) decorator and appropriate providers/exports.'));
+    }
+    const hasInfraModule = [...fileSet].some(f => f === 'src/infrastructure/infrastructure.module.ts' ||
+        /^src\/infrastructure\/\w+\/infrastructure\.module\.ts$/.test(f));
+    if (!hasInfraModule) {
+        findings.push(finding('ARCH_AGGREGATE_MODULE_MISSING', 'src/infrastructure', undefined, 'Missing aggregate module: src/infrastructure/infrastructure.module.ts was not found.', 'Create src/infrastructure/infrastructure.module.ts with @Module({...}) decorator and TypeORM imports.'));
+    }
+    const hasPresModuleByTransport = [...fileSet].some(f => f === 'src/presentation/presentation.module.ts' ||
+        [...PRESENTATION_TRANSPORTS].some(transport => f === `src/presentation/${transport}/${transport}.module.ts` ||
+            f === `src/presentation/${transport}.module.ts`));
+    if (!hasPresModuleByTransport) {
+        findings.push(finding('ARCH_AGGREGATE_MODULE_MISSING', 'src/presentation', undefined, 'Missing aggregate module: src/presentation/presentation.module.ts or transport-specific module was not found.', 'Create src/presentation/presentation.module.ts or a transport-specific module with @Module({...}) decorator.'));
+    }
+    for (const [filePath, content] of fileContents) {
+        const normalized = normalizeSlashes(filePath);
+        if (/\.module\.ts$/.test(normalized)) {
+            const hasNestJSModule = /@Module\s*\(\s*\{/u.test(content);
+            if (!hasNestJSModule) {
+                findings.push(finding('ARCH_AGGREGATE_MODULE_NOT_NESTJS', normalized, undefined, `Module file ${normalized} does not contain a NestJS @Module({...}) decorator.`, 'Add @Module({...}) decorator to the module class or rename the file if it is not a NestJS module.'));
+            }
+        }
+    }
+}
+function detectMissingRuntimePersistence(files, fileContents, findings) {
+    const fileSet = new Set(files.map(f => normalizeSlashes(f)));
+    const hasTypeOrmRepos = [...fileSet].some(f => f.endsWith('.typeorm-repository.ts'));
+    const hasTypeOrmEntities = [...fileSet].some(f => f.endsWith('.orm-entity.ts'));
+    if (!hasTypeOrmRepos && !hasTypeOrmEntities)
+        return;
+    const hasDataSource = [...fileContents.entries()].some(([_, content]) => /\bnew\s+DataSource\s*\(/u.test(content) ||
+        /TypeOrmModule\.(?:forRoot|forRootAsync)\s*\(/u.test(content));
+    if (!hasDataSource) {
+        findings.push(finding('ARCH_MISSING_DATASOURCE', 'src/infrastructure', undefined, 'Missing DataSource or TypeORM root configuration.', 'Add a DataSource configuration or TypeOrmModule.forRoot() call in the infrastructure module.'));
+    }
+    const hasMigrations = [...fileSet].some(f => f.includes('/migrations/'));
+    if (!hasMigrations) {
+        findings.push(finding('ARCH_MISSING_MIGRATIONS', 'src/infrastructure/adapters/orm/migrations', undefined, 'Missing migrations directory or files under src/infrastructure/adapters/orm/migrations/.', 'Create migrations for persistent entities under src/infrastructure/adapters/orm/migrations/.'));
+    }
+    const hasForFeature = [...fileContents.entries()].some(([f, content]) => normalizeSlashes(f).startsWith('src/infrastructure/') &&
+        /TypeOrmModule\.forFeature\s*\(/u.test(content));
+    if (!hasForFeature) {
+        findings.push(finding('ARCH_MISSING_TYPEORM_MODULE_FORFEATURE', 'src/infrastructure', undefined, 'Missing TypeOrmModule.forFeature() wiring in infrastructure module.', 'Add TypeOrmModule.forFeature([Entity]) to the infrastructure module imports for concrete TypeORM repositories.'));
+    }
+}
+function collectDivergenceFindings(filePath, findings) {
+    const normalized = normalizeSlashes(filePath);
+    const segments = normalized.split('/');
+    if (segments[0] === 'src' && segments[1] === 'domain') {
+        const context = segments[2];
+        const subfolder = segments[3];
+        if (context && subfolder === 'entities' && !LEGACY_ENTITY_PATTERN_CONTEXTS.has(context)) {
+            findings.push(finding('ARCH_DOMAIN_ENTITY_CONTEXT_FORBIDDEN', normalized, undefined, `New domain context ${context} uses legacy entities/ layout.`, 'Use src/domain/<context>/business-objects/<name>.bo.ts for new contexts, or record an ADR for an entity-pattern exception.'));
+        }
+        if (context && subfolder === 'repository-ports' && !LEGACY_ENTITY_PATTERN_CONTEXTS.has(context)) {
+            findings.push(finding('ARCH_DOMAIN_REPOSITORY_PORT_CONTEXT_FORBIDDEN', normalized, undefined, `New domain context ${context} declares repository ports in domain.`, 'Move BO-pattern repository ports to src/application/business/<context>/ports/out/.'));
+        }
+        if (subfolder === 'exceptions') {
+            findings.push(finding('ARCH_DOMAIN_EXCEPTION_PATH_FORBIDDEN', normalized, undefined, `Domain exception path ${normalized} is not canonical.`, 'Use centralized exceptions under src/shared/domain/exceptions/ or record an ADR-backed exception.'));
+        }
+        if (subfolder === 'value-objects' && normalized.endsWith('.value-object.ts')) {
+            findings.push(finding('ARCH_VALUE_OBJECT_SUFFIX_INVALID', normalized, undefined, `Value object ${normalized} uses the non-canonical .value-object.ts suffix.`, 'Rename value objects to <name>.vo.ts.'));
+        }
+    }
+    if (segments[0] === 'src' && segments[1] === 'presentation') {
+        const transport = segments[2];
+        if (transport && !PRESENTATION_TRANSPORTS.has(transport)) {
+            findings.push(finding('ARCH_PRESENTATION_TRANSPORT_MISSING', normalized, undefined, `Presentation path ${normalized} is not segmented by a known transport.`, 'Use src/presentation/rest/<context>/... or another explicit transport segment.'));
+        }
+    }
+    if (segments[0] === 'src' && segments[1] === 'infrastructure') {
+        if (segments[2] && segments[2] !== 'adapters' && segments[3] === 'adapters') {
+            findings.push(finding('ARCH_INFRASTRUCTURE_CONTEXT_ADAPTER_FORBIDDEN', normalized, undefined, `Infrastructure path ${normalized} organizes adapters by business context.`, 'Use src/infrastructure/adapters/<subsystem>/... instead of src/infrastructure/<context>/adapters/.'));
+        }
+        if (segments[2] && segments[2] !== 'adapters' && segments.includes('persistence') && segments.includes('typeorm')) {
+            findings.push(finding('ARCH_INFRASTRUCTURE_CONTEXT_PERSISTENCE_FORBIDDEN', normalized, undefined, `Infrastructure path ${normalized} uses context-local TypeORM persistence.`, 'Use centralized TypeORM paths under src/infrastructure/adapters/orm/.'));
+        }
+    }
+}
+function isTypeScriptSourceFile(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    return TYPESCRIPT_EXTENSIONS.some((extension) => normalized.endsWith(extension)) && !normalized.endsWith('.d.ts');
+}
+function isArchitectureSourceFile(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    return isTypeScriptSourceFile(normalized) || normalized.endsWith('.prisma');
+}
+function sourceRoots(input) {
+    if (input.sourceRoots)
+        return input.sourceRoots;
+    if (input.sourceRoot)
+        return [input.sourceRoot];
+    return DEFAULT_SOURCE_ROOTS;
+}
+function normalizeProjectPath(projectRoot, filePath) {
+    const relativePath = path.isAbsolute(filePath) ? path.relative(projectRoot, filePath) : filePath;
+    return normalizeSlashes(relativePath).replace(/^\.\//u, '');
+}
+function normalizeSlashes(value) {
+    return value.replace(/\\/gu, '/');
+}
+function isSafeProjectPath(filePath) {
+    const normalized = normalizeSlashes(filePath);
+    return Boolean(normalized) && !normalized.startsWith('/') && !normalized.split('/').includes('..');
+}
+function dedupeFindings(findings) {
+    const seen = new Set();
+    const result = [];
+    for (const item of findings) {
+        const key = item.code === 'ARCH_PRISMA_FORBIDDEN'
+            ? `${item.code}:${item.path ?? ''}`
+            : `${item.code}:${item.path ?? ''}:${item.import_specifier ?? ''}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        result.push(item);
+    }
+    return result.sort((left, right) => `${left.path ?? ''}:${left.import_specifier ?? ''}:${left.code}`.localeCompare(`${right.path ?? ''}:${right.import_specifier ?? ''}:${right.code}`));
+}
+function compareImportEdges(left, right) {
+    return `${left.from}:${left.to}`.localeCompare(`${right.from}:${right.to}`);
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=devtrack-api-architecture.js.map

package/dist/core/sdd/devtrack-api-import-boundary.d.ts

@@ -0,0 +1,19 @@
+import { type CollectDevTrackApiImportGraphInput, type DevTrackApiArchitectureFinding } from './devtrack-api-architecture.js';
+import type { QualityArchitectureSchema, QualityImportGraph } from './quality-validation.js';
+export type DevTrackApiImportBoundaryIssueCode = 'ARCH_RELATIVE_IMPORT_FORBIDDEN' | 'ARCH_DOMAIN_FORBIDDEN_IMPORT' | 'ARCH_APPLICATION_PRESENTATION_IMPORT' | 'ARCH_APPLICATION_CONCRETE_INFRA_IMPORT' | 'ARCH_PRESENTATION_INFRA_IMPORT' | 'ARCH_TYPEORM_IMPORT_OUTSIDE_INFRASTRUCTURE' | 'ARCH_PRISMA_IMPORT_FORBIDDEN';
+export type DevTrackApiImportBoundaryFinding = DevTrackApiArchitectureFinding & {
+    code: DevTrackApiImportBoundaryIssueCode;
+    import_specifier: string;
+};
+export interface ValidateDevTrackApiImportBoundariesInput extends CollectDevTrackApiImportGraphInput {
+    importGraph?: QualityImportGraph;
+}
+export interface DevTrackApiImportBoundaryValidationResult {
+    status: 'passed' | 'warning';
+    architecture_schema: QualityArchitectureSchema;
+    import_graph: QualityImportGraph;
+    findings: DevTrackApiImportBoundaryFinding[];
+}
+export declare function validateDevTrackApiImportBoundaries(input: ValidateDevTrackApiImportBoundariesInput): Promise<DevTrackApiImportBoundaryValidationResult>;
+export declare function buildDevTrackApiImportBoundarySchema(): QualityArchitectureSchema;
+//# sourceMappingURL=devtrack-api-import-boundary.d.ts.map

package/dist/core/sdd/devtrack-api-import-boundary.js

@@ -0,0 +1,32 @@
+import { buildDevTrackApiArchitectureSchema, collectDevTrackApiImportGraph, validateDevTrackApiArchitecture, } from './devtrack-api-architecture.js';
+const IMPORT_BOUNDARY_CODES = new Set([
+    'ARCH_RELATIVE_IMPORT_FORBIDDEN',
+    'ARCH_DOMAIN_FORBIDDEN_IMPORT',
+    'ARCH_APPLICATION_PRESENTATION_IMPORT',
+    'ARCH_APPLICATION_CONCRETE_INFRA_IMPORT',
+    'ARCH_PRESENTATION_INFRA_IMPORT',
+    'ARCH_TYPEORM_IMPORT_OUTSIDE_INFRASTRUCTURE',
+    'ARCH_PRISMA_IMPORT_FORBIDDEN',
+]);
+export async function validateDevTrackApiImportBoundaries(input) {
+    const importGraph = input.importGraph ?? await collectDevTrackApiImportGraph(input);
+    const architectureResult = await validateDevTrackApiArchitecture({
+        ...input,
+        importGraph,
+    });
+    const findings = architectureResult.findings.filter(isImportBoundaryFinding);
+    return {
+        status: findings.length > 0 ? 'warning' : 'passed',
+        architecture_schema: architectureResult.architecture_schema,
+        import_graph: architectureResult.import_graph,
+        findings,
+    };
+}
+export function buildDevTrackApiImportBoundarySchema() {
+    return buildDevTrackApiArchitectureSchema();
+}
+function isImportBoundaryFinding(finding) {
+    return Boolean(finding.import_specifier &&
+        IMPORT_BOUNDARY_CODES.has(finding.code));
+}
+//# sourceMappingURL=devtrack-api-import-boundary.js.map