Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。
TypeScript agentai-agentai-assistantandroidclaude-codecodexelectroniosllmmacosreact-nativetypescriptwindows
#!/usr/bin/env node
// check-test-hygiene.mjs — 单测性能与价值的静态门禁(engineering-conventions.md §3.2)。
//
// 跑:node scripts/check-test-hygiene.mjs 检查(CI 阻断)
// node scripts/check-test-hygiene.mjs --update 把基线收紧到当前计数(只降不升)
//
// 三条规则都只看源码文本,结果与机器快慢无关:
// reset-modules 每次 vi.resetModules() 都会让后续 import 重新求值整条模块链。
// codexProxyHost.test.ts 逐用例重置时 285 条用例耗时 105s,不重置只要 7s。
// 新增调用必须在上一行写 `// reset-modules: <被隔离的模块状态>`。
// beforeEach/afterEach 及其准备、清理 helper 不接受理由豁免。
// real-wait 单测里 ≥100ms 的真实 setTimeout / sleep 既拖慢 CI 又制造时序抖动;
// 改用 vi.useFakeTimers() 或等待真实事件。确需真实等待时上一行写
// `// real-wait: <原因>`。已切换为 fake timers 的区间不计。
// source-read 普通单测读取生产源码文本做字面量断言。这类静态契约只能进对应包的
// guard tier(scripts/test-workspaces.config.mjs),不接受理由豁免。
//
// 存量计数记在 scripts/test-hygiene-baseline.json,只允许减少:某文件的计数超过基线、
// 或基线外的文件出现未豁免的命中,都会失败。门禁对照可信 Git 基准拒绝基线上调,
// 手改 JSON 与 `--update` 均不能绕过;只有确认基准提交还没有基线文件时才首次登记。
import { existsSync, readdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs';
import { execFileSync } from 'node:child_process';
import path from 'node:path';
import { createRequire } from 'node:module';
import process from 'node:process';
import { fileURLToPath, pathToFileURL } from 'node:url';
const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
const BASELINE_REL = 'scripts/test-hygiene-baseline.json';
const BASELINE_PATH = path.join(ROOT, BASELINE_REL);
const SCAN_ROOTS = ['apps', 'packages', 'scripts'];
const SKIP_DIRS = new Set(['node_modules', 'dist', 'out', 'build', 'coverage', '.vite', '.expo', '.turbo']);
export const TEST_FILE = /\.(?:test|spec)\.[cm]?[jt]sx?$/;
const NON_UNIT_TEST = /(?:^|[-.])(?:integration|e2e|git-integration)\.(?:test|spec)\.|\.bench\./;
export const RULES = ['resetModules', 'realWaits', 'sourceReads'];
const REAL_WAIT_MIN_MS = 100;
const REAL_WAIT_NAMES = new Set(['sleep', 'delay', 'wait', 'waitMs', 'pause']);
// These exact root-runner suites own cross-file contracts that cannot execute
// the full application in node:test. New scripts tests receive no exemption.
const ROOT_SOURCE_CONTRACTS = new Map([
// TS brand identity and executable/userData names mirrored by build scripts.
['scripts/__tests__/brand-identity-sync.test.mjs', 'cross-runtime brand identity'],
// Documented commands, required CI gates and locale-aware QA artifact wiring.
['scripts/__tests__/dev-docs-contract.test.mjs', 'developer/CI and QA artifact contracts'],
// Design inventory must agree with production entry points and shared matchers.
['scripts/__tests__/design-inventory.test.mjs', 'design inventory cross-file contracts'],
// Locale declarations and diagnostic prose implement the terminology policy.
['scripts/__tests__/glossary-rules.test.mjs', 'locale and terminology policy contracts'],
// Approved design exceptions are bound to exact production declarations.
['scripts/__tests__/hardcoded-color-audit.test.mjs', 'design exemption and CI contracts'],
// Dev startup must prepare every supported Agent runtime before it can launch.
['scripts/__tests__/ensure-agent-binaries.test.mjs', 'runtime preparation startup wiring'],
// Restart scripts and app bootstrap must agree on isolation/process boundaries.
['scripts/__tests__/restart-desktop-remote.test.mjs', 'restart and bootstrap isolation contracts'],
// Packaged notice generation and both application entry points must stay wired.
['scripts/__tests__/third-party-notices.test.mjs', 'cross-platform bundled license contracts'],
]);
// This explicit DB-tier suite uses frozen companion bytes as input to real
// hash/manifest repair, not source-spelling assertions. Keep reload/wait checks.
const DB_SOURCE_INPUTS = new Set([
'apps/desktop/src/main/localDb/__tests__/migrationCompatibility.test.ts',
]);
// Reuse Desktop's declared parser to locate test/hook callbacks and local helpers.
// No type checking or module loading is needed.
const requireDesktop = createRequire(new URL('../apps/desktop/package.json', import.meta.url));
let typescript;
function parseTestSource(ts, code) {
const tsx = ts.createSourceFile('test.tsx', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TSX);
if (tsx.parseDiagnostics.length === 0) return tsx;
const plain = ts.createSourceFile('test.ts', code, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
return plain.parseDiagnostics.length < tsx.parseDiagnostics.length ? plain : tsx;
}
/** Replace comments with spaces (keeping newlines) so matches ignore commented-out code. */
export function stripComments(source) {
let out = '';
let i = 0;
let quote = null;
while (i < source.length) {
const ch = source[i];
const next = source[i + 1];
if (quote) {
out += ch;
if (ch === '\\') { out += next ?? ''; i += 2; continue; }
if (ch === quote) quote = null;
i += 1;
continue;
}
if (ch === '/' && next === '/') {
while (i < source.length && source[i] !== '\n') { out += ' '; i += 1; }
continue;
}
if (ch === '/' && next === '*') {
while (i < source.length && !(source[i] === '*' && source[i + 1] === '/')) {
out += source[i] === '\n' ? '\n' : ' ';
i += 1;
}
out += ' ';
i += 2;
continue;
}
if (ch === '"' || ch === "'" || ch === '`') quote = ch;
out += ch;
i += 1;
}
return out;
}
function lineOf(text, index) {
let line = 0;
for (let i = 0; i < index; i += 1) if (text.charCodeAt(i) === 10) line += 1;
return line;
}
/** True when the closest non-blank line above `line` carries `// <marker>: <reason>`. */
function hasJustification(lines, line, marker) {
for (let i = line - 1; i >= 0; i -= 1) {
const text = lines[i].trim();
if (text === '') continue;
return new RegExp(`//\\s*${marker}:\\s*\\S`).test(text);
}
return false;
}
/** A per-test hook cannot turn repeated module loading into an exemption. */
function countModuleResets(code, lines) {
if (!/\bresetModules\b/.test(code)) return 0;
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const nodeScopes = new WeakMap();
const calls = [];
const writes = new Map();
const isFunction = node => ts.isFunctionLike(node) && Boolean(node.body);
function declare(name, declaration, scope) {
if (ts.isIdentifier(name)) scope.bindings.set(name.text, declaration);
else for (const element of name.elements) {
if (ts.isBindingElement(element)) declare(element.name, element, scope);
}
}
function collect(node, scope) {
if (ts.isFunctionDeclaration(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isSourceFile(node) || ts.isBlock(node) || isFunction(node)) {
scope = { parent: scope, bindings: new Map() };
}
nodeScopes.set(node, scope);
if (isFunction(node)) {
if (node.name && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node))) scope.bindings.set(node.name.text, node);
for (const parameter of node.parameters) declare(parameter.name, parameter, scope);
}
if (ts.isVariableDeclaration(node)) declare(node.name, node, scope);
if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isCallExpression(node)) calls.push(node);
ts.forEachChild(node, child => collect(child, scope));
}
collect(source, null);
function binding(identifier) {
for (let scope = nodeScopes.get(identifier); scope; scope = scope.parent) {
if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
}
return null;
}
function unwrap(node) {
while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) node = node.expression;
return node;
}
function propertyName(node) {
return node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : null;
}
function recordWrite(target, expression, property = null) {
target = unwrap(target);
if (ts.isIdentifier(target)) {
const bound = binding(target);
if (bound) {
if (!writes.has(bound)) writes.set(bound, []);
writes.get(bound).push({ expression, property });
}
} else if (ts.isObjectLiteralExpression(target)) {
for (const member of target.properties) {
if (ts.isShorthandPropertyAssignment(member)) recordWrite(member.name, expression, member.name.text);
else if (ts.isPropertyAssignment(member)) recordWrite(member.initializer, expression, propertyName(member.name));
}
}
}
function collectWrites(node) {
if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) recordWrite(node.left, node.right);
ts.forEachChild(node, collectWrites);
}
collectWrites(source);
function importedFromVitest(bound) {
let declaration = bound;
while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
return declaration && !declaration.importClause?.isTypeOnly && !bound.isTypeOnly
&& ts.isStringLiteral(declaration.moduleSpecifier) && declaration.moduleSpecifier.text === 'vitest';
}
function propertyMatches(expression, property, kind, seen) {
if (kind === 'mock' && /^(?:vi|vitest)$/.test(property)) return matches(expression, 'namespace', seen);
if (kind === 'reset' && property === 'resetModules') return matches(expression, 'mock', seen);
if (kind === 'hook' && /^(?:beforeEach|afterEach)$/.test(property)) return matches(expression, 'namespace', seen);
return false;
}
function boundMatches(bound, kind, seen) {
if (!bound || seen.has(bound)) return false;
seen = new Set(seen).add(bound);
if (importedFromVitest(bound)) {
if (kind === 'namespace') return ts.isNamespaceImport(bound);
if (ts.isImportSpecifier(bound)) {
const name = bound.propertyName?.text ?? bound.name.text;
return kind === 'mock' && /^(?:vi|vitest)$/.test(name)
|| kind === 'hook' && /^(?:beforeEach|afterEach)$/.test(name);
}
}
if (ts.isBindingElement(bound) && ts.isObjectBindingPattern(bound.parent) && !bound.dotDotDotToken) {
const property = propertyName(bound.propertyName ?? bound.name);
const owner = bound.parent.parent;
if (kind === 'mock' && /^(?:vi|vitest)$/.test(property) && boundMatches(owner, 'namespace', seen)
|| kind === 'reset' && property === 'resetModules' && boundMatches(owner, 'mock', seen)
|| kind === 'hook' && /^(?:beforeEach|afterEach)$/.test(property) && boundMatches(owner, 'namespace', seen)) return true;
}
if (ts.isVariableDeclaration(bound) && bound.initializer && matches(bound.initializer, kind, seen)) return true;
// Follow only local static aliases, not arbitrary returned objects or callbacks.
return (writes.get(bound) ?? []).some(write => write.property
? propertyMatches(write.expression, write.property, kind, seen) : matches(write.expression, kind, seen));
}
function matches(node, kind, seen = new Set()) {
node = unwrap(node);
if (ts.isIdentifier(node)) {
const bound = binding(node);
if (bound) return boundMatches(bound, kind, seen);
return kind === 'mock' && /^(?:vi|vitest)$/.test(node.text)
|| kind === 'hook' && /^(?:beforeEach|afterEach)$/.test(node.text);
}
if (ts.isPropertyAccessExpression(node)) return propertyMatches(node.expression, node.name.text, kind, seen);
if (ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression)) return propertyMatches(node.expression, node.argumentExpression.text, kind, seen);
return false;
}
function resolveHelper(node, seen = new Set()) {
node = unwrap(node);
if (isFunction(node)) return node;
if (!ts.isIdentifier(node)) return null;
const bound = binding(node);
if (!bound || seen.has(bound)) return null;
seen = new Set(seen).add(bound);
if (isFunction(bound)) return bound;
if (ts.isVariableDeclaration(bound) && bound.initializer) {
const helper = resolveHelper(bound.initializer, seen);
if (helper) return helper;
}
for (const write of writes.get(bound) ?? []) {
if (!write.property) {
const helper = resolveHelper(write.expression, seen);
if (helper) return helper;
}
}
return null;
}
const resets = new Map(calls.filter(call => matches(call.expression, 'reset')).map(call => [call.getStart(source), call]));
const hooks = calls.filter(call => matches(call.expression, 'hook')).flatMap(call => [...call.arguments]);
const perTest = new Set();
const visitedFunctions = new Set();
function visitFunction(node) {
if (!node || visitedFunctions.has(node)) return;
visitedFunctions.add(node);
if (node.body) visit(node.body);
}
function visit(node) {
// Defining or storing a restart callback is not a per-test reload. Only
// follow an actual local call, or the callback registered with a hook.
if (isFunction(node)) return;
if (ts.isCallExpression(node)) {
const expression = node.expression;
if (matches(expression, 'reset')) perTest.add(node.getStart(source));
visitFunction(resolveHelper(expression));
}
ts.forEachChild(node, visit);
}
for (const hook of hooks) {
if (matches(hook, 'reset')) {
resets.set(hook.getStart(source), hook);
perTest.add(hook.getStart(source));
} else visitFunction(resolveHelper(hook));
}
return [...resets.keys()].filter(index => perTest.has(index)
|| !hasJustification(lines, lineOf(code, index), 'reset-modules')).length;
}
/** Mask string contents while preserving line numbers and call-site punctuation. */
function maskStrings(source) {
let out = '';
let quote = null;
let escaped = false;
for (const ch of source) {
if (quote) {
if (escaped) {
escaped = false;
out += ch === '\n' ? '\n' : ' ';
} else if (ch === '\\') {
escaped = true;
out += ' ';
} else if (ch === quote) {
quote = null;
out += ch;
} else {
out += ch === '\n' ? '\n' : ' ';
}
continue;
}
if (ch === '"' || ch === "'" || ch === String.fromCharCode(96)) {
quote = ch;
out += ch;
} else {
out += ch;
}
}
return out;
}
function staticWaitCalls(code) {
if (!/\bsetTimeout\b|\b(?:sleep|delay|wait|waitMs|pause)\s*\(|(?:node:)?timers\/promises/.test(code)) return [];
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const nodeScopes = new WeakMap();
const calls = [];
const promiseTimerNames = new Set();
const isFunction = node => ts.isFunctionLike(node) && Boolean(node.body);
function declare(name, declaration, scope) {
if (ts.isIdentifier(name)) scope.bindings.set(name.text, declaration);
else for (const element of name.elements) {
if (ts.isBindingElement(element)) declare(element.name, element, scope);
}
}
function isPromiseTimerImport(bound) {
let declaration = bound;
while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
return declaration && ts.isStringLiteral(declaration.moduleSpecifier)
&& /^(?:node:)?timers\/promises$/.test(declaration.moduleSpecifier.text);
}
function collect(node, scope) {
if (ts.isFunctionDeclaration(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isSourceFile(node) || ts.isBlock(node) || isFunction(node)) scope = { parent: scope, bindings: new Map() };
nodeScopes.set(node, scope);
if (isFunction(node)) {
for (const parameter of node.parameters) {
declare(parameter.name, parameter, scope);
}
}
if (ts.isVariableDeclaration(node)) declare(node.name, node, scope);
if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) && node.name) {
scope.bindings.set(node.name.text, node);
if (ts.isImportSpecifier(node) && (node.propertyName?.text ?? node.name.text) === 'setTimeout'
&& isPromiseTimerImport(node)) promiseTimerNames.add(node.name.text);
}
if (ts.isCallExpression(node)) calls.push(node);
ts.forEachChild(node, child => collect(child, scope));
}
collect(source, null);
function binding(identifier) {
for (let scope = nodeScopes.get(identifier); scope; scope = scope.parent) {
if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
}
return null;
}
function unwrap(node) {
while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) node = node.expression;
return node;
}
const isConst = node => ts.isVariableDeclaration(node) && (node.parent.flags & ts.NodeFlags.Const);
function callbackTimerImport(bound) {
let declaration = bound;
while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
return declaration && !declaration.importClause?.isTypeOnly && !bound.isTypeOnly
&& ts.isStringLiteral(declaration.moduleSpecifier) && /^(?:node:)?timers$/.test(declaration.moduleSpecifier.text);
}
function timerObject(node, seen = new Set()) {
node = unwrap(node);
if (ts.isPropertyAccessExpression(node) && node.name.text === 'default'
&& timerObject(node.expression, seen) === 'native') return 'native';
if (!ts.isIdentifier(node)) return null;
const bound = binding(node);
if (!bound) return /^(?:globalThis|global|window|self)$/.test(node.text) ? 'global' : null;
if ((ts.isNamespaceImport(bound) || ts.isImportClause(bound)) && callbackTimerImport(bound)) return 'native';
if (seen.has(bound) || !isConst(bound) || !bound.initializer) return null;
return timerObject(bound.initializer, new Set(seen).add(bound));
}
// Immutable local aliases capture the timer function, not the later global
// clock state. Follow that capture through aliases, while respecting shadows.
function callbackTimer(node, clockIndex, seen = new Set()) {
node = unwrap(node);
const property = ts.isPropertyAccessExpression(node) ? node.name.text
: ts.isElementAccessExpression(node) && ts.isStringLiteral(node.argumentExpression) ? node.argumentExpression.text : null;
if (property === 'setTimeout') {
const owner = timerObject(node.expression);
if (owner) return { clockIndex: owner === 'native' ? 0 : clockIndex };
}
if (!ts.isIdentifier(node)) return null;
const bound = binding(node);
if (!bound) return node.text === 'setTimeout' ? { clockIndex } : null;
if (seen.has(bound)) return null;
seen = new Set(seen).add(bound);
if (isConst(bound) && bound.initializer) return callbackTimer(bound.initializer, bound.initializer.getStart(source), seen);
if (ts.isBindingElement(bound) && ts.isObjectBindingPattern(bound.parent) && !bound.dotDotDotToken) {
const name = bound.propertyName ?? bound.name;
const owner = bound.parent.parent;
if ((ts.isIdentifier(name) || ts.isStringLiteral(name)) && name.text === 'setTimeout'
&& isConst(owner) && owner.initializer) {
const object = timerObject(owner.initializer);
if (object) return { clockIndex: object === 'native' ? 0 : owner.initializer.getStart(source) };
}
}
// Builtin callback timers retain native bindings under Vitest's global fake clock.
if (ts.isImportSpecifier(bound) && (bound.propertyName?.text ?? bound.name.text) === 'setTimeout'
&& callbackTimerImport(bound)) return { clockIndex: 0 };
return null;
}
function promiseTimerNamespace(node, seen = new Set()) {
if (!ts.isIdentifier(node) || seen.has(node)) return false;
seen.add(node);
const bound = binding(node);
if (bound && ts.isVariableDeclaration(bound) && bound.initializer) return promiseTimerNamespace(bound.initializer, seen);
return bound && (ts.isNamespaceImport(bound) || ts.isImportClause(bound)) && isPromiseTimerImport(bound);
}
function isPromiseTimer(node, seen = new Set()) {
if (seen.has(node)) return false;
seen.add(node);
if (ts.isPropertyAccessExpression(node)) return node.name.text === 'setTimeout' && promiseTimerNamespace(node.expression);
if (!ts.isIdentifier(node)) return false;
const bound = binding(node);
if (bound && ts.isVariableDeclaration(bound) && bound.initializer) return isPromiseTimer(bound.initializer, seen);
return bound && ts.isImportSpecifier(bound) && (bound.propertyName?.text ?? bound.name.text) === 'setTimeout'
&& isPromiseTimerImport(bound);
}
function number(node, parameters = new Map(), seen = new Set()) {
if (!node || seen.has(node)) return undefined;
seen = new Set(seen).add(node);
if (ts.isNumericLiteral(node)) return Number(node.text.replaceAll('_', ''));
if (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) return number(node.expression, parameters, seen);
if (ts.isIdentifier(node)) {
const bound = binding(node);
if (!bound) return undefined;
if (parameters.has(bound)) return parameters.get(bound);
if (ts.isVariableDeclaration(bound) && (bound.parent.flags & ts.NodeFlags.Const)) return number(bound.initializer, parameters, seen);
return undefined;
}
if (ts.isPrefixUnaryExpression(node)) {
const value = number(node.operand, parameters, seen);
if (node.operator === ts.SyntaxKind.MinusToken) return -value;
if (node.operator === ts.SyntaxKind.PlusToken) return value;
}
if (ts.isBinaryExpression(node)) {
const left = number(node.left, parameters, seen);
const right = number(node.right, parameters, seen);
if (left === undefined || right === undefined) return undefined;
switch (node.operatorToken.kind) {
case ts.SyntaxKind.PlusToken: return left + right;
case ts.SyntaxKind.MinusToken: return left - right;
case ts.SyntaxKind.AsteriskToken: return left * right;
case ts.SyntaxKind.SlashToken: return left / right;
}
}
return undefined;
}
// Recognize direct local wrappers returning a timeout or Promise containing
// one. Do not follow arbitrary control flow, callbacks or external helpers.
function wrapperTimer(fn) {
if (!fn?.body) return null;
const timerCall = node => {
if (!node || !ts.isCallExpression(node)) return null;
if (callbackTimer(node.expression)) return { call: node, kind: 'callback' };
if (isPromiseTimer(node.expression)) return { call: node, kind: 'promise' };
return null;
};
const body = ts.isBlock(fn.body)
? fn.body.statements.find(ts.isReturnStatement)?.expression : fn.body;
if (!body && !ts.isBlock(fn.body)) return null;
const direct = timerCall(body);
if (direct) return direct;
const promiseTimer = node => {
if (!node || !ts.isNewExpression(node) || node.expression.getText(source) !== 'Promise') return null;
const executor = node.arguments?.[0];
if (!executor || !isFunction(executor)) return null;
const candidates = ts.isBlock(executor.body) ? executor.body.statements.map(statement => statement.expression) : [executor.body];
return candidates.map(timerCall).find(Boolean) ?? null;
};
const directPromise = promiseTimer(body);
if (directPromise) return directPromise;
if (!ts.isBlock(fn.body)) return null;
// A common async wrapper awaits a timer in an expression statement rather
// than returning it. Follow only awaits in this wrapper body, never nested
// functions, and let the outer call map its parameter to the timer delay.
let awaited = null;
const visit = node => {
if (awaited || isFunction(node)) return;
if (ts.isAwaitExpression(node)) {
awaited = timerCall(node.expression) ?? promiseTimer(node.expression);
if (awaited) return;
}
ts.forEachChild(node, visit);
};
visit(fn.body);
return awaited;
}
const waits = [];
for (const call of calls) {
const name = ts.isIdentifier(call.expression) ? call.expression.text
: ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : '';
let duration;
let clockIndex;
const callback = callbackTimer(call.expression);
const promiseTimer = isPromiseTimer(call.expression);
const shadowedPromiseTimer = ts.isIdentifier(call.expression) && promiseTimerNames.has(name) && !promiseTimer;
if (promiseTimer) duration = number(call.arguments[0]);
else if (callback) {
duration = number(call.arguments[1]);
clockIndex = callback.clockIndex;
}
// Generic wait names are only meaningful as direct local calls. A method
// such as meter.pause(1_000) is ordinary domain data, not a real wait.
else if (ts.isIdentifier(call.expression) && REAL_WAIT_NAMES.has(name) && !shadowedPromiseTimer) duration = number(call.arguments[0]);
else {
if (!ts.isIdentifier(call.expression)) continue;
const bound = binding(call.expression);
const fn = bound && ts.isVariableDeclaration(bound) ? bound.initializer : bound;
if (!fn || !isFunction(fn)) continue;
const timerInfo = wrapperTimer(fn);
if (!timerInfo) continue;
const timer = timerInfo.call;
const delayArgument = timerInfo.kind === 'promise' ? 0 : 1;
const parameters = new Map(fn.parameters.map((parameter, index) => [parameter, number(call.arguments[index] ?? parameter.initializer)]));
// Constant waits inside a helper are already counted at their own site.
if (number(timer.arguments[delayArgument]) !== undefined) continue;
duration = number(timer.arguments[delayArgument], parameters);
if (timerInfo.kind === 'callback') clockIndex = callbackTimer(timer.expression).clockIndex;
// A wrapper-local capture executes when the wrapper is called.
if (clockIndex >= fn.getStart(source) && clockIndex < fn.end) clockIndex = undefined;
}
if (Number.isFinite(duration)) waits.push({ index: call.getStart(source), duration, clockIndex });
}
return waits;
}
function timerScopes(code, timerEvents) {
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const scopes = [];
const nodeScopes = new WeakMap();
const callbackKinds = new WeakMap();
const registeredHelpers = [];
const calls = [];
const functions = [];
const writes = new Map();
const isFunction = node => ts.isFunctionLike(node) && Boolean(node.body);
const isTimer = name => /^(?:useFakeTimers|useRealTimers)$/.test(name);
const isFramework = name => /^(?:describe|it|test|beforeEach|beforeAll|afterEach|afterAll)$/.test(name);
function declare(name, declaration, scope) {
if (ts.isIdentifier(name)) scope.bindings.set(name.text, declaration);
else for (const element of name.elements) {
if (ts.isBindingElement(element)) declare(element.name, element, scope);
}
}
function visit(node, lexicalScope) {
if (ts.isFunctionDeclaration(node) && node.name) lexicalScope.bindings.set(node.name.text, node);
if (ts.isSourceFile(node) || ts.isBlock(node) || isFunction(node)) lexicalScope = { parent: lexicalScope, bindings: new Map() };
nodeScopes.set(node, lexicalScope);
if (isFunction(node)) {
functions.push(node);
if (node.name && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node))) lexicalScope.bindings.set(node.name.text, node);
for (const parameter of node.parameters) declare(parameter.name, parameter, lexicalScope);
}
if (ts.isVariableDeclaration(node)) declare(node.name, node, lexicalScope);
if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) && node.name) lexicalScope.bindings.set(node.name.text, node);
if (ts.isCallExpression(node)) calls.push(node);
ts.forEachChild(node, child => visit(child, lexicalScope));
}
visit(source, null);
function binding(identifier) {
for (let scope = nodeScopes.get(identifier); scope; scope = scope.parent) {
if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
}
return null;
}
function unwrap(node) {
while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node)) node = node.expression;
return node;
}
const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteral(node)) ? node.text : null;
function recordWrite(target, expression, property = null) {
target = unwrap(target);
if (ts.isIdentifier(target)) {
const bound = binding(target);
if (bound) writes.set(bound, [...(writes.get(bound) ?? []), { expression, property }]);
} else if (ts.isObjectLiteralExpression(target)) {
for (const member of target.properties) {
if (ts.isShorthandPropertyAssignment(member)) recordWrite(member.name, expression, member.name.text);
else if (ts.isPropertyAssignment(member)) recordWrite(member.initializer, expression, propertyName(member.name));
}
}
}
function collectWrites(node) {
if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) recordWrite(node.left, node.right);
ts.forEachChild(node, collectWrites);
}
collectWrites(source);
function member(owner, name) {
if (owner === 'namespace') return /^(?:vi|vitest)$/.test(name) ? 'mock' : isFramework(name) ? name : '';
return owner === 'mock' && isTimer(name) ? name : '';
}
function boundIdentity(bound, seen) {
if (!bound || seen.has(bound)) return '';
seen = new Set(seen).add(bound);
let declaration = bound;
while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
if (declaration && !declaration.importClause?.isTypeOnly && !bound.isTypeOnly
&& ts.isStringLiteral(declaration.moduleSpecifier) && declaration.moduleSpecifier.text === 'vitest') {
if (ts.isNamespaceImport(bound)) return 'namespace';
if (ts.isImportSpecifier(bound)) return member('namespace', bound.propertyName?.text ?? bound.name.text);
}
const write = writes.get(bound)?.at(-1);
if (write) return write.property ? member(identity(write.expression, seen), write.property) : identity(write.expression, seen);
if (ts.isBindingElement(bound) && ts.isObjectBindingPattern(bound.parent) && !bound.dotDotDotToken) {
return member(boundIdentity(bound.parent.parent, seen), propertyName(bound.propertyName ?? bound.name));
}
if (ts.isVariableDeclaration(bound) && bound.initializer) return identity(bound.initializer, seen);
return '';
}
// Resolve static Vitest bindings, not lookalike fixture objects or names in
// strings. Definitions alone never switch the clock; only reachable calls do.
function identity(expression, seen = new Set()) {
expression = unwrap(expression);
if (ts.isIdentifier(expression)) {
const bound = binding(expression);
return bound ? boundIdentity(bound, seen)
: /^(?:vi|vitest)$/.test(expression.text) ? 'mock' : isFramework(expression.text) ? expression.text : '';
}
if (ts.isPropertyAccessExpression(expression)) return member(identity(expression.expression, seen), expression.name.text);
if (ts.isElementAccessExpression(expression) && ts.isStringLiteral(expression.argumentExpression)) return member(identity(expression.expression, seen), expression.argumentExpression.text);
return '';
}
function frameworkName(expression) {
const name = identity(expression);
if (isFramework(name)) return name;
if (ts.isPropertyAccessExpression(expression) || ts.isCallExpression(expression)) return frameworkName(expression.expression);
if (ts.isTaggedTemplateExpression(expression)) return frameworkName(expression.tag);
return '';
}
for (const call of calls) {
const kind = frameworkName(call.expression);
if (!isFramework(kind)) continue;
for (const argument of call.arguments) {
if (isFunction(argument)) callbackKinds.set(argument, kind);
else if (ts.isIdentifier(argument) || isTimer(identity(argument))) {
const scope = { kind, start: argument.getStart(source), end: argument.end };
scopes.push(scope);
registeredHelpers.push({ argument, scope });
}
}
}
for (const node of functions) scopes.push({ kind: callbackKinds.get(node) ?? 'helper', start: node.getStart(source), end: node.end });
scopes.sort((a, b) => (a.end - a.start) - (b.end - b.start));
function helper(expression, seen = new Set()) {
expression = unwrap(expression);
if (isFunction(expression)) return expression;
if (!ts.isIdentifier(expression)) return null;
const bound = binding(expression);
if (!bound || seen.has(bound)) return null;
seen = new Set(seen).add(bound);
const write = writes.get(bound)?.at(-1);
if (write) return write.property ? null : helper(write.expression, seen);
if (isFunction(bound)) return bound;
if (ts.isVariableDeclaration(bound) && bound.initializer) return helper(bound.initializer, seen);
return null;
}
function helperEvents(fn, seen = new Set()) {
if (!fn?.body || seen.has(fn)) return [];
seen = new Set(seen).add(fn);
const events = [];
function inspect(node) {
if (isFunction(node)) return;
if (ts.isCallExpression(node)) {
const expression = node.expression;
const name = identity(expression);
if (isTimer(name)) events.push(name);
else events.push(...helperEvents(helper(expression), seen));
}
ts.forEachChild(node, inspect);
}
inspect(fn.body);
return events;
}
function addEvents(names, index) {
names.forEach((name, order) => timerEvents.push({ 1: name, index: index + (order + 1) / 1e6 }));
}
// A helper definition does not change timer mode. Apply its reachable timer
// calls only where it is actually invoked or registered as a framework hook.
for (const call of calls) {
const index = call.getStart(source);
if (scopes.find(scope => scope.start <= index && index < scope.end)?.kind === 'helper') continue;
const name = identity(call.expression);
addEvents(isTimer(name) ? [name] : helperEvents(helper(call.expression)), index);
}
for (const { argument, scope } of registeredHelpers) {
const name = identity(argument);
addEvents(isTimer(name) ? [name] : helperEvents(helper(argument)), scope.start);
}
timerEvents.sort((a, b) => a.index - b.index);
return scopes;
}
function timerStateAt(index, timerEvents, scopes) {
const scopeAt = (position) => scopes.find(s => s.start <= position && position < s.end);
const localWaitScope = scopeAt(index);
// Inline executors (for example a Promise around setTimeout) still run in
// the surrounding test and inherit its hooks, unlike an uncalled definition.
const waitScope = scopes.find(s => s.kind !== 'helper' && s.start <= index && index < s.end) ?? localWaitScope;
const describeAt = (scope) => scopes.find(s => s.kind === 'describe' && s.start < scope.start && scope.end < s.end);
const belongsToWait = (scope) => !scope || scope.kind === 'describe' && scope.start < index && index < scope.end;
const events = timerEvents.map(event => ({ event, scope: scopeAt(event.index) }));
let fake = false;
// Registration-time calls and before hooks are distinct from calls in a
// sibling test or an after hook. Inherit hooks from outer describes first.
const inherited = events.filter(({ event, scope }) => event.index < index && belongsToWait(scope));
for (const { event } of inherited) fake = event[1] === 'useFakeTimers';
if (waitScope && /^(?:it|test)$/.test(waitScope.kind)) {
// Registration-time setup, like beforeAll, runs only once. An afterEach
// restoring real timers can invalidate it before a later test runs.
const earlierTests = scopes.filter(scope => /^(?:it|test)$/.test(scope.kind) && scope.end < waitScope.start);
const containsTest = (suite, test) => !suite || suite.start < test.start && test.end < suite.end;
const restoringHooks = events.filter(entry => entry.scope?.kind === 'afterEach'
&& entry.event[1] === 'useRealTimers' && belongsToWait(describeAt(entry.scope)));
const hasRestoredTimers = (suite) => restoringHooks.some(entry => earlierTests.some(test =>
containsTest(suite, test) && containsTest(describeAt(entry.scope), test)));
const restoresRealTimers = hasRestoredTimers(null);
if (restoresRealTimers) fake = false;
const hooks = events.filter(({ scope }) => scope && /^(?:beforeAll|beforeEach)$/.test(scope.kind) && belongsToWait(describeAt(scope)))
.sort((a, b) => {
const depthA = scopes.filter(s => s.kind === 'describe' && s.start < a.scope.start && a.scope.end < s.end).length;
const depthB = scopes.filter(s => s.kind === 'describe' && s.start < b.scope.start && b.scope.end < s.end).length;
if (a.scope.kind !== b.scope.kind) return a.scope.kind === 'beforeAll' ? -1 : 1;
return depthA - depthB || a.event.index - b.event.index;
});
for (const { event, scope } of hooks) {
// An afterEach restoring real timers invalidates beforeAll-only setup
// for subsequent tests. Be conservative rather than exempt a real wait.
if (scope.kind === 'beforeAll' && hasRestoredTimers(describeAt(scope))) continue;
fake = event[1] === 'useFakeTimers';
}
}
for (const { event, scope } of events) {
if ((scope === waitScope || scope === localWaitScope) && event.index < index) fake = event[1] === 'useFakeTimers';
}
return fake;
}
function countRealWaits(code, lines, sourceCode = code) {
const timerEvents = [];
const scopes = /\buse(?:Fake|Real)Timers\b/.test(sourceCode) ? timerScopes(sourceCode, timerEvents) : [];
let count = 0;
const waits = staticWaitCalls(sourceCode).sort((a, b) => a.index - b.index);
for (const wait of waits) {
if (timerStateAt(wait.clockIndex ?? wait.index, timerEvents, scopes)) continue;
if (wait.duration < REAL_WAIT_MIN_MS) continue;
const line = lineOf(code, wait.index);
if (!hasJustification(lines, line, 'real-wait')) count += 1;
}
return count;
}
const IMPORT_CONTEXT = /(?:\bfrom|\bimport|\brequire|\.mock|\.doMock|\.unmock|\.importActual|\.importMock|\.glob)\s*\(?\s*$/;
const SOURCE_EXTENSION = '(?:tsx?|mts|cts|css|mjs|cjs|jsx?|swift|[cmh]|mm|cc|cpp|cxx|hh|hpp|hxx|rs|go|kts?|java|cs|py|rb|sh|bash|zsh|html|vue|svelte|scss|sass|less)';
const SOURCE_EXT = new RegExp('\\.' + SOURCE_EXTENSION + '$', 'i');
const SOURCE_LITERAL = new RegExp('\\.' + SOURCE_EXTENSION + '[\'"]', 'i');
// Only anchors that point into the checkout count; generic names such as `root`
// usually hold an mkdtemp() directory whose fake source files are test input.
const REPO_ANCHOR = /__dirname|import\.meta\.(?:url|dirname)|process\.cwd\s*\(\s*\)|\b(?:REPO_ROOT|repoRoot|desktopRoot)\b/;
/** Follow simple local path bindings so an anchor-derived directory cannot be
* hidden behind a descriptive variable name (for example agentsRoot).
* This intentionally stays local and syntax-only; it does not evaluate
* arbitrary expressions or cross module boundaries.
*/
function findRepoAnchorNames(code) {
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const declarations = [];
const collect = node => {
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name) && node.initializer) {
declarations.push({ name: node.name.text, initializer: node.initializer });
}
ts.forEachChild(node, collect);
};
collect(source);
const names = new Set();
let changed = true;
while (changed) {
changed = false;
for (const { name, initializer } of declarations) {
const rhs = initializer.getText(source);
const identifiers = rhs.match(/\b[A-Za-z_$][\w$]*\b/g) ?? [];
let call = initializer;
while (ts.isParenthesizedExpression(call) || ts.isAsExpression(call) || ts.isNonNullExpression(call)) call = call.expression;
const callee = ts.isCallExpression(call) || ts.isNewExpression(call) ? call.expression : null;
const factoryName = callee && (ts.isIdentifier(callee) ? callee.text
: ts.isPropertyAccessExpression(callee) ? callee.name.text
: ts.isElementAccessExpression(callee) && ts.isStringLiteral(callee.argumentExpression) ? callee.argumentExpression.text : null);
const pathFactory = /^(?:resolve|join|URL)$/.test(factoryName ?? '');
const directAnchor = /^\s*(?:__dirname|import\.meta\.(?:url|dirname)|process\.cwd\s*\(\s*\)|REPO_ROOT|repoRoot|desktopRoot)\b/.test(rhs);
const alias = /^\s*[A-Za-z_$][\w$]*\s*$/.test(rhs);
if ((directAnchor || pathFactory && (REPO_ANCHOR.test(rhs) || identifiers.some(identifier => names.has(identifier)))
|| alias && identifiers.some(identifier => names.has(identifier)))
&& !names.has(name)) {
names.add(name);
changed = true;
}
}
}
return names;
}
function hasRepoAnchor(text, anchorNames = new Set()) {
if (REPO_ANCHOR.test(text)) return true;
return (text.match(/\b[A-Za-z_$][\w$]*\b/g) ?? []).some(identifier => anchorNames.has(identifier));
}
/** Normalize only calls bound to fs reads, leaving strings and local shadows
* untouched. All path/execution offsets below come from this same final text.
* This is static local alias tracking, not arbitrary inter-module evaluation.
*/
function normalizeSourceReads(code) {
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const scopes = new WeakMap();
const calls = [];
const writes = new Map();
const isFunction = node => ts.isFunctionLike(node) && Boolean(node.body);
function declare(name, declaration, scope) {
if (ts.isIdentifier(name)) scope.bindings.set(name.text, declaration);
else for (const element of name.elements) {
if (ts.isBindingElement(element)) declare(element.name, element, scope);
}
}
function collect(node, scope) {
if (ts.isFunctionDeclaration(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isSourceFile(node) || ts.isBlock(node) || isFunction(node) || ts.isCatchClause(node)) scope = { parent: scope, bindings: new Map() };
scopes.set(node, scope);
if (isFunction(node)) {
if (node.name && (ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node))) scope.bindings.set(node.name.text, node);
for (const parameter of node.parameters) declare(parameter.name, parameter, scope);
}
if (ts.isVariableDeclaration(node)) declare(node.name, node, scope);
if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isCallExpression(node)) calls.push(node);
ts.forEachChild(node, child => collect(child, scope));
}
collect(source, null);
function binding(identifier) {
for (let scope = scopes.get(identifier); scope; scope = scope.parent) {
if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
}
return null;
}
function unwrap(node) {
while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isNonNullExpression(node) || ts.isAwaitExpression(node)) node = node.expression;
return node;
}
const propertyName = node => node && (ts.isIdentifier(node) || ts.isStringLiteralLike(node)) ? node.text : null;
function recordWrite(target, expression, property = null) {
target = unwrap(target);
if (ts.isIdentifier(target)) {
const bound = binding(target);
if (bound) writes.set(bound, [...(writes.get(bound) ?? []), { expression, property }]);
} else if (ts.isObjectLiteralExpression(target)) {
for (const member of target.properties) {
if (ts.isShorthandPropertyAssignment(member)) recordWrite(member.name, expression, member.name.text);
else if (ts.isPropertyAssignment(member)) recordWrite(member.initializer, expression, propertyName(member.name));
}
}
}
function collectWrites(node) {
if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken) recordWrite(node.left, node.right);
ts.forEachChild(node, collectWrites);
}
collectWrites(source);
function propertyMatches(expression, property, kind, seen) {
return kind === 'promises' && property === 'promises' && matches(expression, 'fs', seen)
|| kind === 'read' && (property === 'readFileSync' && matches(expression, 'fs', seen)
|| property === 'readFile' && (matches(expression, 'fs', seen) || matches(expression, 'promises', seen)));
}
function boundMatches(bound, kind, seen) {
if (!bound || seen.has(bound)) return false;
seen = new Set(seen).add(bound);
let declaration = bound;
while (declaration && !ts.isImportDeclaration(declaration)) declaration = declaration.parent;
const module = declaration && !declaration.importClause?.isTypeOnly && !bound.isTypeOnly
&& ts.isStringLiteral(declaration.moduleSpecifier) ? declaration.moduleSpecifier.text : '';
if (/^(?:node:)?fs(?:\/promises)?$/.test(module)) {
const namespace = module.endsWith('/promises') ? 'promises' : 'fs';
if (ts.isNamespaceImport(bound) || ts.isImportClause(bound)) return kind === namespace;
if (ts.isImportSpecifier(bound)) {
const name = bound.propertyName?.text ?? bound.name.text;
return kind === 'read' && (name === 'readFile' || namespace === 'fs' && name === 'readFileSync')
|| kind === 'promises' && namespace === 'fs' && name === 'promises';
}
}
if (ts.isBindingElement(bound) && ts.isObjectBindingPattern(bound.parent) && !bound.dotDotDotToken) {
const owner = bound.parent.parent;
const property = propertyName(bound.propertyName ?? bound.name);
if (ts.isVariableDeclaration(owner) && owner.initializer && propertyMatches(owner.initializer, property, kind, seen)) return true;
if (ts.isBindingElement(owner) && propertyMatches(owner, property, kind, seen)) return true;
if ((writes.get(owner) ?? []).some(write => !write.property && propertyMatches(write.expression, property, kind, seen))) return true;
}
if (ts.isVariableDeclaration(bound) && bound.initializer && matches(bound.initializer, kind, seen)) return true;
return (writes.get(bound) ?? []).some(write => write.property
? propertyMatches(write.expression, write.property, kind, seen) : matches(write.expression, kind, seen));
}
function matches(node, kind, seen = new Set()) {
node = unwrap(node);
if (ts.isBindingElement(node)) return boundMatches(node, kind, seen);
if (ts.isIdentifier(node)) {
const bound = binding(node);
return bound ? boundMatches(bound, kind, seen)
: kind === 'read' && /^(?:readFileSync|readFile)$/.test(node.text);
}
if (ts.isPropertyAccessExpression(node)) return propertyMatches(node.expression, node.name.text, kind, seen);
if (ts.isElementAccessExpression(node) && ts.isStringLiteralLike(node.argumentExpression)) return propertyMatches(node.expression, node.argumentExpression.text, kind, seen);
if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword
|| ts.isIdentifier(node.expression) && node.expression.text === 'require' && !binding(node.expression))) {
const module = node.arguments[0];
return module && ts.isStringLiteral(module) && /^(?:node:)?fs(?:\/promises)?$/.test(module.text)
&& kind === (module.text.endsWith('/promises') ? 'promises' : 'fs');
}
return false;
}
const wrapperReads = new WeakMap();
function localReadWrapper(bound) {
const value = bound && ts.isVariableDeclaration(bound) ? bound.initializer : bound;
const fn = value && unwrap(value);
if (!fn || !isFunction(fn)) return false;
if (!wrapperReads.has(fn)) wrapperReads.set(fn, calls.some(call => {
if (!matches(call.expression, 'read')) return false;
for (let owner = call.parent; owner; owner = owner.parent) {
if (isFunction(owner)) return owner === fn;
}
return false;
}));
return wrapperReads.get(fn);
}
const edits = [];
// Inline only immutable local string/alias bindings used as a read path.
// Reparse below so literal offsets and source-execution exemptions agree.
function pathLiteral(node, seen = new Set()) {
node = unwrap(node);
if (ts.isStringLiteralLike(node)) return node;
if (!ts.isIdentifier(node)) return null;
const bound = binding(node);
if (!bound || seen.has(bound) || writes.has(bound) || !ts.isVariableDeclaration(bound)
|| !ts.isVariableDeclarationList(bound.parent) || !(bound.parent.flags & ts.NodeFlags.Const)
|| !bound.initializer) return null;
return pathLiteral(bound.initializer, new Set(seen).add(bound));
}
function inlinePathLiterals(node) {
if (!node) return;
node = unwrap(node);
if (ts.isIdentifier(node)) {
// Member names are labels; only value references carry path bindings.
if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node
|| ts.isPropertyAssignment(node.parent) && node.parent.name === node) return;
const literal = pathLiteral(node);
if (literal && SOURCE_EXT.test(literal.text)) edits.push({ start: node.getStart(source), end: node.end, text: literal.getText(source) });
return;
}
if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
const callee = node.expression;
const name = ts.isIdentifier(callee) ? callee.text
: ts.isPropertyAccessExpression(callee) ? callee.name.text
: ts.isElementAccessExpression(callee) && ts.isStringLiteralLike(callee.argumentExpression) ? callee.argumentExpression.text : '';
if (/^(?:resolve|join|URL)$/.test(name)) for (const argument of node.arguments ?? []) inlinePathLiterals(argument);
}
}
for (const call of calls) {
const expression = call.expression;
const name = ts.isIdentifier(expression) ? expression.text
: ts.isPropertyAccessExpression(expression) ? expression.name.text : '';
// Retain the old read-shaped wrapper behavior for all local function forms,
// but a same-named passthrough or shadow must not masquerade as an fs read.
const actualRead = matches(expression, 'read') || /^(?:readFileSync|readFile)$/.test(name)
&& ts.isIdentifier(expression) && localReadWrapper(binding(expression));
if (actualRead) inlinePathLiterals(call.arguments[0]);
if (actualRead && /^(?:readFileSync|readFile)$/.test(name)) continue;
if (actualRead || /^(?:readFileSync|readFile)$/.test(name)) {
edits.push({ start: expression.getStart(source), end: expression.end, text: actualRead ? 'readFileSync' : '__nonFsRead' });
}
}
for (const edit of edits.sort((a, b) => b.start - a.start)) code = code.slice(0, edit.start) + edit.text + code.slice(edit.end);
const normalizedSource = edits.length ? parseTestSource(ts, code) : source;
const literals = [];
function collectLiterals(node) {
if (ts.isStringLiteralLike(node)) {
const literal = [node.getText(normalizedSource), null, node.text];
literal.index = node.getStart(normalizedSource);
literals.push(literal);
}
ts.forEachChild(node, collectLiterals);
}
collectLiterals(normalizedSource);
return { code, literals };
}
function findEnclosingReadCall(code, index, pattern = /\breadFile(?:Sync)?\s*\(/g) {
const starts = [...code.matchAll(pattern)];
for (let n = starts.length - 1; n >= 0; n -= 1) {
const start = starts[n].index;
if (start == null || start >= index) continue;
let depth = 1;
let quote = null;
let escaped = false;
for (let i = start + starts[n][0].length; i < index; i += 1) {
const ch = code[i];
if (quote) {
if (escaped) escaped = false;
else if (ch === '\\') escaped = true;
else if (ch === quote) quote = null;
continue;
}
if (ch === '"' || ch === "'" || ch === String.fromCharCode(96)) {
quote = ch;
} else if (ch === '(') {
depth += 1;
} else if (ch === ')') {
depth -= 1;
if (depth === 0) break;
}
}
if (depth > 0) return start;
}
return -1;
}
function findSourceReadHelpers(code) {
const helpers = new Set();
const arrowPattern = /\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:async\s*)?(?:\([^)]*\)|[A-Za-z_$][\w$]*)\s*(?::[^=;\n]+)?=>[^;{}]{0,500}\breadFile(?:Sync)?\s*\(/g;
for (const match of code.matchAll(arrowPattern)) helpers.add(match[1]);
const functionPattern = /\bfunction\s+([A-Za-z_$][\w$]*)\s*\([^)]*\)\s*(?::[^{;\n]+)?\{[^{}]{0,500}\breadFile(?:Sync)?\s*\(/g;
for (const match of code.matchAll(functionPattern)) helpers.add(match[1]);
return helpers;
}
function isSourcePathLiteral(code, match, sourceReadHelpers = new Set(), anchorNames = new Set()) {
const value = match[2];
if (!SOURCE_EXT.test(value) || /fixture|:\/\//i.test(value)) return false;
if (IMPORT_CONTEXT.test(code.slice(Math.max(0, match.index - 24), match.index))) return false;
const lineStart = code.lastIndexOf('\n', match.index) + 1;
const lineEnd = code.indexOf('\n', match.index);
const line = code.slice(lineStart, lineEnd === -1 ? undefined : lineEnd);
// Test data under a fixtures directory is input, not production source.
if (/fixture/i.test(line)) return false;
const prefix = line.slice(0, match.index - lineStart);
const helperCall = prefix.match(/\b([A-Za-z_$][\w$]*)\s*\(\s*$/)?.[1];
if (helperCall && sourceReadHelpers.has(helperCall)) return true;
// resolve(__dirname, '..', 'Sidebar.tsx') or new URL('../x.ts', import.meta.url).
if (hasRepoAnchor(line, anchorNames) && findEnclosingReadCall(code, match.index) >= 0) return true;
// A separately declared sourcePath may be formatted over several lines before
// it is passed to readFileSync. Keep that equivalent to the inline path form.
const pathStart = findEnclosingReadCall(code, match.index, /\b(?:resolve|join|URL)\s*\(/g);
if (pathStart >= 0) {
const pathEnd = code.indexOf(')', match.index + match[0].length);
const pathContext = code.slice(pathStart, pathEnd < 0 ? match.index + match[0].length : pathEnd + 1);
const binding = code.slice(Math.max(0, pathStart - 150), pathStart)
.match(/\b(?:const|let|var)\s+([A-Za-z_$][\w$]*)\s*=\s*(?:new\s+)?(?:[A-Za-z_$][\w$]*\.)?$/)?.[1];
const readBinding = binding && new RegExp('\\breadFile(?:Sync)?\\s*\\(\\s*' + binding + '\\b').test(code);
if (readBinding && hasRepoAnchor(pathContext, anchorNames) && !/fixture/i.test(pathContext)) return true;
}
// Keep the same decision for a formatted multi-line readFileSync call. The
// current line may only contain the final path segment, while the repository
// anchor and read call live on the preceding lines.
const callStart = findEnclosingReadCall(code, match.index);
if (callStart >= 0) {
const callContext = code.slice(callStart, match.index + match[0].length);
const previousContext = callContext.slice(0, -match[0].length);
const hasPriorSourceLiteral = SOURCE_LITERAL.test(previousContext);
if (/\n/.test(callContext) && !hasPriorSourceLiteral && !/[;{}]/.test(callContext) && hasRepoAnchor(callContext, anchorNames) && !/fixture/i.test(callContext)) return true;
}
// readFileSync('../x.ts') reads relative to the test process, i.e. the checkout.
return callStart >= 0 && (value.startsWith('./') || value.startsWith('../'));
}
/** Source compiled and executed by a behavior harness is not a text assertion.
* Follow each read's local bindings to execution and assertion sites separately:
* an unrelated new Function must never exempt a source-literal assertion.
*/
function executedSourcePaths(code) {
const ts = typescript ??= requireDesktop('typescript');
const source = parseTestSource(ts, code);
const scopes = new WeakMap();
const reads = [];
const calls = [];
const strings = [];
const isFunction = node => ts.isFunctionDeclaration(node) || ts.isArrowFunction(node) || ts.isFunctionExpression(node);
function collect(node, scope) {
if (ts.isFunctionDeclaration(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isSourceFile(node) || ts.isBlock(node) || isFunction(node) || ts.isForOfStatement(node)) scope = { parent: scope, bindings: new Map() };
scopes.set(node, scope);
if (isFunction(node)) for (const parameter of node.parameters) {
if (ts.isIdentifier(parameter.name)) scope.bindings.set(parameter.name.text, parameter);
}
if (ts.isVariableDeclaration(node) && ts.isIdentifier(node.name)) scope.bindings.set(node.name.text, node);
if (ts.isVariableDeclaration(node) && ts.isArrayBindingPattern(node.name)) {
const loop = node.parent.parent;
if (ts.isForOfStatement(loop)) {
for (const element of node.name.elements) {
if (ts.isBindingElement(element) && ts.isIdentifier(element.name)) scope.bindings.set(element.name.text, element);
}
}
}
if (ts.isImportSpecifier(node) || ts.isNamespaceImport(node) || ts.isImportClause(node) && node.name) scope.bindings.set(node.name.text, node);
if (ts.isStringLiteralLike(node)) strings.push(node);
if (ts.isCallExpression(node) || ts.isNewExpression(node)) {
calls.push(node);
const name = ts.isIdentifier(node.expression) ? node.expression.text
: ts.isPropertyAccessExpression(node.expression) ? node.expression.name.text : '';
if (name === 'readFileSync' || name === 'readFile') reads.push(node);
}
ts.forEachChild(node, child => collect(child, scope));
}
collect(source, null);
function binding(identifier) {
for (let scope = scopes.get(identifier); scope; scope = scope.parent) {
if (scope.bindings.has(identifier.text)) return scope.bindings.get(identifier.text);
}
return null;
}
function vmNamespace(node, seen = new Set()) {
if (!ts.isIdentifier(node) || seen.has(node)) return false;
seen.add(node);
const bound = binding(node);
if (bound && ts.isVariableDeclaration(bound) && bound.initializer) return vmNamespace(bound.initializer, seen);
const declaration = bound && (ts.isNamespaceImport(bound) ? bound.parent.parent
: ts.isImportClause(bound) ? bound.parent : null);
return declaration && ts.isImportDeclaration(declaration) && ts.isStringLiteral(declaration.moduleSpecifier)
&& /^(?:node:)?vm$/.test(declaration.moduleSpecifier.text);
}
function execution(node) {
if (!ts.isNewExpression(node) && !ts.isCallExpression(node)) return false;
if (ts.isPropertyAccessExpression(node.expression)) return /^runIn(?:New)?Context$/.test(node.expression.name.text)
&& vmNamespace(node.expression.expression);
if (!ts.isIdentifier(node.expression)) return false;
const bound = binding(node.expression);
if (!bound) return node.expression.text === 'Function';
if (!ts.isImportSpecifier(bound)) return false;
const imported = bound.propertyName?.text ?? bound.name.text;
const declaration = bound.parent.parent.parent;
return /^runIn(?:New)?Context$/.test(imported) && ts.isImportDeclaration(declaration)
&& ts.isStringLiteral(declaration.moduleSpecifier) && /^(?:node:)?vm$/.test(declaration.moduleSpecifier.text);
}
const writes = new Map();
function addWrite(bound, value) {
if (bound && value) writes.set(bound, [...(writes.get(bound) ?? []), value]);
}
function collectWrites(node) {
if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && ts.isIdentifier(node.left)) {
addWrite(binding(node.left), node.right);
}
if (ts.isCallExpression(node) && ts.isIdentifier(node.expression)) {
const bound = binding(node.expression);
const fn = bound && ts.isVariableDeclaration(bound) ? bound.initializer : bound;
if (fn && isFunction(fn)) fn.parameters.forEach((parameter, index) => addWrite(parameter, node.arguments[index]));
}
if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)
&& /^(?:set|push|unshift|add)$/.test(node.expression.name.text) && ts.isIdentifier(node.expression.expression)) {
for (const argument of node.arguments) addWrite(binding(node.expression.expression), argument);
}
ts.forEachChild(node, collectWrites);
}
collectWrites(source);
const returnCache = new WeakMap();
function returns(fn) {
if (returnCache.has(fn)) return returnCache.get(fn);
if (!fn.body) return [];
if (!ts.isBlock(fn.body)) return [fn.body];
const result = [];
function visit(node) {
if (isFunction(node)) return;
if (ts.isReturnStatement(node) && node.expression) result.push(node.expression);
ts.forEachChild(node, visit);
}
visit(fn.body);
returnCache.set(fn, result);
return result;
}
const readSet = new Set(reads);
function dependencies(node, seen = new Set(), paths = false) {
if (!node || seen.has(node)) return new Set();
seen.add(node);
if (paths && ts.isStringLiteralLike(node)) return new Set([node.getStart(source)]);
if (!paths && readSet.has(node)) return new Set([node]);
if (isFunction(node)) {
const result = new Set();
for (const value of returns(node)) for (const dependency of dependencies(value, seen, paths)) result.add(dependency);
return result;
}
if (ts.isIdentifier(node)) {
// A property label is not a read of a same-named local source variable.
// Shorthand and computed properties are expressions and still propagate.
if (ts.isPropertyAccessExpression(node.parent) && node.parent.name === node
|| ts.isPropertyAssignment(node.parent) && node.parent.name === node) return new Set();
const bound = binding(node);
const values = [...(writes.get(bound) ?? [])];
if (bound && (ts.isVariableDeclaration(bound) || ts.isParameter(bound))) values.push(bound.initializer);
if (bound && ts.isBindingElement(bound)) values.push(bound.parent.parent.parent.parent.expression);
if (bound && isFunction(bound)) values.push(...returns(bound));
const result = new Set();
for (const value of values) for (const dependency of dependencies(value, seen, paths)) result.add(dependency);
return result;
}
// Once the compiled function is invoked, its return value is behavior, not
// source text. Its code input is inspected independently at the sink below.
if (!paths && (ts.isCallExpression(node) || ts.isNewExpression(node)) && execution(node)) return new Set();
if (ts.isCallExpression(node)) {
const callee = ts.isIdentifier(node.expression) ? binding(node.expression) : null;
const fn = callee && ts.isVariableDeclaration(callee) ? callee.initializer : callee;
if (fn && isFunction(fn)) {
// Parameters already carry their actual writes. A local helper's
// output depends on its returns, not every unrelated input argument.
const result = new Set();
for (const value of returns(fn)) for (const dependency of dependencies(value, seen, paths)) result.add(dependency);
return result;
}
const initializer = callee && ts.isVariableDeclaration(callee) ? callee.initializer : node.expression;
if (!paths && initializer && execution(initializer)) return new Set();
}
const result = new Set();
ts.forEachChild(node, child => {
for (const dependency of dependencies(child, seen, paths)) result.add(dependency);
});
return result;
}
const executed = new Set();
const asserted = new Set();
for (const call of calls) {
if (execution(call)) {
for (const argument of call.arguments ?? []) for (const read of dependencies(argument)) executed.add(read);
if (ts.isPropertyAccessExpression(call.expression)) {
for (const read of dependencies(call.expression.expression)) executed.add(read);
}
}
let assertionExpression = call.expression;
while (ts.isPropertyAccessExpression(assertionExpression)) assertionExpression = assertionExpression.expression;
const assertion = ts.isIdentifier(assertionExpression) ? assertionExpression.text : '';
if (/^(?:expect|expectTypeOf|assert)$/.test(assertion)) {
for (const argument of call.arguments ?? []) for (const read of dependencies(argument)) asserted.add(read);
}
}
const exempt = new Set();
const readHelpers = findSourceReadHelpers(code);
for (const read of executed) {
if (asserted.has(read)) continue;
for (const position of dependencies(read.arguments[0], new Set(), true)) exempt.add(position);
// readSource('../x.ts') helpers keep their path at the call site. Only
// calls whose result actually depends on this executed read qualify.
for (const call of calls) {
if (!ts.isIdentifier(call.expression) || !readHelpers.has(call.expression.text) || !dependencies(call).has(read)) continue;
for (const argument of call.arguments ?? []) for (const position of dependencies(argument, new Set(), true)) exempt.add(position);
}
}
return exempt;
}
/** Count unjustified rule hits in one unit test file. */
export function scanTestSource(source, { isGuard = false } = {}) {
const code = stripComments(source);
const lines = source.split(/\r?\n/);
const executableCode = maskStrings(code);
const resetModules = countModuleResets(code, lines);
const realWaits = countRealWaits(executableCode, lines, code);
let sourceReads = 0;
if (!isGuard && /\breadFile(?:Sync)?\b|\?raw/.test(code)) {
const normalized = normalizeSourceReads(code);
const sourceReadHelpers = findSourceReadHelpers(normalized.code);
const anchorNames = findRepoAnchorNames(normalized.code);
const executablePaths = /\bFunction\b|\brunIn(?:New)?Context\b/.test(normalized.code) ? executedSourcePaths(normalized.code) : new Set();
for (const match of normalized.literals) {
if (executablePaths.has(match.index)) continue;
if (match[2].endsWith('?raw') || isSourcePathLiteral(normalized.code, match, sourceReadHelpers, anchorNames)) sourceReads += 1;
}
}
return { resetModules, realWaits, sourceReads };
}
function walk(dir, out) {
let entries;
try {
entries = readdirSync(dir, { withFileTypes: true });
} catch {
return;
}
for (const entry of entries) {
if (entry.isDirectory()) {
if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) walk(path.join(dir, entry.name), out);
} else if (TEST_FILE.test(entry.name) && !NON_UNIT_TEST.test(entry.name)) {
out.push(path.join(dir, entry.name));
}
}
}
async function loadGuardFiles(root) {
const configUrl = pathToFileURL(path.join(root, 'scripts', 'test-workspaces.config.mjs'));
const { default: manifest } = await import(configUrl.href);
const guard = new Set();
for (const workspace of manifest.workspaces) {
for (const file of workspace.tiers?.guard?.include ?? []) {
guard.add(path.posix.join(workspace.cwd, file));
}
}
return guard;
}
export async function scanRepository(root = ROOT) {
const files = [];
for (const scanRoot of SCAN_ROOTS) walk(path.join(root, scanRoot), files);
const guard = await loadGuardFiles(root);
const counts = {};
for (const file of files.sort()) {
const rel = path.relative(root, file).split(path.sep).join('/');
// Only explicitly registered contracts or frozen DB inputs may inspect
// application source; their reload/wait rules still run, like guard suites.
const result = scanTestSource(readFileSync(file, 'utf8'), { isGuard: guard.has(rel) || ROOT_SOURCE_CONTRACTS.has(rel) || DB_SOURCE_INPUTS.has(rel) });
if (RULES.some((rule) => result[rule] > 0)) counts[rel] = result;
}
return counts;
}
/** Compare current counts with the ratchet baseline. */
export function compareWithBaseline(counts, baseline) {
const violations = [];
const tightenable = [];
for (const [file, current] of Object.entries(counts)) {
const allowed = baseline[file] ?? {};
for (const rule of RULES) {
const limit = allowed[rule] ?? 0;
if (current[rule] > limit) violations.push({ file, rule, current: current[rule], limit });
}
}
for (const [file, allowed] of Object.entries(baseline)) {
const current = counts[file] ?? {};
if (RULES.some((rule) => (current[rule] ?? 0) < (allowed[rule] ?? 0))) tightenable.push(file);
}
return { violations, tightenable };
}
const HINTS = {
resetModules: 'beforeEach/afterEach 及其准备、清理 helper 禁止重载模块,写理由也不豁免;显式重启边界上一行写 `// reset-modules: <原因>`;优先用生产代码的 dispose/reset 或依赖注入',
realWaits: '改用 vi.useFakeTimers() 或等待真实事件;确需真实等待时上一行写 `// real-wait: <原因>`',
sourceReads: '普通单测不得读取源码文本做字面量断言;改为经生产入口验证行为,纯跨文件契约移入对应包的 guard tier',
};
function parseBaseline(text, label) {
let body;
try { body = JSON.parse(text); } catch { throw new Error('invalid baseline JSON: ' + label); }
const record = value => value !== null && typeof value === 'object' && !Array.isArray(value);
if (!record(body) || !record(body.files)) throw new Error('invalid baseline files: ' + label);
for (const [file, rules] of Object.entries(body.files)) {
if (!record(rules) || Object.entries(rules).some(([rule, count]) => !RULES.includes(rule) || !Number.isSafeInteger(count) || count < 0)) {
throw new Error('invalid baseline limits: ' + label + ' (' + file + ')');
}
}
return body.files;
}
function readBaseline() {
if (!existsSync(BASELINE_PATH)) return {};
return parseBaseline(readFileSync(BASELINE_PATH, 'utf8'), BASELINE_REL);
}
function readTrustedBaseline() {
const event = process.env.GITHUB_EVENT_PATH ? JSON.parse(readFileSync(process.env.GITHUB_EVENT_PATH, 'utf8')) : {};
const remoteBase = process.env.GITHUB_BASE_REF ? 'refs/remotes/origin/' + process.env.GITHUB_BASE_REF : null;
const eventName = process.env.GITHUB_EVENT_NAME;
let ref;
if (eventName === 'pull_request') ref = event.pull_request?.base?.sha ?? remoteBase;
else if (eventName === 'merge_group') ref = event.merge_group?.base_sha;
else if (eventName === 'push') ref = event.before;
else ref = remoteBase ?? 'refs/remotes/origin/main';
if (!ref || /^0+$/.test(ref)) throw new Error('trusted Git base is unavailable for ' + (eventName || 'local check'));
const git = args => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
let commit;
let entry;
try {
commit = git(['rev-parse', '--verify', '--end-of-options', ref + '^{commit}']);
entry = git(['ls-tree', '--name-only', commit, '--', BASELINE_REL]);
} catch {
throw new Error('trusted Git base cannot be read: ' + ref);
}
// Only a successfully read commit with no baseline path is first adoption.
// Missing refs/history and Git failures must never silently bootstrap.
if (!entry) return { files: null, commit };
let text;
try { text = git(['show', commit + ':' + BASELINE_REL]); }
catch { throw new Error('trusted Git baseline cannot be read: ' + commit); }
return { files: parseBaseline(text, 'trusted ' + commit), commit };
}
function writeBaseline(files) {
const sorted = Object.fromEntries(Object.entries(files).sort(([a], [b]) => a.localeCompare(b)));
const body = {
description: 'Ratchet baseline for scripts/check-test-hygiene.mjs. Counts may only go down; see engineering-conventions.md §3.2.',
files: sorted,
};
writeFileSync(BASELINE_PATH, `${JSON.stringify(body, null, 2)}\n`);
}
export async function main(args = process.argv.slice(2)) {
const trusted = readTrustedBaseline();
const hasBaseline = existsSync(BASELINE_PATH);
const baseline = readBaseline();
if (!hasBaseline && (trusted.files !== null || !args.includes('--update'))) throw new Error('baseline is missing: ' + BASELINE_REL);
if (trusted.files === null) console.log('[test-hygiene] bootstrap: trusted base ' + trusted.commit + ' has no baseline yet');
else {
const raised = compareWithBaseline(baseline, trusted.files).violations;
if (raised.length > 0) {
for (const item of raised) console.error('[test-hygiene] baseline cannot increase ' + item.file + ' ' + item.rule + ': ' + item.limit + ' -> ' + item.current);
return 1;
}
}
const counts = await scanRepository();
const { violations, tightenable } = compareWithBaseline(counts, baseline);
if (args.includes('--update')) {
// The very first run records the existing debt; afterwards --update only tightens.
if (violations.length > 0 && existsSync(BASELINE_PATH)) {
for (const v of violations) console.error(`refusing to raise ${v.rule} for ${v.file}: ${v.limit} -> ${v.current}`);
console.error('[test-hygiene] --update only tightens the baseline; fix the new hits instead.');
return 1;
}
const next = {};
for (const [file, current] of Object.entries(counts)) {
const entry = Object.fromEntries(RULES.filter((rule) => current[rule] > 0).map((rule) => [rule, current[rule]]));
if (Object.keys(entry).length > 0) next[file] = entry;
}
writeBaseline(next);
console.log(`[test-hygiene] baseline updated: ${Object.keys(next).length} files`);
return 0;
}
if (violations.length === 0) {
if (tightenable.length > 0) {
console.error(`[test-hygiene] FAIL — ${tightenable.length} baseline entries can be tightened; run node scripts/check-test-hygiene.mjs --update`);
return 1;
}
console.log(`[test-hygiene] PASS (${Object.keys(counts).length} files within baseline)`);
return 0;
}
for (const v of violations) {
console.error(`❌ [${v.rule}] ${v.file}: ${v.current} unjustified hit(s), baseline allows ${v.limit}`);
console.error(` ${HINTS[v.rule]}`);
}
console.error('[test-hygiene] FAIL — see docs/dev-rules/engineering-conventions.md §3.2');
return 1;
}
// macOS temp directories and linked CLI entrypoints may spell the same file
// differently from import.meta.url, which Node resolves to its real path.
if (process.argv[1] && existsSync(process.argv[1]) && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
main().then((code) => { process.exitCode = code; }, (error) => {
console.error(`[test-hygiene] ${error.message}`);
process.exitCode = 2;
});
}