deepdebug-local-agent 0.3.1

package/src/patch-manager.js

@@ -0,0 +1,816 @@
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+
+/**
+ * PatchManager - Sistema robusto de aplicação de patches
+ *
+ * Features:
+ * - Validação rigorosa de unified diff
+ * - Sistema de backup com rollback
+ * - Mensagens de erro detalhadas
+ * - Suporte a múltiplos arquivos
+ * - Cleanup automático de backups antigos
+ */
+export class PatchManager {
+    constructor(workspaceRoot) {
+        this.workspaceRoot = workspaceRoot;
+        this.backupDir = path.join(workspaceRoot, '.deepdebug', 'backups');
+        this.maxBackupsPerFile = 10;
+    }
+
+    // ============================================
+    // PUBLIC METHODS
+    // ============================================
+
+    /**
+     * Valida se o diff está no formato unified diff correto
+     * @param {string} diffText - Texto do diff
+     * @returns {ValidationResult} - { valid: boolean, errors: string[] }
+     */
+    validateDiff(diffText) {
+        const errors = [];
+
+        if (!diffText || typeof diffText !== 'string') {
+            return { valid: false, errors: ['Diff text is empty or invalid'] };
+        }
+
+        const lines = diffText.split('\n');
+
+        // Verificar se tem pelo menos os headers básicos
+        const hasOldFileHeader = lines.some(l => l.startsWith('--- '));
+        const hasNewFileHeader = lines.some(l => l.startsWith('+++ '));
+        const hasHunkHeader = lines.some(l => /^@@ -\d+,?\d* \+\d+,?\d* @@/.test(l));
+
+        if (!hasOldFileHeader) {
+            errors.push('Missing old file header (--- a/path/to/file)');
+        }
+        if (!hasNewFileHeader) {
+            errors.push('Missing new file header (+++ b/path/to/file)');
+        }
+        if (!hasHunkHeader) {
+            errors.push('Missing hunk header (@@ -line,count +line,count @@)');
+        }
+
+        // Validar estrutura dos hunks
+        const hunkErrors = this._validateHunks(lines);
+        errors.push(...hunkErrors);
+
+        return {
+            valid: errors.length === 0,
+            errors
+        };
+    }
+
+    /**
+     * Faz parse do diff em estrutura manipulável
+     * @param {string} diffText - Texto do diff
+     * @returns {ParsedPatch} - Estrutura parseada do patch
+     */
+    parseDiff(diffText) {
+        const validation = this.validateDiff(diffText);
+        if (!validation.valid) {
+            throw new PatchError('INVALID_DIFF', `Invalid diff format: ${validation.errors.join(', ')}`);
+        }
+
+        const lines = diffText.split('\n');
+        const patches = [];
+        let currentPatch = null;
+        let currentHunk = null;
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+
+            // Detectar início de novo arquivo
+            if (line.startsWith('--- ')) {
+                if (currentPatch) {
+                    if (currentHunk) {
+                        currentPatch.hunks.push(currentHunk);
+                    }
+                    patches.push(currentPatch);
+                }
+
+                currentPatch = {
+                    oldFile: this._extractFilePath(line, '--- '),
+                    newFile: null,
+                    hunks: []
+                };
+                currentHunk = null;
+                continue;
+            }
+
+            if (line.startsWith('+++ ') && currentPatch) {
+                currentPatch.newFile = this._extractFilePath(line, '+++ ');
+                continue;
+            }
+
+            // Detectar início de hunk
+            const hunkMatch = line.match(/^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@(.*)$/);
+            if (hunkMatch && currentPatch) {
+                if (currentHunk) {
+                    currentPatch.hunks.push(currentHunk);
+                }
+
+                currentHunk = {
+                    oldStart: parseInt(hunkMatch[1]),
+                    oldCount: hunkMatch[2] ? parseInt(hunkMatch[2]) : 1,
+                    newStart: parseInt(hunkMatch[3]),
+                    newCount: hunkMatch[4] ? parseInt(hunkMatch[4]) : 1,
+                    context: hunkMatch[5] || '',
+                    lines: []
+                };
+                continue;
+            }
+
+            // Coletar linhas do hunk
+            if (currentHunk && (line.startsWith(' ') || line.startsWith('+') || line.startsWith('-') || line === '')) {
+                const type = line.startsWith('+') ? 'add' :
+                    line.startsWith('-') ? 'remove' : 'context';
+                currentHunk.lines.push({
+                    type,
+                    content: line.substring(1) // Remove o prefixo
+                });
+            }
+        }
+
+        // Adicionar último patch/hunk
+        if (currentPatch) {
+            if (currentHunk) {
+                currentPatch.hunks.push(currentHunk);
+            }
+            patches.push(currentPatch);
+        }
+
+        if (patches.length === 0) {
+            throw new PatchError('NO_PATCHES', 'No valid patches found in diff');
+        }
+
+        return {
+            patches,
+            totalHunks: patches.reduce((sum, p) => sum + p.hunks.length, 0),
+            totalFiles: patches.length
+        };
+    }
+
+    /**
+     * Cria backup de um arquivo
+     * @param {string} filePath - Caminho relativo do arquivo
+     * @returns {Promise<BackupResult>}
+     */
+    async backupFile(filePath) {
+        const fullPath = path.join(this.workspaceRoot, filePath);
+
+        // Verificar se arquivo existe
+        try {
+            await fs.access(fullPath);
+        } catch {
+            throw new PatchError('FILE_NOT_FOUND', `File not found: ${filePath}`);
+        }
+
+        // Criar diretório de backup
+        await this._ensureBackupDir();
+
+        // Ler conteúdo original
+        const originalContent = await fs.readFile(fullPath, 'utf8');
+
+        // Gerar ID único para o backup
+        const timestamp = Date.now();
+        const hash = crypto.createHash('md5').update(filePath + timestamp).digest('hex').substring(0, 8);
+        const backupId = `${timestamp}-${hash}`;
+
+        // Criar nome do arquivo de backup
+        const safeFileName = filePath.replace(/[\/\\]/g, '_');
+        const backupFileName = `${backupId}_${safeFileName}`;
+        const backupPath = path.join(this.backupDir, backupFileName);
+
+        // Salvar backup
+        await fs.writeFile(backupPath, originalContent, 'utf8');
+
+        // Salvar metadados
+        const metadataPath = path.join(this.backupDir, `${backupId}.meta.json`);
+        const metadata = {
+            backupId,
+            originalPath: filePath,
+            fullPath,
+            backupPath,
+            timestamp: new Date().toISOString(),
+            size: originalContent.length,
+            checksum: crypto.createHash('md5').update(originalContent).digest('hex')
+        };
+        await fs.writeFile(metadataPath, JSON.stringify(metadata, null, 2), 'utf8');
+
+        // Cleanup de backups antigos
+        await this._cleanupOldBackups(filePath);
+
+        console.log(`📦 Backup created: ${backupId} for ${filePath}`);
+
+        return {
+            backupId,
+            originalPath: filePath,
+            backupPath: backupFileName,
+            timestamp: metadata.timestamp,
+            size: originalContent.length
+        };
+    }
+
+    /**
+     * Aplica um patch parseado ao workspace
+     * @param {ParsedPatch} parsedPatch - Resultado do parseDiff
+     * @param {object} options - Opções { createBackup: boolean, dryRun: boolean }
+     * @returns {Promise<ApplyResult>}
+     */
+    async applyPatch(parsedPatch, options = {}) {
+        const { createBackup = true, dryRun = false } = options;
+        const results = [];
+        const backups = [];
+
+        for (const patch of parsedPatch.patches) {
+            const targetPath = patch.newFile || patch.oldFile;
+
+            if (!targetPath) {
+                results.push({
+                    file: 'unknown',
+                    success: false,
+                    error: 'Could not determine target file path'
+                });
+                continue;
+            }
+
+            try {
+                // Criar backup se solicitado
+                if (createBackup && !dryRun) {
+                    const backup = await this.backupFile(targetPath);
+                    backups.push(backup);
+                }
+
+                // Ler arquivo original
+                const fullPath = path.join(this.workspaceRoot, targetPath);
+                let originalContent;
+
+                try {
+                    originalContent = await fs.readFile(fullPath, 'utf8');
+                } catch (err) {
+                    // Arquivo novo sendo criado
+                    if (patch.oldFile === '/dev/null' || patch.oldFile.endsWith('/dev/null')) {
+                        originalContent = '';
+                    } else {
+                        throw new PatchError('FILE_NOT_FOUND', `File not found: ${targetPath}`);
+                    }
+                }
+
+                // Aplicar cada hunk
+                const originalLines = originalContent.split('\n');
+                let modifiedLines = [...originalLines];
+                let offset = 0; // Offset causado por adições/remoções anteriores
+
+                for (let hunkIndex = 0; hunkIndex < patch.hunks.length; hunkIndex++) {
+                    const hunk = patch.hunks[hunkIndex];
+                    const hunkResult = this._applyHunk(modifiedLines, hunk, offset, hunkIndex + 1);
+
+                    if (!hunkResult.success) {
+                        throw new PatchError('HUNK_FAILED', hunkResult.error);
+                    }
+
+                    modifiedLines = hunkResult.lines;
+                    offset = hunkResult.newOffset;
+                }
+
+                // Salvar arquivo modificado (se não for dry run)
+                if (!dryRun) {
+                    const newContent = modifiedLines.join('\n');
+                    await fs.writeFile(fullPath, newContent, 'utf8');
+                    console.log(`✅ Patched: ${targetPath}`);
+                }
+
+                results.push({
+                    file: targetPath,
+                    success: true,
+                    hunksApplied: patch.hunks.length,
+                    backup: backups.find(b => b.originalPath === targetPath)?.backupId
+                });
+
+            } catch (err) {
+                // Rollback dos backups já criados nesta operação
+                if (!dryRun && backups.length > 0) {
+                    console.log(`⚠️ Rolling back ${backups.length} backups due to error...`);
+                    for (const backup of backups) {
+                        try {
+                            await this.rollback(backup.backupId);
+                        } catch (rollbackErr) {
+                            console.error(`❌ Rollback failed for ${backup.backupId}: ${rollbackErr.message}`);
+                        }
+                    }
+                }
+
+                results.push({
+                    file: targetPath,
+                    success: false,
+                    error: err instanceof PatchError ? err.message : err.toString()
+                });
+
+                // Parar no primeiro erro
+                break;
+            }
+        }
+
+        const allSuccess = results.every(r => r.success);
+
+        return {
+            success: allSuccess,
+            filesModified: results.filter(r => r.success).length,
+            totalFiles: parsedPatch.totalFiles,
+            results,
+            backups: backups.map(b => b.backupId),
+            dryRun
+        };
+    }
+
+    /**
+     * Restaura um arquivo do backup
+     * @param {string} backupId - ID do backup
+     * @returns {Promise<boolean>}
+     */
+    async rollback(backupId) {
+        const metadataPath = path.join(this.backupDir, `${backupId}.meta.json`);
+
+        // Ler metadados
+        let metadata;
+        try {
+            const metadataContent = await fs.readFile(metadataPath, 'utf8');
+            metadata = JSON.parse(metadataContent);
+        } catch {
+            throw new PatchError('BACKUP_NOT_FOUND', `Backup not found: ${backupId}`);
+        }
+
+        // Ler conteúdo do backup
+        const backupFullPath = path.join(this.backupDir, path.basename(metadata.backupPath));
+        let backupContent;
+        try {
+            backupContent = await fs.readFile(backupFullPath, 'utf8');
+        } catch {
+            throw new PatchError('BACKUP_CORRUPTED', `Backup file corrupted or missing: ${backupId}`);
+        }
+
+        // Verificar checksum
+        const currentChecksum = crypto.createHash('md5').update(backupContent).digest('hex');
+        if (currentChecksum !== metadata.checksum) {
+            throw new PatchError('CHECKSUM_MISMATCH', `Backup checksum mismatch for ${backupId}`);
+        }
+
+        // Restaurar arquivo original
+        await fs.writeFile(metadata.fullPath, backupContent, 'utf8');
+
+        console.log(`🔄 Rolled back: ${metadata.originalPath} from backup ${backupId}`);
+
+        return true;
+    }
+
+    /**
+     * Lista todos os backups disponíveis
+     * @returns {Promise<BackupInfo[]>}
+     */
+    async listBackups() {
+        try {
+            await fs.access(this.backupDir);
+        } catch {
+            return [];
+        }
+
+        const files = await fs.readdir(this.backupDir);
+        const metaFiles = files.filter(f => f.endsWith('.meta.json'));
+
+        const backups = [];
+        for (const metaFile of metaFiles) {
+            try {
+                const content = await fs.readFile(path.join(this.backupDir, metaFile), 'utf8');
+                const metadata = JSON.parse(content);
+                backups.push({
+                    backupId: metadata.backupId,
+                    originalPath: metadata.originalPath,
+                    timestamp: metadata.timestamp,
+                    size: metadata.size
+                });
+            } catch {
+                // Ignorar arquivos de metadados corrompidos
+            }
+        }
+
+        // Ordenar por timestamp (mais recente primeiro)
+        backups.sort((a, b) => new Date(b.timestamp) - new Date(a.timestamp));
+
+        return backups;
+    }
+
+    /**
+     * Aplica patch de forma segura com backup automático e rollback em falha
+     * @param {string} diffText - Texto do diff
+     * @param {string} incidentId - ID do incident (para logging)
+     * @returns {Promise<SafePatchResult>}
+     */
+    async safePatch(diffText, incidentId = null) {
+        const startTime = Date.now();
+
+        console.log(`🔧 SafePatch starting${incidentId ? ` for incident ${incidentId}` : ''}...`);
+        console.log(`📝 Diff size: ${diffText.length} characters`);
+
+        // 1. Validar diff
+        const validation = this.validateDiff(diffText);
+        if (!validation.valid) {
+            return {
+                success: false,
+                error: `Invalid diff: ${validation.errors.join('; ')}`,
+                stage: 'validation',
+                duration: Date.now() - startTime
+            };
+        }
+
+        // 2. Parsear diff
+        let parsed;
+        try {
+            parsed = this.parseDiff(diffText);
+            console.log(`📊 Parsed: ${parsed.totalFiles} file(s), ${parsed.totalHunks} hunk(s)`);
+        } catch (err) {
+            return {
+                success: false,
+                error: err.message,
+                stage: 'parsing',
+                duration: Date.now() - startTime
+            };
+        }
+
+        // 3. Aplicar com backup
+        let result;
+        try {
+            result = await this.applyPatch(parsed, { createBackup: true, dryRun: false });
+        } catch (err) {
+            return {
+                success: false,
+                error: err.message,
+                stage: 'apply',
+                duration: Date.now() - startTime
+            };
+        }
+
+        const duration = Date.now() - startTime;
+
+        if (result.success) {
+            console.log(`✅ SafePatch completed in ${duration}ms`);
+            return {
+                success: true,
+                filesModified: result.filesModified,
+                backups: result.backups,
+                results: result.results,
+                stage: 'complete',
+                duration
+            };
+        } else {
+            console.log(`❌ SafePatch failed: ${result.results.find(r => !r.success)?.error}`);
+            return {
+                success: false,
+                error: result.results.find(r => !r.success)?.error || 'Unknown error',
+                stage: 'apply',
+                duration
+            };
+        }
+    }
+
+    // ============================================
+    // PRIVATE METHODS
+    // ============================================
+
+    /**
+     * Valida a estrutura dos hunks
+     */
+    _validateHunks(lines) {
+        const errors = [];
+        let inHunk = false;
+        let hunkNumber = 0;
+        let expectedOldLines = 0;
+        let expectedNewLines = 0;
+        let actualOldLines = 0;
+        let actualNewLines = 0;
+
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+
+            // Detectar início de hunk
+            const hunkMatch = line.match(/^@@ -(\d+),?(\d*) \+(\d+),?(\d*) @@/);
+            if (hunkMatch) {
+                // Verificar hunk anterior
+                if (inHunk) {
+                    if (actualOldLines !== expectedOldLines) {
+                        errors.push(`Hunk #${hunkNumber}: expected ${expectedOldLines} old lines, got ${actualOldLines}`);
+                    }
+                    if (actualNewLines !== expectedNewLines) {
+                        errors.push(`Hunk #${hunkNumber}: expected ${expectedNewLines} new lines, got ${actualNewLines}`);
+                    }
+                }
+
+                hunkNumber++;
+                inHunk = true;
+                expectedOldLines = hunkMatch[2] ? parseInt(hunkMatch[2]) : 1;
+                expectedNewLines = hunkMatch[4] ? parseInt(hunkMatch[4]) : 1;
+                actualOldLines = 0;
+                actualNewLines = 0;
+                continue;
+            }
+
+            // Contar linhas dentro do hunk
+            if (inHunk) {
+                if (line.startsWith(' ')) {
+                    actualOldLines++;
+                    actualNewLines++;
+                } else if (line.startsWith('-')) {
+                    actualOldLines++;
+                } else if (line.startsWith('+')) {
+                    actualNewLines++;
+                } else if (line.startsWith('\\')) {
+                    // "" - ignorar
+                } else if (line.startsWith('diff ') || line.startsWith('index ') ||
+                    line.startsWith('--- ') || line.startsWith('+++ ')) {
+                    // Novo arquivo, resetar
+                    inHunk = false;
+                }
+            }
+        }
+
+        // Verificar último hunk
+        if (inHunk) {
+            if (actualOldLines !== expectedOldLines && expectedOldLines > 0) {
+                errors.push(`Hunk #${hunkNumber}: expected ${expectedOldLines} old lines, got ${actualOldLines}`);
+            }
+            if (actualNewLines !== expectedNewLines && expectedNewLines > 0) {
+                errors.push(`Hunk #${hunkNumber}: expected ${expectedNewLines} new lines, got ${actualNewLines}`);
+            }
+        }
+
+        return errors;
+    }
+
+    /**
+     * Extrai o caminho do arquivo do header
+     */
+    _extractFilePath(line, prefix) {
+        let filePath = line.substring(prefix.length).trim();
+
+        // Remover prefixo a/ ou b/
+        if (filePath.startsWith('a/') || filePath.startsWith('b/')) {
+            filePath = filePath.substring(2);
+        }
+
+        // Remover timestamp se presente (git diff format)
+        const tabIndex = filePath.indexOf('\t');
+        if (tabIndex > 0) {
+            filePath = filePath.substring(0, tabIndex);
+        }
+
+        return filePath;
+    }
+
+    /**
+     * Aplica um único hunk ao array de linhas
+     */
+    _applyHunk(lines, hunk, offset, hunkNumber) {
+        let startLine = hunk.oldStart - 1 + offset; // 0-indexed
+
+        // Collect original lines (context + remove) for verification
+        const originalLines = hunk.lines.filter(l => l.type === 'context' || l.type === 'remove');
+
+        // Try exact position first, then fuzzy search if context mismatch
+        let matchOffset = this._findContextMatch(lines, originalLines, startLine);
+        if (matchOffset === null) {
+            // Fuzzy search: look for the context within a window around the expected position
+            const searchWindow = 50; // lines to search in each direction
+            const searchStart = Math.max(0, startLine - searchWindow);
+            const searchEnd = Math.min(lines.length - originalLines.length, startLine + searchWindow);
+
+            for (let tryLine = searchStart; tryLine <= searchEnd; tryLine++) {
+                if (tryLine === startLine) continue; // already tried
+                matchOffset = this._findContextMatch(lines, originalLines, tryLine);
+                if (matchOffset !== null) {
+                    console.log(`  Hunk #${hunkNumber}: context found at line ${tryLine + 1} instead of ${startLine + 1} (fuzzy match)`);
+                    startLine = tryLine;
+                    break;
+                }
+            }
+        }
+
+        if (matchOffset === null && originalLines.length > 0) {
+            // Context truly not found anywhere nearby
+            const expectedContent = originalLines[0].content;
+            const actualLine = startLine < lines.length ? lines[startLine] : '<EOF>';
+            return {
+                success: false,
+                error: `Hunk #${hunkNumber} FAILED at line ${startLine + 1}: ` +
+                    `expected "${this._truncate(expectedContent, 50)}" but found "${this._truncate(actualLine, 50)}". Context mismatch.`
+            };
+        }
+
+        // Context verified (exact or fuzzy match) - apply the changes
+        const newLines = [...lines];
+
+        // Calcular quantas linhas remover e quais linhas adicionar
+        const linesToAdd = hunk.lines.filter(l => l.type === 'add').map(l => l.content);
+        const removeCount = hunk.lines.filter(l => l.type === 'remove').length;
+        const contextAndRemoveCount = originalLines.length;
+
+        // Construir o novo conteúdo para esta seção
+        const newSectionLines = [];
+        for (const hunkLine of hunk.lines) {
+            if (hunkLine.type === 'context' || hunkLine.type === 'add') {
+                newSectionLines.push(hunkLine.content);
+            }
+            // 'remove' lines são ignoradas (não vão para o novo conteúdo)
+        }
+
+        // Substituir a seção antiga pela nova
+        newLines.splice(startLine, contextAndRemoveCount, ...newSectionLines);
+
+        // Calcular novo offset
+        const addedCount = linesToAdd.length;
+        const newOffset = offset + addedCount - removeCount;
+
+        return {
+            success: true,
+            lines: newLines,
+            newOffset,
+            added: addedCount,
+            removed: removeCount
+        };
+    }
+
+    /**
+     * Trunca string para exibição
+     */
+    /**
+     * Check if context lines match at a given position in the file.
+     * Returns the position if match found, null otherwise.
+     * Uses flexible whitespace comparison.
+     */
+    _findContextMatch(lines, originalLines, startLine) {
+        if (originalLines.length === 0) return startLine;
+
+        for (let i = 0; i < originalLines.length; i++) {
+            const fileLineIndex = startLine + i;
+            if (fileLineIndex >= lines.length) return null;
+
+            const expectedContent = originalLines[i].content;
+            const actualLine = lines[fileLineIndex];
+
+            // Primary: exact match after trimEnd
+            const expectedTrimmed = expectedContent.trimEnd();
+            const actualTrimmed = actualLine.trimEnd();
+
+            if (expectedTrimmed === actualTrimmed) continue;
+
+            // Secondary: normalize all whitespace (tabs vs spaces, etc)
+            const expectedNorm = expectedContent.trim().replace(/\s+/g, ' ');
+            const actualNorm = actualLine.trim().replace(/\s+/g, ' ');
+
+            if (expectedNorm === actualNorm) continue;
+
+            // No match at this position
+            return null;
+        }
+
+        return startLine;
+    }
+
+    _truncate(str, maxLen) {
+        if (str.length <= maxLen) return str;
+        return str.substring(0, maxLen - 3) + '...';
+    }
+
+    /**
+     * Garante que o diretório de backup existe
+     */
+    async _ensureBackupDir() {
+        try {
+            await fs.access(this.backupDir);
+        } catch {
+            await fs.mkdir(this.backupDir, { recursive: true });
+            console.log(`📁 Created backup directory: ${this.backupDir}`);
+        }
+    }
+
+    /**
+     * Remove backups antigos para um arquivo específico
+     */
+    async _cleanupOldBackups(originalPath) {
+        const backups = await this.listBackups();
+        const fileBackups = backups.filter(b => b.originalPath === originalPath);
+
+        if (fileBackups.length <= this.maxBackupsPerFile) {
+            return;
+        }
+
+        // Remover backups mais antigos
+        const toRemove = fileBackups.slice(this.maxBackupsPerFile);
+
+        for (const backup of toRemove) {
+            try {
+                const safeFileName = backup.originalPath.replace(/[\/\\]/g, '_');
+                const backupFileName = `${backup.backupId}_${safeFileName}`;
+
+                await fs.unlink(path.join(this.backupDir, backupFileName));
+                await fs.unlink(path.join(this.backupDir, `${backup.backupId}.meta.json`));
+
+                console.log(`🗑️ Removed old backup: ${backup.backupId}`);
+            } catch (err) {
+                console.warn(`⚠️ Failed to remove old backup ${backup.backupId}: ${err.message}`);
+            }
+        }
+    }
+}
+
+/**
+ * Custom error class for patch operations
+ */
+export class PatchError extends Error {
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'PatchError';
+    }
+}
+
+// ============================================
+// TYPE DEFINITIONS (for documentation)
+// ============================================
+
+/**
+ * @typedef {Object} ValidationResult
+ * @property {boolean} valid
+ * @property {string[]} errors
+ */
+
+/**
+ * @typedef {Object} ParsedPatch
+ * @property {Patch[]} patches
+ * @property {number} totalHunks
+ * @property {number} totalFiles
+ */
+
+/**
+ * @typedef {Object} Patch
+ * @property {string} oldFile
+ * @property {string} newFile
+ * @property {Hunk[]} hunks
+ */
+
+/**
+ * @typedef {Object} Hunk
+ * @property {number} oldStart
+ * @property {number} oldCount
+ * @property {number} newStart
+ * @property {number} newCount
+ * @property {string} context
+ * @property {HunkLine[]} lines
+ */
+
+/**
+ * @typedef {Object} HunkLine
+ * @property {'add'|'remove'|'context'} type
+ * @property {string} content
+ */
+
+/**
+ * @typedef {Object} BackupResult
+ * @property {string} backupId
+ * @property {string} originalPath
+ * @property {string} backupPath
+ * @property {string} timestamp
+ * @property {number} size
+ */
+
+/**
+ * @typedef {Object} ApplyResult
+ * @property {boolean} success
+ * @property {number} filesModified
+ * @property {number} totalFiles
+ * @property {FileResult[]} results
+ * @property {string[]} backups
+ * @property {boolean} dryRun
+ */
+
+/**
+ * @typedef {Object} FileResult
+ * @property {string} file
+ * @property {boolean} success
+ * @property {number} [hunksApplied]
+ * @property {string} [backup]
+ * @property {string} [error]
+ */
+
+/**
+ * @typedef {Object} SafePatchResult
+ * @property {boolean} success
+ * @property {string} [error]
+ * @property {string} stage
+ * @property {number} duration
+ * @property {number} [filesModified]
+ * @property {string[]} [backups]
+ * @property {FileResult[]} [results]
+ */
+
+export default PatchManager;