@webjsdev/server 0.8.17 → 0.8.18

package/package.json

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

package/src/asset-hash.js

@@ -39,7 +39,9 @@
 
 import { createHash } from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { join, resolve, sep } from 'node:path';
+import { extname, join, resolve, sep } from 'node:path';
+import { redactStringsAndTemplates } from './js-scan.js';
+import { resolveImport } from './module-graph.js';
 
 /**
  * Length of the emitted hex hash. 12 hex chars (48 bits) is plenty to
@@ -264,3 +266,155 @@ export function withAssetHash(url, basePath = '') {
   const sepChar = url.includes('?') ? '&' : '?';
   return `${url}${sepChar}v=${hash}`;
 }
+
+/**
+ * Static `import` specifier with positional indices. Mirrors module-graph.js's
+ * `IMPORT_RE` (side-effect / default / namespace / named imports), but captures
+ * the quote (group 1) and specifier (group 2) so the `/d` flag yields the
+ * specifier's start/end for an in-place splice. Excludes dynamic `import(...)`
+ * (no whitespace after `import`) and `import.meta` (no quote), exactly like the
+ * graph scanner, so the rewrite set is the static-import set the modulepreload
+ * hints cover.
+ *
+ * @type {RegExp}
+ */
+const IMPORT_SPEC_RE = /\bimport\s+(?:(?:[\w*{}\s,]+)\s+from\s+)?(['"])([^'"]+)\1/dg;
+
+/** Match `export … from '…'` re-exports (mirrors module-graph's EXPORT_FROM_RE). @type {RegExp} */
+const EXPORT_SPEC_RE = /\bexport\b[^'";]+?\sfrom\s+(['"])([^'"]+)\1/dg;
+
+/** A server-file specifier: served as a stub at a bare URL, never preloaded. @type {RegExp} */
+const SERVER_FILE_RE = /\.server\.(?:js|ts|mjs|mts)$/;
+
+/** JS-ish specifier extensions that map to a `.ts`/`.mts` sibling on disk. @type {Set<string>} */
+const JS_SPEC_EXTS = new Set(['.js', '.mjs', '.jsx', '.cjs']);
+
+/**
+ * Normalize a relative import specifier's extension to the RESOLVED file's, so
+ * the URL the browser fetches equals the modulepreload href (which `ssr.js`
+ * derives from the resolved absolute path via `toUrlPath`, after `resolveImport`
+ * rewrites a `.js` specifier to its `.ts` sibling and resolves an extensionless
+ * one). Without this, an `import './x.js'` whose file is `x.ts` would be served
+ * `./x.js?v=H` (fetched as `/x.js?v=H`) while the preload is `/x.ts?v=H`: same
+ * hash, different path, so the preload is wasted and the file double-fetched.
+ *
+ * Conservative: only swaps a known JS-ish extension or appends to a genuinely
+ * extensionless basename; a directory specifier (`.` / `..` / trailing-slash)
+ * or an unrecognized extension is left untouched.
+ *
+ * @param {string} spec  the author's relative specifier (no query)
+ * @param {string} abs   the resolved absolute file path
+ * @returns {string}
+ */
+function normalizeSpecToResolved(spec, abs) {
+  const absExt = extname(abs);
+  if (!absExt) return spec;
+  const specExt = extname(spec);
+  if (specExt === absExt) return spec;
+  const base = spec.slice(spec.lastIndexOf('/') + 1);
+  if (base === '' || base === '.' || base === '..') return spec; // directory import
+  if (specExt) return JS_SPEC_EXTS.has(specExt) ? spec.slice(0, -specExt.length) + absExt : spec;
+  return spec + absExt; // extensionless
+}
+
+/**
+ * Append `?v=<content-hash>` to every SAME-ORIGIN relative / root-absolute
+ * static-import specifier in a served module's source, so the URL the browser
+ * actually fetches matches the `?v=`-versioned `modulepreload` hint and boot
+ * specifier the framework emits for that file.
+ *
+ * The bug this fixes (#369): the boot script imports the entry modules with
+ * `?v=<hash>` and the head emits `<link rel=modulepreload href=".../x.ts?v=hash">`
+ * for every transitive module, but a layout/page imports its components with a
+ * BARE relative specifier (`import '../components/x.ts'`). The browser resolves
+ * a relative specifier against the importer's URL and a `?v` query is NOT
+ * inherited across that resolution, so it fetches the UN-versioned URL: a
+ * different cache key from the preload. Result: the preload is wasted, the
+ * module is downloaded a second time, and the served copy gets the 1h fallback
+ * cache header instead of `immutable`. Rewriting the specifier in the served
+ * source to carry the same `?v=<hash>` collapses both to one cache key (one
+ * fetch, preload used, immutable cached).
+ *
+ * The appended hash is `assetHashFor(resolvedTarget)`, the exact value
+ * `withAssetHash` computes for the modulepreload href of the same file (same
+ * absolute path -> same hash, elision-fingerprint fold included), so the two
+ * URLs are byte-identical by construction.
+ *
+ * The fetched URL is made to equal the preload href even when the specifier's
+ * extension differs from the file on disk: `normalizeSpecToResolved` rewrites a
+ * `.js`/extensionless specifier to the resolved `.ts` sibling (the form the
+ * preload, derived from the resolved path, uses), then `?v` is appended.
+ *
+ * Scope, mirroring the modulepreload set so the rewrite never diverges from it:
+ *   - Only `.`-relative specifiers (`./`, `../`). The browser resolves these
+ *     against the importer's own URL, which is already base-path-prefixed, so
+ *     the rewrite is base-path-correct by construction. A `/`-root-absolute
+ *     specifier is deliberately NOT versioned: it would miss the `webjs.basePath`
+ *     prefix under a sub-path deploy (a pre-existing author-import limitation),
+ *     and apps use relative imports. A BARE specifier (`@webjsdev/core`) is
+ *     importmap-resolved and versioned at its importmap TARGET; rewriting it here
+ *     would break the importmap key.
+ *   - Only targets that resolve to a readable file UNDER `_appDir` (the servable
+ *     same-origin root). A `.server.*` target is excluded: it serves as a stub
+ *     at a bare URL and is never in the preload set, and its served bytes are
+ *     generated (not the file bytes the hash covers).
+ *   - A specifier already carrying a query is left as-is.
+ *
+ * Matching runs over a redaction mask with `blankStrings` on (NO literal body
+ * survives), so an `import`/`export … from` printed inside an `html\`\`` template
+ * OR a plain string literal is never rewritten (a plain-string body is NOT
+ * blanked by the default mask, so the stricter mask is required here to avoid
+ * splicing `?v` into the served string's value).
+ *
+ * A pure pass-through when fingerprinting is disabled (dev, or roots unset), so
+ * dev output stays byte-identical. Runs AFTER `elideImportsFromSource` in the
+ * serve path, so an elided side-effect import (already replaced by a comment)
+ * is not matched.
+ *
+ * @param {string} source       the served module source (post-elision, type-stripped if TS)
+ * @param {string} importerAbs  absolute path of the module being served
+ * @returns {string}
+ */
+export function versionModuleImports(source, importerAbs) {
+  if (!_enabled || !_appDir) return source;
+  if (typeof source !== 'string') return source;
+  // Cheap bail before any regex/redaction work for a module with no imports.
+  if (!source.includes('import') && !source.includes('export')) return source;
+
+  const masked = redactStringsAndTemplates(source, true);
+  /** @type {Array<{ start: number, end: number, text: string }>} */
+  const edits = [];
+  for (const re of [IMPORT_SPEC_RE, EXPORT_SPEC_RE]) {
+    re.lastIndex = 0;
+    for (const m of source.matchAll(re)) {
+      // The keyword must sit in code position; if blanked in the mask it lives
+      // inside a string / template / comment and is not a real import edge.
+      if (masked[/** @type {number} */ (m.index)] === ' ') continue;
+      const spec = m[2];
+      // Only `./` `../` relative specifiers (base-path-correct, the app pattern).
+      // Bare -> importmap target; `/`-absolute -> pre-existing basePath gap.
+      if (spec[0] !== '.') continue;
+      if (spec.includes('?')) continue;
+      const abs = resolveImport(spec, importerAbs, _appDir);
+      if (!abs || SERVER_FILE_RE.test(abs)) continue;
+      if (!abs.startsWith(_appDir + sep)) continue;
+      const hash = assetHashFor(abs);
+      if (!hash) continue;
+      // `/d` flag: indices[2] is [start, end] of the specifier CONTENT (no
+      // quotes). Replace it with the resolved-extension form + `?v` so the
+      // fetched URL is byte-identical to the preload href.
+      const [start, end] = /** @type {[number, number]} */ (m.indices[2]);
+      edits.push({ start, end, text: `${normalizeSpecToResolved(spec, abs)}?v=${hash}` });
+    }
+  }
+  if (edits.length === 0) return source;
+
+  edits.sort((a, b) => a.start - b.start);
+  let out = '';
+  let last = 0;
+  for (const e of edits) {
+    out += source.slice(last, e.start) + e.text;
+    last = e.end;
+  }
+  return out + source.slice(last);
+}

package/src/check.js

@@ -91,13 +91,18 @@ export const RULES = [
   {
     name: 'gitignore-vendor-not-ignored',
     description:
-      'Verifies the `.gitignore` exception for `.webjs/vendor/` is structurally correct via `git check-ignore`. The intended pattern is `.webjs/*` (NOT `.webjs/`) plus `!.webjs/vendor/` plus `!.webjs/vendor/**`. The common-looking pattern `.webjs/` excludes the directory itself, after which git cannot re-include children (gitignore semantics: a parent exclusion blocks child negations). Without this rule, an AI agent or human editor would silently break `webjs vendor pin` by simplifying the pattern; the failure is invisible until production. Rule fires when the working directory is a git repo and a `.gitignore` exists; skipped when neither is true.',
+      'Verifies the `.gitignore` exception for `.webjs/vendor/` is structurally correct via `git check-ignore`. The intended pattern is `**/.webjs/*` (NOT `.webjs/`) plus `!**/.webjs/vendor/` plus `!**/.webjs/vendor/**`. The `**/` prefix matches `.webjs/` at any depth so a nested / monorepo app does not leak its generated `.webjs/routes.d.ts`; the older root-anchored `.webjs/*` also passes this rule (the probe is run from the app root). The common-looking pattern `.webjs/` excludes the directory itself, after which git cannot re-include children (gitignore semantics: a parent exclusion blocks child negations). Without this rule, an AI agent or human editor would silently break `webjs vendor pin` by simplifying the pattern; the failure is invisible until production. Rule fires when the working directory is a git repo and a `.gitignore` exists; skipped when neither is true.',
   },
   {
     name: 'no-browser-globals-in-render',
     description:
       'Flags genuinely browser-only APIs used in a WebComponent constructor, willUpdate, or render() method. The SSR pipeline instantiates the component, runs willUpdate plus controllers\' hostUpdate, reflects properties, and calls render() to produce HTML, on a server element shim that backs the attribute methods but has no real DOM. So a browser global (document, window, localStorage, sessionStorage, navigator, location, matchMedia, screen, history) or an unshimmed HTMLElement member on `this` (attachShadow, shadowRoot, classList, querySelector, querySelectorAll, getBoundingClientRect, focus, blur, scrollIntoView) touched there throws at SSR time (the isomorphic footgun). The attribute methods (getAttribute/setAttribute/hasAttribute/removeAttribute/toggleAttribute), the event methods (addEventListener/removeEventListener/dispatchEvent), and attachInternals are shim-backed and run server-side, so they are NOT flagged. The flagged APIs belong in connectedCallback() or a lifecycle hook (firstUpdated/updated), which SSR never calls; seed first-paint defaults in the constructor (or derive them in willUpdate) only from server-known inputs (attributes, props). Conservative: only the constructor, willUpdate, and render bodies are scanned, and only direct references, so helper indirection is not flagged (the runtime SSR error covers that case).',
   },
+  {
+    name: 'no-scaffold-placeholder',
+    description:
+      'The one sentinel-based check, and the deliberate exception to the "objectively broken code" framing of the other rules: it flags scaffold example content that has not been replaced, so a delivered app contains only what the user intended and never leftover scaffold code. `webjs create` marks its example/demo files (the example homepage in app/page.ts, the example app chrome in app/layout.ts) with a one-line marker comment carrying the literal token `webjs-scaffold-placeholder`. The rule scans raw source (the marker lives in a comment, which the redacted scan view would hide) and fails for every file that still carries the token. A freshly scaffolded app fails this rule BY DESIGN until its placeholders are addressed: replace the example content, or deliberately keep it, and in either case delete the marker line. No finished app legitimately ships a literal remove-me marker, so this still qualifies as a check rather than a convention. The marker is acknowledge-and-remove, so keeping a piece is a one-line deletion rather than a forced rewrite.',
+  },
 ];
 
 /** Set of all known rule names for fast lookup. */
@@ -465,6 +470,27 @@ export async function checkConventions(appDir) {
     }
   }
 
+  // --- Rule: no-scaffold-placeholder ---
+  // `webjs create` marks its example/demo files (app/page.ts, app/layout.ts)
+  // with a one-line marker comment so a delivered app cannot silently ship
+  // leftover scaffold content. Scan RAW `content`: the marker lives in a
+  // comment, which the `scan` view redacts to whitespace. One violation per
+  // still-marked file. The token is assembled here so this source does not
+  // itself carry the contiguous literal.
+  {
+    const MARKER = 'webjs-scaffold-' + 'placeholder';
+    for (const { rel, content } of files) {
+      if (!content.includes(MARKER)) continue;
+      violations.push({
+        rule: 'no-scaffold-placeholder',
+        file: rel,
+        message:
+          'Scaffold placeholder marker still present. This file is unmodified example content from `webjs create`, and the delivered app should contain only what the user intended, not leftover scaffold code.',
+        fix: `Replace the example content (or deliberately keep it), then delete the marker comment line carrying the ${MARKER} token.`,
+      });
+    }
+  }
+
   // --- Rule: no-server-env-in-components ---
   // Catches `process.env.X` reads in component files where X is not a
   // WEBJS_PUBLIC_* var and not NODE_ENV. The SSR shim only exposes those
@@ -728,9 +754,12 @@ export async function checkConventions(appDir) {
   // --- Rule: gitignore-vendor-not-ignored ---
   // The .gitignore pattern for .webjs/vendor/ is subtle: `.webjs/`
   // alone excludes the directory entirely and git can't re-include
-  // children of an excluded parent. The correct pattern is `.webjs/*`
-  // plus `!.webjs/vendor/` plus `!.webjs/vendor/**`. AI agents
-  // and human reviewers frequently "simplify" this back to `.webjs/`,
+  // children of an excluded parent. The correct pattern is `**/.webjs/*`
+  // plus `!**/.webjs/vendor/` plus `!**/.webjs/vendor/**` (the `**/`
+  // prefix ignores `.webjs/` at any depth so a nested app does not leak
+  // its generated routes.d.ts; the older root-anchored `.webjs/*` also
+  // passes, since this probe runs from the app root). AI agents and
+  // human reviewers frequently "simplify" this back to `.webjs/`,
   // silently breaking `webjs vendor pin`.
   //
   // This rule verifies the actual gitignore behavior by spawning
@@ -778,9 +807,10 @@ export async function checkConventions(appDir) {
               `${probe} is gitignored, but \`webjs vendor pin\` writes files under .webjs/vendor/ and they MUST be committed for production deploys to use the pin (instead of calling api.jspm.io on every cold start). The most common cause: a \`.webjs/\` line in .gitignore that excludes the parent directory before the \`!.webjs/vendor/\` exception can take effect (git semantics: a parent exclusion blocks child negations). A second possible cause is a broader rule (e.g. \`*.js\` at root) that hides bundle files added by \`webjs vendor pin --download\`.`,
           fix:
             'Replace `.webjs/` in your .gitignore with this three-line pattern:\n' +
-            '  .webjs/*\n' +
-            '  !.webjs/vendor/\n' +
-            '  !.webjs/vendor/**\n' +
+            '  **/.webjs/*\n' +
+            '  !**/.webjs/vendor/\n' +
+            '  !**/.webjs/vendor/**\n' +
+            'The `**/` prefix ignores `.webjs/` at any depth (so a nested / monorepo app does not leak its generated `.webjs/routes.d.ts`) while still re-including the committed vendor pin. ' +
             'Verify with `git check-ignore -q .webjs/vendor/importmap.json` (exit 1 means correctly un-ignored).',
         });
       }

package/src/dev.js

@@ -115,7 +115,7 @@ function shouldAccessLog(pathname) {
 }
 import { setVendorEntries, setCoreInstall, publishBuildId, setBasePath, basePath } from './importmap.js';
 import { readBasePath, stripBasePath, withBasePath } from './base-path.js';
-import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor } from './asset-hash.js';
+import { setAssetRoots, clearAssetHashCache, setElisionFingerprint, withAssetHash, assetHashFor, versionModuleImports } from './asset-hash.js';
 import { urlFromRequest } from './forwarded.js';
 import { compileHeaderRules, applySecurityHeaders, webRequestIsHttps } from './headers.js';
 import {
@@ -2142,9 +2142,13 @@ async function jsModuleResponse(abs, dev, elideOpts, immutable) {
   let source;
   try { source = await readFile(abs, 'utf8'); }
   catch { return new Response('Not found', { status: 404 }); }
-  const code = elideImportsFromSource(
+  let code = elideImportsFromSource(
     source, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
   );
+  // Version same-origin relative import specifiers so the URL the browser
+  // fetches matches the `?v=`-versioned modulepreload + boot specifier (#369).
+  // A no-op in dev (fingerprinting disabled).
+  code = versionModuleImports(code, abs);
   // Buffered (string) body, so opt into the conditional-GET funnel for the
   // weak ETag + 304 (see fileResponse).
   const headers = {
@@ -2267,6 +2271,11 @@ async function tsResponse(abs, dev, elideOpts, cache, immutable, reportDevError)
       code, abs, elideOpts.moduleGraph, elideOpts.elidableComponents, resolveImport, elideOpts.appDir,
     );
   }
+  // Version same-origin relative import specifiers so the URL the browser
+  // fetches matches the `?v=`-versioned modulepreload + boot specifier (#369).
+  // A no-op in dev (fingerprinting disabled). Cached with the elision result:
+  // PROD files are static within a deploy, so the baked `?v` stays correct.
+  code = versionModuleImports(code, abs);
   // Evict oldest entry if cache is full (simple FIFO: Map preserves insertion order).
   if (cache.size >= TS_CACHE_MAX) {
     const oldest = cache.keys().next().value;

package/src/js-scan.js

@@ -67,10 +67,20 @@ const REGEX_PRECEDING_KEYWORDS = new Set([
  * nesting, so a nested `` html`...${html`...`}...` `` is delimited correctly
  * (the inner backtick is not mistaken for the outer close).
  *
+ * `blankStrings` (default false, so existing callers are byte-identical)
+ * additionally blanks PLAIN string bodies and disables the verbatim-template
+ * fast path, yielding a mask in which NO literal body survives. Callers that
+ * only check whether a keyword sits in code position (not inside any literal),
+ * e.g. the import-versioning pass, pass true so an `import '…'` written inside
+ * a plain string is correctly masked out (the default mask keeps plain-string
+ * bodies verbatim so `register('tag')` stays readable, which would otherwise
+ * leave such a string looking like a real import).
+ *
  * @param {string} src
+ * @param {boolean} [blankStrings=false]  also blank plain-string + verbatim-template bodies
  * @returns {string}
  */
-export function redactStringsAndTemplates(src) {
+export function redactStringsAndTemplates(src, blankStrings = false) {
   const n = src.length;
   let out = '';
   let i = 0;
@@ -157,7 +167,7 @@ export function redactStringsAndTemplates(src) {
       if (ch === '\n') hasNewline = true;
       k++;
     }
-    const verbatim = !forceBlank && !tagged && closed && !hasNewline && !hasInterp;
+    const verbatim = !forceBlank && !blankStrings && !tagged && closed && !hasNewline && !hasInterp;
     out += '`'; i++;
     if (verbatim) {
       while (i < n) {
@@ -197,7 +207,7 @@ export function redactStringsAndTemplates(src) {
       if (c === '/' && next === '/') { scanLineComment(); continue; }
       if (c === '/' && next === '*') { scanBlockComment(); continue; }
       if (c === '/' && isRegex()) { scanRegex(); continue; }
-      if (c === "'" || c === '"') { scanString(c, blank); continue; }
+      if (c === "'" || c === '"') { scanString(c, blank || blankStrings); continue; }
       if (c === '`') { scanTemplate(blank); continue; }
       if (c === '{') { brace++; lastSig = '{'; lastWord = ''; lastWasIncDec = false; out += blank ? ' ' : c; i++; continue; }
       if (c === '}') { brace--; lastSig = '}'; lastWord = ''; lastWasIncDec = false; out += blank ? ' ' : c; i++; continue; }