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.

docs(ui): describe code health as technical debt (#4180)

Raghav Chamadiya3fb20e91d6a6
diff --git a/README.md b/README.md
index 2f9fe0763..13d404796 100644
--- a/README.md
+++ b/README.md
@@ -394,6 +394,9 @@ git alone cannot attest.
## ★ Know exactly what to fix
+Code health measures technical debt: the code shape and change history that make a
+file likely to need the next fix.
+
A score that says *"this file is risky"* is where most tools stop. Repowise scores
every file, finds where the risk concentrates, and names the specific fix.
diff --git a/docs/architecture/code-health.md b/docs/architecture/code-health.md
index 32133f961..56e94494d 100644
--- a/docs/architecture/code-health.md
+++ b/docs/architecture/code-health.md
@@ -17,7 +17,8 @@ markers, languages, coverage formats, or alerts.
Code Health is the **fifth intelligence layer** in Repowise, alongside Graph,
Git, Docs, and Decisions. It reads from Graph and Git but never modifies
-them. Its only writes are to its own four tables.
+them. Its only writes are to its own four tables. It measures technical debt:
+the code shape and change history that make a file likely to need the next fix.
```
┌─────────────┐ parsed_files ┌──────────────────┐
diff --git a/packages/ui/__tests__/health/fix-first.test.tsx b/packages/ui/__tests__/health/fix-first.test.tsx
index 5cce026b7..8fd84b5ee 100644
--- a/packages/ui/__tests__/health/fix-first.test.tsx
+++ b/packages/ui/__tests__/health/fix-first.test.tsx
@@ -45,7 +45,7 @@ describe("Fix first header", () => {
// Under the score: the headline keeps the first screen.
expect(details.open).toBe(false);
const summary = container.querySelector("summary")!;
- expect(summary.textContent).toContain("Fix first");
+ expect(summary.textContent).toContain("Highest-interest technical debt");
expect(summary.textContent).toContain("3 items");
});
diff --git a/packages/ui/src/health/fix-first/fix-first-list.tsx b/packages/ui/src/health/fix-first/fix-first-list.tsx
index 05952bc99..8d4bf97e6 100644
--- a/packages/ui/src/health/fix-first/fix-first-list.tsx
+++ b/packages/ui/src/health/fix-first/fix-first-list.tsx
@@ -41,6 +41,8 @@ export interface FixFirstListProps {
/** Closed by default, under the score: the headline keeps the first screen
* and the toggle's count says how much is behind it. */
defaultOpen?: boolean | undefined;
+ /** Section heading. Callers with i18n pass their translated string. */
+ title?: string | undefined;
}
export function FixFirstList({
@@ -57,6 +59,7 @@ export function FixFirstList({
LinkComponent,
flush = false,
defaultOpen = false,
+ title = "Highest-interest technical debt",
}: FixFirstListProps) {
// Every row starts as its one or two scan lines; the detail opens per row.
const [expanded, setExpanded] = useState<ReadonlySet<string>>(() => new Set());
@@ -111,7 +114,7 @@ export function FixFirstList({
return (
<OverviewSection
- title="Fix first"
+ title={title}
flush={flush}
collapsible
defaultOpen={defaultOpen}
diff --git a/packages/web/messages/en.json b/packages/web/messages/en.json
index 863bd6414..52574b42d 100644
--- a/packages/web/messages/en.json
+++ b/packages/web/messages/en.json
@@ -514,6 +514,8 @@
},
"codeHealth": {
"title": "Code health",
+ "description": "Technical debt across your codebase, ranked by what it costs you to keep changing it.",
+ "fixFirstTitle": "Highest-interest technical debt",
"scopeFiles": "Files",
"scopeCounts": "Counts",
"scopeAll": "All code",
@@ -1331,7 +1333,7 @@
"codeHealth": {
"hotspots": {
"title": "Hotspots",
- "description": "Ranked by hotspot score: every commit counts, recent ones most (180-day half-life). Same scope as the map above. The danger is not churn on its own. It is a file that changes constantly and only one person understands.",
+ "description": "Files that change often. Debt here costs you on every change. Ranked by hotspot score: every commit counts, recent ones most (180-day half-life). Same scope as the map above. The danger is not churn on its own. It is a file that changes constantly and only one person understands.",
"commitHistory": "Commit history",
"loadFailed": "Couldn't load hotspots. Run a sync to mine git history for this repo.",
"promptTitle": "AI stabilization prompt",
diff --git a/packages/web/messages/zh-CN.json b/packages/web/messages/zh-CN.json
index 09355e98a..d89414da4 100644
--- a/packages/web/messages/zh-CN.json
+++ b/packages/web/messages/zh-CN.json
@@ -514,6 +514,8 @@
},
"codeHealth": {
"title": "代码健康",
+ "description": "整个代码库中的技术债务,按持续修改它所付出的代价排序。",
+ "fixFirstTitle": "利息最高的技术债务",
"scopeFiles": "文件",
"scopeCounts": "计数",
"scopeAll": "全部代码",
@@ -1331,7 +1333,7 @@
"codeHealth": {
"hotspots": {
"title": "热点",
- "description": "按热点分数排序:每次提交都计入,越近的权重越高(半衰期 180 天)。范围与上方地图一致。危险的不只是频繁变更,而是那种频繁改动却只有一个人看得懂的文件。",
+ "description": "经常变更的文件。这里的债务在每次修改时都会让你付出代价。按热点分数排序:每次提交都计入,越近的权重越高(半衰期 180 天)。范围与上方地图一致。危险的不只是频繁变更,而是那种频繁改动却只有一个人看得懂的文件。",
"commitHistory": "提交历史",
"loadFailed": "无法加载热点。请运行一次同步,为该代码仓库挖掘 git 历史。",
"promptTitle": "AI 稳定化提示词",
diff --git a/packages/web/src/app/repos/[id]/code-health/code-health-view.tsx b/packages/web/src/app/repos/[id]/code-health/code-health-view.tsx
index c74cda289..7d28af38a 100644
--- a/packages/web/src/app/repos/[id]/code-health/code-health-view.tsx
+++ b/packages/web/src/app/repos/[id]/code-health/code-health-view.tsx
@@ -338,9 +338,8 @@ export function CodeHealthView() {
<PageShell
title={t("title")}
icon={<HeartPulse />}
- // No description: the lede below opens with what the score is built from,
- // and a header that says it first only says it twice.
- //
+ // What the page is for; the lede below says what the score is built from.
+ description={t("description")}
// "wide" rather than the style's usual 1280 — a deliberate divergence. At
// 1280 the map keeps ~900px beside its 320px inspector; the extra width
// goes entirely to the field, which is this page's whole subject.
diff --git a/packages/web/src/components/code-health/fix-first-section.tsx b/packages/web/src/components/code-health/fix-first-section.tsx
index 9f6ff9df3..ad32c507f 100644
--- a/packages/web/src/components/code-health/fix-first-section.tsx
+++ b/packages/web/src/components/code-health/fix-first-section.tsx
@@ -9,6 +9,7 @@
import { useCallback, useState } from "react";
import Link from "next/link";
import useSWR, { useSWRConfig } from "swr";
+import { useTranslations } from "next-intl";
import { FixFirstList } from "@repowise-dev/ui/health";
import { fileEntityPath } from "@repowise-dev/ui/shared/entity";
import type { FixFirstQueue, FixItem, FixScope } from "@repowise-dev/types/fix-first";
@@ -32,6 +33,7 @@ export function fixPlanHref(repoId: string, item: FixItem): string | null {
}
export function FixFirstSection({ repoId }: { repoId: string }) {
+ const t = useTranslations("views.codeHealth");
const [scope, setScope] = useState<FixScope>("production");
const key = `code-health-fix-first:${repoId}:${scope}`;
const { data, error, isLoading, mutate } = useSWR<FixFirstQueue>(
@@ -77,6 +79,7 @@ export function FixFirstSection({ repoId }: { repoId: string }) {
onTriage={onTriage}
loadPrompt={loadPrompt}
LinkComponent={Link}
+ title={t("fixFirstTitle")}
/>
);
}