Documentation
¶
Overview ¶
ENGMODEL-OWNER-UNIT: FU-ALLOCATION-TRACE
Package reqlinks evaluates the requirement links of a using system against the dependency content it resolved, and compares the meaning of a contract item between two versions. A contract item is a contract.provides capability (CAP-*) or a contract.assumptions assumption of use (AOU-*), together with the requirements that realize it. A link records the dependency version it was reviewed at (decision D23): published versions are immutable, so the pinned version is the review record, and engws bump compares the item's meaning between the pinned and the new version.
Index ¶
- func CapabilityRefs(bundle model.Bundle) map[string]string
- func ItemMeaning(item Item) []byte
- func ItemsFromBundle(bundle model.Bundle) map[string]Item
- func MeaningChanges(before, after Item) []string
- func PublishedItems(bundle model.Bundle, publications ...model.ManifestPublication) map[string]Item
- func RealizedItems(r model.Requirement, refs map[string]string) []string
- func SameMeaning(before, after Item) bool
- type Dependency
- type Item
- type Kind
- type LinkStatus
- type Realizer
- type Reason
- type State
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CapabilityRefs ¶
CapabilityRefs maps each requirement a capability names in its deprecated contract ref to that capability, as RealizedItems expects. Imported alias::ID entries are skipped. TRLC-LINKS: REQ-EMG-091, REQ-EMG-105 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func ItemMeaning ¶ added in v0.9.0
ItemMeaning returns the meaning of a contract item as compact JSON {"item":{id,kind,text,verificationCriteria},"realizers":[{id,text,verificationCriteria}...]} with realizers sorted by id, every string whitespace-collapsed and trimmed, no HTML escaping and no trailing newline. The text of a capability is its note. A realizer's status, notes, criticality, verification methods, title, rationale, appliesTo, priority and tags are not part of it: they do not change what the item obliges (D23). TRLC-LINKS: REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func ItemsFromBundle ¶
ItemsFromBundle returns every contract item of a model by local ID: each contract.provides capability and each assumption of use, with the requirements that realize it in requirement order. Interface entries are not contract items. A capability's deprecated ref counts as a realizer. TRLC-LINKS: REQ-EMG-091, REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func MeaningChanges ¶ added in v0.9.0
MeaningChanges names each difference in meaning between two versions of an item: "item kind", "item text", "item verificationCriteria", then per realizer by ID "<ID> added", "<ID> removed", "<ID> text" or "<ID> verificationCriteria"; nil when the meaning is the same. TRLC-LINKS: REQ-EMG-095, REQ-EMG-100 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func PublishedItems ¶
PublishedItems is ItemsFromBundle limited to what the publications expose: items selected in a publication's architecture list, each with only the realizing requirements selected in a publication's requirements list. A using system fingerprints this view, so it sees what it resolved and nothing the child keeps private. TRLC-LINKS: REQ-EMG-092, REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func RealizedItems ¶
func RealizedItems(r model.Requirement, refs map[string]string) []string
RealizedItems returns the contract item IDs a requirement realizes: its realizes entries plus the capability whose deprecated ref names it (refs maps a requirement ID to that capability), without duplicates. TRLC-LINKS: REQ-EMG-090, REQ-EMG-091 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func SameMeaning ¶ added in v0.9.0
SameMeaning reports whether two versions of a contract item have the same meaning (ItemMeaning). TRLC-LINKS: REQ-EMG-095, REQ-EMG-100 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
Types ¶
type Dependency ¶
type Dependency struct {
Alias string
Version string
Bundle model.Bundle
Publications []model.ManifestPublication
Local bool
}
Dependency is one resolved dependency as a using system sees it: its alias, the version it resolved, its model and the publications selected from it. Local is set when it resolved from a workspace replacement (a checkout, not the published version). TRLC-LINKS: REQ-EMG-097 ENGMODEL-LINKS: FU-ALLOCATION-TRACE, FU-SYSTEM-COMPOSITION
type Item ¶
type Item struct {
ID string
Kind Kind
Text string
VerificationCriteria string
Realizers []Realizer
}
Item is a contract item with its realizing requirements. TRLC-LINKS: REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
type LinkStatus ¶
type LinkStatus struct {
ID string
Parent string
Child string
Alias string
ItemID string
State State
Status string // review status: claimed or accepted
Pinned string // pinned.version
Version string // the dependency pin of the alias
Item *Item
// Local is set when the dependency resolved from a workspace replacement.
Local bool
// Reason classifies a child_unpublished, unresolved or local link;
// Detail is its text for people.
Reason Reason
Detail string
}
LinkStatus is the evaluation of one reqLinks entry: its state, review status (claimed or accepted), the pinned version, the dependency pin and the item at the dependency pin (nil when it is not a published item). TRLC-LINKS: REQ-EMG-097 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func EvaluateLinks ¶
func EvaluateLinks(system model.Bundle, deps []Dependency) []LinkStatus
EvaluateLinks evaluates every reqLinks entry of system against the resolved dependencies, in link order, without comparing content (D23). A link whose alias is not a declared dependency is child_unpublished; a declared but unresolved one is unresolved; an item missing from a published dependency is broken and one that is not a published capability or assumption of use child_unpublished (local for a workspace replacement, which is never reported); otherwise a pin that differs from the manifest dependency version or the resolved version is version_mismatch, else unchanged. TRLC-LINKS: REQ-EMG-097 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func (LinkStatus) NeedsReview ¶ added in v0.9.0
func (s LinkStatus) NeedsReview() bool
NeedsReview reports whether a link needs a person: version_mismatch, broken or claimed. TRLC-LINKS: REQ-EMG-097, REQ-EMG-101 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
type Realizer ¶
type Realizer struct {
ID string
Text string
Notes string
VerificationCriteria string
VerificationMethods []string
Criticality string
Status string
}
Realizer is a requirement that names a contract item in realizes (or, for one release, the requirement a capability names in its deprecated ref). Text and VerificationCriteria are its meaning; the other fields are shown in reviews and the trace but never compared (D23). TRLC-LINKS: REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func SortedRealizers ¶
SortedRealizers returns a copy of realizers sorted by ID. TRLC-LINKS: REQ-EMG-097, REQ-EMG-105, REQ-EMG-107
type Reason ¶
type Reason string
Reason says why a link is child_unpublished or unresolved, or why a contract ID of a resolved dependency is no link target ("" otherwise).
const ( // ReasonNone: the state needs no reason. ReasonNone Reason = "" // ReasonUndeclaredAlias: the child is not alias::ID of a declared dependency. ReasonUndeclaredAlias Reason = "undeclared_alias" // ReasonUnresolved: the dependency is declared but was not resolved. ReasonUnresolved Reason = "unresolved" // ReasonNotInPublication: the item exists but no selected publication exposes it. ReasonNotInPublication Reason = "not_in_publication" // ReasonNotContractItem: the ID is a contract entry that is not a // capability or assumption of use (an interface, a requires entry). ReasonNotContractItem Reason = "not_contract_item" // ReasonMissing: the dependency has no contract entry with the ID. ReasonMissing Reason = "missing" )
func NonItemReason ¶
NonItemReason says why id is no published contract item of a resolved dependency: ReasonNotInPublication when it is a capability or assumption of use (or a capability entry) no selected publication exposes, ReasonNotContractItem when it is a contract entry of another kind (an interface, a requires entry), ReasonMissing when the dependency declares no contract entry with that ID. Callers have already checked that id is not published. TRLC-LINKS: REQ-EMG-097, REQ-EMG-104 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
type State ¶
type State string
State is the evaluated state of one requirement link. A link is never compared with the content of the item at check time (decision D23): the pinned version is the review record, and engws bump compares meanings between versions.
const ( // StateUnchanged: the pin equals the dependency pin and the item is a // published contract item there. StateUnchanged State = "unchanged" // StateBroken: the child item does not exist at the dependency pin. StateBroken State = "broken" // StateVersionMismatch: pinned.version differs from the dependency pin: // the link was reviewed at another version and needs review at this one. StateVersionMismatch State = "version_mismatch" // StateChildUnpublished: the child exists but is not a published contract // item, or names no declared dependency alias. StateChildUnpublished State = "child_unpublished" // StateUnresolved: the dependency is declared but was not resolved, so the // link cannot be evaluated. StateUnresolved State = "unresolved" // StateLocal: the dependency resolved from a workspace replacement and // the item is not a published contract item of that checkout; a local // checkout is work in progress, so nothing is reported (D23). StateLocal State = "local" )