Documentation
¶
Overview ¶
Package lockfile manages CLI lockfile state: loading, saving, and converting the on-disk format.
Index ¶
- Variables
- type DirectTracker
- type MetadataResolver
- type State
- func (s *State) AllDeps() []dep.Dependency
- func (s *State) File() parserlock.File
- func (s *State) Get(workflowKey string) ([]dep.Dependency, error)
- func (s *State) HasWorkflow(workflowKey string) bool
- func (s *State) OriginalVersion() string
- func (s *State) PruneWorkflows(keep map[string]bool) []string
- func (s *State) Save() error
- func (s *State) Set(ctx context.Context, workflowKey string, deps []dep.Dependency, ...) error
- func (s *State) SetMetadataResolver(meta MetadataResolver)
- func (s *State) WorkflowKeys() []string
Constants ¶
This section is empty.
Variables ¶
var ErrCorruptLockfile = errors.New("lockfile is unreadable")
ErrCorruptLockfile reports that a lockfile exists on disk but cannot be parsed (malformed YAML, unknown fields, or a dependency entry missing a required key). It is distinct from a missing lockfile (legitimately empty) and from a future-version lockfile (ErrFutureVersion). Callers decide recovery policy: prompt to delete and recreate, or fail loudly. Loading must never silently discard an unreadable lockfile and overwrite it.
Functions ¶
This section is empty.
Types ¶
type DirectTracker ¶
type DirectTracker struct {
// contains filtered or unexported fields
}
DirectTracker captures, by dep index, which resolved deps correspond to a workflow's direct uses: refs. Build it from the freshly resolved deps (before any narrowing/normalization mutates dep.Ref), then read the final NWO@Ref direct-key set back with Keys after mutation.
Keys takes the (possibly reassigned) deps slice so callers that swap the slice for an index-aligned copy — e.g. PreserveRefs — still resolve to the post-mutation refs. The index alignment is the contract: every transform between NewDirectTracker and Keys must preserve dep order and length.
Directness is determined by the workflow file's own uses: refs, not by the resolver parent map. A dep that is both a direct use and a composite transitive dep (e.g. actions/setup-go used directly and also pulled in by a composite) has a parent in the parent map but must still be recorded as a workflow-direct pin — otherwise it is perpetually re-flagged as not-pinned.
func NewDirectTracker ¶
func NewDirectTracker(refs []parserlock.ActionRef, deps []dep.Dependency) DirectTracker
NewDirectTracker records which entries of deps match one of the workflow's direct refs, by NWO@Ref, at the deps' current (pre-mutation) refs.
func (DirectTracker) IsDirect ¶ added in v0.0.14
func (t DirectTracker) IsDirect(i int) bool
IsDirect reports whether the dep at index i is a workflow-direct use. Out-of-range indices are treated as transitive (false) so callers can gate ref-rewriting on directness without bounds-checking.
func (DirectTracker) Keys ¶
func (t DirectTracker) Keys(deps []dep.Dependency) map[string]bool
Keys returns the set of workflow-direct NWO@Ref keys, reading each dep's current (post-mutation) Key() from the supplied index-aligned slice.
type MetadataResolver ¶
type MetadataResolver interface {
RepoIDs(ctx context.Context, owner, repo string) (ownerID, repoID int64, err error)
}
MetadataResolver fetches the owner/repo numeric IDs for a NWO. The store needs these to populate the dependencies: section on every write.
type State ¶
type State struct {
// contains filtered or unexported fields
}
State wraps the on-disk dependency lockfile for the current invocation. Save garbage-collects orphan dependencies: entries — entries still referenced by an out-of-scope workflow are preserved, so partial invocations (e.g. `upgrade workflows/foo.yml`) stay noop on unrelated workflows.
State is safe for concurrent use: Set/Save/Get/File/AllDeps/lookupIDs all take the same mutex, allowing parallel pin and upgrade workers to share a single store instance without external synchronization.
func LoadState ¶
func LoadState(repoRoot string, meta MetadataResolver) (*State, error)
LoadState reads the lockfile at repoRoot, returning an empty in-memory file when none exists on disk. A lockfile that exists but cannot be parsed is surfaced as ErrCorruptLockfile rather than being silently treated as empty.
func LoadStateAt ¶
func LoadStateAt(lockfilePath string, meta MetadataResolver) (*State, error)
LoadStateAt reads the lockfile at the given path, returning an empty in-memory file when none exists on disk. Use this when the lockfile lives outside the standard .github/workflows/ location.
func (*State) AllDeps ¶
func (s *State) AllDeps() []dep.Dependency
AllDeps returns every action entry in the lockfile as a Dependency, populated with Tag and Branch inferred from the action's ref field. Order is undefined. Intended for callers that need the union of recorded pins across all workflows (e.g. seeding resolver caches on startup).
func (*State) File ¶
func (s *State) File() parserlock.File
File returns the in-memory parser-level lockfile snapshot. Intended for consumers that drive the workflow-parser diagnostics engine directly and need the whole file (workflow keys + actions metadata) in one shot.
func (*State) Get ¶
func (s *State) Get(workflowKey string) ([]dep.Dependency, error)
Get returns the dependencies recorded for workflowKey (e.g. ".github/workflows/ci.yml"). Returns nil when the workflow has no entry.
func (*State) HasWorkflow ¶
HasWorkflow reports whether the lockfile's workflows{} map already contains an entry for workflowKey. Used by `upgrade --no-onboard` to refuse silently onboarding a previously-untracked workflow during a Dependabot run.
func (*State) OriginalVersion ¶ added in v0.1.0
OriginalVersion returns the version string that was on disk before the lockfile was loaded and migrated. Empty when the file did not exist.
func (*State) PruneWorkflows ¶ added in v0.1.6
PruneWorkflows removes every workflow entry whose key is not in keep and returns the removed keys in sorted order. Dependency entries left orphaned by the removal are not deleted here: Save's existing orphan GC drops any pin no surviving workflow references.
Callers must only pass a keep set derived from a full-directory scan. A partial invocation (an explicit subset of workflow paths) has no authority to decide a workflow is deleted and must not call this.
func (*State) Save ¶
Save persists the lockfile to disk, garbage-collecting orphan action entries (pins referenced by no workflow). When the in-memory file is empty after GC, the on-disk file is removed.
func (*State) Set ¶
func (s *State) Set(ctx context.Context, workflowKey string, deps []dep.Dependency, parentMap map[string][]string, directKeys map[string]bool) error
Set replaces the workflow's direct-dependency entry and upserts the per-action metadata for every pin in the resolved closure. The workflow entry holds only the action refs that appear in the workflow file itself (its direct uses); per-action `uses:` lists encode the transitive graph, so a reader walks from each direct pin to reconstruct the full closure — the npm/cargo lockfile model.
parentMap is the resolver's child → []parent map (Dependency.Key() form: NWO@Ref, without the SHA suffix), as returned by Resolver.ParentMap. Set uses it to build per-action `uses:` lists by inversion. Both sides are translated into canonical pin keys (NWO@Ref:algo-hex).
directKeys is the set of Dependency.Key() values (NWO@Ref) that the workflow file uses directly. It is authoritative for the workflow's direct-pin list: a dep is recorded as workflow-direct iff its key is in directKeys. This correctly handles deps that are both a direct use and a composite-transitive dep (e.g. actions/setup-go used directly and also pulled in by a composite) — such a dep has a parent in parentMap but must still appear in the workflow's direct list. When directKeys is nil, Set falls back to treating any dep with no parent in parentMap as direct.
Resolution of owner/repo numeric IDs happens lazily per NWO and is cached for the lifetime of the store.
func (*State) SetMetadataResolver ¶ added in v0.1.0
func (s *State) SetMetadataResolver(meta MetadataResolver)
SetMetadataResolver sets the resolver used by lookupIDs to fetch owner/repo numeric IDs. This allows loading the lockfile before auth is available, then wiring in the resolver once the API client is ready.
func (*State) WorkflowKeys ¶ added in v0.1.6
WorkflowKeys returns the workflow paths currently recorded in the lockfile's workflows{} map. Order is undefined. Intended for callers that need to reconcile the recorded set against the workflows present on disk.
Source Files