@webjsdev/cli 0.10.55 → 0.10.57

package/lib/doctor/probes/framework-resolves.js

@@ -0,0 +1,260 @@
+import { existsSync, lstatSync, readFileSync, readlinkSync, realpathSync, statSync } from 'node:fs';
+import { dirname, join, resolve, sep } from 'node:path';
+import { createRequire } from 'node:module';
+
+/**
+ * @typedef {import('../codes.js').DoctorResult} DoctorResult
+ */
+
+/**
+ * Probe whether `@webjsdev/core` resolves from `appDir`. Node resolution is
+ * directory-relative, so this must probe FROM the app (not the CLI's own
+ * location, which resolves the framework fine from a global install even when
+ * the app cannot). A no-op-cheap resolve, no I/O beyond what Node's resolver
+ * does, no network. Returns true when the framework resolves, false otherwise.
+ * @param {string} appDir
+ * @returns {boolean}
+ */
+export function frameworkResolves(appDir) {
+  try {
+    // The base file need not exist; createRequire only uses it to anchor the
+    // node_modules lookup at appDir.
+    const require = createRequire(join(appDir, '__webjs_resolve_probe__.js'));
+    require.resolve('@webjsdev/core');
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * CHECK 8, framework resolvability (#954). WARN when `@webjsdev/core` cannot be
+ * resolved FROM the app directory, which is the fresh-git-worktree trap: a
+ * worktree does not copy `node_modules`, so a plain `webjs dev` there dies at
+ * SSR with a raw `ERR_MODULE_NOT_FOUND: Cannot find package '@webjsdev/core'`
+ * whose remedy is not obvious. Silent PASS when the framework resolves (the
+ * common case), so this never slows a healthy app. WARN (not a hard fail): it
+ * is a setup/environment concern, the same tier as the version-coherence check.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkFrameworkResolves(appDir) {
+  const name = 'framework-resolve';
+  if (frameworkResolves(appDir)) {
+    return { name, status: 'pass', message: '@webjsdev/core resolves from the app directory.' };
+  }
+  const hasNodeModules = existsSync(join(appDir, 'node_modules'));
+  // A git worktree checks out `.git` as a FILE (a gitdir pointer), not a
+  // directory. That, plus a missing node_modules, is the exact #954 cause.
+  let isWorktree = false;
+  try {
+    isWorktree = statSync(join(appDir, '.git')).isFile();
+  } catch {
+    isWorktree = false;
+  }
+  if (isWorktree && !hasNodeModules) {
+    return {
+      name,
+      status: 'warn',
+      message:
+        '@webjsdev/core cannot be resolved from this directory, and this is a git worktree with no ' +
+        'node_modules. Git worktrees do not copy node_modules, so the framework is unresolvable here ' +
+        'and `webjs dev` / `webjs start` would fail at SSR with a raw ERR_MODULE_NOT_FOUND.',
+      fix: freshWorktreeFix(appDir),
+    };
+  }
+  if (!hasNodeModules) {
+    return {
+      name,
+      status: 'warn',
+      message: '@webjsdev/core cannot be resolved from this directory (no node_modules present).',
+      fix: 'Run `npm install` in the app directory so the framework resolves.',
+    };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      '@webjsdev/core cannot be resolved from this directory even though node_modules exists ' +
+      '(a partial or corrupted install).',
+    fix: linkAwareReinstallFix(appDir),
+  };
+}
+
+/**
+ * Whether `dir`'s own `node_modules` is a SYMLINK, which in a linked worktree
+ * means it points at the primary checkout's tree. The remedies below branch on
+ * this, because `npm install` is the right advice when it is false and is the
+ * exact command that corrupts the primary when it is true (#1442).
+ * @param {string} dir
+ * @returns {boolean}
+ */
+function modulesAreLinked(dir) {
+  try { return lstatSync(join(dir, 'node_modules')).isSymbolicLink(); } catch { return false; }
+}
+
+/**
+ * The `npm run worktree:link` sentence, but ONLY where that script exists.
+ *
+ * This module ships in the PUBLISHED CLI, and `bin/webjs.js` prints these
+ * remedies verbatim as the `webjs dev` / `webjs start` preflight failure. A
+ * scaffolded app has no `worktree:link` script, so naming it unconditionally
+ * sends the exact audience this check exists for (#954, a fresh app worktree)
+ * to run something that does not exist. Walk up for a package.json that really
+ * declares it, and stay silent otherwise.
+ *
+ * @param {string} appDir
+ * @returns {string} a leading-space sentence, or the empty string
+ */
+function linkScriptHint(appDir) {
+  let dir = resolve(appDir);
+  for (let i = 0; i < 8; i += 1) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      if (pkg?.scripts?.['worktree:link']) {
+        return ' In this repo, `npm run worktree:link` does the whole setup and also repairs the shared tree.';
+      }
+    } catch { /* no package.json here, keep walking */ }
+    const up = dirname(dir);
+    if (up === dir) break;
+    dir = up;
+  }
+  return '';
+}
+
+/**
+ * Remedy for the #954 fresh-worktree case, which is a worktree with NO
+ * `node_modules` at all. There is no symlink in the way yet, so a real install
+ * is safe here, and this stays the app-generic advice it has always been.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function freshWorktreeFix(appDir) {
+  return (
+    'Install dependencies in this worktree (`npm install`), or symlink node_modules from the ' +
+    'primary checkout (`ln -s ../<primary-checkout>/node_modules node_modules`). If you symlink, ' +
+    'never run an install through that link afterwards: it acts on the checkout that owns the ' +
+    'tree, not this one (#1442).' + linkScriptHint(appDir)
+  );
+}
+
+/**
+ * Remedy for a `node_modules` that exists but does not resolve the framework.
+ * When it is a SYMLINK, a bare `npm install` is the action that corrupts the
+ * checkout that owns the tree, so the advice has to differ.
+ * @param {string} appDir
+ * @returns {string}
+ */
+function linkAwareReinstallFix(appDir) {
+  if (modulesAreLinked(appDir)) {
+    return (
+      'node_modules here is a SYMLINK at another checkout, so do NOT run `npm install`: it would act ' +
+      'on that checkout, not this one (#1442). Either reinstall in the checkout that owns the tree, ' +
+      'or remove every node_modules symlink first, nested ones included ' +
+      '(`find . -maxdepth 5 -type l -name node_modules -delete`), and install here.' + linkScriptHint(appDir)
+    );
+  }
+  return 'Reinstall dependencies (`npm install`, or remove node_modules and reinstall).';
+}
+
+/**
+ * Classify the `@webjsdev/core` entry that `appDir` would resolve through.
+ *
+ * Walks up for the first `node_modules` carrying the package, then judges the
+ * link against the tree that PHYSICALLY owns that `node_modules`. That owner
+ * rule is the only one correct in a linked worktree: there `node_modules` is
+ * itself a symlink at the primary's, so the owning tree is the PRIMARY and a
+ * target inside it is right rather than foreign. Judging against `appDir` would
+ * report every correctly linked worktree as corrupted.
+ *
+ * @param {string} appDir
+ * @param {string} [pkg]
+ * @returns {{ state: 'absent'|'real'|'ok'|'dangling'|'foreign', entry?: string, target?: string, owner?: string }}
+ */
+export function inspectFrameworkLink(appDir, pkg = '@webjsdev/core') {
+  const parts = pkg.split('/');
+  let dir = resolve(appDir);
+  for (;;) {
+    const modules = join(dir, 'node_modules');
+    const entry = join(modules, ...parts);
+    let st = null;
+    try { st = lstatSync(entry); } catch { st = null; }
+    if (st) {
+      if (!st.isSymbolicLink()) return { state: 'real', entry };
+      let target = '';
+      try { target = readlinkSync(entry); } catch { return { state: 'real', entry }; }
+      // Resolve the target against the directory the link PHYSICALLY sits in,
+      // which is what the OS does. In a linked worktree `node_modules` is itself
+      // a symlink, so the lexical `dirname(entry)` is under the WORKTREE while
+      // the link really lives in the primary. Resolving lexically turns every
+      // correct `../../packages/core` into a worktree path and reports a healthy
+      // linked worktree as `foreign`.
+      let base = dirname(entry);
+      try { base = realpathSync(base); } catch { /* fall back to the lexical path */ }
+      const abs = resolve(base, target);
+      let owner = dir;
+      try { owner = dirname(realpathSync(modules)); } catch { /* use dir as given */ }
+      if (!existsSync(abs)) return { state: 'dangling', entry, target, owner };
+      let real = abs;
+      try { real = realpathSync(abs); } catch { /* compare the unresolved path */ }
+      let ownerReal = owner;
+      try { ownerReal = realpathSync(owner); } catch { /* compare as given */ }
+      if (real !== ownerReal && !real.startsWith(ownerReal + sep)) {
+        return { state: 'foreign', entry, target, owner: ownerReal };
+      }
+      return { state: 'ok', entry, target, owner: ownerReal };
+    }
+    const up = dirname(dir);
+    if (up === dir) return { state: 'absent' };
+    dir = up;
+  }
+}
+
+/**
+ * CHECK: framework link integrity (#1442). WARN when the `@webjsdev/core` entry
+ * in node_modules is a symlink that DANGLES or resolves OUTSIDE the tree that
+ * owns it. That is what an install run inside a linked worktree leaves behind,
+ * and it is invisible to the framework-resolve check above, which only asks
+ * whether the package resolves at all: a link into a live FOREIGN checkout
+ * resolves perfectly and silently runs another branch's framework source.
+ *
+ * Silent PASS for a real directory, a correct link, and no entry at all, so a
+ * normally installed app pays one `lstat`. WARN rather than fail, the same
+ * environment tier as the framework-resolve and version-coherence checks.
+ * @param {string} appDir
+ * @returns {DoctorResult}
+ */
+export function checkFrameworkLinks(appDir) {
+  const name = 'framework-links';
+  const r = inspectFrameworkLink(appDir);
+  if (r.state === 'absent' || r.state === 'real' || r.state === 'ok') {
+    return {
+      name,
+      status: 'pass',
+      message: 'The @webjsdev framework links resolve inside the checkout that owns them.',
+    };
+  }
+  const fix =
+    'Repoint the entry at the package inside the checkout that owns this node_modules. Do NOT run ' +
+    '`npm install` here while node_modules is a symlink: it acts on that owning checkout, not this ' +
+    'one (#1442).' + linkScriptHint(appDir);
+  if (r.state === 'dangling') {
+    return {
+      name,
+      status: 'warn',
+      message:
+        `${r.entry} is a symlink to ${r.target}, which does not exist. An install run inside a linked ` +
+        'worktree leaves these behind, and the worktree it named has since been removed.',
+      fix,
+    };
+  }
+  return {
+    name,
+    status: 'warn',
+    message:
+      `${r.entry} is a symlink to ${r.target}, which resolves OUTSIDE ${r.owner}, the checkout that ` +
+      'owns this node_modules. It resolves fine, so nothing fails, and the framework source being run ' +
+      "is another checkout's. A deliberate `npm link` produces the same shape.",
+    fix,
+  };
+}

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