bantamkit-mcp 0.29.1 → 0.29.2

package/dist/docread.d.ts

@@ -34,6 +34,7 @@
  * (`utf8Scan`).
  */
 import { BantamError } from './errors.js';
+import { cmpCodepoint, pyRepr, pyStrip } from './pysem.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}";
@@ -52,19 +53,15 @@ 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";
+export declare const OMIT_DUPLICATE_CELL = "duplicate-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;
+export { cmpCodepoint, pyRepr, pyStrip };
 /** `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 {
@@ -190,6 +187,35 @@ export declare class BadZipFile extends Error {
     constructor(message: string);
 }
 export declare function crc32(buf: Uint8Array): number;
+/**
+ * How much ONE MEMBER of a zip this reader will decompress and parse. The ceiling on the
+ * PARSE, which is a different door from `XLSX_MAX_TEXT_BYTES`: that one bounds the text a
+ * workbook renders, and it never stands in front of this, because `readMember` decompresses
+ * the member whole and `parsePart` builds a tree from it before the first row is rendered.
+ *
+ * MEASURED 2026-09-06 on this machine, through `docread.extract` on THIS runtime at the
+ * shipped constants, on a sheet of N `<row><c t="inlineStr"><is><t>x</t></is></c></row>`
+ * deflated by `deflateRawSync`, peak RSS from `process.resourceUsage().maxRSS`:
+ * 400,000 rows are 58,378 bytes on disk, declare 19,600,112, and took RSS from 102.2 MB to
+ * 1,039.3 MB in 1,019 ms with NO omission; 1,000,000 rows are 143,939 bytes, declare
+ * 49,000,112, and took it from 158.6 MB to 2,290.8 MB in 2,667 ms. Linear and unbounded —
+ * the memory is the `XmlElement` tree, not the text, so a budget over the rendering could
+ * not see it. The reference measured the same shape at 342.2 MB and 838.8 MB through
+ * `tracemalloc`; the numbers are not comparable (one counts a Python allocator, the other a
+ * whole process) and the SHAPE is what both of them state.
+ *
+ * 16 MiB, the number `TEXT_MAX_BYTES` states, because "how much of a file this reader reads"
+ * is one number — but under its OWN NAME, because it bounds a member of a container and not a
+ * file on a disk, and a bar that varies one must not be varying the other. The reference
+ * measured the corpus behind the figure: 25 OOXML/ODF packages under the goal's roots, the
+ * largest single XML member among them 4,283,286 bytes, 3.9x under this.
+ *
+ * A REFUSAL and not a truncation, which is the one place this module departs from
+ * "disclose, never truncate": half an XML document is not a smaller XML document, and a tree
+ * built from a severed member would carry text that is not what the file says. So the reader
+ * stops and names the member, the number the file declares and its own ceiling.
+ */
+export declare const ZIP_MEMBER_MAX_BYTES: number;
 /** `zipfile.ZipFile` read-only: the central directory, and `read(name)` with a CRC check. */
 export declare class ZipReader {
     private readonly data;
@@ -209,6 +235,8 @@ export declare class ZipReader {
         isDir: boolean;
     }[];
     has(name: string): boolean;
+    /** `getinfo(name).file_size`: what the central directory DECLARES, before any inflate. */
+    declaredSize(name: string): number;
     /** `ZipFile.read(name)`; a missing member is a `KeyError` — here `RangeError`, see `readMember`. */
     read(name: string): Buffer;
 }
@@ -293,6 +321,32 @@ export declare const XLSX_MAX_COLUMNS = 16384;
  */
 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";
+export declare const DUPLICATE_CELL = "the text of a cell a later cell in the same row and column replaced";
+/**
+ * How much text ONE WORKBOOK may materialise, all sheets together. `XLSX_MAX_COLUMNS` bounds a
+ * ROW and nothing bounded the document, which is a ceiling with a hole in it: the width is
+ * bought a row at a time. MEASURED 2026-09-06 on both runtimes: 20,000 rows each holding one
+ * `XFD1` cell deflate to 53,967 bytes and materialise 327,680,000 bytes in ~9 s — 6,072x, out
+ * of a file small enough to mail.
+ *
+ * 16 MiB, the same figure `TEXT_MAX_BYTES` carries and for the same kind of reason, but under
+ * its OWN NAME because the two bound different things: bytes read off a disk there, bytes
+ * rendered out of a container here, and a bar that varies one must not be varying the other.
+ * MEASURED 2026-09-06 over the goal's roots: 15 `.xlsx`, the largest 8,664,227 bytes on disk,
+ * and the largest RENDERING among them 754,520 bytes — 22x under this budget, so no real
+ * workbook on this machine meets it.
+ *
+ * It bounds the RENDERING and nothing else. The sentence that stood here said it bounded the
+ * rendering "because the file is already bounded", and that was FALSE for the whole life of
+ * this constant: `readMember` decompressed a member whole and `parsePart` built a tree from
+ * it, both before the first row was rendered and both outside this budget, so 58,378 bytes on
+ * disk took RSS to 1,039.3 MB with no omission and this ceiling never saw it (review round 5,
+ * H1). What bounds the file is `ZIP_MEMBER_MAX_BYTES`, one door earlier; this bounds what
+ * comes out of it. The shortfall is disclosed as `OMIT_SIZE_CAP` counting the rows no sheet
+ * rendered: a row is what a caller addresses, and a byte count of text that was never built
+ * would be a number this reader cannot honestly produce.
+ */
+export declare const XLSX_MAX_TEXT_BYTES: number;
 /**
  * `B7` -> `[1, '']`. The cell's own reference decides its column; XML order is a fallback.
  *
@@ -320,8 +374,22 @@ export declare const UNPLACED_RANGE = "the column of a cell past XFD, the last c
  * 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;
+/**
+ * Every declared sheet, under ONE `XLSX_MAX_TEXT_BYTES` budget for the whole workbook.
+ *
+ * The budget is the document's, so it is made here and not in `sheetRows`, and the shortfall
+ * is disclosed at the document's grain for the same reason — it is not a fact about the sheet
+ * the budget happened to run out on. The cap is stated BEFORE the media tally, because the
+ * media a reader met is a count of what it met underneath the cap.
+ *
+ * `opened` is the reader `sniff` already had to build to decide this file is an OOXML package
+ * (entries (a)/(j)): before it was handed down, one `extract` read the whole archive off disk
+ * TWICE. It is a parameter and never a field, so its lifetime is this call — a reader kept
+ * across calls would answer from bytes no longer on disk, which is exactly what the document
+ * cache one layer up is keyed on (realpath, size, mtime_ns) to avoid.
+ */
+export declare function extractXlsx(path: string, opened?: ZipReader | null): Document;
+export declare function extractDocx(path: string, opened?: ZipReader | null): 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. */
@@ -349,6 +417,12 @@ export declare function a2bUu(line: Uint8Array): Buffer;
  */
 export declare function decodeUu(encoded: Buffer): Buffer;
 export declare function extractMhtml(path: string): Document;
+/**
+ * Markup to rows, up to `TEXT_MAX_BYTES` of it, saying how much it did not read.
+ *
+ * BOUNDED, entry (k): this did `readFileSync(path)`, so a 1 GB `.html` was materialised whole
+ * where a 1 GB `.txt` had stopped at the cap and counted the rest since J10.
+ */
 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. */