@substrat-run/attachment-extractors 0.1.4 → 0.2.1

package/dist/pdf.d.ts

@@ -0,0 +1,171 @@
+/**
+ * PDF → text (#1575): the text layer a PDF's pages draw, read without a dependency.
+ *
+ * **The bytes are a tenant's, so this is a hostile-input parser first and a PDF reader second.**
+ * Every structure a file can make large or circular has a bound of its own, and every bound
+ * ends the extraction legibly — `{ failed }` with a content-free reason, or the text read so
+ * far marked truncated — never a throw that escapes, and never a hang:
+ *
+ * - **Decompression** (`decodeStream`). Each stream's decoded size is counted as the decoder
+ *   produces it, against `PDF_STREAM_MAX` for the stream (past it: a bomb, and the file
+ *   fails) and against the extraction's inflate budget in total (past it: the text read so
+ *   far is kept, truncated). A declared `/Length` or `/DL` is never trusted for either.
+ * - **The cross-reference chain** (`readXref`): at most `PDF_XREF_SECTIONS` sections, and a
+ *   `/Prev` or `/XRefStm` that comes back to one already read is a loop, refused.
+ * - **Objects**: at most `PDF_OBJECTS_MAX` cross-reference entries, however large a `/Size`
+ *   or a subsection count claims to be — nothing is allocated from a declared count. An object
+ *   is parsed at most once (`objects`), and one whose resolution reaches itself — a `/Length`
+ *   naming its own stream, a chain of references back to the start — resolves to null.
+ * - **Object streams** do not nest: an object stream must itself sit at a file offset, as the
+ *   format requires, so one named as living in another object stream is refused.
+ * - **Nesting**: an array or dictionary at most `PDF_DEPTH_MAX` deep, a page tree at most
+ *   `PDF_TREE_DEPTH_MAX` deep and never through one of its own ancestors, a form XObject at
+ *   most `PDF_FORM_DEPTH_MAX` deep and never inside itself. Every walk is a loop with a depth
+ *   counter or a recursion with one: none follows what the file says without counting.
+ * - **Memory** (`Retained`): what the extraction keeps — cached decoded streams, a page's
+ *   joined content, parsed objects, cross-reference entries, CMap entries, font decoders — is
+ *   charged before it is allocated, at most `PDF_RETAINED_FACTOR` × the inflate budget plus
+ *   `PDF_RETAINED_BASE`. Every other allocation is bounded by a named constant: a token, a
+ *   stream (`PDF_STREAM_MAX`), the text collected, the operand stack.
+ * - **Work**: a token or a direct object larger than `EXTRACTION_STRIDE` is refused, so the
+ *   synchronous lexer never runs more than a stride between two checks of the signal, and
+ *   every loop over the file — the lexer's, the byte searches, the decoders, the content
+ *   interpreter — charges `Pace` and yields at a stride. Content is interpreted against a
+ *   budget of its own (`PDF_INTERPRET_FACTOR` × the inflate budget), so a page tree that
+ *   draws one form a thousand times cannot spend more than that.
+ *
+ * What it reads: the classic and the stream cross-reference forms, hybrid files, incremental
+ * updates, object streams, and — when the cross-reference data is unusable, as in a file
+ * edited by a tool that did not rewrite it — a scan for `N G obj` headers instead. Filters:
+ * Flate (with PNG predictors), LZW, ASCIIHex, ASCII85, RunLength. Image filters are not text
+ * and are skipped. Text is decoded through a font's `/ToUnicode` CMap where it has one, and
+ * through its encoding — WinAnsi, MacRoman, Standard, `/Differences` glyph names — where it
+ * has not. A composite font with no `/ToUnicode` names glyphs, not characters, so its text is
+ * unreadable and is not guessed at.
+ *
+ * What it does not: **encrypted files** are refused with that reason (their keys are derived
+ * with MD5 and RC4, which Web Crypto does not carry, and this package does not hand-roll a
+ * hash). **No OCR**: a scanned page has no text layer, so a scanned PDF extracts to nothing,
+ * which the kernel records `empty`.
+ */
+import { type ExtractionSignal } from '@substrat-run/kernel';
+import { Retained, Pace, type InflateBudget } from './shared.js';
+/** Cross-reference entries one file may declare, across every section. */
+export declare const PDF_OBJECTS_MAX = 200000;
+/** Cross-reference sections followed through `/Prev` and `/XRefStm`. */
+export declare const PDF_XREF_SECTIONS = 64;
+/** Nesting of arrays and dictionaries inside one object. */
+export declare const PDF_DEPTH_MAX = 32;
+/** Depth of the page tree. */
+export declare const PDF_TREE_DEPTH_MAX = 64;
+/** Page-tree nodes visited, pages included. */
+export declare const PDF_TREE_NODES_MAX = 50000;
+/** Depth of form XObjects drawn inside one another. */
+export declare const PDF_FORM_DEPTH_MAX = 8;
+/** Bytes one stream may decode to: past it, the stream is a bomb and the file fails. */
+export declare const PDF_STREAM_MAX: number;
+/** Content bytes interpreted, as a multiple of the inflate budget. */
+export declare const PDF_INTERPRET_FACTOR = 4;
+/**
+ * What one PDF extraction may hold at once, as a multiple of its inflate budget (`Retained`):
+ * the decoded streams themselves (at most one inflate budget), and as much again for what is
+ * built from them — parsed objects, the cross-reference, CMaps, fonts, joined page content.
+ */
+export declare const PDF_RETAINED_FACTOR = 2;
+/** And a base the structures need whatever the inflate budget: fonts, the cross-reference, objects. */
+export declare const PDF_RETAINED_BASE: number;
+interface PdfName {
+    readonly kind: 'name';
+    readonly name: string;
+}
+interface PdfString {
+    readonly kind: 'str';
+    readonly bytes: Uint8Array;
+}
+interface PdfRef {
+    readonly kind: 'ref';
+    readonly num: number;
+    readonly gen: number;
+}
+interface PdfStream {
+    readonly kind: 'stream';
+    readonly dict: PdfDict;
+    readonly start: number;
+    readonly length: number;
+    /** The object number it was read as, for the decode cache; null for none. */
+    readonly num: number | null;
+}
+type PdfDict = Map<string, PdfValue>;
+type PdfValue = null | boolean | number | PdfName | PdfString | PdfRef | PdfStream | PdfDict | PdfValue[];
+/** What a decoder did: its bytes, and whether the extraction's budget ran out on the way. */
+interface Decoded {
+    readonly data: Uint8Array;
+    /** True when the inflate budget, not the stream, ended the data. */
+    readonly exhausted: boolean;
+}
+/** LZW as PDF writes it (8-bit, early change by default). */
+declare function lzw(raw: Uint8Array, early: boolean, budget: InflateBudget, pace: Pace): Promise<Decoded>;
+declare function asciiHex(raw: Uint8Array, budget: InflateBudget, pace: Pace): Promise<Decoded>;
+declare function ascii85(raw: Uint8Array, budget: InflateBudget, pace: Pace): Promise<Decoded>;
+declare function runLength(raw: Uint8Array, budget: InflateBudget, pace: Pace): Promise<Decoded>;
+/** Undo a PNG predictor (`/Predictor` 10–15), row by row, with each row's own filter byte. */
+declare function unpredict(data: Uint8Array, parms: PdfDict | null, pace: Pace): Promise<Uint8Array>;
+/**
+ * A glyph name → its text: the names writers use, `uniXXXX`, `uXXXX`, and composed accents.
+ * The patterns below are anchored with one quantifier each (or fixed-width groups), so none
+ * can backtrack past linear — and a name is at most `GLYPH_NAME_MAX` long besides.
+ */
+declare function glyphText(name: string): string;
+/**
+ * A PDF's text, in page order. `{ text, truncated }` like every extractor here; a file that is
+ * not a readable PDF throws `MalformedInput` and one that breaks a bound
+ * `ExtractionBoundExceeded`, which the extractor turns into `{ failed }`.
+ */
+export declare function pdfExtract(body: Uint8Array, maxInflatedBytes: number, maxTextBytes: number, signal: ExtractionSignal, 
+/** The memory budget; the package's own tests pass one to read what was charged. */
+retained?: Retained, 
+/** The work budget; the package's own tests pass one to count what was charged. */
+pace?: Pace): Promise<{
+    text: string;
+    truncated: boolean;
+}>;
+/** The glyph-name and encoding tables, for the package's own tests. */
+export declare const pdfTables: {
+    glyphText: typeof glyphText;
+    WIN_ANSI: (string | null)[];
+    MAC_ROMAN: (string | null)[];
+    STANDARD: (string | null)[];
+};
+/** The stream decoders, for the package's own tests: each judged on what it charges and keeps. */
+export declare const pdfDecoders: {
+    unpredict: typeof unpredict;
+    asciiHex: typeof asciiHex;
+    ascii85: typeof ascii85;
+    runLength: typeof runLength;
+    lzw: typeof lzw;
+};
+/** The lexer, for the package's own tests: judged on what it charges for one token. */
+/** The CMap parser, for the package's own tests. */
+export declare const pdfCMap: (data: Uint8Array, pace: Pace, retained: Retained) => Promise<{
+    map: {
+        get(length: number, code: number): string | undefined;
+    };
+}>;
+/** What a font's decoder is charged, for the package's own tests. */
+export declare const pdfFontCosts: {
+    simple: number;
+    difference: number;
+    composite: number;
+    decodePerByte: number;
+};
+/** A CodeMap with nothing parsed into it, for the package's own tests to define and seal directly. */
+export declare const pdfCodeMap: (retained: Retained) => {
+    setChar(length: number, code: number, text: string): void;
+    seal(pace: Pace): Promise<unknown>;
+    get(length: number, code: number): string | undefined;
+};
+export declare const pdfLexer: (buf: Uint8Array, pace: Pace) => {
+    next(): unknown;
+};
+export {};
+//# sourceMappingURL=pdf.d.ts.map

package/dist/pdf.d.ts.map

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