[compiler] Detect known incompatible libraries (#34027)

A few libraries are known to be incompatible with memoization, whether
manually via `useMemo()` or via React Compiler. This puts us in a tricky
situation. On the one hand, we understand that these libraries were
developed prior to our documenting the [Rules of
React](https://react.dev/reference/rules), and their designs were the
result of trying to deliver a great experience for their users and
balance multiple priorities around DX, performance, etc. At the same
time, using these libraries with memoization — and in particular with
automatic memoization via React Compiler — can break apps by causing the
components using these APIs not to update. Concretely, the APIs have in
common that they return a function which returns different values over
time, but where the function itself does not change. Memoizing the
result on the identity of the function will mean that the value never
changes. Developers reasonable interpret this as "React Compiler broke
my code".

Of course, the best solution is to work with developers of these
libraries to address the root cause, and we're doing that. We've
previously discussed this situation with both of the respective
libraries:
* React Hook Form:
react-hook-form/react-hook-form#11910 (comment)
* TanStack Table:
#33057 (comment)
and TanStack/table#5567

In the meantime we need to make sure that React Compiler can work out of
the box as much as possible. This means teaching it about popular
libraries that cannot be memoized. We also can't silently skip
compilation, as this confuses users, so we need these error messages to
be visible to users. To that end, this PR adds:

* A flag to mark functions/hooks as incompatible
* Validation against use of such functions
* A default type provider to provide declarations for two
known-incompatible libraries

Note that Mobx is also incompatible, but the `observable()` function is
called outside of the component itself, so the compiler cannot currently
detect it. We may add validation for such APIs in the future.

Again, we really empathize with the developers of these libraries. We've
tried to word the error message non-judgementally, because we get that
it's hard! We're open to feedback about the error message, please let us
know.

DiffTrain build for [4082b0e](4082b0e)

Author: josephsavona

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

@@ -17652,6 +17652,7 @@ var ErrorSeverity;
     ErrorSeverity["InvalidReact"] = "InvalidReact";
     ErrorSeverity["InvalidConfig"] = "InvalidConfig";
     ErrorSeverity["CannotPreserveMemoization"] = "CannotPreserveMemoization";
+    ErrorSeverity["IncompatibleLibrary"] = "IncompatibleLibrary";
     ErrorSeverity["Todo"] = "Todo";
     ErrorSeverity["Invariant"] = "Invariant";
 })(ErrorSeverity || (ErrorSeverity = {}));
@@ -17918,7 +17919,8 @@ class CompilerError extends Error {
                 case ErrorSeverity.InvalidJS:
                 case ErrorSeverity.InvalidReact:
                 case ErrorSeverity.InvalidConfig:
-                case ErrorSeverity.UnsupportedJS: {
+                case ErrorSeverity.UnsupportedJS:
+                case ErrorSeverity.IncompatibleLibrary: {
                     return true;
                 }
                 case ErrorSeverity.CannotPreserveMemoization:
@@ -17956,8 +17958,9 @@ function printErrorSummary(severity, message) {
             severityCategory = 'Error';
             break;
         }
+        case ErrorSeverity.IncompatibleLibrary:
         case ErrorSeverity.CannotPreserveMemoization: {
-            severityCategory = 'Memoization';
+            severityCategory = 'Compilation Skipped';
             break;
         }
         case ErrorSeverity.Invariant: {
@@ -17982,6 +17985,7 @@ var ErrorCategory;
     ErrorCategory["UseMemo"] = "UseMemo";
     ErrorCategory["Factories"] = "Factories";
     ErrorCategory["PreserveManualMemo"] = "PreserveManualMemo";
+    ErrorCategory["IncompatibleLibrary"] = "IncompatibleLibrary";
     ErrorCategory["Immutability"] = "Immutability";
     ErrorCategory["Globals"] = "Globals";
     ErrorCategory["Refs"] = "Refs";
@@ -18214,6 +18218,14 @@ function getRuleForCategoryImpl(category) {
                 recommended: true,
             };
         }
+        case ErrorCategory.IncompatibleLibrary: {
+            return {
+                category,
+                name: 'incompatible-library',
+                description: 'Validates against usage of libraries which are incompatible with memoization (manual or automatic)',
+                recommended: true,
+            };
+        }
         default: {
             assertExhaustive$1(category, `Unsupported category ${category}`);
         }
@@ -30841,7 +30853,7 @@ for (const [name, type_] of TYPED_GLOBALS) {
 DEFAULT_GLOBALS.set('globalThis', addObject(DEFAULT_SHAPES, 'globalThis', TYPED_GLOBALS));
 DEFAULT_GLOBALS.set('global', addObject(DEFAULT_SHAPES, 'global', TYPED_GLOBALS));
 function installTypeConfig(globals, shapes, typeConfig, moduleName, loc) {
-    var _a, _b, _c, _d;
+    var _a, _b, _c, _d, _e, _f;
     switch (typeConfig.kind) {
         case 'type': {
             switch (typeConfig.name) {
@@ -30875,22 +30887,24 @@ function installTypeConfig(globals, shapes, typeConfig, moduleName, loc) {
                 noAlias: typeConfig.noAlias === true,
                 mutableOnlyIfOperandsAreMutable: typeConfig.mutableOnlyIfOperandsAreMutable === true,
                 aliasing: typeConfig.aliasing,
+                knownIncompatible: (_a = typeConfig.knownIncompatible) !== null && _a !== void 0 ? _a : null,
             });
         }
         case 'hook': {
             return addHook(shapes, {
                 hookKind: 'Custom',
-                positionalParams: (_a = typeConfig.positionalParams) !== null && _a !== void 0 ? _a : [],
-                restParam: (_b = typeConfig.restParam) !== null && _b !== void 0 ? _b : Effect.Freeze,
+                positionalParams: (_b = typeConfig.positionalParams) !== null && _b !== void 0 ? _b : [],
+                restParam: (_c = typeConfig.restParam) !== null && _c !== void 0 ? _c : Effect.Freeze,
                 calleeEffect: Effect.Read,
                 returnType: installTypeConfig(globals, shapes, typeConfig.returnType, moduleName, loc),
-                returnValueKind: (_c = typeConfig.returnValueKind) !== null && _c !== void 0 ? _c : ValueKind.Frozen,
+                returnValueKind: (_d = typeConfig.returnValueKind) !== null && _d !== void 0 ? _d : ValueKind.Frozen,
                 noAlias: typeConfig.noAlias === true,
                 aliasing: typeConfig.aliasing,
+                knownIncompatible: (_e = typeConfig.knownIncompatible) !== null && _e !== void 0 ? _e : null,
             });
         }
         case 'object': {
-            return addObject(shapes, null, Object.entries((_d = typeConfig.properties) !== null && _d !== void 0 ? _d : {}).map(([key, value]) => {
+            return addObject(shapes, null, Object.entries((_f = typeConfig.properties) !== null && _f !== void 0 ? _f : {}).map(([key, value]) => {
                 var _a;
                 const type = installTypeConfig(globals, shapes, value, moduleName, loc);
                 const expectHook = isHookName$2(key);
@@ -31091,6 +31105,7 @@ const FunctionTypeSchema = zod.z.object({
     impure: zod.z.boolean().nullable().optional(),
     canonicalName: zod.z.string().nullable().optional(),
     aliasing: AliasingSignatureSchema.nullable().optional(),
+    knownIncompatible: zod.z.string().nullable().optional(),
 });
 const HookTypeSchema = zod.z.object({
     kind: zod.z.literal('hook'),
@@ -31100,6 +31115,7 @@ const HookTypeSchema = zod.z.object({
     returnValueKind: ValueKindSchema.nullable().optional(),
     noAlias: zod.z.boolean().nullable().optional(),
     aliasing: AliasingSignatureSchema.nullable().optional(),
+    knownIncompatible: zod.z.string().nullable().optional(),
 });
 const BuiltInTypeSchema = zod.z.union([
     zod.z.literal('Any'),
@@ -31601,6 +31617,50 @@ const Resolved = Object.assign(Object.assign({}, Primitives), { nullable(type, p
         };
     } });
 
+function defaultModuleTypeProvider(moduleName) {
+    switch (moduleName) {
+        case 'react-hook-form': {
+            return {
+                kind: 'object',
+                properties: {
+                    useForm: {
+                        kind: 'hook',
+                        returnType: {
+                            kind: 'object',
+                            properties: {
+                                watch: {
+                                    kind: 'function',
+                                    positionalParams: [],
+                                    restParam: Effect.Read,
+                                    calleeEffect: Effect.Read,
+                                    returnType: { kind: 'type', name: 'Any' },
+                                    returnValueKind: ValueKind.Mutable,
+                                    knownIncompatible: `React Hook Form's \`useForm()\` API returns a \`watch()\` function which cannot be memoized safely.`,
+                                },
+                            },
+                        },
+                    },
+                },
+            };
+        }
+        case '@tanstack/react-table': {
+            return {
+                kind: 'object',
+                properties: {
+                    useReactTable: {
+                        kind: 'hook',
+                        positionalParams: [],
+                        restParam: Effect.Read,
+                        returnType: { kind: 'type', name: 'Any' },
+                        knownIncompatible: `TanStack Table's \`useReactTable()\` API returns functions that cannot be memoized safely`,
+                    },
+                },
+            };
+        }
+    }
+    return null;
+}
+
 var _Environment_instances, _Environment_globals, _Environment_shapes, _Environment_moduleTypes, _Environment_nextIdentifer, _Environment_nextBlock, _Environment_nextScope, _Environment_scope, _Environment_outlinedFunctions, _Environment_contextIdentifiers, _Environment_hoistedIdentifiers, _Environment_flowTypeEnvironment, _Environment_resolveModuleType, _Environment_isKnownReactModule, _Environment_getCustomHookType;
 const ReactElementSymbolSchema = zod.z.object({
     elementSymbol: zod.z.union([
@@ -31963,12 +32023,14 @@ class Environment {
     }
 }
 _Environment_globals = new WeakMap(), _Environment_shapes = new WeakMap(), _Environment_moduleTypes = new WeakMap(), _Environment_nextIdentifer = new WeakMap(), _Environment_nextBlock = new WeakMap(), _Environment_nextScope = new WeakMap(), _Environment_scope = new WeakMap(), _Environment_outlinedFunctions = new WeakMap(), _Environment_contextIdentifiers = new WeakMap(), _Environment_hoistedIdentifiers = new WeakMap(), _Environment_flowTypeEnvironment = new WeakMap(), _Environment_instances = new WeakSet(), _Environment_resolveModuleType = function _Environment_resolveModuleType(moduleName, loc) {
+    var _a;
     let moduleType = __classPrivateFieldGet(this, _Environment_moduleTypes, "f").get(moduleName);
     if (moduleType === undefined) {
-        if (this.config.moduleTypeProvider == null) {
+        const moduleTypeProvider = (_a = this.config.moduleTypeProvider) !== null && _a !== void 0 ? _a : defaultModuleTypeProvider;
+        if (moduleTypeProvider == null) {
             return null;
         }
-        const unparsedModuleConfig = this.config.moduleTypeProvider(moduleName);
+        const unparsedModuleConfig = moduleTypeProvider(moduleName);
         if (unparsedModuleConfig != null) {
             const parsedModuleConfig = TypeSchema.safeParse(unparsedModuleConfig);
             if (!parsedModuleConfig.success) {
@@ -40776,6 +40838,25 @@ function computeEffectsForLegacySignature(state, signature, lvalue, receiver, ar
             }),
         });
     }
+    if (signature.knownIncompatible != null && state.env.isInferredMemoEnabled) {
+        const errors = new CompilerError();
+        errors.pushDiagnostic(CompilerDiagnostic.create({
+            category: ErrorCategory.IncompatibleLibrary,
+            severity: ErrorSeverity.IncompatibleLibrary,
+            reason: 'Use of incompatible library',
+            description: [
+                'This API returns functions which cannot be memoized without leading to stale UI. ' +
+                    'To prevent this, by default React Compiler will skip memoizing this component/hook. ' +
+                    'However, you may see issues if values from this API are passed to other components/hooks that are ' +
+                    'memoized.',
+            ].join(''),
+        }).withDetail({
+            kind: 'error',
+            loc: receiver.loc,
+            message: signature.knownIncompatible,
+        }));
+        throw errors;
+    }
     const stores = [];
     const captures = [];
     function visit(place, effect) {
@@ -48253,7 +48334,7 @@ function validateInferredDep(dep, temporaries, declsWithinMemoBlock, validDepsIn
     errorState.pushDiagnostic(CompilerDiagnostic.create({
         category: ErrorCategory.PreserveManualMemo,
         severity: ErrorSeverity.CannotPreserveMemoization,
-        reason: 'Compilation skipped because existing memoization could not be preserved',
+        reason: 'Existing memoization could not be preserved',
         description: [
             'React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. ',
             'The inferred dependencies did not match the manually specified dependencies, which could cause the value to change more or less frequently than expected. ',
@@ -48414,7 +48495,7 @@ class Visitor extends ReactiveFunctionVisitor {
                     state.errors.pushDiagnostic(CompilerDiagnostic.create({
                         category: ErrorCategory.PreserveManualMemo,
                         severity: ErrorSeverity.CannotPreserveMemoization,
-                        reason: 'Compilation skipped because existing memoization could not be preserved',
+                        reason: 'Existing memoization could not be preserved',
                         description: [
                             'React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. ',
                             'This dependency may be mutated later, which could cause the value to change unexpectedly.',
@@ -48451,7 +48532,7 @@ class Visitor extends ReactiveFunctionVisitor {
                             state.errors.pushDiagnostic(CompilerDiagnostic.create({
                                 category: ErrorCategory.PreserveManualMemo,
                                 severity: ErrorSeverity.CannotPreserveMemoization,
-                                reason: 'Compilation skipped because existing memoization could not be preserved',
+                                reason: 'Existing memoization could not be preserved',
                                 description: [
                                     'React Compiler has skipped optimizing this component because the existing manual memoization could not be preserved. This value was memoized in source but not in compilation output. ',
                                     '',

compiled/facebook-www/REVISION

@@ -1 +1 @@
-8d7b5e490320732f40d9c3aa4590b5b0ae5116f5
+4082b0e7d3c042d49ef8987547b923051936956f

compiled/facebook-www/REVISION_TRANSFORMS

@@ -1 +1 @@
-8d7b5e490320732f40d9c3aa4590b5b0ae5116f5
+4082b0e7d3c042d49ef8987547b923051936956f

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

@@ -1409,7 +1409,7 @@ __DEV__ &&
     exports.useTransition = function () {
       return resolveDispatcher().useTransition();
     };
-    exports.version = "19.2.0-www-classic-8d7b5e49-20250827";
+    exports.version = "19.2.0-www-classic-4082b0e7-20250828";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

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

@@ -1409,7 +1409,7 @@ __DEV__ &&
     exports.useTransition = function () {
       return resolveDispatcher().useTransition();
     };
-    exports.version = "19.2.0-www-modern-8d7b5e49-20250827";
+    exports.version = "19.2.0-www-modern-4082b0e7-20250828";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

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

@@ -600,4 +600,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-classic-8d7b5e49-20250827";
+exports.version = "19.2.0-www-classic-4082b0e7-20250828";

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

@@ -600,4 +600,4 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-modern-8d7b5e49-20250827";
+exports.version = "19.2.0-www-modern-4082b0e7-20250828";

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

@@ -604,7 +604,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-classic-8d7b5e49-20250827";
+exports.version = "19.2.0-www-classic-4082b0e7-20250828";
 "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
   "function" ===
     typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

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

@@ -604,7 +604,7 @@ exports.useSyncExternalStore = function (
 exports.useTransition = function () {
   return ReactSharedInternals.H.useTransition();
 };
-exports.version = "19.2.0-www-modern-8d7b5e49-20250827";
+exports.version = "19.2.0-www-modern-4082b0e7-20250828";
 "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
   "function" ===
     typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&

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

@@ -19588,10 +19588,10 @@ __DEV__ &&
     (function () {
       var internals = {
         bundleType: 1,
-        version: "19.2.0-www-classic-8d7b5e49-20250827",
+        version: "19.2.0-www-classic-4082b0e7-20250828",
         rendererPackageName: "react-art",
         currentDispatcherRef: ReactSharedInternals,
-        reconcilerVersion: "19.2.0-www-classic-8d7b5e49-20250827"
+        reconcilerVersion: "19.2.0-www-classic-4082b0e7-20250828"
       };
       internals.overrideHookState = overrideHookState;
       internals.overrideHookStateDeletePath = overrideHookStateDeletePath;
@@ -19625,7 +19625,7 @@ __DEV__ &&
     exports.Shape = Shape;
     exports.Surface = Surface;
     exports.Text = Text;
-    exports.version = "19.2.0-www-classic-8d7b5e49-20250827";
+    exports.version = "19.2.0-www-classic-4082b0e7-20250828";
     "undefined" !== typeof __REACT_DEVTOOLS_GLOBAL_HOOK__ &&
       "function" ===
         typeof __REACT_DEVTOOLS_GLOBAL_HOOK__.registerInternalModuleStop &&