@jxsuite/compiler 7.0.0 → 8.0.0

package/src/site/format-host.ts

@@ -62,7 +62,23 @@ export async function importImplementation(path: string): Promise<Implementation
   throw lastError instanceof Error ? lastError : new Error(String(lastError));
 }
 
-/** Create a node FormatHostIO rooted at a project (bare specifiers resolve via node_modules). */
+/**
+ * Resolve a bare specifier from the PROJECT's own node_modules, and nowhere else.
+ *
+ * There is deliberately no host fallback (specs/extensions.md §3). Extensions, first-party ones
+ * included, reach a project only through its own install, the way a third-party extension must: a
+ * host that answered for `@jxsuite/parser` would let a project missing that dependency edit on one
+ * machine and fail to build on the next.
+ *
+ * @param {string} projectRoot
+ * @param {string} specifier - Bare specifier, e.g. "@jxsuite/parser/jx-extension.json"
+ * @returns {string} Absolute resolved path
+ */
+export function resolveFromProject(projectRoot: string, specifier: string): string {
+  return createRequire(resolve(projectRoot, "package.json")).resolve(specifier);
+}
+
+/** Create a node FormatHostIO rooted at a project (bare specifiers resolve from its node_modules). */
 export function createNodeFormatIO(projectRoot: string): FormatHostIO {
   return {
     importModule: (path) => importImplementation(path),
@@ -74,75 +90,39 @@ export function createNodeFormatIO(projectRoot: string): FormatHostIO {
       if (isAbsolute(ref)) {
         return ref;
       }
-      // Bare specifier — prefer the project's own node_modules, then fall back to the host's
-      // Resolution (the desktop app and dev server ship @jxsuite/parser, so format classes work
-      // Even when the project's dependencies are not installed).
-      const projRequire = createRequire(resolve(projectRoot, "package.json"));
-      try {
-        return projRequire.resolve(ref);
-      } catch {
-        const selfRequire = createRequire(import.meta.url);
-        return selfRequire.resolve(ref);
-      }
+      return resolveFromProject(projectRoot, ref);
     },
   };
 }
 
-/**
- * Where an extension package's manifest resolves from — the two answers `createNodeFormatIO`
- * merges.
- */
+/** Where an extension package's manifest resolves from the project, if it does. */
 export interface ExtensionResolution {
-  /** Resolvable from the PROJECT's own node_modules. */
+  /** Resolvable from the PROJECT's own node_modules — the only place an extension resolves from. */
   project: boolean;
-  /** Resolvable from the HOST's module graph — `createNodeFormatIO`'s fallback branch. */
-  host: boolean;
-  /** The manifest path from whichever probe answered; the project wins, matching resolution order. */
+  /** The resolved manifest path, when `project` is true. */
   manifestPath?: string;
 }
 
 /**
- * Split `createNodeFormatIO`'s two-branch resolution into its two ANSWERS.
- *
- * The IO deliberately collapses them (project first, then host) because a caller loading a class
- * only needs the file. A catalogue needs them apart: "the project installed this" and "this host
- * ships it" are different affordances — install-then-enable versus enable — and a surface that
- * cannot tell them apart offers the wrong one.
+ * Probe whether a project resolves an extension package, without loading it.
  *
  * Probes the MANIFEST rather than the package directory, because the manifest is what the registry
  * resolves (see `loadExtension`): a package present in node_modules whose `exports` map omits
  * `./jx-extension.json` is one whose enablement would throw, so it must not read as resolvable.
  *
- * @param {string} projectRoot - The project whose node_modules is tried first
+ * @param {string} projectRoot - The project whose node_modules is probed
  * @param {string} name - Bare package specifier, e.g. "@jxsuite/parser"
  * @returns {ExtensionResolution}
  */
 export function probeExtension(projectRoot: string, name: string): ExtensionResolution {
-  const ref = `${name}/${EXTENSION_MANIFEST}`;
-  let manifestPath: string | undefined;
-
-  let project = false;
-  try {
-    manifestPath = createRequire(resolve(projectRoot, "package.json")).resolve(ref);
-    project = true;
-  } catch {
-    // Not installed in the project. The host probe below decides whether it resolves at all.
-  }
-
-  let host = false;
   try {
-    const fromHost = createRequire(import.meta.url).resolve(ref);
-    host = true;
-    manifestPath ??= fromHost;
+    return {
+      manifestPath: resolveFromProject(projectRoot, `${name}/${EXTENSION_MANIFEST}`),
+      project: true,
+    };
   } catch {
-    // Not shipped by this host either.
+    return { project: false };
   }
-
-  const resolution: ExtensionResolution = { host, project };
-  if (manifestPath !== undefined) {
-    resolution.manifestPath = manifestPath;
-  }
-  return resolution;
 }
 
 /** Build the extension registry for a project from its project.json `extensions` array. */
@@ -157,6 +137,76 @@ export async function buildProjectExtensionRegistry(
   );
 }
 
+/** A registry of what a project has installed, and the enabled packages it has not. */
+export interface InstalledExtensionRegistry {
+  registry: ExtensionRegistry;
+  /** Bare specifiers `project.json` enables whose manifest the project does not resolve. */
+  missing: string[];
+}
+
+/**
+ * Build the registry an EDITOR needs: every enabled extension the project resolves, skipping the
+ * package ones it has not installed yet.
+ *
+ * A build must fail on a missing extension, and does, through {@link buildProjectExtensionRegistry}.
+ * A studio must not: a project opened before its install has run resolves none of its package
+ * extensions, and the format list, the extensions panel and the class picker should answer with
+ * what is there rather than with an error. `missing` says what was skipped, so the host can say so
+ * once instead of logging a resolution stack per request. Relative (local) extensions are never
+ * skipped, because no install produces them.
+ *
+ * @param {string} projectRoot
+ * @param {ProjectConfig} [projectConfig]
+ * @returns {Promise<InstalledExtensionRegistry>}
+ */
+export async function buildInstalledExtensionRegistry(
+  projectRoot: string,
+  projectConfig?: ProjectConfig,
+): Promise<InstalledExtensionRegistry> {
+  const missing: string[] = [];
+  const present: string[] = [];
+  for (const specifier of projectConfig?.extensions ?? []) {
+    const local = specifier.startsWith("./") || specifier.startsWith("../");
+    if (local || probeExtension(projectRoot, specifier).project) {
+      present.push(specifier);
+    } else {
+      missing.push(specifier);
+    }
+  }
+  const registry = await buildExtensionRegistry(
+    present,
+    createNodeFormatIO(projectRoot),
+    resolve(projectRoot, "project.json"),
+  );
+  return { missing, registry };
+}
+
+/**
+ * Whether any of a previous build's `missing` packages resolves now — the cache check a host runs
+ * so that a registry built before an install does not outlive it.
+ *
+ * @param {string} projectRoot
+ * @param {string[]} missing
+ * @returns {boolean}
+ */
+export function anyNowInstalled(projectRoot: string, missing: string[]): boolean {
+  return missing.some((specifier) => probeExtension(projectRoot, specifier).project);
+}
+
+/**
+ * The one line a host logs for the packages {@link buildInstalledExtensionRegistry} skipped.
+ *
+ * @param {string[]} missing
+ * @returns {string}
+ */
+export function missingExtensionsNotice(missing: string[]): string {
+  const names = missing.map((m) => `"${m}"`).join(", ");
+  return (
+    `project.json enables ${names}, which this project has not installed, so ` +
+    `${missing.length === 1 ? "it is" : "they are"} not loaded. Install the project's dependencies.`
+  );
+}
+
 // ─── Studio extensions payload ────────────────────────────────────────────────
 
 /** One project-section contribution on the studio wire (specs/extensions.md §9/§9.1). */

package/src/site/image-cache.ts

@@ -52,30 +52,56 @@ export function _testSetNpmCacheBase(value: string | null) {
   _npmCacheBase = value;
 }
 
+/**
+ * How long the npm probe may run before the build stops waiting and caches in the project.
+ *
+ * `npm config get cache` answers in a fraction of a second, but nothing bounded it, and the call is
+ * synchronous: when npm hung, the first build of the process hung with it. On a CI runner it
+ * stalled past both of the dev server's 5 s and 20 s test timeouts with nothing to show for it but
+ * "killed 1 dangling process". Missing the npm cache only costs persistence across builds.
+ */
+const NPM_PROBE_TIMEOUT_MS = 3000;
+
+/**
+ * Where npm keeps its cache, or null when npm cannot say.
+ *
+ * Npm reads its configuration from the environment as well as from `.npmrc`, and the environment
+ * wins, so a value there is npm's own answer and no process is needed to ask for it. A script run
+ * by a package manager usually has it there.
+ */
+function npmCacheBase(): string | null {
+  const fromEnv = process.env.npm_config_cache ?? process.env.NPM_CONFIG_CACHE;
+  if (fromEnv) {
+    return fromEnv;
+  }
+  try {
+    const result = execSync("npm config get cache", {
+      cwd: tmpdir(), // Avoid ENOWORKSPACES when cwd is inside an npm workspace
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: NPM_PROBE_TIMEOUT_MS,
+    }).trim();
+    return result && result !== "undefined" ? result : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Return the image cache directory for a project.
  *
  * Prefers the npm global cache (`npm config get cache`) so CI environments that cache ~/.npm (e.g.
  * Cloudflare Pages) automatically persist optimized images across builds. Falls back to
- * .cache/images inside the project root when npm is unavailable.
+ * .cache/images inside the project root when npm is unavailable or does not answer in time.
  *
- * Result is memoized — `npm config get cache` is only spawned once per process.
+ * Result is memoized — npm is asked at most once per process.
  *
  * @param {string} projectRoot
  * @returns {string}
  */
 export function getImageCacheDir(projectRoot: string): string {
   if (_npmCacheBase === undefined) {
-    try {
-      const result = execSync("npm config get cache", {
-        cwd: tmpdir(), // Avoid ENOWORKSPACES when cwd is inside an npm workspace
-        encoding: "utf8",
-        stdio: ["ignore", "pipe", "ignore"],
-      }).trim();
-      _npmCacheBase = result && result !== "undefined" ? result : null;
-    } catch {
-      _npmCacheBase = null;
-    }
+    _npmCacheBase = npmCacheBase();
   }
   if (_npmCacheBase) {
     return resolve(_npmCacheBase, "jxsuite-images", basename(projectRoot));

package/src/site/schema-command.ts

@@ -24,7 +24,7 @@ import {
   flattenSchema,
 } from "@jxsuite/schema/project-schemas";
 import { isJsonObject } from "@jxsuite/schema/guards";
-import { buildProjectExtensionRegistry } from "./format-host.ts";
+import { buildProjectExtensionRegistry, resolveFromProject } from "./format-host.ts";
 import { loadProjectConfig } from "./site-loader.ts";
 import type { ExtensionInfo } from "@jxsuite/schema/extension-registry";
 import type { SchemaJsonLoader } from "@jxsuite/schema/project-schemas";
@@ -156,21 +156,24 @@ function readSchemaFile(path: string): JsonObject {
   return parsed;
 }
 
-/** Packages whose schemas define the Jx document contract itself, never a project's own content. */
-const FIRST_PARTY_SCHEMA_SCOPE = "@jxsuite/";
+/**
+ * The package whose schemas define the Jx document contract itself. Only the core: an extension's
+ * fragments, first-party ones included, are the project's (specs/extensions.md §5.4).
+ */
+const CORE_SCHEMA_SCOPE = "@jxsuite/schema/";
 
 /**
- * Is this specifier one of the shipped core schemas, as opposed to a project-local fragment?
+ * Is this specifier one of the shipped core schemas, as opposed to an extension's fragment?
  *
  * @param {string} specifier - Bare specifier, e.g. `@jxsuite/schema/schema.json`
  * @returns {boolean}
  */
-export function isFirstPartySchema(specifier: string): boolean {
-  return specifier.startsWith(FIRST_PARTY_SCHEMA_SCOPE) && specifier.endsWith(".json");
+export function isCoreSchema(specifier: string): boolean {
+  return specifier.startsWith(CORE_SCHEMA_SCOPE) && specifier.endsWith(".json");
 }
 
 /**
- * Resolve a first-party schema from the HOST — the workspace running the generator.
+ * Resolve the core schema from the HOST — the workspace running the generator.
  *
  * Throws rather than falling back to the project, because a fallback is exactly the behaviour that
  * let a stale published core answer for the workspace one. A generator that cannot find its own
@@ -185,7 +188,7 @@ function hostResolve(specifier: string, path: string): string {
     return createRequire(import.meta.url).resolve(specifier);
   } catch (error) {
     throw new Error(
-      `Schema ref "${path}" names the first-party schema "${specifier}", which must resolve from ` +
+      `Schema ref "${path}" names the core schema "${specifier}", which must resolve from ` +
         `the host workspace and does not. The project's own copy is deliberately not consulted, so ` +
         `the host install is missing "${specifier.split("/").slice(0, 2).join("/")}" — check that ` +
         `the package ships with this build`,
@@ -195,9 +198,10 @@ function hostResolve(specifier: string, path: string): string {
 }
 
 /**
- * Bundler loader restricted to the project root, with the validate-project host fallback: a missing
- * `<root>/node_modules/<specifier>` file resolves the specifier project-first, then through the
- * host (workspace symlinks resolve transparently).
+ * Bundler loader restricted to the project root. The core schema comes from the host; every other
+ * `<root>/node_modules/<specifier>` ref that is not on disk at that path resolves through the
+ * project's own module resolution (workspace symlinks and hoisted installs resolve transparently)
+ * and never through the host's, because an extension's fragments are the project's to supply.
  *
  * Exported for test: both refusals below are reachable only through a project whose `node_modules`
  * has been arranged to provoke them, and a fixture that arranges an extension registry as well says
@@ -217,9 +221,9 @@ export function restrictedSchemaLoader(root: string): SchemaJsonLoader {
     const marker = "node_modules/";
     const markerIndex = posixRel.lastIndexOf(marker);
     const specifier = markerIndex === -1 ? null : posixRel.slice(markerIndex + marker.length);
-    // A FIRST-PARTY core comes from the host, always — before the project-local file is even
-    // Looked at. A project may legitimately carry its own fragments, which is what the rest of this
-    // Loader is for; what it may not do is answer for `@jxsuite/schema` itself.
+    // The core comes from the host, always — before the project-local file is even looked at. A
+    // Project supplies every extension's fragments, first-party ones included, which is what the
+    // Rest of this loader is for; what it may not do is answer for `@jxsuite/schema` itself.
     //
     // This is not hypothetical. A stray `bun install` in packages/starters/sites/shop left a
     // Gitignored node_modules holding @jxsuite/schema@0.35.0 beside a 1.5.0 workspace, and BOTH the
@@ -230,7 +234,7 @@ export function restrictedSchemaLoader(root: string): SchemaJsonLoader {
     // Shop's own pages/products/[sku].json invalid against its own committed schema. Nothing
     // Noticed for six weeks, because the artifact was only ever regenerated on the machine that
     // Had the shadow.
-    if (specifier !== null && isFirstPartySchema(specifier)) {
+    if (specifier !== null && isCoreSchema(specifier)) {
       return readSchemaFile(hostResolve(specifier, path));
     }
     if (existsSync(abs)) {
@@ -241,19 +245,13 @@ export function restrictedSchemaLoader(root: string): SchemaJsonLoader {
     }
     let resolved: string;
     try {
-      const projRequire = createRequire(resolve(root, "package.json"));
-      resolved = projRequire.resolve(specifier);
-    } catch {
-      try {
-        const selfRequire = createRequire(import.meta.url);
-        resolved = selfRequire.resolve(specifier);
-      } catch (error) {
-        throw new Error(
-          `Schema ref "${path}" does not exist and "${specifier}" is not resolvable from the ` +
-            `project or the host`,
-          { cause: error },
-        );
-      }
+      resolved = resolveFromProject(root, specifier);
+    } catch (error) {
+      throw new Error(
+        `Schema ref "${path}" does not exist and "${specifier}" is not resolvable from the ` +
+          `project — is the package installed?`,
+        { cause: error },
+      );
     }
     return readSchemaFile(resolved);
   };