@boyingliu01/xp-gate 0.19.2 → 0.20.0

package/plugins/qoder/skills/to-issues/SKILL.md

@@ -242,7 +242,7 @@ Phase 1: PLAN     → autoplan → delphi-review → specification.yaml
                   → **/to-issues** → slices-manifest.json + Issue 列表
 Phase 2: BUILD    → 按 execution_order 逐个切片执行
                   → 每个切片 = 一个 REQ（ralph-loop 模式）
-                  → 或通过 dispatching-parallel-agents 并行（无依赖的 AFK 切片）
+                  → 或通过原生 Task 并行派发（无依赖的 AFK 切片）
 Phase 3: REVIEW   → **整体 review**（全部切片完成后统一 code-walkthrough）
                   → browse / QA 验证端到端行为
 Phase 4: USER ACC → 人工验收（全部切片集成后的完整功能）

package/principles/AGENTS.md

@@ -1,9 +1,9 @@
 # PRINCIPLES CHECKER MODULE
 
-**Generated:** 2026-09-22
-**Commit:** 3d1d1bf
-**Branch:** main
-**Version:** 0.19.2.0
+**Generated:** 2026-10-07
+**Commit:** ff55f35b
+**Branch:** fix/batch-defects-20261007
+**Version:** 0.20.0.0
 
 ## OVERVIEW
 Clean Code & SOLID principles checker — **Gate 4** of pre-commit. 14 rules × 9 language adapters, SARIF 2.1.0 output. Houses the **Boy Scout Rule** enforcement engine (Gate 6) and warning-baseline storage.
@@ -52,7 +52,8 @@ src/principles/
 | Output | reporter.ts | Emits Console, JSON, or SARIF 2.1.0 |
 | Thresholds | config.ts + .principlesrc | Defaults + project overrides |
 | Boy Scout enforcement | boy-scout.ts | classifyFiles → calculateDelta → enforceBoyScoutRule |
-| Baseline lifecycle | baseline.ts | loadBaseline, saveBaseline, initBaseline |
+| Baseline lifecycle | boy-scout.ts | loadBaseline, saveBaseline, initBaseline |
+| Baseline storage | baseline.ts | BaselineStorage (size/timeout/batch guards) + filterBaselineWarnings |
 | Adapter for new language | adapters/base.ts + add `<lang>.ts` | Subclass base; export via index |
 | C / C++ extraction | adapters/cpp.ts | Regex-based; handles both `.cpp` and `.c` |
 | Tests | __tests__/ | Adapter, rule, and core tests |
@@ -67,9 +68,9 @@ src/principles/
 | classifyFiles | Function | boy-scout.ts | new / modified / untouched bucket assignment |
 | calculateDelta | Function | boy-scout.ts | Diff vs `.warnings-baseline.json` |
 | enforceBoyScoutRule | Function | boy-scout.ts | Block when modified-file warnings increase |
-| loadBaseline | Function | baseline.ts | Read `.warnings-baseline.json` |
-| saveBaseline | Function | baseline.ts | Write updated baseline after successful commit |
-| initBaseline | Function | baseline.ts | First-time auto-snapshot (≤5 warnings ⇒ must clear to zero) |
+| loadBaseline | Function | boy-scout.ts | Read `.warnings-baseline.json` |
+| saveBaseline | Function | boy-scout.ts | Write updated baseline after successful commit |
+| initBaseline | Function | boy-scout.ts | First-time auto-snapshot (≤5 warnings ⇒ must clear to zero) |
 
 ## CONVENTIONS
 - **Rule ID format**: `clean-code.long-function`, `solid.srp`. Stable, dot-namespaced.

package/principles/__tests__/adapter-metrics.test.ts

@@ -0,0 +1,292 @@
+/**
+ * @test REQ-DSH-015
+ * @intent 验证 TypeScriptAdapter 为各规则提供其所需度量字段：fix #446 之前，
+ *         createCodeMatch() 只返回 {name,type,line,code}，而规则读取
+ *         length / paramCount / nestingDepth / methodCount / hasTryCatch，
+ *         导致 14 条规则里 12 条在 TypeScript 上结构性无法触发（Gate 4 形同虚设）
+ * @covers AC-DSH-015-01
+ *
+ * Mock-first per src/principles/AGENTS.md: inline fixture, no separate files.
+ */
+
+import { describe, it, expect, vi, type Mock } from 'vitest';
+import { TypeScriptAdapter } from '../adapters/typescript';
+
+vi.mock('fs', () => ({
+  readFileSync: vi.fn(),
+  existsSync: vi.fn(() => true),
+}));
+
+import { readFileSync } from 'fs';
+
+const LONG_BODY = Array.from({ length: 60 }, (_, i) => `  const v${i} = ${i};`).join('\n');
+
+const SAMPLE = `
+import { helper } from './helper';
+
+export function eightParams(a: number, b: number, c: number, d: number, e: number, f: number, g: number, h: number) {
+  return a + b + c + d + e + f + g + h;
+}
+
+export function longOne() {
+${LONG_BODY}
+  return 0;
+}
+
+export function deeplyNested(a: number) {
+  if (a > 0) {
+    if (a > 1) {
+      if (a > 2) {
+        if (a > 3) {
+          if (a > 4) {
+            return 'deep';
+          }
+        }
+      }
+    }
+  }
+  return 'shallow';
+}
+
+export function rawIo() {
+  return readFileSync('/tmp/x', 'utf-8');
+}
+
+export function guardedIo() {
+  try {
+    return readFileSync('/tmp/x', 'utf-8');
+  } catch (e) {
+    return '';
+  }
+}
+
+export const arrowFn = (x: number, y: number) => x + y;
+
+export class MegaService {
+  aMethod() { return 1; }
+  m1() { return 1; } m2() { return 1; } m3() { return 1; } m4() { return 1; }
+  m5() { return 1; } m6() { return 1; } m7() { return 1; } m8() { return 1; }
+  m9() { return 1; } m10() { return 1; } m11() { return 1; } m12() { return 1; }
+  m13() { return 1; } m14() { return 1; } m15() { return 1; }
+}
+`;
+
+interface FnInfo {
+  name: string;
+  startLine?: number;
+  line?: number;
+  length?: number;
+  paramCount?: number;
+  nestingDepth?: number;
+  hasTryCatch?: boolean;
+  ioOperations?: string[];
+}
+
+interface ClsInfo {
+  name: string;
+  methodCount?: number;
+  line?: number;
+}
+
+function adapterFor(content = SAMPLE): TypeScriptAdapter {
+  (readFileSync as Mock).mockReturnValue(content);
+  return new TypeScriptAdapter('sample.ts');
+}
+
+describe('TypeScriptAdapter metric extraction (#446)', () => {
+  describe('extractFunctions', () => {
+    it('reports paramCount for every function', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const eight = fns.find(f => f.name === 'eightParams');
+      expect(eight).toBeDefined();
+      expect(eight?.paramCount).toBe(8);
+    });
+
+    it('reports length (body span) for every function', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const long = fns.find(f => f.name === 'longOne');
+      expect(long).toBeDefined();
+      // > 50 lines is the long-function threshold; assert it is measured at all.
+      expect(long?.length).toBeGreaterThan(50);
+    });
+
+    it('reports nestingDepth for every function', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const deep = fns.find(f => f.name === 'deeplyNested');
+      expect(deep).toBeDefined();
+      expect(deep?.nestingDepth).toBeGreaterThanOrEqual(5);
+    });
+
+    it('reports hasTryCatch for unguarded and guarded IO', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const io = fns.find(f => f.name === 'rawIo');
+      expect(io).toBeDefined();
+      expect(io?.hasTryCatch).toBe(false);
+
+      const guarded = fns.find(f => f.name === 'guardedIo');
+      expect(guarded).toBeDefined();
+      expect(guarded?.hasTryCatch).toBe(true);
+    });
+
+    it('reports ioOperations for IO-performing functions', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const io = fns.find(f => f.name === 'rawIo');
+      expect(io?.ioOperations?.length ?? 0).toBeGreaterThan(0);
+    });
+
+    it('still reports name / line for every function', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      expect(fns.length).toBeGreaterThan(0);
+      for (const f of fns) {
+        expect(f.name).toBeTruthy();
+        expect(f.line).toBeGreaterThan(0);
+      }
+    });
+
+    it('finds arrow functions and class methods, not only `function` declarations', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const names = fns.map(f => f.name);
+      // Arrow consts and class methods are the dominant modern TS forms; the old
+      // regex only matched the literal `function` keyword.
+      expect(names).toContain('arrowFn');
+      expect(names).toContain('aMethod');
+    });
+  });
+
+  describe('extractClasses', () => {
+    it('reports methodCount per class', () => {
+      const classes = adapterFor().extractClasses() as ClsInfo[];
+      const mega = classes.find(c => c.name === 'MegaService');
+      expect(mega).toBeDefined();
+      expect(mega?.methodCount).toBeGreaterThanOrEqual(15);
+    });
+  });
+
+  describe('imports', () => {
+    interface ImportInfo {
+      name?: string;
+      line?: number;
+      used?: boolean;
+      type?: string;
+    }
+
+    it('returns objects, not bare strings (the rule reads .name/.used)', () => {
+      const imports = (adapterFor() as unknown as { imports: ImportInfo[] }).imports;
+      expect(Array.isArray(imports)).toBe(true);
+      expect(imports.length).toBeGreaterThan(0);
+      for (const imp of imports) {
+        expect(typeof imp).toBe('object');
+        // Never leak `undefined` as a name -- it renders straight into the message.
+        expect(imp.name).toBeTruthy();
+        expect(imp.name).not.toBe('undefined');
+        expect(imp.line).toBeGreaterThan(0);
+      }
+    });
+
+    it('marks a genuinely unused import as unused', () => {
+      const imports = (adapterFor() as unknown as { imports: ImportInfo[] }).imports;
+      const helper = imports.find(i => i.name === 'helper');
+      expect(helper).toBeDefined();
+      // `helper` is imported but never referenced in SAMPLE.
+      expect(helper?.used).toBe(false);
+    });
+
+    it('marks a referenced import as used', () => {
+      const content = `
+import { readFileSync } from 'fs';
+export function go() { return readFileSync('/tmp/x', 'utf-8'); }
+`;
+      const imports = (adapterFor(content) as unknown as { imports: ImportInfo[] }).imports;
+      const rfs = imports.find(i => i.name === 'readFileSync');
+      expect(rfs).toBeDefined();
+      expect(rfs?.used).toBe(true);
+    });
+  });
+
+  describe('extract (magic numbers, #446)', () => {
+    it('returns {value,line} objects and ignores comments/strings', () => {
+      const content = `
+// 999 should not count (comment)
+const s = "1234 should not count (string)";
+export function f() { return 12345; }
+`;
+      const nums = (adapterFor(content) as unknown as {
+        extract: () => Array<{ value: number; line: number }>;
+      }).extract();
+      const values = nums.map(n => n.value);
+      expect(values).toContain(12345);
+      expect(values).not.toContain(999);
+      expect(values).not.toContain(1234);
+      for (const n of nums) expect(n.line).toBeGreaterThan(0);
+    });
+
+    /**
+     * @test REQ-DSH-018
+     * @intent 验证「命名常量的初始化值」不被当作 magic number：规则的修复建议
+     *         就是「改用命名常量」，若常量本身仍被标记，该违规永远无法消除
+     * @covers AC-DSH-018-01
+     */
+    it('skips the initializer of a named constant but still reports bare literals', () => {
+      // Fixtures are bare fragments: no `export`, so this file does not itself
+      // trip the many-exports rule that the adapter under test is meant to flag.
+      const content = `
+const RENAME_PARTS = 3;
+const BUDGET: number = 5;
+function f(): number {
+  return 137;
+}
+`;
+      const nums = (adapterFor(content) as unknown as {
+        extract: () => Array<{ value: number; line: number }>;
+      }).extract();
+      const values = nums.map(n => n.value);
+
+      // The rule asks for named constants, so the constants must not be flagged.
+      expect(values).not.toContain(3);
+      expect(values).not.toContain(5);
+      // A bare literal in a body is the actual target and must still be reported.
+      expect(values).toContain(137);
+    });
+
+    it('still reports a number assigned to a non-constant binding', () => {
+      // Only `const`/`readonly` declarations are exempt; `let x = 99` is not.
+      const content = `
+function f(): number {
+  let x = 99;
+  return x;
+}
+`;
+      const nums = (adapterFor(content) as unknown as {
+        extract: () => Array<{ value: number; line: number }>;
+      }).extract();
+      expect(nums.map(n => n.value)).toContain(99);
+    });
+  });
+
+  describe('extractInterfaces (ISP, #446)', () => {
+    it('reports interface names and methodCount', () => {
+      const content = `
+export interface Worker {
+  run(): void;
+  stop(): void;
+}
+`;
+      const ifaces = (adapterFor(content) as unknown as {
+        extractInterfaces: () => Array<{ name: string; methodCount: number }>;
+      }).extractInterfaces();
+      const worker = ifaces.find(i => i.name === 'Worker');
+      expect(worker).toBeDefined();
+      expect(worker?.methodCount).toBe(2);
+    });
+  });
+
+  describe('no control-flow false positives', () => {
+    it('does not report `if` / `for` / `while` as functions', () => {
+      const fns = adapterFor().extractFunctions() as FnInfo[];
+      const names = fns.map(f => f.name);
+      for (const kw of ['if', 'for', 'while', 'switch', 'catch', 'return']) {
+        expect(names).not.toContain(kw);
+      }
+    });
+  });
+});

package/principles/__tests__/analyzer.test.ts

@@ -6,6 +6,7 @@
 
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { analyze } from '../analyzer';
+import { getDefaultConfig, resetActiveConfig, setActiveConfig } from '../config';
 import { Rule, Adapter, Severity } from '../types';
 
 describe('analyzer.ts - Rule Orchestration Engine', () => {
@@ -114,6 +115,26 @@ describe('analyzer.ts - Rule Orchestration Engine', () => {
       expect(disabledRule.check).not.toHaveBeenCalled();
     });
 
+    it('a rule disabled by config must not report files as checked (#457)', async () => {
+      // `filesChecked` used to be incremented before the `enabled` check, so a rule
+      // that never ran still claimed it had examined the file -- inflating per-rule
+      // coverage statistics for work the rule did not do.
+      const disabled = getDefaultConfig();
+      disabled.rules['clean-code']['long-function'].enabled = false;
+      try {
+        setActiveConfig(disabled);
+        const result = await analyze(['test.ts'], [mockRule], mockAdapter, {});
+        expect(mockRule.check).not.toHaveBeenCalled();
+        expect(result.ruleResults['clean-code.long-function'].filesChecked).toBe(0);
+      } finally {
+        // Restore the process-global config so later tests are unaffected.
+        // `resetActiveConfig()` rather than re-installing the captured config:
+        // replacing an already-installed config is exactly what the #457
+        // guardrail reports, and this suite never installs a non-default one.
+        resetActiveConfig();
+      }
+    });
+
     it('should return empty violations if all rules pass', async () => {
       const passingRule: Rule = {
         id: 'clean-code.passing',
@@ -228,6 +249,13 @@ it('should skip files that do not match adapter language', async () => {
   });
 
   describe('runRuleOnFile (via analyze) — verifies context-object parameter bundling', () => {
+    // Extracted from the test body: inlining this callback pushed the test past the
+    // 4-level nesting limit for no readability gain.
+    const ruleACheck = vi.fn().mockImplementation((file: string) => {
+      if (file !== 'a.ts') return [];
+      return [{ file: 'a.ts', line: 1, ruleId: 'test.rule-a', message: 'violation in a', severity: 'warning' as Severity }];
+    });
+
     it('should correctly aggregate violations per file and per rule', async () => {
       const files = ['a.ts', 'b.ts'];
       const ruleA = {
@@ -235,12 +263,7 @@ it('should skip files that do not match adapter language', async () => {
         name: 'Rule A',
         threshold: 10,
         severity: 'warning' as Severity,
-        check: vi.fn().mockImplementation((file: string) => {
-          if (file === 'a.ts') {
-            return [{ file: 'a.ts', line: 1, ruleId: 'test.rule-a', message: 'violation in a', severity: 'warning' as Severity }];
-          }
-          return [];
-        })
+        check: ruleACheck
       } as Rule;
       const ruleB = {
         id: 'test.rule-b',

package/principles/__tests__/baseline-prune-timeout.test.ts

@@ -0,0 +1,71 @@
+/**
+ * @test REQ-452 REQ-3
+ * @intent The baseline pruner runs inside a git hook, so its worst failure mode is
+ *         not a wrong answer but a commit that never returns. Every git call it
+ *         makes must carry a timeout, and the timeout must be short enough that a
+ *         wedged git degrades to "keep the entry" rather than hanging the hook.
+ * @covers AC-452-14
+ *
+ * Mocked rather than stubbed with a fake binary: `execFileSync` resolves PATH
+ * entries without consulting PATHEXT unless `shell` is set, so a `git.cmd` shim on
+ * PATH is silently ignored in favour of the real binary -- a test built that way
+ * passes while proving nothing. Asserting the options handed to child_process
+ * tests the guard itself instead of Node's PATH resolution.
+ */
+
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+const execFileSyncMock = vi.fn();
+
+vi.mock('child_process', () => ({
+  execFileSync: (...args: unknown[]) => execFileSyncMock(...args),
+}));
+vi.mock('fs', async () => {
+  const actual = await vi.importActual<typeof import('fs')>('fs');
+  return { ...actual, existsSync: vi.fn(() => false) };
+});
+
+import { pruneBaselineEntries } from '../baseline-prune';
+
+/** Generous for a healthy `git ls-files`, short enough not to wedge a hook. */
+const MAX_ACCEPTABLE_GIT_TIMEOUT_MS = 60_000;
+
+describe('baseline pruning git invocation (#452)', () => {
+  beforeEach(() => {
+    execFileSyncMock.mockReset();
+  });
+
+  it('AC-452-14: bounds every git call with a timeout', () => {
+    execFileSyncMock.mockReturnValue('tracked.ts\n');
+
+    pruneBaselineEntries(JSON.stringify({ 'gone.ts': { 'clean-code.large-file': 1 } }), '/tmp/project');
+
+    expect(execFileSyncMock).toHaveBeenCalled();
+    for (const call of execFileSyncMock.mock.calls) {
+      const options = call[2] as { timeout?: number };
+      expect(typeof options.timeout).toBe('number');
+      expect(options.timeout).toBeGreaterThan(0);
+      expect(options.timeout).toBeLessThanOrEqual(MAX_ACCEPTABLE_GIT_TIMEOUT_MS);
+    }
+  });
+
+  it('AC-452-14: a git timeout keeps entries instead of failing the hook', () => {
+    // execFileSync reports a killed process as an error with no stdout, which is
+    // how a wedged git surfaces here.
+    execFileSyncMock.mockImplementation(() => {
+      const error = new Error('spawnSync git ETIMEDOUT') as Error & { signal?: string };
+      error.signal = 'SIGTERM';
+      throw error;
+    });
+
+    const result = pruneBaselineEntries(
+      JSON.stringify({ 'gone.ts': { 'clean-code.large-file': 1 } }),
+      '/tmp/project',
+    );
+
+    // Fail closed: an unreadable index must never justify deleting an entry.
+    expect(result.removed).toEqual([]);
+    expect(result.kept).toEqual(['gone.ts']);
+    expect(result.error).toBeDefined();
+  });
+});