@webjsdev/server 0.8.91 → 0.10.0

package/src/elision-differential.js

@@ -1,101 +0,0 @@
-/**
- * The differential-elision primitives, shared by the framework's own guard and
- * by the app-facing one (#1308).
- *
- * Elision's defining invariant is that removing the elided JS NEVER changes
- * observable output. `packages/server/test/elision/differential-elision.test.js`
- * proves that for the blog corpus by rendering every route with elision ON and
- * OFF and diffing the bytes with the JS-loaded set masked out. `webjs elision
- * --verify` runs the identical comparison over an arbitrary app's own route
- * table, so every app gets the framework's own guard rather than inheriting a
- * guarantee it cannot verify locally.
- *
- * `maskJsSet` therefore lives HERE and not in either consumer: it is the
- * definition of "the JS-loaded set", and two copies is the one way the two
- * guards could silently disagree about what the invariant even means.
- *
- * A leaf module: `node:path` is not even needed, and nothing here reads the
- * filesystem or builds a graph.
- */
-
-/**
- * Mask the JS-loaded set so the diff sees only observable output. The
- * importmap, the boot module script, and the modulepreload hints are
- * REMOVED (not placeheld) because their COUNT differs on vs off, and the
- * build-id hash is derived from them; collapsing whitespace afterwards
- * means the differing-length preload block in the head leaves no trace. The
- * two responses come from the identical SSR template pipeline, so any
- * legitimate text/whitespace is the same on both sides regardless.
- *
- * Because the whole JS-loaded set is masked BY CONSTRUCTION, only the
- * DANGEROUS direction (elision changed what the SSR emits) can fail a diff
- * built on this. The SAFE direction (over-ship) lives entirely inside the
- * masked region and is invisible here, by design.
- *
- * @param {string} html
- * @returns {string}
- */
-export function maskJsSet(html) {
-  return html
-    .replace(/<script type="importmap"[\s\S]*?<\/script>/g, '')
-    .replace(/<script type="module"[\s\S]*?<\/script>/g, '')
-    .replace(/<link rel="modulepreload"[^>]*>/g, '')
-    // The auto vendor preconnect / dns-prefetch (#243) is a connection-warming
-    // HINT derived from the served vendor map, which legitimately differs on vs
-    // off (a vendor reachable only through an elided component is pruned on the
-    // ON side, so its preconnect drops too, exactly like its modulepreload). It
-    // is part of the same JS-loaded set, so mask it. The blog corpus declares
-    // no `metadata.preconnect` of its own, so every preconnect/dns-prefetch
-    // there is the auto vendor one.
-    .replace(/<link rel="preconnect"[^>]*>/g, '')
-    .replace(/<link rel="dns-prefetch"[^>]*>/g, '')
-    .replace(/ data-webjs-build="[^"]*"/g, '')
-    .replace(/ data-webjs-src="[^"]*"/g, '')
-    // Render-clock nondeterminism: a page that SSRs a live wall-clock time
-    // ("posts loaded · 3:10:10 AM") ticks between the on and off captures. This
-    // is unrelated to elision (elision never changes rendered text), so
-    // normalise it. The counterfactual in differential-elision.test.js still
-    // fails because a removed element is a structural change, not a clock tick.
-    .replace(/\b\d{1,2}:\d{2}:\d{2}\s?[AP]M\b/gi, 'TIME')
-    .replace(/\s+/g, ' ')
-    .trim();
-}
-
-/**
- * The URL paths of every STATIC page route in a route table, sorted and
- * deduped. The corpus `webjs elision --verify` renders on both sides.
- *
- * A DYNAMIC route is excluded rather than guessed at: rendering it would mean
- * inventing param values, and a route that 404s or throws on invented params
- * proves nothing. The command reports the excluded routes by name and takes
- * `--routes` for an author who wants to cover them with real values.
- *
- * Normalization is `routePathFromDir`'s, restated here so this leaf does not
- * depend on `@webjsdev/mcp`: a route group `(group)` and a `_private` segment
- * drop out of the URL, and the root `.` is `/`.
- *
- * @param {{ pages?: Array<{ routeDir?: string, paramNames?: string[] }> }} table  a `buildRouteTable(appDir)` result
- * @returns {string[]}
- */
-export function staticPageRoutes(table) {
-  const out = new Set();
-  for (const r of table?.pages || []) {
-    if (r.paramNames && r.paramNames.length) continue;
-    out.add(routePath(r.routeDir));
-  }
-  return [...out].sort();
-}
-
-/**
- * `blog` -> `/blog`, the root `.` -> `/`. Route groups and `_private` segments
- * drop, the same normalization `buildRouteTable` uses for matching.
- * @param {string|undefined} routeDir
- * @returns {string}
- */
-function routePath(routeDir) {
-  if (!routeDir || routeDir === '.') return '/';
-  const segs = routeDir
-    .split('/')
-    .filter((s) => !(s.startsWith('(') && s.endsWith(')')) && !s.startsWith('_'));
-  return segs.length ? '/' + segs.join('/') : '/';
-}

package/src/elision-report.js

@@ -1,193 +0,0 @@
-/**
- * App-level elision report (#646, extended in #1308).
- *
- * A reporting layer over the `analyzeElision` verdict, NOT a second analysis
- * and NOT a build (WebJs is no-build; elision is the server's analysis pass,
- * run at dev-server start and re-derived after each fs.watch rebuild). It
- * builds the module graph, runs `analyzeElision` ONCE, and projects the whole
- * verdict into a sorted, app-relative, JSON-serializable object.
- *
- * It carries BOTH directions:
- *
- *   - `components`: every component module with `elided` or `shipped`, and for
- *     a shipped one the evidence that forced it plus the module that did the
- *     forcing. This is the direction where a wrong verdict silently loses
- *     interactivity in production, and before #1308 an app had no way to ask
- *     "what did you drop from my page?".
- *   - `routeModules`: every page / layout as `inert` / `import-only` /
- *     `shipped`, a module that ships whole naming the first client-effecting
- *     blocker that pins it (a non-component on a component-free path from the
- *     module, #963, or its own signal when the module itself is the cause).
- *   - `orphans`: a `class X extends WebComponent` with no literal-tag
- *     registration, either because there is no registration call or because
- *     the tag is computed. The scanner never sees it (invariant 3 requires a
- *     literal tag), so it always loses its elision verdict, its tag-to-module
- *     registry entry, and its preload hint, and `static interactive = true`
- *     cannot rescue it. Whether the ELEMENT still upgrades differs by shape:
- *     with no registration call it never does, and with a computed tag only
- *     while its importing module ships WHOLE, which is the exception rather
- *     than the rule. It is the one shape the verdict cannot speak for.
- *
- * Consumed by `webjs elision` (the CLI report + `--json`), the MCP
- * `list_elision` tool, and `webjs doctor`'s two elision checks, which share
- * ONE call so the module graph is built once per doctor run. Advisory only: a
- * page legitimately MAY ship, and the analyser is biased toward shipping by
- * design (server AGENTS invariant 7), so this never fails anything.
- *
- * Nothing is cached here. Every out-of-process consumer runs the analysis once
- * and exits, so a cache would never hit and would only add a staleness bug.
- */
-import { readFile, stat } from 'node:fs/promises';
-import { join, relative, sep } from 'node:path';
-
-import { buildModuleGraph } from './module-graph.js';
-import { scanComponents, findOrphanComponents } from './component-scanner.js';
-import { buildRouteTable } from './router.js';
-import { analyzeElision } from './component-elision.js';
-
-/**
- * @typedef {'own'|'observed'|'closure'|'render'|'import'|'unreadable'} ElisionEvidence
- * @typedef {{ file: string, tags: string[], verdict: 'elided'|'shipped', evidence: ElisionEvidence|null, reason: string|null, by: string|null }} ElisionComponentRow
- * @typedef {{ file: string, verdict: 'inert'|'import-only'|'shipped', emits: string[], blocker: string|null, reason: string|null }} ElisionRouteModuleRow
- * @typedef {{ file: string, className: string }} ElisionOrphanRow
- * @typedef {{ components: number, elided: number, shipped: number, routeModules: number, inert: number, importOnly: number, shippedWhole: number, orphans: number }} ElisionSummary
- * @typedef {{ analysed: boolean, skipped: 'no-app'|'elide-off'|'unanalysable'|null, components: ElisionComponentRow[], routeModules: ElisionRouteModuleRow[], orphans: ElisionOrphanRow[], summary: ElisionSummary }} ElisionReport
- */
-
-/**
- * @param {string} appDir
- * @returns {Promise<ElisionReport>}
- */
-export async function analyzeAppElision(appDir) {
-  // No `app/` means this is not a routable app (a bare component library, a
-  // lib-only fixture); nothing ships, so there is nothing to report on.
-  if (!(await pathExists(join(appDir, 'app')))) return empty('no-app');
-  // Elision off (opt-out) ships everything by design, so the verdict is moot.
-  if (!(await readElideEnabled(appDir))) return empty('elide-off');
-
-  let moduleGraph, components, routeTable, orphans;
-  try {
-    moduleGraph = await buildModuleGraph(appDir);
-    components = await scanComponents(appDir);
-    routeTable = await buildRouteTable(appDir);
-    // Not a second elision analysis: a lexical scan for the one shape elision
-    // never gets to judge, reusing what the dev server already runs.
-    orphans = await findOrphanComponents(appDir);
-  } catch {
-    // A malformed app the analysis cannot process degrades to no report (the
-    // dev server and `webjs check` surface the real problem).
-    return empty('unanalysable');
-  }
-
-  // Exactly the page + layout set the dev server feeds to analyzeElision, so
-  // the verdict matches (error / loading / not-found modules always ship and
-  // are never elision candidates, so they are not in scope here).
-  const routeModuleSet = new Set();
-  for (const page of routeTable.pages || []) {
-    if (page.file) routeModuleSet.add(page.file);
-    for (const f of page.layouts || []) routeModuleSet.add(f);
-  }
-
-  const { inertRouteModules, importOnlyRouteModules, shippedRouteModules, componentVerdicts } =
-    await analyzeElision(components, [...routeModuleSet], moduleGraph, (f) => readFile(f, 'utf8'), appDir);
-
-  const rel = (f) => (f == null ? null : relative(appDir, f) || f);
-  const byFile = (a, b) => a.file.localeCompare(b.file);
-
-  /** @type {ElisionComponentRow[]} */
-  const componentRows = [...componentVerdicts.entries()].map(([file, v]) => ({
-    file: /** @type {string} */ (rel(file)),
-    tags: v.tags,
-    verdict: v.shipped ? 'shipped' : 'elided',
-    evidence: v.shipped ? /** @type {ElisionEvidence|null} */ (v.evidence) : null,
-    reason: v.shipped ? relativizeReason(v.reason, appDir) : null,
-    by: v.shipped ? rel(v.by) : null,
-  })).sort(byFile);
-
-  /** @type {ElisionRouteModuleRow[]} */
-  const routeRows = [
-    ...[...inertRouteModules].map((f) => ({
-      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('inert'), emits: [], blocker: null, reason: null,
-    })),
-    ...[...importOnlyRouteModules].map(([f, emits]) => ({
-      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('import-only'),
-      emits: emits.map((e) => /** @type {string} */ (rel(e))).sort(), blocker: null, reason: null,
-    })),
-    ...[...shippedRouteModules].map(([f, v]) => ({
-      file: /** @type {string} */ (rel(f)), verdict: /** @type {const} */ ('shipped'), emits: [],
-      blocker: rel(v.blocker), reason: relativizeReason(v.reason, appDir),
-    })),
-  ].sort(byFile);
-
-  /** @type {ElisionOrphanRow[]} */
-  const orphanRows = orphans
-    .map((o) => ({ file: /** @type {string} */ (rel(o.file)), className: o.className }))
-    .sort((a, b) => byFile(a, b) || a.className.localeCompare(b.className));
-
-  return {
-    analysed: true, skipped: null,
-    components: componentRows, routeModules: routeRows, orphans: orphanRows,
-    summary: {
-      components: componentRows.length,
-      elided: componentRows.filter((c) => c.verdict === 'elided').length,
-      shipped: componentRows.filter((c) => c.verdict === 'shipped').length,
-      routeModules: routeRows.length,
-      inert: inertRouteModules.size,
-      importOnly: importOnlyRouteModules.size,
-      shippedWhole: shippedRouteModules.size,
-      orphans: orphanRows.length,
-    },
-  };
-}
-
-/**
- * The no-verdict report, naming WHY nothing was analysed so a machine consumer
- * can tell "elision is switched off" from "this is not an app".
- * @param {'no-app'|'elide-off'|'unanalysable'} skipped
- * @returns {ElisionReport}
- */
-function empty(skipped) {
-  return {
-    analysed: false, skipped,
-    components: [], routeModules: [], orphans: [],
-    summary: { components: 0, elided: 0, shipped: 0, routeModules: 0, inert: 0, importOnly: 0, shippedWhole: 0, orphans: 0 },
-  };
-}
-
-/**
- * `analyzeElision` bakes ABSOLUTE paths into its reason phrases (it works in
- * absolute paths throughout). No absolute filesystem path may reach the JSON
- * contract, so strip the app dir prefix wherever it appears in the sentence.
- * A plain split/join rather than a regex, so an appDir containing regex
- * metacharacters (a `(group)` directory, a `+`) is safe.
- *
- * @param {string|null} reason
- * @param {string} appDir
- * @returns {string|null}
- */
-function relativizeReason(reason, appDir) {
-  if (reason == null) return null;
-  return reason.split(appDir.endsWith(sep) ? appDir : appDir + sep).join('');
-}
-
-/** Mirror of the dev server's elide flag: WEBJS_ELIDE override, then webjs.elide. */
-async function readElideEnabled(appDir) {
-  const raw = process.env.WEBJS_ELIDE;
-  if (raw != null) {
-    const v = raw.trim().toLowerCase();
-    if (v === '0' || v === 'false' || v === 'off' || v === 'no') return false;
-    if (v === '1' || v === 'true' || v === 'on' || v === 'yes') return true;
-  }
-  try {
-    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
-    if (pkg && pkg.webjs && pkg.webjs.elide === false) return false;
-  } catch {
-    // No package.json, malformed JSON, or unreadable: keep the default (on).
-  }
-  return true;
-}
-
-/** @param {string} p @returns {Promise<boolean>} */
-async function pathExists(p) {
-  try { await stat(p); return true; } catch { return false; }
-}