test-inventory 0.2.0 → 0.3.0

package/dist/frameworks/vitest.js

@@ -1,7 +1,18 @@
 import { childNodes, isFunctionNode, isImportMetaVitest, propertyKey, propertyName, unwrap, } from "../ast.js";
 import { snippet } from "../source.js";
-import { allDeclarators, bindAll, exportName, followImport, followModule, moduleImports, requiredModule, } from "./bindings.js";
-import { atLeast, findFunction, isTestName, localTestObject, looksLikeDeclaration, mayDeclareTests, mayHoldTestObject, origin, problem, readChain, readCondition, readOptions, readStrings, isTitleLiteral, readReason, namedFunction, unresolvedOption, unresolvedOptions, readTitle, text, } from "./common.js";
+import { allDeclarators, bindAll, exportName, followImport, followModule, moduleImports, ModuleFunctions, requiredModule, } from "./bindings.js";
+import { atLeast, findFunction, isTestName, localTestObject, looksLikeDeclaration, mayDeclareTests, mayHoldTestObject, origin, problem, readChain, readCondition, returnedFunction, returnedTestObject, readOptions, readStrings, isTitleLiteral, readReason, namedFunction, unresolvedOption, unresolvedOptions, readTitle, refused, text, } from "./common.js";
+/** What a test function chosen at run time, as in `isCI ? it.skip : it`, is either way: only the links both have. */
+function shared(a, b) {
+    if (!a || a.kind !== b?.kind)
+        return null;
+    const same = (link, index) => {
+        const other = b.links.at(index);
+        return other?.name === link.name && !link.args && !link.template && !other.args && !other.template;
+    };
+    const differs = a.links.findIndex((link, index) => !same(link, index));
+    return { kind: a.kind, links: differs === -1 ? a.links : a.links.slice(0, differs) };
+}
 // Maps rather than object literals, so names such as `constructor` don't match inherited properties.
 const KINDS = new Map([
     ['test', 'test'],
@@ -26,6 +37,8 @@ const HOOKS = new Map([
     ['afterAll', null],
     ['aroundAll', null],
 ]);
+/** First members of chains that never declare a test, even when Vitest refuses the rest of the chain. */
+const NOT_DECLARING = new Set([...HOOKS.keys(), ...DERIVATIONS]);
 /** First members that show a name imported from a local file is used as Vitest's `test`. */
 const TEST_MEMBERS = new Set([...MODIFIERS.test, ...MODIFIERS.describe, ...TABLES, ...CONDITIONS, ...KINDS.keys()]);
 /** Calls Vitest moves to the top of the file before running it: `vi.mock`, `vi.unmock` and `vi.hoisted`. */
@@ -91,9 +104,12 @@ class VitestBindings {
     /** Names imported from other modules, which may be test objects there. */
     imported;
     follow;
+    /** The module's functions and the variables they may build test objects in; see `ModuleFunctions`. */
+    functions;
     constructor(program, version, follow) {
         this.imported = moduleImports(program, (source) => source === 'vitest' || MISMATCHED_SOURCES.has(source));
         this.follow = follow;
+        this.functions = new ModuleFunctions(program, this.imported, follow);
         for (const statement of program.body) {
             if (statement.type !== 'ImportDeclaration' || statement.importKind === 'type')
                 continue;
@@ -128,30 +144,49 @@ class VitestBindings {
                 this.declarations.add(declarator);
             return bound;
         });
+        this.functions.keep(declarators.filter((declarator) => !this.declarations.has(declarator)));
     }
     isTestName(name) {
-        return this.kinds.has(name) || this.importsTestObject(name);
+        return this.kinds.has(name) || this.importsTestObject(name) || this.holdsTestObject(name);
     }
-    isTestObject(expression) {
+    /**
+     * `followsCalls` is cleared where a call is not followed to what it returns: while the names are bound, so that only
+     * a value asked about is followed, as following reads other modules, and in the scanned file, whose calls the walk
+     * follows in their scopes.
+     */
+    isTestObject(expression, followsCalls = true) {
         const node = unwrap(expression);
-        if (node.type === 'Identifier')
-            return this.kinds.get(node.name) === 'test' || this.importsTestObject(node.name);
+        if (node.type === 'Identifier') {
+            const { name } = node;
+            return (this.kinds.get(name) === 'test' || this.importsTestObject(name) || (followsCalls && this.holdsTestObject(name)));
+        }
         if (node.type === 'MemberExpression') {
             return KINDS.get(propertyName(node) ?? '') === 'test' && this.isNamespace(node.object);
         }
         // `process.env.CI ? vitestTest : skippedTest` is a test object either way.
         if (node.type === 'ConditionalExpression') {
-            return this.isTestObject(node.consequent) || this.isTestObject(node.alternate);
+            return this.isTestObject(node.consequent, followsCalls) || this.isTestObject(node.alternate, followsCalls);
         }
         if (node.type !== 'CallExpression')
             return false;
         const callee = unwrap(node.callee);
+        // `defineBrokerTest()`, a function that returns a test object.
+        if (callee.type === 'Identifier')
+            return followsCalls && this.returnsTestObject(callee.name);
         return (callee.type === 'MemberExpression' &&
             DERIVATIONS.has(propertyName(callee) ?? '') &&
-            this.isTestObject(callee.object));
+            this.isTestObject(callee.object, followsCalls));
+    }
+    returnsTestObject(name) {
+        return this.functions.returnsTestObject(name, (expression) => this.isTestObject(expression));
     }
-    reexports(source, imported) {
-        return source === 'vitest' ? KINDS.has(imported) : this.follow(source, imported);
+    holdsTestObject(name) {
+        return this.functions.holdsTestObject(name, (expression) => this.isTestObject(expression));
+    }
+    reexports(source, imported, exported) {
+        if (source !== 'vitest')
+            return this.follow(source, imported, exported);
+        return exported === 'test object' && KINDS.has(imported);
     }
     /** Whether a name is imported from another module that exports it as a test object, as `base` from './base'. */
     importsTestObject(name) {
@@ -178,7 +213,7 @@ class VitestBindings {
         const { id, init } = declarator;
         if (!init)
             return false;
-        if (id.type === 'Identifier' && this.isTestObject(init)) {
+        if (id.type === 'Identifier' && this.isTestObject(init, false)) {
             this.kinds.set(id.name, 'test');
             return true;
         }
@@ -208,6 +243,7 @@ export class VitestAdapter {
     imports;
     followed = new Map();
     reported = new Set();
+    /** Variables and names of functions read as test objects on trust, each reported once. */
     assumed = new Set();
     aliases = new Map();
     /** Describe callbacks and the name of their first parameter, which Vitest calls with its `test`. */
@@ -219,10 +255,11 @@ export class VitestAdapter {
         // A test object the file builds from an imported one, as in `const it = base.extend({...})`, is followed quietly:
         // a call through the import itself is what reports an import that can't be followed.
         const followed = new Map();
-        this.bindings = new VitestBindings(parsed.program, file.version, (source, imported) => {
-            const key = `${source}\0${imported}`;
-            if (!followed.has(key))
-                followed.set(key, followModule(source, imported, readModule, this.framework()).exported);
+        this.bindings = new VitestBindings(parsed.program, file.version, (source, imported, exported = 'test object') => {
+            const key = `${source}\0${exported}\0${imported}`;
+            if (!followed.has(key)) {
+                followed.set(key, followModule(source, imported, readModule, this.framework(), exported).exported);
+            }
             return followed.get(key) === true;
         });
         this.problems = [...this.bindings.problems];
@@ -247,6 +284,9 @@ export class VitestAdapter {
             this.contextSkip(call, context) ??
             this.chainCall(call, context));
     }
+    testFunction(expression, scopes, returnsOf) {
+        return this.aliasOf(expression, { scopes, inBody: false, returnsOf });
+    }
     /** A call to `bench` imported from Vitest 5, which is undefined there, so the call throws. */
     benchCall(call, context) {
         const base = readChain(call.callee)?.base;
@@ -263,7 +303,7 @@ export class VitestAdapter {
     }
     chainCall(call, context) {
         const chain = readChain(call.callee);
-        const resolved = chain ? this.resolve(chain, call.arguments, context.scopes, context.inBody) : null;
+        const resolved = chain ? this.resolve(chain, call.arguments, context) : null;
         if (!resolved)
             return null;
         const { kind, links } = resolved;
@@ -275,36 +315,31 @@ export class VitestAdapter {
         if (last && (TABLES.has(last.name) || CONDITIONS.has(last.name)) && !last.args && !last.template) {
             return { kind: 'other' };
         }
-        for (const link of links) {
+        const callee = snippet(text(this.file, call.callee));
+        const removed = (link) => link.name === 'sequential' && atLeast(this.file.version, 5, 0);
+        const valid = (link) => {
             const called = link.args !== null || link.template !== null;
-            const valid = MODIFIERS[kind].has(link.name)
-                ? !called
-                : TABLES.has(link.name)
-                    ? called
-                    : CONDITIONS.has(link.name) && link.args !== null;
-            if (!valid) {
-                const callee = snippet(text(this.file, call.callee));
-                return {
-                    kind: 'invalid',
-                    problem: problem('invalid-chain', call, `${callee} is not part of Vitest's API.`, callee),
-                };
-            }
-            if (link.name === 'sequential' && atLeast(this.file.version, 5, 0)) {
-                const callee = snippet(text(this.file, call.callee));
-                return {
-                    kind: 'invalid',
-                    problem: problem('removed-api', call, `sequential was removed in Vitest 5; ${callee}(...) fails.`, callee),
-                };
-            }
-        }
-        return this.declaration(call, kind, links, context);
+            if (MODIFIERS[kind].has(link.name))
+                return !called && !removed(link);
+            return TABLES.has(link.name) ? called : CONDITIONS.has(link.name) && link.args !== null;
+        };
+        const invalid = links.find((link) => !valid(link));
+        if (!invalid)
+            return this.declaration(call, kind, links, context);
+        const refusal = removed(invalid)
+            ? problem('removed-api', call, `sequential was removed in Vitest 5; ${callee}(...) fails.`, callee)
+            : problem('invalid-chain', call, `${callee} is not part of Vitest's API.`, callee);
+        if (NOT_DECLARING.has(links[0].name))
+            return { kind: 'invalid', problem: refusal };
+        // Which of its parts the chain means is not known, so it declares a plain test or describe.
+        return refused(call, refusal, context, () => this.declaration(call, kind, [], context));
     }
     /**
      * The function a chain calls and the links after it, or null when it isn't one of Vitest's. An import that can't be
      * followed is reported only outside test and hook bodies, where a call can declare tests.
      */
-    resolve(chain, args, scopes, inBody) {
-        const start = this.start(chain, args, scopes, inBody);
+    resolve(chain, args, lookup) {
+        const start = this.start(chain, args, lookup);
         if (!start)
             return null;
         let kind = start.kind;
@@ -318,8 +353,13 @@ export class VitestAdapter {
         }
         return { kind, links };
     }
-    start(chain, args, scopes, inBody) {
+    start(chain, args, lookup) {
         const { base, links } = chain;
+        const { scopes, inBody } = lookup;
+        if (base.type === 'CallExpression') {
+            const returned = this.returned(base, links, args, lookup);
+            return returned && { kind: returned.kind, index: 0, modifiers: returned.links };
+        }
         if (base.type !== 'Identifier')
             return null;
         // A name the file doesn't declare is one of Vitest's globals; a local variable or parameter with the same name,
@@ -335,10 +375,10 @@ export class VitestAdapter {
         if (this.suiteParameters.get(declaration) === base.name)
             return { kind: 'test', index: 0 };
         const followed = this.imports.get(base.name)?.node === declaration &&
-            this.looksLikeTest(links, args) &&
+            this.worthFollowing(base.name, links, args) &&
             this.follow(base.name, !inBody && mayDeclareTests(base.name, links));
         if (!followed && !this.bindings.declarations.has(declaration)) {
-            const alias = declaration.type === 'VariableDeclarator' ? this.alias(declaration, scopes, inBody) : null;
+            const alias = declaration.type === 'VariableDeclarator' ? this.alias(declaration, lookup) : null;
             if (alias)
                 return { kind: alias.kind, index: 0, modifiers: alias.links };
             return this.assumeLocal(declaration, base.name, links, args)
@@ -353,37 +393,48 @@ export class VitestAdapter {
         return kind ? { kind, index: 0 } : null;
     }
     /** The function and modifiers a variable holds, as in `const skipOnCi = test.skipIf(isCI)`. */
-    alias(declarator, scopes, inBody) {
+    alias(declarator, lookup) {
         let alias = this.aliases.get(declarator);
         if (alias === undefined) {
             // Set first, so a variable defined through itself ends the lookup.
             this.aliases.set(declarator, null);
-            alias = declarator.init ? this.aliasOf(declarator.init, scopes, inBody) : null;
+            alias = declarator.init ? this.aliasOf(declarator.init, lookup) : null;
             this.aliases.set(declarator, alias);
         }
         return alias;
     }
-    aliasOf(expression, scopes, inBody) {
+    aliasOf(expression, lookup) {
         const node = unwrap(expression);
         if (node.type === 'ConditionalExpression') {
             // `isCI ? describe.concurrent : describe`: only the modifiers both branches have apply.
-            const consequent = this.aliasOf(node.consequent, scopes, inBody);
-            const alternate = this.aliasOf(node.alternate, scopes, inBody);
-            if (!consequent || consequent.kind !== alternate?.kind)
-                return null;
-            const same = (link, index) => {
-                const other = alternate.links.at(index);
-                return other?.name === link.name && !link.args && !link.template && !other.args && !other.template;
-            };
-            const shared = consequent.links.findIndex((link, index) => !same(link, index));
-            return { kind: consequent.kind, links: shared === -1 ? consequent.links : consequent.links.slice(0, shared) };
+            return shared(this.aliasOf(node.consequent, lookup), this.aliasOf(node.alternate, lookup));
         }
         const chain = readChain(node);
-        const resolved = chain ? this.resolve(chain, [], scopes, inBody) : null;
+        const resolved = chain ? this.resolve(chain, [], lookup) : null;
         const allowed = (link) => resolved !== null &&
             (MODIFIERS[resolved.kind].has(link.name) || TABLES.has(link.name) || CONDITIONS.has(link.name));
         return resolved?.links.every(allowed) ? resolved : null;
     }
+    /**
+     * The function a call returns, as `conditionalTest({ min: 22 })` returns `it` or `it.skip`: what all the values the
+     * function returns have in common, as for a variable chosen by a condition. When the function can't be found, a call
+     * named like a test object is read as one on trust, with a warning; see `returnedTestObject`.
+     */
+    returned(call, links, args, lookup) {
+        const callee = unwrap(call.callee);
+        if (callee.type !== 'Identifier')
+            return null;
+        const returns = lookup.returnsOf(callee.name, lookup.scopes);
+        if (returns)
+            return returnedFunction(returns, shared);
+        if (!isTestName(callee.name) || !this.looksLikeTest(links, args))
+            return null;
+        if (!this.assumed.has(callee.name)) {
+            this.assumed.add(callee.name);
+            this.problems.push(returnedTestObject(this.file, call));
+        }
+        return { kind: KINDS.get(callee.name) ?? 'test', links: [] };
+    }
     /** Whether a local variable is read as a test object it could be; see `localTestObject`. */
     assumeLocal(declaration, name, links, args) {
         if (declaration.type !== 'VariableDeclarator' || !mayHoldTestObject(declaration) || !isTestName(name))
@@ -399,6 +450,14 @@ export class VitestAdapter {
     looksLikeTest(links, args) {
         return links.length === 0 ? looksLikeDeclaration(args) : TEST_MEMBERS.has(links[0].name);
     }
+    /**
+     * Whether a call through an imported name is worth following to the module: shaped like a test, or any call with a
+     * title and a body through a name that reads like a test function, as `it.effect('title', fn)` on a test object that
+     * a package extends.
+     */
+    worthFollowing(name, links, args) {
+        return this.looksLikeTest(links, args) || (isTestName(name) && looksLikeDeclaration(args));
+    }
     /** Vitest as followed modules are read, with the rules of the scanned version. */
     framework() {
         const version = this.file.version;
@@ -489,6 +548,7 @@ export class VitestAdapter {
         // (title, fn, timeout), (title, options, fn) or the removed (title, fn, options)
         let options;
         let body;
+        let refusal = null;
         const [second, third] = [args.at(1), args.at(2)];
         if (args.some((arg) => arg.type === 'SpreadElement')) {
             // With spread arguments, as in test(...args), the function and options are unknown.
@@ -501,29 +561,49 @@ export class VitestAdapter {
             body = second;
             if (third !== undefined && this.isOptions(third, undefined, context)) {
                 if (atLeast(this.file.version, 4, 0)) {
-                    return {
-                        kind: 'invalid',
-                        problem: problem('removed-api', third, `${callee}() takes options as its second argument since Vitest 4; with options third the call fails.`, snippet(text(this.file, third))),
-                    };
+                    refusal = problem('removed-api', third, `${callee}() takes options as its second argument since Vitest 4; with options third the call fails.`, snippet(text(this.file, third)));
                 }
                 options = third;
             }
         }
         const fn = isFunctionNode(body) ? body : null;
         const read = this.readDeclarationOptions(options, context, problems);
-        const flags = new Set([
-            ...links.filter((link) => MODIFIERS[kind].has(link.name)).map((link) => link.name),
-            ...read.flags,
-        ]);
-        const conditions = [
-            ...links.filter((link) => CONDITIONS.has(link.name)).map((link) => this.linkCondition(link, context)),
-            ...read.conditions,
-        ];
+        const chain = new Set(links.filter((link) => MODIFIERS[kind].has(link.name)).map((link) => link.name));
+        const flags = new Set(chain);
+        let conditions = links.filter((link) => CONDITIONS.has(link.name)).map((link) => this.linkCondition(link, context));
+        // A test's own options win over its chain, so `test.skip('title', { skip: false }, fn)` runs. The chain wins for a
+        // test's mode, and for everything on a describe.
+        for (const [flag, value] of read.flags) {
+            if (value)
+                flags.add(flag);
+            else if (kind === 'test' && flag !== 'sequential')
+                flags.delete(flag);
+        }
+        if (read.skip && kind === 'test') {
+            flags.delete('skip');
+            conditions = [read.skip];
+        }
+        else if (read.skip) {
+            conditions.push(read.skip);
+        }
+        // Vitest passes a describe's options down to the tests and describes inside, where their own options and `only`
+        // win. A `skip` passed down skips them, and turns todo into skip, as skip goes before todo.
+        const line = this.file.source.line(call.start);
+        const around = context.passedDown;
+        const passed = read.skip ? null : around;
+        const skips = passed?.condition.applies === 'always' && !flags.has('only');
         const table = links.find((link) => TABLES.has(link.name)) ?? null;
         const isTodo = flags.has('todo') || body === undefined;
-        const states = this.states(flags, conditions, isTodo, this.file.source.line(call.start));
-        // `{ concurrent: false }` is how Vitest 5 turns parallel off, in place of `sequential`.
-        const parallel = read.concurrent ?? flags.has('concurrent');
+        const states = this.states(flags, conditions, isTodo && !skips, line);
+        const skipped = () => states.some((setting) => setting.state === 'skip' && !setting.condition);
+        // The skip is set where the describe that passes it down sets it. A skipped describe around already skips what is
+        // inside, as it does when its own `only` beats its skip; a todo describe gets the skip itself.
+        if (skips && !skipped() && (!passed.covered || (kind === 'describe' && isTodo))) {
+            states.push({ state: 'skip', condition: null, reason: null, hasDynamicReason: false, line: passed.line });
+        }
+        // The chain's mode wins over the options'. `{ concurrent: false }` is how Vitest 5 turns parallel off, in place of
+        // `sequential`.
+        const parallel = chain.has('concurrent') || (!chain.has('sequential') && read.concurrent === true);
         const mode = parallel
             ? 'parallel'
             : flags.has('sequential') || read.concurrent === false
@@ -541,18 +621,20 @@ export class VitestAdapter {
             caseCount: table ? this.caseCount(call, table, context, problems) : null,
             problems,
         };
+        let declared;
         if (kind === 'describe') {
             // A table's cases are passed instead.
             const first = table ? null : fn?.params.at(0);
             if (fn && first?.type === 'Identifier')
                 this.suiteParameters.set(fn, first.name);
-            return { kind: 'describe', ...base, isShuffled: flags.has('shuffle') };
+            const own = read.skip ? { condition: read.skip, line } : around;
+            const passesDown = own && { ...own, covered: (around?.covered ?? false) || skipped() };
+            declared = { kind: 'describe', ...base, isShuffled: flags.has('shuffle'), passesDown };
         }
-        return {
-            kind: 'test',
-            ...base,
-            testContext: skipNames(fn, table?.name === 'for' ? 1 : table ? null : 0),
-        };
+        else {
+            declared = { kind: 'test', ...base, testContext: skipNames(fn, table?.name === 'for' ? 1 : table ? null : 0) };
+        }
+        return refusal ? refused(call, refusal, context, () => declared) : declared;
     }
     /** Whether an argument holds options: an object, a name for one, or anything but a function before the body. */
     isOptions(node, next, context) {
@@ -600,9 +682,9 @@ export class VitestAdapter {
     readDeclarationOptions(node, context, problems) {
         const details = { tags: [], annotations: [], locks: [], meta: null };
         const result = {
-            flags: [],
+            flags: new Map(),
             concurrent: null,
-            conditions: [],
+            skip: null,
             details,
         };
         if (!node)
@@ -618,15 +700,15 @@ export class VitestAdapter {
             else if (option?.resolved.ok && flag === 'concurrent') {
                 result.concurrent = Boolean(option.resolved.value);
             }
-            else if (option?.resolved.ok && option.resolved.value) {
-                result.flags.push(flag);
+            else if (option?.resolved.ok) {
+                result.flags.set(flag, Boolean(option.resolved.value));
             }
         }
         const skip = options.values.get('skip');
         if (skip) {
-            result.conditions.push(skip.resolved.ok
+            result.skip = skip.resolved.ok
                 ? { applies: skip.resolved.value ? 'always' : 'never', text: null }
-                : { applies: 'sometimes', text: snippet(text(this.file, skip.node)) });
+                : { applies: 'sometimes', text: snippet(text(this.file, skip.node)) };
         }
         const tags = options.values.get('tags');
         if (tags && atLeast(this.file.version, 4, 1)) {

package/dist/index.d.ts

@@ -1,4 +1,6 @@
 export { scan } from './scan.ts';
 export { scanSource } from './scan-source.ts';
+export { filterInventory, pickTestFields } from './filter.ts';
+export type { InventoryFilter, PickedInventory } from './filter.ts';
 export type { CommentsMode, ScanOptions, ScanSourceOptions } from './options.ts';
-export type { Annotation, DeclaredAt, Diagnostic, DiagnosticCode, DiagnosticLevel, Framework, Inventory, MetaValue, StateSource, SuiteRecord, Summary, TestRecord, TestState, Tool, } from './types.ts';
+export type { Annotation, DeclaredAt, Diagnostic, DiagnosticCode, DiagnosticLevel, Framework, Inventory, InventoryLine, MetaValue, StateSource, SuiteRecord, Summary, TestRecord, TestState, Tool, } from './types.ts';

package/dist/index.js

@@ -1,2 +1,3 @@
 export { scan } from "./scan.js";
 export { scanSource } from "./scan-source.js";
+export { filterInventory, pickTestFields } from "./filter.js";

package/dist/json.d.ts

@@ -1,6 +1,12 @@
 import type { Inventory } from './types.ts';
+/** An inventory as the command line writes it, with every key of the test records or only the picked ones. */
+export type Output = Omit<Inventory, 'tests'> & {
+    tests: object[];
+};
 /**
  * Writes an inventory as JSON one record at a time, so a large inventory never becomes one huge string.
  * The text is exactly what `JSON.stringify(inventory, null, pretty ? 2 : undefined)` returns.
  */
-export declare function writeInventory(inventory: Inventory, pretty: boolean, write: (chunk: string) => Promise<void>): Promise<void>;
+export declare function writeInventory(inventory: Output, pretty: boolean, write: (chunk: string) => Promise<void>): Promise<void>;
+/** Writes an inventory as JSON Lines: one line per record, each marked by `type`, as `InventoryLine` describes. */
+export declare function writeInventoryLines(inventory: Output, write: (chunk: string) => Promise<void>): Promise<void>;

package/dist/json.js

@@ -1,18 +1,24 @@
 /** Collects small pieces into larger chunks, so a stream gets few writes. */
 const CHUNK_SIZE = 64 * 1024;
+function chunked(write) {
+    let buffer = '';
+    return {
+        emit: async (text) => {
+            buffer += text;
+            if (buffer.length >= CHUNK_SIZE) {
+                await write(buffer);
+                buffer = '';
+            }
+        },
+        flush: () => write(buffer),
+    };
+}
 /**
  * Writes an inventory as JSON one record at a time, so a large inventory never becomes one huge string.
  * The text is exactly what `JSON.stringify(inventory, null, pretty ? 2 : undefined)` returns.
  */
 export async function writeInventory(inventory, pretty, write) {
-    let buffer = '';
-    const emit = async (text) => {
-        buffer += text;
-        if (buffer.length >= CHUNK_SIZE) {
-            await write(buffer);
-            buffer = '';
-        }
-    };
+    const { emit, flush } = chunked(write);
     const stringify = (value, depth) => {
         const json = JSON.stringify(value, null, pretty ? 2 : undefined);
         return pretty ? json.replaceAll('\n', `\n${'  '.repeat(depth)}`) : json;
@@ -34,5 +40,20 @@ export async function writeInventory(inventory, pretty, write) {
         }
     }
     await emit(`${newline(0)}}`);
-    await write(buffer);
+    await flush();
+}
+/** Writes an inventory as JSON Lines: one line per record, each marked by `type`, as `InventoryLine` describes. */
+export async function writeInventoryLines(inventory, write) {
+    const { emit, flush } = chunked(write);
+    const line = (type, record) => emit(`${JSON.stringify({ type, ...record })}\n`);
+    const { schemaVersion, tool, framework, frameworkVersion } = inventory;
+    await line('inventory', { schemaVersion, tool, framework, frameworkVersion });
+    for (const suite of inventory.suites)
+        await line('suite', suite);
+    for (const test of inventory.tests)
+        await line('test', test);
+    for (const diagnostic of inventory.diagnostics)
+        await line('diagnostic', diagnostic);
+    await line('summary', inventory.summary);
+    await flush();
 }

package/dist/model.d.ts

@@ -1,4 +1,4 @@
-import type { CallExpression, Node } from 'oxc-parser';
+import type { CallExpression, Expression, Node } from 'oxc-parser';
 import type { FunctionNode } from './ast.ts';
 import type { Annotation, DiagnosticCode, DiagnosticLevel, MetaValue } from './types.ts';
 export type State = 'skip' | 'fixme' | 'todo' | 'expectedToFail';
@@ -12,6 +12,11 @@ export interface StateSetting {
     /** The reason could not be worked out to a string, so `reason` holds its source text. */
     hasDynamicReason: boolean;
     line: number;
+    /**
+     * Set by code in a test or hook body, which runs only when the test does: a state set while the file loads, on the
+     * test or a describe around it, keeps the test from getting there.
+     */
+    afterLoad?: boolean;
 }
 export interface Span {
     start: number;
@@ -64,6 +69,8 @@ export interface TestDeclaration extends Declaration {
 export interface SuiteDeclaration extends Declaration {
     kind: 'describe';
     isShuffled: boolean;
+    /** What the describe passes down to the calls inside it, such as Vitest's `skip` option; null for nothing. */
+    passesDown: unknown;
 }
 export interface Condition {
     /** `always` and `never` are conditions that could be worked out from the file. */
@@ -92,9 +99,15 @@ export type ApiCall = TestDeclaration | SuiteDeclaration | {
     kind: 'annotations';
     items: Annotation[];
     problems: Problem[];
-} | {
+}
+/**
+ * A call the runner refuses. When it is shaped like a declaration, as `describe.sequential('title', fn)` is in Vitest
+ * 5, `declaration` is what it would declare, so that its tests are listed as not loaded rather than missing.
+ */
+ | {
     kind: 'invalid';
     problem: Problem;
+    declaration?: TestDeclaration | SuiteDeclaration;
 } | {
     kind: 'other';
 };
@@ -105,6 +118,27 @@ export interface CallContext {
     inTest: boolean;
     /** Inside a test or hook body, where calls don't declare tests. */
     inBody: boolean;
+    /**
+     * What the describe the call is registered in passes down, as the framework returned it: the describe around a
+     * helper's call, not where the helper is written. Null outside any describe.
+     */
+    passedDown: unknown;
+    /**
+     * What a function declared in the file, or imported from a local module, returns, for a call on its result such as
+     * `conditionalTest({ min: 22 })('title', fn)`; null when the name is not a function the scan can find.
+     */
+    returnsOf(name: string, scopes: readonly Node[]): Returns | null;
+}
+/** The values a function returns, read by the adapter of the file that writes the function. */
+export interface Returns {
+    adapter: Adapter;
+    /** Each value with the scopes around it; null when the function may return no value, or returns a promise. */
+    values: {
+        expression: Expression;
+        scopes: readonly Node[];
+    }[] | null;
+    /** What the functions the values call return, looked up in the file that writes the function. */
+    returnsOf: CallContext['returnsOf'];
 }
 /** A module read to see whether it exports a custom `test` object. */
 export interface ModuleSource {
@@ -124,5 +158,10 @@ export interface Adapter {
     fileTags: string[];
     usesGlobals: boolean;
     classify(call: CallExpression, context: CallContext): ApiCall | null;
+    /**
+     * The test or describe function a value holds, in the adapter's own terms, as `it.skip` in `return it.skip`; null
+     * when it holds none. A function the value calls is followed to what it returns through `returnsOf`.
+     */
+    testFunction(expression: Expression, scopes: readonly Node[], returnsOf: CallContext['returnsOf']): unknown;
 }
 export {};

package/dist/options.d.ts

@@ -3,12 +3,15 @@ import type { Framework } from './types.ts';
 export type { CommentsMode };
 /** @inline */
 export interface ScanOptions {
-    /** Glob patterns for the test files, relative to `root`. */
+    /**
+     * Glob patterns for the test files, relative to `root`. As in Playwright and Vitest, they match names that start with
+     * a dot too.
+     */
     patterns: string[];
     framework: Framework;
     /** The project root. Paths in the output are relative to it. Defaults to the current directory. */
     root?: string;
-    /** Glob patterns to leave out, in addition to `node_modules`. */
+    /** Glob patterns to leave out, in addition to `node_modules` and `.git`. */
     ignore?: string[];
     /** The framework version whose rules apply, instead of the one read from the project. */
     frameworkVersion?: string;

package/dist/records.js

@@ -2,12 +2,14 @@ import { REJECTS_FILE, toDiagnostic } from "./diagnostics.js";
 import { problem } from "./frameworks/common.js";
 import { hashNodes, shortHash } from "./hash.js";
 /**
- * The state the runner applies, from the candidates nearest the test first. An unconditional skip, fixme or todo
- * wins over an unconditional expected failure, since the test doesn't run; then the nearest conditional state.
+ * The state the runner applies, from the candidates nearest the test first. An unconditional skip, fixme or todo wins
+ * over an unconditional expected failure, since the test doesn't run, and one set while the file loads wins over one
+ * in a test or hook body, which then never runs; then the nearest conditional state.
  */
 function chooseState(candidates) {
     const always = candidates.filter((candidate) => candidate.setting.condition === null);
-    return (always.find((candidate) => candidate.setting.state !== 'expectedToFail') ?? always.at(0) ?? candidates.at(0) ?? null);
+    const stops = always.filter((candidate) => candidate.setting.state !== 'expectedToFail');
+    return (stops.find((candidate) => !candidate.setting.afterLoad) ?? stops.at(0) ?? always.at(0) ?? candidates.at(0) ?? null);
 }
 /** The scope and the scopes around it, innermost first. */
 function outward(scope) {