@readme/cli 0.0.26

package/src/validators/links.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+export const name = 'links';
+
+const CHECKED_DIRS = ['docs', 'reference', 'custom_pages', 'recipes'];
+
+// Match doc:slug and ref:slug links, e.g. [text](doc:my-page) or [text](ref:my-op#anchor)
+const DOC_LINK_RE = /\((?:doc|ref):([a-zA-Z0-9_-]+)(?:#[^)]*)?\)/g;
+
+function collectSlugs(gitRoot) {
+  const slugs = new Set();
+
+  for (const dir of CHECKED_DIRS) {
+    const dirPath = path.join(gitRoot, dir);
+    if (!fs.existsSync(dirPath)) continue;
+
+    const entries = fs.readdirSync(dirPath, { recursive: true });
+    for (const entry of entries) {
+      if (!/\.(md|mdx)$/.test(entry)) continue;
+      const filename = path.basename(entry);
+      if (filename === 'index.md' || filename === 'index.mdx') {
+        // index.md represents the parent directory, e.g. plans-and-pricing/index.md -> slug "plans-and-pricing"
+        const parentDir = path.basename(path.dirname(entry));
+        if (parentDir && parentDir !== '.') slugs.add(parentDir);
+      } else {
+        slugs.add(filename.replace(/\.(md|mdx)$/, ''));
+      }
+    }
+  }
+
+  return slugs;
+}
+
+export function validateAll(files, gitRoot) {
+  const validSlugs = collectSlugs(gitRoot);
+  const results = [];
+
+  for (const relPath of files) {
+    const topDir = relPath.split('/')[0];
+    if (!CHECKED_DIRS.includes(topDir)) continue;
+    if (!/\.(md|mdx)$/.test(relPath)) continue;
+
+    let body;
+    try {
+      const raw = fs.readFileSync(path.join(gitRoot, relPath), 'utf-8');
+      ({ content: body } = matter(raw));
+    } catch {
+      continue;
+    }
+
+    for (const match of body.matchAll(DOC_LINK_RE)) {
+      const prefix = match[0].slice(1, match[0].indexOf(':'));
+      const slug = match[1];
+      if (!validSlugs.has(slug)) {
+        results.push({
+          file: relPath,
+          rule: name,
+          severity: 'error',
+          message: `Broken link: "${prefix}:${slug}" does not match any page`,
+        });
+      }
+    }
+  }
+
+  return results.length > 0 ? results : null;
+}

package/src/validators/nesting.js

@@ -0,0 +1,50 @@
+import path from 'node:path';
+
+export const name = 'nesting';
+
+// Max folder nesting per top-level content dir. Anything deeper still syncs
+// but won't appear in the sidebar.
+const MAX_DEPTH = {
+  docs: 3,
+  reference: 3,
+  recipes: 0,
+  custom_pages: 0,
+  custom_blocks: 0,
+};
+
+export function validateAll(files) {
+  const results = [];
+  const seen = new Set();
+
+  for (const relPath of files) {
+    const parts = relPath.split('/');
+    const topDir = parts[0];
+    const max = MAX_DEPTH[topDir];
+    if (max === undefined) continue;
+
+    // Depth = number of folders between the top dir and the file.
+    // docs/a/b/c/page.md → parts.length 5 → depth 3
+    // docs/a/b/c/d/page.md → parts.length 6 → depth 4
+    const depth = parts.length - 2;
+    if (depth <= max) continue;
+
+    // Warn once per offending folder to avoid spamming every file inside it.
+    const folderPath = parts.slice(0, -1).join('/');
+    if (seen.has(folderPath)) continue;
+    seen.add(folderPath);
+
+    const message =
+      max === 0
+        ? `Folders not supported: "${folderPath}" — "${topDir}" files must live in the root directory`
+        : `Too deeply nested: "${folderPath}" is ${depth} levels deep (only ${max} will render in the sidebar)`;
+
+    results.push({
+      file: folderPath,
+      rule: name,
+      severity: 'warning',
+      message,
+    });
+  }
+
+  return results.length > 0 ? results : null;
+}

package/src/validators/numbering.js

@@ -0,0 +1,136 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import readline from 'node:readline';
+import * as styles from '../utils/styles.js';
+
+export const name = 'numbering';
+
+const SUFFIX_RE = /-(\d+)$/;
+
+function prompt(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      rl.close();
+      resolve(answer.trim().toLowerCase());
+    });
+  });
+}
+
+function updateOrderYaml(fromPath, toPath) {
+  const dir = path.dirname(fromPath);
+  const orderFile = path.join(dir, '_order.yaml');
+  if (!fs.existsSync(orderFile)) return;
+
+  const oldSlug = path.basename(fromPath).replace(/\.(md|mdx)$/, '');
+  const newSlug = path.basename(toPath).replace(/\.(md|mdx)$/, '');
+
+  const content = fs.readFileSync(orderFile, 'utf-8');
+  const updated = content.replace(
+    new RegExp(`^(- )${oldSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}$`, 'm'),
+    `$1${newSlug}`,
+  );
+
+  if (updated !== content) {
+    fs.writeFileSync(orderFile, updated);
+  }
+}
+
+export async function validateAll(files, gitRoot, { fix } = {}) {
+  const results = [];
+  const renames = [];
+
+  // Collect all slugs (filenames without ext) and directory names across the repo.
+  const allSlugs = new Set();
+  const allDirs = new Set();
+  for (const relPath of files) {
+    allSlugs.add(path.basename(relPath).replace(/\.(md|mdx)$/, ''));
+    const parts = relPath.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+      allDirs.add(parts[i]);
+    }
+  }
+
+  // Check files: if slug ends with -N and the base slug doesn't exist anywhere, warn.
+  for (const relPath of files) {
+    const slug = path.basename(relPath).replace(/\.(md|mdx)$/, '');
+    const match = slug.match(SUFFIX_RE);
+    if (!match) continue;
+
+    const baseSlug = slug.slice(0, -match[0].length);
+    if (!allSlugs.has(baseSlug)) {
+      const ext = path.extname(relPath);
+      const from = path.join(gitRoot, relPath);
+      const toRel = path.join(path.dirname(relPath), `${baseSlug}${ext}`);
+      const to = path.join(gitRoot, toRel);
+
+      results.push({
+        file: relPath,
+        rule: name,
+        severity: 'warning',
+        fixable: true,
+        message: `Unnecessary suffix: "${slug}${ext}" should be renamed to "${baseSlug}${ext}"`,
+      });
+      renames.push({ from, to, label: `${relPath} → ${toRel}` });
+    }
+  }
+
+  // Check directories: if a dir name ends with -N and the base dir doesn't exist, warn.
+  const warnedDirs = new Set();
+  for (const relPath of files) {
+    const parts = relPath.split('/');
+    for (let i = 0; i < parts.length - 1; i++) {
+      const dirName = parts[i];
+      if (warnedDirs.has(dirName)) continue;
+
+      const match = dirName.match(SUFFIX_RE);
+      if (!match) continue;
+
+      const baseName = dirName.slice(0, -match[0].length);
+      if (!allDirs.has(baseName)) {
+        warnedDirs.add(dirName);
+        const dirPath = parts.slice(0, i + 1).join('/');
+        const baseDirPath = [...parts.slice(0, i), baseName].join('/');
+        const from = path.join(gitRoot, dirPath);
+        const to = path.join(gitRoot, baseDirPath);
+
+        results.push({
+          file: dirPath,
+          rule: name,
+          severity: 'warning',
+          fixable: true,
+          message: `Unnecessary suffix: "${dirName}" folder should be renamed to "${baseName}"`,
+        });
+        renames.push({ from, to, label: `${dirPath}/ → ${baseDirPath}/` });
+      }
+    }
+  }
+
+  // Interactive rename when --fix is passed.
+  if (fix && renames.length > 0) {
+    console.log();
+    console.log(`  The following will be renamed:`);
+    for (const r of renames) {
+      console.log(`    ${styles.dim(r.label)}`);
+    }
+    console.log();
+    console.log(`  ${styles.warn('Note:')} Renaming changes slugs, which could break existing URLs.`);
+    console.log();
+
+    const answer = await prompt(`  Rename ${renames.length} ${renames.length === 1 ? 'path' : 'paths'}? (y/N) `);
+
+    if (answer === 'y' || answer === 'yes') {
+      // Sort longest path first so nested dirs get renamed before parents.
+      renames.sort((a, b) => b.from.length - a.from.length);
+      for (const r of renames) {
+        fs.renameSync(r.from, r.to);
+        updateOrderYaml(r.from, r.to);
+      }
+      for (const r of results) {
+        r.message += ' (fixed)';
+      }
+    }
+  }
+
+  return results.length > 0 ? results : null;
+}

package/src/validators/oas-reference.js

@@ -0,0 +1,126 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { findOasFiles, extractOperations, collectExistingPages, syncOas } from '../commands/oas-sync.js';
+
+export const name = 'oas-reference';
+
+export function validateAll(files, gitRoot, { fix } = {}) {
+  const refDir = path.join(gitRoot, 'reference');
+  if (!fs.existsSync(refDir)) return [];
+
+  const oasFiles = findOasFiles(refDir);
+  const results = [];
+
+  // Build a map of OAS filename -> spec operations for quick lookup.
+  const oasMap = new Map();
+  for (const { filename, spec } of oasFiles) {
+    oasMap.set(filename, { spec, ops: extractOperations(spec) });
+  }
+
+  // Collect all reference pages with api frontmatter.
+  const refPages = files.filter((f) => f.startsWith('reference/') && f.endsWith('.md'));
+
+  for (const relPath of refPages) {
+    const filePath = path.join(gitRoot, relPath);
+    let data;
+    try {
+      ({ data } = matter(fs.readFileSync(filePath, 'utf-8')));
+    } catch {
+      continue;
+    }
+
+    if (!data.api || !data.api.file) continue;
+
+    const oasFilename = data.api.file;
+    const operationId = data.api.operationId;
+    const oas = oasMap.get(oasFilename);
+
+    // Check: OAS file doesn't exist.
+    if (!oas) {
+      results.push({
+        file: relPath,
+        rule: name,
+        message: `OAS file not found: "${oasFilename}" does not exist in reference/`,
+        fixable: false,
+      });
+      continue;
+    }
+
+    if (!operationId) continue;
+
+    // Check: operationId doesn't exist in the spec.
+    if (!oas.ops.has(operationId)) {
+      results.push({
+        file: relPath,
+        rule: name,
+        message: `Operation not found: "${operationId}" does not exist in "${oasFilename}"`,
+        fixable: true,
+      });
+      continue;
+    }
+
+    // Skip title/excerpt sync checks for ReadMeConfig (internal ReadMe pages).
+    // Check both the spec title and the page's directory path.
+    const isReadMeConfig = oas.spec.info?.title === 'ReadMeConfig'
+      || relPath.startsWith('reference/ReadMeConfig/');
+    if (isReadMeConfig) continue;
+
+    // Check: title or excerpt out of sync.
+    const op = oas.ops.get(operationId);
+    const expectedTitle = op.summary || operationId;
+    const expectedExcerpt = op.description || null;
+
+    if (data.title !== expectedTitle) {
+      results.push({
+        file: relPath,
+        rule: name,
+        severity: 'warning',
+        message: `Out of sync: title is "${data.title}" but spec summary is "${expectedTitle}"`,
+        fixable: true,
+      });
+    }
+
+    const currentExcerpt = data.excerpt || null;
+    if (currentExcerpt !== expectedExcerpt) {
+      results.push({
+        file: relPath,
+        rule: name,
+        severity: 'warning',
+        message: `Out of sync: excerpt does not match spec description for "${operationId}"`,
+        fixable: true,
+      });
+    }
+  }
+
+  // Check for missing pages: operations in the spec with no corresponding page.
+  const existingPages = collectExistingPages(refDir);
+  for (const [oasFilename, { ops }] of oasMap) {
+    const pagesForOas = existingPages.filter((p) => p.data.api.file === oasFilename);
+    const coveredOps = new Set(pagesForOas.map((p) => p.data.api.operationId));
+
+    for (const [opId] of ops) {
+      if (!coveredOps.has(opId)) {
+        results.push({
+          file: `reference/${oasFilename}`,
+          rule: name,
+          severity: 'warning',
+          message: `Missing page: no reference page found for operation "${opId}"`,
+          fixable: true,
+        });
+      }
+    }
+  }
+
+  // Apply fixes by running the full sync.
+  if (fix && results.length > 0) {
+    const syncResults = syncOas(gitRoot);
+    if (syncResults) {
+      for (const r of results) {
+        if (r.fixable) r.message += ' (fixed)';
+      }
+    }
+  }
+
+  return results;
+}

package/src/validators/oas-schema.js

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import OASNormalize from 'oas-normalize';
+import { findOasFiles } from '../commands/oas-sync.js';
+
+export const name = 'oas-schema';
+
+/**
+ * Walk a parsed spec and find $ref values that are malformed.
+ * Valid internal refs start with "#/"; catches things like "#components/schemas/Foo".
+ */
+function findBadRefs(obj, pointer = '') {
+  const issues = [];
+  if (obj && typeof obj === 'object') {
+    if (typeof obj.$ref === 'string') {
+      const ref = obj.$ref;
+      if (ref.startsWith('#') && !ref.startsWith('#/')) {
+        issues.push({ path: pointer, ref });
+      }
+    }
+    for (const [key, value] of Object.entries(obj)) {
+      if (key === '$ref') continue;
+      issues.push(...findBadRefs(value, `${pointer}/${key}`));
+    }
+  }
+  return issues;
+}
+
+export async function validateAll(files, gitRoot) {
+  const refDir = path.join(gitRoot, 'reference');
+  if (!fs.existsSync(refDir)) return [];
+
+  const oasFiles = findOasFiles(refDir);
+  const results = [];
+
+  for (const { filename, spec } of oasFiles) {
+    const filePath = path.join(refDir, filename);
+    const raw = fs.readFileSync(filePath, 'utf-8');
+
+    try {
+      const normalizer = new OASNormalize(raw, { enablePaths: false });
+      const result = await normalizer.validate({
+        shouldThrowIfInvalid: false,
+        parser: {
+          validate: {
+            rules: {
+              openapi: {
+                'array-without-items': 'warning',
+                'duplicate-non-request-body-parameters': 'warning',
+                'duplicate-operation-id': 'warning',
+                'non-optional-path-parameters': 'warning',
+                'path-parameters-not-in-parameters': 'warning',
+                'path-parameters-not-in-path': 'warning',
+              },
+              swagger: {
+                'array-without-items': 'warning',
+                'duplicate-non-request-body-parameters': 'warning',
+                'duplicate-operation-id': 'warning',
+                'non-optional-path-parameters': 'warning',
+                'path-parameters-not-in-parameters': 'warning',
+                'path-parameters-not-in-path': 'warning',
+                'unknown-required-schema-property': 'warning',
+              },
+            },
+          },
+        },
+      });
+
+      if (!result.valid) {
+        for (const err of result.errors) {
+          results.push({
+            file: `reference/${filename}`,
+            rule: name,
+            message: err.message,
+          });
+        }
+      }
+
+      for (const warn of result.warnings) {
+        results.push({
+          file: `reference/${filename}`,
+          rule: name,
+          severity: 'warning',
+          message: warn.message,
+        });
+      }
+    } catch (err) {
+      results.push({
+        file: `reference/${filename}`,
+        rule: name,
+        message: err.message || String(err),
+      });
+    }
+
+    // Check for malformed $ref pointers (oas-normalize doesn't catch these).
+    for (const { path: refPath, ref } of findBadRefs(spec)) {
+      results.push({
+        file: `reference/${filename}`,
+        rule: name,
+        message: `Malformed $ref: "${ref}" at ${refPath} (should start with "#/")`,
+      });
+    }
+  }
+
+  return results;
+}

package/src/validators/ordering.js

@@ -0,0 +1,121 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export const name = 'ordering';
+
+// Content directories where _order.yaml is expected.
+const ORDERED_DIRS = ['docs', 'recipes', 'custom_pages'];
+
+// Values that YAML interprets as non-strings and need quoting in _order.yaml.
+const YAML_UNSAFE = /^(?:\d+\.?\d*|true|false|yes|no|on|off|null|~)$/i;
+function yamlSafeSlug(slug) {
+  return YAML_UNSAFE.test(slug) ? `"${slug}"` : slug;
+}
+
+function slugFromFile(filename) {
+  return filename.replace(/\.(md|mdx)$/, '');
+}
+
+function parseOrderYaml(content) {
+  return content
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.startsWith('- '))
+    .map((line) => line.slice(2).trim().replace(/^(['"])(.*)\1$/, '$2'));
+}
+
+/**
+ * Find all directories that contain content and check their _order.yaml.
+ */
+export function validateAll(files, gitRoot, { fix } = {}) {
+  const results = [];
+
+  // Group files by their immediate parent directory.
+  const dirContents = new Map();
+  for (const relPath of files) {
+    const topDir = relPath.split('/')[0];
+    if (!ORDERED_DIRS.includes(topDir)) continue;
+
+    const dir = path.dirname(relPath);
+    if (!dirContents.has(dir)) dirContents.set(dir, { files: [], subdirs: new Set() });
+
+    const filename = path.basename(relPath);
+    dirContents.get(dir).files.push(filename);
+
+    // Track subdirectories in the parent so we know about categories/nested dirs.
+    const parts = relPath.split('/');
+    if (parts.length > 2) {
+      const parentDir = parts.slice(0, -2).join('/');
+      const subdir = parts[parts.length - 2];
+      if (!dirContents.has(parentDir)) dirContents.set(parentDir, { files: [], subdirs: new Set() });
+      dirContents.get(parentDir).subdirs.add(subdir);
+    }
+  }
+
+  for (const [dir, { files: dirFiles, subdirs }] of dirContents) {
+    const orderPath = path.join(gitRoot, dir, '_order.yaml');
+
+    // Collect expected slugs: files (excluding index.md) + subdirectories.
+    const expectedSlugs = [];
+    for (const f of dirFiles) {
+      if (f === 'index.md' || f === 'index.mdx') continue;
+      expectedSlugs.push(slugFromFile(f));
+    }
+    for (const sub of subdirs) {
+      expectedSlugs.push(sub);
+    }
+
+    if (!fs.existsSync(orderPath)) {
+      if (expectedSlugs.length === 0) continue;
+
+      results.push({
+        file: path.join(dir, '_order.yaml'),
+        rule: name,
+        severity: 'warning',
+        fixable: true,
+        message: `Missing order: _order.yaml not found (${expectedSlugs.length} ${expectedSlugs.length === 1 ? 'entry needs' : 'entries need'} ordering)`,
+        _fix: { orderPath, missing: expectedSlugs },
+      });
+      continue;
+    }
+
+    const content = fs.readFileSync(orderPath, 'utf-8');
+    const ordered = new Set(parseOrderYaml(content));
+    const missing = expectedSlugs.filter((slug) => !ordered.has(slug));
+
+    if (missing.length > 0) {
+      results.push({
+        file: path.join(dir, '_order.yaml'),
+        rule: name,
+        severity: 'warning',
+        fixable: true,
+        message: `Missing from _order.yaml: ${missing.join(', ')}`,
+        _fix: { orderPath, missing },
+      });
+    }
+  }
+
+  // Apply fixes if requested.
+  if (fix) {
+    for (const r of results) {
+      if (!r._fix) continue;
+      const { orderPath, missing } = r._fix;
+      const newEntries = missing.map((slug) => `- ${yamlSafeSlug(slug)}`).join('\n');
+
+      if (fs.existsSync(orderPath)) {
+        const existing = fs.readFileSync(orderPath, 'utf-8');
+        const sep = existing.endsWith('\n') ? '' : '\n';
+        fs.writeFileSync(orderPath, `${existing}${sep}${newEntries}\n`);
+      } else {
+        fs.mkdirSync(path.dirname(orderPath), { recursive: true });
+        fs.writeFileSync(orderPath, `${newEntries}\n`);
+      }
+
+      r.message += ' (fixed)';
+    }
+  }
+
+  // Strip internal _fix data before returning.
+  for (const r of results) delete r._fix;
+  return results;
+}