@dommaker/harness 1.3.0 → 1.5.0

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

@@ -0,0 +1,166 @@
+/**
+ * CAPABILITIES.md 声明与代码实况的对照判定（ADR-0009）
+ *
+ * 纯判定 module：吃「文档内容 + 实际文件清单（+ 增量清单）」，一次产出全部判定结果；
+ * 不做任何 fs/git IO（存在性可选注入）。此前同一套覆盖/幽灵规则在
+ * capability_sync / docs_freshness / sync-docs 三处独立实现，靠「同规则」注释人工同步，
+ * 同一 bug（basename 碰撞、后缀误配）在多处各修一遍——此处为唯一真相源。
+ *
+ * 方向：
+ *   代码→文档  uncoveredChanges / uncoveredFiles / uncoveredDirs（漏登记）
+ *   文档→代码  deadEntries（幽灵：文档登记的路径既不在代码实况中、文件系统中也不存在）
+ *
+ * 解析口径（ADR-0009）：表格所有单元格收集，文件条目与目录条目都参与覆盖；
+ * 「只看第二列」的历史读法废弃。幽灵判定同样覆盖文件与目录条目（口径从严）。
+ * mode=module / file 的差异不在判定层，而是调用方取哪份输出形状：
+ * module 读 uncoveredDirs（目录聚合），file 读 uncoveredFiles（逐文件）。
+ */
+
+import { join, relative } from 'path';
+import {
+  aggregateToSourceSubdir,
+  isCapabilityListingFormat,
+  parseCapabilitiesEntries,
+} from './capabilities-parser';
+import { findTsSourceFiles } from '../../utils/file-walk';
+
+/** markdown 表格分隔行（|------|------|）：区分「无表格的散文文档」与「有表格但零条目」 */
+const TABLE_SEPARATOR_REGEX = /^\s*\|[\s:|-]+\|\s*$/m;
+
+export interface ReconcileInput {
+  /** CAPABILITIES.md 内容 */
+  content: string;
+  /** 代码实况全集：项目相对路径的源文件清单（由调用方收集，见 collectSourceFiles） */
+  populationFiles: string[];
+  /** 增量变更文件（项目相对路径）；无 git 概念的消费方传空/不传 */
+  changedFiles?: string[];
+  /** 存在性 oracle（项目相对路径 → 是否存在）；缺省退化为「代码实况兜底」 */
+  fileExists?: (relPath: string) => boolean;
+  /** 源码根（如 'src'、'apps/api/src'）：未覆盖聚合与条目多根相对路径解析用 */
+  sourceRoots?: string[];
+}
+
+export interface CapabilityVerdict {
+  /** 文档中的文件条目（原样路径，可能为全路径或裸文件名） */
+  fileEntries: string[];
+  /** 文档中的目录条目（以 / 结尾） */
+  dirEntries: string[];
+  /** 参与覆盖判定的条目集 = 文件条目 + 目录条目 */
+  coverageEntries: string[];
+  /** 文档含 markdown 表格（区分「散文文档」与「有表格零条目」） */
+  hasTable: boolean;
+  /** 能力清单格式（计数行文档）：无文件表可核对，调用方据此短路 */
+  listingFormat: boolean;
+  /** 增量文件中未被覆盖的（capability_sync Step1） */
+  uncoveredChanges: string[];
+  /** 代码实况中未被文档登记的 */
+  uncoveredFiles: string[];
+  /** 未覆盖文件按源码根下第一级子目录聚合（module 模式的 added 形状） */
+  uncoveredDirs: string[];
+  /** 幽灵条目（文件 + 目录）：文档登记但代码实况与文件系统均不存在 */
+  deadEntries: string[];
+}
+
+/**
+ * 变更文件是否被条目覆盖（ADR-0009 唯一覆盖规则）
+ *
+ * 目录条目（以 / 结尾）前缀匹配；文件条目精确匹配或路径边界后缀匹配
+ * （兼容 basename 条目，但拒绝 xfoo.ts 命中 foo.ts、docs/src/foo.tsx 命中 src/foo.ts
+ * 这类 endsWith/includes 模糊匹配造成的碰撞）
+ */
+function isCoveredBy(entries: string[], file: string): boolean {
+  return entries.some((listed) =>
+    listed.endsWith('/')
+      ? file.startsWith(listed)
+      : file === listed || file.endsWith('/' + listed)
+  );
+}
+
+/** 条目多根相对路径的存在性：项目根直查 + 各源码根前缀（docs_freshness/sync-docs 历史同语义） */
+function entryExistsOnDisk(
+  entry: string,
+  fileExists: (rel: string) => boolean,
+  sourceRoots: string[]
+): boolean {
+  if (fileExists(entry)) return true;
+  return sourceRoots.some((root) => fileExists(`${root}/${entry}`));
+}
+
+export function reconcileCapabilities(input: ReconcileInput): CapabilityVerdict {
+  const {
+    content,
+    populationFiles,
+    changedFiles = [],
+    fileExists = () => false,
+    sourceRoots = [],
+  } = input;
+
+  const allEntries = parseCapabilitiesEntries(content, { includeDirs: true });
+  const fileEntries = allEntries.filter((e) => !e.endsWith('/'));
+  const dirEntries = allEntries.filter((e) => e.endsWith('/'));
+  const coverageEntries = [...fileEntries, ...dirEntries];
+
+  const uncoveredFiles = populationFiles.filter((f) => !isCoveredBy(coverageEntries, f));
+  const uncoveredDirs = [...new Set(
+    uncoveredFiles.map((file) => {
+      // 与 sync-docs 历史聚合同语义：归属第一个能前缀匹配的来源根，兜底首根
+      const root = sourceRoots.find((d) => file.startsWith(d + '/')) || sourceRoots[0] || '';
+      return aggregateToSourceSubdir(root, file);
+    })
+  )];
+
+  // 条目在代码实况中仍有对应文件即算活（裸文件名条目无法做存在性判定的兜底）
+  const aliveByPopulation = (entry: string): boolean =>
+    populationFiles.some((f) => isCoveredBy([entry], f));
+
+  const deadEntries = allEntries.filter((entry) => {
+    if (entryExistsOnDisk(entry, fileExists, sourceRoots)) return false;
+    return !aliveByPopulation(entry);
+  });
+
+  return {
+    fileEntries,
+    dirEntries,
+    coverageEntries,
+    hasTable: TABLE_SEPARATOR_REGEX.test(content),
+    listingFormat: isCapabilityListingFormat(content),
+    uncoveredChanges: changedFiles.filter((f) => !isCoveredBy(coverageEntries, f)),
+    uncoveredFiles,
+    uncoveredDirs,
+    deadEntries,
+  };
+}
+
+/**
+ * 变更清单中的「有意义的代码变更」：仅 .ts/.tsx/.js 且非测试文件
+ * （capability_sync Step1 的历史过滤规则，收口于此）
+ */
+export function significantCodeChanges(diffNames: string[]): string[] {
+  return diffNames
+    .filter((f) => f.endsWith('.ts') || f.endsWith('.tsx') || f.endsWith('.js'))
+    .filter((f) => !f.includes('__tests__') && !f.includes('.test.') && !f.includes('.spec.'));
+}
+
+/**
+ * 收集源码根下的实际文件清单（项目相对路径）
+ *
+ * 对 utils/file-walk 的统一封装，替代各调用方自拼 join/relative。
+ * 扩展名口径保持各调用方现状（checker 不含 .tsx；sync-docs 的模块扫描需
+ * ModuleInfo 元数据，继续走 scanSourceModules）——统一扩展名口径属行为变更，
+ * 不在本次纯重构范围（ADR-0009 记录在案）。
+ */
+export function collectSourceFiles(
+  projectPath: string,
+  roots: string[],
+  options: { includeTsx?: boolean } = {}
+): string[] {
+  const files: string[] = [];
+  for (const root of roots) {
+    const found = findTsSourceFiles(join(projectPath, root), {
+      skipIndex: true,
+      includeTsx: options.includeTsx,
+    });
+    files.push(...found.map((f) => relative(projectPath, f)));
+  }
+  return files;
+}

package/src/core/constraints/checker.ts

@@ -12,32 +12,33 @@ import {
   ConstraintContext,
   ConstraintResult,
   ConstraintCheckResult,
-  ConstraintTrigger,
   ConstraintLevel,
   ConstraintViolationError,
 } from '../../types/constraint';
 import type { ExecutionTrace } from '../../types/trace';
-import { getTraceCollector } from '../../monitoring/traces';
 import { IRON_LAWS, GUIDELINES, PROMPTS } from './definitions';
 import type { MergedConstraintsConfig } from '../../types/project-config';
-import { normalizeTriggers } from '../../utils/exec';
-import { runCommand } from '../../utils/exec';
+import { matchesTrigger } from '../../utils/exec';
 import { join, relative } from 'path';
 import { CheckCache } from './check-cache';
 import { findTsSourceFiles } from '../../utils/file-walk';
-import { getConstraintCheck, buildCheckEnv, type CheckOutcome } from './checkers';
+import { getConstraintCheck, buildCheckEnv, normalizeCheckOutcome, type CheckOutcome } from './checkers';
+import { createGitEvidence, type GitEvidence } from './git-evidence';
 
 /**
- * trace 记录器最小接口（原工单 15 为消除 core→monitoring 循环；现 monitoring
- * 不反向依赖 core，方向单向、无环，checker 可直接值引用 getTraceCollector）
+ * trace 记录器最小接口（工单 15 decycle 收尾，harness#88）
  *
- * checker 不构造收集器；生产路径首次记录时惰性接线 getTraceCollector()
- * （幂等单点，ADR-0003），测试可经 setTraceRecorder 注入替身。
+ * core 不上行依赖 monitoring：记录器经**构造参数**注入，未注入 = no-op
+ * （默认无副作用）。真实收集器由组合根接线——CLI check/report 与 bootstrap
+ * 各自 `new ConstraintChecker(getTraceCollector())`。
  */
 export interface TraceRecorder {
   record(trace: ExecutionTrace): void;
 }
 
+/** 未注入时的默认记录器：不记录 */
+const NOOP_TRACE_RECORDER: TraceRecorder = { record: () => undefined };
+
 /**
  * 约束检查器
  */
@@ -47,60 +48,15 @@ export class ConstraintChecker {
   /** 检查结果缓存（S7：src 扫描等重复 I/O，TTL=1s 防跨测试污染） */
   private cache: CheckCache = new CheckCache({ ttlMs: 1000 });
 
-  /**
-   * run 级 memo（工单 18）：一次 checkConstraints 内
-   * git diff 等命令只执行一次；run 外直接调用私有检查方法时不 memo（恒新鲜）。
-   */
-  private runCache: Map<string, Promise<string>> | null = null;
-
-  /** trace 记录器（注入式；null = 未显式注入，首次记录时惰性接线全局收集器） */
-  private traceRecorder: TraceRecorder | null = null;
-
-  private constructor() {}
-
-  /**
-   * 取 trace 记录器：未显式注入时惰性接线全局收集器（幂等，ADR-0003 副作用收敛）
-   */
-  private getRecorder(): TraceRecorder {
-    if (!this.traceRecorder) {
-      this.traceRecorder = getTraceCollector();
-    }
-    return this.traceRecorder;
-  }
-
-  /**
-   * run 内 memoize；无活动 run 时直接执行（工单 18）
-   */
-  private memoRun(key: string, fn: () => Promise<string>): Promise<string> {
-    if (!this.runCache) return fn();
-    let pending = this.runCache.get(key);
-    if (!pending) {
-      pending = fn();
-      this.runCache.set(key, pending);
-    }
-    return pending;
-  }
-
-  /**
-   * staged 全量 diff（同一次 run 内只执行一次 git 命令，工单 18）
-   */
-  private getStagedDiff(projectPath: string): Promise<string> {
-    return this.memoRun(`git_diff_staged:${projectPath}`, () =>
-      runCommand('git diff --cached', projectPath)
-    );
-  }
+  /** trace 记录器（构造注入；缺省 no-op） */
+  private readonly traceRecorder: TraceRecorder;
 
-  /**
-   * staged 变更文件名列表（同一次 run 内只执行一次 git 命令，工单 18）
-   */
-  private getStagedDiffNames(projectPath: string): Promise<string> {
-    return this.memoRun(`git_diff_staged_names:${projectPath}`, () =>
-      runCommand('git diff --cached --name-only', projectPath)
-    );
+  constructor(traceRecorder: TraceRecorder = NOOP_TRACE_RECORDER) {
+    this.traceRecorder = traceRecorder;
   }
 
   /**
-   * 获取单例实例
+   * 获取单例实例（未接线记录器的默认实例：不写 trace）
    */
   static getInstance(): ConstraintChecker {
     if (!ConstraintChecker.instance) {
@@ -109,13 +65,6 @@ export class ConstraintChecker {
     return ConstraintChecker.instance;
   }
 
-  /**
-   * 注入 trace 记录器（测试/定制场景；不调用则首次记录时惰性接线全局收集器）
-   */
-  setTraceRecorder(recorder: TraceRecorder): void {
-    this.traceRecorder = recorder;
-  }
-
   /**
    * 获取当前的约束集合（内置 + 自定义）
    *
@@ -143,10 +92,13 @@ export class ConstraintChecker {
 
   /**
    * 检查单个约束
+   *
+   * @param evidence 可选，本 run 的 git 证据实例（#87）；不传 = 本次调用独占一份真 git 证据
    */
   async check(
     constraint: Constraint,
-    context: ConstraintContext
+    context: ConstraintContext,
+    evidence?: GitEvidence
   ): Promise<ConstraintResult> {
     // prompt 类约束不参与 checker 执行（ADR-0001：仅参与注入）
     if (constraint.kind === 'prompt') {
@@ -160,9 +112,11 @@ export class ConstraintChecker {
     }
 
     // 检查前置条件（'skip' = 约定未采用/证据未接线：satisfied 置 true 但不计 pass/fail）
-    const outcome = await this.checkPrecondition(constraint, context);
+    const outcome = normalizeCheckOutcome(
+      await this.checkPrecondition(constraint, context, evidence)
+    );
 
-    if (outcome === 'skip') {
+    if (outcome.skipped) {
       return {
         id: constraint.id,
         level: constraint.level,
@@ -174,7 +128,7 @@ export class ConstraintChecker {
       };
     }
 
-    const satisfied = outcome;
+    const satisfied = outcome.satisfied;
 
     return {
       id: constraint.id,
@@ -182,6 +136,7 @@ export class ConstraintChecker {
       satisfied,
       constraint,
       message: satisfied ? undefined : constraint.message,
+      evidence: outcome.evidence.length > 0 ? outcome.evidence : undefined,
       requiredAction: satisfied ? undefined : constraint.enforcement,
       checkedAt: new Date(),
     };
@@ -203,28 +158,15 @@ export class ConstraintChecker {
     }
   }
 
-  /**
-   * 判断约束是否匹配当前触发条件
-   *
-   * context.operation 为主触发条件，context.extraTriggers 为次级推断
-   * （ADR-0001：pre-commit 代码变更附加 code_implementation），任一命中即匹配。
-   */
-  private matchesTrigger(constraint: Constraint, context: ConstraintContext): boolean {
-    const triggers = normalizeTriggers<ConstraintTrigger>(constraint.trigger);
-    const operations = [context.operation, ...(context.extraTriggers ?? [])];
-    return operations.some(op => triggers.includes(op));
-  }
-
   /**
    * 记录约束检查的 trace
    */
   private recordTrace(
-    collector: TraceRecorder,
     constraint: Constraint,
     checkResult: ConstraintResult,
     context: ConstraintContext
   ): void {
-    collector.record({
+    this.traceRecorder.record({
       constraintId: constraint.id,
       level: constraint.level,
       timestamp: Date.now(),
@@ -233,6 +175,7 @@ export class ConstraintChecker {
       severity: this.getSeverity(constraint.level),
       projectPath: context.projectPath,
       sessionId: context.sessionId,
+      evidence: checkResult.evidence,
     });
   }
 
@@ -241,10 +184,14 @@ export class ConstraintChecker {
    *
    * 注册表闭环（ADR-0001）：kind='check' 未注册 checker 直接抛错，
    * 不再有"未注册默认通过"路径；kind='prompt' 在 check() 入口已短路。
+   *
+   * git 证据（stagedDiff/stagedDiffNames）单一来源 = GitEvidence adapter（#87）：
+   * 一次 run 内调用方传同一实例即至多取证一次，run 外调用独占一份。
    */
   private async checkPrecondition(
     constraint: Constraint,
-    context: ConstraintContext
+    context: ConstraintContext,
+    evidence?: GitEvidence
   ): Promise<CheckOutcome> {
     const impl = getConstraintCheck(constraint.id);
     if (!impl) {
@@ -255,9 +202,10 @@ export class ConstraintChecker {
     }
 
     const projectPath = context.projectPath || process.cwd();
+    const git = evidence ?? createGitEvidence(projectPath);
     const env = buildCheckEnv(context, {
-      stagedDiff: () => this.getStagedDiff(projectPath),
-      stagedDiffNames: () => this.getStagedDiffNames(projectPath),
+      stagedDiff: async () => git.stagedDiff(),
+      stagedDiffNames: async () => git.changedFileNames(true),
       srcScan: (root: string) =>
         this.cache.getSync(`src_scan_${root}`, projectPath, () =>
           findTsSourceFiles(join(projectPath, root), { skipIndex: true }).map((f) =>
@@ -287,12 +235,9 @@ export class ConstraintChecker {
     const constraints = this.getConstraints(customConfig);
 
     const filterByTrigger = (constraintSet: Record<string, Constraint>): Constraint[] => {
-      return Object.values(constraintSet).filter(constraint => {
-        const triggers = Array.isArray(constraint.trigger)
-          ? constraint.trigger
-          : [constraint.trigger];
-        return operations.some(op => triggers.includes(op));
-      });
+      return Object.values(constraintSet).filter(constraint =>
+        matchesTrigger(constraint, operations)
+      );
     };
 
     return {
@@ -310,57 +255,58 @@ export class ConstraintChecker {
    *
    * @param context 约束上下文
    * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
+   * @param evidence 可选，本 run 的 git 证据 adapter（#87）。调用方（CLI check）与
+   *   buildConstraintContext 传同一实例 → 一次 run 内 git 取证单一来源；
+   *   不传则本 run 自建一份，run 级 memo 照样生效（memo 在实例层，非隐式全局）。
    */
   async checkConstraints(
     context: ConstraintContext,
-    customConfig?: MergedConstraintsConfig | null
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
   ): Promise<ConstraintCheckResult> {
-    // run 起始：重置 run 级缓存；run 结束（含铁律提前抛出）清空（工单 18）
+    // run 起始：重置 src 扫描缓存（S7）；git 证据 = 本 run 独占的 adapter 实例（工单 18 → #87）
     this.cache.invalidate();
-    this.runCache = new Map();
-
-    try {
-      const result: ConstraintCheckResult = {
-        ironLaws: [],
-        guidelines: [],
-        passed: true,
-        warningCount: 0,
-      };
+    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
 
-      const traceCollector = this.getRecorder();
-      const constraints = this.getConstraints(customConfig);
+    const result: ConstraintCheckResult = {
+      ironLaws: [],
+      guidelines: [],
+      passed: true,
+      warningCount: 0,
+    };
 
-      // 1. Iron Laws: 必须全部通过
-      for (const constraint of Object.values(constraints.ironLaws)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
+    const constraints = this.getConstraints(customConfig);
+    // context.operation 为主触发条件，extraTriggers 为次级推断（ADR-0001），任一命中即匹配
+    const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
-        const checkResult = await this.check(constraint, context);
-        result.ironLaws.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
+    // 1. Iron Laws: 必须全部通过
+    for (const constraint of Object.values(constraints.ironLaws)) {
+      if (!matchesTrigger(constraint, operations)) continue;
+
+      const checkResult = await this.check(constraint, context, run);
+      result.ironLaws.push(checkResult);
+      this.recordTrace(constraint, checkResult, context);
 
-        if (!checkResult.satisfied) {
-          result.passed = false;
-          throw new ConstraintViolationError(checkResult);
-        }
+      if (!checkResult.satisfied) {
+        result.passed = false;
+        throw new ConstraintViolationError(checkResult);
       }
+    }
 
-      // 2. Guidelines: 记录警告
-      for (const constraint of Object.values(constraints.guidelines)) {
-        if (!this.matchesTrigger(constraint, context)) continue;
+    // 2. Guidelines: 记录警告
+    for (const constraint of Object.values(constraints.guidelines)) {
+      if (!matchesTrigger(constraint, operations)) continue;
 
-        const checkResult = await this.check(constraint, context);
-        result.guidelines.push(checkResult);
-        this.recordTrace(traceCollector, constraint, checkResult, context);
+      const checkResult = await this.check(constraint, context, run);
+      result.guidelines.push(checkResult);
+      this.recordTrace(constraint, checkResult, context);
 
-        if (!checkResult.satisfied) {
-          result.warningCount++;
-        }
+      if (!checkResult.satisfied) {
+        result.warningCount++;
       }
-
-      return result;
-    } finally {
-      this.runCache = null;
     }
+
+    return result;
   }
 
   /**
@@ -368,19 +314,22 @@ export class ConstraintChecker {
    *
    * @param context 约束上下文
    * @param customConfig 可选，per-request 自定义配置（避免多请求间的单例状态污染）
+   * @param evidence 可选，本次检查共用的 git 证据 adapter（#87，同 checkConstraints）
    * @throws ConstraintViolationError 如果有铁律违规
    */
   async beforeExecution(
     context: ConstraintContext,
-    customConfig?: MergedConstraintsConfig | null
+    customConfig?: MergedConstraintsConfig | null,
+    evidence?: GitEvidence
   ): Promise<void> {
+    const run = evidence ?? createGitEvidence(context.projectPath || process.cwd());
     const constraints = this.getConstraints(customConfig);
     const operations = [context.operation, ...(context.extraTriggers ?? [])];
 
     for (const constraint of Object.values(constraints.ironLaws)) {
-      if (!normalizeTriggers(constraint.trigger).some((t) => operations.includes(t))) continue;
+      if (!matchesTrigger(constraint, operations)) continue;
 
-      const result = await this.check(constraint, context);
+      const result = await this.check(constraint, context, run);
       if (!result.satisfied) {
         throw new ConstraintViolationError(result);
       }
@@ -465,5 +414,5 @@ export async function checkBeforeExecution(
   return ConstraintChecker.getInstance().beforeExecution(context, customConfig);
 }
 
-// 导出单例
+// 导出单例（未接线记录器：只评估约束，不写 trace；写 trace 由组合根自行 new）
 export const constraintChecker = ConstraintChecker.getInstance();