paperkit 0.1.0__py3-none-any.whl

paperkit/pages.py

@@ -0,0 +1,254 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Page-count analysis from PDF + aux file.
+
+Extracts:
+  * total pages       - via pdfinfo
+  * refs start page   - from .aux TOC entries ("References"/"Bibliography"),
+                        falling back to a pdftotext heading scan
+  * ack  start page   - same, matching "Acknowledg..."
+  * before refs/ack   - pages occupied by the content preceding each section
+                        (a section starting mid-page counts that page)
+
+Patterns are configurable for non-English papers. Page limits in
+[page_limits] flip the check to ERROR when exceeded.
+
+Page numbers are the same in single- and double-column layouts (a page is a
+page), so this module needs no layout awareness.
+"""
+
+import re
+import shutil
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass
+class PageStats:
+    total: int | None = None
+    refs_page: int | None = None
+    ack_page: int | None = None
+    # Number of pages occupied by the content preceding each section. By
+    # default refs and ack form one exempt tail, so both hold the pages before
+    # whichever comes first: content of one exempt section must not count
+    # against the other's limit. With ack_counts_as_content the tail is the
+    # references alone, and before_ack becomes the pages before the
+    # acknowledgments. The page is counted when the section starts mid-page.
+    before_refs: int | None = None
+    before_ack: int | None = None
+
+
+# Matches \@writefile{toc}{\contentsline {section}{TITLE}{PAGE}{ANCHOR}...}
+# where TITLE may contain balanced nested braces. We pull TITLE with a manual
+# brace scanner since regex can't track arbitrary nesting.
+_TOC_PREFIX = r"\@writefile{toc}{\contentsline {section}{"
+
+
+def _parse_toc_line(line: str) -> tuple[str, int] | None:
+    """Return (raw_title, page) from one \\@writefile{toc} section line."""
+    line = line.lstrip()
+    if not line.startswith(_TOC_PREFIX):
+        return None
+    rest = line[len(_TOC_PREFIX) :]
+
+    # Scan balanced braces for the title.
+    depth = 1
+    i = 0
+    while i < len(rest) and depth > 0:
+        c = rest[i]
+        if c == "{":
+            depth += 1
+        elif c == "}":
+            depth -= 1
+            if depth == 0:
+                break
+        i += 1
+    if depth != 0 or i >= len(rest):
+        return None
+    title = rest[:i]
+    rest = rest[i + 1 :]
+
+    # Expect {PAGE}
+    if not rest.startswith("{"):
+        return None
+    page_end = rest.find("}", 1)
+    if page_end < 0:
+        return None
+    page_str = rest[1:page_end].strip()
+    try:
+        return title, int(page_str)
+    except ValueError:
+        return None  # roman numerals or odd page anchors: skip
+
+
+def _clean_title(title: str) -> str:
+    """Strip \\numberline{...}, \\mbox{...}, and other LaTeX command wrappers."""
+    # \numberline {X} or \numberline{X}
+    title = re.sub(r"\\numberline\s*\{[^{}]*\}", "", title)
+    # Drop \mbox{...} wrappers around section numbers
+    title = re.sub(r"\\mbox\s*\{([^{}]*)\}", r"\1", title)
+    # Drop single-arg \cmd{content} wrappers, keep content
+    for _ in range(3):
+        title = re.sub(r"\\[a-zA-Z]+\s*\{([^{}]*)\}", r"\1", title)
+    # Remove remaining lone commands
+    title = re.sub(r"\\[a-zA-Z@]+", "", title)
+    return title.replace("{", "").replace("}", "").strip()
+
+
+def parse_toc(aux_path: Path) -> list[tuple[str, int]]:
+    """Read .aux and return [(cleaned_title, page)] in document order."""
+    if not aux_path.is_file():
+        return []
+    out: list[tuple[str, int]] = []
+    for line in aux_path.read_text(errors="replace").splitlines():
+        parsed = _parse_toc_line(line)
+        if parsed is None:
+            continue
+        title, page = parsed
+        out.append((_clean_title(title), page))
+    return out
+
+
+def find_section_page(toc: list[tuple[str, int]], pattern: str) -> int | None:
+    """First TOC entry whose title matches *pattern* (used with re.search)."""
+    rx = re.compile(pattern)
+    for title, page in toc:
+        if rx.search(title):
+            return page
+    return None
+
+
+def _pdf_text_pages(pdf_path: Path) -> list[str] | None:
+    """Extract per-page text via pdftotext (pages are form-feed separated)."""
+    if not pdf_path.is_file() or shutil.which("pdftotext") is None:
+        return None
+    proc = subprocess.run(
+        ["pdftotext", str(pdf_path), "-"],
+        capture_output=True,
+        text=True,
+    )
+    if proc.returncode != 0:
+        return None
+    return proc.stdout.split("\f")
+
+
+def _is_heading_line(line: str, rx: re.Pattern[str]) -> bool:
+    """True if *line* looks like a standalone section heading matching *rx*.
+
+    Headings render as short lines; small-caps fonts may introduce spurious
+    spaces ("R EFERENCES"), so we also match with spaces stripped.
+    """
+    line = line.strip()
+    if not 0 < len(line) < 30:
+        return False
+    return bool(rx.search(line) or rx.search(line.replace(" ", "")))
+
+
+def find_heading_pos(pages_text: list[str], pattern: str) -> tuple[int, int] | None:
+    """Locate *pattern* as a standalone heading line in the rendered PDF text.
+
+    Returns (page_num, line_index) of the first match, or None. Also serves
+    as fallback detection for sections that don't write to \\@writefile{toc},
+    such as IEEEtran's `\\section*{Acknowledgment}`.
+    """
+    rx = re.compile(pattern)
+    for page_num, page_text in enumerate(pages_text, start=1):
+        for line_idx, raw_line in enumerate(page_text.splitlines()):
+            if _is_heading_line(raw_line, rx):
+                return page_num, line_idx
+    return None
+
+
+def body_end_page(pages_text: list[str], heading_pos: tuple[int, int]) -> int:
+    """Page on which the body content preceding *heading_pos* ends.
+
+    If the heading sits at the top of its page (nothing but a running header
+    or page number above it), the body ended on the previous page; otherwise
+    it shares the heading's page. In double-column layouts pdftotext emits
+    text in reading order, so a heading at the top of the second column is
+    correctly preceded by first-column body text.
+    """
+    page, line_idx = heading_pos
+    lines = pages_text[page - 1].splitlines()[:line_idx]
+    preceding = sum(1 for raw_line in lines if raw_line.strip())
+    # Tolerate a few short lines above the heading (running header, page number).
+    return page if preceding > 2 else page - 1
+
+
+def get_total_pages(pdf_path: Path) -> int | None:
+    """Return total PDF pages via pdfinfo, or None if it can't be read."""
+    if not pdf_path.is_file() or shutil.which("pdfinfo") is None:
+        return None
+    proc = subprocess.run(["pdfinfo", str(pdf_path)], capture_output=True, text=True)
+    for line in proc.stdout.splitlines():
+        if line.startswith("Pages:"):
+            try:
+                return int(line.split(":", 1)[1].strip())
+            except ValueError:
+                return None
+    return None
+
+
+def content_end_pages(
+    pages_text: list[str],
+    refs_pos: tuple[int, int] | None,
+    ack_pos: tuple[int, int] | None,
+    ack_counts_as_content: bool = False,
+) -> tuple[int | None, int | None]:
+    """Pages occupied by the content before the references and before the acks.
+
+    By default the two sections form one exempt tail: both values are the
+    pages before whichever heading comes first, so acknowledgments sitting
+    between the body and the references do not count against either limit.
+
+    With *ack_counts_as_content* only the references are exempt, as at venues
+    that count acknowledgments as text: the page budget then ends at the
+    references heading, and the acknowledgments fall inside it.
+    """
+    if ack_counts_as_content:
+        before_refs = body_end_page(pages_text, refs_pos) if refs_pos else None
+        before_ack = body_end_page(pages_text, ack_pos) if ack_pos else None
+        return before_refs, before_ack
+
+    positions = [pos for pos in (refs_pos, ack_pos) if pos is not None]
+    if not positions:
+        return None, None
+    end = body_end_page(pages_text, min(positions))
+    return (end if refs_pos else None), (end if ack_pos else None)
+
+
+def gather(
+    pdf_path: Path | None,
+    aux_path: Path | None,
+    refs_pattern: str,
+    ack_pattern: str,
+    ack_counts_as_content: bool = False,
+) -> PageStats:
+    """Collect all page stats; missing inputs leave fields as None."""
+    stats = PageStats()
+    pages_text: list[str] | None = None
+    if pdf_path is not None:
+        stats.total = get_total_pages(pdf_path)
+        pages_text = _pdf_text_pages(pdf_path)
+    if aux_path is not None:
+        toc = parse_toc(aux_path)
+        stats.refs_page = find_section_page(toc, refs_pattern)
+        stats.ack_page = find_section_page(toc, ack_pattern)
+    if pages_text:
+        refs_pos = find_heading_pos(pages_text, refs_pattern)
+        ack_pos = find_heading_pos(pages_text, ack_pattern)
+        # Fallback for sections missing from the TOC (e.g. IEEEtran's
+        # `\section*{Acknowledgment}` doesn't emit `\@writefile{toc}`).
+        if stats.refs_page is None and refs_pos is not None:
+            stats.refs_page = refs_pos[0]
+        if stats.ack_page is None and ack_pos is not None:
+            stats.ack_page = ack_pos[0]
+        stats.before_refs, stats.before_ack = content_end_pages(
+            pages_text,
+            refs_pos,
+            ack_pos,
+            ack_counts_as_content,
+        )
+    return stats

paperkit/profiles/__init__.py

@@ -0,0 +1,56 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Profile registry and base class."""
+
+from paperkit.config import PaperkitConfig
+
+
+class BaseProfile:
+    """Base profile with sensible defaults."""
+
+    def docker_packages(self) -> list[str]:
+        """Extra packages beyond the base set (see docker._BASE_PACKAGES)."""
+        return []
+
+    # Reordering arguments, dropped when sorting is off.
+    SORT_ARGS = ("--sort=key", "--sort-fields")
+
+    def bibtex_tidy_args(self, sort: bool = True) -> list[str]:
+        """Arguments for bibtex-tidy; *sort* also reorders entries and fields."""
+        args = [
+            "--curly",
+            "--blank-lines",
+            "--sort=key",
+            "--duplicates=key,doi,citation",
+            "--no-escape",
+            "--sort-fields",
+            "--trailing-commas",
+            "--remove-empty-fields",
+            "--enclosing-braces=title",
+            "--align=13",
+        ]
+        return args if sort else [a for a in args if a not in self.SORT_ARGS]
+
+    def bibtex_tidy_version(self) -> str:
+        return "1.14.0"
+
+
+_PROFILES: dict[str, type[BaseProfile]] = {}
+
+
+def register_profile(name: str, cls: type[BaseProfile]) -> None:
+    _PROFILES[name] = cls
+
+
+def get_profile(config: PaperkitConfig) -> BaseProfile:
+    cls = _PROFILES.get(config.profile_name, BaseProfile)
+    return cls()
+
+
+# Register built-in profiles
+register_profile("base", BaseProfile)
+
+from paperkit.profiles.acm import ACMProfile  # noqa: E402
+
+register_profile("acm", ACMProfile)

paperkit/profiles/acm.py

@@ -0,0 +1,10 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""ACM sigconf profile."""
+
+from paperkit.profiles import BaseProfile
+
+
+class ACMProfile(BaseProfile):
+    """Profile for ACM sigconf papers (acmart class)."""

paperkit/report.py

@@ -0,0 +1,246 @@
+# Copyright (C) 2026 Vrije Universiteit Brussel. All rights reserved.
+# SPDX-License-Identifier: MIT
+
+"""Build report formatting with colors and summary table."""
+
+import re
+import shutil
+import subprocess
+
+from paperkit import reproducible, texlive
+from paperkit.builder import BuildResult
+from paperkit.checks import CheckResult, CheckStatus
+from paperkit.config import PaperkitConfig
+
+# ANSI color codes
+_RESET = "\033[0m"
+_BOLD = "\033[1m"
+_DIM = "\033[2m"
+_GREEN = "\033[32m"
+_YELLOW = "\033[33m"
+_RED = "\033[31m"
+_CYAN = "\033[36m"
+_WHITE = "\033[37m"
+
+# Status decorations
+_STATUS_STYLE: dict[CheckStatus, tuple[str, str, str]] = {
+    #                     emoji   color    label
+    CheckStatus.CLEAN: ("\u2705", _GREEN, "pass"),
+    CheckStatus.SKIPPED: ("\u23ed\ufe0f ", _YELLOW, "skip"),
+    CheckStatus.WARNING: ("\u26a0\ufe0f ", _YELLOW, "warn"),
+    CheckStatus.ERROR: ("\u274c", _RED, "FAIL"),
+}
+
+
+def _styled(text: str, *codes: str) -> str:
+    return "".join(codes) + text + _RESET
+
+
+def _status_icon(status: CheckStatus) -> str:
+    emoji, _, _ = _STATUS_STYLE[status]
+    return emoji
+
+
+def _status_colored(text: str, status: CheckStatus) -> str:
+    _, color, _ = _STATUS_STYLE[status]
+    return _styled(text, color)
+
+
+def get_environment_info(config: PaperkitConfig, build_result: BuildResult) -> dict[str, str]:
+    """Collect environment info as a dict."""
+    info: dict[str, str] = {}
+
+    # The log banner names the engine that produced the PDF, wherever this
+    # report runs; probing the engine on PATH is only a fallback.
+    banner = texlive.read_log_banner(build_result.log)
+    if banner:
+        info["TeX Live"] = str(banner)
+    elif shutil.which(config.engine):
+        proc = subprocess.run([config.engine, "--version"], capture_output=True, text=True)
+        if proc.stdout:
+            first = proc.stdout.splitlines()[0]
+            info["TeX Live"] = f"{first} (host {config.engine}, no build log)"
+    if config.texlive.source == "upstream":
+        info["TeX Live source"] = texlive.describe(config.texlive)
+    info["Source date"] = str(reproducible.resolve(config.source_date_epoch, config.root))
+
+    if config.profile_name == "acm" and build_result.log and build_result.log.is_file():
+        text = build_result.log.read_text(errors="replace")
+        m = re.search(r"acmart (\d{4}/\d{2}/\d{2} v[\d.]+)", text)
+        info["acmart"] = m.group(1) if m else "not found"
+
+    return info
+
+
+def print_report(
+    build_result: BuildResult,
+    check_results: list[CheckResult],
+    env_info: dict[str, str] | None = None,
+) -> None:
+    """Print formatted build report with colors and summary table."""
+    print()
+
+    # -- Detail sections --
+    _print_details(check_results)
+
+    # -- Summary table --
+    print(_styled("  Summary", _BOLD))
+    print()
+
+    # Environment info
+    if env_info:
+        for key, val in env_info.items():
+            print(f"  {_styled(key.rjust(24), _DIM)}  {val}")
+        print()
+
+    _print_rows(check_results)
+    print()
+
+    # -- Overall verdict --
+    worst = _worst_status(check_results)
+    if worst == CheckStatus.ERROR:
+        verdict = _styled("  \U0001f4a5 Build has errors", _BOLD, _RED)
+    elif worst == CheckStatus.WARNING:
+        verdict = _styled("  \u26a0\ufe0f  Build OK with warnings", _BOLD, _YELLOW)
+    else:
+        verdict = _styled("  \u2728 All checks passed", _BOLD, _GREEN)
+    print(verdict)
+
+    # Log location
+    print(f"  {_styled(f'Logs: {build_result.output_dir}/*.log, *.blg', _DIM)}")
+    print()
+
+
+def _print_details(check_results: list[CheckResult]) -> None:
+    """Detail sections for non-clean checks (and clean ones with extra info)."""
+    has_details = False
+    for cr in check_results:
+        if cr.status != CheckStatus.CLEAN or _has_extra_info(cr):
+            if not has_details:
+                print(_styled("  Details", _BOLD, _DIM))
+                print()
+                has_details = True
+            _print_check_detail(cr)
+
+
+def _print_rows(check_results: list[CheckResult]) -> None:
+    """One summary row per check."""
+    for cr in check_results:
+        icon = _status_icon(cr.status)
+        colored_summary = _status_colored(_check_summary(cr), cr.status)
+        print(f"  {icon} {_styled(cr.name.rjust(24), _BOLD)}  {colored_summary}")
+
+
+def _has_extra_info(cr: CheckResult) -> bool:
+    """Check if a result has info worth showing beyond the summary."""
+    if cr.show_details:
+        return True
+    # bibtex-tidy reports version in messages even when clean
+    return cr.name == "BibTeX tidy" and any("bibtex-tidy:" in m for m in cr.messages)
+
+
+def _check_summary(cr: CheckResult) -> str:
+    """One-line summary for the table."""
+    if not cr.messages:
+        return cr.status.value
+    # Use first message as summary, strip leading whitespace
+    return cr.messages[0].strip()
+
+
+def _print_check_detail(cr: CheckResult) -> None:
+    """Print detailed messages for a check (warnings/errors)."""
+    icon = _status_icon(cr.status)
+    _, color, _ = _STATUS_STYLE[cr.status]
+    print(f"  {icon} {_styled(cr.name, _BOLD, color)}")
+    for msg in cr.messages:
+        print(f"     {_status_colored(msg, cr.status)}")
+    print()
+
+
+# Statuses that make the overall verdict a warning.
+_WARNING_LEVEL = (CheckStatus.WARNING, CheckStatus.SKIPPED)
+
+
+def _worst_status(results: list[CheckResult]) -> CheckStatus:
+    """Worst verdict across results (CLEAN, WARNING or ERROR), ignoring advisory ones."""
+    binding = [cr for cr in results if not cr.advisory]
+    if any(cr.status == CheckStatus.ERROR for cr in binding):
+        return CheckStatus.ERROR
+    if any(cr.status in _WARNING_LEVEL for cr in binding):
+        return CheckStatus.WARNING
+    return CheckStatus.CLEAN
+
+
+def print_multi_summary(
+    runs: list[tuple[str, BuildResult, list[CheckResult]]],
+    shared: list[CheckResult] | None = None,
+) -> None:
+    """Print a one-line-per-main summary across all builds.
+
+    *shared* holds project-wide results (bibliography checks, one per bib
+    file), printed once in their own block and included in the verdict.
+    """
+    if shared:
+        print(_styled("  Bibliography", _BOLD))
+        print()
+        _print_details(shared)
+        _print_rows(shared)
+        print()
+
+    print(_styled("  Per-project summary", _BOLD))
+    print()
+
+    width = max(len(name) for name, _, _ in runs) if runs else 0
+    counts = {CheckStatus.CLEAN: 0, CheckStatus.WARNING: 0, CheckStatus.ERROR: 0}
+    failed = 0
+
+    for name, build_result, check_results in runs:
+        if not build_result.success:
+            failed += 1
+            counts[CheckStatus.ERROR] += 1
+            icon = _status_icon(CheckStatus.ERROR)
+            label = _status_colored("build failed", CheckStatus.ERROR)
+        else:
+            worst = _worst_status(check_results)
+            counts[worst] += 1
+            icon = _status_icon(worst)
+            if worst == CheckStatus.CLEAN:
+                label = _status_colored("all checks passed", worst)
+            else:
+                level = _WARNING_LEVEL if worst == CheckStatus.WARNING else (worst,)
+                bad = [cr.name for cr in check_results if cr.status in level]
+                summary = ", ".join(bad) if bad else worst.value
+                label = _status_colored(summary, worst)
+        print(f"  {icon} {_styled(name.ljust(width), _BOLD)}  {label}")
+
+    print()
+    n = len(runs)
+    parts = [
+        f"{counts[CheckStatus.CLEAN]} pass",
+        f"{counts[CheckStatus.WARNING]} warn",
+        f"{counts[CheckStatus.ERROR]} fail",
+    ]
+    breakdown = ", ".join(parts)
+    shared_worst = _worst_status(shared or [])
+    if shared_worst != CheckStatus.CLEAN:
+        breakdown += f"; bibliography: {_STATUS_STYLE[shared_worst][2]}"
+    if failed:
+        verdict = _styled(
+            f"  \U0001f4a5 {failed}/{n} project(s) failed to build  ({breakdown})",
+            _BOLD,
+            _RED,
+        )
+    elif counts[CheckStatus.WARNING] or shared_worst != CheckStatus.CLEAN:
+        verdict = _styled(
+            f"  \u26a0\ufe0f  {n} project(s) built, see warnings  ({breakdown})",
+            _BOLD,
+            _YELLOW,
+        )
+    else:
+        verdict = _styled(
+            f"  \u2728 All {n} project(s) clean  ({breakdown})",
+            _BOLD,
+            _GREEN,
+        )
+    print(verdict)
+    print()