reqlinks

package
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 4, 2026 License: MIT Imports: 7 Imported by: 0

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func CapabilityRefs

func CapabilityRefs(bundle model.Bundle) map[string]string

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

func ItemMeaning(item Item) []byte

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

func ItemsFromBundle(bundle model.Bundle) map[string]Item

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

func MeaningChanges(before, after Item) []string

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

func PublishedItems(bundle model.Bundle, publications ...model.ManifestPublication) map[string]Item

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

func SameMeaning(before, after Item) bool

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 Kind

type Kind string

Kind is the kind of a contract item.

const (
	// KindCapability is a contract.provides entry of kind capability.
	KindCapability Kind = "capability"
	// KindAssumption is a contract.assumptions assumption of use.
	KindAssumption Kind = "assumption"
)

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(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

func SortedRealizers(in []Realizer) []Realizer

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

func NonItemReason(dep model.Bundle, id string) Reason

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"
)

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL