@jterrats/smart-deployment 1.0.3

package/lib/utils/performance.d.ts

@@ -0,0 +1,148 @@
+/**
+ * Performance Monitoring Utilities
+ *
+ * Provides execution time tracking, memory profiling, and bottleneck identification
+ */
+export type PerformanceMetrics = {
+    /** Operation name */
+    operation: string;
+    /** Start timestamp (ms since epoch) */
+    startTime: number;
+    /** End timestamp (ms since epoch) */
+    endTime?: number;
+    /** Duration in milliseconds */
+    duration?: number;
+    /** Memory usage at start (bytes) */
+    memoryStart: number;
+    /** Memory usage at end (bytes) */
+    memoryEnd?: number;
+    /** Memory delta (bytes) */
+    memoryDelta?: number;
+    /** Additional metadata */
+    metadata?: Record<string, unknown>;
+};
+export type PerformanceReport = {
+    /** Total operations tracked */
+    totalOperations: number;
+    /** Total execution time (ms) */
+    totalDuration: number;
+    /** Average execution time (ms) */
+    averageDuration: number;
+    /** Slowest operation */
+    slowest: PerformanceMetrics | null;
+    /** Fastest operation */
+    fastest: PerformanceMetrics | null;
+    /** All operations sorted by duration */
+    operations: PerformanceMetrics[];
+    /** Bottlenecks (operations > 2x average) */
+    bottlenecks: PerformanceMetrics[];
+    /** Memory statistics */
+    memory: {
+        totalAllocated: number;
+        averageAllocated: number;
+        peakUsage: number;
+    };
+};
+/**
+ * Performance Monitor Singleton
+ *
+ * @ac US-012-AC-1: Execution time tracking
+ * @ac US-012-AC-2: Memory usage tracking
+ * @ac US-012-AC-3: Operation profiling
+ */
+declare class PerformanceMonitor {
+    private static instance;
+    private metrics;
+    private completedMetrics;
+    private constructor();
+    static getInstance(): PerformanceMonitor;
+    /**
+     * Reset singleton instance (for testing)
+     */
+    static resetInstance(): void;
+    /**
+     * Start tracking an operation
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    start(operation: string, metadata?: Record<string, unknown>): string;
+    /**
+     * End tracking an operation
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    end(id: string): PerformanceMetrics | null;
+    /**
+     * Track a synchronous function execution
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-3: Operation profiling
+     */
+    track<T>(operation: string, fn: () => T, metadata?: Record<string, unknown>): T;
+    /**
+     * Track an asynchronous function execution
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-3: Operation profiling
+     */
+    trackAsync<T>(operation: string, fn: () => Promise<T>, metadata?: Record<string, unknown>): Promise<T>;
+    /**
+     * Generate performance report
+     *
+     * @ac US-012-AC-4: Performance reports
+     * @ac US-012-AC-5: Bottleneck identification
+     */
+    generateReport(): PerformanceReport;
+    /**
+     * Get metrics for a specific operation
+     *
+     * @ac US-012-AC-3: Operation profiling
+     */
+    getOperationMetrics(operationName: string): PerformanceMetrics[];
+    /**
+     * Compare two operations (benchmarking)
+     *
+     * @ac US-012-AC-6: Benchmark comparisons
+     */
+    compare(operation1: string, operation2: string): {
+        operation1: PerformanceMetrics[];
+        operation2: PerformanceMetrics[];
+        comparison: {
+            averageDuration1: number;
+            averageDuration2: number;
+            faster: string;
+            speedup: number;
+            memoryDiff: number;
+        };
+    };
+    /**
+     * Clear all metrics
+     */
+    clear(): void;
+    /**
+     * Get current memory usage
+     *
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    private getMemoryUsage;
+    /**
+     * Format bytes to human-readable string
+     */
+    private formatBytes;
+}
+export declare const performanceMonitor: PerformanceMonitor;
+/**
+ * Decorator for tracking method execution time
+ *
+ * @ac US-012-AC-3: Operation profiling
+ */
+export declare function Profile(operationName?: string): (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => void;
+/**
+ * Decorator for tracking async method execution time
+ *
+ * @ac US-012-AC-3: Operation profiling
+ */
+export declare function ProfileAsync(operationName?: string): (target: unknown, propertyKey: string, descriptor: PropertyDescriptor) => void;
+export {};

package/lib/utils/performance.js

@@ -0,0 +1,294 @@
+/**
+ * Performance Monitoring Utilities
+ *
+ * Provides execution time tracking, memory profiling, and bottleneck identification
+ */
+import { getLogger } from './logger.js';
+const logger = getLogger('PerformanceMonitor');
+/**
+ * Performance Monitor Singleton
+ *
+ * @ac US-012-AC-1: Execution time tracking
+ * @ac US-012-AC-2: Memory usage tracking
+ * @ac US-012-AC-3: Operation profiling
+ */
+class PerformanceMonitor {
+    static instance;
+    metrics = new Map();
+    completedMetrics = [];
+    constructor() {
+        logger.debug('Performance Monitor initialized');
+    }
+    static getInstance() {
+        if (!PerformanceMonitor.instance) {
+            PerformanceMonitor.instance = new PerformanceMonitor();
+        }
+        return PerformanceMonitor.instance;
+    }
+    /**
+     * Reset singleton instance (for testing)
+     */
+    static resetInstance() {
+        if (PerformanceMonitor.instance) {
+            PerformanceMonitor.instance.clear();
+        }
+        // @ts-expect-error - Resetting singleton for tests
+        PerformanceMonitor.instance = undefined;
+    }
+    /**
+     * Start tracking an operation
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    start(operation, metadata) {
+        const id = `${operation}-${Date.now()}-${Math.random().toString(36).slice(2, 9)}`;
+        const metric = {
+            operation,
+            startTime: Date.now(),
+            memoryStart: this.getMemoryUsage(),
+            metadata,
+        };
+        this.metrics.set(id, metric);
+        logger.debug(`Performance tracking started: ${operation}`, { id, metadata });
+        return id;
+    }
+    /**
+     * End tracking an operation
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    end(id) {
+        const metric = this.metrics.get(id);
+        if (!metric) {
+            logger.warn(`Performance metric not found: ${id}`);
+            return null;
+        }
+        metric.endTime = Date.now();
+        metric.duration = metric.endTime - metric.startTime;
+        metric.memoryEnd = this.getMemoryUsage();
+        metric.memoryDelta = metric.memoryEnd - metric.memoryStart;
+        this.completedMetrics.push(metric);
+        this.metrics.delete(id);
+        logger.debug(`Performance tracking ended: ${metric.operation}`, {
+            duration: `${metric.duration}ms`,
+            memoryDelta: this.formatBytes(metric.memoryDelta),
+        });
+        return metric;
+    }
+    /**
+     * Track a synchronous function execution
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-3: Operation profiling
+     */
+    track(operation, fn, metadata) {
+        const id = this.start(operation, metadata);
+        try {
+            const result = fn();
+            this.end(id);
+            return result;
+        }
+        catch (error) {
+            this.end(id);
+            throw error;
+        }
+    }
+    /**
+     * Track an asynchronous function execution
+     *
+     * @ac US-012-AC-1: Execution time tracking
+     * @ac US-012-AC-3: Operation profiling
+     */
+    async trackAsync(operation, fn, metadata) {
+        const id = this.start(operation, metadata);
+        try {
+            const result = await fn();
+            this.end(id);
+            return result;
+        }
+        catch (error) {
+            this.end(id);
+            throw error;
+        }
+    }
+    /**
+     * Generate performance report
+     *
+     * @ac US-012-AC-4: Performance reports
+     * @ac US-012-AC-5: Bottleneck identification
+     */
+    generateReport() {
+        const operations = [...this.completedMetrics].filter((m) => m.duration !== undefined);
+        if (operations.length === 0) {
+            return {
+                totalOperations: 0,
+                totalDuration: 0,
+                averageDuration: 0,
+                slowest: null,
+                fastest: null,
+                operations: [],
+                bottlenecks: [],
+                memory: {
+                    totalAllocated: 0,
+                    averageAllocated: 0,
+                    peakUsage: 0,
+                },
+            };
+        }
+        // Sort by duration (slowest first)
+        operations.sort((a, b) => (b.duration ?? 0) - (a.duration ?? 0));
+        const totalDuration = operations.reduce((sum, op) => sum + (op.duration ?? 0), 0);
+        const averageDuration = totalDuration / operations.length;
+        // Ignore timer jitter for sub-5ms work; otherwise short operations with 0/1ms
+        // variance produce false bottlenecks in CI.
+        const bottlenecks = operations.filter((op) => {
+            const duration = op.duration ?? 0;
+            return duration >= 5 && duration > averageDuration * 2;
+        });
+        // Memory statistics
+        const memoryDeltas = operations.map((op) => op.memoryDelta ?? 0);
+        const totalMemory = memoryDeltas.reduce((sum, delta) => sum + delta, 0);
+        const peakMemory = Math.max(...operations.map((op) => op.memoryEnd ?? 0));
+        const report = {
+            totalOperations: operations.length,
+            totalDuration,
+            averageDuration,
+            slowest: operations[0] ?? null,
+            fastest: operations[operations.length - 1] ?? null,
+            operations,
+            bottlenecks,
+            memory: {
+                totalAllocated: totalMemory,
+                averageAllocated: totalMemory / operations.length,
+                peakUsage: peakMemory,
+            },
+        };
+        logger.info('Performance report generated', {
+            totalOperations: report.totalOperations,
+            totalDuration: `${report.totalDuration.toFixed(2)}ms`,
+            averageDuration: `${report.averageDuration.toFixed(2)}ms`,
+            bottlenecks: report.bottlenecks.length,
+        });
+        return report;
+    }
+    /**
+     * Get metrics for a specific operation
+     *
+     * @ac US-012-AC-3: Operation profiling
+     */
+    getOperationMetrics(operationName) {
+        return this.completedMetrics.filter((m) => m.operation === operationName);
+    }
+    /**
+     * Compare two operations (benchmarking)
+     *
+     * @ac US-012-AC-6: Benchmark comparisons
+     */
+    compare(operation1, operation2) {
+        const metrics1 = this.getOperationMetrics(operation1);
+        const metrics2 = this.getOperationMetrics(operation2);
+        const avgDuration1 = metrics1.reduce((sum, m) => sum + (m.duration ?? 0), 0) / (metrics1.length || 1);
+        const avgDuration2 = metrics2.reduce((sum, m) => sum + (m.duration ?? 0), 0) / (metrics2.length || 1);
+        const avgMemory1 = metrics1.reduce((sum, m) => sum + (m.memoryDelta ?? 0), 0) / (metrics1.length || 1);
+        const avgMemory2 = metrics2.reduce((sum, m) => sum + (m.memoryDelta ?? 0), 0) / (metrics2.length || 1);
+        const faster = avgDuration1 < avgDuration2 ? operation1 : operation2;
+        const speedup = Math.abs(avgDuration2 / avgDuration1);
+        logger.info(`Benchmark comparison: ${operation1} vs ${operation2}`, {
+            faster,
+            speedup: `${speedup.toFixed(2)}x`,
+            avgDuration1: `${avgDuration1.toFixed(2)}ms`,
+            avgDuration2: `${avgDuration2.toFixed(2)}ms`,
+        });
+        return {
+            operation1: metrics1,
+            operation2: metrics2,
+            comparison: {
+                averageDuration1: avgDuration1,
+                averageDuration2: avgDuration2,
+                faster,
+                speedup,
+                memoryDiff: avgMemory2 - avgMemory1,
+            },
+        };
+    }
+    /**
+     * Clear all metrics
+     */
+    clear() {
+        this.metrics.clear();
+        this.completedMetrics = [];
+        logger.debug('Performance metrics cleared');
+    }
+    /**
+     * Get current memory usage
+     *
+     * @ac US-012-AC-2: Memory usage tracking
+     */
+    // eslint-disable-next-line class-methods-use-this
+    getMemoryUsage() {
+        return process?.memoryUsage?.()?.heapUsed ?? 0;
+    }
+    /**
+     * Format bytes to human-readable string
+     */
+    formatBytes(bytes) {
+        if (bytes === 0)
+            return '0 Bytes';
+        if (bytes < 0)
+            return `-${this.formatBytes(-bytes)}`;
+        const k = 1024;
+        const sizes = ['Bytes', 'KB', 'MB', 'GB'];
+        const i = Math.floor(Math.log(Math.abs(bytes)) / Math.log(k));
+        return `${(bytes / Math.pow(k, i)).toFixed(2)} ${sizes[i]}`;
+    }
+}
+// Export singleton instance
+export const performanceMonitor = PerformanceMonitor.getInstance();
+/**
+ * Decorator for tracking method execution time
+ *
+ * @ac US-012-AC-3: Operation profiling
+ */
+export function Profile(operationName) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const operation = operationName ??
+            `${target?.constructor?.name ?? 'Unknown'}.${propertyKey}`;
+        const profiledMethod = function (...args) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return performanceMonitor.track(operation, () => originalMethod.apply(this, args));
+        };
+        Object.defineProperty(descriptor, 'value', {
+            configurable: true,
+            enumerable: descriptor.enumerable ?? false,
+            writable: true,
+            value: profiledMethod,
+        });
+    };
+}
+/**
+ * Decorator for tracking async method execution time
+ *
+ * @ac US-012-AC-3: Operation profiling
+ */
+export function ProfileAsync(operationName) {
+    return function (target, propertyKey, descriptor) {
+        const originalMethod = descriptor.value;
+        const operation = operationName ??
+            `${target?.constructor?.name ?? 'Unknown'}.${propertyKey}`;
+        const profiledMethod = async function (...args) {
+            // eslint-disable-next-line @typescript-eslint/no-unsafe-return
+            return performanceMonitor.trackAsync(operation, () => originalMethod.apply(this, args));
+        };
+        Object.defineProperty(descriptor, 'value', {
+            configurable: true,
+            enumerable: descriptor.enumerable ?? false,
+            writable: true,
+            value: profiledMethod,
+        });
+    };
+}
+logger.debug('Performance monitoring utilities loaded');
+//# sourceMappingURL=performance.js.map

package/lib/utils/performance.js.map

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

package/lib/utils/string.d.ts

@@ -0,0 +1,197 @@
+/**
+ * String Utilities
+ *
+ * Provides string manipulation functions for metadata processing
+ */
+/**
+ * Convert string to camelCase
+ *
+ * @ac US-011-AC-1: Case conversions (camelCase, PascalCase, snake_case)
+ * @example
+ * toCamelCase('hello_world') // 'helloWorld'
+ * toCamelCase('HelloWorld') // 'helloWorld'
+ */
+export declare function toCamelCase(str: string): string;
+/**
+ * Convert string to PascalCase
+ *
+ * @ac US-011-AC-1: Case conversions (camelCase, PascalCase, snake_case)
+ * @example
+ * toPascalCase('hello_world') // 'HelloWorld'
+ * toPascalCase('helloWorld') // 'HelloWorld'
+ */
+export declare function toPascalCase(str: string): string;
+/**
+ * Convert string to snake_case
+ *
+ * @ac US-011-AC-1: Case conversions (camelCase, PascalCase, snake_case)
+ * @example
+ * toSnakeCase('helloWorld') // 'hello_world'
+ * toSnakeCase('HelloWorld') // 'hello_world'
+ */
+export declare function toSnakeCase(str: string): string;
+/**
+ * Convert string to kebab-case
+ *
+ * @ac US-011-AC-1: Case conversions (camelCase, PascalCase, snake_case)
+ * @example
+ * toKebabCase('helloWorld') // 'hello-world'
+ * toKebabCase('hello_world') // 'hello-world'
+ */
+export declare function toKebabCase(str: string): string;
+/**
+ * Extract comments from Apex code
+ *
+ * @ac US-011-AC-2: Extract comments from Apex/JavaScript
+ * @example
+ * extractApexComments('// comment\ncode') // ['// comment']
+ */
+export declare function extractApexComments(code: string): string[];
+/**
+ * Extract comments from JavaScript code
+ *
+ * @ac US-011-AC-2: Extract comments from Apex/JavaScript
+ * @example
+ * extractJavaScriptComments('/* comment *\/\ncode') // ['/* comment *\/']
+ */
+export declare function extractJavaScriptComments(code: string): string[];
+/**
+ * Escape XML special characters
+ *
+ * @ac US-011-AC-3: Escape/unescape XML special characters
+ * @example
+ * escapeXml('<tag>value & "quoted"</tag>') // '&lt;tag&gt;value &amp; &quot;quoted&quot;&lt;/tag&gt;'
+ */
+export declare function escapeXml(str: string): string;
+/**
+ * Unescape XML special characters
+ *
+ * @ac US-011-AC-3: Escape/unescape XML special characters
+ * @example
+ * unescapeXml('&lt;tag&gt;value &amp; &quot;quoted&quot;&lt;/tag&gt;') // '<tag>value & "quoted"</tag>'
+ */
+export declare function unescapeXml(str: string): string;
+/**
+ * Common regex patterns for Salesforce
+ *
+ * @ac US-011-AC-4: Regex utilities for common patterns
+ */
+export declare const REGEX_PATTERNS: {
+    /** Salesforce API name (letters, numbers, underscores, starts with letter) */
+    readonly SALESFORCE_API_NAME: RegExp;
+    /** Salesforce Email (standard email pattern) */
+    readonly EMAIL: RegExp;
+    /** Salesforce 15/18 character ID */
+    readonly SALESFORCE_ID: RegExp;
+    /** Salesforce namespace prefix */
+    readonly NAMESPACE_PREFIX: RegExp;
+    /** Custom field suffix */
+    readonly CUSTOM_FIELD_SUFFIX: RegExp;
+    /** Custom object suffix */
+    readonly CUSTOM_OBJECT_SUFFIX: RegExp;
+    /** Metadata file extension */
+    readonly METADATA_FILE: RegExp;
+    /** Version number (semantic versioning) */
+    readonly VERSION: RegExp;
+};
+/**
+ * Validate Salesforce API name
+ *
+ * @ac US-011-AC-4: Regex utilities for common patterns
+ * @example
+ * isValidSalesforceApiName('MyField__c') // true
+ * isValidSalesforceApiName('123Invalid') // false
+ */
+export declare function isValidSalesforceApiName(name: string): boolean;
+/**
+ * Validate email address
+ *
+ * @ac US-011-AC-4: Regex utilities for common patterns
+ * @example
+ * isValidEmail('user@example.com') // true
+ * isValidEmail('invalid-email') // false
+ */
+export declare function isValidEmail(email: string): boolean;
+/**
+ * Normalize Unicode string (NFC normalization)
+ *
+ * @ac US-011-AC-5: Unicode handling
+ * @example
+ * normalizeUnicode('café') // Normalized form
+ */
+export declare function normalizeUnicode(str: string): string;
+/**
+ * Strip accents from Unicode string
+ *
+ * @ac US-011-AC-5: Unicode handling
+ * @example
+ * stripAccents('café') // 'cafe'
+ * stripAccents('naïve') // 'naive'
+ */
+export declare function stripAccents(str: string): string;
+/**
+ * Truncate string with ellipsis
+ *
+ * @example
+ * truncate('Hello World', 8) // 'Hello...'
+ * truncate('Short', 10) // 'Short'
+ */
+export declare function truncate(str: string, maxLength: number, ellipsis?: string): string;
+/**
+ * Pluralize word (simple English rules)
+ *
+ * @example
+ * pluralize('field') // 'fields'
+ * pluralize('class') // 'classes'
+ * pluralize('entry') // 'entries'
+ */
+export declare function pluralize(word: string): string;
+/**
+ * Singularize word (simple English rules)
+ *
+ * @example
+ * singularize('fields') // 'field'
+ * singularize('classes') // 'class'
+ * singularize('entries') // 'entry'
+ */
+export declare function singularize(word: string): string;
+/**
+ * Convert string to title case
+ *
+ * @example
+ * toTitleCase('hello world') // 'Hello World'
+ * toTitleCase('HELLO WORLD') // 'Hello World'
+ */
+export declare function toTitleCase(str: string): string;
+/**
+ * Remove multiple consecutive spaces
+ *
+ * @example
+ * normalizeWhitespace('hello    world') // 'hello world'
+ * normalizeWhitespace('  spaces  ') // 'spaces'
+ */
+export declare function normalizeWhitespace(str: string): string;
+/**
+ * Extract namespace from Salesforce API name
+ *
+ * @example
+ * extractNamespace('MyNamespace__CustomObject__c') // 'MyNamespace'
+ * extractNamespace('StandardObject') // null
+ */
+export declare function extractNamespace(apiName: string): string | null;
+/**
+ * Check if API name is custom (ends with __c)
+ *
+ * @example
+ * isCustom('MyField__c') // true
+ * isCustom('Name') // false
+ */
+export declare function isCustom(apiName: string): boolean;
+/**
+ * Format bytes to human-readable string
+ *
+ * @example
+ * formatBytes(1024) // '1.00 KB'
+ * formatBytes(1048576) // '1.00 MB'
+ */
+export declare function formatBytes(bytes: number, decimals?: number): string;