brewdoc 0.2.0__py3-none-any.whl

brewdoc/selfcheck.py

@@ -0,0 +1,383 @@
+"""Shipped self-check for synthetic documents and presentations, with no fixture files."""
+
+from __future__ import annotations
+
+import datetime
+import io
+import re
+import tempfile
+import zipfile
+from pathlib import Path
+
+import brewdoc.htmltext as htmltext
+from brewdoc.common import (UNIT_COUNTERS, _escape_markdown_text, cell_text, markdown_table,
+                            new_tally, sanitise, sha256)
+from brewdoc.docx import render_doc
+from brewdoc.pdf import render_pdf
+from brewdoc.pptx import render_presentation
+from brewdoc.service import EXIT_FAIL, EXIT_OK, run
+from brewdoc.sheets import render_book
+
+
+def synthetic_pdf(pages, font: bool = True) -> bytes:
+    """A minimal valid PDF printing each page's content stream verbatim; `font=False` for a scan."""
+    objects, count = {}, len(pages)
+    objects[1] = b"<< /Type /Catalog /Pages 2 0 R >>"
+    objects[2] = ("<< /Type /Pages /Kids [%s] /Count %d >>"
+                  % (" ".join("%d 0 R" % (3 + i) for i in range(count)), count)).encode("ascii")
+    first_stream = 3 + count
+    resources = " /Font << /F1 %d 0 R >>" % (first_stream + count) if font else ""
+    for index, body in enumerate(pages):
+        objects[3 + index] = (
+            "<< /Type /Page /Parent 2 0 R /MediaBox [0 0 612 792] /Resources <<%s >> "
+            "/Contents %d 0 R >>" % (resources, first_stream + index)).encode("ascii")
+        data = body.encode("latin-1")
+        objects[first_stream + index] = (("<< /Length %d >>\nstream\n" % len(data)).encode("ascii")
+                                         + data + b"\nendstream")
+    if font:
+        objects[first_stream + count] = b"<< /Type /Font /Subtype /Type1 /BaseFont /Helvetica >>"
+    buffer, offsets = io.BytesIO(), {}
+    buffer.write(b"%PDF-1.4\n")
+    for number in sorted(objects):
+        offsets[number] = buffer.tell()
+        buffer.write(("%d 0 obj\n" % number).encode("ascii"))
+        buffer.write(objects[number])
+        buffer.write(b"\nendobj\n")
+    start, size = buffer.tell(), max(objects) + 1
+    buffer.write(("xref\n0 %d\n" % size).encode("ascii") + b"0000000000 65535 f \n")
+    for number in range(1, size):
+        buffer.write(("%010d 00000 n \n" % offsets.get(number, 0)).encode("ascii"))
+    buffer.write(("trailer\n<< /Size %d /Root 1 0 R >>\nstartxref\n%d\n%%%%EOF\n"
+                  % (size, start)).encode("ascii"))
+    return buffer.getvalue()
+
+
+def _text_op(x: float, y: float, text: str, size: int = 10) -> str:
+    return "BT /F1 %d Tf 1 0 0 1 %s %s Tm (%s) Tj ET\n" % (size, x, y, text)
+
+
+def _rule(x: float, y: float, width: float, height: float = 0.5) -> str:
+    return "%s %s %s %s re f\n" % (x, y, width, height)
+
+
+FIXTURE_TABLE = [_text_op(80, 700, "Table 1. Yield by zone."),
+                 _text_op(80, 685, "Zone") + _text_op(200, 685, "Area") + _text_op(320, 685, "Yield"),
+                 _text_op(80, 670, "North") + _text_op(200, 670, "12.5") + _text_op(320, 670, "4.10"),
+                 _text_op(80, 655, "South") + _text_op(200, 655, "9.0") + _text_op(320, 655, "3.75")]
+FIXTURE_COLUMNS = [_text_op(60, 600 - 12 * i, "left column line %d of the body text here" % i)
+                   + _text_op(330, 600 - 12 * i, "right column line %d of the body text" % i)
+                   for i in range(12)]
+
+
+def _fixture_pages() -> list[str]:
+    body = "".join(FIXTURE_TABLE) + "".join(FIXTURE_COLUMNS)
+    return [_text_op(72, 760, "Seasonal Operations Manual") + body + _text_op(300, 40, "%d" % n)
+            for n in (1, 2, 3)]
+
+
+# p1: a grid closed on the header row alone, plus a subscripted cell. p2: rules only across.
+FIXTURE_UNCLOSED = (
+    "".join(_rule(100, y, 300) for y in (700, 685, 670, 655, 640))
+    + "".join(_rule(x, 640, 0.5, 60) for x in (100, 200, 300))
+    + _rule(400, 685, 0.5, 15)
+    + "".join(_text_op(x, 689, text) for x, text in ((105, "Zone"), (205, "Area"), (305, "Yield")))
+    + "".join(_text_op(x, 674, text) for x, text in ((105, "North"), (205, "12.5"), (305, "4.10")))
+    + "".join(_text_op(x, 659, text) for x, text in ((105, "South"), (205, "9.0"), (305, "3.75")))
+    + _text_op(105, 644, "Salt") + _text_op(305, 644, "1.0")
+    + _text_op(205, 644, "P") + _text_op(211, 641, "2", 6)
+    + _text_op(215, 644, "O") + _text_op(221, 641, "5", 6))
+FIXTURE_SEGMENTED = (
+    "".join(_rule(x, 600, 99.5) for x in (100, 200, 300, 400))
+    + "".join(_text_op(x, 585, text)
+              for x, text in ((105, "Crop"), (205, "Zone"), (305, "Area"), (405, "Yield")))
+    + "".join(_text_op(x, 570, text)
+              for x, text in ((105, "Maize"), (205, "North"), (305, "12.5"), (405, "4.10")))
+    + "".join(_text_op(x, 555, text)
+              for x, text in ((105, "Wheat"), (205, "South"), (305, "9.0"), (405, "3.75")))
+    # Prose, so the region's word-space yardstick is a word space and not a column gap.
+    + "".join(_text_op(100, 520 - 12 * i, "a prose line with ordinary word spaces")
+              for i in range(6)))
+
+
+SHEET_ROWS = [["Zone", "Area", "Sown"], ["North", 12.5, "2026-07-18"], ["South", 9.0, ""]]
+
+
+def _synthetic_xlsx(path: Path) -> None:
+    def cell(column: str, row: int, value):
+        reference = "%s%d" % (column, row)
+        if isinstance(value, float):
+            return '<c r="%s"><v>%r</v></c>' % (reference, value)
+        return ('<c r="%s" t="inlineStr"><is><t>%s</t></is></c>' % (reference, value)
+                if value != "" else '<c r="%s"/>' % reference)
+    rows = "".join(
+        '<row r="%d">%s</row>' % (index, "".join(
+            cell(chr(ord("A") + position), index, value) for position, value in enumerate(row)))
+        for index, row in enumerate(SHEET_ROWS, 1))
+    with zipfile.ZipFile(path, "w") as book:
+        book.writestr("[Content_Types].xml",
+                      '<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/'
+                      'package/2006/content-types"><Default Extension="rels" ContentType='
+                      '"application/vnd.openxmlformats-package.relationships+xml"/><Override '
+                      'PartName="/xl/workbook.xml" ContentType="application/vnd.openxmlformats-'
+                      'officedocument.spreadsheetml.sheet.main+xml"/><Override PartName='
+                      '"/xl/worksheets/sheet1.xml" ContentType="application/vnd.openxmlformats-'
+                      'officedocument.spreadsheetml.worksheet+xml"/></Types>')
+        book.writestr("_rels/.rels",
+                      '<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats'
+                      '.org/package/2006/relationships"><Relationship Id="rId1" Type="http://'
+                      'schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument"'
+                      ' Target="xl/workbook.xml"/></Relationships>')
+        book.writestr("xl/_rels/workbook.xml.rels",
+                      '<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats'
+                      '.org/package/2006/relationships"><Relationship Id="rId1" Type="http://'
+                      'schemas.openxmlformats.org/officeDocument/2006/relationships/worksheet" '
+                      'Target="worksheets/sheet1.xml"/></Relationships>')
+        book.writestr("xl/workbook.xml",
+                      '<?xml version="1.0"?><workbook xmlns="http://schemas.openxmlformats.org/'
+                      'spreadsheetml/2006/main" xmlns:r="http://schemas.openxmlformats.org/'
+                      'officeDocument/2006/relationships"><sheets><sheet name="Zones" sheetId="1" '
+                      'r:id="rId1"/></sheets></workbook>')
+        book.writestr("xl/worksheets/sheet1.xml",
+                      '<?xml version="1.0"?><worksheet xmlns="http://schemas.openxmlformats.org/'
+                      'spreadsheetml/2006/main"><sheetData>%s</sheetData></worksheet>' % rows)
+
+
+DOC_TABLE = [[("Dose table", 3)], [("Product", 1), ("Dose", 1), ("BBCH", 1)],
+             [("Moddus", 1), ("0.4", 1), ("31", 1)]]
+
+
+def synthetic_docx() -> bytes:
+    """A minimal .docx: one Heading1, one paragraph with a `w:br`, one table with a spanning row."""
+    def cell(text: str, span: int) -> str:
+        grid = '<w:tcPr><w:gridSpan w:val="%d"/></w:tcPr>' % span if span > 1 else ""
+        return "<w:tc>%s<w:p><w:r><w:t>%s</w:t></w:r></w:p></w:tc>" % (grid, text)
+    rows = "".join("<w:tr>%s</w:tr>" % "".join(cell(text, span) for text, span in row)
+                   for row in DOC_TABLE)
+    body = ('<w:p><w:pPr><w:pStyle w:val="Heading1"/></w:pPr><w:r><w:t>Growth regulators</w:t>'
+            '</w:r></w:p>'
+            '<w:p><w:r><w:t>first line</w:t><w:br/><w:t>second line</w:t></w:r>'
+            '<w:del><w:r><w:delText>struck out</w:delText></w:r></w:del></w:p>'
+            '<w:tbl>%s</w:tbl>' % rows)
+    stream = io.BytesIO()
+    with zipfile.ZipFile(stream, "w") as package:
+        package.writestr("[Content_Types].xml",
+                         '<?xml version="1.0"?><Types xmlns="http://schemas.openxmlformats.org/'
+                         'package/2006/content-types"><Default Extension="rels" ContentType='
+                         '"application/vnd.openxmlformats-package.relationships+xml"/><Override '
+                         'PartName="/word/document.xml" ContentType="application/vnd.'
+                         'openxmlformats-officedocument.wordprocessingml.document.main+xml"/>'
+                         '</Types>')
+        package.writestr("_rels/.rels",
+                         '<?xml version="1.0"?><Relationships xmlns="http://schemas.'
+                         'openxmlformats.org/package/2006/relationships"><Relationship Id="rId1" '
+                         'Type="http://schemas.openxmlformats.org/officeDocument/2006/'
+                         'relationships/officeDocument" Target="word/document.xml"/>'
+                         '</Relationships>')
+        package.writestr("word/document.xml",
+                         '<?xml version="1.0"?><w:document xmlns:w="http://schemas.'
+                         'openxmlformats.org/wordprocessingml/2006/main"><w:body>%s</w:body>'
+                         '</w:document>' % body)
+    return stream.getvalue()
+
+
+def synthetic_pptx() -> bytes:
+    """Return a one-slide presentation with a title and body text."""
+    stream = io.BytesIO()
+    with zipfile.ZipFile(stream, "w") as package:
+        package.writestr(
+            "_rels/.rels",
+            '<?xml version="1.0"?><Relationships xmlns="http://schemas.openxmlformats.org/'
+            'package/2006/relationships"><Relationship Id="rId1" Type="http://schemas.'
+            'openxmlformats.org/officeDocument/2006/relationships/officeDocument" '
+            'Target="ppt/presentation.xml"/></Relationships>',
+        )
+        package.writestr(
+            "ppt/presentation.xml",
+            '<p:presentation xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" '
+            'xmlns:r="http://schemas.openxmlformats.org/officeDocument/2006/relationships">'
+            '<p:sldIdLst><p:sldId id="256" r:id="rId1"/></p:sldIdLst></p:presentation>',
+        )
+        package.writestr(
+            "ppt/_rels/presentation.xml.rels",
+            '<Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">'
+            '<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/'
+            '2006/relationships/slide" Target="slides/slide1.xml"/></Relationships>',
+        )
+        package.writestr(
+            "ppt/slides/slide1.xml",
+            '<p:sld xmlns:p="http://schemas.openxmlformats.org/presentationml/2006/main" '
+            'xmlns:a="http://schemas.openxmlformats.org/drawingml/2006/main"><p:cSld><p:spTree>'
+            '<p:nvGrpSpPr/><p:grpSpPr/><p:sp><p:nvSpPr><p:cNvPr id="2" name="Title 1"/>'
+            '<p:cNvSpPr/><p:nvPr><p:ph type="title"/></p:nvPr></p:nvSpPr><p:spPr/>'
+            '<p:txBody><a:bodyPr/><a:lstStyle/><a:p><a:r><a:t>Harvest plan</a:t></a:r>'
+            '</a:p></p:txBody></p:sp><p:sp><p:nvSpPr><p:cNvPr id="3" name="Content 2"/>'
+            '<p:cNvSpPr/><p:nvPr><p:ph type="body"/></p:nvPr></p:nvSpPr><p:spPr/>'
+            '<p:txBody><a:bodyPr/><a:lstStyle/><a:p><a:r><a:t>North field</a:t></a:r>'
+            '</a:p></p:txBody></p:sp></p:spTree></p:cSld></p:sld>',
+        )
+    return stream.getvalue()
+
+
+def self_check() -> int:
+    """Render synthetic fixtures and compare against pinned expectations; 0 when green."""
+    failures, checks = [], []
+
+    def want(label, got, expected):
+        checks.append(label)
+        if got != expected:
+            failures.append("%s: got %r want %r" % (label, got, expected))
+
+    tally = new_tally()
+    want("sanitise folds and counts",
+         sanitise(" a b (cid:9) office dišerent­ \x01x – ≥", tally),
+         "- a b office diserent x - >=")
+    want("every class counted", (tally["dropped"]["pua_glyphs"], tally["dropped"]["nbsp"],
+                                 tally["dropped"]["cid_survivors"], tally["dropped"]["ligatures"],
+                                 tally["dropped"]["soft_hyphens"],
+                                 tally["dropped"]["control_chars"],
+                                 tally["broken_ligature_words"]),
+         (1, 1, 1, 1, 1, 1, 1))
+    want("a float keeps its spreadsheet form", cell_text(85.0), "85.0")
+    want("an empty cell is '' and renders empty", cell_text(""), "")
+    want("a date is one ISO day", cell_text(datetime.date(2026, 7, 18)), "2026-07-18")
+    want("a ragged table is padded, never cut", markdown_table([["a", "b"], ["c"]]),
+         ["| a | b |", "| --- | --- |", "| c |  |"])
+
+    with tempfile.TemporaryDirectory(prefix="brewdoc_docx_") as tmp:
+        doc_path = Path(tmp, "fixture.docx")
+        doc_path.write_bytes(synthetic_docx())
+        markdown, tally = render_doc(doc_path)
+        want("a Word heading opens its own chapter",
+             markdown.count('## Chapter 1: "Growth regulators"'), 1)
+        want("a w:br is a line break, and a deleted run is not carried",
+             chapter_lines(markdown, "Growth regulators")[:2], ["first line", "second line"])
+        want("a spanning cell is padded, so every column stays under its own head",
+             chapter_lines(markdown, "Growth regulators")[2:],
+             ["| Dose table |  |  |", "| --- | --- | --- |", "| Product | Dose | BBCH |",
+              "| Moddus | 0.4 | 31 |"])
+        want("the docx tally counts its chapter and its table",
+             (tally["chapters"], tally["tables"], tally["text_regions"]), (1, 1, 1))
+
+    with tempfile.TemporaryDirectory(prefix="brewdoc_pptx_") as tmp:
+        presentation_path = Path(tmp, "fixture.pptx")
+        presentation_path.write_bytes(synthetic_pptx())
+        markdown, tally = render_presentation(presentation_path)
+        want("a presentation title labels its slide once",
+             (markdown.count('## Slide 1: "Harvest plan"'),
+              chapter_lines(markdown, "Harvest plan")),
+             (1, ["North field"]))
+        want("the presentation tally counts its declared slide", tally["slides"], 1)
+        want("a presentation render is deterministic",
+             sha256(render_presentation(presentation_path)[0]), sha256(markdown))
+
+    with tempfile.TemporaryDirectory(prefix="brewdoc_") as tmp:
+        pdf_path = Path(tmp, "fixture.pdf")
+        pdf_path.write_bytes(synthetic_pdf(_fixture_pages()))
+        markdown, tally = render_pdf(pdf_path)
+        lines = markdown.splitlines()
+        want("the captioned unlined table recovers its cells",
+             lines[lines.index("| Zone | Area | Yield |") + 2], "| North | 12.5 | 4.10 |")
+        want("the blank rows the text strategy invents are gone",
+             markdown.count("|  |  |  |"), 0)
+        want("the caption stays prose", markdown.count("Table 1. Yield by zone."), 3)
+        want("two-column prose is read column by column",
+             lines[lines.index("left column line 0 of the body text here") + 1],
+             "left column line 1 of the body text here")
+        want("the region was split at the gutter", tally["columns_split"], 3)
+        want("the running head is dropped once per page",
+             (markdown.count("Seasonal Operations Manual"), tally["dropped"]["running_heads"]),
+             (0, 3))
+        want("the page number is dropped", tally["dropped"]["page_numbers"], 3)
+        want("determinism sha256", sha256(render_pdf(pdf_path)[0]), sha256(markdown))
+
+        ruled_path = Path(tmp, "ruled.pdf")
+        ruled_path.write_bytes(synthetic_pdf([FIXTURE_UNCLOSED, FIXTURE_SEGMENTED]))
+        ruled, _ = render_pdf(ruled_path)
+        want("a column closed on the header row alone is still read",
+             chapter_lines(ruled, "Page 1")[:5],
+             ["| Zone | Area | Yield |", "| --- | --- | --- |", "| North | 12.5 | 4.10 |",
+              "| South | 9.0 | 3.75 |", "| Salt | P2O5 | 1.0 |"])
+        want("a rule cut into one segment per column carries the grid",
+             chapter_lines(ruled, "Page 2")[:4],
+             ["| Crop | Zone | Area | Yield |", "| --- | --- | --- | --- |",
+              "| Maize | North | 12.5 | 4.10 |", "| Wheat | South | 9.0 | 3.75 |"])
+        want("a repaired ruling stays deterministic",
+             sha256(render_pdf(ruled_path)[0]), sha256(ruled))
+
+        scan = Path(tmp, "scan.pdf")
+        scan.write_bytes(synthetic_pdf(["0 0 0 rg 100 100 200 200 re f\n"] * 2, font=False))
+        rc, line, _ = run(scan)
+        want("a document with no text layer is refused by name",
+             (rc, line["file_ok"], line["reason"].split(" in ")[0]),
+             (EXIT_FAIL, False, "no text layer: 2 of 2 pages carry zero characters"))
+
+        book_path = Path(tmp, "fixture.xlsx")
+        _synthetic_xlsx(book_path)
+        book_md, book_tally = render_book(book_path)
+        want("one chapter per sheet",
+             [row for row in book_md.splitlines() if row.startswith("## Sheet ")],
+             ['## Sheet 1: "Zones"'])
+        want("the sheet's measured types survive",
+             chapter_lines(book_md, "Zones"),
+             ["| Zone | Area | Sown |", "| --- | --- | --- |",
+              "| North | 12.5 | 2026-07-18 |", "| South | 9.0 |  |"])
+        want("the sheet route counts its sheets", book_tally["sheets"], 1)
+        out = Path(tmp, "out.md")
+        rc, line, _ = run(book_path, out=out)
+        want("a written render is ASCII and re-readable",
+             (rc, line["route"], out.read_text(encoding="ascii") == book_md), (EXIT_OK, "sheet", True))
+        rc, line, _ = run(Path(tmp, "absent.pdf"))
+        want("a missing file names the path", (rc, line["reason"]),
+             (EXIT_FAIL, "no such file: %s" % Path(tmp, "absent.pdf")))
+
+        html_path = Path(tmp, "fixture.html")
+        html_path.write_bytes('<title>Static HTML</title><p>café 東京</p><table><tr><th>Zone</th>'
+                              '<th>Area</th></tr><tr><td>North</td><td>12.5</td></tr></table>'.encode("utf-8"))
+        rc, line, html_md = run(html_path)
+        if htmltext._SUPPORTED_RUNTIME:
+            want("HTML's native parser is available on supported CPython",
+                 (rc, line["file_ok"], line["route"], line["unit_kind"], line["units"]),
+                 (EXIT_OK, True, "html", "chapter", 1))
+            if rc == EXIT_OK:
+                want("HTML preserves Unicode prose and complete table cells",
+                     chapter_lines(html_md, "Static HTML"),
+                     ["café 東京", "| Zone | Area |", "| --- | --- |", r"| North | 12\.5 |"])
+                want("HTML counts its chapter, table and prose",
+                     (line["units"], line["tables"], line["text_regions"], line["unit_keys"]),
+                     (1, 1, 1, ["chapter/000001"]))
+                html_out = Path(tmp, "html.md")
+                second_rc, second_line, second_md = run(html_path, out=html_out)
+                want("HTML writes deterministic UTF-8 without a BOM",
+                     (second_rc, second_line["file_ok"], second_md,
+                      html_out.read_bytes() if second_rc == EXIT_OK else None),
+                     (EXIT_OK, True, html_md, html_md.encode("utf-8")))
+        else:
+            want("an unsupported HTML runtime explicitly refuses its static route",
+                 (rc, line["file_ok"], line["route"], line["unit_kind"], line["units"],
+                  line["reason"], html_md),
+                 (EXIT_FAIL, False, "html", "chapter", 0, "HTML requires CPython 3.12-3.14", ""))
+
+    for failure in failures:
+        print("FAIL %s" % failure)
+    print("self-check: %s (%d checks)" % ("FAIL" if failures else "ok", len(checks)))
+    return EXIT_FAIL if failures else EXIT_OK
+
+
+def chapter_lines(markdown: str, heading: str) -> list[str]:
+    """Return content under a plain heading or any registered unit display label."""
+    lines = markdown.splitlines()
+    label = ': "%s"' % _escape_markdown_text(heading)
+    unit_headings = tuple("## %s " % kind.title() for kind in UNIT_COUNTERS)
+    unit_anchor = r'<a id="brewdoc-(?:%s)-\d{6}"></a>' % "|".join(
+        re.escape(kind) for kind in UNIT_COUNTERS)
+    matched = next((index for index, line in enumerate(lines) if line == "## " + heading
+                    or (line.startswith(unit_headings) and line.endswith(label))),
+                   None)
+    if matched is None:
+        raise ValueError("chapter heading not found: %s" % heading)
+    start = matched + 1
+    rest = [index for index, line in enumerate(lines[start:], start)
+            if line.startswith("## ")
+            or re.match(unit_anchor, line)]
+    body = lines[start:rest[0]] if rest else lines[start:]
+    return [line for line in body if line.strip()]

brewdoc/service.py

@@ -0,0 +1,116 @@
+"""Service: suffix routes, `run` and its receipt line, output writes through `output`."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Mapping
+from pathlib import Path
+
+from brewdoc.common import MARKDOWN_SCHEMA, RECEIPT_SCHEMA, BrewdocError, Route, new_tally
+from brewdoc.docx import ROUTE as DOC_ROUTE
+from brewdoc.htmltext import ROUTE as HTML_ROUTE
+from brewdoc.output import _output_targets, _write_outputs
+from brewdoc.pdf import ROUTE as PDF_ROUTE
+from brewdoc.pptx import ROUTE as PRESENTATION_ROUTE
+from brewdoc.sheets import ROUTE as SHEET_ROUTE
+from brewdoc.sheets import _artifact_payloads, _sheet_selection
+
+EXIT_OK, EXIT_FAIL, EXIT_USAGE = 0, 1, 2
+
+
+def _route_map(*routes: Route) -> dict[str, Route]:
+    """Suffix -> route; two adapters claiming one suffix is a defect, not a last-one-wins race."""
+    table: dict[str, Route] = {}
+    for route in routes:
+        for suffix in route.suffixes:
+            if suffix in table:
+                raise BrewdocError("suffix '%s' is claimed by both the %s and %s routes"
+                                   % (suffix, table[suffix].name, route.name))
+            table[suffix] = route
+    return table
+
+
+ROUTES = _route_map(PDF_ROUTE, DOC_ROUTE, PRESENTATION_ROUTE, SHEET_ROUTE, HTML_ROUTE)
+SUFFIXES = " ".join(sorted(ROUTES))
+NO_ROUTE = Route("none", "none", (), None, ())
+
+
+def _route(path: Path) -> Route:
+    return ROUTES.get(path.suffix.lower(), NO_ROUTE)
+
+
+def _line(route: Route, file_ok: bool, reason: str, path, tally: dict | None = None,
+          out=None, unit_keys: tuple[str, ...] = (), artifacts: tuple[dict, ...] = (),
+          selected_sheets=None) -> dict:
+    tally = tally or new_tally()
+    line = {"file_ok": file_ok, "route": route.name, "reason": reason,
+            "source": Path(path).name, "out": str(out) if out else None,
+            "receipt_schema": RECEIPT_SCHEMA, "unit_kind": route.unit_kind,
+            "units": len(unit_keys), "tables": tally["tables"],
+            "text_regions": tally["text_regions"], "columns_split": tally["columns_split"],
+            "dropped": dict(tally["dropped"]),
+            "broken_ligature_words": tally["broken_ligature_words"],
+            "not_carried": list(route.not_carried)}
+    if file_ok:
+        line.update({"artifacts": list(artifacts), "markdown_schema": MARKDOWN_SCHEMA,
+                     "unit_keys": list(unit_keys)})
+        if selected_sheets is not None:
+            line["selected_sheets"] = list(selected_sheets)
+    return line
+
+
+def _artifact_output_pairs(artifact_outputs) -> tuple[tuple[str, Path, str], ...]:
+    """Validate a key -> path mapping; each pair keeps the caller's path text for the receipt."""
+    if artifact_outputs is None:
+        return ()
+    if not isinstance(artifact_outputs, Mapping):
+        raise BrewdocError("artifact outputs must map keys to paths")
+    pairs = []
+    for key, raw_path in artifact_outputs.items():
+        if not (isinstance(key, str) and key and isinstance(raw_path, (str, os.PathLike))
+                and str(raw_path)):
+            raise BrewdocError("malformed artifact assignment: %r" % ((key, raw_path),))
+        pairs.append((key, Path(raw_path), str(raw_path)))
+    return tuple(pairs)
+
+
+def run(path, out=None, *, sheets=None, artifact_outputs=None) -> tuple[int, dict, str]:
+    """(exit code, receipt, Markdown); every path returns a receipt, a refusal names what and where."""
+    path = Path(path)
+    route = _route(path)
+    if route.render is None:
+        return EXIT_FAIL, _line(route, False, "unsupported suffix '%s' in %s: brewdoc reads %s"
+                                % (path.suffix.lower(), path, SUFFIXES), path), ""
+    if not path.is_file():
+        return EXIT_FAIL, _line(route, False, "no such file: %s" % path, path), ""
+    try:
+        sheets = _sheet_selection(sheets)
+        pairs = _artifact_output_pairs(artifact_outputs)
+        if route.name != "sheet" and (sheets is not None or pairs):
+            raise BrewdocError("--sheet and --artifact are workbook-only options")
+        targets = _output_targets(path, out, pairs)
+        markdown, tally, unit_keys, references = route.render(path, sheets)
+        keys = tuple(key for key, _target, _shown in pairs)
+        listed = {item.key for item in references}
+        unknown = [key for key in keys if key not in listed]
+        if unknown:
+            raise BrewdocError("unknown artifact key: %s" % ", ".join(unknown))
+        payloads = ((markdown.encode("utf-8" if route.name == "html" else "ascii"),)
+                    if out is not None else ()) + _artifact_payloads(
+            path, sheets, references, keys)
+    except BrewdocError as exc:
+        return EXIT_FAIL, _line(route, False, str(exc), path), ""
+    except Exception as exc:                      # a third-party parser raises its own types
+        return EXIT_FAIL, _line(route, False, "%s unreadable: %s: %s: %s"
+                                % (route.name, path, type(exc).__name__, exc), path), ""
+    try:
+        _write_outputs(tuple(zip(targets, payloads)))
+    except (BrewdocError, OSError) as exc:
+        return EXIT_FAIL, _line(route, False, "output write failed: %s" % exc, path), ""
+    reason = "%s rendered: %d %ss, %d tables, %d text regions, %d column splits" % (
+        route.name, len(unit_keys), route.unit_kind, tally["tables"], tally["text_regions"],
+        tally["columns_split"])
+    shown = {key: text for key, _target, text in pairs}
+    receipt_artifacts = tuple(item.to_dict(shown.get(item.key)) for item in references)
+    return EXIT_OK, _line(route, True, reason, path, tally, out, unit_keys,
+                          receipt_artifacts, sheets), markdown