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

package/README.MD

@@ -92,7 +92,8 @@ Options:
 ```
 
 There is also a `jre` subcommand: `c4builder jre install [--force]` pre-downloads the
-private JRE cache, `c4builder jre info` prints which Java would be used.
+private JRE cache, `c4builder jre info` prints which Java would be used. `c4builder site`
+is accepted as a positional subcommand too, equivalent to `--site`.
 
 ### Validating single diagrams
 
@@ -324,7 +325,9 @@ spec deltas live under `specs/…` mirroring the folder layout (a folder that ha
 ```` ```plantuml ```` / ```` ```d2 ```` fences inside artifacts, deltas and store specs are
 rendered by the **local** engines (nothing is sent to plantuml.com); the image name is derived
 from the fence content, so inserting or reordering fences never reuses a neighbour's cached
-image. Relative links between artifacts of a change point to their pages, referenced files
+image. A block that fails to render does not fail the build (these blocks used to be rendered by
+the browser, which showed an error image): the page gets a placeholder image and the build prints
+a warning naming the artifact file. Relative links between artifacts of a change point to their pages, referenced files
 (images, notes) are copied next to the page (and to the output root for the complete markdown;
 `excludeOtherFiles` applies). The store folder is watched in `-w`.
 
@@ -348,7 +351,9 @@ needed by readers. The plugin forces `executeScript` (logged) and injects `swagg
 `swagger-ui-bundle.js` into `index.html` after the template is rendered (skipped when the template
 already links the bundle), so custom `docsifyTemplate`s need no change. The output folder is never
 treated as a source (`dir: "."` is fine). Archives are downloaded once per process (watch mode
-reuses them).
+reuses them). Behind a TLS-intercepting proxy the download fails with `self-signed certificate in
+certificate chain` — point `NODE_EXTRA_CA_CERTS` at the CA bundle (Node reads neither the system
+store nor `SSL_CERT_FILE`); the error message says so as well.
 
 | Option    | Default                          | Meaning                                  |
 |-----------|----------------------------------|------------------------------------------|
@@ -486,6 +491,13 @@ Publishes to dist-tag `latest`.
   The first build after upgrading re-renders everything once.
 - Watch mode ignores the output folder, its backup and `.c4builder*`, and de-duplicates nested
   watch roots (a plugin `dir` covering the project no longer loops the rebuild)
+- A broken ```` ```plantuml ````/```` ```d2 ```` block inside an OpenSpec artifact no longer fails
+  the build: the page gets a placeholder image and the warning names the source file
+- Diagram errors name the file the diagram came from (fence names are content hashes)
+- `{a,b}` glob alternatives accept `*`/`?` inside them (`{*.yaml,*.yml}`)
+- Archive download failures caused by a TLS-intercepting proxy suggest `NODE_EXTRA_CA_CERTS`
+- `c4builder site` works as a positional subcommand, the same as `--site` (it is the form the
+  post-build hint prints)
 
 ## v0.3.0
 

package/dist/cli/dispatch.js

@@ -131,6 +131,10 @@ export default async () => {
     // Проверка отдельных диаграмм — тоже без конфига проекта.
     if (program.args[0] === 'check')
         return cmdCheck(program.args.slice(1));
+    // `c4builder site` — подсказка после сборки печатает именно эту форму; без
+    // этой строки allowExcessArguments молча глотал бы её и просто пересобирал.
+    if (program.args[0] === 'site')
+        opts.site = true;
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.

package/dist/core/plugins/source.js

@@ -22,6 +22,11 @@ export const redactUrl = (url) => {
         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 — параллельная
@@ -33,7 +38,8 @@ const downloadArchive = async (url, headers) => {
         body = await httpGetBuffer(url, { headers });
     }
     catch (e) {
-        throw new Error(`архив недоступен: ${e.message.replaceAll(url, redactUrl(url))}`);
+        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 });

package/dist/core/plugins/tree.js

@@ -76,7 +76,9 @@ export const addPage = (tree, options, page) => {
             ext,
             engine,
             content: d.content,
-            isDitaa: engine === 'plantuml' && /@startditaa/i.test(d.content)
+            isDitaa: engine === 'plantuml' && /@startditaa/i.test(d.content),
+            source: d.source,
+            soft: d.soft
         });
     }
     return item;

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²) на всё дерево).
@@ -298,6 +314,10 @@ 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.
@@ -328,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/plugins/openspec/fences.js

@@ -26,7 +26,7 @@ export const mapOutsideFences = (md, fn) => {
 export const createFenceExtractor = () => {
     const seen = new Set();
     return {
-        extract(md, base) {
+        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() ?? '';
@@ -45,7 +45,10 @@ export const createFenceExtractor = () => {
                 const file = `${base}-${hash}${ext}`;
                 if (!seen.has(file)) {
                     seen.add(file);
-                    diagrams.push({ file, content });
+                    // soft: блок в артефакте — не файл проекта; синтаксическая
+                    // ошибка в нём не должна ронять весь сайт (раньше такие блоки
+                    // рендерил браузер и показывал картинку с ошибкой).
+                    diagrams.push({ file, content, source, soft: true });
                 }
                 return `${indent}![${file}](${file})`;
             });

package/dist/plugins/openspec/index.js

@@ -5,7 +5,7 @@ import path from 'node:path';
 import { z } from 'zod';
 import { definePlugin } from "../../core/plugins/types.js";
 import { scanStore } from "./scan.js";
-import { renderArchiveIndex, renderChange, renderChangesIndex, renderMarkdown, renderSpecTree, renderSummary } from "./render.js";
+import { renderArchiveIndex, renderChange, renderChangesIndex, relSource, renderMarkdown, renderSpecTree, renderSummary } from "./render.js";
 const optionsSchema = z
     .object({
     dir: z.string().default('openspec'),
@@ -61,6 +61,7 @@ export default definePlugin({
         addPages(renderSpecTree(store.specs, [mount, 'Specs'], options, (pagePath, spec) => renderMarkdown(pagePath, `spec-${spec.path.join('-')}`, spec.content, {
             srcRoot: specsDir,
             fromDir: spec.path.join('/'),
+            source: relSource(specsDir, `${spec.path.join('/')}/spec.md`),
             options
         })), specsDir);
         ctx.addPage({

package/dist/plugins/openspec/render.js

@@ -78,6 +78,8 @@ const ignoreTitle = (title) => {
     const t = title.trim().replace(/^(["'])(.*)\1$/s, '$2');
     return ` ':ignore${t ? ` ${t}` : ''}'`;
 };
+/** Путь файла для сообщений — от cwd, чтобы его можно было открыть как есть. */
+export const relSource = (root, rel) => path.relative(process.cwd(), path.join(root, rel)).split(path.sep).join('/');
 /**
  * Markdown одного исходного файла → страница сайта: fenced-диаграммы вырезаются, ссылки
  * на другие страницы источника (`target`, `#x` → `?id=x`) — на их адреса, прочие
@@ -85,8 +87,8 @@ const ignoreTitle = (title) => {
  * странице (картинки docsify грузит относительно страницы, обычные ссылки — от корня сайта).
  * `fromDir` — posix-каталог файла относительно `srcRoot` (ссылки в нём резолвятся от файла).
  */
-export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', target = () => undefined, options }) => {
-    const { markdown, diagrams } = createFenceExtractor().extract(content, base);
+export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', target = () => undefined, source, options }) => {
+    const { markdown, diagrams } = createFenceExtractor().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;
@@ -172,7 +174,13 @@ export const renderChange = (change, segments, order, options) => {
         const delta = deltas.find((d) => `specs/${d.path.join('/')}/spec.md` === rel);
         return delta && [...specsBase, ...delta.path];
     };
-    const render = (pagePath, base, content, fromDir = '') => renderMarkdown(pagePath, base, content, { srcRoot: change.dir, fromDir, target, options });
+    const render = (pagePath, base, content, fromDir = '', file = `${base}.md`) => renderMarkdown(pagePath, base, content, {
+        srcRoot: change.dir,
+        fromDir,
+        target,
+        source: relSource(change.dir, path.posix.join(fromDir, file)),
+        options
+    });
     const subpages = ordered
         .filter((a) => a !== inline)
         .map((a) => render([...segments, a.name], a.name, a.content));
@@ -201,7 +209,7 @@ export const renderChange = (change, segments, order, options) => {
         ...subpages
     ];
     if (deltas.length) {
-        const tree = renderSpecTree(deltas, specsBase, options, (pagePath, spec) => render(pagePath, `spec-${spec.path.join('-')}`, spec.content, `specs/${spec.path.join('/')}`));
+        const tree = renderSpecTree(deltas, specsBase, options, (pagePath, spec) => render(pagePath, `spec-${spec.path.join('-')}`, spec.content, `specs/${spec.path.join('/')}`, 'spec.md'));
         // Артефакт specs.md и корень дельт — один путь: сливаем в страницу артефакта.
         const artifact = pages.find((p) => p.path.length === segments.length + 1 && p.path.at(-1) === 'specs');
         for (const p of tree) {

package/dist/util/glob.js

@@ -3,7 +3,7 @@
 // `**/openapi.{yaml,yml,json}`; `fs.glob` появился только в Node 22, engines — ≥20.19.
 import fs from 'node:fs';
 import path from 'node:path';
-export const globToRegExp = (glob) => {
+const convert = (glob) => {
     let re = '';
     for (let i = 0; i < glob.length; i++) {
         const c = glob[i];
@@ -28,10 +28,12 @@ export const globToRegExp = (glob) => {
             if (end === -1)
                 re += '\\{';
             else {
+                // Альтернативы — тем же конвертером: `{*.yaml,*.yml}` должен работать
+                // как glob, а не как буквальная звёздочка.
                 re += `(?:${glob
                     .slice(i + 1, end)
                     .split(',')
-                    .map((s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'))
+                    .map(convert)
                     .join('|')})`;
                 i = end;
             }
@@ -39,8 +41,9 @@ export const globToRegExp = (glob) => {
         else
             re += c.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
     }
-    return new RegExp(`^${re}$`);
+    return re;
 };
+export const globToRegExp = (glob) => new RegExp(`^${convert(glob)}$`);
 /**
  * Файлы под root, чьи относительные posix-пути совпадают с glob (сортировано).
  * `.git`/`node_modules` и абсолютные каталоги `skipDirs` не обходятся.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.4.0-rc.2",
+  "version": "0.4.0-rc.3",
   "description": "A CLI tool designed to compile a folder structure of markdowns and plant uml files into a site, single file markdown or a collection of markdowns with links",
   "type": "module",
   "main": "dist/index.js",