@uniweb/build 0.30.2 → 0.32.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniweb/build",
-  "version": "0.30.2",
+  "version": "0.32.0",
   "description": "Build tooling for the Uniweb Component Web Platform",
   "type": "module",
   "exports": {
@@ -59,15 +59,15 @@
     "js-yaml": "^4.1.0",
     "sharp": "^0.35.3",
     "yaml": "^2.5.0",
+    "@uniweb/content-writer": "^0.3.4",
     "@uniweb/content-reader": "^1.2.4",
-    "@uniweb/projections": "^0.5.2",
-    "@uniweb/schemas": "^0.2.12",
-    "@uniweb/semantic-parser": "^1.3.1",
+    "@uniweb/semantic-parser": "^1.4.0",
+    "@uniweb/schemas": "^0.2.13",
     "@uniweb/theming": "^0.1.15",
-    "@uniweb/content-writer": "^0.3.4"
+    "@uniweb/projections": "^0.5.4"
   },
   "optionalDependencies": {
-    "@uniweb/runtime": "^0.13.3"
+    "@uniweb/runtime": "^0.13.5"
   },
   "peerDependencies": {
     "vite": "^5.0.0 || ^6.0.0 || ^7.0.0",
@@ -76,7 +76,7 @@
     "@tailwindcss/vite": "^4.0.0",
     "@vitejs/plugin-react": "^4.0.0 || ^5.0.0",
     "vite-plugin-svgr": "^4.0.0",
-    "@uniweb/core": "^0.14.1"
+    "@uniweb/core": "^0.16.0"
   },
   "peerDependenciesMeta": {
     "vite": {

package/src/site/config.js

@@ -31,6 +31,7 @@ import {
 import { importMapPlugin } from '../import-map-plugin.js'
 import { resolveModuleUrl, resolveExtensionUrls } from './extension-urls.js'
 import { resolveFoundationSrcPath } from '../utils/foundation-source-root.js'
+import { checkFoundationResolution } from '../utils/foundation-resolution-check.js'
 import { detectFoundationType } from './foundation-ref.js'
 
 /**
@@ -191,7 +192,7 @@ export async function defineSiteConfig(options = {}) {
   // Plugin to ensure foundation entry file exists (for bundled mode with local foundation)
   const ensureFoundationEntryPlugin = !isRuntimeMode && foundationInfo.type === 'local' ? {
     name: 'uniweb:ensure-foundation-entry',
-    async config() {
+    async config(_config, env) {
       const srcDir = resolveFoundationSrcPath(foundationInfo.path)
       const entryPath = join(srcDir, '_entry.generated.js')
 
@@ -202,8 +203,50 @@ export async function defineSiteConfig(options = {}) {
         try {
           await generateEntryPoint(srcDir, entryPath)
         } catch (err) {
-          console.warn('[site] Failed to generate foundation entry:', err.message)
+          // ⛔ **Swallowing this on a BUILD is how you get vite's opaque
+          // `Failed to resolve entry for package "<name>"` 50ms later**: we
+          // decline to write the entry, say so in a `console.warn` that scrolls
+          // past, and hand vite a package whose `main` points at a file nobody
+          // created. The message naming the actual cause is the one we printed
+          // and discarded.
+          //
+          // ⚖️ **But only when there is no entry to fall back on.** If a previous
+          // build left one, it is stale rather than absent and the build can
+          // still complete — turning that into a hard failure would break a
+          // build that works today, which is a worse trade than a loud warning.
+          // Dev keeps warning either way: a transient error mid-session must not
+          // kill a running server.
+          const haveFallback = existsSync(entryPath)
+          if (env?.command === 'build' && !haveFallback) {
+            throw new Error(
+              `[site] Could not generate the foundation entry for "${foundationInfo.name}".\n` +
+                `  ${err.message}\n\n` +
+                `  ${entryPath} does not exist, so the build cannot resolve the\n` +
+                `  foundation. Fixing the error above is the fix; vite's next\n` +
+                `  message about resolving package "${foundationInfo.name}" is a\n` +
+                `  symptom of this one.`,
+              { cause: err }
+            )
+          }
+          console.warn(
+            `[site] ⛔ Failed to generate foundation entry: ${err.message}` +
+              (haveFallback
+                ? `\n[site]    Continuing with the EXISTING ${entryPath}, which is now STALE.`
+                : '')
+          )
         }
+
+        // Do we and vite agree on which directory that was? Two resolutions run
+        // here — ours by path, vite's by the bare specifier below
+        // (`alias['#foundation'] = foundationInfo.name`) — and when they diverge
+        // the quiet outcome is worse than the loud one: a stale entry in vite's
+        // directory builds the WRONG foundation and reports success.
+        const agreement = checkFoundationResolution({
+          name: foundationInfo.name,
+          generatedInto: srcDir,
+          siteRoot,
+        })
+        if (!agreement.ok) console.warn(`\n${agreement.message}\n`)
       }
     },
 
@@ -277,7 +320,31 @@ export async function defineSiteConfig(options = {}) {
     // Point #foundation at a virtual noop module.
     alias['#foundation'] = '\0__foundation-noop__'
   } else if (foundationInfo.type !== 'url') {
-    // Bundled mode: #foundation points to the actual package
+    // Bundled mode: #foundation points to the actual package.
+    //
+    // ⛔ **A BARE SPECIFIER, NOT `foundationInfo.path` — and the obvious
+    // "improvement" is measured and wrong.** We hold the resolved path right
+    // here, and handing vite the *name* instead is what lets its node_modules
+    // lookup disagree with ours (the whole reason
+    // `uniweb:ensure-foundation-entry` now runs `checkFoundationResolution`).
+    // Collapsing the two by aliasing to the path looks like it deletes that bug
+    // class. It does not:
+    //
+    //   A vite alias is PREFIX replacement, so `#foundation/styles` — which the
+    //   site's own `entry.js` imports — becomes `<path>/styles`, a filesystem
+    //   path. That bypasses the foundation's `exports` map, and the map is where
+    //   `./styles` → `./styles.css` lives (along with `./dist` and
+    //   `./dist/styles`). Measured 2026-09-01 on a stock marketing scaffold:
+    //   `[vite:load-fallback] Could not load <path>/src/styles (imported by
+    //   entry.js): ENOENT`. A HEALTHY project fails to build.
+    //
+    // Splitting it — exact `#foundation` → path, `#foundation/*` → name — is
+    // worse still: on a diverged tree the entry would come from one directory
+    // and the stylesheet from another, which is a state neither consistent
+    // option can reach.
+    //
+    // ⇒ **The name is load-bearing because the exports map is.** Detecting the
+    // disagreement is the correct shape; eliminating it costs the exports map.
     alias['#foundation'] = foundationInfo.name
   }
 

package/src/utils/foundation-resolution-check.js

@@ -0,0 +1,142 @@
+/**
+ * Do WE and VITE agree on where the foundation is?
+ *
+ * ## The bug this exists for
+ *
+ * A site build resolves its foundation **twice, by two different mechanisms**,
+ * and until 2026-09-01 nothing checked that they agreed:
+ *
+ *   1. **We resolve a PATH.** `detectFoundationType('src', siteRoot)` returns
+ *      `{ type: 'local', path: <siteRoot>/../src }`, and the
+ *      `uniweb:ensure-foundation-entry` plugin generates `_entry.generated.js`
+ *      into exactly that directory.
+ *   2. **Vite resolves a NAME.** `site/config.js` sets
+ *      `alias['#foundation'] = foundationInfo.name` — the bare specifier — so
+ *      Vite runs its own node_modules lookup and reads that package's `main`.
+ *
+ * Those name the same directory only because a package manager linked
+ * `node_modules/<name>` to the foundation. Nothing enforces it, and when it does
+ * not hold we generate into one directory while Vite reads another.
+ *
+ * ## ⛔ The failure is worse when it does NOT fail
+ *
+ * If the directory Vite reaches has no `_entry.generated.js`, the build dies with
+ * vite's `[commonjs--resolver] Failed to resolve entry for package "<name>"` —
+ * opaque, but loud.
+ *
+ * **If it has a STALE one, nothing fails at all.** The site builds against a
+ * different foundation than the one on disk, and reports success. A developer
+ * editing `src/` sees their change generated into `src/_entry.generated.js` and
+ * simply not take effect. *(Measured by the `flows` lane 2026-09-01: their
+ * harness minted fixtures under a `node_modules` that was itself a symlink to a
+ * seed tree, so a relative `../../src` link resolved into the seed. Every run
+ * that mutated its foundation and then built a site had been silently building
+ * the seed's copy — and presenting as green — for as long as the harness had
+ * existed. The red they opened a channel about was the harmless half.)*
+ *
+ * ⇒ **This check is about the silent case.** An error message can only reach the
+ * loud one; comparing the two answers reaches both.
+ *
+ * ## Why it compares REALPATHS and not link text
+ *
+ * `readlink node_modules/<name>` returning `../../src` looks healthy and proves
+ * nothing: **a relative symlink resolves against the link's target, not its
+ * location**, so with `node_modules` itself a link, `../../src` lands in a
+ * different tree. Only the resolved physical path answers the question vite
+ * actually asks. *(This module's first draft compared link text. It reported
+ * healthy on the one tree that was broken.)*
+ *
+ * ## Why it does its own node_modules walk
+ *
+ * `createRequire(...).resolve(name)` cannot be used: in the failure case `main`
+ * points at the missing entry, so it throws rather than telling us where it
+ * looked. `require.resolve(name + '/package.json')` cannot either — a foundation
+ * declares `exports: { ".": "./_entry.generated.js" }`, which gates every other
+ * subpath, so that lookup fails on a *healthy* package.
+ *
+ * So we walk `node_modules` upward for the package directory, which is the part
+ * of node resolution that locates a package before `exports` or `main` is
+ * consulted. That is the step whose answer we need.
+ */
+
+import { existsSync, realpathSync } from 'node:fs'
+import { dirname, join, parse } from 'node:path'
+
+/**
+ * The directory a bare specifier's package lives in, by node's own
+ * node_modules walk — the step that runs before `exports`/`main` are read.
+ *
+ * @param {string} name - the bare specifier (a foundation's package name)
+ * @param {string} fromDir - the directory resolution starts in (the site root)
+ * @returns {string|null} the package directory, or null if no node_modules
+ *   anywhere up the tree holds it
+ */
+export function findPackageDir(name, fromDir) {
+  let dir = fromDir
+  const { root } = parse(fromDir)
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const candidate = join(dir, 'node_modules', name)
+    if (existsSync(join(candidate, 'package.json'))) return candidate
+    if (dir === root) return null
+    const parent = dirname(dir)
+    if (parent === dir) return null
+    dir = parent
+  }
+}
+
+/**
+ * Compare where we generated the foundation entry against where vite will look.
+ *
+ * ⭐ **Silence is deliberate when the package is not found at all.** Not every
+ * supported layout puts the foundation in the site's `node_modules` — a
+ * `foundations/<name>/` multi-site project may not — and a warning that fires on
+ * a healthy project is worse than no warning, because the next person learns to
+ * ignore it. A package we cannot locate is also a case vite will fail on by
+ * itself, loudly. **We report only a disagreement we can actually prove**, which
+ * makes a false positive impossible by construction.
+ *
+ * @param {Object} args
+ * @param {string} args.name - the foundation's declared name (the bare specifier)
+ * @param {string} args.generatedInto - the directory we wrote `_entry.generated.js` to
+ * @param {string} args.siteRoot - where vite resolves the bare specifier from
+ * @returns {{ ok: true } | { ok: false, ours: string, theirs: string, message: string }}
+ */
+export function checkFoundationResolution({ name, generatedInto, siteRoot }) {
+  const theirsRaw = findPackageDir(name, siteRoot)
+  if (!theirsRaw) return { ok: true }
+
+  let ours, theirs
+  try {
+    ours = realpathSync(generatedInto)
+    theirs = realpathSync(theirsRaw)
+  } catch {
+    // A path vanished between the walk and the realpath. Not a disagreement we
+    // can prove, so it is not one we report.
+    return { ok: true }
+  }
+
+  if (ours === theirs) return { ok: true }
+
+  return {
+    ok: false,
+    ours,
+    theirs,
+    message: [
+      `[site] ⛔ Foundation "${name}" resolves to two different directories.`,
+      ``,
+      `  we generated its entry into : ${ours}`,
+      `  vite will import it from    : ${theirs}`,
+      ``,
+      `  Your site build will use the SECOND one, so edits to the first do not`,
+      `  take effect — and if that directory carries a stale _entry.generated.js`,
+      `  the build SUCCEEDS against the wrong foundation.`,
+      ``,
+      `  This means node_modules/${name} under ${siteRoot} is not the foundation`,
+      `  directory. Re-run your package manager's install. If you copied or moved`,
+      `  this project, check whether node_modules (or a parent of it) is a symlink`,
+      `  into another tree — a relative link inside one resolves against the link's`,
+      `  target, so it can point outside this project while looking correct.`,
+    ].join('\n'),
+  }
+}