devassist-agent 1.0.0

package/src/modules/dev-time/tech-debt-tracker.js

@@ -0,0 +1,225 @@
+/**
+ * TechDebtTracker - technical debt inventory and prioritization.
+ *
+ * Defense target: "Refactoring cost explodes" (23/88 failures).
+ *   The v1->v5 defense system kept growing, RecoveryEngine was 347 lines,
+ *   and by the time anyone wanted to refactor, the cost was too high.
+ *
+ * This module:
+ * 1. Weekly scan: complexity, coupling, duplication, file size
+ * 2. Module boundary guard (app.js set 800 line max -> 2720 = alert)
+ * 3. Debt board: auto-sorts "what to pay off next" by risk x failures / effort
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Logger } = require('../../core/logger');
+const log = new Logger('TechDebtTracker');
+
+class TechDebtTracker {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.configDir = path.join(projectRoot, '.devassist');
+    this.debtFile = path.join(this.configDir, 'tech-debt.json');
+    this.history = [];
+    this.thresholds = {
+      maxFileLines: 800,
+      maxFunctionLines: 150,
+      maxCyclomaticComplexity: 20,
+      maxDuplicateBlocks: 3,
+      maxCouplingScore: 10, // max imports per file
+    };
+    this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.debtFile)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(this.debtFile, 'utf-8'));
+        this.history = data.history || [];
+        if (data.thresholds) Object.assign(this.thresholds, data.thresholds);
+      } catch (_) {}
+    }
+  }
+
+  _save() {
+    if (!fs.existsSync(this.configDir)) fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(this.debtFile, JSON.stringify({
+      history: this.history,
+      thresholds: this.thresholds,
+    }, null, 2), 'utf-8');
+  }
+
+  /**
+   * Scan all source files and compute debt metrics.
+   */
+  scan(srcDirs) {
+    const dirs = srcDirs || ['src', 'lib', 'static', 'public', 'app'];
+    const files = [];
+    for (const dir of dirs) {
+      const fullDir = path.join(this.projectRoot, dir);
+      if (fs.existsSync(fullDir)) this._scanDir(fullDir, files);
+    }
+    // Also scan root
+    this._scanDir(this.projectRoot, files, true);
+
+    const items = [];
+    for (const file of files) {
+      let content = '';
+      try { content = fs.readFileSync(file, 'utf-8'); } catch (_) { continue; }
+      const rel = path.relative(this.projectRoot, file);
+      const lines = content.split('\n').length;
+      const complexity = this._estimateComplexity(content);
+      const imports = (content.match(/(?:require\s*\(|import\s+.*from\s+)/g) || []).length;
+      const duplicates = this._findDuplicates(content);
+
+      // File too large
+      if (lines > this.thresholds.maxFileLines) {
+        items.push({
+          id: `debt-file-size-${rel}`,
+          type: 'file-size',
+          severity: lines > this.thresholds.maxFileLines * 2 ? 'high' : 'medium',
+          file: rel,
+          metric: { lines, threshold: this.thresholds.maxFileLines },
+          description: `${rel} 共 ${lines} 行（上限 ${this.thresholds.maxFileLines} 行）。风险：AI 可能误覆盖或截断大文件。`,
+          effort: Math.ceil((lines - this.thresholds.maxFileLines) / 100), // rough effort estimate
+          failureLink: '故障 #9：app.js 膨胀至 2720 行，AI 误覆盖为 106 行',
+        });
+      }
+
+      // High complexity
+      if (complexity > this.thresholds.maxCyclomaticComplexity) {
+        items.push({
+          id: `debt-complexity-${rel}`,
+          type: 'complexity',
+          severity: complexity > this.thresholds.maxCyclomaticComplexity * 2 ? 'high' : 'medium',
+          file: rel,
+          metric: { complexity, threshold: this.thresholds.maxCyclomaticComplexity },
+          description: `${rel} 圈复杂度约 ${complexity}（上限 ${this.thresholds.maxCyclomaticComplexity}）。`,
+          effort: Math.ceil((complexity - this.thresholds.maxCyclomaticComplexity) / 5),
+          failureLink: '故障 #7：RecoveryEngine 347 行，高复杂度，引入 4 个新 bug',
+        });
+      }
+
+      // High coupling
+      if (imports > this.thresholds.maxCouplingScore) {
+        items.push({
+          id: `debt-coupling-${rel}`,
+          type: 'coupling',
+          severity: 'medium',
+          file: rel,
+          metric: { imports, threshold: this.thresholds.maxCouplingScore },
+          description: `${rel} 引入了 ${imports} 个模块（上限 ${this.thresholds.maxCouplingScore}）。高耦合使修改变得危险。`,
+          effort: 3,
+          failureLink: '故障 #5：某模块修改导致依赖方意外崩溃',
+        });
+      }
+
+      // Code duplication
+      if (duplicates.length > 0) {
+        items.push({
+          id: `debt-duplication-${rel}`,
+          type: 'duplication',
+          severity: duplicates.length > this.thresholds.maxDuplicateBlocks ? 'medium' : 'low',
+          file: rel,
+          metric: { duplicateBlocks: duplicates.length, threshold: this.thresholds.maxDuplicateBlocks },
+          description: `${rel} 存在 ${duplicates.length} 处重复代码块。`,
+          effort: duplicates.length,
+          failureLink: '故障 #8：重复声明导致混淆',
+        });
+      }
+    }
+
+    // Calculate priority score: severity weight x failure linkage / effort
+    const severityWeight = { high: 3, medium: 2, low: 1 };
+    items.forEach(item => {
+      item.priority = Math.round((severityWeight[item.severity] || 1) * 10 / Math.max(item.effort, 1));
+    });
+    items.sort((a, b) => b.priority - a.priority);
+
+    // Save snapshot
+    const snapshot = {
+      timestamp: new Date().toISOString(),
+      totalFiles: files.length,
+      totalDebt: items.length,
+      highSeverity: items.filter(i => i.severity === 'high').length,
+      items: items.slice(0, 50), // keep top 50
+    };
+    this.history.push(snapshot);
+    if (this.history.length > 12) this.history.shift(); // keep 12 weeks
+    this._save();
+
+    log.info(`技术债扫描：发现 ${items.length} 项（${snapshot.highSeverity} 项高严重度）`);
+    return snapshot;
+  }
+
+  _scanDir(dir, results, rootOnly) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const entry of entries) {
+      if (['node_modules', '.git', '.devassist', 'dist', 'build'].includes(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory() && !rootOnly) {
+        this._scanDir(full, results);
+      } else if (entry.isFile() && /\.(js|ts|jsx|tsx|py|java|html|css)$/.test(entry.name)) {
+        results.push(full);
+      }
+    }
+  }
+
+  _estimateComplexity(content) {
+    return (content.match(/\bif\s*\(/g) || []).length
+      + (content.match(/\bfor\s*\(/g) || []).length
+      + (content.match(/\bwhile\s*\(/g) || []).length
+      + (content.match(/\bcase\s+/g) || []).length
+      + (content.match(/&&|\|\|/g) || []).length
+      + 1;
+  }
+
+  _findDuplicates(content) {
+    const lines = content.split('\n').map(l => l.trim()).filter(l => l.length > 20 && !l.startsWith('//') && !l.startsWith('/*'));
+    const seen = new Map();
+    const duplicates = [];
+    for (const line of lines) {
+      seen.set(line, (seen.get(line) || 0) + 1);
+    }
+    for (const [line, count] of seen) {
+      if (count > 1) duplicates.push({ line: line.substring(0, 80), count });
+    }
+    return duplicates;
+  }
+
+  /**
+   * Get the debt board (prioritized list).
+   */
+  getBoard() {
+    if (this.history.length === 0) return { items: [], message: '暂无扫描数据，请运行 devassist debt 进行扫描。' };
+    const latest = this.history[this.history.length - 1];
+    return {
+      timestamp: latest.timestamp,
+      totalDebt: latest.totalDebt,
+      highSeverity: latest.highSeverity,
+      topItems: latest.items.slice(0, 10),
+      trend: this.history.length > 1 ? this._calculateTrend() : 'baseline',
+    };
+  }
+
+  _calculateTrend() {
+    if (this.history.length < 2) return 'baseline';
+    const current = this.history[this.history.length - 1].totalDebt;
+    const previous = this.history[this.history.length - 2].totalDebt;
+    if (current > previous) return `上升（+${current - previous}）`;
+    if (current < previous) return `下降（-${previous - current}）`;
+    return '持平';
+  }
+
+  setThreshold(key, value) {
+    if (key in this.thresholds) {
+      this.thresholds[key] = value;
+      this._save();
+      log.info(`阈值已更新：${key} = ${value}`);
+    }
+  }
+}
+
+module.exports = { TechDebtTracker };

package/src/modules/dev-time/version-manager.js

@@ -0,0 +1,280 @@
+/**
+ * VersionManager - incremental backup and file manifest management.
+ *
+ * Defense target: "File management errors" (13% of 88 failures).
+ *   #12 - backup restore deleted new files (cp -r overwrote entire dir)
+ *   #13 - deployment omitted files (forgot to copy config)
+ *   #14 - version confusion (didn't know which version was running)
+ *   #15 - old cache served after deploy (no cache-busting)
+ *
+ * Key principle: NEVER overwrite an entire directory during restore.
+ * Use incremental backups with file manifests.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const { Logger } = require('../../core/logger');
+const log = new Logger('VersionManager');
+
+class VersionManager {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.configDir = path.join(projectRoot, '.devassist');
+    this.backupDir = path.join(this.configDir, 'backups');
+    this.manifestFile = path.join(this.configDir, 'version-manifest.json');
+    this.versions = [];
+    this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.manifestFile)) {
+      try {
+        this.versions = JSON.parse(fs.readFileSync(this.manifestFile, 'utf-8'));
+      } catch (_) {}
+    }
+  }
+
+  _save() {
+    if (!fs.existsSync(this.configDir)) fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(this.manifestFile, JSON.stringify(this.versions, null, 2), 'utf-8');
+  }
+
+  /**
+   * Create an incremental backup.
+   * Only backs up files that have changed since the last backup.
+   * Returns a manifest with file hashes for verification.
+   */
+  backup(label, srcDirs) {
+    const dirs = srcDirs || ['src', 'lib', 'static', 'public', 'app'];
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const versionId = `v-${timestamp}`;
+    const backupPath = path.join(this.backupDir, versionId);
+
+    if (!fs.existsSync(backupPath)) fs.mkdirSync(backupPath, { recursive: true });
+
+    const files = [];
+    for (const dir of dirs) {
+      const fullDir = path.join(this.projectRoot, dir);
+      if (fs.existsSync(fullDir)) {
+        this._collectFiles(fullDir, files);
+      }
+    }
+    // Also collect root-level config files
+    this._collectRootConfigs(files);
+
+    const manifest = {
+      versionId,
+      label: label || 'manual backup',
+      timestamp: new Date().toISOString(),
+      files: [],
+    };
+
+    let prevManifest = this.versions.length > 0 ? this.versions[this.versions.length - 1] : null;
+    let prevFileMap = new Map();
+    if (prevManifest) {
+      // Load previous manifest files
+      const prevManifestPath = path.join(this.backupDir, prevManifest.versionId, 'manifest.json');
+      if (fs.existsSync(prevManifestPath)) {
+        try {
+          const prev = JSON.parse(fs.readFileSync(prevManifestPath, 'utf-8'));
+          for (const f of prev.files) prevFileMap.set(f.path, f.hash);
+        } catch (_) {}
+      }
+    }
+
+    let newCount = 0;
+    let changedCount = 0;
+    let unchangedCount = 0;
+
+    for (const file of files) {
+      const rel = path.relative(this.projectRoot, file);
+      let content;
+      try { content = fs.readFileSync(file); } catch (_) { continue; }
+      const hash = crypto.createHash('md5').update(content).digest('hex');
+      const prevHash = prevFileMap.get(rel);
+
+      if (prevHash === hash) {
+        unchangedCount++;
+        manifest.files.push({ path: rel, hash, status: 'unchanged' });
+      } else if (prevHash) {
+        changedCount++;
+        // Copy changed file to backup
+        const destDir = path.join(backupPath, path.dirname(rel));
+        if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(file, path.join(backupPath, rel));
+        manifest.files.push({ path: rel, hash, status: 'changed', prevHash });
+      } else {
+        newCount++;
+        const destDir = path.join(backupPath, path.dirname(rel));
+        if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+        fs.copyFileSync(file, path.join(backupPath, rel));
+        manifest.files.push({ path: rel, hash, status: 'new' });
+      }
+    }
+
+    // Save manifest
+    fs.writeFileSync(path.join(backupPath, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf-8');
+
+    // Update versions list
+    this.versions.push({
+      versionId,
+      label: manifest.label,
+      timestamp: manifest.timestamp,
+      stats: { total: manifest.files.length, new: newCount, changed: changedCount, unchanged: unchangedCount },
+    });
+    this._save();
+
+    log.info(`备份 ${versionId}：${manifest.files.length} 个文件（${newCount} 新增, ${changedCount} 变更, ${unchangedCount} 未变）`);
+    return manifest;
+  }
+
+  /**
+   * Restore from a backup — INCREMENTAL, not destructive.
+   * Only restores files that were in the backup. Does NOT delete files that
+   * weren't in the backup (failure #12 defense).
+   *
+   * Returns a pre-restore report so the user can see what will change.
+   */
+  prepareRestore(versionId) {
+    const backupPath = path.join(this.backupDir, versionId);
+    const manifestPath = path.join(backupPath, 'manifest.json');
+
+    if (!fs.existsSync(manifestPath)) {
+      throw new Error(`备份 ${versionId} 不存在或清单缺失`);
+    }
+
+    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+    const report = {
+      versionId,
+      willRestore: [],
+      willOverwrite: [],
+      newFilesNotInBackup: [],  // Files that exist now but weren't in backup
+      warning: null,
+    };
+
+    // Check which files would be restored/overwritten
+    for (const fileEntry of manifest.files) {
+      if (fileEntry.status === 'unchanged') continue;
+      const fullPath = path.join(this.projectRoot, fileEntry.path);
+      if (fs.existsSync(fullPath)) {
+        report.willOverwrite.push(fileEntry.path);
+      } else {
+        report.willRestore.push(fileEntry.path);
+      }
+    }
+
+    // CRITICAL: Find files that exist NOW but were NOT in the backup
+    // These would be LOST if we did a naive cp -r restore (failure #12)
+    const backupFiles = new Set(manifest.files.map(f => f.path));
+    const currentFiles = [];
+    for (const dir of ['src', 'lib', 'static', 'public', 'app']) {
+      const fullDir = path.join(this.projectRoot, dir);
+      if (fs.existsSync(fullDir)) this._collectFiles(fullDir, currentFiles);
+    }
+    this._collectRootConfigs(currentFiles);
+
+    for (const file of currentFiles) {
+      const rel = path.relative(this.projectRoot, file);
+      if (!backupFiles.has(rel)) {
+        report.newFilesNotInBackup.push(rel);
+      }
+    }
+
+    if (report.newFilesNotInBackup.length > 0) {
+      report.warning = `WARNING: ${report.newFilesNotInBackup.length} files exist now but are NOT in backup ${versionId}. A naive restore would DELETE these files. This was failure #12.`;
+    }
+
+    return report;
+  }
+
+  /**
+   * Actually perform the restore. Only copies back files that were in the backup.
+   * Does NOT delete any current files.
+   */
+  doRestore(versionId) {
+    const report = this.prepareRestore(versionId);
+    const backupPath = path.join(this.backupDir, versionId);
+    const manifest = JSON.parse(fs.readFileSync(path.join(backupPath, 'manifest.json'), 'utf-8'));
+
+    let restored = 0;
+    for (const fileEntry of manifest.files) {
+      if (fileEntry.status === 'unchanged') continue;
+      const srcFile = path.join(backupPath, fileEntry.path);
+      const destFile = path.join(this.projectRoot, fileEntry.path);
+
+      if (!fs.existsSync(srcFile)) {
+        log.warn(`备份文件缺失：${fileEntry.path}`);
+        continue;
+      }
+
+      const destDir = path.dirname(destFile);
+      if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+      fs.copyFileSync(srcFile, destFile);
+      restored++;
+    }
+
+    log.info(`从 ${versionId} 恢复了 ${restored} 个文件（非破坏性：保留了 ${report.newFilesNotInBackup.length} 个新文件）`);
+    return { restored, newFilesPreserved: report.newFilesNotInBackup.length };
+  }
+
+  /**
+   * Generate a deployment manifest — list of all files that must be deployed.
+   * Failure #13: files omitted during deployment.
+   */
+  generateDeployManifest(srcDirs) {
+    const dirs = srcDirs || ['src', 'lib', 'static', 'public', 'app'];
+    const files = [];
+    for (const dir of dirs) {
+      const fullDir = path.join(this.projectRoot, dir);
+      if (fs.existsSync(fullDir)) this._collectFiles(fullDir, files);
+    }
+    this._collectRootConfigs(files);
+
+    const manifest = {
+      generatedAt: new Date().toISOString(),
+      totalFiles: files.length,
+      files: files.map(f => {
+        const rel = path.relative(this.projectRoot, f);
+        let stat;
+        try { stat = fs.statSync(f); } catch (_) { stat = {}; }
+        return { path: rel, size: stat.size || 0 };
+      }),
+    };
+
+    const manifestPath = path.join(this.configDir, 'deploy-manifest.json');
+    if (!fs.existsSync(this.configDir)) fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2), 'utf-8');
+
+    log.info(`部署清单已生成：${manifest.totalFiles} 个文件`);
+    return manifest;
+  }
+
+  listVersions() {
+    return this.versions;
+  }
+
+  _collectFiles(dir, results) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const entry of entries) {
+      if (['node_modules', '.git', '.devassist', 'dist', 'build'].includes(entry.name)) continue;
+      const full = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        this._collectFiles(full, results);
+      } else if (/\.(js|ts|jsx|tsx|py|java|html|css|json|sql|sh|conf|yaml|yml|env)$/.test(entry.name)) {
+        results.push(full);
+      }
+    }
+  }
+
+  _collectRootConfigs(results) {
+    const configFiles = ['package.json', 'nginx.conf', 'supervisord.conf', '.env', 'docker-compose.yml', 'Dockerfile'];
+    for (const name of configFiles) {
+      const full = path.join(this.projectRoot, name);
+      if (fs.existsSync(full)) results.push(full);
+    }
+  }
+}
+
+module.exports = { VersionManager };