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

package/dist/core/plugins/load.js

@@ -0,0 +1,125 @@
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import fs from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+import { pathToFileURL } from 'node:url';
+import chalk from 'chalk';
+import { BUILTIN_PLUGINS } from "../../plugins/index.js";
+// Подстановка `${NAME}` из окружения во всех строках опций (рекурсивно). Незаданная
+// переменная → пустая строка: так `headers: { 'PRIVATE-TOKEN': '${GITLAB_TOKEN}' }`
+// без токена даёт пустой заголовок, который резолвер источников отбрасывает.
+export const expandEnv = (value) => {
+    if (typeof value === 'string')
+        return value.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => process.env[name] ?? '');
+    if (Array.isArray(value))
+        return value.map(expandEnv);
+    if (value && typeof value === 'object')
+        return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, expandEnv(v)]));
+    return value;
+};
+const isPathId = (id) => id.startsWith('./') || id.startsWith('../') || path.isAbsolute(id);
+// Главный ESM-вход пакета по его package.json: `exports` (вложенные условия
+// import/default, subpath ".", массивы-фолбэки), иначе `module`/`main`. Покрывает
+// типовые формы; экзотические условия — за пределами (`ponytail`).
+const resolveEsmMain = (id, searchPaths) => {
+    const dir = searchPaths
+        .map((p) => path.join(p, id))
+        .find((d) => fs.existsSync(path.join(d, 'package.json')));
+    if (!dir)
+        return undefined;
+    const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf8'));
+    const pick = (e) => {
+        if (typeof e === 'string')
+            return e;
+        if (Array.isArray(e))
+            return e.map(pick).find(Boolean);
+        if (!e || typeof e !== 'object')
+            return undefined;
+        const o = e;
+        return '.' in o ? pick(o['.']) : pick(o.import ?? o.default ?? o.node);
+    };
+    const main = pick(pkg.exports) ?? pkg.module ?? pkg.main;
+    return main ? path.join(dir, main) : undefined;
+};
+// Идентификатор → модуль плагина: встроенный по имени → путь от cwd → npm-пакет,
+// резолвится от cwd проекта (а не от установки c4builder — глобальный бинарь иначе
+// не видел бы локальные node_modules).
+const importPlugin = async (id, cwd) => {
+    if (Object.hasOwn(BUILTIN_PLUGINS, id))
+        return BUILTIN_PLUGINS[id]();
+    let mod;
+    if (isPathId(id)) {
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(path.resolve(cwd, id)).href));
+    }
+    else {
+        const require = createRequire(path.join(cwd, 'package.json'));
+        let resolved;
+        try {
+            resolved = require.resolve(id);
+        }
+        catch (e) {
+            // ESM-only пакет (`exports` лишь с условием import) CJS-резолвер не берёт —
+            // находим пакет в цепочке node_modules от cwd и читаем его exports сами.
+            if (e.code === 'ERR_PACKAGE_PATH_NOT_EXPORTED')
+                resolved = resolveEsmMain(id, require.resolve.paths(id) ?? []);
+            if (!resolved)
+                throw new Error(`не найден ни среди встроенных (${Object.keys(BUILTIN_PLUGINS).join(', ')}), ` +
+                    `ни как npm-пакет от ${cwd}: ${e.message}`);
+        }
+        mod = await import(__rewriteRelativeImportExtension(pathToFileURL(resolved).href));
+    }
+    const plugin = mod.default ?? mod;
+    if (!plugin || typeof plugin !== 'object' || typeof plugin.name !== 'string')
+        throw new Error('модуль должен экспортировать по умолчанию объект плагина с полем name');
+    return plugin;
+};
+/**
+ * Загружает плагины из `plugins` конфига: резолв, импорт, подстановка окружения и
+ * валидация опций схемой плагина. Fail-fast — любая ошибка прерывает до старта сборки
+ * с указанием позиции записи и имени плагина. `requires.executeScript` включает
+ * `EXECUTE_SCRIPT` в опциях сборки (с одной строкой в лог, если ключ был выключен).
+ */
+export const loadPlugins = async (entries, cwd, options) => {
+    const loaded = [];
+    for (const [i, entry] of entries.entries()) {
+        const [id, rawOpts] = typeof entry === 'string' ? [entry, {}] : entry;
+        let plugin;
+        try {
+            plugin = await importPlugin(id, cwd);
+        }
+        catch (e) {
+            throw new Error(`plugins[${i}] "${id}": ${e.message}`);
+        }
+        let opts = expandEnv(rawOpts);
+        if (plugin.options) {
+            const parsed = plugin.options.safeParse(opts);
+            if (!parsed.success) {
+                const issues = parsed.error.issues.map((iss) => `${iss.path.length ? iss.path.join('.') : '(опции)'} — ${iss.message}`);
+                throw new Error(`plugins[${i}] ${plugin.name}: ${issues.join('; ')}`);
+            }
+            opts = parsed.data;
+        }
+        if (plugin.requires?.executeScript && !options.EXECUTE_SCRIPT) {
+            options.EXECUTE_SCRIPT = true;
+            console.log(chalk.gray(`плагин ${plugin.name} требует executeScript — включён для этой сборки`));
+        }
+        loaded.push({ plugin, opts });
+    }
+    return loaded;
+};
+/** Существующие пути наблюдения всех плагинов (абсолютные); несуществующие — предупреждение. */
+export const pluginWatchPaths = (plugins, cwd, exists) => plugins.flatMap(({ plugin, opts }) => (plugin.watchPaths?.(opts) ?? [])
+    .map((p) => path.resolve(cwd, p))
+    .filter((p) => {
+    if (exists(p))
+        return true;
+    console.log(chalk.yellow(`плагин ${plugin.name}: путь наблюдения не существует — ${p}`));
+    return false;
+}));

package/dist/core/plugins/source.js

@@ -0,0 +1,86 @@
+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;
+    }
+};
+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) {
+        throw new Error(`архив недоступен: ${e.message.replaceAll(url, redactUrl(url))}`);
+    }
+    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,83 @@
+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)
+        });
+    }
+    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) {
@@ -159,16 +161,27 @@ const buildCompileRequest = (entryAbs) => {
     return { fs: fsMap, inputPath: toKey(path.resolve(entryAbs)) };
 };
 // Рендер .d2 → SVG (Buffer). Ошибки компиляции пробрасываются с путём файла.
-const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
+// Ошибка компиляции движок отдаёт JSON-массивом [{range, errmsg}] — вытаскиваем
+// человекочитаемые errmsg (`file:line:col: текст`); иной формат отдаём как есть.
+const d2ErrorText = (message) => {
+    try {
+        const parsed = JSON.parse(message);
+        if (Array.isArray(parsed) && parsed.every((x) => typeof x?.errmsg === 'string'))
+            return parsed.map((x) => x.errmsg).join('\n');
+    }
+    catch { }
+    return message;
+};
+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 } });
     }
     catch (err) {
         const e = err;
-        throw new Error(`Ошибка компиляции D2 (${entryAbs}):\n${e.message || e}`);
+        throw new Error(`Ошибка компиляции D2 (${entryAbs}):\n${d2ErrorText(e.message || String(e))}`);
     }
     let svg;
     try {
@@ -185,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

@@ -250,7 +250,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 +262,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 не задействованы,
@@ -299,7 +304,7 @@ export const generateImages = async (tree, options, onImageGenerated, cacheConf,
                 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-рендера (эта

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')
+            });
+        }
+    }
+});