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
/**
* Data contract for the repo Stats ("By the Numbers") page.
*
* Mirrors the payload from `GET /api/repos/{repo_id}/stats/highlights`
* (packages/server/.../routers/stats.py). Scope is defined by subtraction:
* only signals no other page in the app already owns. Health scores belong to
* Code Health, commit volume and categories to Commits, per-person ownership to
* Contributors, dependencies and communities to Architecture. None of those
* appear here. The server derivations live in `repowise.core.stats_highlights`,
* shared by the OSS route and the hosted backend.
*
* Every section is independently built server-side and degrades to null/empty
* rather than failing the page, so most leaf fields are nullable.
*/
export interface StatsSizeClass {
name: string;
blurb: string;
nloc: number;
}
export interface StatsLanguage {
language: string;
file_count: number;
}
export interface StatsScale {
file_count: number;
symbol_count: number;
module_count: number;
total_nloc: number;
/** The share of `total_nloc` in files health analysis marked as tests. */
test_nloc?: number;
/** Code languages only: data and markup formats are not counted. */
language_count: number;
languages: StatsLanguage[];
/** Config, markup and data formats, kept apart from `languages`. */
docs_config_languages?: StatsLanguage[];
size_class: StatsSizeClass;
}
/** The repo's founding moment — its opening line, not just a date. */
export interface StatsOrigin {
first_commit_at: string | null;
/** Founding author (root commit). Null for older indexes / non-git repos. */
first_commit_author: string | null;
/** The root commit's subject. Null until an index captures it. */
first_commit_subject: string | null;
last_commit_at: string | null;
age_days: number | null;
/** Non-merge commits reachable from HEAD, the meaning "commits" has everywhere. */
total_commits: number;
/** Merge commits, counted apart. Null until an index captures it. */
total_merge_commits?: number | null;
contributor_count: number;
}
/**
* Lifetime lines written vs. taken back.
*
* Read from repo-level totals captured at index time, never summed from the
* commit table: that table is bounded to the newest N commits, so summing it
* would present a windowed figure as a lifetime one. Null when the history was
* too deep to walk or the index predates the capture.
*/
export interface StatsChurn {
lines_added: number;
lines_deleted: number;
net: number;
/** Lines deleted per hundred written. The shareable ratio. */
deleted_per_hundred: number;
}
/**
* Coding-rhythm heatmap: commit counts by weekday (0=Monday) x hour (0-23).
*
* `timezone_mode` says which clock the matrix is drawn in. `author_local` means
* every commit was shifted by its author's own UTC offset, the honest version
* of "when do people work". `utc` is the fallback for indexes written before
* the offset was captured; it resolves itself on the next `repowise update`.
*/
export interface StatsPunchCard {
/** 7 rows (Mon..Sun) x 24 columns (hours). */
matrix: number[][];
/** Single hottest weekday/hour cell, or null when there are no commits. */
peak: { weekday: number; hour: number; count: number } | null;
/** Weekday (0=Mon) and hour with the most commits by marginal total. */
busiest_weekday: number | null;
peak_hour: number | null;
total: number;
timezone_mode: "author_local" | "utc";
}
/** Commit momentum: the 90 days ending at the newest commit vs the 90 before. */
export interface StatsVelocity {
recent_90d: number;
prior_90d: number;
/** Percent change recent-vs-prior. Null when the prior window is empty or
* reaches past the indexed commit sample. */
pct_change: number | null;
}
/**
* How much history the rhythm and people sections were drawn from.
*
* The indexed commit table is bounded to the newest N commits. `complete` is
* false when the repo has more history than that, and the page then names the
* window instead of presenting a sample as the repo's whole life.
*/
export interface StatsWindow {
commits: number;
first_at: string | null;
last_at: string | null;
complete: boolean;
}
/** The time-shape of the work. Nothing else in the app has a clock. */
export interface StatsRhythm {
window?: StatsWindow;
punch_card: StatsPunchCard;
/** Null when the 90-day window reaches past the indexed commit sample. */
velocity: StatsVelocity | null;
busiest_month: { month: string; total: number } | null;
busiest_day: { date: string; commits: number } | null;
/** Longest run of consecutive days with at least one commit. */
longest_streak: { days: number; start: string; end: string } | null;
/** Longest stretch between two consecutive commits. */
longest_silence?: { hours: number; start: string; end: string } | null;
/** Distinct calendar days carrying at least one commit. */
active_days: number;
/** Median days since each file was last touched, anchored to the newest
* commit rather than now, so a stale index doesn't inflate it. */
code_half_life_days: number | null;
}
/** A contributor's commit-hour habit. Only emitted in author-local mode:
* awarding "night owl" off UTC would just name whoever lives furthest east. */
export interface StatsChronotype {
name: string;
commits: number;
peak_hour: number;
label: "night_owl" | "early_bird" | "daylight";
night_pct: number;
early_pct: number;
/** This person's own 24-hour commit histogram. */
hour_commits: number[];
/** This person's own weekday histogram, 0=Monday. Named client-side because
* which days count as the weekend is the reader's preference, not the
* server's. Older payloads omit both arrays; naming degrades to null. */
weekday_commits: number[];
}
export interface StatsArrival {
name: string;
first_commit_at: string | null;
}
/**
* Repo-level concentration only. Per-person detail (ownership share, hotspots
* owned, dead-code burden) is the Contributors page's job.
*/
export interface StatsPeople {
owner_count: number;
contributor_count: number;
/** Files with git history: the denominator for `single_owner_files`. */
tracked_files?: number;
single_owner_files: number;
silo_count: number;
/** Fewest primary owners who together hold >50% of owned files. 1 means a
* single person owns most of the codebase. Null when no ownership data. */
truck_factor: number | null;
chronotypes: StatsChronotype[];
/** Contributors ordered by their first commit inside the window. */
arrivals: StatsArrival[];
}
/**
* The superlatives. Several are the only headline treatment their underlying
* signal gets anywhere: max CCN is otherwise a sortable column, and import
* cycles have no other UI at all.
*/
export interface StatsRecords {
largest_file?: { path: string; nloc: number };
/** Highest cyclomatic complexity in any single file. */
gnarliest_file?: { path: string; max_ccn: number };
most_complex_symbol?: { name: string; file_path: string; complexity: number };
most_changed_file?: { path: string; commit_count: number };
/** Files whose first commit is the root commit, out of every dated file. */
day_one_files?: { count: number; of: number };
/** `import_count` present when graph metrics were materialized — the award
* is then "most imported"; without it, it degrades to the PageRank pick. */
most_central_file?: { path: string; pagerank: number; import_count?: number };
/** Biggest strongly-connected import cycle, and how many exist. */
largest_cycle?: { files: number; cycle_count: number };
/** What fraction of this codebase is async, and what fraction is documented. */
symbol_shape?: {
total: number;
async_count: number;
async_pct: number;
documented_count: number;
documented_pct: number;
};
/** Largest non-initial commit by churn (added + deleted lines). */
biggest_commit?: {
sha: string;
subject: string;
lines_changed: number;
files_changed: number;
};
/** Non-initial commit touching the most files. */
widest_commit?: {
sha: string;
subject: string;
files_changed: number;
lines_changed: number;
};
/** Non-initial commit that removed the most lines net. */
biggest_purge?: {
sha: string;
subject: string;
lines_deleted: number;
lines_added: number;
};
/** Function and record awards skip test code. */
longest_function?: { name: string; file_path: string; lines: number };
longest_name?: { name: string; file_path: string };
most_common_name?: { name: string; count: number };
/** Distinct commits that own a surviving line of the function, from
* function blame. High for many small patches, low for a rewrite. */
most_patched_function?: { name: string; file_path: string; mod_count: number };
}
export interface StatsRepo {
id: string;
name: string;
}
export interface StatsHighlights {
repo: StatsRepo;
scale: StatsScale;
origin: StatsOrigin;
/** Null when lifetime churn could not be captured. */
churn: StatsChurn | null;
rhythm: StatsRhythm;
people: StatsPeople;
records: StatsRecords;
/** On-disk size of the local `.repowise/` index. Absent where the index is
* not stored on this machine. */
index_storage_bytes?: number;
}