@helping-ai-workflow/md2doc 3.3.0 → 3.4.2

package/README.md

@@ -1,6 +1,6 @@
 # @helping-ai-workflow/md2doc
 
-> Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support.
+> Markdown → HTML / PDF renderer with WaveDrom, Mermaid, Graphviz, and draw.io support.
 
 A single global CLI (`md2doc`) you can call from any directory.
 
@@ -8,7 +8,9 @@ A single global CLI (`md2doc`) you can call from any directory.
 
 Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
 
-Chromium is only needed for **PDF export** and the optional `--bake-svg` flag. HTML diagram rendering needs nothing extra — Graphviz runs in-process via WebAssembly, and Mermaid / WaveDrom are bundled and inlined, so diagrams render **offline with no system Graphviz and no CDN**.
+Chromium is needed for **PDF export**, for the optional `--bake-svg` flag, and for **`.drawio` diagrams**, which are always rendered to SVG at generation time. Everything else needs nothing extra — Graphviz runs in-process via WebAssembly, and Mermaid / WaveDrom are bundled and inlined.
+
+Nothing is fetched at render time or at read time: every engine, including the vendored draw.io viewer, runs locally, so documents render and read **offline with no system Graphviz, no draw.io install and no CDN**.
 
 ### Recommended: install via nvm
 
@@ -100,8 +102,8 @@ in several places grows the HTML accordingly. PDF output is unaffected.
 
 ### Viewing diagrams
 
-Click any image, Mermaid, Graphviz or WaveDrom graphic in the rendered HTML to open it
-full-screen.
+Click any image, Mermaid, Graphviz, draw.io or WaveDrom graphic in the rendered HTML to
+open it full-screen.
 
 | Input | Action |
 |---|---|
@@ -280,7 +282,7 @@ version-control-friendly.
 ### Degraded blocks: code, diagrams, images, math
 
 Blocks containing content WYSIWYG cannot represent (code fences, Mermaid/Graphviz/
-WaveDrom diagrams, images, LaTeX math, or unstyled HTML) automatically degrade to
+WaveDrom/draw.io diagrams, images, LaTeX math, or unstyled HTML) automatically degrade to
 raw-edit mode: click the block to open the raw Markdown source in a textarea, make
 your changes, then press `Ctrl+Enter` to commit or `Esc` to cancel.
 
@@ -372,9 +374,19 @@ digraph G { A -> B }
 ```
 ````
 
-All three render directly in the output (HTML or PDF), **offline and with no system dependencies**: Graphviz `dot` runs in-process via WebAssembly (no system `dot` binary required), and Mermaid / WaveDrom are bundled and inlined (no CDN). Each engine's runtime is embedded only when the document actually uses that diagram type.
+A fourth engine, **draw.io**, is referenced with image syntax rather than a code fence, because a `.drawio` file is an external artifact rather than inline source:
+
+```markdown
+![Architecture overview](arch.drawio)
+![Just the Flow sheet](arch.drawio#Flow)
+![Just the second sheet](arch.drawio#2)
+```
+
+A `.xml` file is treated as a diagram only when its root element really is `<mxfile>` or `<mxGraphModel>`; anything else falls through to the ordinary image path unchanged. `#Name` selects a sheet by name, `#N` by 1-based position (a name wins over a number). The alt text becomes the rendered box's accessible name. Multi-sheet files get a small sheet bar on hover — every sheet is baked into the output, so switching sheets involves no engine.
+
+All four render directly in the output (HTML or PDF), **offline and with no system dependencies**: Graphviz `dot` runs in-process via WebAssembly (no system `dot` binary required), Mermaid / WaveDrom are bundled and inlined (no CDN), and `.drawio` files are rendered by a vendored draw.io viewer running in a build-time headless Chromium. Each engine's runtime is embedded only when the document actually uses that diagram type — and the draw.io viewer never is, at any size, because `.drawio` diagrams are fully pre-rendered (a multi-sheet document carries only a few lines of sheet-switching script, not an engine).
 
-By default, Mermaid and WaveDrom render in the browser when the HTML is opened; pass `--bake-svg` to pre-render them to inert SVG at generation time instead (Graphviz is always pre-rendered to SVG).
+By default, Mermaid and WaveDrom render in the browser when the HTML is opened; pass `--bake-svg` to pre-render them to inert SVG at generation time instead (Graphviz and draw.io are always pre-rendered to SVG).
 
 ## Why a global CLI
 
@@ -382,4 +394,17 @@ Multiple repos used to ship copies of this script. They drifted. This package ce
 
 ## Licence
 
-MIT.
+md2doc's own source is **MIT** — see [`LICENSE`](LICENSE).
+
+The published package is not MIT-only, because it ships one vendored
+third-party file: `vendor/drawio/viewer-static.min.js`, the draw.io /
+diagrams.net viewer (v31.3.2, ~4 MB), under the **Apache License 2.0**.
+Its licence text and a per-component NOTICE travel with it, in
+[`vendor/drawio/LICENSE`](vendor/drawio/LICENSE) and
+[`vendor/drawio/NOTICE`](vendor/drawio/NOTICE).
+
+**Running a licence scan? Start at
+[`THIRD-PARTY-NOTICES.md`](THIRD-PARTY-NOTICES.md).** It lists everything
+redistributed inside the tarball, including the components bundled inside
+the draw.io viewer itself (DOMPurify, pako, spin.js, Rough.js), and says
+how each finding was established.

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,44 @@
+# Third-party notices
+
+md2doc's own source code is licensed under the MIT License — see
+[`LICENSE`](LICENSE). `"license": "MIT"` in `package.json` refers to that
+code and only to that code.
+
+**The published npm package also contains code that is not md2doc's and
+is not MIT.** If you are running a licence scan, this is the file you
+want; the per-component detail is one level down, next to the artifact it
+describes.
+
+## Vendored at rest (inside the published tarball)
+
+| Path | What | Licence | Detail |
+|---|---|---|---|
+| `vendor/drawio/viewer-static.min.js` | draw.io / diagrams.net viewer, v31.3.2, 4,151,717 bytes | **Apache License 2.0** | [`vendor/drawio/LICENSE`](vendor/drawio/LICENSE), [`vendor/drawio/NOTICE`](vendor/drawio/NOTICE) |
+
+That single 4 MB file is a verbatim copy of
+`src/main/webapp/js/viewer-static.min.js` from
+[jgraph/drawio](https://github.com/jgraph/drawio) at tag `v31.3.2`
+(sha256 `2fabaaa3e28d5f80f943285a2ce19c22cf870857203255f1e0347ef93693a297`).
+md2doc executes it only inside a build-time headless Chromium, to turn
+`.drawio` references into inline SVG; it is never emitted into output
+HTML and never fetched over the network.
+
+The Apache-2.0 text ships **inside `vendor/drawio/`**, next to the file it
+covers, rather than only at the repository root — so it survives being
+copied, vendored or extracted along with the artifact.
+
+That bundle is itself not licence-homogeneous. It contains DOMPurify
+3.4.13 (Apache-2.0 OR MPL-2.0), pako 2.2.0 (MIT AND Zlib), spin.js 2.0.0
+(MIT) and Rough.js 4.6.6 (MIT).
+[`vendor/drawio/NOTICE`](vendor/drawio/NOTICE) records each one's version,
+licence, where inside the bundle it sits, **how that was established**,
+and which of those findings rest on provenance rather than on a
+declaration in the artifact itself.
+
+## Runtime dependencies (installed by npm, not vendored)
+
+md2doc's `dependencies` (marked, mermaid, wavedrom, katex, puppeteer,
+turndown, `@hpcc-js/wasm-graphviz`) are ordinary npm packages: they are
+resolved into your `node_modules` by your own installer, carry their own
+licence files there, and are not redistributed inside md2doc's tarball.
+They are out of scope for this file.

package/lib/drawio.js

@@ -0,0 +1,178 @@
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+// drawio (.drawio / .xml) 來源的判別與頁面解析。
+//
+// 這一支刻意不碰 marked、不碰瀏覽器 —— 判別與頁名是純字串處理，可以用純函式
+// 測；真的需要 headless Chromium 的只有 bakeDrawioSvg()（見同檔下方）。
+//
+// 為什麼不用 XML parser：md2doc 不引進新的 runtime 依賴，而這裡要回答的問題
+// （根元素是什麼、有哪些 <diagram name>）用受控的 regex 就夠。輸入是本機檔案
+// 而不是網路內容，且判別失敗的後果是「當成普通圖片、原樣留著」——不是安全邊界。
+
+// 開頭的 XML 宣告、DOCTYPE、註解、空白都要跳過，才看得到真正的根元素。
+const LEADING_NOISE = /^(?:\s|<\?[\s\S]*?\?>|<!--[\s\S]*?-->|<!DOCTYPE[^>]*>)*/;
+
+// 根元素判別：兩處（isDrawioXml / pageNamesOf）共用同一顆函式，避免各自維護
+// 一份「跳過前導雜訊」的 regex 而在 DOCTYPE / 自我封閉標籤上悄悄長歪。
+//
+// 標籤後面接的字元用 `[\s\/>]` 而不是 `[\s>]`：自我封閉的 `<mxfile/>` 或
+// `<mxGraphModel/>`（沒有任何屬性、也沒有子節點）在真實檔案裡少見，但一旦
+// 出現，`[\s>]` 會因為下一個字元是 `/` 而漏判成「不是 drawio」——用
+// `foo(root, 'not a diagram')` 這種輸入實測會踩到。同時要擋掉
+// `<mxfilex>` / `<mxGraphModelFoo>` 這種前綴相同、但其實是別的標籤的輸入，
+// 所以字元類仍然是白名單而不是「以 mxfile 開頭就算」。
+function rootKindOf(text) {
+  const rest = String(text || '').replace(LEADING_NOISE, '');
+  if (/^<mxfile[\s\/>]/.test(rest)) return 'mxfile';
+  if (/^<mxGraphModel[\s\/>]/.test(rest)) return 'mxGraphModel';
+  return null;
+}
+
+function isDrawioXml(text) {
+  return rootKindOf(text) !== null;
+}
+
+function pageNamesOf(text) {
+  const s = String(text || '');
+  if (rootKindOf(s) !== 'mxfile') {
+    // <mxGraphModel> 直接當一頁，沒有名字。
+    return [''];
+  }
+  const names = [];
+  const re = /<diagram\b([^>]*)>/g;
+  let m;
+  while ((m = re.exec(s)) !== null) {
+    const nameAttr = /\bname\s*=\s*"([^"]*)"/.exec(m[1]);
+    names.push(nameAttr ? nameAttr[1] : '');
+  }
+  return names.length ? names : [''];
+}
+
+function resolvePageIndex(names, fragment) {
+  const frag = String(fragment == null ? '' : fragment);
+  if (!frag) return 0;
+  const byName = names.indexOf(frag);
+  if (byName >= 0) return byName;
+  if (/^\d+$/.test(frag)) {
+    const n = Number(frag);
+    if (n >= 1 && n <= names.length) return n - 1;
+  }
+  return 0;
+}
+
+// v3.4.0 batch2 Task 6 fix round 1 (review F7) — the identity of a referenced
+// `.drawio`/`.xml` file's bytes AS THIS PROCESS LAST SAW THEM.
+//
+// (mtimeMs, size) rather than mtimeMs alone: this project's own environment
+// notes document a filesystem (WSL DrvFs over /mnt/c) that degrades and
+// behaves oddly around timestamps, and coarse-granularity mtimes are also the
+// norm on SMB shares — a rewrite landing inside the same tick as the recorded
+// one compares equal and is never reported. Size costs nothing extra (the
+// Stats object is already in hand) and closes that hole for every edit that
+// changes the file's length.
+//
+// Returns null when the file cannot be stat'd at all. That deliberately
+// collapses "deleted" and "unreadable" (EACCES, an editor's atomic-replace
+// window) into one value: for staleness they are the same answer — "the bytes
+// you baked are no longer the bytes on disk" — and the caller has no repair
+// action that would differ between them. The cost is diagnostic only.
+function drawioStampOf(absPath) {
+  try {
+    const st = fs.statSync(absPath);
+    return String(st.mtimeMs) + '/' + String(st.size);
+  } catch (e) {
+    return null;
+  }
+}
+
+const VIEWER_PATH = path.join(__dirname, '..', 'vendor', 'drawio', 'viewer-static.min.js');
+
+// 每一頁烤成一份 SVG。
+//
+// 為什麼是 headless Chromium 而不是 Node 裡的某個函式庫：drawio 的版面
+// 計算（自動換行、文字度量、stencil 形狀）依賴真正的瀏覽器排版引擎，
+// 沒有等價的 Node 實作。md2doc 已經有 puppeteer（PDF 匯出在用），所以這
+// 不是新依賴。
+//
+// 遠端路徑預設值必須在 viewer 載入之前就改寫掉。viewer 自己的寫法是
+// `window.PROXY_URL = window.PROXY_URL || "https://viewer.diagrams.net/proxy"`
+// 這種形式 —— `||` 代表先設好的值會勝出，所以 addScriptTag 之前先 evaluate。
+//
+// 數字要講清楚，因為下面那份清單看起來很像「全部」：viewer 裡這種形狀的
+// 遠端預設值共有 14 個（11 個指向 diagrams.net、3 個指向 github/gitlab），
+// 下面只中和了靜態渲染路徑真的會讀到的 8 個，外加 2 個載入旗標。沒中和的
+// 6 個（EXPORT_URL、VSS_CONVERT_URL、DRAWIO_LIGHTBOX_URL、DRAWIO_GITHUB_URL、
+// DRAWIO_GITHUB_API_URL、DRAWIO_GITLAB_URL）屬於匯出／格式轉換／git 整合功能，
+// GraphViewer.createViewerForElement() 這條路不會叫到它們。
+//
+// 所以「輸出離線可用」這個保證**不是**靠這份清單完整，而是靠 test/drawio.test.js
+// 對產出斷言沒有任何遠端 URL。要加功能而動到 viewer 的其他能力時，先重新量，
+// 不要假設這 8 個就是全部。
+async function bakeDrawioSvg(xmlText, opts) {
+  const o = opts || {};
+  const names = pageNamesOf(xmlText);
+  let browser = o.browser;
+  let ownBrowser = false;
+  if (!browser) {
+    const puppeteer = require('puppeteer');
+    browser = await puppeteer.launch({
+      headless: 'new',
+      args: ['--no-sandbox', '--disable-setuid-sandbox',
+             '--disable-crash-reporter', '--disable-dev-shm-usage'],
+    });
+    ownBrowser = true;
+  }
+  const page = await browser.newPage();
+  try {
+    await page.setContent('<!doctype html><html><body></body></html>');
+    await page.evaluate(() => {
+      // 全部指向 about:blank 之下的相對路徑：viewer 取不到就用內建的
+      // 基本形狀，而不是去打網路。md2doc 的輸出必須離線可用。
+      window.PROXY_URL = '';
+      window.STYLE_PATH = '';
+      window.SHAPES_PATH = '';
+      window.STENCIL_PATH = '';
+      window.DRAW_MATH_URL = '';
+      window.GRAPH_IMAGE_PATH = '';
+      window.mxImageBasePath = '';
+      window.mxBasePath = '';
+      window.mxLoadStylesheets = false;
+      window.mxLoadResources = false;
+    });
+    await page.addScriptTag({ path: VIEWER_PATH });
+
+    const out = [];
+    for (let i = 0; i < names.length; i++) {
+      const svg = await page.evaluate((xml, pageIndex) => {
+        const el = document.createElement('div');
+        el.className = 'mxgraph';
+        // width 不設會讓 GraphViewer 把圖縮到容器寬度。
+        el.setAttribute('data-mxgraph', JSON.stringify({
+          xml: xml, page: pageIndex, highlight: '#0000ff',
+          toolbar: null, resize: true, nav: false,
+        }));
+        document.body.appendChild(el);
+        window.GraphViewer.createViewerForElement(el);
+        const svgEl = el.querySelector('svg');
+        const html = svgEl ? svgEl.outerHTML : null;
+        el.remove();
+        return html;
+      }, xmlText, i);
+
+      if (!svg) {
+        throw new Error('drawio viewer produced no SVG for page ' + (i + 1) +
+          ' (' + (names[i] || 'unnamed') + ')');
+      }
+      out.push(svg);
+    }
+    return out;
+  } finally {
+    await page.close();
+    if (ownBrowser) await browser.close();
+  }
+}
+
+module.exports = { isDrawioXml, pageNamesOf, resolvePageIndex, bakeDrawioSvg, drawioStampOf };

package/lib/editor/blockmap.js

@@ -12,6 +12,79 @@ function trimmedLineCount(raw) {
   return content === '' ? 1 : content.split('\n').length;
 }
 
+// v3.4.0 (backlog #13, closing the "改動前後相同" observation for real):
+// MEASURED on marked 14.1.4, a top-level 'paragraph' token's `raw` can carry
+// an internal newline that names NO real blank line in the source. Minimal
+// case: 'a\n\tb\n---\n- x\n- y\n\ntail\n' — the paragraph's raw comes back as
+// 'a\n\n\tb\n' (3 newlines) for what is 2 real source lines ('a', a TAB- or
+// >=4-space-over-indented lazy continuation 'b'); every block from the '---'
+// onward then names the line ABOVE its real one. This is not "only literal
+// '---'" — a table SEPARATOR row immediately after the same over-indented
+// continuation ('|---|', ':---') reproduces it too, and the trigger tracks
+// the count of over-indented continuation lines, not any single terminator
+// (see runs/task11-item13-scope-hunt*.js: 195+ cases across continuation
+// width x repeat-count x fifteen terminators — corruption only where the
+// line right after the continuation is dash/equals-shaped, matching
+// whatever internal check marked runs to decide a following line MIGHT be a
+// setext-heading underline; every other terminator tried — the other hr
+// markers, headings, blockquotes, fences, header-led tables, lists, a
+// genuine setext '===' — left raw uncorrupted in every case). A 'heading'
+// token was TRIED as a second covered type (it goes through the same marked
+// code path — setext heading construction IS this ambiguity's positive
+// case) and REJECTED: test/blockmap.test.js's own first fixture ('# Title\n\n
+// Para one.\n\n…') broke immediately, because ATX headings legitimately FOLD
+// a trailing blank-line run into their own raw when nothing else does (raw
+// '# Title\n\n' for a heading followed by one blank line, with no separate
+// 'space' token) — exactly the behaviour this file's own header comment
+// documents ("A token's raw may include trailing newlines … folded in").
+// `t.text` for a heading is just its own single line of prose ("Title", 0
+// newlines) and has no way to reconstruct how many blank lines got folded
+// after it, so text-based counting silently DROPS that fold and lands the
+// next block one line early. Paragraphs do not fold trailing blanks this way
+// (MEASURED: a blank-line run after a paragraph always comes back as its own
+// separate 'space' token, at EOF and mid-document alike — see
+// runs/task11-item13-parafold.js), which is exactly why paragraphs are safe
+// to cover here and headings are not.
+//
+// This file's own item-level code already named the general family: a lazy
+// continuation's `text`-token raw is SYNTHESISED ("a lazy continuation comes
+// back as \"x\n\ncont\n\" (three newlines) for two source lines" — see
+// childListStartOffsets()'s header comment), which is why that code never
+// trusts a `text` token's raw for cursor advancement. This is the same
+// defence at buildBlockMap()'s TOP level, where a top-level 'paragraph' is
+// marked's equivalent of an in-item lazy continuation — the top level had no
+// corresponding defence because the header comment's own stated basis for
+// trusting top-level raws ("at top level the raws are faithful source
+// slices") is exactly the assumption this case disproves.
+//
+// The fix does not detect corruption and fall back conditionally; it simply
+// never counts newlines out of a 'paragraph' token's `raw` at all. `t.text`
+// — marked's own dedented join of the token's real content lines, e.g.
+// "a\nb" for the fixture above — was MEASURED to stay correct in every
+// corrupted case found in the sweep: its newline count always equals (real
+// source lines consumed - 1), carrying none of the synthetic blank lines
+// `raw` picks up. And on every UNCORRUPTED case, `text`-based and
+// `raw`-based counting agree exactly — MEASURED via a direct before/after
+// diff of buildBlockMap()'s own OUTPUT (not just the raw newline count) over
+// every fixture already in test/blockmap.test.js plus a 60000-document
+// random line-soup fuzz corpus (see runs/task11-item13-fuzz-oracle.js and
+// the report) — so there is no accuracy cost paid on the common path.
+//
+// Every OTHER top-level token type is left on the original raw-based
+// computation, unconditionally: the sweep found no corruption outside
+// 'paragraph', and 'space' tokens in particular NEED their raw's FULL,
+// untrimmed newline count (to skip a multi-blank-line run) — trimmedLineCount()
+// or text-based counting would get that case wrong on purpose, not by
+// oversight.
+function topLevelLineInfo(t) {
+  if (t.type === 'paragraph' && typeof t.text === 'string') {
+    const contentNewlines = (t.text.match(/\n/g) || []).length;
+    const endsWithNewline = t.raw.charAt(t.raw.length - 1) === '\n';
+    return { span: contentNewlines + 1, rawNewlines: contentNewlines + (endsWithNewline ? 1 : 0) };
+  }
+  return { span: trimmedLineCount(t.raw), rawNewlines: (t.raw.match(/\n/g) || []).length };
+}
+
 // Recursively emit one `li` block per list item at every depth.
 // Recursion order (mirrored by Task 4's render walk):
 //   1. Push the item's own block.
@@ -304,23 +377,23 @@ function buildBlockMap(mdText) {
   let cursor = 1; // current line number of the token's first character
   const nextId = { v: 0 };
   for (const t of tokens) {
-    const rawNewlines = (t.raw.match(/\n/g) || []).length;
+    const info = topLevelLineInfo(t);
     if (t.type === 'list') {
       pushListItemBlocks(t, cursor, 0, blocks, nextId);
     } else if (t.type !== 'space') {
-      const content = t.raw.replace(/\n+$/, '');
-      const span = content === '' ? 1 : content.split('\n').length;
       blocks.push({
         id: nextId.v++,
         type: t.type,
         startLine: cursor,
-        endLine: cursor + span - 1,
+        endLine: cursor + info.span - 1,
       });
     }
-    // advance by full raw (including folded trailing blank lines).
+    // advance by full raw (including folded trailing blank lines) for every
+    // type except 'paragraph'/'heading', which use topLevelLineInfo()'s
+    // text-based count instead — see its own comment for why.
     // If raw has no trailing newline (EOF), the next token doesn't exist,
     // so the off-by-one is unobservable.
-    cursor += rawNewlines;
+    cursor += info.rawNewlines;
   }
   return { blocks, lineCount: mdText.split('\n').length };
 }