@dommaker/harness 1.7.0 → 1.8.0

package/src/gates/command.ts

@@ -5,7 +5,7 @@
  * 检查命令是否安全，防止执行危险操作
  */
 
-import { pass, gateResult } from './types';
+import { gateResult } from './types';
 import type { GateResult, CommandGateConfig, CommandBlacklistRule, Gate, GateContext, GateDecision } from './types';
 import { decisionFromResult } from './decision';
 
@@ -194,6 +194,17 @@ export const DEFAULT_COMMAND_BLACKLIST: CommandBlacklistRule[] = [
   },
 ];
 
+/**
+ * 三投影共用的裁决（模块内类型，不入公共面）
+ */
+interface CommandVerdict {
+  allowed: boolean;
+  blocked: CommandBlacklistRule[];
+  warnings: CommandBlacklistRule[];
+  audits: CommandBlacklistRule[];
+  riskLevel: 'high' | 'medium' | 'low';
+}
+
 /**
  * 命令门禁
  */
@@ -205,17 +216,10 @@ export class CommandGate implements Gate {
 
   constructor(config: Partial<CommandGateConfig> = {}) {
     this.config = {
-      enabled: config.enabled ?? true,
-      strict: config.strict ?? false,
-      customBlacklist: config.customBlacklist ?? [],
       ignoreCategories: config.ignoreCategories ?? [],
     };
 
-    // 合并默认黑名单和自定义黑名单
-    this.blacklist = [
-      ...DEFAULT_COMMAND_BLACKLIST,
-      ...this.config.customBlacklist,
-    ];
+    this.blacklist = [...DEFAULT_COMMAND_BLACKLIST];
   }
 
   /**
@@ -232,40 +236,30 @@ export class CommandGate implements Gate {
   async check(command: string): Promise<GateResult> {
     const startTime = Date.now();
 
-    if (!this.config.enabled) {
-      return pass('command', '命令门禁已禁用', startTime);
-    }
-
-    const result = this.checkBlacklist(command);
+    const verdict = this.judge(command);
 
     return gateResult(
       'command',
-      result.allowed,
-      result.allowed
-        ? this.formatSuccessMessage(result)
-        : this.formatBlockMessage(result),
+      verdict.allowed,
+      verdict.allowed
+        ? this.formatSuccessMessage(verdict)
+        : this.formatBlockMessage(verdict),
       startTime,
       {
-        blocked: result.blocked,
-        warnings: result.warnings,
-        audits: result.audits,
+        blocked: verdict.blocked,
+        warnings: verdict.warnings,
+        audits: verdict.audits,
         command,
       }
     );
   }
 
   /**
-   * 检查黑名单
+   * 唯一匹配谓词（#135）：类别忽略与规则模式测试只在此处发生。
+   * 三个入口一律经 judge() 取它的投影，不再各写一遍匹配循环。
    */
-  private checkBlacklist(command: string): {
-    allowed: boolean;
-    blocked: CommandBlacklistRule[];
-    warnings: CommandBlacklistRule[];
-    audits: CommandBlacklistRule[];
-  } {
-    const blocked: CommandBlacklistRule[] = [];
-    const warnings: CommandBlacklistRule[] = [];
-    const audits: CommandBlacklistRule[] = [];
+  private matchCommand(command: string): CommandBlacklistRule[] {
+    const hits: CommandBlacklistRule[] = [];
 
     for (const rule of this.blacklist) {
       // 跳过忽略的类别
@@ -274,25 +268,36 @@ export class CommandGate implements Gate {
       }
 
       if (rule.pattern.test(command)) {
-        switch (rule.level) {
-          case 'block':
-            blocked.push(rule);
-            break;
-          case 'warn':
-            warnings.push(rule);
-            break;
-          case 'audit':
-            audits.push(rule);
-            break;
-        }
+        hits.push(rule);
       }
     }
 
+    return hits;
+  }
+
+  /**
+   * 命中集合 → 裁决：级别（block/warn/audit）语义只在此处解释一次，
+   * 三投影因此对同一输入不可能互相矛盾。
+   */
+  private judge(command: string): CommandVerdict {
+    const hits = this.matchCommand(command);
+    const blocked = hits.filter(rule => rule.level === 'block');
+    const warnings = hits.filter(rule => rule.level === 'warn');
+    const audits = hits.filter(rule => rule.level === 'audit');
+
+    let riskLevel: 'high' | 'medium' | 'low' = 'low';
+    if (blocked.length > 0) {
+      riskLevel = 'high';
+    } else if (warnings.length > 0) {
+      riskLevel = 'medium';
+    }
+
     return {
       allowed: blocked.length === 0,
       blocked,
       warnings,
       audits,
+      riskLevel,
     };
   }
 
@@ -335,45 +340,17 @@ export class CommandGate implements Gate {
   }
 
   /**
-   * 快速检查（不生成完整 GateResult）
+   * 快速检查（不生成完整 GateResult）——谓词裁决的布尔投影，hook 侧入口
    */
   isAllowed(command: string): boolean {
-    if (!this.config.enabled) return true;
-
-    for (const rule of this.blacklist) {
-      if (this.config.ignoreCategories.includes(rule.category)) {
-        continue;
-      }
-
-      if (rule.level === 'block' && rule.pattern.test(command)) {
-        return false;
-      }
-    }
-
-    return true;
+    return this.judge(command).allowed;
   }
 
   /**
-   * 获取命令风险等级
+   * 获取命令风险等级——谓词裁决的等级投影：命中集合里的最高档
    */
   getRiskLevel(command: string): 'high' | 'medium' | 'low' {
-    if (!this.config.enabled) return 'low';
-
-    for (const rule of this.blacklist) {
-      if (this.config.ignoreCategories.includes(rule.category)) {
-        continue;
-      }
-
-      if (rule.pattern.test(command)) {
-        switch (rule.level) {
-          case 'block': return 'high';
-          case 'warn': return 'medium';
-          case 'audit': return 'low';
-        }
-      }
-    }
-
-    return 'low';
+    return this.judge(command).riskLevel;
   }
 
   /**

package/src/gates/contract.ts

@@ -23,7 +23,6 @@ export class ContractGate implements Gate {
 
   constructor(config: Partial<ContractGateConfig> = {}) {
     this.config = {
-      enabled: config.enabled ?? true,
       strict: config.strict ?? true,
       allowBreakingChanges: config.allowBreakingChanges ?? false,
       contractPath: config.contractPath ?? 'openapi.yaml',
@@ -43,10 +42,6 @@ export class ContractGate implements Gate {
   async check(context: GateContext): Promise<GateResult> {
     const startTime = Date.now();
 
-    if (!this.config.enabled) {
-      return pass('contract', '契约门禁已禁用', startTime);
-    }
-
     try {
       const contractPath = context.newContractPath ?? 
         path.join(context.projectPath, this.config.contractPath);

package/src/gates/definitions.ts

@@ -11,10 +11,12 @@
  *   bareRunsAction:true（无位置参数时跑默认 action 而非显示帮助）。
  * - 本模块禁止 import 任何门禁/命令实现（仅 type import，运行时零依赖）——
  *   bin 启动期只加载本纯数据模块（保持 --help/--version 懒加载，
- *   闭环校验在 registry 加载期执行）。
+ *   闭环校验在 registry 加载期执行）。唯一例外 import：`utils/numeric-flag`
+ *   纯函数解析器（harness#154 口径条目指名的数值旗帜唯一解析器）。
  */
 
 import type { CommandDefinition } from '../cli/commands/definitions';
+import { requireNumericFlag } from '../utils/numeric-flag';
 
 /**
  * 门禁定义
@@ -70,7 +72,6 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         { flags: '-l, --level', description: '显示风险等级' },
         { flags: '--list', description: '列出所有黑名单规则' },
         { flags: '--json', description: 'JSON 格式输出' },
-        { flags: '--strict', description: '严格模式（warn 也阻止）' },
       ],
       action: { module: 'command', export: 'executeCommand' },
       mapActionArgs: (positionals, options) => [positionals[0], options],
@@ -117,9 +118,9 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
         {
           projectPath: options.projectPath,
           coverage: options.coverage,
-          coverageThreshold: parseInt(String(options.coverageThreshold), 10),
+          coverageThreshold: requireNumericFlag('--coverage-threshold', options.coverageThreshold as string | undefined, 'int'),
           bundle: options.bundle,
-          bundleThreshold: parseInt(String(options.bundleThreshold), 10),
+          bundleThreshold: requireNumericFlag('--bundle-threshold', options.bundleThreshold as string | undefined, 'int'),
         },
       ],
     },
@@ -146,7 +147,7 @@ export const GATE_DEFINITIONS: GateDefinition[] = [
       mapActionArgs: (_positionals, options) => [
         {
           projectPath: options.projectPath,
-          minReviewers: parseInt(String(options.minReviewers), 10),
+          minReviewers: requireNumericFlag('--min-reviewers', options.minReviewers as string | undefined, 'int'),
           requireApproval: options.requireApproval,
           blockOnChangesRequested: options.blockOnChanges,
           allowedReviewers: options.allowedReviewers,

package/src/gates/index.ts

@@ -47,11 +47,6 @@ export { getGate, listRegisteredGates, registeredGateCount, assertGateRegistryCl
  */
 export { runGates, type GateRunResult } from './runner';
 
-/**
- * 生效门禁集：config.yml gates.order / gates.<id>.enabled 声明式裁剪
- */
-export { getEffectiveGates, type GatesConfig } from './effective-gates';
-
 /**
  * checker-as-guard 接线点：ConstraintCheck → Gate（studio #129 随动）
  */

package/src/gates/performance.ts

@@ -18,7 +18,7 @@
 import { execAsync } from '../utils/exec';
 import * as fs from 'fs/promises';
 import * as path from 'path';
-import { pass, gateResult, fromError } from './types';
+import { gateResult, fromError } from './types';
 import type { GateResult, GateContext, PerformanceGateConfig, PerformanceThresholds, Gate, GateDecision } from './types';
 import { decisionFromResult } from './decision';
 
@@ -45,7 +45,6 @@ export class PerformanceGate implements Gate {
 
   constructor(config: Partial<ExtendedPerformanceGateConfig> = {}) {
     this.config = {
-      enabled: config.enabled ?? true,
       thresholds: config.thresholds ?? {},
       coverageTimeout: config.coverageTimeout ?? DEFAULT_TIMEOUTS.coverage,
     };
@@ -64,10 +63,6 @@ export class PerformanceGate implements Gate {
   async check(context: GateContext): Promise<GateResult> {
     const startTime = Date.now();
 
-    if (!this.config.enabled) {
-      return pass('performance', '性能门禁已禁用', startTime);
-    }
-
     try {
       const thresholds = context.performanceThresholds ?? this.config.thresholds;
       const metrics = await this.collectMetrics(context.projectPath, thresholds);

package/src/gates/runner.ts

@@ -26,7 +26,7 @@ export interface GateRunResult {
 /**
  * 依次执行门禁链（按 order 升序，稳定排序）
  *
- * @param gates 参与执行的门禁（通常来自 getEffectiveGates）
+ * @param gates 参与执行的门禁（顺序由本函数按 order 排定，调用方不必预排）
  * @param ctx 门禁上下文
  */
 export async function runGates(

package/src/gates/security.ts

@@ -8,7 +8,7 @@
  */
 
 import { execAsync } from '../utils/exec';
-import { pass, gateResult, fromError } from './types';
+import { gateResult, fromError } from './types';
 import type { GateResult, GateContext, SecurityGateConfig, Gate, GateDecision } from './types';
 import { decisionFromResult } from './decision';
 
@@ -18,12 +18,13 @@ import { decisionFromResult } from './decision';
 export class SecurityGate implements Gate {
   readonly id = 'security';
   order = 0;
-  private config: Required<SecurityGateConfig>;
+  private config: SecurityGateConfig;
 
   constructor(config: Partial<SecurityGateConfig> = {}) {
     this.config = {
-      enabled: config.enabled ?? true,
-      scanCommand: config.scanCommand ?? '',
+      // 空串归一为 undefined：`?? ''` 曾把「未提供」表示成空串，令下方 `??` 链恒停在
+      // 第二级、detectScanCommand() 不可达（#138）。「未提供」的唯一表示是 undefined。
+      scanCommand: config.scanCommand || undefined,
       ignoreWarnings: config.ignoreWarnings ?? false,
       ignoreDevDependencies: config.ignoreDevDependencies ?? false,
       severityThreshold: config.severityThreshold ?? 'high',
@@ -43,13 +44,10 @@ export class SecurityGate implements Gate {
   async scan(context: GateContext): Promise<GateResult> {
     const startTime = Date.now();
 
-    if (!this.config.enabled) {
-      return pass('security', '安全门禁已禁用', startTime);
-    }
-
     try {
-      // 使用自定义命令或默认 npm audit
-      const scanCommand = context.securityScanCommand ?? 
+      // 三级优先级（自上而下取第一个「已提供」者）：context 覆盖 > 构造配置 > 自动探测。
+      // 缺省（未给命令）落到 detectScanCommand()——本行曾因构造器兜空串而恒停在第二级（#138）。
+      const scanCommand = context.securityScanCommand ??
         this.config.scanCommand ?? 
         this.detectScanCommand(context.projectPath);
 
@@ -234,7 +232,7 @@ export class SecurityGate implements Gate {
   /**
    * 获取配置
    */
-  getConfig(): Required<SecurityGateConfig> {
+  getConfig(): SecurityGateConfig {
     return { ...this.config };
   }
 }

package/src/gates/types.ts

@@ -2,6 +2,8 @@
  * 门禁类型定义 + GateResult 构造器
  */
 
+import type { RunEnv } from '../core/constraints/run-env';
+
 /**
  * 门禁结果（报告结构，保留）
  *
@@ -115,38 +117,39 @@ export interface Gate {
 }
 
 /**
- * 门禁上下文
+ * 门禁上下文：只带「这次在哪跑、跑什么」这类运行信息
+ *
+ * 配置一律走构造器（`ReviewGateConfig` 等），不要往这里加字段——
+ * 本类型曾有 6 个无人读取的配置型字段与构造器配置平行，填了不生效。
  */
 export interface GateContext {
-  projectId: string;
-  taskId?: string;
   projectPath: string;
-  
+  taskId?: string;
+
   // Review Gate
   prNumber?: number;
-  minReviewers?: number;
-  reviewers?: string[];
-  
+
   // Security Gate
   securityScanCommand?: string;
-  ignoreWarnings?: boolean;
-  
+
   // Performance Gate
   performanceThresholds?: PerformanceThresholds;
-  
+
   // Contract Gate
   oldContractPath?: string;
   newContractPath?: string;
-  openApiSpec?: string;
 
   // Command Gate
   command?: string;
 
   // Acceptance Gate
   tasksPath?: string;
-  
-  // 通用
-  timeout?: number;
+
+  /**
+   * 本 run 的运行级观察面（ADR-0023）。一条守卫链传同一枚 → 项目配置文件整链至多读一次；
+   * 不传 = 各门禁自造一枚一次性观察面（判定不变，只是不共享读取）
+   */
+  runEnv?: RunEnv;
 }
 
 /**
@@ -172,7 +175,6 @@ export interface ReviewGateConfig {
  * 安全门禁配置
  */
 export interface SecurityGateConfig {
-  enabled: boolean;
   scanCommand?: string;
   ignoreWarnings: boolean;
   ignoreDevDependencies: boolean;
@@ -183,7 +185,6 @@ export interface SecurityGateConfig {
  * 性能门禁配置
  */
 export interface PerformanceGateConfig {
-  enabled: boolean;
   thresholds: PerformanceThresholds;
 }
 
@@ -191,7 +192,6 @@ export interface PerformanceGateConfig {
  * 契约门禁配置
  */
 export interface ContractGateConfig {
-  enabled: boolean;
   strict: boolean;
   allowBreakingChanges: boolean;
   contractPath?: string;
@@ -252,14 +252,11 @@ export interface CommandBlacklistRule {
 
 /**
  * 命令门禁配置
+ *
+ * `strict`（从不被判定读取）与 `customBlacklist`（零生产注入者，运行时扩展点是
+ * `CommandGate.addRule()`）两个配置位已删除，裁决见 ADR-0024（#135）。
  */
 export interface CommandGateConfig {
-  /** 是否启用 */
-  enabled?: boolean;
-  /** 严格模式（warn 也阻止） */
-  strict?: boolean;
-  /** 自定义黑名单规则 */
-  customBlacklist?: CommandBlacklistRule[];
   /** 忽略的类别 */
   ignoreCategories?: string[];
 }

package/src/hooks/CONTEXT.md

@@ -5,26 +5,27 @@
 
 H5（#44）起增加两个机制（G2/G7）：
 - **注册表闭环**：`assertHookRegistryClosed(configs, hooks)` 声明（HookConfig）↔ 实现（HookDefinition）双向校验——引用未注册/注册无定义/重复均抛错，复制 checker 闭环模式；断言限构建/测试期，不进运行时热路径
-- **配置归一**：`HookConfig { name, enabled, errorStrategy }` 为 per-hook 配置唯一真相；`toErrorStrategy(blocking)` 承载 studio `blocking` → errorStrategy 的无损映射
+- **配置归一**：`HookConfig { name, enabled, errorStrategy }` 为 per-hook 配置唯一真相，且自 #159 起是 `enabled` / `errorStrategy` 的**唯一声明点**——`HookDefinition` 不再携带这两个字段，注册环节以配置表填充有效值（`EffectiveHook`），声明一处、读取一处，两侧矛盾在构造上不可能出现；`toErrorStrategy(blocking)` 承载 studio `blocking` → errorStrategy 的无损映射
 
 ## 核心导出
-- `HookRegistry` — Hook 注册表（register/get/getEnabled/setEnabled/clear/listAll）
-- `HookPipeline` — Hook 执行管线（注册/排序/错误隔离/采样；errorStrategy block/warn/ignore）
+- `HookRegistry` — Hook 注册表（register/registerAll/unregister/get/getEnabled/listNames/listAll/setEnabled/clear；register 以 HookConfig 填充有效值）
+- `HookPipeline` — Hook 执行管线（注册/排序/错误隔离/采样；errorStrategy block/warn）
 - `assertHookRegistryClosed` — 注册表闭环双向校验（构建/测试期）
-- `HookConfig`（type）— per-hook 配置声明（归一后形状）
+- `HookConfig`（type）— per-hook 配置声明（enabled / errorStrategy 唯一声明点）
+- `EffectiveHook`（type）— HookDefinition + 配置填充的有效 enabled / errorStrategy（管线与注册表判定只读它）
 - `toErrorStrategy` — blocking → errorStrategy 无损映射（G7）
-- `bootstrapHarness` / `bootstrapHarnessSync` — Harness 启动引导；也是 trace 记录器的组合根：`new ConstraintChecker(getTraceCollector())`（harness#88，core 不上行依赖 monitoring，故由本层接线）
+- `bootstrapHarness` / `bootstrapHarnessSync` — Harness 启动引导；也是 trace 记录器的组合根：`new ConstraintChecker(new TraceCollector({ projectPath }))`（harness#88 接线，core 不上行依赖 monitoring，故由本层接线；#139 收根：两个入口本就收 projectPath，落点随之锚定，不再取 cwd 锚定的 `getTraceCollector()` 单例）
 
 ## 依赖关系
-- 依赖 `src/types/` Hook 相关类型
-- 被 `src/core/` 核心引擎消费
-- 被 CLI 初始化流程消费
+- 类型正本在**本模块** `src/hooks/types.ts`（`HookPhase`/`HookErrorStrategy`/`HookConfig`/`HookDefinition`/`EffectiveHook`/`HookResult`/`PipelineResult`）；`src/types/` 里没有 hook 类型，本层只从 `src/types/project-config` 取 `MergedConstraintsConfig` 类型
+- 向下依赖（仅 `bootstrap.ts` 组合根）：`core/constraints/checker`、`core/project-config-loader`、`context/session-manager`、`monitoring/traces`——`registry/pipeline/config/types` 四文件零上层依赖，是纯管线
+- 消费方：包根 `src/index.ts` 的 `./hooks` 出口与下游项目（studio 的 hook 装配）。**harness 内部无生产消费方**——core/cli 侧的调用边已随零消费者清账删除（harness#141 同判据，ADR-0022），「被 core 核心引擎/CLI 初始化流程消费」的旧说法已失效（harness#142 核对）
 
 ## 约定
 - 无业务逻辑，只提供管线能力
 - Consumer 自行定义 hook 名称和触发时机
 - **闭环**：声明配置与注册实现必须一一对应，缺一抛错（消灭「hook 定义不注册 = 死代码」类人记规矩）
-- **映射语义**：blocking=true → 'block'（失败阻断管线，停止后续 hook、passed=false）；blocking=false → 'warn'（记录警告继续）；未声明 strategy 静默跳过（历史行为保留）
+- **映射语义**：blocking=true → 'block'（失败阻断管线，停止后续 hook、passed=false）；blocking=false → 'warn'（记录警告继续）；有效策略集合仅 'block' | 'warn'（#159 起原 'ignore' 与「未声明 strategy」形态退出有效面——策略由 HookConfig 必填声明）
 - 错误隔离：单个 hook 失败不影响其他 hook
 
 ## 注意事项

package/src/hooks/__tests__/bootstrap.test.ts

@@ -11,7 +11,11 @@ import * as fs from 'fs';
 import * as path from 'path';
 import * as yaml from 'js-yaml';
 import { bootstrapHarnessSync, bootstrapHarness } from '../bootstrap';
-import type { HookDefinition } from '../types';
+import type { HookConfig, HookDefinition } from '../types';
+
+function makeHookConfig(name: string, overrides: Partial<HookConfig> = {}): HookConfig {
+  return { name, enabled: true, errorStrategy: 'warn', ...overrides };
+}
 
 function setupTempDir(dir: string): string {
   const harnessDir = path.join(dir, '.harness');
@@ -51,14 +55,24 @@ describe('bootstrapHarness', () => {
     expect(result.projectPath).toBe(tempDir);
   });
 
-  it('registers hook definitions when provided', async () => {
+  it('registers hook definitions when provided (with configs)', async () => {
     const hookDef: HookDefinition = {
       name: 'async-hook',
       phase: 'before',
       execute: async () => ({ passed: true }),
     };
-    const result = await bootstrapHarness(tempDir, [hookDef]);
+    const result = await bootstrapHarness(tempDir, [hookDef], [makeHookConfig('async-hook')]);
     expect(result.hooks.listNames()).toContain('async-hook');
+    expect(result.hooks.get('async-hook')?.errorStrategy).toBe('warn');
+  });
+
+  it('throws when definitions are provided without configs (#159)', async () => {
+    const hookDef: HookDefinition = {
+      name: 'async-hook',
+      phase: 'before',
+      execute: async () => ({ passed: true }),
+    };
+    await expect(bootstrapHarness(tempDir, [hookDef])).rejects.toThrow(/HookConfig/);
   });
 
   it('does not register hooks when no definitions provided', async () => {
@@ -126,16 +140,25 @@ describe('bootstrapHarnessSync', () => {
     expect(result.mergedConstraints).toHaveProperty('guidelines');
   });
 
-  it('registers hook definitions when provided', () => {
+  it('registers hook definitions when provided (with configs)', () => {
     const hookDef: HookDefinition = {
       name: 'test-hook',
       phase: 'before',
       execute: async () => ({ passed: true }),
     };
-    const result = bootstrapHarnessSync(tempDir, [hookDef]);
+    const result = bootstrapHarnessSync(tempDir, [hookDef], [makeHookConfig('test-hook')]);
     expect(result.hooks.listNames()).toContain('test-hook');
   });
 
+  it('throws when definitions are provided without configs (#159)', () => {
+    const hookDef: HookDefinition = {
+      name: 'test-hook',
+      phase: 'before',
+      execute: async () => ({ passed: true }),
+    };
+    expect(() => bootstrapHarnessSync(tempDir, [hookDef])).toThrow(/HookConfig/);
+  });
+
   it('does not register hooks when no definitions provided', () => {
     const result = bootstrapHarnessSync(tempDir, []);
     expect(result.hooks.listNames()).toEqual([]);
@@ -165,7 +188,7 @@ describe('bootstrapHarnessSync', () => {
       phase: 'after',
       execute: async () => ({ passed: true, data: 'ok' }),
     };
-    const result = bootstrapHarnessSync(tempDir, [hookDef]);
+    const result = bootstrapHarnessSync(tempDir, [hookDef], [makeHookConfig('pipeline-hook')]);
     expect(result.pipeline).toBeDefined();
   });