Frontmatter quote errors, case-sensitive link check, one id rule

- An unterminated quoted scalar or list item is reported with its line
  instead of being accepted with the opening quote kept (Closes #138)
- Relative links whose case differs from the file on disk are reported by
  validate and refused by the build's link resolver, so a link that works
  on Windows or macOS cannot pass locally and fail in CI (Closes #139)
- ID_RE lives in site/lib/entry-files.mjs with idMatchesFile; validate,
  scaffold and the thumbnail manifest check import it, and build.mjs and
  thumbs.mjs refuse to build a page or file path from an id that does not
  match its file name (Closes #135)

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: TMHSDigital

site/build.mjs

@@ -19,9 +19,9 @@ import { filmstripHtml, groupedEntriesHtml } from "./lib/cards.mjs";
 import { categoryPageHtml } from "./lib/category-page.mjs";
 import { filmstripPick, isAttributionLicence, previewCredit, thumbRelPath } from "./lib/thumbs.mjs";
 import { parseFrontmatter, summaryFromBody } from "./lib/frontmatter.mjs";
-import { listEntryFiles } from "./lib/entry-files.mjs";
+import { listEntryFiles, idMatchesFile } from "./lib/entry-files.mjs";
 import { entryPageHtml, scriptJson } from "./lib/entry-page.mjs";
-import { LinkError, makeLinkResolver } from "./lib/links.mjs";
+import { LinkError, makeLinkResolver, caseMismatch } from "./lib/links.mjs";
 import { atomFeed, catalogCsv, homeJsonLd, sitemapXml } from "./lib/exports.mjs";
 import { llmsFullTxt, llmsTxt } from "./lib/llms.mjs";
 import { deprecationReason, MarkdownError, renderBlocks, renderInline, splitEntryBody } from "./lib/markdown.mjs";
@@ -97,6 +97,11 @@ function loadEntries(vocab) {
       errors.push(`duplicate id "${meta.id}": ${fileOfId.get(String(meta.id))} and ${rel}`);
       continue;
     }
+    // Page and thumbnail paths are built from the id; never from one that
+    // could leave dist (validate reports the same mismatch with a line).
+    if (!idMatchesFile(meta.id, rel)) {
+      throw new Error(`${rel}: id "${meta.id}" must be short kebab-case and match the file name (node site/validate.mjs explains)`);
+    }
     fileOfId.set(String(meta.id), rel);
     bodies.set(String(meta.id), body);
 
@@ -340,9 +345,12 @@ function pruneDist(dir = DIST, prefix = "") {
 /** Returns file => link resolver for links in that file's body (`file.path` is repo-relative). */
 function linkResolvers(entries, config, entryBase = "../") {
   const idByPath = new Map(entries.map((e) => [e.path, e.id]));
+  const realRoot = fs.realpathSync.native(ROOT);
   const kindOf = (repoPath) => {
     const full = path.join(ROOT, repoPath);
     if (!fs.existsSync(full)) return null;
+    // A wrong-case link resolves here on Windows and macOS but not on Linux.
+    if (caseMismatch(repoPath, path.relative(realRoot, fs.realpathSync.native(full)))) return null;
     return fs.statSync(full).isDirectory() ? "dir" : "file";
   };
   return (file) => makeLinkResolver({ entryPath: file.path, idByPath, repo: config.site.repo, kindOf, entryBase });

site/checks.mjs

@@ -7,6 +7,7 @@
  */
 
 import path from "node:path";
+import { ID_RE } from "./lib/entry-files.mjs";
 import { evidenceSection } from "./lib/frontmatter.mjs";
 import { isRealDate } from "./lib/shared.mjs";
 import { previewEligibility } from "./lib/thumbs.mjs";
@@ -803,13 +804,13 @@ export function checkThumbManifest(manifest, entriesById, files) {
   const thumbs = (manifest && manifest.thumbs) || {};
   const fileIds = new Set();
   for (const name of files) {
-    const m = name.match(/^([a-z0-9]+(?:-[a-z0-9]+)*)\.webp$/);
-    if (!m) {
+    const id = name.endsWith(".webp") ? name.slice(0, -".webp".length) : "";
+    if (!ID_RE.test(id)) {
       errors.push(`site/public/thumbs/${name} is not a <id>.webp thumbnail`);
       continue;
     }
-    fileIds.add(m[1]);
-    if (!thumbs[m[1]]) errors.push(`site/public/thumbs/${name} has no record in site/thumbs.json`);
+    fileIds.add(id);
+    if (!thumbs[id]) errors.push(`site/public/thumbs/${name} has no record in site/thumbs.json`);
   }
   for (const [id, rec] of Object.entries(thumbs)) {
     if (!fileIds.has(id)) errors.push(`site/thumbs.json has "${id}" but site/public/thumbs/${id}.webp is missing`);

site/lib/entry-files.mjs

@@ -5,6 +5,18 @@
 import fs from "node:fs";
 import path from "node:path";
 
+/** A short kebab-case id: the only thing an entry's file name, page path and thumbnail name are built from. */
+export const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+
+/**
+ * True when `id` may be used as a path segment for `file`: it matches ID_RE
+ * and equals the file's base name. validate reports the mismatch; the other
+ * scripts refuse to build a path from anything else.
+ */
+export function idMatchesFile(id, file) {
+  return ID_RE.test(String(id)) && String(id) === path.basename(String(file), ".md");
+}
+
 /** Not entries: the category index and the copy-me template. */
 export const NON_ENTRY_MD = new Set(["README.md", "TEMPLATE.md"]);
 /** Never walked: hidden folders (any name starting ".") and local scratch. */

site/lib/frontmatter.mjs

@@ -66,6 +66,15 @@ function cutAtHash(raw, value) {
   return /\S\s+#\S/.test(raw) && typeof value === "string" && value !== "" && !/^["'[]/.test(raw.trim());
 }
 
+/** "double" or "single" when a scalar opens a quote it never closes, else null. */
+export function unclosedQuote(raw) {
+  const v = stripComment(raw).trim();
+  const q = v[0];
+  if (q !== '"' && q !== "'") return null;
+  if (v.length >= 2 && v.endsWith(q)) return null;
+  return q === '"' ? "double" : "single";
+}
+
 export function parseScalar(raw) {
   const v = stripComment(raw).trim();
   if (v === "true") return true;
@@ -103,7 +112,9 @@ export function parseFrontmatter(text) {
       if (listKey === null) errors.push(`line ${lineNo}: list item without a key above it`);
       else {
         const value = parseScalar(item[1]);
-        if (value === null) errors.push(`line ${lineNo}: list item is empty (a value starting with # is a comment; quote it)`);
+        const open = unclosedQuote(item[1]);
+        if (open) errors.push(`line ${lineNo}: list item opens a ${open} quote that is never closed`);
+        else if (value === null) errors.push(`line ${lineNo}: list item is empty (a value starting with # is a comment; quote it)`);
         else if (cutAtHash(item[1], value)) errors.push(`line ${lineNo}: list item is cut at " #" (read as a comment); quote the value if the # is part of it`);
         else meta[listKey].push(value);
       }
@@ -122,6 +133,8 @@ export function parseFrontmatter(text) {
     }
     const rawValue = line.slice(idx + 1);
     const value = parseScalar(rawValue);
+    const open = unclosedQuote(rawValue);
+    if (open) errors.push(`line ${lineNo}: "${key}" opens a ${open} quote that is never closed`);
     if (cutAtHash(rawValue, value)) {
       errors.push(`line ${lineNo}: "${key}" is cut at " #" (read as a comment); quote the value if the # is part of it`);
     }

site/lib/lib.test.mjs

@@ -103,10 +103,15 @@ eq("sectionMarkdown missing", sectionMarkdown(body, "Nope"), null);
 eq("deprecationReason starts a sentence", deprecationReason(body), "Gone");
 
 /* links -------------------------------------------------------------------- */
-import { makeLinkResolver } from "./links.mjs";
+import { makeLinkResolver, caseMismatch } from "./links.mjs";
 const idByPath = new Map([["catalog/2d/kenney-ui-pack.md", "kenney-ui-pack"], ["catalog/audio/kenney-ui-audio.md", "kenney-ui-audio"]]);
 const files = new Map([["docs/provenance.md", "file"], ["catalog/2d/README.md", "file"], ["catalog/video", "dir"]]);
 const resolve = makeLinkResolver({ entryPath: "catalog/2d/kenney-ui-pack.md", idByPath, repo: "https://github.com/o/r", kindOf: (p) => files.get(p) || null });
+eq("links: case mismatch names the component", caseMismatch("docs/Licenses.md", "docs/licenses.md"), "Licenses.md vs licenses.md");
+eq("links: directory case counts", caseMismatch("Docs/a.md", "docs/a.md"), "Docs vs docs");
+eq("links: same path is not a mismatch", caseMismatch("docs/licenses.md", "docs\\licenses.md"), null);
+eq("links: a different file is not a case mismatch", caseMismatch("docs/a.md", "docs/b.md"), null);
+eq("links: a drive letter ends the comparison", caseMismatch("e:/r/docs/a.md", "E:/r/docs/a.md"), null);
 eq("sibling entry", resolve("kenney-ui-pack.md").href, "../kenney-ui-pack/");
 eq("entry in another category", resolve("../audio/kenney-ui-audio.md").href, "../kenney-ui-audio/");
 eq("entry link is internal", resolve("../audio/kenney-ui-audio.md").external, false);
@@ -557,6 +562,10 @@ has("empty recent window wording counts the build day", freshnessPageHtml({ stat
 import { evidenceSection, parseFrontmatter, plainText, summaryFromBody } from "./frontmatter.mjs";
 import { latestAllowedDate } from "./shared.mjs";
 const fm = (lines, body = "Body.\n") => parseFrontmatter(`---\n${lines.join("\n")}\n---\n${body}`);
+eq("frontmatter: unterminated double quote is an error", fm(['name: "Foo']).errors.some((e) => e === 'line 2: "name" opens a double quote that is never closed'), true);
+eq("frontmatter: unterminated single quote in a list item", fm(["tags:", "  - 'a"]).errors.some((e) => e === "line 3: list item opens a single quote that is never closed"), true);
+eq("frontmatter: closed quotes stay clean", fm(['name: "Foo"', "tags:", "  - 'a'"]).errors.length, 0);
+eq("frontmatter: a lone quote character is unterminated", fm(['name: "']).errors.length, 1);
 const f1 = fm([
   "id: a",
   'attribution_string: "Music \\"{title}\\" by {artist}"',

site/lib/links.mjs

@@ -4,6 +4,27 @@ import { ANY_SCHEME_RE, EXTERNAL_SCHEME_RE } from "./shared.mjs";
 
 export class LinkError extends Error {}
 
+/**
+ * The path component whose case differs between a link target and the file
+ * on disk, as "linked vs on disk", or null. Windows and macOS resolve
+ * `Docs/Foo.md` to `docs/foo.md`; Linux, where CI runs, does not. Compared
+ * from the file name backwards; a component that differs in more than case
+ * (a symlink, a drive letter) ends the comparison.
+ */
+export function caseMismatch(linked, onDisk) {
+  const a = String(linked).split(/[\\/]+/).filter(Boolean);
+  const b = String(onDisk).split(/[\\/]+/).filter(Boolean);
+  const n = Math.min(a.length, b.length);
+  for (let i = 1; i <= n; i += 1) {
+    const x = a[a.length - i];
+    const y = b[b.length - i];
+    if (x === y) continue;
+    if (x.endsWith(":") || y.endsWith(":")) return null;
+    return x.toLowerCase() === y.toLowerCase() ? `${x} vs ${y}` : null;
+  }
+  return null;
+}
+
 export function makeLinkResolver({ entryPath, idByPath, repo, kindOf, entryBase = "../" }) {
   const dir = path.posix.dirname(entryPath);
   return (raw) => {

site/lib/scaffold.mjs

@@ -27,7 +27,8 @@ export const syncCatalogReadme = (text, counts) => syncTable(text, counts, "`CAT
 
 export const syncConfig = (text, total) => text.replace(/("expectedEntryCount":\s*)\d+/, `$1${total}`);
 
-export const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+import { ID_RE } from "./entry-files.mjs";
+export { ID_RE };
 
 /** Why new-entry must refuse these arguments, or null. `taken` is the category already holding the id, if any. */
 export function newEntryProblem({ category, id, categories, taken }) {

site/thumbs.mjs

@@ -17,7 +17,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { listEntryFiles } from "./lib/entry-files.mjs";
+import { listEntryFiles, idMatchesFile } from "./lib/entry-files.mjs";
 import { parseFrontmatter } from "./lib/frontmatter.mjs";
 import { imageUrlFromHtml, needsFetch, previewEligibility, sharedImageIds, webpSize } from "./lib/thumbs.mjs";
 
@@ -49,7 +49,7 @@ function loadEntries() {
   const out = [];
   for (const file of listEntryFiles(CATALOG)) {
     const parsed = parseFrontmatter(fs.readFileSync(file, "utf8"));
-    if (!parsed || parsed.errors.length || !parsed.meta.id) continue;
+    if (!parsed || parsed.errors.length || !idMatchesFile(parsed.meta.id, file)) continue;
     const m = parsed.meta;
     out.push({
       id: String(m.id),

site/validate.mjs

@@ -3,6 +3,7 @@
  * Catalog integrity checks. Run before every commit: node site/validate.mjs
  */
 import fs from "node:fs";
+import { caseMismatch } from "./lib/links.mjs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import {
@@ -37,11 +38,12 @@ import {
 } from "./checks.mjs";
 import { evidenceSection, parseFrontmatter } from "./lib/frontmatter.mjs";
 import { ANY_SCHEME_RE, EXTERNAL_SCHEME_RE, isRealDate, latestAllowedDate } from "./lib/shared.mjs";
-import { listEntryFiles } from "./lib/entry-files.mjs";
+import { listEntryFiles, ID_RE } from "./lib/entry-files.mjs";
 import { licenceTerms, listStackFiles } from "./lib/stacks.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, "..");
+const REAL_ROOT = fs.realpathSync.native(ROOT);
 const CATALOG = path.join(ROOT, "catalog");
 const CONFIG_PATH = path.join(__dirname, "config.json");
 const SPDX_ALLOWED_PATH = path.join(__dirname, "spdx-allowed.json");
@@ -64,7 +66,6 @@ const REQUIRED = [
   "verified",
   "status",
 ];
-const ID_RE = /^[a-z0-9]+(-[a-z0-9]+)*$/;
 // C0 controls other than tab, LF and CR: invalid in XML, and NUL is the
 // markdown renderer's slot marker.
 const CONTROL_RE = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/;
@@ -189,6 +190,12 @@ function checkRelativeLinks(file, errors) {
       errors.push(`${relFromRoot(file)} broken link: ${href}`);
       continue;
     }
+    // Case-insensitive filesystems accept a wrong-case link that CI (Linux) will not.
+    const mismatch = caseMismatch(path.relative(ROOT, resolved), path.relative(REAL_ROOT, fs.realpathSync.native(resolved)));
+    if (mismatch) {
+      errors.push(`${relFromRoot(file)} broken link: ${href} (case differs on disk: ${mismatch}; CI is case-sensitive)`);
+      continue;
+    }
     // A fragment into a Markdown file must name one of its headings.
     if (fragment && resolved.endsWith(".md") && fs.statSync(resolved).isFile()) {
       let id = fragment;