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

package/README.MD

@@ -33,9 +33,11 @@ I strongly encourage people to check them out first but if you want to dive righ
 `npm install` (no tag) always installs the latest stable release. Release candidates are
 opt-in only — see [Installing a release candidate](#installing-a-release-candidate).
 
-**Requirements:** local diagram generation needs a Java runtime (JRE 17+) on `PATH`.
-Graphviz is **not** required — layout is computed by PlantUML's built-in Java engine
-(Smetana). The PlantUML jar and the diagram font are bundled with c4builder.
+**Requirements:** Node.js ≥ 20.19. Local diagram generation needs Java 17+: a system
+`java` (`JAVA_HOME`/`PATH`) is used when present, otherwise c4builder downloads a private
+JRE into its cache automatically (`c4builder jre install` pre-warms it, `jre info` shows
+what would be used). Graphviz is **not** required — layout is computed by PlantUML's
+built-in Java engine (Smetana). The PlantUML jar and the diagram font are bundled.
 
 With `diagramFormat: png`, diagrams are produced by rasterizing their SVG with
 [`@resvg/resvg-js`](https://github.com/thx/resvg-js) (a bundled dependency, prebuilt
@@ -62,22 +64,57 @@ A sample project is available at [C4Builder-Demo](https://github.com/adrianvlupu
 ## Available Commands
 
 ```bash
-PS C:\docprojects\Online Banking> c4builder --help
+$ c4builder --help
 Usage: index [options]
 
 Options:
-  -V, --version                     output the version number
-  new                               create a new project from template
-  config                            change configuration for the current directory
-  list                              display the current configuration
-  reset                             clear all configuration
-  site                              serve the generated site
-  -w, --watch                       watch for changes and rebuild
-  -o, --open                        open the generated site in the browser (with --site)
-  docs                              a brief explanation for the available configuration options
-  -p, --port <n>                    port used for serving the generated site
-  -c, --config-file <.c4builder>    set the configuration file relative path
-  -h, --help                        output usage information
+  -V, --version                   output the version number
+  --new                           create a new project from template
+  --name <name>                   project name for --new (skips the name prompt)
+  -y, --yes                       non-interactive --new: defaults, no prompts
+                                  (requires --name)
+  --force                         for `jre install`: force JRE download even if
+                                  system java is present
+  --config                        change configuration for the current directory
+  -c, --config-file <.c4builder>  set the configuration file relative path
+  --list                          display the current configuration
+  --reset                         clear all configuration
+  --site                          serve the generated site
+  -w, --watch                     watch for changes and rebuild
+  -o, --open                      open the generated site in the browser (with
+                                  --site)
+  --docs                          a brief explanation for the available
+                                  configuration options
+  --system-fonts                  render with system fonts instead of the
+                                  bundled one (not deterministic)
+  -p, --port <n>                  port used for serving the generated site
+  -h, --help                      display help for command
+```
+
+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.
@@ -217,7 +254,7 @@ The generated markdown file makes for an easy single page readme for the reposit
 
 ### Docsify site with a sidebar
 
-After choosing to generate a docsify site, it can be viewed locally by running `c4builder site` and accessing `http://localhost:3000`;
+After choosing to generate a docsify site, it can be viewed locally by running `c4builder --site` and accessing `http://localhost:3000`;
 
 The site is minimalistic including only a sidebar with the System/Container/Components hierarchy.
 
@@ -264,24 +301,51 @@ Pre-release builds (`0.x.y-rc.N`) are published under the npm dist-tag `rc` and
 
 `npm install` without a tag keeps installing the latest stable version.
 
+## Docker
+
+The image ships everything needed for a build (Node, JRE, PlantUML jar, fonts, D2) —
+mount a project into `/pwd`:
+
+```bash
+docker run --rm -v "$PWD:/pwd" ghcr.io/alfacapital-tech/c4builder:latest c4builder
+```
+
+Tags (in sync with npm dist-tags):
+
+| tag | meaning |
+|---|---|
+| `X.Y.Z`, `sha-…` | immutable releases / commits |
+| `latest` | latest stable release |
+| `rc` | latest release candidate |
+| `edge` | last master commit |
+| `pr-N` | pull request builds |
+
+Use the image directly in CI (GitHub Actions, GitLab CI) as the job image — the
+`c4builder` binary is on `PATH`.
+
 ## Releasing
 
 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
 ```
 
@@ -289,9 +353,31 @@ 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
 
-PDF output removed — use the docsify site or the single/collection markdown outputs instead (the `pdf`/`pdfCss` options no longer exist).
+Full TypeScript rewrite (ESM, Node.js ≥ 20.19) with the same CLI and `.c4builder` format.
+
+- PlantUML renders via a direct `java` call with the built-in Smetana layout — graphviz
+  is no longer needed; the jar is bundled (`vendor/`)
+- Java itself is optional: system java ≥ 17 is used when present, otherwise a private
+  JRE is downloaded automatically (`c4builder jre install` / `jre info`)
+- Second diagram backend: [D2](https://d2lang.com) (`.d2` files, optional
+  `@terrastruct/d2` dependency, imports supported)
+- `diagramFormat: png` rasterizes SVG with `@resvg/resvg-js` — deterministic PNG for
+  PlantUML and D2 alike
+- Bundled Nimbus Sans font for identical diagram geometry everywhere;
+  `useSystemFonts` / `--system-fonts` opts out
+- Config is validated (zod): typos and wrong types fail with a clear message
+- Docker image on GHCR with a tag scheme in sync with npm dist-tags (see [Docker](#docker))
+- PDF output removed — use the docsify site or the single/collection markdown outputs
+  instead (the `pdf`/`pdfCss` options no longer exist)
 
 ## v0.2.20
 

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-rc.3",
+  "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",