Documentation
¶
Overview ¶
Package verify is §4's static verification over an already-loaded repository: the second pass, which runs after internal/repository has walked the artefact locations and parsed every file, and which reports every problem it finds rather than the first.
It is a package of its own because it has two callers and one of them is not a command. `hyper check` is the surface §9 gives it; a Run re-runs it **in full with nothing skipped** at Run start, which is how all thirty-two of §4's static codes reach a Run and why most of the closed `error_code` set declines before Step 1 (§6, ADR-0061). Two callers spelling that pass for themselves is two readings of §4, and the day comes that a Run admits a repository `check` refuses.
It owns two rules and no more. Every other problem it reports comes from the load (internal/repository, over internal/yamlsubset's own grammar) and from an artefact's own schema and checks (internal/artefact); what is here is the walk — which checks run over which artefact, and the one graph-wide pass that needs every procedures/ file at once.
The rules that are its own are the two whose subject is not an artefact, and so could belong to no artefact's checks: §11's `provider-name-collision`, a Manifest in providers/ taking a name a built-in Provider already means (collision.go), and §10's `projection-stale`, the generated workflows the load found against the projection this repository's artefacts ask for (projection.go).
Two derivations stand beside those rules and are exported for one reason: a surface renders what this pass checks, and two builders of one thing is where the day comes that they disagree. ProcedureGraph is the invocation graph a review's roster quantifies over; Projection is the set of workflow files `hyper project` writes, which is the same set §10's own check holds a working tree to — generate and verify being one derivation called from two places (projection.go).
Index ¶
- Constants
- func DeclaredPin(loaded repository.Loaded) (version, digest string)
- func ProcedureGraph(loaded repository.Loaded) artefact.ProcedureGraph
- func Repository(loaded repository.Loaded) []problem.Problem
- func UnwantedWorkflows(loaded repository.Loaded, wanted []ProjectedWorkflow) []string
- type ProjectedWorkflow
Constants ¶
const CodeProjectionStale = "projection-stale"
CodeProjectionStale is §10's own static code: a generated workflow that is not what `project` would write now (§12).
It is spelled here, at the check that fires it, and read from here by the Refusal rendering that knows its remedy — one string rather than two that happen to agree (§8, internal/cli/refusal.go).
const CodeProviderNameCollision = "provider-name-collision"
CodeProviderNameCollision is §11's own static code: a Manifest in providers/ taking a built-in Provider's name (§12).
It is spelled here, at the check that fires it, on CodeProjectionStale's own footing — one string rather than two that happen to agree.
Variables ¶
This section is empty.
Functions ¶
func DeclaredPin ¶
func DeclaredPin(loaded repository.Loaded) (version, digest string)
DeclaredPin is the version and the digest a loaded repository's own declaration carries — the two facts a projection regenerated against what `hyper.yaml` says is derived from — and the empty strings where it carries neither legibly.
**The two facts come through two doors and that is the pin's own shape**: the version is internal/pin's, which is where the gate reads it, and the digest is internal/artefact's, which is where every fact the declaration *says* is read (§9, §11, ADR-0020).
It is exported beside Projection, and for Projection's own reason: the check below regenerates at the declared pin, and so does the corpus guard that holds a fixture repository to the same derivation — **two readings of the pin is the day a `-update` writes bytes `check` disagrees with** (issue #181, internal/cli/golden_test.go).
It is not the reading `project` does. That command derives the version from the binary that ran it and freezes a digest for it, which is a different question about a different moment and is stated at its own site (§11, internal/cli/project.go).
func ProcedureGraph ¶
func ProcedureGraph(loaded repository.Loaded) artefact.ProcedureGraph
ProcedureGraph is the invocation graph an already-loaded repository makes: every procedures/ file at once, which is what the transitive checks and a Procedure's own review roster both need (issue #96).
It is exported beside Repository because the review renders the same graph this pass checks — §8's roster on a Procedure quantifies over every Step's `target:` to any depth — and two builders of one graph is where the day comes that a review's marks and a `check`'s problems disagree about what a nested invocation reaches.
func Repository ¶
func Repository(loaded repository.Loaded) []problem.Problem
Repository runs every static check over an already-loaded repository and answers what it found, unsorted and unfiltered.
The order is the walk's, and it is deliberately not the answer: §9 fixes the order problems are reported in — by file path, then by line — and problem.Sort is what puts them there. A caller that reports a subset filters after this rather than narrowing it, because every rule compares one artefact against another and a subset of the repository is not checkable on its own (§9).
A failed load does not stop it. Reading or parsing one file stops every check after it for that file and never for the repository, which is why the load's own problems are carried through here beside the checks' rather than short- circuiting them (issue #88).
func UnwantedWorkflows ¶
func UnwantedWorkflows(loaded repository.Loaded, wanted []ProjectedWorkflow) []string
UnwantedWorkflows is the files standing in the namespace that this repository's projection does not ask for: what `hyper project` takes away in the same act that writes the rest, and what the check above reports as the second of the code's three shapes.
**The namespace is answered as a set**, which is why there is no shape of leftover that has to be recognised for what it is: a Procedure that has dropped its `cadence:`, a Procedure that has been deleted, and a `hyper-*.yml` naming no Procedure at all reach it the same way (§10).
It is exported beside Projection, and for Projection's own reason: **the command that removes a file and the check that says the file should not be there are one derivation**, and two of them is the day a `project` leaves behind a repository that fails its own check.
wanted is the caller's projection rather than one computed here, because the two callers project at two versions — `project` at the binary's, the check at the declaration's — and which files are asked for is the same set either way (issue #178).
Types ¶
type ProjectedWorkflow ¶
ProjectedWorkflow is one file the projection asks for: which Procedure asked for it, where it sits relative to the repository root, the Cadence that put it there, and its exact bytes.
The Cadence rides along because every surface that reports a projected file glosses it (§10) — `project`'s own rows are the fourth surface that renders a gloss — and re-reading the artefact to find it again would be a second reading of the fact the bytes were derived from.
func Projection ¶
func Projection(loaded repository.Loaded, version, digest string) []ProjectedWorkflow
Projection is every workflow file a repository's reviewed artefacts ask for: one per Procedure declaring a Cadence, ordered by Procedure name by Unicode code point (§10).
It is exported beside Repository and ProcedureGraph, and for ProcedureGraph's own reason: **the command that writes the projection and the check that holds the working tree to it are one derivation**, and two of them is the day a repository `project` has just written fails its own check. What varies between the two callers is only what they do with the bytes — write them, or compare them against what stands.
version and digest are the two facts here that are not read off the loaded repository, and they are parameters to say so. `project` derives the pin from the binary that ran it and freezes the checksum for that version in the same act (§11, ADR-0020) — so at the moment these bytes are generated the declaration on disk still carries the pin they are replacing, and reading either fact off it would project the version being left behind. What the caller hands over is what it is about to write into `hyper.yaml`, which is what makes the workflow and the declaration one edit rather than two (issue #178).
**The other caller reads them off the declaration**, and is right to: §10's projection check regenerates against what `hyper.yaml` says, because under the pin gate the declaration's version and the running binary's are the same string and reading the file is what keeps the check inside a pass that touches nothing outside the load (projectionProblems below, issue #179).
**Nothing here reads a file, a clock or a network**, and nothing here judges a repository: an artefact that would earn a problem still projects, because what stops a projection is `check` reporting something and that is its caller's to ask (§10, ADR-0064).
Source Files