doc-codec 0.0.0 → 1.0.1

package/dist/text/piece-table.js

@@ -0,0 +1,65 @@
+import { DocFormatError } from "../errors.js";
+import { readInt16LE, readUint16LE, readUint32LE, readUint8, slice } from "../bytes.js";
+import { parsePlc } from "../plc.js";
+//#region src/text/piece-table.ts
+/** A Clx's leading Prc marker byte, [MS-DOC] 2.9.20: "This value MUST be 0x01." */
+const CLXT_PRC = 1;
+/** A Clx's Pcdt marker byte, [MS-DOC] 2.9.19: "This value MUST be 0x02." */
+const CLXT_PCDT = 2;
+/** Pcd is 8 bytes: a 2-byte bit field, a 4-byte FcCompressed, and a 2-byte Prm. */
+const PCD_SIZE = 8;
+/** FcCompressed's low 30 bits hold the offset; bit 30 is fCompressed and bit 31 a reserved bit the spec says MUST be zero and MUST be ignored. */
+const FC_MASK = 1073741823;
+const FC_COMPRESSED_BIT = 1073741824;
+/** PrcData.cbGrpprl is a signed integer that "MUST be less than or equal to 0x3FA2". */
+const MAX_CB_GRPPRL = 16290;
+function parseClx(clx) {
+	let cursor = 0;
+	for (;;) {
+		const clxt = readUint8(clx, cursor);
+		if (clxt === CLXT_PCDT) break;
+		if (clxt !== CLXT_PRC) throw new DocFormatError(`Clx element at offset ${cursor} begins with clxt 0x${clxt.toString(16).padStart(2, "0")}, which is neither a Prc (0x01) nor the Pcdt (0x02)`);
+		const cbGrpprl = readInt16LE(clx, cursor + 1);
+		if (cbGrpprl < 0 || cbGrpprl > MAX_CB_GRPPRL) throw new DocFormatError(`Clx Prc at offset ${cursor} declares cbGrpprl ${cbGrpprl}, outside the 0..0x3FA2 range [MS-DOC] permits`);
+		cursor += 3 + cbGrpprl;
+		if (cursor > clx.length) throw new DocFormatError(`Clx Prc at offset ${cursor - 3 - cbGrpprl} declares a ${cbGrpprl}-byte GrpPrl that runs past the end of the ${clx.length}-byte Clx`);
+	}
+	const lcb = readUint32LE(clx, cursor + 1);
+	const plcPcd = slice(clx, cursor + 5, lcb, "Clx Pcdt PlcPcd");
+	const plc = parsePlc(plcPcd, PCD_SIZE, "PlcPcd");
+	const pieces = [];
+	for (let index = 0; index < plc.count; index += 1) {
+		const element = plc.element(index);
+		const bits = readUint16LE(element, 0);
+		const fcCompressed = readUint32LE(element, 2);
+		const cpStart = plc.keys[index];
+		const cpEnd = plc.keys[index + 1];
+		if (cpStart === void 0 || cpEnd === void 0) throw new DocFormatError(`PlcPcd element ${index} has no bracketing character positions, so its text range is undefined`);
+		pieces.push({
+			cpStart,
+			cpEnd,
+			fc: fcCompressed & FC_MASK,
+			compressed: (fcCompressed & FC_COMPRESSED_BIT) !== 0,
+			noParaLast: (bits & 1) !== 0,
+			prm: readUint16LE(element, 6)
+		});
+	}
+	const lastCp = plc.keys[plc.keys.length - 1];
+	if (lastCp === void 0) throw new DocFormatError("PlcPcd carries no character positions at all");
+	return {
+		pieces,
+		cpKeys: plc.keys,
+		lastCp
+	};
+}
+function characterOffset(piece, cp) {
+	if (!Number.isInteger(cp) || cp < piece.cpStart || cp >= piece.cpEnd) throw new DocFormatError(`character position ${cp} is outside the piece covering [${piece.cpStart}, ${piece.cpEnd})`);
+	const delta = cp - piece.cpStart;
+	return piece.compressed ? Math.floor(piece.fc / 2) + delta : piece.fc + 2 * delta;
+}
+/** The number of bytes one character occupies in this piece: one for a compressed (8-bit) piece, two for an uncompressed (16-bit) one. */
+function characterSize(piece) {
+	return piece.compressed ? 1 : 2;
+}
+//#endregion
+export { characterOffset, characterSize, parseClx };

package/dist/text/special.cjs

@@ -0,0 +1,48 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/text/special.ts
+/** "An entity in a document that is used to denote the end of a paragraph and has a Unicode character code of 13." */
+const PARAGRAPH_MARK = 13;
+/** "A character with a hexadecimal value of 0x07 that is used to indicate the end of a cell in a table." With sprmPFTtp applied it is instead an end-of-row mark. */
+const CELL_MARK = 7;
+/** The last character of every section but the last, per [MS-DOC] 2.4.4's worked example. */
+const SECTION_MARK = 12;
+/** "This Sprm MUST NOT be applied to any character other than a line break character (Unicode 0x000B)." */
+const LINE_BREAK = 11;
+/** "U+0013 - A field begin character. See Plcfld." */
+const FIELD_BEGIN = 19;
+/** "U+0014 - A field separator character." Everything between the begin and the separator is the field's instruction, not its displayed result. */
+const FIELD_SEPARATOR = 20;
+/** "U+0015 - A field end character." */
+const FIELD_END = 21;
+/** "U+0001 - A picture location that is used in conjunction with sprmCPicLocation." */
+const INLINE_PICTURE = 1;
+/** "U+0002 - An auto-numbered footnote reference. See plcffndRef." */
+const FOOTNOTE_REFERENCE = 2;
+/** "U+0005 - An annotation reference character. See PlcfandRef." */
+const ANNOTATION_REFERENCE = 5;
+/** "U+0008 - A drawn object. See plcfSpa." */
+const DRAWN_OBJECT = 8;
+/** "U+0028 - A symbol. See sprmCSymbol." Only special when sprmCFSpec is applied; an ordinary '(' otherwise, so it is never treated as structural here. */
+const SYMBOL_ANCHOR = 40;
+/** Ends a paragraph. [MS-DOC] 2.4.2: "The character at the end character position of a paragraph MUST be a paragraph mark, an end-of-section character, a cell mark, or a TTP mark." */
+function endsParagraph(code) {
+	return code === 13 || code === 7 || code === 12;
+}
+function isAnchorOnly(code) {
+	return code === 1 || code === 2 || code === 5 || code === 8;
+}
+//#endregion
+exports.ANNOTATION_REFERENCE = ANNOTATION_REFERENCE;
+exports.CELL_MARK = CELL_MARK;
+exports.DRAWN_OBJECT = DRAWN_OBJECT;
+exports.FIELD_BEGIN = FIELD_BEGIN;
+exports.FIELD_END = FIELD_END;
+exports.FIELD_SEPARATOR = FIELD_SEPARATOR;
+exports.FOOTNOTE_REFERENCE = FOOTNOTE_REFERENCE;
+exports.INLINE_PICTURE = INLINE_PICTURE;
+exports.LINE_BREAK = LINE_BREAK;
+exports.PARAGRAPH_MARK = PARAGRAPH_MARK;
+exports.SECTION_MARK = SECTION_MARK;
+exports.SYMBOL_ANCHOR = SYMBOL_ANCHOR;
+exports.endsParagraph = endsParagraph;
+exports.isAnchorOnly = isAnchorOnly;

package/dist/text/special.d.cts

@@ -0,0 +1,30 @@
+//#region src/text/special.d.ts
+/** "An entity in a document that is used to denote the end of a paragraph and has a Unicode character code of 13." */
+declare const PARAGRAPH_MARK = 13;
+/** "A character with a hexadecimal value of 0x07 that is used to indicate the end of a cell in a table." With sprmPFTtp applied it is instead an end-of-row mark. */
+declare const CELL_MARK = 7;
+/** The last character of every section but the last, per [MS-DOC] 2.4.4's worked example. */
+declare const SECTION_MARK = 12;
+/** "This Sprm MUST NOT be applied to any character other than a line break character (Unicode 0x000B)." */
+declare const LINE_BREAK = 11;
+/** "U+0013 - A field begin character. See Plcfld." */
+declare const FIELD_BEGIN = 19;
+/** "U+0014 - A field separator character." Everything between the begin and the separator is the field's instruction, not its displayed result. */
+declare const FIELD_SEPARATOR = 20;
+/** "U+0015 - A field end character." */
+declare const FIELD_END = 21;
+/** "U+0001 - A picture location that is used in conjunction with sprmCPicLocation." */
+declare const INLINE_PICTURE = 1;
+/** "U+0002 - An auto-numbered footnote reference. See plcffndRef." */
+declare const FOOTNOTE_REFERENCE = 2;
+/** "U+0005 - An annotation reference character. See PlcfandRef." */
+declare const ANNOTATION_REFERENCE = 5;
+/** "U+0008 - A drawn object. See plcfSpa." */
+declare const DRAWN_OBJECT = 8;
+/** "U+0028 - A symbol. See sprmCSymbol." Only special when sprmCFSpec is applied; an ordinary '(' otherwise, so it is never treated as structural here. */
+declare const SYMBOL_ANCHOR = 40;
+/** Ends a paragraph. [MS-DOC] 2.4.2: "The character at the end character position of a paragraph MUST be a paragraph mark, an end-of-section character, a cell mark, or a TTP mark." */
+declare function endsParagraph(code: number): boolean;
+declare function isAnchorOnly(code: number): boolean;
+//#endregion
+export { ANNOTATION_REFERENCE, CELL_MARK, DRAWN_OBJECT, FIELD_BEGIN, FIELD_END, FIELD_SEPARATOR, FOOTNOTE_REFERENCE, INLINE_PICTURE, LINE_BREAK, PARAGRAPH_MARK, SECTION_MARK, SYMBOL_ANCHOR, endsParagraph, isAnchorOnly };

package/dist/text/special.d.ts

@@ -0,0 +1,30 @@
+//#region src/text/special.d.ts
+/** "An entity in a document that is used to denote the end of a paragraph and has a Unicode character code of 13." */
+declare const PARAGRAPH_MARK = 13;
+/** "A character with a hexadecimal value of 0x07 that is used to indicate the end of a cell in a table." With sprmPFTtp applied it is instead an end-of-row mark. */
+declare const CELL_MARK = 7;
+/** The last character of every section but the last, per [MS-DOC] 2.4.4's worked example. */
+declare const SECTION_MARK = 12;
+/** "This Sprm MUST NOT be applied to any character other than a line break character (Unicode 0x000B)." */
+declare const LINE_BREAK = 11;
+/** "U+0013 - A field begin character. See Plcfld." */
+declare const FIELD_BEGIN = 19;
+/** "U+0014 - A field separator character." Everything between the begin and the separator is the field's instruction, not its displayed result. */
+declare const FIELD_SEPARATOR = 20;
+/** "U+0015 - A field end character." */
+declare const FIELD_END = 21;
+/** "U+0001 - A picture location that is used in conjunction with sprmCPicLocation." */
+declare const INLINE_PICTURE = 1;
+/** "U+0002 - An auto-numbered footnote reference. See plcffndRef." */
+declare const FOOTNOTE_REFERENCE = 2;
+/** "U+0005 - An annotation reference character. See PlcfandRef." */
+declare const ANNOTATION_REFERENCE = 5;
+/** "U+0008 - A drawn object. See plcfSpa." */
+declare const DRAWN_OBJECT = 8;
+/** "U+0028 - A symbol. See sprmCSymbol." Only special when sprmCFSpec is applied; an ordinary '(' otherwise, so it is never treated as structural here. */
+declare const SYMBOL_ANCHOR = 40;
+/** Ends a paragraph. [MS-DOC] 2.4.2: "The character at the end character position of a paragraph MUST be a paragraph mark, an end-of-section character, a cell mark, or a TTP mark." */
+declare function endsParagraph(code: number): boolean;
+declare function isAnchorOnly(code: number): boolean;
+//#endregion
+export { ANNOTATION_REFERENCE, CELL_MARK, DRAWN_OBJECT, FIELD_BEGIN, FIELD_END, FIELD_SEPARATOR, FOOTNOTE_REFERENCE, INLINE_PICTURE, LINE_BREAK, PARAGRAPH_MARK, SECTION_MARK, SYMBOL_ANCHOR, endsParagraph, isAnchorOnly };

package/dist/text/special.js

@@ -0,0 +1,34 @@
+//#region src/text/special.ts
+/** "An entity in a document that is used to denote the end of a paragraph and has a Unicode character code of 13." */
+const PARAGRAPH_MARK = 13;
+/** "A character with a hexadecimal value of 0x07 that is used to indicate the end of a cell in a table." With sprmPFTtp applied it is instead an end-of-row mark. */
+const CELL_MARK = 7;
+/** The last character of every section but the last, per [MS-DOC] 2.4.4's worked example. */
+const SECTION_MARK = 12;
+/** "This Sprm MUST NOT be applied to any character other than a line break character (Unicode 0x000B)." */
+const LINE_BREAK = 11;
+/** "U+0013 - A field begin character. See Plcfld." */
+const FIELD_BEGIN = 19;
+/** "U+0014 - A field separator character." Everything between the begin and the separator is the field's instruction, not its displayed result. */
+const FIELD_SEPARATOR = 20;
+/** "U+0015 - A field end character." */
+const FIELD_END = 21;
+/** "U+0001 - A picture location that is used in conjunction with sprmCPicLocation." */
+const INLINE_PICTURE = 1;
+/** "U+0002 - An auto-numbered footnote reference. See plcffndRef." */
+const FOOTNOTE_REFERENCE = 2;
+/** "U+0005 - An annotation reference character. See PlcfandRef." */
+const ANNOTATION_REFERENCE = 5;
+/** "U+0008 - A drawn object. See plcfSpa." */
+const DRAWN_OBJECT = 8;
+/** "U+0028 - A symbol. See sprmCSymbol." Only special when sprmCFSpec is applied; an ordinary '(' otherwise, so it is never treated as structural here. */
+const SYMBOL_ANCHOR = 40;
+/** Ends a paragraph. [MS-DOC] 2.4.2: "The character at the end character position of a paragraph MUST be a paragraph mark, an end-of-section character, a cell mark, or a TTP mark." */
+function endsParagraph(code) {
+	return code === 13 || code === 7 || code === 12;
+}
+function isAnchorOnly(code) {
+	return code === 1 || code === 2 || code === 5 || code === 8;
+}
+//#endregion
+export { ANNOTATION_REFERENCE, CELL_MARK, DRAWN_OBJECT, FIELD_BEGIN, FIELD_END, FIELD_SEPARATOR, FOOTNOTE_REFERENCE, INLINE_PICTURE, LINE_BREAK, PARAGRAPH_MARK, SECTION_MARK, SYMBOL_ANCHOR, endsParagraph, isAnchorOnly };

package/package.json

@@ -1,5 +1,96 @@
 {
   "name": "doc-codec",
-  "version": "0.0.0",
-  "private": false
+  "version": "1.0.1",
+  "description": "A hand-written reader for the Word Binary File Format ([MS-DOC], .doc) against the shared document-schema.js content pivot: FIB parsing, piece-table text reconstruction, and CHPX/PAPX formatting exceptions.",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ExaDev/documents.js.git",
+    "directory": "packages/doc-codec"
+  },
+  "homepage": "https://github.com/ExaDev/documents.js/tree/main/packages/doc-codec",
+  "bugs": {
+    "url": "https://github.com/ExaDev/documents.js/issues"
+  },
+  "exports": {
+    ".": {
+      "types": {
+        "import": "./dist/index.d.ts",
+        "require": "./dist/index.d.cts"
+      },
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./*": {
+      "types": {
+        "import": "./dist/*.d.ts",
+        "require": "./dist/*.d.cts"
+      },
+      "import": "./dist/*.js",
+      "require": "./dist/*.cjs"
+    }
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "turbo run _build",
+    "_build": "tsdown",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && tsdown && publint && attw --pack",
+    "lint": "turbo run _lint",
+    "_lint": "eslint . --fix --cache --max-warnings 0",
+    "lint:check": "eslint . --max-warnings 0",
+    "typecheck": "turbo run _typecheck _typecheck:attw",
+    "_typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.node.json",
+    "_typecheck:attw": "attw --pack",
+    "test": "turbo run _test",
+    "_test": "vitest run --project unit",
+    "test:watch": "vitest --project unit",
+    "test:workers": "turbo run _test:workers",
+    "_test:workers": "vitest run --config vitest.workers.config.ts",
+    "test:smoke": "turbo run _test:smoke",
+    "_test:smoke": "vitest run --project smoke",
+    "prepare": "husky"
+  },
+  "keywords": [
+    "doc",
+    "word",
+    "ms-doc",
+    "binary",
+    "codec",
+    "ms-cfb"
+  ],
+  "license": "MIT",
+  "packageManager": "pnpm@11.6.0",
+  "dependencies": {
+    "archive-codec": "^1.3.0",
+    "document-schema.js": "^5.4.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.5",
+    "@cloudflare/vitest-pool-workers": "^0.20.1",
+    "@types/node": "^26.1.2",
+    "eslint": "^10.8.0",
+    "husky": "^9.1.7",
+    "publint": "^0.3.21",
+    "tsdown": "^0.22.13",
+    "turbo": "^2.10.8",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10"
+  },
+  "lint-staged": {
+    "*.ts": "eslint --fix"
+  }
 }