@ansonlai/docx-redline-js 0.4.0 → 0.5.0

package/scripts/benchmark-operation-session.mjs

@@ -0,0 +1,137 @@
+import { mkdir, writeFile } from 'node:fs/promises';
+import { performance } from 'node:perf_hooks';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { configureXmlProvider, parseOoxmlSafe } from '../adapters/xml-adapter.js';
+import { configureLogger } from '../adapters/logger.js';
+import { buildTargetReferenceSnapshot } from '../core/paragraph-targeting.js';
+import {
+    applyOperationToDocumentXml,
+    applyOperationsToDocumentXml
+} from '../services/standalone-operation-runner.js';
+
+configureXmlProvider({ DOMParser, XMLSerializer });
+configureLogger({ info() {}, warn() {}, error() {} });
+
+const paragraphCount = Math.max(100, Number.parseInt(process.env.DOCX_BENCH_PARAGRAPHS || '1000', 10));
+const operationCount = Math.max(1, Number.parseInt(process.env.DOCX_BENCH_OPERATIONS || '10', 10));
+const iterations = Math.max(3, Number.parseInt(process.env.DOCX_BENCH_ITERATIONS || '7', 10));
+const warmups = Math.max(1, Number.parseInt(process.env.DOCX_BENCH_WARMUPS || '2', 10));
+const NS_W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const NS_W14 = 'http://schemas.microsoft.com/office/word/2010/wordml';
+
+const paragraphs = Array.from({ length: paragraphCount }, (_, index) => {
+    const id = (index + 1).toString(16).toUpperCase().padStart(8, '0');
+    return `<w:p w14:paraId="${id}"><w:r><w:t>Benchmark paragraph ${index + 1} with stable unique content.</w:t></w:r></w:p>`;
+}).join('');
+const source = `<w:document xmlns:w="${NS_W}" xmlns:w14="${NS_W14}"><w:body>${paragraphs}<w:sectPr/></w:body></w:document>`;
+const step = Math.max(1, Math.floor(paragraphCount / (operationCount + 1)));
+const operations = Array.from({ length: operationCount }, (_, index) => {
+    const paragraphNumber = Math.min(paragraphCount, step * (index + 1));
+    return {
+        type: 'replace',
+        target: {
+            paragraphId: paragraphNumber.toString(16).toUpperCase().padStart(8, '0'),
+            exactText: `Benchmark paragraph ${paragraphNumber} with stable unique content.`
+        },
+        modified: `Benchmark paragraph ${paragraphNumber} with verified updated content.`,
+        author: 'Session Benchmark'
+    };
+});
+
+function percentile(values, ratio) {
+    const sorted = [...values].sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.ceil(sorted.length * ratio) - 1)];
+}
+
+async function runBatch() {
+    const instrumentation = { parses: 0, serializations: 0 };
+    const heapBefore = process.memoryUsage().heapUsed;
+    const started = performance.now();
+    const result = await applyOperationsToDocumentXml(source, operations, 'Session Benchmark', null, {
+        generateRedlines: false,
+        _sessionInstrumentation: {
+            onDocumentParse: () => { instrumentation.parses += 1; },
+            onDocumentSerialize: () => { instrumentation.serializations += 1; }
+        }
+    });
+    const elapsedMs = performance.now() - started;
+    if (!result.hasChanges || result.results.some(item => item.status !== 'applied')) {
+        throw new Error('Live-session benchmark batch did not apply every operation.');
+    }
+    return {
+        elapsedMs,
+        heapDeltaBytes: process.memoryUsage().heapUsed - heapBefore,
+        outputBytes: Buffer.byteLength(result.documentXml),
+        ...instrumentation
+    };
+}
+
+async function runSequential() {
+    const parsed = parseOoxmlSafe(source, 'application/xml');
+    const context = { targetRefSnapshot: buildTargetReferenceSnapshot(parsed.doc) };
+    const instrumentation = { parses: 0, serializations: 0 };
+    const heapBefore = process.memoryUsage().heapUsed;
+    const started = performance.now();
+    let documentXml = source;
+    for (const operation of operations) {
+        const result = await applyOperationToDocumentXml(documentXml, operation, 'Session Benchmark', context, {
+            generateRedlines: false,
+            _sessionInstrumentation: {
+                onDocumentParse: () => { instrumentation.parses += 1; },
+                onDocumentSerialize: () => { instrumentation.serializations += 1; }
+            }
+        });
+        if (!result.hasChanges) throw new Error('Sequential benchmark operation did not apply.');
+        documentXml = result.documentXml;
+    }
+    return {
+        elapsedMs: performance.now() - started,
+        heapDeltaBytes: process.memoryUsage().heapUsed - heapBefore,
+        outputBytes: Buffer.byteLength(documentXml),
+        ...instrumentation
+    };
+}
+
+for (let index = 0; index < warmups; index += 1) {
+    await runBatch();
+    await runSequential();
+}
+
+const batchSamples = [];
+const sequentialSamples = [];
+for (let index = 0; index < iterations; index += 1) {
+    batchSamples.push(await runBatch());
+    sequentialSamples.push(await runSequential());
+}
+
+function summarize(samples) {
+    const timings = samples.map(sample => sample.elapsedMs);
+    return {
+        medianMs: Number(percentile(timings, 0.5).toFixed(2)),
+        p95Ms: Number(percentile(timings, 0.95).toFixed(2)),
+        medianHeapDeltaBytes: percentile(samples.map(sample => sample.heapDeltaBytes), 0.5),
+        parseCount: samples[0].parses,
+        serializeCount: samples[0].serializations,
+        outputBytes: samples[0].outputBytes
+    };
+}
+
+const batch = summarize(batchSamples);
+const sequential = summarize(sequentialSamples);
+const report = {
+    generatedAt: new Date().toISOString(),
+    environment: { node: process.version, platform: process.platform, arch: process.arch },
+    fixture: { paragraphCount, operationCount, iterations, warmups },
+    batch,
+    sequential,
+    medianSpeedup: Number((sequential.medianMs / batch.medianMs).toFixed(2)),
+    note: 'Timing and heap figures are observational. Semantic correctness tests remain the release gate.'
+};
+
+await mkdir(new URL('../tmp/benchmarks/', import.meta.url), { recursive: true });
+await writeFile(
+    new URL('../tmp/benchmarks/operation-session-latest.json', import.meta.url),
+    `${JSON.stringify(report, null, 2)}\n`,
+    'utf8'
+);
+console.log(JSON.stringify(report, null, 2));

package/scripts/benchmark-targeting-browser.html

@@ -0,0 +1,74 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <title>Paragraph targeting browser benchmark</title>
+</head>
+<body>
+  <pre id="result">Running…</pre>
+  <script type="module">
+    import {
+      buildParagraphMetadataIndex,
+      buildTargetReferenceSnapshot,
+      resolveTargetParagraph
+    } from '../core/paragraph-targeting.js';
+
+    const params = new URLSearchParams(location.search);
+    const paragraphCount = Number.parseInt(params.get('paragraphs') || '10000', 10);
+    const operationCount = Number.parseInt(params.get('operations') || '1', 10);
+    const measuredIterations = Number.parseInt(params.get('iterations') || '7', 10);
+    const warmups = 2;
+    const W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+    const W14 = 'http://schemas.microsoft.com/office/word/2010/wordml';
+    const body = Array.from({ length: paragraphCount }, (_, index) =>
+      `<w:p w14:paraId="${String(index + 1).padStart(8, '0')}"><w:r><w:t>Benchmark paragraph ${index + 1}</w:t></w:r></w:p>`
+    ).join('');
+    const xml = `<w:document xmlns:w="${W}" xmlns:w14="${W14}"><w:body>${body}<w:sectPr/></w:body></w:document>`;
+    const targets = Array.from({ length: operationCount }, (_, index) => {
+      const paragraphIndex = 1 + Math.floor(index * (paragraphCount - 1) / Math.max(1, operationCount - 1));
+      return { text: `Benchmark paragraph ${paragraphIndex}`, index: paragraphIndex };
+    });
+
+    function percentile(values, ratio) {
+      const sorted = values.slice().sort((a, b) => a - b);
+      return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * ratio))];
+    }
+
+    function measure(useCache) {
+      const doc = new DOMParser().parseFromString(xml, 'application/xml');
+      const started = performance.now();
+      const paragraphMetadataIndex = useCache ? buildParagraphMetadataIndex(doc) : null;
+      buildTargetReferenceSnapshot(doc, paragraphMetadataIndex);
+      for (const targetDescriptor of targets) {
+        resolveTargetParagraph(doc, {
+          targetDescriptor,
+          strictAmbiguity: true,
+          paragraphMetadataIndex
+        });
+      }
+      return performance.now() - started;
+    }
+
+    for (let index = 0; index < warmups; index++) {
+      measure(false);
+      measure(true);
+    }
+    const uncached = [];
+    const cached = [];
+    for (let index = 0; index < measuredIterations; index++) {
+      uncached.push(measure(false));
+      cached.push(measure(true));
+    }
+    const result = {
+      runtime: { userAgent: navigator.userAgent },
+      fixture: { paragraphCount, operationCount, warmups, measuredIterations },
+      uncachedMs: { median: percentile(uncached, 0.5), p95: percentile(uncached, 0.95) },
+      sessionCachedMs: { median: percentile(cached, 0.5), p95: percentile(cached, 0.95) }
+    };
+    result.medianSpeedup = result.uncachedMs.median / result.sessionCachedMs.median;
+    window.benchmarkResult = result;
+    document.querySelector('#result').textContent = JSON.stringify(result, null, 2);
+    document.title = 'Target benchmark complete';
+  </script>
+</body>
+</html>

package/scripts/benchmark-targeting-hot-paths.mjs

@@ -0,0 +1,67 @@
+import { performance } from 'node:perf_hooks';
+import { DOMParser, XMLSerializer } from '@xmldom/xmldom';
+import { configureXmlProvider } from '../adapters/xml-adapter.js';
+import {
+    buildParagraphMetadataIndex,
+    buildTargetReferenceSnapshot,
+    resolveTargetParagraph
+} from '../core/paragraph-targeting.js';
+
+configureXmlProvider({ DOMParser, XMLSerializer });
+
+const paragraphCount = Number.parseInt(process.env.DOCX_TARGET_BENCH_PARAGRAPHS || '10000', 10);
+const operationCount = Number.parseInt(process.env.DOCX_TARGET_BENCH_OPERATIONS || '100', 10);
+const measuredIterations = Number.parseInt(process.env.DOCX_TARGET_BENCH_ITERATIONS || '7', 10);
+const warmups = 2;
+const W = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main';
+const W14 = 'http://schemas.microsoft.com/office/word/2010/wordml';
+
+const body = Array.from({ length: paragraphCount }, (_, index) =>
+    `<w:p w14:paraId="${String(index + 1).padStart(8, '0')}"><w:r><w:t>Benchmark paragraph ${index + 1}</w:t></w:r></w:p>`
+).join('');
+const xml = `<w:document xmlns:w="${W}" xmlns:w14="${W14}"><w:body>${body}<w:sectPr/></w:body></w:document>`;
+const targets = Array.from({ length: operationCount }, (_, index) => {
+    const paragraphIndex = 1 + Math.floor(index * (paragraphCount - 1) / Math.max(1, operationCount - 1));
+    return { text: `Benchmark paragraph ${paragraphIndex}`, index: paragraphIndex };
+});
+
+function percentile(values, ratio) {
+    const sorted = values.slice().sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * ratio))];
+}
+
+function measure(useCache) {
+    const doc = new DOMParser().parseFromString(xml, 'application/xml');
+    const started = performance.now();
+    const paragraphMetadataIndex = useCache ? buildParagraphMetadataIndex(doc) : null;
+    buildTargetReferenceSnapshot(doc, paragraphMetadataIndex);
+    for (const targetDescriptor of targets) {
+        resolveTargetParagraph(doc, {
+            targetDescriptor,
+            strictAmbiguity: true,
+            paragraphMetadataIndex
+        });
+    }
+    return performance.now() - started;
+}
+
+for (let index = 0; index < warmups; index++) {
+    measure(false);
+    measure(true);
+}
+
+const uncached = [];
+const cached = [];
+for (let index = 0; index < measuredIterations; index++) {
+    uncached.push(measure(false));
+    cached.push(measure(true));
+}
+
+const result = {
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    fixture: { paragraphCount, operationCount, warmups, measuredIterations },
+    uncachedMs: { median: percentile(uncached, 0.5), p95: percentile(uncached, 0.95) },
+    sessionCachedMs: { median: percentile(cached, 0.5), p95: percentile(cached, 0.95) }
+};
+result.medianSpeedup = result.uncachedMs.median / result.sessionCachedMs.median;
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/benchmark-test-runner.mjs

@@ -0,0 +1,59 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import * as os from 'node:os';
+import { dirname, join } from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
+const measuredIterations = Number.parseInt(process.env.DOCX_TEST_BENCH_ITERATIONS || '3', 10);
+const warmups = 1;
+const parallelConcurrency = Math.max(1, Math.min(4, os.availableParallelism?.() ?? os.cpus().length));
+
+function run(concurrency) {
+    const started = performance.now();
+    const result = spawnSync(process.execPath, ['scripts/run-tests.mjs'], {
+        cwd: repoRoot,
+        env: { ...process.env, DOCX_TEST_CONCURRENCY: String(concurrency) },
+        encoding: 'utf8',
+        windowsHide: true,
+        maxBuffer: 10 * 1024 * 1024
+    });
+    if (result.status !== 0) {
+        process.stderr.write(result.stdout || '');
+        process.stderr.write(result.stderr || '');
+        throw new Error(`Test runner failed in concurrency=${concurrency} benchmark mode.`);
+    }
+    return performance.now() - started;
+}
+
+function percentile(values, ratio) {
+    const sorted = values.slice().sort((a, b) => a - b);
+    return sorted[Math.min(sorted.length - 1, Math.floor(sorted.length * ratio))];
+}
+
+for (let index = 0; index < warmups; index++) {
+    run(1);
+    run(parallelConcurrency);
+}
+
+const serial = [];
+const parallel = [];
+for (let index = 0; index < measuredIterations; index++) {
+    serial.push(run(1));
+    parallel.push(run(parallelConcurrency));
+}
+
+const result = {
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    fixture: { warmups, measuredIterations, parallelConcurrency },
+    serialMs: { median: percentile(serial, 0.5), p95: percentile(serial, 0.95), samples: serial },
+    parallelMs: { median: percentile(parallel, 0.5), p95: percentile(parallel, 0.95), samples: parallel }
+};
+result.medianSpeedup = result.serialMs.median / result.parallelMs.median;
+result.medianReductionPercent = (1 - (result.parallelMs.median / result.serialMs.median)) * 100;
+
+const outputDir = join(repoRoot, 'tmp', 'benchmarks');
+mkdirSync(outputDir, { recursive: true });
+writeFileSync(join(outputDir, 'test-runner-latest.json'), `${JSON.stringify(result, null, 2)}\n`);
+process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);

package/scripts/build-test-dashboard.mjs

@@ -38,6 +38,29 @@ if (corpusReady && suppliedCorpusFixturesDir) {
     console.warn('Run npm run test:corpus:word once to fetch and validate the pinned corpus.');
 }
 
+const lane1FixturesArgIndex = process.argv.indexOf('--lane1-fixtures-dir');
+if (lane1FixturesArgIndex >= 0 && !process.argv[lane1FixturesArgIndex + 1]) {
+    throw new Error('--lane1-fixtures-dir requires a path');
+}
+const suppliedLane1FixturesDir = lane1FixturesArgIndex >= 0;
+const lane1FixturesDir = suppliedLane1FixturesDir
+    ? resolve(repoRoot, process.argv[lane1FixturesArgIndex + 1])
+    : join(repoRoot, 'tmp', 'lane1-docx');
+
+// The dashboard is self-contained: once generated, it keeps the exact DOCX
+// bytes that were embedded at build time. Regenerate the default Lane 1
+// fixtures on every dashboard build so an existing manifest cannot pin the
+// report to an obsolete tracked document. An explicitly supplied fixture
+// directory is treated as an immutable caller-selected snapshot.
+if (!suppliedLane1FixturesDir) {
+    run('scripts/export-lane1-fixtures.mjs', ['--output-dir', lane1FixturesDir]);
+} else if (!existsSync(join(lane1FixturesDir, 'manifest.json'))) {
+    throw new Error(`Supplied Lane 1 fixture directory has no manifest.json: ${lane1FixturesDir}`);
+}
+
 const args = ['scripts/generate-test-dashboard.mjs', '--fixtures-dir', syntheticDir];
 if (corpusReady) args.push('--corpus-fixtures-dir', corpusFixturesDir);
+if (existsSync(join(lane1FixturesDir, 'manifest.json'))) {
+    args.push('--lane1-fixtures-dir', lane1FixturesDir);
+}
 run(args[0], args.slice(1));