bantamkit-mcp 0.26.0

package/dist/docread.d.ts

@@ -0,0 +1,357 @@
+/**
+ * The Node half of `runtime-py/src/bantamkit/docread.py`: deterministic text extraction,
+ * addressable by part and row, dispatched on what a file IS.
+ *
+ * The Python module is the reference and this file COPIES it — its rows, its omission
+ * records and its sentences, byte for byte, for the kinds it reads: `text`, `xlsx`,
+ * `docx`, `html` and `mhtml`. Every constant, token and sentence below is the Python
+ * one; where the reference reads something this half does not (`pdf` through
+ * `pdfread`, `doc`/`rtf` through `/usr/bin/textutil`), `sniff` still IDENTIFIES the
+ * container so the refusal names it, and `extract` refuses with a sentence that is a
+ * DELIBERATE divergence recorded in `docs/porting.md`.
+ *
+ * No third-party dependency. The reference leans on four standard-library modules that
+ * Node does not ship, and each is replaced by the smallest hand-written reader that
+ * reproduces the reference's answers on the reference's own fixtures:
+ *
+ * - `zipfile`    -> `ZipReader`: central-directory walk, stored + deflate (`node:zlib`
+ *                   `inflateRawSync`), CRC-32 checked the way `ZipFile.read` checks it.
+ * - `xml.etree`  -> `parseXml`: a namespace-expanding element tree with `.text`,
+ *                   `iter(tag)`, `find(tag)` and direct-child iteration — the four ET
+ *                   operations `docread.py` actually calls.
+ * - `html.parser` + `html.unescape` -> `HtmlText` over a line-for-line port of
+ *                   `HTMLParser.goahead` (CPython 3.12.13, `convert_charrefs=True`), so
+ *                   the DATA CHUNKS arrive in the same pieces — the chunking is visible in
+ *                   the rows because `_HtmlText` joins chunks with a space.
+ * - `email`      -> `parseMime`: multipart boundaries, header unfolding, Content-Type
+ *                   parameters, quoted-printable (`binascii.a2b_qp`) and base64.
+ *
+ * Python string semantics that JavaScript does not share are ported explicitly rather
+ * than approximated: `str.strip()`/`split()`/`splitlines()` use Python's whitespace and
+ * line-boundary sets (`PY_WS`, `pySplitlines`), `repr()` of a `str` and of `bytes` is
+ * `pyRepr`/`bytesRepr`, `sorted()` compares by code point (`cmpCodepoint`), and a UTF-8
+ * decode error reports the same `start` offset and `reason` CPython's decoder does
+ * (`utf8Scan`).
+ */
+import { BantamError } from './errors.js';
+export declare const NS_S = "{http://schemas.openxmlformats.org/spreadsheetml/2006/main}";
+export declare const NS_W = "{http://schemas.openxmlformats.org/wordprocessingml/2006/main}";
+export declare const NS_R = "{http://schemas.openxmlformats.org/officeDocument/2006/relationships}";
+export declare const SUPPORTED: readonly ["text", "xlsx", "docx", "pdf", "html", "mhtml"];
+export declare const TEXTUTIL_SUPPORTED: readonly ["doc", "rtf"];
+export declare const TEXTUTIL = "/usr/bin/textutil";
+export declare const DEFAULT_ROW_LIMIT = 50;
+export declare const PAGE_MAX_ROWS = 200;
+export declare const PAGE_MAX_BYTES = 3072;
+export declare const TEXT_MAX_BYTES: number;
+export declare const OMIT_MEDIA = "media";
+export declare const OMIT_BLANK_ROWS = "blank-rows";
+export declare const OMIT_NUMBER_FORMAT = "number-format";
+export declare const OMIT_UNREAD_PAGE = "unread-page";
+export declare const OMIT_UNMAPPED = "unmapped-text";
+export declare const OMIT_UNREAD_TAIL = "unread-tail";
+export declare const OMIT_SIZE_CAP = "size-cap";
+export declare const OMIT_UNPLACED_CELL = "unplaced-cell";
+/** Extraction failed. The message names what was seen, never just the format's own error. */
+export declare class DocumentReadError extends BantamError {
+}
+/** `str.strip()` with no argument. */
+export declare function pyStrip(s: string): string;
+/** `str.split()` with no argument: runs of whitespace, no empty fields. */
+export declare function pySplit(s: string): string[];
+/** `str.splitlines()`: Python's line boundaries, terminators dropped. */
+export declare function pySplitlines(s: string): string[];
+/** `sorted()` on strings: by code point, which is not what `Array.sort` does above U+FFFF. */
+export declare function cmpCodepoint(a: string, b: string): number;
+/** `repr(str)`. */
+export declare function pyRepr(s: string): string;
+/** `repr(bytes)`. */
+export declare function bytesRepr(buf: Uint8Array): string;
+export interface Utf8Scan {
+    /** Bytes `[0, end)` decode cleanly. */
+    end: number;
+    /** Where the first sequence no continuation could complete begins, or -1. */
+    invalidAt: number;
+    /** CPython's `UnicodeDecodeError.reason` for that sequence. */
+    reason: string;
+    /** With `final` false: the bytes past `end` are an incomplete trailing character. */
+    incomplete: boolean;
+}
+/**
+ * CPython's UTF-8 decoder, as a validator: the same `start` and `reason` its
+ * `UnicodeDecodeError` carries, and the same tolerance an incremental decoder has for a
+ * final character the read cut in half when `final` is false.
+ */
+export declare function utf8Scan(buf: Uint8Array, final: boolean): Utf8Scan;
+/**
+ * `encodings.normalize_encoding` after `codecs.lookup`'s own lower-casing: runs of anything
+ * that is not an ASCII letter, digit or `.` collapse to one `_`, and none leads or trails.
+ * `ISO 8859-1`, `ISO--8859--1` and `iso-8859-1;` are all `iso_8859_1`.
+ */
+export declare function pyNormalizeEncoding(encoding: string): string;
+/**
+ * `encodings.search_function`: the module `codecs.lookup(name)` would import, or `null`
+ * where it raises `LookupError`. The alias table is consulted on the normalized name and on
+ * the name with `.` as `_`; the module name itself is the fallback, and a name that is not
+ * a module — `cp-437` (`cp_437`), `x-mac-roman`, `latin.1` — is the `LookupError`.
+ */
+export declare function pyCodecModule(name: string): string | null;
+/**
+ * `bytes.decode(charset, errors="replace")`, falling back to UTF-8 on `LookupError`
+ * (`docread.py`, `_decoded_body`).
+ *
+ * Until H2 this was `TextDecoder(charset)` with the WHATWG label table, and review round 3
+ * measured that table against the codec registry on bytes `80 D0 E9 A4 FF`
+ * (`runtime-py/tests/data/docread/charset-table.json`): cp437, mac_roman and iso-8859-16
+ * are labels WHATWG does not have; iso-8859-9's 0x80–0x9F are C1 controls to Python and
+ * windows-1254's punctuation to WHATWG; Node 25.2.1's ICU decoder maps windows-1252's
+ * 0x80 to U+0080 and prints nothing for a trailing 0xFF under latin-1; us-ascii is
+ * windows-1252 there. The single-byte codecs are now `charsets.ts`, 256 characters per
+ * module written by the registry itself (79 codecs, 20 of them measured over all 256 bytes
+ * against the old path: 13 differed); the CJK codecs go through `TextDecoder` with
+ * CPython's replacement policy (`decodeMultiByte`, where the residual is quantified); a
+ * module this port has no decoder for (`utf_7`, `hz`, `iso2022_kr`, `johab`, the JIS X
+ * 0213 variants) decodes as UTF-8, which is the other remaining divergence.
+ *
+ * AMENDED at review round 4 (H1). This paragraph used to name `iso2022_*` among the modules
+ * with no decoder, and for seven of that family the code did something else and worse: the
+ * generator had written them a single-byte table, so they were decoded one byte at a time and
+ * their escape sequences became U+FFFD. The six `iso2022_jp*` modules now go through ICU's
+ * real decoder (`ESCAPE_LABELS`, where the three arms are scored); `hz`, `iso2022_kr` and
+ * `utf_7` are what is left of the no-decoder set, and for them this paragraph is now true.
+ */
+export declare function decodeCharset(buf: Uint8Array, charset: string): string;
+export interface OmissionDict {
+    subject: string;
+    count: number;
+    size: number;
+    where: string[];
+    what: string;
+    facts: Record<string, number>;
+}
+/** Something the file holds that the rows do not carry, as a COUNT and the fact behind it. */
+export declare class Omission {
+    readonly subject: string;
+    readonly count: number;
+    readonly size: number;
+    readonly where: readonly string[];
+    readonly what: string;
+    readonly facts: readonly (readonly [string, number])[];
+    constructor(subject: string, count: number, size?: number, where?: readonly string[], what?: string, facts?: readonly (readonly [string, number])[]);
+    /** The primitive form the contract layer takes, keys in the reference's order. */
+    asDict(): OmissionDict;
+}
+/** One addressable unit: a worksheet, or a `.docx` body. `rows` are rendered lines. */
+export declare class Part {
+    readonly name: string;
+    readonly index: number;
+    readonly rows: readonly string[];
+    readonly omissions: readonly Omission[];
+    constructor(name: string, index: number, rows: readonly string[], omissions?: readonly Omission[]);
+    get rowCount(): number;
+    /** UTF-8 bytes of this part's full rendering. EXTRACTED size, not file size. */
+    get textBytes(): number;
+}
+export declare class Document {
+    readonly kind: string;
+    readonly parts: readonly Part[];
+    readonly omissions: readonly Omission[];
+    constructor(kind: string, parts: readonly Part[], omissions?: readonly Omission[]);
+    get textBytes(): number;
+    /** Resolve by exact sheet name, else by 0-based index. Names win over numeric keys. */
+    part(key: string | number): Part;
+}
+/** A row slice of one part. `nextOffset` is null exactly when the part is exhausted. */
+export declare class Page {
+    readonly part: string;
+    readonly offset: number;
+    readonly rows: readonly string[];
+    readonly totalRows: number;
+    readonly nextOffset: number | null;
+    readonly truncatedBytes: number;
+    constructor(part: string, offset: number, rows: readonly string[], totalRows: number, nextOffset: number | null, truncatedBytes?: number);
+    get text(): string;
+}
+/** The container a file's own bytes declare it to be. `kind` decides; `what` explains. */
+export declare class Container {
+    readonly kind: string;
+    readonly what: string;
+    readonly named: string;
+    constructor(kind: string, what: string, named: string);
+    /** True when the name promises a container the bytes do not deliver. */
+    get suffixLies(): boolean;
+}
+export declare const SUFFIX_KINDS: Readonly<Record<string, string>>;
+export declare const HEAD_BYTES = 4096;
+/** What `path` IS. Magic bytes, then a zip's member list. The suffix is never consulted. */
+export declare function sniff(path: string): Container;
+/** `zipfile.BadZipFile`. Not a `DocumentReadError`: the reference lets it through too. */
+export declare class BadZipFile extends Error {
+    constructor(message: string);
+}
+export declare function crc32(buf: Uint8Array): number;
+/** `zipfile.ZipFile` read-only: the central directory, and `read(name)` with a CRC check. */
+export declare class ZipReader {
+    private readonly data;
+    private readonly entries;
+    private readonly concat;
+    /** `Path(p).name`, for the one sentence `read` composes itself (the bzip2/lzma ruling). */
+    private readonly pathName;
+    private readonly byName;
+    private constructor();
+    static open(path: string): ZipReader;
+    static from(data: Buffer, pathName?: string): ZipReader;
+    namelist(): string[];
+    /** `infolist()` reduced to what `_media_index` reads: name, size, and whether it is a directory. */
+    infolist(): {
+        filename: string;
+        fileSize: number;
+        isDir: boolean;
+    }[];
+    has(name: string): boolean;
+    /** `ZipFile.read(name)`; a missing member is a `KeyError` — here `RangeError`, see `readMember`. */
+    read(name: string): Buffer;
+}
+/**
+ * The ruled bzip2/lzma refusal, as its own class — review round 4 (M1).
+ *
+ * It IS a `DocumentReadError` and its sentence is unchanged, so `docs/porting.md`'s ruling
+ * and every case that pins the wording still hold. What the subclass buys is that
+ * `isUnreadableOptional` can name exactly this refusal: on the reference the same members are
+ * a `NotImplementedError`, which `_UNREADABLE_OPTIONAL` catches through `RuntimeError`, so a
+ * TOLERANT read swallows it there and must swallow it here. Without the class the only way to
+ * recognise it would be `instanceof DocumentReadError`, which would also swallow the
+ * encrypted-member and shared-string refusals that the same call can raise.
+ */
+export declare class ZipMethodUnsupported extends DocumentReadError {
+    constructor(message: string);
+}
+/**
+ * `ZipFile.read`'s `RuntimeError` family: the member is encrypted (`method` undefined), or
+ * (its subclass `NotImplementedError`) compressed by a method zipfile has no decompressor
+ * for (`method` is the number). Not a `DocumentReadError` itself, because the reference's
+ * `_read` is what words it, and the parts `_rel_targets`/`_date_formats` read swallow it
+ * silently instead.
+ */
+export declare class ZipMemberUnreadable extends Error {
+    readonly member: string;
+    readonly method?: number | undefined;
+    constructor(member: string, method?: number | undefined);
+}
+/** `xml.etree.ElementTree.ParseError`. Not a `DocumentReadError`: the reference lets it through. */
+export declare class XmlParseError extends Error {
+    constructor(message: string);
+}
+/** An element the way ET exposes one: expanded `{ns}tag`, attributes, `.text`, children. */
+export declare class XmlElement {
+    readonly tag: string;
+    readonly attrs: Map<string, string>;
+    text: string;
+    readonly children: XmlElement[];
+    constructor(tag: string, attrs: Map<string, string>);
+    get(name: string): string | undefined;
+    /** `Element.find(tag)`: the first DIRECT child with that tag. */
+    find(tag: string): XmlElement | undefined;
+    /** `Element.iter(tag)`: this element and every descendant, document order. */
+    iter(tag?: string): IterableIterator<XmlElement>;
+}
+/**
+ * A declared encoding expat has no decoder for. `LookupError("unknown encoding: x")` on the
+ * reference — NOT an `ET.ParseError`, so `_parse` does not word it and it escapes to the
+ * wire as a raised exception; the same class of thing here, deliberately not `XmlParseError`.
+ */
+export declare class XmlEncodingError extends Error {
+    constructor(encoding: string);
+}
+/**
+ * A strict-enough XML reader: one root, matched tags, declared prefixes, the five
+ * predefined entities and the internal subset's own, comments and PIs dropped, CDATA kept,
+ * line ends normalised, and attribute values whitespace-normalised — what expat gives ET
+ * for an OOXML part.
+ *
+ * A declared entity is expanded the way expat expands it: in a text run its replacement
+ * text is PARSED in place, so `<!ENTITY e "<x>in</x>y">` yields an element, and a
+ * replacement that opens what it does not close is "asynchronous entity"; in an attribute
+ * value it is expanded as text and may not contain `<`; a reference to the entity being
+ * expanded is "recursive entity reference". Measured against `ET.fromstring` (job43 G2).
+ */
+export declare function parseXml(data: Uint8Array): XmlElement;
+export declare function isDateFormat(code: string): boolean;
+/** 0 -> `A`. */
+export declare function columnLetter(index: number): string;
+/**
+ * ECMA-376 gives a worksheet 16,384 columns, the last of them `XFD`. A reference past that
+ * does not name a column of any workbook, so this reader will not build a row wide enough to
+ * reach one. THE FORMAT'S NUMBER, not a limit invented here, which is why it is spelled as
+ * the last column's name rather than as a round figure someone liked.
+ */
+export declare const XLSX_MAX_COLUMNS = 16384;
+/**
+ * Why a cell's own reference could not place it. Fixed strings, never the reference itself:
+ * `r` is whatever the file says, and an omission that echoed it would carry the file's bytes
+ * into the manifest with no bound at all.
+ */
+export declare const UNPLACED_SHAPE = "the column of a cell whose reference is not letters then digits";
+export declare const UNPLACED_RANGE = "the column of a cell past XFD, the last column the format has";
+/**
+ * `B7` -> `[1, '']`. The cell's own reference decides its column; XML order is a fallback.
+ *
+ * A reference is ASCII letters then ASCII digits naming a column the format has, or this
+ * reader cannot place it and says WHY. The match is on the reference AS WRITTEN and never on
+ * its uppercase (`_column`, review round 3): `r="ß1"` was a `TypeError` on the Python side
+ * and column 486 (`SS1`, after `toUpperCase`) here, and a column number that depends on a
+ * Unicode case table is not a fact about the workbook.
+ *
+ * AN ANSWER AND NOT A THROW, which is review round 4 (M2), mirroring `runtime-py` `a1acfa7`.
+ * Round 3 spelled the refusal as a `DocumentReadError` out of a function `sheetRows` does not
+ * catch, so ONE cell the reader could not place refused the entire workbook — measured on a
+ * two-sheet fixture where sheet `Good` is clean and sheet `Bad` holds one cell `r="1"`: no
+ * manifest, no parts, the clean sheet unreachable. `r="1"`, `r="A"` and `r="B7 "` all read
+ * before round 3. The strictness was right and its price was not: the cell keeps its text and
+ * takes its XML position, which is where it sat before round 3 and is the same position on
+ * both runtimes, and the column it did not get is disclosed as an `Omission` rather than
+ * charged to the whole document. The sentence "cell reference {r!r} is not a column-and-row
+ * reference like B7, so this reader cannot place it" NO LONGER EXISTS on either runtime.
+ *
+ * THE CEILING is review round 4 (M5). Round 3 made this function stricter about the SHAPE of
+ * a reference and left the resulting index unbounded: measured on the reference, a 1,755-byte
+ * xlsx whose one cell is `r="ZZZZZ1"` produced a 12,356,630-byte row, 7,041x the file. Row
+ * width is now bounded by the format at `XLSX_MAX_COLUMNS` fields however many bytes the file
+ * spends asking for more.
+ */
+export declare function columnIndex(ref: string | undefined, fallback: number): [number, string];
+export declare function extractXlsx(path: string): Document;
+export declare function extractDocx(path: string): Document;
+/** `html.unescape`. */
+export declare function unescape(s: string): string;
+/** Rendered rows of one HTML fragment. A pure function of the string: no I/O, no host. */
+export declare function htmlRows(markup: string): string[];
+/** `binascii.a2b_qp(data, header=False)`, i.e. `quopri.decodestring`. */
+export declare function decodeQuotedPrintable(data: Uint8Array): Buffer;
+/**
+ * `binascii.a2b_uu(line)`: one uuencoded line to its bytes, in the C module's own steps.
+ *
+ * The first character is the byte count; each following character carries six bits, a line
+ * end or a line that ran out counts as zero ("some spaces got eaten at end-of-line"); a
+ * character outside `' '..'\x60'` is "Illegal char"; and whatever is left after the count
+ * is satisfied must be space, backtick or a line end, or it is "Trailing garbage".
+ */
+export declare function a2bUu(line: Uint8Array): Buffer;
+/**
+ * `email.message._decode_uu`: the lines between `begin <octal mode> ...` and `end`, or
+ * `ValueError` — which `get_payload` answers with the payload UNDECODED.
+ *
+ * `begin` must start the line and its mode must parse in base 8; a blank line before `end`
+ * is "Truncated input"; `end` is recognised stripped of ` \t\r\n\f`; and a line
+ * `a2b_uu` rejects is retried cut to the length its count character implies (the workaround
+ * for broken encoders that the stdlib carries by name). Measured against the reference
+ * (job43 G2) on seventeen payload shapes, including the Truncated and no-`begin` ones.
+ */
+export declare function decodeUu(encoded: Buffer): Buffer;
+export declare function extractMhtml(path: string): Document;
+export declare function extractHtml(path: string): Document;
+export declare function extractText(path: string): Document;
+/** Dispatch on what the file IS. Anything unreadable raises, naming the container. */
+export declare function extract(path: string): Document;
+/** Slice `limit` rows from `part` starting at `offset`, optionally under a byte ceiling. */
+export declare function page(doc: Document, part?: string | number, offset?: number, limit?: number, maxBytes?: number | null): Page;