@md2nativedocx/cli 0.0.0-stage → 0.2.1

package/src/wordCheck.mjs

@@ -0,0 +1,125 @@
+// Word compatibility check (ADR 0007 part D, TODO §R1.4). Validates the generated `.docx` against the
+// schema real Word enforces (Open XML SDK) and says, part by part, what was actually checked. It never
+// claims an effect on how Word opens the file: the validator cannot know that.
+import { execFileSync } from 'node:child_process';
+
+/** Pandoc release the "known Pandoc" signatures below were recorded against (2026-11-13). */
+export const PANDOC_SIGNATURES_VERSION = '3.1.3';
+
+// Parts only this project writes (diagrams, charts and their embedded workbooks).
+const OWN_PARTS = ['/word/diagrams/', '/word/charts/', '/word/embeddings/'];
+// Elements inside `word/document.xml` that only this project writes: the inline drawing canvas, its
+// shapes, the SmartArt/chart frames and the alternate-content wrappers around them.
+const OWN_PATH = /\/(wpc|wps|wp|a|pic|dgm|c|mc|w14|wp14):|\/w:drawing\b/;
+
+/**
+ * Known noise from Pandoc's own `.docx` writer: a closed list of signatures, each pinned to a part and to
+ * the shape of the validator message. Anything not matching is reported as an error.
+ * @type {ReadonlyArray<{ name: string, part: string, path: RegExp, description?: RegExp }>}
+ */
+const PANDOC_SIGNATURES = [
+  { name: 'syntax-highlighting styles', part: '/word/styles.xml', path: /\/w:style\[\d+\]\/w:rPr\[1\]$/, description: /unexpected child element/ },
+  { name: 'list numbering ids (w:nsid)', part: '/word/numbering.xml', path: /\/w:nsid\[1\]$/ },
+  { name: 'settings (w:doNotTrackMoves)', part: '/word/settings.xml', path: /^\/w:settings\[1\]$/, description: /doNotTrackMoves/ },
+  { name: 'table properties', part: '/word/document.xml', path: /\/w:tbl\[\d+\]\/(w:tblPr\[1\](\/w:jc\[1\])?|w:tr\[\d+\]\/w:trPr\[1\]\/w:tblHeader\[1\])$/ },
+  { name: 'list paragraph properties', part: '/word/document.xml', path: /^\/w:document\[1\]\/w:body\[1\]\/w:p\[\d+\]\/w:pPr\[1\]$/, description: /unexpected child element .*pStyle/ },
+];
+
+/**
+ * Sort validator errors into what this project writes, Pandoc's known noise, and everything else.
+ * Own output wins over a known signature, so a diagram error can never be hidden as Pandoc noise.
+ *
+ * @param {ReadonlyArray<{ Part?: string, Path?: string, Description?: string }>} errors
+ * @returns {{ own: object[], pandoc: object[], other: object[] }}
+ */
+export function classifyValidatorErrors(errors) {
+  const own = [];
+  const pandoc = [];
+  const other = [];
+  for (const e of errors) {
+    const part = e.Part ?? '';
+    const path = e.Path ?? '';
+    if (OWN_PARTS.some((p) => part.startsWith(p)) || (part === '/word/document.xml' && OWN_PATH.test(path))) {
+      own.push(e);
+    } else if (PANDOC_SIGNATURES.some((sig) => sig.part === part && sig.path.test(path) && (!sig.description || sig.description.test(e.Description ?? '')))) {
+      pandoc.push(e);
+    } else {
+      other.push(e);
+    }
+  }
+  return { own, pandoc, other };
+}
+
+/** @param {string} stdout */
+function parseReport(stdout) {
+  const report = JSON.parse(stdout.trim().split('\n').pop());
+  if (!Array.isArray(report.errors)) throw new TypeError('validator report has no errors list');
+  return { ran: true, ...classifyValidatorErrors(report.errors) };
+}
+
+/**
+ * Run the validator on `docxPath` when `MD2NATIVEDOCX_OXML_VALIDATOR_DLL` is set.
+ *
+ * Never throws: an export that already succeeded must never be reported as failed because this
+ * optional check could not run. Returns `null` when off, `{ ran: true, own, pandoc, other }`, or
+ * `{ ran: false, reason }`.
+ * @param {string} docxPath
+ */
+export function runWordCompatibilityCheck(docxPath) {
+  const dllPath = process.env.MD2NATIVEDOCX_OXML_VALIDATOR_DLL;
+  if (!dllPath) return null;
+  const dotnetBin = process.env.MD2NATIVEDOCX_DOTNET_BIN || 'dotnet';
+  try {
+    return parseReport(execFileSync(dotnetBin, [dllPath, docxPath, '--json'], { encoding: 'utf8' }));
+  } catch (err) {
+    // A non-zero exit (errorCount > 0) still wrote the JSON report to stdout first.
+    const stdout = err?.stdout?.toString();
+    if (stdout) {
+      try {
+        return parseReport(stdout);
+      } catch {
+        // Not a usable report: fall through to the "could not run" case.
+      }
+    }
+    return { ran: false, reason: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** @param {{ Path?: string, Description?: string }} e */
+const errorLine = (e) => `  - ${e.Path}: ${e.Description}`;
+
+/**
+ * Render a check result as `.log` lines: one statement per part of the document, saying what was
+ * validated and what was found, never what Word will do.
+ * @param {ReturnType<typeof runWordCompatibilityCheck>} result
+ * @returns {string[]}
+ */
+export function formatWordCompatibility(result) {
+  if (result === null) {
+    return ['Not checked (md2nativedocx.wordCompatibilityCheck is off, or this is a standalone CLI export).'];
+  }
+  if (!result.ran) return [`Not checked (could not run: ${result.reason}).`];
+
+  const lines = [];
+  lines.push(
+    result.own.length === 0
+      ? 'Diagrams and charts (written by md2nativedocx): no schema error found.'
+      : `Diagrams and charts (written by md2nativedocx): ${result.own.length} schema error(s):`,
+    ...result.own.map(errorLine),
+  );
+  const rest = [];
+  if (result.pandoc.length > 0) {
+    const names = [...new Set(PANDOC_SIGNATURES.filter((sig) => result.pandoc.some((e) => e.Part === sig.part && sig.path.test(e.Path ?? ''))).map((sig) => sig.name))];
+    rest.push(`${result.pandoc.length} known schema deviation(s) written by Pandoc itself (${names.join('; ')}; signatures recorded with Pandoc ${PANDOC_SIGNATURES_VERSION}).`);
+  }
+  if (result.other.length > 0) {
+    rest.push(`${result.other.length} other schema error(s):`);
+  }
+  lines.push(
+    rest.length === 0 ? 'Rest of the document (written by Pandoc): no schema error found.' : `Rest of the document (written by Pandoc): ${rest.shift()}`,
+    ...rest,
+    ...result.other.map(errorLine),
+  );
+  lines.push('This is a validation against the Open XML schema; it does not predict how Word will behave.');
+  return lines;
+}

package/src/writeOutputSafely.mjs

@@ -0,0 +1,69 @@
+// Safe output writing (TODO §R1.1). Word keeps an exclusive handle on an open document and drops a
+// `~$` lock file beside it; overwriting under it (notably on OneDrive) corrupts or loses the file.
+// This module refuses in those cases, and otherwise swaps the new file in atomically so the previous
+// target is never truncated.
+import { closeSync, existsSync, fsyncSync, openSync, renameSync, rmSync, writeSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+import { ConversionError } from './convert.mjs';
+
+/**
+ * Names of the lock files Word creates for `fileName`: `~$` + the full name, and, for long names,
+ * `~$` + the name without its first 2 characters.
+ * @param {string} fileName
+ * @returns {string[]}
+ */
+export function wordLockFileNames(fileName) {
+  return [...new Set([`~$${fileName}`, `~$${fileName.slice(2)}`])];
+}
+
+/** @param {string} message @param {unknown} [cause] */
+function writeError(message, cause) {
+  return new ConversionError(message, { stage: 'write', cause });
+}
+
+/**
+ * Write `data` to `target` without ever truncating an existing file.
+ *
+ * Refuses (throws a {@link ConversionError} with `stage: 'write'`) when a Word lock file sits beside the
+ * target, or when the existing target cannot be opened for writing. Otherwise writes
+ * `<target>.<pid>.tmp` in the same folder, fsyncs it, and renames it over the target; the temporary is
+ * removed on failure.
+ *
+ * @param {string} target absolute output path
+ * @param {Buffer | string} data
+ */
+export function writeOutputSafely(target, data) {
+  const dir = dirname(target);
+  const name = basename(target);
+
+  for (const lock of wordLockFileNames(name)) {
+    if (existsSync(join(dir, lock))) {
+      throw writeError(`${name} is open in Word: close it or export under another name.`);
+    }
+  }
+
+  if (existsSync(target)) {
+    try {
+      closeSync(openSync(target, 'r+'));
+    } catch (err) {
+      throw writeError(`${name} cannot be overwritten (it is probably open in Word or another program): close it or export under another name.`, err);
+    }
+  }
+
+  const tmp = `${target}.${process.pid}.tmp`;
+  let fd;
+  try {
+    fd = openSync(tmp, 'w');
+    writeSync(fd, data);
+    fsyncSync(fd);
+    closeSync(fd);
+    fd = undefined;
+    renameSync(tmp, target);
+  } catch (err) {
+    if (fd !== undefined) {
+      try { closeSync(fd); } catch { /* already failing; the original error is the one to report */ }
+    }
+    rmSync(tmp, { force: true });
+    throw writeError(`could not write ${name}: ${err instanceof Error ? err.message : String(err)}`, err);
+  }
+}

package/src/zipUtils.mjs

@@ -0,0 +1,38 @@
+/**
+ * Small AdmZip helpers shared by `referenceDocBuilder.mjs` and
+ * `postprocess.mjs` — both patch a handful of named entries inside an
+ * existing `.docx` (itself a zip archive) while leaving every other part
+ * byte-for-byte untouched.
+ *
+ * Replaces this project's former `execFileSync('unzip'/'zip', ...)` calls:
+ * neither binary exists on stock Windows, and since `md2nativedocx.
+ * layout.pageSize`/`.orientation` default to non-empty values
+ * (`buildReferenceDoc`'s `needsSectPr`), that path ran on *every* export —
+ * confirmed 2026-09-08 by a from-scratch Windows test machine where the
+ * very first export crashed with `spawnSync unzip ENOENT`, misclassified as
+ * "Pandoc missing" (see exportService.ts's `runCli` for that separate fix).
+ */
+import AdmZip from 'adm-zip';
+
+export { AdmZip };
+
+/** Read a text entry from `zip`, throwing a clear error if it's missing —
+ * mirrors the old code's behaviour of a `readFileSync` on a temp file that
+ * `unzip` had failed to extract. */
+export function readZipEntry(zip, entryName) {
+  const buf = zip.readFile(entryName);
+  if (!buf) throw new Error(`md2nativedocx: missing ${entryName} in the .docx archive`);
+  return buf.toString('utf8');
+}
+
+/** Add `entryName` if it isn't already present, otherwise replace its
+ * content. `AdmZip#updateFile` silently no-ops on an entry that doesn't
+ * exist yet, so a plain `updateFile` isn't safe for entries this project
+ * adds for the first time (e.g. `word/footer1.xml`, new SmartArt diagram
+ * parts) — found while porting away from `zip`, which handles both cases
+ * transparently. */
+export function setZipEntry(zip, entryName, content) {
+  const buf = Buffer.isBuffer(content) ? content : Buffer.from(content, 'utf8');
+  if (zip.getEntry(entryName)) zip.updateFile(entryName, buf);
+  else zip.addFile(entryName, buf);
+}