cumulusci-plus 5.0.0__py3-none-any.whl

cumulusci/tasks/vcs/commit_status.py

@@ -0,0 +1,58 @@
+from cumulusci.core.exceptions import DependencyLookupError, VcsNotFoundError
+from cumulusci.tasks.base_source_control_task import BaseSourceControlTask
+from cumulusci.tasks.salesforce.BaseSalesforceApiTask import BaseSalesforceApiTask
+from cumulusci.vcs.bootstrap import get_version_id_from_commit
+
+
+class GetPackageDataFromCommitStatus(BaseSourceControlTask, BaseSalesforceApiTask):
+    task_options = {
+        "context": {
+            "description": "Name of the commit status context",
+            "required": True,
+        },
+        "version_id": {"description": "Package version id"},
+    }
+
+    def _run_task(self):
+        self.api_version = self.project_config.project__api_version
+        repo = self.get_repo()
+        context = self.options["context"]
+        commit_sha = self.project_config.repo_commit or ""
+
+        dependencies = []
+        version_id = self.options.get("version_id")
+        if version_id is None:
+            try:
+                version_id = get_version_id_from_commit(repo, commit_sha, context)
+            except VcsNotFoundError as e:
+                self.logger.error(e)
+                self.logger.error(
+                    "This error usually means your local commit has not been pushed "
+                    "or that a feature test package has not yet been built."
+                )
+
+        if version_id:
+            dependencies = self._get_dependencies(version_id)
+        else:
+            raise DependencyLookupError(
+                f"Could not find package version id in '{context}' commit status for commit {commit_sha}."
+            )
+
+        self.return_values = {"dependencies": dependencies, "version_id": version_id}
+
+    def _get_dependencies(self, version_id):
+        res = self.tooling.query(
+            f"SELECT Dependencies FROM SubscriberPackageVersion WHERE Id='{version_id}'"
+        )
+        if res["records"]:
+            subscriber_version = res["records"][0]
+            dependencies = subscriber_version["Dependencies"] or {"ids": []}
+            dependencies = [
+                {"version_id": d["subscriberPackageVersionId"]}
+                for d in dependencies["ids"]
+            ]
+            return dependencies
+        else:
+            raise DependencyLookupError(
+                f"Could not look up dependencies of {version_id}"
+            )

cumulusci/tasks/vcs/create_commit_status.py

@@ -0,0 +1,37 @@
+from cumulusci.tasks.base_source_control_task import BaseSourceControlTask
+
+
+class CreatePackageDataFromCommitStatus(BaseSourceControlTask):
+    task_options = {
+        "state": {
+            "description": "sha of the commit",
+            "required": True,
+        },
+        "context": {
+            "description": "Name of the commit status context",
+            "required": True,
+        },
+        "commit_id": {
+            "description": "sha of the commit",
+        },
+        "description": {
+            "description": "Description of the commit status",
+        },
+        "target_url": {
+            "description": "URL to associate with the commit status",
+        },
+    }
+
+    def _run_task(self):
+        repo = self.get_repo()
+        commit_sha = self.options["commit_id"] or self.project_config.repo_commit or ""
+
+        commit = repo.create_commit_status(
+            commit_sha,
+            state=self.options["state"],
+            context=self.options["context"],
+            description=self.options.get("description"),
+            target_url=self.options.get("target_url"),
+        )
+
+        self.return_values = {"commit_id": commit.sha}

cumulusci/tasks/vcs/download_extract.py

@@ -0,0 +1,199 @@
+import os
+import time
+from pathlib import Path
+
+import yaml
+
+from cumulusci.cli.utils import timestamp_file
+from cumulusci.core.exceptions import CumulusCIException, TaskOptionsError
+from cumulusci.core.tasks import BaseTask
+from cumulusci.core.utils import process_bool_arg, process_list_arg
+from cumulusci.utils import download_extract_vcs_from_repo, filter_namelist
+from cumulusci.vcs.bootstrap import get_repo_from_url
+from cumulusci.vcs.models import AbstractRepo
+from cumulusci.vcs.utils import get_ref_from_options
+
+
+class DownloadExtract(BaseTask):
+    task_docs = """A task to download and extract files and folders from a Git repository.
+    Will download the repository and extract it to a specified directory.
+    """
+
+    task_options = {
+        "repo_url": {"description": "The url to the repo", "required": True},
+        "target_directory": {
+            "description": "The directory to extract the repo contents to."
+            "If not set, contents will be extracted to the current directory."
+            "If set, it must be a relative path from the project root or an absolute path.",
+            "required": True,
+        },
+        "sub_folder": {
+            "description": "The subfolder directory to download from the repo."
+        },
+        "branch": {
+            "description": "The branch to fetch from the repo."
+            "if 'ref' or 'tag_name' is not set. The default branch will be set."
+        },
+        "tag_name": {
+            "description": "The name of the tag that should be downloaded."
+            "Values of 'latest' and 'latest_beta' are also allowed."
+            "Not required if 'branch' is set."
+            "Required if 'ref' is not set."
+        },
+        "ref": {
+            "description": "The git reference to download. Takes precedence over 'tag_name' and 'branch'."
+            "Required if 'tag_name' or 'branch' is not set."
+        },
+        "include": {
+            "description": "A list of paths from repo root to include. Directories must end with a trailing slash."
+        },
+        "renames": {
+            "description": "A list of paths to rename in the target repo, given as `local:` `target:` pairs."
+        },
+        "force": {"description": "Force Download files in the repo."},
+    }
+
+    def _init_options(self, kwargs):
+        super()._init_options(kwargs)
+        self.options["include"] = process_list_arg(self.options.get("include", None))
+
+        self.options["renames"] = self._process_renames(self.options.get("renames", []))
+
+        self.options["force"] = process_bool_arg(self.options.get("force", False))
+
+    def _init_repo(self):
+        self.repo: AbstractRepo = get_repo_from_url(
+            self.project_config, self.options["repo_url"]
+        )
+        self._set_ref()
+        self.commit = self.repo.get_ref(self.ref).sha
+
+    def _run_task(self):
+        self._set_target_directory()
+
+        if not self._check_latest_commit():
+            self.logger.info(
+                f"Skipping download, no new changes in {self.options['repo_url']} since last run."
+            )
+            return
+
+        self.logger.info(
+            f"{'Force ' if self.options['force'] else ''}Downloading files from {self.options['repo_url']}."
+        )
+
+        target = Path(os.path.join(self.options["target_directory"]))
+        if not target.exists():
+            target.mkdir(parents=True, exist_ok=True)
+
+        self._download_repo_and_extract(target)
+        self._rename_files(target)
+
+        with timestamp_file(self.options["target_directory"]) as f:
+            yaml.dump({"commit": self.commit, "timestamp": time.time()}, f)
+
+    def _process_renames(self, renamed_paths):
+        """
+        For each entry in renames, any renames and store them
+        in self.local_to_target_paths.
+        """
+        if not renamed_paths:
+            return {}
+
+        is_list_of_dicts = all(isinstance(pair, dict) for pair in renamed_paths)
+        dicts_have_correct_keys = is_list_of_dicts and all(
+            {"local", "target"} == pair.keys() for pair in renamed_paths
+        )
+
+        ERROR_MSG = (
+            "Renamed paths must be a list of dicts with `local:` and `target:` keys."
+        )
+        if not dicts_have_correct_keys:
+            raise TaskOptionsError(ERROR_MSG)
+
+        local_to_target_paths = {}
+
+        for rename in renamed_paths:
+            local_path = rename.get("local")
+            target_path = rename.get("target")
+
+            if local_path and target_path:
+                local_to_target_paths[local_path] = target_path
+            else:
+                raise TaskOptionsError(ERROR_MSG)
+
+        return local_to_target_paths
+
+    def _set_ref(self):
+        if "branch" in self.options:
+            branch = self.options.get("branch")
+            self.ref = f"heads/{branch}"
+            return
+
+        try:
+            self.ref = get_ref_from_options(self.project_config, self.options)
+        except CumulusCIException:
+            # If no ref, tag_name or branch is set, default to the repo's default branch
+            self.ref = f"heads/{self.repo.default_branch}"
+
+    def _download_repo_and_extract(self, path):
+        zf = download_extract_vcs_from_repo(
+            self.repo, subfolder=self.options.get("sub_folder", None), ref=self.commit
+        )
+
+        included_members = zf.namelist()
+        if self.options["include"]:
+            included_members = filter_namelist(
+                includes=self.options["include"], namelist=zf.namelist()
+            )
+        zf.extractall(path=path, members=included_members)
+        zf.close()
+
+    def _rename_files(self, zip_dir):
+        for local_name, target_name in self.options["renames"].items():
+            local_path = Path(zip_dir, local_name)
+            if local_path.exists():
+                target_path = Path(zip_dir, target_name)
+                target_path.parent.mkdir(parents=True, exist_ok=True)
+                local_path.replace(target_path)
+
+    def _set_target_directory(self):
+        """
+        Sets the target directory where the repo contents will be extracted.
+        If not set, defaults to the current directory.
+        """
+        # Check if self.options.get("target_directory") is absolute or relative path.
+        target_directory = self.options["target_directory"]
+        if not os.path.isabs(target_directory):
+            # If it's a relative path, make it absolute based on project root
+            target_directory = os.path.join(
+                self.project_config.repo_root, target_directory
+            )
+        self.options["target_directory"] = target_directory
+
+    def _check_latest_commit(self):
+        """checks for the latest commit in repo, max once per hour"""
+        if self.options["force"]:
+            self._init_repo()
+            return True
+
+        check = True
+
+        timestamp = 0
+        commit = ""
+        if os.path.isfile(f"{self.options['target_directory']}/cumulus_timestamp"):
+            with timestamp_file(self.options["target_directory"]) as f:
+                loaded_data = yaml.safe_load(f)
+                timestamp = loaded_data.get("timestamp", 0)
+                commit = loaded_data.get("commit", "")
+
+        delta = time.time() - timestamp
+        check = delta > 3600
+
+        if not check:
+            return False
+
+        self._init_repo()
+        if self.commit != commit:
+            return True
+
+        return False

cumulusci/tasks/vcs/merge.py

@@ -0,0 +1,298 @@
+from cumulusci.core.utils import process_bool_arg
+from cumulusci.tasks.base_source_control_task import BaseSourceControlTask
+from cumulusci.utils.git import is_release_branch
+from cumulusci.vcs.models import AbstractBranch, AbstractRepoCommit
+
+
+class MergeBranch(BaseSourceControlTask):
+    task_docs = """
+    Merges the most recent commit on the current branch into other branches depending on the value of source_branch.
+
+    If source_branch is a branch that does not start with the specified branch_prefix, then the commit will be
+    merged to all branches that begin with branch_prefix and are not themselves child branches (i.e. branches don't contain '__' in their name).
+
+    If source_branch begins with branch_prefix, then the commit is merged to all child branches of source_branch.
+    """
+    task_options = {  # TODO: should use `class Options instead`
+        "commit": {
+            "description": "The commit to merge into feature branches.  Defaults to the current head commit."
+        },
+        "source_branch": {
+            "description": "The source branch to merge from.  Defaults to project__git__default_branch."
+        },
+        "branch_prefix": {
+            "description": "A list of prefixes of branches that should receive the merge.  Defaults to project__git__prefix_feature"
+        },
+        "skip_future_releases": {
+            "description": "If true, then exclude branches that start with the branch prefix if they are not for the lowest release number. Defaults to True."
+        },
+        "update_future_releases": {
+            "description": "If true, then include release branches that are not the lowest release number even if they are not child branches. Defaults to False."
+        },
+        "create_pull_request_on_conflict": {
+            "description": "If true, then create a pull request when a merge conflict arises. Defaults to True."
+        },
+    }
+
+    def _init_options(self, kwargs):
+        super()._init_options(kwargs)
+
+        if "commit" not in self.options:
+            self.options["commit"] = self.project_config.repo_commit
+        if "branch_prefix" not in self.options:
+            self.options[
+                "branch_prefix"
+            ] = self.project_config.project__git__prefix_feature
+        if "source_branch" not in self.options:
+            self.options[
+                "source_branch"
+            ] = self.project_config.project__git__default_branch
+        if "skip_future_releases" not in self.options:
+            self.options["skip_future_releases"] = True
+        else:
+            self.options["skip_future_releases"] = process_bool_arg(
+                self.options.get("skip_future_releases")
+            )
+        self.options["update_future_releases"] = process_bool_arg(
+            self.options.get("update_future_releases") or False
+        )
+        if "create_pull_request_on_conflict" not in self.options:
+            self.options["create_pull_request_on_conflict"] = True
+        else:
+            self.options["create_pull_request_on_conflict"] = process_bool_arg(
+                self.options.get("create_pull_request_on_conflict")
+            )
+
+    def _init_task(self):
+        super()._init_task()
+        self.repo = self.get_repo()
+
+    def _run_task(self):
+        self._validate_source_branch(self.options["source_branch"])
+        branches_to_merge = self._get_branches_to_merge()
+
+        for branch in branches_to_merge:
+            self._merge(
+                branch.name,
+                self.options["source_branch"],
+                self.options["commit"],
+            )
+
+    def _validate_source_branch(self, source_branch):
+        """Validates that the source branch exists in the repository"""
+        branch: AbstractBranch = self.repo.branch(source_branch)
+        self.options["source_branch"] = branch.name
+
+    def _get_existing_prs(self, source_branch, branch_prefix):
+        """Returns the existing pull requests from the source branch
+        to other branches that are candidates for merging."""
+        existing_prs = []
+        for pr in self.repo.pull_requests(state="open"):
+            if pr.base_ref.startswith(branch_prefix) and pr.head_ref == source_branch:
+                existing_prs.append(pr.base_ref)
+        return existing_prs
+
+    def _get_branches_to_merge(self):
+        """
+        If source_branch is the default branch (or a branch that doesn't start with a prefix), we
+        gather all branches with branch_prefix that are not child branches.
+        NOTE: We only include the _next_ closest release branch when automerging from main.
+        A change on main may conflict with the current contents of the lowest release branch.
+        In this case, we would like for that conflict to only need to be resolved once
+        (not once for each release branch).
+
+        If source_branch starts with branch prefix, we gather
+        all branches with branch_prefix that are direct descendents of source_branch.
+
+        If update_future_releases is True, and source_branch is a release branch
+        then we also collect all future release branches.
+        """
+        repo_branches = list(self.repo.branches())
+        next_release = self._get_next_release(repo_branches)
+        skip_future_releases = self.options["skip_future_releases"]
+        update_future_releases = self._update_future_releases(next_release)
+
+        child_branches = []
+        main_descendents = []
+        release_branches = []
+        for branch in repo_branches:
+            # check for adding future release branches
+            if update_future_releases and self._is_future_release_branch(
+                branch.name, next_release
+            ):
+                release_branches.append(branch)
+                continue
+
+            # check if we looking at the source_branch
+            if branch.name == self.options["source_branch"]:
+                self.logger.debug(f"Skipping branch {branch.name}: is source branch")
+                continue
+
+            # check for branch prefix match
+            elif not branch.name.startswith(self.options["branch_prefix"]):
+                self.logger.debug(
+                    f"Skipping branch {branch.name}: does not match prefix '{self.options['branch_prefix']}'"
+                )
+                continue
+
+            # check if source_branch doesn't have prefix and is not a child (e.g. main)
+            elif (
+                not self.options["source_branch"].startswith(
+                    self.options["branch_prefix"]
+                )
+                and "__" not in branch.name
+            ):
+                # only merge to the lowest numbered release branch
+                # when merging from a branch without a prefix (e.g. main)
+                if skip_future_releases and self._is_future_release_branch(
+                    branch.name, next_release
+                ):
+                    continue
+                main_descendents.append(branch)
+
+            # else, we have a branch that starts with branch_prefix
+            # check is this branch is a direct descendent
+            elif self._is_source_branch_direct_descendent(branch.name):
+                child_branches.append(branch)
+
+            # else not a direct descendent
+            else:
+                self.logger.debug(
+                    f"Skipping branch {branch.name}: is not a direct descendent of {self.options['source_branch']}"
+                )
+
+        to_merge = []
+        if child_branches:
+            self.logger.debug(
+                f"Found child branches to update: {[branch.name for branch in child_branches]}"
+            )
+            to_merge = child_branches
+        elif self.options["source_branch"].startswith(self.options["branch_prefix"]):
+            self.logger.debug(
+                f"No children found for branch {self.options['source_branch']}"
+            )
+
+        if release_branches:
+            self.logger.debug(
+                f"Found future release branches to update: {[branch.name for branch in release_branches]}"
+            )
+            to_merge = to_merge + release_branches
+
+        if main_descendents:
+            self.logger.debug(
+                f"Found descendents of {self.options['source_branch']} to update: {[branch.name for branch in main_descendents]}"
+            )
+            to_merge = to_merge + main_descendents
+
+        return to_merge
+
+    def _get_next_release(self, repo_branches):
+        """Returns the integer that corresponds to the lowest release number found on all release branches.
+        NOTE: We assume that once a release branch is merged that it will be deleted.
+        """
+        release_nums = [
+            self._get_release_number(branch.name)
+            for branch in repo_branches
+            if self._is_release_branch(branch.name)
+        ]
+        next_release = sorted(release_nums)[0] if release_nums else None
+        return next_release
+
+    def _update_future_releases(self, next_release):
+        """Determines whether or not to update future releases.
+        Returns True if all of the below checks are True. False otherwise.
+
+        Checks:
+        (1) Did we receive the 'update_future_release' flag?
+        (2) Is the source_branch a release branch?
+        (3) Is it the lowest numbered release branch that exists?
+
+        NOTE: This functionality assumes that the lowest numbered release branch in the repo is
+        the next closest release. Put another way, once a release branch is merged we assume that it is immediately deleted.
+        """
+        update_future_releases = False
+        if (
+            self.options["update_future_releases"]
+            and self._is_release_branch(self.options["source_branch"])
+            and next_release == self._get_release_number(self.options["source_branch"])
+        ):
+            update_future_releases = True
+        return update_future_releases
+
+    def _is_release_branch(self, branch_name):
+        """A release branch begins with the given prefix"""
+        return is_release_branch(branch_name, self.options["branch_prefix"])
+
+    def _get_release_number(self, branch_name) -> int:
+        """Get the release number from a release branch name.
+
+        Assumes we already know it is a release branch.
+        """
+        return int(branch_name.split(self.options["branch_prefix"])[1])
+
+    def _merge(self, branch_name, source, commit):
+        """Attempt to merge a commit from source to branch with branch_name"""
+        compare = self.repo.compare_commits(branch_name, commit, source)
+        if not compare or not compare.files:
+            self.logger.info(f"Skipping branch {branch_name}: no file diffs found")
+            return
+
+        ret = self.repo.merge(branch_name, commit, source)
+        if isinstance(ret, AbstractRepoCommit):
+            self.logger.info(
+                f"Merged {compare.behind_by} commits into branch: {branch_name}"
+            )
+        elif ret is None:
+            if self.options["create_pull_request_on_conflict"]:
+                self._create_conflict_pull_request(branch_name, source)
+            else:
+                self.logger.info(
+                    f"Merge conflict on branch {branch_name}: skipping pull request creation"
+                )
+
+    def _create_conflict_pull_request(self, branch_name, source):
+        """Attempt to create a pull request from source into branch_name if merge operation encounters a conflict"""
+        if branch_name in self._get_existing_prs(
+            self.options["source_branch"], self.options["branch_prefix"]
+        ):
+            self.logger.info(
+                f"Merge conflict on branch {branch_name}: merge PR already exists"
+            )
+            return
+
+        pull = self.repo.create_pull(
+            title=f"Merge {source} into {branch_name}",
+            base=branch_name,
+            head=source,
+            body="This pull request was automatically generated because "
+            "an automated merge hit a merge conflict",
+            options={
+                "error_message": f"Error creating merge conflict pull request to merge {source} into {branch_name}"
+            },
+        )
+
+        if pull is not None:
+            self.logger.info(
+                f"Merge conflict on branch {branch_name}: created pull request #{pull.number}"
+            )
+            return pull
+
+    def _is_source_branch_direct_descendent(self, branch_name):
+        """Returns True if branch is a direct descendent of the source branch"""
+        source_dunder_count = self.options["source_branch"].count("__")
+        return (
+            branch_name.startswith(f"{self.options['source_branch']}__")
+            and branch_name.count("__") == source_dunder_count + 1
+        )
+
+    def _is_future_release_branch(self, branch_name, next_release):
+        return (
+            self._is_release_branch(branch_name)
+            and branch_name != self.options["source_branch"]
+            and self._get_release_num(branch_name) > next_release
+        )
+
+    def _get_release_num(self, release_branch_name):
+        """Given a release branch, returns an integer that
+        corresponds to the release number for that branch"""
+        return int(release_branch_name.split(self.options["branch_prefix"])[1])