描述

本 PR 在 hcomm 仓新增 .clang-tidy 函数复杂度控制配置 + scripts/clang_tidy_check.py 增量拦截脚本 + build.sh 集成，实现新增代码的函数复杂度真正拦截（存量代码不阻塞）。

配置文件 .clang-tidy

启用 readability-function-size + readability-function-cognitive-complexity，阈值遵循华为 C/C++ 编程规范：函数行 50 / 语句 50 / 分支 15 / 参数 6 / 嵌套 4 / 认知复杂度 25。WarningsAsErrors 留空（脚本控制阻断）。

增量拦截脚本 scripts/clang_tidy_check.py + .sh

• git diff TARGET_BRANCH...HEAD 找变更文件 + 新增行号
• clang-tidy -p build <变更文件> 跑（带 compile_commands.json）
• 过滤告警：只保留告警行在新增行内的（存量函数告警过滤）
• 有违规则 exit 1（阻断）
• Fallback：无 clang-tidy / compile_commands.json / base-ref 时跳过（exit 0），不误阻断

build.sh 集成

构建后调用 clang_tidy_check.sh，ENABLE_CLANG_TIDY_CHECK 环境变量控制（默认 on）。

拦截语义

• 新增函数（定义行是新增）→ 告警行在新增行 → 拦截 exit 1
• 修改存量超阈值函数 1 行（定义行非新增）→ 告警过滤 → 不拦截
• 存量代码不阻塞，只拦新增代码

变更类型

• ✨ 新特性

关联的Issue

• hcomm issue：https://gitcode.com/cann/hcomm/issues/752
• 上游 infrastructure issue：https://gitcode.com/cann/infrastructure/issues/229

测试

已完成的测试用例和场景：

1. 独立测试项目 5 用例全通过：
   • case1 新增 7 参数函数 → 拦截 exit 1 ✅
   • case2 新增 50 变量函数 → 拦截 exit 1 ✅
   • case3 存量超阈值函数改 1 行（非定义行）→ 过滤 exit 0 ✅
   • case4 新增合规函数 → 通过 exit 0 ✅
   • case5 NOLINT 豁免 → 通过 exit 0 ✅
   • case6 新增 59 行函数 → 拦截 exit 1 ✅
2. hcomm 真实场景端到端验证：exception_callback_mgr.cc 加 7 参数函数 → 脚本检测违规 + exit 1 ✅
3. OAT 合规检查通过（scripts 文件带 license header，Invalid File Type=0，License Header Invalid=0）

补充的UT用例：NA（脚本是构建工具，非库代码）

文档更新

.clang-tidy 配置文件内含详细注释（英文，Scope/Local verification/CI integration 说明）。scripts/clang_tidy_check.py 含模块级 docstring。

合入检查

• 🧐 已读贡献指南
• 🔍 committer 检查前必要项
  • 🏷️ 标题类型标签 [enhancement]
  • 📄 变更已描述
  • 📝 注释已更新
  • 🛠️ 静态分析通过（YAML + OAT + clang-tidy 配置生效验证）
• 🚀 前冒烟检查
  • 🔧 编译无错误（仅新增配置+脚本，build.sh 集成有 fallback）
• 🎯 approver 检查

CI 拦截说明

本 PR 的 build.sh 集成会在 CI Compile 任务构建后跑 clang-tidy 增量检查。若 CI Compile 镜像未装 clang-tidy，脚本 fallback 跳过（exit 0，不阻断）。真正 CI 拦截需 infrastructure 在 Compile 镜像预装 clang-tidy（issue #229 范围）。

检视意见修复（第 2 轮，2026-10-20）

针对本 PR 六条检视意见（1 HIGH + 3 MEDIUM + 2 LOW）逐一修复：

1. [HIGH] 修复脚本 cwd 依赖：入口解析仓库根（git rev-parse --show-toplevel）并 os.chdir，git pathspec 与 os.path.isfile 均以仓库根解析，build/ 目录下调用不再漏检
2. [MEDIUM] parse_warnings 保留 file 字段：违规判定增加告警文件与被检文件的归一化绝对路径比对，头文件告警即使行号落入新增行也不会误拦
3. [MEDIUM] clang-tidy 返回码检查：run_clang_tidy 返回 (output, returncode)，分析失败（rc!=0）打印醒目 WARNING 并计入汇总，不再静默 PASS
4. [MEDIUM] base-ref 回退修复：按 upstream → origin 顺序尝试，分支名从 TARGET_BRANCH 或默认 base-ref 派生，fetch 用显式 refspec 真正更新 remote-tracking ref
5. [LOW] HeaderFilterRegex 锚定：改为 (^|[/\])(src|include|pkg_inc|test|experimental)[/\]，兼容相对路径与 compile database 绝对路径，锚定到路径段边界
6. [LOW] 仓内单测补齐：新增 scripts/clang_tidy_check_test.py（8 用例：-U0 hunk 解析含纯删除、cwd 无关性、告警 file/line/check 解析、compile db 归一化），接入 build.sh UT 流程

新增发现并修复（拦截生效关键）：两仓 CMake 均未导出 compile_commands.json，构建不产出该文件导致检查从未真正执行；已加 -DCMAKE_EXPORT_COMPILE_COMMANDS=ON。

特殊情况屏蔽（豁免）：

• // NOLINT(check) / // NOLINTNEXTLINE(check) 原生抑制（.clang-tidy 注释说明用法）
• 无 compile_commands.json 条目的变更源文件（生成代码/第三方源码）显式跳过并打 WARNING
• 变更头文件无编译条目时以 standalone -x c++ 模式分析，新增复杂度仍被拦截

测试：本机 python 单测 8/8 通过（Windows python 3.14 + Linux python 3.10 双验证）；WSL clang-tidy 14.0.1 真实验证 8 场景全通过（新增 7 参函数拦截 exit 1 / NOLINT 与 NOLINTNEXTLINE 豁免 exit 0 / 存量行告警过滤 / 第三方文件跳过 / 头文件 50+ 行 standalone 拦截 / build 子目录调用 cwd 无关 / 配置 dump 解析通过）。

交叉验证修复（2026-10-20 晚，glm-5.3 独立模型交叉检视后）

1. HeaderFilterRegex YAML 引号 bug 修复：双引号字符串内反斜杠被 YAML 转义吞掉，正则字符集未闭合成为非法正则（llvm::Regex 静默失效，头文件过滤完全落空）。改为 YAML 单引号（单引号内无反斜杠转义），正则文本为 (^|[/\])(src|include|pkg_inc|test|experimental)[/\]。WSL 真实场景验证：被检源文件 include 的违规头文件告警现在正确出现（修复前被整体抑制），且被脚本按文件归一化比对正确过滤不误拦，新增违规头文件仍被拦截。
2. build.sh 错误日志死代码修复：set -e 下 bash ... ; if [ $? -ne 0 ] 的失败日志永不打印，改为 if ! bash ...; then log ...; exit 1; fi，退出码语义不变、错误信息可见。
3. 脚本移除冗余 +++ 行排除条件（new_start 守卫已覆盖文件头），docstring 补充头文件 standalone 无 -I 的告警语义。
4. 单测增至 9 用例（新增重命名文件场景），WSL clang-tidy 14.0.1 真实验证累计 16 场景全通过。

未采纳说明（记录为设计边界）：增量检查挂在默认构建分支（CI Compile 任务走默认 build.sh 入口，见流水线任务表）；头文件 standalone 无 -I 路径（失败仅告警不阻断）；ENABLE_CLANG_TIDY_CHECK 仅环境变量开关（与仓内 env 开关惯例一致）。

第三轮（2026-10-21，检视意见 jiyuanhao + 可读性/验证要求）

1. 脚本目录收敛：三个脚本移至 scripts/clang-tidy/（避免与 scripts/ 打包脚本混淆），build.sh 与 .clang-tidy 引用同步更新
2. .clang-tidy 注释重写为白话规则说明：每条阈值的含义、检查范围（全仓 C/C++ 变更文件均纳入：db 条目源文件带全编译参数分析、头文件 standalone、无条目第三方源显式跳过）、NOLINT/NOLINTNEXTLINE 屏蔽示例、执行时机（默认构建后，非 UT）、缺依赖行为（不自动下载，WARNING+跳过+安装命令）、一分钟自测配方
3. CI 实证（v8 日志端点下载）：
   • Compile 任务日志：bash build.sh --pkg 后真实执行 Running clang-tidy incremental check (ENABLE_CLANG_TIDY_CHECK=on)，当前镜像无 clang-tidy 按设计 WARNING 跳过
   • UT 任务日志：Ran 9 tests in 0.116s / OK——单测在 UT 流程最先执行并通过

第四轮（2026-10-21，作者要求：基线加固 + 豁免政策）

1. 增量基线加固：default base-ref 恒为 upstream/<目标分支>（CI 的 TARGET_BRANCH 只选分支名，不再产生裸本地分支名，杜绝"本地过期分支被当基线"）；resolve_base_ref 使用前从 remote fetch 刷新（upstream→origin 回退）；docstring 与 .clang-tidy 注释写明三点 diff 语义——新增行永远指"本分支相对 gitcode 上游最新目标分支的新增"，上游新增行不会归属到本分支
2. 豁免政策：.clang-tidy 注释重写为原则上禁止屏蔽（"complex functions get split, not silenced"，豁免行与代码同等检视，无理由的豁免会被拒绝）；示例隐晦化——机制只指向 clang-tidy 官方文档，不再给出可照抄的完整 NOLINT 样板；自测配方保留一个泛化写法（// NOLINT(<FAIL 行报告的检查名>)）并注明仅限自测
3. 单测增至 12 用例（新增 default_base_ref 的 TARGET_BRANCH 语义两例）；自测配方补提交步骤（检查只对比已提交变更，与 CI 语义一致）