Files
faunosteo/packages/pdf/tests/r4.reader-oracles.test.ts
T

323 lines
11 KiB
TypeScript

/**
* R4.1 freeze O7 (plan 2026-10-17 §B.1.2, §B.5.1): what the TypeScript
* reader answers on every input of scan.test.ts, inflate.test.ts,
* read.test.ts and the reader cases of security.test.ts, rebuilt with the
* same code, and on the §B.1.2 semantics rows. Inputs go under
* `apps/app/tests/fixtures/pdf/r4/read/` (bytes, or a generator description
* above 2 MiB), outcomes to `crates/core/tests/oracles/r4/read.json`: the
* Rust reader reproduces them at R4.2. `MAKE_R4_ORACLES=1` writes both;
* without it the test rebuilds everything and requires the same files.
* pdf-lib stamps the current date into the PDFs it creates, so the clock is
* frozen at FIXED_EXPORTED_AT while the inputs are built.
*/
import { resolve } from 'node:path'
import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
import type { ArchiveReadOutcome } from '@faunosteo/domain'
import {
ArchiveReadError,
findEmbeddedFiles,
MAX_ATTACHMENT_BYTES,
MAX_PDF_BYTES,
readAttachedDocument,
readAttachmentBytes,
readReportArchive,
type EmbeddedFileCandidate,
} from '../src'
import { inflateFlate } from '../src/attachment/inflate'
import {
decodePdfString,
hasArchiveStamp,
hasPdfHeader,
locateAttachment,
type LocatedAttachment,
} from '../src/attachment/scan'
import { FIXED_EXPORTED_AT } from './helpers/goldens'
import { objectSpan } from './helpers/r4-reader-craft'
import {
expectOnlyFiles,
generatedWith,
inflateVerdict,
MAKE,
R4_INPUTS_DIR,
R4_ORACLES_DIR,
readJsonFile,
sha256,
storeInput,
storeJson,
type SliceRef,
type StoredInput,
} from './helpers/r4-reader-io'
import {
readerContext,
SUITE_INPUTS,
type CaseRef,
type InputSpec,
type ReaderContext,
} from './helpers/r4-reader-inputs'
import { SEMANTIC_INPUTS, TOKEN_CASES } from './helpers/r4-reader-semantics'
const INPUTS_DIR = resolve(R4_INPUTS_DIR, 'read')
const OUT = resolve(R4_ORACLES_DIR, 'read.json')
const DEMO_EXPORT_FILE = 'scan.demo-export.pdf'
type Outcome = Record<string, unknown>
interface Entry extends StoredInput {
kind: InputSpec['kind']
cases: CaseRef[]
outcomes: Record<string, unknown>
}
const objectSha = (value: unknown) => sha256(JSON.stringify(value))
function failure(error: unknown): Outcome {
if (!(error instanceof ArchiveReadError)) throw error
const found =
error.foundVersion === undefined ? {} : { foundVersion: error.foundVersion }
return { ok: false, kind: error.kind, ...found }
}
/** The success description of `run`, or the ArchiveReadError kind it throws. */
async function outcomeOf<T>(
run: () => Promise<T>,
success: (value: T) => Promise<Outcome> | Outcome,
): Promise<Outcome> {
let value: T
try {
value = await run()
} catch (error) {
return failure(error)
}
return success(value)
}
/**
* The candidate `locateAttachment` kept: a raw one is a view on the input,
* a Flate one is the first whose inflation gives the same bytes (an earlier
* twin would have been accepted first).
*/
async function chosenIndex(
input: Uint8Array,
candidates: EmbeddedFileCandidate[],
kept: Uint8Array,
): Promise<number> {
if (kept.buffer === input.buffer) {
const offset = kept.byteOffset - input.byteOffset
return candidates.findIndex(
(c) =>
c.filter === null &&
c.offset === offset &&
c.length === kept.byteLength,
)
}
const keptSha = sha256(kept)
for (const [index, c] of candidates.entries()) {
if (c.filter === null) continue
const out = await inflateFlate(
input.subarray(c.offset, c.offset + c.length),
)
if (out !== null && sha256(out) === keptSha) return index
}
return -1
}
async function locatedOutcome(
input: Uint8Array,
candidates: EmbeddedFileCandidate[],
located: LocatedAttachment,
): Promise<Outcome> {
const index = await chosenIndex(input, candidates, located.bytes)
expect(index, 'chosen candidate').toBeGreaterThanOrEqual(0)
const chosen = candidates[index]!
return {
ok: true,
candidate: index,
name: chosen.name,
dataOffset: chosen.offset,
bytesLength: located.bytes.byteLength,
bytesSha256: sha256(located.bytes),
objectSha256: objectSha(located.data),
}
}
const archiveOutcome = (outcome: ArchiveReadOutcome): Outcome => ({
ok: true,
origin: outcome.origin,
migrated: outcome.migrated,
unresolvedZones: outcome.unresolvedZones,
unresolvedFindings: outcome.unresolvedFindings,
snapshotRejected: outcome.snapshotRejected ?? null,
reportSha256: objectSha(outcome.report),
archiveSha256: outcome.archive === null ? null : objectSha(outcome.archive),
})
const exercised = (spec: InputSpec, name: string) =>
spec.cases.some((c) => c.exercises.some((f) => f === name))
async function readerOutcomes(
ctx: ReaderContext,
spec: InputSpec,
input: Uint8Array,
): Promise<Outcome> {
const candidates = findEmbeddedFiles(input)
const located = (l: LocatedAttachment) => locatedOutcome(input, candidates, l)
const outcomes: Outcome = {
findEmbeddedFiles: candidates.map(({ name, offset, length, filter }) => ({
name,
offset,
length,
filter,
})),
hasArchiveStamp: hasArchiveStamp(input),
locateAttachment: await outcomeOf(() => locateAttachment(input), located),
readAttachedDocument: await outcomeOf(
() => readAttachedDocument(input),
async (data) => {
const again = await locateAttachment(input)
expect(objectSha(again.data)).toBe(objectSha(data))
return located(again)
},
),
}
if (exercised(spec, 'readAttachmentBytes')) {
outcomes.readAttachmentBytes = await outcomeOf(
() => readAttachmentBytes(input),
(bytes) => ({
ok: true,
bytesLength: bytes.byteLength,
bytesSha256: sha256(bytes),
}),
)
}
outcomes.readReportArchive = await outcomeOf(
() => readReportArchive(input, ctx.golden.draft.migrationMap),
archiveOutcome,
)
return outcomes
}
async function flateOutcomes(spec: InputSpec, input: Uint8Array) {
const runs = []
for (const limit of spec.limits ?? [MAX_ATTACHMENT_BYTES]) {
runs.push({ limit, verdict: await inflateVerdict(input, limit) })
}
return { inflateFlate: runs }
}
/** The demo attachment object, referenced by the descriptions that embed it. */
function sliceRefs(ctx: ReaderContext): SliceRef[] {
const pdf = ctx.exported.pdf
const span = objectSpan(pdf, '/Type /EmbeddedFile')
const bytes = pdf.slice(span.start, span.end)
return [{ file: DEMO_EXPORT_FILE, ...span, bytes }]
}
const extensionOf = (spec: InputSpec, bytes: Uint8Array) =>
spec.kind === 'pdf' && hasPdfHeader(bytes) ? '.pdf' : '.bin'
/** Builds, stores and reads every input; identical inputs of the same kind are stored once. */
async function buildEntries(ctx: ReaderContext): Promise<Entry[]> {
const entries = new Map<string, Entry>()
const refs = sliceRefs(ctx)
for (const spec of [...SUITE_INPUTS, ...SEMANTIC_INPUTS]) {
const bytes = await spec.build(ctx)
const key = `${spec.kind}:${sha256(bytes)}`
const known = entries.get(key)
if (known) {
expect(spec.limits, spec.slug).toBeUndefined()
known.cases.push(...spec.cases)
continue
}
const name = { slug: spec.slug, ext: extensionOf(spec, bytes) }
const stored = storeInput(INPUTS_DIR, name, bytes, refs)
const outcomes =
spec.kind === 'pdf'
? await readerOutcomes(ctx, spec, bytes)
: await flateOutcomes(spec, bytes)
entries.set(key, {
...stored,
kind: spec.kind,
cases: [...spec.cases],
outcomes,
})
}
return [...entries.values()]
}
const CONVENTIONS = {
inputs:
'file under inputsDir; stored "bytes" as is, "generator" as <slug>.gen.json whose parts concatenate in order (latin1: one byte per character; fill: the byte value repeated count times; slice: bytes [start, end) of another file of inputsDir) into length bytes of digest sha256',
kind: 'pdf: every reader function below is run on the file; flate: inflateFlate only',
cases:
'the TypeScript cases (vitest full title) that build this input and the reader functions they call on it; identical inputs are stored once',
findEmbeddedFiles:
'candidates in returned order: name, offset (first data byte), length (stored bytes), filter',
locateAttachment:
'{ ok: true, candidate (index in findEmbeddedFiles), name, dataOffset, bytesLength, bytesSha256 (stored or inflated bytes), objectSha256 (sha256 of JSON.stringify of the parsed value) } or { ok: false, kind }',
readAttachedDocument:
'the same shapes, after the size cap and the %PDF- header check',
readAttachmentBytes:
'only where a case calls it: { ok: true, bytesLength, bytesSha256 } or { ok: false, kind }',
readReportArchive:
'on the draft migration map: { ok: true, origin, migrated, unresolvedZones, unresolvedFindings, snapshotRejected, reportSha256, archiveSha256 } (sha256 of JSON.stringify) or { ok: false, kind, foundVersion when present }',
inflateFlate: 'per limit: verdict null, or { length, sha256 } of the output',
decodePdfString:
'token as a Latin-1 string (one character per byte); result string or null',
}
function oracleOf(entries: Entry[]) {
return {
oracle: 'O7',
plan: '.claude/tasks/plans/2026-10-17-rust-r4-pdf-core.md §B.1.2, §B.5.1',
generator: 'packages/pdf/tests/r4.reader-oracles.test.ts',
generatedWith: generatedWith(),
inputsDir: 'apps/app/tests/fixtures/pdf/r4/read',
constants: { MAX_PDF_BYTES, MAX_ATTACHMENT_BYTES },
conventions: CONVENTIONS,
inputs: entries,
decodePdfString: TOKEN_CASES.map((t) => ({
...t,
result: decodePdfString(t.token),
})),
}
}
type Oracle = ReturnType<typeof oracleOf>
/** Per-input comparison first: a failure names the input instead of diffing the whole oracle. */
function expectSameEntries(entries: Entry[]): void {
const committed = readJsonFile<Oracle>(OUT)
const byFile = new Map(committed.inputs.map((e) => [e.file, e]))
for (const entry of entries) {
expect(byFile.get(entry.file), entry.file).toEqual(
JSON.parse(JSON.stringify(entry)),
)
}
}
beforeAll(() => {
vi.useFakeTimers({ toFake: ['Date'] })
vi.setSystemTime(FIXED_EXPORTED_AT)
})
afterAll(() => {
vi.useRealTimers()
})
describe('R4 reader oracles O7 (TypeScript freeze)', () => {
it('matches the frozen inputs and reader outcomes', async () => {
const entries = await buildEntries(await readerContext())
const bytes = entries.reduce((n, e) => n + e.length, 0)
console.log(`[O7] ${entries.length} inputs, ${bytes} bytes expanded`)
if (!MAKE) expectSameEntries(entries)
storeJson(OUT, oracleOf(entries), (committed) => ({
...(committed as Oracle),
generatedWith: generatedWith(),
}))
expectOnlyFiles(
INPUTS_DIR,
entries.map((e) => e.file),
)
}, 600_000)
})