@cairn-tool/cairn 3.2.0 → 3.3.1

package/dist/pdf/outline.js

@@ -0,0 +1,127 @@
+import { CODES, DiagnosticSink } from "./diagnostics.js";
+/**
+ * The outline is attacker-shaped structure and the walk is recursive, so it is
+ * bounded for the same reason the ADF reader bounds nesting depth: a stack
+ * overflow with no diagnostic is the wrong failure for input off a network.
+ */
+export const MAX_OUTLINE_DEPTH = 64;
+/**
+ * C0 controls and DEL, stripped from every attacker-controlled string.
+ *
+ * Declared once so the directive stays attached to the pattern: inline, the
+ * formatter moves the expression onto its own line and the comment governs the
+ * wrong statement.
+ */
+// eslint-disable-next-line no-control-regex
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/g;
+/** Titles are attacker-controlled; bound them and strip control characters. */
+function cleanTitle(value) {
+    if (typeof value !== "string")
+        return "";
+    return value.replace(CONTROL_CHARACTERS, "").normalize("NFC").trim().slice(0, 512);
+}
+/**
+ * Reads the declared outline and resolves each destination to a page.
+ *
+ * The outline a document declares, never one inferred from its text: a document
+ * with no `/Outlines` returns an empty tree and exits 0, which is an answer
+ * rather than a failure.
+ *
+ * URLs are recorded, never followed — no fetch, no HEAD, no DNS. `unsafeUrl` is
+ * deliberately not surfaced as `url`: pdf.js populates `url` only when the
+ * scheme passed its own validation, and putting a rejected `javascript:` or
+ * `file:` URI into a field named as though it were clickable would be a
+ * misrepresentation.
+ */
+export async function readOutline(handle) {
+    const sink = new DiagnosticSink();
+    const headingLevels = new Map();
+    const { doc } = handle;
+    let raw;
+    try {
+        raw = (await handle.within(() => doc.getOutline()));
+    }
+    catch {
+        // A document with a malformed /Outlines reports no outline rather than
+        // failing: the outline is not why the caller opened the document.
+        raw = null;
+    }
+    if (!raw || raw.length === 0)
+        return { outline: [], diagnostics: sink.all(), headingLevels };
+    // `getPageIndex` walks the page tree, so a 500-entry outline on a long
+    // document is quadratic without this.
+    const resolved = new Map();
+    const pageFor = async (entry, title) => {
+        const dest = entry.dest;
+        if (dest === null || dest === undefined)
+            return null;
+        try {
+            const target = Array.isArray(dest)
+                ? dest
+                : typeof dest === "string"
+                    ? await handle.within(() => doc.getDestination(dest))
+                    : null;
+            const first = Array.isArray(target) ? target[0] : null;
+            if (!first || typeof first.num !== "number")
+                return null;
+            const key = `${first.num}R${first.gen ?? 0}`;
+            if (resolved.has(key))
+                return resolved.get(key) ?? null;
+            const index = await handle.within(() => doc.getPageIndex(first));
+            const page = index + 1;
+            resolved.set(key, page);
+            return page;
+        }
+        catch {
+            sink.add({
+                code: CODES.destinationUnresolved,
+                quality: "approximate",
+                message: `The destination for "${title}" does not resolve to a page`,
+                construct: title,
+                remediation: "The entry is kept with a null page rather than dropped.",
+            });
+            return null;
+        }
+    };
+    const walk = async (entries, level) => {
+        if (level > MAX_OUTLINE_DEPTH) {
+            sink.add({
+                code: CODES.outlineTooDeep,
+                quality: "unsupported",
+                message: `The outline nests deeper than ${MAX_OUTLINE_DEPTH} levels and was truncated`,
+            });
+            return [];
+        }
+        const out = [];
+        for (const entry of entries) {
+            const title = cleanTitle(entry.title);
+            const page = await pageFor(entry, title);
+            if (title && page !== null && !headingLevels.has(title))
+                headingLevels.set(title, level);
+            out.push({
+                title,
+                level,
+                page,
+                ...(typeof entry.url === "string" ? { url: entry.url } : {}),
+                children: await walk(entry.items ?? [], level + 1),
+            });
+        }
+        return out;
+    };
+    const outline = await walk(raw, 1);
+    return { outline, diagnostics: sink.all(), headingLevels };
+}
+/** Renders the tree for the human-facing streams, two spaces per level. */
+export function formatOutline(entries) {
+    const lines = [];
+    const walk = (nodes) => {
+        for (const node of nodes) {
+            const indent = "  ".repeat(node.level - 1);
+            lines.push(`${indent}${node.title} (p. ${node.page ?? "—"})`);
+            walk(node.children);
+        }
+    };
+    walk(entries);
+    return lines.length ? `${lines.join("\n")}\n` : "";
+}
+//# sourceMappingURL=outline.js.map

package/dist/pdf/outline.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.js","sourceRoot":"","sources":["../../src/pdf/outline.ts"],"names":[],"mappings":"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"}

package/dist/pdf/read.d.ts

@@ -0,0 +1,62 @@
+import type { PdfDiagnostic } from "./types.js";
+/**
+ * 64 MiB.
+ *
+ * Not the 256 MB a PDF's own size limits would suggest. The buffer is resident,
+ * it is then *transferred* into the parser, and pdf.js's object cache on top of
+ * it commonly runs three to five times the file size — so a 256 MB input is a
+ * multi-gigabyte process, and the failure is an OOM abort with no diagnostic at
+ * all. That is the shape of failure `MAX_DEPTH` exists to prevent in the ADF
+ * reader. Real corpora sit far below this: papers and forms are single-digit
+ * megabytes, scanned manuals twenty to eighty, and the tail past 64 MiB is
+ * image-only scans that carry no text layer to extract anyway.
+ *
+ * `--max-bytes` raises it, up to {@link MAX_INPUT_CEILING}.
+ */
+export declare const MAX_INPUT_BYTES: number;
+/** The highest `--max-bytes` will accept, so the flag cannot ask for an OOM. */
+export declare const MAX_INPUT_CEILING: number;
+/**
+ * How far in to look for `%PDF-`.
+ *
+ * The specification and every real reader tolerate leading bytes before the
+ * header, and files served through mail gateways routinely have them.
+ */
+export declare const HEADER_SCAN_BYTES = 1024;
+export interface ReadLimits {
+    maxBytes: number;
+}
+export type ReadResult = {
+    ok: true;
+    bytes: Uint8Array;
+    notices: PdfDiagnostic[];
+} | {
+    ok: false;
+    diagnostic: PdfDiagnostic;
+};
+/**
+ * Reads a PDF, from a path or from stdin when `source` is `-`.
+ *
+ * The guards mirror `readSnippetSource` in `src/snippets.ts` and the ADF reader:
+ * resolve through symlinks, refuse anything that is not a regular file *on the
+ * open descriptor* so it cannot be swapped between the check and the read, open
+ * with `O_NONBLOCK` so a FIFO does not block until a writer appears, and cap the
+ * size. The NUL-byte rejection does not carry over — a PDF is binary.
+ */
+export declare function readInput(source: string, limits: ReadLimits): Promise<ReadResult>;
+export type PageRangeResult = {
+    ok: true;
+    pages: number[];
+} | {
+    ok: false;
+    diagnostic: PdfDiagnostic;
+};
+/**
+ * Parses `--pages`, e.g. `1,3,5-8`, `-4`, `20-`.
+ *
+ * Validated against the real page count rather than trusted, and always emitted
+ * ascending and deduplicated regardless of the order it was written in —
+ * determinism, not convenience: `--pages 5,1` and `--pages 1,5` must produce
+ * byte-identical output.
+ */
+export declare function parsePageRange(spec: string, pageCount: number): PageRangeResult;

package/dist/pdf/read.js

@@ -0,0 +1,193 @@
+import fs from "node:fs";
+import path from "node:path";
+import { CODES, diagnostic } from "./diagnostics.js";
+/**
+ * 64 MiB.
+ *
+ * Not the 256 MB a PDF's own size limits would suggest. The buffer is resident,
+ * it is then *transferred* into the parser, and pdf.js's object cache on top of
+ * it commonly runs three to five times the file size — so a 256 MB input is a
+ * multi-gigabyte process, and the failure is an OOM abort with no diagnostic at
+ * all. That is the shape of failure `MAX_DEPTH` exists to prevent in the ADF
+ * reader. Real corpora sit far below this: papers and forms are single-digit
+ * megabytes, scanned manuals twenty to eighty, and the tail past 64 MiB is
+ * image-only scans that carry no text layer to extract anyway.
+ *
+ * `--max-bytes` raises it, up to {@link MAX_INPUT_CEILING}.
+ */
+export const MAX_INPUT_BYTES = 64 * 1024 * 1024;
+/** The highest `--max-bytes` will accept, so the flag cannot ask for an OOM. */
+export const MAX_INPUT_CEILING = 512 * 1024 * 1024;
+/**
+ * How far in to look for `%PDF-`.
+ *
+ * The specification and every real reader tolerate leading bytes before the
+ * header, and files served through mail gateways routinely have them.
+ */
+export const HEADER_SCAN_BYTES = 1024;
+const SIGNATURE = Buffer.from("%PDF-", "latin1");
+function refuse(code, message, remediation) {
+    return {
+        ok: false,
+        diagnostic: diagnostic({
+            code,
+            severity: "error",
+            quality: "unsupported",
+            message,
+            ...(remediation ? { remediation } : {}),
+        }),
+    };
+}
+/**
+ * Reads stdin to completion, refusing past the cap while it streams.
+ *
+ * Not `fs.readFileSync(0)`: when stdin is a pipe whose writer has not produced
+ * anything yet that throws `EAGAIN` rather than waiting, and piping a document
+ * in is a documented workflow. Streaming also means the cap is enforced as the
+ * bytes arrive — there is no `fstat` size to consult here, so a reader that
+ * buffered first and checked after would happily hold the whole oversized input
+ * before deciding it was too big.
+ */
+async function readStdin(limit) {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = chunk;
+        total += buffer.length;
+        if (total > limit) {
+            process.stdin.destroy();
+            return "too-large";
+        }
+        chunks.push(buffer);
+    }
+    return own(Buffer.concat(chunks));
+}
+/**
+ * Copies into an `ArrayBuffer` this process exclusively owns.
+ *
+ * `getDocument({ data })` **transfers and detaches** what it is given — verified
+ * against 6.3.289, where `byteLength` is 0 after the call. Node `Buffer`s below
+ * 8 KiB are views into a shared pooled allocator, so handing one over would
+ * detach a buffer other parts of the process are still using. Every path out of
+ * this module goes through here.
+ */
+function own(source) {
+    const copy = new Uint8Array(source.byteLength);
+    copy.set(source);
+    return copy;
+}
+/** Locates `%PDF-` within the leading bytes; -1 when it is not there. */
+function signatureOffset(bytes) {
+    const window = Buffer.from(bytes.buffer, bytes.byteOffset, Math.min(bytes.byteLength, HEADER_SCAN_BYTES + SIGNATURE.length));
+    return window.indexOf(SIGNATURE);
+}
+function leadingHex(bytes) {
+    return Buffer.from(bytes.subarray(0, 8)).toString("hex").replace(/(..)/g, "$1 ").trim();
+}
+/**
+ * Reads a PDF, from a path or from stdin when `source` is `-`.
+ *
+ * The guards mirror `readSnippetSource` in `src/snippets.ts` and the ADF reader:
+ * resolve through symlinks, refuse anything that is not a regular file *on the
+ * open descriptor* so it cannot be swapped between the check and the read, open
+ * with `O_NONBLOCK` so a FIFO does not block until a writer appears, and cap the
+ * size. The NUL-byte rejection does not carry over — a PDF is binary.
+ */
+export async function readInput(source, limits) {
+    const notices = [];
+    let bytes;
+    if (source === "-") {
+        const streamed = await readStdin(limits.maxBytes);
+        if (streamed === "too-large")
+            return refuse(CODES.tooLarge, `Input on stdin is larger than ${limits.maxBytes} bytes`, "Raise the bound with --max-bytes, or convert a smaller document.");
+        bytes = streamed;
+    }
+    else {
+        const resolved = path.resolve(source);
+        let real;
+        try {
+            real = fs.realpathSync(resolved);
+        }
+        catch {
+            return refuse(CODES.notRegularFile, `Input file not found: ${source}`);
+        }
+        let descriptor;
+        try {
+            descriptor = fs.openSync(real, fs.constants.O_RDONLY | fs.constants.O_NONBLOCK);
+        }
+        catch {
+            return refuse(CODES.notRegularFile, `Input file could not be opened: ${source}`);
+        }
+        try {
+            const stat = fs.fstatSync(descriptor);
+            if (!stat.isFile())
+                return refuse(CODES.notRegularFile, `Input path is not a regular file: ${source}`);
+            if (stat.size > limits.maxBytes)
+                return refuse(CODES.tooLarge, `Input is ${stat.size} bytes, larger than ${limits.maxBytes}`, "Raise the bound with --max-bytes, or convert a smaller document.");
+            bytes = own(fs.readFileSync(descriptor));
+        }
+        finally {
+            fs.closeSync(descriptor);
+        }
+    }
+    if (bytes.byteLength === 0)
+        return refuse(CODES.emptyInput, `Input is empty: ${source}`);
+    const offset = signatureOffset(bytes);
+    if (offset === -1)
+        return refuse(CODES.notAPdf, `Input has no %PDF- signature in its first ${HEADER_SCAN_BYTES} bytes ` +
+            `(begins ${leadingHex(bytes)})`, "Check that this is a PDF and not an HTML error page, an archive, or another document format.");
+    // Accepted, not stripped: the byte offsets in the cross-reference table are
+    // measured from the start of the file as it stands, so slicing the prefix off
+    // would invalidate every one of them. pdf.js handles the offset itself.
+    if (offset > 0)
+        notices.push(diagnostic({
+            code: CODES.leadingBytesIgnored,
+            quality: "exact",
+            message: `The %PDF- signature is at byte ${offset}, not at the start of the file`,
+        }));
+    return { ok: true, bytes, notices };
+}
+/**
+ * Parses `--pages`, e.g. `1,3,5-8`, `-4`, `20-`.
+ *
+ * Validated against the real page count rather than trusted, and always emitted
+ * ascending and deduplicated regardless of the order it was written in —
+ * determinism, not convenience: `--pages 5,1` and `--pages 1,5` must produce
+ * byte-identical output.
+ */
+export function parsePageRange(spec, pageCount) {
+    const selected = new Set();
+    const invalid = (detail) => ({
+        ok: false,
+        diagnostic: diagnostic({
+            code: CODES.pageRangeInvalid,
+            severity: "error",
+            quality: "unsupported",
+            message: `Invalid --pages value: ${detail}`,
+            remediation: `This document has ${pageCount} page(s). Use a form like 1,3,5-8.`,
+        }),
+    });
+    for (const part of spec.split(",")) {
+        const token = part.trim();
+        if (!token)
+            return invalid(`empty range in "${spec}"`);
+        const match = /^(\d+)?(-)?(\d+)?$/.exec(token);
+        if (!match || (!match[1] && !match[3]))
+            return invalid(`"${token}" is not a page or a range`);
+        const [, rawStart, dash, rawEnd] = match;
+        const start = rawStart ? Number(rawStart) : 1;
+        const end = dash ? (rawEnd ? Number(rawEnd) : pageCount) : start;
+        if (!dash && rawStart && rawEnd)
+            return invalid(`"${token}" is not a page or a range`);
+        if (start < 1 || end < 1)
+            return invalid(`"${token}" names page 0; pages are 1-based`);
+        if (start > pageCount || end > pageCount)
+            return invalid(`"${token}" is outside 1-${pageCount}`);
+        if (start > end)
+            return invalid(`"${token}" runs backwards`);
+        for (let page = start; page <= end; page += 1)
+            selected.add(page);
+    }
+    return { ok: true, pages: [...selected].sort((a, b) => a - b) };
+}
+//# sourceMappingURL=read.js.map

package/dist/pdf/read.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"read.js","sourceRoot":"","sources":["../../src/pdf/read.ts"],"names":[],"mappings":"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"}

package/dist/pdf/struct.d.ts

@@ -0,0 +1,35 @@
+import { DiagnosticSink } from "./diagnostics.js";
+import type { PdfStructNode } from "./document.js";
+import type { PositionedRun } from "./text.js";
+import type { Block, BlockKind, MappingQuality } from "./types.js";
+/**
+ * How a structure-tree role maps onto a block.
+ *
+ * Data, deliberately, in the shape `FIDELITY` takes in
+ * `src/jira/adf/profile.ts`: a role a reader can look up beats a switch a reader
+ * has to trace. `block: null` means the role contributes nesting but emits
+ * nothing itself.
+ */
+export interface RoleMapping {
+    block: BlockKind | null;
+    quality: MappingQuality;
+    /** Heading level, for the roles that fix one. */
+    level?: number;
+    note: string;
+}
+export declare const ROLE_FIDELITY: Record<string, RoleMapping>;
+export interface StructResult {
+    blocks: Block[];
+    /** False when the page's tree carried nothing usable and geometry should run. */
+    usable: boolean;
+}
+/**
+ * Converts one page's structure tree into blocks.
+ *
+ * The pairing is by marked-content id: a `StructTreeContent` leaf's `id` and a
+ * `TextMarkedContent` item's `id` are the *same string* (`p5R_mc0`), verified
+ * against 6.3.289, and only `beginMarkedContentProps` carries one. `text.ts`
+ * has already attributed each run to its innermost id-bearing frame, so this
+ * only has to look runs up.
+ */
+export declare function blocksFromStruct(tree: PdfStructNode | null, runs: PositionedRun[], sink: DiagnosticSink, page: number): StructResult;

package/dist/pdf/struct.js

@@ -0,0 +1,226 @@
+import { CODES } from "./diagnostics.js";
+export const ROLE_FIDELITY = {
+    Document: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Part: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Art: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Sect: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Div: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    NonStruct: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    // Real producers mark running heads and page numbers as artifacts, which is
+    // why the tagged path gets header and footer removal for free.
+    Artifact: { block: null, quality: "exact", note: "Page furniture; dropped, as intended." },
+    H1: { block: "heading", quality: "exact", level: 1, note: "A level 1 heading." },
+    H2: { block: "heading", quality: "exact", level: 2, note: "A level 2 heading." },
+    H3: { block: "heading", quality: "exact", level: 3, note: "A level 3 heading." },
+    H4: { block: "heading", quality: "exact", level: 4, note: "A level 4 heading." },
+    H5: { block: "heading", quality: "exact", level: 5, note: "A level 5 heading." },
+    H6: { block: "heading", quality: "exact", level: 6, note: "A level 6 heading." },
+    H: {
+        block: "heading",
+        quality: "approximate",
+        note: "A generic heading; its level is inferred.",
+    },
+    Title: {
+        block: "heading",
+        quality: "approximate",
+        level: 1,
+        note: "Treated as a level 1 heading.",
+    },
+    P: { block: "paragraph", quality: "exact", note: "A paragraph." },
+    L: {
+        block: "list",
+        quality: "approximate",
+        note: "A list; ordered-ness is inferred from its labels.",
+    },
+    LI: { block: "listItem", quality: "exact", note: "A list item." },
+    Lbl: { block: null, quality: "exact", note: "An item label; consumed as the marker." },
+    LBody: { block: null, quality: "exact", note: "An item body; its content is the item's." },
+    Index: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Private: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Aside: { block: null, quality: "exact", note: "A container; contributes nesting only." },
+    Table: { block: "table", quality: "exact", note: "A table." },
+    // Row groups must be containers, not blocks. Left unmodelled they fall to the
+    // AP219 path, which emits one paragraph of everything beneath — collapsing
+    // every row of a table head into a single line and losing the table.
+    THead: { block: null, quality: "exact", note: "A row group; its rows belong to the table." },
+    TBody: { block: null, quality: "exact", note: "A row group; its rows belong to the table." },
+    TFoot: { block: null, quality: "exact", note: "A row group; its rows belong to the table." },
+    TR: { block: "tableRow", quality: "exact", note: "A table row." },
+    TD: { block: "tableCell", quality: "exact", note: "A table cell." },
+    TH: { block: "tableCell", quality: "exact", note: "A header cell." },
+    BlockQuote: { block: "blockquote", quality: "exact", note: "A block quote." },
+    Code: { block: "code", quality: "approximate", note: "A code block; no language is recorded." },
+    Caption: {
+        block: "caption",
+        quality: "approximate",
+        note: "A caption, emitted as emphasized text.",
+    },
+    Figure: { block: "figure", quality: "approximate", note: "A figure; only its text survives." },
+    Formula: {
+        block: "paragraph",
+        quality: "approximate",
+        note: "A formula, flattened to its text.",
+    },
+    TOC: { block: "list", quality: "approximate", note: "A table of contents, flattened to a list." },
+    TOCI: { block: "listItem", quality: "approximate", note: "A table-of-contents entry." },
+    Span: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    Quote: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    Note: { block: null, quality: "approximate", note: "Inline; folded into the enclosing block." },
+    Reference: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    BibEntry: { block: "paragraph", quality: "approximate", note: "A bibliography entry." },
+    Link: { block: null, quality: "approximate", note: "Text is kept; the href is not resolved." },
+    // Ruby and Warichu annotate East Asian text inline; their bases and
+    // annotations flatten into the enclosing block rather than becoming blocks.
+    Ruby: { block: null, quality: "approximate", note: "Inline; folded into the enclosing block." },
+    RB: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    RT: { block: null, quality: "approximate", note: "Inline; folded into the enclosing block." },
+    RP: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    Warichu: {
+        block: null,
+        quality: "approximate",
+        note: "Inline; folded into the enclosing block.",
+    },
+    WT: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    WP: { block: null, quality: "exact", note: "Inline; folded into the enclosing block." },
+    // Interactive elements carry no readable content of their own.
+    Form: { block: null, quality: "unsupported", note: "A form field; it carries no text to emit." },
+    Annot: { block: null, quality: "unsupported", note: "An annotation; not part of the content." },
+};
+/** Guards against a malformed tree; the walk is recursive over hostile input. */
+const MAX_STRUCT_DEPTH = 128;
+function spansFor(runs) {
+    const ordered = [...runs].sort((a, b) => a.page - b.page || a.index - b.index);
+    const spans = [];
+    for (const run of ordered) {
+        const previous = spans[spans.length - 1];
+        // Coalesced before emission, or a paragraph split into forty runs renders as
+        // `**a****b****c**`.
+        if (previous && previous.bold === run.bold && previous.italic === run.italic) {
+            const needsSpace = !/\s$/.test(previous.text) && !/^\s/.test(run.text);
+            previous.text += needsSpace ? ` ${run.text}` : run.text;
+            continue;
+        }
+        spans.push({ text: run.text, bold: run.bold, italic: run.italic, code: false });
+    }
+    return spans;
+}
+/**
+ * Converts one page's structure tree into blocks.
+ *
+ * The pairing is by marked-content id: a `StructTreeContent` leaf's `id` and a
+ * `TextMarkedContent` item's `id` are the *same string* (`p5R_mc0`), verified
+ * against 6.3.289, and only `beginMarkedContentProps` carries one. `text.ts`
+ * has already attributed each run to its innermost id-bearing frame, so this
+ * only has to look runs up.
+ */
+export function blocksFromStruct(tree, runs, sink, page) {
+    if (!tree)
+        return { blocks: [], usable: false };
+    const byMcid = new Map();
+    for (const run of runs) {
+        if (!run.mcid)
+            continue;
+        const bucket = byMcid.get(run.mcid);
+        if (bucket)
+            bucket.push(run);
+        else
+            byMcid.set(run.mcid, [run]);
+    }
+    if (byMcid.size === 0)
+        return { blocks: [], usable: false };
+    const provenance = (quality, role) => ({
+        path: "struct",
+        quality,
+        pages: [page],
+        ...(role ? { role } : {}),
+    });
+    /** Collects every run under a node, in document order. */
+    const gather = (node, depth) => {
+        if (depth > MAX_STRUCT_DEPTH)
+            return [];
+        if (node.type === "content" && node.id)
+            return byMcid.get(node.id) ?? [];
+        return (node.children ?? []).flatMap((child) => gather(child, depth + 1));
+    };
+    const walk = (node, depth) => {
+        if (depth > MAX_STRUCT_DEPTH)
+            return [];
+        const role = node.role;
+        if (!role || role === "Root")
+            return (node.children ?? []).flatMap((child) => walk(child, depth + 1));
+        const mapping = ROLE_FIDELITY[role];
+        if (!mapping) {
+            // The AD100 analogue, and the non-negotiable one: an unrecognized role
+            // reports and emits its text rather than disappearing. Dropping is the one
+            // degradation whose output is indistinguishable from success.
+            sink.add({
+                code: CODES.unknownRole,
+                quality: "unsupported",
+                message: `Structure role "${role}" is not modelled; its text was emitted as a paragraph`,
+                construct: role,
+                page,
+            });
+            const runsHere = gather(node, depth);
+            return runsHere.length
+                ? [
+                    {
+                        kind: "paragraph",
+                        spans: spansFor(runsHere),
+                        children: [],
+                        provenance: provenance("unsupported", role),
+                    },
+                ]
+                : [];
+        }
+        const children = (node.children ?? []).flatMap((child) => walk(child, depth + 1));
+        if (mapping.block === null)
+            return children;
+        if (mapping.quality === "approximate")
+            noteApproximation(role, sink, page);
+        const container = mapping.block === "list" ||
+            mapping.block === "listItem" ||
+            mapping.block === "table" ||
+            mapping.block === "tableRow" ||
+            mapping.block === "blockquote";
+        if (container)
+            return [
+                {
+                    kind: mapping.block,
+                    ...(mapping.block === "list" ? { ordered: false } : {}),
+                    spans: [],
+                    children,
+                    provenance: provenance(mapping.quality, role),
+                },
+            ];
+        const runsHere = gather(node, depth);
+        const spans = spansFor(runsHere);
+        if (spans.length === 0 && children.length === 0)
+            return [];
+        return [
+            {
+                kind: mapping.block,
+                ...(mapping.level ? { level: mapping.level } : {}),
+                ...(mapping.block === "tableCell" ? { header: role === "TH" } : {}),
+                spans,
+                children: mapping.block === "tableCell" ? [] : children,
+                provenance: provenance(mapping.quality, role),
+            },
+        ];
+    };
+    return { blocks: walk(tree, 0), usable: true };
+}
+/** One code per approximating role, so a caller learns what a tag cost. */
+function noteApproximation(role, sink, page) {
+    const mapping = ROLE_FIDELITY[role];
+    const code = role === "H"
+        ? CODES.headingLevelInferred
+        : role === "L" || role === "TOC"
+            ? CODES.listOrderingInferred
+            : role === "Figure"
+                ? CODES.figureTextOnly
+                : null;
+    if (!code)
+        return;
+    sink.add({ code, quality: "approximate", message: mapping.note, construct: role, page });
+}
+//# sourceMappingURL=struct.js.map