lockfile

package
v2.3.7 Latest Latest
Warning

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

 Go to latest Published: Aug 25, 2026 License: Apache-2.0 Imports: 11 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddOrUpdateAsset 

func AddOrUpdateAsset(lockFilePath string, ast *Asset) error

AddOrUpdateAsset adds or updates an asset in the lock file Replaces any existing asset with the same name@version

func Marshal 

func Marshal(lockFile *LockFile) ([]byte, error)

Marshal converts a lock file to TOML bytes, prefixed with the auto-generated header.

func RemoveAsset 

func RemoveAsset(lockFilePath string, name, version string) error

RemoveAsset removes an asset and all its installations from a lock file

func RenameAsset 

func RenameAsset(lockFilePath string, oldName, newName string) error

RenameAsset renames all entries of an asset in the lock file.

func Write 

func Write(lockFile *LockFile, filePath string) error

Write writes a lock file to a file path

Types

type Asset 

type Asset struct {
	Name         string       `toml:"name"`
	Version      string       `toml:"version"`
	Type         asset.Type   `toml:"type"`
	Clients      []string     `toml:"clients,omitempty"`
	Dependencies []Dependency `toml:"dependencies,omitempty"`

	// Source (one of these will be present)
	SourceHTTP *SourceHTTP `toml:"source-http,omitempty"`
	SourcePath *SourcePath `toml:"source-path,omitempty"`
	SourceGit  *SourceGit  `toml:"source-git,omitempty"`

	// Installation configurations - array of scope installations
	// If empty, asset is installed globally
	Scopes []Scope `toml:"scopes,omitempty"`
}

Asset represents an asset with its metadata, source, and installation configurations (formerly Artifact)

func FindAsset 

func FindAsset(lockFilePath, name string) (*Asset, bool)

FindAsset finds an asset by name in a lock file Returns the asset and true if found, nil and false otherwise

func (*Asset) GetSourceConfig 

func (a *Asset) GetSourceConfig() map[string]any

GetSourceConfig returns the source configuration as a map for generic handling

func (*Asset) GetSourceType 

func (a *Asset) GetSourceType() string

GetSourceType returns the type of source for this asset

func (*Asset) HasInvalidSourceGitRef added in v2.3.3 

func (a *Asset) HasInvalidSourceGitRef() bool

HasInvalidSourceGitRef reports whether the asset carries a source-git ref that is not a pinned 40-hex commit SHA.

func (*Asset) IsGlobal 

func (a *Asset) IsGlobal() bool

IsGlobal returns true if asset is installed globally (no scope restrictions)

func (*Asset) Key 

func (a *Asset) Key() string

Key returns a unique key for the asset (name@version)

func (*Asset) MatchesClient 

func (a *Asset) MatchesClient(clientName string) bool

MatchesClient returns true if the asset is compatible with the given client

func (*Asset) String 

func (a *Asset) String() string

String returns a string representation of the asset

func (*Asset) Validate 

func (a *Asset) Validate() error

Validate validates a single asset

type Dependency 

type Dependency struct {
	Name    string `toml:"name"`
	Version string `toml:"version,omitempty"`
}

Dependency represents a dependency reference

type LockFile 

type LockFile struct {
	LockVersion string  `toml:"lock-version"`
	Version     string  `toml:"version"`
	CreatedBy   string  `toml:"created-by"`
	Assets      []Asset `toml:"assets"`

	// SkippedAssets holds assets that were present in the fetched lock
	// file but excluded from installation because they cannot be
	// processed (a source-git ref that isn't a pinned SHA, say).
	// In-memory only, never serialized. Removed-asset cleanup must
	// treat these as still present: a skipped asset is broken, not
	// removed, and uninstalling it from every client would turn one
	// bad manifest entry into a fleet-wide removal.
	SkippedAssets []Asset `toml:"-"`
}

LockFile represents the complete lock file structure

func Parse 

func Parse(data []byte) (*LockFile, error)

Parse parses a lock file from bytes Supports both new "assets"/"scopes" and old "artifacts"/"repositories" field names

func ParseFile 

func ParseFile(filePath string) (*LockFile, error)

ParseFile parses a lock file from a file path

func (*LockFile) ExtractInvalidSourceGitAssets added in v2.3.3 

func (lf *LockFile) ExtractInvalidSourceGitAssets() []Asset

ExtractInvalidSourceGitAssets moves every asset row whose source-git ref is not a pinned 40-hex commit SHA out of Assets and into SkippedAssets, along with — to a fixpoint — every row left with a dependency that the extraction broke (Validate would reject the whole lock file for the dangling reference).

This is the enforcement point for the ref contract that a real command path actually reaches: source-git is a hand-authored manifest feature (no sx command constructs one), so a bad ref can only be discovered when the resolved lock file is consumed. Extraction lets Validate pass for everything else — one bad entry costs the rows that cannot work without it, instead of failing every consumer's entire install.

A dependency counts as broken by extraction only when an extracted row matched it (same name, and matching version when the dependency pins one) and no surviving row satisfies it. Several versions of a name can coexist, so dropping one version never takes down dependents another still satisfies — and a dependency that was never present in the lock file at all is deliberately left alone: it fails Validate wholesale, exactly as it did before this mechanism existed.

Every extracted row is recorded in SkippedAssets and returned, including rows superseded by a surviving version of the same name: cleanup keys protection off these names, and protection must not depend on whether the surviving version applies to the caller's scope. Messaging surfaces suppress superseded entries instead.

func (*LockFile) GroupByScope 

func (lf *LockFile) GroupByScope() map[string][]*Asset

GroupByScope returns all assets grouped by their scope An asset can appear in multiple scopes

func (*LockFile) Validate 

func (lf *LockFile) Validate() error

Validate validates the entire lock file

func (*LockFile) ValidateDependencies 

func (lf *LockFile) ValidateDependencies() error

ValidateDependencies checks for circular dependencies using DFS

type Scope 

type Scope struct {
	Repo  string   `toml:"repo"`            // Repository URL
	Paths []string `toml:"paths,omitempty"` // Specific paths within repo (if empty, entire repo)
}

Scope represents where an asset is installed within a repository (formerly Repository)

func (*Scope) GetScopeType 

func (s *Scope) GetScopeType() ScopeType

GetScopeType returns the scope type for this scope entry - If paths is empty/nil, it's repo-scoped (entire repository) - If paths has entries, it's path-scoped (specific paths within repository)

func (*Scope) Validate 

func (s *Scope) Validate() error

Validate validates a Scope entry

type ScopeType 

type ScopeType string

ScopeType represents the scope of an installation 

const (
	ScopeGlobal ScopeType = "global"
	ScopeRepo   ScopeType = "repo"
	ScopePath   ScopeType = "path"
)

type ScopedAsset 

type ScopedAsset struct {
	Asset     *Asset
	ScopeDesc string // "Global", repo URL, or "repo:path"
}

ScopedAsset represents an asset with its scope information (formerly ScopedArtifact)

type SourceGit 

type SourceGit struct {
	URL          string `toml:"url"`
	Ref          string `toml:"ref"`
	Subdirectory string `toml:"subdirectory,omitempty"`
}

SourceGit represents a Git repository source for an asset

func (*SourceGit) Validate 

func (s *SourceGit) Validate() error

Validate validates a Git source

type SourceHTTP 

type SourceHTTP struct {
	URL        string            `toml:"url"`
	Hashes     map[string]string `toml:"hashes"`
	Size       int64             `toml:"size,omitempty"`
	UploadedAt *time.Time        `toml:"uploaded-at,omitempty"`
}

SourceHTTP represents an HTTP source for an asset

func (*SourceHTTP) Validate 

func (s *SourceHTTP) Validate() error

Validate validates an HTTP source

type SourcePath 

type SourcePath struct {
	Path string `toml:"path"`
}

SourcePath represents a local path source for an asset

func (*SourcePath) Validate 

func (s *SourcePath) Validate() error

Validate validates a path source

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.