@qvac/harness 1.0.0-rc.1 → 1.0.0-rc.2

package/dist-lib/lib/office/engine/opc/package.js

@@ -0,0 +1,324 @@
+import * as xml from '../xml.js';
+import * as zip from './zip.js';
+import * as paths from './paths.js';
+import { ContentTypes, CONTENT_TYPES_NAME } from './content-types.js';
+import { Relationships } from './relationships.js';
+import { DocsError } from '../errors.js';
+const RELATIONSHIPS_TYPE = 'application/vnd.openxmlformats-package.relationships+xml';
+const STORED = new Set(['png', 'jpg', 'jpeg', 'gif', 'mp3', 'mp4', 'm4a', 'wav', 'zip']);
+const DEFAULT_LIMITS = { maxEntries: 10000, maxSize: 512 * 1024 * 1024, maxRatio: 1000 };
+function toBytes(input) {
+    if (input instanceof Uint8Array)
+        return input;
+    if (input instanceof ArrayBuffer) {
+        return new Uint8Array(input);
+    }
+    throw new DocsError('INVALID_INPUT', 'expected the file as a Uint8Array or Buffer');
+}
+function isDocument(data) {
+    return !(data instanceof Uint8Array);
+}
+export class Package {
+    static strict = false;
+    strict;
+    contentTypes;
+    parts;
+    folded;
+    order;
+    relsBySource;
+    removed;
+    edited;
+    strays;
+    constructor(entries, opts = {}) {
+        this.strict = opts.strict ?? Package.strict;
+        this.parts = new Map();
+        this.folded = new Map();
+        this.order = entries.map(([name]) => name);
+        this.relsBySource = new Map();
+        this.removed = false;
+        this.edited = false;
+        for (const [name, bytes] of entries) {
+            this.store(name, { bytes, doc: null, dirty: false });
+        }
+        const types = this.parts.get(CONTENT_TYPES_NAME);
+        if (!types?.bytes) {
+            throw new DocsError('NOT_OOXML', 'the file has no [Content_Types].xml, so it is not an Office document');
+        }
+        this.contentTypes = new ContentTypes(types.bytes);
+        this.forget(CONTENT_TYPES_NAME);
+        this.strays = this.unreachable();
+    }
+    static open(bytes, opts = {}) {
+        const limits = { ...DEFAULT_LIMITS, ...opts.limits };
+        const entries = zip
+            .read(toBytes(bytes), limits)
+            .map((e) => [paths.normalize(e.name), e.data]);
+        return new Package(entries, opts);
+    }
+    static create(opts = {}) {
+        const types = xml.serialize(xml.parse(`<Types xmlns="${xml.ns.ct}"/>`));
+        const pkg = new Package([[CONTENT_TYPES_NAME, types]], opts);
+        pkg.contentTypes.addDefault('rels', RELATIONSHIPS_TYPE);
+        pkg.contentTypes.addDefault('xml', 'application/xml');
+        return pkg;
+    }
+    get changed() {
+        return (this.edited ||
+            this.contentTypes.dirty ||
+            [...this.relsBySource.values()].some((rels) => rels.dirty));
+    }
+    names() {
+        return [...this.parts.keys()].filter((name) => !name.endsWith('.rels'));
+    }
+    has(name) {
+        return name !== null && this.find(name) !== null;
+    }
+    bytes(name) {
+        const part = this.require(name);
+        if (part.doc && part.dirty) {
+            return xml.serialize(part.doc);
+        }
+        if (part.bytes) {
+            return part.bytes;
+        }
+        if (part.doc) {
+            return xml.serialize(part.doc);
+        }
+        throw new DocsError('PART_MISSING', `${name} has no content`);
+    }
+    xml(name) {
+        const part = this.require(name);
+        if (part.doc) {
+            return part.doc;
+        }
+        const doc = xml.parse(part.bytes ?? new Uint8Array(0), name);
+        part.doc = doc;
+        if (this.strict) {
+            part.snapshot = xml.toString(doc);
+        }
+        return doc;
+    }
+    root(name) {
+        return xml.root(this.xml(name));
+    }
+    touch(name) {
+        this.require(name).dirty = true;
+        this.edited = true;
+    }
+    contentType(name) {
+        return this.contentTypes.get(this.find(name) ?? name);
+    }
+    add(name, data, contentType) {
+        if (this.find(name) !== null) {
+            throw new DocsError('PART_EXISTS', `${name} already exists in the package`);
+        }
+        const doc = isDocument(data);
+        this.store(name, { bytes: doc ? null : data, doc: doc ? data : null, dirty: doc });
+        this.order.push(name);
+        if (contentType && this.contentTypes.get(name) !== contentType) {
+            this.contentTypes.setOverride(name, contentType);
+        }
+        this.edited = true;
+    }
+    write(name, data) {
+        const part = this.require(name);
+        const doc = isDocument(data);
+        part.bytes = doc ? null : data;
+        part.doc = doc ? data : null;
+        part.dirty = doc;
+        delete part.snapshot;
+        this.edited = true;
+    }
+    remove(input) {
+        const name = this.find(input);
+        if (name === null) {
+            return false;
+        }
+        this.forget(name);
+        this.relsBySource.delete(name);
+        const rels = this.find(paths.relsFor(name));
+        if (rels !== null) {
+            this.forget(rels);
+        }
+        this.contentTypes.removeOverride(name);
+        this.removed = true;
+        this.edited = true;
+        return true;
+    }
+    rels(source) {
+        const cached = this.relsBySource.get(source);
+        if (cached) {
+            return cached;
+        }
+        const stored = this.find(paths.relsFor(source));
+        const rels = new Relationships(source, stored ? (this.parts.get(stored)?.bytes ?? null) : null);
+        this.relsBySource.set(source, rels);
+        return rels;
+    }
+    related(source, type) {
+        const out = [];
+        for (const rel of this.rels(source).byType(type)) {
+            const part = rel.external ? null : this.find(rel.part);
+            if (part !== null) {
+                out.push(part);
+            }
+        }
+        return out;
+    }
+    dropUnreferenced(source, types) {
+        const used = referencedIds(this.root(source));
+        const rels = this.rels(source);
+        const dropped = rels.all().filter((rel) => types.includes(rel.type) && !used.has(rel.id));
+        for (const rel of dropped) {
+            rels.remove(rel.id);
+        }
+        if (dropped.length) {
+            this.removed = true;
+        }
+        return dropped.map((rel) => rel.id);
+    }
+    freeName(pattern) {
+        let n = 1;
+        while (this.find(pattern.replace('%d', String(n))) !== null) {
+            n++;
+        }
+        return pattern.replace('%d', String(n));
+    }
+    reachable() {
+        const seen = new Set();
+        const queue = ['/'];
+        for (let source = queue.shift(); source !== undefined; source = queue.shift()) {
+            for (const rel of this.rels(source).all()) {
+                const part = rel.external ? null : this.resolveExisting(rel.part);
+                if (part && !seen.has(part)) {
+                    seen.add(part);
+                    queue.push(part);
+                }
+            }
+        }
+        return seen;
+    }
+    prune() {
+        const keep = this.reachable();
+        const removed = this.names().filter((name) => !keep.has(name) && !this.strays.has(name));
+        for (const name of removed) {
+            this.remove(name);
+        }
+        return removed;
+    }
+    unreachable() {
+        try {
+            const keep = this.reachable();
+            return new Set(this.names().filter((name) => !keep.has(name)));
+        }
+        catch {
+            return new Set();
+        }
+    }
+    save() {
+        if (this.strict) {
+            this.checkUntouched();
+        }
+        if (this.removed) {
+            this.prune();
+            this.removed = false;
+        }
+        this.edited = this.changed;
+        this.flushRels();
+        const untyped = [...this.parts.keys()].some((name) => name.endsWith('.rels') && !this.contentTypes.get(name));
+        if (untyped) {
+            this.contentTypes.addDefault('rels', RELATIONSHIPS_TYPE);
+        }
+        const names = [...new Set(this.order)].filter((name) => this.parts.has(name));
+        names.sort((a, b) => Number(a !== '/_rels/.rels') - Number(b !== '/_rels/.rels'));
+        return zip.write([
+            { name: '[Content_Types].xml', data: this.contentTypes.serialize(), compress: true },
+            ...names.map((name) => ({
+                name: name.slice(1),
+                data: this.bytes(name),
+                compress: !STORED.has(paths.extension(name))
+            }))
+        ]);
+    }
+    checkUntouched() {
+        for (const [name, part] of this.parts) {
+            if (part.doc &&
+                !part.dirty &&
+                part.snapshot !== undefined &&
+                xml.toString(part.doc) !== part.snapshot) {
+                throw new DocsError('UNTOUCHED_EDIT', `${name} was changed without touch(), so the edit would be lost`);
+            }
+        }
+    }
+    flushRels() {
+        for (const [source, rels] of this.relsBySource) {
+            if (!rels.dirty)
+                continue;
+            const stored = this.find(rels.name);
+            const existing = stored ? this.parts.get(stored) : undefined;
+            const bytes = rels.serialize();
+            if (existing) {
+                existing.bytes = bytes;
+                existing.doc = null;
+                existing.dirty = false;
+            }
+            else if (source === '/' || this.find(source) !== null) {
+                this.store(rels.name, { bytes, doc: null, dirty: false });
+                this.order.push(rels.name);
+            }
+            rels.dirty = false;
+        }
+    }
+    require(name) {
+        const stored = this.find(name);
+        const part = stored === null ? undefined : this.parts.get(stored);
+        if (!part) {
+            throw new DocsError('PART_MISSING', `${name} is not in the package`);
+        }
+        return part;
+    }
+    resolveExisting(name) {
+        if (name === null)
+            return null;
+        const found = this.find(name);
+        if (found !== null) {
+            return found;
+        }
+        try {
+            return this.find(decodeURI(name));
+        }
+        catch {
+            return null;
+        }
+    }
+    find(name) {
+        if (name === null)
+            return null;
+        if (this.parts.has(name))
+            return name;
+        return this.folded.get(name.toLowerCase()) ?? null;
+    }
+    store(name, part) {
+        this.parts.set(name, part);
+        this.folded.set(name.toLowerCase(), name);
+    }
+    forget(name) {
+        this.parts.delete(name);
+        if (this.folded.get(name.toLowerCase()) === name) {
+            this.folded.delete(name.toLowerCase());
+        }
+    }
+}
+export function referencedIds(top) {
+    const used = new Set();
+    const stack = [top];
+    for (let el = stack.pop(); el; el = stack.pop()) {
+        for (const attr of Array.from(el.attributes)) {
+            if (attr.namespaceURI === xml.ns.r) {
+                used.add(attr.value);
+            }
+        }
+        stack.push(...xml.children(el));
+    }
+    return used;
+}

package/dist-lib/lib/office/engine/opc/paths.d.ts

@@ -0,0 +1,7 @@
+export declare function dirname(partName: string): string;
+export declare function basename(partName: string): string;
+export declare function extension(partName: string): string;
+export declare function normalize(path: string): string;
+export declare function relsFor(source: string): string;
+export declare function resolve(source: string, target: string): string;
+export declare function relative(source: string, target: string): string;

package/dist-lib/lib/office/engine/opc/paths.js

@@ -0,0 +1,46 @@
+export function dirname(partName) {
+    return partName.slice(0, partName.lastIndexOf('/') + 1);
+}
+export function basename(partName) {
+    return partName.slice(partName.lastIndexOf('/') + 1);
+}
+export function extension(partName) {
+    const base = basename(partName);
+    const dot = base.lastIndexOf('.');
+    return dot === -1 ? '' : base.slice(dot + 1).toLowerCase();
+}
+export function normalize(path) {
+    const out = [];
+    for (const segment of path.split('/')) {
+        if (segment === '' || segment === '.')
+            continue;
+        if (segment === '..') {
+            out.pop();
+        }
+        else {
+            out.push(segment);
+        }
+    }
+    return '/' + out.join('/');
+}
+export function relsFor(source) {
+    if (source === '/')
+        return '/_rels/.rels';
+    return `${dirname(source)}_rels/${basename(source)}.rels`;
+}
+export function resolve(source, target) {
+    const clean = target.split('#')[0];
+    if (clean.startsWith('/')) {
+        return normalize(clean);
+    }
+    return normalize(dirname(source) + clean);
+}
+export function relative(source, target) {
+    const from = dirname(source).split('/').filter(Boolean);
+    const to = target.split('/').filter(Boolean);
+    let common = 0;
+    while (common < from.length && common < to.length - 1 && from[common] === to[common]) {
+        common++;
+    }
+    return [...from.slice(common).map(() => '..'), ...to.slice(common)].join('/');
+}

package/dist-lib/lib/office/engine/opc/properties.d.ts

@@ -0,0 +1,7 @@
+import type { Package } from './package.ts';
+export interface SaveOptions {
+    modified?: Date;
+    modifiedBy?: string;
+}
+export declare function applySaveOptions(pkg: Package, opts?: SaveOptions): void;
+export declare function refreshSummary(pkg: Package, counts?: Record<string, number>): void;

package/dist-lib/lib/office/engine/opc/properties.js

@@ -0,0 +1,75 @@
+import * as xml from '../xml.js';
+import { DocsError } from '../errors.js';
+const CORE_REL = 'http://schemas.openxmlformats.org/package/2006/relationships/metadata/core-properties';
+const APP_REL = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/extended-properties';
+const CORE_TYPE = 'application/vnd.openxmlformats-package.core-properties+xml';
+const CP = 'http://schemas.openxmlformats.org/package/2006/metadata/core-properties';
+const DC = 'http://purl.org/dc/elements/1.1/';
+const DCTERMS = 'http://purl.org/dc/terms/';
+const XSI = 'http://www.w3.org/2001/XMLSchema-instance';
+const EP = 'http://schemas.openxmlformats.org/officeDocument/2006/extended-properties';
+function setField(doc, field, value) {
+    const top = xml.root(doc);
+    const local = field.name.split(':')[1];
+    const el = xml.child(top, field.namespace, local) ??
+        xml.append(top, xml.named(doc, field.name, field.namespace));
+    xml.setText(el, value);
+    return el;
+}
+function corePart(pkg) {
+    const existing = pkg.related('/', CORE_REL)[0];
+    if (existing) {
+        return existing;
+    }
+    const part = '/docProps/core.xml';
+    pkg.add(part, xml.parse(`<cp:coreProperties xmlns:cp="${CP}" xmlns:dc="${DC}"/>`), CORE_TYPE);
+    pkg.rels('/').add(CORE_REL, part);
+    return part;
+}
+export function applySaveOptions(pkg, opts = {}) {
+    const { modified, modifiedBy } = opts;
+    if (modified === undefined && modifiedBy === undefined) {
+        return;
+    }
+    if (modified !== undefined && !(modified instanceof Date && !Number.isNaN(modified.getTime()))) {
+        throw new DocsError('INVALID_OPTIONS', 'modified must be a valid Date');
+    }
+    if (modifiedBy !== undefined && typeof modifiedBy !== 'string') {
+        throw new DocsError('INVALID_OPTIONS', 'modifiedBy must be text');
+    }
+    const part = corePart(pkg);
+    const doc = pkg.xml(part);
+    if (modifiedBy !== undefined) {
+        setField(doc, { namespace: CP, name: 'cp:lastModifiedBy' }, modifiedBy);
+    }
+    if (modified !== undefined) {
+        const stamp = modified.toISOString().replace(/\.\d{3}Z$/, 'Z');
+        const el = setField(doc, { namespace: DCTERMS, name: 'dcterms:modified' }, stamp);
+        el.setAttributeNS(XSI, 'xsi:type', 'dcterms:W3CDTF');
+    }
+    pkg.touch(part);
+}
+export function refreshSummary(pkg, counts = {}) {
+    const part = pkg.related('/', APP_REL)[0];
+    if (!part) {
+        return;
+    }
+    const top = pkg.root(part);
+    let changed = false;
+    for (const local of ['HeadingPairs', 'TitlesOfParts']) {
+        for (const el of xml.children(top, EP, local)) {
+            xml.remove(el);
+            changed = true;
+        }
+    }
+    for (const [local, value] of Object.entries(counts)) {
+        const el = xml.child(top, EP, local);
+        if (el && xml.text(el) !== String(value)) {
+            xml.setText(el, String(value));
+            changed = true;
+        }
+    }
+    if (changed) {
+        pkg.touch(part);
+    }
+}

package/dist-lib/lib/office/engine/opc/relationships.d.ts

@@ -0,0 +1,23 @@
+import type { Document, Element } from '../xml.ts';
+export interface Relationship {
+    id: string;
+    type: string;
+    target: string;
+    external: boolean;
+    part: string | null;
+}
+export declare class Relationships {
+    source: string;
+    name: string;
+    doc: Document;
+    dirty: boolean;
+    constructor(source: string, bytes: Uint8Array | null);
+    get root(): Element;
+    all(): Relationship[];
+    get(id: string | null): Relationship | null;
+    byType(type: string): Relationship[];
+    targeting(partName: string): Relationship[];
+    add(type: string, partName: string): string;
+    remove(id: string): boolean;
+    serialize(): Uint8Array;
+}

package/dist-lib/lib/office/engine/opc/relationships.js

@@ -0,0 +1,65 @@
+import * as xml from '../xml.js';
+import * as paths from './paths.js';
+export class Relationships {
+    source;
+    name;
+    doc;
+    dirty;
+    constructor(source, bytes) {
+        this.source = source;
+        this.name = paths.relsFor(source);
+        this.doc = xml.parse(bytes ?? `<Relationships xmlns="${xml.ns.rels}"/>`, this.name);
+        this.dirty = false;
+    }
+    get root() {
+        return xml.root(this.doc);
+    }
+    all() {
+        return xml.children(this.root, xml.ns.rels, 'Relationship').map((el) => {
+            const external = el.getAttribute('TargetMode') === 'External';
+            const target = xml.attr(el, 'Target');
+            return {
+                id: xml.attr(el, 'Id'),
+                type: xml.attr(el, 'Type'),
+                target,
+                external,
+                part: external || !target ? null : paths.resolve(this.source, target)
+            };
+        });
+    }
+    get(id) {
+        return this.all().find((rel) => rel.id === id) ?? null;
+    }
+    byType(type) {
+        return this.all().filter((rel) => rel.type === type);
+    }
+    targeting(partName) {
+        return this.all().filter((rel) => rel.part === partName);
+    }
+    add(type, partName) {
+        const taken = new Set(this.all().map((rel) => rel.id));
+        let n = taken.size + 1;
+        while (taken.has(`rId${n}`)) {
+            n++;
+        }
+        const id = `rId${n}`;
+        const el = xml.named(this.doc, 'Relationship', xml.ns.rels);
+        this.root.appendChild(xml.setAttributes(el, { Id: id, Type: type, Target: paths.relative(this.source, partName) }));
+        this.dirty = true;
+        return id;
+    }
+    remove(id) {
+        const el = xml
+            .children(this.root, xml.ns.rels, 'Relationship')
+            .find((r) => r.getAttribute('Id') === id);
+        if (!el) {
+            return false;
+        }
+        xml.remove(el);
+        this.dirty = true;
+        return true;
+    }
+    serialize() {
+        return xml.serialize(this.doc);
+    }
+}

package/dist-lib/lib/office/engine/opc/zip.d.ts

@@ -0,0 +1,15 @@
+export interface Limits {
+    maxEntries: number;
+    maxSize: number;
+    maxRatio: number;
+}
+export interface ZipEntry {
+    name: string;
+    data: Uint8Array;
+}
+export interface ZipInput extends ZipEntry {
+    compress: boolean;
+}
+export declare function crc32(data: Uint8Array): number;
+export declare function read(bytes: Uint8Array, limits: Limits): ZipEntry[];
+export declare function write(entries: ZipInput[]): Uint8Array;