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.

12.8 KB
Raw Blame
/**
 * Typed message contract between the extension host and the webviews.
 *
 * This module is imported by BOTH bundles (esbuild host bundle and the Vite
 * webview bundles), so it must stay free of 'vscode' imports and of any
 * runtime dependency beyond type-only imports. Webviews never fetch: every
 * data need is an RpcRequest the host serves from the shared api-client and
 * cache; everything else is a one-way notification.
 */

import type {
  ChurnComplexityResponse,
  HealthFilesQuery,
  HealthFilesResponse,
  HealthMapFeed,
  HealthMapQuery,
  HealthOverviewResponse,
  HealthTrendResponse,
} from "@repowise-dev/types/health";
import type { FileDetailResponse } from "@repowise-dev/types/files";
import type {
  ArchitectureGraphResponse,
  CommunityDetailResponse,
  CommunitySliceResponse,
  CommunitySummaryItem,
  DeadCodeGraphResponse,
  DecisionRecordResponse,
  ExecutionFlowsResponse,
  GraphExportResponse,
  GraphPathResponse,
  HotFilesGraphResponse,
  ModuleGraphResponse,
  NodeSearchResult,
  PageResponse,
} from "@repowise-dev/api-client/types";
import type { RiskRangeResponse } from "@repowise-dev/api-client/risk";
import type { PatchCoverageResponse } from "@repowise-dev/types/generated/http";
import type { ReviewerSuggestion } from "@repowise-dev/api-client/types";
import type { BlastRadiusResponse } from "@repowise-dev/types/blast-radius";
import type { ArchitectureView } from "@repowise-dev/ui/c4";
import type {
  RefactoringOpportunityDetail,
  RefactoringOpportunityPage,
  RefactoringPlan,
} from "@repowise-dev/types/refactoring";
import type { AiPromptFlavor } from "@repowise-dev/ui/health/ai-prompt-builder";

/** Every editor-tab webview panel the extension can open. */
export type PanelViewId =
  | "health"
  | "architecture"
  | "graph"
  | "refactoring"
  | "decisions"
  | "docs"
  | "risk"
  | "settings";

/** Panels plus the sidebar Home view (a WebviewView, never a tab). */
export type WebviewViewId = PanelViewId | "home";

/** Per-view open parameters, carried in the init message. */
export interface ViewParams {
  /** selectPath focuses the dashboard on one file (from the status-bar score). */
  health: { selectPath?: string };
  architecture: { selectPath?: string };
  graph: { selectNode?: string };
  refactoring: { planId?: string; filePath?: string };
  decisions: Record<string, never>;
  docs: { pageId?: string; filePath?: string };
  risk: Record<string, never>;
  settings: Record<string, never>;
  home: Record<string, never>;
}

/**
 * The settings the Settings panel can read and write. Kept in lockstep with
 * the `repowise.*` keys contributed in package.json (the extension-side source
 * of truth); the panel offers a friendlier grouped surface over the same keys,
 * and the host validates every write against this allowlist.
 */
export const SETTING_KEYS = [
  "diagnostics.enabled",
  "diagnostics.minSeverity",
  "diagnostics.dimensions",
  "docDrift.diagnostics.enabled",
  "docDrift.diagnostics.minConfidence",
  "gutterHeat.enabled",
  "fileDecorations.enabled",
  "fileDecorations.maxScore",
  "codeLens.enabled",
  "hover.enabled",
  "hover.symbolDetail",
  "server.autoStart",
  "server.port",
  "cliPath",
  "risk.baseBranch",
  "changeIntel.cochangeNudge",
  "changeIntel.cochangeMinScore",
  "agentHandoff.enabled",
  "agentTools.enabled",
] as const;

export type SettingKey = (typeof SETTING_KEYS)[number];

/** The value shapes a setting can hold across the whole allowlist. */
export type SettingValue = boolean | number | string | string[] | null;

/** Current value of every allowlisted setting, keyed by its `repowise.*` tail. */
export type SettingsValues = Record<SettingKey, SettingValue>;

/**
 * Webview color scheme. "auto" follows the editor theme; a fixed value pins
 * every Repowise webview regardless of the editor. Persisted host-side so all
 * views (and future opens) agree.
 */
export type ThemePreference = "auto" | "light" | "dark";

/** Repo facts the webview needs for labels and cache-busting. */
export interface RepoInit {
  id: string;
  name: string;
  headCommit: string | null;
  defaultBranch: string | null;
}

/**
 * Data the host can serve. One method per need; the webview client is a
 * Proxy over this interface and the host dispatcher implements it, so the
 * two sides cannot drift.
 */
export interface HostApi {
  // Health dashboard
  healthOverview(limit?: number): Promise<HealthOverviewResponse>;
  healthFiles(query?: HealthFilesQuery): Promise<HealthFilesResponse>;
  /** The bounded field the map draws, chosen by the server. */
  healthMap(query?: HealthMapQuery): Promise<HealthMapFeed>;
  healthTrend(limit?: number): Promise<HealthTrendResponse>;
  churnComplexity(limit?: number): Promise<ChurnComplexityResponse>;
  // Architecture map
  architectureView(): Promise<ArchitectureView>;
  fileContent(filePath: string): Promise<string>;
  // Knowledge graph
  moduleGraph(): Promise<ModuleGraphResponse>;
  fullGraph(limit?: number): Promise<GraphExportResponse>;
  architectureCommunityGraph(): Promise<ArchitectureGraphResponse>;
  communities(): Promise<CommunitySummaryItem[]>;
  communitySlice(communityId: number): Promise<CommunitySliceResponse>;
  communityDetail(communityId: number): Promise<CommunityDetailResponse>;
  /** Shortest path between two graph nodes (path finder panel). */
  graphPath(from: string, to: string): Promise<GraphPathResponse>;
  /** Node-name autocomplete for the path finder inputs. */
  searchNodes(query: string, limit?: number): Promise<NodeSearchResult[]>;
  deadCodeGraph(): Promise<DeadCodeGraphResponse>;
  hotFilesGraph(): Promise<HotFilesGraphResponse>;
  executionFlows(): Promise<ExecutionFlowsResponse>;
  // Refactoring
  /** The composed unit the web board and the agent contract both speak. */
  refactoringOpportunities(filePath?: string): Promise<RefactoringOpportunityPage>;
  refactoringOpportunity(opportunityId: string): Promise<RefactoringOpportunityDetail>;
  refactoringOpportunityPrompt(
    opportunityId: string,
    flavor: AiPromptFlavor,
  ): Promise<string>;
  refactoringPlan(suggestionId: string): Promise<RefactoringPlan>;
  /** Built host-side so the prompt matches the CodeLens copy path exactly. */
  refactoringPrompt(suggestionId: string, flavor: AiPromptFlavor): Promise<string>;
  // Decisions
  decisionsList(): Promise<DecisionRecordResponse[]>;
  // Docs
  pagesList(): Promise<PageResponse[]>;
  pageById(pageId: string): Promise<PageResponse>;
  fileDetail(relPath: string): Promise<FileDetailResponse>;
  // Change risk
  riskRange(): Promise<RiskRangeReport>;
  /** Impact of the current change set (uncommitted + unpushed). */
  changeImpact(): Promise<ChangeImpactReport>;
  // Sidebar home
  homeSummary(): Promise<HomeSummary>;
  // Settings panel
  /** Current value of every allowlisted setting. */
  getSettings(): Promise<SettingsValues>;
  /** Persist one setting, then echo the full fresh value map back. */
  updateSetting(key: SettingKey, value: SettingValue): Promise<SettingsValues>;
}

/**
 * The sidebar Home payload, aggregated host-side so one RPC serves the whole
 * view and only compact numbers cross the postMessage boundary. Sections are
 * independently nullable: one failing endpoint degrades its card, not the view.
 */
export interface HomeSummary {
  health: {
    /** Headline: NLOC-weighted health of the hotspot files. */
    hotspot: number | null;
    average: number | null;
    fileCount: number;
    openFindings: number;
    band: string | null;
    hotspotDelta: number | null;
    /** Hotspot-health history, oldest first, for the hero sparkline. */
    history: number[];
  } | null;
  counts: {
    refactoringPlans: number | null;
    decisions: number | null;
  };
  freshness: {
    /** Commit the index was built from (null when the server has none). */
    indexedCommit: string | null;
    /** Checked-out commit, or null when git cannot serve it. */
    liveCommit: string | null;
    /** True only when both commits are known and differ. */
    stale: boolean;
    branch: string | null;
    lastIndexedAt: string | null;
  };
}

/** Branch risk payload: the endpoint response plus the refs it compared. */
export interface RiskRangeReport {
  base: string;
  branch: string | null;
  result: RiskRangeResponse;
  /**
   * Patch coverage of the same base...HEAD range. Null when no coverage was
   * ingested, or when the fetch failed (an older server has no endpoint): the
   * panel then shows nothing rather than an error.
   */
  patchCoverage: PatchCoverageResponse | null;
}

/**
 * Impact of the working change set, assembled host-side from the blast-radius
 * and reviewer-suggestion endpoints. Shared verbatim by the Change Risk panel
 * and the ambient co-change nudge so there is one analysis, not two.
 */
export interface ChangeImpactReport {
  /** Repo-relative paths analyzed, sorted (the change-set signature source). */
  changed: string[];
  /** How many of the changed paths are staged / unstaged (working tree). */
  stagedCount: number;
  workingCount: number;
  /**
   * "branch" includes committed-but-unpushed changes (base..HEAD); "working"
   * is the uncommitted tree only. The panel asks for branch scope; the nudge
   * asks for working scope so it speaks to the file being edited right now.
   */
  scope: "branch" | "working";
  /** Blast analysis, or null when git is unavailable or nothing changed. */
  blast: BlastRadiusResponse | null;
  /** Reviewer suggestions for the changed set (names + reasons). */
  reviewers: ReviewerSuggestion[];
  /** True when git could not be read at all (distinct from a clean tree). */
  gitUnavailable: boolean;
}

export type HostApiMethod = keyof HostApi;

// ---------------------------------------------------------------------------
// Envelopes
// ---------------------------------------------------------------------------

/** Webview -> host: invoke a HostApi method. */
export interface RpcRequestMessage {
  kind: "rpc-request";
  id: number;
  method: HostApiMethod;
  args: unknown[];
}

/** Host -> webview: RPC outcome. */
export interface RpcResponseMessage {
  kind: "rpc-response";
  id: number;
  ok: boolean;
  /** Present when ok. */
  result?: unknown;
  /** Present when not ok; already user-presentable. */
  error?: string;
}

/** Webview -> host: bootstrapped and listening; host replies with init. */
export interface ReadyMessage {
  kind: "ready";
}

/** Host -> webview: everything the view needs to render. */
export interface InitMessage<V extends WebviewViewId = WebviewViewId> {
  kind: "init";
  view: V;
  repo: RepoInit;
  params: ViewParams[V];
  theme: ThemePreference;
}

/**
 * Host -> webview: the index moved under the panel (repowise update finished
 * or HEAD changed). Views refetch what they show; repo.headCommit is fresh.
 */
export interface RefreshMessage {
  kind: "refresh";
  repo: RepoInit;
}

/** Webview -> host: open a repo file in an editor column. */
export interface OpenFileMessage {
  kind: "open-file";
  /** Repo-relative path. */
  path: string;
  /** 1-based line to reveal. */
  line?: number;
}

/** Webview -> host: put text on the clipboard and confirm via toast. */
export interface CopyTextMessage {
  kind: "copy-text";
  text: string;
  /** Confirmation toast; defaults to a generic one. */
  toast?: string;
}

/** Webview -> host: open an external URL in the default browser. */
export interface OpenExternalMessage {
  kind: "open-external";
  url: string;
}

/** Webview -> host: open (or reveal) an editor-tab panel. Sent by Home. */
export interface OpenViewMessage {
  kind: "open-view";
  view: PanelViewId;
  params?: ViewParams[PanelViewId];
}

/** Webview -> host: reveal the sidebar Home view. Sent by a panel's chrome. */
export interface FocusHomeMessage {
  kind: "focus-home";
}

/** Webview -> host: open the native Settings editor filtered to the extension. */
export interface OpenNativeSettingsMessage {
  kind: "open-native-settings";
}

/** Webview -> host: run an incremental index update. Sent by Home. */
export interface UpdateIndexMessage {
  kind: "update-index";
}

/** Webview -> host: persist a theme preference. Sent by Home's switcher. */
export interface SetThemeMessage {
  kind: "set-theme";
  theme: ThemePreference;
}

/** Host -> webview: the theme preference changed; every open view applies it. */
export interface ThemeChangedMessage {
  kind: "theme-changed";
  theme: ThemePreference;
}

/**
 * Host -> webview: the requested index update finished (either way). The view
 * refetches its summary; a successful update also arrives as a refresh.
 */
export interface UpdateDoneMessage {
  kind: "update-done";
}

export type WebviewToHostMessage =
  | ReadyMessage
  | RpcRequestMessage
  | OpenFileMessage
  | CopyTextMessage
  | OpenExternalMessage
  | OpenViewMessage
  | FocusHomeMessage
  | OpenNativeSettingsMessage
  | UpdateIndexMessage
  | SetThemeMessage;

export type HostToWebviewMessage =
  | InitMessage
  | RefreshMessage
  | RpcResponseMessage
  | UpdateDoneMessage
  | ThemeChangedMessage;