@webjsdev/server 0.8.20 → 0.8.22

package/src/vendor.js

@@ -44,6 +44,7 @@ import { readFile, readdir, writeFile, mkdir, unlink, stat, rename } from 'node:
 import { readFileSync, existsSync, realpathSync } from 'node:fs';
 import { join, dirname, basename, sep } from 'node:path';
 import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
 import { digestBase64 } from './crypto-utils.js';
 import { BUFFERED_MARKER } from './conditional-get.js';
 
@@ -257,13 +258,48 @@ export function getPackageVersion(pkgName, appDir) {
   }
 }
 
+/**
+ * Read the installed package's declared `dependencies` + `peerDependencies`
+ * from its `package.json`, hoist-aware (same resolution as `getPackageVersion`,
+ * so a monorepo-hoisted dep resolves from the workspace root). Returns null
+ * when the package is not installed / unreadable, which the importmap-coherence
+ * check (#450) treats as "could not verify" rather than a conflict.
+ *
+ * This is the "already-resolved metadata, no network" source the coherence
+ * check prefers: the package is on disk because the importmap pinned it, so its
+ * manifest is a local read.
+ *
+ * @param {string} pkgName
+ * @param {string} appDir
+ * @returns {{ dependencies: Record<string,string>, peerDependencies: Record<string,string> } | null}
+ */
+export function getPackageManifest(pkgName, appDir) {
+  const real = resolvePackageDir(pkgName, appDir);
+  if (!real) return null;
+  try {
+    const pkg = JSON.parse(readFileSync(join(real, 'package.json'), 'utf8'));
+    return {
+      dependencies: pkg.dependencies || {},
+      peerDependencies: pkg.peerDependencies || {},
+    };
+  } catch {
+    return null;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // JSPM Generator API client
 // ---------------------------------------------------------------------------
 
 /**
  * In-memory cache of resolved importmap fragments from api.jspm.io.
- * Keyed by the sorted+joined list of `pkg@version` install specs.
+ * Two kinds of key share this map:
+ *   - The UNIFIED key (`<provider>::unified::<sorted installs joined>`)
+ *     caches the whole-set resolve produced by one `generate` call, the
+ *     default path (issue #446).
+ *   - The PER-INSTALL key (`<provider>::<install>`) caches a single
+ *     install's isolated resolve, used only on the fallback path when the
+ *     unified call fails because some install is unresolvable.
  * Per-process; cleared by `clearVendorCache` on file-watcher rebuild
  * so new versions get re-resolved.
  *
@@ -309,91 +345,144 @@ export function normalizeProvider(name) {
 }
 
 /**
- * Resolve a SINGLE `pkg@version` (or `pkg@version/subpath`) install via
- * api.jspm.io/generate. Returns the imports fragment (typically one or
- * two entries; subpath installs sometimes include the root package).
- *
- * Per-package isolation is the whole point: api.jspm.io/generate fails
- * the ENTIRE batch with a 401 when any single package can't be
- * resolved (e.g. a transitive that has no jspm.io-compatible exports).
- * Calling per-package means one bad dep can no longer poison the
- * importmap for legitimate deps.
- *
- * Cached in-process by the install spec + provider. Failures are
- * logged loudly with the package name and the reason jspm.io
- * returned.
+ * Outcome of one api.jspm.io/generate POST.
+ * @typedef {Object} JspmCallResult
+ * @property {boolean} ok        true when jspm returned a 2xx with a usable map
+ * @property {Record<string, string>} imports  the resolved imports (empty on failure)
+ * @property {boolean} transient true when the failure is worth retrying
+ *           (network / timeout / 5xx / 429), false for a permanent 4xx
+ *           (jspm uses 401 for "this install is unresolvable")
+ */
+
+/**
+ * Make ONE api.jspm.io/generate POST for a list of installs and return a
+ * structured result. The single point that talks to the network; both the
+ * unified path and the per-install fallback funnel through it.
+ *
+ * jspm fails the WHOLE batch (401) when ANY one install is unresolvable, so
+ * a multi-install POST is all-or-nothing: either the entire coherent graph
+ * comes back, or nothing does. `jspmGenerate` uses that property to decide
+ * when to fall back to per-install isolation.
+ *
+ * @param {Array<string>} installs  e.g. ['dayjs@1.11.13', '@codemirror/lint@6.9.6']
+ * @param {string} provider  one of SUPPORTED_PROVIDERS
+ * @returns {Promise<JspmCallResult>}
+ */
+async function jspmCall(installs, provider) {
+  const label = installs.length === 1 ? `'${installs[0]}'` : `${installs.length} packages`;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), JSPM_GENERATE_TIMEOUT_MS);
+  try {
+    const response = await fetch(JSPM_GENERATE_ENDPOINT, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({
+        install: installs,
+        // flattenScope:true merges transitive ESM deps into the flat
+        // `imports` map instead of a separate `scopes` field. Webjs only
+        // consumes `imports`, so without this any package with an
+        // unbundled ESM transitive (e.g. react-dom imports `scheduler`,
+        // @codemirror/lint imports @codemirror/state) would break in the
+        // browser with an unresolved-bare-specifier error. With the
+        // WHOLE-set call (issue #446) the flattened transitives are now
+        // ALSO mutually consistent: one `@codemirror/view` URL shared by
+        // the direct import and lint's transitive need, instead of two
+        // skewed versions from independent per-package calls.
+        flattenScope: true,
+        env: ['browser', 'production', 'module'],
+        provider: normalizeProvider(provider),
+      }),
+      signal: controller.signal,
+    });
+    if (!response.ok) {
+      // jspm.io returns the error reason in the body with a 401 (its
+      // quirk: 401 is what it sends for unresolvable installs, not auth
+      // failures). Surface it so the user sees WHAT failed and why.
+      let detail = '';
+      try {
+        const body = await response.json();
+        if (body && typeof body.error === 'string') detail = `: ${body.error}`;
+      } catch { /* non-JSON body */ }
+      console.error(
+        `[webjs] could not vendor ${label} via ${provider} (status ${response.status})${detail}`,
+      );
+      // A 5xx/429 is a transient jspm problem worth retrying. A 401/4xx
+      // means at least one install is genuinely unresolvable (jspm uses
+      // 401 for that): a private / workspace / server-only package (e.g.
+      // @webjsdev/server, @prisma/client) the browser never fetches
+      // anyway. Permanent failures must NOT block readiness.
+      const transient = response.status >= 500 || response.status === 429;
+      return { ok: false, imports: {}, transient };
+    }
+    const result = await response.json();
+    const imports = (result && result.map && result.map.imports) || {};
+    return { ok: true, imports, transient: false };
+  } catch (e) {
+    const msg = e && e.name === 'AbortError'
+      ? `timed out after ${JSPM_GENERATE_TIMEOUT_MS}ms`
+      : `${e && e.message}`;
+    console.error(`[webjs] could not vendor ${label} via ${provider}: ${msg}`);
+    return { ok: false, imports: {}, transient: true };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/**
+ * Resolve a SINGLE install in isolation, cached per install + provider.
+ * This is the FALLBACK path: it only runs when the unified whole-set call
+ * fails because some install is unresolvable. Isolating each install means
+ * one bad dep (a 401) drops out on its own instead of collapsing the map
+ * for its legitimate neighbours. The cross-package coherence the unified
+ * call provides is lost for this degraded set, which is acceptable: it is
+ * exactly the pre-#446 behaviour, reached only when the app already has an
+ * unresolvable dep.
+ *
+ * Sets `lastLiveResolveFailed` on a TRANSIENT failure (so the caller
+ * retries), never on a permanent 401 (tolerated).
  *
  * @param {string} install  e.g. 'dayjs@1.11.13' or 'dayjs@1.11.13/plugin/utc'
  * @param {string} [provider]  one of SUPPORTED_PROVIDERS; defaults to 'jspm'
  * @returns {Promise<Record<string, string>>}
  */
 async function jspmResolveOne(install, provider = 'jspm') {
-  // Cache key includes provider since the same install can resolve
-  // to different URLs across CDNs (e.g. `dayjs@1.11.13` returns
-  // ga.jspm.io vs cdn.jsdelivr.net depending on `provider`).
-  const cacheKey = `${provider}::${install}`;
+  const { ok, imports, transient } = await jspmProbeOne(install, provider);
+  // Preserve the public contract: an empty map on any failure, and the
+  // module-global retry flag set ONLY on a transient one (a permanent 401
+  // for an unresolvable private/server-only dep is tolerated).
+  if (!ok && transient) lastLiveResolveFailed = true;
+  return imports;
+}
+
+/**
+ * Probe a SINGLE install and return the FULL classification, not just the
+ * imports. Unlike `jspmResolveOne` this does NOT collapse a transient
+ * failure into the same empty map a permanent one yields, and does NOT
+ * touch `lastLiveResolveFailed`: the caller (the 401 fallback in
+ * `jspmGenerate`) needs to tell "genuinely unresolvable, safe to drop"
+ * (`ok:false, transient:false`) from "a network blip mid-probe, do NOT
+ * drop" (`ok:false, transient:true`), and owns the retry flag itself.
+ *
+ * Cached per install + provider; a successful probe's `{imports}` is the
+ * same value `jspmResolveOne` returns, so the two share the cache and the
+ * later unified re-run reuses it.
+ *
+ * @param {string} install
+ * @param {string} provider
+ * @returns {Promise<JspmCallResult>}
+ */
+function jspmProbeOne(install, provider) {
+  const cacheKey = `${provider}::probe::${install}`;
   const existing = jspmCache.get(cacheKey);
   if (existing) return existing;
 
   const promise = (async () => {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), JSPM_GENERATE_TIMEOUT_MS);
-    try {
-      const response = await fetch(JSPM_GENERATE_ENDPOINT, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json' },
-        body: JSON.stringify({
-          install: [install],
-          // flattenScope:true merges transitive ESM deps into the
-          // flat `imports` map instead of returning them in a
-          // separate `scopes` field. Webjs only consumes `imports`
-          // (the importmap output doesn't carry `scopes`), so
-          // without this any package with an unbundled ESM
-          // transitive (e.g. react-dom imports `scheduler`)
-          // would break in the browser with an unresolved-bare-
-          // specifier error. Matches importmap-rails's posture.
-          flattenScope: true,
-          env: ['browser', 'production', 'module'],
-          provider: normalizeProvider(provider),
-        }),
-        signal: controller.signal,
-      });
-      if (!response.ok) {
-        // jspm.io returns the error reason in the body with a 401 (its
-        // quirk: 401 is what it sends for unresolvable installs, not
-        // auth failures). Surface it so the user sees WHICH dep failed
-        // and why, not just a generic "vendor pipeline broken".
-        let detail = '';
-        try {
-          const body = await response.json();
-          if (body && typeof body.error === 'string') detail = `: ${body.error}`;
-        } catch { /* non-JSON body */ }
-        console.error(
-          `[webjs] could not vendor '${install}' via ${provider} (status ${response.status})${detail}`,
-        );
-        jspmCache.delete(cacheKey);
-        // A 5xx/429 is a transient jspm problem worth retrying. A 401/4xx means
-        // the install is genuinely unresolvable (jspm uses 401 for that): a
-        // private / workspace / server-only package (e.g. @webjsdev/server,
-        // @prisma/client) the browser never fetches anyway. That is tolerated
-        // exactly as before and must NOT block readiness, or an app with any
-        // such dep would never become ready.
-        if (response.status >= 500 || response.status === 429) lastLiveResolveFailed = true;
-        return {};
-      }
-      const result = await response.json();
-      return (result && result.map && result.map.imports) || {};
-    } catch (e) {
-      const msg = e && e.name === 'AbortError'
-        ? `timed out after ${JSPM_GENERATE_TIMEOUT_MS}ms`
-        : `${e && e.message}`;
-      console.error(`[webjs] could not vendor '${install}' via ${provider}: ${msg}`);
-      jspmCache.delete(cacheKey);
-      lastLiveResolveFailed = true;
-      return {};
-    } finally {
-      clearTimeout(timer);
-    }
+    const result = await jspmCall([install], provider);
+    // Do not cache a failure: a transient one must be re-attempted on the
+    // next resolve, and a permanent one is cheap to re-confirm and must not
+    // pin a stale "unresolvable" verdict across a dependency change.
+    if (!result.ok) jspmCache.delete(cacheKey);
+    return result;
   })();
 
   jspmCache.set(cacheKey, promise);
@@ -401,15 +490,35 @@ async function jspmResolveOne(install, provider = 'jspm') {
 }
 
 /**
- * Resolve a list of `pkg@version` installs to importmap entries by
- * calling api.jspm.io/generate ONCE PER INSTALL in parallel. Per-package
- * isolation prevents one bad dep from collapsing the whole importmap
- * (see jspmResolveOne for the rationale).
- *
- * The merge is last-write-wins per key. In practice subpath installs
- * never collide with each other (their keys include the subpath), and
- * the bare-package install for `dayjs` always produces the same root
- * URL as `dayjs@x.y.z/plugin/foo`'s incidental `dayjs` entry.
+ * Resolve a list of `pkg@version` installs to importmap entries.
+ *
+ * Issue #446: the WHOLE set is resolved in ONE api.jspm.io/generate call
+ * (a single `install[]` array) so jspm computes one mutually-consistent
+ * dependency graph. A directly-imported package and a transitive that
+ * needs a newer version of the same package now agree on one URL, instead
+ * of the old per-package-in-isolation merge that pinned the direct dep to
+ * its local version while the transitive floated to jspm-latest, producing
+ * a missing-export crash in the browser.
+ *
+ * The per-package-isolation property is PRESERVED as a fallback only: if
+ * the unified call fails because some install is unresolvable (a 401 for a
+ * private / server-only dep), one bad install must not collapse the map
+ * for the rest. So:
+ *   1. Try the unified call. On success, return its coherent graph.
+ *   2. On a PERMANENT failure (401/4xx), probe each install in isolation
+ *      to learn which ones resolve, then RE-RUN the unified call over only
+ *      the resolvable subset so the survivors stay mutually consistent.
+ *      Only installs whose probe fails PERMANENTLY drop out (genuinely
+ *      unresolvable, the browser never fetched them anyway); if any probe
+ *      fails TRANSIENTLY, no one is dropped and the resolve is flagged for
+ *      retry, so a network blip mid-probe cannot evict a good package. If
+ *      the re-run itself fails, fall back to the merged per-install
+ *      fragments so the app is no worse off than pre-#446.
+ *   3. On a TRANSIENT failure (network / timeout / 5xx / 429), set the
+ *      retry flag and serve whatever the per-install probe produced.
+ *
+ * The unified result is cached per sorted-install-set + provider; the
+ * per-install fallback reuses the per-install cache entries.
  *
  * @param {Array<string>} installs  e.g. ['dayjs@1.11.13', 'clsx@2.1.1']
  * @param {string} [provider]  one of SUPPORTED_PROVIDERS; defaults to 'jspm'
@@ -417,9 +526,95 @@ async function jspmResolveOne(install, provider = 'jspm') {
  */
 export async function jspmGenerate(installs, provider = 'jspm') {
   if (installs.length === 0) return {};
-  const perPackage = await Promise.all(installs.map(i => jspmResolveOne(i, provider)));
+
+  // A single install has no cross-package graph to reconcile, so the
+  // isolated path IS the coherent path; reuse the per-install cache.
+  if (installs.length === 1) return jspmResolveOne(installs[0], provider);
+
+  // Stable key regardless of scan order so the same dep set hits cache.
+  const unifiedKey = `${provider}::unified::${[...installs].sort().join('\n')}`;
+  const cached = jspmCache.get(unifiedKey);
+  if (cached) return cached;
+
+  const promise = (async () => {
+    const unified = await jspmCall(installs, provider);
+    if (unified.ok) return unified.imports;
+
+    // The unified call failed. Drop the cached failure so a later retry
+    // re-attempts; the per-install fallback owns the retry flag.
+    jspmCache.delete(unifiedKey);
+
+    if (unified.transient) {
+      // Network / 5xx: nothing resolved coherently. Fall back to merged
+      // per-install fragments (each may still be cached / reachable) so we
+      // serve whatever we can, and flag the transient failure for retry.
+      lastLiveResolveFailed = true;
+      return mergePerInstall(await Promise.all(installs.map(i => jspmResolveOne(i, provider))));
+    }
+
+    // Permanent failure: at least one install is unresolvable. Probe each
+    // in isolation to learn which ones jspm can resolve, then re-run the
+    // unified call over only those so the survivors form one consistent
+    // graph (restores #446 coherence for the resolvable subset).
+    const probes = await Promise.all(installs.map(i => jspmProbeOne(i, provider)));
+
+    // A GOOD package whose isolated probe failed TRANSIENTLY (a network blip
+    // mid-probe) must NOT be classified as unresolvable and dropped. Only a
+    // PERMANENT probe failure (401/404) means the install is genuinely
+    // unresolvable. If any probe failed transiently, we cannot safely decide
+    // the resolvable set this pass, so flag the whole resolve transient-
+    // failed and serve the merged fragments WITHOUT dropping anyone; the next
+    // ensureReady retry re-resolves once the blip clears. Conflating the two
+    // here is exactly the bug this guard prevents.
+    const transientProbe = probes.some(p => !p.ok && p.transient);
+    if (transientProbe) {
+      lastLiveResolveFailed = true;
+      return mergePerInstall(probes.map(p => p.imports));
+    }
+
+    // From here every failed probe is PERMANENT, so dropping it is safe.
+    const resolvable = installs.filter((_, idx) => probes[idx].ok);
+
+    if (resolvable.length === installs.length) {
+      // Every install resolved alone but the batch 401'd: a genuine
+      // cross-package CONFLICT jspm could not satisfy as one graph (rare).
+      // The coherent graph is unavailable, so serve the merged fragments
+      // (pre-#446 behaviour) rather than nothing. NOTE: this degraded path
+      // can REINTRODUCE the #446 skew, because last-write-wins on a shared
+      // transitive across independent fragments is exactly the merge the
+      // unified call exists to avoid. It is a deliberate degrade-not-crash
+      // fallback for an unsatisfiable graph: no coherent graph exists, so a
+      // possibly-skewed map beats no map. The common conflicting-deps case
+      // (one shared transitive needing a newer version, issue #446's repro)
+      // IS satisfiable and resolves coherently on the unified path above;
+      // only a genuinely unsatisfiable set reaches here.
+      return mergePerInstall(probes.map(p => p.imports));
+    }
+    if (resolvable.length === 0) return {};
+    if (resolvable.length === 1) return jspmResolveOne(resolvable[0], provider);
+
+    // Re-run unified over the resolvable subset. If even that fails (a
+    // conflict among the survivors), fall back to their merged fragments.
+    const retry = await jspmCall(resolvable, provider);
+    if (retry.ok) return retry.imports;
+    return mergePerInstall(resolvable.map(i => probes[installs.indexOf(i)].imports));
+  })();
+
+  jspmCache.set(unifiedKey, promise);
+  return promise;
+}
+
+/**
+ * Last-write-wins merge of per-install import fragments. Subpath installs
+ * never collide (their keys include the subpath); a shared base package
+ * resolves to the same root URL across fragments, so the merge is stable.
+ *
+ * @param {Array<Record<string, string>>} fragments
+ * @returns {Record<string, string>}
+ */
+function mergePerInstall(fragments) {
   const merged = {};
-  for (const fragment of perPackage) Object.assign(merged, fragment);
+  for (const fragment of fragments) Object.assign(merged, fragment);
   return merged;
 }
 
@@ -465,6 +660,30 @@ export function clearVendorCache() {
   liveIntegrityCache.clear();
 }
 
+/**
+ * Recover `{ pkg, version, subpath }` for a resolved import spec that was
+ * NOT in the directly-scanned set, i.e. a flattened transitive the unified
+ * resolve added (issue #446). The bare package name and subpath come from
+ * the spec; the version is read out of the resolved CDN URL by locating
+ * `<bare>@<version>` in it (same logic `listPinned` uses, which handles
+ * every supported provider's URL shape). Returns null when the version
+ * can't be parsed, in which case the caller pins the entry by URL anyway
+ * but cannot derive a `--download` filename for it.
+ *
+ * @param {string} spec  e.g. '@codemirror/state' or 'dayjs/plugin/utc'
+ * @param {string} url   the resolved CDN URL for that spec
+ * @returns {{ pkg: string, version: string, subpath: string } | null}
+ */
+function derivePinParts(spec, url) {
+  const pkg = extractPackageName(spec);
+  if (!pkg) return null;
+  const subpath = spec.slice(pkg.length);
+  const escapedBare = pkg.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const match = new RegExp(`(?:^|[^a-zA-Z0-9_.-])${escapedBare}@([^/]+)`).exec(url);
+  if (!match) return null;
+  return { pkg, version: match[1], subpath };
+}
+
 // ---------------------------------------------------------------------------
 // File-based pin (.webjs/vendor/importmap.json, optional --download bundles)
 // ---------------------------------------------------------------------------
@@ -482,6 +701,179 @@ function pinFilePath(appDir) {
   return join(pinDir(appDir), PIN_FILE);
 }
 
+/**
+ * The three-line `.gitignore` pattern that ignores the transient
+ * `.webjs` caches at any depth while re-including the committed
+ * `.webjs/vendor/` pin output. This mirrors the scaffold template
+ * (`packages/cli/templates/.gitignore`) and the `vendor-gitignore`
+ * check in `doctor.js` verbatim, so a self-healed `.gitignore`
+ * ends up byte-identical to a freshly scaffolded one.
+ */
+const VENDOR_GITIGNORE_LINES = [
+  '**/.webjs/*',
+  '!**/.webjs/vendor/',
+  '!**/.webjs/vendor/**',
+];
+
+/**
+ * Probe whether `appDir`'s `.gitignore` would swallow the vendor pin
+ * output, via `git check-ignore`. Best-effort: returns false when the
+ * directory is not a git repo, git is absent, or the spawn fails.
+ *
+ * The inherited GIT_* env vars are stripped so `cwd` is the sole
+ * authority on which repo + `.gitignore` stack is consulted. Git
+ * exports GIT_DIR / GIT_WORK_TREE / GIT_INDEX_FILE / GIT_PREFIX into
+ * hook processes (a pre-commit hook from a linked worktree exports
+ * GIT_WORK_TREE), and those OVERRIDE cwd-based discovery; without the
+ * strip the probe would consult the outer repo instead of `appDir`.
+ * Same reasoning as the `vendor-gitignore` doctor check.
+ *
+ * @param {string} appDir
+ * @returns {boolean} true when `.webjs/vendor/importmap.json` is ignored
+ */
+function vendorPinIsIgnored(appDir) {
+  try {
+    const {
+      GIT_DIR: _gd, GIT_WORK_TREE: _gwt, GIT_INDEX_FILE: _gif, GIT_PREFIX: _gp,
+      ...gitEnv
+    } = process.env;
+    const probe = `.webjs/vendor/${PIN_FILE}`;
+    // `git check-ignore -q` exits 0 when ignored, 1 when not ignored,
+    // 128 on error (not a git repo, etc.). Treat anything but 0 as
+    // "not ignored" so a non-git project never gets its .gitignore
+    // touched.
+    const result = spawnSync('git', ['check-ignore', '-q', probe], {
+      cwd: appDir,
+      stdio: 'pipe',
+      env: gitEnv,
+    });
+    return result.status === 0;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Make the `webjs vendor pin` output committable, idempotently.
+ *
+ * Vendoring is an OPTIONAL opt-in: the no-build default resolves bare
+ * specifiers at runtime via jspm.io and needs nothing committed. But a
+ * user who runs `webjs vendor pin` deliberately creates pins they want
+ * in source control, and a `.gitignore` that excludes `.webjs/` (the
+ * older scaffold pattern, or one an editor/agent "simplified") silently
+ * swallows that output. Fresh scaffolds already carry the vendor
+ * exception (a glob exclusion plus a re-include negation), so for them
+ * this is a no-op.
+ *
+ * Behaviour (only ever called from the opt-in `vendor pin` path):
+ *   - The pin output is NOT ignored (the common, already-correct case):
+ *     return `{ ignored: false, patched: false }`. Nothing is written.
+ *   - The pin output IS ignored AND a `.gitignore` exists: heal it (see
+ *     below), then re-probe. If the pin is committable afterwards return
+ *     `{ ignored: true, patched: true, gitignorePath }`; if a broader
+ *     unrelated rule still swallows it (e.g. a root `*.json`), the heal
+ *     cannot help, so revert the edit and return `patched: false` so the
+ *     caller prints a notice rather than claiming a fix that did not take.
+ *   - The pin output IS ignored but there is NO `.gitignore` to patch
+ *     (e.g. the ignore comes from a parent repo's `.gitignore`, or from
+ *     `.git/info/exclude`): leave the tree untouched and return
+ *     `{ ignored: true, patched: false, gitignorePath: null }` so the
+ *     caller can print a notice instead of writing a file the user did
+ *     not create.
+ *
+ * Healing has two parts, because a plain append is NOT enough. A bare
+ * directory exclusion (`.webjs/`, `/.webjs/`, `.webjs`, with or without a
+ * leading glob) excludes the directory itself, and git CANNOT re-include
+ * a child of an excluded directory, so any later negation is silently
+ * dead. So: (1) rewrite each such line IN PLACE to the glob form
+ * (`**` + `/.webjs/*`), which ignores the directory's CONTENTS at any
+ * depth while leaving the directory re-includable; (2) append whichever
+ * of the three exception lines are still missing. The heal is idempotent:
+ * a re-run finds the pin already committable and short-circuits.
+ *
+ * @param {string} appDir
+ * @returns {Promise<{ ignored: boolean, patched: boolean, gitignorePath: string | null }>}
+ */
+export async function ensureVendorCommittable(appDir) {
+  if (!vendorPinIsIgnored(appDir)) {
+    return { ignored: false, patched: false, gitignorePath: null };
+  }
+  const gitignorePath = join(appDir, '.gitignore');
+  let original;
+  try {
+    original = await readFile(gitignorePath, 'utf8');
+  } catch {
+    // No app-level .gitignore to patch. The ignore is coming from a
+    // parent repo or from .git/info/exclude; do not fabricate a
+    // .gitignore the user never had. Let the caller print a notice.
+    return { ignored: true, patched: false, gitignorePath: null };
+  }
+
+  // The exclusion glob, assembled so the literal `*` + `/` sequence never
+  // appears in this file's source comments above.
+  const exclude = VENDOR_GITIGNORE_LINES[0]; // **/.webjs/*
+
+  // Preserve the file's line ending so a CRLF .gitignore stays all-CRLF
+  // (and an LF one all-LF). Splitting on bare `\n` keeps each existing
+  // line's trailing `\r`; the lines we WRITE (the rewritten exclusion and
+  // the appended block) must use the same ending or the file goes mixed.
+  // A file with any CRLF is treated as CRLF; otherwise LF.
+  const eol = /\r\n/.test(original) ? '\r\n' : '\n';
+
+  // 1. Rewrite any bare `.webjs` DIRECTORY exclusion to the glob form. A
+  //    directory exclusion blocks all child negations, so it must become
+  //    `**/.webjs/*` (ignore contents, keep the dir re-includable).
+  const lines = original.split('\n');
+  let rewroteDir = false;
+  const rewritten = lines.map((line) => {
+    // Trim CR too, so a CRLF file's `.webjs/\r` still matches.
+    const t = line.replace(/\r$/, '').trim();
+    // Match the bare-directory shapes only (no `/*` suffix, not already a
+    // negation): `.webjs`, `.webjs/`, `/.webjs`, `/.webjs/`, `**/.webjs`,
+    // `**/.webjs/`. These all exclude the directory itself. Emit the
+    // replacement with the file's own ending if the original line carried
+    // one (every line but a no-trailing-newline last line does).
+    if (/^(\*\*\/|\/)?\.webjs\/?$/.test(t)) {
+      rewroteDir = true;
+      return line.endsWith('\r') ? exclude + '\r' : exclude;
+    }
+    return line;
+  });
+
+  // 2. Append whichever exception lines are still missing.
+  const present = new Set(rewritten.map((l) => l.replace(/\r$/, '').trim()));
+  const missing = VENDOR_GITIGNORE_LINES.filter((l) => !present.has(l));
+
+  let next = rewritten.join('\n');
+  if (missing.length > 0) {
+    const block =
+      [
+        '# webjs: keep the committed vendor pin (`webjs vendor pin`) out of',
+        '# the `.webjs` cache exclusion so the pinned importmap is committable.',
+        ...missing,
+      ].join(eol) + eol;
+    const sep = next.endsWith('\n') || next === '' ? '' : eol;
+    next = next + sep + block;
+  }
+
+  if (!rewroteDir && missing.length === 0) {
+    // Nothing to change, yet git still ignores the pin: a broader,
+    // unrelated rule is the cause and the vendor exception cannot fix it.
+    return { ignored: true, patched: false, gitignorePath };
+  }
+
+  await writeFile(gitignorePath, next);
+
+  // 3. Re-probe. If a broader unrelated rule still swallows the pin, the
+  //    edit did not achieve the goal, so revert it and report not-patched
+  //    so the caller prints a notice instead of an inaccurate success.
+  if (vendorPinIsIgnored(appDir)) {
+    await writeFile(gitignorePath, original);
+    return { ignored: true, patched: false, gitignorePath };
+  }
+  return { ignored: true, patched: true, gitignorePath };
+}
+
 /**
  * True when the app commits a vendor pin file (`.webjs/vendor/importmap.json`).
  * A pinned app's importmap is deterministic and cheap to read, so `dev.js`
@@ -839,9 +1231,20 @@ export async function pinAll(appDir, opts = {}) {
   const expected = new Set([PIN_FILE]);
   let downloaded = 0;
 
+  // Specs that were directly scanned (`partsByInstall`) AND the flattened
+  // transitive specs the unified resolve returns (issue #446) must BOTH be
+  // pinned, or a pinned app's importmap would be missing the transitive
+  // entries the runtime live-resolve serves (e.g. `@codemirror/state` pulled
+  // in by `@codemirror/lint`), breaking parity: the browser would hit an
+  // unresolved-bare-specifier error for the transitive. For a transitive we
+  // recover pkg + version + subpath by parsing the spec against the resolved
+  // jspm URL (`derivePinParts`), since it has no `partsByInstall` entry.
+  /** @type {Set<string>} */
+  const pinnedDirectSpecs = new Set();
   for (const [spec, jspmUrl] of Object.entries(resolved)) {
-    const parts = partsByInstall.get(spec);
+    const parts = partsByInstall.get(spec) || derivePinParts(spec, jspmUrl);
     if (!parts) continue;
+    const direct = partsByInstall.has(spec);
     const { pkg, version, subpath } = parts;
     if (download) {
       const filename = bundleFilenameWithSubpath(pkg, version, subpath);
@@ -869,6 +1272,7 @@ export async function pinAll(appDir, opts = {}) {
       );
       pins.push({ pkg: spec, version, url: jspmUrl, integrity: sri || undefined });
     }
+    if (direct) pinnedDirectSpecs.add(spec);
   }
 
   // If pin was attempted (installs non-empty) but resolved zero, do
@@ -878,11 +1282,16 @@ export async function pinAll(appDir, opts = {}) {
   // every bare-specifier import. Better: surface the failure so the
   // user knows pin didn't take, and let the next boot fall back to
   // live API resolution (which may have recovered by then).
-  if (installs.length > 0 && pins.length === 0) {
+  //
+  // Account on DIRECT specs only: pins also carries flattened transitive
+  // entries (#446), so `pins.length === 0` would no longer mean "every
+  // direct install failed". A resolve that returned only transitives but
+  // no direct spec is still a total failure for the user's deps.
+  if (installs.length > 0 && pinnedDirectSpecs.size === 0) {
     return { pins, pruned: [], downloaded, failed: true, attemptedInstalls: installs, provider: from };
   }
 
-  // Partial-failure surface. Some installs were attempted but not
+  // Partial-failure surface. Some DIRECT installs were attempted but not
   // every one made it into pins (jspm.io returned the package OK,
   // but downloadBundle failed mid-stream in --download mode, or the
   // resolver response was missing the package entirely). Write the
@@ -892,15 +1301,14 @@ export async function pinAll(appDir, opts = {}) {
   // --download mode).
   //
   // Derive the missing set from partsByInstall (the bare-spec keys)
-  // rather than from `installs` (the versioned strings). pins[].pkg
-  // is the bare spec, so a direct filter over `installs` wouldn't
-  // match anything.
-  if (installs.length > pins.length) {
-    const pinnedSpecs = new Set(pins.map(p => p.pkg));
+  // rather than from `installs` (the versioned strings). Compare against
+  // the DIRECT specs that pinned, NOT pins[].pkg (which now includes
+  // transitives), so a transitive can't mask a missing direct dep.
+  if (pinnedDirectSpecs.size < partsByInstall.size) {
     /** @type {string[]} */
     const missing = [];
     for (const [spec, parts] of partsByInstall.entries()) {
-      if (!pinnedSpecs.has(spec)) {
+      if (!pinnedDirectSpecs.has(spec)) {
         missing.push(`${parts.pkg}@${parts.version}${parts.subpath}`);
       }
     }
@@ -1361,6 +1769,341 @@ export function prunePinToReachable(imports, integrity, reachable) {
   return { imports: keptImports, integrity: keptIntegrity };
 }
 
+// ---------------------------------------------------------------------------
+// Importmap coherence check (issue #450)
+// ---------------------------------------------------------------------------
+//
+// A produced importmap pins one URL per resolved package, each URL carrying an
+// `@<version>`. That pinned graph is INCOHERENT when one resolved package
+// declares a dependency or peer range on ANOTHER resolved package and the
+// version actually pinned for that other package falls OUTSIDE the range. The
+// motivating crash (#446): `@codemirror/view@6.39.16` pinned while
+// `@codemirror/lint@6.9.6` (also pinned) needs `view@^6.42.0`, so a symbol
+// `lint` expects is missing from the older `view` bundle at runtime.
+//
+// This is a VALIDATION over a produced importmap, NOT a re-resolution (that is
+// #446's job) and NOT bundling. It emits warnings; it never mutates the map.
+//
+// PARITY: `checkImportmapCoherence` is a pure function of the EXTRACTED
+// `{ package -> pinned version }` set plus the dependency metadata. It does not
+// know or care whether the importmap came from a live jspm.io resolve or from a
+// committed `.webjs/vendor/importmap.json`. Two importmaps that pin the same
+// versions for the same packages therefore always produce the same verdict,
+// which is exactly the runtime-vs-vendored parity the maintainer requires.
+
+/**
+ * Extract `{ basePackage -> pinned version }` from an importmap's `imports`
+ * map. Each value is a CDN URL (jspm.io's `npm:dayjs@1.11.13/...`, jsdelivr's
+ * `npm/dayjs@1.11.13/...`, unpkg's bare `dayjs@1.11.13/...`, skypack's
+ * `dayjs@1.11.13`) or a local `/__webjs/vendor/<pkg>@<version>...js` path. The
+ * key is the bare package name parsed from the importmap KEY (the specifier),
+ * which is authoritative; the version is parsed from the URL.
+ *
+ * A specifier that resolves to a version we cannot parse from its URL is
+ * skipped (it contributes nothing to the dep graph rather than a wrong pin).
+ * When the same base package appears at several versions (subpath imports),
+ * the LAST parsed wins; in practice every subpath of a package resolves to the
+ * one installed version, so they agree.
+ *
+ * @param {Record<string, string>} imports  importmap `imports` map (specifier -> URL)
+ * @returns {Map<string, string>}  base package name -> pinned version
+ */
+export function extractPinnedVersions(imports) {
+  /** @type {Map<string, string>} */
+  const out = new Map();
+  for (const [spec, url] of Object.entries(imports || {})) {
+    if (typeof url !== 'string') continue;
+    const bare = extractPackageName(spec);
+    if (!bare) continue;
+    let version = null;
+    if (url.startsWith('/__webjs/vendor/')) {
+      // Local downloaded-pin path: `<name>@<version>[__subpath].js`. The name
+      // is `--`-encoded for scoped packages; we only need the version, which
+      // sits after the LAST `@` and before any `__subpath` / `.js` suffix.
+      const filename = url.slice('/__webjs/vendor/'.length);
+      const atIdx = filename.lastIndexOf('@');
+      if (atIdx > 0) {
+        const afterAt = filename.slice(atIdx + 1, filename.endsWith('.js') ? -3 : undefined);
+        const subIdx = afterAt.indexOf('__');
+        version = subIdx < 0 ? afterAt : afterAt.slice(0, subIdx);
+      }
+    } else {
+      // CDN URL: find `<bare>@<version>` anchored on a non-name char (or the
+      // string start) so a short name like `ms` does not false-match inside
+      // another package's URL. Mirrors listPinned's parser.
+      const escapedBare = bare.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+      const m = new RegExp(`(?:^|[^a-zA-Z0-9_.-])${escapedBare}@([^/]+)`).exec(url);
+      if (m) version = m[1];
+    }
+    if (version && /\d/.test(version)) out.set(bare, version);
+  }
+  return out;
+}
+
+/**
+ * Does `version` satisfy the npm `range`? PRAGMATIC, no semver dependency
+ * (vendor.js stays dependency-free). Supports the shapes that appear in real
+ * `dependencies` / `peerDependencies`: `*` / `latest` / `x` / `''` (any),
+ * `||` alternation, a leading `>=` / `>` / `<=` / `<` / `=`, caret `^`, tilde
+ * `~`, an `x`/`*` wildcard segment (`6.x`, `6.39.x`), and an exact `1.2.3`.
+ *
+ * Returns `true` / `false` when the range can be evaluated, and `null` when
+ * the shape is one we do NOT statically understand (a URL range, a git range,
+ * a hyphen `1.2.3 - 1.4.0` range). `null` is the "could not verify" signal: the
+ * caller degrades to a soft "unverified" note rather than warning on a shape it
+ * cannot judge. Failing open here is deliberate, a coherence check must never
+ * cry wolf on a range it misread.
+ *
+ * Prerelease note: both the version and the range are judged on their release
+ * line only (the `-beta` / `-rc` tag is dropped, see `parseSemver`), so a
+ * prerelease pin is treated as its stable tuple. The worst case is a MISSED
+ * warning when a prerelease is pinned, never a spurious one.
+ *
+ * @param {string} version  e.g. `6.39.16`
+ * @param {string} range    e.g. `^6.42.0`
+ * @returns {boolean | null}
+ */
+export function satisfiesSemverRange(version, range) {
+  const v = parseSemver(version);
+  if (!v) return null;
+  const r = String(range == null ? '' : range).trim();
+  if (r === '' || r === '*' || r === 'x' || r === 'X' || r === 'latest') return true;
+  if (r.startsWith('workspace:')) return true;
+  // Alternation: satisfied if ANY clause is satisfied. A clause we cannot
+  // evaluate (null) must not let a non-matching clause produce a false
+  // negative, so an unknown clause makes the whole result unknown unless a
+  // known clause already matched.
+  if (r.includes('||')) {
+    let sawUnknown = false;
+    for (const clause of r.split('||')) {
+      const res = satisfiesSemverRange(version, clause.trim());
+      if (res === true) return true;
+      if (res === null) sawUnknown = true;
+    }
+    return sawUnknown ? null : false;
+  }
+  // A space-joined comparator set (`>=6.0.0 <7.0.0`) must ALL be satisfied.
+  if (/\s/.test(r)) {
+    // A hyphen range (`1.2.3 - 1.4.0`) is not a comparator set; we do not
+    // parse it, so degrade to unknown rather than mis-AND its halves.
+    if (/\s-\s/.test(r)) return null;
+    let result = true;
+    for (const part of r.split(/\s+/)) {
+      if (!part) continue;
+      const res = satisfiesSemverRange(version, part);
+      if (res === null) return null;
+      if (res === false) result = false;
+    }
+    return result;
+  }
+  // Comparators: >= > <= < =.
+  const cmpMatch = /^(>=|<=|>|<|=)\s*(.+)$/.exec(r);
+  if (cmpMatch) {
+    const op = cmpMatch[1];
+    const bound = parseSemver(cmpMatch[2]);
+    if (!bound) return null;
+    const c = cmpSemver(v, bound);
+    switch (op) {
+      case '>=': return c >= 0;
+      case '>': return c > 0;
+      case '<=': return c <= 0;
+      case '<': return c < 0;
+      case '=': return c === 0;
+    }
+  }
+  // Caret: same left-most non-zero segment. ^6.42.0 -> >=6.42.0 <7.0.0;
+  // ^0.7.0 -> >=0.7.0 <0.8.0; ^0.0.3 -> >=0.0.3 <0.0.4.
+  if (r.startsWith('^')) {
+    const b = parseSemver(r.slice(1));
+    if (!b) return null;
+    if (cmpSemver(v, b) < 0) return false;
+    if (b[0] > 0) return v[0] === b[0];
+    if (b[1] > 0) return v[0] === 0 && v[1] === b[1];
+    return v[0] === 0 && v[1] === 0 && v[2] === b[2];
+  }
+  // Tilde: ~6.42.0 -> >=6.42.0 <6.43.0; ~6 -> >=6.0.0 <7.0.0.
+  if (r.startsWith('~')) {
+    const raw = r.slice(1);
+    const b = parseSemver(raw);
+    if (!b) return null;
+    if (cmpSemver(v, b) < 0) return false;
+    // If the range named a minor (`~6.42` / `~6.42.0`), pin the minor; if it
+    // named only a major (`~6`), pin the major.
+    const namedMinor = /^\d+\.\d+/.test(raw);
+    return namedMinor ? v[0] === b[0] && v[1] === b[1] : v[0] === b[0];
+  }
+  // x / * wildcard segment: 6.x, 6.39.x, 6.*.
+  if (/^\d+(\.(\d+|[xX*])){0,2}$/.test(r) && /[xX*]/.test(r)) {
+    const segs = r.split('.');
+    for (let i = 0; i < segs.length; i++) {
+      const s = segs[i];
+      if (s === 'x' || s === 'X' || s === '*') break; // any beyond here
+      if (Number(s) !== v[i]) return false;
+    }
+    return true;
+  }
+  // Exact `1.2.3` (or shorter `1` / `1.2`, treated as that prefix pinned). A
+  // leading `v` (`v1.2.3`) is tolerated so a `v`-prefixed exact pin evaluates
+  // instead of degrading to unverified.
+  const exact = r.startsWith('v') ? r.slice(1) : r;
+  if (/^\d+(\.\d+){0,2}$/.test(exact)) {
+    const b = parseSemver(exact);
+    if (!b) return null;
+    const segs = exact.split('.').length;
+    for (let i = 0; i < segs; i++) if (v[i] !== b[i]) return false;
+    return true;
+  }
+  return null;
+}
+
+/**
+ * Parse a version string to a `[major, minor, patch]` numeric triple, or null
+ * when it has no parseable numeric core (a `latest`, a git URL, a `*`).
+ *
+ * KNOWN LIMITATION: a prerelease / build suffix (`-rc.1`, `+sha`) is dropped, so
+ * a version is judged purely on its release line. A pinned prerelease is treated
+ * as its stable tuple: `6.42.0-beta.1` is judged as `6.42.0`, so a stable range
+ * like `^6.42.0` reports it as a MATCH even though npm semver excludes a
+ * prerelease from a stable range. This is a deliberate fail-safe simplification
+ * (we do not carry prerelease ordering): the only consequence is a MISSED
+ * coherence warning when a prerelease is pinned, never a spurious one on a
+ * coherent graph. Pinned prereleases are vanishingly rare in a vendored
+ * importmap, so the missed-warning risk is negligible.
+ *
+ * @param {string} v
+ * @returns {[number, number, number] | null}
+ */
+function parseSemver(v) {
+  const m = /(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(String(v == null ? '' : v));
+  if (!m) return null;
+  return [Number(m[1]), Number(m[2] || 0), Number(m[3] || 0)];
+}
+
+/**
+ * Compare two `[major, minor, patch]` triples. Negative if a < b, 0 if equal,
+ * positive if a > b.
+ * @param {[number, number, number]} a
+ * @param {[number, number, number]} b
+ * @returns {number}
+ */
+function cmpSemver(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+
+/**
+ * @typedef {{
+ *   pkg: string,
+ *   version: string,
+ *   dependsOn: string,
+ *   kind: 'dependency' | 'peerDependency',
+ *   requiredRange: string,
+ *   pinnedVersion: string,
+ * }} CoherenceConflict
+ */
+
+/**
+ * @typedef {{
+ *   conflicts: CoherenceConflict[],
+ *   unverified: Array<{ pkg: string, reason: string }>,
+ *   checked: number,
+ * }} CoherenceReport
+ * `checked` counts the pinned packages whose dependency metadata was actually
+ * read (so a clean verdict is grounded in real data); a package whose manifest
+ * was unavailable is in `unverified` and is NOT counted as checked. `checked
+ * === 0` with a non-empty `unverified` therefore means "could not verify
+ * anything", which the caller surfaces as a soft degrade rather than "coherent".
+ */
+
+/**
+ * Validate that a produced importmap's pinned dependency graph is COHERENT
+ * (issue #450). For each resolved package, read its declared `dependencies`
+ * and `peerDependencies` (via the injected `getManifest`) and, for every
+ * declared range that targets ANOTHER package ALSO pinned in this importmap,
+ * check the pinned version satisfies the range. A miss is a conflict naming
+ * both packages, the required range, and the pinned version.
+ *
+ * This is the SAME function the doctor runs over the live importmap and over
+ * `.webjs/vendor/importmap.json`. It is pure in `(imports, getManifest)`, so
+ * the same pinned dep set yields the same verdict regardless of which input it
+ * came from (the runtime-vs-vendored parity invariant).
+ *
+ * Degrades gracefully: a package whose manifest `getManifest` cannot supply
+ * (not installed, unreadable, network unavailable) is recorded under
+ * `unverified` and contributes NO conflict, so the check reports "could not
+ * verify" rather than failing closed. A declared range in a shape we cannot
+ * statically evaluate (see `satisfiesSemverRange` -> null) is likewise skipped,
+ * never warned on.
+ *
+ * @param {Record<string, string>} imports  importmap `imports` map
+ * @param {{
+ *   getManifest: (pkg: string, version: string) =>
+ *     ({ dependencies?: Record<string,string>, peerDependencies?: Record<string,string> } | null
+ *      | Promise<{ dependencies?: Record<string,string>, peerDependencies?: Record<string,string> } | null>),
+ * }} opts  `getManifest` returns the declared dep ranges for a resolved
+ *   `pkg@version`, or null when unavailable (degrade to "unverified").
+ * @returns {Promise<CoherenceReport>}
+ */
+export async function checkImportmapCoherence(imports, opts) {
+  const pinned = extractPinnedVersions(imports);
+  /** @type {CoherenceConflict[]} */
+  const conflicts = [];
+  /** @type {Array<{ pkg: string, reason: string }>} */
+  const unverified = [];
+  // Sort for deterministic output: the same dep set always yields the same
+  // ordering, which keeps the verdict (and any test asserting it) stable and
+  // strengthens the parity guarantee end to end.
+  const packages = [...pinned.keys()].sort();
+  // Count of packages whose metadata we could actually read (so a conflict
+  // verdict is grounded). A package whose manifest is unavailable lands in
+  // `unverified` instead and does NOT count as checked, which lets the caller
+  // distinguish "verified coherent" from "could not verify anything".
+  let checked = 0;
+  for (const pkg of packages) {
+    const version = pinned.get(pkg);
+    let manifest;
+    try {
+      manifest = await opts.getManifest(pkg, version);
+    } catch {
+      manifest = null;
+    }
+    if (!manifest || typeof manifest !== 'object') {
+      unverified.push({ pkg, reason: `could not read dependency metadata for ${pkg}@${version}` });
+      continue;
+    }
+    checked++;
+    const groups = /** @type {const} */ ([
+      ['dependency', manifest.dependencies],
+      ['peerDependency', manifest.peerDependencies],
+    ]);
+    for (const [kind, deps] of groups) {
+      if (!deps || typeof deps !== 'object') continue;
+      for (const [depName, range] of Object.entries(deps)) {
+        // Only edges INTO the pinned graph matter: a dep on a package that is
+        // not in this importmap is not the importmap's coherence problem (it
+        // is either bundled into a CDN megabundle or simply unused on the
+        // client). Self-edges cannot conflict.
+        if (depName === pkg) continue;
+        const depPinned = pinned.get(depName);
+        if (!depPinned) continue;
+        const ok = satisfiesSemverRange(depPinned, String(range));
+        if (ok === false) {
+          conflicts.push({
+            pkg,
+            version: String(version),
+            dependsOn: depName,
+            kind,
+            requiredRange: String(range),
+            pinnedVersion: depPinned,
+          });
+        }
+        // ok === null (range shape not understood) is silently skipped: the
+        // check never warns on a range it could not evaluate.
+      }
+    }
+  }
+  return { conflicts, unverified, checked };
+}
+
 /**
  * Per-process cache of SHA-384 integrity hashes for live-resolved vendor
  * URLs, keyed by the FINAL cross-origin URL. A vendor bundle at a given