[compiler][gating] Experimental directive based gating (facebook#33149)

Adds `dynamicGating` as an experimental option for testing rollout DX at
Meta. If specified, this enables dynamic gating which matches `use memo
if(...)` directives.

#### Example usage
Input file
```js
// @dynamicGating:{"source":"myModule"}
export function MyComponent() {
  'use memo if(isEnabled)';
   return <div>...</div>;
}
```
Compiler output
```js
import {isEnabled} from 'myModule';
export const MyComponent = isEnabled()
  ? <optimized version>
  : <original version>;
```
---
[//]: # (BEGIN SAPLING FOOTER)
Stack created with [Sapling](https://sapling-scm.com). Best reviewed
with [ReviewStack](https://reviewstack.dev/facebook/react/pull/33149).
* __->__ facebook#33149
* facebook#33148

DiffTrain build for [459a2c4](facebook@459a2c4)

Author: pull[bot]

compiled/eslint-plugin-react-hooks/index.js

@@ -55944,14 +55944,78 @@ function suppressionsToCompilerError(suppressionRanges) {
 
 const OPT_IN_DIRECTIVES = new Set(['use forget', 'use memo']);
 const OPT_OUT_DIRECTIVES = new Set(['use no forget', 'use no memo']);
-function findDirectiveEnablingMemoization(directives) {
-    var _a;
-    return ((_a = directives.find(directive => OPT_IN_DIRECTIVES.has(directive.value.value))) !== null && _a !== void 0 ? _a : null);
+const DYNAMIC_GATING_DIRECTIVE = new RegExp('^use memo if\\(([^\\)]*)\\)$');
+function tryFindDirectiveEnablingMemoization(directives, opts) {
+    var _a, _b;
+    const optIn = directives.find(directive => OPT_IN_DIRECTIVES.has(directive.value.value));
+    if (optIn != null) {
+        return Ok(optIn);
+    }
+    const dynamicGating = findDirectivesDynamicGating(directives, opts);
+    if (dynamicGating.isOk()) {
+        return Ok((_b = (_a = dynamicGating.unwrap()) === null || _a === void 0 ? void 0 : _a.directive) !== null && _b !== void 0 ? _b : null);
+    }
+    else {
+        return Err(dynamicGating.unwrapErr());
+    }
 }
 function findDirectiveDisablingMemoization(directives) {
     var _a;
     return ((_a = directives.find(directive => OPT_OUT_DIRECTIVES.has(directive.value.value))) !== null && _a !== void 0 ? _a : null);
 }
+function findDirectivesDynamicGating(directives, opts) {
+    var _a, _b;
+    if (opts.dynamicGating === null) {
+        return Ok(null);
+    }
+    const errors = new CompilerError();
+    const result = [];
+    for (const directive of directives) {
+        const maybeMatch = DYNAMIC_GATING_DIRECTIVE.exec(directive.value.value);
+        if (maybeMatch != null && maybeMatch[1] != null) {
+            if (libExports$1.isValidIdentifier(maybeMatch[1])) {
+                result.push({ directive, match: maybeMatch[1] });
+            }
+            else {
+                errors.push({
+                    reason: `Dynamic gating directive is not a valid JavaScript identifier`,
+                    description: `Found '${directive.value.value}'`,
+                    severity: ErrorSeverity.InvalidReact,
+                    loc: (_a = directive.loc) !== null && _a !== void 0 ? _a : null,
+                    suggestions: null,
+                });
+            }
+        }
+    }
+    if (errors.hasErrors()) {
+        return Err(errors);
+    }
+    else if (result.length > 1) {
+        const error = new CompilerError();
+        error.push({
+            reason: `Multiple dynamic gating directives found`,
+            description: `Expected a single directive but found [${result
+                .map(r => r.directive.value.value)
+                .join(', ')}]`,
+            severity: ErrorSeverity.InvalidReact,
+            loc: (_b = result[0].directive.loc) !== null && _b !== void 0 ? _b : null,
+            suggestions: null,
+        });
+        return Err(error);
+    }
+    else if (result.length === 1) {
+        return Ok({
+            gating: {
+                source: opts.dynamicGating.source,
+                importSpecifierName: result[0].match,
+            },
+            directive: result[0].directive,
+        });
+    }
+    else {
+        return Ok(null);
+    }
+}
 function isCriticalError(err) {
     return !(err instanceof CompilerError) || err.isCritical();
 }
@@ -56184,25 +56248,33 @@ function findFunctionsToCompile(program, pass, programContext) {
     return queue;
 }
 function processFn(fn, fnType, programContext) {
-    var _a, _b, _c, _d, _e, _f, _g;
+    var _a, _b, _c, _d, _e, _f, _g, _h;
     let directives;
     if (fn.node.body.type !== 'BlockStatement') {
-        directives = { optIn: null, optOut: null };
+        directives = {
+            optIn: null,
+            optOut: null,
+        };
     }
     else {
+        const optIn = tryFindDirectiveEnablingMemoization(fn.node.body.directives, programContext.opts);
+        if (optIn.isErr()) {
+            handleError(optIn.unwrapErr(), programContext, (_a = fn.node.loc) !== null && _a !== void 0 ? _a : null);
+            return null;
+        }
         directives = {
-            optIn: findDirectiveEnablingMemoization(fn.node.body.directives),
+            optIn: optIn.unwrapOr(null),
             optOut: findDirectiveDisablingMemoization(fn.node.body.directives),
         };
     }
     let compiledFn;
     const compileResult = tryCompileFunction(fn, fnType, programContext);
     if (compileResult.kind === 'error') {
         if (directives.optOut != null) {
-            logError(compileResult.error, programContext, (_a = fn.node.loc) !== null && _a !== void 0 ? _a : null);
+            logError(compileResult.error, programContext, (_b = fn.node.loc) !== null && _b !== void 0 ? _b : null);
         }
         else {
-            handleError(compileResult.error, programContext, (_b = fn.node.loc) !== null && _b !== void 0 ? _b : null);
+            handleError(compileResult.error, programContext, (_c = fn.node.loc) !== null && _c !== void 0 ? _c : null);
         }
         const retryResult = retryCompileFunction(fn, fnType, programContext);
         if (retryResult == null) {
@@ -56217,16 +56289,16 @@ function processFn(fn, fnType, programContext) {
         directives.optOut != null) {
         programContext.logEvent({
             kind: 'CompileSkip',
-            fnLoc: (_c = fn.node.body.loc) !== null && _c !== void 0 ? _c : null,
+            fnLoc: (_d = fn.node.body.loc) !== null && _d !== void 0 ? _d : null,
             reason: `Skipped due to '${directives.optOut.value}' directive.`,
-            loc: (_d = directives.optOut.loc) !== null && _d !== void 0 ? _d : null,
+            loc: (_e = directives.optOut.loc) !== null && _e !== void 0 ? _e : null,
         });
         return null;
     }
     programContext.logEvent({
         kind: 'CompileSuccess',
-        fnLoc: (_e = fn.node.loc) !== null && _e !== void 0 ? _e : null,
-        fnName: (_g = (_f = compiledFn.id) === null || _f === void 0 ? void 0 : _f.name) !== null && _g !== void 0 ? _g : null,
+        fnLoc: (_f = fn.node.loc) !== null && _f !== void 0 ? _f : null,
+        fnName: (_h = (_g = compiledFn.id) === null || _g === void 0 ? void 0 : _g.name) !== null && _h !== void 0 ? _h : null,
         memoSlots: compiledFn.memoSlotsUsed,
         memoBlocks: compiledFn.memoBlocks,
         memoValues: compiledFn.memoValues,
@@ -56290,19 +56362,23 @@ function retryCompileFunction(fn, fnType, programContext) {
     }
 }
 function applyCompiledFunctions(program, compiledFns, pass, programContext) {
-    const referencedBeforeDeclared = pass.opts.gating != null
-        ? getFunctionReferencedBeforeDeclarationAtTopLevel(program, compiledFns)
-        : null;
+    var _a, _b;
+    let referencedBeforeDeclared = null;
     for (const result of compiledFns) {
         const { kind, originalFn, compiledFn } = result;
         const transformedFn = createNewFunctionNode(originalFn, compiledFn);
         programContext.alreadyCompiled.add(transformedFn);
-        if (referencedBeforeDeclared != null && kind === 'original') {
-            CompilerError.invariant(pass.opts.gating != null, {
-                reason: "Expected 'gating' import to be present",
-                loc: null,
-            });
-            insertGatedFunctionDeclaration(originalFn, transformedFn, programContext, pass.opts.gating, referencedBeforeDeclared.has(result));
+        let dynamicGating = null;
+        if (originalFn.node.body.type === 'BlockStatement') {
+            const result = findDirectivesDynamicGating(originalFn.node.body.directives, pass.opts);
+            if (result.isOk()) {
+                dynamicGating = (_b = (_a = result.unwrap()) === null || _a === void 0 ? void 0 : _a.gating) !== null && _b !== void 0 ? _b : null;
+            }
+        }
+        const functionGating = dynamicGating !== null && dynamicGating !== void 0 ? dynamicGating : pass.opts.gating;
+        if (kind === 'original' && functionGating != null) {
+            referencedBeforeDeclared !== null && referencedBeforeDeclared !== void 0 ? referencedBeforeDeclared : (referencedBeforeDeclared = getFunctionReferencedBeforeDeclarationAtTopLevel(program, compiledFns));
+            insertGatedFunctionDeclaration(originalFn, transformedFn, programContext, functionGating, referencedBeforeDeclared.has(result));
         }
         else {
             originalFn.replaceWith(transformedFn);
@@ -56338,8 +56414,10 @@ function getReactFunctionType(fn, pass) {
     var _a, _b;
     const hookPattern = pass.opts.environment.hookPattern;
     if (fn.node.body.type === 'BlockStatement') {
-        if (findDirectiveEnablingMemoization(fn.node.body.directives) != null)
+        const optInDirectives = tryFindDirectiveEnablingMemoization(fn.node.body.directives, pass.opts);
+        if (optInDirectives.unwrapOr(null) != null) {
             return (_a = getComponentOrHookLike(fn, hookPattern)) !== null && _a !== void 0 ? _a : 'Other';
+        }
     }
     let componentSyntaxType = null;
     if (fn.isFunctionDeclaration()) {
@@ -56854,6 +56932,9 @@ zod.z.enum([
     'critical_errors',
     'none',
 ]);
+const DynamicGatingOptionsSchema = zod.z.object({
+    source: zod.z.string(),
+});
 const CompilerReactTargetSchema = zod.z.union([
     zod.z.literal('17'),
     zod.z.literal('18'),
@@ -56876,6 +56957,7 @@ const defaultOptions = {
     logger: null,
     gating: null,
     noEmit: false,
+    dynamicGating: null,
     eslintSuppressionRules: null,
     flowSuppressions: true,
     ignoreUseNoForget: false,
@@ -56922,6 +57004,26 @@ function parsePluginOptions(obj) {
                     }
                     break;
                 }
+                case 'dynamicGating': {
+                    if (value == null) {
+                        parsedOptions[key] = null;
+                    }
+                    else {
+                        const result = DynamicGatingOptionsSchema.safeParse(value);
+                        if (result.success) {
+                            parsedOptions[key] = result.data;
+                        }
+                        else {
+                            CompilerError.throwInvalidConfig({
+                                reason: 'Could not parse dynamic gating. Update React Compiler config to fix the error',
+                                description: `${zodValidationError.fromZodError(result.error)}`,
+                                loc: null,
+                                suggestions: null,
+                            });
+                        }
+                    }
+                    break;
+                }
                 default: {
                     parsedOptions[key] = value;
                 }

compiled/facebook-www/REVISION

@@ -1 +1 @@
-3710c4d4f9ffb6aa07e291b822e4ec7d69ed5a32
+459a2c4298187cb0ee45605e2575ff35f4a81183

compiled/facebook-www/REVISION_TRANSFORMS

@@ -1 +1 @@
-3710c4d4f9ffb6aa07e291b822e4ec7d69ed5a32
+459a2c4298187cb0ee45605e2575ff35f4a81183

compiled/facebook-www/React-dev.classic.js

@@ -1537,7 +1537,7 @@ __DEV__ &&
     exports.useTransition = function () {
       return resolveDispatcher().useTransition();
     };
-    exports.version = "19.2.0-www-classic-3710c4d4-20250521";
+    exports.version = "19.2.0-www-classic-459a2c42-20250521";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

compiled/facebook-www/React-dev.modern.js

@@ -1537,7 +1537,7 @@ __DEV__ &&
     exports.useTransition = function () {
       return resolveDispatcher().useTransition();
     };
-    exports.version = "19.2.0-www-modern-3710c4d4-20250521";
+    exports.version = "19.2.0-www-modern-459a2c42-20250521";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

compiled/facebook-www/React-prod.classic.js

@@ -635,4 +635,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-classic-3710c4d4-20250521";
+exports.version = "19.2.0-www-classic-459a2c42-20250521";

compiled/facebook-www/React-prod.modern.js

@@ -635,4 +635,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-modern-3710c4d4-20250521";
+exports.version = "19.2.0-www-modern-459a2c42-20250521";

compiled/facebook-www/React-profiling.classic.js

@@ -639,7 +639,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-classic-3710c4d4-20250521";
+exports.version = "19.2.0-www-classic-459a2c42-20250521";
 "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
   "function" ===
     typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

compiled/facebook-www/React-profiling.modern.js

@@ -639,7 +639,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-modern-3710c4d4-20250521";
+exports.version = "19.2.0-www-modern-459a2c42-20250521";
 "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
   "function" ===
     typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

compiled/facebook-www/ReactART-dev.classic.js

@@ -19080,10 +19080,10 @@ __DEV__ &&
     (function () {
       var internals = {
         bundleType: 1,
-        version: "19.2.0-www-classic-3710c4d4-20250521",
+        version: "19.2.0-www-classic-459a2c42-20250521",
         rendererPackageName: "react-art",
         currentDispatcherRef: ReactSharedInternals,
-        reconcilerVersion: "19.2.0-www-classic-3710c4d4-20250521"
+        reconcilerVersion: "19.2.0-www-classic-459a2c42-20250521"
       };
       internals.overrideHookState = overrideHookState;
       internals.overrideHookStateDeletePath = overrideHookStateDeletePath;
@@ -19117,7 +19117,7 @@ __DEV__ &&
     exports.Shape = Shape;
     exports.Surface = Surface;
     exports.Text = Text;
-    exports.version = "19.2.0-www-classic-3710c4d4-20250521";
+    exports.version = "19.2.0-www-classic-459a2c42-20250521";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&