feat(cli): add experimental interactive Ink TUI

.changeset/experimental-tui.md

@@ -0,0 +1,5 @@
+---
+"react-doctor": minor
+---
+
+Add an experimental interactive TUI (`react-doctor experimental-tui`) built on Ink. It streams diagnostics live during the scan, then renders a scrollable, score-sorted report (no top-3 truncation) with the doctor-face score header, score projection ("you could improve +X%"), per-category breakdown, and an inline syntax-highlighted code frame for the selected issue. It also supports monorepo project selection (an interactive multiselect) and a multi-project summary view with drill-in per project. Ink/React load lazily so the default static, JSON, and score-only paths are unaffected.

package.json

@@ -32,6 +32,9 @@
     "smoke:tty-prompt": "python3 scripts/smoke-tty-prompt.py",
     "build:schema": "node --experimental-strip-types --no-warnings scripts/generate-config-schema.ts"
   },
+  "dependencies": {
+    "ink-spinner": "^5.0.0"
+  },
   "devDependencies": {
     "@changesets/changelog-github": "^0.7.0",
     "@changesets/cli": "^2.31.0",

packages/core/src/constants.ts

@@ -430,6 +430,27 @@ export const DIAGNOSTIC_CATEGORY_BUCKETS = [
   "Maintainability",
 ] as const;
 
+// One concrete line per category naming what the user pays if these issues
+// ship — the "why going through these is worth it" the diagnostic list can't
+// convey from a bare error/warning glyph. Category-level (not per-rule) on
+// purpose: KISS, no new rule/diagnostic field, no schema change. `satisfies`
+// keeps it exhaustive over the buckets above.
+export const CATEGORY_IMPACT = {
+  Security: "An attacker can read user data, act as your users, or run code you never shipped.",
+  Bugs: "Real users hit crashes, wrong output, or state that silently corrupts.",
+  Performance: "Users feel extra latency and wasted renders on every interaction.",
+  Accessibility: "Users on screen readers, keyboards, or assistive tech get locked out.",
+  Maintainability: "Every future change gets slower and riskier to make.",
+} satisfies Record<(typeof DIAGNOSTIC_CATEGORY_BUCKETS)[number], string>;
+
+// Safe lookup for an arbitrary category string (legacy / adopted rules may
+// report categories outside the closed bucket set, so this returns undefined
+// rather than indexing blindly).
+export const getCategoryImpact = (category: string): string | undefined =>
+  Object.hasOwn(CATEGORY_IMPACT, category)
+    ? CATEGORY_IMPACT[category as keyof typeof CATEGORY_IMPACT]
+    : undefined;
+
 // Rules whose heuristic only makes sense in application code. A published
 // library deliberately exposes flexible primitives (components built in
 // render to capture closures, many `render*` slots for composition), so these

packages/react-doctor/package.json

@@ -63,11 +63,15 @@
     "confbox": "^0.2.4",
     "deslop-js": "workspace:*",
     "eslint-plugin-react-hooks": "^7.1.1",
+    "figures": "^6.1.0",
+    "ink": "^7.1.0",
+    "ink-spinner": "^5.0.0",
     "jiti": "^2.7.0",
     "magicast": "^0.5.3",
     "oxlint": ">=1.66.0 <1.67.0",
     "oxlint-plugin-react-doctor": "workspace:*",
     "prompts": "^2.4.2",
+    "react": "19.2.5",
     "typescript": ">=5.0.4 <6",
     "vscode-languageserver": "^9.0.1",
     "vscode-languageserver-textdocument": "^1.0.12",
@@ -80,8 +84,10 @@
     "@react-doctor/language-server": "workspace:*",
     "@types/babel__code-frame": "^7.27.0",
     "@types/prompts": "^2.4.9",
+    "@types/react": "^19.2.14",
     "@xterm/headless": "^6.0.0",
     "commander": "^14.0.3",
+    "ink-testing-library": "^4.0.0",
     "ora": "^9.4.0"
   },
   "engines": {

packages/react-doctor/src/cli/index.ts

@@ -401,6 +401,31 @@ program
   .allowUnknownOption()
   .action(() => {});
 
+// Gated behind `experimental-` while the interactive Ink report stabilizes
+// (keymap, layout, and the scan-store contract may change). Ink + React load
+// lazily here so the default static path never pays their startup cost.
+program
+  .command("experimental-tui [directory]")
+  .description("[experimental] interactive, scrollable scan report")
+  .option("--no-dead-code", "skip dead-code analysis")
+  .option("--no-score", "skip the score API, the share URL, and crash reporting")
+  .option("-p, --project <names>", "scan specific workspace projects (comma-separated, or *)")
+  .option("-y, --yes", "skip the project prompt and scan every discovered project")
+  .action(
+    async (
+      directory = ".",
+      options: { deadCode?: boolean; score?: boolean; project?: string; yes?: boolean },
+    ) => {
+      const { runScanApp } = await import("./ink/run-scan-app.js");
+      await runScanApp({
+        directory,
+        options: { deadCode: options.deadCode ?? true, noScore: options.score === false },
+        projectFlag: options.project,
+        skipPrompts: options.yes ?? false,
+      });
+    },
+  );
+
 // HACK: when stdout is piped into a process that closes early (e.g.
 // `react-doctor . | head`), Node throws an uncaught EPIPE on the next
 // write. Exit cleanly instead of dumping a stack trace.

packages/react-doctor/src/cli/ink/components/diagnostic-actions.tsx

@@ -0,0 +1,82 @@
+import { getSkillAgentConfig } from "agent-install";
+import { Box, Text } from "ink";
+import type { CliAgentId } from "../../utils/launch-agent.js";
+
+export interface DiagnosticActionsProps {
+  /** Launchable agents, in order; rendered between Copy and the read toggle. */
+  readonly launchableAgents: ReadonlyArray<CliAgentId>;
+  /** Whether the selected issue is currently marked read. */
+  readonly isRead: boolean;
+  /** True right after the selected issue's prompt was copied. */
+  readonly justCopied: boolean;
+  /** Whether this pane holds focus (then `↑/↓` + Enter drive it). */
+  readonly isFocused: boolean;
+  /** Index of the focused action (Copy = 0, agents next, read toggle last). */
+  readonly focusedIndex: number;
+}
+
+/**
+ * The order actions are laid out in — the single source of truth shared with
+ * `DiagnosticList`'s key handler so a focused index always maps to the same
+ * action: Copy, then each launchable agent, then the read toggle.
+ */
+export const actionCount = (agentCount: number): number => agentCount + 2;
+
+const ActionRow = ({
+  label,
+  isFocused,
+  trailing,
+}: {
+  readonly label: string;
+  readonly isFocused: boolean;
+  readonly trailing?: string;
+}) => (
+  <Text wrap="truncate-end">
+    <Text color={isFocused ? "cyan" : undefined}>{isFocused ? "› " : "  "}</Text>
+    <Text color={isFocused ? "cyan" : undefined} dimColor={!isFocused}>
+      {label}
+    </Text>
+    {trailing ? <Text color="green">{`  ${trailing}`}</Text> : null}
+  </Text>
+);
+
+/**
+ * The right-panel triage actions for the selected issue: copy a focused fix
+ * prompt, hand it to a detected CLI agent (Claude Code / Codex / Cursor), or
+ * flip the issue's read state. The pane is navigated by focus — `Tab` moves in,
+ * `↑/↓` highlights a row, Enter runs it — so there are no per-row hotkeys to
+ * memorize.
+ */
+export const DiagnosticActions = ({
+  launchableAgents,
+  isRead,
+  justCopied,
+  isFocused,
+  focusedIndex,
+}: DiagnosticActionsProps) => {
+  const toggleIndex = actionCount(launchableAgents.length) - 1;
+  return (
+    <Box flexDirection="column" marginTop={1}>
+      <Text wrap="truncate-end">
+        <Text bold>Actions</Text>
+        <Text dimColor>{isFocused ? "  ↑/↓ · enter · esc back" : "  tab to focus"}</Text>
+      </Text>
+      <ActionRow
+        label="Copy fix prompt"
+        isFocused={isFocused && focusedIndex === 0}
+        trailing={justCopied ? "✓ copied" : undefined}
+      />
+      {launchableAgents.map((agentId, index) => (
+        <ActionRow
+          key={agentId}
+          label={`Run in ${getSkillAgentConfig(agentId).displayName}`}
+          isFocused={isFocused && focusedIndex === index + 1}
+        />
+      ))}
+      <ActionRow
+        label={isRead ? "Mark unread" : "Mark read"}
+        isFocused={isFocused && focusedIndex === toggleIndex}
+      />
+    </Box>
+  );
+};

packages/react-doctor/src/cli/ink/components/diagnostic-detail.tsx

@@ -0,0 +1,94 @@
+import { getCategoryImpact } from "@react-doctor/core";
+import { Box, Text } from "ink";
+import { useMemo } from "react";
+import { buildCodeFrame } from "../../utils/build-code-frame.js";
+import type { DiagnosticRow } from "../lib/diagnostic-rows.js";
+import { severityVariant } from "../lib/severity-variants.js";
+
+export interface DiagnosticDetailProps {
+  readonly row: DiagnosticRow | null;
+  readonly rootDirectory: string;
+}
+
+// Body lines hang-indent via container padding (not a leading string) so a
+// wrapped continuation line lines up under the first line instead of falling
+// back to column 0.
+const DETAIL_INDENT_COLUMNS = 4;
+
+/**
+ * Detail for the selected rule group, styled after the CLI's rule block
+ * (`render-diagnostics.ts`): icon + headline, impact prose, the dim `→` fix,
+ * the gray location, and the syntax-highlighted source frame at the site.
+ */
+export const DiagnosticDetail = ({ row, rootDirectory }: DiagnosticDetailProps) => {
+  const codeFrame = useMemo(() => {
+    if (!row) return null;
+    const { representative } = row;
+    return buildCodeFrame({
+      filePath: representative.filePath,
+      line: representative.line,
+      column: representative.column,
+      rootDirectory,
+    });
+  }, [row, rootDirectory]);
+
+  if (!row) return null;
+  const variant = severityVariant(row.severity);
+  const { representative } = row;
+  const impact = getCategoryImpact(row.category);
+
+  return (
+    <Box flexDirection="column">
+      <Text wrap="truncate-end">
+        <Text color={variant.color}>
+          {"  "}
+          {variant.icon}{" "}
+        </Text>
+        <Text color={variant.color} bold>
+          {row.title}
+        </Text>
+        {row.siteCount > 1 ? <Text dimColor> ×{row.siteCount}</Text> : null}
+      </Text>
+      <Box flexDirection="column" paddingLeft={DETAIL_INDENT_COLUMNS}>
+        <Text dimColor wrap="truncate-end">
+          {row.category} · {variant.label}
+        </Text>
+        {impact ? (
+          <Text dimColor wrap="wrap">
+            {impact}
+          </Text>
+        ) : null}
+        <Text wrap="wrap">{representative.message}</Text>
+        <Text dimColor wrap="truncate-end">
+          {row.location}
+        </Text>
+      </Box>
+      {codeFrame ? (
+        <Box
+          marginTop={1}
+          marginLeft={DETAIL_INDENT_COLUMNS}
+          borderStyle="round"
+          borderColor="gray"
+          paddingX={1}
+          alignSelf="flex-start"
+        >
+          <Text>{codeFrame}</Text>
+        </Box>
+      ) : null}
+      {representative.help ? (
+        <Box marginTop={1} paddingLeft={DETAIL_INDENT_COLUMNS}>
+          <Text dimColor wrap="wrap">
+            → {representative.help}
+          </Text>
+        </Box>
+      ) : null}
+      {row.learnMore ? (
+        <Box marginTop={1} paddingLeft={DETAIL_INDENT_COLUMNS}>
+          <Text color="cyan" wrap="truncate-end">
+            {row.learnMore}
+          </Text>
+        </Box>
+      ) : null}
+    </Box>
+  );
+};

packages/react-doctor/src/cli/ink/components/diagnostic-item.tsx

@@ -0,0 +1,32 @@
+import { Text } from "ink";
+import type { DiagnosticRow } from "../lib/diagnostic-rows.js";
+import { severityVariant } from "../lib/severity-variants.js";
+
+export interface DiagnosticItemProps {
+  readonly row: DiagnosticRow;
+  readonly isSelected: boolean;
+  /** Triaged ("read") rows render muted with a blank marker instead of the dot. */
+  readonly isRead: boolean;
+}
+
+/**
+ * One collapsed rule-group line, rendered indented under its category header:
+ * `› • ✖ Title ×N` — a `›` pointer on the selected row, an unread `•` dot
+ * (blanked once triaged), then the icon + title colored by severity and a dim
+ * `×N` site badge. Read rows render muted so the unread queue stays scannable.
+ */
+export const DiagnosticItem = ({ row, isSelected, isRead }: DiagnosticItemProps) => {
+  const variant = severityVariant(row.severity);
+
+  return (
+    <Text wrap="truncate-end" dimColor={isRead}>
+      <Text color={isSelected ? variant.color : undefined}>{isSelected ? "›" : " "}</Text>
+      <Text color={isRead ? undefined : variant.color}>{isRead ? "  " : " •"}</Text>
+      <Text color={isRead ? undefined : variant.color}>{` ${variant.icon} `}</Text>
+      <Text color={isRead ? undefined : variant.color} bold={isSelected}>
+        {row.title}
+      </Text>
+      {row.siteCount > 1 ? <Text dimColor> ×{row.siteCount}</Text> : null}
+    </Text>
+  );
+};