@ansonlai/docx-redline-js 0.2.0 → 0.4.0

package/scripts/inspect-visual-evidence.mjs

@@ -0,0 +1,271 @@
+import { existsSync, mkdirSync, readFileSync } from 'fs';
+import { dirname, join, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { execFileSync } from 'child_process';
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const pythonVenvExe = join(repoRoot, 'tmp', 'visual-qa-venv', 'Scripts', 'python.exe');
+
+export function loadManifest(manifestPath) {
+    if (!existsSync(manifestPath)) {
+        return null;
+    }
+    let content = readFileSync(manifestPath, 'utf8');
+    if (content.charCodeAt(0) === 0xFEFF) {
+        content = content.slice(1);
+    }
+    return JSON.parse(content);
+}
+
+export function inspectManifest(manifest, baseDir) {
+    const results = {
+        totalCases: 0,
+        renderedCases: 0,
+        passedCases: 0,
+        anomalies: [],
+        caseSummaries: []
+    };
+
+    if (!manifest || !Array.isArray(manifest.cases)) {
+        return results;
+    }
+
+    results.totalCases = manifest.cases.length;
+
+    for (const testCase of manifest.cases) {
+        const caseName = testCase.name || testCase.identity;
+        const views = testCase.views || {};
+        let caseRendered = true;
+        let caseValid = true;
+        const viewDetails = {};
+
+        for (const viewName of ['allMarkup', 'acceptAll', 'rejectAll']) {
+            const viewInfo = views[viewName];
+            if (!viewInfo || viewInfo.status !== 'rendered') {
+                caseRendered = false;
+                caseValid = false;
+                continue;
+            }
+
+            const pdfFileName = viewInfo.pdf;
+            const pdfPath = join(baseDir, pdfFileName);
+            const exists = existsSync(pdfPath);
+            const pages = viewInfo.pages;
+            const bytes = viewInfo.bytes;
+
+            viewDetails[viewName] = { exists, pages, bytes };
+
+            if (!exists) {
+                results.anomalies.push({
+                    caseName,
+                    view: viewName,
+                    reason: `Missing PDF file: ${pdfFileName}`
+                });
+                caseValid = false;
+            } else if (!bytes || bytes < 1000) {
+                results.anomalies.push({
+                    caseName,
+                    view: viewName,
+                    reason: `Suspiciously small PDF size: ${bytes} bytes`
+                });
+                caseValid = false;
+            } else if (!pages || pages < 1) {
+                results.anomalies.push({
+                    caseName,
+                    view: viewName,
+                    reason: `Invalid page count: ${pages}`
+                });
+                caseValid = false;
+            }
+        }
+
+        if (caseRendered) {
+            results.renderedCases++;
+        }
+
+        // Layout sanity check between acceptAll and rejectAll
+        const acceptPages = viewDetails.acceptAll?.pages;
+        const rejectPages = viewDetails.rejectAll?.pages;
+        if (acceptPages !== undefined && rejectPages !== undefined) {
+            const pageDiff = Math.abs(acceptPages - rejectPages);
+            if (pageDiff > 2 && acceptPages > 0 && rejectPages > 0) {
+                results.anomalies.push({
+                    caseName,
+                    reason: `Unusual page count disparity: acceptAll=${acceptPages} vs rejectAll=${rejectPages}`
+                });
+                caseValid = false;
+            }
+        }
+
+        if (caseValid) {
+            results.passedCases++;
+        }
+
+        results.caseSummaries.push({
+            name: caseName,
+            status: caseValid ? 'valid' : 'flagged',
+            rendered: caseRendered,
+            views: viewDetails
+        });
+    }
+
+    return results;
+}
+
+export function generateContactSheetWithPyMuPdf(pdfPath, outputPngPath, maxPages = 20) {
+    if (!existsSync(pythonVenvExe)) {
+        return false;
+    }
+
+    const pythonScript = `
+import sys
+import fitz # PyMuPDF
+from PIL import Image
+
+pdf_path = sys.argv[1]
+output_png = sys.argv[2]
+max_pages = int(sys.argv[3]) if len(sys.argv) > 3 else 20
+
+doc = fitz.open(pdf_path)
+page_count = min(len(doc), max_pages)
+
+# Render pages as pixmaps
+images = []
+for i in range(page_count):
+    page = doc.load_page(i)
+    pix = page.get_pixmap(dpi=72)
+    img = Image.frombytes("RGB", [pix.width, pix.height], pix.samples)
+    images.append(img)
+
+doc.close()
+
+if not images:
+    sys.exit(1)
+
+# Tile into contact sheet grid (up to 5 columns)
+cols = min(5, len(images))
+rows = (len(images) + cols - 1) // cols
+page_w, page_h = images[0].size
+sheet = Image.new("RGB", (cols * page_w, rows * page_h), color=(240, 240, 240))
+
+for idx, img in enumerate(images):
+    c = idx % cols
+    r = idx // cols
+    sheet.paste(img, (c * page_w, r * page_h))
+
+sheet.save(output_png)
+print("Saved contact sheet:", output_png)
+`;
+
+    try {
+        execFileSync(pythonVenvExe, ['-c', pythonScript, pdfPath, outputPngPath, String(maxPages)], {
+            stdio: 'pipe',
+            encoding: 'utf8'
+        });
+        return true;
+    } catch (e) {
+        return false;
+    }
+}
+
+function runCli() {
+    console.log('=== Word Visual Evidence Inspection ===\n');
+
+    const syntheticDir = join(repoRoot, 'tmp', 'word-visual-review', 'rendered');
+    const syntheticManifestPath = join(syntheticDir, 'manifest.json');
+    const corpusDir = join(repoRoot, 'tmp', 'superdoc-word-visual-review', 'rendered');
+    const corpusManifestPath = join(corpusDir, 'manifest.json');
+
+    let totalCases = 0;
+    let totalRendered = 0;
+    let totalValid = 0;
+    let totalAnomalies = 0;
+
+    // Check synthetic lane
+    const syntheticManifest = loadManifest(syntheticManifestPath);
+    if (syntheticManifest) {
+        const syntheticResults = inspectManifest(syntheticManifest, syntheticDir);
+        console.log(`Synthetic Word Visual Evidence (${syntheticDir}):`);
+        console.log(`  Word Version: ${syntheticManifest.word?.version || 'unknown'} (Build: ${syntheticManifest.word?.build || 'unknown'})`);
+        console.log(`  Total Cases: ${syntheticResults.totalCases}`);
+        console.log(`  Rendered Cases: ${syntheticResults.renderedCases}`);
+        console.log(`  Valid Cases: ${syntheticResults.passedCases}`);
+        if (syntheticResults.anomalies.length > 0) {
+            console.log('  Anomalies:');
+            for (const a of syntheticResults.anomalies) {
+                console.log(`    - [${a.caseName}] ${a.view ? a.view + ': ' : ''}${a.reason}`);
+            }
+        }
+        console.log('');
+        totalCases += syntheticResults.totalCases;
+        totalRendered += syntheticResults.renderedCases;
+        totalValid += syntheticResults.passedCases;
+        totalAnomalies += syntheticResults.anomalies.length;
+    } else {
+        console.log(`Synthetic lane manifest not found at ${syntheticManifestPath}\n  Run: npm run test:word:visual\n`);
+    }
+
+    // Check corpus lane
+    const corpusManifest = loadManifest(corpusManifestPath);
+    if (corpusManifest) {
+        const corpusResults = inspectManifest(corpusManifest, corpusDir);
+        console.log(`SuperDoc Real-Document Visual Evidence (${corpusDir}):`);
+        console.log(`  Word Version: ${corpusManifest.word?.version || 'unknown'} (Build: ${corpusManifest.word?.build || 'unknown'})`);
+        console.log(`  Total Cases: ${corpusResults.totalCases}`);
+        console.log(`  Rendered Cases: ${corpusResults.renderedCases}`);
+        console.log(`  Valid Cases: ${corpusResults.passedCases}`);
+        if (corpusResults.anomalies.length > 0) {
+            console.log('  Anomalies:');
+            for (const a of corpusResults.anomalies) {
+                console.log(`    - [${a.caseName}] ${a.view ? a.view + ': ' : ''}${a.reason}`);
+            }
+        }
+        console.log('');
+        totalCases += corpusResults.totalCases;
+        totalRendered += corpusResults.renderedCases;
+        totalValid += corpusResults.passedCases;
+        totalAnomalies += corpusResults.anomalies.length;
+    } else {
+        console.log(`SuperDoc corpus manifest not found at ${corpusManifestPath}\n  Run: npm run test:corpus:word:visual\n`);
+    }
+
+    console.log(`Summary: ${totalRendered}/${totalCases} rendered, ${totalValid} valid, ${totalAnomalies} anomalies.\n`);
+
+    if (process.argv.includes('--contact-sheets')) {
+        console.log('Generating visual review contact sheets...');
+        const sheetsDir = join(repoRoot, 'tmp', 'word-visual-review', 'inspected-sheets');
+        mkdirSync(sheetsDir, { recursive: true });
+
+        let generated = 0;
+        if (syntheticManifest) {
+            for (const c of syntheticManifest.cases.slice(0, 10)) {
+                for (const [viewName, viewInfo] of Object.entries(c.views)) {
+                    const pdfPath = join(syntheticDir, viewInfo.pdf);
+                    const outPath = join(sheetsDir, `synthetic--${c.name}--${viewName}.png`);
+                    if (existsSync(pdfPath)) {
+                        const success = generateContactSheetWithPyMuPdf(pdfPath, outPath, 10);
+                        if (success) generated++;
+                    }
+                }
+            }
+        }
+        if (corpusManifest) {
+            for (const c of corpusManifest.cases.slice(0, 10)) {
+                for (const [viewName, viewInfo] of Object.entries(c.views)) {
+                    const pdfPath = join(corpusDir, viewInfo.pdf);
+                    const outPath = join(sheetsDir, `superdoc--${c.scenarioKey || c.name}--${viewName}.png`);
+                    if (existsSync(pdfPath)) {
+                        const success = generateContactSheetWithPyMuPdf(pdfPath, outPath, 10);
+                        if (success) generated++;
+                    }
+                }
+            }
+        }
+        console.log(`Generated ${generated} visual contact sheets in ${sheetsDir}`);
+    }
+}
+
+const isCli = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+    runCli();
+}

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));
 }