test-inventory 0.6.1 → 0.8.0

package/dist/scan.js

@@ -4,18 +4,19 @@ import path from 'node:path';
 import { glob } from 'tinyglobby';
 import { ConfigDependencies } from "./config-dependencies.js";
 import { ConfigRuns, fileConfig } from "./config-runs.js";
-import { Configs } from "./config.js";
+import { Configs, settingAt } from "./config.js";
 import { DependencyGraph } from "./dependency-hash.js";
+import { ExportedValues } from "./imported-values.js";
 import { fileDiagnostic } from "./diagnostics.js";
 import { findFiles, normalizePattern, readFailure } from "./files.js";
-import { detectFrameworkVersion, OLDEST } from "./framework-version.js";
+import { detectFramework, detectFrameworkVersion, FRAMEWORK_NAMES, OLDEST } from "./framework-version.js";
 import { createInventory } from "./inventory.js";
-import { checkComments, checkFramework, checkObject, checkStrings, checkVersion, invalid, majorMinor, toPosixPath, } from "./options.js";
+import { checkComments, checkFlag, checkFramework, checkObject, checkStrings, checkVersion, invalid, majorMinor, toPosixPath, } from "./options.js";
 import { moduleResolver } from "./resolve.js";
 import { noRecords, scanFile } from "./scan-file.js";
 import { globalsCheck } from "./vitest-config.js";
 function versionDiagnostics(framework, version, source, range) {
-    const name = framework === 'playwright' ? 'Playwright' : 'Vitest';
+    const name = FRAMEWORK_NAMES[framework];
     if (version === null) {
         return [
             fileDiagnostic('unknown-framework-version', source, `The ${name} version could not be read from the project, so the rules of the newest supported version apply.`),
@@ -36,6 +37,17 @@ function versionDiagnostics(framework, version, source, range) {
         fileDiagnostic('approximate-framework-version', source, `Only the range "${range}" was found for ${name}, so the rules of the newest ${major}.x release apply.`),
     ];
 }
+/** Why Jest gives a file that uses its globals none: a project that runs it sets `injectGlobals` to false. */
+function jestGlobals(placement) {
+    const off = placement.projects?.find(({ settings }) => {
+        const setting = settingAt(settings, ['injectGlobals']);
+        return setting?.kind === 'value' && setting.value === false;
+    });
+    if (!off)
+        return null;
+    const config = off.config.record.relativeFilePath;
+    return `The file uses describe, it or test without importing them, but ${config} sets injectGlobals to false, so Jest doesn't define them; import them from '@jest/globals'.`;
+}
 /** For a pattern that names a folder, which matches no file, a pattern that matches the test files in it. */
 function folderHint(root, patterns, framework) {
     const folder = patterns.find((pattern) => {
@@ -99,7 +111,7 @@ function noFiles(root, patterns, framework, placements) {
     if ([...placements.values()].some((placement) => placement.config)) {
         return 'No test files were found from the configs in the root.';
     }
-    const name = framework === 'playwright' ? 'Playwright' : 'Vitest';
+    const name = FRAMEWORK_NAMES[framework];
     return `No patterns were given, and no ${name} config is in the root or a folder below it, so there are no test files to find.`;
 }
 /**
@@ -111,9 +123,9 @@ function noFiles(root, patterns, framework, placements) {
 export async function scan(options) {
     const checked = checkObject(options, 'options');
     const patterns = checked.patterns === undefined ? null : checkStrings(checked.patterns, 'options.patterns', true);
-    const framework = checkFramework(checked.framework, 'options.framework');
     const ignore = checkStrings(checked.ignore, 'options.ignore', false);
     const comments = checkComments(checked.comments, 'options.comments');
+    const expandCases = checkFlag(checked.expandCases, 'options.expandCases');
     const override = checkVersion(checked.frameworkVersion, 'options.frameworkVersion');
     if (checked.root !== undefined && (typeof checked.root !== 'string' || checked.root === '')) {
         throw invalid('options.root', 'a non-empty string');
@@ -121,7 +133,13 @@ export async function scan(options) {
     const root = path.resolve(checked.root ?? process.cwd());
     if (!existsSync(root) || !statSync(root).isDirectory())
         throw invalid('options.root', `a directory, and ${root} is not one`);
-    const detected = override === null ? detectFrameworkVersion(root, framework) : null;
+    const framework = checked.framework === undefined
+        ? detectFramework(root, ignore)
+        : checkFramework(checked.framework, 'options.framework');
+    // Without patterns, the configs choose among all JavaScript and TypeScript files.
+    const found = await findFiles(root, patterns ?? [SCRIPT_FILES], ignore, framework);
+    const scanned = found.files.map((file) => file.relativeFilePath);
+    const detected = override === null ? detectFrameworkVersion(root, framework, scanned) : null;
     const frameworkVersion = override ?? detected?.version ?? null;
     const range = detected?.range ?? null;
     // With only a range, the newest rules of its major apply, as the newest release in it is the likeliest installed.
@@ -130,11 +148,10 @@ export async function scan(options) {
         : majorMinor(frameworkVersion);
     const source = override === null ? (detected?.source ?? 'package.json') : '.';
     const projectDiagnostics = versionDiagnostics(framework, frameworkVersion, source, range);
-    // Without patterns, the configs choose among all JavaScript and TypeScript files.
-    const found = await findFiles(root, patterns ?? [SCRIPT_FILES], ignore, framework);
     projectDiagnostics.push(...found.diagnostics);
     const readerFor = moduleResolver(root);
     const graph = new DependencyGraph();
+    const exports = new ExportedValues();
     const configs = new Configs(root, framework, readerFor, rules);
     const runs = new ConfigRuns(configs, framework, rules, patterns === null);
     const placements = new Map(found.files.map((file) => [file.absolutePath, runs.placementOf(file.absolutePath)]));
@@ -193,11 +210,13 @@ export async function scan(options) {
             framework,
             version: rules,
             comments,
+            expandCases,
             readModule: readerFor(absolutePath),
             root,
             isBenchmarkFile: placement.runs === null ? null : placement.runs === 'benchmark',
             config: fileConfig(placement, framework, rules, absolutePath),
             graph,
+            exports,
             runsWith,
             snapshotFiles: { ...snapshotFiles, moved: runsWith.moved },
         });
@@ -210,7 +229,9 @@ export async function scan(options) {
         }
         results.push({ ...result, file: { ...result.file, config } });
     }
-    const missingGlobals = globalsCheck(root, configs, (file) => placements.get(file));
+    const missingGlobals = framework === 'jest'
+        ? (file) => jestGlobals(placements.get(file))
+        : globalsCheck(root, configs, (file) => placements.get(file));
     let globals = null;
     for (const { absolutePath, relativeFilePath } of globalsFiles) {
         const message = missingGlobals(absolutePath);

package/dist/types.d.ts

@@ -11,7 +11,7 @@ type Position = number;
 /** @pattern ^[0-9a-f]{16}$ */
 type Hash = string;
 /** @inline */
-export type Framework = 'playwright' | 'vitest';
+export type Framework = 'playwright' | 'vitest' | 'jest';
 /**
  * The state the runner applies to a test, after describes and file-level calls are taken into account. `notLoaded`:
  * the runner refuses to load the file, so none of its tests run.
@@ -38,7 +38,7 @@ export type SettingSource = 'test' | 'suite' | 'file' | 'config';
  * @inline
  */
 export type DiagnosticLevel = 'error' | 'warning';
-export type DiagnosticCode = 'unresolved-test-import' | 'parse-error' | 'read-error' | 'framework-mismatch' | 'unresolved-tag' | 'unresolved-annotation' | 'unresolved-cases' | 'test-in-loop' | 'dynamic-title' | 'duplicate-title' | 'duplicate-id' | 'internal-error' | 'invalid-chain' | 'skip-without-body' | 'test-without-body' | 'describe-not-called' | 'async-describe' | 'nested-test' | 'tag-without-at' | 'removed-api' | 'only-in-skipped-describe' | 'config-may-change-state' | 'undefined-tag' | 'symlink-ignored' | 'invalid-import' | 'globals-not-enabled' | 'unknown-framework-version' | 'unsupported-framework-version' | 'local-test-object' | 'state-in-helper' | 'unresolved-option' | 'dynamic-reason' | 'no-files-matched' | 'unsupported-file' | 'approximate-framework-version' | 'test-in-function' | 'empty-title' | 'bench-outside-benchmark-file' | 'config-value-unknown' | 'file-not-run' | 'forbidden-only' | 'dependency-not-followed';
+export type DiagnosticCode = 'unresolved-test-import' | 'parse-error' | 'read-error' | 'framework-mismatch' | 'unresolved-tag' | 'unresolved-annotation' | 'unresolved-cases' | 'cases-not-expanded' | 'test-in-loop' | 'dynamic-title' | 'duplicate-title' | 'duplicate-id' | 'internal-error' | 'invalid-chain' | 'skip-without-body' | 'test-without-body' | 'describe-not-called' | 'async-describe' | 'describe-throws' | 'nested-test' | 'tag-without-at' | 'removed-api' | 'only-in-skipped-describe' | 'config-may-change-state' | 'undefined-tag' | 'symlink-ignored' | 'invalid-import' | 'globals-not-enabled' | 'unknown-framework-version' | 'unsupported-framework-version' | 'local-test-object' | 'state-in-helper' | 'unresolved-option' | 'dynamic-reason' | 'no-files-matched' | 'unsupported-file' | 'approximate-framework-version' | 'test-in-function' | 'empty-title' | 'bench-outside-benchmark-file' | 'config-value-unknown' | 'file-not-run' | 'forbidden-only' | 'dependency-not-followed';
 export type MetaValue = string | number | boolean | null | MetaValue[] | {
     [key: string]: MetaValue;
 };
@@ -222,6 +222,11 @@ export interface SuiteRecord {
     isShuffled: boolean;
     /** Declared with `.each` or `.for`. */
     isParameterized: boolean;
+    /**
+     * With `expandCases`, which case of its table or pass of its loop the describe is, from 0, as Vitest's `%#` counts;
+     * null without `expandCases`, or when the describe isn't one of several.
+     */
+    caseIndex: Count | null;
     tags: string[];
     annotations: Annotation[];
     /** Playwright only. */
@@ -237,7 +242,10 @@ export interface SuiteRecord {
     /** Source text of the `test.slow()` condition; null when unconditional or not slow. */
     slowCondition: string | null;
     retries: Count | null;
-    /** Vitest only: milliseconds between retries, from the `retry` object (4.1). */
+    /**
+     * Milliseconds between retries: Vitest's from the `retry` object (4.1), Jest's from `waitBeforeRetry` of
+     * `jest.retryTimes()` (30.0); null otherwise.
+     */
     retryDelay: Count | null;
     /** Vitest only: source text of the `retry` object's `condition`, a RegExp or a function. */
     retryCondition: string | null;
@@ -334,7 +342,10 @@ export interface TestRecord {
     slowCondition: string | null;
     /** How many times the runner retries the test when it fails; null when the file sets none. */
     retries: Count | null;
-    /** Vitest only: milliseconds between retries, from the `retry` object (4.1). */
+    /**
+     * Milliseconds between retries: Vitest's from the `retry` object (4.1), Jest's from `waitBeforeRetry` of
+     * `jest.retryTimes()` (30.0); null otherwise.
+     */
     retryDelay: Count | null;
     /** Vitest only: source text of the `retry` object's `condition`, a RegExp or a function. */
     retryCondition: string | null;
@@ -381,10 +392,17 @@ export interface TestRecord {
     /** Declared with `.each` or `.for`, or inside a describe declared with them, so the runner repeats it. */
     isParameterized: boolean;
     /**
-     * How many times the runner repeats the test: the cases of its own table times those of each describe table around
-     * it. Null when a table is not written out in the file, or the test is not parameterized.
+     * How many times the runner repeats the test: the cases of its own table times those of each describe table and the
+     * passes of each loop around it. Null when the scan can't work out a table or a loop's values, or the test is neither
+     * parameterized nor in a loop.
      */
     caseCount: Count | null;
+    /**
+     * With `expandCases`, which case of its own table, or pass of the innermost loop around it inside its describe, the
+     * test is, from 0, as Vitest's `%#` counts; null without `expandCases`, or when the test isn't one of several. The
+     * case of a describe table or loop around the describe is the describe's `caseIndex`.
+     */
+    caseIndex: Count | null;
     /** Declared inside a loop, `forEach` or `map`. */
     isInLoop: boolean;
     /** Declared inside `if`, `?:`, `&&`, `switch` or a `catch` block. */

package/dist/values.d.ts

@@ -11,6 +11,8 @@ export type Resolved = {
     ok: false;
     importedFrom: string | null;
 };
+/** What another module exports under a name, `default` included, for an import of the file. */
+export type ImportReader = (source: string, name: string) => Resolved;
 /** Whether a value can be used as a property name. */
 export declare function isKey(value: Value): value is string | number;
 export declare function isScopeNode(node: Node): boolean;
@@ -22,6 +24,11 @@ export declare class Values {
     private readonly pending;
     /** The functions being read at one of their calls, innermost last. */
     private readonly calls;
+    private readonly imports;
+    private readonly assigned;
+    private readonly changed;
+    /** Without `imports`, a value imported from another module is not worked out. */
+    constructor(imports?: ImportReader | null);
     /**
      * Runs `read` with a function's parameters bound to the arguments of one call, worked out where the call is, so that
      * titles and values built from them resolve, as in `test(\`${side} rejects a zero quantity\`)` inside
@@ -29,6 +36,18 @@ export declare class Values {
      * takes the parameter's default value, worked out in `scopes`, the scopes around the function.
      */
     withArguments<T>(fn: FunctionNode, args: readonly Resolved[], scopes: readonly Node[], read: () => T): T;
+    /**
+     * Runs `read` with the names a loop declares bound to one of the values it goes over, as in
+     * `for (const [tier, bps] of Object.entries(FEES))`. `declarator` is the loop's variable declarator.
+     */
+    withLoopValue<T>(declarator: Node, pattern: Node, value: Resolved, body: Node, scopes: readonly Node[], read: () => T): T;
+    private assignedIn;
+    private withBound;
+    /**
+     * Binds the names of a parameter or a loop variable to the parts of `value` they take, as destructuring does. A
+     * missing `value`, after a spread argument, leaves them unknown, unless a default gives them one.
+     */
+    private bind;
     /** `scopes` lists the scope nodes around the expression, outermost first. */
     resolve(node: Expression, scopes: readonly Node[]): Resolved;
     /**
@@ -41,14 +60,43 @@ export declare class Values {
         init: Expression;
         scopes: readonly Node[];
     } | null;
+    /** The name a module exports that a name imported from it stands for, `default` for a default import; null otherwise. */
+    importedName(name: string, scopes: readonly Node[]): string | null;
     /** The module a name is imported from where it is used; null when it isn't an import. */
     importSource(name: string, scopes: readonly Node[]): string | null;
+    /**
+     * Whether a name refers to a parameter or loop variable bound to a value where it is used: an argument of the helper
+     * call being walked, or a value of the case or pass of an expansion.
+     */
+    isBound(name: string, scopes: readonly Node[]): boolean;
     /** Whether a name refers to a function or class declared in the file. */
     isFunction(name: string, scopes: readonly Node[]): boolean;
     private propertyKey;
-    private resolveName;
+    /**
+     * The calls titles are often built with, all of them pure: `Object.keys()`, `Object.values()`, `Object.entries()`,
+     * `JSON.stringify()` with one argument, `String()`, and a string's `toUpperCase()`, `toLowerCase()` and `trim()` and
+     * an array's `join()`.
+     */
+    private call;
+    /** Whether a name refers to a global, as no scope around the use declares it. */
+    private isGlobal;
+    /** `data.name` where `data` is `import * as data`: what the module exports as `name`; null for any other member. */
+    private namespaceMember;
+    private imported;
+    /**
+     * How many items a list has when not all its values are known, as `[NaN, Infinity]`: a list written out, its spreads
+     * included, held in a constant the module doesn't change, or the keys, values or entries of an object written out;
+     * null otherwise. `seen` stops at a constant defined through itself.
+     */
+    lengthOf(node: Expression, scopes: readonly Node[], seen?: Set<string>): number | null;
+    /** How many keys an object written out has, held in a constant the module doesn't change; null otherwise. */
+    private keyCount;
+    /** What a name refers to where it is used; `scopes` lists the scope nodes around the use, outermost first. */
+    resolveName(name: string, scopes: readonly Node[]): Resolved;
     /** A parameter of a function read at one of its calls: the argument given there. */
     private resolveParameter;
+    /** Names the module changes while it loads, as in `WATCHED.push('MSFT')`, whose declared value isn't the one used. */
+    private changedAtLoad;
     private resolveConstant;
     private enumMembers;
     private lookup;