@dommaker/harness 0.16.6 → 0.16.8

package/src/cli/commands/sync-docs/agents-syncer.ts

@@ -0,0 +1,280 @@
+/**
+ * AGENTS.md 同步器（工单 22）：agent 导读生成（项目简介/目录结构/常用命令/约束治理/知识入口）
+ */
+
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import * as path from 'path';
+import { loadRawProjectConfig } from '../../../core/project-config-loader';
+import {
+  readPackageJsonLite,
+  getConfigDescription,
+  detectPackageManager,
+  formatScriptCommand,
+} from './project-reader';
+
+/** 生成 AGENTS.md 目录结构表时跳过的目录（依赖/构建产物/报告等） */
+const AGENTS_MD_SKIP_DIRS = new Set([
+  'node_modules', 'dist', 'build', 'out', 'coverage',
+  'playwright-report', 'test-results', '.git', '.next', '.turbo',
+]);
+
+/** 知名顶层目录的一句话说明 */
+const AGENTS_MD_DIR_ROLES: Record<string, string> = {
+  docs: '项目文档',
+  scripts: '工具脚本',
+  tests: '测试',
+  test: '测试',
+  bin: '可执行入口/脚本',
+  templates: '项目模板',
+  '.github': 'CI/CD 配置',
+  '.harness': 'harness 配置与运行时状态',
+};
+
+/** 常用命令候选（按展示顺序），仅列出 package.json 中实际存在的脚本 */
+const AGENTS_MD_COMMANDS: Array<[string, string]> = [
+  ['dev', '启动开发环境'],
+  ['build', '构建'],
+  ['test', '运行测试'],
+  ['test:e2e', '端到端测试'],
+  ['test:unit', '单元测试'],
+  ['typecheck', '类型检查'],
+  ['lint', '代码检查'],
+  ['start', '启动生产服务'],
+];
+
+export interface GovernanceInfo {
+  hasConfig: boolean;
+  preset?: string;
+  hasClaudeGovernance: boolean;
+  ironLaws?: number;
+  guidelines?: number;
+}
+
+/**
+ * 生成 AGENTS.md 内容（agent 导读：项目简介/目录结构/常用命令/约束治理/知识入口）
+ *
+ * 纯静态提取（零 LLM），确定性输出：同一代码库状态生成同一内容（无时间戳），
+ * 因此重跑幂等。既有文件中的 PRESERVE 标记块由 composeAgentsMd 组合回输出，
+ * --check 对组合结果做文本对比检测漂移（块内手改不报漂移）。
+ */
+export async function buildAgentsMd(projectPath: string, srcDirs: string[]): Promise<string> {
+  const pkg = await readPackageJsonLite(projectPath);
+  const [dirs, governance, hasKnowledge, contextDocCount] = await Promise.all([
+    getTopLevelDirEntries(projectPath, srcDirs),
+    getGovernanceInfo(projectPath),
+    hasKnowledgeDir(projectPath),
+    countContextDocs(projectPath, srcDirs),
+  ]);
+
+  const name = pkg?.name || path.basename(projectPath);
+  const description = pkg?.description || await getConfigDescription(projectPath);
+
+  const lines: string[] = [
+    '# AGENTS.md',
+    '',
+    '> 本文件由 `harness sync-docs --agents` 自动生成，请勿手改。`<!-- PRESERVE:名称 -->` 与 `<!-- /PRESERVE:名称 -->` 之间的内容在重新生成时原样保留。内容漂移时重新运行该命令更新。',
+    '',
+    '## 项目简介',
+    '',
+    description ? `**${name}** — ${description}` : `**${name}**`,
+    '',
+    '## 目录结构',
+    '',
+  ];
+
+  if (dirs.length > 0) {
+    lines.push('| 目录 | 说明 |', '|------|------|');
+    for (const d of dirs) {
+      lines.push(`| \`${d.dir}/\` | ${d.role} |`);
+    }
+  } else {
+    lines.push('（未检测到顶层目录）');
+  }
+
+  lines.push('', '## 常用命令', '');
+  const pm = detectPackageManager(projectPath);
+  const scripts = pkg?.scripts || {};
+  const commands = AGENTS_MD_COMMANDS.filter(([n]) => scripts[n]);
+  if (commands.length > 0) {
+    lines.push('```bash');
+    for (const [n, comment] of commands) {
+      lines.push(`${formatScriptCommand(pm, n)}  # ${comment}`);
+    }
+    lines.push('```');
+  } else {
+    lines.push('（package.json 中未检测到常用脚本）');
+  }
+
+  lines.push('', '## 约束与治理', '');
+  if (governance.hasConfig) {
+    lines.push(`- 治理配置：\`.harness/config.yml\`${governance.preset ? `（preset: ${governance.preset}）` : ''}`);
+  }
+  if (governance.hasClaudeGovernance) {
+    const counts = [
+      governance.ironLaws !== undefined ? `Iron Laws ${governance.ironLaws} 条` : null,
+      governance.guidelines !== undefined ? `Guidelines ${governance.guidelines} 条` : null,
+    ].filter(Boolean).join('、');
+    lines.push(`- 约束清单：\`CLAUDE.md\` Governance Rules 块${counts ? `（${counts}）` : ''}`);
+  }
+  if (!governance.hasConfig && !governance.hasClaudeGovernance) {
+    lines.push('- 未检测到 harness 治理配置，可运行 `harness init` 初始化');
+  }
+
+  lines.push('', '## 知识入口', '');
+  if (hasKnowledge) {
+    // 不写条目数：.harness/knowledge 通常不入 git，条数是环境状态，
+    // 写进受 --check 漂移比对的文档会制造「必然过期」竞态（任何知识写入都使已提交文档过期）
+    lines.push('- `.harness/knowledge/`：项目知识库，用 `harness knowledge` 查询');
+  }
+  lines.push(
+    contextDocCount > 0
+      ? `- 各源码目录的 \`CONTEXT.md\` 是权威模块文档（现有 ${contextDocCount} 个），改动代码时同步更新`
+      : '- 各源码目录的 `CONTEXT.md` 是权威模块文档，缺失目录可由 `harness sync-docs` 生成模板'
+  );
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+/** 收集顶层目录及其一句话说明（排序保证确定性） */
+async function getTopLevelDirEntries(
+  projectPath: string,
+  srcDirs: string[]
+): Promise<Array<{ dir: string; role: string }>> {
+  let dirents: import('fs').Dirent[];
+  try {
+    dirents = await fs.readdir(projectPath, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+
+  const entries: Array<{ dir: string; role: string }> = [];
+  for (const d of dirents) {
+    if (!d.isDirectory()) continue;
+    if (AGENTS_MD_SKIP_DIRS.has(d.name)) continue;
+    // 隐藏目录只保留 .harness / .github
+    if (d.name.startsWith('.') && d.name !== '.harness' && d.name !== '.github') continue;
+    entries.push({ dir: d.name, role: await describeTopLevelDir(projectPath, d.name, srcDirs) });
+  }
+  entries.sort((a, b) => (a.dir < b.dir ? -1 : a.dir > b.dir ? 1 : 0));
+  return entries;
+}
+
+/** 顶层目录的一句话说明：知名目录 → monorepo 成员 → 源码根 → 子包 description → 占位 */
+async function describeTopLevelDir(projectPath: string, dir: string, srcDirs: string[]): Promise<string> {
+  const known = AGENTS_MD_DIR_ROLES[dir];
+  if (known) return known;
+
+  if (dir === 'apps' || dir === 'packages') {
+    const members = await listWorkspaceMembers(path.join(projectPath, dir));
+    if (members.length > 0) {
+      return `monorepo ${dir === 'apps' ? '应用' : '共享包'}：${members.join('、')}`;
+    }
+    return 'monorepo 工作区';
+  }
+
+  if (srcDirs.includes(dir)) return '源码目录';
+
+  const subPkg = await readPackageJsonLite(path.join(projectPath, dir));
+  if (subPkg?.description) return subPkg.description;
+
+  return '—';
+}
+
+/** 列出 monorepo 工作区成员（含 package.json 的子目录名，排序） */
+async function listWorkspaceMembers(dir: string): Promise<string[]> {
+  try {
+    const dirents = await fs.readdir(dir, { withFileTypes: true });
+    const members: string[] = [];
+    for (const d of dirents) {
+      if (!d.isDirectory() || d.name.startsWith('.')) continue;
+      if (existsSync(path.join(dir, d.name, 'package.json'))) {
+        members.push(d.name);
+      }
+    }
+    return members.sort();
+  } catch {
+    return [];
+  }
+}
+
+/** 收集治理信息：.harness/config.yml 与 CLAUDE.md 治理块（含铁律/指南计数） */
+async function getGovernanceInfo(projectPath: string): Promise<GovernanceInfo> {
+  const info: GovernanceInfo = { hasConfig: false, hasClaudeGovernance: false };
+
+  try {
+    const config = loadRawProjectConfig(projectPath);
+    info.hasConfig = config !== undefined;
+    if (config && typeof config.preset === 'string') {
+      info.preset = config.preset;
+    }
+  } catch {
+    // 配置不存在
+  }
+
+  try {
+    const claude = await fs.readFile(path.join(projectPath, 'CLAUDE.md'), 'utf-8');
+    if (/^##\s+Governance Rules/m.test(claude) || claude.includes('HARNESS_CONSTRAINTS_START')) {
+      info.hasClaudeGovernance = true;
+      info.ironLaws = countConstraintBullets(claude, 'Iron Laws');
+      info.guidelines = countConstraintBullets(claude, 'Guidelines');
+    }
+  } catch {
+    // CLAUDE.md 不存在
+  }
+
+  return info;
+}
+
+/** 统计 CLAUDE.md 指定约束分节下的条目数（`- **key**:` 行），分节不存在时返回 undefined */
+function countConstraintBullets(content: string, section: string): number | undefined {
+  const heading = new RegExp(`^###\\s+${section}[^\\n]*$`, 'm').exec(content);
+  if (!heading) return undefined;
+  const rest = content.slice(heading.index + heading[0].length);
+  const end = rest.search(/^###\s|^\s*<!--\s*HARNESS_CONSTRAINTS_END/m);
+  const block = end === -1 ? rest : rest.slice(0, end);
+  const items = block.match(/^-\s+\*\*[A-Za-z0-9_]+\*\*/gm);
+  return items ? items.length : 0;
+}
+
+/** 判断 .harness/knowledge 目录是否存在（只判存在性，不统计条数——条数易变，见 buildAgentsMd 注释） */
+async function hasKnowledgeDir(projectPath: string): Promise<boolean> {
+  try {
+    return (await fs.stat(path.join(projectPath, '.harness', 'knowledge'))).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/** 统计源码根内的 CONTEXT.md 数量（含源码根本身，跨根去重） */
+async function countContextDocs(projectPath: string, srcDirs: string[]): Promise<number> {
+  const found = new Set<string>();
+
+  async function scan(dir: string): Promise<void> {
+    let entries: import('fs').Dirent[];
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name === 'node_modules' || entry.name === '__tests__' || entry.name === 'dist') continue;
+      const entryPath = path.join(dir, entry.name);
+      if (existsSync(path.join(entryPath, 'CONTEXT.md'))) {
+        found.add(entryPath);
+      }
+      await scan(entryPath);
+    }
+  }
+
+  for (const root of srcDirs) {
+    const rootPath = path.join(projectPath, root);
+    if (existsSync(path.join(rootPath, 'CONTEXT.md'))) {
+      found.add(rootPath);
+    }
+    await scan(rootPath);
+  }
+  return found.size;
+}

package/src/cli/commands/sync-docs/capabilities-syncer.ts

@@ -0,0 +1,229 @@
+/**
+ * CAPABILITIES.md 同步器（工单 22）
+ *
+ * 支持两种格式：
+ * - 文件表格格式：模块/文件/说明三列表格，增删行维护
+ * - 能力清单格式：计数行（CLI Commands (N) 等），FreshnessRunner 校验与刷新
+ */
+
+import * as fs from 'fs/promises';
+import { IRON_LAWS, GUIDELINES, TIPS } from '../../../core/constraints/definitions';
+import { readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
+import { FreshnessRunner } from '../../../core/constraints/doc-freshness/runner';
+import type { DocFreshnessCheck } from '../../../types/project-config';
+import type { ModuleInfo, SyncResult } from './project-reader';
+
+/**
+ * 解析 CAPABILITIES.md 中的文件路径
+ *
+ * 提取所有表格行中提到的 .ts/.tsx/.js/.jsx 文件名（不含路径前缀）
+ * 用于模糊匹配：只要文档中提到了该文件名就算已记录
+ */
+export async function parseCapabilitiesFiles(capabilitiesPath: string): Promise<string[]> {
+  // 工单 19-B：解析收敛到 core/constraints/capabilities-parser；
+  // 此处保持原语义——文件条目取 basename，目录条目（以 / 结尾）原样保留
+  const entries = readCapabilitiesEntries(capabilitiesPath, { includeDirs: true });
+  const files: string[] = [];
+  for (const entry of entries) {
+    const value = entry.endsWith('/') ? entry : entry.split('/').pop()!;
+    if (!files.includes(value)) files.push(value);
+  }
+  return files;
+}
+
+/**
+ * 检测 CAPABILITIES.md 是否使用能力清单格式（计数行），而非文件表格格式
+ */
+export function isCapabilityListingFormat(content: string): boolean {
+  // 能力清单格式特征：包含 "CLI Commands (N)" / "Iron Laws (N)" 等计数行
+  return /CLI Commands\s*\(\d+\)/.test(content) ||
+    /Iron Laws?\s*\(\d+\)/.test(content) ||
+    /Guidelines?\s*\(\d+\)/.test(content);
+}
+
+/**
+ * 构建 CAPABILITIES.md 能力清单格式的检查配置
+ */
+function buildCapabilityChecks(): DocFreshnessCheck[] {
+  return [
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'CLI Commands',
+      pattern: 'CLI Commands\\s*\\((\\d+)\\)',
+      actual: { kind: 'dir_count', path: 'src/cli/commands', extension: '.ts', exclude: ['index.ts'] },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Quality Gates',
+      pattern: 'Quality Gates?\\s*\\((\\d+)\\)',
+      actual: { kind: 'dir_count', path: 'src/gates', extension: '.ts', exclude: ['index.ts', 'types.ts'] },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Iron Laws',
+      pattern: 'Iron Laws?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(IRON_LAWS).length },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Guidelines',
+      pattern: 'Guidelines?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(GUIDELINES).length },
+    },
+    {
+      type: 'doc_regex_count',
+      doc: 'CAPABILITIES.md',
+      label: 'Tips',
+      pattern: 'Tips?\\s*\\((\\d+)\\)',
+      actual: { kind: 'const_count', value: Object.keys(TIPS).length },
+    },
+  ];
+}
+
+/**
+ * 使用 FreshnessRunner 检查能力清单计数是否与代码一致（--check 模式）
+ */
+export function checkCapabilityCounts(
+  projectPath: string
+): { match: boolean; mismatches: string[] } {
+  const runner = new FreshnessRunner();
+  const checks = buildCapabilityChecks();
+  const results = runner.runAll({ checks }, projectPath);
+
+  const mismatches: string[] = [];
+  for (const r of results) {
+    if (!r.pass && r.message) {
+      mismatches.push(r.message);
+    }
+  }
+
+  return { match: mismatches.length === 0, mismatches };
+}
+
+/**
+ * 更新 CAPABILITIES.md 中的能力清单计数（write 模式）
+ *
+ * 使用 FreshnessRunner 获取实际计数，然后 regex 替换文档计数行。
+ */
+export function updateCapabilityCounts(content: string, projectPath: string): string {
+  const runner = new FreshnessRunner();
+
+  const cliCount = runner.countFromDir('src/cli/commands', '.ts', ['index.ts'], projectPath);
+  const gateCount = runner.countFromDir('src/gates', '.ts', ['index.ts', 'types.ts'], projectPath);
+  const ironCount = Object.keys(IRON_LAWS).length;
+  const guideCount = Object.keys(GUIDELINES).length;
+  const tipsCount = Object.keys(TIPS).length;
+
+  const replacements: [RegExp, string][] = [
+    [/CLI Commands\s*\(\d+\)/, `CLI Commands (${cliCount})`],
+    [/Quality Gates?\s*\(\d+\)/, `Quality Gates (${gateCount})`],
+    [/Iron Laws?\s*\(\d+\)/, `Iron Laws (${ironCount})`],
+    [/Guidelines?\s*\(\d+\)/, `Guidelines (${guideCount})`],
+    [/Tips?\s*\(\d+\)/, `Tips (${tipsCount})`],
+  ];
+
+  for (const [regex, replacement] of replacements) {
+    if (regex.test(content)) {
+      content = content.replace(regex, replacement);
+    }
+  }
+
+  return content;
+}
+
+/**
+ * 更新 CAPABILITIES.md 文件
+ */
+export async function updateCapabilitiesFile(
+  capabilitiesPath: string,
+  currentModules: ModuleInfo[],
+  existingFiles: string[],
+  result: SyncResult,
+): Promise<void> {
+  let content: string;
+  try {
+    content = await fs.readFile(capabilitiesPath, 'utf-8');
+  } catch {
+    // 文件不存在，创建新的
+    content = generateCapabilitiesContent(currentModules);
+    await fs.writeFile(capabilitiesPath, content, 'utf-8');
+    return;
+  }
+
+  // 如果有表格行，更新表格
+  if (existingFiles.length > 0) {
+    // 移除已删除文件的行
+    for (const removed of result.removed) {
+      const escapedFile = removed.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      // 第二列存完整路径，basename 只在末尾出现，用 [^|]* 匹配路径前缀
+      const rowRegex = new RegExp(`^\\|[^|]*\\|[^|]*\\b${escapedFile}\\s*\\|.*$`, 'gm');
+      content = content.replace(rowRegex, '');
+    }
+
+    // 添加新文件的行（在最后一个表格行之后）
+    if (result.added.length > 0) {
+      const getBasenameLocal = (f: string) => f.split('/').pop()!;
+      const addedModules = currentModules.filter(m => result.added.includes(getBasenameLocal(m.file)));
+      const tableEndRegex = /(^\|[^|]+\|[^|]+\|[^|]+\|\s*$)/gm;
+      let lastTableRow = '';
+      let match;
+      while ((match = tableEndRegex.exec(content)) !== null) {
+        lastTableRow = match[0];
+      }
+
+      if (lastTableRow) {
+        const newRows = addedModules.map(m =>
+          `| ${m.name} | ${m.file} | ${m.description} |`
+        ).join('\n');
+        content = content.replace(lastTableRow, lastTableRow + '\n' + newRows);
+      }
+    }
+
+    // 清理多余空行
+    content = content.replace(/\n{3,}/g, '\n\n');
+  } else {
+    // 没有表格，追加模块表格
+    content += '\n\n' + generateModuleTable(currentModules);
+  }
+
+  // 更新最后更新时间
+  const now = new Date().toISOString().split('T')[0];
+  content = content.replace(
+    /最后更新[:：].*/,
+    `最后更新: ${now}`
+  );
+
+  await fs.writeFile(capabilitiesPath, content, 'utf-8');
+}
+
+/**
+ * 生成 CAPABILITIES.md 内容
+ */
+function generateCapabilitiesContent(modules: ModuleInfo[]): string {
+  const now = new Date().toISOString().split('T')[0];
+  return `# CAPABILITIES.md
+
+> 最后更新: ${now}
+
+---
+
+${generateModuleTable(modules)}
+`;
+}
+
+/**
+ * 生成模块表格
+ */
+function generateModuleTable(modules: ModuleInfo[]): string {
+  if (modules.length === 0) return '';
+
+  const rows = modules.map(m =>
+    `| ${m.name} | ${m.file} | ${m.description} |`
+  ).join('\n');
+
+  return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
+}

package/src/cli/commands/sync-docs/context-syncer.ts

@@ -0,0 +1,108 @@
+/**
+ * CONTEXT.md 同步器（工单 22）：缺失模板生成 + 既有文件发现 + 过时判定
+ */
+
+import * as fs from 'fs/promises';
+import * as path from 'path';
+
+/**
+ * 创建 CONTEXT.md 模板
+ */
+export async function createContextMd(projectPath: string, dir: string): Promise<void> {
+  const contextPath = path.join(projectPath, dir, 'CONTEXT.md');
+  const dirName = path.basename(dir);
+
+  const content = `# ${dirName}
+
+> 此文件描述 ${dir} 目录的职责和上下文。
+> 请阅读本目录的源代码，然后填写以下各节。
+> 如果使用 AI 编码助手，将本文件内容作为 prompt 请求它分析并填写。
+
+## 职责
+
+本目录的核心职责是？
+
+## 核心导出
+
+本目录对外暴露的主要模块/函数：
+
+## 依赖关系
+
+本目录依赖哪些其他模块，谁依赖本目录？
+
+## 注意事项
+
+开发时需要注意的约束或约定：
+`;
+
+  await fs.mkdir(path.join(projectPath, dir), { recursive: true });
+  await fs.writeFile(contextPath, content, 'utf-8');
+}
+
+/**
+ * 自动发现已有 CONTEXT.md 文件的目录（相对于 projectPath）
+ */
+export async function findExistingContextFiles(projectPath: string, srcDirs: string[]): Promise<string[]> {
+  const dirs: string[] = [];
+
+  async function scan(dir: string): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+      const entryPath = path.join(dir, entry);
+      const stat = await fs.stat(entryPath);
+      if (stat.isDirectory()) {
+        // 检查该目录是否有 CONTEXT.md
+        try {
+          await fs.access(path.join(entryPath, 'CONTEXT.md'));
+          dirs.push(path.relative(projectPath, entryPath));
+        } catch {
+          // 没有，继续递归
+        }
+        await scan(entryPath);
+      }
+    }
+  }
+
+  for (const srcDir of srcDirs) {
+    await scan(path.join(projectPath, srcDir));
+  }
+  return dirs;
+}
+
+/**
+ * 获取目录下最新 .ts 文件的修改时间
+ * 返回 null 如果目录不存在或没有 .ts 文件
+ */
+export async function getLatestTsMtime(dirPath: string): Promise<number | null> {
+  let latest: number | null = null;
+
+  async function scan(dir: string): Promise<void> {
+    let entries: string[];
+    try {
+      entries = await fs.readdir(dir);
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      if (entry === 'node_modules' || entry === '__tests__' || entry === 'dist') continue;
+      const entryPath = path.join(dir, entry);
+      const stat = await fs.stat(entryPath);
+      if (stat.isDirectory()) {
+        await scan(entryPath);
+      } else if (entry.endsWith('.ts') && !entry.endsWith('.d.ts')) {
+        if (latest === null || stat.mtimeMs > latest) {
+          latest = stat.mtimeMs;
+        }
+      }
+    }
+  }
+
+  await scan(dirPath);
+  return latest;
+}