@elytracms/cli 0.0.80 → 0.0.82

package/src/routes-check.js

@@ -0,0 +1,483 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+  createRouter,
+  declaredMounts,
+  hierarchyMountConflicts,
+  isHierarchyTemplate,
+  routeRecordSchema,
+  routeReachabilityIssues,
+} from '@elytracms/core/cms-core'
+
+/**
+ * `elytra doctor`'s route check (EC-469) — the CODE side of route validation.
+ *
+ * `createRouter` computes real structural issues and, before this, no surface showed
+ * them: the studio has had no Routes screen since EC-303 (correctly — routes are
+ * code), and doctor deferred structure to "the studio boot and `elytra build`",
+ * neither of which checked routes. A route conflict shipped silently.
+ *
+ * **What lives here and why only this.** `createRouter` produces exactly two codes —
+ * `route-conflict` (from routes alone) and `redirect-loop` (from redirects). Since
+ * EC-303 redirects are editorial DATA in the backend, so a bundler-less, session-less
+ * CLI cannot see them; and `unknown-route-target` is not a router issue at all — the
+ * *resolver* raises it per URL against the documents that exist
+ * (`core/src/content/client.ts`). So the honest CLI-side answer is **route conflicts**,
+ * and the other two are the studio's (which holds both the routes and the redirects).
+ * The `redirect-loops` check below says exactly that, as an `unknown` — the same
+ * convention `config-valid` already uses for a fact the CLI cannot gather.
+ *
+ * EC-482 adds the half the router structurally cannot see: **hierarchy mounts**. They
+ * are filtered OUT of the router (below, and identically in delivery), so two mounts
+ * fighting over the same URLs were invisible to every surface. `hierarchyMountConflicts`
+ * judges them by declaration instead of by pattern shape; the second check row reports
+ * it. Both checks are code-side and mutually exclusive by construction — a mount never
+ * reaches the router, an ordinary route never reaches the mount detector.
+ *
+ * EC-484 adds the third row, `unreachable-routes`, for the case where nothing is in
+ * conflict and the declaration simply does not work: a `/:slug`-shaped route that
+ * matches every URL at a depth the mount serves (so the mount is never reached and
+ * existing pages 404), a mount whose collection cannot compose nested paths, and a
+ * catch-all with a dynamic prefix that every router drops and no mount is built from.
+ * All three were measured to resolve `notFound` with zero issues on every surface.
+ *
+ * **Loading the routes.** This check runs with NO bundler and NO installed deps: a
+ * project's `cms/` tree is React-free by convention — measured across `apps/demo`, the
+ * scaffold template, and both real consumer repos: every external import is
+ * `import type`, erased by Node's own TypeScript support. So doctor imports
+ * `cms/index.ts` natively and reads the same `collections` + `routes` that
+ * `elytra.config.ts` passes straight through. (`elytra.config.ts` itself is NOT
+ * loadable this way — it imports `.tsx` component barrels, which no Node version
+ * executes, EC-474. Where the consumer's deps ARE installed, EC-495's Vite harness
+ * executes the full config and `runDoctor` hands the collections it resolved to these
+ * checks in place of the `cms/index.ts` re-export; this loader stays the floor.)
+ *
+ * Two things stand in the way, and both are handled rather than assumed away:
+ *
+ * 1. **Node floor.** Native TS needs Node ≥22.18 (measured: 22.13 → `ERR_UNKNOWN_
+ *    FILE_EXTENSION`, 22.21 → loads). Below the floor the check reports `unknown`
+ *    with the version as its reason — the CLI's own `engines` promise (>=20) is not
+ *    quietly broken.
+ * 2. **Bundler-style specifiers.** Real `cms/` trees write `from './collections'` —
+ *    extensionless, and a directory at that. Plain Node ESM resolves neither, at any
+ *    version. {@link withBundlerResolution} registers a *fallback* resolve hook that
+ *    supplies the extension/index a bundler would, and only after Node's own
+ *    resolution has already failed — so it can never hijack a specifier that already
+ *    resolves.
+ *
+ * Executing consumer code in a tool that otherwise only does HTTP is a change in
+ * kind, so it is bounded: one conventional file, read-only, no writes, and every
+ * failure mode (missing file, throwing module, unresolvable import, non-erasable TS,
+ * a `routes` export of the wrong shape, a derive that throws) degrades to a reported
+ * `unknown` carrying its reason. There is no path here that crashes the doctor and
+ * none that reports a pass it did not establish.
+ */
+
+// --- Loading the project's routes (impure) -----------------------------------
+
+/** Where the route set is read from, by convention (AD-11: structure is code, in-repo). */
+export const CMS_ENTRY = join('cms', 'index.ts')
+
+/** Relative-specifier suffixes a bundler would try, in the order it tries them. */
+const RESOLVE_CANDIDATES = ['.ts', '.tsx', '/index.ts', '/index.tsx', '.js', '.mjs', '/index.js']
+
+/**
+ * Run `load` with a FALLBACK module-resolution hook that supplies the extension or
+ * `/index` a bundler would for a relative specifier — but only for specifiers Node
+ * itself could not resolve, so an already-valid specifier is never rewritten. The
+ * hook is deregistered before returning, in success and in failure alike: doctor
+ * never leaves process-wide resolution patched.
+ *
+ * `module.registerHooks` is Node ≥22.15. Where it is absent the load simply runs
+ * unhooked (a `cms/` tree with explicit extensions still works) — never an error.
+ */
+export async function withBundlerResolution(load) {
+  let handle
+  try {
+    const { registerHooks } = await import('node:module')
+    if (typeof registerHooks === 'function') {
+      handle = registerHooks({
+        resolve(specifier, context, nextResolve) {
+          try {
+            return nextResolve(specifier, context)
+          } catch (error) {
+            if (!specifier.startsWith('./') && !specifier.startsWith('../')) throw error
+            if (!context.parentURL) throw error
+            for (const suffix of RESOLVE_CANDIDATES) {
+              const url = new URL(specifier + suffix, context.parentURL)
+              if (url.protocol === 'file:' && existsSync(fileURLToPath(url))) {
+                return { url: url.href, shortCircuit: true }
+              }
+            }
+            throw error
+          }
+        },
+      })
+    }
+  } catch {
+    // No resolve-hook support in this runtime — load unhooked.
+  }
+  try {
+    return await load()
+  } finally {
+    handle?.deregister()
+  }
+}
+
+/**
+ * Silence ONE Node warning for the duration of `run`:
+ * `MODULE_TYPELESS_PACKAGE_JSON`, which fires for every consumer repo whose root
+ * `package.json` omits `"type": "module"` (both real ones). It is unrelated to route
+ * validity and would print into the middle of the doctor report. Every other warning
+ * still prints, and the original listeners are restored unconditionally.
+ */
+async function withoutTypelessModuleWarning(run) {
+  const listeners = process.listeners('warning')
+  process.removeAllListeners('warning')
+  const passthrough = (warning) => {
+    if (warning?.code === 'MODULE_TYPELESS_PACKAGE_JSON') return
+    for (const listener of listeners) listener(warning)
+  }
+  process.on('warning', passthrough)
+  try {
+    return await run()
+  } finally {
+    process.off('warning', passthrough)
+    for (const listener of listeners) process.on('warning', listener)
+  }
+}
+
+/** The first line of an error, safe for a one-line report row. */
+function reason(error) {
+  const text = error instanceof Error ? error.message : String(error)
+  return text.split('\n')[0].trim()
+}
+
+/**
+ * Materialize a `routes` config value against the declared collections — the same
+ * rule `studio-core`'s `materializeRecords` applies (EC-207): a derive function runs
+ * once, a static array passes through. Both real consumer repos declare the array
+ * form; the demo and the scaffold declare the derive.
+ */
+function materializeRoutes(routes, collections) {
+  return typeof routes === 'function' ? routes(collections) : [...routes]
+}
+
+/**
+ * Load the project's declared route set. Returns either `{ routes, routeCount }` or
+ * `{ unavailable, fix? }` — an honest reason the routes could not be read. Never
+ * throws.
+ *
+ * `importModule` is injectable for tests (the default is a native dynamic import).
+ */
+export async function loadProjectRoutes(root, { importModule } = {}) {
+  const entry = join(root, CMS_ENTRY)
+  if (!existsSync(entry)) {
+    return {
+      // EC-533: state what this FALLBACK looked for, not what a project must contain.
+      // Elytra requires one thing of a repo — an `elytra.config.ts` of the right shape
+      // — and no blessed module paths (EC-532). `cms/index.ts` is the scaffold's own
+      // convention, which is all this bundler-free loader can find on its own; where
+      // the project's deps are installed, EC-495's Vite harness executes the real
+      // config and this floor is never reached.
+      unavailable: `Routes not checked: no ${CMS_ENTRY} to read without a bundler (this is the scaffold's convention, not a requirement — your routes may be declared elsewhere).`,
+    }
+  }
+
+  const load = importModule ?? ((path) => import(pathToFileURL(path).href))
+  let mod
+  try {
+    mod = await withoutTypelessModuleWarning(() => withBundlerResolution(() => load(entry)))
+  } catch (error) {
+    if (error?.code === 'ERR_UNKNOWN_FILE_EXTENSION') {
+      return {
+        unavailable: `${CMS_ENTRY} could not be read: this Node (${process.version}) does not run TypeScript natively.`,
+        fix: 'Use Node >=22.18 (the version the engine targets) to have `elytra doctor` check routes.',
+      }
+    }
+    if (error?.code === 'ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX') {
+      return {
+        unavailable: `${CMS_ENTRY} uses TypeScript syntax Node cannot strip (${reason(error)}).`,
+        fix: 'Keep cms/ to erasable TypeScript (no enum/namespace/parameter properties) so build-time tools can read your structure.',
+      }
+    }
+    return { unavailable: `${CMS_ENTRY} could not be loaded: ${reason(error)}` }
+  }
+
+  if (mod?.routes === undefined) {
+    return {
+      unavailable: `${CMS_ENTRY} exports no \`routes\` — the route set was not checked here.`,
+    }
+  }
+  if (typeof mod.routes !== 'function' && !Array.isArray(mod.routes)) {
+    return {
+      unavailable: `${CMS_ENTRY} exports \`routes\` that is neither a RouteRecord[] nor a (collections) => RouteRecord[].`,
+    }
+  }
+  // Distinguish "exports no collections" from "exports an empty array": the
+  // reachability check must report NOT CHECKED rather than a pass when it cannot see
+  // the collection set (a mount's target is judged against it).
+  const collections = Array.isArray(mod.collections) ? mod.collections : undefined
+
+  let records
+  try {
+    records = materializeRoutes(mod.routes, collections ?? [])
+  } catch (error) {
+    return { unavailable: `The \`routes\` derive in ${CMS_ENTRY} threw: ${reason(error)}` }
+  }
+  if (!Array.isArray(records)) {
+    return { unavailable: `The \`routes\` derive in ${CMS_ENTRY} did not return an array.` }
+  }
+
+  // Shape-validate before handing records to the router: a malformed record (no
+  // pattern) would otherwise fault inside pattern compilation. Config validity is
+  // the studio boot's job, so this reports rather than duplicating that check.
+  const invalid = records.filter((record) => !routeRecordSchema.safeParse(record).success)
+  if (invalid.length > 0) {
+    return {
+      unavailable: `${invalid.length} of ${records.length} route record(s) are not valid RouteRecords — config validation reports the details.`,
+      fix: 'Open the studio (or run your build) to see the config validation issues, then re-run `elytra doctor`.',
+    }
+  }
+
+  return {
+    routes: records,
+    routeCount: records.length,
+    ...(collections ? { collections } : {}),
+  }
+}
+
+// --- Detection (pure) --------------------------------------------------------
+
+/**
+ * The router issues of a declared route set — route conflicts, since a CLI passes
+ * no redirects.
+ *
+ * Hierarchy-mount templates (`/:path*`, EC-218) are filtered out first, exactly as
+ * the delivery resolver does (`core/src/content/client.ts:230`): a mount is resolved
+ * per-request against the parent chain, not by the router, so counting it as a route
+ * would report conflicts the runtime does not have. Running the same filter is what
+ * makes doctor unable to disagree with delivery.
+ *
+ * The filter is NOT widened to cover EC-482 — {@link mountIssuesOf} answers that
+ * question about the routes this one removes. Widening the router's signature
+ * comparison instead would reinstate the `/:slug` + `/:path*` false positive the
+ * filter exists to prevent (pinned in both this package's and cms-core's tests).
+ */
+export function routeIssuesOf(routes) {
+  return createRouter(routes.filter((route) => !isHierarchyTemplate(route)), []).issues
+}
+
+/**
+ * The conflicts BETWEEN hierarchy mounts (EC-482) — the routes {@link routeIssuesOf}
+ * filters away. `error` for two mounts on the same path (identical URL space, split
+ * only by declaration order), `warning` for a nested pair (a real shadow, but only
+ * where the outer collection's page tree actually reaches into the inner prefix — a
+ * content fact a CLI cannot see).
+ */
+export function mountIssuesOf(routes) {
+  return hierarchyMountConflicts(routes)
+}
+
+/**
+ * The declarations that can never serve content (EC-484) — the third question, after
+ * "do two routes fight" and "do two mounts fight": **does this declaration work at
+ * all?** An all-dynamic route (`/:slug`) matching every URL at a depth the mount
+ * serves, a mount whose collection has no `parent` self-relation (or is not declared),
+ * and a catch-all with a dynamic prefix (`/:lang/:path*`) that every router drops and
+ * no mount is built from. All three were measured to resolve `notFound` with ZERO
+ * issues anywhere before this.
+ *
+ * `collections` is passed through when the project exported them; without them the
+ * mount-target half is skipped and {@link routesDoctorChecks} reports `unknown`
+ * instead of a pass it did not establish.
+ */
+export function reachabilityIssuesOf(routes, collections) {
+  return routeReachabilityIssues(routes, collections)
+}
+
+// --- Doctor checks (pure) ----------------------------------------------------
+
+const CONFLICT_FIX =
+  'Two routes match the same URLs — give one a distinct pattern (or delete it) in cms/routes.ts.'
+
+const MOUNT_CONFLICT_FIX =
+  'Two collections cannot be served from the same URL space — give one mount a distinct prefix (e.g. "/docs/:path*") in cms/routes.ts, or drop it.'
+
+const MOUNT_SHADOW_FIX =
+  'Mounts resolve in declaration order, not by specificity — declare the more specific mount first, and keep the outer collection\'s page tree clear of that prefix.'
+
+const UNREACHABLE_FIX =
+  'Give an all-dynamic route a static segment (e.g. "/blog/:slug"), mount only collections with a `parent` self-relation, and keep a mount prefix static — in cms/routes.ts.'
+
+/** An `unknown` check row carrying the reason the routes could not be read. */
+function unavailableCheck(id, facts) {
+  return {
+    id,
+    bucket: 'app',
+    status: 'unknown',
+    detail: facts?.unavailable ?? 'Routes were not evaluated here.',
+    ...(facts?.fix ? { fix: facts.fix } : {}),
+  }
+}
+
+/**
+ * The doctor's route checks, for the `app` bucket. Consumes the already-loaded facts
+ * (the {@link loadProjectRoutes} result) so the reporting shape is pure and directly
+ * testable, like `formatReport` and `previewsDoctorChecks`.
+ *
+ * Four rows, in the order a reader needs them: the router's own conflicts, the
+ * mount-vs-mount conflicts the router cannot see (EC-482), the declarations that serve
+ * nothing at all (EC-484), then the redirects a CLI cannot see at all.
+ *
+ * `route-conflicts`, `mount-conflicts` and `unreachable-routes` are the checks here
+ * that can FAIL — all deterministic in code, so failing the exit code is safe for CI.
+ * The latter two can also `warn`, in both cases for the same reason: the finding only
+ * costs content where a collection's tree actually reaches that far, which is CONTENT
+ * a CLI cannot see, so naming it is honest where failing a build would not be.
+ * `redirect-loops` is always `unknown`: they are editorial data, and saying so is how
+ * the report stays honest about what a CLI can and cannot see.
+ */
+export function routesDoctorChecks(facts) {
+  const redirects = {
+    id: 'redirect-loops',
+    bucket: 'app',
+    status: 'unknown',
+    detail:
+      'Redirect loops were not evaluated here — redirects are editorial data in the backend; the studio checks them.',
+  }
+
+  if (!facts || facts.unavailable) {
+    return [
+      unavailableCheck('route-conflicts', facts),
+      unavailableCheck('mount-conflicts', facts),
+      unavailableCheck('unreachable-routes', facts),
+      redirects,
+    ]
+  }
+
+  const count = facts.routeCount ?? facts.routes.length
+  const plural = count === 1 ? '' : 's'
+  const conflicts = routeIssuesOf(facts.routes).filter((issue) => issue.code === 'route-conflict')
+
+  const routeConflicts =
+    conflicts.length === 0
+      ? {
+          id: 'route-conflicts',
+          bucket: 'app',
+          status: 'ok',
+          detail: `${count} declared route${plural}, no URL conflicts.`,
+        }
+      : {
+          id: 'route-conflicts',
+          bucket: 'app',
+          status: 'fail',
+          detail:
+            `${conflicts.length} route conflict(s) among ${count} declared route${plural}. ` +
+            conflicts.map((issue) => issue.message).join(' '),
+          fix: CONFLICT_FIX,
+        }
+
+  return [
+    routeConflicts,
+    mountConflictsCheck(facts.routes),
+    unreachableRoutesCheck(facts.routes, facts.collections),
+    redirects,
+  ]
+}
+
+/**
+ * The `unreachable-routes` row (EC-484): declarations that resolve to nothing.
+ *
+ * Like `mount-conflicts` it states what it LOOKED at when it passes — a bare "ok"
+ * reads the same whether the check examined the mounts or skipped them. And when the
+ * project exported no collections it reports `unknown` rather than `ok`: the
+ * mount-target half could not run, and a pass it did not establish would be exactly
+ * the silent failure this ticket exists to remove.
+ */
+function unreachableRoutesCheck(routes, collections) {
+  const mounts = declaredMounts(routes)
+  const scope = `${routes.length} declared route${routes.length === 1 ? '' : 's'}, ${mounts.length} hierarchy mount${mounts.length === 1 ? '' : 's'}`
+  const base = { id: 'unreachable-routes', bucket: 'app' }
+
+  const issues = reachabilityIssuesOf(routes, collections)
+  const errors = issues.filter((issue) => issue.severity === 'error')
+  const warnings = issues.filter((issue) => issue.severity !== 'error')
+
+  if (errors.length > 0) {
+    return {
+      ...base,
+      status: 'fail',
+      detail:
+        `${errors.length} declaration(s) that cannot serve content, among ${scope}. ` +
+        [...errors, ...warnings].map((issue) => issue.message).join(' '),
+      fix: UNREACHABLE_FIX,
+    }
+  }
+  if (warnings.length > 0) {
+    return {
+      ...base,
+      status: 'warn',
+      detail:
+        `${warnings.length} partially shadowed declaration(s), among ${scope}. ` +
+        warnings.map((issue) => issue.message).join(' '),
+      fix: UNREACHABLE_FIX,
+    }
+  }
+  if (mounts.length > 0 && !collections) {
+    return {
+      ...base,
+      status: 'unknown',
+      detail: `${scope}: no route shadows a mount, but mount targets were not checked — ${CMS_ENTRY} exports no \`collections\`.`,
+      fix: `Export \`collections\` from ${CMS_ENTRY} (the shape elytra.config.ts re-exports) so mounts can be checked against them.`,
+    }
+  }
+  return { ...base, status: 'ok', detail: `${scope} — every declaration can serve content.` }
+}
+
+/**
+ * The `mount-conflicts` row (EC-482). Reports the mount COUNT even when clean — a row
+ * that says "1 hierarchy mount, no overlap" proves the check looked at the mounts,
+ * where a bare "ok" would read the same whether it examined them or skipped them.
+ */
+function mountConflictsCheck(routes) {
+  const mounts = declaredMounts(routes)
+  const mountPlural = mounts.length === 1 ? '' : 's'
+  const base = { id: 'mount-conflicts', bucket: 'app' }
+
+  if (mounts.length === 0) {
+    return { ...base, status: 'ok', detail: 'No hierarchy mounts declared.' }
+  }
+
+  const issues = mountIssuesOf(routes)
+  const errors = issues.filter((issue) => issue.severity === 'error')
+  const warnings = issues.filter((issue) => issue.severity !== 'error')
+  const among = `among ${mounts.length} hierarchy mount${mountPlural}`
+
+  if (errors.length > 0) {
+    return {
+      ...base,
+      status: 'fail',
+      detail:
+        `${errors.length} conflicting mount pair(s) ${among}. ` +
+        [...errors, ...warnings].map((issue) => issue.message).join(' '),
+      fix: MOUNT_CONFLICT_FIX,
+    }
+  }
+  if (warnings.length > 0) {
+    return {
+      ...base,
+      status: 'warn',
+      detail:
+        `${warnings.length} overlapping mount pair(s) ${among}. ` +
+        warnings.map((issue) => issue.message).join(' '),
+      fix: MOUNT_SHADOW_FIX,
+    }
+  }
+  return {
+    ...base,
+    status: 'ok',
+    detail: `${mounts.length} hierarchy mount${mountPlural}, no overlapping mounts.`,
+  }
+}