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 decision-record types.
*
* Canonical source: engine `DecisionRecordResponse`. Some downstream backends
* emit a leaner `DecisionEntry` shape that omits `repository_id` and types
* `status`/`source` as bare `string` instead of literal unions — consumer
* adapters fill defaults before passing data to components.
*/
// ---------------------------------------------------------------------------
// Shared vocabulary
//
// The engine owns these words. Every one below is pinned against
// `tests/fixtures/decision_vocabulary.json`, which the Python registry
// generates, by `__tests__/decisions-vocabulary.test.ts` and by
// `tests/unit/analysis/test_decision_vocabulary_contract.py`. Adding a source or a
// currency on either side without the other fails a build.
//
// Four surfaces used to keep their own copies, and they had already drifted:
// this union named a retired `readme_mining` and omitted five live sources,
// two status ladders disagreed about where `superseded` sat, and the retired
// set was hand-mirrored with nothing tying it to its source.
// ---------------------------------------------------------------------------
/**
* `decision_records.status`, best first: a rule the team stands behind, then a
* candidate, then history, then a tombstone. This is the sort order, not just
* a set.
*
* `dismissed` is a tombstone and `deprecated` is a retirement, and the
* difference is load-bearing: the engine skips a dismissed record on every
* re-extraction and hides it from listings, where a deprecated one keeps being
* re-derived and keeps its row.
*/
export const DECISION_STATUSES = [
"active",
"proposed",
"superseded",
"deprecated",
"dismissed",
] as const;
export type DecisionStatus = (typeof DECISION_STATUSES)[number];
/** The word for a status. Presentation, so the fixture pins coverage only. */
export const DECISION_STATUS_LABELS: Record<DecisionStatus, string> = {
active: "Active",
proposed: "Proposed",
superseded: "Superseded",
deprecated: "Deprecated",
dismissed: "Dismissed",
};
/**
* The two nouns the store holds. An `architectural` decision is a claim about
* the code that a diff can violate. An `agreement` is a claim about how the
* work is conducted, which no diff can violate, so it names no file and is
* never checked against one.
*/
export const DECISION_KINDS = ["architectural", "agreement"] as const;
export type DecisionKind = (typeof DECISION_KINDS)[number];
/** The word for a kind. Presentation, so the fixture pins coverage only. */
export const DECISION_KIND_LABELS: Record<DecisionKind, string> = {
architectural: "Decision",
agreement: "Working agreement",
};
/** Sort key for a status. An unknown status sorts after every known one. */
export function decisionStatusRank(status: string): number {
const i = (DECISION_STATUSES as readonly string[]).indexOf(status);
return i === -1 ? DECISION_STATUSES.length : i;
}
/**
* The values `DecisionRecord.source` can carry on a live index.
*
* Wider than the capture-source registry the settings panel switches on and
* off: `commit` and `llm_inferred` are stored provenance with no toggle, and
* broad session discovery stores `session` rather than a value of its own.
*/
export const DECISION_SOURCES = [
"adr",
"agent",
"cli",
"comment",
"commit",
"conventions",
"git_archaeology",
"inline_marker",
"llm_inferred",
"pr",
"session",
] as const;
export type DecisionSource = (typeof DECISION_SOURCES)[number];
/**
* Sources the engine no longer emits and whose rows were purged with them. A
* record carrying one cannot exist, so offering it as a filter is a control
* that cannot act. `code_comment` is retired and `comment` is not: they are
* different values and a live index still carries the second.
*/
export const RETIRED_DECISION_SOURCES = [
"code_comment",
"readme_mining",
"changelog",
] as const;
export type RetiredDecisionSource = (typeof RETIRED_DECISION_SOURCES)[number];
/**
* Column labels for every source a row can carry, retired ones included so an
* old record still renders a word rather than a raw key.
*
* Presentation, so it is not in the fixture. The test asserts it covers every
* live and retired source, which is the drift that actually happened: one
* column mixed "Docs" with a bare `pr`.
*/
export const DECISION_SOURCE_LABELS: Record<
DecisionSource | RetiredDecisionSource,
string
> = {
adr: "ADR",
agent: "Agent",
cli: "Manual",
comment: "Comment",
commit: "Commit",
conventions: "Convention",
git_archaeology: "Git history",
inline_marker: "Marker",
llm_inferred: "Model",
pr: "Pull request",
session: "Session",
changelog: "Changelog",
code_comment: "Comment",
readme_mining: "Docs",
};
/**
* `source` is an unconstrained string on the wire, so a plain index into the
* label map reaches `Object.prototype`: a row sourced `toString` would hand a
* function to `localeCompare` and throw inside a sort comparator.
*/
export function decisionSourceLabel(source: string): string {
return Object.hasOwn(DECISION_SOURCE_LABELS, source)
? DECISION_SOURCE_LABELS[source as DecisionSource]
: source;
}
/** Whether a source string names a retired source. */
export function isRetiredDecisionSource(source: string): boolean {
return (RETIRED_DECISION_SOURCES as readonly string[]).includes(source);
}
/**
* What an accepted decision's authority currently amounts to.
*
* Not the same axis as `DecisionStatus`, which is the legacy projection kept
* in step for readers that predate the acceptance split. `needs_review` and
* `uncheckable` are derived from the code rather than set by a person, which
* is why a record can be stored `active` and shown `uncheckable`.
*/
export const DECISION_CURRENCIES = [
"active",
"needs_review",
"uncheckable",
"stale",
"superseded",
"dismissed",
] as const;
export type DecisionCurrency = (typeof DECISION_CURRENCIES)[number];
/**
* The word for a currency, and the sentence that says why it reads that way.
*
* `uncheckable` and `needs_review` are the two a reader cannot guess: the
* first means the decision names nothing the repository can be asked about,
* the second that the files it names have moved. Neither is an error, and
* neither is quiet.
*/
export const DECISION_CURRENCY_LABELS: Record<DecisionCurrency, string> = {
active: "Active",
needs_review: "Needs review",
uncheckable: "Uncheckable",
stale: "Stale",
superseded: "Superseded",
dismissed: "Dismissed",
};
export const DECISION_CURRENCY_DESCRIPTIONS: Record<DecisionCurrency, string> =
{
active: "Accepted, and still describes the code it names.",
needs_review: "Accepted, but the code it names has moved since.",
uncheckable:
"Accepted, but it names no file or module, so nothing checks it against the code.",
stale: "Accepted, but nothing it names exists in the code any more.",
superseded: "Replaced by a later decision.",
dismissed: "Authority withdrawn. Kept for history.",
};
/**
* What signed an acceptance, as against who. `accepter` is a free string that
* resolves to the repository's git identity, so a machine signing read as a
* person. A stored `""` is a row written before the column and is not
* `person`: "unrecorded" and "a human signed" are what this keeps apart.
*/
export const ACCEPTER_KINDS = ["person", "agent", "import"] as const;
export type AccepterKind = (typeof ACCEPTER_KINDS)[number];
/**
* Worded for the signature, not the action: the same row records withdrawals,
* so "accepted" would present a revocation as a grant.
*/
export const ACCEPTER_KIND_LABELS: Record<AccepterKind, string> = {
person: "Signed by a person",
agent: "Signed by an agent",
import: "Signed by a tracked artifact",
};
/** Currencies that still bind future work. A moved decision is one to re-read. */
export const GOVERNING_CURRENCIES: readonly DecisionCurrency[] = [
"active",
"needs_review",
];
/** Where a candidate is in review. `dismissed` is a durable tombstone. */
export const CANDIDATE_REVIEW_STATES = [
"open",
"accepted",
"merged",
"needs_split",
"dismissed",
] as const;
export type CandidateReviewState = (typeof CANDIDATE_REVIEW_STATES)[number];
/** Derived granularity of a decision's blast area, narrowest first. */
export type DecisionScope = "file" | "module" | "cross-module";
export interface DecisionRecord {
id: string;
repository_id: string;
title: string;
status: DecisionStatus;
context: string;
decision: string;
rationale: string;
alternatives: string[];
consequences: string[];
affected_files: string[];
affected_modules: string[];
tags: string[];
/**
* Where the record came from. Includes the retired values, because a row
* written before a source was retired still carries its name and still has
* to render; only the *filter* vocabulary is narrowed to the live set.
*/
source: DecisionSource | RetiredDecisionSource;
evidence_commits: string[];
evidence_file: string | null;
evidence_line: number | null;
confidence: number;
staleness_score: number;
superseded_by: string | null;
last_code_change: string | null;
/** Trust tier of the decision's primary supporting evidence. Optional for back-compat. */
verification?: DecisionVerification;
/**
* Which noun this record is. An `agreement` names no file on purpose, so it
* is never shown as missing a scope. Optional for back-compat with a backend
* written before the split; absent reads as `architectural`.
*/
kind?: DecisionKind;
/**
* Derived granularity level. Optional for back-compat with older backends;
* null when the record has no code linkage at all.
*/
scope?: DecisionScope | null;
created_at: string;
updated_at: string;
/**
* Effective currency from the acceptance, or null for a candidate.
*
* This is the authority answer. `status` is the projection kept in step for
* readers that predate the acceptance split, so the two are different
* questions: a record can be stored `active` and carry no currency at all,
* which is exactly what a candidate is. Optional for back-compat with
* backends that predate the field; absent and null both mean unknown, so a
* surface that needs the distinction should ask for the lane instead.
*/
currency?: DecisionCurrency | null;
/**
* Who signed the current authority record. Null on a candidate, beside
* `currency`. `""` means written before provenance, not that a person did.
*/
accepter?: string | null;
accepter_kind?: AccepterKind | "" | null;
accepter_session?: string | null;
/** Why a record just created stayed a candidate. Create endpoint only. */
blockers?: string[] | null;
/**
* True when the stored decision text is blank and `decision` carries the
* title fallback. Acceptance reads the stored text, so this is what predicts
* the "no decision text" refusal. Optional for back-compat.
*/
decision_text_missing?: boolean;
/** Number of evidence rows backing the record. List endpoint only. */
evidence_count?: number | null;
/** Top-ranked evidence row, slimmed for list rows. List endpoint only. */
evidence_preview?: EvidencePreview | null;
}
/** The top-ranked evidence row, slimmed for decision list rows. */
export interface EvidencePreview {
source: string;
source_quote: string;
verification: DecisionVerification;
evidence_file?: string | null;
evidence_line?: number | null;
}
export interface DecisionCreateInput {
title: string;
/**
* Omit to state no opinion: the engine then leaves an existing record's
* noun alone rather than defaulting it back to `architectural`.
*/
kind?: DecisionKind;
context?: string;
decision?: string;
rationale?: string;
alternatives?: string[];
consequences?: string[];
affected_files?: string[];
affected_modules?: string[];
tags?: string[];
}
/**
* PATCH body for /api/repos/{id}/decisions/{decision_id}. All fields are
* optional — clients can update just the status, just the linkage, or both.
*/
export interface DecisionStatusUpdate {
status?: DecisionStatus;
superseded_by?: string;
affected_modules?: string[];
affected_files?: string[];
}
export interface DecisionHealth {
summary: {
active: number;
proposed: number;
deprecated: number;
superseded: number;
stale: number;
};
stale_decisions: DecisionRecord[];
proposed_awaiting_review: DecisionRecord[];
ungoverned_hotspots: string[];
}
// ---------------------------------------------------------------------------
// Phase 4C: evidence / lineage / decision-graph
// ---------------------------------------------------------------------------
/**
* Trust level of a decision's supporting evidence. `exact` = the source quote
* was found verbatim in the cited file/commit; `fuzzy` = a near-match;
* `unverified` = the quote could not be located (LLM-derived, treat with care).
*/
export type DecisionVerification = "exact" | "fuzzy" | "unverified";
/** One supporting evidence row for a decision. */
export interface DecisionEvidence {
id: string;
source: string;
source_rank: number;
evidence_file: string | null;
evidence_line: number | null;
evidence_commit: string | null;
source_quote: string;
confidence: number;
verification: DecisionVerification;
created_at: string;
}
/**
* One hop in a decision's supersession/evolution chain. The chain is ordered
* root -> current; `relation` describes how the NEWER decision related to this
* one ("supersedes" | "refines" | null for the terminal/current entry).
*/
export interface DecisionLineageEntry {
id: string;
title: string;
status: DecisionStatus;
source: string;
relation: string | null;
}
export interface DecisionGraphNode {
id: string;
title: string;
status: DecisionStatus;
source: string;
confidence: number;
staleness_score: number;
verification: DecisionVerification;
}
export type DecisionEdgeKind =
| "supersedes"
| "refines"
| "relates_to"
| "conflicts_with";
export interface DecisionGraphEdge {
src: string;
dst: string;
kind: DecisionEdgeKind;
confidence: number;
evidence: string;
}
export interface DecisionCodeEdge {
decision_id: string;
node_id: string;
link_type: "file" | "module";
}
export interface DecisionGraph {
nodes: DecisionGraphNode[];
decision_edges: DecisionGraphEdge[];
code_edges: DecisionCodeEdge[];
}
/**
* Review lanes, as the list endpoint's `lane` parameter accepts them.
*
* `governing` is the roll-up of `active` and `needs_review`, so it overlaps
* the two and is meant for a caller asking "what binds", not for a tab row.
*/
export const DECISION_LANE_FILTERS = [
"candidates",
"governing",
"active",
"needs_review",
"uncheckable",
"history",
] as const;
export type DecisionLaneFilter = (typeof DECISION_LANE_FILTERS)[number];
/**
* Records per review lane.
*
* `candidates` and the four currency lanes partition the repository and sum to
* `total`; `governing` is the roll-up of the two that still bind.
*/
export interface DecisionLaneCounts {
candidates: number;
active: number;
needs_review: number;
uncheckable: number;
history: number;
governing: number;
total: number;
}
/**
* The review lanes, in tab order. They partition a repository: every record is
* in exactly one, and the five counts sum to the total.
*
* `governing` is deliberately absent. It is the roll-up of `active` and
* `needs_review`, so it overlaps two lanes; it lives in `DECISION_LANE_FILTERS`
* for a caller asking "what binds" and never in a tab row, because a tab row of
* overlapping datasets is one a reader cannot add up.
*/
export const DECISION_LANES = [
"active",
"candidates",
"needs_review",
"uncheckable",
"history",
] as const;
export type DecisionLane = (typeof DECISION_LANES)[number];
/** The capture presets a caller may set. `custom` is a reading, not a choice. */
export const DECISION_PRESETS = [
"default",
"off",
"local_only",
"balanced",
"full",
] as const;
/**
* What `record_acceptance` would refuse this record for, mirrored so a review
* surface can disable a control it knows will be refused instead of finding out
* from the error toast. Pinned against the Python contract by the vocabulary
* tests. The accepter-or-artifact identity check is not here: the
* reviewer supplies that at the moment they act, so it is never something the
* record is missing. `record_blockers` on the Python side asks the same way.
*
* `selfAuthored` is the exemption for a record somebody typed: they wrote the
* claim rather than reviewing an inference, so the entry is its own provenance.
* The engine grants it to `source === "cli"` when an accepter is known. It
* covers evidence only.
*
* The reason reads `rationale` then `context`, never `decision`: `context` is
* what forced the choice, `decision` is the choice itself, and letting the what
* stand in for the why is what marked empty records acceptable. Every record
* needs its `decision`, typed or mined: one that never says what was chosen
* binds nobody to anything. A server response fills a blank `decision` with the
* title for readers, so `decision_text_missing` is what says the stored text is
* blank.
*/
export function decisionAcceptanceBlockers(record: {
// Required so a caller cannot leave it out and have every record refused.
decision: string;
decision_text_missing?: boolean;
rationale?: string;
context?: string;
affected_files?: string[];
affected_modules?: string[];
evidence_commits?: string[];
evidence_file?: string | null;
source?: string;
kind?: string;
}): string[] {
const blockers: string[] = [];
const nonBlank = (values: (string | null | undefined)[]) =>
values.some((v) => (v ?? "").trim().length > 0);
const selfAuthored = record.source === "cli";
if (record.decision_text_missing || !nonBlank([record.decision])) {
blockers.push("no decision text: state what was chosen");
}
if (!nonBlank([record.rationale, record.context])) {
blockers.push("no rationale or explicit constraint reason");
}
// An agreement governs the repository rather than part of it, so naming no
// file is what it is rather than a gap in it. The server states that scope
// explicitly on the acceptance row; here it just means no blocker.
if (
record.kind !== "agreement" &&
!nonBlank(record.affected_files ?? []) &&
!nonBlank(record.affected_modules ?? [])
) {
blockers.push("no scope: name the files or modules it governs");
}
if (
!selfAuthored &&
!nonBlank(record.evidence_commits ?? []) &&
!nonBlank([record.evidence_file])
) {
blockers.push("no evidence reference");
}
return blockers;
}
/** Counts by status, from a grouped COUNT on the server. */
export interface DecisionCounts {
total: number;
active: number;
proposed: number;
superseded: number;
deprecated: number;
}
/** One capture source's capabilities and resolved state. */
export interface DecisionSourceState {
key: string;
label: string;
description: string;
/** `machine` for inferred capture, `human` for authority routes. */
authority: "machine" | "human";
deterministic: boolean;
supports_llm: boolean;
/** False for authority routes, which have no capture to switch off. */
togglable: boolean;
enabled: boolean;
llm_enabled: boolean;
status:
| "enabled"
| "disabled"
| "deterministic_only"
| "skipped_no_provider"
| "always_on";
reason: string;
}
export type DecisionPreset =
| "default"
| "off"
| "local_only"
| "balanced"
| "full"
| "custom";
/** Per-update ceiling on the one broad session-discovery call. */
export interface DecisionDiscoveryBudget {
max_sessions: number;
max_input_tokens: number;
}
/** A change to the discovery budget. Omitted fields keep their value. */
export type DecisionDiscoveryPatch = Partial<DecisionDiscoveryBudget>;
/** The resolved decision capture policy for one repository. */
export interface DecisionSettings {
enabled: boolean;
llm: boolean;
preset: DecisionPreset;
/**
* Whether an agent may grant a decision authority, as against withdrawing
* it. False is the shipped posture.
*/
agent_acceptance: boolean;
discovery: DecisionDiscoveryBudget;
sources: DecisionSourceState[];
provider_available: boolean;
warnings: string[];
/** Legacy config keys still honoured. A save replaces them. */
legacy_keys: string[];
/** Pass back on write to detect a concurrent edit. */
etag: string;
}
/** A change to one source. Omitted fields keep their current value. */
export interface DecisionSourcePatch {
enabled?: boolean;
llm?: boolean;
}
/** A partial policy write. Omitted fields keep their current value. */
export interface DecisionSettingsUpdate {
enabled?: boolean;
llm?: boolean;
preset?: Exclude<DecisionPreset, "custom">;
agent_acceptance?: boolean;
sources?: Record<string, DecisionSourcePatch>;
discovery?: DecisionDiscoveryPatch;
etag?: string;
}