@rengler33/prov 0.1.1

package/dist/commands/constraint.js

@@ -0,0 +1,763 @@
+/**
+ * prov constraint commands implementation.
+ *
+ * Commands for managing constraints:
+ * - constraint add: Add a constraint to tracking
+ * - constraint list: List tracked constraints
+ * - constraint check: Run constraint verification
+ *
+ * @see req:cli:constraint-add
+ * @see req:cli:constraint-list
+ * @see req:cli:constraint-check
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { join, resolve, extname } from 'node:path';
+import { isInitialized, loadGraph, saveGraph } from '../storage.js';
+import { addConstraintToGraph } from '../graph.js';
+import { parseYaml, computeHash } from '../hash.js';
+import { output, error, success, warn, resolveFormat } from '../output.js';
+// ============================================================================
+// Validation Helpers
+// ============================================================================
+/**
+ * Validate constraint ID format: constraint:{name}:v{number}
+ */
+function isValidConstraintId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^constraint:[a-z0-9-]+:v\d+$/.test(id);
+}
+/**
+ * Validate invariant ID format: inv:{constraint}:{name}
+ */
+function isValidInvariantId(id) {
+    if (typeof id !== 'string')
+        return false;
+    return /^inv:[a-z0-9-]+:[a-z0-9-]+$/.test(id);
+}
+/**
+ * Validate entity status.
+ */
+function isValidStatus(status) {
+    return status === 'draft' || status === 'active' || status === 'deprecated' || status === 'archived';
+}
+/**
+ * Validate verification type.
+ */
+function isValidVerificationType(type) {
+    return type === 'command' || type === 'test' || type === 'assertion' || type === 'manual';
+}
+/**
+ * Validate a raw verification object.
+ */
+function validateVerification(raw, invId) {
+    const errors = [];
+    if (raw.type === undefined || raw.type === null) {
+        errors.push(`Invariant ${invId}: verification missing required field: type`);
+    }
+    else if (!isValidVerificationType(raw.type)) {
+        errors.push(`Invariant ${invId}: invalid verification type: ${String(raw.type)} (expected command|test|assertion|manual)`);
+    }
+    if (raw.value === undefined || raw.value === null) {
+        errors.push(`Invariant ${invId}: verification missing required field: value`);
+    }
+    else if (typeof raw.value !== 'string') {
+        errors.push(`Invariant ${invId}: verification value must be a string`);
+    }
+    if (raw.expect !== undefined && typeof raw.expect !== 'string') {
+        errors.push(`Invariant ${invId}: verification expect must be a string`);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    const verification = {
+        type: raw.type,
+        value: raw.value,
+        ...(raw.expect !== undefined ? { expect: raw.expect } : {}),
+    };
+    return { verification, errors: [] };
+}
+/**
+ * Validate a raw constraint object and convert to typed Constraint.
+ */
+function validateConstraint(raw, _filePath) {
+    const errors = [];
+    // Required fields
+    if (raw.id === undefined || raw.id === null) {
+        errors.push('Missing required field: id');
+    }
+    else if (!isValidConstraintId(raw.id)) {
+        errors.push(`Invalid constraint ID format: ${String(raw.id)} (expected constraint:{name}:v{number})`);
+    }
+    if (raw.version === undefined || raw.version === null) {
+        errors.push('Missing required field: version');
+    }
+    else if (typeof raw.version !== 'string') {
+        errors.push(`Invalid version type: expected string, got ${typeof raw.version}`);
+    }
+    if (raw.title === undefined || raw.title === null) {
+        errors.push('Missing required field: title');
+    }
+    else if (typeof raw.title !== 'string') {
+        errors.push(`Invalid title type: expected string, got ${typeof raw.title}`);
+    }
+    if (raw.status !== undefined && !isValidStatus(raw.status)) {
+        errors.push(`Invalid status: ${String(raw.status)} (expected draft|active|deprecated|archived)`);
+    }
+    if (raw.description === undefined || raw.description === null) {
+        errors.push('Missing required field: description');
+    }
+    else if (typeof raw.description !== 'string') {
+        errors.push(`Invalid description type: expected string, got ${typeof raw.description}`);
+    }
+    if (raw.invariants === undefined || raw.invariants === null) {
+        errors.push('Missing required field: invariants');
+    }
+    else if (!Array.isArray(raw.invariants)) {
+        errors.push(`Invalid invariants type: expected array, got ${typeof raw.invariants}`);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    // Validate invariants
+    const invariants = [];
+    const invIds = new Set();
+    for (let i = 0; i < raw.invariants.length; i++) {
+        const rawInv = raw.invariants[i];
+        if (rawInv.id === undefined || rawInv.id === null) {
+            errors.push(`Invariant ${i}: missing required field: id`);
+            continue;
+        }
+        if (!isValidInvariantId(rawInv.id)) {
+            errors.push(`Invariant ${i}: invalid ID format: ${String(rawInv.id)} (expected inv:{constraint}:{name})`);
+            continue;
+        }
+        const invIdStr = rawInv.id;
+        if (invIds.has(invIdStr)) {
+            errors.push(`Invariant ${i}: duplicate ID: ${invIdStr}`);
+            continue;
+        }
+        invIds.add(invIdStr);
+        if (rawInv.rule === undefined || typeof rawInv.rule !== 'string') {
+            errors.push(`Invariant ${invIdStr}: missing or invalid rule`);
+            continue;
+        }
+        if (rawInv.verification === undefined || typeof rawInv.verification !== 'object') {
+            errors.push(`Invariant ${invIdStr}: missing or invalid verification`);
+            continue;
+        }
+        const { verification, errors: verifyErrors } = validateVerification(rawInv.verification, invIdStr);
+        if (verifyErrors.length > 0) {
+            errors.push(...verifyErrors);
+            continue;
+        }
+        const inv = {
+            id: invIdStr,
+            rule: rawInv.rule,
+            verification: verification,
+            ...(typeof rawInv.blocking === 'boolean' ? { blocking: rawInv.blocking } : {}),
+        };
+        invariants.push(inv);
+    }
+    if (errors.length > 0) {
+        return { errors };
+    }
+    const constraint = {
+        id: raw.id,
+        version: raw.version,
+        title: raw.title,
+        status: raw.status ?? 'draft',
+        description: raw.description,
+        invariants,
+    };
+    return { constraint, errors: [] };
+}
+// ============================================================================
+// File Discovery
+// ============================================================================
+/**
+ * Find all constraint files in the constraint directory.
+ */
+function findConstraintFiles(projectRoot) {
+    const constraintDir = join(projectRoot, 'constraint');
+    const files = [];
+    if (!existsSync(constraintDir)) {
+        return files;
+    }
+    function walkDir(dir) {
+        const entries = readdirSync(dir);
+        for (const entry of entries) {
+            const fullPath = join(dir, entry);
+            const stat = statSync(fullPath);
+            if (stat.isDirectory()) {
+                walkDir(fullPath);
+            }
+            else {
+                const ext = extname(entry).toLowerCase();
+                if (ext === '.yaml' || ext === '.yml') {
+                    // Include files with .constraint. in the name or in constraint directory
+                    if (entry.includes('.constraint.') || dir.includes('/constraint')) {
+                        files.push(fullPath);
+                    }
+                }
+            }
+        }
+    }
+    walkDir(constraintDir);
+    return files.sort();
+}
+/**
+ * Load and parse a constraint file.
+ */
+function loadConstraintFile(filePath) {
+    try {
+        const content = readFileSync(filePath, 'utf8');
+        const raw = parseYaml(content);
+        if (raw === null || typeof raw !== 'object') {
+            return { errors: ['File does not contain a valid YAML object'] };
+        }
+        return validateConstraint(raw, filePath);
+    }
+    catch (err) {
+        return {
+            errors: [`Failed to parse YAML: ${err instanceof Error ? err.message : String(err)}`],
+        };
+    }
+}
+// ============================================================================
+// Verification Execution
+// ============================================================================
+/**
+ * Execute a verification command and return the result.
+ */
+async function executeVerification(invariant, projectRoot) {
+    const { id, rule, verification, blocking = true } = invariant;
+    // Manual verification always passes (requires human check)
+    if (verification.type === 'manual') {
+        return {
+            invariantId: id,
+            rule,
+            passed: true,
+            blocking,
+            output: 'Manual verification required',
+        };
+    }
+    // Assertion verification - check if expression is truthy
+    if (verification.type === 'assertion') {
+        try {
+            // Simple assertion evaluation (could be expanded)
+            const result = verification.value.trim().toLowerCase();
+            const passed = result === 'true' || result === '1' || result === 'yes';
+            return {
+                invariantId: id,
+                rule,
+                passed,
+                blocking,
+                output: `Assertion: ${verification.value}`,
+            };
+        }
+        catch (err) {
+            return {
+                invariantId: id,
+                rule,
+                passed: false,
+                blocking,
+                error: `Assertion error: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+    }
+    // Test reference - treat as command
+    if (verification.type === 'test') {
+        // Tests are typically run as commands
+        // e.g., "npm test -- --grep 'pattern'"
+    }
+    // Command verification - execute and check result
+    const command = verification.value;
+    const expect = verification.expect ?? 'success';
+    return new Promise((resolve) => {
+        const spawnOptions = {
+            cwd: projectRoot,
+            shell: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        };
+        const proc = spawn(command, [], spawnOptions);
+        let stdout = '';
+        let stderr = '';
+        proc.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        proc.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        proc.on('error', (err) => {
+            resolve({
+                invariantId: id,
+                rule,
+                passed: false,
+                blocking,
+                error: `Command failed to start: ${err.message}`,
+            });
+        });
+        proc.on('close', (code) => {
+            const output = stdout.trim() || stderr.trim();
+            let passed = false;
+            if (expect === 'success') {
+                passed = code === 0;
+            }
+            else if (expect === 'failure') {
+                passed = code !== 0;
+            }
+            else {
+                // Custom pattern matching
+                passed = output.includes(expect);
+            }
+            resolve({
+                invariantId: id,
+                rule,
+                passed,
+                blocking,
+                output: output.slice(0, 500), // Limit output size
+                ...(code !== 0 && !passed ? { error: `Exit code: ${code}` } : {}),
+            });
+        });
+        // Timeout after 30 seconds
+        setTimeout(() => {
+            proc.kill();
+            resolve({
+                invariantId: id,
+                rule,
+                passed: false,
+                blocking,
+                error: 'Command timed out after 30 seconds',
+            });
+        }, 30000);
+    });
+}
+// ============================================================================
+// constraint add Command
+// ============================================================================
+/**
+ * Execute the constraint add command.
+ *
+ * @see req:cli:constraint-add
+ */
+export function runConstraintAdd(globalOpts, file, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Resolve file path
+    const filePath = resolve(projectRoot, file);
+    if (!existsSync(filePath)) {
+        const result = {
+            success: false,
+            error: `File not found: ${file}`,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load and validate constraint file
+    const { constraint, errors } = loadConstraintFile(filePath);
+    if (errors.length > 0 || constraint === undefined) {
+        const result = {
+            success: false,
+            error: `Invalid constraint file:\n  ${errors.join('\n  ')}`,
+        };
+        if (fmt === 'json') {
+            output({ ...result, validationErrors: errors }, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output({ ...result, validationErrors: errors }, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Compute hash
+    const hash = computeHash(constraint);
+    const constraintWithHash = { ...constraint, hash };
+    // Load existing graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Check if constraint already exists
+    const existingNode = graph.getNode(constraint.id);
+    if (existingNode !== undefined) {
+        const existingConstraint = existingNode.data;
+        if (existingNode.hash === hash) {
+            // Same content, no update needed
+            const result = {
+                success: true,
+                constraintId: constraint.id,
+                hash,
+                invariantCount: constraint.invariants.length,
+            };
+            if (fmt === 'json') {
+                output({ ...result, unchanged: true }, { format: 'json' });
+            }
+            else if (fmt === 'yaml') {
+                output({ ...result, unchanged: true }, { format: 'yaml' });
+            }
+            else {
+                success(`Constraint ${constraint.id} is already tracked (unchanged)`);
+            }
+            return;
+        }
+        // Different content - update by removing old and adding new
+        // First remove old invariants
+        for (const inv of existingConstraint.invariants) {
+            graph.removeNode(inv.id);
+        }
+        graph.removeNode(constraint.id);
+    }
+    // Add constraint to graph
+    addConstraintToGraph(graph, constraintWithHash);
+    // Save graph
+    const saveResult = saveGraph(graph, projectRoot);
+    if (!saveResult.success) {
+        const result = {
+            success: false,
+            error: saveResult.error ?? 'Failed to save graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const result = {
+        success: true,
+        constraintId: constraint.id,
+        hash,
+        invariantCount: constraint.invariants.length,
+    };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        success(`Added constraint ${constraint.id} (${constraint.invariants.length} invariants)`);
+    }
+}
+// ============================================================================
+// constraint list Command
+// ============================================================================
+/**
+ * Execute the constraint list command.
+ *
+ * @see req:cli:constraint-list
+ */
+export function runConstraintList(globalOpts, options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Get all constraint nodes
+    const constraintNodes = graph.getNodesByType('constraint');
+    // Build constraint entries
+    const constraints = [];
+    for (const node of constraintNodes) {
+        const constraint = node.data;
+        // Determine status - check if constraint file still exists and matches
+        let displayStatus = constraint.status;
+        // Find matching constraint file
+        const constraintFiles = findConstraintFiles(projectRoot);
+        let fileMatch;
+        for (const filePath of constraintFiles) {
+            const { constraint: fileConstraint } = loadConstraintFile(filePath);
+            if (fileConstraint?.id === constraint.id) {
+                fileMatch = filePath;
+                const fileHash = computeHash(fileConstraint);
+                if (fileHash !== node.hash) {
+                    displayStatus = 'stale';
+                }
+                break;
+            }
+        }
+        if (fileMatch === undefined) {
+            displayStatus = 'missing';
+        }
+        // Filter by status if specified
+        if (options.status !== undefined && displayStatus !== options.status) {
+            continue;
+        }
+        constraints.push({
+            id: constraint.id,
+            version: constraint.version,
+            title: constraint.title,
+            status: displayStatus,
+            hash: node.hash ?? '',
+            invariants: constraint.invariants.length,
+        });
+    }
+    // Sort by ID
+    constraints.sort((a, b) => a.id.localeCompare(b.id));
+    const result = { constraints };
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        if (constraints.length === 0) {
+            success('No constraints tracked');
+            return;
+        }
+        const columns = [
+            { header: 'ID', key: 'id', minWidth: 24 },
+            { header: 'Version', key: 'version', minWidth: 8 },
+            { header: 'Title', key: 'title', maxWidth: 30 },
+            { header: 'Status', key: 'status', minWidth: 8 },
+            { header: 'Invs', key: 'invariants', minWidth: 4, align: 'right' },
+            { header: 'Hash', key: 'hash', minWidth: 16 },
+        ];
+        output(constraints, { format: 'table', columns });
+    }
+}
+// ============================================================================
+// constraint check Command
+// ============================================================================
+/**
+ * Execute the constraint check command.
+ *
+ * @see req:cli:constraint-check
+ */
+export async function runConstraintCheck(globalOpts, constraintId, _options) {
+    const projectRoot = globalOpts.dir ?? process.cwd();
+    const fmt = resolveFormat({ format: globalOpts.format });
+    // Check if prov is initialized
+    if (!isInitialized(projectRoot)) {
+        const result = {
+            success: false,
+            error: 'prov is not initialized. Run "prov init" first.',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    // Load graph
+    const loadResult = loadGraph(projectRoot);
+    if (!loadResult.success || loadResult.data === undefined) {
+        const result = {
+            success: false,
+            error: loadResult.error ?? 'Failed to load graph',
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            error(result.error);
+        }
+        process.exit(1);
+    }
+    const graph = loadResult.data;
+    // Find constraints to check
+    let constraintsToCheck = [];
+    if (constraintId !== undefined) {
+        // Check specific constraint
+        const node = graph.getNode(constraintId);
+        if (node === undefined || node.type !== 'constraint') {
+            const result = {
+                success: false,
+                results: [],
+                passed: 0,
+                failed: 0,
+                skipped: 0,
+                error: `Constraint not found: ${constraintId}`,
+            };
+            if (fmt === 'json') {
+                output(result, { format: 'json' });
+            }
+            else if (fmt === 'yaml') {
+                output(result, { format: 'yaml' });
+            }
+            else {
+                error(result.error);
+            }
+            process.exit(1);
+        }
+        constraintsToCheck = [node.data];
+    }
+    else {
+        // Check all constraints
+        const constraintNodes = graph.getNodesByType('constraint');
+        constraintsToCheck = constraintNodes.map((n) => n.data);
+    }
+    if (constraintsToCheck.length === 0) {
+        const result = {
+            success: true,
+            results: [],
+            passed: 0,
+            failed: 0,
+            skipped: 0,
+        };
+        if (fmt === 'json') {
+            output(result, { format: 'json' });
+        }
+        else if (fmt === 'yaml') {
+            output(result, { format: 'yaml' });
+        }
+        else {
+            warn('No constraints to check');
+        }
+        return;
+    }
+    // Run verification for each invariant
+    const allResults = [];
+    let passed = 0;
+    let failed = 0;
+    const skipped = 0; // TODO: implement skipping for manual verifications or other cases
+    let hasBlockingFailure = false;
+    for (const constraint of constraintsToCheck) {
+        if (fmt !== 'json' && fmt !== 'yaml') {
+            process.stdout.write(`\nChecking ${constraint.id}...\n`);
+        }
+        for (const invariant of constraint.invariants) {
+            const result = await executeVerification(invariant, projectRoot);
+            allResults.push(result);
+            if (result.passed) {
+                passed++;
+                if (fmt !== 'json' && fmt !== 'yaml') {
+                    process.stdout.write(`  ✓ ${invariant.id}: ${invariant.rule}\n`);
+                }
+            }
+            else {
+                failed++;
+                if (result.blocking) {
+                    hasBlockingFailure = true;
+                }
+                if (fmt !== 'json' && fmt !== 'yaml') {
+                    const marker = result.blocking ? '✗' : '⚠';
+                    process.stdout.write(`  ${marker} ${invariant.id}: ${invariant.rule}\n`);
+                    if (result.error !== undefined) {
+                        process.stdout.write(`      ${result.error}\n`);
+                    }
+                }
+            }
+        }
+    }
+    const result = {
+        success: !hasBlockingFailure,
+        results: allResults,
+        passed,
+        failed,
+        skipped,
+    };
+    if (constraintId !== undefined) {
+        result.constraintId = constraintId;
+    }
+    if (fmt === 'json') {
+        output(result, { format: 'json' });
+    }
+    else if (fmt === 'yaml') {
+        output(result, { format: 'yaml' });
+    }
+    else {
+        process.stdout.write('\n');
+        if (hasBlockingFailure) {
+            error(`${failed} invariant(s) failed (${passed} passed)`);
+        }
+        else if (failed > 0) {
+            warn(`${failed} non-blocking invariant(s) failed (${passed} passed)`);
+        }
+        else {
+            success(`All ${passed} invariant(s) passed`);
+        }
+    }
+    if (hasBlockingFailure) {
+        process.exit(1);
+    }
+}
+//# sourceMappingURL=constraint.js.map