create-ailk 0.31.0 → 0.33.0

package/templates/tools/body-heading.ts

@@ -0,0 +1,440 @@
+/**
+ * The page body owns its H1 (#7495, spec docs/specs/7495-the-page-body-owns-its-spec.md
+ * D3–D5, D8): on a page `apps/web` renders in `bodyMode: "mdx-body"`, the one
+ * `<h1>` a reader sees is the body's `# ` heading — renderPage prints nothing
+ * from frontmatter `title` or `description` there.
+ *
+ * This module is the one owner of that rule, used by `create-ailk update`
+ * (the consumer's migration), `tools/content-compile` (the content check)
+ * and the tests:
+ *
+ * - which pages are mdx-body — read from the site's own `apps/web` routes,
+ *   always or only when frontmatter `sections[]` is empty (`mdxBodyRule`,
+ *   `isMdxBodyPage`);
+ * - how many `# ` headings a body has (`countBodyHeadings`);
+ * - the codemod that gives a page with none `# <title>` and its description
+ *   paragraph (`addBodyHeading`, `planBodyHeadings`, `migrateBodyHeadings`).
+ *   A page with one or more headings is never written;
+ * - the mdx-body pages of a content tree, with their bodies (`mdxBodyPages`),
+ *   which the bare-brace pass and check read (#10773).
+ *
+ * Frontmatter is read with a dependency-free subset of YAML for the three
+ * keys it needs — `create-ailk` ships exactly one runtime dependency (`tar`),
+ * the `design-package.ts` posture — and any form the subset does not cover
+ * is refused, never guessed at. No relative imports: `tools/` imports this
+ * file from source.
+ */
+import { existsSync, lstatSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Per content type: mdx-body always, or only while `sections[]` is empty. */
+export type MdxBodyRule = Map<string, "always" | "unless-sections">;
+
+// The `renderPage({ … })` discovery regexes of `tools/lint-mdx-body-compiles.ts`.
+const RENDER_PAGE_CALL_RE = /renderPage\s*\(\s*\{[\s\S]*?\}\s*\)/g;
+const TYPE_RE = /type\s*:\s*["']([A-Za-z]+)["']/;
+const MDX_BODY_MODE_RE = /bodyMode\s*:\s*["']mdx-body["']/;
+// `...(composed ? {} : { bodyMode: "mdx-body" … })` — the routes' sections test.
+const CONDITIONAL_MDX_BODY_RE = /\?\s*\{\s*\}\s*:\s*\{[^}]*bodyMode\s*:\s*["']mdx-body["']/;
+// A content hub's `HubConfig` (#10121): `hubPageInput` sets `bodyMode` from
+// its `body` — `mdx-body` always, `composed` unless `sections[]` is non-empty.
+// A hub page holds one config, so its one `listType` and one `body` pair in
+// any order; a file with more of either is not read.
+const HUB_INPUT_RE = /\bhubPageInput\s*\(/;
+const HUB_LIST_TYPE_RE = /\blistType\s*:\s*["']([A-Za-z]+)["']/g;
+const HUB_BODY_RE = /\bbody\s*:\s*["'](mdx-body|composed|sections)["']/g;
+
+const LOCALE_RE = /^[a-z]{2}(-[A-Z]{2})?$/;
+const SKIPPED_DIRS = new Set(["node_modules", ".next", "dist"]);
+
+function pageFiles(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (SKIPPED_DIRS.has(entry.name)) continue;
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) pageFiles(path, out);
+    else if (entry.isFile() && (entry.name === "page.tsx" || entry.name === "page.ts")) out.push(path);
+  }
+  return out;
+}
+
+/**
+ * Scan `<appsRoot>/apps/web/app/**\/page.{ts,tsx}` for `renderPage({…})` calls
+ * naming `bodyMode: "mdx-body"`. A call whose `bodyMode` sits in a conditional
+ * spread is `"unless-sections"`, any other `"always"`; `"always"` wins when two
+ * routes name one type. A content hub's `HubConfig` reads the same way, from
+ * its `body`. A missing `apps/web/app` gives an empty map.
+ */
+export function mdxBodyRule(appsRoot: string): MdxBodyRule {
+  const rule: MdxBodyRule = new Map();
+  const appDir = join(appsRoot, "apps", "web", "app");
+  if (!existsSync(appDir)) return rule;
+  for (const file of pageFiles(appDir)) {
+    const source = readFileSync(file, "utf8");
+    if (HUB_INPUT_RE.test(source)) {
+      const types = [...source.matchAll(HUB_LIST_TYPE_RE)];
+      const bodies = [...source.matchAll(HUB_BODY_RE)];
+      if (types.length === 1 && bodies.length === 1) {
+        const type = types[0]![1]!;
+        const body = bodies[0]![1];
+        if (body === "mdx-body") rule.set(type, "always");
+        else if (body === "composed" && !rule.has(type)) rule.set(type, "unless-sections");
+      }
+    }
+    for (const call of source.matchAll(RENDER_PAGE_CALL_RE)) {
+      const block = call[0];
+      if (!MDX_BODY_MODE_RE.test(block)) continue;
+      const type = TYPE_RE.exec(block)?.[1];
+      if (type === undefined) continue;
+      if (CONDITIONAL_MDX_BODY_RE.test(block)) {
+        if (!rule.has(type)) rule.set(type, "unless-sections");
+      } else {
+        rule.set(type, "always");
+      }
+    }
+  }
+  return rule;
+}
+
+/** The routes' own `composed` test: mdx-body unless `sections` is a non-empty array. */
+export function isMdxBodyPage(
+  type: string,
+  frontmatter: Record<string, unknown>,
+  rule: MdxBodyRule,
+): boolean {
+  const mode = rule.get(type);
+  if (mode === "always") return true;
+  if (mode !== "unless-sections") return false;
+  const sections = frontmatter.sections;
+  return !(Array.isArray(sections) && sections.length > 0);
+}
+
+// ── The heading count (D4) ───────────────────────────────────────────────────
+
+const FENCE_RE = /^ {0,3}(`{3,}|~{3,})/;
+const ATX_H1_RE = /^ {0,3}# +\S/;
+
+/**
+ * ATX level-1 headings (`^ {0,3}# +\S`) outside fenced code blocks and
+ * multi-line `{/* … *\/}` comments. `##`, `#text` and Setext headings do not
+ * count. A fence closes, as in CommonMark, on a run of its own character at
+ * least as long as the opening one, with nothing after it.
+ */
+export function countBodyHeadings(body: string): number {
+  let fence: string | undefined;
+  let inComment = false;
+  let count = 0;
+  for (const line of body.split(/\r?\n/)) {
+    if (inComment) {
+      if (line.includes("*/}")) inComment = false;
+      continue;
+    }
+    const fenceMatch = FENCE_RE.exec(line);
+    if (fence !== undefined) {
+      const run = fenceMatch?.[1];
+      if (
+        run !== undefined &&
+        run[0] === fence[0] &&
+        run.length >= fence.length &&
+        line.slice(fenceMatch![0].length).trim() === ""
+      ) {
+        fence = undefined;
+      }
+      continue;
+    }
+    if (fenceMatch !== null) {
+      fence = fenceMatch[1];
+      continue;
+    }
+    if (ATX_H1_RE.test(line)) count += 1;
+    const open = line.lastIndexOf("{/*");
+    if (open !== -1 && !line.includes("*/", open + 3)) inComment = true;
+  }
+  return count;
+}
+
+// ── Frontmatter: split and the subset reader (D8) ───────────────────────────
+
+interface SplitPage {
+  /** Top-level frontmatter lines, between the first two `---` lines. */
+  frontmatter: string[];
+  /** Offset of the body: everything after the closing `---` line. */
+  bodyStart: number;
+}
+
+function splitPage(raw: string): SplitPage | undefined {
+  const open = /^\uFEFF?---[ \t]*\r?\n/.exec(raw);
+  if (open === null) return undefined;
+  const close = /^---[ \t]*(?:\r?\n|$)/m;
+  const rest = raw.slice(open[0].length);
+  const match = close.exec(rest);
+  if (match === null) return undefined;
+  return {
+    frontmatter: rest.slice(0, match.index).split(/\r?\n/),
+    bodyStart: open[0].length + match.index + match[0].length,
+  };
+}
+
+class Refused extends Error {}
+
+const refusedKey = (key: string): Refused =>
+  new Refused(`frontmatter the subset reader does not read: ${key}`);
+
+/** The value after `<key>:` on its top-level line, and the lines after it. */
+function topLevel(lines: string[], key: string): { value: string; next: string[] } | undefined {
+  const prefix = `${key}:`;
+  const index = lines.findIndex((line) => line.startsWith(prefix));
+  if (index === -1) return undefined;
+  return { value: lines[index]!.slice(prefix.length).trim(), next: lines.slice(index + 1) };
+}
+
+const nextNonBlank = (lines: string[]): string | undefined =>
+  lines.find((line) => line.trim() !== "");
+
+/** The key's value goes on below it: its next non-blank line is indented. */
+const continues = (next: string[]): boolean => /^[ \t]/.test(nextNonBlank(next) ?? "");
+
+const YAML_INDICATOR_RE = /^[-?:,[\]{}#&*!|>'"%@`]/;
+
+/** A single-line plain or double-quoted scalar; `""` for an absent or empty key. */
+function readScalar(lines: string[], key: string): string {
+  const entry = topLevel(lines, key);
+  if (entry === undefined) return "";
+  const { value, next } = entry;
+  if (continues(next)) throw refusedKey(key);
+  if (value === "") return "";
+  if (value.startsWith('"')) {
+    try {
+      const decoded: unknown = JSON.parse(value);
+      if (typeof decoded === "string") return decoded;
+    } catch {
+      // refused below
+    }
+    throw refusedKey(key);
+  }
+  if (YAML_INDICATOR_RE.test(value) || /\s#/.test(value)) throw refusedKey(key);
+  return value;
+}
+
+/**
+ * `sections` as empty (absent, `[]`) or non-empty: a one-line flow sequence
+ * with content, or an empty value whose next line opens a block sequence
+ * (`- `, indented or not) or, indented, a multi-line flow sequence (`[` and
+ * anything but `]`).
+ */
+function readSectionsNonEmpty(lines: string[]): boolean {
+  const entry = topLevel(lines, "sections");
+  if (entry === undefined) return false;
+  const value = entry.value.replace(/\s/g, "");
+  if (value === "[]") return false;
+  if (value.startsWith("[") && value.endsWith("]")) return true;
+  const rest = entry.next.filter((line) => line.trim() !== "");
+  if (value === "" && rest[0] !== undefined) {
+    const first = rest[0].trim();
+    if (first.startsWith("- ")) return true;
+    if (/^[ \t]/.test(rest[0])) {
+      if (first.replace(/\s/g, "") === "[]") return false;
+      if (first.startsWith("[")) {
+        const after = first.slice(1).trim() || (rest[1]?.trim() ?? "");
+        if (after !== "" && !after.startsWith("]")) return true;
+      }
+    }
+  }
+  throw refusedKey("sections");
+}
+
+// ── Inserting the heading (D5) ───────────────────────────────────────────────
+
+const MDX_ESCAPED_RE = /[\\{<`*_[]/g;
+
+/**
+ * Text for an MDX body line: whitespace runs collapsed, trimmed, and every
+ * `\`, `{`, `<`, `` ` ``, `*`, `_` and `[` backslash-escaped.
+ */
+export function mdxText(text: string): string {
+  return text.replace(/\s+/g, " ").trim().replace(MDX_ESCAPED_RE, (char) => `\\${char}`);
+}
+
+const headingText = (title: string): string => mdxText(title).replace(/#$/, "\\#");
+
+// A leading block marker would start a heading, list or quote; a leading
+// `import `/`export ` would make the line ESM, so its first letter becomes a
+// character reference that renders as the same letter.
+const paragraphText = (description: string): string =>
+  mdxText(description)
+    .replace(/^[#+>-]|^(\d+)([.)])/, (marker, digits?: string, delimiter?: string) =>
+      digits === undefined ? `\\${marker}` : `${digits}\\${delimiter}`,
+    )
+    .replace(/^(?:import|export)\b/, (word) => `&#${word.charCodeAt(0)};${word.slice(1)}`);
+
+/** Offset in `body` after leading blank lines and a leading ESM block. */
+function insertionPoint(body: string): { at: number; afterEsm: boolean } {
+  const lines = body.split(/(?<=\n)/);
+  let at = 0;
+  let i = 0;
+  const blank = (line: string | undefined): boolean => line !== undefined && line.trim() === "";
+  while (blank(lines[i])) at += lines[i++]!.length;
+  if (!/^(?:import|export) /.test(lines[i] ?? "")) return { at, afterEsm: false };
+  while (i < lines.length && !blank(lines[i])) at += lines[i++]!.length;
+  const sawBlank = blank(lines[i]);
+  while (blank(lines[i])) at += lines[i++]!.length;
+  return { at, afterEsm: !sawBlank };
+}
+
+type Plan =
+  | { kind: "skip" }
+  | { kind: "write"; text: string }
+  | { kind: "refuse"; reason: string };
+
+function planPage(raw: string, rule: MdxBodyRule, type: string): Plan {
+  const mode = rule.get(type);
+  if (mode === undefined) return { kind: "skip" };
+  const split = splitPage(raw);
+  const body = split === undefined ? raw : raw.slice(split.bodyStart);
+  if (countBodyHeadings(body) > 0) return { kind: "skip" };
+  if (split === undefined) return { kind: "refuse", reason: "no frontmatter" };
+  try {
+    if (mode === "unless-sections" && readSectionsNonEmpty(split.frontmatter)) {
+      return { kind: "skip" };
+    }
+    const title = readScalar(split.frontmatter, "title");
+    if (title.trim() === "") return { kind: "refuse", reason: "no title" };
+    const description = readScalar(split.frontmatter, "description");
+    if (description.trim() === "") return { kind: "refuse", reason: "no description" };
+    const eol = raw.includes("\r\n") ? "\r\n" : "\n";
+    const { at, afterEsm } = insertionPoint(body);
+    const rest = body.slice(at);
+    const front = raw.slice(0, split.bodyStart);
+    // A file that ends at its closing `---` with no line ending needs one first.
+    const lead = afterEsm
+      ? body.slice(0, at).endsWith("\n") ? eol : eol + eol
+      : front.endsWith("\n") ? "" : eol;
+    const inserted =
+      `${lead}# ${headingText(title)}${eol}${eol}${paragraphText(description)}${eol}` +
+      (rest === "" ? "" : eol);
+    return { kind: "write", text: front + body.slice(0, at) + inserted + rest };
+  } catch (err) {
+    if (err instanceof Refused) return { kind: "refuse", reason: err.message };
+    throw err;
+  }
+}
+
+/**
+ * The new file text for an mdx-body page with zero `# ` headings — its
+ * `# <title>` and description paragraph inserted at the top of the body —
+ * else `undefined`. A page the subset reader refuses, with no frontmatter, or
+ * with an empty `title` or `description`, is never written.
+ */
+export function addBodyHeading(raw: string, rule: MdxBodyRule, type: string): string | undefined {
+  const plan = planPage(raw, rule, type);
+  return plan.kind === "write" ? plan.text : undefined;
+}
+
+// ── Over a content tree ──────────────────────────────────────────────────────
+
+interface ContentPage {
+  path: string;
+  type: string;
+}
+
+/**
+ * Every `<contentDir>/<locale>/<Type>/<slug>.mdx` whose `<Type>` the rule
+ * names, sorted. Symlinks are skipped, as `copy.ts` and `update.ts` skip
+ * them, so the codemod never reads or writes outside `contentDir`.
+ */
+function rulePages(contentDir: string, rule: MdxBodyRule): ContentPage[] {
+  if (!existsSync(contentDir)) return [];
+  const pages: ContentPage[] = [];
+  for (const locale of readdirSync(contentDir, { withFileTypes: true })) {
+    if (!locale.isDirectory() || !LOCALE_RE.test(locale.name)) continue;
+    for (const type of rule.keys()) {
+      const typeDir = join(contentDir, locale.name, type);
+      if (!existsSync(typeDir) || !lstatSync(typeDir).isDirectory()) continue;
+      for (const entry of readdirSync(typeDir, { withFileTypes: true })) {
+        if (entry.isFile() && entry.name.endsWith(".mdx")) {
+          pages.push({ path: join(typeDir, entry.name), type });
+        }
+      }
+    }
+  }
+  return pages.sort((a, b) => a.path.localeCompare(b.path));
+}
+
+export interface BodyHeadingPlan {
+  writes: Array<{ path: string; text: string }>;
+  refused: Array<{ path: string; reason: string }>;
+}
+
+/** What `migrateBodyHeadings` would write, and the heading-less pages it cannot. Never throws for a page. */
+export function planBodyHeadings(contentDir: string, rule: MdxBodyRule): BodyHeadingPlan {
+  const plan: BodyHeadingPlan = { writes: [], refused: [] };
+  for (const { path, type } of rulePages(contentDir, rule)) {
+    let page: Plan;
+    try {
+      page = planPage(readFileSync(path, "utf8"), rule, type);
+    } catch (err) {
+      plan.refused.push({ path, reason: `could not be read: ${String(err)}` });
+      continue;
+    }
+    if (page.kind === "write") plan.writes.push({ path, text: page.text });
+    else if (page.kind === "refuse") plan.refused.push({ path, reason: page.reason });
+  }
+  return plan;
+}
+
+export interface MdxBodyPage {
+  path: string;
+  /** The file's text. */
+  raw: string;
+  /** Offset of the body in `raw`; 0 for a page with no frontmatter. */
+  bodyStart: number;
+}
+
+/**
+ * Every page under `contentDir` that renders as mdx-body (#10773 D6): the
+ * `rulePages` walk, less an `unless-sections` page whose `sections` is
+ * non-empty or unreadable. An unreadable file is skipped. Sorted by path.
+ */
+export function mdxBodyPages(contentDir: string, rule: MdxBodyRule): MdxBodyPage[] {
+  const pages: MdxBodyPage[] = [];
+  for (const { path, type } of rulePages(contentDir, rule)) {
+    let raw: string;
+    try {
+      raw = readFileSync(path, "utf8");
+    } catch {
+      continue;
+    }
+    const split = splitPage(raw);
+    if (rule.get(type) === "unless-sections" && split !== undefined) {
+      try {
+        if (readSectionsNonEmpty(split.frontmatter)) continue;
+      } catch {
+        continue;
+      }
+    }
+    pages.push({ path, raw, bodyStart: split?.bodyStart ?? 0 });
+  }
+  return pages;
+}
+
+/** Every mdx-body page whose body does not have exactly one `# ` heading. */
+export function headingViolations(
+  contentDir: string,
+  rule: MdxBodyRule,
+): Array<{ path: string; count: number }> {
+  const violations: Array<{ path: string; count: number }> = [];
+  for (const { path, raw, bodyStart } of mdxBodyPages(contentDir, rule)) {
+    const count = countBodyHeadings(raw.slice(bodyStart));
+    if (count !== 1) violations.push({ path, count });
+  }
+  return violations;
+}
+
+/** Write each planned page; the paths written and the refused rows. */
+export function migrateBodyHeadings(
+  contentDir: string,
+  rule: MdxBodyRule,
+): { written: string[]; refused: Array<{ path: string; reason: string }> } {
+  const { writes, refused } = planBodyHeadings(contentDir, rule);
+  for (const { path, text } of writes) writeFileSync(path, text);
+  return { written: writes.map((write) => write.path), refused };
+}

package/templates/tools/check-mdx-body.ts

@@ -0,0 +1,123 @@
+#!/usr/bin/env tsx
+/**
+ * MDX body check (#10773) — fails when a page that renders as mdx-body
+ * carries a bare `{` in its body.
+ *
+ * MDX reads a `{` in body text as JavaScript: a placeholder such as
+ * `{First engagement}` fails the page, and one that parses (`{Tagline}`) is
+ * dropped from it. Write the brace as `\{`. Which pages are mdx-body is read
+ * from the site's own `apps/web/app` routes; frontmatter, fenced and inline
+ * code, JSX tags and `{/* … *\/}` comments are never flagged. When the site's
+ * dependencies are installed, each page with no bare brace is also parsed by
+ * the site's own MDX parser, and a parse failure, or an expression left that
+ * is not a comment, is reported.
+ *
+ * `mdx-braces.ts` and `body-heading.ts` beside this file are copies of
+ * create-ailk's own; the same rule `create-ailk update` repairs with.
+ *
+ * Usage:
+ *   pnpm mdx-body:check  # or: tsx tools/check-mdx-body.ts
+ *
+ * Exit codes:
+ *   0 — no bare brace (and no parse failure) on any mdx-body page
+ *   1 — one or more findings, each named by file, line and column
+ */
+
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { mdxBodyPages, mdxBodyRule } from "./body-heading.js";
+import { findBareBraces, firstExpression, type MdastNode } from "./mdx-braces.js";
+
+const ROOT = resolve(dirname(process.argv[1] ?? "."), "..");
+
+type Parse = (body: string) => MdastNode;
+
+/** `@mdx-js/mdx` through the `next-mdx-remote` apps/web renders with, or undefined. */
+async function siteParse(): Promise<Parse | undefined> {
+  const web = join(ROOT, "apps", "web");
+  // `resolve` falls back to NODE_PATH, so the package must be found here first.
+  for (let at = web; ; at = dirname(at)) {
+    if (existsSync(join(at, "node_modules", "next-mdx-remote", "package.json"))) break;
+    if (dirname(at) === at) return undefined;
+  }
+  try {
+    const remote = createRequire(join(web, "package.json")).resolve(
+      "next-mdx-remote/package.json",
+    );
+    const entry = createRequire(remote).resolve("@mdx-js/mdx");
+    const mdx = (await import(pathToFileURL(entry).href)) as {
+      createProcessor?: () => { parse: Parse };
+    };
+    const createProcessor = mdx.createProcessor;
+    return typeof createProcessor === "function"
+      ? (body) => createProcessor().parse(body)
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+async function main(): Promise<void> {
+  const parse = await siteParse();
+  const pages = mdxBodyPages(join(ROOT, "content"), mdxBodyRule(ROOT));
+  const rows: string[] = [];
+  const failed = new Set<string>();
+
+  for (const { path, raw, bodyStart } of pages) {
+    const file = relative(ROOT, path).split(sep).join("/");
+    const lineOffset = raw.slice(0, bodyStart).split("\n").length - 1;
+    const body = raw.slice(bodyStart);
+    const braces = findBareBraces(body);
+    for (const { line, column, kind } of braces) {
+      rows.push(
+        `${file}:${line + lineOffset}:${column} — ` +
+          (kind === "comment-like"
+            ? "{/ is not a {/* … */} comment."
+            : "a bare { in an mdx-body page is MDX code: the page fails or drops it. Write it as \\{."),
+      );
+      failed.add(file);
+    }
+    if (braces.length > 0 || parse === undefined) continue;
+    try {
+      const left = firstExpression(parse(body));
+      const line = left?.position?.start?.line;
+      if (left !== undefined) {
+        rows.push(
+          `${file}:${typeof line === "number" ? line + lineOffset : 1}:1 — an expression in an mdx-body page is dropped when it renders. Write its braces as \\{.`,
+        );
+        failed.add(file);
+      }
+    } catch (err) {
+      const { line, column, reason } = (err ?? {}) as {
+        line?: unknown;
+        column?: unknown;
+        reason?: unknown;
+      };
+      const at =
+        typeof line === "number"
+          ? `${line + lineOffset}:${typeof column === "number" ? column : 1}`
+          : "1:1";
+      rows.push(
+        `${file}:${at} — ${typeof reason === "string" ? reason : String(err)}`,
+      );
+      failed.add(file);
+    }
+  }
+
+  if (rows.length === 0) {
+    console.log(
+      `check-mdx-body: OK — ${pages.length} mdx-body page(s), no bare brace.`,
+    );
+    process.exit(0);
+  }
+  console.error(
+    `check-mdx-body: FAIL — ${rows.length} finding(s) in ${failed.size} page(s)`,
+  );
+  for (const row of rows) console.error(row);
+  process.exit(1);
+}
+
+void main();