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.

10.0 KB
Raw Blame
/**
 * Canonical symbol types.
 *
 * Canonical source: engine `SymbolResponse`. Some downstream backends emit a
 * leaner shape that omits `repository_id` and `symbol_id` — consumer-side
 * adapters synthesise both before passing data to components.
 */

import type { ResolutionOriginWire } from "./graph";

export type SymbolKind =
  | "function"
  | "method"
  | "class"
  | "interface"
  | "struct"
  | "enum"
  | "trait"
  | "module"
  | "variable"
  | "type"
  | (string & {});

export type SymbolVisibility = "public" | "private" | "protected" | (string & {});

/**
 * Transparent breakdown of the composite importance score. Mirrors the
 * server's ``SymbolImportanceComponents``; lets the UI explain *why* a
 * symbol ranks where it does (tooltip on the score chip).
 */
export interface SymbolImportanceComponents {
  file_pagerank: number;
  visibility_factor: number;
  complexity_norm: number;
  kind_boost: number;
  is_entry_point: boolean;
}

/** Renamed `CodeSymbol` to avoid shadowing the global `Symbol`. */
export interface CodeSymbol {
  id: string;
  repository_id: string;
  file_path: string;
  symbol_id: string;
  name: string;
  qualified_name: string;
  kind: SymbolKind;
  signature: string;
  start_line: number;
  end_line: number;
  docstring: string | null;
  visibility: SymbolVisibility;
  is_async: boolean;
  complexity_estimate: number;
  language: string;
  parent_name: string | null;
  /** Composite importance score (0–1ish). Populated by the list endpoint. */
  importance_score?: number | null;
  importance_components?: SymbolImportanceComponents | null;
  /** File-level signals — populated by the list endpoint via JOINs. */
  file_pagerank?: number | null;
  is_entry_point?: boolean | null;
  file_churn_percentile?: number | null;
  file_is_hotspot?: boolean | null;
  /** Function-blame join — populated by the list/detail endpoints when a
   *  git_function_blame row exists for the symbol. */
  blame_mod_count?: number | null;
  blame_recent_mod_count?: number | null;
  blame_median_author_time?: number | null;
  blame_owner_name?: string | null;
  blame_owner_line_pct?: number | null;
  /** Counted bug fixes attributed to this symbol, populated by the list
   *  endpoint from the per-file rollup. Null when the index predates it,
   *  0 when it ran and found no fixes here. */
  fix_count?: number | null;
}

// ---------------------------------------------------------------------------
// Symbol detail (the symbol entity page aggregate)
// ---------------------------------------------------------------------------

export interface SymbolCallEntry {
  symbol_id: string;
  name: string;
  kind: string;
  file: string;
  start_line: number | null;
  edge_type: string;
  confidence: number;
  /** Absent on an index built before origins were stamped. */
  resolution_origin?: ResolutionOriginWire | null;
}

/**
 * Which side of the symbol a relation sits on. `in` means the other symbol
 * reaches this one.
 */
export type SymbolRelationDirection = "in" | "out";

/**
 * One relation kind on one side of a symbol, with the count it was cut from.
 *
 * `total` is counted unbounded while `rows` is capped, so a surface reports
 * "10 of 1,516" rather than rendering the cap as if it were the answer.
 * `group` partitions `edge_type` into the four families the engine's
 * `SYMBOL_USE_EDGE_TYPES` covers; `symbol-relations.ts` in `@repowise-dev/ui`
 * is the only place either becomes English.
 */
export interface SymbolRelationGroup<Row = SymbolCallEntry> {
  direction: SymbolRelationDirection;
  edge_type: string;
  group: "heritage" | "wiring" | "reference";
  total: number;
  rows: Row[];
}

export interface SymbolDetailGraph {
  pagerank: number;
  in_degree: number;
  out_degree: number;
  /** `calls` edges only. Every other relation kind is in `relations`. */
  callers: SymbolCallEntry[];
  callees: SymbolCallEntry[];
  /** True `calls` counts. `callers.length` is the row cap, not the count.
   *  Absent on a backend that predates the split, so a surface must fall back
   *  to the array length rather than rendering `undefined`. */
  caller_total?: number;
  callee_total?: number;
  /** Heritage, framework wiring and references, each named and counted
   *  separately. Absent on an older backend. */
  relations?: SymbolRelationGroup[];
}

export interface SymbolFileContext {
  file_path: string;
  health_score: number | null;
  is_hotspot: boolean | null;
  primary_owner: string | null;
  language: string;
}

export interface SymbolDetailResponse {
  symbol: CodeSymbol;
  graph: SymbolDetailGraph;
  governing_decisions: { id: string; title: string; status: string }[];
  file_context: SymbolFileContext;
  /** Counted bug fixes attributed to this symbol, and the file's last counted
   *  fix. Both null on an index that predates the fix-event rollup. */
  fix_count?: number | null;
  fix_last_at?: string | null;
}

export interface SymbolList {
  total: number;
  symbols: CodeSymbol[];
}

// ---------------------------------------------------------------------------
// Unified symbol-detail shape (drawer + route render the same body)
// ---------------------------------------------------------------------------

/** A caller/callee edge in the normalized symbol body. */
export interface SymbolBodyCall {
  symbol_id: string;
  name: string;
  file: string;
  edge_type: string;
  confidence?: number | null;
  resolution_origin?: ResolutionOriginWire | null;
}

/** Graph-intelligence block for the unified body (optional — degrades when absent). */
export interface SymbolBodyGraph {
  in_degree: number;
  out_degree: number;
  /** `calls` edges only — see `SymbolDetailGraph.callers`. */
  callers: SymbolBodyCall[];
  callees: SymbolBodyCall[];
  caller_total?: number;
  callee_total?: number;
  relations?: SymbolRelationGroup<SymbolBodyCall>[];
  pagerank_percentile?: number | null;
  betweenness_percentile?: number | null;
  /** False when the symbol appeared after the last exact centrality scoring. */
  betweenness_scored?: boolean;
  community_label?: string | null;
  entry_point_score?: number | null;
}

/** File-level git intelligence for the unified body (optional). */
export interface SymbolBodyGit {
  primary_owner_name: string | null;
  primary_owner_commit_pct?: number | null;
  recent_owner_name?: string | null;
  bus_factor?: number | null;
  contributor_count?: number | null;
  commit_count_90d?: number | null;
  is_hotspot?: boolean | null;
  churn_percentile?: number | null;
}

export interface SymbolBodyCoChange {
  file_path: string;
  co_change_count: number;
}

export interface SymbolBodyDeadFinding {
  id: string;
  kind: string;
  reason: string;
  lines: number | null;
  safe_to_delete: boolean;
}

/**
 * The single normalized shape rendered by `SymbolDetailBody`. Both the drawer
 * (`CodeSymbol` + graph/git APIs) and the route (`SymbolDetailResponse`)
 * normalize into this so they expose the same capabilities. Every block beyond
 * `identity` is optional so a surface that lacks a feed degrades gracefully.
 */
export interface SymbolDetailData {
  identity: {
    name: string;
    qualified_name?: string | null;
    kind: SymbolKind;
    visibility?: SymbolVisibility | null;
    language?: string | null;
    is_async?: boolean | null;
    file_path: string;
    start_line: number;
    parent_name?: string | null;
    file_is_hotspot?: boolean | null;
  };
  signature?: string | null;
  docstring?: string | null;
  importance_score?: number | null;
  complexity_estimate?: number | null;
  blame_mod_count?: number | null;
  blame_recent_mod_count?: number | null;
  blame_median_author_time?: number | null;
  blame_owner_name?: string | null;
  blame_owner_line_pct?: number | null;
  /** Counted bug fixes whose replaced lines landed in this symbol, over the
   *  same 6-month window as `prior_defect_count`. Approximate by construction:
   *  symbol spans are current-tree while each fix's ranges are numbered on its
   *  own parent commit, so any surface showing it must hedge. `fix_last_at` is
   *  the file's most recent counted fix, because a count without recency reads the
   *  same at two weeks and two years. */
  fix_count?: number | null;
  fix_last_at?: string | null;
  graph?: SymbolBodyGraph | null;
  /** Heritage relations (extends/implements + extended-by). Renders when present. */
  heritage?: SymbolHeritage | null;
  git?: SymbolBodyGit | null;
  co_changes?: SymbolBodyCoChange[];
  dead_code?: SymbolBodyDeadFinding[];
  governing_decisions?: { id: string; title: string; status: string }[];
  file_context?: {
    health_score?: number | null;
    language?: string | null;
  } | null;
}

// ---------------------------------------------------------------------------
// Heritage (extends / implements / trait_impl / mixin / overrides)
// ---------------------------------------------------------------------------

/**
 * Heritage relation kinds. Mirrors the engine's edge_type values for
 * heritage edges in the symbol graph plus the raw AST-level "mixin" kind.
 */
export type HeritageKind =
  | "extends"
  | "implements"
  | "trait_impl"
  | "mixin"
  | "method_overrides"
  | "method_implements";

/**
 * A single resolved heritage edge.
 *
 * `child_id` and `parent_id` are symbol-graph node IDs (e.g.
 * `src/app.py::MyClass`). `confidence` is present for resolved relations
 * (0.0–1.0) and absent for raw, unresolved entries lifted directly out of
 * `parsed_files.json::heritage` (in which case only `child_name`,
 * `parent_name`, `kind`, and `line` are meaningful).
 */
export interface HeritageRelation {
  child_id?: string;
  parent_id?: string;
  child_name: string;
  parent_name: string;
  kind: HeritageKind;
  line: number;
  confidence?: number;
}

/**
 * Heritage view for a single symbol — both directions of the relation.
 *
 * `parents` are the relations where this symbol is the child (i.e. what it
 * extends/implements). `children` are the relations where this symbol is the
 * parent (i.e. what extends/implements it).
 */
export interface SymbolHeritage {
  symbol_id: string;
  parents: HeritageRelation[];
  children: HeritageRelation[];
}