@alfacapital-tech/c4builder 0.4.0-rc.4 → 0.5.0-rc.1

package/dist/core/compose/markdown.js

@@ -7,9 +7,11 @@ import { encodeURIPath, readFile, writeFile, plantUmlServerUrl } from "../../uti
 import { VENDOR_DIR } from "../../util/paths.js";
 // Фаза scan: тип дерева и его элементов + производные (имя папки, формат выхода диаграммы)
 // и единый реестр расширений диаграмм (источник истины для regex ссылок ниже).
-import { getFolderName, diagramOutputFormat, DIAGRAM_ENGINES, engineSupportsRemote } from "../scan/tree.js";
+import { getFolderName, diagramOutputFormat, DIAGRAM_ENGINES, engineSupportsRemote, collectIncludes } from "../scan/tree.js";
 // Фаза render: mime-тип формата и загрузка удалённо отрендеренной картинки (embed-ветка).
 import { getMime, httpGet } from "../render/diagrams.js";
+// Граф D2-импортов — тот же, что у рендера (приложение llms-full.txt).
+import { d2LocalImports } from "../render/d2renderer.js";
 // docsifyTemplate можно переопределить пользовательским шаблоном (см. generateWebMD),
 // поэтому это mutable-локаль, а не const-импорт; user-шаблон грузим синхронно через createRequire.
 const require = createRequire(import.meta.url);
@@ -164,6 +166,12 @@ const mdAnchor = (name) => `#${encodeURIPath(name).replace(/%20/g, '-')}`;
 // (rootRel — путь цели от ROOT_FOLDER). Один паттерн для TOC, навигации вверх и
 // меню подпапок — прежде дублировался трижды.
 const relativeMdLink = (fromLevel, rootRel, mdFileName) => encodeURIPath(path.join('./', fromLevel - 1 > 0 ? '../'.repeat(fromLevel - 1) : '', rootRel, `${mdFileName}.md`));
+// Состав и ссылки sidebar сайта — общие с llms.txt, чтобы оглавление агента не
+// разъехалось с навигацией. Чистоту string[] гарантирует zod-схема.
+const inSidebar = (item, options) => !options.EXCLUDE_SIDEBAR_FOLDER_BY_PATH?.some((pathToExclude) => item.dir.startsWith(pathToExclude));
+// Путь веб-страницы от корня сайта, без .md. path.relative, а не отрезание первого
+// сегмента: то ломалось на многосегментном rootFolder из рукописного конфига.
+const sitePagePath = (item, options) => path.join(path.relative(options.ROOT_FOLDER, item.dir), options.WEB_FILE_NAME || item.name);
 // Тело страницы (титул + контент с диаграммами) — общий скелет generateMD и
 // generateWebMD. chrome (breadcrumbs/TOC/навигация) встаёт под заголовок: при
 // авто-титуле — сразу за ним, при пользовательском h1 — пост-вставкой после него.
@@ -176,8 +184,9 @@ const compilePage = async (item, options, chrome = '') => {
         MD = injectAfterFirstH1(MD, chrome);
     return MD.trimStart();
 };
-export const generateCompleteMD = async (tree, options) => {
-    const filePromises = [];
+// Единый документ со всеми страницами в порядке дерева. Стратегия диаграмм — у вызывающего:
+// complete.md вставляет картинки, llms-full.txt — исходники; состав и порядок общие.
+const composeComplete = async (tree, options, getDiagram) => {
     //title
     let MD = `# ${options.PROJECT_NAME}`;
     //table of contents
@@ -195,13 +204,67 @@ export const generateCompleteMD = async (tree, options) => {
             MD += `\n\n[${options.HOMEPAGE_NAME}](${mdAnchor(options.PROJECT_NAME)})`;
         }
         //concatenate markdown files
-        MD = await compileDocument(MD, item, options, (item, diagram, options) => 
-        // complete: ссылки на диаграммы префиксуются папкой элемента.
-        buildDiagramMarkdown(item, diagram, options, 'complete'));
+        MD = await compileDocument(MD, item, options, getDiagram);
     }
-    //write file to disk
-    filePromises.push(writeFile(path.join(options.DIST_FOLDER, `${options.PROJECT_NAME}.md`), MD));
-    await Promise.all(filePromises);
+    return MD;
+};
+export const generateCompleteMD = async (tree, options) => writeFile(path.join(options.DIST_FOLDER, `${options.PROJECT_NAME}.md`), 
+// complete: ссылки на диаграммы префиксуются папкой элемента.
+await composeComplete(tree, options, (i, d, o) => buildDiagramMarkdown(i, d, o, 'complete')));
+// llms.txt (llmstxt.org): плоский список — парсеры читают строки `- [..](..)` от начала
+// строки и теряют вложенные; иерархию несёт заголовок «A / B / C».
+export const generateLlmsTxt = (tree, options) => {
+    const pages = tree
+        .filter((item) => inSidebar(item, options))
+        .map((item) => {
+        const rel = path.relative(options.ROOT_FOLDER, item.dir);
+        const title = rel ? rel.split(path.sep).join(' / ') : options.HOMEPAGE_NAME;
+        return `- [${title}](${encodeURIPath(`${sitePagePath(item, options)}.md`)})\n`;
+    });
+    return (`# ${options.PROJECT_NAME}\n\n` +
+        '> Architecture documentation built with c4builder. Pages are markdown; full text with ' +
+        'diagram sources (PlantUML/D2/BPMN): [llms-full.txt](llms-full.txt).\n\n' +
+        `## Pages\n\n${pages.join('')}`);
+};
+// Fence длиннее самой длинной серии обратных кавычек текста — иначе блок закрылся бы изнутри.
+const fenced = (text, lang = '') => {
+    const fence = '`'.repeat(Math.max(3, ...(text.match(/`+/g) ?? []).map((run) => run.length + 1)));
+    return `${fence}${lang}\n${text.endsWith('\n') ? text : `${text}\n`}${fence}`;
+};
+const FENCE_LANG = {
+    '.puml': 'plantuml',
+    '.iuml': 'plantuml',
+    '.d2': 'd2',
+    '.bpmn': 'xml'
+};
+// llms-full.txt: состав complete-документа, но диаграмма — исходником (C4-PlantUML/D2-текст
+// агенту полезнее SVG). Локальные include/импорты — один раз в приложении, а не инлайном:
+// общий styles.iuml иначе повторился бы в каждой диаграмме. Резолв — тот же, что у рендера.
+export const generateLlmsFull = async (tree, options) => {
+    const MD = await composeComplete(tree, options, async (_item, diagram) => fenced(`${diagram.content}`, FENCE_LANG[diagram.ext]));
+    const deps = new Map();
+    for (const item of tree) {
+        for (const diagram of item.diagrams) {
+            const body = `${diagram.content}`;
+            if (diagram.engine === 'd2') {
+                for (const [abs, content] of d2LocalImports(path.join(item.dir, diagram.dir), body))
+                    deps.set(abs, content);
+            }
+            else if (diagram.engine === 'plantuml') {
+                for (const inc of collectIncludes(body, item.dir, item.dir, new Set()))
+                    deps.set(inc.abs, inc.content);
+            }
+        }
+    }
+    if (!deps.size)
+        return `${MD}\n`;
+    const files = [...deps]
+        .map(([abs, content]) => [path.relative(process.cwd(), abs).split(path.sep).join('/'), content])
+        .sort(([a], [b]) => (a < b ? -1 : 1));
+    const appendix = files
+        .map(([p, content]) => `\n\n### ${p}\n\n${fenced(content, FENCE_LANG[path.extname(p).toLowerCase()])}`)
+        .join('');
+    return `${MD}\n\n## Included files${appendix}\n`;
 };
 export const generateMD = async (tree, options, onProgress) => {
     let processedCount = 0;
@@ -253,13 +316,9 @@ export const generateWebMD = async (tree, options) => {
     const filePromises = [];
     let docsifySideBar = '';
     const getWebFileName = (originalFileName) => options.WEB_FILE_NAME || originalFileName;
-    // Чистоту string[] гарантирует zod-схема (не-строки отброшены препроцессом).
-    const isExcluded = (dir) => !!options.EXCLUDE_SIDEBAR_FOLDER_BY_PATH?.some((pathToExclude) => dir.startsWith(pathToExclude));
     for (const item of tree) {
-        //sidebar — путь от ROOT_FOLDER (path.relative, а не отрезание первого сегмента:
-        // то ломалось на многосегментном rootFolder из рукописного конфига)
-        if (!isExcluded(item.dir)) {
-            docsifySideBar += `${'  '.repeat(item.level - 1)}* [${item.name}](${encodeURIPath(path.join(path.relative(options.ROOT_FOLDER, item.dir), getWebFileName(item.name)))})\n`;
+        if (inSidebar(item, options)) {
+            docsifySideBar += `${'  '.repeat(item.level - 1)}* [${item.name}](${encodeURIPath(sitePagePath(item, options))})\n`;
         }
         const MD = await compilePage(item, options);
         //write to disk
@@ -271,8 +330,8 @@ export const generateWebMD = async (tree, options) => {
         const loaded = require(path.join(process.cwd(), options.DOCSIFY_TEMPLATE));
         const fn = typeof loaded === 'function' ? loaded : loaded?.default;
         if (typeof fn !== 'function') {
-            throw new Error(`docsifyTemplate «${options.DOCSIFY_TEMPLATE}» должен экспортировать функцию ` +
-                `(module.exports = fn или export default fn), получено: ${typeof fn}`);
+            throw new Error(`docsifyTemplate "${options.DOCSIFY_TEMPLATE}" must export a function ` +
+                `(module.exports = fn or export default fn), got: ${typeof fn}`);
         }
         docsifyTemplate = fn;
     }
@@ -281,7 +340,7 @@ export const generateWebMD = async (tree, options) => {
     const rootName = () => {
         const root = tree.find((item) => !item.parent);
         if (!root)
-            throw new Error('docsify: корневой элемент дерева не найден');
+            throw new Error('docsify: tree root not found');
         return root.name;
     };
     //docsify homepage
@@ -296,13 +355,20 @@ export const generateWebMD = async (tree, options) => {
         },
         stylesheet: options.WEB_THEME,
         alias: { '/.*/_sidebar.md': '/_sidebar.md' },
+        nativeEmoji: true,
         supportSearch: options.SUPPORT_SEARCH,
         executeScript: options.EXECUTE_SCRIPT
     })));
     //copy local docsify vendor files to dist
     const docsifyVendorSrc = path.join(VENDOR_DIR, 'docsify');
     if (fs.existsSync(docsifyVendorSrc)) {
-        filePromises.push(fsextra.copy(docsifyVendorSrc, path.join(options.DIST_FOLDER, 'vendor')));
+        const vendorDist = path.join(options.DIST_FOLDER, 'vendor');
+        // Тема — без ведущего @import Google Fonts (у её шрифтов есть системный fallback).
+        // Правим копию, а не vendor/: повторное вендорение вернуло бы @import.
+        const theme = path.join(vendorDist, 'vue.css');
+        filePromises.push(fsextra
+            .copy(docsifyVendorSrc, vendorDist)
+            .then(async () => writeFile(theme, (await readFile(theme)).toString().replace(/^@import url\([^)]*\);/, ''))));
     }
     //github pages preparation
     filePromises.push(writeFile(path.join(options.DIST_FOLDER, `.nojekyll`), ''));

package/dist/core/plugins/hooks.js

@@ -5,7 +5,7 @@ const wrap = async (name, hook, fn) => {
         await fn();
     }
     catch (e) {
-        throw new Error(`Плагин ${name} (${hook}): ${e.message ?? e}`, { cause: e });
+        throw new Error(`Plugin ${name} (${hook}): ${e.message ?? e}`, { cause: e });
     }
 };
 export const runAfterScan = async (tree, options, plugins) => {

package/dist/core/plugins/load.js

@@ -70,14 +70,14 @@ const importPlugin = async (id, cwd) => {
             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}`);
+                throw new Error(`not found among built-ins (${Object.keys(BUILTIN_PLUGINS).join(', ')}) ` +
+                    `nor as an npm package from ${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');
+        throw new Error('module must default-export a plugin object with a name field');
     return plugin;
 };
 /**
@@ -101,14 +101,14 @@ export const loadPlugins = async (entries, cwd, options) => {
         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}`);
+                const issues = parsed.error.issues.map((iss) => `${iss.path.length ? iss.path.join('.') : '(options)'} — ${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 — включён для этой сборки`));
+            console.log(chalk.gray(`plugin ${plugin.name} requires executeScript — enabled for this build`));
         }
         loaded.push({ plugin, opts });
     }
@@ -120,6 +120,6 @@ export const pluginWatchPaths = (plugins, cwd, exists) => plugins.flatMap(({ plu
     .filter((p) => {
     if (exists(p))
         return true;
-    console.log(chalk.yellow(`плагин ${plugin.name}: путь наблюдения не существует — ${p}`));
+    console.log(chalk.yellow(`plugin ${plugin.name}: watch path does not exist — ${p}`));
     return false;
 }));

package/dist/core/plugins/source.js

@@ -25,7 +25,7 @@ export const redactUrl = (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'
+    ? ' — TLS interception? set the CA bundle path in NODE_EXTRA_CA_CERTS'
     : '';
 const downloadArchive = async (url, headers) => {
     const dir = path.join(os.tmpdir(), `c4builder-src-${crypto.createHash('sha1').update(url).digest('hex')}`);
@@ -39,7 +39,7 @@ const downloadArchive = async (url, headers) => {
     }
     catch (e) {
         const reason = e.message.replaceAll(url, redactUrl(url));
-        throw new Error(`архив недоступен: ${reason}${tlsHint(reason)}`);
+        throw new Error(`archive unavailable: ${reason}${tlsHint(reason)}`);
     }
     fs.rmSync(stage, { recursive: true, force: true });
     fs.mkdirSync(stage, { recursive: true });
@@ -50,7 +50,7 @@ const downloadArchive = async (url, headers) => {
         else if (isGzipBuffer(body))
             await extractTarGz(archive, stage);
         else
-            throw new Error(`неизвестный формат архива ${redactUrl(url)} (ожидается zip или tar.gz)`);
+            throw new Error(`unknown archive format ${redactUrl(url)} (expected zip or tar.gz)`);
         fs.rmSync(dir, { recursive: true, force: true });
         fs.renameSync(stage, dir);
     }
@@ -71,11 +71,11 @@ 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}`);
+            throw new Error(`dir source not found: ${abs}`);
         return abs;
     }
     if (spec.archive === undefined)
-        throw new Error('источник должен задавать dir либо archive');
+        throw new Error('source must set dir or archive');
     const url = spec.archive;
     const headers = Object.fromEntries(Object.entries(spec.headers ?? {}).filter(([, v]) => v !== ''));
     let rootPromise = archiveCache.get(url);
@@ -87,6 +87,6 @@ export const resolveSource = async (spec, cwd = process.cwd()) => {
     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})`);
+        throw new Error(`archive ${redactUrl(url)} has no folder ${spec.subdir ?? '.'} (extracted to ${root})`);
     return result;
 };

package/dist/core/plugins/tree.js

@@ -25,10 +25,10 @@ const subtreeEnd = (tree, parent) => {
 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)}`);
+        throw new Error(`addPage: invalid page path ${JSON.stringify(segments)}`);
     const root = tree.find((x) => !x.parent);
     if (!root)
-        throw new Error('addPage: в дереве нет корневого элемента');
+        throw new Error('addPage: tree has no root');
     let parent = root;
     let item = root;
     for (const [i, seg] of segments.entries()) {
@@ -38,9 +38,9 @@ export const addPage = (tree, options, page) => {
         if (existing) {
             if (last) {
                 if (!VIRTUAL.has(existing))
-                    throw new Error(`addPage: путь ${segments.join('/')} занят реальной папкой ${dir} — переименуйте раздел плагина (mount)`);
+                    throw new Error(`addPage: path ${segments.join('/')} is taken by a real folder ${dir} — rename the plugin section (mount)`);
                 if (existing.mdFiles.length || existing.diagrams.length)
-                    throw new Error(`addPage: страница ${segments.join('/')} уже добавлена`);
+                    throw new Error(`addPage: page ${segments.join('/')} already added`);
             }
             item = existing;
         }
@@ -70,7 +70,7 @@ export const addPage = (tree, options, page) => {
         const ext = path.extname(d.file).toLowerCase();
         const engine = engineForExt(ext);
         if (!engine)
-            throw new Error(`addPage: у диаграммы "${d.file}" страницы ${segments.join('/')} неизвестное расширение`);
+            throw new Error(`addPage: diagram "${d.file}" of page ${segments.join('/')} has an unknown extension`);
         item.diagrams.push({
             dir: d.file,
             ext,