@devtrack-solution/codesdd 1.2.4-rc3 → 1.2.4

package/dist/core/sdd/reversa-evidence.d.ts

@@ -0,0 +1,298 @@
+import { z } from 'zod';
+export declare const reversaEvidencePhaseSchema: z.ZodEnum<{
+    architecture: "architecture";
+    surface: "surface";
+    rules: "rules";
+    data: "data";
+    migration: "migration";
+    equivalence: "equivalence";
+    intake: "intake";
+    ux: "ux";
+    artifact_generation: "artifact_generation";
+    reconstruction: "reconstruction";
+}>;
+export declare const reversaConfidenceSchema: z.ZodEnum<{
+    unknown: "unknown";
+    low: "low";
+    medium: "medium";
+    high: "high";
+}>;
+export declare const reversaSourceAttestationSchema: z.ZodObject<{
+    source_ref: z.ZodString;
+    source_type: z.ZodEnum<{
+        config: "config";
+        repository: "repository";
+        document: "document";
+        runtime_log: "runtime_log";
+        database_schema: "database_schema";
+        manual_note: "manual_note";
+    }>;
+    trust_level: z.ZodEnum<{
+        trusted: "trusted";
+        untrusted: "untrusted";
+        hostile: "hostile";
+    }>;
+    sha256: z.ZodOptional<z.ZodString>;
+    redaction_status: z.ZodEnum<{
+        blocked: "blocked";
+        redacted: "redacted";
+        not_required: "not_required";
+    }>;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const reversaEvidenceFindingSchema: z.ZodObject<{
+    id: z.ZodString;
+    phase: z.ZodEnum<{
+        architecture: "architecture";
+        surface: "surface";
+        rules: "rules";
+        data: "data";
+        migration: "migration";
+        equivalence: "equivalence";
+        intake: "intake";
+        ux: "ux";
+        artifact_generation: "artifact_generation";
+        reconstruction: "reconstruction";
+    }>;
+    title: z.ZodString;
+    summary: z.ZodString;
+    confidence: z.ZodEnum<{
+        unknown: "unknown";
+        low: "low";
+        medium: "medium";
+        high: "high";
+    }>;
+    source_refs: z.ZodArray<z.ZodString>;
+    contradiction_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    promoted_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export declare const reversaEvidenceArtifactSchema: z.ZodObject<{
+    path: z.ZodString;
+    artifact_type: z.ZodEnum<{
+        inventory: "inventory";
+        architecture_map: "architecture_map";
+        business_rules: "business_rules";
+        data_model: "data_model";
+        ux_map: "ux_map";
+        generated_sdd_artifact: "generated_sdd_artifact";
+        migration_plan: "migration_plan";
+        reconstruction_diff: "reconstruction_diff";
+        equivalence_report: "equivalence_report";
+        question_set: "question_set";
+    }>;
+    phase: z.ZodEnum<{
+        architecture: "architecture";
+        surface: "surface";
+        rules: "rules";
+        data: "data";
+        migration: "migration";
+        equivalence: "equivalence";
+        intake: "intake";
+        ux: "ux";
+        artifact_generation: "artifact_generation";
+        reconstruction: "reconstruction";
+    }>;
+    checksum_sha256: z.ZodOptional<z.ZodString>;
+    produced_by: z.ZodString;
+    write_scope: z.ZodEnum<{
+        dry_run: "dry_run";
+        read_only: "read_only";
+        sandbox: "sandbox";
+        approved_apply: "approved_apply";
+    }>;
+}, z.core.$strip>;
+export declare const reversaEvidenceValidationSchema: z.ZodObject<{
+    id: z.ZodString;
+    phase: z.ZodEnum<{
+        architecture: "architecture";
+        surface: "surface";
+        rules: "rules";
+        data: "data";
+        migration: "migration";
+        equivalence: "equivalence";
+        intake: "intake";
+        ux: "ux";
+        artifact_generation: "artifact_generation";
+        reconstruction: "reconstruction";
+    }>;
+    command: z.ZodString;
+    status: z.ZodEnum<{
+        blocked: "blocked";
+        warning: "warning";
+        failed: "failed";
+        passed: "passed";
+        skipped: "skipped";
+    }>;
+    evidence_ref: z.ZodOptional<z.ZodString>;
+    issue_codes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strip>;
+export declare const reversaEvidenceBundleSchema: z.ZodObject<{
+    schema_version: z.ZodLiteral<1>;
+    contract: z.ZodLiteral<"reversa-evidence-bundle/v1">;
+    operation_id: z.ZodString;
+    generated_at: z.ZodString;
+    feature_ref: z.ZodString;
+    mode: z.ZodEnum<{
+        validate: "validate";
+        "read-only": "read-only";
+        plan: "plan";
+        "apply-sandbox": "apply-sandbox";
+        "apply-approved": "apply-approved";
+    }>;
+    source_attestations: z.ZodArray<z.ZodObject<{
+        source_ref: z.ZodString;
+        source_type: z.ZodEnum<{
+            config: "config";
+            repository: "repository";
+            document: "document";
+            runtime_log: "runtime_log";
+            database_schema: "database_schema";
+            manual_note: "manual_note";
+        }>;
+        trust_level: z.ZodEnum<{
+            trusted: "trusted";
+            untrusted: "untrusted";
+            hostile: "hostile";
+        }>;
+        sha256: z.ZodOptional<z.ZodString>;
+        redaction_status: z.ZodEnum<{
+            blocked: "blocked";
+            redacted: "redacted";
+            not_required: "not_required";
+        }>;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    findings: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        phase: z.ZodEnum<{
+            architecture: "architecture";
+            surface: "surface";
+            rules: "rules";
+            data: "data";
+            migration: "migration";
+            equivalence: "equivalence";
+            intake: "intake";
+            ux: "ux";
+            artifact_generation: "artifact_generation";
+            reconstruction: "reconstruction";
+        }>;
+        title: z.ZodString;
+        summary: z.ZodString;
+        confidence: z.ZodEnum<{
+            unknown: "unknown";
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        source_refs: z.ZodArray<z.ZodString>;
+        contradiction_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        promoted_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    }, z.core.$strip>>>;
+    artifacts: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        path: z.ZodString;
+        artifact_type: z.ZodEnum<{
+            inventory: "inventory";
+            architecture_map: "architecture_map";
+            business_rules: "business_rules";
+            data_model: "data_model";
+            ux_map: "ux_map";
+            generated_sdd_artifact: "generated_sdd_artifact";
+            migration_plan: "migration_plan";
+            reconstruction_diff: "reconstruction_diff";
+            equivalence_report: "equivalence_report";
+            question_set: "question_set";
+        }>;
+        phase: z.ZodEnum<{
+            architecture: "architecture";
+            surface: "surface";
+            rules: "rules";
+            data: "data";
+            migration: "migration";
+            equivalence: "equivalence";
+            intake: "intake";
+            ux: "ux";
+            artifact_generation: "artifact_generation";
+            reconstruction: "reconstruction";
+        }>;
+        checksum_sha256: z.ZodOptional<z.ZodString>;
+        produced_by: z.ZodString;
+        write_scope: z.ZodEnum<{
+            dry_run: "dry_run";
+            read_only: "read_only";
+            sandbox: "sandbox";
+            approved_apply: "approved_apply";
+        }>;
+    }, z.core.$strip>>>;
+    validations: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        phase: z.ZodEnum<{
+            architecture: "architecture";
+            surface: "surface";
+            rules: "rules";
+            data: "data";
+            migration: "migration";
+            equivalence: "equivalence";
+            intake: "intake";
+            ux: "ux";
+            artifact_generation: "artifact_generation";
+            reconstruction: "reconstruction";
+        }>;
+        command: z.ZodString;
+        status: z.ZodEnum<{
+            blocked: "blocked";
+            warning: "warning";
+            failed: "failed";
+            passed: "passed";
+            skipped: "skipped";
+        }>;
+        evidence_ref: z.ZodOptional<z.ZodString>;
+        issue_codes: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    }, z.core.$strip>>>;
+    contradictions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        finding_refs: z.ZodArray<z.ZodString>;
+        summary: z.ZodString;
+        resolution_status: z.ZodEnum<{
+            accepted_risk: "accepted_risk";
+            resolved: "resolved";
+            open: "open";
+        }>;
+    }, z.core.$strip>>>;
+    human_questions: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        question: z.ZodString;
+        blocks_phase: z.ZodOptional<z.ZodEnum<{
+            architecture: "architecture";
+            surface: "surface";
+            rules: "rules";
+            data: "data";
+            migration: "migration";
+            equivalence: "equivalence";
+            intake: "intake";
+            ux: "ux";
+            artifact_generation: "artifact_generation";
+            reconstruction: "reconstruction";
+        }>>;
+        required_before_apply: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strip>>>;
+    quality_refs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    residual_risks: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        code: z.ZodString;
+        severity: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+            critical: "critical";
+        }>;
+        description: z.ZodString;
+        mitigation: z.ZodString;
+    }, z.core.$strip>>>;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+export type ReversaEvidenceBundle = z.infer<typeof reversaEvidenceBundleSchema>;
+export type ReversaEvidencePhase = z.infer<typeof reversaEvidencePhaseSchema>;
+export type ReversaSourceAttestation = z.infer<typeof reversaSourceAttestationSchema>;
+export declare function parseReversaEvidenceBundle(input: unknown): ReversaEvidenceBundle;
+//# sourceMappingURL=reversa-evidence.d.ts.map

package/dist/core/sdd/reversa-evidence.js

@@ -0,0 +1,118 @@
+import { z } from 'zod';
+const FEATURE_REF_PATTERN = /^FEAT-\d{4}$/;
+const OPERATION_ID_PATTERN = /^[a-z0-9][a-z0-9-]*$/;
+const WINDOWS_ABSOLUTE_PATH_PATTERN = /^[A-Za-z]:[\\/]/;
+const jsonObjectSchema = z.record(z.string(), z.unknown());
+const safeRelativePathSchema = z
+    .string()
+    .min(1)
+    .refine((value) => isSafeRelativePath(value), {
+    message: 'Path must be relative to the project root and must not contain traversal segments.',
+});
+export const reversaEvidencePhaseSchema = z.enum([
+    'intake',
+    'surface',
+    'architecture',
+    'rules',
+    'data',
+    'ux',
+    'artifact_generation',
+    'migration',
+    'reconstruction',
+    'equivalence',
+]);
+export const reversaConfidenceSchema = z.enum(['high', 'medium', 'low', 'unknown']);
+export const reversaSourceAttestationSchema = z.object({
+    source_ref: safeRelativePathSchema,
+    source_type: z.enum(['repository', 'document', 'config', 'runtime_log', 'database_schema', 'manual_note']),
+    trust_level: z.enum(['trusted', 'untrusted', 'hostile']),
+    sha256: z.string().min(1).optional(),
+    redaction_status: z.enum(['not_required', 'redacted', 'blocked']),
+    notes: z.string().min(1).optional(),
+});
+export const reversaEvidenceFindingSchema = z.object({
+    id: z.string().regex(/^REV-FIND-[A-Z0-9-]+$/),
+    phase: reversaEvidencePhaseSchema,
+    title: z.string().min(1),
+    summary: z.string().min(1),
+    confidence: reversaConfidenceSchema,
+    source_refs: z.array(safeRelativePathSchema).min(1),
+    contradiction_refs: z.array(z.string().min(1)).default([]),
+    promoted_refs: z.array(z.string().min(1)).default([]),
+    metadata: jsonObjectSchema.default({}),
+});
+export const reversaEvidenceArtifactSchema = z.object({
+    path: safeRelativePathSchema,
+    artifact_type: z.enum([
+        'inventory',
+        'architecture_map',
+        'business_rules',
+        'data_model',
+        'ux_map',
+        'generated_sdd_artifact',
+        'migration_plan',
+        'reconstruction_diff',
+        'equivalence_report',
+        'question_set',
+    ]),
+    phase: reversaEvidencePhaseSchema,
+    checksum_sha256: z.string().min(1).optional(),
+    produced_by: z.string().min(1),
+    write_scope: z.enum(['read_only', 'dry_run', 'sandbox', 'approved_apply']),
+});
+export const reversaEvidenceValidationSchema = z.object({
+    id: z.string().regex(/^REV-VAL-[A-Z0-9-]+$/),
+    phase: reversaEvidencePhaseSchema,
+    command: z.string().min(1),
+    status: z.enum(['passed', 'warning', 'failed', 'blocked', 'skipped']),
+    evidence_ref: safeRelativePathSchema.optional(),
+    issue_codes: z.array(z.string().regex(/^[A-Z][A-Z0-9_]*$/)).default([]),
+});
+export const reversaEvidenceBundleSchema = z.object({
+    schema_version: z.literal(1),
+    contract: z.literal('reversa-evidence-bundle/v1'),
+    operation_id: z.string().regex(OPERATION_ID_PATTERN),
+    generated_at: z.string().datetime(),
+    feature_ref: z.string().regex(FEATURE_REF_PATTERN),
+    mode: z.enum(['read-only', 'plan', 'validate', 'apply-sandbox', 'apply-approved']),
+    source_attestations: z.array(reversaSourceAttestationSchema).min(1),
+    findings: z.array(reversaEvidenceFindingSchema).default([]),
+    artifacts: z.array(reversaEvidenceArtifactSchema).default([]),
+    validations: z.array(reversaEvidenceValidationSchema).default([]),
+    contradictions: z
+        .array(z.object({
+        id: z.string().regex(/^REV-CONTRA-[A-Z0-9-]+$/),
+        finding_refs: z.array(z.string().min(1)).min(2),
+        summary: z.string().min(1),
+        resolution_status: z.enum(['open', 'resolved', 'accepted_risk']),
+    }))
+        .default([]),
+    human_questions: z
+        .array(z.object({
+        id: z.string().regex(/^REV-Q-[A-Z0-9-]+$/),
+        question: z.string().min(1),
+        blocks_phase: reversaEvidencePhaseSchema.optional(),
+        required_before_apply: z.boolean().default(false),
+    }))
+        .default([]),
+    quality_refs: z.array(safeRelativePathSchema).default([]),
+    residual_risks: z
+        .array(z.object({
+        code: z.string().regex(/^[A-Z][A-Z0-9_]*$/),
+        severity: z.enum(['low', 'medium', 'high', 'critical']),
+        description: z.string().min(1),
+        mitigation: z.string().min(1),
+    }))
+        .default([]),
+    metadata: jsonObjectSchema.default({}),
+});
+export function parseReversaEvidenceBundle(input) {
+    return reversaEvidenceBundleSchema.parse(input);
+}
+function isSafeRelativePath(value) {
+    if (value.startsWith('/') || WINDOWS_ABSOLUTE_PATH_PATTERN.test(value)) {
+        return false;
+    }
+    return !value.split(/[\\/]+/u).some((segment) => segment === '..');
+}
+//# sourceMappingURL=reversa-evidence.js.map

package/dist/core/sdd/reversa-reconstruction.d.ts

@@ -0,0 +1,29 @@
+import type { ReversaArtifactWritePlan } from './reversa-artifact-writer.js';
+export interface ReversaReconstructionPlan {
+    schema_version: 1;
+    contract: 'reversa-reconstruction-plan/v1';
+    feature_ref: string;
+    mode: 'apply-sandbox' | 'apply-approved';
+    status: 'ready' | 'blocked';
+    migration_steps: Array<{
+        id: string;
+        description: string;
+        evidence_ref: string;
+    }>;
+    sandbox_writes: Array<{
+        path: string;
+        source_draft_ref: string;
+    }>;
+    rollback_manifest: {
+        required: true;
+        path: string;
+        rollback_steps: string[];
+    };
+    blocked_reasons: string[];
+}
+export declare function buildReversaReconstructionPlan(input: {
+    writePlan: ReversaArtifactWritePlan;
+    mode: 'apply-sandbox' | 'apply-approved';
+    approval?: 'reversa-apply';
+}): ReversaReconstructionPlan;
+//# sourceMappingURL=reversa-reconstruction.d.ts.map

package/dist/core/sdd/reversa-reconstruction.js

@@ -0,0 +1,32 @@
+export function buildReversaReconstructionPlan(input) {
+    const blockedReasons = [];
+    if (input.writePlan.status === 'needs_clarification') {
+        blockedReasons.push('Human clarification is required before reconstruction.');
+    }
+    if (input.mode === 'apply-approved' && input.approval !== 'reversa-apply') {
+        blockedReasons.push('apply-approved reconstruction requires reversa-apply approval.');
+    }
+    return {
+        schema_version: 1,
+        contract: 'reversa-reconstruction-plan/v1',
+        feature_ref: input.writePlan.feature_ref,
+        mode: input.mode,
+        status: blockedReasons.length === 0 ? 'ready' : 'blocked',
+        migration_steps: input.writePlan.draft_artifacts.map((artifact, index) => ({
+            id: `REV-MIG-${String(index + 1).padStart(3, '0')}`,
+            description: `Review and reconstruct ${artifact.title} from ${artifact.source_finding_ref}.`,
+            evidence_ref: artifact.path,
+        })),
+        sandbox_writes: input.writePlan.draft_artifacts.map((artifact) => ({
+            path: `.sdd/evidence/reversa/${input.writePlan.feature_ref}/sandbox/${artifact.source_finding_ref.toLowerCase()}.yaml`,
+            source_draft_ref: artifact.path,
+        })),
+        rollback_manifest: {
+            required: true,
+            path: `.sdd/evidence/reversa/${input.writePlan.feature_ref}/rollback-manifest.yaml`,
+            rollback_steps: ['remove sandbox writes', 'restore previous generated drafts', 'rerun equivalence gate'],
+        },
+        blocked_reasons: blockedReasons,
+    };
+}
+//# sourceMappingURL=reversa-reconstruction.js.map

package/dist/core/sdd/reversa-rules-extractor.d.ts

@@ -0,0 +1,12 @@
+import type { ReversaEvidenceBundle } from './reversa-evidence.js';
+export interface ReversaRuleSource {
+    path: string;
+    content: string;
+}
+export declare function buildReversaRulesInventory(input: {
+    featureRef: string;
+    operationId: string;
+    generatedAt: string;
+    sources: ReversaRuleSource[];
+}): ReversaEvidenceBundle;
+//# sourceMappingURL=reversa-rules-extractor.d.ts.map

package/dist/core/sdd/reversa-rules-extractor.js

@@ -0,0 +1,86 @@
+import { attestReversaSource } from './reversa-source-safety.js';
+export function buildReversaRulesInventory(input) {
+    const accepted = input.sources
+        .map((source) => ({ source, attestation: attestReversaSource({ sourcePath: source.path, content: source.content }) }))
+        .filter((entry) => entry.attestation.status === 'accepted' && entry.attestation.attestation);
+    const blockedCount = input.sources.length - accepted.length;
+    const rules = accepted.flatMap(({ source, attestation }) => scanRules(attestation.normalized_path, source.content));
+    const workflows = accepted.flatMap(({ source, attestation }) => scanWorkflows(attestation.normalized_path, source.content));
+    const findings = [];
+    if (rules.length > 0) {
+        findings.push({
+            id: 'REV-FIND-RULES-INVARIANTS',
+            phase: 'rules',
+            title: 'Business rules and invariants',
+            summary: `Detected ${rules.length} rule, validation or invariant candidates.`,
+            confidence: 'medium',
+            source_refs: unique(rules.map((entry) => entry.source_ref)),
+            contradiction_refs: [],
+            promoted_refs: [],
+            metadata: { rules },
+        });
+    }
+    if (workflows.length > 0) {
+        findings.push({
+            id: 'REV-FIND-RULES-WORKFLOWS',
+            phase: 'rules',
+            title: 'Workflow transitions',
+            summary: `Detected ${workflows.length} workflow or state transition candidates.`,
+            confidence: 'medium',
+            source_refs: unique(workflows.map((entry) => entry.source_ref)),
+            contradiction_refs: [],
+            promoted_refs: [],
+            metadata: { workflows },
+        });
+    }
+    return {
+        schema_version: 1,
+        contract: 'reversa-evidence-bundle/v1',
+        operation_id: input.operationId,
+        generated_at: input.generatedAt,
+        feature_ref: input.featureRef,
+        mode: 'read-only',
+        source_attestations: accepted.map((entry) => entry.attestation.attestation),
+        findings,
+        artifacts: [{
+                path: `.sdd/evidence/reversa/${input.featureRef}/business-rules.yaml`,
+                artifact_type: 'business_rules',
+                phase: 'rules',
+                produced_by: 'codesdd reversa rules extractor',
+                write_scope: 'read_only',
+            }],
+        validations: [{
+                id: 'REV-VAL-RULES-SAFETY',
+                phase: 'rules',
+                command: 'buildReversaRulesInventory',
+                status: blockedCount === 0 ? 'passed' : 'blocked',
+                issue_codes: blockedCount === 0 ? [] : ['UNSAFE_SOURCE_BLOCKED'],
+            }],
+        contradictions: [],
+        human_questions: rules.length === 0 ? [{
+                id: 'REV-Q-RULES-MISSING',
+                question: 'No explicit business rules were detected. Which workflows or invariants should be reviewed manually?',
+                blocks_phase: 'artifact_generation',
+                required_before_apply: true,
+            }] : [],
+        quality_refs: [`.sdd/active/${input.featureRef}/5-quality.yaml`],
+        residual_risks: [],
+        metadata: { rule_count: rules.length, workflow_count: workflows.length },
+    };
+}
+function scanRules(sourceRef, content) {
+    return [...content.matchAll(/\b(?:if|validate|ensure|invariant|policy|rule|throw new)\b[^\n;]*/giu)].map((match) => ({
+        expression: match[0].trim(),
+        source_ref: sourceRef,
+    }));
+}
+function scanWorkflows(sourceRef, content) {
+    return [...content.matchAll(/\b(?:status|state|stage)\s*=\s*['"]?([A-Za-z0-9_-]+)['"]?/giu)].map((match) => ({
+        state: match[1] ?? 'unknown',
+        source_ref: sourceRef,
+    }));
+}
+function unique(values) {
+    return [...new Set(values)];
+}
+//# sourceMappingURL=reversa-rules-extractor.js.map

package/dist/core/sdd/reversa-source-safety.d.ts

@@ -0,0 +1,19 @@
+import { type ReversaSourceAttestation } from './reversa-evidence.js';
+export interface ReversaSourceIntakeInput {
+    sourcePath: string;
+    sourceType?: ReversaSourceAttestation['source_type'];
+    content?: string;
+    trustLevel?: ReversaSourceAttestation['trust_level'];
+}
+export interface ReversaSourceIntakeResult {
+    status: 'accepted' | 'blocked';
+    normalized_path: string | null;
+    reason: string | null;
+    attestation: ReversaSourceAttestation | null;
+    redacted_content?: string;
+}
+export declare function attestReversaSource(input: ReversaSourceIntakeInput): ReversaSourceIntakeResult;
+export declare function normalizeReversaSourcePath(value: string): string | null;
+export declare function redactReversaSensitiveText(value: string): string;
+export declare function isReversaCanonicalStatePath(value: string): boolean;
+//# sourceMappingURL=reversa-source-safety.d.ts.map