@dommaker/harness 0.16.6 → 0.16.8

package/src/cli/commands/sync-docs/index.ts

@@ -0,0 +1,355 @@
+/**
+ * harness sync-docs 命令（入口编排，工单 22）
+ *
+ * 自动同步项目文档：CAPABILITIES.md、CONTEXT.md 检查、CHANGELOG 辅助
+ * --check 模式输出结构化信息，供 LLM 或 CI 消费
+ *
+ * 实现拆分：
+ * - project-reader.ts       项目信息读取（package.json/config.yml/源码扫描）
+ * - capabilities-syncer.ts  CAPABILITIES.md 两种格式的对比与维护
+ * - context-syncer.ts       CONTEXT.md 模板生成/发现/过时判定
+ * - agents-syncer.ts        AGENTS.md 生成
+ * - preserve-block.ts       PRESERVE 标记块提取与组合
+ */
+
+import chalk from 'chalk';
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import { readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
+import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { getSourceDirs, scanSourceModules, getRequiredContextDirs } from './project-reader';
+import type { ModuleInfo, SyncResult } from './project-reader';
+import {
+  parseCapabilitiesFiles,
+  isCapabilityListingFormat,
+  checkCapabilityCounts,
+  updateCapabilityCounts,
+  updateCapabilitiesFile,
+} from './capabilities-syncer';
+import { createContextMd, findExistingContextFiles, getLatestTsMtime } from './context-syncer';
+import { buildAgentsMd } from './agents-syncer';
+import { extractPreserveBlocks, composeAgentsMd } from './preserve-block';
+
+export interface SyncDocsOptions {
+  /** 项目路径 */
+  projectPath?: string;
+  /** 只检查，不写入（CI 模式） */
+  check?: boolean;
+  /** 是否生成 CHANGELOG 条目 */
+  changelog?: boolean;
+  /** 输出 JSON 格式（供 LLM 消费） */
+  json?: boolean;
+  /** 同步 AGENTS.md（agent 导读）；PRESERVE 标记段在重新生成时原样保留 */
+  agents?: boolean;
+}
+
+/**
+ * 同步文档
+ */
+export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
+  const projectPath = options.projectPath || process.cwd();
+  const isCheck = options.check === true;
+  const isJson = options.json === true;
+
+  if (!isJson) {
+    if (isCheck) {
+      console.log(chalk.blue('🔍 检查文档新鲜度...'));
+    } else {
+      console.log(chalk.blue('📝 同步文档...'));
+    }
+  }
+
+  const result: SyncResult = {
+    added: [],
+    removed: [],
+    contextMissing: [],
+    contextStale: [],
+  };
+
+  // 1. 扫描源码模块（从 governance config 读取目录列表，默认 src/）
+  const srcDirs = await getSourceDirs(projectPath);
+  let currentModules: ModuleInfo[] = [];
+  for (const srcDir of srcDirs) {
+    try {
+      const modules = await scanSourceModules(path.join(projectPath, srcDir), projectPath);
+      currentModules.push(...modules);
+    } catch {
+      if (!isJson) {
+        console.log(chalk.yellow(`⚠️  未找到 ${srcDir} 目录，跳过`));
+      }
+    }
+  }
+
+  // 2. 解析现有 CAPABILITIES.md，检测格式
+  const capabilitiesPath = path.join(projectPath, 'CAPABILITIES.md');
+  let existingFiles: string[] = [];
+  let capsContent = '';
+  let capsIsCapabilityListing = false;
+  try {
+    capsContent = await fs.readFile(capabilitiesPath, 'utf-8');
+    if (isCapabilityListingFormat(capsContent)) {
+      capsIsCapabilityListing = true;
+    } else {
+      existingFiles = await parseCapabilitiesFiles(capabilitiesPath);
+    }
+  } catch {
+    // CAPABILITIES.md 不存在，将创建
+  }
+
+  // 3. 对比差异（分两种格式）
+  let capCountMismatches: string[] = [];
+
+  if (capsIsCapabilityListing) {
+    // 能力清单格式：委托 FreshnessRunner 对比计数
+    const countCheck = checkCapabilityCounts(projectPath);
+    capCountMismatches = countCheck.mismatches;
+    // 不填充 result.added/removed（文件级对比不适用于此格式）
+  } else {
+    // 传统的文件表格格式
+    const getBasename = (f: string) => {
+      const clean = f.endsWith('/') ? f.slice(0, -1) : f;
+      return clean.split('/').pop()!;
+    };
+    const currentBasenames = currentModules.map(m => getBasename(m.file));
+    // 目录条目（如 src/、agents/）按前缀覆盖其中的文件，且不参与 removed 对比
+    // （basename 列表里永远不会有目录，直接对比会把目录行误报为「已删除的模块」）
+    const existingDirs = existingFiles.filter(f => f.endsWith('/'));
+    const existingFileNames = existingFiles.filter(f => !f.endsWith('/'));
+    result.added = currentModules
+      .filter(
+        m =>
+          !existingDirs.some(d => m.file.startsWith(d)) &&
+          !existingFileNames.includes(getBasename(m.file))
+      )
+      .map(m => getBasename(m.file));
+    result.removed = existingFileNames.filter(f => !currentBasenames.includes(f));
+
+    // 幽灵条目清扫（2026-08-08 studio CI 4 连红事故）：上方按 basename 对比，
+    // 同名碰撞时幽灵不可见（如 agent-configs/routes.ts 已删但 agents/routes.ts 仍存在，
+    // basename routes.ts 仍在扫描结果中，永远不会被判 removed）。
+    // 这里按完整路径直接判存在性（与 docs_freshness 检查器同语义：项目根 + 源码根前缀）。
+    const sourceRoots = detectSourceRoots(projectPath);
+    const entryExists = (entry: string): boolean =>
+      existsSync(path.join(projectPath, entry)) ||
+      sourceRoots.some(root => existsSync(path.join(projectPath, root, entry)));
+    for (const entry of readCapabilitiesEntries(capabilitiesPath)) {
+      // 纯文件名条目（无路径）无法用存在性判定，交由上方 basename 对比
+      if (!entry.includes('/') || entryExists(entry)) continue;
+      const basename = entry.split('/').pop()!;
+      // basename 对比已覆盖（无碰撞场景）时不重复加入
+      if (!result.removed.includes(basename) && !result.removed.includes(entry)) {
+        result.removed.push(entry);
+      }
+    }
+  }
+
+  // 4. 检查 CONTEXT.md（缺失 + 过时）
+  // 4a. 配置中要求的目录：检查缺失
+  const contextDirs = await getRequiredContextDirs(projectPath);
+  for (const dir of contextDirs) {
+    const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+    try {
+      await fs.access(contextPath);
+    } catch {
+      result.contextMissing.push(dir);
+    }
+  }
+
+  // 4b. 自动发现已有的 CONTEXT.md：检查过时
+  const existingContextFiles = await findExistingContextFiles(projectPath, srcDirs);
+  for (const dir of existingContextFiles) {
+    const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+    try {
+      const contextStat = await fs.stat(contextPath);
+      const dirPath = path.join(projectPath, dir);
+      const latestTsMtime = await getLatestTsMtime(dirPath);
+      if (latestTsMtime && latestTsMtime > contextStat.mtimeMs) {
+        result.contextStale.push(dir);
+      }
+    } catch {
+      // 目录不存在或无法访问，跳过
+    }
+  }
+
+  // 4c. AGENTS.md（--agents 启用）：缺失或内容漂移
+  // 漂移比对基于"生成内容 + 既有 PRESERVE 标记块"的组合结果：
+  // PRESERVE 块原样穿过，块内手改不报漂移；块外手改/仓库状态变化报漂移。
+  let agentsMdExpected: string | null = null;
+  let agentsMdExists = false;
+  let agentsMdStale = false;
+  let agentsMdMalformedPreserve: string[] = [];
+  if (options.agents) {
+    const generated = await buildAgentsMd(projectPath, srcDirs);
+    let existing: string | null = null;
+    try {
+      existing = await fs.readFile(path.join(projectPath, 'AGENTS.md'), 'utf-8');
+      agentsMdExists = true;
+    } catch {
+      // 缺失视为漂移
+    }
+    const { blocks, malformed } = existing !== null
+      ? extractPreserveBlocks(existing)
+      : { blocks: [] as string[], malformed: [] as string[] };
+    agentsMdMalformedPreserve = malformed;
+    agentsMdExpected = composeAgentsMd(generated, blocks);
+    agentsMdStale = existing !== agentsMdExpected;
+  }
+  const hasAgentsIssues = options.agents === true && agentsMdStale;
+
+  const hasTableIssues = result.added.length > 0 || result.removed.length > 0;
+  const hasCapIssues = capCountMismatches.length > 0;
+  const hasContextIssues = result.contextMissing.length > 0 || result.contextStale.length > 0;
+  const hasIssues = hasTableIssues || hasCapIssues || hasContextIssues || hasAgentsIssues;
+
+  // 5. JSON 输出模式：结构化输出供 LLM 消费
+  if (isJson) {
+    const jsonOutput: Record<string, unknown> = {
+      stale: hasIssues,
+      format: capsIsCapabilityListing ? 'capability-listing' : 'file-table',
+      summary: {
+        added: result.added.length,
+        removed: result.removed.length,
+        capCountMismatches: capCountMismatches.length,
+        contextMissing: result.contextMissing.length,
+        contextStale: result.contextStale.length,
+      },
+      contextMissing: result.contextMissing.map(d => ({
+        dir: d,
+        file: `${d}/CONTEXT.md`,
+      })),
+      contextStale: result.contextStale.map(d => ({
+        dir: d,
+        file: `${d}/CONTEXT.md`,
+      })),
+      resolution: [] as Array<Record<string, unknown>>,
+    };
+
+    if (capsIsCapabilityListing && hasCapIssues) {
+      jsonOutput.capCountMismatches = capCountMismatches.map(m => ({ mismatch: m }));
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+        action: 'sync-capability-counts',
+        command: 'harness sync-docs',
+        details: 'CAPABILITIES.md 计数与代码不一致，运行 harness sync-docs 自动更新',
+      });
+    }
+
+    if (!capsIsCapabilityListing && hasTableIssues) {
+      jsonOutput.added = result.added.map(f => {
+        const getBasenameLocal = (s: string) => s.split('/').pop()!;
+        return {
+          file: f,
+          module: currentModules.find(m => getBasenameLocal(m.file) === f),
+        };
+      });
+      jsonOutput.removed = result.removed.map(f => ({ file: f }));
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+        action: 'sync-capabilities',
+        command: 'harness sync-docs',
+      });
+    }
+
+    if (hasContextIssues) {
+      (jsonOutput.resolution as Array<Record<string, unknown>>).push(
+        ...(result.contextMissing.length > 0
+          ? [{ action: 'create-context-md', command: 'harness sync-docs', dirs: result.contextMissing }]
+          : []),
+        ...(result.contextStale.length > 0
+          ? [{ action: 'update-context-md', command: 'harness sync-docs', dirs: result.contextStale }]
+          : []),
+      );
+    }
+
+    if (options.agents) {
+      jsonOutput.agentsMd = { file: 'AGENTS.md', exists: agentsMdExists, stale: agentsMdStale };
+      if (agentsMdStale) {
+        (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+          action: 'sync-agents-md',
+          command: 'harness sync-docs --agents',
+          details: '生成/更新 AGENTS.md（agent 导读）',
+        });
+      }
+    }
+
+    console.log(JSON.stringify(jsonOutput, null, 2));
+    return !hasIssues;
+  }
+
+  // 6. 人读输出模式
+  if (capsIsCapabilityListing && hasCapIssues) {
+    console.log(chalk.yellow(`\n📊 CAPABILITIES.md 计数不一致:`));
+    capCountMismatches.forEach(m => console.log(chalk.gray(`  - ${m}`)));
+  }
+
+  if (result.added.length > 0) {
+    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
+    result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+  }
+
+  if (result.removed.length > 0) {
+    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 包含已删除的模块:`));
+    result.removed.forEach(f => console.log(chalk.gray(`  - ${f}`)));
+  }
+
+  if (result.contextMissing.length > 0) {
+    console.log(chalk.yellow(`\n📋 缺少 CONTEXT.md:`));
+    result.contextMissing.forEach(d => console.log(chalk.gray(`  - ${d}/CONTEXT.md`)));
+  }
+
+  if (result.contextStale.length > 0) {
+    console.log(chalk.yellow(`\n📋 CONTEXT.md 可能过时（源码比文档新）:`));
+    result.contextStale.forEach(d => console.log(chalk.gray(`  - ${d}/CONTEXT.md`)));
+  }
+
+  if (hasAgentsIssues) {
+    console.log(
+      chalk.yellow(agentsMdExists
+        ? `\n🤖 AGENTS.md 与当前项目状态不一致:`
+        : `\n🤖 缺少 AGENTS.md（agent 导读）:`)
+    );
+    console.log(chalk.gray(`  - AGENTS.md`));
+  }
+
+  if (agentsMdMalformedPreserve.length > 0) {
+    console.log(
+      chalk.yellow(
+        `\n⚠️ AGENTS.md 中 PRESERVE 标记块未闭合（不予保留，重新生成将丢弃）: ${agentsMdMalformedPreserve.join(', ')}`
+      )
+    );
+  }
+
+  if (!hasIssues) {
+    console.log(chalk.green('✅ 所有文档都是最新的'));
+    return true;
+  }
+
+  // 7. 检查模式：只报告，不修改
+  if (isCheck) {
+    console.log(chalk.red('\n❌ 文档不是最新的，请运行 harness sync-docs 更新'));
+    return false;
+  }
+
+  // 8. 写入模式：更新文档
+  if (capsIsCapabilityListing && hasCapIssues) {
+    capsContent = updateCapabilityCounts(capsContent, projectPath);
+    await fs.writeFile(capabilitiesPath, capsContent, 'utf-8');
+    console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md 计数`));
+  }
+
+  if (!capsIsCapabilityListing && hasTableIssues) {
+    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result);
+    console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md`));
+  }
+
+  for (const dir of result.contextMissing) {
+    await createContextMd(projectPath, dir);
+    console.log(chalk.green(`✅ 已创建 ${dir}/CONTEXT.md`));
+  }
+
+  if (hasAgentsIssues && agentsMdExpected !== null) {
+    await fs.writeFile(path.join(projectPath, 'AGENTS.md'), agentsMdExpected, 'utf-8');
+    console.log(chalk.green(agentsMdExists ? `✅ 已更新 AGENTS.md` : `✅ 已生成 AGENTS.md`));
+  }
+
+  return !hasIssues;
+}

package/src/cli/commands/sync-docs/preserve-block.ts

@@ -0,0 +1,59 @@
+/**
+ * AGENTS.md PRESERVE 标记块（工单 22）
+ *
+ * 使用者在 AGENTS.md 中用 `<!-- PRESERVE:名称 -->` / `<!-- /PRESERVE:名称 -->`
+ * 圈出的区段属于使用者自有内容：重新生成时原样保留（附于生成内容之后，保持相对顺序），
+ * 漂移比对对块内改动免疫。名称仅允许字母/数字/下划线/连字符，标记须独占一行。
+ */
+
+/** PRESERVE 开始标记：独占一行，捕获名称 */
+const PRESERVE_BEGIN_RE = /^<!-- PRESERVE:([A-Za-z0-9_-]+) -->\s*$/;
+
+export interface PreserveExtraction {
+  /** 完整保留块（含首尾标记行，块间不含外部空行），保持原有相对顺序 */
+  blocks: string[];
+  /** 未闭合（缺同名结束标记）的块名——不予保留，调用方应告警 */
+  malformed: string[];
+}
+
+/**
+ * 从既有 AGENTS.md 提取 PRESERVE 标记块（逐行扫描，结束标记须与开始标记同名）。
+ * 块内容原样保留（含标记行）；未闭合的开始标记按普通内容处理并记入 malformed。
+ */
+export function extractPreserveBlocks(content: string): PreserveExtraction {
+  const blocks: string[] = [];
+  const malformed: string[] = [];
+  const lines = content.split('\n');
+  let i = 0;
+  while (i < lines.length) {
+    const m = lines[i].match(PRESERVE_BEGIN_RE);
+    if (!m) {
+      i++;
+      continue;
+    }
+    const name = m[1];
+    const endMarker = `<!-- /PRESERVE:${name} -->`;
+    let j = i + 1;
+    while (j < lines.length && lines[j].trim() !== endMarker) {
+      j++;
+    }
+    if (j >= lines.length) {
+      malformed.push(name);
+      i++; // 未闭合：跳过开始标记行，其余行按普通内容继续扫描
+      continue;
+    }
+    blocks.push(lines.slice(i, j + 1).join('\n'));
+    i = j + 1;
+  }
+  return { blocks, malformed };
+}
+
+/**
+ * 组合 AGENTS.md 最终内容：生成部分在前，PRESERVE 块按原序附在文末（空行分隔）。
+ * 无保留块时原样返回生成内容（与历史行为一致）；组合结果重跑幂等。
+ */
+export function composeAgentsMd(generated: string, blocks: string[]): string {
+  if (blocks.length === 0) return generated;
+  const head = generated.replace(/\s*$/, '');
+  return head + '\n\n' + blocks.join('\n\n') + '\n';
+}

package/src/cli/commands/sync-docs/project-reader.ts

@@ -0,0 +1,163 @@
+/**
+ * 项目读取器（工单 22）：package.json / config.yml / 源码结构的项目信息提取
+ */
+
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import { loadRawProjectConfig } from '../../../core/project-config-loader';
+import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { findTsSourceFiles } from '../../../utils/file-walk';
+
+export interface ModuleInfo {
+  name: string;
+  file: string;
+  description: string;
+}
+
+export interface SyncResult {
+  added: string[];
+  removed: string[];
+  contextMissing: string[];
+  contextStale: string[];
+}
+
+export interface PackageJsonLite {
+  name?: string;
+  description?: string;
+  scripts?: Record<string, string>;
+}
+
+/** 读取 package.json（不存在或无法解析时返回 null） */
+export async function readPackageJsonLite(dir: string): Promise<PackageJsonLite | null> {
+  try {
+    return JSON.parse(await fs.readFile(path.join(dir, 'package.json'), 'utf-8')) as PackageJsonLite;
+  } catch {
+    return null;
+  }
+}
+
+/** 从 .harness/config.yml 读取项目描述（package.json 无 description 时的兜底） */
+export async function getConfigDescription(projectPath: string): Promise<string> {
+  try {
+    const config = loadRawProjectConfig(projectPath);
+    return typeof config?.description === 'string' ? config.description : '';
+  } catch {
+    return '';
+  }
+}
+
+/** 检测包管理器（决定命令前缀）：pnpm workspace/lockfile → yarn lockfile → 默认 npm */
+export function detectPackageManager(projectPath: string): 'pnpm' | 'yarn' | 'npm' {
+  if (existsSync(path.join(projectPath, 'pnpm-workspace.yaml')) || existsSync(path.join(projectPath, 'pnpm-lock.yaml'))) {
+    return 'pnpm';
+  }
+  if (existsSync(path.join(projectPath, 'yarn.lock'))) return 'yarn';
+  return 'npm';
+}
+
+/** 格式化脚本调用方式（npm 的 start/test 可省略 run） */
+export function formatScriptCommand(pm: 'pnpm' | 'yarn' | 'npm', name: string): string {
+  if (pm === 'pnpm') return `pnpm ${name}`;
+  if (pm === 'yarn') return `yarn ${name}`;
+  return name === 'start' || name === 'test' ? `npm ${name}` : `npm run ${name}`;
+}
+
+/**
+ * 获取需要 CONTEXT.md 的目录列表
+ */
+export async function getRequiredContextDirs(projectPath: string): Promise<string[]> {
+  try {
+    const config = loadRawProjectConfig(projectPath) ?? {};
+    const governance = config.governance as Record<string, unknown> | undefined;
+    const contextFiles = governance?.context_files as Record<string, unknown> | undefined;
+    if (contextFiles?.enabled) {
+      if (Array.isArray(contextFiles.required_dirs) && contextFiles.required_dirs.length > 0) {
+        return contextFiles.required_dirs as string[];
+      }
+      // Fallback: auto-discover from source roots
+      return detectSourceRoots(projectPath);
+    }
+  } catch {
+    // 配置不存在或无法解析
+  }
+  return [];
+}
+
+/**
+ * 获取源码扫描目录列表
+ * 优先从 governance.context_files.required_dirs 读取，默认 ['src']
+ */
+export async function getSourceDirs(projectPath: string): Promise<string[]> {
+  const requiredDirs = await getRequiredContextDirs(projectPath);
+  if (requiredDirs.length > 0) return requiredDirs;
+  return detectSourceRoots(projectPath);
+}
+
+/**
+ * 扫描源码目录，提取模块信息
+ */
+export async function scanSourceModules(srcDir: string, projectPath: string): Promise<ModuleInfo[]> {
+  const modules: ModuleInfo[] = [];
+
+  let entries: string[];
+  try {
+    entries = await fs.readdir(srcDir);
+  } catch {
+    return [];
+  }
+
+  for (const entry of entries) {
+    // 跳过测试目录和非源码目录
+    if (entry === '__tests__' || entry === 'node_modules' || entry === 'dist') continue;
+
+    const entryPath = path.join(srcDir, entry);
+    const stat = await fs.stat(entryPath);
+
+    if (stat.isDirectory()) {
+      // 子目录：递归扫描 .ts 文件（不报告目录条目本身）
+      const subFiles = findTsSourceFiles(entryPath, { skipIndex: true });
+      for (const f of subFiles) {
+        modules.push({
+          name: path.basename(f, '.ts'),
+          file: path.relative(projectPath, f),
+          description: await extractFileDescription(f),
+        });
+      }
+    } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts') && entry !== 'index.ts') {
+      modules.push({
+        name: path.basename(entry, '.ts'),
+        file: path.relative(projectPath, entryPath),
+        description: await extractFileDescription(entryPath),
+      });
+    }
+  }
+
+  return modules;
+}
+
+/**
+ * 从文件提取描述
+ */
+async function extractFileDescription(filePath: string): Promise<string> {
+  try {
+    const content = await fs.readFile(filePath, 'utf-8');
+    return extractFirstComment(content) || path.basename(filePath, '.ts');
+  } catch {
+    return path.basename(filePath, '.ts');
+  }
+}
+
+/**
+ * 提取文件第一行注释
+ */
+function extractFirstComment(content: string): string | null {
+  // 匹配 /** ... */ 或 // ...
+  const jsdocMatch = content.match(/\/\*\*\s*\n\s*\*\s*(.+?)\s*\n/);
+  if (jsdocMatch) return jsdocMatch[1];
+
+  const lineMatch = content.match(/^\/\/\s*(.+)$/m);
+  if (lineMatch) return lineMatch[1];
+
+  return null;
+}