@smallpen/local-package 0.1.0-alpha.1 → 0.1.0-alpha.11

package/src/workspace.mjs

@@ -1,24 +1,73 @@
 import { realpath } from "node:fs/promises";
-import { dirname, isAbsolute, relative, resolve } from "node:path";
+import { dirname, isAbsolute, posix, resolve, win32 } from "node:path";
 
 import {
+  closestComponentVariant,
   combineContextAxes,
+  findComponentVariant,
   listEffectiveTokens,
   projectScenario,
   projectScreen,
   SmallPenError,
 } from "@smallpen/core";
 
+import { isWithinRoot } from "./fs-utils.mjs";
 import { openPackage } from "./local-package.mjs";
-import { openRemoteLibrary } from "./remote-library.mjs";
+import { openRemoteLibrary, remoteManifestUrl } from "./remote-library.mjs";
 
 function isRecord(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value);
 }
 
-function isWithinRoot(rootPath, candidatePath) {
-  const child = relative(rootPath, candidatePath);
-  return child === "" || (!child.startsWith("..") && !isAbsolute(child));
+// Local Library paths are relative to the declaring Package's directory, like
+// Foundation dependency paths. Unlike dependencies they may climb out of the
+// Workspace ("../libraries/x.smallpen" is the documented form and resolves
+// with an external_library_path warning), but absolute, drive-letter, UNC,
+// and backslash paths are machine-specific and are rejected.
+export function localLibraryLocator(ownerLocator, source) {
+  const path = source?.path;
+  if (
+    typeof path !== "string" ||
+    path.length === 0 ||
+    path.includes("\0") ||
+    path.includes("\\") ||
+    isAbsolute(path) ||
+    posix.isAbsolute(path) ||
+    win32.isAbsolute(path)
+  ) {
+    throw new SmallPenError(
+      "invalid_library_source",
+      "Local Library path must be relative to the declaring Package",
+      { path },
+    );
+  }
+  return resolve(dirname(ownerLocator), path);
+}
+
+// `remoteLibrarySnapshots` (a Map keyed by manifest URL) lets a long-lived
+// caller reuse remote snapshots it already verified; with
+// `reuseRemoteLibrarySnapshots` the network and disk cache are skipped.
+async function remoteLibrarySnapshot(library, options) {
+  const memo =
+    options.remoteLibrarySnapshots instanceof Map
+      ? options.remoteLibrarySnapshots
+      : undefined;
+  const key = remoteManifestUrl(library.source.url);
+  if (
+    memo?.has(key) &&
+    options.reuseRemoteLibrarySnapshots === true &&
+    options.refreshRemoteLibraries !== true
+  ) {
+    return memo.get(key);
+  }
+  const snapshot = await openRemoteLibrary(library.source.url, {
+    cacheRoot: options.libraryCacheRoot,
+    expectedPackageId: library.packageId,
+    fetchImpl: options.fetchImpl,
+    refresh: options.refreshRemoteLibraries === true,
+  });
+  memo?.set(key, snapshot);
+  return snapshot;
 }
 
 function chooseFoundation(dependency) {
@@ -213,7 +262,8 @@ function validateExternalReferences(product, libraries) {
 
 function contextSelections(product, foundation) {
   const axes = [...combineContextAxes(product, foundation).values()].sort(
-    (left, right) => left.id.localeCompare(right.id),
+    // Code-unit order: localeCompare would follow the host LANG.
+    (left, right) => (left.id < right.id ? -1 : left.id > right.id ? 1 : 0),
   );
   let selections = [{}];
   for (const axis of axes) {
@@ -246,13 +296,17 @@ const DEPENDENCY_PROJECTION_CODES = new Set([
 ]);
 
 function validateWorkspaceProjections(product, foundation, libraries = []) {
+  // The Presentation being projected, so a failing Instance is found in it
+  // and not in another Screen that reuses its node id.
+  let projecting;
   try {
     for (const context of contextSelections(product, foundation)) {
       listEffectiveTokens(product, { context, foundation, libraries });
     }
     for (const entry of product.manifest.entries.screens) {
       const screen = product.entries[entry];
-      for (const presentation of screen.presentations) {
+      for (const [index, presentation] of screen.presentations.entries()) {
+        projecting = `${entry}.presentations[${index}]`;
         projectScreen(product, screen.id, {
           foundation,
           libraries,
@@ -260,6 +314,7 @@ function validateWorkspaceProjections(product, foundation, libraries = []) {
         });
       }
     }
+    projecting = undefined;
     for (const scenario of product.domain.scenarios.values()) {
       projectScenario(product, scenario.id, { foundation, libraries });
     }
@@ -276,7 +331,9 @@ function validateWorkspaceProjections(product, foundation, libraries = []) {
     if (!path && error.details.instanceId) {
       const suffix = `.nodes.${error.details.instanceId}.instance.component`;
       const usage = externalReferences(product).find((candidate) =>
-        candidate.path.endsWith(suffix),
+        projecting
+          ? candidate.path === `${projecting}${suffix}`
+          : candidate.path.endsWith(suffix),
       );
       path = usage?.path;
       reference = usage?.reference;
@@ -305,6 +362,83 @@ function validateWorkspaceProjections(product, foundation, libraries = []) {
   }
 }
 
+// Instances of the Product whose selection no variant of their Component
+// Set has any more (the Foundation renamed a value or deleted the variant).
+// They still draw, with the closest variant (`degraded` conflicts let reads
+// go on); the Product waits in Repair for one of the typed choices: select
+// a variant, or remove the Instance (or retarget it, as any reference).
+function staleInstanceConflicts(product, foundation, libraries = []) {
+  const sets = new Map([[product.manifest.packageId, product.domain.componentSets]]);
+  for (const owner of [foundation, ...libraries]) {
+    if (owner) sets.set(owner.manifest.packageId, owner.domain.componentSets);
+  }
+  const conflicts = [];
+  const check = (instance, path, nodePath, target) => {
+    const reference = instance?.component;
+    const componentSet = sets.get(reference?.packageId)?.get(reference?.assetId);
+    if (!componentSet || findComponentVariant(componentSet, instance.variant ?? {}).variant) {
+      return;
+    }
+    const closest = closestComponentVariant(componentSet, instance.variant);
+    const select = closest
+      ? [
+          {
+            action: "select-instance-variant",
+            referencePath: `${nodePath}.instance`,
+            selection: structuredClone(closest.selection),
+            validSelections: componentSet.variants.map((variant) =>
+              structuredClone(variant.selection),
+            ),
+            ...target,
+          },
+        ]
+      : [];
+    conflicts.push({
+      ...conflict(
+        "missing_variant",
+        `Instance ${target.nodeId} selects ${JSON.stringify(instance.variant ?? {})}, ` +
+          `which no variant of ${reference.assetId} has. It draws as ` +
+          `${JSON.stringify(closest?.selection ?? {})} until it is repaired`,
+        `${path}`,
+        [...select, ...referenceRepairChoices(path, reference)],
+      ),
+      degraded: true,
+      reference: structuredClone(reference),
+    });
+  };
+  for (const entry of product.manifest.entries.screens) {
+    const screen = product.entries[entry];
+    screen.presentations.forEach((presentation, index) => {
+      for (const [nodeId, node] of Object.entries(presentation.nodes)) {
+        if (!node.instance) continue;
+        const nodePath = `${entry}.presentations[${index}].nodes.${nodeId}`;
+        check(node.instance, `${nodePath}.instance.component`, nodePath, {
+          nodeId,
+          presentationId: presentation.id,
+          screenId: screen.id,
+        });
+      }
+    });
+  }
+  for (const entry of product.manifest.entries.components) {
+    (product.entries[entry].componentSets ?? []).forEach((componentSet, setIndex) => {
+      componentSet.variants.forEach((variant, variantIndex) => {
+        for (const [nodeId, node] of Object.entries(variant.nodes)) {
+          if (!node.instance) continue;
+          const nodePath =
+            `${entry}.componentSets[${setIndex}].variants[${variantIndex}].nodes.${nodeId}`;
+          check(node.instance, `${nodePath}.instance.component`, nodePath, {
+            componentSetId: componentSet.id,
+            nodeId,
+            variantId: variant.id,
+          });
+        }
+      });
+    });
+  }
+  return conflicts;
+}
+
 function chooseLibrarySource(library) {
   return {
     action: "choose-library-source",
@@ -313,14 +447,35 @@ function chooseLibrarySource(library) {
   };
 }
 
+// Remote Libraries declare their own child Libraries, so a Library server
+// could generate an endless chain of new Package IDs (or a huge fan-out) and
+// keep resolution downloading and caching forever. Every declaration the
+// resolution follows counts against one budget.
+export const MAX_LIBRARY_DECLARATIONS = 256;
+
 async function resolveDeclaredLibraries(owners, options, workspaceRoot) {
   const conflicts = [];
   const records = new Map();
   const warnings = [];
+  let declarations = 0;
 
   const visit = async (owner, library, index, depth, stack) => {
     const path = `manifest.json.libraries[${index}]`;
     const choice = chooseLibrarySource(library);
+    declarations += 1;
+    if (declarations > MAX_LIBRARY_DECLARATIONS) {
+      if (declarations === MAX_LIBRARY_DECLARATIONS + 1) {
+        conflicts.push(
+          conflict(
+            "library_limit_exceeded",
+            `Library resolution stopped after ${MAX_LIBRARY_DECLARATIONS} Library declarations`,
+            path,
+            [choice],
+          ),
+        );
+      }
+      return;
+    }
     if (stack.has(library.packageId)) {
       conflicts.push(
         conflict(
@@ -335,12 +490,7 @@ async function resolveDeclaredLibraries(owners, options, workspaceRoot) {
     let snapshot;
     try {
       if (library.source.type === "url") {
-        snapshot = await openRemoteLibrary(library.source.url, {
-          cacheRoot: options.libraryCacheRoot,
-          expectedPackageId: library.packageId,
-          fetchImpl: options.fetchImpl,
-          refresh: options.refreshRemoteLibraries === true,
-        });
+        snapshot = await remoteLibrarySnapshot(library, options);
       } else {
         if (owner.remote) {
           throw new SmallPenError(
@@ -349,7 +499,7 @@ async function resolveDeclaredLibraries(owners, options, workspaceRoot) {
             { packageId: library.packageId },
           );
         }
-        const candidate = resolve(dirname(owner.locator), library.source.path);
+        const candidate = localLibraryLocator(owner.locator, library.source);
         const locator = await realpath(candidate);
         snapshot = await openPackage(locator);
         if (!isWithinRoot(workspaceRoot, locator)) {
@@ -363,10 +513,16 @@ async function resolveDeclaredLibraries(owners, options, workspaceRoot) {
         }
       }
     } catch (error) {
+      // A Package chooses its URL Libraries: report only the typed code, never
+      // upstream status or transport text a Package could use as a probe.
+      const reason =
+        library.source.type === "url"
+          ? (error?.code ?? "remote_library_unavailable")
+          : error.message;
       conflicts.push(
         conflict(
           "library_unavailable",
-          `Library ${library.packageId} cannot be opened: ${error.message}`,
+          `Library ${library.packageId} cannot be opened: ${reason}`,
           `${path}.source`,
           [choice],
         ),
@@ -407,7 +563,7 @@ async function resolveDeclaredLibraries(owners, options, workspaceRoot) {
       warnings.push(
         warning(
           "remote_library_offline",
-          `Library ${snapshot.manifest.name} is using its last verified cache: ${snapshot.remote.warning}`,
+          `Library ${snapshot.manifest.name} is using its last verified cache: ${snapshot.remote.warningCode}`,
           `${path}.source.url`,
         ),
       );
@@ -563,6 +719,11 @@ export async function resolveWorkspace(productLocator, options = {}) {
       ...validateWorkspaceProjections(product, foundation, resolved.libraries),
     );
   }
+  if (conflicts.length === 0) {
+    conflicts.push(
+      ...staleInstanceConflicts(product, foundation, resolved.libraries),
+    );
+  }
   if (conflicts.length > 0) {
     return repair(product, conflicts, foundation, resolved.libraries, warnings);
   }

package/src/webp-decode.mjs

@@ -1,73 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
-import { createRequire } from "node:module";
-import { fileURLToPath } from "node:url";
-
-import { SmallPenError } from "@smallpen/core";
-
-// WebP static decoding via Google's libwebp compiled to WebAssembly
-// (@jsquash/webp, BSD-3). The emscripten codec is pre-loaded with its .wasm
-// bytes read from disk so decoding also works in the Node CLI (SP-031).
-const here = dirname(fileURLToPath(import.meta.url));
-const require_ = createRequire(import.meta.url);
-
-let decoderModule;
-let decoderInitPromise;
-
-async function loadDecoder() {
-  if (decoderModule) return decoderModule;
-  decoderInitPromise ??= (async () => {
-    const { default: webpDec } = await import(
-      "@jsquash/webp/codec/dec/webp_dec.js"
-    );
-    // Resolve the wasm via Node module resolution (works in workspace and
-    // packaged CLI layouts).
-    const wasmPath = require_.resolve("@jsquash/webp/codec/dec/webp_dec.wasm");
-    const wasmBinary = await readFile(wasmPath);
-    decoderModule = await webpDec({ wasmBinary, noInitialRun: true });
-    return decoderModule;
-  })();
-  return decoderInitPromise;
-}
-
-export async function initWebpDecoder() {
-  await loadDecoder();
-}
-
-// Synchronous decode of a complete WebP image to RGBA pixels. Requires a
-// prior initWebpDecoder(); the renderer initializes it once per projection.
-export function decodeWebpSync(bytes, diagnostics, path) {
-  let module;
-  try {
-    module = decoderModule;
-  } catch {
-    module = undefined;
-  }
-  if (!module) {
-    throw new SmallPenError(
-      "media_decode_failed",
-      "WebP decoder is not initialized",
-      { path },
-    );
-  }
-  try {
-    const result = module.decode(
-      bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes),
-    );
-    if (!result) throw new Error("decoder returned no image");
-    return {
-      width: result.width,
-      height: result.height,
-      pixels: new Uint8ClampedArray(result.data),
-    };
-  } catch (error) {
-    diagnostics?.push({
-      code: "media_decode_failed",
-      message: `Renderer could not decode WebP image: ${
-        error instanceof Error ? error.message : String(error)
-      }`,
-      path,
-    });
-    return undefined;
-  }
-}