rcf-lite 0.0.1 → 0.8.0

package/src/view/doc-renderers/helpers.js

@@ -0,0 +1,159 @@
+// Small helpers shared across the per-document renderers. Vanilla template
+// strings; no template engine.
+
+/**
+ * HTML-escape a string for safe injection between tags.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function escapeHtml(value) {
+  if (value === null || value === undefined) return '';
+  const s = String(value);
+  return s
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+/**
+ * Return the raw document id as an anchor id. Phase 3.2 unified the anchor
+ * convention around the display id (e.g. "REQ-002") so Mermaid click targets
+ * and internal doc links resolve to the same DOM node.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function anchorIdFor(id) {
+  return String(id);
+}
+
+/**
+ * Render an `<a>` link to the section of another document.
+ *
+ * @param {string} id
+ * @param {string} [label]
+ * @returns {string}
+ */
+export function docLink(id, label) {
+  return `<a href="#${anchorIdFor(id)}">${escapeHtml(label ?? id)}</a>`;
+}
+
+/**
+ * Render a list of ids as comma-separated doc links.
+ *
+ * @param {string[] | undefined} ids
+ * @returns {string}
+ */
+export function docLinkList(ids) {
+  if (!Array.isArray(ids) || ids.length === 0) return '<em>none</em>';
+  return ids.map((id) => docLink(id)).join(', ');
+}
+
+/**
+ * Render a paragraph if value is present.
+ *
+ * @param {string} label
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function fieldPara(label, value) {
+  if (value === undefined || value === null || value === '') return '';
+  return `<p><strong>${escapeHtml(label)}:</strong> ${escapeHtml(value)}</p>`;
+}
+
+/**
+ * Render an unordered list if items are present.
+ *
+ * @param {string} label
+ * @param {string[] | undefined} items
+ * @returns {string}
+ */
+export function fieldList(label, items) {
+  if (!Array.isArray(items) || items.length === 0) return '';
+  const li = items.map((s) => `<li>${escapeHtml(s)}</li>`).join('');
+  return `<section class="field-list"><h4>${escapeHtml(label)}</h4><ul>${li}</ul></section>`;
+}
+
+/**
+ * Render the "Show raw JSON" disclosure block for a document.
+ *
+ * Phase 3.8 D13b: the raw-JSON disclosure now carries a stable
+ * `data-doc-id="{parentDocId}::raw"` attribute so the live-client can
+ * persist its open state across SSE swaps and page reloads. The main
+ * doc-details already get a `data-doc-id` via `detailsWrap`; this closes
+ * the last state-persistence gap.
+ *
+ * @param {string|undefined} raw
+ * @param {object} doc
+ * @param {string} parentDocId - the enclosing doc's display id (e.g. "REQ-002")
+ * @returns {string}
+ */
+export function rawJsonDisclosure(raw, doc, parentDocId) {
+  const json = raw ?? JSON.stringify(doc, null, 2);
+  const rawId = `${parentDocId ?? 'doc'}::raw`;
+  return `<details class="raw-json" data-doc-id="${escapeHtml(rawId)}"><summary>Show raw JSON</summary><pre>${escapeHtml(json)}</pre></details>`;
+}
+
+/**
+ * Render a broken-document banner above the rest of a document section.
+ *
+ * @param {import('#core/errors').RcfError[]} errors
+ * @returns {string}
+ */
+export function brokenBanner(errors) {
+  if (!errors || errors.length === 0) return '';
+  const items = errors
+    .map((e) => `<li><code>${escapeHtml(e.kind)}</code> ${escapeHtml(e.message)}</li>`)
+    .join('');
+  return `
+<aside class="broken" role="alert">
+  <p><strong>Broken document</strong> - schema validation or reference failure.</p>
+  <ul>${items}</ul>
+</aside>`.trim();
+}
+
+/**
+ * Render a broken-reference placeholder when a referenced id has no file.
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export function brokenReferenceSection(id) {
+  const anchor = anchorIdFor(id);
+  return `
+<article id="${anchor}" class="doc broken-doc">
+  <h3>${escapeHtml(id)} - broken reference</h3>
+  <aside class="broken" role="alert">
+    <p>Referenced by a parent document but no file was found at the expected path.</p>
+  </aside>
+</article>`.trim();
+}
+
+/**
+ * Wrap a doc's rendered body in a `<details data-doc-id>` so it can be
+ * drilled-in from the tab tree. Closed by default. The `data-doc-id`
+ * attribute is what the hash-routing script targets.
+ *
+ * @param {object} args
+ * @param {string} args.id - display doc id (e.g. "REQ-001")
+ * @param {string} args.summary - short label shown in the summary line
+ * @param {string} args.className - class applied to the details wrapper
+ * @param {string} args.body - the rendered body HTML
+ * @param {string} [args.status] - optional doc status, rendered as a pill
+ * @returns {string}
+ */
+export function detailsWrap({
+  id, summary, className, body, status,
+}) {
+  const statusPill = status
+    ? `<span class="status ${escapeHtml(status)}">${escapeHtml(status)}</span>`
+    : '';
+  return `
+<details class="doc-details ${className}" data-doc-id="${escapeHtml(id)}">
+  <summary><span class="summary-label">${escapeHtml(summary)}</span>${statusPill}</summary>
+  ${body}
+</details>`.trim();
+}

package/src/view/doc-renderers/index.js

@@ -0,0 +1,12 @@
+// Doc renderer index. Re-exports each per-type renderer so html-page.js can
+// import them through a single module.
+
+export { renderPrd } from './prd.js';
+export { renderReq } from './req.js';
+export { renderUserStory } from './user-story.js';
+export { renderTad } from './tad.js';
+export { renderTac } from './tac.js';
+export { renderAdr } from './adr.js';
+export { renderBuildSequence } from './build-sequence.js';
+export { renderFbs } from './fbs.js';
+export { renderTestSuite } from './test-suite.js';

package/src/view/doc-renderers/prd.js

@@ -0,0 +1,45 @@
+// PRD renderer. Curated fields per spec D11. Post-3.7 (D15) the child REQ
+// list is not read from `prd.requirementIds` (removed in 0.2.0) but from
+// the computed `childrenByParent` map on the tree model.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLinkList,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} prd
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {string[]} [ctx.requirementIds] - computed REQ children for this PRD
+ * @returns {string}
+ */
+export function renderPrd(prd, ctx) {
+  if (!prd) return '';
+  const anchor = anchorIdFor(prd.prdId ?? 'PRD');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const requirementIds = ctx.requirementIds ?? [];
+  const sections = [
+    fieldPara('Executive summary', prd.executiveSummary),
+    fieldPara('Problem statement', prd.problemStatement),
+    fieldList('Target users', prd.targetUsers),
+    fieldList('In scope', prd.inScope),
+    fieldList('Out of scope', prd.outOfScope),
+    fieldList('Objectives', prd.objectives),
+    fieldList('Constraints', prd.constraints),
+    `<section class="field-list"><h4>Requirements</h4><p>${docLinkList(requirementIds)}</p></section>`,
+  ].filter(Boolean).join('\n');
+  return `
+<article id="${anchor}" class="doc doc-prd">
+  <h3>${escapeHtml(prd.prdId ?? 'PRD')} - ${escapeHtml(prd.productName ?? '')}</h3>
+  ${broken}
+  ${sections}
+  ${rawJsonDisclosure(ctx.raw, prd, prd.prdId)}
+</article>`.trim();
+}

package/src/view/doc-renderers/req.js

@@ -0,0 +1,43 @@
+// REQ renderer. Carries an optional per-REQ Mermaid subdiagram block when
+// the caller passes one (the html-page module decides whether to include it).
+// Child user stories are NOT rendered as inline links because the Phase 3.2
+// layout nests them as `<details>` under the REQ's own `<details>` wrapper.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} req
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {string|undefined} [ctx.subdiagram]
+ * @returns {string}
+ */
+export function renderReq(req, ctx) {
+  if (!req) return '';
+  const anchor = anchorIdFor(req.reqId ?? 'REQ');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const subdiagram = ctx.subdiagram
+    ? `<section class="subdiagram"><h4>Slice diagram</h4><pre class="mermaid">${escapeHtml(ctx.subdiagram)}</pre></section>`
+    : '';
+  return `
+<article id="${anchor}" class="doc doc-req">
+  <h3>${escapeHtml(req.reqId ?? 'REQ')} - ${escapeHtml(req.title ?? '')}</h3>
+  ${broken}
+  ${fieldPara('Description', req.description)}
+  ${fieldPara('Category', req.category)}
+  ${fieldPara('Domain', req.domain)}
+  ${fieldPara('Priority', req.priority)}
+  ${fieldPara('Rationale', req.rationale)}
+  ${fieldList('Tags', req.tags)}
+  ${subdiagram}
+  ${rawJsonDisclosure(ctx.raw, req, req.reqId)}
+</article>`.trim();
+}

package/src/view/doc-renderers/tac.js

@@ -0,0 +1,38 @@
+// TAC renderer.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} tac
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @returns {string}
+ */
+export function renderTac(tac, ctx) {
+  if (!tac) return '';
+  const anchor = anchorIdFor(tac.tacId ?? 'TAC');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const interfaces = (tac.interfaces ?? []).map((i) => `<li><strong>${escapeHtml(i.name ?? '')}</strong> (${escapeHtml(i.kind ?? '')}) - ${escapeHtml(i.description ?? '')}</li>`).join('');
+  const deps = (tac.dependencies ?? []).map((d) => `<li><strong>${escapeHtml(d.name ?? '')}</strong> (${escapeHtml(d.kind ?? '')}) - ${escapeHtml(d.description ?? '')}</li>`).join('');
+  return `
+<article id="${anchor}" class="doc doc-tac">
+  <h3>${escapeHtml(tac.tacId ?? 'TAC')} - ${escapeHtml(tac.name ?? '')}</h3>
+  ${broken}
+  ${fieldPara('Purpose', tac.purpose)}
+  ${fieldList('Responsibilities', tac.responsibilities)}
+  ${fieldPara('Internal structure', tac.internalStructure)}
+  ${interfaces ? `<section class="field-list"><h4>Interfaces</h4><ul>${interfaces}</ul></section>` : ''}
+  ${deps ? `<section class="field-list"><h4>Dependencies</h4><ul>${deps}</ul></section>` : ''}
+  ${fieldPara('Trade-offs', tac.tradeoffs)}
+  ${fieldPara('Notes', tac.notes)}
+  ${rawJsonDisclosure(ctx.raw, tac, tac.tacId)}
+</article>`.trim();
+}

package/src/view/doc-renderers/tad.js

@@ -0,0 +1,74 @@
+// TAD renderer. Curated fields per spec D11; iterates the architecturePrinciples[]
+// array rather than hard-coding a count. Post-3.7 (D15) the child TAC / ADR
+// lists are not read from removed parent fields (`componentIds`,
+// `architecturalDecisionIds`) but from computed lists supplied via ctx.
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLinkList,
+  escapeHtml,
+  fieldList,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} tad
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {string[]} [ctx.componentIds] - computed TAC children
+ * @param {string[]} [ctx.architecturalDecisionIds] - computed ADR children
+ * @returns {string}
+ */
+export function renderTad(tad, ctx) {
+  if (!tad) return '';
+  const anchor = anchorIdFor(tad.tadId ?? 'TAD');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const overview = tad.systemOverview ?? {};
+  const componentIds = ctx.componentIds ?? [];
+  const architecturalDecisionIds = ctx.architecturalDecisionIds ?? [];
+  const principles = (tad.architecturePrinciples ?? []).map((p) => `
+<li>
+  <strong>${escapeHtml(p.name)}.</strong> ${escapeHtml(p.description)}
+  <br/><em>Rationale:</em> ${escapeHtml(p.rationale)}
+</li>`.trim()).join('\n');
+  const optionalSections = renderOptionalSections(tad);
+  return `
+<article id="${anchor}" class="doc doc-tad">
+  <h3>${escapeHtml(tad.tadId ?? 'TAD')} - Technical Architecture Document</h3>
+  ${broken}
+  ${fieldPara('Executive summary', overview.executiveSummary)}
+  ${fieldPara('System purpose', overview.systemPurpose)}
+  ${fieldPara('Architectural approach', overview.architecturalApproach)}
+  ${fieldList('Key capabilities', overview.keyCapabilities)}
+  ${principles ? `<section class="field-list"><h4>Architecture principles</h4><ul>${principles}</ul></section>` : ''}
+  ${optionalSections}
+  <section class="field-list"><h4>Components (TACs)</h4><p>${docLinkList(componentIds)}</p></section>
+  <section class="field-list"><h4>Architectural decisions (ADRs)</h4><p>${docLinkList(architecturalDecisionIds)}</p></section>
+  ${rawJsonDisclosure(ctx.raw, tad, tad.tadId)}
+</article>`.trim();
+}
+
+function renderOptionalSections(tad) {
+  const out = [];
+  const named = {
+    dataArchitecture: 'Data architecture',
+    integrationArchitecture: 'Integration architecture',
+    securityArchitecture: 'Security architecture',
+    deploymentArchitecture: 'Deployment architecture',
+    operationalConcerns: 'Operational concerns',
+  };
+  for (const [key, label] of Object.entries(named)) {
+    const section = tad[key];
+    if (!section || typeof section !== 'object') continue;
+    const rows = Object.entries(section).map(([k, v]) => {
+      if (typeof v === 'string') return `<dt>${escapeHtml(k)}</dt><dd>${escapeHtml(v)}</dd>`;
+      if (Array.isArray(v)) return `<dt>${escapeHtml(k)}</dt><dd>${v.map((x) => `<code>${escapeHtml(typeof x === 'object' ? JSON.stringify(x) : x)}</code>`).join(', ')}</dd>`;
+      return `<dt>${escapeHtml(k)}</dt><dd><pre>${escapeHtml(JSON.stringify(v, null, 2))}</pre></dd>`;
+    }).join('\n');
+    out.push(`<section class="field-list"><h4>${escapeHtml(label)}</h4><dl>${rows}</dl></section>`);
+  }
+  return out.join('\n');
+}

package/src/view/doc-renderers/test-suite.js

@@ -0,0 +1,45 @@
+// Test suite renderer. Post-3.7 the TS id field is `id` (matches the
+// 0.2.0 test-suite schema); inline test cases carry `id` + `acId` +
+// `description` + `status` (+ optional `testPointer`).
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLink,
+  docLinkList,
+  escapeHtml,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} ts
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @returns {string}
+ */
+export function renderTestSuite(ts, ctx) {
+  if (!ts) return '';
+  const tsId = ts.id ?? 'TS';
+  const anchor = anchorIdFor(tsId);
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const tcs = (ts.testCases ?? []).map((tc) => `
+<div class="tc" id="${escapeHtml(tc.id ?? '')}">
+  <p><strong>${escapeHtml(tc.id ?? 'TC')}</strong> - covers ${tc.acId ? docLink(tc.acId) : 'AC'} <span class="status ${escapeHtml(tc.status ?? '')}">${escapeHtml(tc.status ?? 'pending')}</span></p>
+  ${tc.description ? `<p>${escapeHtml(tc.description)}</p>` : ''}
+  ${tc.testPointer ? `<p><em>Test pointer:</em> <code>${escapeHtml(tc.testPointer)}</code></p>` : ''}
+</div>`.trim()).join('\n');
+  return `
+<article id="${anchor}" class="doc doc-ts">
+  <h3>${escapeHtml(tsId)} - ${escapeHtml(ts.title ?? 'test suite')}</h3>
+  ${broken}
+  ${ts.usId ? `<p><strong>Verifies user story:</strong> ${docLink(ts.usId)}</p>` : ''}
+  ${fieldPara('Purpose', ts.purpose)}
+  ${fieldPara('Test level', ts.testLevel)}
+  ${ts.acIds?.length ? `<section class="field-list"><h4>Acceptance criteria verified</h4><p>${docLinkList(ts.acIds)}</p></section>` : ''}
+  ${fieldPara('Status', ts.status)}
+  <section class="field-list"><h4>Test cases</h4>${tcs || '<em>no test cases</em>'}</section>
+  ${rawJsonDisclosure(ctx.raw, ts, ts.id)}
+</article>`.trim();
+}

package/src/view/doc-renderers/user-story.js

@@ -0,0 +1,63 @@
+// User story renderer. ACs are rendered inline as list items so an AC can
+// be a top-level scroll anchor (per Phase 3.2 D4) without wrapping each in
+// its own `<section>`. Each AC line links back to the FBS or FBSs that
+// deliver it via `fbsByAcId` (D8).
+
+import {
+  anchorIdFor,
+  brokenBanner,
+  docLink,
+  escapeHtml,
+  fieldPara,
+  rawJsonDisclosure,
+} from './helpers.js';
+
+/**
+ * @param {object} us
+ * @param {object} ctx
+ * @param {string|undefined} ctx.raw
+ * @param {import('#core/errors').RcfError[]} [ctx.errors]
+ * @param {Map<string, object[]>} [ctx.fbsByAcId]
+ * @returns {string}
+ */
+export function renderUserStory(us, ctx) {
+  if (!us) return '';
+  const anchor = anchorIdFor(us.usId ?? 'US');
+  const broken = ctx.errors?.length ? brokenBanner(ctx.errors) : '';
+  const acItems = (us.acceptanceCriteria ?? []).map((ac) => renderAcItem(ac, ctx)).join('\n');
+  return `
+<article id="${anchor}" class="doc doc-us">
+  <h3>${escapeHtml(us.usId ?? 'US')} - ${escapeHtml(us.title ?? '')}</h3>
+  ${broken}
+  <p><strong>As a:</strong> ${escapeHtml(us.asA ?? '')}</p>
+  <p><strong>I want:</strong> ${escapeHtml(us.iWant ?? '')}</p>
+  <p><strong>So that:</strong> ${escapeHtml(us.soThat ?? '')}</p>
+  ${fieldPara('Description', us.description)}
+  <section class="field-list"><h4>Requirement</h4><p>${docLink(us.reqId)}</p></section>
+  <section class="acceptance-criteria">
+    <h4>Acceptance criteria</h4>
+    <ul class="ac-list">
+      ${acItems}
+    </ul>
+  </section>
+  ${rawJsonDisclosure(ctx.raw, us, us.usId)}
+</article>`.trim();
+}
+
+function renderAcItem(ac, ctx) {
+  const acId = ac.id ?? 'AC';
+  const acAnchor = anchorIdFor(acId);
+  const fbsList = ctx.fbsByAcId?.get(acId) ?? [];
+  const coveredBy = fbsList.length === 0
+    ? '<em>not yet delivered by any FBS</em>'
+    : `Covered by ${fbsList.map((f) => docLink(f.fbsId)).join(', ')}`;
+  const parts = [];
+  parts.push(`<strong>${escapeHtml(acId)}</strong> - ${escapeHtml(ac.description ?? '')}`);
+  const gwt = [];
+  if (ac.given) gwt.push(`<em>Given</em> ${escapeHtml(ac.given)}`);
+  if (ac.when) gwt.push(`<em>When</em> ${escapeHtml(ac.when)}`);
+  if (ac.then) gwt.push(`<em>Then</em> ${escapeHtml(ac.then)}`);
+  if (gwt.length > 0) parts.push(`<div class="ac-gwt">${gwt.map((p) => `<p>${p}</p>`).join('')}</div>`);
+  parts.push(`<p class="ac-meta"><strong>Testable:</strong> ${escapeHtml(String(ac.testable ?? false))} - ${coveredBy}</p>`);
+  return `<li id="${acAnchor}" class="ac-item">${parts.join('\n')}</li>`;
+}