[compiler][wip] Improve diagnostic infra

Work in progress, i'm experimenting with revamping our diagnostic infra. Starting with a better format for representing errors, with an ability to point ot multiple locations, along with better printing of errors. Of course, Babel still controls the printing in the majority case so this still needs more work.

Author: josephsavona

compiler/packages/babel-plugin-react-compiler/src/CompilerError.ts

@@ -5,6 +5,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import {codeFrameColumns} from '@babel/code-frame';
 import type {SourceLocation} from './HIR';
 import {Err, Ok, Result} from './Utils/Result';
 import {assertExhaustive} from './Utils/utils';
@@ -44,6 +45,40 @@ export enum ErrorSeverity {
   Invariant = 'Invariant',
 }
 
+export type CompilerDiagnosticOptions = {
+  severity: ErrorSeverity;
+  category: string;
+  description: string;
+  details: Array<CompilerDiagnosticDetail>;
+  suggestions?: Array<CompilerSuggestion> | null | undefined;
+};
+
+export type CompilerDiagnosticDetail =
+  /**
+   * Additional information not coupled to a specific location,
+   * generally linking to documentation.
+   */
+  | {
+      kind: 'info';
+      message: string;
+    }
+  /**
+   * The (a) source of the error
+   */
+  | {
+      kind: 'error';
+      loc: SourceLocation;
+      message: string;
+    }
+  /**
+   * A related part of the source code that does not directly contribute to the error
+   */
+  | {
+      kind: 'related';
+      loc: SourceLocation;
+      message: string;
+    };
+
 export enum CompilerSuggestionOperation {
   InsertBefore,
   InsertAfter,
@@ -74,6 +109,73 @@ export type CompilerErrorDetailOptions = {
   suggestions?: Array<CompilerSuggestion> | null | undefined;
 };
 
+export class CompilerDiagnostic {
+  options: CompilerDiagnosticOptions;
+
+  constructor(options: CompilerDiagnosticOptions) {
+    this.options = options;
+  }
+
+  get category(): CompilerDiagnosticOptions['category'] {
+    return this.options.category;
+  }
+  get description(): CompilerDiagnosticOptions['description'] {
+    return this.options.description;
+  }
+  get severity(): CompilerDiagnosticOptions['severity'] {
+    return this.options.severity;
+  }
+  get suggestions(): CompilerDiagnosticOptions['suggestions'] {
+    return this.options.suggestions;
+  }
+
+  printErrorMessage(source: string): string {
+    const buffer = [`${this.severity}: ${this.category}\n\n`, this.description];
+    for (const detail of this.options.details) {
+      switch (detail.kind) {
+        case 'error':
+        case 'related': {
+          const loc = detail.loc;
+          if (typeof loc === 'symbol') {
+            continue;
+          }
+          let codeFrame: string;
+          try {
+            codeFrame = codeFrameColumns(
+              source,
+              {
+                start: {
+                  line: loc.start.line,
+                  column: loc.start.column + 1,
+                },
+                end: {
+                  line: loc.end.line,
+                  column: loc.end.column + 1,
+                },
+              },
+              {
+                message: detail.message,
+              },
+            );
+          } catch (e) {
+            codeFrame = detail.message;
+          }
+          buffer.push(
+            `\n\n${loc.filename}:${loc.start.line}:${loc.start.column}\n`,
+          );
+          buffer.push(codeFrame);
+        }
+      }
+    }
+    return buffer.join('');
+  }
+
+  toString(): string {
+    const buffer = [`${this.severity}: ${this.category}\n\n`, this.description];
+    return buffer.join('');
+  }
+}
+
 /*
  * Each bailout or invariant in HIR lowering creates an {@link CompilerErrorDetail}, which is then
  * aggregated into a single {@link CompilerError} later.
@@ -101,24 +203,58 @@ export class CompilerErrorDetail {
     return this.options.suggestions;
   }
 
-  printErrorMessage(): string {
+  printErrorMessage(source: string): string {
     const buffer = [`${this.severity}: ${this.reason}`];
     if (this.description != null) {
-      buffer.push(`. ${this.description}`);
+      buffer.push(`\n\n${this.description}.`);
     }
-    if (this.loc != null && typeof this.loc !== 'symbol') {
-      buffer.push(` (${this.loc.start.line}:${this.loc.end.line})`);
+    const loc = this.loc;
+    if (loc != null && typeof loc !== 'symbol') {
+      let codeFrame: string;
+      try {
+        codeFrame = codeFrameColumns(
+          source,
+          {
+            start: {
+              line: loc.start.line,
+              column: loc.start.column + 1,
+            },
+            end: {
+              line: loc.end.line,
+              column: loc.end.column + 1,
+            },
+          },
+          {
+            message: this.reason,
+          },
+        );
+      } catch (e) {
+        codeFrame = '';
+      }
+      buffer.push(
+        `\n\n${loc.filename}:${loc.start.line}:${loc.start.column}\n`,
+      );
+      buffer.push(codeFrame);
+      buffer.push('\n\n');
     }
     return buffer.join('');
   }
 
   toString(): string {
-    return this.printErrorMessage();
+    const buffer = [`${this.severity}: ${this.reason}`];
+    if (this.description != null) {
+      buffer.push(`. ${this.description}.`);
+    }
+    const loc = this.loc;
+    if (loc != null && typeof loc !== 'symbol') {
+      buffer.push(` (${loc.start.line}:${loc.start.column})`);
+    }
+    return buffer.join('');
   }
 }
 
 export class CompilerError extends Error {
-  details: Array<CompilerErrorDetail> = [];
+  details: Array<CompilerErrorDetail | CompilerDiagnostic> = [];
 
   static invariant(
     condition: unknown,
@@ -136,6 +272,12 @@ export class CompilerError extends Error {
     }
   }
 
+  static throwDiagnostic(options: CompilerDiagnosticOptions): never {
+    const errors = new CompilerError();
+    errors.pushDiagnostic(new CompilerDiagnostic(options));
+    throw errors;
+  }
+
   static throwTodo(
     options: Omit<CompilerErrorDetailOptions, 'severity'>,
   ): never {
@@ -210,6 +352,21 @@ export class CompilerError extends Error {
     return this.name;
   }
 
+  printErrorMessage(source: string): string {
+    return (
+      `Found ${this.details.length} errors:\n` +
+      this.details.map(detail => detail.printErrorMessage(source)).join('\n')
+    );
+  }
+
+  merge(other: CompilerError): void {
+    this.details.push(...other.details);
+  }
+
+  pushDiagnostic(diagnostic: CompilerDiagnostic): void {
+    this.details.push(diagnostic);
+  }
+
   push(options: CompilerErrorDetailOptions): CompilerErrorDetail {
     const detail = new CompilerErrorDetail({
       reason: options.reason,

compiler/packages/babel-plugin-react-compiler/src/Entrypoint/Options.ts

@@ -7,7 +7,11 @@
 
 import * as t from '@babel/types';
 import {z} from 'zod';
-import {CompilerError, CompilerErrorDetailOptions} from '../CompilerError';
+import {
+  CompilerDiagnosticOptions,
+  CompilerError,
+  CompilerErrorDetailOptions,
+} from '../CompilerError';
 import {
   EnvironmentConfig,
   ExternalFunction,
@@ -224,7 +228,7 @@ export type LoggerEvent =
 export type CompileErrorEvent = {
   kind: 'CompileError';
   fnLoc: t.SourceLocation | null;
-  detail: CompilerErrorDetailOptions;
+  detail: CompilerErrorDetailOptions | CompilerDiagnosticOptions;
 };
 export type CompileDiagnosticEvent = {
   kind: 'CompileDiagnostic';

compiler/packages/babel-plugin-react-compiler/src/Entrypoint/ValidateNoUntransformedReferences.ts

@@ -8,32 +8,27 @@
 import {NodePath} from '@babel/core';
 import * as t from '@babel/types';
 
-import {
-  CompilerError,
-  CompilerErrorDetailOptions,
-  EnvironmentConfig,
-  ErrorSeverity,
-  Logger,
-} from '..';
+import {CompilerError, EnvironmentConfig, ErrorSeverity, Logger} from '..';
 import {getOrInsertWith} from '../Utils/utils';
-import {Environment} from '../HIR';
+import {Environment, GeneratedSource} from '../HIR';
 import {DEFAULT_EXPORT} from '../HIR/Environment';
 import {CompileProgramMetadata} from './Program';
+import {CompilerDiagnosticOptions} from '../CompilerError';
 
 function throwInvalidReact(
-  options: Omit<CompilerErrorDetailOptions, 'severity'>,
+  options: Omit<CompilerDiagnosticOptions, 'severity'>,
   {logger, filename}: TraversalState,
 ): never {
-  const detail: CompilerErrorDetailOptions = {
-    ...options,
+  const detail: CompilerDiagnosticOptions = {
     severity: ErrorSeverity.InvalidReact,
+    ...options,
   };
   logger?.logEvent(filename, {
     kind: 'CompileError',
     fnLoc: null,
     detail,
   });
-  CompilerError.throw(detail);
+  CompilerError.throwDiagnostic(detail);
 }
 function assertValidEffectImportReference(
   numArgs: number,
@@ -65,14 +60,18 @@ function assertValidEffectImportReference(
          */
         throwInvalidReact(
           {
-            reason:
-              '[InferEffectDependencies] React Compiler is unable to infer dependencies of this effect. ' +
-              'This will break your build! ' +
-              'To resolve, either pass your own dependency array or fix reported compiler bailout diagnostics.',
-            description: maybeErrorDiagnostic
-              ? `(Bailout reason: ${maybeErrorDiagnostic})`
-              : null,
-            loc: parent.node.loc ?? null,
+            category:
+              'Cannot infer dependencies of this effect. This will break your build!',
+            description:
+              'To resolve, either pass a dependency array or fix reported compiler bailout diagnostics.' +
+              (maybeErrorDiagnostic ? ` ${maybeErrorDiagnostic}` : ''),
+            details: [
+              {
+                kind: 'error',
+                message: 'Cannot infer dependencies',
+                loc: parent.node.loc ?? GeneratedSource,
+              },
+            ],
           },
           context,
         );
@@ -92,13 +91,20 @@ function assertValidFireImportReference(
     );
     throwInvalidReact(
       {
-        reason:
-          '[Fire] Untransformed reference to compiler-required feature. ' +
-          'Either remove this `fire` call or ensure it is successfully transformed by the compiler',
-        description: maybeErrorDiagnostic
-          ? `(Bailout reason: ${maybeErrorDiagnostic})`
-          : null,
-        loc: paths[0].node.loc ?? null,
+        category:
+          '[Fire] Untransformed reference to compiler-required feature.',
+        description:
+          'Either remove this `fire` call or ensure it is successfully transformed by the compiler' +
+          maybeErrorDiagnostic
+            ? ` ${maybeErrorDiagnostic}`
+            : '',
+        details: [
+          {
+            kind: 'error',
+            message: 'Untransformed `fire` call',
+            loc: paths[0].node.loc ?? GeneratedSource,
+          },
+        ],
       },
       context,
     );

compiler/packages/babel-plugin-react-compiler/src/HIR/BuildHIR.ts

@@ -2271,11 +2271,17 @@ function lowerExpression(
         });
         for (const [name, locations] of Object.entries(fbtLocations)) {
           if (locations.length > 1) {
-            CompilerError.throwTodo({
-              reason: `Support <${tagName}> tags with multiple <${tagName}:${name}> values`,
-              loc: locations.at(-1) ?? GeneratedSource,
-              description: null,
-              suggestions: null,
+            CompilerError.throwDiagnostic({
+              severity: ErrorSeverity.Todo,
+              category: 'Support duplicate fbt tags',
+              description: `Support \`<${tagName}>\` tags with multiple \`<${tagName}:${name}>\` values`,
+              details: locations.map(loc => {
+                return {
+                  kind: 'error',
+                  message: `Multiple \`<${tagName}:${name}>\` tags found`,
+                  loc,
+                };
+              }),
             });
           }
         }
@@ -3501,9 +3507,8 @@ function lowerFunction(
   );
   let loweredFunc: HIRFunction;
   if (lowering.isErr()) {
-    lowering
-      .unwrapErr()
-      .details.forEach(detail => builder.errors.pushErrorDetail(detail));
+    const functionErrors = lowering.unwrapErr();
+    builder.errors.merge(functionErrors);
     return null;
   }
   loweredFunc = lowering.unwrap();

compiler/packages/babel-plugin-react-compiler/src/HIR/Environment.ts

@@ -779,7 +779,7 @@ export class Environment {
     for (const error of errors.unwrapErr().details) {
       this.logger.logEvent(this.filename, {
         kind: 'CompileError',
-        detail: error,
+        detail: error.options,
         fnLoc: null,
       });
     }