Documentation
¶
Overview ¶
ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION
ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION
ENGMODEL-OWNER-UNIT: FU-SYSTEM-COMPOSITION
Index ¶
- Constants
- func DelegationsByRequirement(composed CompositionResult) map[string][]MaterializedAllocation
- func EnrichBundleFromComposition(bundle model.Bundle, domains ...string) (model.Bundle, error)
- func HasComposition(bundle model.Bundle) bool
- func PathWithin(root, path string) bool
- func QualifiedReferenceDiagnostics(bundle model.Bundle, result CompositionResult) []validate.Diagnostic
- func ResolutionCount() int64
- func ResolveCompositionProjection(bundle model.Bundle) (CompositionProjection, CompositionResult, error)
- func ResolveCompositionProjectionWith(bundle model.Bundle, options ResolutionOptions) (CompositionProjection, CompositionResult, error)
- func WriteCompositionLock(path string, lock CompositionLockDocument) error
- type ComposedSystem
- type CompositionLockDependency
- type CompositionLockDocument
- type CompositionProjection
- type CompositionResult
- func ComposeForGeneration(bundle model.Bundle, given *CompositionResult, options ResolutionOptions) (CompositionResult, error)
- func GenerateCompositionForBundle(bundle model.Bundle, options ResolutionOptions) (CompositionResult, error)
- func GenerateCompositionFromFile(manifestPath string) (CompositionResult, error)
- func GenerateCompositionFromFileWith(manifestPath string, options ResolutionOptions) (CompositionResult, error)
- type ImportedEntityProvenance
- type MaterializedAllocation
- type PublishedProjection
- type PublishedProjectionEntity
- type ResolutionOptions
Constants ¶
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" )
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" )
const CompositionLocalLockFileName = "engmod.lock.local.yml"
CompositionLocalLockFileName receives the resolved lock while workspace replacements are active, so the committed lock never pins unpublished content.
const CompositionLockFileName = "engmod.lock.yml"
const LockEnv = "ENGMOD_LOCK"
LockEnv selects the lock mode: "check" compares with the committed lock and writes nothing; "write" (or unset) writes the lock.
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 ¶
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 ¶
HasComposition reports whether the model declares any subsystems. TRLC-LINKS: REQ-EMG-016 ENGMODEL-LINKS: FU-SYSTEM-COMPOSITION
func PathWithin ¶
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 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