feat(pdf): archive check tool pnpm report:compare (attachment vs its v3 reading, unresolved items flagged, --diff/--summary/--identity); readAttachedDocument split out of extractReportJson; stale scaffold:species script removed; docs

This commit is contained in:
bchanot committed 2026-10-10 15:44:20 +02:00
1 parent 1e0491f3bc
commit dc78a00835
13 files changed
+753 -37

No files matched your search

+41 -29
View File
@@ -43,10 +43,45 @@ export interface ExtractedReport extends MigrationOutcome {
migrated: boolean
}
/**
* The raw report document carried by the PDF, of whatever version, before
* any migration: what the archive check tool shows next to the v3 result.
* Throws when the PDF carries no Faunosteo attachment or an oversized one.
*/
export async function readAttachedDocument(
pdfDoc: PDFDocument,
): Promise<unknown> {
const bytes = await attachmentBytes(pdfDoc)
if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
throw new Error('attachment too large')
}
const data: unknown = JSON.parse(new TextDecoder().decode(bytes))
// No numeric version at all: not a Faunosteo attachment (legacy message), not an old one.
if (versionOf(data) === null) {
throw new Error('attachment carries no report version')
}
return data
}
export async function extractReportJson(
pdfDoc: PDFDocument,
map: ReportMigrationMap,
): Promise<ExtractedReport> {
const data = await readAttachedDocument(pdfDoc)
try {
return {
...readReportDocument(data, map),
migrated: versionOf(data) !== REPORT_VERSION,
}
} catch (err) {
if (err instanceof UnsupportedReportVersionError) {
throw new IncompatibleReportVersionError(err.foundVersion)
}
throw err
}
}
async function attachmentBytes(pdfDoc: PDFDocument): Promise<Uint8Array> {
const maybeApi = pdfDoc as unknown as {
getAttachments?: () => Array<{ name: string; data: Uint8Array }>
}
@@ -57,44 +92,21 @@ export async function extractReportJson(
list.find(
(a) => a.name.startsWith('osteo-report') && a.name.endsWith('.json'),
) ?? list[0]
return parseAttachment(hit.data, map)
return hit.data
}
}
const fallback = await traverseForJsonAttachment(pdfDoc)
if (!fallback) throw new Error('No osteo-report attachment found')
return parseAttachment(fallback, map)
return fallback
}
/** Hard ceiling on an attachment (inflated or not): a report is a few hundred KB at most. */
const MAX_ATTACHMENT_BYTES = 16 * 1024 * 1024
function parseAttachment(
bytes: Uint8Array,
map: ReportMigrationMap,
): ExtractedReport {
if (bytes.byteLength > MAX_ATTACHMENT_BYTES) {
throw new Error('attachment too large')
}
const data: unknown = JSON.parse(new TextDecoder().decode(bytes))
const version =
data !== null &&
typeof data === 'object' &&
typeof (data as { version?: unknown }).version === 'number'
? (data as { version: number }).version
: null
// No numeric version at all: not a Faunosteo attachment (legacy message), not an old one.
if (version === null) throw new Error('attachment carries no report version')
try {
return {
...readReportDocument(data, map),
migrated: version !== REPORT_VERSION,
}
} catch (err) {
if (err instanceof UnsupportedReportVersionError) {
throw new IncompatibleReportVersionError(err.foundVersion)
}
throw err
}
function versionOf(data: unknown): number | null {
if (data === null || typeof data !== 'object') return null
const v = (data as { version?: unknown }).version
return typeof v === 'number' ? v : null
}
interface RawObj {