agentwaste-core 0.1.0

package/src/tools.js

@@ -0,0 +1,803 @@
+import { toReportJson } from "./report.js";
+
+export const TOOL_IDS = ["suckytraces", "keybarf", "tokengoblin", "tooltantrum"];
+
+const TOOL_CONFIGS = {
+  suckytraces: {
+    id: "suckytraces",
+    packageName: "suckytraces",
+    binName: "suckytraces",
+    metricKey: "trace_coverage",
+    emoji: "🕵️",
+    npc: "Trace Goblin",
+    tagline: "sniffs out agent runs that cannot be replayed, explained, or defended in standup.",
+    good: "traceable little angel",
+    bad: "all vibes, no receipts",
+    commandHint: "npx suckytraces",
+    score(metric) {
+      if (metric.session_log_files === 0) return 20;
+      return clamp(100 - metric.session_file_coverage_percent);
+    },
+    findings(metric) {
+      return [
+        finding("coverage", `${metric.session_file_coverage_percent}% replayable`, metric.level),
+        finding("traced files", `${formatNumber(metric.traced_session_log_files)} / ${formatNumber(metric.session_log_files)} session logs`),
+        finding("trace crumbs", `${formatNumber(metric.structured_trace_signals)} structured signals`),
+      ];
+    },
+    roast(metric) {
+      if (metric.session_log_files === 0) return "No session logs found. The goblin is unemployed but suspicious.";
+      if (metric.session_file_coverage_percent >= 80) return "Your traces have shoes, a map, and a tiny flashlight. Respect.";
+      if (metric.session_file_coverage_percent >= 30) return "Some traces exist, but the murder board still has yarn gaps.";
+      return "Debugging these runs is basically reading tea leaves in a server room.";
+    },
+    next(metric) {
+      if (metric.session_log_files === 0) return "run an agent once, then re-run this goblin";
+      if (metric.session_file_coverage_percent >= 80) return "keep run_id / trace_id attached to every meaningful tool call";
+      return "add run_id, trace_id, span_id, retry metadata, and final artifacts to agent/tool logs";
+    },
+    evidence(report) {
+      return report.evidence.trace_files_sample;
+    },
+    explain: [
+      "coverage = session log files with structured trace evidence / scanned session log files * 100",
+      "trace evidence includes trace_id, span_id, run_id, OpenTelemetry, or otel",
+      "goal: when an agent breaks prod, you can replay the plot instead of interviewing a ghost",
+    ],
+  },
+  keybarf: {
+    id: "keybarf",
+    packageName: "keybarf",
+    binName: "keybarf",
+    metricKey: "credential_exposure",
+    emoji: "🤮",
+    npc: "Secret Raccoon",
+    tagline: "rummages through local agent logs for API keys that should not be cosplay props.",
+    good: "vault goblin satisfied",
+    bad: "credential confetti cannon",
+    commandHint: "npx keybarf",
+    score(metric) {
+      return clamp(metric.score ?? 0);
+    },
+    findings(metric) {
+      const kinds = Object.entries(metric.by_kind ?? {})
+        .filter(([, count]) => count > 0)
+        .sort((a, b) => b[1] - a[1])
+        .slice(0, 4)
+        .map(([kind, count]) => `${kind}:${count}`)
+        .join(", ");
+      return [
+        finding("secret fp", `${formatNumber(metric.unique_secret_fingerprints)} unique redacted fingerprints`, metric.level),
+        finding("model-facing", `${formatNumber(metric.model_facing_secret_fingerprints)} fingerprints reached prompt/tool context`, metric.model_facing_secret_fingerprints > 0 ? "CRITICAL" : "LOW"),
+        finding("kinds", kinds || "none spotted"),
+        finding("risk score", `${formatNumber(metric.score)} / 100`, metric.level),
+      ];
+    },
+    roast(metric) {
+      if (metric.model_facing_secret_fingerprints > 0) return "A model saw secret-shaped material. The raccoon is screaming into a paper bag.";
+      if (metric.unique_secret_fingerprints > 0) return "Secrets are sitting in logs/config like snacks on a sidewalk.";
+      return "No obvious key barf. The raccoon found crumbs, not crimes.";
+    },
+    next(metric) {
+      if (metric.model_facing_secret_fingerprints > 0) return "rotate exposed keys, purge logs, and vault credentials before the next agent run";
+      if (metric.unique_secret_fingerprints > 0) return "move keys into a vault/env boundary and stop printing them into logs";
+      return "keep secrets out of prompts, tool args, pasted stack traces, and debug logs";
+    },
+    evidence(report) {
+      return report.evidence.secret_files_sample;
+    },
+    explain: [
+      "raw keys = unique redacted fingerprints matched by known API-key patterns",
+      "model-facing keys = those fingerprints inside user/assistant/tool-call records",
+      "level = critical for model-facing material, high for raw secret material in logs/config",
+    ],
+  },
+  tokengoblin: {
+    id: "tokengoblin",
+    packageName: "tokengoblin",
+    binName: "tokengoblin",
+    metricKey: "context_efficiency",
+    emoji: "🧌",
+    npc: "Token Goblin",
+    tagline: "counts prompt calories, cache snacks, and context bloat burps.",
+    good: "lean prompt machine",
+    bad: "context buffet disaster",
+    commandHint: "npx tokengoblin",
+    score(metric) {
+      const levelBase = scoreFromLevel(metric.level);
+      const excessBoost = Math.min(35, metric.excess_fresh_input_percent || 0);
+      const cachePenalty = metric.cache_hit_percent < 20 && metric.fresh_input_tokens > 0 ? 10 : 0;
+      return clamp(levelBase + excessBoost + cachePenalty);
+    },
+    findings(metric, report) {
+      return [
+        finding("fresh/tool", `${formatNumber(metric.fresh_input_tokens_per_tool_call)} tokens`, metric.level),
+        finding("cache hit", `${metric.cache_hit_percent}%`, metric.cache_hit_percent >= 50 ? "LOW" : "MEDIUM"),
+        finding("excess", `${formatNumber(metric.excess_fresh_input_tokens)} fresh tokens over review line`),
+        finding("30d burn", `${formatNumber(report.monthly_impact_estimate.active_tokens_30d)} active tokens`),
+      ];
+    },
+    roast(metric) {
+      if (metric.level === "NO_DATA") return "No token footprints yet. Either pristine, empty, or wearing tiny socks.";
+      if (metric.fresh_input_tokens_per_tool_call >= metric.review_threshold_fresh_input_tokens_per_tool_call) return "Every tool call is dragging a suitcase full of prompt soup.";
+      if (metric.cache_hit_percent < 20 && metric.fresh_input_tokens > 0) return "The cache is basically a decorative bowl.";
+      return "Token goblin nibbled, but did not find a buffet catastrophe.";
+    },
+    next(metric) {
+      if (metric.level === "NO_DATA") return "run agents with token usage enabled, then ask the goblin again";
+      if (metric.fresh_input_tokens_per_tool_call >= metric.review_threshold_fresh_input_tokens_per_tool_call) return "trim repeated context, summarize durable state, and cache stable prompt chunks";
+      return "keep fresh input per tool low and move repeat loops into scripts/jobs";
+    },
+    evidence() {
+      return [];
+    },
+    explain: [
+      "fresh input = model input minus cached reads where providers expose caching",
+      "fresh/tool = sum(fresh input tokens) / tool calls",
+      "excess = fresh input above a conservative 4,000-token-per-tool review line",
+    ],
+  },
+  tooltantrum: {
+    id: "tooltantrum",
+    packageName: "tooltantrum",
+    binName: "tooltantrum",
+    metricKey: "tool_reliability",
+    emoji: "🛠️",
+    npc: "Retry Possum",
+    tagline: "tool reliability: failure rate, retry recovery, and unresolved calls.",
+    good: "healthy tool reliability",
+    bad: "unresolved tool failures",
+    commandHint: "npx tooltantrum",
+    score(metric) {
+      return clamp(scoreFromLevel(metric.level) + Math.min(40, metric.failure_rate_percent));
+    },
+    findings(metric) {
+      return [
+        finding("failure rate", `${metric.failure_rate_percent}%`, metric.level),
+        finding("failed", `${formatNumber(metric.failed_tool_calls)} / ${formatNumber(metric.tool_calls)} tool calls`),
+        finding("unresolved", `${formatNumber(metric.unresolved_failures)} failures never recovered`, metric.unresolved_failures > 0 ? metric.level : "LOW"),
+        finding("retry rescue", `${metric.retry_recovery_percent}% recovered after retry`),
+      ];
+    },
+    roast(metric) {
+      if (metric.tool_calls === 0) return "No tool calls found, so there is nothing to score yet.";
+      if (metric.failure_rate_percent >= 30) return "Very high tool failure rate. Agents are losing too many actions before finishing.";
+      if (metric.unresolved_failures > 0) return "Most failed tool calls did not show a later recovery signal.";
+      return "Tool calls look stable; retry behavior is boring in the good way.";
+    },
+    next(metric) {
+      if (metric.tool_calls === 0) return "run an agent with tool usage, then scan again";
+      if (metric.unresolved_failures > 0) return "classify retryable errors, make actions idempotent, cap retries, and save failure artifacts";
+      return "keep retries boring: classify failures, cap attempts, and log recovery";
+    },
+    evidence(report) {
+      return report.evidence.diagnostics;
+    },
+    explain: [
+      "failure rate = failed_tool_calls / tool_calls * 100",
+      "retry recovery = retry-after-failure signals / failed_tool_calls * 100",
+      "unresolved failures = failed tool calls that did not show a later retry signal",
+    ],
+  },
+};
+
+export function listToolConfigs() {
+  return TOOL_IDS.map((id) => TOOL_CONFIGS[id]);
+}
+
+export function getToolConfig(toolId) {
+  const config = TOOL_CONFIGS[toolId];
+  if (!config) throw new Error(`unknown tool ${toolId}`);
+  return config;
+}
+
+export function buildToolReport(stats, options) {
+  const config = getToolConfig(options.toolId);
+  const color = colorizer(options.color);
+  const full = toReportJson(stats, options);
+  const metric = full.metrics[config.metricKey];
+  const chaosScore = config.score(metric, full);
+  const verdict = verdictFor(config, metric, chaosScore);
+  const findings = config.findings(metric, full);
+  const evidence = config.evidence(full).slice(0, 5);
+  const json = {
+    version: options.version,
+    package: config.packageName,
+    command: config.commandHint,
+    npc: config.npc,
+    emoji: config.emoji,
+    tagline: config.tagline,
+    scanned: full.scanned,
+    metric_key: config.metricKey,
+    metric,
+    chaos_score: chaosScore,
+    verdict,
+    findings: findings.map(({ label, value }) => ({ label, value })),
+    roast: config.roast(metric, full),
+    evidence_sample: evidence,
+  };
+  return {
+    json,
+    text: renderToolText(config, full, metric, findings, evidence, verdict, chaosScore, color),
+  };
+}
+
+export function explainTool(toolId, options = {}) {
+  const config = getToolConfig(toolId);
+  const payload = {
+    version: options.version ?? "0.1.0",
+    package: config.packageName,
+    command: config.commandHint,
+    npc: config.npc,
+    metric_key: config.metricKey,
+    formulas: config.explain,
+  };
+  if (options.json) return JSON.stringify(payload, null, 2);
+  return [
+    `${config.packageName} explain v${payload.version}`,
+    `${config.emoji} ${config.npc}: ${config.tagline}`,
+    "",
+    ...config.explain.map((line) => `- ${line}`),
+  ].join("\n");
+}
+
+function renderToolText(config, full, metric, findings, evidence, verdict, chaosScore, color) {
+  const rows = [
+    reportText(`${config.packageName} postmortem`, color.title(`${config.packageName} postmortem`)),
+    reportText("──────────────────────────────", color.rule("──────────────────────────────")),
+    reportText(""),
+    reportSection("finding", color),
+    ...paragraphRows(toolFinding(config.id, metric), color, { level: metric.level ?? verdict.level }),
+    reportText(""),
+    reportSection("impact", color),
+    ...paragraphRows(toolImpact(config.id, full, metric), color),
+    reportText(""),
+    reportSection("agent leaderboard", color),
+    ...toolAgentLeaderboard(config.id, full, color),
+    reportText(""),
+    reportSection("numbers", color),
+    ...toolNumbers(config.id, full, metric, color),
+  ];
+
+  return rows.map((row) => row.painted).join("\n");
+}
+
+function toolFinding(toolId, metric) {
+  switch (toolId) {
+    case "suckytraces":
+      if (metric.session_log_files === 0) return "No session log files were found.";
+      return `Only ${formatPercent(metric.session_file_coverage_percent)} of scanned session logs include trace, run, or span IDs.`;
+    case "keybarf":
+      if (metric.model_facing_secret_fingerprints > 0) return "Secret fingerprints appeared in model-facing records.";
+      if (metric.unique_secret_fingerprints > 0) return "Secret fingerprints were found in local logs or config.";
+      return "No known secret fingerprints were found.";
+    case "tokengoblin":
+      if (metric.level === "NO_DATA") return "No token usage records were found.";
+      return `Fresh input averages ${formatNumber(metric.fresh_input_tokens_per_tool_call)} tokens per tool call.`;
+    case "tooltantrum":
+      if (metric.tool_calls === 0) return "No tool-call records were found.";
+      return `${formatPercent(metric.failure_rate_percent)} of tool calls failed; ${formatPercent(metric.retry_recovery_percent)} of failures showed retry recovery.`;
+    default:
+      return "No finding available.";
+  }
+}
+
+function toolImpact(toolId, full, metric) {
+  switch (toolId) {
+    case "suckytraces": {
+      const missing = Math.max(0, metric.session_log_files - metric.traced_session_log_files);
+      if (metric.session_log_files === 0) return "There are no runs to assess yet.";
+      return `${formatNumber(missing)} session logs may be hard to replay or debug after the fact.`;
+    }
+    case "keybarf":
+      if (metric.model_facing_secret_fingerprints > 0) return "Credentials may need rotation because secret-like data reached model-facing context.";
+      if (metric.unique_secret_fingerprints > 0) return "Secret material is present where local tools or logs can retain it.";
+      return "No credential exposure was detected by the current patterns.";
+    case "tokengoblin":
+      if (metric.excess_fresh_input_tokens > 0) return `${formatNumber(metric.excess_fresh_input_tokens)} fresh input tokens exceeded the review threshold in the scanned window.`;
+      return "Fresh input stayed under the review threshold for the scanned window.";
+    case "tooltantrum":
+      if (metric.unresolved_failures > 0) return `${formatNumber(metric.unresolved_failures)} failed tool calls did not show a later recovery signal.`;
+      if (metric.failed_tool_calls > 0) return "Failures occurred, but scanned retry signals recovered them.";
+      return "No failed tool calls were detected in the scanned window.";
+    default:
+      return "No impact available.";
+  }
+}
+
+function toolNumbers(toolId, full, metric, color) {
+  switch (toolId) {
+    case "suckytraces":
+      return [
+        metricLine("session logs scanned", formatNumber(metric.session_log_files), color),
+        metricLine("logs with trace/run ids", `${formatNumber(metric.traced_session_log_files)} / ${formatNumber(metric.session_log_files)}`, color, { level: metric.level }),
+        metricLine("trace coverage", formatPercent(metric.session_file_coverage_percent), color, { level: metric.level }),
+        metricLine("trace/run/span markers", formatNumber(metric.structured_trace_signals), color),
+      ];
+    case "keybarf":
+      return [
+        metricLine("unique fingerprints", formatNumber(metric.unique_secret_fingerprints), color, { level: metric.level }),
+        metricLine("model-facing", formatNumber(metric.model_facing_secret_fingerprints), color, { level: metric.model_facing_secret_fingerprints > 0 ? "CRITICAL" : "LOW" }),
+        metricLine("detected kinds", compactKinds(metric.by_kind), color),
+      ];
+    case "tokengoblin":
+      return [
+        metricLine("fresh input/tool", `${formatNumber(metric.fresh_input_tokens_per_tool_call)} tokens`, color, { level: metric.level }),
+        metricLine("review threshold", `${formatNumber(metric.review_threshold_fresh_input_tokens_per_tool_call)} tokens/tool`, color),
+        metricLine("cache hit rate", formatPercent(metric.cache_hit_percent), color, { level: metric.cache_hit_percent >= 50 ? "LOW" : "MEDIUM" }),
+        metricLine("excess fresh input", `${formatNumber(metric.excess_fresh_input_tokens)} tokens`, color, { level: metric.excess_fresh_input_tokens > 0 ? metric.level : "LOW" }),
+        metricLine("30d active tokens", formatNumber(full.monthly_impact_estimate.active_tokens_30d), color),
+      ];
+    case "tooltantrum": {
+      const recovered = Math.max(0, metric.failed_tool_calls - metric.unresolved_failures);
+      return [
+        metricLine("tool calls", formatNumber(metric.tool_calls), color),
+        metricLine("failed calls", formatNumber(metric.failed_tool_calls), color, { level: metric.failed_tool_calls > 0 ? metric.level : "LOW" }),
+        metricLine("failure rate", formatPercent(metric.failure_rate_percent), color, { level: metric.level }),
+        metricLine("recovered after retry", formatNumber(recovered), color, { level: recovered > 0 ? "LOW" : undefined }),
+        metricLine("unresolved failures", formatNumber(metric.unresolved_failures), color, { level: metric.unresolved_failures > 0 ? metric.level : "LOW" }),
+        metricLine("retry recovery rate", formatPercent(metric.retry_recovery_percent), color, { level: metric.retry_recovery_percent >= 80 ? "LOW" : "HIGH" }),
+      ];
+    }
+    default:
+      return [];
+  }
+}
+
+function toolNextStep(toolId, metric) {
+  switch (toolId) {
+    case "suckytraces":
+      return "Write a run_id, trace_id, or span_id into each tool execution log.";
+    case "keybarf":
+      if (metric.model_facing_secret_fingerprints > 0) return "Rotate exposed credentials and move secrets behind environment or secret-manager boundaries.";
+      if (metric.unique_secret_fingerprints > 0) return "Move secrets out of logs/config and keep only redacted values in agent context.";
+      return "Keep secrets out of prompts, tool arguments, stack traces, and debug logs.";
+    case "tokengoblin":
+      if (metric.excess_fresh_input_tokens > 0) return "Trim repeated prompt context and cache stable input before tool-heavy runs.";
+      return "Keep fresh input per tool call below the review threshold.";
+    case "tooltantrum":
+      if (metric.unresolved_failures > 0) return "Classify retryable errors, make tool actions idempotent, and persist final failure details.";
+      return "Keep retry behavior explicit: classify errors, cap attempts, and log recovery.";
+    default:
+      return "Review the finding above.";
+  }
+}
+
+function toolAgentLeaderboard(toolId, full, color) {
+  const ranked = rankAgents(toolId, full).slice(0, 5);
+  if (ranked.length === 0) return paragraphRows("No agent had enough data for a leaderboard.", color);
+  const best = ranked[0];
+  return ranked.map((entry) => {
+    const winner = sameRank(entry, best);
+    return leaderboardLine(winner ? `🏆 ${entry.label}` : `   ${entry.label}`, entry.value, color, winner);
+  });
+}
+
+function rankAgents(toolId, full) {
+  const sources = Object.values(full.scanned.sources ?? {})
+    .filter((source) => source.label !== "Agent config" && source.unavailable !== true);
+
+  if (toolId === "suckytraces") {
+    return sources
+      .filter((source) => eligibleAgent(toolId, source))
+      .map((source) => {
+        const percent = source.files > 0 ? Math.round(((source.traced_session_log_files ?? 0) / source.files) * 100) : 0;
+        return {
+          label: source.label,
+          sort: -percent,
+          value: `${percent}% coverage (${formatNumber(source.traced_session_log_files ?? 0)} / ${formatNumber(source.files)})`,
+        };
+      })
+      .sort(compareAgentRank);
+  }
+
+  if (toolId === "keybarf") {
+    return sources
+      .filter((source) => eligibleAgent(toolId, source))
+      .map((source) => {
+        const modelFacing = source.model_facing_secret_fingerprints ?? 0;
+        const total = Math.max(source.secret_fingerprints ?? 0, modelFacing);
+        return {
+          label: source.label,
+          sort: modelFacing,
+          tiebreaker: total,
+          value: `${formatNumber(modelFacing)} model-facing · ${formatNumber(total)} total`,
+        };
+      })
+      .sort(compareAgentRank);
+  }
+
+  if (toolId === "tokengoblin") {
+    return sources
+      .filter((source) => eligibleAgent(toolId, source))
+      .map((source) => {
+        const freshPerTool = Math.round((source.fresh_input_tokens ?? 0) / source.tool_calls);
+        return {
+          label: source.label,
+          sort: freshPerTool,
+          value: `${formatNumber(freshPerTool)} fresh input/tool`,
+        };
+      })
+      .sort(compareAgentRank);
+  }
+
+  if (toolId === "tooltantrum") {
+    return sources
+      .filter((source) => eligibleAgent(toolId, source))
+      .map((source) => {
+        const failureRate = round(((source.failed_tool_calls ?? 0) / source.tool_calls) * 100, 1);
+        return {
+          label: source.label,
+          sort: failureRate,
+          tiebreaker: source.failed_tool_calls ?? 0,
+          value: `${failureRate}% failure (${formatNumber(source.failed_tool_calls ?? 0)} / ${formatNumber(source.tool_calls)})`,
+        };
+      })
+      .sort(compareAgentRank);
+  }
+
+  return [];
+}
+
+function eligibleAgent(toolId, source) {
+  switch (toolId) {
+    case "suckytraces":
+      return (source.files ?? 0) >= 20;
+    case "keybarf":
+      return (source.files ?? 0) >= 20 || (source.sessions ?? 0) >= 20;
+    case "tokengoblin":
+      return (source.tool_calls ?? 0) >= 50 && (source.fresh_input_tokens ?? 0) > 0;
+    case "tooltantrum":
+      return (source.tool_calls ?? 0) >= 50;
+    default:
+      return false;
+  }
+}
+
+function compareAgentRank(a, b) {
+  if (a.sort !== b.sort) return a.sort - b.sort;
+  return (a.tiebreaker ?? 0) - (b.tiebreaker ?? 0);
+}
+
+function sameRank(a, b) {
+  return a.sort === b.sort && (a.tiebreaker ?? 0) === (b.tiebreaker ?? 0);
+}
+
+function leaderboardLine(label, value, color, winner) {
+  const safeLabel = shortText(label, 26).padEnd(26);
+  const paintLabel = winner ? color.solution(safeLabel) : color.label(safeLabel);
+  const paintValue = winner ? color.solution(value) : color.value(value);
+  return { raw: `    ${safeLabel} ${value}`, painted: `    ${paintLabel} ${paintValue}` };
+}
+
+function sectionTitle(toolId) {
+  switch (toolId) {
+    case "suckytraces":
+      return "trace coverage";
+    case "keybarf":
+      return "credential exposure";
+    case "tokengoblin":
+      return "context usage";
+    case "tooltantrum":
+      return "tool reliability";
+    default:
+      return "metrics";
+  }
+}
+
+function compactStatus(toolId, metric) {
+  switch (toolId) {
+    case "suckytraces":
+      if (metric.session_log_files === 0) return "no session log files were found";
+      if (metric.session_file_coverage_percent >= 80) return "most session logs contain trace evidence";
+      if (metric.session_file_coverage_percent >= 30) return "some session logs contain trace evidence";
+      return "fewer than 30% of session logs contain trace evidence";
+    case "keybarf":
+      if (metric.model_facing_secret_fingerprints > 0) return "secret fingerprints reached model-facing records";
+      if (metric.unique_secret_fingerprints > 0) return "secret fingerprints were found in logs or config";
+      return "no secret fingerprints matched known patterns";
+    case "tokengoblin":
+      if (metric.level === "NO_DATA") return "no token usage records were found";
+      if (metric.fresh_input_tokens_per_tool_call >= metric.review_threshold_fresh_input_tokens_per_tool_call) return "fresh input per tool call exceeds the review threshold";
+      if (metric.cache_hit_percent < 20 && metric.fresh_input_tokens > 0) return "cache hit rate is low for observed input";
+      return "fresh input per tool call is within the review threshold";
+    case "tooltantrum":
+      return toolReliabilityStatus(metric);
+    default:
+      return "ok";
+  }
+}
+
+function toolReliabilityStatus(metric) {
+  if (metric.tool_calls === 0) return "no tool-call records were found";
+  if (metric.unresolved_failures > 0 && metric.retry_recovery_percent < 20) return "failed calls rarely show retry recovery";
+  if (metric.unresolved_failures > 0) return "some failed calls did not show recovery";
+  if (metric.failure_rate_percent >= 15) return "tool-call failure rate is high";
+  if (metric.failure_rate_percent >= 5) return "tool-call failure rate is moderate";
+  return "tool-call failure rate is low";
+}
+
+function verdictFor(config, metric, score) {
+  const level = metric.level ?? scoreLevel(score);
+  if (score >= 75 || level === "CRITICAL" || level === "MISSING") return { level, label: config.bad, mood: "bad" };
+  if (score >= 45 || level === "HIGH") return { level, label: "spicy enough to investigate", mood: "spicy" };
+  if (score >= 20 || level === "MEDIUM" || level === "PARTIAL") return { level, label: "a little haunted", mood: "haunted" };
+  return { level, label: config.good, mood: "good" };
+}
+
+function scoreLevel(score) {
+  if (score >= 75) return "CRITICAL";
+  if (score >= 45) return "HIGH";
+  if (score >= 20) return "MEDIUM";
+  return "LOW";
+}
+
+function finding(label, value, level) {
+  return { label, value, level };
+}
+
+function pairRow(label, value, color, options = {}) {
+  const safeLabel = String(label).slice(0, 12);
+  const raw = `${safeLabel.padEnd(12)} ${value}`;
+  const paintValue = options.solution ? color.solution(value) : options.level ? color.level(value, options.level) : color.value(value);
+  return { raw, painted: `${color.label(safeLabel.padEnd(12))} ${paintValue}` };
+}
+
+function reportLine(label, value, color, options = {}) {
+  const labelWidth = options.labelWidth ?? 14;
+  const indent = " ".repeat(options.indent ?? 2);
+  const safeLabel = String(label).toLowerCase().slice(0, labelWidth);
+  const raw = `${indent}${safeLabel.padEnd(labelWidth)} ${value}`;
+  const paintValue = options.solution ? color.solution(value) : options.level ? color.level(value, options.level) : color.value(value);
+  return { raw, painted: `${indent}${color.label(safeLabel.padEnd(labelWidth))} ${paintValue}` };
+}
+
+function metricLine(label, value, color, options = {}) {
+  return reportLine(label, value, color, { ...options, indent: 4, labelWidth: 28 });
+}
+
+function reportSection(label, color) {
+  return reportText(String(label).toLowerCase(), color.title(String(label).toLowerCase()));
+}
+
+function paragraphRows(value, color, options = {}) {
+  const indent = "    ";
+  return wrapText(String(value), 76).map((line) => {
+    const paintValue = options.solution ? color.solution(line) : options.level ? color.level(line, options.level) : color.value(line);
+    return { raw: `${indent}${line}`, painted: `${indent}${paintValue}` };
+  });
+}
+
+function reportText(raw, painted = raw) {
+  return { raw, painted: raw ? `  ${painted}` : "" };
+}
+
+function wrappedPairRows(label, value, color, options = {}) {
+  const labelWidth = 12;
+  const width = options.width ?? 74;
+  const textWidth = Math.max(20, width - labelWidth - 1);
+  const lines = wrapText(String(value), textWidth);
+  return lines.map((line, index) => {
+    const visibleLabel = index === 0 ? String(label).slice(0, labelWidth) : "";
+    const paintValue = options.solution ? color.solution(line) : options.level ? color.level(line, options.level) : color.value(line);
+    return {
+      raw: `${visibleLabel.padEnd(labelWidth)} ${line}`,
+      painted: `${color.label(visibleLabel.padEnd(labelWidth))} ${paintValue}`,
+    };
+  });
+}
+
+function ruleRow() {
+  return { rule: true, raw: "", painted: "" };
+}
+
+function textRow(raw, painted = raw) {
+  return { raw, painted };
+}
+
+function blankRow() {
+  return { raw: "", painted: "" };
+}
+
+function box(title, rows, color) {
+  const width = Math.max(48, title.length + 4, ...rows.map((row) => row.raw.length));
+  const topFill = "─".repeat(Math.max(1, width - title.length - 1));
+  const bottomFill = "─".repeat(width + 2);
+  return [
+    `${color.border("╭─")} ${color.title(title)} ${color.border(`${topFill}╮`)}`,
+    ...rows.map((row) => boxRow(row, width, color)),
+    `${color.border("╰")}${color.border(bottomFill)}${color.border("╯")}`,
+  ].join("\n");
+}
+
+function boxRow(row, width, color) {
+  const padding = " ".repeat(Math.max(0, width - row.raw.length));
+  return `${color.border("│")} ${row.painted}${padding} ${color.border("│")}`;
+}
+
+function fixedBox(title, rows, color, width) {
+  const topFill = "─".repeat(Math.max(1, width - title.length - 1));
+  const bottomFill = "─".repeat(width + 2);
+  return [
+    `${color.border("╭─")} ${color.title(title)} ${color.border(`${topFill}╮`)}`,
+    ...rows.map((row) => fixedBoxRow(row, width, color)),
+    `${color.border("╰")}${color.border(bottomFill)}${color.border("╯")}`,
+  ].join("\n");
+}
+
+function fixedBoxRow(row, width, color) {
+  if (row.rule) return `${color.border("├")}${color.border("─".repeat(width + 2))}${color.border("┤")}`;
+  const raw = row.raw.length > width ? `${row.raw.slice(0, Math.max(0, width - 1))}…` : row.raw;
+  const painted = row.raw.length > width ? raw : row.painted;
+  const padding = " ".repeat(Math.max(0, width - raw.length));
+  return `${color.border("│")} ${painted}${padding} ${color.border("│")}`;
+}
+
+function largestFileLine(files) {
+  if (!Array.isArray(files) || files.length === 0) return "none";
+  const file = files[0];
+  if (typeof file === "string") return compactPath(file);
+  return `${compactPath(file.path ?? file.file ?? "unknown")} (${formatNumber(file.lines ?? 0)} lines)`;
+}
+
+function compactPath(value) {
+  const text = String(value ?? "unknown");
+  if (text.length <= 30) return text;
+  const tail = text.split(/[\\/]/).slice(-2).join("/");
+  return `…/${tail}`;
+}
+
+function compactKinds(kinds) {
+  const value = Object.entries(kinds ?? {})
+    .filter(([, count]) => count > 0)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 4)
+    .map(([kind, count]) => `${kind}:${count}`)
+    .join(", ");
+  return value || "none";
+}
+
+function rootSummary(roots) {
+  if (!Array.isArray(roots) || roots.length === 0) return "0";
+  return shortText(`${roots.length} (${roots.slice(0, 3).join(", ")}${roots.length > 3 ? ", …" : ""})`, 44);
+}
+
+function shortText(value, max) {
+  const text = String(value ?? "");
+  if (text.length <= max) return text;
+  return `${text.slice(0, Math.max(0, max - 1))}…`;
+}
+
+function scoreFromLevel(level) {
+  switch (String(level).toUpperCase()) {
+    case "CRITICAL":
+    case "MISSING":
+      return 82;
+    case "HIGH":
+      return 62;
+    case "MEDIUM":
+    case "PARTIAL":
+      return 34;
+    case "CONFIG_ONLY":
+    case "NO_DATA":
+      return 12;
+    default:
+      return 5;
+  }
+}
+
+function clamp(value) {
+  return Math.max(0, Math.min(100, Math.round(Number(value) || 0)));
+}
+
+function round(value, digits) {
+  const factor = 10 ** digits;
+  return Math.round(value * factor) / factor;
+}
+
+function scanWindow(days) {
+  return days === "all" ? "all sessions" : `last ${days}d`;
+}
+
+function formatNumber(value) {
+  return Number(value || 0).toLocaleString("en-US");
+}
+
+function formatPercent(value) {
+  const number = Number(value || 0);
+  return `${number.toFixed(Number.isInteger(number) ? 0 : 1)}%`;
+}
+
+function progressBar(value, max, width) {
+  const ratio = Math.max(0, Math.min(1, Number(value || 0) / Math.max(1, max)));
+  const filled = Math.max(value > 0 ? 1 : 0, Math.round(ratio * width));
+  return `${"█".repeat(Math.min(width, filled))}${"░".repeat(Math.max(0, width - filled))}`;
+}
+
+function scoreSparkline(score) {
+  return progressBar(score, 100, 12);
+}
+
+function wrapText(value, width) {
+  const words = String(value).split(/\s+/).filter(Boolean);
+  const lines = [];
+  let line = "";
+  for (const word of words) {
+    if (word.length > width) {
+      if (line) {
+        lines.push(line);
+        line = "";
+      }
+      lines.push(word.slice(0, width));
+      continue;
+    }
+    if (!line) {
+      line = word;
+      continue;
+    }
+    if (`${line} ${word}`.length > width) {
+      lines.push(line);
+      line = word;
+    } else {
+      line = `${line} ${word}`;
+    }
+  }
+  if (line) lines.push(line);
+  return lines.length > 0 ? lines : [""];
+}
+
+function formatSeconds(ms) {
+  const seconds = Math.max(0.1, Number(ms || 0) / 1000);
+  return `${seconds.toFixed(seconds >= 10 ? 0 : 1)}s`;
+}
+
+function colorizer(enabled) {
+  if (!enabled) return plainColors();
+  const paint = (code, value) => `\x1b[${code}m${value}\x1b[0m`;
+  return {
+    accent: (value) => paint("38;2;147;197;253", value),
+    border: (value) => paint("38;2;100;116;139", value),
+    label: (value) => paint("38;2;186;230;253", value),
+    muted: (value) => paint("38;2;148;163;184", value),
+    rule: (value) => paint("38;2;71;85;105", value),
+    solution: (value) => paint("38;2;125;211;252", value),
+    title: (value) => paint("38;2;147;197;253;1", value),
+    value: (value) => paint("38;2;226;232;240", value),
+    level: (value, level) => paint(levelColor(level), value),
+  };
+}
+
+function plainColors() {
+  return {
+    accent: (value) => value,
+    border: (value) => value,
+    label: (value) => value,
+    muted: (value) => value,
+    rule: (value) => value,
+    solution: (value) => value,
+    title: (value) => value,
+    value: (value) => value,
+    level: (value) => value,
+  };
+}
+
+function levelColor(level) {
+  switch (String(level).toLowerCase()) {
+    case "critical":
+    case "missing":
+      return "38;2;251;113;133";
+    case "high":
+      return "38;2;253;186;116";
+    case "medium":
+    case "partial":
+      return "38;2;147;197;253";
+    case "good":
+    case "low":
+      return "38;2;125;211;252";
+    case "config_only":
+    case "no_data":
+      return "38;2;148;163;184";
+    default:
+      return "90";
+  }
+}