Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
/**
* 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;
}