@1aboveio/skills 0.0.0-stage → 1.0.0

package/skills/engineering/test-quality/scripts/lint-tests.test.mjs

@@ -0,0 +1,591 @@
+// Tests for the lint-tests engine (pure core, no filesystem/git).
+import { test } from 'node:test'
+import assert from 'node:assert/strict'
+
+import { scanText, scanDiff, selectRules, RULES, ALL_RULES, isTestFile, stripComment, runCli, findDuplicateFiles, splitShares } from './lint-tests.mjs'
+import { resolveMockPolicy } from './mock-policy-config.mjs'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { execSync } from 'node:child_process'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+
+const ALL_IDS = [
+  'conditional-skip', 'config-read', 'count-pin', 'duplicate-file', 'mock-internal-seam', 'no-empty-test',
+  'no-fixed-timeout', 'no-skip', 'no-swallowed-assertion', 'redundant-matcher', 'text-oracle', 'utility-class',
+]
+
+test('default rules = every rule, gates and leads', () => {
+  assert.deepEqual(selectRules().map((r) => r.id).sort(), ALL_IDS)
+  assert.equal(RULES.length, 4) // the four authoring gates; the rest live in ALL_RULES
+})
+
+test('every rule names its principle and a gate or lead severity', () => {
+  for (const rule of ALL_RULES) {
+    assert.ok([1, 2, 3, 4, 5, 6, 7].includes(rule.principle), rule.id)
+    assert.ok(['gate', 'lead'].includes(rule.severity), rule.id)
+  }
+  const gates = ALL_RULES.filter((r) => r.severity === 'gate').map((r) => r.id).sort()
+  assert.deepEqual(gates, ['mock-internal-seam', 'no-empty-test', 'no-fixed-timeout', 'no-skip', 'no-swallowed-assertion'])
+})
+
+test('no-skip rule flags skip/only/xfail (carries rule + kind)', () => {
+  // non-empty bodies so this isolates no-skip from the no-empty-test rule
+  const f = scanText('a.spec.ts', 'test.skip("x", () => { go() })\ndescribe.only("y", () => { go() })')
+  assert.deepEqual(f.map((x) => [x.rule, x.kind]), [['no-skip', 'skip'], ['no-skip', 'only']])
+})
+
+test('no-fixed-timeout flags waitForTimeout / numeric cy.wait / time.sleep', () => {
+  const f = scanText('a.spec.ts', [
+    'await page.waitForTimeout(500)',
+    "cy.wait(1000)",
+    'time.sleep(2)',
+  ].join('\n'))
+  assert.deepEqual(f.map((x) => x.kind), ['waitForTimeout', 'cy.wait', 'time.sleep'])
+  assert.ok(f.every((x) => x.rule === 'no-fixed-timeout'))
+})
+
+test('no-fixed-timeout does NOT flag an aliased cy.wait (not a fixed sleep)', () => {
+  assert.deepEqual(scanText('a.spec.ts', "cy.wait('@getUser')"), [])
+})
+
+test('--rules selection runs only the chosen rule', () => {
+  const text = 'test.skip("x", () => {})\nawait page.waitForTimeout(500)'
+  const onlySkip = scanText('a.spec.ts', text, ['no-skip'])
+  assert.deepEqual(onlySkip.map((x) => x.rule), ['no-skip'])
+  const onlyTimeout = scanText('a.spec.ts', text, ['no-fixed-timeout'])
+  assert.deepEqual(onlyTimeout.map((x) => x.rule), ['no-fixed-timeout'])
+})
+
+test('a single line can trip two different rules', () => {
+  // contrived but valid: a skipped test on the same line as a timeout call
+  const f = scanText('a.spec.ts', 'test.skip("x", async () => { await page.waitForTimeout(1) })')
+  assert.deepEqual(f.map((x) => x.rule).sort(), ['no-fixed-timeout', 'no-skip'])
+})
+
+test('scanDiff flags only ADDED violations in test files, with new-file line numbers', () => {
+  const diff = [
+    '+++ b/e2e/x.spec.ts',
+    '@@ -10,2 +10,3 @@',
+    ' context',
+    '+await page.waitForTimeout(300)',
+    '-old line',
+  ].join('\n')
+  const f = scanDiff(diff)
+  assert.equal(f.length, 1)
+  assert.equal(f[0].rule, 'no-fixed-timeout')
+  assert.equal(f[0].line, 11)
+})
+
+test('scanDiff ignores violations added to NON-test files', () => {
+  const diff = ['+++ b/src/util.ts', '@@ -1,1 +1,2 @@', '+await sleepThing.waitForTimeout(5)'].join('\n')
+  assert.deepEqual(scanDiff(diff), [])
+})
+
+test('isTestFile ignores data files under a tests directory', () => {
+  assert.equal(isTestFile('backend/tests/data/cybs_a100.parquet'), false)
+  assert.equal(isTestFile('tests/fixtures/sample.json'), false)
+  assert.equal(isTestFile('backend/internal/service/user_test.go'), true)
+})
+
+test('isTestFile is shared and recognizes spec/test paths, rejects app code', () => {
+  for (const p of ['e2e/a.spec.ts', 'src/x.test.tsx', 'tests/e2e/b.spec.js', 'api/test_views.py', 'pkg/foo_test.py', '__tests__/c.ts']) {
+    assert.equal(isTestFile(p), true, p)
+  }
+  for (const p of ['src/app/page.tsx', 'lib/util.ts', 'README.md']) {
+    assert.equal(isTestFile(p), false, p)
+  }
+})
+
+// ---- no-skip rule: richer cases (folded in from the former skip-lint suite) ----
+
+test('conditional runtime skips are a lead, declared skipped tests a gate', () => {
+  const f = scanText('a.spec.ts', 'if (!user) test.skip();\ntest.skip(true, "https://github.com/o/r/issues/1")\ntest.skip(\'broken\', () => {})', ['no-skip', 'conditional-skip'])
+  assert.deepEqual(f.map((x) => `${x.rule}:${x.line}`), ['conditional-skip:1', 'conditional-skip:2', 'no-skip:3'])
+})
+
+test('Python: unconditional skip is a gate; skipif, runtime skip, importorskip and xfail are leads', () => {
+  const text = [
+    '@pytest.mark.skip(reason="x")',
+    '@pytest.mark.skipif(sys.platform == "win32", reason="posix only")',
+    '@unittest.skip("x")',
+    '    pytest.skip("x")',
+    '@pytest.mark.xfail(strict=True, reason="bug #12")',
+    'np = pytest.importorskip("numpy")',
+    '@unittest.skipIf(sys.version_info < (3, 11), "needs 3.11")',
+  ].join('\n')
+  assert.deepEqual(scanText('test_x.py', text, ['no-skip', 'conditional-skip']).map((f) => `${f.rule}/${f.kind}`), [
+    'no-skip/skip', 'conditional-skip/skipif', 'no-skip/skip', 'conditional-skip/runtime-skip',
+    'conditional-skip/xfail', 'conditional-skip/runtime-skip', 'conditional-skip/skipif',
+  ])
+})
+
+test('Go and node runtime skips are leads; test.todo is a gate', () => {
+  const text = ['\tif testing.Short() { t.Skip("slow") }', "  t.skip('needs docker')", "test.todo('handles refunds')"].join('\n')
+  assert.deepEqual(scanText('x_test.go', text, ['no-skip', 'conditional-skip']).map((f) => `${f.rule}:${f.line}`),
+    ['conditional-skip:1', 'conditional-skip:2', 'no-skip:3'])
+})
+
+test('no-empty-test flags a Python test whose body is only pass or ...', () => {
+  const text = ['def test_refund():\n    pass', 'def test_a(): pass', 'async def test_b() -> None: ...', 'def test_c(): assert f() == 1'].join('\n')
+  assert.deepEqual(scanText('test_x.py', text, ['no-empty-test']).map((f) => f.line), [3, 4])
+})
+
+test('no-fixed-timeout flags Go time.Sleep', () => {
+  assert.equal(scanText('a_test.go', '\ttime.Sleep(100 * time.Millisecond)', ['no-fixed-timeout']).length, 1)
+})
+
+test('no-skip does not flag a commented-out or doc mention', () => {
+  const text = [
+    '// never use test.skip() — banned',
+    '# doc: test.skip is not allowed',
+    'const xs = items.skip(2) // unrelated array method',
+  ].join('\n')
+  assert.deepEqual(scanText('a.spec.ts', text), [])
+})
+
+test('no-skip does not flag .only/.skip method calls that are not test forms', () => {
+  assert.deepEqual(scanText('a.spec.ts', 'arr.skip(1); foo.only;'), [])
+})
+
+// ---- no-empty-test rule: the decidable floor of the Missing-Assertion smell ----
+
+test('no-empty-test flags empty arrow/function/playwright/.each/.concurrent bodies', () => {
+  const cases = [
+    "test('a', () => {})",
+    'it("b", async () => {})',
+    "test('c', function () {})",
+    "test('d', async ({ page }) => {})",
+    "it.each([1,2])('e', () => {})",
+    "test.concurrent('f', () => {})",
+  ]
+  for (const c of cases) {
+    const f = scanText('a.spec.ts', c, ['no-empty-test'])
+    assert.equal(f.length, 1, `should flag: ${c}`)
+    assert.equal(f[0].kind, 'empty-test')
+  }
+})
+
+test('no-empty-test does NOT flag a test that has a body', () => {
+  const cases = [
+    "test('a', () => { expect(1).toBe(1) })",
+    "it('b', async () => { await verifyDashboard(page) })", // asserts via helper — not empty, not flagged
+    "test('c', () => { doThing() })",
+  ]
+  for (const c of cases) assert.deepEqual(scanText('a.spec.ts', c, ['no-empty-test']), [], c)
+})
+
+test('no-empty-test does NOT flag describe/suite, look-alike identifiers, or 1-arg calls', () => {
+  const text = [
+    "describe('group', () => {})",   // empty suite is not a fake test
+    "emit('evt', () => {})",          // 'it' inside emit — word boundary protects
+    "submit('x', () => {})",          // 'it' inside submit
+    "it('pending')",                  // no callback — not an empty-bodied test
+    'const t = () => {}',             // not a test call
+  ].join('\n')
+  assert.deepEqual(scanText('a.spec.ts', text, ['no-empty-test']), [])
+})
+
+test('no-empty-test leaves a multi-line empty body to the review lead (no false block)', () => {
+  // The opening line has no closing brace, so the single-line gate does not fire.
+  assert.deepEqual(scanText('a.spec.ts', "it('x', () => {\n})", ['no-empty-test']), [])
+})
+
+// ---- no-swallowed-assertion rule: the vacuous-green form behind #237 ----
+
+test('no-swallowed-assertion flags a matcher whose rejection is eaten by .catch()', () => {
+  const cases = [
+    "await expect(page.locator('#cta')).not.toBeVisible().catch(() => {})", // the #237 form
+    "await expect(btn).toHaveText('Sign in').catch(() => null)",
+    'await expect(x).toBe(1).catch(() => {})',
+  ]
+  for (const c of cases) {
+    const f = scanText('a.spec.ts', c, ['no-swallowed-assertion'])
+    assert.equal(f.length, 1, `should flag: ${c}`)
+    assert.equal(f[0].kind, 'swallowed-catch')
+    assert.equal(f[0].rule, 'no-swallowed-assertion')
+  }
+})
+
+test('no-swallowed-assertion does NOT flag a legitimate assertion or an unrelated .catch', () => {
+  const cases = [
+    "await expect(page.locator('#cta')).toBeVisible()",              // real assertion, no swallow
+    "const v = await fetchThing().catch(() => fallback)",            // .catch on setup, not a matcher
+    "promise.then(ok).catch(handleError)",                           // plain promise handling
+  ]
+  for (const c of cases) assert.deepEqual(scanText('a.spec.ts', c, ['no-swallowed-assertion']), [], c)
+})
+
+test('no-swallowed-assertion is a default gate and flags it in a PR diff', () => {
+  const diff = [
+    '+++ b/e2e/login.sweep.spec.ts',
+    '@@ -1,1 +1,2 @@',
+    ' context',
+    "+await expect(page.locator('#cta')).not.toBeVisible().catch(() => {})",
+  ].join('\n')
+  const f = scanDiff(diff) // default rule set, no explicit --rules
+  assert.equal(f.length, 1)
+  assert.equal(f[0].rule, 'no-swallowed-assertion')
+})
+
+test('stripComment removes // and # trailing comments', () => {
+  assert.equal(stripComment('code // test.skip()').includes('test.skip'), false)
+  assert.equal(stripComment('code  # pytest.skip').includes('pytest.skip'), false)
+})
+
+test('scanDiff ignores a pre-existing skip on an unchanged (context) line', () => {
+  const diff = ['+++ b/e2e/x.spec.ts', '@@ -1,2 +1,3 @@', ' test.skip("inherited", () => {})', '+test("added clean", () => { ok() })'].join('\n')
+  assert.deepEqual(scanDiff(diff), [])
+})
+
+// ---- mock-internal-seam rule: the zero-tolerance, default-on over-mock gate ----
+
+const SEAM_CTX = { policy: resolveMockPolicy({ firstPartyPackages: ['@agentier/'] }) }
+
+test('mock-internal-seam is default-on: in ALL_RULES and in the default gate set', () => {
+  assert.ok(ALL_RULES.some((r) => r.id === 'mock-internal-seam'))
+  // zero-tolerance: it runs by default, no opt-in needed
+  assert.ok(selectRules().some((r) => r.id === 'mock-internal-seam'))
+})
+
+test('mock-internal-seam cannot be opted out via config (enabled:false is ignored)', () => {
+  // the gate is defaultOn:true; selectRules does not consult policy.enabled
+  assert.ok(selectRules().some((r) => r.id === 'mock-internal-seam'))
+  // and naming a subset still resolves it from the registry
+  assert.deepEqual(selectRules(['mock-internal-seam']).map((r) => r.id), ['mock-internal-seam'])
+})
+
+test('mock-internal-seam flags a first-party alias mock (the studio incident)', () => {
+  const f = scanText('a.test.ts', "vi." + "mock('@/lib/org-allowlist-client')", ['mock-internal-seam'], SEAM_CTX)
+  assert.equal(f.length, 1)
+  assert.equal(f[0].rule, 'mock-internal-seam')
+  assert.equal(f[0].detail, '@/lib/org-allowlist-client')
+})
+
+test('mock-internal-seam exempts stdlib and third-party packages', () => {
+  const text = ["vi.mock('node:fs')", "jest.mock('react')", "vi.mock('@playwright/test')"].join('\n')
+  assert.deepEqual(scanText('a.test.ts', text, ['mock-internal-seam'], SEAM_CTX), [])
+})
+
+test('mock-internal-seam ignores an inline @mock-ok comment (no waivers)', () => {
+  const text = "vi." + "mock('@/lib/cp') // @mock-ok: covered by cp.real.test.ts"
+  const f = scanText('a.test.ts', text, ['mock-internal-seam'], SEAM_CTX)
+  assert.equal(f.length, 1) // still flagged — zero-tolerance, no escape hatch
+  assert.equal(f[0].detail, '@/lib/cp')
+})
+
+test('mock-internal-seam flags a declared first-party workspace package', () => {
+  const f = scanText('a.test.ts', "vi.mock('@agentier/shared')", ['mock-internal-seam'], SEAM_CTX)
+  assert.equal(f.length, 1)
+  assert.equal(f[0].detail, '@agentier/shared')
+})
+
+test('mock-internal-seam fires with NO ctx policy (never silently inert; @/ defaults apply)', () => {
+  // zero-tolerance: omitting config must not disable the gate — it falls back
+  // to DEFAULT_MOCK_POLICY, which flags conventional @/ first-party mocks.
+  const f = scanText('a.test.ts', "vi." + "mock('@/lib/x')", ['mock-internal-seam'])
+  assert.equal(f.length, 1)
+  assert.equal(f[0].detail, '@/lib/x')
+})
+
+test('mock-internal-seam flags an ADDED first-party mock in a PR diff (PR lane)', () => {
+  const diff = ['+++ b/src/__tests__/x.test.ts', '@@ -1,1 +1,2 @@', " import x", "+vi." + "mock('@/lib/cp')"].join('\n')
+  const f = scanDiff(diff, ['mock-internal-seam'], SEAM_CTX)
+  assert.equal(f.length, 1)
+  assert.equal(f[0].rule, 'mock-internal-seam')
+})
+
+test('mock-internal-seam flags an INHERITED (un-added) mock in a whole-tree scan (no grandfathering)', () => {
+  // whole-tree lane: scanText sees every line, not just diff additions, so the
+  // 781-style inherited debt is flagged until removed.
+  const f = scanText('src/__tests__/x.test.ts', "import x\nvi.mock('@/lib/cp')\n", ['mock-internal-seam'], SEAM_CTX)
+  assert.equal(f.length, 1)
+  assert.equal(f[0].detail, '@/lib/cp')
+})
+
+test('mock-internal-seam does not fire on a commented-out mock line', () => {
+  assert.deepEqual(scanText('a.test.ts', "// vi.mock('@/lib/x')", ['mock-internal-seam'], SEAM_CTX), [])
+})
+
+test('--help prints usage and exits 0 without scanning the tree', () => {
+  const lines = []
+  const orig = console.log
+  console.log = (s) => lines.push(String(s))
+  try {
+    assert.equal(runCli(['--help']), 0)
+  } finally {
+    console.log = orig
+  }
+  assert.match(lines.join('\n'), /usage: lint-tests\.mjs/)
+})
+
+// ---- test-quality rules ----
+
+// Fixture text for first-party mocks, built at runtime so repository-wide over-mock scans do not
+// read this file's own fixtures as real mocks.
+const seamMocks = (...targets) => targets.map((target) => `vi.mock('${target}')`).join('\n') + '\n'
+
+const ids = (findings) => findings.map((f) => `${f.rule}:${f.line}`)
+
+test('redundant-matcher flags a matcher after a query that already throws when missing', () => {
+  const text = [
+    "expect(screen.getByText('Saved')).toBeDefined()",
+    "expect(within(row).getByRole('button', { name: /edit/i })).toBeTruthy()",
+    "expect(wrapper.get('[data-test=title]').exists()).toBe(true)",
+  ].join('\n')
+  assert.deepEqual(ids(scanText('a.test.ts', text, ['redundant-matcher'])), ['redundant-matcher:1', 'redundant-matcher:2', 'redundant-matcher:3'])
+})
+
+test('redundant-matcher leaves queryBy, find and real matchers alone', () => {
+  const text = [
+    "expect(screen.queryByText('Saved')).toBeNull()",
+    "expect(screen.getByText('Saved')).toBeVisible()",
+    "expect(wrapper.find('.x').exists()).toBe(false)",
+    "expect(items.find((i) => i.id === 1)).toBeDefined()",
+  ].join('\n')
+  assert.deepEqual(scanText('a.test.ts', text, ['redundant-matcher']), [])
+})
+
+test('text-oracle flags a checked-in doc or source read and text-matched', () => {
+  const text = [
+    "const doc = readFileSync(join(root, 'docs/runbook.md'), 'utf8')",
+    "const src = readFileSync('src/auth.ts', 'utf8')",
+    "assert.match(doc, /Never force-publish/)",
+    "expect(src).toMatch(/expiresIn:\\s*600/)",
+  ].join('\n')
+  const found = scanText('x.test.mjs', text, ['text-oracle'])
+  assert.deepEqual(ids(found), ['text-oracle:1']) // one lead per file, at the first read
+  assert.equal(found[0].severity, 'lead')
+  assert.equal(found[0].detail, 'docs/runbook.md, src/auth.ts')
+})
+
+test('text-oracle flags a Python read_text with an `in` assertion', () => {
+  const text = [
+    "content = (ROOT / 'dags' / 'mw_dag.py').read_text()",
+    "assert 'start >> fee_settings' in content",
+  ].join('\n')
+  // the path literal on line 1 is 'mw_dag.py'
+  assert.deepEqual(ids(scanText('tests/test_dag.py', text, ['text-oracle'])), ['text-oracle:1'])
+})
+
+test('text-oracle ignores executed scripts, fixtures, written temp files and match-free reads', () => {
+  const runs = [
+    "const out = execFileSync('node', ['scripts/build.mjs'])",
+    "const cfg = readFileSync('fixtures/sample.md', 'utf8')",
+    "writeFileSync(join(tmp, 'out.md'), render(doc))",
+    "const got = readFileSync(join(tmp, 'out.md'), 'utf8')",
+    "import { run } from './run.mjs'",
+    "fs.copyFileSync(join(repoRoot, 'scripts/e2e-db.mjs'), script)",
+    "expect(got).toContain('# Title')",
+  ].join('\n')
+  assert.deepEqual(scanText('x.test.mjs', runs, ['text-oracle']), [])
+  const bound = [
+    "const cli = path.join(__dirname, '../bin/cli.ts')",
+    "const out = spawnSync('node', [cli]).stdout.toString()",
+    "const log = readFileSync(logPath, 'utf8')",
+    "expect(out).toContain('usage')",
+  ].join('\n')
+  assert.deepEqual(scanText('x.test.mjs', bound, ['text-oracle']), [])
+  const noMatch = "const src = readFileSync('src/a.ts', 'utf8')\nexpect(parse(src)).toEqual({ ok: true })"
+  assert.deepEqual(scanText('x.test.mjs', noMatch, ['text-oracle']), [])
+})
+
+test('config-read flags a parsed config file whatever the assertion', () => {
+  const text = [
+    "const config = yaml.load(fs.readFileSync(path.join(repo, '.mergify.yml'), 'utf8'))",
+    "const wf = readFileSync('.github/workflows/ci.yml', 'utf8')",
+    "const pkg = JSON.parse(readFileSync('package.json', 'utf8'))",
+    "const docker = readFileSync('Dockerfile.prod', 'utf8')",
+    "assert.equal(config.queue_rules[0].batch_size, 3)",
+  ].join('\n')
+  const found = scanText('x.test.mjs', text, ['config-read'])
+  assert.deepEqual(ids(found), ['config-read:1']) // one lead per file, at the first read
+  assert.equal(found[0].severity, 'lead')
+  assert.equal(found[0].detail, '.mergify.yml, .github/workflows/ci.yml, package.json, Dockerfile.prod')
+  const py = "with open('cloudbuild.yaml') as f:\n    steps = yaml.safe_load(f)['steps']\nassert steps[0]['name'] == 'gcr.io/cloud-builders/docker'"
+  assert.deepEqual(ids(scanText('tests/test_build.py', py, ['config-read'])), ['config-read:1'])
+})
+
+test('config-read ignores fixtures, written files, executed configs, data JSON and read-free tests', () => {
+  const text = [
+    "const cfg = readFileSync('fixtures/coverage.config.json', 'utf8')",
+    "writeFileSync(join(tmp, 'coverage.config.json'), JSON.stringify(policy))",
+    "const got = readFileSync(join(tmp, 'coverage.config.json'), 'utf8')",
+    "execFileSync('node', ['cli.mjs', '--config', 'app.config.json'])",
+    "expect(got).toEqual(cfg)",
+  ].join('\n')
+  assert.deepEqual(scanText('x.test.mjs', text, ['config-read']), [])
+  const data = "const run = JSON.parse(readFileSync(join(dir, 'run-state.json'), 'utf8'))\nconst rates = readFileSync('data/rates.json', 'utf8')\nexpect(run.status).toBe('green')"
+  assert.deepEqual(scanText('x.test.mjs', data, ['config-read']), []) // JSON as data, not config
+  const noRead = "expect(loadConfig({ env: 'prod' }).port).toBe(8080) // config.yaml defaults"
+  assert.deepEqual(scanText('x.test.mjs', noRead, ['config-read']), [])
+})
+
+test('a text-matched config file is config-read, not text-oracle', () => {
+  const text = "const wf = readFileSync('.github/workflows/ci.yml', 'utf8')\nexpect(wf).toContain('postgres:17')"
+  assert.deepEqual(ids(scanText('x.test.mjs', text, ['text-oracle', 'config-read'])), ['config-read:1'])
+})
+
+test('count-pin flags exact sizes of five or more and skips format lengths', () => {
+  const text = [
+    'expect(STATES).toHaveLength(11)',
+    'assert.equal(members.length, 19)',
+    'require.Len(t, knownLogEvents, 28)',
+    'assert len(rows) == 12',
+    'expect(digest).toHaveLength(64)',
+    'expect(list).toHaveLength(2)',
+    'expect(id.length).toBe(36)',
+  ].join('\n')
+  assert.deepEqual(ids(scanText('a.test.ts', text, ['count-pin'])), ['count-pin:1', 'count-pin:2', 'count-pin:3', 'count-pin:4'])
+})
+
+test('utility-class flags Tailwind tokens on class assertions, not semantic state classes', () => {
+  const text = [
+    "expect(el).toHaveClass('-mx-6', 'rounded-none', 'sm:shadow-sm')",
+    "expect(wrapper.classes()).toContain('h-[min(62vh,36rem)]')",
+    "expect(button.className).toContain('min-h-11')",
+    "expect(cell.classes()).toContain('health-unknown')",
+    "expect(el).toHaveClass('is-active')",
+  ].join('\n')
+  assert.deepEqual(ids(scanText('a.test.ts', text, ['utility-class'])), ['utility-class:1', 'utility-class:2', 'utility-class:3'])
+})
+
+test('findDuplicateFiles groups whitespace-identical files and ignores tiny ones', () => {
+  const body = Array.from({ length: 12 }, (_, i) => `  it('case ${i}', () => expect(f(${i})).toBe(${i}))`).join('\n')
+  const found = findDuplicateFiles([
+    { file: 'a/x.test.ts', text: body },
+    { file: 'b/x.test.ts', text: body.replace(/ {2}/g, '\t') },
+    { file: 'c/y.test.ts', text: body + '\nit("extra", () => {})' },
+    { file: 'd/tiny.test.ts', text: 'it("a", () => {})' },
+    { file: 'e/tiny.test.ts', text: 'it("a", () => {})' },
+  ])
+  assert.deepEqual(found.map((f) => [f.file, f.detail]), [['a/x.test.ts', 'b/x.test.ts'], ['b/x.test.ts', 'a/x.test.ts']])
+  assert.equal(found[0].severity, 'lead')
+})
+
+test('scanDiff runs file-level rules on the full file but reports only added lines', () => {
+  const file = [
+    "const old = readFileSync('docs/old.md', 'utf8')",
+    "const doc = readFileSync('docs/new.md', 'utf8')",
+    "expect(doc).toContain('x')",
+  ].join('\n')
+  const diff = [
+    'diff --git a/x.test.mjs b/x.test.mjs',
+    '--- a/x.test.mjs',
+    '+++ b/x.test.mjs',
+    '@@ -1,1 +1,3 @@',
+    " const old = readFileSync('docs/old.md', 'utf8')",
+    "+const doc = readFileSync('docs/new.md', 'utf8')",
+    "+expect(doc).toContain('x')",
+  ].join('\n')
+  assert.deepEqual(ids(scanDiff(diff, ['text-oracle'], undefined, () => file)), ['text-oracle:2'])
+  assert.deepEqual(scanDiff(diff, ['text-oracle']), []) // no reader → file-level rules skipped
+})
+
+test('lead findings never change the exit code; gate findings do', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'lint-tests-'))
+  const lead = join(dir, 'lead.test.ts')
+  const gate = join(dir, 'gate.test.ts')
+  writeFileSync(lead, 'expect(STATES).toHaveLength(11)\n')
+  writeFileSync(gate, seamMocks('@/lib/db'))
+  const orig = console.log
+  console.log = () => {}
+  try {
+    assert.equal(runCli(['--files', lead]), 0)
+    assert.equal(runCli(['--files', gate]), 1)
+  } finally {
+    console.log = orig
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+// ---- CLI: fail closed, working-tree diff, exclude ----
+
+function quietly(fn) {
+  const out = []
+  const [log, err] = [console.log, console.error]
+  console.log = (s) => out.push(String(s))
+  console.error = (s) => out.push(String(s))
+  try { return { code: fn(), out: out.join('\n') } } finally { console.log = log; console.error = err }
+}
+
+test('the CLI rejects unknown flags, unknown rules, and missing files with exit 2', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'lint-cli-'))
+  try {
+    assert.equal(quietly(() => runCli(['--file', 'a.test.ts'], { cwd: dir })).code, 2)
+    const typo = quietly(() => runCli(['--rules', 'cannot-fial'], { cwd: dir }))
+    assert.equal(typo.code, 2)
+    assert.match(typo.out, /unknown rule\(s\): cannot-fial/)
+    assert.equal(quietly(() => runCli(['--files', 'nope.test.ts'], { cwd: dir })).code, 2)
+    assert.equal(quietly(() => runCli(['--diff'], { cwd: dir })).code, 2)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('--exclude drops files by path segment or prefix', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'lint-cli-'))
+  try {
+    for (const d of ['src', 'dist', 'tests/fixtures']) mkdirSync(join(dir, d), { recursive: true })
+    for (const f of ['src/a.test.ts', 'dist/a.test.ts', 'tests/fixtures/b.test.ts']) writeFileSync(join(dir, f), seamMocks('@/lib/db'))
+    const all = JSON.parse(quietly(() => runCli(['--json'], { cwd: dir })).out)
+    assert.equal(all.gates, 3)
+    const some = JSON.parse(quietly(() => runCli(['--json', '--exclude', 'dist,fixtures'], { cwd: dir })).out)
+    assert.deepEqual(some.findings.map((f) => f.file), ['src/a.test.ts'])
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+test('--diff sees staged, unstaged, and untracked test files, with repo-root paths from a subdirectory', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'lint-diff-'))
+  const git = (args) => execSync(`git ${args}`, { cwd: dir, stdio: 'pipe', env: { ...process.env, GIT_AUTHOR_NAME: 't', GIT_AUTHOR_EMAIL: 't@t', GIT_COMMITTER_NAME: 't', GIT_COMMITTER_EMAIL: 't@t' } })
+  try {
+    git('init -q -b main')
+    mkdirSync(join(dir, 'pkg/tests'), { recursive: true })
+    writeFileSync(join(dir, 'pkg/tests/old.test.ts'), seamMocks('@/lib/old'))
+    git('add -A')
+    git('commit -q -m base')
+    git('checkout -q -b work')
+    writeFileSync(join(dir, 'pkg/tests/old.test.ts'), seamMocks('@/lib/old', '@/lib/unstaged'))
+    writeFileSync(join(dir, 'pkg/tests/staged.test.ts'), seamMocks('@/lib/staged'))
+    git('add pkg/tests/staged.test.ts')
+    writeFileSync(join(dir, 'pkg/tests/new.test.ts'), "const doc = readFileSync('docs/a.md', 'utf8')\nexpect(doc).toContain('x')\n")
+    const res = JSON.parse(quietly(() => runCli(['--json', '--diff', 'main'], { cwd: join(dir, 'pkg') })).out)
+    assert.deepEqual(res.findings.map((f) => `${f.file}:${f.line}:${f.rule}`).sort(), [
+      'pkg/tests/new.test.ts:1:text-oracle',
+      'pkg/tests/old.test.ts:2:mock-internal-seam',
+      'pkg/tests/staged.test.ts:1:mock-internal-seam',
+    ])
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})
+
+// ---- --shares: split flagged files for parallel reviewers ----
+
+test('splitShares balances finding counts, keeps each file whole, and never makes empty shares', () => {
+  const at = (file, n) => Array.from({ length: n }, () => ({ file }))
+  const findings = [...at('a', 5), ...at('b', 3), ...at('c', 3), ...at('d', 2), ...at('e', 1)]
+  const shares = splitShares(findings, 3)
+  assert.deepEqual(shares.map((s) => s.findings), [5, 5, 4])
+  assert.deepEqual(shares.flatMap((s) => s.files).sort(), ['a', 'b', 'c', 'd', 'e'])
+  assert.equal(splitShares(at('a', 9), 4).length, 1, 'one flagged file is one share')
+  assert.deepEqual(splitShares([], 4), [])
+})
+
+test('--shares adds the split to --json output and rejects a non-positive count', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'lint-tests-'))
+  try {
+    writeFileSync(join(dir, 'a.test.ts'), 'expect(STATES).toHaveLength(11)\nexpect(X).toHaveLength(12)\n')
+    writeFileSync(join(dir, 'b.test.ts'), 'expect(Y).toHaveLength(13)\n')
+    writeFileSync(join(dir, 'clean.test.ts'), 'expect(add(1, 2)).toBe(3)\n')
+    const run = quietly(() => runCli(['--json', '--shares', '2'], { cwd: dir }))
+    assert.equal(run.code, 0)
+    assert.deepEqual(JSON.parse(run.out).shares, [{ findings: 2, files: ['a.test.ts'] }, { findings: 1, files: ['b.test.ts'] }])
+    assert.equal(JSON.parse(quietly(() => runCli(['--json'], { cwd: dir })).out).shares, undefined)
+    assert.equal(quietly(() => runCli(['--shares', '0'], { cwd: dir })).code, 2)
+    assert.equal(quietly(() => runCli(['--shares', 'x'], { cwd: dir })).code, 2)
+  } finally {
+    rmSync(dir, { recursive: true, force: true })
+  }
+})