@velarscript/cli 0.14.1 → 0.14.3

package/dist/project.js

@@ -12,6 +12,7 @@ import { hostErrorMessage, isHostErrorCode } from "./host-error.js";
 import { canonicalizePotentialPath } from "./canonical-path.js";
 import { byCodeUnit } from "./stable-order.js";
 import { VELAR_VERSION } from "./version.js";
+import { loadVelarLibraryArtifact, packageStableModulePath, rebaseModuleInterfaceIdentities, } from "./library-artifact.js";
 const MAX_PROJECT_RESOURCES = 1024;
 const MAX_JSON_RESOURCE_BYTES = 4 * 1024 * 1024;
 function missingExportMessage(source, name) {
@@ -65,6 +66,7 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
     const interfaceCache = new Map();
     const velarPackages = new Map();
     const velarImports = new Map();
+    const velarArtifactInterfaces = new Map();
     const resources = new Map();
     const resourceImports = new Map();
     const unsafeCssOwners = new Map();
@@ -342,17 +344,22 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
                     continue;
                 }
                 try {
-                    const package_ = await resolveVelarSourcePackage(dependency.source, inputPath);
-                    assertVelarPackageCompatibility(package_, packageTarget, packageCapabilities);
+                    const package_ = await resolveVelarSourcePackage(dependency.source, inputPath, packageTarget, packageCapabilities);
                     const existing = velarPackages.get(package_.name);
                     if (existing && existing.root !== package_.root) {
                         recordResolution(inputPath, dependency.source, "VEL6002", `VelarScript package '${package_.name}' resolves to multiple installed versions; use one package instance per application build`);
                         continue;
                     }
                     velarPackages.set(package_.name, package_);
-                    velarImports.set(projectImportKey(inputPath, dependency.source), package_.entryPath);
-                    importOrigins.set(package_.entryPath, { importer: inputPath, source: dependency.source });
-                    enqueue({ inputPath: package_.entryPath, package: package_ });
+                    const importKey = projectImportKey(inputPath, dependency.source);
+                    if (package_.artifact) {
+                        velarArtifactInterfaces.set(importKey, package_.artifact.moduleInterface);
+                    }
+                    else {
+                        velarImports.set(importKey, package_.entryPath);
+                        importOrigins.set(package_.entryPath, { importer: inputPath, source: dependency.source });
+                        enqueue({ inputPath: package_.entryPath, package: package_ });
+                    }
                 }
                 catch (error) {
                     if (error instanceof JavaScriptOnlyPackageError) {
@@ -410,7 +417,8 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
     }
     let compiledModules = 0;
     let reusedModules = 0;
-    for (const group of dependencyFirstCompilationGroups(loaded, velarImports, compilerExtensions)) {
+    const compilationGroups = dependencyFirstCompilationGroups(loaded, velarImports, compilerExtensions);
+    for (const group of compilationGroups) {
         const reusable = group.every((module) => !affected.has(module.inputPath));
         if (reusable) {
             for (const module of group) {
@@ -436,8 +444,8 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
                 interfaceCache.delete(module.inputPath);
             const nextResults = new Map();
             for (const module of group) {
-                const analysis = await createAnalysisContext(module, loaded, velarImports, failures, notices, declarationCache, externalTypeDependencies, interfaceCache, compiledInterfaces, compilerExtensions);
-                const result = importedReactiveAssignmentDiagnostics(compile(module.text, {
+                const analysis = await createAnalysisContext(module, loaded, velarImports, velarArtifactInterfaces, failures, notices, declarationCache, externalTypeDependencies, interfaceCache, compiledInterfaces, compilerExtensions);
+                const compiled = importedReactiveAssignmentDiagnostics(compile(module.text, {
                     path: module.inputPath,
                     analysis,
                     extensions: compilerExtensions,
@@ -445,6 +453,9 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
                     sharedRuntimeModules: true,
                     ...(options.exportTestFunctions ? { exportFunctions: new Set(module.inspection.moduleInterface.tests.map((item) => item.name)) } : {}),
                 }), analysis.reactiveImports ?? new Map());
+                const result = module.package === null
+                    ? compiled
+                    : { ...compiled, moduleInterface: stableSourcePackageInterface(module, compiled.moduleInterface, loaded) };
                 nextResults.set(module.inputPath, { inputPath: module.inputPath, relativePath: module.relativePath, result });
             }
             passResults = nextResults;
@@ -477,6 +488,19 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
     // machine's `LC_ALL`. Order by code unit over the POSIX-normalized
     // relative path instead.
     modules.sort((left, right) => byCodeUnit(left.relativePath, right.relativePath));
+    // Resolve every public barrel after the final SCC pass. A frozen library
+    // serializes this map, so source mode and artifact mode expose the same
+    // flattened contract even when the package entry only re-exports names.
+    // Walk the same dependency-first groups used for compilation: clearing the
+    // cache and starting at the entry would otherwise recurse through one host
+    // frame per module while resolving a legal 3000-module line.
+    interfaceCache.clear();
+    const moduleInterfaces = new Map();
+    for (const group of compilationGroups) {
+        for (const module of group) {
+            moduleInterfaces.set(module.inputPath, resolvedModuleInterface(module, loaded, velarImports, velarArtifactInterfaces, interfaceCache, compiledInterfaces, compilerExtensions));
+        }
+    }
     if (framework?.host.validateProject) {
         try {
             const messages = framework.host.validateProject({
@@ -503,10 +527,12 @@ export async function compileProjectEntries(entries, primaryEntry, overrides = n
         framework,
         capabilities,
         modules,
+        moduleInterfaces,
         failures: uniqueFailures(failures),
         notices: uniqueNotices(notices),
         velarPackages: [...velarPackages.values()],
         velarImports,
+        velarArtifactInterfaces,
         resources: [...resources.values()],
         resourceImports,
         externalTypeDependencies,
@@ -1154,7 +1180,7 @@ export function moduleInterfaceIdentity(interface_, extensions = []) {
         extensionExports,
     ]);
 }
-async function createAnalysisContext(module, loaded, velarImports, failures, notices, declarationCache, externalTypeDependencies, interfaceCache, compiledInterfaces, compilerExtensions) {
+async function createAnalysisContext(module, loaded, velarImports, artifactInterfaces, failures, notices, declarationCache, externalTypeDependencies, interfaceCache, compiledInterfaces, compilerExtensions) {
     const imports = new Map();
     const dynamicImports = new Map();
     const reactiveImports = new Map();
@@ -1175,15 +1201,24 @@ async function createAnalysisContext(module, loaded, velarImports, failures, not
             extensionModules.set(extensionId, values);
         }
     }
+    for (const interface_ of new Set(artifactInterfaces.values())) {
+        for (const [extensionId, data] of interface_.extensionData) {
+            const values = extensionModules.get(extensionId) ?? [];
+            values.push(data);
+            extensionModules.set(extensionId, values);
+        }
+    }
     for (const dependency of module.inspection.dependencies) {
         if (dependency.dynamic) {
+            const artifact = artifactInterfaces.get(projectImportKey(module.inputPath, dependency.source));
             const targetPath = dependency.source.startsWith(".") && extname(dependency.source) === ".vel"
                 ? resolve(dirname(module.inputPath), dependency.source)
                 : null;
             const target = targetPath ? loaded.get(targetPath) : null;
-            if (!target)
+            const interface_ = artifact
+                ?? (target ? resolvedModuleInterface(target, loaded, velarImports, artifactInterfaces, interfaceCache, compiledInterfaces, compilerExtensions) : null);
+            if (!interface_)
                 continue;
-            const interface_ = resolvedModuleInterface(target, loaded, velarImports, interfaceCache, compiledInterfaces, compilerExtensions);
             if (interface_.reactiveExports.size > 0) {
                 failures.push({
                     path: module.inputPath,
@@ -1200,12 +1235,13 @@ async function createAnalysisContext(module, loaded, velarImports, failures, not
             continue;
         }
         if (dependency.reExport) {
-            const interface_ = standardModuleInterface(dependency.source, compilerExtensions) ?? (() => {
+            const interface_ = artifactInterfaces.get(projectImportKey(module.inputPath, dependency.source))
+                ?? standardModuleInterface(dependency.source, compilerExtensions) ?? (() => {
                 const targetPath = dependency.source.startsWith(".") && extname(dependency.source) === ".vel"
                     ? resolve(dirname(module.inputPath), dependency.source)
                     : velarImports.get(projectImportKey(module.inputPath, dependency.source));
                 const target = targetPath ? loaded.get(targetPath) : null;
-                return target ? resolvedModuleInterface(target, loaded, velarImports, interfaceCache, compiledInterfaces, compilerExtensions) : null;
+                return target ? resolvedModuleInterface(target, loaded, velarImports, artifactInterfaces, interfaceCache, compiledInterfaces, compilerExtensions) : null;
             })();
             if (interface_) {
                 for (const specifier of dependency.specifiers) {
@@ -1274,6 +1310,12 @@ async function createAnalysisContext(module, loaded, velarImports, failures, not
             importReachableStandardTypeMetadata(standard, compilerExtensions, namedTypes, namedTypeReadonlyFields, namedTypeBases, genericTypes, enums, classes);
             continue;
         }
+        const artifact = artifactInterfaces.get(projectImportKey(module.inputPath, dependency.source));
+        if (artifact) {
+            importInterface(module, dependency, artifact, imports, reactiveImports, namedTypes, namedTypeReadonlyFields, namedTypeIdentities, namedTypeBases, genericTypes, typeAliases, enums, classes, extensionImports, failures);
+            importReachableStandardTypeMetadata(artifact, compilerExtensions, namedTypes, namedTypeReadonlyFields, namedTypeBases, genericTypes, enums, classes);
+            continue;
+        }
         const targetPath = dependency.source.startsWith(".") && extname(dependency.source) === ".vel"
             ? resolve(dirname(module.inputPath), dependency.source)
             : velarImports.get(projectImportKey(module.inputPath, dependency.source));
@@ -1282,7 +1324,7 @@ async function createAnalysisContext(module, loaded, velarImports, failures, not
         const target = loaded.get(targetPath);
         if (!target)
             continue;
-        const targetInterface = resolvedModuleInterface(target, loaded, velarImports, interfaceCache, compiledInterfaces, compilerExtensions);
+        const targetInterface = resolvedModuleInterface(target, loaded, velarImports, artifactInterfaces, interfaceCache, compiledInterfaces, compilerExtensions);
         importInterface(module, dependency, targetInterface, imports, reactiveImports, namedTypes, namedTypeReadonlyFields, namedTypeIdentities, namedTypeBases, genericTypes, typeAliases, enums, classes, extensionImports, failures);
         // The same sink one step sideways: a project module can re-export a
         // signature returning a standard type it never declares either.
@@ -1305,11 +1347,12 @@ async function createAnalysisContext(module, loaded, velarImports, failures, not
         resources: module.resourceContents,
     };
 }
-function resolvedModuleInterface(module, loaded, velarImports, cache, compiledInterfaces, compilerExtensions) {
+function resolvedModuleInterface(module, loaded, velarImports, artifactInterfaces, cache, compiledInterfaces, compilerExtensions) {
     const cached = cache.get(module.inputPath);
     if (cached)
         return cached;
-    const own = compiledInterfaces.get(module.inputPath) ?? module.inspection.moduleInterface;
+    const rawOwn = compiledInterfaces.get(module.inputPath) ?? module.inspection.moduleInterface;
+    const own = module.package === null ? rawOwn : stableSourcePackageInterface(module, rawOwn, loaded);
     const exports = new Map(own.exports);
     const mutableExports = new Set(own.mutableExports);
     const reactiveExports = new Map(own.reactiveExports);
@@ -1345,7 +1388,8 @@ function resolvedModuleInterface(module, loaded, velarImports, cache, compiledIn
     for (const dependency of module.inspection.dependencies) {
         if (dependency.javascript)
             continue;
-        let dependencyInterface = standardModuleInterface(dependency.source, compilerExtensions);
+        let dependencyInterface = artifactInterfaces.get(projectImportKey(module.inputPath, dependency.source))
+            ?? standardModuleInterface(dependency.source, compilerExtensions);
         if (!dependencyInterface) {
             const targetPath = dependency.source.startsWith(".") && extname(dependency.source) === ".vel"
                 ? resolve(dirname(module.inputPath), dependency.source)
@@ -1353,7 +1397,7 @@ function resolvedModuleInterface(module, loaded, velarImports, cache, compiledIn
             const target = targetPath ? loaded.get(targetPath) : null;
             if (!target)
                 continue;
-            dependencyInterface = resolvedModuleInterface(target, loaded, velarImports, cache, compiledInterfaces, compilerExtensions);
+            dependencyInterface = resolvedModuleInterface(target, loaded, velarImports, artifactInterfaces, cache, compiledInterfaces, compilerExtensions);
         }
         const aliases = new Map(dependency.specifiers
             .filter((specifier) => !specifier.namespace && specifier.imported !== "default")
@@ -1463,6 +1507,24 @@ function resolvedModuleInterface(module, loaded, velarImports, cache, compiledIn
     }
     return resolved;
 }
+/**
+ * Source fallback and frozen artifacts must agree on nominal identities.
+ * Absolute installation paths would make one record or class a different
+ * type on every machine and would leak a publisher path into the artifact.
+ */
+function stableSourcePackageInterface(module, interface_, loaded) {
+    if (module.package === null)
+        return interface_;
+    return rebaseModuleInterfaceIdentities(interface_, [...loaded.values()].flatMap((candidate) => {
+        const owner = candidate.package;
+        if (owner === null)
+            return [];
+        return [{
+                physical: candidate.inputPath,
+                logical: packageStableModulePath(owner.name, owner.version, relative(owner.root, candidate.inputPath)),
+            }];
+    }));
+}
 /**
  * MOD-U7: the package is installed and its manifest reads fine — it is simply
  * a JavaScript package. That is the mirror image of BRG-U2 (a VelarScript
@@ -1472,7 +1534,7 @@ function resolvedModuleInterface(module, loaded, velarImports, cache, compiledIn
  */
 class JavaScriptOnlyPackageError extends Error {
 }
-async function resolveVelarSourcePackage(source, importerPath) {
+async function resolveVelarSourcePackage(source, importerPath, target, capabilities) {
     const name = packageNameOf(source);
     if (source !== name)
         throw new Error("package subpaths are not supported; import the package entry by name");
@@ -1480,7 +1542,7 @@ async function resolveVelarSourcePackage(source, importerPath) {
     while (true) {
         const root = join(directory, "node_modules", ...name.split("/"));
         try {
-            return await velarPackageAtRoot(name, root);
+            return await velarPackageAtRoot(name, root, target, capabilities);
         }
         catch (error) {
             if (error instanceof SyntaxError)
@@ -1494,11 +1556,12 @@ async function resolveVelarSourcePackage(source, importerPath) {
         directory = parent;
     }
 }
-async function velarPackageAtRoot(name, root) {
+async function velarPackageAtRoot(name, root, target, capabilities) {
     const manifest = JSON.parse(await readBoundedText(join(root, "package.json"), 1024 * 1024, `Package manifest for '${name}'`));
     if (manifest.name !== undefined && manifest.name !== name) {
         throw new Error(`package name is '${String(manifest.name)}', expected '${name}'`);
     }
+    const version = typeof manifest.version === "string" && manifest.version !== "" ? manifest.version : "0.0.0";
     const entry = manifest.velar?.entry;
     if (typeof entry !== "string" || entry.length === 0) {
         throw new JavaScriptOnlyPackageError("package.json must declare 'velar.entry'");
@@ -1514,15 +1577,63 @@ async function velarPackageAtRoot(name, root) {
     const requires = packageRequiresFields(manifest.velar?.requires);
     const requiredCapabilities = packageRequiredCapabilities(requires);
     const requiredLanguage = packageRequiredLanguage(requires);
-    return {
+    const package_ = {
         name,
+        version,
         root,
         entryPath,
         resources: packageResources(name, root, manifest.velar.resources, manifest.exports),
         targets,
         requiredCapabilities,
         requiredLanguage,
+        artifact: null,
     };
+    const artifacts = packageArtifactDescriptors(manifest.velar?.artifacts);
+    if (artifacts.size > 0 && manifest.version === undefined)
+        throw new Error("A package declaring 'velar.artifacts' must declare its version");
+    if (target === undefined)
+        return package_;
+    const artifactTarget = artifacts.has(target)
+        ? target
+        : target !== "core" && artifacts.has("core")
+            ? "core"
+            : null;
+    if (artifactTarget !== null) {
+        assertVelarPackageTargetCapabilities(package_, target, capabilities ?? new Set());
+        const artifact = await loadVelarLibraryArtifact({
+            packageRoot: root,
+            packageName: name,
+            packageVersion: version,
+            sourceEntry: entry,
+            descriptor: artifacts.get(artifactTarget),
+            target: artifactTarget,
+            packageExports: manifest.exports,
+        });
+        return { ...package_, artifact };
+    }
+    assertVelarPackageCompatibility(package_, target, capabilities ?? new Set());
+    return package_;
+}
+function packageArtifactDescriptors(value) {
+    if (value === undefined)
+        return new Map();
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("'velar.artifacts' must be an object mapping core or node to a receipt path");
+    }
+    const entries = Object.entries(value);
+    if (entries.length !== 1)
+        throw new Error("Velar library ABI 1 requires exactly one artifact target per package");
+    const artifacts = new Map();
+    for (const [target, descriptor] of entries) {
+        if (target !== "core" && target !== "node")
+            throw new Error(`Velar library ABI 1 does not support artifact target '${target}'; supported targets are core and node`);
+        if (typeof descriptor !== "string" || descriptor === "" || /[\u0000-\u001f\u007f]/u.test(descriptor) || isAbsolute(descriptor) || descriptor.includes("\\")
+            || descriptor.split("/").some((part) => part === "" || part === "." || part === "..")) {
+            throw new Error(`'velar.artifacts.${target}' must be a normalized package-relative receipt path`);
+        }
+        artifacts.set(target, descriptor);
+    }
+    return artifacts;
 }
 const velarPackageTargets = new Set(["core", "node", "web", "desktop"]);
 function packageTargets(value) {
@@ -1675,6 +1786,9 @@ function assertVelarPackageCompatibility(package_, target, capabilities) {
             throw new Error(`package '${package_.name}' requires VelarScript language ${declaredLanguage.text}; this toolchain implements ${TOOLCHAIN_LANGUAGE_GENERATION}; install a release of '${package_.name}' published for ${TOOLCHAIN_LANGUAGE_GENERATION}, or run the toolchain the package asks for — its sources are not wrong, they belong to another generation of the language`);
         }
     }
+    assertVelarPackageTargetCapabilities(package_, target, capabilities);
+}
+function assertVelarPackageTargetCapabilities(package_, target, capabilities) {
     if (!package_.targets.includes(target)) {
         throw new Error(`package '${package_.name}' does not support the '${target}' target; supported targets: ${package_.targets.join(", ")}`);
     }