@elytracms/cli 0.0.79 → 0.0.81

package/README.md

@@ -29,7 +29,8 @@ elytra doctor   Diagnose the active deployment's readiness and print each fix.
                 by NAME only — values are never read into the report or printed.
                 When the publish revalidate pair is set, also sends a signed
                 no-op ping to the endpoint to prove the publish → live chain
-                end to end. Also reports the generated-previews artifacts
+                end to end. Also checks your cms/ route set for URL conflicts
+                (see below), and reports the generated-previews artifacts
                 (manifest present, image files present, no strays — warnings
                 only; previews are optional). Read-only; exits non-zero if any
                 check fails.
@@ -175,3 +176,90 @@ has no `pairWith` escalation because its real partner lives on a plane this
 doctor cannot read. Missing it is a warning: draft preview is closed
 everywhere (401 on both sides) until it's set — a project that never uses
 draft preview may legitimately leave it unset.
+
+## Route conflicts (`elytra doctor`)
+
+Routes are code, so a route conflict is a build-time bug, and `elytra doctor`
+reports it: two routes that would match the exact same URLs fail the run with
+the offending ids and patterns named. Nothing about this needs a deployment —
+the check runs in playground mode too.
+
+The doctor reads the route set from your project's `cms/index.ts` (the
+`collections` + `routes` your `elytra.config.ts` passes through). That tree is
+plain, React-free TypeScript by convention, so the CLI imports it natively —
+no bundler, no Vite, no dev server. Two consequences worth knowing:
+
+- It needs a Node that runs TypeScript natively (**≥22.18**). On an older Node
+  the check reports "not checked here" and names the version — never a false
+  pass.
+- If the route set cannot be read for any reason (no `cms/index.ts`, a module
+  that throws, an import the CLI cannot resolve such as a `tsconfig` path
+  alias, TypeScript syntax Node cannot strip, or a `routes` export of the
+  wrong shape), the check reports **why**, as "not checked here". It never
+  crashes the doctor and never claims your routes are fine.
+
+### Conflicting hierarchy mounts
+
+A hierarchy mount (`/:path*`, `/docs/:path*`) is not a router route: it is pulled
+out of the router and resolved per request against a collection's composed page
+tree. So the route-conflict check above cannot see mounts at all, and a second
+row — `mount-conflicts` — judges them by what they declare instead:
+
+- **Two collections mounted at the same path fail the run.** They claim an
+  identical URL space, and the only thing separating them is declaration order.
+- **A mount nested inside another's URL space is a warning.** It is a real
+  shadow, but only where the outer collection's tree actually composes a path
+  into the inner mount's prefix — that is content, which a CLI cannot see, so
+  naming the precedence is honest and failing your build on it would not be.
+
+The precedence being named is worth stating plainly, because nothing else does:
+**mounts are tried in declaration order, not by specificity**, and the first
+whose collection resolves a document for that URL wins. A root mount declared
+first therefore outranks a deeper one — the opposite of how ordinary routes
+behave, where more static segments always win. Declare the more specific mount
+first.
+
+### Declarations that serve nothing
+
+A third row — `unreachable-routes` — asks a different question from the two
+above: not "do two declarations fight?" but "can this declaration ever serve
+anything at all?" Three shapes trip it, all of which used to 404 silently with
+no issue raised anywhere:
+
+- **An all-dynamic route over a mount's URL space** — a **warning**. `/:slug`
+  matches *every* one-segment URL, so the `/:path*` mount is consulted there
+  only where the route resolves no document. Nothing is unconditionally
+  unreachable (the resolver falls through — see *Precedence* below), but
+  precedence at that depth is then decided by your **content**: a page whose
+  composed path collides with a post slug is silently shadowed, and neither
+  side is told. `/blog/:slug` is fine and always was: a static segment claims
+  only the namespace you carved out. It is the *all*-dynamic pattern that takes
+  a whole depth.
+- **A mount on a collection that cannot back it** — no `parent` self-relation,
+  so there are no nested paths to compose, or the collection is not declared at
+  all. The resolver skips such a mount silently; every URL under it 404s. This
+  one **fails** the run: no content and no ordering can make it work.
+- **A catch-all with a dynamic prefix** (`/:lang/:path*`) — also a **failure**.
+  It is dead in both directions: every router drops it as a catch-all, and no
+  mount is built from it because a mount prefix must be static. For per-locale
+  mounts, declare one mount per locale instead:
+  `{ pattern: '/de/:path*', locale: 'de' }`.
+
+### Precedence: a match is not a result
+
+A route always wins over a mount **for the URLs it can actually serve**. When a
+route matches a URL but resolves no document there — no post with that slug, or
+none published in this perspective — the resolver falls through to the hierarchy
+mounts instead of returning 404. So declaring `/blog/:slug` does not take the
+`/blog/*` namespace away from your page tree: a page at `blog/kid` is served,
+and it stops being served the moment a *post* with slug `kid` exists.
+
+The consequence worth knowing: which collection serves such a URL depends on
+what exists, not on the routes alone, and it is evaluated per perspective — a
+draft-only post wins in preview while the published page still serves live.
+
+**Redirect loops are not checked here.** Since EC-303 redirects are editorial
+data in the backend, not code — a CLI has no editorial data. The studio checks
+them (and route conflicts, and the route-side half of `unreachable-routes`)
+live, at the section-rail foot, because it holds both the config routes and the
+redirects rail.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/cli",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.79",
+  "version": "0.0.81",
   "description": "The Elytra CLI — run a consuming repo's studio, frontend, and Convex backend under one command.",
   "license": "MIT",
   "type": "module",
@@ -17,7 +17,7 @@
     "node": ">=20"
   },
   "dependencies": {
-    "@elytracms/core": "^0.0.79"
+    "@elytracms/core": "^0.0.81"
   },
   "devDependencies": {
     "vitest": "^4.1.10"

package/src/cli.js

@@ -29,9 +29,10 @@ Commands:
              values never shown — config, membership) and print each fix. When the
              instant-publish revalidate pair is set, also sends a signed no-op ping
              to the endpoint to prove the publish → live chain end to end. Also
-             reports the generated-previews artifacts (manifest/files present;
-             hash staleness lives in \`elytra previews --check\`). Exit non-zero
-             if any check fails. Read-only. Optional: --url <convex url>.
+             checks your cms/ routes for URL conflicts, and reports the
+             generated-previews artifacts (manifest/files present; hash staleness
+             lives in \`elytra previews --check\`). Exit non-zero if any check
+             fails. Read-only. Optional: --url <convex url>.
   previews   Render every canvas-eligible component's fixtures against YOUR theme
              (headless Chromium via Playwright — an optional install) and write
              committed preview images (studio/public/elytra-previews/) plus an
@@ -110,9 +111,11 @@ Diagnose the active deployment's readiness (URL, reachability, auth signing
 keys, expected deployment env vars — set/missing by NAME, values never shown
 — config, membership) and print each fix. When the instant-publish
 revalidate pair is set, also sends a signed no-op ping to the endpoint to
-prove the publish → live chain end to end. Also reports the
-generated-previews artifacts (manifest/files present; hash staleness lives
-in \`elytra previews --check\`). Exit non-zero if any check fails. Read-only.
+prove the publish → live chain end to end. Also checks the route set in your
+cms/ for URL conflicts (routes are code — redirect loops are editorial data
+and are checked in the studio), and reports the generated-previews artifacts
+(manifest/files present; hash staleness lives in \`elytra previews --check\`).
+Exit non-zero if any check fails. Read-only.
 
 Options:
   --url <convex url>   Diagnose this deployment instead of the one resolved
@@ -470,6 +473,8 @@ export async function run(argv, { cwd = process.cwd(), env = process.env, emit =
       // EC-399: where `convex env list` runs (name enumeration — presence only),
       // and whether the AI provider-key expectation applies.
       studioDir: project.apps.studio ? join(project.root, 'studio') : undefined,
+      // EC-469: where the project's `cms/` route set is read from (code, not backend).
+      root: project.root,
       aiRouteConfigured: project.hasAiRoute,
       exec,
     })

package/src/doctor.js

@@ -9,6 +9,7 @@ import {
 } from '@elytracms/core/export-sync/deployment-ready'
 import { convexEnvGet, defaultConvexExec } from './provision.js'
 import { gatherPreviewsArtifacts, previewsDoctorChecks } from './previews.js'
+import { loadProjectRoutes, routesDoctorChecks } from './routes-check.js'
 
 /**
  * `elytra doctor` (EC-259) — the pre-boot counterpart to the studio's boot
@@ -236,6 +237,22 @@ const BUCKET_TITLE = {
   previews: 'Previews',
 }
 
+/**
+ * Splice extra checks into an existing bucket's run, right after that bucket's last
+ * check (EC-469). {@link formatReport} opens a bucket heading whenever `check.bucket`
+ * changes, so appending an `app` check after the `user`/`previews` ones would print
+ * "App:" twice. Bucket absent from the report → the extras go at the end. Pure.
+ */
+export function spliceBucketChecks(checks, bucket, extra) {
+  if (extra.length === 0) return [...checks]
+  let last = -1
+  for (let i = 0; i < checks.length; i++) {
+    if (checks[i].bucket === bucket) last = i
+  }
+  if (last === -1) return [...checks, ...extra]
+  return [...checks.slice(0, last + 1), ...extra, ...checks.slice(last + 1)]
+}
+
 /**
  * Render a `DeploymentReadinessReport` as the bucketed doctor report (pure — no I/O,
  * no color, so it's directly testable). Failing AND warning checks print their
@@ -284,6 +301,12 @@ export function formatReport(report) {
  * findings there are warnings (previews are optional); input-hash STALENESS needs
  * the component registry and lives in `elytra previews --check` (the ratified
  * split). `previewsArtifacts` is injectable for tests.
+ *
+ * EC-469: when a project `root` is known, the `app` bucket also reports ROUTE
+ * CONFLICTS, read from the project's React-free `cms/` tree (see `routes-check.js`).
+ * That check CAN fail — a conflict is deterministic in code — so it participates in
+ * the exit code; a route set that cannot be read reports `unknown` with its reason and
+ * never fails. `routeFacts` is injectable for tests.
  */
 export async function runDoctor({
   env = {},
@@ -291,9 +314,11 @@ export async function runDoctor({
   log = (l) => console.log(l),
   url,
   studioDir,
+  root,
   aiRouteConfigured = false,
   exec,
   previewsArtifacts,
+  routeFacts,
 } = {}) {
   const target = resolveDoctorTarget(env, { url })
 
@@ -325,12 +350,22 @@ export async function runDoctor({
 
   // EC-440: the previews bucket (repo artifacts, backend-independent). Appended to
   // the shared report before formatting so it wears the same glyph/fix conventions;
-  // its checks are ok/warn/unknown only, so `report.ok` (the exit code) is unchanged.
+  // its checks are ok/warn/unknown only, so the exit code is unchanged by them.
   const artifacts = previewsArtifacts ?? (studioDir ? gatherPreviewsArtifacts(studioDir) : undefined)
-  const merged = artifacts
-    ? { ...report, checks: [...report.checks, ...previewsDoctorChecks(artifacts)] }
-    : report
+  let checks = artifacts ? [...report.checks, ...previewsDoctorChecks(artifacts)] : [...report.checks]
+
+  // EC-469: the route-conflict check, spliced into the `app` bucket it belongs to.
+  // Backend-independent (routes are CODE) — it runs in playground mode too.
+  if (root !== undefined || routeFacts !== undefined) {
+    const facts = routeFacts ?? (await loadProjectRoutes(root))
+    checks = spliceBucketChecks(checks, 'app', routesDoctorChecks(facts))
+  }
+
+  // One rule for the exit code, the same one `checkDeploymentReady` applies: a
+  // report is ok when nothing FAILED. Recomputed over the merged set so an appended
+  // bucket's failure can never be silently dropped from the exit code.
+  const merged = { ok: !checks.some((c) => c.status === 'fail'), checks }
 
   log(formatReport(merged))
-  return report.ok ? 0 : 1
+  return merged.ok ? 0 : 1
 }

package/src/routes-check.js

@@ -0,0 +1,473 @@
+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.** Doctor deliberately executes no `elytra.config.ts` (it
+ * imports React components). But 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, with no bundler and no Vite, and reads the
+ * same `collections` + `routes` that `elytra.config.ts` passes straight through.
+ *
+ * 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 {
+      unavailable: `No ${CMS_ENTRY} found — routes are declared in the project's cms/ directory.`,
+    }
+  }
+
+  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.`,
+  }
+}