devassist-agent 1.0.0

package/src/modules/dev-time/convention-store.js

@@ -0,0 +1,201 @@
+/**
+ * ConventionStore - project convention memory.
+ *
+ * Defense target: "AI forgetting early conventions" (32/88 failures).
+ * The #1 example: data.list vs data.items vs data.records — three variants
+ * appeared because AI forgot the original naming convention across sessions.
+ *
+ * This module:
+ * 1. Stores conventions in .devassist/conventions.json (persists across sessions)
+ * 2. Injects relevant conventions into AI context automatically
+ * 3. Checks code against conventions and flags violations
+ * 4. Records ADRs (Architecture Decision Records) — not just "what" but "why"
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Logger } = require('../../core/logger');
+const log = new Logger('ConventionStore');
+
+class ConventionStore {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.configDir = path.join(projectRoot, '.devassist');
+    this.configFile = path.join(this.configDir, 'conventions.json');
+    this.conventions = [];
+    this.adrs = [];
+    this._load();
+  }
+
+  _load() {
+    if (fs.existsSync(this.configFile)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(this.configFile, 'utf-8'));
+        this.conventions = data.conventions || [];
+        this.adrs = data.adrs || [];
+        log.info(`已加载 ${this.conventions.length} 条约定，${this.adrs.length} 条 ADR`);
+      } catch (err) {
+        log.warn(`加载约定失败：${err.message}`);
+      }
+    }
+  }
+
+  _save() {
+    if (!fs.existsSync(this.configDir)) {
+      fs.mkdirSync(this.configDir, { recursive: true });
+    }
+    fs.writeFileSync(this.configFile, JSON.stringify({
+      conventions: this.conventions,
+      adrs: this.adrs,
+    }, null, 2), 'utf-8');
+  }
+
+  /**
+   * Register a new convention.
+   * @param {object} conv - { id, category, rule, description, examples, severity }
+   */
+  add(conv) {
+    if (!conv.id || !conv.rule) {
+      throw new Error('约定必须有 id 和 rule');
+    }
+    // Prevent duplicates
+    const existing = this.conventions.find(c => c.id === conv.id);
+    if (existing) {
+      // Clean up _example flag if present
+      delete existing._example;
+      Object.assign(existing, conv, { updatedAt: new Date().toISOString() });
+      log.info(`已更新约定：${conv.id}`);
+    } else {
+      this.conventions.push({ ...conv, createdAt: new Date().toISOString() });
+      log.info(`已添加约定：${conv.id}`);
+    }
+    this._save();
+  }
+
+  /**
+   * Record an Architecture Decision Record.
+   * @param {object} adr - { id, title, context, decision, consequences, date }
+   */
+  addADR(adr) {
+    if (!adr.id || !adr.decision) {
+      throw new Error('ADR 必须有 id 和 decision');
+    }
+    this.adrs.push({ ...adr, date: adr.date || new Date().toISOString() });
+    this._save();
+    log.info(`已记录 ADR：${adr.id}`);
+  }
+
+  /**
+   * Get all conventions relevant to a given context (file type, module, etc.)
+   * This is what gets injected into the AI's prompt.
+   */
+  getRelevant(context) {
+    let relevant = this.conventions;
+
+    if (context && context.fileType) {
+      relevant = relevant.filter(c =>
+        !c.appliesTo || c.appliesTo.includes(context.fileType) || c.appliesTo.includes('*')
+      );
+    }
+
+    return relevant.map(c => ({
+      id: c.id,
+      rule: c.rule,
+      description: c.description || '',
+      examples: c.examples || [],
+    }));
+  }
+
+  /**
+   * Generate a conventions summary for AI prompt injection.
+   * Returns a string block that can be prepended to any AI code generation request.
+   */
+  getPromptBlock(context) {
+    const relevant = this.getRelevant(context);
+    if (relevant.length === 0) return '';
+
+    let block = '## 项目约定（必须遵守）\n\n';
+    for (const c of relevant) {
+      block += `- **${c.id}**：${c.rule}\n`;
+      if (c.description) block += `  ${c.description}\n`;
+      if (c.examples && c.examples.length > 0) {
+        block += `  示例：${c.examples.join('，')}\n`;
+      }
+    }
+    block += '\n';
+    return block;
+  }
+
+  /**
+   * Check file content against conventions.
+   * Returns findings for any violations.
+   */
+  check(filePath, content) {
+    const findings = [];
+    const ext = path.extname(filePath);
+    const fileType = ext.replace('.', '');
+
+    for (const conv of this.conventions) {
+      if (conv.appliesTo && !conv.appliesTo.includes(fileType) && !conv.appliesTo.includes('*')) {
+        continue;
+      }
+
+      // Pattern-based check: if convention has a `forbid` regex pattern
+      if (conv.forbid) {
+        const regex = new RegExp(conv.forbid, 'g');
+        let match;
+        while ((match = regex.exec(content)) !== null) {
+          const lines = content.substring(0, match.index).split('\n');
+          findings.push({
+            ruleId: `conv-${conv.id}`,
+            severity: conv.severity || 'warn',
+            category: 'convention',
+            message: `约定违规：${conv.rule}`,
+            file: filePath,
+            line: lines.length,
+            suggestion: conv.description || '请修改以符合项目约定',
+            context: { match: match[0], conventionId: conv.id },
+          });
+        }
+      }
+
+      // Pattern-based check: if convention has a `require` regex pattern
+      if (conv.require) {
+        const regex = new RegExp(conv.require);
+        if (!regex.test(content)) {
+          findings.push({
+            ruleId: `conv-${conv.id}`,
+            severity: conv.severity || 'warn',
+            category: 'convention',
+            message: `缺少必需的模式：${conv.rule}`,
+            file: filePath,
+            suggestion: conv.description || '请添加所需的模式',
+            context: { conventionId: conv.id },
+          });
+        }
+      }
+    }
+
+    return findings;
+  }
+
+  list() {
+    return {
+      conventions: this.conventions,
+      adrs: this.adrs,
+    };
+  }
+
+  remove(id) {
+    const before = this.conventions.length;
+    this.conventions = this.conventions.filter(c => c.id !== id);
+    if (this.conventions.length < before) {
+      this._save();
+      log.info(`已移除约定：${id}`);
+      return true;
+    }
+    return false;
+  }
+}
+
+module.exports = { ConventionStore };

package/src/modules/dev-time/impact-analyzer.js

@@ -0,0 +1,292 @@
+/**
+ * ImpactAnalyzer - dependency graph + change impact analysis.
+ *
+ * Defense target: "AI local optimization" (41/88 failures — the #1 killer).
+ *   The worst case: AI rewrote app.js from 2720 lines to 106 lines because
+ *   it only saw the current file, not the global dependency graph.
+ *
+ * This module:
+ * 1. Builds a dependency graph by scanning import/require/reference
+ * 2. Before any file modification, checks what depends on it
+ * 3. Detects dangerous changes: massive line reduction, signature changes
+ * 4. Flags "patch" patterns that should be fixed at the source
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { Logger } = require('../../core/logger');
+const log = new Logger('ImpactAnalyzer');
+
+class ImpactAnalyzer {
+  constructor(projectRoot) {
+    this.projectRoot = projectRoot;
+    this.graph = new Map(); // filePath -> { imports: Set, importedBy: Set, lines: number, exports: Set }
+    this.configDir = path.join(projectRoot, '.devassist');
+    this.graphFile = path.join(this.configDir, 'dependency-graph.json');
+  }
+
+  /**
+   * Scan the project and build/update the dependency graph.
+   */
+  buildGraph(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)) continue;
+      this._scanDir(fullDir, files);
+    }
+
+    // Also scan root-level HTML/JS files
+    this._scanDir(this.projectRoot, files, true);
+
+    // Build graph
+    for (const file of files) {
+      const rel = path.relative(this.projectRoot, file);
+      if (!this.graph.has(rel)) {
+        this.graph.set(rel, { imports: new Set(), importedBy: new Set(), lines: 0, exports: new Set() });
+      }
+      const node = this.graph.get(rel);
+
+      let content = '';
+      try { content = fs.readFileSync(file, 'utf-8'); } catch (_) { continue; }
+      node.lines = content.split('\n').length;
+
+      // Detect imports/requires
+      const importRegex = /(?:require\s*\(\s*['"`]([^'"`]+)['"`]|import\s+.*from\s+['"`]([^'"`]+)['"`]|src\s*=\s*['"`]([^'"`]+\.js)['"`])/g;
+      let match;
+      while ((match = importRegex.exec(content)) !== null) {
+        const imported = match[1] || match[2] || match[3];
+        if (imported) {
+          // Normalize: resolve relative paths
+          let resolved = imported;
+          if (imported.startsWith('.')) {
+            resolved = path.normalize(path.join(path.dirname(rel), imported));
+            // Add extension if missing
+            if (!path.extname(resolved)) {
+              for (const ext of ['.js', '.ts', '.jsx', '.tsx']) {
+                if (this.graph.has(resolved + ext) || files.some(f => path.relative(this.projectRoot, f) === resolved + ext)) {
+                  resolved += ext;
+                  break;
+                }
+              }
+            }
+          }
+          node.imports.add(resolved);
+
+          // Reverse link
+          if (!this.graph.has(resolved)) {
+            this.graph.set(resolved, { imports: new Set(), importedBy: new Set(), lines: 0, exports: new Set() });
+          }
+          this.graph.get(resolved).importedBy.add(rel);
+        }
+      }
+
+      // Detect exports
+      const exportRegex = /(?:export\s+(?:default\s+)?(?:function|class|const|let|var)\s+(\w+)|module\.exports\s*=\s*(\w+))/g;
+      while ((match = exportRegex.exec(content)) !== null) {
+        node.exports.add(match[1] || match[2]);
+      }
+    }
+
+    this._saveGraph();
+    log.info(`依赖图已构建：${this.graph.size} 个节点，${this._countEdges()} 条边`);
+    return this.graph;
+  }
+
+  _scanDir(dir, results, rootOnly) {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (_) { return; }
+    for (const entry of entries) {
+      // Skip node_modules, .git, .devassist, etc.
+      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|html|vue)$/.test(entry.name)) {
+        results.push(full);
+      }
+    }
+  }
+
+  _countEdges() {
+    let count = 0;
+    for (const node of this.graph.values()) count += node.imports.size;
+    return count;
+  }
+
+  _saveGraph() {
+    const serializable = {};
+    for (const [file, node] of this.graph) {
+      serializable[file] = {
+        imports: Array.from(node.imports),
+        importedBy: Array.from(node.importedBy),
+        lines: node.lines,
+        exports: Array.from(node.exports),
+      };
+    }
+    if (!fs.existsSync(this.configDir)) fs.mkdirSync(this.configDir, { recursive: true });
+    fs.writeFileSync(this.graphFile, JSON.stringify(serializable, null, 2), 'utf-8');
+  }
+
+  _loadGraph() {
+    if (fs.existsSync(this.graphFile)) {
+      try {
+        const data = JSON.parse(fs.readFileSync(this.graphFile, 'utf-8'));
+        this.graph.clear();
+        for (const [file, node] of Object.entries(data)) {
+          this.graph.set(file, {
+            imports: new Set(node.imports || []),
+            importedBy: new Set(node.importedBy || []),
+            lines: node.lines || 0,
+            exports: new Set(node.exports || []),
+          });
+        }
+        return true;
+      } catch (_) { return false; }
+    }
+    return false;
+  }
+
+  /**
+   * Analyze the impact of modifying a file.
+   * Returns a risk assessment.
+   */
+  analyzeChange(filePath, newContent) {
+    if (this.graph.size === 0) this._loadGraph();
+    if (this.graph.size === 0) this.buildGraph();
+
+    const rel = path.relative(this.projectRoot, filePath);
+    const node = this.graph.get(rel);
+    const findings = [];
+
+    if (!node) {
+      // New file — low risk
+      return { risk: 'low', findings, dependents: 0, oldLines: 0, newLines: newContent ? newContent.split('\n').length : 0 };
+    }
+
+    const oldLines = node.lines;
+    const newLines = newContent ? newContent.split('\n').length : 0;
+    const lineDelta = newLines - oldLines;
+    const dependents = node.importedBy.size;
+
+    // CRITICAL: massive line reduction (the app.js 2720→106 case)
+    if (oldLines > 200 && lineDelta < -oldLines * 0.5) {
+      findings.push({
+        ruleId: 'ia-massive-reduction',
+        severity: 'block',
+        category: 'impact',
+        message: `严重：文件从 ${oldLines} 行缩减至 ${newLines} 行（${Math.round((lineDelta / oldLines) * 100)}%）。这可能是一次意外覆盖。`,
+        file: filePath,
+        suggestion: `这符合已知故障模式：AI 将大文件覆盖为桩代码。请确认此变更是有意为之后再继续。`,
+        context: { oldLines, newLines, lineDelta, dependents },
+      });
+    }
+
+    // HIGH: critical file with many dependents being modified
+    if (dependents >= 5) {
+      findings.push({
+        ruleId: 'ia-high-dependency',
+        severity: 'warn',
+        category: 'impact',
+        message: `该文件被 ${dependents} 个其他文件引用，此处的修改影响面较大。`,
+        file: filePath,
+        suggestion: `检查所有依赖文件是否存在破坏性变更。依赖文件：${Array.from(node.importedBy).slice(0, 5).join('，')}${dependents > 5 ? '...' : ''}`,
+        context: { dependents, dependentFiles: Array.from(node.importedBy) },
+      });
+    }
+
+    // WARN: patch pattern detection — adding compatibility shim instead of fixing source
+    if (newContent) {
+      const patchPatterns = [
+        /if\s*\(.*data\.items.*\)\s*.*data\.list\s*=/,  // data.items → data.list compat
+        /if\s*\(.*data\.records.*\)\s*.*data\.list\s*=/, // data.records → data.list compat
+        /\.replaceAll\s*\(/,  // using replaceAll when the source should be fixed
+      ];
+      for (const pattern of patchPatterns) {
+        if (pattern.test(newContent)) {
+          findings.push({
+            ruleId: 'ia-patch-detected',
+            severity: 'warn',
+            category: 'impact',
+            message: `检测到补丁模式——这看起来是前端兼容性补丁。建议直接修复 API 响应格式。`,
+            file: filePath,
+            suggestion: `不要添加兼容性代码，而是修复数据源使其返回正确格式。这可以避免"三种变体"问题（data.list/data.items/data.records）。`,
+          });
+          break;
+        }
+      }
+    }
+
+    // Export removal detection
+    if (newContent && node.exports.size > 0) {
+      for (const exp of node.exports) {
+        const exportRegex = new RegExp(`(?:export\\s+(?:default\\s+)?(?:function|class|const|let|var)\\s+${exp}|module\\.exports\\s*=\\s*${exp})`);
+        if (!exportRegex.test(newContent)) {
+          findings.push({
+            ruleId: 'ia-export-removed',
+            severity: 'block',
+            category: 'impact',
+            message: `导出 '${exp}' 已被移除，但 ${dependents} 个文件依赖此模块。`,
+            file: filePath,
+            suggestion: `移除导出会破坏依赖文件。请保留导出或更新所有 ${dependents} 个依赖方。`,
+            context: { removedExport: exp, dependents: Array.from(node.importedBy) },
+          });
+        }
+      }
+    }
+
+    const risk = findings.some(f => f.severity === 'block') ? 'critical'
+               : findings.some(f => f.severity === 'warn') ? 'high'
+               : 'low';
+
+    return { risk, findings, dependents, oldLines, newLines, lineDelta };
+  }
+
+  /**
+   * Get all files that would be affected by changing the given file.
+   */
+  getAffectedFiles(filePath, depth) {
+    if (this.graph.size === 0) this._loadGraph();
+    const rel = path.relative(this.projectRoot, filePath);
+    const affected = new Set();
+    const maxDepth = depth || 3;
+
+    const traverse = (file, currentDepth) => {
+      if (currentDepth >= maxDepth) return;
+      const node = this.graph.get(file);
+      if (!node) return;
+      for (const dep of node.importedBy) {
+        if (!affected.has(dep)) {
+          affected.add(dep);
+          traverse(dep, currentDepth + 1);
+        }
+      }
+    };
+
+    traverse(rel, 0);
+    return Array.from(affected);
+  }
+
+  getStats() {
+    let totalImports = 0;
+    let maxDependents = 0;
+    let mostDependedFile = null;
+    for (const [file, node] of this.graph) {
+      totalImports += node.imports.size;
+      if (node.importedBy.size > maxDependents) {
+        maxDependents = node.importedBy.size;
+        mostDependedFile = file;
+      }
+    }
+    return {
+      totalFiles: this.graph.size,
+      totalImports,
+      maxDependents,
+      mostDependedFile,
+    };
+  }
+}
+
+module.exports = { ImpactAnalyzer };