# C++ Linter Template

這是一個符合最佳實務、可漸進式導入的 C++ linter 自動化模板。現為 Phase 1：格式嚴格、靜態分析建議不擋流程。

## 目標
- 對舊 C++ 專案導入 `clang-tidy` 與 `clang-format`
- 提供「先格式、後強化」的漸進策略
- 內建 Azure DevOps CI/CD 串接與 PR 差異分析

## 快速開始（Phase 1）

### 1) 安裝工具
```bash
# Ubuntu/Debian
sudo apt install clang-tidy clang-format cmake build-essential

# macOS
brew install llvm cmake
```

### 2) 產出 compile_commands.json（建議）
```bash
mkdir -p build && cd build
cmake .. -DCMAKE_EXPORT_COMPILE_COMMANDS=ON
cd -
```

### 3) 執行 Linter
```bash
# 使用腳本（會自動偵測 build/compile_commands.json）
./scripts/run-linter.sh
```

### 4) 安裝 Git hooks（建議）
```bash
./scripts/setup-hooks.sh
```
- pre-commit 會自動 clang-format 已 staged 的 C/C++ 檔並要求你重提一次 commit。
- clang-tidy 以建議模式執行（不擋提交）。

### 5) 建構與執行
```bash
mkdir -p build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Debug
make -j$(nproc)
./tests
./main
```

## Phase 1 政策（建議 → 強制的起點）
- 格式：以 `.clang-format` 為準；CI 以 `--dry-run --Werror` 強制。
- 靜態分析：`.clang-tidy` 啟用 `clang-analyzer-*` 與精選 `bugprone-*`；僅回報警告，不讓 CI 失敗。
- PR：僅分析變更檔案，加速回饋。

## CI 流程（Azure Pipelines）
1. 安裝工具與版本資訊
2. `clang-format --dry-run --Werror`（不合格式即失敗）
3. 以 CMake 匯出 `build/compile_commands.json`
4. `clang-tidy -p build` 掃描（建議模式，不擋流程）
5. Build 專案與執行 `./tests`、`./main`
6. PR Job 僅對變更檔案跑 `clang-tidy -p build`

## 自定義規則
- `.clang-tidy`：Phase 1 強調重大缺陷檢查（例如 analyzer、部分 bugprone）。
- `.clang-format`：基於 LLVM 風格（IndentWidth=4, ColumnLimit=100）。

## 文件
- `docs/linter-setup.md`：本地與 CI 設定流程
- `docs/coding-standards.md`：編碼與格式規範（Phase 1）

## 專案結構
cpp-linter-template/
├── .clang-tidy                 # linter 配置檔（Phase 1）
├── .clang-format               # 格式化配置
├── azure-pipelines.yml         # Azure DevOps CI/CD 配置
├── CMakeLists.txt              # 建構配置（C++98）
├── README.md                   # 專案說明（本檔）
├── docs/                       # 文件目錄
│   ├── linter-setup.md         # Linter 設定指南
│   └── coding-standards.md     # 編碼標準（Phase 1）
├── src/                        # 原始碼
│   ├── main.cpp                # 主程式（含測試片段）
│   ├── utils.cpp               # 工具函數
│   └── utils.h                 # 標頭檔
├── tests/                      # 測試程式碼
│   └── test_main.cpp           # 最小測試（無框架）
└── scripts/                    # 輔助腳本
    ├── run-linter.sh           # 本地執行 linter
    └── setup-hooks.sh          # 安裝 pre-commit hooks

## 後續階段（預覽）
- Phase 2：對關鍵 tidy 規則轉為失敗門檻（資源管理/未定義行為）。
- Phase 3：引入 readability/modernize 並在 PR 變更檔上強制。
- Phase 4：全域強制，警告視為錯誤（需技術債清理完成）。