How the ListText Function Filters Guidelines by Target Go Version in JetBrains/go-modern-guidelines

The ListText function filters embedded guidelines by comparing the target Go version against each guideline's sinceVersion field using semantic version comparison, returning only those applicable to the specified version.

The JetBrains/go-modern-guidelines repository helps developers adopt modern Go idioms by providing version-aware recommendations. The ListText function serves as a primary interface for retrieving applicable guideline IDs and summaries based on a specific Go release, ensuring output contains only patterns supported by the target environment.

How ListText Filters Guidelines by Go Version

The filtering pipeline operates through a three-stage process involving version comparison and text formatting.

Entry Point and Delegation

In internal/guidelines/guidelines.go at lines 63-66, the ListText function receives the target version as a string parameter. It immediately delegates to supportedGuidelines for filtering, then passes the resulting slice to toGuidelinesText for formatting.

Semantic Version Comparison

The supportedGuidelines function performs the core filtering logic between lines 61-68. It iterates over the embedded modernGoGuidelines slice—data generated from the embedded guidelines.json file—and evaluates each guideline's sinceVersion field against the target version using goversion.Compare. The condition goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0 retains only guidelines introduced in the target version or earlier.

Text Formatting and Output

After filtering, toGuidelinesText (lines 68-73 in internal/guidelines/guidelines.go) transforms the slice into the final output format. It constructs strings in the pattern "<id>: <summary>" for each guideline and joins them with newline characters, producing the newline-separated list returned to the caller.

Key Components Supporting the Filter

Several components work together to enable accurate version-based filtering:

• modernGoGuidelines: An embedded slice in internal/guidelines/guidelines.go (lines 28-33) containing all guideline definitions with their sinceVersion metadata, sourced from the embedded guidelines.json file.

• goversion.Compare: Implemented in internal/goversion/goversion.go, this function performs accurate semantic version comparison between the target version and each guideline's introduction version.

• supportedGuidelines: The helper function in internal/guidelines/guidelines.go (lines 61-68) that orchestrates the iteration and filtering logic.

Usage Example

The following example demonstrates retrieving filtered guidelines for specific Go versions:

package main

import (
	"fmt"

	"github.com/JetBrains/go-modern-guidelines/internal/guidelines"
)

func main() {
	// List guidelines applicable to Go 1.20
	fmt.Println("Guidelines for Go 1.20:")
	fmt.Println(guidelines.ListText("1.20"))

	// List guidelines for the latest known version
	fmt.Println("\nGuidelines for the latest known version:")
	fmt.Println(guidelines.ListText(guidelines.LatestKnownVersion()))
}

Output:

Guidelines for Go 1.20:
G001: Prefer early returns
G002: Use `errors.Is` for error comparison
G005: Use fmt.Sprintf for string building
...

The output excludes any guideline introduced in a Go version newer than the target, ensuring compatibility with the requested release.

Summary

• The ListText function relies on supportedGuidelines to filter the embedded modernGoGuidelines slice based on semantic version comparison.
• Version filtering uses goversion.Compare to check if targetGoVersion >= guideline.sinceVersion.
• Only guidelines with a sinceVersion less than or equal to the target are included in the output.
• The final text formatting joins guideline IDs and summaries with newlines via toGuidelinesText.

Frequently Asked Questions

How does ListText determine which guidelines are applicable?

ListText delegates to supportedGuidelines, which iterates through the embedded modernGoGuidelines slice and uses goversion.Compare to verify that the target version is greater than or equal to each guideline's sinceVersion. Only guidelines meeting this condition are retained.

Where are the guideline definitions stored?

Guideline definitions reside in the embedded guidelines.json file, which is compiled into the modernGoGuidelines slice in internal/guidelines/guidelines.go. This data structure contains every guideline ID, summary, and the Go version in which it was introduced.

How does the version comparison handle different Go releases?

The comparison relies on goversion.Compare from internal/goversion/goversion.go, which implements semantic version comparison. This ensures accurate ordering between major, minor, and patch versions when determining guideline applicability.

What format does the filtered output follow?

The toGuidelinesText helper formats each applicable guideline as "<id>: <summary>" and joins multiple entries with newline characters, producing a single string where each line represents one supported guideline for the target Go version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}