brewdoc 0.2.0__py3-none-any.whl

brewdoc/sheets.py

@@ -0,0 +1,341 @@
+"""Workbook adapter: cached sheet values, sheet selection, OOXML formulas and VBA projects."""
+
+from __future__ import annotations
+
+import contextlib
+import hashlib
+import json
+import xml.etree.ElementTree as ET
+import zipfile
+from collections.abc import Iterable
+from dataclasses import dataclass
+from pathlib import Path
+
+from python_calamine import CalamineWorkbook
+
+from brewdoc.common import (CAPABILITY_FIELDS, ArtifactRef, BrewdocError, Rendered, Route,
+                            _assemble, _local_name, _opc_main_part, _relationship_elements,
+                            _relationship_part, _relationships, _resolve_ooxml_part,
+                            _unit_anchor, _unit_key, _xml_part, cell_text, new_tally, reading,
+                            sanitise)
+
+FORMULA_SCHEMA = "brewdoc.formulas/1"
+FORMULA_SUFFIXES = (".xlsm", ".xlsx")
+VBA_SUFFIXES = (".xlsb", ".xlsm")
+
+VBA_PROJECT_KEY = "vba/project/000001"
+VBA_RELATIONSHIP_TYPE = "http://schemas.microsoft.com/office/2006/relationships/vbaProject"
+# The two project fixtures top out at 17,920 bytes; 16 MiB is the passive-read boundary.
+MAX_VBA_PROJECT_BYTES = 16 * 1024 * 1024
+
+
+@dataclass(frozen=True, slots=True)
+class CellFormula:
+    """A passive OOXML formula attached to one source cell."""
+
+    sheet: str
+    cell: str
+    formula: str
+    attributes: tuple[tuple[str, str], ...]
+
+    def to_dict(self) -> dict:
+        """Return a JSON-ready formula without changing its source text."""
+        return {"attributes": dict(self.attributes), "cell": self.cell,
+                "formula": self.formula, "sheet": self.sheet}
+
+
+@dataclass(frozen=True, slots=True)
+class FormulaArtifact:
+    """All recoverable formulas from one source worksheet."""
+
+    key: str
+    source_name: str
+    source_sha256: str
+    source_ordinal: int
+    sheet: str
+    formulas: tuple[CellFormula, ...]
+
+
+def _sheet_grid(rows, tally: dict) -> list[list[str]]:
+    # calamine trims trailing empty rows but not trailing empty columns; interior empty rows stay.
+    grid = [[sanitise(cell_text(cell), tally) for cell in row] for row in rows]
+    width = max((index + 1 for row in grid for index, cell in enumerate(row) if cell), default=0)
+    return [row[:width] for row in grid] if width else []
+
+
+def _sheet_selection(sheets) -> tuple | None:
+    """Freeze a public sheet selection once; None keeps every sheet."""
+    if sheets is None:
+        return None
+    if isinstance(sheets, (str, bytes)) or not isinstance(sheets, Iterable):
+        raise BrewdocError("sheet selection must be a sequence of names")
+    return tuple(sheets)
+
+
+def _select_sheets(available, sheets) -> tuple[tuple[int, str], ...]:
+    """Validate a selection and retain each sheet's one-based source ordinal."""
+    available = tuple(available)
+    if sheets is None:
+        requested = available
+    else:
+        requested = sheets
+        if not requested:
+            raise BrewdocError("sheet selection is empty")
+        if any(not isinstance(name, str) for name in requested):
+            raise BrewdocError("sheet selection names must be strings")
+        seen = set()
+        for name in requested:
+            if name in seen:
+                raise BrewdocError("duplicate sheet selection: %s" % name)
+            seen.add(name)
+        unknown = [name for name in requested if name not in available]
+        if unknown:
+            raise BrewdocError("unknown sheet selection: %s; available sheets: %s"
+                               % (", ".join(unknown), ", ".join(available)))
+    ordinals = {name: index for index, name in enumerate(available, 1)}
+    return tuple((ordinals[name], name) for name in requested)
+
+
+@contextlib.contextmanager
+def _workbook(path: Path):
+    """Open a workbook with calamine; its own error types become one BrewdocError."""
+    with reading(path, "spreadsheet"), CalamineWorkbook.from_path(str(path)) as book:
+        yield book
+
+
+def _render_book(path: Path, sheets) -> Rendered:
+    """Render selected cached values; the same frozen selection scopes the artifact inventory."""
+    tally = new_tally()
+    with _workbook(path) as book:
+        selected = _select_sheets(book.sheet_names, sheets)
+        source_units = len(book.sheet_names)
+        units = []
+        for ordinal, name in selected:
+            raw = book.get_sheet_by_name(name).to_python(skip_empty_area=False)
+            rows = _sheet_grid(raw, tally)
+            if rows:
+                tally["tables"] += 1
+            units.append((ordinal, name, [("table", rows)] if rows else []))
+    artifacts = _book_artifacts(path, sheets)
+    return _assemble(path, ROUTE.name, ROUTE.unit_kind, source_units, units, tally,
+                     not_carried=ROUTE.not_carried, artifacts=artifacts,
+                     capabilities=_book_capabilities(path.suffix.lower(), artifacts))
+
+
+ROUTE = Route("sheet", "sheet", (".ods", ".xls", ".xlsb", ".xlsm", ".xlsx"), _render_book,
+              ("cell formulas in Markdown content - only cached values are rendered",
+               "formatting, colours, comments and data validation",
+               "charts and embedded images",
+               "readable VBA source modules"))
+
+
+def render_book(path, *, sheets=None) -> tuple[str, dict]:
+    """Render cached values for selected sheets with full-source ordinal navigation."""
+    return _render_book(Path(path), _sheet_selection(sheets))[:2]
+
+
+def _book_capabilities(suffix: str, artifacts: tuple[ArtifactRef, ...]) -> tuple:
+    """Workbook formula and VBA rows; a reader the format lacks reports an unknown count."""
+    unknown = ("unavailable", "unknown")
+    formulas = sum(item.count for item in artifacts if item.kind == "formula")
+    projects = sum(item.kind == "vba-project" for item in artifacts)
+    values = ("available", str(formulas)) if suffix in FORMULA_SUFFIXES else unknown
+    values += ("available", str(projects)) if suffix in VBA_SUFFIXES else unknown
+    return tuple(zip(CAPABILITY_FIELDS, values + unknown))
+
+
+def _sheet_relation_id(element: ET.Element, name: str) -> str:
+    for key, value in element.attrib.items():
+        if _local_name(key) == "id":
+            return value
+    raise BrewdocError("worksheet relationship is missing for sheet %s" % name)
+
+
+def _formula_elements(root: ET.Element, sheet: str):
+    """Yield addressed formula elements in worksheet XML order."""
+    for cell in (element for element in root.iter() if _local_name(element.tag) == "c"):
+        formula = next((child for child in cell if _local_name(child.tag) == "f"), None)
+        if formula is None:
+            continue
+        address = cell.attrib.get("r")
+        if not address:
+            raise BrewdocError("formula cell address is missing in sheet %s" % sheet)
+        yield address, formula
+
+
+def _formula_cells(root: ET.Element, sheet: str) -> tuple[CellFormula, ...]:
+    """Read formula elements, including empty shared followers."""
+    return tuple(CellFormula(sheet, address, "".join(formula.itertext()),
+                             tuple(sorted(formula.attrib.items())))
+                 for address, formula in _formula_elements(root, sheet))
+
+
+def _read_formula_artifacts(path: Path, sheets, references=False) -> tuple:
+    """Read full artifacts or count-only `ArtifactRef`s with stable source ordinals."""
+    suffix = path.suffix.lower()
+    if suffix not in FORMULA_SUFFIXES:
+        raise BrewdocError("formula artifacts unavailable for '%s'; supported suffixes: %s"
+                           % (suffix, " ".join(FORMULA_SUFFIXES)))
+    try:
+        digest = None if references else hashlib.sha256(path.read_bytes()).hexdigest()
+        with zipfile.ZipFile(path) as package:
+            workbook_part = _opc_main_part(package)
+            workbook = _xml_part(package, workbook_part)
+            entries = []
+            for ordinal, element in enumerate(
+                    (node for node in workbook.iter() if _local_name(node.tag) == "sheet"), 1):
+                name = element.attrib.get("name")
+                if name is None:
+                    raise BrewdocError("OOXML worksheet name is missing")
+                entries.append((ordinal, name, _sheet_relation_id(element, name)))
+            selected = _select_sheets((name for _ordinal, name, _relation in entries), sheets)
+            by_name = {name: (ordinal, relation) for ordinal, name, relation in entries}
+            relationships = _relationships(package, _relationship_part(workbook_part))
+            artifacts = []
+            for _selected_ordinal, name in selected:
+                ordinal, relation_id = by_name[name]
+                relationship = relationships.get(relation_id)
+                if relationship is None:
+                    raise BrewdocError("worksheet relationship %s is missing for sheet %s"
+                                       % (relation_id, name))
+                if not relationship.attrib.get("Type", "").endswith("/worksheet"):
+                    continue
+                if relationship.attrib.get("TargetMode") == "External":
+                    raise BrewdocError("worksheet relationship is external for sheet %s" % name)
+                target = _resolve_ooxml_part(
+                    workbook_part, relationship.attrib.get("Target", ""))
+                root = _xml_part(package, target)
+                key = "formula/sheet/%06d" % ordinal
+                if references:
+                    count = sum(1 for _address, _formula in _formula_elements(root, name))
+                    if count:
+                        artifacts.append(ArtifactRef(
+                            key, "formula", "available", count,
+                            "#" + _unit_anchor(_unit_key("sheet", ordinal)), "application/json"))
+                else:
+                    formulas = _formula_cells(root, name)
+                    if formulas:
+                        artifacts.append(FormulaArtifact(
+                            key, path.name, digest, ordinal, name, formulas))
+            return tuple(artifacts)
+    except BrewdocError:
+        raise
+    except (OSError, zipfile.BadZipFile) as exc:
+        raise BrewdocError("formula artifact unreadable: %s: %s" % (path, exc)) from exc
+
+
+def read_formulas(path, *, sheets=None) -> tuple[FormulaArtifact, ...]:
+    """Read formula-bearing OOXML sheets as immutable keyed artifacts."""
+    return _read_formula_artifacts(Path(path), _sheet_selection(sheets))
+
+
+def _vba_relationship(package: zipfile.ZipFile, workbook_part: str) -> str | None:
+    """Return the package part of the single internal VBA relationship, or None."""
+    relationships = tuple(
+        relationship for relationship in _relationship_elements(
+            package, _relationship_part(workbook_part))
+        if relationship.attrib.get("Type") == VBA_RELATIONSHIP_TYPE
+    )
+    if len(relationships) > 1:
+        raise BrewdocError("multiple VBA project relationships")
+    if not relationships:
+        return None
+    relationship = relationships[0]
+    if relationship.attrib.get("TargetMode") == "External":
+        raise BrewdocError("VBA project relationship is external")
+    return _resolve_ooxml_part(workbook_part, relationship.attrib.get("Target", ""))
+
+
+def _vba_member(package: zipfile.ZipFile, package_part: str) -> bytes:
+    """Read one bounded project member; zipfile never yields more than its declared size."""
+    matches = tuple(info for info in package.infolist() if info.filename == package_part)
+    if not matches:
+        raise BrewdocError("OOXML part is missing: %s" % package_part)
+    if len(matches) > 1:
+        raise BrewdocError("OOXML part occurs more than once: %s" % package_part)
+    info = matches[0]
+    if info.flag_bits & 1:
+        raise BrewdocError("VBA project part is encrypted: %s" % package_part)
+    if info.file_size > MAX_VBA_PROJECT_BYTES:
+        raise BrewdocError("VBA project part exceeds %d bytes: %s"
+                           % (MAX_VBA_PROJECT_BYTES, package_part))
+    return package.read(info)
+
+
+def _vba_project(path: Path) -> bytes | None:
+    """Read the related opaque VBA project as exact bytes without parsing its streams."""
+    try:
+        with zipfile.ZipFile(path) as package:
+            package_part = _vba_relationship(package, _opc_main_part(package))
+            return None if package_part is None else _vba_member(package, package_part)
+    except BrewdocError:
+        raise
+    except (OSError, RuntimeError, zipfile.BadZipFile) as exc:
+        raise BrewdocError("VBA artifact unreadable: %s: %s" % (path, exc)) from exc
+
+
+def _workbook_suffix(path: Path) -> str:
+    """Return a workbook suffix or refuse the artifact capability before any read."""
+    suffix = path.suffix.lower()
+    if suffix not in ROUTE.suffixes:
+        raise BrewdocError("workbook artifacts unavailable for '%s'" % suffix)
+    return suffix
+
+
+def _book_artifacts(path: Path, sheets) -> tuple[ArtifactRef, ...]:
+    """Inventory selected formula sheets and the workbook-level VBA project; None selects all."""
+    suffix = _workbook_suffix(path)
+    artifacts = (_read_formula_artifacts(path, sheets, references=True)
+                 if suffix in FORMULA_SUFFIXES else ())
+    project = _vba_project(path) if suffix in VBA_SUFFIXES else None
+    if project is None:
+        return artifacts
+    return artifacts + (ArtifactRef(
+        VBA_PROJECT_KEY, "vba-project", "available", 1, "#brewdoc-metadata",
+        "application/vnd.ms-office.vbaProject", len(project), hashlib.sha256(project).hexdigest()),)
+
+
+def list_book_artifacts(path, *, sheets=None) -> tuple[ArtifactRef, ...]:
+    """List selected formula sheets and the workbook-level opaque VBA project."""
+    path = Path(path)
+    _workbook_suffix(path)
+    sheets = _sheet_selection(sheets)
+    with _workbook(path) as book:
+        _select_sheets(book.sheet_names, sheets)      # the value reader validates every format
+    return _book_artifacts(path, sheets)
+
+
+def _formula_json(path: Path, artifact: FormulaArtifact) -> bytes:
+    """Serialize one formula-bearing sheet as versioned deterministic ASCII JSON."""
+    payload = {
+        "formulas": [formula.to_dict() for formula in artifact.formulas],
+        "schema": FORMULA_SCHEMA,
+        "sheet": {"key": _unit_key("sheet", artifact.source_ordinal),
+                  "name": artifact.sheet, "ordinal": artifact.source_ordinal},
+        "source": {"bytes": path.stat().st_size, "name": path.name,
+                   "sha256": artifact.source_sha256, "suffix": path.suffix.lower()},
+    }
+    return (json.dumps(payload, ensure_ascii=True, sort_keys=True) + "\n").encode("ascii")
+
+
+def _artifact_payloads(path: Path, sheets, references: tuple[ArtifactRef, ...],
+                       keys: tuple[str, ...]) -> tuple[bytes, ...]:
+    """Serialize listed artifacts by key: formula JSON or exact VBA project bytes."""
+    kinds = [next((item.kind for item in references if item.key == key), None) for key in keys]
+    formulas = ({item.key: item for item in _read_formula_artifacts(path, sheets)}
+                if "formula" in kinds else {})
+    payloads = []
+    for key, kind in zip(keys, kinds):
+        payload = (_formula_json(path, formulas[key]) if kind == "formula" and key in formulas
+                   else _vba_project(path) if kind == "vba-project" else None)
+        if payload is None:
+            raise BrewdocError("workbook artifact not found: %s" % key)
+        payloads.append(payload)
+    return tuple(payloads)
+
+
+def read_book_artifact(path, key: str, *, sheets=None) -> bytes:
+    """Return deterministic formula JSON or exact opaque VBA project bytes by key."""
+    path = Path(path)
+    sheets = _sheet_selection(sheets)
+    return _artifact_payloads(path, sheets, list_book_artifacts(path, sheets=sheets), (key,))[0]

brewdoc-0.2.0.dist-info/METADATA

@@ -0,0 +1,232 @@
+Metadata-Version: 2.5
+Name: brewdoc
+Version: 0.2.0
+Summary: Brew any document into LLM-ready Markdown: PDF tables, spreadsheets, docx - no ML, deterministic, with a JSON receipt
+Project-URL: Homepage, https://github.com/kochetkov-ma/brewdoc
+Project-URL: Repository, https://github.com/kochetkov-ma/brewdoc
+Project-URL: Issues, https://github.com/kochetkov-ma/brewdoc/issues
+Author-email: Maksim Kochetkov <apmatypa88@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: docx,llm,markdown,pdf,rag,table-extraction,xlsx
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Text Processing :: Markup :: Markdown
+Requires-Python: >=3.12
+Requires-Dist: pdfplumber==0.11.10
+Requires-Dist: python-calamine==0.8.2
+Requires-Dist: selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'
+Description-Content-Type: text/markdown
+
+# brewdoc
+
+Document to Markdown for agent systems: PDF, Word, PPTX presentations, spreadsheets and static
+HTML in, one Markdown file plus a JSON receipt out. No models, no OCR, no network,
+deterministic (same file, same bytes). The receipt says what was rendered,
+what was dropped and what the route structurally cannot carry, so an agent never mistakes a
+silent gap for "the document does not say so".
+
+## Install
+
+| channel | command |
+|---|---|
+| pip | `pip install brewdoc==0.2.0` |
+| uvx | `uvx brewdoc==0.2.0 file.pdf` |
+| uv tool | `uv tool install brewdoc==0.2.0` |
+| Docker | `RUN pip install brewdoc==0.2.0` |
+
+Alternative, straight from git (no PyPI round-trip):
+
+```
+uvx --from git+https://github.com/kochetkov-ma/brewdoc@v0.2.0 brewdoc file.pdf
+```
+
+Requires Python >= 3.12. Base runtime dependencies: `pdfplumber` (pulls pypdfium2, Pillow,
+cryptography) and `python-calamine`. HTML requires CPython 3.12-3.14 and the native Lexbor
+parser from this exact conditional dependency:
+
+```text
+selectolax==0.4.13; python_version < '3.15' and platform_python_implementation == 'CPython'
+```
+
+Other runtimes retain the `.html` route and Python API but explicitly refuse HTML. On supported
+CPython, a missing or broken parser is an environment failure and `--self-check` exits 1.
+On an unsupported HTML runtime, self-check verifies HTML refusal and checks all other formats.
+
+## Usage
+
+```
+brewdoc file.pdf --out file.md
+brewdoc slides.pptx --out slides.md
+brewdoc page.html --out page.md
+brewdoc file.xlsx                # no --out: receipt line, then the Markdown, on stdout
+brewdoc file.xlsx --sheet Calc --sheet Inputs
+brewdoc file.xlsm --artifact formula/sheet/000002=formulas.json
+brewdoc file.xlsm --artifact vba/project/000001=vbaProject.bin
+brewdoc --self-check             # renders synthetic fixtures twice, compares sha256, exit 0 when green
+```
+
+`--sheet` is repeatable. Names are exact and case-sensitive. Output follows caller order while
+keeping each sheet's full-workbook ordinal. `--artifact` is also repeatable. Use keys listed in the
+Markdown artifact table. Both options are workbook-only. brewdoc validates every request and
+output collision before writing.
+
+Every successful document uses `brewdoc.markdown/2`. A quoted source title is followed by Metadata,
+Artifacts, Known omissions, Contents, then anchored content units. PDF keys are `page/000001`,
+workbook keys are `sheet/000001`, DOCX keys are `chapter/000001`, PPTX keys are `slide/000001`,
+and HTML has one `chapter/000001`.
+Metadata contains deterministic source identity, selection, content hashes, conversion tallies, and
+artifact capabilities. It excludes paths, timestamps, permissions, host data, and unsupported author
+metadata.
+
+One JSON receipt line always goes to stdout first (wrapped here, `unit_keys` omitted):
+
+```json
+{"artifacts": [], "broken_ligature_words": 0, "columns_split": 1,
+ "dropped": {"cid_survivors": 0, "control_chars": 0, "ligatures": 0, "nbsp": 0,
+             "non_ascii_replaced": 0, "page_numbers": 3, "pua_glyphs": 0,
+             "running_heads": 0, "soft_hyphens": 0},
+ "file_ok": true, "markdown_schema": "brewdoc.markdown/2",
+ "not_carried": ["images, figures and the text drawn inside them",
+                 "a table that spans a page break",
+                 "text rotated out of the horizontal reading order"],
+ "out": "file.md",
+ "reason": "pdf rendered: 7 pages, 1 tables, 26 text regions, 1 column splits",
+ "receipt_schema": "brewdoc.receipt/1",
+ "route": "pdf", "source": "nist-sp800-145.pdf", "tables": 1,
+ "text_regions": 26, "unit_kind": "page", "units": 7}
+```
+
+| key | meaning |
+|---|---|
+| `file_ok`, `reason` | `false` when the file was refused (no text layer, unreadable, unsupported suffix); `reason` names why, or summarises what was rendered |
+| `route` | which reader ran: `pdf`, `doc`, `presentation`, `sheet` or `html` |
+| `source` | the input file name, without its directory |
+| `unit_kind`, `units` | the route's content unit and how many were rendered; one pair for every format. `page` for PDF, `chapter` for DOCX and HTML, `slide` for PPTX, `sheet` for a workbook, and `none` on a suffix brewdoc does not read |
+| `tables`, `text_regions`, `columns_split` | what else was rendered |
+| `receipt_schema` | the receipt key contract; `brewdoc.receipt/1` replaced the per-format `pages` and `sheets` counters |
+| `broken_ligature_words` | words with a ligature the font mapped to a stray code point, folded to ASCII, not repaired |
+| `dropped` | sanitised items removed on purpose, counted by kind (running heads, page numbers, ...) |
+| `not_carried` | what this route structurally cannot represent - read it before concluding a fact is absent |
+| `out` | the Markdown path, or `null` when it went to stdout |
+| `markdown_schema`, `unit_keys` | the contract and ordered full-source content keys; success only |
+| `artifacts` | available keyed formula or opaque VBA outputs and requested output paths; success only |
+| `selected_sheets` | the `--sheet` names in caller order; present only when sheets were selected |
+
+Paths resolve against the current working directory; `--out` creates parent directories.
+Exit code is non-zero on refusal; the receipt line is still printed.
+
+## Formats
+
+| in | reader | notes |
+|---|---|---|
+| `.pdf` | pdfplumber | needs a text layer; route chosen per region, never per page |
+| `.docx` | stdlib zip + XML | paragraphs and tables |
+| `.pptx` | stdlib zip + XML | slides in declared order; text, tables, notes and picture metadata |
+| `.xlsx` `.xlsm` `.xls` `.xlsb` `.ods` | python-calamine | selected sheets keep full-source ordinals; numbers as stored (`85.0`), dates as ISO days |
+| `.html` | selectolax Lexbor | full static body or fragment, complete tables and source-declared controls; CPython 3.12-3.14 |
+
+`.xlsx` and `.xlsm` expose original OOXML formulas as one deterministic JSON artifact per
+formula-bearing selected sheet. Markdown still contains cached values. `.xlsm` and `.xlsb` can expose
+one complete related `vbaProject.bin` as opaque bytes. brewdoc does not execute macros, decompile VBA,
+report source-module counts, evaluate formulas, or infer dependency graphs.
+
+HTML reads local strict UTF-8, with an optional BOM. It preserves meaningful Unicode, navigation,
+main content, sidebars and footers in recovered DOM order. It never fetches links or resources,
+executes scripts, submits forms or infers interactive values. Links use a restricted scheme policy;
+form actions remain inert metadata. Inline code outside tables becomes a literal fenced block;
+surrounding emphasis and links remain balanced. Safe links in literal code and around code/images
+retain destination records without changing the source literals. Table-cell code uses labelled
+escaped text. Quotes and list items containing standalone child blocks use explicit nesting
+boundaries in place of visual Markdown
+containers. Plain list paragraphs retain their item marker and continuation indentation.
+See [HTML scope and limits](FORMATS.md#static-html).
+
+The public Python API exposes HTML and presentation rendering and generic workbook artifact access:
+
+```python
+import brewdoc
+
+markdown, tally = brewdoc.render_html("page.html")
+code, receipt, markdown = brewdoc.run("page.html", out="page.md")
+markdown, tally = brewdoc.render_presentation("slides.pptx")
+refs = brewdoc.list_book_artifacts("book.xlsm", sheets=("Calc",))
+payload = brewdoc.read_book_artifact("book.xlsm", refs[0].key, sheets=("Calc",))
+code, receipt, markdown = brewdoc.run(
+    "book.xlsm", out="book.md", sheets=("Calc",),
+    artifact_outputs={refs[0].key: "formulas.json"},
+)
+```
+
+`artifact_outputs` maps artifact keys to paths. The CLI builds it from repeated `--artifact KEY=PATH`.
+
+Planned formats, deferred ones and the never-list: `FORMATS.md`.
+A planned format is refused by name today. The adapter contract and the ordered checklist for
+adding one are in [`docs/architecture.md`](docs/architecture.md).
+
+PDF regions, in the order tried:
+
+| region looks like | rendered as |
+|---|---|
+| ruled on all sides | Markdown table from the drawn ruling |
+| ruling unfinished (cells never closed) | re-read on the grid the ruling implies, kept only when it carries more text than the drawn ruling did |
+| ruled across only (head and foot rules) | column grid from the rule segment ends |
+| unruled, tabular band | layout-preserved text |
+| unruled, captioned `Table N` | the band is bounded first (caption to next blank band), then read as a table |
+| two-column prose | split at the gutter (relative density on the character x-histogram), left then right |
+| plain prose | lines |
+
+## What it does not do
+
+| gap | behaviour |
+|---|---|
+| OCR | a PDF with no text layer is refused by name, never rendered empty |
+| PDF and DOCX images, figures, text drawn inside them | not carried; listed in `not_carried` |
+| PPTX pictures | represented by deterministic name, size, alt text, caption, source and byte-count placeholders; pixels are never emitted |
+| PPTX charts, SmartArt, audio, video and embedded objects | not carried; listed in `not_carried` |
+| a table spanning a page break | columns recovered, wrapped rows stay separate rows |
+| text rotated out of horizontal reading order | not carried |
+| sub/superscripts | folded back into their line (`NH4H2PO4`, not `NHHPO` over `4 2 4`) |
+| broken font CMaps (ligatures mapped to wrong code points) | counted (`broken_ligature_words`), folded to ASCII, never guessed back |
+| formula calculation | cached values in Markdown; passive source formulas only for `.xlsx` and `.xlsm` |
+| readable VBA source | unavailable; `.xlsm` and `.xlsb` preserve a related project only as opaque bytes |
+
+## Determinism
+
+No timestamps or unordered iteration. Two renders of one file have the same sha256;
+`--self-check` pins it. PDF, DOCX, PPTX and workbook output remains ASCII. HTML Markdown uses
+UTF-8 without BOM and LF newlines, with the same bytes in the API, file output and CLI stdout.
+Receipt JSON keeps ASCII escaping.
+
+## Size and speed
+
+These measurements cover the existing PDF/workbook baseline before the HTML parser addition.
+They do not measure HTML conversion or the new installed footprint.
+
+| measure | value |
+|---|---|
+| installed footprint | ~45 MB (pdfplumber, pypdfium2, Pillow, cryptography, python-calamine) |
+| import | 0.08 s |
+| 130-page PDF | ~5.5 s |
+| 14-sheet xlsx | ~0.9 s |
+
+## Benchmarks
+
+Browse the [corpus catalog](benchmarks/CATALOG.md), follow the
+[measurement method](benchmarks/METHODOLOGY.md), and inspect the
+[full-run results](benchmarks/results/README.md). Completed runs include actual
+outputs and known failures; capture completion does not mean content quality passed.
+
+## Releasing
+
+Tag-triggered, see `RELEASING.md`.
+
+## License
+
+MIT, see `LICENSE`.

brewdoc-0.2.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+brewdoc/__init__.py,sha256=G1bE3W5rODBYROJlc4gKi1gmYLaPCupk2M2COVl6SPI,815
+brewdoc/cli.py,sha256=bpkQQbmQNL5KEx3kEUq5zR3_kjzIBLaINTj-BqFQc_g,4796
+brewdoc/common.py,sha256=2rADIDAIrv7clZzbNlI0fx6F3Xe6Qpym-1NCVXOQcIM,17088
+brewdoc/docx.py,sha256=18PfJtjqmD1E_OL6W4aj3wfccgm_FWQD2zTN1z-sz_o,5021
+brewdoc/htmltext.py,sha256=eKBO-MIe6-UgcIL9x1pbSKJD98TBEw239TOFu9yf9Js,36997
+brewdoc/output.py,sha256=aMgDoB5UDbRWYr9pBxlH402jEiUl8OSEqhox31O0ljk,4123
+brewdoc/pdf.py,sha256=TcLqUpqibwiLwed2F01I1nblhWTfnKN3B5FFgkttJDM,58652
+brewdoc/pptx.py,sha256=t6-0o7okV5hWVtnbFLJ9xrzbYjMFbxT3kvOgyUIgqvY,17167
+brewdoc/selfcheck.py,sha256=tVG5MTAFXTB-F2yhxfW1QpksERqHv6K8Gb3TRt-HKSs,21642
+brewdoc/service.py,sha256=NqVZlZR8YGYXBFtT4uaYDlTdv259bbJmSah1J5l9GS0,5694
+brewdoc/sheets.py,sha256=oVlUf3QRm9W9JzKCqvLxAXF0HwTxvCH8DXgvkVoUSYI,15720
+brewdoc-0.2.0.dist-info/METADATA,sha256=A8SeR30ItMOlr6YMs3jjpaWDwlbVrktxSEoeNCc8NPo,11989
+brewdoc-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+brewdoc-0.2.0.dist-info/entry_points.txt,sha256=avLrj5Y-MJ1yq0XFkjH5dbZW9QwYQkpn_hz6sNydbA4,45
+brewdoc-0.2.0.dist-info/licenses/LICENSE,sha256=DNUrRveB3NXcyWxUr8csAHYmvrOmAzFDDAKv3iXNYKk,1073
+brewdoc-0.2.0.dist-info/RECORD,,

brewdoc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

brewdoc-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+brewdoc = brewdoc.cli:main

brewdoc-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Maksim Kochetkov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.