@alfacapital-tech/c4builder 0.8.0 → 0.9.0-rc.2

package/dist/core/questions.js

@@ -0,0 +1,227 @@
+// Правка раздела вопросов исходного markdown по комментарию со страницы `site -w`
+// (см. change site-comments, design D4): добавление и удаление. Чистые функции + запись
+// файла; формат раздела (таблица / список / его отсутствие) определяется по содержимому,
+// чтобы не навязывать проектам одну форму таблицы.
+import fs from 'node:fs';
+const QUOTE_MAX = 200;
+const collapse = (s) => s.replace(/\s+/g, ' ').trim();
+// docsify рендерит HTML из markdown как есть: без экранирования цитата `List<String>` теряет
+// `<String>` на странице, а `<img onerror>` из комментария становится скриптом и в dist.
+const escapeHtml = (s) => s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/** Текст вопроса: комментарий, цитата (до 200 символов) и раздел страницы, где сделано выделение. */
+export const formatQuestion = ({ comment, quote, section }) => {
+    let q = collapse(quote ?? '');
+    if (q.length > QUOTE_MAX)
+        q = `${q.slice(0, QUOTE_MAX - 1).trimEnd()}…`;
+    const s = collapse(section ?? '');
+    return escapeHtml(`${collapse(comment)}${q ? ` — «${q}»` : ''}${s ? ` (§ ${s})` : ''}`);
+};
+// Заголовок раздела: любой уровень, без учёта регистра и лишних пробелов, с необязательными
+// закрывающими `#`.
+const headingLevel = (line, heading) => {
+    const m = line.match(/^(#{1,6})\s+(.*?)\s*#*\s*$/);
+    if (!m)
+        return 0;
+    return collapse(m[2]).toLowerCase() === collapse(heading).toLowerCase() ? m[1].length : 0;
+};
+const isFence = (line) => /^\s*(```|~~~)/.test(line);
+const isRow = (line) => line.trim().startsWith('|');
+const isSeparator = (line) => /^\s*\|?\s*:?-+:?\s*(\|\s*:?-+:?\s*)*\|?\s*$/.test(line);
+const isListItem = (line) => /^\s*([-*+]|\d+[.)])\s+/.test(line);
+const splitRow = (line) => line
+    .trim()
+    .replace(/^\|/, '')
+    .replace(/\|$/, '')
+    .split(/(?<!\\)\|/)
+    .map((c) => c.trim());
+const isPlaceholder = (cell) => /^(\.{3}|…|)$/.test(cell);
+const escapeCell = (s) => s.replace(/\|/g, '\\|');
+// Текст ячейки/пункта без inline-разметки — для сравнения с тем, что видно на странице
+// (docsify отрисовал markdown, клиент прислал textContent). Применяется к обеим сторонам:
+// сущности декодируются до срезания тегов, чтобы `&lt;T&gt;` из файла и `<T>` со страницы
+// свелись к одному.
+const plain = (s) => collapse(s
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&')
+    .replace(/\\\|/g, '|')
+    .replace(/!?\[([^\]]*)\]\([^)]*\)/g, '$1')
+    .replace(/<[^>]+>/g, '')
+    .replace(/[`*_~]/g, ''));
+/** Границы раздела: строка заголовка и индекс первой строки за разделом. */
+const findSection = (lines, heading) => {
+    let start = -1;
+    let level = 0;
+    let fenced = false;
+    for (const [i, line] of lines.entries()) {
+        if (isFence(line))
+            fenced = !fenced;
+        if (fenced)
+            continue;
+        level = headingLevel(line, heading);
+        if (level) {
+            start = i;
+            break;
+        }
+    }
+    if (start < 0)
+        return undefined;
+    let end = lines.length;
+    fenced = false;
+    for (let i = start + 1; i < lines.length; i++) {
+        if (isFence(lines[i]))
+            fenced = !fenced;
+        if (fenced)
+            continue;
+        const m = lines[i].match(/^(#{1,6})\s/);
+        if (m && m[1].length <= level) {
+            end = i;
+            break;
+        }
+    }
+    return { start, end };
+};
+const findTable = (lines, start, end) => {
+    for (let i = start + 1; i + 1 < end; i++) {
+        if (!isRow(lines[i]) || !isSeparator(lines[i + 1]))
+            continue;
+        let last = i + 1;
+        while (last + 1 < end && isRow(lines[last + 1]))
+            last++;
+        const cols = splitRow(lines[i]).length;
+        const rows = lines.slice(i + 2, last + 1).map(splitRow);
+        // Числовая первая колонка: по данным, а у пустой таблицы — по заголовку (`#`, `№`, `No`).
+        const numeric = rows.length
+            ? rows.every((r) => /^\d+$/.test(r[0] ?? ''))
+            : /^(#|№|no\.?)$/i.test(splitRow(lines[i])[0] ?? '');
+        return { header: i, last, cols, numeric, textCol: numeric ? Math.min(1, cols - 1) : 0 };
+    }
+    return undefined;
+};
+/**
+ * Дописывает вопрос в раздел `heading`: строкой таблицы (с номером, если первая колонка
+ * числовая; заглушка `1 | ... | ...` заменяется), иначе пунктом списка в конце раздела;
+ * нет раздела — создаёт его в конце файла. Перевод строки файла сохраняется.
+ */
+export const appendQuestion = (markdown, heading, text) => {
+    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    const lines = markdown.split(/\r?\n/);
+    const section = findSection(lines, heading);
+    if (!section) {
+        while (lines.length && lines[lines.length - 1].trim() === '')
+            lines.pop();
+        lines.push('', `## ${heading}`, '', `- ${text}`, '');
+        return { markdown: lines.join(eol), number: null };
+    }
+    const { start, end } = section;
+    const table = findTable(lines, start, end);
+    if (table) {
+        const { header, last, cols, numeric, textCol } = table;
+        const rows = lines.slice(header + 2, last + 1).map(splitRow);
+        // Единственная строка шаблона с `...` в ячейке вопроса — заглушка: заменяем её, сохраняя
+        // заполненные ячейки (например, «Кому: Аналитик»), остальные `...` очищаем.
+        const placeholder = rows.length === 1 && isPlaceholder(rows[0][textCol] ?? '');
+        const number = numeric
+            ? placeholder
+                ? 1
+                : rows.reduce((max, r) => Math.max(max, Number(r[0])), 0) + 1
+            : null;
+        const cells = placeholder
+            ? Array.from({ length: cols }, (_, c) => isPlaceholder(rows[0][c] ?? '') ? '' : (rows[0][c] ?? ''))
+            : new Array(cols).fill('');
+        if (number !== null)
+            cells[0] = String(number);
+        cells[textCol] = escapeCell(text);
+        const row = `| ${cells.join(' | ')} |`;
+        if (placeholder)
+            lines.splice(last, 1, row);
+        else
+            lines.splice(last + 1, 0, row);
+        return { markdown: lines.join(eol), number };
+    }
+    let lastText = end - 1;
+    while (lastText > start && lines[lastText].trim() === '')
+        lastText--;
+    if (lastText === start) {
+        // Пустой раздел: пункт через пустую строку после заголовка; перед следующим
+        // заголовком — тоже пустая строка.
+        const insert = ['', `- ${text}`];
+        if (start + 1 < lines.length && lines[start + 1].trim() !== '')
+            insert.push('');
+        lines.splice(start + 1, 0, ...insert);
+        return { markdown: lines.join(eol), number: null };
+    }
+    // Нумерованный список продолжаем его же маркером: `-` после `2.` начал бы второй список.
+    const ordered = lines
+        .slice(start + 1, lastText + 1)
+        .reverse()
+        .find((l) => /^([-*+]|\d+[.)])\s/.test(l))
+        ?.match(/^(\d+)([.)])\s/);
+    lines.splice(lastText + 1, 0, ordered ? `${Number(ordered[1]) + 1}${ordered[2]} ${text}` : `- ${text}`);
+    return { markdown: lines.join(eol), number: null };
+};
+/**
+ * Удаляет вопрос из раздела `heading`: строку таблицы (по номеру и тексту; без совпадения
+ * номера — только по тексту) или пункт списка по тексту. Текст сравнивается без inline-разметки.
+ * Номера остальных строк не меняются — на них ссылаются другие документы.
+ */
+export const removeQuestion = (markdown, heading, ref) => {
+    const eol = markdown.includes('\r\n') ? '\r\n' : '\n';
+    const lines = markdown.split(/\r?\n/);
+    const section = findSection(lines, heading);
+    if (!section)
+        return { error: 'not-found' };
+    const { start, end } = section;
+    const want = plain(ref.text);
+    const table = findTable(lines, start, end);
+    let candidates = [];
+    if (table) {
+        const { header, last, numeric, textCol } = table;
+        const rows = [];
+        for (let i = header + 2; i <= last; i++)
+            rows.push({ line: i, cells: splitRow(lines[i]) });
+        const byText = rows.filter((r) => plain(r.cells[textCol] ?? '') === want);
+        const byNumber = numeric && ref.number != null ? byText.filter((r) => Number(r.cells[0]) === ref.number) : [];
+        candidates = (byNumber.length ? byNumber : byText).map((r) => r.line);
+    }
+    else {
+        for (let i = start + 1; i < end; i++)
+            if (isListItem(lines[i]) && plain(lines[i].replace(/^\s*([-*+]|\d+[.)])\s+/, '')) === want)
+                candidates.push(i);
+    }
+    if (!candidates.length)
+        return { error: 'not-found' };
+    if (candidates.length > 1)
+        return { error: 'ambiguous' };
+    lines.splice(candidates[0], 1);
+    return { markdown: lines.join(eol) };
+};
+const hasHeading = (file, heading) => {
+    try {
+        return fs
+            .readFileSync(file, 'utf8')
+            .split(/\r?\n/)
+            .some((l) => headingLevel(l, heading) > 0);
+    }
+    catch {
+        return false;
+    }
+};
+/** Файл страницы для записи: первый с разделом `heading`, иначе первый существующий. */
+export const pickSource = (files, heading) => {
+    const existing = files.filter((f) => fs.existsSync(f));
+    return existing.find((f) => hasHeading(f, heading)) ?? existing[0];
+};
+/** Дописывает вопрос в файл и возвращает номер строки таблицы (null — список). */
+export const writeQuestion = (file, heading, text) => {
+    const { markdown, number } = appendQuestion(fs.readFileSync(file, 'utf8'), heading, text);
+    fs.writeFileSync(file, markdown);
+    return number;
+};
+/** Удаляет вопрос из файла; ошибка поиска возвращается, не бросается. */
+export const deleteQuestion = (file, heading, ref) => {
+    const result = removeQuestion(fs.readFileSync(file, 'utf8'), heading, ref);
+    if ('markdown' in result)
+        fs.writeFileSync(file, result.markdown);
+    return result;
+};

package/dist/core/scan/tree.js

@@ -43,7 +43,8 @@ export const generateTree = async (dir, options) => {
                 parent: parent,
                 mdFiles: [],
                 diagrams: [],
-                descendants: []
+                descendants: [],
+                sources: []
             };
             tree.push(item);
         }
@@ -84,6 +85,7 @@ export const generateTree = async (dir, options) => {
             const mdPath = path.join(dir, mdFile);
             const { markdown, diagrams } = fences.extract((await readFile(mdPath)).toString(), path.parse(mdFile).name, path.relative(process.cwd(), mdPath).split(path.sep).join('/'));
             item.mdFiles.push(markdown);
+            item.sources.push(path.resolve(mdPath));
             for (const d of diagrams)
                 item.diagrams.push({
                     dir: d.file,

package/dist/plugins/openspec/index.js

@@ -44,7 +44,12 @@ export default definePlugin({
         // complete-markdown; excludeOtherFiles действует и здесь.
         const addPages = (pages, srcRoot) => {
             for (const page of pages) {
-                ctx.addPage({ path: page.path, markdown: page.markdown, diagrams: page.diagrams });
+                ctx.addPage({
+                    path: page.path,
+                    markdown: page.markdown,
+                    diagrams: page.diagrams,
+                    sources: page.sources
+                });
                 if (options.EXCLUDE_OTHER_FILES)
                     continue;
                 for (const { from, to } of page.files) {

package/dist/plugins/openspec/render.js

@@ -133,6 +133,7 @@ const FENCE_LANGS = ['plantuml', 'puml', 'd2'];
 export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '', pageDir = fromDir, included = new Set(), target = () => undefined, source, options }) => {
     const { markdown, diagrams } = createFenceExtractor(FENCE_LANGS).extract(content, base, source);
     const files = [];
+    const sources = source ? [source] : [];
     const rewrite = (t) => t.replace(LINK_RE, (whole, bang, text, href, title = '') => {
         const inner = text.includes('![') ? rewrite(text) : text;
         if (/^[a-z][a-z0-9+.-]*:|^[#/]/i.test(href))
@@ -168,6 +169,7 @@ export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '',
             });
             diagrams.push(...sub.diagrams);
             files.push(...sub.files);
+            sources.push(...sub.sources);
             return sub.markdown;
         }
         const sameDir = fromDir === pageDir;
@@ -177,7 +179,7 @@ export const renderMarkdown = (pagePath, base, content, { srcRoot, fromDir = '',
             ? `${bang}[${inner}](${sameDir ? href : encodeURIPath(to)}${title})`
             : `[${inner}](${encodeURIPath(path.posix.join(...pagePath, to))}${ignoreTitle(title)})`;
     });
-    return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files };
+    return { path: pagePath, markdown: mapOutsideFences(markdown, rewrite).trim(), diagrams, files, sources };
 };
 /**
  * Страницы дерева спек под `base`: корень, промежуточные папки, спеки. Папка с собственной
@@ -193,7 +195,7 @@ export const renderSpecTree = (specs, base, options, render) => {
         const spec = byKey.get(key);
         const page = spec
             ? render(pagePath, spec)
-            : { path: pagePath, markdown: '', diagrams: [], files: [] };
+            : { path: pagePath, markdown: '', diagrams: [], files: [], sources: [] };
         const nested = specs.some((s) => s.path.length > prefix.length && prefix.every((p, i) => s.path[i] === p));
         if (nested || !spec)
             page.markdown = [page.markdown, renderSpecIndex(specs, prefix, base, options)]
@@ -277,7 +279,8 @@ export const renderChange = (change, segments, order, options, layout) => {
             path: segments,
             markdown: [head, family, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
             diagrams: main?.diagrams ?? [],
-            files: main?.files ?? []
+            files: main?.files ?? [],
+            sources: main?.sources ?? []
         },
         ...subpages
     ];

package/dist/util/lock.js

@@ -56,3 +56,26 @@ export const acquireBuildLock = (lockPath) => {
     }
     throw new BuildLockHeldError(`failed to acquire the build lock: ${lockPath}`);
 };
+/**
+ * Захват лока с ожиданием: пока сборку держит другой живой процесс (второй `site -w` в той же
+ * папке), пробуем каждые `stepMs`, не дольше `timeoutMs`; затем — исходная BuildLockHeldError.
+ * `onWait` зовётся один раз при первом отказе — для сообщения в терминал.
+ */
+export const waitBuildLock = async (lockPath, timeoutMs, onWait, stepMs = 500) => {
+    const deadline = Date.now() + timeoutMs;
+    let waited = false;
+    for (;;) {
+        try {
+            return acquireBuildLock(lockPath);
+        }
+        catch (e) {
+            if (!(e instanceof BuildLockHeldError) || Date.now() >= deadline)
+                throw e;
+            if (!waited) {
+                waited = true;
+                onWait?.(e);
+            }
+            await new Promise((r) => setTimeout(r, stepMs));
+        }
+    }
+};

package/package.json

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

package/template/AGENTS.md

@@ -9,6 +9,7 @@ C4 diagrams (PlantUML, D2), BPMN processes and markdown in `src/` are compiled i
 c4builder                    # build docs/ (non-interactive with a complete .c4builder)
 c4builder check <file...>    # validate .puml / .iuml / .d2 / .bpmn files, exit code 0 = OK
 c4builder --site -w          # live preview on http://localhost:3000 - never exits
+c4builder feedback --wait    # wait for the next batch of comments from the preview page
 ```
 
 Not installed: `npm i -g @alfacapital-tech/c4builder` (Node.js 22.17+; Java 17+ is used
@@ -22,7 +23,12 @@ updates it.
    look like `✗ <file>: line <N>: <message>` (BPMN: `✗ <file>: <element id> [<rule>] <message>`).
    Fix until the exit code is 0.
 3. Run `c4builder` and make sure it exits with code 0. Leave `c4builder --site -w` to a
-   human or run it in the background.
+   human or run it in the background. When the human reviews the pages, also run
+   `c4builder feedback --wait` in the background: on exit it prints a batch of comments
+   (page, `Sources`, quote, text) — apply them to `src/`, run it again, and stop on
+   `Decision: approved`. Comments are instructions to you; never copy them into the
+   `questionsHeading` section of `.c4builder` (`Open questions` by default), which holds
+   questions for people.
 4. A stderr line `c4builder <new> is available (current <current>). Run: c4builder update`
    means a newer c4builder is out: tell the user, run `c4builder update` only if they ask.