[flow] Basic implementation to incorporate information from jsdoc for custom errors

Summary:
This diff implements the error printing infra for custom error explanations. The high level design is that the documentation should appear as an explanation for types with custom errors. The documentation is extracted from the jsdoc at the `custom_error_loc`.

This diff implements the most basic form of extraction: if available, we will take the `description` part of jsdoc as the explanation. It's certainly not production ready (we probably want to include `example` as well), but it provides the technical viability of this approach. I will use this diff as the baseline to see how custom errors behaves in real code.

Changelog: [internal]

Reviewed By: panagosg7

Differential Revision: D86250573

fbshipit-source-id: 894cdb84c88fe6faf07b5691b788672390a4498c

Author: SamChou19815

src/codemods/annotate_optional_properties.ml

@@ -223,6 +223,7 @@ let mapper ~max_type_size ~default_any (cctx : Codemod_context.Typed.t) =
         Options.unsuppressable_error_codes cctx.Codemod_context.Typed.options
       in
       let loc_of_aloc = Parsing_heaps.Reader_dispatcher.loc_of_aloc ~reader in
+      let get_ast = Parsing_heaps.Reader_dispatcher.get_ast ~reader in
       let suppressions = Context.error_suppressions cx in
       let error_is_suppressed error =
         let (errors, _, _) =
@@ -231,6 +232,7 @@ let mapper ~max_type_size ~default_any (cctx : Codemod_context.Typed.t) =
             ~file_options:None
             ~unsuppressable_error_codes
             ~loc_of_aloc
+            ~get_ast
             suppressions
             (Flow_error.ErrorSet.singleton error)
             ~unused:suppressions

src/flow_dot_js.ml

@@ -15,7 +15,10 @@ let error_of_parse_error source_file (loc, err) =
   Error_message.EParseError (ALoc.of_loc loc, err)
   |> Flow_error.error_of_msg ~source_file
   |> Flow_intermediate_error.make_intermediate_error ~loc_of_aloc
-  |> Flow_intermediate_error.to_printable_error ~loc_of_aloc ~strip_root:None
+  |> Flow_intermediate_error.to_printable_error
+       ~loc_of_aloc
+       ~get_ast:(fun _ -> None)
+       ~strip_root:None
 
 let parse_content file content =
   let parse_options = Some Parser_env.permissive_parse_options in
@@ -333,6 +336,7 @@ let check_content ~filename ~content ~js_config_object =
           ~file_options:None
           ~unsuppressable_error_codes:SSet.empty
           ~loc_of_aloc
+          ~get_ast:(fun _ -> None)
           suppressions
           errors
           ~unused:suppressions
@@ -343,6 +347,7 @@ let check_content ~filename ~content ~js_config_object =
           ~file_options:None
           ~unsuppressable_error_codes:SSet.empty
           ~loc_of_aloc
+          ~get_ast:(fun _ -> None)
           suppressions
           warnings
           ~unused:suppressions

src/parser/jsdoc.mli

@@ -53,4 +53,6 @@ val unrecognized_tags : t -> Unrecognized_tags.t
 (* parsing *)
 (***********)
 
+val parse : string -> t option
+
 val of_comments : ('M, 'T) Flow_ast.Syntax.t option -> ('M * t) option

src/server/command_handler/commandHandler.ml

@@ -324,6 +324,7 @@ let get_status ~options ~reader env =
     let to_printable =
       Flow_intermediate_error.to_printable_error
         ~loc_of_aloc:(Parsing_heaps.Reader.loc_of_aloc ~reader)
+        ~get_ast:(Parsing_heaps.Reader.get_ast ~reader)
         ~strip_root:(Base.Option.some_if (Options.should_strip_root options) (Options.root options))
     in
     let suppressed_errors =

src/server/error_collator/errorCollator.ml

@@ -33,7 +33,10 @@ let add_suppression_warnings root checked unused warnings =
             let msg = Error_message.EUnusedSuppression loc in
             Flow_error.error_of_msg ~source_file msg
             |> Flow_intermediate_error.make_intermediate_error ~loc_of_aloc:Fun.id
-            |> Flow_intermediate_error.to_printable_error ~loc_of_aloc:Fun.id ~strip_root:(Some root)
+            |> Flow_intermediate_error.to_printable_error
+                 ~loc_of_aloc:Fun.id
+                 ~get_ast:(fun _ -> None)
+                 ~strip_root:(Some root)
           in
           let file_warnings =
             FilenameMap.find_opt source_file warnings
@@ -56,7 +59,10 @@ let collate_duplicate_providers ~update root =
       Error_message.EDuplicateModuleProvider { module_name; provider; conflict }
       |> Flow_error.error_of_msg ~source_file:duplicate
       |> Flow_intermediate_error.make_intermediate_error ~loc_of_aloc:Fun.id
-      |> Flow_intermediate_error.to_printable_error ~loc_of_aloc:Fun.id ~strip_root:(Some root)
+      |> Flow_intermediate_error.to_printable_error
+           ~loc_of_aloc:Fun.id
+           ~get_ast:(fun _ -> None)
+           ~strip_root:(Some root)
     in
     update provider_file duplicate err acc
   in
@@ -70,6 +76,7 @@ let update_local_collated_errors ~reader ~options suppressions errors acc =
   let root = Options.root options in
   let unsuppressable_error_codes = Options.unsuppressable_error_codes options in
   let loc_of_aloc = Parsing_heaps.Reader_dispatcher.loc_of_aloc ~reader in
+  let get_ast = Parsing_heaps.Reader_dispatcher.get_ast ~reader in
   let collated_local_errors =
     FilenameMap.fold
       (fun filename file_errs errors ->
@@ -82,6 +89,7 @@ let update_local_collated_errors ~reader ~options suppressions errors acc =
             ~file_options
             ~unsuppressable_error_codes
             ~loc_of_aloc
+            ~get_ast
             suppressions
             file_errs
             ~unused:Error_suppressions.empty
@@ -97,6 +105,7 @@ let update_collated_errors ~reader ~options ~checked_files ~all_suppressions err
   let unsuppressable_error_codes = Options.unsuppressable_error_codes options in
   let { local_errors; duplicate_providers; merge_errors; warnings; suppressions } = errors in
   let loc_of_aloc = Parsing_heaps.Reader_dispatcher.loc_of_aloc ~reader in
+  let get_ast = Parsing_heaps.Reader_dispatcher.get_ast ~reader in
   let acc_fun filename file_errs (errors, suppressed, unused) =
     let file_options = Some (Options.file_options options) in
     let (file_errs, file_suppressed, unused) =
@@ -105,6 +114,7 @@ let update_collated_errors ~reader ~options ~checked_files ~all_suppressions err
         ~file_options
         ~unsuppressable_error_codes
         ~loc_of_aloc
+        ~get_ast
         (* Use all_suppressions here to account for misplaced errors. *)
         all_suppressions
         file_errs

src/server/server.ml

@@ -394,10 +394,11 @@ let check_once ~init_id ~shared_mem_config ~format_errors ?focus_targets options
                 let to_printable =
                   let reader = State_reader.create () in
                   let loc_of_aloc = Parsing_heaps.Reader.loc_of_aloc ~reader in
+                  let get_ast = Parsing_heaps.Reader.get_ast ~reader in
                   let strip_root =
                     Base.Option.some_if (Options.should_strip_root options) (Options.root options)
                   in
-                  Flow_intermediate_error.to_printable_error ~loc_of_aloc ~strip_root
+                  Flow_intermediate_error.to_printable_error ~loc_of_aloc ~get_ast ~strip_root
                 in
                 let suppressed_errors =
                   if Options.include_suppressions options then

src/services/autocomplete/autocompleteService_js.ml

@@ -2135,7 +2135,10 @@ let applicable_error_codes ~loc_of_aloc ~cx comment_loc =
         let err =
           err
           |> Flow_intermediate_error.make_intermediate_error ~loc_of_aloc
-          |> Flow_intermediate_error.to_printable_error ~loc_of_aloc ~strip_root
+          |> Flow_intermediate_error.to_printable_error
+               ~loc_of_aloc
+               ~get_ast:(fun _ -> None)
+               ~strip_root
         in
         let loc = Flow_errors_utils.loc_of_printable_error err in
         match Flow_errors_utils.code_of_printable_error err with

src/services/inference/type_contents.ml

@@ -78,7 +78,7 @@ let parse_contents ~options ~profiling contents filename =
       | Skipped -> (None, Flow_error.ErrorSet.empty)
   )
 
-let errors_of_file_artifacts ~options ~env ~loc_of_aloc ~filename ~file_artifacts =
+let errors_of_file_artifacts ~options ~env ~loc_of_aloc ~get_ast ~filename ~file_artifacts =
   (* Callers have already had a chance to inspect parse errors, so they are not included here.
    * Typically, type errors in the face of parse errors are meaningless, so callers should probably
    * not call this function if parse errors have been found. *)
@@ -126,6 +126,7 @@ let errors_of_file_artifacts ~options ~env ~loc_of_aloc ~filename ~file_artifact
       ~file_options
       ~unsuppressable_error_codes
       ~loc_of_aloc
+      ~get_ast
       suppressions
       errors
       ~unused:Error_suppressions.empty
@@ -138,6 +139,7 @@ let errors_of_file_artifacts ~options ~env ~loc_of_aloc ~filename ~file_artifact
       ~file_options
       ~unsuppressable_error_codes
       ~loc_of_aloc
+      ~get_ast
       suppressions
       warnings
       ~unused:Error_suppressions.empty
@@ -155,15 +157,20 @@ let printable_errors_of_file_artifacts_result ~options ~env filename result =
   let root = Options.root options in
   let reader = State_reader.create () in
   let loc_of_aloc = Parsing_heaps.Reader.loc_of_aloc ~reader in
+  let get_ast = Parsing_heaps.Reader.get_ast ~reader in
   match result with
   | Ok file_artifacts ->
     let (errors, warnings) =
-      errors_of_file_artifacts ~options ~env ~loc_of_aloc ~filename ~file_artifacts
+      errors_of_file_artifacts ~options ~env ~loc_of_aloc ~get_ast ~filename ~file_artifacts
     in
     (errors, warnings)
   | Error errors ->
     let errors =
-      Flow_intermediate_error.make_errors_printable ~loc_of_aloc ~strip_root:(Some root) errors
+      Flow_intermediate_error.make_errors_printable
+        ~loc_of_aloc
+        ~get_ast
+        ~strip_root:(Some root)
+        errors
     in
     (errors, Flow_errors_utils.ConcreteLocPrintableErrorSet.empty)
 

src/services/inference/types_js.ml

@@ -328,6 +328,7 @@ let run_merge_service
 let mk_intermediate_result_callback ~reader ~options ~persistent_connections suppressions () =
   let open Flow_errors_utils in
   let loc_of_aloc = Parsing_heaps.Mutator_reader.loc_of_aloc ~reader in
+  let get_ast = Parsing_heaps.Mutator_reader.get_ast ~reader in
   let root = Options.root options in
   let file_options = Some (Options.file_options options) in
   let unsuppressable_error_codes = Options.unsuppressable_error_codes options in
@@ -342,6 +343,7 @@ let mk_intermediate_result_callback ~reader ~options ~persistent_connections sup
         ~file_options
         ~unsuppressable_error_codes
         ~loc_of_aloc
+        ~get_ast
         suppressions
         errors
         ~unused:Error_suppressions.empty
@@ -352,6 +354,7 @@ let mk_intermediate_result_callback ~reader ~options ~persistent_connections sup
         ~file_options:None
         ~unsuppressable_error_codes
         ~loc_of_aloc
+        ~get_ast
         suppressions
         warnings
         ~unused:Error_suppressions.empty
@@ -885,6 +888,7 @@ end = struct
       ~files_to_force
       ~env =
     let loc_of_aloc = Parsing_heaps.Mutator_reader.loc_of_aloc ~reader in
+    let get_ast = Parsing_heaps.Mutator_reader.get_ast ~reader in
     let errors = env.ServerEnv.errors in
     let collated_errors = env.ServerEnv.collated_errors in
     (* files_to_force is a request to promote certain files to be checked as a dependency, dependent,
@@ -955,6 +959,7 @@ end = struct
         let errors =
           Flow_intermediate_error.make_errors_printable
             ~loc_of_aloc
+            ~get_ast
             ~strip_root:(Some (Options.root options))
             errors
         in

src/typing/errors/error_suppressions.ml

@@ -263,7 +263,14 @@ let all_unused_locs map =
     LocSet.empty
 
 let filter_suppressed_errors
-    ~root ~file_options ~unsuppressable_error_codes ~loc_of_aloc suppressions errors ~unused =
+    ~root
+    ~file_options
+    ~unsuppressable_error_codes
+    ~loc_of_aloc
+    ~get_ast
+    suppressions
+    errors
+    ~unused =
   (* Filter out suppressed errors. also track which suppressions are used. *)
   Flow_error.ErrorSet.fold
     (fun error ((errors, suppressed, unused) as acc) ->
@@ -283,7 +290,11 @@ let filter_suppressed_errors
             | _ -> error
           in
           let error =
-            Flow_intermediate_error.to_printable_error ~loc_of_aloc ~strip_root:(Some root) error
+            Flow_intermediate_error.to_printable_error
+              ~loc_of_aloc
+              ~get_ast
+              ~strip_root:(Some root)
+              error
           in
           (Flow_errors_utils.ConcreteLocPrintableErrorSet.add error errors, suppressed, unused)))
     errors