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 { getHealthFileBreakdown } from "@repowise-dev/api-client/code-health";
import { getFileDetail } from "@repowise-dev/api-client/files";
import { getRiskRange } from "@repowise-dev/api-client/risk";
import { search } from "@repowise-dev/api-client/search";
import { getSymbolDetail, listSymbols } from "@repowise-dev/api-client/symbols";
import type { SymbolResponse } from "@repowise-dev/api-client/types";
import type { HealthFileBreakdownResponse } from "@repowise-dev/types/health";
import type { SymbolDetailResponse } from "@repowise-dev/types/symbols";
import { AGENT_TOOLS_CONTEXT_KEY, CONFIG_SECTION, LmToolNames } from "../constants";
import type { RepowiseContext } from "../core/context";
import { getFileFindings } from "../core/fileSignals";
import { getPlansForFile } from "../core/plans";
/**
* Native language model tools over the Repowise index, mirroring the
* `languageModelTools` contribution in package.json. All six tools are
* read-only lookups against the local server; chat invokes them, so every
* outcome (including "disabled" and "not connected") flows back as a tool
* result rather than a toast.
*/
/** Hard ceiling on any tool result; the model gets a truncation note, not an error. */
const MAX_RESULT_CHARS = 30000;
/** Caps mirroring the manifest contract: bounded payloads, never firehoses. */
const MAX_SEARCH_RESULTS = 20;
const DEFAULT_SEARCH_RESULTS = 5;
const MAX_FINDINGS = 50;
const MAX_PLANS = 10;
const MAX_SYMBOLS = 100;
const MAX_SYMBOL_CANDIDATES = 5;
/** Input shapes mirrored from the package.json inputSchema declarations. */
interface SearchInput {
query: string;
limit?: number;
}
interface FileInput {
filePath: string;
}
interface BranchRiskInput {
base?: string;
}
interface SymbolInput {
filePath: string;
symbolName?: string;
}
function textResult(text: string): vscode.LanguageModelToolResult {
const bounded =
text.length > MAX_RESULT_CHARS
? `${text.slice(0, MAX_RESULT_CHARS)}\n[truncated]`
: text;
return new vscode.LanguageModelToolResult([
new vscode.LanguageModelTextPart(bounded),
]);
}
function jsonResult(payload: unknown): vscode.LanguageModelToolResult {
return textResult(JSON.stringify(payload));
}
/**
* Normalizes a repo-relative path from the model: forward slashes, no leading
* "./". Returns null for absolute paths or ".." segments; the caller answers
* with a polite refusal instead of letting the path reach the server.
*/
function normalizeRelPath(input: string): string | null {
let rel = input.replace(/\\/g, "/").trim();
if (rel.startsWith("./")) rel = rel.slice(2);
if (!rel) return null;
if (rel.startsWith("/") || /^[A-Za-z]:/.test(rel)) return null;
if (rel.split("/").some((segment) => segment === "..")) return null;
return rel;
}
function agentToolsEnabled(): boolean {
return vscode.workspace
.getConfiguration(CONFIG_SECTION)
.get<boolean>("agentTools.enabled", true);
}
export function registerLmTools(ctx: RepowiseContext): vscode.Disposable {
// The manifest `when` clauses hide the tools from pickers via this context
// key; the per-invoke guard below is the backstop for calls already in
// flight or hosts that ignore the clause.
const syncContextKey = (): void => {
void vscode.commands.executeCommand(
"setContext",
AGENT_TOOLS_CONTEXT_KEY,
agentToolsEnabled(),
);
};
syncContextKey();
const configListener = vscode.workspace.onDidChangeConfiguration((event) => {
if (event.affectsConfiguration(`${CONFIG_SECTION}.agentTools.enabled`)) {
syncContextKey();
}
});
/**
* Reads through the shared cache under the current head commit, mirroring
* plans.ts. Fetch failures propagate to the per-tool catch, which turns
* them into a text result.
*/
async function cached<T>(key: string, fetcher: (repoId: string) => Promise<T>): Promise<T> {
const repoId = ctx.repoId;
if (!repoId) throw new Error("No repository resolved.");
const tag = ctx.repo?.head_commit ?? "";
const hit = ctx.cache.get<T>(repoId, key, tag);
if (hit !== undefined) return hit;
const value = await fetcher(repoId);
ctx.cache.set(repoId, key, tag, value);
return value;
}
/**
* Wraps a tool body with the shared guards: setting toggle, server
* readiness, and a catch that reports failures as tool text. Tools never
* throw for expected states and never surface UI notifications.
*/
function makeTool<T>(
invocationMessage: string,
run: (input: T, token: vscode.CancellationToken) => Promise<vscode.LanguageModelToolResult>,
): vscode.LanguageModelTool<T> {
return {
prepareInvocation: () => ({ invocationMessage }),
invoke: async (options, token) => {
if (!agentToolsEnabled()) {
return textResult(
"The Repowise tools are disabled in settings (repowise.agentTools.enabled).",
);
}
if (ctx.getExtensionState() !== "ready" || !ctx.repoId) {
return textResult(
"The local Repowise server is not connected. The user can start it from the Repowise status bar or the \"Repowise: Start Server\" command.",
);
}
try {
return await run(options.input, token);
} catch (err) {
const message = err instanceof Error ? err.message : String(err);
ctx.log.error(`Language model tool failed: ${String(err)}`);
return textResult(`Repowise lookup failed: ${message}`);
}
},
};
}
/** Path-taking tools share the normalization refusal. */
function badPathResult(raw: string): vscode.LanguageModelToolResult {
return textResult(
`The path "${raw}" is not a valid repository-relative path. Use forward slashes, relative to the repository root, without ".." segments.`,
);
}
const searchTool = makeTool<SearchInput>(
"Searching the Repowise index",
async (input) => {
const repoId = ctx.repoId ?? "";
const raw = typeof input.limit === "number" ? Math.floor(input.limit) : DEFAULT_SEARCH_RESULTS;
const limit = Math.min(Math.max(raw, 1), MAX_SEARCH_RESULTS);
// Queries form an unbounded space, so results are never cached.
const results = await search(input.query, { limit, repo_id: repoId });
const payload = results.map((r) => ({
title: r.title,
page_type: r.page_type,
target_path: r.target_path,
score: r.score,
snippet: r.snippet,
}));
return jsonResult(payload);
},
);
const fileHealthTool = makeTool<FileInput>(
"Reading file health from Repowise",
async (input) => {
const rel = normalizeRelPath(input.filePath);
if (!rel) return badPathResult(input.filePath);
// Same cache key the hover uses, so a hovered file costs the tool nothing.
const breakdown = await cached<HealthFileBreakdownResponse>(
`breakdown:${rel}`,
(repoId) => getHealthFileBreakdown(repoId, rel),
);
const metric = breakdown.metric;
if (!metric) {
return textResult(`Repowise has no health data for ${rel}.`);
}
const findings = await getFileFindings(ctx, rel);
return jsonResult({
scores: {
defect: metric.defect_score ?? metric.score,
maintainability: metric.maintainability_score ?? null,
performance: metric.performance_score ?? null,
},
findings: findings.slice(0, MAX_FINDINGS).map((f) => ({
severity: f.severity,
dimension: f.dimension ?? "defect",
biomarker: f.biomarker_type,
line_start: f.line_start,
line_end: f.line_end,
message: f.reason,
})),
});
},
);
const plansTool = makeTool<FileInput>(
"Fetching Repowise refactoring plans",
async (input) => {
const rel = normalizeRelPath(input.filePath);
if (!rel) return badPathResult(input.filePath);
const plans = await getPlansForFile(ctx, rel);
if (plans.length === 0) {
return textResult(`Repowise has no refactoring plans for ${rel}.`);
}
const payload = plans.slice(0, MAX_PLANS).map((p) => ({
id: p.id,
refactoring_type: p.refactoring_type,
target_symbol: p.target_symbol,
line_start: p.line_start,
line_end: p.line_end,
impact_delta: p.impact_delta,
effort_bucket: p.effort_bucket,
confidence: p.confidence,
plan: p.plan,
evidence: p.evidence,
blast_radius: p.blast_radius,
}));
return jsonResult(payload);
},
);
const branchRiskTool = makeTool<BranchRiskInput>(
"Scoring branch risk with Repowise",
async (input) => {
const repoId = ctx.repoId ?? "";
const configured = vscode.workspace
.getConfiguration(CONFIG_SECTION)
.get<string>("risk.baseBranch", "")
.trim();
const base =
input.base?.trim() || configured || ctx.repo?.default_branch || "main";
// Scores the working HEAD, which moves independently of the index, so
// this always fetches fresh.
const result = await getRiskRange(repoId, { base, head: "HEAD" });
return jsonResult({
base,
// First, because the score below measures diff size rather than danger,
// and a model handed only the score will read it as a verdict.
fix_history: result.fix_history,
risk_authority: result.risk_authority,
score: result.score,
score_measures: result.score_measures,
score_unit: result.score_unit,
risk_percentile: result.risk_percentile,
review_priority: result.review_priority,
classification: result.classification,
fallback_band: result.fallback_band,
drivers: result.drivers,
features: result.features,
});
},
);
const symbolInfoTool = makeTool<SymbolInput>(
"Looking up symbol info in Repowise",
async (input) => {
const rel = normalizeRelPath(input.filePath);
if (!rel) return badPathResult(input.filePath);
// Same cache key the hover uses, so both features share one fetch.
const symbols = await cached<SymbolResponse[]>(`symbols:${rel}`, (repoId) =>
listSymbols({ repo_id: repoId, file_path: rel, limit: 1000 }),
);
if (symbols.length === 0) {
return textResult(`Repowise has no indexed symbols for ${rel}.`);
}
const name = input.symbolName?.trim();
if (!name) {
const payload = symbols.slice(0, MAX_SYMBOLS).map((s) => ({
name: s.name,
kind: s.kind,
line_start: s.start_line,
line_end: s.end_line,
}));
return jsonResult(payload);
}
const match =
symbols.find((s) => s.name === name) ??
symbols.find((s) => s.name.toLowerCase() === name.toLowerCase());
if (!match) {
const lower = name.toLowerCase();
const near = symbols.filter((s) => s.name.toLowerCase().includes(lower));
const candidates = (near.length > 0 ? near : symbols)
.slice(0, MAX_SYMBOL_CANDIDATES)
.map((s) => s.name);
return textResult(
`No symbol named "${name}" in ${rel}. Close candidates: ${candidates.join(", ")}.`,
);
}
// Shares the hover's cache key and its convention: a failed fetch caches
// as null so a dead symbol id is asked once per index version.
const detail = await cached<SymbolDetailResponse | null>(
`symbolDetail:${match.symbol_id}`,
async (repoId) => {
try {
return await getSymbolDetail(repoId, match.symbol_id);
} catch (err) {
ctx.log.debug(`symbol detail ${match.symbol_id}: ${String(err)}`);
return null;
}
},
);
if (!detail) {
return jsonResult({
name: match.name,
kind: match.kind,
lines: { start: match.start_line, end: match.end_line },
note: "Detail lookup unavailable for this symbol.",
});
}
return jsonResult({
name: match.name,
kind: detail.symbol.kind,
lines: { start: match.start_line, end: match.end_line },
owner: detail.file_context?.primary_owner ?? null,
callers: detail.graph.callers.map((c) => ({
name: c.name,
kind: c.kind,
file: c.file,
line: c.start_line,
})),
callees: detail.graph.callees.map((c) => ({
name: c.name,
kind: c.kind,
file: c.file,
line: c.start_line,
})),
decisions: detail.governing_decisions.map((d) => d.title),
});
},
);
const fileDocsTool = makeTool<FileInput>(
"Reading Repowise docs",
async (input) => {
const rel = normalizeRelPath(input.filePath);
if (!rel) return badPathResult(input.filePath);
// The file-detail aggregate carries the wiki page content inline, the
// same fetch the docs panel resolves a file through.
const detail = await cached(`lm:docs:${rel}`, (repoId) =>
getFileDetail(repoId, rel),
);
const page = detail.wiki_page;
if (!page) {
return textResult(`Repowise has no documentation page for ${rel}.`);
}
const header = JSON.stringify({ title: page.title, path: rel });
return textResult(`${header}\n\n# ${page.title}\n\n${page.content}`);
},
);
const registrations: vscode.Disposable[] = [configListener];
// Fail soft per tool: a host that rejects one registration (an older
// proposal surface, a name collision) should not take down the rest.
function safeRegister<T>(toolName: string, tool: vscode.LanguageModelTool<T>): void {
try {
registrations.push(vscode.lm.registerTool(toolName, tool));
} catch (err) {
ctx.log.warn(`Could not register language model tool ${toolName}: ${String(err)}`);
}
}
safeRegister(LmToolNames.searchCodebase, searchTool);
safeRegister(LmToolNames.getFileHealth, fileHealthTool);
safeRegister(LmToolNames.getRefactoringPlans, plansTool);
safeRegister(LmToolNames.getBranchRisk, branchRiskTool);
safeRegister(LmToolNames.getSymbolInfo, symbolInfoTool);
safeRegister(LmToolNames.getFileDocs, fileDocsTool);
return vscode.Disposable.from(...registrations);
}