feat(latex): add optional Tectonic TikZ rendering with isolated dependency staging

  Add opt-in TikZ image rendering for the LaTeX backend using Tectonic,
  while preserving stable fallback behavior when rendering fails.

  What this changes:
  - add optional `tikz_engine="tectonic"` backend support for TikZ diagrams
  - render `tikzpicture` environments asynchronously during LaTeX parsing
  - preserve raw TikZ code as `PictureMeta.code` whenever rendering fails,
    times out, or rasterization cannot complete
  - add Tectonic engine options for:
    - automatic binary download
    - per-diagram timeout
    - shell escape control
  - make shell escape explicit opt-in via CLI/backend config
  - sanitize known pdfTeX-only assignment lines in preambles for better
    Tectonic/XeTeX compatibility
  - restore file-backed relative TikZ compatibility by staging only explicit
    local dependencies (`\input`, `\include`, `\includegraphics`) into the
    temp render directory
  - block dependency path traversal and avoid ambient source-directory search
  - rasterize generated PDFs with locking and crop whitespace from output

  CLI / config updates:
  - add `--tikz-engine` / `-T`
  - add `--no-tikz-engine-download`
  - add `--tikz-engine-timeout`
  - add `--tikz-shell-escape`

  Tests:
  - add focused Tectonic engine tests for download behavior, timeout,
    preamble sanitization, shell escape toggling, dependency staging,
    and path traversal blocking
  - add backend tests for TikZ fallback behavior and file-backed source-root
    handling

Signed-off-by: Aditya Sasidhar <telikicherlaadityasasidhar@gmail.com>

Author: adityasasidhar

docling/backend/latex/engines/tectonic.py

@@ -1,27 +1,44 @@
 import logging
 import os
-import platform
+import re
 import shutil
 import subprocess
-import tarfile
 import tempfile
-import urllib.request
 from pathlib import Path
 
-import pypdfium2 as pdfium
 from docling_core.types.doc.document import ImageRef
 
 from docling.backend.latex.engines.base import RenderEngine
+from docling.utils.locks import pypdfium2_lock
 
 _log = logging.getLogger(__name__)
 
 
 class TectonicEngine(RenderEngine):
-    def __init__(self):
+    _PDFTEX_ASSIGNMENT_PATTERN = re.compile(
+        r"(?m)^([ \t]*)(\\(?:pdfcompresslevel|pdfminorversion|pdfobjcompresslevel)"
+        r"\s*=\s*.*)$"
+    )
+    _INPUT_COMMAND_PATTERN = re.compile(
+        r"""\\(?P<command>input|include)\s*\{(?P<path>[^{}\n]+)\}"""
+    )
+    _INCLUDEGRAPHICS_PATTERN = re.compile(
+        r"""\\includegraphics(?:\s*\[[^\]]*\])?\s*\{(?P<path>[^{}\n]+)\}"""
+    )
+    _LATEX_GRAPHICS_EXTENSIONS = (".pdf", ".png", ".jpg", ".jpeg", ".eps", ".svg")
+
+    def __init__(
+        self,
+        allow_download: bool = True,
+        timeout: float = 60.0,
+        allow_shell_escape: bool = True,
+    ):
         self.cache_dir = Path.home() / ".cache" / "docling" / "tectonic"
-        self.binary_path = None
+        self.binary_path = self.cache_dir / "tectonic"
+        self.allow_download = allow_download
+        self.timeout = timeout
+        self.allow_shell_escape = allow_shell_escape
         self._is_available = False
-
         self.install()
 
     def is_available(self) -> bool:
@@ -35,69 +52,224 @@ def install(self):
             _log.info(f"Using system tectonic at {self.binary_path}")
             return
 
-        self.binary_path = self.cache_dir / "tectonic"
         if self.binary_path.exists() and os.access(self.binary_path, os.X_OK):
             self._is_available = True
             return
 
-        system = platform.system().lower()
+        if not self.allow_download:
+            _log.warning(
+                "Tectonic binary not found and automatic download is disabled; "
+                "TikZ rendering will fall back."
+            )
+            return
 
-        if system not in ["linux", "darwin"]:
-            _log.warning(f"Tectonic engine is not supported on {system}")
+        if self._download_binary():
+            self._is_available = True
             return
 
+        _log.warning("Tectonic binary is unavailable; TikZ rendering will fall back.")
+
+    def _download_binary(self) -> bool:
         try:
             self.cache_dir.mkdir(parents=True, exist_ok=True)
             _log.info("Downloading Tectonic binary using the official script...")
-
             subprocess.run(
                 "curl --proto '=https' --tlsv1.2 -fsSL https://drop-sh.fullyjustified.net | sh",
                 shell=True,
                 cwd=self.cache_dir,
                 check=True,
             )
-
             if self.binary_path.exists():
                 self.binary_path.chmod(0o755)
-                self._is_available = True
-                _log.info(f"Tectonic successfully installed at {self.binary_path}")
-            else:
-                _log.warning("Tectonic binary not found after extraction.")
-
+                _log.info("Tectonic successfully installed at %s", self.binary_path)
+                return True
+            _log.warning("Tectonic binary not found after extraction.")
+            return False
         except Exception as e:
-            _log.warning(f"Failed to install Tectonic: {e}")
+            _log.warning("Failed to install Tectonic: %s", e)
+            return False
+
+    @classmethod
+    def _sanitize_preamble_for_tectonic(cls, preamble: str) -> str:
+        """Drop assignment-only pdfTeX primitives Tectonic/XeTeX does not provide."""
+        return cls._PDFTEX_ASSIGNMENT_PATTERN.sub(
+            r"\1% docling: removed for Tectonic compatibility: \2", preamble
+        )
+
+    @staticmethod
+    def _strip_comments(text: str) -> str:
+        return re.sub(r"(?m)(?<!\\)%.*$", "", text)
+
+    @classmethod
+    def _resolve_local_dependency(
+        cls, source_root: Path, raw_path: str, *, is_tex: bool
+    ) -> Path | None:
+        raw_path = raw_path.strip()
+        if not raw_path:
+            return None
+
+        candidate = Path(raw_path)
+        if candidate.is_absolute():
+            _log.warning("Absolute TikZ dependency paths are not staged: %s", raw_path)
+            return None
+
+        resolved = (source_root / candidate).resolve()
+        try:
+            if not resolved.is_relative_to(source_root):
+                _log.warning(
+                    "Path traversal attempt blocked for TikZ dependency: %s", raw_path
+                )
+                return None
+        except ValueError:
+            _log.warning("Invalid TikZ dependency path: %s", raw_path)
+            return None
+
+        if is_tex and not resolved.suffix:
+            resolved = resolved.with_suffix(".tex")
+        return resolved
+
+    @classmethod
+    def _find_existing_asset(cls, source_root: Path, raw_path: str) -> Path | None:
+        base_path = cls._resolve_local_dependency(source_root, raw_path, is_tex=False)
+        if base_path is None:
+            return None
+        if base_path.exists():
+            return base_path
+        if base_path.suffix:
+            return None
 
-    def render(self, tikz_code: str, preamble: str = "") -> ImageRef | None:
+        for suffix in cls._LATEX_GRAPHICS_EXTENSIONS:
+            candidate = base_path.with_suffix(suffix)
+            if candidate.exists():
+                return candidate
+        return None
+
+    @classmethod
+    def _collect_local_dependencies(
+        cls, text: str, source_root: Path, seen_tex_files: set[Path] | None = None
+    ) -> set[Path]:
+        if seen_tex_files is None:
+            seen_tex_files = set()
+
+        dependencies: set[Path] = set()
+        stripped_text = cls._strip_comments(text)
+
+        for match in cls._INPUT_COMMAND_PATTERN.finditer(stripped_text):
+            source_path = cls._resolve_local_dependency(
+                source_root, match.group("path"), is_tex=True
+            )
+            if source_path is None:
+                continue
+            if not source_path.exists():
+                _log.warning("TikZ dependency not found: %s", match.group("path"))
+                continue
+
+            dependencies.add(source_path)
+            if source_path in seen_tex_files:
+                continue
+
+            seen_tex_files.add(source_path)
+            try:
+                nested_text = source_path.read_text(encoding="utf-8")
+            except Exception as exc:
+                _log.warning("Failed to read TikZ dependency %s: %s", source_path, exc)
+                continue
+
+            dependencies.update(
+                cls._collect_local_dependencies(
+                    nested_text, source_root, seen_tex_files=seen_tex_files
+                )
+            )
+
+        for match in cls._INCLUDEGRAPHICS_PATTERN.finditer(stripped_text):
+            asset_path = cls._find_existing_asset(source_root, match.group("path"))
+            if asset_path is None:
+                _log.warning("TikZ asset not found: %s", match.group("path"))
+                continue
+            dependencies.add(asset_path)
+
+        return dependencies
+
+    @classmethod
+    def _stage_local_dependencies(
+        cls, temp_path: Path, preamble: str, tikz_code: str, source_root: Path | None
+    ) -> None:
+        if source_root is None:
+            return
+
+        source_root = source_root.resolve()
+        if not source_root.exists() or not source_root.is_dir():
+            _log.warning("TikZ source root is not a directory: %s", source_root)
+            return
+
+        dependencies = cls._collect_local_dependencies(
+            preamble + "\n" + tikz_code, source_root
+        )
+        for source_path in dependencies:
+            relative_path = source_path.relative_to(source_root)
+            staged_path = temp_path / relative_path
+            staged_path.parent.mkdir(parents=True, exist_ok=True)
+            shutil.copy2(source_path, staged_path)
+
+    def render(
+        self, tikz_code: str, preamble: str = "", source_root: Path | None = None
+    ) -> ImageRef | None:
         if not self.is_available():
             return None
 
         # Fallback preamble if none provided
         if not preamble.strip():
-            preamble = "\\usepackage{tikz}\n\\usepackage{pgfplots}\n\\pgfplotsset{compat=newest}"
+            preamble = (
+                "\\usepackage{tikz}\n"
+                "\\usepackage{pgfplots}\n"
+                "\\pgfplotsset{compat=newest}"
+            )
+        else:
+            preamble = self._sanitize_preamble_for_tectonic(preamble)
 
-        # Minimal LaTeX document wrapping the Tikz code
-        latex_doc = f"""\\documentclass[tikz, border=2pt]{{standalone}}
-        {preamble}
-        \\begin{{document}}
-        {tikz_code}
-        \\end{{document}}
-"""
+        latex_doc = (
+            "\\documentclass[border=20pt]{standalone}\n"
+            + preamble
+            + "\n"
+            + "\\begin{document}\n"
+            + tikz_code
+            + "\n"
+            + "\\end{document}\n"
+        )
 
         with tempfile.TemporaryDirectory() as temp_dir:
             temp_path = Path(temp_dir)
+            self._stage_local_dependencies(temp_path, preamble, tikz_code, source_root)
             tex_file = temp_path / "diagram.tex"
             tex_file.write_text(latex_doc, encoding="utf-8")
 
+            cmd = [str(self.binary_path)]
+            if self.allow_shell_escape:
+                cmd.extend(["-Z", "shell-escape"])
+            cmd.append("--print")
+            cmd.append(str(tex_file))
+
             try:
                 subprocess.run(
-                    [str(self.binary_path), str(tex_file)],
+                    cmd,
                     cwd=temp_dir,
                     capture_output=True,
                     check=True,
+                    timeout=self.timeout,
                 )
             except subprocess.CalledProcessError as e:
+                stderr = e.stderr.decode("utf-8", errors="replace")
+                stdout = e.stdout.decode("utf-8", errors="replace")
                 _log.warning(
-                    f"Tectonic compilation failed: {e.stderr.decode('utf-8', errors='replace')}"
+                    "Tectonic compilation failed: %s\nSTDOUT: %s",
+                    stderr,
+                    stdout,
+                )
+                return None
+            except subprocess.TimeoutExpired:
+                _log.warning(
+                    "Tectonic compilation timed out after %s seconds",
+                    self.timeout,
                 )
                 return None
 
@@ -107,10 +279,19 @@ def render(self, tikz_code: str, preamble: str = "") -> ImageRef | None:
                 return None
 
             try:
-                with pdfium.PdfDocument(pdf_file) as pdf:
-                    page = pdf[0]
-                    pil_image = page.render(scale=300 / 72).to_pil()
-                    page.close()
+                import pypdfium2 as pdfium
+
+                from docling.backend.docx.drawingml.utils import crop_whitespace
+
+                with pypdfium2_lock:
+                    with pdfium.PdfDocument(pdf_file) as pdf:
+                        page = pdf[0]
+                        pil_image = page.render(scale=300 / 72).to_pil()
+                        page.close()
+
+                # Auto-crop the generous border added by standalone,
+                # keeping a small padding (10px) for clean margins.
+                pil_image = crop_whitespace(pil_image, padding=10)
 
                 return ImageRef.from_pil(pil_image, dpi=300)
             except Exception as e: