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
- Variables
- func Anchor(heading string) string
- func DocsURL(ref string) string
- func Encode(f *File) ([]byte, error)
- func ModuleFromRepo(repo string) (string, bool)
- func RefreshGauntlet(root string) (bool, error)
- func StaticTier(root string, s *Sweep, opts StaticOptions) (*StaticMeasurement, []StaticRow, error)
- func Write(root string, f *File) (bool, error)
- type File
- type GauntletRow
- type Oracle
- type Refusal
- type Source
- type Stage
- type StaticMeasurement
- type StaticOptions
- type StaticRow
- type Sweep
- type SweepEntry
- type SweepForm
- type SweepOnboarding
- type SweepProvider
- type SweepSource
Constants ¶
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.
const ( TierStatic = "static" TierGauntlet = "gauntlet" )
The tiers, as each row spells its own.
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.
const ( VerdictClear = "clear" VerdictRefused = "refused" VerdictUnmeasured = "unmeasured" )
The static verdicts.
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.
const DocsBase = "https://github.com/INTENTIUS/choudoufu/blob/main/"
DocsBase is where a refusal's documentation reference is linked to.
Variables ¶
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 ¶
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 ¶
DocsURL links a documentation reference (docsref form) to its first heading on GitHub. It returns "" for a reference that does not parse.
func ModuleFromRepo ¶
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 ¶
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.
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.
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 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 ¶
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.
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 ¶
SweepOnboarding is internal/live/onboard's conclusion for an entry.
type SweepProvider ¶
SweepProvider is one provider an entry needed.