@openrewrite/rewrite 8.96.4 → 8.97.0

package/src/recipe.ts

@@ -175,6 +175,11 @@ export interface OptionDescriptor {
     readonly type?: string
 }
 
+/**
+ * @typeParam P The type of the accumulator where scanning data is held until the editing phase. It stays in memory
+ * until the cycle ends, so it should hold values such as coordinates, paths and ids, not trees or other objects of a
+ * type given to registerHeavyweight.
+ */
 export abstract class ScanningRecipe<P> extends Recipe {
     private readonly recipeAccMessage = Symbol("org.openrewrite.recipe.acc");
 

package/src/run.ts

@@ -14,7 +14,7 @@
  * limitations under the License.
  */
 import {ExecutionContext} from "./execution";
-import {rootCursor, SourceFile} from "./tree";
+import {Cursor, rootCursor, SourceFile} from "./tree";
 import {createTwoFilesPatch} from "diff";
 import {TreePrinters} from "./print";
 import {Recipe, ScanningRecipe} from "./recipe";
@@ -83,6 +83,25 @@ async function recursiveOnComplete(recipe: Recipe, ctx: ExecutionContext, recipe
     }
 }
 
+/**
+ * Under this key a test harness puts an {@link AccumulatorListener} on the execution context, which the scheduler
+ * calls with the accumulator of each scanning recipe after the scanning phase and again after the editing phase.
+ */
+export const ACCUMULATOR_LISTENER = "org.openrewrite.test.accumulatorListener";
+
+export type AccumulatorListener =
+    (accumulators: Map<ScanningRecipe<any>, any>, phase: "after scanning" | "after editing") => void;
+
+async function accumulators(recipe: Recipe, recipeLists: RecipeLists, cursor: Cursor,
+                            ctx: ExecutionContext): Promise<Map<ScanningRecipe<any>, any>> {
+    return (await recurseRecipeList(recipe, new Map<ScanningRecipe<any>, any>(), recipeLists, async (r, found) => {
+        if (r instanceof ScanningRecipe && !found.has(r)) {
+            found.set(r, r.accumulator(cursor, ctx));
+        }
+        return found;
+    }))!;
+}
+
 export async function scheduleRun(recipe: Recipe, before: SourceFile[], ctx: ExecutionContext): Promise<RecipeRun> {
     const changeset: Result[] = [];
     for await (const result of scheduleRunStreaming(recipe, before, ctx)) {
@@ -135,13 +154,21 @@ export async function* scheduleRunStreaming(
             // of the recipe list, leaving nested scanners unrun.
             await recurseRecipeList(recipe, b, recipeLists, async (recipe, b2) => {
                 if (recipe instanceof ScanningRecipe) {
-                    await (await recipe.scanner(recipe.accumulator(cursor, ctx))).visit(b2, ctx, cursor);
+                    const scanned = await (await recipe.scanner(recipe.accumulator(cursor, ctx))).visit(b2, ctx, cursor);
+                    if (scanned !== b2 && ctx.getBoolean(ExecutionContext.SCANNING_MUTATION_VALIDATION, false)) {
+                        throw new Error("Record what the scanner finds in the accumulator, and make the edits in " +
+                            `editorWithData(acc). ${recipe.name}'s scanner ${scanned ? "changed" : "deleted"} ` +
+                            `${b2.sourcePath}, and the scanning phase discards edits. A scanner that reuses an ` +
+                            "editing visitor opts out with spec.checkNoEditsInScanningPhase = false.");
+                    }
                 }
                 return b2;
             });
         }
 
         const totalFiles = files.length;
+        const listener: AccumulatorListener | undefined = ctx.messages[ACCUMULATOR_LISTENER];
+        listener?.(await accumulators(recipe, recipeLists, cursor, ctx), "after scanning");
 
         // Phase 2: Collect generated files
         const generated = (await recurseRecipeList(recipe, [] as SourceFile[], recipeLists, async (recipe, generated) => {
@@ -169,6 +196,7 @@ export async function* scheduleRunStreaming(
                 yield new Result(undefined, editedG);
             }
         }
+        listener?.(await accumulators(recipe, recipeLists, cursor, ctx), "after editing");
     } else {
         // For non-scanning recipes, process files immediately as they come in
         let processCount = 0;

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}\``;
+}