stack/packages/library/src/render.mjs

// renderItems(body): how a stored cited reply looks (design 7.4), shared by the Console chat (C2-10b)
// and the Discord relay (C2-18). Pure: no git, no clock. The caller passes what it knows about cites.
// The guard (C2-06) checks limits before a reply is stored. This only refuses to show a body that
// doesn't have the reply shape, and then it shows a fixed line, never the body's text.
export const KINDS = Object.freeze({ fact: 'Fact', finding: 'Finding', correction: 'Correction', question: 'Question', idea: 'Idea' });
export const NOTICES = Object.freeze({ 'no-cited-answer': 'No cited answer', 'no-answer': 'No answer', 'turn-failed': 'The turn failed' });
export const UNREADABLE = 'This reply could not be shown.';
const SHA = /^[0-9a-f]{40}$/;

const plain = value => value !== null && typeof value === 'object' && !Array.isArray(value);
const line = n => Number.isSafeInteger(n) && n > 0;
function cite(value, { scopeOf, changed }) {
  if (!plain(value) || typeof value.quote !== 'string') return null;
  if (Object.hasOwn(value, 'url')) {
    if (typeof value.url !== 'string' || Object.hasOwn(value, 'path')) return null;
    return { badge: 'web', url: value.url, ref: value.url, quote: value.quote, changed: false };
  }
  const { path, commit, lines } = value;
  if (typeof path !== 'string' || !SHA.test(commit ?? '') || !Array.isArray(lines) || lines.length !== 2
      || !line(lines[0]) || !line(lines[1]) || lines[1] < lines[0]) return null;
  const badge = scopeOf?.(path);
  const ref = `${path}:${lines[0] === lines[1] ? lines[0] : `${lines[0]}-${lines[1]}`} @${commit.slice(0, 7)}`;
  return { badge: badge === 'canon' || badge === 'playground' ? badge : null, path, commit, lines: [...lines], ref,
    quote: value.quote, changed: changed?.({ path, commit }) === true };
}
const quoted = text => JSON.stringify(text);

// body: the stored message body (a JSON string or the parsed object).
// options.scopeOf(path) -> 'canon' | 'playground' | undefined, for the scope badge.
// options.changed({path, commit}) -> true when the file's last commit is newer than the cited one.
// Returns { kind: 'items', items, text } | { kind: 'notice', notice, text } | { kind: 'unreadable', text }.
export function renderItems(body, options = {}) {
  const unreadable = { kind: 'unreadable', text: UNREADABLE };
  let value = body;
  if (typeof body === 'string') { try { value = JSON.parse(body); } catch { return unreadable; } }
  if (!plain(value) || !Array.isArray(value.items)) return unreadable;
  const keys = Object.keys(value);
  if (value.items.length === 0) {
    if (keys.length !== 2 || !Object.hasOwn(NOTICES, value.notice)) return unreadable;
    return { kind: 'notice', notice: value.notice, text: NOTICES[value.notice] };
  }
  if (keys.length !== 1) return unreadable;
  const items = [];
  for (const item of value.items) {
    if (!plain(item) || !Object.hasOwn(KINDS, item.kind) || typeof item.text !== 'string' || !Array.isArray(item.cites)) return unreadable;
    const correction = item.kind === 'correction';
    if (correction && (typeof item.from !== 'string' || typeof item.to !== 'string')) return unreadable;
    const cites = item.cites.map(c => cite(c, options));
    if (cites.some(c => c === null)) return unreadable;
    items.push({ kind: item.kind, label: KINDS[item.kind], text: item.text,
      ...(correction ? { from: item.from, to: item.to } : {}), cites });
  }
  const text = items.map((item, i) => [
    `${i + 1}. ${item.label}: ${item.text}`,
    ...(item.kind === 'correction' ? [`   From: ${quoted(item.from)}`, `   To: ${quoted(item.to)}`] : []),
    ...item.cites.map(c => `   ${c.badge ? `[${c.badge}] ` : ''}${c.ref} ${quoted(c.quote)}${c.changed ? ' (changed since)' : ''}`),
  ].join('\n')).join('\n');
  return { kind: 'items', items, text };
}