test-inventory 0.7.0 → 0.9.0

package/dist/framework-version.js

@@ -1,9 +1,54 @@
 import { readFileSync } from 'node:fs';
 import path from 'node:path';
 import { globSync } from 'tinyglobby';
-const PACKAGES = { playwright: '@playwright/test', vitest: 'vitest' };
-/** Oldest supported version of each framework. */
-export const OLDEST = { playwright: [1, 42], vitest: [3, 0] };
+import { nodeTestCommands } from "./node-scripts.js";
+import { OptionsError } from "./options.js";
+/** The package of each runner; `node:test` ships with Node.js. */
+const PACKAGES = {
+    playwright: '@playwright/test',
+    vitest: 'vitest',
+    jest: 'jest',
+    mocha: 'mocha',
+    // Karma and Angular projects list only jasmine-core, which the jasmine command depends on.
+    jasmine: 'jasmine-core',
+    cypress: 'cypress',
+    webdriverio: '@wdio/cli',
+};
+/** The packages that give a framework's version, the first found. */
+function versionPackages(framework) {
+    return framework === 'jasmine' ? [PACKAGES.jasmine, 'jasmine'] : [PACKAGES[framework]];
+}
+/**
+ * The packages that show a project runs a framework. For Jasmine, the jasmine command or Karma's adapter: jasmine-core
+ * alone is often left over in projects that moved to Jest, or comes with type packages.
+ */
+function runnerPackages(framework) {
+    return framework === 'jasmine' ? ['jasmine', 'karma-jasmine'] : [PACKAGES[framework]];
+}
+/** Each framework's name in messages. */
+export const FRAMEWORK_NAMES = {
+    playwright: 'Playwright',
+    vitest: 'Vitest',
+    jest: 'Jest',
+    mocha: 'Mocha',
+    jasmine: 'Jasmine',
+    cypress: 'Cypress',
+    webdriverio: 'WebdriverIO',
+    node: 'node:test',
+    bun: 'Bun',
+};
+/** Oldest supported version of each framework, as major, minor and for Bun, whose 1.2.23 changed how it runs tests, patch. */
+export const OLDEST = {
+    playwright: [1, 42],
+    vitest: [3, 0],
+    jest: [29, 0],
+    mocha: [10, 0],
+    jasmine: [4, 0],
+    cypress: [13, 0],
+    webdriverio: [9, 0],
+    node: [22, 0],
+    bun: [1, 2, 23],
+};
 /** A file's text, or null when it is missing or can't be read. */
 function readText(file) {
     try {
@@ -26,7 +71,7 @@ function escape(text) {
     return text.replace(/[.*+?^${}()|[\]\\/]/g, '\\$&');
 }
 /** The root, then each folder above it, as a monorepo package's dependencies may be installed or locked higher up. */
-function folders(root) {
+export function folders(root) {
     const list = [];
     for (let folder = path.resolve(root);; folder = path.dirname(folder)) {
         list.push(folder);
@@ -77,10 +122,16 @@ function declaredVersion(folder, name) {
  * below the root that declares it and holds one of the scanned `files` is read the same way, from its own folder up.
  */
 export function detectFrameworkVersion(root, framework, files) {
+    if (framework === 'node')
+        return nodeVersion(root);
+    if (framework === 'bun')
+        return bunVersion(root);
+    for (const name of versionPackages(framework)) {
+        const found = detectIn(root, folders(root), name);
+        if (found)
+            return found;
+    }
     const name = PACKAGES[framework];
-    const found = detectIn(root, folders(root), name);
-    if (found)
-        return found;
     // In path order, then shallowest first; the sort is stable, so packages as deep stay in path order.
     const nested = globSync('**/package.json', { cwd: root, ignore: ['**/node_modules/**'] })
         .sort()
@@ -108,3 +159,152 @@ function detectIn(root, all, name) {
     }
     return null;
 }
+/**
+ * The Node.js version a project pins, whose `node:test` runs its tests: the first of `.node-version`, `.nvmrc`, Volta's
+ * `node` and the newest version `engines.node` names, in the root, then in each folder above it. A pin without a
+ * minor, as `24`, or an alias, as `lts/*`, is a range or nothing.
+ */
+function nodeVersion(root) {
+    const source = (folder, file) => path.relative(root, path.join(folder, file)).replaceAll('\\', '/');
+    for (const folder of folders(root)) {
+        for (const file of ['.node-version', '.nvmrc']) {
+            const pinned = readText(path.join(folder, file))?.trim() ?? '';
+            const found = /^v?(\d+)(?:\.(\d+)(?:\.(\d+))?)?$/.exec(pinned);
+            if (!found)
+                continue;
+            const [major, minor, patch] = [found[1], found[2], found[3]];
+            return {
+                version: `${major}.${minor ?? 0}.${patch ?? 0}`,
+                source: source(folder, file),
+                range: minor === undefined ? pinned : null,
+            };
+        }
+        const manifest = readJson(path.join(folder, 'package.json'));
+        const volta = manifest?.volta?.node;
+        if (typeof volta === 'string' && /^\d+\.\d+\.\d+$/.test(volta)) {
+            return { version: volta, source: source(folder, 'package.json'), range: null };
+        }
+        // `engines.node` is a floor: the newest version it names is the likeliest to run, and none older than node:test's.
+        const engines = manifest?.engines?.node;
+        const named = typeof engines === 'string' ? [...engines.matchAll(/\d+(?:\.\d+){0,2}/g)].map(versionParts) : [];
+        if (typeof engines === 'string' && named.length > 0) {
+            const newest = named.reduce((a, b) => (compareParts(b, a) > 0 ? b : a));
+            const floor = compareParts(newest, [...OLDEST.node, 0]) < 0 ? [...OLDEST.node, 0] : newest;
+            return { version: floor.join('.'), source: source(folder, 'package.json'), range: engines };
+        }
+    }
+    return null;
+}
+function versionParts(match) {
+    const [major, minor = 0, patch = 0] = match[0].split('.').map(Number);
+    return [major, minor, patch];
+}
+function compareParts(a, b) {
+    return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+/**
+ * The Bun version a project pins: `.bun-version`, which setup-bun reads, or `packageManager` or `engines.bun` in
+ * package.json, in the root, then in each folder above it; else the version of `@types/bun` or `bun-types`, which Bun
+ * publishes with each release, read as other packages are.
+ */
+function bunVersion(root) {
+    const source = (folder, file) => path.relative(root, path.join(folder, file)).replaceAll('\\', '/');
+    for (const folder of folders(root)) {
+        const pinned = readText(path.join(folder, '.bun-version'))?.trim() ?? '';
+        if (/^v?\d+\.\d+\.\d+$/.test(pinned)) {
+            return { version: pinned.replace(/^v/, ''), source: source(folder, '.bun-version'), range: null };
+        }
+        const manifest = readJson(path.join(folder, 'package.json'));
+        const manager = typeof manifest?.packageManager === 'string' ? /^bun@(\d+\.\d+\.\d+)/.exec(manifest.packageManager) : null;
+        if (manager)
+            return { version: manager[1], source: source(folder, 'package.json'), range: null };
+        const engines = manifest?.engines?.bun;
+        const lowest = typeof engines === 'string' ? /\d+\.\d+(\.\d+)?/.exec(engines) : null;
+        if (typeof engines === 'string' && lowest) {
+            const [major, minor, patch = '0'] = lowest[0].split('.');
+            return { version: `${major}.${minor}.${patch}`, source: source(folder, 'package.json'), range: engines };
+        }
+    }
+    for (const name of ['@types/bun', 'bun-types']) {
+        const found = detectIn(root, folders(root), name);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/** Config file names of each runner. A Vite config alone doesn't count, as Vite apps without Vitest have one. */
+const CONFIG_NAMES = {
+    playwright: /^playwright\.config\.[cm]?[jt]s$/,
+    vitest: /^vitest\.config\.[cm]?[jt]s$/,
+    jest: /^jest\.config\.([cm]?[jt]s|json)$/,
+    mocha: /^\.mocharc\.([cm]?js|ya?ml|jsonc?)$/,
+    // Matched against the path, not only the name: Jasmine's config is in spec/support.
+    jasmine: /(^|\/)spec\/support\/jasmine\.(m?js|json)$/,
+    cypress: /^cypress\.config\.[cm]?[jt]s$/,
+    webdriverio: /^wdio\.conf\.[cm]?[jt]s$/,
+    node: /^node\.config\.json$/,
+    bun: /^bunfig\.toml$/,
+};
+/**
+ * Whether a file is a runner's config. A `bunfig.toml` counts only with a `[test]` table, as projects that run another
+ * runner keep one for Bun's installs.
+ */
+function isConfig(root, file, framework) {
+    if (!CONFIG_NAMES[framework].test(framework === 'jasmine' ? file : path.basename(file)))
+        return false;
+    // A file that can't be read gives null, which holds no table.
+    return framework !== 'bun' || /^\s*\[test\]/m.test(String(readText(path.join(root, file))));
+}
+/**
+ * Whether a package.json lists a runner, or for Jest or Mocha has a `jest` or `mocha` key, its config, or for
+ * `node:test` has a script that runs `node --test`.
+ */
+function declares(manifest, framework) {
+    const json = readJson(manifest);
+    const fields = ['devDependencies', 'dependencies', 'peerDependencies', 'optionalDependencies'];
+    if (framework === 'bun') {
+        return Object.values(json?.scripts ?? {}).some((script) => typeof script === 'string' && /(^|[\s;&|(])bun\s+test(?=\s|$)/.test(script));
+    }
+    if (framework === 'node') {
+        return Object.values(json?.scripts ?? {}).some((script) => typeof script === 'string' && nodeTestCommands(script).length > 0);
+    }
+    return (fields.some((field) => runnerPackages(framework).some((name) => json?.[field]?.[name] !== undefined)) ||
+        ((framework === 'jest' || framework === 'mocha') && json?.[framework] !== undefined));
+}
+/**
+ * The runner a project uses, for a scan without `framework`: the one whose package a package.json in the root or a
+ * folder below it, outside `ignore`, lists, or whose config is there. Only when none is found there do the package.json files above the
+ * root count, as a monorepo may declare its runner once at its top. Throws an `OptionsError` when the project uses
+ * none of them or several, naming what it found.
+ */
+export function detectFramework(root, ignore) {
+    const below = globSync([
+        '**/package.json',
+        '**/*.config.*',
+        '**/.mocharc.*',
+        '**/spec/support/jasmine.*',
+        '**/wdio.conf.*',
+        '**/node.config.json',
+        '**/bunfig.toml',
+    ], {
+        cwd: root,
+        ignore: ['**/node_modules/**', '**/.git/**', ...ignore],
+    });
+    const manifests = below.filter((file) => path.basename(file) === 'package.json').map((file) => path.join(root, file));
+    const above = folders(root)
+        .slice(1)
+        .map((folder) => path.join(folder, 'package.json'));
+    const all = ['playwright', 'vitest', 'jest', 'mocha', 'jasmine', 'cypress', 'webdriverio', 'node', 'bun'];
+    let found = all.filter((framework) => below.some((file) => isConfig(root, file, framework)) ||
+        manifests.some((manifest) => declares(manifest, framework)));
+    if (found.length === 0)
+        found = all.filter((framework) => above.some((manifest) => declares(manifest, framework)));
+    if (found.length === 1)
+        return found[0];
+    if (found.length === 0) {
+        throw new OptionsError('options.framework is needed: no package.json in the root, below it or above it lists @playwright/test, vitest, jest, mocha, jasmine, cypress or @wdio/cli or has a script that runs node --test or bun test, and no config of theirs is in the root or below.');
+    }
+    const names = found.map((framework) => FRAMEWORK_NAMES[framework]);
+    const values = found.map((framework) => `"${framework}"`);
+    throw new OptionsError(`options.framework is needed, as the project uses ${names.slice(0, -1).join(', ')} and ${names.at(-1)}: scan it once with each of ${values.join(', ')}.`);
+}

package/dist/frameworks/bindings.d.ts

@@ -19,6 +19,8 @@ export interface TestObjects {
     returnsTestObject(name: string): boolean;
     /** Whether re-exporting `imported` from `source` exports a test object, or a function that returns one. */
     reexports(source: string, imported: string, exported: Exported): boolean;
+    /** What the test object the module exports as `name` stands for, as `it.skip` stands for `it` with `skip`. */
+    exportedStart?(name: string): unknown;
 }
 /**
  * The functions a module declares at its top level, by name, to tell whether one returns a test object: every value it
@@ -54,6 +56,13 @@ export declare function allDeclarators(program: Program): VariableDeclarator[];
 export declare function moduleImports(program: Program, isFramework: (source: string) => boolean): Map<string, ModuleImport>;
 /** The module of `require('module')`, or null for any other expression. */
 export declare function requiredModule(expression: Expression): string | null;
+/**
+ * What a CommonJS module exports under `name`: `exports.name = value`, `module.exports.name = value` or a key of
+ * `module.exports = { ... }`, and for `default`, `module.exports` itself; the last one written wins; null otherwise.
+ */
+export declare function commonJsExport(program: Program, name: string): Expression | null;
+/** The names a CommonJS module exports one by one, as `exports.name = value` and `module.exports.name = value` do. */
+export declare function commonJsNames(program: Program): string[];
 /** What `module.exports = value` assigns, the default export of a CommonJS module; null for any other statement. */
 export declare function moduleExportsValue(statement: Node): Expression | null;
 /** Applies `bind` to each declarator until no more names are bound, so declaration order doesn't matter. */
@@ -103,10 +112,15 @@ export declare function followModule(source: string, name: string, readModule: M
 interface Followed {
     exported: boolean;
     reason: string | null;
+    /** What the exported test object stands for, when the framework's test objects say. */
+    start?: unknown;
+    /** The module writes a function under the name, a helper that registers tests itself, which the walk follows. */
+    isHelper?: boolean;
 }
 /** Follows the import of `name` in a test file, with the diagnostic to report when it isn't a test object. */
 export declare function followImport(name: string, imported: ModuleImport, readModule: ModuleReader | null, file: FileContext, framework: Framework): {
     exported: boolean;
     problem: Problem | null;
+    start: unknown;
 };
 export {};

package/dist/frameworks/bindings.js

@@ -1,4 +1,4 @@
-import { childNodes, isFunctionNode, propertyName, returnValues, unwrap } from "../ast.js";
+import { childNodes, isFunctionNode, propertyKey, propertyName, returnValues, unwrap, } from "../ast.js";
 import { parseFile } from "../parse.js";
 import { snippet } from "../source.js";
 import { problem, text } from "./common.js";
@@ -125,6 +125,18 @@ export function moduleImports(program, isFramework) {
             imports.set(specifier.local.name, { source: statement.source.value, imported, node: specifier });
         }
     }
+    // `const { test } = require('./fixtures')` imports as `import { test } from './fixtures'` does.
+    for (const declarator of topLevelDeclarators(program)) {
+        const source = declarator.init ? requiredModule(declarator.init) : null;
+        if (source === null || !/^\.\.?\//.test(source) || declarator.id.type !== 'ObjectPattern')
+            continue;
+        for (const property of declarator.id.properties) {
+            const key = property.type === 'Property' ? propertyKey(property) : null;
+            if (key !== null && property.type === 'Property' && property.value.type === 'Identifier') {
+                imports.set(property.value.name, { source, imported: key, node: declarator });
+            }
+        }
+    }
     return imports;
 }
 /** The module of `require('module')`, or null for any other expression. */
@@ -135,6 +147,59 @@ export function requiredModule(expression) {
     const argument = node.arguments.at(0);
     return argument?.type === 'Literal' && typeof argument.value === 'string' ? argument.value : null;
 }
+/**
+ * What a CommonJS module exports under `name`: `exports.name = value`, `module.exports.name = value` or a key of
+ * `module.exports = { ... }`, and for `default`, `module.exports` itself; the last one written wins; null otherwise.
+ */
+export function commonJsExport(program, name) {
+    let found = null;
+    for (const statement of program.body) {
+        const whole = moduleExportsValue(statement);
+        if (whole) {
+            const object = unwrap(whole);
+            if (name === 'default')
+                found = whole;
+            else if (object.type === 'ObjectExpression') {
+                for (const property of object.properties) {
+                    if (property.type === 'Property' && propertyKey(property) === name)
+                        found = property.value;
+                }
+            }
+            continue;
+        }
+        if (statement.type !== 'ExpressionStatement')
+            continue;
+        const expression = unwrap(statement.expression);
+        if (expression.type !== 'AssignmentExpression' || expression.left.type !== 'MemberExpression')
+            continue;
+        if (propertyName(expression.left) !== name)
+            continue;
+        const target = unwrap(expression.left.object);
+        const isExports = target.type === 'Identifier' && target.name === 'exports';
+        const isModuleExports = target.type === 'MemberExpression' &&
+            target.object.type === 'Identifier' &&
+            target.object.name === 'module' &&
+            propertyName(target) === 'exports';
+        if (isExports || isModuleExports)
+            found = expression.right;
+    }
+    return found;
+}
+/** The names a CommonJS module exports one by one, as `exports.name = value` and `module.exports.name = value` do. */
+export function commonJsNames(program) {
+    const names = new Set();
+    for (const statement of program.body) {
+        if (statement.type !== 'ExpressionStatement')
+            continue;
+        const expression = unwrap(statement.expression);
+        if (expression.type !== 'AssignmentExpression' || expression.left.type !== 'MemberExpression')
+            continue;
+        const name = propertyName(expression.left);
+        if (name !== null && commonJsExport(program, name) === expression.right)
+            names.add(name);
+    }
+    return [...names];
+}
 /** What `module.exports = value` assigns, the default export of a CommonJS module; null for any other statement. */
 export function moduleExportsValue(statement) {
     if (statement.type !== 'ExpressionStatement')
@@ -187,6 +252,9 @@ export function exportsTestObject(program, name, objects, exported = 'test objec
         case 'specifier':
             return own.source === null ? local(own.local) : objects.reexports(own.source, own.local, exported);
     }
+    const commonJs = exported === 'test object' && name !== 'default' ? commonJsExport(program, name) : null;
+    if (commonJs)
+        return objects.isTestObject(commonJs);
     return program.body.some((statement) => {
         const source = starReexport(statement);
         return source !== null && objects.reexports(source, name, exported);
@@ -382,12 +450,21 @@ function followExports(module, name, framework, exported, within, followed) {
         return { exported: false, reason: 'could not be parsed' };
     const followFrom = (from, imported, kind) => followModule(from, imported, module.readModule, framework, kind, within, followed);
     const objects = framework.testObjects(program, (from, imported, kind = 'test object') => followFrom(from, imported, kind).exported);
-    if (exportsTestObject(program, name, objects, exported))
-        return { exported: true, reason: null };
+    if (exportsTestObject(program, name, objects, exported)) {
+        return { exported: true, reason: null, start: objects.exportedStart?.(name) };
+    }
+    // A function the module writes and exports is a helper that registers tests itself, which the walk follows.
+    if (exported === 'test object' && exportsFunction(program, name)) {
+        return { exported: false, reason: null, isHelper: true };
+    }
     const unrecognized = (kind) => `does not export ${kind === 'function' ? 'a function that returns a test object' : `a ${framework.name} test object`} that could be recognized`;
     const origin = importOrigin(program, name, framework.isSource, exported);
     if (origin) {
-        const end = followFrom(origin.source, origin.imported, origin.exported).reason ?? unrecognized(origin.exported);
+        const followed = followFrom(origin.source, origin.imported, origin.exported);
+        // A helper function re-exported, as `import helper from './a'; export { helper }`, is no broken test object.
+        if (followed.isHelper && origin.how === 're-exports')
+            return followed;
+        const end = followed.reason ?? unrecognized(origin.exported);
         return { exported: false, reason: `${origin.how} it from '${origin.source}', which ${end}` };
     }
     if (importsFrom(program, framework.isSource))
@@ -397,6 +474,22 @@ function followExports(module, name, framework, exported, within, followed) {
     const call = exported === 'test object' ? creatingCall(program, name, source) : null;
     return { exported: false, reason: call ? `builds it with ${call}, which is not followed` : null };
 }
+/** Whether a module writes the function it exports as `name`: declared, written in place, or held in a variable. */
+function exportsFunction(program, name) {
+    const own = ownExport(program, name);
+    if (own?.kind === 'function')
+        return true;
+    if (own?.kind === 'default') {
+        const value = unwrap(own.value);
+        return value.type === 'FunctionDeclaration' || isFunctionNode(value);
+    }
+    const local = own?.kind === 'variable' ? name : own?.kind === 'specifier' && own.source === null ? own.local : null;
+    if (local === null)
+        return false;
+    const declared = program.body.some((statement) => statement.type === 'FunctionDeclaration' && statement.id?.name === local);
+    const declarator = topLevelDeclarators(program).find((item) => item.id.type === 'Identifier' && item.id.name === local);
+    return declared || isFunctionNode(declarator?.init ? unwrap(declarator.init) : null);
+}
 /**
  * The call that creates what the module exports as `name`, a variable or its default export, as `defineBrokerTest()`;
  * null for other values.
@@ -412,9 +505,9 @@ function creatingCall(program, name, source) {
 }
 /** Follows the import of `name` in a test file, with the diagnostic to report when it isn't a test object. */
 export function followImport(name, imported, readModule, file, framework) {
-    const { exported, reason } = followModule(imported.source, imported.imported, readModule, framework);
+    const { exported, reason, start } = followModule(imported.source, imported.imported, readModule, framework);
     const problemFound = reason
         ? problem('unresolved-test-import', imported.node, `'${name}' is imported from '${imported.source}', which ${reason}; tests that use it are missing.`, snippet(text(file, imported.node)))
         : null;
-    return { exported, problem: problemFound };
+    return { exported, problem: problemFound, start };
 }

package/dist/frameworks/bun.d.ts

@@ -0,0 +1,42 @@
+import type { CallExpression } from 'oxc-parser';
+import type { ApiCall, CallContext, ModuleReader } from '../model.ts';
+import type { ParsedFile } from '../parse.ts';
+import type { HookCounts } from '../types.ts';
+import { type FileContext, type Link } from './common.ts';
+import { SuiteAdapter, type Kind } from './test-functions.ts';
+/**
+ * Bun's `bun test`, from 1.2.23, which runs its tests the way 1.3 and 1.4 do. Its functions are globals in test files,
+ * and imports of `bun:test`, `@jest/globals` and `vitest` give them too. A chain holds its modes in any order, one of
+ * each group, and the conditions `if`, `skipIf`, `todoIf`, `failingIf`, `concurrentIf` and `serialIf` as often as
+ * it likes; options go second or third.
+ */
+export declare class BunAdapter extends SuiteAdapter {
+    constructor(parsed: ParsedFile, file: FileContext, readModule: ModuleReader | null);
+    classify(call: CallExpression, context: CallContext): ApiCall | null;
+    protected isAliasLink(_kind: Kind, link: Link): boolean;
+    /** A hook; before Bun 1.3, one given more than its function fails the file. */
+    protected hook(call: CallExpression, name: keyof HookCounts, context: CallContext): ApiCall;
+    private chainCall;
+    /**
+     * Whether Bun takes a chain: one of `skip`, `todo` and `failing`, one `only`, one of `concurrent` and `serial`, and
+     * one table, where a condition that holds counts as its mode, as `if(false)` counts as `skip`; the conditions and
+     * the table called and the modes not; and no `failing` on a describe. A condition the scan can't work out counts as
+     * not holding (checked with Bun 1.2.23, 1.3.14 and 1.4.4).
+     */
+    private isValid;
+    private condition;
+    private declaration;
+    /**
+     * The states of a chain, as Bun ranks them: `skip` over `todo` over `failing`. `if(condition)` skips when the
+     * condition is false; `skipIf`, `todoIf` and `failingIf` set theirs when it is true.
+     */
+    private states;
+    /** `concurrent` runs the test with others at once, and `serial` alone, also as `concurrentIf` and `serialIf` that hold. */
+    private mode;
+    /** A number as the timeout, or an object with `timeout`, `retry` and `repeats`. */
+    private options;
+    /** How many tests a table registers: one per item; null with a warning when the scan can't count them. */
+    private caseCount;
+    /** The cases of a table the scan can work out: an item that is an array is spread into the arguments, another is one. */
+    private tableCases;
+}