@jterrats/smart-deployment 1.0.3

package/lib/utils/error-aggregator.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Error Aggregator - US-076 Enhancement
+ * Aggregates and categorizes errors for comprehensive reporting
+ *
+ * @ac US-076-AC-5: File and line numbers
+ * @ac US-076-AC-6: Error aggregation
+ * @issue #76
+ */
+export type AggregatedError = {
+    filePath?: string;
+    lineNumber?: number;
+    columnNumber?: number;
+    errorType: string;
+    errorMessage: string;
+    severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+    timestamp: Date;
+    stack?: string;
+    context?: Record<string, unknown>;
+};
+export type ErrorStats = {
+    total: number;
+    byType: Map<string, number>;
+    bySeverity: Map<string, number>;
+    byFile: Map<string, number>;
+};
+export type ErrorReport = {
+    totalErrors: number;
+    criticalCount: number;
+    highCount: number;
+    mediumCount: number;
+    lowCount: number;
+    errors: AggregatedError[];
+    stats: ErrorStats;
+    timestamp: Date;
+};
+/**
+ * @ac US-076-AC-6: Error aggregation
+ */
+export declare class ErrorAggregator {
+    private errors;
+    private readonly maxErrors;
+    constructor(maxErrors?: number);
+    /**
+     * @ac US-076-AC-5: File and line numbers
+     * Add error with file location
+     */
+    addError(error: {
+        message: string;
+        type?: string;
+        severity?: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+        filePath?: string;
+        lineNumber?: number;
+        columnNumber?: number;
+        stack?: string;
+        context?: Record<string, unknown>;
+    }): void;
+    /**
+     * Extract file path and line number from stack trace
+     */
+    private extractLocationFromStack;
+    /**
+     * Get all aggregated errors
+     */
+    getErrors(): AggregatedError[];
+    /**
+     * Get errors filtered by severity
+     */
+    getErrorsBySeverity(severity: 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL'): AggregatedError[];
+    /**
+     * Get errors filtered by type
+     */
+    getErrorsByType(type: string): AggregatedError[];
+    /**
+     * Get errors filtered by file
+     */
+    getErrorsByFile(filePath: string): AggregatedError[];
+    /**
+     * Generate statistics
+     */
+    getStats(): ErrorStats;
+    /**
+     * Generate comprehensive error report
+     */
+    generateReport(): ErrorReport;
+    /**
+     * Format error report as human-readable string
+     */
+    formatReport(includeStackTraces?: boolean): string;
+    /**
+     * Get severity icon
+     */
+    private getSeverityIcon;
+    /**
+     * Check if there are critical errors
+     */
+    hasCriticalErrors(): boolean;
+    /**
+     * Check if there are high or critical errors
+     */
+    hasHighSeverityErrors(): boolean;
+    /**
+     * Clear all errors
+     */
+    clear(): void;
+    /**
+     * Get error count
+     */
+    getCount(): number;
+}
+/**
+ * Get global error aggregator instance
+ */
+export declare function getErrorAggregator(): ErrorAggregator;
+/**
+ * Reset global error aggregator (for testing)
+ */
+export declare function resetErrorAggregator(): void;

package/lib/utils/error-aggregator.js

@@ -0,0 +1,268 @@
+/**
+ * Error Aggregator - US-076 Enhancement
+ * Aggregates and categorizes errors for comprehensive reporting
+ *
+ * @ac US-076-AC-5: File and line numbers
+ * @ac US-076-AC-6: Error aggregation
+ * @issue #76
+ */
+import { getLogger } from './logger.js';
+const logger = getLogger('ErrorAggregator');
+/**
+ * @ac US-076-AC-6: Error aggregation
+ */
+export class ErrorAggregator {
+    errors = [];
+    maxErrors;
+    constructor(maxErrors = 1000) {
+        this.maxErrors = maxErrors;
+    }
+    /**
+     * @ac US-076-AC-5: File and line numbers
+     * Add error with file location
+     */
+    addError(error) {
+        // Extract file/line from stack if not provided
+        let { filePath, lineNumber, columnNumber } = error;
+        if (!filePath && error.stack) {
+            const location = this.extractLocationFromStack(error.stack);
+            filePath = filePath ?? location.filePath;
+            lineNumber = lineNumber ?? location.lineNumber;
+            columnNumber = columnNumber ?? location.columnNumber;
+        }
+        const aggregatedError = {
+            filePath,
+            lineNumber,
+            columnNumber,
+            errorType: error.type ?? 'UnknownError',
+            errorMessage: error.message,
+            severity: error.severity ?? 'MEDIUM',
+            timestamp: new Date(),
+            stack: error.stack,
+            context: error.context,
+        };
+        this.errors.push(aggregatedError);
+        // Trim if exceeding max
+        if (this.errors.length > this.maxErrors) {
+            this.errors.shift();
+            logger.warn('Error buffer full, dropping oldest error');
+        }
+        logger.debug('Error added to aggregator', {
+            type: aggregatedError.errorType,
+            severity: aggregatedError.severity,
+            file: filePath,
+        });
+    }
+    /**
+     * Extract file path and line number from stack trace
+     */
+    extractLocationFromStack(stack) {
+        // Match patterns like:
+        //   at Object.<anonymous> (/path/to/file.ts:123:45)
+        //   at /path/to/file.ts:123:45
+        const patterns = [
+            /\((.+):(\d+):(\d+)\)/, // (path:line:col)
+            /at (.+):(\d+):(\d+)/, // at path:line:col
+            /(.+):(\d+):(\d+)$/, // path:line:col at end
+        ];
+        for (const pattern of patterns) {
+            const match = pattern.exec(stack);
+            if (match) {
+                return {
+                    filePath: match[1],
+                    lineNumber: Number.parseInt(match[2], 10),
+                    columnNumber: Number.parseInt(match[3], 10),
+                };
+            }
+        }
+        return {};
+    }
+    /**
+     * Get all aggregated errors
+     */
+    getErrors() {
+        return [...this.errors];
+    }
+    /**
+     * Get errors filtered by severity
+     */
+    getErrorsBySeverity(severity) {
+        return this.errors.filter((e) => e.severity === severity);
+    }
+    /**
+     * Get errors filtered by type
+     */
+    getErrorsByType(type) {
+        return this.errors.filter((e) => e.errorType === type);
+    }
+    /**
+     * Get errors filtered by file
+     */
+    getErrorsByFile(filePath) {
+        return this.errors.filter((e) => e.filePath === filePath);
+    }
+    /**
+     * Generate statistics
+     */
+    getStats() {
+        const stats = {
+            total: this.errors.length,
+            byType: new Map(),
+            bySeverity: new Map(),
+            byFile: new Map(),
+        };
+        for (const error of this.errors) {
+            // Count by type
+            stats.byType.set(error.errorType, (stats.byType.get(error.errorType) ?? 0) + 1);
+            // Count by severity
+            stats.bySeverity.set(error.severity, (stats.bySeverity.get(error.severity) ?? 0) + 1);
+            // Count by file
+            if (error.filePath) {
+                stats.byFile.set(error.filePath, (stats.byFile.get(error.filePath) ?? 0) + 1);
+            }
+        }
+        return stats;
+    }
+    /**
+     * Generate comprehensive error report
+     */
+    generateReport() {
+        const stats = this.getStats();
+        return {
+            totalErrors: this.errors.length,
+            criticalCount: stats.bySeverity.get('CRITICAL') ?? 0,
+            highCount: stats.bySeverity.get('HIGH') ?? 0,
+            mediumCount: stats.bySeverity.get('MEDIUM') ?? 0,
+            lowCount: stats.bySeverity.get('LOW') ?? 0,
+            errors: this.getErrors(),
+            stats,
+            timestamp: new Date(),
+        };
+    }
+    /**
+     * Format error report as human-readable string
+     */
+    formatReport(includeStackTraces = false) {
+        const report = this.generateReport();
+        const lines = [];
+        lines.push('🚨 Error Report');
+        lines.push('═══════════════════════════════════════');
+        lines.push(`📊 Total Errors: ${report.totalErrors}`);
+        lines.push('');
+        lines.push('📈 By Severity:');
+        lines.push(`   🔴 CRITICAL: ${report.criticalCount}`);
+        lines.push(`   🟠 HIGH: ${report.highCount}`);
+        lines.push(`   🟡 MEDIUM: ${report.mediumCount}`);
+        lines.push(`   🟢 LOW: ${report.lowCount}`);
+        lines.push('');
+        if (report.stats.byType.size > 0) {
+            lines.push('🏷️  By Type:');
+            const sortedTypes = Array.from(report.stats.byType.entries()).sort((a, b) => b[1] - a[1]);
+            for (const [type, count] of sortedTypes.slice(0, 10)) {
+                lines.push(`   ${type}: ${count}`);
+            }
+            if (sortedTypes.length > 10) {
+                lines.push(`   ... and ${sortedTypes.length - 10} more`);
+            }
+            lines.push('');
+        }
+        if (report.stats.byFile.size > 0) {
+            lines.push('📁 Files with Most Errors:');
+            const sortedFiles = Array.from(report.stats.byFile.entries()).sort((a, b) => b[1] - a[1]);
+            for (const [file, count] of sortedFiles.slice(0, 10)) {
+                lines.push(`   ${file}: ${count} errors`);
+            }
+            if (sortedFiles.length > 10) {
+                lines.push(`   ... and ${sortedFiles.length - 10} more files`);
+            }
+            lines.push('');
+        }
+        // List errors (limit to first 20)
+        if (report.errors.length > 0) {
+            lines.push('📋 Error Details:');
+            const errorsToShow = report.errors.slice(0, 20);
+            for (const [index, error] of errorsToShow.entries()) {
+                const severity = this.getSeverityIcon(error.severity);
+                lines.push(`\n${index + 1}. ${severity} ${error.errorType}`);
+                lines.push(`   Message: ${error.errorMessage}`);
+                if (error.filePath) {
+                    lines.push(`   Location: ${error.filePath}:${error.lineNumber ?? '?'}:${error.columnNumber ?? '?'}`);
+                }
+                if (error.context && Object.keys(error.context).length > 0) {
+                    lines.push(`   Context: ${JSON.stringify(error.context)}`);
+                }
+                if (includeStackTraces && error.stack) {
+                    lines.push(`   Stack:\n${error.stack.split('\n').slice(0, 5).join('\n')}`);
+                }
+            }
+            if (report.errors.length > 20) {
+                lines.push(`\n... and ${report.errors.length - 20} more errors`);
+            }
+        }
+        lines.push('');
+        lines.push(`📅 Generated: ${report.timestamp.toISOString()}`);
+        return lines.join('\n');
+    }
+    /**
+     * Get severity icon
+     */
+    getSeverityIcon(severity) {
+        switch (severity) {
+            case 'CRITICAL':
+                return '🔴';
+            case 'HIGH':
+                return '🟠';
+            case 'MEDIUM':
+                return '🟡';
+            case 'LOW':
+                return '🟢';
+            default:
+                return '⚪';
+        }
+    }
+    /**
+     * Check if there are critical errors
+     */
+    hasCriticalErrors() {
+        return this.errors.some((e) => e.severity === 'CRITICAL');
+    }
+    /**
+     * Check if there are high or critical errors
+     */
+    hasHighSeverityErrors() {
+        return this.errors.some((e) => e.severity === 'CRITICAL' || e.severity === 'HIGH');
+    }
+    /**
+     * Clear all errors
+     */
+    clear() {
+        this.errors = [];
+        logger.debug('Error aggregator cleared');
+    }
+    /**
+     * Get error count
+     */
+    getCount() {
+        return this.errors.length;
+    }
+}
+/**
+ * Global error aggregator instance
+ */
+let globalAggregator = null;
+/**
+ * Get global error aggregator instance
+ */
+export function getErrorAggregator() {
+    if (!globalAggregator) {
+        globalAggregator = new ErrorAggregator();
+    }
+    return globalAggregator;
+}
+/**
+ * Reset global error aggregator (for testing)
+ */
+export function resetErrorAggregator() {
+    globalAggregator = null;
+}
+//# sourceMappingURL=error-aggregator.js.map

package/lib/utils/error-aggregator.js.map

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

package/lib/utils/file-system.d.ts

@@ -0,0 +1,62 @@
+/**
+ * File System Utilities
+ *
+ * Provides safe file system operations with proper error handling
+ */
+export type FileReadResult = {
+    content: string;
+    encoding: string;
+    isBinary: boolean;
+    filePath: string;
+    size: number;
+};
+export type ScanOptions = {
+    pattern: string;
+    recursive?: boolean;
+    followSymlinks?: boolean;
+    ignorePatterns?: string[];
+    maxDepth?: number;
+};
+/**
+ * Reads file with encoding detection
+ *
+ * @ac US-003-AC-1
+ */
+export declare function readFileWithEncoding(filePath: string): Promise<FileReadResult>;
+/**
+ * Scans directory recursively with glob patterns
+ *
+ * @ac US-003-AC-2
+ */
+export declare function scanDirectory(directoryPath: string, options: ScanOptions): Promise<string[]>;
+/**
+ * Parses XML file with namespace support
+ * Uses XML Utils (Issue #10) for robust parsing
+ *
+ * @ac US-003-AC-3
+ */
+export declare function parseXmlFile(xmlFilePath: string): Promise<unknown>;
+/**
+ * Check if file/directory is accessible
+ *
+ * @ac US-003-AC-4 (Handles permission errors gracefully)
+ */
+export declare function isAccessible(filePath: string): Promise<boolean>;
+/**
+ * Check if path is a symlink
+ *
+ * @ac US-003-AC-5 (Supports symlinks)
+ */
+export declare function isSymlink(filePath: string): Promise<boolean>;
+/**
+ * Get file size in bytes
+ *
+ * @ac US-003-AC-5 (Supports large files >10MB)
+ */
+export declare function getFileSize(filePath: string): Promise<number>;
+/**
+ * Check if file is larger than threshold
+ *
+ * @ac US-003-AC-5 (Supports large files >10MB)
+ */
+export declare function isLargeFile(filePath: string, thresholdMB?: number): Promise<boolean>;

package/lib/utils/file-system.js

@@ -0,0 +1,167 @@
+/**
+ * File System Utilities
+ *
+ * Provides safe file system operations with proper error handling
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { glob } from 'glob';
+import { getLogger } from './logger.js';
+import { parseXmlFile as parseXmlWithUtils, validateXml } from './xml.js';
+const logger = getLogger('FileSystemUtils');
+/**
+ * Reads file with encoding detection
+ *
+ * @ac US-003-AC-1
+ */
+export async function readFileWithEncoding(filePath) {
+    try {
+        const [fileBuffer, stats] = await Promise.all([fs.readFile(filePath), fs.stat(filePath)]);
+        // Detect if binary by checking for null bytes
+        const isBinary = fileBuffer.includes(0x00);
+        if (isBinary) {
+            logger.debug('Binary file detected', { filePath, size: stats.size });
+            return {
+                content: '',
+                encoding: 'binary',
+                isBinary: true,
+                filePath,
+                size: stats.size,
+            };
+        }
+        // Assume UTF-8 for text files
+        const textContent = fileBuffer.toString('utf-8');
+        return {
+            content: textContent,
+            encoding: 'utf-8',
+            isBinary: false,
+            filePath,
+            size: stats.size,
+        };
+    }
+    catch (error) {
+        logger.error('Failed to read file', { error, filePath });
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to read file '${filePath}': ${errorMessage}`);
+    }
+}
+/**
+ * Scans directory recursively with glob patterns
+ *
+ * @ac US-003-AC-2
+ */
+export async function scanDirectory(directoryPath, options) {
+    try {
+        const { pattern, recursive = true, followSymlinks = false, ignorePatterns = [], maxDepth } = options;
+        const globPattern = recursive ? pattern : path.join(directoryPath, pattern);
+        const matchedFiles = await glob(globPattern, {
+            cwd: directoryPath,
+            absolute: true,
+            follow: followSymlinks,
+            ignore: ignorePatterns,
+            nodir: true,
+            maxDepth,
+            withFileTypes: false, // Ensure we get strings, not Path objects
+        });
+        logger.debug('Directory scan completed', {
+            directoryPath,
+            pattern,
+            filesFound: matchedFiles.length,
+        });
+        return matchedFiles;
+    }
+    catch (error) {
+        logger.error('Failed to scan directory', { error, directoryPath, options });
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        throw new Error(`Failed to scan directory '${directoryPath}': ${errorMessage}`);
+    }
+}
+/**
+ * Parses XML file with namespace support
+ * Uses XML Utils (Issue #10) for robust parsing
+ *
+ * @ac US-003-AC-3
+ */
+export async function parseXmlFile(xmlFilePath) {
+    try {
+        // Validate before parsing
+        const content = await fs.readFile(xmlFilePath, 'utf-8');
+        const validation = validateXml(content);
+        if (validation !== true) {
+            logger.warn('XML validation failed', {
+                filePath: xmlFilePath,
+                error: validation.err,
+            });
+            throw new Error(`Invalid XML: ${validation.err.msg} at line ${validation.err.line}`);
+        }
+        // Parse using XML Utils
+        const parsed = await parseXmlWithUtils(xmlFilePath);
+        logger.debug('XML file parsed successfully', { filePath: xmlFilePath });
+        return parsed;
+    }
+    catch (error) {
+        logger.error('Failed to parse XML file', { error, filePath: xmlFilePath });
+        throw error;
+    }
+}
+/**
+ * Check if file/directory is accessible
+ *
+ * @ac US-003-AC-4 (Handles permission errors gracefully)
+ */
+export async function isAccessible(filePath) {
+    try {
+        await fs.access(filePath, fs.constants.R_OK);
+        return true;
+    }
+    catch {
+        logger.warn('File not accessible', { filePath });
+        return false;
+    }
+}
+/**
+ * Check if path is a symlink
+ *
+ * @ac US-003-AC-5 (Supports symlinks)
+ */
+export async function isSymlink(filePath) {
+    try {
+        const stats = await fs.lstat(filePath);
+        return stats.isSymbolicLink();
+    }
+    catch (error) {
+        logger.error('Failed to check if symlink', { error, filePath });
+        return false;
+    }
+}
+/**
+ * Get file size in bytes
+ *
+ * @ac US-003-AC-5 (Supports large files >10MB)
+ */
+export async function getFileSize(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        return stats.size;
+    }
+    catch (error) {
+        logger.error('Failed to get file size', { error, filePath });
+        throw new Error(`Failed to get file size for '${filePath}': ${error.message}`);
+    }
+}
+/**
+ * Check if file is larger than threshold
+ *
+ * @ac US-003-AC-5 (Supports large files >10MB)
+ */
+export async function isLargeFile(filePath, thresholdMB = 10) {
+    try {
+        const size = await getFileSize(filePath);
+        const sizeMB = size / (1024 * 1024);
+        return sizeMB > thresholdMB;
+    }
+    catch {
+        return false;
+    }
+}
+//# sourceMappingURL=file-system.js.map

package/lib/utils/file-system.js.map

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