UEPyScripts 1.2.7__tar.gz → 1.4.0__tar.gz

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: UEPyScripts
-Version: 1.2.7
+Version: 1.4.0
 Summary: Collection of Python tools and helpers designed to automate common Unreal Engine project tasks (builds, packaging, editor control, CI tasks, etc.).
 Project-URL: Changelog, https://github.com/TheEmidee/UEPyScripts/releases
 Project-URL: Homepage, https://github.com/TheEmidee/UEPyScripts
@@ -39,6 +39,7 @@ Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Utilities
 Requires-Python: >=3.11
 Requires-Dist: annotated-types
+Requires-Dist: blake3
 Requires-Dist: colorama
 Requires-Dist: gamedevtools
 Requires-Dist: invoke

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/pyproject.toml

@@ -44,7 +44,8 @@ dependencies = [
   "urllib3",
   "invoke",
   "types-invoke",
-  "GameDevTools"
+  "GameDevTools",
+  "blake3"
 ]
 
 urls.Changelog = "https://github.com/TheEmidee/UEPyScripts/releases"
@@ -91,7 +92,7 @@ fixable = ["ALL"]
 convention = "google"
 
 [tool.mypy]
-python_version = "3.9"
+python_version = "3.12"
 warn_return_any = true
 disallow_untyped_defs = true
 
@@ -131,6 +132,9 @@ ue-generate-solution = "uepyscripts.tools.ue.generate_solution:main"
 ue-close-editor = "uepyscripts.tools.ue.close_editor:main"
 ue-compile-editor = "uepyscripts.tools.ue.compile_editor:main"
 ue-check-engine-installation = "uepyscripts.tools.ue.check_engine_installation:main"
+ue-ugs-push = "uepyscripts.tools.ugs.push:main"
+ue-ugs-pull = "uepyscripts.tools.ugs.pull:main"
+ue-ugs-cleanup = "uepyscripts.tools.ugs.cleanup:main"
 ue-ci-cleanup = "uepyscripts.tools.ci.cleanup:main"
 ue-ci-run-buildgraph = "uepyscripts.tools.ci.buildgraph:main"
 

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/internal/config.py

@@ -13,12 +13,16 @@ class Config:
 
         logger.debug("Initializing config")
 
-        ini_files = [f for f in os.listdir(self.folder) if f.endswith(".ini")]
+        if self.folder.exists():
+            self.valid = True
+            ini_files = [f for f in os.listdir(self.folder) if f.endswith(".ini")]
 
-        for ini_file in ini_files:
-            ini_path = os.path.join(self.folder, ini_file)
-            logger.debug(f"Reading file: {ini_path}")
-            self.config.read(ini_path)
+            for ini_file in ini_files:
+                ini_path = os.path.join(self.folder, ini_file)
+                logger.debug(f"Reading file: {ini_path}")
+                self.config.read(ini_path)
+        else:
+            self.valid = False
 
     def __getitem__(self, key: str) -> configparser.SectionProxy:
         return self.config[key]
@@ -27,7 +31,4 @@ class Config:
 def resolve_config(project: Project) -> Config:
     config_folder = project.project_folders.config.joinpath("PyScripts")
 
-    if not config_folder.exists():
-        raise Exception("Impossible to find the PyScripts folder in Config")
-
     return Config(config_folder)

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/internal/engine.py

@@ -14,7 +14,8 @@ class Engine:
     class Runner:
         def __init__(self, path: Path, capture_output: bool, wait_process: bool = True, extra_args: list[str] = []) -> None:
             if not path.exists():
-                raise FileNotFoundError(f"The file {path} does not exist")
+                logger.warning(f"The file {path} does not exist")
+                return
 
             self.path = path.resolve()
             self.capture_output = capture_output
@@ -49,6 +50,7 @@ class Engine:
         self.path = self.root_path.joinpath("Engine").resolve()
         self.build_path = self.path.joinpath("Build").resolve()
         self.batchfiles_path = self.build_path.joinpath("BatchFiles").resolve()
+        self.saved_path = self.path.joinpath("Saved").resolve()
         self.version = self.get_version_number()
         self.uat_path = self.Runner(self.batchfiles_path.joinpath("RunUAT.bat"), True)
         self.ubt_path = self.Runner(

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/internal/engine_resolver.py

@@ -11,6 +11,13 @@ from ..tools.helpers import get_engine_root_folder_from_env_var, is_engine_from_
 from ..tools.winreg import get_registry_value
 
 
+def resolve_engine_from_native_project(project: Project) -> Optional[Path]:
+    if project.is_native_project:
+        return project.root_folder.parent
+
+    return None
+
+
 def resolve_engine_from_env_var(project: Project) -> Optional[Path]:
     return get_engine_root_folder_from_env_var(project.engine_association)
 
@@ -86,6 +93,7 @@ def resolve_engine_from_path(project: Project) -> Optional[Path]:
 
 def resolve_engine_path(project: Project) -> Path:
     resolvers = [
+        resolve_engine_from_native_project,
         resolve_engine_from_registry,
         resolve_engine_from_egs,
         resolve_engine_from_path,

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/internal/project.py

@@ -1,4 +1,3 @@
-import os
 from pathlib import Path
 from typing import Optional
 
@@ -44,6 +43,10 @@ class Project:
     def engine_association(self) -> str:
         return self.uproject.engine_association
 
+    @property
+    def is_native_project(self) -> bool:
+        return not self.engine_association
+
     def __str__(self) -> str:
         return f"""
 ----- Project infos -----
@@ -55,6 +58,24 @@ class Project:
         """
 
 
+EXCLUDED_DIR_NAMES = {"Engine", "FeaturePacks", "Samples", "Scripts", "Templates", ".git"}
+
+
+def find_uproject_in_subfolders(root: Path) -> Optional[Path]:
+    """Recursively search for a .uproject file under root, skipping excluded folders."""
+    for entry in root.iterdir():
+        if entry.is_dir():
+            if entry.name in EXCLUDED_DIR_NAMES:
+                continue
+            found = find_uproject_in_subfolders(entry)
+            if found:
+                return found
+        elif entry.is_file() and entry.suffix == ".uproject":
+            return entry.resolve()
+
+    return None
+
+
 def find_parent_with_project_file(starting_path: Path, max_parents: int = 10) -> Optional[Path]:
     current_path = Path(starting_path).resolve()
 
@@ -65,12 +86,16 @@ def find_parent_with_project_file(starting_path: Path, max_parents: int = 10) ->
             if file.is_file() and file.suffix == ".uproject":
                 return file.resolve()
 
+        build_version_path = path / "Engine" / "Build" / "Build.version"
+        if build_version_path.is_file():
+            return find_uproject_in_subfolders(path)
+
     return None
 
 
 def resolve_project(uproject_path: Optional[Path] = None) -> Project:
     if not uproject_path:
-        dir_path = Path(os.path.dirname(os.path.realpath(__file__)))
+        dir_path = Path.cwd()
         uproject_path = find_parent_with_project_file(dir_path)
         if not uproject_path:
             raise Exception(f"Could not find a uproject file from {dir_path}")

uepyscripts-1.4.0/src/uepyscripts/run/buildgraph.py

@@ -0,0 +1,125 @@
+import argparse
+import re
+from pathlib import Path
+from typing import Optional, Sequence
+
+from .. import logger
+from ..internal.config import resolve_config
+from ..internal.engine import resolve_engine
+from ..internal.project import resolve_project
+
+
+def run(target: str, arguments: list[str], script: Optional[str] = None, uproject_path: Optional[str] = None) -> int:
+    logger.info(f"Run Buildgraph - Target : {target}")
+    logger.info(f"Arguments : {arguments}")
+
+    project = resolve_project(Path(uproject_path) if uproject_path else None)
+    engine = resolve_engine(project)
+    config = resolve_config(project)
+
+    if script:
+        buildgraph_path = Path(script)
+    else:
+        buildgraph_path = project.root_folder.joinpath(config["Project"]["BuildgraphPath"])
+    logger.info(f"Buildgraph XML path : {buildgraph_path}")
+
+    if not buildgraph_path.exists():
+        raise Exception(f"Impossible to get a valid path to the buildgraph XML file. Current path : {buildgraph_path}")
+
+    extension = buildgraph_path.suffix
+    if extension != ".xml":
+        raise Exception(f"The buildgraph file must be a XML file. Current path : {buildgraph_path}")
+
+    uat_arguments = ["BuildGraph"]
+    uat_arguments.append(f"-script={buildgraph_path}")
+
+    # We can execute buildgraph without a target if the SingleNode argument is set
+    if target != "":
+        uat_arguments.append(f"-target={target}")
+
+    uat_arguments.append(f"-Project={project.uproject_path}")
+
+    if config.valid:
+        automation_scripts_directories = config["Project"].get("AutomationScriptsDirectories")
+        if automation_scripts_directories == "" or automation_scripts_directories is None:
+            logger.info("No automation scripts directory is set")
+        else:
+            automation_scripts_paths = automation_scripts_directories.split("+")
+
+            for automation_scripts_path_str in automation_scripts_paths:
+                automation_scripts_path = Path(automation_scripts_path_str)
+                automation_scripts_path = project.root_folder.joinpath(automation_scripts_path)
+                if not automation_scripts_path.exists():
+                    logger.warning(f"The automation scripts directory does not exist. Current value {automation_scripts_path}")
+                    continue
+
+                logger.info(f"Automation Scripts directory set to {automation_scripts_path}")
+                uat_arguments.append(f"-ScriptDir={automation_scripts_path}")
+
+        shared_properties_str = config["Project"].get("BuildgraphSharedProperties", "")
+        if shared_properties_str == "" or shared_properties_str is None:
+            logger.info("No shared properties to set")
+        else:
+            shared_properties = dict(pair.split("=") for pair in shared_properties_str.split("+")) if shared_properties_str else {}
+
+            if shared_properties is not None:
+                for key, value in shared_properties.items():
+                    uat_arguments.append(f"-set:{key}={value}")
+
+    for arg in arguments:
+        uat_arguments.append(arg)
+
+    return engine.uat(uat_arguments)
+
+
+def parse_arguments(argv: Optional[Sequence[str]] = None) -> tuple[argparse.Namespace, list[str]]:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="Execute a buildgraph task based on a target and properties.")
+    parser.add_argument("--target", type=str, default="", help="The target to run in the buildgraph file")
+    parser.add_argument(
+        "--script", type=str, default=None, help="Path to the buildgraph XML file. If not set, resolved from the project configuration."
+    )
+    parser.add_argument(
+        "--uproject",
+        type=str,
+        default=None,
+        help="Path to the .uproject file. Required when --script is set; otherwise auto-discovered from the current directory.",
+    )
+    return parser.parse_known_args(argv)
+
+
+def validate_config(target: str, arguments: list[str], script: Optional[str], uproject_path: Optional[str]) -> None:
+    """Validate the configuration values."""
+    pattern = r'-SingleNode=[^"]*'
+
+    if not target and not any(re.search(pattern, item) for item in arguments):
+        raise ValueError("Target is required")
+
+    if script and not uproject_path:
+        raise ValueError("--uproject is required when --script is set")
+
+
+def main(argv: Optional[Sequence[str]] = None) -> int:
+    args, other_arguments = parse_arguments(argv)
+
+    target = ""
+
+    if args.target:
+        target = args.target
+
+    try:
+        logger.info("Validating configuration")
+        validate_config(target, other_arguments, args.script, args.uproject)
+    except (ValueError, TypeError) as e:
+        logger.error(f"Configuration validation failed: {e}")
+        raise e
+
+    try:
+        return run(target, other_arguments, args.script, args.uproject)
+    except Exception as e:
+        logger.error(f"Execution failed: {e}")
+        raise e
+
+
+if __name__ == "__main__":
+    main()

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/tools/ci/buildgraph.py

@@ -53,7 +53,11 @@ def parse_arguments(argv: Optional[Sequence[str]] = None) -> tuple[argparse.Name
     parser = argparse.ArgumentParser(description="Execute a buildgraph task using a shared storage.")
     parser.add_argument("--target", type=str, help="The target to run in the buildgraph file")
     parser.add_argument("--build_tag", type=str, help="The tag that will be used to define a folder on a shared storage")
-    # parser.add_argument("remainder", nargs=argparse.REMAINDER, help="Properties (-set:K:V) and extra arguments")
+    parser.add_argument(
+        "--no-single-node",
+        action="store_true",
+        help="Set this flag to not use SingleNode but use Target. This also disables using the shared storage dir.",
+    )
 
     args, unknown_args = parser.parse_known_args(argv)
     return args, unknown_args
@@ -115,17 +119,22 @@ def main(argv: Optional[Sequence[str]] = None) -> int:
 
     logger.info(f"Running ci.buildgraph with build tag: {args.build_tag} on machine {socket.gethostname()}")
 
-    shared_storage_dir = Path(config["Jenkins"]["BuildgraphSharedStoragePath"]) / args.build_tag
-    logger.info(f"Shared storage directory: {shared_storage_dir}")
+    default_arguments: list[str] = ["-BuildMachine", "-NoP4"]
 
-    remove_task_shared_storage_dir(shared_storage_dir, args.target)
-    try_delete_local_buildgraph_folder(args.build_tag)
-    cleanup_local_folder()
+    if args.no_single_node:
+        logger.info("The flag --no-single-node was passed. Run the task with Target and not with SingleNode")
+        default_arguments += [f"--target={args.target}"]
+    else:
+        shared_storage_dir = Path(config["Jenkins"]["BuildgraphSharedStoragePath"]) / args.build_tag
+        logger.info(f"Shared storage directory: {shared_storage_dir}")
 
-    updated_args = update_or_add_argument(
-        unknown_args,
-        ["-BuildMachine", f"-SharedStorageDir={shared_storage_dir}", "-WriteToSharedStorage", f"-SingleNode={args.target}", "-NoP4"],
-    )
+        remove_task_shared_storage_dir(shared_storage_dir, args.target)
+        try_delete_local_buildgraph_folder(args.build_tag)
+        cleanup_local_folder()
+
+        default_arguments += [f"-SharedStorageDir={shared_storage_dir}", "-WriteToSharedStorage", f"-SingleNode={args.target}"]
+
+    updated_args = update_or_add_argument(unknown_args, default_arguments)
 
     return buildgraph.main(updated_args)
 

uepyscripts-1.4.0/src/uepyscripts/tools/subprocess.py

@@ -0,0 +1,50 @@
+import subprocess
+import sys
+from typing import Any
+
+from uepyscripts import logger
+
+
+def run_subprocess(cmd: list[str], log_output: bool = True) -> int:
+    """Run a subprocess with the given command and return its exit code (or 0 if fire-and-forget)."""
+    kwargs: dict[str, Any] = {}
+    creationflags = 0
+
+    if sys.platform == "win32":
+        creationflags = subprocess.CREATE_NEW_PROCESS_GROUP | subprocess.CREATE_NO_WINDOW
+        startupinfo = subprocess.STARTUPINFO()
+        startupinfo.dwFlags |= subprocess.STARTF_USESHOWWINDOW
+        startupinfo.wShowWindow = subprocess.SW_HIDE
+        kwargs["startupinfo"] = startupinfo
+    else:
+        kwargs["start_new_session"] = True
+
+    if log_output:
+        process = subprocess.Popen(
+            cmd,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            text=True,
+            bufsize=1,
+            creationflags=creationflags,
+            **kwargs,
+        )
+
+        assert process.stdout is not None
+        for line in process.stdout:
+            line = line.strip()
+            if line:
+                logger.info(line)
+
+        process.wait()
+        return process.returncode
+    else:
+        subprocess.Popen(
+            cmd,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            stdin=subprocess.DEVNULL,
+            creationflags=creationflags,
+            **kwargs,
+        )
+        return 0

{uepyscripts-1.2.7 → uepyscripts-1.4.0}/src/uepyscripts/tools/ue/engine_installation/engine_installer.py

@@ -63,9 +63,9 @@ class TaskList:
 
 class EngineInstaller:
     def __init__(self, project: Project, unattended: bool = False) -> None:
+        self.project = project
         self.check_requirements()
 
-        self.project = project
         try:
             self.engine_destination_folder = resolve_engine_destination(project)
         except FileNotFoundError as e:
@@ -95,6 +95,9 @@ class EngineInstaller:
         if not is_7z_installed():
             raise RuntimeError("7-Zip is not installed or not found in PATH. Please install 7-Zip to proceed.")
 
+        if self.project.is_native_project:
+            raise RuntimeError("A native project should be in the same folder than its engine")
+
     def get_project_platforms(self) -> List[str]:
         platforms: str = self.config["EngineUpdate.TurnKey"]["Platforms"]
         return platforms.split("+")

uepyscripts-1.4.0/src/uepyscripts/tools/ugs/cleanup.py

@@ -0,0 +1,126 @@
+"""
+Prunes S3 data for commits whose branch no longer exists on the remote.
+
+  - A commit is "orphaned" once it is no longer reachable from any current
+    remote branch tip (i.e. its branch was deleted). This needs no per-branch
+    bookkeeping in S3 — reachability is computed straight from git, the same
+    way push.py/pull.py resolve diff baselines and sync targets.
+  - Deletes manifests/{sha}.json, deltas/{sha}.7z and checkpoints/{sha}.7z for
+    every orphaned sha, then rewrites index.json/checkpoints.json to drop them.
+  - Intended to run on a schedule (e.g. a periodic Jenkins job).
+"""
+
+import argparse
+import json
+from pathlib import Path
+from typing import cast
+
+from gamedevtools.s3 import S3Client
+
+from uepyscripts import logger
+from uepyscripts.internal.engine import resolve_engine
+from uepyscripts.internal.project import resolve_project
+from uepyscripts.tools.ugs.git_utils import get_remote_reachable_shas
+
+
+class Context:
+    def __init__(self, args: argparse.Namespace) -> None:
+        self.args = args
+        self.s3_client: S3Client = S3Client(
+            access_key=args.s3_access_key,
+            secret_key=args.s3_secret_key,
+            region=args.s3_bucket_region,
+        )
+
+
+def build_orphaned_keys(orphaned: list[str]) -> list[str]:
+    """S3 keys to delete for each orphaned sha. Including a key that was never
+    written is harmless — S3 batch-delete is a no-op for missing keys, the same
+    assumption prune_old_versions (push.py) already relies on."""
+    keys: list[str] = []
+    for sha in orphaned:
+        keys.append(f"manifests/{sha}.json")
+        keys.append(f"deltas/{sha}.7z")
+        keys.append(f"checkpoints/{sha}.7z")
+    return keys
+
+
+def parse_arguments() -> argparse.Namespace:
+    """Parse command line arguments."""
+    parser = argparse.ArgumentParser(description="Delete S3 binary-publish data for branches that no longer exist on the remote.")
+    parser.add_argument("--uproject-path", type=Path, help=("Path to a native uproject file"))
+    parser.add_argument("--s3-bucket-name", type=str, help=("AWS S3 Bucket Name"))
+    parser.add_argument("--s3-bucket-region", type=str, help=("AWS S3 Bucket Region"))
+    parser.add_argument("--s3-access-key", type=str, help=("AWS S3 Access Key"))
+    parser.add_argument("--s3-secret-key", type=str, help=("AWS S3 Secret Key"))
+    parser.add_argument("--remote", type=str, default="origin", help="Git remote to check branches against (default: origin)")
+    parser.add_argument(
+        "--dry-run",
+        action=argparse.BooleanOptionalAction,
+        default=False,
+        help="Log what would be deleted without touching S3",
+    )
+
+    return parser.parse_args()
+
+
+def main() -> None:
+    args = parse_arguments()
+
+    logger.info("Cleanup orphaned binary publishes...")
+
+    try:
+        project = resolve_project(args.uproject_path)
+    except Exception as e:
+        logger.fatal(f"Project resolution failed: {e}")
+        exit(1)
+
+    engine = resolve_engine(project)
+    context = Context(args)
+
+    logger.info(f"Fetching '{args.remote}' and computing reachable commits")
+    reachable = get_remote_reachable_shas(engine.root_path, args.remote)
+
+    if not reachable:
+        logger.fatal(f"No commit is reachable from any branch on remote '{args.remote}' — aborting without deleting anything")
+        exit(1)
+
+    logger.info("Download index.json")
+    index = cast(list[str], context.s3_client.download_json(context.args.s3_bucket_name, "index.json", default=[]))
+
+    logger.info("Download checkpoints.json")
+    checkpoints = cast(list[str], context.s3_client.download_json(context.args.s3_bucket_name, "checkpoints.json", default=[]))
+
+    orphaned = [sha for sha in index if sha not in reachable]
+
+    if not orphaned:
+        logger.info(f"Nothing to clean up. {len(index)} published commit(s), all reachable from '{args.remote}'.")
+        return
+
+    logger.info(f"Found {len(orphaned)} orphaned commit(s) out of {len(index)} published")
+
+    keys = build_orphaned_keys(orphaned)
+
+    if args.dry_run:
+        logger.info(f"[dry-run] Would delete {len(keys)} key(s):")
+        for key in keys:
+            logger.info(f"[dry-run]   {key}")
+        return
+
+    context.s3_client.delete_keys(context.args.s3_bucket_name, keys)
+
+    orphaned_set = set(orphaned)
+    index = [sha for sha in index if sha not in orphaned_set]
+    checkpoints = [sha for sha in checkpoints if sha not in orphaned_set]
+
+    logger.info("Upload index.json")
+    context.s3_client.upload_bytes(context.args.s3_bucket_name, "index.json", json.dumps(index).encode(), content_type="application/json")
+
+    logger.info("Upload checkpoints.json")
+    context.s3_client.upload_bytes(context.args.s3_bucket_name, "checkpoints.json", json.dumps(checkpoints).encode(), content_type="application/json")
+
+    logger.info(f"Cleanup done. Deleted {len(keys)} key(s) for {len(orphaned)} orphaned commit(s).")
+
+
+if __name__ == "__main__":
+    main()

uepyscripts-1.4.0/src/uepyscripts/tools/ugs/git_utils.py

@@ -0,0 +1,49 @@
+import os
+import subprocess
+from pathlib import Path
+
+ANCESTRY_LOOKBACK = 2000
+
+
+def get_current_sha(cwd: Path) -> str:
+    sha = os.environ.get("GIT_COMMIT")  # Jenkins sets this automatically
+    if sha:
+        return sha
+    return subprocess.check_output(["git", "rev-parse", "HEAD"], cwd=cwd, text=True).strip()
+
+
+def get_current_branch(cwd: Path) -> str:
+    branch = os.environ.get("GIT_BRANCH")  # Jenkins' Git plugin sets this, sometimes as "origin/<branch>"
+    if branch:
+        return branch.split("/", 1)[1] if "/" in branch else branch
+    return subprocess.check_output(["git", "rev-parse", "--abbrev-ref", "HEAD"], cwd=cwd, text=True).strip()
+
+
+def get_local_ancestry(cwd: Path, limit: int = ANCESTRY_LOOKBACK) -> list[str]:
+    out = subprocess.check_output(["git", "log", f"-{limit}", "--format=%H", "HEAD"], cwd=cwd, text=True)
+    return out.splitlines()
+
+
+def get_remote_reachable_shas(cwd: Path, remote: str = "origin") -> set[str]:
+    """All commit SHAs reachable from any current branch tip on `remote`, after
+    pruning local remote-tracking refs for branches deleted on the remote."""
+    subprocess.run(["git", "fetch", "--prune", remote], cwd=cwd, check=True, capture_output=True, text=True)
+    out = subprocess.check_output(["git", "rev-list", f"--remotes={remote}"], cwd=cwd, text=True)
+    return set(out.splitlines())
+
+
+def resolve_nearest_published_ancestor(index: list[str], ancestry: list[str]) -> tuple[str | None, bool]:
+    """Finds the nearest ancestor SHA (including HEAD itself) present in the
+    index. Returns None if nothing has ever been published reachable from HEAD
+    within the walked ancestry. The bool is True when the match was found by
+    walking the ancestry itself (an exact match), False when falling back to
+    the most recent published version because nothing in the ancestry matched."""
+    index_set = set(index)
+    for sha in ancestry:
+        if sha in index_set:
+            return sha, True
+
+    if index:
+        return index[-1], False
+
+    return None, True