/**
* Pure-JS category classifier (U5, KTD11, KTD19).
*
* Decides which `gitnexus/test/unit` files a mutation run can use in a prepared copy
* (tools/mutation/prepare) without native code, workers, child processes, or file reads that the
* prepared copy breaks. Gate 1 (U6) records the modules each accepted test loads at runtime and
* fails on a native binding, worker or child_process load, so a miss here surfaces there.
*
* Walk. Each test file's import closure, parsed with @babel/parser:
* - `import` declarations, except `import type`, type-only specifiers, and value imports whose
* bindings are never used as values (the TypeScript transform erases those, because the repo
* does not set `verbatimModuleSyntax`); `export ... from`; `import x = require()`.
* - `import()`, `require()`, `createRequire()` results called directly or through a const,
* `vi.importActual()`, `vi.importMock()`, and `vi.mock()`/`vi.doMock()` unless the factory
* takes no parameter (automocking and `importOriginal` load the real module).
* A specifier must evaluate statically: a string literal, a template or `+` concatenation of
* those, an identifier whose binding (resolved lexically; a redeclared name is unknown) is a
* `const` initialised with such a value, or an absolute path or file URL built from
* `import.meta.url`, `__dirname`, `process.cwd()`, `path.join/resolve/dirname/sep`, `new URL()`,
* `fileURLToPath()` and `pathToFileURL().href`. Type assertions are looked through.
* Anything else is "unresolvable dynamic import". Relative specifiers resolve like Vite (exact
* file, `.js` to `.ts`/`.tsx`, appended extensions, directory `index`); `gitnexus-shared[/x]`
* resolves through that package's `exports` (`./dist/X.js` maps to `src/X.ts`, KTD8); node
* builtins and other bare packages are leaves (package code is not walked).
*
* Rejection reasons:
* - `native package: `: a bare package on {@link KNOWN_NATIVE_PACKAGES}, or one that ships a
* `.node` file, a `binding.gyp` or `"gypfile": true`, or reaches such a package through the
* installed packages of its `dependencies`/`optionalDependencies`. `vitest` and `@vitest/*` are
* the harness and exempt.
* - `native binding: `: an import resolves to a `.node` file.
* - `spawns processes: child_process|cluster`: the closure imports that builtin, or a package on
* {@link KNOWN_PROCESS_PACKAGES} (its own code loads `child_process` when imported).
* - `spawns workers: worker_threads`: the closure imports `Worker` from `worker_threads`, or the
* whole module (default/namespace binding, non-destructured `require`/`import()`).
* - `imports outside gitnexus/`, `imports from ignored dir: /`: a relative import leaves the
* package (gitnexus-shared/src is reachable only through its alias, and a shared module may
* not leave gitnexus-shared/src), or lands in a directory the Stryker sandbox omits
* (stryker-config.ts `DEFAULT_IGNORED_DIRS`).
* - `unresolved import: `, `unsupported import specifier: `,
* `unresolvable dynamic import`, `parse error`.
* - Reads, checked in test-side modules only (every module of the closure outside `gitnexus/src`
* and `gitnexus-shared/src`; production modules that import fs do not count):
* `reads source under src/`, `reads test fixtures`, `reads ignored dir: /`,
* `reads source outside gitnexus/`, `unresolvable file path`. Two rules: (a) every path
* expression anchored to a location (`__dirname`, `__filename`, `import.meta.url|dirname|
* filename`, `process.cwd()`, or a const bound to one) is evaluated through the functions above,
* templates and `+`, whether or not it reaches an fs call; (b) the first argument of an
* `fs`/`fs/promises` call that is a relative literal resolves against the package dir (the
* Vitest root and cwd). When a trailing part is not static, the known prefix decides, and a
* prefix that contains a checked directory (the package root, `test/`, anything above the
* package) is "unresolvable file path".
*
* Limits: paths built by helper functions or passed through parameters are not followed, and a
* production function reading a path the test hands it is not seen; an unknown suffix is assumed
* not to contain `..`; package internals are not walked for child_process or worker use (gate 1
* sees them, and the packages it finds go on {@link KNOWN_PROCESS_PACKAGES}); `vi.mock` factories
* do not neutralise a module other imports load (conservative); Babel parse failures reject the
* file; hook and test counts look at the test file only.
*
* CLI (from gitnexus/):
* node --import tsx tools/mutation/classify/classify.ts [--root test/unit] [--file ]...
* [--out ] [--closure]
* Without `--out` the JSON goes to stdout; with it, a summary does. `--closure` keeps each file's
* closure, package and builtin lists in the JSON.
*/
import { readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from 'node:fs';
import { builtinModules } from 'node:module';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
import { parseArgs } from 'node:util';
import { parse, type ParserOptions } from '@babel/parser';
import {
VISITOR_KEYS,
type CallExpression,
type ExportNamedDeclaration,
type File,
type ImportDeclaration,
type MemberExpression,
type NewExpression,
type Node,
} from '@babel/types';
import { DEFAULT_IGNORED_DIRS } from '../driver/stryker-config.js';
import { errorMessage, isMainModule } from '../shared/cli.js';
export const CLASSIFY_SCHEMA_VERSION = 1;
/**
* Packages rejected by name, installed or not, so the verdict does not depend on what a checkout
* installed; detection on disk adds the rest. `@huggingface/transformers` always depends on
* `onnxruntime-node` and `sharp`.
*/
export const KNOWN_NATIVE_PACKAGES: readonly RegExp[] = Object.freeze([
/^tree-sitter$/,
/^tree-sitter-/,
/^@ladybugdb\//,
/^onnxruntime-/,
/^@huggingface\/transformers$/,
/^sharp$/,
/^fsevents$/,
/^node-gyp-build$/,
/^bindings$/,
]);
/**
* Pure-JS packages whose own code loads `child_process` when imported. The walk does not enter
* package code, so gate 1's runtime load check (tools/mutation/fidelity) finds them; each entry
* names its evidence. `commander`: lib/command.js requires `node:child_process` at the top (for
* executable subcommands); gate 1 saw it load in test/unit/cli-command-banner.test.ts.
*/
export const KNOWN_PROCESS_PACKAGES: readonly RegExp[] = Object.freeze([/^commander$/]);
/** The test harness itself: always loaded, never a reason to reject. */
const isHarnessPackage = (name: string): boolean =>
name === 'vitest' || name.startsWith('@vitest/');
const SHARED_PACKAGE = 'gitnexus-shared';
const PROCESS_BUILTINS = new Set(['child_process', 'cluster']);
const WORKER_BUILTIN = 'worker_threads';
const FS_MODULES = new Set(['fs', 'fs/promises']);
const PATH_MODULES = new Set(['path', 'url']);
const PATH_ONLY = new Set(['path']);
const BUILTINS = new Set(builtinModules);
/** Vite's default `resolve.extensions` order. */
const APPENDED_EXTENSIONS = ['.mjs', '.js', '.mts', '.ts', '.jsx', '.tsx', '.json'];
const TS_FOR_JS: Readonly> = {
'.js': ['.ts', '.tsx'],
'.jsx': ['.tsx'],
'.mjs': ['.mts'],
'.cjs': ['.cts'],
};
const WALKED_EXTENSIONS = new Set(['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs']);
const HOOK_NAMES = ['beforeAll', 'beforeEach', 'afterAll', 'afterEach'] as const;
const TEST_ROOTS = new Set(['it', 'test']);
const EACH_ROOTS = new Set(['it', 'test', 'describe', 'suite']);
// ── Public types ───────────────────────────────────────────────────────────
export type HookCounts = Record<(typeof HOOK_NAMES)[number], number>;
export interface Evidence {
reason: string;
/** Repo-relative POSIX path of the module where the reason was found. */
module: string;
line: number;
detail: string;
/** Import chain from the test file to {@link module}, both included. */
via: string[];
}
export interface FileVerdict {
/** Package-relative POSIX path, e.g. `test/unit/schema.test.ts`. */
file: string;
status: 'accepted' | 'rejected';
/** Sorted, distinct; empty when accepted. */
reasons: string[];
/** The first occurrence of each reason in breadth-first closure order, sorted by reason. */
evidence: Evidence[];
hooks: HookCounts;
/** `.each`/`.for` calls on `it`/`test`/`describe`/`suite` in the test file. */
eachCalls: number;
/** Outermost `it`/`test` call sites in the test file (an `it.each` row set counts once). */
testCalls: number;
/** Repo-relative local modules and data files of the import closure, test file included. */
closure: string[];
/** Bare packages the closure imports (leaves). */
packages: string[];
/** Node builtins the closure imports, without the `node:` prefix. */
builtins: string[];
}
export interface ClassificationSummary {
total: number;
accepted: number;
rejected: number;
/** Rejected files per reason; a file counts once for each of its reasons. */
byReason: Record;
/** Rejected files per reason category (the text before `: `). */
byCategory: Record;
}
export interface Classification {
schemaVersion: typeof CLASSIFY_SCHEMA_VERSION;
/** Package-relative directory that was listed, or null for an explicit file list. */
testRoot: string | null;
files: FileVerdict[];
accepted: string[];
rejected: { file: string; reasons: string[] }[];
acceptedWithBeforeAll: string[];
summary: ClassificationSummary;
}
export interface ClassifyOptions {
/** Directory holding `gitnexus/` and `gitnexus-shared/`. */
repoRoot: string;
/** Package-relative test files; defaults to every `*.test.ts` under {@link testRoot}. */
testFiles?: readonly string[];
/** Package-relative directory to list; default `test/unit`. */
testRoot?: string;
}
// ── Static values ──────────────────────────────────────────────────────────
/**
* What an expression evaluates to: plain text, an absolute file path (or file URL) anchored to a
* known location, or unknown. A `file` value with `exact: false` is a prefix: the expression
* names something inside `abs` whose remaining segments are not static.
*/
type Value =
| { kind: 'text'; text: string }
| { kind: 'file'; abs: string; url: boolean; exact: boolean }
| { kind: 'unknown' };
const UNKNOWN: Value = { kind: 'unknown' };
const text = (value: string): Value => ({ kind: 'text', text: value });
const file = (abs: string, url = false): Value => ({ kind: 'file', abs, url, exact: true });
/** A name's declaration; a `const` keeps the scopes around it to evaluate its initialiser. */
type Binding =
| { kind: 'const'; init: Node | null | undefined; scopes: readonly Node[] }
| { kind: 'import'; source: string; imported: string }
| { kind: 'other' };
const OTHER: Binding = { kind: 'other' };
type EdgeTarget =
| { kind: 'specifier'; specifier: string; fromDir: string }
| { kind: 'file'; abs: string };
interface ImportEdge {
target: EdgeTarget;
line: number;
/** Imported names when known; null when the importer can reach every export. */
names: readonly string[] | null;
}
interface Finding {
reason: string;
line: number;
detail: string;
}
interface ModuleFacts {
edges: ImportEdge[];
/** Reasons that apply wherever the module sits (unresolvable dynamic imports, parse errors). */
findings: Finding[];
/** Read-rule hits; computed for test-side modules only. */
reads: Finding[];
hooks: HookCounts;
eachCalls: number;
testCalls: number;
}
type Resolved =
| { kind: 'module'; abs: string }
| { kind: 'leaf'; abs: string }
| { kind: 'builtin'; name: string }
| { kind: 'package'; name: string }
| { kind: 'reject'; reason: string; detail: string };
// ── AST helpers ────────────────────────────────────────────────────────────
/** Keys holding type syntax, which never runs. */
const TYPE_KEYS = new Set([
'typeAnnotation',
'typeParameters',
'typeArguments',
'returnType',
'superTypeArguments',
'superTypeParameters',
'implements',
'predicate',
]);
/** Declarations that are types only. */
const TYPE_ONLY_NODES = new Set([
'TSInterfaceDeclaration',
'TSTypeAliasDeclaration',
'TSDeclareFunction',
'TSDeclareMethod',
'TSIndexSignature',
'TSImportType',
]);
const KEYED_NODES = new Set([
'ObjectProperty',
'ObjectMethod',
'ClassProperty',
'ClassMethod',
'ClassAccessorProperty',
'ClassPrivateProperty',
'ClassPrivateMethod',
]);
const FUNCTION_NODES = new Set([
'FunctionDeclaration',
'FunctionExpression',
'ArrowFunctionExpression',
'ObjectMethod',
'ClassMethod',
'ClassPrivateMethod',
]);
/** Nodes that open a lexical scope (`var` goes to the nearest function or the program). */
const SCOPE_NODES = new Set([
'Program',
'BlockStatement',
'CatchClause',
'ForStatement',
'ForInStatement',
'ForOfStatement',
'SwitchStatement',
'StaticBlock',
...FUNCTION_NODES,
]);
/** Type-only wrappers around a runtime expression. */
const TS_WRAPPERS = new Set([
'TSAsExpression',
'TSSatisfiesExpression',
'TSNonNullExpression',
'TSTypeAssertion',
'ParenthesizedExpression',
]);
const isNode = (value: unknown): value is Node =>
typeof value === 'object' &&
value !== null &&
typeof (value as { type?: unknown }).type === 'string';
const flag = (node: Node, key: 'computed' | 'declare'): boolean =>
(node as unknown as Record)[key] === true;
/** Child keys of `node` that hold runtime values (identifiers in name positions are skipped). */
function valueKeys(node: Node): readonly string[] {
const keys = VISITOR_KEYS[node.type] ?? [];
if (node.type === 'MetaProperty') return [];
return keys.filter((key) => {
if (TYPE_KEYS.has(key)) return false;
if (key === 'property' && !flag(node, 'computed')) {
return node.type !== 'MemberExpression' && node.type !== 'OptionalMemberExpression';
}
if (key === 'key' && KEYED_NODES.has(node.type)) return flag(node, 'computed');
if (key === 'label') return false;
if (node.type === 'ExportSpecifier') return key === 'local';
if (node.type === 'TSEnumMember') return key !== 'id';
return true;
});
}
/** `scopes` lists the scope nodes around `node`, outermost first, excluding `node` itself. */
type Visitor = (node: Node, ancestors: readonly Node[], scopes: readonly Node[]) => boolean;
/** Depth-first walk over runtime syntax; the visitor returns false to skip a node's children. */
function walk(root: Node, visit: Visitor): void {
const ancestors: Node[] = [];
const scopes: Node[] = [];
const go = (node: Node): void => {
if (TYPE_ONLY_NODES.has(node.type) || flag(node, 'declare')) return;
if (!visit(node, ancestors, scopes)) return;
const scoped = SCOPE_NODES.has(node.type);
ancestors.push(node);
if (scoped) scopes.push(node);
for (const key of valueKeys(node)) {
const child = (node as unknown as Record)[key];
if (Array.isArray(child)) {
for (const item of child) if (isNode(item)) go(item);
} else if (isNode(child)) {
go(child);
}
}
if (scoped) scopes.pop();
ancestors.pop();
};
go(root);
}
/** `node` without type-only wrappers (`x as T`, `x!`, `(x)`). */
function unwrap(node: Node | null | undefined): Node | null | undefined {
let current = node;
while (current && TS_WRAPPERS.has(current.type)) {
current = (current as Node & { expression: Node }).expression;
}
return current;
}
/** The module a `require('m')` / `await import('m')` initialiser loads, or null. */
function loadedModule(init: Node | null | undefined): string | null {
const unwrapped = unwrap(init);
const call = unwrapped?.type === 'AwaitExpression' ? unwrap(unwrapped.argument) : unwrapped;
if (call?.type === 'ImportExpression' && call.source.type === 'StringLiteral') {
return call.source.value;
}
if (
call?.type === 'CallExpression' &&
call.callee.type === 'Identifier' &&
call.callee.name === 'require' &&
call.arguments[0]?.type === 'StringLiteral'
) {
return call.arguments[0].value;
}
return null;
}
const lineOf = (node: Node): number => node.loc?.start.line ?? 0;
/** Strips `node:` and maps `path/posix` to `path` so module checks see one name. */
const normaliseModule = (source: string): string => {
const bare = source.startsWith('node:') ? source.slice('node:'.length) : source;
return bare === 'path/posix' ? 'path' : bare;
};
const propertyName = (node: MemberExpression): string | null =>
!node.computed && node.property.type === 'Identifier' ? node.property.name : null;
const keyName = (key: Node): string | null =>
key.type === 'Identifier' ? key.name : key.type === 'StringLiteral' ? key.value : null;
/** Root identifier of a callee chain such as `it.concurrent.each(rows)`. */
function calleeRoot(node: Node): string | null {
if (node.type === 'Identifier') return node.name;
if (node.type === 'MemberExpression') return calleeRoot(node.object);
if (node.type === 'CallExpression') return calleeRoot(node.callee);
return null;
}
const isCreateRequireCall = (node: Node | null | undefined): node is CallExpression =>
node?.type === 'CallExpression' &&
((node.callee.type === 'Identifier' && node.callee.name === 'createRequire') ||
(node.callee.type === 'MemberExpression' && propertyName(node.callee) === 'createRequire'));
const toPosix = (value: string): string => value.split(path.sep).join('/');
/** True when POSIX `rel` is `dir` or inside it. */
const isWithin = (rel: string, dir: string): boolean => rel === dir || rel.startsWith(`${dir}/`);
/** True when POSIX `rel` is `dir` or one of its ancestors (`''` is the root). */
const contains = (rel: string, dir: string): boolean => rel === '' || isWithin(dir, rel);
const isInside = (abs: string, dir: string): boolean => {
const rel = path.relative(dir, abs);
return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
};
/** `@scope/name` or `name` of a bare specifier, or null when it is not a package specifier. */
function packageName(specifier: string): string | null {
const segments = specifier.split('/');
if (specifier.startsWith('@')) {
return segments.length >= 2 && segments[1] !== '' ? `${segments[0]}/${segments[1]}` : null;
}
return segments[0] === '' || specifier.startsWith('#') ? null : segments[0];
}
// ── Module analysis ────────────────────────────────────────────────────────
interface AnalysisContext {
packageDir: string;
/** Read rules apply (the module is not production code). */
testSide: boolean;
/** Repo-relative display path. */
display: (abs: string) => string;
}
/** Facts of one module: import edges, dynamic-import failures, read-rule hits and test API use. */
class ModuleAnalysis {
private readonly scopeBindings = new Map>();
private readonly references = new Map();
private readonly values = new Map();
private readonly evaluating = new Set();
private readonly skipped = new WeakSet();
private readonly calleeCalls = new WeakSet();
readonly facts: ModuleFacts = {
edges: [],
findings: [],
reads: [],
hooks: { beforeAll: 0, beforeEach: 0, afterAll: 0, afterEach: 0 },
eachCalls: 0,
testCalls: 0,
};
constructor(
private readonly file: string,
private readonly source: string,
ast: File,
private readonly context: AnalysisContext,
) {
walk(ast.program, (node, ancestors, scopes) => this.collect(node, ancestors, scopes));
walk(ast.program, (node, ancestors, scopes) => this.analyse(node, ancestors, scopes));
}
// Pass 1: bindings per scope, and value references.
private bind(scope: Node | undefined, name: string, binding: Binding): void {
if (!scope) return;
let names = this.scopeBindings.get(scope);
if (!names) {
names = new Map();
this.scopeBindings.set(scope, names);
}
const list = names.get(name);
if (list) list.push(binding);
else names.set(name, [binding]);
}
private bindPattern(scope: Node | undefined, pattern: Node | null | undefined): void {
if (!pattern) return;
switch (pattern.type) {
case 'Identifier':
this.bind(scope, pattern.name, { kind: 'other' });
return;
case 'ObjectPattern':
for (const property of pattern.properties) {
this.bindPattern(
scope,
property.type === 'RestElement' ? property.argument : property.value,
);
}
return;
case 'ArrayPattern':
for (const element of pattern.elements) this.bindPattern(scope, element);
return;
case 'AssignmentPattern':
this.bindPattern(scope, pattern.left);
return;
case 'RestElement':
this.bindPattern(scope, pattern.argument);
return;
case 'TSParameterProperty':
this.bindPattern(scope, pattern.parameter);
return;
default:
return;
}
}
private collect(node: Node, ancestors: readonly Node[], scopes: readonly Node[]): boolean {
const current = scopes[scopes.length - 1];
switch (node.type) {
case 'ImportDeclaration':
if (node.importKind !== 'type') {
for (const specifier of node.specifiers) {
if (specifier.type === 'ImportSpecifier' && specifier.importKind === 'type') continue;
this.bind(current, specifier.local.name, {
kind: 'import',
source: node.source.value,
imported:
specifier.type === 'ImportDefaultSpecifier'
? 'default'
: specifier.type === 'ImportNamespaceSpecifier'
? '*'
: (keyName(specifier.imported) ?? '*'),
});
}
}
return false;
case 'TSImportEqualsDeclaration':
if (node.moduleReference.type === 'TSExternalModuleReference') {
this.bind(current, node.id.name, {
kind: 'import',
source: node.moduleReference.expression.value,
imported: '*',
});
}
return false;
case 'ExportAllDeclaration':
return false;
case 'ExportNamedDeclaration':
return !node.source;
case 'Identifier':
this.references.set(node.name, (this.references.get(node.name) ?? 0) + 1);
return true;
case 'VariableDeclarator': {
const declaration = ancestors[ancestors.length - 1];
const kind = declaration?.type === 'VariableDeclaration' ? declaration.kind : 'var';
const scope =
kind === 'var'
? [...scopes].reverse().find((s) => s.type === 'Program' || FUNCTION_NODES.has(s.type))
: current;
const loaded = loadedModule(node.init);
if (node.id.type === 'Identifier') {
this.bind(
scope,
node.id.name,
kind === 'const' ? { kind: 'const', init: node.init, scopes: [...scopes] } : OTHER,
);
} else if (node.id.type === 'ObjectPattern' && loaded !== null) {
for (const property of node.id.properties) {
const name =
property.type === 'ObjectProperty' && !property.computed
? keyName(property.key)
: null;
if (property.type === 'ObjectProperty' && name !== null) {
if (property.value.type === 'Identifier') {
this.bind(scope, property.value.name, {
kind: 'import',
source: loaded,
imported: name,
});
} else {
this.bindPattern(scope, property.value);
}
} else {
this.bindPattern(
scope,
property.type === 'RestElement' ? property.argument : property,
);
}
}
} else {
this.bindPattern(scope, node.id);
}
return true;
}
case 'ClassDeclaration':
case 'TSEnumDeclaration':
if (node.id?.type === 'Identifier') this.bind(current, node.id.name, OTHER);
return true;
case 'CatchClause':
this.bindPattern(node, node.param);
return true;
default:
if (FUNCTION_NODES.has(node.type)) {
const fn = node as Node & { id?: Node | null; params: readonly Node[] };
this.bindPattern(node.type === 'FunctionDeclaration' ? current : node, fn.id);
for (const param of fn.params) this.bindPattern(node, param);
}
return true;
}
}
/** The binding `name` resolves to from a position inside `scopes` (outermost first). */
private lookup(name: string, scopes: readonly Node[]): Binding | 'global' | 'ambiguous' {
for (let index = scopes.length - 1; index >= 0; index -= 1) {
const list = this.scopeBindings.get(scopes[index])?.get(name);
if (list) return list.length === 1 ? list[0] : 'ambiguous';
}
return 'global';
}
/** The module and export an identifier stands for, when its binding is import-like. */
private refersTo(
name: string,
scopes: readonly Node[],
): { module: string; imported: string } | null {
const binding = this.lookup(name, scopes);
if (typeof binding === 'string') return null;
if (binding.kind === 'import') {
return { module: normaliseModule(binding.source), imported: binding.imported };
}
if (binding.kind === 'const') {
const loaded = loadedModule(binding.init);
return loaded === null ? null : { module: normaliseModule(loaded), imported: '*' };
}
return null;
}
private isModuleObject(node: Node, modules: ReadonlySet, scopes: readonly Node[]) {
if (node.type !== 'Identifier') return false;
const target = this.refersTo(node.name, scopes);
return (
target !== null &&
modules.has(target.module) &&
(target.imported === '*' || target.imported === 'default')
);
}
// Static evaluation.
private evaluateIdentifier(name: string, scopes: readonly Node[]): Value {
const binding = this.lookup(name, scopes);
if (binding === 'global') {
if (name === '__dirname') return file(path.dirname(this.file));
if (name === '__filename') return file(this.file);
return UNKNOWN;
}
if (binding === 'ambiguous' || binding.kind !== 'const') return UNKNOWN;
const cached = this.values.get(binding);
if (cached) return cached;
if (this.evaluating.has(binding)) return UNKNOWN;
this.evaluating.add(binding);
const value = this.evaluate(binding.init, binding.scopes);
this.evaluating.delete(binding);
this.values.set(binding, value);
return value;
}
/** `path`/`url` function a callee names, or `cwd` for `process.cwd`. */
private pathFunction(callee: Node, scopes: readonly Node[]): string | null {
if (callee.type === 'Identifier') {
const target = this.refersTo(callee.name, scopes);
return target && (target.module === 'path' || target.module === 'url')
? target.imported
: null;
}
if (callee.type !== 'MemberExpression') return null;
const name = propertyName(callee);
if (name === null) return null;
const object = callee.object;
if (
object.type === 'Identifier' &&
object.name === 'process' &&
this.lookup('process', scopes) === 'global'
) {
return name === 'cwd' ? 'cwd' : null;
}
if (this.isModuleObject(object, PATH_MODULES, scopes)) return name;
if (
object.type === 'MemberExpression' &&
propertyName(object) === 'posix' &&
this.isModuleObject(object.object, PATH_ONLY, scopes)
) {
return name;
}
return null;
}
private evaluate(node: Node | null | undefined, scopes: readonly Node[]): Value {
if (!node) return UNKNOWN;
switch (node.type) {
case 'StringLiteral':
return text(node.value);
case 'TemplateLiteral': {
const parts: Value[] = [];
node.quasis.forEach((quasi, index) => {
parts.push(quasi.value.cooked == null ? UNKNOWN : text(quasi.value.cooked));
const expression = node.expressions[index];
if (expression) parts.push(this.evaluate(expression, scopes));
});
return this.concat(parts);
}
case 'BinaryExpression':
return node.operator === '+'
? this.concat([this.evaluate(node.left, scopes), this.evaluate(node.right, scopes)])
: UNKNOWN;
case 'Identifier':
return this.evaluateIdentifier(node.name, scopes);
case 'TSAsExpression':
case 'TSSatisfiesExpression':
case 'TSNonNullExpression':
case 'TSTypeAssertion':
case 'ParenthesizedExpression':
return this.evaluate(node.expression, scopes);
case 'MemberExpression':
return this.evaluateMember(node, scopes);
case 'CallExpression':
return this.evaluateCall(node, scopes);
case 'NewExpression':
return this.evaluateNew(node, scopes);
default:
return UNKNOWN;
}
}
private evaluateMember(node: MemberExpression, scopes: readonly Node[]): Value {
const name = propertyName(node);
if (
node.object.type === 'MetaProperty' &&
node.object.meta.name === 'import' &&
node.object.property.name === 'meta'
) {
if (name === 'url') return file(this.file, true);
if (name === 'filename') return file(this.file);
if (name === 'dirname') return file(path.dirname(this.file));
return UNKNOWN;
}
if (
(name === 'sep' || name === 'delimiter') &&
this.isModuleObject(node.object, PATH_ONLY, scopes)
) {
return text(name === 'sep' ? path.sep : path.delimiter);
}
const object = this.evaluate(node.object, scopes);
if (object.kind !== 'file' || !object.url) return UNKNOWN;
if (name === 'href') return object;
if (name === 'pathname') return { ...object, url: false };
return UNKNOWN;
}
private evaluateCall(node: CallExpression, scopes: readonly Node[]): Value {
if (
node.callee.type === 'MemberExpression' &&
propertyName(node.callee) === 'toString' &&
node.arguments.length === 0
) {
const object = this.evaluate(node.callee.object, scopes);
return object.kind === 'file' && object.url ? object : UNKNOWN;
}
const fn = this.pathFunction(node.callee, scopes);
if (fn === null) return UNKNOWN;
const args = node.arguments.map((arg) => this.evaluate(arg, scopes));
switch (fn) {
case 'cwd':
return file(this.context.packageDir);
case 'join':
return this.combine(args, 'join');
case 'resolve':
return this.combine(args, 'resolve');
case 'normalize':
return args[0]?.kind === 'text'
? text(path.normalize(args[0].text))
: args[0]?.kind === 'file' && !args[0].url
? { ...args[0], abs: path.normalize(args[0].abs) }
: UNKNOWN;
case 'dirname': {
const arg = args[0];
if (arg?.kind === 'text') return text(path.dirname(arg.text));
if (arg?.kind !== 'file') return UNKNOWN;
return arg.exact ? { ...arg, abs: path.dirname(arg.abs) } : arg;
}
case 'fileURLToPath':
return args[0]?.kind === 'file' && args[0].url ? { ...args[0], url: false } : UNKNOWN;
case 'pathToFileURL':
return args[0]?.kind === 'file' && !args[0].url ? { ...args[0], url: true } : UNKNOWN;
default:
return UNKNOWN;
}
}
private isUrlConstructor(callee: Node, scopes: readonly Node[]): boolean {
if (callee.type !== 'Identifier') return false;
if (callee.name === 'URL' && this.lookup('URL', scopes) === 'global') return true;
const target = this.refersTo(callee.name, scopes);
return target?.module === 'url' && target.imported === 'URL';
}
private evaluateNew(node: NewExpression, scopes: readonly Node[]): Value {
if (!this.isUrlConstructor(node.callee, scopes) || node.arguments.length !== 2) return UNKNOWN;
const spec = this.evaluate(node.arguments[0], scopes);
const base = this.evaluate(node.arguments[1], scopes);
if (base.kind !== 'file' || !base.url) return UNKNOWN;
if (!base.exact) return base;
if (spec.kind === 'unknown') return { ...base, abs: path.dirname(base.abs), exact: false };
if (spec.kind !== 'text' || /^[a-z][a-z0-9+.-]*:/i.test(spec.text)) return UNKNOWN;
return file(path.resolve(path.dirname(base.abs), spec.text), true);
}
/** `path.join` / `path.resolve` over evaluated arguments. */
private combine(parts: readonly Value[], mode: 'join' | 'resolve'): Value {
let acc: Value | undefined;
for (const part of parts) {
if (acc?.kind === 'file' && !acc.exact) return acc;
if (part.kind === 'unknown') {
return acc?.kind === 'file' ? { ...acc, exact: false } : UNKNOWN;
}
if (part.kind === 'file') {
if (part.url || (acc !== undefined && mode === 'join')) return UNKNOWN;
acc = part;
} else if (acc === undefined || (mode === 'resolve' && path.isAbsolute(part.text))) {
acc = part;
} else if (acc.kind === 'file') {
acc = { ...acc, abs: path.join(acc.abs, part.text) };
} else if (acc.kind === 'text') {
acc = text(path.join(acc.text, part.text));
}
}
if (acc === undefined) return mode === 'resolve' ? file(this.context.packageDir) : text('.');
if (mode === 'resolve' && acc.kind === 'text' && !path.isAbsolute(acc.text)) {
return file(path.resolve(this.context.packageDir, acc.text));
}
return acc;
}
/** String concatenation (templates and `+`). */
private concat(parts: readonly Value[]): Value {
let acc: Value = text('');
for (const part of parts) {
if (acc.kind === 'unknown' || (acc.kind === 'file' && !acc.exact)) return acc;
if (part.kind === 'unknown') {
if (acc.kind !== 'file') return UNKNOWN;
const prefix = /[\\/]$/.test(acc.abs) ? acc.abs : path.dirname(acc.abs);
return { ...acc, abs: path.normalize(prefix), exact: false };
}
if (part.kind === 'file') {
if (acc.kind !== 'text' || acc.text !== '') return UNKNOWN;
acc = part;
} else {
acc =
acc.kind === 'file' ? { ...acc, abs: acc.abs + part.text } : text(acc.text + part.text);
}
}
return acc.kind === 'file' && acc.exact ? { ...acc, abs: path.normalize(acc.abs) } : acc;
}
// Pass 2: edges, reads and test API.
private snippet(node: Node): string {
const raw = this.source.slice(node.start ?? 0, node.end ?? 0).replace(/\s+/g, ' ');
return raw.length > 100 ? `${raw.slice(0, 97)}...` : raw;
}
private edge(specifier: string, line: number, names: readonly string[] | null): void {
this.facts.edges.push({
target: { kind: 'specifier', specifier, fromDir: path.dirname(this.file) },
line,
names,
});
}
/** A load whose specifier is an expression; `base` is null when it is not statically known. */
private loadEdge(
arg: Node | undefined,
base: string | null,
node: Node,
names: readonly string[] | null,
scopes: readonly Node[],
): void {
const line = lineOf(node);
const value = arg ? this.evaluate(arg, scopes) : UNKNOWN;
if (value.kind === 'text' && (base !== null || !value.text.startsWith('.'))) {
this.facts.edges.push({
target: {
kind: 'specifier',
specifier: value.text,
fromDir: path.dirname(base ?? this.file),
},
line,
names,
});
} else if (value.kind === 'file' && value.exact) {
this.facts.edges.push({ target: { kind: 'file', abs: value.abs }, line, names });
} else {
this.facts.findings.push({
reason: 'unresolvable dynamic import',
line,
detail: this.snippet(arg ?? node),
});
}
if (arg) this.skipped.add(arg);
}
/** Names a `require()`/`import()` result is destructured into, or null for the whole module. */
private destructuredNames(node: Node, ancestors: readonly Node[]): readonly string[] | null {
let child = node;
let index = ancestors.length - 1;
while (
index >= 0 &&
(ancestors[index].type === 'AwaitExpression' || TS_WRAPPERS.has(ancestors[index].type))
) {
child = ancestors[index];
index -= 1;
}
const parent = ancestors[index];
if (parent?.type === 'MemberExpression' && parent.object === child) {
const name = propertyName(parent);
return name === null ? null : [name];
}
if (parent?.type !== 'VariableDeclarator' || parent.init !== child) return null;
if (parent.id.type !== 'ObjectPattern') return null;
const names: string[] = [];
for (const property of parent.id.properties) {
const name = property.type === 'ObjectProperty' ? keyName(property.key) : null;
if (name === null) return null;
names.push(name);
}
return names;
}
private importDeclaration(node: ImportDeclaration): void {
if (node.importKind === 'type') return;
if (node.specifiers.length === 0) {
this.edge(node.source.value, lineOf(node), []);
return;
}
const used = node.specifiers.filter(
(specifier) =>
!(specifier.type === 'ImportSpecifier' && specifier.importKind === 'type') &&
(this.references.get(specifier.local.name) ?? 0) > 0,
);
if (used.length === 0) return;
const names: string[] = [];
for (const specifier of used) {
if (specifier.type !== 'ImportSpecifier') {
this.edge(node.source.value, lineOf(node), null);
return;
}
names.push(keyName(specifier.imported) ?? '*');
}
this.edge(node.source.value, lineOf(node), names);
}
private reexport(node: ExportNamedDeclaration): void {
if (!node.source || node.exportKind === 'type') return;
const names: string[] = [];
for (const specifier of node.specifiers) {
if (specifier.type === 'ExportSpecifier') {
if (specifier.exportKind !== 'type') names.push(keyName(specifier.local) ?? '*');
} else {
this.edge(node.source.value, lineOf(node), null);
return;
}
}
if (names.length > 0) this.edge(node.source.value, lineOf(node), names);
}
/** Base file of a `createRequire(...)` call, or null when it is not static. */
private requireBase(call: CallExpression, scopes: readonly Node[]): string | null {
const value = this.evaluate(call.arguments[0], scopes);
return value.kind === 'file' && value.exact ? value.abs : null;
}
/** Load semantics of a call: the base its specifier resolves against, or null for none. */
private loadCall(node: CallExpression, scopes: readonly Node[]): { base: string | null } | null {
const callee = node.callee;
if (callee.type === 'Identifier') {
const binding = this.lookup(callee.name, scopes);
if (binding === 'global') return callee.name === 'require' ? { base: this.file } : null;
const init = typeof binding === 'string' || binding.kind !== 'const' ? null : binding;
const call = init ? unwrap(init.init) : null;
return init && isCreateRequireCall(call)
? { base: this.requireBase(call, init.scopes) }
: null;
}
if (isCreateRequireCall(callee)) return { base: this.requireBase(callee, scopes) };
if (
callee.type !== 'MemberExpression' ||
callee.object.type !== 'Identifier' ||
callee.object.name !== 'vi'
) {
return null;
}
switch (propertyName(callee)) {
case 'importActual':
case 'importMock':
return { base: this.file };
case 'mock':
case 'doMock': {
const factory = node.arguments[1];
const loadsOriginal =
!factory ||
!FUNCTION_NODES.has(factory.type) ||
(factory as Node & { params: readonly Node[] }).params.length > 0;
return loadsOriginal ? { base: this.file } : null;
}
default:
return null;
}
}
private isFsCall(callee: Node, scopes: readonly Node[]): boolean {
if (callee.type === 'Identifier') {
const target = this.refersTo(callee.name, scopes);
return target !== null && FS_MODULES.has(target.module) && target.imported !== '*';
}
if (callee.type !== 'MemberExpression') return false;
const object = callee.object;
return (
this.isModuleObject(object, FS_MODULES, scopes) ||
(object.type === 'MemberExpression' &&
propertyName(object) === 'promises' &&
this.isModuleObject(object.object, FS_MODULES, scopes))
);
}
private countTestApi(node: CallExpression): void {
const callee = node.callee;
if (callee.type === 'Identifier') {
const hook = HOOK_NAMES.find((name) => name === callee.name);
if (hook) this.facts.hooks[hook] += 1;
}
if (callee.type === 'CallExpression') this.calleeCalls.add(callee);
if (callee.type === 'MemberExpression') {
const name = propertyName(callee);
const root = calleeRoot(callee.object);
if ((name === 'each' || name === 'for') && root !== null && EACH_ROOTS.has(root)) {
this.facts.eachCalls += 1;
}
}
const root = calleeRoot(callee);
if (root !== null && TEST_ROOTS.has(root) && !this.calleeCalls.has(node)) {
this.facts.testCalls += 1;
}
}
private recordRead(node: Node, abs: string, exact: boolean): void {
const rel = toPosix(path.relative(this.context.packageDir, abs));
let reason: string | null = null;
if (rel === '..' || rel.startsWith('../') || path.isAbsolute(rel)) {
// A prefix above the package may still end inside it.
reason =
!exact && isInside(this.context.packageDir, abs)
? 'unresolvable file path'
: 'reads source outside gitnexus/';
} else if (isWithin(rel, 'src')) {
reason = 'reads source under src/';
} else {
const ignored = DEFAULT_IGNORED_DIRS.find((dir) => isWithin(rel, dir));
if (ignored === 'test/fixtures') reason = 'reads test fixtures';
else if (ignored !== undefined) reason = `reads ignored dir: ${ignored}/`;
else if (!exact && ['src', ...DEFAULT_IGNORED_DIRS].some((dir) => contains(rel, dir))) {
reason = 'unresolvable file path';
}
}
if (reason !== null) {
this.facts.reads.push({
reason,
line: lineOf(node),
detail: `${this.snippet(node)} -> ${this.context.display(abs)}${exact ? '' : '/...'}`,
});
}
}
/** Read rule (a): evaluates an anchored path expression; returns false when it was decided. */
private pathExpression(node: Node, scopes: readonly Node[]): boolean {
const value = this.evaluate(node, scopes);
if (value.kind !== 'file') return value.kind === 'unknown';
this.recordRead(node, value.abs, value.exact);
return false;
}
private isPathExpression(node: Node, scopes: readonly Node[]): boolean {
switch (node.type) {
case 'Identifier':
case 'MemberExpression':
case 'TemplateLiteral':
return true;
case 'BinaryExpression':
return node.operator === '+';
case 'NewExpression':
return this.isUrlConstructor(node.callee, scopes);
case 'CallExpression':
return (
this.pathFunction(node.callee, scopes) !== null ||
(node.callee.type === 'MemberExpression' && propertyName(node.callee) === 'toString')
);
default:
return false;
}
}
private analyse(node: Node, ancestors: readonly Node[], scopes: readonly Node[]): boolean {
if (this.skipped.has(node)) return false;
switch (node.type) {
case 'ImportDeclaration':
this.importDeclaration(node);
return false;
case 'ExportNamedDeclaration':
if (!node.source) return true;
this.reexport(node);
return false;
case 'ExportAllDeclaration':
if (node.exportKind !== 'type') this.edge(node.source.value, lineOf(node), null);
return false;
case 'TSImportEqualsDeclaration':
if (
node.importKind !== 'type' &&
node.moduleReference.type === 'TSExternalModuleReference' &&
(this.references.get(node.id.name) ?? 0) > 0
) {
this.edge(node.moduleReference.expression.value, lineOf(node), null);
}
return false;
case 'ImportExpression':
this.loadEdge(
node.source,
this.file,
node,
this.destructuredNames(node, ancestors),
scopes,
);
return false;
case 'CallExpression': {
this.countTestApi(node);
const load = this.loadCall(node, scopes);
if (load) {
const arg = node.arguments[0];
this.loadEdge(arg, load.base, node, this.destructuredNames(node, ancestors), scopes);
}
if (!this.context.testSide) return true;
const first = node.arguments[0];
if (first && this.isFsCall(node.callee, scopes)) {
const value = this.evaluate(first, scopes);
if (value.kind === 'text' && !path.isAbsolute(value.text) && !value.text.includes(':')) {
this.recordRead(first, path.resolve(this.context.packageDir, value.text), true);
}
}
return this.isPathExpression(node, scopes) ? this.pathExpression(node, scopes) : true;
}
default:
if (this.context.testSide && this.isPathExpression(node, scopes)) {
return this.pathExpression(node, scopes);
}
return true;
}
}
}
// ── Classifier ─────────────────────────────────────────────────────────────
const PARSER_PLUGINS: NonNullable = ['typescript', 'decorators-legacy'];
function parseModule(abs: string, source: string): File {
const ext = path.extname(abs);
return parse(source, {
sourceType: ext === '.cjs' || ext === '.cts' ? 'commonjs' : 'module',
plugins: ext === '.tsx' || ext === '.jsx' ? [...PARSER_PLUGINS, 'jsx'] : PARSER_PLUGINS,
errorRecovery: false,
});
}
const emptyFacts = (finding: Finding): ModuleFacts => ({
edges: [],
findings: [finding],
reads: [],
hooks: { beforeAll: 0, beforeEach: 0, afterAll: 0, afterEach: 0 },
eachCalls: 0,
testCalls: 0,
});
const reject = (reason: string, detail: string): Resolved => ({ kind: 'reject', reason, detail });
/** Native hit of a package: the native package, the dependency chain to it and why. */
interface NativeHit {
pkg: string;
chain: string[];
why: string;
}
/** Classifies test files of one repo checkout; caches parsed modules and resolutions. */
export class Classifier {
readonly packageDir: string;
private readonly sharedDir: string;
private readonly sharedSrcDir: string;
private readonly productionDirs: readonly string[];
private readonly factsCache = new Map();
private readonly resolutions = new Map();
private readonly kinds = new Map();
private readonly directNative = new Map();
private readonly packageNative = new Map();
private readonly displays = new Map();
private sharedExports: ReadonlyMap | undefined;
constructor(readonly repoRoot: string) {
this.packageDir = path.join(repoRoot, 'gitnexus');
this.sharedDir = path.join(repoRoot, SHARED_PACKAGE);
this.sharedSrcDir = path.join(this.sharedDir, 'src');
this.productionDirs = [path.join(this.packageDir, 'src'), this.sharedSrcDir];
}
private display(abs: string): string {
let shown = this.displays.get(abs);
if (shown === undefined) {
shown = isInside(abs, this.repoRoot) ? toPosix(path.relative(this.repoRoot, abs)) : abs;
this.displays.set(abs, shown);
}
return shown;
}
private kind(abs: string): 'file' | 'dir' | null {
let kind = this.kinds.get(abs);
if (kind === undefined) {
const stat = statSync(abs, { throwIfNoEntry: false });
kind = stat?.isFile() ? 'file' : stat?.isDirectory() ? 'dir' : null;
this.kinds.set(abs, kind);
}
return kind;
}
private facts(abs: string): ModuleFacts {
const cached = this.factsCache.get(abs);
if (cached) return cached;
let facts: ModuleFacts;
try {
const source = readFileSync(abs, 'utf8');
facts = new ModuleAnalysis(abs, source, parseModule(abs, source), {
packageDir: this.packageDir,
testSide: !this.productionDirs.some((dir) => isInside(abs, dir)),
display: (target) => this.display(target),
}).facts;
} catch (error) {
const message = errorMessage(error);
facts = emptyFacts({ reason: 'parse error', line: 0, detail: message.split('\n')[0] });
}
this.factsCache.set(abs, facts);
return facts;
}
// Resolution.
private findFile(abs: string): string | null {
if (this.kind(abs) === 'file') return abs;
const ext = path.extname(abs);
for (const tsExt of TS_FOR_JS[ext] ?? []) {
const candidate = abs.slice(0, -ext.length) + tsExt;
if (this.kind(candidate) === 'file') return candidate;
}
for (const appended of APPENDED_EXTENSIONS) {
if (this.kind(abs + appended) === 'file') return abs + appended;
}
if (this.kind(abs) === 'dir') {
for (const appended of APPENDED_EXTENSIONS) {
const index = path.join(abs, `index${appended}`);
if (this.kind(index) === 'file') return index;
}
}
return null;
}
private locationReason(importer: string, target: string): string | null {
if (isInside(importer, this.sharedSrcDir)) {
const allowed =
isInside(target, this.sharedSrcDir) || target === path.join(this.sharedDir, 'package.json');
return allowed ? null : 'imports outside gitnexus/';
}
if (!isInside(target, this.packageDir)) return 'imports outside gitnexus/';
const rel = toPosix(path.relative(this.packageDir, target));
const ignored = DEFAULT_IGNORED_DIRS.find((dir) => isWithin(rel, dir));
return ignored === undefined ? null : `imports from ignored dir: ${ignored}/`;
}
private resolveFile(importer: string, abs: string, shown: string, aliased: boolean): Resolved {
const found = this.findFile(abs);
if (found === null) return reject(`unresolved import: ${shown}`, `imports ${shown}`);
if (found.endsWith('.node')) {
return reject(`native binding: ${this.display(found)}`, `imports ${shown}`);
}
const location = aliased ? null : this.locationReason(importer, found);
if (location !== null) {
return reject(location, `imports ${shown} -> ${this.display(found)}`);
}
return WALKED_EXTENSIONS.has(path.extname(found)) && !found.endsWith('.d.ts')
? { kind: 'module', abs: found }
: { kind: 'leaf', abs: found };
}
/** `exports` subpath of gitnexus-shared to its `src/` file (`./dist/X.js` -> `src/X.ts`). */
private sharedExportMap(): ReadonlyMap {
if (this.sharedExports) return this.sharedExports;
const map = new Map();
try {
const manifest: unknown = JSON.parse(
readFileSync(path.join(this.sharedDir, 'package.json'), 'utf8'),
);
const exportsField =
typeof manifest === 'object' && manifest !== null && 'exports' in manifest
? manifest.exports
: undefined;
if (typeof exportsField === 'object' && exportsField !== null) {
for (const [subpath, target] of Object.entries(exportsField)) {
const resolved: unknown =
typeof target === 'string'
? target
: typeof target === 'object' && target !== null && 'default' in target
? target.default
: undefined;
const match = typeof resolved === 'string' ? /^\.\/dist\/(.+)\.js$/.exec(resolved) : null;
if (match) map.set(subpath, path.join(this.sharedSrcDir, `${match[1]}.ts`));
}
}
} catch {
// A missing or broken manifest leaves the alias unresolved.
}
this.sharedExports = map;
return map;
}
private findPackageDir(fromDir: string, name: string): string | null {
let dir = fromDir;
for (;;) {
const candidate = path.join(dir, 'node_modules', name);
if (this.kind(path.join(candidate, 'package.json')) === 'file') return candidate;
const parent = path.dirname(dir);
if (parent === dir) return null;
dir = parent;
}
}
private readManifest(dir: string): Record {
try {
const data: unknown = JSON.parse(readFileSync(path.join(dir, 'package.json'), 'utf8'));
return typeof data === 'object' && data !== null ? (data as Record) : {};
} catch {
return {};
}
}
/** First `.node` file of a package, outside nested `node_modules`, in sorted order. */
private findNodeBinary(dir: string, relative = ''): string | null {
let entries;
try {
entries = readdirSync(path.join(dir, relative), { withFileTypes: true });
} catch {
return null;
}
const sorted = [...entries].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
for (const entry of sorted) {
const child = relative === '' ? entry.name : `${relative}/${entry.name}`;
if (entry.isFile() && entry.name.endsWith('.node')) return child;
if (entry.isDirectory() && entry.name !== 'node_modules' && !entry.name.startsWith('.')) {
const found = this.findNodeBinary(dir, child);
if (found !== null) return found;
}
}
return null;
}
/** Why a package itself is native, or null. */
private nativeSelf(dir: string, name: string): string | null {
const key = `${dir}\0${name}`;
const cached = this.directNative.get(key);
if (cached !== undefined) return cached;
let why: string | null = null;
if (KNOWN_NATIVE_PACKAGES.some((pattern) => pattern.test(name))) why = 'known native package';
else if (this.readManifest(dir).gypfile === true) why = 'declares gypfile';
else if (this.kind(path.join(dir, 'binding.gyp')) === 'file') why = 'has binding.gyp';
else {
const binary = this.findNodeBinary(dir);
if (binary !== null) why = `ships ${binary}`;
}
this.directNative.set(key, why);
return why;
}
/** Breadth-first over installed runtime dependencies; the first native package found. */
private nativeOf(rootDir: string, rootName: string): NativeHit | null {
const cached = this.packageNative.get(rootDir);
if (cached !== undefined) return cached;
const realOf = (dir: string): string => {
try {
return realpathSync(dir);
} catch {
return dir;
}
};
const queue: { dir: string; name: string; chain: string[] }[] = [
{ dir: rootDir, name: rootName, chain: [rootName] },
];
const seen = new Set([realOf(rootDir)]);
let hit: NativeHit | null = null;
for (let index = 0; index < queue.length && hit === null; index += 1) {
const { dir, name, chain } = queue[index];
const why = this.nativeSelf(dir, name);
if (why !== null) {
hit = { pkg: name, chain, why };
break;
}
const manifest = this.readManifest(dir);
const deps = new Set();
for (const field of ['dependencies', 'optionalDependencies']) {
const value = manifest[field];
if (typeof value === 'object' && value !== null) {
for (const dep of Object.keys(value)) deps.add(dep);
}
}
for (const dep of [...deps].sort()) {
const depDir = this.findPackageDir(dir, dep);
if (depDir === null || seen.has(realOf(depDir))) continue;
seen.add(realOf(depDir));
queue.push({ dir: depDir, name: dep, chain: [...chain, dep] });
}
}
this.packageNative.set(rootDir, hit);
return hit;
}
private resolveSpecifier(importer: string, specifier: string, fromDir: string): Resolved {
if (specifier.startsWith('.') || path.isAbsolute(specifier)) {
if (/[?#]/.test(specifier)) {
return reject(`unsupported import specifier: ${specifier}`, `imports ${specifier}`);
}
return this.resolveFile(importer, path.resolve(fromDir, specifier), specifier, false);
}
if (specifier.startsWith('file:')) {
let abs: string;
try {
abs = fileURLToPath(specifier);
} catch {
return reject(`unresolved import: ${specifier}`, `imports ${specifier}`);
}
return this.resolveFile(importer, abs, specifier, false);
}
if (specifier.startsWith('node:') || BUILTINS.has(specifier)) {
return { kind: 'builtin', name: normaliseModule(specifier) };
}
const name = packageName(specifier);
if (name === null) return reject(`unresolved import: ${specifier}`, `imports ${specifier}`);
if (name === SHARED_PACKAGE) {
const subpath = specifier === name ? '.' : `.${specifier.slice(name.length)}`;
const target = this.sharedExportMap().get(subpath);
return target === undefined
? reject(`unresolved import: ${specifier}`, `imports ${specifier} (not in exports)`)
: this.resolveFile(importer, target, specifier, true);
}
if (isHarnessPackage(name)) return { kind: 'package', name };
if (KNOWN_NATIVE_PACKAGES.some((pattern) => pattern.test(name))) {
return reject(`native package: ${name}`, `imports ${specifier} (known native package)`);
}
if (KNOWN_PROCESS_PACKAGES.some((pattern) => pattern.test(name))) {
return reject(
'spawns processes: child_process',
`imports ${specifier} (the package loads node:child_process when imported)`,
);
}
const dir = this.findPackageDir(fromDir, name);
if (dir === null) {
return reject(`unresolved import: ${specifier}`, `imports ${specifier} (not installed)`);
}
const native = this.nativeOf(dir, name);
return native === null
? { kind: 'package', name }
: reject(
`native package: ${native.pkg}`,
`imports ${specifier} (${native.chain.join(' -> ')}: ${native.why})`,
);
}
private resolve(importer: string, target: EdgeTarget): Resolved {
const zone = isInside(importer, this.sharedSrcDir) ? 'shared' : 'package';
const key =
target.kind === 'file'
? `${zone}\0file\0${target.abs}`
: `${zone}\0${target.fromDir}\0${target.specifier}`;
let resolved = this.resolutions.get(key);
if (resolved === undefined) {
resolved =
target.kind === 'file'
? this.resolveFile(importer, target.abs, this.display(target.abs), false)
: this.resolveSpecifier(importer, target.specifier, target.fromDir);
this.resolutions.set(key, resolved);
}
return resolved;
}
// Closure walk.
/** Classifies one package-relative test file. */
classifyFile(testFile: string): FileVerdict {
const testAbs = path.join(this.packageDir, testFile);
const parents = new Map([[testAbs, null]]);
const queue = [testAbs];
const closure = new Set();
const packages = new Set();
const builtins = new Set();
const evidence = new Map();
const chain = (abs: string): string[] => {
const via: string[] = [];
for (let at: string | null | undefined = abs; at; at = parents.get(at)) {
via.unshift(this.display(at));
}
return via;
};
const record = (module: string, finding: Finding): void => {
if (evidence.has(finding.reason)) return;
evidence.set(finding.reason, {
reason: finding.reason,
module: this.display(module),
line: finding.line,
detail: finding.detail,
via: chain(module),
});
};
if (this.kind(testAbs) !== 'file') {
record(testAbs, { reason: 'parse error', line: 0, detail: 'test file not found' });
queue.length = 0;
}
for (let index = 0; index < queue.length; index += 1) {
const module = queue[index];
closure.add(this.display(module));
const facts = this.facts(module);
for (const finding of facts.findings) record(module, finding);
for (const finding of facts.reads) record(module, finding);
for (const edge of facts.edges) {
const resolved = this.resolve(module, edge.target);
switch (resolved.kind) {
case 'module':
if (!parents.has(resolved.abs)) {
parents.set(resolved.abs, module);
queue.push(resolved.abs);
}
break;
case 'leaf':
closure.add(this.display(resolved.abs));
break;
case 'package':
packages.add(resolved.name);
break;
case 'reject':
record(module, { reason: resolved.reason, line: edge.line, detail: resolved.detail });
break;
case 'builtin':
builtins.add(resolved.name);
if (PROCESS_BUILTINS.has(resolved.name)) {
record(module, {
reason: `spawns processes: ${resolved.name}`,
line: edge.line,
detail: `imports node:${resolved.name}`,
});
}
if (
resolved.name === WORKER_BUILTIN &&
(edge.names === null || edge.names.includes('Worker'))
) {
record(module, {
reason: `spawns workers: ${WORKER_BUILTIN}`,
line: edge.line,
detail: `imports ${edge.names === null ? 'all of' : 'Worker from'} node:${WORKER_BUILTIN}`,
});
}
break;
}
}
}
const sortedEvidence = [...evidence.values()].sort((a, b) =>
a.reason < b.reason ? -1 : a.reason > b.reason ? 1 : 0,
);
const testFacts = this.kind(testAbs) === 'file' ? this.facts(testAbs) : undefined;
return {
file: testFile,
status: sortedEvidence.length === 0 ? 'accepted' : 'rejected',
reasons: sortedEvidence.map((entry) => entry.reason),
evidence: sortedEvidence,
hooks: {
...(testFacts?.hooks ?? { beforeAll: 0, beforeEach: 0, afterAll: 0, afterEach: 0 }),
},
eachCalls: testFacts?.eachCalls ?? 0,
testCalls: testFacts?.testCalls ?? 0,
closure: [...closure].sort(),
packages: [...packages].sort(),
builtins: [...builtins].sort(),
};
}
}
// ── Classification ─────────────────────────────────────────────────────────
/** Every `*.test.ts` file under a package-relative directory, package-relative and sorted. */
export function listTestFiles(packageDir: string, testRoot: string): string[] {
const found: string[] = [];
const visit = (relative: string): void => {
for (const entry of readdirSync(path.join(packageDir, relative), { withFileTypes: true })) {
const child = `${relative}/${entry.name}`;
if (entry.isDirectory() && entry.name !== 'node_modules') visit(child);
else if (entry.isFile() && entry.name.endsWith('.test.ts')) found.push(child);
}
};
visit(testRoot.replace(/\/+$/, ''));
return found.sort();
}
const countBy = (keys: readonly string[]): Record => {
const counts = new Map();
for (const key of keys) counts.set(key, (counts.get(key) ?? 0) + 1);
return Object.fromEntries([...counts.entries()].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
};
const categoryOf = (reason: string): string => {
const index = reason.indexOf(': ');
return index === -1 ? reason : reason.slice(0, index);
};
/** Classifies the test files of a checkout; output order is deterministic (sorted by path). */
export function classify(options: ClassifyOptions): Classification {
const classifier = new Classifier(options.repoRoot);
const testRoot = options.testFiles ? null : (options.testRoot ?? 'test/unit');
const testFiles = options.testFiles
? [...new Set(options.testFiles)].sort()
: listTestFiles(classifier.packageDir, testRoot ?? 'test/unit');
const files = testFiles.map((testFile) => classifier.classifyFile(testFile));
const accepted = files.filter((verdict) => verdict.status === 'accepted');
const rejected = files.filter((verdict) => verdict.status === 'rejected');
return {
schemaVersion: CLASSIFY_SCHEMA_VERSION,
testRoot,
files,
accepted: accepted.map((verdict) => verdict.file),
rejected: rejected.map(({ file: testFile, reasons }) => ({ file: testFile, reasons })),
acceptedWithBeforeAll: accepted
.filter((verdict) => verdict.hooks.beforeAll > 0)
.map((verdict) => verdict.file),
summary: {
total: files.length,
accepted: accepted.length,
rejected: rejected.length,
byReason: countBy(rejected.flatMap((verdict) => verdict.reasons)),
byCategory: countBy(
rejected.flatMap((verdict) => [...new Set(verdict.reasons.map(categoryOf))]),
),
},
};
}
/** Human-readable summary: counts, rejection categories and accepted files with `beforeAll`. */
export function renderSummary(result: Classification): string {
const { summary } = result;
const lines = [
`classify: ${summary.total} test files: ${summary.accepted} accepted, ${summary.rejected} rejected`,
'rejected files per reason category (a file counts once per category):',
...Object.entries(summary.byCategory).map(([category, count]) => ` ${category}: ${count}`),
`accepted files with beforeAll: ${result.acceptedWithBeforeAll.length}`,
];
const byFile = new Map(result.files.map((verdict) => [verdict.file, verdict]));
for (const testFile of result.acceptedWithBeforeAll) {
const verdict = byFile.get(testFile);
lines.push(
` ${testFile} (beforeAll ${verdict?.hooks.beforeAll ?? 0}, test call sites ` +
`${verdict?.testCalls ?? 0}, each ${verdict?.eachCalls ?? 0}, closure ` +
`${verdict?.closure.length ?? 0} files)`,
);
}
return lines.join('\n');
}
/** JSON form for the CLI; drops closure lists unless asked for. */
export function toJson(result: Classification, withClosure: boolean): string {
const files = withClosure
? result.files
: result.files.map(
({ closure: _closure, packages: _packages, builtins: _builtins, ...rest }) => rest,
);
return `${JSON.stringify({ ...result, files }, null, 2)}\n`;
}
// ── CLI ────────────────────────────────────────────────────────────────────
if (isMainModule(import.meta.url)) {
const usage =
'usage: node --import tsx tools/mutation/classify/classify.ts [--root ] ' +
'[--file ]... [--out ] [--closure]';
let values: { root?: string; file?: string[]; out?: string; closure?: boolean };
try {
({ values } = parseArgs({
options: {
root: { type: 'string' },
file: { type: 'string', multiple: true },
out: { type: 'string' },
closure: { type: 'boolean', default: false },
},
strict: true,
}));
} catch (error) {
console.error(`${errorMessage(error)}\n${usage}`);
process.exit(2);
}
const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url));
try {
const result = classify({
repoRoot,
testFiles: values.file && values.file.length > 0 ? values.file : undefined,
testRoot: values.root,
});
const json = toJson(result, values.closure === true);
if (values.out) {
writeFileSync(path.resolve(values.out), json);
console.log(renderSummary(result));
} else {
process.stdout.write(json);
}
} catch (error) {
console.error(errorMessage(error));
process.exitCode = 2;
}
}