# repostack doctor

> 

诊断 stack 配置和健康状况。

```bash
repostack doctor
```

## 执行流程

`doctor` 是纯诊断命令，**不会修改任何文件**。它按顺序执行以下检查：

### 1. `repostack.yaml` 检查

- 文件是否存在。
- 是否能被成功解析为有效 YAML。
- **如果失败**：标记为 `error` 并直接停止后续检查（因为后续都依赖配置）。

### 2. 用户配置检查

- **若定义了 `users`**：

  - 检查 `.repostackrc` 是否存在。
  - 检查其中指定的用户是否在 `users` 列表中。
  - 任一失败标记为 `error`。
- **若未定义 `users`**：

  - 检查 `.repostackrc` 是否存在。
  - 若存在标记为 `warning`（提示多余的 rc 文件）。

### 3. `.gitignore` 检查

- 检查 `.gitignore` 是否包含 `.repostackrc`。
- 仅在以下情况执行：

  - 配置中定义了 `users`，或
  - `.repostackrc` 文件已存在。
- 若 `.gitignore` 缺失或不包含该规则，标记为 `warning`。

### 4. Repo 状态检查

- 遍历 `config.repos` 中的每个 repo：

  - 路径是否存在？
  - 路径是否为 Git 仓库？
  - 任一失败标记为 `error`。

### 5. Lock 文件检查

- 检查 `repostack.lock.yaml` 是否存在。
- 缺失时标记为 `warning`（并提示运行 `repostack snapshot`）。

### 6. Stack root Git 检查

- 检查当前目录是否为 Git 仓库。
- 不是则标记为 `error`。

### 7. Repo 父目录 `.gitignore` 检查

- 对每个 repo，检查其父目录的 `.gitignore` 是否包含该 repo 的目录名。
- 目的是防止子 repo 被意外提交到 stack root 的 Git 历史中。
- 失败时标记为 `warning`。

### 8. 未跟踪 Git 仓库扫描

- 在 stack root 下扫描深度为 **2** 的目录结构。
- 跳过已注册的 repo 和 `.git` 目录。
- 如果发现独立的 Git 仓库但**未在 `repostack.yaml` 中注册**，标记为 `warning`。
- 扫描过程中的权限错误会被静默忽略。

## 输出格式

每条检查结果以图标前缀显示：

- `✓` 绿色 — 正常
- `⚠` 黄色 — 警告（建议修复，但命令仍返回 0）
- `✗` 红色 — 错误（严重问题）

## 涉及文件

| 文件                    | 操作         |
| --------------------- | ---------- |
| `repostack.yaml`      | 读取         |
| `.repostackrc`        | 读取         |
| `.gitignore`          | 读取         |
| `repostack.lock.yaml` | 读取（仅检查存在性） |
| 各 repo 目录及父目录         | 读取         |

## 副作用

- **无**。这是一个只读诊断命令。

## 错误与边界情况

- 只有 `repostack.yaml` 缺失或解析失败时才会提前终止。
- 其他单项检查失败只会记录问题，不会中断流程。
- 未跟踪仓库扫描深度硬编码为 2，深层嵌套的仓库不会被检测到。

## 输出示例

```text
✓ repostack.yaml exists
✓ .gitignore contains .repostackrc
✓ Using user: alice
✓ Repo 'foo': OK
✓ Repo 'bar': OK
⚠ Lock file not found. Run: repostack snapshot
✓ Stack root is a git repository
```

## 适用场景

- 排查配置问题
- 验证环境设置
- CI/CD 前置检查