@cj-tech-master/excelts 9.4.2 → 9.5.0

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

@@ -0,0 +1,191 @@
+/**
+ * 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).
+ */
+import { attrByLocalName, findChildrenLocal, tryParseXml } from "./xml-utils.js";
+const textDecoder = new TextDecoder();
+// -----------------------------------------------------------------------------
+// Context
+// -----------------------------------------------------------------------------
+export 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 = 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 findChildrenLocal(root, "Default")) {
+            const extRaw = attrByLocalName(el, "Extension");
+            const ct = attrByLocalName(el, "ContentType");
+            if (extRaw && ct) {
+                data.defaults.set(extRaw.toLowerCase(), ct);
+            }
+        }
+        for (const el of findChildrenLocal(root, "Override")) {
+            const partName = attrByLocalName(el, "PartName");
+            const ct = 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 findChildrenLocal(root, "Relationship")) {
+            const id = attrByLocalName(el, "Id");
+            const type = attrByLocalName(el, "Type");
+            const target = attrByLocalName(el, "Target");
+            const targetMode = 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;
+    }
+}
+/** Get the root element of a DOM; returns undefined for missing DOM. */
+export function domRoot(dom) {
+    return dom?.root;
+}

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

@@ -0,0 +1,102 @@
+/**
+ * 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.
+ */
+import { extractAll } from "../../../archive/unzip/extract.js";
+import { checkChart } from "./check-chart.js";
+import { checkChartSidecars } from "./check-chart-sidecar.js";
+import { checkChartsheet } from "./check-chartsheet.js";
+import { checkContentTypes } from "./check-content-types.js";
+import { checkDrawing } from "./check-drawing.js";
+import { checkPivot } from "./check-pivot.js";
+import { checkRelationships, checkRootRelationships } from "./check-relationships.js";
+import { checkStructure, checkXmlWellFormed } from "./check-structure.js";
+import { checkStyles } from "./check-styles.js";
+import { checkTables } from "./check-table.js";
+import { checkWorkbook } from "./check-workbook.js";
+import { checkWorksheets } from "./check-worksheet.js";
+import { ValidationContext } from "./context.js";
+import { isXmlLike } from "./path-utils.js";
+import { Reporter } from "./reporter.js";
+/**
+ * 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.
+ */
+export 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 extractAll(xlsxBuffer);
+    const reporter = new Reporter({ maxProblems, includeWarnings });
+    const ctx = new ValidationContext(entries, reporter);
+    // Order matters: later checks rely on earlier ones NOT firing false
+    // positives when structural invariants are broken. Structure first.
+    checkStructure(ctx);
+    if (optCheckXmlWellFormed) {
+        checkXmlWellFormed(ctx);
+    }
+    if (checkContentTypesOverrides) {
+        checkContentTypes(ctx);
+    }
+    checkRootRelationships(ctx);
+    if (checkRelationshipTargets) {
+        checkRelationships(ctx);
+    }
+    checkWorkbook(ctx);
+    if (checkWorksheetControlWiring) {
+        checkWorksheets(ctx);
+    }
+    if (checkChartStructure) {
+        checkChart(ctx);
+        checkDrawing(ctx);
+        checkChartsheet(ctx);
+        checkPivot(ctx);
+        checkTables(ctx);
+        checkChartSidecars(ctx);
+    }
+    if (checkStylesIntegrity) {
+        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 (isXmlLike(entry.path)) {
+            xmlLikeCount++;
+        }
+        if (entry.path.endsWith(".rels")) {
+            relsCount++;
+        }
+    }
+    return { entryCount, xmlLikeCount, relsCount };
+}

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

@@ -0,0 +1,156 @@
+/**
+ * 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.
+ */
+/**
+ * Strip a single leading `/` if present. OPC `PartName` values start with
+ * `/` by spec, but zip entries do not.
+ */
+export function stripLeadingSlash(p) {
+    return p.startsWith("/") ? p.slice(1) : p;
+}
+/** `.xml`, `.rels`, or `.vml` — the payloads we parse as XML. */
+export 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`     |
+ */
+export 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`.
+ */
+export function posixBasename(p) {
+    const idx = p.lastIndexOf("/");
+    return idx === -1 ? p : p.slice(idx + 1);
+}
+/** Extension without the leading dot, lowercase. `""` when missing. */
+export 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.
+ */
+export 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.
+ */
+export 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`  |
+ */
+export 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).
+ */
+export 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.
+ */
+export 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/esm/modules/excel/utils/ooxml-validator/reporter.js

@@ -0,0 +1,61 @@
+/**
+ * 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.
+ */
+export 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);
+    }
+}
+/**
+ * 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.
+ */
+export function reportWithSeverity(reporter, severity, kind, message, file) {
+    if (severity === "error") {
+        reporter.error(kind, message, file);
+    }
+    else {
+        reporter.warning(kind, message, file);
+    }
+}

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

@@ -0,0 +1,12 @@
+/**
+ * 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.
+ */
+export {};

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

@@ -0,0 +1,100 @@
+/**
+ * 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`.
+ */
+import { findChildren, parseXml, walk } from "../../../xml/dom.js";
+/**
+ * Extract the local name from a tag name, i.e. the part after the last `:`.
+ * For `drawing` returns `drawing`; for `x:drawing` returns `drawing`.
+ */
+export function localName(name) {
+    const idx = name.lastIndexOf(":");
+    return idx === -1 ? name : name.slice(idx + 1);
+}
+/** Namespace-insensitive element-name equality. */
+export function matchesLocal(name, target) {
+    return localName(name) === target;
+}
+/** Find first child element with matching **local** name. */
+export 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. */
+export 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. */
+export function hasDescendantLocal(root, local) {
+    if (matchesLocal(root.name, local)) {
+        return true;
+    }
+    let found = false;
+    walk(root, child => {
+        if (!found && matchesLocal(child.name, local)) {
+            found = true;
+        }
+    });
+    return found;
+}
+/** Collect all descendants (including self) matching local name. */
+export function collectDescendantsLocal(root, local) {
+    const out = [];
+    if (matchesLocal(root.name, local)) {
+        out.push(root);
+    }
+    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`.
+ */
+export 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.
+ */
+export function tryParseXml(xml, onMalformed) {
+    try {
+        return parseXml(xml);
+    }
+    catch (err) {
+        onMalformed(err instanceof Error ? err : new Error(String(err)));
+        return undefined;
+    }
+}
+// Re-export commonly used primitives so checkers only need one import.
+export { findChildren };