@shbernal/ts-xlsx 1.0.0

package/dist/vba/codepage.js

@@ -0,0 +1,87 @@
+// The VBA project stores module names and source as MBCS bytes in the project code page
+// (`PROJECTCODEPAGE`, [MS-OVBA] 2.3.4.2). To recover text we decode those bytes with the matching
+// encoding rather than assuming latin1 — a CJK or Cyrillic project would otherwise mojibake.
+import { VbaAuthorError, VbaParseError } from "./errors.js";
+// Windows code-page numbers → the WHATWG encoding label `TextDecoder` understands. Node's built-in
+// ICU covers all of these. Only the code pages a VBA project realistically declares are listed; an
+// unlisted one falls back to windows-1252 (the overwhelmingly common Western-European default) so a
+// rare project still decodes readably instead of throwing.
+const CODEPAGE_LABEL = new Map([
+    [1250, 'windows-1250'],
+    [1251, 'windows-1251'],
+    [1252, 'windows-1252'],
+    [1253, 'windows-1253'],
+    [1254, 'windows-1254'],
+    [1255, 'windows-1255'],
+    [1256, 'windows-1256'],
+    [1257, 'windows-1257'],
+    [1258, 'windows-1258'],
+    [874, 'windows-874'],
+    [932, 'shift_jis'],
+    [936, 'gbk'],
+    [949, 'euc-kr'],
+    [950, 'big5'],
+    [10000, 'macintosh'],
+    [20866, 'koi8-r'],
+    [21866, 'koi8-u'],
+    [28591, 'iso-8859-1'],
+    [28592, 'iso-8859-2'],
+    [65001, 'utf-8'],
+]);
+/**
+ * A `TextDecoder` for the given VBA project code page. Non-fatal (malformed bytes become U+FFFD rather
+ * than throwing) because recovered source is for reading, not re-encoding — a stray byte must not sink
+ * the whole extraction. An unknown code page falls back to windows-1252.
+ */
+export function decoderForCodePage(codePage) {
+    const label = CODEPAGE_LABEL.get(codePage) ?? 'windows-1252';
+    try {
+        return new TextDecoder(label, { fatal: false });
+    }
+    catch {
+        // A runtime whose ICU lacks the label (a minimal build) still gets usable Western-European text
+        // rather than a hard failure on an otherwise-valid project.
+        try {
+            return new TextDecoder('windows-1252', { fatal: false });
+        }
+        catch (cause) {
+            throw new VbaParseError('runtime TextDecoder cannot decode the VBA project code page', {
+                cause,
+            });
+        }
+    }
+}
+/**
+ * The write-side inverse of {@link decoderForCodePage}: an encoder for a project's code page, built by
+ * decoding every byte 0x00..0xFF through the matching decoder and inverting the map. This is exact for
+ * the single-byte code pages a VBA project realistically declares. Under a multi-byte code page (Shift
+ * JIS, GBK, …) the high bytes are lead bytes, not standalone characters, so only ASCII inverts and any
+ * non-ASCII character is rejected — fail-closed rather than emit a corrupt byte. A character the chosen
+ * code page cannot represent throws {@link VbaAuthorError}.
+ */
+export function encoderForCodePage(codePage) {
+    const decoder = decoderForCodePage(codePage);
+    const charToByte = new Map();
+    const one = new Uint8Array(1);
+    for (let b = 0x00; b <= 0xff; b++) {
+        one[0] = b;
+        const decoded = decoder.decode(one);
+        if (decoded.length !== 1)
+            continue; // a lead byte / incomplete sequence under a multi-byte code page
+        const code = decoded.charCodeAt(0);
+        if (code !== 0xfffd && !charToByte.has(code))
+            charToByte.set(code, b);
+    }
+    return (text) => {
+        const out = new Uint8Array(text.length);
+        for (let i = 0; i < text.length; i++) {
+            const code = text.charCodeAt(i);
+            const byte = charToByte.get(code);
+            if (byte === undefined) {
+                throw new VbaAuthorError(`character U+${code.toString(16).toUpperCase().padStart(4, '0')} is not representable in code page ${codePage}`);
+            }
+            out[i] = byte;
+        }
+        return out;
+    };
+}

package/dist/vba/errors.d.ts

@@ -0,0 +1,24 @@
+import { XlsxError } from '../errors.ts';
+/**
+ * Thrown when a VBA project (`vbaProject.bin`) is present but cannot be parsed — a malformed
+ * compound file, a corrupt compressed stream, or a `dir` record that does not conform to [MS-OVBA].
+ * A workbook with no macros never produces this: {@link Workbook.vbaProject} is `undefined` instead.
+ *
+ * The parser treats the blob as hostile input (a spreadsheet library parses untrusted files), so every
+ * malformed structure fails closed with this error rather than crashing, hanging, or over-allocating.
+ */
+export declare class VbaParseError extends XlsxError {
+    readonly name = "VbaParseError";
+    readonly code = "malformed-input";
+}
+/**
+ * Thrown when authoring a VBA project (synthesizing a `vbaProject.bin` from module source) is asked to
+ * produce something that cannot be encoded to a well-formed container — a stream name longer than the
+ * [MS-CFB] 31-character limit, a duplicate stream name, or a project so large it would exceed the
+ * writer's single-header DIFAT bound. This is a caller-side contract violation, distinct from
+ * {@link VbaParseError} (which reports a malformed blob *read* from an untrusted file).
+ */
+export declare class VbaAuthorError extends XlsxError {
+    readonly name = "VbaAuthorError";
+    readonly code = "authoring";
+}

package/dist/vba/errors.js

@@ -0,0 +1,24 @@
+import { XlsxError } from "../errors.js";
+/**
+ * Thrown when a VBA project (`vbaProject.bin`) is present but cannot be parsed — a malformed
+ * compound file, a corrupt compressed stream, or a `dir` record that does not conform to [MS-OVBA].
+ * A workbook with no macros never produces this: {@link Workbook.vbaProject} is `undefined` instead.
+ *
+ * The parser treats the blob as hostile input (a spreadsheet library parses untrusted files), so every
+ * malformed structure fails closed with this error rather than crashing, hanging, or over-allocating.
+ */
+export class VbaParseError extends XlsxError {
+    name = 'VbaParseError';
+    code = 'malformed-input';
+}
+/**
+ * Thrown when authoring a VBA project (synthesizing a `vbaProject.bin` from module source) is asked to
+ * produce something that cannot be encoded to a well-formed container — a stream name longer than the
+ * [MS-CFB] 31-character limit, a duplicate stream name, or a project so large it would exceed the
+ * writer's single-header DIFAT bound. This is a caller-side contract violation, distinct from
+ * {@link VbaParseError} (which reports a malformed blob *read* from an untrusted file).
+ */
+export class VbaAuthorError extends XlsxError {
+    name = 'VbaAuthorError';
+    code = 'authoring';
+}

package/dist/vba/index.d.ts

@@ -0,0 +1,5 @@
+export { type CfbNode, type CfbStorage, type CfbStream, writeCompoundFile, } from './cfb-writer.ts';
+export { VbaAuthorError, VbaParseError } from './errors.ts';
+export { compressContainer, decompressContainer } from './ms-ovba.ts';
+export { parseVbaProject, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, type VbaModule, type VbaModuleKind, type VbaProject, type VbaProjectSignature, type VbaProjectSignatureKind, vbaProjectSignatureKind, } from './project.ts';
+export { addVbaReference, removeVbaModule, type VbaLibraryReference, } from './project-editor.ts';

package/dist/vba/index.js

@@ -0,0 +1,15 @@
+// Native VBA read, plus pure-TS structural edits: decode a macro-enabled workbook's `vbaProject.bin`
+// into readable module source, and remove a module or add a library reference from an existing project
+// by splicing the original bytes (every module's compiled p-code preserved untouched).
+//
+// Authoring or editing module SOURCE is NOT here. Excel runs a module's compiled p-code, not its source,
+// and only a real Excel can produce source-matched p-code — so that lives in the offline
+// `tools/vba-compiler` (VBIDE), whose output is attached via `Workbook.vbaProjectBytes`. The read path
+// is a projection over bytes the model preserves opaquely on round-trip. For the design invariants and
+// the wider VBA feature map see the ADRs: read view (docs/decisions/0016), authoring (0017/0019), and
+// structural edits (0018/0019), plus docs/knowledge/specs/xlsm-macro-preservation.md.
+export { writeCompoundFile, } from "./cfb-writer.js";
+export { VbaAuthorError, VbaParseError } from "./errors.js";
+export { compressContainer, decompressContainer } from "./ms-ovba.js";
+export { parseVbaProject, VBA_PROJECT_CONTENT_TYPE, VBA_PROJECT_PART_PATH, VBA_PROJECT_REL_TYPE, vbaProjectSignatureKind, } from "./project.js";
+export { addVbaReference, removeVbaModule, } from "./project-editor.js";

package/dist/vba/ms-ovba.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Decompress an MS-OVBA CompressedContainer beginning at `start` in `buf`.
+ * @param maxOutput hard ceiling on decompressed bytes; exceeding it throws (bomb guard).
+ */
+export declare function decompressContainer(buf: Uint8Array, start?: number, maxOutput?: number): Uint8Array;
+/**
+ * Compress `data` into an MS-OVBA CompressedContainer — the inverse of {@link decompressContainer}.
+ * Every 4096-decompressed-byte window is emitted as a compressed chunk of literal and copy tokens, or
+ * stored verbatim when compression would not shrink it (so the encoded chunk never exceeds the 12-bit
+ * size field). The result re-expands to `data` byte-for-byte.
+ */
+export declare function compressContainer(data: Uint8Array): Uint8Array;

package/dist/vba/ms-ovba.js

@@ -0,0 +1,176 @@
+// MS-OVBA §2.4.1 — compression and decompression of a "CompressedContainer".
+//
+// VBA module source and the project `dir` stream are stored in Office's own run-length compression,
+// NOT deflate. A container is a 0x01 signature byte followed by one or more chunks; each chunk
+// decompresses to at most 4096 bytes and is either a raw 4096-byte copy or a stream of literal/copy
+// tokens. Reference: [MS-OVBA] 2.4.1.3.6 (decompressing a CompressedContainer), 2.4.1.3.19.3 (the
+// CopyToken bit-packing), and 2.4.1.3.7 (compressing a chunk).
+//
+// The decompressor is a hostile-input parser: the container comes from an untrusted file, so every
+// length and back-reference is bounds-checked and the total output is capped. A malformed container
+// fails closed with a VbaParseError rather than over-allocating, looping, or reading out of bounds. The
+// compressor is the authoring inverse — it is fed our own bytes, and its output re-expands to the input
+// byte-for-byte (the round-trip is the correctness contract).
+import { VbaParseError } from "./errors.js";
+// A decompressed chunk covers at most 4096 bytes; both directions honour this window ([MS-OVBA]
+// 2.4.1.3.6). The chunk header's bits 12-14 carry a fixed 0b011 signature, bit 15 the compressed flag.
+const MAX_CHUNK_DECOMPRESSED = 4096;
+const CHUNK_SIGNATURE = 0b011 << 12;
+const CHUNK_COMPRESSED_FLAG = 0x8000;
+// A single VBA project is well under a megabyte; 64 MiB is far above any legitimate container yet
+// bounds a decompression bomb (a small container that expands without limit) to a survivable size.
+const DEFAULT_MAX_OUTPUT = 64 * 1024 * 1024;
+/**
+ * Decompress an MS-OVBA CompressedContainer beginning at `start` in `buf`.
+ * @param maxOutput hard ceiling on decompressed bytes; exceeding it throws (bomb guard).
+ */
+export function decompressContainer(buf, start = 0, maxOutput = DEFAULT_MAX_OUTPUT) {
+    if (start >= buf.length) {
+        throw new VbaParseError(`compressed container starts past end of stream (${start} >= ${buf.length})`);
+    }
+    if (buf[start] !== 0x01) {
+        throw new VbaParseError(`compressed container must begin with a 0x01 signature byte, found 0x${(buf[start] ?? 0).toString(16)}`);
+    }
+    const out = [];
+    let pos = start + 1;
+    while (pos + 2 <= buf.length) {
+        const header = readU16(buf, pos);
+        pos += 2;
+        // Bits 0-11: (chunk data size - 1). Bit 15: compressed flag. Bits 12-14: the fixed 0b011 signature.
+        const chunkDataSize = (header & 0x0fff) + 1;
+        const compressed = (header & 0x8000) !== 0;
+        if (((header >> 12) & 0x7) !== 0b011) {
+            throw new VbaParseError(`chunk header has a bad 0b011 signature (0x${header.toString(16)})`);
+        }
+        const chunkEnd = pos + chunkDataSize;
+        if (chunkEnd > buf.length) {
+            throw new VbaParseError(`chunk data (${chunkDataSize} bytes) runs past end of stream`);
+        }
+        if (!compressed) {
+            // A raw chunk carries its bytes verbatim (Excel emits one only when compression would expand).
+            for (let i = pos; i < chunkEnd; i++)
+                out.push(buf[i]);
+            guardOutput(out.length, maxOutput);
+            pos = chunkEnd;
+            continue;
+        }
+        const chunkStart = out.length; // decompressed offset where this chunk began
+        while (pos < chunkEnd) {
+            const flagByte = buf[pos++];
+            for (let bit = 0; bit < 8 && pos < chunkEnd; bit++) {
+                const isCopy = (flagByte >> bit) & 1;
+                if (!isCopy) {
+                    out.push(buf[pos++]);
+                    guardOutput(out.length, maxOutput);
+                    continue;
+                }
+                if (pos + 2 > chunkEnd) {
+                    throw new VbaParseError('copy token truncated at chunk end');
+                }
+                const token = readU16(buf, pos);
+                pos += 2;
+                const { lengthMask, bitCount } = copyTokenHelp(out.length - chunkStart);
+                const length = (token & lengthMask) + 3;
+                const copyOffset = (token >> (16 - bitCount)) + 1;
+                const src = out.length - copyOffset;
+                if (src < chunkStart) {
+                    // A back-reference may only reach data emitted since this chunk began ([MS-OVBA] 2.4.1.3.19).
+                    throw new VbaParseError('copy token references before the start of its chunk');
+                }
+                // Byte-by-byte so overlapping runs (run-length expansion) grow correctly.
+                for (let i = 0; i < length; i++)
+                    out.push(out[src + i]);
+                guardOutput(out.length, maxOutput);
+            }
+        }
+        pos = chunkEnd;
+    }
+    return Uint8Array.from(out);
+}
+/**
+ * Compress `data` into an MS-OVBA CompressedContainer — the inverse of {@link decompressContainer}.
+ * Every 4096-decompressed-byte window is emitted as a compressed chunk of literal and copy tokens, or
+ * stored verbatim when compression would not shrink it (so the encoded chunk never exceeds the 12-bit
+ * size field). The result re-expands to `data` byte-for-byte.
+ */
+export function compressContainer(data) {
+    const out = [0x01]; // container signature; an empty input yields just this byte
+    for (let start = 0; start < data.length; start += MAX_CHUNK_DECOMPRESSED) {
+        const chunk = data.subarray(start, Math.min(start + MAX_CHUNK_DECOMPRESSED, data.length));
+        const tokens = compressChunk(chunk);
+        // Prefer the token stream only when it is strictly smaller; otherwise store the chunk raw. Both
+        // encode their exact length in the header, so the decompressor reconstructs the window either way.
+        const compressed = tokens.length < chunk.length;
+        const body = compressed ? tokens : chunk;
+        const header = (compressed ? CHUNK_COMPRESSED_FLAG : 0) | CHUNK_SIGNATURE | ((body.length - 1) & 0x0fff);
+        out.push(header & 0xff, (header >> 8) & 0xff);
+        for (const b of body)
+            out.push(b);
+    }
+    return Uint8Array.from(out);
+}
+// Encode one decompressed chunk (≤ 4096 bytes) as a sequence of MS-OVBA token groups: a flag byte whose
+// bits mark the next up-to-8 tokens as literal (0) or copy (1). A copy token replaces a run of 3+ bytes
+// that recurs earlier in the *same* chunk; matches may overlap the current position (run-length growth),
+// which the decompressor reproduces byte-by-byte. The bit split between the offset and length fields
+// widens as the chunk fills, exactly as the decoder computes it, so both agree on every token's shape.
+function compressChunk(chunk) {
+    const tokens = [];
+    let pos = 0;
+    while (pos < chunk.length) {
+        const flagIndex = tokens.length;
+        tokens.push(0);
+        let flags = 0;
+        for (let bit = 0; bit < 8 && pos < chunk.length; bit++) {
+            const { lengthMask, bitCount } = copyTokenHelp(pos);
+            const maxLength = lengthMask + 3;
+            const windowStart = Math.max(0, pos - (1 << bitCount));
+            let bestLength = 0;
+            let bestOffset = 0;
+            // Scan nearest-first so equal-length matches keep the smallest offset (a marginally cheaper token).
+            for (let cand = pos - 1; cand >= windowStart; cand--) {
+                let len = 0;
+                while (len < maxLength &&
+                    pos + len < chunk.length &&
+                    chunk[cand + len] === chunk[pos + len]) {
+                    len++;
+                }
+                if (len > bestLength) {
+                    bestLength = len;
+                    bestOffset = pos - cand;
+                    if (bestLength === maxLength)
+                        break; // cannot improve
+                }
+            }
+            if (bestLength >= 3) {
+                const token = ((bestOffset - 1) << (16 - bitCount)) | (bestLength - 3);
+                tokens.push(token & 0xff, (token >> 8) & 0xff);
+                flags |= 1 << bit;
+                pos += bestLength;
+            }
+            else {
+                tokens.push(chunk[pos]);
+                pos++;
+            }
+        }
+        tokens[flagIndex] = flags;
+    }
+    return tokens;
+}
+function guardOutput(size, maxOutput) {
+    if (size > maxOutput) {
+        throw new VbaParseError(`decompressed output exceeds the ${maxOutput}-byte ceiling (possible bomb)`);
+    }
+}
+/**
+ * Bit split for a CopyToken given how many bytes have been emitted since the current chunk began
+ * ([MS-OVBA] 2.4.1.3.19.3): the offset field grows and the length field shrinks as the chunk fills.
+ */
+function copyTokenHelp(decompressedSoFar) {
+    const bitCount = Math.max(Math.ceil(Math.log2(Math.max(decompressedSoFar, 1))), 4);
+    const lengthMask = 0xffff >> bitCount;
+    return { lengthMask, bitCount };
+}
+function readU16(buf, at) {
+    return buf[at] | (buf[at + 1] << 8);
+}

package/dist/vba/project-editor.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Remove a standard module from an existing `vbaProject.bin`, returning new bytes that carry every
+ * remaining module, reference, and host-info record unchanged. It drops the module's `VBA/<name>`
+ * stream, its MODULE record block in `dir` (decrementing `MODULES_COUNT`), and its `Module=`/`Class=` +
+ * workspace lines in `PROJECT`/`PROJECTwm`.
+ *
+ * Only `procedural` and `class` modules can be removed this way — removing a `document` module (e.g.
+ * `ThisWorkbook`) or a `designer` module (a UserForm) would leave the host referencing code that no
+ * longer exists, since their names are tied to a worksheet/workbook `codeName` or a designer storage
+ * this project-level primitive has no visibility into. Editing such a module's code-behind is a job for
+ * the offline `tools/vba-compiler` (in-place mode), which drives the real host.
+ *
+ * @throws {VbaParseError} if `bin` is not a parseable VBA project (validated before any edit).
+ * @throws {VbaAuthorError} if `name` is not in the project, or names a `document`/`designer` module.
+ */
+export declare function removeVbaModule(bin: Uint8Array, name: string): Uint8Array;
+/**
+ * A registered (COM Automation type-library) reference to add to an existing VBA project — the shape of
+ * a real "add a reference to Microsoft Scripting Runtime" call. Project references (to another VBA
+ * project) and control references (to an ActiveX control library) are out of scope — see
+ * {@link addVbaReference}.
+ */
+export interface VbaLibraryReference {
+    /**
+     * The reference's namespace name in the VBA editor — what a qualified reference like
+     * `Scripting.Dictionary` resolves through. Must be a valid VBA identifier, at most 31 characters, as
+     * real type libraries use (e.g. `Scripting`, `Office`, `stdole`).
+     */
+    readonly name: string;
+    /**
+     * The friendly name shown in the References dialog, e.g. `Microsoft Scripting Runtime`. Real projects
+     * usually keep this distinct from {@link name}; defaults to {@link name} if omitted.
+     */
+    readonly displayName?: string;
+    /** The type library's GUID, e.g. `{420B2830-E718-11CF-893D-00A0C9054228}` (braces optional). */
+    readonly guid: string;
+    /** The type library's major version — an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMajorVersion`). */
+    readonly majorVersion: number;
+    /** The type library's minor version — an integer in `[0, 0xFFFF]` ([MS-OVBA] `LibidMinorVersion`). */
+    readonly minorVersion: number;
+    /**
+     * The type library's LCID — an integer in `[0, 0xFFFFFFFF]`. Defaults to `0` (locale-neutral), the
+     * overwhelming common case (every reference in a real project observed while building this had `0`).
+     */
+    readonly lcid?: number;
+    /** Absolute Windows path to the type library file, e.g. `C:\Windows\System32\scrrun.dll`. */
+    readonly path: string;
+}
+/**
+ * Add a registered (COM type-library) reference to an existing `vbaProject.bin`, returning new bytes
+ * that carry every existing module, reference, and host-info record unchanged. It grows the project's
+ * `dir` stream by one `REFERENCENAME` + `REFERENCEREGISTERED` record pair, positioned immediately before
+ * `MODULES_COUNT` (references have no count field of their own — `MODULES_COUNT` simply marks where the
+ * reference array ends). It needs no change to `PROJECT`/`PROJECTwm`: a real Excel-authored `PROJECT`
+ * stream carries no `Reference=` line at all — references live only in `dir` (confirmed against a genuine
+ * Excel-authored project).
+ *
+ * @throws {VbaParseError} if `bin` is not a parseable VBA project (validated before any edit).
+ * @throws {VbaAuthorError} if any field of `ref` is invalid (see {@link VbaLibraryReference}), or the
+ *   assembled reference text has a character the project's code page cannot represent.
+ */
+export declare function addVbaReference(bin: Uint8Array, ref: VbaLibraryReference): Uint8Array;