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
/**
* Fix first: one ranked list of what to fix, built once in core from stored rows.
*
* Mirrors `repowise.core.analysis.health.fix_first.model`.
* `test_wire_vocabulary_parity.py` fails when the unions below and their
* Python twins disagree.
*/
import type { ActionCommand } from "./actions.js";
import type { QueueCounts } from "./queue.js";
export type FixTier = "now" | "next" | "later";
export type FixKind = "refactor" | "perf_fix" | "finding";
export type FixImproves = "defect" | "maintainability" | "performance";
export type FixGainKind = "health_points" | "performance";
export type FixEffort = "S" | "M" | "L" | "XL";
export type FixLevel = "high" | "medium" | "low";
/** `unknown` is printed as a fact, never read as zero. */
export type FixFactBasis = "measured" | "inferred" | "unknown";
/** Why a unit of work is not in the queue; each is counted in `totals.excluded`. */
export type FixExclusion =
| "test"
| "tooling"
| "unknown"
| "generated"
| "expected"
| "no_strategy"
| "no_plan"
| "below_min_worth"
| "history_only"
| "vendored"
| "docs_example"
| "deprecated"
| "gated_off"
| "cold_path"
| "unreachable"
| "inherent_dispatch"
| "small_function"
| "no_concrete_step"
| "low_value_kind"
| "kind_unaudited"
| "terminal_flow"
| "moderate_quiet"
| "unmeasured_cost"
| "cold_role"
| "background_unproven"
| "unconfirmed_cost";
/** `all` keeps test files, labelled in `context`. */
export type FixScope = "production" | "all";
export interface FixTarget {
file_path: string;
symbol: string | null;
line_start: number | null;
line_end: number | null;
}
export interface FixFact {
label: string;
value: string;
basis: FixFactBasis;
}
export interface FixStep {
order: number;
text: string;
file_path: string;
line: number | null;
mechanical: boolean;
/** An Extract Method helper's header and the statement that replaces the span. */
signature?: string | null;
call?: string | null;
/** The command that checks this step, when it differs from the item's. */
command?: string | null;
/** What the helper's code cannot say: a type a guard narrows, a parameter object to declare. */
notes?: string[];
}
/** A due item's first edit, inline in the compact projection. */
export interface FixFirstStep {
action: string;
line?: number;
/** Only when the step edits a file other than the item's target. */
file?: string;
}
export interface FixItem {
/** `fix1_<20 hex>`: stable while the item's source id is. */
id: string;
rank: number;
tier: FixTier;
kind: FixKind;
improves: FixImproves;
/** Imperative, at most 90 characters, no biomarker ids. */
title: string;
target: FixTarget;
/** One plain sentence: the problem, and why it matters here. */
why: string;
facts: FixFact[];
action: { summary: string; steps: FixStep[]; steps_total: number; mechanical: boolean };
gain: { kind: FixGainKind; value: number | null; text: string };
effort: { bucket: FixEffort; basis: string };
risk: { level: FixLevel; dependents: number | null; files_touched: number; text: string };
confidence: { level: FixLevel; reason: string };
verify: {
tests: { path: string; reason: string }[];
tests_total: number;
command: string | null;
basis: FixFactBasis;
/** What to do before the edit when no test reaches it. */
prerequisite?: string | null;
};
/** History signals: shown beside the item, never ranked on. */
context: { label: string; value: string }[];
source: { opportunity_id: string | null; plan_ids: string[]; finding_ids: string[] };
next_call: ActionCommand;
/** The value inputs and the tier reason, so the order is explainable. */
why_ranked: { factor: string; value: string }[];
/** The value band, 0 to 4, Do next ranks the item on; null on an older snapshot. */
value?: number | null;
}
/** The projection a list renders; the full item is one lookup away. */
export interface FixItemCompact {
id: string;
tier: FixTier;
kind: FixKind;
title: string;
target: FixTarget;
why: string;
gain: string;
effort: FixEffort;
confidence: FixLevel;
/** Due items only (tier `now` or `next`). */
first_step?: FixFirstStep;
/** The item's command, or the step to take first when no test reaches it. */
verify?: { command?: string; prerequisite?: string };
next_call: ActionCommand;
}
export interface FixFirstTotals {
candidates: number;
eligible: number;
shown: number;
excluded: Record<FixExclusion, number>;
/**
* Distinct functions with work kept out as `gated_off`: dormant, not gone.
* Absent from a server that predates it.
*/
dormant?: number;
}
/** The count vocabulary (`QueueCounts`) read on the whole Fix first queue. */
export type FixFirstCounts = QueueCounts;
export interface FixFirstQueue<Item = FixItem> {
items: Item[];
/** `items[0]`, or null when nothing is eligible. */
lead: Item | null;
totals: FixFirstTotals;
/** Eligible items per pillar they improve. */
by_improves: Record<FixImproves, number>;
model_version: number;
basis: { analyzed_commit: string | null; health_analyzed_at: string | null };
/** The items' counts; `totals` stays for older readers. */
counts?: QueueCounts;
}