Role addition using add subcommand (#391)

* adding files

* test case addition

* chore: auto fixes from pre-commit.com hooks

* fixing test case

* fix in test case

* changing file

* chore: auto fixes from pre-commit.com hooks

* fix path in test case

* fix file

* chore: auto fixes from pre-commit.com hooks

* removed file form fixture

* adding file

* chore: auto fixes from pre-commit.com hooks

* fix

* chore: auto fixes from pre-commit.com hooks

* fix

* chore: auto fixes from pre-commit.com hooks

* fixes

* commenting out test case for coming soon

* chore: auto fixes from pre-commit.com hooks

* remove coming soon test case

* removing coming soon

* adding back

* adding back coming soon test to keep coverage intact

* chore: auto fixes from pre-commit.com hooks

* fixing test case for coming soon

* chore: auto fixes from pre-commit.com hooks

* fix

* fixing name

* chore: auto fixes from pre-commit.com hooks

* adding name for role

* chore: auto fixes from pre-commit.com hooks

* fix docstring

* test fixes

* fixing path

* added fixes for lint

* fix lint

* removing coming soon var

* chore: auto fixes from pre-commit.com hooks

* remove var coming soon

* fixed version

* removing unused code for lint fix

* fixing folder structure

* fixture fix

* fix

* chore: auto fixes from pre-commit.com hooks

* fixed test case to remove re

* adding files to fixture

* fixes

* chore: auto fixes from pre-commit.com hooks

* add test cases

* fixing help

* comment fix

* fixing fixtures

* added changes for checking path

* changes as per new review

* fixes for review

* adding task example

* readme updates

* added argument_specs file

* remove fix

* test

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: tanwigeetika1618 <[email protected]>

Author: 3 people

.config/dictionary.txt

@@ -43,3 +43,4 @@ testns
 testorg
 testpaths
 webservers
+role

.config/pydoclint-baseline.txt

@@ -50,7 +50,6 @@ tests/units/test_basic.py
     DOC502: Function `test_not_a_tty` has a "Raises" section in the docstring, but there are not "raise" statements in the body
     DOC502: Function `test_main` has a "Raises" section in the docstring, but there are not "raise" statements in the body
     DOC502: Function `test_proj_main` has a "Raises" section in the docstring, but there are not "raise" statements in the body
-    DOC502: Function `test_coming_soon` has a "Raises" section in the docstring, but there are not "raise" statements in the body
     DOC502: Function `test_config_post_init` has a "Raises" section in the docstring, but there are not "raise" statements in the body
 --------------------
 tests/units/test_compat.py

src/ansible_creator/arg_parser.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import argparse
-import contextlib
 import re
 import sys
 
@@ -34,8 +33,6 @@
 
 MIN_COLLECTION_NAME_LEN = 2
 
-COMING_SOON = ("add resource role",)
-
 
 class Parser:
     """A parser for the command line arguments."""
@@ -81,21 +78,6 @@ def parse_args(self) -> tuple[argparse.Namespace, list[Msg]]:
             argcomplete.autocomplete(parser)
         self.args = parser.parse_args()
 
-        combinations = (
-            ("subcommand", "type", "resource_type"),
-            ("subcommand", "type", "plugin_type"),
-            ("subcommand", "project"),
-        )
-        for combination in combinations:
-            with contextlib.suppress(AttributeError):
-                name = " ".join(getattr(self.args, part) for part in combination)
-
-        if name in COMING_SOON:
-            msg = f"The `{name}` command is coming soon. Please try in the next release."
-            self.pending_logs.append(Msg(prefix=Level.HINT, message=msg))
-            self.pending_logs.append(Msg(prefix=Level.CRITICAL, message="Goodbye."))
-            return self.args, self.pending_logs
-
         return self.args, self.pending_logs
 
     def _add(self, subparser: SubParser[ArgumentParser]) -> None:
@@ -308,6 +290,8 @@ def _add_resource_role(self, subparser: SubParser[ArgumentParser]) -> None:
             help="The path to the Ansible collection. The default is the "
             "current working directory.",
         )
+
+        self._add_overwrite(parser)
         self._add_args_common(parser)
 
     def _add_resource_execution_env(self, subparser: SubParser[ArgumentParser]) -> None:

src/ansible_creator/config.py

@@ -36,6 +36,7 @@ class Config:
         type: The type of the project for which the resource is being scaffolded.
         path: The file path where the resource should be added.
         image: The image to be used while scaffolding devcontainer.
+        role_name: The role to be scaffolded.
     """
 
     creator_version: str
@@ -55,6 +56,7 @@ class Config:
     type: str = ""
     path: str | Path = "./"
     image: str = ""
+    role_name: str = "run"
 
     def __post_init__(self) -> None:
         """Post process config values."""

src/ansible_creator/resources/common/role/roles/run/README.md.j2

@@ -0,0 +1,89 @@
+{{ namespace }}.{{ collection_name }} {{ role_name }} Role
+========================
+
+A brief description of the role goes here.
+
+Requirements
+------------
+
+Any pre-requisites that may not be covered by Ansible itself or the role should be mentioned here. For instance, if the role uses the EC2 module, it may be a good idea to mention in this section that the boto package is required.
+
+Role Variables
+--------------
+
+A description of the settable variables for this role should go here, including any variables that are in defaults/main.yml, vars/main.yml, and any variables that can/should be set via parameters to the role. Any variables that are read from other roles and/or the global scope (ie. hostvars, group vars, etc.) should be mentioned here as well.
+
+Dependencies
+------------
+
+A list of other roles hosted on Galaxy should go here, plus any details in regards to parameters that may need to be set for other roles, or variables that are used from other roles.
+
+Example Playbook
+----------------
+
+Including an example of how to use your role (for instance, with variables passed in as parameters) is always nice for users too:
+
+```yaml
+- name: Execute tasks on servers
+  hosts: servers
+  roles:
+    - role: {{ namespace }}.{{ collection_name }}.run
+      run_x: 42
+```
+
+Another way to consume this role would be:
+
+```yaml
+- name: Initialize the run role from {{ namespace }}.{{ collection_name }}
+  hosts: servers
+  gather_facts: false
+  tasks:
+    - name: Trigger invocation of run role
+      ansible.builtin.include_role:
+        name: {{ namespace }}.{{ collection_name }}.run
+      vars:
+        run_x: 42
+```
+
+Role Idempotency
+----------------
+
+Designation of the role as idempotent (True/False)
+
+Role Atomicity
+----------------
+
+Designation of the role as atomic if applicable (True/False)
+
+Roll-back capabilities
+----------------------
+
+Define the roll-back capabilities of the role
+
+Argument Specification
+----------------------
+
+Including an example of how to add an argument Specification file that validates the arguments provided to the role.
+
+```
+argument_specs:
+  main:
+    short_description: Role description.
+    options:
+      string_arg1:
+        description: string argument description.
+        type: "str"
+        default: "x"
+        choices: ["x", "y"]
+```
+
+License
+-------
+
+# TO-DO: Update the license to the one you want to use (delete this line after setting the license)
+BSD
+
+Author Information
+------------------
+
+An optional section for the role authors to include contact information, or a website (HTML is not allowed).

src/ansible_creator/resources/common/role/roles/run/defaults/main.yml.j2

@@ -0,0 +1,2 @@
+---
+# defaults file for {{ namespace }}.{{ collection_name }}.{{ role_name }}

src/ansible_creator/resources/collection_project/roles/run/files/.keep renamed to src/ansible_creator/resources/common/role/roles/run/files/.keep

@@ -0,0 +1,2 @@
+---
+# handlers file for {{ namespace }}.{{ collection_name }}.{{ role_name }}

src/ansible_creator/resources/common/role/roles/run/handlers/main.yml.j2

@@ -0,0 +1,11 @@
+---
+# argument spec file for {{ namespace }}.{{ collection_name }}.{{ role_name }}
+
+argument_specs:
+  main:
+    short_description: Role description.
+    options:
+      my_variable:
+        type: str
+        description: A simple string argument for demonstration.
+        default: "default_value"

src/ansible_creator/resources/common/role/roles/run/meta/argument_specs.yml.j2

@@ -1,7 +1,7 @@
 galaxy_info:
   author: foo
-  description: {{ namespace|capitalize }}.{{ collection_name|capitalize }} Run Role
-  company: {{ namespace | capitalize }}
+  description: {{ namespace }}.{{ collection_name }} {{ role_name }} Role
+  company: {{ namespace }}
 
   # If the issue tracker for your role is not on github, uncomment the
   # next line and provide a value

src/ansible_creator/resources/collection_project/roles/run/meta/main.yml.j2 renamed to src/ansible_creator/resources/common/role/roles/run/meta/main.yml.j2

@@ -0,0 +1,7 @@
+---
+# tasks file for {{ namespace }}.{{ collection_name }}.{{ role_name }}
+
+# task example for debugging a value
+- name: Debug the value of my_variable
+  ansible.builtin.debug:
+    msg: "The value of my_variable is {% raw %}{{ my_variable }}{% endraw %}"

src/ansible_creator/resources/common/role/roles/run/tasks/main.yml.j2

@@ -0,0 +1,2 @@
+---
+# vars file for {{ namespace }}.{{ collection_name }}.{{ role_name }}

src/ansible_creator/resources/collection_project/roles/run/templates/.keep renamed to src/ansible_creator/resources/common/role/roles/run/templates/.keep

@@ -34,6 +34,7 @@ def __init__(
             config: App configuration object.
         """
         self._resource_type: str = config.resource_type
+        self._role_name: str = config.role_name
         self._plugin_type: str = config.plugin_type
         self._resource_id: str = f"common.{self._resource_type}"
         self._plugin_id: str = f"collection_project.plugins.{self._plugin_type}"
@@ -47,6 +48,8 @@ def __init__(
         self._dev_container_image = config.image
         self.output: Output = config.output
         self.templar = Templar()
+        self._namespace: str = config.namespace or ""
+        self._collection_name: str = config.collection_name or ""
 
     @property
     def _plugin_type_output(self) -> str:
@@ -140,6 +143,10 @@ def _resource_scaffold(self) -> None:
             template_data = self._get_devcontainer_template_data()
         elif self._resource_type == "execution-environment":
             template_data = self._get_ee_template_data()
+        elif self._resource_type == "role":
+            self._check_collection_path()
+            self._namespace, self._collection_name = self.role_galaxy()
+            template_data = self._get_role_template_data()
         else:
             msg = f"Unsupported resource type: {self._resource_type}"
             raise CreatorError(msg)
@@ -396,3 +403,43 @@ def _get_ee_template_data(self) -> TemplateData:
             resource_type=self._resource_type,
             creator_version=self._creator_version,
         )
+
+    def role_galaxy(self) -> tuple[str, str]:
+        """Fetch values from galaxy.yml file.
+
+        Returns:
+        tuple[str, str]: A tuple containing the namespace and collection name.
+                          Defaults are ('your-collection-namespace', 'your-collection-name')
+                          if the file is missing or keys are absent.
+        """
+        fallback_cn = "your-collection-namespace"
+        fallback_ns = "your-collection-name"
+        galaxy_file = self._add_path / "galaxy.yml"
+
+        # Check if galaxy.yml exists
+        if not galaxy_file.exists():
+            return fallback_cn, fallback_ns
+
+        # Load the galaxy.yml file
+        with galaxy_file.open("r", encoding="utf-8") as file:
+            data = yaml.safe_load(file)
+
+        # Ensure the namespace and name key exists
+        namespace = data.get("namespace", "your-collection-namespace")
+        collection_name = data.get("name", "your-collection-name")
+
+        return namespace, collection_name
+
+    def _get_role_template_data(self) -> TemplateData:
+        """Get the template data for role resources.
+
+        Returns:
+            TemplateData: Data required for templating the role resource.
+        """
+        return TemplateData(
+            resource_type=self._resource_type,
+            role_name=self._role_name,
+            namespace=self._namespace,
+            collection_name=self._collection_name,
+            creator_version=self._creator_version,
+        )

src/ansible_creator/resources/collection_project/roles/run/tests/inventory renamed to src/ansible_creator/resources/common/role/roles/run/tests/inventory

@@ -26,7 +26,7 @@ class Init:
         common_resources: List of common resources to copy.
     """
 
-    common_resources = (
+    common_resources: tuple[str, ...] = (
         "common.devcontainer",
         "common.devfile",
         "common.gitignore",
@@ -52,6 +52,7 @@ def __init__(
         self._project = config.project
         self._templar = Templar()
         self.output: Output = config.output
+        self._role_name: str = config.role_name
 
     def run(self) -> None:
         """Start scaffolding skeleton."""
@@ -128,10 +129,14 @@ def _scaffold(self) -> None:
             collection_name=self._collection_name,
             creator_version=self._creator_version,
             dev_file_name=self.unique_name_in_devfile(),
+            role_name=self._role_name,
         )
 
         if self._project == "execution_env":
             resources = (f"{self._project}_project",)
+        elif self._project == "collection":
+            self.common_resources = (*self.common_resources, "common.role")
+            resources = (f"{self._project}_project", *self.common_resources)
         else:
             resources = (f"{self._project}_project", *self.common_resources)
 

src/ansible_creator/resources/common/role/roles/run/vars/main.yml.j2

@@ -20,6 +20,7 @@ class TemplateData:
         resource_type: The type of resource to be scaffolded.
         plugin_type: The type of plugin to be scaffolded.
         plugin_name: The name of the plugin to be scaffolded.
+        role_name: The name of the role to be scaffolded.
         additions: A dictionary containing additional data to add to the gitignore.
         collection_name: The name of the collection.
         creator_version: The version of the creator.
@@ -34,6 +35,7 @@ class TemplateData:
     resource_type: str = ""
     plugin_type: str = ""
     plugin_name: str = ""
+    role_name: str = ""
     additions: dict[str, dict[str, dict[str, str | bool]]] = field(default_factory=dict)
     collection_name: str = ""
     creator_version: str = ""

src/ansible_creator/subcommands/add.py

@@ -33,6 +33,7 @@
     "sample_filter": "plugin_name",
     "sample_lookup": "plugin_name",
     "sample_test": "plugin_name",
+    "run": "role_name",
 }
 
 

src/ansible_creator/subcommands/init.py

@@ -1,4 +1,4 @@
-Testorg.Testcol Run Role
+testorg.testcol run Role
 ========================
 
 A brief description of the role goes here.
@@ -45,6 +45,38 @@ Another way to consume this role would be:
         run_x: 42
 ```
 
+Role Idempotency
+----------------
+
+Designation of the role as idempotent (True/False)
+
+Role Atomicity
+----------------
+
+Designation of the role as atomic if applicable (True/False)
+
+Roll-back capabilities
+----------------------
+
+Define the roll-back capabilities of the role
+
+Argument Specification
+----------------------
+
+Including an example of how to add an argument Specification file that validates the arguments provided to the role.
+
+```
+argument_specs:
+  main:
+    short_description: Role description.
+    options:
+      string_arg1:
+        description: string argument description.
+        type: "str"
+        default: "x"
+        choices: ["x", "y"]
+```
+
 License
 -------
 

src/ansible_creator/types.py

@@ -1,2 +1,2 @@
 ---
-# defaults file for run
+# defaults file for testorg.testcol.run

src/ansible_creator/utils.py

@@ -1,2 +1,2 @@
 ---
-# handlers file for run
+# handlers file for testorg.testcol.run

tests/fixtures/collection/testorg/testcol/roles/run/README.md

@@ -0,0 +1,11 @@
+---
+# argument spec file for testorg.testcol.run
+
+argument_specs:
+  main:
+    short_description: Role description.
+    options:
+      my_variable:
+        type: str
+        description: A simple string argument for demonstration.
+        default: "default_value"