Implement -Wambiguous-fields

Fixes #18966. Adds a new warning -Wambiguous-fields for uses of field selectors
or record updates that will be rejected in the future, when the DuplicateRecordFields
extension is simplified per https://github.com/ghc-proposals/ghc-proposals/pull/366.

2 files changed, 39 insertions, 5 deletions

diff --git a/docs/users_guide/exts/duplicate_record_fields.rst b/docs/users_guide/exts/duplicate_record_fields.rst
index d8abedaefa..8f0ace158b 100644
--- a/docs/users_guide/exts/duplicate_record_fields.rst
+++ b/docs/users_guide/exts/duplicate_record_fields.rst
@@ -45,6 +45,13 @@ is still not allowed if both ``S(x)`` and ``T(x)`` are in scope: ::
 
     bad r = x r
 
+**Warning**: the type-based disambiguation rules described in the remainder of
+this section are being removed (see the proposal `DuplicateRecordFields without
+ambiguous field access
+<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst>`_).
+The :ghc-flag:`-Wambiguous-fields` option will warn about code that relies on
+these rules. In a future GHC release, such code will produce ambiguity errors.
+
 An ambiguous selector may be disambiguated by the type being "pushed down" to
 the occurrence of the selector (see :ref:`higher-rank-type-inference` for more
 details on what "pushed down" means). For example, the following are permitted: ::
@@ -86,14 +93,21 @@ definitions: ::
 
 Without :extension:`DuplicateRecordFields`, an update mentioning ``foo`` will always be
 ambiguous if all these definitions were in scope. When the extension is enabled,
-there are several options for disambiguating updates:
-
-- Check for types that have all the fields being updated. For example: ::
+and there is exactly one type that has all the fields being updated, that type will be used.
+For example: ::
 
       f x = x { foo = 3, bar = 2 }
 
-  Here ``f`` must be updating ``T`` because neither ``S`` nor ``U`` have both
-  fields.
+Here ``f`` must be updating ``T`` because neither ``S`` nor ``U`` have both
+fields.
+
+If there are multiple types with all the fields, type information may be used to
+disambiguate which record type is meant. **Warning**: the following rules are
+being removed (see the proposal `DuplicateRecordFields without ambiguous field
+access
+<https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst>`_).
+The :ghc-flag:`-Wambiguous-fields` option will warn about code that relies on
+these rules. In a future GHC release, such code will produce ambiguity errors.
 
 - Use the type being pushed in to the record update, as in the following: ::
 
diff --git a/docs/users_guide/using-warnings.rst b/docs/users_guide/using-warnings.rst
index 5c2c9b66e1..a9995268ea 100644
--- a/docs/users_guide/using-warnings.rst
+++ b/docs/users_guide/using-warnings.rst
@@ -52,6 +52,7 @@ To reverse ``-Werror``, which makes all warnings into errors, use ``-Wwarn``.
         * :ghc-flag:`-Winaccessible-code`
         * :ghc-flag:`-Wstar-binder`
         * :ghc-flag:`-Woperator-whitespace-ext-conflict`
+        * :ghc-flag:`-Wambiguous-fields`
 
 The following flags are simple ways to select standard "packages" of warnings:
 
@@ -1947,6 +1948,25 @@ of ``-W(no-)*``.
     Since GHC 7.10, ``Typeable`` is automatically derived for all types.
     Thus, deriving ``Typeable`` yourself is redundant.
 
+.. ghc-flag:: -Wambiguous-fields
+    :shortdesc: warn about ambiguous field selectors or updates
+    :type: dynamic
+    :category:
+
+    :since: 9.2
+
+    When :extension:`DuplicateRecordFields` is enabled, the option
+    :ghc-flag:`-Wambiguous-fields` warns about occurrences of fields in
+    selectors or updates that depend on the deprecated mechanism for
+    type-directed disambiguation.  This mechanism will be removed in a future
+    GHC release, at which point these occurrences will be rejected as ambiguous.
+    See the proposal `DuplicateRecordFields without ambiguous field access
+    <https://github.com/ghc-proposals/ghc-proposals/blob/master/proposals/0366-no-ambiguous-field-access.rst>`_
+    and the documentation on :extension:`DuplicateRecordFields` for further details.
+
+    This warning has no effect when :extension:`DuplicateRecordFields` is
+    disabled.
+
 If you're feeling really paranoid, the :ghc-flag:`-dcore-lint` option is a good choice.
 It turns on heavyweight intra-pass sanity-checking within GHC. (It checks GHC's
 sanity, not yours.)