[compiler] Deprecate noEmit, add outputMode (facebook#35112)

This deprecates the `noEmit: boolean` flag and adds `outputMode:
'client' | 'client-no-memo' | 'ssr' | 'lint'` as the replacement.
OutputMode defaults to null and takes precedence if specified, otherwise
we use 'client' mode for noEmit=false and 'lint' mode for noEmit=true.

Key points:
* Retrying failed compilation switches from 'client' mode to
'client-no-memo'
* Validations are enabled behind
Environment.proto.shouldEnableValidations, enabled for all modes except
'client-no-memo'. Similar for dropping manual memoization.
* OptimizeSSR is now gated by the outputMode==='ssr', not a feature flag
* Creation of reactive scopes, and related codegen logic, is now gated
by outputMode==='client'

Author: josephsavona

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

@@ -102,14 +102,25 @@ export type PluginOptions = Partial<{
 
   panicThreshold: PanicThresholdOptions;
 
-  /*
+  /**
+   * @deprecated
+   *
    * When enabled, Forget will continue statically analyzing and linting code, but skip over codegen
    * passes.
    *
+   * NOTE: ignored if `outputMode` is specified
+   *
    * Defaults to false
    */
   noEmit: boolean;
 
+  /**
+   * If specified, overrides `noEmit` and controls the output mode of the compiler.
+   *
+   * Defaults to null
+   */
+  outputMode: CompilerOutputMode | null;
+
   /*
    * Determines the strategy for determining which functions to compile. Note that regardless of
    * which mode is enabled, a component can be opted out by adding the string literal
@@ -212,6 +223,19 @@ const CompilationModeSchema = z.enum([
 
 export type CompilationMode = z.infer<typeof CompilationModeSchema>;
 
+const CompilerOutputModeSchema = z.enum([
+  // Build optimized for SSR, with client features removed
+  'ssr',
+  // Build optimized for the client, with auto memoization
+  'client',
+  // Build optimized for the client without auto memo
+  'client-no-memo',
+  // Lint mode, the output is unused but validations should run
+  'lint',
+]);
+
+export type CompilerOutputMode = z.infer<typeof CompilerOutputModeSchema>;
+
 /**
  * Represents 'events' that may occur during compilation. Events are only
  * recorded when a logger is set (through the config).
@@ -293,6 +317,7 @@ export const defaultOptions: ParsedPluginOptions = {
   logger: null,
   gating: null,
   noEmit: false,
+  outputMode: null,
   dynamicGating: null,
   eslintSuppressionRules: null,
   flowSuppressions: true,

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

@@ -8,7 +8,7 @@
 import {NodePath} from '@babel/traverse';
 import * as t from '@babel/types';
 import prettyFormat from 'pretty-format';
-import {Logger, ProgramContext} from '.';
+import {CompilerOutputMode, Logger, ProgramContext} from '.';
 import {
   HIRFunction,
   ReactiveFunction,
@@ -24,7 +24,6 @@ import {
   pruneUnusedLabelsHIR,
 } from '../HIR';
 import {
-  CompilerMode,
   Environment,
   EnvironmentConfig,
   ReactFunctionType,
@@ -120,7 +119,7 @@ function run(
   >,
   config: EnvironmentConfig,
   fnType: ReactFunctionType,
-  mode: CompilerMode,
+  mode: CompilerOutputMode,
   programContext: ProgramContext,
   logger: Logger | null,
   filename: string | null,
@@ -170,7 +169,7 @@ function runWithEnvironment(
   validateUseMemo(hir).unwrap();
 
   if (
-    env.isInferredMemoEnabled &&
+    env.enableDropManualMemoization &&
     !env.config.enablePreserveExistingManualUseMemo &&
     !env.config.disableMemoizationForDebugging &&
     !env.config.enableChangeDetectionForDebugging
@@ -206,7 +205,7 @@ function runWithEnvironment(
   inferTypes(hir);
   log({kind: 'hir', name: 'InferTypes', value: hir});
 
-  if (env.isInferredMemoEnabled) {
+  if (env.enableValidations) {
     if (env.config.validateHooksUsage) {
       validateHooksUsage(hir).unwrap();
     }
@@ -232,13 +231,13 @@ function runWithEnvironment(
 
   const mutabilityAliasingErrors = inferMutationAliasingEffects(hir);
   log({kind: 'hir', name: 'InferMutationAliasingEffects', value: hir});
-  if (env.isInferredMemoEnabled) {
+  if (env.enableValidations) {
     if (mutabilityAliasingErrors.isErr()) {
       throw mutabilityAliasingErrors.unwrapErr();
     }
   }
 
-  if (env.config.enableOptimizeForSSR) {
+  if (env.outputMode === 'ssr') {
     optimizeForSSR(hir);
     log({kind: 'hir', name: 'OptimizeForSSR', value: hir});
   }
@@ -259,14 +258,14 @@ function runWithEnvironment(
     isFunctionExpression: false,
   });
   log({kind: 'hir', name: 'InferMutationAliasingRanges', value: hir});
-  if (env.isInferredMemoEnabled) {
+  if (env.enableValidations) {
     if (mutabilityAliasingRangeErrors.isErr()) {
       throw mutabilityAliasingRangeErrors.unwrapErr();
     }
     validateLocalsNotReassignedAfterRender(hir);
   }
 
-  if (env.isInferredMemoEnabled) {
+  if (env.enableValidations) {
     if (env.config.assertValidMutableRanges) {
       assertValidMutableRanges(hir);
     }
@@ -310,20 +309,18 @@ function runWithEnvironment(
     value: hir,
   });
 
-  if (env.isInferredMemoEnabled) {
-    if (env.config.validateStaticComponents) {
-      env.logErrors(validateStaticComponents(hir));
-    }
+  if (env.enableValidations && env.config.validateStaticComponents) {
+    env.logErrors(validateStaticComponents(hir));
+  }
 
+  if (env.enableMemoization) {
     /**
      * Only create reactive scopes (which directly map to generated memo blocks)
      * if inferred memoization is enabled. This makes all later passes which
      * transform reactive-scope labeled instructions no-ops.
      */
-    if (!env.config.enableOptimizeForSSR) {
-      inferReactiveScopeVariables(hir);
-      log({kind: 'hir', name: 'InferReactiveScopeVariables', value: hir});
-    }
+    inferReactiveScopeVariables(hir);
+    log({kind: 'hir', name: 'InferReactiveScopeVariables', value: hir});
   }
 
   const fbtOperands = memoizeFbtAndMacroOperandsInSameScope(hir);
@@ -588,7 +585,7 @@ export function compileFn(
   >,
   config: EnvironmentConfig,
   fnType: ReactFunctionType,
-  mode: CompilerMode,
+  mode: CompilerOutputMode,
   programContext: ProgramContext,
   logger: Logger | null,
   filename: string | null,

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

@@ -24,6 +24,7 @@ import {
   validateRestrictedImports,
 } from './Imports';
 import {
+  CompilerOutputMode,
   CompilerReactTarget,
   ParsedPluginOptions,
   PluginOptions,
@@ -421,9 +422,17 @@ export function compileProgram(
   );
   const compiledFns: Array<CompileResult> = [];
 
+  // outputMode takes precedence if specified
+  const outputMode: CompilerOutputMode =
+    pass.opts.outputMode ?? (pass.opts.noEmit ? 'lint' : 'client');
   while (queue.length !== 0) {
     const current = queue.shift()!;
-    const compiled = processFn(current.fn, current.fnType, programContext);
+    const compiled = processFn(
+      current.fn,
+      current.fnType,
+      programContext,
+      outputMode,
+    );
 
     if (compiled != null) {
       for (const outlined of compiled.outlined) {
@@ -581,6 +590,7 @@ function processFn(
   fn: BabelFn,
   fnType: ReactFunctionType,
   programContext: ProgramContext,
+  outputMode: CompilerOutputMode,
 ): null | CodegenFunction {
   let directives: {
     optIn: t.Directive | null;
@@ -616,18 +626,27 @@ function processFn(
   }
 
   let compiledFn: CodegenFunction;
-  const compileResult = tryCompileFunction(fn, fnType, programContext);
+  const compileResult = tryCompileFunction(
+    fn,
+    fnType,
+    programContext,
+    outputMode,
+  );
   if (compileResult.kind === 'error') {
     if (directives.optOut != null) {
       logError(compileResult.error, programContext, fn.node.loc ?? null);
     } else {
       handleError(compileResult.error, programContext, fn.node.loc ?? null);
     }
-    const retryResult = retryCompileFunction(fn, fnType, programContext);
-    if (retryResult == null) {
+    if (outputMode === 'client') {
+      const retryResult = retryCompileFunction(fn, fnType, programContext);
+      if (retryResult == null) {
+        return null;
+      }
+      compiledFn = retryResult;
+    } else {
       return null;
     }
-    compiledFn = retryResult;
   } else {
     compiledFn = compileResult.compiledFn;
   }
@@ -663,7 +682,7 @@ function processFn(
 
   if (programContext.hasModuleScopeOptOut) {
     return null;
-  } else if (programContext.opts.noEmit) {
+  } else if (programContext.opts.outputMode === 'lint') {
     /**
      * inferEffectDependencies + noEmit is currently only used for linting. In
      * this mode, add source locations for where the compiler *can* infer effect
@@ -693,6 +712,7 @@ function tryCompileFunction(
   fn: BabelFn,
   fnType: ReactFunctionType,
   programContext: ProgramContext,
+  outputMode: CompilerOutputMode,
 ):
   | {kind: 'compile'; compiledFn: CodegenFunction}
   | {kind: 'error'; error: unknown} {
@@ -719,7 +739,7 @@ function tryCompileFunction(
         fn,
         programContext.opts.environment,
         fnType,
-        'all_features',
+        outputMode,
         programContext,
         programContext.opts.logger,
         programContext.filename,
@@ -757,7 +777,7 @@ function retryCompileFunction(
       fn,
       environment,
       fnType,
-      'no_inferred_memo',
+      'client-no-memo',
       programContext,
       programContext.opts.logger,
       programContext.filename,

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

@@ -9,7 +9,7 @@ import * as t from '@babel/types';
 import {ZodError, z} from 'zod/v4';
 import {fromZodError} from 'zod-validation-error/v4';
 import {CompilerError} from '../CompilerError';
-import {Logger, ProgramContext} from '../Entrypoint';
+import {CompilerOutputMode, Logger, ProgramContext} from '../Entrypoint';
 import {Err, Ok, Result} from '../Utils/Result';
 import {
   DEFAULT_GLOBALS,
@@ -51,6 +51,7 @@ import {Scope as BabelScope, NodePath} from '@babel/traverse';
 import {TypeSchema} from './TypeSchema';
 import {FlowTypeEnv} from '../Flood/Types';
 import {defaultModuleTypeProvider} from './DefaultModuleTypeProvider';
+import {assertExhaustive} from '../Utils/utils';
 
 export const ReactElementSymbolSchema = z.object({
   elementSymbol: z.union([
@@ -691,8 +692,6 @@ export const EnvironmentConfigSchema = z.object({
    * by React to only execute in response to events, not during render.
    */
   enableInferEventHandlers: z.boolean().default(false),
-
-  enableOptimizeForSSR: z.boolean().default(false),
 });
 
 export type EnvironmentConfig = z.infer<typeof EnvironmentConfigSchema>;
@@ -732,7 +731,7 @@ export class Environment {
   code: string | null;
   config: EnvironmentConfig;
   fnType: ReactFunctionType;
-  compilerMode: CompilerMode;
+  outputMode: CompilerOutputMode;
   programContext: ProgramContext;
   hasFireRewrite: boolean;
   hasInferredEffect: boolean;
@@ -747,7 +746,7 @@ export class Environment {
   constructor(
     scope: BabelScope,
     fnType: ReactFunctionType,
-    compilerMode: CompilerMode,
+    outputMode: CompilerOutputMode,
     config: EnvironmentConfig,
     contextIdentifiers: Set<t.Identifier>,
     parentFunction: NodePath<t.Function>, // the outermost function being compiled
@@ -758,7 +757,7 @@ export class Environment {
   ) {
     this.#scope = scope;
     this.fnType = fnType;
-    this.compilerMode = compilerMode;
+    this.outputMode = outputMode;
     this.config = config;
     this.filename = filename;
     this.code = code;
@@ -854,8 +853,65 @@ export class Environment {
     return this.#flowTypeEnvironment;
   }
 
-  get isInferredMemoEnabled(): boolean {
-    return this.compilerMode !== 'no_inferred_memo';
+  get enableDropManualMemoization(): boolean {
+    switch (this.outputMode) {
+      case 'lint': {
+        // linting drops to be more compatible with compiler analysis
+        return true;
+      }
+      case 'client':
+      case 'ssr': {
+        return true;
+      }
+      case 'client-no-memo': {
+        return false;
+      }
+      default: {
+        assertExhaustive(
+          this.outputMode,
+          `Unexpected output mode '${this.outputMode}'`,
+        );
+      }
+    }
+  }
+
+  get enableMemoization(): boolean {
+    switch (this.outputMode) {
+      case 'client':
+      case 'lint': {
+        // linting also enables memoization so that we can check if manual memoization is preserved
+        return true;
+      }
+      case 'ssr':
+      case 'client-no-memo': {
+        return false;
+      }
+      default: {
+        assertExhaustive(
+          this.outputMode,
+          `Unexpected output mode '${this.outputMode}'`,
+        );
+      }
+    }
+  }
+
+  get enableValidations(): boolean {
+    switch (this.outputMode) {
+      case 'client':
+      case 'lint':
+      case 'ssr': {
+        return true;
+      }
+      case 'client-no-memo': {
+        return false;
+      }
+      default: {
+        assertExhaustive(
+          this.outputMode,
+          `Unexpected output mode '${this.outputMode}'`,
+        );
+      }
+    }
   }
 
   get nextIdentifierId(): IdentifierId {

compiler/packages/babel-plugin-react-compiler/src/Inference/InferMutationAliasingEffects.ts

@@ -2452,7 +2452,7 @@ function computeEffectsForLegacySignature(
       }),
     });
   }
-  if (signature.knownIncompatible != null && state.env.isInferredMemoEnabled) {
+  if (signature.knownIncompatible != null && state.env.enableValidations) {
     const errors = new CompilerError();
     errors.pushDiagnostic(
       CompilerDiagnostic.create({