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.

14.4 KB
Raw Blame
/**
 * Canonical git-intelligence types — hotspots, ownership, bus factor, summary.
 *
 * Canonical source: engine `PipelineResult.git_metadata` (per-file) and
 * the rollups produced by `packages/web` UI. Downstream pipelines that emit
 * a different key (e.g. `path` instead of `file_path`) must rename via an
 * adapter before passing data to components.
 */

import type { HealthDeltaSummaryResponse } from "./generated/http.js";

export interface FileAuthor {
  name: string;
  email: string;
  commit_count: number;
  /** Share of the file's commits, 0–1. Optional: the file-detail endpoint
   *  serves these rows straight off the stored artifact, which records counts
   *  and no share. Derive from `commit_count` when it is absent. */
  pct?: number;
}

export interface SignificantCommit {
  sha: string;
  date: string;
  message: string;
  author: string;
}

export interface CoChangePartner {
  file_path: string;
  co_change_count: number;
}

export interface GitMetadata {
  file_path: string;
  commit_count_total: number;
  commit_count_90d: number;
  commit_count_30d: number;
  first_commit_at: string | null;
  last_commit_at: string | null;
  primary_owner_name: string | null;
  primary_owner_email: string | null;
  /** The primary owner's own share of the file's commits, 0–1. */
  primary_owner_commit_pct: number | null;
  /** The primary (blame) owner's share of current lines, 0–1. Null without blame. */
  primary_owner_line_pct?: number | null;
  recent_owner_name: string | null;
  recent_owner_commit_pct: number | null;
  top_authors: FileAuthor[];
  significant_commits: SignificantCommit[];
  co_change_partners: CoChangePartner[];
  is_hotspot: boolean;
  is_stable: boolean;
  churn_percentile: number;
  age_days: number;
  bus_factor: number;
  contributor_count: number;
  lines_added_90d: number;
  lines_deleted_90d: number;
  avg_commit_size: number;
  commit_categories: Record<string, number>;
  merge_commit_count_90d: number;
  test_gap?: boolean | null;
  /** v0.2.0+ — combined recency × churn × ownership score. Order hotspots by this when present. */
  temporal_hotspot_score?: number | null;
  /** Hassan change entropy (History Complexity Metric) — decay-weighted commit scatter. */
  change_entropy?: number;
  /** Repo-wide percentile rank of change_entropy, 0–100. */
  change_entropy_pct?: number;
  /** Bug-fix commits touching this file in the trailing defect window. */
  prior_defect_count?: number;
  /** `symbol_id` -> counted fixes that landed in it, over the same window.
   *  Approximate: symbol spans are current-tree while each fix's ranges are
   *  numbered on its own parent commit. Empty on a pre-rollup index. */
  fix_symbol_counts?: Record<string, number>;
  /** Decayed fix mass past its trigger. A recency claim, so any copy showing
   *  it must show `last_fix_at` too. */
  bug_magnet?: boolean;
  last_fix_at?: string | null;
  /** The file's path before its most recent rename, if any. */
  original_path?: string | null;
  /** True when the per-file commit-history cap was hit during indexing. */
  commit_count_capped?: boolean;
}

export interface Hotspot {
  file_path: string;
  commit_count_total?: number;
  commit_count_90d: number;
  commit_count_30d: number;
  churn_percentile: number;
  temporal_hotspot_score?: number | null;
  primary_owner: string | null;
  /** Share of all-time commits attributable to the primary owner, 0–1. */
  primary_owner_commit_pct?: number | null;
  /** Top author in the last 90 days; may differ from primary_owner on legacy code. */
  recent_owner_name?: string | null;
  recent_owner_commit_pct?: number | null;
  is_hotspot: boolean;
  is_stable: boolean;
  bus_factor: number;
  contributor_count: number;
  lines_added_90d: number;
  lines_deleted_90d: number;
  avg_commit_size: number;
  commit_categories: Record<string, number>;
  merge_commit_count_90d?: number;
  /** True when the per-file commit-history cap was hit during indexing — i.e. older history exists but was not analysed. */
  commit_count_capped?: boolean;
  age_days?: number;
  last_commit_at?: string | null;
  /** Hassan change entropy (History Complexity Metric) — decay-weighted commit scatter. */
  change_entropy?: number;
  /** Repo-wide percentile rank of change_entropy, 0–100. */
  change_entropy_pct?: number;
  /** Bug-fix commits touching this file in the trailing defect window. */
  prior_defect_count?: number;
  /** Decayed fix mass past its trigger. A recency claim, so any copy showing
   *  it must show `last_fix_at` too. */
  bug_magnet?: boolean;
  last_fix_at?: string | null;
  /** The file's path before its most recent rename, if any. */
  original_path?: string | null;
  /** Faster over the last 30 days than over the last 90, on a file older than that window. */
  accelerating?: boolean;
  /** Place by hotspot score within the listed scope; set by the hotspot list only. */
  rank?: number | null;
}

/** The hotspot list's filters; `all` lists every hotspot in scope. */
export type HotspotFilter = "all" | "bus_factor_1" | "accelerating" | "bug_magnet";
/** The hotspot list's sortable columns; `score` is the temporal hotspot score. */
export type HotspotSort = "score" | "commits" | "fixes" | "churn";
export type HotspotOrder = "asc" | "desc";

/** Counts over every hotspot the search matches, whatever the filter. */
export interface HotspotFacets {
  total: number;
  bus_factor_1: number;
  accelerating: number;
  bug_magnet: number;
  /** Hotspots with any recorded fix, across the whole searched set. */
  with_fixes?: number;
}

/** Repo-relative tercile of the diff-size percentile within its own repo;
 * size, not danger. */
export type ReviewPriority = "low" | "moderate" | "high";

export interface Commit {
  sha: string;
  short_sha: string;
  author_name: string;
  author_email: string;
  committed_at: string | null;
  subject: string;
  lines_added: number;
  lines_deleted: number;
  files_changed: number;
  dirs_changed: number;
  subsystems_changed: number;
  entropy: number;
  is_fix: boolean;
  /** Supporting 0–10 calibrated diff-size/spread score (stored; not a probability). */
  change_risk_score: number | null;
  /** Absolute calibration band — kept for transparency, but skews high on
   * repos with large typical commits; prefer {@link review_priority}. */
  change_risk_level: ReviewPriority | null;
  /** Where this commit's score sits within its repo's distribution, 0–100. */
  risk_percentile: number;
  /** Repo-relative tercile of the diff-size percentile; size, not danger. */
  review_priority: ReviewPriority;
  /** Label of the dominant risk driver, so rows explain themselves without
   * opening the detail sheet. Null when the commit was never risk-scored. */
  top_driver?: string | null;
  /** Author's cumulative prior-commit count at the time of the commit.
   * Low values flag a new-to-this-repo contributor. */
  author_experience?: number | null;
  /** Commits by this author across the indexed history (identities folded). */
  author_commit_count?: number | null;
  /** Coding-agent attribution (deterministic local-git channels). Null for
   * human-attested and unknown commits alike; read `attribution`. */
  agent_name?: string | null;
  /** 1 = near-autonomous bot, 2 = human-driven agent, 3 = assisted/co-authored. */
  agent_autonomy_tier?: number | null;
  agent_confidence?: string | null;
  /** agent / human_attested / unknown; null when attribution is off. */
  attribution?: CommitAttribution | null;
  /** What the commit did to health, the row's lead; null when never scanned. */
  health_delta?: HealthDeltaSummaryResponse | null;
  /** Hotspot files (as flagged now) the commit touched. */
  touches_hotspot?: number;
}

export type CommitAttribution = "agent" | "human_attested" | "unknown";

/** One feature's signed contribution to a commit's change-risk logit. */
export interface RiskDriver {
  feature: string;
  value: number | null;
  /** Signed push on the model logit; positive raises the supporting score. */
  contribution: number;
  label: string;
}

/** One file a commit touched, with what it cost and what it carries. */
export interface CommitFile {
  path: string;
  lines_added: number;
  lines_deleted: number;
  /** Bug-fix commits recorded against this path; null when untracked. */
  prior_fixes?: number | null;
}

/** One thing a commit introduced or worsened. */
export interface CommitHealthFinding {
  change_kind: string;
  dimension: string;
  biomarker_type: string;
  severity: string;
  /** Only set on `worsened`: what the severity was before the commit. */
  severity_before?: string | null;
  path: string;
  symbol?: string | null;
  line_start?: number | null;
  line_end?: number | null;
  /** How directly the commit is responsible, from `added_lines` down to
   *  `unknown`. Separates what a change wrote from what it merely touched. */
  attribution_basis: string;
  reason: string;
  /** Set when the commit moved this finding's code here from another file. */
  moved_from?: { path: string; symbol?: string | null } | null;
}

/** What a commit did to code health, computed at index time.
 *
 *  Absent rather than empty when the commit was never scanned: the scan is
 *  bounded, so older commits routinely have none, and that is not the same
 *  claim as "changed nothing". */
export interface CommitHealth {
  /** `available` when every changed file was compared, `partial` when some
   *  were skipped (unsupported language, binary, unreadable). */
  status: string;
  /** An older analyzer wrote it: the direction holds, the counts do not
   *  compare with current rows. */
  stale?: boolean;
  introduced_count: number;
  worsened_count: number;
  resolved_count: number;
  /** Findings whose metric dropped, at the same place or after a move. */
  improved_count?: number;
  /** Findings carried to another file with their code; a worsened or improved one is in that count too. */
  moved_count?: number;
  files_analyzed: number;
  files_skipped: number;
  /** Worst first, capped. `introduced_count + worsened_count` is the true
   *  total, so a shorter list means the rest was not stored. */
  findings: CommitHealthFinding[];
}

export interface CommitDetail extends Commit {
  /** Per-feature breakdown, strongest contribution first. */
  drivers: RiskDriver[];
  /** Which attribution channel identified the agent (e.g. git footer). */
  agent_channel?: string | null;
  /** Files this commit touched, biggest churn first. Empty on an index written
   *  before per-commit files were captured — re-index to fill it. */
  files?: CommitFile[];
  /** What the commit did to health; null when it was never scanned. */
  health?: CommitHealth | null;
}

/** Commits by attribution label, with the honest agent share. Unknown is
 * never counted as human: `agent_pct_of_covered` is the agent share of commits
 * with a known source (agent or human-attested), null below the coverage
 * floor with `suppressed_reason` set. Percentages are 0-100. */
export interface AttributionShareFields {
  total_commits: number;
  agent_commits: number;
  human_attested_commits: number;
  unknown_commits: number;
  coverage_pct: number | null;
  agent_pct_of_covered: number | null;
  suppressed_reason: string | null;
}

/** One month of commits by attribution label. */
export interface AgentTrendBucket extends AttributionShareFields {
  month: string; // "YYYY-MM"
  tier_counts: Record<string, number>;
}

/** Monthly attribution trend across the indexed commit window. `enabled` is
 * false, with every figure empty, when attribution is off for the repo. */
export interface AgentTrend extends AttributionShareFields {
  /** Absent from a server that does not send it; a trend carrying
   *  `agent_pct_of_covered` then reads as on. */
  enabled?: boolean;
  coverage_floor_pct: number;
  buckets: AgentTrendBucket[];
  agent_names: { name: string; count: number }[];
}

/** Canonical commit-category labels for the Code Evolution timeline. */
export type CommitCategory =
  | "feature"
  | "fix"
  | "refactor"
  | "docs"
  | "test"
  | "deps"
  | "chore"
  | "other";

/** One time bucket of commit-category counts. */
export interface CommitEvolutionBucket {
  period: string; // "YYYY-MM" (monthly) or "YYYY-Wnn" (weekly)
  start: string; // ISO date of the bucket's first day
  total: number;
  counts: Partial<Record<CommitCategory, number>>;
}

/** Commit-category mix over time — the repo's development "story arc". */
export interface CommitEvolution {
  buckets: CommitEvolutionBucket[];
  categories: CommitCategory[]; // present across the window, canonical order
  totals: Partial<Record<CommitCategory, number>>;
  total_commits: number;
  granularity: "month" | "week";
  first_commit_at: string | null;
  last_commit_at: string | null;
}

/** One bin of the repo's supporting 0-10 diff-shape score distribution. */
export interface RiskHistogramBucket {
  /** Bin lower bound on the 0-10 raw score axis (inclusive). */
  start: number;
  /** Bin upper bound (exclusive, except the final bin). */
  end: number;
  count: number;
}

/** Repo-wide commit aggregates (over all commits, not the loaded page). */
export interface CommitStats {
  total_commits: number;
  high_priority_count: number;
  fix_commit_count: number;
  /** Null, like the two figures below, when attribution is off. */
  agent_commit_count: number | null;
  /** Agent share of commits with a known source, 0-100; null below the
   * coverage floor. */
  agent_pct_of_covered?: number | null;
  /** Commits with a known source / all commits, 0-100. */
  attribution_coverage_pct?: number | null;
  avg_entropy: number;
  /** Binned on the raw score, not the percentile — percentile ranks are
   * uniform by construction, so only the raw axis has a shape to draw. */
  risk_histogram?: RiskHistogramBucket[];
  /** Raw score at the low/moderate tercile boundary. */
  moderate_cut?: number | null;
  /** Raw score at the moderate/high boundary — the review-priority line. */
  high_cut?: number | null;
}

export interface OwnershipEntry {
  module_path: string;
  primary_owner: string | null;
  owner_pct: number | null;
  file_count: number;
  is_silo: boolean;
}

export interface TopOwner {
  name: string;
  email?: string;
  file_count: number;
  pct: number;
}

export interface GitSummary {
  total_files: number;
  hotspot_count: number;
  stable_count: number;
  average_churn_percentile: number;
  top_owners: TopOwner[];
}

export interface BusFactorEntry {
  path: string;
  bus_factor: number;
  top_author: string;
  top_author_pct: number;
  contributor_count: number;
}

export interface BusFactor {
  files: BusFactorEntry[];
  overall_bus_factor: number;
}