Allow for arbitrary key 'context' in argument spec (#82183)

* Allow for arbitrary key 'context' in argument spec

changelogs/fragments/argument-spec-context.yml

@@ -0,0 +1,4 @@
+minor_changes:
+- module argument spec - Allow module authors to include arbitrary additional context in the argument spec, by making use of a new top level key
+  called ``context``. This key should be a dict type. This allows for users to customize what they place in the argument spec, without having to
+  ignore sanity tests that validate the schema.

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

@@ -0,0 +1,36 @@
+#!/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: invalid_argument_spec_extra_key
+short_description: Invalid argument spec extra key schema test module
+description: Invalid argument spec extra key schema test module
+author:
+  - Ansible Core Team
+options:
+  foo:
+    description: foo
+    type: str
+'''
+
+EXAMPLES = '''#'''
+RETURN = ''''''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(
+        argument_spec=dict(
+            foo=dict(
+                type='str',
+                extra_key='bar',
+            ),
+        ),
+    )
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,36 @@
+#!/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: invalid_argument_spec_incorrect_context
+short_description: Invalid argument spec incorrect context schema test module
+description: Invalid argument spec incorrect context schema test module
+author:
+  - Ansible Core Team
+options:
+  foo:
+    description: foo
+    type: str
+'''
+
+EXAMPLES = '''#'''
+RETURN = ''''''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(
+        argument_spec=dict(
+            foo=dict(
+                type='str',
+                context='bar',
+            ),
+        ),
+    )
+
+
+if __name__ == '__main__':
+    main()

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

@@ -0,0 +1,38 @@
+#!/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: valid_argument_spec_context
+short_description: Valid argument spec context schema test module
+description: Valid argument spec context schema test module
+author:
+  - Ansible Core Team
+options:
+  foo:
+    description: foo
+    type: str
+'''
+
+EXAMPLES = '''#'''
+RETURN = ''''''
+
+from ansible.module_utils.basic import AnsibleModule
+
+
+def main():
+    AnsibleModule(
+        argument_spec=dict(
+            foo=dict(
+                type='str',
+                context=dict(
+                    extra_key='bar',
+                ),
+            ),
+        ),
+    )
+
+
+if __name__ == '__main__':
+    main()

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

@@ -4,6 +4,8 @@ plugins/modules/check_mode_attribute_2.py:0:0: attributes-check-mode: The module
 plugins/modules/check_mode_attribute_3.py:0:0: attributes-check-mode: The module does declare support for check mode, but the check_mode attribute's support value is 'none'
 plugins/modules/check_mode_attribute_4.py:0:0: attributes-check-mode-details: The module declares it does not fully support check mode, but has no details on what exactly that means
 plugins/modules/import_order.py:7:0: import-before-documentation: Import found before documentation variables. All imports must appear below DOCUMENTATION/EXAMPLES/RETURN.
+plugins/modules/invalid_argument_spec_extra_key.py:0:0: invalid-ansiblemodule-schema: AnsibleModule.argument_spec.foo.extra_key: extra keys not allowed @ data['argument_spec']['foo']['extra_key']. Got 'bar'
+plugins/modules/invalid_argument_spec_incorrect_context.py:0:0: invalid-ansiblemodule-schema: AnsibleModule.argument_spec.foo.context: expected dict for dictionary value @ data['argument_spec']['foo']['context']. Got 'bar'
 plugins/modules/invalid_choice_value.py:0:0: doc-choices-do-not-match-spec: Argument 'caching' in argument_spec defines choices as (['ReadOnly', 'ReadOnly']) but documentation defines choices as (['ReadOnly', 'ReadWrite'])
 plugins/modules/invalid_yaml_syntax.py:0:0: deprecation-mismatch: "meta/runtime.yml" and DOCUMENTATION.deprecation do not agree.
 plugins/modules/invalid_yaml_syntax.py:0:0: missing-documentation: No DOCUMENTATION provided

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

@@ -297,6 +297,7 @@ def argument_spec_schema(for_collection):
                 [is_callable, list_string_types],
             ),
             'choices': Any([object], (object,)),
+            'context': dict,
             'required': bool,
             'no_log': bool,
             'aliases': Any(list_string_types, tuple(list_string_types)),