luthersystems/elps / .claude/skills/add-linter-check
add-linter-check
Verified/add-linter-check — New Lint Analyzer Skill
Adds a new static analysis check to the ELPS linter (lint/, run by elps lint, the LSP, and CI). This is a prescriptive workflow touching three Go files plus docs/lint-checks.md.
For Go-side invariants over elps's own source, use /elpsvet instead.
Trigger
Use when asked to add a new lint check or analyzer for ELPS source, when a new builtin/op/macro has structural requirements (see /implement), or when a behavior change needs a static migration diagnostic.
Workflow
1. Design the Check
Before writing code, answer:
- What pattern does this check detect? (name it with kebab-case, e.g.,
unused-import) - Is it a simple per-expression check (use
WalkSExprs) or context-sensitive (use custom walker)? - What's the diagnostic message? Keep it concise and actionable.
- What are the false positive risks? Plan mitigations.
2. File 1: lint/analyzers.go — Define the Analyzer
Add a new exported variable following this pattern:
var AnalyzerMyCheck = &Analyzer{
Name: "my-check",
Doc: "Check that ... (one-line description used by --list)",
Run: func(pass *Pass) error {
WalkSExprs(pass.Exprs, func(sexpr *lisp.LVal, depth int) {
head := HeadSymbol(sexpr)
if head != "target-form" {
return
}
// Check logic here
argc := ArgCount(sexpr)
if argc < 2 {
src := SourceOf(sexpr)
pass.Report(Diagnostic{
Message: "descriptive error message",
Pos: posFromSource(src.Source),
})
}
})
return nil
},
}
Available helpers:
WalkSExprs(exprs, fn)— Walk all s-expressions, calls fn with each sexpr and depthWalk(exprs, fn)— Walk ALL nodes (not just s-expressions)HeadSymbol(sexpr)— Get the operator name (e.g.,"if","defun")ArgCount(sexpr)— Count arguments (excludes the operator)SourceOf(v)— Get source location, falling back to first child if neededposFromSource(loc)— Convert*token.LocationtoPositionpass.Report(diag)— Report a diagnosticpass.Reportf(source, format, args...)— Printf-style diagnostic
For checks that need scope/symbol resolution, set Semantic: true on the Analyzer and read pass.Semantics (nil-check it and return early; tests use lintCheckSemantic).
For context-sensitive checks (e.g., checking nesting), write a custom recursive walker with depth/context tracking — walkRethrowContext in lint/analyzers.go is the reference example:
Run: func(pass *Pass) error {
for _, expr := range pass.Exprs {
walkMyCheck(pass, expr, false)
}
return nil
},
// ...
func walkMyCheck(pass *Pass, v *lisp.LVal, insideTarget bool) {
// Custom traversal with context tracking
}
Do not add a ; nolint:analyzer-name note yourself — the CLI renderer
(cmd/diagnostic.go) appends a suppression hint to every diagnostic
automatically, and a hand-written note renders as a duplicate. Use Notes for
check-specific context (e.g. "first defined at ...").
3. File 2: lint/lint.go — Register in DefaultAnalyzers()
Add the new analyzer to the DefaultAnalyzers() return slice:
func DefaultAnalyzers() []*Analyzer {
return []*Analyzer{
// ... existing analyzers ...
AnalyzerMyCheck,
}
}
4. File 3: lint/lint_test.go — Write Tests
Write at minimum three test categories:
// Positive case: should trigger diagnostic
func TestMyCheck_Positive(t *testing.T) {
diags := lintCheck(t, AnalyzerMyCheck, `(bad-pattern arg)`)
assert.Len(t, diags, 1)
assertHasDiag(t, diags, "descriptive error")
assertDiagOnLine(t, diags, 1, "descriptive error")
}
// Negative case: should NOT trigger diagnostic
func TestMyCheck_Negative(t *testing.T) {
diags := lintCheck(t, AnalyzerMyCheck, `(good-pattern arg1 arg2)`)
assertNoDiags(t, diags)
}
// Nolint suppression: diagnostic should be suppressed
func TestMyCheck_Nolint(t *testing.T) {
diags := lintCheck(t, AnalyzerMyCheck,
`(bad-pattern arg) ; nolint:my-check`)
assertNoDiags(t, diags)
}
Update TestDefaultAnalyzers — increment the expected count in assert.Len and add the name to the expected name list.
Test helpers available:
lintCheck(t, analyzer, source) []Diagnostic— Run single analyzer on sourceassertHasDiag(t, diags, substr)— Assert at least one diagnostic contains substrassertNoDiags(t, diags)— Assert no diagnosticsassertDiagOnLine(t, diags, line, substr)— Assert diagnostic on specific line
5. Document it: docs/lint-checks.md
Add a ### \my-check`section under "Checks" with what it flags, a bad and a good example, and how to suppress it. The LSP links every diagnostic todocs/lint-checks.md# (lsp/diagnostics.go`), so a missing section
is a dead link in editors.
6. Verify
go test ./lint/... # Linter tests pass
go build -o elps . && ./elps lint --workspace=. --exclude 'grammar' --include '_examples' ./... # as CI runs it
Then the full /verify pipeline. A new check — or a fix that stops an
existing analyzer skipping nodes — often surfaces true positives in the repo's
own .lisp files (e.g. lisp/lisplib/libjson/*_test.lisp). Fix those in the
same PR; do not suppress them.
False Positive Mitigations
Common patterns that cause false positives:
- User-defined functions shadowing builtins: Pre-scan for
defun/defmacrothat shadow the target name - Macro template bodies: Forms inside quasiquote templates aren't real calls
- Formals lists: Parameter lists look like function calls but aren't — use
aritySkipNodes()pattern - Threading macros:
thread-first/thread-lastchildren get an extra arg at expansion time
Checklist
- Analyzer defined in
lint/analyzers.gowith Name, Doc, Run - No hand-written
; nolint:note (the CLI appends the hint automatically) - Registered in
DefaultAnalyzers()inlint/lint.go - Positive, negative, and nolint tests in
lint/lint_test.go -
TestDefaultAnalyzerscount updated - Section added to
docs/lint-checks.md - No false positives on existing codebase (CI's
elps lintcommand above) -
make testpasses
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |