test-inventory 0.1.2 → 0.2.0

package/dist/extract.js

@@ -1,8 +1,16 @@
-import { childNodes, isImportMetaVitest, propertyName, unwrap } from "./ast.js";
+import { childNodes, isFunctionNode, isImportMetaVitest, propertyName, unwrap } from "./ast.js";
 import { exportName } from "./frameworks/bindings.js";
 import { problem } from "./frameworks/common.js";
 import { snippet, splitLines } from "./source.js";
 import { isScopeNode } from "./values.js";
+/** How many helpers deep a call is followed into the functions it calls, far more than real suites nest. */
+const MAX_DEPTH = 16;
+/**
+ * How many helper calls are followed in one file, and from each call in a test or hook, counting the calls inside the
+ * helpers; far more than real suites make. Helpers that call each other in several places multiply: ten calls at each
+ * of six levels are a million.
+ */
+const MAX_CALLS = 10_000;
 /** Whether a function is called where it is written, so that its tests are registered there. */
 function calledWhereWritten(call, written) {
     return (call.scope === written.scope &&
@@ -39,21 +47,46 @@ class Walker {
     suites = [];
     tests = [];
     problems = [];
-    parsed;
-    adapter;
-    values;
+    /** The scanned file. */
+    main;
+    /** The file whose code is being walked: the scanned file, or the module of an imported helper. */
+    frame;
+    /** While an imported helper is walked, the call in the scanned file that walks it; records and problems point there. */
+    site = null;
+    openModule;
+    frames = new Map();
+    /** Problems of helper modules' own imports, reported once, at the first call that walks the module. */
+    moduleProblems = new Set();
+    /** The file each describe is written in, so that a describe's body hash only leaves out code from its own file. */
+    suiteFrames = new WeakMap();
     effects = new Map();
     helperCalls = [];
     /** Where each function with a name is written, outside test and hook bodies. */
     written = new Map();
-    /** Every call by name to a function declared in the file. */
+    /**
+     * Every call by name to a function declared in the file, once per call: a call inside a helper is walked again each
+     * time the helper is, and the first walk, from where the helper is called, places it.
+     */
     callSites = new Map();
     /** The function with a name each test is declared in, which registers the test when it is called. */
     declaredIn = new Map();
-    constructor(parsed, adapter, values) {
-        this.parsed = parsed;
-        this.adapter = adapter;
-        this.values = values;
+    deferred = [];
+    isDeferred = new Set();
+    /** Functions walked at one of their calls, so that their tests are recorded where they are registered. */
+    walkedAtCall = new Set();
+    /** The functions being walked at their calls, innermost last, to stop recursion. */
+    callStack = [];
+    /** Helper calls walked in the file so far, up to MAX_CALLS. */
+    callsWalked = 0;
+    /** Problems already reported, since a function walked at several calls finds the same ones each time. */
+    reported = new Set();
+    /** For each file's program, the scopes around each function in it. */
+    scopeChains = new Map();
+    constructor(main, openModule) {
+        this.main = main;
+        this.frame = main;
+        this.openModule = openModule;
+        const { adapter } = main;
         this.fileScope = {
             kind: 'file',
             parent: null,
@@ -65,7 +98,7 @@ class Walker {
         };
     }
     run() {
-        this.visit(this.parsed.program, {
+        this.visit(this.main.parsed.program, {
             scope: this.fileScope,
             test: null,
             hookScope: null,
@@ -76,15 +109,23 @@ class Walker {
             isInFunction: false,
             helper: null,
             declaredIn: null,
+            quiet: false,
+            registeredAt: null,
         });
-        const exported = this.exportedFunctions(this.parsed.program);
+        // Functions defined inside these are deferred in turn; the loop reaches them too, as they are added to the end.
+        for (const entry of this.deferred)
+            this.walkWhereWritten(entry);
+        // Records follow the order the file registers them in; the sort is stable, so one call's tests keep theirs.
+        this.tests.sort((a, b) => a.order - b.order);
+        this.suites.sort((a, b) => a.order - b.order);
+        const exported = this.exportedFunctions(this.main.parsed.program);
         this.applyHelpers(exported);
         this.checkFunctionTests(exported);
         return {
             suites: this.suites,
             tests: this.tests,
-            problems: [...this.adapter.problems, ...this.problems],
-            usesGlobals: this.adapter.usesGlobals,
+            problems: [...this.main.adapter.problems, ...this.problems],
+            usesGlobals: this.main.adapter.usesGlobals,
         };
     }
     visit(node, context) {
@@ -103,11 +144,15 @@ class Walker {
     }
     visitNode(node, context) {
         switch (node.type) {
-            case 'CallExpression':
-                this.helperCall(node, context);
+            case 'CallExpression': {
+                const helper = this.helperCall(node, context);
                 if (this.call(node, context) || this.loopCall(node, context))
                     return;
-                break;
+                this.visitChildren(node, context);
+                if (helper)
+                    this.walkAtCall(helper, node, context);
+                return;
+            }
             case 'IfStatement': {
                 // In-source tests sit inside `if (import.meta.vitest)`, which is how they are written, not a condition.
                 if (isImportMetaVitest(node.test))
@@ -158,14 +203,23 @@ class Walker {
                 // A function outside any test or hook runs when it is called; what it sets applies where it is called.
                 const helper = context.test || context.hookScope ? null : node;
                 const named = helper !== null && this.isNamed(node);
-                if (named)
+                // In an imported helper's module, a function runs only when it is called, and is walked then.
+                if (named && this.frame !== this.main)
+                    return;
+                if (named && !this.isDeferred.has(node)) {
+                    // Its calls decide where its tests are registered, and a call may come after it, so it waits.
                     this.written.set(node, { ...this.placement(context), declaredIn: context.declaredIn });
+                    this.isDeferred.add(node);
+                    this.deferred.push({ fn: node, context, scopes: [...this.scopes], parents: [...this.parents] });
+                    return;
+                }
+                if (named)
+                    return;
                 this.visitChildren(node, {
                     ...context,
                     isInFunction: true,
                     helper: helper ?? context.helper,
                     guards: helper ? [] : context.guards,
-                    declaredIn: named ? node : context.declaredIn,
                 });
                 return;
             }
@@ -202,7 +256,7 @@ class Walker {
         this.scopes.pop();
     }
     text(node) {
-        return snippet(this.parsed.source.slice(node.start, node.end));
+        return snippet(this.frame.parsed.source.slice(node.start, node.end));
     }
     /** `symbols.forEach((symbol) => test(...))` declares its tests in a loop. */
     loopCall(call, context) {
@@ -221,7 +275,7 @@ class Walker {
         return true;
     }
     call(call, context) {
-        const api = this.adapter.classify(call, {
+        const api = this.frame.adapter.classify(call, {
             scopes: this.scopes,
             testContext: context.testContext,
             inTest: context.test !== null,
@@ -240,7 +294,11 @@ class Walker {
                 this.declareSuite(call, api, context);
                 return true;
             case 'modifier': {
-                (context.test?.problems ?? this.problems).push(...api.problems);
+                if (context.test)
+                    context.test.problems.push(...api.problems.map((item) => this.here(item)));
+                else
+                    for (const item of api.problems)
+                        this.report(item);
                 if (api.condition.applies === 'never')
                     return true;
                 const own = api.condition.applies === 'sometimes' ? [api.condition.text] : [];
@@ -249,7 +307,7 @@ class Walker {
                     condition: joinConditions([...context.guards, ...own]),
                     reason: api.reason,
                     hasDynamicReason: api.hasDynamicReason,
-                    line: this.parsed.source.line(call.start),
+                    line: this.lineOf(call),
                 };
                 if (context.helper)
                     this.effectsOf(context.helper).push({ kind: 'state', setting, call });
@@ -258,7 +316,8 @@ class Walker {
                 return true;
             }
             case 'configure':
-                this.problems.push(...api.problems);
+                for (const item of api.problems)
+                    this.report(item);
                 if (context.helper) {
                     this.effectsOf(context.helper).push({ kind: 'configure', mode: api.mode, locks: api.locks, call });
                 }
@@ -281,11 +340,11 @@ class Walker {
                 return true;
             case 'annotations':
                 context.test?.annotations.push(...api.items);
-                context.test?.problems.push(...api.problems);
+                context.test?.problems.push(...api.problems.map((item) => this.here(item)));
                 return true;
             case 'invalid': {
                 const afterLoad = context.test !== null || context.hookScope !== null || context.helper !== null;
-                this.problems.push(afterLoad ? { ...api.problem, afterLoad } : api.problem);
+                this.report(afterLoad ? { ...api.problem, afterLoad } : api.problem);
                 return true;
             }
             case 'other':
@@ -299,29 +358,239 @@ class Walker {
     }
     /** The function a name refers to when it is declared in the file, as a function or a variable holding one. */
     functionNamed(name, scopes) {
-        const declaration = this.values.declarationOf(name, scopes);
+        return this.functionIn(this.frame, name, scopes);
+    }
+    functionIn(frame, name, scopes) {
+        const declaration = frame.values.declarationOf(name, scopes);
         if (declaration?.type === 'FunctionDeclaration')
             return declaration;
         const init = declaration?.type === 'VariableDeclarator' && declaration.init ? unwrap(declaration.init) : null;
         return init?.type === 'ArrowFunctionExpression' || init?.type === 'FunctionExpression' ? init : null;
     }
-    /** Records a call to a function declared in the file, so that the states it sets can follow the call. */
+    /**
+     * Records a call to a function declared in the file. A call from the file or a describe returns the function, to be
+     * walked there: its tests are registered in the describe around the call, and what it sets applies there. A call
+     * from a test, a hook or another function is applied later, through the states the function sets.
+     */
     helperCall(call, context) {
         const callee = unwrap(call.callee);
-        const fn = callee.type === 'Identifier' ? this.functionNamed(callee.name, this.scopes) : null;
-        if (!fn)
-            return;
-        const sites = this.callSites.get(fn) ?? [];
-        sites.push(this.placement(context));
+        if (callee.type !== 'Identifier')
+            return null;
+        const fn = this.functionNamed(callee.name, this.scopes);
+        if (!fn) {
+            const runsHere = !context.test && !context.hookScope && !context.helper;
+            const imported = runsHere && this.callStack.length < MAX_DEPTH ? this.importedFunction(callee.name) : null;
+            return imported && !this.callStack.includes(imported.fn) ? this.withinLimit(imported, call) : null;
+        }
+        const sites = this.callSites.get(fn) ?? new Map();
+        if (!sites.has(call))
+            sites.set(call, this.placement(context));
         this.callSites.set(fn, sites);
         if (context.helper) {
             this.effectsOf(context.helper).push({ kind: 'call', fn, guards: context.guards });
         }
-        else {
-            const target = context.test ?? context.hookScope ?? context.scope;
-            const scope = context.test || context.hookScope ? null : context.scope;
-            this.helperCalls.push({ fn, target, scope, guards: context.guards });
+        else if (context.test || context.hookScope) {
+            this.helperCalls.push({
+                call,
+                fn,
+                target: context.test ?? context.hookScope,
+                guards: context.guards,
+            });
+        }
+        else if (!this.callStack.includes(fn) && this.callStack.length < MAX_DEPTH) {
+            return this.withinLimit({ fn, frame: this.frame }, call);
         }
+        return null;
+    }
+    /** The function to walk at a call, while the file has calls left to walk; past MAX_CALLS, the call is reported once. */
+    withinLimit(callee, call) {
+        if (this.callsWalked < MAX_CALLS) {
+            this.callsWalked++;
+            return callee;
+        }
+        if (this.callsWalked === MAX_CALLS) {
+            this.callsWalked++;
+            this.report(problem('test-in-function', call, `The file's helper functions are called more than ${MAX_CALLS.toLocaleString('en-US')} times, counting the calls inside them, so the scan stops following them here. Tests they register from here on are missing, or listed once where they are written.`));
+        }
+        return null;
+    }
+    /** The function a name imported from a local module stands for, in the file that writes it; null otherwise. */
+    importedFunction(name) {
+        const declaration = this.frame.values.declarationOf(name, this.scopes);
+        const source = this.frame.values.importSource(name, this.scopes);
+        if (source === null)
+            return null;
+        const imported = declaration?.type === 'ImportSpecifier' ? exportName(declaration.imported) : 'default';
+        const frame = this.openFrom(this.frame, 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. */
+    openFrom(frame, source) {
+        const module = frame.readModule?.(source);
+        if (!module || 'reason' in module)
+            return null;
+        if (!this.frames.has(module))
+            this.frames.set(module, this.openModule(module));
+        return this.frames.get(module) ?? null;
+    }
+    /**
+     * The function a module exports under a name, written there or re-exported from another module, as a barrel file
+     * does; null when the export isn't a function the scan can find. Each module is searched once for a name, however many
+     * barrels lead to it: one searched before didn't have it, or the search would have ended there.
+     */
+    exportedFunction(frame, name, searched, depth) {
+        const key = `${frame.relativeFilePath}\0${name}`;
+        if (searched.has(key) || depth >= MAX_DEPTH)
+            return null;
+        searched.add(key);
+        const { program } = frame.parsed;
+        const local = (localName) => {
+            const fn = this.functionIn(frame, localName, [program]);
+            return fn ? { fn, frame } : null;
+        };
+        const from = (source, exported) => {
+            const module = this.openFrom(frame, source);
+            return module ? this.exportedFunction(module, exported, searched, depth + 1) : null;
+        };
+        for (const statement of program.body) {
+            if (statement.type === 'ExportDefaultDeclaration' && name === 'default') {
+                const declaration = statement.declaration;
+                if (declaration.type === 'FunctionDeclaration' || isFunctionNode(declaration))
+                    return { fn: declaration, frame };
+                return declaration.type === 'Identifier' ? local(declaration.name) : null;
+            }
+            if (statement.type === 'ExportAllDeclaration' && !statement.exported) {
+                const found = from(statement.source.value, name);
+                if (found)
+                    return found;
+            }
+            if (statement.type !== 'ExportNamedDeclaration')
+                continue;
+            const declaration = statement.declaration;
+            if (declaration?.type === 'FunctionDeclaration' && declaration.id?.name === name)
+                return { fn: declaration, frame };
+            if (declaration?.type === 'VariableDeclaration') {
+                const declarator = declaration.declarations.find((item) => item.id.type === 'Identifier' && item.id.name === name);
+                if (declarator)
+                    return local(name);
+            }
+            const specifier = statement.specifiers.find((item) => exportName(item.exported) === name);
+            if (specifier) {
+                const localName = exportName(specifier.local);
+                return statement.source ? from(statement.source.value, localName) : local(localName);
+            }
+        }
+        return null;
+    }
+    /**
+     * Walks a function at one of its calls from the file or a describe, as the runner runs it there: with the scopes
+     * where it is written, and its parameters bound to the call's arguments so that titles built from them resolve. A
+     * function imported from another module is walked in that module, and what it registers points at this call.
+     */
+    walkAtCall({ fn, frame }, call, context) {
+        this.walkedAtCall.add(fn);
+        // Arguments are worked out where the call is, in the file and scopes of the caller.
+        const spread = call.arguments.findIndex((item) => item.type === 'SpreadElement');
+        const args = (spread === -1 ? call.arguments : call.arguments.slice(0, spread)).map((item) => this.frame.values.resolve(item, this.scopes));
+        const caller = this.frame;
+        const site = this.site;
+        if (frame !== caller) {
+            this.frame = frame;
+            this.site ??= call;
+        }
+        const scopes = this.scopeChain(fn);
+        const saved = this.scopes.splice(0, this.scopes.length, ...scopes);
+        this.callStack.push(fn);
+        frame.values.withArguments(fn, args, scopes, () => {
+            this.visitCallback(fn, {
+                ...context,
+                isInFunction: true,
+                declaredIn: null,
+                registeredAt: context.registeredAt ?? call.start,
+            });
+        });
+        this.callStack.pop();
+        this.scopes.splice(0, this.scopes.length, ...saved);
+        // What the module's own imports couldn't resolve is reported at the call, as it is why tests may be missing.
+        if (frame !== caller) {
+            for (const item of frame.adapter.problems.filter((found) => !this.moduleProblems.has(found))) {
+                this.moduleProblems.add(item);
+                this.report(item);
+            }
+        }
+        this.frame = caller;
+        this.site = site;
+    }
+    /**
+     * Walks a deferred function where it is written. One that was walked at its calls only collects the states it sets,
+     * for calls from tests and hooks; one that wasn't records its tests where they are written, as nothing places them.
+     */
+    walkWhereWritten({ fn, context, scopes, parents }) {
+        const savedScopes = this.scopes.splice(0, this.scopes.length, ...scopes);
+        const savedParents = this.parents.splice(0, this.parents.length, ...parents);
+        this.visitChildren(fn, {
+            ...context,
+            isInFunction: true,
+            helper: fn,
+            guards: [],
+            declaredIn: fn,
+            quiet: this.walkedAtCall.has(fn),
+        });
+        this.scopes.splice(0, this.scopes.length, ...savedScopes);
+        this.parents.splice(0, this.parents.length, ...savedParents);
+    }
+    /** The scopes around a function where it is written, outermost first, to resolve names in it at its calls. */
+    scopeChain(fn) {
+        const { program } = this.frame.parsed;
+        let chains = this.scopeChains.get(program);
+        if (!chains) {
+            const found = new Map();
+            const around = [];
+            const visit = (node) => {
+                if (node.type === 'FunctionDeclaration' || isFunctionNode(node))
+                    found.set(node, [...around]);
+                const isScope = isScopeNode(node);
+                if (isScope)
+                    around.push(node);
+                for (const child of childNodes(node))
+                    visit(child);
+                if (isScope)
+                    around.pop();
+            };
+            visit(program);
+            chains = found;
+            this.scopeChains.set(program, chains);
+        }
+        return chains.get(fn);
+    }
+    /** Reports a problem not tied to a test, once, however many times a function with it is walked. */
+    report(found) {
+        const item = this.here(found);
+        // Problems found in code point at it.
+        const key = `${item.code}\0${item.node.start}\0${item.message}`;
+        if (this.reported.has(key))
+            return;
+        this.reported.add(key);
+        this.problems.push(item);
+    }
+    /** A problem found in an imported helper points at the call in the scanned file that walks the helper. */
+    here(item) {
+        return this.site ? { ...item, node: this.site } : item;
+    }
+    /** The line in the scanned file of code being walked: its own, or that of the call walking an imported helper. */
+    lineOf(node) {
+        return this.main.parsed.source.line((this.site ?? node).start);
+    }
+    /** Where an imported helper writes a test or describe; null for code in the scanned file. */
+    declaredAt(call) {
+        if (!this.site)
+            return null;
+        return { relativeFilePath: this.frame.relativeFilePath, source: this.frame.parsed.source, start: call.start };
+    }
+    /** Leaves a test or describe out of the describe's body hash, when both are written in the same file. */
+    cut(scope, call) {
+        if (scope.suite && this.suiteFrames.get(scope.suite) === this.frame)
+            scope.suite.cuts.push(this.statement(call));
     }
     /** Functions the file exports, whose callers in other files are not followed. */
     exportedFunctions(program) {
@@ -357,9 +626,18 @@ class Walker {
      */
     applyHelpers(exported) {
         const reached = new Set();
+        // For one call from a test or hook: the conditions each helper was expanded under, and how many expansions it took.
+        let expanded = new Map();
+        let steps = 0;
         const expand = (fn, guards, path) => {
             if (path.has(fn) || exported.has(fn))
                 return [];
+            // A helper reached again under the same conditions sets the same states again.
+            const conditions = expanded.get(fn) ?? new Set();
+            const key = guards.join('\0');
+            if (conditions.has(key) || ++steps > MAX_CALLS)
+                return [];
+            expanded.set(fn, conditions.add(key));
             reached.add(fn);
             return (this.effects.get(fn) ?? []).flatMap((effect) => {
                 if (effect.kind === 'call')
@@ -371,18 +649,23 @@ class Walker {
             });
         };
         for (const call of this.helperCalls) {
+            expanded = new Map();
+            steps = 0;
             for (const effect of expand(call.fn, call.guards, new Set())) {
+                // `describe.configure()` does nothing in a test or hook body.
                 if (effect.kind === 'state')
                     call.target.states.push(effect.setting);
-                else if (call.scope)
-                    configure(call.scope, effect);
+            }
+            if (steps > MAX_CALLS) {
+                const callee = snippet(this.frame.parsed.source.slice(call.call.callee.start, call.call.callee.end));
+                this.problems.push(problem('state-in-helper', call.call, `${callee}() calls helper functions more than ${MAX_CALLS.toLocaleString('en-US')} times, counting the calls inside them, so the states they set past that are not applied.`, callee));
             }
         }
         for (const [fn, effects] of this.effects) {
             const own = effects.find((effect) => effect.kind !== 'call');
-            if (!own || (reached.has(fn) && !exported.has(fn)))
+            if (!own || ((reached.has(fn) || this.walkedAtCall.has(fn)) && !exported.has(fn)))
                 continue;
-            const callee = snippet(this.parsed.source.slice(own.call.callee.start, own.call.callee.end));
+            const callee = snippet(this.frame.parsed.source.slice(own.call.callee.start, own.call.callee.end));
             const why = exported.has(fn) ? 'is exported' : 'no test, hook or describe in the file calls';
             this.problems.push(problem('state-in-helper', own.call, `${callee}() is in a function that ${why}; it applies to the tests that call the function, so it is not applied here.`, callee));
         }
@@ -391,7 +674,7 @@ class Walker {
     misplaced(fn, exported) {
         if (exported.has(fn))
             return 'the file exports the function';
-        const sites = this.callSites.get(fn) ?? [];
+        const sites = [...(this.callSites.get(fn)?.values() ?? [])];
         if (sites.length === 0)
             return 'nothing in the file calls the function by name';
         if (sites.length > 1)
@@ -419,29 +702,32 @@ class Walker {
     nested(call, context) {
         if (!context.test && !context.hookScope)
             return false;
-        this.problems.push(problem('nested-test', call, 'A test or describe declared inside a test or hook body is not collected by the runner, so it is not listed.', snippet(this.parsed.source.slice(call.start, call.end))));
+        this.report(problem('nested-test', call, 'A test or describe declared inside a test or hook body is not collected by the runner, so it is not listed.', snippet(this.frame.parsed.source.slice(call.start, call.end))));
         return true;
     }
     declareTest(call, declaration, context) {
-        if (this.nested(call, context))
+        if (context.quiet || this.nested(call, context))
             return;
         const statement = this.statement(call);
         const test = {
             scope: context.scope,
             declaration,
             call,
+            site: this.site,
+            declaredAt: this.declaredAt(call),
+            order: context.registeredAt ?? call.start,
             states: [...declaration.states],
             annotations: [...declaration.details.annotations],
             isInLoop: context.isInLoop,
             isInCondition: context.isInCondition,
             isInFunction: context.isInFunction,
             comments: this.commentsAbove(statement.start),
-            problems: [...declaration.problems],
+            problems: declaration.problems.map((item) => this.here(item)),
         };
         this.tests.push(test);
         if (context.declaredIn)
             this.declaredIn.set(test, context.declaredIn);
-        context.scope.suite?.cuts.push(statement);
+        this.cut(context.scope, call);
         if (declaration.fn) {
             this.visitCallback(declaration.fn, {
                 ...context,
@@ -454,9 +740,10 @@ class Walker {
         }
     }
     declareSuite(call, declaration, context) {
-        if (this.nested(call, context))
+        if (context.quiet || this.nested(call, context))
             return;
-        this.problems.push(...declaration.problems);
+        for (const item of declaration.problems)
+            this.report(item);
         const scope = {
             kind: 'describe',
             parent: context.scope,
@@ -466,10 +753,19 @@ class Walker {
             details: declaration.details,
             suite: null,
         };
-        const suite = { scope, declaration, call, cuts: [] };
+        const suite = {
+            scope,
+            declaration,
+            call,
+            site: this.site,
+            declaredAt: this.declaredAt(call),
+            order: context.registeredAt ?? call.start,
+            cuts: [],
+        };
         scope.suite = suite;
         this.suites.push(suite);
-        context.scope.suite?.cuts.push(this.statement(call));
+        this.cut(context.scope, call);
+        this.suiteFrames.set(suite, this.frame);
         if (declaration.fn) {
             this.visitCallback(declaration.fn, {
                 ...context,
@@ -489,7 +785,7 @@ class Walker {
     }
     /** Comment lines on the lines directly above a statement, with no blank line in between. */
     commentsAbove(start) {
-        const { comments, source } = this.parsed;
+        const { comments, source } = this.frame.parsed;
         const lines = [];
         let next = start;
         // Comments are in source order; find the last one that ends before the statement.
@@ -512,6 +808,7 @@ class Walker {
         return lines;
     }
 }
-export function extract(parsed, adapter, values) {
-    return new Walker(parsed, adapter, values).run();
+/** 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/frameworks/bindings.d.ts

@@ -1,5 +1,6 @@
 import type { Expression, ModuleExportName, Node, Program, VariableDeclarator } from 'oxc-parser';
-import type { ModuleReader, Problem } from '../model.ts';
+import type { ModuleReader, ModuleSource, Problem } from '../model.ts';
+import { type ParsedFile } from '../parse.ts';
 import { type FileContext } from './common.ts';
 /** A name imported from a module other than the framework, which may be a custom `test` object in a fixtures file. */
 export interface ModuleImport {
@@ -26,26 +27,33 @@ export declare function requiredModule(expression: Expression): string | null;
 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 re-exports `name` from another module, which the scan does not follow. */
-export declare function reexportsFromModule(program: Program, name: string, isFramework: (source: string) => boolean): boolean;
-/**
- * Whether a module exports `name` as a value built from something imported from another module, directly or through
- * its own variables, as in `const test = baseTest.extend({...})` and then `export const browserTest = test`.
- */
-export declare function buildsFromModule(program: Program, name: string, isFramework: (source: string) => boolean): boolean;
-/** Whether a module imports or requires any of the given sources. */
+/** 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;
 /** How a framework recognizes the modules and test objects of a followed file. */
 export interface Framework {
     name: string;
     isSource: (source: string) => boolean;
-    testObjects: (program: Program) => TestObjects;
+    /** The test objects of a followed module, which uses `follow` for the names it imports from other modules. */
+    testObjects: (program: Program, follow: FollowImport) => TestObjects;
 }
+/** Shared with the walk of imported helpers, so that a module both read and walked is parsed once. */
+export declare function parseModule(module: ModuleSource): ParsedFile;
 /**
- * Follows one import to see whether the module exports a test object. Only one level is followed. A module that has
- * nothing to do with the framework is not reported: the call only looked like a test.
+ * Whether `name` from `source` is a test object, following the module through the modules it re-exports from or builds
+ * on, as deep as it takes. When it isn't, the reason says where the chain ends; it is null for a module that has
+ * 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;
+interface Followed {
+    exported: boolean;
+    reason: string | null;
+}
+/** 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;
 };
+export {};