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

package/dist/core/render/diagrams.js

@@ -1,51 +1,95 @@
 import chalk from 'chalk';
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
-import http from 'node:http';
-import https from 'node:https';
 import crypto from 'node:crypto';
 import fsextra from 'fs-extra';
 import { spawn } from 'node:child_process';
+import { createRequire } from 'node:module';
 import { writeFile, VENDORED_JAR } from "../../util/utils.js";
+import { httpGetBuffer } from "../../util/http.js";
 // D2-бэкенд: только статические хелперы (парсинг импортов) грузятся сразу; сам
 // движок @terrastruct/d2 тянется лениво внутри renderD2/teardownD2.
 import { renderD2, foldD2Imports } from "./d2renderer.js";
 import { resolveJava } from "./jre.js";
 // PNG-выход: SVG обоих движков растеризуется resvg (ленивая загрузка внутри модуля).
 import { rasterizeSvgToPng } from "./pngraster.js";
+// Шрифт-пин общий с resvg-растеризатором (одна точка правды, см. fonts.ts).
+import { FONTS_DIR, DEFAULT_FONT_NAME } from "./fonts.js";
 import { VENDOR_DIR } from "../../util/paths.js";
 import { foldIncludes, diagramOutputFormat } from "../scan/tree.js";
-// Вендорный шрифт: ширина текста в SVG считается из AWT-метрик, поэтому
-// шрифт пинуется, чтобы рендер не зависел от того, что установлено на машине.
-const FONTS_DIR = path.join(VENDOR_DIR, 'fonts');
-const DEFAULT_FONT_NAME = 'Liberation Sans';
+// Таймаут рендера ОДНОЙ диаграммы: зависший JVM (циклы Smetana-layout) не эмитит
+// ни 'close', ни 'error' — без таймаута await виснет вечно, а в watch-режиме
+// isBuilding остаётся true навсегда. По таймауту процесс убивается (SIGTERM→SIGKILL).
+const RENDER_TIMEOUT_MS = 120_000;
+const SIGKILL_GRACE_MS = 5_000;
+// Размер пула PlantUML-рендера. Каждая задача — отдельный процесс java (свой JVM,
+// свои сотни МБ heap), поэтому пул НЕ равен числу ядер: дефолт — cpus-1, но не более 4.
+// Переопределяется env C4BUILDER_RENDER_CONCURRENCY (целое ≥1); мусор — молча дефолт.
+const renderConcurrency = () => {
+    const raw = process.env.C4BUILDER_RENDER_CONCURRENCY;
+    if (raw !== undefined) {
+        const n = Number(raw);
+        if (Number.isInteger(n) && n >= 1)
+            return n;
+    }
+    return Math.max(1, Math.min(4, os.cpus().length - 1));
+};
+// Пул ограниченной конкурентности: гоняет tasks не более `concurrency` одновременно.
+// Порядок вызова задач сохраняется (worker'ы разбирают общий индекс next), результат —
+// не собираем (каждая задача пишет свой файл сама). При первой ошибке новые задачи не
+// стартуют, но УЖЕ запущенные дожидаются (finally у Promise.all в воркере) — чтобы не
+// осталось висящих JVM, — после чего пробрасывается первая пойманная ошибка.
+const runPool = async (tasks, concurrency) => {
+    let next = 0;
+    let firstError;
+    const worker = async () => {
+        while (next < tasks.length && firstError === undefined) {
+            const task = tasks[next++];
+            try {
+                await task();
+            }
+            catch (err) {
+                if (firstError === undefined)
+                    firstError = err;
+            }
+        }
+    };
+    const width = Math.max(1, Math.min(concurrency, tasks.length));
+    const workers = [];
+    for (let i = 0; i < width; i++)
+        workers.push(worker());
+    await Promise.all(workers);
+    if (firstError !== undefined)
+        throw firstError;
+};
+// Версия движка @terrastruct/d2 для чексуммы кэша (апгрейд движка → перерендер).
+// Читаем package.json лениво и один раз: pure-PlantUML сборки его не трогают.
+let d2VersionCache = null;
+const d2EngineVersion = () => {
+    if (d2VersionCache !== null)
+        return d2VersionCache;
+    try {
+        const req = createRequire(import.meta.url);
+        d2VersionCache = req('@terrastruct/d2/package.json').version;
+    }
+    catch {
+        d2VersionCache = 'unknown';
+    }
+    return d2VersionCache;
+};
+// В ключ кеша: смена режима не должна отдавать картинку, отрисованную другим шрифтом
+// (D2 тоже — его PNG растрирует общий resvg).
+export const fontCacheTag = (options) => options.USE_SYSTEM_FONTS ? 'system' : DEFAULT_FONT_NAME;
 export const getMime = (format) => {
     if (format === 'svg')
         return `image/svg+xml`;
     return `image/${format}`;
 };
-export const httpGet = async (url) => {
-    // return new pending promise
-    return new Promise((resolve, reject) => {
-        // select http or https module, depending on reqested url
-        const lib = url.startsWith('https') ? https : http;
-        const request = lib.get(url, (response) => {
-            const status = response.statusCode; // ответ всегда со статусом
-            // handle http errors
-            if (status < 200 || status > 299) {
-                reject(new Error(`Failed to load page ${url}, status code: ${status}`));
-            }
-            // temporary data holder
-            const body = [];
-            // on every content chunk, push it to the data array
-            response.on('data', (chunk) => body.push(chunk));
-            // we are done, resolve promise with those joined chunks
-            response.on('end', () => resolve(Buffer.concat(body).toString('base64')));
-        });
-        // handle connection errors of the request
-        request.on('error', (err) => reject(err));
-    });
-};
+// Загрузка удалённо отрендеренной картинки (embed-ветка онлайн-рендера PlantUML) в
+// base64. Редиректы и таймауты берём из общего util/http: прежде здесь был голый GET
+// без обоих — 302 от PlantUML-сервера ронял embed-сборку, а зависший сокет вешал её.
+export const httpGet = async (url) => (await httpGetBuffer(url)).toString('base64');
 // Прямой вызов PlantUML: layout считает встроенный Java-движок Smetana
 // (`-Playout=smetana`), внешний graphviz/dot не нужен. Диаграмма подаётся в stdin
 // (`-pipe`), результат читается из stdout — имя выходного файла задаёт c4builder,
@@ -53,21 +97,32 @@ export const httpGet = async (url) => {
 // ditaa рендерит собственный движок (layout не участвует), а `-Playout=smetana`
 // на нём меняет размер холста — поэтому для ditaa флаг не передаётся (выход
 // байт-в-байт совпадает с историческим).
-export const renderDiagram = (content, { javaBin, jarPath, includePath, format, charset, isDitaa }) => new Promise((resolve, reject) => {
-    const argv = [
-        '-Djava.awt.headless=true',
-        `-Dplantuml.include.path=${includePath}`,
-        `-Dsun.java2d.fontpath=prepend:${FONTS_DIR}`,
-        '-jar',
-        jarPath,
-        ...(isDitaa ? [] : ['-Playout=smetana']),
-        `-SdefaultFontName=${DEFAULT_FONT_NAME}`,
-        '-charset',
-        charset,
-        `-t${format}`,
-        '-pipe'
-    ];
-    const child = spawn(javaBin, argv);
+//
+// Оба имени шрифта пиним явно. `-SdefaultFontName` покрывает текст, а бэджи классов
+// (буквы «C»/«A»/«I» в кружках) PlantUML рисует КРИВЫМИ отдельного шрифта
+// CircledCharacterFontName: без пина это логический шрифт JVM, который резолвит
+// системный fontconfig (Ubuntu → DejaVu/TrueType, Arch → Nimbus/CFF) — контуры
+// расходятся между ОС. С пином шрифт берётся из vendor/fonts (JRE своих не несёт,
+// freetype у Temurin бандлед), и SVG получается одинаковым везде.
+// ditaa этим не лечится: его движок берёт AWT-шрифт мимо обеих опций.
+// useSystemFonts убирает все три шрифтовых аргумента — рендер как до пина (машинозависим).
+export const renderArgv = ({ jarPath, includePath, format, charset, isDitaa, useSystemFonts }) => [
+    '-Djava.awt.headless=true',
+    `-Dplantuml.include.path=${includePath}`,
+    ...(useSystemFonts ? [] : [`-Dsun.java2d.fontpath=prepend:${FONTS_DIR}`]),
+    '-jar',
+    jarPath,
+    ...(isDitaa ? [] : ['-Playout=smetana']),
+    ...(useSystemFonts
+        ? []
+        : [`-SdefaultFontName=${DEFAULT_FONT_NAME}`, `-SCircledCharacterFontName=${DEFAULT_FONT_NAME}`]),
+    '-charset',
+    charset,
+    `-t${format}`,
+    '-pipe'
+];
+export const renderDiagram = (content, options) => new Promise((resolve, reject) => {
+    const child = spawn(options.javaBin, renderArgv(options));
     const stdout = [];
     const stderr = [];
     // stdio по умолчанию 'pipe' → потоки заведомо не null; берём их деструктуризацией
@@ -76,17 +131,49 @@ export const renderDiagram = (content, { javaBin, jarPath, includePath, format,
     if (!stdin || !childOut || !childErr) {
         return reject(new Error('PlantUML: не удалось открыть stdio-потоки процесса java'));
     }
+    // Smetana печатает диагностический шум (UNSURE_ABOUT…) — это не ошибка
+    // рендера, пользователю не показываем; остальной stderr пробрасываем.
+    const cleanStderr = () => Buffer.concat(stderr)
+        .toString('utf8')
+        .split('\n')
+        .filter((line) => line.trim() && !/UNSURE_ABOUT/.test(line))
+        .join('\n');
+    let settled = false;
+    let sigkillTimer;
+    const timer = setTimeout(() => {
+        if (settled)
+            return;
+        settled = true;
+        // JVM завис: мягко SIGTERM, затем жёстко SIGKILL, если не среагировал.
+        child.kill('SIGTERM');
+        sigkillTimer = setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS);
+        sigkillTimer.unref();
+        const tail = cleanStderr();
+        reject(new Error(`PlantUML не завершился за ${RENDER_TIMEOUT_MS / 1000} c и был прерван` +
+            (tail ? `\n${tail}` : '')));
+    }, RENDER_TIMEOUT_MS);
+    timer.unref();
+    const clearTimers = () => {
+        clearTimeout(timer);
+        if (sigkillTimer)
+            clearTimeout(sigkillTimer);
+    };
     childOut.on('data', (chunk) => stdout.push(chunk));
     childErr.on('data', (chunk) => stderr.push(chunk));
-    child.on('error', reject); // java не найдена и пр.
+    child.on('error', (err) => {
+        // java не найдена и пр.
+        clearTimers();
+        if (settled)
+            return;
+        settled = true;
+        reject(err);
+    });
     child.on('close', (code) => {
-        // Smetana печатает диагностический шум (UNSURE_ABOUT…) — это не ошибка
-        // рендера, пользователю не показываем; остальной stderr пробрасываем.
-        const errText = Buffer.concat(stderr)
-            .toString('utf8')
-            .split('\n')
-            .filter((line) => line.trim() && !/UNSURE_ABOUT/.test(line))
-            .join('\n');
+        clearTimers(); // гасим таймеры даже если сработал timeout (не убиваем чужой PID)
+        if (settled)
+            return;
+        settled = true;
+        const errText = cleanStderr();
         if (code !== 0) {
             return reject(new Error(`PlantUML завершился с кодом ${code}\n${errText}`));
         }
@@ -102,9 +189,14 @@ export const renderDiagram = (content, { javaBin, jarPath, includePath, format,
 // по чексумме. Его lifecycle (создание/удаление) держит оркестратор build(); сюда
 // путь приходит явным параметром, а не пересчитывается из общей константы.
 export const generateImages = async (tree, options, onImageGenerated, cacheConf, bkFolderName) => {
-    // Get the old checksums (from last run) of all PUML-files
-    const oldChecksums = cacheConf.get('checksums') || [];
-    const newChecksums = [];
+    // Чексуммы прошлого прогона — в Set: попадание проверяется O(1) на диаграмму
+    // (было O(N) find → O(N²) на всё дерево).
+    const oldChecksums = new Set(cacheConf.get('checksums') || []);
+    // Каждой диаграмме — запись в порядке обхода дерева; ok выставляется задачей при
+    // УСПЕХЕ (рендер или восстановление из бэкапа). В кеш пишем только успешные: иначе
+    // упавший прогон терял бы чексуммы уже отрендеренных → их полный перерендер на
+    // следующем запуске (см. persist в finally ниже).
+    const checksumEntries = [];
     let totalImages = 0;
     let processedImages = 0;
     // Рендерим единственным вендорным JAR — выбора версии больше нет. Легаси-ключ
@@ -117,17 +209,37 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
         console.log(chalk.yellow(`Выбор версии PlantUML удалён — сборка идёт вендорным JAR ${VENDORED_JAR.version}. ` +
             `Ключ plantumlVersion: "${pinned}" в .c4builder можно убрать.`));
     }
-    // JRE резолвится ЛЕНИВО и один раз за сборку: только если в дереве есть хотя бы одна
-    // PlantUML-диаграмма. Проект целиком на D2 java не трогает (скачивание не инициируется).
-    const needsJava = tree.some((item) => item.diagrams.some((d) => d.engine === 'plantuml'));
-    let javaBin = null;
-    if (needsJava) {
-        javaBin = (await resolveJava({ log: (m) => console.log(chalk.gray(m)) })).path;
-    }
+    // JRE резолвится ЛЕНИВО и один раз за сборку: только когда встретилась PlantUML-
+    // диаграмма, которую РЕАЛЬНО надо рендерить (кэш не сработал — restore-путь ниже
+    // делает continue до создания render-задачи). Проект целиком на D2 либо полностью
+    // восстановленный из бэкапа java не трогает — важно для офлайн-пересборки готового
+    // проекта на машине без установленной java (иначе резолв инициировал бы скачивание).
+    let javaPromise = null;
+    const getJava = () => {
+        if (!javaPromise) {
+            javaPromise = resolveJava({ log: (m) => console.log(chalk.gray(m)) }).then((r) => r.path);
+        }
+        return javaPromise;
+    };
     for (const item of tree) {
         totalImages += item.diagrams.length;
     }
-    const taskList = [];
+    // Прогресс инкрементируем по ЗАВЕРШЕНИИ каждой задачи. Порядок завершения при
+    // конкурентности недетерминирован (сообщения `processed X/Y` могут идти вразнобой),
+    // но X монотонно растёт и финал = totalImages. Инкремент атомарен (один event-loop).
+    const withProgress = (task) => async () => {
+        await task();
+        processedImages++;
+        if (onImageGenerated)
+            onImageGenerated(processedImages, totalImages);
+    };
+    // D2-задачи гоняем отдельной очередью с конкурентностью 1: @terrastruct/d2 держит
+    // ЕДИНСТВЕННЫЙ worker с одним currentResolve/currentReject без корреляции запросов —
+    // два параллельных renderD2 затирают колбэк друг друга (промис виснет / результаты
+    // перепутываются). Движок всё равно однопоточный, так что сериализация D2 бесплатна.
+    // PlantUML — отдельные процессы java, их гоняем пулом renderConcurrency().
+    const d2Tasks = [];
+    const otherTasks = [];
     for (const item of tree) {
         for (const diagram of item.diagrams) {
             // Чексумма = контент диаграммы + свёрнутый граф её зависимостей, чтобы
@@ -140,59 +252,103 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             const includes = entryPath !== null
                 ? foldD2Imports(entryPath)
                 : foldIncludes(body, item.dir, item.dir, new Set());
+            const outFormat = diagramOutputFormat(diagram, options);
+            // renderKey: параметры, влияющие на БАЙТЫ вывода помимо контента и графа
+            // импортов. Без него смена layout (D2) или charset (PlantUML) не меняла
+            // чексумму → из бэкапа копировалась старая картинка (новые параметры молча
+            // игнорировались, кэш чистился только через --reset). Формат/движок/версия
+            // движка тоже в ключе: их смена обязана приводить к перерендеру.
+            const renderKey = (entryPath !== null
+                ? `d2\0${d2EngineVersion()}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
+                : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
+                `\0font=${fontCacheTag(options)}`;
             const cksum = crypto
                 .createHash('sha256')
-                .update(body + includes, 'utf-8')
+                .update(body + includes + renderKey, 'utf-8')
                 .digest('hex');
-            const outName = `${path.parse(diagram.dir).name}.${diagramOutputFormat(diagram, options)}`;
+            // Записи копим в порядке обхода дерева, СИНХРОННО и до запуска задач:
+            // порядок массива не зависит от того, кто из воркеров финиширует раньше —
+            // .c4builder.cache детерминирован (важно для сравнения кэша между сборками).
+            const cksumEntry = { cksum, ok: false };
+            checksumEntries.push(cksumEntry);
+            const outName = `${path.parse(diagram.dir).name}.${outFormat}`;
             // path to backup image file
             const bkFilePath = path.join(bkFolderName, item.dir.replace(options.ROOT_FOLDER, ''), outName);
             // path to image in dist folder
             const filePath = path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), outName);
             // if checksum exists (diagram untouched) and file/image exists - copy image back from backup folder
-            if (oldChecksums.find((x) => x === cksum) && (await fs.existsSync(bkFilePath))) {
-                await fsextra.copyFileSync(bkFilePath, filePath);
+            if (oldChecksums.has(cksum) && fs.existsSync(bkFilePath)) {
+                // Восстановление из бэкапа — без рендера; JVM/worker не задействованы,
+                // поэтому кладём в общий пул (kind не важен).
+                otherTasks.push(withProgress(async () => {
+                    fsextra.copyFileSync(bkFilePath, filePath);
+                    cksumEntry.ok = true;
+                }));
+                continue;
             }
-            else {
-                const outFormat = diagramOutputFormat(diagram, options);
-                // PNG-выход не-ditaa диаграмм — растеризацией SVG (resvg), а не нативным
-                // движком: единый детерминированный PNG для PlantUML и D2. ditaa остаётся
-                // нативным PlantUML-PNG (у него нет SVG-представления) — не растеризуем.
-                const needsRaster = outFormat === 'png' && !diagram.isDitaa;
+            // PNG-выход не-ditaa диаграмм — растеризацией SVG (resvg), а не нативным
+            // движком: единый детерминированный PNG для PlantUML и D2. ditaa остаётся
+            // нативным PlantUML-PNG (у него нет SVG-представления) — не растеризуем.
+            const needsRaster = outFormat === 'png' && !diagram.isDitaa;
+            const diagramContent = diagram.content;
+            const includePath = item.dir;
+            const isDitaa = diagram.isDitaa;
+            const task = withProgress(async () => {
                 // render diagram to image: D2 через WASM, PlantUML — прямым вызовом java.
                 // Для растеризации PlantUML не-ditaa рендерим в svg (не -tpng), затем resvg.
                 let rendered;
-                if (entryPath !== null) {
-                    rendered = renderD2(entryPath, { layout: options.D2_LAYOUT });
+                try {
+                    if (entryPath !== null) {
+                        rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT });
+                    }
+                    else {
+                        // Резолв JRE отложен до первого реального PlantUML-рендера (эта
+                        // ветка исполняется лишь при промахе кэша). getJava мемоизирует.
+                        const javaBin = await getJava();
+                        rendered = await renderDiagram(diagramContent, {
+                            javaBin,
+                            jarPath,
+                            includePath,
+                            format: needsRaster ? 'svg' : outFormat,
+                            charset: options.CHARSET,
+                            isDitaa,
+                            useSystemFonts: options.USE_SYSTEM_FONTS
+                        });
+                    }
+                    const image = needsRaster
+                        ? await rasterizeSvgToPng(rendered, options.USE_SYSTEM_FONTS)
+                        : rendered;
+                    await writeFile(filePath, image);
+                    cksumEntry.ok = true;
                 }
-                else {
-                    // needsJava гарантирует резолв для plantuml-ветки; guard — нарратив для типов.
-                    if (!javaBin)
-                        throw new Error('PlantUML: JRE не резолвнут для plantuml-диаграммы');
-                    rendered = renderDiagram(diagram.content, {
-                        javaBin,
-                        jarPath,
-                        includePath: item.dir,
-                        format: needsRaster ? 'svg' : outFormat,
-                        charset: options.CHARSET,
-                        isDitaa: diagram.isDitaa
-                    });
+                catch (err) {
+                    // Имя диаграммы в ошибку: renderDiagram/renderD2 сами его не знают.
+                    throw new Error(`Диаграмма "${outName}": ${err.message || err}`);
                 }
-                const render = rendered
-                    .then((image) => (needsRaster ? rasterizeSvgToPng(image) : image))
-                    .then((image) => writeFile(filePath, image));
-                taskList.push(render);
-            }
-            const taskPromises = Promise.all(taskList).then(() => {
-                processedImages++;
-                if (onImageGenerated)
-                    onImageGenerated(processedImages, totalImages);
             });
-            await taskPromises;
-            // Add diagram checksum
-            newChecksums.push(cksum);
+            if (entryPath !== null)
+                d2Tasks.push(task);
+            else
+                otherTasks.push(task);
         }
     }
-    // store all puml checksums
-    cacheConf.set('checksums', newChecksums);
+    // PlantUML-пул и D2-очередь работают независимо (процессы java vs WASM-worker) и
+    // параллельно друг другу. allSettled — чтобы падение одной очереди не оставляло
+    // вторую как floating promise с висящими JVM: обе доосушаются, затем бросаем первую
+    // ошибку (приоритет — PlantUML-пул, порядок между очередями не значим).
+    try {
+        const results = await Promise.allSettled([
+            runPool(otherTasks, renderConcurrency()),
+            runPool(d2Tasks, 1)
+        ]);
+        const failed = results.find((r) => r.status === 'rejected');
+        if (failed && failed.status === 'rejected')
+            throw failed.reason;
+    }
+    finally {
+        // Персистим чексуммы даже при частичном падении: успешно обработанные диаграммы
+        // не перерендерятся на следующем прогоне. Вместе с сохранением dist_bk при ошибке
+        // (build.ts) повторный прогон после сбоя чинит только упавшую диаграмму.
+        cacheConf.set('checksums', checksumEntries.filter((e) => e.ok).map((e) => e.cksum));
+    }
 };

package/dist/core/render/fonts.js

@@ -0,0 +1,8 @@
+import path from 'node:path';
+import { VENDOR_DIR } from "../../util/paths.js";
+// Единая точка детерминизма рендера текста. Вендорный шрифт пинуется в ОБА движка:
+// JVM/PlantUML (`-Dsun.java2d.fontpath`, `-SdefaultFontName`) и resvg/PNG
+// (`fontDirs`, `defaultFontFamily`). Значения обязаны совпадать — иначе метрики
+// текста разъедутся и PNG-golden покраснеют. НЕ менять без пересбора эталонов.
+export const FONTS_DIR = path.join(VENDOR_DIR, 'fonts');
+export const DEFAULT_FONT_NAME = 'Nimbus Sans';