/** * Finding a package's modules. * * A package is a directory. If it holds a manifest, the manifest's * export map is the module list; otherwise every `.zena` file under the * root is a module. A single `.zena` file is a package of one module. * * Two manifest filenames are read, because the standard library's is * spelled differently: `zena-package.json` with an `exports` map, and * `stdlib-manifest.json` with a `modules` map. Both mean the same * thing. See docs/design/zenadoc.md and docs/design/package-manifest.md. */ import { parseJson, JsonValue, JsonObject } from 'zena:json'; import { Future } from 'zena:async'; import { exists, isDirectory, listDir, readFile, FileType } from 'zena:fs'; import { basename, dirname, join2 } from 'zena:path'; import { growable } from 'zena:core'; let PACKAGE_MANIFEST = 'zena-package.json'; let STDLIB_MANIFEST = 'stdlib-manifest.json'; /** One module a package exposes. */ export final class PackageModule( /** The module's name within the package, e.g. `array` or `bench`. */ name: String, /** The entry file, relative to the package root. */ file: String ) /** A package as zenadoc sees it: a name, a root, and a module list. */ export final class Package { name: String; root: String; var version: String | null = null; var modules = new Array(0); new(this.name, this.root); } /** * The package at `path`. * * `path` is a directory or a single `.zena` file. `name` overrides the * name the manifest or the directory would give. */ export async function loadPackage( path: String, name: String | null = null, target: String = 'zena-component' ): Future { if (!(await exists(path))) { throw new Error('no such path: ' + path); } if (!(await isDirectory(path))) { return singleFilePackage(path, name); } let manifestPath = await manifestIn(path); if (manifestPath == null) { return await openPackage(path, name); } return await manifestPackage(path, manifestPath, name, target); } /** The manifest in a directory, whichever of the two names it uses. */ async function manifestIn(root: String): Future { let preferred = join2(root, PACKAGE_MANIFEST); if (await exists(preferred)) { return preferred; } let stdlib = join2(root, STDLIB_MANIFEST); if (await exists(stdlib)) { return stdlib; } return null; } async function manifestPackage( root: String, manifestPath: String, override: String | null, target: String ): Future { let json = parseJson(await readFile(manifestPath)); let manifest = json as JsonObject; var exports = manifest['exports']; if (exports == null) { exports = manifest['modules']; } let name = override ?? manifestName(manifest, root); // The manifest may sit above the sources it describes: a package's // libraries are in its `source` directory, `src` by default // (package-manifest.md, "source"), and the stdlib's manifest, // `packages/stdlib/stdlib-manifest.json`, names `zena` as its `root`. // Every entry file is relative to that directory, not to the manifest. let declaredRoot = if (manifestPath.endsWith(PACKAGE_MANIFEST)) manifest['source'] ?? 'src' else manifest['root']; let sourceRoot = if (declaredRoot is String && declaredRoot != '.') { join2(root, declaredRoot) } else { root }; let out = new Package(name, sourceRoot); let version = manifest['version']; if (version is String) { out.version = version; } if (exports == null) { // A manifest with no export map says nothing about which modules // are public, so every file is. out.modules = await openModules(sourceRoot); return out; } let modules = new Array(16); (exports as JsonObject).forEach((moduleName, value) => { let file = entryFileOf(moduleName, value, target); if (file != null) { modules.push(new PackageModule(moduleName, file)); } }); out.modules = sortModules(modules); return out; } /** * A module's entry file on a target. * * `{}` means `.zena` and `path` names the file. A `virtual` * module has one entry file per target and exists only on the targets * it names — `zena:wasi` is not a module a `zena` * program can import, and documenting it as one would describe an API * that is not there. * * An `internal` module is not one either. It carries a manifest entry * because that is what selects its file per target, and the package's * own modules are the only ones allowed to import it. */ function entryFileOf( name: String, value: JsonValue, target: String ): String | null { if (!(value is JsonObject)) { return name + '.zena'; } let entry = value; let internal = entry['internal']; if (internal is Box && internal.value) { return null; } let path = entry['path']; if (path is String) { return path; } let virtual = entry['virtual']; if (virtual is JsonObject) { let file = virtual[target]; if (file is String) { return file; } return null; } return name + '.zena'; } function manifestName(manifest: JsonObject, root: String): String { let name = manifest['name']; if (name is String) { return name; } return basename(root); } /** Every `.zena` file under a root, as a module named by its path. */ async function openPackage(root: String, override: String | null): Future { let name = override ?? basename(root); let out = new Package(name, root); out.modules = await openModules(root); return out; } async function openModules(root: String): Future> { let modules = new Array(16); await collectZenaFiles(root, '', modules); return sortModules(modules); } async function collectZenaFiles( root: String, prefix: String, out: GrowableArray ): Future { let dir = if (prefix.length == 0) { root } else { join2(root, prefix) }; for (let entry in await listDir(dir)) { if (entry.name == '.' || entry.name == '..') { continue; } let relative = if (prefix.length == 0) { entry.name } else { join2(prefix, entry.name) }; if (entry.fileType == FileType.Directory) { await collectZenaFiles(root, relative, out); } else if (entry.fileType == FileType.RegularFile && entry.name.endsWith('.zena')) { out.push(new PackageModule( relative.sliceBytes(0, relative.length - 5), relative)); } } } function singleFilePackage(path: String, override: String | null): Package { let file = basename(path); let name = override ?? stripExtension(file); let out = new Package(name, dirname(path)); let modules = growable([ new PackageModule(stripExtension(file), file), ]); out.modules = modules; return out; } /** * Modules in name order. * * A manifest's JSON object preserves the order it was written in, and a * directory listing is in whatever order the host returns. Sorting * makes the output depend on the package's contents and nothing else. */ function sortModules( modules: GrowableArray ): GrowableArray { // Insertion sort: a package has tens of modules, not thousands. var i = 1; while (i < modules.length) { let current = modules[i]; var j = i - 1; while (j >= 0 && precedes(current.name, modules[j].name)) { modules[j + 1] = modules[j]; j -= 1; } modules[j + 1] = current; i += 1; } return modules; } /** Whether `a` sorts before `b`, byte by byte. */ function precedes(a: String, b: String): boolean { let shorter = if (a.length < b.length) { a.length } else { b.length }; var i = 0; while (i < shorter) { let x = a.getByteAt(i); let y = b.getByteAt(i); if (x != y) { return x < y; } i += 1; } return a.length < b.length; } function stripExtension(file: String): String { if (file.endsWith('.zena')) { return file.sliceBytes(0, file.length - 5); } return file; }