Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

22.4 KB
Raw Blame
/**
 * Canonical chat types: conversation, messages, the SSE event union, and the
 * discriminated-union `ChatArtifact` the transcript renders tool results as.
 *
 * Artifact `data` shapes are the raw MCP tool results passed through the
 * server envelope, so they stay convenience-shaped rather than strict engine
 * records. Mirrored by `packages/server/src/repowise/server/schemas/chat.py`.
 */

import type { GraphExport } from "./graph.js";
import type { Hotspot } from "./git.js";
import type { DeadCodeFinding } from "./dead-code.js";
import type { DecisionRecord } from "./decisions.js";
import type { CardRef, EvidenceCard } from "./cards.js";
import type { ViewPart } from "./views.js";
import type { ChatFigure } from "./generated/http.js";

/** Headless chat session wire types, generated from the server schema. */
export type {
  ChatFigure,
  ChatSessionMessageRequest,
  ChatSessionOpenRequest,
  ChatSessionPolicyRequest,
  ChatSessionResponse,
  ChatToolTraceEntry,
  ChatTurnResultResponse,
  ChatTurnUsage,
} from "./generated/http.js";

// ---------------------------------------------------------------------------
// Product context surrounding a chat composer
// ---------------------------------------------------------------------------

export type ChatContextKind =
  | "repository"
  | "overview"
  | "documentation"
  | "architecture"
  | "graph"
  | "health"
  | "refactoring"
  | "file"
  | "symbol"
  | "module"
  | "commit"
  | "contributor"
  | "decision"
  | "risk"
  | "dead-code"
  | "blast-radius"
  | "security"
  | "usage"
  | "settings"
  | "chat";

export type ChatContextTargetKind =
  | "path"
  | "symbol"
  | "module"
  | "dependency"
  | "commit"
  | "person"
  | "decision"
  | "documentation";

/** Portable navigation context supplied by a product host for one chat turn. */
export interface ChatContext {
  kind: ChatContextKind;
  label: string;
  target?: string;
  targetKind?: ChatContextTargetKind;
}

/** A passage the reader highlighted on the page, carried into the composer. */
export interface ChatSelection {
  text: string;
  path?: string;
  startLine?: number;
  endLine?: number;
}

/** What a page hands to chat when the reader asks about the thing in front of
 *  them. `autoSend` skips the composer and asks immediately. */
export interface ChatHandoff {
  context: ChatContext;
  question?: string;
  selection?: ChatSelection;
  autoSend?: boolean;
}

/** Where a composer chip came from, so ranking and telemetry can tell the
 *  static fallback tier apart from one derived from live page data. */
export type ChatSuggestionSource = "static" | "page" | "followup";

export interface ChatSuggestion {
  text: string;
  source: ChatSuggestionSource;
  toolHint?: string;
}

// ---------------------------------------------------------------------------
// Conversations + messages
// ---------------------------------------------------------------------------

export interface Conversation {
  id: string;
  repository_id: string;
  title: string;
  message_count: number;
  pinned?: boolean;
  created_at: string;
  updated_at: string;
}

/** Who made a tool call: the model, or the server reading for the page. */
export type ChatToolCallOrigin = "grounding";

export interface ChatToolCall {
  id: string;
  name: string;
  arguments?: Record<string, unknown>;
  result?: Record<string, unknown>;
  summary?: string;
  artifact_type?: string;
  artifact?: ChatArtifact;
  origin?: ChatToolCallOrigin;
}

export interface ChatMessage {
  id: string;
  conversation_id: string;
  role: "user" | "assistant";
  content: {
    text?: string;
    tool_calls?: ChatToolCall[];
    provider?: string;
    model?: string;
    /** The step ceiling was reached before a final answer. */
    truncated?: boolean;
    /** Next steps derived from the artifacts this turn produced. */
    follow_ups?: ChatSuggestion[];
    /** Evidence cards for this turn, unvalidated until parsed. */
    cards?: unknown[];
    /** View parts `show_view` built this turn, unvalidated until parsed. */
    views?: unknown[];
    /** Each number the answer states, looked up in the turn's tool results. */
    figures?: ChatFigure[];
    diagnostics?: {
      figures_checked?: number;
      figures_unverified?: number;
      /** Verified figures worked out from others (a ratio or a sum) rather than read. */
      figures_derived?: number;
      /** Figures left unchecked because the evidence was past the read cap. */
      figures_not_checked?: number;
    };
  };
  created_at: string;
}

// ---------------------------------------------------------------------------
// UI-flattened message shape (consumed by chat presentation components)
// ---------------------------------------------------------------------------

export interface ChatUIToolCall {
  id: string;
  name: string;
  arguments: Record<string, unknown>;
  result?: Record<string, unknown>;
  summary?: string;
  artifact?: ChatArtifact;
  status: "running" | "done" | "error";
  origin?: ChatToolCallOrigin;
}

export interface ChatUIMessage {
  id: string;
  serverId?: string;
  role: "user" | "assistant";
  text: string;
  toolCalls: ChatUIToolCall[];
  isStreaming: boolean;
  /** Provenance recorded on assistant responses. */
  provider?: string;
  model?: string;
  /** The step ceiling was reached before a final answer. */
  truncated?: boolean;
  /** Next steps this turn earned. Absent on a turn that called no tool. */
  followUps?: ChatSuggestion[];
  /** Validated evidence cards for this turn. */
  cards?: EvidenceCard[];
  /** Validated view parts for this turn, in the order they were built. */
  views?: ViewPart[];
  /** Figures in `text` no tool result of the turn holds; flagged, not removed. */
  unverifiedFigures?: ChatFigureSpan[];
}

/** A figure's place in the text a message shows, in UTF-16 offsets. */
export interface ChatFigureSpan {
  text: string;
  start: number;
  end: number;
}

// ---------------------------------------------------------------------------
// Tool-result artifacts (discriminated union)
// ---------------------------------------------------------------------------

/**
 * Common citation surface emitted alongside any artifact when the tool
 * referenced specific files/symbols. Drives `chat/source-citation.tsx`.
 */
export interface ChatCitation {
  file_path: string;
  symbol_name?: string;
  start_line?: number;
  end_line?: number;
  /** The tool result that cited this file. */
  artifact_id?: string;
  /** The file or symbol as an entity ref, resolved like a card's. */
  ref?: CardRef;
}

export interface ArtifactEvidence {
  basis: "measured" | "inferred" | "unknown" | string;
  confidence?: number | string;
  coverage?: unknown;
  limits?: Record<string, unknown>;
  truncated?: boolean;
  stale?: string;
}

export interface ArtifactEnvelopeIdentity {
  id: string;
  version: 1;
  tool_name: string;
  title?: string;
  presentation: string;
  evidence?: ArtifactEvidence;
  pinned?: boolean;
  created_at?: string;
}

/** `get_overview` — repository fact sheet. */
export interface OverviewArtifactData {
  total_files: number;
  total_symbols: number;
  languages: Record<string, number>;
  modules: string[];
  entry_points: string[];
  hotspot_count: number;
  git_summary?: Record<string, unknown> | null;
  is_monorepo: boolean;
}
export interface OverviewArtifact extends ArtifactEnvelopeIdentity {
  type: "overview";
  data: OverviewArtifactData;
}

/** `get_context` — per-target wiki snippet + git/decision context. */
export interface ContextArtifactData {
  targets: Record<
    string,
    {
      docs?: { content_md?: string; title?: string; page_type?: string; page_id?: string } | null;
      hotspot_info?: Record<string, unknown> | null;
      decisions?: Array<Record<string, unknown>>;
      [k: string]: unknown;
    }
  >;
}
export interface ContextArtifact extends ArtifactEnvelopeIdentity {
  type: "context";
  data: ContextArtifactData;
}

/** `get_risk` / `get_change_risk` — modification or commit-range risk report. */
export interface RiskTargetRow {
  /** Path key; optional on MCP dict values that use `target` instead. */
  file_path?: string;
  /** MCP per-target id when `targets` is a path-keyed object. */
  target?: string;
  /**
   * MCP `get_risk` hotspot score: a 0–1 fraction from
   * `GitMetadata.churn_percentile` (rank / total), not 0–100.
   */
  hotspot_score?: number;
  /** Same 0–1 fraction as `hotspot_score` (legacy fixture field name). */
  churn_percentile?: number;
  is_hotspot?: boolean;
  risk_type?: string;
  trend?: string;
  risk_summary?: string;
  [k: string]: unknown;
}

export interface RiskReportArtifactData {
  /**
   * MCP `get_risk` returns a path-keyed object; legacy fixtures used an array.
   * Renderers normalize either shape.
   */
  targets?: RiskTargetRow[] | Record<string, RiskTargetRow>;
  global_hotspots?: Array<{
    /** MCP wire. */
    file_path?: string;
    hotspot_score?: number;
    /** Legacy chat fixture. */
    path?: string;
    churn_percentile?: number;
  }>;
  /** `get_change_risk` live-git payload fields. */
  ref?: string;
  score?: number;
  risk_percentile?: number | null;
  review_priority?: string;
  classification?: string;
  warning?: string;
  error?: string;
  /** `nothing_to_score` when the change has no counted files. */
  status?: string;
  /** True when uncommitted work was scored; false when a clean tree fell back to `HEAD`. */
  working_tree?: boolean;
  /** `get_change_risk` action-first blocks. */
  directive?: ChangeRiskDirective;
  health_delta?: ChangeHealthDeltaData;
  /** One line on diff size and spread; never a danger verdict. */
  diff_shape?: string;
  independent_changes?: {
    count?: number;
    summary?: string;
    basis?: string;
    ungrouped_files?: string[];
    groups?: Array<{ files: string[]; bridging_files?: string[] }>;
    [k: string]: unknown;
  };
  impacted_tests?: {
    tests_to_run?: string[];
    /** `selected`, `run_all`, or why nothing was selected (`no_index`, `timeout`, ...). */
    status?: string;
    /** No subset can be vouched for: every test must run (`reasons` says why). */
    run_all?: boolean;
    reasons?: string[];
    summary?: string;
    /** `measured` from stored coverage, `inferred` from the dependency graph. */
    basis?: "measured" | "inferred" | "none";
    /** Test ids, or whole test files when inferred. */
    tests_to_run_kind?: "test_id" | "test_file" | null;
    total?: number;
    truncated?: boolean;
  };
  /** Bug-fix record of the touched files: the "historically fragile" signal. */
  fix_history?: {
    available?: boolean;
    files?: Array<{ path: string; churn: number; fix_pressure: number }>;
    overlap?: { files_with_fixes?: number; total_fixes?: number };
  };
  /** Other open branches editing the files this change edits. */
  branch_overlap?: {
    base?: string;
    current?: string;
    scanned?: number;
    total?: number;
    truncated?: boolean;
    summary?: string;
    branches?: Array<{
      branch: string;
      ahead?: number;
      behind?: number;
      last_commit?: string;
      files?: Array<{ file: string; basis: string; partner?: string }>;
      [k: string]: unknown;
    }>;
    [k: string]: unknown;
  };
  [k: string]: unknown;
}

/** What the change did to the codebase's health, and how sure the tool is. */
export interface ChangeFindingRow {
  id: string;
  change: "introduced" | "worsened";
  dimension: "defect" | "maintainability" | "performance";
  biomarker: string;
  severity: "low" | "medium" | "high" | "critical";
  path: string;
  reason: string;
  attribution: { basis: string; confidence: "high" | "medium" | "low"; why: string };
  symbol?: string;
  lines?: [number, number];
  severity_before?: string;
  suggestion?: string;
  opportunity_id?: string;
  opportunity_rank?: number;
  inspect?: string;
}

export interface ChangeHealthDeltaData {
  /** `partial` and `unavailable` must never render as a clean result. */
  status:
    | "available"
    | "partial"
    | "unavailable"
    | "unsupported_range"
    | "too_large"
    | "timeout"
    | "analyzer_mismatch"
    | "rules_mismatch"
    | "stale_baseline";
  explanation: string;
  /**
   * How the two sides were compared, e.g. `both_sides_analyzed` /
   * `not_compared`. Open on the wire: the producer types it as a plain string.
   */
  basis: string;
  introduced: number;
  worsened: number;
  resolved: number;
  top_findings: ChangeFindingRow[];
  findings_total: number;
  findings_emitted: number;
  by_dimension?: Record<string, number>;
  by_severity?: Record<string, number>;
  scope?: { changed: number; eligible: number; analyzed: number; skipped: number; failed: number };
  skipped?: { total: number; by_reason: Record<string, number> };
  base?: { ref: string; sha: string; kind: string };
  head?: { ref: string; sha: string; kind: string };
  limits?: string[];
}

export interface ChangeRiskDirective {
  status: "review_required" | "review_recommended" | "clear_in_analyzed_scope" | "unknown";
  headline: string;
  reasons?: string[];
  next_actions?: string[];
}
export interface RiskReportArtifact extends ArtifactEnvelopeIdentity {
  type: "risk_report";
  data: RiskReportArtifactData;
}
export interface RiskArtifact extends ArtifactEnvelopeIdentity {
  type: "risk";
  data: RiskReportArtifactData;
}
export interface ChangeRiskArtifact extends ArtifactEnvelopeIdentity {
  type: "change_risk";
  data: RiskReportArtifactData;
}

/** `search_codebase` — wiki page hits. */
export interface SearchResultsArtifactData {
  query: string;
  results: Array<{
    /** Omitted when it only restates `path`/`symbol_id` (a structural title). */
    title?: string;
    page_type: string;
    page_id?: string;
    /** Openable repo-relative file; absent when the hit names no file. */
    path?: string;
    /** `path::Symbol` on a symbol page. */
    symbol_id?: string;
    /** Kept only where it differs from `path` or `path` is absent. */
    target_path?: string;
    snippet?: string;
    relevance_score?: number;
  }>;
}
export interface SearchResultsArtifact extends ArtifactEnvelopeIdentity {
  type: "search_results";
  data: SearchResultsArtifactData;
}

/**
 * Legacy wire shape from the removed chat tool `get_dependency_path`.
 * Retained so stored conversations / SSE history still narrow; not emitted
 * by the current 7-tool chat registry (MCP still offers it as opt-in).
 */
export interface GraphPathArtifactData {
  path: string[];
  distance: number;
  explanation: string;
}
export interface GraphPathArtifact extends ArtifactEnvelopeIdentity {
  type: "graph";
  data: GraphPathArtifactData;
}
export interface DependencyPathArtifact extends ArtifactEnvelopeIdentity {
  type: "dependency_path";
  data: Record<string, unknown>;
}
export interface CallPathArtifact extends ArtifactEnvelopeIdentity {
  type: "call_path";
  data: Record<string, unknown>;
}
export interface SourceArtifact extends ArtifactEnvelopeIdentity {
  type: "source";
  data: Record<string, unknown>;
}
export interface HealthArtifact extends ArtifactEnvelopeIdentity {
  type: "health";
  data: Record<string, unknown>;
}

/** `get_why` — decision register search / path lookup / health dashboard. */
export interface DecisionsArtifactData {
  mode: "health" | "search" | "path";
  query?: string;
  path?: string;
  summary?: string;
  /** Health mode: counters from `get_decision_health_summary`. */
  counts?: Record<string, number>;
  /** @deprecated Legacy chat fixture field; prefer `counts`. */
  total_decisions?: number;
  /** @deprecated Legacy chat fixture field; unused by MCP wire format. */
  by_source?: Record<string, number>;
  stale_decisions?: Array<{
    title: string;
    status?: string;
    affected_files?: string[];
    staleness_score?: number;
  }>;
  proposed_awaiting_review?: Array<{
    title: string;
    source?: string;
    confidence?: number;
  }>;
  ungoverned_hotspots?: Array<string | { file_path?: string; path?: string }>;
  /** Search/path mode: governing or matched decisions (MCP wire). */
  decisions?: Array<{
    title: string;
    status?: string;
    decision?: string;
    rationale?: string;
    affected_files?: string[];
  }>;
  /**
   * @deprecated Legacy chat fixture shape. MCP search/path return `decisions`.
   * Renderers still accept this for stored conversations.
   */
  results?: Array<{
    title: string;
    decision: string;
    rationale?: string;
    affected_files?: string[];
  }>;
  origin_story?: {
    first_commit?: { date?: string; author?: string; message?: string };
    primary_author?: string;
    [k: string]: unknown;
  };
  alignment?: {
    score?: number;
    label?: string;
    summary?: string;
    [k: string]: unknown;
  };
}
export interface DecisionsArtifact extends ArtifactEnvelopeIdentity {
  type: "decisions";
  data: DecisionsArtifactData;
}

/** One finding inside a `get_dead_code` tier. */
export interface DeadCodeArtifactFinding {
  file_path: string;
  symbol_name?: string | null;
  kind: string;
  confidence: number;
  reason: string;
  lines: number | null;
  safe_to_delete: boolean;
}

/** One confidence tier of a `get_dead_code` result. */
export interface DeadCodeArtifactTier {
  count: number;
  findings: DeadCodeArtifactFinding[];
  truncated: boolean;
}

/**
 * `get_dead_code`: confidence-tiered dead-code findings. Totals sit in
 * `summary`; a `tier` argument drops the tiers it did not ask for.
 */
export interface DeadCodeArtifactTiers {
  mode?: undefined;
  summary: {
    total_findings: number;
    deletable_lines: number;
  };
  tiers: Partial<Record<"high" | "medium" | "low", DeadCodeArtifactTier>>;
}

/** `get_dead_code(finding_id=...)`: one finding, or none when the id is unknown. */
export interface DeadCodeArtifactLookup {
  mode: "finding";
  finding_id: string;
  finding: DeadCodeArtifactFinding | null;
  resolved: boolean;
}

export type DeadCodeArtifactData = DeadCodeArtifactTiers | DeadCodeArtifactLookup;
export interface DeadCodeArtifact extends ArtifactEnvelopeIdentity {
  type: "dead_code";
  data: DeadCodeArtifactData;
}

/**
 * Legacy wire shape from the removed chat tool `get_architecture_diagram`.
 * Retained for historical SSE payloads; current chat does not emit `diagram`.
 */
export interface DiagramArtifactData {
  diagram_type: string;
  mermaid_syntax: string;
  description?: string;
}
export interface DiagramArtifact extends ArtifactEnvelopeIdentity {
  type: "diagram";
  data: DiagramArtifactData;
}

/**
 * Fallback for tools that haven't yet been promoted to a typed variant.
 * The renderer falls back to JSON pretty-print for this case.
 */
export interface GenericArtifact extends ArtifactEnvelopeIdentity {
  type: string;
  data: Record<string, unknown>;
}

/** Future variants — declared for the type system, not yet emitted on the wire. */
export interface HotspotArtifact extends ArtifactEnvelopeIdentity {
  type: "hotspot";
  data: { hotspots: Hotspot[] };
}
export interface AnswerArtifact extends ArtifactEnvelopeIdentity {
  type: "answer";
  data: {
    answer: string;
    citations: ChatCitation[];
    confidence: "high" | "medium" | "low";
  };
}
/** Strict-typed future variants — wire-format alternatives mirroring engine canonicals. */
export interface StrictGraphArtifact extends ArtifactEnvelopeIdentity {
  type: "graph_export";
  data: GraphExport;
}
export interface StrictDeadCodeArtifact extends ArtifactEnvelopeIdentity {
  type: "dead_code_strict";
  data: { findings: DeadCodeFinding[] };
}
export interface StrictDecisionsArtifact extends ArtifactEnvelopeIdentity {
  type: "decisions_strict";
  data: { decisions: DecisionRecord[] };
}

/**
 * Typed variants only — use this when a consumer needs to narrow on `.type`
 * and access the per-variant `data` shape. The renderer's `switch` exhaust
 * check should be against this type.
 */
export type KnownChatArtifact =
  | OverviewArtifact
  | ContextArtifact
  | SourceArtifact
  | RiskArtifact
  | ChangeRiskArtifact
  | RiskReportArtifact
  | HealthArtifact
  | SearchResultsArtifact
  | DependencyPathArtifact
  | CallPathArtifact
  | GraphPathArtifact
  | DecisionsArtifact
  | DeadCodeArtifact
  | DiagramArtifact;

/**
 * Full union accepted on the wire. Consumers should branch on
 * `isKnownChatArtifact(a)` first, then switch on `a.type` for a typed render
 * path; the `else` falls through to a JSON pretty-print.
 */
export type ChatArtifact = KnownChatArtifact | GenericArtifact;

const KNOWN_ARTIFACT_TYPES: ReadonlyArray<KnownChatArtifact["type"]> = [
  "overview",
  "context",
  "source",
  "risk",
  "change_risk",
  "risk_report",
  "health",
  "search_results",
  "dependency_path",
  "call_path",
  "graph",
  "decisions",
  "dead_code",
  "diagram",
];

export function isKnownChatArtifact(
  a: ChatArtifact,
): a is KnownChatArtifact {
  return (KNOWN_ARTIFACT_TYPES as readonly string[]).includes(a.type);
}

// ---------------------------------------------------------------------------
// SSE event stream
// ---------------------------------------------------------------------------

export type ChatSSEEvent =
  | { type: "text_delta"; text: string }
  /** The server read for the page before the first model turn. */
  | {
      type: "grounding";
      tool_id: string;
      tool_name: string;
      input: Record<string, unknown>;
      summary: string;
      artifact: ChatArtifact;
    }
  | {
      type: "tool_start";
      tool_id: string;
      tool_name: string;
      input: Record<string, unknown>;
    }
  | {
      type: "tool_result";
      tool_id: string;
      tool_name: string;
      summary: string;
      artifact: ChatArtifact;
      citations?: ChatCitation[];
    }
  /** A table or chart the server built from a tool result of this turn,
   *  sent right after the `show_view` call's `tool_result`. */
  | { type: "view"; tool_id: string; view: ViewPart }
  /** A limit stopped the turn before a final answer; `done` still follows.
   *  `reason` is `loop_cap` (every call ended in a tool call) or `token_budget`. */
  | { type: "truncated"; loops: number; reason?: "loop_cap" | "token_budget" }
  /** The post-turn numeric check, sent before `suggestions` when the answer
   *  states a figure. Spans are offsets into the streamed text. */
  | {
      type: "diagnostics";
      figures_checked: number;
      figures_unverified: number;
      figures_not_checked?: number;
      unverified_figures: ChatFigureSpan[];
    }
  /** Next steps for the turn that just finished, sent just before `done`.
   *  A turn that failed or called no tool sends none. */
  | { type: "suggestions"; suggestions: ChatSuggestion[] }
  | { type: "done"; conversation_id: string; message_id: string; user_message_id?: string; provider?: string; model?: string; replayed?: boolean }
  | { type: "error"; message: string };