test-inventory 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # test-inventory
 
+## 0.3.0
+
+### Minor Changes
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - `--fields` keeps only the named keys of each test, and `id`, as in `--fields fullName,reason`, so a short question gets a short answer. Output written with it leaves keys out, so it no longer matches the JSON Schema. The library exports the same as `pickTestFields()`.
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - Filters keep only the tests a question is about: `--state`, `--tag`, `--grep` (a regular expression on the full name, ignoring case), `--only` and `--without-reason`, as in `--state skip --state fixme` for the tests that don't run. The output then describes only those tests: the describes around them, their diagnostics and a summary counted over them. The library exports the same as `filterInventory()`.
+
+- [#37](https://github.com/Huldoser/test-inventory/pull/37) [`5aeb139`](https://github.com/Huldoser/test-inventory/commit/5aeb13959daaeb0fdf4488765944fe42ef7754bc) - `--format jsonl` writes the inventory as JSON Lines: an `inventory` line, one line per suite, test and diagnostic, and a `summary` line, each marked with a `type` key. Tools that read one record per line, such as `grep` or DuckDB, no longer need the whole document in memory. The `InventoryLine` type describes the lines.
+
+### Patch Changes
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - A fixtures file that builds its test object with a function, written there or imported from another file, as in `export const test = defineDeskTest('equities')`, is followed: MSW's test files import such a `test`. Their tests were missing before, with no diagnostic when the fixtures file didn't import the framework itself. A test object built with a call the scan can't follow now gets an `unresolved-test-import` error that names the call, as in "builds it with withWarmup(), which is not followed". A function that returns what another function returns, as `() => onFeed('NYSE')`, is followed too.
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - A call the runner refuses that is written like a declaration, as `describe.sequential('title', fn)` in Vitest 5, `test('title', fn, { retry: 2 })` from Vitest 4 or `test.only.skip('title', fn)`, is listed as a plain test or describe without the part that fails. Its tests were missing before; now they are `notLoaded`, like every other test in the file.
+
+- [#34](https://github.com/Huldoser/test-inventory/pull/34) [`0f96258`](https://github.com/Huldoser/test-inventory/commit/0f96258e65085fa1b7c667b5fa7219a8b19230df) - States follow the runners' precedence more closely, as checked against Vitest 5.0.4 running generated files. A skip in a test or hook body loses to a fixme, skip or todo set while the file loads, as on a describe around the test, since the body never runs. In Vitest, a test's own options win over its chain, so `test.skip('title', { skip: false }, fn)` is active, but the chain still sets its mode: `test.concurrent('title', { concurrent: false }, fn)` runs in parallel. A describe passes its `skip` option down to the tests and describes inside, where it wins over todo, also when the describe's own `.only` keeps the describe itself from being skipped.
+
 ## 0.2.1
 
 ### Patch Changes

package/README.md

@@ -70,7 +70,9 @@ the first test's record includes:
 ```
 
 The output also has a `summary` with counts, a record for each describe, and `diagnostics` that point at code the
-scan could not read and values it could not work out.
+scan could not read and values it could not work out. Filters such as `--state skip`, `--tag @smoke` and
+`--grep "limit order"` keep only some tests, `--fields fullName,reason` keeps only some keys, and `--format jsonl`
+writes one record per line.
 
 ## Library
 

package/dist/ast.d.ts

@@ -4,6 +4,17 @@ export declare function childNodes(node: Node): Node[];
 /** Strips TypeScript-only wrappers such as `test!`, `test as any` and `<any>test`. */
 export declare function unwrap(node: Expression): Expression;
 export declare function isFunctionNode(node: Node | null | undefined): node is FunctionNode;
+/** A value a function returns, with the nodes inside the function around its `return`, outermost first. */
+export interface ReturnValue {
+    expression: Expression;
+    around: Node[];
+}
+/**
+ * The values a function returns; null when it may return no value, as with `return;` or no `return` at all, and for
+ * an async function or a generator, which returns a promise or an iterator whatever its `return` says. A `return` in a
+ * function inside it is that function's.
+ */
+export declare function returnValues(fn: FunctionNode): ReturnValue[] | null;
 export declare function isStringLiteral(node: Node): node is StringLiteral;
 /** `import.meta.vitest`, which in-source Vitest tests read their functions from. */
 export declare function isImportMetaVitest(expression: Expression): boolean;

package/dist/ast.js

@@ -32,6 +32,36 @@ export function unwrap(node) {
 export function isFunctionNode(node) {
     return node?.type === 'ArrowFunctionExpression' || node?.type === 'FunctionExpression';
 }
+/**
+ * The values a function returns; null when it may return no value, as with `return;` or no `return` at all, and for
+ * an async function or a generator, which returns a promise or an iterator whatever its `return` says. A `return` in a
+ * function inside it is that function's.
+ */
+export function returnValues(fn) {
+    if (fn.async || fn.generator)
+        return null;
+    // Only declarations of overloads have no body.
+    const body = fn.body;
+    if (body.type !== 'BlockStatement')
+        return [{ expression: body, around: [] }];
+    const values = [];
+    // Copied only at a `return`, so that a long function costs no more than its size.
+    const around = [];
+    const visit = (node) => {
+        if (node.type === 'ReturnStatement') {
+            values.push(node.argument ? { expression: node.argument, around: [...around] } : null);
+            return;
+        }
+        if (node.type === 'FunctionDeclaration' || isFunctionNode(node))
+            return;
+        around.push(node);
+        for (const child of childNodes(node))
+            visit(child);
+        around.pop();
+    };
+    visit(body);
+    return values.length > 0 && !values.includes(null) ? values : null;
+}
 export function isStringLiteral(node) {
     return node.type === 'Literal' && typeof node.value === 'string';
 }

package/dist/cli.d.ts

@@ -4,6 +4,6 @@ export interface Io {
     stderr: Writable;
     cwd: string;
 }
-export declare const HELP = "Usage: test-inventory <glob...> --framework <playwright|vitest> [options]\n\nLists the tests in the matching files as JSON, read from the source code without running them.\n\nOptions:\n  --framework <name>           playwright or vitest (required)\n  --root <dir>                 project root; paths in the output are relative to it (default: current directory)\n  --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)\n  --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project\n  --comments <mode>            comments above tests: all, non-active or none (default: non-active)\n  -o, --output <file>          write to a file instead of standard output\n  --pretty                     indent the JSON\n  -h, --help                   show this help\n  -v, --version                show the version\n\nExit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be\nwritten, or a crash. 1 is reserved for a future release.\n\nExample:\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --output inventory.json\n";
+export declare const HELP = "Usage: test-inventory <glob...> --framework <playwright|vitest> [options]\n\nLists the tests in the matching files as JSON, read from the source code without running them.\n\nOptions:\n  --framework <name>           playwright or vitest (required)\n  --root <dir>                 project root; paths in the output are relative to it (default: current directory)\n  --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)\n  --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project\n  --comments <mode>            comments above tests: all, non-active or none (default: non-active)\n  --state <state>              keep tests in this state, such as skip or fixme; can be repeated\n  --tag <tag>                  keep tests with this tag, such as @smoke; can be repeated\n  --grep <regex>               keep tests whose full name matches, ignoring case\n  --only                       keep tests that use .only, or are inside a describe that does\n  --without-reason             keep tests that don't run and give no reason\n  --fields <keys>              write only these keys of each test, separated by commas; id is always kept\n  --format <format>            json or jsonl, one record per line (default: json)\n  -o, --output <file>          write to a file instead of standard output\n  --pretty                     indent the JSON\n  -h, --help                   show this help\n  -v, --version                show the version\n\nExit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be\nwritten, or a crash. 1 is reserved for a future release.\n\nExamples:\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --output inventory.json\n  test-inventory \"tests/**/*.spec.ts\" --framework playwright --state skip --fields fullName,reason\n";
 /** Runs the command line with the given arguments and streams. Resolves to the exit code. */
 export declare function run(argv: string[], io: Io): Promise<number>;

package/dist/cli.js

@@ -3,7 +3,8 @@ import { once } from 'node:events';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { readFailure } from "./files.js";
-import { writeInventory } from "./json.js";
+import { checkFields, filterInventory, matcher, pickTestFields } from "./filter.js";
+import { writeInventory, writeInventoryLines } from "./json.js";
 import { OptionsError } from "./options.js";
 import { scan } from "./scan.js";
 import { toolVersion } from "./version.js";
@@ -17,6 +18,13 @@ Options:
   --ignore <glob>              leave out matching files; can be repeated (node_modules is always left out)
   --framework-version <x.y.z>  apply the rules of this framework version instead of the one in the project
   --comments <mode>            comments above tests: all, non-active or none (default: non-active)
+  --state <state>              keep tests in this state, such as skip or fixme; can be repeated
+  --tag <tag>                  keep tests with this tag, such as @smoke; can be repeated
+  --grep <regex>               keep tests whose full name matches, ignoring case
+  --only                       keep tests that use .only, or are inside a describe that does
+  --without-reason             keep tests that don't run and give no reason
+  --fields <keys>              write only these keys of each test, separated by commas; id is always kept
+  --format <format>            json or jsonl, one record per line (default: json)
   -o, --output <file>          write to a file instead of standard output
   --pretty                     indent the JSON
   -h, --help                   show this help
@@ -25,18 +33,24 @@ Options:
 Exit codes: 0 when the scan finishes, even with diagnostics; 2 for invalid arguments, an output that cannot be
 written, or a crash. 1 is reserved for a future release.
 
-Example:
+Examples:
   test-inventory "tests/**/*.spec.ts" --framework playwright --output inventory.json
+  test-inventory "tests/**/*.spec.ts" --framework playwright --state skip --fields fullName,reason
 `;
-/** CLI names for the option names in `scan()`'s errors. */
+/** CLI names for the option names in the library's errors. */
 const FLAGS = {
-    patterns: 'the glob patterns',
-    framework: '--framework',
-    root: '--root',
-    ignore: '--ignore',
-    frameworkVersion: '--framework-version',
-    comments: '--comments',
+    'options.patterns': 'the glob patterns',
+    'options.framework': '--framework',
+    'options.root': '--root',
+    'options.ignore': '--ignore',
+    'options.frameworkVersion': '--framework-version',
+    'options.comments': '--comments',
+    'filter.states': '--state',
+    'filter.tags': '--tag',
+    'filter.grep': '--grep',
+    fields: '--fields',
 };
+const FORMATS = ['json', 'jsonl'];
 async function writeTo(stream, chunk) {
     if (stream.errored)
         throw stream.errored;
@@ -89,6 +103,13 @@ export async function run(argv, io) {
                 ignore: { type: 'string', multiple: true },
                 'framework-version': { type: 'string' },
                 comments: { type: 'string' },
+                state: { type: 'string', multiple: true },
+                tag: { type: 'string', multiple: true },
+                grep: { type: 'string' },
+                only: { type: 'boolean' },
+                'without-reason': { type: 'boolean' },
+                fields: { type: 'string' },
+                format: { type: 'string' },
                 output: { type: 'string', short: 'o' },
                 pretty: { type: 'boolean' },
                 help: { type: 'boolean', short: 'h' },
@@ -112,8 +133,26 @@ export async function run(argv, io) {
         return fail('give at least one glob pattern for the test files.');
     if (values.framework === undefined)
         return fail('--framework is required: playwright or vitest.');
+    const format = values.format ?? 'json';
+    if (!FORMATS.includes(format))
+        return fail('--format must be json or jsonl.');
+    if (format === 'jsonl' && values.pretty)
+        return fail('--pretty indents JSON, so it does not go with --format jsonl.');
+    const filter = {
+        states: values.state,
+        tags: values.tag,
+        grep: values.grep,
+        only: values.only,
+        withoutReason: values['without-reason'],
+    };
+    const fields = values.fields?.split(',').map((field) => field.trim());
     let inventory;
+    let result;
     try {
+        // Checked before the scan, so a mistyped state or key doesn't wait for every file to be read.
+        matcher(filter);
+        if (fields !== undefined)
+            checkFields(fields);
         inventory = await scan({
             patterns: positionals,
             framework: values.framework,
@@ -122,10 +161,12 @@ export async function run(argv, io) {
             frameworkVersion: values['framework-version'],
             comments: values.comments,
         });
+        const filtered = filterInventory(inventory, filter);
+        result = fields === undefined ? filtered : pickTestFields(filtered, fields);
     }
     catch (error) {
         if (error instanceof OptionsError) {
-            return fail(error.message.replace(/^options\.(\w+)/, (_, name) => FLAGS[name]));
+            return fail(error.message.replace(/^[\w.]+/, (name) => FLAGS[name]));
         }
         io.stderr.write(`test-inventory: unexpected error: ${error instanceof Error ? String(error.stack) : String(error)}\n`);
         return FAILED;
@@ -139,8 +180,14 @@ export async function run(argv, io) {
     io.stdout.on('error', quiet);
     try {
         await writeOutput(io, values.output, async (output) => {
-            await writeInventory(inventory, values.pretty === true, (chunk) => writeTo(output, chunk));
-            await writeTo(output, '\n');
+            const write = (chunk) => writeTo(output, chunk);
+            if (format === 'jsonl') {
+                await writeInventoryLines(result, write);
+            }
+            else {
+                await writeInventory(result, values.pretty === true, write);
+                await write('\n');
+            }
         });
     }
     catch (error) {

package/dist/extract.js

@@ -1,4 +1,4 @@
-import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, unwrap } from "./ast.js";
+import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, returnValues, unwrap, } from "./ast.js";
 import { exportName } from "./frameworks/bindings.js";
 import { problem } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
@@ -294,6 +294,7 @@ class Walker {
             testContext: context.testContext,
             inTest: context.test !== null,
             inBody: context.test !== null || context.hookScope !== null,
+            passedDown: context.scope.suite?.declaration.passesDown ?? null,
             returnsOf: (name, scopes) => this.returnsOf(name, scopes),
         });
         if (!api)
@@ -323,6 +324,7 @@ class Walker {
                     reason: api.reason,
                     hasDynamicReason: api.hasDynamicReason,
                     line: this.lineOf(call),
+                    afterLoad: context.test !== null || context.hookScope !== null,
                 };
                 if (context.helper)
                     this.effectsOf(context.helper).push({ kind: 'state', setting, call });
@@ -360,7 +362,7 @@ class Walker {
             case 'invalid': {
                 const afterLoad = context.test !== null || context.hookScope !== null || context.helper !== null;
                 this.report(afterLoad ? { ...api.problem, afterLoad } : api.problem);
-                return true;
+                return api.declaration ? this.handle(call, api.declaration, context) : true;
             }
             case 'other':
                 return false;
@@ -430,33 +432,40 @@ class Walker {
         return null;
     }
     /**
-     * What a function declared in the file being walked, or imported from a local module, returns; null otherwise. Each
-     * declaration is looked up once, however many calls use it.
+     * What a function declared in a file, the one being walked unless said otherwise, or imported from a local module,
+     * returns; null otherwise. Each declaration is looked up once, however many calls use it.
      */
-    returnsOf(name, scopes) {
-        const declaration = this.frame.values.declarationOf(name, scopes);
+    returnsOf(name, scopes, frame = this.frame) {
+        const declaration = frame.values.declarationOf(name, scopes);
         if (declaration === null)
             return null;
         if (!this.returns.has(declaration)) {
-            const local = this.functionNamed(name, scopes);
-            const callee = local ? { fn: local, frame: this.frame } : this.importedFunction(name, scopes);
+            const local = this.functionIn(frame, name, scopes);
+            const callee = local ? { fn: local, frame } : this.importedFunction(name, scopes, frame);
             this.returns.set(declaration, callee && this.returnsIn(callee));
         }
         return this.returns.get(declaration) ?? null;
     }
     returnsIn({ fn, frame }) {
-        // An async function returns a promise, and a generator an iterator, whatever their `return` says.
-        const values = fn.async || fn.generator ? null : returnValues(fn, [...this.scopeChain(fn, frame), fn]);
-        return { adapter: frame.adapter, values };
+        const scopes = [...this.scopeChain(fn, frame), fn];
+        const values = returnValues(fn)?.map(({ expression, around }) => ({
+            expression,
+            scopes: [...scopes, ...around.filter(isScopeNode)],
+        }));
+        return {
+            adapter: frame.adapter,
+            values: values ?? null,
+            returnsOf: (name, at) => this.returnsOf(name, at, frame),
+        };
     }
     /** The function a name imported from a local module stands for, in the file that writes it; null otherwise. */
-    importedFunction(name, scopes) {
-        const declaration = this.frame.values.declarationOf(name, scopes);
-        const source = this.frame.values.importSource(name, scopes);
+    importedFunction(name, scopes, from = this.frame) {
+        const declaration = from.values.declarationOf(name, scopes);
+        const source = from.values.importSource(name, scopes);
         if (source === null)
             return null;
         const imported = declaration?.type === 'ImportSpecifier' ? exportName(declaration.imported) : 'default';
-        const frame = this.openFrom(this.frame, source);
+        const frame = this.openFrom(from, source);
         return frame ? this.exportedFunction(frame, imported, new Set(), 0) : null;
     }
     /** A module a file imports, read as a frame once; null when it can't be read or parsed. */
@@ -680,7 +689,8 @@ class Walker {
                 if (effect.kind === 'configure')
                     return [effect];
                 const condition = joinConditions([...guards, ...(effect.setting.condition ? [effect.setting.condition] : [])]);
-                return [{ ...effect, setting: { ...effect.setting, condition } }];
+                // Helpers are expanded here only for calls from tests and hooks.
+                return [{ ...effect, setting: { ...effect.setting, condition, afterLoad: true } }];
             });
         };
         for (const call of this.helperCalls) {
@@ -843,31 +853,6 @@ class Walker {
         return lines;
     }
 }
-/**
- * The values a function returns, each with the scopes around it, outermost first; null when it may return no value, as
- * with `return;` or no `return` at all. A `return` in a function inside it is that function's.
- */
-function returnValues(fn, scopes) {
-    // Only declarations of overloads have no body.
-    const body = fn.body;
-    if (body.type !== 'BlockStatement')
-        return [{ expression: body, scopes }];
-    const values = [];
-    const visit = (node, around) => {
-        if (node.type === 'ReturnStatement') {
-            values.push(node.argument ? { expression: node.argument, scopes: around } : null);
-            return;
-        }
-        if (node.type === 'FunctionDeclaration' || isFunctionNode(node))
-            return;
-        const inner = isScopeNode(node) ? [...around, node] : around;
-        for (const child of childNodes(node))
-            visit(child, inner);
-    };
-    visit(body, scopes);
-    const always = values.every((value) => value !== null);
-    return always && values.length > 0 ? values : null;
-}
 /** Walks the scanned file; `openModule` reads the modules of imported helpers that the file calls. */
 export function extract(main, openModule) {
     return new Walker(main, openModule).run();

package/dist/filter.d.ts

@@ -0,0 +1,37 @@
+import type { Inventory, TestRecord, TestState } from './types.ts';
+/** @inline */
+export interface InventoryFilter {
+    /** Keeps tests in one of these states. */
+    states?: TestState[];
+    /** Keeps tests with one of these tags, as the output writes them. */
+    tags?: string[];
+    /** Keeps tests whose `fullName` matches this regular expression, ignoring case, as Playwright's `--grep` does. */
+    grep?: string;
+    /** Keeps tests that use `.only`, or are inside a describe that does. */
+    only?: boolean;
+    /** Keeps tests that don't run and give no reason. Tests in a file the runner refuses are left out. */
+    withoutReason?: boolean;
+}
+/** An inventory whose test records have only `id` and the keys picked with `pickTestFields()`. */
+export type PickedInventory<K extends keyof TestRecord> = Omit<Inventory, 'tests'> & {
+    tests: Pick<TestRecord, 'id' | K>[];
+};
+/** Checks a filter and returns whether a test passes it. */
+export declare function matcher(filter: InventoryFilter): (test: TestRecord) => boolean;
+/**
+ * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
+ * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * `summary.fileCount` stays the number of files scanned.
+ *
+ * Throws a `TypeError` for an invalid filter.
+ */
+export declare function filterInventory(inventory: Inventory, filter: InventoryFilter): Inventory;
+/** Checks the keys to pick and returns them after `id`, each once. */
+export declare function checkFields(fields: unknown): (keyof TestRecord)[];
+/**
+ * Leaves only `id` and the given keys on each test record, in that order, to make the output smaller. Suites,
+ * diagnostics and the summary are unchanged. The result no longer matches the JSON Schema, which requires every key.
+ *
+ * Throws a `TypeError` for a key that test records don't have.
+ */
+export declare function pickTestFields<K extends keyof TestRecord>(inventory: Inventory, fields: readonly K[]): PickedInventory<K>;

package/dist/filter.js

@@ -0,0 +1,153 @@
+import { checkObject, OptionsError } from "./options.js";
+import { summarize } from "./summary.js";
+const STATES = ['active', 'skip', 'fixme', 'todo', 'expectedToFail', 'notLoaded'];
+const FILTER_KEYS = [
+    'states',
+    'tags',
+    'grep',
+    'only',
+    'withoutReason',
+];
+// Typed as a record of every key, so a key added to TestRecord fails to compile until it is listed here.
+const TEST_KEYS = Object.keys({
+    id: true,
+    bodyHash: true,
+    suiteId: true,
+    suitePath: true,
+    relativeFilePath: true,
+    fileName: true,
+    lineStart: true,
+    lineEnd: true,
+    columnStart: true,
+    columnEnd: true,
+    declaredAt: true,
+    title: true,
+    titleWithoutTags: true,
+    hasDynamicTitle: true,
+    fullName: true,
+    isTypeTest: true,
+    state: true,
+    isActive: true,
+    isSkipped: true,
+    isFixme: true,
+    isTodo: true,
+    isExpectedToFail: true,
+    isNotLoaded: true,
+    isOnly: true,
+    isConditional: true,
+    condition: true,
+    reason: true,
+    hasDynamicReason: true,
+    stateSource: true,
+    stateLine: true,
+    isParallel: true,
+    isSerial: true,
+    tags: true,
+    annotations: true,
+    comments: true,
+    locks: true,
+    meta: true,
+    isParameterized: true,
+    caseCount: true,
+    isInLoop: true,
+    isInCondition: true,
+    isInFunction: true,
+});
+function list(value, option, allowed) {
+    if (value === undefined)
+        return [];
+    const valid = (item) => typeof item === 'string' && item !== '' && (allowed === null || allowed.includes(item));
+    if (Array.isArray(value) && value.every(valid))
+        return value;
+    const bad = Array.isArray(value) ? value.find((item) => !valid(item)) : value;
+    const expected = allowed === null ? 'non-empty strings' : allowed.map((item) => `"${item}"`).join(', ');
+    throw new OptionsError(`${option} can only hold ${expected}; got ${JSON.stringify(bad)}.`);
+}
+function flag(value, option) {
+    if (value === undefined)
+        return false;
+    if (typeof value !== 'boolean')
+        throw new OptionsError(`${option} must be true or false.`);
+    return value;
+}
+function pattern(value) {
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || value === '')
+        throw new OptionsError('filter.grep must be a non-empty string.');
+    try {
+        return new RegExp(value, 'i');
+    }
+    catch (error) {
+        throw new OptionsError(`filter.grep must be a regular expression: ${error.message}.`);
+    }
+}
+/** Checks a filter and returns whether a test passes it. */
+export function matcher(filter) {
+    const checked = checkObject(filter, 'filter');
+    // A misspelled key would return every test, an answer that looks filtered but isn't.
+    const unknown = Object.keys(checked).find((key) => !FILTER_KEYS.includes(key));
+    if (unknown !== undefined) {
+        throw new OptionsError(`filter can only have the keys ${FILTER_KEYS.join(', ')}; got "${unknown}".`);
+    }
+    const states = list(checked.states, 'filter.states', STATES);
+    const tags = list(checked.tags, 'filter.tags', null);
+    const grep = pattern(checked.grep);
+    const only = flag(checked.only, 'filter.only');
+    const withoutReason = flag(checked.withoutReason, 'filter.withoutReason');
+    return (test) => (states.length === 0 || states.includes(test.state)) &&
+        (tags.length === 0 || test.tags.some((tag) => tags.includes(tag))) &&
+        (grep === null || grep.test(test.fullName)) &&
+        (!only || test.isOnly) &&
+        (!withoutReason || (!test.isActive && !test.isNotLoaded && test.reason === null));
+}
+/**
+ * Keeps the tests that pass every condition of the filter; a list keeps a test that has any of its values. The
+ * result describes only those tests: the describes around them, their diagnostics, and a summary counted over them.
+ * `summary.fileCount` stays the number of files scanned.
+ *
+ * Throws a `TypeError` for an invalid filter.
+ */
+export function filterInventory(inventory, filter) {
+    const tests = inventory.tests.filter(matcher(filter));
+    const testIds = new Set(tests.map((test) => test.id));
+    const parents = new Map(inventory.suites.map((suite) => [suite.id, suite.parentId]));
+    const suiteIds = new Set();
+    for (const test of tests) {
+        for (let id = test.suiteId; id !== null && !suiteIds.has(id); id = parents.get(id)) {
+            suiteIds.add(id);
+        }
+    }
+    const suites = inventory.suites.filter((suite) => suiteIds.has(suite.id));
+    const filesWithTests = new Set(inventory.tests.map((test) => test.relativeFilePath));
+    const filesWithMatches = new Set(tests.map((test) => test.relativeFilePath));
+    // A problem that is not about one test stays, unless every test of its file was left out: an error in a file
+    // with no tests, or in package.json, may mean tests are missing from the answer.
+    const diagnostics = inventory.diagnostics.filter((diagnostic) => diagnostic.testId === null
+        ? !filesWithTests.has(diagnostic.relativeFilePath) || filesWithMatches.has(diagnostic.relativeFilePath)
+        : testIds.has(diagnostic.testId));
+    const summary = summarize(inventory.summary.fileCount, suites, tests, diagnostics);
+    return { ...inventory, summary, suites, tests, diagnostics };
+}
+/** Checks the keys to pick and returns them after `id`, each once. */
+export function checkFields(fields) {
+    if (!Array.isArray(fields) || fields.length === 0) {
+        throw new OptionsError('fields must be a non-empty array of test record keys.');
+    }
+    const bad = fields.findIndex((field) => !TEST_KEYS.includes(field));
+    if (bad !== -1) {
+        throw new OptionsError(`fields can only hold keys of a test record, such as "fullName"; got ${JSON.stringify(fields[bad])}.`);
+    }
+    return [...new Set(['id', ...fields])];
+}
+/**
+ * Leaves only `id` and the given keys on each test record, in that order, to make the output smaller. Suites,
+ * diagnostics and the summary are unchanged. The result no longer matches the JSON Schema, which requires every key.
+ *
+ * Throws a `TypeError` for a key that test records don't have.
+ */
+export function pickTestFields(inventory, fields) {
+    const keys = checkFields(fields);
+    const tests = inventory.tests.map((test) => Object.fromEntries(keys.map((key) => [key, test[key]])));
+    return { ...inventory, tests };
+}

package/dist/frameworks/bindings.d.ts

@@ -9,12 +9,43 @@ export interface ModuleImport {
     node: Node;
 }
 export declare function exportName(name: ModuleExportName): string;
+/** What a module is followed for: a test object, or a function that returns one, as in `defineBrokerTest()`. */
+export type Exported = 'test object' | 'function';
 /** Names a module's test objects are known by, used to check what a fixtures file exports. */
 export interface TestObjects {
     isTestObject(expression: Expression): boolean;
     isTestName(name: string): boolean;
-    /** Whether re-exporting `imported` from `source` exports a test object. */
-    reexports(source: string, imported: string): boolean;
+    /** Whether a function the module declares or imports under `name` returns a test object. */
+    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;
+}
+/**
+ * The functions a module declares at its top level, by name, to tell whether one returns a test object: every value it
+ * returns is one, as `return base.extend({...})` is. An imported function is followed to its module. The function a
+ * module exports as its default, named or not, is also known as `default`.
+ */
+export declare class ModuleFunctions {
+    private readonly functions;
+    /** The functions being read, to end a function that returns what it returns itself. */
+    private readonly reading;
+    /** Whether each function returns a test object, read once however many calls and functions lead to it. */
+    private readonly read;
+    /** The values of variables the bindings left unbound, by name, which a call may make test objects. */
+    private readonly values;
+    /** Whether each of those holds a test object; null while that is being worked out, which ends a loop. */
+    private readonly built;
+    private readonly imported;
+    private readonly follow;
+    constructor(program: Program, imported: Map<string, ModuleImport>, follow: FollowImport);
+    /** Keeps the variables the bindings didn't bind without following calls, to be worked out when asked. */
+    keep(declarators: Iterable<VariableDeclarator>): void;
+    /**
+     * Whether a variable holds a test object built by a call, as `const test = defineBrokerTest()`. It is worked out
+     * only when asked, as following the call reads other modules.
+     */
+    holdsTestObject(name: string, isTestObject: (expression: Expression) => boolean): boolean;
+    returnsTestObject(name: string, isTestObject: (expression: Expression) => boolean): boolean;
 }
 export declare function topLevelDeclarators(program: Program): VariableDeclarator[];
 /** All variable declarators in the file, at any depth, such as `const { it } = import.meta.vitest` inside an `if`. */
@@ -25,12 +56,12 @@ export declare function moduleImports(program: Program, isFramework: (source: st
 export declare function requiredModule(expression: Expression): string | null;
 /** Applies `bind` to each declarator until no more names are bound, so declaration order doesn't matter. */
 export declare function bindAll(declarators: VariableDeclarator[], bind: (declarator: VariableDeclarator) => boolean): void;
-/** Whether a module exports `name` as a test object. */
-export declare function exportsTestObject(program: Program, name: string, objects: TestObjects): boolean;
+/** Whether a module exports `name` as a test object, or as a function that returns one. */
+export declare function exportsTestObject(program: Program, name: string, objects: TestObjects, exported?: Exported): boolean;
 /** Whether a module imports, re-exports or requires any of the given sources. */
 export declare function importsFrom(program: Program, matches: (source: string) => boolean): boolean;
 /** Whether a name a module imports from another module is a test object there, which follows that module in turn. */
-export type FollowImport = (source: string, imported: string) => boolean;
+export type FollowImport = (source: string, imported: string, exported?: Exported) => boolean;
 /** How a framework recognizes the modules and test objects of a followed file. */
 export interface Framework {
     name: string;
@@ -46,7 +77,7 @@ export declare function parseModule(module: ModuleSource): ParsedFile;
  * nothing to do with the framework, as when a call only looked like a test. Each module is followed once for a name,
  * however many imports lead to it, as fixtures files that build on several others share their bases.
  */
-export declare function followModule(source: string, name: string, readModule: ModuleReader | null, framework: Framework, path?: readonly string[], followed?: Map<string, Followed>): Followed;
+export declare function followModule(source: string, name: string, readModule: ModuleReader | null, framework: Framework, exported?: Exported, path?: readonly string[], followed?: Map<string, Followed>): Followed;
 interface Followed {
     exported: boolean;
     reason: string | null;