Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

63.5 KB
Raw Blame
import { spawnSync } from 'node:child_process';
import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';
import { afterAll, describe, expect, test } from 'vitest';
import { configureTestGitRepository } from '../test-support/configure-git-fixture.test-helper.ts';
import { okVitestBase } from '../test-support/vitest.base.ts';
import { ISSUE_URL_RULE } from './deviations/contract.mjs';
import { gitCleanEnv } from './git-clean-env.mjs';
import {
  ALLOWANCE_FIELDS,
  ALLOWLIST_PATH,
  CONVENTION_DOC,
  EXPIRY_WARNING_DAYS,
  expired,
  expiringSoon,
  KNOWN_BUG_TAG,
  listTestFiles,
  loadAllowlist,
  MAX_HORIZON_DAYS,
  MIN_SIGNATURE_LITERAL,
  OK_ROOT,
  OWNERS,
  QUARANTINE_TAG,
  render,
  SCHEMA_VERSION,
  scanSource,
  scanTree,
  todayUtc,
  validate,
} from './known-reds.mjs';

const SCRIPT = fileURLToPath(new URL('./known-reds.mjs', import.meta.url));
const ISSUE = 'https://github.com/inkeep/agents-private/issues/1056';
const TODAY = '2026-10-01';
const NO_ALLOWLIST = { ciSkips: [] };
const daysFromToday = (days) =>
  new Date(Date.parse(`${todayUtc()}T00:00:00Z`) + days * 86_400_000).toISOString().slice(0, 10);

const vitestPin = ({
  tags = "['known-bug']",
  meta = `{ issue: '${ISSUE}', owner: 'get-main-green', until: '2026-10-15' }`,
  declare = 'test',
  body = 'await expectKnownBug(/row still visible/, async () => { expect(1).toBe(2); });',
} = {}) => `
import { expect, test } from 'vitest';
import { expectKnownBug } from '../../test-support/known-bug.vitest.test-helper';
${declare}('deleted file leaves the sidebar', { tags: ${tags}, meta: ${meta} }, async () => {
  ${body}
});
`;

const playwrightPin = (configure, until = '2026-10-15') => `
import { expect, test } from '@playwright/test';
import { expectKnownBug } from '../../../../test-support/known-bug.test-helper';
test.describe('sidebar', () => {
  ${configure}
  test('hide removes the row', {
    tag: '@known-bug',
    annotation: [
      { type: 'issue', description: '${ISSUE}' },
      { type: 'owner', description: 'get-main-green' },
      { type: 'until', description: '${until}' },
    ],
  }, async ({ page }) => {
    await expectKnownBug(/unexpected value "visible"/, async () => {
      await expect(page.getByRole('treeitem')).toBeHidden();
    });
  });
});
`;

const rules = (scan) => scan.problems.map((problem) => problem.rule);
const ciSkipCount = (path, source) =>
  scanSource(path, source).gates.filter((gate) => gate.ci === 'skips-on-ci').length;

describe('known-reds scanner: pins and quarantines', () => {
  test('reads a Vitest pin with its fields and signature', () => {
    const scan = scanSource('packages/app/src/a.test.ts', vitestPin());
    expect(scan.problems).toEqual([]);
    expect(scan.pins).toEqual([
      {
        path: 'packages/app/src/a.test.ts',
        line: 4,
        runner: 'vitest',
        title: 'deleted file leaves the sidebar',
        titles: ['deleted file leaves the sidebar'],
        issue: ISSUE,
        owner: 'get-main-green',
        until: '2026-10-15',
        signature: '/row still visible/',
      },
    ]);
  });

  test('a test without the known-bug tag is not a pin', () => {
    const scan = scanSource('packages/app/src/a.test.ts', vitestPin({ tags: "['slow']" }));
    expect(scan.pins).toEqual([]);
    expect(scan.problems).toEqual([]);
  });

  test('accepts a single-string tag', () => {
    expect(
      scanSource('packages/app/src/a.test.ts', vitestPin({ tags: "'known-bug'" })).pins,
    ).toHaveLength(1);
  });

  test('refuses a tag list the listing cannot read', () => {
    expect(
      rules(scanSource('packages/app/src/a.test.ts', vitestPin({ tags: 'PIN_TAGS' }))),
    ).toEqual(['tags-not-literal']);
  });

  test('refuses meta fields the listing cannot read', () => {
    const meta = `{ issue: ISSUE_URL, owner: 'get-main-green', until: '2026-10-15' }`;
    expect(rules(scanSource('packages/app/src/a.test.ts', vitestPin({ meta })))).toEqual([
      'fields-not-literal',
    ]);
  });

  test('a pin must assert through expectKnownBug', () => {
    const scan = scanSource(
      'packages/app/src/a.test.ts',
      vitestPin({ body: 'expect(1).toBe(2);' }),
    );
    expect(rules(scan)).toEqual(['pin-without-helper']);
  });

  test('a pin signature must be a regular-expression literal', () => {
    const body = "await expectKnownBug('row still visible', () => { expect(1).toBe(2); });";
    expect(rules(scanSource('packages/app/src/a.test.ts', vitestPin({ body })))).toEqual([
      'signature-not-literal',
    ]);
  });

  test.each(['/./', '/.*/', '/[a-z]+/', '/a.b.c/', '/.{10,20}/', '/\\w{2,10}/'])(
    'refuses the signature %s, which names no wrong outcome',
    (signature) => {
      const body = `await expectKnownBug(${signature}, () => { expect(1).toBe(2); });`;
      expect(rules(scanSource('packages/app/src/a.test.ts', vitestPin({ body })))).toEqual([
        'signature-too-broad',
      ]);
    },
  );

  test('accepts a signature with a literal run of the minimum length', () => {
    expect(MIN_SIGNATURE_LITERAL).toBe(4);
    for (const signature of ['/ENOENT/', '/\\d+ items/', '/Received: "visible"/i', '/\\{ab\\}/']) {
      const body = `await expectKnownBug(${signature}, () => { expect(1).toBe(2); });`;
      expect(rules(scanSource('packages/app/src/a.test.ts', vitestPin({ body })))).toEqual([]);
    }
  });

  test('a test tagged both known-bug and quarantine is refused', () => {
    const scan = scanSource(
      'packages/app/src/a.test.ts',
      vitestPin({ tags: "['known-bug', 'quarantine']" }),
    );
    expect(rules(scan)).toEqual(['pin-and-quarantine']);
  });

  test('reads a single-object Playwright annotation, and refuses a non-literal one', () => {
    const single = playwrightPin('test.describe.configure({ retries: 0 });').replace(
      /annotation: \[[\s\S]*?\],/,
      `annotation: { type: 'issue', description: '${ISSUE}' },`,
    );
    const singleScan = scanSource('packages/app/tests/stress/a.e2e.ts', single);
    expect(singleScan.problems).toEqual([]);
    expect(singleScan.pins[0]).toMatchObject({ issue: ISSUE });
    expect(singleScan.pins[0].owner).toBeUndefined();
    const nonLiteral = playwrightPin('test.describe.configure({ retries: 0 });').replace(
      `{ type: 'issue', description: '${ISSUE}' }`,
      "{ type: 'issue', description: ISSUE_URL }",
    );
    expect(rules(scanSource('packages/app/tests/stress/a.e2e.ts', nonLiteral))).toEqual([
      'fields-not-literal',
    ]);
  });

  test('a skipped pin is refused, because it checks nothing', () => {
    expect(
      rules(scanSource('packages/app/src/a.test.ts', vitestPin({ declare: 'test.skip' }))),
    ).toEqual(['pin-not-run']);
  });

  test('a known-bug tag on a describe is refused', () => {
    const source = `
import { describe, test } from 'vitest';
describe('sidebar', { tags: ['known-bug'] }, () => {
  test('x', () => {});
});
`;
    expect(rules(scanSource('packages/app/src/a.test.ts', source))).toEqual(['tag-on-describe']);
  });

  test('a Playwright pin runs with retries: 0 in its describe', () => {
    const ok = scanSource(
      'packages/app/tests/stress/a.e2e.ts',
      playwrightPin('test.describe.configure({ retries: 0 });'),
    );
    expect(ok.problems).toEqual([]);
    expect(ok.pins).toHaveLength(1);
    expect(ok.pins[0]).toMatchObject({
      runner: 'playwright',
      issue: ISSUE,
      owner: 'get-main-green',
      until: '2026-10-15',
    });
    expect(rules(scanSource('packages/app/tests/stress/a.e2e.ts', playwrightPin('')))).toEqual([
      'pin-retries',
    ]);
    expect(
      rules(
        scanSource(
          'packages/app/tests/stress/a.e2e.ts',
          playwrightPin('test.describe.configure({ retries: 2 });'),
        ),
      ),
    ).toEqual(['pin-retries']);
  });

  test('the nearest retries setting decides, not an outer one', () => {
    const source = `test.describe.configure({ retries: 0 });\n${playwrightPin('test.describe.configure({ retries: 1 });')}`;
    expect(rules(scanSource('packages/app/tests/stress/a.e2e.ts', source))).toEqual([
      'pin-retries',
    ]);
    const outerOnly = `test.describe.configure({ retries: 0 });\n${playwrightPin('')}`;
    expect(rules(scanSource('packages/app/tests/stress/a.e2e.ts', outerOnly))).toEqual([]);
  });

  test('a quarantine is declared skipped', () => {
    const quarantine = (declare) => `
import { test } from 'vitest';
${declare}('flaky under load', { tags: ['quarantine'], meta: { issue: '${ISSUE}', owner: 'get-main-green', until: '2026-10-15' } }, () => {});
`;
    const skipped = scanSource('packages/app/src/a.test.ts', quarantine('test.skip'));
    expect(skipped.problems).toEqual([]);
    expect(skipped.quarantines).toHaveLength(1);
    expect(skipped.notRun).toEqual([]);
    expect(rules(scanSource('packages/app/src/a.test.ts', quarantine('test')))).toEqual([
      'quarantine-runs',
    ]);
  });

  test('uses the runner-appropriate tag spelling', () => {
    expect(KNOWN_BUG_TAG).toBe('known-bug');
    expect(QUARANTINE_TAG).toBe('quarantine');
    const playwrightWithVitestSpelling = playwrightPin(
      'test.describe.configure({ retries: 0 });',
    ).replace("tag: '@known-bug'", "tag: 'known-bug'");
    expect(
      scanSource('packages/app/tests/stress/a.e2e.ts', playwrightWithVitestSpelling).pins,
    ).toEqual([]);
  });
});

describe('known-reds scanner: bare expected-failure markers', () => {
  test.each([
    ["test.fails('x', () => { expect(1).toBe(2); });", 'packages/app/src/a.test.ts'],
    ["it.fails('x', () => { expect(1).toBe(2); });", 'packages/app/src/a.test.ts'],
    ["test('x', { fails: true }, () => { expect(1).toBe(2); });", 'packages/app/src/a.test.ts'],
    ["test('x', async () => { test.fail(); });", 'packages/app/tests/stress/a.e2e.ts'],
    ["test.fail('x', async () => {});", 'packages/app/tests/stress/a.e2e.ts'],
  ])('refuses %s', (source, path) => {
    expect(rules(scanSource(path, source))).toEqual(['bare-expected-failure']);
  });

  test.each([
    "import assert from 'node:assert'; test('x', () => { assert.fail('unreachable'); });",
    "test('x', () => { deferred.fail(new Error('x')); });",
    "test('x', () => { expect(['test.only(', 'test.fail(']).toHaveLength(2); });",
    "test('x', () => { report({ fails: 3 }); });",
  ])('does not mistake %s for a marker', (source) => {
    expect(scanSource('packages/app/src/a.test.ts', source).problems).toEqual([]);
  });
});

describe('known-reds scanner: CI-keyed skips', () => {
  test.each([
    "test.skip(IS_CI, 'x');",
    "test.skip(isCI, 'x');",
    "test.skip(CI, 'x');",
    "test.skip(process.env.CI === 'true', 'x');",
    'test.skip(process.env.GITHUB_ACTIONS, "x");',
    'test.skip(process.env.GITHUB_RUN_ID, "x");',
    'test.skip(process.env.GITHUB_WORKFLOW, "x");',
    ['test.skip(', '  IS_CI,', "  'disabled on CI',", ');'].join('\n'),
  ])('finds the Playwright skip %s', (source) => {
    expect(ciSkipCount('packages/app/tests/stress/a.e2e.ts', source)).toBe(1);
  });

  test.each([
    "test.skip(!SMOKE_ENABLED, 'x');",
    "test.skip(!DARWIN, 'x');",
    'test.skip(!BUILD_EXISTS, `x`);',
    "test.skip('cold-start deferred', () => {});",
    'test.skip();',
    "test.skip(decisionMade, 'x');",
    "test.skip(CIRCLE_FLAG, 'x');",
    'test.skip(true, "x");',
    "test.skip(config.CI, 'x');",
  ])('does not count %s as CI-keyed', (source) => {
    expect(ciSkipCount('packages/app/tests/stress/a.e2e.ts', source)).toBe(0);
  });

  test('counts each site', () => {
    expect(
      ciSkipCount(
        'packages/app/tests/stress/a.e2e.ts',
        "test.skip(IS_CI, 'a');\ntest.skip(process.env.CI, 'b');",
      ),
    ).toBe(2);
  });

  test.each([
    [
      "import { describe as _d } from 'vitest';\nconst describe = process.env.CI ? _d.skip : _d;",
      'file',
    ],
    ["(process.env.CI ? describe.skip : describe)('x', () => {});", 'describe'],
    ["describe.skipIf(process.env.CI)('x', () => {});", 'describe'],
    ["test.skipIf(process.env.CI ? a : b)('x', () => {});", 'test'],
    ["test('x', (ctx) => { ctx.skip(process.env.CI === 'true', 'no keyring on CI'); });", 'test'],
    ["test('x', ({ skip }) => { skip(process.env.GITHUB_ACTIONS !== undefined); });", 'test'],
    ["const ON_CI = Boolean(process.env.CI);\ntest.skipIf(ON_CI)('x', () => {});", 'test'],
    ["test('x', { skip: process.env.CI === 'true' }, () => {});", 'test'],
    ["test('x', (ctx) => { if (process.env.CI) { ctx.skip(); } });", 'test'],
    ["test.runIf(process.env.CI && FEATURE_FLAG)('x', () => {});", 'test'],
    ["test.skipIf(!process.env.CI || FLAG)('x', () => {});", 'test'],
    ["test.skipIf(process.env.CI || FLAG)('x', () => {});", 'test'],
    ["test.skipIf(process.env.CI && FLAG)('x', () => {});", 'test'],
    ["const RUN = process.env.CI && FEATURE_FLAG;\ntest.runIf(RUN)('x', () => {});", 'test'],
    ["const SKIP = !process.env.CI || FLAG;\ntest.skipIf(SKIP)('x', () => {});", 'test'],
    [
      "const TIMEOUT = process.env.CI ? 60_000 : 5_000;\ntest.skipIf(TIMEOUT > 10_000)('x', () => {});",
      'test',
    ],
    ["const e = process.env;\ntest.skipIf(e.CI)('x', () => {});", 'test'],
    ["const { env: e } = process;\ntest.skipIf(e.CI)('x', () => {});", 'test'],
    ["const { CI } = process.env;\ntest.skipIf(CI)('x', () => {});", 'test'],
    ["const { GITHUB_ACTIONS: gha } = process.env;\ntest.skipIf(gha)('x', () => {});", 'test'],
    ["const key = 'CI';\ntest.skipIf(process.env[key])('x', () => {});", 'test'],
    ["const onCi = () => Boolean(process.env.CI);\ntest.skipIf(onCi())('x', () => {});", 'test'],
    [
      "function onCi() { return process.env.CI === 'true'; }\ntest.skipIf(onCi())('x', () => {});",
      'test',
    ],
    ["import ci from 'ci-info';\ntest.skipIf(ci.isCI)('x', () => {});", 'test'],
    ["import * as ci from 'ci-info';\ntest.skipIf(ci.isCI)('x', () => {});", 'test'],
    ["import { isCI } from 'ci-info';\ntest.skipIf(isCI)('x', () => {});", 'test'],
    ["test.skipIf('CI' in process.env)('x', () => {});", 'test'],
    ["const key = 'GITHUB_ACTIONS';\ntest.skipIf(key in process.env)('x', () => {});", 'test'],
  ])('finds the Vitest skip in %s', (source, scope) => {
    const gates = scanSource('packages/server/src/a.test.ts', source).gates;
    expect(gates.filter((gate) => gate.ci === 'skips-on-ci').map((gate) => gate.scope)).toEqual([
      scope,
    ]);
  });

  test.each([
    "test.runIf(process.env.CI)('x', () => {});",
    "test.skipIf(!process.env.CI)('x', () => {});",
    "test.skipIf(process.env.CI !== 'true')('x', () => {});",
    "describe.skipIf(process.env.CI === undefined)('x', () => {});",
    "test.runIf(process.env.CI || FLAG)('x', () => {});",
    "test.skipIf(!process.env.CI && FLAG)('x', () => {});",
  ])('lists %s as running only on CI, not as a CI skip', (source) => {
    const gates = scanSource('packages/server/src/a.test.ts', source).gates;
    expect(gates.map((gate) => gate.ci)).toEqual(['runs-only-on-ci']);
  });

  test.each([
    "test.skipIf(process.env.CIRCLE)('x', () => {});",
    "test.skipIf({ CI: true }.CI_FLAG)('x', () => {});",
    "test.skipIf(process.platform === 'win32')('x', () => {});",
    "const e = process.env;\ntest.skipIf(e.OK_LIVE_API)('x', () => {});",
    "const { HOME } = process.env;\ntest.skipIf(HOME)('x', () => {});",
    "const key = 'OK_LIVE_API';\ntest.skipIf(process.env[key])('x', () => {});",
    "const hasDocker = () => process.env.DOCKER_HOST !== undefined;\ntest.skipIf(hasDocker())('x', () => {});",
    "import ci from 'ci-info';\ntest.skipIf(ci.isPR)('x', () => {});",
    "import { isCI } from './ci';\ntest.skipIf(isCI)('x', () => {});",
    "import { isCi } from './env';\ntest.skipIf(isCi())('x', () => {});",
    "const { ...CI } = process.env;\ntest.skipIf(CI)('x', () => {});",
    "const { CI } = config;\ntest.skipIf(CI)('x', () => {});",
    "const { env: e } = config;\ntest.skipIf(e.CI)('x', () => {});",
    "import ci from './ci';\ntest.skipIf(ci.isCI)('x', () => {});",
    "import * as ci from './ci';\ntest.skipIf(ci.isCI)('x', () => {});",
    "const onCi = (flag) => Boolean(process.env.CI);\ntest.skipIf(onCi())('x', () => {});",
    "function onCi() { return Boolean(process.env.CI); console.log('after'); }\ntest.skipIf(onCi())('x', () => {});",
    "test.skipIf('OK_LIVE_API' in process.env)('x', () => {});",
    "test.skipIf('CI' in flags)('x', () => {});",
  ])('lists %s as an environment gate', (source) => {
    const gates = scanSource('packages/server/src/a.test.ts', source).gates;
    expect(gates.map((gate) => gate.ci)).toEqual([null]);
  });
});

describe('known-reds feed: gate atoms and title chains', () => {
  const atomsOf = (source) =>
    scanSource('packages/server/src/a.test.ts', source).gates.map((gate) => gate.atoms);

  test.each([
    [
      "test.skipIf(process.platform === 'win32')('x', () => {});",
      [{ kind: 'platform', name: 'process.platform', text: "process.platform === 'win32'" }],
    ],
    [
      "test.skipIf(process.arch !== 'arm64')('x', () => {});",
      [{ kind: 'arch', name: 'process.arch', text: "process.arch !== 'arm64'" }],
    ],
    [
      "test.runIf(process.env.OK_LIVE_API === '1')('x', () => {});",
      [{ kind: 'env', name: 'OK_LIVE_API', text: "process.env.OK_LIVE_API === '1'" }],
    ],
    [
      "test.runIf('OK_LIVE_API' in process.env)('x', () => {});",
      [{ kind: 'env', name: 'OK_LIVE_API', text: "'OK_LIVE_API' in process.env" }],
    ],
    [
      "test.skipIf(process.env.GITHUB_ACTIONS)('x', () => {});",
      [{ kind: 'ci', name: 'GITHUB_ACTIONS', text: 'process.env.GITHUB_ACTIONS' }],
    ],
    [
      "test.skipIf(process.getuid?.() === 0)('x', () => {});",
      [{ kind: 'uid', name: 'process.getuid', text: 'process.getuid?.() === 0' }],
    ],
    [
      "import { existsSync } from 'node:fs';\ntest.runIf(existsSync(BINARY))('x', () => {});",
      [{ kind: 'fs', name: 'BINARY', text: 'existsSync(BINARY)' }],
    ],
    [
      "import os from 'node:os';\ntest.skipIf(os.platform() === 'linux')('x', () => {});",
      [{ kind: 'platform', name: 'os.platform', text: "os.platform() === 'linux'" }],
    ],
    [
      "import { arch as cpu } from 'node:os';\ntest.skipIf(cpu() === 'x64')('x', () => {});",
      [{ kind: 'arch', name: 'os.arch', text: "cpu() === 'x64'" }],
    ],
    [
      "test.skipIf(Number(process.versions.node.split('.')[0]) < 24)('x', () => {});",
      [
        {
          kind: 'runtime',
          name: 'process.versions.node',
          text: "Number(process.versions.node.split('.')[0]) < 24",
        },
      ],
    ],
    [
      "test.skipIf(typeof process.getuid !== 'function')('x', () => {});",
      [
        {
          kind: 'uid',
          name: 'process.getuid',
          text: "typeof process.getuid !== 'function'",
        },
      ],
    ],
    [
      "import { existsSync } from 'node:fs';\ntest.runIf(['/bin/zsh', '/usr/bin/zsh'].find(existsSync))('x', () => {});",
      [
        {
          kind: 'fs',
          name: "['/bin/zsh', '/usr/bin/zsh'].find(existsSync)",
          text: "['/bin/zsh', '/usr/bin/zsh'].find(existsSync)",
        },
      ],
    ],
    [
      "test.skipIf(hasDocker())('x', () => {});",
      [{ kind: 'unknown', name: 'hasDocker()', text: 'hasDocker()' }],
    ],
    [
      "import * as os from 'node:os';\ntest.skipIf(os.type() === 'Windows_NT')('x', () => {});",
      [{ kind: 'platform', name: 'os.type', text: "os.type() === 'Windows_NT'" }],
    ],
    [
      "import os from 'node:os';\ntest.skipIf(os.release().startsWith('10.'))('x', () => {});",
      [{ kind: 'platform', name: 'os.release', text: "os.release().startsWith('10.')" }],
    ],
    [
      "import os from 'node:os';\ntest.skipIf(os.userInfo().uid === 0)('x', () => {});",
      [{ kind: 'uid', name: 'os.userInfo', text: 'os.userInfo().uid === 0' }],
    ],
    [
      "import { machine } from 'node:os';\ntest.skipIf(machine() !== 'arm64')('x', () => {});",
      [{ kind: 'arch', name: 'os.machine', text: "machine() !== 'arm64'" }],
    ],
    [
      "const hasSharp = (() => { try { require.resolve('sharp'); return true; } catch { return false; } })();\ntest.runIf(hasSharp)('x', () => {});",
      [{ kind: 'import', name: 'sharp', text: 'hasSharp' }],
    ],
    [
      "import { createRequire } from 'node:module';\nconst hasCanvas = (() => { try { createRequire(import.meta.url).resolve('canvas'); return true; } catch { return false; } })();\ntest.runIf(hasCanvas)('x', () => {});",
      [{ kind: 'import', name: 'canvas', text: 'hasCanvas' }],
    ],
    [
      "const hasLegacy = (() => { try { require('legacy-dep'); return true; } catch { return false; } })();\ntest.runIf(hasLegacy)('x', () => {});",
      [{ kind: 'import', name: 'legacy-dep', text: 'hasLegacy' }],
    ],
    [
      "test.skipIf(process.env.OK_MODE ?? process.env.CI)('x', () => {});",
      [
        { kind: 'env', name: 'OK_MODE', text: 'process.env.OK_MODE' },
        { kind: 'ci', name: 'CI', text: 'process.env.CI' },
      ],
    ],
    [
      "test.skipIf(process.platform === 'win32' ? process.env.OK_WIN : process.env.OK_POSIX)('x', () => {});",
      [
        { kind: 'platform', name: 'process.platform', text: "process.platform === 'win32'" },
        { kind: 'env', name: 'OK_WIN', text: 'process.env.OK_WIN' },
        { kind: 'env', name: 'OK_POSIX', text: 'process.env.OK_POSIX' },
      ],
    ],
    [
      "import { env } from 'node:process';\ntest.skipIf(env.OK_FLAG === '1')('x', () => {});",
      [{ kind: 'env', name: 'OK_FLAG', text: "env.OK_FLAG === '1'" }],
    ],
    ["test.skipIf(IS_CI)('x', () => {});", [{ kind: 'ci', name: 'IS_CI', text: 'IS_CI' }]],
    [
      "test.skipIf(process.geteuid?.() === 0)('x', () => {});",
      [{ kind: 'uid', name: 'process.geteuid', text: 'process.geteuid?.() === 0' }],
    ],
    [
      "import { isTerminalPlatform } from './p';\ntest.skipIf(isTerminalPlatform(process.platform))('x', () => {});",
      [
        {
          kind: 'unknown',
          name: 'isTerminalPlatform(process.platform)',
          text: 'isTerminalPlatform(process.platform)',
        },
        { kind: 'platform', name: 'process.platform', text: 'process.platform' },
      ],
    ],
    [
      "const { CI } = process.env;\ntest.skipIf(CI)('x', () => {});",
      [{ kind: 'ci', name: 'CI', text: 'CI' }],
    ],
    [
      "const e = process.env;\ntest.skipIf(e.OK_LIVE_API)('x', () => {});",
      [{ kind: 'env', name: 'OK_LIVE_API', text: 'e.OK_LIVE_API' }],
    ],
    [
      "const { platform } = process;\ntest.skipIf(platform === 'win32')('x', () => {});",
      [{ kind: 'platform', name: 'process.platform', text: "platform === 'win32'" }],
    ],
    [
      "import ci from 'ci-info';\ntest.skipIf(ci.isCI)('x', () => {});",
      [{ kind: 'ci', name: 'ci-info', text: 'ci.isCI' }],
    ],
    [
      "const onCi = () => Boolean(process.env.CI);\ntest.skipIf(onCi())('x', () => {});",
      [{ kind: 'ci', name: 'CI', text: 'process.env.CI' }],
    ],
    [
      "import { isCi } from './env';\ntest.skipIf(isCi())('x', () => {});",
      [{ kind: 'unknown', name: 'isCi()', text: 'isCi()' }],
    ],
    [
      "const onCi = (name) => Boolean(process.env[name]);\ntest.skipIf(onCi('CI'))('x', () => {});",
      [{ kind: 'unknown', name: "onCi('CI')", text: "onCi('CI')" }],
    ],
    [
      "test.skipIf(!process.env.OK_PACKAGE_DIR?.trim())('x', () => {});",
      [
        {
          kind: 'unknown',
          name: 'process.env.OK_PACKAGE_DIR?.trim()',
          text: 'process.env.OK_PACKAGE_DIR?.trim()',
        },
        { kind: 'env', name: 'OK_PACKAGE_DIR', text: 'process.env.OK_PACKAGE_DIR' },
      ],
    ],
    [
      "test.skipIf(process.getegid?.() === 0)('x', () => {});",
      [{ kind: 'uid', name: 'process.getegid', text: 'process.getegid?.() === 0' }],
    ],
    [
      "const key = 'OK_LIVE_API';\ntest.skipIf(process.env[key] === '1')('x', () => {});",
      [{ kind: 'env', name: 'OK_LIVE_API', text: "process.env[key] === '1'" }],
    ],
    [
      "import { isCI } from 'ci-info';\ntest.skipIf(isCI)('x', () => {});",
      [{ kind: 'ci', name: 'ci-info', text: 'isCI' }],
    ],
    [
      "const key = 'CI';\ntest.skipIf(key in process.env)('x', () => {});",
      [{ kind: 'ci', name: 'CI', text: 'key in process.env' }],
    ],
    [
      "const { ...rest } = process.env;\ntest.skipIf(rest)('x', () => {});",
      [{ kind: 'unknown', name: 'rest', text: 'rest' }],
    ],
    [
      "const { ...platform } = process;\ntest.skipIf(platform)('x', () => {});",
      [{ kind: 'unknown', name: 'platform', text: 'platform' }],
    ],
    [
      "const { env: { CI } } = process;\ntest.skipIf(CI)('x', () => {});",
      [{ kind: 'unknown', name: 'CI', text: 'CI' }],
    ],
    [
      "function onCi() { const v = process.env.CI; return Boolean(v); }\ntest.skipIf(onCi())('x', () => {});",
      [{ kind: 'unknown', name: 'onCi()', text: 'onCi()' }],
    ],
  ])('reads the atoms of %s', (source, atoms) => {
    expect(atomsOf(source)).toEqual([atoms]);
  });

  test.each([
    ['import { hasLsof } from "../test-support/capabilities.test-helper.ts";', 'hasLsof'],
    [
      'import { hasLsof as present } from "../test-support/capabilities.test-helper.ts";',
      'present',
    ],
    ['import present from "../test-support/capabilities.test-helper.ts";', 'present'],
    ['import * as present from "../test-support/capabilities.test-helper.ts";', 'present'],
  ])('attributes a statically imported condition to its module: %s', (imported, condition) => {
    const source = `${imported}\ntest('x', (ctx) => { ctx.skip(!${condition}, 'requires the tool'); });`;
    expect(atomsOf(source)).toEqual([
      [{ kind: 'import', name: '../test-support/capabilities.test-helper.ts', text: condition }],
    ]);
  });

  test('a local binding shadows a statically imported capability', () => {
    const source = [
      'import { hasLsof } from "../test-support/capabilities.test-helper.ts";',
      "test('x', (ctx) => {",
      '  const hasLsof = localProbe();',
      "  ctx.skip(!hasLsof, 'requires the local tool');",
      '});',
    ].join('\n');
    expect(atomsOf(source)).toEqual([
      [{ kind: 'unknown', name: 'localProbe()', text: 'localProbe()' }],
    ]);
  });

  test('follows aliases to the facts they read', () => {
    const source = [
      "const ON_WINDOWS = process.platform === 'win32';",
      'const SLOW_HOST = ON_WINDOWS || process.env.OK_SLOW === "1";',
      "test.skipIf(SLOW_HOST && !process.env.CI)('x', () => {});",
    ].join('\n');
    expect(atomsOf(source)).toEqual([
      [
        { kind: 'platform', name: 'process.platform', text: "process.platform === 'win32'" },
        { kind: 'env', name: 'OK_SLOW', text: 'process.env.OK_SLOW === "1"' },
        { kind: 'ci', name: 'CI', text: 'process.env.CI' },
      ],
    ]);
  });

  test('resolves an alias to the declaration visible where the gate sits', () => {
    const source = [
      "test('an earlier test', () => {",
      "  const FLAG = process.env.OK_OTHER === '1';",
      '  expect(FLAG).toBe(FLAG);',
      '});',
      "const FLAG = process.platform === 'win32';",
      "test.skipIf(FLAG)('x', () => {});",
    ].join('\n');
    expect(atomsOf(source)).toEqual([
      [{ kind: 'platform', name: 'process.platform', text: "process.platform === 'win32'" }],
    ]);
  });

  test('does not follow a name a parameter shadows', () => {
    const source = [
      'const platform = process.platform;',
      "test.for([{ platform: 'win32' }])('x', ({ platform }, ctx) => {",
      "  ctx.skip(platform === 'win32', 'not here');",
      '  expect(platform).toBe(platform);',
      '});',
    ].join('\n');
    expect(atomsOf(source)).toEqual([
      [{ kind: 'unknown', name: 'platform', text: "platform === 'win32'" }],
    ]);
  });

  test('resolves a shadowed CI alias consistently for ci and atoms', () => {
    const source = [
      'const FLAG = process.env.CI;',
      '{',
      "  const FLAG = process.env.INNER === '1';",
      "  test.skipIf(FLAG)('inner', () => {});",
      '}',
      "test.skipIf(FLAG)('outer', () => {});",
    ].join('\n');
    const { gates } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
      {
        ci: null,
        atoms: [{ kind: 'env', name: 'INNER', text: "process.env.INNER === '1'" }],
      },
      {
        ci: 'skips-on-ci',
        atoms: [{ kind: 'ci', name: 'CI', text: 'process.env.CI' }],
      },
    ]);
  });

  test('resolves CI polarity at each alias declaration, outside the gate scope', () => {
    const source = [
      'const FLAG = !process.env.CI;',
      'const ALIAS = FLAG;',
      '{',
      '  const FLAG = process.env.GITHUB_ACTIONS;',
      "  test.skipIf(FLAG)('inner', () => {});",
      "  test.skipIf(ALIAS)('captured', () => {});",
      '}',
      "test.skipIf(FLAG)('outer', () => {});",
    ].join('\n');
    const { gates } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
      {
        ci: 'skips-on-ci',
        atoms: [{ kind: 'ci', name: 'GITHUB_ACTIONS', text: 'process.env.GITHUB_ACTIONS' }],
      },
      ...Array.from({ length: 2 }, () => ({
        ci: 'runs-only-on-ci',
        atoms: [{ kind: 'ci', name: 'CI', text: 'process.env.CI' }],
      })),
    ]);
  });

  test('resolves a shadowed environment alias consistently for early returns and atoms', () => {
    const source = [
      "const FLAG = process.env.OUTER === '1';",
      "test('inner', (ctx) => {",
      '  const FLAG = capability();',
      '  if (FLAG) return;',
      "  ctx.skip(FLAG, 'inner capability');",
      '  expect(1).toBe(1);',
      '});',
      "test('outer', () => { if (FLAG) return; expect(1).toBe(1); });",
    ].join('\n');
    const { gates, earlyReturns } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
      { ci: null, atoms: [{ kind: 'unknown', name: 'capability()', text: 'capability()' }] },
    ]);
    expect(earlyReturns.map(({ line, condition }) => ({ line, condition }))).toEqual([
      { line: 8, condition: 'FLAG' },
    ]);
  });

  test.each(['function FLAG() {}', 'class FLAG {}'])(
    'stops at a block-scoped %s that shadows an environment alias',
    (declaration) => {
      const source = [
        "import { test } from 'vitest';",
        "const FLAG = process.env.OUTER === '1';",
        '{',
        `  ${declaration}`,
        "  test.skipIf(FLAG)('inner', () => {});",
        '}',
      ].join('\n');
      const { gates } = scanSource('packages/server/src/a.test.ts', source);
      expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
        { ci: null, atoms: [{ kind: 'unknown', name: 'FLAG', text: 'FLAG' }] },
      ]);
    },
  );

  test.each([
    "const run = function FLAG() { test.skipIf(FLAG)('x', () => {}); };",
    "const run = class FLAG { method() { test.skipIf(FLAG)('x', () => {}); } };",
    "class Host { constructor(FLAG) { test.skipIf(FLAG)('x', () => {}); } }",
    "class Host { set value(FLAG) { test.skipIf(FLAG)('x', () => {}); } }",
    "function run(FLAG) { test.skipIf(FLAG)('x', () => {}); }",
    "try { work(); } catch (FLAG) { test.skipIf(FLAG)('x', () => {}); }",
    "for (const FLAG of flags) { test.skipIf(FLAG)('x', () => {}); }",
    "{ const { FLAG } = flags; test.skipIf(FLAG)('x', () => {}); }",
    "function run() { { var FLAG; } test.skipIf(FLAG)('x', () => {}); }",
    "function run() { for (var FLAG of flags) {} test.skipIf(FLAG)('x', () => {}); }",
    "class Host { static { { var FLAG; } test.skipIf(FLAG)('x', () => {}); } }",
    "switch (value) { case 0: let FLAG; break; default: test.skipIf(FLAG)('x', () => {}); }",
    "switch (value) { case 0: function FLAG() {} break; default: test.skipIf(FLAG)('x', () => {}); }",
    "switch (value) { case 0: test.skipIf(FLAG)('x', () => {}); break; default: class FLAG {} }",
  ])('keeps every gate field inside the binding scope in %s', (body) => {
    const source = `const FLAG = process.env.CI;\n${body}`;
    const { gates } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
      { ci: null, atoms: [{ kind: 'unknown', name: 'FLAG', text: 'FLAG' }] },
    ]);
  });

  test.each([
    'import IS_CI from "host";',
    'import * as IS_CI from "host";',
    'import { flag as IS_CI } from "host";',
    'const IS_CI = false;',
    'function IS_CI() {}',
    'class IS_CI {}',
  ])('does not apply the CI-name convention over %s', (binding) => {
    const { gates } = scanSource(
      'packages/server/src/a.test.ts',
      `${binding}\ntest.skipIf(IS_CI)('x', () => {});`,
    );
    expect(gates[0].ci).toBeNull();
    expect(gates[0].atoms.every((atom) => atom.kind !== 'ci')).toBe(true);
  });

  test.each([
    ['import { platform as FLAG } from "node:os";', 'FLAG()'],
    ['import * as FLAG from "node:os";', 'FLAG.platform()'],
    ['import FLAG from "node:os";', 'FLAG.platform()'],
  ])('resolves shadowed OS imports by scope for %s', (imported, condition) => {
    const source = [
      imported,
      "test('x', (ctx) => {",
      '  const FLAG = host;',
      `  if (${condition}) return;`,
      `  ctx.skip(${condition});`,
      '});',
    ].join('\n');
    const { gates, earlyReturns } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates[0].ci).toBeNull();
    expect(gates[0].atoms).toContainEqual({ kind: 'unknown', name: condition, text: condition });
    expect(gates[0].atoms.every((atom) => atom.kind === 'unknown')).toBe(true);
    expect(earlyReturns).toEqual([]);
  });

  test('terminates cyclic alias resolution and follows chains beyond three passes', () => {
    const source = [
      'const FIRST = SECOND;',
      'const SECOND = FIRST;',
      "test.skipIf(FIRST)('cycle', () => {});",
      'const A = B;',
      'const B = C;',
      'const C = D;',
      'const D = E;',
      'const E = process.env.CI;',
      "test.skipIf(A)('chain', () => {});",
      "test('cycle body', () => { if (FIRST) return; expect(1).toBe(1); });",
      "test('chain body', () => { if (A) return; expect(1).toBe(1); });",
    ].join('\n');
    const { gates, earlyReturns } = scanSource('packages/server/src/a.test.ts', source);
    expect(gates.map(({ ci, atoms }) => ({ ci, atoms }))).toEqual([
      { ci: null, atoms: [{ kind: 'unknown', name: 'FIRST', text: 'FIRST' }] },
      { ci: 'skips-on-ci', atoms: [{ kind: 'ci', name: 'CI', text: 'process.env.CI' }] },
    ]);
    expect(earlyReturns.map(({ condition }) => condition)).toEqual(['A']);
  });

  test('gives a pin nested in a describe its full title chain', () => {
    const [pin] = scanSource(
      'packages/app/tests/stress/a.e2e.ts',
      playwrightPin('test.describe.configure({ retries: 0 });'),
    ).pins;
    expect(pin.titles).toEqual(['sidebar', 'hide removes the row']);
  });

  test('names the module an import probe tries', () => {
    const source = [
      "const hasPlaywright = await import('playwright').then(() => true, () => false);",
      "test.runIf(hasPlaywright)('x', () => {});",
    ].join('\n');
    expect(atomsOf(source)).toEqual([
      [{ kind: 'import', name: 'playwright', text: 'hasPlaywright' }],
    ]);
  });

  test('gives test- and describe-scope entries their title chain', () => {
    const source = [
      "describe('outer', () => {",
      "  describe.skipIf(process.env.CI)('inner', () => {",
      "    test('works', (ctx) => {",
      "      ctx.skip(process.platform === 'win32', 'posix only');",
      '      expect(1).toBe(1);',
      '    });',
      "    test.todo('later');",
      '  });',
      '});',
    ].join('\n');
    const scan = scanSource('packages/server/src/a.test.ts', source);
    expect(scan.gates.map((gate) => [gate.scope, gate.titles])).toEqual([
      ['describe', ['outer', 'inner']],
      ['test', ['outer', 'inner', 'works']],
    ]);
    expect(scan.notRun.map((entry) => entry.titles)).toEqual([['outer', 'inner', 'later']]);
  });

  test('marks a title that is not a string literal', () => {
    const source = [
      "const name = 'dynamic';",
      "describe('suite for ' + name, () => {",
      "  test.skipIf(process.platform === 'darwin')(name, () => {});",
      '});',
    ].join('\n');
    const [gate] = scanSource('packages/server/src/a.test.ts', source).gates;
    expect(gate.titles).toEqual([{ nonLiteral: "'suite for ' + name" }, { nonLiteral: 'name' }]);
  });

  test('gives a file-scope gate no title chain', () => {
    const source = "const d = process.env.CI ? describe.skip : describe;\nd('x', () => {});";
    const [gate] = scanSource('packages/server/src/a.test.ts', source).gates;
    expect([gate.scope, 'titles' in gate]).toEqual(['file', false]);
  });
});

describe('known-reds scanner: early returns and not-run tests', () => {
  test.each([
    "test('x', () => { if (process.platform === 'win32') return; expect(1).toBe(1); });",
    "const IS_WIN = process.platform === 'win32';\ntest('x', () => { if (IS_WIN) { console.log('skip'); return; } expect(1).toBe(1); });",
    "import { existsSync } from 'node:fs';\ntest('x', () => { if (!existsSync(built)) return; expect(1).toBe(1); });",
    "import os from 'node:os';\ntest('x', () => { if (os.platform() !== 'darwin') return; expect(1).toBe(1); });",
    "test('x', () => { if (process.env.OK_AUDIT === '1') { report(); return; } expect(1).toBe(1); });",
    "describe('x', () => { const isWin = process.platform === 'win32'; test('y', () => { if (isWin) return; expect(1).toBe(1); }); });",
    "const { OK_LIVE_API } = process.env;\ntest('x', () => { if (!OK_LIVE_API) return; expect(1).toBe(1); });",
    "const { platform } = process;\ntest('x', () => { if (platform === 'win32') return; expect(1).toBe(1); });",
  ])('flags the environment early return in %s', (source) => {
    expect(scanSource('packages/server/src/a.test.ts', source).earlyReturns).toHaveLength(1);
  });

  test.each([
    "test('x', () => { const button = find(); if (!button) return; expect(button).toBeTruthy(); });",
    "test('x', () => { expect(a).toBe(1); if (process.platform === 'win32') return; expect(b).toBe(2); });",
    "test('x', async () => { await vi.waitFor(() => expect(a).toBe(1)); if (process.platform === 'win32') return; });",
    "test('x', () => { const f = () => { if (process.platform === 'win32') return; }; f(); expect(1).toBe(1); });",
    "test('x', () => { if (process.platform === 'win32') return promise; expect(1).toBe(1); });",
    "test('x', (ctx) => { if (process.platform === 'win32') { ctx.skip(); return; } expect(1).toBe(1); });",
    "describe('x', () => { if (process.platform === 'win32') return; test('y', () => { expect(1).toBe(1); }); });",
    "const { value } = config;\ntest('x', () => { if (!value) return; expect(1).toBe(1); });",
    "const { platform } = opts;\ntest('x', () => { if (platform === 'win32') return; expect(1).toBe(1); });",
    "const { argv } = process;\ntest('x', () => { if (!argv) return; expect(1).toBe(1); });",
  ])('leaves %s alone', (source) => {
    expect(scanSource('packages/server/src/a.test.ts', source).earlyReturns).toEqual([]);
  });

  test.each([
    ["function f() { return f(); }\ntest.skipIf(f())('x', () => {});", 'f()'],
    ["const a = b;\nconst b = a;\ntest.skipIf(process.env[a])('x', () => {});", null],
    ["const e = f;\nconst f = e;\ntest.skipIf(e.CI)('x', () => {});", null],
  ])('terminates on the cyclic declarations in %s', (source, unknownName) => {
    const [gate] = scanSource('packages/server/src/a.test.ts', source).gates;
    expect(gate.ci).toBeNull();
    if (unknownName !== null)
      expect(gate.atoms).toContainEqual({ kind: 'unknown', name: unknownName, text: unknownName });
  });

  test('flags a Playwright early return too', () => {
    const source = "test('x', async () => { if (process.platform === 'win32') return; });";
    expect(scanSource('packages/app/tests/stress/a.e2e.ts', source).earlyReturns).toHaveLength(1);
  });

  test('reads the test context from test.for, and none from test.each', () => {
    const forSource =
      "test.for(cases)('x $name', (row, ctx) => { ctx.skip(process.platform === 'win32', 'posix'); expect(row).toBeTruthy(); });";
    expect(
      scanSource('packages/server/src/a.test.ts', forSource).gates.map((gate) => gate.form),
    ).toEqual(['context-skip']);
    const eachSource =
      "test.each(cases)('x $name', (row) => { row.skip(process.platform === 'win32'); expect(row).toBeTruthy(); });";
    expect(scanSource('packages/server/src/a.test.ts', eachSource).gates).toEqual([]);
  });

  test('lists unconditional skips, fixme and todo as not run', () => {
    const vitest = scanSource(
      'packages/server/src/a.test.ts',
      "test.skip('a', () => {});\ntest.todo('b');\ntest('c', { skip: true }, () => {});\ntest('d', (ctx) => { ctx.skip('not yet'); });",
    );
    expect(vitest.notRun.map((row) => row.form)).toEqual([
      'skip',
      'todo',
      'skip-option',
      'context-skip',
    ]);
    const playwright = scanSource(
      'packages/app/tests/stress/a.e2e.ts',
      "test('e', async () => { test.skip(true, 'PR #1010 broke it'); });\ntest.fixme('f', async () => {});",
    );
    expect(playwright.notRun.map((row) => [row.form, row.scope])).toEqual([
      ['skip', 'test'],
      ['fixme', 'test'],
    ]);
  });

  test('takes a literal-true skip’s condition from the if around it', () => {
    const source =
      "async function settle() { if (workArea.width < width) { test.skip(true, 'too small'); } }";
    const scan = scanSource('packages/desktop/tests/smoke/a.e2e.ts', source);
    expect(scan.notRun).toEqual([]);
    expect(scan.gates.map((gate) => [gate.scope, gate.condition, gate.reason])).toEqual([
      ['helper', 'workArea.width < width', 'too small'],
    ]);
  });

  test('ignores runner-like calls on other objects', () => {
    const scan = scanSource(
      'packages/server/src/a.test.ts',
      "test('x', () => { harness.test.skip(process.env.CI); runner.skipIf(process.env.CI); });",
    );
    expect(scan.gates).toEqual([]);
    expect(scan.problems).toEqual([]);
  });
});

describe('known-reds validation', () => {
  const pinReport = (fields) => ({
    problems: [],
    pins: [
      {
        path: 'a.test.ts',
        line: 1,
        runner: 'vitest',
        title: 't',
        issue: ISSUE,
        owner: 'get-main-green',
        until: '2026-10-15',
        ...fields,
      },
    ],
    quarantines: [],
    earlyReturns: [],
    ciSkips: [],
  });
  const messages = (report, allowlist = NO_ALLOWLIST) =>
    validate(report, { today: TODAY, allowlist }).map((violation) => violation.message);

  test('accepts a complete pin', () => {
    expect(messages(pinReport({}))).toEqual([]);
  });

  test.each([
    [{ owner: undefined }, 'known-bug pin has no owner'],
    [
      { owner: 'someone-else' },
      `known-bug pin has owner "someone-else", which is not one of ${OWNERS.join(', ')}`,
    ],
    [{ issue: undefined }, 'known-bug pin has no issue'],
    [
      { issue: 'inkeep/agents-private#1056' },
      `known-bug pin has issue "inkeep/agents-private#1056", which is not ${ISSUE_URL_RULE}`,
    ],
    [{ until: undefined }, 'known-bug pin has no until'],
    [
      { until: '15/10/2026' },
      'known-bug pin has until "15/10/2026", which is not a YYYY-MM-DD date',
    ],
    [
      { until: '2026-02-30' },
      'known-bug pin has until "2026-02-30", which is not a YYYY-MM-DD date',
    ],
    [
      { until: '2026-12-31' },
      `known-bug pin has until 2026-12-31, beyond the ${MAX_HORIZON_DAYS}-day horizon (2026-12-30)`,
    ],
  ])('refuses %j', (fields, message) => {
    expect(messages(pinReport(fields))).toEqual([message]);
  });

  test('reports a pin past its until date instead of refusing it', () => {
    const report = pinReport({ until: '2026-09-30' });
    expect(messages(report)).toEqual([]);
    expect(expired(report, { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([
      {
        kind: 'pin',
        path: 'a.test.ts',
        line: 1,
        owner: 'get-main-green',
        issue: ISSUE,
        until: '2026-09-30',
      },
    ]);
    expect(expired(pinReport({}), { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([]);
  });

  test('a pin dated its own day is neither expired nor refused', () => {
    const report = pinReport({ until: TODAY });
    expect(messages(report)).toEqual([]);
    expect(expired(report, { today: TODAY, allowlist: NO_ALLOWLIST })).toEqual([]);
  });

  test('an expired pin with a malformed issue is still refused for the issue', () => {
    expect(messages(pinReport({ until: '2026-09-30', issue: 'PRD-1' }))).toEqual([
      `known-bug pin has issue "PRD-1", which is not ${ISSUE_URL_RULE}`,
    ]);
  });

  test('reports an expired quarantine and an expired allowlist entry the same way', () => {
    const report = {
      ...pinReport({}),
      quarantines: [
        { path: 'q.test.ts', line: 4, issue: ISSUE, owner: 'get-main-green', until: '2026-09-01' },
      ],
    };
    const allowlist = {
      ciSkips: [
        {
          path: 'd.test.ts',
          condition: 'CI',
          issue: ISSUE,
          owner: 'known-reds',
          until: '2026-09-02',
          reason: 'r',
          exit: 'e',
        },
      ],
    };
    expect(
      expired(report, { today: TODAY, allowlist }).map((row) => `${row.kind} ${row.until}`),
    ).toEqual(['quarantine 2026-09-01', 'ci-skip-entry 2026-09-02']);
    expect(
      validate(report, { today: TODAY, allowlist }).map((violation) => violation.rule),
    ).toEqual(['allowlist-stale']);
  });

  test(`lists what expires within ${EXPIRY_WARNING_DAYS} days, without failing it`, () => {
    const report = {
      ...pinReport({}),
      pins: [
        { path: 'a.test.ts', line: 1, until: '2026-10-08', owner: 'get-main-green' },
        { path: 'b.test.ts', line: 2, until: '2026-10-15', owner: 'get-main-green' },
        { path: 'c.test.ts', line: 3, until: '2026-10-16', owner: 'get-main-green' },
      ],
    };
    const allowlist = {
      ciSkips: [{ path: 'd.test.ts', condition: 'CI', owner: 'known-reds', until: '2026-10-02' }],
    };
    expect(expiringSoon(report, { today: TODAY, allowlist })).toEqual([
      {
        kind: 'pin',
        path: 'a.test.ts',
        line: 1,
        owner: 'get-main-green',
        issue: null,
        until: '2026-10-08',
      },
      {
        kind: 'pin',
        path: 'b.test.ts',
        line: 2,
        owner: 'get-main-green',
        issue: null,
        until: '2026-10-15',
      },
      {
        kind: 'ci-skip-entry',
        path: 'd.test.ts',
        line: null,
        owner: 'known-reds',
        issue: null,
        until: '2026-10-02',
      },
    ]);
  });

  test('the listing names each expiring kind', () => {
    const report = {
      files: 3,
      problems: [],
      pins: [{ path: 'a.test.ts', line: 1, until: '2026-10-08', owner: 'get-main-green' }],
      quarantines: [{ path: 'q.test.ts', line: 4, until: '2026-10-09', owner: 'get-main-green' }],
      earlyReturns: [],
      ciSkips: [],
      notRun: [],
      envGates: [],
    };
    const allowlist = {
      ciSkips: [{ path: 'd.test.ts', condition: 'CI', owner: 'known-reds', until: '2026-10-02' }],
    };
    const upcoming = expiringSoon(report, { today: TODAY, allowlist });
    expect(render(report, [], upcoming, TODAY, { all: false })).toContain(
      [
        `Expiring within ${EXPIRY_WARNING_DAYS} days (3)`,
        '  pin  a.test.ts:1  owner get-main-green, until 2026-10-08',
        '  quarantine  q.test.ts:4  owner get-main-green, until 2026-10-09',
        '  allowlisted CI skip  d.test.ts  owner known-reds, until 2026-10-02',
      ].join('\n'),
    );
  });

  test('the listing counts gates it cannot read, and lists them with --all', () => {
    const unread = { kind: 'unknown', name: 'isCi()', text: 'isCi()' };
    const report = {
      files: 1,
      problems: [],
      pins: [],
      quarantines: [],
      earlyReturns: [],
      ciSkips: [],
      notRun: [],
      envGates: [
        {
          path: 'a.test.ts',
          line: 3,
          form: 'skipIf',
          condition: 'isCi()',
          ci: null,
          atoms: [unread],
        },
        {
          path: 'b.test.ts',
          line: 5,
          form: 'skipIf',
          condition: "process.platform === 'win32'",
          ci: null,
          atoms: [{ kind: 'platform', name: 'process.platform', text: 'process.platform' }],
        },
      ],
    };
    report.ciSkips = [
      {
        path: 'c.test.ts',
        line: 7,
        form: 'skipIf',
        scope: 'test',
        condition: 'process.env.CI && isFoo()',
        ci: 'skips-on-ci',
        atoms: [
          { kind: 'ci', name: 'CI', text: 'process.env.CI' },
          { kind: 'unknown', name: 'isFoo()', text: 'isFoo()' },
        ],
      },
    ];
    const heading = 'Gates with a condition the scanner cannot read (2)';
    const rows = [
      '  c.test.ts:7  skipIf  cannot read: isFoo()',
      '  a.test.ts:3  skipIf  cannot read: isCi()',
    ];
    const brief = render(report, [], [], TODAY, { all: false });
    expect(brief).toContain(heading);
    for (const row of rows) expect(brief).not.toContain(row);
    expect(render(report, [], [], TODAY, { all: true })).toContain([heading, ...rows].join('\n'));
  });

  test('the date boundaries are inclusive', () => {
    expect(messages(pinReport({ until: TODAY }))).toEqual([]);
    expect(messages(pinReport({ until: '2026-12-30' }))).toEqual([]);
  });

  test('accepts a Linear issue', () => {
    expect(
      messages(pinReport({ issue: 'https://linear.app/inkeep/issue/PRD-8603/symlink-reads' })),
    ).toEqual([]);
  });

  test('holds a quarantine to the same fields', () => {
    const report = {
      ...pinReport({}),
      pins: [],
      quarantines: [
        { path: 'a.test.ts', line: 1, title: 't', issue: ISSUE, owner: 'get-main-green' },
      ],
    };
    expect(messages(report)).toEqual(['quarantine has no until']);
  });

  test('refuses an environment early return', () => {
    const report = {
      ...pinReport({}),
      pins: [],
      earlyReturns: [{ path: 'a.test.ts', line: 3, condition: "process.platform === 'win32'" }],
    };
    expect(
      validate(report, { today: TODAY, allowlist: NO_ALLOWLIST }).map(
        (violation) => violation.rule,
      ),
    ).toEqual(['early-return']);
  });

  describe('the CI-skip allowlist', () => {
    const skip = {
      path: 'packages/server/src/boot.test.ts',
      line: 3,
      form: 'alias',
      scope: 'file',
      condition: 'process.env.CI',
    };
    const entry = {
      path: skip.path,
      condition: skip.condition,
      issue: ISSUE,
      owner: 'known-reds',
      until: '2026-11-01',
      reason: 'skips the whole file on CI',
      exit: 'run the file on CI, then delete this entry',
    };
    const report = { ...pinReport({}), pins: [], ciSkips: [skip] };
    const ruleNames = (allowlist) =>
      validate(report, { today: TODAY, allowlist }).map((violation) => violation.rule);

    test('refuses a CI skip that is not listed', () => {
      expect(ruleNames(NO_ALLOWLIST)).toEqual(['ci-skip']);
    });

    test('accepts a listed CI skip that carries all five fields', () => {
      expect(ALLOWANCE_FIELDS).toEqual(['issue', 'owner', 'until', 'reason', 'exit']);
      expect(ruleNames({ ciSkips: [entry] })).toEqual([]);
    });

    test.each(ALLOWANCE_FIELDS)('refuses an entry without %s, by exactly that field', (field) => {
      const { [field]: _dropped, ...missing } = entry;
      expect(
        validate(report, { today: TODAY, allowlist: { ciSkips: [missing] } }).map(
          (violation) => violation.message,
        ),
      ).toEqual([`entry ${entry.path} has no ${field}`]);
    });

    test('permits exactly one site per entry', () => {
      const twice = { ...report, ciSkips: [skip, { ...skip, line: 40 }] };
      expect(
        validate(twice, { today: TODAY, allowlist: { ciSkips: [entry] } }).map(
          (violation) => `${violation.line} ${violation.rule}`,
        ),
      ).toEqual(['40 ci-skip']);
    });

    test('matches on the condition as well as the path', () => {
      expect(
        ruleNames({ ciSkips: [{ ...entry, condition: "process.env.CI === 'true'" }] }),
      ).toEqual(['ci-skip', 'allowlist-stale']);
    });

    test('refuses a stale, unowned or unexplained entry, a whitespace-only reason included', () => {
      expect(
        validate({ ...report, ciSkips: [] }, { today: TODAY, allowlist: { ciSkips: [entry] } }).map(
          (violation) => violation.rule,
        ),
      ).toEqual(['allowlist-stale']);
      expect(ruleNames({ ciSkips: [{ ...entry, owner: 'nobody' }] })).toEqual(['allowlist-fields']);
      expect(ruleNames({ ciSkips: [{ ...entry, reason: '' }] })).toEqual(['allowlist-fields']);
      expect(ruleNames({ ciSkips: [{ ...entry, reason: ' \t ' }] })).toEqual(['allowlist-fields']);
      expect(ruleNames({ ciSkips: [{ ...entry, exit: '  ' }] })).toEqual(['allowlist-fields']);
    });

    test('reports an expired entry and still consumes its site', () => {
      const lapsed = { ...entry, until: '2026-09-01' };
      expect(ruleNames({ ciSkips: [lapsed] })).toEqual([]);
      expect(
        expired(report, { today: TODAY, allowlist: { ciSkips: [lapsed] } }).map((row) => row.kind),
      ).toEqual(['ci-skip-entry']);
    });
  });
});

describe('known-reds through its real invocation', () => {
  const root = mkdtempSync(join(tmpdir(), 'ok-known-reds-'));
  afterAll(() => rmSync(root, { recursive: true, force: true }));
  const write = (path, source) => {
    mkdirSync(dirname(join(root, path)), { recursive: true });
    writeFileSync(join(root, path), source);
  };
  write(
    'packages/server/src/planted-boot.test.ts',
    "import { describe as _d } from 'vitest';\nconst describe = process.env.CI ? _d.skip : _d;\ndescribe('boot', () => {});\n",
  );
  write(
    'packages/server/src/spawn.test.ts',
    "test('x', () => { if (process.platform === 'win32') return; expect(1).toBe(1); });\n",
  );
  write(
    'packages/app/tests/stress/hide.e2e.ts',
    playwrightPin('', daysFromToday(Math.floor((EXPIRY_WARNING_DAYS + MAX_HORIZON_DAYS) / 2))),
  );
  write(
    'packages/app/src/helper.test-helper.ts',
    [
      "import { hasLsof } from '../../../../test-support/capabilities.test-helper.ts';",
      "test('helper contract', (ctx) => { ctx.skip(!hasLsof, 'the product inspects processes with lsof'); });",
    ].join('\n'),
  );
  write('reports/spike/probe.test.ts', "test.skip(process.env.CI, 'evidence');\n");
  write('specs/spike/probe.e2e.ts', "test.skip(process.env.CI, 'evidence');\n");
  write('node_modules/pkg/dep.test.js', "test.skip(process.env.CI, 'vendored');\n");
  const init = spawnSync('git', ['init', '-q'], {
    cwd: root,
    env: gitCleanEnv(),
    windowsHide: true,
    encoding: 'utf8',
  });
  if (init.status === 0) configureTestGitRepository(root);

  test('scans test files and helpers that can declare their tests', () => {
    expect(init.status).toBe(0);
    expect(listTestFiles(root)).toEqual([
      'packages/app/src/helper.test-helper.ts',
      'packages/app/tests/stress/hide.e2e.ts',
      'packages/server/src/planted-boot.test.ts',
      'packages/server/src/spawn.test.ts',
    ]);
  });

  test('lists a reasoned environment gate declared in a helper file', () => {
    const report = scanTree(root);
    expect(report.envGates).toEqual([
      {
        path: 'packages/app/src/helper.test-helper.ts',
        line: 2,
        form: 'context-skip',
        scope: 'test',
        condition: '!hasLsof',
        skipWhen: 'condition',
        ci: null,
        reason: 'the product inspects processes with lsof',
        atoms: [
          {
            kind: 'import',
            name: '../../../../test-support/capabilities.test-helper.ts',
            text: 'hasLsof',
          },
        ],
        titles: ['helper contract'],
      },
    ]);
  });

  test('finds every planted violation', () => {
    const report = scanTree(root);
    const violations = validate(report, { today: todayUtc(), allowlist: NO_ALLOWLIST });
    expect(
      violations.map((violation) => `${violation.path}:${violation.line} ${violation.rule}`).sort(),
    ).toEqual([
      'packages/app/tests/stress/hide.e2e.ts:6 pin-retries',
      'packages/server/src/planted-boot.test.ts:2 ci-skip',
      'packages/server/src/spawn.test.ts:1 early-return',
    ]);
  });

  test('the command exits 1 on violations, and lists them in its JSON feed', () => {
    const run = spawnSync(process.execPath, [SCRIPT, '--json', '--root', root], {
      encoding: 'utf8',
      env: gitCleanEnv(),
      windowsHide: true,
    });
    expect(run.status).toBe(1);
    const feed = JSON.parse(run.stdout);
    expect(feed.schemaVersion).toBe(4);
    expect(feed.expired).toEqual([]);
    expect(feed.files).toBe(4);
    expect(feed.violations.map((violation) => violation.rule)).toEqual(
      expect.arrayContaining(['pin-retries', 'ci-skip', 'early-return']),
    );
  });

  test('the command warns about a pin that expires soon, in the feed and the listing', () => {
    const soon = daysFromToday(7);
    write(
      'packages/server/src/expiring.test.ts',
      vitestPin({ meta: `{ issue: '${ISSUE}', owner: 'get-main-green', until: '${soon}' }` }),
    );
    try {
      const json = spawnSync(process.execPath, [SCRIPT, '--json', '--root', root], {
        encoding: 'utf8',
        env: gitCleanEnv(),
        windowsHide: true,
      });
      expect(JSON.parse(json.stdout).expiringSoon).toEqual(
        expect.arrayContaining([
          {
            kind: 'pin',
            path: 'packages/server/src/expiring.test.ts',
            line: 4,
            owner: 'get-main-green',
            issue: ISSUE,
            until: soon,
          },
        ]),
      );
      const listing = spawnSync(process.execPath, [SCRIPT, '--root', root], {
        encoding: 'utf8',
        env: gitCleanEnv(),
        windowsHide: true,
      });
      expect(listing.stdout).toMatch(
        new RegExp(`Expiring within ${EXPIRY_WARNING_DAYS} days \\(\\d+\\)`),
      );
      expect(listing.stdout).toContain(
        `pin  packages/server/src/expiring.test.ts:4  owner get-main-green, until ${soon}`,
      );
    } finally {
      rmSync(join(root, 'packages/server/src/expiring.test.ts'), { force: true });
    }
  });

  test('the listing names the planted sites and points at the convention', () => {
    const run = spawnSync(process.execPath, [SCRIPT, '--root', root], {
      encoding: 'utf8',
      env: gitCleanEnv(),
      windowsHide: true,
    });
    expect(run.status).toBe(1);
    expect(run.stdout).toContain('Known reds in open-knowledge on ');
    expect(run.stdout).toContain(': 4 test files scanned.');
    expect(run.stdout).toContain(
      'packages/server/src/planted-boot.test.ts:2  file  process.env.CI',
    );
    expect(run.stdout).toContain(`The convention: ${CONVENTION_DOC}.`);
  });

  test('the command exits 2, not 0, when it cannot scan', () => {
    const notARepo = mkdtempSync(join(tmpdir(), 'ok-known-reds-bare-'));
    try {
      const run = spawnSync(process.execPath, [SCRIPT, '--root', notARepo], {
        encoding: 'utf8',
        env: { ...gitCleanEnv(), GIT_CEILING_DIRECTORIES: tmpdir() },
        windowsHide: true,
      });
      expect(run.status).toBe(2);
      expect(run.stderr).toMatch(/^known-reds: could not run: /);
    } finally {
      rmSync(notARepo, { recursive: true, force: true });
    }
  });
});

describe('an expired date through the real invocation', () => {
  const yesterday = daysFromToday(-1);
  const treeWith = (until) => {
    const root = mkdtempSync(join(tmpdir(), 'ok-known-reds-expiry-'));
    const file = join(root, 'packages/server/src/lapsed.test.ts');
    mkdirSync(dirname(file), { recursive: true });
    writeFileSync(
      file,
      vitestPin({ meta: `{ issue: '${ISSUE}', owner: 'get-main-green', until: '${until}' }` }),
    );
    const init = spawnSync('git', ['init', '-q'], {
      cwd: root,
      env: gitCleanEnv(),
      windowsHide: true,
      encoding: 'utf8',
    });
    if (init.status === 0) configureTestGitRepository(root);
    return { root, init };
  };
  const roots = [];
  afterAll(() => {
    for (const root of roots) rmSync(root, { recursive: true, force: true });
  });
  const run = (until, args) => {
    const { root, init } = treeWith(until);
    roots.push(root);
    expect(init.status).toBe(0);
    return spawnSync(process.execPath, [SCRIPT, ...args, '--root', root], {
      encoding: 'utf8',
      env: gitCleanEnv(),
      windowsHide: true,
    });
  };

  test('a pin past its until exits 0, and the feed and the listing report it', () => {
    const json = run(yesterday, ['--json']);
    expect(json.status, json.stderr).toBe(0);
    const feed = JSON.parse(json.stdout);
    expect(feed.files).toBe(1);
    expect(feed.pins.map((pin) => pin.until)).toEqual([yesterday]);
    expect(feed.violations).toEqual([]);
    expect(feed.expired).toEqual([
      {
        kind: 'pin',
        path: 'packages/server/src/lapsed.test.ts',
        line: 4,
        owner: 'get-main-green',
        issue: ISSUE,
        until: yesterday,
      },
    ]);
    const listing = run(yesterday, []);
    expect(listing.status, listing.stderr).toBe(0);
    expect(listing.stdout).toContain(
      `Expired, reported and not failed (1)\n  pin  packages/server/src/lapsed.test.ts:4  owner get-main-green, until ${yesterday}, issue ${ISSUE}`,
    );
  });

  test('the same pin with a date that is not a real day exits 1', () => {
    const json = run('2026-02-30', ['--json']);
    expect(json.status).toBe(1);
    expect(JSON.parse(json.stdout).violations.map((violation) => violation.message)).toEqual([
      'known-bug pin has until "2026-02-30", which is not a YYYY-MM-DD date',
    ]);
  });
});

describe('known-reds on this tree', () => {
  const files = listTestFiles(OK_ROOT);
  let scanned;
  const tree = () => {
    scanned ??= scanTree(OK_ROOT);
    return scanned;
  };

  test('scans every runner’s test files and nothing under reports/ or specs/', () => {
    expect(files).toEqual(
      expect.arrayContaining([
        'scripts/check-known-reds.uncached.test.mjs',
        'test-support/known-bug.test.ts',
        'packages/app/tests/stress/file-tree-create.e2e.ts',
        'packages/desktop/tests/smoke/mcp-wiring.e2e.ts',
      ]),
    );
    expect(
      files.filter((path) => path.startsWith('reports/') || path.startsWith('specs/')),
    ).toEqual([]);
  });

  test('every gate on this tree names at least one atom', () => {
    const report = tree();
    expect(
      [...report.ciSkips, ...report.envGates]
        .filter((gate) => gate.atoms.length === 0)
        .map((gate) => `${gate.path}:${gate.line} ${gate.condition}`),
    ).toEqual([]);
  });

  test('conforms: pins, quarantines, CI skips and early returns follow the convention', () => {
    const violations = validate(tree(), {
      today: todayUtc(),
      allowlist: loadAllowlist(),
    });
    expect(
      violations.map(
        (violation) =>
          `${violation.path}:${violation.line} [${violation.rule}] ${violation.message}`,
      ),
    ).toEqual([]);
  });

  test('the allowlist is the file the command reads', () => {
    expect(JSON.parse(readFileSync(ALLOWLIST_PATH, 'utf8'))).toEqual(loadAllowlist());
  });

  test('every Vitest tier declares the known-bug and quarantine tags', () => {
    expect(okVitestBase.test.tags.map((tag) => tag.name)).toEqual([KNOWN_BUG_TAG, QUARANTINE_TAG]);
  });

  test('the convention doc and the guard cite each other', () => {
    const doc = readFileSync(join(OK_ROOT, CONVENTION_DOC), 'utf8');
    for (const cited of [
      'scripts/check-known-reds.uncached.test.mjs',
      'scripts/known-reds.mjs',
      'scripts/known-reds-allowlist.json',
      'pnpm known-reds',
      `no more than ${MAX_HORIZON_DAYS} days away`,
      `at least ${MIN_SIGNATURE_LITERAL} literal characters in a row`,
      `Expiring within ${EXPIRY_WARNING_DAYS} days`,
      'Expired, reported and not failed',
      `(\`schemaVersion\` ${SCHEMA_VERSION})`,
    ]) {
      expect(doc, `${CONVENTION_DOC} must mention ${cited}`).toContain(cited);
    }
  });

  test('pnpm known-reds runs this command', () => {
    const manifest = JSON.parse(readFileSync(join(OK_ROOT, 'package.json'), 'utf8'));
    expect(manifest.scripts['known-reds']).toBe('node scripts/known-reds.mjs');
  });
});