Glint

glint is Gram's package of custom go/analysis analyzers, and gcl is the golangci-lint custom-build configuration that loads glint as a plugin. Together they automate enforcement of project coding conventions and bug-prevention rules so the same feedback isn't re-litigated in PR review.

• Plugin entry point: glint/plugin.go — registers the plugin via register.Plugin("glint", New), defines the settings/ruleSettings structs, and lists every analyzer in BuildAnalyzers.
• Second plugin: glint/nolint_plugin.go registers glintnolint, which polices //nolint:glint directives. It is a separate linter name because a //nolint:glint directive would otherwise suppress the diagnostic that reports it. It is enabled in server/.golangci.yaml next to glint, and derives the valid analyzer names from BuildAnalyzers, so new analyzers need no extra wiring there.
• gcl wiring: server/.custom-gcl.yml — declares github.com/speakeasy-api/gram/glint as the imported plugin module for the custom golangci-lint binary. Its version must match the golangci-lint pinned in mise.toml; mise run lint:server refuses to run otherwise.
• glint is its own Go module (glint/go.mod), separate from the root module, so that the custom build only depends on golang.org/x/tools and plugin-module-register at the versions golangci-lint itself uses, and so that server dependency bumps never rebuild gcl. Keep it that way: never import a root-module package from glint. The one shared type, the annotations.Service marker embedded by services, lives in the root module at server/internal/annotations and analyzers match it by import path.
• Tests run with mise run test:glint (CI runs them in the glint-test job).

The current set of analyzers and their rule keys is the source of truth in BuildAnalyzers. Read that function before adding a new one.

Quick start

When adding a new analyzer:

1. Pick a kebab-case rule key and a matching snake_case.go file name in glint/. See Naming conventions.
2. Define <rule>Settings with Disabled bool. Add nothing else unless there's a concrete user-facing reason. See Settings and ignore mechanisms.
3. Implement detection in new<Rule>Analyzer(rule <rule>Settings) *analysis.Analyzer. Prefer type-based checks over AST shape, and AST shape over string matching. See Detection methodology.
4. Write the diagnostic with imperative tone and the offending identifier inlined via %q. See Diagnostic message style.
5. Wire the rule into glint/plugin.go: add a ruleSettings field with the kebab-case JSON tag, then an if !p.settings.Rules.<X>.Disabled block in BuildAnalyzers.
6. Add <rule>_test.go with analysistest.Run(...) and a fixture under glint/testdata/src/<fixture>/. Update disabledAllRulesPlugin() and the count in TestBuildAnalyzersAllEnabled in glint/plugin_test.go. See Testing.

Detection methodology

Strongly prefer type-based detection over AST-shape matching, and AST-shape matching over source-string matching. Type-based checks are robust against renames, aliases, vendored packages, and import-path quirks; AST shape is robust against most refactors but blind to type identity; raw string matching is fragile and should only be reached for when the signal genuinely lives in source text rather than the type system.

Prefer types via pass.TypesInfo

glint/no_repo_fields_in_service.go walks struct fields, resolves each field's type via pass.TypesInfo.TypeOf, then narrows through *types.Pointer → *types.Named to identify a sqlc-generated repo handle:

fieldType := pass.TypesInfo.TypeOf(field.Type)
if fieldType == nil {
    continue
}

ptr, ok := fieldType.(*types.Pointer)
if !ok {
    continue
}

named, ok := ptr.Elem().(*types.Named)
if !ok {
    continue
}

if !isSqlcGenerated(pass.Fset, named.Obj(), cache) {
    continue
}

Reach for type assertions on types.Type (*types.Named, *types.Pointer, *types.Slice, *types.Map, *types.Interface); use pass.TypesInfo.Uses[ident] / pass.TypesInfo.Defs[ident] to resolve identifiers to their declared types.Object; inspect method receivers via Recv() when checking method-set rules. The plugin advertises register.LoadModeTypesInfo from GetLoadMode in glint/plugin.go, so type information is guaranteed to be loaded.

AST shape is acceptable when types are not load-bearing

When the rule is fundamentally about the shape of code rather than its types, AST matching is fine. glint/no_anonymous_defer.go walks *ast.DeferStmt and asserts the call target is *ast.FuncLit:

ins := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)

ins.Preorder([]ast.Node{(*ast.DeferStmt)(nil)}, func(node ast.Node) {
    deferStmt := node.(*ast.DeferStmt)

    if _, ok := deferStmt.Call.Fun.(*ast.FuncLit); !ok {
        return
    }

    pass.ReportRangef(deferStmt, "%s", message)
})

There's no *types.Type that captures "anonymous deferred function" — the property only exists at the AST level — so AST matching is the right tool.

Traversal: depend on inspect.Analyzer for deep walks

When a rule needs to find nodes anywhere in the tree (calls, defers, type specs nested in functions, etc.), declare a dependency on the shared inspector rather than hand-rolling for _, file := range pass.Files { ast.Inspect(file, ...) }. inspect.Analyzer parses each file once and shares the resulting *inspector.Inspector across every dependent analyzer, so the package's analyzers walk each file once collectively instead of once per analyzer. Preorder also filters by node type up front, replacing the node.(*ast.T) type-switch-and-return true boilerplate:

import (
    "go/ast"

    "golang.org/x/tools/go/analysis"
    "golang.org/x/tools/go/analysis/passes/inspect"
    "golang.org/x/tools/go/ast/inspector"
)

return &analysis.Analyzer{
    Name:     enforceO11yConventionsAnalyzer,
    Doc:      enforceO11yConventionsDefaultMessage,
    Requires: []*analysis.Analyzer{inspect.Analyzer},
    Run: func(pass *analysis.Pass) (any, error) {
        ins := pass.ResultOf[inspect.Analyzer].(*inspector.Inspector)

        ins.Preorder([]ast.Node{(*ast.CallExpr)(nil)}, func(node ast.Node) {
            callExpr := node.(*ast.CallExpr)
            // ...
        })

        return nil, nil
    },
}

Notes when adopting it:

• The callback returns nothing, so there is no return false to prune a subtree the way ast.Inspect allows. If a rule genuinely depends on pruning descent (matching a node and deliberately skipping its children, for example), keep a manual ast.Inspect and say why in a comment.
• Preorder walks every file in the package with no file boundary, so any per-file scoping has to happen per node instead of around a pass.Files loop. When a rule applies only to certain files, filter inside the callback via pass.Fset.File(n.Pos()).Name(). For example, glint/no_testing_raw_sql.go checks for the _test.go suffix there because the test-only rule no longer has a file loop to gate.
• Pulling the inspector from pass.ResultOf only works if the analyzer declared inspect.Analyzer in its Requires; otherwise the result is nil and the type assertion panics. This bites helpers shared across analyzers, since every caller must carry the dependency. For example, findAnnotatedStructs reads the inspector, so all four analyzers that call it list inspect.Analyzer in their Requires.

Two situations where the manual walk is still the right call, and the inspector earns nothing:

• Per-file stateful detection. When a rule accumulates state across a file and emits fixes scoped to that one *ast.File (an occurrence list, a "is this import used elsewhere" flag, import add/remove SuggestedFixes), the natural unit of work is the file, not the node. The shared inspector deliberately flattens that boundary, so adopting it would force re-bucketing nodes back by file to rebuild the same state, with no traversal saved. Keep the manual per-file ast.Inspect and leave a comment explaining the exemption. For example, glint/no_sql_err_no_rows.go collects each file's ErrNoRows occurrences alongside an otherSqlUsage flag before deciding which imports to rewrite.
• Top-level-declaration scans. When a rule only cares about package-level declarations, iterating file.Decls directly is already a shallow single pass and expresses the intent precisely. Reaching for Preorder on *ast.GenDecl would additionally visit function-local declarations, widening the rule's scope, so the inspector is both unnecessary and subtly wrong here. For example, the audit-* analyzers (e.g. glint/audit_event_urn_naming.go) walk file.Decls to inspect only package-level *ast.GenDecl/*ast.TypeSpec.

Source-string matching is a last resort

Raw strings.Contains / regex over file content is fragile and almost never warranted. The only string-matching helper currently in the package is isSqlcGenerated in glint/no_repo_fields_in_service.go, and only because the "sqlc-generated" signal lives in a generated-file header comment that has no type-system representation:

f, err := parser.ParseFile(token.NewFileSet(), pos.Filename, nil, parser.ParseComments|parser.PackageClauseOnly)
if err == nil && ast.IsGenerated(f) {
    for _, cg := range f.Comments {
        if strings.Contains(cg.Text(), "sqlc") {
            result = true
            break
        }
    }
}

Note the helper caches results by filename, parses with parser.PackageClauseOnly to skip body parsing, and uses ast.IsGenerated to confirm the standard generated-code header before substring-matching. If you find yourself reaching for string matching, justify in a comment why type-based detection won't work — future readers will assume it was a last resort.

Settings and ignore mechanisms

Each analyzer accepts exactly one common setting: Disabled bool. Don't add allowlist fields (Ignored []string, regex includes/excludes, package globs, etc.) — they're a maintenance burden, they obscure the rule's contract, and golangci-lint already understands //nolint directives as the standard opt-out path.

type noRepoFieldsInServiceSettings struct {
    Disabled bool `json:"disabled"`
}

The opt-out for end users is the standard //nolint:glint directive, which golangci-lint applies without any analyzer-side wiring. golangci-lint only knows the linter name, so the directive silences every glint analyzer on that line. glintnolint therefore requires it to sit on the offending line (not above package or a top-level declaration) with an explanation that starts with the suppressed analyzer name: //nolint:glint // notestingrawsql: <why this violation is intentional>.

The only setting-shape exception today is narrow message customization: two analyzers (no-anonymous-defer, enforce-o11y-conventions) expose a Message string that gets appended to the default diagnostic when set. From glint/no_anonymous_defer.go:

type noAnonymousDeferSettings struct {
    Disabled bool   `json:"disabled"`
    Message  string `json:"message"`
}

message := noAnonymousDeferDefaultMessage
if rule.Message != "" {
    message += ": " + rule.Message
}

Add a Message field only if there's a concrete reason for end-user customization. Anything more elaborate than a single appended-suffix string warrants a discussion before being added.

Diagnostic message style

Diagnostics tell the reader what to do, not just what's wrong. Imperative present-tense, action-oriented, with the offending identifier inlined where it aids resolution. No trailing punctuation, no leading capital, match the tone of the existing analyzers.

<bad-example>

pass.ReportRangef(field, "Repo field detected in service struct.")

Past-tense observation, capitalized, trailing period — describes the symptom but doesn't tell the reader what to change.

</bad-example>

<good-example>

pass.ReportRangef(field, "field %q in %s has type %s which is sqlc-generated; services should use *pgxpool.Pool and create repo instances in methods",
    field.Names[0].Name, s.name, fieldType)

(from glint/no_repo_fields_in_service.go)

Names the offending field with %q, explains why it's wrong, and tells the reader what shape the code should take instead.

</good-example>

<good-example>

pass.ReportRangef(deferStmt, "%s", message) // message = "avoid anonymous deferred functions"

(from glint/no_anonymous_defer.go)

Imperative ("avoid"), short, no trailing punctuation.

</good-example>

When the diagnostic has a mechanical fix, attach a SuggestedFix so editor quick-fix actions and golangci-lint --fix can apply it. See Suggested fixes.