Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Add gate atoms and title chains to the known-reds feed (#5133)

Nick Gomez418e0155f30b
diff --git a/scripts/check-known-reds.uncached.test.mjs b/scripts/check-known-reds.uncached.test.mjs
index 3e1b3867d..cdf2215d8 100644
--- a/scripts/check-known-reds.uncached.test.mjs
+++ b/scripts/check-known-reds.uncached.test.mjs
@@ -20,6 +20,7 @@ import {
OWNERS,
QUARANTINE_TAG,
render,
+ SCHEMA_VERSION,
scanSource,
scanTree,
todayUtc,
@@ -78,6 +79,7 @@ describe('known-reds scanner: pins and quarantines', () => {
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',
@@ -357,6 +359,395 @@ describe('known-reds scanner: CI-keyed skips', () => {
});
});
+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: 'runtime', 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' }]],
+ ])('reads the atoms of %s', (source, atoms) => {
+ expect(atomsOf(source)).toEqual([atoms]);
+ });
+
+ 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: 'runtime', 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: 'runtime', 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: 'runtime', 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: 'runtime', 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).toEqual([{ kind: 'runtime', name: condition, text: condition }]);
+ 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: 'runtime', 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); });",
@@ -688,7 +1079,7 @@ describe('known-reds through its real invocation', () => {
});
expect(run.status).toBe(1);
const feed = JSON.parse(run.stdout);
- expect(feed.schemaVersion).toBe(1);
+ expect(feed.schemaVersion).toBe(2);
expect(feed.files).toBe(3);
expect(feed.violations.map((violation) => violation.rule)).toEqual(
expect.arrayContaining(['pin-retries', 'ci-skip', 'early-return']),
@@ -769,6 +1160,11 @@ describe('known-reds through its real invocation', () => {
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(
@@ -784,8 +1180,17 @@ describe('known-reds on this tree', () => {
).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(scanTree(OK_ROOT), {
+ const violations = validate(tree(), {
today: todayUtc(),
allowlist: loadAllowlist(),
});
@@ -815,6 +1220,7 @@ describe('known-reds on this tree', () => {
`no more than ${MAX_HORIZON_DAYS} days away`,
`at least ${MIN_SIGNATURE_LITERAL} literal characters in a row`,
`Expiring within ${EXPIRY_WARNING_DAYS} days`,
+ `(\`schemaVersion\` ${SCHEMA_VERSION})`,
]) {
expect(doc, `${CONVENTION_DOC} must mention ${cited}`).toContain(cited);
}
diff --git a/scripts/known-reds.mjs b/scripts/known-reds.mjs
index af3500913..799c95e17 100644
--- a/scripts/known-reds.mjs
+++ b/scripts/known-reds.mjs
@@ -11,7 +11,7 @@ export const OK_ROOT = fileURLToPath(new URL('..', import.meta.url));
export const ALLOWLIST_PATH = fileURLToPath(
new URL('./known-reds-allowlist.json', import.meta.url),
);
-export const SCHEMA_VERSION = 1;
+export const SCHEMA_VERSION = 2;
export const KNOWN_BUG_TAG = 'known-bug';
export const QUARANTINE_TAG = 'quarantine';
export const OWNERS = Object.freeze(['get-main-green', 'known-reds']);
@@ -257,8 +257,7 @@ function isEnvObject(node) {
function ciAtom(node, aliases) {
if (ts.isIdentifier(node)) {
if (!isExpressionIdentifier(node)) return null;
- if (aliases.has(node.text)) return aliases.get(node.text);
- return CI_IDENTIFIERS.has(node.text) ? 'positive' : null;
+ return aliases(node);
}
if (
ts.isPropertyAccessExpression(node) &&
@@ -356,70 +355,50 @@ function ciValue(node, aliases, onCi) {
return null;
}
-function declarationsAtAnyDepth(sourceFile, kinds) {
- const declarations = [];
- const collect = (node) => {
- if (
- ts.isVariableDeclaration(node) &&
- ts.isIdentifier(node.name) &&
- node.initializer &&
- !skipTernary(node.initializer, kinds)
- ) {
- declarations.push(node);
- }
- ts.forEachChild(node, collect);
- };
- collect(sourceFile);
- return declarations;
-}
-
-function ciAliases(sourceFile, kinds) {
- const declarations = declarationsAtAnyDepth(sourceFile, kinds);
+function ciAliases() {
const aliases = new Map();
- for (let pass = 0; pass < 3; pass += 1) {
- for (const declaration of declarations) {
- if (!containsCi(declaration.initializer, aliases)) continue;
- const onCi = ciValue(declaration.initializer, aliases, true);
- const offCi = ciValue(declaration.initializer, aliases, false);
- const polarity =
+ const following = new Set();
+ const resolve = (identifier) => {
+ const binding = visibleBinding(identifier, identifier.text);
+ if (!binding) return CI_IDENTIFIERS.has(identifier.text) ? 'positive' : null;
+ const { initializer } = binding;
+ if (!initializer || following.has(initializer)) return null;
+ if (aliases.has(initializer)) return aliases.get(initializer);
+ following.add(initializer);
+ let polarity = null;
+ if (containsCi(initializer, resolve)) {
+ const onCi = ciValue(initializer, resolve, true);
+ const offCi = ciValue(initializer, resolve, false);
+ polarity =
onCi === true && offCi === false
? 'positive'
: onCi === false && offCi === true
? 'negative'
: 'unknown';
- aliases.set(declaration.name.text, polarity);
}
- }
- return aliases;
+ following.delete(initializer);
+ aliases.set(initializer, polarity);
+ return polarity;
+ };
+ return resolve;
}
-const PROCESS_ENVIRONMENT = new Set([
- 'platform',
- 'arch',
- 'env',
- 'getuid',
- 'getgid',
- 'versions',
- 'release',
+const PROCESS_ATOMS = new Map([
+ ['platform', 'platform'],
+ ['arch', 'arch'],
+ ['getuid', 'uid'],
+ ['getgid', 'uid'],
+ ['versions', 'runtime'],
+ ['release', 'runtime'],
]);
+const PROCESS_ENVIRONMENT = new Set(['env', ...PROCESS_ATOMS.keys()]);
const OS_MODULES = new Set(['os', 'node:os']);
const FS_PRESENCE = new Set(['existsSync']);
-function environmentImports(sourceFile) {
- const names = new Set();
- const namespaces = new Set();
- for (const statement of sourceFile.statements) {
- if (!ts.isImportDeclaration(statement) || !ts.isStringLiteral(statement.moduleSpecifier))
- continue;
- if (!OS_MODULES.has(statement.moduleSpecifier.text)) continue;
- const clause = statement.importClause;
- if (clause?.name) namespaces.add(clause.name.text);
- const named = clause?.namedBindings;
- if (named && ts.isNamespaceImport(named)) namespaces.add(named.name.text);
- if (named && ts.isNamedImports(named))
- for (const element of named.elements) names.add(element.name.text);
- }
- return { names, namespaces };
+function osImport(identifier) {
+ if (!identifier || !ts.isIdentifier(identifier)) return null;
+ const imported = visibleBinding(identifier, identifier.text)?.imported;
+ return imported && OS_MODULES.has(imported.module) ? imported : null;
}
function isEnvironmentAtom(node, environment) {
@@ -432,10 +411,11 @@ function isEnvironmentAtom(node, environment) {
PROCESS_ENVIRONMENT.has(node.name.text)
)
return true;
- if (ts.isIdentifier(target) && environment.imports.namespaces.has(target.text)) return true;
+ if (osImport(target)?.namespace) return true;
}
if (ts.isIdentifier(node) && isExpressionIdentifier(node)) {
- return environment.imports.names.has(node.text) || environment.aliases.has(node.text);
+ const imported = osImport(node);
+ return Boolean(imported && !imported.namespace) || environment.aliases(node);
}
if (ts.isCallExpression(node)) {
const callee = unwrap(node.expression);
@@ -464,19 +444,22 @@ function dependsOnEnvironment(node, environment) {
return found;
}
-function environmentBindings(sourceFile, ciAliasMap, kinds) {
+function environmentBindings(ciAliasMap) {
+ const aliases = new Map();
+ const following = new Set();
const environment = {
ciAliases: ciAliasMap,
- imports: environmentImports(sourceFile),
- aliases: new Set(),
+ aliases: (identifier) => {
+ const initializer = visibleBinding(identifier, identifier.text)?.initializer;
+ if (!initializer || following.has(initializer)) return false;
+ if (aliases.has(initializer)) return aliases.get(initializer);
+ following.add(initializer);
+ const depends = dependsOnEnvironment(initializer, environment);
+ following.delete(initializer);
+ aliases.set(initializer, depends);
+ return depends;
+ },
};
- const declarations = declarationsAtAnyDepth(sourceFile, kinds);
- for (let pass = 0; pass < 3; pass += 1) {
- for (const declaration of declarations) {
- if (dependsOnEnvironment(declaration.initializer, environment))
- environment.aliases.add(declaration.name.text);
- }
- }
return environment;
}
@@ -487,6 +470,351 @@ function ciEffect(condition, skipWhen, aliases) {
return skipsOnCi === false ? 'runs-only-on-ci' : 'skips-on-ci';
}
+const LOGICAL = new Set([
+ ts.SyntaxKind.AmpersandAmpersandToken,
+ ts.SyntaxKind.BarBarToken,
+ ts.SyntaxKind.QuestionQuestionToken,
+]);
+const COMPARISON = new Set([
+ ...EQUALITY,
+ ...INEQUALITY,
+ ts.SyntaxKind.LessThanToken,
+ ts.SyntaxKind.LessThanEqualsToken,
+ ts.SyntaxKind.GreaterThanToken,
+ ts.SyntaxKind.GreaterThanEqualsToken,
+]);
+const PROCESS_KEYED = new Set(['versions', 'release']);
+const CONVERSIONS = new Set(['Boolean', 'Number', 'String', 'parseInt', 'parseFloat']);
+const OS_ATOMS = new Map([
+ ['platform', 'platform'],
+ ['type', 'platform'],
+ ['release', 'platform'],
+ ['arch', 'arch'],
+ ['machine', 'arch'],
+ ['userInfo', 'uid'],
+]);
+
+function memberPath(node) {
+ const members = [];
+ let current = unwrap(node);
+ while (current) {
+ if (ts.isPropertyAccessExpression(current)) {
+ members.unshift(current.name.text);
+ current = unwrap(current.expression);
+ } else if (ts.isElementAccessExpression(current)) {
+ members.unshift(stringValue(current.argumentExpression) ?? '[]');
+ current = unwrap(current.expression);
+ } else if (ts.isCallExpression(current)) {
+ current = unwrap(current.expression);
+ } else {
+ break;
+ }
+ }
+ return { root: current && ts.isIdentifier(current) ? current : null, members };
+}
+
+function envKey(node) {
+ const value = unwrap(node);
+ if (ts.isPropertyAccessExpression(value) && isEnvObject(value.expression)) return value.name.text;
+ if (ts.isElementAccessExpression(value) && isEnvObject(value.expression))
+ return stringValue(value.argumentExpression);
+ return undefined;
+}
+
+function probesFilesystem(node) {
+ let found = false;
+ const visit = (current) => {
+ if (found) return;
+ if (ts.isIdentifier(current) && FS_PRESENCE.has(current.text)) {
+ found = true;
+ return;
+ }
+ ts.forEachChild(current, visit);
+ };
+ visit(node);
+ return found;
+}
+
+function importSpecifier(node, sourceFile) {
+ let found = null;
+ const visit = (current) => {
+ if (found !== null) return;
+ if (ts.isCallExpression(current)) {
+ const callee = unwrap(current.expression);
+ const dynamicImport = current.expression.kind === ts.SyntaxKind.ImportKeyword;
+ const require = ts.isIdentifier(callee) && callee.text === 'require';
+ const resolve =
+ ts.isPropertyAccessExpression(callee) &&
+ callee.name.text === 'resolve' &&
+ ['require', 'createRequire'].includes(rootIdentifier(callee.expression));
+ if (dynamicImport || require || resolve) {
+ const [first] = current.arguments;
+ found = first ? (stringValue(first) ?? oneLine(first, sourceFile)) : '';
+ return;
+ }
+ }
+ ts.forEachChild(current, visit);
+ };
+ visit(node);
+ return found;
+}
+
+function bindsName(name, target) {
+ if (ts.isIdentifier(name)) return name.text === target;
+ if (ts.isObjectBindingPattern(name) || ts.isArrayBindingPattern(name)) {
+ return name.elements.some(
+ (element) => !ts.isOmittedExpression(element) && bindsName(element.name, target),
+ );
+ }
+ return false;
+}
+
+function variableBinding(list, target) {
+ const declaration = list.declarations.find((entry) => bindsName(entry.name, target));
+ return declaration
+ ? {
+ initializer: ts.isIdentifier(declaration.name) ? (declaration.initializer ?? null) : null,
+ }
+ : null;
+}
+
+function statementBinding(statement, target) {
+ if (ts.isVariableStatement(statement)) return variableBinding(statement.declarationList, target);
+ if (
+ (ts.isFunctionDeclaration(statement) ||
+ ts.isClassDeclaration(statement) ||
+ ts.isEnumDeclaration(statement) ||
+ ts.isModuleDeclaration(statement) ||
+ (ts.isImportEqualsDeclaration(statement) && !statement.isTypeOnly)) &&
+ statement.name &&
+ bindsName(statement.name, target)
+ ) {
+ return { initializer: null };
+ }
+ if (ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly) {
+ const clause = statement.importClause;
+ const named = clause?.namedBindings;
+ let imported = null;
+ if (
+ clause?.name?.text === target ||
+ (named && ts.isNamespaceImport(named) && named.name.text === target)
+ ) {
+ imported = { namespace: true };
+ } else if (named && ts.isNamedImports(named)) {
+ const element = named.elements.find(
+ (entry) => !entry.isTypeOnly && entry.name.text === target,
+ );
+ if (element)
+ imported = { namespace: false, name: (element.propertyName ?? element.name).text };
+ }
+ if (imported) {
+ return {
+ initializer: null,
+ imported: { ...imported, module: stringValue(statement.moduleSpecifier) },
+ };
+ }
+ }
+ return null;
+}
+
+function hoistedVariableBinding(scope, target) {
+ let binding = null;
+ const visit = (node) => {
+ if (binding || ts.isFunctionLike(node) || ts.isClassLike(node) || ts.isModuleDeclaration(node))
+ return;
+ if (ts.isVariableDeclarationList(node) && !(node.flags & ts.NodeFlags.BlockScoped)) {
+ binding = variableBinding(node, target);
+ if (binding) return;
+ }
+ ts.forEachChild(node, visit);
+ };
+ ts.forEachChild(scope, visit);
+ return binding;
+}
+
+function visibleBinding(identifier, target) {
+ let child = identifier;
+ for (let scope = identifier.parent; scope; child = scope, scope = scope.parent) {
+ if ((ts.isFunctionExpression(scope) || ts.isClassLike(scope)) && scope.name?.text === target) {
+ return { initializer: null };
+ }
+ if (
+ ts.isFunctionLike(scope) &&
+ scope.parameters.some((parameter) => bindsName(parameter.name, target))
+ ) {
+ return { initializer: null };
+ }
+ if (
+ (ts.isForStatement(scope) || ts.isForOfStatement(scope) || ts.isForInStatement(scope)) &&
+ scope.initializer &&
+ ts.isVariableDeclarationList(scope.initializer) &&
+ variableBinding(scope.initializer, target)
+ ) {
+ return { initializer: null };
+ }
+ if (
+ ts.isCatchClause(scope) &&
+ scope.variableDeclaration &&
+ bindsName(scope.variableDeclaration.name, target)
+ ) {
+ return { initializer: null };
+ }
+ if (
+ ts.isSourceFile(scope) ||
+ ts.isBlock(scope) ||
+ ts.isModuleBlock(scope) ||
+ ts.isCaseBlock(scope)
+ ) {
+ const statements = ts.isCaseBlock(scope)
+ ? scope.clauses.flatMap((clause) => clause.statements)
+ : scope.statements;
+ for (const statement of statements) {
+ const binding = statementBinding(statement, target);
+ if (binding) return binding;
+ }
+ }
+ if (
+ ts.isSourceFile(scope) ||
+ ts.isModuleBlock(scope) ||
+ ts.isClassStaticBlockDeclaration(scope) ||
+ (ts.isFunctionLike(scope) && child === scope.body)
+ ) {
+ const binding = hoistedVariableBinding(scope, target);
+ if (binding) return binding;
+ }
+ if (ts.isFunctionLike(scope) && !ts.isArrowFunction(scope) && target === 'arguments') {
+ return { initializer: null };
+ }
+ }
+ return null;
+}
+
+function conditionAtoms(condition, context) {
+ const { sourceFile } = context;
+ const atoms = [];
+ const seen = new Set();
+ const following = new Set();
+ const add = (kind, name, textNode) => {
+ const atom = { kind, name, text: oneLine(textNode, sourceFile) };
+ const key = JSON.stringify(atom);
+ if (seen.has(key)) return;
+ seen.add(key);
+ atoms.push(atom);
+ };
+ const envAtom = (name, textNode) =>
+ add(name !== null && CI_ENV_NAMES.has(name) ? 'ci' : 'env', name ?? '[]', textNode);
+ const leaf = (node, textNode) => {
+ const key = envKey(node);
+ if (key !== undefined) {
+ envAtom(key, textNode);
+ return;
+ }
+ if (ts.isCallExpression(node)) {
+ const callee = unwrap(node.expression);
+ const name = ts.isIdentifier(callee)
+ ? callee.text
+ : ts.isPropertyAccessExpression(callee)
+ ? callee.name.text
+ : null;
+ if (name !== null && FS_PRESENCE.has(name)) {
+ const [first] = node.arguments;
+ add('fs', first ? oneLine(first, sourceFile) : name, textNode);
+ return;
+ }
+ }
+ const { root, members } = memberPath(node);
+ if (root?.text === 'process' && PROCESS_ATOMS.has(members[0])) {
+ const keyed = PROCESS_KEYED.has(members[0]) && members[1] && members[1] !== '[]';
+ add(
+ PROCESS_ATOMS.get(members[0]),
+ ['process', ...members.slice(0, keyed ? 2 : 1)].join('.'),
+ textNode,
+ );
+ return;
+ }
+ const imported = osImport(root);
+ if (imported?.namespace && members.length > 0) {
+ add(OS_ATOMS.get(members[0]) ?? 'runtime', `os.${members[0]}`, textNode);
+ return;
+ }
+ if (imported && !imported.namespace) {
+ const original = imported.name;
+ add(OS_ATOMS.get(original) ?? 'runtime', `os.${original}`, textNode);
+ return;
+ }
+ if (ts.isIdentifier(node)) {
+ const binding = visibleBinding(node, node.text);
+ const initializer = binding?.initializer ?? null;
+ if (initializer && !following.has(initializer)) {
+ const specifier = importSpecifier(initializer, sourceFile);
+ if (specifier !== null) {
+ add('import', specifier, textNode);
+ return;
+ }
+ following.add(initializer);
+ visit(initializer, null);
+ following.delete(initializer);
+ return;
+ }
+ if (!binding && CI_IDENTIFIERS.has(node.text)) {
+ add('ci', node.text, textNode);
+ return;
+ }
+ }
+ add(probesFilesystem(node) ? 'fs' : 'runtime', oneLine(node, sourceFile), textNode);
+ };
+ const visit = (raw, textNode) => {
+ const node = unwrap(raw);
+ if (!node) return;
+ if (ts.isAwaitExpression(node)) {
+ visit(node.expression, textNode);
+ return;
+ }
+ if (ts.isPrefixUnaryExpression(node) && node.operator === ts.SyntaxKind.ExclamationToken) {
+ visit(node.operand, textNode);
+ return;
+ }
+ if (ts.isConditionalExpression(node)) {
+ for (const part of [node.condition, node.whenTrue, node.whenFalse]) visit(part, null);
+ return;
+ }
+ if (ts.isBinaryExpression(node)) {
+ const operator = node.operatorToken.kind;
+ if (LOGICAL.has(operator)) {
+ visit(node.left, null);
+ visit(node.right, null);
+ return;
+ }
+ if (COMPARISON.has(operator)) {
+ for (const side of [node.left, node.right])
+ if (literalTruth(side) === null) visit(side, textNode ?? node);
+ return;
+ }
+ if (operator === ts.SyntaxKind.InKeyword && isEnvObject(node.right)) {
+ envAtom(stringValue(node.left), textNode ?? node);
+ return;
+ }
+ }
+ if (
+ ts.isCallExpression(node) &&
+ ts.isIdentifier(node.expression) &&
+ CONVERSIONS.has(node.expression.text) &&
+ node.arguments.length > 0
+ ) {
+ visit(node.arguments[0], textNode);
+ return;
+ }
+ if (ts.isTypeOfExpression(node)) {
+ leaf(unwrap(node.expression), textNode ?? node);
+ return;
+ }
+ if (literalTruth(node) !== null) return;
+ leaf(node, textNode ?? node);
+ };
+ visit(condition, null);
+ return atoms;
+}
+
function enclosingCondition(node, boundary) {
let child = node;
let current = node.parent;
@@ -684,6 +1012,23 @@ function scopeOf(node, kinds) {
return 'file';
}
+function titleChain(node, kinds, sourceFile) {
+ const chain = [];
+ for (let current = node; current; current = current.parent) {
+ if (!ts.isCallExpression(current)) continue;
+ const info = runnerCall(current, kinds);
+ const kind = info ? declarationKind(info.ref) : null;
+ if (kind !== 'test' && kind !== 'describe') continue;
+ const parts = declarationParts(current);
+ if (!parts.fn && !info.ref.members.includes('todo')) continue;
+ const first = current.arguments[0] ? unwrap(current.arguments[0]) : null;
+ if (!first || isFunction(first)) continue;
+ const literal = stringValue(first);
+ chain.unshift(literal ?? { nonLiteral: oneLine(first, sourceFile) });
+ }
+ return chain;
+}
+
export function scanSource(path, source) {
const sourceFile = ts.createSourceFile(
path,
@@ -694,8 +1039,11 @@ export function scanSource(path, source) {
);
const runner = PLAYWRIGHT_FILE.test(path) ? 'playwright' : 'vitest';
const kinds = runnerBindings(sourceFile);
- const aliases = ciAliases(sourceFile, kinds);
- const environment = environmentBindings(sourceFile, aliases, kinds);
+ const aliases = ciAliases();
+ const environment = environmentBindings(aliases);
+ const atomContext = { sourceFile };
+ const titlesFor = (node, scope) =>
+ scope === 'test' || scope === 'describe' ? { titles: titleChain(node, kinds, sourceFile) } : {};
const scan = {
path,
runner,
@@ -720,10 +1068,20 @@ export function scanSource(path, source) {
skipWhen,
ci: condition ? ciEffect(condition, skipWhen, aliases) : null,
reason,
+ atoms: condition ? conditionAtoms(condition, atomContext) : [],
+ ...titlesFor(node, scope),
});
};
const notRun = (node, form, scope, title, reason = '') =>
- scan.notRun.push({ path, line: lineOf(node), form, scope, title, reason });
+ scan.notRun.push({
+ path,
+ line: lineOf(node),
+ form,
+ scope,
+ title,
+ reason,
+ ...titlesFor(node, scope),
+ });
const inspectTestBody = (fn, via) => {
const context = via === 'each' ? undefined : fn.parameters[via === 'for' ? 1 : 0]?.name;
@@ -851,7 +1209,14 @@ export function scanSource(path, source) {
`write the issue, owner and until ${runner === 'playwright' ? 'annotations' : 'meta'} as inline string literals`,
);
}
- const record = { path, line: lineOf(call), runner, title, ...fields };
+ const record = {
+ path,
+ line: lineOf(call),
+ runner,
+ title,
+ titles: titleChain(call, kinds, sourceFile),
+ ...fields,
+ };
if (isPin && isQuarantine)
problem(
call,
diff --git a/test-support/KNOWN-REDS.md b/test-support/KNOWN-REDS.md
index c263867fb..83111384c 100644
--- a/test-support/KNOWN-REDS.md
+++ b/test-support/KNOWN-REDS.md
@@ -83,4 +83,6 @@ Use `test.todo('title')`.
- `pnpm known-reds` prints the pins, the quarantines and the CI-keyed skips.
- `--all` adds every test that does not run and every environment gate.
-- `--json` prints the full feed (`schemaVersion` 1).
+- `--json` prints the full feed (`schemaVersion` 2). Beyond the listing, it carries:
+ - `atoms` on each CI skip and environment gate: the facts its condition reads, following each name to the declaration visible where the gate sits. Each is `{ kind, name, text }`, and `kind` is `platform`, `arch`, `uid`, `env`, `ci`, `fs`, `import` or `runtime`. `runtime` covers what the scanner cannot resolve, such as a call to a helper, and also resolved reads of `process.versions` or `process.release`, which keep their full name.
+ - `titles` on every pin and quarantine, and on each other entry scoped to a test or describe: the enclosing describe titles, ending with the entry's own declaration title, so a describe-scoped gate ends with its describe's title. A title that is not a string literal appears as `{ nonLiteral: <source> }`.