@jterrats/smart-deployment 1.0.3

package/lib/utils/functional.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Functional Programming Utilities
+ */
+/**
+ * Executes functions left-to-right
+ *
+ * @ac US-001-AC-1
+ */
+export declare function pipe<InitialValue, FinalValue>(firstTransform: (input: InitialValue) => FinalValue | Promise<FinalValue>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function pipe<InitialValue, AfterFirst, FinalValue>(firstTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>, secondTransform: (input: AfterFirst) => FinalValue | Promise<FinalValue>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function pipe<InitialValue, AfterFirst, AfterSecond, FinalValue>(firstTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>, secondTransform: (input: AfterFirst) => AfterSecond | Promise<AfterSecond>, thirdTransform: (input: AfterSecond) => FinalValue | Promise<FinalValue>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function pipe<InitialValue, AfterFirst, AfterSecond, AfterThird, FinalValue>(firstTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>, secondTransform: (input: AfterFirst) => AfterSecond | Promise<AfterSecond>, thirdTransform: (input: AfterSecond) => AfterThird | Promise<AfterThird>, fourthTransform: (input: AfterThird) => FinalValue | Promise<FinalValue>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+/**
+ * Executes functions right-to-left
+ *
+ * @ac US-001-AC-2
+ */
+export declare function compose<InitialValue, FinalValue>(firstTransform: (input: InitialValue) => FinalValue | Promise<FinalValue>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function compose<InitialValue, AfterFirst, FinalValue>(firstTransform: (input: AfterFirst) => FinalValue | Promise<FinalValue>, secondTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function compose<InitialValue, AfterFirst, AfterSecond, FinalValue>(firstTransform: (input: AfterSecond) => FinalValue | Promise<FinalValue>, secondTransform: (input: AfterFirst) => AfterSecond | Promise<AfterSecond>, thirdTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+export declare function compose<InitialValue, AfterFirst, AfterSecond, AfterThird, FinalValue>(firstTransform: (input: AfterThird) => FinalValue | Promise<FinalValue>, secondTransform: (input: AfterSecond) => AfterThird | Promise<AfterThird>, thirdTransform: (input: AfterFirst) => AfterSecond | Promise<AfterSecond>, fourthTransform: (input: InitialValue) => AfterFirst | Promise<AfterFirst>): (input: InitialValue) => FinalValue | Promise<FinalValue>;
+/**
+ * Enables partial application
+ *
+ * @ac US-001-AC-3
+ */
+export declare function curry<FirstParameter, ReturnValue>(originalFunction: (first: FirstParameter) => ReturnValue): (first: FirstParameter) => ReturnValue;
+export declare function curry<FirstParameter, SecondParameter, ReturnValue>(originalFunction: (first: FirstParameter, second: SecondParameter) => ReturnValue): {
+    (first: FirstParameter): (second: SecondParameter) => ReturnValue;
+    (first: FirstParameter, second: SecondParameter): ReturnValue;
+};
+export declare function curry<FirstParameter, SecondParameter, ThirdParameter, ReturnValue>(originalFunction: (first: FirstParameter, second: SecondParameter, third: ThirdParameter) => ReturnValue): {
+    (first: FirstParameter): {
+        (second: SecondParameter): (third: ThirdParameter) => ReturnValue;
+        (second: SecondParameter, third: ThirdParameter): ReturnValue;
+    };
+    (first: FirstParameter, second: SecondParameter): (third: ThirdParameter) => ReturnValue;
+    (first: FirstParameter, second: SecondParameter, third: ThirdParameter): ReturnValue;
+};
+/**
+ * Memoization options
+ */
+export type MemoizeOptions = {
+    maxSize?: number;
+    keyGenerator?: (...parameters: unknown[]) => string;
+};
+/**
+ * Caches results based on arguments
+ *
+ * @ac US-001-AC-4
+ */
+export declare function memoize<ExpensiveFunction extends (...parameters: any[]) => any>(expensiveFunction: ExpensiveFunction, options?: MemoizeOptions): ExpensiveFunction;

package/lib/utils/functional.js

@@ -0,0 +1,61 @@
+/**
+ * Functional Programming Utilities
+ */
+export function pipe(...transformations) {
+    if (transformations.length === 0) {
+        return (input) => input;
+    }
+    return (initialValue) => {
+        let currentValue = initialValue;
+        for (const transform of transformations) {
+            if (currentValue instanceof Promise) {
+                currentValue = currentValue.then(transform);
+            }
+            else {
+                currentValue = transform(currentValue);
+            }
+        }
+        return currentValue;
+    };
+}
+export function compose(...transformations) {
+    return pipe(...transformations.reverse());
+}
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument */
+export function curry(originalFunction) {
+    return function curriedFunction(...providedParameters) {
+        if (providedParameters.length >= originalFunction.length) {
+            return originalFunction(...providedParameters);
+        }
+        return (...remainingParameters) => curriedFunction(...providedParameters, ...remainingParameters);
+    };
+}
+/**
+ * Caches results based on arguments
+ *
+ * @ac US-001-AC-4
+ */
+/* eslint-disable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment */
+export function memoize(expensiveFunction, options = {}) {
+    const { maxSize = Infinity, keyGenerator = JSON.stringify } = options;
+    const cachedResults = new Map();
+    const accessOrder = [];
+    return ((...parameters) => {
+        const cacheKey = keyGenerator(...parameters);
+        if (cachedResults.has(cacheKey)) {
+            return cachedResults.get(cacheKey);
+        }
+        const computedValue = expensiveFunction(...parameters);
+        if (cachedResults.size >= maxSize) {
+            const oldestKey = accessOrder.shift();
+            if (oldestKey !== undefined) {
+                cachedResults.delete(oldestKey);
+            }
+        }
+        cachedResults.set(cacheKey, computedValue);
+        accessOrder.push(cacheKey);
+        return computedValue;
+    });
+}
+/* eslint-enable @typescript-eslint/no-explicit-any, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-argument, @typescript-eslint/no-unsafe-assignment */
+//# sourceMappingURL=functional.js.map

package/lib/utils/functional.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"functional.js","sourceRoot":"","sources":["../../src/utils/functional.ts"],"names":[],"mappings":"AAAA;;GAEG;AAyBH,MAAM,UAAU,IAAI,CAAC,GAAG,eAAmD;IACzE,IAAI,eAAe,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACjC,OAAO,CAAC,KAAc,EAAE,EAAE,CAAC,KAAK,CAAC;IACnC,CAAC;IAED,OAAO,CAAC,YAAqB,EAAE,EAAE;QAC/B,IAAI,YAAY,GAAY,YAAY,CAAC;QAEzC,KAAK,MAAM,SAAS,IAAI,eAAe,EAAE,CAAC;YACxC,IAAI,YAAY,YAAY,OAAO,EAAE,CAAC;gBACpC,YAAY,GAAG,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;YAC9C,CAAC;iBAAM,CAAC;gBACN,YAAY,GAAG,SAAS,CAAC,YAAY,CAAC,CAAC;YACzC,CAAC;QACH,CAAC;QAED,OAAO,YAAY,CAAC;IACtB,CAAC,CAAC;AACJ,CAAC;AAyBD,MAAM,UAAU,OAAO,CAAC,GAAG,eAAmD;IAC5E,OAAO,IAAI,CAAC,GAAI,eAAe,CAAC,OAAO,EAAoC,CAAC,CAAC;AAC/E,CAAC;AA0BD,mIAAmI;AACnI,MAAM,UAAU,KAAK,CAAC,gBAA+C;IACnE,OAAO,SAAS,eAAe,CAAC,GAAG,kBAAyB;QAC1D,IAAI,kBAAkB,CAAC,MAAM,IAAI,gBAAgB,CAAC,MAAM,EAAE,CAAC;YACzD,OAAO,gBAAgB,CAAC,GAAG,kBAAkB,CAAC,CAAC;QACjD,CAAC;QAED,OAAO,CAAC,GAAG,mBAA0B,EAAE,EAAE,CAAC,eAAe,CAAC,GAAG,kBAAkB,EAAE,GAAG,mBAAmB,CAAC,CAAC;IAC3G,CAAC,CAAC;AACJ,CAAC;AAWD;;;;GAIG;AACH,4KAA4K;AAC5K,MAAM,UAAU,OAAO,CACrB,iBAAoC,EACpC,UAA0B,EAAE;IAE5B,MAAM,EAAE,OAAO,GAAG,QAAQ,EAAE,YAAY,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,OAAO,CAAC;IAEtE,MAAM,aAAa,GAAG,IAAI,GAAG,EAAyC,CAAC;IACvE,MAAM,WAAW,GAAa,EAAE,CAAC;IAEjC,OAAO,CAAC,CAAC,GAAG,UAAiB,EAAO,EAAE;QACpC,MAAM,QAAQ,GAAG,YAAY,CAAC,GAAI,UAAwB,CAAC,CAAC;QAE5D,IAAI,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;YAChC,OAAO,aAAa,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;QACtC,CAAC;QAED,MAAM,aAAa,GAAG,iBAAiB,CAAC,GAAG,UAAU,CAAC,CAAC;QAEvD,IAAI,aAAa,CAAC,IAAI,IAAI,OAAO,EAAE,CAAC;YAClC,MAAM,SAAS,GAAG,WAAW,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,SAAS,KAAK,SAAS,EAAE,CAAC;gBAC5B,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;YAClC,CAAC;QACH,CAAC;QAED,aAAa,CAAC,GAAG,CAAC,QAAQ,EAAE,aAAa,CAAC,CAAC;QAC3C,WAAW,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;QAE3B,OAAO,aAAa,CAAC;IACvB,CAAC,CAAsB,CAAC;AAC1B,CAAC;AACD,2KAA2K"}

package/lib/utils/graph-algorithms.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Graph Algorithms for Dependency Analysis
+ *
+ * Provides efficient algorithms for analyzing metadata dependency graphs:
+ * - Topological sorting for deployment ordering
+ * - Cycle detection for identifying circular dependencies
+ * - Depth calculation for determining deployment waves
+ * - Path finding for dependency tracing
+ */
+export type NodeId = string;
+export type GraphNode = {
+    nodeId: NodeId;
+    dependencies: Set<NodeId>;
+};
+export type DependencyGraph = Map<NodeId, GraphNode>;
+export type CycleDetectionResult = {
+    hasCycles: boolean;
+    cycles: NodeId[][];
+};
+/**
+ * Performs topological sort using Kahn's algorithm (BFS-based)
+ *
+ * @ac US-002-AC-1
+ * @param dependencyGraph - Graph where edges represent dependencies
+ * @returns Array of node IDs in topological order (dependencies first)
+ */
+export declare function topologicalSort(dependencyGraph: DependencyGraph): NodeId[];
+/**
+ * Detects cycles using Depth-First Search with color marking
+ *
+ * @ac US-002-AC-2
+ * @param dependencyGraph - Graph to analyze for cycles
+ * @returns Detection result with all found cycles
+ */
+export declare function detectCycles(dependencyGraph: DependencyGraph): CycleDetectionResult;
+/**
+ * Calculates dependency depth (longest path from root)
+ *
+ * @ac US-002-AC-3
+ * @param dependencyGraph - Graph to analyze
+ * @returns Map of node ID to its depth level
+ */
+export declare function calculateDepth(dependencyGraph: DependencyGraph): Map<NodeId, number>;
+/**
+ * Finds shortest path between two nodes using BFS
+ *
+ * @ac US-002-AC-4
+ * @param dependencyGraph - Graph to search
+ * @param startNodeId - Starting node
+ * @param targetNodeId - Target node to find
+ * @returns Array representing path from start to target, or null if no path exists
+ */
+export declare function findPath(dependencyGraph: DependencyGraph, startNodeId: NodeId, targetNodeId: NodeId): NodeId[] | null;

package/lib/utils/graph-algorithms.js

@@ -0,0 +1,177 @@
+/**
+ * Graph Algorithms for Dependency Analysis
+ *
+ * Provides efficient algorithms for analyzing metadata dependency graphs:
+ * - Topological sorting for deployment ordering
+ * - Cycle detection for identifying circular dependencies
+ * - Depth calculation for determining deployment waves
+ * - Path finding for dependency tracing
+ */
+/**
+ * Performs topological sort using Kahn's algorithm (BFS-based)
+ *
+ * @ac US-002-AC-1
+ * @param dependencyGraph - Graph where edges represent dependencies
+ * @returns Array of node IDs in topological order (dependencies first)
+ */
+export function topologicalSort(dependencyGraph) {
+    const sortedNodes = [];
+    const remainingDependencies = new Map();
+    const readyQueue = [];
+    // Initialize: copy all dependencies
+    for (const [nodeId, graphNode] of dependencyGraph) {
+        remainingDependencies.set(nodeId, new Set(graphNode.dependencies));
+    }
+    // Find all nodes with no dependencies (ready to process)
+    for (const [nodeId, dependencies] of remainingDependencies) {
+        if (dependencies.size === 0) {
+            readyQueue.push(nodeId);
+        }
+    }
+    // Process nodes in topological order
+    while (readyQueue.length > 0) {
+        const currentNodeId = readyQueue.shift();
+        sortedNodes.push(currentNodeId);
+        // Remove this node from all other nodes' dependencies
+        for (const [nodeId, dependencies] of remainingDependencies) {
+            if (dependencies.has(currentNodeId)) {
+                dependencies.delete(currentNodeId);
+                // If node now has no dependencies, add to ready queue
+                if (dependencies.size === 0 && !sortedNodes.includes(nodeId)) {
+                    readyQueue.push(nodeId);
+                }
+            }
+        }
+    }
+    return sortedNodes;
+}
+/**
+ * Detects cycles using Depth-First Search with color marking
+ *
+ * @ac US-002-AC-2
+ * @param dependencyGraph - Graph to analyze for cycles
+ * @returns Detection result with all found cycles
+ */
+export function detectCycles(dependencyGraph) {
+    const visitedNodes = new Set();
+    const recursionStack = new Set();
+    const discoveredCycles = [];
+    const pathToNode = [];
+    function depthFirstSearch(currentNodeId) {
+        visitedNodes.add(currentNodeId);
+        recursionStack.add(currentNodeId);
+        pathToNode.push(currentNodeId);
+        const currentNode = dependencyGraph.get(currentNodeId);
+        if (currentNode) {
+            for (const dependencyId of currentNode.dependencies) {
+                if (!visitedNodes.has(dependencyId)) {
+                    if (depthFirstSearch(dependencyId)) {
+                        return true; // Cycle found in subtree
+                    }
+                }
+                else if (recursionStack.has(dependencyId)) {
+                    // Found a cycle!
+                    const cycleStartIndex = pathToNode.indexOf(dependencyId);
+                    const cycleNodes = pathToNode.slice(cycleStartIndex);
+                    discoveredCycles.push(cycleNodes);
+                    return true;
+                }
+            }
+        }
+        recursionStack.delete(currentNodeId);
+        pathToNode.pop();
+        return false;
+    }
+    for (const [nodeId] of dependencyGraph) {
+        if (!visitedNodes.has(nodeId)) {
+            depthFirstSearch(nodeId);
+            pathToNode.length = 0; // Clear path for next component
+        }
+    }
+    return {
+        hasCycles: discoveredCycles.length > 0,
+        cycles: discoveredCycles,
+    };
+}
+/**
+ * Calculates dependency depth (longest path from root)
+ *
+ * @ac US-002-AC-3
+ * @param dependencyGraph - Graph to analyze
+ * @returns Map of node ID to its depth level
+ */
+export function calculateDepth(dependencyGraph) {
+    const depthMap = new Map();
+    const visitedNodes = new Set();
+    function calculateNodeDepth(nodeId) {
+        if (depthMap.has(nodeId)) {
+            return depthMap.get(nodeId);
+        }
+        if (visitedNodes.has(nodeId)) {
+            // Circular dependency, return large number
+            return Infinity;
+        }
+        visitedNodes.add(nodeId);
+        const currentNode = dependencyGraph.get(nodeId);
+        if (!currentNode || currentNode.dependencies.size === 0) {
+            depthMap.set(nodeId, 0);
+            visitedNodes.delete(nodeId);
+            return 0;
+        }
+        let maximumDepth = 0;
+        for (const dependencyId of currentNode.dependencies) {
+            const dependencyDepth = calculateNodeDepth(dependencyId);
+            maximumDepth = Math.max(maximumDepth, dependencyDepth + 1);
+        }
+        depthMap.set(nodeId, maximumDepth);
+        visitedNodes.delete(nodeId);
+        return maximumDepth;
+    }
+    for (const [nodeId] of dependencyGraph) {
+        if (!depthMap.has(nodeId)) {
+            calculateNodeDepth(nodeId);
+        }
+    }
+    return depthMap;
+}
+/**
+ * Finds shortest path between two nodes using BFS
+ *
+ * @ac US-002-AC-4
+ * @param dependencyGraph - Graph to search
+ * @param startNodeId - Starting node
+ * @param targetNodeId - Target node to find
+ * @returns Array representing path from start to target, or null if no path exists
+ */
+export function findPath(dependencyGraph, startNodeId, targetNodeId) {
+    if (startNodeId === targetNodeId) {
+        return [startNodeId];
+    }
+    const visitedNodes = new Set();
+    const searchQueue = [
+        { currentNodeId: startNodeId, pathSoFar: [startNodeId] },
+    ];
+    while (searchQueue.length > 0) {
+        const { currentNodeId, pathSoFar } = searchQueue.shift();
+        if (visitedNodes.has(currentNodeId)) {
+            continue;
+        }
+        visitedNodes.add(currentNodeId);
+        const currentNode = dependencyGraph.get(currentNodeId);
+        if (!currentNode)
+            continue;
+        for (const dependencyId of currentNode.dependencies) {
+            if (dependencyId === targetNodeId) {
+                return [...pathSoFar, dependencyId];
+            }
+            if (!visitedNodes.has(dependencyId)) {
+                searchQueue.push({
+                    currentNodeId: dependencyId,
+                    pathSoFar: [...pathSoFar, dependencyId],
+                });
+            }
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=graph-algorithms.js.map

package/lib/utils/graph-algorithms.js.map

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

package/lib/utils/logger.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Log levels in order of severity
+ */
+export declare enum LogLevel {
+    DEBUG = "DEBUG",
+    INFO = "INFO",
+    WARN = "WARN",
+    ERROR = "ERROR"
+}
+/**
+ * Log entry structure
+ */
+export type LogEntry = {
+    timestamp: string;
+    level: LogLevel;
+    component: string;
+    message: string;
+    context?: Record<string, unknown>;
+    duration?: number;
+    error?: {
+        name: string;
+        message: string;
+        stack?: string;
+    };
+};
+/**
+ * Logger configuration
+ */
+export type LoggerConfig = {
+    /** Component name for context */
+    component: string;
+    /** Minimum log level to record */
+    level: LogLevel;
+    /** Enable console output */
+    logToConsole: boolean;
+    /** Enable file output */
+    logToFile: boolean;
+    /** Directory for log files */
+    logDirectory?: string;
+    /** Format: 'json' or 'text' */
+    format: 'json' | 'text';
+    /** Max log file size in MB before rotation */
+    maxLogFileSizeMB: number;
+    /** Max number of rotated log files to keep */
+    maxLogFiles: number;
+};
+/**
+ * Performance timer for measuring operation duration
+ */
+export declare class PerformanceTimer {
+    private startTime;
+    private label;
+    constructor(label: string);
+    end(): number;
+    getLabel(): string;
+}
+/**
+ * Singleton Logger with file rotation and structured logging
+ *
+ * @example
+ * ```typescript
+ * const logger = Logger.getInstance({ component: 'MyComponent' });
+ * logger.info('Operation started', { userId: 123 });
+ * logger.error('Operation failed', { error, userId: 123 });
+ *
+ * const timer = logger.startTimer('expensive-operation');
+ * // ... do work ...
+ * logger.info('Operation completed', { duration: timer.end() });
+ * ```
+ */
+export declare class Logger {
+    private static instances;
+    private config;
+    private logFilePath?;
+    private writeQueue;
+    /**
+     * Private constructor - use getInstance() instead
+     */
+    private constructor();
+    /**
+     * Get logger instance for component (one instance per component)
+     */
+    static getInstance(config: Partial<LoggerConfig> & {
+        component: string;
+    }): Logger;
+    /**
+     * Reset all instances (for testing)
+     */
+    static resetInstances(): void;
+    /**
+     * Log debug message
+     */
+    debug(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log info message
+     */
+    info(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log warning message
+     */
+    warn(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log error message
+     */
+    error(message: string, context?: Record<string, unknown>): void;
+    /**
+     * Log with timer duration
+     */
+    logWithDuration(level: LogLevel, message: string, timer: PerformanceTimer, context?: Record<string, unknown>): void;
+    /**
+     * Update logger configuration
+     */
+    configure(config: Partial<Omit<LoggerConfig, 'component'>>): void;
+    /**
+     * Get current configuration
+     */
+    getConfig(): Readonly<LoggerConfig>;
+    /**
+     * Flush any pending writes (useful for testing)
+     */
+    flush(): Promise<void>;
+    /**
+     * Core logging method
+     */
+    private log;
+    /**
+     * Log to console with color coding
+     */
+    private logToConsoleOutput;
+    /**
+     * Log to file asynchronously (queued to prevent race conditions)
+     */
+    private logToFileAsync;
+    /**
+     * Check file size and rotate if needed
+     */
+    private rotateIfNeeded;
+    /**
+     * Rotate log file
+     */
+    private rotateLogFile;
+    /**
+     * Format log entry based on configured format
+     */
+    private formatEntry;
+}
+/**
+ * Get or create logger instance
+ */
+export declare function getLogger(component: string, config?: Partial<Omit<LoggerConfig, 'component'>>): Logger;
+/**
+ * Create a performance timer for measuring operation duration
+ */
+export declare function startTimer(label: string): PerformanceTimer;