destructure record rest elements (#8317)

* destructure record rest elements - fixes #8311

* support type with parameter for record rest

* simplify parsing of record rest

* update record spread error message

* improve error message of superfluous fields in rest

* improve error message of non optional rest field already matched

* add a warning when rest record would be empty

* add fixture tests for error/warning messages

* add changelog

* address comments (parsetree0 PPX roundtrips, nested rest, etc)

* support rest of inline record

* check rest field types, fix matching & invalid field identifier

* fix rest of private type and analysis

* use runtime field names for rest

* support record type alias in rest

* fix compiler crash when spreading the whole record

* disallow rest spreading on packed modules

* add tests for record rest with namespaced type

* make sure rest is used and move logic to its own files

* stop ignoring _rest in a few more places

* format

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* improve output (compile to JS destructuring)

* update changelog

* remove leading _ of used variable

* add more tests

* disallow spreading rest to unboxed record

* address #8317 (comment)

* document type_record_pat_rest function

* add comment about Tpat_record rest

* forbid destructure to rest of record with mutable fields

* do not spread function params to avoid issues with 'use strict'

* fix comment table for rest spread

* Include record rest binders in rec check

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* Track record rest types in dead analysis

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* Rename record rest test config fixture

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* add a warning for optional field overlap

* no longer drop rest when printing pattern

* make Parmatch.Conv.conv no longer drop rest

* remove unused Object_rest_param

* use internal attribute for ast mapper

* improve completion support for record rest destructuring

* simplify js dump shape

* simplify materialize_fields

* improve record rest completion

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* print record rest in typedtree dumps

Signed-off-by: tsnobip <dontshootthink@gmail.com>

* simplify record rest implementation

* restore better JS output for rest destructuring

---------

Signed-off-by: tsnobip <dontshootthink@gmail.com>

Author: tsnobip

CHANGELOG.md

@@ -24,6 +24,7 @@
 
 - Add a first-class `taggedTemplate<'param, 'output>` builtin type and the `TaggedTemplate` stdlib module (`TaggedTemplate.make`). Tagged-template tags are now tracked through the type system, so they emit real JS tagged-template syntax across module boundaries, when passed as first-class values, and when constructed at runtime by a factory (e.g. `postgres`). https://github.com/rescript-lang/rescript/pull/8461
 - Make mutation of private record mutable fields a configurable warning instead of a hard error. https://github.com/rescript-lang/rescript/pull/8366
+- Add support for pattern matching/destructuring of record rest. https://github.com/rescript-lang/rescript/pull/8317
 
 #### :bug: Bug fix
 

analysis/reanalyze/src/dead_value.ml

@@ -230,16 +230,78 @@ let rec collect_expr ~config ~refs ~file_deps ~cross_file
   With this annotation we declare a new type for each branch to allow the
   function to be typed.
   *)
-let collect_pattern ~config ~refs :
+let type_path_candidates ~file ~(module_path : Module_path.t) path =
+  let path = Dce_path.from_path_t path in
+  let module_context =
+    module_path.path @ [File_context.module_name_tagged file]
+  in
+  let add_unique paths path =
+    if List.exists (fun existing -> existing = path) paths then paths
+    else path :: paths
+  in
+  [path; path @ module_context]
+  |> List.fold_left
+       (fun paths path ->
+         [
+           path;
+           Dce_path.module_to_implementation path;
+           Dce_path.module_to_interface path;
+         ]
+         |> List.fold_left add_unique paths)
+       []
+
+let add_record_label_type_references ~config ~refs ~pos_from labels =
+  labels
+  |> List.iter (fun {Types.ld_loc = {loc_start = pos_to; loc_ghost}; _} ->
+         if not loc_ghost then
+           Dead_type.add_type_reference ~config ~refs ~pos_from ~pos_to)
+
+let add_record_rest_type_references_from_path ~config ~decls ~refs ~file
+    ~module_path ~pos_from rest =
+  if !Config.analyze_types then
+    match (Ctype.repr rest.Typedtree.rest_type).desc with
+    | Types.Tconstr (path, _, _) ->
+      let type_paths = type_path_candidates ~file ~module_path path in
+      decls |> Declarations.builder_to_list
+      |> List.iter (fun (_, decl) ->
+             match (decl.Decl.decl_kind, decl.path) with
+             | RecordLabel, _label :: type_path
+               when List.exists
+                      (fun candidate -> candidate = type_path)
+                      type_paths ->
+               Dead_type.add_type_reference ~config ~refs ~pos_from
+                 ~pos_to:decl.pos
+             | _ -> ())
+    | _ -> ()
+
+let add_record_rest_type_references ~config ~decls ~refs ~file ~module_path
+    ~pos_from ~env rest =
+  if !Config.analyze_types then
+    match
+      try Some (Ctype.extract_concrete_typedecl env rest.Typedtree.rest_type)
+      with Not_found -> None
+    with
+    | Some (_, _, {Types.type_kind = Type_record (labels, _)}) ->
+      add_record_label_type_references ~config ~refs ~pos_from labels
+    | _ ->
+      add_record_rest_type_references_from_path ~config ~decls ~refs ~file
+        ~module_path ~pos_from rest
+
+let collect_pattern ~config ~decls ~refs ~file ~module_path :
     _ -> _ -> Typedtree.pattern -> Typedtree.pattern =
  fun super self pat ->
   let pos_from = pat.Typedtree.pat_loc.loc_start in
   (match pat.pat_desc with
-  | Typedtree.Tpat_record (cases, _clodsedFlag) ->
+  | Typedtree.Tpat_record (cases, _clodsedFlag, rest) -> (
     cases
     |> List.iter (fun (_loc, {Types.lbl_loc = {loc_start = pos_to}}, _pat, _) ->
            if !Config.analyze_types then
-             Dead_type.add_type_reference ~config ~refs ~pos_from ~pos_to)
+             Dead_type.add_type_reference ~config ~refs ~pos_from ~pos_to);
+    match rest with
+    | None -> ()
+    | Some rest ->
+      add_record_rest_type_references ~config ~decls ~refs ~file ~module_path
+        ~pos_from:rest.rest_name.loc.loc_start ~env:pat.pat_env rest)
   | _ -> ());
   super.Tast_mapper.pat self pat
 
@@ -331,7 +393,11 @@ let traverse_structure ~config ~decls ~refs ~file_deps ~cross_file ~file
             e
             |> collect_expr ~config ~refs ~file_deps ~cross_file ~last_binding
                  super mapper);
-        pat = (fun _self p -> p |> collect_pattern ~config ~refs super mapper);
+        pat =
+          (fun _self p ->
+            p
+            |> collect_pattern ~config ~decls ~refs ~file ~module_path super
+                 mapper);
         structure_item =
           (fun _self (structure_item : Typedtree.structure_item) ->
             let modulePath_for_item_opt =

analysis/src/completion_front_end.ml

@@ -517,7 +517,7 @@ let completion_with_parser1 ~debug ~offset ~pos_cursor ~kind_file
           (NPolyvariantPayload {item_num = 0; constructor_name = txt}
           :: pattern_path)
         ?context_path p
-    | Ppat_record (fields, _) ->
+    | Ppat_record (fields, _, rest) -> (
       Ext_list.iter fields (fun {lid = fname; x = p} ->
           match fname with
           | {Location.txt = Longident.Lident fname} ->
@@ -526,7 +526,16 @@ let completion_with_parser1 ~debug ~offset ~pos_cursor ~kind_file
                 (Completable.NFollowRecordField {field_name = fname}
                 :: pattern_path)
               ?context_path p
-          | _ -> ())
+          | _ -> ());
+      match rest with
+      | None -> ()
+      | Some {rest_name = {txt; loc}; rest_type; _} ->
+        let context_path =
+          match rest_type with
+          | Some typ -> Type_utils.context_path_from_core_type typ
+          | None -> context_path_to_save
+        in
+        scope := !scope |> Scope.add_value ~name:txt ~loc ?context_path)
     | Ppat_array pl ->
       pl
       |> List.iter

analysis/src/completion_patterns.ml

@@ -48,6 +48,13 @@ and traverse_pattern (pat : Parsetree.pattern) ~pattern_path ~loc_has_cursor
       Some v)
     else None
   in
+  let rest_cursor (rest : Parsetree.record_pat_rest option) =
+    match rest with
+    | Some {rest_name = {txt; loc}; _} when loc_has_cursor loc ->
+      Some (`Name txt)
+    | Some {rest_loc; _} when loc_has_cursor rest_loc -> Some `Rest
+    | _ -> None
+  in
   match pat.ppat_desc with
   | Ppat_constant _ | Ppat_interval _ -> None
   | Ppat_constraint (p, _)
@@ -106,12 +113,16 @@ and traverse_pattern (pat : Parsetree.pattern) ~pattern_path ~loc_has_cursor
            [Completable.NTupleItem {item_num}] @ pattern_path)
          ~result_from_found_item_num:(fun item_num ->
            [Completable.NTupleItem {item_num = item_num + 1}] @ pattern_path)
-  | Ppat_record ([], _) ->
+  | Ppat_record ([], _, rest) -> (
     (* Empty fields means we're in a record body `{}`. Complete for the fields. *)
-    some_if_has_cursor
-      ("", [Completable.NRecordBody {seen_fields = []}] @ pattern_path)
-      "Ppat_record(empty)"
-  | Ppat_record (fields, _) -> (
+    match rest_cursor rest with
+    | Some (`Name txt) -> Some (txt, pattern_path)
+    | Some `Rest -> None
+    | None ->
+      some_if_has_cursor
+        ("", [Completable.NRecordBody {seen_fields = []}] @ pattern_path)
+        "Ppat_record(empty)")
+  | Ppat_record (fields, _, rest) -> (
     let field_with_cursor = ref None in
     let field_with_pat_hole = ref None in
     Ext_list.iter fields (fun {lid = fname; x = f} ->
@@ -131,8 +142,10 @@ and traverse_pattern (pat : Parsetree.pattern) ~pattern_path ~loc_has_cursor
           | {Location.txt = Longident.Lident field_name} -> Some field_name
           | _ -> None)
     in
-    match (!field_with_cursor, !field_with_pat_hole) with
-    | Some (fname, f), _ | None, Some (fname, f) -> (
+    match (rest_cursor rest, !field_with_cursor, !field_with_pat_hole) with
+    | Some (`Name txt), _, _ -> Some (txt, pattern_path)
+    | Some `Rest, _, _ -> None
+    | None, Some (fname, f), _ | None, None, Some (fname, f) -> (
       match f.ppat_desc with
       | Ppat_extension ({txt = "rescript.patternhole"}, _) ->
         (* A pattern hole means for example `{someField: <com>}`. We want to complete for the type of `someField`.  *)
@@ -154,7 +167,7 @@ and traverse_pattern (pat : Parsetree.pattern) ~pattern_path ~loc_has_cursor
                @ pattern_path)
              ~loc_has_cursor ~first_char_before_cursor_no_white
              ~pos_before_cursor)
-    | None, None -> (
+    | None, None, None -> (
       (* Figure out if we're completing for a new field.
          If the cursor is inside of the record body, but no field has the cursor,
          and there's no pattern hole. Check the first char to the left of the cursor,

analysis/src/dump_ast.ml

@@ -67,6 +67,14 @@ let print_core_type typ ~pos =
   | Ptyp_variant _ -> "Ptyp_variant(<unimplemented>)"
   | _ -> "<unimplemented_ptyp_desc>"
 
+let print_record_pattern_rest rest ~pos =
+  (rest.Parsetree.rest_name |> print_loc_denominator_loc ~pos)
+  ^ rest.rest_name.txt
+  ^
+  match rest.rest_type with
+  | Some core_type -> " as " ^ print_core_type core_type ~pos
+  | None -> ""
+
 let rec print_pattern pattern ~pos ~indentation =
   print_attributes pattern.Parsetree.ppat_attributes
   ^ (pattern.ppat_loc |> print_loc_denominator ~pos)
@@ -101,7 +109,7 @@ let rec print_pattern pattern ~pos ~indentation =
       | None -> ""
       | Some pat -> "," ^ print_pattern pat ~pos ~indentation)
     ^ ")"
-  | Ppat_record (fields, _) ->
+  | Ppat_record (fields, _, rest) ->
     "Ppat_record(\n"
     ^ add_indentation (indentation + 1)
     ^ "fields:\n"
@@ -112,6 +120,14 @@ let rec print_pattern pattern ~pos ~indentation =
            ^ ": "
            ^ print_pattern pat ~pos ~indentation:(indentation + 2))
       |> String.concat "\n")
+    ^ (match rest with
+      | None -> ""
+      | Some rest ->
+        "\n"
+        ^ add_indentation (indentation + 1)
+        ^ "rest:\n"
+        ^ add_indentation (indentation + 2)
+        ^ print_record_pattern_rest rest ~pos)
     ^ "\n"
     ^ add_indentation indentation
     ^ ")"

analysis/src/hint.ml

@@ -42,8 +42,11 @@ let inlay ~source ~kind_file ~pos ~max_length ~full ~state ~debug =
   let rec process_pattern (pat : Parsetree.pattern) =
     match pat.ppat_desc with
     | Ppat_tuple pl -> pl |> List.iter process_pattern
-    | Ppat_record (fields, _) ->
-      Ext_list.iter fields (fun {x = p} -> process_pattern p)
+    | Ppat_record (fields, _, rest) -> (
+      Ext_list.iter fields (fun {x = p} -> process_pattern p);
+      match rest with
+      | Some {rest_name; _} -> push rest_name.loc Type
+      | None -> ())
     | Ppat_array fields -> fields |> List.iter process_pattern
     | Ppat_var {loc} -> push loc Type
     | _ -> ()

analysis/src/process_cmt.ml

@@ -517,8 +517,27 @@ let rec for_structure_item ~(env : Shared_types.Env.t) ~(exported : Exported.t)
       | Tpat_tuple pats | Tpat_array pats | Tpat_construct (_, _, pats) ->
         pats |> List.iter (fun p -> handle_pattern [] p)
       | Tpat_or (p, _, _) -> handle_pattern [] p
-      | Tpat_record (items, _) ->
-        items |> List.iter (fun (_, _, p, _) -> handle_pattern [] p)
+      | Tpat_record (record_items, _, rest) -> (
+        record_items |> List.iter (fun (_, _, p, _) -> handle_pattern [] p);
+        match rest with
+        | None -> ()
+        | Some rest ->
+          let declared =
+            add_declared ~name:rest.rest_name
+              ~stamp:(Ident.binding_time rest.rest_ident)
+              ~env ~extent:rest.rest_name.loc ~item:rest.rest_type []
+              (Exported.add exported Exported.Value)
+              Stamps.add_value
+          in
+          items :=
+            {
+              Module.kind = Module.Value declared.item;
+              name = declared.name.txt;
+              docstring = declared.docstring;
+              deprecated = declared.deprecated;
+              loc = declared.extent_loc;
+            }
+            :: !items)
       | Tpat_variant (_, Some p, _) -> handle_pattern [] p
       | Tpat_variant (_, None, _) | Tpat_any | Tpat_constant _ -> ()
     in

analysis/src/process_extra.ml

@@ -378,22 +378,32 @@ let pat ~(file : File.t) ~env ~extra (iter : Tast_iterator.iterator)
       | Tpackage (path, _, _) -> Some path
       | _ -> None
   in
-  let add_for_pattern stamp name =
+  let add_for_declared_pattern ~stamp ~name ~extent ~item ~attributes =
     if Stamps.find_value file.stamps stamp = None then (
       let declared =
         Process_attributes.new_declared ~name ~stamp ~module_path:NotVisible
-          ~extent:pattern.pat_loc ~item:pattern.pat_type false
-          pattern.pat_attributes
+          ~extent ~item false attributes
       in
       Stamps.add_value file.stamps stamp declared;
       add_reference ~extra stamp name.loc;
       add_loc_item extra name.loc
-        (Typed (name.txt, pattern.pat_type, Definition (stamp, Value))))
+        (Typed (name.txt, item, Definition (stamp, Value))))
+  in
+  let add_for_pattern stamp name =
+    add_for_declared_pattern ~stamp ~name ~extent:pattern.pat_loc
+      ~item:pattern.pat_type ~attributes:pattern.pat_attributes
   in
   (* Log.log("Entering pattern " ++ Utils.showLocation(pat_loc)); *)
   (match pattern.pat_desc with
-  | Tpat_record (items, _) ->
-    add_for_record ~env ~extra ~record_type:pattern.pat_type items
+  | Tpat_record (items, _, rest) -> (
+    add_for_record ~env ~extra ~record_type:pattern.pat_type items;
+    match rest with
+    | None -> ()
+    | Some rest ->
+      add_for_declared_pattern
+        ~stamp:(Ident.binding_time rest.rest_ident)
+        ~name:rest.rest_name ~extent:rest.rest_name.loc ~item:rest.rest_type
+        ~attributes:pattern.pat_attributes)
   | Tpat_construct (lident, constructor, _) ->
     add_for_constructor ~env ~extra pattern.pat_type lident constructor
   | Tpat_alias (_inner, ident, name) -> (

analysis/src/semantic_tokens.ml

@@ -233,9 +233,13 @@ let command ~debug ~emitter ~source ~kind_file =
     | Ppat_construct ({txt = Lident ("true" | "false")}, _) ->
       (* Don't emit true or false *)
       Ast_iterator.default_iterator.pat iterator p
-    | Ppat_record (cases, _) ->
+    | Ppat_record (cases, _, rest) ->
       Ext_list.iter cases (fun {lid = label} ->
           emitter |> emit_record_label ~label ~debug);
+      (match rest with
+      | Some {rest_name = {txt = id; loc}; _} when is_lowercase_id id ->
+        emitter |> emit_variable ~id ~debug ~loc
+      | _ -> ());
       Ast_iterator.default_iterator.pat iterator p
     | Ppat_construct (name, _) ->
       emitter |> emit_variant ~name ~debug;
@@ -490,7 +494,7 @@ let command ~debug ~emitter ~source ~kind_file =
     in
     let {Res_driver.parsetree = structure; diagnostics} = parser ~source in
     if debug then
-      Printf.printf "structure items:%d diagnostics:%d \n"
+      Printf.printf "structure items:%d diagnostics:%d\n"
         (List.length structure) (List.length diagnostics);
     iterator.structure iterator structure |> ignore)
   else
@@ -499,7 +503,7 @@ let command ~debug ~emitter ~source ~kind_file =
     in
     let {Res_driver.parsetree = signature; diagnostics} = parser ~source in
     if debug then
-      Printf.printf "signature items:%d diagnostics:%d \n"
+      Printf.printf "signature items:%d diagnostics:%d\n"
         (List.length signature) (List.length diagnostics);
     iterator.signature iterator signature |> ignore
 

analysis/src/signature_help.ml

@@ -685,7 +685,8 @@ let signature_help ~debug ~source ~kind_file ~pos
                 match tuple_item_with_cursor with
                 | None -> -1
                 | Some i -> i)
-              | `ConstructorPat (_, {ppat_desc = Ppat_record (fields, _)}) -> (
+              | `ConstructorPat (_, {ppat_desc = Ppat_record (fields, _, _rest)})
+                -> (
                 let field_name_with_cursor =
                   fields
                   |> List.find_map