@haaaiawd/loom 0.1.0

package/cli/src/diagnostics.js

@@ -0,0 +1,277 @@
+// diagnostics — LOOM 诊断与追溯工具集
+// 提供 doctor / context / trace / reverse-dep / reverse-ref 五个聚合命令。
+// 全部是只读的数据聚合，不做决策、不修改文件。
+
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { loadIntentMap, getStatus, getNextIntent, getNarrative, getIntent } from './intent-map.js';
+import { getPhilosophy } from './philosophy.js';
+import { getVerificationHistory, getPendingVerifications, getVerificationContract } from './verify.js';
+
+// ─── doctor ────────────────────────────────────────────
+// 全面健康检查：一致性 + 孤儿引用 + 循环依赖 + 僵尸 Intent
+
+/**
+ * 项目健康检查。
+ * @param {string} loomDir — 当前版本目录
+ * @param {string} verificationsDir — 验证记录目录
+ * @param {string} philosophyDir — 哲学目录
+ * @returns {{ issues: object[], summary: object }}
+ */
+export function doctor(loomDir, verificationsDir, philosophyDir) {
+  const { intents, topo_order } = loadIntentMap(loomDir);
+  const issues = [];
+
+  // 1. 状态一致性：in_progress/completed 但无验证记录
+  for (const [id, intent] of Object.entries(intents)) {
+    const hasRecord = existsSync(join(verificationsDir, `${id}.json`));
+    if (intent.status === 'completed' && !hasRecord) {
+      issues.push({ id, type: 'completed_no_record', severity: 'high', msg: `${id} 状态为 completed 但无验证记录` });
+    }
+    if (intent.status === 'in_progress' && !hasRecord) {
+      issues.push({ id, type: 'in_progress_no_record', severity: 'medium', msg: `${id} 状态为 in_progress 但无验证记录（可能上次中断）` });
+    }
+  }
+
+  // 2. 孤儿引用：哲学锚点指向不存在的文件
+  for (const [id, intent] of Object.entries(intents)) {
+    if (!intent.philosophy_anchors) continue;
+    for (const anchor of intent.philosophy_anchors) {
+      const [file] = anchor.split('#');
+      const filePath = join(philosophyDir, file);
+      if (!existsSync(filePath)) {
+        issues.push({ id, type: 'orphan_philosophy_ref', severity: 'high', msg: `${id} 引用不存在的哲学文件: ${file}` });
+      }
+    }
+  }
+
+  // 3. 孤儿引用：depends_on 指向不存在的 Intent
+  for (const [id, intent] of Object.entries(intents)) {
+    if (!intent.depends_on) continue;
+    for (const dep of intent.depends_on) {
+      if (!(dep in intents)) {
+        issues.push({ id, type: 'orphan_dependency', severity: 'high', msg: `${id} 依赖不存在的 Intent: ${dep}` });
+      }
+    }
+  }
+
+  // 4. 循环依赖检测（DFS）
+  const cycles = detectCycles(intents);
+  for (const cycle of cycles) {
+    issues.push({ id: cycle.join('→'), type: 'cycle', severity: 'fatal', msg: `循环依赖: ${cycle.join(' → ')}` });
+  }
+
+  // 5. 僵尸 Intent：in_progress/blocked 超过 N 天无活动（按验证记录最后修改时间）
+  const ZOMBIE_DAYS = 7;
+  const now = Date.now();
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.status !== 'in_progress' && intent.status !== 'blocked') continue;
+    const recordPath = join(verificationsDir, `${id}.json`);
+    let lastActivity = existsSync(join(loomDir, '04_INTENT_MAP.json'))
+      ? statSync(join(loomDir, '04_INTENT_MAP.json')).mtimeMs
+      : now;
+    if (existsSync(recordPath)) {
+      lastActivity = Math.max(lastActivity, statSync(recordPath).mtimeMs);
+    }
+    const daysIdle = (now - lastActivity) / (1000 * 60 * 60 * 24);
+    if (daysIdle > ZOMBIE_DAYS) {
+      issues.push({ id, type: 'zombie', severity: 'medium', msg: `${id} 状态为 ${intent.status} 已 ${Math.floor(daysIdle)} 天无活动` });
+    }
+  }
+
+  // 6. 依赖状态一致性：completed 不能依赖 blocked
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.status !== 'completed' || !intent.depends_on) continue;
+    for (const dep of intent.depends_on) {
+      const depIntent = intents[dep];
+      if (depIntent && depIntent.status === 'blocked') {
+        issues.push({ id, type: 'completed_depends_blocked', severity: 'high', msg: `${id} 状态为 completed 但依赖 blocked 的 ${dep}` });
+      }
+    }
+  }
+
+  const summary = {
+    total_issues: issues.length,
+    fatal: issues.filter((i) => i.severity === 'fatal').length,
+    high: issues.filter((i) => i.severity === 'high').length,
+    medium: issues.filter((i) => i.severity === 'medium').length,
+    healthy: issues.length === 0,
+  };
+
+  return { issues, summary };
+}
+
+/**
+ * DFS 检测循环依赖。
+ * 返回循环路径数组，每个是 [A, B, C, A] 形式。
+ */
+function detectCycles(intents) {
+  const cycles = [];
+  const visited = new Set();
+  const stack = new Set();
+  const path = [];
+
+  function dfs(id) {
+    if (stack.has(id)) {
+      // 找到环
+      const cycleStart = path.indexOf(id);
+      cycles.push([...path.slice(cycleStart), id]);
+      return;
+    }
+    if (visited.has(id)) return;
+    visited.add(id);
+    stack.add(id);
+    path.push(id);
+    const intent = intents[id];
+    if (intent?.depends_on) {
+      for (const dep of intent.depends_on) {
+        if (dep in intents) dfs(dep);
+      }
+    }
+    path.pop();
+    stack.delete(id);
+  }
+
+  for (const id of Object.keys(intents)) {
+    if (!visited.has(id)) dfs(id);
+  }
+  return cycles;
+}
+
+// ─── context ───────────────────────────────────────────
+// 一条命令拿到：进度 + 下一个 Intent + 待验证 + 不一致项 + 风险
+
+/**
+ * 项目上下文摘要——Agent 重启后一条命令获取"我在哪"。
+ * @param {string} loomDir
+ * @param {string} verificationsDir
+ * @param {string} philosophyDir
+ * @returns {object}
+ */
+export function contextSummary(loomDir, verificationsDir, philosophyDir) {
+  const status = getStatus(loomDir);
+  const next = getNextIntent(loomDir);
+  const pending = getPendingVerifications(loomDir, verificationsDir);
+  const { issues } = doctor(loomDir, verificationsDir, philosophyDir);
+
+  const risks = [];
+  const fatalCount = issues.filter((i) => i.severity === 'fatal').length;
+  const highCount = issues.filter((i) => i.severity === 'high').length;
+  if (fatalCount > 0) risks.push(`${fatalCount} 个致命问题（循环依赖）`);
+  if (highCount > 0) risks.push(`${highCount} 个高严重度问题（状态不一致/孤儿引用）`);
+  if (status.counts.blocked > 0) risks.push(`${status.counts.blocked} 个阻塞 Intent`);
+
+  return {
+    progress: {
+      completed: status.counts.completed,
+      total: status.counts.total,
+      rate: `${status.counts.completed}/${status.counts.total}`,
+    },
+    next_intent: next ? next.id : null,
+    pending_verifications: pending,
+    inconsistent_states: issues.filter((i) => i.type === 'in_progress_no_record' || i.type === 'completed_no_record').map((i) => i.id),
+    risks,
+    healthy: issues.length === 0,
+  };
+}
+
+// ─── trace ─────────────────────────────────────────────
+// Intent 完整追溯链：依赖链 + 验证历史 + 哲学锚点内容 + 意图叙事
+
+/**
+ * 返回某个 Intent 的完整追溯链。
+ * @param {string} loomDir
+ * @param {string} verificationsDir
+ * @param {string} philosophyDir
+ * @param {string} intentId
+ * @returns {object}
+ */
+export function traceIntent(loomDir, verificationsDir, philosophyDir, intentId) {
+  const intent = getIntent(loomDir, intentId);
+  if (!intent) throw new Error(`Intent 不存在: ${intentId}`);
+
+  // 意图叙事
+  let narrative = null;
+  try { narrative = getNarrative(loomDir, intentId); } catch { /* narrative_ref 可能缺失 */ }
+
+  // 验收契约
+  let acceptance = null;
+  try { acceptance = getVerificationContract(loomDir, intentId); } catch { /* 可能缺失 */ }
+
+  // 验证历史
+  const verificationHistory = getVerificationHistory(verificationsDir, intentId);
+
+  // 哲学锚点内容
+  const philosophyContent = {};
+  if (intent.philosophy_anchors) {
+    for (const anchor of intent.philosophy_anchors) {
+      try {
+        philosophyContent[anchor] = getPhilosophy(philosophyDir, anchor);
+      } catch (e) {
+        philosophyContent[anchor] = null;
+      }
+    }
+  }
+
+  // 依赖链（递归向上）
+  const { intents } = loadIntentMap(loomDir);
+  const dependencyChain = [];
+  function walkDeps(id, depth) {
+    const node = intents[id];
+    if (!node?.depends_on || node.depends_on.length === 0) return;
+    for (const dep of node.depends_on) {
+      dependencyChain.push({ id: dep, depth, status: intents[dep]?.status });
+      walkDeps(dep, depth + 1);
+    }
+  }
+  walkDeps(intentId, 0);
+
+  return {
+    intent,
+    narrative,
+    acceptance,
+    verification_history: verificationHistory,
+    philosophy_anchors_content: philosophyContent,
+    dependency_chain: dependencyChain,
+  };
+}
+
+// ─── reverse-dep ───────────────────────────────────────
+// 反向依赖：哪些 Intent 依赖这个 Intent
+
+/**
+ * 返回依赖指定 Intent 的所有 Intent。
+ * @param {string} loomDir
+ * @param {string} intentId
+ * @returns {string[]}
+ */
+export function reverseDep(loomDir, intentId) {
+  const { intents } = loadIntentMap(loomDir);
+  const result = [];
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.depends_on?.includes(intentId)) {
+      result.push(id);
+    }
+  }
+  return result;
+}
+
+// ─── reverse-ref ───────────────────────────────────────
+// 反向哲学引用：哪些 Intent 引用了这个哲学锚点
+
+/**
+ * 返回引用指定哲学锚点的所有 Intent。
+ * @param {string} loomDir
+ * @param {string} anchor — 如 "PRODUCT_PHILOSOPHY.md#core-belief"
+ * @returns {string[]}
+ */
+export function reverseRef(loomDir, anchor) {
+  const { intents } = loadIntentMap(loomDir);
+  const result = [];
+  for (const [id, intent] of Object.entries(intents)) {
+    if (intent.philosophy_anchors?.includes(anchor)) {
+      result.push(id);
+    }
+  }
+  return result;
+}

package/cli/src/guide.js

@@ -0,0 +1,201 @@
+// guide — 状态感知动态引导
+// 检测项目当前在哪个阶段，输出"你在阶段 X，下一步做 Y"。
+// 面向 Agent（主）和人类（辅）。比 help workflow（静态）智能。
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { readCurrentPointer } from './version.js';
+import { loadIntentMap } from './intent-map.js';
+import { isAutoOn } from './auto.js';
+
+/**
+ * 检测文件是否还是模板（未填充真实内容）。
+ * MD 文件检查 <!-- LOOM_TEMPLATE --> 标记。
+ * JSON 文件检查 _meta._template 字段。
+ */
+function isTemplate(filePath) {
+  if (!existsSync(filePath)) return true;
+  const content = readFileSync(filePath, 'utf-8');
+  if (filePath.endsWith('.json')) {
+    try {
+      const data = JSON.parse(content);
+      return data._meta?._template === true;
+    } catch {
+      return false; // 损坏文件不算模板
+    }
+  }
+  return content.includes('<!-- LOOM_TEMPLATE -->');
+}
+
+/**
+ * 诊断项目当前阶段。
+ * @param {string} projectDir — 项目根目录
+ * @returns {{ stage: string, stage_num: number, details: object, auto: boolean, next_action: string, next_command: string, message: string }}
+ */
+export function guideProject(projectDir) {
+  const cwd = projectDir || process.cwd();
+  const loomRoot = join(cwd, '.loom');
+  const auto = isAutoOn(loomRoot);
+
+  // 状态 0: 没有 .loom/
+  if (!existsSync(loomRoot)) {
+    return {
+      stage: 'not_initialized',
+      stage_num: 0,
+      details: {},
+      auto,
+      next_action: '初始化 LOOM 项目',
+      next_command: 'loom init',
+      message: '项目尚未初始化。运行 loom init 创建 .loom/v1/ 骨架。',
+    };
+  }
+
+  const current = readCurrentPointer(loomRoot);
+  if (!current) {
+    return {
+      stage: 'no_version',
+      stage_num: 0,
+      details: {},
+      auto,
+      next_action: '初始化第一个版本',
+      next_command: 'loom init',
+      message: '.loom/ 存在但没有版本目录。运行 loom init 创建 v1。',
+    };
+  }
+
+  const versionDir = join(loomRoot, current);
+  const philosophyDir = join(versionDir, '00_PHILOSOPHY');
+  const visionPath = join(versionDir, '01_VISION.md');
+  const intentMapPath = join(versionDir, '04_INTENT_MAP.json');
+
+  // 状态 1: 哲学未织造
+  const philosophyFile = join(philosophyDir, 'PRODUCT_PHILOSOPHY.md');
+  if (isTemplate(philosophyFile)) {
+    return {
+      stage: 'need_philosophy',
+      stage_num: 1,
+      details: { version: current },
+      auto,
+      next_action: '织造产品哲学',
+      next_command: 'loom activate weaver',
+      message: `当前版本 ${current}：哲学还是模板，需要 Weaver 织造。`,
+    };
+  }
+
+  // 状态 2: 哲学已织造，愿景未定义
+  if (isTemplate(visionPath)) {
+    return {
+      stage: 'need_vision',
+      stage_num: 2,
+      details: { version: current },
+      auto,
+      next_action: '定义产品愿景',
+      next_command: 'loom activate visionary',
+      message: `当前版本 ${current}：哲学已织造，愿景还是模板，需要 Visionary 定义。`,
+    };
+  }
+
+  // 状态 3: 愿景已定义，Intent Map 未设计
+  if (isTemplate(intentMapPath)) {
+    return {
+      stage: 'need_architecture',
+      stage_num: 3,
+      details: { version: current },
+      auto,
+      next_action: '设计系统架构 + Intent Map',
+      next_command: 'loom activate architect',
+      message: `当前版本 ${current}：愿景已定义，Intent Map 还是模板，需要 Architect 设计。`,
+    };
+  }
+
+  // 状态 4-7: Intent Map 已设计，根据 Intent 状态判断
+  let intents;
+  try {
+    intents = loadIntentMap(versionDir).intents;
+  } catch (e) {
+    return {
+      stage: 'intent_map_broken',
+      stage_num: 3,
+      details: { version: current, error: e.message },
+      auto,
+      next_action: '修复 Intent Map',
+      next_command: 'loom intent validate',
+      message: `Intent Map 格式错误: ${e.message}`,
+    };
+  }
+
+  const allIntents = Object.values(intents);
+  const counts = {
+    pending: allIntents.filter((i) => i.status === 'pending').length,
+    in_progress: allIntents.filter((i) => i.status === 'in_progress').length,
+    completed: allIntents.filter((i) => i.status === 'completed').length,
+    blocked: allIntents.filter((i) => i.status === 'blocked').length,
+    needs_review: allIntents.filter((i) => i.status === 'needs_review').length,
+  };
+  const total = allIntents.length;
+
+  // 状态 7: 有 blocked（优先报告）
+  if (counts.blocked > 0) {
+    const blockedIds = allIntents.filter((i) => i.status === 'blocked').map((i) => i.id);
+    return {
+      stage: 'blocked',
+      stage_num: 7,
+      details: { version: current, counts, blocked_ids: blockedIds },
+      auto,
+      next_action: '人工介入解决阻塞',
+      next_command: 'loom intent get ' + blockedIds[0],
+      message: `有 ${counts.blocked} 个 Intent 阻塞: ${blockedIds.join(', ')}。需要人工介入。`,
+    };
+  }
+
+  // 状态 6: 全部 completed
+  if (counts.completed === total && total > 0) {
+    return {
+      stage: 'done',
+      stage_num: 6,
+      details: { version: current, counts, total },
+      auto,
+      next_action: '项目阶段完成，考虑版本演进',
+      next_command: 'loom version new',
+      message: `当前版本 ${current}：全部 ${total} 个 Intent 已完成。可考虑 loom version new 开始新版本。`,
+    };
+  }
+
+  // 状态 5: 有 in_progress
+  if (counts.in_progress > 0) {
+    const inProgressIds = allIntents.filter((i) => i.status === 'in_progress').map((i) => i.id);
+    return {
+      stage: 'in_loop',
+      stage_num: 5,
+      details: { version: current, counts, in_progress_ids: inProgressIds },
+      auto,
+      next_action: '继续 Intent Loop',
+      next_command: 'loom context',
+      message: `当前版本 ${current}：Intent Loop 进行中（${inProgressIds.join(', ')}）。运行 loom context 查看状态。`,
+    };
+  }
+
+  // 状态 4: 有 pending，进入 Intent Loop
+  if (counts.pending > 0) {
+    return {
+      stage: 'ready_for_loop',
+      stage_num: 4,
+      details: { version: current, counts, total },
+      auto,
+      next_action: '进入 Intent Loop',
+      next_command: 'loom intent next',
+      message: `当前版本 ${current}：${counts.pending} 个 Intent 待执行。运行 loom intent next 开始。`,
+    };
+  }
+
+  // 兜底
+  return {
+    stage: 'unknown',
+    stage_num: -1,
+    details: { version: current, counts },
+    auto,
+    next_action: '运行健康检查',
+    next_command: 'loom doctor',
+    message: '项目状态不明确，运行 loom doctor 诊断。',
+  };
+}