@boyingliu01/xp-gate 0.5.3 → 0.6.1

package/bin/xp-gate.js

@@ -53,6 +53,11 @@ const COMMANDS = {
     description: 'Run UI review for non-sprint developers (generates .ui-gate-result.json)',
     fn: null,
     usage: 'xp-gate ui-review'
+  },
+  'audit': {
+    description: 'Gate audit logging (record, --tail, --stats)',
+    fn: null,
+    usage: 'xp-gate audit [--tail [N]|--stats|record --gate-id X --gate-name Y ...]'
   }
 };
 
@@ -153,12 +158,132 @@ function main() {
       process.exit(1);
     }
   }
+
+  if (command === 'audit') {
+    handleAudit(subargs);
+    return;
+  }
   
   console.error(`Unknown command: ${command}`);
   printHelp();
   process.exit(1);
 }
 
+function handleAudit(args) {
+  const path = require('path');
+  const auditPath = path.join(__dirname, '..', 'lib', 'gate-audit.ts');
+
+  // --tail [N]
+  const tailIdx = args.indexOf('--tail');
+  if (tailIdx !== -1) {
+    const count = parseInt(args[tailIdx + 1] || '20', 10);
+    try {
+      const { readTailEntries } = require(auditPath);
+      const entries = readTailEntries(count);
+      if (entries.length === 0) {
+        console.log('No audit entries found.');
+        return;
+      }
+      printAuditTable(entries);
+    } catch (err) {
+      console.error('Error reading audit entries:', err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // --stats
+  if (args.includes('--stats')) {
+    try {
+      const { computeStats } = require(auditPath);
+      const stats = computeStats();
+      if (stats.length === 0) {
+        console.log('No audit data found.');
+        return;
+      }
+      printStatsTable(stats);
+    } catch (err) {
+      console.error('Error computing stats:', err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  // record --gate-id X --gate-name Y --passed true/false ...
+  if (args[0] === 'record') {
+    try {
+      const { appendAuditEntry } = require(auditPath);
+      const rest = args.slice(1);
+      const opts = {};
+      for (let i = 0; i < rest.length; i++) {
+        if (rest[i].startsWith('--') && i + 1 < rest.length) {
+          opts[rest[i].slice(2)] = rest[i + 1];
+          i++;
+        }
+      }
+      const entry = {
+        timestamp: new Date().toISOString(),
+        gate_id: opts['gate-id'] || 'unknown',
+        gate_name: opts['gate-name'] || 'unknown',
+        passed: opts['passed'] === 'true',
+        issues_found: parseInt(opts['issues-found'] || '0', 10),
+        duration_ms: parseInt(opts['duration-ms'] || '0', 10),
+        trigger: opts['trigger'] || 'manual',
+        repo_path: process.cwd(),
+        commit_hash: opts['commit-hash'] || 'HEAD',
+      };
+      appendAuditEntry(entry);
+    } catch (err) {
+      console.error('Error recording audit entry:', err.message);
+      process.exit(1);
+    }
+    return;
+  }
+
+  console.error('Error: Unknown audit subcommand or missing flag');
+  console.error('Usage:');
+  console.error('  xp-gate audit record --gate-id X --gate-name Y --passed true/false --issues-found N --duration-ms N --trigger commit');
+  console.error('  xp-gate audit --tail [N]     (default: 20)');
+  console.error('  xp-gate audit --stats');
+  process.exit(1);
+}
+
+function printAuditTable(entries) {
+  console.log('');
+  console.log('Recent Audit Entries:');
+  console.log('┌─────────────────────┬──────────┬─────────────────────┬────────┬────────┬───────────┬──────────┐');
+  console.log('│ Timestamp           │ Gate     │ Name                │ Passed │ Issues │ Duration  │ Trigger  │');
+  console.log('├─────────────────────┼──────────┼─────────────────────┼────────┼────────┼───────────┼──────────┤');
+  for (const e of entries) {
+    const ts = e.timestamp ? e.timestamp.slice(0, 19) : 'N/A';
+    const gid = (e.gate_id || '').padEnd(8);
+    const gname = (e.gate_name || '').slice(0, 19).padEnd(19);
+    const pass = (e.passed ? 'Y' : 'N').padEnd(6);
+    const issues = String(e.issues_found ?? 0).padEnd(6);
+    const dur = String(e.duration_ms ?? 0).padEnd(9);
+    const trig = (e.trigger || 'manual').padEnd(8);
+    console.log(`│ ${ts} │ ${gid} │ ${gname} │ ${pass} │ ${issues} │ ${dur} │ ${trig} │`);
+  }
+  console.log('└─────────────────────┴──────────┴─────────────────────┴────────┴────────┴───────────┴──────────┘');
+  console.log(`Total: ${entries.length} entries`);
+}
+
+function printStatsTable(stats) {
+  console.log('');
+  console.log('Gate Statistics:');
+  console.log('┌──────────────────┬────────┬────────┬────────────┐');
+  console.log('│ Gate             │ Pass%  │ Avg ms │ Issues Avg │');
+  console.log('├──────────────────┼────────┼────────┼────────────┤');
+  for (const s of stats) {
+    const gid = (s.gate_id || '').slice(0, 16).padEnd(16);
+    const pp = (s.pass_pct || 'N/A').padEnd(6);
+    const avg = String(s.avg_ms ?? 0).padEnd(6);
+    const iss = String(s.avg_issues ?? 0).padEnd(10);
+    console.log(`│ ${gid} │ ${pp} │ ${avg} │ ${iss} │`);
+  }
+  console.log('└──────────────────┴────────┴────────┴────────────┘');
+}
+
 function parseOptions(args) {
   const options = { offline: false, verbose: false, force: false, all: false, check: false };
   for (const arg of args) {

package/hooks/pre-push

@@ -185,20 +185,29 @@ else
   for test_file in $ALL_PUSHED_TEST_FILES; do
     if [ -f "$test_file" ]; then
       # Count mock keyword references (precise patterns only)
+      # Use grep -o piped to wc -l for reliable single-number output (grep -c can emit
+      # multi-line output with filenames under some grep versions, causing bash arithmetic
+      # syntax errors). grep -o extracts each match on its own line, wc -l counts them.
       MOCK_COUNT=0
       for kw in 'jest\.mock' 'vi\.mock' 'jest\.spyOn' 'vi\.spyOn' 'jest\.fn' 'vi\.fn' \
                 'mockResolvedValue' 'mockRejectedValue' 'mockReturnValue' 'mockImplementation' \
                 'createMock' 'mockReset' 'mockClear' 'mockRestore' 'MagicMock' 'unittest\.mock' \
-                '\.patch(' 'gomock' 'mockgen' '.EXPECT()'; do
-        c=$(grep -o -c "$kw" "$test_file" 2>/dev/null || echo "0")
+                '\.patch(' 'gomock' 'mockgen' '\.EXPECT()'; do
+        c=$(grep -o "$kw" "$test_file" 2>/dev/null | wc -l || echo "0")
+        # Guard against empty/non-numeric values that break bash arithmetic
+        c=${c//[^0-9]/}
+        c=${c:-0}
         MOCK_COUNT=$((MOCK_COUNT + c))
       done
 
       # Count total non-empty, non-comment lines for density denominator
       TOTAL_LINES=$(grep -v '^\s*$' "$test_file" | grep -v '^\s*//' | grep -v '^\s*\*' | grep -v '^\s*#' | wc -l | awk '{print $1}')
+      TOTAL_LINES=${TOTAL_LINES//[^0-9]/}
+      TOTAL_LINES=${TOTAL_LINES:-0}
 
       if [ "$TOTAL_LINES" -gt 0 ] 2>/dev/null; then
         MOCK_DENSITY=$(awk "BEGIN {printf \"%.1f\", ($MOCK_COUNT / $TOTAL_LINES) * 100}")
+        MOCK_DENSITY=${MOCK_DENSITY:-"0"}
       else
         MOCK_DENSITY="0"
       fi

package/lib/__tests__/audit-log.test.ts

@@ -0,0 +1,107 @@
+/**
+ * @test audit-log
+ * @intent Verify UI gate bypass audit logging and threshold reporting
+ * @covers AUDIT-LOG-001
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, rmSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  appendAuditEntry,
+  readAllEntries,
+  countBypassesInWindow,
+  exceedsBypassThreshold,
+  formatRetroReport,
+  type AuditEntry,
+} from '../audit-log';
+
+const TEST_DIR = join(process.cwd(), '.audit-log-test');
+
+function baseEntry(overrides: Partial<Omit<AuditEntry, 'gate_count'>> = {}): Omit<AuditEntry, 'gate_count'> {
+  return {
+    timestamp: new Date().toISOString(),
+    branch: 'main',
+    commit: 'abc123',
+    user: 'tester',
+    reason: 'manual approval for test',
+    bypass_type: 'ui-gates',
+    ...overrides,
+  };
+}
+
+describe('audit-log', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe('appendAuditEntry and readAllEntries', () => {
+    it('should append an entry and compute gate_count', () => {
+      const first = appendAuditEntry(baseEntry(), TEST_DIR);
+      const second = appendAuditEntry(baseEntry({ commit: 'def456' }), TEST_DIR);
+
+      expect(first.gate_count).toBe(0);
+      expect(second.gate_count).toBe(1);
+
+      const entries = readAllEntries(join(TEST_DIR, '.audit-log.jsonl'));
+      expect(entries).toHaveLength(2);
+      expect(entries[1].commit).toBe('def456');
+    });
+
+    it('should return empty array when log file is missing or empty', () => {
+      expect(readAllEntries(join(TEST_DIR, 'missing.jsonl'))).toEqual([]);
+      const emptyLog = join(TEST_DIR, '.audit-log.jsonl');
+      writeFileSync(emptyLog, '', 'utf8');
+      expect(readAllEntries(emptyLog)).toEqual([]);
+    });
+  });
+
+  describe('rolling window calculations', () => {
+    it('should count only matching bypass type in rolling window', () => {
+      const now = new Date();
+      const old = new Date(now.getTime() - 40 * 24 * 60 * 60 * 1000).toISOString();
+      const entries: AuditEntry[] = [
+        { ...baseEntry({ timestamp: now.toISOString(), bypass_type: 'ui-gates' }), gate_count: 0 },
+        { ...baseEntry({ timestamp: now.toISOString(), bypass_type: 'other' }), gate_count: 0 },
+        { ...baseEntry({ timestamp: old, bypass_type: 'ui-gates' }), gate_count: 0 },
+      ];
+
+      expect(countBypassesInWindow(entries, 'ui-gates')).toBe(1);
+    });
+
+    it('should report threshold exceedance', () => {
+      const entries: AuditEntry[] = Array.from({ length: 4 }, (_, i) => ({
+        ...baseEntry({ commit: `commit-${i}` }),
+        gate_count: i,
+      }));
+      expect(exceedsBypassThreshold(entries, 'ui-gates')).toEqual({ exceeded: true, count: 4 });
+    });
+  });
+
+  describe('formatRetroReport', () => {
+    it('should include recent bypasses and threshold warning', () => {
+      const entries: AuditEntry[] = Array.from({ length: 4 }, (_, i) => ({
+        ...baseEntry({ reason: `reason-${i}`, branch: `branch-${i}` }),
+        gate_count: i,
+      }));
+      const report = formatRetroReport(entries, 'ui-gates');
+      expect(report).toContain('Last 30 days: 4 bypasses');
+      expect(report).toContain('EXCEEDS threshold');
+      expect(report).toContain('reason-3');
+    });
+
+    it('should omit recent section when no matching bypasses exist', () => {
+      const report = formatRetroReport([], 'ui-gates');
+      expect(report).toContain('Last 30 days: 0 bypasses');
+      expect(report).not.toContain('Recent bypasses');
+    });
+  });
+});

package/lib/__tests__/gate-audit.test.ts

@@ -0,0 +1,258 @@
+/**
+ * @test Gate Audit Logger
+ * @intent Verify JSONL audit logging for quality gate executions
+ * @covers AUDIT-001-01, AUDIT-001-02, AUDIT-001-03, AUDIT-001-04, AUDIT-001-05, AUDIT-001-06
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { existsSync, mkdirSync, rmSync, readFileSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import {
+  appendAuditEntry,
+  readTailEntries,
+  computeStats,
+  rotateIfNeeded,
+  parseCliOptions,
+  getCommitHash,
+  type GateAuditEntry,
+} from '../gate-audit';
+
+const TEST_DIR = join(process.cwd(), '.xp-gate-test');
+
+function makeEntry(overrides: Partial<GateAuditEntry> = {}): GateAuditEntry {
+  return {
+    timestamp: new Date().toISOString(),
+    gate_id: 'gate-1',
+    gate_name: 'code-quality',
+    passed: true,
+    issues_found: 0,
+    duration_ms: 100,
+    trigger: 'commit',
+    repo_path: TEST_DIR,
+    commit_hash: 'abc123',
+    ...overrides,
+  };
+}
+
+describe('gate-audit', () => {
+  beforeEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+    mkdirSync(TEST_DIR, { recursive: true });
+  });
+
+  afterEach(() => {
+    if (existsSync(TEST_DIR)) {
+      rmSync(TEST_DIR, { recursive: true, force: true });
+    }
+  });
+
+  describe('appendAuditEntry', () => {
+    it('should create .xp-gate/ directory on first write', () => {
+      const repoRoot = join(TEST_DIR, 'new-project');
+      appendAuditEntry(makeEntry({ repo_path: repoRoot }), repoRoot);
+      expect(existsSync(join(repoRoot, '.xp-gate'))).toBe(true);
+    });
+
+    it('should write valid JSONL', () => {
+      const repoRoot = join(TEST_DIR, 'jsonl-test');
+      const entry = makeEntry({ repo_path: repoRoot, gate_id: 'gate-2', gate_name: 'dup-code' });
+      appendAuditEntry(entry, repoRoot);
+
+      const logPath = join(repoRoot, '.xp-gate', 'audit.jsonl');
+      expect(existsSync(logPath)).toBe(true);
+
+      const content = readFileSync(logPath, 'utf8').trim();
+      const parsed = JSON.parse(content) as GateAuditEntry;
+      expect(parsed.gate_id).toBe('gate-2');
+      expect(parsed.gate_name).toBe('dup-code');
+      expect(typeof parsed.timestamp).toBe('string');
+    });
+
+    it('should append multiple entries as separate lines', () => {
+      const repoRoot = join(TEST_DIR, 'multi-test');
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1' }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-2' }), repoRoot);
+
+      const logPath = join(repoRoot, '.xp-gate', 'audit.jsonl');
+      const lines = readFileSync(logPath, 'utf8').trim().split('\n');
+      expect(lines.length).toBe(2);
+      expect(JSON.parse(lines[0]).gate_id).toBe('gate-1');
+      expect(JSON.parse(lines[1]).gate_id).toBe('gate-2');
+    });
+
+    it('should never throw even when filesystem is broken', () => {
+      const badPath = '/nonexistent/path/that/cannot/exist/for/real';
+      expect(() => appendAuditEntry(makeEntry({ repo_path: badPath }), badPath)).not.toThrow();
+    });
+  });
+
+  describe('readTailEntries', () => {
+    it('should return last N entries', () => {
+      const repoRoot = join(TEST_DIR, 'tail-test');
+      for (let i = 1; i <= 30; i++) {
+        appendAuditEntry(
+          makeEntry({ repo_path: repoRoot, gate_id: `gate-${i % 3}`, duration_ms: i * 10 }),
+          repoRoot,
+        );
+      }
+
+      const tail = readTailEntries(5, repoRoot);
+      expect(tail.length).toBe(5);
+      expect(tail[0].duration_ms).toBe(260);
+      expect(tail[4].duration_ms).toBe(300);
+    });
+
+    it('should return empty array when log does not exist', () => {
+      const result = readTailEntries(10, join(TEST_DIR, 'empty-project'));
+      expect(result).toEqual([]);
+    });
+
+    it('should default to 20 entries', () => {
+      const repoRoot = join(TEST_DIR, 'default-tail');
+      for (let i = 0; i < 50; i++) {
+        appendAuditEntry(makeEntry({ repo_path: repoRoot, duration_ms: i }), repoRoot);
+      }
+      const tail = readTailEntries(undefined, repoRoot);
+      expect(tail.length).toBe(20);
+    });
+
+    it('should skip malformed JSON lines', () => {
+      const repoRoot = join(TEST_DIR, 'malformed-tail');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(
+        join(logDir, 'audit.jsonl'),
+        `not-json\n${JSON.stringify(makeEntry({ repo_path: repoRoot, gate_id: 'gate-valid' }))}\n`,
+        'utf8',
+      );
+      const tail = readTailEntries(10, repoRoot);
+      expect(tail.length).toBe(1);
+      expect(tail[0].gate_id).toBe('gate-valid');
+    });
+
+    it('should return empty array for empty log file', () => {
+      const repoRoot = join(TEST_DIR, 'empty-log');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(join(logDir, 'audit.jsonl'), '', 'utf8');
+      expect(readTailEntries(10, repoRoot)).toEqual([]);
+    });
+  });
+
+  describe('computeStats', () => {
+    it('should aggregate per-gate statistics correctly', () => {
+      const repoRoot = join(TEST_DIR, 'stats-test');
+      // gate-1: 3 runs, 2 passed, durations 100+200+300
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1', passed: true, duration_ms: 100 }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1', passed: true, duration_ms: 200 }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1', passed: false, duration_ms: 300 }), repoRoot);
+      // gate-2: 2 runs, 2 passed
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-2', passed: true, duration_ms: 50 }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-2', passed: true, duration_ms: 150 }), repoRoot);
+
+      const stats = computeStats(repoRoot);
+      expect(stats.length).toBe(2);
+
+      const g1 = stats.find(s => s.gate_id === 'gate-1')!;
+      expect(g1.pass_pct).toBe('66.7%');
+      expect(g1.avg_ms).toBe(200);
+
+      const g2 = stats.find(s => s.gate_id === 'gate-2')!;
+      expect(g2.pass_pct).toBe('100.0%');
+      expect(g2.avg_ms).toBe(100);
+    });
+
+    it('should return empty array when no log exists', () => {
+      const result = computeStats(join(TEST_DIR, 'no-stats'));
+      expect(result).toEqual([]);
+    });
+
+    it('should calculate avg_issues correctly', () => {
+      const repoRoot = join(TEST_DIR, 'issues-test');
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-3', issues_found: 5 }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-3', issues_found: 3 }), repoRoot);
+      appendAuditEntry(makeEntry({ repo_path: repoRoot, gate_id: 'gate-3', issues_found: 0 }), repoRoot);
+
+      const stats = computeStats(repoRoot);
+      expect(stats[0].avg_issues).toBe(2.67);
+    });
+
+    it('should return empty array for empty stats log', () => {
+      const repoRoot = join(TEST_DIR, 'empty-stats-log');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(join(logDir, 'audit.jsonl'), '', 'utf8');
+      expect(computeStats(repoRoot)).toEqual([]);
+    });
+
+    it('should skip malformed lines during stats aggregation', () => {
+      const repoRoot = join(TEST_DIR, 'malformed-stats');
+      const logDir = join(repoRoot, '.xp-gate');
+      mkdirSync(logDir, { recursive: true });
+      writeFileSync(
+        join(logDir, 'audit.jsonl'),
+        `${JSON.stringify(makeEntry({ repo_path: repoRoot, gate_id: 'gate-1' }))}\n{bad json}\n`,
+        'utf8',
+      );
+      const stats = computeStats(repoRoot);
+      expect(stats).toHaveLength(1);
+      expect(stats[0].gate_id).toBe('gate-1');
+    });
+  });
+
+  describe('CLI helpers', () => {
+    it('should parse CLI options and skip dangling flags', () => {
+      expect(parseCliOptions(['--gate-id', 'gate-1', '--passed', 'true', '--dangling'])).toEqual({
+        'gate-id': 'gate-1',
+        passed: 'true',
+      });
+    });
+
+    it('should return a commit hash string or unknown', () => {
+      expect(typeof getCommitHash()).toBe('string');
+    });
+  });
+
+  describe('rotateIfNeeded', () => {
+    it('should not rotate when file is under 10MB', () => {
+      const logPath = join(TEST_DIR, 'small-log', '.xp-gate', 'audit.jsonl');
+      mkdirSync(join(TEST_DIR, 'small-log', '.xp-gate'), { recursive: true });
+      writeFileSync(logPath, 'small content', 'utf8');
+
+      rotateIfNeeded(logPath);
+      expect(existsSync(logPath)).toBe(true);
+      expect(existsSync(`${logPath}.1`)).toBe(false);
+    });
+
+    it('should rotate when file exceeds 10MB', () => {
+      const logPath = join(TEST_DIR, 'big-log', '.xp-gate', 'audit.jsonl');
+      mkdirSync(join(TEST_DIR, 'big-log', '.xp-gate'), { recursive: true });
+
+      // Write > 10MB of data
+      const bigContent = 'x'.repeat(10 * 1024 * 1024 + 100);
+      writeFileSync(logPath, bigContent, 'utf8');
+
+      rotateIfNeeded(logPath);
+      expect(existsSync(`${logPath}.1`)).toBe(true);
+    });
+
+    it('should keep max 3 archives', () => {
+      const logPath = join(TEST_DIR, 'archive-test', '.xp-gate', 'audit.jsonl');
+      mkdirSync(join(TEST_DIR, 'archive-test', '.xp-gate'), { recursive: true });
+      const bigContent = 'x'.repeat(10 * 1024 * 1024 + 100);
+
+      // Create 3 rotations
+      for (let i = 0; i < 3; i++) {
+        writeFileSync(logPath, `${bigContent} round ${i}`, 'utf8');
+        rotateIfNeeded(logPath);
+      }
+
+      // Should have .1, .2, .3 but NOT .4
+      expect(existsSync(`${logPath}.1`)).toBe(true);
+      expect(existsSync(`${logPath}.2`)).toBe(true);
+      expect(existsSync(`${logPath}.3`)).toBe(true);
+      expect(existsSync(`${logPath}.4`)).toBe(false);
+    });
+  });
+});

package/lib/__tests__/ui-detector.test.ts

@@ -114,7 +114,63 @@ describe('ui-detector', () => {
     it('should handle git command failure gracefully', async () => {
       mockExecSync.mockImplementation(() => {
         throw new Error('git not available');
-      });
+  describe('collectUiMatches and detectUiSprint', () => {
+    it('should detect UI files in components directory', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.tsx', 'src/utils/helper.ts']);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toEqual(['src/components/Button.tsx']);
+      expect(result.matchedRules.length).toBeGreaterThan(0);
+    });
+
+    it('should exclude test files from matching', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.test.tsx']);
+      expect(result.isUiSprint).toBe(false);
+      expect(result.matchedFiles).toEqual([]);
+    });
+
+    it('should exclude coverage directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['coverage/components/Coverage.tsx']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should handle empty file list', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([]);
+      expect(result.isUiSprint).toBe(false);
+      expect(result.matchedFiles).toEqual([]);
+    });
+
+    it('should collect multiple UI files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Header.tsx',
+        'src/utils/api.ts',
+        'views/styles/app.css',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toHaveLength(2);
+    });
+
+    it('should aggregate unique rules across files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Button.tsx',
+        'src/components/Card.tsx',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('should respect .ui-gate-ignore patterns', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const withoutIgnore = collectUiMatches(['legacy/components/Old.tsx']);
+      expect(withoutIgnore.isUiSprint).toBe(true);
+    });
+  });
+});
       const { detectUiSprint } = await import('../ui-detector');
       const result = detectUiSprint();
       expect(result.isUiSprint).toBe(false);
@@ -197,4 +253,59 @@ describe('ui-detector', () => {
       expect(rules).toContain('style-.css');
     });
   });
+
+  describe('collectUiMatches', () => {
+    it('should detect UI files in components directory', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/components/Button.tsx', 'src/utils/helper.ts']);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toEqual(['src/components/Button.tsx']);
+      expect(result.matchedRules.length).toBeGreaterThan(0);
+    });
+
+    it('should exclude __tests__ directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/__tests__/Button.test.tsx']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should exclude src/__snapshots__ directory files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches(['src/__snapshots__/Button.test.tsx.snap']);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should handle empty file list', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([]);
+      expect(result.isUiSprint).toBe(false);
+    });
+
+    it('should collect multiple UI files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Header.tsx',
+        'src/utils/api.ts',
+        'views/styles/app.css',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles).toHaveLength(2);
+    });
+
+    it('should collect unique rules across files', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const result = collectUiMatches([
+        'src/components/Button.tsx',
+        'src/components/Card.tsx',
+      ]);
+      expect(result.isUiSprint).toBe(true);
+      expect(result.matchedFiles.length).toBeGreaterThan(0);
+    });
+
+    it('should respect .ui-gate-ignore patterns', async () => {
+      const { collectUiMatches } = await import('../ui-detector');
+      const withoutIgnore = collectUiMatches(['legacy/components/Old.tsx']);
+      expect(withoutIgnore.isUiSprint).toBe(true);
+    });
+  });
 });