@webjsdev/cli 0.10.54 → 0.10.56

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,71 @@
+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 } 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)),
+    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;
+}

package/lib/doctor/util.js

@@ -0,0 +1,160 @@
+import { statSync, readdirSync } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * Read the CLI package's own `engines.node` so the required Node major lives in
+ * one place (mirrors how `bin/webjs.js` sources it). Falls back to `>=24.0.0`.
+ * @param {string} cliDir  directory of THIS file's package (lib/ -> package root)
+ * @returns {Promise<string>}
+ */
+export async function readEngines(cliDir) {
+  try {
+    const pkg = JSON.parse(await readFile(join(cliDir, '..', 'package.json'), 'utf8'));
+    return pkg?.engines?.node || '>=24.0.0';
+  } catch {
+    return '>=24.0.0';
+  }
+}
+
+/**
+ * Strip `//` line comments, block comments, and trailing commas from a JSONC
+ * string so a tsconfig (which permits all three) parses with `JSON.parse`.
+ * Deliberately simple: it does not honor comment-looking sequences inside
+ * string values, which is acceptable for a tsconfig (paths rarely contain `//`
+ * or block-comment markers, and the worst case is a parse failure the caller
+ * already degrades to a WARN).
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripJsonc(text) {
+  let out = '';
+  let inString = false;
+  let stringQuote = '';
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    const next = text[i + 1];
+    if (inString) {
+      out += ch;
+      if (ch === '\\') {
+        // Copy the escaped char verbatim so an escaped quote does not end the string.
+        out += text[i + 1] || '';
+        i++;
+      } else if (ch === stringQuote) {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"' || ch === "'") {
+      inString = true;
+      stringQuote = ch;
+      out += ch;
+      continue;
+    }
+    if (ch === '/' && next === '/') {
+      while (i < text.length && text[i] !== '\n') i++;
+      out += '\n';
+      continue;
+    }
+    if (ch === '/' && next === '*') {
+      i += 2;
+      while (i < text.length && !(text[i] === '*' && text[i + 1] === '/')) i++;
+      i++; // land on the '/'
+      continue;
+    }
+    out += ch;
+  }
+  // Drop trailing commas before } or ].
+  return out.replace(/,(\s*[}\]])/g, '$1');
+}
+
+/**
+ * Parse a `.env`-style file into the SET of KEY names it declares. A simple
+ * `KEY=value` line parse: comments (`#`) and blank lines are skipped, and only
+ * the key before the first `=` is taken (the value is irrelevant for drift).
+ * @param {string} text
+ * @returns {Set<string>}
+ */
+export function parseEnvKeys(text) {
+  const keys = new Set();
+  for (const raw of text.split(/\r?\n/)) {
+    const line = raw.trim();
+    if (!line || line.startsWith('#')) continue;
+    const eq = line.indexOf('=');
+    if (eq <= 0) continue;
+    let key = line.slice(0, eq).trim();
+    // Tolerate a leading `export ` (a common .env.example convention).
+    if (key.startsWith('export ')) key = key.slice('export '.length).trim();
+    if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) keys.add(key);
+  }
+  return keys;
+}
+
+// Directories never worth walking for the CSS-freshness advisory (mirrors
+// dev-regenerate's IGNORE_DIRS): build output, deps, VCS + framework caches.
+const FRESHNESS_IGNORE = new Set(['node_modules', '.git', '.webjs', 'dist', '.next', 'coverage']);
+
+/**
+ * Newest mtime (ms) of any FILE under a path (a file's own, or the max over the
+ * files in a directory tree, skipping dependencies / dotfiles). Directory-node
+ * mtimes are NOT counted, matching dev-regenerate's walker: a content edit only
+ * shows through the file mtime, and a directory mtime is a flaky moving target.
+ * A missing path is 0. Best-effort: never throws.
+ * @param {string} abs
+ * @returns {number}
+ */
+export function newestMtimeMs(abs) {
+  let st;
+  try { st = statSync(abs); } catch { return 0; }
+  if (!st.isDirectory()) return st.mtimeMs;
+  let newest = 0;
+  let entries;
+  try { entries = readdirSync(abs, { withFileTypes: true }); } catch { return newest; }
+  for (const e of entries) {
+    if (e.name.startsWith('.') || FRESHNESS_IGNORE.has(e.name)) continue;
+    // Skip symlinks: following one can cycle into unbounded recursion (a stack
+    // overflow here) or escape into node_modules. Same tradeoff as the server
+    // walker in dev-regenerate.js.
+    if (e.isSymbolicLink()) continue;
+    const m = newestMtimeMs(join(abs, e.name));
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+/**
+ * Whether the `<link>` tag at `idx` is commented out, so dead markup is never
+ * reported as a live finding.
+ *
+ * A DELIMITED comment is decided by an unclosed opener behind the tag. Neither
+ * `<!--` nor `/*` nests, so "nearest opener beats nearest closer" is exact, and
+ * it covers a multi-line block whose interior lines carry no marker of their
+ * own (what an editor's toggle-block-comment writes). A `//` has no closer, so
+ * it is decided from the tag's own line: a `//` inside an href later in the
+ * line cannot match, because the line does not START with it.
+ *
+ * Do NOT replace this with a lexer. Two attempts did, and both shipped bugs a
+ * stateless test cannot have: a line-blanking regex killed any line holding a
+ * protocol-relative url, and a quote-tracking walk inverted string/code
+ * polarity on a nested ``html`...` `` inside a `${}` hole (one quote char
+ * cannot model nesting), so an unbalanced apostrophe in template text
+ * desynchronized the rest of the file. This check does not need to lex
+ * JavaScript. If it ever genuinely does, export `redactStringsAndTemplates`
+ * from `@webjsdev/server` (`src/js-scan.js`, fuzz-tested differentially against
+ * a real TypeScript parse) rather than growing a third one here.
+ *
+ * Residual gap: a tag behind a `//` that trails real code on the same line
+ * stays reported. Rare, and it fails toward reporting rather than toward the
+ * silent inertness both lexers produced.
+ *
+ * @param {string} src
+ * @param {number} idx  index of the tag's `<`
+ * @returns {boolean}
+ */
+export function isCommentedOut(src, idx) {
+  const before = src.slice(0, idx);
+  if (before.lastIndexOf('<!--') > before.lastIndexOf('-->')) return true;
+  if (before.lastIndexOf('/*') > before.lastIndexOf('*/')) return true;
+  const lineStart = before.lastIndexOf('\n') + 1;
+  return before.slice(lineStart).trimStart().startsWith('//');
+}