severally-mcp 2.3.1 → 2.4.2

package/src/jsonc.mjs

@@ -11,8 +11,12 @@
 // byte offsets -- and therefore JSON.parse's error positions -- still point at
 // the right place in the original text.
 
-/** Remove // and /* *\/ comments and trailing commas, preserving offsets. */
+/**
+ * Remove // and /* *\/ comments and trailing commas, preserving offsets.
+ * @param {string} text
+ */
 export function stripJsonc(text) {
+  /** @type {string[]} */
   const out = [];
   let inString = false;
   let i = 0;
@@ -28,7 +32,7 @@ export function stripJsonc(text) {
   };
 
   while (i < text.length) {
-    const c = text[i];
+    const c = text.charAt(i);
     const next = text[i + 1];
 
     if (inString) {
@@ -78,7 +82,11 @@ export function stripJsonc(text) {
   return out.join('');
 }
 
-/** JSON.parse, tolerating comments and trailing commas. */
+/**
+ * JSON.parse, tolerating comments and trailing commas.
+ * @param {string} text
+ * @returns {unknown}
+ */
 export function parseJsonc(text) {
   return JSON.parse(stripJsonc(text));
 }

package/src/parse-result.mjs

@@ -8,6 +8,10 @@ import { RESULT_KEYS } from './result-schema.mjs';
 import { redact } from './redact.mjs';
 
 export class OutputError extends Error {
+  /**
+   * @param {string} message
+   * @param {string} [detail]
+   */
   constructor(message, detail) {
     super(message);
     this.name = 'OutputError';
@@ -17,6 +21,38 @@ export class OutputError extends Error {
 
 const O = POLICY.output;
 
+/** @typedef {'high' | 'medium' | 'low'} Level */
+/** @typedef {'sufficient' | 'thin' | 'insufficient'} EvidenceBasis */
+/** @typedef {(typeof STANCES)[number]} Stance */
+/** @typedef {{ id: string, point: string, grounds: string | null, impact: string | null, severity: Level | null, confidence: Level | null }} Finding */
+/** @typedef {{ option: string, tradeoffs: string | null, when_preferred: string | null }} Alternative */
+/** @typedef {{ id: string, item: string, why_it_matters: string | null, how_to_obtain: string | null }} Unknown */
+/** @typedef {{ condition: string, changes_to: string | null }} DecisionChanger */
+/** @typedef {{ id: string, check: string, method: string | null, expected_signal: string | null }} NextCheck */
+/** @typedef {{ topic: string, your_position: string | null, why_unresolved: string | null }} RemainingDisagreement */
+/** @typedef {{ title: string | null, url: string | null, relevance: string | null }} Reference */
+
+/**
+ * The validated consult result, in the shape of CONSULT_RESULT_SCHEMA.
+ * @typedef {object} ConsultResult
+ * @property {string} summary
+ * @property {Level | null} confidence
+ * @property {EvidenceBasis | null} evidence_basis
+ * @property {Stance | null} stance
+ * @property {Finding[]} findings
+ * @property {Alternative[]} alternatives
+ * @property {Unknown[]} unknowns
+ * @property {DecisionChanger[]} decision_changers
+ * @property {NextCheck[]} next_checks
+ * @property {RemainingDisagreement[]} remaining_disagreements
+ * @property {Reference[]} references
+ */
+
+/**
+ * @param {unknown} v
+ * @param {number} max
+ * @returns {string | null}
+ */
 function clampText(v, max) {
   if (typeof v !== 'string') return null;
   const t = v.trim();
@@ -24,34 +60,61 @@ function clampText(v, max) {
   return t.length > max ? `${t.slice(0, max)}\n…[truncated by severally]` : t;
 }
 
+/**
+ * Narrows a string to one of the listed values.
+ * @template {string} T
+ * @param {readonly T[]} list
+ * @param {string} t
+ * @returns {t is T}
+ */
+const oneOf = (list, t) => list.some((x) => x === t);
+
+/** @type {Level[]} */
 const LEVELS = ['high', 'medium', 'low'];
+/** @type {EvidenceBasis[]} */
 const BASIS = ['sufficient', 'thin', 'insufficient'];
 
+/**
+ * @param {unknown} v
+ * @param {Level | null} [fallback]
+ * @returns {Level | null}
+ */
 function level(v, fallback = null) {
   const t = typeof v === 'string' ? v.trim().toLowerCase() : '';
-  return LEVELS.includes(t) ? t : fallback;
+  return oneOf(LEVELS, t) ? t : fallback;
 }
 
+/**
+ * @param {unknown} v
+ * @returns {EvidenceBasis | null}
+ */
 function basis(v) {
   const t = typeof v === 'string' ? v.trim().toLowerCase() : '';
-  return BASIS.includes(t) ? t : null;
+  return oneOf(BASIS, t) ? t : null;
 }
 
+/**
+ * @param {unknown} v
+ * @returns {Stance | null}
+ */
 function stance(v) {
   const t = typeof v === 'string' ? v.trim().toLowerCase() : '';
-  return STANCES.includes(t) ? t : null;
+  return oneOf(STANCES, t) ? t : null;
 }
 
-/** Extract a JSON object from raw model text (fenced block, or first balanced object). */
+/**
+ * Extract a JSON object from raw model text (fenced block, or first balanced object).
+ * @param {unknown} text
+ * @returns {Record<string, unknown> | null}
+ */
 export function extractJson(text) {
   if (typeof text !== 'string') return null;
   const trimmed = text.trim();
   if (!trimmed) return null;
+  /** @type {string[]} */
   const candidates = [];
   if (trimmed.startsWith('{')) candidates.push(trimmed);
-  const fence = /```(?:json)?\s*([\s\S]*?)```/gi;
-  let m;
-  while ((m = fence.exec(trimmed)) !== null) candidates.push(m[1].trim());
+  for (const [, body = ''] of trimmed.matchAll(/```(?:json)?\s*([\s\S]*?)```/gi)) candidates.push(body.trim());
   // Longest balanced {...} run as a last resort.
   const start = trimmed.indexOf('{');
   if (start !== -1) {
@@ -60,14 +123,26 @@ export function extractJson(text) {
     let esc = false;
     for (let i = start; i < trimmed.length; i++) {
       const ch = trimmed[i];
-      if (esc) { esc = false; continue; }
-      if (ch === '\\') { esc = true; continue; }
-      if (ch === '"') { inStr = !inStr; continue; }
+      if (esc) {
+        esc = false;
+        continue;
+      }
+      if (ch === '\\') {
+        esc = true;
+        continue;
+      }
+      if (ch === '"') {
+        inStr = !inStr;
+        continue;
+      }
       if (inStr) continue;
       if (ch === '{') depth++;
       else if (ch === '}') {
         depth--;
-        if (depth === 0) { candidates.push(trimmed.slice(start, i + 1)); break; }
+        if (depth === 0) {
+          candidates.push(trimmed.slice(start, i + 1));
+          break;
+        }
       }
     }
   }
@@ -75,7 +150,9 @@ export function extractJson(text) {
     try {
       const parsed = JSON.parse(c);
       if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) return parsed;
-    } catch { /* try the next candidate */ }
+    } catch {
+      /* try the next candidate */
+    }
   }
   return null;
 }
@@ -84,24 +161,34 @@ export function extractJson(text) {
 // verdict against one point later. The id is ours, assigned at parse time and
 // never read from the answer: a consultant that numbered its own findings
 // cannot make one of them impersonate another.
+/**
+ * @template T
+ * @param {unknown} raw
+ * @param {Record<string, 'text' | 'level'>} fields
+ * @param {{ requiredField: string, idPrefix?: string | null }} options
+ * @returns {T[]}
+ */
 function mapList(raw, fields, { requiredField, idPrefix = null }) {
   if (!Array.isArray(raw)) return [];
+  /** @type {T[]} */
   const out = [];
   for (const entry of raw.slice(0, O.listMax)) {
     if (!entry || typeof entry !== 'object') continue;
+    /** @type {Record<string, unknown>} */
     const item = idPrefix ? { id: `${idPrefix}${out.length + 1}` } : {};
     for (const [key, kind] of Object.entries(fields)) {
       item[key] = kind === 'level' ? level(entry[key]) : clampText(entry[key], O.itemTextMax);
     }
     if (!item[requiredField]) continue;
-    out.push(item);
+    // Every key of `fields` is a key of T, and the required one is set.
+    out.push(/** @type {T} */ (item));
   }
   return out;
 }
 
 /**
- * @param {object|string} raw  parsed JSON object, or raw text to mine one out of
- * @returns {{result: object, quality: {structured_output: boolean, missing_sections: string[]}}}
+ * @param {Record<string, unknown> | string} raw  parsed JSON object, or raw text to mine one out of
+ * @returns {{result: ConsultResult, quality: {missing_sections: string[], findings_without_grounds: number, unsourced: boolean, list_truncated?: Record<string, number>}}}
  */
 export function normalizeResult(raw) {
   const objIn = typeof raw === 'string' ? extractJson(raw) : raw;
@@ -115,45 +202,90 @@ export function normalizeResult(raw) {
     throw new OutputError('consultant response has no usable "summary" field', JSON.stringify(src).slice(0, 2000));
   }
 
+  /** @type {ConsultResult} */
   const result = {
     summary,
     confidence: level(src.confidence),
     evidence_basis: basis(src.evidence_basis),
     stance: stance(src.stance),
-    findings: mapList(src.findings, {
-      point: 'text', grounds: 'text', impact: 'text', severity: 'level', confidence: 'level',
-    }, { requiredField: 'point', idPrefix: 'f' }),
-    alternatives: mapList(src.alternatives, {
-      option: 'text', tradeoffs: 'text', when_preferred: 'text',
-    }, { requiredField: 'option' }),
-    unknowns: mapList(src.unknowns, {
-      item: 'text', why_it_matters: 'text', how_to_obtain: 'text',
-    }, { requiredField: 'item', idPrefix: 'u' }),
-    decision_changers: mapList(src.decision_changers, {
-      condition: 'text', changes_to: 'text',
-    }, { requiredField: 'condition' }),
-    next_checks: mapList(src.next_checks, {
-      check: 'text', method: 'text', expected_signal: 'text',
-    }, { requiredField: 'check', idPrefix: 'c' }),
-    remaining_disagreements: mapList(src.remaining_disagreements, {
-      topic: 'text', your_position: 'text', why_unresolved: 'text',
-    }, { requiredField: 'topic' }),
+    findings: mapList(
+      src.findings,
+      {
+        point: 'text',
+        grounds: 'text',
+        impact: 'text',
+        severity: 'level',
+        confidence: 'level',
+      },
+      { requiredField: 'point', idPrefix: 'f' },
+    ),
+    alternatives: mapList(
+      src.alternatives,
+      {
+        option: 'text',
+        tradeoffs: 'text',
+        when_preferred: 'text',
+      },
+      { requiredField: 'option' },
+    ),
+    unknowns: mapList(
+      src.unknowns,
+      {
+        item: 'text',
+        why_it_matters: 'text',
+        how_to_obtain: 'text',
+      },
+      { requiredField: 'item', idPrefix: 'u' },
+    ),
+    decision_changers: mapList(
+      src.decision_changers,
+      {
+        condition: 'text',
+        changes_to: 'text',
+      },
+      { requiredField: 'condition' },
+    ),
+    next_checks: mapList(
+      src.next_checks,
+      {
+        check: 'text',
+        method: 'text',
+        expected_signal: 'text',
+      },
+      { requiredField: 'check', idPrefix: 'c' },
+    ),
+    remaining_disagreements: mapList(
+      src.remaining_disagreements,
+      {
+        topic: 'text',
+        your_position: 'text',
+        why_unresolved: 'text',
+      },
+      { requiredField: 'topic' },
+    ),
     references: (Array.isArray(src.references) ? src.references : [])
       .slice(0, O.referencesMax)
-      .map((r) => (r && typeof r === 'object'
-        ? { title: clampText(r.title, 300), url: clampText(r.url, 1000), relevance: clampText(r.relevance, 600) }
-        : { title: clampText(r, 300), url: null, relevance: null }))
+      .map((r) =>
+        r && typeof r === 'object'
+          ? { title: clampText(r.title, 300), url: clampText(r.url, 1000), relevance: clampText(r.relevance, 600) }
+          : { title: clampText(r, 300), url: null, relevance: null },
+      )
       .filter((r) => r.title || r.url),
   };
 
   // The lists are cut to O.listMax before anything else looks at them; say how
   // long the ones that were cut had been, so the cut is not silent.
-  const listTruncated = Object.fromEntries(['findings', 'alternatives', 'unknowns', 'decision_changers', 'next_checks', 'remaining_disagreements']
-    .filter((k) => Array.isArray(src[k]) && src[k].length > O.listMax)
-    .map((k) => [k, src[k].length]));
+  const listTruncated = Object.fromEntries(
+    ['findings', 'alternatives', 'unknowns', 'decision_changers', 'next_checks', 'remaining_disagreements'].flatMap((k) => {
+      const v = src[k];
+      return Array.isArray(v) && v.length > O.listMax ? [[k, v.length]] : [];
+    }),
+  );
 
+  /** @type {Record<string, unknown>} */
+  const fields = result;
   const missing = RESULT_KEYS.filter((k) => {
-    const v = result[k];
+    const v = fields[k];
     return v === null || v === undefined || (Array.isArray(v) && v.length === 0);
   });
 

package/src/platform.mjs

@@ -1,3 +1,4 @@
+/// <reference path="./cross-spawn-escape.d.ts" />
 import fs from 'node:fs';
 import path from 'node:path';
 import which from 'which';
@@ -5,12 +6,24 @@ import spawn from 'cross-spawn';
 import escape from 'cross-spawn/lib/util/escape.js';
 import { spawn as nativeSpawn, spawnSync as nativeSpawnSync } from 'node:child_process';
 
+/**
+ * @param {string} source
+ * @param {string} destination
+ */
 export function copyTree(source, destination) {
   // Node 22.23.2's native cpSync fast path corrupts non-ASCII Windows paths.
   // A filter selects its JS traversal, preserving Japanese directory names.
   fs.cpSync(source, destination, { recursive: true, filter: () => true });
 }
 
+/** @typedef {import('node:child_process').SpawnOptions & { cwd?: string | undefined, env?: NodeJS.ProcessEnv | undefined }} SpawnOpts */
+
+/**
+ * @template {SpawnOpts} O
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {O} options
+ */
 function batchInvocation(command, args, options) {
   if (process.platform !== 'win32') return null;
   const resolved = findCommand(command, options);
@@ -26,23 +39,46 @@ function batchInvocation(command, args, options) {
   };
 }
 
+/**
+ * @overload
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {SpawnOpts & { stdio: ['pipe', 'pipe', 'pipe'] }} options
+ * @returns {import('node:child_process').ChildProcessWithoutNullStreams}
+ */
+/**
+ * @overload
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {SpawnOpts} [options]
+ * @returns {import('node:child_process').ChildProcess}
+ */
+/**
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {SpawnOpts} [options]
+ */
 export function spawnCommand(command, args, options = {}) {
   const batch = batchInvocation(command, args, options);
   return batch ? nativeSpawn(batch.command, batch.args, batch.options) : spawn(command, args, options);
 }
 
 // Explicit script paths are supported by cross-spawn's shebang handling too.
+/**
+ * @param {string} command
+ * @param {{ cwd?: string | undefined, env?: NodeJS.ProcessEnv | undefined }} [options]
+ * @returns {string | null}
+ */
 export function findCommand(command, { cwd = process.cwd(), env = process.env } = {}) {
   if (typeof command !== 'string' || !command) return null;
   cwd = path.resolve(cwd);
   const windows = process.platform === 'win32';
-  const value = (name) => env[windows
-    ? Object.keys(env).find((key) => key.toUpperCase() === name) : name];
+  const value = (/** @type {string} */ name) => {
+    const key = windows ? Object.keys(env).find((k) => k.toUpperCase() === name) : name;
+    return key === undefined ? undefined : env[key];
+  };
   const explicit = command.includes('/') || (windows && command.includes('\\'));
-  const dirs = explicit ? [cwd] : [
-    ...(windows ? [cwd] : []),
-    ...(value('PATH') ?? '').split(path.delimiter).filter(Boolean),
-  ];
+  const dirs = explicit ? [cwd] : [...(windows ? [cwd] : []), ...(value('PATH') ?? '').split(path.delimiter).filter(Boolean)];
   for (const dir of dirs) {
     // Absolute candidates prevent which's own cwd lookup from resolving a
     // wrapper in the server directory instead of the child's directory.
@@ -56,13 +92,25 @@ export function findCommand(command, { cwd = process.cwd(), env = process.env }
       if (!fs.statSync(candidate).isFile()) return null;
       fs.accessSync(candidate, fs.constants.X_OK);
       return candidate;
-    } catch { /* not installed */ }
+    } catch {
+      /* not installed */
+    }
   }
   return null;
 }
 
+/** @typedef {Omit<import('node:child_process').SpawnSyncOptionsWithStringEncoding, 'cwd' | 'encoding'> & { cwd?: string, encoding?: BufferEncoding }} ExecOptions */
+
+/**
+ * @param {string} command
+ * @param {readonly string[]} args
+ * @param {ExecOptions} [options]
+ * @returns {string}
+ */
 export function execCommandSync(command, args, options = {}) {
-  const opts = { windowsHide: true, encoding: 'utf8', ...options };
+  /** @type {BufferEncoding} */
+  const encoding = 'utf8';
+  const opts = { windowsHide: true, encoding, ...options };
   const batch = batchInvocation(command, args, opts);
   const result = batch ? nativeSpawnSync(batch.command, batch.args, batch.options) : spawn.sync(command, args, opts);
   if (result.error) throw result.error;