Metadata-Version: 2.4
Name: cpp-code-checker
Version: 1.0.0
Summary: C++代码规范检查工具 - 支持命名规范、代码风格和最佳实践检查
Author-email: LiKe <ke_li2@ymtc.com>
License: MIT
Project-URL: Homepage, https://gitee.com/like310101/cpp-code-checker
Project-URL: Repository, https://gitee.com/like310101/cpp-code-checker
Project-URL: Bug Tracker, https://gitee.com/like310101/cpp-code-checker/issues
Project-URL: Documentation, https://gitee.com/like310101/cpp-code-checker/blob/main/README.md
Keywords: cpp,code-checker,lint,code-quality,static-analysis
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: Software Development :: Code Generators
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: LICENSE_GUIDE.md
Dynamic: license-file

# C++编程规范检查工具

自动化检查C++代码规范，支持可配置编码规范、白名单过滤和命令行批量检查。

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python Version](https://img.shields.io/badge/python-3.8%2B-blue)](https://www.python.org/downloads/)
[![PyPI](https://img.shields.io/pypi/v/cpp-code-checker)](https://pypi.org/project/cpp-code-checker/)

## 📄 许可证

本项目采用 **MIT License** 开源许可证。

**许可证摘要**：
- ✅ 允许商业使用
- ✅ 允许修改
- ✅ 允许分发
- ✅ 允许私人使用
- ⚠️ 需要包含版权声明和许可证文本
- ❌ 不提供任何担保

详细内容请查看 [LICENSE](LICENSE) 文件。

## 🚀 快速开始

本项目提供两种使用方式：
1. **VS Code 插件**（推荐用于日常开发）
2. **命令行工具**（推荐用于CI/CD或批量检查）

### ⚠️ 重要提示

**必须在项目根目录运行脚本**

```bash
# ✅ 正确：在项目根目录运行
cd /path/to/project
python3 source/cpp_checker.py

# ❌ 错误：在source目录运行
cd /path/to/project/source
python3 cpp_checker.py  # 会报错！
```

### 🌟 零依赖设计（推荐）

本项目采用**零依赖**设计，**无需安装任何第三方包**（无需 pip），只需 Python 3.8+ 标准库即可运行！

**离线环境使用**：
```bash
# Windows
run.bat

# Linux/Mac
./run.sh

# 或通用方式
python run.py -d .
```

详细说明请查看：[离线部署说明](OFFLINE_DEPLOY.md)

### 方式1：VS Code 插件（推荐用于日常开发）

安装插件后，在 VS Code 中自动检查 C++ 代码：

**安装方法**：
1. 在 VS Code 中按 `Ctrl+Shift+X` 打开扩展市场
2. 搜索 "C++ Code Checker"
3. 点击安装

**使用方法**：
- 保存文件时自动检查（可配置）
- 按 `Ctrl+Shift+C` 检查当前文件
- 命令面板中选择 "检查整个工作区"

详细说明请查看：[VS Code 插件文档](vscode-extension/README.md)

### 方式2：命令行工具（推荐用于CI/CD）

**Linux/macOS**:
```bash
# 进入项目根目录
cd /path/to/project

# 检查当前目录
python3 source/cpp_checker.py

# 检查指定目录
python3 source/cpp_checker.py -d /path/to/code
```

**Windows**:
```cmd
# 进入项目根目录
cd D:\path\to\project

# 检查当前目录（推荐使用 run.bat，自动处理中文编码）
run.bat

# 或直接运行 Python
python source\cpp_checker.py

# 检查指定目录
python source\cpp_checker.py -d C:\path\to\code
```

**💡 中文编码提示**：

Windows 环境下可能出现中文显示为方框的问题（字符编码问题），解决方法：

**方法1：使用 `--no-color` 参数（推荐）**
```cmd
python source\cpp_checker.py -d . --no-color
```

**方法2：使用 `run.bat` 脚本（自动处理编码）**
```cmd
run.bat
```

**方法3：输出到文件**
```cmd
python source\cpp_checker.py -d . -o report.txt
```

**方法4：在 PowerShell 中运行（支持 UTF-8）**
```powershell
$env:PYTHONIOENCODING="utf-8"
python source\cpp_checker.py -d .
```

**原因说明**：
- 部分旧版 Windows 控制台默认编码为 GBK，不支持 UTF-8
- ANSI 颜色代码在某些 Windows 版本中与中文编码兼容性有问题
- 输出到文件或使用 `--no-color` 参数可以避免这些问题

### 方式1：快速检查单个文件

**Linux/macOS**:
```bash
python3 source/cpp_checker.py -f assets/test_code_enhanced.cpp
```

**Windows**:
```cmd
python source\cpp_checker.py -f assets\test_code_enhanced.cpp
```

### 方式2：批量检查整个目录

**Linux/macOS**:
```bash
python3 source/cpp_checker.py -d src/
```

**Windows**:
```cmd
python source\cpp_checker.py -d src\
```

## 🔧 命令行参数

| 参数 | 说明 | 示例 |
|------|------|------|
| `-d, --dir` | 指定要检查的目录 | `-d src` |
| `-f, --file` | 检查单个文件 | `-f main.cpp` |
| `-c, --config` | 指定配置文件路径 | `-c config/my_standards.json` |
| `-w, --whitelist` | 指定白名单文件路径 | `-w config/whitelist.json` |
| `-o, --output` | 输出结果到文件（无颜色代码） | `-o report.txt` |
| `--ignore` | 忽略的目录（空格分隔） | `--ignore build dist` |
| `--ext` | 文件扩展名（空格分隔） | `--ext .cpp .h .hpp` |
| `--generate-whitelist` | 生成白名单 | `--generate-whitelist` |
| `--show-filtered` | 显示白名单过滤数量 | `--show-filtered` |
| `--no-color` | 禁用颜色输出（Windows中文显示问题解决方案） | `--no-color` |
| `-h, --help` | 显示帮助信息 | `-h` |

**使用示例**：

```bash
# 检查目录并输出到文件
python3 source/cpp_checker.py -d src -o report.txt

# 检查文件并输出到文件
python3 source/cpp_checker.py -f main.cpp -o result.txt

# 检查目录，忽略 build 和 dist 目录
python3 source/cpp_checker.py -d . --ignore build dist

# 生成白名单
python3 source/cpp_checker.py -d . --generate-whitelist -o whitelist.json

# 使用自定义配置文件
python3 source/cpp_checker.py -d . -c config/my_standards.json -o output.txt
```

## 📁 项目结构

```
├── source/                      # 源代码
│   ├── cpp_checker.py          # ✅ C++代码规范检查工具主程序
│   ├── base.py                 # 基础工具类和默认配置
│   ├── config_loader.py        # 配置加载器
│   ├── whitelist.py            # 白名单管理器
│   ├── naming_conventions/     # 命名规范规则模块
│   ├── code_style/             # 代码格式规则模块
│   └── best_practices/         # 最佳实践规则模块
│
├── config/                     # 配置文件
│   ├── coding_standards.json  # 编码规范配置
│   ├── white_list.json        # 白名单配置
│   └── need_check_code_dir.json # 检查目录配置文件
│
├── tests/                       # 测试用例
│   ├── cases/                  # 各种规则的测试用例
│   └── README.md               # 测试用例说明
│
├── assets/                      # 测试文件
│   ├── test_code_enhanced.cpp
│   ├── usr_test.cpp
│   └── test_class_struct_naming.cpp
│
├── vscode-extension/           # VS Code 插件
│   ├── src/                   # 插件源码
│   ├── python/                # Python检查工具（符号链接）
│   ├── package.json           # 插件配置
│   └── README.md              # 插件说明文档
```

## 🔧 依赖说明

本项目采用**零依赖**设计，**无需安装任何第三方包**！

| 依赖 | 用途 | 必需 |
|-----|------|------|
| Python 3.8+ | 运行环境 | ✅ |
| 无第三方包 | - | - |

### 安装依赖

```bash
# 检查是否已安装
uv pip list | grep pydantic

# 安装 pydantic
uv add pydantic
```

**说明**：最小依赖版本只需要 pydantic，无需安装 langgraph、langchain 等依赖，完全离线可用。

## ⚙️ 配置文件

### 1. 编码规范配置

**文件**: `config/coding_standards.json`

定义19种命名规范和代码格式标准：
- 类名、函数名、变量名的命名规范
- 代码格式（缩进、空格、大括号风格）
- 最佳实践（const正确性、智能指针等）

### 2. 白名单配置

**文件**: `config/white_list.json`

基于符号的白名单，不依赖行号，代码重构后仍然有效。

**默认白名单文件**：
- `config/white_list.json`

**使用方式**：
- **无需命令行指定**：工具会自动查找并加载白名单文件
- **指定白名单文件**：使用 `-w` 参数指定自定义白名单

**白名单格式**：
```json
{
  "class_struct": [],
  "enum_type": [],
  "enum_value": [],
  "function": ["main"],
  "member_function": [],
  "parameter": [],
  "local_variable": [],
  "constant": [],
  "class_member_variable": [],
  "struct_member_variable": [],
  "global_variable": [],
  "static_global_variable": [],
  "macro": [],
  "file_name": [],
  "indentation": [],
  "line_length": [],
  "function_length": [],
  "cyclomatic_complexity": [],
  "no_extern": []
}
```

**命令行使用示例**：
```bash
# 使用默认白名单文件
python source/cpp_checker.py -f test.cpp

# 指定自定义白名单文件
python source/cpp_checker.py -f test.cpp -w my_whitelist.json
```

**白名单分类说明**：
| 分类 | 说明 | 示例 |
|------|------|------|
| `class_struct` | 类名和结构体名 | `MyClass`, `UartDriver` |
| `enum_type` | 枚举类型名 | `ColorType`, `LogLevel` |
| `enum_value` | 枚举值 | `POWER_OFF`, `COLOR_RED` |
| `function` | 普通函数名 | `main`, `printf`, `FastRead` |
| `member_function` | 成员函数名 | `calculateSum`, `getUserInfo` |
| `parameter` | 函数参数名 | `data`, `length` |
| `local_variable` | 局部变量名 | `myVar`, `temp` |
| `constant` | 常量名 | `MAX_SIZE`, `cMaxBufferSize` |
| `class_member_variable` | 类成员变量 | `_myVar`, `handle` |
| `struct_member_variable` | 结构体成员变量 | `myVar`, `baudRate` |
| `global_variable` | 全局变量名 | `g_var`, `g_uartDriver` |
| `static_global_variable` | 静态全局变量名 | `s_instance`, `s_count` |
| `macro` | 宏定义 | `MAX_SIZE`, `NULL` |
| `file_name` | 文件名 | `my_file.cpp`, `test.h` |

### 3. 检查目录配置

**文件**: `config/need_check_code_dir.json`

配置需要检查的代码目录、忽略列表和文件后缀名。

**配置格式**：
```json
{
  "_comment": "C++代码规范检查工具配置文件",
  "_usage": "使用命令: python source/cpp_checker.py -d config/need_check_code_dir.json",
  "root": "tests",
  "ignore": [
    "build",
    "dist",
    "venv",
    "__pycache__",
    ".git",
    "node_modules"
  ],
  "extensions": [
    ".cpp",
    ".h",
    ".hpp",
    ".cc",
    ".cxx",
    ".c"
  ]
}
```

**配置项说明**：
- `root`: 检查代码根目录（支持相对路径和绝对路径）
  - 绝对路径：如 `"C:\\project\\src"` 或 `"/home/user/project/src"`
  - 相对路径：如 `"."`, `".."`, `"src"`
  - **重要**：相对路径是相对于 `config` 目录（配置文件所在目录）
  - 示例：
    - `"."` → 检查 config 目录
    - `".."` → 检查项目根目录
    - `"src"` → 检查 config 目录下的 src 目录
- `ignore`: 需要忽略的文件夹或文件名列表（相对于 root 目录）
- `extensions`: 需要检查的文件后缀名列表

**输出说明**：
程序运行时会显示实际的检查路径（绝对路径）：
```
使用配置文件: config/need_check_code_dir.json
检查目录: /absolute/path/to/check/
忽略目录: build, dist
```

**使用配置文件**：
```bash
# 使用启动脚本（推荐）
python run.py -d config/need_check_code_dir.json

# 或直接运行主程序
python source/cpp_checker.py -d config/need_check_code_dir.json
```

## 📖 使用场景

### 场景1：日常开发检查

```bash
# 不带参数，自动使用默认配置文件检查
python3 source/cpp_checker.py

# 或使用配置文件
python3 source/cpp_checker.py -d config/need_check_code_dir.json
```

**说明**：
- 不带 `-d` 参数时，工具会自动使用 `config/need_check_code_dir.json` 配置文件
- 可以通过修改该配置文件来调整默认检查行为

### 场景2：历史代码冻结

对于大量不符合规范的历史代码，使用自动白名单生成：

```bash
# 1. 对现有代码进行检查
python3 source/cpp_checker.py -d .

# 2. 生成白名单（冻结历史代码）
python3 source/cpp_checker.py --generate-whitelist

# 3. 使用白名单进行日常检查
# 老代码不受影响，新代码需要遵循规范
python3 source/cpp_checker.py
```

**说明**：
- 不带 `-d` 参数生成白名单时，会自动使用 `config/need_check_code_dir.json` 配置文件
- 白名单默认生成到 `config/white_list.json`

### 场景3：代码审查前严格检查

```bash
# 不使用白名单，发现所有问题
python3 source/cpp_checker.py --generate-whitelist
```

### 场景4：检查特定目录

```bash
# 使用配置文件检查特定目录
python3 source/cpp_checker.py -d config/need_check_code_dir.json

# 或直接指定目录
python3 source/cpp_checker.py -d src
```

## 📊 输出示例

### 控制台输出

```
🔍 正在检查文件: assets/test_code_enhanced.cpp
============================================================
✅ 检查完成

文件名: test_code_enhanced.cpp
整体评分: 55/100
违规数量: 18
过滤数量: 1

摘要: 代码存在命名规范、格式、内存泄漏和野指针等问题...

📋 命名问题 (6个):
------------------------------------------------------------
  🟡 [行7] 中: 类成员变量x不符合_camelCase命名规范
     💡 建议: 修改为_x
  🟡 [行8] 中: 类成员变量y不符合_camelCase命名规范
     💡 建议: 修改为_y

📋 常见错误 (2个):
------------------------------------------------------------
  🔴 [行40] 高: 内存泄漏：使用new[]分配的数组未释放
     💡 建议: 添加delete[] p;
  🔴 [行50] 高: 野指针：未初始化的指针ptr被解引用
     💡 建议: 初始化指针为nullptr或分配内存后再使用

💾 详细报告已保存: assets/test_code_enhanced.cpp_report.json
```

### JSON报告

```json
{
  "filename": "test_code_enhanced.cpp",
  "overall_score": 55,
  "total_violations": 18,
  "filtered_by_whitelist": 1,
  "analysis_data": {
    "naming_issues": [...],
    "format_issues": [...],
    "common_errors": [...],
    "best_practices": [...]
  }
}
```

## ❓ 常见问题

### Q1: 本地使用需要什么依赖？

只需要安装核心依赖：
```bash
# 检查是否已安装
uv pip list | grep pydantic

# 安装依赖
uv add pydantic
```

**说明**：最小依赖版本只需要 pydantic，完全离线可用。

### Q2: 如何使用工具？

有三种使用方式：

1. **使用命令行工具（推荐）**：
```bash
# 不带参数，自动使用默认配置文件检查
python source/cpp_checker.py

# 检查指定目录
python source/cpp_checker.py -d src

# 检查单个文件
python source/cpp_checker.py -f main.cpp

# 使用配置文件
python source/cpp_checker.py -d config/need_check_code_dir.json
```

**默认行为说明**：
- 不带 `-d` 参数时，工具会自动使用 `config/need_check_code_dir.json` 配置文件
- 可以通过修改该配置文件来调整默认检查行为（检查目录、忽略列表、文件后缀名）

2. **使用运行脚本**：
```bash
# Windows
run.bat -d src

# Linux/macOS
./run.sh -d src
```

### Q3: 如何验证环境是否配置正确？

```bash
# 测试导入
python3 -c "from source.cpp_checker import CppCodeChecker; print('✓ 导入成功')"

# 测试命令行工具
python3 source/cpp_checker.py --help
```

### Q4: 白名单如何工作？

白名单基于**符号名称**匹配，不依赖行号：

```json
{
  "class_struct": ["MyClass"],
  "class_member_variable": ["_oldVar"],
  "function": ["main"]
}
```

符号在白名单中，相关的命名规范问题将被过滤。

**默认白名单文件**：`config/white_list.json`

**生成白名单**：
```bash
# 生成白名单到默认位置
python source/cpp_checker.py -d . --generate-whitelist

# 生成白名单到指定位置
python source/cpp_checker.py -d . --generate-whitelist -o my_whitelist.json
```

### Q5: 如何自定义编码规范？

编辑 `config/coding_standards.json`：

```json
{
  "class_member_variable": {
    "style": "下划线前缀+驼峰命名法",
    "pattern": "^_[a-z][a-zA-Z0-9]*$"
  }
}
```

### Q6: 如何使用配置文件检查代码？

创建或编辑 `config/need_check_code_dir.json`：

```json
{
  "root": "src",
  "ignore": [
    "build",
    "dist",
    "venv"
  ],
  "extensions": [
    ".cpp",
    ".h",
    ".hpp"
  ]
}
```

然后使用配置文件检查：
```bash
python source/cpp_checker.py -d config/need_check_code_dir.json
```

### Q7: Windows 环境下遇到中文编码错误怎么办？

如果你看到类似 `UnicodeEncodeError: 'gbk' codec can't encode character` 的错误，可以尝试以下方法：

**方法 1: 使用 run.bat（推荐）**
```cmd
run.bat -d src
```
run.bat 已自动设置 UTF-8 代码页，可以正确处理中文。

**方法 2: 直接使用 Python 命令**
```cmd
python source\cpp_checker.py -d src
```

**方法 3: 输出到文件**
```cmd
python source\cpp_checker.py -d src -o report.txt
```
输出到文件可以避免控制台编码问题。

**方法 4: 设置环境变量**
```cmd
set PYTHONIOENCODING=utf-8
python source\cpp_checker.py -d src
```

详细解决方案请参考：[离线部署说明](OFFLINE_DEPLOY.md)

## 📚 文档

- [离线部署说明](OFFLINE_DEPLOY.md) - 离线环境部署指南
- [快速开始](QUICKSTART.md) - 快速开始指南
- [测试用例说明](tests/README.md) - 测试用例和规则说明

## 🎯 特性

✅ **VS Code 插件**: 实时代码检查，保存文件时自动检查
✅ **批量检查**: 一次性检查整个项目的所有文件
✅ **跨平台**: 支持Windows、Linux、macOS
✅ **UTF-8 支持**: 完整支持中文字符，自动处理编码问题
✅ **可配置**: 自定义编码规范和白名单
✅ **白名单机制**: 基于符号，代码重构后仍然有效
✅ **详细报告**: 包含行号、错误类型、修改建议
✅ **配置文件**: 支持使用 JSON 配置文件管理检查参数
✅ **模块化设计**: 每个规则独立为一个模块，易于维护和扩展
✅ **输出到文件**: 支持将检查结果输出到文件，便于归档和分享

## 🔌 VS Code 插件

### 安装

1. 在 VS Code 中按 `Ctrl+Shift+X` 打开扩展市场
2. 搜索 "C++ Code Checker"
3. 点击安装

### 使用

**快捷键**：
- `Ctrl+Shift+C` - 检查当前文件

**命令**：
- `C++ Code Checker: 检查当前文件`
- `C++ Code Checker: 检查整个工作区`
- `C++ Code Checker: 生成白名单`

详细说明请查看：[VS Code 插件文档](vscode-extension/README.md)

## 🔗 技术栈

- **语言**: Python 3.8+
- **核心依赖**: Python 标准库（零第三方依赖）
- **正则表达式**: Python re 模块
- **配置文件**: JSON 格式
- **数据类**: Python dataclasses 模块

## 📝 许可证

内部使用

## 🤝 支持

如有问题，请参考文档或联系开发团队。
