Help us shape the future of Go! Take the 2026 Go Developer Survey

modcompat

package
v0.32.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Oct 29, 2026 License: MPL-2.0 Imports: 11 Imported by: 0

Documentation

Overview

Package modcompat builds live/module-compat.json, the module compatibility table in its two tiers (GitHub issue #2292).

The static tier is one row per terraform-aws-modules example, measured by tools/refusal-probe in the onboarded form (-schemas -onboarded): the configuration a user runs after adding a live block, and the one every gauntlet script runs. Its rows come from a sweep file, so regenerating the static tier means running the probe again; see tools/modcompat-gen.

The gauntlet tier is one row per terraform-popular estate in live/gauntlet.json whose last run is current: measured against the pinned emulator, AWS provider, stock oracle and engine base, with a script that has not changed since (the board's script_stale). A row that fails any of those is left out, so the array lists recorded current runs only. It is a pure function of committed files, and `go run ./tools/gauntlet render` refreshes it.

The two tiers share no figure. Nothing in the file adds a static row to a gauntlet row or reports a combined total, by the issue's ruling: a static clear says live-check plans the example offline, and a gauntlet pass says a recorded run applied it against the emulator. Those are different claims.

Index

Constants

View Source
const (
	Rel           = "live/module-compat.json"
	ManifestRel   = "live/corpus-manifest.json"
	ArtifactRel   = "live/gauntlet.json"
	BoardRel      = "live/gauntlet-board.json"
	SchemaVersion = 1
)

Paths, relative to the repository root.

View Source
const (
	TierStatic   = "static"
	TierGauntlet = "gauntlet"
)

The tiers, as each row spells its own.

View Source
const (
	Origin = "terraform-aws-modules"
	Lane   = "terraform-popular"
)

Origin is the manifest origin the static tier draws from, and Lane the gauntlet lane the gauntlet tier draws from.

View Source
const (
	VerdictClear      = "clear"
	VerdictRefused    = "refused"
	VerdictUnmeasured = "unmeasured"
)

The static verdicts.

View Source
const (
	StaticCommand   = "refusal-probe -schemas -onboarded -out sweep.json, then go run ./tools/modcompat-gen -sweep sweep.json"
	GauntletCommand = "go run ./tools/gauntlet render"
)

StaticCommand is the command that regenerates the static tier, and GauntletCommand the one that refreshes the gauntlet tier.

View Source
const DocsBase = "https://github.com/INTENTIUS/choudoufu/blob/main/"

DocsBase is where a refusal's documentation reference is linked to.

Variables

View Source
var Comment = []string{
	"Generated, never hand-edited (GitHub issue #2292). Two tiers, which share no figure:",
	"",
	"static: one row per terraform-aws-modules example in live/corpus-manifest.json,",
	"measured by tools/refusal-probe in the onboarded form (-schemas -onboarded), the",
	"configuration a user runs after adding a live block. clear means live-check plans",
	"it offline; reads counts eligible data-source reads, which never refuse. Regenerate",
	"with: " + StaticCommand + ".",
	"",
	"gauntlet: one row per terraform-popular estate in live/gauntlet.json whose last run",
	"is current against every pin and whose script has not changed since. A row that is",
	"not current is left out. Refresh with: " + GauntletCommand + ".",
}

Comment is the file's _comment, written on every generation.

Functions

func Anchor

func Anchor(heading string) string

Anchor is GitHub's heading anchor: lower case, every character that is not a letter, digit, space, hyphen or underscore dropped, spaces made hyphens.

func DocsURL

func DocsURL(ref string) string

DocsURL links a documentation reference (docsref form) to its first heading on GitHub. It returns "" for a reference that does not parse.

func Encode

func Encode(f *File) ([]byte, error)

Encode renders f the way it is committed.

func ModuleFromRepo

func ModuleFromRepo(repo string) (string, bool)

ModuleFromRepo turns a terraform-aws-modules clone URL into its registry address: https://github.com/terraform-aws-modules/terraform-aws-vpc.git is terraform-aws-modules/vpc/aws.

func RefreshGauntlet

func RefreshGauntlet(root string) (bool, error)

RefreshGauntlet rebuilds the gauntlet tier from the committed artifact and board, keeps the static tier as committed, and writes the file. It is what `tools/gauntlet render` calls.

func StaticTier

func StaticTier(root string, s *Sweep, opts StaticOptions) (*StaticMeasurement, []StaticRow, error)

StaticTier builds the static measurement and rows from a sweep, against the manifest's terraform-aws-modules sources at root.

It refuses a sweep that cannot stand for the static tier: one taken without schemas, without the onboarded form or without the second pass; one whose corpus was partial for any terraform-aws-modules source; one taken on a dirty tree; and one whose sources disagree with the manifest's pins. Each of those would publish a row measuring something other than what the row says.

func Write

func Write(root string, f *File) (bool, error)

Write writes f to root and reports whether the bytes changed.

Types

type File

type File struct {
	Schema  int      `json:"schema"`
	Comment []string `json:"_comment"`

	// StaticMeasurement says what the static rows were measured with. It
	// is nil only before the first sweep.
	StaticMeasurement *StaticMeasurement `json:"static_measurement"`

	Static   []StaticRow   `json:"static"`
	Gauntlet []GauntletRow `json:"gauntlet"`
}

File is live/module-compat.json.

func Read

func Read(root string) (*File, error)

Read loads the committed file at root. A missing file reads as an empty one, so the first generation can start from nothing.

type GauntletRow

type GauntletRow struct {
	Tier    string `json:"tier"`
	Module  string `json:"module"`
	Version string `json:"version"`
	Example string `json:"example"`
	Estate  string `json:"estate"`

	Date        string  `json:"date"`
	Commit      string  `json:"commit"`
	Emulator    string  `json:"emulator"`
	AWSProvider string  `json:"aws_provider"`
	Engine      string  `json:"engine"`
	Oracle      Oracle  `json:"oracle"`
	Clear       bool    `json:"clear"`
	Stages      []Stage `json:"stages"`
}

GauntletRow is one current recorded gauntlet run of a module example.

func GauntletRows

func GauntletRows(root string) ([]GauntletRow, error)

GauntletRows returns the gauntlet tier: every terraform-popular estate of a terraform-aws-modules repository whose last run is current.

Current means all of: a recorded run, on the floci substrate, against the emulator image, the hashicorp/aws release, the stock oracle and the engine base the artifact pins now, with a script the board does not mark stale. That is tools/gauntlet's pinCurrent plus its provider and script checks, restated over the committed files, so a row the board marks **Stale** in any way is never published here.

type Oracle

type Oracle struct {
	Terraform string `json:"terraform"`
	Tofu      string `json:"tofu"`
}

Oracle is the stock binaries a gauntlet run compared against.

type Refusal

type Refusal struct {
	ID      string `json:"id"`
	Layer   string `json:"layer"`
	Sites   int    `json:"sites"`
	DocsRef string `json:"docs_ref,omitempty"`
	DocsURL string `json:"docs_url,omitempty"`
}

Refusal is one refusal ID that fired on a row, with its site count and the document that explains it.

type Source

type Source struct {
	Module   string `json:"module"`
	Repo     string `json:"repo"`
	Version  string `json:"version"`
	Commit   string `json:"commit"`
	Glob     string `json:"glob"`
	Examples int    `json:"examples"`
}

Source is one module repository at one tag.

func ManifestSources

func ManifestSources(root string) ([]Source, error)

ManifestSources returns the manifest's terraform-aws-modules sources at root, in manifest order, with Examples left zero. A source of that origin with no fetch block, no tag or an unrecognized repository is an error: the static tier cannot name a module and version for it.

type Stage

type Stage struct {
	ID      string `json:"id"`
	Title   string `json:"title"`
	Verdict string `json:"verdict"`
}

Stage is one gauntlet stage's verdict.

type StaticMeasurement

type StaticMeasurement struct {
	Date       string `json:"date"`
	Commit     string `json:"commit"`
	Instrument string `json:"instrument"`
	Form       string `json:"form"`
	Schemas    bool   `json:"schemas"`
	SecondPass bool   `json:"second_pass"`

	// AWSProvider is the hashicorp/aws release the probe held every entry
	// at (its -provider-version).
	AWSProvider string `json:"aws_provider"`

	// Sources are the manifest's terraform-aws-modules sources at the time
	// of the sweep. live/module_compat_test.go holds them to the manifest,
	// so a re-pinned or added module makes the static tier stale loudly.
	Sources []Source `json:"sources"`
}

StaticMeasurement is the provenance every static row shares.

type StaticOptions

type StaticOptions struct {
	// Date is the day the sweep ran, YYYY-MM-DD.
	Date string

	// Commit is the choudoufu commit the probe was built from. It is
	// required when the sweep recorded none (a -root outside a git
	// checkout), and must agree with the sweep when both are set.
	Commit string
}

StaticOptions are the inputs a sweep does not carry.

type StaticRow

type StaticRow struct {
	Tier    string `json:"tier"`
	Module  string `json:"module"`
	Version string `json:"version"`
	Example string `json:"example"`

	Date        string `json:"date"`
	Commit      string `json:"commit"`
	AWSProvider string `json:"aws_provider"`

	Verdict string `json:"verdict"`

	// Reason is why a row is unmeasured. Empty otherwise.
	Reason string `json:"reason,omitempty"`

	// Reads counts the sites that resolve at plan time through an eligible
	// data-source read (check.Report.Reads). They never make a row
	// refused, and they never appear under Refusals (#2295).
	Reads int `json:"reads"`

	Refusals []Refusal `json:"refusals"`

	// MissingProviders names the providers whose schemas the probe could
	// not acquire for this example. A row with any is a partial-schema
	// measurement.
	MissingProviders []string `json:"missing_providers,omitempty"`
}

StaticRow is one example in the onboarded form.

type Sweep

type Sweep struct {
	ProbeVersion   int               `json:"probe_version"`
	Commit         string            `json:"commit"`
	CorpusProblems []string          `json:"corpus_problems"`
	Schemas        bool              `json:"schemas"`
	OnboardedForm  bool              `json:"onboarded_form"`
	SecondPass     bool              `json:"second_pass"`
	PinSource      string            `json:"pin_source"`
	PinVersion     string            `json:"pin_version"`
	Sources        []SweepSource     `json:"sources"`
	Layers         map[string]string `json:"layers"`
	Entries        []SweepEntry      `json:"entries"`
}

Sweep is the part of a tools/refusal-probe sweep file the static tier reads. The probe is a main package, so its types are mirrored here field by field, by JSON name.

func ReadSweep

func ReadSweep(path string) (*Sweep, error)

ReadSweep decodes a sweep file.

type SweepEntry

type SweepEntry struct {
	Name       string           `json:"name"`
	Origin     string           `json:"origin"`
	Providers  []SweepProvider  `json:"providers"`
	Onboarding *SweepOnboarding `json:"onboarding"`
	Onboarded  *SweepForm       `json:"onboarded"`
}

SweepEntry is one measured configuration.

type SweepForm

type SweepForm struct {
	Blocked  bool           `json:"blocked"`
	Reads    int            `json:"reads"`
	Refusals map[string]int `json:"refusals"`
}

SweepForm is one form's analysis.

type SweepOnboarding

type SweepOnboarding struct {
	Status string `json:"status"`
	Reason string `json:"reason"`
}

SweepOnboarding is internal/live/onboard's conclusion for an entry.

type SweepProvider

type SweepProvider struct {
	Provider string `json:"provider"`
	Present  bool   `json:"present"`
}

SweepProvider is one provider an entry needed.

type SweepSource

type SweepSource struct {
	Glob     string `json:"glob"`
	Origin   string `json:"origin"`
	Entries  int    `json:"entries"`
	Pin      string `json:"pin"`
	Checkout string `json:"checkout"`
}

SweepSource is one manifest source as the sweep expanded it.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL