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 graph types — file/module dependency graph plus graph-intelligence
* surfaces (callers/callees, communities, execution flows, metrics).
*
* Canonical source: engine `PipelineResult.graph` (NetworkX node_link_data
* format) and the per-symbol intelligence endpoints in
* `packages/server/src/repowise/server/schemas.py`.
*
* Some downstream backends emit a looser `{ nodes, links, directed?, multigraph? }`
* shape; consumer-side adapters are responsible for converting that to
* `GraphExport` below before passing data to components.
*/
// The relation vocabulary lives beside the symbol types that define it, so
// `CallersCallees` below borrows it rather than restating the group union.
import type { SymbolRelationGroup } from "./symbols";
// ---------------------------------------------------------------------------
// Core node + link
// ---------------------------------------------------------------------------
export interface GraphNode {
node_id: string;
node_type: string;
language: string;
symbol_count: number;
pagerank: number;
betweenness: number;
community_id: number;
is_test: boolean;
is_entry_point: boolean;
has_doc: boolean;
/** Cross-link signals — added in Phase A enrichment. All optional for
* back-compat with older backends; consumers should default to false/null. */
is_hotspot?: boolean;
churn_percentile?: number | null;
is_dead?: boolean;
dead_confidence?: number | null;
has_decision?: boolean;
primary_owner?: string | null;
}
export interface GraphLink {
source: string;
target: string;
imported_names: string[];
/** Edge kind from v0.4.0 framework-aware extractors (e.g. "spring.bean", "rails.route").
* `null` is a real value on the wire — the server's `GraphEdgeResponse` declares
* it optional-but-nullable — so a consumer reading it has to handle both. */
edge_type?: string | null;
/** Confidence score for resolved symbol-level call edges (v0.4.x). */
confidence?: number;
}
export interface GraphExport {
nodes: GraphNode[];
links: GraphLink[];
/** Server flagged response as capped (PageRank fill + reserved dead/hot/flow
* slots). UI should banner. */
truncated?: boolean;
total_node_count?: number;
/** Signal-overlay counts: repo-wide totals vs how many nodes are in this
* response. Lets the UI say "12 of 37 dead files in view" and distinguish
* "none in the repo" from "none in the loaded view". Optional — older
* backends and endpoints that don't compute them omit these. */
dead_total?: number | null;
dead_in_view?: number | null;
hot_total?: number | null;
hot_in_view?: number | null;
}
// ---------------------------------------------------------------------------
// Architecture (community super-node) graph
// ---------------------------------------------------------------------------
export interface ArchitectureNode {
community_id: number;
label: string;
/** Decays with size; kept for older servers. Read `conductance` instead. */
cohesion: number;
/** Share of this group's dependency volume that leaves it, lower is tighter.
* Absent or null on an older index. */
conductance?: number | null;
/** Members in the requested population; every figure is over them. */
member_count: number;
/** Members the population filter left out. */
hidden_member_count?: number;
top_file: string;
avg_pagerank: number;
hotspot_count: number;
dead_count: number;
has_decision: boolean;
doc_coverage_pct: number;
languages: string[];
}
export interface ArchitectureEdge {
source: number;
target: number;
edge_count: number;
}
/** Which non-production files a community view counts. All off = production only. */
export interface GraphPopulation {
tests: boolean;
examples: boolean;
docs: boolean;
}
export const PRODUCTION_ONLY: GraphPopulation = { tests: false, examples: false, docs: false };
/** What the map is counting. Category totals are always reported. */
export interface PopulationBreakdown {
total: number;
visible: number;
tests?: number;
examples?: number;
docs?: number;
include_tests?: boolean;
include_examples?: boolean;
include_docs?: boolean;
}
/** Visible files in no drawn community. `files` is the head by PageRank. */
export interface UnclusteredFiles {
file_count: number;
files?: string[];
}
export interface ArchitectureGraph {
nodes: ArchitectureNode[];
edges: ArchitectureEdge[];
/** Both absent on an older server. */
population?: PopulationBreakdown | null;
unclustered?: UnclusteredFiles | null;
}
// ---------------------------------------------------------------------------
// Community slice (constellation blossom — one hub's member sub-graph)
// ---------------------------------------------------------------------------
export interface CommunitySliceNode extends GraphNode {
/** True for one-hop neighbor stubs outside the community (cross-cluster). */
is_boundary?: boolean;
}
export interface CommunitySlice {
nodes: CommunitySliceNode[];
links: GraphLink[];
community_id: number;
member_count: number;
truncated?: boolean;
hidden_member_count?: number;
}
// ---------------------------------------------------------------------------
// NetworkX-shaped raw payload (what some downstream backends emit)
// ---------------------------------------------------------------------------
export interface RawGraphNode {
id?: string;
node_id?: string;
label?: string;
type?: string;
language?: string;
loc?: number;
is_test?: boolean;
is_config?: boolean;
is_entry_point?: boolean;
community?: number;
community_id?: number;
pagerank?: number;
betweenness?: number;
symbol_count?: number;
has_doc?: boolean;
[extra: string]: unknown;
}
export interface RawGraphLink {
source: string;
target: string;
kind?: string;
weight?: number;
confidence?: number;
imported_names?: string[];
edge_type?: string;
[extra: string]: unknown;
}
export interface RawGraph {
nodes: RawGraphNode[];
links?: RawGraphLink[];
edges?: RawGraphLink[];
directed?: boolean;
multigraph?: boolean;
}
export interface RawGraphResponse {
graph: RawGraph;
pagerank: Record<string, number>;
betweenness: Record<string, number>;
communities: Record<string, number>;
}
// ---------------------------------------------------------------------------
// Module rollup
// ---------------------------------------------------------------------------
export interface ModuleNode {
module_id: string;
file_count: number;
symbol_count: number;
avg_pagerank: number;
doc_coverage_pct: number;
hotspot_count?: number;
dead_count?: number;
has_decision?: boolean;
primary_owner?: string | null;
}
export interface ModuleEdge {
source: string;
target: string;
edge_count: number;
}
export interface ModuleGraph {
nodes: ModuleNode[];
edges: ModuleEdge[];
}
// ---------------------------------------------------------------------------
// Ego (neighborhood) graph
// ---------------------------------------------------------------------------
export interface EgoGraph {
nodes: GraphNode[];
links: GraphLink[];
center_node_id: string;
/** Optional git metadata for the center file. Present when the engine has indexed git history. */
center_git_meta?: import("./git.js").GitMetadata | null;
inbound_count: number;
outbound_count: number;
}
// ---------------------------------------------------------------------------
// Path finder
// ---------------------------------------------------------------------------
export interface GraphPath {
path: string[];
distance: number;
explanation: string;
visual_context?: unknown;
}
/**
* Lightweight node-search result used by the path finder autocomplete.
* Mirrors `NodeSearchResultResponse` from the engine.
*/
export interface NodeSearchResult {
node_id: string;
language: string;
symbol_count: number;
}
// ---------------------------------------------------------------------------
// Symbol-level intelligence (v0.4.x)
// ---------------------------------------------------------------------------
export interface SymbolNodeSummary {
symbol_id: string;
name: string;
kind: string;
file: string;
start_line?: number | null;
signature?: string | null;
}
/**
* Which resolution strategy produced a `calls` edge. Closed vocabulary owned
* by `ingestion/models.py::ResolutionOrigin`; the two are edited together.
* Render via `originDescriptor` (`@repowise-dev/ui/graph/edge-provenance`) —
* which origins count as a guess is one decision and lives in one place.
*/
export type ResolutionOrigin =
| "same_file"
| "self_scope"
| "enclosing_class"
| "receiver_same_file"
| "same_package"
| "import_scoped"
| "receiver_same_package"
| "package_alias"
| "module_alias"
| "crate_root"
| "receiver_import"
| "import_merged"
| "scoped_name"
| "same_target"
| "receiver_global"
| "global_unique"
| "receiver_typed_same_file"
| "receiver_typed_same_package"
| "receiver_typed_import"
| "receiver_typed_global"
| "receiver_field_same_file"
| "receiver_field_same_package"
| "receiver_field_import"
| "receiver_field_global"
| "receiver_framework_same_file"
| "receiver_framework_same_package"
| "receiver_framework_import"
| "receiver_framework_global"
| "receiver_extension_same_file"
| "receiver_extension_import"
| "receiver_extension_global"
| "receiver_chain_same_file"
| "receiver_chain_import"
| "return_type_same_file"
| "return_type_same_package"
| "return_type_import"
| "return_type_global"
| "self_inherited"
| "enclosing_inherited";
/**
* An origin as received, not as declared. An index outlives the bundle reading
* it, so a newer indexer can stamp a word this build predates —
* `originDescriptor` degrades those rather than throwing. Same `(string & {})`
* escape as `SymbolKind`: autocomplete on the vocabulary, no lie about the wire.
*/
export type ResolutionOriginWire = ResolutionOrigin | (string & {});
/**
* What stopped a traced flow. Closed vocabulary owned by
* `analysis/execution_flows.py::FlowTermination`. A trace that merely ends
* reads as "execution ends here" whether it does or whether the walk ran out
* of things it could follow; this keeps those apart.
*/
export type FlowTermination =
| "depth_limit"
| "callees_truncated"
| "cycle"
| "confidence_filtered"
| "excluded_target"
| "no_callees";
/** A termination as received. See `ResolutionOriginWire`. */
export type FlowTerminationWire = FlowTermination | (string & {});
export interface CallerCalleeEntry {
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;
}
export interface CallersCallees {
symbol_id: string;
symbol: SymbolNodeSummary;
/** `calls` edges only. Every other relation kind is in `relations`. */
callers: CallerCalleeEntry[];
callees: CallerCalleeEntry[];
/** True totals, not the number of rows served. */
caller_count: number;
callee_count: number;
truncated: boolean;
/** Heritage, framework wiring and references, each named and counted.
* Absent on a backend that predates the split. */
relations?: SymbolRelationGroup<CallerCalleeEntry>[];
}
// ---------------------------------------------------------------------------
// Communities (Leiden — v0.4.0)
// ---------------------------------------------------------------------------
export interface CommunityMember {
path: string;
pagerank: number;
is_entry_point: boolean;
/** Cross-link signals, so a count can name the files behind it. Optional: an
* older server omits them, which reads as "no signal", not as "not flagged". */
is_hotspot?: boolean;
is_dead?: boolean;
}
export interface NeighboringCommunity {
community_id: number;
label: string;
cross_edge_count: number;
}
export interface CommunityDetail {
community_id: number;
label: string;
/** Decays with size; kept for older servers. The panel reads `conductance`. */
cohesion: number;
/** Share of this group's dependency volume that leaves it, lower is tighter.
* Absent or null on an older index. */
conductance?: number | null;
/** Members in the requested population; every count is over them. */
member_count: number;
hidden_member_count?: number;
members: CommunityMember[];
truncated: boolean;
neighboring_communities: NeighboringCommunity[];
/** State of the area rather than its shape. Every field below is optional:
* additive on the wire, and absent from an older server.
*
* LOC-weighted mean health over the members that carry a score, 0-10, higher
* is better. `null` when none do — which is not zero and must not render as
* a score. */
health_score?: number | null;
/** How many members contributed to `health_score`. */
scored_member_count?: number;
/** Members flagged hot / dead / decision-anchored, over every member — not
* only the page returned in `members`. */
hot_count?: number;
dead_count?: number;
decision_count?: number;
/** Who is primary owner on the most members, and how many. "Most files
* owned", not "most commits" — see the router comment. */
primary_owner?: string | null;
primary_owner_file_count?: number;
}
export interface CommunitySummaryItem {
community_id: number;
label: string;
cohesion: number;
conductance?: number | null;
member_count: number;
hidden_member_count?: number;
top_file: string;
}
// ---------------------------------------------------------------------------
// Graph metrics + execution flows
// ---------------------------------------------------------------------------
export interface GraphMetrics {
target: string;
node_type: string;
pagerank: number;
pagerank_percentile: number;
betweenness: number;
betweenness_percentile: number;
/** False when the node appeared after the last exact centrality scoring. */
betweenness_scored?: boolean;
community_id: number;
community_label: string | null;
is_entry_point: boolean;
in_degree: number;
out_degree: number;
entry_point_score?: number | null;
kind?: string | null;
file?: string | null;
}
export interface ExecutionFlowEntry {
entry_point: string;
entry_point_name: string;
entry_point_score: number;
trace: string[];
depth: number;
crosses_community: boolean;
communities_visited: number[];
/** Why the trace stopped. Absent on an index that carries no terminations. */
termination?: FlowTerminationWire | null;
/** For `confidence_filtered` only: declined origin -> count. */
termination_detail?: Record<string, number> | null;
/**
* Origin per hop, pairwise with `trace`, so `trace_via[i]` describes the hop
* from `trace[i]` to `trace[i + 1]` and the array is one shorter. Omitted
* when no hop carries one.
*/
trace_via?: (ResolutionOriginWire | null)[] | null;
}
export interface ExecutionFlows {
total_entry_points: number;
flows: ExecutionFlowEntry[];
}