@openrewrite/rewrite 8.96.4 → 8.96.5

package/src/test/rewrite-test.ts

@@ -19,15 +19,24 @@ import {noopVisitor, TreeVisitor} from "../visitor";
 import {Parser} from "../parser";
 import {MarkerPrinter, PrintOutputCapture, TreePrinters} from "../print";
 import {Cursor, isTree, rootCursor, SourceFile} from "../tree";
-import {Result, scheduleRun} from "../run";
+import {ACCUMULATOR_LISTENER, Result, scheduleRun} from "../run";
 import {mapAsync, trimIndent} from "../util";
 import {isParseError, ParseErrorKind} from "../parse-error";
 import {Marker, Markers, MarkersKind, ParseExceptionResult} from "../markers";
 import {isNamedStyles} from "../style";
 import {JavaScriptVisitor} from "../javascript";
+import {listenToFormatting} from "../javascript/format";
 import {attributionHint, dumpTypesIfRequested} from "../javascript/type-report";
 import {J, Type} from "../java";
 import {DATA_TABLE_STORE, InMemoryDataTableStore} from "../data-table";
+import * as path from "path";
+import {AccumulatorContents} from "./accumulator-contents";
+import {EmptySources} from "./empty-sources";
+import {UnparsedSources} from "./unparsed-sources";
+import {TreeShapes} from "./tree-shapes";
+import {FormattingScope} from "./formatting-scope";
+import {RpcRecipe} from "../rpc/recipe";
+import {DelegatingRecipe} from "../rpc/java-recipe";
 
 export interface SourceSpec<T extends SourceFile> {
     kind: string,
@@ -45,6 +54,11 @@ interface RecipeSpecConfiguration {
     checkParsePrintIdempotence: boolean;
     allowEmptyDiff: boolean;
     checkReportingMarkersOnly: boolean;
+    checkExecutionContextUnchanged: boolean;
+    checkNoEditsInScanningPhase: boolean;
+    checkLightweightAccumulators: boolean;
+    checkParserShapedTrees: boolean;
+    checkMinimalFormatting: boolean;
     cycles?: number;
     expectedCyclesThatMakeChanges?: number;
     recipe: Recipe;
@@ -62,6 +76,33 @@ export class RecipeSpec {
      */
     checkReportingMarkersOnly: boolean = true
 
+    /**
+     * Fails a run whose recipe puts a message on the execution context, which every recipe and source file in a run
+     * shares.
+     */
+    checkExecutionContextUnchanged: boolean = true
+
+    /** Fails a run whose ScanningRecipe's scanner edits a tree, which the scanning phase discards. */
+    checkNoEditsInScanningPhase: boolean = true
+
+    /**
+     * Fails a run whose ScanningRecipe's accumulator keeps a tree, cursor, visitor, execution context, dependency model
+     * or other type given to registerHeavyweight, which would stay in memory all cycle.
+     */
+    checkLightweightAccumulators: boolean = true
+
+    /**
+     * Fails a run whose output holds a node that the source's parser builds differently from the text it prints, such
+     * as a J.Identifier where the parser makes a J.Literal of `null`.
+     */
+    checkParserShapedTrees: boolean = true
+
+    /**
+     * Fails a run whose recipe auto-formats a whole source file or class that existed before the run, instead of only
+     * what it changed.
+     */
+    checkMinimalFormatting: boolean = true
+
     /**
      * The cycles to run, by default one more than {@link expectedCyclesThatMakeChanges} and at least two. The
      * cycles after the expected ones, and a run on a fresh parse of the output, fail the test if they change
@@ -114,6 +155,11 @@ export class RecipeSpec {
             checkParsePrintIdempotence: this.checkParsePrintIdempotence,
             allowEmptyDiff: this.allowEmptyDiff,
             checkReportingMarkersOnly: this.checkReportingMarkersOnly,
+            checkExecutionContextUnchanged: this.checkExecutionContextUnchanged,
+            checkNoEditsInScanningPhase: this.checkNoEditsInScanningPhase,
+            checkLightweightAccumulators: this.checkLightweightAccumulators,
+            checkParserShapedTrees: this.checkParserShapedTrees,
+            checkMinimalFormatting: this.checkMinimalFormatting,
             cycles: this.cycles,
             expectedCyclesThatMakeChanges: this.expectedCyclesThatMakeChanges,
             recipe: this.recipe,
@@ -217,21 +263,43 @@ export class RecipeSpec {
         }
 
         this.recipeExecutionContext.messages[DATA_TABLE_STORE] = new InMemoryDataTableStore();
+        this.recipeExecutionContext.messages[ExecutionContext.SCANNING_MUTATION_VALIDATION] =
+            this.checkNoEditsInScanningPhase;
+        const accumulatorContents = this.checkLightweightAccumulators ? new AccumulatorContents() : undefined;
+        this.recipeExecutionContext.messages[ACCUMULATOR_LISTENER] = accumulatorContents?.listener;
+        const contextWrites = this.checkExecutionContextUnchanged ? new ExecutionContextWrites() : undefined;
+        const runContext = (ctx: ExecutionContext) => contextWrites?.watch(ctx) ?? ctx;
         const expectedCycles = this.expectedCyclesThatMakeChanges ?? 1;
         const cycles = this.cycles ?? Math.max(2, expectedCycles + 1);
-        const {changeset, unsettled} = await this.runCycles(allParsed.map(([_, sourceFile]) => sourceFile),
-            cycles, expectedCycles);
+        const formattingScope = this.checkMinimalFormatting ? new FormattingScope(this.recipe) : undefined;
+        const run = () => this.runCycles(allParsed.map(([_, sourceFile]) => sourceFile), cycles, expectedCycles,
+            runContext);
+        const {changeset, unsettled} = formattingScope ? await listenToFormatting(formattingScope, run) : await run();
+        contextWrites?.assertNone(this.recipe);
 
         this.expectNoUnexpectedGeneratedFiles(flattenedSpecs, changeset);
         this.checkReportingMarkersOnly && await this.expectNoAddedMarkers(flattenedSpecs, allParsed, changeset);
+        accumulatorContents?.assertNoneFound();
         await this.expectResultsToMatchAfter(flattenedSpecs, changeset, allParsed);
         await this.expectGeneratedFiles(flattenedSpecs, changeset);
         if (unsettled) {
             await this.expectNoFurtherChanges(unsettled.changes,
                 `Expected recipe to complete in ${pluralCycles(expectedCycles)}, but cycle ${unsettled.cycle} changed`);
         }
-        cycles > expectedCycles && await this.expectStableOnFreshParse(flattenedSpecs, allParsed, changeset);
+        await formattingScope?.assertFormattedOnlyWhatChanged(changeset);
+        const changed = changeset.some(r => r.before !== r.after);
+        const freshParse = changed && (cycles > expectedCycles || this.checkParserShapedTrees) ?
+            await this.freshParse(flattenedSpecs, allParsed, changeset) : new Map<SourceFile, SourceFile>();
+        this.checkParserShapedTrees && await new TreeShapes(this.recipe).assertParserShaped(changeset, freshParse);
+        cycles > expectedCycles && await this.expectStableOnFreshParse(changeset, freshParse, runContext);
+        contextWrites?.assertNone(this.recipe);
         await this.expectDataTables();
+        if (changeset.some(r => r.before && r.after !== r.before) && await isProbed(this.recipe)) {
+            await new EmptySources(this.recipe, changeset)
+                .assertNoneThrow(allParsed, this.executionContext, this.recipeExecutionContext, cycles);
+            await new UnparsedSources(this.recipe, changeset)
+                .assertNoneThrow(allParsed.map(([_, sourceFile]) => sourceFile), this.recipeExecutionContext, cycles);
+        }
     }
 
     private async expectDataTables() {
@@ -247,7 +315,8 @@ export class RecipeSpec {
         }
     }
 
-    private async runCycles(sources: SourceFile[], cycles: number, expectedCycles: number):
+    private async runCycles(sources: SourceFile[], cycles: number, expectedCycles: number,
+                            runContext: (ctx: ExecutionContext) => ExecutionContext):
         Promise<{ changeset: Result[], unsettled?: { cycle: number, changes: Result[] } }> {
         const lineages: { origin?: SourceFile, latest?: SourceFile }[] = sources.map(s => ({origin: s, latest: s}));
         const changesetOf = () => lineages.map(({origin, latest}) => new Result(origin, latest));
@@ -255,7 +324,7 @@ export class RecipeSpec {
         let cyclesThatMadeChanges = 0;
         for (let cycle = 1; cycle <= cycles; cycle++) {
             const live = lineages.filter(l => l.latest).map(l => l.latest!);
-            const ctx = cycle === 1 ? this.recipeExecutionContext : this.laterRunContext();
+            const ctx = runContext(cycle === 1 ? this.recipeExecutionContext : this.laterRunContext());
             const changes = (await scheduleRun(this.recipe, live, ctx)).changeset.filter(r => r.before !== r.after);
             if (changes.length === 0) {
                 break;
@@ -319,14 +388,11 @@ export class RecipeSpec {
     }
 
     /**
-     * Code that the next run reads is parsed from the printed output, not the LST this run produced, and a
-     * recipe that recognizes its own output only by the shape of that LST changes it again.
+     * A fresh parse, by the parser of its spec, of the text each source the recipe left prints, parsing the sources
+     * of one kind together so that they can refer to one another. A parser that throws leaves its sources out.
      */
-    private async expectStableOnFreshParse(specs: SourceSpec<any>[], parsed: [SourceSpec<any>, SourceFile][],
-                                           changeset: Result[]) {
-        if (!changeset.some(r => r.before !== r.after)) {
-            return;
-        }
+    private async freshParse(specs: SourceSpec<any>[], parsed: [SourceSpec<any>, SourceFile][],
+                             changeset: Result[]): Promise<Map<SourceFile, SourceFile>> {
         const finals = changeset.filter(r => r.after).map(({before, after}): [SourceSpec<any> | undefined, SourceFile] => [
             before ? parsed.find(([_, sourceFile]) => sourceFile === before)?.[0] :
                 specs.find(s => s.path === after!.sourcePath),
@@ -344,22 +410,39 @@ export class RecipeSpec {
             let i = 0;
             try {
                 for await (const reparsed of group[0][0]!.parser(this.executionContext).parse(...inputs)) {
-                    if (!isParseError(reparsed) && await printSanitized(reparsed) === inputs[i].text) {
-                        // What the source file carries, like its styles, comes from outside its text
-                        reparsedByFinal.set(group[i][1], {...reparsed, markers: group[i][1].markers});
-                    }
-                    i++;
+                    reparsedByFinal.set(group[i++][1], reparsed);
                 }
             } catch {
+                // the sources it didn't get to are left out
+            }
+        }
+        return reparsedByFinal;
+    }
+
+    /**
+     * Code that the next run reads is parsed from the printed output, not the LST this run produced, and a
+     * recipe that recognizes its own output only by the shape of that LST changes it again.
+     */
+    private async expectStableOnFreshParse(changeset: Result[], freshParse: Map<SourceFile, SourceFile>,
+                                           runContext: (ctx: ExecutionContext) => ExecutionContext) {
+        let reparsedAny = false;
+        const sources: SourceFile[] = [];
+        for (const after of changeset.filter(r => r.after).map(r => r.after!)) {
+            const reparsed = freshParse.get(after);
+            if (reparsed && !isParseError(reparsed) && await printSanitized(reparsed) === await printSanitized(after)) {
+                // What the source file carries, like its styles, comes from outside its text
+                sources.push({...reparsed, markers: after.markers});
+                reparsedAny = true;
+            } else {
                 // files that do not parse again keep the LST the recipe produced
+                sources.push(after);
             }
         }
-        if (reparsedByFinal.size === 0) {
+        if (!reparsedAny) {
             return;
         }
 
-        const sources = finals.map(([_, sourceFile]) => reparsedByFinal.get(sourceFile) ?? sourceFile);
-        const changes = (await scheduleRun(this.recipe, sources, this.laterRunContext())).changeset
+        const changes = (await scheduleRun(this.recipe, sources, runContext(this.laterRunContext()))).changeset
             .filter(r => r.before !== r.after);
         await this.expectNoFurtherChanges(changes, "Running the recipe on a fresh parse of its output changed", true);
     }
@@ -501,7 +584,7 @@ export class RecipeSpec {
 
     private async expectGeneratedFiles(specs: SourceSpec<any>[], changeset: Result[]) {
         for (const spec of specs) {
-            if (spec.before) {
+            if (spec.before !== null) {
                 continue;
             }
             if (!spec.after) {
@@ -513,7 +596,7 @@ export class RecipeSpec {
     }
 
     private expectNoUnexpectedGeneratedFiles(specs: SourceSpec<any>[], changeset: Result[]) {
-        const expectedPaths = new Set(specs.filter(spec => !spec.before).map(spec => spec.path));
+        const expectedPaths = new Set(specs.filter(spec => spec.before === null).map(spec => spec.path));
         const unexpected = changeset.filter(c => !c.before && c.after && !expectedPaths.has(c.after.sourcePath));
         if (unexpected.length > 0) {
             throw new Error([
@@ -554,7 +637,7 @@ export class RecipeSpec {
         let unnamed = 0;
         const before: [SourceSpec<any>, { text: string, sourcePath: string }][] = [];
         for (const spec of specs) {
-            if (spec.before) {
+            if (spec.before !== null) {
                 const sourcePath = spec.path || `source-${unnamed++}.${spec.ext}`;
                 before.push([spec, {text: dedent(spec.before), sourcePath: sourcePath}]);
             }
@@ -587,6 +670,76 @@ class ValidateWhitespaceVisitor extends JavaScriptVisitor<ExecutionContext> {
     }
 }
 
+/** Whether the framework puts `key` on the execution context of a run itself. */
+function isFrameworkMessage(key: string | symbol): boolean {
+    return key === DATA_TABLE_STORE || key === ExecutionContext.REQUIRE_PRINT_EQUALS_INPUT;
+}
+
+/** Records the messages that a recipe puts on the execution context of its run, with the code that put each. */
+class ExecutionContextWrites {
+    private readonly writes = new Map<string | symbol, string | undefined>();
+
+    /** A view of `ctx` whose messages record what is put on them, and that otherwise acts as `ctx`. */
+    watch(ctx: ExecutionContext): ExecutionContext {
+        const record = (key: string | symbol) => {
+            if (!isFrameworkMessage(key) && !this.writes.has(key)) {
+                this.writes.set(key, callerFrame());
+            }
+        };
+        const messages = new Proxy(ctx.messages, {
+            set(target, key, value) {
+                record(key);
+                return Reflect.set(target, key, value);
+            },
+            defineProperty(target, key, attributes) {
+                record(key);
+                return Reflect.defineProperty(target, key, attributes);
+            }
+        });
+        return Object.create(ctx, {messages: {value: messages, enumerable: true, writable: true}});
+    }
+
+    assertNone(recipe: Recipe): void {
+        if (this.writes.size === 0) {
+            return;
+        }
+        throw new Error([
+            "Keep state that spans source files in a ScanningRecipe's accumulator, and state within one source file " +
+            "in cursor messages, with this.cursor.messages.set(key, value). " +
+            `${recipe.name} put messages on the ExecutionContext, which every recipe and source file in a run ` +
+            "shares, so what it keeps there leaks into the others:",
+            ...[...this.writes].map(([key, frame]) =>
+                `  ${typeof key === "symbol" ? key.toString() : JSON.stringify(key)}${frame ? ` at ${frame}` : ""}`),
+            "A recipe that must change the ExecutionContext opts out with spec.checkExecutionContextUnchanged = false."
+        ].join("\n"));
+    }
+}
+
+/** The first frame of the stack outside the harness and the runtime, relative to the working directory. */
+function callerFrame(): string | undefined {
+    const frame = (new Error().stack ?? "").split("\n").slice(1)
+        .map(line => line.trim().replace(/^at (async )?/, ""))
+        .find(line => !/[\\/]test[\\/]rewrite-test\.[jt]s:|<anonymous>|^node:/.test(line));
+    return frame?.split(process.cwd() + path.sep).join("");
+}
+
+/**
+ * Whether the recipe is run on sources the test doesn't give it, which a recipe isn't when it or one in its recipe list
+ * is the harness's stand-in for a visitor, or runs in Java, whose harness probes it.
+ */
+async function isProbed(recipe: Recipe): Promise<boolean> {
+    if (recipe instanceof NoopRecipe || recipe instanceof AdHocRecipe || recipe instanceof RpcRecipe ||
+        recipe instanceof DelegatingRecipe) {
+        return false;
+    }
+    for (const child of await recipe.recipeList()) {
+        if (!await isProbed(child)) {
+            return false;
+        }
+    }
+    return true;
+}
+
 /** Without the comments that search results and markup print as. */
 function printSanitized(sourceFile: SourceFile): Promise<string> {
     return TreePrinters.printer(sourceFile).print(sourceFile, new PrintOutputCapture(MarkerPrinter.SANITIZED));

package/src/test/tree-shapes.ts

@@ -0,0 +1,332 @@
+/*
+ * 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 {Recipe} from "../recipe";
+import {Cursor, isTree, rootCursor, SourceFile, Tree} from "../tree";
+import {Result} from "../run";
+import {MarkerPrinter, PrintOutputCapture, TreePrinters} from "../print";
+import {isParseError} from "../parse-error";
+import {MarkersKind, ParseExceptionResult} from "../markers";
+import {TreeVisitor} from "../visitor";
+import {J} from "../java";
+import {JavaScriptVisitor, JS} from "../javascript";
+import {Json, JsonVisitor} from "../json";
+import {Yaml, YamlVisitor} from "../yaml";
+import {typeName} from "./probes";
+
+const MAX_PER_FILE = 5;
+const SNIPPET_LENGTH = 60;
+const STRICT_NUMBER = /^-?(0|[1-9][0-9]*)(\.[0-9]+)?([eE][+-]?[0-9]+)?$/;
+
+/** How the check reads the trees of a language, as Java's `TreeShapeValidationService` does. */
+interface Language {
+    /** The visitor of the language, whose order of visiting the check compares nodes in. */
+    readonly visitor: abstract new () => TreeVisitor<any, any>
+
+    /** What tells a node apart from another of its kind with the same children, such as an identifier's name. */
+    value(tree: Tree): string | undefined
+
+    /** Whether the comparison leaves out a node and what it holds, as with an empty element the parser adds. */
+    skip(tree: Tree): boolean
+
+    /** What a node has that the parser accepts but the language doesn't, such as a duplicate key. */
+    invalid(tree: Tree): string[]
+}
+
+let languages: { [kind: string]: Language } | undefined;
+
+/**
+ * The language of a source file of `kind`, from a table built on first use, since the modules of the languages import
+ * the harness and may still be loading when it loads.
+ */
+function languageOf(kind: string): Language | undefined {
+    languages ??= {
+        [JS.Kind.CompilationUnit]: {
+            visitor: JavaScriptVisitor,
+            value: javaScriptValue,
+            skip: tree => tree.kind === J.Kind.Empty,
+            invalid: () => []
+        },
+        [Json.Kind.Document]: {
+            visitor: JsonVisitor,
+            value: jsonValue,
+            skip: tree => tree.kind === Json.Kind.Empty,
+            invalid: jsonInvalid
+        },
+        [Yaml.Kind.Documents]: {
+            visitor: YamlVisitor,
+            value: yamlValue,
+            skip: () => false,
+            invalid: yamlInvalid
+        }
+    };
+    return languages[kind];
+}
+
+interface Node {
+    readonly tree: Tree
+    readonly cursor: Cursor
+    readonly children: Node[]
+}
+
+/**
+ * Finds nodes in a recipe's output that its parser builds differently from the text they print, which recipes that
+ * run after it don't match the way they match parsed code.
+ */
+export class TreeShapes {
+    constructor(private readonly recipe: Recipe) {
+    }
+
+    /** @param freshParse The fresh parse of the text each source the recipe left prints. */
+    async assertParserShaped(results: Result[], freshParse: Map<SourceFile, SourceFile>): Promise<void> {
+        const found: string[] = [];
+        for (const {before, after} of results) {
+            const language = after && languageOf(after.kind);
+            if (!after || after === before || !language) {
+                continue;
+            }
+            const text = await printed(after);
+            const reparsed = freshParse.get(after);
+            if (!reparsed || text.trim() === "" || before && await printed(before) === text) {
+                continue;
+            }
+            const problems = await this.problems(language, after, before, reparsed, text);
+            if (problems.length > 0) {
+                found.push(`  ${after.sourcePath}:`, ...problems.map(problem => `    ${problem}`));
+            }
+        }
+        if (found.length > 0) {
+            throw new Error([
+                "Write code with a template or the format's own parser, or build the nodes the way its parser " +
+                `builds the text they print. The output of ${this.recipe.name} holds nodes that its parser makes ` +
+                "differently of the same text:",
+                ...found,
+                "A recipe that runs after it matches the tree, not the text, so it misses or mistakes a node that " +
+                "parsed code never holds. If the output is meant to differ from parsed code, set " +
+                "spec.checkParserShapedTrees = false."
+            ].join("\n"));
+        }
+    }
+
+    private async problems(language: Language, after: SourceFile, before: SourceFile | undefined,
+                           reparsed: SourceFile, text: string): Promise<string[]> {
+        if (isParseError(reparsed)) {
+            const exception = reparsed.markers.markers
+                .find(m => m.kind === MarkersKind.ParseExceptionResult) as ParseExceptionResult | undefined;
+            return [`the text it prints doesn't parse: ${exception ? firstLine(exception.message) : "a ParseError"}`];
+        } else if (reparsed.kind !== after.kind || await printed(reparsed) !== text) {
+            // a parser that doesn't print back what it read is the parser's to fix
+            return [];
+        }
+        const problems: string[] = [];
+        const shape = await skeleton(language, after);
+        await compare(language, after, shape, await skeleton(language, reparsed), problems);
+        // a file that already broke its language's rules follows other ones
+        if (!before || invalid(language, await skeleton(language, before)).length === 0) {
+            for (const problem of invalid(language, shape)) {
+                if (problems.length < MAX_PER_FILE) {
+                    problems.push(problem);
+                }
+            }
+        }
+        return problems;
+    }
+}
+
+async function compare(language: Language, sourceFile: SourceFile, node: Node, parsed: Node,
+                       problems: string[]): Promise<void> {
+    if (problems.length >= MAX_PER_FILE) {
+        return;
+    }
+    if (node.tree.kind !== parsed.tree.kind) {
+        problems.push(`${await snippet(sourceFile, node)} is a ${typeName(node.tree.kind)} where the parser makes a ` +
+            typeName(parsed.tree.kind));
+        return;
+    }
+    const value = language.value(node.tree);
+    const parsedValue = language.value(parsed.tree);
+    if (value !== parsedValue) {
+        problems.push(`${await snippet(sourceFile, node)} has ${value} where the parser makes ${parsedValue}`);
+    }
+    if (node.children.length !== parsed.children.length) {
+        problems.push(`${await snippet(sourceFile, node)} holds ${kinds(node.children)} where the parser makes ` +
+            kinds(parsed.children));
+        return;
+    }
+    for (let i = 0; i < node.children.length; i++) {
+        await compare(language, sourceFile, node.children[i], parsed.children[i], problems);
+    }
+}
+
+function kinds(nodes: Node[]): string {
+    return nodes.length === 0 ? "nothing" : nodes.map(node => typeName(node.tree.kind)).join(", ");
+}
+
+/** The nodes of a source file, each with the nodes it holds, leaving out those the language skips. */
+async function skeleton(language: Language, sourceFile: SourceFile): Promise<Node> {
+    const roots: Node[] = [];
+    const path: Node[] = [];
+    const Visitor = language.visitor as unknown as new () => TreeVisitor<any, any>;
+    const visitor = new class extends Visitor {
+        protected override async preVisit(tree: Tree, _p: any): Promise<Tree | undefined> {
+            if (language.skip(tree)) {
+                this.stopAfterPreVisit();
+                return tree;
+            }
+            const ancestors = this.cursor.asArray().filter(value => isTree(value)).length - 1;
+            path.length = Math.min(path.length, ancestors);
+            const node: Node = {tree, cursor: this.cursor, children: []};
+            (path.length === 0 ? roots : path[path.length - 1].children).push(node);
+            path.push(node);
+            return tree;
+        }
+    };
+    await visitor.visit(sourceFile, undefined);
+    return roots[0] ?? {tree: sourceFile, cursor: rootCursor(), children: []};
+}
+
+function invalid(language: Language, node: Node): string[] {
+    return [...language.invalid(node.tree), ...node.children.flatMap(child => invalid(language, child))];
+}
+
+async function snippet(sourceFile: SourceFile, node: Node): Promise<string> {
+    let shown: string;
+    try {
+        shown = (await TreePrinters.printer(sourceFile)
+            .print(node.tree, new PrintOutputCapture(MarkerPrinter.SANITIZED), node.cursor.parent))
+            .trim().replace(/\s+/g, " ");
+    } catch {
+        shown = "?";
+    }
+    return `\`${shown.length > SNIPPET_LENGTH ? `${shown.substring(0, SNIPPET_LENGTH)}...` : shown}\``;
+}
+
+function javaScriptValue(tree: Tree): string | undefined {
+    switch (tree.kind) {
+        case J.Kind.Identifier:
+            return `the name \`${(tree as J.Identifier).simpleName}\``;
+        case J.Kind.Literal: {
+            const literal = tree as J.Literal;
+            // the parser keeps the source of a literal with surrogate escapes in place of its value
+            const value = literal.unicodeEscapes?.length ? "a value with surrogate escapes" :
+                literal.value === null || literal.value === undefined ? `the value ${literal.value}` :
+                    `the ${typeof literal.value} value ${quoted(literal.value)}`;
+            return `${value} of type ${literal.type?.keyword ?? "none"}`;
+        }
+        case J.Kind.Modifier: {
+            const modifier = tree as J.Modifier;
+            return `the modifier ${modifier.type === J.ModifierType.LanguageExtension ? modifier.keyword : modifier.type}`;
+        }
+        case J.Kind.Primitive:
+            return `the type ${(tree as J.Primitive).type.keyword}`;
+        case J.Kind.Binary:
+        case J.Kind.Unary:
+        case J.Kind.AssignmentOperation:
+        case JS.Kind.Binary:
+        case JS.Kind.AssignmentOperation:
+            return `the operator ${(tree as J.Binary).operator.element}`;
+        case JS.Kind.TypeOperator:
+            return `the operator ${(tree as JS.TypeOperator).operator}`;
+    }
+    return undefined;
+}
+
+function quoted(value: string | number | bigint | boolean): string {
+    let shown = String(value).replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/\r/g, "\\r")
+        .replace(/\t/g, "\\t");
+    if (shown.length > 40) {
+        shown = `${shown.substring(0, 40)}...`;
+    }
+    return typeof value === "string" ? `"${shown}"` : shown;
+}
+
+function jsonValue(tree: Tree): string | undefined {
+    if (tree.kind === Json.Kind.Literal) {
+        const value = (tree as Json.Literal).value;
+        return value === null || value === undefined ? `the value ${value}` : `the ${typeof value} value \`${value}\``;
+    } else if (tree.kind === Json.Kind.Identifier) {
+        return `the name \`${(tree as Json.Identifier).name}\``;
+    }
+    return undefined;
+}
+
+function jsonInvalid(tree: Tree): string[] {
+    const found: string[] = [];
+    if (tree.kind === Json.Kind.Object) {
+        const keys = new Set<string>();
+        for (const member of (tree as Json.Object).members.map(m => m.element)) {
+            if (member.kind === Json.Kind.Member) {
+                const key = (member as Json.Member).key.element;
+                const name = key.kind === Json.Kind.Identifier ? key.name : String(key.value);
+                if (keys.has(name)) {
+                    found.push(`the key \`${name}\` appears twice in one object`);
+                }
+                keys.add(name);
+            }
+        }
+    } else if (tree.kind === Json.Kind.Member) {
+        const key = (tree as Json.Member).key.element;
+        if (key.kind === Json.Kind.Identifier) {
+            found.push(`the key \`${key.name}\` has no quotes, which JSON doesn't allow`);
+        }
+    } else if (tree.kind === Json.Kind.Literal) {
+        const {source, value} = tree as Json.Literal;
+        if (source.startsWith("'")) {
+            found.push(`\`${source}\` is in single quotes, which JSON doesn't allow`);
+        } else if (typeof value === "number" && !STRICT_NUMBER.test(source)) {
+            found.push(`\`${source}\` isn't a number JSON allows`);
+        }
+    }
+    return found;
+}
+
+function yamlValue(tree: Tree): string | undefined {
+    if (tree.kind === Yaml.Kind.Scalar) {
+        const scalar = tree as Yaml.Scalar;
+        // a block scalar's value holds the whitespace up to the next node, which the parser splits differently
+        const block = scalar.style === Yaml.ScalarStyle.LITERAL || scalar.style === Yaml.ScalarStyle.FOLDED;
+        return `the ${scalar.style} value \`${block ? scalar.value.replace(/\s+$/, "") : scalar.value}\``;
+    } else if (tree.kind === Yaml.Kind.Anchor) {
+        return `the anchor \`${(tree as Yaml.Anchor).key}\``;
+    } else if (tree.kind === Yaml.Kind.Alias) {
+        return `the alias of \`${(tree as Yaml.Alias).anchor.key}\``;
+    }
+    return undefined;
+}
+
+function yamlInvalid(tree: Tree): string[] {
+    if (tree.kind !== Yaml.Kind.Mapping) {
+        return [];
+    }
+    const found: string[] = [];
+    const keys = new Set<string>();
+    for (const {key} of (tree as Yaml.Mapping).entries) {
+        const name = key.kind === Yaml.Kind.Scalar ? (key as Yaml.Scalar).value : `*${(key as Yaml.Alias).anchor.key}`;
+        if (keys.has(name)) {
+            found.push(`the key \`${name}\` appears twice in one mapping, which YAML doesn't allow`);
+        }
+        keys.add(name);
+    }
+    return found;
+}
+
+function printed(sourceFile: SourceFile): Promise<string> {
+    return TreePrinters.printer(sourceFile).print(sourceFile, new PrintOutputCapture(MarkerPrinter.SANITIZED));
+}
+
+function firstLine(message: string): string {
+    const line = message.trim().split("\n")[0];
+    return line.length > 200 ? `${line.substring(0, 200)}...` : line;
+}