calkit-python 0.47.7__py3-none-any.whl → 0.47.9__py3-none-any.whl

calkit/agent_skills/conventions/SKILL.md

@@ -25,6 +25,8 @@ is `calkit.yaml`, the project's metadata database.
 - `environments`—computational environments (Python venvs, Conda, Docker,
   R, Julia, MATLAB, etc.)
 - `pipeline.stages`—the reproducible pipeline
+- `questions`—research questions, hypotheses, and answers backed by
+  evidence the pipeline produces
 - `notebooks`—registered Jupyter notebooks
 - `datasets`, `figures`, `publications`—versioned project outputs
 - `procedures`, `calculations`, `references`—supporting metadata
@@ -209,6 +211,9 @@ DVC handles:
 | `calkit add <file>`             | Add a file to version control                        |
 | `calkit check env --name <env>` | Verify an environment matches its spec               |
 | `calkit new`                    | Create new project objects (notebook, dataset, etc.) |
+| `calkit new question "<text>"`  | Record a research question                           |
+| `calkit list questions`         | Show questions with answers rendered from evidence   |
+| `calkit check questions`        | Check answers against current evidence               |
 
 ## `calkit xr`: The fastest path to a reproducible stage
 
@@ -233,6 +238,27 @@ calkit xr scripts/run.py --environment main
 calkit xr scripts/run.py --dry-run    # see what would happen without running
 ```
 
+## Questions and answers
+
+Research in a Calkit project is organized around the `questions` list in
+`calkit.yaml`. Follow this workflow:
+
+1. Before starting an analysis, make sure the question it answers is
+   recorded, e.g., with `calkit new question`. If the user hasn't stated
+   one, ask them for it rather than inventing it. Add a `hypothesis` if
+   they have one.
+2. Produce evidence with pipeline stages, never by hand, so every figure,
+   table, and number traces back to data and code.
+3. Write the `answer` citing that evidence. Read numbers out of results
+   files and put them in the prose with `{name}` placeholders instead of
+   typing them in, either one per `kind: value` entry, or several from one
+   file with a `kind: result` entry's `values` mapping of names to keys.
+4. After a pipeline run changes results, run `calkit check questions`,
+   then use the `check-questions` skill to judge whether each answer's
+   wording still follows from its evidence.
+
+See the Calkit docs on questions for the full evidence schema.
+
 ## Version control conventions
 
 - Source code and small outputs: tracked with Git

calkit/cli/config.py

@@ -12,7 +12,7 @@ import typer
 from typing_extensions import Annotated
 
 import calkit
-from calkit.cli.core import raise_error
+from calkit.cli.core import raise_error, warn
 
 config_app = typer.Typer(no_args_is_help=True)
 
@@ -189,9 +189,17 @@ def setup_remote(
 ):
     """Set up the Calkit hub as the default DVC remote and store a token
     in the local config.
+
+    Deprecated: this configures the project, not Calkit itself, which is
+    what the rest of this app is for.
     """
     from git.exc import InvalidGitRepositoryError
 
+    warn(
+        "'calkit config remote' is deprecated; use 'calkit update hub', "
+        "which also creates the project on the hub if it isn't there"
+    )
+
     from calkit.dvc import configure_remote, set_remote_auth
 
     try:

calkit/cli/latex.py

@@ -137,6 +137,20 @@ def from_json(
             json2latex.dump(cmd_name, formatted, f)
 
 
+def _tex_env_vars(source_date_epoch: str | None) -> dict[str, str]:
+    r"""The environmental variables a TeX command needs, beyond the ambient.
+
+    ``FORCE_SOURCE_DATE`` is what makes pdfTeX apply the date to
+    ``\pdfcreationdate`` and friends, not only to the trailer ID.
+    """
+    if source_date_epoch is None:
+        return {}
+    return {
+        "SOURCE_DATE_EPOCH": source_date_epoch,
+        "FORCE_SOURCE_DATE": "1",
+    }
+
+
 @latex_app.command(name="from-questions")
 def from_questions(
     output_fpaths: Annotated[
@@ -180,6 +194,7 @@ def _tex_cmd(
     no_check: bool,
     verbose: bool,
     dep: str,
+    env_vars: dict[str, str] | None = None,
 ) -> list[str]:
     """Wrap a TeX command so it runs wherever the project's TeX lives.
 
@@ -189,31 +204,162 @@ def _tex_cmd(
     inside the project -- which is why the diff builds its copy of the
     base revision there rather than in a temp directory.
     """
+    env_vars = env_vars or {}
     if environment is not None:
         cmd = (
             ["calkit", "xenv", "--name", environment]
             + (["--no-check"] if no_check else [])
+            # Named rather than inherited: the environment may run in a
+            # container, which inherits nothing from here
+            + [f"--env-var={k}={v}" for k, v in env_vars.items()]
             + ["--"]
             + tex_cmd
         )
     elif calkit.check_dep_exists(dep):
         cmd = tex_cmd
     else:
+        # Pulled deliberately, since docker run's implicit pull of an
+        # image that isn't there can stall rather than report it
+        try:
+            calkit.docker.ensure_image_available(
+                calkit.latex.DEFAULT_LATEX_IMAGE
+            )
+        except ValueError as e:
+            raise_error(str(e))
+        # Packages fetched at run time go to the project's cache, which
+        # the working directory mount already covers, rather than over
+        # the image's own tree, which would hide the distribution entirely
+        os.makedirs(calkit.latex.get_texmf_cache_dir(), exist_ok=True)
         cmd = [
             "docker",
             "run",
             "--rm",
             "-v",
             f"{os.getcwd()}:/work",
+            "-e",
+            f"TEXMFHOME={calkit.latex.CONTAINER_TEXMF_DIR}",
             "-w",
             "/work",
-            "texlive/texlive:latest-full",
-        ] + tex_cmd
+        ]
+        # As the user, so a PDF doesn't come back owned by root
+        try:
+            cmd += ["--user", f"{os.getuid()}:{os.getgid()}"]
+        except AttributeError:
+            # Windows has no UID to map
+            pass
+        # The container gets its own environment, so anything the command
+        # needs has to be handed to it rather than inherited
+        for key, value in env_vars.items():
+            cmd += ["-e", f"{key}={value}"]
+        cmd += [calkit.latex.DEFAULT_LATEX_IMAGE] + tex_cmd
     if verbose:
         typer.echo(f"Running command: {cmd}")
     return cmd
 
 
+def _run_latexmk(
+    cmd: list[str],
+    env: dict[str, str] | None,
+    log_path: str,
+    fdb_path: str,
+    environment: str | None,
+    verbose: bool,
+) -> int:
+    """Run latexmk, fetching the TeX packages it's missing and retrying.
+
+    Only where what's fetched is kept with the project, i.e., Calkit's
+    LaTeX image, run directly or as a Docker environment built on it. A
+    system TeX is the user's to manage, and anything installed in another
+    container is gone when it exits. Returns latexmk's exit status.
+    """
+    import shlex
+
+    def in_tex(tex_cmd: list[str]) -> list[str]:
+        # Where the build runs, so what's installed is what it sees
+        return _tex_cmd(
+            tex_cmd,
+            environment=environment,
+            no_check=True,
+            verbose=verbose,
+            dep="latexmk",
+        )
+
+    def can_fetch() -> bool:
+        if environment is None:
+            return not calkit.check_dep_exists("latexmk")
+        envs = calkit.load_calkit_info().get("environments", {})
+        if envs.get(environment, {}).get("kind") != "docker":
+            return False
+        # The image switches to the project's cache when it's there
+        os.makedirs(calkit.latex.get_texmf_cache_dir(), exist_ok=True)
+        out = subprocess.run(
+            in_tex(["printenv", "TEXMFHOME"]), capture_output=True, text=True
+        ).stdout.strip()
+        return out.endswith("/.calkit/local/texmf")
+
+    fetched: set[str] = set()
+    fetchable = None
+    while True:
+        try:
+            subprocess.check_call(cmd, env=env)
+            return 0
+        except subprocess.CalledProcessError as e:
+            status = e.returncode
+        try:
+            with open(log_path, encoding="utf-8", errors="replace") as f:
+                log = f.read()
+        except OSError:
+            return status
+        # A file still missing after fetching it is one fetching can't fix
+        missing = [
+            f
+            for f in calkit.latex.find_missing_tex_files(log)
+            if f not in fetched
+        ]
+        if not missing:
+            return status
+        if fetchable is None:
+            fetchable = can_fetch()
+        if not fetchable:
+            return status
+        packages = []
+        for name in missing:
+            out = subprocess.run(
+                in_tex(["tlmgr", "search", "--global", "--file", f"/{name}"]),
+                capture_output=True,
+                text=True,
+            ).stdout
+            # Package names end with a colon; the paths under them are
+            # indented, and the first one ending in the file is its owner
+            owner = None
+            for line in out.splitlines():
+                if line.endswith(":") and not line.startswith((" ", "\t")):
+                    owner = line[:-1]
+                elif owner and line.strip().endswith(f"/{name}"):
+                    packages.append(owner)
+                    break
+        packages = list(dict.fromkeys(packages))
+        if not packages:
+            return status
+        typer.echo(
+            f"Fetching TeX packages for {', '.join(missing)}: "
+            f"{', '.join(packages)}"
+        )
+        install = in_tex(["tlmgr", "--usermode", "install", *packages])
+        if verbose:
+            typer.echo(f"Running command: {shlex.join(install)}")
+        # A font's install fails at its last step, updating the font map,
+        # which user mode can't do in this image, with the files already in
+        # place and usable. Whether it worked is the retry's to say.
+        if subprocess.run(install, capture_output=not verbose).returncode:
+            if verbose:
+                warn(f"tlmgr reported an error installing {packages}")
+        fetched.update(missing)
+        # Otherwise latexmk remembers the failure and won't try again
+        if os.path.isfile(fdb_path):
+            os.remove(fdb_path)
+
+
 @latex_app.command(name="build")
 def build(
     tex_file: Annotated[str, typer.Argument(help="The .tex file to compile.")],
@@ -300,6 +446,21 @@ def build(
     system environment if available. If not available, a TeX Live Docker
     container will be used.
     """
+    # latexmk records a failed run in its file database and then refuses
+    # to try again, reporting "Nothing to do" and exiting non-zero with no
+    # PDF. Running it again is the first thing anyone does after a
+    # failure, so the record is cleared when there is no PDF to show for
+    # it, which makes a retry a real retry.
+    tex_dir = os.path.dirname(tex_file) or "."
+    stem = Path(tex_file).stem
+    pdf_dir = output_dir if output_dir is not None else tex_dir
+    if not os.path.isfile(os.path.join(pdf_dir, stem + ".pdf")):
+        fdb_dir = aux_dir if aux_dir is not None else tex_dir
+        fdb_fpath = os.path.join(fdb_dir, stem + ".fdb_latexmk")
+        if os.path.isfile(fdb_fpath):
+            if verbose:
+                typer.echo(f"Removing {fdb_fpath} so latexmk will retry")
+            os.remove(fdb_fpath)
     # Now formulate the command
     latexmk_cmd = ["latexmk", "-pdf", "-cd"]
     if latexmk_rc_path is not None:
@@ -313,7 +474,6 @@ def build(
     # latexmk runs with -cd, so its -outdir/-auxdir are relative to the .tex
     # file's directory; convert the (current-directory-relative) Calkit paths
     # into that frame.
-    tex_dir = os.path.dirname(tex_file) or "."
     if output_dir is not None:
         rel = Path(os.path.relpath(output_dir, tex_dir)).as_posix()
         latexmk_cmd.append(f"-outdir={rel}")
@@ -324,16 +484,24 @@ def build(
     # User pass-through args come last so they can override Calkit's defaults.
     latexmk_cmd += latexmk_args
     latexmk_cmd.append(tex_file)
+    tex_env_vars = _tex_env_vars(calkit.latex.get_source_date_epoch(tex_file))
     cmd = _tex_cmd(
         latexmk_cmd,
         environment=environment,
         no_check=no_check,
         verbose=verbose,
         dep="latexmk",
+        env_vars=tex_env_vars,
     )
-    try:
-        subprocess.check_call(cmd)
-    except subprocess.CalledProcessError:
+    log_dir = aux_dir or output_dir or tex_dir
+    if _run_latexmk(
+        cmd,
+        env=(os.environ | tex_env_vars) if tex_env_vars else None,
+        log_path=os.path.join(log_dir, stem + ".log"),
+        fdb_path=os.path.join(log_dir, stem + ".fdb_latexmk"),
+        environment=environment,
+        verbose=verbose,
+    ):
         raise_error("latexmk failed")
 
 
@@ -345,6 +513,9 @@ _VERBATIM_PARAM_RE = re.compile(
     r"(\\(?:verbatiminput\*?|lstinputlisting))"
     r"(?=\s*(?:\[[^\]\n]*\])?\s*\{[^}\n]*#[0-9])"
 )
+_INPUT_WRAPPER_RE = re.compile(
+    r"\\([A-Za-z@]+)\*?\s*(?:\[[^\]]*\]\s*)*\{\s*\\(?:input|include)\s*\{"
+)
 get_diff_path = calkit.latex.get_diff_path
 _default_base_ref = calkit.latex.default_base_ref
 
@@ -409,7 +580,9 @@ def diff(
         typer.Option(
             "--latexmk-rc",
             "-r",
-            help="Path to a latexmkrc file to build the marked-up document with.",
+            help=(
+                "Path to a latexmkrc file to build the marked-up document with."
+            ),
         ),
     ] = None,
     latexmk_args: Annotated[
@@ -473,7 +646,11 @@ def diff(
         bool,
         typer.Option(
             "--keep-tex",
-            help="Keep the generated diff .tex file for inspection.",
+            help=(
+                "Keep the old, new, and diff .tex files beside the diff "
+                "PDF for inspection, e.g., "
+                ".calkit/latex-diffs/v1/paper/main-old.tex."
+            ),
         ),
     ] = False,
     no_check: Annotated[
@@ -508,6 +685,53 @@ def diff(
     the comparison shows its own.
     """
 
+    def stage_path(stage: dict, path: str) -> str:
+        """A stage's path in the project's frame rather than its wdir's."""
+        return Path(
+            os.path.normpath(os.path.join(stage.get("wdir") or "", path))
+        ).as_posix()
+
+    def find_latex_stage() -> tuple[str | None, dict | None]:
+        """The pipeline stage that builds the document, if any."""
+        ck_info = calkit.load_calkit_info()
+        stages = (ck_info.get("pipeline") or {}).get("stages") or {}
+        target = Path(os.path.normpath(tex_file)).as_posix()
+        for name, stage in stages.items():
+            if (
+                isinstance(stage, dict)
+                and stage.get("kind") == "latex"
+                and stage_path(stage, stage.get("target_path") or "") == target
+            ):
+                return name, stage
+        return None, None
+
+    def stage_inputs(name: str, stage: dict) -> list[str]:
+        """What a stage's diffs fetch at each revision.
+
+        Its dependencies in the compiled pipeline, which include other
+        stages' outputs it reads, found there since calkit.yaml only names
+        the stages they come from.
+        """
+        from calkit.models.pipeline import LatexStage
+
+        try:
+            dvc_stage = calkit.ryaml.load(Path("dvc.yaml").read_text())[
+                "stages"
+            ][name]
+            deps = [
+                dep if isinstance(dep, str) else next(iter(dep))
+                for dep in dvc_stage.get("deps") or []
+            ]
+        except Exception:
+            deps = LatexStage.model_validate(stage | {"name": name}).dvc_deps
+        skip = {tex_file, latexmk_rc_path}
+        return [
+            path
+            for dep in deps
+            if (path := stage_path(stage, dep)) not in skip
+            and not path.startswith(".calkit/")
+        ]
+
     def fetch_dvc_inputs(root: str, rev: str, paths: list[str]) -> list[str]:
         """Fetch the DVC-tracked content of ``paths`` at ``rev`` into ``root``.
 
@@ -629,7 +853,9 @@ def diff(
         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.
+        document are included whole. Neither finds another stage's output
+        DVC doesn't cache, so the pipeline's inputs for the document are
+        added too.
         """
         doc_dir = Path(root, os.path.dirname(tex_file))
         pointed = [
@@ -637,7 +863,8 @@ def diff(
             for p in sorted(doc_dir.rglob("*.dvc"))
             if p.is_file()
         ]
-        return calkit.latex.detect_inputs(tex_file, wdir=root) + pointed
+        detected = calkit.latex.detect_inputs(tex_file, wdir=root)
+        return detected + pointed + pipeline_inputs
 
     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.
@@ -698,6 +925,20 @@ def diff(
         from_ref = _default_base_ref(repo)
     if to_ref is None and not os.path.isfile(tex_file):
         raise_error(f"{tex_file} does not exist")
+    # A document the pipeline builds is diffed the way it's built, with its
+    # stage's environment, settings, and inputs, unless told otherwise
+    stage_name, stage = find_latex_stage()
+    pipeline_inputs: list[str] = []
+    if stage is not None:
+        if environment is None:
+            environment = stage.get("environment")
+        if latexmk_rc_path is None and stage.get("latexmkrc_path"):
+            latexmk_rc_path = stage_path(stage, stage["latexmkrc_path"])
+        latexmk_args = latexmk_args or list(stage.get("latexmk_args") or [])
+        latexdiff_args = latexdiff_args or list(
+            stage.get("latexdiff_args") or []
+        )
+        pipeline_inputs = stage_inputs(str(stage_name), stage)
     if output is None:
         output = get_diff_path(
             tex_file,
@@ -766,9 +1007,9 @@ def diff(
             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,
+            base_tex_fpath=sides["base"],
+            head_tex_fpath=sides["head"],
+            tex_file_fpath=tex_file,
             head_root=head_root,
             output=output,
             environment=environment,
@@ -825,9 +1066,9 @@ def _remove_worktree(path: str) -> None:
 
 
 def _build_diff(
-    base_tex: str,
-    head_tex: str,
-    tex_file: str,
+    base_tex_fpath: str,
+    head_tex_fpath: str,
+    tex_file_fpath: str,
     head_root: str,
     output: str,
     environment: str | None,
@@ -840,39 +1081,63 @@ def _build_diff(
     force: bool,
     verbose: bool,
 ) -> None:
-    """Mark up one document against another and build the result."""
+    """Mark up one document against another and build the result.
+
+    base_tex_fpath is the older revision's document, head_tex_fpath the
+    newer revision's, and tex_file_fpath the document as named on the
+    command line. head_root is where the newer side lives: a checkout,
+    or the working tree, beside which the marked-up document is built
+    so its relative inputs resolve.
+    """
     # 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 "."
+    tex_dir = os.path.dirname(tex_file_fpath) or "."
     build_dir = os.path.normpath(os.path.join(head_root, tex_dir))
-    stem = Path(tex_file).stem
-    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"))
+    stem = Path(tex_file_fpath).stem
+    diff_tex_fpath = os.path.join(build_dir, f"{stem}-diff.tex")
+    # Where --keep-tex leaves its copies: beside the diff PDF, since a
+    # checkout is removed afterwards. The old and new files are what
+    # latexdiff saw, after verbatim fixes and figure repointing, so a
+    # --flatten or macro expansion failure can be inspected.
+    kept_stem = os.path.splitext(output)[0]
+    kept_diff_fpath = f"{kept_stem}-diff.tex"
+    kept_old_fpath = f"{kept_stem}-old.tex"
+    kept_new_fpath = f"{kept_stem}-new.tex"
+    marked_up: bytes | None = None
     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"]
-        # 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] + [
+        sources = [base_tex_fpath, head_tex_fpath] + [
             path
-            for side in (base_tex, head_tex)
+            for side in (base_tex_fpath, head_tex_fpath)
             for path in calkit.latex.detect_inputs(side)
             if Path(path).suffix in calkit.latex._SOURCE_EXTS
         ]
-        if any(
-            os.path.isfile(path)
-            and _VERBATIM_PARAM_RE.search(
-                Path(path).read_text(encoding="utf-8", errors="replace")
-            )
+        texts = [
+            Path(path).read_text(encoding="utf-8", errors="replace")
             for path in sources
-        ):
+            if os.path.isfile(path)
+        ]
+        # A macro wrapping an \input or \include, e.g., one making an
+        # appendix single column, gets the whole flattened file as its
+        # argument, which latexdiff would otherwise mark up as one token
+        wrappers = sorted(
+            {
+                name
+                for text in texts
+                for name in _INPUT_WRAPPER_RE.findall(text)
+            }
+        )
+        if wrappers:
+            latexdiff_cmd.append("--append-textcmd=" + ";".join(wrappers))
+        # 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.
+        if any(_VERBATIM_PARAM_RE.search(text) for text in texts):
             filter_path = Path(DIFF_TMP_DIR, "verbatim-param-filter.pl")
             os.makedirs(filter_path.parent, exist_ok=True)
             # latexdiff appends a newline to what it sends, so drop it
@@ -896,7 +1161,7 @@ def _build_diff(
         # defaults
         latexdiff_cmd += latexdiff_args
         cmd = _tex_cmd(
-            latexdiff_cmd + [base_tex, head_tex],
+            latexdiff_cmd + [base_tex_fpath, head_tex_fpath],
             environment=environment,
             no_check=no_check,
             verbose=verbose,
@@ -904,7 +1169,9 @@ def _build_diff(
         )
         typer.echo("Marking up the document with latexdiff")
         try:
-            marked_up = subprocess.check_output(cmd)
+            # No stdin, so an environment's container isn't given a TTY,
+            # which would merge latexdiff's warnings into the document
+            marked_up = subprocess.check_output(cmd, stdin=subprocess.DEVNULL)
         except FileNotFoundError:
             raise_error(
                 "latexdiff was not found; it ships with TeX Live, so a "
@@ -944,8 +1211,7 @@ def _build_diff(
         ):
             typer.echo(f"{output} is up to date")
             return
-        with open(diff_tex, "wb") as f:
-            f.write(marked_up)
+        Path(diff_tex_fpath).write_bytes(marked_up)
         os.makedirs(aux_dir, exist_ok=True)
         rel_aux = calkit.latex.DIFF_AUX_DIRNAME
         latexmk_cmd = ["latexmk"]
@@ -965,17 +1231,30 @@ def _build_diff(
         # User pass-through args come last so they can override Calkit's
         # defaults
         latexmk_cmd += latexmk_args
-        latexmk_cmd.append(diff_tex)
+        latexmk_cmd.append(diff_tex_fpath)
+        tex_env_vars = _tex_env_vars(
+            calkit.latex.get_source_date_epoch(tex_file_fpath)
+        )
         cmd = _tex_cmd(
             latexmk_cmd,
             environment=environment,
             no_check=no_check,
             verbose=verbose,
             dep="latexmk",
+            env_vars=tex_env_vars,
         )
         typer.echo("Building the marked-up document")
         try:
-            subprocess.check_call(cmd)
+            status = _run_latexmk(
+                cmd,
+                env=(os.environ | tex_env_vars) if tex_env_vars else None,
+                log_path=os.path.join(aux_dir, f"{stem}-diff.log"),
+                fdb_path=os.path.join(aux_dir, f"{stem}-diff.fdb_latexmk"),
+                environment=environment,
+                verbose=verbose,
+            )
+            if status:
+                raise subprocess.CalledProcessError(status, cmd)
         except subprocess.CalledProcessError as e:
             # -silent hides why, so show the errors LaTeX logged
             log_path = Path(aux_dir, f"{stem}-diff.log")
@@ -993,10 +1272,13 @@ def _build_diff(
             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 with exit status "
-                f"{e.returncode}; rerun with --keep-tex to inspect it"
+            msg = (
+                "latexmk failed on the diff document with exit code "
+                f"{e.returncode}"
             )
+            if not keep_tex:
+                msg += "; rerun with --keep-tex to inspect"
+            raise_error(msg)
         built = os.path.join(aux_dir, f"{stem}-diff.pdf")
         if not os.path.isfile(built):
             raise_error("latexmk did not produce a PDF")
@@ -1007,16 +1289,28 @@ def _build_diff(
         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)
+        Path(state_path).write_text(digest)
         typer.echo(f"Wrote {output}")
     finally:
-        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)
+        if keep_tex:
+            os.makedirs(os.path.dirname(output) or ".", exist_ok=True)
+            if marked_up is not None:
+                Path(kept_diff_fpath).write_bytes(marked_up)
+            for src, kept_fpath in (
+                (base_tex_fpath, kept_old_fpath),
+                (head_tex_fpath, kept_new_fpath),
+            ):
+                if os.path.isfile(src):
+                    shutil.copy(src, kept_fpath)
+            for kept_fpath in (
+                kept_old_fpath,
+                kept_new_fpath,
+                kept_diff_fpath,
+            ):
+                if os.path.isfile(kept_fpath):
+                    typer.echo(f"Kept {kept_fpath} for inspection")
+        if os.path.isfile(diff_tex_fpath):
+            os.remove(diff_tex_fpath)
 
 
 @latex_app.command(name="to-docx")