calkit-python 0.47.6__tar.gz → 0.47.8__tar.gz

{calkit_python-0.47.6 → calkit_python-0.47.8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: calkit-python
-Version: 0.47.6
+Version: 0.47.8
 Summary: Reproducibility simplified.
 Project-URL: Homepage, https://calkit.org
 Project-URL: Issues, https://github.com/calkit/calkit/issues

{calkit_python-0.47.6 → calkit_python-0.47.8}/agent-plugin/skills/check-questions/SKILL.md

@@ -135,7 +135,9 @@ project, not a tidy-up.
 - One claim per question, two to four sentences. Say what was found and
   what it means; leave the reasoning to the publication.
 - Numbers come from `value` evidence via placeholders, formatted to the
-  precision the claim needs: `{ratio:.1f}x`, `{error:.0%}`.
+  precision the claim needs: `{ratio:.1f}x`, `{error:.0%}`. When several
+  come from one file, e.g., the outputs of one calculation, name them
+  together in one `result` entry's `values`, a map of name to key.
 - A `value` entry must read a file a pipeline stage writes. A placeholder
   over a results file written by hand, including one you write, is a
   retyped number with extra steps, and the check fails it. If no stage
@@ -152,17 +154,15 @@ project, not a tidy-up.
     if p < 0.05: "The closure cuts error by {improvement:.1f}x."
     else: "The closure does not measurably reduce error."
   evidence:
-    - kind: value
+    - kind: result
       path: results/closure.json
-      key: p-value
-      name: p
-    - kind: value
-      path: results/closure.json
-      key: improvement
+      values:
+        p: p-value
+        improvement: improvement
   ```
 
-  Conditions name `value` evidence, so those names must be valid Python
-  identifiers; give the entry a `name` otherwise. Every branch must be a
+  Conditions use the names of values, so those names must be valid Python
+  identifiers. Every branch must be a
   claim the evidence would support if it held. The threshold is part of
   the claim: take it from the field's convention or the user, never pick
   it to make the current branch hold, and don't use branches to hedge a

{calkit_python-0.47.6 → calkit_python-0.47.8}/calkit/cli/latex.py

@@ -137,6 +137,43 @@ def from_json(
             json2latex.dump(cmd_name, formatted, f)
 
 
+@latex_app.command(name="from-questions")
+def from_questions(
+    output_fpaths: Annotated[
+        list[str],
+        typer.Option("--output", "-o", help="Output LaTeX file path(s)."),
+    ],
+    command_name: Annotated[
+        str,
+        typer.Option("--command", help="Command name to use in LaTeX output."),
+    ] = "questions",
+) -> None:
+    """Write the project's questions and answers as a LaTeX command.
+
+    Each question's text, hypothesis, answer, and notes are rendered from
+    their evidence and exposed as, e.g., ``\\questions[staging.answer]``,
+    keyed by the question's ``name`` or its 1-based position.
+    """
+    import json2latex
+
+    import calkit.questions
+
+    for out_path in output_fpaths:
+        if not out_path.endswith(".tex"):
+            raise_error("Output file must be a .tex file")
+    ck_info = calkit.load_calkit_info()
+    try:
+        values = calkit.questions.latex_values(ck_info)
+    except ValueError as e:
+        raise_error(str(e))
+    for out_path in output_fpaths:
+        outdir = os.path.dirname(out_path)
+        if outdir:
+            os.makedirs(outdir, exist_ok=True)
+        with open(out_path, "w") as f:
+            json2latex.dump(command_name, values, f)
+
+
 def _tex_cmd(
     tex_cmd: list[str],
     environment: str | None,
@@ -308,6 +345,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
 
@@ -372,7 +412,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[
@@ -436,7 +478,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[
@@ -471,6 +517,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``.
 
@@ -592,7 +685,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 = [
@@ -600,7 +695,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.
@@ -661,6 +757,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,
@@ -729,9 +839,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,
@@ -788,9 +898,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,
@@ -803,39 +913,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
@@ -859,7 +993,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,
@@ -867,7 +1001,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 "
@@ -907,8 +1043,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"]
@@ -928,7 +1063,7 @@ 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)
         cmd = _tex_cmd(
             latexmk_cmd,
             environment=environment,
@@ -956,10 +1091,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")
@@ -970,16 +1108,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")

{calkit_python-0.47.6 → calkit_python-0.47.8}/calkit/cli/list.py

@@ -197,7 +197,10 @@ def _echo_question(n: int, question: str | dict) -> None:
     question = dict(question)
     text = question.pop("question", "")
     typer.echo(f"{n}. question: {text}")
+    # Rendering fills every field, so leave out the ones that aren't set
     for k, v in question.items():
+        if v is None:
+            continue
         if isinstance(v, dict):
             typer.echo(f"    {k}:")
             for k1, v1 in v.items():
@@ -206,11 +209,17 @@ def _echo_question(n: int, question: str | dict) -> None:
             typer.echo(f"    {k}:")
             for item in v:
                 if isinstance(item, dict):
+                    item = {
+                        k1: v1 for k1, v1 in item.items() if v1 is not None
+                    }
                     for n1, (k1, v1) in enumerate(item.items()):
-                        if n1 == 0:
-                            typer.echo(f"      - {k1}: {v1}")
+                        prefix = "      - " if n1 == 0 else "        "
+                        if isinstance(v1, dict):
+                            typer.echo(f"{prefix}{k1}:")
+                            for k2, v2 in v1.items():
+                                typer.echo(f"          {k2}: {v2}")
                         else:
-                            typer.echo(f"        {k1}: {v1}")
+                            typer.echo(f"{prefix}{k1}: {v1}")
                 else:
                     typer.echo(f"        - {item}")
         else:

{calkit_python-0.47.6 → calkit_python-0.47.8}/calkit/cli/main/core.py

@@ -684,10 +684,16 @@ def get_status(
         typer.echo()
     if "dvc" in categories:
         print_sep("DVC")
+        from dvc.exceptions import NotDvcRepoError
+
         try:
             calkit.dvc.get_dvc_repo()
-        except Exception:
+        except NotDvcRepoError:
             typer.echo("This is not a DVC repository.\n")
+        except Exception as e:
+            typer.echo(
+                f"Failed to open DVC repo: {e.__class__.__name__}: {e}\n"
+            )
         else:
             zip_path_map = calkit.dvc.zip.get_zip_path_map()
             dvc_repo = calkit.dvc.get_dvc_repo()
@@ -2699,14 +2705,19 @@ def run(
             os.environ.pop("CALKIT_PIPELINE_RUNNING", None)
             raise_error(f"Pipeline compilation failed: {e}")
     # Initialize DVC repo if necessary
+    from dvc.exceptions import NotDvcRepoError
+
     try:
         calkit.dvc.get_dvc_repo()
-    except Exception:
+    except NotDvcRepoError:
         if not quiet:
             typer.echo("Initializing DVC repo")
         result = calkit.dvc.init()
         if result != 0:
             raise_error("Failed to initialize DVC repo")
+    except Exception as e:
+        # E.g., DVC's site cache dir isn't writable, which 'dvc init' can't fix
+        raise_error(f"Failed to open DVC repo: {e.__class__.__name__}: {e}")
     # Convert deps into target stage names
     # TODO: This could probably be merged back upstream into DVC
     if dvc_stages is None:

{calkit_python-0.47.6 → calkit_python-0.47.8}/calkit/cli/sync.py

@@ -39,12 +39,16 @@ def sync_dvc(
     no_check_auth: Annotated[bool, typer.Option("--no-check-auth")] = False,
 ) -> None:
     """Sync the DVC repository by pulling and then pushing."""
+    from dvc.exceptions import NotDvcRepoError
+
     from calkit.cli.main.core import pull, push
 
     try:
         calkit.dvc.get_dvc_repo()
-    except Exception:
+    except NotDvcRepoError:
         raise_error("No DVC repository found. Run 'calkit init' first.")
+    except Exception as e:
+        raise_error(f"Failed to open DVC repo: {e.__class__.__name__}: {e}")
     if not calkit.dvc.get_remotes():
         raise_error(
             "No DVC remotes configured. Add a remote with "

{calkit_python-0.47.6 → calkit_python-0.47.8}/calkit/models/core.py

@@ -1703,8 +1703,12 @@ class FigureEvidence(BaseModel):
 
 class ResultsEvidence(BaseModel):
     """Evidence in the form of a results file: a set of values, a table, a
-    map, whatever the pipeline wrote. For one value inside such a file, use
-    ``value`` evidence, which can be templated into the answer.
+    map, whatever the pipeline wrote.
+
+    ``values`` names related values within it, like the fields of a struct
+    or object,
+    so each can be templated into the answer as ``value`` evidence would be
+    without an entry per value.
     """
 
     kind: Literal["result"] = "result"
@@ -1716,6 +1720,14 @@ class ResultsEvidence(BaseModel):
             "results file."
         ),
     )
+    values: dict[str, str] | None = Field(
+        default=None,
+        description=(
+            "Values within the results file, mapping each name, under which "
+            "it can be templated into the question's text, to its key. Names "
+            "must be unique within the question."
+        ),
+    )
     explanation: str | None = None
     git_ref: str | None = Field(
         default=None,
@@ -1725,11 +1737,17 @@ class ResultsEvidence(BaseModel):
         ),
     )
 
+    @model_validator(mode="after")
+    def _key_or_values(self) -> ResultsEvidence:
+        if self.key is not None and self.values is not None:
+            raise ValueError("a result takes 'values' or 'key', not both")
+        return self
+
 
 _KEY_DESCRIPTION = (
-    "Key of the value within the results file. A key present at the top "
-    "level is used as-is; otherwise it is split on dots and walked into "
-    "nested objects, with integers indexing lists."
+    "Key of the value within the results file. It is split on dots and "
+    "walked into nested objects, taking the longest run of parts that names "
+    "a key at each level, with integers indexing lists."
 )
 
 
@@ -1817,6 +1835,34 @@ class PublicationEvidence(BaseModel):
     )
 
 
+class DocumentEvidence(BaseModel):
+    """Evidence in the form of a document cited by path, e.g., a Markdown
+    write-up, without declaring it as a publication.
+
+    The document must be built by a pipeline stage, usually a Markdown
+    stage, so its numbers are injected from the results and go stale with
+    them; one written by hand is an error, like a typed-in value.
+    """
+
+    kind: Literal["document"] = "document"
+    path: str
+    section: str | None = Field(
+        default=None,
+        description=(
+            "Section of the document where the evidence is presented, as a "
+            "reader would find it, e.g., '4.2' or 'Results'."
+        ),
+    )
+    explanation: str | None = None
+    git_ref: str | None = Field(
+        default=None,
+        description=(
+            "Git reference (branch, tag, or commit hash) pointing to the "
+            "version of the repository where the document can be found."
+        ),
+    )
+
+
 class Question(BaseModel):
     """A question the project hopes to answer.
 
@@ -1839,6 +1885,15 @@ class Question(BaseModel):
     new evidence is how to say it still holds.
     """
 
+    name: str | None = Field(
+        default=None,
+        description=(
+            "Name for the question, e.g., for quoting its answer in a "
+            "document through 'calkit latex from-questions'. Unlike its "
+            "position in the list, it survives questions being added or "
+            "reordered. Must be unique among the project's questions."
+        ),
+    )
     question: str
     hypothesis: str | None = None
     answer: str | dict[str, str] | None = Field(
@@ -1866,10 +1921,23 @@ class Question(BaseModel):
             | ValueEvidence
             | TableEvidence
             | PublicationEvidence
+            | DocumentEvidence
         ]
         | None
     ) = None
 
+    @field_validator("name")
+    @classmethod
+    def check_name_not_a_position(cls, v: str | None) -> str | None:
+        # A question is also addressable by its position, so an all-digit
+        # name would be ambiguous with some other question's number
+        if v is not None and v.isdigit():
+            raise ValueError(
+                f"Question name {v!r} can't be a number, since questions "
+                "are also addressed by position"
+            )
+        return v
+
 
 class ProjectInfo(BaseModel):
     """All of the project's information or metadata, written to the
@@ -2074,3 +2142,14 @@ class ProjectInfo(BaseModel):
         description="Overleaf sync configuration, keyed by the path of the "
         "synced directory.",
     )
+
+    @field_validator("questions")
+    @classmethod
+    def check_question_names_unique(
+        cls, v: list[str | Question]
+    ) -> list[str | Question]:
+        names = [q.name for q in v if isinstance(q, Question) and q.name]
+        dupes = sorted({n for n in names if names.count(n) > 1})
+        if dupes:
+            raise ValueError(f"Question names must be unique: {dupes}")
+        return v