ShellCheck 开发指南：构建、架构解析与新检查项的编写实践

ShellCheck 开发指南构建、架构解析与新检查项的编写实践【免费下载链接】shellcheckShellCheck, a static analysis tool for shell scripts项目地址: https://gitcode.com/gh_mirrors/sh/shellcheckShellCheck 是一个用 Haskell 编写的 shell 脚本静态分析工具能够在脚本执行前发现常见错误、陷阱与风格问题。本指南面向希望参与 ShellCheck 开发的贡献者完整覆盖仓库内的构建与测试命令、三阶段流水线架构、关键源码文件映射以及从零新增一条检查项的标准流程帮助读者快速上手开发环境并理解底层实现原理。构建与测试日常开发的完整命令集仓库根目录的.claude/CLAUDE.md给出了从编译、单测到调试的整套命令。这些命令都基于 Cabal/GHC 工具链前提是本地已安装 GHC 与 cabal-install。标准编译与测试cabal build # 编译 cabal test # 运行单元测试权威来源 source of truth cabal run shellcheck -- file.sh # 对文件执行检查 cabal run shellcheck - cmd # 对内联输入执行检查其中cabal test被明确标注为测试的 source of truth权威来源因为 test/shellcheck.hs 会聚合ShellCheck.Analytics、ShellCheck.Parser、ShellCheck.Checks.Commands、ShellCheck.CFGAnalysis等全部模块的runTests任何一个模块的测试失败都会导致整体退出码非零。该文件顶部mapM sequenceA tests逐模块收集测试结果最终打印失败的模块名并以exitFailure结束。免编译的解释执行模式每次改动都重新编译会拖慢迭代节奏仓库为此提供了两个解释执行脚本./quickrun - cmd # 解释模式运行快速、无需重新编译 ./quicktest # 解释模式跑测试快速、无需重新编译从 quickrun 的源码可以看到它先通过find在dist*构建目录中定位Paths_ShellCheck.hs第一次使用前必须至少执行过一次cabal build否则会报错退出随后用runghc -isrc直接解释执行 shellcheck.hs。quicktest 的原理类似但它借助ghci加载 test/shellcheck.hs通过判断输出中是否包含ExitSuccess来判定测试是否全部通过。申请新的警告编号ShellCheck 的每条检查项都有独立的SC1xxx语法/解析、SC2xxx分析或SC3xxx数据流/CFG编号./nextnumber # 打印下一个可用的 SC1xxx/SC2xxx/SC3xxx 编号nextnumber 脚本要求 Bash 4依赖globstar其实现是遍历仓库内所有.hs文件用正则提取形如1xxx、2xxx、3xxx的数字并取最大值加一分别输出三段编号的下一个可用值。在新增检查项之前运行它可以避免与现有警告编号冲突。交互式 REPL 开发对于需要反复试错的场景文档推荐进入 GHCi 交互环境cabal repl # 进入交互式 REPL # 之后在 GHCi 中 # :load ShellCheck.Debug # 加载调试辅助模块 # :r # 编辑源码后重载 # shellcheckString your shell code # 直接对字符串执行完整检查shellcheckString定义在 Debug.hs返回一个完整的CheckResult非常适合在不写测试的情况下快速验证新检查项的行为。不进入交互会话直接看 AST在 shellcheck-dev.hs 中提供了一个专为开发官方注释明确提到其潜在受益者是 AI/自动化工具设计的子命令入口cabal run -fdev-mode shellcheck-dev -- ast myshellcommandshellcheck-dev通过-fdev-modeCabal flag 启用目前只注册了ast一个子命令内部调用Debug.stringToAst见 Debug.hs将一行 shell 命令解析并打印为 Token 树是理解解析结果的最直接手段。注意cabal run -fdev-mode意味着需要以 dev-mode 特性重新编译该目标。架构三阶段流水线ShellCheck 处理一份 shell 脚本时严格经过三个阶段.claude/CLAUDE.md的 Architecture 一节:Parsing解析——核心实现在 Parser.hs。基于 Parsec 组合子解析器把源码转换为 AST同时产出 SC1xxx 编号的警告。解析器注释parser notes是非致命的会被缓存起来一旦整个解析失败即被丢弃而解析器问题parser problems是致命的永远会被保留并输出。AST AnalysisAST 分析——核心实现在 Analytics.hs 以及 Checks/ 目录下遍历 AST 并产出 SC2xxx/SC3xxx 编号的警告。Output输出——核心实现在 Formatter/ 目录把诊断结果格式化为 TTY、JSON、GCC 风格、diff 等不同输出形式。三个阶段在 shellcheck.hs 的main中串联process解析命令行参数与SHELLCHECK_OPTS环境变量用空格切分写在命令行参数之前生效为每个输入文件构造CheckSpec调用checkScript完成解析与分析最后交给 formatter 渲染结果。各阶段职责的源码佐证解析阶段Parser.hs产出的是TokenAST节点类型定义在 AST.hs。解析器对语法错误和非致命注释的差异化处理决定了后续分析器能拿到什么样的输入。分析阶段Analytics.hs 定义了treeChecks在 AST 根节点上运行一次的整体性检查如checkUnusedAssignments、checkShebang、checkUnassignedReferences与nodeChecks对每个节点运行如checkPipePitfalls、checkForInLs。nodeChecksToTreeCheck会把所有 node check 折叠成一次遍历保证整棵树的节点检查只走一遍。此外还有独立的 CFG 体系CFG.hs 与 CFGAnalysis.hs支撑 Checks/ControlFlow.hs 中的数据流分析。输出阶段shellcheck.hs中的formats映射shellcheck.hs注册了七种格式器checkstyle、diff、gcc、json、json1、tty、quiet对应Formatter/目录下的同名模块。关键源码文件速查表.claude/CLAUDE.md给出了与各阶段对应的关键文件映射完整罗列如下文件用途src/ShellCheck/AST.hsToken 类型定义AST 节点类型src/ShellCheck/ASTLib.hs操作 AST 节点的辅助函数如getLiteralStringsrc/ShellCheck/Analytics.hs主分析器treeChecks与nodeChecks列表src/ShellCheck/AnalyzerLib.hs检查项作者的共享工具warn、err、style等src/ShellCheck/Checks/Commands.hs按命令名分发的逐命令检查src/ShellCheck/Checks/ShellSupport.hs按 shell 方言分发的检查src/ShellCheck/Checks/ControlFlow.hs控制流 / CFG 检查src/ShellCheck/CFG.hs、CFGAnalysis.hs控制流图构建与分析src/ShellCheck/Parser.hs基于 Parsec 的 shell 解析器src/ShellCheck/Interface.hs公共 API 类型CheckResult、PositionedComment等src/ShellCheck/Debug.hs开发辅助stringToAst、shellcheckString等其中 Interface.hs 定义的数据结构是理解各阶段数据流的钥匙CheckSpec输入规格脚本内容、shell 方言、排除/包含的警告等、CheckResult输出结果、Comment与PositionedComment带位置的诊断注释被各 formatter 消费。新增一条检查项的标准流程Adding a check一节是给贡献者的核心操作手册下面结合源码展开说明。检查的两种形态绝大多数检查都定义在 Analytics.hs 中且只有两种形态Node checks节点检查——对 AST 的每个节点运行追加到nodeChecks列表。例如checkPipePitfalls、checkUnquotedDollarAt这类逐点扫描式的检查。Tree checks树检查——只在根节点运行一次追加到treeChecks列表。例如checkUnusedAssignments、checkUnassignedReferences这类需要跨整个脚本收集信息的检查。当检查器需要多次遍历整棵树时也可以写成树检查。从 Analytics.hs 的checker可以看到mkChecker会把treeChecks与所有启用/可选的检查合并在perScript中一次性应用到 AST 根节点。检查项的函数签名检查是纯函数签名为Parameters - Token - Writer [TokenComment] ()即输入解析参数与 AST 节点通过 Writer monad 追加诊断注释。要输出诊断使用 AnalyzerLib.hs 提供的四个辅助函数warn id code str -- WarningC 级别 err id code str -- ErrorC 级别 info id code str -- InfoC 级别 style id code str -- StyleC 级别它们底层都调用makeComment把给定的IdToken 节点 ID、Code如SC2155和消息文本包装成TokenComment。选用哪个级别决定了默认-S/--severity阈值下该警告是否可见默认最小级别为style见 shellcheck.hs。配套单元测试prop_ 约定每条检查项上方都必须配prop_开头的单元测试正反两个方向各覆盖一次prop_checkFoo1 verify checkFoo bad shell code prop_checkFoo2 verifyNot checkFoo good shell codecabal test会自动发现并运行所有prop_函数这也是 Analytics.hs 中Test.QuickCheck.All.forAllProperties的作用——把每个prop_当作一个 QuickCheck 属性批量执行。提交前必须保证cabal test全绿。检查的归类放置与具体命令强相关的检查如cat、grep、find的使用模式放在 Checks/Commands.hs这类检查按命令名分派与 shell 方言强相关的检查如sh与bash语法差异放在 Checks/ShellSupport.hs按方言分派其余通用检查直接进 Analytics.hs 的nodeChecks/treeChecks。AST 编码约定只用糖衣模式别名ShellCheck 的 AST 存在两套表示方式文档明确要求检查项代码中一律使用糖衣sugared模式别名T_Literal id str -- 字面量 T_IoFile id op filename -- 文件重定向而绝不要直接写脱糖后的内部类例如OuterToken (Id id) (Inner_T_Literal str)后者是 GHC 的内部表示一旦出现在检查项代码中既难以阅读也极易出错。这套别名的定义位置在 AST.hs 中配合 ASTLib.hs 的辅助函数如getLiteralString可以写出简洁且稳健的模式匹配。开发规范速查.claude/CLAUDE.md的 Guidelines 总结了提交前必须遵守的检查清单新增和修改的检查项都要配单元测试且正反用例都要覆盖改动保持聚焦避免为传递新数据而做大规模重构要考虑命令的等价形式例如echo foo bar与echo bar foo语义相同检查不能漏掉其中一种始终确认cabal test干净通过通过cabal run shellcheck - bad code或./quickrun做端到端验证确认警告确实按预期触发。端到端验证之所以重要是因为单元测试只验证检查函数本身而真实场景还涉及 shell 方言识别、.shellcheckrc配置、-e/-i过滤与 formatter 渲染等整条链路。例如 shellcheck.hs 中注册了-s/--shell方言、-S/--severity最小级别、-i/--include、-e/--exclude、-o/--enable、-f/--format、-x/--external-sources、--norc、--rcfile、-P/--source-path、--extended-analysis、--list-optional、--files-from等选项其中-e/-i/-o支持逗号分隔并可重复出现、parseNum还兼容SC前缀shellcheck.hs。这些都会影响检查最终是否被触发值得在提交前用真实脚本跑一遍。另外主程序用不同的退出码区分失败原因shellcheck.hs0无问题、1存在警告/错误、2运行时异常、3语法错误如非法参数、4不支持的功能如未知格式名。在 CI 或脚本中集成时可以据此精确判断失败类别。总结从.claude/CLAUDE.md出发结合仓库源码可以看到 ShellCheck 是一个结构清晰、易于扩展的静态分析器cabal工具链负责编译与测试quickrun/quicktest提供免编译的快速迭代通道nextnumber管理警告编号资源核心代码严格遵循「解析 → AST 分析 → 格式化输出」的三阶段流水线新增检查项只需在Analytics.hs或Checks/下按 node/tree 两种形态注册一个纯函数并配齐prop_测试再遵循糖衣 AST 别名等编码约定即可。掌握这套流程后无论是修复误报、增强现有检查还是提交全新的 SC 编号警告都可以在既有架构内高效完成。【免费下载链接】shellcheckShellCheck, a static analysis tool for shell scripts项目地址: https://gitcode.com/gh_mirrors/sh/shellcheck创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考