config-audit/tests/scanners/hook-validator.test.mjs

import { describe, it, beforeEach, afterEach } from 'node:test';
import assert from 'node:assert/strict';
import { resolve, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { mkdtemp, mkdir, writeFile, rm } from 'node:fs/promises';
import { tmpdir } from 'node:os';
import { resetCounter } from '../../scanners/lib/output.mjs';
import { discoverConfigFiles } from '../../scanners/lib/file-discovery.mjs';
import { scan } from '../../scanners/hook-validator.mjs';

const __dirname = fileURLToPath(new URL('.', import.meta.url));
const FIXTURES = resolve(__dirname, '../fixtures');

describe('HKV scanner — healthy project', () => {
  let result;
  beforeEach(async () => {
    resetCounter();
    const discovery = await discoverConfigFiles(resolve(FIXTURES, 'healthy-project'));
    result = await scan(resolve(FIXTURES, 'healthy-project'), discovery);
  });

  it('returns status ok', () => {
    assert.strictEqual(result.status, 'ok');
  });

  it('has scanner prefix HKV', () => {
    assert.strictEqual(result.scanner, 'HKV');
  });

  it('finds no critical or high issues', () => {
    const serious = result.findings.filter(f => f.severity === 'critical' || f.severity === 'high');
    assert.strictEqual(serious.length, 0, `Found: ${serious.map(f => f.title).join(', ')}`);
  });

  it('all finding IDs match CA-HKV-NNN', () => {
    for (const f of result.findings) {
      assert.match(f.id, /^CA-HKV-\d{3}$/);
    }
  });
});

describe('HKV scanner — broken project', () => {
  let result;
  beforeEach(async () => {
    resetCounter();
    const discovery = await discoverConfigFiles(resolve(FIXTURES, 'broken-project'));
    result = await scan(resolve(FIXTURES, 'broken-project'), discovery);
  });

  it('detects unknown hook event', () => {
    // CA-HKV-001 in broken-project, evidence='InvalidEvent'.
    const found = result.findings.some(f => f.scanner === 'HKV' && /InvalidEvent/.test(f.evidence || ''));
    assert.ok(found, 'Should detect InvalidEvent');
  });

  it('detects object matcher (should be string)', () => {
    // CA-HKV-002 in broken-project, evidence contains the object matcher snippet.
    const found = result.findings.some(f => f.scanner === 'HKV' && f.id === 'CA-HKV-002');
    assert.ok(found, 'Should detect nested object matcher');
  });

  it('detects invalid handler type', () => {
    // CA-HKV-003 in broken-project, evidence='type: "invalid_type"'.
    const found = result.findings.some(f => f.scanner === 'HKV' && /invalid_type/.test(f.evidence || ''));
    assert.ok(found, 'Should detect invalid_type');
  });

  it('detects timeout below minimum', () => {
    // CA-HKV-004 in broken-project, evidence='timeout: 500'.
    const found = result.findings.some(f => f.scanner === 'HKV' && /timeout:\s*500/.test(f.evidence || ''));
    assert.ok(found, 'Should detect timeout of 500ms');
  });

  it('marks unknown event as high severity', () => {
    // CA-HKV-001 in broken-project = unknown-event finding (evidence='InvalidEvent').
    const f = result.findings.find(x => x.scanner === 'HKV' && /InvalidEvent/.test(x.evidence || ''));
    assert.strictEqual(f?.severity, 'high');
  });
});

describe('HKV scanner — verbose hook output (v5 M5)', () => {
  it('flags hook script with > 50 console.log/stdout.write lines (low)', async () => {
    resetCounter();
    const path = resolve(FIXTURES, 'hooks-verbose');
    const discovery = await discoverConfigFiles(path);
    const result = await scan(path, discovery);
    // Verbose-hook finding in hooks-verbose; evidence carries the line-count metric.
    const f = result.findings.find(x => x.scanner === 'HKV' && /console_log_or_stdout_lines=/.test(x.evidence || ''));
    assert.ok(f, `expected verbose-hook finding; got: ${result.findings.map(x => x.title).join(' | ')}`);
    assert.equal(f.severity, 'low', `expected low, got ${f.severity}`);
    assert.match(f.evidence || '', /console_log_or_stdout_lines=6\d/);
  });

  it('does NOT flag a quiet hook script', async () => {
    resetCounter();
    const path = resolve(FIXTURES, 'hooks-quiet');
    const discovery = await discoverConfigFiles(path);
    const result = await scan(path, discovery);
    const f = result.findings.find(x => x.scanner === 'HKV' && /console_log_or_stdout_lines=/.test(x.evidence || ''));
    assert.equal(f, undefined, `expected no verbose-hook finding; got id=${f?.id}`);
  });
});

describe('HKV scanner — additionalContext injection advisory (v5.10 B5)', () => {
  it('flags a hook that injects unfiltered command output into additionalContext (info advisory)', async () => {
    resetCounter();
    const path = resolve(FIXTURES, 'hooks-additional-context');
    const discovery = await discoverConfigFiles(path);
    const result = await scan(path, discovery);
    const f = result.findings.find(
      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || ''),
    );
    assert.ok(f, `expected additionalContext advisory; got: ${result.findings.map(x => x.title).join(' | ')}`);
    assert.equal(f.severity, 'info', `expected info (advisory), got ${f.severity}`);
    // The chatty.sh script (SessionStart) is the one flagged, not filtered.sh.
    assert.match(f.file || '', /chatty\.sh$/);
    // Precision caveat must be disclosed in the description (low-precision advisory).
    assert.match(f.description || '', /every time|enters Claude's context|advisory/i);
  });

  it('does NOT flag the filtered (grep|head) sibling hook', async () => {
    resetCounter();
    const path = resolve(FIXTURES, 'hooks-additional-context');
    const discovery = await discoverConfigFiles(path);
    const result = await scan(path, discovery);
    const filtered = result.findings.find(
      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || '') && /filtered\.sh$/.test(x.file || ''),
    );
    assert.equal(filtered, undefined, `filtered.sh should not be flagged; got id=${filtered?.id}`);
  });

  it('does NOT flag a quiet hook with no additionalContext', async () => {
    resetCounter();
    const path = resolve(FIXTURES, 'hooks-quiet');
    const discovery = await discoverConfigFiles(path);
    const result = await scan(path, discovery);
    const f = result.findings.find(
      x => x.scanner === 'HKV' && /additional_context_unfiltered=true/.test(x.evidence || ''),
    );
    assert.equal(f, undefined, `expected no additionalContext advisory; got id=${f?.id}`);
  });
});

describe('HKV scanner — CC 2.1.152 MessageDisplay event (Batch 1 false-positive fix)', () => {
  // The pre-write path-guard blocks committing settings.json/hooks.json, so
  // this suite materializes a hermetic temp fixture at runtime.
  let tmpRoot;
  let result;

  const VALID_NEW = ['MessageDisplay'];

  beforeEach(async () => {
    resetCounter();
    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-hkv-events-'));
    await mkdir(join(tmpRoot, '.claude'), { recursive: true });
    const settings = {
      hooks: {
        // 'echo …' commands skip the script-existence check (extractScriptPath
        // only resolves bash/node/sh), isolating the event-name validation.
        MessageDisplay: [{ hooks: [{ type: 'command', command: 'echo display' }] }],
      },
    };
    await writeFile(
      join(tmpRoot, '.claude', 'settings.json'),
      JSON.stringify(settings, null, 2) + '\n',
      'utf8',
    );
    const discovery = await discoverConfigFiles(tmpRoot);
    result = await scan(tmpRoot, discovery);
  });

  afterEach(async () => {
    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
  });

  for (const event of VALID_NEW) {
    it(`does NOT flag "${event}" as an unknown hook event`, () => {
      const unknown = result.findings.find(f =>
        f.title === 'Unknown hook event' && f.evidence === event);
      assert.equal(unknown, undefined, `${event} should be in VALID_EVENTS`);
    });
  }

  it('produces zero findings for a valid MessageDisplay config', () => {
    assert.equal(result.findings.length, 0,
      `expected clean scan; got: ${result.findings.map(f => `${f.title}:${f.evidence || ''}`).join(' | ')}`);
  });
});

describe('HKV scanner — post-session is NOT a settings.json hook event (Verifiseringsplikt)', () => {
  // Verified 2026-06-20 against hooks.md + the 2.1.169 changelog: the
  // `post-session` hook in that changelog is a SELF-HOSTED-RUNNER
  // workspace-lifecycle hook, NOT a settings.json hook event. It is absent
  // from hooks.md's (all-PascalCase) event list, so a settings.json hook
  // keyed on it never fires and MUST be flagged.
  let tmpRoot;
  let result;

  beforeEach(async () => {
    resetCounter();
    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-hkv-postsession-'));
    await mkdir(join(tmpRoot, '.claude'), { recursive: true });
    const settings = {
      hooks: {
        'post-session': [{ hooks: [{ type: 'command', command: 'echo bye' }] }],
      },
    };
    await writeFile(
      join(tmpRoot, '.claude', 'settings.json'),
      JSON.stringify(settings, null, 2) + '\n',
      'utf8',
    );
    const discovery = await discoverConfigFiles(tmpRoot);
    result = await scan(tmpRoot, discovery);
  });

  afterEach(async () => {
    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
  });

  it('flags "post-session" as an unknown hook event', () => {
    const f = result.findings.find(x =>
      x.title === 'Unknown hook event' && x.evidence === 'post-session');
    assert.ok(f, 'post-session must be flagged as an unknown settings.json hook event');
  });
});

describe('HKV scanner — Setup/UserPromptExpansion/PostToolBatch events (Batch 2 false-positive fix)', () => {
  // Three more events verified live against code.claude.com/docs/en/hooks.md
  // (2026-06-19): Setup (session-level), UserPromptExpansion (per-turn),
  // PostToolBatch (agentic loop). Same hermetic temp-fixture pattern — the
  // path-guard blocks committing settings.json/hooks.json fixtures.
  let tmpRoot;
  let result;

  const NEW_EVENTS = ['Setup', 'UserPromptExpansion', 'PostToolBatch'];

  beforeEach(async () => {
    resetCounter();
    tmpRoot = await mkdtemp(join(tmpdir(), 'ca-hkv-events2-'));
    await mkdir(join(tmpRoot, '.claude'), { recursive: true });
    const settings = {
      hooks: {
        // 'echo …' commands skip the script-existence check, isolating
        // event-name validation.
        Setup: [{ hooks: [{ type: 'command', command: 'echo setup' }] }],
        UserPromptExpansion: [{ hooks: [{ type: 'command', command: 'echo expand' }] }],
        PostToolBatch: [{ hooks: [{ type: 'command', command: 'echo batch' }] }],
      },
    };
    await writeFile(
      join(tmpRoot, '.claude', 'settings.json'),
      JSON.stringify(settings, null, 2) + '\n',
      'utf8',
    );
    const discovery = await discoverConfigFiles(tmpRoot);
    result = await scan(tmpRoot, discovery);
  });

  afterEach(async () => {
    if (tmpRoot) await rm(tmpRoot, { recursive: true, force: true });
  });

  for (const event of NEW_EVENTS) {
    it(`does NOT flag "${event}" as an unknown hook event`, () => {
      const unknown = result.findings.find(f =>
        f.title === 'Unknown hook event' && f.evidence === event);
      assert.equal(unknown, undefined, `${event} should be in VALID_EVENTS`);
    });
  }

  it('produces zero findings for a valid Setup + UserPromptExpansion + PostToolBatch config', () => {
    assert.equal(result.findings.length, 0,
      `expected clean scan; got: ${result.findings.map(f => `${f.title}:${f.evidence || ''}`).join(' | ')}`);
  });
});

describe('HKV scanner — empty project', () => {
  let result;
  beforeEach(async () => {
    resetCounter();
    const discovery = await discoverConfigFiles(resolve(FIXTURES, 'empty-project'));
    result = await scan(resolve(FIXTURES, 'empty-project'), discovery);
  });

  it('returns status ok with 0 findings', () => {
    assert.strictEqual(result.status, 'ok');
    assert.strictEqual(result.findings.length, 0);
  });
});