@devtrack-solution/codesdd 1.2.2

package/dist/core/sdd/structural-health.js

@@ -0,0 +1,187 @@
+import { z } from 'zod';
+export const STRUCTURAL_HEALTH_TOKENS = {
+    lifecycleDirectories: ['planned', 'active', 'archived'],
+    generatedDirectories: ['planning', 'core'],
+    commandNames: ['diagnose', 'sanitize', 'check', 'audit'],
+    findingSeverities: ['info', 'warning', 'error', 'blocker'],
+    findingCategories: [
+        'lifecycle',
+        'references',
+        'integrity',
+        'boundary',
+        'render',
+        'metadata',
+        'naming',
+    ],
+    sanitizerDispositions: ['safe', 'manual', 'blocked', 'noop'],
+    lifecycleStates: ['planned', 'ready', 'blocked', 'in_progress', 'done', 'archived'],
+    navigationNodeKinds: ['insight', 'debate', 'epic', 'feature', 'frontend_gap', 'tech_debt', 'other'],
+    navigationEdgeKinds: ['origin', 'depends_on', 'produces', 'consumes', 'related'],
+    boundaryViolations: ['none', 'path_traversal', 'symlink_escape', 'absolute_escape', 'out_of_root'],
+};
+const NonEmptyStringSchema = z.string().trim().min(1);
+export const StructuralLifecycleDirectoryTokenSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.lifecycleDirectories);
+export const StructuralGeneratedDirectoryTokenSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.generatedDirectories);
+export const StructuralCommandNameTokenSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.commandNames);
+export const StructuralFindingSeveritySchema = z.enum(STRUCTURAL_HEALTH_TOKENS.findingSeverities);
+export const StructuralFindingCategorySchema = z.enum(STRUCTURAL_HEALTH_TOKENS.findingCategories);
+export const StructuralSanitizerDispositionSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.sanitizerDispositions);
+export const StructuralLifecycleStateTokenSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.lifecycleStates);
+export const StructuralNavigationNodeKindSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.navigationNodeKinds);
+export const StructuralNavigationEdgeKindSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.navigationEdgeKinds);
+export const StructuralBoundaryViolationSchema = z.enum(STRUCTURAL_HEALTH_TOKENS.boundaryViolations);
+export const StructuralTokenRegistrySchema = z.object({
+    lifecycle_directories: z.array(StructuralLifecycleDirectoryTokenSchema).min(1),
+    generated_directories: z.array(StructuralGeneratedDirectoryTokenSchema).min(1),
+    command_names: z.array(StructuralCommandNameTokenSchema).min(1),
+    finding_severities: z.array(StructuralFindingSeveritySchema).min(1),
+    finding_categories: z.array(StructuralFindingCategorySchema).min(1),
+    sanitizer_dispositions: z.array(StructuralSanitizerDispositionSchema).min(1),
+});
+export const StructuralBoundaryPathSchema = z
+    .object({
+    root_path: NonEmptyStringSchema,
+    candidate_path: NonEmptyStringSchema,
+    normalized_path: NonEmptyStringSchema,
+    real_path: NonEmptyStringSchema,
+    is_within_root: z.boolean(),
+    violation: StructuralBoundaryViolationSchema.default('none'),
+})
+    .superRefine((value, ctx) => {
+    if (value.is_within_root && value.violation !== 'none') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Boundary path marked inside root cannot carry a violation token.',
+        });
+    }
+    if (!value.is_within_root && value.violation === 'none') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: 'Boundary path outside root must carry a non-none violation token.',
+        });
+    }
+});
+export const StructuralCommandInvocationSchema = z.object({
+    command: StructuralCommandNameTokenSchema,
+    mode: z.enum(['read', 'dry_run', 'apply']),
+    args: z.record(z.string(), z.unknown()).default({}),
+});
+export const StructuralFindingSchema = z.object({
+    finding_id: z.string().regex(/^SH-[A-Z0-9][A-Z0-9-]{2,}$/),
+    rule_id: z.string().regex(/^SH-RULE-[A-Z0-9][A-Z0-9-]{2,}$/),
+    category: StructuralFindingCategorySchema,
+    severity: StructuralFindingSeveritySchema,
+    summary: NonEmptyStringSchema,
+    evidence: z.record(z.string(), z.unknown()).default({}),
+    location: NonEmptyStringSchema.optional(),
+    sanitizer: z.object({
+        disposition: StructuralSanitizerDispositionSchema,
+        reason: NonEmptyStringSchema,
+        actions: z.array(NonEmptyStringSchema).default([]),
+    }),
+});
+export const StructuralDiagnosticReportSchema = z.object({
+    report_version: z.literal(1),
+    generated_at: NonEmptyStringSchema,
+    root_path: NonEmptyStringSchema,
+    strict: z.boolean().default(false),
+    findings: z.array(StructuralFindingSchema),
+    summary: z.object({
+        total: z.number().int().nonnegative(),
+        by_severity: z.partialRecord(StructuralFindingSeveritySchema, z.number().int().nonnegative()).default({}),
+        by_category: z.partialRecord(StructuralFindingCategorySchema, z.number().int().nonnegative()).default({}),
+    }),
+});
+export const StructuralSanitizerActionSchema = z.object({
+    action_id: z.string().regex(/^SH-ACTION-[A-Z0-9][A-Z0-9-]{2,}$/),
+    finding_id: z.string().regex(/^SH-[A-Z0-9][A-Z0-9-]{2,}$/),
+    disposition: StructuralSanitizerDispositionSchema,
+    operation: z.enum(['mkdir', 'move', 'render', 'register', 'manual_review', 'skip']),
+    from_path: NonEmptyStringSchema.optional(),
+    to_path: NonEmptyStringSchema.optional(),
+    notes: NonEmptyStringSchema.optional(),
+});
+export const StructuralSanitizerRollbackOperationSchema = z.object({
+    operation: z.enum(['noop', 'delete_path', 'move', 'restore_backup']),
+    path: NonEmptyStringSchema.optional(),
+    from_path: NonEmptyStringSchema.optional(),
+    to_path: NonEmptyStringSchema.optional(),
+    backup_path: NonEmptyStringSchema.optional(),
+});
+export const StructuralSanitizerTransactionOperationSchema = z.object({
+    transaction_action_id: z.string().regex(/^SAN-OP-[A-Z0-9][A-Z0-9-]{2,}$/),
+    action_id: z.string().regex(/^SH-ACTION-[A-Z0-9][A-Z0-9-]{2,}$/),
+    finding_id: z.string().regex(/^SH-[A-Z0-9][A-Z0-9-]{2,}$/),
+    disposition: StructuralSanitizerDispositionSchema,
+    operation: StructuralSanitizerActionSchema.shape.operation,
+    status: z.enum(['applied', 'skipped', 'failed', 'rolled_back']),
+    from_path: NonEmptyStringSchema.optional(),
+    to_path: NonEmptyStringSchema.optional(),
+    before_hash: NonEmptyStringSchema.optional(),
+    after_hash: NonEmptyStringSchema.optional(),
+    error: NonEmptyStringSchema.optional(),
+    rollback: StructuralSanitizerRollbackOperationSchema,
+});
+export const StructuralSanitizerTransactionSummarySchema = z.object({
+    applied: z.number().int().nonnegative(),
+    skipped: z.number().int().nonnegative(),
+    failed: z.number().int().nonnegative(),
+    rolled_back: z.number().int().nonnegative(),
+});
+export const StructuralSanitizerTransactionManifestSchema = z.object({
+    report_version: z.literal(1),
+    transaction_id: z.string().regex(/^SAN-[0-9]{8}T[0-9]{6}Z-[A-F0-9]{8}$/),
+    generated_at: NonEmptyStringSchema,
+    source_report_id: NonEmptyStringSchema,
+    root_path: NonEmptyStringSchema,
+    mode: z.literal('apply'),
+    operations: z.array(StructuralSanitizerTransactionOperationSchema),
+    summary: StructuralSanitizerTransactionSummarySchema,
+    audit_log_path: NonEmptyStringSchema,
+});
+export const StructuralSanitizerReportSchema = z.object({
+    report_version: z.literal(1),
+    generated_at: NonEmptyStringSchema,
+    source_report_id: NonEmptyStringSchema,
+    mode: z.enum(['dry_run', 'apply']),
+    actions: z.array(StructuralSanitizerActionSchema),
+    blocked_actions: z.array(StructuralSanitizerActionSchema).default([]),
+    transaction_id: NonEmptyStringSchema.optional(),
+    manifest_path: NonEmptyStringSchema.optional(),
+    audit_log_path: NonEmptyStringSchema.optional(),
+    summary: StructuralSanitizerTransactionSummarySchema.optional(),
+});
+export const StructuralLifecycleEntrySchema = z.object({
+    entity_id: z.string().regex(/^(?:INS|DEB|EPIC|FEAT|FGAP|TD)-\d{3,}$/),
+    expected_root: StructuralLifecycleDirectoryTokenSchema,
+    actual_root: StructuralLifecycleDirectoryTokenSchema.optional(),
+    state_token: StructuralLifecycleStateTokenSchema,
+});
+export const StructuralDirectoryStateMappingSchema = z.object({
+    version: z.literal(1),
+    lifecycle_roots: z.record(StructuralLifecycleDirectoryTokenSchema, z.array(StructuralLifecycleStateTokenSchema)),
+    state_to_root: z.record(StructuralLifecycleStateTokenSchema, StructuralLifecycleDirectoryTokenSchema),
+});
+export const StructuralNavigationNodeSchema = z.object({
+    node_id: NonEmptyStringSchema,
+    kind: StructuralNavigationNodeKindSchema,
+    ref: NonEmptyStringSchema,
+    status: NonEmptyStringSchema.optional(),
+});
+export const StructuralNavigationEdgeSchema = z.object({
+    from: NonEmptyStringSchema,
+    to: NonEmptyStringSchema,
+    kind: StructuralNavigationEdgeKindSchema,
+});
+export const StructuralNavigationGraphSchema = z.object({
+    nodes: z.array(StructuralNavigationNodeSchema),
+    edges: z.array(StructuralNavigationEdgeSchema),
+});
+export const StructuralFixtureRootSchema = z.object({
+    fixture_id: NonEmptyStringSchema,
+    lifecycle_directories: z.array(StructuralLifecycleDirectoryTokenSchema).min(1),
+    generated_directories: z.array(StructuralGeneratedDirectoryTokenSchema).default([]),
+    state_files: z.array(z.string().regex(/^\.sdd\/state\/[a-z0-9-]+\.yaml$/i)).default([]),
+    translated_directories: z.array(NonEmptyStringSchema).default([]),
+});
+//# sourceMappingURL=structural-health.js.map

package/dist/core/sdd/transaction.d.ts

@@ -0,0 +1,14 @@
+import { promises as fs } from 'node:fs';
+type FsApi = Pick<typeof fs, 'mkdir' | 'writeFile' | 'rename' | 'rm'>;
+export declare class SddWriteTransaction {
+    private readonly fsApi;
+    private readonly txId;
+    private readonly writes;
+    private committed;
+    constructor(fsApi?: FsApi);
+    writeFile(filePath: string, content: string): void;
+    commit(): Promise<void>;
+    private rollback;
+}
+export {};
+//# sourceMappingURL=transaction.d.ts.map

package/dist/core/sdd/transaction.js

@@ -0,0 +1,100 @@
+import { randomUUID } from 'node:crypto';
+import { promises as fs } from 'node:fs';
+import path from 'node:path';
+function isErrnoCode(error, code) {
+    return !!error && typeof error === 'object' && 'code' in error && error.code === code;
+}
+async function rmIfExists(fsApi, filePath) {
+    try {
+        await fsApi.rm(filePath, { force: true });
+    }
+    catch (error) {
+        if (!isErrnoCode(error, 'ENOENT')) {
+            throw error;
+        }
+    }
+}
+export class SddWriteTransaction {
+    fsApi;
+    txId;
+    writes = [];
+    committed = false;
+    constructor(fsApi = fs) {
+        this.fsApi = fsApi;
+        this.txId = randomUUID();
+    }
+    writeFile(filePath, content) {
+        this.writes.push({ targetPath: filePath, content });
+    }
+    async commit() {
+        if (this.committed) {
+            throw new Error('SddWriteTransaction already committed');
+        }
+        this.committed = true;
+        if (this.writes.length === 0) {
+            return;
+        }
+        const staged = [];
+        for (let index = 0; index < this.writes.length; index += 1) {
+            const write = this.writes[index];
+            const tmpPath = `${write.targetPath}.${this.txId}.${index}.tmp`;
+            const backupPath = `${write.targetPath}.${this.txId}.${index}.bak`;
+            await this.fsApi.mkdir(path.dirname(write.targetPath), { recursive: true });
+            await this.fsApi.writeFile(tmpPath, write.content, 'utf-8');
+            staged.push({
+                targetPath: write.targetPath,
+                tmpPath,
+                backupPath,
+                backupCreated: false,
+                applied: false,
+            });
+        }
+        try {
+            for (const item of staged) {
+                try {
+                    await this.fsApi.rename(item.targetPath, item.backupPath);
+                    item.backupCreated = true;
+                }
+                catch (error) {
+                    if (!isErrnoCode(error, 'ENOENT')) {
+                        throw error;
+                    }
+                }
+                await this.fsApi.rename(item.tmpPath, item.targetPath);
+                item.applied = true;
+            }
+            for (const item of staged) {
+                if (!item.backupCreated)
+                    continue;
+                await rmIfExists(this.fsApi, item.backupPath);
+            }
+        }
+        catch (error) {
+            await this.rollback(staged);
+            throw error;
+        }
+    }
+    async rollback(staged) {
+        for (const item of staged.slice().reverse()) {
+            await rmIfExists(this.fsApi, item.tmpPath);
+            if (item.backupCreated) {
+                if (item.applied) {
+                    await rmIfExists(this.fsApi, item.targetPath);
+                }
+                try {
+                    await this.fsApi.rename(item.backupPath, item.targetPath);
+                }
+                catch (error) {
+                    if (!isErrnoCode(error, 'ENOENT')) {
+                        throw error;
+                    }
+                }
+            }
+            else if (item.applied) {
+                await rmIfExists(this.fsApi, item.targetPath);
+            }
+            await rmIfExists(this.fsApi, item.backupPath);
+        }
+    }
+}
+//# sourceMappingURL=transaction.js.map