texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/adapters/handlers/links.py

@@ -0,0 +1,239 @@
+"""Link handling utilities."""
+
+from __future__ import annotations
+
+from functools import lru_cache
+from hashlib import sha256
+from pathlib import Path
+from urllib.parse import urlparse
+
+from bs4 import BeautifulSoup
+from bs4.element import NavigableString, Tag
+from requests.utils import requote_uri as requote_url
+
+from texsmith.core.context import RenderContext
+from texsmith.core.exceptions import AssetMissingError, InvalidNodeError
+from texsmith.core.rules import RenderPhase, renders
+
+from ..latex.utils import escape_latex_chars
+from ..markdown import DEFAULT_MARKDOWN_EXTENSIONS, render_markdown
+from ._helpers import coerce_attribute, mark_processed, resolve_asset_path
+
+
+def _coerce_existing_path(candidate: Path) -> Path | None:
+    """Return a concrete file path for a directory or file candidate."""
+    if candidate.is_file():
+        return candidate.resolve()
+    if candidate.is_dir():
+        index_file = candidate / "index.md"
+        if index_file.exists():
+            return index_file.resolve()
+        html_index = candidate / "index.html"
+        if html_index.exists():
+            return html_index.resolve()
+    return None
+
+
+def _iter_local_href_candidates(href: str) -> list[str]:
+    """Return potential filesystem paths for a MkDocs-style link."""
+    clean_href = href.split("#", 1)[0].split("?", 1)[0].strip()
+    if not clean_href:
+        return []
+
+    candidates: list[str] = []
+
+    def add_candidate(value: str | None) -> None:
+        if value and value not in candidates:
+            candidates.append(value)
+
+    add_candidate(clean_href)
+
+    trimmed = clean_href
+    while trimmed.startswith("./"):
+        trimmed = trimmed[2:]
+    if trimmed.startswith("/"):
+        trimmed = trimmed.lstrip("/")
+    add_candidate(trimmed)
+
+    if not trimmed:
+        add_candidate("index.md")
+        return candidates
+
+    if trimmed.endswith("/"):
+        stripped = trimmed.rstrip("/")
+        add_candidate(stripped)
+        add_candidate(f"{trimmed}index.md")
+        add_candidate(f"{trimmed}index.html")
+        if stripped:
+            add_candidate(f"{stripped}/index.md")
+            add_candidate(f"{stripped}/index.html")
+            add_candidate(f"{stripped}.md")
+            add_candidate(f"{stripped}.html")
+    else:
+        suffix = Path(trimmed).suffix
+        if not suffix:
+            add_candidate(f"{trimmed}.md")
+            add_candidate(f"{trimmed}.html")
+            add_candidate(f"{trimmed}/index.md")
+            add_candidate(f"{trimmed}/index.html")
+
+    return candidates
+
+
+def _resolve_local_target(context: RenderContext, href: str) -> Path | None:
+    runtime_dir = context.runtime.get("source_dir")
+    if runtime_dir is not None:
+        for candidate in _iter_local_href_candidates(href):
+            candidate_path = _coerce_existing_path(Path(runtime_dir) / candidate)
+            if candidate_path is not None:
+                return candidate_path
+
+    document_path = context.runtime.get("document_path")
+    if document_path is not None:
+        for candidate in _iter_local_href_candidates(href):
+            resolved = resolve_asset_path(Path(document_path), candidate)
+            if resolved is not None:
+                coerced = _coerce_existing_path(resolved)
+                if coerced is not None:
+                    return coerced
+
+    project_dir = getattr(context.config, "project_dir", None)
+    if project_dir:
+        for candidate in _iter_local_href_candidates(href):
+            candidate_path = _coerce_existing_path(Path(project_dir) / candidate)
+            if candidate_path is not None:
+                return candidate_path
+
+    return None
+
+
+@renders(
+    "autoref",
+    phase=RenderPhase.INLINE,
+    priority=10,
+    name="autoref_tags",
+    nestable=False,
+)
+def render_autoref(element: Tag, context: RenderContext) -> None:
+    """Render <autoref> custom tags."""
+    identifier = coerce_attribute(element.get("identifier"))
+    if not identifier:
+        legacy_latex_accents = getattr(context.config, "legacy_latex_accents", False)
+        literal = f"<{element.name}>"
+        latex = escape_latex_chars(literal, legacy_accents=legacy_latex_accents)
+        element.replace_with(mark_processed(NavigableString(latex)))
+        return
+    text = element.get_text(strip=False)
+
+    latex = context.formatter.ref(text, ref=identifier)
+    element.replace_with(mark_processed(NavigableString(latex)))
+
+
+@renders(
+    "span",
+    phase=RenderPhase.INLINE,
+    priority=15,
+    name="autoref_spans",
+    nestable=False,
+    auto_mark=False,
+)
+def render_autoref_spans(element: Tag, context: RenderContext) -> None:
+    """Render MkDocs autoref span placeholders."""
+    identifier = coerce_attribute(element.get("data-autorefs-identifier"))
+    if not identifier:
+        return
+    text = element.get_text(strip=False)
+
+    latex = context.formatter.ref(text, ref=identifier)
+    node = mark_processed(NavigableString(latex))
+    context.mark_processed(element)
+    context.suppress_children(element)
+    element.replace_with(node)
+
+
+@renders("a", phase=RenderPhase.INLINE, priority=60, name="links", nestable=False)
+def render_links(element: Tag, context: RenderContext) -> None:
+    """Render hyperlinks and internal references."""
+    href = coerce_attribute(element.get("href")) or ""
+    element_id = coerce_attribute(element.get("id"))
+    text = element.get_text(strip=False)
+
+    # Already handled in preprocessing modules
+    if element.name != "a":
+        return
+
+    parsed_href = urlparse(href)
+    scheme = (parsed_href.scheme or "").lower()
+    fragment = parsed_href.fragment.strip() if parsed_href.fragment else ""
+
+    if scheme in {"http", "https"}:
+        latex = context.formatter.href(text=text, url=requote_url(href))
+    elif scheme:
+        raise InvalidNodeError(f"Unsupported link scheme '{scheme}' for '{href}'.")
+    elif href.startswith("#"):
+        latex = context.formatter.ref(text, ref=href[1:])
+    elif href == "" and element_id:
+        latex = context.formatter.label(element_id)
+    elif href:
+        resolved = _resolve_local_target(context, href)
+        if resolved is None:
+            raise AssetMissingError(f"Unable to resolve link target '{href}'")
+        target_ref = fragment or _infer_heading_reference(resolved)
+        if target_ref:
+            latex = context.formatter.ref(text or "", ref=target_ref)
+        else:
+            content = resolved.read_bytes()
+            digest = sha256(content).hexdigest()
+            reference = f"snippet:{digest}"
+            context.state.register_snippet(
+                reference,
+                {
+                    "path": resolved,
+                    "content": content,
+                    "format": resolved.suffix[1:] if resolved.suffix else "",
+                },
+            )
+            latex = context.formatter.ref(text or "extrait", ref=reference)
+    else:
+        legacy_latex_accents = getattr(context.config, "legacy_latex_accents", False)
+        latex = escape_latex_chars(text, legacy_accents=legacy_latex_accents)
+
+    element.replace_with(mark_processed(NavigableString(latex)))
+
+
+_HEADING_TAGS = ("h1", "h2", "h3", "h4", "h5", "h6")
+_HTML_EXTENSIONS = {".html", ".htm"}
+_MARKDOWN_EXTENSIONS = {".md", ".markdown", ".mkd", ".mkdn"}
+
+
+@lru_cache(maxsize=256)
+def _extract_primary_heading(path: str) -> str | None:
+    candidate = Path(path)
+    suffix = candidate.suffix.lower()
+    try:
+        payload = candidate.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError):
+        return None
+
+    if suffix in _HTML_EXTENSIONS:
+        soup = BeautifulSoup(payload, "html.parser")
+    elif suffix in _MARKDOWN_EXTENSIONS:
+        document = render_markdown(
+            payload,
+            extensions=DEFAULT_MARKDOWN_EXTENSIONS,
+            base_path=candidate.parent,
+        )
+        soup = BeautifulSoup(document.html, "html.parser")
+    else:
+        return None
+
+    heading = soup.find(_HEADING_TAGS, id=True)
+    if heading is None:
+        return None
+    identifier = heading.get("id")
+    return identifier or None
+
+
+def _infer_heading_reference(path: Path) -> str | None:
+    reference = _extract_primary_heading(str(path.resolve()))
+    return reference

texsmith/adapters/handlers/media.py

@@ -0,0 +1,380 @@
+"""Handlers responsible for assets such as images and diagrams."""
+
+from __future__ import annotations
+
+import hashlib
+from pathlib import Path
+from typing import Any
+import warnings
+
+from bs4.element import NavigableString, Tag
+from requests.utils import requote_uri as requote_url
+
+from texsmith.core.context import RenderContext
+from texsmith.core.diagnostics import DiagnosticEmitter
+from texsmith.core.exceptions import (
+    AssetMissingError,
+    InvalidNodeError,
+    exception_hint,
+    exception_messages,
+)
+from texsmith.core.rules import RenderPhase, renders
+from texsmith.fonts.scripts import render_moving_text
+
+from ..latex.utils import escape_latex_chars
+from ..transformers import mermaid2pdf
+from ._assets import store_local_image_asset, store_remote_image_asset
+from ._helpers import (
+    coerce_attribute,
+    gather_classes,
+    is_valid_url,
+    mark_processed,
+    resolve_asset_path,
+)
+from ._mermaid import (
+    MERMAID_FILE_SUFFIXES,
+    extract_mermaid_live_diagram as _extract_mermaid_live_diagram,
+    looks_like_mermaid as _looks_like_mermaid,
+)
+
+
+def _runtime_emitter(context: RenderContext) -> DiagnosticEmitter | None:
+    """Return the diagnostic emitter bound to the current runtime, if any."""
+    emitter = context.runtime.get("emitter")
+    if isinstance(emitter, DiagnosticEmitter):
+        return emitter
+    return None
+
+
+def _load_mermaid_diagram(context: RenderContext, src: str) -> tuple[str, str] | None:
+    """Attempt to load a Mermaid diagram from a local file or URL."""
+    lowercase = src.lower()
+    if lowercase.endswith(MERMAID_FILE_SUFFIXES):
+        resolved = _resolve_source_path(context, src)
+        if resolved is None:
+            raise AssetMissingError(f"Unable to resolve Mermaid diagram '{src}'")
+        try:
+            return resolved.read_text(encoding="utf-8"), "file"
+        except OSError as exc:
+            raise AssetMissingError(f"Unable to read Mermaid diagram '{resolved}'") from exc
+
+    diagram = _extract_mermaid_live_diagram(src)
+    if diagram is not None:
+        return diagram, "url"
+
+    return None
+
+
+def _figure_template_for(element: Tag) -> str | None:
+    """Determine which figure template to use based on ancestor metadata."""
+    current = element
+    while current is not None:
+        raw_classes = getattr(current, "get", lambda *_: None)("class")
+        class_list = gather_classes(raw_classes)
+        if any(cls in {"admonition", "exercise"} for cls in class_list):
+            return "figure_tcolorbox"
+        if getattr(current, "name", None) == "details":
+            return "figure_tcolorbox"
+        current = getattr(current, "parent", None)
+    return None
+
+
+def _resolve_source_path(context: RenderContext, src: str) -> Path | None:
+    """Resolve a local asset path using runtime hints."""
+    runtime_dir = context.runtime.get("source_dir")
+    if runtime_dir is not None:
+        candidate = Path(runtime_dir) / src
+        if candidate.exists():
+            return candidate.resolve()
+
+    document_path = context.runtime.get("document_path")
+    if document_path is not None:
+        resolved = resolve_asset_path(Path(document_path), src)
+        if resolved is not None:
+            return resolved
+
+    project_dir = getattr(context.config, "project_dir", None)
+    if project_dir:
+        candidate = Path(project_dir) / src
+        if candidate.exists():
+            return candidate.resolve()
+
+    return None
+
+
+_MKDOCS_THEME_VARIANTS = {"only-light", "only-dark"}
+
+
+def _strip_mkdocs_theme_variant(src: str) -> str:
+    """Drop MkDocs Material light/dark suffixes appended to image URLs."""
+    base, sep, fragment = src.partition("#")
+    if not sep:
+        return src
+    if fragment.lower() in _MKDOCS_THEME_VARIANTS:
+        return base
+    return src
+
+
+def _apply_figure_template(
+    context: RenderContext,
+    *,
+    path: Path,
+    caption: str | None = None,
+    shortcaption: str | None = None,
+    alt: str | None = None,
+    label: str | None = None,
+    width: str | None = None,
+    template: str | None = None,
+    adjustbox: bool = False,
+    link: str | None = None,
+) -> NavigableString:
+    """Render the shared figure template and return a new node."""
+    template_name = template or context.runtime.get("figure_template", "figure")
+    formatter = getattr(context.formatter, template_name)
+    asset_path = context.assets.latex_path(path)
+    legacy_accents = getattr(context.config, "legacy_latex_accents", False)
+    caption = render_moving_text(caption, context, legacy_accents=legacy_accents, wrap_scripts=True)
+    shortcaption = render_moving_text(
+        shortcaption, context, legacy_accents=legacy_accents, wrap_scripts=True
+    )
+    alt_text = render_moving_text(alt, context, legacy_accents=legacy_accents, wrap_scripts=True)
+    effective_shortcaption = shortcaption or alt_text or caption
+    safe_link = (
+        escape_latex_chars(requote_url(link), legacy_accents=legacy_accents) if link else None
+    )
+    latex = formatter(
+        path=asset_path,
+        caption=caption,
+        shortcaption=effective_shortcaption,
+        label=label,
+        width=width,
+        adjustbox=adjustbox,
+        link=safe_link,
+    )
+    return mark_processed(NavigableString(latex))
+
+
+def _render_mermaid_diagram(
+    context: RenderContext,
+    diagram: str,
+    *,
+    template: str | None = None,
+    caption: str | None = None,
+    width: str | None = None,
+) -> NavigableString | None:
+    """Render a Mermaid diagram and return the resulting LaTeX node."""
+    extracted_caption, body = _mermaid_caption(diagram)
+    effective_caption = extracted_caption if extracted_caption is not None else caption
+    if not context.runtime.get("copy_assets", True):
+        placeholder = effective_caption or "Mermaid diagram"
+        return mark_processed(NavigableString(placeholder))
+    if not _looks_like_mermaid(body):
+        return None
+    if "```" in body or "~~~" in body:
+        return None
+
+    render_options: dict[str, Any] = {}
+    mermaid_config = getattr(context.config, "mermaid_config", None)
+    if mermaid_config:
+        project_dir = getattr(context.config, "project_dir", None)
+        if project_dir is None:
+            raise AssetMissingError("Project directory required to render Mermaid diagrams")
+        render_options["config_filename"] = Path(project_dir) / mermaid_config
+    backend = context.runtime.get("diagrams_backend")
+    if backend:
+        render_options["backend"] = backend
+    runtime_mermaid_config = context.runtime.get("mermaid_config")
+    if runtime_mermaid_config is not None:
+        render_options["mermaid_config"] = runtime_mermaid_config
+
+    try:
+        artefact = mermaid2pdf(body, output_dir=context.assets.output_root, **render_options)
+    except Exception as exc:  # pragma: no cover - safeguard
+        _warn_mermaid_failure(context, exc)
+        placeholder = effective_caption or "Mermaid diagram"
+        return mark_processed(NavigableString(f"[{placeholder} unavailable]"))
+
+    asset_key = f"mermaid::{hashlib.sha256(body.encode('utf-8')).hexdigest()}"
+    stored_path = context.assets.register(asset_key, artefact)
+
+    return _apply_figure_template(
+        context,
+        path=stored_path,
+        caption=effective_caption,
+        label=None,
+        width=width,
+        template=template,
+        adjustbox=True,
+    )
+
+
+def _mermaid_caption(diagram: str) -> tuple[str | None, str]:
+    """Extract caption from the diagram comment header."""
+    lines = diagram.splitlines()
+    if lines and lines[0].strip().startswith("%%"):
+        caption = lines[0].strip()[2:].strip() or None
+        body = "\n".join(lines[1:])
+        return caption, body
+    return None, diagram
+
+
+@renders("img", phase=RenderPhase.BLOCK, name="render_images", nestable=False)
+def render_images(element: Tag, context: RenderContext) -> None:
+    """Convert <img> nodes into LaTeX figures and manage assets."""
+    if not context.runtime.get("copy_assets", True):
+        alt_text = (
+            coerce_attribute(element.get("alt")) or coerce_attribute(element.get("title")) or ""
+        )
+        placeholder = alt_text.strip() or "[image]"
+        element.replace_with(mark_processed(NavigableString(placeholder)))
+        return
+
+    src = coerce_attribute(element.get("src"))
+    if not src:
+        raise InvalidNodeError("Image tag without 'src' attribute")
+
+    src = _strip_mkdocs_theme_variant(src)
+
+    classes = gather_classes(element.get("class"))
+    if {"twemoji", "emojione"}.intersection(classes):
+        return
+
+    if element.find_parent("figure"):
+        return
+
+    raw_alt = coerce_attribute(element.get("alt"))
+    alt_text = raw_alt.strip() if raw_alt else None
+    raw_title = coerce_attribute(element.get("title"))
+    caption_text = raw_title.strip() if raw_title else None
+    width = coerce_attribute(element.get("width")) or None
+    template = _figure_template_for(element)
+
+    link_wrapper = None
+    link_target = None
+    parent = element.parent
+    if isinstance(parent, Tag) and parent.name == "a":
+        candidates = [
+            child
+            for child in parent.contents
+            if not (isinstance(child, NavigableString) and not child.strip())
+        ]
+        if len(candidates) == 1 and candidates[0] is element:
+            link_wrapper = parent
+            link_target = coerce_attribute(parent.get("href"))
+
+    mermaid_payload = _load_mermaid_diagram(context, src)
+    if mermaid_payload is not None:
+        diagram, _ = mermaid_payload
+        figure_node = _render_mermaid_diagram(
+            context,
+            diagram,
+            template=template,
+            caption=caption_text,
+        )
+        if figure_node is None:
+            raise InvalidNodeError(f"Mermaid source '{src}' does not contain a valid diagram")
+        element.replace_with(figure_node)
+        return
+
+    if not caption_text:
+        caption_text = alt_text
+
+    if is_valid_url(src):
+        stored_path = store_remote_image_asset(context, src)
+    else:
+        resolved = _resolve_source_path(context, src)
+        if resolved is None:
+            raise AssetMissingError(f"Unable to resolve image asset '{src}'")
+
+        stored_path = store_local_image_asset(context, resolved)
+
+    figure_node = _apply_figure_template(
+        context,
+        path=stored_path,
+        caption=caption_text,
+        alt=alt_text,
+        label=None,
+        width=width,
+        template=template,
+        adjustbox=False,
+        link=link_target,
+    )
+    if link_wrapper:
+        link_wrapper.replace_with(figure_node)
+    else:
+        element.replace_with(figure_node)
+
+
+@renders("div", phase=RenderPhase.BLOCK, name="render_mermaid", nestable=False)
+def render_mermaid(element: Tag, context: RenderContext) -> None:
+    """Convert Mermaid code blocks inside highlight containers."""
+    classes = gather_classes(element.get("class"))
+    if "highlight" not in classes and "mermaid" not in classes:
+        return
+
+    code = element.find("code")
+    if code is None:
+        return
+
+    diagram = code.get_text()
+    width = coerce_attribute(code.get("width") or element.get("width"))
+    template = _figure_template_for(element)
+    figure_node = _render_mermaid_diagram(context, diagram, template=template, width=width)
+    if figure_node is None:
+        return
+
+    element.replace_with(figure_node)
+
+
+@renders("pre", phase=RenderPhase.BLOCK, name="render_mermaid_pre", nestable=False)
+def render_mermaid_pre(element: Tag, context: RenderContext) -> None:
+    """Handle <pre class=\"mermaid\"> blocks."""
+    classes = gather_classes(element.get("class"))
+    if "mermaid" not in classes:
+        return
+
+    diagram: str | None = None
+    source_hint = coerce_attribute(element.get("data-mermaid-source"))
+    if source_hint:
+        payload = _load_mermaid_diagram(context, source_hint)
+        if payload is not None:
+            diagram, _ = payload
+    if diagram is None:
+        diagram = element.get_text()
+    width = coerce_attribute(element.get("width"))
+
+    template = _figure_template_for(element)
+    figure_node = _render_mermaid_diagram(context, diagram, template=template, width=width)
+    if figure_node is None:
+        return
+
+    element.replace_with(figure_node)
+
+
+def _warn_mermaid_failure(context: RenderContext, exc: Exception) -> None:
+    """Emit a CLI-friendly warning describing Mermaid rendering failures."""
+    emitter = _runtime_emitter(context)
+    guidance = (
+        "Install Docker and the 'minlag/mermaid-cli' image (or register a custom Mermaid "
+        "converter) to enable diagram rendering."
+    )
+    summary = "Mermaid diagram could not be rendered. TexSmith inserted a placeholder instead."
+    hint = exception_hint(exc)
+
+    if emitter is None:
+        detail = f" ({hint})" if hint else ""
+        message = f"{summary}{detail}. {guidance}"
+        warnings.warn(message, stacklevel=3)
+        return
+
+    if emitter.debug_enabled:
+        chain = exception_messages(exc)
+        detail_block = ""
+        if chain:
+            detail_lines = "\n".join(f"- {line}" for line in chain)
+            detail_block = f"\nDetails:\n{detail_lines}"
+        emitter.warning(f"{summary}{detail_block}\n{guidance}", exc=exc)
+        return
+
+    detail = f" ({hint})" if hint else ""
+    emitter.warning(f"{summary}{detail}. {guidance} Run with --debug for technical details.")

texsmith/adapters/latex/__init__.py

@@ -0,0 +1,10 @@
+"""LaTeX-specific utilities exposed by Texsmith."""
+
+from __future__ import annotations
+
+from .formatter import LaTeXFormatter, optimize_list
+from .renderer import LaTeXRenderer
+from .utils import escape_latex_chars
+
+
+__all__ = ["LaTeXFormatter", "LaTeXRenderer", "escape_latex_chars", "optimize_list"]