@alfacapital-tech/c4builder 0.7.0 → 0.8.0

package/dist/plugins/openspec/index.js

@@ -16,7 +16,16 @@ const optionsSchema = z
     artifacts: z.array(z.string()).default(['proposal', 'design', 'tasks']),
     // Ключ `.openspec.yaml` со ссылкой на родительский change (например `x-parent`):
     // вложенный change выводится страницей под родителем. Не задан — плоский список.
-    parentKey: z.string().min(1).optional()
+    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({
@@ -52,23 +61,36 @@ export default definePlugin({
             }
         };
         // Родитель добавляется раньше вложенных: в sidebar под ним сначала его артефакты,
-        // затем вложенные change'ы.
-        const addChanges = (changes, layout) => {
+        // затем вложенные 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)
-                    addPages(renderChange(change, at.segments, o.artifacts, options, layout), change.dir);
+                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 } = o;
-        const active = layoutChanges(store.changes, [mount, 'Changes'], { parentKey });
-        const archived = layoutChanges(store.archive, [mount, 'Archive'], { parentKey, archived: true });
-        ctx.addPage({ path: [mount], markdown: renderSummary(store, mount, options, active) });
+        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, active)
+            markdown: renderChangesIndex(store.changes, mount, options, active, { columns: o.columns })
         });
-        addChanges(store.changes, active);
+        addChanges(store.changes, active, 'Changes', (members) => renderChangesIndex(members, mount, options, active, { sections: false, columns: o.columns }));
         // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
         // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
         const specsDir = path.join(storeDir, 'specs');
@@ -82,6 +104,6 @@ export default definePlugin({
             path: [mount, 'Archive'],
             markdown: renderArchiveIndex(store.archive, mount, options, archived)
         });
-        addChanges(store.archive, archived);
+        addChanges(store.archive, archived, 'Archive', (members) => renderArchiveIndex(members, mount, options, archived, { sections: false }));
     }
 });

package/dist/plugins/openspec/layout.js

@@ -8,8 +8,15 @@ const originalId = (c, archived) => archived ? c.id.replace(DATE_PREFIX, '') : c
  * вложенный или не найден — change остаётся на верхнем уровне. Подпись вложенного — хвост
  * id после `<id родителя>-`; если хвоста нет или он совпадает с подстраницей родителя
  * (артефакт, `specs`) или с подписью соседа — полный id.
+ * С `groupKey` change верхнего уровня, у которого задан этот ключ, кладётся под папку
+ * группы: `<base>/<группа>/<id>`; вложенные идут за родителем. Значение со `/` или
+ * совпадающее с подписью change'а без группы (коллизия путей) — группой не считается.
+ * С `nameKey` подпись и сегмент пути change'а верхнего уровня — значение ключа (например
+ * `x-name: Оплата картой`): sidebar и таблицы читаются по-человечески, а адрес страницы
+ * стабилен, пока значение не меняют. Недопустимое значение (`/`, `\`, `#`, `?`, `.`, `..`) или
+ * занятое в той же папке — подпись остаётся id; для группы — то же, change остаётся без группы.
  */
-export const layoutChanges = (changes, base, { parentKey, archived = false } = {}) => {
+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;
@@ -21,8 +28,41 @@ export const layoutChanges = (changes, base, { parentKey, archived = false } = {
         const p = parentOf(c);
         return !p || parentOf(p);
     });
-    for (const c of top)
-        layout.set(c, { segments: [...base, c.id], label: c.id, children: [] });
+    // Значение ключа как сегмент пути: 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;
@@ -37,19 +77,34 @@ export const layoutChanges = (changes, base, { parentKey, archived = false } = {
         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: [] });
+        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` (по имени для страниц, по дате для таблиц).
+ * внутри обоих уровней — порядок `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,7 +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 { pageOrder } from "./layout.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]));
@@ -11,23 +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) : '—';
+// Секции по группам (опция 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'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные страницы.
+ * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные
+ * страницы, а при группах таблица делится на секции по группам. `columns` — колонки из
+ * `.openspec.yaml` после стандартных (например исполнитель); нет значения — `—`.
  */
-export const renderChangesIndex = (changes, mount, options, layout) => {
+export const renderChangesIndex = (changes, mount, options, layout, { sections = true, columns = [] } = {}) => {
     if (!changes.length)
         return '_No changes._';
-    const byDate = [...changes].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)})`;
-        return `| ${at?.parent ? `↳ ${link}` : link} | ${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, layout) => {
+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);
@@ -40,18 +63,18 @@ export const renderSummary = (store, mount, options, layout) => {
         '',
         '## Active changes',
         '',
-        renderChangesIndex(store.changes, mount, options, layout)
+        renderChangesIndex(store.changes, mount, options, layout, { columns })
     ].join('\n');
 };
-/** Список архива: от новых к старым; с `layout` вложенные — пунктами под родителем. */
-export const renderArchiveIndex = (archive, mount, options, layout) => archive.length
-    ? (layout ? pageOrder(archive, layout) : archive)
+/** Список архива: от новых к старым; с `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')
+        .join('\n'))
     : '_Archive is empty._';
 /** Индекс папки спек (Specs, промежуточные папки, дельты change'а): вложенный список под prefix. */
 export const renderSpecIndex = (specs, prefix, base, options) => {

package/dist/plugins/openspec/scan.js

@@ -41,8 +41,10 @@ const readMeta = (file) => {
             const m = line.match(/^([A-Za-z0-9_.-]+):[ \t]*(.+?)\s*$/);
             if (!m || m[2].startsWith('#'))
                 continue;
-            // Комментарий в конце строки (` # …`) — не часть значения.
-            meta[m[1]] = m[2].replace(/\s+#.*$/, '').replace(/^["']|["']$/g, '');
+            // Значение в кавычках — целиком (`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 };
 };

package/package.json

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