第 13 章：Ink + React — 组件化终端界面

// 命令式写法：手动管理每一行输出
process.stdout.write('\x1b[2J')  // 清屏
process.stdout.write('\x1b[1;1H') // 移动光标到左上角
process.stdout.write('\x1b[1m扫描结果\x1b[0m\n')
process.stdout.write(`文件数: ${count}\n`)
if (loading) {
  process.stdout.write('⠋ 分析中...\n')
}
 
// 声明式写法：描述界面应该是什么样
function ScanResult({ count, loading }) {
  return (
    <Box flexDirection="column">
      <Text bold>扫描结果</Text>
      <Text>文件数: {count}</Text>
      {loading && <Text><Spinner /> 分析中...</Text>}
    </Box>
  )
}

React 组件 → React Reconciler → Yoga 布局引擎 → ANSI 输出

import { Box, Text } from 'ink'
 
// 垂直排列（默认）
<Box flexDirection="column">
  <Text>第一行</Text>
  <Text>第二行</Text>
</Box>
 
// 水平排列
<Box flexDirection="row">
  <Text>左边</Text>
  <Text>右边</Text>
</Box>
 
// 带边框和内边距
<Box borderStyle="round" borderColor="cyan" padding={1}>
  <Text>带边框的内容</Text>
</Box>
 
// 指定宽高
<Box width={40} height={10}>
  <Text>固定大小的容器</Text>
</Box>
 
// 百分比宽度
<Box width="50%">
  <Text>占父容器一半宽度</Text>
</Box>

import { Text } from 'ink'
 
// 颜色
<Text color="green">成功</Text>
<Text color="red">失败</Text>
<Text color="#ff8800">自定义颜色</Text>
<Text color="rgb(255, 136, 0)">RGB 颜色</Text>
 
// 样式
<Text bold>粗体</Text>
<Text italic>斜体</Text>
<Text underline>下划线</Text>
<Text strikethrough>删除线</Text>
<Text dimColor>暗色（次要信息）</Text>
 
// 背景色
<Text backgroundColor="red" color="white"> ERROR </Text>
 
// 组合
<Text bold color="cyan">repox v0.1.0</Text>
 
// 换行控制
<Text wrap="truncate">很长的文本会被截断而不是换行...</Text>
<Text wrap="truncate-end">截断末尾</Text>
<Text wrap="truncate-middle">截断中间</Text>

import { Box, Text, Newline, Spacer } from 'ink'
 
// Spacer 把内容推到两端
<Box>
  <Text>左对齐内容</Text>
  <Spacer />
  <Text>右对齐内容</Text>
</Box>
 
// 输出效果（假设终端宽 40 列）：
// 左对齐内容                  右对齐内容
 
// Newline 插入空行
<Box flexDirection="column">
  <Text>第一段</Text>
  <Newline />
  <Text>第二段（隔了一行）</Text>
</Box>

// 上下分区：标题 + 内容 + 状态栏
<Box flexDirection="column" height={process.stdout.rows}>
  {/* 标题栏 */}
  <Box borderStyle="single" paddingX={1}>
    <Text bold>repox review</Text>
  </Box>
 
  {/* 内容区，flexGrow 占满剩余空间 */}
  <Box flexGrow={1}>
    <Text>内容区域</Text>
  </Box>
 
  {/* 底部状态栏 */}
  <Box borderStyle="single" paddingX={1}>
    <Text dimColor>按 q 退出 | ↑↓ 导航 | Enter 选择</Text>
  </Box>
</Box>

// 左右分区：侧边栏 + 主内容
<Box flexDirection="row">
  {/* 固定宽度侧边栏 */}
  <Box width={30} borderStyle="single" flexDirection="column">
    <Text>侧边栏</Text>
  </Box>
 
  {/* 自适应宽度主内容 */}
  <Box flexGrow={1} borderStyle="single" flexDirection="column">
    <Text>主内容区</Text>
  </Box>
</Box>

// 居中对齐
<Box justifyContent="center" alignItems="center" height={5}>
  <Text>水平垂直居中</Text>
</Box>
 
// 两端对齐
<Box justifyContent="space-between" width={60}>
  <Text>文件名.ts</Text>
  <Text dimColor>42 行</Text>
</Box>
 
// 末尾对齐（右对齐）
<Box justifyContent="flex-end" width={40}>
  <Text color="green">✓ PASS</Text>
</Box>

<Box
  paddingX={2}      // 左右各 2 个字符
  paddingY={1}      // 上下各 1 行
  marginLeft={4}    // 左边空 4 个字符（缩进效果）
  borderStyle="round"
>
  <Text>有内边距和左边距的盒子</Text>
</Box>

single:           round:            double:           bold:
┌─────────┐       ╭─────────╮       ╔═════════╗       ┏━━━━━━━━━┓
│  内容   │       │  内容   │       ║  内容   ║       ┃  内容   ┃
└─────────┘       ╰─────────╯       ╚═════════╝       ┗━━━━━━━━━┛

import React, { useState } from 'react'
import { Box, Text } from 'ink'
import TextInput from 'ink-text-input'
 
function SearchBox() {
  const [query, setQuery] = useState('')
  const [submitted, setSubmitted] = useState(false)
 
  return (
    <Box>
      <Text bold>搜索: </Text>
      {submitted ? (
        <Text color="cyan">{query}</Text>
      ) : (
        <TextInput
          value={query}
          onChange={setQuery}
          onSubmit={() => setSubmitted(true)}
          placeholder="输入关键词..."
        />
      )}
    </Box>
  )
}

import React from 'react'
import { Box, Text } from 'ink'
import SelectInput from 'ink-select-input'
 
function FormatSelector() {
  const items = [
    { label: 'JSON', value: 'json' },
    { label: 'Table', value: 'table' },
    { label: 'Markdown', value: 'markdown' },
    { label: 'CSV', value: 'csv' },
  ]
 
  const handleSelect = (item) => {
    // item.value 是用户选择的值
    console.log(`选择了: ${item.value}`)
  }
 
  return (
    <Box flexDirection="column">
      <Text bold>选择输出格式:</Text>
      <SelectInput items={items} onSelect={handleSelect} />
    </Box>
  )
}

import React from 'react'
import { Box, Text } from 'ink'
import Spinner from 'ink-spinner'
 
function LoadingStatus({ task, done }) {
  return (
    <Box>
      {done ? (
        <Text color="green">✓ </Text>
      ) : (
        <Text color="cyan"><Spinner type="dots" /> </Text>
      )}
      <Text>{task}</Text>
    </Box>
  )
}
 
// 使用
<Box flexDirection="column">
  <LoadingStatus task="扫描文件结构" done={true} />
  <LoadingStatus task="分析代码复杂度" done={true} />
  <LoadingStatus task="生成 AI 审查报告" done={false} />
  <LoadingStatus task="格式化输出" done={false} />
</Box>

import React, { useState, useReducer } from 'react'
import { Box, Text } from 'ink'
 
// useState：简单状态
function Counter() {
  const [count, setCount] = useState(0)
  // ...
  return <Text>计数: {count}</Text>
}
 
// useReducer：复杂状态（推荐用于 TUI 应用）
interface ReviewState {
  selectedFile: number
  expandedDiffs: Set<string>
  filterPattern: string
  viewMode: 'split' | 'unified'
}
 
type ReviewAction =
  | { type: 'SELECT_FILE'; index: number }
  | { type: 'TOGGLE_DIFF'; file: string }
  | { type: 'SET_FILTER'; pattern: string }
  | { type: 'TOGGLE_VIEW_MODE' }
 
function reviewReducer(state: ReviewState, action: ReviewAction): ReviewState {
  switch (action.type) {
    case 'SELECT_FILE':
      return { ...state, selectedFile: action.index }
    case 'TOGGLE_DIFF':
      const next = new Set(state.expandedDiffs)
      next.has(action.file) ? next.delete(action.file) : next.add(action.file)
      return { ...state, expandedDiffs: next }
    case 'SET_FILTER':
      return { ...state, filterPattern: action.pattern, selectedFile: 0 }
    case 'TOGGLE_VIEW_MODE':
      return {
        ...state,
        viewMode: state.viewMode === 'split' ? 'unified' : 'split',
      }
    default:
      return state
  }
}

import { useInput, useApp } from 'ink'
 
function NavigableList({ items }) {
  const [selected, setSelected] = useState(0)
  const { exit } = useApp()
 
  useInput((input, key) => {
    // 方向键导航
    if (key.upArrow) {
      setSelected(prev => Math.max(0, prev - 1))
    }
    if (key.downArrow) {
      setSelected(prev => Math.min(items.length - 1, prev + 1))
    }
 
    // Page Up / Page Down（大跳转）
    if (key.pageUp) {
      setSelected(prev => Math.max(0, prev - 10))
    }
    if (key.pageDown) {
      setSelected(prev => Math.min(items.length - 1, prev + 10))
    }
 
    // Enter 确认
    if (key.return) {
      handleSelect(items[selected])
    }
 
    // q 退出
    if (input === 'q') {
      exit()
    }
 
    // Ctrl+C 也能退出（useInput 能捕获）
    if (input === 'c' && key.ctrl) {
      exit()
    }
 
    // / 进入搜索模式
    if (input === '/') {
      setSearchMode(true)
    }
  })
 
  // ...渲染逻辑
}

import React, { useState, useEffect } from 'react'
import { Box, Text } from 'ink'
import Spinner from 'ink-spinner'
 
function AIReview({ filePath }) {
  const [status, setStatus] = useState<'loading' | 'done' | 'error'>('loading')
  const [result, setResult] = useState('')
 
  useEffect(() => {
    let cancelled = false
 
    async function fetchReview() {
      try {
        const review = await callAI(filePath)
        if (!cancelled) {
          setResult(review)
          setStatus('done')
        }
      } catch (err) {
        if (!cancelled) {
          setResult(err.message)
          setStatus('error')
        }
      }
    }
 
    fetchReview()
    return () => { cancelled = true }
  }, [filePath])
 
  if (status === 'loading') {
    return (
      <Box>
        <Spinner type="dots" />
        <Text> 正在分析 {filePath}...</Text>
      </Box>
    )
  }
 
  return (
    <Box flexDirection="column">
      <Text color={status === 'error' ? 'red' : 'green'}>
        {status === 'error' ? '✗' : '✓'} {filePath}
      </Text>
      <Text>{result}</Text>
    </Box>
  )
}

// 概念性代码：展示状态栏组件的设计
import React from 'react'
import { Box, Text, Spacer } from 'ink'
 
interface StatusBarProps {
  filename?: string
  line?: number
  total?: number
  mode?: string
  branch?: string
}
 
function StatusBar({ filename, line, total, mode, branch }: StatusBarProps) {
  return (
    <Box
      borderStyle="single"
      borderTop={false}
      borderLeft={false}
      borderRight={false}
      paddingX={1}
    >
      {/* 左侧：模式和文件信息 */}
      <Text backgroundColor="blue" color="white" bold>
        {' '}{mode || 'NORMAL'}{' '}
      </Text>
      <Text> </Text>
      {filename && <Text>{filename}</Text>}
 
      <Spacer />
 
      {/* 右侧：分支和位置 */}
      {branch && (
        <Text dimColor>
          ⎇ {branch}
        </Text>
      )}
      <Text> </Text>
      {line != null && total != null && (
        <Text dimColor>
          {line}/{total}
        </Text>
      )}
    </Box>
  )
}

// 概念性代码：展示 diff 渲染组件的设计
import React from 'react'
import { Box, Text } from 'ink'
 
interface DiffLine {
  type: 'add' | 'remove' | 'context' | 'header'
  content: string
  lineNumber?: number
}
 
function DiffView({ lines, scrollOffset = 0, visibleHeight = 20 }: {
  lines: DiffLine[]
  scrollOffset?: number
  visibleHeight?: number
}) {
  const visible = lines.slice(scrollOffset, scrollOffset + visibleHeight)
 
  return (
    <Box flexDirection="column" flexGrow={1}>
      {visible.map((line, i) => {
        const lineNum = line.lineNumber
          ? String(line.lineNumber).padStart(4)
          : '    '
 
        const colorMap = {
          add: 'green',
          remove: 'red',
          context: 'white',
          header: 'cyan',
        } as const
 
        const prefixMap = {
          add: '+',
          remove: '-',
          context: ' ',
          header: '@',
        }
 
        return (
          <Box key={i}>
            <Text dimColor>{lineNum} </Text>
            <Text color={colorMap[line.type]}>
              {prefixMap[line.type]} {line.content}
            </Text>
          </Box>
        )
      })}
 
      {/* 滚动指示器 */}
      {lines.length > visibleHeight && (
        <Box justifyContent="flex-end">
          <Text dimColor>
            [{scrollOffset + 1}-{Math.min(scrollOffset + visibleHeight, lines.length)}/{lines.length}]
          </Text>
        </Box>
      )}
    </Box>
  )
}

// 概念性代码：展示流式文本组件的设计
import React, { useState, useEffect } from 'react'
import { Text } from 'ink'
 
function StreamingText({ stream }: { stream: AsyncIterable<string> }) {
  const [text, setText] = useState('')
 
  useEffect(() => {
    let cancelled = false
 
    async function consume() {
      for await (const chunk of stream) {
        if (cancelled) break
        setText(prev => prev + chunk)
      }
    }
 
    consume()
    return () => { cancelled = true }
  }, [stream])
 
  return <Text>{text}</Text>
}

// 概念性代码：展示文件树组件的设计
import React from 'react'
import { Box, Text } from 'ink'
 
interface TreeNode {
  name: string
  type: 'file' | 'directory'
  children?: TreeNode[]
  status?: 'added' | 'modified' | 'deleted'
}
 
function FileTree({ nodes, selected, depth = 0, expanded }: {
  nodes: TreeNode[]
  selected: string
  depth?: number
  expanded: Set<string>
}) {
  return (
    <Box flexDirection="column">
      {nodes.map(node => {
        const isSelected = node.name === selected
        const indent = '  '.repeat(depth)
        const icon = node.type === 'directory'
          ? (expanded.has(node.name) ? '▾ ' : '▸ ')
          : '  '
 
        const statusColor = {
          added: 'green',
          modified: 'yellow',
          deleted: 'red',
        }[node.status || ''] || 'white'
 
        return (
          <Box key={node.name} flexDirection="column">
            <Text
              color={isSelected ? 'cyan' : statusColor}
              bold={isSelected}
              backgroundColor={isSelected ? 'gray' : undefined}
            >
              {indent}{icon}{node.name}
            </Text>
            {node.children && expanded.has(node.name) && (
              <FileTree
                nodes={node.children}
                selected={selected}
                depth={depth + 1}
                expanded={expanded}
              />
            )}
          </Box>
        )
      })}
    </Box>
  )
}

// 概念性代码：repox review --tui 的整体布局
import React, { useState, useReducer } from 'react'
import { render, Box, Text, useInput, useApp } from 'ink'
import Spinner from 'ink-spinner'
 
// ===== 文件树组件 =====
function FileTree({ files, selected, onSelect }) {
  return (
    <Box flexDirection="column" borderStyle="single" width={30}>
      <Box paddingX={1} borderStyle="single" borderLeft={false} borderRight={false} borderTop={false}>
        <Text bold>变更文件</Text>
        <Spacer />
        <Text dimColor>{files.length}</Text>
      </Box>
      {files.map((file, i) => (
        <Box key={file.path} paddingX={1}>
          <Text
            color={i === selected ? 'cyan' : file.status === 'added' ? 'green' : file.status === 'deleted' ? 'red' : 'yellow'}
            bold={i === selected}
            backgroundColor={i === selected ? 'gray' : undefined}
          >
            {i === selected ? '▸ ' : '  '}
            {file.status === 'added' ? 'A' : file.status === 'deleted' ? 'D' : 'M'}{' '}
            {file.path}
          </Text>
        </Box>
      ))}
    </Box>
  )
}
 
// ===== Diff 预览组件 =====
function DiffView({ diff, scrollOffset }) {
  const lines = diff.split('\n')
  const visibleHeight = (process.stdout.rows || 24) - 6  // 减去边框和状态栏
  const visible = lines.slice(scrollOffset, scrollOffset + visibleHeight)
 
  return (
    <Box flexDirection="column" flexGrow={1} borderStyle="single">
      <Box paddingX={1} borderStyle="single" borderLeft={false} borderRight={false} borderTop={false}>
        <Text bold>差异预览</Text>
      </Box>
      {visible.map((line, i) => (
        <Text
          key={scrollOffset + i}
          color={
            line.startsWith('@@') ? 'cyan' :
            line.startsWith('+') ? 'green' :
            line.startsWith('-') ? 'red' :
            'white'
          }
        >
          {' '}{line}
        </Text>
      ))}
    </Box>
  )
}
 
// ===== 状态栏组件 =====
function StatusBar({ filename, position, total, branch }) {
  return (
    <Box paddingX={1}>
      <Text backgroundColor="blue" color="white" bold>
        {' '}REVIEW{' '}
      </Text>
      <Text> {filename} </Text>
      <Spacer />
      <Text dimColor>⎇ {branch}</Text>
      <Text> </Text>
      <Text dimColor>{position}/{total}</Text>
      <Text>  </Text>
      <Text dimColor>↑↓ 导航  Enter 选择  q 退出</Text>
    </Box>
  )
}
 
// ===== 主应用 =====
function ReviewTUI({ files, diffs, branch }) {
  const [selected, setSelected] = useState(0)
  const [scrollOffset, setScrollOffset] = useState(0)
  const { exit } = useApp()
 
  useInput((input, key) => {
    if (key.upArrow) {
      setSelected(prev => Math.max(0, prev - 1))
      setScrollOffset(0) // 切换文件时重置滚动
    }
    if (key.downArrow) {
      setSelected(prev => Math.min(files.length - 1, prev + 1))
      setScrollOffset(0)
    }
    // j/k Vim 风格滚动 diff 内容
    if (input === 'j') {
      setScrollOffset(prev => prev + 1)
    }
    if (input === 'k') {
      setScrollOffset(prev => Math.max(0, prev - 1))
    }
    if (input === 'q') {
      exit()
    }
  })
 
  return (
    <Box flexDirection="column" height={process.stdout.rows}>
      {/* 主内容区：左右分栏 */}
      <Box flexDirection="row" flexGrow={1}>
        <FileTree
          files={files}
          selected={selected}
          onSelect={setSelected}
        />
        <DiffView
          diff={diffs[selected] || ''}
          scrollOffset={scrollOffset}
        />
      </Box>
 
      {/* 底部状态栏 */}
      <StatusBar
        filename={files[selected]?.path || ''}
        position={selected + 1}
        total={files.length}
        branch={branch}
      />
    </Box>
  )
}

// 概念性代码：命令注册
program
  .command('review')
  .option('--tui', '启动全屏 TUI 界面')
  .option('-f, --format <format>', '输出格式', 'text')
  .action(async (options) => {
    const { files, diffs } = await analyzeChanges()
 
    if (options.tui) {
      // TUI 模式：全屏交互界面
      const { waitUntilExit } = render(
        <ReviewTUI files={files} diffs={diffs} branch="main" />
      )
      await waitUntilExit()
    } else {
      // 标准模式：纯文本输出
      printReviewResult(files, diffs, options.format)
    }
  })

// 启用全屏模式
const { waitUntilExit } = render(<ReviewTUI />, {
  exitOnCtrlC: true,
  // Ink v4+ 支持 stdout 配置
})