用途:glint 是 Gram 的自定义 go/analysis 分析器包,gcl 是将其作为插件加载的 golangci-lint 自定义构建配置,二者共同在本地自动化执行项目编码约定与防错规则,减少在代码评审中反复讨论同类问题。
主要能力与结构:插件入口为 glint/plugin.go,通过 register.Plugin("glint", New) 注册,定义 settings/ruleSettings,并在 BuildAnalyzers 中列出所有分析器;BuildAnalyzers 是当前规则集合的事实来源。gcl 的接线在 server/.custom-gcl.yml,将 github.com/speakeasy-api/gram/glint 声明为导入的插件模块。
新增分析器的要点:选择 kebab-case 规则键与对应 snake_case.go 文件名;定义仅含 Disabled bool 的 <rule>Settings;实现 new<Rule>Analyzer(rule <rule>Settings) *analysis.Analyzer;检测优先用类型而非 AST 形状,AST 形状优先于字符串匹配;诊断信息用祈使语气并用 %q 内联违规标识符;在 plugin.go 中接线并加入 BuildAnalyzers;用 analysistest.Run 与新 fixture 编写 <rule>_test.go,同时更新 disabledAllRulesPlugin() 和 plugin_test.go 中的计数。
检测与遍历:通过 pass.TypesInfo 做类型判断;需要全树遍历时依赖 inspect.Analyzer 并用 Preorder。回调无返回值,无法像 ast.Inspect 那样剪枝;Preorder 跨文件遍历,需要按文件过滤时用 pass.Fset.File(n.Pos()).Name()。从 pass.ResultOf 取 inspector 前必须声明依赖,否则结果为 nil 会 panic。若规则需按文件维护状态或只关心包级声明,仍应手写 ast.Inspect 并注释原因。字符串匹配仅在信号确实存在于源码文本时使用。
配置与忽略:每个分析器仅接受 Disabled bool,不添加 allowlist 字段;用户通过 //nolint:glint 或 //nolint:glint:<rule-key> 退出。目前仅 no-anonymous-defer、enforce-o11y-conventions 额外提供 Message 字符串追加到默认诊断。所有分析器应设置 Doc 字段,与默认消息常量保持一致。
建议修复:当修复机械且安全时,附加 SuggestedFixes 以支持编辑器快速修复和 golangci-lint --fix。每条 TextEdit 仅作用于一个文件,End 不得早于 Pos;同一诊断的编辑不得重叠;替换文本用 go/format.Node 生成以保证 gofmt 干净;涉及跨出现位置的编辑应附加到每条诊断上。共享编辑逻辑放入 glint/ 下的公共子包(如 glint/imports/)。测试修复用 analysistest.RunWithSuggestedFixes 并与 .go.golden 比较。命名需保持规则键、Go 标识符与文件名三者一致。
限制:资料未提供 glint 的安装命令、平台支持、收费或价格信息,也未说明其独立于 Gram 项目的使用方式;相关事实暂未提供。