@dommaker/harness 0.16.8 → 0.16.9

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

@@ -7,9 +7,11 @@
  */
 
 import * as fs from 'fs/promises';
+import * as path from 'path';
 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 { CapabilitiesMode } from '../../../core/project-config-loader';
 import type { DocFreshnessCheck } from '../../../types/project-config';
 import type { ModuleInfo, SyncResult } from './project-reader';
 
@@ -137,19 +139,23 @@ export function updateCapabilityCounts(content: string, projectPath: string): st
 
 /**
  * 更新 CAPABILITIES.md 文件
+ *
+ * module 模式（governance.capabilities.mode=module）下不再为新文件自动加表格行
+ * （目录条目需人工策划登记），幽灵行剔除与「最后更新」刷新保留。
  */
 export async function updateCapabilitiesFile(
   capabilitiesPath: string,
   currentModules: ModuleInfo[],
   existingFiles: string[],
   result: SyncResult,
+  mode: CapabilitiesMode = 'file',
 ): Promise<void> {
   let content: string;
   try {
     content = await fs.readFile(capabilitiesPath, 'utf-8');
   } catch {
-    // 文件不存在，创建新的
-    content = generateCapabilitiesContent(currentModules);
+    // 文件不存在，创建新的（module 模式生成按目录聚合的模板）
+    content = generateCapabilitiesContent(currentModules, mode);
     await fs.writeFile(capabilitiesPath, content, 'utf-8');
     return;
   }
@@ -164,8 +170,8 @@ export async function updateCapabilitiesFile(
       content = content.replace(rowRegex, '');
     }
 
-    // 添加新文件的行（在最后一个表格行之后）
-    if (result.added.length > 0) {
+    // 添加新文件的行（在最后一个表格行之后）；module 模式跳过
+    if (mode !== 'module' && 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;
@@ -186,8 +192,8 @@ export async function updateCapabilitiesFile(
     // 清理多余空行
     content = content.replace(/\n{3,}/g, '\n\n');
   } else {
-    // 没有表格，追加模块表格
-    content += '\n\n' + generateModuleTable(currentModules);
+    // 没有表格，追加模块表格（module 模式按目录聚合）
+    content += '\n\n' + (mode === 'module' ? generateDirTable(currentModules) : generateModuleTable(currentModules));
   }
 
   // 更新最后更新时间
@@ -203,7 +209,7 @@ export async function updateCapabilitiesFile(
 /**
  * 生成 CAPABILITIES.md 内容
  */
-function generateCapabilitiesContent(modules: ModuleInfo[]): string {
+function generateCapabilitiesContent(modules: ModuleInfo[], mode: CapabilitiesMode = 'file'): string {
   const now = new Date().toISOString().split('T')[0];
   return `# CAPABILITIES.md
 
@@ -211,7 +217,7 @@ function generateCapabilitiesContent(modules: ModuleInfo[]): string {
 
 ---
 
-${generateModuleTable(modules)}
+${mode === 'module' ? generateDirTable(modules) : generateModuleTable(modules)}
 `;
 }
 
@@ -227,3 +233,74 @@ function generateModuleTable(modules: ModuleInfo[]): string {
 
   return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
 }
+
+/**
+ * 生成按目录聚合的模块表格（module 模式模板）
+ *
+ * 每个源码子目录一行目录条目（| core | src/core/ | core |），
+ * 文件直接位于源码根时聚到根目录一行。
+ */
+function generateDirTable(modules: ModuleInfo[]): string {
+  if (modules.length === 0) return '';
+
+  const dirs: string[] = [];
+  for (const m of modules) {
+    const dir = path.posix.dirname(m.file);
+    const key = dir === '.' ? '' : dir + '/';
+    if (key && !dirs.includes(key)) dirs.push(key);
+  }
+
+  const rows = dirs.map(d => {
+    const name = d.replace(/\/$/, '').split('/').pop()!;
+    return `| ${name} | ${d} | ${name} |`;
+  }).join('\n');
+
+  return `| 模块 | 文件 | 说明 |\n|------|------|------|\n${rows}`;
+}
+
+/**
+ * 将 CAPABILITIES.md 文件表格折叠为目录条目（--compact 一次性迁移）
+ *
+ * 按文件条目（第二列）的 dirname 分组：同组 ≥2 个文件条目折叠为一行目录条目
+ * （替换组内第一行、删除其余行，说明取组内第一行，为空则用目录名）；
+ * 单独成组的文件行、表头、非表格文本、PRESERVE 块原样保留。
+ * 已折叠的目录条目行不再匹配文件条目，故幂等。
+ */
+export function compactCapabilitiesContent(content: string): string {
+  const lines = content.split('\n');
+  const fileEntryRegex = /\.(?:ts|tsx|js|jsx)$/;
+  const rowRegex = /^\|[^|]+\|[^|]+\|[^|]+\|\s*$/;
+
+  interface TableRow {
+    lineIndex: number;
+    file: string;
+    desc: string;
+  }
+
+  // 收集文件条目行，按 dirname 分组（无目录前缀的条目不参与折叠）
+  const groups = new Map<string, TableRow[]>();
+  for (let i = 0; i < lines.length; i++) {
+    if (!rowRegex.test(lines[i])) continue;
+    const cells = lines[i].split('|').map(c => c.trim());
+    const file = cells[2] ?? '';
+    if (!fileEntryRegex.test(file)) continue;
+    const dir = path.posix.dirname(file);
+    if (dir === '.') continue;
+    const group = groups.get(dir) ?? [];
+    group.push({ lineIndex: i, file, desc: cells[3] ?? '' });
+    groups.set(dir, group);
+  }
+
+  const deleteLines = new Set<number>();
+  for (const [dir, rows] of groups) {
+    if (rows.length < 2) continue;
+    const name = dir.split('/').pop()!;
+    const desc = rows[0].desc || name;
+    lines[rows[0].lineIndex] = `| ${name} | ${dir}/ | ${desc} |`;
+    for (const row of rows.slice(1)) {
+      deleteLines.add(row.lineIndex);
+    }
+  }
+
+  return lines.filter((_, i) => !deleteLines.has(i)).join('\n');
+}

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

@@ -16,8 +16,9 @@ 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 { aggregateToSourceSubdir, readCapabilitiesEntries } from '../../../core/constraints/capabilities-parser';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
+import { getCapabilitiesMode } from '../../../core/project-config-loader';
 import { getSourceDirs, scanSourceModules, getRequiredContextDirs } from './project-reader';
 import type { ModuleInfo, SyncResult } from './project-reader';
 import {
@@ -26,6 +27,7 @@ import {
   checkCapabilityCounts,
   updateCapabilityCounts,
   updateCapabilitiesFile,
+  compactCapabilitiesContent,
 } from './capabilities-syncer';
 import { createContextMd, findExistingContextFiles, getLatestTsMtime } from './context-syncer';
 import { buildAgentsMd } from './agents-syncer';
@@ -42,6 +44,8 @@ export interface SyncDocsOptions {
   json?: boolean;
   /** 同步 AGENTS.md（agent 导读）；PRESERVE 标记段在重新生成时原样保留 */
   agents?: boolean;
+  /** 一次性迁移：将 CAPABILITIES.md 文件表格折叠为目录条目 */
+  compact?: boolean;
 }
 
 /**
@@ -51,6 +55,26 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   const projectPath = options.projectPath || process.cwd();
   const isCheck = options.check === true;
   const isJson = options.json === true;
+  const capsMode = getCapabilitiesMode(projectPath);
+
+  // --compact：一次性迁移，将文件表格折叠为目录条目后直接返回
+  if (options.compact) {
+    const capsPath = path.join(projectPath, 'CAPABILITIES.md');
+    try {
+      const content = await fs.readFile(capsPath, 'utf-8');
+      const compacted = compactCapabilitiesContent(content);
+      if (compacted !== content) {
+        await fs.writeFile(capsPath, compacted, 'utf-8');
+        if (!isJson) console.log(chalk.green('✅ 已将 CAPABILITIES.md 文件表格折叠为目录条目'));
+      } else {
+        if (!isJson) console.log(chalk.green('✅ CAPABILITIES.md 无需折叠'));
+      }
+      return true;
+    } catch {
+      if (!isJson) console.log(chalk.red('❌ CAPABILITIES.md 不存在，无法折叠'));
+      return false;
+    }
+  }
 
   if (!isJson) {
     if (isCheck) {
@@ -88,7 +112,8 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   let capsIsCapabilityListing = false;
   try {
     capsContent = await fs.readFile(capabilitiesPath, 'utf-8');
-    if (isCapabilityListingFormat(capsContent)) {
+    // mode=listing 是清单格式的显式声明，与嗅探结果等价
+    if (capsMode === 'listing' || isCapabilityListingFormat(capsContent)) {
       capsIsCapabilityListing = true;
     } else {
       existingFiles = await parseCapabilitiesFiles(capabilitiesPath);
@@ -116,13 +141,31 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
     // （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));
+    if (capsMode === 'module') {
+      // module 模式：文件条目精确匹配或目录条目前缀覆盖；
+      // added 不再是逐文件列表，聚合为「未覆盖目录」（与 capability_sync checker 同规则）
+      const entries = readCapabilitiesEntries(capabilitiesPath, { includeDirs: true });
+      const fileEntries = entries.filter(e => !e.endsWith('/'));
+      const dirEntries = entries.filter(e => e.endsWith('/'));
+      const uncoveredDirs = new Set<string>();
+      for (const m of currentModules) {
+        const covered =
+          fileEntries.includes(m.file) || dirEntries.some(d => m.file.startsWith(d));
+        if (!covered) {
+          const root = srcDirs.find(d => m.file.startsWith(d + '/')) || srcDirs[0] || '';
+          uncoveredDirs.add(aggregateToSourceSubdir(root, m.file));
+        }
+      }
+      result.added = [...uncoveredDirs];
+    } else {
+      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 对比，
@@ -235,18 +278,30 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
     }
 
     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 (capsMode === 'module') {
+        // module 模式：added 为聚合后的未覆盖目录，需人工登记目录条目
+        jsonOutput.added = result.added.map(d => ({ dir: d }));
+        jsonOutput.removed = result.removed.map(f => ({ file: f }));
+        (jsonOutput.resolution as Array<Record<string, unknown>>).push({
+          action: 'register-capability-dirs',
+          details:
+            '在 CAPABILITIES.md 中为这些目录登记一行目录条目（如 `| 模块名 | src/xxx/ | 说明 |`）',
+          dirs: result.added,
+        });
+      } else {
+        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) {
@@ -282,8 +337,16 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   }
 
   if (result.added.length > 0) {
-    console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
-    result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+    if (capsMode === 'module') {
+      console.log(chalk.yellow(`\n📄 CAPABILITIES.md 未登记以下模块（目录）:`));
+      result.added.forEach(d => console.log(chalk.gray(`  + ${d}`)));
+      console.log(
+        chalk.gray('  请在 CAPABILITIES.md 中为这些目录登记一行目录条目（如 `| 模块名 | src/xxx/ | 说明 |`）')
+      );
+    } else {
+      console.log(chalk.yellow(`\n📄 CAPABILITIES.md 缺少以下模块:`));
+      result.added.forEach(f => console.log(chalk.gray(`  + ${f}`)));
+    }
   }
 
   if (result.removed.length > 0) {
@@ -337,7 +400,7 @@ export async function syncDocs(options: SyncDocsOptions): Promise<boolean> {
   }
 
   if (!capsIsCapabilityListing && hasTableIssues) {
-    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result);
+    await updateCapabilitiesFile(capabilitiesPath, currentModules, existingFiles, result, capsMode);
     console.log(chalk.green(`\n✅ 已更新 CAPABILITIES.md`));
   }
 

package/src/core/constraints/capabilities-parser.ts

@@ -68,3 +68,18 @@ export function readCapabilitiesEntries(capabilitiesPath: string, options: Capab
     return [];
   }
 }
+
+/**
+ * 未覆盖文件的聚合目录（module 模式）
+ *
+ * 规则：取源码根下的第一级子目录（root=src、file=src/core/foo.ts → src/core/）；
+ * 源码根直接下的文件聚到根（file=src/foo.ts → src/）。
+ */
+export function aggregateToSourceSubdir(root: string, file: string): string {
+  if (!root) return file;
+  const prefix = root.endsWith('/') ? root : root + '/';
+  const rest = file.startsWith(prefix) ? file.slice(prefix.length) : file;
+  const idx = rest.indexOf('/');
+  if (idx === -1) return prefix;
+  return prefix + rest.slice(0, idx) + '/';
+}

package/src/core/constraints/checkers/capability-sync.ts

@@ -4,11 +4,15 @@
  * 两步验证：
  *   1. Git diff 增量 — 当前变更的非测试文件是否在文档中有记录
  *   2. 全量扫描 — 源码根下所有源文件是否都在 CAPABILITIES.md 中（T-058）
+ *
+ * governance.capabilities.mode=module 时 step 2 改按目录覆盖判定：
+ * 文件条目精确匹配或目录条目前缀覆盖，未覆盖文件按源码根下第一级子目录聚合。
  */
 
 import { existsSync } from 'fs';
 import { join } from 'path';
-import { readCapabilitiesEntries } from '../capabilities-parser';
+import { aggregateToSourceSubdir, readCapabilitiesEntries } from '../capabilities-parser';
+import { getCapabilitiesMode } from '../../project-config-loader';
 import { detectSourceRoots } from '../../../utils/detect-source-roots';
 import type { ConstraintCheck } from './types';
 
@@ -49,7 +53,31 @@ export const capabilitySync: ConstraintCheck = {
       }
 
       // ── Step 2: 全量源码根扫描（T-058 修复核心）──
-      if (listedFiles.length > 0) {
+      const capabilitiesMode = getCapabilitiesMode(projectPath);
+      if (capabilitiesMode === 'module') {
+        // module 模式：文件条目精确匹配 或 目录条目前缀覆盖；
+        // 未覆盖文件按源码根下第一级子目录聚合，任一组非空即失败
+        const entries = readCapabilitiesEntries(capabilitiesPath, { includeDirs: true });
+        if (entries.length > 0) {
+          const fileEntries = entries.filter(e => !e.endsWith('/'));
+          const dirEntries = entries.filter(e => e.endsWith('/'));
+          const uncoveredDirs = new Set<string>();
+          const sourceRoots = detectSourceRoots(projectPath);
+          for (const root of sourceRoots) {
+            const srcDir = join(projectPath, root);
+            if (existsSync(srcDir)) {
+              for (const file of env.srcScan(root)) {
+                const covered =
+                  fileEntries.includes(file) || dirEntries.some(d => file.startsWith(d));
+                if (!covered) {
+                  uncoveredDirs.add(aggregateToSourceSubdir(root, file));
+                }
+              }
+            }
+          }
+          if (uncoveredDirs.size > 0) return false;
+        }
+      } else if (listedFiles.length > 0) {
         const sourceRoots = detectSourceRoots(projectPath);
         for (const root of sourceRoots) {
           const srcDir = join(projectPath, root);

package/src/core/constraints/definitions/guidelines.ts

@@ -197,7 +197,7 @@ export const GUIDELINES: Record<string, Constraint> = {
   capability_sync: {
     id: 'capability_sync',
     rule: 'CODE CHANGES MUST UPDATE CAPABILITIES.MD',
-    message: '核心模块变更必须同步功能清单',
+    message: '核心模块变更必须同步功能清单（支持模块级目录条目登记）',
     level: 'guideline',
     trigger: ['module_creation', 'module_modification', 'module_deletion', 'module_extension'],
     enforcement: 'update-capabilities',
@@ -212,7 +212,9 @@ export const GUIDELINES: Record<string, Constraint> = {
 [不强制更新]
 - 内部重构不影响对外接口
 - bug fix 不改变功能
-- 性能优化不改变接口`,
+- 性能优化不改变接口
+
+支持模块级目录条目登记：governance.capabilities.mode=module 时按目录覆盖判定（如 src/core/ 一条目录条目覆盖该目录下所有源文件）。`,
     exceptions: ['internal_refactor', 'bug_fix_only', 'performance_optimization'],
   },
 

package/src/core/project-config-loader.ts

@@ -13,6 +13,7 @@ import type {
   ProjectConfig,
   CustomConstraintDefinition,
   MergedConstraintsConfig,
+  CapabilitiesConfig,
 } from '../types/project-config';
 import { IRON_LAWS, GUIDELINES, TIPS } from './constraints/definitions';
 
@@ -69,6 +70,29 @@ export function loadRawProjectConfig(projectPath: string): Record<string, unknow
   return raw;
 }
 
+/**
+ * CAPABILITIES.md 登记模式（governance.capabilities.mode）
+ */
+export type CapabilitiesMode = NonNullable<CapabilitiesConfig['mode']>;
+
+/**
+ * 读取 governance.capabilities.mode（缺省 'file'，向后兼容）
+ *
+ * 配置缺失/解析失败/取值非法时一律回落 'file'。
+ */
+export function getCapabilitiesMode(projectPath: string): CapabilitiesMode {
+  try {
+    const raw = loadRawProjectConfig(projectPath);
+    const governance = raw?.governance as Record<string, unknown> | undefined;
+    const capabilities = governance?.capabilities as Record<string, unknown> | undefined;
+    const mode = capabilities?.mode;
+    if (mode === 'file' || mode === 'module' || mode === 'listing') return mode;
+  } catch {
+    // 配置缺失或解析失败，按默认 file 处理
+  }
+  return 'file';
+}
+
 /**
  * 项目配置加载器
  */

package/src/types/project-config.ts

@@ -60,6 +60,19 @@ export interface ContextFilesConfig {
   required_dirs?: string[];
 }
 
+/**
+ * CAPABILITIES.md 登记模式配置
+ */
+export interface CapabilitiesConfig {
+  /**
+   * 登记模式：
+   * - file：逐文件登记（默认，历史行为）
+   * - module：模块级目录条目登记，按目录前缀覆盖判定
+   * - listing：能力清单格式（计数行）的显式声明
+   */
+  mode?: 'file' | 'module' | 'listing';
+}
+
 /**
  * CHANGELOG 配置
  */
@@ -183,6 +196,9 @@ export interface GovernanceConfig {
   /** CONTEXT.md 配置 */
   context_files?: ContextFilesConfig;
 
+  /** CAPABILITIES.md 登记模式配置 */
+  capabilities?: CapabilitiesConfig;
+
   /** CHANGELOG 配置 */
   changelog?: ChangelogConfig;