Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
import { spawnSync } from 'node:child_process';
import { existsSync, readFileSync } from 'node:fs';
import { createRequire } from 'node:module';
import { join, resolve } from 'node:path';
import { fileURLToPath } from 'node:url';
import {
HORIZON_DAYS,
horizonProblem,
reviewState,
todayUtc,
trackingProblems,
} from './deviations/contract.mjs';
import { gitCleanEnv } from './git-clean-env.mjs';
export { todayUtc };
const ts = createRequire(import.meta.url)('typescript');
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 = 4;
export const KNOWN_BUG_TAG = 'known-bug';
export const QUARANTINE_TAG = 'quarantine';
export const OWNERS = Object.freeze(['get-main-green', 'known-reds']);
export const MAX_HORIZON_DAYS = HORIZON_DAYS;
export const EXCLUDED_PREFIXES = Object.freeze(['reports/', 'specs/']);
export const CONVENTION_DOC = 'test-support/KNOWN-REDS.md';
export const MIN_SIGNATURE_LITERAL = 4;
export const EXPIRY_WARNING_DAYS = 14;
const TEST_FILE = /\.test\.[cm]?[jt]sx?$|\.e2e\.tsx?$|\.test-helper\.[cm]?[jt]sx?$/;
const PLAYWRIGHT_FILE = /\.e2e\.tsx?$/;
const RUNNER_KINDS = new Map([
['test', 'test'],
['it', 'test'],
['describe', 'describe'],
['suite', 'describe'],
]);
const HOOKS = new Set(['beforeEach', 'afterEach', 'beforeAll', 'afterAll']);
const NON_DECLARING = new Set([
'configure',
'use',
'step',
'extend',
'info',
'setTimeout',
'slow',
'expect',
]);
const NOT_RUN_MODIFIERS = new Set(['skip', 'fixme', 'todo']);
const BARE_EXPECTED_FAILURE = new Set(['fails', 'fail']);
const ANNOTATION_MODIFIERS = new Set(['skip', 'fixme', 'fail', 'slow']);
const CI_ENV_NAMES = new Set([
'CI',
'GITHUB_ACTIONS',
'GITHUB_RUN_ID',
'GITHUB_WORKFLOW',
'RUNNER_OS',
]);
const CI_IDENTIFIERS = new Set(['CI', 'IS_CI', 'isCI', 'isCi', 'ON_CI', 'onCI', 'IN_CI', 'inCI']);
const CI_INFO_MODULE = 'ci-info';
const CI_INFO_FLAG = 'isCI';
const FIELDS = ['issue', 'owner', 'until'];
export const ALLOWANCE_FIELDS = Object.freeze(['issue', 'owner', 'until', 'reason', 'exit']);
function scriptKind(path) {
if (path.endsWith('.tsx')) return ts.ScriptKind.TSX;
if (/\.[cm]?ts$/.test(path)) return ts.ScriptKind.TS;
if (path.endsWith('.jsx')) return ts.ScriptKind.JSX;
return ts.ScriptKind.JS;
}
function unwrap(node) {
let current = node;
while (
current &&
(ts.isParenthesizedExpression(current) ||
ts.isAsExpression(current) ||
ts.isNonNullExpression(current) ||
ts.isSatisfiesExpression(current) ||
ts.isTypeAssertionExpression(current))
) {
current = current.expression;
}
return current;
}
function isFunction(node) {
return Boolean(node) && (ts.isArrowFunction(node) || ts.isFunctionExpression(node));
}
function isTitle(node) {
return (
Boolean(node) &&
(ts.isStringLiteral(node) ||
ts.isNoSubstitutionTemplateLiteral(node) ||
ts.isTemplateExpression(node))
);
}
function stringValue(node) {
const value = unwrap(node);
return value && (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value))
? value.text
: null;
}
function oneLine(node, sourceFile) {
return node.getText(sourceFile).replace(/\s+/g, ' ').trim();
}
function propertyName(property) {
const { name } = property;
if (name && (ts.isIdentifier(name) || ts.isStringLiteral(name))) return name.text;
return null;
}
function objectProperty(object, name) {
return object.properties.find(
(property) =>
(ts.isPropertyAssignment(property) || ts.isShorthandPropertyAssignment(property)) &&
propertyName(property) === name,
);
}
function chainOf(node) {
const members = [];
let current = unwrap(node);
while (current && ts.isPropertyAccessExpression(current)) {
members.unshift(current.name.text);
current = unwrap(current.expression);
}
return { root: current, members };
}
function runnerRef(node, kinds) {
const { root, members } = chainOf(node);
if (!root || !ts.isIdentifier(root) || !kinds.has(root.text)) return null;
return {
root: root.text,
members,
kind: members.includes('describe') ? 'describe' : kinds.get(root.text),
};
}
function isSkipVariant(ref) {
return ref.members.includes('skip') || ref.members.includes('fixme');
}
function skipTernary(node, kinds) {
const value = unwrap(node);
if (!value || !ts.isConditionalExpression(value)) return null;
const whenTrue = runnerRef(value.whenTrue, kinds);
const whenFalse = runnerRef(value.whenFalse, kinds);
if (!whenTrue || !whenFalse || isSkipVariant(whenTrue) === isSkipVariant(whenFalse)) return null;
return {
condition: value.condition,
skipWhen: isSkipVariant(whenTrue) ? 'condition' : 'negation',
ref: isSkipVariant(whenTrue) ? whenFalse : whenTrue,
};
}
function runnerBindings(sourceFile) {
const kinds = new Map(RUNNER_KINDS);
for (const statement of sourceFile.statements) {
if (!ts.isImportDeclaration(statement)) continue;
const named = statement.importClause?.namedBindings;
if (!named || !ts.isNamedImports(named)) continue;
for (const element of named.elements) {
const kind = RUNNER_KINDS.get((element.propertyName ?? element.name).text);
if (kind) kinds.set(element.name.text, kind);
}
}
const visit = (node) => {
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
const ternary = skipTernary(node.initializer, kinds);
if (ternary) kinds.set(node.name.text, ternary.ref.kind);
}
ts.forEachChild(node, visit);
};
visit(sourceFile);
return kinds;
}
function runnerCall(call, kinds) {
const callee = unwrap(call.expression);
const ternary = skipTernary(callee, kinds);
if (ternary) {
return {
ref: ternary.ref,
gate: { form: 'ternary', condition: ternary.condition, skipWhen: ternary.skipWhen },
};
}
if (ts.isCallExpression(callee)) {
const inner = runnerRef(callee.expression, kinds);
if (!inner) return null;
const last = inner.members.at(-1);
const ref = { ...inner, members: inner.members.slice(0, -1) };
if (last === 'skipIf' || last === 'runIf') {
return {
ref,
gate: {
form: last,
condition: callee.arguments[0] ?? null,
skipWhen: last === 'skipIf' ? 'condition' : 'negation',
},
};
}
return last === 'each' || last === 'for' ? { ref, gate: null, via: last } : null;
}
const ref = runnerRef(callee, kinds);
return ref ? { ref, gate: null } : null;
}
function declarationKind(ref) {
if (
HOOKS.has(ref.root) ||
ref.members.some((member) => HOOKS.has(member) || NON_DECLARING.has(member))
) {
return 'other';
}
return ref.kind;
}
function declarationParts(call) {
const args = call.arguments.map(unwrap);
const fn = [...args].reverse().find(isFunction) ?? null;
const options = args.slice(1).find((arg) => ts.isObjectLiteralExpression(arg)) ?? null;
return { title: isTitle(args[0]) ? args[0] : null, fn, options };
}
function rootIdentifier(node) {
let current = unwrap(node);
while (current && (ts.isPropertyAccessExpression(current) || ts.isCallExpression(current))) {
current = unwrap(current.expression);
}
return current && ts.isIdentifier(current) ? current.text : null;
}
function isAssertionCall(node) {
if (!ts.isCallExpression(node)) return false;
const root = rootIdentifier(node.expression);
return root !== null && /^(expect|assert)/.test(root);
}
function isExpressionIdentifier(node) {
const { parent } = node;
if (!parent) return true;
if (ts.isPropertyAccessExpression(parent) && parent.name === node) return false;
if ((ts.isPropertyAssignment(parent) || ts.isBindingElement(parent)) && parent.name === node)
return false;
if (ts.isVariableDeclaration(parent) && parent.name === node) return false;
if (ts.isPropertyAssignment(parent) && parent.propertyName === node) return false;
return true;
}
function isProcessObject(node) {
const value = unwrap(node);
if (ts.isIdentifier(value)) return value.text === 'process';
return ts.isPropertyAccessExpression(value) && value.name.text === 'process';
}
function isEnvObject(node, seen = new Set()) {
const value = unwrap(node);
if (!value) return false;
if (ts.isPropertyAccessExpression(value)) return value.name.text === 'env';
if (!ts.isIdentifier(value)) return false;
if (value.text === 'env') return true;
const binding = visibleBinding(value, value.text);
if (binding?.destructured)
return binding.destructured.key === 'env' && isProcessObject(binding.destructured.from);
const initializer = binding?.initializer;
if (!initializer || seen.has(initializer)) return false;
seen.add(initializer);
return isEnvObject(initializer, seen);
}
function constantString(node, seen = new Set()) {
const direct = stringValue(node);
if (direct !== null) return direct;
const value = unwrap(node);
if (!value || !ts.isIdentifier(value)) return null;
const initializer = visibleBinding(value, value.text)?.initializer;
if (!initializer || seen.has(initializer)) return null;
seen.add(initializer);
return constantString(initializer, seen);
}
function localHelperResult(call) {
if (!ts.isCallExpression(call) || call.arguments.length > 0) return null;
const callee = unwrap(call.expression);
if (!ts.isIdentifier(callee)) return null;
const binding = visibleBinding(callee, callee.text);
const initializer = binding?.initializer ? unwrap(binding.initializer) : null;
const fn = binding?.declaration ?? (isFunction(initializer) ? initializer : null);
if (!fn?.body || fn.parameters.length > 0) return null;
if (!ts.isBlock(fn.body)) return fn.body;
const [only] = fn.body.statements;
return fn.body.statements.length === 1 && ts.isReturnStatement(only)
? (only.expression ?? null)
: null;
}
function isCiInfoNamespace(node) {
const value = unwrap(node);
if (!value || !ts.isIdentifier(value)) return false;
const imported = visibleBinding(value, value.text)?.imported;
return Boolean(imported?.namespace) && imported.module === CI_INFO_MODULE;
}
function isCiInfoFlag(imported) {
return (
imported?.module === CI_INFO_MODULE && !imported.namespace && imported.name === CI_INFO_FLAG
);
}
function ciAtom(node, aliases) {
if (ts.isIdentifier(node)) {
if (!isExpressionIdentifier(node)) return null;
return aliases(node);
}
if (ts.isPropertyAccessExpression(node)) {
if (CI_ENV_NAMES.has(node.name.text) && isEnvObject(node.expression)) return 'positive';
if (node.name.text === CI_INFO_FLAG && isCiInfoNamespace(node.expression)) return 'positive';
return null;
}
if (ts.isElementAccessExpression(node) && isEnvObject(node.expression)) {
const key = constantString(node.argumentExpression);
return key !== null && CI_ENV_NAMES.has(key) ? 'positive' : null;
}
if (
ts.isBinaryExpression(node) &&
node.operatorToken.kind === ts.SyntaxKind.InKeyword &&
isEnvObject(node.right)
) {
const key = constantString(node.left);
return key !== null && CI_ENV_NAMES.has(key) ? 'positive' : null;
}
const result = ts.isCallExpression(node) ? localHelperResult(node) : null;
return result ? aliases(result) : null;
}
function containsCi(node, aliases) {
let found = false;
const visit = (current) => {
if (found) return;
if (ciAtom(current, aliases)) {
found = true;
return;
}
if (isFunction(current) || ts.isFunctionDeclaration(current)) return;
ts.forEachChild(current, visit);
};
visit(node);
return found;
}
function literalTruth(node) {
const value = unwrap(node);
if (value.kind === ts.SyntaxKind.TrueKeyword) return true;
if (value.kind === ts.SyntaxKind.FalseKeyword || value.kind === ts.SyntaxKind.NullKeyword)
return false;
if (ts.isIdentifier(value) && value.text === 'undefined') return false;
if (ts.isStringLiteral(value) || ts.isNoSubstitutionTemplateLiteral(value)) {
return !['', '0', 'false'].includes(value.text);
}
if (ts.isNumericLiteral(value)) return Number(value.text) !== 0;
return null;
}
const EQUALITY = new Set([ts.SyntaxKind.EqualsEqualsEqualsToken, ts.SyntaxKind.EqualsEqualsToken]);
const INEQUALITY = new Set([
ts.SyntaxKind.ExclamationEqualsEqualsToken,
ts.SyntaxKind.ExclamationEqualsToken,
]);
function not(value) {
return value === null ? null : !value;
}
function ciValue(node, aliases, onCi) {
const value = unwrap(node);
if (!value || !containsCi(value, aliases)) return null;
const atom = ciAtom(value, aliases);
if (atom === 'positive') return onCi;
if (atom === 'negative') return !onCi;
if (atom === 'unknown') return null;
if (ts.isPrefixUnaryExpression(value) && value.operator === ts.SyntaxKind.ExclamationToken) {
return not(ciValue(value.operand, aliases, onCi));
}
if (ts.isBinaryExpression(value)) {
const operator = value.operatorToken.kind;
if (operator === ts.SyntaxKind.AmpersandAmpersandToken) {
const left = ciValue(value.left, aliases, onCi);
const right = ciValue(value.right, aliases, onCi);
if (left === false || right === false) return false;
return left === true && right === true ? true : null;
}
if (operator === ts.SyntaxKind.BarBarToken) {
const left = ciValue(value.left, aliases, onCi);
const right = ciValue(value.right, aliases, onCi);
if (left === true || right === true) return true;
return left === false && right === false ? false : null;
}
if (EQUALITY.has(operator) || INEQUALITY.has(operator)) {
const ciOnLeft = containsCi(value.left, aliases);
if (ciOnLeft === containsCi(value.right, aliases)) return null;
const side = ciValue(ciOnLeft ? value.left : value.right, aliases, onCi);
const truth = literalTruth(ciOnLeft ? value.right : value.left);
if (side === null || truth === null) return null;
return EQUALITY.has(operator) ? side === truth : side !== truth;
}
}
if (
ts.isCallExpression(value) &&
ts.isIdentifier(value.expression) &&
value.expression.text === 'Boolean' &&
value.arguments.length === 1
) {
return ciValue(value.arguments[0], aliases, onCi);
}
return null;
}
function ciAliases() {
const aliases = new Map();
const following = new Set();
const polarityOf = (expression) => {
if (following.has(expression)) return null;
if (aliases.has(expression)) return aliases.get(expression);
following.add(expression);
let polarity = null;
if (containsCi(expression, resolve)) {
const onCi = ciValue(expression, resolve, true);
const offCi = ciValue(expression, resolve, false);
polarity =
onCi === true && offCi === false
? 'positive'
: onCi === false && offCi === true
? 'negative'
: 'unknown';
}
following.delete(expression);
aliases.set(expression, polarity);
return polarity;
};
const resolve = (node) => {
if (!ts.isIdentifier(node)) return polarityOf(node);
const binding = visibleBinding(node, node.text);
if (!binding) return CI_IDENTIFIERS.has(node.text) ? 'positive' : null;
if (binding.destructured) {
const { key, from } = binding.destructured;
return CI_ENV_NAMES.has(key) && isEnvObject(from) ? 'positive' : null;
}
if (binding.imported) return isCiInfoFlag(binding.imported) ? 'positive' : null;
return binding.initializer ? polarityOf(binding.initializer) : null;
};
return resolve;
}
const PROCESS_ATOMS = new Map([
['platform', 'platform'],
['arch', 'arch'],
['getuid', 'uid'],
['getgid', 'uid'],
['geteuid', 'uid'],
['getegid', '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 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) {
if (ciAtom(node, environment.ciAliases)) return true;
if (ts.isPropertyAccessExpression(node)) {
const target = unwrap(node.expression);
if (
ts.isIdentifier(target) &&
target.text === 'process' &&
PROCESS_ENVIRONMENT.has(node.name.text)
)
return true;
if (osImport(target)?.namespace) return true;
}
if (ts.isIdentifier(node) && isExpressionIdentifier(node)) {
const imported = osImport(node);
return Boolean(imported && !imported.namespace) || environment.aliases(node);
}
if (ts.isCallExpression(node)) {
const callee = unwrap(node.expression);
const name = ts.isIdentifier(callee)
? callee.text
: ts.isPropertyAccessExpression(callee)
? callee.name.text
: null;
return name !== null && FS_PRESENCE.has(name);
}
return false;
}
function dependsOnEnvironment(node, environment) {
let found = false;
const visit = (current) => {
if (found) return;
if (isEnvironmentAtom(current, environment)) {
found = true;
return;
}
if (isFunction(current) || ts.isFunctionDeclaration(current)) return;
ts.forEachChild(current, visit);
};
visit(node);
return found;
}
function environmentBindings(ciAliasMap) {
const aliases = new Map();
const following = new Set();
const environment = {
ciAliases: ciAliasMap,
aliases: (identifier) => {
const binding = visibleBinding(identifier, identifier.text);
if (binding?.destructured) {
const { key, from } = binding.destructured;
return isEnvObject(from) || (isProcessObject(from) && PROCESS_ENVIRONMENT.has(key));
}
const initializer = binding?.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;
},
};
return environment;
}
function ciEffect(condition, skipWhen, aliases) {
if (!containsCi(condition, aliases)) return null;
const skipWhenTrue = ciValue(condition, aliases, true);
const skipsOnCi = skipWhen === 'condition' ? skipWhenTrue : not(skipWhenTrue);
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 constantString(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));
if (!declaration) return null;
if (ts.isIdentifier(declaration.name)) return { initializer: declaration.initializer ?? null };
const element = ts.isObjectBindingPattern(declaration.name)
? declaration.name.elements.find(
(entry) => ts.isIdentifier(entry.name) && entry.name.text === target,
)
: undefined;
const key =
element && !element.dotDotDotToken
? propertyName({ name: element.propertyName ?? element.name })
: null;
return {
initializer: null,
destructured:
key !== null && declaration.initializer ? { from: declaration.initializer, key } : null,
};
}
function statementBinding(statement, target) {
if (ts.isVariableStatement(statement)) return variableBinding(statement.declarationList, target);
if (ts.isFunctionDeclaration(statement) && statement.name && bindsName(statement.name, target)) {
return { initializer: null, declaration: statement };
}
if (
(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 result = localHelperResult(node);
if (result && !following.has(result)) {
following.add(result);
visit(result, null);
following.delete(result);
return;
}
}
if (
ts.isPropertyAccessExpression(node) &&
node.name.text === CI_INFO_FLAG &&
isCiInfoNamespace(node.expression)
) {
add('ci', CI_INFO_MODULE, 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);
if (binding?.imported) {
add(isCiInfoFlag(binding.imported) ? 'ci' : 'import', binding.imported.module, textNode);
return;
}
if (binding?.destructured) {
const { key, from } = binding.destructured;
if (isEnvObject(from)) {
envAtom(key, textNode);
return;
}
if (isProcessObject(from) && PROCESS_ATOMS.has(key)) {
add(PROCESS_ATOMS.get(key), `process.${key}`, textNode);
return;
}
}
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;
}
}
if (probesFilesystem(node)) {
add('fs', oneLine(node, sourceFile), textNode);
return;
}
add('unknown', oneLine(node, sourceFile), textNode);
if (ts.isCallExpression(node)) {
const callee = unwrap(node.expression);
if (ts.isPropertyAccessExpression(callee)) visit(callee.expression, null);
for (const argument of node.arguments) {
const value = unwrap(argument);
if (
!isFunction(value) &&
!ts.isArrayLiteralExpression(value) &&
!ts.isObjectLiteralExpression(value)
)
visit(argument, null);
}
}
};
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(constantString(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;
while (
current &&
current !== boundary &&
!isFunction(current) &&
!ts.isFunctionDeclaration(current)
) {
if (ts.isIfStatement(current) && child !== current.expression) {
return {
condition: current.expression,
skipWhen: child === current.thenStatement ? 'condition' : 'negation',
};
}
child = current;
current = current.parent;
}
return null;
}
function containsBefore(scope, position, predicate) {
let found = false;
const visit = (node) => {
if (found || node.getStart() >= position) return;
if (predicate(node)) {
found = true;
return;
}
ts.forEachChild(node, visit);
};
visit(scope);
return found;
}
function readTags(options, key) {
const property = options && objectProperty(options, key);
if (!property) return { tags: [], literal: true };
if (!ts.isPropertyAssignment(property)) return { tags: [], literal: false };
const value = unwrap(property.initializer);
const single = stringValue(value);
if (single !== null) return { tags: [single], literal: true };
if (!ts.isArrayLiteralExpression(value)) return { tags: [], literal: false };
const tags = value.elements.map(stringValue);
return tags.includes(null)
? { tags: tags.filter((tag) => tag !== null), literal: false }
: { tags, literal: true };
}
function readVitestFields(options) {
const property = options && objectProperty(options, 'meta');
if (!property) return { fields: {}, literal: true };
const value = ts.isPropertyAssignment(property) ? unwrap(property.initializer) : null;
if (!value || !ts.isObjectLiteralExpression(value)) return { fields: {}, literal: false };
const fields = {};
let literal = true;
for (const name of FIELDS) {
const field = objectProperty(value, name);
if (!field) continue;
const text = ts.isPropertyAssignment(field) ? stringValue(field.initializer) : null;
if (text === null) literal = false;
else fields[name] = text;
}
return { fields, literal };
}
function readPlaywrightFields(options) {
const property = options && objectProperty(options, 'annotation');
if (!property) return { fields: {}, literal: true };
const value = ts.isPropertyAssignment(property) ? unwrap(property.initializer) : null;
const entries =
value && ts.isArrayLiteralExpression(value) ? value.elements.map(unwrap) : [value];
const fields = {};
let literal = true;
for (const entry of entries) {
if (!entry || !ts.isObjectLiteralExpression(entry)) {
literal = false;
continue;
}
const typeProperty = objectProperty(entry, 'type');
const descriptionProperty = objectProperty(entry, 'description');
const type =
typeProperty && ts.isPropertyAssignment(typeProperty)
? stringValue(typeProperty.initializer)
: null;
if (type === null) {
literal = false;
continue;
}
if (!FIELDS.includes(type)) continue;
const description =
descriptionProperty && ts.isPropertyAssignment(descriptionProperty)
? stringValue(descriptionProperty.initializer)
: null;
if (description === null) literal = false;
else fields[type] = description;
}
return { fields, literal };
}
function configuredRetries(statements, kinds) {
for (const statement of statements) {
if (!ts.isExpressionStatement(statement)) continue;
const call = unwrap(statement.expression);
if (!ts.isCallExpression(call)) continue;
const ref = runnerRef(call.expression, kinds);
if (ref?.members.at(-1) !== 'configure') continue;
const options = call.arguments[0] ? unwrap(call.arguments[0]) : null;
if (!options || !ts.isObjectLiteralExpression(options)) continue;
const retries = objectProperty(options, 'retries');
if (!retries) continue;
const value = ts.isPropertyAssignment(retries) ? unwrap(retries.initializer) : null;
return value && ts.isNumericLiteral(value) ? Number(value.text) : Number.NaN;
}
return undefined;
}
function effectiveRetries(call, kinds) {
let current = call.parent;
while (current) {
if (
isFunction(current) &&
current.parent &&
ts.isCallExpression(current.parent) &&
ts.isBlock(current.body)
) {
const owner = runnerCall(current.parent, kinds);
if (owner && declarationKind(owner.ref) === 'describe') {
const retries = configuredRetries(current.body.statements, kinds);
if (retries !== undefined) return retries;
}
}
if (ts.isSourceFile(current)) return configuredRetries(current.statements, kinds);
current = current.parent;
}
return undefined;
}
function longestLiteralRun(regexLiteral) {
const pattern = regexLiteral.slice(1, regexLiteral.lastIndexOf('/'));
const cut = String.fromCharCode(0);
const literal = pattern
.replace(/\[(?:\\.|[^\]\\])*\]/g, cut)
.replace(/\\[pPu]\{[^}]*\}|\\x[0-9a-fA-F]{2}|\\u[0-9a-fA-F]{4}|\\c[A-Za-z]/g, cut)
.replace(/\\[dDwWsSbB]/g, cut)
.replace(/\\./g, 'x')
.replace(/\{\d*,?\d*\}/g, cut)
.replace(/[.^$*+?()|{}]/g, cut);
return Math.max(0, ...literal.split(cut).map((part) => part.length));
}
function findSignature(fn) {
let found = null;
const visit = (node) => {
if (found) 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 === 'expectKnownBug') {
const signature = node.arguments[0] ? unwrap(node.arguments[0]) : null;
found = {
node,
signature: signature && ts.isRegularExpressionLiteral(signature) ? signature.text : null,
};
return;
}
}
ts.forEachChild(node, visit);
};
visit(fn);
return found;
}
function scopeOf(node, kinds) {
let current = node.parent;
while (current) {
if (
isFunction(current) ||
ts.isFunctionDeclaration(current) ||
ts.isMethodDeclaration(current)
) {
const owner =
current.parent && ts.isCallExpression(current.parent)
? runnerCall(current.parent, kinds)
: null;
const kind = owner ? declarationKind(owner.ref) : null;
return kind === 'test' || kind === 'describe' ? kind : 'helper';
}
current = current.parent;
}
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,
source,
ts.ScriptTarget.Latest,
true,
scriptKind(path),
);
const runner = PLAYWRIGHT_FILE.test(path) ? 'playwright' : 'vitest';
const kinds = runnerBindings(sourceFile);
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,
pins: [],
quarantines: [],
gates: [],
notRun: [],
earlyReturns: [],
problems: [],
};
const lineOf = (node) =>
sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
const problem = (node, rule, message) =>
scan.problems.push({ path, line: lineOf(node), rule, message });
const gate = (node, form, scope, condition, skipWhen, reason = '') => {
scan.gates.push({
path,
line: lineOf(node),
form,
scope,
condition: condition ? oneLine(condition, sourceFile) : '',
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,
...titlesFor(node, scope),
});
const inspectTestBody = (fn, via) => {
const context = via === 'each' ? undefined : fn.parameters[via === 'for' ? 1 : 0]?.name;
const contextNames = new Set();
const skipNames = new Set();
if (context && ts.isIdentifier(context)) contextNames.add(context.text);
if (context && ts.isObjectBindingPattern(context)) {
for (const element of context.elements) {
const key = (element.propertyName ?? element.name).getText(sourceFile);
if (key === 'skip' && ts.isIdentifier(element.name)) skipNames.add(element.name.text);
}
}
const isContextSkip = (node) => {
if (!ts.isCallExpression(node)) return false;
const callee = unwrap(node.expression);
if (ts.isIdentifier(callee)) return skipNames.has(callee.text);
return (
ts.isPropertyAccessExpression(callee) &&
callee.name.text === 'skip' &&
ts.isIdentifier(unwrap(callee.expression)) &&
contextNames.has(unwrap(callee.expression).text)
);
};
const isAnySkip = (node) => {
if (isContextSkip(node)) return true;
if (!ts.isCallExpression(node)) return false;
const ref = runnerRef(node.expression, kinds);
return Boolean(ref) && ref.members.at(-1) === 'skip';
};
const visit = (node) => {
if (node !== fn && (isFunction(node) || ts.isFunctionDeclaration(node))) return;
if (isContextSkip(node)) {
const [first, second] = node.arguments;
if (first && !isTitle(unwrap(first))) {
gate(
node,
'context-skip',
'test',
first,
'condition',
second ? (stringValue(second) ?? '') : '',
);
} else {
const around = enclosingCondition(node, fn);
const reason = first ? (stringValue(first) ?? '') : '';
if (around) gate(node, 'context-skip', 'test', around.condition, around.skipWhen, reason);
else notRun(node, 'context-skip', 'test', '', reason);
}
}
if (ts.isReturnStatement(node) && !node.expression) {
const around = enclosingCondition(node, fn);
if (around && dependsOnEnvironment(around.condition, environment)) {
const guarded = containsBefore(
fn.body,
node.getStart(),
(candidate) => isAssertionCall(candidate) || isAnySkip(candidate),
);
if (!guarded) {
scan.earlyReturns.push({
path,
line: lineOf(node),
condition: oneLine(around.condition, sourceFile),
});
}
}
}
ts.forEachChild(node, visit);
};
ts.forEachChild(fn, visit);
};
const inspectDeclaration = (call, info, kind) => {
const parts = declarationParts(call);
const modifiers = new Set(info.ref.members);
const title = parts.title ? (stringValue(parts.title) ?? oneLine(parts.title, sourceFile)) : '';
const tagKey = runner === 'playwright' ? 'tag' : 'tags';
const { tags, literal } = readTags(parts.options, tagKey);
if (!literal) {
problem(
call,
'tags-not-literal',
`write \`${tagKey}\` as inline string literals so the known-reds listing can see it`,
);
}
const pinTag = runner === 'playwright' ? `@${KNOWN_BUG_TAG}` : KNOWN_BUG_TAG;
const quarantineTag = runner === 'playwright' ? `@${QUARANTINE_TAG}` : QUARANTINE_TAG;
const isPin = tags.includes(pinTag);
const isQuarantine = tags.includes(quarantineTag);
const skipOption = parts.options && objectProperty(parts.options, 'skip');
const skipValue =
skipOption && ts.isPropertyAssignment(skipOption)
? unwrap(skipOption.initializer)
: skipOption
? skipOption.name
: null;
const skipTruth = skipValue ? literalTruth(skipValue) : false;
const todoOption = parts.options && objectProperty(parts.options, 'todo');
const failsOption = parts.options && objectProperty(parts.options, 'fails');
if (failsOption) {
problem(
call,
'bare-expected-failure',
'an expected-failure marker accepts any failure; pin the bug with expectKnownBug instead',
);
}
const declaredNotRun =
[...modifiers].find((modifier) => NOT_RUN_MODIFIERS.has(modifier)) ?? null;
const skipped = Boolean(declaredNotRun) || skipTruth === true || Boolean(todoOption);
if (skipValue && skipTruth === null) gate(call, 'skip-option', kind, skipValue, 'condition');
if ((isPin || isQuarantine) && kind === 'describe') {
problem(
call,
'tag-on-describe',
`tag each test ${isPin ? pinTag : quarantineTag}, not the describe, so every pin carries its own issue, owner and date`,
);
} else if (isPin || isQuarantine) {
const { fields, literal: fieldsLiteral } =
runner === 'playwright'
? readPlaywrightFields(parts.options)
: readVitestFields(parts.options);
if (!fieldsLiteral) {
problem(
call,
'fields-not-literal',
`write the issue, owner and until ${runner === 'playwright' ? 'annotations' : 'meta'} as inline string literals`,
);
}
const record = {
path,
line: lineOf(call),
runner,
title,
titles: titleChain(call, kinds, sourceFile),
...fields,
};
if (isPin && isQuarantine)
problem(
call,
'pin-and-quarantine',
'a test is either a pinned known bug or a quarantined flake, not both',
);
if (isPin) {
const found = parts.fn ? findSignature(parts.fn) : null;
record.signature = found?.signature ?? null;
if (!found) {
problem(
call,
'pin-without-helper',
'a known-bug pin must wrap its correct assertion in expectKnownBug(/signature/, fn)',
);
} else if (found.signature === null) {
problem(
found.node,
'signature-not-literal',
'pass expectKnownBug a regular-expression literal naming the observed wrong outcome',
);
} else if (longestLiteralRun(found.signature) < MIN_SIGNATURE_LITERAL) {
problem(
found.node,
'signature-too-broad',
`a pin's signature must name the observed wrong outcome with at least ${MIN_SIGNATURE_LITERAL} literal characters in a row; a pattern like /./ absorbs any failure`,
);
}
if (skipped)
problem(
call,
'pin-not-run',
'a known-bug pin must run; a pin that is skipped checks nothing',
);
if (runner === 'playwright') {
const retries = effectiveRetries(call, kinds);
if (retries !== 0) {
problem(
call,
'pin-retries',
'run a Playwright pin with `test.describe.configure({ retries: 0 })` in its describe, so a retry cannot turn a changed failure into a flaky pass',
);
}
}
scan.pins.push(record);
} else {
if (!skipped)
problem(call, 'quarantine-runs', 'a quarantined flake is declared skipped, with `.skip`');
scan.quarantines.push(record);
}
} else if (skipped) {
const form = declaredNotRun ?? (todoOption ? 'todo-option' : 'skip-option');
notRun(call, form, kind, title);
}
if (info.gate) {
gate(call, info.gate.form, kind, info.gate.condition, info.gate.skipWhen);
}
if (kind === 'test' && parts.fn) inspectTestBody(parts.fn, info.via);
};
const inspectAnnotation = (call, modifier) => {
const [first, second] = call.arguments.map(unwrap);
const scope = scopeOf(call, kinds);
const reason = second ? (stringValue(second) ?? '') : '';
if (modifier === 'fail') {
problem(
call,
'bare-expected-failure',
'test.fail() accepts any failure in the test body; pin the bug with expectKnownBug instead',
);
return;
}
if (modifier === 'slow') return;
if (first && isFunction(first)) {
const body = ts.isBlock(first.body) ? null : first.body;
gate(call, `${modifier}-callback`, scope, body ?? first, 'condition', reason);
return;
}
const truth = first ? literalTruth(first) : true;
if (truth === false) return;
if (truth === null) {
gate(call, modifier, scope, first, 'condition', reason);
return;
}
const around = enclosingCondition(call, null);
if (around) gate(call, modifier, scope, around.condition, around.skipWhen, reason);
else notRun(call, modifier, scope, '', reason);
};
const visit = (node) => {
if (ts.isVariableDeclaration(node) && node.initializer) {
const ternary = skipTernary(node.initializer, kinds);
if (ternary) {
const topLevel =
ts.isVariableStatement(node.parent?.parent) && ts.isSourceFile(node.parent.parent.parent);
gate(
node,
'alias',
topLevel ? 'file' : scopeOf(node, kinds),
ternary.condition,
ternary.skipWhen,
);
}
}
if (ts.isCallExpression(node)) {
const info = runnerCall(node, kinds);
if (info) {
const kind = declarationKind(info.ref);
const bare = info.ref.members.find((member) => BARE_EXPECTED_FAILURE.has(member));
const parts = kind === 'test' || kind === 'describe' ? declarationParts(node) : null;
const annotation =
kind === 'test' &&
parts &&
!parts.title &&
ANNOTATION_MODIFIERS.has(info.ref.members.at(-1) ?? '') &&
!info.gate;
if (annotation) {
inspectAnnotation(node, info.ref.members.at(-1));
} else if (parts && (parts.fn || info.ref.members.includes('todo'))) {
if (bare) {
problem(
node,
'bare-expected-failure',
`\`.${bare}\` accepts any failure; pin the bug with expectKnownBug instead`,
);
}
inspectDeclaration(node, info, kind);
}
}
}
ts.forEachChild(node, visit);
};
visit(sourceFile);
return scan;
}
export function listTestFiles(root) {
const listed = spawnSync(
'git',
['ls-files', '-z', '--cached', '--others', '--exclude-standard'],
{
cwd: root,
encoding: 'utf8',
env: gitCleanEnv(),
maxBuffer: 1 << 28,
windowsHide: true,
},
);
if (listed.error || listed.status !== 0) {
throw new Error(
`known-reds: git ls-files failed in ${root} (${listed.error?.message ?? listed.stderr.trim()}), so the scan cannot show that it read every test file.`,
);
}
return listed.stdout
.split('\0')
.filter(
(path) =>
path !== '' &&
TEST_FILE.test(path) &&
!path.includes('node_modules/') &&
!EXCLUDED_PREFIXES.some((prefix) => path.startsWith(prefix)) &&
existsSync(join(root, path)),
)
.sort();
}
export function scanTree(root) {
if (typeof ts.createSourceFile !== 'function') {
throw new Error(
`known-reds: the resolved typescript ${ts.version} has no createSourceFile, so the scan cannot run.`,
);
}
const files = listTestFiles(root);
const report = {
schemaVersion: SCHEMA_VERSION,
files: files.length,
pins: [],
quarantines: [],
ciSkips: [],
envGates: [],
notRun: [],
earlyReturns: [],
problems: [],
};
for (const path of files) {
const scan = scanSource(path, readFileSync(join(root, path), 'utf8'));
report.pins.push(...scan.pins);
report.quarantines.push(...scan.quarantines);
report.notRun.push(...scan.notRun);
report.earlyReturns.push(...scan.earlyReturns);
report.problems.push(...scan.problems);
for (const entry of scan.gates)
(entry.ci === 'skips-on-ci' ? report.ciSkips : report.envGates).push(entry);
}
return report;
}
function trackedProblems(entry, today, required) {
const problems = trackingProblems(entry, { required, owners: OWNERS });
const beyond = horizonProblem(entry.until, today);
if (beyond) problems.push(beyond);
return problems;
}
export function loadAllowlist(path = ALLOWLIST_PATH) {
const parsed = JSON.parse(readFileSync(path, 'utf8'));
if (!parsed || !Array.isArray(parsed.ciSkips)) {
throw new Error(`known-reds: ${path} must hold { "ciSkips": [...] }.`);
}
return parsed;
}
export function validate(report, { today, allowlist }) {
const violations = [...report.problems];
for (const pin of report.pins) {
for (const message of trackedProblems(pin, today, FIELDS)) {
violations.push({
path: pin.path,
line: pin.line,
rule: 'pin-fields',
message: `known-bug pin ${message}`,
});
}
}
for (const quarantine of report.quarantines) {
for (const message of trackedProblems(quarantine, today, FIELDS)) {
violations.push({
path: quarantine.path,
line: quarantine.line,
rule: 'quarantine-fields',
message: `quarantine ${message}`,
});
}
}
for (const early of report.earlyReturns) {
violations.push({
path: early.path,
line: early.line,
rule: 'early-return',
message: `returns early when ${early.condition}, so the test reports a pass without running; skip it instead (ctx.skip(condition, note) in Vitest, test.skip(condition, reason) in Playwright)`,
});
}
const entries = allowlist.ciSkips;
const matched = new Set();
for (const skip of report.ciSkips) {
const index = entries.findIndex(
(entry, at) =>
!matched.has(at) && entry.path === skip.path && entry.condition === skip.condition,
);
if (index === -1) {
violations.push({
path: skip.path,
line: skip.line,
rule: 'ci-skip',
message: `skips on CI (${skip.condition}), so CI reports it green without running it; run it on CI, or key the skip on the missing capability rather than on CI`,
});
} else {
matched.add(index);
}
}
entries.forEach((entry, index) => {
const where = { path: `scripts/known-reds-allowlist.json`, line: index + 1 };
if (!matched.has(index)) {
violations.push({
...where,
rule: 'allowlist-stale',
message: `entry ${entry.path} (${entry.condition}) matches no CI-keyed skip; remove it`,
});
}
for (const message of trackedProblems(entry, today, ALLOWANCE_FIELDS)) {
violations.push({
...where,
rule: 'allowlist-fields',
message: `entry ${entry.path} ${message}`,
});
}
});
return violations;
}
function trackedRows(report, allowlist, keep) {
const row = (kind) => (entry) => ({
kind,
path: entry.path,
line: entry.line ?? null,
owner: entry.owner ?? null,
issue: entry.issue ?? null,
until: entry.until,
});
return [
...report.pins.filter(keep).map(row('pin')),
...report.quarantines.filter(keep).map(row('quarantine')),
...allowlist.ciSkips.filter(keep).map(row('ci-skip-entry')),
];
}
export function expiringSoon(report, { today, allowlist }) {
return trackedRows(
report,
allowlist,
(entry) => reviewState(entry.until, today, { soonDays: EXPIRY_WARNING_DAYS }) === 'due-soon',
);
}
export function expired(report, { today, allowlist }) {
return trackedRows(report, allowlist, (entry) => reviewState(entry.until, today) === 'expired');
}
const EXPIRING_KIND_LABELS = {
pin: 'pin',
quarantine: 'quarantine',
'ci-skip-entry': 'allowlisted CI skip',
};
export function render(report, violations, upcoming, today, { all, lapsed = [] }) {
const lines = [
`Known reds in open-knowledge on ${today}: ${report.files} test files scanned.`,
'',
];
const section = (heading, rows, format, show = true) => {
lines.push(`${heading} (${rows.length})`);
if (show) for (const row of rows) lines.push(` ${format(row)}`);
lines.push('');
};
section(
'Pinned known bugs',
report.pins,
(pin) =>
`${pin.path}:${pin.line} ${pin.title} ${pin.issue ?? '?'} owner ${pin.owner ?? '?'}, until ${pin.until ?? '?'} ${pin.signature ?? ''}`,
);
section(
'Quarantined flakes',
report.quarantines,
(row) =>
`${row.path}:${row.line} ${row.title} ${row.issue ?? '?'} owner ${row.owner ?? '?'}, until ${row.until ?? '?'}`,
);
section(
'Skipped on CI',
report.ciSkips,
(row) => `${row.path}:${row.line} ${row.scope} ${row.condition}`,
);
section(
'Not run: skip, fixme and todo',
report.notRun,
(row) => `${row.path}:${row.line} ${row.form} ${row.title || row.reason}`,
all,
);
section(
'Environment gates',
report.envGates,
(row) =>
`${row.path}:${row.line} ${row.form} ${row.condition}${row.ci ? ' (runs only on CI)' : ''}`,
all,
);
section(
'Gates with a condition the scanner cannot read',
[...report.ciSkips, ...report.envGates].filter((row) =>
row.atoms.some((atom) => atom.kind === 'unknown'),
),
(row) =>
`${row.path}:${row.line} ${row.form} cannot read: ${row.atoms
.filter((atom) => atom.kind === 'unknown')
.map((atom) => atom.name)
.join(', ')}`,
all,
);
section(
`Expiring within ${EXPIRY_WARNING_DAYS} days`,
upcoming,
(row) =>
`${EXPIRING_KIND_LABELS[row.kind] ?? row.kind} ${row.path}${row.line === null ? '' : `:${row.line}`} owner ${row.owner ?? '?'}, until ${row.until}`,
);
section(
'Expired, reported and not failed',
lapsed,
(row) =>
`${EXPIRING_KIND_LABELS[row.kind] ?? row.kind} ${row.path}${row.line === null ? '' : `:${row.line}`} owner ${row.owner ?? '?'}, until ${row.until}, issue ${row.issue ?? 'none'}`,
);
section(
'Violations',
violations,
(row) => `${row.path}:${row.line} [${row.rule}] ${row.message}`,
);
if (!all)
lines.push(
'Pass --all to list every not-run test, environment gate and gate the scanner cannot read, or --json for the full feed.',
);
lines.push(`The convention: ${CONVENTION_DOC}.`);
return `${lines.join('\n')}\n`;
}
function main(argv) {
try {
const rootAt = argv.indexOf('--root');
const root = rootAt === -1 ? OK_ROOT : resolve(argv[rootAt + 1] ?? '');
const today = todayUtc();
const report = scanTree(root);
const allowlist = loadAllowlist();
const violations = validate(report, { today, allowlist });
const upcoming = expiringSoon(report, { today, allowlist });
const lapsed = expired(report, { today, allowlist });
if (argv.includes('--json')) {
process.stdout.write(
`${JSON.stringify({ ...report, today, expiringSoon: upcoming, expired: lapsed, violations }, null, 2)}\n`,
);
} else {
process.stdout.write(
render(report, violations, upcoming, today, { all: argv.includes('--all'), lapsed }),
);
}
process.exitCode = violations.length > 0 ? 1 : 0;
} catch (error) {
process.stderr.write(
`known-reds: could not run: ${error instanceof Error ? error.message : String(error)}\n`,
);
process.exitCode = 2;
}
}
if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url))
main(process.argv.slice(2));