Documentation
¶
Overview ¶
Package requiredfield owns the stored-value audit that admits a field becoming required. Planners detect the fields a schema change newly requires, and migration runners and development synchronization inspect stored documents with the same rule, so a missing value stops the schema change instead of surfacing later in a read or an unrelated edit.
A block definition is compared once: a field it newly requires is one requirement, checked in every stored block of the definition, however many placements the block graph gives it.
Index ¶
- Constants
- func Addresses(requirements []Requirement) []migration.RequiredFieldAddress
- func Missing(field schema.Field, value store.Value) bool
- func Payload(requirements []Requirement) migration.AuditRequiredValuesPayload
- func Risks(requirements []Requirement) []migration.Risk
- type Audit
- type Finding
- type Group
- type MissingValuesError
- type Renames
- type Requirement
- type Scope
- type Step
Constants ¶
const Code = "RIDU_REQUIRED_VALUES_MISSING"
Code is the stable error code of a refused required-field change.
const RiskCode = "RIDU_REQUIRED_FIELD_AUDIT"
RiskCode identifies the planned audit in a migration's review findings.
const StepName = "audit stored values of newly required fields"
StepName labels the planned audit step.
Variables ¶
This section is empty.
Functions ¶
func Addresses ¶
func Addresses(requirements []Requirement) []migration.RequiredFieldAddress
Addresses returns the audit step payload addresses of requirements.
func Missing ¶
Missing reports whether a value fails a required field the way write validation does: absent or null, an empty string for string-valued kinds, and an empty list for list-valued kinds.
func Payload ¶
func Payload(requirements []Requirement) migration.AuditRequiredValuesPayload
Payload returns the audit step payload of requirements.
func Risks ¶
func Risks(requirements []Requirement) []migration.Risk
Risks returns one review finding per requirement.
Types ¶
type Audit ¶
type Audit struct {
// contains filtered or unexported fields
}
Audit counts the stored documents in which each requirement has no value. Adapters feed it every stored row that must be complete; a document stored in several rows, such as a working and a published row, counts once.
func NewAudit ¶
func NewAudit(requirements []Requirement) *Audit
NewAudit prepares an audit of requirements.
type Finding ¶
type Finding struct {
Address string
// Locale is set when a translation exists but is empty, or when a
// localized container's translation lacks the field.
Locale schema.LocaleCode
// EveryLocale is set when a localized field has no translation at all.
EveryLocale bool
Documents int
// Samples are up to five of those documents' IDs.
Samples []string
}
Finding is one newly required field, in one locale when it is localized, that stored documents leave without a value.
type Group ¶
type Group struct {
Resource schema.Collection
Requirements []Requirement
Roots []schema.Field
}
Group is the requirements of one resource with the distinct top-level fields an audit must read to inspect them.
func Groups ¶
func Groups(requirements []Requirement) []Group
Groups orders requirements by resource, preserving their order. An unanchored requirement joins the group of every resource that places its definition, reading the top-level fields that can hold its blocks.
type MissingValuesError ¶
MissingValuesError refuses a schema change that would require a field that stored documents leave without a value.
func (*MissingValuesError) Error ¶
func (failure *MissingValuesError) Error() string
type Renames ¶
type Renames struct {
Resources map[schema.StableID]schema.StableID
Fields map[schema.StableID]schema.Field
Blocks map[string]map[schema.StableID]schema.Field
}
Renames binds confirmed renames so a renamed field keeps its requiredness. Resources maps a before resource ID to its after ID; Fields maps an after field ID to the before field whose content it keeps, and Blocks does the same for the definition-relative IDs of each block definition's fields.
type Requirement ¶
type Requirement struct {
// Resource is the anchor, or the zero value for an unanchored requirement.
Resource schema.Collection
// Steps lead from the anchor to Field, whose name is the last step.
Steps []Step
// Field is the required field as the after schema declares it.
Field schema.Field
Scope Scope
// contains filtered or unexported fields
}
Requirement is one stored field that the after schema requires where the before schema did not. An anchored requirement names a resource and a path from its fields; an unanchored one starts with a descent to a block definition and holds in every stored block of it.
func Detect ¶
func Detect(before, after schema.Snapshot, renames Renames) []Requirement
Detect lists the stored fields that after requires and before did not: fields made required, required fields added to existing resources or containers, required fields whose stored kind or localization changed, and every required field of a resource that stops deferring drafts. A new resource, field container or block type holds no stored values yet, so its fields need no audit. Embedded plugin payloads keep their own evolution rules.
Each resource's own fields are compared, then each block definition placed before and after the change beneath a surviving resource, once in each of its localization scopes. Blocks stored beneath a container whose stored shape changes are all newly constrained; that container contributes one requirement per required field of each definition placed beneath it.
func Resolve ¶
func Resolve(after schema.Snapshot, addresses []migration.RequiredFieldAddress) ([]Requirement, error)
Resolve locates audit payload addresses in an artifact's after manifest.
func (Requirement) Address ¶
func (requirement Requirement) Address() string
Address is the requirement's public address: posts.seo.title for a resource field, or block hero.heading for a field of every hero block.
func (Requirement) Anchored ¶
func (requirement Requirement) Anchored() bool
Anchored reports whether the requirement names one resource.
func (Requirement) Path ¶
func (requirement Requirement) Path() string
Path is the requirement's canonical path from its anchor.
func (Requirement) TopLevel ¶
func (requirement Requirement) TopLevel() bool
TopLevel reports a requirement on a resource's own top-level field.
type Scope ¶
type Scope string
Scope limits a requirement's first descent to blocks stored beneath a localized ancestor, or to the others. A definition is compared once for each of the two, and its fields' localization differs only between them.
const ( ScopeAll Scope = "" ScopeLocalized Scope = migration.RequiredScopeLocalized ScopeUnlocalized Scope = migration.RequiredScopeUnlocalized )
Source Files