Jenkins 共享库 Linter

这个技能解决什么问题

Jenkins 共享库的 Groovy 代码有一个很具体的痛点：错误发现得太晚。vars/ 下的脚本、src/ 里的带 @CpsTransform 的方法、resources/ 中被共享库加载器引用的资源，只有在流水线真正被 Jenkins controller 加载执行时才会暴露问题。反馈链路被迫变成：跑一次构建 → 翻日志 → 定位到共享库 → 修改 → 再跑一次，一次语法错误就可能消耗十几分钟。

更麻烦的是，共享库并不是纯 Groovy。它运行在 Jenkins 的 Groovy 沙箱里，依赖 Jenkins core 的 AST 转换、@NonNull / @CheckForNull 的注解语义、CpsFunction 以及共享库加载机制。通用 Groovy linter 要么不认识这些构造，要么把 Jenkins 特有的合法写法误报成错误。

它是如何工作的

这个技能把检查提前到代码落盘与流水线执行之间，核心是两套解析能力的组合：

• Groovy AST parser：把共享库中的 *.groovy 解析成抽象语法树，逐节点检查语法结构、声明顺序、作用域与引用完整性。AST 层面的判断比正则匹配可靠得多。
• Jenkins Pipeline Model Definition API：把 declarative pipeline 建模成结构化的 pipeline 模型，而不是当作一段文本。这样 stage / steps / post 的结构、environment 与 options 的用法才能被真正解析和校验。

在此基础上按共享库的常见约定做静态扫描，重点识别两类问题：

1. 语法错误——括号不匹配、缺失的 import、非法的方法签名、声明式语法中不合法的块。
2. 反模式——会被 Jenkins 沙箱拒绝或要到运行时才报错的写法，例如在 @NonNull 标注的位置传入可能为 null 的表达式、跨脚本引用未声明的变量、CpsTransform 作用域下的不安全调用。

关键步骤可以概括为：

• 扫描共享库目录，定位 vars/、src/、resources/ 下的候选文件；
• 用 Groovy AST parser 构建语法树，用 Pipeline Model Definition API 构建 pipeline 模型；
• 对照 Jenkins 的共享库约定逐条做规则匹配；
• 在本地或提交阶段直接输出可定位的错误，而不是等到 CI 里。

适用边界与注意点

它不是运行时模拟器，以下几点需要明确：

• 不做行为验证。sharedLibrary 的加载、凭据与权限的实际解析、CpsCallableInvocation 的执行结果，只能在 Jenkins controller 的真实运行环境中确认，静态检查无法覆盖。
• 不保证穷尽 Jenkins 特有的运行时反模式。Jenkins core 的 AST 转换会随版本变化，不同版本处理同一段代码可能有差异，规则集需要跟随目标 Jenkins 版本。
• 依赖环境一致性。上游资料来自 Jenkins 项目的官方分发（WAR、Docker 镜像、原生包与各平台安装包）以及 Jenkins 开发者文档和贡献指南。要保证检查结果可靠，本地的 Groovy 与 Pipeline 依赖应当与目标 Jenkins 版本对齐，而不是随便拉一份 Groovy 就跑。
• 覆盖范围以声明式 pipeline 和共享库 Groovy 为主。自由式任务、Jenkinsfile 之外的外部 Groovy 脚本、插件自定义 step 的语义，不在其主要检查范围内。
• 定位是前置防线，不是替代。把它接在提交钩子或 CI 的早期阶段最划算——先拦住语法和反模式，运行时问题留给真正的 Jenkins 构建去暴露。