Keep language builds from stopping on a stale snippet path

A stored translation can still name a docs_src file that an English change
has since renamed; language configs now build with snippet path checks off,
so that block renders empty under the outdated notice instead of failing the
docs build. On update jobs the carried sections are put back before any check
runs, so drift in text the run discards can no longer cost repair turns.

Author: maxisbey

scripts/docs/build_config.py

@@ -210,6 +210,12 @@ def build_config(lang: str | None = None, root: Path = ROOT) -> Path:
         # No API reference on a language site, so no mkdocstrings pass either.
         plugins: list[str | dict[str, Any]] = config["plugins"]
         config["plugins"] = [p for p in plugins if (next(iter(p)) if isinstance(p, dict) else p) != "mkdocstrings"]
+        # A stored translation can name a `docs_src` file an English change has since renamed:
+        # that block renders empty under the outdated notice instead of stopping the build.
+        extensions: list[str | dict[str, Any]] = config["markdown_extensions"]
+        for extension in extensions:
+            if isinstance(extension, dict) and extension.get("pymdownx.snippets"):
+                extension["pymdownx.snippets"]["check_paths"] = False
         config["theme"]["language"] = language.theme
         # Zensical resolves docs_dir/site_dir against the config file and
         # rejects absolute paths.

scripts/docs/translations.py

@@ -891,6 +891,9 @@ def _validate_open(english: str, body: str, job: Job, glossary: Glossary) -> lis
 def translate_page(repo: Repo, inputs: Inputs, job: Job, translator: Translator, model: str, usage: Usage) -> str:
     """Translate one page and return its body; token usage accumulates into `usage`.
 
+    Each reply has its carried sections overwritten before any check runs, so
+    only text this run keeps can cost a repair turn or fail the page.
+
     Raises:
         PageError: The page could not be produced (API failure, refusal, or unrepairable structure).
         ConfigError: The credentials were rejected.
@@ -908,9 +911,12 @@ def translate_page(repo: Repo, inputs: Inputs, job: Job, translator: Translator,
             raise PageError(f"the reply was cut off at {OUTPUT_TOKEN_BUDGET} output tokens")
         if completion.stop_reason == "refusal":
             raise PageError("the model declined to translate this page")
-        result = reimpose(english, ids, unwrap(english, completion.text))
-        if isinstance(result, str):  # aligned, so it can be assembled: carry sections forward, pin today's ids on them
-            result = reimpose(english, ids, carry_forward(job, result))
+        reply = unwrap(english, completion.text)
+        # Only a reply whose sections line up with the English can be assembled; one that
+        # does not is checked as it stands and fails the heading check.
+        if len(sections(reply)) == len(job.state.hashes):
+            reply = carry_forward(job, reply)
+        result = reimpose(english, ids, reply)  # today's ids pinned on carried sections too
         if isinstance(result, Mismatch):
             findings = result.findings
         elif not (findings := _validate_open(english, result, job, inputs.glossary)):  # checked as it would be written

tests/docs/test_build_config.py

@@ -23,6 +23,7 @@
     "nav": NAV,
     "theme": {"name": "material"},
     "plugins": ["search", {"mkdocstrings": {"handlers": {"python": {"paths": ["src"]}}}}],
+    "markdown_extensions": ["admonition", {"pymdownx.snippets": {"base_path": ["."], "check_paths": True}}],
 }
 
 LANGUAGES = """\
@@ -86,15 +87,17 @@ def test_alternate_lists_english_then_each_language_as_code_labelled_links_relat
 
 def test_lang_config_builds_the_staged_tree_into_site_code_without_an_api_reference(tmp_path: Path) -> None:
     """Tool-defined: `--lang ja` writes mkdocs.ja.gen.yml pointing Zensical at the staged tree (repo-relative),
-    building into site/ja/ under the ja URL prefix and theme language, with mkdocstrings dropped, the API
+    building into site/ja/ under the ja URL prefix and theme language, with mkdocstrings dropped, snippet path
+    checks off (a stale include in a stored translation renders empty rather than failing the build), the API
     entry turned into a link up to the English reference, section titles from the `titles.json` staged
     beside the tree, and the switcher with links relative to this site."""
     write_repo(tmp_path)
 
     written = build_config.build_config("ja", tmp_path)
 
     config = cast(dict[str, Any], yaml.safe_load(written.read_text(encoding="utf-8")))
-    picked = {key: config[key] for key in ("docs_dir", "site_dir", "site_url", "theme", "plugins", "nav", "extra")}
+    keys = ("docs_dir", "site_dir", "site_url", "theme", "plugins", "markdown_extensions", "nav", "extra")
+    picked = {key: config[key] for key in keys}
     assert (written.name, picked) == snapshot(
         (
             "mkdocs.ja.gen.yml",
@@ -104,6 +107,10 @@ def test_lang_config_builds_the_staged_tree_into_site_code_without_an_api_refere
                 "site_url": "https://docs.example/ja/",
                 "theme": {"name": "material", "language": "ja"},
                 "plugins": ["search"],
+                "markdown_extensions": [
+                    "admonition",
+                    {"pymdownx.snippets": {"base_path": ["."], "check_paths": False}},
+                ],
                 "nav": [
                     "index.md",
                     {"サーバー": ["servers/index.md", "servers/tools.md"]},

tests/docs/test_translations.py

@@ -779,6 +779,29 @@ def test_banned_rendering_is_a_finding_in_a_retranslated_section_but_not_in_a_ca
     assert body.endswith("## エラー {#errors}\n\nファンクションから送出します。\n")
 
 
+def test_link_dropped_in_a_carried_section_costs_no_repair_turn_and_the_stored_section_is_kept(
+    tmp_path: Path, capsys: pytest.CaptureFixture[str]
+) -> None:
+    """Tool-defined: a reply is assembled with the carried sections before its structure is checked, so a link
+    the model lost in a section this run discards anyway is no finding: one call, and the published intro is
+    the stored one, link and all."""
+    root = make_repo(tmp_path)
+    translate_all(capsys, root)
+    write(root / "docs" / "tools.md", TOOLS.replace("Raise to signal a failure.", "Raise `ToolError` to fail."))
+    reply = TOOLS_JA.replace("[ホーム](index.md#install)から", "ホームから").replace(
+        "失敗を伝えるには例外を送出します。", "失敗するには `ToolError` を送出します。"
+    )
+    fake = FakeTranslator([reply])
+
+    code, out, err = run(capsys, root, "translate", "--lang", "ja", translator=fake)
+
+    assert (code, err, out.split("\n")[0]) == (0, "", "translated: tools.md (1 of 3 sections)")
+    assert [len(conversation) for conversation in fake.conversations] == [1]  # one call, no repair turn
+    body = t.split_front_matter((root / "i18n" / "ja" / "pages" / "tools.md").read_text(encoding="utf-8"))[1]
+    assert t.sections(body)[0] == t.sections(TOOLS_JA)[0].replace("# ツール\n", "# ツール {#tools}\n")
+    assert body.endswith("## エラー {#errors}\n\n失敗するには `ToolError` を送出します。\n")
+
+
 def test_removed_english_section_is_reassembled_with_no_client_but_an_edited_one_needs_credentials_first(
     tmp_path: Path, capsys: pytest.CaptureFixture[str], monkeypatch: pytest.MonkeyPatch
 ) -> None:
@@ -921,8 +944,9 @@ def test_code_block_moved_out_of_a_retranslated_section_gets_repair_turns_like_a
     tmp_path: Path, capsys: pytest.CaptureFixture[str]
 ) -> None:
     """Tool-defined: on an update the same slip (the retranslated section's reply swallows the code block of
-    the carried section before it) is fed back for repair rather than failing the page outright, and the
-    fixed reply is assembled with the carried sections."""
+    the carried section before it) is fed back for repair rather than failing the page outright; the carried
+    section is the stored one by then, so only the retranslated section's extra fence is named, and the fixed
+    reply is assembled with the carried sections."""
     root = make_repo(tmp_path)
     translate_all(capsys, root)
     write(root / "docs" / "tools.md", TOOLS.replace("Raise to signal a failure.", "Raise `ToolError` to fail."))
@@ -937,7 +961,6 @@ def test_code_block_moved_out_of_a_retranslated_section_gets_repair_turns_like_a
 Your translation broke the following structural rules. Fix each problem and return the
 full corrected page, changing nothing else:
 
-- ## Your first tool: 0 code fences vs 1 in the English: keep each where it is, add none
 - ## Errors: 1 code fences vs 0 in the English: keep each where it is, add none\
 """)
     body = t.split_front_matter((root / "i18n" / "ja" / "pages" / "tools.md").read_text(encoding="utf-8"))[1]