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.

7.8 KB
Raw Blame
/**
 * Canonical documentation-drift types.
 *
 * Canonical source: the engine's `DocDriftResponse` / `DocDriftReferencesResponse`
 * (`packages/server/src/repowise/server/schemas/doc_drift.py`), emitted verbatim
 * by the route. Nothing here is a normalisation of the wire: a client that
 * reshapes this contract is a client that recomputes the summary, and the
 * summary is served precisely so it cannot be recomputed from a page.
 *
 * The vocabulary carries a claim, and the claims are not the same size:
 * a *finding* says a document asserts something the repository no longer
 * satisfies, and is filed against the document. A *reference* says only that a
 * document names a file the repository still has. It never says the document
 * describes that file.
 */

/**
 * Why a drift answer could not be given.
 *
 * Not an error state. `not_computed` means the drift pass has never run on
 * this index, which must not render as a repository with clean documentation;
 * `index_predates_doc_drift` means the index is older than the store;
 * `drift_read_failed` is anything else, and is separate because "reindex" is
 * the wrong advice for a locked database.
 *
 * Mirrors `UNAVAILABLE_NOT_COMPUTED` / `UNAVAILABLE_NO_TABLE` /
 * `UNAVAILABLE_READ_FAILED` in `core/analysis/doc_drift/constants.py`, pinned
 * by `tests/unit/doc_drift/test_ts_contract_parity.py`.
 */
export type DocDriftUnavailable =
  | "not_computed"
  | "index_predates_doc_drift"
  | "drift_read_failed";

/**
 * The reference classes the detector ships.
 *
 * `symbol` flags only an identifier git proves was a symbol definition when
 * the document line was written and is defined nowhere now. It needs an index,
 * so an index-free run reports the other four.
 */
export type DocDriftKind = "path" | "link" | "anchor" | "command" | "symbol";

/**
 * The one set of confidence boundaries, mirroring the engine.
 *
 * `HIGH` is `HIGH_CONFIDENCE_THRESHOLD` and `MEDIUM` is
 * `REVIEW_CONFIDENCE_THRESHOLD` in `core/analysis/doc_drift/constants.py`,
 * which are themselves held equal to dead code's boundaries so that "high"
 * means one thing to a reader comparing the two reports.
 *
 * Duplicated across languages rather than derived, and pinned by a parity
 * test, because three surfaces disagreeing about where "high" starts is a
 * failure this repository has already had once
 * (`tests/unit/dead_code/test_confidence_parity.py`).
 */
export const DOC_DRIFT_CONFIDENCE = {
  /** At or above this, a finding is near-certain. */
  HIGH: 0.7,
  /** The default floor; below it findings are not fetched. */
  MEDIUM: 0.4,
} as const;

/** Which tier a confidence falls in, using the boundaries above. */
export function docDriftConfidenceTier(confidence: number): "high" | "medium" | "low" {
  if (confidence >= DOC_DRIFT_CONFIDENCE.HIGH) return "high";
  if (confidence >= DOC_DRIFT_CONFIDENCE.MEDIUM) return "medium";
  return "low";
}

/**
 * What each reference class is, in a reader's words.
 *
 * The slugs are an API vocabulary, not English: a table column headed `anchor`
 * tells a reader nothing about a heading link whose heading was renamed.
 * Keyed on every value `DocDriftKind` can take, pinned by the same parity test.
 */
export const DOC_DRIFT_KIND_LABELS: Record<DocDriftKind, string> = {
  path: "File path",
  link: "Link",
  anchor: "Heading link",
  command: "Command",
  symbol: "Symbol",
};

/** Label for one reference class, falling back to the raw slug. */
export function docDriftKindLabel(kind: string): string {
  return DOC_DRIFT_KIND_LABELS[kind as DocDriftKind] ?? kind;
}

/**
 * How a finding's suggested replacement was found, in a reader's words.
 *
 * Keys mirror `SuggestionBasis` in `core/analysis/doc_drift/constants.py`,
 * pinned by `tests/unit/doc_drift/test_ts_contract_parity.py`.
 */
export const SUGGESTION_BASIS_LABELS: Readonly<Record<string, string>> = {
  package_split: "Became a package",
  git_rename: "Renamed in git",
  similar_heading: "Similar heading",
  similar_target: "Similar target",
  symbol_rename: "Renamed symbol",
};

export interface DocDriftFinding {
  /**
   * Stable across stores and rebuilds, derived from
   * `(file_path, kind, line_number, target)`. The row's own primary key is an
   * autoincrement integer and is re-minted whenever a store is rebuilt, so it
   * is this id that a client keys triage on.
   */
  id: string;
  /**
   * The *document* that is wrong, and the file a reader has to edit. Never the
   * target it names. Rendering this as the broken code file tells the reader
   * the opposite of the truth.
   */
  file_path: string;
  line_number: number;
  kind: string;
  /** What the document claims exists. */
  target: string;
  confidence: number;
  /** Which named resolution strategy produced this. */
  origin: string;
  /** One human sentence. */
  reason: string;
  /** The reference exactly as written. */
  raw: string;
  /** The source line, trimmed, so a finding can be judged without opening the file. */
  context: string;
  /** Lines a reader can check for themselves. */
  evidence: string[];
  /** Line-independent key a CI baseline holds; survives edits above the finding. */
  fingerprint: string;
  /** What the missing target is likely called now. Evidence, never a verdict. */
  suggestion?: string | null;
  /** Key of `SUGGESTION_BASIS_LABELS` naming how `suggestion` was found. */
  suggestion_basis?: string | null;
  /**
   * When first found, carried across updates. `null` when it was present at
   * the first check, or when the store keeps no history.
   */
  first_seen_at?: string | null;
  /** First found by the latest update that stored a finding. */
  is_new?: boolean;
}

/**
 * The rollup above a findings list, computed server-side over the same rows.
 *
 * `findings_total` counts every finding matching the query, including any the
 * display cap left out, so a client must not recompute these numbers from the
 * page it holds.
 */
export interface DocDriftSummary {
  findings_total: number;
  /** Distinct documents carrying at least one finding. */
  documents: number;
  confidence: Record<string, number>;
  by_kind: Record<string, number>;
  /**
   * What the counts do and do not cover. Most references in a real tree are
   * uncheckable by design, so no surface may show the counts without it.
   */
  findings_basis: string;
  /** Of `findings_total`, how many are new since the last update; `null` without history. */
  new_since_last_update?: number | null;
}

export interface DocDriftResponse {
  findings: DocDriftFinding[];
  /** Rows served after the cap; below `summary.findings_total` when capped. */
  findings_emitted: number;
  /** Null exactly when `unavailable` is set. */
  summary: DocDriftSummary | null;
  unavailable: DocDriftUnavailable | null;
}

/** A document that names a file the repository still has. */
export interface DocDriftReference {
  document: string;
  line: number;
  kind: string;
  /** The enclosing heading trail, so a reader can find the passage. */
  section?: string;
}

/**
 * A naming document that carries drift somewhere in it.
 *
 * `findings` counts the whole document. A drifted reference resolves to
 * nothing, so this can never mean "this document's description of your file is
 * wrong", and a surface that words it that way is lying.
 */
export interface DocDriftDocumentDrift {
  document: string;
  findings: number;
}

export interface DocDriftReferencesResponse {
  target_path: string;
  references: DocDriftReference[];
  /** Rows served after the cap; below `references_total` when capped. */
  references_emitted: number;
  /** Every reference to the target, so a capped list cannot read as complete. */
  references_total: number;
  /** Distinct documents naming the target, before any display cap. */
  documents: number;
  documents_with_drift: DocDriftDocumentDrift[];
  /** What a reference claims, and what its absence does not prove. */
  references_basis: string;
  unavailable: DocDriftUnavailable | null;
}