@devtrack-solution/codesdd 1.2.2 → 1.2.4-rc3

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

@@ -0,0 +1,280 @@
+import { buildPluginRuntimeInvocationPlan, pluginArtifactManifestSchema, } from './plugin-broker.js';
+import { pluginManifestSchema } from './plugin-manifest.js';
+import { createPluginRegistryState } from './plugin-registry.js';
+export const DEVTRACK_API_APPLIANCE_PLUGIN_ID = 'codesdd-plugin-devtrack-api';
+export const DEVTRACK_API_APPLIANCE_CAPABILITIES = [
+    'scaffold.project',
+    'generate.domain',
+    'generate.crud',
+    'validate.structure',
+    'evidence.emit',
+];
+const REQUIRED_ARTIFACT_WRITES = ['src', 'tests', 'docs', '.sdd/plugin-evidence'];
+const REQUIRED_FORBIDDEN_WRITES = ['.git', 'node_modules', '.env', '.sdd/state'];
+const DEVTRACK_API_REFERENCE_ROOT = '/Volumes/WORKSPACE/DEVTRACK_TOOLS/devtrack-foundation-api';
+const DEVTRACK_API_SCAFFOLD_CAPABILITY = 'scaffold.project';
+const DEVTRACK_API_SCAFFOLD_WRITE_SCOPE = [
+    'src',
+    'tests',
+    'docs',
+    'package.json',
+    'tsconfig.json',
+    'nest-cli.json',
+    'eslint.config.mjs',
+];
+export function evaluateDevTrackApiApplianceConformance(manifest) {
+    const parsed = pluginManifestSchema.parse(manifest);
+    const capabilityNames = parsed.capabilities.map((capability) => capability.name);
+    const missingCapabilities = DEVTRACK_API_APPLIANCE_CAPABILITIES.filter((capability) => !capabilityNames.includes(capability));
+    const missingArtifactWrites = REQUIRED_ARTIFACT_WRITES.filter((scope) => !parsed.artifacts.writes.includes(scope));
+    const missingForbiddenWrites = REQUIRED_FORBIDDEN_WRITES.filter((scope) => !parsed.artifacts.forbidden_writes.includes(scope));
+    const serialized = JSON.stringify(parsed).toLowerCase();
+    const typeormOnly = serialized.includes('typeorm') && !serialized.includes('prisma');
+    const issues = [
+        ...collectIdentityIssues(parsed),
+        ...missingCapabilities.map((capability) => `Missing required capability: ${capability}.`),
+        ...missingArtifactWrites.map((scope) => `Missing required artifact write scope: ${scope}.`),
+        ...missingForbiddenWrites.map((scope) => `Missing required forbidden write scope: ${scope}.`),
+        ...(typeormOnly ? [] : ['DevTrack API appliance must declare TypeORM-only persistence and must not mention Prisma.']),
+    ];
+    return {
+        valid: issues.length === 0,
+        plugin_id: parsed.id,
+        capability_names: capabilityNames,
+        missing_capabilities: missingCapabilities,
+        missing_artifact_writes: missingArtifactWrites,
+        missing_forbidden_writes: missingForbiddenWrites,
+        typeorm_only: typeormOnly,
+        issues,
+    };
+}
+export function buildDevTrackApiScaffoldDryRunPlan(manifest, input) {
+    const parsed = pluginManifestSchema.parse(manifest);
+    const createdAt = input.created_at ?? new Date().toISOString();
+    const packageName = normalizePackageName(input.package_name ?? input.project_name);
+    const conformance = evaluateDevTrackApiApplianceConformance(parsed);
+    if (!conformance.valid) {
+        return {
+            schema_version: 1,
+            status: 'invalid',
+            created_at: createdAt,
+            project_name: input.project_name,
+            package_name: packageName,
+            artifacts: [],
+            issues: conformance.issues,
+        };
+    }
+    const artifacts = buildScaffoldArtifacts();
+    const runtimePlan = buildRuntimePlan(parsed, input, packageName, createdAt, artifacts);
+    if (runtimePlan.status !== 'ready' || !runtimePlan.envelope) {
+        return {
+            schema_version: 1,
+            status: runtimePlan.status === 'blocked' ? 'blocked' : 'unresolved',
+            created_at: createdAt,
+            operation_id: runtimePlan.envelope?.operation_id,
+            project_name: input.project_name,
+            package_name: packageName,
+            runtime_plan: runtimePlan,
+            artifacts: [],
+            issues: runtimePlan.reasons,
+        };
+    }
+    const operationId = runtimePlan.envelope.operation_id;
+    const pluginRef = {
+        id: parsed.id,
+        version: parsed.version,
+    };
+    return {
+        schema_version: 1,
+        status: 'planned',
+        created_at: createdAt,
+        operation_id: operationId,
+        project_name: input.project_name,
+        package_name: packageName,
+        runtime_plan: runtimePlan,
+        artifacts,
+        artifact_manifest: pluginArtifactManifestSchema.parse({
+            schema_version: 1,
+            operation_id: operationId,
+            generated_at: createdAt,
+            feature_ref: input.feature_ref,
+            plugin_ref: pluginRef,
+            capability: DEVTRACK_API_SCAFFOLD_CAPABILITY,
+            mode: 'dry-run',
+            status: 'planned',
+            artifacts: artifacts.map((artifact) => ({
+                path: artifact.path,
+                operation: artifact.operation,
+                reason: artifact.reason,
+                content_type: artifact.content_type,
+                artifact_kind: artifact.artifact_kind,
+                role: artifact.role,
+                layer: artifact.layer,
+                language: artifact.language,
+                implementation: artifact.implementation,
+                decision_refs: artifact.decision_refs,
+                source_refs: [artifact.source_reference],
+                tags: artifact.tags,
+            })),
+            validation_evidence: parsed.validation.commands.map((command) => ({
+                command,
+                status: 'pending',
+            })),
+        }),
+        evidence_manifest: buildEvidenceManifest({
+            operationId,
+            createdAt,
+            featureRef: input.feature_ref,
+            pluginRef,
+            projectName: input.project_name,
+            packageName,
+            validationCommands: parsed.validation.commands,
+        }),
+        issues: [],
+    };
+}
+function collectIdentityIssues(manifest) {
+    const issues = [];
+    if (manifest.id !== DEVTRACK_API_APPLIANCE_PLUGIN_ID) {
+        issues.push(`Plugin id must be ${DEVTRACK_API_APPLIANCE_PLUGIN_ID}.`);
+    }
+    if (manifest.technology.language !== 'typescript') {
+        issues.push('DevTrack API appliance language must be typescript.');
+    }
+    if (manifest.technology.framework !== 'nestjs') {
+        issues.push('DevTrack API appliance framework must be nestjs.');
+    }
+    return issues;
+}
+function buildRuntimePlan(manifest, input, packageName, createdAt, artifacts) {
+    const registry = createPluginRegistryState([
+        {
+            manifest,
+            source: {
+                type: 'workspace',
+                uri: 'test/fixtures/plugins/devtrack-api/codesdd-plugin.yaml',
+                checksum: manifest.supply_chain.checksum,
+            },
+            registered_at: createdAt,
+        },
+    ], createdAt);
+    return buildPluginRuntimeInvocationPlan(registry, {
+        feature_ref: input.feature_ref,
+        capability: DEVTRACK_API_SCAFFOLD_CAPABILITY,
+        skill_ref: 'devtrack-api',
+        inputs: {
+            project_name: input.project_name,
+            package_name: packageName,
+            persistence: {
+                provider: 'typeorm',
+            },
+        },
+        technology: {
+            language: 'typescript',
+            framework: 'nestjs',
+        },
+        requested_write_scope: input.requested_write_scope ?? [...DEVTRACK_API_SCAFFOLD_WRITE_SCOPE],
+        require_apply: false,
+        planned_writes: artifacts.map((artifact) => artifact.path),
+        requested_env: ['CI'],
+        approval_grants: [],
+        network_domains: [],
+        process_spawn_requested: false,
+        filesystem_checks: [],
+        mode: 'dry-run',
+        operation_id: input.operation_id,
+        created_at: createdAt,
+    });
+}
+function buildEvidenceManifest(input) {
+    return {
+        schema_version: 1,
+        operation_id: input.operationId,
+        generated_at: input.createdAt,
+        feature_ref: input.featureRef,
+        plugin_ref: input.pluginRef,
+        capability: DEVTRACK_API_SCAFFOLD_CAPABILITY,
+        status: 'planned',
+        project_name: input.projectName,
+        package_name: input.packageName,
+        foundation_reference: {
+            repository: DEVTRACK_API_REFERENCE_ROOT,
+            architecture_doc: `${DEVTRACK_API_REFERENCE_ROOT}/arquitetura.md`,
+            derived_structure_doc: 'docs/foundation-backend-reference-structure.md',
+            skill_ref: 'devtrack-api',
+        },
+        validation_commands: input.validationCommands.map((command) => ({
+            command,
+            status: 'pending',
+        })),
+        quality_gates: [
+            'typeorm-only-persistence',
+            'no-secret-fixtures',
+            'no-out-of-root-writes',
+            'artifact-manifest-required',
+            'evidence-manifest-required',
+        ],
+    };
+}
+function buildScaffoldArtifacts() {
+    return [
+        artifact('package.json', 'root', 'package-metadata', 'manifest', 'application/json', 'Foundation-compatible package metadata, scripts, and dependencies.'),
+        artifact('tsconfig.json', 'config', 'configuration', 'manifest', 'application/json', 'TypeScript path aliases and compiler settings aligned to Foundation API.'),
+        artifact('nest-cli.json', 'config', 'configuration', 'manifest', 'application/json', 'Nest CLI configuration with Swagger plugin support.'),
+        artifact('eslint.config.mjs', 'config', 'configuration', 'policy', 'text/javascript', 'Foundation-compatible lint rules and import-boundary checks.'),
+        artifact('docs/foundation-backend-reference-structure.md', 'docs', 'documentation', 'documentation', 'text/markdown', 'Derived Foundation package structure reference for maintainers.'),
+        artifact('src/main.ts', 'root', 'source', 'implementation', 'text/typescript', 'NestJS bootstrap entrypoint.'),
+        artifact('src/app.module.ts', 'root', 'source', 'module', 'text/typescript', 'Root module composing application, infrastructure, and presentation layers.'),
+        artifact('src/application/application.module.ts', 'application', 'source', 'module', 'text/typescript', 'Application layer module boundary.'),
+        artifact('src/application/runtime-settings.ts', 'application', 'source', 'type', 'text/typescript', 'Application runtime settings boundary.'),
+        artifact('src/domain/auth/business-objects/api-keys.bo.ts', 'domain', 'source', 'business-object', 'text/typescript', 'Initial BO-pattern domain object example from Foundation API.'),
+        artifact('src/application/business/auth/ports/out/api-key-repository.port.ts', 'application', 'source', 'repository-port', 'text/typescript', 'BO-pattern repository port owned by application ports/out.'),
+        artifact('src/infrastructure/infrastructure.module.ts', 'infrastructure', 'source', 'module', 'text/typescript', 'Infrastructure layer module boundary.'),
+        artifact('src/infrastructure/settings/app-configuration.ts', 'infrastructure', 'source', 'implementation', 'text/typescript', 'Typed application configuration source.'),
+        artifact('src/infrastructure/adapters/orm/entities/api-key.orm-entity.ts', 'infrastructure', 'source', 'entity', 'text/typescript', 'TypeORM persistence entity kept in the centralized orm subsystem.'),
+        artifact('src/presentation/presentation.module.ts', 'presentation', 'source', 'module', 'text/typescript', 'Presentation layer module boundary.'),
+        artifact('src/presentation/rest/rest.presentation.module.ts', 'presentation', 'source', 'module', 'text/typescript', 'REST channel module boundary.'),
+        artifact('src/presentation/graphql/graphql.presentation.module.ts', 'presentation', 'source', 'module', 'text/typescript', 'GraphQL channel module boundary.'),
+        artifact('src/presentation/cli/cli.presentation.module.ts', 'presentation', 'source', 'module', 'text/typescript', 'CLI channel module boundary.'),
+        artifact('src/presentation/websocket/websocket.module.ts', 'presentation', 'source', 'module', 'text/typescript', 'WebSocket channel module boundary.'),
+        artifact('src/shared/domain/generic-business-object.ts', 'shared', 'source', 'abstraction', 'text/typescript', 'Shared domain primitive used by Foundation packages.'),
+        artifact('src/shared/presentation/generic-controller.ts', 'shared', 'source', 'abstraction', 'text/typescript', 'Shared presentation primitive used by REST controllers.'),
+        artifact('tests/app.e2e-spec.ts', 'tests', 'test', 'test', 'text/typescript', 'Initial E2E smoke test for the generated API scaffold.'),
+        artifact('tests/jest-e2e.json', 'tests', 'configuration', 'manifest', 'application/json', 'Jest E2E configuration for the scaffold.'),
+    ];
+}
+function artifact(artifactPath, layer, artifactKind, role, contentType, reason) {
+    const mapEntry = {
+        path: artifactPath,
+        layer,
+        operation: 'planned',
+        artifact_kind: artifactKind,
+        role,
+        content_type: contentType,
+        reason,
+        language: contentType.includes('typescript') || contentType.includes('javascript') ? 'typescript' : undefined,
+        implementation: role === 'interface' || role === 'repository-port' ? 'contract' : 'generated',
+        decision_refs: ['EPIC-0075'],
+        source_refs: [`${DEVTRACK_API_REFERENCE_ROOT}/${artifactPath}`],
+        tags: ['devtrack-api', 'foundation-api'],
+        metadata: {},
+    };
+    return {
+        ...mapEntry,
+        source_reference: `${DEVTRACK_API_REFERENCE_ROOT}/${artifactPath}`,
+        decision_refs: mapEntry.decision_refs,
+        tags: mapEntry.tags,
+    };
+}
+function normalizePackageName(value) {
+    const normalized = value
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/gu, '-')
+        .replace(/^-+|-+$/gu, '');
+    if (!normalized) {
+        throw new Error('DevTrack API scaffold package name cannot be empty.');
+    }
+    return normalized;
+}
+//# sourceMappingURL=devtrack-api-appliance.js.map

package/dist/core/sdd/devtrack-api-architecture.d.ts

@@ -0,0 +1,31 @@
+import { type QualityArchitectureSchema, type QualityImportGraph } from './quality-validation.js';
+export declare const DEVTRACK_API_ARCHITECTURE_SCHEMA_ID = "ARCH-GATE-devtrack-api-p0";
+export type DevTrackApiArchitectureIssueCode = 'ARCH_RELATIVE_IMPORT_FORBIDDEN' | 'ARCH_DOMAIN_FORBIDDEN_IMPORT' | 'ARCH_DOMAIN_OUTER_LAYER_IMPORT' | 'ARCH_PRISMA_FORBIDDEN' | 'ARCH_PRISMA_IMPORT_FORBIDDEN' | 'ARCH_PRISMA_FILE_FORBIDDEN' | 'ARCH_APPLICATION_PRESENTATION_IMPORT' | 'ARCH_APPLICATION_CONCRETE_INFRA_IMPORT' | 'ARCH_PRESENTATION_INFRA_IMPORT' | 'ARCH_TYPEORM_IMPORT_OUTSIDE_INFRASTRUCTURE' | 'ARCH_ENTITY_OUTSIDE_INFRASTRUCTURE' | 'ARCH_REPOSITORY_OUTSIDE_INFRASTRUCTURE' | 'ARCH_TYPEORM_ENTITY_PATH_INVALID' | 'ARCH_TYPEORM_ENTITY_SUFFIX_INVALID' | 'ARCH_TYPEORM_REPOSITORY_PATH_INVALID' | 'ARCH_TYPEORM_REPOSITORY_SUFFIX_INVALID' | 'ARCH_DOMAIN_ENTITY_CONTEXT_FORBIDDEN' | 'ARCH_DOMAIN_REPOSITORY_PORT_CONTEXT_FORBIDDEN' | 'ARCH_DOMAIN_EXCEPTION_PATH_FORBIDDEN' | 'ARCH_VALUE_OBJECT_SUFFIX_INVALID' | 'ARCH_PRESENTATION_TRANSPORT_MISSING' | 'ARCH_INFRASTRUCTURE_CONTEXT_ADAPTER_FORBIDDEN' | 'ARCH_INFRASTRUCTURE_CONTEXT_PERSISTENCE_FORBIDDEN' | 'ARCH_TYPEORM_REPOSITORY_FAKE' | 'ARCH_PRESENTATION_COMPOSITION_ROOT' | 'ARCH_AGGREGATE_MODULE_MISSING' | 'ARCH_AGGREGATE_MODULE_NOT_NESTJS' | 'ARCH_PORT_MISSING_SYMBOL' | 'ARCH_PORT_GROUPED_UNRELATED' | 'ARCH_BO_MISSING_METHODS' | 'ARCH_VO_MISSING_METHODS' | 'ARCH_MISSING_DATASOURCE' | 'ARCH_MISSING_MIGRATIONS' | 'ARCH_MISSING_TYPEORM_MODULE_FORFEATURE';
+export interface DevTrackApiArchitectureFinding {
+    code: DevTrackApiArchitectureIssueCode;
+    severity: 'warn';
+    path?: string;
+    import_specifier?: string;
+    message: string;
+    remediation: string;
+}
+export interface CollectDevTrackApiImportGraphInput {
+    projectRoot: string;
+    sourceRoots?: string[];
+    sourceRoot?: string;
+    files?: string[];
+    collector?: 'typescript' | 'text';
+}
+export interface ValidateDevTrackApiArchitectureInput extends CollectDevTrackApiImportGraphInput {
+    importGraph?: QualityImportGraph;
+}
+export interface DevTrackApiArchitectureValidationResult {
+    status: 'passed' | 'warning';
+    architecture_schema: QualityArchitectureSchema;
+    import_graph: QualityImportGraph;
+    findings: DevTrackApiArchitectureFinding[];
+}
+export declare function buildDevTrackApiArchitectureSchema(): QualityArchitectureSchema;
+export declare function collectDevTrackApiImportGraph(input: CollectDevTrackApiImportGraphInput): Promise<QualityImportGraph>;
+export declare function validateDevTrackApiArchitecture(input: ValidateDevTrackApiArchitectureInput): Promise<DevTrackApiArchitectureValidationResult>;
+//# sourceMappingURL=devtrack-api-architecture.d.ts.map