typsphinx 0.6.2__tar.gz → 0.6.3__tar.gz

{typsphinx-0.6.2 → typsphinx-0.6.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: typsphinx
-Version: 0.6.2
+Version: 0.6.3
 Summary: Sphinx extension for Typst output
 Author-email: YuSabo <yusabo90002@gmail.com>
 License-Expression: MIT
@@ -249,7 +249,6 @@ Below are the main configuration options. This is not the complete set — see [
 - `typst_template`: Custom template path
 - `typst_elements`: Template parameters (paper size, fonts, etc.)
 - `typst_template_mapping`: Sphinx metadata to template parameter mapping
-- `typst_toctree_defaults`: Default toctree options
 
 ## Development
 
@@ -357,5 +356,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.6.2) - Production ready
+**Status**: Stable (v0.6.3) - Production ready
 **Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.6.2 → typsphinx-0.6.3}/README.md

@@ -205,7 +205,6 @@ Below are the main configuration options. This is not the complete set — see [
 - `typst_template`: Custom template path
 - `typst_elements`: Template parameters (paper size, fonts, etc.)
 - `typst_template_mapping`: Sphinx metadata to template parameter mapping
-- `typst_toctree_defaults`: Default toctree options
 
 ## Development
 
@@ -313,5 +312,5 @@ See [CHANGELOG.md](CHANGELOG.md) for detailed version history.
 
 ---
 
-**Status**: Stable (v0.6.2) - Production ready
+**Status**: Stable (v0.6.3) - Production ready
 **Python**: 3.12+ | **Sphinx**: 9.1+ | **Typst**: 0.15+

{typsphinx-0.6.2 → typsphinx-0.6.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "typsphinx"
-version = "0.6.2"
+version = "0.6.3"
 description = "Sphinx extension for Typst output"
 readme = "README.md"
 requires-python = ">=3.12"

{typsphinx-0.6.2 → typsphinx-0.6.3}/tests/test_pdf_render_gate.py

@@ -126,6 +126,12 @@ def table_width_render_gate_dir(fixtures_dir):
     return fixtures_dir / "table_width_render_gate"
 
 
+@pytest.fixture
+def captioned_table_render_gate_dir(fixtures_dir):
+    """Return the path to the captioned_table_render_gate fixture project."""
+    return fixtures_dir / "captioned_table_render_gate"
+
+
 @pytest.fixture
 def temp_build_dir(tmp_path):
     """Provide a temporary directory for build output."""
@@ -2333,3 +2339,325 @@ class TestTableWidthRenderGate:
                 "rendered PDF text -- table-width markup/code-mode "
                 "regression"
             )
+
+
+# ---------------------------------------------------------------------------
+# Phase 25 (TBL-01, TBL-02, GATE-01): extend the render-gate pattern to prove
+# the Plan 25-01 depart_table figure-wrap + single <label> fix renders
+# correctly through a real sphinx-build -> typst.compile() -> pypdf
+# round-trip -- two consecutive captioned tables (the stale-buffer proof:
+# 25-RESEARCH.md Verified Mechanism 2), a caption+:width: composition case,
+# a :numref:/:ref:-resolves case, and a captioned csv-table + list-table
+# case (D-05). ``TestCaptionedTablePreFixBasisFailureProof`` below closes
+# D-06's durable fail-pre-fix red->green requirement by reconstructing the
+# two pre-fix defect shapes from first principles now that Plan 25-01's fix
+# has replaced the buggy code -- the double-anchor collision (Critical
+# Pitfall 3, 25-RESEARCH.md) and the stale-buffer caption loss (Verified
+# Mechanism 2) -- mirroring the ``TestPreFixBasisFailureProof`` convention
+# already established in tests/test_package_only_config_gate.py.
+# ---------------------------------------------------------------------------
+
+# Sentinel tokens for the captioned-table render gate -- distinctive,
+# ALLCAPS-no-space words chosen so `full_text.count(...)` can prove each
+# caption reached the compiled PDF exactly once (guarding against both the
+# stray-heading bug -- Verified Mechanism 1 -- and the 2nd-table
+# stale-buffer caption-loss bug -- Verified Mechanism 2). Must match the
+# sentinel tokens embedded in captioned_table_render_gate/index.rst.
+TBLCAP_FIRST_SENTINEL = "TBLCAPFIRSTSENTINEL"
+TBLCAP_SECOND_SENTINEL = "TBLCAPSECONDSENTINEL"
+TBLCAP_WIDTH_SENTINEL = "TBLCAPWIDTHSENTINEL"
+TBLCAP_CSV_SENTINEL = "TBLCAPCSVSENTINEL"
+TBLCAP_LIST_SENTINEL = "TBLCAPLISTSENTINEL"
+
+
+class _CaptionedTableRenderGateArtifacts:
+    """
+    Plain container for the one real-compile artifact shared by every
+    ``TestCaptionedTableRenderGate`` test method: the emitted Typst source
+    text and the pypdf-extracted PDF text. A plain class (not a dict/tuple)
+    so each thin test method below can read ``.typ_source``/``.full_text``
+    by name.
+    """
+
+    def __init__(self, typ_source: str, full_text: str) -> None:
+        self.typ_source = typ_source
+        self.full_text = full_text
+
+
+@pytest.fixture(scope="class")
+def captioned_table_render_gate_artifacts(tmp_path_factory):
+    """
+    Build + real-compile the captioned_table_render_gate fixture ONCE per
+    class and return both the emitted Typst source text and the
+    pypdf-extracted PDF text.
+
+    Class-scoped so the four thin test methods below each assert a
+    disjoint slice of the SAME real-compile artifact rather than
+    re-running sphinx-build/typst.compile() four times (mirrors the
+    ``topic_line_block_render_gate_pdf_text`` class-scoped fixture pattern
+    above). Depends only on ``tmp_path_factory`` (session-scoped-
+    compatible) -- not on the narrower, function-scoped
+    ``captioned_table_render_gate_dir``/``fixtures_dir`` fixtures, to avoid
+    a pytest ScopeMismatch (a class-scoped fixture may not depend on a
+    narrower, function-scoped one).
+    """
+    source_dir = Path(__file__).parent / "fixtures" / "captioned_table_render_gate"
+    build_dir = tmp_path_factory.mktemp("captioned_table_gate") / "_build"
+
+    result = _run_sphinx_build_typst(source_dir, build_dir)
+    assert (
+        result.returncode == 0
+    ), f"sphinx-build failed:\nstdout: {result.stdout}\nstderr: {result.stderr}"
+
+    index_typ = build_dir / "index.typ"
+    assert index_typ.exists(), "index.typ was not generated"
+    typ_source = index_typ.read_text(encoding="utf-8")
+
+    # Compile the emitted .typ to PDF with typst-py, WITHOUT try/except:
+    # this is the crux of GATE-01 -- the double-anchor Critical Pitfall 3
+    # fatal (a captioned table's ids[0] defined twice) would abort the
+    # ENTIRE compile here, failing every dependent test method loudly,
+    # rather than merely failing a string-agreement check.
+    pdf_output = build_dir / "index.pdf"
+    typst.compile(str(index_typ), output=str(pdf_output))
+
+    assert pdf_output.exists(), "PDF file was not created"
+    assert pdf_output.stat().st_size > 0, "PDF file is empty"
+    with open(pdf_output, "rb") as f:
+        magic = f.read(4)
+        assert magic == b"%PDF", "Generated file is not a valid PDF"
+
+    reader = pypdf.PdfReader(str(pdf_output))
+    full_text = "\n".join(page.extract_text() for page in reader.pages)
+
+    return _CaptionedTableRenderGateArtifacts(typ_source, full_text)
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(
+    not (TYPST_AVAILABLE and PYPDF_AVAILABLE),
+    reason="typst-py and pypdf are both required for the GATE-01 render gate",
+)
+class TestCaptionedTableRenderGate:
+    """
+    Real-compile acceptance gate for TBL-01/TBL-02: the Plan 25-01
+    depart_table figure-wrap + single <label> fix, covering two
+    consecutive captioned tables (the stale-buffer proof), a
+    caption+:width: composition case, a :numref:/:ref:-resolves case, and
+    a captioned csv-table + list-table case (D-05).
+
+    Requirements: TBL-01, TBL-02, GATE-01 (25-CONTEXT.md, 25-RESEARCH.md
+    Validation Architecture, 25-01-SUMMARY.md).
+
+    All four test methods share the SAME real-compile artifact via the
+    class-scoped ``captioned_table_render_gate_artifacts`` fixture above --
+    sphinx-build/typst.compile() run exactly once per class, not once per
+    test method.
+    """
+
+    def test_each_caption_sentinel_appears_exactly_once(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        Each of the five caption sentinels appears EXACTLY ONCE in the
+        extracted PDF text -- proving neither the stray-heading bug
+        (Verified Mechanism 1) nor the 2nd-table stale-buffer
+        caption-loss bug (Verified Mechanism 2) regressed. The 2nd
+        table's sentinel (TBLCAPSECONDSENTINEL) is the specific
+        stale-buffer proof: a single-table fixture cannot expose it.
+        """
+        full_text = captioned_table_render_gate_artifacts.full_text
+
+        for sentinel in (
+            TBLCAP_FIRST_SENTINEL,
+            TBLCAP_SECOND_SENTINEL,
+            TBLCAP_WIDTH_SENTINEL,
+            TBLCAP_CSV_SENTINEL,
+            TBLCAP_LIST_SENTINEL,
+        ):
+            assert full_text.count(sentinel) == 1, (
+                f"Expected caption sentinel '{sentinel}' exactly once in "
+                "extracted PDF text -- possible stray-heading or "
+                "stale-buffer caption-loss regression (TBL-01)"
+            )
+
+    def test_typ_source_uses_figure_kind_table_with_no_heading_above(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        The emitted index.typ wraps every captioned table in
+        figure(..., kind: table) -- native Typst "Table N" numbering --
+        and no heading() call appears anywhere in the captioned-table
+        region (from the first figure( call onward): this fixture's only
+        heading() is the document's own top-level title, which precedes
+        every table (SC#1).
+        """
+        typ_source = captioned_table_render_gate_artifacts.typ_source
+
+        assert "figure(" in typ_source, (
+            "Expected 'figure(' in generated Typst source -- depart_table "
+            "figure-wrap regression"
+        )
+        assert "kind: table" in typ_source, (
+            "Expected 'kind: table' in generated Typst source -- "
+            "depart_table figure-wrap regression"
+        )
+
+        first_figure_index = typ_source.index("figure(")
+        captioned_table_region = typ_source[first_figure_index:]
+        assert "heading(" not in captioned_table_region, (
+            "Found a stray 'heading(' call inside the captioned-table "
+            "region -- a table caption fell through to the generic "
+            "section-heading path instead of being figure-wrapped "
+            "(Verified Mechanism 1 regression)"
+        )
+
+    def test_xref_numref_ref_resolve_no_empty_link(
+        self, captioned_table_render_gate_artifacts
+    ):
+        """
+        The :numref:/:ref: cross-references to the first captioned table
+        both resolve to a real link(<label>, ...) anchor reference in the
+        generated Typst source, with no link("", ...) leak -- mirrors
+        TestXrefRefidRenderGate's D-04 contract, applied to a captioned
+        table's own <label> instead of a section/glossary anchor.
+        """
+        typ_source = captioned_table_render_gate_artifacts.typ_source
+
+        assert "link(<" in typ_source, (
+            "Expected at least one refid link(<...>, ...) anchor "
+            "reference in the generated Typst source -- the "
+            ":numref:/:ref: to a captioned table may have regressed"
+        )
+        assert 'link("",' not in typ_source, (
+            'Found link("", ...) in generated Typst source -- the '
+            'never-link("", ...) contract has regressed'
+        )
+
+    def test_no_literal_source_leak(self, captioned_table_render_gate_artifacts):
+        """No LEAK_SIGNATURES token reaches the extracted PDF text."""
+        full_text = captioned_table_render_gate_artifacts.full_text
+
+        for leaked_token in LEAK_SIGNATURES:
+            assert leaked_token not in full_text, (
+                f"Literal Typst source '{leaked_token}' leaked into "
+                "rendered PDF text -- captioned-table markup/code-mode "
+                "regression"
+            )
+
+
+@pytest.mark.slow
+@pytest.mark.skipif(
+    not TYPST_AVAILABLE,
+    reason="typst-py is required for the GATE-01 pre-fix-basis failure proof",
+)
+class TestCaptionedTablePreFixBasisFailureProof:
+    """
+    Standing pre-fix-basis failure proof (D-06): reconstructs the two
+    pre-fix defect shapes from first principles -- the buggy code no
+    longer exists post Plan 25-01 -- and proves each one is genuinely
+    fail-pre-fix, mirroring the
+    ``tests/test_package_only_config_gate.py::TestPreFixBasisFailureProof``
+    convention (reconstruct the pre-fix compile basis; never assert on the
+    TEXT of a compiler error message).
+
+    (a) Double-anchor basis (Critical Pitfall 3, 25-RESEARCH.md): a
+    minimal Typst source in which one label id is defined TWICE -- once
+    as a ``[#metadata(none) <dup>]`` anchor (the unconditional
+    ``_emit_id_anchors`` call ``visit_table`` used to make even for a
+    captioned table) and once as a ``figure(...) <dup>`` postfix (the
+    NEW figure-wrap self-anchor this phase adds) -- plus a
+    ``link(<dup>, ...)`` reference to that label, reproducing the actual
+    :numref:/:ref: xref shape that resolves it. Live-verified while
+    writing this module: Typst does NOT raise merely from defining a
+    label twice with no reference to it; the "label ... occurs multiple
+    times" fatal fires only when something (here, the xref's own
+    ``link(<dup>, ...)``) tries to RESOLVE the ambiguous label -- exactly
+    the real-world shape a :numref:/:ref: to a captioned table produces.
+
+    (b) Stale-buffer basis (Verified Mechanism 2, 25-RESEARCH.md): a
+    reconstructed pre-fix two-table Typst source -- a plain ``table(...)``
+    for each, a stray ``heading(...)`` above the first (the OLD
+    stray-heading caption bug), and the SECOND caption sentinel
+    deliberately ABSENT (the observed pre-fix stale-buffer shape, where a
+    2nd table's caption silently vanished into a leftover buffer from the
+    first). This half is a pure string reconstruction (no compile needed)
+    proving the positive gate's ``full_text.count(sentinel) == 1``
+    assertion is genuinely fail-pre-fix: applied to this reconstruction,
+    the second sentinel's count is 0, not 1.
+
+    Requirements: TBL-01, TBL-02, D-06.
+    """
+
+    def test_double_anchor_basis_raises(self, tmp_path):
+        """
+        BUG basis (Critical Pitfall 3): reconstruct a captioned table
+        whose id is anchored TWICE -- once via the old unconditional
+        ``_emit_id_anchors`` metadata anchor, once via the new figure
+        ``<label>`` postfix -- with a ``link(<dup>, ...)`` xref
+        resolving it, and assert a real ``typst.compile()`` RAISES. No
+        assertion matches the exception's message text (D-06) -- only
+        that it raises.
+        """
+        reconstructed = (
+            "#metadata(none) <dup>\n"
+            "\n"
+            "#figure(\n"
+            "  table(\n"
+            "    columns: (1fr, 1fr),\n"
+            "    [A], [B],\n"
+            "  ),\n"
+            "  caption: [Caption],\n"
+            "  kind: table,\n"
+            ") <dup>\n"
+            "\n"
+            "See #link(<dup>, [Ref]).\n"
+        )
+        target = tmp_path / "double_anchor_basis.typ"
+        target.write_text(reconstructed, encoding="utf-8")
+
+        with pytest.raises(Exception):
+            typst.compile(str(target), root=str(tmp_path))
+
+    def test_stale_buffer_basis_second_sentinel_count_is_zero(self):
+        """
+        Stale-buffer basis (Verified Mechanism 2): a reconstructed pre-fix
+        two-table Typst source in which the SECOND table's caption
+        sentinel is deliberately absent (the observed pre-fix shape --
+        the second table's caption silently vanished into a stale
+        ``table_cell_content`` buffer left over from the first table).
+        Asserts the positive gate's ``count(...) == 1`` check FAILS
+        (count is 0) against this reconstruction -- proof the gate is
+        genuinely fail-pre-fix, not vacuously green.
+        """
+        reconstructed_pre_fix_shape = (
+            "heading(level: 1, {text(" + repr(TBLCAP_FIRST_SENTINEL) + ")})\n"
+            "\n"
+            "table(\n"
+            "  columns: (1fr, 1fr),\n"
+            "  [A], [B],\n"
+            ")\n"
+            "\n"
+            "table(\n"
+            "  columns: (1fr, 1fr),\n"
+            "  [C], [D],\n"
+            ")\n"
+        )
+
+        # The pre-fix stray-heading bug: the FIRST table's caption leaked
+        # into a heading() call (Verified Mechanism 1) instead of a
+        # figure caption -- present here to keep the reconstruction
+        # faithful to the actually-observed pre-fix output shape.
+        assert TBLCAP_FIRST_SENTINEL in reconstructed_pre_fix_shape
+
+        # The proof this test exists for: the SECOND table's caption
+        # sentinel never reached the reconstructed output at all -- the
+        # stale-buffer bug swallowed it. count() is 0, not 1, so the
+        # positive gate's exact-once assertion would have failed loudly
+        # against this pre-fix basis.
+        assert reconstructed_pre_fix_shape.count(TBLCAP_SECOND_SENTINEL) == 0, (
+            "Expected the reconstructed pre-fix stale-buffer basis to have "
+            "ZERO occurrences of the second table's caption sentinel -- "
+            "if this fails, the reconstruction no longer reproduces the "
+            "pre-fix bug shape and the fail-pre-fix proof is void"
+        )

{typsphinx-0.6.2 → typsphinx-0.6.3}/tests/test_preview_version_sync.py

@@ -1,5 +1,5 @@
 """
-Tests guarding the 3-way `@preview` version-sync hazard.
+Tests guarding the `@preview` version-sync hazard.
 
 typsphinx declares the same four Typst Universe `@preview` package versions
 (codly, codly-languages, mitex, gentle-clues) in three separate places:
@@ -9,6 +9,17 @@ Typst documents can end up importing mismatched package versions depending
 on which code path produced them. This module asserts the three declaration
 sites agree, so a future single-file edit fails CI loudly instead of
 silently (D-03).
+
+The bundled `examples/` templates are a fourth surface. They are not part of
+the extension's own import generation, so they carry no lockstep *identity*
+requirement across all four packages -- an example may legitimately use only
+some of them, or a different package entirely (charged-ieee). But when an
+example does pin one of the four, a stale pin is not cosmetic: it makes the
+shipped sample fail to compile outright (`codly-languages` older than 0.1.10
+aborts with `unknown variable: kai`). That is exactly what happened to
+`examples/advanced/_templates/custom.typ`, which sat three milestones behind
+the v0.5.0 bump because nothing watched it. `test_example_templates_match_canonical_versions`
+closes that gap.
 """
 
 import re
@@ -20,6 +31,8 @@ WRITER_PATH = REPO_ROOT / "typsphinx" / "writer.py"
 TEMPLATE_ENGINE_PATH = REPO_ROOT / "typsphinx" / "template_engine.py"
 BASE_TYP_PATH = REPO_ROOT / "typsphinx" / "templates" / "base.typ"
 
+EXAMPLES_DIR = REPO_ROOT / "examples"
+
 EXPECTED_PACKAGES = {"codly", "codly-languages", "mitex", "gentle-clues"}
 
 # Matches an actual Typst `#import "@preview/<name>:<version>"` statement
@@ -103,3 +116,33 @@ def test_all_four_packages_declared():
             f"{filename} is missing expected @preview packages: {missing} "
             f"(declared: {declared})"
         )
+
+
+def test_example_templates_match_canonical_versions():
+    """Bundled `examples/` .typ templates must not pin a stale version.
+
+    Scans every `.typ` file under `examples/` and, for each of the four
+    packages typsphinx itself pins, asserts the example agrees with the
+    canonical version in `base.typ`. Packages outside that set (e.g. an
+    example built on `charged-ieee`) are ignored, and an example that
+    imports none of the four is trivially fine -- this guards against
+    *drift*, not against an example choosing a different toolkit.
+    """
+    canonical = _extract_preview_versions(BASE_TYP_PATH)
+
+    stale = []
+    for typ_path in sorted(EXAMPLES_DIR.rglob("*.typ")):
+        for package, version in _extract_preview_versions(typ_path).items():
+            if package not in canonical:
+                continue
+            if version != canonical[package]:
+                stale.append(
+                    f"{typ_path.relative_to(REPO_ROOT)}: {package} pins "
+                    f"{version}, base.typ pins {canonical[package]}"
+                )
+
+    assert not stale, (
+        "bundled example template(s) pin @preview versions that diverge from "
+        "typsphinx/templates/base.typ -- a shipped sample that cannot compile: "
+        + "; ".join(stale)
+    )