/** * A package's manifest, `zena-package.json` * (docs/design/package-manifest.md): its name, its DID, its dependencies, * the scope on a package host it is created in, and at a workspace's root, * the workspace's other packages, the domains of `scope:name` and whether * `zena pkg add` gives names their scope. * * ```json * { * "name": "app", * "dependencies": { * "router": {"did": "did:plc:routerrouterrouterrouter", "version": "^1.4.2"}, * "lib": {"path": "./packages/lib"}, * "gfx": {"wit": "./wit"} * }, * "workspace": {"packages": ["packages/*"]}, * "scopes": {"widgets": "widgets.alt-pkg.org"} * } * ``` * * `writeDependencies` rewrites the dependencies and keeps the rest of the * file, each key where it was. A WIT dependency, which the compiler reads * and the package manager has nothing to select or fetch for, is kept as * it is. */ import {HashSet, OrderedHashMap} from 'zena:collections'; import {join} from 'zena:core'; import {globToRegex} from 'zena:glob'; import {JsonArray, JsonObject, JsonValue, parseJson, stringify} from 'zena:json'; import {isValidDid} from 'atproto/syntax'; import {isValidLocalName, isValidPackageName, isValidScopeName, parsePackageVersion, readRange} from './records.zena'; import {Requirement} from './resolve.zena'; import {Range, Version} from 'zena-lang:semver'; /** A manifest the package manager cannot read or update. */ export class ManifestError extends Error { new(message: String) : super(message); } /** What a package's `zena-package.json` says. */ export final class Manifest { /** The package's name, or null when the manifest gives none. */ name: String | null; /** The package's DID, once it has been created on a package host. */ did: String | null; /** * The scope on a package host the package is created in, the part of * `name` before its `:`, or null (package-manifest.md, "name"). */ var scope: String | null = null; /** What the package is for, in a sentence: publishing requires it. */ var description: String | null = null; /** The package's license, an SPDX expression such as `MIT`: publishing requires it. */ var license: String | null = null; /** The version `zena pkg publish` publishes next, or null. */ version: Version | null; /** The published packages it depends on, by local name, in file order. */ requirements: OrderedHashMap; /** * The packages on disk it depends on, by local name: each one's * directory, relative to the manifest's. */ paths: OrderedHashMap; /** * The range of versions each package on disk is published as a * dependency with, by local name, for those whose entry gives a * `version` beside its `path`. Builds use the directory; only * `zena pkg publish` reads the range (package-manifest.md, * "dependencies"). */ var pathRanges = new OrderedHashMap(); /** * At a workspace's root, the directories of the workspace's other * packages, or patterns ending in `/*`. Empty elsewhere. */ workspacePackages: GrowableArray; /** At a workspace's root, each scope mapped to its domain. */ scopes: OrderedHashMap; /** * At a workspace's root, whether `zena pkg add` names a package in a * scope `:`, as it does unless `scopedNames` is false * (docs/design/import-names.md, "Names are still local"). */ var scopedNames = true; /** * At a workspace's root, what `zena pkg add` and `zena pkg update` do when * selection installs a package at two versions: `allow`, `warn` or * `error` (docs/design/package-manager.md, "What zena pkg add and zena * pkg update report"). */ var duplicates = 'allow'; /** * The WIT-backed packages it depends on, by local name: each one's `.wit` * file or directory, relative to the manifest's. */ var wits = new OrderedHashMap(); /** * The patterns of the files a published archive holds, relative to the * manifest's directory, or null for the default (`package-manager/files`). */ var files: Array | null = null; /** * The directory its libraries are in, relative to the manifest's: its * `source`, or `src` when it has none (package-manifest.md, "source"). */ var source = 'src'; /** * The entry files of the libraries `exports` names, relative to the * manifest's directory, under `source`: none for an open package, which * exports every file. A published archive must hold each. */ var exportFiles = new GrowableArray(); /** * The library an import of the package's name alone imports, when the * manifest names one: `main` when it does not (import-names.md, "The main * library"). */ var main: String | null = null; /** * The entry file of the library `main` names, relative to the manifest's * directory, for a package that names a `main` and lists no `exports`: * one that does has it among `exportFiles`. A published archive must * hold it. */ var mainFile: String | null = null; new(name: String | null, did: String | null, requirements: OrderedHashMap, paths: OrderedHashMap, workspacePackages: GrowableArray, scopes: OrderedHashMap, version: Version | null = null) : name = name, did = did, requirements = requirements, paths = paths, workspacePackages = workspacePackages, scopes = scopes, version = version; } /** * The package name and scope a manifest's `name`, `[scope:]name`, gives: * both null when it has none, and a null scope when the name has none. */ function splitName(name: String | null): inline (String | null, String | null) { if (name == null) { return (null, null); } let colon = name.indexOf(':'); if (let (true, at) = colon) { let scope = name.slice(name.startIndex, at); let plain = name.slice(name.indexAfter(at)); if (!isValidLocalName(name) || !isValidPackageName(plain)) { throw new ManifestError(`zena-package.json: '${name}' is not a valid package name: a name, or scope:name`); } return (plain, scope); } if (!isValidPackageName(name)) { throw new ManifestError(`zena-package.json: '${name}' is not a valid package name`); } return (name, null); } /** * Reads `zena-package.json` text. A null `text`, for a directory with no * manifest, reads as an empty manifest. Throws `ManifestError`. */ export function readManifest(text: String | null): Manifest { let root = parse(text); let (name, nameScope) = splitName(optionalString(root, 'name')); let did = optionalString(root, 'did'); if (did != null && !isValidDid(did)) { throw new ManifestError(`zena-package.json: '${did}' is not a DID`); } let versionText = optionalString(root, 'version'); var version: Version | null = null; if (versionText != null) { try { version = parsePackageVersion(versionText); } catch (e) { throw new ManifestError(`zena-package.json: version: ${e.message}`); } } let requirements = new OrderedHashMap(); let paths = new OrderedHashMap(); let pathRanges = new OrderedHashMap(); let wits = new OrderedHashMap(); let dependencies = member(root, 'dependencies'); if (dependencies != null) { dependencies.forEach((localName, value) => { if (!isValidLocalName(localName)) { throw new ManifestError(`zena-package.json: '${localName}' is not a valid local name`); } if (!(value is JsonObject)) { throw new ManifestError(`zena-package.json: dependency '${localName}' is not an object`); } let entry = value; let wit = entry['wit']; if (wit != null) { if (!(wit is String) || entry.has('did') || entry.has('version') || entry.has('path')) { throw new ManifestError( `zena-package.json: dependency '${localName}' has a wit and a DID, version or path, or a wit that is not a string`); } wits[localName] = wit; return; } let path = entry['path']; if (path != null) { if (!(path is String) || entry.has('did')) { throw new ManifestError( `zena-package.json: dependency '${localName}' has a path and a DID, or a path that is not a string`); } // A version beside a path is the range the dependency is published // with. The package is still the one in the directory. if (entry.has('version')) { let range = entry['version']; if (!(range is String)) { throw new ManifestError(`zena-package.json: dependency '${localName}' has a version that is not a string`); } pathRanges[localName] = parseRange(range, localName); } paths[localName] = path; return; } let did = entry['did']; let version = entry['version']; if (!(did is String) || !isValidDid(did)) { throw new ManifestError(`zena-package.json: dependency '${localName}' has no DID, path or wit`); } if (!(version is String)) { throw new ManifestError(`zena-package.json: dependency '${localName}' has no version`); } requirements[localName] = new Requirement(did, parseRange(version, localName)); }); } let workspacePackages = new GrowableArray(); let workspace = member(root, 'workspace'); if (workspace != null) { let packages = workspace['packages']; if (packages != null) { if (!(packages is JsonArray)) { throw new ManifestError('zena-package.json: workspace.packages is not a list'); } let list = packages; for (var i = 0; i < list.length; i += 1) { let item = list[i]; if (!(item is String)) { throw new ManifestError('zena-package.json: workspace.packages lists something other than a directory'); } workspacePackages.push(item); } } } let scopes = new OrderedHashMap(); let scopeMap = member(root, 'scopes'); if (scopeMap != null) { scopeMap.forEach((scope, domain) => { if (!isValidScopeName(scope) || !(domain is String)) { throw new ManifestError(`zena-package.json: scope '${scope}' is not a scope's name mapped to a domain`); } scopes[scope] = domain; }); } let manifest = new Manifest(name, did, requirements, paths, workspacePackages, scopes, version); manifest.wits = wits; manifest.pathRanges = pathRanges; manifest.scope = nameScope; let scopedNames = root['scopedNames']; if (scopedNames != null) { if (!(scopedNames is Box)) { throw new ManifestError('zena-package.json: scopedNames is not true or false'); } manifest.scopedNames = scopedNames.value; } let duplicates = optionalString(root, 'duplicates'); if (duplicates != null) { if (duplicates != 'allow' && duplicates != 'warn' && duplicates != 'error') { throw new ManifestError(`zena-package.json: duplicates is allow, warn or error, not '${duplicates}'`); } manifest.duplicates = duplicates; } manifest.description = optionalString(root, 'description'); manifest.license = optionalString(root, 'license'); manifest.files = filePatterns(root); manifest.source = sourceDirectory(root); manifest.exportFiles = exportedFiles(root, manifest.source); let main = mainLibrary(root); manifest.main = main; if (main != null && !(root['exports'] is JsonObject)) { manifest.mainFile = underSource(manifest.source, `${main}.zena`); } return manifest; } /** * The manifest's `main`, or null when it has none: a library's name, and * one of the `exports` when it lists them, as the compiler requires. */ function mainLibrary(root: JsonObject): String | null { let value = root['main']; if (value == null) { return null; } if (!(value is String)) { throw new ManifestError('zena-package.json: main is not a string'); } let main = value; if (main == '' || main.startsWith('/') || main.endsWith('/') || main.endsWith('.zena')) { throw new ManifestError(`zena-package.json: main '${main}' is not a library's name`); } let exports = root['exports']; if (exports is JsonObject) { if (!exports.has(main)) { throw new ManifestError(`zena-package.json: main '${main}' is not one of its exports`); } } return main; } /** * The `source` directory, normalized, or `src` when there is none. It must * be a directory inside the package: relative, and without `..`. */ function sourceDirectory(root: JsonObject): String { if (!root.has('source')) { return 'src'; } let value = root['source']; if (!(value is String)) { throw new ManifestError('zena-package.json: source is not a path'); } let text = value; let parts = new GrowableArray(); for (let part in text.split('/')) { if (part == '..' || (parts.length == 0 && part == '' && text.startsWith('/'))) { throw new ManifestError(`zena-package.json: source '${text}' is not a directory inside the package`); } if (part != '' && part != '.') { parts.push(part); } } return if (parts.length == 0) '.' else join(parts, '/'); } /** * The `files` list: patterns, each perhaps negated with `!`, of paths * inside the package. Null when there is none. */ function filePatterns(root: JsonObject): Array | null { if (!root.has('files')) { return null; } let value = root['files']; if (!(value is JsonArray)) { throw new ManifestError('zena-package.json: files is not a list of paths'); } let list = value; let patterns = new GrowableArray(); for (var i = 0; i < list.length; i += 1) { let item = list[i]; if (!(item is String)) { throw new ManifestError('zena-package.json: an entry of files is not a string'); } let pattern = item; let path = if (pattern.startsWith('!')) pattern.sliceBytes(1, pattern.length) else pattern; var outside = path == '' || path.startsWith('/'); for (let segment in path.split('/')) { if (segment == '..') { outside = true; } } if (outside) { throw new ManifestError(`zena-package.json: '${pattern}' in files is not a path inside the package`); } try { globToRegex(path); } catch (e) { throw new ManifestError(`zena-package.json: '${pattern}' in files is not a pattern: ${e.message}`); } patterns.push(pattern); } return patterns; } /** * The entry files of the libraries `exports` names, in the `source` * directory (package-manifest.md, "exports"). */ function exportedFiles(root: JsonObject, source: String): GrowableArray { let files = new GrowableArray(); let exports = root['exports']; if (!(exports is JsonObject)) { return files; } exports.forEach((name, value) => { if (!(value is JsonObject)) { return; } let entry = value; let path = entry['path']; let virtual = entry['virtual']; if (path is String) { files.push(underSource(source, path)); } else if (virtual is JsonObject) { virtual.forEach((target, file) => { if (file is String) { files.push(underSource(source, file)); } }); } else { files.push(underSource(source, `${name}.zena`)); } }); return files; } /** `file`, a path relative to the `source` directory, relative to the manifest's. */ function underSource(source: String, file: String): String { let relative = if (file.startsWith('./')) file.sliceBytes(2, file.length) else file; return if (source == '.') relative else `${source}/${relative}`; } /** * The range a release of `manifest`'s package states for its path * dependency `localName`, which is at `version` in its directory: the * range the manifest gives beside the path, or else `^`. * * Throws `ManifestError` when the range the manifest gives leaves out * `version`, since the package was built and tested against that one. */ export function publishedRange(manifest: Manifest, localName: String, version: Version): Range { if (let (true, range) = manifest.pathRanges.get(localName)) { if (!range.includes(version)) { throw new ManifestError( `zena-package.json: dependency '${localName}' is published as ${range.text}, which leaves out ${version.toString()}, the version at its path`); } return range; } return Range.parse(`^${version.toString()}`); } /** * `zena-package.json` text with its `dependencies` replaced by * `requirements` and `paths`, or a new manifest holding only them when * `text` is null. A dependency the file already has keeps its place, new * ones follow, and every other key stays where it was. A WIT dependency * stays as the file has it, and a path dependency keeps the `version` * the file gives beside its path. */ export function writeDependencies(text: String | null, requirements: OrderedHashMap, paths: OrderedHashMap): String { let root = parse(text); let section = new JsonObject(); let written = new HashSet(); let existing = member(root, 'dependencies'); let write = (localName: String) => { if (written.has(localName)) { return; } if (let (true, requirement) = requirements.get(localName)) { let entry = new JsonObject(); entry['did'] = requirement.did; entry['version'] = requirement.range.text; section[localName] = entry; written.add(localName); } else if (let (true, path) = paths.get(localName)) { let entry = new JsonObject(); entry['path'] = path; if (existing != null) { let before = existing[localName]; if (before is JsonObject && before.has('path') && before.has('version')) { entry['version'] = before['version']; } } section[localName] = entry; written.add(localName); } }; if (existing != null) { existing.forEach((localName, value) => { if (value is JsonObject && value.has('wit') && !requirements.has(localName) && !paths.has(localName)) { section[localName] = value; written.add(localName); return; } write(localName); }); } for (let localName in requirements.keys()) { write(localName); } for (let localName in paths.keys()) { write(localName); } root['dependencies'] = section; return stringify(root, ' '); } /** * `zena-package.json` text with its `did` set to `did`, and, when a `scope` * is given, its `name` to `:`, as `zena pkg publish` writes it * when it creates the package. A new `did` goes after `name`, and every * other key stays where it was. */ export function writeDid(text: String, did: String, scope: String | null = null): String { var root = parse(text); if (root.has('did')) { root['did'] = did; } else { root = insertAfter(root, 'name', 'did', did); } if (scope != null) { let (name, _) = splitName(optionalString(root, 'name')); if (name == null) { throw new ManifestError('zena-package.json has no name to give the scope in'); } root['name'] = `${scope}:${name}`; } return stringify(root, ' '); } /** `root` with `key` set to `value` just after `after`, or last when it has no `after`. */ function insertAfter(root: JsonObject, after: String, key: String, value: String): JsonObject { let written = new JsonObject(); root.forEach((existing, existingValue) => { written[existing] = existingValue; if (existing == after) { written[key] = value; } }); if (!written.has(key)) { written[key] = value; } return written; } function parse(text: String | null): JsonObject { if (text == null) { return new JsonObject(); } var json: JsonValue = null; try { json = parseJson(text); } catch (e) { throw new ManifestError(`zena-package.json is not JSON: ${e.message}`); } if (!(json is JsonObject)) { throw new ManifestError('zena-package.json is not a JSON object'); } return json; } function member(root: JsonObject, name: String): JsonObject | null { let value = root[name]; if (value == null) { return null; } if (!(value is JsonObject)) { throw new ManifestError(`zena-package.json: "${name}" is not an object`); } return value; } function optionalString(root: JsonObject, name: String): String | null { let value = root[name]; if (value == null) { return null; } if (!(value is String)) { throw new ManifestError(`zena-package.json: "${name}" is not a string`); } return value; } /** A dependency's range, which must have a version in it. */ function parseRange(text: String, localName: String): Range { try { return readRange(text, `zena-package.json: dependency '${localName}'`); } catch (e) { throw new ManifestError(e.message); } }