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
import * as vscode from "vscode";
import {
getChurnComplexity,
getHealthOverview,
getHealthTrend,
getHealthMap,
listHealthFiles,
} from "@repowise-dev/api-client/code-health";
import { getArchitectureView } from "@repowise-dev/api-client/c4";
import { getFileContent, getFileDetail } from "@repowise-dev/api-client/files";
import {
getArchitectureCommunityGraph,
getCommunities,
getCommunityDetail,
getCommunitySlice,
getDeadCodeGraph,
getExecutionFlows,
getGraph,
getGraphPath,
getHotFilesGraph,
getModuleGraph,
searchNodes,
} from "@repowise-dev/api-client/graph";
import {
getRefactoringOpportunities,
getRefactoringOpportunity,
getRefactoringPlan,
getRefactoringTargets,
} from "@repowise-dev/api-client/refactoring";
import { listDecisions } from "@repowise-dev/api-client/decisions";
import { getPageById, listAllPages } from "@repowise-dev/api-client/pages";
import { getPatchCoverage, getRiskRange } from "@repowise-dev/api-client/risk";
import { CONFIG_SECTION } from "../constants";
import {
SETTING_KEYS,
type HomeSummary,
type HostApi,
type RiskRangeReport,
type SettingKey,
type SettingsValues,
type SettingValue,
} from "../shared/webviewMessages";
import type { RepowiseContext } from "./context";
import { analyzeChange } from "./changeAnalysis";
import { commitsMatch, getCurrentBranchName, resolveLiveHead } from "./gitApi";
import { opportunityPrompt, planPrompt } from "./planPrompt";
/** Thrown by the dispatcher when a request arrives while disconnected. */
class NotReadyError extends Error {
constructor() {
super("The Repowise server is not connected.");
}
}
/** Defaults mirrored from the package.json contribution, for a robust read. */
const SETTING_DEFAULTS: SettingsValues = {
"diagnostics.enabled": true,
"diagnostics.minSeverity": "high",
"diagnostics.dimensions": ["defect", "maintainability", "performance"],
"docDrift.diagnostics.enabled": true,
"docDrift.diagnostics.minConfidence": 0.7,
"gutterHeat.enabled": true,
"fileDecorations.enabled": true,
"fileDecorations.maxScore": 4,
"codeLens.enabled": true,
"hover.enabled": true,
"hover.symbolDetail": true,
"server.autoStart": "ask",
"server.port": null,
"cliPath": "",
"risk.baseBranch": "",
"changeIntel.cochangeNudge": true,
"changeIntel.cochangeMinScore": 4,
"agentHandoff.enabled": true,
"agentTools.enabled": true,
};
const SEVERITIES = ["critical", "high", "medium", "low"];
const DIMENSIONS = ["defect", "maintainability", "performance", "advisory"];
/**
* Per-key validator for writes. The webview is untrusted input, so an out-of-
* shape value is rejected before it reaches config.update rather than trusting
* VS Code to coerce it. Returns the value to write, or throws.
*/
const SETTING_VALIDATORS: Record<SettingKey, (v: SettingValue) => SettingValue> = {
"diagnostics.enabled": expectBoolean,
"diagnostics.minSeverity": (v) => expectEnum(v, SEVERITIES),
"diagnostics.dimensions": (v) => expectStringSubset(v, DIMENSIONS),
"docDrift.diagnostics.enabled": expectBoolean,
"docDrift.diagnostics.minConfidence": (v) => expectNumberInRange(v, 0, 1),
"gutterHeat.enabled": expectBoolean,
"fileDecorations.enabled": expectBoolean,
"fileDecorations.maxScore": (v) => expectNumberInRange(v, 0, 10),
"codeLens.enabled": expectBoolean,
"hover.enabled": expectBoolean,
"hover.symbolDetail": expectBoolean,
"server.autoStart": (v) => expectEnum(v, ["ask", "always", "never"]),
"server.port": expectNullablePort,
"cliPath": expectString,
"risk.baseBranch": expectString,
"changeIntel.cochangeNudge": expectBoolean,
"changeIntel.cochangeMinScore": (v) => expectNumberInRange(v, 0, 100),
"agentHandoff.enabled": expectBoolean,
"agentTools.enabled": expectBoolean,
};
function expectBoolean(v: SettingValue): boolean {
if (typeof v !== "boolean") throw new Error("Expected a boolean.");
return v;
}
function expectString(v: SettingValue): string {
if (typeof v !== "string") throw new Error("Expected a string.");
return v;
}
function expectEnum(v: SettingValue, allowed: string[]): string {
if (typeof v !== "string" || !allowed.includes(v)) throw new Error("Value not allowed.");
return v;
}
function expectStringSubset(v: SettingValue, allowed: string[]): string[] {
if (!Array.isArray(v) || v.some((x) => !allowed.includes(x))) {
throw new Error("Value not allowed.");
}
// De-dupe and preserve the canonical order so the array stays stable.
return allowed.filter((x) => v.includes(x));
}
function expectNumberInRange(v: SettingValue, min: number, max: number): number {
if (typeof v !== "number" || !Number.isFinite(v) || v < min || v > max) {
throw new Error(`Expected a number in [${min}, ${max}].`);
}
return v;
}
function expectNullablePort(v: SettingValue): number | null {
if (v === null) return null;
if (typeof v !== "number" || !Number.isInteger(v) || v < 1 || v > 65535) {
throw new Error("Expected a port in [1, 65535] or null.");
}
return v;
}
/** Reads every allowlisted setting into a plain value map (defaults applied). */
function readSettings(): SettingsValues {
const cfg = vscode.workspace.getConfiguration(CONFIG_SECTION);
const out = {} as SettingsValues;
for (const key of SETTING_KEYS) {
out[key] = cfg.get<SettingValue>(key, SETTING_DEFAULTS[key]);
}
return out;
}
/**
* Host-side implementation of the webview data contract. Every method runs an
* api-client fetcher against the connected server, memoized in the shared
* cache under the indexed head commit plus a refresh epoch the panel manager
* bumps on every refresh broadcast (so a null or unchanged head commit can
* never serve stale data after an index update). Branch risk is the
* exception: it scores the working HEAD, which moves independently of the
* index, so it always fetches fresh.
*
* Cache keys are namespaced `wv:` to stay clear of the tree/hover/lens keys.
*/
export function createHostApi(ctx: RepowiseContext, epoch: () => number): HostApi {
function repoId(): string {
const id = ctx.repoId;
if (!id || ctx.getExtensionState() !== "ready") throw new NotReadyError();
return id;
}
// Concurrent callers of the same key share one request instead of racing
// (two panels opening together, or one view fanning out related slices).
const inFlight = new Map<string, Promise<unknown>>();
/** Serves from the tagged cache; concurrent misses share one request. */
function cached<T>(key: string, load: (id: string) => Promise<T>): Promise<T> {
const id = repoId();
const tag = `${ctx.repo?.head_commit ?? ""}#${epoch()}`;
const hit = ctx.cache.get<T>(id, `wv:${key}`, tag);
if (hit !== undefined) return Promise.resolve(hit);
const flightKey = `${id}|${key}|${tag}`;
const pending = inFlight.get(flightKey);
if (pending) return pending as Promise<T>;
const request = load(id)
.then((value) => {
ctx.cache.set(id, `wv:${key}`, tag, value);
return value;
})
.finally(() => {
inFlight.delete(flightKey);
});
inFlight.set(flightKey, request);
return request;
}
/**
* Aggregates the sidebar Home payload. Sub-fetches go through the same
* cached() keys the dashboards use (limits included), so opening a dashboard
* after the sidebar costs nothing extra. Refactoring uses the lighter
* medium-confidence query, not the panel's unfiltered multi-megabyte one.
* allSettled: one failing endpoint degrades its section to null.
*/
async function homeSummary(): Promise<HomeSummary> {
const id = repoId();
const [overview, trend, refactor, decisions, liveCommit, branch] =
await Promise.allSettled([
cached("health:overview:25", () => getHealthOverview(id, 25)),
cached("health:trend:20", () => getHealthTrend(id, 20)),
cached("home:refactor", () =>
getRefactoringTargets(id, { minConfidence: "medium" }),
),
cached("decisions:timeline", () =>
listDecisions(id, { include_proposed: true, limit: 500 }),
),
resolveLiveHead(ctx.workspace.repoRoot ?? ""),
getCurrentBranchName(ctx.workspace.repoRoot ?? ""),
]);
const summary = overview.status === "fulfilled" ? overview.value.summary : null;
const trendVal = trend.status === "fulfilled" ? trend.value : null;
const indexedCommit =
(overview.status === "fulfilled" ? overview.value.meta?.head_commit : null) ??
ctx.repo?.head_commit ??
null;
const live = liveCommit.status === "fulfilled" ? liveCommit.value : null;
return {
health: summary
? {
hotspot: summary.hotspot_health ?? null,
average: summary.average_health ?? null,
fileCount: summary.file_count,
openFindings: summary.open_findings,
band: summary.band ?? null,
hotspotDelta: trendVal?.summary?.hotspot_delta ?? null,
// A snapshot only carries a hotspot figure for the whole
// repository, so a reading without one is dropped rather than
// plotted at zero.
history: (trendVal?.history ?? [])
.slice()
.reverse()
.map((p) => p.hotspot_health)
.filter((v): v is number => v !== null),
}
: null,
counts: {
refactoringPlans:
refactor.status === "fulfilled" ? refactor.value.plans.length : null,
decisions: decisions.status === "fulfilled" ? decisions.value.length : null,
},
freshness: {
indexedCommit,
liveCommit: live,
stale: Boolean(indexedCommit && live && !commitsMatch(indexedCommit, live)),
branch: branch.status === "fulfilled" ? branch.value : null,
lastIndexedAt:
overview.status === "fulfilled"
? (overview.value.meta?.last_indexed_at ?? null)
: null,
},
};
}
return {
// Health dashboard
healthOverview: (limit) => cached(`health:overview:${limit ?? ""}`, (id) => getHealthOverview(id, limit)),
healthFiles: (query) =>
cached(`health:files:${JSON.stringify(query ?? {})}`, (id) => listHealthFiles(id, query)),
healthMap: (query) =>
cached(`health:map:${JSON.stringify(query ?? {})}`, (id) => getHealthMap(id, query)),
healthTrend: (limit) => cached(`health:trend:${limit ?? ""}`, (id) => getHealthTrend(id, limit)),
churnComplexity: (limit) =>
cached(`health:churn:${limit ?? ""}`, (id) => getChurnComplexity(id, limit != null ? { limit } : undefined)),
// Architecture map
architectureView: () => cached("arch:view", (id) => getArchitectureView(id)),
// Working-tree content, not index content: never cached under head_commit.
fileContent: (filePath) => getFileContent(repoId(), filePath),
// Knowledge graph
moduleGraph: () => cached("graph:modules", (id) => getModuleGraph(id)),
fullGraph: (limit) => cached(`graph:full:${limit ?? ""}`, (id) => getGraph(id, limit)),
architectureCommunityGraph: () =>
cached("graph:architecture", (id) => getArchitectureCommunityGraph(id)),
communities: () => cached("graph:communities", (id) => getCommunities(id)),
communitySlice: (communityId) =>
cached(`graph:slice:${communityId}`, (id) => getCommunitySlice(id, communityId)),
communityDetail: (communityId) =>
cached(`graph:community:${communityId}`, (id) => getCommunityDetail(id, communityId)),
graphPath: (from, to) =>
cached(`graph:path:${from}|${to}`, (id) => getGraphPath(id, from, to)),
// Autocomplete over an unbounded query space: live, never cached.
searchNodes: (query, limit) => searchNodes(repoId(), query, limit),
deadCodeGraph: () => cached("graph:dead", (id) => getDeadCodeGraph(id)),
hotFilesGraph: () => cached("graph:hot", (id) => getHotFilesGraph(id)),
executionFlows: () => cached("graph:flows", (id) => getExecutionFlows(id)),
// Refactoring
refactoringOpportunities: (filePath) =>
cached(`refactor:opps:${filePath ?? ""}`, (id) =>
getRefactoringOpportunities(id, {
...(filePath ? { filePath } : {}),
// The row renders counts, not steps; the detail call carries those.
stepPreview: 0,
limit: 100,
}),
),
refactoringOpportunity: (opportunityId) =>
cached(`refactor:opp:${opportunityId}`, (id) =>
getRefactoringOpportunity(id, opportunityId, { stepLimit: 50, evidenceLimit: 20 }),
),
refactoringOpportunityPrompt: (opportunityId, flavor) =>
opportunityPrompt(ctx, opportunityId, flavor, async () => {
const detail = await cached(`refactor:opp:${opportunityId}`, (id) =>
getRefactoringOpportunity(id, opportunityId, { stepLimit: 50, evidenceLimit: 20 }),
);
if (!detail.found) {
throw new Error(`No refactoring opportunity resolves for ${opportunityId}.`);
}
return detail;
}),
refactoringPlan: (suggestionId) =>
cached(`refactor:plan:${suggestionId}`, (id) => getRefactoringPlan(id, suggestionId)),
refactoringPrompt: async (suggestionId, flavor) => {
const plan = await cached(`refactor:plan:${suggestionId}`, (id) =>
getRefactoringPlan(id, suggestionId),
);
return planPrompt(ctx, plan, flavor);
},
// Decisions
decisionsList: () =>
cached("decisions:timeline", (id) => listDecisions(id, { include_proposed: true, limit: 500 })),
// Docs
pagesList: () => cached("docs:pages", (id) => listAllPages(id)),
pageById: (pageId) =>
cached(`docs:page:${pageId}`, (id) => getPageById(pageId, id)),
fileDetail: (relPath) => cached(`docs:file:${relPath}`, (id) => getFileDetail(id, relPath)),
// Branch risk
riskRange: async (): Promise<RiskRangeReport> => {
const id = repoId();
const configured = vscode.workspace
.getConfiguration(CONFIG_SECTION)
.get<string>("risk.baseBranch", "")
.trim();
const base = configured || ctx.repo?.default_branch || "main";
const range = { base, head: "HEAD" };
const [result, patchCoverage] = await Promise.all([
getRiskRange(id, range),
getPatchCoverage(id, range).catch(() => null),
]);
const branch = await getCurrentBranchName(ctx.workspace.repoRoot ?? "");
return { base, branch, result, patchCoverage };
},
// Change impact: reads the working tree, so it tracks the live change set
// rather than the indexed commit. analyzeChange owns caching by change-set
// signature, so this never re-fetches for an unchanged file set.
changeImpact: () => analyzeChange(ctx, "branch"),
// Sidebar home
homeSummary,
// Settings panel
getSettings: async () => readSettings(),
updateSetting: async (key, value) => {
if (!SETTING_KEYS.includes(key)) throw new Error(`Unknown setting: ${String(key)}`);
const validated = SETTING_VALIDATORS[key](value);
// Workspace scope when a folder is open (the common case, so the choice
// travels with the repo); user scope otherwise so the write still lands.
const target = vscode.workspace.workspaceFolders?.length
? vscode.ConfigurationTarget.Workspace
: vscode.ConfigurationTarget.Global;
await vscode.workspace.getConfiguration(CONFIG_SECTION).update(key, validated, target);
return readSettings();
},
};
}