ooxml.js 1.0.0 → 1.2.0

package/README.md

@@ -1,5 +1,7 @@
 # ooxml.js
 
+[![GitHub](https://img.shields.io/badge/GitHub-181717?logo=github&logoColor=white)](https://github.com/ExaDev/ooxml.js) [![npm](https://img.shields.io/npm/v/ooxml.js?logo=npm)](https://www.npmjs.com/package/ooxml.js) [![CI](https://img.shields.io/github/actions/workflow/status/ExaDev/ooxml.js/ci.yml?branch=main)](https://github.com/ExaDev/ooxml.js/actions)
+
 > Type-safe, lossless round-trip conversion between OOXML packages (`.docx`, `.pptx`, `.xlsx`) and a faithful JSON model, built on [Zod 4](https://zod.dev) codecs.
 
 An OOXML file is a ZIP archive of parts (an OPC "package"): `[Content_Types].xml`, relationships (`*.rels`), XML content parts, and binary parts (images, embedded objects). `ooxml.js` decodes the **whole package** into a faithful JSON model and encodes it back — part for part — so `encode(decode(file))` reproduces the original content.
@@ -140,13 +142,14 @@ const out = encodeCompactPackage(compact); // CompactPackage -> OOXML bytes dire
 
 ```sh
 pnpm build          # tsdown -> dist/ (ESM + CJS + .d.ts, via tsdown.config.ts)
+pnpm lint           # eslint . --max-warnings 0
 pnpm typecheck      # tsc --noEmit
 pnpm test           # vitest run
 pnpm test:watch     # vitest
 pnpm test:smoke     # builds dist/, then runs test/smoke.test.mjs to verify the built ESM and CJS artifacts both load and behave identically
 ```
 
-There is no separate lint script or ESLint config; `pnpm typecheck` and `vitest` are the enforced gates. `pnpm prepublishOnly` runs `typecheck`, `tsdown`, `publint`, and `@arethetypeswrong/cli` (`attw --pack`) — the full publish-readiness check — before a release.
+`pnpm prepublishOnly` runs `lint`, `typecheck`, `tsdown`, `publint`, and `@arethetypeswrong/cli` (`attw --pack`) — the full publish-readiness check — before a release.
 
 `test/smoke.test.mjs` loads the actual built `dist/index.js` (ESM) and `dist/index.cjs` (CJS) artifacts and checks they load and behave identically — a check none of `vitest`'s normal run, `tsc`, `publint`, or `attw` can do, since those either run against source or statically analyse package metadata without executing the compiled output. `vitest.config.ts` defines it as its own `smoke` project (vitest's `test.projects`), separate from the `unit` project (`src/**/*.test.ts`); `pnpm test`/`test:watch` pass `--project unit` and `pnpm test:smoke` passes `--project smoke` after `tsdown` rebuilds `dist/`, so neither run touches the other project's files.
 
@@ -170,15 +173,15 @@ The package is layered from a lossless core outward to lossy convenience views:
 - **`XmlNode` uses a recursive structural guard, not `z.lazy`.** `z.lazy` collapses to `unknown` for the element-children case in the Zod version this project pins, so `XmlElementSchema` validates `children` via `z.custom<XmlNode>(isXmlNode)`, a hand-written recursive type guard in `model/node.ts`. Any change to `XmlNode`'s shape must update `isXmlNode` in step. `src/compact.ts`'s `CompactXmlNode` reuses the same pattern (`isCompactXmlNode` + `z.custom`) for the same reason.
 - **Lossless core vs. lossy views is a hard boundary.** `decodePackage`/`encodePackage` (and the underlying codecs) must stay byte/part faithful — every part round-trips unchanged. `src/typed/*` readers are explicitly one-way and are allowed to drop information (documented per-reader, e.g. `readDocx`'s bold/italic toggle presence check ignores `w:val`, and `readXlsx` drops cell styles, formats and charts). Don't blur this line by adding write-back support to a typed reader; a full round-trip always goes through the generic `Package`.
 - **XML entities stay raw in the lossless layer.** `parseXml` runs with `processEntities: false` so encoded entities (e.g. `&amp;`) are preserved verbatim for round-trip fidelity; typed readers decode the five standard entities (`decodeEntities` in `typed/util.ts`) only in their own lossy projection, never in the core model.
+- **No type assertions.** `eslint.config.ts` runs `@typescript-eslint/consistent-type-assertions` with `assertionStyle: "never"`, banning `as` and angle-bracket casts outright, with `linterOptions.noInlineConfig: true` so there is no `eslint-disable` escape hatch either — narrow with a guard or parse with Zod. An exception would have to be scoped structurally, as a `files`-matched override block in `eslint.config.ts`, not an inline comment.
 
 ## Gotchas and quirks
 
-- **No git remote is configured yet.** `git remote -v` is empty; this repository has not been pushed anywhere. Confirm the intended origin before assuming a `git push` target.
 - **`test:smoke` depends on a fresh build.** It runs `tsdown && vitest run --project smoke`, so it always rebuilds `dist/` first — don't run it expecting to test a stale build.
 - **`--project` matters for `test/smoke.test.mjs`.** `vitest.config.ts` defines `unit` and `smoke` as separate projects; `pnpm test`/`test:watch`/`test:smoke` always pass the right `--project` flag. A bare `vitest`/`vitest run` with no `--project` filter runs both projects, and `smoke` fails loudly (`Cannot find module '../dist/index.js'`) if `dist/` hasn't been built yet — a clear failure pointing at the cause, not a silent false pass, but still worth knowing if you invoke `vitest` directly instead of through the npm scripts.
 - **Binary-vs-XML part classification is a byte sniff, not an extension check.** `package-io/read.ts`'s `looksLikeXml` looks for a leading `<` after skipping a UTF-8 BOM and whitespace; this is deliberate (no standard OOXML binary part starts with `<`) but means any future binary format starting with `<` would misclassify.
-- **`fflate`'s bundled types are ahead of what it actually allocates.** `zip.ts` casts `fflate`'s `Uint8Array<ArrayBufferLike>` results to `Uint8Array<ArrayBuffer>` with a comment explaining why the narrowing is safe (fflate only ever allocates a real `ArrayBuffer`) — don't remove the cast without preserving that guarantee elsewhere.
-- **No CI workflow exists yet.** There is no `.github/workflows/` directory; `pnpm build`, `pnpm typecheck`, and `pnpm test` are run locally/manually, not gated by GitHub Actions.
+- **`Array.isArray` narrows `unknown` to `any[]`, not `unknown[]`.** `lib.es5.d.ts` types its parameter as `any`, so TypeScript can't do better even after the check succeeds — indexing straight into the result (e.g. `value[0]`) silently reintroduces `any` and trips `@typescript-eslint/no-unsafe-assignment`. `compact.ts` and `xml/parse.ts` each define a local `isUnknownArray` guard (`value is unknown[]`) for exactly this reason; reach for it instead of `Array.isArray` wherever the narrowed element is going to be read.
+- **TypeScript is pinned to the latest 6.x, not 7.** TypeScript 7 restructured its JS-facing API surface heavily enough that both `typescript-eslint` (peer range `<6.1.0`) and `cosmiconfig`'s TypeScript loader (used by `semantic-release` to read `release.config.ts`, via `typescript.findConfigFile`, which TS 7 no longer exports) break under it. Upgrading past 6.x has to wait for that ecosystem tooling to add TS 7 support.
 
 ## Fidelity
 
@@ -186,9 +189,15 @@ Conversion is **part-content-faithful**: every XML part re-serialises to equival
 
 It is **not** guaranteed to be byte-for-byte identical at the ZIP-container level — re-zipping changes archive entry layout (entry order, compression, metadata), and that is not achievable deterministically across the tools that produce OOXML files.
 
+## Release and publishing
+
+`.github/workflows/ci.yml` runs commitlint, lint, typecheck, the unit suite, and the smoke test on every push and pull request. On a push to `main` where those all pass, `release.config.ts` drives [semantic-release](https://semantic-release.gitbook.io/semantic-release): commit history since the last tag decides the version bump, `CHANGELOG.md` and `package.json` are committed back to `main`, a GitHub Release is cut, and the package publishes to [npmjs.org](https://www.npmjs.com/package/ooxml.js) — via npm's OIDC trusted publishing, so no `NPM_TOKEN` exists anywhere in the pipeline.
+
+Whether that release actually published a new version is detected by diffing `package.json`'s version before and after the release step, not by trusting a third-party action's own detection. Two further jobs gate on that: one republishes the same build under the scoped `@exadev/ooxml.js` alias to GitHub Packages (which has no OIDC exchange of its own, so it authenticates with `GITHUB_TOKEN` instead), and one packs the release into its own directory, generates an SPDX SBOM (`pnpm sbom`), and signs both an SBOM and a build-provenance attestation against that exact tarball — verifiable independently of the registry, and still present if the package is later unpublished.
+
 ## Contributing
 
-Commits follow Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`), evidenced by the existing git history; there is no `CONTRIBUTING.md` or enforced commit hook yet. There is a single `main` branch and no open pull request workflow established so far.
+Commits follow Conventional Commits (`feat:`, `fix:`, `test:`, `chore:`, …), enforced by commitlint (`commitlint.config.ts`) via a husky `commit-msg` hook and a CI `commitlint` job — semantic-release's version bump depends on these being well-formed, not just style. A husky `pre-commit` hook runs `lint-staged` (`eslint --fix` on staged `*.ts` files) and `pre-push` runs the test suite. There is a single `main` branch and no open pull request workflow established so far.
 
 ## License
 

package/dist/index.cjs

@@ -32,15 +32,15 @@ function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isAttribute(value) {
-	return isRecord$1(value) && typeof value["name"] === "string" && typeof value["value"] === "string";
+	return isRecord$1(value) && typeof value.name === "string" && typeof value.value === "string";
 }
 function isXmlNode(value) {
 	if (!isRecord$1(value)) return false;
-	const t = value["type"];
-	if (t === "text" || t === "cdata" || t === "comment") return typeof value["value"] === "string";
-	if (t === "declaration") return Array.isArray(value["attributes"]) && value["attributes"].every(isAttribute);
-	if (t === "pi") return typeof value["target"] === "string" && typeof value["content"] === "string";
-	if (t === "element") return typeof value["tag"] === "string" && Array.isArray(value["attributes"]) && value["attributes"].every(isAttribute) && Array.isArray(value["children"]) && value["children"].every(isXmlNode);
+	const t = value.type;
+	if (t === "text" || t === "cdata" || t === "comment") return typeof value.value === "string";
+	if (t === "declaration") return Array.isArray(value.attributes) && value.attributes.every(isAttribute);
+	if (t === "pi") return typeof value.target === "string" && typeof value.content === "string";
+	if (t === "element") return typeof value.tag === "string" && Array.isArray(value.attributes) && value.attributes.every(isAttribute) && Array.isArray(value.children) && value.children.every(isXmlNode);
 	return false;
 }
 const XmlElementSchema = zod.z.object({
@@ -133,12 +133,15 @@ function parseXml(xml) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isUnknownArray$1(value) {
+	return Array.isArray(value);
+}
 function asString(value) {
 	if (typeof value !== "string") throw new Error(`expected string while parsing XML, got ${typeof value}`);
 	return value;
 }
 function parseNodes(raw) {
-	if (!Array.isArray(raw)) throw new Error("fast-xml-parser output was not an ordered array");
+	if (!isUnknownArray$1(raw)) throw new Error("fast-xml-parser output was not an ordered array");
 	return raw.map(parseNode);
 }
 function parseNode(raw) {
@@ -156,11 +159,11 @@ function parseNode(raw) {
 	};
 	if (tagKey === "__comment") return {
 		type: "comment",
-		value: scalarText(raw["__comment"])
+		value: scalarText(raw.__comment)
 	};
 	if (tagKey === "__cdata") return {
 		type: "cdata",
-		value: scalarText(raw["__cdata"])
+		value: scalarText(raw.__cdata)
 	};
 	if (tagKey === "?xml") return {
 		type: "declaration",
@@ -192,7 +195,7 @@ function parseAttributes(raw) {
 	return attrs;
 }
 function scalarText(raw) {
-	if (!Array.isArray(raw) || raw.length === 0) throw new Error("expected a scalar-text wrapper array");
+	if (!isUnknownArray$1(raw) || raw.length === 0) throw new Error("expected a scalar-text wrapper array");
 	const first = raw[0];
 	if (!isRecord(first)) throw new Error("scalar-text wrapper was not an object");
 	return asString(first["#text"]);
@@ -308,11 +311,14 @@ function encodePackage(pkg) {
 }
 //#endregion
 //#region src/compact.ts
+function isUnknownArray(value) {
+	return Array.isArray(value);
+}
 function isCompactAttrPairs(value) {
-	return Array.isArray(value) && value.every((v) => typeof v === "number");
+	return isUnknownArray(value) && value.every((v) => typeof v === "number");
 }
 function isCompactXmlNode(value) {
-	if (!Array.isArray(value)) return false;
+	if (!isUnknownArray(value)) return false;
 	const code = value[0];
 	if (code === 1 || code === 2 || code === 3) return value.length === 2 && typeof value[1] === "number";
 	if (code === 4) return value.length === 2 && isCompactAttrPairs(value[1]);
@@ -473,7 +479,7 @@ function attr(element, name) {
 	for (const a of element.attributes) if (a.name === name) return a.value;
 }
 function rootElement(part) {
-	if (part === void 0 || part.kind !== "xml") return;
+	if (part?.kind !== "xml") return;
 	for (const node of part.nodes) if (node.type === "element") return node;
 }
 function decodeEntities(value) {
@@ -647,7 +653,7 @@ function readHeaderFooterText(pkg, prefix) {
 	for (const path of Object.keys(pkg.parts)) {
 		if (!path.startsWith(prefix) || !path.endsWith(".xml")) continue;
 		const part = pkg.parts[path];
-		if (part === void 0 || part.kind !== "xml") continue;
+		if (part?.kind !== "xml") continue;
 		out.push(elementsWithTag(part.nodes, "w:t").map(textContent).join(""));
 	}
 	return out;
@@ -708,7 +714,7 @@ function readNotes(pkg, slidePath) {
 	}
 	if (notesPath === void 0) return "";
 	const part = pkg.parts[notesPath];
-	if (part === void 0 || part.kind !== "xml") return "";
+	if (part?.kind !== "xml") return "";
 	return elementsWithTag(part.nodes, "a:t").map(textContent).join("");
 }
 function readPptx(pkg) {

package/dist/index.js

@@ -31,15 +31,15 @@ function isRecord$1(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 function isAttribute(value) {
-	return isRecord$1(value) && typeof value["name"] === "string" && typeof value["value"] === "string";
+	return isRecord$1(value) && typeof value.name === "string" && typeof value.value === "string";
 }
 function isXmlNode(value) {
 	if (!isRecord$1(value)) return false;
-	const t = value["type"];
-	if (t === "text" || t === "cdata" || t === "comment") return typeof value["value"] === "string";
-	if (t === "declaration") return Array.isArray(value["attributes"]) && value["attributes"].every(isAttribute);
-	if (t === "pi") return typeof value["target"] === "string" && typeof value["content"] === "string";
-	if (t === "element") return typeof value["tag"] === "string" && Array.isArray(value["attributes"]) && value["attributes"].every(isAttribute) && Array.isArray(value["children"]) && value["children"].every(isXmlNode);
+	const t = value.type;
+	if (t === "text" || t === "cdata" || t === "comment") return typeof value.value === "string";
+	if (t === "declaration") return Array.isArray(value.attributes) && value.attributes.every(isAttribute);
+	if (t === "pi") return typeof value.target === "string" && typeof value.content === "string";
+	if (t === "element") return typeof value.tag === "string" && Array.isArray(value.attributes) && value.attributes.every(isAttribute) && Array.isArray(value.children) && value.children.every(isXmlNode);
 	return false;
 }
 const XmlElementSchema = z.object({
@@ -132,12 +132,15 @@ function parseXml(xml) {
 function isRecord(value) {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
+function isUnknownArray$1(value) {
+	return Array.isArray(value);
+}
 function asString(value) {
 	if (typeof value !== "string") throw new Error(`expected string while parsing XML, got ${typeof value}`);
 	return value;
 }
 function parseNodes(raw) {
-	if (!Array.isArray(raw)) throw new Error("fast-xml-parser output was not an ordered array");
+	if (!isUnknownArray$1(raw)) throw new Error("fast-xml-parser output was not an ordered array");
 	return raw.map(parseNode);
 }
 function parseNode(raw) {
@@ -155,11 +158,11 @@ function parseNode(raw) {
 	};
 	if (tagKey === "__comment") return {
 		type: "comment",
-		value: scalarText(raw["__comment"])
+		value: scalarText(raw.__comment)
 	};
 	if (tagKey === "__cdata") return {
 		type: "cdata",
-		value: scalarText(raw["__cdata"])
+		value: scalarText(raw.__cdata)
 	};
 	if (tagKey === "?xml") return {
 		type: "declaration",
@@ -191,7 +194,7 @@ function parseAttributes(raw) {
 	return attrs;
 }
 function scalarText(raw) {
-	if (!Array.isArray(raw) || raw.length === 0) throw new Error("expected a scalar-text wrapper array");
+	if (!isUnknownArray$1(raw) || raw.length === 0) throw new Error("expected a scalar-text wrapper array");
 	const first = raw[0];
 	if (!isRecord(first)) throw new Error("scalar-text wrapper was not an object");
 	return asString(first["#text"]);
@@ -307,11 +310,14 @@ function encodePackage(pkg) {
 }
 //#endregion
 //#region src/compact.ts
+function isUnknownArray(value) {
+	return Array.isArray(value);
+}
 function isCompactAttrPairs(value) {
-	return Array.isArray(value) && value.every((v) => typeof v === "number");
+	return isUnknownArray(value) && value.every((v) => typeof v === "number");
 }
 function isCompactXmlNode(value) {
-	if (!Array.isArray(value)) return false;
+	if (!isUnknownArray(value)) return false;
 	const code = value[0];
 	if (code === 1 || code === 2 || code === 3) return value.length === 2 && typeof value[1] === "number";
 	if (code === 4) return value.length === 2 && isCompactAttrPairs(value[1]);
@@ -472,7 +478,7 @@ function attr(element, name) {
 	for (const a of element.attributes) if (a.name === name) return a.value;
 }
 function rootElement(part) {
-	if (part === void 0 || part.kind !== "xml") return;
+	if (part?.kind !== "xml") return;
 	for (const node of part.nodes) if (node.type === "element") return node;
 }
 function decodeEntities(value) {
@@ -646,7 +652,7 @@ function readHeaderFooterText(pkg, prefix) {
 	for (const path of Object.keys(pkg.parts)) {
 		if (!path.startsWith(prefix) || !path.endsWith(".xml")) continue;
 		const part = pkg.parts[path];
-		if (part === void 0 || part.kind !== "xml") continue;
+		if (part?.kind !== "xml") continue;
 		out.push(elementsWithTag(part.nodes, "w:t").map(textContent).join(""));
 	}
 	return out;
@@ -707,7 +713,7 @@ function readNotes(pkg, slidePath) {
 	}
 	if (notesPath === void 0) return "";
 	const part = pkg.parts[notesPath];
-	if (part === void 0 || part.kind !== "xml") return "";
+	if (part?.kind !== "xml") return "";
 	return elementsWithTag(part.nodes, "a:t").map(textContent).join("");
 }
 function readPptx(pkg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ooxml.js",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Type-safe, lossless round-trip conversion between OOXML packages (docx, pptx, xlsx) and JSON, built on Zod 4 codecs.",
   "type": "module",
   "repository": {
@@ -38,7 +38,8 @@
   },
   "scripts": {
     "build": "tsdown",
-    "prepublishOnly": "pnpm run typecheck && tsdown && publint && attw --pack",
+    "prepublishOnly": "pnpm run lint && pnpm run typecheck && tsdown && publint && attw --pack",
+    "lint": "eslint . --max-warnings 0",
     "typecheck": "tsc --noEmit",
     "test": "vitest run --project unit",
     "test:watch": "vitest --project unit",
@@ -67,14 +68,19 @@
     "@arethetypeswrong/cli": "^0.18.5",
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
+    "@eslint/js": "^10.0.1",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.1",
     "@types/node": "^26.1.1",
+    "eslint": "^10.8.0",
+    "globals": "^17.8.0",
     "husky": "^9.1.7",
+    "lint-staged": "^17.2.0",
     "publint": "^0.3.21",
     "semantic-release": "^25.0.8",
     "tsdown": "^0.22.13",
-    "typescript": "^7.0.2",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0",
     "vitest": "^4.1.10"
   }
 }