texsmith 0.0.2.dev0__py3-none-any.whl

texsmith/core/user_dir.py

@@ -0,0 +1,179 @@
+"""Centralised resolution of the TeXSmith user and cache directories."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from contextlib import contextmanager
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import shutil
+from threading import RLock
+
+
+__all__ = [
+    "TexsmithUserDir",
+    "configure_user_dir",
+    "get_user_dir",
+    "set_user_dir",
+    "user_dir_context",
+]
+
+_USER_DIR: TexsmithUserDir | None = None
+_LOCK: RLock = RLock()
+
+
+def _resolve_root(root: str | Path | None) -> tuple[Path, bool]:
+    if root is not None:
+        return Path(root).expanduser(), True
+    env_root = os.environ.get("TEXSMITH_HOME")
+    if env_root:
+        return Path(env_root).expanduser(), True
+    return Path.home() / ".texsmith", False
+
+
+def _resolve_cache_root(
+    cache_root: str | Path | None,
+    *,
+    user_root: Path,
+    root_was_explicit: bool,
+) -> tuple[Path, bool]:
+    if cache_root is not None:
+        return Path(cache_root).expanduser(), True
+    env_cache = os.environ.get("TEXSMITH_CACHE_DIR")
+    if env_cache:
+        return Path(env_cache).expanduser(), True
+    xdg_cache = os.environ.get("XDG_CACHE_HOME")
+    if xdg_cache:
+        return Path(xdg_cache).expanduser() / "texsmith", True
+    if root_was_explicit:
+        return user_root / "cache", True
+    return Path.home() / ".cache" / "texsmith", False
+
+
+@dataclass(slots=True)
+class TexsmithUserDir:
+    """Resolved user and cache roots plus helpers to manage them."""
+
+    root: Path
+    cache_root: Path
+    root_is_explicit: bool = False
+    cache_is_explicit: bool = False
+
+    def data_dir(self, *parts: str | Path, create: bool = True) -> Path:
+        """Return a directory under the user root, creating it when requested."""
+        target = self.root.joinpath(*parts)
+        if create:
+            target.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def cache_dir(self, *parts: str | Path, create: bool = True) -> Path:
+        """Return a directory under the cache root, creating it when requested."""
+        target = self.cache_root.joinpath(*parts)
+        if create:
+            target.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def data_path(self, *parts: str | Path, create: bool = True) -> Path:
+        """Return a path under the user root, creating parent directories if needed."""
+        target = self.root.joinpath(*parts)
+        if create:
+            target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def cache_path(self, *parts: str | Path, create: bool = True) -> Path:
+        """Return a path under the cache root, creating parent directories if needed."""
+        target = self.cache_root.joinpath(*parts)
+        if create:
+            target.parent.mkdir(parents=True, exist_ok=True)
+        return target
+
+    def clear_cache(self, namespaces: Iterable[str] | None = None) -> list[Path]:
+        """Clear cached namespaces and return the list of removed paths."""
+        targets: list[Path] = []
+        if namespaces is None:
+            targets.append(self.cache_root)
+        else:
+            for name in namespaces:
+                targets.append(self.cache_root / name)
+                targets.append(self.root / name)
+
+        cleared: list[Path] = []
+        for path in targets:
+            if not path.exists():
+                continue
+            try:
+                shutil.rmtree(path)
+                cleared.append(path)
+            except OSError:
+                continue
+        return cleared
+
+
+def configure_user_dir(
+    *,
+    root: str | Path | None = None,
+    cache_root: str | Path | None = None,
+) -> TexsmithUserDir:
+    """Replace the global user dir singleton with a freshly resolved instance."""
+    user_root, root_was_explicit = _resolve_root(root)
+    resolved_cache_root, cache_was_explicit = _resolve_cache_root(
+        cache_root, user_root=user_root, root_was_explicit=root_was_explicit
+    )
+    return set_user_dir(
+        TexsmithUserDir(
+            root=user_root,
+            cache_root=resolved_cache_root,
+            root_is_explicit=root_was_explicit,
+            cache_is_explicit=cache_was_explicit,
+        )
+    )
+
+
+def get_user_dir() -> TexsmithUserDir:
+    """Return the lazily created user dir singleton."""
+    global _USER_DIR
+    with _LOCK:
+        if _USER_DIR is None:
+            _USER_DIR = configure_user_dir()
+            return _USER_DIR
+        current_root, root_was_explicit = _resolve_root(None)
+        current_cache_root, cache_was_explicit = _resolve_cache_root(
+            None, user_root=current_root, root_was_explicit=root_was_explicit
+        )
+        if (not _USER_DIR.root_is_explicit and _USER_DIR.root != current_root) or (
+            not _USER_DIR.cache_is_explicit and _USER_DIR.cache_root != current_cache_root
+        ):
+            _USER_DIR = TexsmithUserDir(
+                root=current_root,
+                cache_root=current_cache_root,
+                root_is_explicit=root_was_explicit,
+                cache_is_explicit=cache_was_explicit,
+            )
+        return _USER_DIR
+
+
+def set_user_dir(user_dir: TexsmithUserDir) -> TexsmithUserDir:
+    """Replace the current user dir singleton and return it."""
+    global _USER_DIR
+    with _LOCK:
+        _USER_DIR = user_dir
+        return _USER_DIR
+
+
+@contextmanager
+def user_dir_context(
+    *,
+    root: str | Path | None = None,
+    cache_root: str | Path | None = None,
+) -> Iterable[TexsmithUserDir]:
+    """Temporarily override the global user dir singleton."""
+    global _USER_DIR
+    with _LOCK:
+        previous = _USER_DIR
+    current = configure_user_dir(root=root, cache_root=cache_root)
+    try:
+        yield current
+    finally:
+        with _LOCK:
+            _USER_DIR = previous

texsmith/devtools.py

@@ -0,0 +1,28 @@
+"""Developer utilities for local workflows."""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+import subprocess
+import sys
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    """Run repository checks (currently proxies to ruff)."""
+    args = list(argv) if argv is not None else sys.argv[1:]
+    try:
+        pass
+    except Exception as exc:  # pragma: no cover - defensive message
+        sys.stderr.write("ruff is required to run checks; install dev dependencies.\n")
+        sys.stderr.write(f"Details: {exc}\n")
+        return 1
+
+    result = subprocess.run(
+        ["ruff", "check", *args],
+        check=False,
+    )
+    return result.returncode
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

texsmith/extensions/__init__.py

@@ -0,0 +1,162 @@
+"""Central registry for TeXSmith's bundled Markdown extensions."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Iterable
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any
+
+
+__all__ = [
+    "ExtensionSpec",
+    "available_extensions",
+    "get_extension_spec",
+    "load_markdown_extension",
+    "load_mkdocs_plugin",
+    "register_all_renderers",
+]
+
+
+def _load_attribute(path: str) -> Any:
+    module_name, _, attribute = path.partition(":")
+    if not module_name or not attribute:
+        msg = f"Extension entry point '{path}' must use the 'module:attribute' format."
+        raise ValueError(msg)
+    module = import_module(module_name)
+    target: Any = module
+    for chunk in attribute.split("."):
+        target = getattr(target, chunk)
+    return target
+
+
+def _normalise_slug(value: str) -> str:
+    slug = value.split(":", 1)[0].lower()
+    if slug.startswith("texsmith."):
+        return slug.removeprefix("texsmith.")
+    return slug
+
+
+@dataclass(frozen=True, slots=True)
+class ExtensionSpec:
+    """Describe how to import Markdown and renderer hooks for an extension."""
+
+    slug: str
+    markdown_entry: str
+    renderer_entry: str | None = None
+    mkdocs_entry: str | None = None
+    description: str | None = None
+
+    @property
+    def package_name(self) -> str:
+        return f"texsmith.{self.slug}"
+
+    def iter_entry_points(self) -> Iterable[str]:
+        """Yield configured entry points for documentation/debugging."""
+        yield self.markdown_entry
+        if self.renderer_entry:
+            yield self.renderer_entry
+        if self.mkdocs_entry:
+            yield self.mkdocs_entry
+
+
+_EXTENSIONS: dict[str, ExtensionSpec] = {
+    "index": ExtensionSpec(
+        slug="index",
+        markdown_entry="texsmith.index:TexsmithIndexExtension",
+        renderer_entry="texsmith.index:register_renderer",
+        mkdocs_entry="texsmith.index:IndexPlugin",
+        description="Inline hashtags converted into LaTeX index entries.",
+    ),
+    "texlogos": ExtensionSpec(
+        slug="texlogos",
+        markdown_entry="texsmith.texlogos:TexLogosExtension",
+        renderer_entry="texsmith.texlogos:register_renderer",
+        description="Semantic spans for TeX logos rendered in Markdown and LaTeX.",
+    ),
+    "smallcaps": ExtensionSpec(
+        slug="smallcaps",
+        markdown_entry="texsmith.smallcaps:SmallCapsExtension",
+        description="Maps '__text__' syntax to small caps spans.",
+    ),
+    "latex_raw": ExtensionSpec(
+        slug="latex_raw",
+        markdown_entry="texsmith.latex_raw:LatexRawExtension",
+        description="Fence supporting inline raw LaTeX payloads.",
+    ),
+    "rawlatex": ExtensionSpec(
+        slug="rawlatex",
+        markdown_entry="texsmith.rawlatex:RawLatexExtension",
+        description="Inline {latex}[...] markers and /// latex fences.",
+    ),
+    "latex_text": ExtensionSpec(
+        slug="latex_text",
+        markdown_entry="texsmith.latex_text:LatexTextExtension",
+        description="Styles the literal 'LaTeX' token with a dedicated span.",
+    ),
+    "smart_dashes": ExtensionSpec(
+        slug="smart_dashes",
+        markdown_entry="texsmith.smart_dashes:TexsmithSmartDashesExtension",
+        description="Converts '--' and '---' into typographic dashes outside code.",
+    ),
+    "missing_footnotes": ExtensionSpec(
+        slug="missing_footnotes",
+        markdown_entry="texsmith.missing_footnotes:MissingFootnotesExtension",
+        description="Warns about references to undefined footnotes.",
+    ),
+    "multi_citations": ExtensionSpec(
+        slug="multi_citations",
+        markdown_entry="texsmith.multi_citations:MultiCitationExtension",
+        description="Normalises '^[a,b]' inline citations before footnotes run.",
+    ),
+    "mermaid": ExtensionSpec(
+        slug="mermaid",
+        markdown_entry="texsmith.mermaid:MermaidExtension",
+        description="Inlines Mermaid diagrams referenced via Markdown images.",
+    ),
+    "progressbar": ExtensionSpec(
+        slug="progressbar",
+        markdown_entry="texsmith.progressbar:ProgressBarExtension",
+        renderer_entry="texsmith.progressbar:register_renderer",
+        description="Renders `[=50%]` progress blocks via the LaTeX progressbar package.",
+    ),
+}
+
+
+def available_extensions() -> list[ExtensionSpec]:
+    """Return the registered extension specs sorted by slug."""
+    return [_EXTENSIONS[key] for key in sorted(_EXTENSIONS)]
+
+
+def get_extension_spec(name: str) -> ExtensionSpec:
+    """Look up the runtime spec for a given extension slug or qualified name."""
+    slug = _normalise_slug(name)
+    try:
+        return _EXTENSIONS[slug]
+    except KeyError as exc:  # pragma: no cover - defensive
+        raise KeyError(f"No TeXSmith extension named '{name}'.") from exc
+
+
+def load_markdown_extension(name: str, **config: Any) -> Any:
+    """Instantiate a Python-Markdown extension by slug or qualified name."""
+    spec = get_extension_spec(name)
+    factory: Callable[..., Any] = _load_attribute(spec.markdown_entry)
+    return factory(**config)
+
+
+def register_all_renderers(renderer: object) -> None:
+    """Register every available renderer hook on the provided renderer."""
+    for spec in _EXTENSIONS.values():
+        if not spec.renderer_entry:
+            continue
+        register: Callable[[object], None] = _load_attribute(spec.renderer_entry)
+        register(renderer)
+
+
+def load_mkdocs_plugin(name: str) -> type[Any] | None:
+    """Return the MkDocs plugin class for an extension, if any."""
+    spec = get_extension_spec(name)
+    if not spec.mkdocs_entry:
+        return None
+    plugin_cls: type[Any] = _load_attribute(spec.mkdocs_entry)
+    return plugin_cls

texsmith/extensions/index/__init__.py

@@ -0,0 +1,21 @@
+"""Public entry points for TeXSmith's hashtag index extension."""
+
+from __future__ import annotations
+
+from .markdown import TexsmithIndexExtension, makeExtension
+from .registry import (
+    IndexEntry,
+    IndexRegistry,
+    clear_registry,
+    get_registry,
+)
+
+
+__all__ = [
+    "IndexEntry",
+    "IndexRegistry",
+    "TexsmithIndexExtension",
+    "clear_registry",
+    "get_registry",
+    "makeExtension",
+]

texsmith/extensions/index/markdown.py

@@ -0,0 +1,94 @@
+"""Markdown extension providing the ``#[term]`` hashtag syntax."""
+
+from __future__ import annotations
+
+import re
+from xml.etree import ElementTree
+
+from markdown import Markdown
+from markdown.extensions import Extension
+from markdown.inlinepatterns import InlineProcessor
+
+
+TAG_PATTERN = re.compile(r"\[([^\]]+)\]")
+STYLE_PATTERN = re.compile(r"\{([^}]+)\}")
+
+
+class _IndexInlineProcessor(InlineProcessor):
+    """Replace index syntax with tagged spans."""
+
+    def handleMatch(  # noqa: N802 - Markdown inline API requires camelCase
+        self,
+        match: re.Match[str],
+        data: str,
+    ) -> tuple[ElementTree.Element, int, int]:  # type: ignore[override]
+        del data
+        payload = match.group("payload")
+        registry = match.group("registry1")
+        style_token = match.group("style")
+
+        tags = _extract_tags(payload)
+        if not tags:
+            return None, match.start(0), match.end(0)
+
+        element = ElementTree.Element("span")
+        element.set("class", "ts-hashtag")
+        for index, tag in enumerate(tags):
+            key = "data-tag" if index == 0 else f"data-tag{index}"
+            element.set(key, tag)
+
+        normalised_style = _normalise_style(style_token)
+        if normalised_style:
+            element.set("data-style", normalised_style)
+
+        if registry:
+            element.set("data-registry", registry)
+
+        # The index marker is invisible in the output text
+        element.text = ""
+        return element, match.start(0), match.end(0)
+
+
+def _extract_tags(payload: str | None) -> list[str]:
+    if not payload:
+        return []
+    values = [part.strip() for part in TAG_PATTERN.findall(payload)]
+    return [value for value in values if value]
+
+
+def _normalise_style(style_token: str | None) -> str | None:
+    if not style_token:
+        return None
+    match = STYLE_PATTERN.search(style_token)
+    if not match:
+        return None
+    style = match.group(1).strip().lower()
+    if not style:
+        return None
+    if style == "ib":
+        style = "bi"
+    if style not in {"b", "i", "bi"}:
+        return None
+    return style
+
+
+class TexsmithIndexExtension(Extension):
+    """Register the inline index processor with Python-Markdown."""
+
+    def extendMarkdown(self, md: Markdown) -> None:  # noqa: N802
+        """Match modern and legacy index syntaxes and register the inline processor."""
+        pattern = (
+            r"(?<!\\)"
+            r"(?P<prefix>#|\{index(?::(?P<registry1>[^\]\{\(\s]+))?\}|%)"
+            r"(?P<payload>(?:\[[^\]]+\])+)"
+            r"(?P<style>\{[^}]+\})?"
+        )
+        processor = _IndexInlineProcessor(pattern, md)
+        md.inlinePatterns.register(processor, "texsmith_index", 180)
+
+
+def makeExtension(**kwargs: object) -> TexsmithIndexExtension:  # noqa: N802 - Markdown API hook; pragma: no cover
+    return TexsmithIndexExtension(**kwargs)
+
+
+__all__ = ["TexsmithIndexExtension", "makeExtension"]

texsmith/extensions/index/mkdocs_plugin.py

@@ -0,0 +1,136 @@
+"""MkDocs plugin injecting TeXSmith hashtag spans into the lunr search index."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from collections.abc import Iterable
+import json
+from pathlib import Path
+import re
+from typing import Any
+
+from mkdocs import plugins
+from mkdocs.config import config_options
+from mkdocs.config.defaults import MkDocsConfig
+from mkdocs.plugins import BasePlugin
+from mkdocs.structure.files import Files
+from mkdocs.structure.pages import Page
+
+
+RE_HEADERLINK = re.compile(r'<a\s+[^>]*headerlink[^>]*href="(#[^"]+)"[^>]*>')
+RE_HASHTAG = re.compile(r"<span\s+[^>]*class=\"[^\"]*ts-(?:hashtag|index)[^\"]*\"[^>]*>")
+RE_DATA_TAG = re.compile(r"data-tag\d*=\"([^\"]+)\"")
+
+
+def _expand_search_terms(tags: Iterable[str]) -> list[str]:
+    """Return a list of search tokens derived from the hierarchy of tags."""
+    tokens: list[str] = []
+    collected: set[str] = set()
+    hierarchy: list[str] = []
+    for tag in tags:
+        hierarchy.append(tag)
+        direct = tag.strip()
+        if direct and direct not in collected:
+            collected.add(direct)
+            tokens.append(direct)
+        composite = "::".join(hierarchy)
+        if composite not in collected:
+            collected.add(composite)
+            tokens.append(composite)
+    return tokens
+
+
+def _extract_tags(fragment: str) -> list[str]:
+    return [value.strip() for value in RE_DATA_TAG.findall(fragment) if value.strip()]
+
+
+class IndexPlugin(BasePlugin):
+    """Collect hashtag spans and inject their tags into MkDocs search."""
+
+    config_scheme = (("inject_markdown_extension", config_options.Type(bool, default=True)),)
+
+    def __init__(self) -> None:
+        self._collected: dict[str, set[tuple[str, ...]]] = defaultdict(set)
+
+    def on_config(self, config: MkDocsConfig) -> MkDocsConfig:
+        """Optionally enable the markdown extension automatically."""
+        self._collected.clear()
+        if self.config.get("inject_markdown_extension", True):
+            extension = "texsmith.index:TexsmithIndexExtension"
+            extensions = list(config.markdown_extensions or [])
+            if extension not in extensions:
+                extensions.append(extension)
+                config.markdown_extensions = extensions
+        return config
+
+    def on_page_content(
+        self,
+        html: str,
+        page: Page,
+        config: MkDocsConfig,
+        files: Files,
+    ) -> str:
+        """Collect tags per page (and optionally per section heading)."""
+        del config, files
+        base = page.url or ""
+        anchor = ""
+        heading_count = 0
+
+        for line in html.split("\n"):
+            if header := RE_HEADERLINK.search(line):
+                anchor = header.group(1)
+                heading_count += 1
+
+            for match in RE_HASHTAG.findall(line):
+                tags = _extract_tags(match)
+                if not tags:
+                    continue
+                location = f"{base}{anchor}" if anchor and heading_count > 1 else base
+                self._collected[location].add(tuple(tags))
+
+        return html
+
+    @plugins.event_priority(-100)
+    def on_post_build(self, config: MkDocsConfig) -> None:
+        """Inject gathered tags into the lunr search index."""
+        if not self._collected:
+            return
+
+        search_dir = Path(config.site_dir) / "search"
+        index_path = search_dir / "search_index.json"
+        if not index_path.exists():
+            return
+
+        data: dict[str, Any]
+        with index_path.open("r", encoding="utf-8") as handle:
+            data = json.load(handle)
+
+        docs = data.get("docs")
+        if not isinstance(docs, list):
+            return
+
+        for entry in docs:
+            location = entry.get("location")
+            if not isinstance(location, str):
+                continue
+            tag_sets = self._collected.get(location)
+            if not tag_sets:
+                continue
+            existing = entry.setdefault("tags", [])
+            if not isinstance(existing, list):
+                continue
+            payload: list[str] = []
+            seen: set[str] = set(map(str, existing))
+            for tags in sorted(tag_sets):
+                for token in _expand_search_terms(tags):
+                    if token not in seen:
+                        seen.add(token)
+                        payload.append(token)
+            if payload:
+                existing.extend(payload)
+
+        with index_path.open("w", encoding="utf-8") as handle:
+            json.dump(data, handle)
+
+
+__all__ = ["IndexPlugin"]

texsmith/extensions/index/registry.py

@@ -0,0 +1,57 @@
+"""Global registry tracking hashtag-index entries across documents."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Iterator
+from dataclasses import dataclass, field
+from threading import Lock
+
+
+IndexEntry = tuple[str, ...]
+
+
+@dataclass(slots=True)
+class IndexRegistry:
+    """Thread-safe container gathering index entries encountered during rendering."""
+
+    _entries: set[IndexEntry] = field(default_factory=set)
+    _lock: Lock = field(default_factory=Lock)
+
+    def add(self, entry: Iterable[str]) -> None:
+        """Record a tuple describing an index entry."""
+        values = tuple(part for part in entry if part)
+        if not values:
+            return
+        with self._lock:
+            self._entries.add(values)
+
+    def clear(self) -> None:
+        """Reset the registry to its initial empty state."""
+        with self._lock:
+            self._entries.clear()
+
+    def __len__(self) -> int:  # pragma: no cover - trivial
+        with self._lock:
+            return len(self._entries)
+
+    def __iter__(self) -> Iterator[IndexEntry]:  # pragma: no cover - simple proxy
+        with self._lock:
+            yield from sorted(self._entries)
+
+    def snapshot(self) -> set[IndexEntry]:
+        """Return a shallow copy of the registered entries."""
+        with self._lock:
+            return set(self._entries)
+
+
+_REGISTRY = IndexRegistry()
+
+
+def get_registry() -> IndexRegistry:
+    """Return the global index registry."""
+    return _REGISTRY
+
+
+def clear_registry() -> None:
+    """Convenience helper to wipe the global registry."""
+    _REGISTRY.clear()