/** * The packages a workspace pins: the `resolved` section of its lockfile * (docs/design/package-manifest.md, "zena-lock.json"), keyed by DID and * version. `zena pkg fetch` fetches them, and the compiler reads them from * the package cache. The `workspace` section gives the pin each workspace * package's names stand for, by the package's directory. * * `writeLockfile` writes a `Resolution` as `zena-lock.json`, and * `diffPins` sorts what writing it changes in the pins already there. * * ```json * { * "lockfileVersion": 1, * "workspace": {".": {"router": "did:plc:...@1.4.2"}}, * "resolved": { * "did:plc:...@1.4.2": { * "release": "bafyrei...", * "source": "bafkrei...", * "dependencies": {"json": "did:web:json.example.com@2.1.0"} * } * } * } * ``` */ import {HashMap, HashSet, OrderedHashMap} from 'zena:collections'; import {JsonObject, JsonValue, parseJson, stringify} from 'zena:json'; import {CODEC_DAG_CBOR, CODEC_RAW, Cid} from 'atproto/cid'; import {isValidCidSyntax, isValidDid} from 'atproto/syntax'; import {Range, Version} from 'zena-lang:semver'; import {parsePackageVersion} from './records.zena'; /** * The version of the lockfile's format, which `writeLockfile` writes as * `lockfileVersion` and `readPins` requires. It is the format's own * number, unrelated to any package's version. The compiler reads * lockfiles too (`LOCKFILE_VERSION` in `compiler/package-manifest`), * so a change to the format raises both, and * `packages/cli/tests/lockfile-version_test.zena` checks they agree. */ export let LOCKFILE_VERSION = 1; /** A lockfile whose pins cannot be read. */ export class ResolutionError extends Error { new(message: String) : super(message); } /** How a lockfile names a version of a package: `did:plc:...@1.4.2`. */ export function packageKey(did: String, version: Version): String { return `${did}@${version.toString()}`; } /** A package a lockfile pins. */ export final class Pin { /** The package's DID and version, `did:plc:...@1.4.2`. */ key: String; did: String; version: Version; /** The CID of the release record. */ release: Cid; /** The raw CID of the release's source archive. */ source: Cid; /** The local names the package's own imports use, each mapped to a pinned package's key. */ dependencies: HashMap; new(key: String, did: String, version: Version, release: Cid, source: Cid, dependencies: HashMap) : key = key, did = did, version = version, release = release, source = source, dependencies = dependencies; } /** * The packages the lockfile `text` pins, in the order it lists * them; none when it has no `resolved` section. Throws `ResolutionError` * for a lockfile of another `lockfileVersion`, or none, and for a pin that * cannot be fetched as written. */ export function readPins(text: String): GrowableArray { var json: JsonValue = null; try { json = parseJson(text); } catch (e) { throw new ResolutionError(`zena-lock.json is not JSON: ${e.message}`); } if (!(json is JsonObject)) { throw new ResolutionError('zena-lock.json is not an object'); } let root = json; checkVersion(root['lockfileVersion']); let pins = new GrowableArray(); let resolved = root['resolved']; if (resolved == null) { return pins; } if (!(resolved is JsonObject)) { throw new ResolutionError('the "resolved" section of zena-lock.json is not an object'); } resolved.forEach((key, value) => { pins.push(readPin(key, value)); }); return pins; } /** * Throws `ResolutionError` unless `value`, a lockfile's `lockfileVersion`, * is `LOCKFILE_VERSION`: a newer one asks for a newer `zena`, and an older * one, or none, for the lockfile to be written again. */ function checkVersion(value: JsonValue): void { let again = 'delete it and run zena pkg update to write it again'; if (value == null) { throw new ResolutionError(`zena-lock.json has no "lockfileVersion": ${again}`); } if (!(value is Box) || value.value != ((value.value as i32) as f64) || value.value < 1.0) { throw new ResolutionError('the "lockfileVersion" of zena-lock.json is not a whole number of at least 1'); } let version = value.value as i32; if (version > LOCKFILE_VERSION) { throw new ResolutionError( `zena-lock.json is lockfile version ${version}, newer than the ${LOCKFILE_VERSION} this zena reads: upgrade zena`); } if (version < LOCKFILE_VERSION) { throw new ResolutionError( `zena-lock.json is lockfile version ${version}, older than the ${LOCKFILE_VERSION} this zena reads: ${again}`); } } function readPin(key: String, value: JsonValue): Pin { var at = -1; for (var i = 0; i < key.length; i += 1) { if (key.getByteAt(i) == 64) { // '@' at = i; } } let did = if (at < 0) key else key.sliceBytes(0, at); if (at < 0 || !isValidDid(did)) { throw new ResolutionError(`'${key}' is not a DID and version, such as did:plc:example@1.4.2`); } if (!(value is JsonObject)) { throw new ResolutionError(`${key} is not an object`); } let entry = value; let version = parseVersion(key.sliceBytes(at + 1, key.length), key); let release = cidMember(entry, 'release', key); if (release.codec != CODEC_DAG_CBOR) { throw new ResolutionError(`${key}: release ${release.toString()} is not the CID of a record`); } let source = cidMember(entry, 'source', key); if (source.codec != CODEC_RAW) { throw new ResolutionError(`${key}: source ${source.toString()} is not the raw CID of a blob`); } let dependencies = new HashMap(); let names = entry['dependencies']; if (names != null) { if (!(names is JsonObject)) { throw new ResolutionError(`${key}: dependencies is not an object`); } names.forEach((name, target) => { if (!(target is String)) { throw new ResolutionError(`${key}: dependency '${name}' is not a string`); } dependencies[name] = target; }); } return new Pin(key, did, version, release, source, dependencies); } function member(entry: JsonObject, name: String, key: String): String { let value = entry[name]; if (!(value is String)) { throw new ResolutionError(`${key} has no "${name}" string`); } return value; } function cidMember(entry: JsonObject, name: String, key: String): Cid { let text = member(entry, name, key); if (!isValidCidSyntax(text)) { throw new ResolutionError(`${key}: ${name} '${text}' is not a CID`); } return Cid.parse(text); } function parseVersion(text: String, key: String): Version { try { return parsePackageVersion(text); } catch (e) { throw new ResolutionError(`${key}: ${e.message}`); } } /** A published package as the lockfile pins it. */ export final class ResolvedPackage { /** The package's DID and version, `did:plc:...@1.4.2`. */ key: String; did: String; version: Version; /** The CID of the release record. */ release: Cid; /** The raw CID of the source archive. */ source: Cid; /** The release's names for its dependencies, each mapped to a package's key. */ dependencies: OrderedHashMap; new(key: String, did: String, version: Version, release: Cid, source: Cid, dependencies: OrderedHashMap) : key = key, did = did, version = version, release = release, source = source, dependencies = dependencies; } /** What selection chose for a workspace. */ export final class Resolution { /** The selected packages, by key. */ packages: OrderedHashMap; new(packages: OrderedHashMap) : packages = packages; /** * The key of the version selected for a dependency on `did` with * `range`: the highest selected version of `did` in the range, or null * when none is. */ keyOf(did: String, range: Range): String | null { var found: ResolvedPackage | null = null; for (let key in this.packages.keys()) { let pkg = this.packages[key]; if (pkg.did == did && range.includes(pkg.version)) { let current = found; if (current == null || pkg.version.compareTo(current.version) > 0) { found = pkg; } } } return found?.key; } /** Each package selected at more than one version, with its versions in order. */ duplicates(): OrderedHashMap> { let byPackage = new OrderedHashMap>(); for (let key in this.packages.keys()) { let pkg = this.packages[key]; if (let (true, versions) = byPackage.get(pkg.did)) { versions.push(pkg.version); } else { let versions = new GrowableArray(); versions.push(pkg.version); byPackage[pkg.did] = versions; } } let out = new OrderedHashMap>(); byPackage.forEach((did, versions) => { if (versions.length > 1) { out[did] = versions; } }); return out; } } /** * `zena-lock.json` text pinning `resolution`'s packages, with `workspace`, * each workspace package's names by its directory, each mapped to a key * of `resolution`, after `lockfileVersion`. The lockfile holds nothing * else, so it is written whole. */ export function writeLockfile(resolution: Resolution, workspace: OrderedHashMap>): String { let root = new JsonObject(); root['lockfileVersion'] = new Box(LOCKFILE_VERSION as f64); let names = new JsonObject(); workspace.forEach((dir, pins) => { if (pins.size > 0) { let entry = new JsonObject(); pins.forEach((name, key) => { entry[name] = key; }); names[dir] = entry; } }); if (names.size > 0) { root['workspace'] = names; } let resolved = new JsonObject(); resolution.packages.forEach((key, pkg) => { let entry = new JsonObject(); entry['release'] = pkg.release.toString(); entry['source'] = pkg.source.toString(); if (pkg.dependencies.size > 0) { let dependencies = new JsonObject(); pkg.dependencies.forEach((name, target) => { dependencies[name] = target; }); entry['dependencies'] = dependencies; } resolved[key] = entry; }); root['resolved'] = resolved; return stringify(root, ' '); } /** * How a package's pin changes when a lockfile is written for a new * resolution (`diffPins`). */ export sealed class PinChange { /** A package the lockfile did not pin. */ case PinAdded(now: ResolvedPackage) /** A package the lockfile pinned, and no longer does. */ case PinRemoved(pin: Pin) /** * A package pinned at another version on the same compatible line * (`Version.compatibleLine`), higher or lower: the one version on that * line the lockfile pinned and the one the resolution selects instead. */ case PinVersionChanged(pin: Pin, now: ResolvedPackage) /** * A package at the version it was pinned at, with another release * record or source archive: the release was changed in place, which a * published version never is (docs/design/package-manager.md, * "Immutability"). */ case PinChangedInPlace(pin: Pin, now: ResolvedPackage) } /** * What writing `after` changes in the pins `before`, in `after`'s order * and then `before`'s: a version both have with other CIDs was changed in * place; a package and compatible line with one version before and * another after changed version; any other version only one of them has * was added or removed. A pin that stays the same has no change. */ export function diffPins(before: GrowableArray, after: Resolution): GrowableArray { let pinned = new HashMap(); // The versions only `before` or only `after` has, by package and compatible line. let gone = new HashMap>(); let fresh = new HashMap>(); for (let pin in before) { pinned[pin.key] = pin; if (!after.packages.has(pin.key)) { append(gone, slotOf(pin.did, pin.version), pin); } } after.packages.forEach((key, now) => { if (!pinned.has(key)) { append(fresh, slotOf(now.did, now.version), now); } }); let changes = new GrowableArray(); let paired = new HashSet(); after.packages.forEach((key, now) => { if (let (true, pin) = pinned.get(key)) { if (!pin.release.equals(now.release) || !pin.source.equals(now.source)) { changes.push(new PinChangedInPlace(pin, now)); } return; } let slot = slotOf(now.did, now.version); if (let (true, pins) = gone.get(slot)) { if (pins.length == 1 && fresh[slot].length == 1) { changes.push(new PinVersionChanged(pins[0], now)); paired.add(pins[0].key); return; } } changes.push(new PinAdded(now)); }); for (let pin in before) { if (!after.packages.has(pin.key) && !paired.has(pin.key)) { changes.push(new PinRemoved(pin)); } } return changes; } /** The package `did`'s compatible line that `version` is on. */ function slotOf(did: String, version: Version): String { return `${did}@${version.compatibleLine()}`; } function append(map: HashMap>, key: String, value: T): void { if (let (true, values) = map.get(key)) { values.push(value); } else { let values = new GrowableArray(); values.push(value); map[key] = values; } }