Go Module Review: golangci-lint

[github-actions[bot]]

🐹 Go Fan Report: golangci-lint/v2

Module Overview

golangci-lint is the industry-standard fast linters runner for Go. It runs linters in parallel, uses intelligent caching, supports YAML configuration, integrates with all major IDEs, and includes over 100 linters. With 18,207 GitHub stars and extremely active development (last updated today!), it's the de-facto choice for Go code quality enforcement.

Version: v2.7.2 (latest) - Released December 7, 2025
Repository: https://github.com/golangci/golangci-lint

Current Usage in gh-aw

Integration Architecture ⚙️

gh-aw demonstrates textbook-perfect integration of golangci-lint across multiple touchpoints:

1. Version Pinning (tools.go):

   _ "github.com/golangci/golangci-lint/v2/cmd/golangci-lint"

   • Ensures consistent versions across dev and CI
   • Follows official Go tools best practices

2. Configuration (.golangci.yml):

   • Uses v2 format with explicit version: "2" field
   • 6 carefully selected linters enabled
   • 40+ thoughtful exclusion rules
   • 4 preset exclusion groups
   • Formatters configured (gofmt, goimports)

3. Makefile Targets:

   • make golint: Full repository scan
   • make golint-incremental BASE_REF=(ref): Incremental linting (50-75% faster)

4. CI Workflow (.github/workflows/ci.yml):

   # Smart conditional linting:
   # - Pull Requests: Incremental (--new-from-rev)
   # - Main Branch: Full scan

Linters Enabled (6 Total) 🔍

Linter	Purpose	Notes
misspell	Spelling errors	Catches typos in comments/strings
revive	Code style	Fast, configurable, extensible
modernize	Modern Go patterns	NEW in v2.6.0
gocritic	Opinionated checks	Comprehensive analysis
gosec	Security	Vulnerability detection
unconvert	Type conversions	Removes unnecessary casts

Performance Optimization 🚀

Incremental Linting Strategy:

• On PRs: Only checks changed files with --new-from-rev
• Result: 50-75% faster CI runs on typical PRs
• On Main: Full repository scan for comprehensive coverage

This is an industry best practice that gh-aw implements perfectly!

Configuration Highlights ✨

Smart Exclusions Strategy:

• errcheck: Allows unchecked errors in test files (practical)
• gosec: 20+ file-specific security exceptions for controlled contexts
  • Example: Allows exec.Command in gateway.go, actionlint.go (legitimate use cases)
  • Example: Allows file permissions 0644/0755 where appropriate
• gocritic: Disables overly pedantic checks
  • ifElseChain: else-if chains are often clearer than switches
  • singleCaseSwitch: Single case switches can be intentional
• modernize: Maintains Go 1.20+ compatibility
  • Excludes min/max builtins (Go 1.21+)
  • Excludes slices.Contains (Go 1.21+)
  • Excludes strings.Cut* (Go 1.20+)

Why this matters: These exclusions show thoughtful engineering rather than blindly following linter rules. The project balances code quality with practical concerns like backward compatibility and intentional patterns.

Research Findings

Repository Activity 📊

• Stars: 18,207 ⭐
• Forks: 1,529
• Open Issues: 115
• License: AGPL-3.0 (the linter tool itself; individual linters have various licenses)
• Documentation: (redacted) (excellent docs!)
• Last Updated: 2025-12-26 (TODAY! 🔥)

Recent Updates 🆕

v2.7.2 (2025-12-07) - Current Version

Bug Fixes:

• gosec: Updated to daccba6b93d7 with security scanner improvements

v2.7.0 (2025-12-03)

New Revive Rules:

1. forbidden-call-in-wg-go: Prevents dangerous patterns in WaitGroup goroutines
2. unnecessary-if: Simplifies conditional logic
3. inefficient-map-lookup: Optimizes map access patterns

New Modernize Analyzers:

• plusbuild: Checks build constraints
• stringscut: String cutting patterns

v2 Major Release (2025-03-24)

Game-Changing Features:

• 🌟 New golangci-lint fmt command with dedicated formatter configuration
• ♻️ golangci-lint migrate command for v1→v2 migration
• Merged linters: staticcheck, stylecheck, gosimple unified
• Better defaults: No exclusions by default (more strict)
• Performance: New --fast-only flag for quick checks

Best Practices from Maintainers ✅

golangci-lint documentation recommends:

1. ✅ Use version field - gh-aw: YES
2. ✅ Start with few linters - gh-aw: 6 linters (excellent balance)
3. ✅ Use presets for exclusions - gh-aw: 4 presets
4. ✅ Incremental linting on PRs - gh-aw: Perfectly implemented
5. ✅ Pin tool version - gh-aw: Uses tools.go pattern

Assessment: gh-aw follows ALL major best practices! 🎉

Improvement Opportunities

⭐ Quick Wins

1. Document Incremental Linting Strategy

Current: Implemented in CI but not documented for developers
Action: Add section to DEVGUIDE.md:

## Local Incremental Linting

Speed up linting by only checking changed files:

# Lint changes since origin/main
make golint-incremental BASE_REF=origin/main

# This is what CI uses on PRs - 50-75% faster!

Benefit: Helps contributors adopt the faster workflow

2. Add Comments for Recent Features

Current: Using v2.7.2 features but not documenting them
Action: Add comments in .golangci.yml:

linters:
  enable:
    - revive  # v2.7.0: Now includes forbidden-call-in-wg-go, unnecessary-if
    - modernize  # v2.6.0: Modern Go patterns (plusbuild, stringscut)

Benefit: Better team awareness of available checks

3. Evaluate New Revive Rules (v2.7.0)

Available but not explicitly configured:

• forbidden-call-in-wg-go: Prevents WaitGroup anti-patterns
• unnecessary-if: Simplifies logic
• inefficient-map-lookup: Performance optimization

Action: Test these rules on the codebase:

# Try them out
golangci-lint run --enable-only=revive --config=(test-config)

✨ Feature Opportunities

1. Adopt golangci-lint fmt Command (v2.0.0+)

Current: Using separate gofmt and goimports via Makefile
Opportunity: Consolidate with golangci-lint fmt

Benefits:

• Single tool for linting AND formatting
• Better caching and performance
• Consistent configuration in .golangci.yml

You already have the formatters section configured!

formatters:
  enable:
    - gofmt
    - goimports

Migration path:

# Try it:
golangci-lint fmt

# In Makefile:
fmt-go:
	golangci-lint fmt

2. Add JSON Output for Trending Analysis

Feature: golangci-lint run --out-format=json
Use Case: Track code quality metrics over time
Example:

# Save results
golangci-lint run --out-format=json > lint-results.json

# Analyze trends
jq '.Issues | length' lint-results.json

3. Cache Optimization

Current: Using Go cache from setup-go action
Enhancement: golangci-lint has its own cache (~/.cache/golangci-lint)

Action: Add to CI workflow:

- name: Cache golangci-lint
  uses: actions/cache@v4
  with:
    path: ~/.cache/golangci-lint
    key: golangci-lint-${{ runner.os }}-${{ hashFiles('**/go.sum') }}

Benefit: Even faster subsequent CI runs

4. Audit Exclusions with warn-unused

Feature: linters.exclusions.warn-unused: true (v2.0.0)
Benefit: Identifies stale exclusion rules
Current: 40+ exclusion rules - some may be outdated

Action: Enable temporarily:

linters:
  exclusions:
    warn-unused: true  # Audit mode

📐 Best Practice Alignment

What's Already Perfect ✅:

• ✅ Version field (version: "2")
• ✅ Incremental linting on PRs
• ✅ tools.go version pinning
• ✅ Conservative linter selection (6 linters - quality over quantity)
• ✅ Comprehensive exclusion rules with clear comments
• ✅ CI integration strategy (incremental on PRs, full on main)
• ✅ Formatters configured
• ✅ Test file handling

Rating: ⭐⭐⭐⭐⭐ (5/5) - Exemplary implementation!

Recommendations

Priority 1: No Action Needed! ✨

The current implementation is exemplary. This is a textbook example of how to integrate golangci-lint.

Priority 2: Nice-to-Haves (Consider within 1-2 months)

1. Document incremental linting in DEVGUIDE.md
2. Evaluate new revive rules from v2.7.0
3. Audit exclusion rules with warn-unused option
4. Try golangci-lint fmt to consolidate formatting

Priority 3: Future Enhancements (Optional)

1. Optimize CI cache for golangci-lint
2. Add JSON output for quality trending
3. Explore staticcheck quickfix rules

Things to Keep As-Is ✅

• Current version (v2.7.2 is latest)
• Incremental linting strategy
• Linter selection (6 is a good balance)
• Exclusion rules (thoughtful and well-commented)
• CI integration pattern
• tools.go pinning approach

Key Metrics

Metric	Value	Assessment
Version Currency	Latest (v2.7.2)	✅ Perfect
Configuration	v2 format	✅ Perfect
CI Performance	50-75% faster on PRs	✅ Excellent
Linter Count	6 enabled	✅ Well-balanced
Exclusion Strategy	40+ rules, 4 presets	✅ Thoughtful
Best Practices	All followed	✅ Exemplary
Repository Activity	Updated today	✅ Very active

Next Steps

For the Team 👥

1. Continue the current excellent practices
2. Read the detailed summary at specs/mods/golangci-lint.md
3. Consider documenting incremental linting for new contributors
4. Stay updated - golangci-lint releases frequently (watch for v2.8.0)

For Developers 💻

# Use incremental linting locally for speed:
make golint-incremental BASE_REF=origin/main

# Try new features:
golangci-lint fmt  # Formatting
golangci-lint run --out-format=json  # JSON output

For CI/CD 🤖

Current CI strategy is perfect - no changes needed!

Conclusion

This review finds gh-aw's golangci-lint integration to be exemplary - a model implementation that other projects should emulate. The combination of:

• ✅ Latest version usage
• ✅ Perfect v2 configuration
• ✅ Industry-leading incremental linting
• ✅ Smart CI integration
• ✅ Thoughtful exclusion strategy
• ✅ Version pinning discipline

...makes this a 5-star implementation with no critical improvements needed.

Well done! 🎉 This is exactly how golangci-lint should be integrated into a professional Go project.

---

Generated by Go Fan 🐹
Module summary saved to: specs/mods/golangci-lint.md
Last reviewed: 2025-12-26
Repository activity: Updated today (2025-12-26)

AI generated by Go Fan

[pelikhan]

/plan

[github-actions[bot]]

🎉 Yo ho ho! Plan Command found the treasure and completed successfully! ⚓💰

[github-actions[bot]]

Plan Created ✅

I've analyzed the Go Fan review and created a structured improvement plan:

Parent Tracking Issue: Created to track all golangci-lint enhancements

Sub-Issues Created (5):

1. Document incremental linting strategy - Help developers use the faster local workflow
2. Add configuration comments - Document v2.6.0 and v2.7.0 features in config
3. Evaluate new revive rules - Test v2.7.0 rules for additional value
4. Migrate to golangci-lint fmt - Consolidate formatting under single tool
5. Audit exclusion rules - Clean up stale exclusions with warn-unused

Summary

The Go Fan report confirmed our golangci-lint integration is exemplary (5/5 rating). The sub-issues address nice-to-have improvements to make an already excellent setup even better.

All tasks are well-scoped, actionable, and prioritized as enhancements rather than critical fixes.

AI generated by Plan Command for discussion #7808