Supported Guideline IDs and Their Normalization in the JetBrains Go Modern Guidelines CLI

The JetBrains go-modern-guidelines CLI references IDs from an embedded guidelines.json file (such as G001, G002) and normalizes user input through the normalizeGuidelineIDs helper to trim whitespace, filter empty strings, and remove duplicates while maintaining the original order.

The go-modern-guidelines CLI by JetBrains provides structured recommendations for modern Go development through specific guideline identifiers. When developers query these guidelines using the explain command, the tool processes raw user input into a clean, valid set of supported guideline IDs through a specific normalization pipeline. This article examines how these IDs are defined in the source code and how the CLI normalizes them before performing lookups against the embedded dataset.

Where Supported Guideline IDs Are Defined

The canonical list of supported guideline IDs resides in the embedded resource internal/guidelines/guidelines.json. Each entry in this JSON array contains an "id" field that defines a valid identifier, following the pattern G001, G002, and subsequent sequential codes.

According to the repository structure, internal/guidelines/schema/schema.go parses this embedded JSON into Go structs, which are then consumed by internal/guidelines/guidelines.go. This architecture ensures that the CLI operates against a static, version-controlled set of guidelines shipped within the binary itself.

How the CLI Normalizes Guideline IDs

When the explain command receives user input, the raw slice of strings passes through the normalizeGuidelineIDs function located at lines 82–94 in internal/guidelines/guidelines.go. This function implements a three-step sanitization process:

• Whitespace trimming: Each value undergoes strings.TrimSpace() to remove leading and trailing whitespace.
• Empty string removal: The function skips any values that are empty after trimming.
• Deduplication: A map[string]bool tracks seen IDs, ensuring only the first occurrence of each ID is retained in the result slice.

The following implementation from guidelines.go demonstrates this logic:

func normalizeGuidelineIDs(values []string) []string {
    seen := map[string]bool{}
    var result []string
    for _, value := range values {
        value = strings.TrimSpace(value)   // 1️⃣ trim whitespace
        if value == "" || seen[value] {    // 2️⃣ skip empty & duplicates
            continue
        }
        seen[value] = true
        result = append(result, value)     // 3️⃣ keep first occurrence order
    }
    return result
}

Using the Explain Command with Guideline IDs

The explain command accepts guideline IDs through the --guideline-id flag, defined in internal/cli/cli.go. The CLI uses a custom stringListFlag type to accumulate multiple IDs, whether passed as comma-separated values or separate arguments.

For example, the following command demonstrates how users can supply multiple IDs:

go-modern-guidelines explain --guideline-id G001,G002 G003

Internally, cli.go forwards this raw slice to guidelines.ExplainText(), which invokes the normalization routine before attempting any lookup against the embedded JSON data.

Error Handling for Unknown IDs

If the normalization process yields an ID that does not exist in the embedded guidelines.json, the CLI returns a descriptive error. The error message lists the invalid ID followed by the complete set of supported guideline IDs:

unknown Go modern code guideline ids: XYZ. Available ids: G001, G002, …

This validation occurs after normalization, ensuring that only clean, unique, and valid identifiers trigger the guideline lookup logic.

Summary

• Supported guideline IDs are defined in the embedded internal/guidelines/guidelines.json file, parsed via internal/guidelines/schema/schema.go.
• The normalizeGuidelineIDs function in internal/guidelines/guidelines.go (lines 82–94) handles CLI normalization by trimming whitespace, removing empty strings, and deduplicating while preserving order.
• The explain command in internal/cli/cli.go accepts IDs via the --guideline-id flag and processes them through the normalization pipeline before lookup.
• Invalid IDs trigger an error message that explicitly lists all available guideline identifiers.

Frequently Asked Questions

Where are the supported guideline IDs defined in the repository?

The supported IDs are defined in the id fields of the embedded internal/guidelines/guidelines.json file. The internal/guidelines/schema/schema.go file provides the Go structs used to parse this JSON into usable data structures consumed by the main logic.

How does the CLI handle duplicate guideline IDs?

The normalizeGuidelineIDs function removes duplicates while preserving the order of the first occurrence. It uses a map to track seen IDs during iteration, ensuring that subsequent duplicates are skipped during the normalization process.

What happens if I provide an invalid guideline ID to the explain command?

The CLI validates normalized IDs against the embedded guidelines.json set. If an ID is not found, it returns an error message formatted as unknown Go modern code guideline ids: [ID]. Available ids: [list], where [list] contains all valid guideline IDs.

Does the CLI normalize whitespace in guideline IDs?

Yes, the normalization routine explicitly calls strings.TrimSpace() on every input value to remove leading and trailing whitespace before checking for emptiness or duplicates.

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