@webjsdev/server 0.8.91 → 0.10.0

package/src/dev/watch-tree.js

@@ -1,6 +1,7 @@
 import { watch, readdirSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { watchRecursive } from './watch-recursive.js';
+import { pollTree, isWatchLimitError } from './watch-poll.js';
 
 /**
  * The dev live-reload watcher over one root (#1521).
@@ -25,58 +26,94 @@ import { watchRecursive } from './watch-recursive.js';
  * root watcher's events, so `mkdir lib` mid-session is watched like it was
  * there at boot.
  *
+ * When the OS runs out of watches (ENOSPC once the inotify limit is reached,
+ * EMFILE for file descriptors, #1689), the directory that failed is polled
+ * instead (`watch-poll.js`) and `onFallback` is told once per directory, so its
+ * edits keep arriving, a second slower, instead of never. A root watcher that
+ * fails that way polls the root's direct entries.
+ *
  * @param {string} root  absolute directory to watch
  * @param {{
  *   ignore: (relPath: string) => boolean,
  *   onEvent: (relPath: string) => void,
  *   onError: (err: NodeJS.ErrnoException) => void,
- * }} opts  `relPath` is relative to `root`, with OS separators.
+ *   onFallback?: (name: string, err: NodeJS.ErrnoException) => void,
+ *   watchFn?: typeof watch,
+ *   pollMs?: number,
+ * }} opts  `relPath` is relative to `root`, with OS separators. `onFallback`
+ *   gets the top-level directory name (`''` for the root). `watchFn` and
+ *   `pollMs` are test seams.
  * @returns {() => void} closes every watcher
  */
-export function watchTree(root, { ignore, onEvent, onError }) {
-  /** @type {Map<string, import('node:fs').FSWatcher>} */
+export function watchTree(root, { ignore, onEvent, onError, onFallback, watchFn = watch, pollMs = 1000 }) {
+  /** @type {Map<string, { close: () => void, polled?: boolean }>} */
   const dirs = new Map();
   let closed = false;
 
-  const guard = (/** @type {import('node:fs').FSWatcher} */ w) => {
-    w.on('error', (err) => onError(/** @type {NodeJS.ErrnoException} */ (err)));
-    return w;
-  };
-
   const isDir = (name) => {
     try { return statSync(join(root, name)).isDirectory(); } catch { return false; }
   };
 
+  /** Replace a top-level directory's watcher with a poller. */
+  const pollDir = (name, /** @type {NodeJS.ErrnoException} */ err) => {
+    if (closed || dirs.get(name)?.polled) return;
+    try { dirs.get(name)?.close(); } catch {}
+    const stop = pollTree(join(root, name), {
+      ignore: (rel) => ignore(join(name, rel)),
+      onEvent: (rel) => onEvent(join(name, rel)),
+      intervalMs: pollMs,
+    });
+    dirs.set(name, { close: stop, polled: true });
+    onFallback?.(name, err);
+  };
+
   const watchDir = (name) => {
     if (closed || dirs.has(name) || ignore(name)) return;
+    const failed = (/** @type {NodeJS.ErrnoException} */ err) => {
+      if (isWatchLimitError(err)) pollDir(name, err);
+      else onError(err);
+    };
     try {
       // `watchRecursive` (#1529): on Linux under Node a per-directory walker,
       // since Node 24's recursive watcher goes deaf to a file once it is
       // replaced (`sed -i`, an editor's atomic save).
-      const w = guard(watchRecursive(join(root, name), (_type, filename) => {
+      const w = watchRecursive(join(root, name), (_type, filename) => {
         const rel = filename ? join(name, String(filename)) : name;
         if (!ignore(rel)) onEvent(rel);
-      }, { ignore: (rel) => ignore(join(name, rel)) }));
+      }, { ignore: (rel) => ignore(join(name, rel)), watchFn });
+      w.on('error', (err) => failed(/** @type {NodeJS.ErrnoException} */ (err)));
       dirs.set(name, w);
     } catch (err) {
-      onError(/** @type {NodeJS.ErrnoException} */ (err));
+      failed(/** @type {NodeJS.ErrnoException} */ (err));
     }
   };
 
-  /** @type {import('node:fs').FSWatcher | null} */
+  /** A top-level entry changed: start or stop following it as a directory. */
+  const onTop = (/** @type {string} */ name) => {
+    if (ignore(name)) return;
+    if (isDir(name)) watchDir(name);
+    else if (dirs.has(name)) { try { dirs.get(name)?.close(); } catch {} dirs.delete(name); }
+    onEvent(name);
+  };
+
+  /** @type {{ close: () => void } | null} */
   let top = null;
+  const pollRoot = (/** @type {NodeJS.ErrnoException} */ err) => {
+    if (closed) return;
+    try { top?.close(); } catch {}
+    top = { close: pollTree(root, { ignore, onEvent: onTop, intervalMs: pollMs, recursive: false }) };
+    onFallback?.('', err);
+  };
+  const rootFailed = (/** @type {NodeJS.ErrnoException} */ err) => {
+    if (isWatchLimitError(err)) pollRoot(err);
+    else onError(err);
+  };
   try {
-    top = guard(watch(root, (_type, filename) => {
-      if (!filename) return;
-      const name = String(filename);
-      if (ignore(name)) return;
-      // A top-level entry changed: start or stop following it as a directory.
-      if (isDir(name)) watchDir(name);
-      else if (dirs.has(name)) { try { dirs.get(name)?.close(); } catch {} dirs.delete(name); }
-      onEvent(name);
-    }));
+    const w = watchFn(root, (_type, filename) => { if (filename) onTop(String(filename)); });
+    w.on('error', (err) => rootFailed(/** @type {NodeJS.ErrnoException} */ (err)));
+    top = w;
   } catch (err) {
-    onError(/** @type {NodeJS.ErrnoException} */ (err));
+    rootFailed(/** @type {NodeJS.ErrnoException} */ (err));
   }
 
   let entries = [];

package/src/dev-classify.js

@@ -18,9 +18,8 @@
  * heuristic ("anything under `app/**` named `page.ts` can morph") is wrong in
  * both directions and neither failure is exotic:
  *
- * - A page that imports a client-effecting non-component util SHIPS WHOLE (the
- *   import-only rule in `component-elision.js`, #605 / #963). Editing it changes
- *   browser-bound JS, so it must reload despite being a page.
+ * - A page never ships (#1686), but a helper it imports may also be imported by
+ *   a component, which makes it browser-bound JS: editing it must reload.
  * - A helper under `modules/<feature>/utils/` imported by both a page and a
  *   component is a component edit by reachability, and its path says nothing.
  *
@@ -29,9 +28,9 @@
  */
 
 /**
- * The three verdicts, STRONGEST FIRST. The index in this array IS the strength
- * order, which is what `strongerVerdict` compares and what lets a batch of
- * changes collapse to the strongest verdict it contains rather than the last.
+ * The verdicts, STRONGEST FIRST. The index in this array IS the strength order,
+ * which is what `mergeVerdicts` compares and what lets a batch of changes
+ * collapse to the strongest verdict it contains rather than the last.
  *
  * - `reload`: a component module, anything transitively reaching one, or any
  *   path the server cannot place. The browser does `location.reload()`.
@@ -40,21 +39,40 @@
  * - `page`: a page module and nothing else. The browser re-renders the current
  *   URL and morphs the deepest shared boundary, preserving scroll AND the
  *   hydrated state of components outside the changed region.
+ * - `component`: browser modules the tab re-imports and patches onto the live
+ *   component classes (#1689), listed in the verdict's `modules`. A tab with no
+ *   hot-swap support applies it as a full reload.
+ * - `css`: a stylesheet and nothing else (#1689). The tab re-requests its
+ *   stylesheets and swaps them in. A tab with no support reloads.
  *
- * @type {readonly ['reload', 'shell', 'page']}
+ * @type {readonly ['reload', 'shell', 'page', 'component', 'css']}
  */
-export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page']);
+export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page', 'component', 'css']);
 
 /**
- * @typedef {{ v: 'page' | 'shell' | 'reload', by: string, why: string }} ReloadVerdict
+ * A live-reload verdict. `modules` lists the versioned browser URLs a
+ * `component` verdict asks the tab to re-import, and `css` says a stylesheet
+ * changed too, so the tab refreshes its sheets on top of whatever else it does.
+ *
+ * @typedef {{
+ *   v: 'reload' | 'shell' | 'page' | 'component' | 'css',
+ *   by: string,
+ *   why: string,
+ *   modules?: string[],
+ *   css?: true,
+ * }} ReloadVerdict
  */
 
 /**
- * The stronger of two verdicts, treating `null` / `undefined` as weakest and an
- * unrecognised one as `reload` (fail safe, never fail open).
+ * Merge two verdicts into the one a batch applies, treating `null` /
+ * `undefined` as nothing and an unrecognised name as `reload` (fail safe, never
+ * fail open). `v`, `by` and `why` come from the stronger verdict (the first on
+ * a tie). `modules` is the sorted union of both and `css` is set when either
+ * sets it, because a weaker change in the batch still needs its own work done
+ * alongside the stronger one.
  *
  * Used twice for the same reason. The watcher can see several files change
- * inside one 80ms debounce window, and the browser relay coalesces a burst of
+ * inside one debounce window, and the browser relay coalesces a burst of
  * signals into ONE emitted reload (#1397). In both places a batch mixing a page
  * edit and a component edit is a COMPONENT edit, so taking the last verdict
  * would leave the old component class running against fresh markup.
@@ -63,10 +81,16 @@ export const RELOAD_VERDICTS = /** @type {const} */ (['reload', 'shell', 'page']
  * @param {ReloadVerdict | null | undefined} b
  * @returns {ReloadVerdict | null}
  */
-export function strongerVerdict(a, b) {
+export function mergeVerdicts(a, b) {
   if (!a) return b || null;
   if (!b) return a;
-  return verdictRank(a.v) <= verdictRank(b.v) ? a : b;
+  const top = verdictRank(a.v) <= verdictRank(b.v) ? a : b;
+  /** @type {ReloadVerdict} */
+  const out = { v: top.v, by: top.by, why: top.why };
+  const modules = [...new Set([...(a.modules || []), ...(b.modules || [])])].sort();
+  if (modules.length) out.modules = modules;
+  if (a.css || b.css) out.css = true;
+  return out;
 }
 
 /**
@@ -96,7 +120,7 @@ function verdictRank(v) {
  *    gap. Reading currency here would therefore turn the feature off for every
  *    edit after the first in a burst. Classifying against the previous build's
  *    graph is the intended behaviour, and it is conservative in the right
- *    direction: a file the stale graph has never seen falls to rung 6 and
+ *    direction: a file the stale graph has never seen falls to rung 7 and
  *    reloads.
  * 2. The path is outside `appDir`. The watcher only fires for `appDir` plus the
  *    opt-in `webjs.dev.watch` roots (#894), and a file outside `appDir` is
@@ -104,25 +128,33 @@ function verdictRank(v) {
  *    change what any layout renders, so it takes the whole-body `shell` swap.
  * 3. The path is in the SHIPPED closure. This is the transitive answer and the
  *    one that matters: the browser holds this module, so the page must reload.
- * 4. The path is a page module. Morphable.
- * 5. The path is somewhere else in the module graph (a layout, a server-only
+ *    A CSS module script (`import s from './x.css' with { type: 'css' }`) is in
+ *    the closure too, so it stops here and never reaches rung 4.
+ * 4. The path is a stylesheet (`.css`) the browser does not hold as a module
+ *    (#1689): a `public/` sheet, an `@import`ed partial, a
+ *    `webjs.dev.regenerate` input such as Tailwind's. The tab re-requests every
+ *    same-origin stylesheet and swaps them in place, with no reload and no
+ *    re-render. Every sheet rather than the changed one, which is what makes a
+ *    partial and a regenerate output come out right, since neither is the file
+ *    the page links.
+ * 5. The path is a page module. Morphable.
+ * 6. The path is somewhere else in the module graph (a layout, a server-only
  *    util, a `.server.*` file reachable only from a page). Server-only by
  *    elimination, so `shell`.
- * 6. Anything else. A brand-new file, a deleted file, and every `public/` asset
- *    land here. `public/` is not in the module graph at all, so the server
- *    cannot tell what the file IS or what depends on it, and most of what lives
- *    there (an image, a font, a service worker, a hand-written script) is
- *    something no amount of re-rendering picks up. The refresh does re-request
- *    the page's stylesheets, so a `public/` CSS edit alone would now survive a
- *    morph, but that is one knowable case inside a rung whose whole point is
- *    that the file is unknowable.
+ * 7. Anything else. A brand-new file, a deleted file, and every other `public/`
+ *    asset land here. `public/` is not in the module graph at all, so the
+ *    server cannot tell what the file IS or what depends on it, and most of
+ *    what lives there (an image, a font, a service worker, a hand-written
+ *    script) is something no amount of re-rendering picks up. A stylesheet is
+ *    the one kind it can name from the path alone, which is why rung 4 takes
+ *    it out first.
  *
  * Note what step 3 sweeps in deliberately. A `'use server'` action file
  * imported by a SHIPPING component is inside the closure (the graph keeps a
  * `.server.*` node and stops at it), so editing it reloads. That is correct
  * rather than merely conservative, because adding an export to that file
  * changes the generated RPC stub the browser holds. The same action imported
- * only by a page falls to step 5 and gets `shell`.
+ * only by a page falls to step 6 and gets `shell`.
  *
  * @param {string} abs  absolute path of the changed file
  * @param {object} ctx
@@ -141,6 +173,7 @@ export function classifyChangedPath(abs, ctx) {
   if (!ctx.analysisReady) return { v: 'reload', by, why: 'analysis-cold' };
   if (!isUnder(abs, ctx.appDir, sep)) return { v: 'shell', by, why: 'extra-watch-root' };
   if (ctx.shippedFiles && ctx.shippedFiles.has(abs)) return { v: 'reload', by, why: 'ships-to-browser' };
+  if (abs.endsWith('.css')) return { v: 'css', by, why: 'stylesheet', css: true };
   if (ctx.pageFiles && ctx.pageFiles.has(abs)) return { v: 'page', by, why: 'page-module' };
   if (ctx.graphFiles && ctx.graphFiles.has(abs)) return { v: 'shell', by, why: 'server-only-module' };
   return { v: 'reload', by, why: 'unknown-path' };

package/src/dev-error.js

@@ -14,7 +14,10 @@
  * offending source file for the code frame (a read failure degrades to no
  * frame, never throws).
  */
-import { readFileSync } from 'node:fs';
+import { readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { findDecorator, decoratorReport, parseMissingExport, isCoreModule, missingCoreNameFix } from './lit-hints.js';
+import { coreSurface, isTypeOnlyAnywhere } from './core-exports.js';
 
 /**
  * Pull the first useful `file:line:column` out of an error stack. Prefers a
@@ -40,7 +43,9 @@ export function parseStackLocation(stack, appDir) {
   // (the `file:///` URL form, whose path uses forward slashes, still resolves).
   // That matches the framework's POSIX-first dev posture; it degrades, never
   // crashes.
-  const re = /(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+):(\d+)/g;
+  // The lookbehind keeps a runtime-internal frame (`node:internal/modules/...`)
+  // from reading as the path `/modules/...`.
+  const re = /(?<![\w.-])(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+):(\d+)/g;
   /** @type {{ file: string, line: number, column: number }[]} */
   const frames = [];
   let m;
@@ -114,6 +119,15 @@ export function buildDevErrorFrame(error, opts = {}) {
   let file = opts.file || null;
   let line = opts.line != null ? opts.line : null;
   let column = opts.column != null ? opts.column : null;
+  // A module that fails to PARSE (a decorator is the common case) throws a
+  // SyntaxError whose stack OPENS with a bare `file:///abs/x.ts:2` header (a
+  // line, no column) and continues with node:internal frames only, which the
+  // frame pattern would misread as a path. The header names the source, so it
+  // wins.
+  if (!file && stack) {
+    const head = /^(?:file:\/\/)?(\/[^\s:()?]+)(?:\?[^\s:()]*)?:(\d+)[ \t]*\n/.exec(stack);
+    if (head) { file = head[1]; line = Number(head[2]); }
+  }
   if (!file && stack) {
     const loc = parseStackLocation(stack, opts.appDir);
     if (loc) { file = loc.file; line = loc.line; column = loc.column; }
@@ -125,6 +139,20 @@ export function buildDevErrorFrame(error, opts = {}) {
     const loc = parseStackLocation(`${err.message}\n${stack || ''}`, opts.appDir);
     if (loc && loc.file === file) { line = loc.line; column = loc.column; }
   }
+  // A module that fails to PARSE, caught rather than crashing the process,
+  // carries no location at all on Node (the `file:line` arrow header is only
+  // printed for an uncaught error), so a decorator three imports down leaves
+  // the overlay with nothing to point at. The usual cause of an unexpected
+  // token in a WebJs app is a decorator, so look for one in the app source.
+  let hint = opts.hint || null;
+  if (!hint && !file && err instanceof SyntaxError && opts.appDir) {
+    const found = findAppDecorator(opts.appDir);
+    if (found) {
+      file = found.file; line = found.hit.line; column = found.hit.column;
+      const { message, fix } = decoratorReport(found.hit);
+      hint = `${message} ${fix}`;
+    }
+  }
   const codeFrame = file && line ? readCodeFrame(file, line, column || 0) : null;
   return {
     kind,
@@ -134,7 +162,80 @@ export function buildDevErrorFrame(error, opts = {}) {
     line,
     column,
     codeFrame,
-    hint: opts.hint || null,
+    hint: hint || inferHint(err, file, opts.appDir) || null,
     url: typeof opts.url === 'string' && opts.url ? opts.url : null,
   };
 }
+
+/**
+ * Name the WebJs fix for an error whose own message does not, so the overlay
+ * says what to write instead of only what broke.
+ *
+ * A decorator (`@customElement`, `@property`, ...) is the case it exists for.
+ * Node fails the module with a bare `SyntaxError: Invalid or unexpected
+ * token`, and Bun, which runs legacy decorators, with a `ReferenceError` for
+ * the undefined decorator function. Neither names the fix, so when the failing
+ * file carries a decorator the hint is the one `webjs check` prints.
+ *
+ * The other is a name `@webjsdev/core` does not export (`LitElement`, a
+ * decorator function, a type imported as a value). Node says `does not provide
+ * an export named X` and Bun `Export named 'X' not found`; the hint is the one
+ * the `core-imports-exist` check rule prints for the same import.
+ *
+ * @param {Error} err
+ * @param {string | null} file  the located source file, when there is one
+ * @param {string} [appDir]  resolves the core package the app imports
+ * @returns {string | null}
+ */
+export function inferHint(err, file, appDir) {
+  const missing = parseMissingExport(err.message);
+  if (missing && isCoreModule(missing.module)) {
+    const surface = coreSurface(appDir);
+    const typeOnly = !!surface && isTypeOnlyAnywhere(surface, missing.name);
+    return `\`${missing.name}\` is not a runtime export of @webjsdev/core. ${missingCoreNameFix(missing.name, { typeOnly })}`;
+  }
+  if ((err instanceof SyntaxError || err instanceof ReferenceError) && file) {
+    let src = null;
+    try { src = readFileSync(file, 'utf8'); } catch { src = null; }
+    const hit = src ? findDecorator(src) : null;
+    if (hit) {
+      const { message, fix } = decoratorReport(hit);
+      return `${message} ${fix}`;
+    }
+  }
+  return null;
+}
+
+/**
+ * The first decorator in the app's own source, walking every JS / TS file
+ * outside node_modules, `public/`, and dot or underscore folders. Dev-only and
+ * reached only for an unlocated SyntaxError, so the synchronous walk costs
+ * nothing on the happy path.
+ *
+ * @param {string} appDir
+ * @returns {{ file: string, hit: { name: string, index: number, line: number, column: number } } | null}
+ */
+function findAppDecorator(appDir) {
+  /** @type {string[]} */
+  const stack = [appDir];
+  let budget = 5000;
+  while (stack.length && budget-- > 0) {
+    const dir = /** @type {string} */ (stack.pop());
+    let entries;
+    try { entries = readdirSync(dir, { withFileTypes: true }); } catch { continue; }
+    for (const e of entries) {
+      if (e.name === 'node_modules' || e.name.startsWith('.') || e.name.startsWith('_')) continue;
+      const abs = join(dir, e.name);
+      if (e.isDirectory()) {
+        if (dir === appDir && e.name === 'public') continue;
+        stack.push(abs);
+      } else if (/\.m?[jt]s$/.test(e.name)) {
+        let src;
+        try { src = readFileSync(abs, 'utf8'); } catch { continue; }
+        const hit = findDecorator(src);
+        if (hit) return { file: abs, hit };
+      }
+    }
+  }
+  return null;
+}