Internal Architecture of the go-modern-guidelines Loading System: A Deep Dive

The go-modern-guidelines loading system embeds guideline definitions directly into the binary using //go:embed, then validates the JSON through a strict schema parser before constructing a runtime model with O(1) ID lookups and version-filtered access.

The JetBrains/go-modern-guidelines repository provides a lightweight tool for accessing modern Go coding recommendations. Its loading system is built around a self-contained pipeline that transforms embedded JSON data into a queryable runtime model without external file dependencies. Understanding this architecture reveals how the tool achieves zero runtime dependencies while maintaining strict data integrity and fast lookup performance.

Core Components of the Loading Pipeline

The loading system consists of three primary components working in sequence to deliver guideline data from embedded binary assets to the public API.

Embedded JSON Payload

The raw guideline definitions live in internal/guidelines/guidelines.json and are compiled into the binary using the //go:embed directive. In internal/guidelines/guidelines.go, the variable declaration embeds the JSON as a byte slice:

//go:embed guidelines.json
var modernGoGuidelinesJSON []byte

This compile-time embedding ensures the application requires no external data files at runtime.

Schema Parser and Validation

The internal/guidelines/schema/schema.go file contains the validation logic that unmarshals and verifies the embedded JSON. The schema.Parse function returns a slice of schema.Guideline structs only after performing rigorous safety checks on the data structure.

Runtime Model Builder

After validation, internal/guidelines/guidelines.go converts the parsed schema.Guideline objects into the internal modernGoGuideline type. This component builds helper maps for fast lookups and supplies the public API methods including ListText, ExplainText, and SupportedGuidelines.

Step-by-Step Loading Process

The pipeline executes a strict sequence from compile-time embedding to runtime API exposure.

Compile-Time Embedding with go:embed

The process begins at compilation when the Go toolchain embeds guidelines.json into the binary via the //go:embed directive. The modernGoGuidelinesJSON byte slice makes the entire dataset available as a static resource, eliminating file system dependencies and ensuring distribution as a single static binary.

Strict Validation in schema.Parse

When the application initializes, the mustLoadModernGoGuidelines function invokes schema.Parse(modernGoGuidelinesJSON). The parser performs several critical validations:

• Identifier format validation using validID to ensure guideline IDs follow naming conventions
• Version format checking with goversion.IsMajorMinor to confirm since_version fields match the "major.minor" pattern
• Ordering verification using goversion.Compare to guarantee the list is sorted newest-first
• Content completeness checks ensuring the modernizer flag, category, impact, guideline, details, and at least one example are present

If any validation fails, schema.Parse returns an error, causing mustLoadModernGoGuidelines to panic during initialization if the embedded data is malformed.

Runtime Model Construction

For each validated schema.Guideline, the loader constructs a modernGoGuideline value by:

1. Concatenating the Before and After example slices into single strings using strings.Join
2. Copying remaining fields including id, sinceVersion, and modernizer flags
3. Storing the resulting slice in the package-level variable modernGoGuidelines

This transformation creates a flattened, runtime-optimized structure distinct from the raw schema representation.

Lazy Lookup Helper Initialization

The system creates a lazily-initialized map named guidelineByID from the modernGoGuidelines slice. This map supports O(1) lookups for the Explain command, allowing immediate access to specific guidelines by their identifier without linear scanning.

Version Filtering Logic

The supportedGuidelines(targetGoVersion) function iterates over modernGoGuidelines and filters entries based on their sinceVersion. Using goversion.Compare, it retains only guidelines applicable to the supplied target version (where guideline version ≤ target version). This enables the tool to show only relevant recommendations for specific Go releases.

Public API and CLI Integration

The loading system exposes functionality through both programmatic interfaces and command-line tools.

Programmatic API

The public API in internal/guidelines/guidelines.go provides three primary functions:

// List all guidelines applicable to Go 1.20
txt, err := guidelines.ListText("1.20")
if err != nil {
    log.Fatal(err)
}
fmt.Println(txt)

// Retrieve detailed markdown descriptions for specific guidelines
details, err := guidelines.ExplainText([]string{"use_context", "no_interface_nil"})
if err != nil {
    log.Fatal(err)
}
fmt.Println(details)

// Determine the highest Go version covered by the guideline set
fmt.Println("Latest known version:", guidelines.LatestKnownVersion())

CLI Wrapper

The entry point in main.go forwards command-line arguments to cli.Run in internal/cli/cli.go. This thin wrapper translates CLI invocations into calls to the loading system:

# List supported guidelines for Go 1.19

$ go-modern-guidelines list 1.19

# Show detailed help for specific IDs

$ go-modern-guidelines explain use_context no_interface_nil

The CLI delegates to the same ListText and ExplainText functions used by the programmatic API, ensuring consistent behavior across interfaces.

Summary

• The system uses //go:embed to compile guidelines.json directly into the binary, eliminating external file dependencies.
• Validation occurs in schema.Parse within internal/guidelines/schema/schema.go, checking ID formats, version strings, ordering, and content completeness.
• The runtime model converts schema structs into modernGoGuideline objects with concatenated example strings stored in internal/guidelines/guidelines.go.
• O(1) lookups are enabled via a lazy-initialized guidelineByID map for the Explain functionality.
• Version filtering uses goversion.Compare to show only guidelines relevant to a target Go version.
• The public API exposes ListText, ExplainText, and LatestKnownVersion functions used by both programmatic consumers and the CLI wrapper.

Frequently Asked Questions

How does go-modern-guidelines load data without external files?

The tool uses the //go:embed directive in internal/guidelines/guidelines.go to embed guidelines.json as a byte slice at compile time. This embeds the JSON data directly into the compiled binary, allowing the application to access guideline definitions without reading external files at runtime.

What validation checks does the schema parser perform?

According to internal/guidelines/schema/schema.go, the parser validates identifier formats with validID, confirms since_version follows "major.minor" patterns using goversion.IsMajorMinor, verifies the list is ordered newest-first via goversion.Compare, and ensures required fields including modernizer, category, impact, and at least one example are present.

How does the system handle different Go versions?

The supportedGuidelines function filters the full guideline list by comparing each entry's sinceVersion against the user-supplied target version using goversion.Compare. Only guidelines with a version less than or equal to the target are returned, allowing the tool to display contextually appropriate recommendations for specific Go releases.

Where is the entry point for the loading system?

The entry point resides in main.go, which calls cli.Run to process command-line arguments. The CLI then invokes mustLoadModernGoGuidelines, which triggers the full loading pipeline: parsing the embedded JSON, validating through schema.Parse, building the runtime model, and initializing lookup maps before serving API requests.

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