clang-tidy 静态检查

仓库根 .clang-tidy 已配置检查集(google-/readability-/performance-/ modernize- 等,豁免项集中管理)且 WarningsAsErrors: '*' —— 任何告警即 失败。头文件过滤:HeaderFilterRegex 只覆盖 include/vlink|src|modules|cli|proxy。

先从仓库任意子目录解析根目录:

REPO_ROOT="$(git rev-parse --show-toplevel)"
PHYSICAL_CORES=
case "$(uname -s 2>/dev/null)" in
  Linux)
    PHYSICAL_CORES="$(
      LC_ALL=C lscpu -p=CORE,SOCKET 2>/dev/null |
        awk -F, '
          $1 !~ /^#/ && $1 ~ /^[0-9]+$/ && $2 ~ /^[0-9]+$/ {
            cores[$2 SUBSEP $1] = 1
          }
          END {
            for (core in cores) {
              count++
            }
            if (count > 0) {
              print count
            }
          }'
    )" || PHYSICAL_CORES=
    ;;
  Darwin)
    PHYSICAL_CORES="$(sysctl -n hw.physicalcpu 2>/dev/null)" || PHYSICAL_CORES=
    ;;
esac
case "$PHYSICAL_CORES" in
  '' | *[!0-9]* | 0) PHYSICAL_CORES=1 ;;
esac
if [ "$PHYSICAL_CORES" -gt 1 ]; then
  BUILD_JOBS=$((PHYSICAL_CORES - 1))
else
  BUILD_JOBS=1
fi

AI 创建的 clang-tidy 构建目录必须位于 build-ai/ 下并使用 skill_clang_tidy 前缀;不得复用、覆盖或清理维护者、IDE、CI 的其他 构建目录。默认目录正被其他任务使用时改用 skill_clang_tidy_<task_name> 或 skill_clang_tidy_file_<task_name>。 执行以下任一路径前设置 PYTHONPYCACHEPREFIX="$BUILD_DIR/__pycache__"。

1. 检查指定文件

需要 compile_commands.json。使用独立目录生成(仅 configure,不编译), 避免改写维护者日常构建配置:

BUILD_DIR="$REPO_ROOT/build-ai/skill_clang_tidy_file"
export PYTHONPYCACHEPREFIX="$BUILD_DIR/__pycache__"
cmake -S "$REPO_ROOT" -B "$BUILD_DIR" \
  -DENABLE_CXX_STD_20=OFF \
  -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

然后对改动过的 .cc 文件运行:

clang-tidy -p "$BUILD_DIR" <file1.cc> <file2.cc>

纯头文件改动:找到包含它的某个 .cc 作为入口来跑。

2. 检查全仓库

以下只展示 clang-tidy 随编译执行的机制,不是 CI 参数的完整复现。 完整门禁参数以 .github/scripts/ci-tidy.sh 和 workflow 提供的 VLINK_CI_CMAKE_ARGS 为准;该 CI 脚本使用 CI 自己的构建目录,AI 在 当前工作区不得直接执行,必须把所需参数用于以下 skill 专属目录:

BUILD_DIR="$REPO_ROOT/build-ai/skill_clang_tidy"
export PYTHONPYCACHEPREFIX="$BUILD_DIR/__pycache__"
cmake -S "$REPO_ROOT" -B "$BUILD_DIR" \
  -DENABLE_CXX_STD_20=OFF \
  -DCMAKE_CXX_CLANG_TIDY=clang-tidy
cmake --build "$BUILD_DIR" --parallel "$BUILD_JOBS"

耗时长(CI 限时 120 分钟),仅在需要完整复现 CI 门禁时使用。 BUILD_JOBS 必须严格等于 max(真实物理核心数 - 1, 1)。禁止改用逻辑 CPU 数、裸 --parallel/-j 或固定高并行度;无法可靠获取时固定单核, 且同一时刻只运行一个本地构建,防止 clang-tidy 随编译并发卡死或耗尽 内存。

3. 结果处理

• 有告警时先报告;用户同时要求修复时优先修复源码。确属误报或有意 写法时优先在目标行前使用 // NOLINTNEXTLINE(<检查名>);只有不适合放在前一行时才使用同行 // NOLINT(<检查名>)。必须带具体检查名并保持最小范围,见 .agents/languages/CPP.md §11。 禁止修改 .clang-tidy 配置——检查集由维护者统一治理。
• test/**/*.cc 已整体 // NOLINTBEGIN/// NOLINTEND 包裹,tidy 告警 不适用于 test 目录。
• 修复方式须符合 .agents/languages/CPP.md(如 modernize 类告警按仓库惯用 写法修,而非教科书写法)。