@mosetta/build 0.0.0-stage → 0.0.9

package/src/scanner.mjs

@@ -0,0 +1,397 @@
+import { path } from './nodeApi.mjs';
+import { parse as parseYaml } from 'yaml';
+import { depPathToFilename } from '@pnpm/dependency-path';
+
+/**
+ * Package catalog scanner: LOCKFILE scan + CODE scan, portable.
+ *
+ * The input is exactly what a scanner isolate would have: a file port under which the
+ * distributive sources and the lockfile live. No node_modules traversal, no `createRequire`,
+ * no direct disk access: the "(importer, name) → package dir" edges are read from the lock,
+ * the narrowing seeds come from bare specifiers in the sources and from `mosetta.json`, and the
+ * closure is completed over the lock edges without reading third-party code. In dev the CLI
+ * calls this same scanner before every build iteration.
+ *
+ * The package-manager extension point is the LOCK ADAPTER (contract: "(port, lock dir) →
+ * edges + devNames"); narrowing, seeds and the devDependencies policy on top of it are
+ * manager-agnostic. Supported dialects are those whose lock carries the layout itself:
+ *   - pnpm-lock v9 — YAML parsed by the `yaml` package, `.pnpm` directory names produced by
+ *     the native `@pnpm/dependency-path` (the same code pnpm itself uses);
+ *   - package-lock v2/v3 (npm) — the layout is written directly into the `packages` keys
+ *     (`node_modules/foo/node_modules/react`), walk-up follows those same keys.
+ * yarn/bun — deferred: their lock does NOT carry the layout (the hoister computes it at
+ * install time); dev support will come through indexer tables rather than a hoister
+ * reimplementation.
+ */
+
+const MAX_WALK_UP = 50;
+// pnpm collapses a long peer suffix into a hash starting at this length — pnpm's own default
+const PEER_DIR_MAX_LENGTH = 120;
+
+// Dialects, in order of preference when both exist in one directory: pnpm first — it is our
+// native manager and its lock is the most precise (versioned paths instead of hoisting).
+const LOCK_DIALECTS = [
+  { file: 'pnpm-lock.yaml', read: readPnpmLock },
+  { file: 'package-lock.json', read: readNpmLock },
+];
+// recognized but unsupported locks — so the error names the manager instead of "nothing found"
+const KNOWN_UNSUPPORTED_LOCKS = { 'yarn.lock': 'yarn', 'bun.lock': 'bun', 'bun.lockb': 'bun' };
+
+// ALL locks up the chain (nearest to farthest): a nested project carries its own lock, but its
+// resolution still sees the parent one — same directionality as node_modules walk-up.
+function findLocks(fileSystem, startDir) {
+  const locks = [];
+  let dir = startDir;
+  for (let i = 0; i < MAX_WALK_UP; i++) {
+    const dialect = LOCK_DIALECTS.find((d) => fileSystem.exists(path.join(dir, d.file)));
+    if (dialect) locks.push({ dir, read: dialect.read });
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return locks;
+}
+
+// snapshot depPath → package dir in .pnpm ('react-dom@19.2.0(react@19.2.0)' → …/react-dom)
+function snapshotDirOf(lockfileDir, depPath) {
+  const cut = depPath.indexOf('@', 1); // for scoped packages the first @ is part of the name
+  return path.join(
+    lockfileDir, 'node_modules', '.pnpm',
+    depPathToFilename(depPath, PEER_DIR_MAX_LENGTH),
+    'node_modules', depPath.slice(0, cut),
+  );
+}
+
+// 'react-dom@19.2.0(react@19.2.0)' → dir in .pnpm; 'link:../../packages/x' → workspace dir
+function targetDirOf(lockfileDir, importerDir, name, version) {
+  if (version.startsWith('link:')) return path.resolve(importerDir, version.slice('link:'.length));
+  return path.join(
+    lockfileDir, 'node_modules', '.pnpm',
+    depPathToFilename(`${name}@${version}`, PEER_DIR_MAX_LENGTH),
+    'node_modules', name,
+  );
+}
+
+/**
+ * ALL edges of all locks up the chain (dialect adapters). devDependencies of importers do
+ * enter the edges but are flagged in `devNames` — the policy (dev sees them, prod rejects
+ * with an explanation) is applied by scanCatalog.
+ */
+export function loadLockEdges(fileSystem, startDir) {
+  const locks = findLocks(fileSystem, startDir);
+  if (!locks.length) {
+    // before saying "no lock at all", look for a lock of an unsupported manager — an error
+    // that names it is more useful than a generic one
+    let dir = startDir;
+    for (let i = 0; i < MAX_WALK_UP; i++) {
+      const found = Object.keys(KNOWN_UNSUPPORTED_LOCKS).find((f) => fileSystem.exists(path.join(dir, f)));
+      if (found) {
+        throw new Error(`found ${found} (${dir}), but ${KNOWN_UNSUPPORTED_LOCKS[found]} is not supported: `
+          + `its lock does not carry the package layout. Supported: pnpm (pnpm-lock.yaml v9) and npm `
+          + `(package-lock.json v2/v3); other managers will come through the indexer`);
+      }
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    throw new Error(`lockfile not found upwards from ${startDir} `
+      + `(supported: ${LOCK_DIALECTS.map((d) => d.file).join(', ')})`);
+  }
+  const edges = {}; // importerPkgDir -> { name -> pkgDir }
+  const devNames = {}; // importerPkgDir -> { name: true } — declared ONLY in devDependencies
+  for (const { dir, read } of locks) read(fileSystem, dir, edges, devNames);
+  return { lockfileDirs: locks.map((l) => l.dir), edges, devNames };
+}
+
+// --- pnpm-lock v9 adapter ------------------------------------------------------------------
+
+function readPnpmLock(fileSystem, lockfileDir, edges, devNames) {
+  const lock = parseYaml(fileSystem.readFile(path.join(lockfileDir, 'pnpm-lock.yaml'), 'utf8'));
+  if (!String(lock.lockfileVersion ?? '').startsWith('9')) {
+    throw new Error(`unsupported pnpm-lock version ${lock.lockfileVersion} (MVP: v9)`);
+  }
+  for (const [rel, entry] of Object.entries(lock.importers ?? {})) {
+    const dir = path.resolve(lockfileDir, rel);
+    const bucket = (edges[dir] ??= {});
+    for (const section of ['dependencies', 'optionalDependencies']) {
+      for (const [name, spec] of Object.entries(entry?.[section] ?? {})) {
+        bucket[name] ??= targetDirOf(lockfileDir, dir, name, spec.version);
+      }
+    }
+    for (const [name, spec] of Object.entries(entry?.devDependencies ?? {})) {
+      if (name in bucket) continue;
+      bucket[name] = targetDirOf(lockfileDir, dir, name, spec.version);
+      (devNames[dir] ??= {})[name] = true;
+    }
+  }
+  // bundledDependencies: the package SHIPS the dependency inside itself
+  // (`<pkg>/node_modules/<name>`) — it has no snapshot edges, but the lock does declare it
+  // and the layout is fixed by convention. lightningcss-wasm (napi-wasm inside) lives this way.
+  for (const [depPath, meta] of Object.entries(lock.packages ?? {})) {
+    const bundled = meta?.bundledDependencies;
+    if (!Array.isArray(bundled) || !bundled.length) continue;
+    const dir = snapshotDirOf(lockfileDir, depPath);
+    const bucket = (edges[dir] ??= {});
+    for (const bundledName of bundled) {
+      bucket[bundledName] ??= path.join(dir, 'node_modules', bundledName);
+    }
+  }
+  for (const [depPath, snap] of Object.entries(lock.snapshots ?? {})) {
+    const dir = snapshotDirOf(lockfileDir, depPath);
+    const bucket = (edges[dir] ??= {});
+    for (const section of ['dependencies', 'optionalDependencies']) {
+      for (const [depName, depVersion] of Object.entries(snap?.[section] ?? {})) {
+        bucket[depName] ??= targetDirOf(lockfileDir, dir, depName, depVersion);
+      }
+    }
+  }
+}
+
+// --- package-lock v2/v3 (npm) adapter ------------------------------------------------------
+
+// npm writes the layout DIRECTLY into the `packages` keys (`node_modules/foo/node_modules/react`),
+// so resolution walk-up replays over those same keys: the nearest `<prefix>/node_modules/<name>`
+// upwards from the importer's location. Workspaces come as a key pair: the alias
+// `node_modules/<name>` with `link: true` plus the real package path.
+function readNpmLock(fileSystem, lockfileDir, edges, devNames) {
+  const lock = fileSystem.readJson(path.join(lockfileDir, 'package-lock.json'));
+  const packages = lock.packages;
+  if (!packages) {
+    throw new Error(`unsupported package-lock version ${lock.lockfileVersion} (need v2/v3 with a "packages" map)`);
+  }
+  const dirOf = (location) => path.resolve(lockfileDir, location);
+  const targetOf = (location, name) => {
+    let prefix = location;
+    for (;;) {
+      const key = `${prefix ? `${prefix}/` : ''}node_modules/${name}`;
+      const entry = packages[key];
+      if (entry) return dirOf(entry.link && entry.resolved ? entry.resolved : key);
+      if (!prefix) return null; // not installed (e.g. an optional peer)
+      const cut = prefix.lastIndexOf('/node_modules/');
+      prefix = cut >= 0 ? prefix.slice(0, cut) : '';
+    }
+  };
+  for (const [location, entry] of Object.entries(packages)) {
+    if (entry?.link) continue; // workspace alias — the real path acts as the importer
+    const dir = dirOf(location);
+    const bucket = (edges[dir] ??= {});
+    // peerDependencies participate in the edges: npm installs peers (v7+) but declares them
+    // in a separate section; an uninstalled optional peer drops out by having no target
+    for (const section of ['dependencies', 'optionalDependencies', 'peerDependencies']) {
+      for (const name of Object.keys(entry?.[section] ?? {})) {
+        if (name in bucket) continue;
+        const target = targetOf(location, name);
+        if (target) bucket[name] = target;
+      }
+    }
+    // devDependencies are installed only for the root and workspaces — nested node_modules have none
+    if (!location.includes('node_modules')) {
+      for (const name of Object.keys(entry?.devDependencies ?? {})) {
+        if (name in bucket) continue;
+        const target = targetOf(location, name);
+        if (target) {
+          bucket[name] = target;
+          (devNames[dir] ??= {})[name] = true;
+        }
+      }
+    }
+  }
+}
+
+// --- code scan: greedy specifier collection ------------------------------------------------
+
+const SOURCE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+const SKIP_DIRS = new Set(['node_modules', 'dist', '.git']);
+// Greedy lexer walk: precision only affects the SIZE of the closure, not correctness —
+// rebuilding extra packages is cheap, and a miss surfaces as a resolve error at build time.
+const SPECIFIER_RE = /\bfrom\s*['"]([^'"\n]+)['"]|\bimport\s*\(?\s*['"]([^'"\n]+)['"]|\brequire\s*\(\s*['"]([^'"\n]+)['"]/g;
+
+function packageNameOf(specifier) {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+/** Build config file name: its imports are TOOLING and get their own closure (see below). */
+export const BUILD_CONFIG_FILE = 'mosetta.build.mjs';
+
+/** Bare specifiers of a single file. */
+function specifiersOfFile(fileSystem, file) {
+  const found = new Set();
+  let text;
+  try {
+    text = fileSystem.readFile(file, 'utf8');
+  } catch {
+    return found;
+  }
+  for (const m of text.matchAll(SPECIFIER_RE)) {
+    const spec = m[1] ?? m[2] ?? m[3];
+    if (spec && !spec.startsWith('.') && !path.isAbsolute(spec) && !spec.startsWith('node:')) found.add(spec);
+  }
+  return found;
+}
+
+/**
+ * Bare specifiers of all sources under rootDir (recursive, skipping node_modules/dist).
+ * `skipFiles` — file names whose imports do NOT enter this closure (the build config).
+ */
+export function scanSourceSpecifiers(fileSystem, rootDir, { skipFiles = new Set() } = {}) {
+  const found = new Set();
+  const walk = (dir) => {
+    let entries;
+    try {
+      entries = fileSystem.readDir(dir);
+    } catch {
+      return;
+    }
+    for (const e of entries) {
+      if (e.isDirectory) {
+        if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) walk(path.join(dir, e.name));
+        continue;
+      }
+      if (!SOURCE_EXTENSIONS.has(path.extname(e.name))) continue;
+      if (skipFiles.has(e.name)) continue;
+      for (const spec of specifiersOfFile(fileSystem, path.join(dir, e.name))) found.add(spec);
+    }
+  };
+  walk(rootDir);
+  return found;
+}
+
+// --- composition: seeds → closure over the lock --------------------------------------------
+
+/**
+ * PRODUCT closure of the distributive: lock edges narrowed to the seeds — imports of the
+ * sources (EXCEPT the build config) and the mosetta.json libraries — plus the framework layer
+ * as a whole. Packages outside the closure do not enter the catalog: importing an undeclared
+ * one is a resolve error.
+ *
+ * devDependencies policy is a parity policy:
+ *   - prod (`includeDev: false`): devDeps edges are CUT OUT and the names go to
+ *     `catalog.devOnly` — the resolver throws on them with a "move to dependencies" explanation;
+ *   - dev (`includeDev: true`): the edges are available (devLibraries live exactly there), but
+ *     a source seed resolved through devDependencies immediately gets a warning in `log`.
+ *
+ * Imports of `mosetta.build.mjs` do NOT enter this closure: the build config is a TOOL, its
+ * dependencies legitimately live in devDependencies, and demanding `dependencies` for them
+ * would be harmful advice. They get their own closure — `scanToolingCatalog`.
+ */
+export function scanCatalog({ fileSystem, root, frameworkDir, includeDev = true, log = () => {} }) {
+  const { edges: full, devNames } = loadLockEdges(fileSystem, root);
+  if (!includeDev) {
+    for (const [dir, names] of Object.entries(devNames)) {
+      for (const name of Object.keys(names)) delete full[dir]?.[name];
+    }
+  }
+
+  // walk-up contexts: lock importers through which the seeds are visible (root and ancestors)
+  const contexts = Object.keys(full)
+    .filter((d) => root === d || root.startsWith(d + path.sep))
+    .sort((a, b) => b.length - a.length); // nearest first — node ordering
+
+  const names = new Set(
+    [...scanSourceSpecifiers(fileSystem, root, { skipFiles: new Set([BUILD_CONFIG_FILE]) })].map(packageNameOf),
+  );
+  let cfg = null;
+  try {
+    cfg = fileSystem.readJson(path.join(root, 'mosetta.json'));
+  } catch { /* not a distributive — imports only */ }
+  for (const lib of [...(cfg?.libraries ?? []), ...(cfg?.devLibraries ?? [])]) {
+    names.add(packageNameOf(lib));
+  }
+
+  const keep = new Set(contexts);
+  const queue = [];
+  const enqueue = (dir) => {
+    if (!keep.has(dir)) {
+      keep.add(dir);
+      queue.push(dir);
+    }
+  };
+  for (const name of names) {
+    const ctx = contexts.find((c) => full[c]?.[name]);
+    if (!ctx) continue; // greedy-scan noise or an honest phantom (fails at resolve)
+    if (devNames[ctx]?.[name]) {
+      log(`  ! ${name} is declared in devDependencies (${ctx}) — a prod build will not resolve it; move it to dependencies`);
+    }
+    enqueue(full[ctx][name]);
+  }
+  // framework layer as a whole: generated facets import from the tool's installation
+  keep.add(frameworkDir);
+  for (const target of Object.values(full[frameworkDir] ?? {})) enqueue(target);
+  while (queue.length) {
+    const dir = queue.shift();
+    for (const target of Object.values(full[dir] ?? {})) enqueue(target);
+  }
+
+  const edges = {};
+  for (const dir of keep) {
+    const bucket = full[dir];
+    if (!bucket) continue;
+    const filtered = {};
+    for (const [name, target] of Object.entries(bucket)) {
+      if (keep.has(target)) filtered[name] = target;
+    }
+    edges[dir] = filtered;
+  }
+  const devOnly = {};
+  if (!includeDev) {
+    for (const dir of keep) {
+      if (devNames[dir]) devOnly[dir] = devNames[dir];
+    }
+  }
+  return { edges, devOnly };
+}
+
+/**
+ * BUILD CONFIG closure: seeds are the imports of `mosetta.build.mjs` and the specifiers of its
+ * `buildConfigWasm` knob. Here devDependencies are ALWAYS allowed, with no warnings: a build
+ * tool (an scss compiler, lightningcss-wasm, …) is exactly what should live in devDependencies
+ * rather than in product dependencies.
+ *
+ * The closure is SEPARATE, not an extension of the product one: otherwise tooling would leak
+ * into the product-code catalog — a client module could import a build package that is not in
+ * its dependencies.
+ */
+export function scanToolingCatalog({ fileSystem, root, frameworkDir }) {
+  const { edges: full } = loadLockEdges(fileSystem, root);
+  const contexts = Object.keys(full)
+    .filter((d) => root === d || root.startsWith(d + path.sep))
+    .sort((a, b) => b.length - a.length);
+
+  const names = new Set(
+    [...specifiersOfFile(fileSystem, path.join(root, BUILD_CONFIG_FILE))].map(packageNameOf),
+  );
+  try {
+    const cfg = fileSystem.readJson(path.join(root, 'mosetta.json'));
+    for (const spec of Object.values(cfg?.buildConfigWasm ?? {})) names.add(packageNameOf(spec));
+  } catch { /* no mosetta.json — config imports only */ }
+
+  const keep = new Set([...contexts, frameworkDir]);
+  const queue = [];
+  const enqueue = (dir) => {
+    if (!keep.has(dir)) {
+      keep.add(dir);
+      queue.push(dir);
+    }
+  };
+  for (const name of names) {
+    const ctx = contexts.find((c) => full[c]?.[name]);
+    if (ctx) enqueue(full[ctx][name]);
+  }
+  while (queue.length) {
+    const dir = queue.shift();
+    for (const target of Object.values(full[dir] ?? {})) enqueue(target);
+  }
+
+  const edges = {};
+  for (const dir of keep) {
+    const bucket = full[dir];
+    if (!bucket) continue;
+    const filtered = {};
+    for (const [name, target] of Object.entries(bucket)) {
+      if (keep.has(target)) filtered[name] = target;
+    }
+    edges[dir] = filtered;
+  }
+  return { edges };
+}

package/src/settings.mjs

@@ -0,0 +1,39 @@
+import { path } from './nodeApi.mjs';
+import { portResolveEsbuild } from './plugins/portResolveEsbuild.mjs';
+import { monolithCompat, monolithCompatOptions } from './plugins/monolithCompat.mjs';
+import { MONOLITH_CONDITIONS } from './conditions.mjs';
+
+// A BLOCK'S SETTINGS SCHEMA in its catalog entry. A block may describe what its node keeps in
+// `settings` — `<name>/<name>.settings.ts` beside its module, exporting `settings` (a schema of
+// @mosetta/settings). The build bundles that file with what turns it into JSON Schema and has the
+// HOST run it: the build itself executes nothing (`evaluate` is a capability the environment
+// supplies — the CLI runs it in node). Without one, the catalog goes without schemas: a block
+// still works, only nothing can tell what it takes.
+
+export const SETTINGS_SUFFIX = '.settings.ts';
+
+const ENTRY = (file) => `export { settings } from ${JSON.stringify(`./${path.basename(file)}`)};
+export { settingsJsonSchema } from '@mosetta/settings';
+`;
+
+/** the JSON Schema of a block's settings and the files it came from */
+export async function describeSettings(fileSystem, file, { resolver, engine, evaluate, frameworkDir, sourceBase }) {
+  const watched = new Set([file]);
+  const result = await engine.bundle({
+    stdin: { contents: ENTRY(file), resolveDir: path.dirname(file), sourcefile: 'settings.entry.ts', loader: 'ts' },
+    bundle: true,
+    format: 'esm',
+    platform: 'neutral',
+    target: 'es2022',
+    write: false,
+    logLevel: 'silent',
+    plugins: [monolithCompat(fileSystem, resolver), portResolveEsbuild(fileSystem, resolver, frameworkDir, MONOLITH_CONDITIONS, watched)],
+    ...monolithCompatOptions(),
+    ...(sourceBase ? { absWorkingDir: sourceBase } : {}),
+  });
+  const described = await evaluate(result.outputFiles[0].text);
+  if (!described?.settings || typeof described.settingsJsonSchema !== 'function') {
+    throw new Error(`${file}: exports no \`settings\` schema`);
+  }
+  return { schema: described.settingsJsonSchema(described.settings), watchFiles: [...watched] };
+}

package/src/sourcemap.mjs

@@ -0,0 +1,26 @@
+import { path } from './nodeApi.mjs';
+
+/**
+ * Unified `sources` form in sourcemaps.
+ *
+ * The engines relativize paths differently and both badly: native rollup — against
+ * `process.cwd()` (the form depends on which directory the build runs from), `@rollup/browser` —
+ * against `/`, because it has no `cwd` at all. We normalize to a path RELATIVE TO THE ROOT of
+ * the distributive: the engines start to agree, and the form stops depending on the machine and
+ * the launch directory.
+ *
+ * The engines can be told apart by what they put in `sourcemapPath`: the native one gives an
+ * absolute path (and `rel` relative to it), the wasm one — a bare file name (and `rel` = an
+ * absolute path without the leading slash). This contract is pinned by `sourcemapForm`.
+ *
+ * Changing the form is safe: `sourcesContent` is inlined into the maps, so `sources` acts as a
+ * label in devtools, not as a load address.
+ */
+export function sourcemapPathTransformFor(sourceBase) {
+  return (relativeSourcePath, sourcemapPath) => {
+    const absolute = sourcemapPath && path.isAbsolute(sourcemapPath)
+      ? path.resolve(path.dirname(sourcemapPath), relativeSourcePath)
+      : path.resolve('/', relativeSourcePath);
+    return path.relative(sourceBase, absolute).split(path.sep).join('/');
+  };
+}

package/src/specifiers.mjs

@@ -0,0 +1,76 @@
+// External-dependency resolution + version-qualified identity.
+// Single source of truth for "given a bare specifier, what artifact (full-id, file, version)
+// does it build into" — shared by the closure walker (build.mjs) and the per-build external
+// rewriter (output.paths in buildModules/buildDependencies).
+import { builtinModules } from './nodeApi.mjs';
+import { dependencyFullId } from '@mosetta/runtime/naming';
+import { CLIENT_CONDITIONS } from './conditions.mjs';
+import { applyBrowserField, applyBrowserEntry } from './browserField.mjs';
+import { packageVersionOf } from './packageMeta.mjs';
+
+// `builtinModules` is pure DATA (a list of names), not I/O: target-environment policy
+// (the browser has no node builtins), not a build-host capability — hence not in the port.
+export const BUILTINS = new Set([...builtinModules, ...builtinModules.map((m) => `node:${m}`)]);
+
+// node builtins → browser shims. EMPTY on purpose: the last shim (crypto for object-hash) died
+// with the legacy hashing (cache keys switched to stableStringify). The mechanism stays —
+// an unshimmed builtin is warn-skipped below, and a future need slots a file back in here.
+export const SHIMS = {};
+
+// Framework runtime modules resolved specially into the closure: a component's bare
+// import of '@mosetta/runtime' gets the package's ROOT (asset) surface as a dependency artifact.
+// Resolved from the TOOL'S OWN installation (resolver.resolveFramework), not from the distributive.
+export const FRAMEWORK_SPECIFIERS = new Set(['@mosetta/runtime']);
+
+const SKIP_PREFIXES = ['@types/'];
+
+// Version-qualified id of an external dependency artifact — re-exported from the
+// shared naming module so the build and the runtime resolver form ids identically.
+export { dependencyFullId };
+
+/**
+ * Resolve a bare specifier to its built-dependency identity, as seen FROM `fromDir`
+ * (importer-relative resolution). Returns { specifier, full, resolvedFile, version, kind }
+ * or null when it must be skipped (@types, unresolvable, or an unshimmed node builtin).
+ */
+export function resolveSpecifier(fileSystem, resolver, specifier, fromDir, log = () => {}) {
+  if (SKIP_PREFIXES.some((p) => specifier.startsWith(p))) return null;
+
+  let resolvedFile;
+  let version;
+  let kind;
+  if (FRAMEWORK_SPECIFIERS.has(specifier)) {
+    resolvedFile = resolver.resolveFramework(specifier);
+    // the version of the runtime the tool brings — a new runtime is a new artifact, never new bytes
+    // under an old name
+    version = packageVersionOf(fileSystem, resolvedFile);
+    kind = 'framework';
+  } else if (BUILTINS.has(specifier)) {
+    const shim = SHIMS[specifier];
+    if (!shim) {
+      log(`  ! node builtin ${specifier} has no browser shim — left unresolved`);
+      return null;
+    }
+    resolvedFile = shim;
+    version = '0.0.0';
+    kind = 'builtin';
+  } else {
+    try {
+      const hit = resolver.resolve(specifier, fromDir, CLIENT_CONDITIONS);
+      const entry = applyBrowserEntry(fileSystem, specifier, hit, CLIENT_CONDITIONS);
+      const mapped = applyBrowserField(fileSystem, entry, CLIENT_CONDITIONS);
+      // a stub as a dependency ENTRY makes no sense — such a specifier is simply skipped
+      if (typeof mapped !== 'string' || mapped.startsWith('\0')) return null;
+      resolvedFile = mapped;
+    } catch (e) {
+      // a devDep in product code is not a "reason to skip" but a configuration error with a
+      // ready recipe: fail the build with an explanation instead of leaving a hole in the closure
+      if (e.code === 'DEV_DEPENDENCY') throw e;
+      log(`  ! unresolved ${specifier} (${e.code || e.message}) — skipped`);
+      return null;
+    }
+    version = packageVersionOf(fileSystem, resolvedFile);
+    kind = 'npm';
+  }
+  return { specifier, full: dependencyFullId(specifier, version), resolvedFile, version, kind };
+}