Documentation
¶
Overview ¶
Package workflow is the file `hyper project` writes, as a pure function: the facts one Procedure's workflow is derived from in, its exact bytes out (§10, §11, issue #176).
**Nothing here writes a file.** It opens none, reaches no network, starts no subprocess and reads no clock — which is what lets the generator and §10's projection check be *one function called from two places* rather than two renderings that can drift. Who writes, and whether anything is written at all, is internal/cli's; what the check compares against is these same bytes.
**It is not called `projection`.** That name is taken, by §12's path grammar resolved against a Capability's response object — a different thing wearing the same word, which §12 says out loud about the two `projection` error codes, and one package name cannot carry both.
**Nothing about the executor is a parameter.** §11 closes the compiled-in constants at four and they are this package's own: the runner, the checkout, the release artefact URL and the checksums file URL. There is no file, flag or environment variable that reaches them (ADR-0014, ADR-0046), and the version is the only variable in either URL — the platform is not one.
**The job summary is shell in this file and nothing else.** The binary those bytes invoke is told nothing: it never reads `$GITHUB_STEP_SUMMARY`, and detecting it would be the is-CI axis the safety model deleted wearing a helpful costume. `hyper run <procedure>` writes the same bytes on a laptop as on a runner (ADR-0021).
Index ¶
Constants ¶
const ( // Dir is where every generated workflow sits, relative to the // repository root and spelled in slashes: it is a path inside a git // repository before it is a path on a disk, and the executor reads it // under that name on every platform. Dir = ".github/workflows" )
Variables ¶
This section is empty.
Functions ¶
func ArtefactName ¶
ArtefactName is the release artefact's filename for version.
func ArtefactURL ¶
ArtefactURL is the release artefact for version, and ArtefactName is the filename alone — what a line of the checksums file names, and what `project` looks for there. They are one template read two ways rather than two templates, so no reading of it can name a file the other does not fetch.
func ChecksumsURL ¶
ChecksumsURL is the checksums file under the same tag — the one network read `project` makes, and the fourth of §11's constants.
func Generate ¶
Generate is one Procedure's workflow file, whole.
The sections are §10's own, in its order, and every one of them carries one fact for its own reason. Two of them are conditional and neither is conditional on anything about the executor: the concurrency block, on the Procedure effecting, and the `env:` block, on its bindings requiring a slot.
func Path ¶
Path is where procedure's workflow sits, relative to the repository root — the Procedure's name verbatim between the two fixed halves, so run history in the executor's own UI is per-Procedure and nothing is ambiguous about which expression fired (§10).
func ProcedureOf ¶
ProcedureOf is the Procedure name a path in the namespace carries, and false where the path is not in the namespace at all.
It is Path read backwards and is exact about it: a file directly under Dir whose name opens with `hyper-` and closes with `.yml`, and nothing else. A `hyper-.yml` names the empty Procedure, which no Procedure is, and is in the namespace like any other — the file is `project`'s to remove, and what makes it so is where it sits rather than whether the name it carries resolves.
Types ¶
type Facts ¶
type Facts struct {
// Procedure is the Procedure's name, verbatim. It is the workflow's
// name and its job's, that string being the subject line of the
// executor's own failure email and the only part of a failure visible
// on a phone (§10, ADR-0005, ADR-0021).
Procedure string
// Cadence is the recurrence exactly as the artefact declared it. It is
// the whole of `on:` — the reviewed artefact declares a recurrence and
// no second occasion for a Run to start, and a Run a person starts is
// started from a laptop and records that Trigger (§7, §10).
Cadence string
// Effects is whether the Procedure reaches, to any depth, a Step that
// is not a `read`. It decides the concurrency block and nothing else: a
// Procedure whose every reachable Step is `read` takes the shared lock
// and reaps nothing, and serialising it would starve a five-minute
// cadence behind a forty-minute provision (§10).
Effects bool
// Variables is the environment variable names the credential slots this
// Procedure's bindings require resolve from — the executor secrets the
// `run` step needs, each named exactly as the variable, because the
// runtime binary resolves an environment variable on a runner exactly
// as it does on a laptop (§10, ADR-0007).
//
// In any order and with repeats: Generate orders them by Unicode code
// point and writes each once, the block being a function of the
// repository rather than of the walk that found them. Two Definitions
// binding one Target under one scheme reach one slot and one variable,
// and a mapping may not carry a key twice.
//
// Empty writes no `env:` key at all rather than an empty mapping: an
// absent block is the ordinary absence rule, and an empty one asserts a
// lookup that happened and found nothing (§10).
Variables []string
// Version is the `hyper` version to install — the pin, appearing in the
// four places §11 counts: the header comment, the install step's own
// name, the release tag and the artefact's filename.
Version string
// Digest is the frozen checksum of that artefact, as `hyper.yaml`
// spells it — the algorithm inline, so a reviewer reads which one
// produced it rather than trusting the file's silence (§3). The
// checksum line takes the hex alone and this package writes it that
// way, which is one split in one place rather than one every caller
// repeats.
Digest string
}
Facts is everything one workflow file says, and the whole of what Generate is given: the file is a function of these and of the four constants above, and of nothing else.
Every member is derived from something somebody wrote and reviewed — which is the division §11 draws through the file's content, the constants being what it says about the world outside both the binary and the repository.
Source Files