@md2nativedocx/cli 0.0.0-stage → 0.1.0

package/src/convert.d.mts

@@ -0,0 +1,91 @@
+/**
+ * Types of `@md2nativedocx/cli`'s library entry point (`convert.mjs`). Hand-written: the package is plain
+ * JavaScript with no build step. Keep in step with `convert.mjs` and `envOptions.mjs`.
+ */
+
+/** Page and typography of the bundled reference document. Ignored under {@link ConvertOptions.referenceDoc}. */
+export interface LayoutOptions {
+  /** `A3`, `A4` (default), `Letter`, `Legal`… An unknown value falls back to A4. */
+  pageSize?: string;
+  /** `portrait` (default) or `landscape`. */
+  orientation?: string;
+  /** Word's presets: `normal` (default), `narrow`, `moderate`, `wide`. */
+  margins?: string;
+  /** Custom margins in centimetres; each side overrides the preset. */
+  marginsCustomCm?: { top?: number; right?: number; bottom?: number; left?: number };
+  headingFont?: string;
+  bodyFont?: string;
+  /** Body text size in points. */
+  fontSizePt?: number;
+  /** `single`, `1.15`, `1.5`, `double`; anything else keeps the template's spacing. */
+  lineSpacing?: string;
+  /** `both`, `right` or `center`; anything else leaves body text left-aligned. */
+  justify?: string;
+  /** Theme accent colour, `RRGGBB`. */
+  accentColor?: string;
+  /** Table header fill, `RRGGBB`. */
+  tableHeaderColor?: string;
+  /** A centred page number in the footer. */
+  footerPageNumber?: boolean;
+  /** Put each heading immediately followed by a table in its own landscape section. */
+  landscapeTables?: boolean;
+}
+
+/** How {@link convert} builds the document. Every field is optional; the defaults match the CLI's. */
+export interface ConvertOptions {
+  /** Pandoc's working directory, against which relative image paths resolve. Default: `process.cwd()`. */
+  cwd?: string;
+  /** A `.docx` template to use instead of the bundled one (Pandoc's `--reference-doc`). Must exist. */
+  referenceDoc?: string;
+  layout?: LayoutOptions;
+  /** A table of contents after the title, refreshed when Word opens the file. Default `false`. */
+  toc?: boolean;
+  /** Heading levels in the table of contents, 2 to 4. Default 3. */
+  tocDepth?: number;
+  /** Force a colour emoji font on emoji runs. Default `true`. */
+  emojiFont?: boolean;
+  /** SmartArt for the diagrams that can be one. Default `true`. */
+  smartArt?: boolean;
+  /** SmartArt look; unknown values fall back to `colorful`. */
+  smartArtStyle?: string;
+  /** Ship the pre-rendered SmartArt drawing, so Word and LibreOffice show the same geometry. Default `true`. */
+  smartArtDrawing?: boolean;
+  /** Native Word charts for `pie` / `xychart` / `radar`: `true` (default), `false`, or the types to chart. */
+  nativeCharts?: boolean | readonly string[];
+  /** Largest diagram width in EMU. Default: the page's usable width. */
+  maxDrawingCx?: number;
+  /** Largest diagram height in EMU. Default: the page's usable height. */
+  maxDrawingCy?: number;
+  /** Pandoc executable. Default `pandoc`, looked up on `PATH`. */
+  pandocBin?: string;
+  /** Node executable the Lua filter runs the diagram bridge with. Default: `process.execPath`. */
+  nodeBin?: string;
+}
+
+/** A finished document. */
+export interface ConvertResult {
+  /** The `.docx` file's bytes. */
+  document: Buffer;
+  /** Non-fatal problems in the diagrams (syntax ignored, a SmartArt or chart drawn as shapes instead). */
+  warnings: string[];
+  /** Everything Pandoc and the filter wrote to stderr, for a log. */
+  pandocStderr: string;
+}
+
+/** A conversion that produced no document. */
+export declare class ConversionError extends Error {
+  /** `setup`: filter or reference document · `pandoc`: Pandoc failed or is missing · `postprocess`. */
+  readonly stage: 'setup' | 'pandoc' | 'postprocess';
+  /** Pandoc's stderr, when it ran. */
+  readonly pandocStderr: string;
+}
+
+/**
+ * Convert a Markdown document to `.docx`: Pandoc with the md2nativedocx filter, every ```mermaid block as
+ * editable Word shapes, SmartArt or a native chart. Needs Pandoc installed. Never reads `MD2NATIVEDOCX_*`
+ * environment variables: behavior comes from `options` only.
+ *
+ * @param source Markdown text, or `{ path }` of a file for Pandoc to read (`.qmd` is read as Markdown).
+ * @throws {ConversionError} when no document could be produced.
+ */
+export declare function convert(source: string | { path: string }, options?: ConvertOptions): Promise<ConvertResult>;

package/src/convert.mjs

@@ -0,0 +1,202 @@
+/**
+ * `convert()`: Markdown in, finished `.docx` bytes out (docs/specs/01-v2-engine-spec.md §6, ADR 0012).
+ *
+ * The library entry point of `@md2nativedocx/cli`, and what `bin/md2nativedocx.mjs` itself calls. It owns
+ * the whole document path: reference document build, Pandoc with the Lua filter (which renders each
+ * ```mermaid block through `renderDiagram()`), post-processing, SmartArt and chart part injection. It
+ * lives here and not in `core` because it runs Pandoc (AGENTS.md: core knows nothing about Pandoc).
+ *
+ * Behavior comes from {@link ConvertOptions} only. Every inherited `MD2NATIVEDOCX_*` variable is removed
+ * from the environment Pandoc and the filter see, then the ones the filter and the bridge read are set from
+ * the options, so a host process's environment cannot change a conversion behind its caller's back. The
+ * variables remain the CLI's interface (`envOptions.mjs` reads them).
+ *
+ * Security (AGENTS.md): Pandoc runs through `execFile` with an argument array (rule 4); every file is written
+ * in a fresh temporary directory removed afterwards; the post-processing is the rule 7 allowlist.
+ */
+
+import { execFile } from 'node:child_process';
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { postProcessDocx, injectSmartArtParts } from './postprocess.mjs';
+import { injectChartParts } from './chartParts.mjs';
+import { buildReferenceDoc, resolveMaxDrawingExtentEmu, resolvePageSize, resolveMargins } from './referenceDocBuilder.mjs';
+
+/** A conversion that produced no document. `stage` says where it stopped. */
+export class ConversionError extends Error {
+  /**
+   * @param {string} message
+   * @param {{ stage: 'setup' | 'pandoc' | 'postprocess', pandocStderr?: string, cause?: unknown }} details
+   */
+  constructor(message, { stage, pandocStderr = '', cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'ConversionError';
+    this.stage = stage;
+    this.pandocStderr = pandocStderr;
+  }
+}
+
+// Custom reference.docx (Word's current default look: Aptos font scheme, modern "Office" theme colors,
+// non-bold flat heading hierarchy) instead of Pandoc's own bundled default, which is still the original
+// 2007-2010 Office theme. See packages/cli/assets/README.md for how it was built and what it changes.
+// `src/` and `bin/` are at the same depth, so this also holds in the VS Code extension's vendored bundle.
+const DEFAULT_REFERENCE_DOC = fileURLToPath(new URL('../assets/reference.docx', import.meta.url));
+
+/**
+ * Where @md2nativedocx/pandoc-filter lands varies with how the CLI was deployed (npm workspace, nested or
+ * flat install, the VS Code extension's vendored copy). import.meta.resolve() is Node's own resolution
+ * algorithm, so it finds it in every case without guessing directory depths.
+ */
+function resolveFilterPath() {
+  try {
+    return fileURLToPath(import.meta.resolve('@md2nativedocx/pandoc-filter/md2nativedocx.lua'));
+  } catch (err) {
+    throw new ConversionError(`could not locate @md2nativedocx/pandoc-filter: ${errorMessage(err)}`, { stage: 'setup', cause: err });
+  }
+}
+
+function errorMessage(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/** `MD2NATIVEDOCX_NATIVE_CHARTS` as the bridge reads it, or `null` for charts off. */
+function nativeChartsEnv(setting) {
+  if (setting === undefined || setting === true) return '1';
+  if (setting === false || (Array.isArray(setting) && setting.length === 0)) return null;
+  return setting.join(',');
+}
+
+/** The environment Pandoc runs with: the caller's, minus `MD2NATIVEDOCX_*`, plus what `options` says. */
+function pandocEnvironment(options, { smartArtDir, chartDir, maxDrawingExtentEmu, landscapeGeometry }) {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.startsWith('MD2NATIVEDOCX_')));
+  if (smartArtDir) env.MD2NATIVEDOCX_SMARTART_DIR = smartArtDir;
+  if (options.smartArtStyle !== undefined) env.MD2NATIVEDOCX_SMARTART_STYLE = options.smartArtStyle;
+  if (options.smartArtDrawing === false) env.MD2NATIVEDOCX_SMARTART_DRAWING = '0';
+  if (chartDir) {
+    env.MD2NATIVEDOCX_CHART_DIR = chartDir;
+    env.MD2NATIVEDOCX_NATIVE_CHARTS = nativeChartsEnv(options.nativeCharts);
+  }
+  // md2nativedocx.lua needs it on Windows (no shebang handling there, so it cannot run a bare .mjs). Our
+  // own interpreter is always Node: a system Node, or the VS Code extension's Electron run as Node.
+  env.MD2NATIVEDOCX_NODE_BIN = options.nodeBin ?? process.execPath;
+  // An explicit drawing cap wins over the page-derived one (e.g. a diagram meant for a half-width cell).
+  const cx = options.maxDrawingCx ?? (maxDrawingExtentEmu ? Math.round(maxDrawingExtentEmu.cx) : undefined);
+  const cy = options.maxDrawingCy ?? (maxDrawingExtentEmu ? Math.round(maxDrawingExtentEmu.cy) : undefined);
+  if (cx !== undefined) env.MD2NATIVEDOCX_MAX_DRAWING_CX = String(cx);
+  if (cy !== undefined) env.MD2NATIVEDOCX_MAX_DRAWING_CY = String(cy);
+  if (landscapeGeometry) {
+    env.MD2NATIVEDOCX_LANDSCAPE_TABLES = '1';
+    env.MD2NATIVEDOCX_PAGE_W_TWIPS = String(landscapeGeometry.pgSize.w);
+    env.MD2NATIVEDOCX_PAGE_H_TWIPS = String(landscapeGeometry.pgSize.h);
+    env.MD2NATIVEDOCX_MARGIN_TOP_TWIPS = String(landscapeGeometry.margins.top);
+    env.MD2NATIVEDOCX_MARGIN_RIGHT_TWIPS = String(landscapeGeometry.margins.right);
+    env.MD2NATIVEDOCX_MARGIN_BOTTOM_TWIPS = String(landscapeGeometry.margins.bottom);
+    env.MD2NATIVEDOCX_MARGIN_LEFT_TWIPS = String(landscapeGeometry.margins.left);
+  }
+  return env;
+}
+
+function runPandoc(bin, args, { cwd, env }) {
+  return new Promise((resolvePromise, reject) => {
+    execFile(bin, args, { cwd, env, maxBuffer: 64 * 1024 * 1024 }, (err, _stdout, stderr) => {
+      if (err) {
+        reject(new ConversionError(`Pandoc failed (exit ${err.code ?? '?'})`, { stage: 'pandoc', pandocStderr: stderr ?? '', cause: err }));
+      } else {
+        resolvePromise(stderr ?? '');
+      }
+    });
+  });
+}
+
+/**
+ * Lines this project wrote to stderr (`md2nativedocx: ...`: parser warnings, SmartArt or chart fallbacks,
+ * from each bridge run the Lua filter spawned), without that prefix. Pandoc's own diagnostics share the
+ * stream but are not ours to count.
+ */
+function extractWarnings(stderrText) {
+  return stderrText
+    .split('\n')
+    .filter((line) => line.startsWith('md2nativedocx: ') && line.trim().length > 0)
+    .map((line) => line.slice('md2nativedocx: '.length));
+}
+
+/**
+ * Convert a Markdown document to `.docx`. See `convert.d.mts` for the option and result types.
+ *
+ * @param {string | { path: string }} source Markdown text, or a file for Pandoc to read (its extension picks
+ *   the reader; `.qmd` is read as Markdown).
+ * @param {import('./convert.d.mts').ConvertOptions} [options]
+ * @returns {Promise<import('./convert.d.mts').ConvertResult>}
+ */
+export async function convert(source, options = {}) {
+  const filterPath = resolveFilterPath();
+  const cwd = options.cwd ?? process.cwd();
+  const customReferenceDoc = options.referenceDoc;
+  if (customReferenceDoc !== undefined && !existsSync(customReferenceDoc)) {
+    throw new ConversionError(`reference document not found: ${customReferenceDoc}`, { stage: 'setup' });
+  }
+  // A custom reference document wins outright: its page setup is unknown, so page/typography options are
+  // not patched into it (spec §2.1, option (a)).
+  const layout = customReferenceDoc ? {} : (options.layout ?? {});
+
+  const work = mkdtempSync(join(tmpdir(), 'md2nativedocx-convert-'));
+  let generatedReferenceDoc = null;
+  try {
+    try {
+      generatedReferenceDoc = customReferenceDoc ? null : buildReferenceDoc(DEFAULT_REFERENCE_DOC, layout);
+    } catch (err) {
+      throw new ConversionError(`reference document setup failed: ${errorMessage(err)}`, { stage: 'setup', cause: err });
+    }
+    const referenceDoc = customReferenceDoc ?? generatedReferenceDoc?.path ?? DEFAULT_REFERENCE_DOC;
+
+    let inputPath;
+    if (typeof source === 'string') {
+      inputPath = join(work, 'input.md');
+      writeFileSync(inputPath, source, 'utf8');
+    } else {
+      inputPath = source.path;
+    }
+    const outputPath = join(work, 'output.docx');
+
+    const pandocArgs = [inputPath, '-o', outputPath, '--lua-filter', filterPath];
+    // Pandoc picks its reader from the extension and does not know `.qmd`; Quarto Markdown is Pandoc
+    // Markdown plus front matter and code chunks, so naming the reader is correct and drops its warning.
+    if (extname(inputPath).toLowerCase() === '.qmd') pandocArgs.push('--from', 'markdown');
+    if (existsSync(referenceDoc)) pandocArgs.push('--reference-doc', referenceDoc);
+    const tocDepth = Math.min(4, Math.max(2, Math.round(options.tocDepth ?? 3)));
+    if (options.toc) pandocArgs.push('--toc', `--toc-depth=${tocDepth}`);
+
+    // The bridge (one run per ```mermaid block, spawned by the Lua filter) hands SmartArt and chart parts
+    // back through these directories: a Lua filter cannot add package parts itself.
+    const smartArtDir = options.smartArt !== false ? mkdtempSync(join(work, 'smartart-')) : null;
+    const chartDir = nativeChartsEnv(options.nativeCharts) !== null ? mkdtempSync(join(work, 'chart-')) : null;
+    const env = pandocEnvironment(options, {
+      smartArtDir,
+      chartDir,
+      // Usable page area for the translator, whether or not the reference document needed a patch.
+      maxDrawingExtentEmu: customReferenceDoc ? null : resolveMaxDrawingExtentEmu(layout),
+      // The filter's "back to portrait" section needs the document's actual page geometry.
+      landscapeGeometry: layout.landscapeTables
+        ? { pgSize: resolvePageSize(layout.pageSize, layout.orientation), margins: resolveMargins(layout.margins, layout.marginsCustomCm) }
+        : null,
+    });
+
+    const pandocStderr = await runPandoc(options.pandocBin ?? 'pandoc', pandocArgs, { cwd, env });
+
+    try {
+      // Namespaces and drawing ids first: the SmartArt and chart injection read the fixed document.xml.
+      postProcessDocx(outputPath, { toc: Boolean(options.toc), emojiFont: options.emojiFont !== false });
+      if (smartArtDir) injectSmartArtParts(outputPath, smartArtDir);
+      if (chartDir) injectChartParts(outputPath, chartDir);
+    } catch (err) {
+      throw new ConversionError(`post-processing failed: ${errorMessage(err)}`, { stage: 'postprocess', pandocStderr, cause: err });
+    }
+
+    return { document: readFileSync(outputPath), warnings: extractWarnings(pandocStderr), pandocStderr };
+  } finally {
+    rmSync(work, { recursive: true, force: true });
+    if (generatedReferenceDoc) rmSync(generatedReferenceDoc.dir, { recursive: true, force: true });
+  }
+}

package/src/envOptions.mjs

@@ -0,0 +1,88 @@
+/**
+ * The `MD2NATIVEDOCX_*` environment variables, read into {@link convert}'s typed options.
+ *
+ * The variables stay the CLI's configuration interface: the VS Code extension's `exportService.ts` sets
+ * them from its settings, and a standalone user can set them by hand. Only this adapter reads them
+ * (docs/specs/01-v2-engine-spec.md §8); `convert()` itself never looks at the environment.
+ *
+ * Variables the CLI sets for the Lua filter and the bridge (`_SMARTART_DIR`, `_CHART_DIR`, `_NODE_BIN`,
+ * `_PAGE_*_TWIPS`, `_MARGIN_*_TWIPS`) are not inputs and are not read here.
+ */
+
+import { existsSync } from 'node:fs';
+
+/** Whether any page/typography option is set (they are ignored under a custom reference document). */
+export function hasLayoutOptions(layout) {
+  return Object.values(layout ?? {}).some((v) => v !== undefined);
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} env
+ * @returns {import('./convert.d.mts').ConvertOptions}
+ */
+export function readConvertOptionsFromEnv(env) {
+  const str = (name) => {
+    const v = env[name];
+    return v && v.trim() !== '' ? v.trim() : undefined;
+  };
+  const num = (name) => {
+    const v = env[name];
+    if (v === undefined || v.trim() === '') return undefined;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : undefined;
+  };
+  const positiveInt = (name) => {
+    const n = Number.parseInt(env[name] ?? '', 10);
+    return Number.isFinite(n) && n > 0 ? n : undefined;
+  };
+
+  const marginsCustomCm = {
+    top: num('MD2NATIVEDOCX_MARGINS_CUSTOM_TOP'),
+    right: num('MD2NATIVEDOCX_MARGINS_CUSTOM_RIGHT'),
+    bottom: num('MD2NATIVEDOCX_MARGINS_CUSTOM_BOTTOM'),
+    left: num('MD2NATIVEDOCX_MARGINS_CUSTOM_LEFT'),
+  };
+  const layout = {
+    pageSize: str('MD2NATIVEDOCX_PAGE_SIZE'),
+    orientation: str('MD2NATIVEDOCX_ORIENTATION'),
+    margins: str('MD2NATIVEDOCX_MARGINS'),
+    marginsCustomCm: Object.values(marginsCustomCm).some((v) => v !== undefined) ? marginsCustomCm : undefined,
+    headingFont: str('MD2NATIVEDOCX_HEADING_FONT'),
+    bodyFont: str('MD2NATIVEDOCX_BODY_FONT'),
+    fontSizePt: num('MD2NATIVEDOCX_FONT_SIZE'),
+    lineSpacing: str('MD2NATIVEDOCX_LINE_SPACING'),
+    justify: str('MD2NATIVEDOCX_JUSTIFY'),
+    accentColor: str('MD2NATIVEDOCX_ACCENT_COLOR'),
+    tableHeaderColor: str('MD2NATIVEDOCX_TABLE_HEADER_COLOR'),
+    footerPageNumber: env.MD2NATIVEDOCX_FOOTER_PAGE_NUMBER === '1' ? true : undefined,
+    landscapeTables: env.MD2NATIVEDOCX_LANDSCAPE_TABLES === '1' ? true : undefined,
+  };
+
+  // Unset or `1`: every chartable type; `0`: none; otherwise a comma-separated list of types.
+  const chartsRaw = (env.MD2NATIVEDOCX_NATIVE_CHARTS ?? '').trim();
+  const nativeCharts = chartsRaw === '' || chartsRaw === '1' ? true : chartsRaw === '0' ? false : chartsRaw.split(',').map((t) => t.trim());
+
+  const tocDepth = Number(env.MD2NATIVEDOCX_TOC_DEPTH);
+  // A reference document that does not exist is ignored (the bundled one is used), as it always was.
+  const referenceDoc = env.MD2NATIVEDOCX_REFERENCE_DOC && existsSync(env.MD2NATIVEDOCX_REFERENCE_DOC) ? env.MD2NATIVEDOCX_REFERENCE_DOC : undefined;
+
+  /** @type {import('./convert.d.mts').ConvertOptions} */
+  const options = {
+    layout,
+    toc: env.MD2NATIVEDOCX_TOC === '1',
+    emojiFont: env.MD2NATIVEDOCX_EMOJI_FONT !== '0',
+    // SmartArt and native charts are on by default, as in the VS Code extension; `0` turns them off.
+    smartArt: env.MD2NATIVEDOCX_ENABLE_SMARTART !== '0',
+    smartArtDrawing: env.MD2NATIVEDOCX_SMARTART_DRAWING !== '0',
+    nativeCharts,
+  };
+  if (Number.isFinite(tocDepth)) options.tocDepth = tocDepth;
+  if (referenceDoc) options.referenceDoc = referenceDoc;
+  if (env.MD2NATIVEDOCX_SMARTART_STYLE !== undefined) options.smartArtStyle = env.MD2NATIVEDOCX_SMARTART_STYLE;
+  const maxDrawingCx = positiveInt('MD2NATIVEDOCX_MAX_DRAWING_CX');
+  const maxDrawingCy = positiveInt('MD2NATIVEDOCX_MAX_DRAWING_CY');
+  if (maxDrawingCx !== undefined) options.maxDrawingCx = maxDrawingCx;
+  if (maxDrawingCy !== undefined) options.maxDrawingCy = maxDrawingCy;
+  if (env.MD2NATIVEDOCX_PANDOC_BIN) options.pandocBin = env.MD2NATIVEDOCX_PANDOC_BIN;
+  return options;
+}