@ansonlai/docx-redline-js 0.2.1 → 0.4.0

package/scripts/lib/minimal-zip.mjs

@@ -8,6 +8,7 @@
  */
 
 import { deflateRawSync } from 'zlib';
+import { DOMParser } from '@xmldom/xmldom';
 
 const CRC_TABLE = (() => {
     const table = new Uint32Array(256);
@@ -120,36 +121,216 @@ const ROOT_RELS = `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/officeDocument" Target="word/document.xml"/>
 </Relationships>`;
 
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const NS_R = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships';
+const REL_BASE = 'http://schemas.openxmlformats.org/officeDocument/2006/relationships/';
+const CONTENT_TYPES = {
+    numbering: 'application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml',
+    comments: 'application/vnd.openxmlformats-officedocument.wordprocessingml.comments+xml',
+    footnotes: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footnotes+xml',
+    endnotes: 'application/vnd.openxmlformats-officedocument.wordprocessingml.endnotes+xml',
+    header: 'application/vnd.openxmlformats-officedocument.wordprocessingml.header+xml',
+    footer: 'application/vnd.openxmlformats-officedocument.wordprocessingml.footer+xml'
+};
+
+function escapeXmlAttribute(value) {
+    return String(value)
+        .replace(/&/g, '&amp;')
+        .replace(/"/g, '&quot;')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+function parsePartXml(xml, label) {
+    const errors = [];
+    const document = new DOMParser({
+        onError: (_level, message) => errors.push(message)
+    }).parseFromString(String(xml), 'application/xml');
+    if (!document?.documentElement || errors.length > 0 || document.getElementsByTagName('parsererror').length > 0) {
+        throw new Error(`${label} is not well-formed XML${errors[0] ? `: ${errors[0]}` : ''}`);
+    }
+    return document;
+}
+
+function wordIds(document, localName) {
+    return Array.from(document.getElementsByTagNameNS(NS_W, localName), node =>
+        node.getAttributeNS?.(NS_W, 'id') || node.getAttribute('w:id') || node.getAttribute('id')
+    );
+}
+
+function relationshipIds(document, localName) {
+    return Array.from(document.getElementsByTagNameNS(NS_W, localName), node =>
+        node.getAttributeNS?.(NS_R, 'id') || node.getAttribute('r:id') || node.getAttribute('id')
+    ).filter(Boolean);
+}
+
+function requireRoot(document, localName, label) {
+    if (document.documentElement.namespaceURI !== NS_W || document.documentElement.localName !== localName) {
+        throw new Error(`${label} must have w:${localName} as its document element`);
+    }
+}
+
+function validateReferencedIds(documentXml, parts) {
+    const document = parsePartXml(documentXml, 'word/document.xml');
+    requireRoot(document, 'document', 'word/document.xml');
+
+    const documentCommentIds = [
+        ...wordIds(document, 'commentRangeStart'),
+        ...wordIds(document, 'commentRangeEnd'),
+        ...wordIds(document, 'commentReference')
+    ];
+    if (documentCommentIds.length > 0 && !parts.commentsXml) {
+        throw new Error('document comment anchors require word/comments.xml');
+    }
+    if (parts.commentsXml) {
+        const comments = parsePartXml(parts.commentsXml, 'word/comments.xml');
+        requireRoot(comments, 'comments', 'word/comments.xml');
+        const defined = new Set(wordIds(comments, 'comment'));
+        const starts = wordIds(document, 'commentRangeStart');
+        const ends = wordIds(document, 'commentRangeEnd');
+        const references = wordIds(document, 'commentReference');
+        for (const id of new Set([...starts, ...ends, ...references])) {
+            if (!defined.has(id)) throw new Error(`word/comments.xml does not define referenced comment ID ${id}`);
+        }
+        if (starts.length === 0 || JSON.stringify(starts) !== JSON.stringify(ends) || JSON.stringify(starts) !== JSON.stringify(references)) {
+            throw new Error('comment start/end/reference IDs must be present and ordered identically');
+        }
+    }
+
+    for (const family of ['footnote', 'endnote']) {
+        const partKey = `${family}sXml`;
+        const referenceIds = wordIds(document, `${family}Reference`);
+        if (referenceIds.length > 0 && !parts[partKey]) {
+            throw new Error(`document ${family} references require word/${family}s.xml`);
+        }
+        if (!parts[partKey]) continue;
+        const partName = `word/${family}s.xml`;
+        const notes = parsePartXml(parts[partKey], partName);
+        requireRoot(notes, `${family}s`, partName);
+        const defined = new Set(wordIds(notes, family));
+        if (!defined.has('-1') || !defined.has('0')) {
+            throw new Error(`${partName} must define separator ID -1 and continuation separator ID 0`);
+        }
+        for (const id of referenceIds) {
+            if (!defined.has(id)) throw new Error(`${partName} does not define referenced ${family} ID ${id}`);
+        }
+    }
+
+    const headerIds = new Set((parts.headers || []).map(header => header.relationshipId));
+    const footerIds = new Set((parts.footers || []).map(footer => footer.relationshipId));
+    for (const id of relationshipIds(document, 'headerReference')) {
+        if (!headerIds.has(id)) throw new Error(`document headerReference ${id} has no configured header relationship`);
+    }
+    for (const id of relationshipIds(document, 'footerReference')) {
+        if (!footerIds.has(id)) throw new Error(`document footerReference ${id} has no configured footer relationship`);
+    }
+
+    const hyperlinkIds = new Set((parts.externalHyperlinks || []).map(link => link.relationshipId));
+    for (const id of relationshipIds(document, 'hyperlink')) {
+        if (!hyperlinkIds.has(id)) throw new Error(`external hyperlink ${id} has no configured relationship`);
+    }
+}
+
+function normalizeRelatedParts(parts) {
+    const normalized = {
+        ...parts,
+        headers: (parts.headers || []).map((header, index) => ({
+            partName: header.partName || `header${index + 1}.xml`,
+            relationshipId: header.relationshipId || `rIdHeader${index + 1}`,
+            xml: header.xml
+        })),
+        footers: (parts.footers || []).map((footer, index) => ({
+            partName: footer.partName || `footer${index + 1}.xml`,
+            relationshipId: footer.relationshipId || `rIdFooter${index + 1}`,
+            xml: footer.xml
+        })),
+        externalHyperlinks: parts.externalHyperlinks || []
+    };
+
+    const relationshipIds = [];
+    if (normalized.numberingXml) relationshipIds.push('rIdNum1');
+    if (normalized.commentsXml) relationshipIds.push('rIdComments1');
+    if (normalized.footnotesXml) relationshipIds.push('rIdFootnotes1');
+    if (normalized.endnotesXml) relationshipIds.push('rIdEndnotes1');
+    relationshipIds.push(...normalized.headers.map(item => item.relationshipId));
+    relationshipIds.push(...normalized.footers.map(item => item.relationshipId));
+    relationshipIds.push(...normalized.externalHyperlinks.map(item => item.relationshipId));
+    if (relationshipIds.some(id => !/^rId[A-Za-z0-9._-]+$/.test(String(id)))) {
+        throw new Error('every relationship ID must use a non-empty rId-prefixed token');
+    }
+    if (new Set(relationshipIds).size !== relationshipIds.length) throw new Error('document relationship IDs must be unique');
+
+    for (const [family, items, pattern] of [
+        ['header', normalized.headers, /^header[1-9][0-9]*\.xml$/],
+        ['footer', normalized.footers, /^footer[1-9][0-9]*\.xml$/]
+    ]) {
+        for (const item of items) {
+            if (!pattern.test(item.partName)) throw new Error(`${family} part name must match ${family}<number>.xml`);
+            if (typeof item.xml !== 'string' || item.xml.length === 0) throw new Error(`${family} ${item.partName} requires XML content`);
+            const xml = parsePartXml(item.xml, `word/${item.partName}`);
+            requireRoot(xml, family === 'header' ? 'hdr' : 'ftr', `word/${item.partName}`);
+        }
+    }
+    const partNames = [...normalized.headers, ...normalized.footers].map(item => item.partName);
+    if (new Set(partNames).size !== partNames.length) throw new Error('header/footer part names must be unique');
+
+    for (const link of normalized.externalHyperlinks) {
+        if (!link.relationshipId || !link.target) throw new Error('external hyperlinks require relationshipId and target');
+        let url;
+        try { url = new URL(link.target); } catch { throw new Error(`invalid external hyperlink target: ${link.target}`); }
+        if (!url.protocol || url.protocol === 'file:') throw new Error(`unsupported external hyperlink target: ${link.target}`);
+    }
+    return normalized;
+}
+
 /**
- * Assembles a minimal .docx package around a word/document.xml payload.
- *
- * @param {string} documentXml - Complete word/document.xml content
- * @param {{ numberingXml?: string|null }} [parts] - Optional extra parts
- * @returns {Buffer} - .docx bytes
+ * Creates and validates the deterministic entry set used by buildMinimalDocx.
+ * Exported for package-integrity tests; this remains script-only tooling.
  */
-export function buildMinimalDocx(documentXml, parts = {}) {
+export function buildMinimalDocxEntries(documentXml, parts = {}) {
+    const normalized = normalizeRelatedParts(parts);
+    validateReferencedIds(documentXml, normalized);
     const overrides = [];
     const documentRels = [];
     const entries = [];
 
-    if (parts.numberingXml) {
-        overrides.push('  <Override PartName="/word/numbering.xml" ContentType="application/vnd.openxmlformats-officedocument.wordprocessingml.numbering+xml"/>\n');
-        documentRels.push('  <Relationship Id="rIdNum1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/numbering" Target="numbering.xml"/>');
-    }
+    const addXmlPart = (partName, contentType, relationshipId, relationshipType, xml) => {
+        overrides.push(`  <Override PartName="/word/${partName}" ContentType="${contentType}"/>\n`);
+        documentRels.push(`  <Relationship Id="${escapeXmlAttribute(relationshipId)}" Type="${REL_BASE}${relationshipType}" Target="${escapeXmlAttribute(partName)}"/>`);
+        entries.push({ name: `word/${partName}`, data: xml });
+    };
 
-    entries.push({ name: '[Content_Types].xml', data: CONTENT_TYPES_BASE.replace('%OVERRIDES%', overrides.join('')) });
-    entries.push({ name: '_rels/.rels', data: ROOT_RELS });
-    entries.push({
+    if (normalized.numberingXml) addXmlPart('numbering.xml', CONTENT_TYPES.numbering, 'rIdNum1', 'numbering', normalized.numberingXml);
+    if (normalized.commentsXml) addXmlPart('comments.xml', CONTENT_TYPES.comments, 'rIdComments1', 'comments', normalized.commentsXml);
+    if (normalized.footnotesXml) addXmlPart('footnotes.xml', CONTENT_TYPES.footnotes, 'rIdFootnotes1', 'footnotes', normalized.footnotesXml);
+    if (normalized.endnotesXml) addXmlPart('endnotes.xml', CONTENT_TYPES.endnotes, 'rIdEndnotes1', 'endnotes', normalized.endnotesXml);
+    normalized.headers.forEach(item => addXmlPart(item.partName, CONTENT_TYPES.header, item.relationshipId, 'header', item.xml));
+    normalized.footers.forEach(item => addXmlPart(item.partName, CONTENT_TYPES.footer, item.relationshipId, 'footer', item.xml));
+    normalized.externalHyperlinks.forEach(link => {
+        documentRels.push(`  <Relationship Id="${escapeXmlAttribute(link.relationshipId)}" Type="${REL_BASE}hyperlink" Target="${escapeXmlAttribute(link.target)}" TargetMode="External"/>`);
+    });
+
+    entries.unshift({ name: 'word/document.xml', data: documentXml });
+    entries.unshift({
         name: 'word/_rels/document.xml.rels',
         data: `<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
 <Relationships xmlns="http://schemas.openxmlformats.org/package/2006/relationships">
 ${documentRels.join('\n')}
 </Relationships>`
     });
-    entries.push({ name: 'word/document.xml', data: documentXml });
-    if (parts.numberingXml) {
-        entries.push({ name: 'word/numbering.xml', data: parts.numberingXml });
-    }
+    entries.unshift({ name: '_rels/.rels', data: ROOT_RELS });
+    entries.unshift({ name: '[Content_Types].xml', data: CONTENT_TYPES_BASE.replace('%OVERRIDES%', overrides.join('')) });
+    return entries;
+}
 
-    return buildZip(entries);
+/**
+ * Assembles a minimal .docx package around a word/document.xml payload.
+ *
+ * @param {string} documentXml - Complete word/document.xml content
+ * @param {Object} [parts] - Optional numbering/comments/notes/header/footer/
+ *   external-hyperlink package parts. This helper is development-only.
+ * @returns {Buffer} - .docx bytes
+ */
+export function buildMinimalDocx(documentXml, parts = {}) {
+    return buildZip(buildMinimalDocxEntries(documentXml, parts));
 }

package/scripts/lib/word-coverage-catalogue.mjs

@@ -0,0 +1,207 @@
+import { readFileSync } from 'fs';
+
+import { WORD_TASK_CASES } from '../../tests/fixtures/word-task-cases.mjs';
+import {
+    COVERAGE_ORACLES,
+    COVERAGE_STRUCTURES,
+    COVERAGE_TASKS,
+    sortCoverageMetadata,
+    validateCoverageMetadata
+} from './word-coverage-metadata.mjs';
+
+const corpusCatalogue = JSON.parse(readFileSync(
+    new URL('../../tests/corpus/superdoc-word-scenarios.json', import.meta.url),
+    'utf8'
+));
+const corpusManifest = JSON.parse(readFileSync(
+    new URL('../../tests/corpus/superdoc-english-legal-administrative.json', import.meta.url),
+    'utf8'
+));
+const corpusCoverage = JSON.parse(readFileSync(
+    new URL('../../tests/corpus/superdoc-word-coverage.json', import.meta.url),
+    'utf8'
+));
+const priorities = JSON.parse(readFileSync(
+    new URL('../../tests/fixtures/coverage-matrix-priorities.json', import.meta.url),
+    'utf8'
+));
+
+const manifestById = new Map(corpusManifest.documents.map(document => [document.id, document]));
+
+export function validateScenarioIdentities(cases) {
+    const identities = new Set();
+    for (const item of cases) {
+        if (!item.identity || identities.has(item.identity)) {
+            throw new Error(`Duplicate or missing scenario identity: ${item.identity || '<missing>'}`);
+        }
+        identities.add(item.identity);
+    }
+}
+
+function elementCount(xml, localName) {
+    return (xml.match(new RegExp(`<w:${localName}(?:\\s|/|>)`, 'g')) || []).length;
+}
+
+function assertSyntheticClaim(testCase, structure) {
+    const xml = testCase.sourceDocumentXml || '';
+    const rules = {
+        'plain-paragraph': () => !testCase.sourceText?.includes('\n') && !testCase.original.includes('\n'),
+        'multi-paragraph': () => elementCount(xml, 'p') > 1 || testCase.sourceText?.includes('\n')
+            || testCase.original.includes('\n') || testCase.modified.includes('\n'),
+        'formatted-runs': () => /<(?:w:)?(?:b|i|u)(?:\s|\/|>)/.test(xml) || /(?:\*\*|\*|\+\+)/.test(testCase.modified),
+        list: () => elementCount(xml, 'numPr') > 0,
+        table: () => elementCount(xml, 'tbl') > 0,
+        bookmark: () => elementCount(xml, 'bookmarkStart') > 0 && elementCount(xml, 'bookmarkEnd') > 0,
+        hyperlink: () => elementCount(xml, 'hyperlink') > 0,
+        'content-control': () => elementCount(xml, 'sdt') > 0,
+        'tab-break': () => elementCount(xml, 'tab') > 0 || elementCount(xml, 'br') > 0,
+        field: () => elementCount(xml, 'fldChar') > 0,
+        comment: () => elementCount(xml, 'commentRangeStart') > 0 && Boolean(testCase.packageParts?.commentsXml),
+        note: () => (elementCount(xml, 'footnoteReference') > 0 && Boolean(testCase.packageParts?.footnotesXml))
+            || (elementCount(xml, 'endnoteReference') > 0 && Boolean(testCase.packageParts?.endnotesXml)),
+        'header-footer': () => (elementCount(xml, 'headerReference') > 0 && Boolean(testCase.packageParts?.headers))
+            || (elementCount(xml, 'footerReference') > 0 && Boolean(testCase.packageParts?.footers)),
+        'section-boundary': () => elementCount(xml, 'sectPr') > 0,
+        'prior-revisions': () => elementCount(xml, 'ins') > 0 || elementCount(xml, 'del') > 0
+    };
+    if (!rules[structure]()) {
+        throw new Error(`synthetic:${testCase.name}: ${structure} is not supported by the fixture`);
+    }
+}
+
+function syntheticTask(testCase) {
+    if (testCase.operation?.type === 'list-change') return 'list-change';
+    if (testCase.operation?.type === 'table-reconciliation') return 'table-reconciliation';
+    if (testCase.expectAtomicRollback) return 'mixed-batch';
+    if (testCase.expectNoOp) return 'accept-reject';
+    if (testCase.task.startsWith('apply-')) return 'format';
+    if (testCase.task.includes('deletion') || testCase.task.startsWith('delete-')) return 'delete';
+    if (testCase.task.includes('insertion') || testCase.task.startsWith('insert-')
+        || testCase.task === 'preserve-dollar-delimiters') return 'insert';
+    return 'replace';
+}
+
+function corpusStructures(scenario) {
+    const labels = new Set([scenario.shape, ...scenario.coverage]);
+    const structures = new Set();
+    if (scenario.shape === 'list') structures.add('list');
+    if (scenario.shape === 'table-form') structures.add('table');
+    if (scenario.shape === 'body-paragraph' || scenario.shape === 'administrative-layout' || scenario.shape === 'legal-apparatus') {
+        structures.add('plain-paragraph');
+    }
+    const mappings = [
+        [['table', 'tables', 'table-cell'], 'table'],
+        [['numbering', 'numbered-list'], 'list'],
+        [['bookmark', 'bookmarks', 'bookmark-adjacency'], 'bookmark'],
+        [['header', 'headers', 'footer', 'footers'], 'header-footer'],
+        [['footnotes-part'], 'note'],
+        [['tabs'], 'tab-break'],
+        [['field-adjacency'], 'field'],
+        [['multi-section', 'section-properties'], 'section-boundary'],
+        [['format-only', 'formatting', 'formatted-runs'], 'formatted-runs']
+    ];
+    for (const [sourceLabels, structure] of mappings) {
+        if (sourceLabels.some(label => labels.has(label))) structures.add(structure);
+    }
+    return [...structures];
+}
+
+function corpusScenarioKey(scenario) {
+    return scenario.key || scenario.id;
+}
+
+function corpusSourceId(scenario) {
+    return scenario.sourceId || scenario.id;
+}
+
+function corpusOperations(scenario) {
+    return scenario.operations || [scenario.operation];
+}
+
+export function loadCoverageCatalogue() {
+    const synthetic = WORD_TASK_CASES.map(testCase => {
+        const identity = `synthetic:${testCase.name}`;
+        const metadata = sortCoverageMetadata(validateCoverageMetadata(testCase.coverageMetadata, identity));
+        if (metadata.task !== syntheticTask(testCase)) {
+            throw new Error(`${identity}: task ${metadata.task} is unsupported by fixture task ${testCase.task}`);
+        }
+        for (const structure of metadata.structures) assertSyntheticClaim(testCase, structure);
+        return { identity, lane: 'synthetic', category: testCase.category, detail: testCase.task, metadata };
+    });
+
+    const corpus = corpusCatalogue.scenarios.map(scenario => {
+        const scenarioKey = corpusScenarioKey(scenario);
+        const sourceId = corpusSourceId(scenario);
+        const identity = `superdoc:${scenarioKey}`;
+        const source = manifestById.get(sourceId);
+        if (!source) throw new Error(`${identity}: source is absent from the pinned corpus manifest`);
+        const operations = corpusOperations(scenario);
+        const supportedOperationTypes = new Set(['replace', 'format', 'list-change', 'table-reconciliation', 'insert', 'delete']);
+        for (const operation of operations) {
+            if (!supportedOperationTypes.has(operation?.type)) {
+                throw new Error(`${identity}: unsupported corpus operation type ${operation?.type}`);
+            }
+        }
+        const declaredStructures = corpusCoverage.structuresByScenario[scenarioKey];
+        const supportedStructures = corpusStructures(scenario).sort();
+        if (!declaredStructures || JSON.stringify([...declaredStructures].sort()) !== JSON.stringify(supportedStructures)) {
+            throw new Error(`${identity}: declared structures do not match reviewed fixture labels`);
+        }
+        const declaredTask = corpusCoverage.tasksByScenario?.[scenarioKey]
+            || (operations.length > 1 ? 'mixed-batch' : (operations[0]?.type || 'replace'));
+        const metadata = sortCoverageMetadata(validateCoverageMetadata({
+            ...corpusCoverage.defaults,
+            task: declaredTask,
+            structures: declaredStructures
+        }, identity));
+        const expectedTask = operations.length > 1 ? 'mixed-batch' : (operations[0]?.type || 'replace');
+        if (metadata.task !== expectedTask) {
+            throw new Error(`${identity}: task ${metadata.task} does not match operation type ${expectedTask}`);
+        }
+        return { identity, lane: 'superdoc', category: source.type, detail: scenario.shape, metadata };
+    });
+    const cases = [...synthetic, ...corpus];
+    if (Object.keys(corpusCoverage.structuresByScenario).length !== corpus.length) {
+        throw new Error('SuperDoc coverage metadata contains a missing or unknown scenario identity');
+    }
+    validateScenarioIdentities(cases);
+    return { cases, priorities };
+}
+
+export function buildCoverageMatrix(cases) {
+    const cells = new Map();
+    for (const task of COVERAGE_TASKS) {
+        for (const structure of COVERAGE_STRUCTURES) cells.set(`${task}/${structure}`, []);
+    }
+    for (const testCase of cases) {
+        for (const structure of testCase.metadata.structures) {
+            cells.get(`${testCase.metadata.task}/${structure}`).push(testCase.identity);
+        }
+    }
+    return cells;
+}
+
+export function validateCoveragePriorities(cases, priorityConfig = priorities) {
+    const cells = buildCoverageMatrix(cases);
+    const dispositions = new Map(priorityConfig.emptyCellDispositions.map(item => [`${item.task}/${item.structure}`, item]));
+    for (const item of [...priorityConfig.highPriorityCells, ...priorityConfig.emptyCellDispositions]) {
+        if (!COVERAGE_TASKS.includes(item.task) || !COVERAGE_STRUCTURES.includes(item.structure)) {
+            throw new Error(`Unknown priority cell: ${item.task}/${item.structure}`);
+        }
+    }
+    for (const cell of priorityConfig.highPriorityCells) {
+        const key = `${cell.task}/${cell.structure}`;
+        if (cells.get(key).length === 0 && !dispositions.has(key)) {
+            throw new Error(`High-priority empty cell lacks a disposition: ${key}`);
+        }
+    }
+    for (const [key, disposition] of dispositions) {
+        if (!['planned', 'excluded'].includes(disposition.status) || !disposition.reason || !disposition.dependency) {
+            throw new Error(`${key}: disposition requires status, reason, and dependency`);
+        }
+        if (cells.get(key).length > 0) throw new Error(`${key}: obsolete empty-cell disposition is still present`);
+    }
+    return cells;
+}
+
+export { COVERAGE_ORACLES, COVERAGE_STRUCTURES, COVERAGE_TASKS };

package/scripts/lib/word-coverage-metadata.mjs

@@ -0,0 +1,93 @@
+export const COVERAGE_TASKS = Object.freeze([
+    'replace',
+    'insert',
+    'delete',
+    'format',
+    'comment',
+    'accept-reject',
+    'list-change',
+    'table-reconciliation',
+    'mixed-batch'
+]);
+
+export const COVERAGE_STRUCTURES = Object.freeze([
+    'plain-paragraph',
+    'multi-paragraph',
+    'formatted-runs',
+    'list',
+    'table',
+    'bookmark',
+    'hyperlink',
+    'content-control',
+    'tab-break',
+    'field',
+    'comment',
+    'note',
+    'header-footer',
+    'section-boundary',
+    'prior-revisions'
+]);
+
+export const COVERAGE_ORACLES = Object.freeze([
+    'js-exact-round-trip',
+    'runtime-validator',
+    'xsd',
+    'libreoffice',
+    'synthetic-word',
+    'real-document-word',
+    'ai-word-visual-preflight',
+    'human-word-visual-review'
+]);
+
+export const MANUAL_REVIEW_STATES = Object.freeze([
+    'missing',
+    'current',
+    'stale'
+]);
+
+const vocabularySets = {
+    task: new Set(COVERAGE_TASKS),
+    structures: new Set(COVERAGE_STRUCTURES),
+    oracles: new Set(COVERAGE_ORACLES)
+};
+
+export function validateCoverageMetadata(metadata, identity) {
+    if (!metadata || typeof metadata !== 'object') {
+        throw new Error(`${identity}: coverage metadata is missing`);
+    }
+    if (!vocabularySets.task.has(metadata.task)) {
+        throw new Error(`${identity}: unknown coverage task ${JSON.stringify(metadata.task)}`);
+    }
+    for (const field of ['structures', 'oracles']) {
+        if (!Array.isArray(metadata[field]) || metadata[field].length === 0) {
+            throw new Error(`${identity}: ${field} must be a non-empty array`);
+        }
+        if (new Set(metadata[field]).size !== metadata[field].length) {
+            throw new Error(`${identity}: ${field} contains duplicates`);
+        }
+        for (const label of metadata[field]) {
+            if (!vocabularySets[field].has(label)) {
+                throw new Error(`${identity}: unknown ${field} label ${JSON.stringify(label)}`);
+            }
+        }
+    }
+    if (!MANUAL_REVIEW_STATES.includes(metadata.manualReview?.status)) {
+        throw new Error(`${identity}: manualReview.status must be missing, current, or stale`);
+    }
+    if (metadata.manualReview.status !== 'missing' && !metadata.manualReview.reviewedAt) {
+        throw new Error(`${identity}: reviewedAt is required for a ${metadata.manualReview.status} review`);
+    }
+    return metadata;
+}
+
+export function sortCoverageMetadata(metadata) {
+    return {
+        ...metadata,
+        structures: [...metadata.structures].sort(
+            (a, b) => COVERAGE_STRUCTURES.indexOf(a) - COVERAGE_STRUCTURES.indexOf(b)
+        ),
+        oracles: [...metadata.oracles].sort(
+            (a, b) => COVERAGE_ORACLES.indexOf(a) - COVERAGE_ORACLES.indexOf(b)
+        )
+    };
+}

package/scripts/lib/zip-reader.mjs

@@ -0,0 +1,64 @@
+/**
+ * Small read-only ZIP helper for validation tooling.
+ *
+ * This intentionally stays outside the runtime package path. It supports the
+ * stored and deflated entries used by DOCX packages without adding a ZIP
+ * dependency to the library.
+ */
+
+import { inflateRawSync } from 'zlib';
+
+const EOCD_SIGNATURE = 0x06054b50;
+const CENTRAL_DIR_SIGNATURE = 0x02014b50;
+const LOCAL_FILE_SIGNATURE = 0x04034b50;
+
+function findEndOfCentralDirectory(zipBuffer) {
+    const minOffset = Math.max(0, zipBuffer.length - 0xffff - 22);
+    for (let offset = zipBuffer.length - 22; offset >= minOffset; offset -= 1) {
+        if (zipBuffer.readUInt32LE(offset) === EOCD_SIGNATURE) return offset;
+    }
+    throw new Error('Invalid zip: End of central directory not found');
+}
+
+function readEntryData(zipBuffer, localHeaderOffset, compressedSize, compressionMethod) {
+    if (zipBuffer.readUInt32LE(localHeaderOffset) !== LOCAL_FILE_SIGNATURE) {
+        throw new Error('Invalid zip: local file header signature mismatch');
+    }
+
+    const fileNameLength = zipBuffer.readUInt16LE(localHeaderOffset + 26);
+    const extraLength = zipBuffer.readUInt16LE(localHeaderOffset + 28);
+    const dataStart = localHeaderOffset + 30 + fileNameLength + extraLength;
+    const compressed = zipBuffer.subarray(dataStart, dataStart + compressedSize);
+
+    if (compressionMethod === 0) return Buffer.from(compressed);
+    if (compressionMethod === 8) return inflateRawSync(compressed);
+    throw new Error(`Unsupported compression method: ${compressionMethod}`);
+}
+
+/** @returns {Map<string, Buffer>} */
+export function unzipEntries(zipBuffer) {
+    const eocdOffset = findEndOfCentralDirectory(zipBuffer);
+    const totalEntries = zipBuffer.readUInt16LE(eocdOffset + 10);
+    const centralDirOffset = zipBuffer.readUInt32LE(eocdOffset + 16);
+    const entries = new Map();
+    let offset = centralDirOffset;
+
+    for (let index = 0; index < totalEntries; index += 1) {
+        if (zipBuffer.readUInt32LE(offset) !== CENTRAL_DIR_SIGNATURE) {
+            throw new Error('Invalid zip: central directory signature mismatch');
+        }
+
+        const compressionMethod = zipBuffer.readUInt16LE(offset + 10);
+        const compressedSize = zipBuffer.readUInt32LE(offset + 20);
+        const fileNameLength = zipBuffer.readUInt16LE(offset + 28);
+        const extraLength = zipBuffer.readUInt16LE(offset + 30);
+        const commentLength = zipBuffer.readUInt16LE(offset + 32);
+        const localHeaderOffset = zipBuffer.readUInt32LE(offset + 42);
+        const name = zipBuffer.toString('utf8', offset + 46, offset + 46 + fileNameLength);
+
+        entries.set(name, readEntryData(zipBuffer, localHeaderOffset, compressedSize, compressionMethod));
+        offset += 46 + fileNameLength + extraLength + commentLength;
+    }
+
+    return entries;
+}

package/scripts/package-superdoc-word-fixtures.ps1

@@ -0,0 +1,64 @@
+param(
+    [string]$FixturesDir = "tmp/superdoc-word-fixtures",
+    [string]$SourcesDir = "tmp/superdoc-corpus"
+)
+
+$ErrorActionPreference = 'Stop'
+Add-Type -AssemblyName System.IO.Compression
+Add-Type -AssemblyName System.IO.Compression.FileSystem
+
+function Get-UntouchedPartHashes([string]$path, [string]$changedPart) {
+    $hashes = @{}
+    $zip = [IO.Compression.ZipFile]::OpenRead($path)
+    try {
+        foreach ($entry in $zip.Entries) {
+            if ($entry.FullName -eq $changedPart) { continue }
+            $stream = $entry.Open()
+            $sha = [Security.Cryptography.SHA256]::Create()
+            try {
+                $hashes[$entry.FullName] = [BitConverter]::ToString($sha.ComputeHash($stream)).Replace('-', '').ToLowerInvariant()
+            }
+            finally {
+                $sha.Dispose()
+                $stream.Dispose()
+            }
+        }
+    }
+    finally { $zip.Dispose() }
+    return $hashes
+}
+
+$resolvedFixtures = (Resolve-Path -LiteralPath $FixturesDir).Path
+$resolvedSources = (Resolve-Path -LiteralPath $SourcesDir).Path
+$suite = Get-Content -LiteralPath (Join-Path $resolvedFixtures 'suite.json') -Raw -Encoding UTF8 | ConvertFrom-Json
+
+foreach ($case in $suite.cases) {
+    $sourcePath = Join-Path $resolvedSources "$($case.sourceId).docx"
+    $outputPath = Join-Path $resolvedFixtures "$($case.name).docx"
+    $xmlPath = Join-Path $resolvedFixtures "$($case.name).document.xml"
+    $revisionPart = if ($case.revisionPart) { [string]$case.revisionPart } else { 'word/document.xml' }
+    $before = Get-UntouchedPartHashes $sourcePath $revisionPart
+
+    Copy-Item -LiteralPath $sourcePath -Destination $outputPath -Force
+    $zip = [IO.Compression.ZipFile]::Open($outputPath, [IO.Compression.ZipArchiveMode]::Update)
+    try {
+        $oldEntry = $zip.GetEntry($revisionPart)
+        if ($null -eq $oldEntry) { throw "Missing $revisionPart in $sourcePath" }
+        $oldEntry.Delete()
+        $newEntry = $zip.CreateEntry($revisionPart, [IO.Compression.CompressionLevel]::Optimal)
+        $stream = $newEntry.Open()
+        try {
+            $bytes = [Text.UTF8Encoding]::new($false).GetBytes((Get-Content -LiteralPath $xmlPath -Raw -Encoding UTF8))
+            $stream.Write($bytes, 0, $bytes.Length)
+        }
+        finally { $stream.Dispose() }
+    }
+    finally { $zip.Dispose() }
+
+    $after = Get-UntouchedPartHashes $outputPath $revisionPart
+    if ($before.Count -ne $after.Count) { throw "$($case.name): package part count changed" }
+    foreach ($name in $before.Keys) {
+        if ($after[$name] -ne $before[$name]) { throw "$($case.name): untouched package part changed: $name" }
+    }
+    Write-Output "Packaged $($case.name) (verified $($before.Count) untouched parts)"
+}