@principles/pd-cli 1.133.0 → 1.135.0

package/tests/bdd/support/gherkin-loader.ts

@@ -0,0 +1,147 @@
+import { AstBuilder, GherkinClassicTokenMatcher, Parser } from '@cucumber/gherkin';
+import * as messages from '@cucumber/messages';
+
+export interface ParsedStep {
+  keyword: 'Given' | 'When' | 'Then' | 'And' | 'But';
+  text: string;
+}
+
+export interface ParsedScenario {
+  featureName: string;
+  featureTags: string[];
+  scenarioName: string;
+  scenarioTags: string[];
+  background?: ParsedStep[];
+  steps: ParsedStep[];
+}
+
+// 步骤关键词归一化表。英文关键词由 @cucumber/gherkin 以带尾空格的形式返回
+// (如 "Given "),中文关键词无尾空格 (如 "假如")。trim 后用此表映射到规范形式。
+// 中文条目用于带 # language: zh-CN 指令的文件 (parser 原生返回中文关键词)。
+const KEYWORD_MAP: Record<string, ParsedStep['keyword']> = {
+  Given: 'Given',
+  When: 'When',
+  Then: 'Then',
+  And: 'And',
+  But: 'But',
+  // 中文关键词 (@cucumber/gherkin zh-CN 方言)
+  假如: 'Given',
+  假设: 'Given',
+  假定: 'Given',
+  当: 'When',
+  那么: 'Then',
+  而且: 'And',
+  并且: 'And',
+  同时: 'And',
+  但是: 'But',
+};
+
+function normalizeKeyword(keyword: string): ParsedStep['keyword'] {
+  const trimmed = keyword.trim();
+  const mapped = KEYWORD_MAP[trimmed];
+  if (!mapped) {
+    // rc-9: 不静默回退到 'Given'，未知关键词 fail loud。
+    // @cucumber/gherkin parser 理论上只产生已知关键词，这里防御 parser 升级或异常输入。
+    throw new Error(`normalizeKeyword: unknown step keyword "${trimmed}"`);
+  }
+  return mapped;
+}
+
+// 行首中文步骤关键词 → 英文。用于无 # language 指令的混合写法
+// (英文 Feature/Scenario + 中文步骤),这是 PD .feature 文件的常见写法。
+// 要求关键词后跟空白,避免误伤描述文本里的中文字符。
+const CHINESE_STEP_KEYWORD_PATTERNS: ReadonlyArray<readonly [RegExp, string]> = [
+  [/^(\s*)(假如|假设|假定)(\s+)/gm, '$1Given$3'],
+  [/^(\s*)(当)(\s+)/gm, '$1When$3'],
+  [/^(\s*)(那么)(\s+)/gm, '$1Then$3'],
+  [/^(\s*)(而且|并且|同时)(\s+)/gm, '$1And$3'],
+  [/^(\s*)(但是)(\s+)/gm, '$1But$3'],
+];
+
+function hasLanguageDirective(featureText: string): boolean {
+  return /^\s*#\s*language\s*:/m.test(featureText);
+}
+
+function normalizeChineseStepKeywords(featureText: string): string {
+  let result = featureText;
+  for (const [pattern, replacement] of CHINESE_STEP_KEYWORD_PATTERNS) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+/**
+ * 解析 .feature 文本为 ParsedScenario[]。
+ *
+ * 纯逻辑,无 I/O。失败时 fail loud (rc-3),抛错带原因。
+ *
+ * 中文支持策略:
+ * - 有 `# language:` 指令 → 交给 @cucumber/gherkin 原生处理方言,KEYWORD_MAP 兜底归一化。
+ * - 无指令但含中文步骤关键词 → 行首归一化为英文后用默认英文方言解析
+ *   (支持英文 Feature/Scenario + 中文步骤的混合写法)。
+ */
+export function parseFeature(featureText: string): ParsedScenario[] {
+  if (!featureText || featureText.trim().length === 0) {
+    throw new Error('parseFeature: empty feature text');
+  }
+
+  const source = hasLanguageDirective(featureText)
+    ? featureText
+    : normalizeChineseStepKeywords(featureText);
+
+  let gherkinDocument: messages.GherkinDocument;
+  try {
+    const newId = messages.IdGenerator.uuid();
+    const parser = new Parser(new AstBuilder(newId), new GherkinClassicTokenMatcher());
+    gherkinDocument = parser.parse(source);
+  } catch (e) {
+    throw new Error(
+      `parseFeature: malformed feature file: ${e instanceof Error ? e.message : String(e)}`
+    );
+  }
+
+  if (!gherkinDocument.feature) {
+    throw new Error('parseFeature: feature file has no Feature section');
+  }
+
+  const feature = gherkinDocument.feature;
+  const featureTags = (feature.tags || []).map((t) => t.name);
+
+  // 提取 Background (一个 Feature 至多一个 Background,适用于全部 scenario)
+  let background: ParsedStep[] | undefined;
+  for (const child of feature.children || []) {
+    if (child.background) {
+      background = (child.background.steps || []).map((step) => ({
+        keyword: normalizeKeyword(step.keyword),
+        text: step.text,
+      }));
+      break;
+    }
+  }
+
+  // 提取 Scenario 列表
+  const scenarios: ParsedScenario[] = [];
+  for (const child of feature.children || []) {
+    if (!child.scenario) continue;
+    const scenario = child.scenario;
+    const scenarioTags = (scenario.tags || []).map((t) => t.name);
+    const steps: ParsedStep[] = (scenario.steps || []).map((step) => ({
+      keyword: normalizeKeyword(step.keyword),
+      text: step.text,
+    }));
+    scenarios.push({
+      featureName: feature.name || '(unnamed feature)',
+      featureTags,
+      scenarioName: scenario.name || '(unnamed scenario)',
+      scenarioTags,
+      background,
+      steps,
+    });
+  }
+
+  if (scenarios.length === 0) {
+    throw new Error('parseFeature: feature file has no Scenario');
+  }
+
+  return scenarios;
+}

package/tests/bdd/support/repo-root.ts

@@ -0,0 +1,62 @@
+import { fileURLToPath } from 'node:url';
+import { dirname, join, resolve, isAbsolute } from 'node:path';
+import { readFileSync, existsSync } from 'node:fs';
+
+/**
+ * 解析仓库根路径。优先用 PD_REPO_ROOT 环境变量,否则从 import.meta.url 向上查找
+ * 含 "principles-disciple-monorepo" 的 package.json。
+ *
+ * 不依赖 process.cwd(),避免在 package 目录下运行测试时路径错误。
+ */
+export function resolveRepoRoot(): string {
+  // 优先使用环境变量 (CI 显式注入)
+  const envRoot = process.env.PD_REPO_ROOT;
+  if (envRoot && existsSync(join(envRoot, 'package.json'))) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(envRoot, 'package.json'), 'utf8'));
+      if (pkg.name === 'principles-disciple-monorepo') {
+        return envRoot;
+      }
+    } catch {
+      // fallthrough to import.meta.url strategy
+    }
+  }
+
+  // 从 import.meta.url 向上查找
+  const thisFileDir = dirname(fileURLToPath(import.meta.url));
+  let current: string = thisFileDir;
+  for (let i = 0; i < 20; i++) {
+    const pkgPath = join(current, 'package.json');
+    if (existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+        if (pkg.name === 'principles-disciple-monorepo') {
+          return current;
+        }
+      } catch {
+        // continue upward
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+
+  throw new Error(
+    `resolveRepoRoot: cannot find principles-disciple-monorepo from ${thisFileDir}. ` +
+    `Set PD_REPO_ROOT env var or run from within the repo. Searched: ${thisFileDir} and 20 ancestors.`
+  );
+}
+
+/**
+ * 把相对仓库根的路径解析为绝对路径。
+ * 如果传入的已经是绝对路径,直接返回(若存在)。
+ */
+export function resolveFeaturePath(relativePath: string): string {
+  if (isAbsolute(relativePath)) {
+    return relativePath;
+  }
+  return resolve(resolveRepoRoot(), relativePath);
+}

package/tests/bdd/support/vitest-bdd.ts

@@ -0,0 +1,179 @@
+import { describe, it } from 'vitest';
+import { parseFeature, type ParsedStep } from './gherkin-loader.js';
+
+export interface StepContext {
+  state: Record<string, unknown>;
+  redactable: Record<string, unknown>;
+  attachments: Array<{ name: string; body: string }>;
+}
+
+export type StepFn = (ctx: StepContext, ...args: unknown[]) => void | Promise<void>;
+
+export interface StepMatch {
+  fn: StepFn;
+  args: unknown[];
+}
+
+export interface StepRegistry {
+  given(pattern: string | RegExp, fn: StepFn): void;
+  when(pattern: string | RegExp, fn: StepFn): void;
+  then(pattern: string | RegExp, fn: StepFn): void;
+  match(step: ParsedStep): StepMatch | null;
+  /** 返回已注册步骤的描述列表，用于 fail-loud 诊断 (rc-3)。 */
+  list(): ReadonlyArray<{ keyword: 'Given' | 'When' | 'Then'; pattern: string }>;
+}
+
+interface RegisteredStep {
+  keyword: 'Given' | 'When' | 'Then';
+  pattern: string | RegExp;
+  fn: StepFn;
+}
+
+/**
+ * defineFeature 使用的测试注册钩子。可选注入,便于单元测试验证
+ * @disabled 与正常注册路径调用了正确的钩子 (vitest 4.x 不允许在 it 内调 describe)。
+ */
+export interface DefineFeatureHooks {
+  describe: (name: string, fn: () => void) => void;
+  it: (name: string, fn: () => void | Promise<void>) => void;
+  itSkip: (name: string, fn: () => void) => void;
+}
+
+export function createStepRegistry(): StepRegistry {
+  const steps: RegisteredStep[] = [];
+
+  function register(keyword: RegisteredStep['keyword']) {
+    return (pattern: string | RegExp, fn: StepFn) => {
+      steps.push({ keyword, pattern, fn });
+    };
+  }
+
+  function match(step: ParsedStep): StepMatch | null {
+    for (const registered of steps) {
+      // keyword 匹配:And/But 匹配任何 registered keyword (gherkin 语义)
+      const keywordMatch =
+        step.keyword === registered.keyword ||
+        step.keyword === 'And' ||
+        step.keyword === 'But';
+      if (!keywordMatch) continue;
+
+      if (typeof registered.pattern === 'string') {
+        if (registered.pattern === step.text) {
+          return { fn: registered.fn, args: [] };
+        }
+      } else {
+        const m = registered.pattern.exec(step.text);
+        if (m) {
+          return { fn: registered.fn, args: m.slice(1) };
+        }
+      }
+    }
+    return null;
+  }
+
+  return {
+    given: register('Given'),
+    when: register('When'),
+    then: register('Then'),
+    match,
+    list: () => steps.map((s) => ({ keyword: s.keyword, pattern: String(s.pattern) })),
+  };
+}
+
+function parseDisabledTag(tags: string[]): { reason: string; owner: string; date: string } | null {
+  for (const tag of tags) {
+    if (tag.startsWith('@disabled')) {
+      // 格式: @disabled(reason="...",owner="...",date="...")
+      // rc-3/rc-9: 三字段必填，缺失即 fail loud，不允许静默 skip。
+      const reasonMatch = tag.match(/reason="([^"]+)"/);
+      const ownerMatch = tag.match(/owner="([^"]+)"/);
+      const dateMatch = tag.match(/date="([^"]+)"/);
+      if (!reasonMatch || !ownerMatch || !dateMatch) {
+        throw new Error(
+          `Malformed @disabled tag: reason, owner, date are all required. ` +
+          `Expected: @disabled(reason="...",owner="...",date="..."). Got: ${tag}`
+        );
+      }
+      return {
+        reason: reasonMatch[1],
+        owner: ownerMatch[1],
+        date: dateMatch[1],
+      };
+    }
+  }
+  return null;
+}
+
+function createStepContext(): StepContext {
+  return {
+    state: {},
+    redactable: {},
+    attachments: [],
+  };
+}
+
+/**
+ * 把 .feature 文本注册为 vitest describe/it。
+ *
+ * 关键行为:
+ * - @disabled 标签的 scenario 走 it.skip,并打印显式 skip 报告 (rc-9)
+ * - step 未匹配时 fail loud (rc-3)
+ * - 每个场景独立 StepContext (rc-7)
+ *
+ * hooks 可选注入,默认使用 vitest 的 describe/it/it.skip。测试时传 spy
+ * 可避免在 it 内调 describe 触发 vitest "suite inside test" 错误。
+ */
+export function defineFeature(
+  featureText: string,
+  registry: StepRegistry,
+  hooks?: Partial<DefineFeatureHooks>
+): void {
+  const h: DefineFeatureHooks = {
+    describe,
+    it,
+    itSkip: (name, fn) => it.skip(name, fn),
+    ...hooks,
+  };
+  const scenarios = parseFeature(featureText);
+
+  h.describe(scenarios[0]?.featureName ?? '(feature)', () => {
+    for (const scenario of scenarios) {
+      const disabledInfo = parseDisabledTag(scenario.scenarioTags);
+
+      if (disabledInfo) {
+        // 显式 skip 报告 (rc-9: no silent fallback)
+        h.itSkip(`${scenario.scenarioName} [SKIP: ${disabledInfo.reason}; owner=${disabledInfo.owner}; date=${disabledInfo.date}]`, () => {});
+        continue;
+      }
+
+      h.it(scenario.scenarioName, async () => {
+        const ctx = createStepContext();
+        const allSteps = [...(scenario.background ?? []), ...scenario.steps];
+
+        for (const step of allSteps) {
+          const match = registry.match(step);
+          if (!match) {
+            // fail loud (rc-3): 列出已注册 steps 帮助诊断
+            const registeredList = registry.list().length > 0
+              ? registry.list().map((s) => `  ${s.keyword} ${s.pattern}`).join('\n')
+              : '  (no steps registered)';
+            throw new Error(
+              `Step not matched: ${step.keyword} ${step.text}\n` +
+              `Scenario: ${scenario.scenarioName}\n` +
+              `Registered steps:\n${registeredList}`
+            );
+          }
+
+          try {
+            await match.fn(ctx, ...match.args);
+          } catch (e) {
+            // 增强 error 信息:附加 step 文本和场景名
+            const enhanced = e instanceof Error ? e : new Error(String(e));
+            enhanced.message = `Step failed: ${step.keyword} ${step.text}\nScenario: ${scenario.scenarioName}\n${enhanced.message}`;
+            throw enhanced;
+          }
+        }
+      });
+    }
+  });
+}

package/tests/commands/admission-gate-coverage.test.ts

@@ -0,0 +1,79 @@
+/**
+ * PRI-503 regression: admission gate must be checked before intakeService.intake()
+ * in every CLI command that calls it. This static source-text scan prevents future
+ * commands (or refactors) from re-introducing the bypass that PR #1134 missed in
+ * pain-retry.ts and diagnose.ts (ERR-089 sibling-branch defect).
+ *
+ * Why static scan: runtime mocking of the full CLI command path is heavy and
+ * brittle. A source-text check is deterministic, fast, and directly asserts the
+ * invariant ("gate call appears before intake call in the same file").
+ */
+import { describe, it, expect } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+
+const PD_CLI_COMMANDS_DIR = path.resolve(__dirname, '..', '..', 'src', 'commands');
+
+function readSource(fileName: string): string {
+  return fs.readFileSync(path.join(PD_CLI_COMMANDS_DIR, fileName), 'utf-8');
+}
+
+describe('PRI-503: admission gate coverage (static source scan)', () => {
+  describe('shared helper exists', () => {
+    it('admission-gate.ts exists and exports checkAdmissionGate', () => {
+      const content = readSource('admission-gate.ts');
+      expect(content).toContain('export function checkAdmissionGate');
+      expect(content).toContain('evaluateCandidateAdmissionFromRecord');
+    });
+  });
+
+  describe('candidate.ts uses shared helper (no local definition)', () => {
+    it('candidate.ts imports checkAdmissionGate from ./admission-gate.js', () => {
+      const content = readSource('candidate.ts');
+      expect(content).toContain("from './admission-gate.js'");
+      expect(content).toContain('checkAdmissionGate');
+    });
+
+    it('candidate.ts no longer defines a local function checkAdmissionGate', () => {
+      const content = readSource('candidate.ts');
+      // Local definition would be `function checkAdmissionGate(` at top level
+      expect(content).not.toMatch(/function\s+checkAdmissionGate\s*\(/);
+    });
+  });
+
+  describe('pain-retry.ts checks admission gate before intake', () => {
+    it('pain-retry.ts imports checkAdmissionGate from ./admission-gate.js', () => {
+      const content = readSource('pain-retry.ts');
+      expect(content).toContain("from './admission-gate.js'");
+      expect(content).toContain('checkAdmissionGate');
+    });
+
+    it('pain-retry.ts calls checkAdmissionGate before intakeService.intake', () => {
+      const content = readSource('pain-retry.ts');
+      const gateIdx = content.indexOf('checkAdmissionGate(');
+      const intakeIdx = content.indexOf('intakeService.intake(');
+      expect(gateIdx).toBeGreaterThan(-1);
+      expect(intakeIdx).toBeGreaterThan(-1);
+      // Gate MUST appear before intake in source order
+      expect(gateIdx).toBeLessThan(intakeIdx);
+    });
+  });
+
+  describe('diagnose.ts checks admission gate before intake', () => {
+    it('diagnose.ts imports checkAdmissionGate from ./admission-gate.js', () => {
+      const content = readSource('diagnose.ts');
+      expect(content).toContain("from './admission-gate.js'");
+      expect(content).toContain('checkAdmissionGate');
+    });
+
+    it('diagnose.ts calls checkAdmissionGate before intakeService.intake', () => {
+      const content = readSource('diagnose.ts');
+      const gateIdx = content.indexOf('checkAdmissionGate(');
+      const intakeIdx = content.indexOf('intakeService.intake(');
+      expect(gateIdx).toBeGreaterThan(-1);
+      expect(intakeIdx).toBeGreaterThan(-1);
+      // Gate MUST appear before intake in source order
+      expect(gateIdx).toBeLessThan(intakeIdx);
+    });
+  });
+});

package/tests/commands/candidate-audit-repair.test.ts

@@ -96,6 +96,18 @@ vi.mock('@principles/core/runtime-v2', () => ({
   }),
   resolveOutputLanguage: vi.fn().mockReturnValue({ outputLanguage: 'zh-CN' }),
   PrincipleTreeLedgerAdapter: MockPrincipleTreeLedgerAdapter,
+  evaluateCandidateAdmissionFromRecord: vi.fn((candidate: { recommendationKind: string; confidence: number | null }) => {
+    if (candidate.recommendationKind === 'defer') {
+      return { decision: 'deferred', reason: 'recommendation_kind_defer_not_actionable', nextAction: 'review_defer_disposition_manually', evidenceStatus: 'unknown' };
+    }
+    if (candidate.confidence === null) {
+      return { decision: 'needs_evidence', reason: 'confidence_missing_on_candidate_record', nextAction: 're_run_diagnosis_to_populate_confidence_or_manual_review', evidenceStatus: 'unknown' };
+    }
+    if (candidate.confidence !== undefined && candidate.confidence < 0.5) {
+      return { decision: 'needs_evidence', reason: `confidence_below_threshold:${candidate.confidence.toFixed(2)}<0.5`, nextAction: 'provide_additional_evidence_or_manual_review', evidenceStatus: 'unknown' };
+    }
+    return { decision: 'admitted', reason: 'cli_partial_check_passed_confidence_and_kind', nextAction: 'none', evidenceStatus: 'unknown' };
+  }),
 }));
 
 // PRI-443 Phase 5: loadLedger and getLedgerFilePathPublic now imported from
@@ -341,4 +353,69 @@ describe('pd candidate repair', () => {
     );
     expect(exitSpy).toHaveBeenCalledWith(1);
   });
+
+  // PRI-442 Stage 4: admission gate bypass prevention for repair
+  describe('admission gate bypass prevention (PRI-442 Stage 4)', () => {
+    it('refuses repair when recommendationKind is defer', async () => {
+      mockStateManager.getCandidate.mockResolvedValue({
+        candidateId: 'c-defer',
+        status: 'consumed',
+        artifactId: 'a1',
+        title: 'Deferred',
+        description: 'desc',
+        recommendationKind: 'defer',
+        confidence: 0.9,
+      });
+
+      await handleCandidateRepair({ candidateId: 'c-defer', workspace: '/tmp/test-workspace', json: true });
+
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"status": "refused"'),
+      );
+      expect(consoleLogSpy).toHaveBeenCalledWith(
+        expect.stringContaining('"admissionDecision": "deferred"'),
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('refuses repair when confidence is null (rc-3 fail loud)', async () => {
+      mockStateManager.getCandidate.mockResolvedValue({
+        candidateId: 'c-null',
+        status: 'consumed',
+        artifactId: 'a1',
+        title: 'Null conf',
+        description: 'desc',
+        recommendationKind: 'principle',
+        confidence: null,
+      });
+
+      await handleCandidateRepair({ candidateId: 'c-null', workspace: '/tmp/test-workspace', json: false });
+
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('Admission gate refused'),
+      );
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        expect.stringContaining('needs_evidence'),
+      );
+      expect(exitSpy).toHaveBeenCalledWith(1);
+    });
+
+    it('allows repair when candidate passes admission gate', async () => {
+      mockStateManager.getCandidate.mockResolvedValue({
+        candidateId: 'c-ok',
+        status: 'consumed',
+        artifactId: 'a1',
+        title: 'OK',
+        description: 'desc',
+        recommendationKind: 'principle',
+        confidence: 0.8,
+      });
+      mockAdapter.existsForCandidate.mockReturnValue(null);
+      mockService.intake.mockResolvedValue({ id: 'entry-1', title: 'OK', text: 'text', status: 'probation' });
+
+      await handleCandidateRepair({ candidateId: 'c-ok', workspace: '/tmp/test-workspace', json: true });
+
+      expect(mockService.intake).toHaveBeenCalledWith('c-ok');
+    });
+  });
 });