Help us shape the future of Go! Take the 2026 Go Developer Survey

reqlinks

package
v0.8.0 Latest Latest
Warning

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

Go to latest
Published: Nov 3, 2026 License: MIT Imports: 11 Imported by: 0

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

View Source
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

func CanonicalItem(item Item) []byte

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

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 Fingerprint

func Fingerprint(item Item) string

Fingerprint returns "sha256:v<CanonicalVersion>:<hex>" of CanonicalItem(item). TRLC-LINKS: REQ-EMG-095, REQ-EMG-109 ENGMODEL-LINKS: FU-ALLOCATION-TRACE

func FingerprintVersion

func FingerprintVersion(fingerprint string) int

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

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

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

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.

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

Jump to

Keyboard shortcuts

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