// Module resolution for the Zena compiler. // // Resolves import specifiers to canonical module paths. Handles: // - Relative imports (./foo, ../bar) // - Package imports (package:module) // - Virtual modules (target-conditional resolution) // - Internal modules (package-private) // // Resolution is a pure function of configuration (packages + target). // No I/O is performed. import { HashMap } from 'zena:collections'; // ============================================================================ // Package Configuration // ============================================================================ // Configuration for a single module export within a package. // For simple modules, `virtual` and `path` are null and the module resolves // to `.zena` in the package's source directory. // `path` overrides the entry file (relative to the source directory). // For target-conditional modules, `virtual` maps target names to entry file // paths (relative to the source directory). export final class ModuleExport { virtual: HashMap | null; path: String | null; // Part of the package's own machinery rather than its API. It keeps a // manifest entry, because that is what selects a file per target and // what makes the name resolve at all, but only modules of the same // package may import it, and documentation tools leave it out. internal: boolean; new(virtual: HashMap | null, path: String | null = null, internal: boolean = false) : virtual = virtual, path = path, internal = internal; } // Configuration for a package in the package manifest. // // A package maps a name (e.g., "zena", "compiler") to a root directory // containing .zena source files. Packages can optionally restrict which // modules are importable via `exports`; files not listed there are private // to the package and reachable only via relative imports. export final class PackageConfig { // Absolute path to the package root directory. root: String; // Explicit module exports. If null, all .zena files are importable (open // package). If present, only listed modules can be imported (closed package). // A published package's are read from its manifest once it is in the // cache, after the config is made. var exports: HashMap | null; // WIT-backed package: the path to a .wit file, or a directory of them, // declared with `{"wit": "./path"}` in the manifest. Its modules are // WIT interfaces — `import {now} from 'wasi:clocks/monotonic-clock'` — // and the compiler host synthesizes their Zena declarations from the // WIT source (docs/design/component-model.md, Part 2). On `zena`, this // points to `host-wit` so `zena:host/*` interfaces resolve alongside // the standard library's `.zena` modules. var witRoot: String | null = null; // A package the resolution file pins (its `resolved` section), keyed by // DID and major version, `did:plc:...@1`: the local names its own // imports use, each mapped to the key of the package it stands for. // Such a package sees only these names, the standard library and // WIT-backed packages. Null for a package listed by path, whose files // see the project's names. var dependencies: HashMap | null = null; // One of the project's dependency names (the resolution file's // `dependencies` section): the key of the resolved package the name // stands for. An alias has no root of its own. var aliasOf: String | null = null; // The directory, relative to `root`, that library names and export // entry files are measured from: a manifest's `source`, `src` when it // has none (package-manifest.md, "source"). `.` for the libraries at // the root, as the standard library's are. var source = "."; // The library an import of the package's name alone imports: the // manifest's `main`, `main` when it has none (import-names.md, "The // main library"). var main = "main"; new( root: String, exports: HashMap | null ) : root = root, exports = exports; // The directory libraries are in: `root` joined with `source`. libraryRoot: String { get { return if (this.source == ".") this.root else `${this.root}/${this.source}`; } } } // ============================================================================ // Resolution Result // ============================================================================ // A resolved module with its canonical path and package info. export final class ResolvedModule( // Canonical path. For stdlib, either a name id ("zena:regex") for a // manifest module resolving to its default ".zena" file, or a path // id ("zena:console/host.zena") for any other stdlib file. // For file modules: "/absolute/path/to/module.zena". path: String, // The package this module belongs to. Empty string for relative imports // that don't fall under any known package. packageName: String ) // ============================================================================ // Module Resolver // ============================================================================ // Resolves import specifiers to canonical module paths. // // The resolver does not perform any I/O. It operates purely on its // configuration: a map of package names to PackageConfig, and a // compilation target string. // // Usage: // let resolver = new ModuleResolver(packages, "js"); // let resolved = resolver.resolve("zena:regex", "/my/file.zena"); // // resolved.path == "zena:regex" export final class ModuleResolver { #packages: HashMap; #target: String; new(packages: HashMap, target: String) : #packages = packages, #target = target; // The compilation target (e.g., "core", "js", "zena-js", "component", "zena-component"). target: String { get { return this.#target; } } // Resolve an import specifier relative to a referrer module. // // Specifier formats (docs/design/import-names.md): // - Relative: "./foo.zena", "../bar.zena" // - Package: "[scope:]package[/library]", such as "acme:router/server" // or "router/server"; without a library, the package's main library // - The standard library, the scope `zena`: "zena:regex" // - A WIT interface, whose namespace is a WIT dependency's name: // "wasi:clocks/monotonic-clock" resolve(specifier: String, referrer: String): ResolvedModule { if (specifier.startsWith("./") || specifier.startsWith("../")) { return this.resolveRelative(specifier, referrer); } // A `:` before any `/` ends the scope. let colonPos = indexOfByte(specifier, 58); // 58 = ':' let slashPos = indexOfByte(specifier, 47); // 47 = '/' var scope: String | null = null; var rest = specifier; if (colonPos >= 0 && (slashPos < 0 || colonPos < slashPos)) { scope = specifier.sliceBytes(0, colonPos); rest = specifier.sliceBytes(colonPos + 1, specifier.length); } if (scope != null) { // The standard library's libraries keep their ids, `/`s and all. if (scope == "zena") { return this.resolvePackage("zena", rest, referrer); } let witKey = this.#witPackageKey(scope, referrer); if (witKey != null) { return this.resolvePackage(witKey, rest, referrer); } } let restSlash = indexOfByte(rest, 47); let packageName = if (restSlash < 0) rest else rest.sliceBytes(0, restSlash); let name = if (scope != null) `${scope}:${packageName}` else packageName; let key = this.#packageKey(name, referrer); let moduleName = if (restSlash < 0) this.#mainLibrary(key) else rest.sliceBytes(restSlash + 1, rest.length); return this.resolvePackage(key, moduleName, referrer); } // The main library of the package `key` names, through its alias if it // is one: the library an import of its name alone imports. #mainLibrary(key: String): String { var current = key; while (true) { if (let (true, config) = this.#packages.get(current)) { let aliasOf = config.aliasOf; if (aliasOf == null) { return config.main; } current = aliasOf; } else { return "main"; } } return "main"; } // The key of the WIT-backed package the scope `scope` names in an import // from `referrer`, or null when it names none: WIT's namespaces are the // scopes of its interfaces. #witPackageKey(scope: String, referrer: String): String | null { var key = scope; let owner = this.findPackageForPath(referrer); if (owner != "" && owner != "zena") { let dependencies = this.#packages[owner].dependencies; if (dependencies != null) { if (let (true, given) = dependencies.get(scope)) { key = given; } } } return if (this.#isWitPackage(key)) key else null; } // The key of the package `name` stands for in an import from // `referrer`. A resolved package's files resolve names through its own // dependencies; every other file through the package map, where the // project's dependency names are aliases. #packageKey(name: String, referrer: String): String { let owner = this.findPackageForPath(referrer); if (owner != "" && owner != "zena") { let dependencies = this.#packages[owner].dependencies; if (dependencies != null) { if (let (true, key) = dependencies.get(name)) { return key; } if (name == "zena" || this.#isWitPackage(name)) { return name; } throw new Error(`Package '${owner}' has no dependency named '${name}'`); } } return name; } #isWitPackage(name: String): boolean { if (let (true, config) = this.#packages.get(name)) { return config.witRoot != null; } return false; } // Resolve a relative import specifier. resolveRelative(specifier: String, referrer: String): ResolvedModule { // Relative imports between stdlib files resolve in the space of paths // relative to the stdlib source root and stay within it. if (referrer.startsWith("zena:")) { return this.#resolveStdlibRelative(specifier, referrer); } let dir = dirName(referrer); let resolved = normalizePath(`${dir}/${specifier}`); let packageName = this.findPackageForPath(resolved); return new ResolvedModule(resolved, packageName); } #resolveStdlibRelative(specifier: String, referrer: String): ResolvedModule { let refPath = this.#stdlibFilePath(referrer.sliceBytes(5, referrer.length)); let resolved = normalizePath(`${dirName(refPath)}/${specifier}`); if (resolved == ".." || resolved.startsWith("../")) { throw new Error( `Cannot resolve '${specifier}' from ${referrer} (escapes the stdlib)` ); } if (let (true, config) = this.#packages.get("zena")) { if (config.exports != null) { let exports = config.exports as HashMap; var exportEntry: ModuleExport | null = null; if (let (true, entry) = exports.get(resolved)) { exportEntry = entry; } else if (!resolved.endsWith(".zena")) { if (let (true, entry) = exports.get(resolved + ".zena")) { exportEntry = entry; } } if (exportEntry != null) { let virtual = (exportEntry as ModuleExport).virtual; if (virtual != null) { let virtualMap = virtual as HashMap; if (let (true, entryPath) = virtualMap.get(this.#target)) { return makeCanonicalFilePath("zena", entryPath, config); } if (let (true, defaultPath) = virtualMap.get("default")) { return makeCanonicalFilePath("zena", defaultPath, config); } } } } } return new ResolvedModule("zena:" + this.#stdlibIdForPath(resolved), "zena"); } // Map a stdlib canonical id (without the "zena:" prefix) to its file path // relative to the stdlib source root. #stdlibFilePath(sub: String): String { if (sub.endsWith(".zena")) { return sub; } return sub + ".zena"; } // Map a stdlib-root-relative file path back to a canonical id (without the // "zena:" prefix): the module name when the path is the default entry file // of a manifest module, otherwise the path itself. Modules with an explicit // `path` or a `virtual` mapping always canonicalize to path ids, so each // file has exactly one canonical id. #stdlibIdForPath(path: String): String { if (path.contains("/") || !path.endsWith(".zena")) { return path; } let name = path.sliceBytes(0, path.length - 5); if (let (true, config) = this.#packages.get("zena")) { if (config.exports != null) { let exports = config.exports as HashMap; if (let (true, moduleExport) = exports.get(name)) { if (moduleExport.virtual == null && moduleExport.path == null) { return name; } } } } return path; } // Resolve a package import specifier. resolvePackage( packageName: String, moduleName: String, referrer: String ): ResolvedModule { if (let (true, config) = this.#packages.get(packageName)) { let aliasOf = config.aliasOf; if (aliasOf != null) { return this.resolvePackage(aliasOf, moduleName, referrer); } // A WIT-backed package: the module is a WIT interface, and the // canonical path carries everything the host needs to synthesize // its declarations — where the WIT lives, and which interface. // The specifier has no version on purpose; the WIT declares it. let witRoot = config.witRoot; if (config.exports == null && witRoot != null) { return new ResolvedModule( `wit:${witRoot as String}#${packageName}:${moduleName}`, packageName); } // Check exports if the package has an explicit export list. if (config.exports != null) { let exports = config.exports as HashMap; if (!exports.has(moduleName)) { if (witRoot != null && moduleName.startsWith("host/")) { return new ResolvedModule( `wit:${witRoot}#${packageName}:${moduleName}`, packageName); } throw new Error( `Library '${moduleName}' not found in package '${packageName}'` ); } let moduleExport = exports[moduleName]; // An internal module is the package's own machinery. It is in the // export map because that is what selects its file per target and // what makes the name resolve, and not because anyone outside may // name it. if (moduleExport.internal && this.findPackageForPath(referrer) != packageName) { throw new Error( "Library '" + packageName + ":" + moduleName + "' is internal to '" + packageName + "' and cannot be imported from outside it" ); } // Resolve virtual modules (target-conditional) to their entry file. // A module with no entry for the current target is not available // there, and says so: falling through would resolve to a default // entry file that does not exist, and report a missing file // instead of a missing capability. if (moduleExport.virtual != null) { let virtual = moduleExport.virtual as HashMap; if (let (true, entryPath) = virtual.get(this.#target)) { return makeCanonicalFilePath(packageName, entryPath, config); } if (let (true, defaultPath) = virtual.get("default")) { return makeCanonicalFilePath(packageName, defaultPath, config); } throw new Error( "Library '" + packageName + ":" + moduleName + "' is not available on target '" + this.#target + "'" ); } // Modules with an explicit entry file resolve to it. if (moduleExport.path != null) { return makeCanonicalFilePath( packageName, moduleExport.path as String, config ); } } return makeCanonicalPath(packageName, moduleName, config); } throw new Error(`Unknown package: '${packageName}'`); } // Find which package (if any) contains the given path: the one with the // longest root the path is inside, so a package nested in another's // directory owns its own files. WIT-backed packages and aliases have no // root and own nothing. findPackageForPath(path: String): String { if (path.startsWith("zena:")) { return "zena"; } var found = ""; var foundLength = -1; let iter = this.#packages.keys(); for (let name in iter) { let root = this.#packages[name].root; if (root == "" || !isUnder(path, root)) { continue; } // A HashMap's order varies between processes, so equal roots are // decided by name. if (root.length > foundLength || (root.length == foundLength && name.compareTo(found) < 0)) { found = name; foundLength = root.length; } } return found; } } // ============================================================================ // Path Utilities // ============================================================================ // Whether `path` is `root` or a file under it. A root of `.`, the workspace's // own directory, holds every relative path that does not climb out of it. function isUnder(path: String, root: String): boolean { if (root == ".") { return !path.startsWith("/") && !path.startsWith("../") && path != ".." && !path.startsWith("zena:") && !path.startsWith("wit:"); } return path == root || path.startsWith(`${root}/`); } // Map a stdlib canonical id (with or without the "zena:" prefix) to its file // path relative to the stdlib source root. Name ids ("zena:string") map to // ".zena"; path ids ("zena:console/host.zena") contain the file path. export function stdlibIdToRelativeFile(id: String): String { let sub = if (id.startsWith("zena:")) id.sliceBytes(5, id.length) else id; if (sub.endsWith(".zena")) { return sub; } return sub + ".zena"; } // Create a canonical path for a module resolving to its default // ".zena" entry file. // Stdlib modules use the "zena:" prefix; other packages resolve to file paths. function makeCanonicalPath( packageName: String, moduleName: String, config: PackageConfig ): ResolvedModule { if (packageName == "zena") { return new ResolvedModule("zena:" + moduleName, "zena"); } let filePath = `${config.libraryRoot}/${moduleName}.zena`; return new ResolvedModule(filePath, packageName); } // Create a canonical path for a module with an explicit entry file // (from `path` or a `virtual` mapping), given relative to the package's // source directory. // Stdlib entries become path ids ("zena:console/host.zena"). function makeCanonicalFilePath( packageName: String, entryPath: String, config: PackageConfig ): ResolvedModule { if (packageName == "zena") { return new ResolvedModule("zena:" + entryPath, "zena"); } return new ResolvedModule(`${config.libraryRoot}/${entryPath}`, packageName); } // Find the byte position of the first occurrence of a byte in a string. // Returns -1 if not found. export function indexOfByte(s: String, byte: i32): i32 { var i = 0; while (i < s.length) { if (s.getByteAt(i) == byte) { return i; } i += 1; } return 0 - 1; } // Get the directory portion of a path. // e.g., "/foo/bar/baz.zena" → "/foo/bar" // Returns "." if the path has no directory separator. // Note: "zena:" canonical ids must not be passed here — the resolver maps // them to stdlib-root-relative file paths first (see #resolveStdlibRelative). export function dirName(path: String): String { var lastSlash = 0 - 1; var i = 0; while (i < path.length) { if (path.getByteAt(i) == 47) { // 47 = '/' lastSlash = i; } i += 1; } if (lastSlash < 0) { return "."; } return path.sliceBytes(0, lastSlash); } // Normalize a path by resolving "." and ".." segments. // Preserves leading "/" for absolute paths. export function normalizePath(path: String): String { let segments = splitByByte(path, 47); // 47 = '/' let result = new Array(); let isAbsolute = path.length > 0 && path.getByteAt(0) == 47; for (let seg in segments) { if (seg == "." || seg == "") { // Skip "." and empty segments (from "//") } else if (seg == "..") { if (result.length > 0 && result[result.length - 1] != "..") { result.pop(); } else if (!isAbsolute) { // Preserve leading ".." segments in relative paths so callers can // detect escapes above the base directory. (Above the root of an // absolute path, ".." is dropped as before.) result.push(seg); } } else { result.push(seg); } } if (isAbsolute) { return "/" + joinBySlash(result); } if (result.length == 0) { return "."; } return joinBySlash(result); } // Split a string by a byte delimiter. export function splitByByte(s: String, delim: i32): GrowableArray { let parts = new Array(); var start = 0; var i = 0; while (i < s.length) { if (s.getByteAt(i) == delim) { parts.push(s.sliceBytes(start, i)); start = i + 1; } i += 1; } parts.push(s.sliceBytes(start, s.length)); return parts; } // Join an array of path segments with "/". function joinBySlash(segments: GrowableArray): String { if (segments.length == 0) { return ""; } var result = segments[0]; var i = 1; while (i < segments.length) { result = `${result}/${segments[i]}`; i += 1; } return result; }