Argument spec alias handling: actually report deprecated aliases in suboptions, and fix warning message in suboptions when two aliases of the same option are used (#79740) (#79770)

* Normalize deprecation records.

* Fix alias deprecations in suboptions.

* Report in which option an alias warning happened for suboptions.

* Add deprecation tests for suboptions.

* Also test deprecation in list of dicts.

* Adjust unit tests for toplevel alias deprecation field name change.

(cherry picked from commit 8a7185c224eb6e116d1233d37d57bbbb223cb5bb)

4 files changed, 247 insertions, 3 deletions

diff --git a/test/integration/targets/argspec/library/argspec.py b/test/integration/targets/argspec/library/argspec.py
index 2f24bb7492..b6d6d110f2 100644
--- a/test/integration/targets/argspec/library/argspec.py
+++ b/test/integration/targets/argspec/library/argspec.py
@@ -34,7 +34,7 @@ def main():
                 'elements': 'dict',
                 'options': {
                     'thing': {},
-                    'other': {},
+                    'other': {'aliases': ['other_alias']},
                 },
             },
             'required_by': {
@@ -136,6 +136,7 @@ def main():
                     'bar': {
                         'type': 'str',
                         'default': 'baz',
+                        'aliases': ['bar_alias1', 'bar_alias2'],
                     },
                 },
             },
@@ -168,6 +169,78 @@ def main():
                 'removed_at_date': '2023-01-01',
                 'removed_from_collection': 'foo.bar',
             },
+            'subdeprecation': {
+                'aliases': [
+                    'subdeprecation_alias',
+                ],
+                'type': 'dict',
+                'options': {
+                    'deprecation_aliases': {
+                        'type': 'str',
+                        'aliases': [
+                            'deprecation_aliases_version',
+                            'deprecation_aliases_date',
+                        ],
+                        'deprecated_aliases': [
+                            {
+                                'name': 'deprecation_aliases_version',
+                                'version': '2.0.0',
+                                'collection_name': 'foo.bar',
+                            },
+                            {
+                                'name': 'deprecation_aliases_date',
+                                'date': '2023-01-01',
+                                'collection_name': 'foo.bar',
+                            },
+                        ],
+                    },
+                    'deprecation_param_version': {
+                        'type': 'str',
+                        'removed_in_version': '2.0.0',
+                        'removed_from_collection': 'foo.bar',
+                    },
+                    'deprecation_param_date': {
+                        'type': 'str',
+                        'removed_at_date': '2023-01-01',
+                        'removed_from_collection': 'foo.bar',
+                    },
+                },
+            },
+            'subdeprecation_list': {
+                'type': 'list',
+                'elements': 'dict',
+                'options': {
+                    'deprecation_aliases': {
+                        'type': 'str',
+                        'aliases': [
+                            'deprecation_aliases_version',
+                            'deprecation_aliases_date',
+                        ],
+                        'deprecated_aliases': [
+                            {
+                                'name': 'deprecation_aliases_version',
+                                'version': '2.0.0',
+                                'collection_name': 'foo.bar',
+                            },
+                            {
+                                'name': 'deprecation_aliases_date',
+                                'date': '2023-01-01',
+                                'collection_name': 'foo.bar',
+                            },
+                        ],
+                    },
+                    'deprecation_param_version': {
+                        'type': 'str',
+                        'removed_in_version': '2.0.0',
+                        'removed_from_collection': 'foo.bar',
+                    },
+                    'deprecation_param_date': {
+                        'type': 'str',
+                        'removed_at_date': '2023-01-01',
+                        'removed_from_collection': 'foo.bar',
+                    },
+                },
+            }
         },
         required_if=(
             ('state', 'present', ('path', 'content'), True),
diff --git a/test/integration/targets/argspec/tasks/main.yml b/test/integration/targets/argspec/tasks/main.yml
index a00d33d7ab..6e8ec054fe 100644
--- a/test/integration/targets/argspec/tasks/main.yml
+++ b/test/integration/targets/argspec/tasks/main.yml
@@ -390,6 +390,106 @@
     deprecation_param_date: value
   register: deprecation_param_date
 
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation:
+      deprecation_aliases_version: value
+  register: sub_deprecation_alias_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation:
+      deprecation_aliases_date: value
+  register: sub_deprecation_alias_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation:
+      deprecation_param_version: value
+  register: sub_deprecation_param_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation:
+      deprecation_param_date: value
+  register: sub_deprecation_param_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_alias:
+      deprecation_aliases_version: value
+  register: subalias_deprecation_alias_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_alias:
+      deprecation_aliases_date: value
+  register: subalias_deprecation_alias_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_alias:
+      deprecation_param_version: value
+  register: subalias_deprecation_param_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_alias:
+      deprecation_param_date: value
+  register: subalias_deprecation_param_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_list:
+      - deprecation_aliases_version: value
+  register: sublist_deprecation_alias_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_list:
+      - deprecation_aliases_date: value
+  register: sublist_deprecation_alias_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_list:
+      - deprecation_param_version: value
+  register: sublist_deprecation_param_version
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    subdeprecation_list:
+      - deprecation_param_date: value
+  register: sublist_deprecation_param_date
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    apply_defaults:
+      bar_alias1: foo
+      bar_alias2: baz
+  register: alias_warning_dict
+
+- argspec:
+    required: value
+    required_one_of_one: value
+    required_one_of:
+      - other: foo
+        other_alias: bar
+  register: alias_warning_listdict
+
 - assert:
     that:
       - argspec_required_fail is failed
@@ -491,3 +591,69 @@
       - deprecation_param_date.deprecations[0].collection_name == 'foo.bar'
       - deprecation_param_date.deprecations[0].date == '2023-01-01'
       - "'version' not in deprecation_param_date.deprecations[0]"
+
+      - sub_deprecation_alias_version.deprecations | length == 1
+      - sub_deprecation_alias_version.deprecations[0].msg == "Alias 'subdeprecation.deprecation_aliases_version' is deprecated. See the module docs for more information"
+      - sub_deprecation_alias_version.deprecations[0].collection_name == 'foo.bar'
+      - sub_deprecation_alias_version.deprecations[0].version == '2.0.0'
+      - "'date' not in sub_deprecation_alias_version.deprecations[0]"
+      - sub_deprecation_alias_date.deprecations | length == 1
+      - sub_deprecation_alias_date.deprecations[0].msg == "Alias 'subdeprecation.deprecation_aliases_date' is deprecated. See the module docs for more information"
+      - sub_deprecation_alias_date.deprecations[0].collection_name == 'foo.bar'
+      - sub_deprecation_alias_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in sub_deprecation_alias_date.deprecations[0]"
+      - sub_deprecation_param_version.deprecations | length == 1
+      - sub_deprecation_param_version.deprecations[0].msg == "Param 'subdeprecation[\"deprecation_param_version\"]' is deprecated. See the module docs for more information"
+      - sub_deprecation_param_version.deprecations[0].collection_name == 'foo.bar'
+      - sub_deprecation_param_version.deprecations[0].version == '2.0.0'
+      - "'date' not in sub_deprecation_param_version.deprecations[0]"
+      - sub_deprecation_param_date.deprecations | length == 1
+      - sub_deprecation_param_date.deprecations[0].msg == "Param 'subdeprecation[\"deprecation_param_date\"]' is deprecated. See the module docs for more information"
+      - sub_deprecation_param_date.deprecations[0].collection_name == 'foo.bar'
+      - sub_deprecation_param_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in sub_deprecation_param_date.deprecations[0]"
+
+      - subalias_deprecation_alias_version.deprecations | length == 1
+      - subalias_deprecation_alias_version.deprecations[0].msg == "Alias 'subdeprecation.deprecation_aliases_version' is deprecated. See the module docs for more information"
+      - subalias_deprecation_alias_version.deprecations[0].collection_name == 'foo.bar'
+      - subalias_deprecation_alias_version.deprecations[0].version == '2.0.0'
+      - "'date' not in subalias_deprecation_alias_version.deprecations[0]"
+      - subalias_deprecation_alias_date.deprecations | length == 1
+      - subalias_deprecation_alias_date.deprecations[0].msg == "Alias 'subdeprecation.deprecation_aliases_date' is deprecated. See the module docs for more information"
+      - subalias_deprecation_alias_date.deprecations[0].collection_name == 'foo.bar'
+      - subalias_deprecation_alias_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in subalias_deprecation_alias_date.deprecations[0]"
+      - subalias_deprecation_param_version.deprecations | length == 1
+      - subalias_deprecation_param_version.deprecations[0].msg == "Param 'subdeprecation[\"deprecation_param_version\"]' is deprecated. See the module docs for more information"
+      - subalias_deprecation_param_version.deprecations[0].collection_name == 'foo.bar'
+      - subalias_deprecation_param_version.deprecations[0].version == '2.0.0'
+      - "'date' not in subalias_deprecation_param_version.deprecations[0]"
+      - subalias_deprecation_param_date.deprecations | length == 1
+      - subalias_deprecation_param_date.deprecations[0].msg == "Param 'subdeprecation[\"deprecation_param_date\"]' is deprecated. See the module docs for more information"
+      - subalias_deprecation_param_date.deprecations[0].collection_name == 'foo.bar'
+      - subalias_deprecation_param_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in subalias_deprecation_param_date.deprecations[0]"
+
+      - sublist_deprecation_alias_version.deprecations | length == 1
+      - sublist_deprecation_alias_version.deprecations[0].msg == "Alias 'subdeprecation_list[0].deprecation_aliases_version' is deprecated. See the module docs for more information"
+      - sublist_deprecation_alias_version.deprecations[0].collection_name == 'foo.bar'
+      - sublist_deprecation_alias_version.deprecations[0].version == '2.0.0'
+      - "'date' not in sublist_deprecation_alias_version.deprecations[0]"
+      - sublist_deprecation_alias_date.deprecations | length == 1
+      - sublist_deprecation_alias_date.deprecations[0].msg == "Alias 'subdeprecation_list[0].deprecation_aliases_date' is deprecated. See the module docs for more information"
+      - sublist_deprecation_alias_date.deprecations[0].collection_name == 'foo.bar'
+      - sublist_deprecation_alias_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in sublist_deprecation_alias_date.deprecations[0]"
+      - sublist_deprecation_param_version.deprecations | length == 1
+      - sublist_deprecation_param_version.deprecations[0].msg == "Param 'subdeprecation_list[\"deprecation_param_version\"]' is deprecated. See the module docs for more information"
+      - sublist_deprecation_param_version.deprecations[0].collection_name == 'foo.bar'
+      - sublist_deprecation_param_version.deprecations[0].version == '2.0.0'
+      - "'date' not in sublist_deprecation_param_version.deprecations[0]"
+      - sublist_deprecation_param_date.deprecations | length == 1
+      - sublist_deprecation_param_date.deprecations[0].msg == "Param 'subdeprecation_list[\"deprecation_param_date\"]' is deprecated. See the module docs for more information"
+      - sublist_deprecation_param_date.deprecations[0].collection_name == 'foo.bar'
+      - sublist_deprecation_param_date.deprecations[0].date == '2023-01-01'
+      - "'version' not in sublist_deprecation_param_date.deprecations[0]"
+
+      - "'Both option apply_defaults.bar and its alias apply_defaults.bar_alias2 are set.' in alias_warning_dict.warnings"
+      - "'Both option required_one_of[0].other and its alias required_one_of[0].other_alias are set.' in alias_warning_listdict.warnings"
diff --git a/test/units/module_utils/common/arg_spec/test_aliases.py b/test/units/module_utils/common/arg_spec/test_aliases.py
index 1c1e243a7b..7d30fb0f0c 100644
--- a/test/units/module_utils/common/arg_spec/test_aliases.py
+++ b/test/units/module_utils/common/arg_spec/test_aliases.py
@@ -57,7 +57,12 @@ ALIAS_TEST_CASES = [
             'path': '/tmp',
             'not_yo_path': '/tmp',
         },
-        {'version': '1.7', 'date': None, 'collection_name': None, 'name': 'not_yo_path'},
+        {
+            'version': '1.7',
+            'date': None,
+            'collection_name': None,
+            'msg': "Alias 'not_yo_path' is deprecated. See the module docs for more information",
+        },
         "",
     )
 ]
diff --git a/test/units/module_utils/common/arg_spec/test_module_validate.py b/test/units/module_utils/common/arg_spec/test_module_validate.py
index 5041d521bd..2c2211c9d4 100644
--- a/test/units/module_utils/common/arg_spec/test_module_validate.py
+++ b/test/units/module_utils/common/arg_spec/test_module_validate.py
@@ -49,7 +49,7 @@ def test_module_alias_deprecations_warnings(monkeypatch):
         {
             'collection_name': None,
             'date': '2020-03-04',
-            'name': 'flamethrower',
+            'msg': "Alias 'flamethrower' is deprecated. See the module docs for more information",
             'version': None,
         }
     ]