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

package/dist/cli/wizard/collect.js

@@ -3,8 +3,16 @@ import { z } from 'zod';
 import fs from 'node:fs';
 import path from 'node:path';
 import { defaultConfig } from "../../config/defaults.js";
-// Валидатор ответа визарда: zod safeParse → boolean (true = валидно) для inquirer.
-const validate = (schema) => (answer) => schema.safeParse(answer).success;
+// Непустая строка: в zod `.trim()` — трансформ, а не проверка, поэтому пустую строку
+// и пробелы отсекает явный `.min(1)`.
+const nonEmptyString = z.string().trim().min(1);
+// Валидатор ответа визарда: true при успешном safeParse, иначе текст ошибки для inquirer.
+// Пустой Enter уже подставил дефолт (answer = value || default) — сообщение получают
+// только явно введённые пробелы/пустая строка при отсутствии дефолта.
+const validate = (schema, message = 'значение обязательно') => (answer) => schema.safeParse(answer).success || message;
+// Пункт default-списка чекбокса inquirer: ключ отмечен, если он включён в текущем
+// конфиге, а при незаданном значении — если включён по умолчанию.
+const checkedKey = (current, dflt, key) => (current === undefined ? dflt : current) ? key : null;
 export default async (currentConfiguration, conf, program) => {
     // ESM исполняется в strict mode: под CommonJS `responses` был неявным глобалом,
     // здесь объявляем его явно (иначе присваивание бросит ReferenceError).
@@ -15,7 +23,7 @@ export default async (currentConfiguration, conf, program) => {
             name: 'projectName',
             message: 'Project Name',
             default: currentConfiguration.PROJECT_NAME || path.parse(process.cwd()).name,
-            validate: validate(z.string().trim().optional())
+            validate: validate(nonEmptyString, 'укажите имя проекта')
         });
         conf.set('projectName', responses.projectName);
     }
@@ -25,7 +33,7 @@ export default async (currentConfiguration, conf, program) => {
             name: 'homepageName',
             message: 'HomePage Name',
             default: currentConfiguration.HOMEPAGE_NAME || defaultConfig.homepageName,
-            validate: validate(z.string().trim().optional())
+            validate: validate(nonEmptyString, 'укажите имя главной страницы')
         });
         conf.set('homepageName', responses.homepageName);
     }
@@ -35,17 +43,21 @@ export default async (currentConfiguration, conf, program) => {
             name: 'rootFolder',
             message: 'Root documentation folder',
             default: currentConfiguration.ROOT_FOLDER || defaultConfig.rootFolder,
-            validate: (answers) => {
-                const isValid = validate(z.string().trim().optional())(answers);
-                if (isValid) {
-                    if (answers.indexOf('/') !== -1 || answers.indexOf('\\') !== -1)
-                        return false;
-                    //check it's an actual folder
-                    const isDirectory = fs.statSync(path.join(process.cwd(), answers)).isDirectory();
-                    if (isDirectory)
-                        return true;
+            validate: (answer) => {
+                if (!nonEmptyString.safeParse(answer).success)
+                    return 'укажите папку с документацией';
+                if (answer.indexOf('/') !== -1 || answer.indexOf('\\') !== -1)
+                    return 'имя папки не должно содержать «/» или «\\»';
+                // statSync бросает ENOENT для несуществующего пути — ловим и превращаем в
+                // сообщение, иначе async-хендлер inquirer уронит процесс сырым стектрейсом.
+                try {
+                    if (!fs.statSync(path.join(process.cwd(), answer)).isDirectory())
+                        return 'указанный путь не является каталогом';
                 }
-                return false;
+                catch {
+                    return 'папка не найдена';
+                }
+                return true;
             }
         });
         conf.set('rootFolder', responses.rootFolder);
@@ -74,27 +86,9 @@ export default async (currentConfiguration, conf, program) => {
         currentConfiguration.GENERATE_WEBSITE === undefined ||
         program.config) {
         const defaults = [
-            currentConfiguration.GENERATE_MD === undefined
-                ? defaultConfig.generateMD
-                    ? 'generateMD'
-                    : null
-                : currentConfiguration.GENERATE_MD
-                    ? 'generateMD'
-                    : null,
-            currentConfiguration.GENERATE_COMPLETE_MD_FILE === undefined
-                ? defaultConfig.generateCompleteMD
-                    ? 'generateCompleteMD'
-                    : null
-                : currentConfiguration.GENERATE_COMPLETE_MD_FILE
-                    ? 'generateCompleteMD'
-                    : null,
-            currentConfiguration.GENERATE_WEBSITE === undefined
-                ? defaultConfig.generateWEB
-                    ? 'generateWEB'
-                    : null
-                : currentConfiguration.GENERATE_WEBSITE
-                    ? 'generateWEB'
-                    : null
+            checkedKey(currentConfiguration.GENERATE_MD, defaultConfig.generateMD, 'generateMD'),
+            checkedKey(currentConfiguration.GENERATE_COMPLETE_MD_FILE, defaultConfig.generateCompleteMD, 'generateCompleteMD'),
+            checkedKey(currentConfiguration.GENERATE_WEBSITE, defaultConfig.generateWEB, 'generateWEB')
         ];
         responses = await inquirer.prompt({
             type: 'checkbox',
@@ -116,10 +110,10 @@ export default async (currentConfiguration, conf, program) => {
                 }
             ]
         });
-        conf.set('generateMD', !!responses.generate.find((x) => x === 'generateMD'));
-        conf.set('generateCompleteMD', !!responses.generate.find((x) => x === 'generateCompleteMD'));
-        conf.set('generateWEB', !!responses.generate.find((x) => x === 'generateWEB'));
-        if (responses.generate.find((x) => x === 'generateMD')) {
+        conf.set('generateMD', responses.generate.includes('generateMD'));
+        conf.set('generateCompleteMD', responses.generate.includes('generateCompleteMD'));
+        conf.set('generateWEB', responses.generate.includes('generateWEB'));
+        if (responses.generate.includes('generateMD')) {
             let mdOptions = await inquirer.prompt({
                 type: 'confirm',
                 name: 'includeNavigation',
@@ -139,7 +133,7 @@ export default async (currentConfiguration, conf, program) => {
             });
             conf.set('includeTableOfContents', mdOptions.includeTableOfContents);
         }
-        if (responses.generate.find((x) => x === 'generateWEB')) {
+        if (responses.generate.includes('generateWEB')) {
             let webOptions = await inquirer.prompt({
                 type: 'input',
                 name: 'webTheme',
@@ -148,7 +142,9 @@ export default async (currentConfiguration, conf, program) => {
             });
             conf.set('webTheme', webOptions.webTheme);
             webOptions = await inquirer.prompt({
-                type: 'input',
+                // confirm возвращает boolean — схема требует строгий z.boolean();
+                // input сохранял бы строку ('y') и валил последующий safeParse конфига.
+                type: 'confirm',
                 name: 'supportSearch',
                 message: 'Support search on navbar?',
                 default: defaultConfig.supportSearch
@@ -195,48 +191,12 @@ export default async (currentConfiguration, conf, program) => {
         currentConfiguration.EXCLUDE_OTHER_FILES === undefined ||
         program.config) {
         const defaults = [
-            currentConfiguration.INCLUDE_BREADCRUMBS === undefined
-                ? defaultConfig.includeBreadcrumbs
-                    ? 'includeBreadcrumbs'
-                    : null
-                : currentConfiguration.INCLUDE_BREADCRUMBS
-                    ? 'includeBreadcrumbs'
-                    : null,
-            currentConfiguration.GENERATE_LOCAL_IMAGES === undefined
-                ? defaultConfig.generateLocalImages
-                    ? 'generateLocalImages'
-                    : null
-                : currentConfiguration.GENERATE_LOCAL_IMAGES
-                    ? 'generateLocalImages'
-                    : null,
-            currentConfiguration.INCLUDE_LINK_TO_DIAGRAM === undefined
-                ? defaultConfig.includeLinkToDiagram
-                    ? 'includeLinkToDiagram'
-                    : null
-                : currentConfiguration.INCLUDE_LINK_TO_DIAGRAM
-                    ? 'includeLinkToDiagram'
-                    : null,
-            currentConfiguration.DIAGRAMS_ON_TOP === undefined
-                ? defaultConfig.diagramsOnTop
-                    ? 'diagramsOnTop'
-                    : null
-                : currentConfiguration.DIAGRAMS_ON_TOP
-                    ? 'diagramsOnTop'
-                    : null,
-            currentConfiguration.EMBED_DIAGRAM === undefined
-                ? defaultConfig.embedDiagram
-                    ? 'embedDiagram'
-                    : null
-                : currentConfiguration.EMBED_DIAGRAM
-                    ? 'embedDiagram'
-                    : null,
-            currentConfiguration.EXCLUDE_OTHER_FILES === undefined
-                ? defaultConfig.excludeOtherFiles
-                    ? 'excludeOtherFiles'
-                    : null
-                : currentConfiguration.EXCLUDE_OTHER_FILES
-                    ? 'excludeOtherFiles'
-                    : null
+            checkedKey(currentConfiguration.INCLUDE_BREADCRUMBS, defaultConfig.includeBreadcrumbs, 'includeBreadcrumbs'),
+            checkedKey(currentConfiguration.GENERATE_LOCAL_IMAGES, defaultConfig.generateLocalImages, 'generateLocalImages'),
+            checkedKey(currentConfiguration.INCLUDE_LINK_TO_DIAGRAM, defaultConfig.includeLinkToDiagram, 'includeLinkToDiagram'),
+            checkedKey(currentConfiguration.DIAGRAMS_ON_TOP, defaultConfig.diagramsOnTop, 'diagramsOnTop'),
+            checkedKey(currentConfiguration.EMBED_DIAGRAM, defaultConfig.embedDiagram, 'embedDiagram'),
+            checkedKey(currentConfiguration.EXCLUDE_OTHER_FILES, defaultConfig.excludeOtherFiles, 'excludeOtherFiles')
         ];
         const choices = [
             {
@@ -271,12 +231,12 @@ export default async (currentConfiguration, conf, program) => {
             default: defaults,
             choices: choices
         });
-        conf.set('includeBreadcrumbs', !!responses.generate.find((x) => x === 'includeBreadcrumbs'));
-        conf.set('includeLinkToDiagram', !!responses.generate.find((x) => x === 'includeLinkToDiagram'));
-        conf.set('diagramsOnTop', !!responses.generate.find((x) => x === 'diagramsOnTop'));
-        conf.set('embedDiagram', !!responses.generate.find((x) => x === 'embedDiagram'));
-        conf.set('excludeOtherFiles', !!responses.generate.find((x) => x === 'excludeOtherFiles'));
-        conf.set('generateLocalImages', !!responses.generate.find((x) => x === 'generateLocalImages'));
+        conf.set('includeBreadcrumbs', responses.generate.includes('includeBreadcrumbs'));
+        conf.set('includeLinkToDiagram', responses.generate.includes('includeLinkToDiagram'));
+        conf.set('diagramsOnTop', responses.generate.includes('diagramsOnTop'));
+        conf.set('embedDiagram', responses.generate.includes('embedDiagram'));
+        conf.set('excludeOtherFiles', responses.generate.includes('excludeOtherFiles'));
+        conf.set('generateLocalImages', responses.generate.includes('generateLocalImages'));
     }
     if (!currentConfiguration.PLANTUML_SERVER_URL || program.config) {
         responses = await inquirer.prompt({
@@ -284,7 +244,7 @@ export default async (currentConfiguration, conf, program) => {
             name: 'plantumlServerUrl',
             message: 'PlantUML Server URL',
             default: currentConfiguration.PLANTUML_SERVER_URL || defaultConfig.plantumlServerUrl,
-            validate: validate(z.string().trim().optional())
+            validate: validate(nonEmptyString, 'укажите URL сервера PlantUML')
         });
         conf.set('plantumlServerUrl', responses.plantumlServerUrl);
     }
@@ -294,7 +254,7 @@ export default async (currentConfiguration, conf, program) => {
             name: 'diagramFormat',
             message: 'Diagram Image Format',
             default: currentConfiguration.DIAGRAM_FORMAT || defaultConfig.diagramFormat,
-            validate: validate(z.string().trim().optional())
+            validate: validate(nonEmptyString, 'укажите формат изображения диаграмм')
         });
         conf.set('diagramFormat', responses.diagramFormat);
     }

package/dist/config/defaults.js

@@ -22,12 +22,14 @@ const defaultConfig = {
     webPort: '3000',
     includeBreadcrumbs: true,
     includeLinkToDiagram: false,
-    diagramsOnTop: false,
+    diagramsOnTop: true,
     embedDiagram: false,
     excludeOtherFiles: false,
     generateLocalImages: true,
     plantumlServerUrl: 'https://www.plantuml.com/plantuml',
     diagramFormat: 'svg',
-    charset: 'UTF-8'
+    d2Layout: 'dagre',
+    charset: 'UTF-8',
+    useSystemFonts: false
 };
 export { defaultConfig };

package/dist/config/options.js

@@ -1,4 +1,32 @@
 // Опорные типы конфигурации c4builder. Объявлены здесь (первой группой порта),
 // потому что результат getOptions() (BuildOptions) потребляет build() — он
 // портируется раньше, чем cli/dispatch, где getOptions() физически живёт.
-export {};
+// Форма файла `.c4builder` (camelCase) — единый тип задаёт zod-схема (config/schema),
+// её же валидацией опирается загрузка опций сборки. Ре-экспорт: потребители типа
+// (defaults, dispatch) продолжают импортировать его отсюда.
+import { configSchema } from "./schema.js";
+/**
+ * Разбирает сырой объект `.c4builder`, разделяя строгий и щадящий пути. Сам НЕ печатает
+ * и НЕ завершает процесс — решение (ошибка+выход либо предупреждение) принимает CLI.
+ * Битые ключи определяются по первому сегменту `issue.path`; `salvaged` получается
+ * повторным разбором очищенного от них конфига — без дублирования схемы.
+ */
+export function parseConfig(raw) {
+    const parsed = configSchema.safeParse(raw);
+    if (parsed.success)
+        return { ok: true, value: parsed.data };
+    const issues = [];
+    const brokenKeys = new Set();
+    for (const issue of parsed.error.issues) {
+        const key = issue.path.length ? String(issue.path[0]) : '(корень)';
+        if (brokenKeys.has(key))
+            continue; // один ключ — одно сообщение (напр. массив с N битых элементов)
+        brokenKeys.add(key);
+        issues.push({ key, value: raw[key], message: issue.message });
+    }
+    const cleaned = Object.fromEntries(Object.entries(raw).filter(([k]) => !brokenKeys.has(k)));
+    const salvagedParse = configSchema.safeParse(cleaned);
+    // cleaned свободен от всех проблемных ключей → валиден; фолбэк на пустой конфиг — страховка.
+    const salvaged = salvagedParse.success ? salvagedParse.data : configSchema.parse({});
+    return { ok: false, issues, salvaged };
+}

package/dist/config/schema.js

@@ -4,45 +4,66 @@
 // валидируется `safeParse` — неверный тип значения отклоняется понятной ошибкой с
 // путём ключа, отсутствующие поля дополняются дефолтами.
 //
-// Строки коэрсятся (`z.coerce.string`: число `webPort` из рукописного конфига → строка),
+// Числа в строковых полях коэрсятся (`webPort: 8000` из рукописного конфига → строка),
 // булевы поля строгие (`z.boolean`: строка вместо булева — ошибка, а не тихое truthy).
 import { z } from 'zod';
 import { defaultConfig } from "./defaults.js";
+// В JSON-конфиге `null` означает «ключ не задан» (а не строку "null"): гоним его в
+// `undefined` до внутренней схемы, чтобы срабатывал `.default`/`.optional`, а не строгий тип.
+const nullish = (s) => z.preprocess((v) => (v === null ? undefined : v), s);
+// Строковое поле: null И false = «не задано» → дефолт (false — легаси-идиома отключения,
+// напр. `docsifyTemplate: false` в конфигах 0.2.x); число коэрсится в строку. Прочие типы
+// (true, объекты) — понятная ошибка, а не тихая строка 'true' (z.coerce.string превращал
+// false в 'false', и сборка падала на require('<cwd>/false')).
+const strPre = (v) => v === null || v === false ? undefined : typeof v === 'number' ? String(v) : v;
+const str = (def) => z.preprocess(strPre, z.string().default(def));
+const optStr = () => z.preprocess(strPre, z.string().optional());
+const bool = (def) => nullish(z.boolean().default(def));
+const optBool = () => nullish(z.boolean().optional());
+// TCP-порт: нечисловая строка ('30OO') иначе доехала бы до app.listen(), который
+// трактует её как имя unix-сокета. Экспортируется для проверки CLI-флага -p.
+export const isValidPort = (s) => /^\d+$/.test(s) && Number(s) >= 1 && Number(s) <= 65535;
 export const configSchema = z.object({
     // Базовые поля: опциональны в файле, но с дефолтом из defaultConfig — частичный
     // или пустой конфиг остаётся валидным (недостающее берёт значение по умолчанию).
-    homepageName: z.coerce.string().default(defaultConfig.homepageName),
-    rootFolder: z.coerce.string().default(defaultConfig.rootFolder),
-    distFolder: z.coerce.string().default(defaultConfig.distFolder),
-    generateMD: z.boolean().default(defaultConfig.generateMD),
-    generateCompleteMD: z.boolean().default(defaultConfig.generateCompleteMD),
-    generateWEB: z.boolean().default(defaultConfig.generateWEB),
-    includeNavigation: z.boolean().default(defaultConfig.includeNavigation),
-    includeTableOfContents: z.boolean().default(defaultConfig.includeTableOfContents),
-    webTheme: z.coerce.string().default(defaultConfig.webTheme),
-    supportSearch: z.boolean().default(defaultConfig.supportSearch),
-    repoUrl: z.coerce.string().default(defaultConfig.repoUrl),
-    executeScript: z.boolean().default(defaultConfig.executeScript),
-    docsifyTemplate: z.coerce.string().default(defaultConfig.docsifyTemplate),
-    webPort: z.coerce.string().default(defaultConfig.webPort),
-    includeBreadcrumbs: z.boolean().default(defaultConfig.includeBreadcrumbs),
-    includeLinkToDiagram: z.boolean().default(defaultConfig.includeLinkToDiagram),
-    diagramsOnTop: z.boolean().default(defaultConfig.diagramsOnTop),
-    embedDiagram: z.boolean().default(defaultConfig.embedDiagram),
-    excludeOtherFiles: z.boolean().default(defaultConfig.excludeOtherFiles),
-    generateLocalImages: z.boolean().default(defaultConfig.generateLocalImages),
-    plantumlServerUrl: z.coerce.string().default(defaultConfig.plantumlServerUrl),
-    diagramFormat: z.coerce.string().default(defaultConfig.diagramFormat),
-    charset: z.coerce.string().default(defaultConfig.charset),
+    homepageName: str(defaultConfig.homepageName),
+    rootFolder: str(defaultConfig.rootFolder),
+    distFolder: str(defaultConfig.distFolder),
+    generateMD: bool(defaultConfig.generateMD),
+    generateCompleteMD: bool(defaultConfig.generateCompleteMD),
+    generateWEB: bool(defaultConfig.generateWEB),
+    includeNavigation: bool(defaultConfig.includeNavigation),
+    includeTableOfContents: bool(defaultConfig.includeTableOfContents),
+    webTheme: str(defaultConfig.webTheme),
+    supportSearch: bool(defaultConfig.supportSearch),
+    repoUrl: str(defaultConfig.repoUrl),
+    executeScript: bool(defaultConfig.executeScript),
+    docsifyTemplate: str(defaultConfig.docsifyTemplate),
+    webPort: z.preprocess(strPre, z
+        .string()
+        .refine(isValidPort, 'ожидается TCP-порт: целое число 1..65535')
+        .default(defaultConfig.webPort)),
+    includeBreadcrumbs: bool(defaultConfig.includeBreadcrumbs),
+    includeLinkToDiagram: bool(defaultConfig.includeLinkToDiagram),
+    diagramsOnTop: bool(defaultConfig.diagramsOnTop),
+    embedDiagram: bool(defaultConfig.embedDiagram),
+    excludeOtherFiles: bool(defaultConfig.excludeOtherFiles),
+    generateLocalImages: bool(defaultConfig.generateLocalImages),
+    plantumlServerUrl: str(defaultConfig.plantumlServerUrl),
+    diagramFormat: str(defaultConfig.diagramFormat),
+    d2Layout: str(defaultConfig.d2Layout),
+    charset: str(defaultConfig.charset),
+    useSystemFonts: bool(defaultConfig.useSystemFonts),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в defaultConfig не входят.
-    projectName: z.coerce.string().optional(),
-    d2Layout: z.coerce.string().optional(),
-    webFileName: z.coerce.string().optional(),
-    excludeSidebarFolderByPath: z.array(z.string()).optional(),
-    hasRun: z.boolean().optional(),
+    projectName: optStr(),
+    webFileName: optStr(),
+    // Не-строки внутри массива молча отбрасываются (совместимость с master: null среди
+    // путей не валит сборку) — runtime дальше работает с чистым string[].
+    excludeSidebarFolderByPath: nullish(z.preprocess((v) => (Array.isArray(v) ? v.filter((x) => typeof x === 'string') : v), z.array(z.string()).optional())),
+    hasRun: optBool(),
     // Легаси-ключи старых `.c4builder` — читаются лишь для однократного предупреждения.
-    plantumlVersion: z.coerce.string().optional(),
-    generatePDF: z.boolean().optional(),
-    generateCompletePDF: z.boolean().optional(),
+    plantumlVersion: optStr(),
+    generatePDF: optBool(),
+    generateCompletePDF: optBool(),
     checksums: z.unknown().optional()
 });

package/dist/core/build.js

@@ -1,13 +1,14 @@
 import chalk from 'chalk';
 import path from 'node:path';
 import fsextra from 'fs-extra';
-import { makeDirectory } from "../util/utils.js";
-// teardownD2: освобождение webworker D2 в конце сборки.
-import { teardownD2 } from "./render/d2renderer.js";
+import { makeDirectory, writeOnSameLine } from "../util/utils.js";
+// clearD2FileCache: сброс кеша графа D2-импортов на границах сборки (сам webworker
+// D2 гасит CLI после одиночной сборки — в watch-режиме он переживает ребилды).
+import { clearD2FileCache } from "./render/d2renderer.js";
 // Фазы сборки: scan (дерево исходников) → render (диаграммы) → compose (markdown/сайт).
-import { generateTree } from "./scan/tree.js";
+import { generateTree, engineSupportsRemote, clearIncludeCache } from "./scan/tree.js";
 import { generateImages } from "./render/diagrams.js";
-import { generateMD, generateWebMD, generateCompleteMD } from "./compose/markdown.js";
+import { generateMD, generateWebMD, generateCompleteMD, clearDiagramCache } from "./compose/markdown.js";
 // Оркестратор владеет lifecycle выходного каталога: dist бэкапится в dist_bk, откуда
 // generateImages восстанавливает неизменённые по чексумме картинки; в конце бэкап сносится.
 const DIST_BACKUP_FOLDER_SUFFIX = '_bk';
@@ -26,50 +27,75 @@ const build = async (options, cacheConf) => {
         await fsextra.emptyDir(options.DIST_FOLDER);
     }
     await makeDirectory(path.join(options.DIST_FOLDER));
-    //actual build
-    console.log(chalk.green(`\nbuilding documentation in ./${options.DIST_FOLDER}`));
-    const tree = await generateTree(options.ROOT_FOLDER, options);
-    console.log(chalk.blue(`parsed ${tree.length} folders`));
-    // У D2 нет онлайн-сервера рендера (в отличие от PlantUML): без локальной
-    // генерации .d2 не во что превратить — ссылки на SVG вели бы в никуда.
-    // Падаем сразу с понятной ошибкой, а не молча битым выводом.
-    if (!options.GENERATE_LOCAL_IMAGES && tree.some((item) => item.diagrams.some((d) => d.engine === 'd2'))) {
-        throw new Error('В проекте есть .d2-диаграммы, но generateLocalImages выключен. У D2 нет ' +
-            'онлайн-сервера рендера — включите локальную генерацию изображений (generateLocalImages).');
-    }
-    if (options.GENERATE_LOCAL_IMAGES) {
-        console.log(chalk.blue('generating images'));
-        await generateImages(tree, options, (count, total) => {
-            process.stdout.write(`processed ${count}/${total} images\r`);
-        }, cacheConf, bkFolderName);
-        console.log('');
-    }
-    if (options.GENERATE_MD) {
-        console.log(chalk.blue('generating markdown files'));
-        await generateMD(tree, options, (count, total) => {
-            process.stdout.write(`processed ${count}/${total} files\r`);
-        });
-        console.log('');
-    }
-    if (options.GENERATE_WEBSITE) {
-        console.log(chalk.blue('generating docsify site'));
-        await generateWebMD(tree, options);
-    }
-    if (options.GENERATE_COMPLETE_MD_FILE) {
-        console.log(chalk.blue('generating complete markdown file'));
-        await generateCompleteMD(tree, options);
+    // Сбросить пофайловые кеши прошлой сборки (актуально для watch-режима): base64
+    // диаграмм, граф D2-импортов, контент include-файлов PlantUML.
+    clearDiagramCache();
+    clearD2FileCache();
+    clearIncludeCache();
+    let ok = false;
+    try {
+        //actual build
+        console.log(chalk.green(`\nbuilding documentation in ./${options.DIST_FOLDER}`));
+        const tree = await generateTree(options.ROOT_FOLDER, options);
+        console.log(chalk.blue(`parsed ${tree.length} folders`));
+        // У движков без онлайн-рендера (D2, см. remoteRender в DIAGRAM_ENGINES) при
+        // выключенной локальной генерации диаграммы не во что превратить — ссылки на
+        // SVG вели бы в никуда. Падаем сразу с понятной ошибкой, а не молча битым выводом.
+        if (!options.GENERATE_LOCAL_IMAGES) {
+            const offline = new Set(tree.flatMap((item) => item.diagrams.filter((d) => !engineSupportsRemote(d.engine)).map((d) => d.engine)));
+            if (offline.size) {
+                throw new Error(`В проекте есть диаграммы без онлайн-сервера рендера (${[...offline].join(', ')}), ` +
+                    'но generateLocalImages выключен — включите локальную генерацию изображений ' +
+                    '(generateLocalImages).');
+            }
+        }
+        if (options.GENERATE_LOCAL_IMAGES) {
+            console.log(chalk.blue('generating images'));
+            await generateImages(tree, options, (count, total) => {
+                writeOnSameLine(`processed ${count}/${total} images`);
+            }, cacheConf, bkFolderName);
+            console.log('');
+        }
+        if (options.GENERATE_MD) {
+            console.log(chalk.blue('generating markdown files'));
+            await generateMD(tree, options, (count, total) => {
+                writeOnSameLine(`processed ${count}/${total} files`);
+            });
+            console.log('');
+        }
+        if (options.GENERATE_WEBSITE) {
+            console.log(chalk.blue('generating docsify site'));
+            await generateWebMD(tree, options);
+        }
+        if (options.GENERATE_COMPLETE_MD_FILE) {
+            console.log(chalk.blue('generating complete markdown file'));
+            await generateCompleteMD(tree, options);
+        }
+        // PDF-вывод удалён. Легаси-конфиг с truthy generatePDF/generateCompletePDF не
+        // роняем: печатаем предупреждение с реально присутствующими ключами и собираем
+        // остальные выходы (exit 0). Конфиг НЕ мутируем — только подсказка пользователю.
+        if (options.LEGACY_PDF_KEYS?.length) {
+            console.log(chalk.bold(chalk.yellow('WARNING:')));
+            console.log(chalk.yellow(`PDF-вывод больше не поддерживается. Удалите вручную из .c4builder: ${options.LEGACY_PDF_KEYS.join(', ')}.`));
+        }
+        console.log(chalk.green(`built in ${(Date.now() - start_date.getTime()) / 1000} seconds`));
+        ok = true;
     }
-    // PDF-вывод удалён. Легаси-конфиг с truthy generatePDF/generateCompletePDF не
-    // роняем: печатаем предупреждение с реально присутствующими ключами и собираем
-    // остальные выходы (exit 0). Конфиг НЕ мутируем — только подсказка пользователю.
-    if (options.LEGACY_PDF_KEYS?.length) {
-        console.log(chalk.bold(chalk.yellow('WARNING:')));
-        console.log(chalk.yellow(`PDF-вывод больше не поддерживается. Удалите вручную из .c4builder: ${options.LEGACY_PDF_KEYS.join(', ')}.`));
+    finally {
+        // Бэкап dist сносим ТОЛЬКО при успехе: при падении фазы dist_bk — единственная
+        // полная копия прошлого удачного билда, её нельзя терять (иначе первый же
+        // сломавшийся рендер уничтожает рабочий вывод).
+        if (ok) {
+            await fsextra.removeSync(bkFolderName);
+        }
+        else if (options.GENERATE_LOCAL_IMAGES && fsextra.existsSync(bkFolderName)) {
+            console.log(chalk.yellow(`\nсборка прервана — бэкап предыдущего билда сохранён в ./${bkFolderName}`));
+        }
+        // Пофайловые кеши нужны только внутри сборки — чистим и на выходе, чтобы
+        // watch-процесс не держал base64 всех диаграмм в памяти между ребилдами.
+        clearDiagramCache();
+        clearD2FileCache();
+        clearIncludeCache();
     }
-    // Remove image backup folder
-    await fsextra.removeSync(bkFolderName);
-    // Освободить D2-инстанс (webworker), иначе процесс не завершится. No-op, если .d2 не было.
-    await teardownD2();
-    console.log(chalk.green(`built in ${(Date.now() - start_date.getTime()) / 1000} seconds`));
 };
 export { build };

package/dist/core/compose/docsify.template.js

@@ -20,8 +20,8 @@ export default (options) => {
         <script src="vendor/docsify.min.js"></script>
         <script src="vendor/docsify-plantuml.min.js"></script>
         <script src="vendor/zoom-image.min.js"></script>
-        ${!!options.supportSearch && `<script src="vendor/search.min.js"></script>`}
-        ${!!options.executeScript && `<script src="vendor/swagger-ui-bundle.js"></script>`}
+        ${options.supportSearch ? `<script src="vendor/search.min.js"></script>` : ''}
+        ${options.executeScript ? `<script src="vendor/swagger-ui-bundle.js"></script>` : ''}
     </body>
     
     </html>`;