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

package/dist/core/plugins/source.js

@@ -0,0 +1,92 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { httpGetBuffer } from "../../util/http.js";
+import { extractTarGz, extractZip } from "../../util/archive.js";
+// Кэш скачанных архивов на процесс: в watch-режиме повторные сборки не качают заново.
+// Ключ — URL; каталог на диске — по sha1(URL) в tmp, чистить не нужно.
+const archiveCache = new Map();
+// Формат по магическим байтам, а не по расширению: URL archive-API часто без него
+// (`…/archive?format=zip`). zip — `PK\x03\x04`, gzip — `\x1f\x8b`.
+const isZipBuffer = (b) => b.length > 3 && b[0] === 0x50 && b[1] === 0x4b && b[2] === 3 && b[3] === 4;
+const isGzipBuffer = (b) => b.length > 1 && b[0] === 0x1f && b[1] === 0x8b;
+// URL для сообщений: без query и userinfo — токен, переданный в URL
+// (`?private_token=${TOKEN}`), не должен попадать в логи сборки/CI.
+export const redactUrl = (url) => {
+    try {
+        const u = new URL(url);
+        return `${u.origin}${u.pathname}`;
+    }
+    catch {
+        return url;
+    }
+};
+// За корпоративным TLS-перехватом Node не доверяет подменённой цепочке: свой набор
+// корней он берёт не из системы и не из SSL_CERT_FILE — только NODE_EXTRA_CA_CERTS.
+export const tlsHint = (reason) => /certificate|self.signed|unable to (?:verify|get local issuer)/i.test(reason)
+    ? ' — TLS-перехват? укажите путь к CA-бандлу в NODE_EXTRA_CA_CERTS'
+    : '';
+const downloadArchive = async (url, headers) => {
+    const dir = path.join(os.tmpdir(), `c4builder-src-${crypto.createHash('sha1').update(url).digest('hex')}`);
+    // Распаковываем в свой staging и заменяем кэш атомарным rename — параллельная
+    // сборка того же URL не увидит полураспакованный каталог.
+    const stage = `${dir}.tmp-${process.pid}`;
+    const archive = `${stage}.archive`;
+    let body;
+    try {
+        body = await httpGetBuffer(url, { headers });
+    }
+    catch (e) {
+        const reason = e.message.replaceAll(url, redactUrl(url));
+        throw new Error(`архив недоступен: ${reason}${tlsHint(reason)}`);
+    }
+    fs.rmSync(stage, { recursive: true, force: true });
+    fs.mkdirSync(stage, { recursive: true });
+    fs.writeFileSync(archive, body);
+    try {
+        if (isZipBuffer(body))
+            await extractZip(archive, stage);
+        else if (isGzipBuffer(body))
+            await extractTarGz(archive, stage);
+        else
+            throw new Error(`неизвестный формат архива ${redactUrl(url)} (ожидается zip или tar.gz)`);
+        fs.rmSync(dir, { recursive: true, force: true });
+        fs.renameSync(stage, dir);
+    }
+    finally {
+        fs.rmSync(archive, { force: true });
+        fs.rmSync(stage, { recursive: true, force: true }); // no-op после rename
+    }
+    // GitLab/GitHub archive кладут всё в `<repo>-<sha>/` — единственный корневой каталог снимаем.
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    return entries.length === 1 && entries[0].isDirectory() ? path.join(dir, entries[0].name) : dir;
+};
+/**
+ * Резолв источника плагина в локальный каталог: `dir` (+ `subdir`) — проверка
+ * существования; `archive` — скачивание (с непустыми `headers`), распаковка в tmp-кэш,
+ * снятие единственного корневого каталога, затем `subdir`. Ошибки называют путь/URL.
+ */
+export const resolveSource = async (spec, cwd = process.cwd()) => {
+    if (spec.dir !== undefined) {
+        const abs = path.resolve(cwd, spec.dir, spec.subdir ?? '');
+        if (!fs.existsSync(abs) || !fs.statSync(abs).isDirectory())
+            throw new Error(`источник dir не найден: ${abs}`);
+        return abs;
+    }
+    if (spec.archive === undefined)
+        throw new Error('источник должен задавать dir либо archive');
+    const url = spec.archive;
+    const headers = Object.fromEntries(Object.entries(spec.headers ?? {}).filter(([, v]) => v !== ''));
+    let rootPromise = archiveCache.get(url);
+    if (!rootPromise) {
+        rootPromise = downloadArchive(url, headers);
+        archiveCache.set(url, rootPromise);
+        rootPromise.catch(() => archiveCache.delete(url)); // неудачу не кэшируем — следующая сборка повторит
+    }
+    const root = await rootPromise;
+    const result = spec.subdir ? path.join(root, spec.subdir) : root;
+    if (!fs.existsSync(result) || !fs.statSync(result).isDirectory())
+        throw new Error(`в архиве ${redactUrl(url)} нет каталога ${spec.subdir ?? '.'} (распаковано в ${root})`);
+    return result;
+};

package/dist/core/plugins/tree.js

@@ -0,0 +1,85 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { engineForExt } from "../scan/tree.js";
+// Виртуальные элементы дерева (добавлены плагинами, каталога на диске нет). Нужно
+// лишь для правила коллизий в addPage: реальную папку затирать нельзя, а свой же
+// пустой промежуточный узел плагин вправе наполнить позже.
+const VIRTUAL = new WeakSet();
+export const isVirtual = (item) => VIRTUAL.has(item);
+// Индекс сразу за концом поддерева элемента: дерево DFS-упорядочено, потомки идут
+// подряд за родителем — вставка туда сохраняет порядок обхода (sidebar/навигация).
+const subtreeEnd = (tree, parent) => {
+    const prefix = parent.dir + path.sep;
+    let i = tree.indexOf(parent) + 1;
+    while (i < tree.length && tree[i].dir.startsWith(prefix))
+        i++;
+    return i;
+};
+/**
+ * Добавляет виртуальную страницу в дерево сборки: считает `dir`/`level`/`parent` как
+ * scan (dir = ROOT_FOLDER/сегменты), дополняет `descendants` родителя, вставляет в конец
+ * поддерева родителя; недостающие промежуточные сегменты создаёт пустыми узлами
+ * (авто-заголовок, как папка без README). Каталог в dist создаётся здесь же — compose
+ * пишет страницы без mkdir, полагаясь на scan.
+ */
+export const addPage = (tree, options, page) => {
+    const segments = page.path;
+    if (!segments.length || segments.some((s) => !s || /[\\/]/.test(s) || s === '.' || s === '..'))
+        throw new Error(`addPage: некорректный путь страницы ${JSON.stringify(segments)}`);
+    const root = tree.find((x) => !x.parent);
+    if (!root)
+        throw new Error('addPage: в дереве нет корневого элемента');
+    let parent = root;
+    let item = root;
+    for (const [i, seg] of segments.entries()) {
+        const dir = path.join(parent.dir, seg);
+        const last = i === segments.length - 1;
+        const existing = tree.find((x) => x.dir === dir);
+        if (existing) {
+            if (last) {
+                if (!VIRTUAL.has(existing))
+                    throw new Error(`addPage: путь ${segments.join('/')} занят реальной папкой ${dir} — переименуйте раздел плагина (mount)`);
+                if (existing.mdFiles.length || existing.diagrams.length)
+                    throw new Error(`addPage: страница ${segments.join('/')} уже добавлена`);
+            }
+            item = existing;
+        }
+        else {
+            item = {
+                dir,
+                name: seg,
+                level: dir.split(path.sep).length,
+                parent: parent.dir,
+                mdFiles: [],
+                diagrams: [],
+                descendants: []
+            };
+            VIRTUAL.add(item);
+            parent.descendants.push(seg);
+            tree.splice(subtreeEnd(tree, parent), 0, item);
+            if (options.GENERATE_WEBSITE || options.GENERATE_MD || options.GENERATE_LOCAL_IMAGES)
+                fs.mkdirSync(path.join(options.DIST_FOLDER, dir.replace(options.ROOT_FOLDER, '')), {
+                    recursive: true
+                });
+        }
+        parent = item;
+    }
+    const md = page.markdown === undefined ? [] : Array.isArray(page.markdown) ? page.markdown : [page.markdown];
+    item.mdFiles.push(...md);
+    for (const d of page.diagrams ?? []) {
+        const ext = path.extname(d.file).toLowerCase();
+        const engine = engineForExt(ext);
+        if (!engine)
+            throw new Error(`addPage: у диаграммы "${d.file}" страницы ${segments.join('/')} неизвестное расширение`);
+        item.diagrams.push({
+            dir: d.file,
+            ext,
+            engine,
+            content: d.content,
+            isDitaa: engine === 'plantuml' && /@startditaa/i.test(d.content),
+            source: d.source,
+            soft: d.soft
+        });
+    }
+    return item;
+};

package/dist/core/plugins/types.js

@@ -0,0 +1,2 @@
+/** Identity ради вывода типа опций из схемы. */
+export const definePlugin = (plugin) => plugin;

package/dist/core/render/d2renderer.js

@@ -81,7 +81,9 @@ const resolveImport = (ref, fromDir) => {
 // пробел — иначе инлайновый spread `x: { ...@lib }` захватил бы `lib }`. Флаг `u` —
 // корректный юникод. Хвостовые `.key`-сегменты частичного импорта отрезает resolveImport.
 const IMPORT_RE = /(?<!\w)@(?:"([^"\n]+)"|([^\s"#;}\n][^#;}\n]*?)\s*(?=[#;}\n]|$))/gu;
-const collectFiles = (entryAbs, acc = new Map()) => {
+// seed — контент входного файла из дерева сборки: у виртуальных страниц плагинов
+// файла на диске нет, а импорты (`@…`) по-прежнему резолвятся от его каталога.
+const collectFiles = (entryAbs, acc = new Map(), seed) => {
     const abs = path.resolve(entryAbs);
     if (acc.has(abs))
         return acc;
@@ -89,7 +91,7 @@ const collectFiles = (entryAbs, acc = new Map()) => {
     try {
         // Строго UTF-8: язык D2 определён поверх UTF-8, опция CHARSET конфига относится
         // к PlantUML (уходит в -charset) и на .d2 сознательно не распространяется.
-        content = fs.readFileSync(abs, 'utf-8');
+        content = seed ?? fs.readFileSync(abs, 'utf-8');
     }
     catch {
         return acc;
@@ -117,14 +119,14 @@ let filesMemo = null;
 const clearD2FileCache = () => {
     filesMemo = null;
 };
-const collectFilesCached = (entryAbs) => {
+const collectFilesCached = (entryAbs, seed) => {
     const abs = path.resolve(entryAbs);
     if (!filesMemo)
         filesMemo = new Map();
     const hit = filesMemo.get(abs);
     if (hit)
         return hit;
-    const built = collectFiles(abs);
+    const built = collectFiles(abs, new Map(), seed);
     filesMemo.set(abs, built);
     return built;
 };
@@ -144,8 +146,8 @@ const commonAncestor = (files) => {
     return common.join(path.sep) || path.sep;
 };
 // Подготовить аргументы compile(): виртуальная fs (все файлы графа) + inputPath.
-const buildCompileRequest = (entryAbs) => {
-    const files = collectFilesCached(entryAbs);
+const buildCompileRequest = (entryAbs, seed) => {
+    const files = collectFilesCached(entryAbs, seed);
     // Пустой граф = не прочитался сам входной файл (удалён/недоступен — гонка в watch).
     // Без guard'а commonAncestor([]) давал бы сырой TypeError (Math.min()=Infinity).
     if (files.size === 0) {
@@ -170,9 +172,9 @@ const d2ErrorText = (message) => {
     catch { }
     return message;
 };
-const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
+const renderD2 = async (entryAbs, { layout = 'dagre', seed } = {}) => {
     const d2 = await getD2();
-    const { fs: fsMap, inputPath } = buildCompileRequest(entryAbs);
+    const { fs: fsMap, inputPath } = buildCompileRequest(entryAbs, seed);
     let result;
     try {
         result = await d2.compile({ fs: fsMap, inputPath, options: { layout } });
@@ -196,9 +198,9 @@ const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
 // диаграммы — аналог foldIncludes для PlantUML.
 // Путь в материале — относительный к cwd, posix-разделители: чексумма не зависит
 // от машины/чекаута/ОС (абсолютный путь делал кеш непереносимым).
-const foldD2Imports = (entryAbs) => {
+const foldD2Imports = (entryAbs, seed) => {
     const abs = path.resolve(entryAbs);
-    const files = collectFilesCached(entryAbs);
+    const files = collectFilesCached(entryAbs, seed);
     const rel = (p) => path.relative(process.cwd(), p).split(path.sep).join('/');
     // Мемоизированную Map не мутируем (её же использует buildCompileRequest) —
     // входной файл исключаем фильтром, а не delete. Сортировка по относительному

package/dist/core/render/diagrams.js

@@ -188,6 +188,22 @@ export const renderDiagram = (content, options) => new Promise((resolve, reject)
 // bkFolderName — каталог бэкапа dist, откуда восстанавливаются неизменённые картинки
 // по чексумме. Его lifecycle (создание/удаление) держит оркестратор build(); сюда
 // путь приходит явным параметром, а не пересчитывается из общей константы.
+// Картинка-заглушка вместо упавшей «мягкой» диаграммы: ошибка видна на странице,
+// сайт остаётся собранным (так же вёл себя онлайн-рендер docsify-plantuml).
+const errorPlaceholderSvg = (name, reason) => {
+    const esc = (s) => s.replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' })[c]);
+    const lines = [`${name}: диаграмма не отрендерена`, ...reason.split('\n')]
+        .flatMap((l) => l.match(/.{1,88}/g) ?? [''])
+        .slice(0, 8);
+    const w = 720;
+    const h = 34 + lines.length * 20;
+    const text = lines
+        .map((l, i) => `<text x="16" y="${34 + i * 20}" font-size="14">${esc(l)}</text>`)
+        .join('');
+    return (`<svg xmlns="http://www.w3.org/2000/svg" width="${w}" height="${h}" viewBox="0 0 ${w} ${h}" ` +
+        `font-family="${DEFAULT_FONT_NAME}" fill="#8b0000">` +
+        `<rect x="1" y="1" width="${w - 2}" height="${h - 2}" fill="#fff5f5" stroke="#8b0000"/>${text}</svg>`);
+};
 export const generateImages = async (tree, options, onImageGenerated, cacheConf, bkFolderName) => {
     // Чексуммы прошлого прогона — в Set: попадание проверяется O(1) на диаграмму
     // (было O(N) find → O(N²) на всё дерево).
@@ -250,7 +266,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             // entryPath !== null ⟺ engine === 'd2' — используем как сужение типа вместо assertion.
             const entryPath = diagram.engine === 'd2' ? path.join(item.dir, diagram.dir) : null;
             const includes = entryPath !== null
-                ? foldD2Imports(entryPath)
+                ? foldD2Imports(entryPath, body)
                 : foldIncludes(body, item.dir, item.dir, new Set());
             const outFormat = diagramOutputFormat(diagram, options);
             // renderKey: параметры, влияющие на БАЙТЫ вывода помимо контента и графа
@@ -262,20 +278,25 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 ? `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);
+            // Путь выхода — тоже в чексумме: восстановление из бэкапа идёт по паре
+            // «чексумма встречалась» + «бэкап с этим именем есть», иначе диаграммы,
+            // обменявшиеся содержимым (или сдвинувшиеся имена fence-блоков плагинов),
+            // молча получали бы чужую старую картинку.
             const cksum = crypto
                 .createHash('sha256')
-                .update(body + includes + renderKey, 'utf-8')
+                .update(`${body}${includes}${renderKey}\0out=${relOut.split(path.sep).join('/')}`, 'utf-8')
                 .digest('hex');
             // Записи копим в порядке обхода дерева, СИНХРОННО и до запуска задач:
             // порядок массива не зависит от того, кто из воркеров финиширует раньше —
             // .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);
+            const bkFilePath = path.join(bkFolderName, relOut);
             // path to image in dist folder
-            const filePath = path.join(options.DIST_FOLDER, item.dir.replace(options.ROOT_FOLDER, ''), outName);
+            const filePath = path.join(options.DIST_FOLDER, relOut);
             // if checksum exists (diagram untouched) and file/image exists - copy image back from backup folder
             if (oldChecksums.has(cksum) && fs.existsSync(bkFilePath)) {
                 // Восстановление из бэкапа — без рендера; JVM/worker не задействованы,
@@ -293,13 +314,17 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
             const diagramContent = diagram.content;
             const includePath = item.dir;
             const isDitaa = diagram.isDitaa;
+            // Имя картинки диаграммы виртуальной страницы производно от контента —
+            // без исходного файла в сообщении его не найти.
+            const source = diagram.source;
+            const soft = diagram.soft === true;
             const task = withProgress(async () => {
                 // render diagram to image: D2 через WASM, PlantUML — прямым вызовом java.
                 // Для растеризации PlantUML не-ditaa рендерим в svg (не -tpng), затем resvg.
                 let rendered;
                 try {
                     if (entryPath !== null) {
-                        rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT });
+                        rendered = await renderD2(entryPath, { layout: options.D2_LAYOUT, seed: body });
                     }
                     else {
                         // Резолв JRE отложен до первого реального PlantUML-рендера (эта
@@ -323,7 +348,15 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 }
                 catch (err) {
                     // Имя диаграммы в ошибку: renderDiagram/renderD2 сами его не знают.
-                    throw new Error(`Диаграмма "${outName}": ${err.message || err}`);
+                    const reason = `${err.message || err}`;
+                    const msg = `Диаграмма "${outName}"${source ? ` (${source})` : ''}: ${reason}`;
+                    if (!soft)
+                        throw new Error(msg);
+                    // Диаграммы из markdown-блоков плагинов писались под онлайн-рендер,
+                    // где битый блок давал картинку с ошибкой, а не падение сборки.
+                    console.log(chalk.yellow(`⚠ ${msg}`));
+                    const svg = Buffer.from(errorPlaceholderSvg(outName, reason), 'utf-8');
+                    await writeFile(filePath, outFormat === 'png' ? await rasterizeSvgToPng(svg, options.USE_SYSTEM_FONTS) : svg);
                 }
             });
             if (entryPath !== null)

package/dist/core/render/jre.js

@@ -9,12 +9,12 @@ import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
 import crypto from 'node:crypto';
-import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { httpGetStream, httpGetJson } from "../../util/http.js";
-// yauzl/tar грузятся лениво (только при распаковке скачанного JRE) — сохраняем это
-// синхронным require через createRequire, а не тянем их на импорте модуля.
-const require = createRequire(import.meta.url);
+// Распаковка (zip-slip-guard общий) вынесена в util/archive — её же использует
+// резолвер источников плагинов. isPathInside ре-экспортируется для тестов.
+import { extractZip, extractTarGz, isPathInside } from "../../util/archive.js";
+export { isPathInside };
 const MAJOR_MIN = 17; // минимальная годная мажорная версия системной java
 const TEMURIN_FEATURE = 21; // скачиваем ровно Temurin 21 JRE
 const JAVA_BIN = process.platform === 'win32' ? 'java.exe' : 'java';
@@ -207,60 +207,7 @@ const downloadAndVerify = async (link, expectedSha, destFile) => {
         throw new Error(`sha256 архива не совпал: ожидалось ${expectedSha}, получено ${actual}`);
     }
 };
-// Защита от zip-slip: путь записи, разрешённый относительно destDir, обязан
-// оставаться ВНУТРИ него (не `../` за пределы). Экспортируется для юнит-теста.
-export const isPathInside = (destDir, entryName) => {
-    const root = path.resolve(destDir);
-    const dest = path.resolve(root, entryName);
-    return dest === root || dest.startsWith(root + path.sep);
-};
-const extractZip = (archive, destDir) => new Promise((resolve, reject) => {
-    require('yauzl').open(archive, { lazyEntries: true }, (err, zip) => {
-        if (err)
-            return reject(err);
-        zip.on('entry', (entry) => {
-            // zip-slip: злонамеренная запись `../../evil` вышла бы за destDir. tar-ветка
-            // защищена node-tar≥6 по умолчанию, zip (yauzl) — нет, проверяем сами.
-            if (!isPathInside(destDir, entry.fileName)) {
-                return reject(new Error(`Небезопасный путь в архиве JRE (выход за каталог): ${entry.fileName}`));
-            }
-            // Симлинки пропускаем: вне доверенного Adoptium-архива симлинк мог бы
-            // указывать за пределы каталога. Temurin Windows-zip симлинков не содержит.
-            const isSymlink = ((entry.externalFileAttributes >>> 16) & 0xffff & 0o170000) === 0o120000;
-            if (isSymlink)
-                return zip.readEntry();
-            const dest = path.join(destDir, entry.fileName);
-            if (entry.fileName.endsWith('/')) {
-                fs.mkdirSync(dest, { recursive: true });
-                return zip.readEntry();
-            }
-            fs.mkdirSync(path.dirname(dest), { recursive: true });
-            zip.openReadStream(entry, (e, rs) => {
-                if (e)
-                    return reject(e);
-                const ws = fs.createWriteStream(dest);
-                ws.on('error', reject);
-                ws.on('finish', () => {
-                    const mode = (entry.externalFileAttributes >>> 16) & 0o777;
-                    if (mode) {
-                        try {
-                            fs.chmodSync(dest, mode);
-                        }
-                        catch {
-                            /* права не критичны на windows */
-                        }
-                    }
-                    zip.readEntry();
-                });
-                rs.pipe(ws);
-            });
-        });
-        zip.on('end', resolve);
-        zip.on('error', reject);
-        zip.readEntry();
-    });
-});
-const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : require('tar').x({ file: archive, cwd: destDir });
+const extractArchive = (archive, destDir, isZip) => isZip ? extractZip(archive, destDir) : extractTarGz(archive, destDir);
 // (3) скачивание: assets API → sha256 (до распаковки) → распаковка в staging →
 // атомарная замена кеша. Распаковываем НЕ в финальный каталог, а в свой staging
 // (<dir>.tmp-<pid>, уникальный на процесс → параллельные сборки не топчут друг друга),

package/dist/plugins/index.js

@@ -0,0 +1,4 @@
+export const BUILTIN_PLUGINS = {
+    openspec: async () => (await import("./openspec/index.js")).default,
+    openapi: async () => (await import("./openapi/index.js")).default
+};

package/dist/plugins/openapi/index.js

@@ -0,0 +1,95 @@
+// Встроенный плагин openapi: набор OpenAPI-спек (локальная папка или архив репозитория
+// контрактов) → раздел сайта со страницей swagger-ui на спеку. Полностью офлайн:
+// бандл swagger-ui и CSS — вендорные ассеты плагина, спеки копируются в dist статикой
+// с сохранением относительных путей ($ref).
+import fs from 'node:fs';
+import path from 'node:path';
+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 { VENDOR_DIR } from "../../util/paths.js";
+import { encodeURIPath } from "../../util/utils.js";
+const optionsSchema = z
+    .object({
+    mount: z.string().min(1).default('API'),
+    dir: z.string().min(1).optional(),
+    archive: z.string().optional(),
+    subdir: z.string().optional(),
+    headers: z.record(z.string(), z.string()).optional(),
+    glob: z.string().default('**/openapi.{yaml,yml,json}')
+})
+    .strict()
+    .refine((o) => (o.dir === undefined) !== (o.archive === undefined), {
+    message: 'нужен ровно один источник: dir либо archive'
+});
+// Имя страницы: родительская папка спеки; в корне источника — имя файла без расширения.
+const pageName = (rel) => {
+    const dir = path.posix.dirname(rel);
+    return dir === '.' ? path.posix.basename(rel).replace(/\.[^.]+$/, '') : path.posix.basename(dir);
+};
+export default definePlugin({
+    name: 'openapi',
+    options: optionsSchema,
+    requires: { executeScript: true },
+    // Бандл объявлен ассетом, а не взят из шаблона docsify: пользовательский docsifyTemplate
+    // может его не подключать; при дефолтном шаблоне injectPluginAssets дубль не добавит.
+    assets: {
+        styles: [path.join(VENDOR_DIR, 'swagger-ui', 'swagger-ui.css')],
+        scripts: [path.join(VENDOR_DIR, 'docsify', 'swagger-ui-bundle.js')]
+    },
+    watchPaths: (o) => (o.dir ? [path.join(o.dir, o.subdir ?? '')] : []),
+    async afterScan(ctx, o) {
+        const { mount } = o;
+        const source = o.dir ?? redactUrl(o.archive ?? '');
+        const root = await ctx.source({
+            dir: o.dir,
+            archive: o.archive,
+            subdir: o.subdir,
+            headers: o.headers
+        });
+        // Источник может быть предком выходного каталога (dir: '.') — свои же копии
+        // спек прошлой сборки в dist/dist_bk не считаются источником.
+        const skip = outputDirs(ctx.options);
+        const files = globFiles(root, o.glob, skip);
+        if (!files.length)
+            throw new Error(`по шаблону "${o.glob}" в ${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}`);
+            names.set(name, rel);
+        }
+        // Статикой в dist — все yaml/json источника, а не только совпавшие с glob: $ref
+        // может вести в общие схемы (components), не являющиеся спеками.
+        for (const rel of globFiles(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);
+        }
+        const sorted = [...names.entries()].sort(([a], [b]) => a.localeCompare(b));
+        const link = (name) => encodeURIPath(path.posix.join(mount, name, ctx.options.WEB_FILE_NAME || name));
+        ctx.addPage({
+            path: [mount],
+            markdown: sorted.map(([name, rel]) => `- [${name}](${link(name)}) — \`${rel}\``).join('\n')
+        });
+        for (const [name, rel] of sorted) {
+            // Спека грузится swagger-ui по ссылке от корня сайта (SPA: base = index.html);
+            // относительные $ref внутри спек резолвятся от её URL — структура сохранена.
+            const specUrl = encodeURIPath(path.posix.join(mount, '_specs', rel));
+            const domId = `swagger-${name.replace(/[^A-Za-z0-9_-]/g, '_')}`;
+            ctx.addPage({
+                path: [mount, name],
+                markdown: [
+                    `<div id="${domId}"></div>`,
+                    '<script>',
+                    `SwaggerUIBundle({ url: '${specUrl}', dom_id: '#${domId}' });`,
+                    '</script>'
+                ].join('\n')
+            });
+        }
+    }
+});

package/dist/plugins/openspec/fences.js

@@ -0,0 +1,58 @@
+// Fenced-блоки ```plantuml / ```d2 в артефактах → диаграммы страницы (рендер общим
+// локальным движком) + ссылка `![…](name.ext)` на их месте: compose подставит картинку
+// inline, а клиентский docsify-plantuml (онлайн-рендер в браузере) не сработает —
+// fence в выводе уже отсутствует.
+import crypto from 'node:crypto';
+// Fenced-блок по CommonMark: открывающая ``` или ~~~ (≥3) с любым отступом (fence в
+// списке), инфо-строка, тело (может быть пустым), закрывающая того же вида не короче
+// открывающей. Тело захватывается вместе с завершающим переводом строки.
+const FENCE_RE = /^([ \t]*)(`{3,}|~{3,})[ \t]*([^\n]*)\n([\s\S]*?)^[ \t]*\2[`~]*[ \t]*$/gm;
+const ENGINE_EXT = { plantuml: '.puml', puml: '.puml', d2: '.d2' };
+/** Применить fn к тексту вне fenced-блоков (сами блоки — без изменений). */
+export const mapOutsideFences = (md, fn) => {
+    let out = '';
+    let last = 0;
+    for (const m of md.matchAll(FENCE_RE)) {
+        out += fn(md.slice(last, m.index)) + m[0];
+        last = m.index + m[0].length;
+    }
+    return out + fn(md.slice(last));
+};
+/**
+ * Экстрактор диаграмм одной страницы. Имя файла — `<base>-<sha1 контента>`: не зависит
+ * от позиции fence, поэтому вставка/удаление соседнего блока не сдвигает имена и не
+ * подсовывает картинку соседа из кэша; одинаковые блоки дают одну диаграмму.
+ */
+export const createFenceExtractor = () => {
+    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];
+                if (!ext)
+                    return whole;
+                // Отступ fence (в списке) снимаем со строк тела, как CommonMark.
+                const src = body
+                    .replace(/\n$/, '')
+                    .split('\n')
+                    .map((l) => (l.startsWith(indent) ? l.slice(indent.length) : l))
+                    .join('\n');
+                // PlantUML требует @startuml/@enduml; в артефактах их часто опускают.
+                const content = ext === '.puml' && !/@start\w+/.test(src) ? `@startuml\n${src}\n@enduml` : src;
+                const hash = crypto.createHash('sha1').update(content).digest('hex').slice(0, 8);
+                const file = `${base}-${hash}${ext}`;
+                if (!seen.has(file)) {
+                    seen.add(file);
+                    // soft: блок в артефакте — не файл проекта; синтаксическая
+                    // ошибка в нём не должна ронять весь сайт (раньше такие блоки
+                    // рендерил браузер и показывал картинку с ошибкой).
+                    diagrams.push({ file, content, source, soft: true });
+                }
+                return `${indent}![${file}](${file})`;
+            });
+            return { markdown, diagrams };
+        }
+    };
+};