lockfile

Documentation

Overview

Package lockfile loads and validates pawn.lock files.

Index

• Constants
• func MarshalSampctlDependencies(content []byte, packages []Package, generated time.Time) ([]byte, error)
• func MarshalSampctlResources(content []byte, lock *Lock, resources []ResolvedResource) ([]byte, error)
• type Compiler
• type Graph
  • func (g Graph) Dependencies(name string) []string
  • func (g Graph) Names() []string
  • func (g Graph) Roots() []string
• type LoadResult
  • func Load(reg *source.Registry, fsys fsx.FS, path string) (LoadResult, error)
• type Lock
  • func (l *Lock) ByName(name string) (Package, bool)
  • func (l *Lock) Graph() Graph
• type Package
• type PackageSource
• type PlatformArtifact
• type ResolvedResource
• type ResolvedResourceFile

Constants

const (
	CodeParseError             = "pawn-project:lockfile-parse-error"
	CodeInvalidType            = "pawn-project:lockfile-invalid-type"
	CodeSchemaVersionInvalid   = "pawn-project:lockfile-schema-version-unsupported"
	CodeMissingField           = "pawn-project:lockfile-missing-required-field"
	CodeInvalidChecksum        = "pawn-project:lockfile-invalid-checksum"
	CodeInvalidIntegrity       = "pawn-project:lockfile-invalid-integrity"
	CodeInvalidCommit          = "pawn-project:lockfile-invalid-commit"
	CodeInvalidName            = "pawn-project:lockfile-invalid-name"
	CodeInvalidSourceType      = "pawn-project:lockfile-invalid-source-type"
	CodeInvalidKind            = "pawn-project:lockfile-invalid-kind"
	CodeMissingArchiveChecksum = "pawn-project:lockfile-missing-archive-checksum"
	CodeDuplicatePackage       = "pawn-project:lockfile-duplicate-package"
	CodeUnknownDependencyEdge  = "pawn-project:lockfile-unknown-dependency-edge"
	CodeDependencyCycle        = "pawn-project:lockfile-dependency-cycle"
	CodePathTraversal          = "pawn-project:lockfile-path-traversal"
	CodeResourceSchemaInvalid  = "pawn-project:lockfile-resource-schema-unsupported"
	CodeInvalidResource        = "pawn-project:lockfile-invalid-resource"
	CodeDuplicateResource      = "pawn-project:lockfile-duplicate-resource"
	CodeUnknownResourcePackage = "pawn-project:lockfile-unknown-resource-package"
)

Diagnostic codes emitted by Load. Never repurposed once shipped, per the shared engineering baseline's diagnostic-code stability rule.

const (
	KindDependency    = "dependency"
	KindDevDependency = "dev-dependency"
	KindPlugin        = "plugin"
	KindComponent     = "component"
	KindIncludes      = "includes"
	KindFilterscript  = "filterscript"
)

Kind enum values, mirroring the schema.

const (
	SourceTypeGit     = "git"
	SourceTypeArchive = "archive"
	SourceTypeLocal   = "local"
)

Source type enum values, mirroring the schema.

const Source = "pawn-project"

Source is the diagnostic.Source value used for every diagnostic this package produces.

Functions

func MarshalSampctlDependencies

func MarshalSampctlDependencies(
	content []byte,
	packages []Package,
	generated time.Time,
) ([]byte, error)

MarshalSampctlDependencies writes a complete sampctl dependency object.

func MarshalSampctlResources

func MarshalSampctlResources(
	content []byte,
	lock *Lock,
	resources []ResolvedResource,
) ([]byte, error)

MarshalSampctlResources updates only the PawnKit resource extension.

Types

type Compiler

type Compiler struct {
	Vendor   string `json:"vendor"`
	Version  string `json:"version"`
	Checksum string `json:"checksum,omitempty"`
}

Compiler mirrors the schema's "compiler" object.

type Graph

type Graph struct {
	// contains filtered or unexported fields
}

Graph is a read-only view over a Lock's resolved dependency edges.

func (Graph) Dependencies

func (g Graph) Dependencies(name string) []string

Dependencies returns the direct dependency names of name, or nil if name is unknown.

func (Graph) Names

func (g Graph) Names() []string

Names returns every package name, in the lockfile's declared order.

func (Graph) Roots

func (g Graph) Roots() []string

Roots returns package names that no other package in the graph depends on directly — the entry points of the resolved graph.

type LoadResult

type LoadResult struct {
	Lock        *Lock
	Diagnostics []diagnostic.Diagnostic
}

LoadResult contains a lockfile and any content diagnostics.

func Load

func Load(reg *source.Registry, fsys fsx.FS, path string) (LoadResult, error)

Load reads and validates an absolute pawn.lock path. Content problems become diagnostics; filesystem failures return an error.

type Lock

type Lock struct {
	SchemaVersion    int                `json:"schemaVersion"`
	GeneratedAt      string             `json:"generatedAt,omitempty"`
	ManifestChecksum string             `json:"manifestChecksum,omitempty"`
	Compiler         *Compiler          `json:"compiler,omitempty"`
	RuntimeProfile   string             `json:"runtimeProfile,omitempty"`
	Packages         []Package          `json:"packages"`
	Resources        []ResolvedResource `json:"resources,omitempty"`

	// SourcePath is the absolute path this Lock was loaded from.
	SourcePath string `json:"-"`
}

Lock is the decoded, validated form of a pawn.lock file.

func (*Lock) ByName

func (l *Lock) ByName(name string) (Package, bool)

ByName returns the package named name, if present.

func (*Lock) Graph

func (l *Lock) Graph() Graph

Graph builds a Graph view of l's packages. Safe to call on an l with validation diagnostics (e.g. duplicate names): later entries win.

type Package

type Package struct {
	Key               string             `json:"-"`
	Constraint        string             `json:"-"`
	Name              string             `json:"name"`
	Resolved          string             `json:"resolved"`
	Version           string             `json:"version,omitempty"`
	Commit            string             `json:"commit"`
	Source            PackageSource      `json:"source"`
	Checksum          string             `json:"checksum,omitempty"`
	Integrity         string             `json:"-"`
	Kind              string             `json:"kind"`
	Branch            string             `json:"-"`
	Path              string             `json:"-"`
	Transitive        bool               `json:"-"`
	RequiredBy        []string           `json:"-"`
	PlatformArtifacts []PlatformArtifact `json:"platformArtifacts,omitempty"`
	Dependencies      []string           `json:"dependencies,omitempty"`
}

Package is one resolved dependency-graph entry.

type PackageSource

type PackageSource struct {
	Type string `json:"type"`
	URL  string `json:"url"`
}

PackageSource mirrors the schema's "packages[].source" object.

type PlatformArtifact

type PlatformArtifact struct {
	Platform string `json:"platform"`
	URL      string `json:"url,omitempty"`
	Path     string `json:"path,omitempty"`
	Checksum string `json:"checksum,omitempty"`
}

PlatformArtifact mirrors the schema's "packages[].platformArtifacts[]" object.

type ResolvedResource

type ResolvedResource struct {
	Package  string                 `json:"package"`
	Resource string                 `json:"resource"`
	Target   string                 `json:"target"`
	URL      string                 `json:"url"`
	Size     int64                  `json:"size"`
	Checksum string                 `json:"checksum"`
	Archive  string                 `json:"archive"`
	Files    []ResolvedResourceFile `json:"files"`
}

ResolvedResource is a verified package asset for one host target.

type ResolvedResourceFile

type ResolvedResourceFile struct {
	Source      string `json:"source"`
	Destination string `json:"destination"`
	Size        int64  `json:"size"`
	Checksum    string `json:"checksum"`
}

ResolvedResourceFile is one file installed from a resource.