create-website-build-kit 0.1.18 → 0.1.20

package/template/scripts/check-cms.mjs

@@ -41,6 +41,7 @@
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, relative, sep } from 'node:path';
 import { parse } from 'yaml';
+import { literalContent } from './lib/literal-content.mjs';
 import { literalImages } from './lib/literal-images.mjs';
 import { routeExists, routesFromPages } from './lib/routes.mjs';
 
@@ -52,6 +53,23 @@ const DIM = '\x1b[2m';
 
 const CONFIG = '.pages.yml';
 
+/*
+ * ⚠ `--fix` PRINTS. IT NEVER WRITES.
+ *
+ *   The name is what people reach for, and the behaviour is what keeps this
+ *   safe: for every undeclared key the check already knows the exact dotted
+ *   path and the value sitting at it, so it can emit the field declaration to
+ *   paste. What it cannot know is whether declaring the key is the RIGHT fix —
+ *   for an analytics ID it is not, and this file's own other warning says so.
+ *
+ *   So the fix is offered, never applied, and the one case where the other
+ *   answer is usually correct is marked.
+ *
+ * It is off by default because this runs in `build:production`, where a gate
+ * that floods is a gate somebody switches off.
+ */
+const SHOW_FIX = process.argv.includes('--fix');
+
 if (!existsSync(CONFIG)) {
   console.log(`${DIM}·${RESET} no ${CONFIG} — no CMS to check`);
   process.exit(0);
@@ -75,6 +93,36 @@ const flatten = (entries) =>
     entry?.type === 'group' ? flatten(entry.items ?? entry.content ?? []) : [entry],
   );
 
+/*
+ * ⚠ A FIELD MAY BORROW ITS SHAPE FROM `components:`, AND MISSING THAT REPORTS
+ *   DATA LOSS THAT IS NOT HAPPENING.
+ *
+ *   PagesCMS lets a field say `component: image_field` instead of repeating a
+ *   field list. This walk used to read only `field.fields`, so every key
+ *   inside a borrowed shape looked undeclared — and undeclared, in this
+ *   check, means "the client's first save DELETES it".
+ *
+ *   Measured on a live trilingual site: six phantom problems across three
+ *   home pages, every one of them `image.src` / `image.alt` / `image.isRender`
+ *   reached through `component: image_field`, which declares exactly those
+ *   three. The site was correct and the check was wrong — the worst direction
+ *   for this particular check to fail in, because the fix it invites is
+ *   pasting duplicate declarations into a config that was already right.
+ */
+function fieldsOf(field, seen = new Set()) {
+  if (!field) return null;
+  if (field.component) {
+    /* A component referring to itself would otherwise recurse forever. */
+    if (seen.has(field.component)) return null;
+    seen.add(field.component);
+    const base = (config.components ?? {})[field.component];
+    /* The field's own keys win over the component's — a call site may
+       override the label, or supply its own `fields` outright. */
+    return base ? fieldsOf({ ...base, ...field, component: undefined }, seen) : null;
+  }
+  return Array.isArray(field.fields) ? field.fields : null;
+}
+
 /** Every dotted path the schema declares. Arrays reuse the parent prefix. */
 function schemaPaths(fields, prefix = '') {
   const out = new Set();
@@ -82,7 +130,76 @@ function schemaPaths(fields, prefix = '') {
     if (!field?.name) continue;
     const path = prefix ? `${prefix}.${field.name}` : field.name;
     out.add(path);
-    if (Array.isArray(field.fields)) for (const p of schemaPaths(field.fields, path)) out.add(p);
+    const sub = fieldsOf(field);
+    if (sub) for (const p of schemaPaths(sub, path)) out.add(p);
+  }
+  return out;
+}
+
+/*
+ * ⚠ A FLAT SET OF DECLARED PATHS IS WRONG FOR `type: block`, AND WRONG IN THE
+ *   DIRECTION THAT LOSES DATA.
+ *
+ *   Comparing `dataPaths(data)` against `schemaPaths(fields)` unions every
+ *   variant of a block: `sections[].items[].path` reads as declared as long
+ *   as ANY section type declares `path`, so a variant missing it is invisible
+ *   behind a sibling that has it.
+ *
+ *   That is the 2026-08-25 incident — PagesCMS deleted card links from a live
+ *   `uz/services.json` while this check reported clean, because a different
+ *   section type happened to declare the same field name.
+ *
+ *   So the data is walked ALONGSIDE the schema instead, and each block item
+ *   is matched to its OWN variant through the discriminator. A field name
+ *   declared by a sibling variant no longer covers for it.
+ */
+function undeclaredPaths(data, fields, prefix = '', out = new Set()) {
+  if (data === null || data === undefined) return out;
+  /* A list's items share their parent's prefix — `items[0].x` and
+     `items[1].x` are the same declared path. */
+  if (Array.isArray(data)) {
+    for (const item of data) undeclaredPaths(item, fields, prefix, out);
+    return out;
+  }
+  if (typeof data !== 'object') return out;
+  if (!fields) return out;
+
+  const byName = new Map(fields.filter((f) => f?.name).map((f) => [f.name, f]));
+
+  for (const [key, value] of Object.entries(data)) {
+    const here = prefix ? `${prefix}.${key}` : key;
+    const field = byName.get(key);
+    if (!field) {
+      out.add(here);
+      continue;
+    }
+
+    if (field.type === 'block') {
+      const discriminator = field.blockKey ?? '_block';
+      for (const item of Array.isArray(value) ? value : [value]) {
+        if (!item || typeof item !== 'object') continue;
+        const variant = (field.blocks ?? []).find((b) => b?.name === item[discriminator]);
+        if (!variant) {
+          /* An item whose type matches no declared variant has NO schema at
+             all, so every key in it would be dropped. */
+          out.add(`${here}[] (no block type "${item[discriminator]}")`);
+          continue;
+        }
+        const variantFields = fieldsOf(variant) ?? [];
+        for (const [k, v] of Object.entries(item)) {
+          if (k === discriminator) continue;
+          const vf = variantFields.find((x) => x?.name === k);
+          if (!vf) {
+            out.add(`${here}[type=${item[discriminator]}].${k}`);
+            continue;
+          }
+          undeclaredPaths(v, fieldsOf(vf), `${here}[type=${item[discriminator]}].${k}`, out);
+        }
+      }
+      continue;
+    }
+
+    undeclaredPaths(value, fieldsOf(field), here, out);
   }
   return out;
 }
@@ -102,20 +219,78 @@ function dataPaths(value, prefix = '') {
   return out;
 }
 
+/** The same walk as `dataPaths`, keeping one sample value per path. */
+function pathValues(value, prefix = '', out = new Map()) {
+  if (Array.isArray(value)) {
+    for (const item of value) pathValues(item, prefix, out);
+  } else if (value && typeof value === 'object') {
+    for (const [key, inner] of Object.entries(value)) {
+      const path = prefix ? `${prefix}.${key}` : key;
+      /* First writer wins: across a collection the first document with a key is
+         as good a sample as any, and later ones must not overwrite a rich value
+         with a null from a document that happens to omit it. */
+      if (!out.has(path)) out.set(path, inner);
+      pathValues(inner, path, out);
+    }
+  }
+  return out;
+}
+
 /** Frontmatter keys actually used across a collection, as dotted paths. */
-function collectionPaths(dir) {
+function collectionPaths(dir, values = new Map(), fields = null, exclude = []) {
   const out = new Set();
+  /*
+   * ⚠ `exclude` MUST BE HONOURED, or a file that legitimately sits inside a
+   *   collection's directory is checked against the wrong schema.
+   *
+   *   The real case: a home page living at `pages/ru/home.json` with its own
+   *   `type: file` entry and its own fields, while `pages/ru` is a collection
+   *   of interior pages. Reading it as a collection item reports every home
+   *   page key as undeclared — six confident, wrong data-loss problems on a
+   *   config that already handled this correctly by declaring
+   *   `exclude: [home.json]`.
+   *
+   *   A check that cries wolf gets switched off, so this is not cosmetic.
+   */
+  const excluded = new Set((exclude ?? []).map((e) => String(e)));
   const walk = (d) =>
     readdirSync(d).flatMap((e) => {
       const full = join(d, e);
       return statSync(full).isDirectory() ? walk(full) : [full];
     });
-  for (const file of walk(dir).filter((f) => /\.mdx?$/.test(f))) {
+  /*
+   * ⚠ `.json` IS NOT OPTIONAL HERE, AND OMITTING IT SKIPS WHOLE COLLECTIONS
+   *   IN SILENCE.
+   *
+   *   This read only `.md`/`.mdx` and took the absence of frontmatter as
+   *   "nothing to check". A collection whose items are JSON therefore passed
+   *   without a single file being opened — no warning, no count, just a tick.
+   *
+   *   Measured on a live site: 60 JSON items across six collections, none of
+   *   them ever read, while the check reported clean. Astro content
+   *   collections take JSON as readily as Markdown, so this is a normal shape
+   *   and not an exotic one.
+   */
+  const withinCollection = (f) => relative(dir, f).split(sep).join('/');
+  for (const file of walk(dir).filter(
+    (f) => /\.(mdx?|json)$/.test(f) && !excluded.has(withinCollection(f)),
+  )) {
     const raw = readFileSync(file, 'utf8');
-    const match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+    let match = null;
+    if (/\.json$/.test(file)) {
+      match = ['', raw];
+    } else {
+      match = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+    }
     if (!match) continue;
     try {
-      for (const p of dataPaths(parse(match[1]) ?? {})) out.add(p);
+      const data = (/\.json$/.test(file) ? JSON.parse(match[1]) : parse(match[1])) ?? {};
+      /* With `fields`, report only what the schema cannot round-trip — walked
+         per file so a block variant is matched to itself. Without it, fall
+         back to every path, which is what the callers that only want values
+         expect. */
+      for (const p of fields ? undeclaredPaths(data, fields) : dataPaths(data)) out.add(p);
+      pathValues(data, '', values);
     } catch {
       /* A collection item with unparseable frontmatter is the content
          collection's problem, and astro check reports it properly. */
@@ -124,6 +299,10 @@ function collectionPaths(dir) {
   return out;
 }
 
+/** The extensions a content collection item can have — the same set the
+    collection walker filters on, kept here so the two cannot disagree. */
+const CONTENT_EXT = /\.(mdx?|json)$/;
+
 const rel = (p) => relative(process.cwd(), p).split(sep).join('/');
 
 /* ── content entries ─────────────────────────────────────────────────────── */
@@ -146,13 +325,67 @@ for (const entry of entries) {
     continue;
   }
 
+  /*
+   * ⚠ A COLLECTION WHOSE ITEMS ALL SIT ONE LEVEL DOWN.
+   *
+   *   `existsSync` is satisfied by the directory and the walk below recurses,
+   *   so a config left pointing at the PARENT of its content reports clean —
+   *   every file gets read and every key checked, but against an entry the
+   *   editor may not be seeing at all.
+   *
+   *   Measured on ngbif 2026-09-02: a locale migration moved six collections
+   *   into `en/` and `uz/` and nobody updated `.pages.yml`. This check caught
+   *   the two singletons, whose paths had genuinely vanished, and MISSED all
+   *   four collections — two of six real findings.
+   *
+   *   ⚠ A WARNING, NOT A PROBLEM, AND DELIBERATELY SO. Whether Pages CMS
+   *   lists a collection's subfolders is not something this script has
+   *   verified, and a guard that asserts unmeasured behaviour is how a check
+   *   earns a reputation for crying wolf. What IS certain is that the config
+   *   no longer has the shape the content does, and that a person should look
+   *   at it. Sites that legitimately nest will see this once and can add
+   *   `exclude` or split the entry.
+   */
+  if (entry.type === 'collection') {
+    const direct = readdirSync(path, { withFileTypes: true }).some(
+      (e) => e.isFile() && CONTENT_EXT.test(e.name),
+    );
+    if (!direct) {
+      const holders = readdirSync(path, { withFileTypes: true })
+        .filter((e) => e.isDirectory())
+        .filter((e) => {
+          try {
+            return readdirSync(join(path, e.name)).some((f) => CONTENT_EXT.test(f));
+          } catch {
+            return false;
+          }
+        })
+        .map((e) => `${e.name}/`);
+      if (holders.length) {
+        warnings.push(
+          `${label}: no content directly in ${path}, but ${holders.join(', ')} ` +
+            `underneath ${holders.length === 1 ? 'holds' : 'hold'} some — ` +
+            'usually a locale or structure move the config was not updated for. ' +
+            'Verify what the CMS actually lists; the fix is one entry per subdirectory.',
+        );
+      }
+    }
+  }
+
   const declared = schemaPaths(entry.fields);
 
   if (entry.type === 'collection') {
-    const used = collectionPaths(path);
-    const undeclared = [...used].filter((p) => !declared.has(p));
+    const values = new Map();
+    const undeclared = [...collectionPaths(path, values, entry.fields, entry.exclude)];
     if (undeclared.length) {
-      problems.push({ label, why: `frontmatter keys the schema does not declare`, keys: undeclared, path });
+      problems.push({
+        label,
+        why: `frontmatter keys the schema does not declare`,
+        keys: undeclared,
+        path,
+        values,
+        declared,
+      });
     }
     continue;
   }
@@ -165,9 +398,16 @@ for (const entry of entries) {
       problems.push({ label, why: `${path} is not valid JSON — ${err.message}` });
       continue;
     }
-    const undeclared = [...dataPaths(data)].filter((p) => !declared.has(p));
+    const undeclared = [...undeclaredPaths(data, entry.fields)];
     if (undeclared.length) {
-      problems.push({ label, why: 'keys in the file the schema does not declare', keys: undeclared, path });
+      problems.push({
+        label,
+        why: 'keys in the file the schema does not declare',
+        keys: undeclared,
+        path,
+        values: pathValues(data),
+        declared,
+      });
     }
   }
 }
@@ -184,6 +424,71 @@ const mediaByName = new Map();
    file dropped into generated output. */
 const GENERATED = ['public/img', 'dist', '.astro'];
 
+/*
+ * ⚠ POINTING A PICKER AT THE GENERATED OUTPUT IS NOT AUTOMATICALLY THE BUG,
+ *   AND THIS CHECK USED TO SAY IT WAS.
+ *
+ *   `src/lib/image-key.ts` exists in this very template BECAUSE a CMS picker
+ *   "browses files and returns the public path of what it found,
+ *   /img/photos/hero-1200.webp". That only happens when the media source's
+ *   input IS the output directory. So the check was telling people to break
+ *   the feature the kit ships to make image fields usable at all — follow it
+ *   and the picker returns /media/source/..., which `toImageKey` does not map,
+ *   and <Img> throws.
+ *
+ *   Measured on a delivered site with the mapping in place: 386 files under
+ *   public/img, 95 manifest keys, and ZERO files with no manifest entry after
+ *   months of use. The design holds.
+ *
+ * What the original trap was actually about is a project that CANNOT resolve a
+ * picked path — no mapping, so anything the editor chooses is unusable, and an
+ * upload into the output is unusable twice over. That is what this now reports.
+ *
+ * The residual risk where a mapping DOES exist — an editor uploading a raw
+ * JPEG that never gets processed — is covered by the `extensions` warning
+ * below, which is the lever that actually refuses it at the door.
+ */
+/*
+ * ⚠ AND THE DIRECTION CANNOT BITE AT ALL IF NOTHING STORES A PICKED PATH.
+ *
+ *   A third delivered site declares TWO media sources on purpose — "Image
+ *   library (published)" pointed at public/img so an editor can see what is
+ *   live, and "Originals (need `npm run media`)" pointed at media/source where
+ *   uploads belong. It has no `type: image` field at all: seven fields use a
+ *   `select` of manifest keys instead, so a picked path can never become a
+ *   field value.
+ *
+ *   The trap needs all three - a source pointed at generated output, a field
+ *   that can store what the picker returns, and nothing able to resolve it.
+ *   Miss any one and this reports a design somebody thought harder about than
+ *   the check did.
+ */
+const declaresImageFields = (() => {
+  const walk = (fields) =>
+    (fields ?? []).some((f) => {
+      if (!f?.name) return false;
+      const effective = f.type ?? (config.components ?? {})[f.component]?.type;
+      if (effective === 'image') return true;
+      return walk(f.fields ?? (config.components ?? {})[f.component]?.fields);
+    });
+  return entries.some((e) => walk(e?.fields));
+})();
+
+const resolvesPickerPaths = (() => {
+  if (existsSync(join('src', 'lib', 'image-key.ts'))) return true;
+  try {
+    const walk = (d) =>
+      readdirSync(d, { withFileTypes: true }).flatMap((e) =>
+        e.isDirectory() ? walk(join(d, e.name)) : [join(d, e.name)],
+      );
+    return walk('src')
+      .filter((f) => /\.(ts|js|mjs|astro)$/.test(f))
+      .some((f) => readFileSync(f, 'utf8').includes('toImageKey'));
+  } catch {
+    return false;
+  }
+})();
+
 const media = config.media ? (Array.isArray(config.media) ? config.media : [config.media]) : [];
 
 for (const source of media) {
@@ -196,14 +501,19 @@ for (const source of media) {
   if (typeof source === 'object' && source.name) mediaByName.set(source.name, source);
   const normalised = input.replace(/^\.?\//, '').replace(/\/$/, '');
   if (GENERATED.some((g) => normalised === g || normalised.startsWith(`${g}/`))) {
-    problems.push({
-      label: `media ${name}`,
-      why: `uploads into ${input}, which is GENERATED output`,
-      direction: true,
-    });
-    continue;
-  }
-  if (!existsSync(input)) {
+    if (declaresImageFields && !resolvesPickerPaths) {
+      problems.push({
+        label: `media ${name}`,
+        why:
+          `uploads into ${input}, which is GENERATED output. A \`type: image\` field stores ` +
+          `what the picker returns and nothing here maps that path back to a manifest key`,
+        direction: true,
+      });
+      continue;
+    }
+    /* Mapping present: browsing the output is the intended design. The upload
+       risk is the `extensions` question, checked below like any other source. */
+  } else if (!existsSync(input)) {
     problems.push({ label: `media ${name}`, why: `input directory does not exist: ${input}` });
     continue;
   }
@@ -237,13 +547,28 @@ for (const source of media) {
  *   with that media source's `output`. Convert the field and migrate the data
  *   in the same change.
  */
+/** Dotted field path → the `options.path` it is scoped to, when it declares one. */
+const scopedPaths = new Map();
+
 function imageFields(fields, prefix = '') {
   const out = [];
   for (const field of fields ?? []) {
     if (!field?.name) continue;
     const path = prefix ? `${prefix}.${field.name}` : field.name;
-    if (field.type === 'image') out.push({ path, media: field.options?.media });
-    if (Array.isArray(field.fields)) out.push(...imageFields(field.fields, path));
+    /* ⚠ RESOLVE THE COMPONENT FIRST. A picture field is very often a shared
+       `component: image_field`, and reading only `field.type` misses every
+       one of them — so the check that catches an unpickable path went quiet
+       on exactly the fields most likely to have one. Observed live: a home
+       page whose picture showed an empty square in the CMS and whose "View on
+       GitHub" link 404'd, while this check reported the page clean. */
+    const effectiveType =
+      field.type ?? (config.components ?? {})[field.component]?.type;
+    if (effectiveType === 'image') {
+      out.push({ path, media: field.options?.media });
+      if (field.options?.path) scopedPaths.set(path, String(field.options.path).replace(/^\.?\//, ''));
+    }
+    const sub = fieldsOf(field);
+    if (sub) out.push(...imageFields(sub, path));
   }
   return out;
 }
@@ -270,13 +595,20 @@ for (const entry of entries) {
         const full = join(d, e);
         return statSync(full).isDirectory() ? walk(full) : [full];
       });
-    for (const file of walk(entry.path).filter((f) => /\.mdx?$/.test(f))) {
-      const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(readFileSync(file, 'utf8'));
-      if (!m) continue;
+    /* JSON items count too — see the note on `collectionPaths`. Filtering to
+       markdown here meant image fields in a JSON collection were never
+       type-checked at all. */
+    for (const file of walk(entry.path).filter((f) => /\.(mdx?|json)$/.test(f))) {
+      const raw = readFileSync(file, 'utf8');
       try {
-        documents.push({ where: rel(file), data: parse(m[1]) ?? {} });
+        if (/\.json$/.test(file)) {
+          documents.push({ where: rel(file), data: JSON.parse(raw) ?? {} });
+        } else {
+          const m = /^---\r?\n([\s\S]*?)\r?\n---/.exec(raw);
+          if (m) documents.push({ where: rel(file), data: parse(m[1]) ?? {} });
+        }
       } catch {
-        /* astro check reports unparseable frontmatter properly. */
+        /* astro check reports unparseable content properly. */
       }
     }
   } else if (/\.json$/.test(entry.path)) {
@@ -290,7 +622,26 @@ for (const entry of entries) {
   for (const { path: fieldPath, media: mediaName } of fields) {
     const source =
       (mediaName && mediaByName.get(mediaName)) ?? (media.length === 1 ? media[0] : null);
-    const output = typeof source === 'object' ? source?.output : null;
+
+    /*
+     * ⚠ A PICKER SCOPED TO A FOLDER THAT DOES NOT EXIST OPENS ON NOTHING.
+     *   `options.path` narrows which directory the media browser shows. Point it
+     *   at `public/img/brand` when the files live in `brand-v2/` and the editor
+     *   gets an empty folder — no error, no warning, and the build does not
+     *   care. It is visible only to the person trying to choose an image, which
+     *   is the one person who cannot fix it.
+     */
+    if (fieldPath && typeof entry.fields === 'object') {
+      const scoped = scopedPaths.get(fieldPath);
+      if (scoped && !existsSync(scoped)) {
+        problems.push({
+          label: `${entry.name ?? entry.label} → ${fieldPath}`,
+          why: `\`options.path\` is ${JSON.stringify(scoped)}, which does not exist — the picker opens on an empty folder`,
+        });
+      }
+    }
+
+  const output = typeof source === 'object' ? source?.output : null;
     if (!output) continue; // nothing declared to measure against
     /* `output: /` makes "starts with the output" true of every absolute path, so
        it only distinguishes a path from a non-path. Still worth reporting — a
@@ -321,8 +672,167 @@ for (const entry of entries) {
       });
     }
   }
+
+  /*
+   * ⚠ A BLANK IMAGE SLOT THE CMS WROTE, WHICH BREAKS THE BUILD ON SAVE.
+   *
+   *   PagesCMS writes an object for every declared object field whether or not
+   *   the editor filled it in. A picture left empty therefore arrives as
+   *   `{ "isRender": false }` — the boolean has a default, the required
+   *   strings do not — and that is NOT a missing optional. It is a present
+   *   object failing validation, so `.optional()` on the schema does not save
+   *   you.
+   *
+   *   Observed: the first save by a non-developer broke a production deploy
+   *   this way, and the client saw only a failed build in a log they cannot
+   *   read. It is the single most likely way a CMS commit takes a site down.
+   *
+   *   The durable fix is in the SCHEMA, not here — strip a src-less object
+   *   before validating:
+   *
+   *     z.preprocess(
+   *       (v) => (v && typeof v === 'object' && !('src' in v) ? undefined : v),
+   *       imageObject.optional(),
+   *     )
+   *
+   *   This reports the state so it is caught before the deploy rather than by
+   *   the client.
+   */
+  for (const { path: fieldPath } of fields) {
+    if (!fieldPath.includes('.')) continue; // a bare image field has no wrapper
+    const parts = fieldPath.split('.');
+    const key = parts.pop();
+    const blanks = [];
+    for (const doc of documents) {
+      for (const parent of valuesAt(doc.data, parts)) {
+        if (!parent || typeof parent !== 'object' || Array.isArray(parent)) continue;
+        if (key in parent) continue;
+        /*
+         * ⚠ AN OMITTED OPTIONAL FIELD LOOKS EXACTLY LIKE A BLANK SLOT, AND
+         *   REPORTING IT IS THIS CHECK'S WHOLE FALSE-POSITIVE CLASS.
+         *
+         *   Caught on a delivered site: a video list where the first item is
+         *   `{ src: 'a-video.mp4' }` and the others also carry a `poster`. The
+         *   poster is `.optional()` in the content schema, the page does
+         *   `poster: v.poster ?? d.image`, and the component guards on it.
+         *   Nothing is wrong, and this reported two problems on a clean site.
+         *
+         *   What the check is actually for is the object the CMS WROTE with
+         *   nothing in it - `{ isRender: false }`, where the boolean has a
+         *   default and every string is absent. The signal that separates
+         *   them is whether the object carries any real string at all: a
+         *   blank slot carries none, an author's omission carries the rest of
+         *   the record.
+         */
+        const substance = Object.values(parent).some(
+          (v) => typeof v === 'string' && v.trim() !== '',
+        );
+        if (substance) continue;
+        blanks.push(doc.where);
+      }
+    }
+    if (blanks.length) {
+      problems.push({
+        label: `${entry.name ?? entry.label} → ${parts.join('.')}`,
+        why:
+          `is an image slot the CMS filled in PARTIALLY — the object exists but has no \`${key}\`, ` +
+          `so it is a present object that fails validation rather than a missing optional. ` +
+          `${blanks.length} file(s), e.g. ${blanks[0]}`,
+      });
+    }
+  }
+}
+
+/* ── a select of manifest keys, against the manifest ─────────────────────── */
+
+/*
+ * ⚠ A HAND-MAINTAINED LIST OF IMAGE KEYS DRIFTS, AND BOTH DIRECTIONS HURT.
+ *
+ *   Where a project has no way to map a picked path back to a manifest key,
+ *   the workable alternative is a `select` of the keys themselves. A delivered
+ *   site does exactly that: 110 photograph keys and 9 blog keys written out in
+ *   `.pages.yml`. Its own comment states the hazard:
+ *
+ *     "a key missing here simply cannot be chosen, and a key here that the
+ *      manifest lost will fail the build the moment it is selected"
+ *
+ *   That is a promise a person has to keep every time `npm run media` runs. It
+ *   was being kept - 110 and 9, nothing dead, nothing unlisted - and nothing
+ *   was enforcing it.
+ *
+ * A key OFFERED that the manifest lacks is a problem: choosing it is an
+ * ordinary editorial action that turns the build red. A key the manifest HAS
+ * that the list omits is a warning, because which images belong in a given
+ * field is a judgement - a blog header list is right to exclude the team
+ * photographs.
+ *
+ * ⚠ ONLY LISTS THAT ARE ALREADY KEY LISTS. A select of "texas, nevada,
+ *   arizona" is not a broken image list, and saying so would be noise on every
+ *   project. A list qualifies only when one of its values is a real manifest
+ *   key, and the unlisted half is scoped to prefixes the list already uses, so
+ *   a blog list is measured against `blog/` and never against every photograph
+ *   on the site.
+ */
+{
+  const manifestFile = ['src/data/image-manifest.json', 'src/data/media-manifest.json'].find(existsSync);
+  let keys = null;
+  if (manifestFile) {
+    try {
+      keys = new Set(Object.keys(JSON.parse(readFileSync(manifestFile, 'utf8'))));
+    } catch {
+      /* A malformed manifest is the media pipeline's problem, not this one. */
+    }
+  }
+
+  if (keys?.size) {
+    /* PagesCMS accepts a bare string or `{ name, label }`. */
+    const valueOf = (v) => (typeof v === 'string' ? v : (v?.name ?? v?.value));
+
+    const selects = [];
+    for (const [name, def] of Object.entries(config.components ?? {})) {
+      if (def?.type === 'select') selects.push([`component ${name}`, def]);
+    }
+    const collect = (fields, where) => {
+      for (const f of fields ?? []) {
+        if (!f?.name) continue;
+        if (f.type === 'select') selects.push([`${where} → ${f.name}`, f]);
+        collect(f.fields, where);
+      }
+    };
+    for (const entry of entries) collect(entry?.fields, entry?.name ?? entry?.label ?? '?');
+
+    for (const [label, def] of selects) {
+      const values = (def.options?.values ?? []).map(valueOf).filter((v) => typeof v === 'string');
+      if (!values.some((v) => keys.has(v))) continue; // not a key list
+
+      const dead = values.filter((v) => !keys.has(v));
+      if (dead.length) {
+        problems.push({
+          label,
+          why:
+            `offers ${dead.length} image key(s) the manifest does not have - choosing one fails ` +
+            `the build: ${dead.slice(0, 4).map((d) => JSON.stringify(d)).join(', ')}` +
+            (dead.length > 4 ? `, and ${dead.length - 4} more` : ''),
+        });
+      }
+
+      const prefixes = new Set(values.map((v) => v.slice(0, v.lastIndexOf('/') + 1)).filter(Boolean));
+      const unlisted = [...keys].filter(
+        (k) => !values.includes(k) && [...prefixes].some((pre) => k.startsWith(pre)),
+      );
+      if (unlisted.length) {
+        warnings.push(
+          `"${label}" omits ${unlisted.length} image(s) the manifest has, so the editor cannot ` +
+            `choose them: ${unlisted.slice(0, 5).join(', ')}${unlisted.length > 5 ? ', …' : ''}\n` +
+            `      A hand-written list goes stale the next time \`npm run media\` adds an image. ` +
+            `Either add them, or write down why the list is curated.`,
+        );
+      }
+    }
+  }
 }
 
+
 /* ── internal links a client can type ────────────────────────────────────── */
 
 /*
@@ -518,6 +1028,35 @@ if (literals.length) {
   );
 }
 
+/*
+ * ⚠ AND THE SAME FAILURE ONE LEVEL IN: THE COPY ITSELF.
+ *
+ *   A page whose content is a `const` array in its own frontmatter renders
+ *   correctly, types correctly, and has no field anywhere. Measured across
+ *   seven delivered sites that all had a working CMS the client was using:
+ *   nine such blocks on three of them, including a twelve-item FAQ about
+ *   post-operative medication and a page of seven treatments with their
+ *   patient-facing copy.
+ *
+ *   A warning for the same reason as the images above — an inline list is
+ *   sometimes right. It must be a decision, not an oversight.
+ */
+const inline = literalContent();
+if (inline.length) {
+  const strings = inline.reduce((n, b) => n + b.strings, 0);
+  warnings.push(
+    `${inline.length} block(s) of page copy declared inline, holding ${strings} sentence(s) ` +
+      `the CMS cannot reach:\n` +
+      inline
+        .slice(0, 8)
+        .map((b) => `      ${b.file}  ${b.name}[${b.items}]  ${b.strings} sentences  "${b.sample}…"`)
+        .join('\n') +
+      (inline.length > 8 ? `\n      …and ${inline.length - 8} more` : '') +
+      `\n      This is what "required sections cannot be edited" looks like in the source. ` +
+      `Each block is either deliberately fixed or a page the client cannot touch.`,
+  );
+}
+
 /*
  * ⚠ A SECRET IN A CMS IS A SECRET THE CLIENT CAN READ AND CHANGE. Analytics
  *   IDs, tokens and keys are technical configuration: their failure mode is
@@ -548,6 +1087,122 @@ if (!problems.length) {
   process.exit(0);
 }
 
+/*
+ * ── The field declarations to paste, built from the data itself ────────────
+ *
+ * ⚠ THE TYPE COMES FROM THE VALUE, NOT FROM THE NAME. `openingHours` is an
+ *   array of objects on one site and a string on another, and guessing from
+ *   the key is how a generator produces confident nonsense. Every type below
+ *   is read off the value actually sitting at that path.
+ *
+ * PagesCMS spells a repeated field `list: true` on the field itself rather
+ * than as a distinct type, so an array becomes its element's type plus that
+ * flag. An empty array cannot say what it holds, and is emitted as a string
+ * list with a comment rather than silently picking one.
+ */
+function fieldType(value) {
+  if (Array.isArray(value)) {
+    const sample = value.find((v) => v != null);
+    if (sample === undefined) return { type: 'string', list: true, unknown: true };
+    return { ...fieldType(sample), list: true };
+  }
+  if (value === null) return { type: 'string', unknown: true };
+  if (typeof value === 'number') return { type: 'number' };
+  if (typeof value === 'boolean') return { type: 'boolean' };
+  if (typeof value === 'object') return { type: 'object' };
+  /* A long string is a textarea; a short one is an input. The threshold is the
+     point past which a single-line box stops being usable, not a rule. */
+  return { type: String(value).length > 80 ? 'text' : 'string' };
+}
+
+/** Nest a flat list of dotted paths back into a tree. */
+function tree(paths) {
+  const root = new Map();
+  for (const path of paths) {
+    let node = root;
+    for (const part of path.split('.')) {
+      if (!node.has(part)) node.set(part, new Map());
+      node = node.get(part);
+    }
+  }
+  return root;
+}
+
+function emitFields(node, values, prefix, indent) {
+  const pad = ' '.repeat(indent);
+  const lines = [];
+  for (const [name, children] of node) {
+    const path = prefix ? `${prefix}.${name}` : name;
+    const { type, list, unknown } = fieldType(values.get(path));
+    const note = unknown ? '   # value was null or empty — check this one' : '';
+    if (children.size) {
+      lines.push(`${pad}- name: ${name}`);
+      lines.push(`${pad}  type: object`);
+      if (list) lines.push(`${pad}  list: true`);
+      lines.push(`${pad}  fields:`);
+      lines.push(...emitFields(children, values, path, indent + 4));
+    } else if (list) {
+      lines.push(`${pad}- name: ${name}`);
+      lines.push(`${pad}  type: ${type}`);
+      lines.push(`${pad}  list: true${note}`);
+    } else {
+      lines.push(`${pad}- { name: ${name}, type: ${type} }${note}`);
+    }
+  }
+  return lines;
+}
+
+/**
+ * The fix for one undeclared-keys problem, as lines to print.
+ *
+ * ⚠ A KEY WHOSE PARENT IS ALREADY DECLARED CANNOT BE PASTED AT THE TOP LEVEL.
+ *   `analytics` declared and `analytics.gtmId` missing means the field exists
+ *   and its `fields:` is short — emitting a second `analytics` field would
+ *   give the editor two screens for one object. Those are reported separately,
+ *   naming the field to open.
+ */
+function fixFor(problem) {
+  const { keys, values, declared, label, path } = problem;
+  const roots = [];
+  const nested = new Map();
+
+  for (const key of keys) {
+    const parent = key.slice(0, key.lastIndexOf('.'));
+    if (key.includes('.') && declared.has(parent)) {
+      if (!nested.has(parent)) nested.set(parent, []);
+      nested.get(parent).push(key);
+    } else if (!keys.some((k) => k !== key && key.startsWith(`${k}.`))) {
+      roots.push(key);
+    }
+  }
+
+  const out = [];
+  if (roots.length) {
+    const own = keys.filter((k) => roots.some((r) => k === r || k.startsWith(`${r}.`)));
+    out.push(`      ${DIM}── paste into \`fields:\` for \`${label}\` ${'─'.repeat(30)}${RESET}`);
+    out.push(...emitFields(tree(own), values, '', 6).map((l) => `${DIM}${l}${RESET}`));
+  }
+  for (const [parent, children] of nested) {
+    out.push('');
+    out.push(`      ${DIM}── add under the existing \`${parent}\` field's \`fields:\` ──${RESET}`);
+    const relative_ = children.map((c) => c.slice(parent.length + 1));
+    const scoped = new Map(children.map((c) => [c.slice(parent.length + 1), values.get(c)]));
+    out.push(...emitFields(tree(relative_), scoped, '', 6).map((l) => `${DIM}${l}${RESET}`));
+  }
+
+  const risky = keys.filter((k) => SECRET_SHAPED.test(k));
+  if (risky.length) {
+    out.push('');
+    out.push(
+      `      ${YELLOW}⚠${RESET} ${DIM}${risky.slice(0, 4).join(', ')}${risky.length > 4 ? ', …' : ''} ` +
+        `look like technical configuration.\n` +
+        `        Moving them OUT of ${rel(path)} is usually the better fix — a client\n` +
+        `        cannot diagnose what breaks when one is changed, and it fails silently.${RESET}`,
+    );
+  }
+  return out;
+}
+
 console.error(`\n${RED}✗ ${problems.length} problem(s) in ${CONFIG}${RESET}\n`);
 
 for (const p of problems) {
@@ -560,6 +1215,17 @@ for (const p of problems) {
         `      save from this screen DELETES them. Declare every key — including ones\n` +
         `      the client will never touch — or move them out of a CMS-managed file.${RESET}`,
     );
+    if (!SHOW_FIX) {
+      console.error(
+        `      ${DIM}Run \`npm run check:cms -- --fix\` to print the field declarations\n` +
+          `      to paste, with each type read off the value actually stored there.${RESET}`,
+      );
+    }
+    if (SHOW_FIX) {
+      console.error('');
+      for (const line of fixFor(p)) console.error(line);
+      console.error('');
+    }
   }
   if (p.links) {
     for (const l of p.links.slice(0, 8)) {