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.

10.8 KB
Raw Blame
/**
 * Overview-summary contract — the one-call payload behind the repo
 * Overview page (`GET /api/repos/{id}/overview-summary`). Mirrors the
 * server's `routers/overview.py` response shape.
 */

import type { Hotspot } from "./git.js";
import type {
  DefectAccuracy,
  HealthBand,
  HealthSeverity,
  PerformanceCauses,
} from "./health.js";
import type { QueueCounts } from "./queue.js";

export interface OverviewRepoMeta {
  id: string;
  name: string;
  local_path: string;
  default_branch: string;
  head_commit: string | null;
  updated_at: string | null;
  /** GitHub owner/login. Hosted-only — lets surfaces like the MCP connect
   *  card build the `owner/name` server URL without resolving the repo
   *  through the viewer's own repo list (so it works on public shares for
   *  non-owners). Absent/`""` for the OSS CLI, which has no remote owner. */
  owner?: string;
  /** Whether the repo is publicly browsable. Hosted-only; drives the
   *  public/private connect copy. Defaults to public when absent. */
  is_public?: boolean;
  /** Git remote, from the stored repo URL or `.git/config`'s origin. Used
   *  only to resolve a repo avatar, so a null (no remote, or a host we do not
   *  recognise) simply falls back to initials. */
  remote_url?: string | null;
}

export interface OverviewStatDeltas {
  average_health: number | null;
  hotspot_health: number | null;
  file_count: number | null;
}

export interface OverviewStats {
  file_count: number;
  symbol_count: number;
  entry_point_count: number;
  /**
   * Total generated wiki pages. Optional: a server that predates this field
   * omits it, and hosted bumps the ui/types packages independently of its
   * backend deploy — treat absent as unknown rather than rendering NaN.
   */
  doc_page_count?: number;
  /**
   * Of `doc_page_count`, how many carry model-written prose rather than being
   * assembled deterministically from the index. The two are different products
   * — deterministic pages are free and always current, prose pages cost a model
   * call and can go stale — so the Overview reports them separately instead of
   * behind one total. Optional: a server predating the field omits it, and the
   * UI then shows the flat total rather than inventing a split.
   */
  doc_prose_page_count?: number;
  doc_coverage_pct: number;
  freshness_score: number;
  dead_export_count: number;
  hotspot_count: number;
  silo_count: number;
  module_count: number;
  /**
   * Total non-comment lines of code, summed from the per-file health metrics.
   * Optional: a server predating the field omits it and the caller then has no
   * lines figure rather than rendering a zero it did not measure.
   */
  total_nloc?: number;
  deltas: OverviewStatDeltas;
}

export interface OverviewHealthHistoryPoint {
  taken_at: string | null;
  average_health: number;
  /** Null on a snapshot whose repo had no scored hotspot file. */
  hotspot_health: number | null;
}

export interface OverviewHealth {
  average_health: number | null;
  /** Files health has no dialect for, left out of every figure. */
  unanalysed_file_count?: number;
  /** Scored files over all code files, 0-1; `null` with no code files. */
  analysed_share?: number | null;
  /** Band for `average_health`; `null` when too few code files were analysed
   *  to grade the repo. Absent on an older server. */
  band?: HealthBand | null;
  /** Backtested precision of the defect ranking — the "can you trust this
   *  score?" panel on the health card. Optional so an older server payload
   *  simply omits the panel. */
  defect_accuracy?: DefectAccuracy | null;
  hotspot_health: number | null;
  worst_performer_path: string | null;
  worst_performer_score: number | null;
  open_findings: number;
  /** The findings' count vocabulary; the same numbers the Code Health page shows. */
  finding_counts?: QueueCounts;
  /** Co-equal maintainability pillar headline (NLOC-weighted). `null` when no
   *  file carries a maintainability score yet. */
  maintainability_average?: number | null;
  /** Co-equal performance pillar headline: static performance RISK (I/O-in-loop
   *  / N+1). `null` when not yet measured. */
  performance_average?: number | null;
  /** Open performance causes: worth fixing now, in production code, overall. */
  performance_causes?: PerformanceCauses | null;
  /** Lowest-scoring file by performance risk, surfaced only when score < 10. */
  worst_performance_path?: string | null;
  worst_performance_score?: number | null;
  severity_breakdown: Record<string, number>;
  last_indexed_at: string | null;
  snapshot_count: number;
  history: OverviewHealthHistoryPoint[];
}

export interface OverviewLanguage {
  language: string;
  file_count: number;
}

export type OverviewAttentionType =
  | "stale_decision"
  | "proposed_decision"
  | "ungoverned_hotspot"
  | "knowledge_silo"
  | "dead_code"
  | "health_finding"
  | "security_finding"
  | "doc_drift"
  | "refactoring";

export interface OverviewAttentionItem {
  id: string;
  type: OverviewAttentionType;
  title: string;
  description: string;
  /**
   * The four-level ladder shared with `HealthSeverity`, rather than the three
   * levels this used to declare. Sources that publish their own severity are
   * passed through unchanged; the two that genuinely have none (dead code and
   * documentation drift carry a confidence float instead) are bucketed onto it
   * server-side. See `core/analysis/attention/compose.py`.
   */
  severity: HealthSeverity;
  /** Decision id, file path, … — what the item points at. */
  target_id: string;
  /**
   * The finding's own kind within its source: a `biomarker_type` for a health
   * finding, a scanner kind for security, a drift kind. Optional because the
   * decision and silo sources have no sub-kind.
   *
   * Sent raw so the UI can resolve it through the biomarker glossary it
   * already owns, rather than the server holding a second copy of that
   * vocabulary and the two drifting.
   */
  subtype?: string;
}

/**
 * How much each source holds, beside the capped list in `attention`.
 *
 * Every source is capped so no single store floods the merged list, which
 * means `attention.length` is not a total and never was safe to render as one.
 */
export type OverviewAttentionArea =
  | "security"
  | "health"
  | "refactoring"
  | "doc_drift"
  | "decisions"
  | "ownership"
  | "dead_code";

/**
 * One area of work, with the worst thing in it named.
 *
 * Six ranked findings out of sixteen thousand is a sample, not triage, and it
 * lets one store own every visible row. An area row reports how much that area
 * holds and leads with the single item that topped it, so the list stays a
 * fixed, scannable seven rows whatever the underlying volume.
 */
export interface OverviewAttentionAreaRow {
  key: OverviewAttentionArea;
  /** Everything this area holds, not what is displayed. */
  total: number;
  /** Severity of the lead, i.e. the worst thing in the area. */
  severity: HealthSeverity;
  /**
   * What the count is made of, where one number over several lanes would
   * misstate it — "365 awaiting review · 699 hotspots ungoverned" rather than
   * a bare 1,064. Empty string for an area with a single lane.
   */
  detail?: string;
  /** Absent only if the area reports a count with no item behind it. */
  lead: {
    title: string;
    description: string;
    type: OverviewAttentionType;
    target_id?: string | null;
    subtype?: string;
    severity: HealthSeverity;
  } | null;
}

export interface OverviewAttentionSummary {
  total: number;
  /** Keyed by attention type, plus `decisions` for the three decision lanes. */
  by_source: Record<string, number>;
  /** Optional: a server predating the area rows omits it. */
  areas?: OverviewAttentionAreaRow[];
}

export interface OverviewOnboardingTarget {
  path: string;
  pagerank: number;
  doc_words: number;
}

export interface OverviewDecisionSlim {
  id: string;
  title: string;
  status: string;
  source: string | null;
  created_at: string | null;
  staleness_score: number;
}

/**
 * The savings headline on the overview payload.
 *
 * A strict subset of the full savings report, from the same core report
 * service, so the overview and the Costs page cannot disagree. The
 * measured/inferred and priced/unpriced splits travel with the total because a
 * lone headline reads as one confident number and the evidence is not uniform.
 *
 * `available: false` means nothing has been measured in this repository, which
 * is not the same as a measured zero.
 */
export interface OverviewSavings {
  available: boolean;
  saved_input_tokens?: number;
  measured_saved_input_tokens?: number;
  inferred_saved_input_tokens?: number;
  priced_saved_input_tokens?: number;
  unpriced_saved_input_tokens?: number;
  estimated_usd_saved?: number;
  mcp_queries_answered?: number;
  last_event_at?: string | null;
}

export interface OverviewSyncStatus {
  last_sync_at: string | null;
  last_resync_at: string | null;
  last_sync_model: string | null;
  active_job_id: string | null;
  page_count: number;
  /** @deprecated Not sent by the OSS server; read `StatsHighlights.index_storage_bytes`. */
  index_storage_bytes?: number;
}

/**
 * Figures Overview shares with the pages it links to, each read through the
 * function that page leads with. A block is `null` when its store is absent.
 */
export interface OverviewExploreCounts {
  /** The Decisions page lanes: accepted of total recorded, candidates
   *  awaiting review, and accepted ones drifting from the code. */
  decisions: { total: number; accepted: number; candidates: number; needs_review: number } | null;
  /** The Refactoring page lede: open opportunities, one per file. */
  refactoring: { opportunities_total: number; files_total: number } | null;
  /** The Contributors page: files with one author and no second reader. */
  ownership: { sole_owned_files: number } | null;
  /** The Security page lede: matches in shipped source versus tests and docs. */
  security: { total: number; source: number; source_high: number; elsewhere: number } | null;
  /** The Tests page lede; `null` until a coverage report is ingested. */
  coverage: { line_coverage_pct: number; ingested_at: string | null } | null;
}

export interface OverviewSummaryResponse {
  repo: OverviewRepoMeta;
  stats: OverviewStats;
  health: OverviewHealth;
  /** Code languages only. */
  languages: OverviewLanguage[];
  /** Config, markup and data formats, kept apart from `languages`. */
  docs_config_languages?: OverviewLanguage[];
  attention: OverviewAttentionItem[];
  /** Optional: a server predating the merged attention list omits it, and the
   *  UI then falls back to counting the rows it was given. */
  attention_summary?: OverviewAttentionSummary;
  onboarding_targets: OverviewOnboardingTarget[];
  top_hotspots: Hotspot[];
  recent_decisions: OverviewDecisionSlim[];
  savings: OverviewSavings;
  sync: OverviewSyncStatus;
  /** Optional: a server predating it omits the block. */
  explore?: OverviewExploreCounts;
}