codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/resume/tex_parser.py

@@ -0,0 +1,394 @@
+"""Parse a LaTeX resume into structured sections, entries, and bullets.
+
+Default configuration matches the ``twocolentry`` / ``onecolentry`` /
+``highlights`` template family (the "rendercv"-style layout). Override
+``TexParserConfig`` to handle other templates.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+
+_TILDE_SENTINEL = "\x00TILDE\x00"
+
+
+@dataclass(frozen=True)
+class TexParserConfig:
+    """Environment names the parser looks for. Override for a different template."""
+
+    heading_env: str = "twocolentry"
+    content_env: str = "onecolentry"
+    bullet_env: str = "highlights"
+
+
+@dataclass(frozen=True)
+class ResumeBullet:
+    text: str
+    raw_tex: str
+
+
+@dataclass(frozen=True)
+class ResumeEntry:
+    heading: str
+    date: str
+    bullets: list[ResumeBullet]
+    heading_raw: str = ""  # raw TeX of the heading/content line, when known
+
+
+@dataclass
+class ParsedResume:
+    name: str
+    sections: list[ResumeSection] = field(default_factory=list)
+
+    @property
+    def all_bullets(self) -> list[tuple[str, str, ResumeBullet]]:
+        """(section_name, entry_heading, bullet) for every bullet."""
+        out: list[tuple[str, str, ResumeBullet]] = []
+        for sec in self.sections:
+            for entry in sec.entries:
+                for b in entry.bullets:
+                    out.append((sec.name, entry.heading, b))
+        return out
+
+    @property
+    def all_items(self) -> list[tuple[str, str, ResumeBullet]]:
+        """Like ``all_bullets`` but also yields heading-only entries.
+
+        Entries without bullets (common in Skills, Certifications, Education)
+        produce a synthetic bullet from the heading text so the claim
+        extractor can process every line of the resume.
+        """
+        out: list[tuple[str, str, ResumeBullet]] = []
+        for sec in self.sections:
+            for entry in sec.entries:
+                if entry.bullets:
+                    for b in entry.bullets:
+                        out.append((sec.name, entry.heading, b))
+                elif entry.heading:
+                    out.append(
+                        (
+                            sec.name,
+                            entry.heading,
+                            ResumeBullet(
+                                text=entry.heading,
+                                raw_tex=entry.heading_raw or entry.heading,
+                            ),
+                        )
+                    )
+        return out
+
+
+@dataclass(frozen=True)
+class ResumeSection:
+    name: str
+    entries: list[ResumeEntry]
+
+
+# ---------------------------------------------------------------------------
+# LaTeX cleaning
+# ---------------------------------------------------------------------------
+
+
+def clean_tex(text: str) -> str:
+    """Strip LaTeX formatting, returning readable plain text."""
+    s = text
+
+    # 1. Protect \(\sim\) → tilde (must happen before ~ → space)
+    s = s.replace("\\(\\sim\\)", _TILDE_SENTINEL)
+
+    # 2. Literal character escapes
+    s = s.replace("\\%", "%")
+    s = s.replace("\\_", "_")
+    s = s.replace("\\&", "&")
+    s = s.replace("\\$", "$")
+    s = s.replace("\\#", "#")
+    s = s.replace("\\textbar", "|")
+
+    # 3. Line breaks (\\, \\[3pt])
+    s = re.sub(r"\\\\(?:\[[^\]]*\])?", " ", s)
+
+    # 4. Spacing commands → space
+    s = re.sub(r"\\(?:enspace|quad|qquad|hfill|vfill)\b", " ", s)
+    s = re.sub(r"\\[,;!]", " ", s)
+    s = s.replace("~", " ")
+
+    # 5. Remove icon commands
+    s = re.sub(r"\\faIcon\{[^}]*\}", "", s)
+
+    # 6. Remove sizing / spacing with arguments
+    s = re.sub(r"\\(?:vspace|hspace)\{[^}]*\}", "", s)
+    s = re.sub(r"\\fontsize\{[^}]*\}\{[^}]*\}", "", s)
+    s = re.sub(r"\\selectfont", "", s)
+    s = re.sub(r"\\(?:par|kern)\\?[a-z]*", "", s)
+
+    # 7. \href{url}{text} → text (text arg may have 2 levels of nesting)
+    _NESTED2 = r"[^{}]*(?:\{[^{}]*(?:\{[^{}]*\}[^{}]*)?\}[^{}]*)*"
+    for _ in range(3):
+        prev = s
+        s = re.sub(
+            r"\\(?:href|hrefWithoutArrow)\{[^}]*\}\{(" + _NESTED2 + r")\}",
+            r"\1",
+            s,
+        )
+        if s == prev:
+            break
+
+    # 8. \textcolor{color}{text} → text (iterate for nesting)
+    for _ in range(5):
+        prev = s
+        s = re.sub(r"\\textcolor\{[^{}]*\}\{(" + _NESTED2 + r")\}", r"\1", s)
+        if s == prev:
+            break
+
+    # 9. \textbf / \textit / \texttt / … → text (iterate for nesting)
+    for _ in range(5):
+        prev = s
+        s = re.sub(
+            r"\\text(?:bf|it|tt|sc|rm|sf)\{(" + _NESTED2 + r")\}",
+            r"\1",
+            s,
+        )
+        if s == prev:
+            break
+
+    # 10. Font switches: {\small text}, {\bf text}
+    s = re.sub(
+        r"\{\\(?:small|bf|it|tt|sc|em|rm|sf|bfseries|itshape)\s+([^}]*)\}",
+        r"\1",
+        s,
+    )
+    s = re.sub(
+        r"\\(?:small|large|Large|LARGE|normalsize|footnotesize|tiny"
+        r"|scriptsize|bfseries|itshape|centering|raggedright|raggedleft)\b",
+        "",
+        s,
+    )
+    s = re.sub(r"\\linespread\{[^}]*\}", "", s)
+
+    # 11. Inline math: $…$ → content
+    s = re.sub(r"\$([^$]*)\$", r"\1", s)
+    s = re.sub(r"\\vcenter\{\\hbox\{([^}]*)\}\}", r"\1", s)
+
+    # 12. Strip remaining braces
+    s = s.replace("{", "").replace("}", "")
+
+    # 13. Restore tilde sentinel
+    s = s.replace(_TILDE_SENTINEL, "~")
+
+    # 14. En-dash cleanup: -- → –
+    s = s.replace("--", "–")
+
+    # 15. Collapse whitespace
+    s = re.sub(r"[ \t]+", " ", s)
+    s = s.strip()
+
+    return s
+
+
+# ---------------------------------------------------------------------------
+# Low-level helpers
+# ---------------------------------------------------------------------------
+
+
+def _find_brace_group(text: str, start: int) -> tuple[str, int]:
+    """Return (content, end_index) for the brace group starting at *start*."""
+    if start >= len(text) or text[start] != "{":
+        return "", start
+    depth = 0
+    i = start
+    while i < len(text):
+        if text[i] == "{":
+            depth += 1
+        elif text[i] == "}":
+            depth -= 1
+            if depth == 0:
+                return text[start + 1 : i], i + 1
+        i += 1
+    return text[start + 1 :], len(text)
+
+
+def _extract_items(highlights_text: str) -> list[ResumeBullet]:
+    """Split ``\\item`` entries from a highlights block."""
+    parts = re.split(r"\\item\s+", highlights_text)
+    bullets: list[ResumeBullet] = []
+    for raw in parts:
+        raw = raw.strip()
+        if not raw:
+            continue
+        cleaned = clean_tex(raw)
+        if cleaned:
+            bullets.append(ResumeBullet(text=cleaned, raw_tex=raw))
+    return bullets
+
+
+# ---------------------------------------------------------------------------
+# Section splitting
+# ---------------------------------------------------------------------------
+
+_SECTION_RE = re.compile(r"\\section\{", re.DOTALL)
+
+
+def _split_sections(body: str) -> list[tuple[str, str]]:
+    """Return (section_name, section_body_text) pairs."""
+    hits = list(_SECTION_RE.finditer(body))
+    if not hits:
+        return []
+
+    sections: list[tuple[str, str]] = []
+    for idx, m in enumerate(hits):
+        name_raw, after = _find_brace_group(body, m.start() + len("\\section"))
+        name = clean_tex(name_raw)
+        end = hits[idx + 1].start() if idx + 1 < len(hits) else len(body)
+        sections.append((name, body[after:end]))
+    return sections
+
+
+# ---------------------------------------------------------------------------
+# Entry parsing within a section
+# ---------------------------------------------------------------------------
+
+
+def _parse_section_content(text: str, cfg: TexParserConfig) -> list[ResumeEntry]:
+    entries: list[ResumeEntry] = []
+    pos = 0
+
+    h_tag = f"\\begin{{{cfg.heading_env}}}"
+    h_end_tag = f"\\end{{{cfg.heading_env}}}"
+    c_tag = f"\\begin{{{cfg.content_env}}}"
+    c_end_tag = f"\\end{{{cfg.content_env}}}"
+    b_tag = f"\\begin{{{cfg.bullet_env}}}"
+    b_end_tag = f"\\end{{{cfg.bullet_env}}}"
+
+    while pos < len(text):
+        h_pos = text.find(h_tag, pos)
+        c_pos = text.find(c_tag, pos)
+
+        if h_pos == -1 and c_pos == -1:
+            break
+
+        if h_pos != -1 and (c_pos == -1 or h_pos < c_pos):
+            # --- heading entry (twocolentry) ---
+            brace = text.find("{", h_pos + len(h_tag))
+            if brace == -1:
+                pos = h_pos + len(h_tag)
+                continue
+            date_raw, after_brace = _find_brace_group(text, brace)
+
+            end_marker = text.find(h_end_tag, after_brace)
+            if end_marker == -1:
+                pos = after_brace
+                continue
+            heading_raw = text[after_brace:end_marker].strip()
+            pos = end_marker + len(h_end_tag)
+
+            # look for a following content env (skip whitespace / vspace)
+            bullets: list[ResumeBullet] = []
+            rest = text[pos:]
+            stripped = re.sub(r"^[\s]*(?:\\vspace\{[^}]*\}[\s]*)*", "", rest)
+            offset = len(rest) - len(stripped)
+
+            if stripped.startswith(c_tag):
+                c_start = pos + offset
+                c_end = text.find(c_end_tag, c_start)
+                if c_end != -1:
+                    inner = text[c_start + len(c_tag) : c_end]
+                    hl_start = inner.find(b_tag)
+                    if hl_start != -1:
+                        hl_end = inner.find(b_end_tag, hl_start)
+                        if hl_end != -1:
+                            bullets = _extract_items(
+                                inner[hl_start + len(b_tag) : hl_end]
+                            )
+                    else:
+                        cleaned = clean_tex(inner.strip())
+                        if cleaned:
+                            bullets = [
+                                ResumeBullet(text=cleaned, raw_tex=inner.strip())
+                            ]
+                    pos = c_end + len(c_end_tag)
+
+            entries.append(
+                ResumeEntry(
+                    heading=clean_tex(heading_raw),
+                    date=clean_tex(date_raw),
+                    bullets=bullets,
+                )
+            )
+
+        else:
+            # --- standalone content env (skills, certs without heading) ---
+            c_end = text.find(c_end_tag, c_pos)
+            if c_end == -1:
+                pos = c_pos + len(c_tag)
+                continue
+            inner = text[c_pos + len(c_tag) : c_end]
+
+            hl_start = inner.find(b_tag)
+            if hl_start != -1:
+                hl_end = inner.find(b_end_tag, hl_start)
+                if hl_end != -1:
+                    bullets = _extract_items(inner[hl_start + len(b_tag) : hl_end])
+                    entries.append(ResumeEntry(heading="", date="", bullets=bullets))
+            else:
+                cleaned = clean_tex(inner.strip())
+                if cleaned:
+                    entries.append(
+                        ResumeEntry(
+                            heading=cleaned,
+                            date="",
+                            bullets=[],
+                            heading_raw=inner.strip(),
+                        )
+                    )
+
+            pos = c_end + len(c_end_tag)
+
+    return entries
+
+
+# ---------------------------------------------------------------------------
+# Name extraction
+# ---------------------------------------------------------------------------
+
+
+def _extract_name(body: str) -> str:
+    m = re.search(r"\\textbf\{\\textcolor\{[^}]*\}\{([^}]*)\}\}", body)
+    if m:
+        return m.group(1).strip()
+    header_m = re.search(r"\\begin\{header\}(.*?)\\end\{header\}", body, re.DOTALL)
+    if header_m:
+        bf = re.search(r"\\textbf\{([^}]*)\}", header_m.group(1))
+        if bf:
+            return clean_tex(bf.group(1))
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def parse_resume(
+    tex_source: str, config: TexParserConfig | None = None
+) -> ParsedResume:
+    """Parse a LaTeX resume source into a structured ``ParsedResume``."""
+    cfg = config or TexParserConfig()
+
+    doc = re.search(r"\\begin\{document\}(.*?)\\end\{document\}", tex_source, re.DOTALL)
+    body = doc.group(1) if doc else tex_source
+
+    name = _extract_name(body)
+    sections: list[ResumeSection] = []
+    for sec_name, sec_text in _split_sections(body):
+        entries = _parse_section_content(sec_text, cfg)
+        if entries:
+            sections.append(ResumeSection(name=sec_name, entries=entries))
+
+    return ParsedResume(name=name, sections=sections)
+
+
+def parse_file(path: Path, config: TexParserConfig | None = None) -> ParsedResume:
+    """Read a ``.tex`` file and parse it."""
+    return parse_resume(path.read_text(encoding="utf-8"), config)

receipts/rewrite/compiler.py

@@ -0,0 +1,180 @@
+"""Compile a .tex file to PDF if a TeX toolchain is available."""
+
+from __future__ import annotations
+
+import os
+import shutil
+import subprocess
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class CompileResult:
+    success: bool
+    pdf_path: Path | None
+    tool_used: str | None
+    error: str | None
+
+
+# Well-known per-platform binary locations that may not be on PATH yet
+# (e.g. MiKTeX installs to AppData on Windows; MacTeX to /Library).
+_EXTRA_SEARCH_PATHS: list[str] = []
+
+if sys.platform == "win32":
+    _local = os.environ.get("LOCALAPPDATA", "")
+    _program_files = os.environ.get("ProgramFiles", "C:\\Program Files")
+    _EXTRA_SEARCH_PATHS = [
+        os.path.join(_local, "Programs", "MiKTeX", "miktex", "bin", "x64"),
+        os.path.join(_program_files, "MiKTeX", "miktex", "bin", "x64"),
+        os.path.join(_program_files, "MiKTeX 2.9", "miktex", "bin", "x64"),
+    ]
+elif sys.platform == "darwin":
+    _EXTRA_SEARCH_PATHS = [
+        "/Library/TeX/texbin",
+        "/usr/local/texlive/2024/bin/universal-darwin",
+        "/usr/local/texlive/2023/bin/universal-darwin",
+    ]
+
+
+def _which_extended(cmd: str) -> str | None:
+    """Like shutil.which but also searches known TeX install locations."""
+    found = shutil.which(cmd)
+    if found:
+        return found
+    exe = cmd if sys.platform != "win32" else cmd + ".exe"
+    for extra in _EXTRA_SEARCH_PATHS:
+        candidate = os.path.join(extra, exe)
+        if os.path.isfile(candidate):
+            return candidate
+    return None
+
+
+def find_tex_compiler() -> str | None:
+    """Return the NAME of the first available TeX compiler, or None.
+
+    Preference order is platform-aware: on Windows latexmk needs Perl (rarely
+    installed), so pdflatex leads; on Unix latexmk leads. Searches PATH plus
+    known install locations (MiKTeX on Windows, MacTeX on macOS).
+    """
+    # On Windows latexmk requires Perl which is rarely installed; prefer
+    # pdflatex directly and fall back to latexmk only on Unix where Perl ships.
+    if sys.platform == "win32":
+        order = ("pdflatex", "xelatex", "lualatex", "latexmk", "tectonic")
+    else:
+        order = ("latexmk", "pdflatex", "xelatex", "lualatex", "tectonic")
+    for cmd in order:
+        if _which_extended(cmd):
+            return cmd
+    return None
+
+
+def compile_tex(tex_path: Path, *, compiler: str | None = None) -> CompileResult:
+    """Compile a .tex file to PDF.
+
+    Returns a CompileResult with the PDF path on success, or a descriptive
+    error message on failure. Checks for the PDF by path (not exit code) so
+    MiKTeX's non-zero-on-warning behaviour doesn't cause false negatives.
+    """
+    if compiler is None:
+        compiler = find_tex_compiler()
+
+    if compiler is None:
+        return CompileResult(
+            success=False,
+            pdf_path=None,
+            tool_used=None,
+            error=(
+                "No TeX compiler found. Install one of:\n"
+                "  • MiKTeX (Windows): https://miktex.org/download\n"
+                "  • MacTeX  (macOS):  https://www.tug.org/mactex/\n"
+                "  • TeX Live (Linux): sudo apt install texlive-full\n"
+                "  • tectonic (any):   https://tectonic-typesetting.github.io\n"
+                "Or paste your .tex into https://overleaf.com to compile online."
+            ),
+        )
+
+    # Resolve the compiler to a full path (may live off PATH, e.g. MiKTeX).
+    compiler_path = _which_extended(compiler)
+    if compiler_path is None:
+        return CompileResult(
+            success=False,
+            pdf_path=None,
+            tool_used=compiler,
+            error=f"{compiler} not found in PATH.",
+        )
+
+    tex_dir = tex_path.parent
+
+    if compiler == "latexmk":
+        cmd = [
+            compiler_path,
+            "-pdf",
+            "-interaction=nonstopmode",
+            "-output-directory=" + str(tex_dir),
+            str(tex_path),
+        ]
+    elif compiler == "tectonic":
+        cmd = [compiler_path, "--outdir", str(tex_dir), str(tex_path)]
+    else:
+        # pdflatex / xelatex / lualatex
+        cmd = [
+            compiler_path,
+            "-interaction=nonstopmode",
+            f"-output-directory={tex_dir}",
+            str(tex_path),
+        ]
+
+    try:
+        result = subprocess.run(
+            cmd,
+            capture_output=True,
+            text=True,
+            timeout=120,
+            cwd=tex_dir,
+        )
+    except FileNotFoundError:
+        return CompileResult(
+            success=False,
+            pdf_path=None,
+            tool_used=compiler,
+            error=f"{compiler} disappeared from PATH mid-run.",
+        )
+    except subprocess.TimeoutExpired:
+        return CompileResult(
+            success=False,
+            pdf_path=None,
+            tool_used=compiler,
+            error=f"{compiler} timed out after 120 seconds.",
+        )
+
+    pdf_path = tex_path.with_suffix(".pdf")
+
+    # Check the file — MiKTeX exits non-zero even on success (update nag).
+    if pdf_path.exists():
+        return CompileResult(
+            success=True,
+            pdf_path=pdf_path,
+            tool_used=compiler,
+            error=None,
+        )
+
+    # Pull the most useful tail of output for the error message.
+    combined = (result.stderr or "") + (result.stdout or "")
+    # Strip the MiKTeX update nag — it's not an error.
+    lines = [
+        ln
+        for ln in combined.splitlines()
+        if "check for MiKTeX updates" not in ln and "major issue" not in ln
+    ]
+    error_text = "\n".join(lines[-20:]) or (
+        f"{compiler} exited with code {result.returncode}"
+    )
+
+    return CompileResult(
+        success=False,
+        pdf_path=None,
+        tool_used=compiler,
+        error=error_text,
+    )