artefact

type AbsentName ¶

type AbsentName struct {
	Key      string
	Name     string
	Provider string
}

AbsentName is the name that resolved to nothing on a Step the gutter marks unresolved: the key it was written under — definition, operation, provider or procedure — the name it named, and, where the key is operation, the Provider whose Manifest it was looked for in.

Name is "" where the key carried nothing legible to resolve at all, which is a different absence from a name that resolved to nothing and is why the name is carried rather than assumed present.

The key is the authoring format's own, and provider is one of the four although no Step writes it: a Step's definition: resolves and the Definition it found names a Provider that does not, which is a name on the Step's own line failing one hop out (§3, §4).

type Authority ¶

type Authority struct {
	Definitions map[string]DefinitionFacts
	Targets     map[string]TargetFacts
}

Authority is the supply behind §8's `AUTHORITY` table: the two namespaces the relation is read across, each keyed by the name its artefact declares for itself.

It is one relation and not two tables. §5's authority rule is an intersection — a Definition claims Kinds and Targets, a Target declaration accepts Kinds — and an intersection privileges neither operand, so the artefact under review supplies one end of it and which end decides the filter and nothing else (ADR-0069). Three of the five artefacts supply an end and two are members of no pair at all.

Both maps are the load's own folds, so the Definition a name means here and the Definition a Step's definition: resolves to are the same file rather than two walks agreeing (issue #109). A name absent from either is a name that resolved to nothing — which covers a file that is not there and one that is there and will not parse alike, the two differing in nothing this table can act on (ADR-0064).

func (a Authority) Table(kind string, root *yaml.Node) AuthorityTable

type AuthorityRow ¶

type AuthorityRow struct {
	Definition        string
	Target            string
	DefinitionKinds   []string
	TargetKinds       []string
	Effective         []string
	DestroyOperations []string
}

AuthorityRow is one pairing as the table states it: which Definition, which Target, what each claims and accepts, their intersection, and the `destroy` Operations the Definition names (§5, §8).

The three Kind lists carry full names and never the page's initials. The initials are a notation this screen renders an intersection in and the names are the values, exactly as `envelope ✓` and `"envelope ok"` are one fact in two notations (§8, ADR-0026).

DefinitionKinds carries `destroy` where the Definition's destroy: names any Operation, derived at that one position rather than read. §3 keeps `destroy` out of kinds: precisely so this column can derive it, granularity following severity (§8).

A list is nil where its end of the pairing has no supply and non-nil otherwise, empty included — and that one encoding is the whole of what says so, a second boolean beside it being a fact stated twice. A Definition that claims no Kind at all claims none, where one that did not load claims nothing this table can read: the page renders the first as an em dash and the second as §8's `unresolved`, and a supply that resolved to nothing and one that resolved to something unreadable are the same absence here.

Effective is the intersection, in the Definition's own claim order: §5's check reads a claim against a grant, so the claim is the operand the intersection is ordered by. It is nil where either end lacks a supply.

type AuthorityTable ¶

type AuthorityTable struct {
	// Renders is false on the two artefacts that are members of no pair — a
	// Manifest, whose Operations declare the Kinds a Definition *may* claim
	// rather than claiming any, and a Repository declaration, which pairs
	// with nothing. On those the table is absent entire rather than empty.
	Renders bool
	// Discovered is true where the row set is discovered across
	// definitions/ rather than authored in the artefact under review, which
	// is the one filter a file that did not load can silently remove a row
	// from. It is why a discovery failure is counted beneath the table on
	// that artefact and nowhere else (ADR-0069).
	Discovered bool
	Rows       []AuthorityRow
}

AuthorityTable is the relation on one artefact: whether it renders at all, whether its row set was discovered rather than authored, and the rows.

The three travel together because a caller needs all three to render the block and no two of them are separable: a table that does not render has no rows and no discovery to have failed, and an empty table means one thing where an edit could produce a row and another where none could (§8).

type ChangeFact ¶

type ChangeFact struct {
	// Key is the key the fact is written at — `kinds`, `targets`,
	// `destroy`, `capabilities`, `operations`, `cadence`, `target`, `over`,
	// `bound` — or, for the credential source, the slot it belongs to
	// spelled as §8's own `credential <slot>`.
	Key string
	// Step is the id of the Step this fact belongs to, and "" where the
	// subject is the artefact itself. It is the coordinate a flag citing the
	// fact carries, and the identity the two sides of a range are paired on:
	// a Step on one side only has no before-and-after of its own.
	Step string
	// SubjectLine is the line the fact's subject opens on — a Step's own
	// `- id:`, or the artefact's first line where the subject is the
	// artefact. It is the anchor of last resort for a citation, and it is a
	// line the gutter marks on every Step there is (§8).
	SubjectLine int
	// Lines are the lines the fact is written across: the key's own, and
	// each line a member of the value stands on. They are what a citation is
	// chosen from — a flag cites the line carrying its subject, and where a
	// fact spans a block the line that moved is the one carrying it.
	//
	// It is empty where the artefact writes no such key, which is a fact
	// stated by omission and rendered `–` (§8).
	Lines []int
	// Shape is what the value is, which decides both what a row renders and
	// what makes two readings of it differ. It follows the value at the row
	// and never the class above it, which is why it is a member here rather
	// than a fact about the key: the Target set class alone carries a set
	// for a Procedure's envelope and a scalar for the `target:` a Step binds
	// (§8).
	Shape FactShape
	// Members are a set's members or a selector's, in the order a row
	// renders them: sorted by Unicode code point wherever the fact compares
	// as a set, and as authored for a `values:` selector, whose order *is*
	// the fact (§6, §8).
	Members []string
	// Value is a scalar's text as the artefact wrote it, and a selector's
	// form name — `values`, `assets` or `observations`. A cell dropping the
	// form could not tell an `assets` selector from an `observations` one,
	// which is the difference between ranging over what `hyper` built and
	// over what it read (§5, §8).
	Value string
	// Wire is the value as §8's row stream carries it: **the artefact's own
	// parsed shape**, in the order the page renders it, and nil where the
	// artefact states the value by omission — the absence the page renders
	// `–` and the wire states by writing no member at all.
	//
	// It is here rather than composed by a renderer because the page's
	// notation is that chapter's geometry and never a fact either surface
	// states (ADR-0059): a ` · `-separated run and a `field operator
	// operand` line are renderings, and a reader composing the wire out of
	// them would have to parse its own rendering back — and could not, an
	// `in:` list and a bare operand rendering alike once a conjunct is one
	// line of text (fact_wire.go).
	Wire json.RawMessage
}

ChangeFact is one `(subject, fact)` pair as one artefact's own lines carry it: which key it is written at, which subject inside the artefact it belongs to, where it is written, and the value.

A class emits one row per pair rather than one row, so a Definition's claimed Kinds and the `destroy` Operations it names are two facts under one class (§12). The class names are the grouping and reach no screen: what a row names is the key, which is what a reader greps for and what the gutter marks.

func ReadChangeFacts(kind string, root *yaml.Node) []ChangeFact

func (f ChangeFact) Same(other ChangeFact) bool

func (f ChangeFact) Written() bool

type CredentialSlot ¶

type CredentialSlot struct {
	Slot string
	Env  string
	// Line is the 1-indexed line the slot's own key is written on, which is
	// what §8 says `credential-absent` cites: the `env:` line of the Target
	// declaration whose slot the environment did not fill. A row reporting a
	// Target's credentials has never asked for it and does not read it; a
	// Refusal has to, an absence with no coordinate being a search rather
	// than an edit (§8).
	Line int
}

CredentialSlot is one member of a Target declaration's auth: mapping as a surface reports it: the slot the repository named, and the environment variable that slot resolves from. The variable's name and never its value — nothing hyper writes has ever held a secret, and the pair exists so that a declaration carrying slots for more than one scheme says which fills what (§3, §9, ADR-0007).

Env is empty where the slot names no variable, which is a slot whose value is not the mapping whose sole key is env: that §4 fixes. The slot is still a slot the declaration carries, so it is still reported; what is wrong with it is credential-slot-malformed, which is check's to name (ADR-0064).

type DefinitionFacts ¶

type DefinitionFacts struct {
	Kinds   []string
	Destroy []string
	Targets []string
}

DefinitionFacts is what a Definition claims, in the shape a surface reports it: ordered lists rather than the membership sets DefinitionInfo carries.

It is ReadTargetFacts's other end. The two readings are one artefact read for two questions: a check asks *does this Definition claim that Kind*, which is a set, and a row states *what does this Definition claim*, which is an enumeration answered in the file's own order — a claim silently reduced or re-sorted is not the claim the reviewer has open beside it (§3, §5, §8).

Targets is every member of targets: as written, including one that resolves to no declaration. DefinitionInfo.Targets drops those, a check having nothing to check them against; a row may not, a Definition claiming three Targets and rendering two rows saying the third was never claimed (§8, ADR-0064).

Each list is nil where its key is absent, which is the ordinary absence rule a reader reads off it (§7): a Definition claiming no `destroy` Operation carries no destroy: at all.

func ReadDefinitionFacts(root *yaml.Node) DefinitionFacts

type DefinitionIndex ¶

type DefinitionIndex map[string]DefinitionInfo

DefinitionIndex maps a definitions/ file's own definition: to what a Step binding it is checked against — a Step's definition: resolves against this namespace (§3, §4, issue #94).

func BuildDefinitionIndex(definitionRoots []*yaml.Node, targets TargetIndex) DefinitionIndex

type DefinitionInfo ¶

type DefinitionInfo struct {
	ProviderName string
	Kinds        map[string]bool
	Destroy      map[string]bool
	Targets      map[string]TargetInfo
}

DefinitionInfo is what checking a Step against the Definition it binds needs, read once per repository pass rather than reparsed per Step that names it (§3, §4, §5, issue #95): the provider: it names, unresolved — a Step's operation: and args: are checked against a second lookup, into ProviderIndex, once ProviderName has resolved; the Kinds it claims via kinds: — read and/or mutate, the claim half of the two keys; the Operations it claims for destroy:, by name — the same set both operation-not-claimed and the destroy half of ClaimsKind read; and the targets: it claims, resolved against TargetIndex and keyed by name — the namespace a Step's target: resolves against and nothing wider (§4), and the source of the Kinds a Step's bound Target grants.

func (d DefinitionInfo) ClaimsKind(kind string) bool

type DefinitionMarks ¶

type DefinitionMarks struct {
	Kinds, Destroy, Targets KeyMark
}

DefinitionMarks is §8's roster on a Definition: the Kinds it claims, the `destroy` Operations it names, and the Targets it may bind, each beside the line that makes the claim.

All three are authored in the file being read, which is the whole of why a Definition's `provider:` carries no mark: this screen annotates what `hyper` derived from these lines, and nothing it derived reaches a Manifest (§8).

func ReadDefinitionMarks(root *yaml.Node) DefinitionMarks

type FactShape ¶

type FactShape int

FactShape is what a fact's value is, which decides both how a row renders it and what makes two of them differ (§8). It is the shape of the value at the row and never the class above it: the Target set class alone carries a set for a Procedure's envelope and a scalar for the `target:` a Step binds.

const (
	// FactSet is a set of names, comparing by set equality: declared Kinds,
	// a Target set, required Capabilities, the Operations a Manifest
	// exposes, a Definition's `destroy:` claim. It is the shape a direction
	// is decidable on by inclusion, which is why the rule is quantified over
	// the shape rather than listed over the classes (§12).
	FactSet FactShape = iota
	// FactBound is a Step's `bound:`: a magnitude, comparing numerically,
	// and the one scalar a direction is decidable on.
	FactBound
	// FactScalar is a scalar no direction is available for — a Step's
	// `target:` and a credential slot's variable. It takes `changed` and its
	// full before-and-after text.
	FactScalar
	// FactCadence is a Procedure's declared recurrence: a scalar under the
	// shape rule and a stacked cell under the mandatory gloss, which are two
	// rules meeting in one place and neither is the other (§8, §10,
	// ADR-0005, ADR-0063).
	FactCadence
	// FactSelector is a Step's `over:`, in any of its three forms. It takes
	// `changed` however it moved: predicate subsumption is undecidable in
	// general, so a surface calling `equals: preview` → `starts_with:
	// preview-` a widening would be inventing the one thing it may not
	// invent (§12).
	FactSelector
)

type HostReach ¶

type HostReach struct {
	Reach   Reach
	Host    string
	Granted int
}

HostReach is where a call goes, and why it goes nowhere.

Host is the host the call reaches under ReachGranted, and under ReachNotGranted the host it *would* have reached — the value the input carried, or the first candidate the template expanded to — so a Refusal can name what was asked for. It is "" where nothing named one at all, which is `{from-target}` against a grant with nothing in it: the grant is the only thing that could have named a host, and it named none.

Granted is how many hosts the candidate set and the grant intersected to, and is read only under ReachUndecidable, that being the count above one.

func ResolveHost(provider ProviderInfo, operation OperationInfo, target TargetInfo, suppliedHost string) HostReach

type InputInfo ¶

type InputInfo struct {
	Type string
	Enum []string
}

InputInfo is what checking a Step's args: value against one Operation input needs: the type: it declares, read the way an argument's own type is — object and array are the two a reference may never fill (§3, §4) — and the enum: its value is checked against, nil where the input declares none.

type KeyMark ¶

type KeyMark struct {
	Line   int
	Values []string
}

KeyMark is one top-level key's own line and what `hyper` derived from what it carries: the line the key is written on, 0 where the artefact writes no such key, and the derived values in the artefact's own order.

The values are the fact and not the marker: which of them is upper-cased, what stands in front of them and how they are separated is §8's vocabulary and the rendering surface's to compose, exactly as a StepMark's Kind is (§8).

Values is empty on a key that is written and yields nothing — a `hosts:` that is not a list of scalars, an `auth:` naming neither of §12's two schemes. That is a line with no derived fact rather than a fact that is empty, and the two are one thing to every surface: nothing was derived, so nothing is marked.

type ManifestFacts ¶

type ManifestFacts struct {
	AuthScheme    string
	Capabilities  []string
	SchemaVersion *int
	OriginRef     string
	OriginDigest  string
	Operations    []OperationFacts
}

ManifestFacts is what a Manifest declares about itself, in the shape a surface reports it — `hyper provider`'s header row, which exists to state what a Manifest declares (§9).

It is ReadTargetFacts's counterpart and stands beside ProviderInfo for ProviderInfo's own reason: one artefact read for two questions. A check asks *may this Definition bind that Provider*, which is a set of memberships; a row states *what does this Manifest declare*, which is an enumeration and the composition an Auth scheme writes. Neither reading judges the artefact — a Manifest that declares a Capability outside the closed set states what it states here and earns its problem from check (ADR-0064).

AuthScheme is the header the Manifest's scheme composes, with the credential's position marked; the word §12 fixes for a Manifest carrying no auth: block, and "" where it carries one `hyper` cannot read as a scheme — which is a schema fault check names, and not an absence of authentication a row may report as one.

SchemaVersion is a pointer because the Manifest's own schema-version: is an integer and a Manifest that wrote something else has stated no version at all: 0 would be an answer to a question nothing asked, and the ordinary absence rule is what a reader reads off its absence (§7).

OriginRef and OriginDigest are the origin: block's two members, both empty where the block is absent — a built-in Provider and a locally authored Extension alike, which together are the whole of what distinguishes an installed Extension from one an author wrote (ADR-0073).

Operations are in the Manifest's own order, which is the order they were authored in. The normative order a listing is ranged over in is the surface's rule and is applied there: `hyper operation` writes a Manifest's declaring lines back verbatim, so the authored order is preserved exactly where it is the answer (§9).

func ReadManifestFacts(root *yaml.Node) ManifestFacts

type ManifestMarks ¶

type ManifestMarks struct {
	Auth, Capabilities KeyMark
	Operations         []OperationMark
}

ManifestMarks is §8's roster on a Manifest: the Auth scheme it names, the Capabilities its Operations require, and one entry per Operation.

func ReadManifestMarks(root *yaml.Node) ManifestMarks

type OperationDetail ¶

type OperationDetail struct {
	Capabilities      []string
	Bound             string
	PatternsResolved  []string
	RecordCardinality string
	RecordIdentity    string
	Repeatability     string
	Deadline          string
	DeadlineSeconds   *int
	ConcurrencyLimit  int
}

OperationDetail is the derived half of `hyper operation`'s answer: the facts the Manifest's own lines do not carry in that form, computed once here so that no caller re-derives what `hyper` already has (§9).

It stands beside the source rather than instead of it. The source teaches the format a caller is expected to author Definitions in, and this states what reading that format would otherwise cost — which Capability the request is written under, whether a Bound is mandatory, illegal or moot, and the three facts an Operation states by omission.

Capabilities carries the one Capability the Operation's request is written under — an Operation uses exactly one (§12) — and is empty where the request block names neither Capability or names both, which is schema-mismatch from `check` and never a Capability this reader may pick between (ADR-0064).

Bound is one of the three members above, and "" where kind: is not one of the three Kinds: the fact is read off a declared Kind, and there is none to read it off.

PatternsResolved is the members of §12's three-member set the Operation declares, and it is empty rather than nil where it declares none: a caller asking which Patterns run around this call is answered *none of them*, which is a fact, where an absent member would say the question was not asked.

RecordCardinality and RecordIdentity are the record: block's two facts and are both "" where there is no record: — a destroy, which projects no Record of its own. The identity is the identity: scalar verbatim, a template hole and a response path alike.

Repeatability is the effective value and not the declared one: an Operation whose Manifest omits repeatability: gets run-once where it effects and repeatable where it reads (§12, ADR-0037). run-once is rendered even though no artefact may write that word, which makes it exactly parallel to opaque — a fact no artefact declares and every surface renders.

Deadline is the authored spelling, 30s, and DeadlineSeconds is that duration in seconds: §9 fixed the wire name and its unit with it, and the spelling is what a page standing beside the source renders, that being what the source says. DeadlineSeconds is a pointer because 0s is a duration an author can write, so 0 is a value this member must be able to state rather than the absence of one (§7).

ConcurrencyLimit is the effective limit and is always present: the declared concurrency:, or 1 where absent, and 1 on every mutate and destroy, whose Expansion is serial and which may not declare the key at all. A caller asking *how many at once* gets a number for every Operation, and the rule about which Kinds may author the key stays in §3 where authoring rules live, rather than being inferred here from a field that came back empty (ADR-0045).

func ReadOperationDetail(root *yaml.Node, name string) OperationDetail

type OperationFacts ¶

type OperationFacts struct {
	Name    string
	Kind    string
	Opaque  bool
	Summary string
}

OperationFacts is one Operation as a listing reports it: the name the Manifest keys it by, the Kind it declares, whether it is Opaque, and a derived summary (§9).

Kind is read from the Manifest's own kind: and never inferred from the name — an Operation called delete_thing that declares mutate is a mutate (§12). Opaque is not read from the Manifest at all in the sense the other two are: opacity is a property of the Capability the Operation's request uses, so it is read from the request block, and no artefact anywhere declares it (§12).

type OperationInfo ¶

type OperationInfo struct {
	IsShell       bool
	Kind          string
	HasSeries     bool
	RecordFields  map[string]bool
	Inputs        map[string]InputInfo
	Repeatability string
	HasSecret     bool
	SecretFields  map[string]bool
	// HostTemplate is the raw host: scalar an http: block carries — ""
	// on a shell Operation, which has no host: at all — the template
	// whose at-load expansion is the candidate set the bound Target's
	// grant is checked against (§3, ADR-0029, issue #98).
	HostTemplate string
	// HostInput is the raw host-input: scalar — "" where the Operation
	// declares none — naming the one input that carries a whole host
	// where the candidate set and the grant intersect to several, and
	// the position that makes an over: values: list a host list where a
	// Step wires {item: $} into it (§3, §4, issue #98).
	HostInput string
	// Identity is the raw identity: scalar record: carries — "" on a
	// destroy, which projects nothing — read to decide whether an
	// Expansion's members can be shown to project one identity before
	// any call goes out: a template hole or $.command on a shell
	// Operation resolve before the call, and any response path does not
	// (§3, §4, issue #98).
	Identity string
}

OperationInfo is what checking a Step against the Operation it binds needs, read once per repository pass alongside the rest of ProviderInfo rather than reparsed per Step that names it (§3, §4, issue #94): whether its request is the shell Capability, the one hyper's own Provider may declare and the one whose argv arrives as the input named command, and the same fact by which opacity is read rather than declared (§5, §13, issue #95); its own Kind — read, mutate or destroy — the two keys and the Bound both check against; its Record cardinality, series where its record: carries an over: and one otherwise — the fact a reference's step: half is refused against (series-reference); the field names its record: projects, nil on an Operation with no record: at all — the namespace a reference's path: half resolves against; every input its input: schema declares, by name; its own Repeatability, "" where undeclared — the fact IsRunOnce reads, and the two Cadence rules' own walk with it (issue #96); whether its own secret: is present and names at least one field — the other fact that same walk reads; and SecretFields, the field names secret: itself names — the set a predicate's own field: is checked against, nil where secret: is absent (§3, §4, §12, issue #97).

func (o OperationInfo) IsOpaqueDestroy() bool

func (o OperationInfo) IsRunOnce() bool

func (o OperationInfo) SuppliedHost(inputs map[string]schema.Scalar) string

type OperationMark ¶

type OperationMark struct {
	Line          int
	Name          string
	Kind          string
	Repeatability string
	Opaque        bool
}

OperationMark is one member of `operations:` as the gutter marks it, beside the line its key is written on — which is the line that binds the claim, an Operation's body being everything indented beneath its name.

Name is the key itself. It is no part of the mark — the marker stands beside the line the name is written on and would only repeat it — and it is what a flag indexing that line names, a Manifest carrying no coordinate on the wire for the row to be read by (§8, §12).

Kind is what the Manifest declares and is never inferred from the Operation's name (§12), and it is "" where the entry declares none legibly.

Repeatability is the effective value and not the declared one: an Operation whose Manifest omits `repeatability:` is run-once where it effects and repeatable where it reads (§12, ADR-0037). It is the same derivation `hyper operation` renders, so `run-once` — a word no artefact may write — reaches this column exactly as `opaque` does. It is "" where `kind:` is not one of the three, there being no default to read off a Kind the Manifest never stated.

Opaque is whether the Operation's request uses an Opaque Capability, read off the request block because no artefact anywhere declares it (§12).

type ProcedureGraph ¶

type ProcedureGraph map[string]procedureGraphInfo

ProcedureGraph is every procedures/ file's own per-file facts, keyed by the name it declares: the namespace the transitive walk recurses through, and what a review's own gutter reads a nested invocation's transitive envelope off of (§4, §5, §8, issues #96, #120). Its members are unexported because what a caller does with the graph is walk it, never read one file's entry.

func BuildProcedureGraph(roots []ProcedureRoot, providers ProviderIndex, definitions DefinitionIndex) ProcedureGraph

func (g ProcedureGraph) Reaches(name string) ProcedureReach

type ProcedureIndex ¶

type ProcedureIndex map[string]bool

ProcedureIndex maps a procedures/ file's own procedure: to whether it exists — the namespace a nested invocation's procedure: resolves against (§3, §4, issue #94).

func BuildProcedureIndex(procedureRoots []*yaml.Node) ProcedureIndex

type ProcedureMarks ¶

type ProcedureMarks struct {
	EnvelopeLine    int
	EnvelopeTargets []string
	EnvelopeHolds   bool
	Steps           []StepMark
}

ProcedureMarks is what a review derives about a Procedure's own lines — the supply behind §8's marker column, and the facts a reviewer with the file open in a diff cannot see because none of them are in the file: an Operation's Kind is declared in a Manifest two directories away, its opacity is declared nowhere at all, and the envelope check quantifies over every Step's target: at once (§8, issue #120).

It reads and does not judge, on ReadManifestFacts's own rule: a name that resolves to nothing is marked as the absence it is rather than refused, a review not running check and not declining (ADR-0064). Nothing an author wrote is in here either — a comment is source and is read for nothing (§8).

EnvelopeLine is the targets: line the envelope mark stands beside, and 0 where the Procedure declares no targets: at all — there being no line to mark and the missing key being check's to report.

EnvelopeTargets are the Targets that line declares, in the file's own order and as written, including one that resolves to no declaration. It is the envelope the mark is a verdict on, which is what an index of that verdict states rather than restating the verdict (§8, §12): the values are the fact and how they are punctuated is the rendering surface's.

EnvelopeHolds is whether every Step and every nested invocation this reader could derive an envelope contribution from stays inside the declared envelope. The comparisons are envelope-exceeded's — a bound Target outside the declared targets:, and a Kind outside the union those targets accept — together with the transitive half CheckProcedureGraph runs, over the graph that check walks rather than a second derivation of a Procedure's reach.

What it quantifies over is not what check quantifies over, and the difference is a rendering rule rather than a disagreement. checkStepEnvelope reports an out-of-envelope target: whatever else about the Step failed to resolve; this mark reads nothing off a Step it derived nothing else about, §8 fixing that an unresolved Step carries no Kind, no opacity and no envelope contribution. So a Step whose definition: names nothing and whose target: is outside the envelope renders `unresolved` beside `envelope ✓` here and earns envelope-exceeded from check — which is the two surfaces doing their own jobs: check reports what is wrong with the artefact, and a review annotates what hyper derived from these lines (ADR-0026, ADR-0064).

func ReadProcedureMarks(root *yaml.Node, providers ProviderIndex, definitions DefinitionIndex, targets TargetIndex, graph ProcedureGraph) ProcedureMarks

type ProcedureReach ¶

type ProcedureReach struct {
	// Pairs is each (Definition, Target) pair once, in the Steps' own
	// order and a nested invocation's after its caller's — deterministic,
	// so one repository answers one way. The env: block orders itself by
	// variable name and does not read this order (§10); what it needs is
	// that a walk of one repository twice is a walk of one repository.
	//
	// They are store.Pair because they are §6's own noun, and the same
	// pairs a Run's credential pass and the Store's schema test are
	// quantified over — one concept, and the walk that finds them early
	// answers in the type the walk that binds them uses.
	Pairs []store.Pair
	// EveryStepReads is whether every Step reachable from this Procedure
	// declares kind: read — the fact deciding whether its workflow takes
	// the Store's concurrency group. Reachability decides it and not the
	// Procedure's own declared Steps: a read-looking Procedure that
	// invokes an effectful one effects (§10).
	EveryStepReads bool
}

ProcedureReach is what one Procedure reaches, to any depth, that nothing about a single procedures/ file can answer: the pairs its Steps bind, and whether every Step it reaches is a read (§10, issue #176).

Both are the projection's, and both come off the walk the two Cadence rules already ride rather than a traversal of their own: a Procedure's reach is one question, and asking it twice is where the day comes that the env: block and the concurrency group disagree about what a Procedure runs.

type ProcedureRoot ¶

type ProcedureRoot struct {
	File string
	Root *yaml.Node
}

ProcedureRoot pairs one procedures/ file's own relative path with its already-parsed root — what BuildProcedureGraph reads the transitive walk's own per-file facts off of, needing every procedures/ file's own name to know where a citation belongs (§4, §5, issue #96).

type ProviderIndex ¶

type ProviderIndex map[string]ProviderInfo

ProviderIndex maps a Provider's own name — a built-in or a providers/ file's provider: — to what a Definition binding it is checked against. It is the namespace a Definition's provider: resolves against (§4).

func BuildProviderIndex(manifestRoots []*yaml.Node) ProviderIndex

type ProviderInfo ¶

type ProviderInfo struct {
	Class        string
	Capabilities map[string]bool
	Operations   map[string]OperationInfo
	AuthSlots    []string
	RecordFields map[string]bool
	SecretFields map[string]bool
	// Enumerations is the Manifest's own enumerations: block, name to
	// members — the one source a Capability-relevant hole in an
	// Operation's host: may resolve to, and half the candidate set
	// expansion the host grant is checked against (§3, §12, issue #98).
	Enumerations map[string][]string
}

ProviderInfo is what checking a Definition against its bound Provider needs, read once per repository pass rather than reparsed per Definition that binds it (§4, §5): the class its Definitions may bind, the Capabilities its Operations require, the Operations it declares — the namespace a destroy: member and a Step's operation: resolve against — the credential slot names its Auth scheme requires, nil where it authenticates nothing, and RecordFields and SecretFields, the union of every Operation's own two sets of the same name (§3, §4, §12, issue #97). The union rather than one Operation's own set is what a selector's and a condition's field: resolve against: assets:/observations: range over the (Definition, Target) Record series a different Operation of the same Provider may have written — a destroy Step's own Operation projects no record: at all, and its selector still names the fields the mutate that created what it destroys projected.

func (p ProviderInfo) Summary() string

type Reach ¶

type Reach int

Reach is what resolving an invocation's host answered.

const (
	// ReachGranted: the call reaches Host, which the grant admits.
	ReachGranted Reach = iota
	// ReachNotGranted: nothing the call could reach is granted.
	// `host-not-granted` (§4, ADR-0042).
	ReachNotGranted
	// ReachUndecidable: the candidate set and the grant intersect to
	// several hosts under an Operation naming no `host-input:`, so which
	// host the request would reach is not decided by anything. `check`
	// reports this as `manifest-inconsistent` wherever a Step binds the
	// Operation (§4), so a Run reaches it only where `check` has not run;
	// a Probe is a binding no artefact wrote, and reaches it always.
	ReachUndecidable
	// ReachIllegible: the `host:` template writes a hole naming neither
	// `from-target` nor a declared enumeration, which `check` has already
	// refused as `hole-illegal`. There is nothing to expand and so nothing
	// to decide (ADR-0064).
	ReachIllegible
)

type RepositoryDeclarationMarks ¶

type RepositoryDeclarationMarks struct {
	Version, Retention KeyMark
}

RepositoryDeclarationMarks is §8's roster on a Repository declaration: the `hyper` version every Run in this repository is gated on, and the retention policy that bounds Compaction (§3, §11).

The digest beside the pin carries no mark, and the roster is what says so: the two members here are the facts that govern every Run in this repository — what `hyper` it is pinned to, and how long its Records are kept — where the digest is `hyper project`'s own writing about the pin rather than a third thing the repository declares (§11, §12).

func ReadRepositoryDeclarationMarks(root *yaml.Node) RepositoryDeclarationMarks

type RepositoryFacts ¶

type RepositoryFacts struct {
	// Retention is the policy as the artefact spells it, `90d`, and empty
	// where the declaration carries no `retention:` at all.
	//
	// The empty string is the whole of *this repository has agreed to lose
	// nothing*, and it is safe as a sentinel because no duration is empty:
	// §3 admits `<count><unit>` and nothing else, so a key written with no
	// value is a key that declared no policy. That is also the only reading
	// that is safe to get wrong in one direction — a policy read as absent
	// removes nothing (§3, §7).
	Retention string
	// Digest is the released artefact's checksum as the declaration spells
	// it, algorithm inline — `sha256:` and sixty-four hex digits — and
	// empty where the declaration carries none.
	//
	// It is written by `project` and read by `project`: the version pins
	// which release the generated workflow installs and this pins the bytes
	// that release is, literal in the file so that nothing is resolved when
	// the job runs (§11). The schema makes it required, so empty here is a
	// declaration `check` has already refused rather than a state a
	// projection has to have an answer for (§3, ADR-0064).
	Digest string
}

RepositoryFacts is what the Repository declaration says that a command acts on, in the shape a command reads it: the retention policy that bounds Compaction, and the digest the projection freezes.

The version pin is deliberately not here. It is the gate's, and the gate reads `hyper.yaml`'s bytes before the repository is loaded at all — a second reading of one fact through a second door is exactly what §12's opening rule closes (§9, §11, ADR-0020). The digest beside it is not the gate's and never was: `hyper` never hashes itself, and what the digest covers is the released artefact a runner fetches — a fact about the world outside this checkout, read here like any other thing the declaration says (§11, ADR-0020).

It is the third of these readers and stands beside ReadTargetFacts and ReadManifestFacts for their reason: a check asks *is this value well formed*, which is a schema question, and a command asks *what did the repository declare*, which is this. Neither judges — a `retention:` that is not a duration states what it states here and earns its `schema-mismatch` from `check` (ADR-0064).

func ReadRepositoryFacts(root *yaml.Node) RepositoryFacts

type Step ¶

type Step struct {
	// ID is the Step's authored `id:` — what the Journal matches a Step by
	// across Runs, and what the Step table's second column renders (§7, §8).
	ID string
	// Definition, Operation and Target are the binding: the three names a
	// Step resolves against the repository's namespaces. All three are ""
	// on a nested invocation, which binds nothing.
	Definition, Operation, Target string
	// Invocation is the `procedure:` a nested invocation names, and "" on a
	// Step proper. An invocation is not a Step: it writes no Journal file
	// and reaches no Disposition, and its own Steps are Steps of the one
	// Run (§6, §7).
	Invocation string
	// Require is the `require:` a Requirement carries, and nil on both other
	// shapes. It is a Requirement's whole content beside its `id:`: the
	// predicate the Run must satisfy to go on, in the condition's own root —
	// a named earlier Step's Record, `step:` beside `field:` (§3, §12).
	//
	// A Requirement is not a Step either, and on the invocation's own three
	// grounds: it writes no Journal file, none of §12's Dispositions
	// describes one, and it takes no position in the sequence. What it does
	// instead is halt, which is how a Procedure that claims no effectful
	// authority stops a Run (§6, ADR-0116).
	Require *yaml.Node
	// Args are the Step's `args:`, by input name, as authored: a scalar
	// literal, or the mapping a reference is written as. What each may be
	// is §3's, and reading one against the Operation's declared input type
	// is the engine's at the moment the value is needed.
	Args map[string]*yaml.Node
	// Over, When and Bound are the three keys a Step may carry beside its
	// binding: the selector whose Expansion §6 resolves, the condition
	// §6 evaluates before it, and the Bound §5 makes mandatory on a
	// `destroy`. They are held as nodes because nothing here reads them —
	// their presence is what a milestone that has not built one declines
	// on, and their content belongs to the milestone that has.
	Over, When, Bound *yaml.Node
	// Line is where the Step's own entry begins, which is what a Refusal
	// citing this Step points a caret at (§8).
	Line int
}

Step is one member of a Procedure's `steps:` — a Step proper, the nested invocation that shares the sequence with it, or the Requirement that shares it with both, told apart by which of `procedure:`, `require:` and the three binding keys it carries (§3).

Every member is held as it was authored and never as it resolves. `Kind` is not here: a Step's Kind is its Operation's, read off the Manifest, and a Procedure that named one would be declaring an authority its Provider owns (ADR-0025).

func ReadProcedureSteps(root *yaml.Node) []Step

func (s Step) IsInvocation() bool

func (s Step) IsRequirement() bool

type StepMark ¶

type StepMark struct {
	Line        int
	ID          string
	Requirement bool
	Unresolved  bool
	Absent      AbsentName
	Kind        string
	Operation   string
	Bounded     bool
	Bound       string
	Opaque      bool
	Targets     []string
}

StepMark is one entry of a Procedure's steps: as the gutter marks it, in the order the file declares them.

Line is the line the entry opens on, which is the line that binds the claim: a Step's own `- id:`, and a nested invocation's.

ID is the id: the entry declares, "" where it declares none legibly. It is the coordinate a flag citing this line carries — a Step is named by its id: on every surface in the tool — and no part of the mark: the gutter stands beside the line and needs no name for it (§8, §12).

Unresolved is §8's one mark for four absences: a definition:, an operation:, a bound Provider or a nested procedure: that names nothing. It is one name and not four because the gutter marks and does not classify — which name failed is FLAGS' text — and a mark that fired carries nothing else: no Kind to read, no opacity, and no contribution to the envelope check.

Absent is which of those four it was, set exactly where Unresolved is: the key that carried the name, the name itself, and the Provider an Operation was looked for on. It is the classification the gutter does not make and the flag does, and it is carried as the facts rather than as a sentence — what a rendering says about them is the rendering surface's (§8, §12).

Kind is the Operation's declared Kind, read from the Manifest and never inferred from the Operation's name (§12). It is "" on a nested invocation, which invokes no Operation and has no blast radius of its own to declare.

Operation is the operation: the Step names, which resolved: a flag indexing this line names what is being invoked, where the marker beside it carries the Kind that invocation reaches. It is "" on a nested invocation for Kind's own reason.

Bounded is whether the Step declares a bound: at all, whatever its Kind. It is the fact rather than the mark: a mutate Step with none is marked mutate! and a destroy Step with none is bound-missing, a static check's to report, so the rendering of this fact differs by Kind and the reading does not (§4).

Bound is that Bound's value as the Step wrote it, "" where the Step declares none or declares one this cannot read. The two are one key read for two questions — whether a Bound stands behind the Step, and what it says — and a value that would not read is a bound: check's to report and a fact this states nothing about (ADR-0064).

Opaque is whether the Operation's request uses an Opaque Capability, which is read off the request and declared beside no Operation anywhere (§12).

Targets is what the mark binds: the one Target a Step's target: names, as written; or, on a nested invocation, the transitive envelope it reaches, in name order — the envelope §3 states, walked to any depth. It is empty on a Requirement, which reaches nothing.

Requirement is whether the entry is one: a `require:` and an `id:`, binding nothing and invoking nothing. Every other member of the mark is empty on one, and that is the gutter's supply rule holding rather than a roster left short — a Requirement's whole content is authored on the line the reviewer is reading, so there is nothing `hyper` derived for a marker to carry (§8, ADR-0026, ADR-0116).

type TargetDeclarationMarks ¶

type TargetDeclarationMarks struct {
	Kinds, Capabilities, Hosts KeyMark
	Credentials                []KeyMark
	OpaqueDestroy              int
}

TargetDeclarationMarks is §8's roster on a Target declaration: the Kinds it accepts, the Capabilities it grants, the hosts it grants, the environment variable each credential slot resolves from, and the opt-in that admits an `opaque` `destroy` (§4, §8).

Credentials is one entry per member of `auth:`, in the mapping's own order, each carrying the slot's own line and the variable it names. A slot whose value is not the mapping §4 fixes carries no value: the slot is still a line of the file and still renders, and what is wrong with it is `credential-slot-malformed` from `check` (ADR-0064).

OpaqueDestroy is the opt-in's own line where the declaration grants it, and 0 where it writes none or writes the default. The grant is the whole of what is derived there and there is no value beside it, so the line alone is the mark's supply — a declaration writing `opaque-destroy: false` admits exactly what one writing nothing admits, and a mark there would name a grant that was not made.

func ReadTargetDeclarationMarks(root *yaml.Node) TargetDeclarationMarks

type TargetFacts ¶

type TargetFacts struct {
	Hosts        []string
	Kinds        []string
	Capabilities []string
	Credentials  []CredentialSlot
}

TargetFacts is what a Target declaration grants, in the shape a surface reports it: ordered lists rather than the membership sets TargetInfo carries.

The two readings are one artefact read for two questions. A check asks *does this Target grant that host*, which is a set; a row states *what does this Target grant*, which is an enumeration and is answered in the declaration's own order — a grant silently reduced or re-sorted is not the grant the reviewer has open beside it (§3, ADR-0024, ADR-0029).

Hosts is nil where the declaration enumerates no host, which is a Target granting no http: hosts: is the one key here a declaration may leave out, and the ordinary absence rule is what a reader reads off it (§4, §7).

func ReadTargetFacts(root *yaml.Node) TargetFacts

type TargetIndex ¶

type TargetIndex map[string]TargetInfo

TargetIndex maps a Target declaration's own target: to what a Definition binding it is checked against. It is the namespace a Definition's targets: member resolves against (§4).

func BuildTargetIndex(declarationRoots []*yaml.Node) TargetIndex

type TargetInfo ¶

type TargetInfo struct {
	Class         string
	Capabilities  map[string]bool
	AuthSlots     map[string]bool
	Kinds         map[string]bool
	OpaqueDestroy bool
	Hosts         map[string]bool
}

TargetInfo is what checking a Definition against a Target it binds needs: the class it declares, the Capabilities it grants, the credential slot names its auth: mapping supplies, the Kinds it accepts — the grant half of the two keys, a Step's bound Definition supplying the claim — whether it has opted into opaque-destroy: (§3, §4, §5, issue #95), and the granted host set its hosts: enumerates — the comparand both host-not-granted comparisons run against (§3, §4, ADR-0024, ADR-0029, issue #98).

type Touched ¶

type Touched struct {
	// Lines are the working tree's lines the change column marks: a line
	// whose content differs from the baseline, a line that is new, and the
	// line a deletion anchors to. **One mark and not three** — the gutter
	// marks and does not classify, and a direction is `FLAGS`' text (§8).
	Lines map[int]bool
	// Anchors is each removed line's own number in the baseline against the
	// working-tree line its deletion is cited at. It is what lets a flag
	// about a fact the working tree no longer carries cite a line the gutter
	// marked, which is the whole of what a citation is for (§8, §12).
	Anchors map[int]int
}

Touched is one reading of the range over one artefact.

func ReadTouched(baseline, working []string, root *yaml.Node) Touched

func (t Touched) Marked(line int) bool