@readme/cli 0.1.0 → 0.3.0

package/src/utils/tips.js

@@ -5,7 +5,7 @@ const tips = [
   {
     weight: 1,
     commands: ['lint', 'oas:validate'],
-    condition: (ctx) => !ctx.isRunningInClaude && ctx.workflowOutdated,
+    condition: ctx => !ctx.isRunningInClaude && ctx.workflowOutdated,
     render() {
       console.log(`  💡 ${styles.bold('Tip:')} Your GitHub Action is out of date!`);
       console.log(`     ${styles.dim('⎿')}  ${styles.orange(`${styles.binName()} setup:github`)}`);
@@ -15,7 +15,7 @@ const tips = [
   {
     weight: 1,
     commands: ['lint', 'oas:validate'],
-    condition: (ctx) => !ctx.isRunningInClaude && ctx.detectedPlatform && !ctx.hasCiWorkflow,
+    condition: ctx => !ctx.isRunningInClaude && ctx.detectedPlatform && !ctx.hasCiWorkflow,
     render(ctx) {
       const label = ctx?.detectedPlatformLabel || 'CI';
       console.log(`  💡 ${styles.bold('Tip:')} Set up ${label} to lint your docs on every PR!`);
@@ -26,17 +26,19 @@ const tips = [
   {
     weight: 1,
     commands: ['lint', 'oas:validate'],
-    condition: (ctx) => !ctx.isRunningInClaude && ctx.hasClaude,
+    condition: ctx => !ctx.isRunningInClaude && ctx.hasClaude,
     render() {
       console.log(`  💡 ${styles.bold('Tip:')} Claude can fix these issues for you easily!`);
-      console.log(`     ${styles.dim('⎿')}  ${styles.orange(`claude "run '${styles.binName()} lint' and fix the issues"`)}`);
+      console.log(
+        `     ${styles.dim('⎿')}  ${styles.orange(`claude "run '${styles.binName()} lint' and fix the issues"`)}`,
+      );
       console.log();
     },
   },
   {
     weight: 1,
     commands: ['lint', 'oas:validate'],
-    condition: (ctx) => !ctx.isRunningInClaude && !ctx.hasClaude,
+    condition: ctx => !ctx.isRunningInClaude && !ctx.hasClaude,
     render() {
       console.log(`  💡 ${styles.bold('Tip:')} Install Claude to automatically fix these issues!`);
       console.log(`     ${styles.dim('⎿')}  ${styles.dim('https://claude.ai/download')}`);
@@ -47,7 +49,9 @@ const tips = [
     weight: 0.1,
     condition: () => !loadPet(),
     render() {
-      console.log(`  💡 ${styles.bold('Tip:')} Want a little friend? Run ${styles.orange(`${styles.binName()} play`)} to hatch one!`);
+      console.log(
+        `  💡 ${styles.bold('Tip:')} Want a little friend? Run ${styles.orange(`${styles.binName()} play`)} to hatch one!`,
+      );
       console.log();
     },
   },
@@ -56,7 +60,9 @@ const tips = [
     condition: () => !!loadPet(),
     render() {
       const pet = loadPet();
-      console.log(`  💡 ${styles.bold('Tip:')} ${pet.name} misses you! Run ${styles.orange(`${styles.binName()} play`)} to check in.`);
+      console.log(
+        `  💡 ${styles.bold('Tip:')} ${pet.name} misses you! Run ${styles.orange(`${styles.binName()} play`)} to check in.`,
+      );
       console.log();
     },
   },
@@ -69,7 +75,7 @@ const tips = [
  */
 export function getRandomTip(context) {
   const cmd = context.command;
-  const eligible = tips.filter((t) => {
+  const eligible = tips.filter(t => {
     // Filter by command if tip has a commands array
     if (t.commands && cmd && !t.commands.includes(cmd)) return false;
     // Tips without commands array show everywhere
@@ -83,7 +89,10 @@ export function getRandomTip(context) {
   let chosen = eligible[eligible.length - 1];
   for (const tip of eligible) {
     rand -= tip.weight || 1;
-    if (rand <= 0) { chosen = tip; break; }
+    if (rand <= 0) {
+      chosen = tip;
+      break;
+    }
   }
   // Bind context so render() can read it without a second argument.
   return { render: () => chosen.render(context) };

package/src/utils/url-segs.js

@@ -4,8 +4,8 @@
  */
 
 // Extensions that are implementation artifacts, not meaningful path segments.
-const DOC_FILE_EXTENSIONS = ['md', 'mdx', 'html', 'htm', 'txt']
-const DOC_EXT_RE = new RegExp(`(\\.(${DOC_FILE_EXTENSIONS.join('|')}))+$`, 'i')
+const DOC_FILE_EXTENSIONS = ['md', 'mdx', 'html', 'htm', 'txt'];
+const DOC_EXT_RE = new RegExp(`(\\.(${DOC_FILE_EXTENSIONS.join('|')}))+$`, 'i');
 
 /**
  * Strip all chained doc-file extensions (.html.md, .html, .md, .mdx, .htm, .txt)
@@ -13,7 +13,7 @@ const DOC_EXT_RE = new RegExp(`(\\.(${DOC_FILE_EXTENSIONS.join('|')}))+$`, 'i')
  * by some SSGs (e.g. `.html.md`).
  */
 export function stripSegmentExtensions(s) {
-  return s.replace(DOC_EXT_RE, '')
+  return s.replace(DOC_EXT_RE, '');
 }
 
 /**
@@ -28,12 +28,12 @@ export function urlTrieSegs(url) {
     const segs = new URL(url).pathname
       .split('/')
       .filter(Boolean)
-      .map((s) => stripSegmentExtensions(s))
-      .filter(Boolean)
-    if (segs.length > 0 && segs[segs.length - 1].toLowerCase() === 'index') segs.pop()
-    return segs
+      .map(s => stripSegmentExtensions(s))
+      .filter(Boolean);
+    if (segs.length > 0 && segs[segs.length - 1].toLowerCase() === 'index') segs.pop();
+    return segs;
   } catch {
-    return null
+    return null;
   }
 }
 
@@ -44,17 +44,17 @@ export function urlTrieSegs(url) {
  * `/foo/index.html.md` and `/foo/` both collapse to the same slug base.
  */
 export function extractUrlPathSegments(url) {
-  if (!url) return []
+  if (!url) return [];
   try {
     const segs = new URL(url).pathname
       .split('/')
       .filter(Boolean)
-      .map((s) => stripSegmentExtensions(s).replace(/^\d+[-_.]/, ''))
-      .filter(Boolean)
-    if (segs.length > 0 && segs[segs.length - 1].toLowerCase() === 'index') segs.pop()
-    return segs
+      .map(s => stripSegmentExtensions(s).replace(/^\d+[-_.]/, ''))
+      .filter(Boolean);
+    if (segs.length > 0 && segs[segs.length - 1].toLowerCase() === 'index') segs.pop();
+    return segs;
   } catch {
-    return []
+    return [];
   }
 }
 
@@ -66,13 +66,13 @@ export function extractUrlPathSegments(url) {
  */
 export function normalizePath(url) {
   try {
-    const u = new URL(url)
-    let p = u.pathname.replace(/\/$/, '').toLowerCase()
-    p = p.replace(DOC_EXT_RE, '')
-    p = p.replace(/\/index$/i, '')
-    return p || '/'
+    const u = new URL(url);
+    let p = u.pathname.replace(/\/$/, '').toLowerCase();
+    p = p.replace(DOC_EXT_RE, '');
+    p = p.replace(/\/index$/i, '');
+    return p || '/';
   } catch {
-    return String(url).toLowerCase()
+    return String(url).toLowerCase();
   }
 }
 
@@ -87,38 +87,43 @@ export function normalizePath(url) {
  */
 export function llmsPageDedupeKey(url) {
   try {
-    const u = new URL(url)
-    let p = u.pathname.replace(/\/$/, '').toLowerCase()
-    p = p.replace(DOC_EXT_RE, '')
-    p = p.replace(/\/index$/i, '')
+    const u = new URL(url);
+    let p = u.pathname.replace(/\/$/, '').toLowerCase();
+    p = p.replace(DOC_EXT_RE, '');
+    p = p.replace(/\/index$/i, '');
 
-    const params = [...u.searchParams.entries()].sort(([ak, av], [bk, bv]) => (ak === bk ? av.localeCompare(bv) : ak.localeCompare(bk)))
-    const query = params.length > 0 ? `?${params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')}` : ''
+    const params = [...u.searchParams.entries()].sort(([ak, av], [bk, bv]) =>
+      ak === bk ? av.localeCompare(bv) : ak.localeCompare(bk),
+    );
+    const query =
+      params.length > 0
+        ? `?${params.map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`).join('&')}`
+        : '';
 
-    return `${u.origin.toLowerCase()}${p || '/'}${query}`
+    return `${u.origin.toLowerCase()}${p || '/'}${query}`;
   } catch {
-    return String(url).toLowerCase()
+    return String(url).toLowerCase();
   }
 }
 
 export function compareCanonicalUrlPreference(a, b) {
-  const aRank = canonicalUrlPreferenceRank(a)
-  const bRank = canonicalUrlPreferenceRank(b)
-  if (aRank !== bRank) return aRank - bRank
-  return String(a || '').length - String(b || '').length
+  const aRank = canonicalUrlPreferenceRank(a);
+  const bRank = canonicalUrlPreferenceRank(b);
+  if (aRank !== bRank) return aRank - bRank;
+  return String(a || '').length - String(b || '').length;
 }
 
 function canonicalUrlPreferenceRank(url) {
   try {
-    const pathname = new URL(url).pathname
-    const lower = pathname.toLowerCase()
-    if (/\.md$/.test(lower)) return 0
-    if (/\.txt$/.test(lower)) return 1
-    if (!/\/$/.test(pathname) && !/\/index\.html?$/.test(lower) && !/\.[^/]+$/.test(lower)) return 2
-    if (/\/$/.test(pathname)) return 3
-    if (/\/index\.html?$/.test(lower)) return 4
-    return 5
+    const pathname = new URL(url).pathname;
+    const lower = pathname.toLowerCase();
+    if (lower.endsWith('.md')) return 0;
+    if (lower.endsWith('.txt')) return 1;
+    if (!pathname.endsWith('/') && !/\/index\.html?$/.test(lower) && !/\.[^/]+$/.test(lower)) return 2;
+    if (pathname.endsWith('/')) return 3;
+    if (/\/index\.html?$/.test(lower)) return 4;
+    return 5;
   } catch {
-    return 5
+    return 5;
   }
 }

package/src/validators/components.js

@@ -1,44 +1,46 @@
-import fs from "node:fs";
-import path from "node:path";
-import matter from "gray-matter";
-import markdown from "@readme/markdown";
+import fs from 'node:fs';
+import path from 'node:path';
+
+import markdown from '@readme/markdown';
+
+import { parseFrontmatter } from '../utils/markdown.js';
 
 const { mdxishTags } = markdown;
 
-export const name = "components";
+export const name = 'components';
 
 // Built-in components provided by @readme/markdown.
 const BUILTIN_COMPONENTS = new Set([
   // Documented in ReadMe user docs
-  "Accordion",
-  "Tabs",
-  "Tab",
-  "Cards",
-  "Card",
-  "Columns",
-  "Column",
-  "Image",
+  'Accordion',
+  'Tabs',
+  'Tab',
+  'Cards',
+  'Card',
+  'Columns',
+  'Column',
+  'Image',
   // Available from @readme/markdown
-  "Anchor",
-  "Callout",
-  "Code",
-  "CodeTabs",
-  "Embed",
-  "Glossary",
-  "Heading",
-  "HTMLBlock",
-  "Table",
-  "TableOfContents",
-  "Recipe",
-  "MCPIntro",
-  "PostmanRunButton",
-  "TailwindRoot",
-  "TailwindStyle",
-  "TutorialTile",
+  'Anchor',
+  'Callout',
+  'Code',
+  'CodeTabs',
+  'Embed',
+  'Glossary',
+  'Heading',
+  'HTMLBlock',
+  'Table',
+  'TableOfContents',
+  'Recipe',
+  'MCPIntro',
+  'PostmanRunButton',
+  'TailwindRoot',
+  'TailwindStyle',
+  'TutorialTile',
 ]);
 
 // Directories that can contain MDXish content with component references.
-const CONTENT_DIRS = new Set(["docs", "reference", "custom_pages", "recipes"]);
+const CONTENT_DIRS = new Set(['docs', 'reference', 'custom_pages', 'recipes']);
 
 /**
  * Extract component tag names from MDXish content.
@@ -48,12 +50,7 @@ const CONTENT_DIRS = new Set(["docs", "reference", "custom_pages", "recipes"]);
 function extractComponentTags(content) {
   // Strip frontmatter — mdxishTags parses raw mdxish, so frontmatter values
   // like `foo: <NotAComponent />` would otherwise be picked up.
-  let body;
-  try {
-    ({ content: body } = matter(content));
-  } catch {
-    body = content.replace(/^---[\s\S]*?---/, "");
-  }
+  const { content: body } = parseFrontmatter(content);
 
   try {
     return new Set(mdxishTags(body));
@@ -82,33 +79,33 @@ function extractExportedNames(body) {
  * .md files: uses the filename slug (e.g., Greeting.md → <Greeting />).
  */
 function collectCustomBlockNames(gitRoot) {
-  const blocksDir = path.join(gitRoot, "custom_blocks");
+  const blocksDir = path.join(gitRoot, 'custom_blocks');
   if (!fs.existsSync(blocksDir)) return new Set();
 
   const names = new Set();
   const entries = fs.readdirSync(blocksDir);
 
   for (const entry of entries) {
-    if (!entry.endsWith(".md") && !entry.endsWith(".mdx")) continue;
+    if (!entry.endsWith('.md') && !entry.endsWith('.mdx')) continue;
 
     try {
-      const content = fs.readFileSync(path.join(blocksDir, entry), "utf-8");
+      const content = fs.readFileSync(path.join(blocksDir, entry), 'utf-8');
 
-      if (entry.endsWith(".mdx")) {
+      if (entry.endsWith('.mdx')) {
         // .mdx: component names come from exports.
-        const { content: body } = matter(content);
+        const { content: body } = parseFrontmatter(content);
         for (const n of extractExportedNames(body)) {
           names.add(n);
         }
       } else {
         // .md snippet: component name is the PascalCase filename.
-        const slug = entry.replace(/\.md$/, "");
+        const slug = entry.replace(/\.md$/, '');
         names.add(slug);
         // Also register the PascalCase form so references resolve.
         const pascalCase = slug
           .split(/[-_]/)
-          .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-          .join("");
+          .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+          .join('');
         names.add(pascalCase);
       }
     } catch {
@@ -125,11 +122,11 @@ function collectCustomBlockNames(gitRoot) {
  * - .md: filename must be capitalized (used as component name via <Name />)
  */
 export function validate({ content, relativePath }) {
-  if (!relativePath.startsWith("custom_blocks/")) return null;
+  if (!relativePath.startsWith('custom_blocks/')) return null;
 
   const filename = path.basename(relativePath);
-  const isMdx = relativePath.endsWith(".mdx");
-  const isMd = relativePath.endsWith(".md");
+  const isMdx = relativePath.endsWith('.mdx');
+  const isMd = relativePath.endsWith('.md');
 
   if (!isMdx && !isMd) return null;
 
@@ -140,16 +137,16 @@ export function validate({ content, relativePath }) {
   // digits are fine (<Helm_v4_error /> is valid); hyphens and a lowercase initial
   // are not.
   if (isMd) {
-    const slug = filename.replace(/\.md$/, "");
+    const slug = filename.replace(/\.md$/, '');
     if (!/^[A-Z][A-Za-z0-9_$]*$/.test(slug)) {
       const suggestion = slug
         .split(/[-_]/)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join("");
+        .map(part => part.charAt(0).toUpperCase() + part.slice(1))
+        .join('');
       results.push({
         file: relativePath,
         rule: name,
-        severity: "warning",
+        severity: 'warning',
         message: `Bad filename: "${slug}" can't be used as a component tag — rename to "${suggestion}.md" so it can be used as <${suggestion} />`,
       });
     }
@@ -157,14 +154,9 @@ export function validate({ content, relativePath }) {
   }
 
   // .mdx component files: validate export and usage example.
-  let data;
-  let body;
-
-  try {
-    ({ data, content: body } = matter(content));
-  } catch {
-    return null; // frontmatter validator handles parse errors.
-  }
+  // Invalid YAML is reported by the frontmatter validator via `error`.
+  const { data, content: body, error } = parseFrontmatter(content);
+  if (error) return null;
 
   const componentName = data.name;
   if (!componentName) return null; // frontmatter validator handles missing name.
@@ -187,7 +179,7 @@ export function validate({ content, relativePath }) {
     results.push({
       file: relativePath,
       rule: name,
-      severity: "warning",
+      severity: 'warning',
       message: `Missing example: no usage example found for "${componentName}"`,
     });
   }
@@ -204,14 +196,14 @@ export function validateAll(files, gitRoot) {
   const available = new Set([...BUILTIN_COMPONENTS, ...customBlocks]);
 
   for (const relPath of files) {
-    const dir = relPath.split("/")[0];
+    const dir = relPath.split('/')[0];
     if (!CONTENT_DIRS.has(dir)) continue;
-    if (!relPath.endsWith(".md")) continue;
+    if (!relPath.endsWith('.md')) continue;
 
     const filePath = path.join(gitRoot, relPath);
     let content;
     try {
-      content = fs.readFileSync(filePath, "utf-8");
+      content = fs.readFileSync(filePath, 'utf-8');
     } catch {
       continue;
     }

package/src/validators/content.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import matter from 'gray-matter';
+
+import { parseFrontmatter } from '../utils/markdown.js';
 
 export const name = 'content';
 
@@ -9,13 +10,7 @@ export function validate({ filePath, content, relativePath }) {
   if (!['docs', 'reference', 'custom_pages'].includes(dir)) return null;
   if (!relativePath.endsWith('.md')) return null;
 
-  let data;
-  let body;
-  try {
-    ({ data, content: body } = matter(content));
-  } catch {
-    return null;
-  }
+  const { data, content: body } = parseFrontmatter(content);
 
   if (data.hidden || data.deprecated) return null;
   if (data.api) return null;
@@ -27,18 +22,25 @@ export function validate({ filePath, content, relativePath }) {
         file: relativePath,
         rule: name,
         severity: 'warning',
-        message: 'Redirect page has body content: pages with a link URL won\'t display their content',
+        message: "Redirect page has body content: pages with a link URL won't display their content",
       };
     }
     return null;
   }
   if (trimmed.length === 0) {
-    // index.md files that act as parent pages (have child .md siblings) can be empty.
+    // index.md files that act as parent pages (have child page siblings or nested page
+    // directories) can be empty. The backend accepts .md and .mdx in any case.
     if (path.basename(filePath) === 'index.md') {
-      const siblings = fs.readdirSync(path.dirname(filePath));
-      if (siblings.some((f) => f.endsWith('.md') && f !== 'index.md')) {
-        return null;
-      }
+      const dir = path.dirname(filePath);
+      const isPage = f => /\.mdx?$/i.test(f);
+      const hasChildren = fs
+        .readdirSync(dir, { withFileTypes: true })
+        .some(
+          e =>
+            (!e.isDirectory() && isPage(e.name) && !/^index\.mdx?$/i.test(e.name)) ||
+            (e.isDirectory() && fs.readdirSync(path.join(dir, e.name)).some(isPage)),
+        );
+      if (hasChildren) return null;
     }
 
     return {

package/src/validators/duplicates.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+
 import { slugForEntry } from '../utils/slug-for-entry.js';
 
 export const name = 'duplicates';
@@ -26,12 +27,15 @@ export function validateAll(files) {
 
     // TODO: figure out why ReadMeConfig causes duplicate slugs and handle properly.
     // For now, skip any duplicate set that involves a ReadMeConfig path.
-    if (paths.some((p) => p.includes('ReadMeConfig/'))) continue;
+    if (paths.some(p => p.includes('ReadMeConfig/'))) continue;
 
     const slug = key.slice(key.indexOf(':') + 1);
     const others = paths.slice(1);
     for (const relPath of others) {
-      const otherLocations = paths.filter((p) => p !== relPath).map((p) => path.dirname(p)).join(', ');
+      const otherLocations = paths
+        .filter(p => p !== relPath)
+        .map(p => path.dirname(p))
+        .join(', ');
       results.push({
         file: relPath,
         rule: name,

package/src/validators/frontmatter.js

@@ -1,10 +1,9 @@
 import fs from 'node:fs';
-import path from 'node:path';
-import { createRequire } from 'node:module';
-import matter from 'gray-matter';
+
 import Ajv from 'ajv';
 
-const require = createRequire(import.meta.url);
+import frontmatterSchema from '../../vendor/git-format/frontmatter.schema.json' with { type: 'json' };
+import { parseFrontmatter } from '../utils/markdown.js';
 
 export const name = 'frontmatter';
 
@@ -12,7 +11,7 @@ function getNestedValue(obj, instancePath) {
   const keys = instancePath.split('/').filter(Boolean);
   let current = obj;
   for (const key of keys) {
-    if (current == null || typeof current !== 'object') return undefined;
+    if (current == null || typeof current !== 'object') return;
     current = current[key];
   }
   return current;
@@ -27,9 +26,7 @@ function levenshtein(a, b) {
   for (let j = 0; j <= n; j++) dp[0][j] = j;
   for (let i = 1; i <= m; i++) {
     for (let j = 1; j <= n; j++) {
-      dp[i][j] = a[i - 1] === b[j - 1]
-        ? dp[i - 1][j - 1]
-        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      dp[i][j] = a[i - 1] === b[j - 1] ? dp[i - 1][j - 1] : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
     }
   }
   return dp[m][n];
@@ -77,30 +74,25 @@ const DIR_SCHEMA_INDEX = {
   custom_blocks: 4,
 };
 
-// Load the schema and compile a validator for each directory type.
-const schemaPath = require.resolve('@readmeio/git-format/frontmatter.schema.json');
-const fullSchema = JSON.parse(fs.readFileSync(schemaPath, 'utf-8'));
-
+// Compile a validator for each directory type from the vendored schema.
 const ajv = new Ajv({ allErrors: true, strict: false, logger: false, verbose: true });
 
 const validators = {};
 const knownProperties = {};
 for (const [dir, index] of Object.entries(DIR_SCHEMA_INDEX)) {
-  const subSchema = { defs: fullSchema.defs, ...fullSchema.oneOf[index] };
+  const subSchema = { defs: frontmatterSchema.defs, ...frontmatterSchema.oneOf[index] };
   validators[dir] = ajv.compile(subSchema);
-  knownProperties[dir] = collectPropertyNames(subSchema, fullSchema.defs);
+  knownProperties[dir] = collectPropertyNames(subSchema, frontmatterSchema.defs);
 }
 
 export function validate({ content, filePath, relativePath, fix }) {
   // Step 1: Parse the frontmatter YAML.
-  let data;
-  try {
-    ({ data } = matter(content));
-  } catch (e) {
+  const { data, error } = parseFrontmatter(content);
+  if (error) {
     return {
       file: relativePath,
       rule: name,
-      message: `Invalid frontmatter: ${e.reason || e.message || 'unknown error'}`,
+      message: `Invalid frontmatter: ${error.reason || error.message || 'unknown error'}`,
     };
   }
 
@@ -126,7 +118,7 @@ export function validate({ content, filePath, relativePath, fix }) {
 
         if (err.keyword === 'not' && err.schema?.properties) {
           const target = err.instancePath ? getNestedValue(data, err.instancePath) : data;
-          if (!target || !Object.keys(err.schema.properties).some((k) => k in target)) continue;
+          if (!target || !Object.keys(err.schema.properties).some(k => k in target)) continue;
         }
 
         let msg;
@@ -169,9 +161,9 @@ export function validate({ content, filePath, relativePath, fix }) {
 
   // Step 4: Detect typos by comparing unknown properties against known ones.
   const missingRequired = results.filter(
-    (r) => r.severity === 'error' && r.message.includes('must have required property'),
+    r => r.severity === 'error' && r.message.includes('must have required property'),
   );
-  const unknowns = results.filter((r) => r._key);
+  const unknowns = results.filter(r => r._key);
 
   const consumed = new Set();
 
@@ -223,17 +215,17 @@ export function validate({ content, filePath, relativePath, fix }) {
 
   // Step 5: Apply fixes — rename unknown (non-typo) properties to x- prefixed.
   if (fix && filePath) {
-    const typoKeys = new Set([...consumed].map((r) => r._key));
-    const keysToFix = unknownKeys.filter((key) => !typoKeys.has(key) && !suggestedTypos.has(key));
+    const typoKeys = new Set([...consumed].map(r => r._key));
+    const keysToFix = unknownKeys.filter(key => !typoKeys.has(key) && !suggestedTypos.has(key));
 
     if (keysToFix.length > 0) {
       let fileContent = fs.readFileSync(filePath, 'utf-8');
 
-      // Only replace within the frontmatter block (between the --- delimiters).
-      const fmMatch = fileContent.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-      if (fmMatch) {
+      // Same header boundaries as parseFrontmatter: leading blanks OK; empty
+      // headers (`---\n---`) leave group 1 unset so we skip the rewrite.
+      const fmMatch = fileContent.match(/^[\r\n]*---[ \t]*\r?\n(?:([\s\S]*?)\r?\n)?---[ \t]*/);
+      if (fmMatch && fmMatch[1] != null) {
         let frontmatter = fmMatch[1];
-        const keysToFixSet = new Set(keysToFix);
         for (const key of keysToFix) {
           const regex = new RegExp(`^(${key}:)`, 'gm');
           frontmatter = frontmatter.replace(regex, `x-${key}:`);
@@ -253,6 +245,6 @@ export function validate({ content, filePath, relativePath, fix }) {
   }
 
   // Remove consumed warnings (they've been merged into the error).
-  const final = results.filter((r) => !consumed.has(r));
+  const final = results.filter(r => !consumed.has(r));
   return final.length > 0 ? final : null;
 }