Sanity checks: make sure that `required` in argument spec coincides with documentation (#65437)

* Add sanity test for required parameters, update ignore.txt, and add changelog.

changelogs/fragments/65437-ansible-test-module-validation-required.yml

@@ -0,0 +1,2 @@
+minor_changes:
+- "ansible-test - the module validation code now checks whether ``requirement`` for options is documented correctly."

docs/docsite/rst/dev_guide/testing_validate-modules.rst

@@ -68,6 +68,7 @@ Codes
   doc-default-does-not-match-spec                              Documentation        Error                  Value for "default" from the argument_spec does not match the documentation
   doc-default-incompatible-type                                Documentation        Error                  Default value from the documentation is not compatible with type defined in the argument_spec
   doc-missing-type                                             Documentation        Error                  Documentation doesn't specify a type but argument in ``argument_spec`` use default type (``str``)
+  doc-required-mismatch                                        Documentation        Error                  argument in argument_spec is required but documentation says it is not, or vice versa
   doc-type-does-not-match-spec                                 Documentation        Error                  Argument_spec defines type different than documentation does
   documentation-error                                          Documentation        Error                  Unknown ``DOCUMENTATION`` error
   documentation-syntax-error                                   Documentation        Error                  Invalid ``DOCUMENTATION`` schema

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

@@ -1435,6 +1435,22 @@ class ModuleValidator(Validator):
                     msg=msg
                 )
 
+            doc_required = doc_options_arg.get('required', False)
+            data_required = data.get('required', False)
+            if (doc_required or data_required) and not (doc_required and data_required):
+                msg = "Argument '%s' in argument_spec" % arg
+                if context:
+                    msg += " found in %s" % " -> ".join(context)
+                if doc_required:
+                    msg += " is not required, but is documented as being required"
+                else:
+                    msg += " is required, but is not documented as being required"
+                self.reporter.error(
+                    path=self.object_path,
+                    code='doc-required-mismatch',
+                    msg=msg
+                )
+
             spec_suboptions = data.get('options')
             doc_suboptions = doc_options_arg.get('suboptions', {})
             if spec_suboptions: