[Role][2167] A role that automatically scans the playbooks in the directory and advises of migration actions

changelogs/fragments/2167_playbook_upgrade_validator_role.yml

@@ -0,0 +1,3 @@
+minor_changes:
+   - playbook_upgrade_validator - Adding a role that automatically scans the playbooks in the directory and advises of migration actions from v1.x.x to v2.0.0.
+     (https://github.com/ansible-collections/ibm_zos_core/pull/2399)

roles/playbook_upgrade_validator/README.md

@@ -0,0 +1,11 @@
+# ibm.ibm_zos_core.playbook_upgrade_validator
+
+This role validates playbooks against ibm_zos_core 2.0.0 and provides migration actions.
+
+## Role Variables
+
+The following variables are required:
+
+- `playbook_path`: Path to the directory containing the Ansible playbooks to be validated.
+- `output_path`: Path to the output JSON file where results should be saved.
+- `ignore_response_params`: Indicates whether information about response parameter changes should be included.

roles/playbook_upgrade_validator/docs/doc_playbook_upgrade_validator

@@ -0,0 +1,94 @@
+# Copyright (c) IBM Corporation 2025
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#     http://www.apache.org/licenses/LICENSE-2.0
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+DOCUMENTATION = r'''
+---
+module: playbook_upgrade_validator
+version_added: "2.0.0"
+author:
+  - "Ravella Surendra Babu (@surendrababuravella)"
+short_description: Validates playbooks against ibm_zos_core 2.0.0 and provides migration actions.
+description:
+  - Scans one or more Ansible playbooks to identify deprecated or renamed parameters
+    based on migration rules for IBM z/OS Core collection version 2.0.0.
+  - Provides line numbers, affected modules, and suggested corrective actions.
+options:
+  ignore_response_params:
+    description:
+      - Indicates whether information about response parameter changes should be included.
+    default: false
+    type: bool
+  migration_map:
+    description:
+      - A structured set of migration rules that specifies deprecated, renamed, and modified parameters
+        to help upgrade playbooks from ibm_zos_core 1.x.x to 2.0.0.
+    required: true
+    type: dict
+  output_path:
+    description:
+      - Path to the output JSON file where results should be saved.
+      - Default path is <<playbook_dir>>/logs/migration_report.json
+    required: false
+    type: str
+  playbook_path:
+    description:
+      - Path to the directory containing the Ansible playbooks to be validated.
+    required: true
+    type: str
+notes:
+  - Designed to assist migration of playbooks from older IBM z/OS core collection versions to 2.0.0.
+  - Supports reading tasks, blocks, and nested includes.
+'''
+
+EXAMPLES = r'''
+- name: execute playbook_upgrade_validator role to list migration changes
+  include_role:
+    name: ibm.ibm_zos_core.playbook_upgrade_validator
+  vars:
+    playbook_path: "/path/to/playbooks/*.yml"
+    output_path: "/path/to/reports/validation_report.json"
+    ignore_response_params: false
+'''
+
+RETURN = r'''
+changed:
+  description:
+    - Always false as there are no state changes happening in this process.
+  returned: always
+  type: bool
+output_path:
+  description: Path to the output JSON file containing validation results.
+  returned: always
+  type: str
+playbook_path:
+  description: The path to the directory containing the Ansible playbooks to be validated.
+  returned: always
+  type: str
+results:
+  description: List of issues identified in all scanned playbooks, along with detailed information.
+  returned: always
+  type: list
+  sample:
+    [
+        {
+            "line": 9,
+            "migration_actions": [
+                "[MUST_FIX] Param 'force_lock' is renamed to 'force' in zos_copy",
+                "[MUST_FIX] Param 'is_binary' is renamed to 'binary' in zos_copy",
+                "[MUST_FIX] Param 'force' is renamed to 'replace' in zos_copy"
+            ],
+            "module": "zos_copy",
+            "play_name": "Execute z/OS modules",
+            "playbook": "/path/to/playbook/copy_file.yml",
+            "task_name": "copy file to z/os"
+        }
+    ]
+'''

roles/playbook_upgrade_validator/files/dependency_config.json

@@ -0,0 +1,139 @@
+{
+    "zos_apf": {
+        "renamed_params": {
+            "data_set_name": "target"
+        },
+        "deprecated_params": [],
+        "renamed_response_params": {}
+    },
+    "zos_archive": {
+        "renamed_params": {
+            "format.type": "format.name",
+            "format.format_options": "format.options",
+            "format.format_options.terse_pack": "format.options.spack",
+            "format.format_options.use_adrdssu": "format.options.adrdssu"
+        },
+        "type_changed_params": {
+            "format.format_options.terse_pack": "string_boolean"
+        },
+        "deprecated_params": [],
+        "functionality_impact": []
+    },
+    "zos_copy": {
+        "renamed_params": {
+            "force": "replace",
+            "force_lock": "force",
+            "is_binary": "binary"
+        }
+    },
+    "zos_data_set": {
+        "renamed_response_params": {
+            "names": "data_sets"
+        }
+    },
+    "zos_job_query": {
+        "renamed_response_params": {
+            "ret_code.steps": "jobs.steps"
+        },
+        "deprecated_response_params": [
+            "message"
+        ]
+    },
+    "zos_fetch": {
+        "deprecated_params": [
+            "note"
+        ],
+        "renamed_response_params": {
+            "file": "src"
+        }
+    },
+    "zos_find": {
+        "renamed_params": {
+            "pds_pattern": "patterns"
+        }
+    },
+    "zos_lineinfile": {
+        "renamed_params": {
+            "insertafter": "after",
+            "insertbefore": "before"
+        },
+        "renamed_response_params": {
+            "return_content": "stdout"
+        }
+    },
+    "zos_unarchive": {
+        "renamed_params": {
+            "format.type": "format.name",
+            "format.format_options": "format.options",
+            "format.format_options.use_adrdssu": "format.options.adrdssu"
+        }
+    },
+    "zos_job_output": {
+        "renamed_params": {
+            "ddname": "dd_name"
+        },
+        "renamed_response_params": {
+            "ddnames": "dds",
+            "ddnames.ddname": "dds.dd_name",
+            "ret_code.steps": "jobs.steps"
+        }
+    },
+    "zos_operator_action_query": {
+        "renamed_params": {
+            "message_filter": "msg_filter",
+            "message_id": "msg_id"
+        },
+        "renamed_response_params": {
+            "actions.message_text": "actions.msg_text",
+            "actions.message_id": "actions.msg_id"
+        }
+    },
+    "zos_mount": {
+        "renamed_params": {
+            "persistent.data_store": "persistent.name",
+            "persistent.comment": "persistent.marker",
+            "persistent.addDataset": "persistent.state",
+            "persistent.delDataset": "persistent.name"
+        }
+    },
+    "zos_tso_command": {
+        "renamed_response_params": {
+            "content": "stdout_lines",
+            "lines": "line_count"
+        }
+    },
+    "zos_copy": {
+        "renamed_params": {
+            "force_lock": "force",
+            "is_binary": "binary",
+            "force": "replace"
+        }
+    },
+    "zos_job_submit": {
+        "renamed_params": {
+            "location": "remote_src",
+            "wait_time_s": "wait_time"
+        },
+        "deprecated_params": [
+            "location"
+        ],
+        "renamed_response_params": {
+            "ddnames": "dds",
+            "ddnames.ddname": "dds.dd_name",
+            "ret_code.steps": "jobs.steps"
+        },
+        "deprecated_response_params": [
+            "system",
+            "subsystem",
+            "cpu_time",
+            "execution_node",
+            "origin_node"
+        ]
+    },
+    "zos_blockinfile": {
+        "renamed_params": {
+            "insertafter": "after",
+            "insertbefore": "before"
+        }
+    }
+}