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
/**
* 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[];
}