@readme/cli 0.0.26

package/src/utils/tips.js

@@ -0,0 +1,90 @@
+import * as styles from './styles.js';
+import { loadPet } from './tamagotchi.js';
+
+const tips = [
+  {
+    weight: 1,
+    commands: ['lint', 'oas:validate'],
+    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`)}`);
+      console.log();
+    },
+  },
+  {
+    weight: 1,
+    commands: ['lint', 'oas:validate'],
+    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!`);
+      console.log(`     ${styles.dim('⎿')}  ${styles.orange(`${styles.binName()} setup`)}`);
+      console.log();
+    },
+  },
+  {
+    weight: 1,
+    commands: ['lint', 'oas:validate'],
+    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();
+    },
+  },
+  {
+    weight: 1,
+    commands: ['lint', 'oas:validate'],
+    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')}`);
+      console.log();
+    },
+  },
+  {
+    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();
+    },
+  },
+  {
+    weight: 0.3,
+    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();
+    },
+  },
+];
+
+/**
+ * Get a random tip, optionally filtered by command name.
+ * @param {object} context
+ * @param {string} [context.command] - current command name (e.g. 'lint', 'help')
+ */
+export function getRandomTip(context) {
+  const cmd = context.command;
+  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
+    return t.condition(context);
+  });
+  if (eligible.length === 0) return null;
+
+  // Weighted random selection
+  const totalWeight = eligible.reduce((sum, t) => sum + (t.weight || 1), 0);
+  let rand = Math.random() * totalWeight;
+  let chosen = eligible[eligible.length - 1];
+  for (const tip of eligible) {
+    rand -= tip.weight || 1;
+    if (rand <= 0) { chosen = tip; break; }
+  }
+  // Bind context so render() can read it without a second argument.
+  return { render: () => chosen.render(context) };
+}

package/src/validators/components.js

@@ -0,0 +1,230 @@
+import fs from "node:fs";
+import path from "node:path";
+import matter from "gray-matter";
+import markdown from "@readme/markdown";
+
+const { mdxishTags } = markdown;
+
+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",
+  // Available from @readme/markdown
+  "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"]);
+
+/**
+ * Extract component tag names from MDXish content.
+ * Parses via @readme/markdown's mdxishTags so code blocks, inline code, and
+ * HTML comments are respected as markdown (tags inside them aren't components).
+ */
+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]*?---/, "");
+  }
+
+  try {
+    return new Set(mdxishTags(body));
+  } catch {
+    return new Set();
+  }
+}
+
+/**
+ * Extract exported component names from .mdx file body.
+ * Matches: export const Foo, export function Foo, export default function Foo
+ */
+function extractExportedNames(body) {
+  const names = new Set();
+  const pattern = /export\s+(?:const|function|class)\s+([A-Z][a-zA-Z0-9]*)/g;
+  let match;
+  while ((match = pattern.exec(body)) !== null) {
+    names.add(match[1]);
+  }
+  return names;
+}
+
+/**
+ * Collect available custom block component names from custom_blocks/.
+ * .mdx files: uses the actual exported component names (e.g., export const Foo → <Foo />).
+ * .md files: uses the filename slug (e.g., Greeting.md → <Greeting />).
+ */
+function collectCustomBlockNames(gitRoot) {
+  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;
+
+    try {
+      const content = fs.readFileSync(path.join(blocksDir, entry), "utf-8");
+
+      if (entry.endsWith(".mdx")) {
+        // .mdx: component names come from exports.
+        const { content: body } = matter(content);
+        for (const n of extractExportedNames(body)) {
+          names.add(n);
+        }
+      } else {
+        // .md snippet: component name is the PascalCase filename.
+        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("");
+        names.add(pascalCase);
+      }
+    } catch {
+      // Skip unparseable files.
+    }
+  }
+
+  return names;
+}
+
+/**
+ * Per-file: validate custom_block files.
+ * - .mdx: must have an exported component and a usage example
+ * - .md: filename must be capitalized (used as component name via <Name />)
+ */
+export function validate({ content, relativePath }) {
+  if (!relativePath.startsWith("custom_blocks/")) return null;
+
+  const filename = path.basename(relativePath);
+  const isMdx = relativePath.endsWith(".mdx");
+  const isMd = relativePath.endsWith(".md");
+
+  if (!isMdx && !isMd) return null;
+
+  const results = [];
+
+  // .md snippet files: filename must be PascalCase (it becomes the component tag).
+  if (isMd) {
+    const slug = filename.replace(/\.md$/, "");
+    const pascalCase = slug
+      .split(/[-_]/)
+      .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+      .join("");
+    if (slug !== pascalCase) {
+      results.push({
+        file: relativePath,
+        rule: name,
+        severity: "warning",
+        message: `Bad filename: should be PascalCase — rename to "${pascalCase}.md" so it can be used as <${pascalCase} />`,
+      });
+    }
+    return results.length > 0 ? results : null;
+  }
+
+  // .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.
+  }
+
+  const componentName = data.name;
+  if (!componentName) return null; // frontmatter validator handles missing name.
+
+  // Check for an exported component.
+  // Matches: export const Name, export function Name, export default
+  const hasExport = /export\s+(const|function|default)\s+/.test(body);
+  if (!hasExport) {
+    results.push({
+      file: relativePath,
+      rule: name,
+      message: `Missing export: no exported component found in "${componentName}"`,
+    });
+  }
+
+  // Check for a usage example — a component tag at the start of a line (not indented
+  // inside an export). The example demonstrates the component for the slash menu preview.
+  const hasExample = /^<[A-Z][a-zA-Z0-9]*/m.test(body);
+  if (!hasExample) {
+    results.push({
+      file: relativePath,
+      rule: name,
+      severity: "warning",
+      message: `Missing example: no usage example found for "${componentName}"`,
+    });
+  }
+
+  return results.length > 0 ? results : null;
+}
+
+/**
+ * Cross-file: check that all component references in content files resolve.
+ */
+export function validateAll(files, gitRoot) {
+  const results = [];
+  const customBlocks = collectCustomBlockNames(gitRoot);
+  const available = new Set([...BUILTIN_COMPONENTS, ...customBlocks]);
+
+  for (const relPath of files) {
+    const dir = relPath.split("/")[0];
+    if (!CONTENT_DIRS.has(dir)) continue;
+    if (!relPath.endsWith(".md")) continue;
+
+    const filePath = path.join(gitRoot, relPath);
+    let content;
+    try {
+      content = fs.readFileSync(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+
+    const usedComponents = extractComponentTags(content);
+
+    for (const comp of usedComponents) {
+      if (!available.has(comp)) {
+        results.push({
+          file: relPath,
+          rule: name,
+          message: `Unknown component: <${comp}> is not a built-in or custom block`,
+        });
+      }
+    }
+  }
+
+  return results;
+}

package/src/validators/content.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+export const name = 'content';
+
+export function validate({ filePath, content, relativePath }) {
+  const dir = relativePath.split('/')[0];
+  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;
+  }
+
+  if (data.hidden || data.deprecated) return null;
+  if (data.api) return null;
+  const trimmed = body.trim();
+
+  if (data.link?.url) {
+    if (trimmed.length > 0) {
+      return {
+        file: relativePath,
+        rule: name,
+        severity: 'warning',
+        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.
+    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;
+      }
+    }
+
+    return {
+      file: relativePath,
+      rule: name,
+      severity: 'warning',
+      message: 'Empty page: non-hidden page has no content',
+    };
+  }
+
+  return null;
+}

package/src/validators/duplicates.js

@@ -0,0 +1,45 @@
+import path from 'node:path';
+
+export const name = 'duplicates';
+
+// Only docs and reference require unique slugs.
+const CHECKED_DIRS = ['docs', 'reference'];
+
+export function validateAll(files) {
+  const results = [];
+
+  // Group files by slug.
+  const slugMap = new Map();
+  for (const relPath of files) {
+    const topDir = relPath.split('/')[0];
+    if (!CHECKED_DIRS.includes(topDir)) continue;
+
+    const filename = path.basename(relPath);
+    if (filename === 'index.md' || filename === 'index.mdx') continue;
+
+    const slug = filename.replace(/\.(md|mdx)$/, '');
+    if (!slugMap.has(slug)) slugMap.set(slug, []);
+    slugMap.get(slug).push(relPath);
+  }
+
+  for (const [slug, paths] of slugMap) {
+    if (paths.length < 2) continue;
+
+    // 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;
+
+    const others = paths.slice(1);
+    for (const relPath of others) {
+      const otherLocations = paths.filter((p) => p !== relPath).map((p) => path.dirname(p)).join(', ');
+      results.push({
+        file: relPath,
+        rule: name,
+        severity: 'error',
+        message: `Duplicate slug: "${slug}" also exists in ${otherLocations}`,
+      });
+    }
+  }
+
+  return results.length > 0 ? results : null;
+}

package/src/validators/frontmatter.js

@@ -0,0 +1,247 @@
+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);
+
+export const name = 'frontmatter';
+
+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;
+    current = current[key];
+  }
+  return current;
+}
+
+// Levenshtein distance between two strings.
+function levenshtein(a, b) {
+  const m = a.length;
+  const n = b.length;
+  const dp = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
+  for (let i = 0; i <= m; i++) dp[i][0] = i;
+  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]);
+    }
+  }
+  return dp[m][n];
+}
+
+// Returns similarity ratio between 0 and 1.
+function similarity(a, b) {
+  const maxLen = Math.max(a.length, b.length);
+  if (maxLen === 0) return 1;
+  return 1 - levenshtein(a, b) / maxLen;
+}
+
+const TYPO_THRESHOLD = 0.7;
+
+// Recursively collect all known property names from a schema, following $ref and allOf.
+function collectPropertyNames(schema, defs) {
+  const props = new Set();
+
+  if (schema.properties) {
+    for (const k of Object.keys(schema.properties)) props.add(k);
+  }
+
+  if (schema.$ref?.startsWith('#/defs/')) {
+    const refSchema = defs[schema.$ref.slice('#/defs/'.length)];
+    if (refSchema) {
+      for (const k of collectPropertyNames(refSchema, defs)) props.add(k);
+    }
+  }
+
+  if (schema.allOf) {
+    for (const sub of schema.allOf) {
+      for (const k of collectPropertyNames(sub, defs)) props.add(k);
+    }
+  }
+
+  return props;
+}
+
+// Map directory names to their index in the schema's oneOf array.
+const DIR_SCHEMA_INDEX = {
+  docs: 0,
+  custom_pages: 1,
+  reference: 2,
+  recipes: 3,
+  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'));
+
+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] };
+  validators[dir] = ajv.compile(subSchema);
+  knownProperties[dir] = collectPropertyNames(subSchema, fullSchema.defs);
+}
+
+export function validate({ content, filePath, relativePath, fix }) {
+  // Step 1: Parse the frontmatter YAML.
+  let data;
+  try {
+    ({ data } = matter(content));
+  } catch (e) {
+    return {
+      file: relativePath,
+      rule: name,
+      message: `Invalid frontmatter: ${e.reason || e.message || 'unknown error'}`,
+    };
+  }
+
+  const results = [];
+  const dir = relativePath.split('/')[0];
+
+  // Step 2: Validate the parsed frontmatter against the schema.
+  const validateFn = validators[dir];
+  if (validateFn) {
+    const valid = validateFn(data);
+    if (!valid) {
+      for (const err of validateFn.errors) {
+        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;
+        }
+
+        let msg;
+        if (err.keyword === 'not' && err.schema?.description) {
+          msg = err.schema.description;
+        } else {
+          // Convert JSON pointer paths (/foo/bar) to dot notation (foo.bar).
+          const loc = err.instancePath ? err.instancePath.slice(1).replace(/\//g, '.') : '';
+          msg = loc ? `"${loc}" ${err.message}` : err.message;
+        }
+
+        results.push({
+          file: relativePath,
+          rule: name,
+          severity: 'error',
+          message: `Invalid frontmatter: ${msg}`,
+        });
+      }
+    }
+  }
+
+  // Step 3: Warn about unknown properties (allow x- prefix for custom metadata).
+  const allowed = knownProperties[dir];
+  const unknownKeys = [];
+  if (allowed && data && typeof data === 'object') {
+    for (const key of Object.keys(data)) {
+      if (!allowed.has(key) && !key.startsWith('x-')) {
+        unknownKeys.push(key);
+        results.push({
+          file: relativePath,
+          rule: name,
+          severity: 'warning',
+          fixable: true,
+          _key: key,
+          message: `Unknown property: "${key}" is not a known frontmatter field (use x-${key} for custom metadata)`,
+        });
+      }
+    }
+  }
+
+  // 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'),
+  );
+  const unknowns = results.filter((r) => r._key);
+
+  const consumed = new Set();
+
+  // First pass: match unknowns to missing required properties (these become errors).
+  for (const err of missingRequired) {
+    const match = err.message.match(/must have required property '(\w+)'/);
+    if (!match) continue;
+    const required = match[1];
+
+    let bestMatch = null;
+    let bestScore = 0;
+    for (const warn of unknowns) {
+      if (consumed.has(warn)) continue;
+      const score = similarity(required, warn._key);
+      if (score >= TYPO_THRESHOLD && score > bestScore) {
+        bestMatch = warn;
+        bestScore = score;
+      }
+    }
+
+    if (bestMatch) {
+      consumed.add(bestMatch);
+      err.message = `Invalid frontmatter: "${bestMatch._key}" is not a valid property — did you mean "${required}"?`;
+    }
+  }
+
+  // Second pass: match remaining unknowns to any known property (these stay as warnings).
+  const suggestedTypos = new Set();
+  if (allowed) {
+    for (const warn of unknowns) {
+      if (consumed.has(warn)) continue;
+
+      let bestProp = null;
+      let bestScore = 0;
+      for (const known of allowed) {
+        const score = similarity(warn._key, known);
+        if (score >= TYPO_THRESHOLD && score > bestScore) {
+          bestProp = known;
+          bestScore = score;
+        }
+      }
+
+      if (bestProp) {
+        suggestedTypos.add(warn._key);
+        warn.message = `Unknown property: "${warn._key}" — did you mean "${bestProp}"?`;
+      }
+    }
+  }
+
+  // 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));
+
+    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) {
+        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}:`);
+        }
+        fileContent = fileContent.replace(fmMatch[1], frontmatter);
+      }
+      fs.writeFileSync(filePath, fileContent, 'utf-8');
+
+      // Mark the corresponding warnings as fixed.
+      const keysToFixSet = new Set(keysToFix);
+      for (const r of results) {
+        if (r._key && keysToFixSet.has(r._key)) {
+          r.message += ' (fixed)';
+        }
+      }
+    }
+  }
+
+  // Remove consumed warnings (they've been merged into the error).
+  const final = results.filter((r) => !consumed.has(r));
+  return final.length > 0 ? final : null;
+}