@stravica-ai/digital-operator-pa 0.1.0

package/dist/engineering-pa-cli/src/knowledge/formatters.mjs

@@ -0,0 +1,331 @@
+// formatters.mjs — output-format renderers for `pa knowledge`.
+//
+// Three formats are supported per the brief:
+//
+//   - `table`   : human-readable ASCII with sane column widths.
+//   - `json`    : machine-readable, stable-shape-by-convention. Consumed
+//                 by dispatch-briefer (A2, next wave) and other agents.
+//   - `mermaid` : graph syntax for any mermaid renderer. Useful for
+//                 visual debugging of "what's connected to what".
+//
+// Each verb has its own renderer per format. The JSON renderers just
+// pass through the verb result — the CLI-layer wraps in `{verb, ...}`
+// for stability.
+
+// --- generic table primitives ---------------------------------------------
+
+const TABLE_MAX_WIDTH = 120;
+
+function padRight(s, width) {
+  return String(s ?? '').padEnd(width, ' ');
+}
+
+function truncate(s, max) {
+  s = String(s ?? '');
+  if (s.length <= max) return s;
+  return s.slice(0, Math.max(0, max - 1)) + '…';
+}
+
+function renderTable(headers, rows, { maxWidth = TABLE_MAX_WIDTH } = {}) {
+  if (rows.length === 0) return '(no rows)\n';
+  const cols = headers.map((h) => h.key);
+  const widths = {};
+  for (const h of headers) widths[h.key] = Math.max(h.label.length, ...rows.map((r) => String(r[h.key] ?? '').length));
+  // Cap column widths so a very long id doesn't blow out the table.
+  const capped = capWidths(headers, widths, maxWidth);
+  const lines = [];
+  lines.push(headers.map((h) => padRight(h.label, capped[h.key])).join('  '));
+  lines.push(headers.map((h) => '-'.repeat(capped[h.key])).join('  '));
+  for (const row of rows) {
+    lines.push(headers.map((h) => padRight(truncate(row[h.key], capped[h.key]), capped[h.key])).join('  '));
+  }
+  return lines.join('\n') + '\n';
+}
+
+function capWidths(headers, widths, maxWidth) {
+  const separators = (headers.length - 1) * 2;
+  const total = Object.values(widths).reduce((a, b) => a + b, 0) + separators;
+  if (total <= maxWidth) return { ...widths };
+  // Trim the widest column iteratively until we fit.
+  const capped = { ...widths };
+  let budget = total;
+  while (budget > maxWidth) {
+    const [widestKey, widestVal] = Object.entries(capped).sort((a, b) => b[1] - a[1])[0];
+    if (widestVal <= 8) break;
+    capped[widestKey] = widestVal - 1;
+    budget -= 1;
+  }
+  return capped;
+}
+
+// --- verb: related --------------------------------------------------------
+
+export function formatRelated(result, format) {
+  if (format === 'json') return JSON.stringify({ verb: 'related', ...result }, null, 2) + '\n';
+  if (format === 'mermaid') return renderRelatedMermaid(result);
+  return renderRelatedTable(result);
+}
+
+function renderRelatedTable({ anchor, neighbours }) {
+  if (neighbours.length === 0) return `${anchor}\n(no neighbours)\n`;
+  const rows = neighbours.map((n) => ({
+    direction: n.direction === 'out' ? '→' : '←',
+    id: n.id,
+    title: n.title ?? '',
+    domain: n.domain ?? '',
+    type: n.type ?? '',
+  }));
+  const header = `${anchor} (${neighbours.length} neighbour${neighbours.length === 1 ? '' : 's'})\n`;
+  return header + renderTable(
+    [
+      { key: 'direction', label: 'dir' },
+      { key: 'id', label: 'id' },
+      { key: 'title', label: 'title' },
+      { key: 'domain', label: 'domain' },
+      { key: 'type', label: 'type' },
+    ],
+    rows,
+  );
+}
+
+function renderRelatedMermaid({ anchor, neighbours }) {
+  const lines = ['graph LR'];
+  const seen = new Set();
+  const idFor = (s) => 'n' + hashSlug(s);
+  const declare = (id, label) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    lines.push(`  ${idFor(id)}["${escapeMermaid(label ?? id)}"]`);
+  };
+  declare(anchor, anchor);
+  for (const n of neighbours) {
+    declare(n.id, n.title ?? n.id);
+    const label = n.type ? `|${n.type}|` : '';
+    if (n.direction === 'out') lines.push(`  ${idFor(anchor)} -->${label} ${idFor(n.id)}`);
+    else lines.push(`  ${idFor(n.id)} -->${label} ${idFor(anchor)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+// --- verb: search ---------------------------------------------------------
+
+// The `envelope` opt carries the searchCascade() result envelope when the
+// caller took the cascade path (default). Byte-identical rule: a tier-1
+// hit (`mode:'title'`, non-empty results) MUST render exactly what the
+// pre-cascade world rendered — no header line, JSON without `mode` or
+// `hint`. Cascade tiers (body / partial / miss) get a header label and
+// the JSON gains `mode` plus, for miss, a `hint.nearestDomains`.
+//
+// `--strict` and the eval runner call this without an envelope; those
+// callers see the pre-cascade shape unconditionally.
+export function formatSearch(results, format, { term, envelope } = {}) {
+  const isCascade = envelope != null;
+  const showBanner = isCascade && envelope.mode !== 'title';
+  if (format === 'json') {
+    const payload = { verb: 'search', term, results };
+    if (showBanner) {
+      payload.mode = envelope.mode;
+      if (envelope.tokensTotal != null) payload.tokensTotal = envelope.tokensTotal;
+      if (envelope.hint) payload.hint = envelope.hint;
+    }
+    return JSON.stringify(payload, null, 2) + '\n';
+  }
+  if (format === 'mermaid') return renderSearchMermaid(results);
+  return renderSearchTable(results, showBanner ? envelope : null);
+}
+
+function renderSearchTable(results, envelope) {
+  if (envelope != null && envelope.mode === 'miss') {
+    return renderGuidedMiss(envelope);
+  }
+  if (results.length === 0) return '(no matches)\n';
+  const rows = results.map((r) => ({
+    score: r.score,
+    edges: r.edgeCount,
+    id: r.id,
+    title: r.title ?? '',
+    domain: r.domain ?? '',
+    hits: r.tokensMatched != null ? `${r.tokensMatched}/${r.tokensTotal}` : '',
+  }));
+  const headers = [
+    { key: 'score', label: 'score' },
+    { key: 'edges', label: 'edges' },
+    { key: 'id', label: 'id' },
+    { key: 'title', label: 'title' },
+    { key: 'domain', label: 'domain' },
+  ];
+  let prefix = '';
+  if (envelope != null) {
+    if (envelope.mode === 'body') {
+      prefix = '(matched in body)\n';
+    } else if (envelope.mode === 'partial') {
+      const total = envelope.tokensTotal;
+      // Column added only for the partial tier so tier-1 tables stay
+      // shape-compatible with the pre-cascade world.
+      headers.push({ key: 'hits', label: 'hits' });
+      const nMax = results.reduce((m, r) => Math.max(m, r.tokensMatched ?? 0), 0);
+      prefix = `(partial match — ${nMax} of ${total} terms)\n`;
+    }
+  }
+  return prefix + renderTable(headers, rows);
+}
+
+function renderGuidedMiss(envelope) {
+  const nd = envelope.hint?.nearestDomains ?? [];
+  const parts = ['(no matches — no doc contains every search term, even in the body.)', ''];
+  if (nd.length > 0) {
+    parts.push('Nearest domains:');
+    for (const d of nd) parts.push(`  - ${d}`);
+    parts.push('');
+    parts.push(`Browse one with:  pa knowledge domain <name>`);
+    parts.push(`Example:          pa knowledge domain ${nd[0]}`);
+  } else {
+    parts.push('No populated domains in this graph.');
+  }
+  return parts.join('\n') + '\n';
+}
+
+function renderSearchMermaid(results) {
+  if (results.length === 0) return '%% no matches\n';
+  const lines = ['graph LR'];
+  const idFor = (s) => 'n' + hashSlug(s);
+  for (const r of results) {
+    lines.push(`  ${idFor(r.id)}["${escapeMermaid(r.title ?? r.id)}"]`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+// --- verb: domain ---------------------------------------------------------
+
+export function formatDomain(result, format) {
+  if (format === 'json') return JSON.stringify({ verb: 'domain', ...result }, null, 2) + '\n';
+  if (format === 'mermaid') return renderDomainMermaid(result);
+  return renderDomainTable(result);
+}
+
+function renderDomainTable({ domain, nodes, edges }) {
+  const header = `domain: ${domain} (${nodes.length} node${nodes.length === 1 ? '' : 's'}, ${edges.length} internal edge${edges.length === 1 ? '' : 's'})\n`;
+  const rows = nodes.map((n) => ({ id: n.id, title: n.title ?? '' }));
+  return header + renderTable(
+    [
+      { key: 'id', label: 'id' },
+      { key: 'title', label: 'title' },
+    ],
+    rows,
+  );
+}
+
+function renderDomainMermaid({ domain, nodes, edges }) {
+  const lines = ['graph LR'];
+  const idFor = (s) => 'n' + hashSlug(s);
+  for (const n of nodes) lines.push(`  ${idFor(n.id)}["${escapeMermaid(n.title ?? n.id)}"]`);
+  for (const e of edges) {
+    const label = e.type ? `|${e.type}|` : '';
+    lines.push(`  ${idFor(e.from)} -->${label} ${idFor(e.to)}`);
+  }
+  lines.push(`  %% domain: ${domain}`);
+  return lines.join('\n') + '\n';
+}
+
+// --- verb: orphans --------------------------------------------------------
+
+export function formatOrphans(results, format) {
+  if (format === 'json') return JSON.stringify({ verb: 'orphans', results }, null, 2) + '\n';
+  if (format === 'mermaid') return renderOrphansMermaid(results);
+  return renderOrphansTable(results);
+}
+
+function renderOrphansTable(results) {
+  if (results.length === 0) return '(no orphans)\n';
+  const rows = results.map((r) => ({
+    id: r.id,
+    title: r.title ?? '',
+    domain: r.domain ?? '',
+    outDegree: r.outDegree,
+  }));
+  return renderTable(
+    [
+      { key: 'id', label: 'id' },
+      { key: 'title', label: 'title' },
+      { key: 'domain', label: 'domain' },
+      { key: 'outDegree', label: 'outEdges' },
+    ],
+    rows,
+  );
+}
+
+function renderOrphansMermaid(results) {
+  if (results.length === 0) return '%% no orphans\n';
+  const lines = ['graph LR'];
+  const idFor = (s) => 'n' + hashSlug(s);
+  for (const r of results) lines.push(`  ${idFor(r.id)}["${escapeMermaid(r.title ?? r.id)}"]`);
+  return lines.join('\n') + '\n';
+}
+
+// --- verb: path -----------------------------------------------------------
+
+export function formatPath(result, format) {
+  if (format === 'json') return JSON.stringify({ verb: 'path', ...result }, null, 2) + '\n';
+  if (format === 'mermaid') return renderPathMermaid(result);
+  return renderPathTable(result);
+}
+
+function renderPathTable({ from, to, path }) {
+  if (path == null) return `no path from ${from} to ${to}\n`;
+  const header = `${from} → ${to} (${path.length - 1} hop${path.length - 1 === 1 ? '' : 's'})\n`;
+  const rows = path.map((step, i) => ({
+    step: i + 1,
+    id: step.id,
+    title: step.title ?? '',
+    edge: step.type ?? '(anchor)',
+  }));
+  return header + renderTable(
+    [
+      { key: 'step', label: 'step' },
+      { key: 'id', label: 'id' },
+      { key: 'title', label: 'title' },
+      { key: 'edge', label: 'via' },
+    ],
+    rows,
+  );
+}
+
+function renderPathMermaid({ from, to, path }) {
+  if (path == null) return `%% no path from ${from} to ${to}\n`;
+  const lines = ['graph LR'];
+  const idFor = (s) => 'n' + hashSlug(s);
+  for (const step of path) lines.push(`  ${idFor(step.id)}["${escapeMermaid(step.title ?? step.id)}"]`);
+  for (let i = 1; i < path.length; i++) {
+    const prev = path[i - 1];
+    const curr = path[i];
+    const label = curr.type ? `|${curr.type}|` : '';
+    lines.push(`  ${idFor(prev.id)} -->${label} ${idFor(curr.id)}`);
+  }
+  return lines.join('\n') + '\n';
+}
+
+// --- shared helpers -------------------------------------------------------
+
+// Mermaid ids must match `[A-Za-z_][A-Za-z0-9_]*`. Our slugs contain
+// slashes, dots, dashes. Hash the slug to a stable short id — no
+// collisions in practice at graph sizes we care about (<10K nodes).
+function hashSlug(slug) {
+  // djb2 truncated to 8 hex chars. Deterministic + node-stdlib only.
+  let hash = 5381;
+  for (let i = 0; i < slug.length; i++) {
+    hash = ((hash << 5) + hash) ^ slug.charCodeAt(i);
+    hash = hash >>> 0;
+  }
+  return hash.toString(16).padStart(8, '0');
+}
+
+function escapeMermaid(s) {
+  // Mermaid node labels wrapped in double quotes tolerate most characters
+  // except embedded double quotes. Backslash + double-quote is not portable
+  // across mermaid renderers, so we substitute with a single quote.
+  return String(s).replace(/"/g, "'");
+}
+
+// Test seams — exposed so unit tests can pin the primitives without
+// duplicating the format contract.
+export const _internals = { renderTable, hashSlug, escapeMermaid };