[flow] Introduce opaque underlying type variant to prepare for custom errors

Summary:
This diff changes the simple `Type.t option` that's the backing storage of the underlying type of opaque type to a 3-member variant:

```
type underlying_t =
    | FullyOpaque
    | NormalUnderlying of { t: TypeTerm.t }
    | FullyTransparentForCustomError of {
        custom_error_loc: ALoc.t;
        t: TypeTerm.t;
      }
```

, where `FullyOpaque` and `NormalUnderlying` mapped to the previous `None` and `Some` case, and the new `FullyTransparentForCustomError` is introduced for custom errors.

`FullyTransparentForCustomError` behaves almost exactly the same as `NormalUnderlying`, except that, as the name suggests, it will always be transparent (while NormalUnderlying is only transparent while the same-file reason check passes).

I believe the design balances between not changing type checking behavior while also gives us a reliable marker for types with custom errors. The opaque type design is battle tested, so I believe we should use it instead of patching more reasons.

For now, nothing uses the new `FullyTransparentForCustomError` yet.

Changelog: [internal]

Reviewed By: panagosg7

Differential Revision: D86207093

fbshipit-source-id: b7231197277cedbfc0f502200de9a41a416d4ae9

Author: SamChou19815

src/typing/annotation_inference.ml

@@ -704,9 +704,16 @@ module rec ConsGen : S = struct
     (****************)
     | (OpaqueT (_, { upper_t = Some upper_t; _ }), Annot_ToStringT { reason; _ }) ->
       elab_t cx upper_t (Annot_ToStringT { orig_t = Some t; reason })
-    | (OpaqueT (r, { underlying_t = Some t; _ }), _)
+    | (OpaqueT (r, { underlying_t = Opaque.NormalUnderlying { t }; _ }), _)
       when ALoc.source (loc_of_reason r) = ALoc.source (def_loc_of_reason r) ->
       elab_t cx ~seen t op
+    | ( OpaqueT
+          ( _,
+            { underlying_t = Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ }; _ }
+          ),
+        _
+      ) ->
+      elab_t cx ~seen t op
     (********)
     (* Keys *)
     (********)

src/typing/concrete_type_eq.ml

@@ -23,7 +23,12 @@ let rec swap_reason t2 t1 =
     ) ->
     let underlying_t =
       match (repr1, repr2) with
-      | (Some t1, Some t2) -> Some (swap_reason t2 t1)
+      | ( Opaque.FullyTransparentForCustomError { t = t1; custom_error_loc = _ },
+          Opaque.FullyTransparentForCustomError { t = t2; custom_error_loc }
+        ) ->
+        Opaque.FullyTransparentForCustomError { custom_error_loc; t = swap_reason t2 t1 }
+      | (Opaque.NormalUnderlying { t = t1 }, Opaque.NormalUnderlying { t = t2 }) ->
+        Opaque.NormalUnderlying { t = swap_reason t2 t1 }
       | _ -> repr2
     in
     let lower_t =

src/typing/convertTypes.ml

@@ -200,8 +200,10 @@ and type_to_json : Context.t -> int -> t -> json =
                 ("opaque_id", JSON_String (Opaque.string_of_id opaquetype.opaque_id));
                 ( "underlying_t",
                   match opaquetype.underlying_t with
-                  | None -> JSON_Null
-                  | Some t -> type_to_json cx (depth - 1) t
+                  | Opaque.FullyOpaque -> JSON_Null
+                  | Opaque.FullyTransparentForCustomError { t; _ }
+                  | Opaque.NormalUnderlying { t; _ } ->
+                    type_to_json cx (depth - 1) t
                 );
                 ( "super_t",
                   match opaquetype.upper_t with

src/typing/debug_js.ml

@@ -269,7 +269,11 @@ let rec dump_t_ (depth, tvars) cx t =
                  )
                 )
              )
-             (Base.Option.value_map underlying_t ~default:"" ~f:(fun t -> spf " (%s)" (kid t)))
+             (match underlying_t with
+             | Opaque.NormalUnderlying { t } -> spf " (%s)" (kid t)
+             | Opaque.FullyTransparentForCustomError { t; custom_error_loc } ->
+               spf " (%s, custom_error_loc=%s)" (kid t) (ALoc.debug_to_string custom_error_loc)
+             | Opaque.FullyOpaque -> "")
           )
         t
     | OptionalT { reason = _; type_ = arg; use_desc = _ } -> p ~extra:(kid arg) t

src/typing/flow_js.ml

@@ -1411,14 +1411,25 @@ struct
               ( _,
                 {
                   opaque_id = Opaque.UserDefinedOpaqueTypeId (opaque_id, _);
-                  underlying_t = Some t;
+                  underlying_t = Opaque.NormalUnderlying { t };
                   _;
                 }
               ),
             ToStringT { reason; t_out; _ }
           )
           when ALoc.source (opaque_id :> ALoc.t) = Some (Context.file cx) ->
           rec_flow cx trace (t, ToStringT { orig_t = Some l; reason; t_out })
+        | ( OpaqueT
+              ( _,
+                {
+                  opaque_id = Opaque.UserDefinedOpaqueTypeId _;
+                  underlying_t = Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ };
+                  _;
+                }
+              ),
+            ToStringT { reason; t_out; _ }
+          ) ->
+          rec_flow cx trace (t, ToStringT { orig_t = Some l; reason; t_out })
         (* Use the upper bound of OpaqueT if it's available, for operations that must be
          * performed on some concretized types. *)
         | (OpaqueT (_, { upper_t = Some t; _ }), ObjKitT _)
@@ -1434,14 +1445,25 @@ struct
               ( _,
                 {
                   opaque_id = Opaque.UserDefinedOpaqueTypeId (opaque_id, _);
-                  underlying_t = Some t;
+                  underlying_t = Opaque.NormalUnderlying { t; _ };
                   _;
                 }
               ),
             _
           )
           when ALoc.source (opaque_id :> ALoc.t) = Some (Context.file cx) ->
           rec_flow cx trace (t, u)
+        | ( OpaqueT
+              ( _,
+                {
+                  opaque_id = Opaque.UserDefinedOpaqueTypeId _;
+                  underlying_t = Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ };
+                  _;
+                }
+              ),
+            _
+          ) ->
+          rec_flow cx trace (t, u)
         (*****************************************************)
         (* keys (NOTE: currently we only support string keys *)
         (*****************************************************)
@@ -5528,10 +5550,17 @@ struct
             )
         )
     | OpaqueT (r, ({ underlying_t; lower_t; upper_t; opaque_type_args; _ } as opaquetype)) ->
+      let underlying_t =
+        match underlying_t with
+        | Opaque.FullyOpaque -> Opaque.FullyOpaque
+        | Opaque.FullyTransparentForCustomError { t; custom_error_loc } ->
+          Opaque.FullyTransparentForCustomError { t = only_any t; custom_error_loc }
+        | Opaque.NormalUnderlying { t } -> Opaque.NormalUnderlying { t = only_any t }
+      in
       let opaquetype =
         {
           opaquetype with
-          underlying_t = Base.Option.(underlying_t >>| only_any);
+          underlying_t;
           lower_t = Base.Option.(lower_t >>| only_any);
           upper_t = Base.Option.(upper_t >>| only_any);
           opaque_type_args =
@@ -6412,7 +6441,13 @@ struct
            * lower_t to be inspectable *)
           eagerly_eval_destructor_if_resolved cx ~trace use_op reason t d tvar
         in
-        let underlying_t = Base.Option.map ~f:eval_t underlying_t in
+        let underlying_t =
+          match underlying_t with
+          | Opaque.FullyOpaque -> Opaque.FullyOpaque
+          | Opaque.FullyTransparentForCustomError { t; custom_error_loc } ->
+            Opaque.FullyTransparentForCustomError { t = eval_t t; custom_error_loc }
+          | Opaque.NormalUnderlying { t } -> Opaque.NormalUnderlying { t = eval_t t }
+        in
         let lower_t = Base.Option.map ~f:eval_t lower_t in
         let upper_t = Base.Option.map ~f:eval_t upper_t in
         let opaque_t = OpaqueT (r, { opaquetype with underlying_t; lower_t; upper_t }) in
@@ -6438,7 +6473,7 @@ struct
                   ( _,
                     {
                       opaque_id = Opaque.UserDefinedOpaqueTypeId (opaque_id, _);
-                      underlying_t = Some t;
+                      underlying_t = Opaque.NormalUnderlying { t };
                       _;
                     }
                   );
@@ -6458,13 +6493,57 @@ struct
           (GenericT { bound = t; reason = r; id; name; no_infer })
           d
           tout
+      | ( GenericT
+            {
+              bound =
+                OpaqueT
+                  ( _,
+                    {
+                      opaque_id = Opaque.UserDefinedOpaqueTypeId _;
+                      underlying_t =
+                        Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ };
+                      _;
+                    }
+                  );
+              reason = r;
+              id;
+              name;
+              no_infer;
+            },
+          _
+        ) ->
+        eval_destructor
+          cx
+          ~trace
+          use_op
+          reason
+          (GenericT { bound = t; reason = r; id; name; no_infer })
+          d
+          tout
       | (OpaqueT (r, opaquetype), ReactDRO _) -> destruct_and_preserve_opaque_t r opaquetype
       | ( OpaqueT
-            (_, { opaque_id = Opaque.UserDefinedOpaqueTypeId (id, _); underlying_t = Some t; _ }),
+            ( _,
+              {
+                opaque_id = Opaque.UserDefinedOpaqueTypeId (id, _);
+                underlying_t = Opaque.NormalUnderlying { t };
+                _;
+              }
+            ),
           _
         )
         when ALoc.source (id :> ALoc.t) = Some (Context.file cx) ->
         eval_destructor cx ~trace use_op reason t d tout
+      | ( OpaqueT
+            ( _,
+              {
+                opaque_id = Opaque.UserDefinedOpaqueTypeId _;
+                underlying_t = Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ };
+                _;
+              }
+            ),
+          _
+        ) ->
+        eval_destructor cx ~trace use_op reason t d tout
       (* Specialize TypeAppTs before evaluating them so that we can handle special
          cases. Like the union case below. mk_typeapp_instance will return an AnnotT
          which will be fully resolved using the AnnotT case above. *)
@@ -6836,7 +6915,7 @@ struct
                   ( reason,
                     {
                       opaque_id = Opaque.StuckEval stuck_eval_kind;
-                      underlying_t = None;
+                      underlying_t = Opaque.FullyOpaque;
                       lower_t = None;
                       upper_t;
                       opaque_type_args;
@@ -9195,11 +9274,27 @@ struct
         UnionT (r, rep)
       | OpaqueT (r, opaquetype) ->
         let r = mod_reason r in
+        let underlying_t =
+          match opaquetype.underlying_t with
+          | Opaque.FullyOpaque -> opaquetype.underlying_t
+          | Opaque.NormalUnderlying { t } ->
+            let t' = recurse seen t in
+            if t == t' then
+              opaquetype.underlying_t
+            else
+              Opaque.NormalUnderlying { t = t' }
+          | Opaque.FullyTransparentForCustomError { t; custom_error_loc } ->
+            let t' = recurse seen t in
+            if t == t' then
+              opaquetype.underlying_t
+            else
+              Opaque.FullyTransparentForCustomError { t = t'; custom_error_loc }
+        in
         OpaqueT
           ( r,
             {
               opaquetype with
-              underlying_t = OptionUtils.ident_map (recurse seen) opaquetype.underlying_t;
+              underlying_t;
               lower_t = OptionUtils.ident_map (recurse seen) opaquetype.lower_t;
               upper_t = OptionUtils.ident_map (recurse seen) opaquetype.upper_t;
             }

src/typing/implicit_instantiation.ml

@@ -1814,7 +1814,7 @@ module Kit (FlowJs : Flow_common.S) (Instantiation_helper : Flow_js_utils.Instan
                 ( reason,
                   {
                     opaque_id = Opaque.(StuckEval StuckEvalForConditionalType);
-                    underlying_t = None;
+                    underlying_t = Opaque.FullyOpaque;
                     lower_t = None;
                     upper_t = Some bound;
                     opaque_type_args;

src/typing/members.ml

@@ -580,7 +580,15 @@ let rec extract_type cx this_t =
   | DefT (reason, SymbolT) -> get_builtin_type cx reason "Symbol" |> extract_type cx
   | DefT (_, ReactAbstractComponentT _) as t -> Success t
   | DefT (_, RendersT _) as t -> Success t
-  | OpaqueT (_, { underlying_t = Some t; _ })
+  | OpaqueT
+      ( _,
+        {
+          underlying_t =
+            ( Opaque.NormalUnderlying { t }
+            | Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ } );
+          _;
+        }
+      )
   | OpaqueT (_, { upper_t = Some t; _ }) ->
     extract_type cx t
   | DefT (reason, ArrT arrtype) ->

src/typing/merge_js.ml

@@ -67,8 +67,16 @@ let detect_sketchy_null_checks cx tast =
         (* Ignore AnyTs for sketchy null checks; otherwise they'd always trigger the lint. *)
         | AnyT _ -> cur_checks
         | GenericT { bound = t; _ }
-        | OpaqueT (_, { underlying_t = Some t; _ })
-        | OpaqueT (_, { underlying_t = None; upper_t = Some t; _ }) ->
+        | OpaqueT
+            ( _,
+              {
+                underlying_t =
+                  ( Opaque.NormalUnderlying { t }
+                  | Opaque.FullyTransparentForCustomError { t; custom_error_loc = _ } );
+                _;
+              }
+            )
+        | OpaqueT (_, { underlying_t = Opaque.FullyOpaque; upper_t = Some t; _ }) ->
           make_checks seen cur_checks loc t
         | MaybeT (r, t) ->
           let acc = make_checks seen cur_checks loc t in
@@ -732,7 +740,7 @@ let enforce_optimize cx loc t =
       ( reason,
         {
           opaque_id = Opaque.InternalEnforceUnionOptimized;
-          underlying_t = None;
+          underlying_t = Opaque.FullyOpaque;
           lower_t = None;
           upper_t = None;
           opaque_type_args = [];

src/typing/predicate_kit.ml

@@ -608,7 +608,13 @@ and intersect =
         let upper_t =
           Some (Base.Option.value_map upper_t ~default:t2 ~f:(fun t -> intersect cx t t2))
         in
-        let underlying_t = Base.Option.map ~f:(fun t -> intersect cx t t2) underlying_t in
+        let underlying_t =
+          match underlying_t with
+          | Opaque.FullyOpaque -> Opaque.FullyOpaque
+          | Opaque.FullyTransparentForCustomError { custom_error_loc; t } ->
+            Opaque.FullyTransparentForCustomError { custom_error_loc; t = intersect cx t t2 }
+          | Opaque.NormalUnderlying { t } -> Opaque.NormalUnderlying { t = intersect cx t t2 }
+        in
         Some (OpaqueT (r, { opaquetype with underlying_t; upper_t }))
       | _ -> None
   in

src/typing/react_rules.ml

@@ -35,7 +35,12 @@ let check_ref_use cx rrid in_hook var_reason kind t =
       when Base.Option.value_map ~default:false ~f:(( = ) opaque_id) rrid ->
       [Error_message.EReactRefInRender { usage = var_reason; kind; in_hook }]
     | OpaqueT (_, { underlying_t; upper_t; _ }) ->
-      Base.Option.value_map ~default:[] ~f:recur underlying_t
+      begin
+        match underlying_t with
+        | Type.Opaque.NormalUnderlying { t } -> recur t
+        | Type.Opaque.FullyTransparentForCustomError { t; _ } -> recur t
+        | Type.Opaque.FullyOpaque -> []
+      end
       @ Base.Option.value_map ~default:[] ~f:recur upper_t
     | OpenT (_, id) when ISet.mem id seen -> []
     | OpenT (_, id) ->
@@ -106,9 +111,10 @@ let hook_callee cx t =
     | DefT (r, FunT (_, { effect_ = ArbitraryEffect; _ })) -> NotHookCallee (set_of_reason r)
     | OpaqueT (_, { underlying_t; upper_t; _ }) -> begin
       match (underlying_t, upper_t) with
-      | (Some t, _)
-      | (None, Some t) ->
+      | (Type.Opaque.NormalUnderlying { t }, _)
+      | (Type.Opaque.FullyTransparentForCustomError { t; _ }, _) ->
         recur t
+      | (Type.Opaque.FullyOpaque, Some t) -> recur t
       | _ -> AnyCallee
     end
     | OpenT (_, id) when ISet.mem id seen -> AnyCallee