devassist-agent 1.0.0

package/src/cli/shared/watch-list.js

@@ -0,0 +1,281 @@
+/**
+ * Watch List — 待观察发现跟踪器
+ *
+ * 引擎判断不一致的发现会被标记为"待观察"，不立即修复，
+ * 等实际运行验证后再决定是否处理。
+ *
+ * 文件位置: .devassist/watch-list.json
+ *
+ * 数据结构:
+ * {
+ *   items: [
+ *     {
+ *       id: "app.js:2781:xss-innerhtml",       // 唯一标识（file:line:ruleId）
+ *       status: "pending" | "resolved" | "dismissed",
+ *       finding: { severity, message, file, line, ruleId },
+ *       aiAnalyses: [ { engineName, isFalsePositive, rootCause, confidence } ],
+ *       note: "待观察：引擎判断不一致，等运行时验证",
+ *       deferredAt: "2026-07-22T00:00:00.000Z",
+ *       resolvedAt: null,
+ *       resolution: null,  // "fixed" | "no-issue" | null
+ *       runtimeNotes: ""   // 运行时观察到的现象
+ *     }
+ *   ]
+ * }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const WATCH_LIST_FILE = 'watch-list.json';
+
+/**
+ * Get the path to the watch list file.
+ */
+function getWatchListPath(projectRoot) {
+  return path.join(projectRoot, '.devassist', WATCH_LIST_FILE);
+}
+
+/**
+ * Load the watch list from disk.
+ * Returns { items: [] } if file doesn't exist.
+ */
+function loadWatchList(projectRoot) {
+  const filePath = getWatchListPath(projectRoot);
+  if (!fs.existsSync(filePath)) {
+    return { items: [] };
+  }
+  try {
+    const data = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    if (!Array.isArray(data.items)) data.items = [];
+    return data;
+  } catch (_) {
+    return { items: [] };
+  }
+}
+
+/**
+ * Save the watch list to disk.
+ */
+function saveWatchList(projectRoot, watchList) {
+  const dir = path.join(projectRoot, '.devassist');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  const filePath = getWatchListPath(projectRoot);
+  fs.writeFileSync(filePath, JSON.stringify(watchList, null, 2), 'utf-8');
+}
+
+/**
+ * Generate a unique ID for a finding.
+ */
+function makeFindingId(finding) {
+  return `${finding.file || 'unknown'}:${finding.line || 0}:${finding.ruleId || 'no-rule'}`;
+}
+
+/**
+ * Determine if a finding's AI analyses show disagreement.
+ * Disagreement = at least 2 engines returned results but they disagree on isFalsePositive.
+ */
+function isDisagreement(finding) {
+  if (!finding.aiAnalyses) return false;
+  const available = finding.aiAnalyses.filter(ea => ea.available && ea.analysis);
+  if (available.length < 2) return false;
+
+  const fpValues = available.map(ea => ea.analysis.isFalsePositive);
+  const allSame = fpValues.every(v => v === fpValues[0]);
+  return !allSame;
+}
+
+/**
+ * Add disagreement findings to the watch list as "pending".
+ * Only adds findings that aren't already tracked.
+ * Returns the number of newly added items.
+ */
+function addDeferredFindings(projectRoot, findings, defaultNote) {
+  const watchList = loadWatchList(projectRoot);
+  let added = 0;
+
+  for (const f of findings) {
+    if (!isDisagreement(f)) continue;
+
+    const id = makeFindingId(f);
+    const existing = watchList.items.find(item => item.id === id);
+
+    if (existing) {
+      // Update finding info and analyses (keep status/note if already set)
+      existing.finding = {
+        severity: f.severity,
+        message: f.message,
+        file: f.file,
+        line: f.line,
+        ruleId: f.ruleId,
+      };
+      existing.aiAnalyses = (f.aiAnalyses || []).map(ea => ({
+        engineName: ea.engineName,
+        isFalsePositive: ea.analysis?.isFalsePositive,
+        rootCause: ea.analysis?.rootCause,
+        fix: ea.analysis?.fix,
+        confidence: ea.analysis?.confidence,
+      }));
+      continue;
+    }
+
+    watchList.items.push({
+      id,
+      status: 'pending',
+      finding: {
+        severity: f.severity,
+        message: f.message,
+        file: f.file,
+        line: f.line,
+        ruleId: f.ruleId,
+      },
+      aiAnalyses: (f.aiAnalyses || []).map(ea => ({
+        engineName: ea.engineName,
+        isFalsePositive: ea.analysis?.isFalsePositive,
+        rootCause: ea.analysis?.rootCause,
+        fix: ea.analysis?.fix,
+        confidence: ea.analysis?.confidence,
+      })),
+      note: defaultNote || '待观察：引擎判断不一致，等运行时验证',
+      deferredAt: new Date().toISOString(),
+      resolvedAt: null,
+      resolution: null,
+      runtimeNotes: '',
+    });
+    added++;
+  }
+
+  saveWatchList(projectRoot, watchList);
+  return added;
+}
+
+/**
+ * Get all pending (unresolved) watch list items.
+ */
+function getPending(projectRoot) {
+  const watchList = loadWatchList(projectRoot);
+  return watchList.items.filter(item => item.status === 'pending');
+}
+
+/**
+ * Get all watch list items (including resolved/dismissed).
+ */
+function getAll(projectRoot) {
+  const watchList = loadWatchList(projectRoot);
+  return watchList.items;
+}
+
+/**
+ * Resolve a watch list item — mark as fixed after runtime confirmed issue.
+ */
+function resolveItem(projectRoot, idOrIndex, resolution, runtimeNotes) {
+  const watchList = loadWatchList(projectRoot);
+  const item = findItem(watchList, idOrIndex);
+  if (!item) return null;
+
+  item.status = 'resolved';
+  item.resolvedAt = new Date().toISOString();
+  item.resolution = resolution || 'fixed';
+  if (runtimeNotes) item.runtimeNotes = runtimeNotes;
+
+  saveWatchList(projectRoot, watchList);
+  return item;
+}
+
+/**
+ * Dismiss a watch list item — runtime confirmed no issue.
+ */
+function dismissItem(projectRoot, idOrIndex, runtimeNotes) {
+  const watchList = loadWatchList(projectRoot);
+  const item = findItem(watchList, idOrIndex);
+  if (!item) return null;
+
+  item.status = 'dismissed';
+  item.resolvedAt = new Date().toISOString();
+  item.resolution = 'no-issue';
+  if (runtimeNotes) item.runtimeNotes = runtimeNotes;
+
+  saveWatchList(projectRoot, watchList);
+  return item;
+}
+
+/**
+ * Update the note on a watch list item.
+ */
+function updateNote(projectRoot, idOrIndex, note) {
+  const watchList = loadWatchList(projectRoot);
+  const item = findItem(watchList, idOrIndex);
+  if (!item) return null;
+
+  item.note = note;
+  saveWatchList(projectRoot, watchList);
+  return item;
+}
+
+/**
+ * Remove a watch list item entirely.
+ */
+function removeItem(projectRoot, idOrIndex) {
+  const watchList = loadWatchList(projectRoot);
+  const idx = findItemIndex(watchList, idOrIndex);
+  if (idx === -1) return false;
+
+  const removed = watchList.items.splice(idx, 1)[0];
+  saveWatchList(projectRoot, watchList);
+  return removed;
+}
+
+/**
+ * Find an item by ID string or numeric index.
+ */
+function findItem(watchList, idOrIndex) {
+  return findItemIndex(watchList, idOrIndex) >= 0
+    ? watchList.items[findItemIndex(watchList, idOrIndex)]
+    : null;
+}
+
+function findItemIndex(watchList, idOrIndex) {
+  // Try numeric index (into pending items)
+  const idx = parseInt(idOrIndex, 10);
+  if (!isNaN(idx)) {
+    const pending = watchList.items.filter(item => item.status === 'pending');
+    if (idx >= 0 && idx < pending.length) {
+      return watchList.items.indexOf(pending[idx]);
+    }
+    // Also try as direct index into all items
+    if (idx >= 0 && idx < watchList.items.length) {
+      return idx;
+    }
+  }
+  // Try as ID string
+  return watchList.items.findIndex(item => item.id === idOrIndex);
+}
+
+/**
+ * Get summary stats.
+ */
+function getStats(projectRoot) {
+  const items = getAll(projectRoot);
+  return {
+    total: items.length,
+    pending: items.filter(i => i.status === 'pending').length,
+    resolved: items.filter(i => i.status === 'resolved').length,
+    dismissed: items.filter(i => i.status === 'dismissed').length,
+  };
+}
+
+module.exports = {
+  loadWatchList,
+  saveWatchList,
+  addDeferredFindings,
+  isDisagreement,
+  makeFindingId,
+  getPending,
+  getAll,
+  resolveItem,
+  dismissItem,
+  updateNote,
+  removeItem,
+  getStats,
+  getWatchListPath,
+};

package/src/core/event-bus.js

@@ -0,0 +1,83 @@
+/**
+ * EventBus - lightweight pub/sub event bus
+ * Decouples modules: dev-time checks, runtime monitors, AI adapter all communicate via events.
+ *
+ * Design from the 88-failure report: the #1 cause of "local optimization" bugs was
+ * modules not knowing what other modules were doing. EventBus fixes this by making
+ * all check results broadcast events that any module can react to.
+ */
+class EventBus {
+  constructor() {
+    this._handlers = new Map();
+    this._history = [];
+    this._maxHistory = 200;
+  }
+
+  on(event, handler) {
+    if (!this._handlers.has(event)) {
+      this._handlers.set(event, []);
+    }
+    this._handlers.get(event).push(handler);
+    return () => this.off(event, handler);
+  }
+
+  off(event, handler) {
+    const list = this._handlers.get(event);
+    if (!list) return;
+    const idx = list.indexOf(handler);
+    if (idx >= 0) list.splice(idx, 1);
+  }
+
+  async emit(event, payload) {
+    const entry = { event, payload, ts: Date.now() };
+    this._history.push(entry);
+    if (this._history.length > this._maxHistory) {
+      this._history.shift();
+    }
+
+    const list = this._handlers.get(event);
+    if (!list) return;
+
+    const errors = [];
+    for (const handler of list) {
+      try {
+        await handler(payload);
+    } catch (err) {
+        errors.push({ event, handler: handler.name || 'anonymous', err });
+      }
+    }
+    // Also emit a catch-all for logging/monitoring
+    const allList = this._handlers.get('*');
+    if (allList) {
+      for (const handler of allList) {
+        try { await handler(entry); } catch (_) {}
+      }
+    }
+    // Don't swallow errors silently — return them for the caller to decide
+    if (errors.length > 0) {
+      return errors;
+    }
+  }
+
+  emitSync(event, payload) {
+    const list = this._handlers.get(event);
+    if (!list) return;
+    for (const handler of list) {
+      try { handler(payload); } catch (_) {}
+    }
+  }
+
+  getHistory(filter) {
+    if (!filter) return this._history.slice();
+    return this._history.filter(e => e.event === filter);
+  }
+
+  clear() {
+    this._handlers.clear();
+    this._history = [];
+  }
+}
+
+// Singleton instance shared across all modules
+const bus = new EventBus();
+module.exports = { EventBus, bus };

package/src/core/fsm.js

@@ -0,0 +1,103 @@
+/**
+ * FSM - Finite State Machine for the DevAssist agent lifecycle.
+ *
+ * Borrowed from the ChannelAgent design in the 麦克纳姆 project.
+ * States: IDLE -> PERCEIVING -> ANALYZING -> DECIDING -> ACTING -> LEARNING -> IDLE
+ *
+ * The FSM ensures the agent never gets stuck in an infinite loop
+ * (failure #7 in the report: RecoveryEngine infinite loop).
+ */
+
+const STATES = {
+  IDLE: 'IDLE',
+  PERCEIVING: 'PERCEIVING',
+  ANALYZING: 'ANALYZING',
+  DECIDING: 'DECIDING',
+  ACTING: 'ACTING',
+  LEARNING: 'LEARNING',
+  ERROR: 'ERROR',
+};
+
+const TRANSITIONS = {
+  IDLE:        ['PERCEIVING', 'ERROR'],
+  PERCEIVING:  ['ANALYZING', 'IDLE', 'ERROR'],
+  ANALYZING:   ['DECIDING', 'IDLE', 'ERROR'],
+  DECIDING:    ['ACTING', 'IDLE', 'ERROR'],
+  ACTING:      ['LEARNING', 'IDLE', 'ERROR'],
+  LEARNING:    ['IDLE', 'ERROR'],
+  ERROR:       ['IDLE'],
+};
+
+class FSM {
+  constructor() {
+    this._state = STATES.IDLE;
+    this._history = [{ state: STATES.IDLE, ts: Date.now(), reason: 'init' }];
+    this._maxHistory = 50;
+    this._maxTransitions = 100; // hard limit to prevent infinite loops
+    this._transitionCount = 0;
+    this._listeners = new Map();
+  }
+
+  get state() {
+    return this._state;
+  }
+
+  get history() {
+    return this._history.slice();
+  }
+
+  canTransition(to) {
+    const allowed = TRANSITIONS[this._state];
+    return allowed ? allowed.includes(to) : false;
+  }
+
+  transition(to, reason) {
+    if (!STATES[to]) {
+      throw new Error(`Unknown state: ${to}`);
+    }
+    if (!this.canTransition(to)) {
+      throw new Error(`Invalid transition: ${this._state} -> ${to}. Allowed: ${(TRANSITIONS[this._state] || []).join(', ')}`);
+    }
+
+    // Infinite loop protection (failure #7 defense)
+    this._transitionCount++;
+    if (this._transitionCount > this._maxTransitions) {
+      this._state = STATES.ERROR;
+      this._history.push({ state: STATES.ERROR, ts: Date.now(), reason: 'max transitions exceeded' });
+      if (this._history.length > this._maxHistory) this._history.shift();
+      throw new Error(`FSM transition limit (${this._maxTransitions}) exceeded — possible infinite loop. Forcing ERROR state.`);
+    }
+
+    const from = this._state;
+    this._state = to;
+    this._history.push({ state: to, ts: Date.now(), reason: reason || '', from });
+    if (this._history.length > this._maxHistory) this._history.shift();
+
+    // Notify listeners
+    const listeners = this._listeners.get('*') || [];
+    const stateListeners = this._listeners.get(to) || [];
+    for (const fn of [...listeners, ...stateListeners]) {
+      try { fn({ from, to, reason }); } catch (_) {}
+    }
+  }
+
+  on(state, fn) {
+    if (!this._listeners.has(state)) {
+      this._listeners.set(state, []);
+    }
+    this._listeners.get(state).push(fn);
+  }
+
+  reset() {
+    this._state = STATES.IDLE;
+    this._transitionCount = 0;
+    this._history.push({ state: STATES.IDLE, ts: Date.now(), reason: 'reset' });
+    if (this._history.length > this._maxHistory) this._history.shift();
+  }
+
+  isTerminal() {
+    return this._state === STATES.IDLE || this._state === STATES.ERROR;
+  }
+}
+
+module.exports = { FSM, STATES };

package/src/core/logger.js

@@ -0,0 +1,54 @@
+/**
+ * Logger - structured logging with severity levels.
+ * Keeps a ring buffer for debugging and emits events to EventBus.
+ */
+const { bus } = require('./event-bus');
+
+const LEVELS = { debug: 10, info: 20, warn: 30, error: 40, fatal: 50 };
+const LEVEL_NAMES = { 10: 'DEBUG', 20: 'INFO', 30: 'WARN', 40: 'ERROR', 50: 'FATAL' };
+
+class Logger {
+  constructor(name) {
+    this.name = name;
+    this._level = LEVELS.info;
+    this._buffer = [];
+    this._maxBuffer = 500;
+  }
+
+  setLevel(level) {
+    this._level = LEVELS[level] || LEVELS.info;
+  }
+
+  _log(level, msg, meta) {
+    if (level < this._level) return;
+    const entry = {
+      ts: new Date().toISOString(),
+      level: LEVEL_NAMES[level],
+      module: this.name,
+      msg,
+      meta: meta || null,
+    };
+    this._buffer.push(entry);
+    if (this._buffer.length > this._maxBuffer) this._buffer.shift();
+
+    // Color output for console
+    const colors = { DEBUG: '\x1b[90m', INFO: '\x1b[36m', WARN: '\x1b[33m', ERROR: '\x1b[31m', FATAL: '\x1b[35m' };
+    const reset = '\x1b[0m';
+    const c = colors[entry.level] || '';
+    const metaStr = meta ? ' ' + JSON.stringify(meta) : '';
+    console.log(`${c}[${entry.level}]${reset} ${entry.module}: ${msg}${metaStr}`);
+
+    // Emit for EventBus subscribers (e.g. NotificationCenter)
+    bus.emitSync('log', entry);
+  }
+
+  debug(msg, meta) { this._log(LEVELS.debug, msg, meta); }
+  info(msg, meta)  { this._log(LEVELS.info, msg, meta); }
+  warn(msg, meta)  { this._log(LEVELS.warn, msg, meta); }
+  error(msg, meta) { this._log(LEVELS.error, msg, meta); }
+  fatal(msg, meta) { this._log(LEVELS.fatal, msg, meta); }
+
+  getBuffer() { return this._buffer.slice(); }
+}
+
+module.exports = { Logger };

package/src/core/rule-engine.js

@@ -0,0 +1,117 @@
+/**
+ * RuleEngine - the deterministic first-pass checker.
+ *
+ * Core principle (from the design doc): "Rules engine first, AI second."
+ * The rule engine runs with zero latency, predictable results, and catches
+ * 90% of issues. Only the remaining 10% of "suspect" findings go to the AI.
+ *
+ * Each rule has:
+ *   id       - unique identifier (e.g. "cq-null-check")
+ *   severity - 'block' | 'warn' | 'info'
+ *   category - which module owns this rule
+ *   check    - (ctx) => Finding | null   (synchronous, deterministic)
+ */
+
+/**
+ * @typedef {Object} Finding
+ * @property {string} ruleId      - which rule triggered
+ * @property {string} severity    - block | warn | info
+ * @property {string} category    - module category
+ * @property {string} message     - human-readable description
+ * @property {string} file        - affected file path
+ * @property {number} [line]      - line number if available
+ * @property {string} [suggestion]- quick fix suggestion
+ * @property {object} [context]   - extra data for AI deep-analysis
+ */
+
+class RuleEngine {
+  constructor() {
+    this._rules = new Map();
+  }
+
+  register(rule) {
+    if (!rule.id || !rule.check) {
+      throw new Error(`Invalid rule: missing id or check. Got: ${JSON.stringify(rule)}`);
+    }
+    this._rules.set(rule.id, rule);
+  }
+
+  registerBatch(rules) {
+    for (const r of rules) this.register(r);
+  }
+
+  unregister(ruleId) {
+    this._rules.delete(ruleId);
+  }
+
+  list() {
+    return Array.from(this._rules.values());
+  }
+
+  /**
+   * Run all rules (or filtered by category) against a context.
+   * @param {object} ctx - { files, config, projectRoot, gitDiff, ... }
+   * @param {string} [categoryFilter] - only run rules in this category
+   * @returns {{ findings: Finding[], stats: object }}
+   */
+  run(ctx, categoryFilter) {
+    const findings = [];
+    let passed = 0;
+    let failed = 0;
+
+    for (const rule of this._rules.values()) {
+      if (categoryFilter && rule.category !== categoryFilter) continue;
+      try {
+        const result = rule.check(ctx);
+        if (result) {
+          if (Array.isArray(result)) {
+            for (const f of result) {
+              findings.push({ ...f, ruleId: rule.id, severity: f.severity || rule.severity, category: rule.category });
+            }
+          } else {
+            findings.push({
+              ...result,
+              ruleId: rule.id,
+              severity: result.severity || rule.severity,
+              category: rule.category
+            });
+          }
+          failed++;
+        } else {
+          passed++;
+        }
+      } catch (err) {
+        // A broken rule should not crash the entire engine
+        findings.push({
+          ruleId: rule.id,
+          severity: 'info',
+          category: rule.category || 'unknown',
+          message: `Rule execution error: ${err.message}`,
+          file: ctx.file || '(unknown)',
+          context: { error: err.stack }
+        });
+      }
+    }
+
+    const stats = {
+      totalRules: categoryFilter
+        ? Array.from(this._rules.values()).filter(r => r.category === categoryFilter).length
+        : this._rules.size,
+      passed,
+      failed,
+      findings: findings.length,
+      blocks: findings.filter(f => f.severity === 'block').length,
+      warnings: findings.filter(f => f.severity === 'warn').length,
+      infos: findings.filter(f => f.severity === 'info').length,
+    };
+
+    // Sort: blocks first, then warnings, then info
+    const severityOrder = { block: 0, warn: 1, info: 2 };
+    findings.sort((a, b) => (severityOrder[a.severity] || 3) - (severityOrder[b.severity] || 3));
+
+    return { findings, stats };
+  }
+}
+
+const engine = new RuleEngine();
+module.exports = { RuleEngine, engine };

package/src/index.js

@@ -0,0 +1,64 @@
+/**
+ * DevAssist Agent - main entry point
+ *
+ * Layer 1 (Dev-time): ConventionStore, SchemaRegistry, ImpactAnalyzer,
+ *   TechDebtTracker, CodeQualityGuard, ArchRiskAssessor, PreDeployGuard, VersionManager
+ *
+ * Layer 2 (Runtime base code): ChannelAgent, ChannelMiddleware, ToolRegistry,
+ *   InfrastructureGuard, NotificationCenter, SchemaGatekeeper
+ *   (Install into projects via: devassist init --base-code)
+ *
+ * Layer 3 (AI interface): Unified adapter for Qwen/OpenAI/Claude
+ */
+
+// Core
+const { EventBus, bus } = require('./core/event-bus');
+const { RuleEngine, engine } = require('./core/rule-engine');
+const { FSM, STATES } = require('./core/fsm');
+const { Logger } = require('./core/logger');
+
+// Dev-time modules (Layer 1)
+const { ConventionStore } = require('./modules/dev-time/convention-store');
+const { SchemaRegistry } = require('./modules/dev-time/schema-registry');
+const { ImpactAnalyzer } = require('./modules/dev-time/impact-analyzer');
+const { TechDebtTracker } = require('./modules/dev-time/tech-debt-tracker');
+const { codeQualityRules } = require('./modules/dev-time/code-quality-guard');
+const { ArchRiskAssessor } = require('./modules/dev-time/arch-risk-assessor');
+const { PreDeployGuard } = require('./modules/dev-time/pre-deploy-guard');
+const { VersionManager } = require('./modules/dev-time/version-manager');
+
+// Runtime modules (Layer 2)
+const runtime = require('./modules/runtime');
+
+// AI adapter (Layer 3)
+const ai = require('./ai/adapter');
+
+// Register default rules
+engine.registerBatch(codeQualityRules);
+
+module.exports = {
+  // Core
+  EventBus,
+  bus,
+  RuleEngine,
+  engine,
+  FSM,
+  STATES,
+  Logger,
+
+  // Dev-time modules (Layer 1)
+  ConventionStore,
+  SchemaRegistry,
+  ImpactAnalyzer,
+  TechDebtTracker,
+  ArchRiskAssessor,
+  PreDeployGuard,
+  VersionManager,
+  codeQualityRules,
+
+  // Runtime modules (Layer 2)
+  ...runtime,
+
+  // AI (Layer 3)
+  ai,
+};