@webjsdev/cli 0.10.55 → 0.10.57

package/lib/doctor/probes/unmarked-asset-links.js

@@ -0,0 +1,199 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { isCommentedOut } from '../util.js';
+import { collectRouteModules, readAppBasePath } from '../route-modules.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * One whole `<link …>` tag. QUOTE-AWARE (`(?:[^>"']|"[^"]*"|'[^']*')*`), the
+ * same shape `ssr.js`'s hoist scanner uses, so a `>` inside a quoted attribute
+ * value cannot terminate the tag early.
+ * @type {RegExp}
+ */
+const LINK_TAG_RE = /<link\b(?:[^>"']|"[^"]*"|'[^']*')*>/gi;
+
+/**
+ * One attribute inside a tag: a name, then optionally `=` and a double-quoted,
+ * single-quoted, or unquoted value. Matching attributes as WHOLE units is what
+ * makes the scan correct, because each quoted value is consumed in one step and
+ * can therefore never be re-scanned as if it contained an attribute of its own.
+ * @type {RegExp}
+ */
+const ATTR_RE = /([a-zA-Z_:][-\w:.]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s>]+)))?/g;
+
+/**
+ * Parse a tag's attributes into a lowercased-name map. The value is `null` for a
+ * valueless attribute and carries a `quoted` flag, since this check treats an
+ * UNQUOTED href (a template hole) as undecidable rather than as a path.
+ * @param {string} tag
+ * @returns {Map<string, { value: string | null, quoted: boolean }>}
+ */
+function parseTagAttrs(tag) {
+  /** @type {Map<string, { value: string | null, quoted: boolean }>} */
+  const attrs = new Map();
+  // Skip the tag name itself so `link` is not read as an attribute.
+  const body = tag.replace(/^<[a-zA-Z_:][-\w:.]*/, '');
+  ATTR_RE.lastIndex = 0;
+  for (const m of body.matchAll(ATTR_RE)) {
+    const name = m[1].toLowerCase();
+    if (attrs.has(name)) continue; // first wins, as in HTML parsing
+    const quoted = m[2] !== undefined || m[3] !== undefined;
+    const value = m[2] ?? m[3] ?? m[4] ?? null;
+    attrs.set(name, { value, quoted });
+  }
+  return attrs;
+}
+
+/**
+ * Whether a parsed `<link>` is an unmarked stylesheet, and if so its href.
+ *
+ * Attribute PARSING rather than a lookahead over the raw tag is load-bearing,
+ * not tidiness. A scan that merely looks ahead for `rel=…stylesheet` anywhere in
+ * the tag matches the string inside ANOTHER attribute's value, which flags the
+ * two shapes this check most needs to leave alone: the canonical async-CSS
+ * `<link rel="preload" as="style" href="/public/app.css" onload="this.rel='stylesheet'">`
+ * (where the advised `asset()` fix would actively BREAK the preload, since the
+ * versioned hint could then never match the unversioned request), and a
+ * `data-rel="stylesheet"` sitting on a `rel="icon"`. Reading real attributes
+ * makes `rel` mean the `rel` attribute and nothing else.
+ *
+ * Returns the href only when every condition holds:
+ *   - `rel` is a token list CONTAINING `stylesheet` (so `rel="preload"` with an
+ *     onload swap, and `rel="icon"`, are both out).
+ *   - `href` is QUOTED. An unquoted value is a template hole
+ *     (`href=${asset('/public/app.css')}`), undecidable from source, and is
+ *     exactly the shape the marked form uses.
+ *   - the path is under `/public/` (after the app's `webjs.basePath` is
+ *     stripped, since under a sub-path deploy the author writes the prefix
+ *     themselves and `resolveAssetUrl` strips it before its own `public/` gate).
+ *   - `resolveAssetUrl` would actually fingerprint it. It returns a path
+ *     carrying a QUERY or a `..` unchanged, so wrapping one in `asset()` is a
+ *     runtime NO-OP: the author does the work and the url they ship is
+ *     byte-identical. Advising it would be advising a change that buys nothing.
+ *     A hand-rolled `?v=` cache-buster is exactly what an author who has not
+ *     adopted `asset()` is most likely to have written, so this is the common
+ *     case, not a corner. (The warning itself would clear, since this check
+ *     reads the SOURCE shape and a wrapped href is an unquoted hole. Clearing a
+ *     warning without improving the caching is the outcome to avoid.)
+ *
+ * @param {string} tag
+ * @param {string} basePath  the app's normalized `webjs.basePath` (`''` at root)
+ * @returns {string | null}
+ */
+function unmarkedStylesheetHref(tag, basePath = '') {
+  const attrs = parseTagAttrs(tag);
+  const rel = attrs.get('rel');
+  if (!rel || !rel.value) return null;
+  if (!rel.value.toLowerCase().split(/\s+/).includes('stylesheet')) return null;
+  const href = attrs.get('href');
+  if (!href || !href.quoted || !href.value) return null;
+  const url = href.value;
+  if (url[0] !== '/' || url[1] === '/') return null;
+  // Mirror `resolveAssetUrl`'s refusals IN ITS ORDER, so every flagged href is
+  // one `asset()` can actually fingerprint. It strips the base path, cuts at
+  // `?` / `#`, DECODES, and only then tests `..` and the `public/` prefix.
+  // Testing the raw value instead disagrees at both ends: `/public/%2e%2e/x`
+  // would be flagged although wrapping it changes nothing, and
+  // `/%70ublic/app.css` would be skipped although `asset()` fingerprints it.
+  let probe = url;
+  if (basePath && probe.startsWith(basePath + '/')) probe = probe.slice(basePath.length);
+  const cuts = [probe.indexOf('?'), probe.indexOf('#')].filter((i) => i !== -1);
+  let decoded = probe.slice(0, cuts.length ? Math.min(...cuts) : probe.length);
+  try { decoded = decodeURIComponent(decoded); } catch { /* keep raw */ }
+  if (decoded.includes('..') || !decoded.startsWith('/public/')) return null;
+  // A query is refused outright (an author query may carry meaning we do not
+  // own, so `resolveAssetUrl` returns the url untouched); a `#fragment` is not,
+  // since it is split off and preserved.
+  const beforeFragment = url.indexOf('#') === -1 ? url : url.slice(0, url.indexOf('#'));
+  if (beforeFragment.includes('?')) return null;
+  return url;
+}
+
+/**
+ * ADVISORY (#1095): a route module hand-writes a `<link rel="stylesheet"
+ * href="/public/…">` without `asset()`, so the url is un-versioned and a deploy
+ * cannot bust a CDN's copy of it.
+ *
+ * The failure this names was caught in production on webjs.dev: the edge served
+ * a `public/tailwind.css` built BEFORE the deploy (`cf-cache-status: HIT`,
+ * `max-age=14400`) against post-deploy HTML, so the new page rendered with its
+ * content edge to edge and its grid collapsed, because the cached css was
+ * missing the arbitrary-value utilities that page introduced. It is invisible
+ * while a deploy only restyles existing classes and maximally visible the moment
+ * one adds a page using new utilities.
+ *
+ * Why this is an ADVISORY over the author's SOURCE rather than a rewrite of the
+ * framework's OUTPUT. The first attempt at the automatic form (#1196) matched
+ * urls in the assembled HTML, and two deep-review rounds found six major
+ * defects, five of them one bug: at that layer framework output and author data
+ * are indistinguishable, so the matcher kept editing things it did not own. That
+ * is why `asset()` (#1194) is opt-in, and it is what Rails (a
+ * `stylesheet_link_tag` helper over a digest manifest) and Remix (a hashed url
+ * from the build graph, surfaced through `links()`) both do: take the
+ * fingerprint from an authoritative source at the point the url is PRODUCED, and
+ * never rewrite a rendered document. The gap `asset()` leaves is purely
+ * ergonomic. In Rails the helper is the only idiomatic way to write the tag, so
+ * forgetting it is nearly impossible; in WebJs the `<link>` is hand-written HTML,
+ * so it is easy to omit. This check closes exactly that gap, at authoring time,
+ * where the author's meaning is unambiguous and nothing is rewritten.
+ *
+ * Scoped to `rel="stylesheet"` on purpose. An icon is a legitimate deliberate
+ * NON-mark (the website leaves its favicons bare so the SEO repo-health tests
+ * can parse the hrefs literally), and a `rel="preload"` must NOT be marked at
+ * all, since its versioned hint could never match the unversioned request a CSS
+ * `url()` actually makes. Flagging either would nag about a correct choice.
+ *
+ * WARN only: an un-versioned stylesheet still SERVES correctly, it just caches
+ * badly, and an app fronted by no CDN may not care.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkUnmarkedAssetLinks(appDir) {
+  const name = 'Asset urls (unmarked stylesheet links)';
+  const routeDir = join(appDir, 'app');
+  if (!existsSync(routeDir)) {
+    return { name, status: 'pass', message: 'no app/ directory to analyse' };
+  }
+  const basePath = await readAppBasePath(appDir);
+  const findings = [];
+  for (const file of collectRouteModules(routeDir)) {
+    let src;
+    try { src = await readFile(file, 'utf8'); } catch { continue; }
+    // Cheap bail before any tag scanning. Case-INSENSITIVE to match the tag
+    // regex: a file whose only link tag is written `<LINK …>` must still be
+    // scanned, or the scanner's own case-insensitivity is unreachable exactly
+    // where it is needed.
+    if (!/<link/i.test(src)) continue;
+    LINK_TAG_RE.lastIndex = 0;
+    for (const m of src.matchAll(LINK_TAG_RE)) {
+      const href = unmarkedStylesheetHref(m[0], basePath);
+      if (!href) continue;
+      // A commented-out tag emits nothing, so advising on it is advice about
+      // dead markup.
+      if (isCommentedOut(src, /** @type {number} */ (m.index))) continue;
+      // 1-indexed line of the match, for a jump-to reference.
+      const line = src.slice(0, m.index).split('\n').length;
+      findings.push({ file, line, href });
+    }
+  }
+  if (findings.length === 0) {
+    return { name, status: 'pass', message: 'every route-module stylesheet link is content-hashed (or has none)' };
+  }
+  const rel = (f) => relative(appDir, f) || f;
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${findings.length} stylesheet link(s) are served at an un-versioned url, so a deploy cannot bust a cached copy:\n` +
+      findings.map((f) => `    ${rel(f.file)}:${f.line} href="${f.href}"`).join('\n'),
+    fix:
+      "Wrap the path in asset(): `import { asset } from '@webjsdev/core'` then "
+      + '`<link rel="stylesheet" href=${asset(\'/public/app.css\')}>`. It appends a content hash in prod '
+      + '(the framework then serves that url immutable for a year) and is a no-op in dev and in the browser. '
+      + 'Call it inside the render function, not at module scope.',
+  };
+}

package/lib/doctor/probes/vendor-gitignore.js

@@ -0,0 +1,84 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK: the `.gitignore` does not swallow the committed vendor pin. The pattern
+ * for `.webjs/vendor/` is subtle: a bare `.webjs/` line excludes the directory
+ * entirely and git cannot re-include children of an excluded parent, so a
+ * `!.webjs/vendor/` exception silently does nothing and `webjs vendor pin`
+ * output never gets committed. The correct pattern is the depth-robust
+ * contents-glob form (see the fix text below / VENDOR_GITIGNORE_LINES in
+ * vendor.js): a globstar-prefixed `.webjs/*` plus the matching vendor
+ * negations, which ignores transient `.webjs` output at any depth while
+ * keeping the committed vendor pin tracked.
+ *
+ * This was a `webjs check` rule, but inspecting `.gitignore` is a project-config
+ * concern (like `tsconfig-erasable`), not source-code correctness, and vendoring
+ * is optional, so a doctor WARN fits the domain and severity better than a CI
+ * hard-fail (#461). It lives next to `vendor-pin` (same family).
+ *
+ * PASS/skip when the dir is not a git repo or has no `.gitignore` (the user has
+ * not opted into version control yet). Probes two representative paths via
+ * `git check-ignore` with the inherited GIT_* env stripped so `cwd` is the sole
+ * authority on which repo + .gitignore stack is consulted (a pre-commit hook
+ * from a linked worktree exports GIT_WORK_TREE, which would otherwise override
+ * cwd-based discovery).
+ *
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkVendorGitignore(appDir) {
+  const hasGit = existsSync(join(appDir, '.git'));
+  const hasGitignore = existsSync(join(appDir, '.gitignore'));
+  if (!hasGit || !hasGitignore) {
+    return {
+      name: 'vendor-gitignore',
+      status: 'pass',
+      message: 'Not a git checkout with a .gitignore; nothing to verify.',
+    };
+  }
+  const { spawnSync } = await import('node:child_process');
+  const {
+    GIT_DIR: _gd, GIT_WORK_TREE: _gwt, GIT_INDEX_FILE: _gif, GIT_PREFIX: _gp,
+    ...gitEnv
+  } = process.env;
+  // Check two representative paths: the pin manifest AND a sample downloaded
+  // bundle. A `.gitignore` that allows the manifest but blocks bundles (e.g.
+  // `*.js` higher up) would still break `webjs vendor pin --download`.
+  // `git check-ignore -q` exits 0 when the path is ignored, 1 when not.
+  const probes = [
+    '.webjs/vendor/importmap.json',
+    '.webjs/vendor/sample-pkg@1.0.0.js',
+  ];
+  for (const probe of probes) {
+    const result = spawnSync('git', ['check-ignore', '-q', probe], {
+      cwd: appDir,
+      stdio: 'pipe',
+      env: gitEnv,
+    });
+    if (result.status === 0) {
+      return {
+        name: 'vendor-gitignore',
+        status: 'warn',
+        message:
+          `${probe} is gitignored, but \`webjs vendor pin\` writes files under .webjs/vendor/ that MUST be committed for a production deploy to use the pin (instead of calling api.jspm.io on every cold start). The most common cause: a \`.webjs/\` line that excludes the parent directory before the \`!.webjs/vendor/\` exception can take effect (git semantics: a parent exclusion blocks child negations). A second cause is a broader rule (e.g. \`*.js\` at root) hiding 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' +
+          '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).',
+      };
+    }
+  }
+  return {
+    name: 'vendor-gitignore',
+    status: 'pass',
+    message: 'The .gitignore keeps .webjs/vendor/ committable.',
+  };
+}

package/lib/doctor/probes/vendor-pin.js

@@ -0,0 +1,77 @@
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 4, vendor pin freshness. Applies ONLY when a pin file exists. PASS/skip
+ * for an unpinned app (it resolves live, which is fine in dev). BEST-EFFORT +
+ * NETWORK-TOLERANT: any error (network, timeout) is a WARN "could not check",
+ * never a hard fail and never a throw. PASS when all pins current, WARN listing
+ * outdated packages otherwise.
+ *
+ * The vendor functions are injected via `opts.vendor` so a test can supply a
+ * stub without a real network call; absent the override, they are dynamically
+ * imported from `@webjsdev/server`.
+ * @param {string} appDir
+ * @param {{ vendor?: { hasVendorPin: (d: string) => boolean, findOutdated: (d: string) => Promise<Array<{ pkg: string, current: string, latest: string }>> } }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkVendorPin(appDir, opts) {
+  let vendor = opts.vendor;
+  if (!vendor) {
+    try {
+      const mod = await import('@webjsdev/server');
+      vendor = { hasVendorPin: mod.hasVendorPin, findOutdated: mod.findOutdated };
+    } catch {
+      return {
+        name: 'vendor-pin',
+        status: 'warn',
+        // "Could not check", not a finding: never escalatable by a gate.
+        bestEffort: true,
+        message: 'Could not load the vendor toolchain to check pin freshness.',
+        fix: 'Run `npm install` so @webjsdev/server is available, then re-run `webjs doctor`.',
+      };
+    }
+  }
+  let pinned = false;
+  try {
+    pinned = vendor.hasVendorPin(appDir);
+  } catch {
+    pinned = false;
+  }
+  if (!pinned) {
+    return {
+      name: 'vendor-pin',
+      status: 'pass',
+      message: 'No vendor pin file; the app resolves vendor imports live (fine in dev).',
+    };
+  }
+  let outdated;
+  try {
+    outdated = await vendor.findOutdated(appDir);
+  } catch {
+    // findOutdated is built to swallow fetch errors and return [], but guard
+    // anyway: a network check must NEVER throw out of doctor.
+    return {
+      name: 'vendor-pin',
+      status: 'warn',
+      bestEffort: true,
+      message: 'Could not check pin freshness (network unreachable or registry error).',
+      fix: 'Re-run `webjs doctor` when connectivity is back, or run `webjs vendor outdated`.',
+    };
+  }
+  if (!Array.isArray(outdated) || outdated.length === 0) {
+    return {
+      name: 'vendor-pin',
+      status: 'pass',
+      message: 'All vendor pins are current.',
+    };
+  }
+  const list = outdated.map((o) => `${o.pkg} (${o.current} -> ${o.latest})`).join(', ');
+  return {
+    name: 'vendor-pin',
+    status: 'warn',
+    message: `${outdated.length} pinned package(s) are outdated: ${list}.`,
+    fix: 'Run `webjs vendor update` to re-pin to the latest versions.',
+  };
+}

package/lib/doctor/probes/webjs-versions.js

@@ -0,0 +1,85 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { satisfiesRange, readInstalledVersion } from '../manifest.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 5, @webjsdev/* version coherence. WARN-level only (a version drift is
+ * not a crash). Reads the app package.json `@webjsdev/*` ranges across
+ * dependencies + devDependencies, then for each resolves the INSTALLED version
+ * through Node's own resolver anchored at the app dir (see
+ * `readInstalledVersion`, which is why a workspace-hoisted install resolves)
+ * and checks it satisfies the declared range. PASS when every @webjsdev dep is
+ * present + satisfied; WARN on a missing install or a range drift.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkWebjsVersions(appDir) {
+  const pkgPath = join(appDir, 'package.json');
+  if (!existsSync(pkgPath)) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'No package.json found in this directory.',
+      fix: 'Run `webjs doctor` from the app root (where package.json lives).',
+    };
+  }
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
+  } catch {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'package.json could not be parsed.',
+      fix: 'Fix the package.json syntax.',
+    };
+  }
+  const ranges = { ...(pkg.dependencies || {}), ...(pkg.devDependencies || {}) };
+  const webjsDeps = Object.keys(ranges).filter((n) => n.startsWith('@webjsdev/'));
+  if (webjsDeps.length === 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: 'No @webjsdev/* dependencies declared in package.json.',
+      fix: 'A webjs app depends on @webjsdev/core + @webjsdev/server (+ @webjsdev/cli).',
+    };
+  }
+  const missing = [];
+  const drift = [];
+  for (const dep of webjsDeps) {
+    const installedVersion = await readInstalledVersion(dep, appDir);
+    if (!installedVersion) {
+      missing.push(dep);
+      continue;
+    }
+    const ok = satisfiesRange(installedVersion, ranges[dep]);
+    // null = a range shape we cannot statically verify; do not warn on it.
+    if (ok === false) drift.push(`${dep}@${installedVersion} does not satisfy "${ranges[dep]}"`);
+  }
+  if (missing.length > 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: `${missing.length} @webjsdev/* dependency not installed: ${missing.join(', ')}.`,
+      fix: 'Run `npm install` to install the declared dependencies.',
+    };
+  }
+  if (drift.length > 0) {
+    return {
+      name: 'webjs-versions',
+      status: 'warn',
+      message: `@webjsdev version drift: ${drift.join('; ')}.`,
+      fix: 'Run `npm install` to reconcile node_modules with the declared ranges.',
+    };
+  }
+  return {
+    name: 'webjs-versions',
+    status: 'pass',
+    message: `All ${webjsDeps.length} @webjsdev/* dependency satisfy their declared ranges.`,
+  };
+}

package/lib/doctor/route-modules.js

@@ -0,0 +1,100 @@
+import { readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+// Directories the route-module walk never descends into (deps, VCS, framework
+// and build caches). Mirrors FRESHNESS_IGNORE; kept separate so either walk can
+// change its exclusions without silently moving the other.
+export const ROUTE_WALK_IGNORE = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
+
+/**
+ * A route module that renders markup on the server, which is where `asset()`
+ * belongs. Page and layout are the common case, but the BOUNDARY modules matter
+ * too and are easy to miss: `error` / `not-found` / `forbidden` / `unauthorized`
+ * / `loading` are always shipped and never elided, and `global-error` renders
+ * its OWN `<!doctype><html><head>` and is returned verbatim with no framework
+ * head splice, which makes it the likeliest place outside the root layout for
+ * an author to hand-write a stylesheet link.
+ * @type {RegExp}
+ */
+export const ROUTE_MODULE_RE =
+  /^(?:page|layout|error|not-found|forbidden|unauthorized|loading)\.(?:js|ts|mjs|mts)$/;
+
+/**
+ * The two boundary stems `router.js` registers ONLY at the app root (both are
+ * guarded by `dir === '.'` there). A nested `app/admin/global-error.ts` is never
+ * in the route table and never renders, so scanning one would advise on dead
+ * code, the same defect the `_private` skip exists to avoid.
+ * @type {RegExp}
+ */
+export const ROOT_ONLY_MODULE_RE = /^(?:global-error|global-not-found)\.(?:js|ts|mjs|mts)$/;
+
+/**
+ * The app's `webjs.basePath`, normalized to `''` (root mount) or `/segment…`.
+ *
+ * A faithful port of `normalizeBasePath` (`packages/server/src/base-path.js`),
+ * which is the source of truth: it trims, PREPENDS the leading slash (so the
+ * documented `"myapp"`, `"/myapp"` and `"/myapp/"` all normalize alike), and
+ * fails safe to `''` on a value that is not a plain same-origin prefix. Reading
+ * only `startsWith('/')` would leave this check inert for an app configured
+ * `"myapp"`, which is exactly the silently-inert case it exists to close.
+ *
+ * Ported rather than imported because that helper is not on `@webjsdev/server`'s
+ * public surface, and because doctor must stay usable when the framework does
+ * not resolve from the app dir at all (the #954 fresh-worktree case this same
+ * command exists to diagnose). The port is intentional and stays. What makes it
+ * safe is that the drift is tested rather than trusted.
+ *
+ * `test/cli/base-path-parity.test.mjs` feeds one input table through BOTH this
+ * function and the server's `readBasePath`, asserting they agree with each other
+ * and with the expected value. Change either side without the other and it reds.
+ * So edit this body only alongside `packages/server/src/base-path.js`, and run
+ * that test. (`test/cli/doctor.test.mjs` covers the check that consumes this,
+ * not the normalization forms themselves.)
+ * @param {string} appDir
+ * @returns {Promise<string>}
+ */
+export async function readAppBasePath(appDir) {
+  let raw;
+  try {
+    const pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+    raw = pkg?.webjs?.basePath;
+  } catch {
+    return '';
+  }
+  if (typeof raw !== 'string') return '';
+  let v = raw.trim();
+  if (v === '' || v === '/') return '';
+  // Not a plain same-origin path prefix: fail safe to no base path.
+  if (v.includes('..') || v.includes('://') || v.includes('\\') || /\s/.test(v)) return '';
+  // A network-path reference (`//host`) is rejected BEFORE leading slashes are
+  // collapsed, since collapsing would turn an origin escape into `/host`.
+  if (v.startsWith('//')) return '';
+  v = ('/' + v.replace(/^\/+/, '')).replace(/\/+$/, '');
+  return v === '' || v === '/' ? '' : v;
+}
+
+/**
+ * Collect every `app/**` route module that renders markup, depth-first.
+ * Best-effort: an unreadable directory contributes nothing rather than throwing.
+ * @param {string} dir
+ * @param {string[]} [out]
+ * @returns {string[]}
+ */
+export function collectRouteModules(dir, root = dir, out = []) {
+  let entries;
+  try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return out; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || ROUTE_WALK_IGNORE.has(e.name)) continue;
+    if (e.isSymbolicLink()) continue; // never follow: can cycle or escape into deps
+    // `_`-prefixed folders are PRIVATE: `router.js` drops any route whose
+    // directory has such a segment, so markup under one is never routed and
+    // never rendered. Advising on it would be advice about dead code.
+    if (e.isDirectory() && e.name.startsWith('_')) continue;
+    const abs = join(dir, e.name);
+    if (e.isDirectory()) collectRouteModules(abs, root, out);
+    else if (ROUTE_MODULE_RE.test(e.name)) out.push(abs);
+    else if (dir === root && ROOT_ONLY_MODULE_RE.test(e.name)) out.push(abs);
+  }
+  return out;
+}

package/lib/doctor/runner.js

@@ -0,0 +1,72 @@
+import { codeForName } from './codes.js';
+import { checkNode } from './probes/node.js';
+import { checkTsconfig } from './probes/tsconfig.js';
+import { checkEnv } from './probes/env.js';
+import { checkVendorPin } from './probes/vendor-pin.js';
+import { checkVendorGitignore } from './probes/vendor-gitignore.js';
+import { checkImportmapCoherence } from './probes/importmap-coherence.js';
+import { checkWebjsVersions } from './probes/webjs-versions.js';
+import { checkGitHook } from './probes/git-hook.js';
+import { checkElisionCarriers, checkElisionComponents } from './probes/elision.js';
+import { checkStaticAssetFreshness } from './probes/static-asset-freshness.js';
+import { checkUnmarkedAssetLinks } from './probes/unmarked-asset-links.js';
+import { checkFrameworkResolves, checkFrameworkLinks } from './probes/framework-resolves.js';
+
+/**
+ * @typedef {import('./codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * Run every doctor check against `appDir` and return the results. PURE: no
+ * printing, no `process.exit`; the CLI renders + decides the exit code.
+ *
+ * @param {string} appDir  the app directory to check (usually `process.cwd()`)
+ * @param {{
+ *   nodeVersion?: string,
+ *   cliDir?: string,
+ *   vendor?: { hasVendorPin: (d: string) => boolean, findOutdated: (d: string) => Promise<Array<{ pkg: string, current: string, latest: string }>> },
+ * }} [opts]  test-injection seams:
+ *   - `nodeVersion`: override the running Node version (asserts the fail case
+ *     without being on old Node);
+ *   - `cliDir`: directory of the CLI package whose `engines.node` sources the
+ *     required major (defaults to THIS module's package);
+ *   - `vendor`: inject the `{ hasVendorPin, findOutdated }` pair so the pin check
+ *     runs against a stub instead of a real network call.
+ *   - `coherence`: inject `{ liveImports, vendoredImports, getManifest, check }`
+ *     so the importmap-coherence check runs against stub importmaps + metadata
+ *     instead of a real live resolve / node_modules read.
+ * @returns {Promise<DoctorResult[]>}
+ */
+export async function runDoctorChecks(appDir, opts = {}) {
+  const cliDir = opts.cliDir || new URL('.', import.meta.url).pathname;
+  // ONE elision report for BOTH elision checks (#1308). Started before the
+  // batch and awaited inside each check, so the module graph is built once per
+  // doctor run and the two checks still run in parallel with everything else.
+  // Fails soft to null, exactly as the carrier check's own try/catch did.
+  const elision = (async () => {
+    try {
+      const { analyzeAppElision } = await import('@webjsdev/server');
+      return await analyzeAppElision(appDir);
+    } catch { return null; }
+  })();
+  const results = await Promise.all([
+    checkNode(cliDir, opts),
+    checkTsconfig(appDir),
+    checkEnv(appDir),
+    checkVendorPin(appDir, opts),
+    checkVendorGitignore(appDir),
+    checkWebjsVersions(appDir),
+    Promise.resolve(checkFrameworkResolves(appDir)),
+    Promise.resolve(checkFrameworkLinks(appDir)),
+    checkImportmapCoherence(appDir, opts),
+    Promise.resolve(checkGitHook(appDir)),
+    checkElisionCarriers(elision),
+    checkElisionComponents(elision),
+    checkStaticAssetFreshness(appDir),
+    checkUnmarkedAssetLinks(appDir),
+  ]);
+  // Attach the stable machine code to every result (#975). Centralized here so
+  // each check function stays free of the code-contract concern.
+  for (const r of results) r.code = codeForName(r.name);
+  return results;
+}