/** * 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; } }