@alfacapital-tech/c4builder 0.3.0-rc.1 → 0.3.0-rc.2

package/dist/core/compose/markdown.js

@@ -5,8 +5,9 @@ import { createRequire } from 'node:module';
 import defaultDocsifyTemplate from "./docsify.template.js";
 import { encodeURIPath, readFile, writeFile, plantUmlServerUrl } from "../../util/utils.js";
 import { VENDOR_DIR } from "../../util/paths.js";
-// Фаза scan: тип дерева и его элементов + производные (имя папки, формат выхода диаграммы).
-import { getFolderName, diagramOutputFormat } from "../scan/tree.js";
+// Фаза scan: тип дерева и его элементов + производные (имя папки, формат выхода диаграммы)
+// и единый реестр расширений диаграмм (источник истины для regex ссылок ниже).
+import { getFolderName, diagramOutputFormat, DIAGRAM_ENGINES, engineSupportsRemote } from "../scan/tree.js";
 // Фаза render: mime-тип формата и загрузка удалённо отрендеренной картинки (embed-ветка).
 import { getMime, httpGet } from "../render/diagrams.js";
 // docsifyTemplate можно переопределить пользовательским шаблоном (см. generateWebMD),
@@ -34,27 +35,101 @@ const injectAfterFirstH1 = (md, block) => {
         return `${block}\n\n${md}`;
     return m[1] + block + md.slice(m[1].length);
 };
+// Расширения диаграмм без точки, экранированные для regex. Источник истины — реестр
+// DIAGRAM_ENGINES из фазы scan (scan/tree.ts): добавление движка там автоматически
+// расширяет regex ссылок здесь, без синхронной правки. Экранируем на случай спецсимволов.
+const diagramExtAlternation = () => DIAGRAM_ENGINES.map((e) => e.ext.slice(1).replace(/[.*+?^${}()|[\]\\]/g, '\\$&')).join('|');
+// Ссылка на диаграмму в markdown: ![alt](path.puml|d2). Путь ленивый и не пересекает ')',
+// иначе две ссылки на одной строке склеились бы в один матч и не заменились. Свежий объект
+// на вызов — чтобы matchAll не тянул чужой lastIndex.
+const diagramRefRegex = () => new RegExp(`!\\[.*?\\]\\(([^)]*?\\.(?:${diagramExtAlternation()}))\\)`, 'g');
+// Кеш base64 отрендеренных диаграмм на время ОДНОЙ сборки: один файл читают все три
+// генератора (per-page md / docsify / complete). clearDiagramCache() зовётся в начале build() —
+// иначе в watch-режиме (build() вызывается повторно) вернулись бы данные до правки файла.
+const diagramBase64Cache = new Map();
+export const clearDiagramCache = () => diagramBase64Cache.clear();
+const readDiagramBase64 = async (absPath) => {
+    const cached = diagramBase64Cache.get(absPath);
+    if (cached !== undefined)
+        return cached;
+    const b64 = (await readFile(absPath)).toString('base64');
+    diagramBase64Cache.set(absPath, b64);
+    return b64;
+};
+// Тот же кеш для embed-ветки онлайн-рендера (ключ — URL, с абсолютными путями не
+// пересекается): три генератора иначе тянули бы одну и ту же картинку с PlantUML-сервера
+// трижды за сборку.
+const readRemoteDiagramBase64 = async (url) => {
+    const cached = diagramBase64Cache.get(url);
+    if (cached !== undefined)
+        return cached;
+    const b64 = await httpGet(url);
+    diagramBase64Cache.set(url, b64);
+    return b64;
+};
+// Единый рендер markdown одной диаграммы для всех трёх генераторов. В complete-документе
+// ссылки «скачать/перейти» префиксуются папкой элемента, а Download отбивается переводом
+// строки (историческая вёрстка). Признак — variant, а не пустота префикса: у диаграмм в
+// корневой папке префикс пуст, и complete всё равно обязан отбить ссылку.
+const buildDiagramMarkdown = async (item, diagram, options, variant) => {
+    const isComplete = variant === 'complete';
+    const name = path.parse(diagram.dir).name;
+    const format = diagramOutputFormat(diagram, options);
+    // rawPath — сырой путь (для чтения файла и как основа ссылок), кодируем ровно один раз.
+    const rawPath = path.join(path.dirname(diagram.dir), `${name}.${format}`);
+    // Онлайн-рендер (движки с remoteRender в DIAGRAM_ENGINES) отдаёт абсолютный URL
+    // сервера: его нельзя ни префиксовать папкой, ни повторно кодировать (encodeURI
+    // сломал бы схему https:// и '+' в base64).
+    const isRemoteUrl = !options.GENERATE_LOCAL_IMAGES && engineSupportsRemote(diagram.engine);
+    const diagramUrl = isRemoteUrl
+        ? plantUmlServerUrl(options.PLANTUML_SERVER_URL, format, diagram.content // рендер-контент диаграммы (Buffer читается как текст)
+        )
+        : encodeURIPath(rawPath);
+    // В complete-документе И картинка, И ссылка «скачать/перейти» префиксуются папкой
+    // элемента: complete.md лежит в корне dist, а картинки — во вложенных папках, поэтому
+    // относительный путь считается от корня. Склеиваем СЫРЫЕ сегменты и кодируем один раз
+    // (иначе % из первого encodeURI превратился бы в %25). Абсолютный URL онлайн-рендера
+    // отдаём как есть — без папки и без повторного encodeURI. В page-варианте md лежит
+    // рядом с картинкой, поэтому путь остаётся относительным к странице (diagramUrl).
+    const localHref = isComplete && !isRemoteUrl
+        ? encodeURIPath(path.join(item.dir.replace(options.ROOT_FOLDER, ''), rawPath))
+        : diagramUrl;
+    if (options.EMBED_DIAGRAM) {
+        const imgContent = options.GENERATE_LOCAL_IMAGES
+            ? await readDiagramBase64(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), rawPath))
+            : await readRemoteDiagramBase64(diagramUrl);
+        const diagramImage = `\n![${name}](data:${getMime(format)};base64,${imgContent})\n`;
+        const diagramLink = `${isComplete ? '\n' : ''}[Download ${name} diagram](${localHref} ':ignore')`;
+        return diagramImage + diagramLink;
+    }
+    const diagramImage = `![diagram](${localHref})`;
+    if (!options.INCLUDE_LINK_TO_DIAGRAM)
+        return diagramImage;
+    return `[Go to ${name} diagram](${localHref})`;
+};
 const compileDocument = async (md, item, options, getDiagram) => {
     let MD = md;
     const alreadyIncluded = [];
     const texts = [];
     const diagrams = [];
-    const regex = /(?:!\[.*?\]\()(.*\.(?:puml|d2))(\))/g;
+    const regex = diagramRefRegex();
     for (const mdFile of item.mdFiles) {
-        let content = mdFile.toString();
-        let diagramRef;
-        // biome-ignore lint/suspicious/noAssignInExpressions: идиома regex.exec() в условии while
-        while ((diagramRef = regex.exec(content)) !== null) {
-            if (diagramRef?.[1]) {
-                const ref = diagramRef[1]; // const → сужение держится в замыкании .find
-                const diagram = item.diagrams.find((x) => x.dir === ref);
-                if (diagram) {
-                    alreadyIncluded.push(ref);
-                    content = content.replace(diagramRef[0], await getDiagram(item, diagram, options));
-                }
-            }
+        const content = mdFile.toString();
+        // Один проход matchAll + сборка из срезов: каждая ссылка заменяется ровно один раз.
+        // (Прежний regex.exec + переприсваивание content пропускал ссылки при укорачивающей замене.)
+        let result = '';
+        let lastIndex = 0;
+        for (const m of content.matchAll(regex)) {
+            const ref = m[1];
+            const diagram = item.diagrams.find((x) => x.dir === ref);
+            if (!diagram)
+                continue; // ссылка без соответствующей диаграммы — оставляем сырой markdown
+            alreadyIncluded.push(ref);
+            result += content.slice(lastIndex, m.index) + (await getDiagram(item, diagram, options));
+            lastIndex = m.index + m[0].length;
         }
-        texts.push(content);
+        result += content.slice(lastIndex);
+        texts.push(result);
     }
     for (const diagram of item.diagrams) {
         if (alreadyIncluded.find((x) => x === diagram.dir)) {
@@ -64,7 +139,15 @@ const compileDocument = async (md, item, options, getDiagram) => {
     }
     let fullDoc = [];
     if (options.DIAGRAMS_ON_TOP) {
-        fullDoc = [...diagrams, ...texts];
+        // Пользовательский h1 обязан оставаться самым первым: при diagramsOnTop диаграммы
+        // иначе встают ВЫШЕ заголовка страницы. Отделяем ведущий h1 первого текста и держим
+        // его перед диаграммами (chrome вставляется под него caller'ом), остальное тело —
+        // после. Ведущего h1 нет (авто-заголовок) → прежний порядок diagrams → texts.
+        const [firstText = '', ...restTexts] = texts;
+        const h1 = firstText.match(/^(?\s*#\s+[^\n]*)\n?([\s\S]*)$/);
+        fullDoc = h1
+            ? [h1[1], ...diagrams, h1[2], ...restTexts].filter((s) => s !== '')
+            : [...diagrams, ...texts];
     }
     else {
         fullDoc = [...texts, ...diagrams];
@@ -75,6 +158,24 @@ const compileDocument = async (md, item, options, getDiagram) => {
     }
     return MD;
 };
+// Якорь заголовка в complete-документе (докcифай/GitHub-стиль: пробелы → дефисы).
+const mdAnchor = (name) => `#${encodeURIPath(name).replace(/%20/g, '-')}`;
+// Относительная ссылка со страницы уровня fromLevel на README целевой папки
+// (rootRel — путь цели от ROOT_FOLDER). Один паттерн для TOC, навигации вверх и
+// меню подпапок — прежде дублировался трижды.
+const relativeMdLink = (fromLevel, rootRel, mdFileName) => encodeURIPath(path.join('./', fromLevel - 1 > 0 ? '../'.repeat(fromLevel - 1) : '', rootRel, `${mdFileName}.md`));
+// Тело страницы (титул + контент с диаграммами) — общий скелет generateMD и
+// generateWebMD. chrome (breadcrumbs/TOC/навигация) встаёт под заголовок: при
+// авто-титуле — сразу за ним, при пользовательском h1 — пост-вставкой после него.
+const compilePage = async (item, options, chrome = '') => {
+    const name = getFolderName(item.dir, options.ROOT_FOLDER, options.HOMEPAGE_NAME);
+    const ownH1 = hasOwnH1(item);
+    let MD = ownH1 ? '' : `# ${name}${chrome}`;
+    MD = await compileDocument(MD, item, options, (i, d, o) => buildDiagramMarkdown(i, d, o, 'page'));
+    if (ownH1)
+        MD = injectAfterFirstH1(MD, chrome);
+    return MD.trimStart();
+};
 export const generateCompleteMD = async (tree, options) => {
     const filePromises = [];
     //title
@@ -82,7 +183,7 @@ export const generateCompleteMD = async (tree, options) => {
     //table of contents
     let tableOfContents = '';
     for (const item of tree)
-        tableOfContents += `${'  '.repeat(item.level - 1)}* [${item.name}](#${encodeURIPath(item.name).replace(/%20/g, '-')})\n`;
+        tableOfContents += `${'  '.repeat(item.level - 1)}* [${item.name}](${mdAnchor(item.name)})\n`;
     MD += `\n\n${tableOfContents}\n---`;
     for (const item of tree) {
         const name = getFolderName(item.dir, options.ROOT_FOLDER, options.HOMEPAGE_NAME);
@@ -91,35 +192,12 @@ export const generateCompleteMD = async (tree, options) => {
         if (name !== options.HOMEPAGE_NAME) {
             if (options.INCLUDE_BREADCRUMBS)
                 MD += `\n\n\`${item.dir.replace(options.ROOT_FOLDER, '')}\``;
-            MD += `\n\n[${options.HOMEPAGE_NAME}](#${encodeURIPath(options.PROJECT_NAME).replace(/%20/g, '-')})`;
+            MD += `\n\n[${options.HOMEPAGE_NAME}](${mdAnchor(options.PROJECT_NAME)})`;
         }
         //concatenate markdown files
-        MD = await compileDocument(MD, item, options, async (item, diagram, options) => {
-            let diagramUrl = encodeURIPath(path.join(path.dirname(diagram.dir), `${path.parse(diagram.dir).name}.${diagramOutputFormat(diagram, options)}`));
-            if (!options.GENERATE_LOCAL_IMAGES && diagram.engine === 'plantuml')
-                diagramUrl = plantUmlServerUrl(options.PLANTUML_SERVER_URL, diagramOutputFormat(diagram, options), diagram.content // рендер-контент диаграммы (Buffer читается как текст)
-                );
-            if (options.EMBED_DIAGRAM) {
-                let imgContent = '';
-                if (options.GENERATE_LOCAL_IMAGES)
-                    imgContent = (await readFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), diagramUrl))).toString('base64');
-                else
-                    imgContent = await httpGet(diagramUrl);
-                const diagramImage = `\n![${path.parse(diagram.dir).name}](data:${getMime(diagramOutputFormat(diagram, options))};base64,${imgContent})\n`;
-                const diagramLink = `\n[Download ${path.parse(diagram.dir).name} diagram](${encodeURIPath(path.join(item.dir.replace(options.ROOT_FOLDER, ''), diagramUrl))} ':ignore')`;
-                return diagramImage + diagramLink;
-            }
-            else {
-                const diagramImage = `![diagram](${diagramUrl})`;
-                const diagramLink = `[Go to ${path.parse(diagram.dir).name} diagram](${encodeURIPath(path.join(item.dir.replace(options.ROOT_FOLDER, ''), diagramUrl))})`;
-                if (!options.INCLUDE_LINK_TO_DIAGRAM)
-                    //img
-                    return diagramImage;
-                //link
-                else
-                    return diagramLink;
-            }
-        });
+        MD = await compileDocument(MD, item, options, (item, diagram, options) => 
+        // complete: ссылки на диаграммы префиксуются папкой элемента.
+        buildDiagramMarkdown(item, diagram, options, 'complete'));
     }
     //write file to disk
     filePromises.push(writeFile(path.join(options.DIST_FOLDER, `${options.PROJECT_NAME}.md`), MD));
@@ -131,12 +209,8 @@ export const generateMD = async (tree, options, onProgress) => {
     const filePromises = [];
     for (const item of tree) {
         const name = getFolderName(item.dir, options.ROOT_FOLDER, options.HOMEPAGE_NAME);
-        const ownH1 = hasOwnH1(item);
-        //title
-        let MD = ownH1 ? '' : `# ${name}`;
-        // "Page chrome" — breadcrumb / TOC / навигация. Собираем отдельно, чтобы при
-        // наличии собственного h1 у пользователя поместить весь блок ПОД его заголовок,
-        // а не над ним (как было исторически — между авто-# name и контентом).
+        // "Page chrome" — breadcrumb / TOC / навигация. Собирается отдельно и встаёт
+        // под заголовок страницы (авто или пользовательский h1) внутри compilePage.
         let chrome = '';
         //bradcrumbs
         if (options.INCLUDE_BREADCRUMBS && name !== options.HOMEPAGE_NAME)
@@ -146,62 +220,28 @@ export const generateMD = async (tree, options, onProgress) => {
             let tableOfContents = '';
             for (const _item of tree) {
                 const label = `${item.dir === _item.dir ? '**' : ''}${_item.name}${item.dir === _item.dir ? '**' : ''}`;
-                tableOfContents += `${'  '.repeat(_item.level - 1)}* [${label}](${encodeURIPath(path.join('./', item.level - 1 > 0 ? '../'.repeat(item.level - 1) : '', _item.dir.replace(options.ROOT_FOLDER, ''), `${options.MD_FILE_NAME}.md`))})\n`; //slice 1 if root and down
+                tableOfContents += `${'  '.repeat(_item.level - 1)}* [${label}](${relativeMdLink(item.level, _item.dir.replace(options.ROOT_FOLDER, ''), options.MD_FILE_NAME)})\n`;
             }
             chrome += `\n\n${tableOfContents}\n---`;
         }
         //parent menu
         if (item.parent && options.INCLUDE_NAVIGATION) {
             const parentName = getFolderName(item.parent, options.ROOT_FOLDER, options.HOMEPAGE_NAME);
-            chrome += `\n\n[${parentName} (up)](${encodeURIPath(path.join('./', item.level - 1 > 0 ? '../'.repeat(item.level - 1) : '', item.parent.replace(options.ROOT_FOLDER, ''), `${options.MD_FILE_NAME}.md`))})`;
+            chrome += `\n\n[${parentName} (up)](${relativeMdLink(item.level, item.parent.replace(options.ROOT_FOLDER, ''), options.MD_FILE_NAME)})`;
         }
-        //exclude files and folders prefixed with _
+        //descendants menu (files and folders prefixed with _ excluded at scan)
         let descendantsMenu = '';
         for (const file of item.descendants) {
-            descendantsMenu += `\n\n- [${file}](${encodeURIPath(path.join('./', item.level - 1 > 0 ? '../'.repeat(item.level - 1) : '', item.dir.replace(options.ROOT_FOLDER, ''), file, `${options.MD_FILE_NAME}.md`))})`;
+            descendantsMenu += `\n\n- [${file}](${relativeMdLink(item.level, path.join(item.dir.replace(options.ROOT_FOLDER, ''), file), options.MD_FILE_NAME)})`;
         }
-        //descendants menu
         if (descendantsMenu && options.INCLUDE_NAVIGATION)
             chrome += `${descendantsMenu}`;
         //separator
         if (options.INCLUDE_NAVIGATION)
             chrome += `\n\n---`;
-        // Если своего h1 нет — chrome идёт сразу после авто-заголовка, как раньше.
-        // Если есть — chrome будет вставлен после пользовательского h1 пост-обработкой.
-        if (!ownH1)
-            MD += chrome;
-        //concatenate markdown files
-        MD = await compileDocument(MD, item, options, async (item, diagram, options) => {
-            let diagramUrl = encodeURIPath(path.join(path.dirname(diagram.dir), `${path.parse(diagram.dir).name}.${diagramOutputFormat(diagram, options)}`));
-            if (!options.GENERATE_LOCAL_IMAGES && diagram.engine === 'plantuml')
-                diagramUrl = plantUmlServerUrl(options.PLANTUML_SERVER_URL, diagramOutputFormat(diagram, options), diagram.content // рендер-контент диаграммы (Buffer читается как текст)
-                );
-            if (options.EMBED_DIAGRAM) {
-                let imgContent = '';
-                if (options.GENERATE_LOCAL_IMAGES)
-                    imgContent = (await readFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), diagramUrl))).toString('base64');
-                else
-                    imgContent = await httpGet(diagramUrl);
-                const diagramImage = `\n![${path.parse(diagram.dir).name}](data:${getMime(diagramOutputFormat(diagram, options))};base64,${imgContent})\n`;
-                const diagramLink = `[Download ${path.parse(diagram.dir).name} diagram](${diagramUrl} ':ignore')`;
-                return diagramImage + diagramLink;
-            }
-            else {
-                const diagramImage = `![diagram](${diagramUrl})`;
-                const diagramLink = `[Go to ${path.parse(diagram.dir).name} diagram](${diagramUrl})`;
-                if (!options.INCLUDE_LINK_TO_DIAGRAM)
-                    //img
-                    return diagramImage;
-                //link
-                else
-                    return diagramLink;
-            }
-        });
-        // Если был свой h1 — вставляем chrome (breadcrumbs/TOC/nav) после него.
-        if (ownH1)
-            MD = injectAfterFirstH1(MD, chrome);
+        const MD = await compilePage(item, options, chrome);
         //write to disk
-        filePromises.push(writeFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), `${options.MD_FILE_NAME}.md`), MD.trimStart()).then(() => {
+        filePromises.push(writeFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), `${options.MD_FILE_NAME}.md`), MD).then(() => {
             processedCount++;
             if (onProgress)
                 onProgress(processedCount, totalCount);
@@ -213,57 +253,28 @@ export const generateWebMD = async (tree, options) => {
     const filePromises = [];
     let docsifySideBar = '';
     const getWebFileName = (originalFileName) => options.WEB_FILE_NAME || originalFileName;
-    const isExcluded = (dir) => {
-        if (!Array.isArray(options.EXCLUDE_SIDEBAR_FOLDER_BY_PATH))
-            return false;
-        return options.EXCLUDE_SIDEBAR_FOLDER_BY_PATH.find((pathToExclude) => {
-            const isString = typeof pathToExclude === 'string';
-            if (isString)
-                return dir.startsWith(pathToExclude);
-            return false;
-        });
-    };
+    // Чистоту string[] гарантирует zod-схема (не-строки отброшены препроцессом).
+    const isExcluded = (dir) => !!options.EXCLUDE_SIDEBAR_FOLDER_BY_PATH?.some((pathToExclude) => dir.startsWith(pathToExclude));
     for (const item of tree) {
-        //sidebar
+        //sidebar — путь от ROOT_FOLDER (path.relative, а не отрезание первого сегмента:
+        // то ломалось на многосегментном rootFolder из рукописного конфига)
         if (!isExcluded(item.dir)) {
-            docsifySideBar += `${'  '.repeat(item.level - 1)}* [${item.name}](${encodeURIPath(path.join(...path.join(item.dir).split(path.sep).splice(1), getWebFileName(item.name)))})\n`;
+            docsifySideBar += `${'  '.repeat(item.level - 1)}* [${item.name}](${encodeURIPath(path.join(path.relative(options.ROOT_FOLDER, item.dir), getWebFileName(item.name)))})\n`;
         }
-        const name = getFolderName(item.dir, options.ROOT_FOLDER, options.HOMEPAGE_NAME);
-        //title
-        let MD = hasOwnH1(item) ? '' : `# ${name}`;
-        //concatenate markdown files
-        MD = await compileDocument(MD, item, options, async (item, diagram, options) => {
-            let diagramUrl = encodeURIPath(path.join(path.dirname(diagram.dir), `${path.parse(diagram.dir).name}.${diagramOutputFormat(diagram, options)}`));
-            if (!options.GENERATE_LOCAL_IMAGES && diagram.engine === 'plantuml')
-                diagramUrl = plantUmlServerUrl(options.PLANTUML_SERVER_URL, diagramOutputFormat(diagram, options), diagram.content // рендер-контент диаграммы (Buffer читается как текст)
-                );
-            if (options.EMBED_DIAGRAM) {
-                let imgContent = '';
-                if (options.GENERATE_LOCAL_IMAGES)
-                    imgContent = (await readFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), diagramUrl))).toString('base64');
-                else
-                    imgContent = await httpGet(diagramUrl);
-                const diagramImage = `\n![${path.parse(diagram.dir).name}](data:${getMime(diagramOutputFormat(diagram, options))};base64,${imgContent})\n`;
-                const diagramLink = `[Download ${path.parse(diagram.dir).name} diagram](${diagramUrl} ':ignore')`;
-                return diagramImage + diagramLink;
-            }
-            else {
-                const diagramImage = `![diagram](${diagramUrl})`;
-                const diagramLink = `[Go to ${path.parse(diagram.dir).name} diagram](${diagramUrl})`;
-                if (!options.INCLUDE_LINK_TO_DIAGRAM)
-                    //img
-                    return diagramImage;
-                //link
-                else
-                    return diagramLink;
-            }
-        });
-        MD = MD.trimStart();
+        const MD = await compilePage(item, options);
         //write to disk
         filePromises.push(writeFile(path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), `${getWebFileName(item.name)}.md`), MD));
     }
     if (options.DOCSIFY_TEMPLATE && options.DOCSIFY_TEMPLATE !== '') {
-        docsifyTemplate = require(path.join(process.cwd(), options.DOCSIFY_TEMPLATE));
+        // require ESM/TS-шаблона возвращает namespace { default: fn }, а не саму функцию —
+        // разворачиваем default, иначе дальше «docsifyTemplate is not a function».
+        const loaded = require(path.join(process.cwd(), options.DOCSIFY_TEMPLATE));
+        const fn = typeof loaded === 'function' ? loaded : loaded?.default;
+        if (typeof fn !== 'function') {
+            throw new Error(`docsifyTemplate «${options.DOCSIFY_TEMPLATE}» должен экспортировать функцию ` +
+                `(module.exports = fn или export default fn), получено: ${typeof fn}`);
+        }
+        docsifyTemplate = fn;
     }
     // Имя корневого элемента дерева (без parent) для homepage docsify. Считается лениво
     // (только если не задан WEB_FILE_NAME); отсутствие корня — явная ошибка вместо assertion.

package/dist/core/render/d2renderer.js

@@ -26,8 +26,13 @@ const getD2 = () => {
     })();
     return d2Promise;
 };
-// Явный teardown: webworker иначе держит процесс и CLI не завершается. Воркер
-// завершаем в finally, чтобы освободить его даже если init (inst.ready) упал.
+// Явный teardown: webworker иначе держит процесс и CLI не завершается. Зовётся из
+// CLI (dispatch) после ОДИНОЧНОЙ сборки — в watch-режиме воркер переживает ребилды
+// (его пересоздание на каждый ребилд стоило секунды), а при Ctrl+C умирает с процессом.
+// НЕ должен бросать: его throw затёр бы исходную причину падения сборки. Все ошибки
+// освобождения глушим (движок уже мёртв — то, что надо освободить, и так освобождено).
+// Идемпотентен: d2Promise=null в начале. Кеш графа импортов сбрасывает не он, а
+// clearD2FileCache() на границах build().
 const teardownD2 = async () => {
     if (!d2Promise)
         return;
@@ -43,10 +48,17 @@ const teardownD2 = async () => {
     try {
         await inst.ready; // worker создаётся асинхронно в init()
     }
-    finally {
+    catch {
+        // init движка мог упасть — это уже отражено ошибкой рендера; глушим, иначе
+        // throw из finally build() подменил бы исходную причину падения сборки.
+    }
+    try {
         if (inst.worker)
             await inst.worker.terminate();
     }
+    catch {
+        // воркер уже недоступен/мёртв — освобождать нечего.
+    }
 };
 // Разрешить ссылку импорта в .d2-файл на диске. Расширение .d2 подразумевается,
 // а `@file.key1.key2` — частичный импорт: имя файла это префикс до ключевого пути,
@@ -61,14 +73,22 @@ const resolveImport = (ref, fromDir) => {
     return null;
 };
 // Собрать граф импортов от входного .d2 рекурсивно: { абсолютный путь -> контент }.
-// Лидирующий `@` не после word-символа отсекает почтовые адреса и т.п.
-const IMPORT_RE = /(?<![\w])@([\w./-]+)/g;
+// Лидирующий `@` не после word-символа отсекает почтовые адреса (`foo@bar`).
+// Путь импорта поддерживает пробелы и юникод (папки `4 D2 Example`, `3 Локализация`),
+// а также закавыченную форму `@"путь с пробелом"` — движок @terrastruct/d2
+// принимает все три (проверено эмпирически). Незакавыченный путь читается до
+// терминатора statement (`#` комментарий, `;`, `}`, перевод строки) минус хвостовой
+// пробел — иначе инлайновый spread `x: { ...@lib }` захватил бы `lib }`. Флаг `u` —
+// корректный юникод. Хвостовые `.key`-сегменты частичного импорта отрезает resolveImport.
+const IMPORT_RE = /(?<!\w)@(?:"([^"\n]+)"|([^\s"#;}\n][^#;}\n]*?)\s*(?=[#;}\n]|$))/gu;
 const collectFiles = (entryAbs, acc = new Map()) => {
     const abs = path.resolve(entryAbs);
     if (acc.has(abs))
         return acc;
     let content;
     try {
+        // Строго UTF-8: язык D2 определён поверх UTF-8, опция CHARSET конфига относится
+        // к PlantUML (уходит в -charset) и на .d2 сознательно не распространяется.
         content = fs.readFileSync(abs, 'utf-8');
     }
     catch {
@@ -79,12 +99,35 @@ const collectFiles = (entryAbs, acc = new Map()) => {
     // между вложенными вызовами — иначе рекурсия затирала бы позицию глобального
     // regex и вложенные (2-го уровня) импорты молча терялись бы.
     for (const m of content.matchAll(IMPORT_RE)) {
-        const resolved = resolveImport(m[1], path.dirname(abs));
+        const ref = m[1] ?? m[2]; // закавыченный | незакавыченный путь
+        if (!ref)
+            continue;
+        const resolved = resolveImport(ref, path.dirname(abs));
         if (resolved)
             collectFiles(resolved, acc);
     }
     return acc;
 };
+// Мемоизация графа на время одной сборки: foldD2Imports (чексумма) и
+// buildCompileRequest (рендер) иначе читают один и тот же граф с диска дважды.
+// Ключ — абсолютный путь входного файла. Сбрасывается clearD2FileCache() на границах
+// build(), иначе watch-режим отдавал бы устаревшее содержимое. Возвращаемую Map
+// потребители НЕ мутируют (foldD2Imports исключает входной файл фильтром, не delete).
+let filesMemo = null;
+const clearD2FileCache = () => {
+    filesMemo = null;
+};
+const collectFilesCached = (entryAbs) => {
+    const abs = path.resolve(entryAbs);
+    if (!filesMemo)
+        filesMemo = new Map();
+    const hit = filesMemo.get(abs);
+    if (hit)
+        return hit;
+    const built = collectFiles(abs);
+    filesMemo.set(abs, built);
+    return built;
+};
 // Общий корень набора путей — чтобы ключи виртуальной fs были относительны ему и
 // родительские импорты (`...@../c4lib`) резолвились движком как на реальном диске.
 const commonAncestor = (files) => {
@@ -102,7 +145,12 @@ const commonAncestor = (files) => {
 };
 // Подготовить аргументы compile(): виртуальная fs (все файлы графа) + inputPath.
 const buildCompileRequest = (entryAbs) => {
-    const files = collectFiles(entryAbs);
+    const files = collectFilesCached(entryAbs);
+    // Пустой граф = не прочитался сам входной файл (удалён/недоступен — гонка в watch).
+    // Без guard'а commonAncestor([]) давал бы сырой TypeError (Math.min()=Infinity).
+    if (files.size === 0) {
+        throw new Error(`D2: не удалось прочитать ${entryAbs} (файл удалён или недоступен?)`);
+    }
     const root = commonAncestor([...files.keys()]);
     const toKey = (abs) => path.relative(root, abs).split(path.sep).join('/');
     const fsMap = {};
@@ -135,12 +183,20 @@ const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
 // Материал импортов для чексуммы кэша (без самого входного файла — его контент
 // хэшируется отдельно). Правка импортируемого .d2 меняет чексумму зависимой
 // диаграммы — аналог foldIncludes для PlantUML.
+// Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит
+// от машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
 const foldD2Imports = (entryAbs) => {
-    const files = collectFiles(entryAbs);
-    files.delete(path.resolve(entryAbs));
+    const abs = path.resolve(entryAbs);
+    const files = collectFilesCached(entryAbs);
+    const rel = (p) => path.relative(process.cwd(), p).split(path.sep).join('/');
+    // Мемоизированную Map не мутируем (её же использует buildCompileRequest) —
+    // входной файл исключаем фильтром, а не delete. Сортировка по относительному
+    // ключу — тому же, что уходит в материал.
     return [...files.entries()]
+        .filter(([p]) => p !== abs)
+        .map(([p, content]) => [rel(p), content])
         .sort((a, b) => a[0].localeCompare(b[0]))
-        .map(([abs, content]) => ` ${abs} ${content}`)
+        .map(([p, content]) => ` ${p} ${content}`)
         .join('');
 };
-export { renderD2, foldD2Imports, teardownD2 };
+export { renderD2, foldD2Imports, teardownD2, clearD2FileCache };