Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

20.7 KB
Raw Blame
/**
 * 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;
}