inspecto 1.0.0

package/dist/index.js

@@ -0,0 +1,1234 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command } from "commander";
+
+// src/parser/project-scanner.ts
+import { readdir, stat } from "fs/promises";
+import { join as join2, basename, extname } from "path";
+
+// src/utils/paths.ts
+import { join } from "path";
+import { homedir } from "os";
+function getClaudeDir() {
+  return join(homedir(), ".claude");
+}
+
+// src/parser/project-scanner.ts
+async function scanSessions(options) {
+  const claudeDir = options?.dataDir ?? getClaudeDir();
+  const projectsDir = join2(claudeDir, "projects");
+  let projectDirs;
+  try {
+    projectDirs = await readdir(projectsDir);
+  } catch {
+    throw new Error(
+      `Claude Code data directory not found. Make sure Claude Code is installed and has been used at least once.
+Expected: ${projectsDir}`
+    );
+  }
+  if (options?.project) {
+    projectDirs = projectDirs.filter(
+      (dir) => dir.toLowerCase().includes(options.project.toLowerCase())
+    );
+  }
+  const sessions = [];
+  for (const projectDir of projectDirs) {
+    if (projectDir.startsWith(".")) continue;
+    const fullProjectDir = join2(projectsDir, projectDir);
+    let entries;
+    try {
+      entries = await readdir(fullProjectDir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (extname(entry) !== ".jsonl") continue;
+      const filePath = join2(fullProjectDir, entry);
+      const sessionId = basename(entry, ".jsonl");
+      try {
+        const fileStat = await stat(filePath);
+        if (options?.since && fileStat.mtime < options.since) continue;
+        sessions.push({
+          path: filePath,
+          sessionId,
+          projectSlug: projectDir,
+          mtime: fileStat.mtime
+        });
+      } catch {
+        continue;
+      }
+    }
+  }
+  sessions.sort((a, b) => b.mtime.getTime() - a.mtime.getTime());
+  return sessions;
+}
+async function getMostRecentSession(options) {
+  const sessions = await scanSessions(options);
+  if (sessions.length === 0) {
+    throw new Error(
+      "No Claude Code sessions found. Use Claude Code in a project first to generate session data."
+    );
+  }
+  return sessions[0];
+}
+
+// src/parser/jsonl-reader.ts
+import { createReadStream } from "fs";
+import { createInterface } from "readline";
+async function* readJsonl(filePath) {
+  const stream = createReadStream(filePath, { encoding: "utf-8" });
+  const rl = createInterface({ input: stream, crlfDelay: Infinity });
+  for await (const line of rl) {
+    const trimmed = line.trim();
+    if (trimmed.length === 0) continue;
+    try {
+      const record = JSON.parse(trimmed);
+      if (record && typeof record === "object" && "type" in record) {
+        yield record;
+      }
+    } catch {
+    }
+  }
+}
+
+// src/parser/session-builder.ts
+async function buildSession(records, sessionId, projectSlug) {
+  const assistantChunks = /* @__PURE__ */ new Map();
+  const turns = [];
+  let cwd = "";
+  let gitBranch = null;
+  let model = "";
+  let firstTimestamp = "";
+  let lastTimestamp = "";
+  for await (const record of records) {
+    if (isSkippable(record.type)) continue;
+    if (record.type === "user") {
+      const userRecord = record;
+      handleUserRecord(userRecord, turns);
+      captureMetadata(userRecord);
+    } else if (record.type === "assistant") {
+      const assistantRecord = record;
+      if (assistantRecord.message.model === "<synthetic>") continue;
+      if (assistantRecord.error) continue;
+      handleAssistantChunk(assistantRecord, assistantChunks);
+      captureMetadata(assistantRecord);
+    }
+  }
+  for (const [, acc] of assistantChunks) {
+    turns.push({
+      role: "assistant",
+      content: acc.content,
+      usage: acc.usage,
+      complete: acc.complete,
+      timestamp: acc.timestamp,
+      isHumanTurn: false,
+      model: acc.model
+    });
+  }
+  turns.sort((a, b) => a.timestamp.localeCompare(b.timestamp));
+  return {
+    id: sessionId,
+    projectSlug,
+    model,
+    turns,
+    startTime: firstTimestamp,
+    endTime: lastTimestamp,
+    cwd,
+    gitBranch,
+    durationMs: firstTimestamp && lastTimestamp ? new Date(lastTimestamp).getTime() - new Date(firstTimestamp).getTime() : 0
+  };
+  function captureMetadata(record) {
+    if (!firstTimestamp && record.timestamp) {
+      firstTimestamp = record.timestamp;
+    }
+    if (record.timestamp) {
+      lastTimestamp = record.timestamp;
+    }
+    if (!cwd && record.cwd) {
+      cwd = record.cwd;
+    }
+    if (gitBranch === null && record.gitBranch) {
+      gitBranch = record.gitBranch;
+    }
+    if (!model && record.type === "assistant") {
+      const ar = record;
+      if (ar.message.model && ar.message.model !== "<synthetic>") {
+        model = ar.message.model;
+      }
+    }
+  }
+  function handleUserRecord(record, turns2) {
+    const content = record.message.content;
+    const isHumanTurn = typeof content === "string" && !record.isMeta;
+    turns2.push({
+      role: "user",
+      content: normalizeContent(content),
+      usage: null,
+      complete: true,
+      timestamp: record.timestamp,
+      isHumanTurn
+    });
+  }
+  function handleAssistantChunk(record, chunks) {
+    const messageId = record.message.id;
+    let acc = chunks.get(messageId);
+    if (!acc) {
+      acc = {
+        content: [],
+        usage: null,
+        complete: false,
+        timestamp: record.timestamp,
+        model: record.message.model
+      };
+      chunks.set(messageId, acc);
+    }
+    for (const block of record.message.content) {
+      acc.content.push(block);
+    }
+    if (record.message.stop_reason !== null) {
+      acc.complete = true;
+      acc.usage = record.message.usage;
+    }
+  }
+}
+function normalizeContent(content) {
+  if (typeof content === "string") {
+    return [{ type: "text", text: content }];
+  }
+  return content;
+}
+var SKIPPABLE = /* @__PURE__ */ new Set([
+  "queue-operation",
+  "attachment",
+  "system",
+  "last-prompt"
+]);
+function isSkippable(type) {
+  return SKIPPABLE.has(type);
+}
+
+// src/metrics/reads-per-edit.ts
+var EDIT_TOOLS = /* @__PURE__ */ new Set(["Write", "Edit", "NotebookEdit"]);
+var READ_TOOL = "Read";
+function computeReadsPerEdit(session) {
+  let readsSinceLastEdit = 0;
+  const ratios = [];
+  for (const turn of session.turns) {
+    if (turn.role !== "assistant") continue;
+    for (const block of turn.content) {
+      if (block.type !== "tool_use") continue;
+      const toolBlock = block;
+      if (toolBlock.name === READ_TOOL) {
+        readsSinceLastEdit++;
+      } else if (EDIT_TOOLS.has(toolBlock.name)) {
+        ratios.push(readsSinceLastEdit);
+        readsSinceLastEdit = 0;
+      }
+    }
+  }
+  if (ratios.length === 0) {
+    return {
+      name: "reads-per-edit",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No file modifications in this session"
+    };
+  }
+  const average2 = ratios.reduce((a, b) => a + b, 0) / ratios.length;
+  return {
+    name: "reads-per-edit",
+    value: round(average2),
+    status: average2 >= 4 ? "healthy" : average2 >= 2 ? "warning" : "critical",
+    label: round(average2).toString()
+  };
+}
+function round(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/metrics/rewrite-ratio.ts
+function computeRewriteRatio(session) {
+  let writes = 0;
+  let edits = 0;
+  for (const turn of session.turns) {
+    if (turn.role !== "assistant") continue;
+    for (const block of turn.content) {
+      if (block.type !== "tool_use") continue;
+      const toolBlock = block;
+      if (toolBlock.name === "Write") writes++;
+      else if (toolBlock.name === "Edit" || toolBlock.name === "NotebookEdit") edits++;
+    }
+  }
+  const total = writes + edits;
+  if (total === 0) {
+    return {
+      name: "rewrite-ratio",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No file modifications in this session"
+    };
+  }
+  const ratio = writes / total;
+  return {
+    name: "rewrite-ratio",
+    value: round2(ratio),
+    status: ratio <= 0.25 ? "healthy" : ratio <= 0.5 ? "warning" : "critical",
+    label: round2(ratio).toString()
+  };
+}
+function round2(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/metrics/cache-hit-rate.ts
+function computeCacheHitRate(session) {
+  let totalCacheRead = 0;
+  let totalCacheCreation = 0;
+  for (const turn of session.turns) {
+    if (turn.role !== "assistant" || !turn.usage || !turn.complete) continue;
+    totalCacheRead += turn.usage.cache_read_input_tokens;
+    totalCacheCreation += turn.usage.cache_creation_input_tokens;
+  }
+  const totalInput = totalCacheRead + totalCacheCreation;
+  if (totalInput === 0) {
+    return {
+      name: "cache-hit-rate",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No token usage data available"
+    };
+  }
+  const rate = totalCacheRead / totalInput;
+  return {
+    name: "cache-hit-rate",
+    value: round3(rate),
+    status: rate >= 0.5 ? "healthy" : rate >= 0.2 ? "warning" : "critical",
+    label: round3(rate).toString()
+  };
+}
+function round3(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/metrics/task-completion.ts
+var INTENT_PATTERNS = [
+  /\bI'll now\b/i,
+  /\bLet me\b/i,
+  /\bI'll update\b/i,
+  /\bNext,? I'll\b/i,
+  /\bI'll (?:also |then )?(?:fix|add|create|implement|refactor|modify|change|write|edit|update)\b/i,
+  /\bI'm going to\b/i
+];
+function computeTaskCompletion(session) {
+  const assistantTurns = session.turns.filter(
+    (t) => t.role === "assistant" && t.complete
+  );
+  let totalIntents = 0;
+  let unfulfilledIntents = 0;
+  for (const turn of assistantTurns) {
+    const hasIntent = hasIntentPhrase(turn);
+    if (!hasIntent) continue;
+    totalIntents++;
+    const hasToolUse = turn.content.some((b) => b.type === "tool_use");
+    if (!hasToolUse) {
+      unfulfilledIntents++;
+    }
+  }
+  if (totalIntents === 0) {
+    return {
+      name: "task-completion",
+      value: 1,
+      status: "healthy",
+      label: "1.00",
+      detail: "No intent phrases detected"
+    };
+  }
+  const rate = 1 - unfulfilledIntents / totalIntents;
+  return {
+    name: "task-completion",
+    value: round4(rate),
+    status: rate >= 0.9 ? "healthy" : rate >= 0.7 ? "warning" : "critical",
+    label: round4(rate).toString()
+  };
+}
+function hasIntentPhrase(turn) {
+  for (const block of turn.content) {
+    if (block.type === "text") {
+      const textBlock = block;
+      if (INTENT_PATTERNS.some((p) => p.test(textBlock.text))) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function round4(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/utils/levenshtein.ts
+function levenshteinDistance(a, b) {
+  if (a === b) return 0;
+  if (a.length === 0) return b.length;
+  if (b.length === 0) return a.length;
+  if (a.length > b.length) [a, b] = [b, a];
+  const aLen = a.length;
+  const bLen = b.length;
+  const row = new Array(aLen + 1);
+  for (let i = 0; i <= aLen; i++) row[i] = i;
+  for (let j = 1; j <= bLen; j++) {
+    let prev = row[0];
+    row[0] = j;
+    for (let i = 1; i <= aLen; i++) {
+      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+      const temp = row[i];
+      row[i] = Math.min(
+        row[i] + 1,
+        // deletion
+        row[i - 1] + 1,
+        // insertion
+        prev + cost
+        // substitution
+      );
+      prev = temp;
+    }
+  }
+  return row[aLen];
+}
+function normalizedSimilarity(a, b, maxLen = 200) {
+  const aTrunc = a.slice(0, maxLen);
+  const bTrunc = b.slice(0, maxLen);
+  const maxLength = Math.max(aTrunc.length, bTrunc.length);
+  if (maxLength === 0) return 1;
+  const distance = levenshteinDistance(aTrunc, bTrunc);
+  return 1 - distance / maxLength;
+}
+
+// src/metrics/retry-density.ts
+function computeRetryDensity(session) {
+  const humanTexts = [];
+  for (const turn of session.turns) {
+    if (!turn.isHumanTurn) continue;
+    const text = turn.content.filter((b) => b.type === "text").map((b) => b.text).join(" ");
+    if (text.length > 0) humanTexts.push(text);
+  }
+  if (humanTexts.length < 2) {
+    return {
+      name: "retry-density",
+      value: 0,
+      status: "healthy",
+      label: "0.00",
+      detail: "Not enough user messages to detect retries"
+    };
+  }
+  let retries = 0;
+  const pairs = humanTexts.length - 1;
+  for (let i = 0; i < pairs; i++) {
+    const similarity = normalizedSimilarity(humanTexts[i], humanTexts[i + 1]);
+    if (similarity > 0.6) {
+      retries++;
+    }
+  }
+  const density = retries / pairs;
+  return {
+    name: "retry-density",
+    value: round5(density),
+    status: density <= 0.1 ? "healthy" : density <= 0.25 ? "warning" : "critical",
+    label: round5(density).toString()
+  };
+}
+function round5(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/metrics/tool-diversity.ts
+function computeToolDiversity(session) {
+  const toolCounts = /* @__PURE__ */ new Map();
+  for (const turn of session.turns) {
+    if (turn.role !== "assistant") continue;
+    for (const block of turn.content) {
+      if (block.type !== "tool_use") continue;
+      const toolBlock = block;
+      toolCounts.set(toolBlock.name, (toolCounts.get(toolBlock.name) ?? 0) + 1);
+    }
+  }
+  const uniqueTools = toolCounts.size;
+  if (uniqueTools <= 1) {
+    return {
+      name: "tool-diversity",
+      value: uniqueTools === 0 ? null : 0,
+      status: uniqueTools === 0 ? "healthy" : "critical",
+      label: uniqueTools === 0 ? "N/A" : "0.00",
+      detail: uniqueTools === 0 ? "No tool usage in this session" : `Only one tool used: ${[...toolCounts.keys()][0]}`
+    };
+  }
+  const totalCalls = [...toolCounts.values()].reduce((a, b) => a + b, 0);
+  const maxEntropy = Math.log2(uniqueTools);
+  let entropy = 0;
+  for (const count of toolCounts.values()) {
+    const p = count / totalCalls;
+    entropy -= p * Math.log2(p);
+  }
+  const normalized = entropy / maxEntropy;
+  const sorted = [...toolCounts.entries()].sort((a, b) => b[1] - a[1]);
+  const topTool = sorted[0];
+  const topPercent = Math.round(topTool[1] / totalCalls * 100);
+  const detail = `Most used: ${topTool[0]} (${topPercent}%)`;
+  return {
+    name: "tool-diversity",
+    value: round6(normalized),
+    status: normalized >= 0.6 ? "healthy" : normalized >= 0.4 ? "warning" : "critical",
+    label: round6(normalized).toString(),
+    detail
+  };
+}
+function round6(n) {
+  return Math.round(n * 100) / 100;
+}
+
+// src/metrics/tokens-per-edit.ts
+var EDIT_TOOLS2 = /* @__PURE__ */ new Set(["Write", "Edit", "NotebookEdit"]);
+function computeTokensPerEdit(session) {
+  let totalOutputTokens = 0;
+  let editCount = 0;
+  for (const turn of session.turns) {
+    if (turn.role !== "assistant") continue;
+    if (turn.complete && turn.usage) {
+      totalOutputTokens += turn.usage.output_tokens;
+    }
+    for (const block of turn.content) {
+      if (block.type !== "tool_use") continue;
+      const toolBlock = block;
+      if (EDIT_TOOLS2.has(toolBlock.name)) editCount++;
+    }
+  }
+  if (editCount === 0) {
+    return {
+      name: "tokens-per-edit",
+      value: null,
+      status: "healthy",
+      label: "N/A",
+      detail: "No file modifications in this session"
+    };
+  }
+  const ratio = totalOutputTokens / editCount;
+  return {
+    name: "tokens-per-edit",
+    value: Math.round(ratio),
+    status: ratio <= 5e3 ? "healthy" : ratio <= 15e3 ? "warning" : "critical",
+    label: Math.round(ratio).toLocaleString("en-US")
+  };
+}
+
+// src/metrics/grader.ts
+var METRIC_WEIGHTS = [
+  {
+    compute: computeReadsPerEdit,
+    weight: 0.2,
+    // 0 reads → 0, 2 reads → 50, 4+ reads → 100
+    score: (v) => clamp(v / 4 * 100, 0, 100)
+  },
+  {
+    compute: computeRewriteRatio,
+    weight: 0.15,
+    // 0 ratio → 100, 0.25 → 50, 0.5+ → 0 (inverted: lower is better)
+    score: (v) => clamp((1 - v / 0.5) * 100, 0, 100)
+  },
+  {
+    compute: computeCacheHitRate,
+    weight: 0.15,
+    // 0% → 0, 50% → 100
+    score: (v) => clamp(v / 0.5 * 100, 0, 100)
+  },
+  {
+    compute: computeTaskCompletion,
+    weight: 0.15,
+    // 0.7 → 0, 0.9 → 50, 1.0 → 100
+    score: (v) => clamp((v - 0.7) / 0.3 * 100, 0, 100)
+  },
+  {
+    compute: computeRetryDensity,
+    weight: 0.1,
+    // 0% → 100, 10% → 60, 25%+ → 0 (inverted)
+    score: (v) => clamp((1 - v / 0.25) * 100, 0, 100)
+  },
+  {
+    compute: computeToolDiversity,
+    weight: 0.1,
+    // 0 → 0, 0.4 → 50, 0.6+ → 100
+    score: (v) => clamp(v / 0.6 * 100, 0, 100)
+  },
+  {
+    compute: computeTokensPerEdit,
+    weight: 0.15,
+    // 5000 → 100, 10000 → 50, 15000+ → 0 (inverted)
+    score: (v) => clamp((1 - (v - 5e3) / 1e4) * 100, 0, 100)
+  }
+];
+var GRADE_THRESHOLDS = [
+  [97, "A+"],
+  [93, "A"],
+  [90, "A-"],
+  [87, "B+"],
+  [83, "B"],
+  [80, "B-"],
+  [77, "C+"],
+  [73, "C"],
+  [70, "C-"],
+  [67, "D+"],
+  [63, "D"],
+  [60, "D-"],
+  [0, "F"]
+];
+function gradeSession(session) {
+  const metrics = [];
+  let weightedSum = 0;
+  let totalWeight = 0;
+  for (const mw of METRIC_WEIGHTS) {
+    const result = mw.compute(session);
+    metrics.push(result);
+    if (result.value !== null) {
+      weightedSum += mw.score(result.value) * mw.weight;
+      totalWeight += mw.weight;
+    }
+  }
+  const compositeScore = totalWeight > 0 ? weightedSum / totalWeight : 0;
+  const letter = GRADE_THRESHOLDS.find(([threshold]) => compositeScore >= threshold)?.[1] ?? "F";
+  return {
+    letter,
+    score: Math.round(compositeScore),
+    metrics
+  };
+}
+function clamp(value, min, max) {
+  return Math.max(min, Math.min(max, value));
+}
+
+// src/reporter/terminal.ts
+import chalk from "chalk";
+import Table from "cli-table3";
+
+// src/utils/format.ts
+function formatDuration(ms) {
+  const seconds = Math.floor(ms / 1e3);
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes} min`;
+  const hours = Math.floor(minutes / 60);
+  const remainingMinutes = minutes % 60;
+  if (remainingMinutes === 0) return `${hours}h`;
+  return `${hours}h ${remainingMinutes}m`;
+}
+function shortSessionId(id) {
+  return id.slice(0, 8);
+}
+function projectNameFromSlug(slug) {
+  const parts = slug.split("-").filter(Boolean);
+  return parts[parts.length - 1] || slug;
+}
+
+// src/reporter/tips.ts
+var TIPS = {
+  "reads-per-edit": {
+    warning: "Claude is editing with less context. Add 'Always read files before editing' to your CLAUDE.md.",
+    critical: "Very low reads before edits. Claude is making blind changes. Consider adding explicit read instructions."
+  },
+  "rewrite-ratio": {
+    warning: "High ratio of full-file rewrites. Add 'Prefer Edit over Write for existing files' to CLAUDE.md.",
+    critical: "Claude is rewriting entire files instead of making surgical edits. This wastes tokens and risks data loss."
+  },
+  "cache-hit-rate": {
+    warning: "Cache hit rate is below normal. Sessions may be too short for caching to help.",
+    critical: "Very low cache hit rate \u2014 possible cache bug. Try restarting Claude Code or downgrading to a previous version."
+  },
+  "task-completion": {
+    warning: "Claude is occasionally promising actions without following through.",
+    critical: "Frequent unfulfilled promises. Claude says it will do things but doesn't. Try breaking tasks into smaller steps."
+  },
+  "retry-density": {
+    warning: "Some user messages look like retries. Claude may be misunderstanding requests.",
+    critical: "High retry rate. Users are frequently re-asking. Consider providing more context in prompts."
+  },
+  "tool-diversity": {
+    warning: "Low tool diversity. Claude is over-relying on a narrow set of tools.",
+    critical: "Very narrow tool usage. Claude may be stuck in a pattern. Try prompting for specific tool usage."
+  },
+  "tokens-per-edit": {
+    warning: "Tokens per edit is above average. Claude may be verbose without being productive.",
+    critical: "Very high token cost per edit. Claude is burning tokens without proportional output."
+  }
+};
+function getTip(metric) {
+  if (metric.status === "healthy") return null;
+  const metricTips = TIPS[metric.name];
+  if (!metricTips) return null;
+  return metricTips[metric.status] ?? null;
+}
+function getAllTips(metrics) {
+  return metrics.map(getTip).filter((tip) => tip !== null);
+}
+
+// src/reporter/terminal.ts
+var STATUS_ICONS = {
+  healthy: chalk.green("\u2713"),
+  warning: chalk.yellow("\u26A0"),
+  critical: chalk.red("\u2717")
+};
+var STATUS_LABELS = {
+  healthy: chalk.green("healthy"),
+  warning: chalk.yellow("warning"),
+  critical: chalk.red("critical")
+};
+var METRIC_DISPLAY_NAMES = {
+  "reads-per-edit": "Reads/edit",
+  "rewrite-ratio": "Rewrite ratio",
+  "cache-hit-rate": "Cache hit rate",
+  "task-completion": "Task completion",
+  "retry-density": "Retry density",
+  "tool-diversity": "Tool diversity",
+  "tokens-per-edit": "Tokens/useful-edit"
+};
+function renderAuditReport(session, grade) {
+  const lines = [];
+  lines.push("");
+  lines.push(chalk.bold("  cc-audit v1.0.0") + chalk.dim(" \u2014 Claude Code Session Quality Analyzer"));
+  lines.push("");
+  const sessionInfo = [
+    `Session: ${chalk.cyan(shortSessionId(session.id))}`,
+    projectNameFromSlug(session.projectSlug),
+    formatDuration(session.durationMs),
+    session.model
+  ].join(chalk.dim(" | "));
+  lines.push(`  ${sessionInfo}`);
+  lines.push("");
+  const gradeColor = getGradeColor(grade.letter);
+  lines.push(`  Overall grade: ${gradeColor(chalk.bold(grade.letter))}`);
+  lines.push("");
+  const table = new Table({
+    head: ["Metric", "Value", "Status"].map((h) => chalk.dim(h)),
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  for (const metric of grade.metrics) {
+    const displayName = METRIC_DISPLAY_NAMES[metric.name] ?? metric.name;
+    const icon = STATUS_ICONS[metric.status] ?? "";
+    table.push([displayName, metric.label, `${icon} ${STATUS_LABELS[metric.status] ?? metric.status}`]);
+  }
+  lines.push(table.toString());
+  const tips = getAllTips(grade.metrics);
+  if (tips.length > 0) {
+    lines.push("");
+    lines.push(chalk.yellow("  Tips:"));
+    for (const tip of tips) {
+      lines.push(`  ${chalk.dim("\u2192")} ${tip}`);
+    }
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function renderTrendReport(results, sessionCount, period) {
+  const lines = [];
+  lines.push("");
+  lines.push(chalk.bold(`  Trend report: last ${period}`) + chalk.dim(` (${sessionCount} sessions)`));
+  lines.push("");
+  const table = new Table({
+    head: ["Metric", "Recent avg", "Full avg", "Change", "Status"].map((h) => chalk.dim(h)),
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  for (const result of results) {
+    const displayName = METRIC_DISPLAY_NAMES[result.name] ?? result.name;
+    const recentStr = result.recentAvg !== null ? result.recentAvg.toFixed(2) : "N/A";
+    const fullStr = result.fullAvg !== null ? result.fullAvg.toFixed(2) : "N/A";
+    let changeStr = "N/A";
+    if (result.changePercent !== null) {
+      const arrow = result.changePercent > 0 ? "\u25B2" : result.changePercent < 0 ? "\u25BC" : "";
+      changeStr = `${arrow} ${Math.abs(Math.round(result.changePercent))}%`;
+    }
+    const statusStr = formatRegressionStatus(result.status);
+    table.push([displayName, recentStr, fullStr, changeStr, statusStr]);
+  }
+  lines.push(table.toString());
+  lines.push("");
+  return lines.join("\n");
+}
+function renderCacheCheckReport(results) {
+  const lines = [];
+  lines.push("");
+  lines.push(chalk.bold("  Cache health check"));
+  lines.push("");
+  const table = new Table({
+    head: ["Session", "Project", "Cache Hit", "Status"].map((h) => chalk.dim(h)),
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  for (const result of results) {
+    const hitStr = result.cacheHitRate !== null ? result.cacheHitRate.toFixed(2) : "N/A";
+    const statusStr = result.isAnomaly ? chalk.red("\u2717 ANOMALY") : chalk.green("\u2713 normal");
+    table.push([
+      shortSessionId(result.sessionId),
+      projectNameFromSlug(result.projectSlug),
+      hitStr,
+      statusStr
+    ]);
+  }
+  lines.push(table.toString());
+  const anomalies = results.filter((r) => r.isAnomaly);
+  if (anomalies.length > 0) {
+    lines.push("");
+    lines.push(
+      chalk.yellow(`  \u26A0 ${anomalies.length} session(s) with abnormally low cache hit rate.`)
+    );
+    for (const a of anomalies) {
+      if (a.estimatedInflation) {
+        lines.push(
+          `  ${chalk.dim("\u2192")} Session ${shortSessionId(a.sessionId)} consumed ~${a.estimatedInflation}x more input tokens than expected.`
+        );
+      }
+    }
+    lines.push(
+      chalk.dim("  Try: restart Claude Code or downgrade to a previous version.")
+    );
+  } else {
+    lines.push("");
+    lines.push(chalk.green("  \u2713 No cache anomalies detected."));
+  }
+  lines.push("");
+  return lines.join("\n");
+}
+function getGradeColor(letter) {
+  if (letter.startsWith("A")) return chalk.green;
+  if (letter.startsWith("B")) return chalk.cyan;
+  if (letter.startsWith("C")) return chalk.yellow;
+  return chalk.red;
+}
+function formatRegressionStatus(status) {
+  switch (status) {
+    case "stable":
+      return chalk.green("\u2713 stable");
+    case "declining":
+      return chalk.yellow("\u26A0 declining");
+    case "regression":
+      return chalk.red("\u26A0 REGRESSION");
+    default:
+      return status;
+  }
+}
+
+// src/reporter/json-reporter.ts
+function formatAuditJson(session, grade) {
+  const output = {
+    session: {
+      id: session.id,
+      project: session.projectSlug,
+      model: session.model,
+      durationMs: session.durationMs,
+      startTime: session.startTime
+    },
+    grade: grade.letter,
+    score: grade.score,
+    metrics: grade.metrics.map((m) => ({
+      name: m.name,
+      value: m.value,
+      status: m.status,
+      label: m.label
+    }))
+  };
+  return JSON.stringify(output, null, 2);
+}
+function formatTrendJson(results) {
+  return JSON.stringify({ trend: results }, null, 2);
+}
+function formatCacheCheckJson(results) {
+  return JSON.stringify({ cacheCheck: results }, null, 2);
+}
+
+// src/commands/audit.ts
+async function runAudit(options) {
+  const sessionFile = await getMostRecentSession({
+    dataDir: options.dataDir,
+    project: options.project
+  });
+  const records = readJsonl(sessionFile.path);
+  const session = await buildSession(
+    records,
+    sessionFile.sessionId,
+    sessionFile.projectSlug
+  );
+  const grade = gradeSession(session);
+  if (options.json) {
+    console.log(formatAuditJson(session, grade));
+  } else {
+    console.log(renderAuditReport(session, grade));
+  }
+}
+
+// src/anomaly/baseline.ts
+function computeBaselines(grades, recentCount) {
+  if (grades.length === 0) return [];
+  const recent = grades.slice(0, recentCount);
+  const full = grades;
+  const metricNames = grades[0].metrics.map((m) => m.name);
+  return metricNames.map((name) => {
+    const recentValues = extractValues(recent, name);
+    const fullValues = extractValues(full, name);
+    const recentAvg = average(recentValues);
+    const fullAvg = average(fullValues);
+    let changePercent = null;
+    if (recentAvg !== null && fullAvg !== null && fullAvg !== 0) {
+      changePercent = (recentAvg - fullAvg) / Math.abs(fullAvg) * 100;
+    }
+    return { name, recentAvg, fullAvg, changePercent };
+  });
+}
+function extractValues(grades, metricName) {
+  const values = [];
+  for (const grade of grades) {
+    const metric = grade.metrics.find((m) => m.name === metricName);
+    if (metric?.value !== null && metric?.value !== void 0) {
+      values.push(metric.value);
+    }
+  }
+  return values;
+}
+function average(values) {
+  if (values.length === 0) return null;
+  return values.reduce((a, b) => a + b, 0) / values.length;
+}
+
+// src/anomaly/regression-detector.ts
+var INVERTED_METRICS = /* @__PURE__ */ new Set([
+  "rewrite-ratio",
+  "retry-density",
+  "tokens-per-edit"
+]);
+function detectRegressions(baselines) {
+  return baselines.map((b) => {
+    let status = "stable";
+    if (b.changePercent !== null) {
+      const isInverted = INVERTED_METRICS.has(b.name);
+      const badDirection = isInverted ? b.changePercent > 0 : b.changePercent < 0;
+      const magnitude = Math.abs(b.changePercent);
+      if (badDirection && magnitude > 30) {
+        status = "regression";
+      } else if (badDirection && magnitude > 10) {
+        status = "declining";
+      }
+    }
+    return {
+      name: b.name,
+      recentAvg: b.recentAvg,
+      fullAvg: b.fullAvg,
+      changePercent: b.changePercent,
+      status
+    };
+  });
+}
+
+// src/utils/duration.ts
+function parseDuration(duration, now = /* @__PURE__ */ new Date()) {
+  const match = duration.match(/^(\d+)d$/);
+  if (!match) {
+    throw new Error(
+      `Invalid duration: "${duration}". Use format like "7d", "14d", "30d".`
+    );
+  }
+  const days = parseInt(match[1], 10);
+  const result = new Date(now);
+  result.setDate(result.getDate() - days);
+  return result;
+}
+
+// src/commands/trend.ts
+async function runTrend(options) {
+  const duration = options.since ?? "7d";
+  const sinceDate = parseDuration(duration);
+  const sessionFiles = await scanSessions({
+    dataDir: options.dataDir,
+    project: options.project,
+    since: sinceDate
+  });
+  if (sessionFiles.length === 0) {
+    console.log(`No sessions found in the last ${duration}.`);
+    return;
+  }
+  const grades = [];
+  for (const sf of sessionFiles) {
+    try {
+      const records = readJsonl(sf.path);
+      const session = await buildSession(records, sf.sessionId, sf.projectSlug);
+      grades.push(gradeSession(session));
+    } catch {
+    }
+  }
+  if (grades.length === 0) {
+    console.log("No valid sessions found to analyze.");
+    return;
+  }
+  const recentCount = Math.max(1, Math.floor(grades.length / 2));
+  const baselines = computeBaselines(grades, recentCount);
+  const regressions = detectRegressions(baselines);
+  if (options.json) {
+    console.log(formatTrendJson(regressions));
+  } else {
+    console.log(renderTrendReport(regressions, grades.length, duration));
+  }
+}
+
+// src/anomaly/cache-anomaly.ts
+var ANOMALY_THRESHOLD = 0.05;
+var NORMAL_CACHE_RATE = 0.65;
+function checkCacheAnomaly(session) {
+  const metric = computeCacheHitRate(session);
+  const isAnomaly = metric.value !== null && metric.value < ANOMALY_THRESHOLD;
+  let estimatedInflation = null;
+  if (isAnomaly && metric.value !== null) {
+    estimatedInflation = Math.round(1 / (1 - NORMAL_CACHE_RATE));
+  }
+  return {
+    sessionId: session.id,
+    projectSlug: session.projectSlug,
+    timestamp: session.startTime,
+    cacheHitRate: metric.value,
+    isAnomaly,
+    estimatedInflation
+  };
+}
+
+// src/commands/cache-check.ts
+async function runCacheCheck(options) {
+  const duration = options.since ?? "7d";
+  const sinceDate = parseDuration(duration);
+  const sessionFiles = await scanSessions({
+    dataDir: options.dataDir,
+    since: sinceDate
+  });
+  if (sessionFiles.length === 0) {
+    console.log(`No sessions found in the last ${duration}.`);
+    return;
+  }
+  const results = [];
+  for (const sf of sessionFiles) {
+    try {
+      const records = readJsonl(sf.path);
+      const session = await buildSession(records, sf.sessionId, sf.projectSlug);
+      results.push(checkCacheAnomaly(session));
+    } catch {
+    }
+  }
+  if (results.length === 0) {
+    console.log("No valid sessions found to analyze.");
+    return;
+  }
+  if (options.json) {
+    console.log(formatCacheCheckJson(results));
+  } else {
+    console.log(renderCacheCheckReport(results));
+  }
+}
+
+// src/commands/compare.ts
+import chalk2 from "chalk";
+import Table2 from "cli-table3";
+async function runCompare(options) {
+  const projectNames = options.projects.split(",").map((p) => p.trim());
+  const summaries = [];
+  for (const projectFilter of projectNames) {
+    const sessionFiles = await scanSessions({
+      dataDir: options.dataDir,
+      project: projectFilter
+    });
+    if (sessionFiles.length === 0) continue;
+    const grades = [];
+    for (const sf of sessionFiles) {
+      try {
+        const records = readJsonl(sf.path);
+        const session = await buildSession(records, sf.sessionId, sf.projectSlug);
+        grades.push(gradeSession(session));
+      } catch {
+        continue;
+      }
+    }
+    if (grades.length === 0) continue;
+    const avgScore = grades.reduce((s, g) => s + g.score, 0) / grades.length;
+    const metricAvgs = /* @__PURE__ */ new Map();
+    for (const metric of grades[0].metrics) {
+      const values = grades.map((g) => g.metrics.find((m) => m.name === metric.name)?.value).filter((v) => v !== null);
+      if (values.length > 0) {
+        metricAvgs.set(metric.name, values.reduce((a, b) => a + b, 0) / values.length);
+      }
+    }
+    summaries.push({
+      name: projectFilter,
+      sessionCount: grades.length,
+      avgGrade: Math.round(avgScore),
+      avgLetter: getLetterGrade(avgScore),
+      metrics: metricAvgs
+    });
+  }
+  if (summaries.length === 0) {
+    console.log("No matching projects found.");
+    return;
+  }
+  if (options.json) {
+    const jsonOutput = summaries.map((s) => ({
+      project: s.name,
+      sessions: s.sessionCount,
+      grade: s.avgLetter,
+      score: s.avgGrade,
+      metrics: Object.fromEntries(s.metrics)
+    }));
+    console.log(JSON.stringify({ compare: jsonOutput }, null, 2));
+    return;
+  }
+  const lines = [];
+  lines.push("");
+  lines.push(chalk2.bold("  Project comparison"));
+  lines.push("");
+  const head = ["Project", "Sessions", "Grade", ...summaries[0]?.metrics.keys() ?? []].map(
+    (h) => chalk2.dim(h)
+  );
+  const table = new Table2({
+    head,
+    style: { head: [], border: [], "padding-left": 2, "padding-right": 2 },
+    chars: {
+      top: "\u2500",
+      "top-mid": "\u2500",
+      "top-left": "  ",
+      "top-right": "",
+      bottom: "\u2500",
+      "bottom-mid": "\u2500",
+      "bottom-left": "  ",
+      "bottom-right": "",
+      left: "  ",
+      "left-mid": "  ",
+      mid: "\u2500",
+      "mid-mid": "\u2500",
+      right: "",
+      "right-mid": "",
+      middle: "  "
+    }
+  });
+  for (const summary of summaries) {
+    const row = [
+      summary.name,
+      summary.sessionCount.toString(),
+      summary.avgLetter
+    ];
+    for (const [, value] of summary.metrics) {
+      row.push(value.toFixed(2));
+    }
+    table.push(row);
+  }
+  lines.push(table.toString());
+  lines.push("");
+  console.log(lines.join("\n"));
+}
+function getLetterGrade(score) {
+  if (score >= 97) return "A+";
+  if (score >= 93) return "A";
+  if (score >= 90) return "A-";
+  if (score >= 87) return "B+";
+  if (score >= 83) return "B";
+  if (score >= 80) return "B-";
+  if (score >= 77) return "C+";
+  if (score >= 73) return "C";
+  if (score >= 70) return "C-";
+  if (score >= 67) return "D+";
+  if (score >= 63) return "D";
+  if (score >= 60) return "D-";
+  return "F";
+}
+
+// src/index.ts
+var program = new Command();
+program.name("cc-audit").description("Claude Code session quality analyzer \u2014 grade sessions, detect regressions, catch cache bugs").version("1.0.0");
+program.command("audit", { isDefault: true }).description("Grade the most recent Claude Code session").option("--json", "Output as JSON").option("--verbose", "Show per-message breakdown").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").action(async (options) => {
+  try {
+    await runAudit(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("trend").description("Analyze quality trends and detect regressions over time").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--project <name>", "Filter to a specific project").action(async (options) => {
+  try {
+    await runTrend(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("cache-check").description("Detect prompt cache bugs that inflate token costs").option("--since <duration>", "Time range: 7d, 14d, 30d", "7d").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").action(async (options) => {
+  try {
+    await runCacheCheck(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+program.command("compare").description("Compare quality metrics across projects").requiredOption("--projects <names>", "Comma-separated project names").option("--json", "Output as JSON").option("--data-dir <path>", "Custom Claude data directory").option("--since <duration>", "Time range: 7d, 14d, 30d").action(async (options) => {
+  try {
+    await runCompare(options);
+  } catch (error) {
+    handleError(error);
+  }
+});
+function handleError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`
+Error: ${message}
+`);
+  process.exit(1);
+}
+program.parse();
+//# sourceMappingURL=index.js.map