# 开发指南 (Development Guide)

欢迎参与 `l-tool` 的开发！本指南将帮助你了解如何构建、测试和贡献代码。

## 环境准备

确保你已经安装了 Rust 工具链 (Rustc, Cargo)。

```bash
# 检查版本
cargo --version
```

## 构建与运行

```bash
# 构建项目
cargo build

# 运行项目
cargo run -- help

# 构建发布版本
cargo build --release
```

## 项目结构

```
l-tool/
├── src/
│   ├── commands/       # 子命令实现
│   │   ├── js/         # JS 相关命令
│   │   ├── image/      # 图片处理命令
│   │   ├── pdf/        # PDF 处理命令
│   │   └── git/        # Git 相关命令
│   ├── types/          # 通用类型定义
│   ├── utils/          # 工具函数
│   ├── lib.rs          # 库入口，导出模块
│   └── main.rs         # 二进制入口
├── tests/              # 集成测试
├── docs/               # 文档目录
└── Cargo.toml          # 项目配置
```

## 测试规则 (Testing Rules)

为了保持代码质量和项目整洁，请严格遵守以下测试规则。

### ❌ 禁止行为 (Prohibited Actions)

1. **禁止在项目根目录创建临时文件进行测试**
   - 不允许创建 `test_*.json`、`example_*.rs` 等临时文件。
   - 不允许在根目录创建任何用于测试目的的临时文件。
   - 不允许修改项目根目录的 `package.json` 等配置文件进行测试。

2. **禁止在 `examples/` 目录创建临时演示文件**
   - `examples/` 目录应该只包含正式的示例代码。
   - 不允许创建临时的演示程序。

### ✅ 正确做法 (Correct Practices)

1. **使用正式的测试框架**
   - 在 `tests/` 目录下创建集成测试。
   - 在 `src/` 目录下的模块中创建单元测试 (`#[cfg(test)]` 模块)。
   - 使用 `tempfile::TempDir` 创建临时测试环境。

2. **测试日志功能的正确方式**

   ```rust
   #[cfg(test)]
   mod tests {
       use super::*;
       use tempfile::TempDir;
       
       #[test]
       fn test_log_functions() {
           // 测试各种日志函数
           success("测试成功日志");
           error("测试错误日志");
           // 验证输出或行为
       }
   }
   ```

3. **测试文件操作的正确方式**

   ```rust
   #[test]
   fn test_package_json_parsing() {
       let temp_dir = TempDir::new().unwrap();
       let package_json_path = temp_dir.path().join("package.json");
       
       // 创建临时测试文件
       std::fs::write(&package_json_path, r#"{"name": "test"}"#).unwrap();
       
       // 执行测试逻辑...
       
       // TempDir 会在离开作用域时自动清理
   }
   ```

## 代码风格

- 使用 `cargo fmt` 格式化代码。
- 使用 `cargo clippy` 进行代码静态分析。
