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

package/dist/config/defaults.js

@@ -22,12 +22,13 @@ 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',
+    d2Layout: 'dagre',
     charset: 'UTF-8'
 };
 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,65 @@
 // валидируется `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),
     // Задаются явно (флаг/промпт) либо тонкой правкой файла — в 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>`;