@jterrats/smart-deployment 1.0.3

package/lib/dependencies/dependency-validator.js

@@ -0,0 +1,291 @@
+/**
+ * Dependency Validator
+ * Validates the dependency graph for correctness and consistency
+ *
+ * @ac US-034-AC-1: Validate no dangling references
+ * @ac US-034-AC-2: Validate all nodes have types
+ * @ac US-034-AC-3: Validate no self-loops (except cycles)
+ * @ac US-034-AC-4: Validate edge consistency
+ * @ac US-034-AC-5: Generate validation report
+ * @ac US-034-AC-6: Fail on critical issues
+ *
+ * @issue #34
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('DependencyValidator');
+/**
+ * Dependency Validator
+ *
+ * Validates dependency graph integrity:
+ * - No dangling references (edges to non-existent nodes)
+ * - All nodes have valid types
+ * - No self-loops (unless in known cycles)
+ * - Edge consistency (graph ↔ components)
+ *
+ * Performance: O(V + E)
+ *
+ * @example
+ * const validator = new DependencyValidator(graph, components);
+ * const result = validator.validate();
+ * if (!result.isValid) {
+ *   console.error(`Found ${result.errors.length} errors`);
+ *   result.errors.forEach(e => console.error(e.message));
+ * }
+ */
+export class DependencyValidator {
+    graph;
+    components;
+    options;
+    constructor(graph, components, options = {}) {
+        this.graph = graph;
+        this.components = components;
+        this.options = {
+            strictMode: options.strictMode ?? false,
+            circularDependencies: options.circularDependencies ?? [],
+            allowSelfLoops: options.allowSelfLoops ?? false,
+        };
+        logger.debug('Initialized DependencyValidator', {
+            nodes: this.graph.size,
+            components: this.components.size,
+            strictMode: this.options.strictMode,
+        });
+    }
+    /**
+     * Validate the dependency graph
+     *
+     * @ac US-034-AC-5: Generate validation report
+     * @ac US-034-AC-6: Fail on critical issues
+     */
+    validate() {
+        const startTime = Date.now();
+        const issues = [];
+        // Run all validations
+        issues.push(...this.validateDanglingReferences());
+        issues.push(...this.validateNodeTypes());
+        issues.push(...this.validateSelfLoops());
+        issues.push(...this.validateEdgeConsistency());
+        // Categorize issues by severity
+        const errors = issues.filter((i) => i.severity === 'error');
+        const warnings = issues.filter((i) => i.severity === 'warning');
+        const critical = issues.filter((i) => i.severity === 'critical');
+        // Calculate stats
+        const stats = this.calculateStats(issues);
+        // Determine if valid
+        const isValid = critical.length === 0 && errors.length === 0 && (!this.options.strictMode || warnings.length === 0);
+        const duration = Date.now() - startTime;
+        logger.info('Validation completed', {
+            isValid,
+            issues: issues.length,
+            errors: errors.length,
+            warnings: warnings.length,
+            critical: critical.length,
+            durationMs: duration,
+        });
+        return {
+            isValid,
+            issues,
+            errors,
+            warnings,
+            critical,
+            stats,
+        };
+    }
+    /**
+     * @ac US-034-AC-1: Validate no dangling references
+     */
+    validateDanglingReferences() {
+        const issues = [];
+        for (const [nodeId, deps] of this.graph.entries()) {
+            for (const dep of deps) {
+                // Check if dependency exists in graph
+                if (!this.graph.has(dep) && !this.components.has(dep)) {
+                    issues.push({
+                        severity: 'error',
+                        code: 'DANGLING_REFERENCE',
+                        message: `Dangling reference: ${nodeId} references non-existent ${dep}`,
+                        nodeId,
+                        relatedNodes: [dep],
+                        suggestion: `Ensure ${dep} exists in the project or remove the reference`,
+                    });
+                }
+            }
+        }
+        logger.debug('Dangling reference validation', { danglingRefs: issues.length });
+        return issues;
+    }
+    /**
+     * @ac US-034-AC-2: Validate all nodes have types
+     */
+    validateNodeTypes() {
+        const issues = [];
+        for (const nodeId of this.graph.keys()) {
+            // Check if node ID has valid format: "Type:Name"
+            if (!nodeId.includes(':')) {
+                issues.push({
+                    severity: 'critical',
+                    code: 'INVALID_NODE_FORMAT',
+                    message: `Invalid node format: ${nodeId} (expected "Type:Name")`,
+                    nodeId,
+                    suggestion: 'Node IDs must follow the format "MetadataType:ComponentName"',
+                });
+                continue;
+            }
+            const [type, name] = nodeId.split(':');
+            if (!type || type.trim().length === 0) {
+                issues.push({
+                    severity: 'critical',
+                    code: 'MISSING_TYPE',
+                    message: `Node ${nodeId} has no type`,
+                    nodeId,
+                    suggestion: 'All nodes must have a valid metadata type',
+                });
+            }
+            if (!name || name.trim().length === 0) {
+                issues.push({
+                    severity: 'critical',
+                    code: 'MISSING_NAME',
+                    message: `Node ${nodeId} has no name`,
+                    nodeId,
+                    suggestion: 'All nodes must have a valid component name',
+                });
+            }
+        }
+        logger.debug('Node type validation', { invalidNodes: issues.length });
+        return issues;
+    }
+    /**
+     * @ac US-034-AC-3: Validate no self-loops (except cycles)
+     */
+    validateSelfLoops() {
+        const issues = [];
+        // Build set of nodes in known cycles
+        const cyclicNodes = new Set();
+        for (const cycle of this.options.circularDependencies) {
+            for (const nodeId of cycle.cycle) {
+                cyclicNodes.add(nodeId);
+            }
+        }
+        for (const [nodeId, deps] of this.graph.entries()) {
+            if (deps.has(nodeId)) {
+                // Self-loop detected
+                if (!this.options.allowSelfLoops && !cyclicNodes.has(nodeId)) {
+                    issues.push({
+                        severity: 'error',
+                        code: 'SELF_LOOP',
+                        message: `Self-loop detected: ${nodeId} depends on itself`,
+                        nodeId,
+                        suggestion: 'Remove the self-reference or declare it as a circular dependency',
+                    });
+                }
+                else if (cyclicNodes.has(nodeId)) {
+                    issues.push({
+                        severity: 'info',
+                        code: 'KNOWN_SELF_LOOP',
+                        message: `Self-loop in known circular dependency: ${nodeId}`,
+                        nodeId,
+                    });
+                }
+            }
+        }
+        logger.debug('Self-loop validation', { selfLoops: issues.length });
+        return issues;
+    }
+    /**
+     * @ac US-034-AC-4: Validate edge consistency
+     */
+    validateEdgeConsistency() {
+        const issues = [];
+        // Validate that components match graph
+        for (const [nodeId, component] of this.components.entries()) {
+            const graphDeps = this.graph.get(nodeId) ?? new Set();
+            const componentDeps = component.dependencies;
+            // Check if graph has all component dependencies
+            for (const dep of componentDeps) {
+                if (!graphDeps.has(dep)) {
+                    issues.push({
+                        severity: 'warning',
+                        code: 'GRAPH_COMPONENT_MISMATCH',
+                        message: `Component ${nodeId} declares dependency ${dep} but not in graph`,
+                        nodeId,
+                        relatedNodes: [dep],
+                        suggestion: 'Ensure dependency graph is built from component metadata',
+                    });
+                }
+            }
+            // Check if component has all graph dependencies
+            for (const dep of graphDeps) {
+                if (!componentDeps.has(dep)) {
+                    issues.push({
+                        severity: 'warning',
+                        code: 'COMPONENT_GRAPH_MISMATCH',
+                        message: `Graph has edge ${nodeId} → ${dep} but component doesn't declare it`,
+                        nodeId,
+                        relatedNodes: [dep],
+                        suggestion: 'Synchronize graph with component metadata',
+                    });
+                }
+            }
+        }
+        logger.debug('Edge consistency validation', { inconsistencies: issues.length });
+        return issues;
+    }
+    /**
+     * Calculate validation statistics
+     */
+    calculateStats(issues) {
+        const danglingReferences = issues.filter((i) => i.code === 'DANGLING_REFERENCE').length;
+        const selfLoops = issues.filter((i) => i.code === 'SELF_LOOP' || i.code === 'KNOWN_SELF_LOOP').length;
+        const invalidNodes = issues.filter((i) => i.code === 'INVALID_NODE_FORMAT' || i.code === 'MISSING_TYPE' || i.code === 'MISSING_NAME').length;
+        const edgeInconsistencies = issues.filter((i) => i.code === 'GRAPH_COMPONENT_MISMATCH' || i.code === 'COMPONENT_GRAPH_MISMATCH').length;
+        let totalEdges = 0;
+        for (const deps of this.graph.values()) {
+            totalEdges += deps.size;
+        }
+        return {
+            totalNodes: this.graph.size,
+            totalEdges,
+            danglingReferences,
+            selfLoops,
+            invalidNodes,
+            edgeInconsistencies,
+        };
+    }
+    /**
+     * Validate a specific component
+     */
+    validateComponent(nodeId) {
+        const issues = [];
+        // Check if component exists
+        if (!this.graph.has(nodeId)) {
+            issues.push({
+                severity: 'error',
+                code: 'NODE_NOT_FOUND',
+                message: `Component ${nodeId} not found in graph`,
+                nodeId,
+            });
+            return issues;
+        }
+        // Validate its dependencies
+        const deps = this.graph.get(nodeId);
+        for (const dep of deps) {
+            if (!this.graph.has(dep)) {
+                issues.push({
+                    severity: 'error',
+                    code: 'DANGLING_REFERENCE',
+                    message: `${nodeId} references non-existent ${dep}`,
+                    nodeId,
+                    relatedNodes: [dep],
+                });
+            }
+        }
+        return issues;
+    }
+    /**
+     * Check if validation would pass
+     */
+    isValid() {
+        const result = this.validate();
+        return result.isValid;
+    }
+}
+//# sourceMappingURL=dependency-validator.js.map

package/lib/dependencies/dependency-validator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependency-validator.js","sourceRoot":"","sources":["../../src/dependencies/dependency-validator.ts"],"names":[],"mappings":"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"}

package/lib/dependencies/graph-visualizer.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Graph Visualizer
+ * Generates visual representations of the dependency graph
+ *
+ * @ac US-035-AC-1: Generate Mermaid diagram
+ * @ac US-035-AC-2: Generate DOT format
+ * @ac US-035-AC-3: Support filtering by type
+ * @ac US-035-AC-4: Support filtering by depth
+ * @ac US-035-AC-5: Highlight critical path
+ * @ac US-035-AC-6: Export as SVG/PNG (requires external tools)
+ *
+ * @issue #35
+ */
+import type { NodeId, DependencyGraph } from '../types/dependency.js';
+import type { MetadataType } from '../types/metadata.js';
+/**
+ * Visualization format
+ */
+export type VisualizationFormat = 'mermaid' | 'dot' | 'ascii';
+/**
+ * Visualization options
+ */
+export type VisualizationOptions = {
+    /** Filter by metadata types */
+    includeTypes?: MetadataType[];
+    /** Exclude metadata types */
+    excludeTypes?: MetadataType[];
+    /** Maximum depth to visualize */
+    maxDepth?: number;
+    /** Nodes in critical path to highlight */
+    criticalPath?: NodeId[];
+    /** Show node labels */
+    showLabels?: boolean;
+    /** Color scheme */
+    colorScheme?: 'default' | 'type' | 'depth';
+};
+/**
+ * Graph Visualizer
+ *
+ * Generates visual representations of dependency graphs in multiple formats:
+ * - Mermaid: For GitHub, documentation
+ * - DOT: For Graphviz rendering
+ * - ASCII: For terminal output
+ *
+ * Performance: O(V + E)
+ *
+ * @example
+ * const visualizer = new GraphVisualizer(graph);
+ * const mermaid = visualizer.toMermaid({ criticalPath });
+ * const dot = visualizer.toDot({ includeTypes: ['ApexClass'] });
+ * const ascii = visualizer.toAscii();
+ */
+export declare class GraphVisualizer {
+    private graph;
+    private options;
+    constructor(graph: DependencyGraph, options?: VisualizationOptions);
+    /**
+     * @ac US-035-AC-1: Generate Mermaid diagram
+     * @ac US-035-AC-5: Highlight critical path
+     */
+    toMermaid(overrideOptions?: VisualizationOptions): string;
+    /**
+     * @ac US-035-AC-2: Generate DOT format
+     */
+    toDot(overrideOptions?: VisualizationOptions): string;
+    /**
+     * Generate ASCII tree view
+     */
+    toAscii(rootNode?: NodeId, overrideOptions?: VisualizationOptions): string;
+    /**
+     * @ac US-035-AC-3: Support filtering by type
+     * @ac US-035-AC-4: Support filtering by depth
+     */
+    private filterGraph;
+    /**
+     * Check if node matches any of the given types
+     */
+    private matchesType;
+    /**
+     * Get Mermaid node styling
+     */
+    private getMermaidNodeStyle;
+    /**
+     * Get DOT color for node
+     */
+    private getDotColor;
+    /**
+     * Get node label (short name)
+     */
+    private getNodeLabel;
+    /**
+     * Escape node ID for Mermaid
+     */
+    private escapeNodeId;
+    /**
+     * Check if node has incoming edges
+     */
+    private hasIncomingEdge;
+    /**
+     * Find a suitable root node for ASCII tree
+     */
+    private findRootNode;
+    /**
+     * Get graph statistics
+     */
+    getStats(): {
+        nodes: number;
+        edges: number;
+    };
+}

package/lib/dependencies/graph-visualizer.js

@@ -0,0 +1,262 @@
+/**
+ * Graph Visualizer
+ * Generates visual representations of the dependency graph
+ *
+ * @ac US-035-AC-1: Generate Mermaid diagram
+ * @ac US-035-AC-2: Generate DOT format
+ * @ac US-035-AC-3: Support filtering by type
+ * @ac US-035-AC-4: Support filtering by depth
+ * @ac US-035-AC-5: Highlight critical path
+ * @ac US-035-AC-6: Export as SVG/PNG (requires external tools)
+ *
+ * @issue #35
+ */
+import { getLogger } from '../utils/logger.js';
+const logger = getLogger('GraphVisualizer');
+/**
+ * Color palette for metadata types
+ */
+const TYPE_COLORS = {
+    ApexClass: '#FF6B6B',
+    ApexTrigger: '#4ECDC4',
+    CustomObject: '#45B7D1',
+    CustomField: '#96CEB4',
+    Flow: '#FFEAA7',
+    LightningComponentBundle: '#DFE6E9',
+    AuraDefinitionBundle: '#74B9FF',
+    VisualforcePage: '#A29BFE',
+    EmailTemplate: '#FD79A8',
+    PermissionSet: '#FDCB6E',
+    Layout: '#6C5CE7',
+    Profile: '#E17055',
+    FlexiPage: '#00B894',
+    Bot: '#00CEC9',
+    GenAiPromptTemplate: '#B2BEC3',
+};
+/**
+ * Graph Visualizer
+ *
+ * Generates visual representations of dependency graphs in multiple formats:
+ * - Mermaid: For GitHub, documentation
+ * - DOT: For Graphviz rendering
+ * - ASCII: For terminal output
+ *
+ * Performance: O(V + E)
+ *
+ * @example
+ * const visualizer = new GraphVisualizer(graph);
+ * const mermaid = visualizer.toMermaid({ criticalPath });
+ * const dot = visualizer.toDot({ includeTypes: ['ApexClass'] });
+ * const ascii = visualizer.toAscii();
+ */
+export class GraphVisualizer {
+    graph;
+    options;
+    constructor(graph, options = {}) {
+        this.graph = graph;
+        this.options = {
+            showLabels: options.showLabels ?? true,
+            colorScheme: options.colorScheme ?? 'type',
+            ...options,
+        };
+        logger.debug('Initialized GraphVisualizer', {
+            nodes: this.graph.size,
+            format: 'multi',
+        });
+    }
+    /**
+     * @ac US-035-AC-1: Generate Mermaid diagram
+     * @ac US-035-AC-5: Highlight critical path
+     */
+    toMermaid(overrideOptions) {
+        const opts = { ...this.options, ...overrideOptions };
+        const filtered = this.filterGraph(opts);
+        const criticalSet = new Set(opts.criticalPath ?? []);
+        const lines = ['graph TD'];
+        // Add nodes with styling
+        for (const [nodeId, deps] of filtered.entries()) {
+            for (const dep of deps) {
+                const fromStyle = this.getMermaidNodeStyle(nodeId, criticalSet);
+                const toStyle = this.getMermaidNodeStyle(dep, criticalSet);
+                const edgeStyle = criticalSet.has(nodeId) && criticalSet.has(dep) ? '==>' : '-->';
+                lines.push(`    ${this.escapeNodeId(nodeId)}${fromStyle} ${edgeStyle} ${this.escapeNodeId(dep)}${toStyle}`);
+            }
+        }
+        // Add isolated nodes
+        for (const nodeId of filtered.keys()) {
+            if (filtered.get(nodeId).size === 0 && !this.hasIncomingEdge(nodeId, filtered)) {
+                const style = this.getMermaidNodeStyle(nodeId, criticalSet);
+                lines.push(`    ${this.escapeNodeId(nodeId)}${style}`);
+            }
+        }
+        // Add styling classes
+        lines.push('');
+        lines.push('    %% Styling');
+        lines.push('    classDef critical fill:#ff6b6b,stroke:#ff0000,stroke-width:3px');
+        lines.push('    classDef normal fill:#4ecdc4,stroke:#333,stroke-width:1px');
+        return lines.join('\n');
+    }
+    /**
+     * @ac US-035-AC-2: Generate DOT format
+     */
+    toDot(overrideOptions) {
+        const opts = { ...this.options, ...overrideOptions };
+        const filtered = this.filterGraph(opts);
+        const criticalSet = new Set(opts.criticalPath ?? []);
+        const lines = ['digraph Dependencies {'];
+        lines.push('    rankdir=LR;');
+        lines.push('    node [shape=box, style=rounded];');
+        lines.push('');
+        // Add nodes with styling
+        for (const nodeId of filtered.keys()) {
+            const color = this.getDotColor(nodeId, criticalSet);
+            const label = opts.showLabels ? this.getNodeLabel(nodeId) : nodeId;
+            lines.push(`    "${nodeId}" [label="${label}", fillcolor="${color}", style="filled,rounded"];`);
+        }
+        lines.push('');
+        // Add edges
+        for (const [nodeId, deps] of filtered.entries()) {
+            for (const dep of deps) {
+                const edgeStyle = criticalSet.has(nodeId) && criticalSet.has(dep) ? ', color=red, penwidth=2.0' : '';
+                lines.push(`    "${nodeId}" -> "${dep}"${edgeStyle};`);
+            }
+        }
+        lines.push('}');
+        return lines.join('\n');
+    }
+    /**
+     * Generate ASCII tree view
+     */
+    toAscii(rootNode, overrideOptions) {
+        const opts = { ...this.options, ...overrideOptions };
+        const filtered = this.filterGraph(opts);
+        const selectedRootNode = rootNode ?? this.findRootNode(filtered);
+        if (!selectedRootNode) {
+            return 'Empty graph';
+        }
+        const visited = new Set();
+        const lines = [];
+        const buildTree = (nodeId, prefix, isLast) => {
+            if (visited.has(nodeId)) {
+                lines.push(`${prefix}${isLast ? '└─' : '├─'} ${nodeId} (circular)`);
+                return;
+            }
+            visited.add(nodeId);
+            const label = opts.showLabels ? this.getNodeLabel(nodeId) : nodeId;
+            lines.push(`${prefix}${isLast ? '└─' : '├─'} ${label}`);
+            const deps = Array.from(filtered.get(nodeId) ?? []);
+            const newPrefix = prefix + (isLast ? '   ' : '│  ');
+            deps.forEach((dep, index) => {
+                const depIsLast = index === deps.length - 1;
+                buildTree(dep, newPrefix, depIsLast);
+            });
+        };
+        buildTree(selectedRootNode, '', true);
+        return lines.join('\n');
+    }
+    /**
+     * @ac US-035-AC-3: Support filtering by type
+     * @ac US-035-AC-4: Support filtering by depth
+     */
+    filterGraph(opts) {
+        const filtered = new Map();
+        for (const [nodeId, deps] of this.graph.entries()) {
+            // Filter by type
+            if (opts.includeTypes && !this.matchesType(nodeId, opts.includeTypes)) {
+                continue;
+            }
+            if (opts.excludeTypes && this.matchesType(nodeId, opts.excludeTypes)) {
+                continue;
+            }
+            // Filter dependencies
+            const filteredDeps = new Set();
+            for (const dep of deps) {
+                if (opts.includeTypes && !this.matchesType(dep, opts.includeTypes)) {
+                    continue;
+                }
+                if (opts.excludeTypes && this.matchesType(dep, opts.excludeTypes)) {
+                    continue;
+                }
+                filteredDeps.add(dep);
+            }
+            filtered.set(nodeId, filteredDeps);
+        }
+        return filtered;
+    }
+    /**
+     * Check if node matches any of the given types
+     */
+    matchesType(nodeId, types) {
+        const nodeType = nodeId.split(':')[0];
+        return types.includes(nodeType);
+    }
+    /**
+     * Get Mermaid node styling
+     */
+    getMermaidNodeStyle(nodeId, criticalSet) {
+        if (criticalSet.has(nodeId)) {
+            return ':::critical';
+        }
+        return ':::normal';
+    }
+    /**
+     * Get DOT color for node
+     */
+    getDotColor(nodeId, criticalSet) {
+        if (criticalSet.has(nodeId)) {
+            return '#ff6b6b';
+        }
+        const type = nodeId.split(':')[0];
+        return TYPE_COLORS[type] ?? '#e0e0e0';
+    }
+    /**
+     * Get node label (short name)
+     */
+    getNodeLabel(nodeId) {
+        const parts = nodeId.split(':');
+        return parts.length === 2 ? parts[1] : nodeId;
+    }
+    /**
+     * Escape node ID for Mermaid
+     */
+    escapeNodeId(nodeId) {
+        return nodeId.replace(/:/g, '_');
+    }
+    /**
+     * Check if node has incoming edges
+     */
+    hasIncomingEdge(nodeId, graph) {
+        for (const deps of graph.values()) {
+            if (deps.has(nodeId)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    /**
+     * Find a suitable root node for ASCII tree
+     */
+    findRootNode(graph) {
+        // Find node with most dependencies
+        let maxDeps = 0;
+        let root;
+        for (const [nodeId, deps] of graph.entries()) {
+            if (deps.size > maxDeps) {
+                maxDeps = deps.size;
+                root = nodeId;
+            }
+        }
+        return root;
+    }
+    /**
+     * Get graph statistics
+     */
+    getStats() {
+        let edges = 0;
+        for (const deps of this.graph.values()) {
+            edges += deps.size;
+        }
+        return { nodes: this.graph.size, edges };
+    }
+}
+//# sourceMappingURL=graph-visualizer.js.map