How the supportedGuidelines Function Filters Guidelines by Go Version

The supportedGuidelines function filters guidelines by comparing the target Go version against each guideline's sinceVersion field using goversion.Compare, retaining only guidelines where sinceVersion is less than or equal to the target version.

The JetBrains/go-modern-guidelines repository provides a CLI tool to discover modern Go language features available in specific versions. At its core, the supportedGuidelines function in internal/guidelines/guidelines.go implements the version-based filtering logic that determines which recommendations are applicable to your codebase.

How Version Filtering Works

The filtering process involves three distinct stages: loading the guideline data, resolving the target Go version, and performing semantic version comparisons.

Loading Guidelines from Embedded JSON

At program initialization, the repository parses an embedded JSON file (internal/guidelines/guidelines.json) into a slice of modernGoGuideline structs stored in the modernGoGuidelines variable. Each struct contains metadata including a sinceVersion field indicating when the feature became available.

Resolving and Comparing Go Versions

Before filtering begins, the CLI resolves the target version string. The internal/goversion package handles this through two key functions:

• Resolve – Determines the version from CLI flags (--go-version), environment variables, or the local toolchain (lines 18-27 in internal/goversion/goversion.go).
• Compare – Parses version strings into major/minor integers and returns a signed integer indicating relative ordering (lines 37-48 in internal/goversion/goversion.go).

As implemented in internal/goversion/goversion.go, the Compare function returns a value greater than zero if the first version is newer than the second, less than zero if older, and zero if equal.

The supportedGuidelines Implementation

The supportedGuidelines function iterates over the loaded guidelines and applies the version constraint. Located at lines 61-68 in internal/guidelines/guidelines.go, the implementation uses goversion.Compare to check if the target version is greater than or equal to the guideline's sinceVersion:

func supportedGuidelines(targetGoVersion string) []modernGoGuideline {
    var guidelines []modernGoGuideline
    for _, guideline := range modernGoGuidelines {
        if goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0 {
            guidelines = append(guidelines, guideline)
        }
    }
    return guidelines
}

The logic goversion.Compare(targetGoVersion, guideline.sinceVersion) >= 0 effectively means: "Keep this guideline if it was introduced in the target version or earlier."

Practical Usage Examples

While supportedGuidelines is an internal helper, higher-level functions like ListText expose this filtering capability to users programmatically and via the CLI.

Command Line Interface

The CLI entry point in internal/cli/cli.go wires version resolution to the filtering logic. To see guidelines for a specific version:

go-modern-guidelines list --go-version=1.25

This command prints all guidelines valid for Go 1.25 and earlier, excluding features introduced in Go 1.26+.

Programmatic Access

You can invoke the exported helpers from Go code to retrieve filtered results:

package main

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

func main() {
    // List guidelines supported by Go 1.27
    output := guidelines.ListText("1.27")
    fmt.Println(output)
}

The ListText function internally calls supportedGuidelines and formats the results into human-readable text, displaying only guidelines where the JSON "since_version" field is less than or equal to 1.27.

Summary

• Data Source: Guidelines load from internal/guidelines/guidelines.json into modernGoGuideline structs at startup.
• Version Resolution: The internal/goversion package parses and compares semantic versions via Resolve and Compare.
• Filter Logic: supportedGuidelines in internal/guidelines/guidelines.go (lines 61-68) retains guidelines where sinceVersion ≤ target version using goversion.Compare(target, since) >= 0.
• Public API: ListText provides the primary interface for accessing filtered guidelines programmatically or via CLI.

Frequently Asked Questions

How does supportedGuidelines handle invalid version strings?

The goversion.Compare function in internal/goversion/goversion.go parses version strings into numeric major and minor components. While the function expects valid semantic versions (e.g., "1.22", "1.23.4"), the comparison logic focuses on the numeric values to ensure accurate filtering regardless of patch levels.

Can I use supportedGuidelines directly in my own code?

No, supportedGuidelines is unexported (lowercase) and intended for internal use within the internal/guidelines package. Use the exported function ListText to retrieve filtered guidelines, or import the internal/goversion package directly if you only need version comparison logic for your own filtering.

What happens if I don't specify a Go version in the CLI?

According to the source code in internal/cli/cli.go and internal/goversion/goversion.go, the tool resolves the version from the local Go toolchain when no --go-version flag is provided. This ensures you see guidelines compatible with your current development environment by default.

Where are the guideline definitions stored?

Guideline definitions reside in internal/guidelines/guidelines.json and are embedded into the binary at build time. Each entry includes fields like id, description, and since_version, which supportedGuidelines uses to determine applicability against your target Go version.

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