calkit-python 0.47.3__py3-none-any.whl → 0.47.4__py3-none-any.whl

calkit/cli/latex.py

@@ -17,7 +17,7 @@ from typing_extensions import Annotated
 
 import calkit
 import calkit.latex
-from calkit.cli import raise_error
+from calkit.cli import raise_error, warn
 
 latex_app = typer.Typer(no_args_is_help=True)
 
@@ -301,9 +301,14 @@ def build(
 
 
 DIFF_TMP_DIR = calkit.latex.DIFF_TMP_DIR
-DIFF_AUX_DIR = calkit.latex.DIFF_AUX_DIR
+# A verbatim input named by a macro parameter, e.g., \verbatiminput{#1.wcsum}
+# in a \newcommand, which latexdiff dies trying to open. Breaking the line
+# after the command reads the same to TeX, but not to latexdiff's pattern.
+_VERBATIM_PARAM_RE = re.compile(
+    r"(\\(?:verbatiminput\*?|lstinputlisting))"
+    r"(?=\s*(?:\[[^\]\n]*\])?\s*\{[^}\n]*#[0-9])"
+)
 get_diff_path = calkit.latex.get_diff_path
-_is_immutable_ref = calkit.latex._is_immutable_ref
 _default_base_ref = calkit.latex.default_base_ref
 
 
@@ -362,14 +367,68 @@ def diff(
             ),
         ),
     ] = None,
+    latexmk_rc_path: Annotated[
+        str | None,
+        typer.Option(
+            "--latexmk-rc",
+            "-r",
+            help="Path to a latexmkrc file to build the marked-up document with.",
+        ),
+    ] = None,
+    latexmk_args: Annotated[
+        list[str],
+        typer.Option(
+            "--latexmk-arg",
+            help=(
+                "Extra argument to pass through to latexmk. Repeat the option "
+                "to pass more than one."
+            ),
+        ),
+    ] = [],
+    latexdiff_args: Annotated[
+        list[str],
+        typer.Option(
+            "--latexdiff-arg",
+            help=(
+                "Extra argument to pass through to latexdiff, e.g., "
+                "'--type=CFONT'. Changed figures are shown old and new by "
+                "default; pass '--graphics-markup=new-only' to show only the "
+                "new. Repeat the option to pass more "
+                "than one."
+            ),
+        ),
+    ] = [],
+    inputs: Annotated[
+        list[str],
+        typer.Option(
+            "--input",
+            help=(
+                "File or directory the document reads. Anything in it "
+                "tracked with DVC is fetched as it was at each revision. "
+                "Defaults to the inputs detected in the document. Repeat "
+                "the option to pass more than one."
+            ),
+        ),
+    ] = [],
+    revision_key: Annotated[
+        str | None,
+        typer.Option(
+            "--revision-key",
+            hidden=True,
+            help=(
+                "Set by the pipeline so a diff's stage reruns when either "
+                "revision's inputs change. Not used by the command."
+            ),
+        ),
+    ] = None,
     force: Annotated[
         bool,
         typer.Option(
             "--force",
             "-f",
             help=(
-                "Rebuild even if this comparison can't have changed and "
-                "has already been built."
+                "Rebuild even if nothing the diff depends on has changed "
+                "since it was last built."
             ),
         ),
     ] = False,
@@ -406,7 +465,191 @@ def diff(
     With the default `--to`, the newer side is the working tree, so the
     marked-up document is built with the current figures and bibliography
     and what's marked is what changed in the text.
+
+    A revision's DVC-tracked inputs, e.g., figures and tables a pipeline
+    generates, are fetched as they were at that revision, so each side of
+    the comparison shows its own.
     """
+
+    def fetch_dvc_inputs(root: str, rev: str, paths: list[str]) -> list[str]:
+        """Fetch the DVC-tracked content of ``paths`` at ``rev`` into ``root``.
+
+        Returns each fetched path with its hash, since that content changes
+        the PDF without changing the marked-up source.
+        """
+        from dvc.exceptions import NotDvcRepoError
+        from dvc.fs import DVCFileSystem
+
+        import calkit.dvc
+
+        def reason(e: BaseException) -> str:
+            # DVC wraps a remote's own error, e.g., needing to log in, in
+            # several layers that each say less
+            while e.__cause__ is not None:
+                e = e.__cause__
+            return str(e)
+
+        fetched: list[str] = []
+        try:
+            # A project using Calkit's own remote needs its scheme known
+            calkit.dvc.register_ck_scheme()
+            fs = DVCFileSystem(url=".", rev=rev)
+        except NotDvcRepoError:
+            return fetched
+        found: list[str] = []
+        for path in paths:
+            try:
+                found += list(fs.find(path.rstrip("/")))
+            except FileNotFoundError:
+                continue
+            except Exception as e:
+                # A directory whose listing is in neither the cache nor a
+                # reachable remote can't be expanded, but the rest of the
+                # comparison can still be built
+                warn(
+                    f"Can't list {path} at {rev[:7]}, so the diff will be "
+                    f"missing it: {reason(e)}"
+                )
+        for rpath in dict.fromkeys(found):
+            dvc_info = fs.info(rpath).get("dvc_info")
+            if not dvc_info:
+                continue
+            fetched.append(f"{rpath} {dvc_info.get('md5')}")
+            dest = os.path.join(root, rpath)
+            if os.path.exists(dest):
+                continue
+            os.makedirs(os.path.dirname(dest), exist_ok=True)
+            try:
+                fs.get_file(rpath, dest)
+            except Exception as e:
+                warn(
+                    f"Can't fetch {rpath} at {rev[:7]}, so the diff will be "
+                    f"missing it: {reason(e)}"
+                )
+        return fetched
+
+    def copy_uncached_outputs(
+        root: str, rev: str, paths: list[str]
+    ) -> list[str]:
+        """Copy outputs DVC records but doesn't store from the working tree.
+
+        An output with caching off, e.g., a copy another stage makes, has
+        only its hash in ``dvc.lock``, so no revision's checkout can have
+        it. The working tree's copy stands in when it's the same content.
+        Returns each copied path with its hash.
+        """
+        try:
+            lock = calkit.ryaml.load(repo.git.show(f"{rev}:dvc.lock")) or {}
+        except Exception:
+            return []
+        prefixes = [p.rstrip("/") for p in paths]
+        copied: list[str] = []
+        for stage in (lock.get("stages") or {}).values():
+            for out in stage.get("outs") or []:
+                path, md5 = out.get("path"), out.get("md5")
+                if not path or not md5 or str(md5).endswith(".dir"):
+                    continue
+                if not any(
+                    path == p or path.startswith(p + "/") for p in prefixes
+                ):
+                    continue
+                dest = os.path.join(root, path)
+                if os.path.exists(dest) or not os.path.isfile(path):
+                    continue
+                if hashlib.md5(Path(path).read_bytes()).hexdigest() != md5:
+                    continue
+                os.makedirs(os.path.dirname(dest), exist_ok=True)
+                shutil.copy2(path, dest)
+                copied.append(f"{path} {md5}")
+        return copied
+
+    def break_verbatim_params(root: str) -> None:
+        """Break verbatim inputs named by macro parameters in a checkout.
+
+        Done to the checked-out files directly rather than with latexdiff's
+        --filter-script, which hands text to the script and reads it back
+        with no encoding, mangling anything outside Latin-1, e.g., a curly
+        apostrophe.
+        """
+        sources = [tex_file] + [
+            path
+            for path in calkit.latex.detect_inputs(tex_file, wdir=root)
+            if Path(path).suffix in calkit.latex._SOURCE_EXTS
+        ]
+        for source in sources:
+            source_path = Path(root, source)
+            try:
+                text = source_path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            new_text = _VERBATIM_PARAM_RE.sub("\\1%\n", text)
+            if new_text != text:
+                source_path.write_text(new_text, encoding="utf-8")
+
+    def default_inputs(root: str) -> list[str]:
+        """What to fetch or note for a side when no inputs were given.
+
+        Detection finds a file by its own name or pointer, but a file in a
+        directory DVC tracks as a whole has only the directory's pointer,
+        which can't say what's inside, so those directories beside the
+        document are included whole.
+        """
+        doc_dir = Path(root, os.path.dirname(tex_file))
+        pointed = [
+            Path(os.path.relpath(p, root)).as_posix().removesuffix(".dvc")
+            for p in sorted(doc_dir.rglob("*.dvc"))
+            if p.is_file()
+        ]
+        return calkit.latex.detect_inputs(tex_file, wdir=root) + pointed
+
+    def point_changed_figures_at_base(base_root: str, head_root: str) -> None:
+        """Make the older side's changed figures refer to its own copies.
+
+        The marked-up document is built beside the newer side, where the
+        older side's figure names find the newer figures. Left alone, a
+        figure that changed would show as it is now on both sides, and
+        latexdiff wouldn't mark it, since its name didn't change.
+        """
+        import filecmp
+
+        tex_dir = os.path.dirname(tex_file)
+        build_dir = os.path.join(head_root, tex_dir)
+        graphic_re = re.compile(
+            r"(\\includegraphics\*?\s*(?:\[[^\]]*\])*\s*\{)([^}#\\]+)(\})"
+        )
+
+        def repoint(match: re.Match[str]) -> str:
+            name = match.group(2).strip()
+            exts = calkit.latex._GRAPHICS_EXTS
+            for candidate in [name] + [name + ext for ext in exts]:
+                rel = os.path.normpath(os.path.join(tex_dir, candidate))
+                base_path = os.path.join(base_root, rel)
+                if not os.path.isfile(base_path):
+                    continue
+                head_path = os.path.join(head_root, rel)
+                if os.path.isfile(head_path) and filecmp.cmp(
+                    base_path, head_path, shallow=False
+                ):
+                    return match.group(0)
+                new_name = Path(os.path.relpath(base_path, build_dir))
+                return match.group(1) + new_name.as_posix() + match.group(3)
+            return match.group(0)
+
+        sources = [tex_file] + [
+            path
+            for path in calkit.latex.detect_inputs(tex_file, wdir=base_root)
+            if Path(path).suffix in calkit.latex._SOURCE_EXTS
+        ]
+        for source in sources:
+            source_path = Path(base_root, source)
+            try:
+                text = source_path.read_text(encoding="utf-8")
+            except (OSError, UnicodeDecodeError):
+                continue
+            new_text = graphic_re.sub(repoint, text)
+            if new_text != text:
+                source_path.write_text(new_text, encoding="utf-8")
+
     repo = calkit.git.get_repo()
     if repo.bare:
         raise_error("This is not a working Git repo")
@@ -425,16 +668,8 @@ def diff(
             to_ref=to_ref,
             output_dir=output_dir,
         )
-    # A comparison between two revisions that can't move is the same
-    # comparison forever, and LaTeX writes a timestamp into every PDF, so
-    # rebuilding one would change the file without changing what it says
-    fixed = _is_immutable_ref(repo, from_ref) and _is_immutable_ref(
-        repo, to_ref
-    )
-    if fixed and os.path.isfile(output) and not force:
-        typer.echo(f"{output} is already built; use --force to rebuild it")
-        return
     checkouts: dict[str, str] = {}
+    shas: dict[str, str] = {}
     try:
         for name, ref in [("base", from_ref), ("head", to_ref)]:
             if ref is None:
@@ -442,6 +677,7 @@ def diff(
             sha = calkit.git.resolve_ref(repo, ref)
             if sha is None:
                 raise_error(f"Git ref '{ref}' was not found")
+            shas[name] = sha
             # A worktree, not a temp directory: a document is rarely one
             # file, and \input needs the rest of them as they were then
             path = os.path.join(DIFF_TMP_DIR, name)
@@ -466,12 +702,43 @@ def diff(
             if not os.path.isfile(side):
                 raise_error(f"{tex_file} does not exist at {ref}")
             sides[name] = side
+        # The working tree already has its DVC-tracked files, if pulled
+        head_root = checkouts.get("head", ".")
+        context: list[str] = []
+        for name, root in checkouts.items():
+            paths = inputs or default_inputs(root)
+            context += fetch_dvc_inputs(root, rev=shas[name], paths=paths)
+            context += copy_uncached_outputs(root, rev=shas[name], paths=paths)
+        if "head" not in checkouts:
+            # The working tree has no revision to name its files by, so
+            # note what's there instead
+            for path in inputs or default_inputs("."):
+                if os.path.isfile(path):
+                    files = [Path(path)]
+                else:
+                    files = sorted(
+                        p for p in Path(path).rglob("*") if p.is_file()
+                    )
+                for file_path in files:
+                    stat = file_path.stat()
+                    context.append(
+                        f"{file_path.as_posix()} {stat.st_size} "
+                        f"{stat.st_mtime_ns}"
+                    )
+        for root in checkouts.values():
+            break_verbatim_params(root)
+        point_changed_figures_at_base(checkouts["base"], head_root)
         _build_diff(
             base_tex=sides["base"],
             head_tex=sides["head"],
             tex_file=tex_file,
+            head_root=head_root,
             output=output,
             environment=environment,
+            latexmk_rc_path=latexmk_rc_path,
+            latexmk_args=latexmk_args,
+            latexdiff_args=latexdiff_args,
+            context=context,
             no_check=no_check,
             keep_tex=keep_tex,
             force=force,
@@ -482,19 +749,23 @@ def diff(
             _remove_worktree(path)
 
 
-def _marked_up_digest(marked_up: bytes) -> str:
+def _marked_up_digest(marked_up: bytes, context: list[str] = []) -> str:
     """Hash a marked-up document by what actually determines the PDF.
 
     latexdiff writes the two inputs' paths and modification times into a
     header comment, and the older side is a fresh checkout every time, so
     hashing the file as-is would say "changed" on every run when nothing
     had. Those lines are comments; the PDF doesn't depend on them.
+
+    ``context`` is anything else the PDF depends on, e.g., the hashes of
+    DVC-tracked figures and the options it's built with.
     """
     kept = [
         line
         for line in marked_up.splitlines(keepends=True)
         if not line.startswith((b"%DIF DEL ", b"%DIF ADD "))
     ]
+    kept += [f"{item}\n".encode() for item in context]
     return hashlib.sha256(b"".join(kept)).hexdigest()
 
 
@@ -520,35 +791,38 @@ def _build_diff(
     base_tex: str,
     head_tex: str,
     tex_file: str,
+    head_root: str,
     output: str,
     environment: str | None,
+    latexmk_rc_path: str | None,
+    latexmk_args: list[str],
+    latexdiff_args: list[str],
+    context: list[str],
     no_check: bool,
     keep_tex: bool,
     force: bool,
     verbose: bool,
 ) -> None:
     """Mark up one document against another and build the result."""
-    # Built beside the working copy of the document, so \graphicspath,
-    # \bibliography, and relative \includegraphics resolve the way they do
-    # for the real thing. A checked-out revision would be the tidier place
-    # for it, but a DVC-tracked figure isn't in Git: a checkout has the
-    # pointer file and not the image, and the marked-up document would
-    # come out with its figures missing.
+    # Built beside the newer side, so \graphicspath, \bibliography, and
+    # relative \includegraphics resolve the way they do for the real thing,
+    # against that revision's own files
     tex_dir = os.path.dirname(tex_file) or "."
+    build_dir = os.path.normpath(os.path.join(head_root, tex_dir))
     stem = Path(tex_file).stem
-    diff_tex = os.path.join(tex_dir, f"{stem}-diff.tex")
+    diff_tex = os.path.join(build_dir, f"{stem}-diff.tex")
+    # Where --keep-tex leaves it: beside the document, since a checkout is
+    # removed afterwards
+    kept_tex = os.path.normpath(os.path.join(tex_dir, f"{stem}-diff.tex"))
+    aux_dir = os.path.join(build_dir, calkit.latex.DIFF_AUX_DIRNAME)
     try:
         # --flatten pulls \input and \include files into one document on
         # each side, so a multi-file paper compares as a whole
         latexdiff_cmd = ["latexdiff", "--flatten", "--encoding=utf8"]
-        # latexdiff dies trying to open a verbatim input that's a macro
-        # parameter, e.g., \verbatiminput{#1.wcsum} in a \newcommand, so a
-        # filter breaks the line after the command, which TeX reads the same
-        # but latexdiff's pattern doesn't match
-        verbatim_param = re.compile(
-            r"\\(?:verbatiminput\*?|lstinputlisting)"
-            r"\s*(?:\[[^\]\n]*\])?\s*\{[^}\n]*#[0-9]"
-        )
+        # A checkout's verbatim inputs named by macro parameters are already
+        # broken, so this only finds the working tree's, which can't be
+        # edited. A filter breaks those instead, though latexdiff's
+        # --filter-script mangles anything outside Latin-1.
         sources = [base_tex, head_tex] + [
             path
             for side in (base_tex, head_tex)
@@ -557,7 +831,7 @@ def _build_diff(
         ]
         if any(
             os.path.isfile(path)
-            and verbatim_param.search(
+            and _VERBATIM_PARAM_RE.search(
                 Path(path).read_text(encoding="utf-8", errors="replace")
             )
             for path in sources
@@ -576,6 +850,14 @@ def _build_diff(
             latexdiff_cmd.append(
                 f"--filter-script=perl {filter_path.as_posix()}"
             )
+        # Each side has its own revision's figures, so a changed one is
+        # shown both ways rather than only as it is now, unless the user
+        # chose otherwise
+        if not any(a.startswith("--graphics-markup") for a in latexdiff_args):
+            latexdiff_cmd.append("--graphics-markup=both")
+        # User pass-through args come last so they can override Calkit's
+        # defaults
+        latexdiff_cmd += latexdiff_args
         cmd = _tex_cmd(
             latexdiff_cmd + [base_tex, head_tex],
             environment=environment,
@@ -591,14 +873,32 @@ def _build_diff(
                 "latexdiff was not found; it ships with TeX Live, so a "
                 "minimal install may not have it"
             )
-        except subprocess.CalledProcessError:
-            raise_error("latexdiff failed")
-        # The PDF is a function of this marked-up source, so if it hasn't
-        # changed there's nothing to build. Worth checking because the
-        # common case produces nothing at all: on the default branch the
-        # merge base is usually HEAD, so the comparison is empty, and
-        # latexmk is the expensive half of this.
-        digest = _marked_up_digest(marked_up)
+        except subprocess.CalledProcessError as e:
+            raise_error(f"latexdiff failed with exit status {e.returncode}")
+        # The newer side's copy, which is what the document was built with
+        # at that revision
+        rc_path = None
+        rc_hash = None
+        if latexmk_rc_path is not None:
+            rc_path = os.path.join(head_root, latexmk_rc_path)
+            if not os.path.isfile(rc_path):
+                rc_path = latexmk_rc_path
+            rc_path = Path(os.path.normpath(rc_path)).as_posix()
+            if os.path.isfile(rc_path):
+                rc_hash = hashlib.sha256(
+                    Path(rc_path).read_bytes()
+                ).hexdigest()
+        # The PDF is a function of this marked-up source and how it's built,
+        # so if neither has changed there's nothing to build. Worth checking
+        # because the common case produces nothing at all: on the default
+        # branch the merge base is usually HEAD, so the comparison is empty,
+        # and latexmk is the expensive half of this.
+        digest = _marked_up_digest(
+            marked_up,
+            context=context
+            + [f"latexmkrc {rc_path} {rc_hash}"]
+            + latexmk_args,
+        )
         state_path = calkit.latex.diff_state_path(output)
         if (
             not force
@@ -609,11 +909,14 @@ def _build_diff(
             return
         with open(diff_tex, "wb") as f:
             f.write(marked_up)
-        aux_dir = DIFF_AUX_DIR
         os.makedirs(aux_dir, exist_ok=True)
-        rel_aux = Path(os.path.relpath(aux_dir, tex_dir)).as_posix()
-        latexmk_cmd = [
-            "latexmk",
+        rel_aux = calkit.latex.DIFF_AUX_DIRNAME
+        latexmk_cmd = ["latexmk"]
+        # First, since latexmk reads an rc file where it appears, so the
+        # directories below override any the rc file sets
+        if rc_path is not None:
+            latexmk_cmd += ["-r", rc_path]
+        latexmk_cmd += [
             "-pdf",
             "-cd",
             "-interaction=nonstopmode",
@@ -622,6 +925,9 @@ def _build_diff(
         ]
         if not verbose:
             latexmk_cmd.append("-silent")
+        # User pass-through args come last so they can override Calkit's
+        # defaults
+        latexmk_cmd += latexmk_args
         latexmk_cmd.append(diff_tex)
         cmd = _tex_cmd(
             latexmk_cmd,
@@ -633,23 +939,47 @@ def _build_diff(
         typer.echo("Building the marked-up document")
         try:
             subprocess.check_call(cmd)
-        except subprocess.CalledProcessError:
+        except subprocess.CalledProcessError as e:
+            # -silent hides why, so show the errors LaTeX logged
+            log_path = Path(aux_dir, f"{stem}-diff.log")
+            try:
+                log_lines = log_path.read_text(
+                    encoding="utf-8", errors="replace"
+                ).splitlines()
+            except OSError:
+                log_lines = []
+            shown: list[str] = []
+            for i, line in enumerate(log_lines):
+                if line.startswith("!"):
+                    shown += log_lines[i : i + 3]
+            excerpt = shown[:60] or log_lines[-20:]
+            if excerpt:
+                typer.echo(f"From {log_path.as_posix()}:", err=True)
+                typer.echo("\n".join(excerpt), err=True)
             raise_error(
-                "latexmk failed on the marked-up document; rerun with "
-                "--keep-tex to inspect it"
+                "latexmk failed on the marked-up document with exit status "
+                f"{e.returncode}; rerun with --keep-tex to inspect it"
             )
         built = os.path.join(aux_dir, f"{stem}-diff.pdf")
         if not os.path.isfile(built):
             raise_error("latexmk did not produce a PDF")
         os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
         shutil.move(built, output)
+        # A checkout is removed afterwards, but the working tree's document
+        # directory is the user's, so nothing is left behind in it
+        if os.path.abspath(head_root) == os.path.abspath("."):
+            shutil.rmtree(aux_dir, ignore_errors=True)
         os.makedirs(os.path.dirname(state_path), exist_ok=True)
         with open(state_path, "w") as f:
             f.write(digest)
         typer.echo(f"Wrote {output}")
     finally:
-        if not keep_tex and os.path.isfile(diff_tex):
-            os.remove(diff_tex)
+        if os.path.isfile(diff_tex):
+            in_place = os.path.abspath(diff_tex) == os.path.abspath(kept_tex)
+            if keep_tex and not in_place:
+                shutil.copy(diff_tex, kept_tex)
+            if not keep_tex or not in_place:
+                os.remove(diff_tex)
 
 
 @latex_app.command(name="to-docx")

calkit/cli/main/core.py

@@ -2777,9 +2777,13 @@ def run(
         dvc_data_status_before.pop("git", None)  # Remove git status
     if targets is None:
         targets = []
-    args, isolated_sp_targets = calkit.pipeline.translate_run_targets(
-        deepcopy(targets), ck_info=ck_info
-    )
+    try:
+        args, isolated_sp_targets = calkit.pipeline.translate_run_targets(
+            deepcopy(targets), ck_info=ck_info
+        )
+    except ValueError as e:
+        os.environ.pop("CALKIT_PIPELINE_RUNNING", None)
+        raise_error(str(e))
     # Extract any boolean args
     for name in [
         "quiet",
@@ -3478,8 +3482,11 @@ def run_in_env(
             typer.echo(f"Running command: {docker_cmd}")
         try:
             subprocess.check_call(docker_cmd, cwd=wdir)
-        except subprocess.CalledProcessError:
-            raise_error("Failed to run in Docker environment")
+        except subprocess.CalledProcessError as e:
+            raise_error(
+                "Failed to run in Docker environment: command exited with "
+                f"status {e.returncode}"
+            )
     elif env["kind"] == "conda":
         with open(env["path"]) as f:
             conda_env = calkit.ryaml.load(f)

calkit/environments.py

@@ -1140,10 +1140,20 @@ def check_all_in_pipeline(
             for t in targets
             if t in md_stages
         ]
+        # A latex stage's diffs run in its environment, whether they're
+        # named one at a time or all together
+        import calkit.latex
+
         stages = {
             k: v
             for k, v in stages.items()
-            if k in targets or any(k.startswith(p) for p in prefixes)
+            if k in targets
+            or any(k.startswith(p) for p in prefixes)
+            or k + calkit.latex.DIFFS_TARGET_SUFFIX in targets
+            or any(
+                name in targets
+                for name in calkit.latex.get_diff_stage_names(k, v)
+            )
         }
     envs_in_pipeline = [stage.get("environment") for stage in stages.values()]
     envs_in_pipeline = [

calkit/git.py

@@ -625,24 +625,3 @@ def resolve_ref(repo: git.Repo, ref: str) -> str | None:
         warnings.warn(f"Failed to fetch history: {e}")
         return None
     return parse()
-
-
-def last_change(repo: git.Repo, ref: str, paths: list[str]) -> str | None:
-    """The last commit at or before ``ref`` that touched any of ``paths``.
-
-    Used to name a revision by its content rather than its position. A
-    comparison against ``HEAD`` means the document as it stands, and the
-    document doesn't change when something else in the project is
-    committed, so resolving to the commit that last changed it keeps the
-    answer stable and keeps a pipeline from invalidating itself.
-
-    Returns None if nothing matches, including when the paths were never
-    tracked.
-    """
-    if not paths:
-        return None
-    try:
-        out = str(repo.git.rev_list("-1", ref, "--", *paths)).strip()
-    except Exception:
-        return None
-    return out or None