test-inventory 0.1.2 → 0.2.1

package/dist/records.js

@@ -79,6 +79,12 @@ class RecordBuilder {
         const end = this.parsed.source.position(node.end);
         return { lineStart: start.line, lineEnd: end.line, columnStart: start.column, columnEnd: end.column };
     }
+    declaredAt(written) {
+        if (!written)
+            return null;
+        const { line, column } = written.source.position(written.start);
+        return { relativeFilePath: written.relativeFilePath, lineStart: line, columnStart: column };
+    }
     /** Each describe's titles without tags, outermost first; anonymous describes are left out. */
     describeTitles(scopes) {
         return scopes.flatMap((scope) => suiteOf(scope).declaration.title?.withoutTags ?? []);
@@ -105,7 +111,8 @@ class RecordBuilder {
             bodyHash: fn ? hashNodes(bodyNodes(fn), pending.cuts) : null,
             relativeFilePath: this.options.relativeFilePath,
             fileName: this.fileName,
-            ...this.position(call),
+            ...this.position(pending.site ?? call),
+            declaredAt: this.declaredAt(pending.declaredAt),
             title: title?.text ?? '',
             titleWithoutTags: title?.withoutTags ?? '',
             hasDynamicTitle: title?.isDynamic ?? false,
@@ -130,7 +137,9 @@ class RecordBuilder {
         };
     }
     test(pending) {
-        const { declaration, call } = pending;
+        const { declaration } = pending;
+        // A test from an imported helper is placed at the call in this file that registers it.
+        const located = pending.site ?? pending.call;
         const scopes = outward(pending.scope);
         const describes = scopes.filter((scope) => scope.kind === 'describe').reverse();
         const title = declaration.title;
@@ -162,10 +171,10 @@ class RecordBuilder {
         for (const item of pending.problems)
             this.diagnostics.push(this.diagnostic(item, id));
         if (pending.isInLoop) {
-            this.diagnostics.push(this.diagnostic(problem('test-in-loop', call, 'The test is declared in a loop; it is listed once, while the runner creates one test per iteration.'), id));
+            this.diagnostics.push(this.diagnostic(problem('test-in-loop', located, 'The test is declared in a loop; it is listed once, while the runner creates one test per iteration.'), id));
         }
         if (declaration.isOnly && chosen && chosen.source !== 'test' && chosen.setting.state === 'skip') {
-            this.diagnostics.push(this.diagnostic(problem('only-in-skipped-describe', call, 'The test uses .only, but a describe around it is skipped, so it is skipped too.'), id));
+            this.diagnostics.push(this.diagnostic(problem('only-in-skipped-describe', located, 'The test uses .only, but a describe around it is skipped, so it is skipped too.'), id));
         }
         return {
             id,
@@ -174,7 +183,8 @@ class RecordBuilder {
             suitePath,
             relativeFilePath: this.options.relativeFilePath,
             fileName: this.fileName,
-            ...this.position(call),
+            ...this.position(located),
+            declaredAt: this.declaredAt(pending.declaredAt),
             title: title.text,
             titleWithoutTags: title.withoutTags,
             hasDynamicTitle: title.isDynamic,
@@ -229,6 +239,14 @@ class RecordBuilder {
                 continue;
             const describes = outward(test.scope).filter((scope) => scope.kind === 'describe');
             const titles = describes.flatMap((scope) => suiteOf(scope).declaration.title?.text ?? []).reverse();
+            // In a loop, a title path that never changes is registered again on each pass.
+            const repeated = playwright && test.isInLoop && describes.every((scope) => !suiteOf(scope).declaration.title?.isDynamic);
+            if (repeated) {
+                const message = 'The test is declared in a loop with the same title on each pass, so Playwright fails to load the file and runs no tests at all.';
+                const item = problem('duplicate-title', test.site ?? test.call, message, test.declaration.title.text);
+                found.push({ index, problem: { ...item, level: 'error' } });
+                continue;
+            }
             const group = playwright ? null : test.scope;
             const key = JSON.stringify(playwright ? [...titles, test.declaration.title.text] : test.declaration.title.text);
             const keys = seen.get(group) ?? new Set();
@@ -237,7 +255,7 @@ class RecordBuilder {
                 const message = playwright
                     ? 'Another test in the file has the same title path, so Playwright fails to load the file and runs no tests at all.'
                     : 'Another test in the same describe has the same title.';
-                const item = problem('duplicate-title', test.call, message, test.declaration.title.text);
+                const item = problem('duplicate-title', test.site ?? test.call, message, test.declaration.title.text);
                 found.push({ index, problem: playwright ? { ...item, level: 'error' } : item });
             }
             keys.add(key);

package/dist/resolve.d.ts

@@ -2,7 +2,8 @@ import type { ModuleReader } from './model.ts';
 /** Parses JSON written with comments and trailing commas, as tsconfig files often are; null when it isn't JSON. */
 export declare function parseJsonc(text: string): unknown;
 /**
- * Returns a reader for the modules a test file imports. It follows relative paths, tsconfig `paths` and `baseUrl`,
- * package.json `imports` (`#name`), and workspace packages linked into node_modules whose entry is TypeScript source.
+ * Returns a reader for the modules a test file imports. It follows relative paths, tsconfig `paths` and `baseUrl` from
+ * the tsconfig nearest the importing file, package.json `imports` (`#name`), and workspace packages whose entry is
+ * TypeScript source. Each module it reads carries a reader for the modules that module imports in turn.
  */
 export declare function moduleResolver(root: string): (fromFile: string) => ModuleReader;

package/dist/resolve.js

@@ -1,5 +1,6 @@
 import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
+import { globSync } from 'tinyglobby';
 const EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.jsx', '.mjs', '.cjs'];
 const TYPESCRIPT_SOURCE = /(?<!\.d)\.[cm]?tsx?$/;
 function isFile(file) {
@@ -76,26 +77,62 @@ function targetStrings(target) {
     const conditions = record(target);
     return conditions ? Object.values(conditions).flatMap(targetStrings) : [];
 }
-/** `paths` and `baseUrl` from the root tsconfig.json, with the ones of the file it extends, one level deep. */
-function tsconfigPaths(root) {
-    const options = { paths: null, pathsBase: root, baseUrl: null };
-    const file = path.join(root, 'tsconfig.json');
-    const config = readJson(file);
+/** A package name and the subpath after it, as in `@trading/test-utils` and `./fixtures`; `.` when there is none. */
+function packageName(specifier) {
+    const parts = specifier.split('/');
+    const nameLength = specifier.startsWith('@') ? 2 : 1;
+    return { name: parts.slice(0, nameLength).join('/'), subpath: ['.', ...parts.slice(nameLength)].join('/') };
+}
+/** The file a path names, with `.json` added when it has no extension and doesn't exist as written, as in `extends`. */
+function jsonFile(file) {
+    if (isFile(file))
+        return file;
+    return !file.endsWith('.json') && isFile(`${file}.json`) ? `${file}.json` : null;
+}
+/** The file a tsconfig `extends` entry names: a path, or a package found in node_modules as TypeScript finds it. */
+function extendedFile(entry, directory) {
+    if (entry.startsWith('.') || path.isAbsolute(entry))
+        return jsonFile(path.resolve(directory, entry));
+    const { name, subpath } = packageName(entry);
+    for (let folder = directory;; folder = path.dirname(folder)) {
+        const packageFolder = path.join(folder, 'node_modules', name);
+        if (existsSync(packageFolder)) {
+            if (subpath !== '.')
+                return jsonFile(path.join(packageFolder, subpath));
+            const field = readJson(path.join(packageFolder, 'package.json'))?.tsconfig;
+            return jsonFile(path.join(packageFolder, typeof field === 'string' ? field : 'tsconfig.json'));
+        }
+        if (path.dirname(folder) === folder)
+            return null;
+    }
+}
+/** A tsconfig and every file it extends, the furthest base first, in the order TypeScript applies them. */
+function tsconfigLayers(file, seen = new Set()) {
+    const config = seen.has(file) ? null : readJson(file);
     if (!config)
-        return options;
-    const extended = (Array.isArray(config.extends) ? config.extends : [config.extends]).filter((item) => typeof item === 'string' && item.startsWith('.'));
-    const layers = [
-        ...extended.map((item) => {
-            const parent = path.resolve(root, item.endsWith('.json') ? item : `${item}.json`);
-            return { directory: path.dirname(parent), config: readJson(parent) };
-        }),
-        { directory: root, config },
-    ];
-    // Later layers override earlier ones, as `extends` does.
+        return [];
+    seen.add(file);
+    const directory = path.dirname(file);
+    const entries = (Array.isArray(config.extends) ? config.extends : [config.extends]).filter((item) => typeof item === 'string');
+    const bases = entries.flatMap((entry) => {
+        const base = extendedFile(entry, directory);
+        return base ? tsconfigLayers(base, seen) : [];
+    });
+    return [...bases, { directory, config }];
+}
+/**
+ * `paths` and `baseUrl` from a tsconfig and the files it extends, later files overriding earlier ones. A solution-style
+ * tsconfig without them, as Vite projects have, takes them from the first project in its `references` that sets them.
+ */
+function tsconfigPaths(file, seen = new Set()) {
+    seen.add(file);
+    const configDir = path.dirname(file);
+    const options = { paths: null, pathsBase: configDir, baseUrl: null, configDir };
+    const layers = tsconfigLayers(file);
     for (const layer of layers) {
-        const compilerOptions = record(layer.config?.compilerOptions);
+        const compilerOptions = record(layer.config.compilerOptions);
         if (typeof compilerOptions?.baseUrl === 'string') {
-            options.baseUrl = path.resolve(layer.directory, compilerOptions.baseUrl);
+            options.baseUrl = path.resolve(layer.directory, compilerOptions.baseUrl.replaceAll('${configDir}', configDir));
         }
         const paths = record(compilerOptions?.paths);
         if (paths) {
@@ -103,16 +140,47 @@ function tsconfigPaths(root) {
             options.pathsBase = layer.directory;
         }
     }
-    if (options.baseUrl)
+    if (options.baseUrl) {
         options.pathsBase = options.baseUrl;
+    }
+    else if (!options.paths) {
+        const references = layers.at(-1)?.config.references;
+        for (const reference of Array.isArray(references) ? references : []) {
+            const target = record(reference)?.path;
+            if (typeof target !== 'string')
+                continue;
+            const referenced = path.resolve(configDir, target);
+            const referencedFile = target.endsWith('.json') ? referenced : path.join(referenced, 'tsconfig.json');
+            // Projects may reference each other; each tsconfig is read once.
+            const found = isFile(referencedFile) && !seen.has(referencedFile) ? tsconfigPaths(referencedFile, seen) : null;
+            if (found && (found.paths ?? found.baseUrl))
+                return found;
+        }
+    }
     return options;
 }
+/**
+ * The tsconfig TypeScript uses for a file in the folder: the nearest tsconfig.json above it. Without one, the nearest
+ * tsconfig.base.json, which holds the path aliases of an Nx workspace.
+ */
+function nearestTsconfig(directory) {
+    let base = null;
+    for (let folder = directory;; folder = path.dirname(folder)) {
+        const file = path.join(folder, 'tsconfig.json');
+        if (isFile(file))
+            return file;
+        const baseFile = path.join(folder, 'tsconfig.base.json');
+        base ??= isFile(baseFile) ? baseFile : null;
+        if (path.dirname(folder) === folder)
+            return base;
+    }
+}
 /** Files a path alias stands for in tsconfig `paths`; null when no pattern matches. */
 function aliasFiles(specifier, options) {
     const match = options.paths ? matchPattern(Object.keys(options.paths), specifier) : null;
     if (!match || !options.paths)
         return null;
-    return targetStrings(options.paths[match.key]).map((target) => path.resolve(options.pathsBase, target.replace('*', match.star)));
+    return targetStrings(options.paths[match.key]).map((target) => path.resolve(options.pathsBase, target.replaceAll('${configDir}', options.configDir).replace('*', match.star)));
 }
 /** Files a `#name` import may stand for, from `imports` in the nearest package.json. */
 function subpathImportFiles(specifier, directory) {
@@ -129,12 +197,110 @@ function subpathImportFiles(specifier, directory) {
             return [];
     }
 }
-/** A package linked from the workspace into node_modules, followed to its TypeScript source. */
-function workspaceSource(specifier, directory) {
-    const parts = specifier.split('/');
-    const nameLength = specifier.startsWith('@') ? 2 : 1;
-    const name = parts.slice(0, nameLength).join('/');
-    const subpath = ['.', ...parts.slice(nameLength)].join('/');
+const BUILD_FOLDERS = new Set(['dist', 'build', 'lib', 'out']);
+const FORMAT_FOLDERS = new Set(['esm', 'cjs', 'es', 'mjs', 'umd', 'types']);
+/**
+ * Where the TypeScript source of a built file usually is, for a workspace package that hasn't been built: both
+ * `dist/esm/index.js` and `dist/types/index.d.ts` come from `src/index.ts`.
+ */
+function sourceOf(target) {
+    const parts = target.replace(/^\.\//, '').split('/');
+    if (parts.length < 2 || !BUILD_FOLDERS.has(parts[0]))
+        return [];
+    const rest = parts.length > 2 && FORMAT_FOLDERS.has(parts[1]) ? parts.slice(2) : parts.slice(1);
+    const base = ['src', ...rest].join('/').replace(/(\.d)?\.[cm]?[jt]sx?$/, '');
+    return [`${base}.ts`, `${base}.tsx`];
+}
+/**
+ * The TypeScript source a package's exports, types or main point to for a subpath such as `.` or `./fixtures`. When they
+ * point to build output, the source next to it is used, as in a workspace package that hasn't been built.
+ */
+function packageEntry(folder, subpath) {
+    const manifest = readJson(path.join(folder, 'package.json'));
+    const exports = manifest?.exports;
+    const map = record(exports);
+    const isSubpathMap = map !== null && Object.keys(map).some((key) => key.startsWith('.'));
+    let targets;
+    if (isSubpathMap) {
+        const match = matchPattern(Object.keys(map), subpath);
+        targets = match ? targetStrings(map[match.key]).map((target) => target.replace('*', match.star)) : [];
+    }
+    else {
+        targets = subpath === '.' ? targetStrings(exports) : [];
+    }
+    if (subpath === '.')
+        targets.push(...targetStrings(manifest?.types), ...targetStrings(manifest?.main));
+    const file = [...targets.filter((target) => TYPESCRIPT_SOURCE.test(target)), ...targets.flatMap(sourceOf)]
+        .map((target) => path.resolve(folder, target))
+        .find(isFile);
+    return file
+        ? { file }
+        : { reason: "is a workspace package whose exports, types and main don't point to TypeScript source" };
+}
+/**
+ * The `packages` list of a pnpm-workspace.yaml, as a block list or a flow list. The file holds little more than this
+ * list, so it is read line by line rather than with a YAML parser.
+ */
+function pnpmWorkspacePatterns(text) {
+    const unquote = (item) => item.trim().replace(/^(['"])(.*)\1$/, '$2');
+    const flow = /^packages:\s*\[(.*)\]/m.exec(text);
+    if (flow)
+        return flow[1].split(',').map(unquote).filter(Boolean);
+    const patterns = [];
+    let inList = false;
+    for (const line of text.split(/\r?\n/)) {
+        if (/^packages:\s*(#.*)?$/.test(line)) {
+            inList = true;
+            continue;
+        }
+        const item = inList ? /^\s+-\s*([^#]+)/.exec(line) : null;
+        if (item)
+            patterns.push(unquote(item[1]));
+        else if (inList && line.trim() !== '' && !line.trim().startsWith('#'))
+            inList = false;
+    }
+    return patterns;
+}
+/** The folder of each package in the workspace a folder belongs to, by name; empty outside a workspace. */
+function workspacePackages(directory) {
+    for (let folder = directory;; folder = path.dirname(folder)) {
+        const workspaces = readJson(path.join(folder, 'package.json'))?.workspaces;
+        const fromManifest = Array.isArray(workspaces) ? workspaces : record(workspaces)?.packages;
+        const pnpm = readText(path.join(folder, 'pnpm-workspace.yaml'));
+        // pnpm reads only pnpm-workspace.yaml, and npm, Yarn and Bun only package.json, so a repository that moved to
+        // pnpm may still have an old list there. Packages from both are found.
+        const lists = [Array.isArray(fromManifest) ? fromManifest : null, pnpm ? pnpmWorkspacePatterns(pnpm) : null];
+        const patterns = lists.some((list) => list !== null)
+            ? lists.flat().filter((item) => typeof item === 'string')
+            : null;
+        if (patterns) {
+            // Packages are inside the workspace. A pattern or a link that leads out of its folder could send the search through
+            // the whole disk, so neither is followed.
+            const inside = patterns.filter((item) => !path.isAbsolute(item.replace(/^!/, '')) && !/(^|\/)\.\.(\/|$)/.test(item));
+            const manifests = globSync(inside.filter((item) => !item.startsWith('!')).map((item) => `${item.replace(/\/+$/, '')}/package.json`), {
+                cwd: folder,
+                absolute: true,
+                followSymbolicLinks: false,
+                ignore: ['**/node_modules/**', ...inside.filter((item) => item.startsWith('!')).map((item) => item.slice(1))],
+            });
+            const packages = new Map();
+            for (const manifest of manifests) {
+                const name = readJson(manifest)?.name;
+                if (typeof name === 'string')
+                    packages.set(name, path.dirname(manifest));
+            }
+            return packages;
+        }
+        if (path.dirname(folder) === folder)
+            return new Map();
+    }
+}
+/**
+ * A workspace package followed to its TypeScript source: through its link in node_modules, or, before an install, from
+ * the packages the workspace lists. A package installed from a registry is not followed.
+ */
+function workspaceSource(specifier, directory, packagesOf) {
+    const { name, subpath } = packageName(specifier);
     for (let folder = directory;; folder = path.dirname(folder)) {
         const linked = path.join(folder, 'node_modules', name);
         if (existsSync(linked)) {
@@ -142,41 +308,47 @@ function workspaceSource(specifier, directory) {
             if (real.split(path.sep).includes('node_modules')) {
                 return { reason: 'is an installed package, which is not followed' };
             }
-            const manifest = readJson(path.join(real, 'package.json'));
-            const exports = manifest?.exports;
-            const map = record(exports);
-            const isSubpathMap = map !== null && Object.keys(map).some((key) => key.startsWith('.'));
-            let targets;
-            if (isSubpathMap) {
-                const match = matchPattern(Object.keys(map), subpath);
-                targets = match ? targetStrings(map[match.key]).map((target) => target.replace('*', match.star)) : [];
-            }
-            else {
-                targets = subpath === '.' ? targetStrings(exports) : [];
-            }
-            if (subpath === '.')
-                targets.push(...targetStrings(manifest?.types), ...targetStrings(manifest?.main));
-            const file = targets
-                .filter((target) => TYPESCRIPT_SOURCE.test(target))
-                .map((target) => path.resolve(real, target))
-                .find(isFile);
-            return file
-                ? { file }
-                : { reason: "is a workspace package whose exports, types and main don't point to TypeScript source" };
+            return packageEntry(real, subpath);
         }
         if (path.dirname(folder) === folder)
-            return null;
+            break;
     }
+    const local = packagesOf(directory).get(name);
+    return local ? packageEntry(local, subpath) : null;
 }
 /**
- * Returns a reader for the modules a test file imports. It follows relative paths, tsconfig `paths` and `baseUrl`,
- * package.json `imports` (`#name`), and workspace packages linked into node_modules whose entry is TypeScript source.
+ * Returns a reader for the modules a test file imports. It follows relative paths, tsconfig `paths` and `baseUrl` from
+ * the tsconfig nearest the importing file, package.json `imports` (`#name`), and workspace packages whose entry is
+ * TypeScript source. Each module it reads carries a reader for the modules that module imports in turn.
  */
 export function moduleResolver(root) {
-    let options = null;
-    // Many test files import the same fixtures file; it is read once, and parsed once by the code that follows it.
+    // Many test files import the same fixtures file and share a tsconfig; each is read once.
     const modules = new Map();
-    return (fromFile) => (specifier) => {
+    const tsconfigs = new Map();
+    const pathOptions = new Map();
+    const workspaces = new Map();
+    const optionsFor = (directory) => {
+        if (!tsconfigs.has(directory))
+            tsconfigs.set(directory, nearestTsconfig(directory));
+        const file = tsconfigs.get(directory);
+        if (!file)
+            return null;
+        let options = pathOptions.get(file);
+        if (!options) {
+            options = tsconfigPaths(file);
+            pathOptions.set(file, options);
+        }
+        return options;
+    };
+    const packagesOf = (directory) => {
+        let packages = workspaces.get(directory);
+        if (!packages) {
+            packages = workspacePackages(directory);
+            workspaces.set(directory, packages);
+        }
+        return packages;
+    };
+    const reader = (fromFile) => (specifier) => {
         const directory = path.dirname(fromFile);
         let candidates;
         // `.` and `..` are paths too: the index of the file's folder, or of the folder above.
@@ -189,15 +361,15 @@ export function moduleResolver(root) {
                 return { reason: 'is not in the imports of package.json' };
         }
         else {
-            options ??= tsconfigPaths(root);
-            const aliased = aliasFiles(specifier, options);
+            const options = optionsFor(directory);
+            const aliased = options ? aliasFiles(specifier, options) : null;
             if (aliased) {
                 candidates = aliased;
             }
             else {
                 // `baseUrl` turns any name into a path, so a name not found there may still be a workspace package.
-                const fromBaseUrl = options.baseUrl ? findFile(path.resolve(options.baseUrl, specifier)) : null;
-                const workspace = fromBaseUrl ? null : workspaceSource(specifier, directory);
+                const fromBaseUrl = options?.baseUrl ? findFile(path.resolve(options.baseUrl, specifier)) : null;
+                const workspace = fromBaseUrl ? null : workspaceSource(specifier, directory, packagesOf);
                 if (workspace && 'reason' in workspace)
                     return workspace;
                 const file = fromBaseUrl ?? workspace?.file;
@@ -211,8 +383,11 @@ export function moduleResolver(root) {
             return { reason: 'could not be read' };
         if (!modules.has(found)) {
             const code = readText(found);
-            modules.set(found, code === null ? null : { code, relativeFilePath: path.relative(root, found).replaceAll('\\', '/') });
+            modules.set(found, code === null
+                ? null
+                : { code, relativeFilePath: path.relative(root, found).replaceAll('\\', '/'), readModule: reader(found) });
         }
         return modules.get(found) ?? { reason: 'could not be read' };
     };
+    return reader;
 }

package/dist/scan-file.js

@@ -1,5 +1,6 @@
 import { fileDiagnostic, toDiagnostic } from "./diagnostics.js";
 import { extract } from "./extract.js";
+import { parseModule } from "./frameworks/bindings.js";
 import { problem } from "./frameworks/common.js";
 import { PlaywrightAdapter } from "./frameworks/playwright.js";
 import { VitestAdapter } from "./frameworks/vitest.js";
@@ -8,6 +9,14 @@ import { buildRecords } from "./records.js";
 import { snippet } from "./source.js";
 import { Values } from "./values.js";
 const TYPE_TEST = /\.(test|spec)-d\.[cm]?[jt]sx?$/;
+/** A file read for the scan: the scanned file, or a module a helper function is imported from. */
+function frame(parsed, relativeFilePath, settings, readModule) {
+    const file = { source: parsed.source, values: new Values(), version: settings.version };
+    const adapter = settings.framework === 'playwright'
+        ? new PlaywrightAdapter(parsed.program, file, readModule)
+        : new VitestAdapter(parsed, file, readModule);
+    return { parsed, adapter, values: file.values, readModule, relativeFilePath };
+}
 /** Reads one file: parse, extract, build records, and drop the AST. Never throws. */
 export function scanFile(code, relativeFilePath, settings) {
     try {
@@ -20,11 +29,11 @@ export function scanFile(code, relativeFilePath, settings) {
             if (parsed.program.body.length === 0)
                 return { suites: [], tests: [], diagnostics, usesGlobals: false };
         }
-        const file = { source: parsed.source, values: new Values(), version: settings.version };
-        const adapter = settings.framework === 'playwright'
-            ? new PlaywrightAdapter(parsed.program, file, settings.readModule)
-            : new VitestAdapter(parsed, file, settings.readModule);
-        const extraction = extract(parsed, adapter, file.values);
+        const main = frame(parsed, relativeFilePath, settings, settings.readModule);
+        const extraction = extract(main, (module) => {
+            const helper = parseModule(module);
+            return helper.error ? null : frame(helper, module.relativeFilePath, settings, module.readModule);
+        });
         const records = buildRecords(extraction, parsed, {
             relativeFilePath,
             framework: settings.framework,

package/dist/types.d.ts

@@ -101,6 +101,11 @@ export interface SuiteRecord {
     columnStart: Position;
     /** In UTF-16 code units. */
     columnEnd: Position;
+    /**
+     * Where a helper imported from another file writes the describe; the record's location is then the
+     * call that registers it. Null for code written in the scanned file.
+     */
+    declaredAt: DeclaredAt | null;
     /** As the runner shows it, tags included. */
     title: string;
     /** `title` with `@tag` words removed and spaces tidied. */
@@ -157,6 +162,11 @@ export interface TestRecord {
     columnStart: Position;
     /** In UTF-16 code units. */
     columnEnd: Position;
+    /**
+     * Where a helper imported from another file writes the test; the record's location is then the
+     * call that registers it. Null for code written in the scanned file.
+     */
+    declaredAt: DeclaredAt | null;
     /** As the runner shows it, tags included. */
     title: string;
     /** `title` with `@tag` words removed and spaces tidied. */
@@ -209,12 +219,20 @@ export interface TestRecord {
     caseCount: Count | null;
     /** Declared inside a loop, `forEach` or `map`. */
     isInLoop: boolean;
-    /** Declared inside `if`, `?:`, `&&` or `switch`. */
+    /** Declared inside `if`, `?:`, `&&`, `switch` or a `catch` block. */
     isInCondition: boolean;
     /** Declared inside a plain function. */
     isInFunction: boolean;
 }
 /** @inline */
+export interface DeclaredAt {
+    /** The helper's file, from the project root. */
+    relativeFilePath: string;
+    lineStart: Position;
+    /** In UTF-16 code units. */
+    columnStart: Position;
+}
+/** @inline */
 export interface Annotation {
     type: string;
     description: string | null;

package/dist/values.d.ts

@@ -1,4 +1,5 @@
 import type { Expression, Node } from 'oxc-parser';
+import { type FunctionNode } from './ast.ts';
 export type Value = string | number | boolean | null | undefined | Value[] | {
     [key: string]: Value;
 };
@@ -19,6 +20,15 @@ export declare class Values {
     private readonly bindingsByScope;
     private readonly cache;
     private readonly pending;
+    /** The functions being read at one of their calls, innermost last. */
+    private readonly calls;
+    /**
+     * Runs `read` with a function's parameters bound to the arguments of one call, worked out where the call is, so that
+     * titles and values built from them resolve, as in `test(\`${side} rejects a zero quantity\`)` inside
+     * `validatesQuantity('buy')`. `args` stop at a spread argument, after which no position is known. A missing argument
+     * takes the parameter's default value, worked out in `scopes`, the scopes around the function.
+     */
+    withArguments<T>(fn: FunctionNode, args: readonly Resolved[], scopes: readonly Node[], read: () => T): T;
     /** `scopes` lists the scope nodes around the expression, outermost first. */
     resolve(node: Expression, scopes: readonly Node[]): Resolved;
     /**
@@ -26,10 +36,14 @@ export declare class Values {
      * the file does not declare it, as with globals.
      */
     declarationOf(name: string, scopes: readonly Node[]): Node | null;
+    /** The module a name is imported from where it is used; null when it isn't an import. */
+    importSource(name: string, scopes: readonly Node[]): string | null;
     /** Whether a name refers to a function or class declared in the file. */
     isFunction(name: string, scopes: readonly Node[]): boolean;
     private propertyKey;
     private resolveName;
+    /** A parameter of a function read at one of its calls: the argument given there. */
+    private resolveParameter;
     private resolveConstant;
     private enumMembers;
     private lookup;

package/dist/values.js

@@ -56,6 +56,35 @@ export class Values {
     bindingsByScope = new Map();
     cache = new Map();
     pending = new Set();
+    /** The functions being read at one of their calls, innermost last. */
+    calls = [];
+    /**
+     * Runs `read` with a function's parameters bound to the arguments of one call, worked out where the call is, so that
+     * titles and values built from them resolve, as in `test(\`${side} rejects a zero quantity\`)` inside
+     * `validatesQuantity('buy')`. `args` stop at a spread argument, after which no position is known. A missing argument
+     * takes the parameter's default value, worked out in `scopes`, the scopes around the function.
+     */
+    withArguments(fn, args, scopes, read) {
+        const parameters = new Map();
+        for (const [index, parameter] of fn.params.entries()) {
+            const target = parameter.type === 'AssignmentPattern' ? parameter.left : parameter;
+            if (target.type !== 'Identifier')
+                continue;
+            const argument = args.at(index);
+            if (argument)
+                parameters.set(target.name, () => argument);
+            else if (parameter.type === 'AssignmentPattern') {
+                parameters.set(target.name, () => this.resolve(parameter.right, [...scopes, fn]));
+            }
+        }
+        this.calls.push({ fn, parameters, cache: new Map() });
+        try {
+            return read();
+        }
+        finally {
+            this.calls.pop();
+        }
+    }
     /** `scopes` lists the scope nodes around the expression, outermost first. */
     resolve(node, scopes) {
         const expression = unwrap(node);
@@ -179,6 +208,11 @@ export class Values {
     declarationOf(name, scopes) {
         return this.lookup(name, scopes)?.binding.declaration ?? null;
     }
+    /** The module a name is imported from where it is used; null when it isn't an import. */
+    importSource(name, scopes) {
+        const binding = this.lookup(name, scopes)?.binding;
+        return binding?.kind === 'import' ? binding.source : null;
+    }
     /** Whether a name refers to a function or class declared in the file. */
     isFunction(name, scopes) {
         return this.lookup(name, scopes)?.binding.kind === 'function';
@@ -203,12 +237,19 @@ export class Values {
             case 'import':
                 return { ok: false, importedFrom: binding.source };
             case 'function':
-            case 'other':
                 return UNRESOLVED;
+            case 'other':
+                return this.resolveParameter(name, binding.declaration);
         }
     }
+    /** A parameter of a function read at one of its calls: the argument given there. */
+    resolveParameter(name, fn) {
+        const call = this.calls.findLast((item) => item.fn === fn);
+        return call?.parameters.get(name)?.() ?? UNRESOLVED;
+    }
     resolveConstant(init, scopes) {
-        const cached = this.cache.get(init);
+        const cache = this.calls.at(-1)?.cache ?? this.cache;
+        const cached = cache.get(init);
         if (cached)
             return cached;
         if (this.pending.has(init))
@@ -216,7 +257,7 @@ export class Values {
         this.pending.add(init);
         const resolved = this.resolve(init, scopes);
         this.pending.delete(init);
-        this.cache.set(init, resolved);
+        cache.set(init, resolved);
         return resolved;
     }
     enumMembers(node, scopes) {