@webjsdev/server 0.8.49 → 0.8.50

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/server",
-  "version": "0.8.49",
+  "version": "0.8.50",
   "type": "module",
   "description": "webjs dev/prod server: SSR, router, API, server actions, live reload",
   "main": "index.js",

package/src/check.js

@@ -7,7 +7,7 @@ import {
   matchClosingBrace,
   parsePropEntries,
 } from './js-scan.js';
-import { buildModuleGraph, transitiveDeps } from './module-graph.js';
+import { buildModuleGraph, transitiveDeps, resolveImport } from './module-graph.js';
 import { scanComponents } from './component-scanner.js';
 import { buildRouteTable } from './router.js';
 import { analyzeElision } from './component-elision.js';
@@ -144,6 +144,11 @@ export const RULES = [
     description:
       'Flags a template interpolation (`${...}`) placed as a child of a `<style>` or `<script>` element inside a COMPONENT `html` template. Raw-text elements are an SSR/client asymmetry trap: the server renderer emits the interpolated content, but the client renderer drops it (a raw-text hole is a `noop`, since the compile cache is keyed on the static strings), so the element renders correctly on the server and then wipes to empty on hydration. Scoped to components (files with a `WebComponent` class), which hydrate; pages and layouts render server-only and never hydrate, so a page interpolating a `css` result into a `<style>` is a legitimate pattern and is not flagged. In a component, author scoped CSS with `static styles` (shadow DOM) or a `css` template. Found dogfooding a tic-tac-toe app (#845): a `<style>${STYLE}</style>` painted at SSR then vanished on hydrate.',
   },
+  {
+    name: 'no-missing-local-import',
+    description:
+      'Flags a NAMED value import of a symbol that a resolvable app-internal module does not export (`import { todos } from \'#db/schema.server.ts\'` when the schema no longer exports `todos`). The binding is `undefined` at runtime and crashes on first use, yet the rest of `webjs check` (elision-based, it does not compile types) misses it, so a schema swap that orphans a gallery module can pass `check` while `typecheck` is red. This is the runtime-crash class `check` exists to catch, filling that gap so an agent running only `check` cannot ship a broken import. Deliberately conservative to never false-positive on a valid app: it only inspects app-internal specifiers (a relative `./` path or a `#` alias) that resolve to a file in the app, only NAMED value imports (a `type` import, a default import, a namespace import, and any bare / `node:` / npm-package specifier are skipped), and it treats a module as UNKNOWABLE (never flags imports from it) when its exports are not fully enumerable: a `export * from ...` star re-export, a destructuring `export const { a } = ...`, or a multi-declarator `export const a = .., b = ..`. It reads names from `export function/class/const/let/var/type/interface/enum` and from `export { a, b as c }` / `export { x } from ...` clauses (the alias after `as` is the exported name). A re-export barrel therefore resolves correctly, and a `\'use server\'` action file exports its function names normally. Found dogfooding a tic-tac-toe app: dropping the example `todos` table left a gallery module importing it, green under `check` but red under `typecheck`.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -379,6 +384,112 @@ function findBrowserMemberUses(code) {
   return out;
 }
 
+/**
+ * True if any `export const/let/var` declares more than one binding
+ * (`export const a = 1, b = 2`), which the single-name collector would
+ * under-count. Depth-aware: a comma inside an initializer (`f(a, b)`, `[a, b]`,
+ * `{ a, b }`) does not count, only a top-level comma before the statement end.
+ * Bailing the whole module on this errs toward a false negative (safe), never a
+ * false positive. Runs on the string/comment-redacted `scan`.
+ * @param {string} scan
+ * @returns {boolean}
+ */
+function hasMultiDeclaratorExport(scan) {
+  const re = /\bexport\s+(?:const|let|var)\b/g;
+  let m;
+  while ((m = re.exec(scan))) {
+    let depth = 0;      // () [] {} nesting
+    let angle = 0;      // <> generics, tracked ONLY inside a type annotation
+    let seenEq = false; // passed this declarator's `=` (now in the initializer)
+    let inType = false; // inside a `: Type` annotation (before the `=`)
+    for (let i = m.index + m[0].length; i < scan.length; i++) {
+      const ch = scan[i];
+      if (ch === '(' || ch === '[' || ch === '{') { depth++; continue; }
+      if (ch === ')' || ch === ']' || ch === '}') { if (depth === 0) break; depth--; continue; }
+      if (depth !== 0) continue;
+      if (ch === ';') break;
+      // A plain `=` ends the type annotation and enters the initializer. `<=`,
+      // `>=`, `=>`, `==` are harmless here (seenEq only latches true).
+      if (ch === '=') { seenEq = true; inType = false; angle = 0; continue; }
+      // A `:` BEFORE the `=` opens the type annotation. A `:` after `=` (a
+      // ternary in the initializer) is NOT a type and must not suppress a real
+      // declarator comma.
+      if (ch === ':' && !seenEq) { inType = true; continue; }
+      // Inside a type annotation `<` / `>` are generic delimiters (a comparison
+      // only appears in the initializer, after `=`). Track their depth so a
+      // generic's comma (`Map<string, number>`) is skipped while a real
+      // declarator comma (`a: number, b: number`) still counts. A `>` that is
+      // part of a `=>` function-type arrow is not a generic close.
+      if (inType && ch === '<') { angle++; continue; }
+      if (inType && ch === '>' && scan[i - 1] !== '=') { if (angle > 0) angle--; continue; }
+      // A top-level comma starts a second declarator UNLESS it is a generic's
+      // comma inside a type annotation.
+      if (ch === ',' && !(inType && angle > 0)) return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Enumerate a module's provable named exports from its redacted `scan`, for the
+ * `no-missing-local-import` rule. Returns `null` when the export list is NOT
+ * fully enumerable (a `export *` star re-export, a destructuring export, or a
+ * multi-declarator `export const a = .., b = ..`), which tells the rule to treat
+ * the module as unknowable and flag nothing from it. Otherwise returns the set
+ * of exported names (the alias after `as` for a clause, and type/interface/enum
+ * names too, so a value import of a type is not falsely flagged; tsc owns that).
+ * @param {string} scan  string/template/comment-redacted source
+ * @returns {Set<string>|null}
+ */
+function enumerableExports(scan) {
+  // Unknowable export shapes: bail so the rule never false-positives.
+  if (/\bexport\s*\*/.test(scan)) return null;                       // export * from
+  if (/\bexport\s+(?:const|let|var)\s*[{[]/.test(scan)) return null; // destructuring export
+  if (hasMultiDeclaratorExport(scan)) return null;                   // export const a=1, b=2
+  const names = new Set();
+  let m;
+  const collect = (re) => { while ((m = re.exec(scan))) names.add(m[1]); };
+  collect(/\bexport\s+(?:async\s+)?function\b\s*\*?\s*([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:abstract\s+)?class\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:const|let|var)\s+([A-Za-z_$][\w$]*)/g);
+  collect(/\bexport\s+(?:type|interface|enum|namespace)\s+([A-Za-z_$][\w$]*)/g);
+  // A named-default import (`import { default as Foo }`) is legal against an
+  // `export default` module, so record the `default` name when present.
+  if (/\bexport\s+default\b/.test(scan)) names.add('default');
+  // `export { a, b as c }` / `export type { ... }` / `export { x } from '...'`:
+  // the EXPORTED name is the alias after `as`, else the bare name.
+  const reClause = /\bexport\s+(?:type\s+)?\{([^}]*)\}/g;
+  while ((m = reClause.exec(scan))) {
+    for (let part of m[1].split(',')) {
+      part = part.trim().replace(/^type\s+/, '');
+      if (!part) continue;
+      const name = part.split(/\s+as\s+/).pop().trim();
+      if (/^[A-Za-z_$][\w$]*$/.test(name)) names.add(name);
+    }
+  }
+  return names;
+}
+
+/**
+ * The NAMED VALUE names a single `import { ... } from` clause pulls in, for the
+ * `no-missing-local-import` rule. Returns `null` for an `import type { ... }`
+ * (all type, skip), and `[]` for a default / namespace / side-effect import
+ * (nothing named to verify). A per-specifier inline `type` marker is dropped,
+ * and for `a as b` the IMPORTED name is `a` (what the target must export).
+ * @param {string} clause  the text between `import` and `from`
+ * @returns {string[]|null}
+ */
+function importedValueNames(clause) {
+  if (/^\s*type\b/.test(clause)) return null; // import type { ... }
+  const brace = clause.match(/\{([^}]*)\}/);
+  if (!brace) return []; // default / namespace only
+  return brace[1].split(',')
+    .map((s) => s.trim())
+    .filter((s) => s && !/^type\s/.test(s))
+    .map((s) => s.split(/\s+as\s+/)[0].trim())
+    .filter((n) => /^[A-Za-z_$][\w$]*$/.test(n));
+}
+
 /**
  * Scan a WebJs app directory and report convention violations.
  *
@@ -1125,6 +1236,59 @@ export async function checkConventions(appDir) {
   // directly, so it is not elided and ships the server import.
   await checkServerImportInBrowserModule(appDir, violations);
 
+  // --- Rule: no-missing-local-import ---
+  // A named value import of a symbol an app-internal module does not export is a
+  // runtime crash (the binding is undefined) that the elision-based checks miss,
+  // so `check` can stay green while `typecheck` is red (a dropped schema table
+  // orphaning a gallery module is the motivating dogfood case). Conservative by
+  // construction: only app-internal specifiers resolving to a known app file,
+  // only named value imports, and only when the target's exports are fully
+  // enumerable (see enumerableExports / importedValueNames).
+  {
+    // Fully-blanked view (blankStrings=true): string AND template AND comment
+    // bodies blank to spaces, position-preserving. The default `scan` keeps
+    // plain-string bodies VERBATIM (so callers can read `register('tag')`),
+    // which would let an `import`/`export` inside a string be matched, so use
+    // the fully-blanked view for both the export map and the import scan. The
+    // real specifier is read back from `content` at the same (length-preserved)
+    // offset.
+    const maskedByAbs = new Map();
+    for (const f of files) maskedByAbs.set(f.abs, redactStringsAndTemplates(f.content, true));
+    const exportsByAbs = new Map();
+    for (const f of files) exportsByAbs.set(f.abs, enumerableExports(maskedByAbs.get(f.abs)));
+    // `import\s+` excludes `import.meta` and a dynamic `import(`. The clause is
+    // `[^'";]*?` so it cannot swallow a side-effect `import '...'` (its quote) or
+    // bridge across a `;` into the next statement's `from`.
+    const reImport = /\bimport\s+([^'";]*?)\bfrom\s*(['"])/g;
+    for (const { abs, rel, content } of files) {
+      const masked = maskedByAbs.get(abs);
+      reImport.lastIndex = 0;
+      let m;
+      while ((m = reImport.exec(masked))) {
+        const quote = m[2];
+        const specStart = reImport.lastIndex;           // just past the opening quote
+        const specEnd = content.indexOf(quote, specStart);
+        if (specEnd < 0) continue;
+        const spec = content.slice(specStart, specEnd);
+        if (!/^(?:\.|#)/.test(spec)) continue; // app-internal only (relative or #alias)
+        const names = importedValueNames(m[1]);
+        if (!names || names.length === 0) continue;
+        const target = resolveImport(spec, abs, appDir);
+        const exp = exportsByAbs.get(target);
+        if (exp == null) continue; // not an app file, or exports not enumerable
+        for (const name of names) {
+          if (exp.has(name)) continue;
+          violations.push({
+            rule: 'no-missing-local-import',
+            file: rel,
+            message: `Imports \`${name}\` from \`${spec}\`, but that module does not export \`${name}\`. The binding is undefined at runtime and crashes on first use (often a renamed or removed export, e.g. a dropped schema table).`,
+            fix: `Add \`${name}\` to \`${spec}\`, correct the imported name, or remove the import.`,
+          });
+        }
+      }
+    }
+  }
+
   return violations;
 }
 

package/src/ssr.js

@@ -1528,6 +1528,7 @@ function wrapHead(opts) {
 <html lang="en">
 <head>
 <meta charset="utf-8">
+<style${n}>@layer webjs-host{:where([data-wj-host]){display:block}:where([data-wj-host][hidden]:not([hidden='until-found'])){display:none}}</style>
 ${opts.nonce ? `<meta name="csp-nonce" content="${escapeAttr(opts.nonce)}">` : ''}
 ${metaTags.join('\n')}
 <title>${escapeHtml(title)}</title>

package/src/vendor.js

@@ -1176,9 +1176,16 @@ async function pruneOrphans(appDir, expected) {
  * instead. When the app has zero bare-specifier imports at all
  * (scanned source produced nothing), returns
  * `{ pins: [], pruned: [], downloaded: 0, noBareImports: true }`
- * WITHOUT writing the pin file. Callers that need to surface a
- * non-zero exit code key off `failed` or `noBareImports`; both
- * are absent on the success path.
+ * WITHOUT writing the pin file. When the scan DID find specifiers but
+ * every one was dropped because no local version resolved (the package
+ * is not installed under `node_modules`), returns
+ * `{ pins: [], pruned: [], downloaded: 0, droppedUnresolvable: [...] }`
+ * (also WITHOUT a pin file), so the caller can name the found-but-
+ * uninstalled specifiers instead of claiming there were none. A
+ * partial pin (some resolved, some dropped) still writes the file and
+ * carries `droppedUnresolvable` alongside `pins`. Callers that need to
+ * surface a non-zero exit code key off `failed`, `noBareImports`, or an
+ * all-dropped `droppedUnresolvable`; all are absent on a clean success.
  *
  * The `from` option mirrors importmap-rails's `bin/importmap pin foo
  * --from jsdelivr`. Default `jspm` resolves to jspm.io; other values
@@ -1196,6 +1203,7 @@ async function pruneOrphans(appDir, expected) {
  *   provider?: string,
  *   failed?: boolean,
  *   noBareImports?: boolean,
+ *   droppedUnresolvable?: string[],
  *   attemptedInstalls?: string[],
  * }>}
  */
@@ -1224,12 +1232,23 @@ export async function pinAll(appDir, opts = {}) {
    * @type {Map<string, { pkg: string, version: string, subpath: string }>}
    */
   const partsByInstall = new Map();
+  /**
+   * Bare specifiers the scan FOUND but that were dropped because no local
+   * version could be resolved (the package is not installed under the app's
+   * `node_modules`). Kept distinct from "scan found nothing" so the CLI can
+   * name them and point at the remedy instead of claiming there were none.
+   * @type {string[]}
+   */
+  const droppedUnresolvable = [];
   for (const spec of bare) {
     if (BUILTIN.has(spec)) continue;
     const pkg = extractPackageName(spec);
     if (!pkg || BUILTIN.has(pkg) || FRAMEWORK_SERVER_ONLY.has(pkg)) continue;
     const version = getPackageVersion(pkg, appDir);
-    if (!version) continue;
+    if (!version) {
+      droppedUnresolvable.push(spec);
+      continue;
+    }
     const subpath = spec.slice(pkg.length);
     const install = `${pkg}@${version}${subpath}`;
     installs.push(install);
@@ -1350,12 +1369,22 @@ export async function pinAll(appDir, opts = {}) {
   // -imports filter, so the file exists but does nothing. The CLI
   // surfaces this as a clearer "no bare imports found" message.
   if (installs.length === 0) {
+    // Distinguish the two empty-set causes the CLI must report differently:
+    // the scan genuinely found nothing (noBareImports) vs it found specifiers
+    // that were all dropped for a missing local version (droppedUnresolvable).
+    if (droppedUnresolvable.length > 0) {
+      return { pins, pruned: [], downloaded, droppedUnresolvable, provider: from };
+    }
     return { pins, pruned: [], downloaded, noBareImports: true, provider: from };
   }
 
   await writePinFile(appDir, importmap, integrity, from);
   const pruned = await pruneOrphans(appDir, expected);
-  return { pins, pruned, downloaded, provider: from };
+  // Some specifiers may have pinned while others were dropped for a missing
+  // version; surface the dropped ones so a partial pin is not silent.
+  return droppedUnresolvable.length > 0
+    ? { pins, pruned, downloaded, provider: from, droppedUnresolvable }
+    : { pins, pruned, downloaded, provider: from };
 }
 
 /**