@readme/cli 0.0.31 → 0.2.0

package/src/utils/lint.js

@@ -1,15 +1,16 @@
-import fs from 'node:fs'
-import path from 'node:path'
-import * as componentsValidator from '../validators/components.js'
-import * as contentValidator from '../validators/content.js'
-import * as duplicatesValidator from '../validators/duplicates.js'
-import * as frontmatterValidator from '../validators/frontmatter.js'
-import * as linksValidator from '../validators/links.js'
-import * as nestingValidator from '../validators/nesting.js'
-import * as oasReferenceValidator from '../validators/oas-reference.js'
-import * as oasSchemaValidator from '../validators/oas-schema.js'
-import * as orderingValidator from '../validators/ordering.js'
-import * as recipesValidator from '../validators/recipes.js'
+import fs from 'node:fs';
+import path from 'node:path';
+
+import * as componentsValidator from '../validators/components.js';
+import * as contentValidator from '../validators/content.js';
+import * as duplicatesValidator from '../validators/duplicates.js';
+import * as frontmatterValidator from '../validators/frontmatter.js';
+import * as linksValidator from '../validators/links.js';
+import * as nestingValidator from '../validators/nesting.js';
+import * as oasReferenceValidator from '../validators/oas-reference.js';
+import * as oasSchemaValidator from '../validators/oas-schema.js';
+import * as orderingValidator from '../validators/ordering.js';
+import * as recipesValidator from '../validators/recipes.js';
 
 const TARGET_PATTERNS = [
   { dir: 'custom_blocks', ext: ['.mdx', '.md'] },
@@ -17,28 +18,28 @@ const TARGET_PATTERNS = [
   { dir: 'reference', ext: '.md' },
   { dir: 'custom_pages', ext: '.md' },
   { dir: 'recipes', ext: '.md' },
-]
+];
 
 /**
  * Collect all target files from the repo root.
  */
 export function collectFiles(gitRoot) {
-  const files = []
+  const files = [];
 
   for (const { dir, ext } of TARGET_PATTERNS) {
-    const dirPath = path.join(gitRoot, dir)
-    if (!fs.existsSync(dirPath)) continue
+    const dirPath = path.join(gitRoot, dir);
+    if (!fs.existsSync(dirPath)) continue;
 
-    const exts = Array.isArray(ext) ? ext : [ext]
-    const entries = fs.readdirSync(dirPath, { recursive: true })
+    const exts = Array.isArray(ext) ? ext : [ext];
+    const entries = fs.readdirSync(dirPath, { recursive: true });
     for (const entry of entries) {
-      if (exts.some((e) => entry.endsWith(e))) {
-        files.push(path.join(dir, entry))
+      if (exts.some(e => entry.endsWith(e))) {
+        files.push(path.join(dir, entry));
       }
     }
   }
 
-  return files.sort()
+  return files.sort();
 }
 
 // Every validator in src/validators/, imported statically (rather than
@@ -57,14 +58,14 @@ const ALL_VALIDATORS = [
   oasSchemaValidator,
   orderingValidator,
   recipesValidator,
-]
+];
 
 /**
  * Validators can export `validate()` for per-file checks and/or
  * `validateAll()` for cross-file checks (like ordering).
  */
 function loadValidators() {
-  return ALL_VALIDATORS.filter((mod) => mod.name && (mod.validate || mod.validateAll))
+  return ALL_VALIDATORS.filter(mod => mod.name && (mod.validate || mod.validateAll));
 }
 
 /**
@@ -73,42 +74,42 @@ function loadValidators() {
  * Calls `onFile(relativePath)` before processing each file (for progress reporting).
  */
 export async function runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive } = {}) {
-  const validators = await loadValidators()
-  const results = []
+  const validators = await loadValidators();
+  const results = [];
 
   // Per-file validators.
   for (const relativePath of files) {
-    if (onFile) onFile(relativePath)
+    if (onFile) onFile(relativePath);
 
-    const filePath = path.join(gitRoot, relativePath)
-    const content = fs.readFileSync(filePath, 'utf-8')
+    const filePath = path.join(gitRoot, relativePath);
+    const content = fs.readFileSync(filePath, 'utf-8');
 
     for (const validator of validators) {
-      if (!validator.validate) continue
-      const result = validator.validate({ filePath, content, relativePath, fix })
+      if (!validator.validate) continue;
+      const result = validator.validate({ filePath, content, relativePath, fix });
       if (result) {
         if (Array.isArray(result)) {
-          results.push(...result)
+          results.push(...result);
         } else {
-          results.push(result)
+          results.push(result);
         }
       }
     }
   }
 
   // Cross-file validators — stop the spinner first so interactive prompts work.
-  if (onBeforeCrossFile) onBeforeCrossFile()
+  if (onBeforeCrossFile) onBeforeCrossFile();
   for (const validator of validators) {
-    if (!validator.validateAll) continue
-    const result = await validator.validateAll(files, gitRoot, { fix, nonInteractive })
+    if (!validator.validateAll) continue;
+    const result = await validator.validateAll(files, gitRoot, { fix, nonInteractive });
     if (result) {
       if (Array.isArray(result)) {
-        results.push(...result)
+        results.push(...result);
       } else {
-        results.push(result)
+        results.push(result);
       }
     }
   }
 
-  return results
+  return results;
 }

package/src/utils/llms.js

@@ -1,15 +1,15 @@
-const H1_RE = /^#\s+(.+)$/
-const H2_RE = /^##\s+(.+)$/
-const H3_RE = /^###\s+(.+)$/
+const H1_RE = /^#\s+(.+)$/;
+const H2_RE = /^##\s+(.+)$/;
+const H3_RE = /^###\s+(.+)$/;
 
 // llms.txt might have a literal " (section)" marker to every
 // grouping heading (e.g. `## getting-started (section)`). It's internal
 // metadata, not part of the category name — strip it before it reaches the sidebar.
-const SECTION_MARKER_RE = /\s*\(section\)\s*$/i
+const SECTION_MARKER_RE = /\s*\(section\)\s*$/i;
 
 // Max items per section before we consider it "oversized" for usability purposes.
 // Mirrors the cap in usableSections() in import.js.
-const MAX_SECTION_ITEMS = 200
+const MAX_SECTION_ITEMS = 200;
 // Any line whose meaningful content is a markdown link. Accepts:
 //   - Standard list rows:           `- [text](url)`, `* [text](url) — desc`
 //   - Bare link lines:              `[text](url)`
@@ -20,9 +20,10 @@ const MAX_SECTION_ITEMS = 200
 //     breadcrumb sits between the url and the description and is matched-and-discarded:
 //       `[text](url) (Breadcrumb > path): description`
 // Captures: [prefix, text, url, description] (prefix and description may be empty).
-const LINK_LINE_RE = /^\s*(?:[-*+]\s+)?([^\[\n]*?)\s*\[([^\]]+)\] ?\(([^)\s]+)\)(?:\s+\([^)]*\))?(?:\s*[:—–-]\s*(.+?))?\s*$/
-const BLOCKQUOTE_RE = /^\s*>/
-const FENCE_RE = /^\s*(?:```|~~~)/
+const LINK_LINE_RE =
+  /^\s*(?:[-*+]\s+)?([^[\n]*?)\s*\[([^\]]+)\] ?\(([^)\s]+)\)(?:\s+\([^)]*\))?(?:\s*[:—–-]\s*(.+?))?\s*$/;
+const BLOCKQUOTE_RE = /^\s*>/;
+const FENCE_RE = /^\s*(?:```|~~~)/;
 
 // A llms.txt is considered usable as long as it has at least one link row.
 // Beyond that we enforce a structural ratio (share of "spec-shaped" lines —
@@ -31,81 +32,81 @@ const FENCE_RE = /^\s*(?:```|~~~)/
 // 3-link file with one prose sentence would compute a misleading ratio; we
 // can't tell signal from noise at that size, so we trust it and let the
 // BFS-merge dedupe handle any junk that slips through.
-const RATIO_CHECK_MIN_LINKS = 10
-const MIN_CONFORMING_RATIO = 0.7
+const RATIO_CHECK_MIN_LINKS = 10;
+const MIN_CONFORMING_RATIO = 0.7;
 
 export function analyzeLlmsTxt(body, llmsUrl, options = {}) {
-  const parsed = parseLlmsTxt(body, llmsUrl, options)
-  const lineStats = classifyLines(body)
-  const linkItems = parsed.sections.reduce((sum, s) => sum + s.items.length, 0)
-  const reason = getSkipReason(body, linkItems, lineStats)
+  const parsed = parseLlmsTxt(body, llmsUrl, options);
+  const lineStats = classifyLines(body);
+  const linkItems = parsed.sections.reduce((sum, s) => sum + s.items.length, 0);
+  const reason = getSkipReason(body, linkItems, lineStats);
 
   return {
     parsed,
     usable: !reason,
     reason,
     stats: { ...lineStats, linkItems },
-  }
+  };
 }
 
 export function parseLlmsTxt(body, llmsUrl, options = {}) {
-  const h2Result = parseSections(body, llmsUrl, H2_RE, options)
+  const h2Result = parseSections(body, llmsUrl, H2_RE, options);
 
   // If every H2 section is oversized (or there are none), and the file has H3
   // headings, re-parse treating H3 (###) as section boundaries.
   // For strange LLMS.txt formatting
-  const allOversized = h2Result.sections.length === 0 ||
-    h2Result.sections.every((s) => s.items.length > MAX_SECTION_ITEMS)
+  const allOversized =
+    h2Result.sections.length === 0 || h2Result.sections.every(s => s.items.length > MAX_SECTION_ITEMS);
   if (allOversized && /^###\s/m.test(body)) {
-    const h3Result = parseSections(body, llmsUrl, H3_RE, options)
+    const h3Result = parseSections(body, llmsUrl, H3_RE, options);
     if (h3Result.sections.length > 1) {
-      return { ...h3Result, h3Fallback: true }
+      return { ...h3Result, h3Fallback: true };
     }
   }
 
-  return h2Result
+  return h2Result;
 }
 
 function parseSections(body, llmsUrl, sectionRe, options = {}) {
-  const lines = body.split(/\r?\n/)
-  let title = null
-  const sections = []
-  let current = null
+  const lines = body.split(/\r?\n/);
+  let title = null;
+  const sections = [];
+  let current = null;
 
   for (const line of lines) {
-    const h1 = line.match(H1_RE)
+    const h1 = line.match(H1_RE);
     if (h1 && !title) {
-      title = h1[1].trim()
-      continue
+      title = h1[1].trim();
+      continue;
     }
 
-    const sectionMatch = line.match(sectionRe)
+    const sectionMatch = line.match(sectionRe);
     if (sectionMatch) {
-      current = { title: sectionMatch[1].trim().replace(SECTION_MARKER_RE, '').trim(), items: [] }
-      sections.push(current)
-      continue
+      current = { title: sectionMatch[1].trim().replace(SECTION_MARKER_RE, '').trim(), items: [] };
+      sections.push(current);
+      continue;
     }
 
-    const item = parseListLink(line, llmsUrl, options)
-    if (!item) continue
+    const item = parseListLink(line, llmsUrl, options);
+    if (!item) continue;
 
     if (!current) {
-      current = { title: 'Resources', items: [] }
-      sections.push(current)
+      current = { title: 'Resources', items: [] };
+      sections.push(current);
     }
-    current.items.push(item)
+    current.items.push(item);
   }
 
-  return { title, sections }
+  return { title, sections };
 }
 
 function getSkipReason(body, linkItems, lineStats) {
-  if (/^---\r?\n/.test(body)) return 'starts with YAML frontmatter'
-  if (linkItems === 0) return 'no link items'
+  if (/^---\r?\n/.test(body)) return 'starts with YAML frontmatter';
+  if (linkItems === 0) return 'no link items';
   if (linkItems >= RATIO_CHECK_MIN_LINKS && lineStats.ratio < MIN_CONFORMING_RATIO) {
-    return `conforming-line ratio ${lineStats.ratio.toFixed(2)} below ${MIN_CONFORMING_RATIO} (${lineStats.conforming}/${lineStats.total} lines)`
+    return `conforming-line ratio ${lineStats.ratio.toFixed(2)} below ${MIN_CONFORMING_RATIO} (${lineStats.conforming}/${lineStats.total} lines)`;
   }
-  return null
+  return null;
 }
 
 /**
@@ -116,109 +117,111 @@ function getSkipReason(body, linkItems, lineStats) {
  *                  of) a fenced code block
  */
 function classifyLines(body) {
-  const lines = body.split(/\r?\n/)
-  let inFence = false
-  let conforming = 0
-  let nonConforming = 0
+  const lines = body.split(/\r?\n/);
+  let inFence = false;
+  let conforming = 0;
+  let nonConforming = 0;
 
   for (const line of lines) {
     if (FENCE_RE.test(line)) {
-      nonConforming++
-      inFence = !inFence
-      continue
+      nonConforming++;
+      inFence = !inFence;
+      continue;
     }
     if (inFence) {
-      nonConforming++
-      continue
+      nonConforming++;
+      continue;
     }
     if (line.trim() === '') {
-      conforming++
-      continue
+      conforming++;
+      continue;
     }
     if (H1_RE.test(line) || H2_RE.test(line) || LINK_LINE_RE.test(line) || BLOCKQUOTE_RE.test(line)) {
-      conforming++
-      continue
+      conforming++;
+      continue;
     }
-    nonConforming++
+    nonConforming++;
   }
 
-  const total = conforming + nonConforming
-  const ratio = total === 0 ? 0 : conforming / total
-  return { conforming, nonConforming, total, ratio }
+  const total = conforming + nonConforming;
+  const ratio = total === 0 ? 0 : conforming / total;
+  return { conforming, nonConforming, total, ratio };
 }
 
 function parseListLink(line, llmsUrl, options = {}) {
-  const match = line.match(LINK_LINE_RE)
-  if (!match) return null
+  const match = line.match(LINK_LINE_RE);
+  if (!match) return null;
 
-  const [, prefix, text, rawUrl, trailingDesc] = match
-  const url = normalizeUrl(rawUrl, llmsUrl, options)
-  if (!url) return null
+  const [, prefix, text, rawUrl, trailingDesc] = match;
+  const url = normalizeUrl(rawUrl, llmsUrl, options);
+  if (!url) return null;
 
   // Prefer an explicit trailing description (`[text](url) — desc`); fall back
   // to the breadcrumb prefix (`API Reference > Agents [text](url)`) when no
   // explicit description is present. Either gives downstream extra context.
-  const description = trailingDesc?.trim() || prefix?.trim() || null
+  const description = trailingDesc?.trim() || prefix?.trim() || null;
 
   return {
     text: text.trim(),
     url,
     description: description || null,
-  }
+  };
 }
 
 function normalizeUrl(rawUrl, llmsUrl, options = {}) {
-  const trimmed = String(rawUrl || '').trim().replace(/[.,;]+$/, '')
-  if (!trimmed || /^#/.test(trimmed) || /^(mailto|javascript):/i.test(trimmed)) return null
+  const trimmed = String(rawUrl || '')
+    .trim()
+    .replace(/[.,;]+$/, '');
+  if (!trimmed || trimmed.startsWith('#') || /^(mailto|javascript):/i.test(trimmed)) return null;
 
   try {
-    const url = llmsUrl ? new URL(resolveLlmsRelativeUrl(trimmed, llmsUrl, options), llmsUrl) : new URL(trimmed)
-    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null
-    return url.toString()
+    const url = llmsUrl ? new URL(resolveLlmsRelativeUrl(trimmed, llmsUrl, options), llmsUrl) : new URL(trimmed);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:') return null;
+    return url.toString();
   } catch {
-    return null
+    return null;
   }
 }
 
 function resolveLlmsRelativeUrl(trimmed, llmsUrl, options) {
-  if (options.rootRelativeResolution !== 'llms-dir' || !isRootRelativeUrl(trimmed)) return trimmed
+  if (options.rootRelativeResolution !== 'llms-dir' || !isRootRelativeUrl(trimmed)) return trimmed;
 
-  const nestedPrefix = getLlmsNestedPrefix(llmsUrl)
-  if (!nestedPrefix) return trimmed
+  const nestedPrefix = getLlmsNestedPrefix(llmsUrl);
+  if (!nestedPrefix) return trimmed;
 
-  const normallyResolved = new URL(trimmed, llmsUrl)
-  if (!shouldResolveRootRelativeFromLlmsDir(trimmed, normallyResolved.pathname, nestedPrefix)) return trimmed
+  const normallyResolved = new URL(trimmed, llmsUrl);
+  if (!shouldResolveRootRelativeFromLlmsDir(trimmed, normallyResolved.pathname, nestedPrefix)) return trimmed;
 
-  return `.${trimmed}`
+  return `.${trimmed}`;
 }
 
 function shouldResolveRootRelativeFromLlmsDir(rawUrl, pathname, nestedPrefix) {
-  if (isPathWithinPrefix(pathname, nestedPrefix)) return false
-  if (/\/llms\.txt$/i.test(pathname)) return false
+  if (isPathWithinPrefix(pathname, nestedPrefix)) return false;
+  if (/\/llms\.txt$/i.test(pathname)) return false;
 
-  const lastSegment = pathname.split('/').pop() || ''
-  const ext = lastSegment.match(/\.([a-z0-9]+)$/i)?.[1]?.toLowerCase()
-  if (ext && !['htm', 'html', 'md', 'mdx'].includes(ext)) return false
+  const lastSegment = pathname.split('/').pop() || '';
+  const ext = lastSegment.match(/\.([a-z0-9]+)$/i)?.[1]?.toLowerCase();
+  if (ext && !['htm', 'html', 'md', 'mdx'].includes(ext)) return false;
 
-  return isRootRelativeUrl(rawUrl)
+  return isRootRelativeUrl(rawUrl);
 }
 
 function getLlmsNestedPrefix(llmsUrl) {
-  if (!llmsUrl) return null
+  if (!llmsUrl) return null;
 
   try {
-    const pathname = new URL(llmsUrl).pathname
-    const dir = pathname.replace(/llms\.txt$/i, '').replace(/\/+$/, '/')
-    return dir === '/' ? null : dir
+    const pathname = new URL(llmsUrl).pathname;
+    const dir = pathname.replace(/llms\.txt$/i, '').replace(/\/+$/, '/');
+    return dir === '/' ? null : dir;
   } catch {
-    return null
+    return null;
   }
 }
 
 function isRootRelativeUrl(rawUrl) {
-  return /^\/(?!\/)/.test(rawUrl)
+  return /^\/(?!\/)/.test(rawUrl);
 }
 
 function isPathWithinPrefix(pathname, prefix) {
-  return pathname === prefix.replace(/\/$/, '') || pathname.startsWith(prefix)
+  return pathname === prefix.replace(/\/$/, '') || pathname.startsWith(prefix);
 }