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

composition

package
v0.6.0 Latest Latest
Warning

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

Go to latest
Published: Oct 30, 2026 License: MIT Imports: 20 Imported by: 0

Documentation

Overview

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION

Index

Constants

View Source
const (
	// LockModeWrite writes engmod.lock.yml (or the local lock in workspace mode).
	LockModeWrite = "write"
	// LockModeCheck compares the resolved lock with engmod.lock.yml and writes nothing.
	LockModeCheck = "check"
)
View Source
const (
	// ModuleCacheReuse reuses a cached module without contacting the
	// registry. Set explicitly it applies in every lock mode; it is also the
	// default except for lock check mode and lock regeneration (see cacheMode).
	ModuleCacheReuse = "reuse"
	// ModuleCacheRefresh re-fetches every registry dependency.
	ModuleCacheRefresh = "refresh"
)
View Source
const CompositionLocalLockFileName = "engmod.lock.local.yml"

CompositionLocalLockFileName receives the resolved lock while workspace replacements are active, so the committed lock never pins unpublished content.

View Source
const CompositionLockFileName = "engmod.lock.yml"
View Source
const LockEnv = "ENGMOD_LOCK"

LockEnv selects the lock mode: "check" compares with the committed lock and writes nothing; "write" (or unset) writes the lock.

View Source
const ModuleCacheEnv = "ENGMOD_MODULE_CACHE"

ModuleCacheEnv selects the module cache mode: "refresh" re-fetches every registry dependency; "reuse" reuses cached modules offline; unset applies the defaults of cacheMode.

Variables

This section is empty.

Functions

func DelegationsByRequirement

func DelegationsByRequirement(composed CompositionResult) map[string][]MaterializedAllocation

DelegationsByRequirement indexes the composition's allocations by requirement. TRLC-LINKS: REQ-EMG-020, REQ-EMG-066 ENGMODEL-LINKS: FU-ALLOCATION-TRACE

func EnrichBundleFromComposition

func EnrichBundleFromComposition(bundle model.Bundle, domains ...string) (model.Bundle, error)

EnrichBundleFromComposition resolves the bundle's composition and returns a copy enriched with the published entities of the given domains; a bundle without composition is returned unchanged. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func HasComposition

func HasComposition(bundle model.Bundle) bool

HasComposition reports whether the model declares any subsystems. TRLC-LINKS: REQ-EMG-016 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION

func PathWithin

func PathWithin(root, path string) bool

PathWithin reports whether path, after resolving symlinks where possible, lies inside root (root itself included). TRLC-LINKS: REQ-EMG-017, REQ-EMG-049

func QualifiedReferenceDiagnostics

func QualifiedReferenceDiagnostics(bundle model.Bundle, result CompositionResult) []validate.Diagnostic

QualifiedReferenceDiagnostics reports every alias::ID reference in the authored model that no selected dependency publication makes visible, once per field path (composition.unpublished_reference). A model without composition has no visible imports, so each of its qualified references is reported. TRLC-LINKS: REQ-EMG-065 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-VALIDATION-ENGINE

func ResolutionCount

func ResolutionCount() int64

ResolutionCount returns how many composition resolutions this process has run. Engine tests use it to prove that one generation call composes once. TRLC-LINKS: REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION

func ResolveCompositionProjection

func ResolveCompositionProjection(bundle model.Bundle) (CompositionProjection, CompositionResult, error)

ResolveCompositionProjection resolves and validates composition for a bundle. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func ResolveCompositionProjectionWith

func ResolveCompositionProjectionWith(bundle model.Bundle, options ResolutionOptions) (CompositionProjection, CompositionResult, error)

ResolveCompositionProjectionWith is ResolveCompositionProjection under explicit workspace and lock modes. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064

func WriteCompositionLock

func WriteCompositionLock(path string, lock CompositionLockDocument) error

WriteCompositionLock writes deterministic generated dependency state. TRLC-LINKS: REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051

Types

type ComposedSystem

type ComposedSystem struct {
	SubsystemID    string
	Dependency     string
	Publication    string
	ModulePath     string
	Version        string
	Dir            string
	Bundle         model.Bundle
	Requirements   model.RequirementsDocument
	PublishedIDs   map[string]bool
	PublishedFacet map[string]string
	Children       []*ComposedSystem
}

ComposedSystem is a resolved system together with its resolved subsystems. ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, DO-ARCHITECTURE-MODEL

type CompositionLockDependency

type CompositionLockDependency struct {
	Alias        string   `yaml:"alias"`
	Path         string   `yaml:"path"`
	Version      string   `yaml:"version"`
	Publications []string `yaml:"publications"`
	Digest       string   `yaml:"digest"`
}

type CompositionLockDocument

type CompositionLockDocument struct {
	SchemaVersion int                         `yaml:"schemaVersion"`
	Dependencies  []CompositionLockDependency `yaml:"dependencies"`
}

CompositionLockDocument is deterministic generated dependency state. TRLC-LINKS: REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051

type CompositionProjection

type CompositionProjection struct {
	Publications []PublishedProjection
	Entities     []PublishedProjectionEntity
}

CompositionProjection is the reusable, read-only projection boundary used by every output format. It never mutates an authored bundle. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func BuildCompositionProjection

func BuildCompositionProjection(result CompositionResult) CompositionProjection

BuildCompositionProjection materializes only direct, explicitly selected dependency publications. Transitive or unexported child data is not exposed. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (CompositionProjection) Domain

func (projection CompositionProjection) Domain(domain string) []PublishedProjectionEntity

Domain returns published entities from one manifest publication facet. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (CompositionProjection) EnrichBundle

func (projection CompositionProjection) EnrichBundle(bundle model.Bundle, domains ...string) model.Bundle

EnrichBundle returns a projection-only copy containing typed published entities. It is intended for native generators after the authored bundle has been validated; unsupported relationships are omitted rather than flattened. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051, REQ-EMG-065

type CompositionResult

type CompositionResult struct {
	Root        *ComposedSystem
	Allocations []MaterializedAllocation
	Provenance  []ImportedEntityProvenance
	Lock        CompositionLockDocument
	Diagnostics []validate.Diagnostic
	// Workspace is the workspace root the dependencies resolved from.
	Workspace string
	// contains filtered or unexported fields
}

CompositionResult is the resolved tree plus materialized allocation trace and diagnostics. ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-ALLOCATION-TRACE

func ComposeForGeneration

func ComposeForGeneration(bundle model.Bundle, given *CompositionResult, options ResolutionOptions) (CompositionResult, error)

ComposeForGeneration returns the composition for a bundle: the caller's result when given, otherwise one fresh resolution with the bundle itself as the root system (so in-memory content, not the files on disk, is checked). A model without composition returns an empty result. TRLC-LINKS: REQ-EMG-066 ENGMODEL-LINKS: FU-ASCIIDOC-GENERATOR, FU-SYSTEM-COMPOSITION

func GenerateCompositionForBundle

func GenerateCompositionForBundle(bundle model.Bundle, options ResolutionOptions) (CompositionResult, error)

GenerateCompositionForBundle resolves the composition of an already loaded bundle: the dependencies are resolved from bundle.ManifestPath's location (workspace, module cache, lock) as in GenerateCompositionFromFileWith, but the root system - its manifest dependencies, composition, contract and every alias::ID reference - is the given bundle, not the files on disk. A caller validating edited content in memory thus gets the diagnostics of that content. TRLC-LINKS: REQ-EMG-065, REQ-EMG-066, REQ-EMG-069 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER

func GenerateCompositionFromFile

func GenerateCompositionFromFile(manifestPath string) (CompositionResult, error)

GenerateCompositionFromFile resolves the system-of-systems rooted at engmod.yml with the workspace and lock modes taken from ENGMOD_WORK and ENGMOD_LOCK. TRLC-LINKS: REQ-EMG-016, REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER, FLOW-MODEL-CHANGE-TO-VERIFIED-ARTIFACTS

func GenerateCompositionFromFileWith

func GenerateCompositionFromFileWith(manifestPath string, options ResolutionOptions) (CompositionResult, error)

GenerateCompositionFromFileWith resolves the system-of-systems rooted at engmod.yml under explicit workspace and lock modes. Lock policy: while workspace replacements are active, engmod.lock.yml is never touched and the resolved lock is written to engmod.lock.local.yml; in check mode nothing is written and, without replacements, the resolved lock is compared with the committed one (composition.lock_missing, lock_invalid, lock_mismatch); otherwise engmod.lock.yml is written. TRLC-LINKS: REQ-EMG-016, REQ-EMG-047, REQ-EMG-048, REQ-EMG-049, REQ-EMG-051, REQ-EMG-063, REQ-EMG-064, REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, FU-MODEL-LOADER, FLOW-MODEL-CHANGE-TO-VERIFIED-ARTIFACTS

func (CompositionResult) DisplayDir

func (r CompositionResult) DisplayDir(dir string) string

DisplayDir names a resolved directory for output that may leave the machine (MCP responses): a module cache entry as module@version, a directory under the workspace root relative to it, anything else by its base name. It never returns an absolute path. TRLC-LINKS: REQ-EMG-069, REQ-EMG-066 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION, CTRL-MCP-PATH-BOUNDARY

type ImportedEntityProvenance

type ImportedEntityProvenance struct {
	QualifiedID string `yaml:"qualifiedId"`
	Alias       string `yaml:"alias"`
	ModulePath  string `yaml:"path"`
	Version     string `yaml:"version"`
	SourceModel string `yaml:"sourceModelId"`
	Publication string `yaml:"publicationId"`
	Domain      string `yaml:"domain"`
	SourceID    string `yaml:"sourceId"`
	ResolvedDir string `yaml:"resolvedDirectory"`
}

ImportedEntityProvenance records where each visible imported identifier came from without leaking composition metadata into generic target properties. TRLC-LINKS: REQ-EMG-047, REQ-EMG-049, REQ-EMG-051

type MaterializedAllocation

type MaterializedAllocation struct {
	System            string // owning (parent) system id
	Requirement       string
	Subsystem         string
	Target            string // public id within the subsystem
	TargetRef         string // the subsystem requirement that realizes the target (its contract ref)
	Resolved          bool   // target is published in the subsystem contract
	TargetRefResolved bool   // TargetRef names a requirement that exists in the subsystem
	Note              string
}

MaterializedAllocation is a parent->subsystem allocation with its composed-view resolution status. ENGMODEL-LINKS: FU-ALLOCATION-TRACE, CTRL-TRACEABILITY-COVERAGE

func MaterializeAllocations

func MaterializeAllocations(sys *ComposedSystem) []MaterializedAllocation

MaterializeAllocations walks the tree and produces the parent->subsystem allocation trace, resolving each target against the referenced subsystem's published contract. The subsystem models are never modified. TRLC-LINKS: REQ-EMG-020, REQ-EMG-025 ENGMODEL-LINKS: FU-ALLOCATION-TRACE, CTRL-TRACEABILITY-COVERAGE

type PublishedProjection

type PublishedProjection struct {
	Alias       string
	Publication string
	ModulePath  string
	Version     string
	SourceModel string
	Entities    []PublishedProjectionEntity
}

PublishedProjection groups the entities selected from one dependency publication. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

type PublishedProjectionEntity

type PublishedProjectionEntity struct {
	QualifiedID string
	SourceID    string
	Domain      string
	Facet       string
	Value       any
	Source      *model.Bundle
	Provenance  ImportedEntityProvenance
}

PublishedProjectionEntity is one explicitly published dependency entity, retaining its typed value, qualified identity, source bundle, and provenance. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

func (PublishedProjectionEntity) QualifyList

func (entity PublishedProjectionEntity) QualifyList(refs []string) []string

QualifyList qualifies each reference that the entity's publication makes visible with its dependency alias and drops the others. TRLC-LINKS: REQ-EMG-050, REQ-EMG-051

type ResolutionOptions

type ResolutionOptions struct {
	Workspace string
	Lock      string
	// ModuleCache is "refresh" to re-fetch every registry dependency into
	// the module cache, or "reuse"; empty falls back to ENGMOD_MODULE_CACHE.
	ModuleCache string
}

ResolutionOptions overrides the ENGMOD_WORK and ENGMOD_LOCK environment for one call. Empty fields fall back to the environment. Workspace is "off" or a workspace file path; Lock is "check" or "write". TRLC-LINKS: REQ-EMG-063, REQ-EMG-064

Jump to

Keyboard shortcuts

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