@remnic/core 1.1.12 → 1.1.14

package/src/recall-explain-renderer.ts

@@ -0,0 +1,356 @@
+/**
+ * Renderers for RecallTierExplain (issue #518).
+ *
+ * Pure functions that format a `LastRecallSnapshot` and its
+ * optional `tierExplain` field for human text and machine JSON
+ * consumption.  CLI / HTTP / MCP surfaces consume these — they do
+ * not format explain output themselves, so rendering is tested in
+ * one place.
+ */
+
+import type { LastRecallSnapshot } from "./recall-state.js";
+import type { RecallTierExplain } from "./types.js";
+import { isRetrievalTier } from "./retrieval-tiers.js";
+import type {
+  RecallXraySnapshot,
+  RecallFilterTrace,
+  RecallXrayResult,
+} from "./recall-xray.js";
+import { renderXrayMarkdown } from "./recall-xray-renderer.js";
+
+function sanitizeString(v: unknown): string | null {
+  return typeof v === "string" && v.length > 0 ? v : null;
+}
+
+function sanitizeFiniteNumber(v: unknown): number | null {
+  return typeof v === "number" && Number.isFinite(v) ? v : null;
+}
+
+/**
+ * `text` and `json` are the original formats (backwards-compatible
+ * since issue #518).  `markdown` was added in issue #570 PR 7 and
+ * delegates to the shared X-ray renderer so the three observability
+ * surfaces stay in lock-step (CLAUDE.md rule 22).
+ */
+export type RecallExplainFormat = "text" | "json" | "markdown";
+
+export interface RecallExplainJsonPayload {
+  hasExplain: boolean;
+  snapshotFound: boolean;
+  sessionKey: string | null;
+  recordedAt: string | null;
+  namespace: string | null;
+  memoryIds: string[];
+  source: string | null;
+  sourcesUsed: string[] | null;
+  latencyMs: number | null;
+  tierExplain: RecallTierExplain | null;
+}
+
+function normalizeTierExplain(value: unknown): RecallTierExplain | null {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return null;
+  const raw = value as Record<string, unknown>;
+  const filteredBy = Array.isArray(raw.filteredBy)
+    ? raw.filteredBy.filter((x): x is string => typeof x === "string")
+    : [];
+  const sourceAnchors = Array.isArray(raw.sourceAnchors)
+    ? raw.sourceAnchors
+        .filter(
+          (a): a is { path: string; lineRange?: unknown } =>
+            !!a && typeof a === "object" && typeof (a as { path?: unknown }).path === "string",
+        )
+        .map((a) => {
+          const lr = (a as { lineRange?: unknown }).lineRange;
+          const lineRange =
+            Array.isArray(lr) &&
+            lr.length === 2 &&
+            Number.isFinite(lr[0]) &&
+            Number.isFinite(lr[1])
+              ? ([lr[0] as number, lr[1] as number] as [number, number])
+              : undefined;
+          return lineRange
+            ? { path: (a as { path: string }).path, lineRange }
+            : { path: (a as { path: string }).path };
+        })
+    : undefined;
+  return {
+    tier: isRetrievalTier(raw.tier) ? raw.tier : "hybrid",
+    tierReason: typeof raw.tierReason === "string" ? raw.tierReason : "",
+    filteredBy,
+    candidatesConsidered: sanitizeFiniteNumber(raw.candidatesConsidered) ?? 0,
+    latencyMs: sanitizeFiniteNumber(raw.latencyMs) ?? 0,
+    ...(sourceAnchors !== undefined ? { sourceAnchors } : {}),
+  };
+}
+
+export function toRecallExplainJson(
+  snapshot: LastRecallSnapshot | null,
+): RecallExplainJsonPayload {
+  if (!snapshot) {
+    return {
+      hasExplain: false,
+      snapshotFound: false,
+      sessionKey: null,
+      recordedAt: null,
+      namespace: null,
+      memoryIds: [],
+      source: null,
+      sourcesUsed: null,
+      latencyMs: null,
+      tierExplain: null,
+    };
+  }
+  const normalizedExplain = normalizeTierExplain(snapshot.tierExplain);
+  return {
+    hasExplain: normalizedExplain !== null,
+    snapshotFound: true,
+    sessionKey: sanitizeString(snapshot.sessionKey),
+    recordedAt: sanitizeString(snapshot.recordedAt),
+    namespace: sanitizeString(snapshot.namespace),
+    memoryIds: Array.isArray(snapshot.memoryIds)
+      ? snapshot.memoryIds.filter((x): x is string => typeof x === "string")
+      : [],
+    source: sanitizeString(snapshot.source),
+    sourcesUsed: Array.isArray(snapshot.sourcesUsed)
+      ? snapshot.sourcesUsed.filter((x): x is string => typeof x === "string")
+      : null,
+    latencyMs: sanitizeFiniteNumber(snapshot.latencyMs),
+    tierExplain: normalizedExplain,
+  };
+}
+
+/**
+ * Render the shared "--- tier explain ---" text block used by both the
+ * recall-explain surface and the Recall X-ray surface.  Callers provide
+ * the normalized `RecallTierExplain` (or `null` for the
+ * not-populated/disabled case) so the block stays character-for-character
+ * identical across surfaces (CLAUDE.md rule 22).  The returned strings do
+ * NOT include leading blank lines or headers — callers own that framing.
+ */
+export function renderTierExplainTextLines(
+  tierExplain: RecallTierExplain | null,
+): string[] {
+  const lines: string[] = [];
+  if (!tierExplain) {
+    lines.push(
+      "(not populated — direct-answer tier disabled or did not fire)",
+    );
+    return lines;
+  }
+  lines.push(`tier: ${tierExplain.tier}`);
+  lines.push(`reason: ${tierExplain.tierReason}`);
+  lines.push(`candidates-considered: ${tierExplain.candidatesConsidered}`);
+  lines.push(`latency-ms: ${tierExplain.latencyMs}`);
+  if (tierExplain.filteredBy.length > 0) {
+    lines.push(`filtered-by: ${tierExplain.filteredBy.join(", ")}`);
+  } else {
+    lines.push("filtered-by: (none)");
+  }
+  if (tierExplain.sourceAnchors && tierExplain.sourceAnchors.length > 0) {
+    lines.push("source-anchors:");
+    for (const anchor of tierExplain.sourceAnchors) {
+      const range = anchor.lineRange
+        ? `:${anchor.lineRange[0]}-${anchor.lineRange[1]}`
+        : "";
+      lines.push(`  - ${anchor.path}${range}`);
+    }
+  }
+  return lines;
+}
+
+export function toRecallExplainText(
+  snapshot: LastRecallSnapshot | null,
+): string {
+  const lines: string[] = ["=== Recall Explain ==="];
+
+  if (!snapshot) {
+    lines.push("No recall snapshot recorded yet.");
+    return lines.join("\n");
+  }
+
+  const sessionKey = sanitizeString(snapshot.sessionKey);
+  const recordedAt = sanitizeString(snapshot.recordedAt);
+  const namespace = sanitizeString(snapshot.namespace);
+  const source = sanitizeString(snapshot.source);
+  lines.push(`session: ${sessionKey ?? "(unknown)"}`);
+  lines.push(`recorded: ${recordedAt ?? "(unknown)"}`);
+  if (namespace) lines.push(`namespace: ${namespace}`);
+  if (source) lines.push(`source: ${source}`);
+  const sourcesUsed = Array.isArray(snapshot.sourcesUsed)
+    ? snapshot.sourcesUsed.filter((x): x is string => typeof x === "string")
+    : [];
+  if (sourcesUsed.length > 0) {
+    lines.push(`sources-used: ${sourcesUsed.join(", ")}`);
+  }
+  const latencyMs = sanitizeFiniteNumber(snapshot.latencyMs);
+  if (latencyMs !== null) {
+    lines.push(`latency-ms: ${latencyMs}`);
+  }
+  const memoryIds = Array.isArray(snapshot.memoryIds)
+    ? snapshot.memoryIds.filter((x): x is string => typeof x === "string")
+    : [];
+  if (memoryIds.length > 0) {
+    lines.push(`memories: ${memoryIds.join(", ")}`);
+  }
+
+  const ex = normalizeTierExplain(snapshot.tierExplain);
+  if (!ex) {
+    lines.push("");
+    lines.push(
+      "tier-explain: (not populated — direct-answer tier disabled or did not fire)",
+    );
+    return lines.join("\n");
+  }
+
+  lines.push("");
+  lines.push("--- tier explain ---");
+  for (const line of renderTierExplainTextLines(ex)) {
+    lines.push(line);
+  }
+  return lines.join("\n");
+}
+
+/**
+ * Adapter: convert a `LastRecallSnapshot` into a best-effort
+ * `RecallXraySnapshot` so the markdown renderer can produce a
+ * consistent, richly-formatted document for callers that have asked
+ * for `markdown` format.  The LastRecallSnapshot and the X-ray
+ * snapshot share session/namespace/memoryIds; additional X-ray-only
+ * fields (filters, score decomposition, graph path, audit id) are
+ * left empty because the legacy snapshot doesn't carry them.  The
+ * renderer handles missing fields gracefully.
+ */
+/**
+ * Strip backticks, pipes, and newlines from a host-provided value so it
+ * cannot escape its enclosing markdown code span, break the surrounding
+ * table row, or inject extra rows when it lands in
+ * `renderXrayMarkdown`.  Applied at the adapter boundary because
+ * `LastRecallSnapshot` is hydrated from on-disk JSON without schema
+ * validation (codex P2 review on #605).
+ *
+ * Accepts `unknown` so non-string truthy values (numbers, objects,
+ * booleans, arrays) coming from a corrupted snapshot are coerced to
+ * the empty string rather than crashing on `.replace(...)`.  Callers
+ * should treat an empty return as "drop this field."
+ */
+function sanitizeForMarkdownInline(value: unknown): string {
+  if (typeof value !== "string") return "";
+  return value.replace(/[`|\r\n]/g, " ").trim();
+}
+
+/**
+ * Map the legacy `LastRecallSnapshot.source` field to the
+ * `RecallXrayServedBy` union used by the unified x-ray renderer.
+ * Mirrors the `mapRecallSourceToXrayServedBy` helper inside
+ * `orchestrator.ts` (which is private).  Keep the two in sync when a
+ * new source lands — unknown values collapse to `"hybrid"` to preserve
+ * backwards compatibility with older on-disk snapshots.
+ */
+function mapLegacySourceToServedBy(
+  source: unknown,
+): "hybrid" | "recent-scan" {
+  if (source === "recent_scan") return "recent-scan";
+  return "hybrid";
+}
+
+export function toRecallXraySnapshotFromLegacy(
+  snapshot: LastRecallSnapshot | null,
+): RecallXraySnapshot | null {
+  if (!snapshot) return null;
+  const capturedAt = (() => {
+    if (typeof snapshot.recordedAt !== "string") return 0;
+    const ms = Date.parse(snapshot.recordedAt);
+    return Number.isFinite(ms) && ms >= 0 ? ms : 0;
+  })();
+  const memoryIds = Array.isArray(snapshot.memoryIds)
+    ? snapshot.memoryIds.filter((x): x is string => typeof x === "string")
+    : [];
+  // Codex P2 + Cursor Medium on #605: every converted result used to
+  // be stamped with `servedBy: "hybrid"`, misattributing legacy
+  // snapshots that came from `recent_scan` (or any future source).
+  // Propagate the recorded `source` so markdown `recall-explain`
+  // output matches the `served-by=` string the native x-ray capture
+  // would emit for the same recall.
+  const servedBy = mapLegacySourceToServedBy(snapshot.source);
+  const results: RecallXrayResult[] = memoryIds.map((memoryId) => ({
+    memoryId,
+    path: "",
+    servedBy,
+    scoreDecomposition: { final: 0 },
+    admittedBy: [],
+  }));
+  const filters: RecallFilterTrace[] = [];
+  return {
+    schemaVersion: "1",
+    // `LastRecallSnapshot` does not preserve the original query text;
+    // synthesize a placeholder so the renderer has a non-empty
+    // string to print.  `queryHash` + `queryLen` stay in the JSON
+    // payload via `toRecallExplainJson` for callers that need them.
+    query:
+      snapshot.queryHash
+        ? `(legacy explain; queryHash=${snapshot.queryHash})`
+        : "(legacy explain)",
+    // `snapshotId` is synthesized here; `sessionKey` is already
+    // sanitized before it reaches the ID because we re-use the
+    // sanitized string below.
+    snapshotId: `legacy-${sanitizeForMarkdownInline(snapshot.sessionKey ?? "unknown") || "unknown"}-${capturedAt}`,
+    capturedAt,
+    // Run the raw on-disk value through the same normalizer the text
+    // and JSON paths use so the markdown adapter cannot render
+    // unvalidated tier-explain payloads (cursor / codex review on
+    // #605).  A malformed tierExplain is dropped to null, matching the
+    // behavior of the non-markdown surfaces.
+    tierExplain: normalizeTierExplain(snapshot.tierExplain) ?? null,
+    results,
+    filters,
+    budget: { chars: 0, used: 0 },
+    // Sanitize legacy session metadata at the adapter boundary so a
+    // malformed on-disk value (containing backticks, pipes, or
+    // newlines) cannot break the enclosing markdown table when
+    // `renderXrayMarkdown` prints it in a raw code-span cell (codex P2
+    // review on #605).
+    ...(snapshot.sessionKey
+      ? (() => {
+          const clean = sanitizeForMarkdownInline(snapshot.sessionKey);
+          return clean ? { sessionKey: clean } : {};
+        })()
+      : {}),
+    ...(snapshot.namespace
+      ? (() => {
+          const clean = sanitizeForMarkdownInline(snapshot.namespace);
+          return clean ? { namespace: clean } : {};
+        })()
+      : {}),
+  };
+}
+
+export function renderRecallExplain(
+  snapshot: LastRecallSnapshot | null,
+  format: RecallExplainFormat,
+): string {
+  if (format === "json") {
+    return JSON.stringify(toRecallExplainJson(snapshot), null, 2);
+  }
+  if (format === "markdown") {
+    // Delegate to the shared X-ray renderer so CLI / HTTP / MCP
+    // markdown output all share one implementation (CLAUDE.md rule
+    // 22).  The JSON and text paths remain byte-for-byte
+    // backwards-compatible with pre-#570 behavior.
+    return renderXrayMarkdown(toRecallXraySnapshotFromLegacy(snapshot));
+  }
+  return toRecallExplainText(snapshot);
+}
+
+export function parseRecallExplainFormat(value: unknown): RecallExplainFormat {
+  if (value === undefined || value === null) return "text";
+  if (typeof value !== "string") {
+    throw new Error(
+      `--format expects "text", "json", or "markdown", got ${typeof value}`,
+    );
+  }
+  const v = value.trim().toLowerCase();
+  if (v === "text" || v === "json" || v === "markdown") return v;
+  throw new Error(
+    `--format expects "text", "json", or "markdown", got ${JSON.stringify(value)}`,
+  );
+}