severally-mcp 2.3.1 → 2.4.2

package/src/export.mjs

@@ -13,7 +13,15 @@ import path from 'node:path';
 import { POLICY } from './policy.mjs';
 import { humanSize } from './expose-paths.mjs';
 
+/** @typedef {import('./store.mjs').Round} Round A round parsed from the history files. */
+/** @typedef {import('./store.mjs').BriefRecord} BriefRecord */
+/** @typedef {import('./store.mjs').JobRecord} JobRecord */
+
 export class ExportError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} code
+   */
   constructor(message, code) {
     super(message);
     this.name = 'ExportError';
@@ -23,14 +31,28 @@ export class ExportError extends Error {
 
 const historyDir = () => path.join(POLICY.home, 'history');
 
+/** @param {string} p */
 function readJson(p) {
-  try { return JSON.parse(fs.readFileSync(p, 'utf8')); } catch { return null; }
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null;
+  }
 }
 
+/**
+ * @param {string} chainId
+ * @returns {Round[]}
+ */
 function roundsOf(chainId) {
   const dir = path.join(historyDir(), chainId);
+  /** @type {string[]} */
   let names = [];
-  try { names = fs.readdirSync(dir); } catch { return []; }
+  try {
+    names = fs.readdirSync(dir);
+  } catch {
+    return [];
+  }
   return names
     .filter((n) => /^round-\d+\.json$/.test(n))
     .sort()
@@ -41,6 +63,10 @@ function roundsOf(chainId) {
 // A fan-out is one question sent to several consultants, and each consultant
 // answers on its own chain. Nothing in the group file records which chain that
 // was, so the index -- one line per consultation -- is what maps them back.
+/**
+ * @param {string} groupId
+ * @returns {string[]}
+ */
 function chainsOfGroup(groupId) {
   const group = readJson(path.join(historyDir(), 'groups', `${groupId}.json`));
   if (!group) throw new ExportError(`no fan-out with group_id "${groupId}" in ~/.severally/history`, 'unknown_group');
@@ -51,7 +77,10 @@ function chainsOfGroup(groupId) {
       const row = JSON.parse(line);
       byJob.set(row.job_id, row.chain_id);
     }
-  } catch { /* an unreadable index leaves the group unresolvable, handled below */ }
+  } catch {
+    /* an unreadable index leaves the group unresolvable, handled below */
+  }
+  /** @type {string[]} */
   const chains = [];
   for (const jobId of group.job_ids ?? []) {
     const chainId = byJob.get(jobId);
@@ -63,16 +92,30 @@ function chainsOfGroup(groupId) {
   return chains;
 }
 
+/**
+ * @param {string[] | null | undefined} items
+ * @param {(item: string) => string} render
+ */
 const bullets = (items, render) => (items ?? []).map(render);
 
+/**
+ * @param {string} text
+ * @param {string | null | undefined} language
+ */
 function fence(text, language) {
   const marker = String(text).includes('```') ? '~~~' : '```';
   return [`${marker}${language ?? ''}`, text, marker];
 }
 
+/** @param {BriefRecord | null | undefined} brief */
 function briefSection(brief) {
   if (!brief) return ['*(the brief was not recorded for this round)*', ''];
+  /** @type {string[]} */
   const out = [];
+  /**
+   * @param {string} title
+   * @param {string | string[] | null | undefined} body
+   */
   const block = (title, body) => {
     if (!body || (Array.isArray(body) && body.length === 0)) return;
     out.push(`**${title}**`, '');
@@ -80,11 +123,23 @@ function briefSection(brief) {
     out.push('');
   };
   block('Objective', brief.objective);
-  block('Success criteria', bullets(brief.success_criteria, (c) => `- ${c}`));
-  block('Constraints', bullets(brief.constraints, (c) => `- ${c}`));
-  block('Facts as given', bullets(brief.facts, (f) => `- ${f}`));
+  block(
+    'Success criteria',
+    bullets(brief.success_criteria, (c) => `- ${c}`),
+  );
+  block(
+    'Constraints',
+    bullets(brief.constraints, (c) => `- ${c}`),
+  );
+  block(
+    'Facts as given',
+    bullets(brief.facts, (f) => `- ${f}`),
+  );
   block('Proposal', brief.proposal);
-  block('Opposing claims', bullets(brief.counterpoints, (c) => `- ${c}`));
+  block(
+    'Opposing claims',
+    bullets(brief.counterpoints, (c) => `- ${c}`),
+  );
   for (const a of brief.artifacts ?? []) {
     out.push(`**Material: ${a.name}** (${[a.kind, a.language, a.source].filter(Boolean).join(', ')})`, '');
     out.push(...fence(a.excerpt, a.language));
@@ -98,15 +153,22 @@ function briefSection(brief) {
   if (exposed?.entries?.length || exposed?.skipped?.length) {
     out.push('**Files exposed to the consultant**', '');
     for (const e of exposed.entries) {
-      const since = e.changed_since_parent === undefined ? '' : e.changed_since_parent ? ', changed since the earlier round' : ', unchanged since the earlier round';
+      const since =
+        e.changed_since_parent === undefined
+          ? ''
+          : e.changed_since_parent
+            ? ', changed since the earlier round'
+            : ', unchanged since the earlier round';
       out.push(`- ${e.exposed_as} (${e.kind}, ${e.files} file(s), ${humanSize(e.bytes)}${since}) -- from ${e.source}`);
     }
+    /** @param {string} reason */
     const count = (reason) => (exposed.skipped ?? []).filter((x) => x.reason === reason).length;
     if (count('symlink')) out.push(`- ${count('symlink')} symlink(s) inside those directories were skipped, not followed`);
     if (count('protected')) out.push(`- ${count('protected')} credential or history path(s) were left out on purpose`);
     if (count('gone')) out.push(`- ${count('gone')} path(s) from the earlier round no longer existed and were not copied again`);
-    if (count('masked')) out.push(`- ${count('masked')} path(s) from the earlier round were masked in its record and were not copied again`);
-    if (count('replaced')) out.push('- the earlier round\'s change was replaced by the diff given in this round');
+    if (count('masked'))
+      out.push(`- ${count('masked')} path(s) from the earlier round were masked in its record and were not copied again`);
+    if (count('replaced')) out.push("- the earlier round's change was replaced by the diff given in this round");
     out.push('');
   }
   return out;
@@ -115,6 +177,10 @@ function briefSection(brief) {
 // The lead's own line, printed under the point it belongs to. An id with no
 // entry says so out loud: "nobody looked at this" is the thing a record of a
 // decision most easily loses.
+/**
+ * @param {JobRecord | null | undefined} record
+ * @param {string} id
+ */
 function verdictLine(record, id) {
   const entry = (record?.entries ?? []).find((e) => e.id === id);
   if (!entry) return '  - checked: no verdict recorded';
@@ -122,6 +188,7 @@ function verdictLine(record, id) {
   return `  - checked: ${entry.verdict}${tail ? ` -- ${tail}` : ''}`;
 }
 
+/** @param {Round} round */
 function answerSection(round) {
   const r = round.result;
   if (!r) {
@@ -132,6 +199,7 @@ function answerSection(round) {
       '',
     ];
   }
+  /** @type {string[]} */
   const out = [];
   const record = round.record;
   out.push('**Summary**', '', r.summary, '');
@@ -199,6 +267,10 @@ function answerSection(round) {
 // A fan-out sends the byte-identical brief to every consultant, so printing it
 // once per consultant buries the answers in repetition. Compared, not judged:
 // identical text is named as identical, anything else is printed in full.
+/**
+ * @param {Round} round
+ * @param {BriefRecord | null} previousBrief
+ */
 function roundSection(round, previousBrief) {
   const secs = round.duration_ms == null ? null : (round.duration_ms / 1000).toFixed(1);
   const head = [
@@ -209,7 +281,9 @@ function roundSection(round, previousBrief) {
   ];
   if (round.result) {
     head.push(`- stance as declared: ${round.result.stance ?? 'not declared'}`);
-    head.push(`- the consultant's own confidence: ${round.result.confidence ?? 'not declared'}, evidence basis: ${round.result.evidence_basis ?? 'not declared'}`);
+    head.push(
+      `- the consultant's own confidence: ${round.result.confidence ?? 'not declared'}, evidence basis: ${round.result.evidence_basis ?? 'not declared'}`,
+    );
   }
   head.push('');
   head.push('### Question', '', round.question, '');
@@ -239,21 +313,20 @@ function roundSection(round, previousBrief) {
 }
 
 /**
- * @param {{chain_id?: string, group_id?: string}} target
+ * @param {{chain_id?: string | undefined, group_id?: string | undefined}} target
  * @returns {{markdown: string, rounds: number, chain_ids: string[]}}
  */
 export function exportChain({ chain_id: chainId, group_id: groupId } = {}) {
   if (Boolean(chainId) === Boolean(groupId)) {
     throw new ExportError('pass exactly one of chain_id or group_id', 'export_target_required');
   }
-  const chainIds = groupId ? chainsOfGroup(groupId) : [chainId];
+  const chainIds = groupId ? chainsOfGroup(groupId) : chainId ? [chainId] : [];
   const perChain = chainIds.map((id) => ({ chain_id: id, rounds: roundsOf(id) }));
-  const total = perChain.reduce((n, c) => n + c.rounds.length, 0);
-  if (total === 0) {
+  const first = perChain.find((c) => c.rounds.length)?.rounds[0];
+  if (!first) {
     throw new ExportError(`no consultation recorded under "${chainId ?? groupId}" in ~/.severally/history`, 'unknown_chain');
   }
-
-  const first = perChain.find((c) => c.rounds.length)?.rounds[0];
+  const total = perChain.reduce((n, c) => n + c.rounds.length, 0);
   const lines = [
     `# Consultation record: ${first.question}`,
     '',
@@ -266,6 +339,7 @@ export function exportChain({ chain_id: chainId, group_id: groupId } = {}) {
     'ways, both are printed and the difference is left standing.',
     '',
   ];
+  /** @type {BriefRecord | null} */
   let previousBrief = null;
   for (const chain of perChain) {
     for (const round of chain.rounds) {
@@ -273,5 +347,12 @@ export function exportChain({ chain_id: chainId, group_id: groupId } = {}) {
       if (round.brief) previousBrief = round.brief;
     }
   }
-  return { markdown: `${lines.join('\n').replace(/\n{3,}/g, '\n\n').trimEnd()}\n`, rounds: total, chain_ids: chainIds };
+  return {
+    markdown: `${lines
+      .join('\n')
+      .replace(/\n{3,}/g, '\n\n')
+      .trimEnd()}\n`,
+    rounds: total,
+    chain_ids: chainIds,
+  };
 }