Documentation
¶
Overview ¶
ENGMODEL-OWNER-UNIT: FU-ALLOCATION-TRACE
Package reqlinks computes contract item fingerprints and evaluates the requirement links of a using system against the dependency content it resolved. A contract item is a contract.provides capability (CAP-*) or a contract.assumptions assumption of use (AOU-*), together with the requirements that realize it. The fingerprint covers both, so any change to the item or a realizing requirement makes every link on it suspect, without the child knowing who links it.
Index ¶
- Constants
- func CanonicalItem(item Item) []byte
- func CapabilityRefs(bundle model.Bundle) map[string]string
- func Fingerprint(item Item) string
- func FingerprintVersion(fingerprint string) int
- func ItemsFromBundle(bundle model.Bundle) map[string]Item
- func OutdatedMessage(s LinkStatus) string
- func PublishedItems(bundle model.Bundle, publications ...model.ManifestPublication) map[string]Item
- func RealizedItems(r model.Requirement, refs map[string]string) []string
- func SuspectMessage(s LinkStatus) string
- type Dependency
- type Item
- type Kind
- type LinkStatus
- type Realizer
- type Reason
- type State
Constants ¶
const CanonicalVersion = 1
CanonicalVersion is the version of the canonical form CanonicalItem writes and Fingerprint names in its prefix (decision D17). Any change to the canonical form, a field added, removed, renamed or normalized differently, is a new version: a fingerprint of another version is reported as link.fingerprint_outdated, never compared.
Variables ¶
This section is empty.
Functions ¶
func CanonicalItem ¶
CanonicalItem returns the canonical serialization (version 1) the fingerprint hashes: compact JSON {"item":{id,kind,text,verificationCriteria},"realizers":[...]} with realizers sorted by id, each {id,text,notes,verificationCriteria,verificationMethods,criticality,status}, verificationMethods sorted, every string whitespace-collapsed and trimmed, no HTML escaping and no trailing newline. Tools diff two items through this form. TRLC-LINKS: REQ-EMG-095 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
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 Fingerprint ¶
Fingerprint returns "sha256:v<CanonicalVersion>:<hex>" of CanonicalItem(item). TRLC-LINKS: REQ-EMG-095, REQ-EMG-109 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
func FingerprintVersion ¶
FingerprintVersion returns the canonical-form version a recorded fingerprint names: N for "sha256:vN:<hex>", 0 for the unversioned "sha256:<hex>" of the v0.8.0 pre-releases, -1 when it is no fingerprint. TRLC-LINKS: REQ-EMG-109 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 OutdatedMessage ¶
func OutdatedMessage(s LinkStatus) string
OutdatedMessage describes a link whose recorded fingerprint uses another canonical form than this engine writes (decision D17). TRLC-LINKS: REQ-EMG-109 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 SuspectMessage ¶
func SuspectMessage(s LinkStatus) string
SuspectMessage describes a suspect link: the recorded and current fingerprints and the current text of the item and its realizing requirements. The text at the reviewed version is not part of the pinned dependency; engws review-links resolves it for a before/after diff. TRLC-LINKS: REQ-EMG-097 ENGMODEL-LINKS: FU-ALLOCATION-TRACE
Types ¶
type Dependency ¶
type Dependency struct {
Alias string
Version string
Bundle model.Bundle
Publications []model.ManifestPublication
}
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. 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: the content a fingerprint covers. 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
// Content is the state of the item content alone: unchanged, suspect or
// broken, also for a version_mismatch link (evaluated at the resolved
// version against the recorded fingerprint); empty when the item cannot
// be evaluated.
Content State
Pinned string // pinned.version
Version string // the dependency pin of the alias
Recorded string
Current string
Item *Item
// Reason classifies a child_unpublished or unresolved link; Detail is
// its text for people.
Reason Reason
Detail string
}
LinkStatus is the evaluation of one reqLinks entry. Recorded is the pinned fingerprint, Current the fingerprint of the item in the resolved dependency (empty when it cannot be computed), Item the current 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. A link whose alias is not a declared dependency is child_unpublished; a declared but unresolved one is unresolved; a pin that differs from the manifest dependency version or the resolved version is version_mismatch (Content still holds the content state at the resolved version); an item missing from the dependency is broken; an item that is not a published capability or assumption of use is child_unpublished; otherwise the fingerprints decide unchanged or suspect. TRLC-LINKS: REQ-EMG-097, REQ-EMG-109 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), with the requirement fields the fingerprint covers. 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.
const ( // StateUnchanged: the recorded fingerprint equals the current one. StateUnchanged State = "unchanged" // StateSuspect: the item or a realizing requirement changed since review. StateSuspect State = "suspect" // StateBroken: the child item no longer exists in the pinned version. StateBroken State = "broken" // StateVersionMismatch: pinned.version differs from the dependency pin. 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" // StateFingerprintOutdated: the recorded fingerprint was written in // another canonical form (an older or unknown sha256:vN: version, or the // unversioned form), so it cannot be compared (decision D17). StateFingerprintOutdated State = "fingerprint_outdated" )