@alfacapital-tech/c4builder 0.6.0 → 0.8.0

package/dist/plugins/openspec/index.js

@@ -4,6 +4,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { z } from 'zod';
 import { definePlugin } from "../../core/plugins/types.js";
+import { layoutChanges, pageOrder } from "./layout.js";
 import { scanStore } from "./scan.js";
 import { renderArchiveIndex, renderChange, renderChangesIndex, relSource, renderMarkdown, renderSpecTree, renderSummary } from "./render.js";
 const optionsSchema = z
@@ -12,7 +13,19 @@ const optionsSchema = z
     mount: z.string().min(1).default('OpenSpec'),
     // Порядок артефактов change'а; первый выводится на странице change'а, остальные —
     // подстраницами; не перечисленные — после, по алфавиту.
-    artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks'])
+    artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks']),
+    // Ключ `.openspec.yaml` со ссылкой на родительский change (например `x-parent`):
+    // вложенный change выводится страницей под родителем. Не задан — плоский список.
+    parentKey: z.string().min(1).optional(),
+    // Ключ `.openspec.yaml` с группой change'а (например `x-team`): change'ы верхнего
+    // уровня раскладываются по папкам групп `Changes/<группа>/<id>`. Не задан — без групп.
+    groupKey: z.string().min(1).optional(),
+    // Ключ `.openspec.yaml` с человеческим именем change'а (например `x-name`): подпись и
+    // сегмент пути change'а верхнего уровня вместо id. Не задан — id.
+    nameKey: z.string().min(1).optional(),
+    // Дополнительные колонки таблицы Changes из `.openspec.yaml` (например исполнитель):
+    // `[{ key: "x-assignee", title: "Assignee" }]`. Не задана — прежняя таблица.
+    columns: z.array(z.object({ key: z.string().min(1), title: z.string().min(1) }).strict()).optional()
 })
     .strict();
 export default definePlugin({
@@ -47,14 +60,37 @@ export default definePlugin({
                 }
             }
         };
-        const addChange = (change, segments) => addPages(renderChange(change, segments, o.artifacts, options), change.dir);
-        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options) });
+        // Родитель добавляется раньше вложенных: в sidebar под ним сначала его артефакты,
+        // затем вложенные change'ы. Страница группы — перед первым её change'ем, со своей
+        // таблицей (без секций — она сама и есть секция).
+        const addChanges = (changes, layout, section, index) => {
+            const seen = new Set();
+            for (const change of pageOrder(changes, layout)) {
+                const at = layout.get(change);
+                if (!at)
+                    continue;
+                if (at.group && !seen.has(at.group)) {
+                    seen.add(at.group);
+                    const members = changes.filter((c) => layout.get(c)?.group === at.group);
+                    ctx.addPage({ path: [mount, section, at.group], markdown: index(members) });
+                }
+                addPages(renderChange(change, at.segments, o.artifacts, options, layout), change.dir);
+            }
+        };
+        const { parentKey, groupKey, nameKey } = o;
+        const active = layoutChanges(store.changes, [mount, 'Changes'], { parentKey, groupKey, nameKey });
+        const archived = layoutChanges(store.archive, [mount, 'Archive'], {
+            parentKey,
+            groupKey,
+            nameKey,
+            archived: true
+        });
+        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options, active, o.columns) });
         ctx.addPage({
             path: [mount, 'Changes'],
-            markdown: renderChangesIndex(store.changes, mount, options)
+            markdown: renderChangesIndex(store.changes, mount, options, active, { columns: o.columns })
         });
-        for (const change of store.changes)
-            addChange(change, [mount, 'Changes', change.id]);
+        addChanges(store.changes, active, 'Changes', (members) => renderChangesIndex(members, mount, options, active, { sections: false, columns: o.columns }));
         // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
         // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
         const specsDir = path.join(storeDir, 'specs');
@@ -66,9 +102,8 @@ export default definePlugin({
         })), specsDir);
         ctx.addPage({
             path: [mount, 'Archive'],
-            markdown: renderArchiveIndex(store.archive, mount, options)
+            markdown: renderArchiveIndex(store.archive, mount, options, archived)
         });
-        for (const change of store.archive)
-            addChange(change, [mount, 'Archive', change.id]);
+        addChanges(store.archive, archived, 'Archive', (members) => renderArchiveIndex(members, mount, options, archived, { sections: false }));
     }
 });

package/dist/plugins/openspec/layout.js

@@ -0,0 +1,112 @@
+// Архивный change — `<YYYY-MM-DD>-<id>`; ссылка на родителя пишется по активному id.
+const DATE_PREFIX = /^\d{4}-\d{2}-\d{2}-/;
+const originalId = (c, archived) => archived ? c.id.replace(DATE_PREFIX, '') : c.id;
+/**
+ * Без `parentKey` — все change'ы на верхнем уровне `base` (прежнее поведение). С ним
+ * change, у которого в `.openspec.yaml` есть `parentKey`, указывающий на change того же
+ * списка, кладётся страницей под родителя. Вложенность — один уровень: родитель сам
+ * вложенный или не найден — change остаётся на верхнем уровне. Подпись вложенного — хвост
+ * id после `<id родителя>-`; если хвоста нет или он совпадает с подстраницей родителя
+ * (артефакт, `specs`) или с подписью соседа — полный id.
+ * С `groupKey` change верхнего уровня, у которого задан этот ключ, кладётся под папку
+ * группы: `<base>/<группа>/<id>`; вложенные идут за родителем. Значение со `/` или
+ * совпадающее с подписью change'а без группы (коллизия путей) — группой не считается.
+ * С `nameKey` подпись и сегмент пути change'а верхнего уровня — значение ключа (например
+ * `x-name: Оплата картой`): sidebar и таблицы читаются по-человечески, а адрес страницы
+ * стабилен, пока значение не меняют. Недопустимое значение (`/`, `\`, `#`, `?`, `.`, `..`) или
+ * занятое в той же папке — подпись остаётся id; для группы — то же, change остаётся без группы.
+ */
+export const layoutChanges = (changes, base, { parentKey, groupKey, nameKey, archived = false } = {}) => {
+    const byId = new Map(changes.map((c) => [originalId(c, archived), c]));
+    const parentOf = (c) => {
+        const ref = parentKey ? c.meta[parentKey] : undefined;
+        const p = ref ? byId.get(ref) : undefined;
+        return p && p !== c ? p : undefined;
+    };
+    const layout = new Map();
+    const top = changes.filter((c) => {
+        const p = parentOf(c);
+        return !p || parentOf(p);
+    });
+    // Значение ключа как сегмент пути: addPage отвергает `/`, `\`, `.`, `..` и пустые, а `#` и
+    // `?` encodeURI оставляет как есть — ссылка в sidebar оборвалась бы на якоре или запросе.
+    const segment = (key, c) => {
+        const v = key ? c.meta[key]?.trim() : undefined;
+        return v && !/[\\/#?]/.test(v) && v !== '.' && v !== '..' ? v : undefined;
+    };
+    // Имя, совпадающее с id другого change'а, дало бы тот же путь — остаётся id.
+    const ids = new Set(changes.map((c) => c.id));
+    const wanted = (c) => {
+        const name = segment(nameKey, c);
+        return name && !ids.has(name) ? name : c.id;
+    };
+    // Подписи change'ов без группы заняты на уровне base — группа с таким именем дала бы коллизию.
+    const flat = new Set(top.filter((c) => !segment(groupKey, c)).map(wanted));
+    const groups = new Set();
+    const used = new Map();
+    for (const c of top) {
+        const g = segment(groupKey, c);
+        const group = g && !flat.has(g) ? g : undefined;
+        if (group)
+            groups.add(group);
+        const folder = group ?? '';
+        const taken = used.get(folder) ?? new Set();
+        used.set(folder, taken);
+        // Повтор подписи в папке (или имя группы на уровне base) — откат на уникальный id.
+        const want = wanted(c);
+        const label = taken.has(want) || (!group && want !== c.id && groups.has(want)) ? c.id : want;
+        taken.add(label);
+        layout.set(c, {
+            segments: group ? [...base, group, label] : [...base, label],
+            label,
+            children: [],
+            group
+        });
+    }
+    for (const c of changes) {
+        if (layout.has(c))
+            continue;
+        const parent = parentOf(c);
+        const host = layout.get(parent);
+        const taken = new Set([
+            ...parent.artifacts.map((a) => a.name),
+            'specs',
+            ...host.children.map((s) => layout.get(s).label)
+        ]);
+        const own = originalId(c, archived);
+        const prefix = `${originalId(parent, archived)}-`;
+        const tail = own.startsWith(prefix) ? own.slice(prefix.length) : '';
+        const label = tail && !taken.has(tail) ? tail : c.id;
+        layout.set(c, {
+            segments: [...host.segments, label],
+            label,
+            parent,
+            children: [],
+            group: host.group
+        });
+        host.children.push(c);
+    }
+    return layout;
+};
+/** Группы раскладки по алфавиту; change'ы без группы в список не входят. */
+export const groupNames = (changes, layout) => [...new Set(changes.map((c) => layout.get(c)?.group).filter((g) => !!g))].sort((a, b) => a.localeCompare(b));
+/**
+ * Change'ы в порядке вывода: каждый верхнего уровня, сразу за ним — его вложенные. Порядок
+ * внутри обоих уровней — порядок `changes` (по имени для страниц, по дате для таблиц); с
+ * группами — сначала группы по алфавиту, затем change'ы без группы.
+ */
+export const pageOrder = (changes, layout) => {
+    const pos = new Map(changes.map((c, i) => [c, i]));
+    const groups = groupNames(changes, layout);
+    const rank = (c) => {
+        const g = layout.get(c)?.group;
+        return g ? groups.indexOf(g) : groups.length;
+    };
+    return changes
+        .filter((c) => !layout.get(c)?.parent)
+        .sort((a, b) => rank(a) - rank(b) || (pos.get(a) ?? 0) - (pos.get(b) ?? 0))
+        .flatMap((c) => [
+        c,
+        ...[...(layout.get(c)?.children ?? [])].sort((a, b) => (pos.get(a) ?? 0) - (pos.get(b) ?? 0))
+    ]);
+};

package/dist/plugins/openspec/render.js

@@ -3,6 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createFenceExtractor, mapOutsideFences } from "../../core/scan/fences.js";
 import { encodeURIPath } from "../../util/utils.js";
+import { groupNames, pageOrder } from "./layout.js";
 // Ссылка на страницу сайта от корня (без ведущего «/»): так же строится sidebar,
 // а docsify без relativePath резолвит ссылки от корня сайта.
 export const pageLink = (segments, options) => encodeURIPath(path.posix.join(...segments, options.WEB_FILE_NAME || segments[segments.length - 1]));
@@ -10,17 +11,46 @@ const fmtDate = (ms) => new Date(ms).toISOString().slice(0, 10);
 // Прогресс задач: нативный <progress> (docsify рендерит HTML в markdown) + числа и процент.
 const progressBar = (done, total) => `<progress value="${done}" max="${total}"></progress> ${done}/${total} (${Math.round((done / total) * 100)}%)`;
 const fmtProgress = (c) => c.progress ? progressBar(c.progress.done, c.progress.total) : '—';
-/** Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. */
-export const renderChangesIndex = (changes, mount, options) => {
+// Секции по группам (опция groupKey): `### <группа>` над своей частью таблицы или списка,
+// change'ы без группы — последней секцией `### Ungrouped`. Групп нет или `sections` выключен
+// (страница самой группы) — один блок без заголовка, как раньше.
+const bySections = (changes, layout, sections, render) => {
+    const groups = layout && sections ? groupNames(changes, layout) : [];
+    if (!groups.length)
+        return render(changes);
+    const groupOf = (c) => layout?.get(c)?.group;
+    const parts = groups.map((g) => `### ${g}\n\n${render(changes.filter((c) => groupOf(c) === g))}`);
+    const rest = changes.filter((c) => !groupOf(c));
+    if (rest.length)
+        parts.push(`### Ungrouped\n\n${render(rest)}`);
+    return parts.join('\n\n');
+};
+// Значение ячейки markdown-таблицы: `|` разорвал бы строку на колонки.
+const cell = (v) => (v ? v.replace(/\|/g, '\\|') : '—');
+/**
+ * Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. С `layout`
+ * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные
+ * страницы, а при группах таблица делится на секции по группам. `columns` — колонки из
+ * `.openspec.yaml` после стандартных (например исполнитель); нет значения — `—`.
+ */
+export const renderChangesIndex = (changes, mount, options, layout, { sections = true, columns = [] } = {}) => {
     if (!changes.length)
         return '_No changes._';
-    const rows = [...changes]
-        .sort((a, b) => b.mtime - a.mtime)
-        .map((c) => `| [${c.id}](${pageLink([mount, 'Changes', c.id], options)}) | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |`);
-    return ['| Change | Schema | Tasks | Updated |', '|---|---|---|---|', ...rows].join('\n');
+    const head = ['Change', 'Schema', 'Tasks', 'Updated', ...columns.map((c) => cell(c.title))];
+    const table = (part) => {
+        const byDate = [...part].sort((a, b) => b.mtime - a.mtime);
+        const rows = (layout ? pageOrder(byDate, layout) : byDate).map((c) => {
+            const at = layout?.get(c);
+            const link = `[${at?.label ?? c.id}](${pageLink(at?.segments ?? [mount, 'Changes', c.id], options)})`;
+            const extra = columns.map((col) => ` ${cell(c.meta[col.key])} |`).join('');
+            return `| ${at?.parent ? `↳ ${link}` : link} | ${c.schema ?? '—'} | ${fmtProgress(c)} | ${fmtDate(c.mtime)} |${extra}`;
+        });
+        return [`| ${head.join(' | ')} |`, `|${'---|'.repeat(head.length)}`, ...rows].join('\n');
+    };
+    return bySections(changes, layout, sections, table);
 };
 /** Сводка store (страница mount): счётчики, суммарный прогресс, таблица активных change'ов. */
-export const renderSummary = (store, mount, options) => {
+export const renderSummary = (store, mount, options, layout, columns = []) => {
     const withProgress = store.changes.filter((c) => c.progress);
     const done = withProgress.reduce((s, c) => s + (c.progress?.done ?? 0), 0);
     const total = withProgress.reduce((s, c) => s + (c.progress?.total ?? 0), 0);
@@ -33,11 +63,18 @@ export const renderSummary = (store, mount, options) => {
         '',
         '## Active changes',
         '',
-        renderChangesIndex(store.changes, mount, options)
+        renderChangesIndex(store.changes, mount, options, layout, { columns })
     ].join('\n');
 };
-export const renderArchiveIndex = (archive, mount, options) => archive.length
-    ? archive.map((c) => `- [${c.id}](${pageLink([mount, 'Archive', c.id], options)})`).join('\n')
+/** Список архива: от новых к старым; с `layout` вложенные — пунктами под родителем, по секциям групп. */
+export const renderArchiveIndex = (archive, mount, options, layout, { sections = true } = {}) => archive.length
+    ? bySections(archive, layout, sections, (part) => (layout ? pageOrder(part, layout) : part)
+        .map((c) => {
+        const at = layout?.get(c);
+        const link = pageLink(at?.segments ?? [mount, 'Archive', c.id], options);
+        return `${at?.parent ? '  ' : ''}- [${at?.label ?? c.id}](${link})`;
+    })
+        .join('\n'))
     : '_Archive is empty._';
 /** Индекс папки спек (Specs, промежуточные папки, дельты change'а): вложенный список под prefix. */
 export const renderSpecIndex = (specs, prefix, base, options) => {
@@ -179,7 +216,7 @@ const orderArtifacts = (artifacts, order) => [...artifacts].sort((a, b) => {
  * `specs` дельт (страница на capability, структура папок). Артефакт с именем `specs`
  * делит страницу с индексом дельт.
  */
-export const renderChange = (change, segments, order, options) => {
+export const renderChange = (change, segments, order, options, layout) => {
     const ordered = orderArtifacts(change.artifacts, order);
     const inline = ordered[0]?.name === order[0] ? ordered[0] : undefined;
     const deltas = change.deltas.map((d) => ({
@@ -222,11 +259,23 @@ export const renderChange = (change, segments, order, options) => {
     ]
         .filter(Boolean)
         .join(' · ');
+    // Связи по опции parentKey: у вложенного — ссылка на родителя, у родителя — на вложенные.
+    const at = layout?.get(change);
+    const linkTo = (c) => {
+        const p = layout?.get(c);
+        return p ? `[${p.label}](${pageLink(p.segments, options)})` : c.id;
+    };
+    const family = [
+        at?.parent && `**Parent:** ${linkTo(at.parent)}`,
+        at?.children.length && `**Sub-changes:** ${at.children.map(linkTo).join(' · ')}`
+    ]
+        .filter(Boolean)
+        .join(' · ');
     const main = inline ? render(segments, inline.name, inline.content) : undefined;
     const pages = [
         {
             path: segments,
-            markdown: [head, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
+            markdown: [head, family, links.join(' · '), main?.markdown].filter(Boolean).join('\n\n'),
             diagrams: main?.diagrams ?? [],
             files: main?.files ?? []
         },

package/dist/plugins/openspec/scan.js

@@ -32,17 +32,21 @@ export const taskProgress = (tasks) => {
         return undefined;
     return { done: boxes.filter((m) => m[1] !== ' ').length, total: boxes.length };
 };
-// Метаданные `.openspec.yaml` построчно: нужны два скаляра, yaml-парсер избыточен.
+// Метаданные `.openspec.yaml` построчно: нужны только скаляры верхнего уровня (schema,
+// created и пользовательские ключи вроде `x-parent`), yaml-парсер избыточен.
 const readMeta = (file) => {
-    if (!fs.existsSync(file))
-        return {};
     const meta = {};
-    for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
-        const m = line.match(/^(schema|created):\s*(.+?)\s*$/);
-        if (m)
-            meta[m[1]] = m[2].replace(/^["']|["']$/g, '');
-    }
-    return meta;
+    if (fs.existsSync(file))
+        for (const line of fs.readFileSync(file, 'utf8').split('\n')) {
+            const m = line.match(/^([A-Za-z0-9_.-]+):[ \t]*(.+?)\s*$/);
+            if (!m || m[2].startsWith('#'))
+                continue;
+            // Значение в кавычках — целиком (`x-name: "Задача #5"`); у остальных комментарий в
+            // конце строки (` # …`) — не часть значения.
+            const quoted = m[2].match(/^(["'])(.*?)\1(?:\s+#.*)?$/);
+            meta[m[1]] = quoted ? quoted[2] : m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
+        }
+    return { schema: meta.schema, created: meta.created, meta };
 };
 const scanChange = (dir) => {
     const files = fs.readdirSync(dir, { withFileTypes: true });

package/package.json

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