Claude Opus 4.8
aaa9a253ae
Make the "structure-true best effort" fidelity contract (ADR 0009) an objective, pipeline-gated suite so "best effort" cannot erode silently. - New CI job "Import/export fidelity gate" (.gitea/workflows/ci.yml) runs the corpus suites against the pinned sidecar images the stages use (pandoc/core:3.6, gotenberg/gotenberg:8), started via docker run and reached over the host gateway. Small and separate so it stays well under five minutes; the suites self-skip in the main checks job (no sidecars). - Export fidelity: fixtures/export corpus + gen-export-fixtures.mjs + export.fidelity.test.ts — exports Markdown to docx/odt through the real pinned pandoc and reads it back, snapshotting the round trip so a writer drift (ours or a version bump) fails the gate. - PDF smoke: pdf.fidelity.test.ts renders a page through real Gotenberg and asserts the extracted text and a sane page count (pdf-parse, dev-only). - Fidelity contract doc: fixtures/README.md defines "corpus green = fidelity acceptable" and the fixture-first bug process; per-corpus READMEs updated. Because the snapshots are byte-exact and generated with the pinned tools, bumping a sidecar without regenerating shifts the output and fails the suite (AC3). The import corpus (#63) is folded into the same gate. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EwZ4jR4KFAPvpjWevfUGX1
2.2 KiB
Import fixture corpus (issue #63, ADR 0009)
Representative .docx/.odt documents and the Markdown our import pipeline is
expected to produce from them. import.fixtures.test.ts runs the real two-pass
pandoc conversion over each and asserts the result, so a change in behaviour
(ours or pandoc's) surfaces as a snapshot diff to review — not a silent
regression. This suite is part of the CI fidelity gate (issue #69); see
../README.md for the fidelity contract and the fixture-first
bug process (how a fidelity bug becomes a new corpus fixture).
Files
For each document <name> and format <ext> (docx, odt):
<name>.<ext>— the source document.<name>.<ext>.expected.md— the Markdown the pipeline produces, with every embedded image'sdata:URI normalised to the literaldata:embedded-image(the base64 payload is volatile and not what the snapshot is pinning).
article covers headings, paragraphs, bold/italic, a link, a bullet list
with nesting, an ordered list, an embedded image, and a table. formatting
covers strikethrough, inline code, a blockquote, and three levels of nesting.
Fidelity notes (structure, not layout — ADR 0009)
- ODT images lose their alt text and ODT tables lose their header row: pandoc's HTML→ODT writer does not encode either, so the source documents genuinely lack them. The DOCX variants keep both. This is a pinned pandoc limitation, not an import bug — extend the corpus rather than chasing it.
Limits (ADR 0009)
An uploaded document may be at most 25 MiB (MAX_CONVERSION_INPUT_BYTES),
and each of the two conversion passes may run for at most 60 s
(CONVERSION_TIMEOUT_MS). A ~50-page document converts well inside that ceiling
(import.fixtures.test.ts asserts it); a document that exceeds the timeout fails
the job with converter_timeout.
Regenerating
The documents and snapshots are generated with the pinned pandoc/core:3.6
(the production sidecar) so the snapshots match CI; a different pandoc version
wraps lists and pads tables differently. scripts/gen-import-fixtures.mjs
regenerates everything against a reachable pandoc sidecar (PANDOC_URL).