@dommaker/harness 1.11.0 → 1.12.0

package/src/core/constraints/checkers/__tests__/templates-registry.test.ts

@@ -0,0 +1,81 @@
+/**
+ * 两层注册表闭环校验扩展（ADR-0033 块 3 子项 1）测试
+ *
+ * - getConstraintCheck：字符串 id / 内置约束走内置注册表（现状不动）；
+ *   source='app' 按模板 id + params 实例化；模板 id 未注册 → 抛错（闭环保留）
+ * - 内置对账闭环不动：每条 kind=check 内置约束有 checker、无孤儿实现
+ *   （既有断言在 src/__tests__/iron-laws.test.ts，此处只补应用层维度）
+ */
+
+import { describe, it, expect, afterEach } from '@jest/globals';
+import {
+  getConstraintCheck,
+  TEMPLATES,
+  type ConstraintCheck,
+  type TemplatedCheckerFactory,
+} from '../index';
+import type { Constraint } from '../../../../types/constraint';
+
+const FAKE_PARAMS = { p: 1 };
+
+const fakeFactory: TemplatedCheckerFactory = {
+  validateParams: () => [],
+  create: (id, params) => ({
+    id,
+    evaluate: () => ({ pass: params === FAKE_PARAMS || params.p === 1 }),
+  }),
+};
+
+function appConstraint(overrides: Partial<Constraint> = {}): Constraint {
+  return {
+    id: 'app_fake',
+    kind: 'check',
+    rule: 'r',
+    message: 'm',
+    severity: 'warning',
+    trigger: 'commit',
+    enforcement: '',
+    source: 'app',
+    checker: 'fake-template',
+    params: FAKE_PARAMS,
+    ...overrides,
+  };
+}
+
+afterEach(() => {
+  TEMPLATES.delete('fake-template');
+});
+
+describe('getConstraintCheck 两层分发', () => {
+  it('字符串 id 走内置注册表（现状口径：未注册返回 undefined）', () => {
+    expect(getConstraintCheck('capability_sync')).toBeDefined();
+    expect(getConstraintCheck('removed_legacy')).toBeUndefined();
+  });
+
+  it('内置约束对象按 id 查找（source 缺省 = builtin）', () => {
+    const builtin: Constraint = {
+      id: 'capability_sync',
+      kind: 'check',
+      rule: 'r',
+      message: 'm',
+      severity: 'warning',
+      trigger: 'module_modification',
+      enforcement: 'update-capabilities',
+    };
+    expect(getConstraintCheck(builtin)?.id).toBe('capability_sync');
+  });
+
+  it('source=app：按模板 id + params 实例化 checker', () => {
+    TEMPLATES.set('fake-template', fakeFactory);
+    const check = getConstraintCheck(appConstraint()) as ConstraintCheck;
+    expect(check.id).toBe('app_fake');
+  });
+
+  it('source=app 模板未注册 → 抛错（闭环保留，不许静默 pass）', () => {
+    expect(() => getConstraintCheck(appConstraint())).toThrow(/未注册/);
+  });
+
+  it('source=app 缺 checker 字段 → 抛错', () => {
+    expect(() => getConstraintCheck(appConstraint({ checker: undefined }))).toThrow(/闭环校验失败/);
+  });
+});

package/src/core/constraints/checkers/index.ts

@@ -1,13 +1,19 @@
 /**
- * 约束检查器注册表（工单 21）
+ * 约束检查器注册表（工单 21；ADR-0033 拆两层）
  *
- * checker.ts 编排层通过 getConstraintCheck(id) 查找实现。
+ * checker.ts 编排层通过 getConstraintCheck() 查找实现。
  *
- * 注册表闭环（ADR-0001）：模块加载时校验全部 kind='check' 的内置约束
- * 都有已注册 checker，且注册表中没有无对应 check 定义的孤儿实现；
- * 任一不满足即抛错（加载期失败，不许静默 pass）。
+ * 两层注册表：
+ * - 内置 checker（registry，按约束 id）：模块加载时校验全部 kind='check' 的内置约束
+ *   都有已注册 checker，且注册表中没有无对应 check 定义的孤儿实现；
+ *   任一不满足即抛错（加载期失败，不许静默 pass，ADR-0001）。
+ * - 模板 checker（TEMPLATES，按模板 id）：填空式参数化模板，供应用层约束
+ *   （source='app'，`.harness/constraints.yml`）按 checker + params 实例化。
+ *   闭环语义扩展而非开口：应用层约束在加载期（app-constraints-loader）校验
+ *   模板 id 存在 + validateParams 通过；getConstraintCheck 对未注册模板 id 抛错。
  */
 
+import type { Constraint } from '../../../types/constraint';
 import type { ConstraintCheck } from './types';
 import { getAllConstraints } from '../definitions';
 
@@ -20,14 +26,15 @@ import { contextDocSync } from './context-doc-sync';
 import { docsFreshness } from './docs-freshness';
 import { noHardcodedCredentials } from './no-hardcoded-credentials';
 import { governancePresence } from './governance-presence';
+import { TEMPLATES } from './templates-registry';
 
 const CHECKS: ConstraintCheck[] = [
   // severity='error'
   noCompletionWithoutVerification,
   noTestSimplification,
   docsFreshness,
-  // severity='warning'
   noHardcodedCredentials,
+  // severity='warning'
   capabilitySync,
   contextDocSync,
   governancePresence,
@@ -35,6 +42,14 @@ const CHECKS: ConstraintCheck[] = [
 
 const registry = new Map<string, ConstraintCheck>(CHECKS.map(c => [c.id, c]));
 
+// ========================================
+// 模板注册表（ADR-0033，应用层约束用）
+// ========================================
+
+// TEMPLATES 住在 ./templates-registry（独立模块防值级循环，见该文件头注释）；
+// 此处 re-export 供编排层与测试单口取数
+export { TEMPLATES } from './templates-registry';
+
 // ========================================
 // 注册表闭环校验（加载期）
 // ========================================
@@ -60,11 +75,29 @@ for (const id of registry.keys()) {
 }
 
 /**
- * 按约束 ID 查找检查实现；未注册返回 undefined
- * （编排层对 kind='check' 未注册的情况抛错）
+ * 查找检查实现
+ *
+ * - 传字符串 id 或内置约束：按 id 查内置注册表，未注册返回 undefined
+ *   （编排层对 kind='check' 未注册的情况抛错）
+ * - 传 source='app' 的约束：按 checker 模板 id + params 实例化；
+ *   模板 id 未注册 → 抛错（闭环保留，不许静默 pass）
  */
-export function getConstraintCheck(id: string): ConstraintCheck | undefined {
-  return registry.get(id);
+export function getConstraintCheck(idOrConstraint: string | Constraint): ConstraintCheck | undefined {
+  if (typeof idOrConstraint === 'string') {
+    return registry.get(idOrConstraint);
+  }
+  if (idOrConstraint.source === 'app') {
+    const templateId = idOrConstraint.checker;
+    const factory = templateId ? TEMPLATES.get(templateId) : undefined;
+    if (!factory) {
+      throw new Error(
+        `[harness] 约束注册表闭环校验失败：应用层约束 "${idOrConstraint.id}" 引用的 checker 模板 ` +
+        `"${templateId ?? '（未填写）'}" 未注册。请在 checkers/templated/ 中实现并注册。`
+      );
+    }
+    return factory.create(idOrConstraint.id, idOrConstraint.params ?? {});
+  }
+  return registry.get(idOrConstraint.id);
 }
 
 /**
@@ -77,6 +110,7 @@ export function registeredCheckCount(): number {
 export { buildCheckEnv, normalizeCheckOutcome } from './types';
 export type {
   ConstraintCheck,
+  TemplatedCheckerFactory,
   CheckEnv,
   CheckOutcome,
   CheckDetail,

package/src/core/constraints/checkers/templated/file-exists.ts

@@ -0,0 +1,75 @@
+/**
+ * file-exists 模板：文件存在性约束（ADR-0033，块 3 子项 2）
+ *
+ * 形态参照 context-doc-sync：存在性判定 + 证据行（fail 必须可归因，harness#119）。
+ * 与 context-doc-sync 的差别：目标由参数显式给出（加载期已校验），
+ * 无「约定未采用」三态，故永不 skip。
+ *
+ * 参数：
+ * - path（可选）：相对项目根的单文件路径
+ * - glob（可选）：文件集 glob（fast-glob 口径，dot: true 以覆盖 .harness 等点目录）
+ * - mustExist（可选，缺省 true）：true = 必须存在；false = 必须不存在
+ * path 与 glob 至少填一个；都填 = 两者都要满足。
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+import * as glob from 'fast-glob';
+import { formatEvidence, type ConstraintCheck, type TemplatedCheckerFactory } from '../types';
+
+export const fileExists: TemplatedCheckerFactory = {
+  validateParams(params) {
+    const errors: string[] = [];
+    if (params.path !== undefined && typeof params.path !== 'string') {
+      errors.push('path 必须是字符串');
+    }
+    if (params.glob !== undefined && typeof params.glob !== 'string') {
+      errors.push('glob 必须是字符串');
+    }
+    const hasPath = typeof params.path === 'string' && params.path.length > 0;
+    const hasGlob = typeof params.glob === 'string' && params.glob.length > 0;
+    if (!hasPath && !hasGlob) {
+      errors.push('path 或 glob 至少填一个');
+    }
+    if (params.mustExist !== undefined && typeof params.mustExist !== 'boolean') {
+      errors.push('mustExist 必须是布尔值');
+    }
+    return errors;
+  },
+
+  create(id, params): ConstraintCheck {
+    const rel = params.path as string | undefined;
+    const globPattern = params.glob as string | undefined;
+    const mustExist = params.mustExist !== false;
+
+    return {
+      id,
+      evaluate(env) {
+        const pathHit = rel !== undefined && existsSync(join(env.projectPath, rel));
+        const globHits = globPattern !== undefined
+          ? glob.sync(globPattern, { cwd: env.projectPath, dot: true, onlyFiles: false })
+          : [];
+
+        if (mustExist) {
+          const missing: string[] = [];
+          if (rel !== undefined && !pathHit) missing.push(rel);
+          if (globPattern !== undefined && globHits.length === 0) missing.push(`${globPattern}（无匹配文件）`);
+          if (missing.length > 0) {
+            return { pass: false, evidence: formatEvidence('必需文件不存在', missing) };
+          }
+          return true;
+        }
+
+        // mustExist=false：任何目标存在即违规
+        const present: string[] = [
+          ...(pathHit ? [rel!] : []),
+          ...globHits,
+        ];
+        if (present.length > 0) {
+          return { pass: false, evidence: formatEvidence('禁存文件存在', present) };
+        }
+        return true;
+      },
+    };
+  },
+};

package/src/core/constraints/checkers/templated/glob.ts

@@ -0,0 +1,46 @@
+/**
+ * 模板侧轻量 glob 匹配（支持 `**`、`*`、`?`，纯字符串判定，不碰文件系统）
+ *
+ * 与 completion-checkers/glob-match 同一匹配语义；此处另写一份是因为分层
+ * （harness#88 参数化守卫）不许 core 值导入同层领域模块——约束域的模板
+ * 参数匹配不住 completion-checkers 的 commits 分类模块。
+ */
+
+function escapeRegExp(s: string): string {
+  return s.replace(/[.+^${}()|[\]\\]/g, '\\$&');
+}
+
+/** glob → 锚定正则。前缀 `**` + `/` 匹配零或多段路径；`*` 不跨 `/`；`?` 匹配单个非 `/` 字符 */
+function globToRegExp(glob: string): RegExp {
+  let re = '';
+  let i = 0;
+  while (i < glob.length) {
+    const c = glob[i];
+    if (c === '*') {
+      if (glob[i + 1] === '*') {
+        if (glob[i + 2] === '/') {
+          re += '(?:[^/]+/)*';
+          i += 3;
+        } else {
+          re += '.*';
+          i += 2;
+        }
+      } else {
+        re += '[^/]*';
+        i += 1;
+      }
+    } else if (c === '?') {
+      re += '[^/]';
+      i += 1;
+    } else {
+      re += escapeRegExp(c);
+      i += 1;
+    }
+  }
+  return new RegExp('^' + re + '$');
+}
+
+/** 单 glob 匹配（相对路径正斜杠口径） */
+export function matchGlob(file: string, glob: string): boolean {
+  return globToRegExp(glob).test(file);
+}

package/src/core/constraints/checkers/templated/index.ts

@@ -0,0 +1,12 @@
+/**
+ * 填空式 checker 模板（ADR-0033 两层约束模型，块 3 子项 2）
+ *
+ * 每个模板 = TemplatedCheckerFactory（validateParams + create），注册进
+ * checkers/index.ts 的 TEMPLATES 供应用层约束（`.harness/constraints.yml`）
+ * 按 checker + params 实例化。
+ *
+ * 模板只认参数不认应用语义（harness 零业务逻辑）：约束条文、文案归应用仓。
+ */
+
+export { regexScan } from './regex-scan';
+export { fileExists } from './file-exists';

package/src/core/constraints/checkers/templated/regex-scan.ts

@@ -0,0 +1,132 @@
+/**
+ * regex-scan 模板：正则扫描约束（ADR-0033，块 3 子项 2）
+ *
+ * 形态参照 no-hardcoded-credentials：scope='diff'（缺省）扫 staged diff 新增行，
+ * diff 为空/不可用时退化为变更文件内容扫描；scope='content' 直接扫变更文件内容。
+ * 命中即违规，证据行点名文件与命中行（harness#119：fail 必须可归因）。
+ *
+ * 参数：
+ * - pattern（必填）：正则字符串
+ * - glob（可选）：限定文件集（相对路径，支持 `**`/`*`/`?`）
+ * - scope（可选）：'diff' | 'content'，缺省 'diff'
+ */
+
+import { readFileSync } from 'fs';
+import { join } from 'path';
+import { formatEvidence, type CheckDetail, type CheckEnv, type ConstraintCheck, type TemplatedCheckerFactory } from '../types';
+import { matchGlob } from './glob';
+
+/** 证据行单行长度上限（命中行可能是整行配置/长文本） */
+const MAX_LINE = 120;
+
+interface AddedLine {
+  file: string;
+  line: string;
+}
+
+/** 从 unified diff 中取新增行（按 +++ b/<path> 归属文件，glob 过滤文件集） */
+function collectAddedLines(diff: string, inScope: (file: string) => boolean): AddedLine[] {
+  const out: AddedLine[] = [];
+  let file = '';
+  for (const raw of diff.split('\n')) {
+    if (raw.startsWith('+++ b/')) {
+      file = raw.slice('+++ b/'.length);
+      continue;
+    }
+    if (raw.startsWith('+++') || raw.startsWith('diff --git')) {
+      if (raw.startsWith('diff --git')) file = '';
+      continue;
+    }
+    if (raw.startsWith('+') && file && inScope(file)) {
+      out.push({ file, line: raw.slice(1) });
+    }
+  }
+  return out;
+}
+
+function hitEvidence(pattern: RegExp, hits: string[]): CheckDetail {
+  return {
+    pass: false,
+    evidence: formatEvidence(`命中禁用模式 /${pattern.source}/`, hits),
+  };
+}
+
+function clip(line: string): string {
+  const t = line.trim();
+  return t.length > MAX_LINE ? `${t.slice(0, MAX_LINE)}…` : t;
+}
+
+export const regexScan: TemplatedCheckerFactory = {
+  validateParams(params) {
+    const errors: string[] = [];
+    const pattern = params.pattern;
+    if (typeof pattern !== 'string' || pattern.length === 0) {
+      errors.push('pattern 必填（正则字符串）');
+    } else {
+      try {
+        new RegExp(pattern);
+      } catch (err) {
+        errors.push(`pattern 不是合法正则：${err instanceof Error ? err.message : String(err)}`);
+      }
+    }
+    if (params.glob !== undefined && typeof params.glob !== 'string') {
+      errors.push('glob 必须是字符串');
+    }
+    if (params.scope !== undefined && params.scope !== 'diff' && params.scope !== 'content') {
+      errors.push("scope 必须是 'diff' 或 'content'");
+    }
+    return errors;
+  },
+
+  create(id, params): ConstraintCheck {
+    const pattern = new RegExp(params.pattern as string);
+    const glob = params.glob as string | undefined;
+    const scope = (params.scope as 'diff' | 'content' | undefined) ?? 'diff';
+    const inScope = (file: string) => !glob || matchGlob(file, glob);
+
+    const scanChangedFiles = (env: CheckEnv): string[] => {
+      const hits: string[] = [];
+      for (const file of (env.context.changedFiles ?? []).filter(inScope)) {
+        let content: string;
+        try {
+          content = readFileSync(join(env.projectPath, file), 'utf-8');
+        } catch {
+          continue; // 文件不可读（已删除/二进制）→ 跳过
+        }
+        for (const line of content.split('\n')) {
+          if (pattern.test(line)) hits.push(`${file}: ${clip(line)}`);
+        }
+      }
+      return hits;
+    };
+
+    return {
+      id,
+      async evaluate(env) {
+        if (scope === 'content') {
+          const hits = scanChangedFiles(env);
+          return hits.length > 0 ? hitEvidence(pattern, hits) : true;
+        }
+
+        // scope='diff'：staged diff 新增行；diff 为空/不可用 → 退化变更文件内容扫描
+        let scanned = false;
+        try {
+          const diff = await env.stagedDiff();
+          const added = collectAddedLines(diff, inScope);
+          if (added.length > 0) {
+            scanned = true;
+            const hits = added.filter(a => pattern.test(a.line)).map(a => `${a.file}: ${clip(a.line)}`);
+            if (hits.length > 0) return hitEvidence(pattern, hits);
+          }
+        } catch {
+          // diff 不可用 → 退化为文件内容扫描
+        }
+        if (!scanned) {
+          const hits = scanChangedFiles(env);
+          if (hits.length > 0) return hitEvidence(pattern, hits);
+        }
+        return true;
+      },
+    };
+  },
+};

package/src/core/constraints/checkers/templates-registry.ts

@@ -0,0 +1,22 @@
+/**
+ * 填空式 checker 模板注册表（ADR-0033 两层约束模型）
+ *
+ * 独立成模块而非住在 checkers/index.ts：应用层加载器（core/app-constraints-loader）
+ * 要做加载期模板校验，若直接引 checkers/index.ts 会经 project-config-loader →
+ * 本注册表 → 内置 checker → project-config-loader 形成值级循环（checker 初始化时
+ * 拿到 undefined）。本模块不引内置 checker，无环。
+ *
+ * 闭环语义：模板 id 未注册即不可用——加载期由 app-constraints-loader 校验，
+ * 运行期由 checkers/index.ts 的 getConstraintCheck 抛错兜底。
+ *
+ * 首批模板：regex-scan（正则扫描）/ file-exists（文件存在性），块 3 子项 2。
+ */
+
+import type { TemplatedCheckerFactory } from './types';
+import { regexScan, fileExists } from './templated';
+
+/** 模板注册表（模板 id → 工厂）；测试可注册替身模板，用后须注销 */
+export const TEMPLATES = new Map<string, TemplatedCheckerFactory>([
+  ['regex-scan', regexScan],
+  ['file-exists', fileExists],
+]);

package/src/core/constraints/checkers/types.ts

@@ -148,6 +148,21 @@ export interface ConstraintCheck {
   evaluate(env: CheckEnv): Promise<CheckOutcome> | CheckOutcome;
 }
 
+/**
+ * 填空式 checker 模板工厂（ADR-0033 两层约束模型）
+ *
+ * 每个模板 = validateParams + create：参数坏在加载期早报（validateParams），
+ * create 只在参数已校验后调用。注册点 = checkers/index.ts 的 TEMPLATES。
+ * 类型住在 types.ts（而非 index.ts）是为了模板实现文件只依赖本模块，
+ * 不与注册表形成值级循环导入。
+ */
+export interface TemplatedCheckerFactory {
+  /** 参数校验：返回错误清单，空数组 = 通过（加载期跑，参数坏早报） */
+  validateParams(params: Record<string, unknown>): string[];
+  /** 按约束 id + 已校验参数实例化 checker */
+  create(id: string, params: Record<string, unknown>): ConstraintCheck;
+}
+
 /**
  * 构造纯上下文标志检查（无 I/O 的轻量约束）
  */

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

@@ -10,21 +10,6 @@
 import type { Constraint } from '../../../types/constraint';
 
 export const WARNING_CONSTRAINTS: Record<string, Constraint> = {
-  /**
-   * 禁止硬编码凭证
-   * 原因：密码/token/密钥泄露是最严重的安全漏洞，一旦提交到版本控制即不可逆
-   */
-  no_hardcoded_credentials: {
-    id: 'no_hardcoded_credentials',
-    kind: 'check',
-    rule: 'NO HARDCODED PASSWORDS, TOKENS, SECRETS, OR CREDENTIALS IN ANY SOURCE FILE',
-    message: '禁止在代码/文档/配置文件中硬编码密码、token、密钥、API key',
-    severity: 'warning',
-    trigger: ['code_implementation', 'doc_update', 'config_change', 'commit'],
-    enforcement: 'credential-scan',
-    description: `凭证（密码/token/密钥/API key）必须从环境变量或加密配置读取，严禁以明文形式出现在任何源代码文件中。包括但不限于：源码、Markdown 文档、YAML/JSON 配置、脚本文件。模板文件（.example/.sample/.template）允许占位符但不得包含真实值。建议配合 pre-commit hook 做自动扫描。`,
-  },
-
   /**
    * 功能清单同步
    * 例外：内部重构、bug fix

package/src/core/constraints/definitions/iron-laws.ts

@@ -25,6 +25,22 @@ export const ERROR_CONSTRAINTS: Record<string, Constraint> = {
     description: '在声明任何任务完成之前，必须运行新鲜的验证命令（项目声明的测试 + type check），以新鲜输出作为完成证据。验证命令集由项目自行声明，全量验证留给 CI 流程。',
   },
 
+  /**
+   * 禁止硬编码凭证
+   * 原因：密码/token/密钥泄露是最严重的安全漏洞，一旦提交到版本控制即不可逆。
+   * ADR-0032：安全底线类约束，warning 不阻断等于没有——升级为 error（违规即阻断）。
+   */
+  no_hardcoded_credentials: {
+    id: 'no_hardcoded_credentials',
+    kind: 'check',
+    rule: 'NO HARDCODED PASSWORDS, TOKENS, SECRETS, OR CREDENTIALS IN ANY SOURCE FILE',
+    message: '禁止在代码/文档/配置文件中硬编码密码、token、密钥、API key',
+    severity: 'error',
+    trigger: ['code_implementation', 'doc_update', 'config_change', 'commit'],
+    enforcement: 'credential-scan',
+    description: `凭证（密码/token/密钥/API key）必须从环境变量或加密配置读取，严禁以明文形式出现在任何源代码文件中。包括但不限于：源码、Markdown 文档、YAML/JSON 配置、脚本文件。模板文件（.example/.sample/.template）允许占位符但不得包含真实值。建议配合 pre-commit hook 做自动扫描。`,
+  },
+
   /**
    * 禁止简化测试
    * 原因：质量底线，测试困难必须解决