@alfacapital-tech/c4builder 0.6.0 → 0.7.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,10 @@ 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()
 })
     .strict();
 export default definePlugin({
@@ -47,14 +51,24 @@ 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'ы.
+        const addChanges = (changes, layout) => {
+            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);
+            }
+        };
+        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) });
         ctx.addPage({
             path: [mount, 'Changes'],
-            markdown: renderChangesIndex(store.changes, mount, options)
+            markdown: renderChangesIndex(store.changes, mount, options, active)
         });
-        for (const change of store.changes)
-            addChange(change, [mount, 'Changes', change.id]);
+        addChanges(store.changes, active);
         // Specs: индекс, промежуточные папки, страницы спек — тем же рендером, что и
         // дельты (fenced-диаграммы локально, ссылки на файлы рядом со спекой).
         const specsDir = path.join(storeDir, 'specs');
@@ -66,9 +80,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);
     }
 });

package/dist/plugins/openspec/layout.js

@@ -0,0 +1,57 @@
+// Архивный 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.
+ */
+export const layoutChanges = (changes, base, { parentKey, 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);
+    });
+    for (const c of top)
+        layout.set(c, { segments: [...base, c.id], label: c.id, children: [] });
+    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: [] });
+        host.children.push(c);
+    }
+    return layout;
+};
+/**
+ * Change'ы в порядке вывода: каждый верхнего уровня, сразу за ним — его вложенные. Порядок
+ * внутри обоих уровней — порядок `changes` (по имени для страниц, по дате для таблиц).
+ */
+export const pageOrder = (changes, layout) => {
+    const pos = new Map(changes.map((c, i) => [c, i]));
+    return changes
+        .filter((c) => !layout.get(c)?.parent)
+        .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 { 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,23 @@ 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) => {
+/**
+ * Таблица change'ов (сводка и индекс Changes): по дате изменения от новых к старым. С `layout`
+ * вложенные change'ы идут сразу под родителем (`↳` + подпись) и ведут на свои вложенные страницы.
+ */
+export const renderChangesIndex = (changes, mount, options, layout) => {
     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)} |`);
+    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');
 };
 /** Сводка store (страница mount): счётчики, суммарный прогресс, таблица активных change'ов. */
-export const renderSummary = (store, mount, options) => {
+export const renderSummary = (store, mount, options, layout) => {
     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 +40,18 @@ export const renderSummary = (store, mount, options) => {
         '',
         '## Active changes',
         '',
-        renderChangesIndex(store.changes, mount, options)
+        renderChangesIndex(store.changes, mount, options, layout)
     ].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) => archive.length
+    ? (layout ? pageOrder(archive, layout) : archive)
+        .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 +193,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 +236,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,19 @@ 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;
+            // Комментарий в конце строки (` # …`) — не часть значения.
+            meta[m[1]] = 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.7.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",