@cairn-tool/cairn 3.1.0 → 3.3.0

package/dist/pdf/document.js

@@ -0,0 +1,272 @@
+import { createRequire } from "node:module";
+import path from "node:path";
+import { CODES, diagnostic } from "./diagnostics.js";
+/** Raised when the wall-clock budget expires. Classified as `AP005`. */
+export class DeadlineExceeded extends Error {
+    ms;
+    constructor(ms) {
+        super(`Exceeded the ${ms}ms budget`);
+        this.ms = ms;
+        this.name = "DeadlineExceeded";
+    }
+}
+/** Raised when the install is broken, rather than the document. */
+export class PdfjsUnavailableError extends Error {
+    constructor(cause) {
+        super(`The PDF parser could not be loaded (${cause}). Reinstall @cairn-tool/cairn; ` +
+            "this is an installation problem rather than a problem with the document.");
+        this.name = "PdfjsUnavailableError";
+    }
+}
+/**
+ * Resolves pdfjs's asset directories.
+ *
+ * `createRequire(import.meta.url)` is the idiom `src/sqlite.ts` already uses.
+ * Resolving `package.json` rather than the entry point lands at the package root
+ * with no `..` climbing, and works because pdfjs-dist publishes no `exports`
+ * map.
+ *
+ * These are **runtime resolutions into another package's directory, not files
+ * cairn packs**. Nothing here belongs in `package.json` `files`; this looks like
+ * the `.markdownlintrc` packaging trap and is not one.
+ */
+function pdfjsRoot() {
+    try {
+        return path.dirname(createRequire(import.meta.url).resolve("pdfjs-dist/package.json"));
+    }
+    catch (error) {
+        throw new PdfjsUnavailableError(error.message);
+    }
+}
+/**
+ * A trailing separator is load-bearing: pdf.js concatenates
+ * `cMapUrl + name + ".bcmap"`, so omitting it produces a wrong path, no cmap,
+ * and silently missing CJK text — a degradation indistinguishable from success.
+ */
+function assetDir(root, name) {
+    return `${path.join(root, name)}${path.sep}`;
+}
+let cached;
+/**
+ * Imports the **legacy** build.
+ *
+ * Not a preference. The package-root entry prints
+ * "Please use the `legacy` build in Node.js environments" and then throws
+ * `hashOriginal.toHex is not a function`: it assumes a V8 with
+ * `Uint8Array.prototype.toHex`, which Node 22 and 23 do not have. The legacy
+ * build works across cairn's whole `engines` range.
+ *
+ * The `process.emitWarning` swap is the same guard `src/sqlite.ts` applies to
+ * `node:sqlite`: stderr carries the diagnostics stream, and an experimental
+ * warning emitted at import time would land in it.
+ */
+async function loadPdfjs() {
+    if (cached)
+        return cached;
+    const emit = process.emitWarning;
+    try {
+        process.emitWarning = () => { };
+        cached = await import("pdfjs-dist/legacy/build/pdf.mjs");
+    }
+    catch (error) {
+        throw new PdfjsUnavailableError(error.message);
+    }
+    finally {
+        process.emitWarning = emit;
+    }
+    return cached;
+}
+/**
+ * A pathological document can emit a warning per object; past this the count is
+ * kept and the text is dropped.
+ */
+const CAPTURE_CAP = 2000;
+/**
+ * Opens a document, runs `body`, and tears down — in that order, always.
+ *
+ * A scoped-resource function rather than an open/close pair so a caller cannot
+ * forget the teardown. On 6.3.289 pdf.js uses the main-thread fake worker in
+ * Node (no worker thread is spawned, verified), so a leaked handle does not hang
+ * the process — but `destroy()` still releases the parsed object graph, and a
+ * future version spawning a real worker would make it load-bearing.
+ */
+export async function withDocument(data, options, body) {
+    const pdfjs = await loadPdfjs();
+    const root = pdfjsRoot();
+    // pdf.js refuses a Node `Buffer` outright — "Please provide binary data as
+    // `Uint8Array`" — even though a Buffer is one. `read.ts` already hands over a
+    // plain array it owns, but normalizing here means no caller can get it wrong,
+    // and this is the site whose job is to absorb exactly that.
+    const bytes = data.constructor === Uint8Array ? data : Uint8Array.from(data);
+    const captured = [];
+    let dropped = 0;
+    const saved = {
+        log: console.log,
+        warn: console.warn,
+        error: console.error,
+        info: console.info,
+        debug: console.debug,
+    };
+    const capture = (...args) => {
+        if (captured.length < CAPTURE_CAP)
+            captured.push(args.map(String).join(" "));
+        else
+            dropped += 1;
+    };
+    // Captured rather than silenced. pdf.js routes warn() to console.warn, which
+    // is stderr — the stream that carries this toolset's diagnostics and must be
+    // empty on a clean run. Capturing also gives `validate` its only signal for a
+    // reconstructed xref, a substituted font, or an unsupported filter; setting
+    // verbosity to ERRORS would keep stderr clean and take those away.
+    console.log = capture;
+    console.warn = capture;
+    console.error = capture;
+    console.info = capture;
+    console.debug = capture;
+    const deadline = Date.now() + options.timeoutMs;
+    const within = async (work) => {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new DeadlineExceeded(options.timeoutMs);
+        let timer;
+        try {
+            return await Promise.race([
+                work(),
+                new Promise((_, reject) => {
+                    // unref'd, or the timer itself keeps the event loop alive and the CLI
+                    // waits out the whole budget after it has already written its output.
+                    timer = setTimeout(() => reject(new DeadlineExceeded(options.timeoutMs)), remaining);
+                    timer.unref();
+                }),
+            ]);
+        }
+        finally {
+            if (timer)
+                clearTimeout(timer);
+        }
+    };
+    let task;
+    try {
+        let needsPassword = false;
+        task = pdfjs.getDocument({
+            data: bytes,
+            // No `url` and no `docBaseUrl`: absence is the hardening. Supplying either
+            // would make pdf.js the thing performing I/O, and the toolset could no
+            // longer claim it does not reach the network.
+            verbosity: pdfjs.VerbosityLevel.WARNINGS,
+            cMapUrl: assetDir(root, "cmaps"),
+            cMapPacked: true,
+            standardFontDataUrl: assetDir(root, "standard_fonts"),
+            iccUrl: assetDir(root, "iccs"),
+            wasmUrl: assetDir(root, "wasm"),
+            useWasm: false,
+            // The field that actually keeps the no-network claim true: it forces the
+            // main thread to supply cmap and font bytes from the paths above instead
+            // of letting the worker call fetch().
+            useWorkerFetch: false,
+            // Probing the host's installed fonts would make output machine-dependent.
+            useSystemFonts: false,
+            disableFontFace: true,
+            // Always false, in every command. Enumerating every damaged page is worth
+            // more than dying on the first, and `--strict` changes the exit rule
+            // rather than the parse.
+            stopAtErrors: false,
+            maxImageSize: 32 * 1024 * 1024,
+        });
+        // Never prompts: a CLI that blocks on a TTY read is unusable in a pipeline.
+        // There is no --password flag, so this only ever refuses.
+        task.onPassword = (reply) => {
+            needsPassword = true;
+            reply(new Error("password required"));
+        };
+        const doc = (await within(() => task.promise));
+        if (doc.numPages > options.maxPages)
+            throw new PageBudgetExceeded(doc.numPages, options.maxPages);
+        void needsPassword;
+        const permissions = await within(() => doc.getPermissions());
+        const handle = {
+            doc,
+            notices: captured,
+            // getPermissions() returns null on an unencrypted document and a Set on an
+            // encrypted one, verified against 6.3.289 — so a non-null result here with
+            // no password supplied means the document opened on an empty user
+            // password, and its restrictions are advisory only.
+            encrypted: permissions !== null,
+            within,
+        };
+        return await body(handle);
+    }
+    finally {
+        // destroy() first, restore second. pdf.js fires callbacks during teardown,
+        // and restoring the console before the worker is gone lets a late warning
+        // escape onto a stream that is carrying a payload.
+        if (task) {
+            try {
+                await task.destroy();
+            }
+            catch {
+                // Teardown failure cannot change the answer already computed.
+            }
+        }
+        Object.assign(console, saved);
+        if (dropped > 0)
+            captured.push(`(${dropped} further parser messages dropped)`);
+    }
+}
+/** Raised before any page is touched, when the document is larger than allowed. */
+export class PageBudgetExceeded extends Error {
+    pages;
+    limit;
+    constructor(pages, limit) {
+        super(`Document has ${pages} pages, more than the ${limit} allowed`);
+        this.pages = pages;
+        this.limit = limit;
+        this.name = "PageBudgetExceeded";
+    }
+}
+/**
+ * Maps a thrown value onto a finding.
+ *
+ * Matched by class where pdf.js exports one, never by `error.name`: a name is a
+ * string that has drifted before, and the classes are exported precisely so a
+ * consumer can branch on them.
+ *
+ * The distinction between `AP002` and `AP100` is worth keeping: `AP002` means
+ * the bytes never had a `%PDF-` header, decided by `read.ts` before pdf.js ran,
+ * and `AP100` means it looked like a PDF and could not be parsed. That is the
+ * difference between "wrong file" and "damaged file".
+ */
+export async function classify(error, page) {
+    const pdfjs = await loadPdfjs().catch(() => null);
+    const message = error instanceof Error ? error.message : String(error);
+    const build = (code, text, remediation) => diagnostic({
+        code,
+        severity: "error",
+        quality: "unsupported",
+        message: text,
+        ...(page !== undefined ? { page } : {}),
+        ...(remediation ? { remediation } : {}),
+    });
+    if (error instanceof DeadlineExceeded)
+        return build(CODES.timedOut, message, "Raise the budget with --timeout.");
+    if (error instanceof PageBudgetExceeded)
+        return build(CODES.tooManyPages, message, "Raise the bound with --max-pages.");
+    if (error instanceof PdfjsUnavailableError)
+        return build(CODES.failure, message);
+    if (pdfjs) {
+        if (error instanceof pdfjs.PasswordException) {
+            const incorrect = error.code === pdfjs.PasswordResponses?.INCORRECT_PASSWORD;
+            return build(incorrect ? CODES.passwordIncorrect : CODES.passwordRequired, incorrect
+                ? "The document was encrypted with a password this tool was not given"
+                : "The document is encrypted and requires a password to open", "This toolset takes no password. Decrypt the document with another tool first.");
+        }
+        if (error instanceof pdfjs.InvalidPDFException)
+            return build(CODES.unparseable, `The document could not be parsed even after recovery: ${message}`);
+        if (pdfjs.ResponseException && error instanceof pdfjs.ResponseException)
+            return build(CODES.failure, `The parser attempted a network request, which should be impossible: ${message}`, "Report this: it means a hardening option stopped taking effect.");
+    }
+    if (page !== undefined)
+        return build(CODES.pageUnreadable, `Page ${page}: ${message}`);
+    return build(CODES.failure, message);
+}
+//# sourceMappingURL=document.js.map

package/dist/pdf/document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document.js","sourceRoot":"","sources":["../../src/pdf/document.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAgIrD,wEAAwE;AACxE,MAAM,OAAO,gBAAiB,SAAQ,KAAK;IACpB;IAArB,YAAqB,EAAU;QAC7B,KAAK,CAAC,gBAAgB,EAAE,WAAW,CAAC,CAAC;QADlB,OAAE,GAAF,EAAE,CAAQ;QAE7B,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;IACjC,CAAC;CACF;AAED,mEAAmE;AACnE,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAC9C,YAAY,KAAa;QACvB,KAAK,CACH,uCAAuC,KAAK,kCAAkC;YAC5E,0EAA0E,CAC7E,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;IACtC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,SAAS,SAAS;IAChB,IAAI,CAAC;QACH,OAAO,IAAI,CAAC,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,yBAAyB,CAAC,CAAC,CAAC;IACzF,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,QAAQ,CAAC,IAAY,EAAE,IAAY;IAC1C,OAAO,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;AAC/C,CAAC;AAED,IAAI,MAAW,CAAC;AAEhB;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,SAAS;IACtB,IAAI,MAAM;QAAE,OAAO,MAAM,CAAC;IAC1B,MAAM,IAAI,GAAG,OAAO,CAAC,WAAW,CAAC;IACjC,IAAI,CAAC;QACH,OAAO,CAAC,WAAW,GAAG,GAAG,EAAE,GAAE,CAAC,CAAC;QAC/B,MAAM,GAAG,MAAM,MAAM,CAAC,iCAAiC,CAAC,CAAC;IAC3D,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,IAAI,qBAAqB,CAAE,KAAe,CAAC,OAAO,CAAC,CAAC;IAC5D,CAAC;YAAS,CAAC;QACT,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;IAC7B,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,MAAM,WAAW,GAAG,IAAI,CAAC;AAEzB;;;;;;;;GAQG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAChC,IAAgB,EAChB,OAAoB,EACpB,IAA0C;IAE1C,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC;IAChC,MAAM,IAAI,GAAG,SAAS,EAAE,CAAC;IAEzB,2EAA2E;IAC3E,8EAA8E;IAC9E,8EAA8E;IAC9E,4DAA4D;IAC5D,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,KAAK,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,UAAU,CAAC,IAAI,CAAC,IAAyB,CAAC,CAAC;IAElG,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,MAAM,KAAK,GAAG;QACZ,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;QACpB,IAAI,EAAE,OAAO,CAAC,IAAI;QAClB,KAAK,EAAE,OAAO,CAAC,KAAK;KACrB,CAAC;IACF,MAAM,OAAO,GAAG,CAAC,GAAG,IAAe,EAAQ,EAAE;QAC3C,IAAI,QAAQ,CAAC,MAAM,GAAG,WAAW;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;;YACxE,OAAO,IAAI,CAAC,CAAC;IACpB,CAAC,CAAC;IAEF,6EAA6E;IAC7E,6EAA6E;IAC7E,8EAA8E;IAC9E,4EAA4E;IAC5E,mEAAmE;IACnE,OAAO,CAAC,GAAG,GAAG,OAAO,CAAC;IACtB,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC;IACvB,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC;IACxB,OAAO,CAAC,IAAI,GAAG,OAAO,CAAC;IACvB,OAAO,CAAC,KAAK,GAAG,OAAO,CAAC;IAExB,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,OAAO,CAAC,SAAS,CAAC;IAChD,MAAM,MAAM,GAAG,KAAK,EAAK,IAAsB,EAAc,EAAE;QAC7D,MAAM,SAAS,GAAG,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACxC,IAAI,SAAS,IAAI,CAAC;YAAE,MAAM,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAClE,IAAI,KAAiC,CAAC;QACtC,IAAI,CAAC;YACH,OAAO,MAAM,OAAO,CAAC,IAAI,CAAC;gBACxB,IAAI,EAAE;gBACN,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE;oBAC/B,sEAAsE;oBACtE,sEAAsE;oBACtE,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,gBAAgB,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;oBACrF,KAAK,CAAC,KAAK,EAAE,CAAC;gBAChB,CAAC,CAAC;aACH,CAAC,CAAC;QACL,CAAC;gBAAS,CAAC;YACT,IAAI,KAAK;gBAAE,YAAY,CAAC,KAAK,CAAC,CAAC;QACjC,CAAC;IACH,CAAC,CAAC;IAEF,IAAI,IAAS,CAAC;IACd,IAAI,CAAC;QACH,IAAI,aAAa,GAAG,KAAK,CAAC;QAC1B,IAAI,GAAG,KAAK,CAAC,WAAW,CAAC;YACvB,IAAI,EAAE,KAAK;YACX,2EAA2E;YAC3E,uEAAuE;YACvE,8CAA8C;YAC9C,SAAS,EAAE,KAAK,CAAC,cAAc,CAAC,QAAQ;YACxC,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;YAChC,UAAU,EAAE,IAAI;YAChB,mBAAmB,EAAE,QAAQ,CAAC,IAAI,EAAE,gBAAgB,CAAC;YACrD,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAC9B,OAAO,EAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;YAC/B,OAAO,EAAE,KAAK;YACd,yEAAyE;YACzE,yEAAyE;YACzE,sCAAsC;YACtC,cAAc,EAAE,KAAK;YACrB,0EAA0E;YAC1E,cAAc,EAAE,KAAK;YACrB,eAAe,EAAE,IAAI;YACrB,0EAA0E;YAC1E,qEAAqE;YACrE,yBAAyB;YACzB,YAAY,EAAE,KAAK;YACnB,YAAY,EAAE,EAAE,GAAG,IAAI,GAAG,IAAI;SAC/B,CAAC,CAAC;QAEH,4EAA4E;QAC5E,0DAA0D;QAC1D,IAAI,CAAC,UAAU,GAAG,CAAC,KAA+B,EAAE,EAAE;YACpD,aAAa,GAAG,IAAI,CAAC;YACrB,KAAK,CAAC,IAAI,KAAK,CAAC,mBAAmB,CAAC,CAAC,CAAC;QACxC,CAAC,CAAC;QAEF,MAAM,GAAG,GAAG,CAAC,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,CAAsB,CAAC;QAEpE,IAAI,GAAG,CAAC,QAAQ,GAAG,OAAO,CAAC,QAAQ;YACjC,MAAM,IAAI,kBAAkB,CAAC,GAAG,CAAC,QAAQ,EAAE,OAAO,CAAC,QAAQ,CAAC,CAAC;QAC/D,KAAK,aAAa,CAAC;QAEnB,MAAM,WAAW,GAAG,MAAM,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,cAAc,EAAE,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAiB;YAC3B,GAAG;YACH,OAAO,EAAE,QAAQ;YACjB,2EAA2E;YAC3E,2EAA2E;YAC3E,kEAAkE;YAClE,oDAAoD;YACpD,SAAS,EAAE,WAAW,KAAK,IAAI;YAC/B,MAAM;SACP,CAAC;QACF,OAAO,MAAM,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,CAAC;YAAS,CAAC;QACT,2EAA2E;QAC3E,0EAA0E;QAC1E,mDAAmD;QACnD,IAAI,IAAI,EAAE,CAAC;YACT,IAAI,CAAC;gBACH,MAAM,IAAI,CAAC,OAAO,EAAE,CAAC;YACvB,CAAC;YAAC,MAAM,CAAC;gBACP,8DAA8D;YAChE,CAAC;QACH,CAAC;QACD,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,KAAK,CAAC,CAAC;QAC9B,IAAI,OAAO,GAAG,CAAC;YAAE,QAAQ,CAAC,IAAI,CAAC,IAAI,OAAO,mCAAmC,CAAC,CAAC;IACjF,CAAC;AACH,CAAC;AAED,mFAAmF;AACnF,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAEhC;IACA;IAFX,YACW,KAAa,EACb,KAAa;QAEtB,KAAK,CAAC,gBAAgB,KAAK,yBAAyB,KAAK,UAAU,CAAC,CAAC;QAH5D,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAAQ;QAGtB,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,KAAc,EAAE,IAAa;IAC1D,MAAM,KAAK,GAAG,MAAM,SAAS,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;IAClD,MAAM,OAAO,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAEvE,MAAM,KAAK,GAAG,CAAC,IAAY,EAAE,IAAY,EAAE,WAAoB,EAAiB,EAAE,CAChF,UAAU,CAAC;QACT,IAAI;QACJ,QAAQ,EAAE,OAAO;QACjB,OAAO,EAAE,aAAa;QACtB,OAAO,EAAE,IAAI;QACb,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACvC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxC,CAAC,CAAC;IAEL,IAAI,KAAK,YAAY,gBAAgB;QACnC,OAAO,KAAK,CAAC,KAAK,CAAC,QAAQ,EAAE,OAAO,EAAE,kCAAkC,CAAC,CAAC;IAC5E,IAAI,KAAK,YAAY,kBAAkB;QACrC,OAAO,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE,OAAO,EAAE,mCAAmC,CAAC,CAAC;IACjF,IAAI,KAAK,YAAY,qBAAqB;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;IAEjF,IAAI,KAAK,EAAE,CAAC;QACV,IAAI,KAAK,YAAY,KAAK,CAAC,iBAAiB,EAAE,CAAC;YAC7C,MAAM,SAAS,GACZ,KAA2B,CAAC,IAAI,KAAK,KAAK,CAAC,iBAAiB,EAAE,kBAAkB,CAAC;YACpF,OAAO,KAAK,CACV,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,iBAAiB,CAAC,CAAC,CAAC,KAAK,CAAC,gBAAgB,EAC5D,SAAS;gBACP,CAAC,CAAC,oEAAoE;gBACtE,CAAC,CAAC,2DAA2D,EAC/D,+EAA+E,CAChF,CAAC;QACJ,CAAC;QACD,IAAI,KAAK,YAAY,KAAK,CAAC,mBAAmB;YAC5C,OAAO,KAAK,CACV,KAAK,CAAC,WAAW,EACjB,yDAAyD,OAAO,EAAE,CACnE,CAAC;QACJ,IAAI,KAAK,CAAC,iBAAiB,IAAI,KAAK,YAAY,KAAK,CAAC,iBAAiB;YACrE,OAAO,KAAK,CACV,KAAK,CAAC,OAAO,EACb,uEAAuE,OAAO,EAAE,EAChF,iEAAiE,CAClE,CAAC;IACN,CAAC;IAED,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,KAAK,CAAC,cAAc,EAAE,QAAQ,IAAI,KAAK,OAAO,EAAE,CAAC,CAAC;IACvF,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;AACvC,CAAC"}

package/dist/pdf/forms.d.ts

@@ -0,0 +1,9 @@
+import type { OpenDocument } from "./document.js";
+import type { PdfDiagnostic, PdfForm } from "./types.js";
+export interface FormResult {
+    form: PdfForm;
+    diagnostics: PdfDiagnostic[];
+}
+export declare function readForm(handle: OpenDocument): Promise<FormResult>;
+/** The human and llm rendering: one line per field. */
+export declare function formatForm(form: PdfForm): string;

package/dist/pdf/forms.js

@@ -0,0 +1,101 @@
+import { CODES, DiagnosticSink } from "./diagnostics.js";
+/** Field values arrive as strings, names, or arrays; anything else is dropped. */
+function text(value) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number" || typeof value === "boolean")
+        return String(value);
+    if (Array.isArray(value)) {
+        const parts = value.filter((item) => typeof item === "string");
+        return parts.length ? parts.join(", ") : undefined;
+    }
+    return undefined;
+}
+function fieldFrom(name, widgets, pageCount) {
+    // The widgets of one field agree on everything but position, so the first is
+    // representative; the count is what the rest contribute.
+    const first = widgets[0] ?? {};
+    // A field attached to no page reports -1, not undefined — so the range check
+    // below is what turns the sentinel into `page: null` instead of page 0.
+    const zeroBased = typeof first.page === "number" ? first.page : null;
+    const page = zeroBased === null || zeroBased < 0 || zeroBased >= pageCount ? null : zeroBased + 1;
+    return {
+        name,
+        type: typeof first.type === "string" && first.type ? first.type : "unknown",
+        page,
+        ...(text(first.value) === undefined ? {} : { value: text(first.value) }),
+        ...(text(first.defaultValue) === undefined ? {} : { defaultValue: text(first.defaultValue) }),
+        readOnly: first.editable === false,
+        hidden: first.hidden === true,
+        password: first.password === true,
+        ...(typeof first.charLimit === "number" && first.charLimit > 0
+            ? { charLimit: first.charLimit }
+            : {}),
+        ...(text(first.exportValues) === undefined ? {} : { exportValues: text(first.exportValues) }),
+        widgets: widgets.length,
+    };
+}
+export async function readForm(handle) {
+    const sink = new DiagnosticSink();
+    // Checked before the field lookup, not after: an XFA-only document has no
+    // AcroForm field objects at all, so an empty list here would otherwise be
+    // indistinguishable from a document carrying no form.
+    if (handle.doc.isPureXfa) {
+        sink.add({
+            code: CODES.formXfa,
+            quality: "approximate",
+            message: "This is an XFA form; its field values live in an XML packet that is not read",
+            remediation: "Open it in a viewer that supports XFA, or use pdf text for whatever static content the document carries.",
+        });
+        return { form: { type: "xfa", fieldCount: 0, fields: [] }, diagnostics: sink.all() };
+    }
+    // Null covers both "no /AcroForm" and "an /AcroForm declaring no fields":
+    // pdf.js reports `hasFields: false` for each and there is nothing in the API
+    // that separates them, so `none` is the only claim this can honestly make.
+    const objects = await handle.within(() => handle.doc.getFieldObjects());
+    if (!objects || objects.size === 0)
+        return { form: { type: "none", fieldCount: 0, fields: [] }, diagnostics: sink.all() };
+    const fields = [];
+    for (const [name, widgets] of objects) {
+        const list = (Array.isArray(widgets) ? widgets : []);
+        if (list.length === 0)
+            continue;
+        const field = fieldFrom(name, list, handle.doc.numPages);
+        if (field.page === null)
+            sink.add({
+                code: CODES.formFieldPageUnresolved,
+                quality: "exact",
+                construct: name,
+                message: `Field '${name}' does not resolve to a page in this document`,
+            });
+        fields.push(field);
+    }
+    // Byte comparison, never localeCompare: a differently configured CI runner
+    // would otherwise reorder the payload.
+    fields.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    return {
+        form: { type: "acroform", fieldCount: fields.length, fields },
+        diagnostics: sink.all(),
+    };
+}
+/** The human and llm rendering: one line per field. */
+export function formatForm(form) {
+    if (form.type === "xfa")
+        return "xfa form: field values are not readable\n";
+    if (form.fieldCount === 0)
+        return "no form fields\n";
+    const width = Math.max(...form.fields.map((field) => field.name.length));
+    const lines = form.fields.map((field) => {
+        const flags = [
+            field.readOnly ? "read-only" : "",
+            field.hidden ? "hidden" : "",
+            field.password ? "password" : "",
+        ].filter(Boolean);
+        const page = field.page === null ? "  -" : String(field.page).padStart(3);
+        const value = field.value === undefined ? "" : ` = ${JSON.stringify(field.value)}`;
+        const suffix = flags.length ? ` [${flags.join(", ")}]` : "";
+        return `${page}  ${field.name.padEnd(width)}  ${field.type}${value}${suffix}`;
+    });
+    return `${lines.join("\n")}\n`;
+}
+//# sourceMappingURL=forms.js.map

package/dist/pdf/forms.js.map

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

package/dist/pdf/inspect.d.ts

@@ -0,0 +1,42 @@
+import type { OpenDocument, PdfStructNode } from "./document.js";
+import type { PdfDiagnostic, PdfDocumentInfo, PdfPageInfo, TextLayer } from "./types.js";
+export declare function classifyTextLayer(characters: number, density: number): TextLayer;
+/**
+ * Converts a PDF `D:YYYYMMDDHHmmSS` date to ISO 8601 in UTC.
+ *
+ * Omitted rather than guessed when it does not parse, and never rendered in the
+ * host timezone: that would make the payload machine-dependent, which is the
+ * same reasoning the ADF converter applies to its own timestamps.
+ */
+export declare function parsePdfDate(value: unknown): string | undefined;
+/** True when a structure tree carries at least one marked-content leaf. */
+export declare function hasStructContent(node: PdfStructNode | null | undefined): boolean;
+export interface SummaryResult {
+    document: PdfDocumentInfo;
+    diagnostics: PdfDiagnostic[];
+}
+/**
+ * The document facts that cost nothing: no page is opened.
+ *
+ * Every command carries this, so a caller can read `document.tagged` off a
+ * `to-markdown` payload rather than making a second call. `structured` and
+ * `textLayer` are absent here because only a command that walks pages can
+ * measure them, and a field nobody measured must not read as a measurement.
+ */
+export declare function documentSummary(handle: OpenDocument): Promise<SummaryResult>;
+export interface InspectResult {
+    document: PdfDocumentInfo;
+    pages: PdfPageInfo[];
+    diagnostics: PdfDiagnostic[];
+}
+/**
+ * The page inventory, on top of {@link documentSummary}.
+ *
+ * `probeStructure` drives whether each page's structure tree is opened. It is on
+ * for `inspect`, because `structured` is one of the two fields the command
+ * exists to report, and off elsewhere.
+ */
+export declare function inspectDocument(handle: OpenDocument, options?: {
+    pages?: number[];
+    probeStructure?: boolean;
+}): Promise<InspectResult>;