@devtrack-solution/codesdd 1.2.3 → 1.2.4

package/dist/core/sdd/package-structure-gate.js

@@ -1,22 +1,56 @@
+import { createHash } from 'node:crypto';
 import { z } from 'zod';
+import { validateFoundationArtifactMapArchitecture } from './foundation-artifact-map-validator.js';
+import { pluginArtifactMapSchema } from './plugin-sdk-contract.js';
 export const DerivationProfileSchema = z.enum(['prototype', 'foundation-compatible', 'enterprise-strict']);
 export const PreviewGateStatusSchema = z.enum(['pending', 'approved', 'corrected', 'rejected']);
 export const PackageStructureNodeKindSchema = z.enum(['dir', 'file']);
+export const PreviewContextPatternSchema = z.enum(['bo-pattern', 'entity-pattern', 'application-only']);
+export const PreviewDiagnosticSeveritySchema = z.enum(['warn', 'block']);
 export const PackageStructureNodeSchema = z.lazy(() => z.object({
     name: z.string().min(1),
     kind: PackageStructureNodeKindSchema,
     description: z.string().optional(),
     children: z.array(PackageStructureNodeSchema).optional(),
 }));
+export const ApplicationOnlyContextSchema = z.object({
+    context: z.string().min(1),
+    path: z.string().min(1),
+    reason: z.string().min(1),
+    adr_required: z.boolean().default(true),
+    contract_rule_ref: z.literal('DTAPI-P1-APPONLY-001'),
+});
+export const PreviewContextClassificationSchema = z.object({
+    context: z.string().min(1),
+    pattern: PreviewContextPatternSchema,
+    source_paths: z.array(z.string().min(1)).default([]),
+    decision_refs: z.array(z.string().min(1)).default([]),
+});
+export const PreviewDiagnosticSchema = z.object({
+    code: z.string().min(1),
+    severity: PreviewDiagnosticSeveritySchema,
+    message: z.string().min(1),
+    remediation: z.string().min(1),
+    path: z.string().min(1).optional(),
+});
 export const PackageStructurePreviewSchema = z.object({
     schema_version: z.literal(1),
     generated_at: z.string(),
     project_name: z.string().min(1),
     profile: DerivationProfileSchema,
+    source: z.enum(['template', 'artifact-map']).default('template'),
     contexts: z.array(z.string()),
     subsystems: z.array(z.string()),
     transports: z.array(z.string()),
     tree: PackageStructureNodeSchema,
+    foundation_tests_projection: PackageStructureNodeSchema.optional(),
+    runtime_scripts_projection: PackageStructureNodeSchema.optional(),
+    application_only_contexts: z.array(ApplicationOnlyContextSchema).default([]),
+    context_classification: z.array(PreviewContextClassificationSchema).default([]),
+    contract_pack_refs: z.array(z.string().min(1)).default([]),
+    diagnostics: z.array(PreviewDiagnosticSchema).default([]),
+    artifact_languages: z.array(z.string().min(1)).default([]),
+    material_signature: z.string().min(1),
 });
 export const HumanValidationGateSchema = z.object({
     gate_id: z.string(),
@@ -27,22 +61,59 @@ export const HumanValidationGateSchema = z.object({
     approved_by: z.string().optional(),
     correction_notes: z.string().optional(),
     exception_refs: z.array(z.string()).default([]),
+    contract_pack_refs: z.array(z.string().min(1)).default([]),
+    material_signature: z.string().min(1),
+    serialized_at: z.string(),
 });
+const DEFAULT_CONTRACT_PACK_REFS = [
+    'DTAPI-P0-FOUNDATION-001',
+    'DTAPI-P0-PREVIEW-001',
+    'DTAPI-P0-PATH-001',
+    'DTAPI-P0-RUNTIME-SCRIPTS-001',
+    'DTAPI-P1-APPONLY-001',
+];
+const FOUNDATION_TESTS_ROOT = 'tests/';
+const SUPPORTED_PREVIEW_LANGUAGES = new Set(['typescript', 'javascript']);
+const APPLICATION_ONLY_CONTEXT_REASONS = {
+    'aws-integrations': 'Orchestrates AWS adapter wiring across infrastructure subsystems; invariants stay in infrastructure adapters.',
+    foundation: 'Composition root for Foundation-wide use-cases shared by other contexts and does not introduce a bounded domain vocabulary.',
+};
 export function generatePackageStructurePreview(input) {
+    if (input.artifact_map) {
+        return generateArtifactMapPackageStructurePreview(input);
+    }
     const profile = input.profile ?? 'foundation-compatible';
     const contexts = input.contexts ?? ['auth'];
     const subsystems = input.subsystems ?? ['orm', 'cache', 'configuration'];
     const transports = input.transports ?? ['rest', 'graphql', 'cli'];
     const generatedAt = input.generated_at ?? new Date().toISOString();
-    return {
+    const preview = {
         schema_version: 1,
         generated_at: generatedAt,
         project_name: input.project_name,
         profile,
+        source: 'template',
         contexts,
         subsystems,
         transports,
         tree: buildProjectTree(profile, contexts, subsystems, transports),
+        foundation_tests_projection: buildTemplateTestsProjection(),
+        runtime_scripts_projection: buildRuntimeScriptsProjection(),
+        application_only_contexts: [],
+        context_classification: contexts.map((context) => ({
+            context,
+            pattern: 'bo-pattern',
+            source_paths: [`src/domain/${context}/`, `src/application/business/${context}/`],
+            decision_refs: [],
+        })),
+        contract_pack_refs: [...DEFAULT_CONTRACT_PACK_REFS],
+        diagnostics: [],
+        artifact_languages: ['typescript'],
+        material_signature: '',
+    };
+    return {
+        ...preview,
+        material_signature: computePreviewSignature(preview),
     };
 }
 export function formatPreviewAsTree(node, prefix = '') {
@@ -58,13 +129,24 @@ export function formatPreviewAsTree(node, prefix = '') {
     }
     return lines.join('\n');
 }
-export function buildHumanValidationGate(preview) {
+export function buildHumanValidationGate(preview, options) {
+    const exceptionRefs = [...new Set(options?.exception_refs ?? [])];
+    const materialSignature = computeGateSignature(preview, exceptionRefs);
+    const previousGate = options?.previous_gate;
+    const preserveStatus = previousGate?.material_signature === materialSignature;
+    const serializedAt = new Date().toISOString();
     return {
         gate_id: `GATE-PKG-${preview.project_name.replace(/[^a-zA-Z0-9-]/g, '-')}`,
         rule_ref: 'DTAPI-P0-PREVIEW-001',
-        status: 'pending',
+        status: preserveStatus ? previousGate.status : 'pending',
         preview_ref: `devtrack-api-package-preview-${preview.project_name}`,
-        exception_refs: [],
+        approved_at: preserveStatus ? previousGate?.approved_at : undefined,
+        approved_by: preserveStatus ? previousGate?.approved_by : undefined,
+        correction_notes: preserveStatus ? previousGate?.correction_notes : undefined,
+        exception_refs: exceptionRefs,
+        contract_pack_refs: preview.contract_pack_refs,
+        material_signature: materialSignature,
+        serialized_at: serializedAt,
     };
 }
 export function generateDevtrackApiDebGate(input) {
@@ -73,12 +155,18 @@ export function generateDevtrackApiDebGate(input) {
     return {
         selected_profile: input.profile ?? 'foundation-compatible',
         package_preview: preview,
-        human_validation_gate: gate,
+        human_validation_gate: buildHumanValidationGate(preview, {
+            previous_gate: input.previous_human_validation_gate,
+            exception_refs: gate.exception_refs,
+        }),
         exception_list: [],
         policy_pool_seed: [
+            'DTAPI-P0-FOUNDATION-001: Foundation evidence wins over generated assumptions',
             'DTAPI-P0-PROFILE-001: derivation profile must be explicit',
             'DTAPI-P0-PREVIEW-001: early planning must include package structure preview',
             'DTAPI-P0-PATH-001: proposed paths must match canonical Foundation paths',
+            'DTAPI-P0-RUNTIME-SCRIPTS-001: Foundation-linked projects require cleanup and port-safe npm/pnpm runtime scripts',
+            'DTAPI-P1-APPONLY-001: application-only contexts require ADR justification',
         ],
     };
 }
@@ -243,7 +331,12 @@ function buildOrmSubsystem(contexts) {
         children: [
             { name: 'typeorm.config.ts', kind: 'file', description: 'TypeORM root configuration' },
             { name: 'typeorm-cli.datasource.ts', kind: 'file', description: 'TypeORM CLI datasource' },
-            { name: 'typeorm.module.ts', kind: 'file', description: 'Root TypeORM module' },
+            { name: 'typeorm.module.ts', kind: 'file', description: 'TypeORM root module with forRootAsync and base forFeature entities' },
+            ...contexts.map((context) => ({
+                name: `${context}-orm.module.ts`,
+                kind: 'file',
+                description: `${context} ORM module exporting repository port providers`,
+            })),
             {
                 name: 'entities/',
                 kind: 'dir',
@@ -264,11 +357,6 @@ function buildOrmSubsystem(contexts) {
                 kind: 'dir',
                 children: [{ name: '<timestamp>-<action>.migration.ts', kind: 'file', description: 'Database migration' }],
             },
-            ...contexts.map((context) => ({
-                name: `${context}-orm.module.ts`,
-                kind: 'file',
-                description: `${context} TypeORM module`,
-            })),
         ],
     };
 }
@@ -359,4 +447,289 @@ function buildSharedLayer() {
         ],
     };
 }
+function generateArtifactMapPackageStructurePreview(input) {
+    const generatedAt = input.generated_at ?? new Date().toISOString();
+    const profile = input.profile ?? 'foundation-compatible';
+    const parsed = pluginArtifactMapSchema.safeParse(input.artifact_map);
+    const contractPackRefs = [...new Set(input.contract_pack_refs ?? DEFAULT_CONTRACT_PACK_REFS)];
+    if (!parsed.success) {
+        const fallbackPreview = {
+            schema_version: 1,
+            generated_at: generatedAt,
+            project_name: input.project_name,
+            profile,
+            source: 'artifact-map',
+            contexts: input.contexts ?? [],
+            subsystems: input.subsystems ?? [],
+            transports: input.transports ?? [],
+            tree: { name: 'src/', kind: 'dir', children: [] },
+            foundation_tests_projection: { name: FOUNDATION_TESTS_ROOT, kind: 'dir', children: [] },
+            runtime_scripts_projection: buildRuntimeScriptsProjection([]),
+            application_only_contexts: [],
+            context_classification: [],
+            contract_pack_refs: contractPackRefs,
+            diagnostics: parsed.error.issues.map((issue) => ({
+                code: 'DTAPI_PREVIEW_ARTIFACT_MAP_INVALID',
+                severity: 'block',
+                message: issue.message,
+                remediation: 'Validate the artifact map with the CodeSDD plugin SDK before generating the Foundation-compatible preview.',
+                path: issue.path.join('.') || undefined,
+            })),
+            artifact_languages: [],
+            material_signature: '',
+        };
+        return {
+            ...fallbackPreview,
+            material_signature: computePreviewSignature(fallbackPreview),
+        };
+    }
+    const artifactMap = parsed.data;
+    const srcEntries = artifactMap.artifacts.filter((entry) => entry.path.startsWith('src/'));
+    const testEntries = artifactMap.artifacts.filter((entry) => entry.path.startsWith(FOUNDATION_TESTS_ROOT));
+    const runtimeEntries = artifactMap.artifacts.filter(isRuntimeScriptArtifact);
+    const domainContexts = collectDomainContexts(artifactMap.artifacts);
+    const applicationContexts = collectApplicationContexts(artifactMap.artifacts);
+    const applicationOnlyContexts = buildApplicationOnlyContexts(applicationContexts, domainContexts);
+    const contextClassification = buildContextClassification(artifactMap.artifacts, domainContexts, applicationOnlyContexts);
+    const diagnostics = [
+        ...validateFoundationArtifactMapArchitecture(artifactMap).findings.map(mapFoundationFindingToPreviewDiagnostic),
+        ...buildLanguageDiagnostics(artifactMap.artifacts),
+        ...(testEntries.length === 0
+            ? [
+                {
+                    code: 'DTAPI_PREVIEW_TESTS_MISSING',
+                    severity: 'warn',
+                    message: 'Artifact map does not project any Foundation-compatible tests/ artifacts.',
+                    remediation: 'Project at least the canonical tests/ smoke artifacts before human preview approval.',
+                },
+            ]
+            : []),
+    ];
+    const preview = {
+        schema_version: 1,
+        generated_at: generatedAt,
+        project_name: input.project_name,
+        profile,
+        source: 'artifact-map',
+        contexts: [...domainContexts],
+        subsystems: collectSubsystems(artifactMap.artifacts),
+        transports: collectTransports(artifactMap.artifacts),
+        tree: buildTreeFromArtifacts(srcEntries, 'src/'),
+        foundation_tests_projection: buildTreeFromArtifacts(testEntries, FOUNDATION_TESTS_ROOT),
+        runtime_scripts_projection: buildRuntimeScriptsProjection(runtimeEntries),
+        application_only_contexts: applicationOnlyContexts,
+        context_classification: contextClassification,
+        contract_pack_refs: contractPackRefs,
+        diagnostics,
+        artifact_languages: collectArtifactLanguages(artifactMap.artifacts),
+        material_signature: '',
+    };
+    return {
+        ...preview,
+        material_signature: computePreviewSignature(preview),
+    };
+}
+function buildTemplateTestsProjection() {
+    return {
+        name: FOUNDATION_TESTS_ROOT,
+        kind: 'dir',
+        description: 'Foundation-compatible tests projection',
+        children: [
+            { name: 'app.e2e-spec.ts', kind: 'file', description: 'Initial E2E smoke test' },
+            { name: 'jest-e2e.json', kind: 'file', description: 'Jest E2E configuration' },
+        ],
+    };
+}
+function buildRuntimeScriptsProjection(entries) {
+    if (entries !== undefined) {
+        return buildTreeFromArtifacts(entries, 'project-root/');
+    }
+    return {
+        name: 'project-root/',
+        kind: 'dir',
+        description: 'Mandatory npm/pnpm-compatible runtime script projection',
+        children: [
+            { name: 'package.json', kind: 'file', description: 'Package scripts with cleanup, cleanup:install, start, start:dev, and npm-run internal composition' },
+            {
+                name: 'scripts/',
+                kind: 'dir',
+                children: [
+                    { name: 'cleanup.sh', kind: 'file', description: 'Destructive cleanup for dependencies, build outputs, caches, lockfiles, and compilation residue' },
+                    { name: 'kill-port.js', kind: 'file', description: 'Port preflight used by start and start:dev before Nest bootstrap' },
+                ],
+            },
+        ],
+    };
+}
+function buildTreeFromArtifacts(entries, rootName) {
+    const root = { name: rootName, kind: 'dir', children: [] };
+    const rootSegments = rootName.replace(/\/$/u, '').split('/');
+    for (const entry of [...entries].sort((left, right) => left.path.localeCompare(right.path))) {
+        const segments = entry.path.split('/');
+        const relativeSegments = rootSegments.every((segment, index) => segments[index] === segment)
+            ? segments.slice(rootSegments.length)
+            : segments;
+        insertArtifactPath(root, relativeSegments, entry.reason);
+    }
+    return root;
+}
+function isRuntimeScriptArtifact(entry) {
+    return entry.path === 'package.json' || entry.path === 'scripts/cleanup.sh' || entry.path === 'scripts/kill-port.js';
+}
+function insertArtifactPath(root, segments, description) {
+    if (segments.length === 0)
+        return;
+    if (!root.children)
+        root.children = [];
+    const [current, ...rest] = segments;
+    const isLeaf = rest.length === 0;
+    const nodeName = isLeaf ? current : `${current}/`;
+    let node = root.children.find((child) => child.name === nodeName);
+    if (!node) {
+        node = {
+            name: nodeName,
+            kind: isLeaf ? 'file' : 'dir',
+            description: isLeaf ? description : undefined,
+            children: isLeaf ? undefined : [],
+        };
+        root.children.push(node);
+    }
+    else if (isLeaf && !node.description) {
+        node.description = description;
+    }
+    if (!isLeaf) {
+        insertArtifactPath(node, rest, description);
+    }
+}
+function collectDomainContexts(entries) {
+    const contexts = new Set();
+    for (const entry of entries) {
+        const match = /^src\/domain\/([^/]+)\//u.exec(entry.path);
+        if (match)
+            contexts.add(match[1]);
+    }
+    return contexts;
+}
+function collectApplicationContexts(entries) {
+    const contexts = new Set();
+    for (const entry of entries) {
+        const match = /^src\/application\/business\/([^/]+)\//u.exec(entry.path);
+        if (match)
+            contexts.add(match[1]);
+    }
+    return contexts;
+}
+function buildApplicationOnlyContexts(applicationContexts, domainContexts) {
+    return [...applicationContexts]
+        .filter((context) => !domainContexts.has(context))
+        .sort()
+        .map((context) => ({
+        context,
+        path: `src/application/business/${context}/`,
+        reason: APPLICATION_ONLY_CONTEXT_REASONS[context] ??
+            'Application-only orchestration context without a domain counterpart; requires ADR justification before approval.',
+        adr_required: true,
+        contract_rule_ref: 'DTAPI-P1-APPONLY-001',
+    }));
+}
+function buildContextClassification(entries, domainContexts, applicationOnlyContexts) {
+    const grouped = new Map();
+    for (const entry of entries) {
+        const match = /^src\/domain\/([^/]+)\//u.exec(entry.path);
+        if (!match)
+            continue;
+        const context = match[1];
+        grouped.set(context, [...(grouped.get(context) ?? []), entry]);
+    }
+    const classifications = [...domainContexts].sort().map((context) => {
+        const contextEntries = grouped.get(context) ?? [];
+        const pattern = contextEntries.some((entry) => entry.role === 'entity')
+            ? 'entity-pattern'
+            : 'bo-pattern';
+        return {
+            context,
+            pattern,
+            source_paths: [...new Set(contextEntries.map((entry) => entry.path))],
+            decision_refs: [...new Set(contextEntries.flatMap((entry) => entry.decision_refs))],
+        };
+    });
+    return [
+        ...classifications,
+        ...applicationOnlyContexts.map((item) => ({
+            context: item.context,
+            pattern: 'application-only',
+            source_paths: [item.path],
+            decision_refs: [],
+        })),
+    ];
+}
+function collectSubsystems(entries) {
+    return [
+        ...new Set(entries
+            .map((entry) => /^src\/infrastructure\/adapters\/([^/]+)\//u.exec(entry.path)?.[1])
+            .filter((value) => Boolean(value))),
+    ];
+}
+function collectTransports(entries) {
+    return [
+        ...new Set(entries
+            .map((entry) => /^src\/presentation\/([^/]+)\//u.exec(entry.path)?.[1])
+            .filter((value) => Boolean(value))),
+    ];
+}
+function collectArtifactLanguages(entries) {
+    return [
+        ...new Set(entries.map((entry) => entry.language).filter((value) => value !== undefined)),
+    ];
+}
+function buildLanguageDiagnostics(entries) {
+    return entries
+        .filter((entry) => Boolean(entry.language) && !SUPPORTED_PREVIEW_LANGUAGES.has(entry.language))
+        .map((entry) => ({
+        code: 'DTAPI_PREVIEW_LANGUAGE_INVALID',
+        severity: 'block',
+        message: `Artifact "${entry.path}" declares unsupported preview language "${entry.language}".`,
+        remediation: 'Use TypeScript or JavaScript for Foundation-compatible devtrack-api preview artifacts, or document a governed exception.',
+        path: entry.path,
+    }));
+}
+function mapFoundationFindingToPreviewDiagnostic(finding) {
+    return {
+        code: finding.code,
+        severity: finding.severity === 'warn' ? 'warn' : 'block',
+        message: finding.message,
+        remediation: finding.remediation,
+        path: finding.path,
+    };
+}
+function computePreviewSignature(preview) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        project_name: preview.project_name,
+        profile: preview.profile,
+        source: preview.source,
+        contexts: preview.contexts,
+        subsystems: preview.subsystems,
+        transports: preview.transports,
+        tree: preview.tree,
+        foundation_tests_projection: preview.foundation_tests_projection,
+        runtime_scripts_projection: preview.runtime_scripts_projection,
+        application_only_contexts: preview.application_only_contexts,
+        context_classification: preview.context_classification,
+        contract_pack_refs: preview.contract_pack_refs,
+        diagnostics: preview.diagnostics.map((item) => ({ code: item.code, path: item.path, severity: item.severity })),
+        artifact_languages: preview.artifact_languages,
+    }))
+        .digest('hex');
+}
+function computeGateSignature(preview, exceptionRefs) {
+    return createHash('sha256')
+        .update(JSON.stringify({
+        preview_signature: preview.material_signature,
+        profile: preview.profile,
+        contract_pack_refs: preview.contract_pack_refs,
+        exception_refs: [...exceptionRefs].sort(),
+    }))
+        .digest('hex');
+}
 //# sourceMappingURL=package-structure-gate.js.map