refactor(pdf): R4.8 the TypeScript PDF engine leaves: packages/pdf, pdf-lib, the TS CLI and import path, the oracle generators deleted; test read-back on an own reader of the writer's files (pdfFile.ts), view goldens from the session's SVGs, import helper on the module's reader, N-1 scanner exported by core-wasm/n-1; app no longer depends on @faunosteo/domain; r4.census suite

This commit is contained in:
bchanot committed 2026-10-19 12:17:01 +02:00
1 parent 77e11a53e4
commit 0dc1ba27c7
96 files changed
+743 -15769

No files matched your search

+1 -1
View File
@@ -1,7 +1,7 @@
import { readFileSync } from 'node:fs'
import { resolve } from 'node:path'
import type { Report } from '@faunosteo/core-wasm/types'
import { importAttachment } from '@/pdf/import'
import { importAttachment } from './pdfImport'
import type { SheetIndex } from '@/services/sheetIndex'
import { FIXTURES_DIR } from './goldens'
import {
+51 -103
View File
@@ -1,36 +1,26 @@
import { createHash } from 'node:crypto'
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { fileURLToPath } from 'node:url'
import { dirname, resolve } from 'node:path'
import { expect, vi } from 'vitest'
import {
PDFArray,
PDFDict,
PDFDocument,
PDFHexString,
PDFName,
PDFNumber,
PDFPage,
PDFString,
} from 'pdf-lib'
import type {
Branding,
Observation,
Report,
SheetSnapshot,
} from '@faunosteo/core-wasm/types'
import { composeHighlightedViewSvg } from '@faunosteo/pdf'
/** The engine's own (Zod-inferred) types of the same JSON contracts. */
type EngineView = Parameters<typeof composeHighlightedViewSvg>
import { PdfFile, nameOf, numbersOf, subDict, textOf } from './pdfFile'
import { nologosBranding } from './sheet'
/**
* Step 6 Phase 0 freeze: what the PDF pipeline drew before the engine,
* recorded as JSON goldens (docs/development/STEP6_PDF_ARCHIVE_ANALYSIS.md
* §17) that the app export path must still reproduce. The recorder spies on
* pdf-lib, the link reader parses the saved bytes, the view snapshot parses
* the engine's highlighted SVG with the browser DOM. Numbers are rounded to
* 2 decimals; nothing ordered by drawing order is sorted.
* §17) that the app export path must still reproduce. Since R4.8 the text
* and image facts are read back from the file's content streams
* (`pdfRead.ts`), the links from its annotations (`pdfFile.ts`), and the
* view snapshot parses the SVG the core's session asked the rasteriser for,
* with the browser DOM. Numbers are rounded to 2 decimals; nothing ordered
* by drawing order is sorted.
*/
/** 1×1 PNG (nologos: the legacy stub) and 2×1 PNG (logos: deterministic partner logo width). */
@@ -53,6 +43,13 @@ export const GOLDEN_DIR = resolve(FIXTURES_DIR, 'goldens/step6')
/** `MAKE_GOLDEN=1` writes the goldens instead of asserting them. */
export const MAKE_GOLDEN = process.env.MAKE_GOLDEN === '1'
/** The R4 digests of the writer's own bytes (`goldens/r4/pdf.*.sha256`), frozen by the cargo suite. */
export const R4_GOLDEN_DIR = resolve(FIXTURES_DIR, 'goldens/r4')
/** The export time of every R4 run (the engine suites' `FIXED_EXPORTED_AT` at the freeze). */
export const FIXED_EXPORTED_AT = new Date('2026-10-11T12:00:00.000Z')
export const sha256 = (data: Uint8Array | string): string =>
createHash('sha256').update(data).digest('hex')
export type LogoMode = 'nologos' | 'logos'
@@ -106,82 +103,19 @@ export function round2(value: unknown): number | null {
return typeof value === 'number' ? Math.round(value * 100) / 100 : null
}
/** Pages are appended in order and never moved: the index at draw time is final. */
function pageIndex(page: PDFPage): number {
return page.doc.getPages().indexOf(page)
}
export interface DrawRecording {
texts: TextEntry[]
images: ImageEntry[]
stop(): void
}
/** Records every drawText / drawImage while letting pdf-lib draw for real. */
export function recordDrawing(): DrawRecording {
const texts: TextEntry[] = []
const images: ImageEntry[] = []
const drawText = PDFPage.prototype.drawText
const drawImage = PDFPage.prototype.drawImage
const textSpy = vi
.spyOn(PDFPage.prototype, 'drawText')
.mockImplementation(function (this: PDFPage, text, options) {
texts.push({
page: pageIndex(this),
text,
x: round2(options?.x),
y: round2(options?.y),
size: round2(options?.size),
font: options?.font?.name ?? null,
})
return drawText.call(this, text, options)
})
const imageSpy = vi
.spyOn(PDFPage.prototype, 'drawImage')
.mockImplementation(function (this: PDFPage, image, options) {
images.push({
page: pageIndex(this),
x: round2(options?.x),
y: round2(options?.y),
width: round2(options?.width),
height: round2(options?.height),
})
return drawImage.call(this, image, options)
})
return {
texts,
images,
stop: () => {
textSpy.mockRestore()
imageSpy.mockRestore()
},
}
}
function linkOf(dict: PDFDict, page: number): LinkEntry | null {
if (dict.get(PDFName.of('Subtype')) !== PDFName.of('Link')) return null
const rect = dict
.lookup(PDFName.of('Rect'), PDFArray)
.asArray()
.map((n) => round2((n as PDFNumber).asNumber()) ?? 0)
const uri = dict.lookup(PDFName.of('A'), PDFDict).lookup(PDFName.of('URI'))
const text =
uri instanceof PDFString || uri instanceof PDFHexString
? uri.decodeText()
: String(uri)
return { page, rect, uri: text }
}
/** Every `/Annot /Link` of the saved PDF, page by page, in annotation order. */
export async function readLinks(bytes: Uint8Array): Promise<LinkEntry[]> {
const doc = await PDFDocument.load(bytes)
const file = PdfFile.parse(bytes)
const out: LinkEntry[] = []
doc.getPages().forEach((page, index) => {
const annots = page.node.Annots()
if (!annots) return
for (let i = 0; i < annots.size(); i += 1) {
const link = linkOf(annots.lookup(i, PDFDict), index)
if (link) out.push(link)
file.pages().forEach((page, index) => {
for (const annot of file.annots(page)) {
if (nameOf(annot.dict, 'Subtype') !== 'Link') continue
const action = subDict(annot.dict, 'A') ?? ''
out.push({
page: index,
rect: numbersOf(annot.dict, 'Rect').map((n) => round2(n) ?? 0),
uri: textOf(action, 'URI') ?? '',
})
}
})
return out
@@ -239,22 +173,18 @@ function countDataAttributes(root: Element): number {
)
}
/** The facts of one composed view, from the SVG the core's session asked the rasteriser for. */
export function snapshotView(
sheet: SheetSnapshot,
observation: Observation,
observationId: string,
viewId: string,
svg: string,
): ViewSnapshot {
const svg = composeHighlightedViewSvg(
sheet as EngineView[0],
viewId,
observation as EngineView[2],
)
const root = new DOMParser().parseFromString(
svg,
'image/svg+xml',
).documentElement
return {
observationId: observation.id,
observationId,
viewId,
viewBox: root.getAttribute('viewBox'),
halo: root.querySelector('filter#osteo-halo') !== null,
@@ -279,14 +209,32 @@ export function viewIdsOf(
.sort((a, b) => Number(b === main) - Number(a === main))
}
/** The (observation, view) pairs an export rasterises, in the session's request order. */
export function viewPairsOf(
sheet: SheetSnapshot,
report: Report,
): { observationId: string; viewId: string }[] {
return report.observations.flatMap((observation) =>
viewIdsOf(sheet, observation).map((viewId) => ({
observationId: observation.id,
viewId,
})),
)
}
/**
* The view snapshots of an export: `svgs` are the view SVGs the session asked the
* rasteriser for (every logo raster excluded), in request order, one per pair.
*/
export function snapshotViews(
sheet: SheetSnapshot,
report: Report,
svgs: readonly string[],
): ViewSnapshot[] {
return report.observations.flatMap((observation) =>
viewIdsOf(sheet, observation).map((viewId) =>
snapshotView(sheet, observation, viewId),
),
const pairs = viewPairsOf(sheet, report)
expect(svgs).toHaveLength(pairs.length)
return pairs.map((pair, i) =>
snapshotView(pair.observationId, pair.viewId, svgs[i]!),
)
}
+285
View File
@@ -0,0 +1,285 @@
import { inflateSync } from 'node:zlib'
/**
* A reader of the files the core's writer produces (R4.8: pdf-lib left the application
* and its tests; `crates/core/src/pdf/write/{objects,serialize}.rs` is the format). Test
* tooling only, on trusted bytes the tests just wrote: every object is `N 0 obj`, one
* dictionary on one line (`<< /Key value … >>`, nested dictionaries inline, strings in hex),
* an optional `stream` of the direct `/Length` bytes, then `endobj`; the page tree is one
* `/Pages` node whose `/Kids` lists the pages in order. Nothing here parses a foreign PDF:
* the application reads attachments with the core's scanner.
*/
export interface PdfObject {
number: number
/** The dictionary text, `<<` to `>>` inclusive. */
dict: string
/** The raw stream bytes (not inflated), when the object is a stream. */
stream: Uint8Array | null
}
const latin1 = new TextDecoder('latin1')
/** The end of the dictionary that opens at `start` (`<<`): strings and nesting skipped. */
function dictEnd(text: string, start: number): number {
let depth = 0
let at = start
while (at < text.length) {
const two = text.slice(at, at + 2)
if (two === '<<') {
depth += 1
at += 2
} else if (two === '>>') {
depth -= 1
at += 2
if (depth === 0) return at
} else if (text[at] === '<') {
at = text.indexOf('>', at) + 1
} else if (text[at] === '(') {
at = text.indexOf(')', at) + 1
} else {
at += 1
}
}
throw new Error('unterminated dictionary')
}
function lengthOf(dict: string): number {
const match = /\/Length (\d+)/.exec(dict)
if (!match) throw new Error('stream without /Length')
return Number(match[1])
}
/** The objects of the file, by number. */
export function parsePdf(bytes: Uint8Array): Map<number, PdfObject> {
const text = latin1.decode(bytes)
const objects = new Map<number, PdfObject>()
const header = /(\d+) 0 obj\n/g
let match: RegExpExecArray | null
while ((match = header.exec(text)) !== null) {
const number = Number(match[1])
const start = header.lastIndex
if (text.slice(start, start + 2) !== '<<') continue
const end = dictEnd(text, start)
const dict = text.slice(start, end)
let stream: Uint8Array | null = null
const marker = '\nstream\n'
if (text.slice(end, end + marker.length) === marker) {
const from = end + marker.length
stream = bytes.slice(from, from + lengthOf(dict))
header.lastIndex = from + stream.length
}
objects.set(number, { number, dict, stream })
}
return objects
}
/** The decoded stream of an object: inflated when `/Filter /FlateDecode`. */
export function streamOf(object: PdfObject): Uint8Array {
if (!object.stream) throw new Error(`object ${object.number} is not a stream`)
return object.dict.includes('/Filter /FlateDecode')
? new Uint8Array(inflateSync(object.stream))
: object.stream
}
/** The text of a nested dictionary value (`/Key << … >>`). */
export function subDict(dict: string, key: string): string | null {
const at = dict.indexOf(`/${key} <<`)
if (at < 0) return null
const start = at + key.length + 2
return dict.slice(start, dictEnd(dict, start))
}
/** `/Key N 0 R` → N. */
export function refOf(dict: string, key: string): number | null {
const match = new RegExp(`/${key} (\\d+) 0 R`).exec(dict)
return match ? Number(match[1]) : null
}
/** `/Key [N 0 R M 0 R …]` → [N, M, …]. */
export function refsOf(dict: string, key: string): number[] {
const match = new RegExp(`/${key} \\[([^\\]]*)\\]`).exec(dict)
if (!match) return []
return [...match[1]!.matchAll(/(\d+) 0 R/g)].map((m) => Number(m[1]))
}
/** `/Key /Name` → Name. */
export function nameOf(dict: string, key: string): string | null {
const match = new RegExp(`/${key} /([^\\s/>]+)`).exec(dict)
return match ? match[1]! : null
}
export function numberOf(dict: string, key: string): number | null {
const match = new RegExp(`/${key} (-?[\\d.]+)`).exec(dict)
return match ? Number(match[1]) : null
}
/** `/Key [n n n n]` → the numbers. */
export function numbersOf(dict: string, key: string): number[] {
const match = new RegExp(`/${key} \\[([^\\]]*)\\]`).exec(dict)
return match ? match[1]!.trim().split(/\s+/).map(Number) : []
}
/** A hex string `<…>`: UTF-16BE behind a BOM, else Latin-1 bytes. */
export function decodeHexString(token: string): string {
const hex = token.slice(1, -1)
const bytes = new Uint8Array(hex.length / 2)
for (let i = 0; i < bytes.length; i += 1) {
bytes[i] = Number.parseInt(hex.slice(i * 2, i * 2 + 2), 16)
}
if (bytes[0] === 0xfe && bytes[1] === 0xff) {
return new TextDecoder('utf-16be').decode(bytes.subarray(2))
}
return latin1.decode(bytes)
}
/** `/Key <hex>` or `/Key (literal)` → the decoded text. */
export function textOf(dict: string, key: string): string | null {
const match = new RegExp(`/${key} (<[0-9A-Fa-f]*>|\\([^)]*\\))`).exec(dict)
if (!match) return null
const token = match[1]!
return token.startsWith('<') ? decodeHexString(token) : token.slice(1, -1)
}
/** `/F1 5 0 R /F2 6 0 R` → the name → object number pairs of a resource dictionary. */
export function entriesOf(dict: string): Map<string, number> {
return new Map(
[...dict.matchAll(/\/([^\s/<>]+) (\d+) 0 R/g)].map((m) => [
m[1]!,
Number(m[2]),
]),
)
}
/** The file as a whole: its objects, catalog, pages in order, Info. */
export class PdfFile {
private constructor(
private readonly objects: Map<number, PdfObject>,
private readonly trailer: string,
) {}
static parse(bytes: Uint8Array): PdfFile {
const text = latin1.decode(bytes)
const at = text.lastIndexOf('trailer\n')
if (at < 0) throw new Error('no trailer')
return new PdfFile(parsePdf(bytes), text.slice(at))
}
object(number: number): PdfObject {
const object = this.objects.get(number)
if (!object) throw new Error(`object ${number} missing`)
return object
}
/** Every object, in number order. */
all(): PdfObject[] {
return [...this.objects.values()].sort((a, b) => a.number - b.number)
}
catalog(): PdfObject {
return this.object(refOf(this.trailer, 'Root')!)
}
info(): PdfObject {
return this.object(refOf(this.trailer, 'Info')!)
}
/** The pages in `/Kids` order. */
pages(): PdfObject[] {
const pages = this.object(refOf(this.catalog().dict, 'Pages')!)
return refsOf(pages.dict, 'Kids').map((n) => this.object(n))
}
/** The content stream text (Latin-1) of a page. */
content(page: PdfObject): string {
return latin1.decode(streamOf(this.object(refOf(page.dict, 'Contents')!)))
}
/** `/F1` → `Helvetica`, through the page's font resources. */
fontNames(page: PdfObject): Map<string, string> {
const fonts = subDict(subDict(page.dict, 'Resources') ?? '', 'Font') ?? ''
const names = new Map<string, string>()
for (const [name, number] of entriesOf(fonts)) {
names.set(name, nameOf(this.object(number).dict, 'BaseFont') ?? '')
}
return names
}
/** The image XObjects of a page, by resource name. */
xobjects(page: PdfObject): Map<string, PdfObject> {
const dict = subDict(subDict(page.dict, 'Resources') ?? '', 'XObject') ?? ''
return new Map(
[...entriesOf(dict)].map(([name, number]) => [name, this.object(number)]),
)
}
/** The annotation objects of a page, in `/Annots` order. */
annots(page: PdfObject): PdfObject[] {
return refsOf(page.dict, 'Annots').map((n) => this.object(n))
}
}
/**
* A minimal PDF carrying one embedded file in clear (one empty page, the stream stored
* raw, a Filespec named `/F (name)` with `/EF`, the names tree, a classic xref): what the
* rejection cases of the import suites used to build with pdf-lib. Test input only.
*/
export function buildPdfWithAttachment(
name: string,
data: Uint8Array,
): Uint8Array {
const latin1Bytes = (text: string) =>
Uint8Array.from(text, (c) => c.charCodeAt(0))
const bodies: Uint8Array[] = [
latin1Bytes(
`<< /Type /Catalog /Pages 2 0 R /Names << /EmbeddedFiles << /Names [(${name}) 5 0 R] >> >> >>`,
),
latin1Bytes('<< /Type /Pages /Count 1 /Kids [3 0 R] >>'),
latin1Bytes(
'<< /Type /Page /Parent 2 0 R /MediaBox [0 0 595.28 841.89] >>',
),
new Uint8Array([
...latin1Bytes(
`<< /Type /EmbeddedFile /Subtype /application#2Fjson /Length ${data.length} >>\nstream\n`,
),
...data,
...latin1Bytes('\nendstream'),
]),
latin1Bytes(
`<< /Type /Filespec /F (${name}) /UF (${name}) /EF << /F 4 0 R >> /AFRelationship /Data >>`,
),
]
const parts: Uint8Array[] = [latin1Bytes('%PDF-1.7\n%\xe2\xe3\xcf\xd3\n')]
const offsets: number[] = []
let total = parts[0]!.length
bodies.forEach((body, i) => {
offsets.push(total)
const object = new Uint8Array([
...latin1Bytes(`${i + 1} 0 obj\n`),
...body,
...latin1Bytes('\nendobj\n'),
])
parts.push(object)
total += object.length
})
const xref = [
'xref',
`0 ${bodies.length + 1}`,
'0000000000 65535 f ',
...offsets.map((o) => `${String(o).padStart(10, '0')} 00000 n `),
'trailer',
`<< /Size ${bodies.length + 1} /Root 1 0 R >>`,
'startxref',
String(total),
'%%EOF',
'',
].join('\n')
parts.push(latin1Bytes(xref))
const out = new Uint8Array(parts.reduce((n, p) => n + p.length, 0))
let at = 0
for (const part of parts) {
out.set(part, at)
at += part.length
}
return out
}
+60
View File
@@ -0,0 +1,60 @@
import type { ArchiveImport } from '@faunosteo/core-wasm/types'
import { coreRuntime } from '@/core/runtime'
import { ImportError, pdfImportOf } from '@/core/worker/outcome'
import type { SheetIndex } from '@/services/sheetIndex'
import { bundledSheet } from './sheet'
export { ImportError }
/**
* The application's PDF import, in-process for the tests (R4.8, the TypeScript scanner
* gone): the module's reader (`SheetHandle.import_pdf`, R4.2) on a handle of the bundled
* sheet, its envelope mapped as HomeRoute maps the worker's settlement (`pdfImportOf`). The
* page never runs the reader on its main instance (OD-1: the import worker does, on a
* handle of its own); these helpers give the tests the same reading, same kinds, without a
* worker thread. The route suites cover the worker itself.
*/
export async function importReportFromPdf(
bytes: Uint8Array,
): Promise<ArchiveImport> {
const bundle = JSON.stringify(await bundledSheet())
const runtime = coreRuntime()
if (!(await runtime.ready())) throw new ImportError('core_unavailable')
const out = runtime.invoke<string>((glue) => {
const handle = new glue.SheetHandle(bundle)
try {
return { ok: true, value: handle.import_pdf(bytes) }
} finally {
handle.free()
}
})
if (!out.ok) throw new ImportError('core_unavailable', null, out.kind)
return pdfImportOf({
kind: 'result',
out: out.value,
diag: { ms: 0, linearBytes: null, chunks: 0 },
})
}
/**
* The core's layered reading of an attachment already parsed (`archive.import` on the
* loaded sheet): the v3 report as is, a v2 migrated through the sheet's map, the envelope
* kept or its snapshot dropped with a reason, then the rebase onto that sheet. The kinds
* are the worker's.
*/
export function importAttachment(
attachment: unknown,
index: SheetIndex,
): ArchiveImport {
const outcome = index.ops.importArchive(attachment)
if (outcome.ok) return outcome.value
switch (outcome.kind) {
case 'incompatible_version':
throw new ImportError('incompatible_version', outcome.found ?? null)
case 'no_attachment':
case 'lone_surrogate':
throw new ImportError(outcome.kind)
default:
throw new ImportError('core_unavailable', null, outcome.kind)
}
}
+12 -49
View File
@@ -1,20 +1,13 @@
import {
decodePDFRawStream,
PDFArray,
PDFDict,
PDFDocument,
PDFName,
PDFRawStream,
type PDFPage,
} from 'pdf-lib'
import { PdfFile, type PdfObject } from './pdfFile'
import { round2, type ImageEntry, type TextEntry } from './goldens'
/**
* The drawing facts of a saved PDF, read back from its content streams (R4.6: the core
* writes the file, so nothing is recorded at draw time any more; pdf-lib still reads the
* file in the tests until R4.8). The streams are the operator sequences pdf-lib emitted
* and the core reproduces: one operator per line, `q BT rg Tf TL Tm (Tj T*)+ ET Q` per
* text call, `q cm cm cm cm Do Q` per image. Positions are rounded like the recorder did.
* writes the file, so nothing is recorded at draw time any more; R4.8: the file is read by
* `pdfFile.ts`, pdf-lib having left the tests). The streams are the operator sequences
* pdf-lib emitted and the core reproduces: one operator per line, `q BT rg Tf TL Tm (Tj
* T*)+ ET Q` per text call, `q cm cm cm cm Do Q` per image. Positions are rounded like the
* recorder did.
*/
/** WinAnsi is Windows-1252 for every glyph the engine prints. */
@@ -29,43 +22,13 @@ function hexBytes(token: string): Uint8Array {
return out
}
function contentOf(page: PDFPage): string {
const contents = page.node.Contents()
const streams: PDFRawStream[] = []
if (contents instanceof PDFRawStream) streams.push(contents)
else if (contents instanceof PDFArray) {
for (let i = 0; i < contents.size(); i += 1) {
streams.push(contents.lookup(i, PDFRawStream))
}
}
return streams
.map((stream) =>
new TextDecoder('latin1').decode(decodePDFRawStream(stream).decode()),
)
.join('\n')
}
/** `/F1` → `Helvetica`, through the page's font resources. */
function fontNames(page: PDFPage): Map<string, string> {
const names = new Map<string, string>()
const resources = page.node.lookup(PDFName.of('Resources'), PDFDict)
const fonts = resources.lookupMaybe(PDFName.of('Font'), PDFDict)
if (!fonts) return names
for (const [key, ref] of fonts.entries()) {
const font = fonts.context.lookup(ref, PDFDict)
const base = font.lookup(PDFName.of('BaseFont'))
names.set(key.decodeText(), String(base).replace(/^\//, ''))
}
return names
}
interface PageFacts {
texts: TextEntry[]
images: ImageEntry[]
}
function readPage(page: PDFPage, index: number): PageFacts {
const fonts = fontNames(page)
function readPage(file: PdfFile, page: PdfObject, index: number): PageFacts {
const fonts = file.fontNames(page)
const texts: TextEntry[] = []
const images: ImageEntry[] = []
let font: string | null = null
@@ -74,7 +37,7 @@ function readPage(page: PDFPage, index: number): PageFacts {
let y: number | null = null
let lines: string[] = []
let matrices: number[][] = []
for (const line of contentOf(page).split('\n')) {
for (const line of file.content(page).split('\n')) {
const tokens = line.trim().split(' ')
const op = tokens[tokens.length - 1]
const operands = tokens.slice(0, -1)
@@ -123,11 +86,11 @@ function readPage(page: PDFPage, index: number): PageFacts {
/** Every text and image call of the file, page by page, in stream order. */
export async function readDrawing(bytes: Uint8Array): Promise<PageFacts> {
const doc = await PDFDocument.load(bytes)
const file = PdfFile.parse(bytes)
const texts: TextEntry[] = []
const images: ImageEntry[] = []
doc.getPages().forEach((page, index) => {
const facts = readPage(page, index)
file.pages().forEach((page, index) => {
const facts = readPage(file, page, index)
texts.push(...facts.texts)
images.push(...facts.images)
})
-389
View File
@@ -1,389 +0,0 @@
import { createHash } from 'node:crypto'
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
import { dirname, resolve } from 'node:path'
import { expect, vi } from 'vitest'
import {
PDFArray,
PDFDict,
PDFDocument,
PDFFont,
PDFHexString,
PDFImage,
PDFName,
PDFNumber,
PDFPage,
PDFString,
} from 'pdf-lib'
import {
FIXTURES_DIR,
round2,
type ImageEntry,
type LinkEntry,
type TextEntry,
} from './goldens'
/**
* R4.1 freeze, writer oracles (plan 2026-10-17 §B.5.1 O1 to O3): what the
* TypeScript writer draws, at full precision, for the Rust writer to
* reproduce. The recorder is the Step 6 one made complete: every drawText,
* drawImage, drawLine and drawRectangle call with every option passed, the
* images by embed order and PNG digest, the links read back from the saved
* bytes. `MAKE_R4_ORACLES=1` writes the files; otherwise they are asserted.
*/
export const MAKE_R4_ORACLES = process.env.MAKE_R4_ORACLES === '1'
export const R4_GOLDEN_DIR = resolve(FIXTURES_DIR, 'goldens/r4')
export const R3_PDF_DIR = resolve(FIXTURES_DIR, 'pdf/r3')
export const STEP6_PDF_DIR = resolve(FIXTURES_DIR, 'pdf/step6')
/** The engine suites' export time (packages/pdf/tests/helpers/goldens.ts). */
export const FIXED_EXPORTED_AT = new Date('2026-10-11T12:00:00.000Z')
export type Json =
| null
| boolean
| number
| string
| Json[]
| { [key: string]: Json }
/** A type alias, not an interface: it must fit the `Json` index signature. */
export type ImageRef = {
embedIndex: number
pngSha256: string
}
export type DrawOpName = 'drawText' | 'drawImage' | 'drawLine' | 'drawRectangle'
export interface DrawOp {
/** Global call order across pages: footers are drawn after every page. */
seq: number
op: DrawOpName
text?: string
image?: ImageRef
options: Json
}
export interface FullLink {
page: number
rect: number[]
uri: string
}
export interface DrawLog {
pages: { index: number; ops: DrawOp[] }[]
/** Every embedPng call in order, drawn or not: each one is an XObject. */
embeds: ImageRef[]
links: FullLink[]
}
export const sha256 = (data: Uint8Array | string): string =>
createHash('sha256').update(data).digest('hex')
interface RecorderState {
ops: { page: number; op: DrawOp }[]
embeds: ImageRef[]
images: Map<PDFImage, ImageRef>
documents: Set<PDFDocument>
}
/** Non-finite numbers and -0 have no JSON form: tagged so none is lost. */
function numberOf(value: number): Json {
if (Number.isFinite(value) && !Object.is(value, -0)) return value
return { $number: Object.is(value, -0) ? '-0' : String(value) }
}
function imageRefOf(state: RecorderState, image: PDFImage): ImageRef {
const ref = state.images.get(image)
if (!ref) throw new Error('drawImage of an image embedPng did not return')
return ref
}
function objectOf(
value: object,
state: RecorderState,
path: Set<object>,
): Json {
if (path.has(value)) throw new Error('cyclic draw argument')
path.add(value)
const out: Json = Array.isArray(value)
? value.map((item) => serialise(item, state, path))
: Object.fromEntries(
Object.entries(value).map(([k, v]) => [k, serialise(v, state, path)]),
)
path.delete(value)
return out
}
/** Generic: whatever a call passes is kept, keys in insertion order. */
function serialise(
value: unknown,
state: RecorderState,
path = new Set<object>(),
): Json {
if (value === undefined) return { $undefined: true }
if (value === null || typeof value === 'string') return value
if (typeof value === 'boolean') return value
if (typeof value === 'number') return numberOf(value)
if (value instanceof PDFFont) return value.name
if (value instanceof PDFImage) return imageRefOf(state, value)
if (typeof value === 'object') return objectOf(value, state, path)
throw new Error(`unexpected draw argument of type ${typeof value}`)
}
/** Pages are appended in order and never moved: the index at draw time is final. */
function pageIndex(page: PDFPage): number {
return page.doc.getPages().indexOf(page)
}
function record(
state: RecorderState,
page: PDFPage,
entry: Omit<DrawOp, 'seq'>,
): void {
state.documents.add(page.doc)
state.ops.push({
page: pageIndex(page),
op: { seq: state.ops.length, ...entry },
})
}
function pngBytes(png: string | Uint8Array | ArrayBuffer): Uint8Array {
if (png instanceof Uint8Array) return png
if (png instanceof ArrayBuffer) return new Uint8Array(png)
throw new Error('embedPng received a string: the engine passes bytes')
}
function spyEmbedPng(state: RecorderState) {
const original = PDFDocument.prototype.embedPng
return vi
.spyOn(PDFDocument.prototype, 'embedPng')
.mockImplementation(async function (this: PDFDocument, png) {
state.documents.add(this)
const ref = {
embedIndex: state.embeds.length,
pngSha256: sha256(pngBytes(png)),
}
state.embeds.push(ref)
const image = await original.call(this, png)
state.images.set(image, ref)
return image
})
}
function spyDrawText(state: RecorderState) {
const original = PDFPage.prototype.drawText
return vi.spyOn(PDFPage.prototype, 'drawText').mockImplementation(function (
this: PDFPage,
text,
options,
) {
const opts = serialise(options, state)
record(state, this, { op: 'drawText', text, options: opts })
return original.call(this, text, options)
})
}
function spyDrawImage(state: RecorderState) {
const original = PDFPage.prototype.drawImage
return vi.spyOn(PDFPage.prototype, 'drawImage').mockImplementation(function (
this: PDFPage,
image,
options,
) {
const ref = imageRefOf(state, image)
const opts = serialise(options, state)
record(state, this, { op: 'drawImage', image: ref, options: opts })
return original.call(this, image, options)
})
}
function spyDrawLine(state: RecorderState) {
const original = PDFPage.prototype.drawLine
return vi.spyOn(PDFPage.prototype, 'drawLine').mockImplementation(function (
this: PDFPage,
options,
) {
record(state, this, { op: 'drawLine', options: serialise(options, state) })
return original.call(this, options)
})
}
function spyDrawRectangle(state: RecorderState) {
const original = PDFPage.prototype.drawRectangle
return vi
.spyOn(PDFPage.prototype, 'drawRectangle')
.mockImplementation(function (this: PDFPage, options) {
const opts = serialise(options, state)
record(state, this, { op: 'drawRectangle', options: opts })
return original.call(this, options)
})
}
/** Drawing and embedding entry points the engine must not use. */
const UNEXPECTED_PAGE = [
'drawPage',
'drawSvgPath',
'drawSquare',
'drawEllipse',
'drawCircle',
] as const
const UNEXPECTED_DOC = ['embedJpg', 'embedPdf', 'embedPage'] as const
function guardSpies() {
return [
...UNEXPECTED_PAGE.map((name) => ({
name,
spy: vi.spyOn(PDFPage.prototype, name),
})),
...UNEXPECTED_DOC.map((name) => ({
name,
spy: vi.spyOn(PDFDocument.prototype, name),
})),
]
}
export interface DrawRecorder {
state: RecorderState
/** Names of the guarded methods that were called. */
unexpectedCalls(): string[]
stop(): void
}
export function recordFullDrawing(): DrawRecorder {
const state: RecorderState = {
ops: [],
embeds: [],
images: new Map(),
documents: new Set(),
}
const spies = [
spyEmbedPng(state),
spyDrawText(state),
spyDrawImage(state),
spyDrawLine(state),
spyDrawRectangle(state),
]
const guards = guardSpies()
return {
state,
unexpectedCalls: () =>
guards.filter((g) => g.spy.mock.calls.length > 0).map((g) => g.name),
stop: () =>
[...spies, ...guards.map((g) => g.spy)].forEach((s) => s.mockRestore()),
}
}
function linkOf(dict: PDFDict, page: number): FullLink | null {
if (dict.get(PDFName.of('Subtype')) !== PDFName.of('Link')) return null
const rect = dict
.lookup(PDFName.of('Rect'), PDFArray)
.asArray()
.map((n) => (n as PDFNumber).asNumber())
const uri = dict.lookup(PDFName.of('A'), PDFDict).lookup(PDFName.of('URI'))
const text =
uri instanceof PDFString || uri instanceof PDFHexString
? uri.decodeText()
: String(uri)
return { page, rect, uri: text }
}
export interface PdfFacts {
pageCount: number
links: FullLink[]
}
/** Page count and every `/Annot /Link` of the saved bytes, in annotation order. */
export async function readPdfFacts(bytes: Uint8Array): Promise<PdfFacts> {
const doc = await PDFDocument.load(bytes)
const links: FullLink[] = []
doc.getPages().forEach((page, index) => {
const annots = page.node.Annots()
for (let i = 0; i < (annots?.size() ?? 0); i += 1) {
const link = linkOf(annots!.lookup(i, PDFDict), index)
if (link) links.push(link)
}
})
return { pageCount: doc.getPageCount(), links }
}
export function drawLogOf(recorder: DrawRecorder, facts: PdfFacts): DrawLog {
const { ops, embeds } = recorder.state
if (ops.some((o) => o.page < 0 || o.page >= facts.pageCount)) {
throw new Error('a draw call landed on a page the saved PDF lacks')
}
const pages = Array.from({ length: facts.pageCount }, (_, index) => ({
index,
ops: ops.filter((o) => o.page === index).map((o) => o.op),
}))
return { pages, embeds, links: facts.links }
}
function inCallOrder(log: DrawLog, name: DrawOpName) {
return log.pages
.flatMap((p) => p.ops.map((op) => ({ page: p.index, op })))
.filter((entry) => entry.op.op === name)
.sort((a, b) => a.op.seq - b.op.seq)
}
const optionsOf = (op: DrawOp) => op.options as Record<string, Json>
/** The Step 6 text golden's projection: 2 decimals, the same fields. */
export function step6Texts(log: DrawLog): TextEntry[] {
return inCallOrder(log, 'drawText').map(({ page, op }) => {
const o = optionsOf(op)
return {
page,
text: op.text ?? '',
x: round2(o.x),
y: round2(o.y),
size: round2(o.size),
font: typeof o.font === 'string' ? o.font : null,
}
})
}
export function step6Images(log: DrawLog): ImageEntry[] {
return inCallOrder(log, 'drawImage').map(({ page, op }) => {
const o = optionsOf(op)
return {
page,
x: round2(o.x),
y: round2(o.y),
width: round2(o.width),
height: round2(o.height),
}
})
}
export function step6Links(log: DrawLog): LinkEntry[] {
return log.links.map(({ page, rect, uri }) => ({
page,
rect: rect.map((n) => round2(n) ?? 0),
uri,
}))
}
/** Writes under MAKE_R4_ORACLES; otherwise deep equality, then the exact text. */
export function checkJsonOracle(file: string, value: unknown): void {
const text = `${JSON.stringify(value, null, 2)}\n`
if (MAKE_R4_ORACLES) {
mkdirSync(dirname(file), { recursive: true })
writeFileSync(file, text)
return
}
const committed = readFileSync(file, 'utf8')
expect(JSON.parse(text), file).toEqual(JSON.parse(committed))
expect(text, file).toBe(committed)
}
/** Writes under MAKE_R4_ORACLES; otherwise byte equality (by digest). */
export function checkBytesOracle(file: string, bytes: Uint8Array): void {
if (MAKE_R4_ORACLES) {
mkdirSync(dirname(file), { recursive: true })
writeFileSync(file, bytes)
return
}
const committed = new Uint8Array(readFileSync(file))
expect(sha256(bytes), file).toBe(sha256(committed))
}
+1 -1
View File
@@ -7,7 +7,7 @@ import type {
ReportArchiveEnvelope,
SheetSnapshot,
} from '@faunosteo/core-wasm/types'
import { defaultPdfLabels } from '@faunosteo/pdf'
import { defaultPdfLabels } from '@/pdf/labels'
import type { SheetIndexData } from '@faunosteo/core-wasm/types'
import type { ReportMigrationMap } from '@faunosteo/core-wasm/n-1'
import { coreRuntime } from '@/core/runtime'