How Guidelines Data Is Embedded in the go-modern-guidelines CLI

The go-modern-guidelines CLI embeds its guideline definitions as a compiled-in JSON asset using Go's embed package, parsing the data at startup into a slice of structs that the list and explain commands consume.

The JetBrains/go-modern-guidelines project distributes Go best practices as a standalone command-line tool. To ensure seamless operation without external dependencies, the guidelines data embedded into the go-modern-guidelines CLI is baked directly into the binary at compile time. This approach guarantees that every distribution contains the complete, version-matched rule set regardless of the execution environment.

How the Embedding Works

Embedding the JSON Asset

In internal/guidelines/guidelines.go, the source file guidelines.json is embedded using the //go:embed directive. This directive instructs the Go compiler to store the specified file's contents as a byte slice within the binary.

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

This declaration places the entire JSON content into the modernGoGuidelinesJSON variable, making it available at runtime without filesystem access.

Parsing the Guideline Data

At program initialization, the mustLoadModernGoGuidelines() function parses the embedded byte slice. According to the JetBrains/go-modern-guidelines source code, this function uses a schema-generated parser to validate and convert the JSON into strongly-typed Go structs.

The resulting slice of modernGoGuideline structs is stored in the package-level variable modernGoGuidelines, providing in-memory access to all guideline definitions throughout the application lifecycle.

Accessing Embedded Data from CLI Commands

The CLI implementation in internal/cli/cli.go delegates all data retrieval to the guidelines package, ensuring both commands operate on the same embedded dataset.

The list Command

When users run the list subcommand, the CLI invokes guidelines.ListText(targetVersion) (referenced at lines 84-86 in internal/cli/cli.go). This function filters the embedded guidelines based on the target Go version and returns a concise summary of applicable rule IDs and descriptions.

The explain Command

For detailed inspections, the explain command calls guidelines.ExplainText(guidelineIDs) (found at lines 6-12 in internal/cli/cli.go) to fetch full documentation, including code examples and rationales. This retrieval occurs against the in-memory modernGoGuidelines slice populated during startup.

Benefits of Compile-Time Embedding

Embedding the guidelines data embedded into the go-modern-guidelines CLI directly into the binary provides significant operational advantages. The tool requires no external data files, configuration directories, or network access to function. This design ensures the guideline set remains available even when the binary is distributed independently or executed in isolated, air-gapped environments.

Summary

• The //go:embed directive in internal/guidelines/guidelines.go imports guidelines.json into the modernGoGuidelinesJSON byte slice.
• mustLoadModernGoGuidelines() parses the embedded JSON into a slice of modernGoGuideline structs at startup.
• The list command consumes this data via guidelines.ListText(targetVersion) to filter by Go version.
• The explain command retrieves details via guidelines.ExplainText(guidelineIDs) from the in-memory cache.
• Compile-time embedding enables single-binary distribution with zero external file dependencies.

Frequently Asked Questions

What file format stores the guidelines definitions?

The guidelines are stored as a JSON file located at internal/guidelines/guidelines.json. This file contains structured definitions including guideline IDs, summaries, detailed explanations, and code examples.

How does the CLI access the embedded guidelines?

The CLI accesses the data through the guidelines package API. The list command calls guidelines.ListText(targetVersion) while the explain command calls guidelines.ExplainText(guidelineIDs), both operating on the modernGoGuidelines slice populated during package initialization.

Why embed the data instead of loading it from disk?

Embedding the JSON directly into the binary using the //go:embed directive ensures the CLI operates as a single standalone file. This guarantees that guideline definitions remain available even when the binary is moved, renamed, or distributed without accompanying data files.

Where in the source code does the embedding logic reside?

The embedding occurs in internal/guidelines/guidelines.go at lines 29-30, where the //go:embed guidelines.json directive precedes the modernGoGuidelinesJSON variable declaration. This file also contains the mustLoadModernGoGuidelines() function that handles parsing.

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