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

package/README.MD

@@ -94,6 +94,29 @@ 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.
 
+### Validating single diagrams
+
+`c4builder check <file...>` validates individual `.puml` / `.iuml` / `.d2` files with the
+same engines the build uses (bundled PlantUML jar + system/managed Java, bundled D2) —
+no project or `.c4builder` needed, nothing is written. Handy for pre-commit hooks and CI:
+exit code 0 when every file compiles, 1 otherwise; errors are printed as
+`✗ file: line N: <engine message>`.
+
+```bash
+c4builder check src/c4/context.puml lib/shared.iuml diagrams/flow.d2
+```
+
+`!include` paths resolve relative to the checked file's directory; a `.iuml` library is
+validated by including it into an empty diagram.
+
+A minimal pre-commit hook (`.git/hooks/pre-commit`) that validates staged diagrams:
+
+```bash
+#!/bin/sh
+files=$(git diff --cached --name-only --diff-filter=ACM -- '*.puml' '*.iuml' '*.d2')
+[ -z "$files" ] || exec c4builder check $files
+```
+
 By default, running `c4builder` will attempt to build the project.
 
 If no configuration was set it will ask for it and then do the actual build. Running just `c4builder` after a configuration will no longer show the wizard.
@@ -305,19 +328,24 @@ Use the image directly in CI (GitHub Actions, GitLab CI) as the job image — th
 Publishing is triggered by pushing a git tag `v<version>` — pushes/merges to `master` alone
 do not publish.
 
-**Release candidate** (from `refactor/phoenix`, no merge to `master` needed):
+Every user-facing PR adds a line to the `## Unreleased` section of the change log below;
+the release commit renames it to `## vX.Y.Z`.
+
+**Release candidate** (from `master`, as many as needed — consumers pinned to `rc`
+pick each one up automatically):
 
 ```
-npm version 0.3.0-rc.1 -m "rc: %s"
+npm version X.Y.Z-rc.1 -m "rc: %s"      # first candidate
+npm version prerelease -m "rc: %s"      # next ones: rc.2, rc.3, …
 git push --follow-tags
 ```
 
-Publishes to dist-tag `rc`.
+Publishes to npm dist-tag `rc` and docker tag `rc`; `latest` is untouched.
 
-**Final release:**
+**Final release** (rename `## Unreleased` → `## vX.Y.Z` first):
 
 ```
-npm version 0.3.0 -m "release: %s"
+npm version X.Y.Z -m "release: %s"
 git push --follow-tags
 ```
 
@@ -325,6 +353,13 @@ Publishes to dist-tag `latest`.
 
 # Change log
 
+## Unreleased
+
+- `c4builder check <file...>` — validate individual `.puml` / `.iuml` / `.d2` files with the
+  bundled engines, without a project build (#13)
+- D2 compile errors are printed as readable `file:line:col: message` lines instead of raw JSON
+- Regression test for two adjacent `![..](x.puml)` embeds (#12 — the bug itself was fixed in 0.3.0)
+
 ## v0.3.0
 
 Full TypeScript rewrite (ESM, Node.js ≥ 20.19) with the same CLI and `.c4builder` format.

package/dist/cli/commands/check.js

@@ -0,0 +1,80 @@
+import chalk from 'chalk';
+import path from 'node:path';
+import { readFile } from 'node:fs/promises';
+import { VENDOR_DIR } from "../../util/paths.js";
+import { VENDORED_JAR } from "../../util/utils.js";
+import { resolveJava } from "../../core/render/jre.js";
+import { renderDiagram } from "../../core/render/diagrams.js";
+import { renderD2, teardownD2 } from "../../core/render/d2renderer.js";
+// `c4builder check <file...>` — валидация отдельных диаграмм ТЕМ ЖЕ движком, что и
+// сборка (вендорный PlantUML jar + системная/managed java, бандл D2), без проекта и
+// `.c4builder`. Рендер идёт в память и выбрасывается: проверяем ровно то, что упало бы
+// в сборке (системный `plantuml` может отличаться версией). Код выхода 0 — все файлы ок,
+// 1 — есть ошибка (движка, неизвестного расширения или чтения файла).
+// stderr PlantUML в -pipe: `ERROR` / позиция / описание. Позиция — 0-based строка
+// диаграммы, для файла с одной диаграммой это file:N+1.
+// ponytail: в файле с несколькими @startuml позиция считается от начала блока — смещение
+// не учитываем, добавить, если такие файлы станут проверять.
+const PUML_ERROR = /^ERROR\n(\d+)\n(.*)$/m;
+const JAR_PATH = path.join(VENDOR_DIR, VENDORED_JAR.jar);
+// JRE резолвится лениво и один раз: список только из .d2 java не трогает.
+let javaPromise = null;
+const getJava = () => {
+    javaPromise ??= resolveJava({ log: (m) => console.log(chalk.gray(m)) }).then((r) => r.path);
+    return javaPromise;
+};
+const checkPlantUml = async (abs) => {
+    // .iuml — библиотека без @startuml: сам по себе PlantUML «рендерит» его без ошибок,
+    // поэтому проверяем через включение в пустую диаграмму.
+    const isLib = path.extname(abs) === '.iuml';
+    const content = isLib ? `@startuml\n!include ${abs}\n@enduml\n` : await readFile(abs);
+    const isDitaa = /@startditaa/i.test(content.toString());
+    try {
+        await renderDiagram(content, {
+            javaBin: await getJava(),
+            jarPath: JAR_PATH,
+            includePath: path.dirname(abs),
+            format: isDitaa ? 'png' : 'svg',
+            charset: 'UTF-8',
+            isDitaa,
+            useSystemFonts: false
+        });
+    }
+    catch (e) {
+        const m = e.message.match(PUML_ERROR);
+        if (!m)
+            throw e;
+        // Для .iuml позиция относится к обёртке, а не к файлу — не показываем.
+        throw new Error(isLib ? m[2] : `строка ${Number(m[1]) + 1}: ${m[2]}`);
+    }
+};
+const CHECKERS = {
+    '.puml': checkPlantUml,
+    '.iuml': checkPlantUml,
+    '.d2': (abs) => renderD2(abs)
+};
+export default async (files) => {
+    if (files.length === 0) {
+        console.log(chalk.red('использование: c4builder check <file...>  (.puml | .iuml | .d2)'));
+        process.exit(1);
+    }
+    let failed = 0;
+    // ponytail: последовательно — на сотнях файлов добавить пул как в generateImages.
+    for (const file of files) {
+        const abs = path.resolve(file);
+        const check = CHECKERS[path.extname(abs).toLowerCase()];
+        try {
+            if (!check)
+                throw new Error('неизвестное расширение (ожидается .puml, .iuml или .d2)');
+            await check(abs);
+            console.log(chalk.green(`✓ ${file}`));
+        }
+        catch (e) {
+            failed++;
+            console.error(chalk.red(`✗ ${file}: ${e.message}`));
+        }
+    }
+    await teardownD2();
+    if (failed)
+        process.exit(1);
+};

package/dist/cli/dispatch.js

@@ -6,6 +6,7 @@ import Configstore from 'configstore';
 import cmdHelp from "./commands/help.js";
 import cmdNewProject from "./commands/new.js";
 import cmdJre from "./commands/jre.js";
+import cmdCheck from "./commands/check.js";
 import cmdList from "./commands/list.js";
 import cmdSite from "./commands/site.js";
 import cmdCollect from "./wizard/collect.js";
@@ -118,12 +119,15 @@ export default async () => {
             throw new InvalidArgumentError('ожидается TCP-порт: целое число 1..65535');
         return Number(v);
     })
-        .allowExcessArguments() // позиционные аргументы подкоманды `jre <action>`
+        .allowExcessArguments() // позиционные аргументы подкоманд `jre <action>` и `check <file...>`
         .parse(process.argv);
     const opts = program.opts();
     // Прогрев JRE — до загрузки конфига проекта и intro: команда самостоятельна.
     if (program.args[0] === 'jre')
         return cmdJre(program.args.slice(1), { force: opts.force });
+    // Проверка отдельных диаграмм — тоже без конфига проекта.
+    if (program.args[0] === 'check')
+        return cmdCheck(program.args.slice(1));
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
     // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.

package/dist/core/render/d2renderer.js

@@ -159,6 +159,17 @@ const buildCompileRequest = (entryAbs) => {
     return { fs: fsMap, inputPath: toKey(path.resolve(entryAbs)) };
 };
 // Рендер .d2 → SVG (Buffer). Ошибки компиляции пробрасываются с путём файла.
+// Ошибка компиляции движок отдаёт 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' } = {}) => {
     const d2 = await getD2();
     const { fs: fsMap, inputPath } = buildCompileRequest(entryAbs);
@@ -168,7 +179,7 @@ const renderD2 = async (entryAbs, { layout = 'dagre' } = {}) => {
     }
     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 {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alfacapital-tech/c4builder",
-  "version": "0.3.0",
+  "version": "0.4.0-rc.1",
   "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",