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.

9.4 KB
Raw Blame
/**
 * File-detail contract — the aggregate behind the canonical file entity
 * page (`GET /api/repos/{id}/files/{path}`). Mirrors the server's
 * `routers/files.py` response shape.
 */

import type { CoChangePartner, FileAuthor, Hotspot, SignificantCommit } from "./git.js";
import type { FileHealthTrend, FileSignals, HealthDimension } from "./health.js";

export interface FileWikiPageRef {
  id: string;
  title: string;
  summary: string;
  content: string;
  freshness_status: string;
  confidence: number;
  human_notes: string | null;
  /** Hand-requested doc: regenerated on every reindex so it keeps
      following the code (issue #812). */
  pinned: boolean;
  updated_at: string | null;
}

export interface FileHealthFinding {
  id: string;
  file_path: string;
  biomarker_type: string;
  severity: string;
  function_name: string | null;
  line_start: number | null;
  line_end: number | null;
  health_impact: number;
  reason: string;
  details: Record<string, unknown>;
  status: string;
  /**
   * The finding's "home" health dimension (`defect` / `maintainability` /
   * `performance`), so the file page can tag findings by pillar. Optional /
   * `defect` when an older payload omits it.
   */
  dimension?: HealthDimension;
  /** `"unverified"` for a provisional finding type; null for a validated one. */
  verification?: string | null;
  lower_priority?: string | null;
  /** The measurement note when the row's language cell is served as a preview;
   *  null or absent for a validated cell. */
  preview?: string | null;
}

export interface FileHealthMetric {
  file_path: string;
  score: number;
  max_ccn: number;
  max_nesting: number;
  nloc: number;
  has_test_file: boolean;
  line_coverage_pct: number | null;
  module: string | null;
  duplication_pct: number | null;
  /**
   * Per-dimension scores from the three-signal split. `score` stays the overall
   * surfaced number (== `defect_score`); `maintainability_score` and
   * `performance_score` are the co-surfaced pillars. All optional/nullable so
   * older payloads parse unchanged and unmeasured pillars read "—".
   */
  defect_score?: number | null;
  maintainability_score?: number | null;
  performance_score?: number | null;
  /**
   * Dominant-cause lead (worst finding's biomarker + reason) and the summed
   * pre-floor `health_impact`. Additive display signals: the lead headlines the
   * "one reason", `total_deduction` ranks two files that both floor at `1.0`.
   * Null on clean files or payloads that predate these fields.
   */
  primary_biomarker?: string | null;
  primary_reason?: string | null;
  total_deduction?: number | null;
}

export interface FileScoreBreakdownFinding {
  id: string;
  biomarker_type: string;
  severity: string;
  raw_impact: number;
  applied_impact: number;
  function_name: string | null;
  reason: string;
}

export interface FileScoreBreakdownCategory {
  category: string;
  cap: number;
  raw_deduction: number;
  applied_deduction: number;
  capped: boolean;
  finding_count: number;
  findings: FileScoreBreakdownFinding[];
}

export interface FileScoreBreakdown {
  score: number;
  total_deduction: number;
  categories: FileScoreBreakdownCategory[];
}

export interface FileDetailHealth {
  metric: FileHealthMetric | null;
  breakdown: FileScoreBreakdown | null;
  findings: FileHealthFinding[];
  /** Per-file score trajectory; `points` empty when history is thin. */
  trend: FileHealthTrend | null;
  /** Process / people / topology signals; null fields read "no signal". */
  signals: FileSignals | null;
}

/** Agent share (0-1) of the file's commits with a known source, null below
 * the coverage floor with `agent_share_suppressed` set; coverage is known /
 * all commits (0-1). Unknown commits are never counted as human. */
export interface FileAgentProvenance {
  agent_commit_count: number;
  agent_authored_pct: number | null;
  tier_counts: Record<string, number>;
  attribution_coverage: number | null;
  agent_share_suppressed: string | null;
}

/** Hotspot row + history extras the detail endpoint joins in. */
export interface FileDetailGit extends Hotspot {
  significant_commits: SignificantCommit[];
  top_authors: FileAuthor[];
  co_change_partners: CoChangePartner[];
  /** Null when attribution is off for the repository. */
  agent: FileAgentProvenance | null;
  first_commit_at: string | null;
  /** The primary (blame) owner's share of current lines, 0-1. Null without
   *  blame; `primary_owner_commit_pct` is the same person's share of commits. */
  primary_owner_line_pct?: number | null;
  /** `symbol_id` -> counted fixes that landed in it, over the same window as
   *  `prior_defect_count`. Approximate: symbol spans are current-tree while
   *  each fix's line ranges are numbered on its own parent commit. A symbol
   *  with no fixes is absent from the map; the whole map is empty on an index
   *  that predates the fix rollup. */
  fix_symbol_counts?: Record<string, number>;
}

export interface FileDetailCoverage {
  line_coverage_pct: number;
  branch_coverage_pct: number | null;
  total_coverable_lines: number;
  /**
   * How many lines `covered_lines` names. Always sent, including under
   * `fields=slim` where the array itself is dropped — the coverage headline
   * only ever wanted the count, and counting it client-side is what forced the
   * whole integer array across the wire. Optional so older payloads parse.
   */
  covered_line_count?: number;
  /** Empty under `fields=slim`; read `covered_line_count` for the total. */
  covered_lines: number[];
  source_format: string;
  ingested_at: string | null;
  ingested_commit_sha: string | null;
  /**
   * Whether `covered_lines` still lines up with the file on disk: `stale` when
   * git shows the file changed since `ingested_commit_sha`, `unknown` when it
   * cannot tell. Only `stale` withholds the line tint. Optional so older
   * payloads parse.
   */
  freshness?: "current" | "stale" | "unknown";
}

export interface FileGraphNeighbor {
  node_id: string;
  node_type: string;
  language: string | null;
  edge_type: string;
  imported_names: string[];
}

export interface FileDetailGraph {
  language: string;
  is_entry_point: boolean;
  is_test: boolean;
  symbol_count: number;
  pagerank: number;
  pagerank_percentile: number;
  in_degree: number;
  out_degree: number;
  community_id: number;
  community_label: string | null;
  dependents: FileGraphNeighbor[];
  dependencies: FileGraphNeighbor[];
}

export interface FileSymbolSlim {
  symbol_id: string;
  name: string;
  kind: string;
  signature: string;
  start_line: number;
  end_line: number;
  visibility: string;
  complexity_estimate: number;
  is_async: boolean;
}

export interface FunctionBlameRow {
  symbol_id: string;
  function_name: string;
  start_line: number;
  end_line: number;
  line_count: number;
  mod_count: number;
  recent_mod_count: number;
  median_author_time: number | null;
  owner_name: string | null;
  owner_email: string | null;
  owner_line_pct: number | null;
}

export interface GoverningDecisionRef {
  id: string;
  title: string;
  status: string;
}

export interface FileDeadCodeFinding {
  id: string;
  kind: string;
  symbol_name: string | null;
  confidence: number;
  reason: string;
  lines: number | null;
  safe_to_delete: boolean;
}

/**
 * One slim row in the browsable Files index (`GET /api/repos/{id}/files`).
 * Everything the treemap + ranked table need without the per-file aggregate's
 * weight. `pagerank_pct` / `churn_pct` are 0-100 percentiles ranked over the
 * whole repo; scores are 0-10; nullable fields read "—" when unmeasured.
 */
export interface FileRow {
  file_path: string;
  language: string;
  /** NLOC, not raw lines; null where health measured none (see `loc_null_reason`). */
  loc: number | null;
  symbol_count: number;
  pagerank_pct: number;
  in_degree: number;
  out_degree: number;
  defect_score: number | null;
  maintainability_score: number | null;
  performance_score: number | null;
  churn_pct: number | null;
  commit_count: number | null;
  last_commit_at: string | null;
  /** Measured line coverage, 0-100, from the stored report. Optional so older servers parse. */
  line_coverage_pct?: number | null;
  /** @deprecated The same figure as `line_coverage_pct`; read that. */
  coverage_pct: number | null;
  is_test: boolean;
  is_entry_point: boolean;
  community_id: number;
}

export interface FileLanguageCount {
  language: string;
  count: number;
}

export interface FilesIndexResponse {
  files: FileRow[];
  total: number;
  languages: FileLanguageCount[];
  /** What `loc` counts. Optional so older servers parse. */
  loc_unit?: "nloc";
  /** Why a row's `loc` is null. */
  loc_null_reason?: string;
}

export interface FileDetailResponse {
  file_path: string;
  wiki_page: FileWikiPageRef | null;
  health: FileDetailHealth;
  git: FileDetailGit | null;
  coverage: FileDetailCoverage | null;
  graph: FileDetailGraph | null;
  symbols: FileSymbolSlim[];
  /** Empty under `fields=slim`; read `function_blame_count` for the total. */
  function_blame: FunctionBlameRow[];
  /**
   * How many blame rows exist, in both modes. Optional so a frontend ahead of
   * its backend degrades rather than rendering `NaN` — the same contract
   * `coverage.covered_line_count` follows, and for the same reason: a caller
   * deciding whether a block is worth fetching cannot otherwise tell an empty
   * table from a dropped one.
   */
  function_blame_count?: number;
  governing_decisions: GoverningDecisionRef[];
  dead_code: FileDeadCodeFinding[];
}