@openrewrite/rewrite 8.96.3 → 8.96.5

package/src/test/accumulator-contents.ts

@@ -0,0 +1,194 @@
+/*
+ * Copyright 2025 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import {types} from "util";
+import {AccumulatorListener} from "../run";
+import {Recipe} from "../recipe";
+import {isSourceFile} from "../tree";
+import {heavyweightType} from "../heavyweight";
+import {Type} from "../java";
+import {typeName} from "./probes";
+
+/** Beyond this many objects in one accumulator the walk stops descending. */
+const MAX_OBJECTS = 100_000;
+
+const MAX_PATHS = 5;
+
+interface Finding {
+    readonly path: string
+    readonly what: string
+    readonly phase: string
+}
+
+interface Node {
+    readonly value: object
+    readonly parent?: Node
+    readonly step: string
+}
+
+/**
+ * Finds the heavyweight objects that ScanningRecipe accumulators keep, which are trees and the types
+ * registerHeavyweight registers. An accumulator lives from the first source file scanned until the cycle ends. The
+ * walk reads data properties and built-in collections, and runs no code of the recipe's own.
+ */
+export class AccumulatorContents {
+    /** What each recipe's accumulator keeps, by recipe name and then by the shape of the path to it. */
+    private readonly findings = new Map<string, Map<string, Finding>>();
+
+    readonly listener: AccumulatorListener = (accumulators, phase) => {
+        const walked = new Set<unknown>();
+        for (const [recipe, acc] of accumulators) {
+            if (acc !== null && typeof acc === "object" && !walked.has(acc)) {
+                walked.add(acc);
+                try {
+                    this.walk(recipe.name, acc, phase);
+                } catch {
+                    // an accumulator the walk can't read is left alone
+                }
+            }
+        }
+    };
+
+    assertNoneFound(): void {
+        if (this.findings.size === 0) {
+            return;
+        }
+        const lines = ["A ScanningRecipe's accumulator should keep the values the recipe needs, such as package " +
+        "names, versions, paths and ids, and no heavyweight objects, such as trees, cursors, visitors, execution " +
+        "contexts and dependency models:"];
+        for (const [recipe, found] of this.findings) {
+            lines.push(`  ${recipe} keeps`);
+            const shown = [...found.values()].slice(0, MAX_PATHS);
+            lines.push(...shown.map(f => `    ${f.path} -> ${f.what}, ${f.phase}`));
+            if (found.size > MAX_PATHS) {
+                lines.push(`    and ${found.size - MAX_PATHS} more`);
+            }
+        }
+        lines.push("An accumulator stays in memory from the first source file scanned until the cycle ends, so " +
+            "what it keeps for each source file adds up over a large repository. A NodeResolutionResult can reach " +
+            "the model of a whole dependency tree, while small markers such as NodeRuntime are fine to keep. A " +
+            "recipe that must keep a heavyweight object opts out with spec.checkLightweightAccumulators = false.");
+        throw new Error(lines.join("\n"));
+    }
+
+    /** Breadth first, so that the path to what the accumulator keeps is a short one. */
+    private walk(recipe: string, acc: object, phase: string): void {
+        const visited = new Set<object>();
+        const queue: Node[] = [];
+        let budget = MAX_OBJECTS;
+        const visit = (value: unknown, parent: Node | undefined, step: string) => {
+            if (!walks(value)) {
+                return;
+            }
+            const what = heavyweight(value);
+            if (what) {
+                const path = pathOf({value, parent, step});
+                let found = this.findings.get(recipe);
+                if (!found) {
+                    this.findings.set(recipe, found = new Map());
+                }
+                const shape = `${path.replace(/\[[^\]]*]/g, "[]")} -> ${what}`;
+                if (!found.has(shape)) {
+                    found.set(shape, {path, what, phase});
+                }
+            } else if (budget > 0 && !visited.has(value)) {
+                budget--;
+                visited.add(value);
+                queue.push({value, parent, step});
+            }
+        };
+
+        visit(acc, undefined, "acc");
+        for (let i = 0; i < queue.length; i++) {
+            const node = queue[i];
+            const value = node.value;
+            if (types.isMap(value)) {
+                Map.prototype.forEach.call(value, (v: unknown, k: unknown) => {
+                    if (walks(k) || walks(v)) {
+                        visit(k, node, `[${key(k)}]`);
+                        visit(v, node, `[${key(k)}]`);
+                    }
+                });
+            } else if (types.isSet(value)) {
+                let index = 0;
+                Set.prototype.forEach.call(value, (v: unknown) => visit(v, node, `[${index++}]`));
+            } else {
+                // data properties only, since a getter is code of the recipe's own
+                const array = Array.isArray(value);
+                for (const name of Reflect.ownKeys(value)) {
+                    const descriptor = Reflect.getOwnPropertyDescriptor(value, name);
+                    if (descriptor && "value" in descriptor && !(array && name === "length")) {
+                        visit(descriptor.value, node, step(name, array));
+                    }
+                }
+            }
+        }
+    }
+}
+
+/** Whether the walk looks at a value at all, which it doesn't for primitives and for what refers to no tree. */
+function walks(value: unknown): value is object {
+    return value !== null && typeof value === "object" && !types.isProxy(value) && !types.isPromise(value) &&
+        !types.isWeakMap(value) && !types.isWeakSet(value) && !types.isAnyArrayBuffer(value) &&
+        !types.isArrayBufferView(value) && !types.isDate(value) && !types.isRegExp(value) &&
+        !types.isBoxedPrimitive(value) &&
+        // a recipe lives for the whole run anyway, and type attribution refers to no tree
+        !(value instanceof Recipe) && !Type.isType(value);
+}
+
+/** How to name what the accumulator keeps, when it is a heavyweight object. */
+function heavyweight(value: object): string | undefined {
+    const type = heavyweightType(value);
+    if (type === undefined) {
+        return undefined;
+    } else if (typeof type === "function") {
+        return type.name || "an object of an anonymous class";
+    }
+    return isSourceFile(value) ? `${typeName(type)} ${value.sourcePath}` : typeName(type);
+}
+
+function pathOf(node: Node): string {
+    const steps: string[] = [];
+    for (let n: Node | undefined = node; n; n = n.parent) {
+        steps.push(n.step);
+    }
+    return steps.reverse().join("");
+}
+
+function step(name: string | symbol, array: boolean): string {
+    if (typeof name === "symbol") {
+        return `[${name.toString()}]`;
+    }
+    return array && /^\d+$/.test(name) ? `[${name}]` :
+        /^[A-Za-z_$][\w$]*$/.test(name) ? `.${name}` : `[${JSON.stringify(name)}]`;
+}
+
+/** A map key as the path shows it, without calling code of the recipe's own. */
+function key(k: unknown): string {
+    let shown: string;
+    if (k === null || typeof k !== "object") {
+        shown = typeof k === "symbol" ? k.toString() : String(k);
+    } else if (isSourceFile(k)) {
+        shown = k.sourcePath;
+    } else if (k instanceof Recipe) {
+        shown = k.name;
+    } else if (typeof (k as { kind?: unknown }).kind === "string") {
+        shown = typeName((k as { kind: string }).kind);
+    } else {
+        shown = Object.getPrototypeOf(k)?.constructor?.name || "Object";
+    }
+    return shown.length > 60 ? `${shown.substring(0, 60)}...` : shown;
+}
+

package/src/test/empty-sources.ts

@@ -0,0 +1,99 @@
+/*
+ * Copyright 2025 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type {SourceSpec} from "./rewrite-test";
+import {Recipe} from "../recipe";
+import {ExecutionContext} from "../execution";
+import {SourceFile} from "../tree";
+import {Result} from "../run";
+import {TreePrinters} from "../print";
+import {describeThrown, probeOnce, thrownBy, typeName, withMarkersOf} from "./probes";
+
+/** Runs the recipe on an empty file of each kind it changed, and fails the test if the recipe throws there. */
+export class EmptySources {
+    private readonly changed: Set<SourceFile>;
+
+    constructor(private readonly recipe: Recipe, results: Result[]) {
+        this.changed = new Set(results.filter(r => r.before && r.after !== r.before).map(r => r.before!));
+    }
+
+    async assertNoneThrow(parsed: [SourceSpec<any>, SourceFile][], parseCtx: ExecutionContext,
+                          recipeCtx: ExecutionContext, cycles: number): Promise<void> {
+        const kinds = new Set<string>();
+        for (const [spec, before] of parsed) {
+            const probe = `empty ${before.kind} ${spec.ext}`;
+            if (!this.changed.has(before) || kinds.has(probe)) {
+                continue;
+            }
+            kinds.add(probe);
+            await probeOnce(this.recipe, probe, async () => {
+                const empty = await parseEmpty(before, spec, parseCtx);
+                const thrown = empty ? await thrownBy(this.recipe, [empty], recipeCtx, cycles) : undefined;
+                if (empty && thrown) {
+                    throw new Error(this.message(empty, thrown.error));
+                }
+            });
+        }
+    }
+
+    private message(empty: SourceFile, thrown: unknown): string {
+        return [
+            "Check for the structure the recipe edits before using it, so that it handles an empty file or leaves " +
+            "it unchanged instead of throwing.",
+            `${this.recipe.name} threw when run on an empty ${typeName(empty.kind)} at ${empty.sourcePath}` +
+            `${withMarkersOf(empty.markers.markers)}:`,
+            describeThrown(thrown, "    "),
+            "The test gives the recipe only files that contain what it edits, but repositories also hold empty " +
+            "files and files without that block, such as an empty index.ts, a placeholder tsconfig.json or an " +
+            "empty .eslintrc.yml.",
+            "  - return the tree unchanged when what the visitor assumes is absent: check the kind before a cast " +
+            "(`document.value.kind === Json.Kind.Object`), the length before an index (`cu.statements.length > 0`) " +
+            "and undefined before a dereference (`documents.documents[0]?.block`)",
+            "  - if the recipe adds what is missing, build that content correctly for an empty file too",
+            "  - don't catch the exception to make this pass",
+            "Then add a test with an empty source, such as typescript(\"\"), json(\"\") or yaml(\"\"), that states the " +
+            "intended result."
+        ].join("\n");
+    }
+}
+
+/**
+ * An empty file at the source's path, with the markers that describe the source's project, or undefined for a kind of
+ * file that can't be empty.
+ */
+async function parseEmpty(before: SourceFile, spec: SourceSpec<any>,
+                          parseCtx: ExecutionContext): Promise<SourceFile | undefined> {
+    // a file its parser resolves a project from, such as a package.json, can't be empty
+    if (before.markers.markers.some(m => m.kind.endsWith("ResolutionResult"))) {
+        return undefined;
+    }
+    let empty: SourceFile;
+    try {
+        const parsed: SourceFile[] = [];
+        for await (const sourceFile of spec.parser(parseCtx).parse({text: "", sourcePath: before.sourcePath})) {
+            parsed.push(sourceFile);
+        }
+        // some kinds of file can't be empty
+        if (parsed.length !== 1 || parsed[0].kind !== before.kind || await TreePrinters.print(parsed[0]) !== "") {
+            return undefined;
+        }
+        empty = parsed[0];
+    } catch {
+        return undefined;
+    }
+    const present = new Set(empty.markers.markers.map(m => m.kind));
+    const added = before.markers.markers.filter(m => !present.has(m.kind));
+    return {...empty, markers: {...empty.markers, markers: [...empty.markers.markers, ...added]}};
+}

package/src/test/formatting-scope.ts

@@ -0,0 +1,231 @@
+/*
+ * Copyright 2025 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as path from "path";
+import {Recipe} from "../recipe";
+import {Cursor, isSourceFile, SourceFile, Tree} from "../tree";
+import {Result} from "../run";
+import {TreePrinters} from "../print";
+import {UUID} from "../uuid";
+import {J} from "../java";
+import {JavaScriptVisitor} from "../javascript";
+import type {FormattingListener} from "../javascript/format";
+
+interface Request {
+    readonly tree: Tree
+    readonly sourceFile: UUID
+    readonly callSite: string
+}
+
+/**
+ * Finds recipes that auto-format a whole source file or class that existed before the run. Test inputs are usually
+ * formatted already, so the reformatting this causes on real code rarely shows in an expected output.
+ */
+export class FormattingScope implements FormattingListener {
+    private readonly requests: Request[] = [];
+    private readonly requested = new Set<Tree>();
+
+    constructor(private readonly recipe: Recipe) {
+    }
+
+    onFormat(tree: Tree, stopAfter: Tree | undefined, cursor: Cursor | undefined): void {
+        if (stopAfter || !isWhole(tree) || this.requested.has(tree)) {
+            return;
+        }
+        this.requested.add(tree);
+        const sourceFile = isSourceFile(tree) ? tree : cursor?.firstEnclosing(isSourceFile);
+        const site = sourceFile && callSite(new Error().stack ?? "");
+        if (sourceFile && site) {
+            this.requests.push({tree, sourceFile: sourceFile.id, callSite: site});
+        }
+    }
+
+    async assertFormattedOnlyWhatChanged(results: Result[]): Promise<void> {
+        if (this.requests.length === 0 || await isFormatter(this.recipe)) {
+            return;
+        }
+        const treesByFile = new Map<UUID, Map<UUID, Tree>>();
+        const found = new Map<string, Set<string>>();
+        for (const request of this.requests) {
+            const result = results.find(r => r.before?.id === request.sourceFile && r.after && r.after !== r.before);
+            if (!result || await onlyWhitespaceChanged(result)) {
+                continue;
+            }
+            const before = result.before!;
+            let trees = treesByFile.get(before.id);
+            if (!trees) {
+                treesByFile.set(before.id, trees = await treesById(before));
+            }
+            const original = trees.get(request.tree.id);
+            if (original && !await holdsNoneOfItsChildren(original, request.tree)) {
+                let targets = found.get(request.callSite);
+                if (!targets) {
+                    found.set(request.callSite, targets = new Set());
+                }
+                targets.add(`${describe(request.tree)} of ${before.sourcePath}`);
+            }
+        }
+        if (found.size > 0) {
+            throw new Error(this.message(found));
+        }
+    }
+
+    private message(found: Map<string, Set<string>>): string {
+        return [
+            "Format only what the recipe changed, not the whole class or file around it. These calls of " +
+            `${this.recipe.name} auto-formatted a whole file or class that existed before the run, with no stopAfter:`,
+            ...[...found].flatMap(([site, targets]) => [`  ${site}`, ...[...targets].map(target => `    ${target}`)]),
+            "That rewrites the whitespace of code the recipe did not change. Test inputs are usually formatted " +
+            "already, so expected outputs rarely show it, but on real code the diff will carry unrelated " +
+            "reformatting. Instead:",
+            "  - format the element you created or replaced: maybeAutoFormat(original, changed, ctx) on that " +
+            "element, or autoFormat(newElement, ctx, undefined, cursor) with a cursor on its parent",
+            "  - when a new element only formats right inside its container, format a copy of the container that " +
+            "holds just the new element, and add the formatted element to the original",
+            "  - after changing a declaration's decorators or modifiers, stop after its header: " +
+            "maybeAutoFormat(c, updated, ctx, updated.name, this.cursor.parent)",
+            "  - when you remove an element, give its prefix to the element that takes its place",
+            "  - re-indent statements you moved with autoIndent(..) rather than autoFormat",
+            "  - a template already formats what it inserts, so drop the extra call",
+            "Recipes named with a `format` segment, such as org.openrewrite.javascript.format.auto-format, are exempt. " +
+            "Any other recipe whose purpose is formatting opts out with spec.checkMinimalFormatting = false."
+        ].join("\n");
+    }
+}
+
+/** A source file or a class. */
+function isWhole(tree: Tree): boolean {
+    return isSourceFile(tree) || tree.kind === J.Kind.ClassDeclaration;
+}
+
+interface Frame {
+    readonly fn: string
+    readonly location: string
+}
+
+/**
+ * The code that asked for the format, from the stack of the request, or undefined when that is a formatter, a
+ * template, or the scheduler running a recipe whose own visitor is a formatter.
+ */
+function callSite(stack: string): string | undefined {
+    const frames: Frame[] = stack.split("\n").map(line => line.trim()).filter(line => line.startsWith("at "))
+        .map(line => {
+            const m = /^at (?:async )?(?:(.*?) \((.*)\)|(.*))$/.exec(line)!;
+            return {fn: m[1] ?? "", location: (m[2] ?? m[3]).split(process.cwd() + path.sep).join("")};
+        });
+    // the listener, the formatter and the helpers that run it
+    let i = frames.findIndex(f => /\.visit$/.test(f.fn) && inFormat(f));
+    if (i < 0) {
+        return undefined;
+    }
+    let helper: string | undefined;
+    for (i++; i < frames.length && inFormat(frames[i]) && /^(maybeAutoFormat|autoFormat)$/.test(frames[i].fn); i++) {
+        helper = frames[i].fn;
+    }
+    // a precondition and a scanning recipe's editor hand the tree on to the visitor they wrap, after an await
+    while (i < frames.length && (isWrapper(frames[i]) || frames[i].location.startsWith("node:"))) {
+        i++;
+    }
+    const caller = frames[i];
+    if (!caller) {
+        return undefined;
+    } else if (/(^|[\\/])(src|dist)[\\/]visitor\.[jt]s:/.test(caller.location)) {
+        // the visitor that asked is gone from the stack by the time its after-visitors run
+        return "A visitor's afterVisit.push(new AutoformatVisitor()) ran on";
+    } else if (inFormat(caller) || /[\\/]templating[\\/]/.test(caller.location) ||
+        /(^|[\\/])(src|dist)[\\/]run\.[jt]s:/.test(caller.location)) {
+        return undefined;
+    }
+    return `${caller.fn || "<anonymous>"} (${caller.location}) ${helper ? `called ${helper} on` : "ran an AutoformatVisitor on"}`;
+}
+
+function inFormat(frame: Frame): boolean {
+    return /[\\/]format[\\/]/.test(frame.location);
+}
+
+/** The visit of a precondition or of a scanning recipe's editor, which runs the visitor it wraps. */
+function isWrapper(frame: Frame): boolean {
+    return /\.visit$/.test(frame.fn) && /(^|[\\/])(src|dist)[\\/](preconditions|recipe)\.[jt]s:/.test(frame.location);
+}
+
+/** A formatting recipe may format whole files, and so may the recipes run alongside it. */
+async function isFormatter(recipe: Recipe): Promise<boolean> {
+    if (/(^|\.)format\./.test(recipe.name)) {
+        return true;
+    }
+    for (const child of await recipe.recipeList()) {
+        if (await isFormatter(child)) {
+            return true;
+        }
+    }
+    return false;
+}
+
+async function onlyWhitespaceChanged(result: Result): Promise<boolean> {
+    const [before, after] = [await TreePrinters.print(result.before!), await TreePrinters.print(result.after!)];
+    return before.replace(/\s+/g, "") === after.replace(/\s+/g, "");
+}
+
+async function treesById(sourceFile: SourceFile): Promise<Map<UUID, Tree>> {
+    const trees = new Map<UUID, Tree>();
+    await new class extends JavaScriptVisitor<undefined> {
+        protected override async preVisit(tree: J): Promise<J | undefined> {
+            trees.set(tree.id, tree);
+            return tree;
+        }
+    }().visit(sourceFile, undefined);
+    return trees;
+}
+
+/**
+ * A tree formatted with none of the children it had reformats no existing code below it: a class with its body
+ * emptied to be put back afterwards, or a copy of a container holding only a new element. A tree that had no children
+ * to begin with would format them on real code.
+ */
+async function holdsNoneOfItsChildren(original: Tree, formatted: Tree): Promise<boolean> {
+    const children = await childrenOf(original);
+    if (children.size === 0) {
+        return false;
+    }
+    for (const child of await childrenOf(formatted)) {
+        if (children.has(child)) {
+            return false;
+        }
+    }
+    return true;
+}
+
+/** The members of a class's body, or the trees directly below any other tree. */
+async function childrenOf(tree: Tree): Promise<Set<UUID>> {
+    if (tree.kind === J.Kind.ClassDeclaration) {
+        return new Set((tree as J.ClassDeclaration).body.statements.map(s => s.element.id));
+    }
+    const children = new Set<UUID>();
+    await new class extends JavaScriptVisitor<undefined> {
+        protected override async preVisit(t: J): Promise<J | undefined> {
+            if (t !== tree) {
+                children.add(t.id);
+                this.stopAfterPreVisit();
+            }
+            return t;
+        }
+    }().visit(tree, undefined);
+    return children;
+}
+
+/** Reads as "all" or "class `A`". */
+function describe(tree: Tree): string {
+    return isSourceFile(tree) ? "all" : `class \`${(tree as J.ClassDeclaration).name.simpleName}\``;
+}

package/src/test/probes.ts

@@ -0,0 +1,156 @@
+/*
+ * Copyright 2025 the original author or authors.
+ * <p>
+ * Licensed under the Moderne Source Available License (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ * <p>
+ * https://docs.moderne.io/licensing/moderne-source-available-license
+ * <p>
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import * as path from "path";
+import {Recipe} from "../recipe";
+import {ExecutionContext} from "../execution";
+import {SourceFile} from "../tree";
+import {ACCUMULATOR_LISTENER, scheduleRun} from "../run";
+import {RecipeRunError} from "../visitor";
+import {DATA_TABLE_STORE} from "../data-table";
+import {Marker} from "../markers";
+
+/** Messages that belong to the test's own run. */
+const NOT_COPIED = new Set<string | symbol>([DATA_TABLE_STORE, ACCUMULATOR_LISTENER]);
+
+/**
+ * Probes of recipes that resolve dependencies take seconds each, so a recipe stops being probed in this process once
+ * its probes have taken this long.
+ */
+const TIME_CAP_MS = 20_000;
+
+/** How long each recipe's probes have taken in this process, by {@link timeCapKey}. */
+const PROBE_MS = new Map<string, number>();
+
+/** The probes each recipe class ran, which a process runs once whether they pass or fail. */
+const PROBED = new WeakMap<Function, Set<string>>();
+
+/**
+ * Runs `run`, a probe of the recipe on what `probe` names, unless this process ran that probe before or the recipe's
+ * probes have taken the time cap, and charges the recipe the time it takes.
+ */
+export async function probeOnce(recipe: Recipe, probe: string, run: () => Promise<void>): Promise<void> {
+    if ((PROBE_MS.get(await timeCapKey(recipe)) ?? 0) > TIME_CAP_MS) {
+        return;
+    }
+    let probed = PROBED.get(recipe.constructor);
+    if (!probed) {
+        PROBED.set(recipe.constructor, probed = new Set());
+    }
+    const key = await probeKey(recipe, probe);
+    if (probed.has(key)) {
+        return;
+    }
+    probed.add(key);
+    const start = performance.now();
+    try {
+        await run();
+    } finally {
+        await charge(recipe, performance.now() - start);
+    }
+}
+
+/** Adds `ms` to the time the recipe's probes have taken in this process. */
+export async function charge(recipe: Recipe, ms: number): Promise<void> {
+    const key = await timeCapKey(recipe);
+    PROBE_MS.set(key, (PROBE_MS.get(key) ?? 0) + ms);
+}
+
+/**
+ * What a recipe's probes share a time cap by: its name, and for a recipe with a recipe list its children's keys too,
+ * since a composite a test declares has one name whatever it runs.
+ */
+async function timeCapKey(recipe: Recipe): Promise<string> {
+    let children: Recipe[];
+    try {
+        children = await recipe.recipeList();
+    } catch {
+        return recipe.name;
+    }
+    const keys: string[] = [];
+    for (const child of children) {
+        keys.push(await timeCapKey(child));
+    }
+    return keys.length === 0 ? recipe.name : `${recipe.name}[${keys.join(",")}]`;
+}
+
+async function probeKey(recipe: Recipe, probe: string): Promise<string> {
+    try {
+        return `${JSON.stringify(await recipe.descriptor())}\0${probe}`;
+    } catch {
+        return `${recipe.name}\0${probe}`;
+    }
+}
+
+/** The error the recipe threw when run on `sources` for up to `cycles` cycles, if it threw. */
+export async function thrownBy(recipe: Recipe, sources: SourceFile[], recipeCtx: ExecutionContext,
+                               cycles: number): Promise<{ error: unknown } | undefined> {
+    const messages: { [key: string | symbol]: any } = {};
+    for (const key of Reflect.ownKeys(recipeCtx.messages)) {
+        if (!NOT_COPIED.has(key)) {
+            messages[key] = recipeCtx.messages[key];
+        }
+    }
+    const ctx = new ExecutionContext(messages);
+    let current = sources;
+    try {
+        for (let cycle = 1; cycle <= cycles; cycle++) {
+            const changeset = (await scheduleRun(recipe, current, ctx)).changeset;
+            if (changeset.every(r => r.before === r.after)) {
+                break;
+            }
+            current = changeset.filter(r => r.after).map(r => r.after!);
+        }
+    } catch (error) {
+        return {error};
+    }
+    return undefined;
+}
+
+/**
+ * The error the recipe threw, with the first line of its message and the first frame of its stack, and when that
+ * frame is in a dependency, the first frame that isn't.
+ */
+export function describeThrown(thrown: unknown, indent: string): string {
+    const cause = thrown instanceof RecipeRunError ? thrown.cause : thrown;
+    if (!(cause instanceof Error)) {
+        return `${indent}${String(cause)}`;
+    }
+    const firstLine = cause.message.trim().split("\n")[0];
+    let description = `${indent}${cause.name}${firstLine ? `: ${firstLine.length > 200 ?
+        `${firstLine.substring(0, 200)}...` : firstLine}` : ""}`;
+    const frames = (cause.stack ?? "").split("\n").map(line => line.trim())
+        .filter(line => line.startsWith("at ") && !/\(node:|^at node:|<anonymous>/.test(line))
+        .map(line => line.split(process.cwd() + path.sep).join(""));
+    if (frames.length > 0) {
+        description += `\n${indent}    ${frames[0]}`;
+        const own = frames.find(frame => !frame.includes("node_modules"));
+        if (own && own !== frames[0]) {
+            description += `\n${indent}    ${own}`;
+        }
+    }
+    return description;
+}
+
+/** Reads as " with the markers of the test's source (Autodetect, PrettierStyle)", or as nothing. */
+export function withMarkersOf(markers: Marker[]): string {
+    const kinds = [...new Set(markers.map(m => typeName(m.kind)))];
+    return kinds.length === 0 ? "" : ` with the markers of the test's source (${kinds.join(", ")})`;
+}
+
+/** Reads as "PlainText" or "JS.CompilationUnit". */
+export function typeName(kind: string): string {
+    return kind.replace(/^.*\./, "").replace(/\$/g, ".");
+}