@webjsdev/cli 0.10.55 → 0.10.56

package/lib/doctor/probes/git-hook.js

@@ -0,0 +1,58 @@
+import { existsSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 6 (optional), git pre-commit hook installed + executable. WARN when the
+ * repo is a git checkout but `.git/hooks/pre-commit` is absent or
+ * non-executable, since the test-gate / changelog hook would not fire. PASS when
+ * present + executable, or skip (PASS) when this is not a git checkout at all
+ * (an exported tarball, a non-repo dir). Respects a configured `core.hooksPath`
+ * is OUT of scope here: the common scaffold installs into `.git/hooks`, so this
+ * checks the default location and a configured path is the user's own concern.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkGitHook(appDir) {
+  const gitDir = join(appDir, '.git');
+  if (!existsSync(gitDir)) {
+    return {
+      name: 'git-hook',
+      status: 'pass',
+      message: 'Not a git checkout; no pre-commit hook expected.',
+    };
+  }
+  const hook = join(gitDir, 'hooks', 'pre-commit');
+  if (!existsSync(hook)) {
+    return {
+      name: 'git-hook',
+      status: 'warn',
+      message: 'No .git/hooks/pre-commit hook installed.',
+      fix: 'Install the project hooks (e.g. `npm install` runs the prepare step that wires them).',
+    };
+  }
+  let executable = false;
+  try {
+    // Owner-execute bit. On a checkout without exec bits (some Windows / CI
+    // setups) the hook will not run, so flag it.
+    executable = (statSync(hook).mode & 0o100) !== 0;
+  } catch {
+    executable = false;
+  }
+  if (!executable) {
+    return {
+      name: 'git-hook',
+      status: 'warn',
+      message: '.git/hooks/pre-commit exists but is not executable.',
+      fix: 'chmod +x .git/hooks/pre-commit',
+    };
+  }
+  return {
+    name: 'git-hook',
+    status: 'pass',
+    message: '.git/hooks/pre-commit is installed and executable.',
+  };
+}

package/lib/doctor/probes/importmap-coherence.js

@@ -0,0 +1,158 @@
+import { formatConflicts, makeInstalledManifestReader } from '../manifest.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 7, importmap coherence (issue #450). Defense-in-depth that catches an
+ * INCOHERENT client dependency graph in the produced importmap, regardless of
+ * how the incoherence arose (a hand-edited pin file, a partial vendor pin, or
+ * the #446 resolution skew). For each resolved package, it checks that the
+ * version actually pinned for every OTHER resolved package it depends on
+ * satisfies the declared range; a miss warns naming both packages, the range,
+ * and the pinned version.
+ *
+ * Runs the SAME check over BOTH inputs and produces the same verdict for the
+ * same dep set (the parity invariant): the live importmap (resolved the way the
+ * server resolves it at runtime) AND the vendored `.webjs/vendor/importmap.json`.
+ * A vendored importmap is a freeze of the runtime-resolved graph, so a coherent
+ * runtime graph that gets vendored stays coherent.
+ *
+ * WARN-only and BEST-EFFORT: it never hard-fails (a runtime incoherence is the
+ * app's concern, not a broken toolchain), and it degrades to a soft
+ * "could not verify" whenever metadata or a live resolve is unavailable rather
+ * than failing closed. Dependency metadata is read from the already-installed
+ * `node_modules` manifests, no network call of its own; the only network touch
+ * is the live importmap resolve, which is wrapped so any failure degrades.
+ *
+ * The vendor functions + manifest reader are injectable via `opts.coherence`
+ * so a test can drive every branch without a network call.
+ *
+ * @param {string} appDir
+ * @param {{ coherence?: {
+ *   liveImports?: () => Promise<Record<string,string> | null>,
+ *   vendoredImports?: () => Promise<Record<string,string> | null>,
+ *   getManifest?: (pkg: string, version: string) => Promise<any>,
+ *   check?: (imports: Record<string,string>, o: { getManifest: any }) => Promise<{ conflicts: any[], unverified: any[], checked: number }>,
+ * } }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkImportmapCoherence(appDir, opts) {
+  let inj = opts.coherence;
+  // Resolve the real vendor toolchain unless a test injected stubs. Both the
+  // importmap sources and the coherence-check function come from
+  // @webjsdev/server, so a missing install degrades to a WARN, never a throw.
+  if (!inj || !inj.check || !inj.liveImports || !inj.vendoredImports || !inj.getManifest) {
+    let mod;
+    try {
+      mod = await import('@webjsdev/server');
+    } catch {
+      return {
+        name: 'importmap-coherence',
+        status: 'warn',
+        bestEffort: true,
+        message: 'Could not load the vendor toolchain to check importmap coherence.',
+        fix: 'Run `npm install` so @webjsdev/server is available, then re-run `webjs doctor`.',
+      };
+    }
+    const real = {
+      check: mod.checkImportmapCoherence,
+      // Hoist-aware manifest read from the already-installed node_modules (no
+      // network of its own), so a monorepo-hoisted dep still resolves. Falls
+      // back to the local app/node_modules read if the server build predates
+      // getPackageManifest.
+      getManifest: typeof mod.getPackageManifest === 'function'
+        ? (pkg) => mod.getPackageManifest(pkg, appDir)
+        : makeInstalledManifestReader(appDir),
+      // Live importmap: resolve vendor imports the way the server does on the
+      // first request (prefers the pin file, else a live jspm.io resolve).
+      liveImports: async () => {
+        try {
+          const resolved = await mod.resolveVendorImports(appDir, () => mod.scanBareImports(appDir));
+          return resolved && resolved.imports ? resolved.imports : {};
+        } catch {
+          return null;
+        }
+      },
+      // Vendored importmap: the committed pin file, no network.
+      vendoredImports: async () => {
+        try {
+          const pin = await mod.readPinFile(appDir);
+          return pin && pin.imports ? pin.imports : null;
+        } catch {
+          return null;
+        }
+      },
+    };
+    inj = { ...real, ...(inj || {}) };
+  }
+
+  // Gather both importmaps. Either may be absent (no pin file, or a live
+  // resolve that failed / found no vendor imports); the check runs over
+  // whichever exist, identically.
+  let live = null;
+  let vendored = null;
+  try { live = await inj.liveImports(); } catch { live = null; }
+  try { vendored = await inj.vendoredImports(); } catch { vendored = null; }
+
+  const liveHas = live && Object.keys(live).length > 0;
+  const vendoredHas = vendored && Object.keys(vendored).length > 0;
+  if (!liveHas && !vendoredHas) {
+    return {
+      name: 'importmap-coherence',
+      status: 'pass',
+      message: 'No vendor importmap to check (the app imports no npm packages on the client).',
+    };
+  }
+
+  // Run the IDENTICAL check over each available importmap. The function is
+  // pure in (imports, getManifest), so the same pinned dep set produces the
+  // same verdict whichever input it came from (the runtime-vs-vendored parity
+  // invariant). Aggregate the conflicts; dedupe identical ones so a package
+  // pinned the same way in both maps is reported once.
+  /** @type {Map<string, any>} */
+  const conflictsByKey = new Map();
+  let anyChecked = 0;
+  let anyUnverified = 0;
+  for (const imports of [liveHas ? live : null, vendoredHas ? vendored : null]) {
+    if (!imports) continue;
+    let report;
+    try {
+      report = await inj.check(imports, { getManifest: inj.getManifest });
+    } catch {
+      // A check that threw is a "could not verify", never a doctor crash.
+      anyUnverified++;
+      continue;
+    }
+    anyChecked += report.checked || 0;
+    anyUnverified += (report.unverified || []).length;
+    for (const c of report.conflicts || []) {
+      conflictsByKey.set(`${c.pkg}@${c.version}->${c.dependsOn}@${c.pinnedVersion}`, c);
+    }
+  }
+
+  const conflicts = [...conflictsByKey.values()];
+  if (conflicts.length > 0) {
+    return {
+      name: 'importmap-coherence',
+      status: 'warn',
+      message: `Incoherent client dependency graph in the importmap: ${formatConflicts(conflicts)}.`,
+      fix: 'Align the pinned versions: re-run `webjs vendor pin` to re-resolve a coherent set, or bump the lagging package in package.json and reinstall so the importmap pins a version satisfying every dependent.',
+    };
+  }
+  if (anyChecked === 0 && anyUnverified > 0) {
+    return {
+      name: 'importmap-coherence',
+      status: 'warn',
+      bestEffort: true,
+      message: 'Could not verify importmap coherence (dependency metadata for the pinned packages was unavailable).',
+      fix: 'Run `npm install` so the pinned packages are present in node_modules, then re-run `webjs doctor`.',
+    };
+  }
+  return {
+    name: 'importmap-coherence',
+    status: 'pass',
+    message: 'The importmap dependency graph is coherent (every pinned package satisfies its dependents\' declared ranges).',
+  };
+}

package/lib/doctor/probes/node.js

@@ -0,0 +1,37 @@
+import { checkNodeInline } from '../../node-preflight.js';
+import { readEngines } from '../util.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 1, Node version. HARD-FAIL when the running major is below the required
+ * major (the strip-types + recursive fs.watch floor). `opts.nodeVersion` lets a
+ * test inject the running version so the fail case is assertable without being
+ * on old Node.
+ * @param {string} cliDir
+ * @param {{ nodeVersion?: string }} opts
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkNode(cliDir, opts) {
+  const engines = await readEngines(cliDir);
+  const current = opts.nodeVersion || process.versions.node;
+  const r = checkNodeInline(current, engines);
+  if (r.ok) {
+    return {
+      name: 'node-version',
+      status: 'pass',
+      message: `Node ${r.current} satisfies the required Node ${r.requiredMajor}+.`,
+    };
+  }
+  return {
+    name: 'node-version',
+    status: 'fail',
+    message:
+      `Node ${r.current} is below the required Node ${r.requiredMajor}+. ` +
+      `webjs is buildless and relies on Node ${r.requiredMajor}'s built-in TypeScript ` +
+      `strip and recursive fs.watch.`,
+    fix: `Upgrade to Node ${r.requiredMajor}+ (see https://nodejs.org).`,
+  };
+}

package/lib/doctor/probes/static-asset-freshness.js

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { newestMtimeMs } from '../util.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * ADVISORY: a declared `webjs.dev.regenerate` output is STALE on disk (a source
+ * is newer than the committed/built output). In DEV the framework recompiles it
+ * on request (#967), so this never bites locally, but the check is the explicit
+ * dev/prod PARITY backstop: it catches a stale `public/tailwind.css` that would
+ * be served as-is by `webjs start` (prod does NOT recompile on request) or
+ * committed into the repo. WARN-level: the fix is a one-line rebuild, and a
+ * missing output (a fresh clone before the first `css:build`) is not this app's
+ * bug to hard-fail on.
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkStaticAssetFreshness(appDir) {
+  const name = 'Static build outputs (dev.regenerate freshness)';
+  let pkg;
+  try {
+    pkg = JSON.parse(await readFile(join(appDir, 'package.json'), 'utf8'));
+  } catch {
+    return { name, status: 'pass', message: 'no package.json to analyse' };
+  }
+  const rules = pkg && pkg.webjs && pkg.webjs.dev ? pkg.webjs.dev.regenerate : null;
+  if (!Array.isArray(rules) || rules.length === 0) {
+    return { name, status: 'pass', message: 'no webjs.dev.regenerate rules declared' };
+  }
+  const stale = [];
+  for (const rule of rules) {
+    if (!rule || typeof rule.output !== 'string') continue;
+    const output = rule.output.replace(/^\/+/, '');
+    const outMtime = newestMtimeMs(join(appDir, output));
+    if (outMtime === 0) continue; // missing output: not a staleness fail (built on first boot)
+    let newestSrc = 0;
+    for (const inp of Array.isArray(rule.inputs) ? rule.inputs : []) {
+      const m = newestMtimeMs(join(appDir, inp));
+      if (m > newestSrc) newestSrc = m;
+    }
+    if (newestSrc > outMtime) stale.push({ output, command: rule.command });
+  }
+  if (stale.length === 0) {
+    return { name, status: 'pass', message: 'every declared build output is up to date with its sources' };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${stale.length} static build output(s) are older than a source file:\n` +
+      stale.map((s) => `    ${s.output} (rebuild: ${s.command})`).join('\n') +
+      '\n    In dev the framework recompiles these on request, so this only bites a `webjs start` (prod) or a committed stale file.',
+    fix: 'Rebuild the output(s) with the command shown (e.g. `npm run css:build`) before deploying or committing. `webjs dev` regenerates them on request automatically.',
+  };
+}

package/lib/doctor/probes/tsconfig.js

@@ -0,0 +1,55 @@
+import { existsSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { stripJsonc } from '../util.js';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * CHECK 2, tsconfig erasableSyntaxOnly. PASS when `true`; WARN when no tsconfig
+ * (a JS-only app legitimately has none) or the file is unparseable; HARD-FAIL
+ * when the file EXISTS but the flag is missing/false (non-erasable TS 500s at
+ * strip time).
+ * @param {string} appDir
+ * @returns {Promise<DoctorResult>}
+ */
+export async function checkTsconfig(appDir) {
+  const path = join(appDir, 'tsconfig.json');
+  if (!existsSync(path)) {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'warn',
+      message: 'No tsconfig.json found. A JS-only app needs none; a TypeScript app requires one.',
+      fix: 'If this app uses TypeScript, add a tsconfig.json with "erasableSyntaxOnly": true.',
+    };
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(stripJsonc(await readFile(path, 'utf8')));
+  } catch {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'warn',
+      message: 'tsconfig.json could not be parsed (even after stripping comments + trailing commas).',
+      fix: 'Fix the tsconfig.json syntax, then ensure "compilerOptions.erasableSyntaxOnly": true.',
+    };
+  }
+  const flag = parsed?.compilerOptions?.erasableSyntaxOnly;
+  if (flag === true) {
+    return {
+      name: 'tsconfig-erasable',
+      status: 'pass',
+      message: 'tsconfig.json sets "erasableSyntaxOnly": true.',
+    };
+  }
+  return {
+    name: 'tsconfig-erasable',
+    status: 'fail',
+    message:
+      'tsconfig.json is missing "compilerOptions.erasableSyntaxOnly": true. ' +
+      'Non-erasable TypeScript (enum, namespace, parameter properties, ...) 500s at strip time.',
+    fix: 'Set "compilerOptions": { "erasableSyntaxOnly": true } in tsconfig.json.',
+  };
+}

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.',
+  };
+}