@alfacapital-tech/c4builder 0.4.0 → 0.5.0

package/dist/core/render/diagrams.js

@@ -11,6 +11,8 @@ import { httpGetBuffer } from "../../util/http.js";
 // D2-бэкенд: только статические хелперы (парсинг импортов) грузятся сразу; сам
 // движок @terrastruct/d2 тянется лениво внутри renderD2/teardownD2.
 import { renderD2, foldD2Imports } from "./d2renderer.js";
+// BPMN-бэкенд: пакеты движка грузятся лениво внутри renderBpmn.
+import { renderBpmn, BPMN_CACHE_PACKAGES } from "./bpmnrenderer.js";
 import { resolveJava } from "./jre.js";
 // PNG-выход: SVG обоих движков растеризуется resvg (ленивая загрузка внутри модуля).
 import { rasterizeSvgToPng } from "./pngraster.js";
@@ -63,24 +65,43 @@ const runPool = async (tasks, concurrency) => {
     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';
+// Версии пакетов движков (D2, BPMN) для чексуммы кэша (апгрейд движка → перерендер).
+// Читаем package.json лениво и один раз: pure-PlantUML сборки их не трогают.
+const versionCache = new Map();
+const pkgVersion = (name) => {
+    let version = versionCache.get(name);
+    if (version === undefined) {
+        // package.json ищем по путям поиска node_modules, а не require(`${name}/package.json`):
+        // пакеты с полем exports (bpmn-auto-layout) этот подпуть не отдают — версия молча
+        // становилась бы 'unknown', и апгрейд движка не перерисовывал бы диаграммы.
+        try {
+            const paths = createRequire(import.meta.url).resolve.paths(name) ?? [];
+            const dir = paths.find((p) => fs.existsSync(path.join(p, name, 'package.json')));
+            if (!dir)
+                throw new Error(`${name} not found`);
+            version = JSON.parse(fs.readFileSync(path.join(dir, name, 'package.json'), 'utf8')).version;
+        }
+        catch {
+            version = 'unknown';
+        }
+        versionCache.set(name, version);
     }
-    return d2VersionCache;
+    return version;
 };
 // В ключ кеша: смена режима не должна отдавать картинку, отрисованную другим шрифтом
 // (D2 тоже — его PNG растрирует общий resvg).
 export const fontCacheTag = (options) => options.USE_SYSTEM_FONTS ? 'system' : DEFAULT_FONT_NAME;
+// renderKey: параметры, влияющие на БАЙТЫ вывода помимо контента и графа импортов.
+// Без него смена layout (D2) или charset (PlantUML) не меняла чексумму → из бэкапа
+// копировалась старая картинка (новые параметры молча игнорировались, кэш чистился
+// только через --reset). Формат/движок/версия движка тоже в ключе: их смена обязана
+// приводить к перерендеру.
+export const renderKey = (diagram, options, outFormat) => (diagram.engine === 'd2'
+    ? `d2\0${pkgVersion('@terrastruct/d2')}\0layout=${options.D2_LAYOUT}\0fmt=${outFormat}`
+    : diagram.engine === 'bpmn'
+        ? `bpmn\0${BPMN_CACHE_PACKAGES.map(pkgVersion).join('\0')}\0fmt=${outFormat}`
+        : `puml\0${VENDORED_JAR.version}\0charset=${options.CHARSET}\0fmt=${outFormat}\0ditaa=${diagram.isDitaa}`) +
+    `\0font=${fontCacheTag(options)}`;
 export const getMime = (format) => {
     if (format === 'svg')
         return `image/svg+xml`;
@@ -129,7 +150,7 @@ export const renderDiagram = (content, options) => new Promise((resolve, reject)
     // с одним guard вместо non-null assertion на каждом обращении.
     const { stdin, stdout: childOut, stderr: childErr } = child;
     if (!stdin || !childOut || !childErr) {
-        return reject(new Error('PlantUML: не удалось открыть stdio-потоки процесса java'));
+        return reject(new Error('PlantUML: failed to open stdio streams of the java process'));
     }
     // Smetana печатает диагностический шум (UNSURE_ABOUT…) — это не ошибка
     // рендера, пользователю не показываем; остальной stderr пробрасываем.
@@ -149,7 +170,7 @@ export const renderDiagram = (content, options) => new Promise((resolve, reject)
         sigkillTimer = setTimeout(() => child.kill('SIGKILL'), SIGKILL_GRACE_MS);
         sigkillTimer.unref();
         const tail = cleanStderr();
-        reject(new Error(`PlantUML не завершился за ${RENDER_TIMEOUT_MS / 1000} c и был прерван` +
+        reject(new Error(`PlantUML did not finish in ${RENDER_TIMEOUT_MS / 1000} s and was aborted` +
             (tail ? `\n${tail}` : '')));
     }, RENDER_TIMEOUT_MS);
     timer.unref();
@@ -175,7 +196,7 @@ export const renderDiagram = (content, options) => new Promise((resolve, reject)
         settled = true;
         const errText = cleanStderr();
         if (code !== 0) {
-            return reject(new Error(`PlantUML завершился с кодом ${code}\n${errText}`));
+            return reject(new Error(`PlantUML exited with code ${code}\n${errText}`));
         }
         if (errText)
             process.stderr.write(`${errText}\n`);
@@ -192,7 +213,7 @@ export const renderDiagram = (content, options) => new Promise((resolve, reject)
 // сайт остаётся собранным (так же вёл себя онлайн-рендер docsify-plantuml).
 const errorPlaceholderSvg = (name, reason) => {
     const esc = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
-    const lines = [`${name}: диаграмма не отрендерена`, ...reason.split('\n')]
+    const lines = [`${name}: diagram not rendered`, ...reason.split('\n')]
         .flatMap((l) => l.match(/.{1,88}/g) ?? [''])
         .slice(0, 8);
     const w = 720;
@@ -222,8 +243,8 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
     const pinned = options.LEGACY_PLANTUML_VERSION;
     if (pinned && pinned !== 'latest' && pinned !== VENDORED_JAR.version) {
         console.log(chalk.bold(chalk.yellow('WARNING:')));
-        console.log(chalk.yellow(`Выбор версии PlantUML удалён — сборка идёт вендорным JAR ${VENDORED_JAR.version}. ` +
-            `Ключ plantumlVersion: "${pinned}" в .c4builder можно убрать.`));
+        console.log(chalk.yellow(`Choosing the PlantUML version was removed — builds use the vendored JAR ${VENDORED_JAR.version}. ` +
+            `The plantumlVersion: "${pinned}" key can be removed from .c4builder.`));
     }
     // JRE резолвится ЛЕНИВО и один раз за сборку: только когда встретилась PlantUML-
     // диаграмма, которую РЕАЛЬНО надо рендерить (кэш не сработал — restore-путь ниже
@@ -255,29 +276,25 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
     // перепутываются). Движок всё равно однопоточный, так что сериализация D2 бесплатна.
     // PlantUML — отдельные процессы java, их гоняем пулом renderConcurrency().
     const d2Tasks = [];
+    // BPMN рендерится в общем окне jsdom главного потока — параллельность ничего не даёт,
+    // а последовательная очередь исключает гонки на общем состоянии бандла bpmn-js.
+    const bpmnTasks = [];
     const otherTasks = [];
     for (const item of tree) {
         for (const diagram of item.diagrams) {
             // Чексумма = контент диаграммы + свёрнутый граф её зависимостей, чтобы
             // правка включаемого/импортируемого файла инвалидировала кэш: PlantUML —
-            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов.
+            // !include-граф (.iuml и пр.), D2 — граф @/...@-импортов. У BPMN зависимостей нет.
             const body = `${diagram.content || ''}`;
-            // entryPath нужен только D2 (граф импортов + рендер); для PlantUML не считаем.
-            // entryPath !== null ⟺ engine === 'd2' — используем как сужение типа вместо assertion.
-            const entryPath = diagram.engine === 'd2' ? path.join(item.dir, diagram.dir) : null;
-            const includes = entryPath !== null
+            const entryPath = path.join(item.dir, diagram.dir);
+            const isD2 = diagram.engine === 'd2';
+            const isBpmn = diagram.engine === 'bpmn';
+            const includes = isD2
                 ? foldD2Imports(entryPath, body)
-                : foldIncludes(body, item.dir, item.dir, new Set());
+                : isBpmn
+                    ? ''
+                    : 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 outName = `${path.parse(diagram.dir).name}.${outFormat}`;
             const relOut = path.join(item.dir.replace(options.ROOT_FOLDER, ''), outName);
             // Путь выхода — тоже в чексумме: восстановление из бэкапа идёт по паре
@@ -286,7 +303,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             // молча получали бы чужую старую картинку.
             const cksum = crypto
                 .createHash('sha256')
-                .update(`${body}${includes}${renderKey}\0out=${relOut.split(path.sep).join('/')}`, 'utf-8')
+                .update(`${body}${includes}${renderKey(diagram, options, outFormat)}\0out=${relOut.split(path.sep).join('/')}`, 'utf-8')
                 .digest('hex');
             // Записи копим в порядке обхода дерева, СИНХРОННО и до запуска задач:
             // порядок массива не зависит от того, кто из воркеров финиширует раньше —
@@ -323,9 +340,13 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 // Для растеризации PlantUML не-ditaa рендерим в svg (не -tpng), затем resvg.
                 let rendered;
                 try {
-                    if (entryPath !== null) {
+                    if (isD2) {
                         rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT, seed: body });
                     }
+                    else if (isBpmn) {
+                        // Путь для сообщений валидации; у виртуальных страниц — их источник.
+                        rendered = await renderBpmn(body, source ?? path.relative(process.cwd(), entryPath).split(path.sep).join('/'));
+                    }
                     else {
                         // Резолв JRE отложен до первого реального PlantUML-рендера (эта
                         // ветка исполняется лишь при промахе кэша). getJava мемоизирует.
@@ -349,7 +370,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 catch (err) {
                     // Имя диаграммы в ошибку: renderDiagram/renderD2 сами его не знают.
                     const reason = `${err.message || err}`;
-                    const msg = `Диаграмма "${outName}"${source ? ` (${source})` : ''}: ${reason}`;
+                    const msg = `Diagram "${outName}"${source ? ` (${source})` : ''}: ${reason}`;
                     if (!soft)
                         throw new Error(msg);
                     // Диаграммы из markdown-блоков плагинов писались под онлайн-рендер,
@@ -359,20 +380,18 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                     await writeFile(filePath, outFormat === 'png' ? await rasterizeSvgToPng(svg, options.USE_SYSTEM_FONTS) : svg);
                 }
             });
-            if (entryPath !== null)
-                d2Tasks.push(task);
-            else
-                otherTasks.push(task);
+            (isD2 ? d2Tasks : isBpmn ? bpmnTasks : otherTasks).push(task);
         }
     }
-    // PlantUML-пул и D2-очередь работают независимо (процессы java vs WASM-worker) и
-    // параллельно друг другу. allSettled — чтобы падение одной очереди не оставляло
-    // вторую как floating promise с висящими JVM: обе доосушаются, затем бросаем первую
+    // PlantUML-пул, D2- и BPMN-очереди работают независимо (процессы java, WASM-worker,
+    // главный поток) и параллельно друг другу. allSettled — чтобы падение одной очереди не
+    // оставляло другие как floating promise с висящими JVM: все доосушаются, затем бросаем первую
     // ошибку (приоритет — PlantUML-пул, порядок между очередями не значим).
     try {
         const results = await Promise.allSettled([
             runPool(otherTasks, renderConcurrency()),
-            runPool(d2Tasks, 1)
+            runPool(d2Tasks, 1),
+            runPool(bpmnTasks, 1)
         ]);
         const failed = results.find((r) => r.status === 'rejected');
         if (failed && failed.status === 'rejected')

package/dist/core/render/jre.js

@@ -177,15 +177,15 @@ const fetchAssetMeta = async () => {
     const json = await httpGetJson(url, { headers: JRE_UA });
     const asset = Array.isArray(json) ? json.find((a) => a.binary?.package) : null;
     if (!asset) {
-        throw new Error(`Adoptium не отдал JRE-сборку под ${adoptiumOs()}/${adoptiumArch()} (Temurin ${TEMURIN_FEATURE})`);
+        throw new Error(`Adoptium has no JRE build for ${adoptiumOs()}/${adoptiumArch()} (Temurin ${TEMURIN_FEATURE})`);
     }
     const pkg = asset.binary.package;
     if (!pkg.link)
-        throw new Error('Adoptium не вернул ссылку на архив JRE');
+        throw new Error('Adoptium returned no JRE archive link');
     // Отсутствие checksum — ошибка, а не молчаливый пропуск проверки целостности.
     if (!pkg.checksum) {
-        throw new Error(`Adoptium не вернул sha256 для ${pkg.name || 'архива JRE'}: ` +
-            'отказ принимать архив без проверки целостности');
+        throw new Error(`Adoptium returned no sha256 for ${pkg.name || 'the JRE archive'}: ` +
+            'refusing to accept an archive without an integrity check');
     }
     return { link: pkg.link, sha256: pkg.checksum, name: pkg.name, release: asset.release_name };
 };
@@ -202,9 +202,9 @@ const downloadAndVerify = async (link, expectedSha, destFile) => {
     });
     const actual = hash.digest('hex').toLowerCase();
     if (!expectedSha)
-        throw new Error('Нет ожидаемого sha256 — проверка целостности архива невозможна');
+        throw new Error('No expected sha256 — cannot verify archive integrity');
     if (actual !== expectedSha.toLowerCase()) {
-        throw new Error(`sha256 архива не совпал: ожидалось ${expectedSha}, получено ${actual}`);
+        throw new Error(`archive sha256 mismatch: expected ${expectedSha}, got ${actual}`);
     }
 };
 const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : extractTarGz(archive, destDir);
@@ -223,13 +223,13 @@ const downloadJre = async ({ log } = {}) => {
     const stageDir = `${dir}.tmp-${process.pid}`;
     try {
         if (log)
-            log(`Скачивание Temurin ${TEMURIN_FEATURE} JRE (${meta.release || meta.name})…`);
+            log(`Downloading Temurin ${TEMURIN_FEATURE} JRE (${meta.release || meta.name})…`);
         await downloadAndVerify(meta.link, meta.sha256, tmpArchive);
         fs.rmSync(stageDir, { recursive: true, force: true });
         fs.mkdirSync(stageDir, { recursive: true });
         await extractArchive(tmpArchive, stageDir, isZip);
         if (!findJavaUnder(stageDir)) {
-            throw new Error('JRE распакован, но исполняемый bin/java не найден');
+            throw new Error('JRE extracted, but the bin/java executable was not found');
         }
         fs.writeFileSync(markerPath(stageDir), JSON.stringify({
             schema: JRE_CACHE_SCHEMA,
@@ -261,15 +261,15 @@ const downloadJre = async ({ log } = {}) => {
     }
     const bin = findJavaUnder(dir);
     if (!bin)
-        throw new Error('JRE распакован, но исполняемый bin/java не найден');
+        throw new Error('JRE extracted, but the bin/java executable was not found');
     return { path: bin, source: 'download' };
 };
 const failureMessage = (cause) => [
-    'Не удалось получить Java для рендеринга PlantUML-диаграмм.',
-    'Ни системная java (17+), ни кеш, ни скачивание с Adoptium не сработали. Сделайте одно из двух:',
-    '  • установите JRE 17+ (например, Eclipse Temurin) — java на PATH или задайте JAVA_HOME;',
-    '  • выполните `c4builder jre install`, чтобы загрузить JRE в локальный кеш.',
-    cause?.message ? `Причина: ${cause.message}` : ''
+    'Could not get Java to render PlantUML diagrams.',
+    'Neither system java (17+), the cache, nor a download from Adoptium worked. Do one of the following:',
+    '  • install JRE 17+ (e.g. Eclipse Temurin) — java on PATH or set JAVA_HOME;',
+    '  • run `c4builder jre install` to download a JRE into the local cache.',
+    cause?.message ? `Cause: ${cause.message}` : ''
 ]
     .filter(Boolean)
     .join('\n');

package/dist/core/render/pngraster.js

@@ -6,7 +6,7 @@ import { FONTS_DIR, DEFAULT_FONT_NAME } from "./fonts.js";
 // растеризации, не на импорте модуля).
 const require = createRequire(import.meta.url);
 let resvgMod = null;
-const getResvg = () => {
+export const getResvg = () => {
     if (resvgMod)
         return resvgMod;
     try {
@@ -14,9 +14,9 @@ const getResvg = () => {
     }
     catch (err) {
         const e = err;
-        throw new Error('Для PNG-вывода (DIAGRAM_FORMAT=png) нужен пакет @resvg/resvg-js.\n' +
-            'Установите его: npm install @resvg/resvg-js\n' +
-            `Исходная ошибка: ${e.message || e}`);
+        throw new Error('PNG output (DIAGRAM_FORMAT=png) requires the @resvg/resvg-js package.\n' +
+            'Install it: npm install @resvg/resvg-js\n' +
+            `Original error: ${e.message || e}`);
     }
     return resvgMod;
 };

package/dist/{plugins/openspec → core/scan}/fences.js

@@ -1,7 +1,7 @@
-// Fenced-блоки ```plantuml / ```d2 в артефактах → диаграммы страницы (рендер общим
-// локальным движком) + ссылка `![…](name.ext)` на их месте: compose подставит картинку
-// inline, а клиентский docsify-plantuml (онлайн-рендер в браузере) не сработает —
-// fence в выводе уже отсутствует.
+// Fenced-блоки диаграмм в markdown (страницы проекта, артефакты плагинов) → диаграммы
+// страницы (рендер общим локальным движком) + ссылка `![…](name.ext)` на их месте:
+// compose подставит картинку inline, а клиентский docsify-plantuml (онлайн-рендер в
+// браузере) не сработает — fence в выводе уже отсутствует.
 import crypto from 'node:crypto';
 // Fenced-блок по CommonMark: открывающая ``` или ~~~ (≥3) с любым отступом (fence в
 // списке), инфо-строка, тело (может быть пустым), закрывающая того же вида не короче
@@ -19,18 +19,19 @@ export const mapOutsideFences = (md, fn) => {
     return out + fn(md.slice(last));
 };
 /**
- * Экстрактор диаграмм одной страницы. Имя файла — `<base>-<sha1 контента>`: не зависит
- * от позиции fence, поэтому вставка/удаление соседнего блока не сдвигает имена и не
- * подсовывает картинку соседа из кэша; одинаковые блоки дают одну диаграмму.
+ * Экстрактор диаграмм одной страницы; извлекаются только блоки языков `langs` (из
+ * plantuml/puml/d2), остальные остаются кодом. Имя файла — `<base>-<sha1 контента>`: не
+ * зависит от позиции fence, поэтому вставка/удаление соседнего блока не сдвигает имена и
+ * не подсовывает картинку соседа из кэша; одинаковые блоки дают одну диаграмму.
  */
-export const createFenceExtractor = () => {
+export const createFenceExtractor = (langs) => {
     const seen = new Set();
     return {
         extract(md, base, source) {
             const diagrams = [];
             const markdown = md.replace(FENCE_RE, (whole, indent, _fence, info, body) => {
                 const lang = info.trim().split(/\s+/)[0]?.toLowerCase() ?? '';
-                const ext = ENGINE_EXT[lang];
+                const ext = langs.includes(lang) ? ENGINE_EXT[lang] : undefined;
                 if (!ext)
                     return whole;
                 // Отступ fence (в списке) снимаем со строк тела, как CommonMark.
@@ -45,7 +46,7 @@ export const createFenceExtractor = () => {
                 const file = `${base}-${hash}${ext}`;
                 if (!seen.has(file)) {
                     seen.add(file);
-                    // soft: блок в артефакте — не файл проекта; синтаксическая
+                    // soft: блок в markdown — не файл диаграммы; синтаксическая
                     // ошибка в нём не должна ронять весь сайт (раньше такие блоки
                     // рендерил браузер и показывал картинку с ошибкой).
                     diagrams.push({ file, content, source, soft: true });

package/dist/core/scan/tree.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import fsextra from 'fs-extra';
 import { makeDirectory, readFile } from "../../util/utils.js";
+import { createFenceExtractor } from "./fences.js";
 // Единый реестр движков диаграмм: расширение (с точкой) → рендерер + способности.
 // ЕДИНСТВЕННЫЙ источник истины о том, какие файлы считаются диаграммами. Из него
 // строятся фильтр scan (ниже), regex ссылок в compose/markdown.ts и ветвление
@@ -9,7 +10,8 @@ import { makeDirectory, readFile } from "../../util/utils.js";
 // здесь; фазы подхватят его без синхронной правки.
 export const DIAGRAM_ENGINES = [
     { ext: '.puml', engine: 'plantuml', remoteRender: true },
-    { ext: '.d2', engine: 'd2', remoteRender: false }
+    { ext: '.d2', engine: 'd2', remoteRender: false },
+    { ext: '.bpmn', engine: 'bpmn', remoteRender: false }
 ];
 // Расширение (lowercase, с точкой) → движок. undefined ⇒ файл не диаграмма.
 export const engineForExt = (ext) => DIAGRAM_ENGINES.find((e) => e.ext === ext)?.engine;
@@ -73,10 +75,25 @@ export const generateTree = async (dir, options) => {
                 await build(childDir, dir);
             }
         }
+        // Блоки ```plantuml в страницах рендерим при сборке: иначе текст диаграммы доезжал
+        // до браузера и клиентский docsify-plantuml (в т.ч. в пользовательских шаблонах)
+        // отправлял его на plantuml.com. puml/d2 остаются кодом — так показывают исходник.
+        const fences = createFenceExtractor(['plantuml']);
         const mdFiles = files.filter((x) => path.extname(x).toLowerCase() === '.md');
         for (const mdFile of mdFiles) {
-            const fileContents = await readFile(path.join(dir, mdFile));
-            item.mdFiles.push(fileContents);
+            const mdPath = path.join(dir, mdFile);
+            const { markdown, diagrams } = fences.extract((await readFile(mdPath)).toString(), path.parse(mdFile).name, path.relative(process.cwd(), mdPath).split(path.sep).join('/'));
+            item.mdFiles.push(markdown);
+            for (const d of diagrams)
+                item.diagrams.push({
+                    dir: d.file,
+                    ext: '.puml',
+                    engine: 'plantuml',
+                    content: d.content,
+                    isDitaa: /@startditaa/i.test(d.content),
+                    source: d.source,
+                    soft: d.soft
+                });
         }
         // Диаграммы: расширение → движок берём из DIAGRAM_ENGINES. Поле dir — имя файла
         // (историческое), engine выбирает рендерер, isDitaa — только для PlantUML.
@@ -91,7 +108,7 @@ export const generateTree = async (dir, options) => {
             item.diagrams.push({ dir: diagramFile, ext, engine, content: fileContents, isDitaa });
         }
         item.diagrams.sort((a, b) => `${a.dir}`.localeCompare(b.dir));
-        //copy all other files (.d2 исходники, как и .puml, не копируем — они рендерятся)
+        //copy all other files (.d2/.bpmn исходники, как и .puml, не копируем — они рендерятся)
         const otherFiles = options.EXCLUDE_OTHER_FILES
             ? []
             : files.filter((x) => {
@@ -118,8 +135,8 @@ export const generateTree = async (dir, options) => {
         for (const d of item.diagrams) {
             const out = `${path.parse(d.dir).name}.${diagramOutputFormat(d, options)}`;
             if (seen.has(out))
-                throw new Error(`Коллизия имени выхода '${out}' в ${item.dir}: '${seen.get(out)}' и '${d.dir}' ` +
-                    `рендерятся в один файл. Переименуйте одну из диаграмм.`);
+                throw new Error(`Output name collision '${out}' in ${item.dir}: '${seen.get(out)}' and '${d.dir}' ` +
+                    `render to the same file. Rename one of the diagrams.`);
             seen.set(out, d.dir);
         }
     }
@@ -131,14 +148,13 @@ export const generateTree = async (dir, options) => {
 // build() — в watch-режиме иначе отдавались бы устаревшие данные.
 const includeReadCache = new Map();
 export const clearIncludeCache = () => includeReadCache.clear();
-// Свернуть локальные !include (.iuml и пр.) диаграммы в материал для чексуммы — рекурсивно.
-// Иначе правка включённого .iuml не инвалидирует кэш и на сайт уезжает устаревший рендер.
+// Локальные !include (.iuml и пр.) диаграммы рекурсивно, в DFS-порядке: каждый файл —
+// один раз (visited). Один резолвер на чексумму кэша (foldIncludes) и приложение
+// llms-full.txt — иначе граф зависимостей у них разъехался бы.
 // URL (!include https://…) и stdlib (!include <…>) пропускаем: локально не меняются.
-// Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит от
-// машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
-export const foldIncludes = (content, fileDir, searchDir, visited) => {
+export const collectIncludes = (content, fileDir, searchDir, visited) => {
     const re = /^[ \t]*!include(?:_once|_many|sub|url)?[ \t]+(.+?)[ \t]*$/gim;
-    let out = '';
+    const out = [];
     let m;
     // biome-ignore lint/suspicious/noAssignInExpressions: идиома regex.exec() в условии while
     while ((m = re.exec(content)) !== null) {
@@ -166,8 +182,15 @@ export const foldIncludes = (content, fileDir, searchDir, visited) => {
         }
         if (inc === null)
             continue;
-        out += ` ${path.relative(process.cwd(), resolved).split(path.sep).join('/')} ${inc}`;
-        out += foldIncludes(inc, path.dirname(resolved), searchDir, visited); // вложенные include
+        out.push({ abs: resolved, content: inc });
+        out.push(...collectIncludes(inc, path.dirname(resolved), searchDir, visited)); // вложенные include
     }
     return out;
 };
+// Свернуть include-граф диаграммы в материал для чексуммы: правка включённого .iuml
+// обязана инвалидировать кэш, иначе на сайт уезжает устаревший рендер.
+// Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит от
+// машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
+export const foldIncludes = (content, fileDir, searchDir, visited) => collectIncludes(content, fileDir, searchDir, visited)
+    .map((inc) => ` ${path.relative(process.cwd(), inc.abs).split(path.sep).join('/')} ${inc.content}`)
+    .join('');

package/dist/plugins/openapi/index.js

@@ -8,7 +8,7 @@ import { z } from 'zod';
 import { outputDirs } from "../../config/options.js";
 import { redactUrl } from "../../core/plugins/source.js";
 import { definePlugin } from "../../core/plugins/types.js";
-import { globFiles } from "../../util/glob.js";
+import { isPathInside } from "../../util/archive.js";
 import { VENDOR_DIR } from "../../util/paths.js";
 import { encodeURIPath } from "../../util/utils.js";
 const optionsSchema = z
@@ -22,8 +22,17 @@ const optionsSchema = z
 })
     .strict()
     .refine((o) => (o.dir === undefined) !== (o.archive === undefined), {
-    message: 'нужен ровно один источник: dir либо archive'
+    message: 'exactly one source required: dir or archive'
 });
+// Файлы под root по glob: posix-пути, сортировка. Каталоги с точкой (.git) fs.glob не
+// обходит сам. Выходные каталоги (skip) отсеиваются по результату, а не в exclude:
+// под `**` Node передаёт в exclude лишь имя записи, и вложенный `x/docs` был бы
+// неотличим от корневого `docs`.
+const findFiles = (root, pattern, skip) => fs
+    .globSync(pattern, { cwd: root, exclude: (p) => path.basename(p) === 'node_modules' })
+    .filter((rel) => !skip.some((d) => isPathInside(d, path.resolve(root, rel))))
+    .map((rel) => rel.split(path.sep).join('/'))
+    .sort();
 // Имя страницы: родительская папка спеки; в корне источника — имя файла без расширения.
 const pageName = (rel) => {
     const dir = path.posix.dirname(rel);
@@ -52,20 +61,20 @@ export default definePlugin({
         // Источник может быть предком выходного каталога (dir: '.') — свои же копии
         // спек прошлой сборки в dist/dist_bk не считаются источником.
         const skip = outputDirs(ctx.options);
-        const files = globFiles(root, o.glob, skip);
+        const files = findFiles(root, o.glob, skip);
         if (!files.length)
-            throw new Error(`по шаблону "${o.glob}" в ${source} не найдено ни одной спеки`);
+            throw new Error(`no specs match "${o.glob}" in ${source}`);
         const names = new Map();
         for (const rel of files) {
             const name = pageName(rel);
             const dup = names.get(name);
             if (dup)
-                throw new Error(`две спеки дают одно имя страницы "${name}": ${dup} и ${rel}`);
+                throw new Error(`two specs give the same page name "${name}": ${dup} and ${rel}`);
             names.set(name, rel);
         }
         // Статикой в dist — все yaml/json источника, а не только совпавшие с glob: $ref
         // может вести в общие схемы (components), не являющиеся спеками.
-        for (const rel of globFiles(root, '**/*.{yaml,yml,json}', skip)) {
+        for (const rel of findFiles(root, '**/*.{yaml,yml,json}', skip)) {
             const dest = path.join(ctx.options.DIST_FOLDER, mount, '_specs', rel);
             fs.mkdirSync(path.dirname(dest), { recursive: true });
             fs.copyFileSync(path.join(root, rel), dest);
@@ -79,6 +88,7 @@ export default definePlugin({
         for (const [name, rel] of sorted) {
             // Спека грузится swagger-ui по ссылке от корня сайта (SPA: base = index.html);
             // относительные $ref внутри спек резолвятся от её URL — структура сохранена.
+            // validatorUrl: null — иначе swagger-ui шлёт адрес спеки на validator.swagger.io.
             const specUrl = encodeURIPath(path.posix.join(mount, '_specs', rel));
             const domId = `swagger-${name.replace(/[^A-Za-z0-9_-]/g, '_')}`;
             ctx.addPage({
@@ -86,7 +96,7 @@ export default definePlugin({
                 markdown: [
                     `<div id="${domId}"></div>`,
                     '<script>',
-                    `SwaggerUIBundle({ url: '${specUrl}', dom_id: '#${domId}' });`,
+                    `SwaggerUIBundle({ url: '${specUrl}', dom_id: '#${domId}', validatorUrl: null });`,
                     '</script>'
                 ].join('\n')
             });

package/dist/plugins/openspec/index.js

@@ -22,7 +22,7 @@ export default definePlugin({
     afterScan(ctx, o) {
         const storeDir = path.resolve(o.dir);
         if (!fs.existsSync(storeDir))
-            throw new Error(`OpenSpec store не найден: ${storeDir} (опция dir плагина openspec)`);
+            throw new Error(`OpenSpec store not found: ${storeDir} (dir option of the openspec plugin)`);
         const store = scanStore(storeDir);
         const { mount } = o;
         const { options } = ctx;

package/dist/plugins/openspec/render.js

@@ -1,8 +1,8 @@
 // Markdown страниц раздела OpenSpec: сводка, change и его подстраницы, индексы подразделов.
 import fs from 'node:fs';
 import path from 'node:path';
+import { createFenceExtractor, mapOutsideFences } from "../../core/scan/fences.js";
 import { encodeURIPath } from "../../util/utils.js";
-import { createFenceExtractor, mapOutsideFences } from "./fences.js";
 // Ссылка на страницу сайта от корня (без ведущего «/»): так же строится sidebar,
 // а docsify без relativePath резолвит ссылки от корня сайта.
 export const pageLink = (segments, options) => encodeURIPath(path.posix.join(...segments, options.WEB_FILE_NAME || segments[segments.length - 1]));
@@ -80,6 +80,9 @@ const ignoreTitle = (title) => {
 };
 /** Путь файла для сообщений — от cwd, чтобы его можно было открыть как есть. */
 export const relSource = (root, rel) => path.relative(process.cwd(), path.join(root, rel)).split(path.sep).join('/');
+// В артефактах OpenSpec любой блок диаграммы — иллюстрация, а не пример исходника
+// (в отличие от страниц проекта, где извлекается только ```plantuml).
+const FENCE_LANGS = ['plantuml', 'puml', 'd2'];
 /**
  * Markdown одного исходного файла → страница сайта: fenced-диаграммы вырезаются, ссылки
  * на другие страницы источника (`target`, `#x` → `?id=x`) — на их адреса, прочие
@@ -88,7 +91,7 @@ export const relSource = (root, rel) => path.relative(process.cwd(), path.join(r
  * `fromDir` — posix-каталог файла относительно `srcRoot` (ссылки в нём резолвятся от файла).
  */
 export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', target = () => undefined, source, options }) => {
-    const { markdown, diagrams } = createFenceExtractor().extract(content, base, source);
+    const { markdown, diagrams } = createFenceExtractor(FENCE_LANGS).extract(content, base, source);
     const files = [];
     const rewrite = (t) => t.replace(LINK_RE, (whole, bang, text, href, title = '') => {
         const inner = text.includes('![') ? rewrite(text) : text;

package/dist/util/archive.js

@@ -20,7 +20,7 @@ export const extractZip = (archive, destDir) => new Promise((resolve, reject) =>
         zip.on('entry', (entry) => {
             // zip-slip: злонамеренная запись `../../evil` вышла бы за destDir.
             if (!isPathInside(destDir, entry.fileName)) {
-                return reject(new Error(`Небезопасный путь в архиве (выход за каталог): ${entry.fileName}`));
+                return reject(new Error(`Unsafe path in archive (escapes the folder): ${entry.fileName}`));
             }
             // Симлинки пропускаем: в недоверенном архиве симлинк мог бы указывать
             // за пределы каталога.

package/dist/util/http.js

@@ -25,21 +25,21 @@ export const httpGetStream = (url, opts = {}) => {
             if (status >= 300 && status < 400 && location) {
                 res.resume();
                 if (redirectsLeft <= 0) {
-                    return reject(new Error(`Слишком много редиректов (>${MAX_REDIRECTS}) для ${url}`));
+                    return reject(new Error(`Too many redirects (>${MAX_REDIRECTS}) for ${url}`));
                 }
                 const next = new URL(location, url).toString();
                 return resolve(httpGetStream(next, { headers, redirectsLeft: redirectsLeft - 1 }));
             }
             if (status < 200 || status > 299) {
                 res.resume();
-                return reject(new Error(`Не удалось загрузить ${url}, код ответа: ${status}`));
+                return reject(new Error(`Failed to download ${url}, status code: ${status}`));
             }
             // Коннект установлен → с таймаута коннекта переключаемся на таймаут простоя
             // приёма (крупный ответ тянется дольше): молчащий сокет уронит таймаут.
             req.setTimeout(IDLE_TIMEOUT_MS);
             resolve(res);
         });
-        req.on('timeout', () => req.destroy(new Error(`Таймаут сети (${url})`)));
+        req.on('timeout', () => req.destroy(new Error(`Network timeout (${url})`)));
         req.on('error', reject);
     });
 };