@cj-tech-master/excelts 9.4.2 → 9.5.0

package/dist/cjs/modules/excel/utils/ooxml-validator/context.js

@@ -0,0 +1,196 @@
+"use strict";
+/**
+ * Shared validation context.
+ *
+ * Checkers share XML parsing work through this context. Relationships,
+ * content types, and parsed XML DOMs are parsed at most once and cached.
+ * Every checker consumes from the same cache so they all see identical
+ * parse results (this matters for "rels malformed" propagation — the
+ * malformed entry is reported once, and every downstream checker simply
+ * sees the empty parse result).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ValidationContext = void 0;
+exports.domRoot = domRoot;
+const xml_utils_1 = require("./xml-utils");
+const textDecoder = new TextDecoder();
+// -----------------------------------------------------------------------------
+// Context
+// -----------------------------------------------------------------------------
+class ValidationContext {
+    constructor(entries, reporter) {
+        this.textCache = new Map();
+        this.domCache = new Map();
+        this.relsCache = new Map();
+        this.entries = entries;
+        this.reporter = reporter;
+    }
+    /** `true` if `path` points to a file (not a directory) in the package. */
+    has(path) {
+        const entry = this.entries.get(path);
+        return !!entry && entry.type !== "directory";
+    }
+    /** Iterate every file (skip directories). */
+    *files() {
+        for (const entry of this.entries) {
+            if (entry[1].type !== "directory") {
+                yield entry;
+            }
+        }
+    }
+    /** Decode a part as UTF-8 text. Cached. */
+    readText(path) {
+        const cached = this.textCache.get(path);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const entry = this.entries.get(path);
+        if (!entry || entry.type === "directory") {
+            return undefined;
+        }
+        const text = textDecoder.decode(entry.data);
+        this.textCache.set(path, text);
+        return text;
+    }
+    /**
+     * Parse a part as XML DOM. Cached. Returns `undefined` if the part is
+     * missing or malformed. Callers that need to distinguish those cases
+     * should check `has(path)` first.
+     */
+    readDom(path, onMalformed) {
+        if (this.domCache.has(path)) {
+            return this.domCache.get(path);
+        }
+        const text = this.readText(path);
+        if (text === undefined) {
+            this.domCache.set(path, undefined);
+            return undefined;
+        }
+        const dom = (0, xml_utils_1.tryParseXml)(text, err => {
+            onMalformed?.(err);
+        });
+        this.domCache.set(path, dom);
+        return dom;
+    }
+    /**
+     * Read and cache the content-types table. On first call, parse
+     * `[Content_Types].xml`; subsequent calls return the cache.
+     * Reports malformed-XML problems via the reporter but never throws.
+     */
+    readContentTypes() {
+        if (this.contentTypes) {
+            return this.contentTypes;
+        }
+        const path = "[Content_Types].xml";
+        const dom = this.readDom(path, err => {
+            this.reporter.error("content-types-malformed", `Content types XML parse error: ${err.message}`, path);
+        });
+        const data = {
+            defaults: new Map(),
+            overrides: new Map(),
+            parseOk: false,
+            duplicateOverrides: []
+        };
+        if (!dom) {
+            this.contentTypes = data;
+            return data;
+        }
+        const root = dom.root;
+        // Accept namespaced <Types> just in case.
+        const looksLikeTypes = root.name === "Types" || root.name.endsWith(":Types");
+        if (!looksLikeTypes) {
+            this.reporter.error("content-types-malformed", `Content types root element is <${root.name}>, expected <Types>`, path);
+            this.contentTypes = data;
+            return data;
+        }
+        for (const el of (0, xml_utils_1.findChildrenLocal)(root, "Default")) {
+            const extRaw = (0, xml_utils_1.attrByLocalName)(el, "Extension");
+            const ct = (0, xml_utils_1.attrByLocalName)(el, "ContentType");
+            if (extRaw && ct) {
+                data.defaults.set(extRaw.toLowerCase(), ct);
+            }
+        }
+        for (const el of (0, xml_utils_1.findChildrenLocal)(root, "Override")) {
+            const partName = (0, xml_utils_1.attrByLocalName)(el, "PartName");
+            const ct = (0, xml_utils_1.attrByLocalName)(el, "ContentType");
+            if (!partName || !ct) {
+                continue;
+            }
+            const key = partName.startsWith("/") ? partName.slice(1) : partName;
+            if (data.overrides.has(key)) {
+                data.duplicateOverrides.push(partName);
+            }
+            else {
+                data.overrides.set(key, ct);
+            }
+        }
+        data.parseOk = true;
+        this.contentTypes = data;
+        return data;
+    }
+    /**
+     * Read and cache a relationships file. Every .rels in the package is
+     * parsed lazily on first request. Malformed files are reported once
+     * and return an empty relationships array.
+     */
+    readRels(relsPath) {
+        const cached = this.relsCache.get(relsPath);
+        if (cached) {
+            return cached;
+        }
+        const data = {
+            rels: [],
+            byId: new Map(),
+            parseOk: false,
+            malformedEntries: []
+        };
+        if (!this.has(relsPath)) {
+            this.relsCache.set(relsPath, data);
+            return data;
+        }
+        const dom = this.readDom(relsPath, err => {
+            this.reporter.error("rels-malformed", `Relationships XML parse error: ${err.message}`, relsPath);
+        });
+        if (!dom) {
+            this.relsCache.set(relsPath, data);
+            return data;
+        }
+        const root = dom.root;
+        const looksLikeRelationships = root.name === "Relationships" || root.name.endsWith(":Relationships");
+        if (!looksLikeRelationships) {
+            this.reporter.error("rels-malformed", `Relationships root element is <${root.name}>, expected <Relationships>`, relsPath);
+            this.relsCache.set(relsPath, data);
+            return data;
+        }
+        for (const el of (0, xml_utils_1.findChildrenLocal)(root, "Relationship")) {
+            const id = (0, xml_utils_1.attrByLocalName)(el, "Id");
+            const type = (0, xml_utils_1.attrByLocalName)(el, "Type");
+            const target = (0, xml_utils_1.attrByLocalName)(el, "Target");
+            const targetMode = (0, xml_utils_1.attrByLocalName)(el, "TargetMode");
+            if (!id || !type || target === undefined) {
+                data.malformedEntries.push({
+                    missingId: !id,
+                    missingType: !type,
+                    missingTarget: target === undefined,
+                    id,
+                    type
+                });
+                continue;
+            }
+            const rel = { id, type, target, targetMode };
+            data.rels.push(rel);
+            // Note: duplicates are checked elsewhere; we keep the FIRST here.
+            if (!data.byId.has(id)) {
+                data.byId.set(id, rel);
+            }
+        }
+        data.parseOk = true;
+        this.relsCache.set(relsPath, data);
+        return data;
+    }
+}
+exports.ValidationContext = ValidationContext;
+/** Get the root element of a DOM; returns undefined for missing DOM. */
+function domRoot(dom) {
+    return dom?.root;
+}

package/dist/cjs/modules/excel/utils/ooxml-validator/index.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Public entry point for the OOXML validator.
+ *
+ * Validates an xlsx package buffer against the OPC spec and Excel's
+ * known opening invariants. See `types.ts` for the full catalog of
+ * problem kinds.
+ *
+ * ```ts
+ * const report = await validateXlsxBuffer(await wb.xlsx.writeBuffer());
+ * if (!report.ok) {
+ *   console.error(report.problems);
+ * }
+ * ```
+ *
+ * The implementation is composed of independent checkers under
+ * `check-*.ts` — each can be unit-tested in isolation. The entry point
+ * orchestrates them with a shared `ValidationContext` that caches XML
+ * parsing across checks.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateXlsxBuffer = validateXlsxBuffer;
+const extract_1 = require("../../../archive/unzip/extract.js");
+const check_chart_1 = require("./check-chart");
+const check_chart_sidecar_1 = require("./check-chart-sidecar");
+const check_chartsheet_1 = require("./check-chartsheet");
+const check_content_types_1 = require("./check-content-types");
+const check_drawing_1 = require("./check-drawing");
+const check_pivot_1 = require("./check-pivot");
+const check_relationships_1 = require("./check-relationships");
+const check_structure_1 = require("./check-structure");
+const check_styles_1 = require("./check-styles");
+const check_table_1 = require("./check-table");
+const check_workbook_1 = require("./check-workbook");
+const check_worksheet_1 = require("./check-worksheet");
+const context_1 = require("./context");
+const path_utils_1 = require("./path-utils");
+const reporter_1 = require("./reporter");
+/**
+ * Validate an xlsx package. Returns a report with every detected
+ * problem; `ok === true` when no error-severity problems were found.
+ *
+ * This function never throws — malformed input is surfaced as a
+ * `xml-malformed` or similar problem kind. The only exception is if
+ * `extractAll` fails to unzip the buffer (not a valid ZIP at all), in
+ * which case the underlying archive error propagates.
+ */
+async function validateXlsxBuffer(xlsxBuffer, options = {}) {
+    const { checkXmlWellFormed: optCheckXmlWellFormed = true, checkRelationshipTargets = true, checkContentTypesOverrides = true, checkWorksheetControlWiring = true, checkChartStructure = true, checkStylesIntegrity = true, maxProblems, includeWarnings = false } = options;
+    const entries = await (0, extract_1.extractAll)(xlsxBuffer);
+    const reporter = new reporter_1.Reporter({ maxProblems, includeWarnings });
+    const ctx = new context_1.ValidationContext(entries, reporter);
+    // Order matters: later checks rely on earlier ones NOT firing false
+    // positives when structural invariants are broken. Structure first.
+    (0, check_structure_1.checkStructure)(ctx);
+    if (optCheckXmlWellFormed) {
+        (0, check_structure_1.checkXmlWellFormed)(ctx);
+    }
+    if (checkContentTypesOverrides) {
+        (0, check_content_types_1.checkContentTypes)(ctx);
+    }
+    (0, check_relationships_1.checkRootRelationships)(ctx);
+    if (checkRelationshipTargets) {
+        (0, check_relationships_1.checkRelationships)(ctx);
+    }
+    (0, check_workbook_1.checkWorkbook)(ctx);
+    if (checkWorksheetControlWiring) {
+        (0, check_worksheet_1.checkWorksheets)(ctx);
+    }
+    if (checkChartStructure) {
+        (0, check_chart_1.checkChart)(ctx);
+        (0, check_drawing_1.checkDrawing)(ctx);
+        (0, check_chartsheet_1.checkChartsheet)(ctx);
+        (0, check_pivot_1.checkPivot)(ctx);
+        (0, check_table_1.checkTables)(ctx);
+        (0, check_chart_sidecar_1.checkChartSidecars)(ctx);
+    }
+    if (checkStylesIntegrity) {
+        (0, check_styles_1.checkStyles)(ctx);
+    }
+    const stats = computeStats(entries);
+    return {
+        ok: !reporter.hasErrors,
+        problems: reporter.problems,
+        stats
+    };
+}
+function computeStats(entries) {
+    let entryCount = 0;
+    let xmlLikeCount = 0;
+    let relsCount = 0;
+    for (const [, entry] of entries) {
+        if (entry.type === "directory") {
+            continue;
+        }
+        entryCount++;
+        if ((0, path_utils_1.isXmlLike)(entry.path)) {
+            xmlLikeCount++;
+        }
+        if (entry.path.endsWith(".rels")) {
+            relsCount++;
+        }
+    }
+    return { entryCount, xmlLikeCount, relsCount };
+}

package/dist/cjs/modules/excel/utils/ooxml-validator/path-utils.js

@@ -0,0 +1,168 @@
+"use strict";
+/**
+ * Path helpers shared across all validator checkers.
+ *
+ * All paths are handled as **forward-slash POSIX strings** because that is
+ * how OPC part names are defined. We never touch the host's path separator.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.stripLeadingSlash = stripLeadingSlash;
+exports.isXmlLike = isXmlLike;
+exports.getRelsSourceDir = getRelsSourceDir;
+exports.posixBasename = posixBasename;
+exports.getExtension = getExtension;
+exports.resolveRelTarget = resolveRelTarget;
+exports.isSafeResolvedPath = isSafeResolvedPath;
+exports.relsPathForPart = relsPathForPart;
+exports.sourcePartForRels = sourcePartForRels;
+exports.isLegalPartName = isLegalPartName;
+/**
+ * Strip a single leading `/` if present. OPC `PartName` values start with
+ * `/` by spec, but zip entries do not.
+ */
+function stripLeadingSlash(p) {
+    return p.startsWith("/") ? p.slice(1) : p;
+}
+/** `.xml`, `.rels`, or `.vml` — the payloads we parse as XML. */
+function isXmlLike(pathName) {
+    return pathName.endsWith(".xml") || pathName.endsWith(".rels") || pathName.endsWith(".vml");
+}
+/**
+ * Directory in which a relationships part's **source** part lives. OPC
+ * resolves rel Targets relative to the source part's directory, NOT the
+ * `.rels` file's directory. Examples:
+ *
+ * | .rels path                              | source dir          |
+ * |-----------------------------------------|---------------------|
+ * | `_rels/.rels`                           | ``                  |
+ * | `xl/_rels/workbook.xml.rels`            | `xl`                |
+ * | `xl/worksheets/_rels/sheet1.xml.rels`   | `xl/worksheets`     |
+ */
+function getRelsSourceDir(relsPath) {
+    if (relsPath === "_rels/.rels") {
+        return "";
+    }
+    const marker = "/_rels/";
+    const idx = relsPath.indexOf(marker);
+    if (idx === -1) {
+        return relsPath.includes("/") ? relsPath.slice(0, relsPath.lastIndexOf("/")) : "";
+    }
+    return relsPath.slice(0, idx);
+}
+/**
+ * Basename without directory, e.g. `xl/foo/bar.xml` → `bar.xml`.
+ */
+function posixBasename(p) {
+    const idx = p.lastIndexOf("/");
+    return idx === -1 ? p : p.slice(idx + 1);
+}
+/** Extension without the leading dot, lowercase. `""` when missing. */
+function getExtension(p) {
+    const base = posixBasename(p);
+    const idx = base.lastIndexOf(".");
+    return idx === -1 ? "" : base.slice(idx + 1).toLowerCase();
+}
+/**
+ * Resolve a relationship Target against a .rels path. Handles absolute
+ * targets starting with `/` (relative to package root), `../` traversal,
+ * `./`, and plain relative segments. Never returns a leading slash.
+ *
+ * We do NOT use `node:path` so this module is usable in browsers.
+ */
+function resolveRelTarget(relsPath, target) {
+    // Absolute-in-package targets start with "/".
+    if (target.startsWith("/")) {
+        return normalizeSegments(target.split("/"));
+    }
+    const baseDir = getRelsSourceDir(relsPath);
+    const segments = [];
+    if (baseDir) {
+        segments.push(...baseDir.split("/"));
+    }
+    segments.push(...target.split("/"));
+    return normalizeSegments(segments);
+}
+function normalizeSegments(segments) {
+    const out = [];
+    let escaped = false;
+    for (const seg of segments) {
+        if (seg === "" || seg === ".") {
+            continue;
+        }
+        if (seg === "..") {
+            if (out.length === 0) {
+                // Record traversal past the package root — caller's job to flag it.
+                escaped = true;
+            }
+            else {
+                out.pop();
+            }
+            continue;
+        }
+        out.push(seg);
+    }
+    const joined = out.join("/");
+    return escaped ? `../${joined}` : joined;
+}
+/**
+ * `false` when a resolved rel target escapes the package root. Targets
+ * that escape are malicious or accidentally produced by broken
+ * serialisers and always indicate a corrupt package.
+ */
+function isSafeResolvedPath(resolved) {
+    return !(resolved === ".." || resolved.startsWith("../") || resolved.includes("/../"));
+}
+/**
+ * Derive the .rels path for a given source part. Symmetric with
+ * `getRelsSourceDir`. Examples:
+ *
+ * | source part                    | rels path                              |
+ * |--------------------------------|----------------------------------------|
+ * | `xl/workbook.xml`              | `xl/_rels/workbook.xml.rels`           |
+ * | `xl/worksheets/sheet1.xml`     | `xl/worksheets/_rels/sheet1.xml.rels`  |
+ */
+function relsPathForPart(partPath) {
+    const base = posixBasename(partPath);
+    const dir = partPath.length > base.length ? partPath.slice(0, partPath.length - base.length - 1) : "";
+    return dir ? `${dir}/_rels/${base}.rels` : `_rels/${base}.rels`;
+}
+/**
+ * Inverse of {@link relsPathForPart}: source part for a given rels file.
+ * Returns undefined for the root rels (which has no conventional source).
+ */
+function sourcePartForRels(relsPath) {
+    if (relsPath === "_rels/.rels") {
+        return undefined;
+    }
+    const base = posixBasename(relsPath);
+    if (!base.endsWith(".rels")) {
+        return undefined;
+    }
+    const srcDir = getRelsSourceDir(relsPath);
+    const sourceName = base.slice(0, -".rels".length);
+    return srcDir ? `${srcDir}/${sourceName}` : sourceName;
+}
+/**
+ * Part name satisfies OPC PartName grammar — not empty, uses only safe
+ * characters, does not end with `/` and does not contain `.` or `..`
+ * segments. We do not validate the full grammar but cover the cases that
+ * break Excel in practice.
+ */
+function isLegalPartName(partName) {
+    if (!partName) {
+        return false;
+    }
+    if (partName.endsWith("/")) {
+        return false;
+    }
+    if (/[\\:*?"<>|]/.test(partName)) {
+        return false;
+    }
+    const segments = partName.split("/");
+    for (const seg of segments) {
+        if (seg === "" || seg === "." || seg === "..") {
+            return false;
+        }
+    }
+    return true;
+}

package/dist/cjs/modules/excel/utils/ooxml-validator/reporter.js

@@ -0,0 +1,66 @@
+"use strict";
+/**
+ * Problem reporter shared by all checkers.
+ *
+ * Two responsibilities:
+ *   1. Filter warnings when `includeWarnings` is `false`.
+ *   2. Short-circuit after `maxProblems` is reached.
+ *
+ * The reporter does not sort or dedupe — checkers are expected to emit at
+ * most one problem per logical issue. Callers get problems in encounter
+ * order, which is stable across runs for the same input.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Reporter = void 0;
+exports.reportWithSeverity = reportWithSeverity;
+class Reporter {
+    constructor(options = {}) {
+        this.problems = [];
+        this.errorCount = 0;
+        this.maxProblems = options.maxProblems;
+        this.includeWarnings = options.includeWarnings ?? false;
+    }
+    /**
+     * `true` once the configured `maxProblems` cap is reached. Checkers
+     * should consult this at the top of their per-part loops to avoid
+     * doing unnecessary work.
+     */
+    get capped() {
+        return this.maxProblems !== undefined && this.problems.length >= this.maxProblems;
+    }
+    get hasErrors() {
+        return this.errorCount > 0;
+    }
+    /** Report an error-severity problem. */
+    error(kind, message, file) {
+        this.push({ kind, severity: "error", message, file });
+        this.errorCount += this.capped ? 0 : 1;
+    }
+    /** Report a warning-severity problem. Only recorded if includeWarnings. */
+    warning(kind, message, file) {
+        if (!this.includeWarnings) {
+            return;
+        }
+        this.push({ kind, severity: "warning", message, file });
+    }
+    push(problem) {
+        if (this.maxProblems !== undefined && this.problems.length >= this.maxProblems) {
+            return;
+        }
+        this.problems.push(problem);
+    }
+}
+exports.Reporter = Reporter;
+/**
+ * Convenience alias for the legacy `severity` argument used in the old
+ * flat API. Kept for internal checker code that wants to produce a
+ * problem with a runtime-chosen severity.
+ */
+function reportWithSeverity(reporter, severity, kind, message, file) {
+    if (severity === "error") {
+        reporter.error(kind, message, file);
+    }
+    else {
+        reporter.warning(kind, message, file);
+    }
+}

package/dist/cjs/modules/excel/utils/ooxml-validator/types.js

@@ -0,0 +1,13 @@
+"use strict";
+/**
+ * Public types for the OOXML validator.
+ *
+ * The validator's job is to detect xlsx packages that Excel will refuse to
+ * open (or silently repair). Each check emits zero or more `Problem` entries
+ * tagged by `kind`; callers can branch on `kind` for structured handling.
+ *
+ * Problem kinds are grouped by subsystem to make ad-hoc extension easy.
+ * New kinds MUST be added to the union below so consumers can enumerate them
+ * at the type level. Removing or renaming kinds is a breaking change.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/modules/excel/utils/ooxml-validator/xml-utils.js

@@ -0,0 +1,110 @@
+"use strict";
+/**
+ * XML helpers that tolerate namespace prefixes.
+ *
+ * OOXML serialisers are allowed to write `<drawing>` or `<x:drawing>` —
+ * both are legal in the same schema. All validator checks must therefore
+ * match on the **local name**, not the prefixed name. These helpers also
+ * tolerate namespaced attributes like `r:id` vs `ns0:id`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findChildren = void 0;
+exports.localName = localName;
+exports.matchesLocal = matchesLocal;
+exports.findChildLocal = findChildLocal;
+exports.findChildrenLocal = findChildrenLocal;
+exports.hasDescendantLocal = hasDescendantLocal;
+exports.collectDescendantsLocal = collectDescendantsLocal;
+exports.attrByLocalName = attrByLocalName;
+exports.tryParseXml = tryParseXml;
+const dom_1 = require("../../../xml/dom.js");
+Object.defineProperty(exports, "findChildren", { enumerable: true, get: function () { return dom_1.findChildren; } });
+/**
+ * Extract the local name from a tag name, i.e. the part after the last `:`.
+ * For `drawing` returns `drawing`; for `x:drawing` returns `drawing`.
+ */
+function localName(name) {
+    const idx = name.lastIndexOf(":");
+    return idx === -1 ? name : name.slice(idx + 1);
+}
+/** Namespace-insensitive element-name equality. */
+function matchesLocal(name, target) {
+    return localName(name) === target;
+}
+/** Find first child element with matching **local** name. */
+function findChildLocal(el, local) {
+    for (const child of el.children) {
+        if (child.type === "element" && matchesLocal(child.name, local)) {
+            return child;
+        }
+    }
+    return undefined;
+}
+/** Find all child elements with matching **local** name. */
+function findChildrenLocal(el, local) {
+    const out = [];
+    for (const child of el.children) {
+        if (child.type === "element" && matchesLocal(child.name, local)) {
+            out.push(child);
+        }
+    }
+    return out;
+}
+/** `true` when any descendant (or self) has matching local name. */
+function hasDescendantLocal(root, local) {
+    if (matchesLocal(root.name, local)) {
+        return true;
+    }
+    let found = false;
+    (0, dom_1.walk)(root, child => {
+        if (!found && matchesLocal(child.name, local)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/** Collect all descendants (including self) matching local name. */
+function collectDescendantsLocal(root, local) {
+    const out = [];
+    if (matchesLocal(root.name, local)) {
+        out.push(root);
+    }
+    (0, dom_1.walk)(root, child => {
+        if (child !== root && matchesLocal(child.name, local)) {
+            out.push(child);
+        }
+    });
+    return out;
+}
+/**
+ * Read an attribute by local name. The OOXML convention is to use
+ * namespaced attributes like `r:id` but some serialisers strip or
+ * renumber the prefix. We match by suffix `:<local>` or exact `local`.
+ */
+function attrByLocalName(el, local) {
+    const direct = el.attributes[local];
+    if (direct !== undefined) {
+        return direct;
+    }
+    for (const key in el.attributes) {
+        const idx = key.lastIndexOf(":");
+        if (idx !== -1 && key.slice(idx + 1) === local) {
+            return el.attributes[key];
+        }
+    }
+    return undefined;
+}
+/**
+ * Parse an XML string into a DOM tree. Returns `undefined` and records the
+ * failure as a malformed XML problem via `onMalformed`. We don't throw
+ * because validators must continue after a parse failure.
+ */
+function tryParseXml(xml, onMalformed) {
+    try {
+        return (0, dom_1.parseXml)(xml);
+    }
+    catch (err) {
+        onMalformed(err instanceof Error ? err : new Error(String(err)));
+        return undefined;
+    }
+}