validate-modules: detect names set mismatch between argument spec and documentation (#83599)

changelogs/fragments/83599-validate-modules-aliases.yml

@@ -0,0 +1,3 @@
+minor_changes:
+  - "validate-modules sanity test - detect if names of an option (option name + aliases) do not match between argument spec and documentation
+     (https://github.com/ansible/ansible/issues/83598, https://github.com/ansible/ansible/pull/83599)."

test/integration/targets/ansible-test-sanity-validate-modules/ansible_collections/ns/col/plugins/modules/wrong_aliases.py

@@ -0,0 +1,46 @@
+#!/usr/bin/python
+# GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
+
+from __future__ import annotations
+
+DOCUMENTATION = '''
+module: wrong_aliases
+short_description: Aliases that are attached to the wrong option in documentation
+description: Aliases that are attached to the wrong option in documentation.
+author:
+  - Ansible Core Team
+options:
+  foo:
+    description: Foo.
+    type: str
+    aliases:
+      - bam
+  bar:
+    description: Bar.
+    type: str
+'''
+
+EXAMPLES = '''#'''
+RETURN = ''''''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(
+        argument_spec=dict(
+            foo=dict(
+                type='str',
+            ),
+            bar=dict(
+                type='str',
+                aliases=[
+                    'bam'
+                ],
+            ),
+        ),
+    )
+
+
+if __name__ == '__main__':
+    main()

test/integration/targets/ansible-test-sanity-validate-modules/expected.txt

@@ -31,3 +31,5 @@ plugins/modules/semantic_markup.py:0:0: invalid-documentation-markup: Directive
 plugins/modules/semantic_markup.py:0:0: invalid-documentation-markup: Directive "RV(does.not.exist=true)" contains a non-existing return value "does.not.exist"
 plugins/modules/unsupported_extension.nope:0:0: invalid-extension: Official Ansible modules must have a .py extension for python modules or a .ps1 for powershell modules
 plugins/modules/unsupported_extension.nope:0:0: missing-gplv3-license: GPLv3 license header not found in the first 20 lines of the module
+plugins/modules/wrong_aliases.py:0:0: parameter-documented-aliases-differ: Argument 'bar' in argument_spec has names 'bam', 'bar', but its documentation has names 'bar'
+plugins/modules/wrong_aliases.py:0:0: parameter-documented-aliases-differ: Argument 'foo' in argument_spec has names 'foo', but its documentation has names 'bam', 'foo'

test/lib/ansible_test/_util/controller/sanity/validate-modules/validate_modules/main.py

@@ -1919,8 +1919,10 @@ class ModuleValidator(Validator):
             if len(doc_options_args) == 0:
                 # Undocumented arguments will be handled later (search for undocumented-parameter)
                 doc_options_arg = {}
+                doc_option_name = None
             else:
-                doc_options_arg = doc_options[doc_options_args[0]]
+                doc_option_name = doc_options_args[0]
+                doc_options_arg = doc_options[doc_option_name]
                 if len(doc_options_args) > 1:
                     msg = "Argument '%s' in argument_spec" % arg
                     if context:
@@ -1935,6 +1937,26 @@ class ModuleValidator(Validator):
                         msg=msg
                     )
 
+            all_aliases = set(aliases + [arg])
+            all_docs_aliases = set(
+                ([doc_option_name] if doc_option_name is not None else [])
+                +
+                (doc_options_arg['aliases'] if isinstance(doc_options_arg.get('aliases'), list) else [])
+            )
+            if all_docs_aliases and all_aliases != all_docs_aliases:
+                msg = "Argument '%s' in argument_spec" % arg
+                if context:
+                    msg += " found in %s" % " -> ".join(context)
+                msg += " has names %s, but its documentation has names %s" % (
+                    ", ".join([("'%s'" % alias) for alias in sorted(all_aliases)]),
+                    ", ".join([("'%s'" % alias) for alias in sorted(all_docs_aliases)])
+                )
+                self.reporter.error(
+                    path=self.object_path,
+                    code='parameter-documented-aliases-differ',
+                    msg=msg
+                )
+
             try:
                 doc_default = None
                 if 'default' in doc_options_arg and doc_options_arg['default'] is not None: