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

package/README.MD

@@ -42,6 +42,11 @@ With `diagramFormat: png`, diagrams are produced by rasterizing their SVG with
 native binary, no browser). This gives a single deterministic PNG for both PlantUML and
 D2, using the bundled font. ditaa diagrams stay native PlantUML PNG.
 
+**Fonts.** Diagrams use the bundled Nimbus Sans (Helvetica metrics, Cyrillic and Greek —
+see `vendor/fonts/README.md`), so diagram geometry is identical on any machine.
+`useSystemFonts: true` in `.c4builder` (or `--system-fonts` for one run) renders with the
+machine's fonts instead — machine-dependent by design.
+
 The easiest way to get started is with the _new project_ template.
 
 ![new](docs/images/new.gif)
@@ -110,7 +115,7 @@ Following the C4 model, folders inside the **source** represent Systems/Containe
                     class.1.md
 ```
 
-The **destination** folder is automatically generated by the **build** process and can have various formats. The folder can provide a drill down style view of the Systems/Containers/Components in different ways. Either by pushing it as a site to gitpages, using it as a navigable markdown directly in the repository or by generating pdfs and using the traditional mail.
+The **destination** folder is automatically generated by the **build** process and can have various formats. The folder can provide a drill down style view of the Systems/Containers/Components in different ways. Either by pushing it as a site to gitpages or using it as a navigable markdown directly in the repository.
 
 ## The build
 
@@ -210,18 +215,6 @@ The generated markdown file makes for an easy single page readme for the reposit
 
 ![singlemd](docs/images/single-md.jpg)
 
-### Collection of pdf files each describing one entity
-
-A fast way to pass around information regarding only one particular System/Container/Component
-
-![pdf](docs/images/pdf.jpg)
-
-### Single pdf file with a table of contents
-
-The easiest format to share the full documentation
-
-![pdffull](docs/images/full-pdf.jpg)
-
 ### 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`;
@@ -232,7 +225,7 @@ The sidebar is generated manually so that it only contains the main entities def
 
 ![site](docs/images/site.jpg)
 
-By going to the github repository settings and enabling GitHub pages the site be pushed with ease and provide an overview to all people involved in the project without having to worry about which version of pdf file got sent when.
+By going to the github repository settings and enabling GitHub pages the site be pushed with ease and provide an overview to all people involved in the project.
 
 ![github](docs/images/githubpages.gif)
 
@@ -256,10 +249,6 @@ By default this is disabled. If enabled, the output will no longer include the a
 
 The current entity structure is inserted after the header
 
-### Custom pdf
-
-If defined, this css is used in the generation of the pdf files.
-
 # Future plans
 
 I would like to bind the **build** phase to the C4 model. It could parse the diagrams and know what Person/System/Component/Container is related to what and help with additional validation. Maybe even export to [structurizr](https://structurizr.com/) or vice versa.
@@ -300,6 +289,10 @@ Publishes to dist-tag `latest`.
 
 # Change log
 
+## v0.3.0
+
+PDF output removed — use the docsify site or the single/collection markdown outputs instead (the `pdf`/`pdfCss` options no longer exist).
+
 ## v0.2.20
 
 Fork by [Alfa Capital Technologies](https://alfacapital.tech)

package/dist/cli/commands/help.js

@@ -30,8 +30,6 @@ ${chalk.cyan('Generate website')}
 Uses docsify to generate a website with a sidebar for navigation. The site can be easily deployed to github pages.
     ${chalk.cyan('Website docsify theme')}
     Changes the default theme of the generated docsify website
-${chalk.cyan('PlantUML version')}
-Uses the specific plantuml version jar file for generating images.
 ${chalk.cyan('Generate diagram images locally')}
 Uses the localy installed plantuml package to build svg images for each diagram.
 ${chalk.cyan('Replace diagrams with a link')}

package/dist/cli/commands/jre.js

@@ -1,13 +1,20 @@
 import chalk from 'chalk';
-import { resolveJava, detectSystemJava, TEMURIN_FEATURE } from "../../core/render/jre.js";
-// Прогрев кеша: `c4builder jre install [--force]`. Резолвит/скачивает JRE заранее
+import { resolveJava, detectSystemJava, TEMURIN_FEATURE, JRE_CACHE_SCHEMA, jreCacheDir } from "../../core/render/jre.js";
+// `c4builder jre install [--force]` — прогрев кеша: резолвит/скачивает JRE заранее
 // (CI/офлайн) без полной сборки. При годной системной java по умолчанию сообщает,
 // что скачивание не требуется; `--force` форсирует загрузку Temurin в кеш.
+// `c4builder jre info` — машиночитаемые параметры managed-JRE (JSON): путь кеша и
+// материал ключа для внешних кешей (actions/cache в CI) из единственного источника
+// истины, вместо grep констант по исходникам и хардкода пути.
 export default async (args = [], { force = false } = {}) => {
     const action = args[0];
+    if (action === 'info') {
+        console.log(JSON.stringify({ feature: TEMURIN_FEATURE, schema: JRE_CACHE_SCHEMA, cacheDir: jreCacheDir() }));
+        return;
+    }
     if (action !== 'install') {
         console.log(chalk.red(`неизвестная подкоманда: c4builder jre ${action || ''}`.trim()));
-        console.log(chalk.gray('доступно: c4builder jre install [--force]'));
+        console.log(chalk.gray('доступно: c4builder jre install [--force] | jre info'));
         process.exit(1);
     }
     try {

package/dist/cli/commands/list.js

@@ -1,5 +1,5 @@
 import chalk from 'chalk';
-export default (currentConfiguration) => {
+export default (currentConfiguration, issues = []) => {
     console.log(`
 CURRENT CONFIGURATION
 
@@ -74,5 +74,13 @@ Exclude other files: ${currentConfiguration.EXCLUDE_OTHER_FILES !== undefined
         ? chalk.green(currentConfiguration.EXCLUDE_OTHER_FILES)
         : chalk.red('not set')}
 `);
+    // Битые ключи показаны выше как «not set» (щадящий разбор их выбросил); помечаем их
+    // сырым значением и причиной, чтобы было видно, что и почему требует правки/визарда.
+    if (issues.length) {
+        console.log(chalk.yellow('⚠ Невалидные ключи в .c4builder (показаны как «not set», чините через `c4builder --config`):'));
+        for (const { key, value, message } of issues)
+            console.log(chalk.yellow(`  ⚠ ${key}: ${JSON.stringify(value)} — ${message}`));
+        console.log('');
+    }
     return;
 };

package/dist/cli/commands/new.js

@@ -15,37 +15,18 @@ const validateProjectName = (name) => {
     if (name.indexOf('/') !== -1 || name.indexOf('\\') !== -1)
         return 'имя проекта не должно содержать «/» или «\\»';
     const target = path.join(process.cwd(), name);
-    if (fs.existsSync(target) && fs.readdirSync(target).length > 0)
-        return `папка «${name}» уже существует и не пуста`;
+    if (fs.existsSync(target)) {
+        // readdirSync по файлу бросает ENOTDIR — сперва различаем файл и каталог.
+        if (!fs.statSync(target).isDirectory())
+            return `«${name}» уже существует и является файлом`;
+        if (fs.readdirSync(target).length > 0)
+            return `папка «${name}» уже существует и не пуста`;
+    }
     return null;
 };
-const generateTemplate = async (dir, projectName) => {
-    const build = async (dir, _parent) => {
-        const files = fs.readdirSync(dir);
-        for (const file of files) {
-            if (fs.statSync(path.join(dir, file)).isDirectory()) {
-                await makeDirectory(path.join(process.cwd(), projectName, dir.replace(TEMPLATE_DIR, ''), file));
-                await build(path.join(dir, file), dir);
-            }
-        }
-        const mdFiles = files.filter((x) => path.extname(x).toLowerCase() === '.md');
-        for (const mdFile of mdFiles) {
-            await fsextra.copy(path.join(dir, mdFile), path.join(process.cwd(), projectName, dir.replace(TEMPLATE_DIR, ''), mdFile));
-        }
-        const pumlFiles = files.filter((x) => path.extname(x).toLowerCase() === '.puml');
-        for (const pumlFile of pumlFiles) {
-            const fileContents = await readFile(path.join(dir, pumlFile));
-            await writeFile(path.join(process.cwd(), projectName, dir.replace(TEMPLATE_DIR, ''), pumlFile), fileContents);
-        }
-        const otherFiles = files.filter((x) => ['.md', '.puml'].indexOf(path.extname(x).toLowerCase()) === -1);
-        for (const otherFile of otherFiles) {
-            if (fs.statSync(path.join(dir, otherFile)).isDirectory())
-                continue;
-            await fsextra.copy(path.join(dir, otherFile), path.join(process.cwd(), projectName, dir.replace(TEMPLATE_DIR, ''), otherFile));
-        }
-    };
-    await build(dir);
-};
+// Копия шаблона в новый проект как есть (включая dot-файлы) — раньше это была ручная
+// рекурсия на 40 строк, повторявшая fsextra.copy по типам файлов.
+const generateTemplate = (dir, projectName) => fsextra.copy(dir, path.join(process.cwd(), projectName));
 export default async (opts = {}) => {
     const nonInteractive = !!opts.yes;
     // --- имя проекта: флаг --name пропускает промпт; --yes без имени — фатально ---

package/dist/cli/dispatch.js

@@ -1,5 +1,5 @@
 import figlet from 'figlet';
-import { program } from 'commander';
+import { InvalidArgumentError, program } from 'commander';
 import chalk from 'chalk';
 import path from 'node:path';
 import Configstore from 'configstore';
@@ -13,27 +13,50 @@ import { build } from "../core/build.js";
 import watch from 'node-watch';
 import { EventEmitter } from 'node:events';
 import { clearConsole } from "../util/utils.js";
+import { acquireBuildLock, BuildLockHeldError } from "../util/lock.js";
+// teardownD2 живёт здесь, а не в finally build(): в watch-режиме D2-воркер должен
+// переживать ребилды (его пересоздание — секунды), гасим его только когда сборок
+// больше не будет (одиночный запуск).
+import { teardownD2 } from "../core/render/d2renderer.js";
 import { packageJson as pkg } from "../util/paths.js";
-import { configSchema } from "../config/schema.js";
+import { parseConfig } from "../config/options.js";
+import { isValidPort } from "../config/schema.js";
 const intro = () => {
     console.log(chalk.blue(figlet.textSync('c4builder')));
     console.log(chalk.gray('Blow up your software documentation writing skills'));
 };
-function getOptions(conf, applyDefaults) {
+// Читает сырой `.c4builder` и разбирает его щадяще (config/parseConfig): для визарда и
+// `--list`. Возвращает лишь ЗАДАННЫЕ пользователем и ВАЛИДНЫЕ ключи (недостающее и битое
+// = undefined, как читалось до валидации), чтобы визард спросил их на первом запуске,
+// а `--list` всё равно показал конфиг. Битые ключи — в `issues` для предупреждения.
+function readLenientConfig(conf) {
     const raw = (conf.all ?? {});
-    const parsed = configSchema.safeParse(raw);
-    if (!parsed.success) {
-        const issue = parsed.error.issues[0];
-        const key = issue?.path.join('.') || '(корень)';
-        console.error(chalk.red(`Ошибка в .c4builder: ключ «${key}» — ${issue?.message ?? 'неверное значение'}`));
-        process.exit(1);
-    }
-    const full = parsed.data;
-    const c = applyDefaults === false
-        ? Object.fromEntries(Object.keys(full)
-            .filter((k) => k in raw)
-            .map((k) => [k, full[k]]))
-        : full;
+    const result = parseConfig(raw);
+    const source = result.ok ? result.value : result.salvaged;
+    const broken = new Set(result.ok ? [] : result.issues.map((i) => i.key));
+    const config = Object.fromEntries(Object.keys(source)
+        // null в файле = «не задан» (как отсутствие ключа): схема уже подставила
+        // дефолт, но визард обязан спросить значение, а не молча принять его.
+        .filter((k) => k in raw && raw[k] !== null && !broken.has(k))
+        .map((k) => [k, source[k]]));
+    return { config, issues: result.ok ? [] : result.issues, salvaged: source };
+}
+// Строгий путь (сборка) не терпит битого конфига: печатает внятную ошибку и завершает
+// процесс с ненулевым кодом. Держим решение о выходе здесь, в CLI, а не в config/*.
+function failOnConfigIssues(issues) {
+    console.error(chalk.red('Ошибка в .c4builder — невалидные значения не дают собрать документацию:'));
+    for (const { key, message } of issues)
+        console.error(chalk.red(`  ${key} — ${message}`));
+    process.exit(1);
+}
+// Щадящий путь (--config/первый запуск визарда) предупреждает о битых ключах: они
+// трактуются как «не задано» и будут перезаписаны валидными значениями после визарда.
+function warnConfigIssues(issues) {
+    console.log(chalk.yellow('\n⚠ Невалидные ключи в .c4builder (трактуются как «не задано», визард их перезапишет):'));
+    for (const { key, value, message } of issues)
+        console.log(chalk.yellow(`  ⚠ ${key}: ${JSON.stringify(value)} — ${message}`));
+}
+function getOptions(c) {
     return {
         // Легаси-детект: выбор версии PlantUML удалён; ключ plantumlVersion из старых
         // .c4builder отдаём build.js только для однократного предупреждения на пине.
@@ -64,12 +87,13 @@ function getOptions(conf, applyDefaults) {
         HAS_RUN: c.hasRun,
         PLANTUML_SERVER_URL: c.plantumlServerUrl,
         DIAGRAM_FORMAT: c.diagramFormat,
-        D2_LAYOUT: c.d2Layout || 'dagre',
+        D2_LAYOUT: c.d2Layout,
         MD_FILE_NAME: 'README',
         WEB_FILE_NAME: c.webFileName,
         SUPPORT_SEARCH: c.supportSearch,
         EXECUTE_SCRIPT: c.executeScript,
-        EXCLUDE_OTHER_FILES: c.excludeOtherFiles
+        EXCLUDE_OTHER_FILES: c.excludeOtherFiles,
+        USE_SYSTEM_FONTS: c.useSystemFonts
     };
 }
 export default async () => {
@@ -87,7 +111,13 @@ export default async () => {
         .option('-w, --watch', 'watch for changes and rebuild')
         .option('-o, --open', 'open the generated site in the browser (with --site)')
         .option('--docs', 'a brief explanation for the available configuration options')
-        .option('-p, --port <n>', 'port used for serving the generated site', parseInt)
+        .option('--system-fonts', 'render with system fonts instead of the bundled one (not deterministic)')
+        .option('-p, --port <n>', 'port used for serving the generated site', (v) => {
+        // parseInt молча резал бы опечатку ('30OO' → 30) — валидируем строго.
+        if (!isValidPort(v))
+            throw new InvalidArgumentError('ожидается TCP-порт: целое число 1..65535');
+        return Number(v);
+    })
         .allowExcessArguments() // позиционные аргументы подкоманды `jre <action>`
         .parse(process.argv);
     const opts = program.opts();
@@ -96,9 +126,12 @@ export default async () => {
         return cmdJre(program.args.slice(1), { force: opts.force });
     let conf = { get: () => { } };
     let cacheConf = { get: () => { }, set: () => { }, clear: () => { } };
+    // Лок сборки — рядом с конфигом проекта (см. util/lock.ts). Заполняется вместе с conf.
+    let lockPath = '';
     if (!opts.new) {
         const projectKey = process.cwd().split(path.sep).splice(1).join('_');
         const configPath = path.join(process.cwd(), opts.configFile ?? '.c4builder');
+        lockPath = `${configPath}.lock`;
         conf = new Configstore(projectKey, {}, { configPath });
         cacheConf = new Configstore(`${projectKey}_cache`, {}, { configPath: `${configPath}.cache` });
         // Миграция: чексуммы раньше жили в .c4builder, переносим их в .c4builder.cache,
@@ -113,9 +146,20 @@ export default async () => {
     }
     if (opts.docs)
         return cmdHelp();
-    // Начальный конфиг для визарда/--list: raw-вид (незаданные поля = undefined),
-    // чтобы визард спросил недостающее на первом запуске.
-    const currentConfig = getOptions(conf, false);
+    // --reset чистит .c4builder при ЛЮБОМ его содержимом — до строгой проверки конфига,
+    // чтобы сломанное значение не мешало собственному сбросу.
+    if (opts.reset && !opts.new) {
+        clearConsole();
+        intro();
+        conf.clear();
+        cacheConf.clear();
+        console.log(`configuration was reset`);
+        return;
+    }
+    // Начальный конфиг для визарда/--list: щадящий разбор (незаданные и битые поля =
+    // undefined), чтобы визард спросил недостающее, а --list всё равно показал конфиг.
+    const { config: rawConfig, issues: configIssues, salvaged } = readLenientConfig(conf);
+    const currentConfig = getOptions(rawConfig);
     if (opts.new || opts.config || !currentConfig.HAS_RUN)
         clearConsole();
     intro();
@@ -126,20 +170,42 @@ export default async () => {
     if (opts.new)
         return cmdNewProject(opts);
     if (opts.list)
-        return cmdList(currentConfig);
-    if (opts.reset) {
-        conf.clear();
-        cacheConf.clear();
-        console.log(`configuration was reset`);
-        return;
+        return cmdList(currentConfig, configIssues);
+    // Повторная сборка установленного проекта (есть HAS_RUN, не --config) — строгий путь:
+    // битый конфиг обязан упасть с внятной ошибкой сразу, а не быть тихо «починен» визардом.
+    // Первый запуск (!HAS_RUN) и --config остаются щадящими — это штатный путь восстановления.
+    const strictBuild = !opts.config && !!currentConfig.HAS_RUN;
+    if (configIssues.length) {
+        if (strictBuild)
+            failOnConfigIssues(configIssues);
+        warnConfigIssues(configIssues);
+        // Битые ключи чиним физически (salvage-значение = дефолт схемы, либо удаление):
+        // визард переспрашивает не всё (вложенные блоки гейтятся generate*-флагами), а
+        // строгий parseConfig после него обязан пройти — иначе exit 1 на каждом запуске.
+        for (const { key } of configIssues) {
+            const v = salvaged[key];
+            if (v === undefined)
+                conf.delete(key);
+            else
+                conf.set(key, v);
+        }
     }
     await cmdCollect(currentConfig, conf, opts);
     if (!opts.config) {
-        conf.set('hasRun', true);
         let isBuilding = false;
         let attemptedWatchBuild = false;
-        // Опции сборки после визарда: полный вид с дефолтами (базовые поля гарантированы).
-        const options = getOptions(conf);
+        // Опции сборки после визарда: строгий разбор итогового конфига. Штатно валиден
+        // (визард только что записал корректные значения; повторная сборка с битым конфигом
+        // отсеяна выше) — падение здесь страхует от иного невалидного состояния.
+        const built = parseConfig((conf.all ?? {}));
+        if (!built.ok)
+            failOnConfigIssues(built.issues);
+        // hasRun — только ПОСЛЕ успешной валидации: битый конфиг с hasRun=true навсегда
+        // уводил бы последующие запуски на строгий путь (exit 1 до визарда).
+        conf.set('hasRun', true);
+        const options = getOptions(built.value);
+        if (opts.systemFonts)
+            options.USE_SYSTEM_FONTS = true; // флаг сильнее ключа конфига
         const reloadEmitter = new EventEmitter();
         reloadEmitter.setMaxListeners(0);
         if (opts.watch) {
@@ -159,17 +225,31 @@ export default async () => {
                 isBuilding = true;
                 let buildOk = true;
                 try {
-                    await build(options, cacheConf);
-                    while (attemptedWatchBuild) {
-                        attemptedWatchBuild = false;
+                    // Лок на всю серию ребилдов: параллельная ручная сборка в этом же
+                    // каталоге не потопчет dist_bk и не потеряет чексуммы кеша.
+                    const release = acquireBuildLock(lockPath);
+                    try {
                         await build(options, cacheConf);
+                        while (attemptedWatchBuild) {
+                            attemptedWatchBuild = false;
+                            await build(options, cacheConf);
+                        }
+                    }
+                    finally {
+                        release();
                     }
                 }
                 catch (err) {
                     buildOk = false;
                     attemptedWatchBuild = false;
-                    const e = err;
-                    console.log(chalk.red(`build failed: ${e?.stack ? e.stack : e}`));
+                    if (err instanceof BuildLockHeldError) {
+                        // Соседняя сборка ещё идёт — ребилд пропущен, watch жив.
+                        console.log(chalk.yellow(`ребилд пропущен: ${err.message}`));
+                    }
+                    else {
+                        const e = err;
+                        console.log(chalk.red(`build failed: ${e?.stack ? e.stack : e}`));
+                    }
                 }
                 finally {
                     isBuilding = false;
@@ -179,7 +259,25 @@ export default async () => {
             });
         }
         isBuilding = true;
-        await build(options, cacheConf);
+        let release;
+        try {
+            release = acquireBuildLock(lockPath);
+        }
+        catch (e) {
+            // Занято живой сборкой — падаем сразу с внятным сообщением, без стектрейса.
+            console.error(chalk.red(e.message));
+            process.exit(1);
+        }
+        try {
+            await build(options, cacheConf);
+        }
+        finally {
+            release();
+            // Одиночная сборка: D2-воркер больше не нужен, без teardown он держал бы
+            // процесс. В watch-режиме воркер живёт до конца процесса (Ctrl+C).
+            if (!opts.watch)
+                await teardownD2();
+        }
         isBuilding = false;
         if (opts.site)
             return await cmdSite(options, opts, reloadEmitter);