parseoff 0.2.1__py3-none-any.whl

parseoff/__init__.py

@@ -0,0 +1,3 @@
+"""parseoff - compare PDF parsers side by side on your own documents."""
+
+__version__ = "0.2.1"

parseoff/adapters/__init__.py

@@ -0,0 +1,32 @@
+"""Parser adapters.
+
+An adapter is a function ``convert(pdf_path: str, pages: list[int]) -> list[str]`` that returns one
+Markdown/plain-text string per requested page (``pages`` are 1-based). Adapters import their parser
+lazily so that a missing optional parser never breaks the others.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+from .builtin import pdfminer_convert, pdfplumber_convert, pypdf_convert
+from .optional import docling_convert, markitdown_convert, pymupdf4llm_convert
+
+Adapter = Callable[[str, list[int]], list[str]]
+
+ADAPTERS: dict[str, Adapter] = {
+    "pypdf": pypdf_convert,
+    "pdfplumber": pdfplumber_convert,
+    "pdfminer": pdfminer_convert,
+    "markitdown": markitdown_convert,
+    "pymupdf4llm": pymupdf4llm_convert,
+    "docling": docling_convert,
+}
+
+
+def get_adapter(name: str) -> Adapter:
+    try:
+        return ADAPTERS[name]
+    except KeyError:
+        known = ", ".join(sorted(ADAPTERS))
+        raise ValueError(f"unknown parser {name!r}; known parsers: {known}") from None

parseoff/adapters/_common.py

@@ -0,0 +1,10 @@
+"""Helpers shared by the adapters."""
+
+from __future__ import annotations
+
+
+def check_pages(pages: list[int], total: int) -> None:
+    """Raise a helpful error if a requested page is outside the document."""
+    bad = [p for p in pages if p < 1 or p > total]
+    if bad:
+        raise ValueError(f"page(s) {bad} out of range: the PDF has {total} page(s) (pages are 1-based)")

parseoff/adapters/builtin.py

@@ -0,0 +1,70 @@
+"""Adapters for the parsers installed together with parseoff: pypdf, pdfplumber, pdfminer.six."""
+
+from __future__ import annotations
+
+from ._common import check_pages
+
+
+def pypdf_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """Plain text in content-stream order (pypdf's default). No structure is reconstructed."""
+    from pypdf import PdfReader
+
+    reader = PdfReader(pdf_path)
+    check_pages(pages, len(reader.pages))
+    return [(reader.pages[p - 1].extract_text() or "").strip() for p in pages]
+
+
+def _gfm_table(rows: list[list[str | None]]) -> str:
+    """Render extracted table rows as a GitHub-flavoured Markdown table (first row = header)."""
+
+    def cell(value: str | None) -> str:
+        return " ".join((value or "").split()).replace("|", "\\|")
+
+    clean = [[cell(c) for c in row] for row in rows if row]
+    width = max(len(r) for r in clean)
+    clean = [r + [""] * (width - len(r)) for r in clean]
+    lines = ["| " + " | ".join(clean[0]) + " |", "| " + " | ".join(["---"] * width) + " |"]
+    lines += ["| " + " | ".join(r) + " |" for r in clean[1:]]
+    return "\n".join(lines)
+
+
+def pdfplumber_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """Text by position, with detected tables rendered as GFM tables at their vertical position.
+
+    Characters inside a table are removed from the running text so cell values appear once.
+    """
+    import pdfplumber
+
+    out: list[str] = []
+    with pdfplumber.open(pdf_path) as pdf:
+        check_pages(pages, len(pdf.pages))
+        for number in pages:
+            page = pdf.pages[number - 1]
+            tables = page.find_tables()
+            boxes = [t.bbox for t in tables]
+
+            def outside(obj: dict, boxes=boxes) -> bool:
+                if obj.get("object_type") != "char":
+                    return True
+                cx, cy = (obj["x0"] + obj["x1"]) / 2, (obj["top"] + obj["bottom"]) / 2
+                return not any(x0 <= cx <= x1 and top <= cy <= bottom for x0, top, x1, bottom in boxes)
+
+            body = page.filter(outside) if boxes else page
+            blocks = [(ln["top"], ln["text"]) for ln in body.extract_text_lines(return_chars=False)]
+            blocks += [(t.bbox[1], _gfm_table(t.extract())) for t in tables if t.extract()]
+            out.append("\n".join(text for _, text in sorted(blocks, key=lambda b: b[0])))
+    return out
+
+
+def pdfminer_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """Layout-box text from pdfminer.six (the engine behind markitdown's PDF path)."""
+    from pdfminer.high_level import extract_pages
+    from pdfminer.layout import LTTextContainer
+    from pypdf import PdfReader
+
+    check_pages(pages, len(PdfReader(pdf_path).pages))
+    by_page: dict[int, str] = {}
+    for number, layout in zip(sorted(set(pages)), extract_pages(pdf_path, page_numbers=[p - 1 for p in sorted(set(pages))])):
+        boxes = [el.get_text().strip() for el in layout if isinstance(el, LTTextContainer)]
+        by_page[number] = "\n\n".join(b for b in boxes if b)
+    return [by_page.get(p, "") for p in pages]

parseoff/adapters/custom.py

@@ -0,0 +1,69 @@
+"""User-supplied parsers: ``--custom NAME=module:function``.
+
+The function receives ``(pdf_path: str, page_numbers: list[int])`` (1-based pages) and must return
+one string per requested page. It runs inside the worker subprocess, never in the main process.
+Only the module you name is imported - make sure you trust it, it can run any code.
+"""
+
+from __future__ import annotations
+
+import importlib
+import os
+import re
+import sys
+from collections.abc import Callable
+from dataclasses import dataclass
+
+from ..i18n import LocalizedError
+from ..registry import BUILTIN_NAMES
+
+_NAME = re.compile(r"^[A-Za-z][A-Za-z0-9_-]{0,31}$")
+_DOTTED = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*(\.[A-Za-z_][A-Za-z0-9_]*)*$")
+
+
+@dataclass(frozen=True)
+class CustomSpec:
+    name: str
+    module: str
+    function: str
+
+    @property
+    def spec(self) -> str:
+        return f"{self.name}={self.module}:{self.function}"
+
+
+class SpecError(LocalizedError, ValueError):
+    """A malformed ``--custom`` value. The message is English; ``text(lang)`` translates it."""
+
+
+def parse_spec(text: str) -> CustomSpec:
+    """Parse ``NAME=module:function``; raise SpecError (a ValueError) with the fix on a malformed value."""
+    name, sep, target = text.partition("=")
+    module, colon, function = target.partition(":")
+    if not (sep and colon and name and module and function):
+        raise SpecError("custom.bad_value", text=text)
+    if not _NAME.match(name):
+        raise SpecError("custom.bad_name", name=name)
+    if name in BUILTIN_NAMES:
+        raise SpecError("custom.taken", name=name)
+    if not _DOTTED.match(module) or not function.isidentifier():
+        raise SpecError("custom.bad_target", target=target)
+    return CustomSpec(name, module, function)
+
+
+def load(spec: CustomSpec) -> Callable[[str, list[int]], list[str]]:
+    """Import the user's module (current directory and PARSEOFF_PATH are searched) and get the function."""
+    for extra in [os.getcwd(), *os.environ.get("PARSEOFF_PATH", "").split(os.pathsep)]:
+        if extra and extra not in sys.path:
+            sys.path.append(extra)
+    try:
+        module = importlib.import_module(spec.module)
+    except ImportError as exc:
+        raise RuntimeError(
+            f"cannot import module {spec.module!r} for custom parser {spec.name!r}: {exc}. "
+            "Run parseoff from the folder that contains it or install the package."
+        ) from exc
+    func = getattr(module, spec.function, None)
+    if not callable(func):
+        raise RuntimeError(f"module {spec.module!r} has no callable {spec.function!r}")
+    return func

parseoff/adapters/optional.py

@@ -0,0 +1,58 @@
+"""Adapters for parsers that are NOT part of parseoff's own dependencies.
+
+Nothing from these packages is bundled; each adapter imports its parser inside the function and
+only runs when the user installed it. An import failure is reported as a clear error message.
+"""
+
+from __future__ import annotations
+
+import tempfile
+from pathlib import Path
+
+from ._common import check_pages
+
+
+def _require(module: str, hint: str):
+    import importlib
+
+    try:
+        return importlib.import_module(module)
+    except ImportError as exc:
+        raise RuntimeError(f"{module} is not installed ({hint})") from exc
+
+
+def markitdown_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """markitdown only returns one string per file, so each page is split out and converted alone."""
+    mod = _require("markitdown", 'uv sync --extra markitdown')
+    from pypdf import PdfReader, PdfWriter
+
+    reader = PdfReader(pdf_path)
+    check_pages(pages, len(reader.pages))
+    converter = mod.MarkItDown(enable_plugins=False)
+    out: list[str] = []
+    with tempfile.TemporaryDirectory(prefix="parseoff-") as tmp:
+        for number in pages:
+            writer = PdfWriter()
+            writer.add_page(reader.pages[number - 1])
+            single = Path(tmp) / f"page-{number}.pdf"
+            with single.open("wb") as fh:
+                writer.write(fh)
+            out.append((converter.convert(str(single)).text_content or "").strip())
+    return out
+
+
+def pymupdf4llm_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """pymupdf4llm (AGPL-3.0, user-installed). `page_chunks=True` returns one dict per page."""
+    mod = _require("pymupdf4llm", "uv pip install pymupdf4llm - AGPL-3.0, check the licence terms")
+    chunks = mod.to_markdown(pdf_path, pages=[p - 1 for p in pages], page_chunks=True)
+    if len(chunks) != len(pages):
+        raise RuntimeError(f"pymupdf4llm returned {len(chunks)} page chunk(s) for {len(pages)} page(s)")
+    return [str(chunk.get("text", "")).strip() for chunk in chunks]
+
+
+def docling_convert(pdf_path: str, pages: list[int]) -> list[str]:
+    """docling (experimental, opt-in). Downloads models on first run unless they are present."""
+    mod = _require("docling.document_converter", 'uv sync --extra docling')
+    converter = mod.DocumentConverter()
+    document = converter.convert(pdf_path).document
+    return [document.export_to_markdown(page_no=p).strip() for p in pages]

parseoff/cli.py

@@ -0,0 +1,183 @@
+"""Command line interface: `parseoff doctor | run | demo`.
+
+Screen language: ``--lang en|ko`` > ``PARSEOFF_LANG`` > ``LC_ALL`` / ``LC_MESSAGES`` / ``LANG`` (see i18n.py).
+The language is read from the command line *before* the real parser is built, so even the
+argparse sentences (usage, options, errors) come out in the chosen language.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from pathlib import Path
+
+from . import __version__
+from .adapters.custom import CustomSpec, SpecError, parse_spec
+from .doctor import render_doctor
+from .findings import skip_reason
+from .i18n import LANGS, argparse_language, resolve_lang, t
+from .model import Thresholds
+from .report_html import render_doc, render_index
+from .report_text import summary_json, summary_markdown
+from .runner import RunOptions, UsageError, run_pipeline
+from .samples import create_samples
+
+
+def read_lang_option(argv: list[str]) -> str | None:
+    """Find ``--lang X`` / ``--lang=X`` anywhere in argv (before the real parser exists)."""
+    for i, arg in enumerate(argv):
+        if arg == "--":
+            break
+        if arg == "--lang":
+            return argv[i + 1] if i + 1 < len(argv) else None
+        if arg.startswith("--lang="):
+            return arg.partition("=")[2]
+    return None
+
+
+def _fraction_type(lang: str) -> Callable[[str], float]:
+    def convert(text: str) -> float:
+        try:
+            value = float(text)
+        except ValueError:
+            raise argparse.ArgumentTypeError(t("arg.not_fraction", lang, text=text)) from None
+        if not 0.0 <= value <= 1.0:
+            raise argparse.ArgumentTypeError(t("arg.out_of_range", lang, text=text))
+        return value
+
+    return convert
+
+
+def _positive_type(lang: str) -> Callable[[str], float]:
+    def convert(text: str) -> float:
+        try:
+            value = float(text)
+        except ValueError:
+            raise argparse.ArgumentTypeError(t("arg.not_number", lang, text=text)) from None
+        if value <= 0:
+            raise argparse.ArgumentTypeError(t("arg.not_positive", lang, text=text))
+        return value
+
+    return convert
+
+
+def _custom_type(lang: str) -> Callable[[str], CustomSpec]:
+    def convert(text: str) -> CustomSpec:
+        try:
+            return parse_spec(text)
+        except SpecError as exc:
+            raise argparse.ArgumentTypeError(exc.text(lang)) from None
+
+    return convert
+
+
+def _add_lang_option(p: argparse.ArgumentParser, lang: str) -> None:
+    # SUPPRESS: the value was already read by read_lang_option; this entry is for --help and validation
+    p.add_argument("--lang", choices=LANGS, default=argparse.SUPPRESS, metavar="{en,ko}", help=t("cli.help.lang", lang))
+
+
+def _add_run_options(p: argparse.ArgumentParser, lang: str) -> None:
+    fraction, positive = _fraction_type(lang), _positive_type(lang)
+    p.add_argument("--parsers", help=t("cli.help.parsers", lang))
+    p.add_argument("--max-pages", type=int, metavar="N", help=t("cli.help.max_pages", lang))
+    p.add_argument("--timeout", type=positive, default=120.0, metavar="SEC", help=t("cli.help.timeout", lang))
+    p.add_argument("--custom", action="append", default=[], type=_custom_type(lang), metavar="NAME=module:function",
+                   help=t("cli.help.custom", lang))
+    p.add_argument("--min-coverage", type=fraction, default=0.8, metavar="X", help=t("cli.help.min_coverage", lang))
+    p.add_argument("--min-agreement", type=fraction, default=0.6, metavar="X", help=t("cli.help.min_agreement", lang))
+    p.add_argument("--strict", action="store_true", help=t("cli.help.strict", lang))
+    p.add_argument("--fresh", action="store_true", help=t("cli.help.fresh", lang))
+    p.add_argument("--no-render", action="store_true", help=t("cli.help.no_render", lang))
+    _add_lang_option(p, lang)
+
+
+def build_parser(lang: str = "en") -> argparse.ArgumentParser:
+    ap = argparse.ArgumentParser(prog="parseoff", description=t("cli.description", lang))
+    ap.add_argument("--version", action="version", version=f"parseoff {__version__}", help=t("cli.help.version", lang))
+    _add_lang_option(ap, lang)
+    sub = ap.add_subparsers(dest="command", required=True)
+    doctor = sub.add_parser("doctor", help=t("cli.help.doctor", lang))
+    _add_lang_option(doctor, lang)
+    run = sub.add_parser("run", help=t("cli.help.run", lang))
+    run.add_argument("input", type=Path, help=t("cli.help.input", lang))
+    run.add_argument("--out", type=Path, default=Path("parseoff-out"), help=t("cli.help.out_run", lang))
+    _add_run_options(run, lang)
+    demo = sub.add_parser("demo", help=t("cli.help.demo", lang))
+    demo.add_argument("--out", type=Path, default=Path("demo-out"), help=t("cli.help.out_demo", lang))
+    _add_run_options(demo, lang)
+    return ap
+
+
+def _write_outputs(out: Path, report, lang: str) -> Path:
+    """Write summary.json, summary.md and report/*.html; return the index.html path."""
+    report_dir = out / "report"
+    report_dir.mkdir(parents=True, exist_ok=True)
+    (out / "summary.json").write_text(summary_json(report), encoding="utf-8")  # same bytes in every language
+    (out / "summary.md").write_text(summary_markdown(report, lang), encoding="utf-8")
+    (report_dir / "index.html").write_text(render_index(report, lang), encoding="utf-8")
+    for doc in report.docs:
+        (report_dir / f"doc-{doc.slug}.html").write_text(render_doc(report, doc, lang), encoding="utf-8")
+    return report_dir / "index.html"
+
+
+def _fail(message: str, lang: str) -> int:
+    print(t("cli.error_prefix", lang) + message, file=sys.stderr)
+    return 2
+
+
+def _execute(args: argparse.Namespace, input_path: Path, demo: bool, lang: str) -> int:
+    if args.max_pages is not None and args.max_pages < 1:
+        return _fail(t("err.max_pages", lang), lang)
+    requested = [p.strip() for p in args.parsers.split(",") if p.strip()] if args.parsers else None
+    options = RunOptions(
+        input_path=input_path, out_dir=args.out, parsers=requested, customs=args.custom,
+        max_pages=args.max_pages, timeout=args.timeout, fresh=args.fresh, render=not args.no_render,
+        thresholds=Thresholds(args.min_coverage, args.min_agreement), demo=demo, lang=lang,
+    )
+    try:
+        report = run_pipeline(options, progress=print)
+    except UsageError as exc:
+        return _fail(exc.text(lang), lang)
+    index = _write_outputs(args.out, report, lang)
+
+    counts = report.counts()
+    failed = counts["FAIL"] > 0
+    code = 1 if (args.strict and failed) else 0
+    print()
+    print(t("run.summary", lang, count=len(report.docs), parsers=", ".join(report.parsers) or t("run.none", lang)))
+    for skip in report.skipped:
+        print(t("run.skipped", lang, name=skip.name, reason=skip_reason(skip, lang)))
+    hint = "" if code else t("run.strict_hint", lang)
+    print(t("run.counts", lang, fail=counts["FAIL"], warn=counts["WARN"], info=counts["INFO"], code=code, hint=hint))
+    print(t("run.report", lang, path=index))
+    return code
+
+
+def _tolerate_unencodable_output() -> None:
+    """A terminal whose encoding cannot show Korean should print '?' instead of crashing."""
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(errors="replace")  # type: ignore[union-attr]
+        except (AttributeError, ValueError, OSError):
+            pass  # not a real text stream (for example a test capture): nothing to do
+
+
+def main(argv: list[str] | None = None) -> int:
+    args_in = list(sys.argv[1:] if argv is None else argv)
+    lang = resolve_lang(read_lang_option(args_in))
+    _tolerate_unencodable_output()
+    with argparse_language(lang):
+        args = build_parser(lang).parse_args(args_in)
+    if args.command == "doctor":
+        print(render_doctor(lang))
+        return 0
+    if args.command == "demo":
+        print(t("demo.banner", lang))
+        samples = create_samples(args.out / "samples")
+        return _execute(args, samples[0].parent, True, lang)
+    return _execute(args, args.input, False, lang)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

parseoff/doctor.py

@@ -0,0 +1,64 @@
+"""`parseoff doctor`: which parsers are installed, with licence, size and warnings."""
+
+from __future__ import annotations
+
+import unicodedata
+
+from .i18n import DEFAULT_LANG, t
+from .registry import (
+    REGISTRY,
+    disk_size_mb,
+    docling_models_present,
+    install_hint,
+    installed_version,
+    is_installed,
+    size_text,
+    survey_note,
+)
+
+_HEADER_KEYS = ("parser", "installed", "version", "license", "size", "disk", "notes")
+
+
+def _width(text: str) -> int:
+    """Columns the text takes in a terminal (Korean letters are two columns wide)."""
+    return sum(2 if unicodedata.east_asian_width(ch) in ("W", "F") else 1 for ch in text)
+
+
+def _pad(text: str, width: int) -> str:
+    return text + " " * (width - _width(text))
+
+
+def _notes(name: str, lang: str) -> str:
+    info = REGISTRY[name]
+    notes = [t(f"note.{name}", lang)]
+    if info.copyleft:
+        notes.append(t("doctor.copyleft", lang))
+    if info.model_download:
+        found = t("doctor.found" if docling_models_present() else "doctor.not_found", lang)
+        notes.append(t("doctor.model_download", lang, found=found))
+    if not info.core:
+        notes.append(t("doctor.install", lang, hint=install_hint(name, lang)))
+    return "; ".join(n for n in notes if n)
+
+
+def render_doctor(lang: str = DEFAULT_LANG) -> str:
+    header = tuple(t(f"doctor.h.{k}", lang) for k in _HEADER_KEYS)
+    rows = [header]
+    for name, info in REGISTRY.items():
+        installed = is_installed(name)
+        disk = disk_size_mb(name) if installed else None
+        rows.append((
+            name,
+            t("doctor.yes" if installed else "doctor.no", lang),
+            (installed_version(name) or "-") if installed else "-",
+            info.license,
+            size_text(name, lang),
+            f"{disk:.1f} MB" if disk is not None else "-",
+            _notes(name, lang),
+        ))
+    widths = [max(_width(r[i]) for r in rows) for i in range(len(header) - 1)]
+    lines = []
+    for r in rows:
+        lines.append("  ".join(_pad(r[i], widths[i]) for i in range(len(widths))) + "  " + r[-1])
+    lines += ["", t("doctor.foot1", lang, survey=survey_note(lang)), t("doctor.foot2", lang)]
+    return "\n".join(lines)

parseoff/findings.py

@@ -0,0 +1,146 @@
+"""Turn metrics, parser status and registry facts into a flat list of findings.
+
+Levels: FAIL = something is broken or unusable, WARN = look at it before choosing, INFO = good to know.
+Rules (code -> level):
+  FAIL  PARSER_ERROR, TIMEOUT, EMPTY_TEXT_LAYER, LOW_COVERAGE
+  WARN  LOW_AGREEMENT, BOILERPLATE, LICENSE_COPYLEFT, LICENSE_WEIGHTS, MODEL_DOWNLOAD, HEAVY_INSTALL
+  INFO  NO_STRUCTURE, SKIPPED
+
+Every finding keeps an English ``message`` (this is what summary.json stores, so it never depends on
+the screen language) plus a message ``key`` and ``params``. ``message_for(finding, lang)`` builds the
+same sentence in the screen language for the terminal, HTML report and summary.md.
+"""
+
+from __future__ import annotations
+
+from .i18n import DEFAULT_LANG, t
+from .metrics import BOILERPLATE_MIN_RATIO
+from .model import FAIL, INFO, LEVELS, WARN, DocReport, Finding, RunReport, Skipped
+from .registry import HEAVY_INSTALL_MB, REGISTRY, docling_models_present, install_hint, size_text
+
+
+def _render(key: str, params: dict, lang: str) -> str:
+    """Build one finding sentence. Language independent params, language dependent words."""
+    if key == "finding.no_item" and "parts" in params:  # NO_STRUCTURE: one or two parts
+        items = t("finding.and", lang).join(
+            t("finding.no_item", lang, label=t(f"label.{label}", lang), best=best, count=count)
+            for label, best, count in params["parts"]
+        )
+        return t("finding.flattened", lang, items=items)
+    if key == "finding.model_download":
+        state = t("finding.models_found" if params["found"] else "finding.models_missing", lang)
+        return t(key, lang, state=state)
+    if key == "skip.not_installed":
+        hint = install_hint(params["name"], lang) or t("skip.install_first", lang)
+        return t(key, lang, hint=hint)
+    if key == "finding.heavy":
+        return t(key, lang, size=size_text(params["name"], lang))
+    return t(key, lang, **params)
+
+
+def message_for(finding: Finding, lang: str = DEFAULT_LANG) -> str:
+    """The finding's message in `lang`. Messages without a key (text from a parser) stay as they are."""
+    if lang == DEFAULT_LANG or not finding.key:
+        return finding.message
+    return _render(finding.key, finding.params, lang)
+
+
+def skip_reason(skip: Skipped, lang: str = DEFAULT_LANG) -> str:
+    """Why a parser was skipped, in `lang` (the English text is `skip.reason`)."""
+    if lang == DEFAULT_LANG or not skip.key:
+        return skip.reason
+    return _render(skip.key, skip.params, lang)
+
+
+def _make(code: str, level: str, key: str, params: dict, doc: str | None = None,
+          page: int | None = None, parser: str | None = None) -> Finding:
+    return Finding(code, level, _render(key, params, DEFAULT_LANG), doc, page, parser, key, params)
+
+
+def _structure_findings(doc: DocReport) -> list[Finding]:
+    """NO_STRUCTURE: a parser found no tables/headings although another parser did."""
+    out: list[Finding] = []
+    if not doc.metrics:
+        return out
+    totals = {
+        name: (sum(p.tables for p in pm.pages), sum(p.headings for p in pm.pages))
+        for name, pm in doc.metrics.parsers.items()
+    }
+    for name in totals:
+        missing = []
+        for idx, label in ((0, "tables"), (1, "headings")):
+            donors = {n: t_[idx] for n, t_ in totals.items() if n != name and t_[idx] > 0}
+            if totals[name][idx] == 0 and donors:
+                best = max(sorted(donors), key=lambda n: donors[n])
+                missing.append((label, best, donors[best]))
+        if missing:
+            out.append(_make("NO_STRUCTURE", INFO, "finding.no_item", {"parts": missing}, doc.doc_id, None, name))
+    return out
+
+
+def build_findings(report: RunReport) -> list[Finding]:
+    th = report.thresholds
+    found: list[Finding] = []
+
+    for doc in report.docs:
+        if doc.open_error:
+            found.append(_make("PARSER_ERROR", FAIL, "finding.cannot_open", {"error": doc.open_error}, doc.doc_id))
+            continue
+        for page, chars in zip(doc.pages, doc.layer_chars):
+            if chars == 0:
+                found.append(_make("EMPTY_TEXT_LAYER", FAIL, "finding.empty_layer", {}, doc.doc_id, page))
+        for name, out in doc.outputs.items():
+            if out.status in ("timeout", "error"):
+                code = "TIMEOUT" if out.status == "timeout" else "PARSER_ERROR"
+                # the text comes from the parser or from parseoff itself; only our own is translatable
+                found.append(Finding(code, FAIL, out.error, doc.doc_id, None, name, out.error_key, dict(out.error_params)))
+        if not doc.metrics:
+            continue
+        for name, pm in doc.metrics.parsers.items():
+            for page, m in zip(doc.pages, pm.pages):
+                if m.coverage is not None and m.coverage < th.min_coverage:
+                    found.append(_make(
+                        "LOW_COVERAGE", FAIL, "finding.low_coverage",
+                        {"coverage": m.coverage, "threshold": th.min_coverage}, doc.doc_id, page, name,
+                    ))
+        for page, pairs in doc.metrics.agreement.items():
+            values = {pair: v for pair, v in pairs.items() if v is not None}
+            if values:
+                pair = min(sorted(values), key=lambda p: values[p])
+                if values[pair] < th.min_agreement:
+                    found.append(_make(
+                        "LOW_AGREEMENT", WARN, "finding.low_agreement",
+                        {"a": pair[0], "b": pair[1], "value": values[pair], "threshold": th.min_agreement},
+                        doc.doc_id, page,
+                    ))
+        repeated = {
+            n: pm for n, pm in doc.metrics.parsers.items() if pm.boilerplate_ratio >= BOILERPLATE_MIN_RATIO
+        }
+        if repeated:
+            top = max(sorted(repeated), key=lambda n: repeated[n].boilerplate_ratio)
+            share = ", ".join(f"{n} {pm.boilerplate_ratio:.0%}" for n, pm in sorted(repeated.items()))
+            found.append(_make(
+                "BOILERPLATE", WARN, "finding.boilerplate",
+                {"example": repeated[top].boilerplate_example, "share": share}, doc.doc_id,
+            ))
+        found += _structure_findings(doc)
+
+    for name in report.parsers:
+        info = REGISTRY.get(name)
+        if info is None:  # custom parser: nothing is known about it
+            continue
+        if info.copyleft:
+            found.append(_make("LICENSE_COPYLEFT", WARN, "finding.copyleft", {"license": info.license}, parser=name))
+        if info.weights_restricted:
+            found.append(_make("LICENSE_WEIGHTS", WARN, "finding.weights", {}, parser=name))
+        if info.model_download:
+            found.append(_make(
+                "MODEL_DOWNLOAD", WARN, "finding.model_download", {"found": docling_models_present()}, parser=name,
+            ))
+        if info.size_mb is not None and info.size_mb >= HEAVY_INSTALL_MB:
+            found.append(_make("HEAVY_INSTALL", WARN, "finding.heavy", {"name": name}, parser=name))
+    for skip in report.skipped:
+        found.append(Finding("SKIPPED", INFO, skip.reason, None, None, skip.name, skip.key, dict(skip.params)))
+
+    rank = {lvl: i for i, lvl in enumerate(LEVELS)}
+    return sorted(found, key=lambda f: (rank[f.level], f.code, f.doc or "", f.page or 0, f.parser or "", f.message))