bau/lock

Search:
Group by:

Reads, writes, and verifies reproducible Bau dependency lockfiles.

Types

DependencyEdge = object
  name*: string              ## Required dependency name.
  requirement*: string       ## Required version expression.
  package*: string           ## Resolved package key, when known.
  optional*: bool            ## Whether the edge is optional.
Dependency edge from one package to another. 
DependencyReq = object
  name*: string              ## Dependency name from configuration.
  requirement*: string       ## Version requirement, if any.
  source*: string            ## Canonical source URI.
  registry*: string          ## Configured source or registry name.
  url*: string               ## Git URL, if configured.
  path*: string              ## Local path, if configured.
  tag*: string               ## Git tag, if configured.
  branch*: string            ## Git branch, if configured.
  rev*: string               ## Exact Git revision, if configured.
  optional*: bool            ## Whether the dependency is optional.
  enabledBy*: seq[string]    ## Features that can enable this dependency.
  workspaceMember*: string   ## Workspace member that declared the requirement.
Root dependency requirement captured in a lockfile. 
LockDiagnostic = object
  kind*: LockDiagnosticKind  ## Stable diagnostic kind.
  packageName*: string       ## Related package name, when applicable.
  path*: string              ## Related file or directory path.
  message*: string           ## Human-readable diagnostic message.
One lock validation diagnostic. 
LockDiagnosticKind = enum
  ldkMissingLock = "missing-lock", ## Lockfile is absent.
  ldkInvalidLock = "invalid-lock", ## Lockfile cannot be parsed or has wrong version.
  ldkStaleRequirements = "stale-requirements", ## Configuration no longer matches lock requirements.
  ldkMissingDependency = "missing-dependency", ## Required direct dependency is absent from the lock.
  ldkMissingMaterial = "missing-material", ## Locked materialized files are missing.
  ldkChecksumMismatch = "checksum-mismatch", ## Materialized files do not match the lock checksum.
  ldkRevisionMismatch = "revision-mismatch", ## Materialized Git revision differs from the lock.
  ldkUnmaterialized = "unmaterialized" ## Required direct dependency was not materialized.
Machine-readable lock validation issue kind. 
LockFile = object
  version*: int              ## Lockfile format version.
  resolver*: string          ## Resolver implementation that produced the lock.
  requirementsHash*: string  ## Hash of root dependency requirements.
  workspaceMembers*: seq[string] ## Workspace members covered by the lock.
  rootDependencies*: seq[DependencyReq] ## Direct requirements captured in the lock.
  packages*: OrderedTable[string, ResolvedPackage] ## Locked packages keyed by identity string.
Parsed or generated Bau lockfile content. 
LockProject = object
  path*: string              ## Project path relative to the workspace root.
  projectDir*: string        ## Absolute project directory.
  cfg*: BauConfig            ## Effective project configuration.
Workspace project included in lock generation. 
LockValidationReport = object
  ok*: bool                  ## True when no diagnostics were produced.
  messages*: seq[string]     ## Human-readable diagnostic messages.
  diagnostics*: seq[LockDiagnostic] ## Structured diagnostics.
Result of validating a Bau lockfile. 
PackageId = object
  name*: string              ## Package name.
  version*: string           ## Resolved package version.
  source*: string            ## Canonical source URI.
Identity of one resolved package. 
ResolvedPackage = object
  id*: PackageId             ## Package identity.
  dependencies*: seq[DependencyEdge] ## Dependencies declared by the package.
  revision*: string          ## Git revision, when available.
  checksum*: string          ## Content checksum for materialized package files.
  path*: string              ## Workspace-relative materialized path.
  direct*: bool              ## True when declared directly by a workspace member.
  optional*: bool            ## True when all direct requirements are optional.
  enabledBy*: seq[string]    ## Features that enable this package.
  materialized*: bool        ## True when package files were present locally.
  lockedAt*: int             ## Unix timestamp when the materialized package was locked.
Fully or partially resolved package lock entry. 
ResolveGraph = object
  resolver*: string          ## Resolver implementation name.
  requirementsHash*: string  ## Hash of root dependency requirements.
  workspaceMembers*: seq[string] ## Workspace members included in the graph.
  rootDependencies*: seq[DependencyReq] ## Direct requirements from projects.
  packages*: OrderedTable[string, ResolvedPackage] ## Resolved packages keyed by identity string.
In-memory dependency graph before lockfile emission. 
SourceId = object
  uri*: string               ## Canonical URI including source kind prefix.
Stable source identity used in lock entries. 
SourceKind = enum
  skRegistry = "registry",  ## Registry source such as Nimble.
  skGit = "git",            ## Git source.
  skPath = "path",          ## Local path dependency.
  skVendor = "vendor",      ## Vendor directory source.
  skMirror = "mirror"        ## Local registry or mirror source.
Dependency source category encoded into lock metadata. 
SourceProvider = object
  name*: string              ## Source name from configuration.
  kind*: SourceKind          ## Source category.
  uri*: string               ## Canonical source URI.
  replaceWith*: string       ## Replacement source name, if configured.
Resolved source definition used to identify packages.

Consts

DefaultResolver = "atlas-bridge"
Default resolver identifier written to locks. 
LockFileName = "bau.lock"
Filename used for Bau dependency locks. 
LockFileVersion = 2
Current lockfile format version.

Procs

proc buildResolveGraph(projects: openArray[LockProject]; workspaceRoot: string): ResolveGraph {.
    ...raises: [ValueError, OSError, KeyError, Exception, IOError], tags: [
    TimeEffect, ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect,
    WriteDirEffect, ReadEnvEffect, ExecIOEffect], forbids: [].}
Build a dependency graph from configured projects and materialized packages. 
proc checksumPath(path: string): string {.
    ...raises: [IOError, OSError, ValueError],
    tags: [ReadDirEffect, ReadIOEffect, RootEffect], forbids: [].}
proc generateLockFile(cfg: BauConfig; projectDir: string = ""): LockFile {.
    ...raises: [OSError, ValueError, KeyError, Exception, IOError], tags: [
    TimeEffect, ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect,
    WriteDirEffect, ReadEnvEffect, ExecIOEffect], forbids: [].}
Generate a lockfile for a single project configuration. 
proc generateLockFile(projects: openArray[LockProject]; workspaceRoot: string): LockFile {.
    ...raises: [ValueError, OSError, KeyError, Exception, IOError], tags: [
    TimeEffect, ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect,
    WriteDirEffect, ReadEnvEffect, ExecIOEffect], forbids: [].}
Generate a lockfile for a workspace project set. 
proc gitRevision(path: string): string {....raises: [OSError, IOError, ValueError], tags: [
    ReadDirEffect, ExecIOEffect, ReadEnvEffect, RootEffect, ReadIOEffect,
    TimeEffect], forbids: [].}
proc initLockFile(): LockFile {....raises: [], tags: [], forbids: [].}
Return an empty lockfile using the current format version. 
proc initResolveGraph(): ResolveGraph {....raises: [], tags: [], forbids: [].}
Return an empty dependency resolution graph. 
proc lockIdentity(provider: SourceProvider; dep: DepInfo): SourceId {.
    ...raises: [], tags: [], forbids: [].}
Build the canonical source identity for a dependency and provider. 
proc lockIsValid(cfg: BauConfig; lockPath: string; projectDir: string = ""): bool {.
    ...raises: [OSError, Exception, ValueError, KeyError, IOError], tags: [
    ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect, ExecIOEffect,
    ReadEnvEffect, TimeEffect], forbids: [].}
Return true when a single-project lockfile validates successfully. 
proc lockIsValid(projects: openArray[LockProject];
                 workspaceRoot, lockPath: string): bool {.
    ...raises: [Exception, ValueError, OSError, KeyError, IOError], tags: [
    ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect, ExecIOEffect,
    ReadEnvEffect, TimeEffect], forbids: [].}
Return true when a workspace lockfile validates successfully. 
proc packageMaterialPath(workspaceRoot: string; pkg: ResolvedPackage): string {.
    ...raises: [], tags: [], forbids: [].}
Return the absolute materialized package path for a resolved package. 
proc parseLockFile(path: string): LockFile {.
    ...raises: [IOError, OSError, TomlError, ValueError, KeyError, Exception],
    tags: [ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect], forbids: [].}

Parse a Bau lockfile from disk.

Missing files return an empty lockfile; unsupported versions raise.

proc readNimbleVersion(depPath, name: string): string {....raises: [IOError],
    tags: [ReadDirEffect, ReadIOEffect], forbids: [].}
Read a dependency version from a .nimble file when available. 
proc requirementsHash(projects: openArray[LockProject]; workspaceRoot: string): string {.
    ...raises: [ValueError, OSError, KeyError], tags: [], forbids: [].}
Hash dependency requirements that should invalidate a lock when changed. 
proc sourceProvider(name: string; info: SourceInfo): SourceProvider {.
    ...raises: [], tags: [], forbids: [].}
Convert configured source info into a source provider descriptor. 
proc toLockFile(graph: ResolveGraph): LockFile {....raises: [], tags: [],
    forbids: [].}
Convert an in-memory resolve graph to lockfile content. 
proc toString(id: PackageId): string {....raises: [], tags: [], forbids: [].}
Format a package identity as the stable lock-table key. 
proc toString(pkg: ResolvedPackage): string {....raises: [], tags: [], forbids: [].}
Format a resolved package identity as the stable lock-table key. 
proc unresolvedLockEntries(cfg: BauConfig; lock: LockFile; projectDir: string): seq[
    string] {....raises: [], tags: [], forbids: [].}
Return non-optional dependencies that are missing resolved material. 
proc validateLockFile(cfg: BauConfig; projectDir, lockPath: string): LockValidationReport {.
    ...raises: [OSError, Exception, ValueError, KeyError, IOError], tags: [
    ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect, ExecIOEffect,
    ReadEnvEffect, TimeEffect], forbids: [].}
Validate a lockfile against a single project configuration. 
proc validateLockFile(projects: openArray[LockProject];
                      workspaceRoot, lockPath: string): LockValidationReport {.
    ...raises: [Exception, ValueError, OSError, KeyError, IOError], tags: [
    ReadDirEffect, ReadIOEffect, RootEffect, WriteIOEffect, ExecIOEffect,
    ReadEnvEffect, TimeEffect], forbids: [].}
Validate a lockfile against workspace projects and materialized packages. 
proc writeLockFile(lock: LockFile; path: string) {.
    ...raises: [KeyError, OSError, IOError],
    tags: [WriteDirEffect, ReadDirEffect, WriteIOEffect], forbids: [].}
Write a lockfile in Bau's deterministic TOML format.

Made with Nim. Generated: 2026-05-23 13:54:20 UTC