@readme/cli 0.0.27 → 0.0.30

package/src/validators/ordering.js

@@ -3,8 +3,13 @@ import path from 'node:path';
 
 export const name = 'ordering';
 
-// Content directories where _order.yaml is expected.
-const ORDERED_DIRS = ['docs', 'recipes', 'custom_pages'];
+// Top-level content directories that use _order.yaml.
+const CONTENT_DIRS = ['docs', 'reference', 'recipes', 'custom_pages'];
+
+// Of those, the dirs that must list every page/folder. reference ordering is
+// OAS-managed, so we never flag pages "missing from" a reference _order.yaml —
+// but stale entries are flagged everywhere.
+const REQUIRE_ORDER = new Set(['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;
@@ -12,110 +17,191 @@ function yamlSafeSlug(slug) {
   return YAML_UNSAFE.test(slug) ? `"${slug}"` : slug;
 }
 
-function slugFromFile(filename) {
-  return filename.replace(/\.(md|mdx)$/, '');
+// Returns the slug a "- entry" line refers to, or null for any other line.
+// Handles quoted slugs and trailing inline comments (`- overview # comment`).
+function parseOrderEntry(line) {
+  const trimmed = line.trim();
+  if (!trimmed.startsWith('- ')) return null;
+  const value = trimmed.slice(2).trim();
+  const quoted = value.match(/^(['"])(.*)\1\s*(?:#.*)?$/);
+  if (quoted) return quoted[2];
+  const slug = value.replace(/(?:^|\s)#.*$/, '').trim();
+  return slug === '' ? null : slug;
 }
 
 function parseOrderYaml(content) {
   return content
     .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.startsWith('- '))
-    .map((line) => line.slice(2).trim().replace(/^(['"])(.*)\1$/, '$2'));
+    .map(parseOrderEntry)
+    .filter((entry) => entry !== null);
+}
+
+function isIndex(name) {
+  return name === 'index' || name === 'index.md' || name === 'index.mdx';
+}
+
+/**
+ * Walk a content directory tree once. For every directory, capture the on-disk
+ * slug set (child pages + child folders) and its _order.yaml entries (or null
+ * when absent), so the caller can diff the two in a single pass.
+ */
+function collectDirs(gitRoot, topDir) {
+  const base = path.join(gitRoot, topDir);
+  if (!fs.existsSync(base)) return [];
+
+  const dirs = [];
+  const stack = [base];
+  while (stack.length) {
+    const cur = stack.pop();
+    const onDisk = new Set();
+    let orderEntries = null;
+
+    for (const entry of fs.readdirSync(cur, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        onDisk.add(entry.name);
+        stack.push(path.join(cur, entry.name));
+      } else if (entry.name === '_order.yaml') {
+        orderEntries = parseOrderYaml(fs.readFileSync(path.join(cur, entry.name), 'utf-8'));
+      } else if (/\.(md|mdx)$/.test(entry.name) && !isIndex(entry.name)) {
+        onDisk.add(entry.name.replace(/\.(md|mdx)$/, ''));
+      }
+    }
+
+    dirs.push({ dir: cur, onDisk, orderEntries });
+  }
+  return dirs;
 }
 
 /**
- * Find all directories that contain content and check their _order.yaml.
+ * Validate every _order.yaml against the files and folders next to it:
+ *   - on disk but missing from _order.yaml  → "Missing from _order.yaml" (required dirs only)
+ *   - in _order.yaml but missing on disk     → "Stale entry"
+ *   - an index entry that shouldn't be listed → "Invalid entry"
  */
 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 topDir of CONTENT_DIRS) {
+    const requireOrder = REQUIRE_ORDER.has(topDir);
+
+    for (const { dir, onDisk, orderEntries } of collectDirs(gitRoot, topDir)) {
+      const orderPath = path.join(dir, '_order.yaml');
+      const relOrder = path.relative(gitRoot, orderPath);
+
+      // No _order.yaml at all: only required dirs need one.
+      if (orderEntries === null) {
+        if (requireOrder && onDisk.size > 0) {
+          const missing = [...onDisk].sort();
+          results.push({
+            file: relOrder,
+            rule: name,
+            severity: 'warning',
+            fixable: true,
+            message: `Missing order: _order.yaml not found (${missing.length} ${missing.length === 1 ? 'entry needs' : 'entries need'} ordering)`,
+            _fixAdd: { orderPath, missing },
+          });
+        }
+        continue;
+      }
 
-  for (const [dir, { files: dirFiles, subdirs }] of dirContents) {
-    const orderPath = path.join(gitRoot, dir, '_order.yaml');
+      const ordered = new Set(orderEntries);
+
+      // On disk but not ordered.
+      if (requireOrder) {
+        const missing = [...onDisk].filter((slug) => !ordered.has(slug)).sort();
+        if (missing.length > 0) {
+          results.push({
+            file: relOrder,
+            rule: name,
+            severity: 'warning',
+            fixable: true,
+            message: `Missing from _order.yaml: ${missing.join(', ')}`,
+            _fixAdd: { orderPath, missing },
+          });
+        }
+      }
 
-    // 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);
+      // Ordered but not on disk (or an index entry that shouldn't be listed).
+      for (const entry of orderEntries) {
+        if (isIndex(entry)) {
+          results.push({
+            file: relOrder,
+            rule: name,
+            severity: 'warning',
+            fixable: true,
+            message: `Invalid entry: "${entry}" should not be listed in _order.yaml`,
+            _fixRemove: { orderPath, entry },
+          });
+        } else if (!onDisk.has(entry)) {
+          results.push({
+            file: relOrder,
+            rule: name,
+            severity: 'warning',
+            fixable: true,
+            message: `Stale entry: "${entry}" in _order.yaml has no matching file or folder`,
+            _fixRemove: { orderPath, entry },
+          });
+        }
+      }
     }
+  }
 
-    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;
+  if (!fix) return strip(results);
+
+  // Additions: append missing slugs to the _order.yaml.
+  for (const r of results) {
+    if (!r._fixAdd) continue;
+    const { orderPath, missing } = r._fixAdd;
+    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)';
+  }
 
-    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 },
+  // Removals: group stale/index entries by order file, then rewrite each once.
+  const removalsByPath = new Map();
+  for (const r of results) {
+    if (!r._fixRemove) continue;
+    const { orderPath, entry } = r._fixRemove;
+    if (!removalsByPath.has(orderPath)) removalsByPath.set(orderPath, new Set());
+    removalsByPath.get(orderPath).add(entry);
+  }
+  for (const [orderPath, toRemove] of removalsByPath) {
+    if (!fs.existsSync(orderPath)) continue;
+    // Drop only the targeted entry lines, keeping comments, blank lines, and
+    // untouched entries exactly as written.
+    const kept = fs
+      .readFileSync(orderPath, 'utf-8')
+      .split('\n')
+      .filter((line) => {
+        const entry = parseOrderEntry(line);
+        return entry === null || !toRemove.has(entry);
       });
+    if (kept.some((line) => parseOrderEntry(line) !== null)) {
+      fs.writeFileSync(orderPath, kept.join('\n'));
+    } else {
+      fs.unlinkSync(orderPath);
     }
   }
+  for (const r of results) {
+    if (r._fixRemove) r.message += ' (fixed)';
+  }
 
-  // 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`);
-      }
+  return strip(results);
+}
 
-      r.message += ' (fixed)';
-    }
+// Remove internal fix descriptors before returning results to the reporter.
+function strip(results) {
+  for (const r of results) {
+    delete r._fixAdd;
+    delete r._fixRemove;
   }
-
-  // Strip internal _fix data before returning.
-  for (const r of results) delete r._fix;
   return results;
 }

package/vendor/TOOLS.md

@@ -4,7 +4,7 @@ The ReadMe CLI (`npx @readme/cli`) has several commands that can help fix issues
 
 ## `npx @readme/cli lint --fix`
 
-Automatically fixes common linting issues: ordering problems, frontmatter cleanup, numbering suffixes, etc. Always try this first.
+Automatically fixes common linting issues: ordering problems, frontmatter cleanup, etc. Always try this first.
 
 ## `npx @readme/cli oas:sync`
 

package/src/dev/.next/app-build-manifest.json

@@ -1,20 +0,0 @@
-{
-  "pages": {
-    "/layout": [
-      "static/chunks/webpack.js",
-      "static/chunks/main-app.js",
-      "static/css/app/layout.css",
-      "static/chunks/app/layout.js"
-    ],
-    "/[...slug]/loading": [
-      "static/chunks/webpack.js",
-      "static/chunks/main-app.js",
-      "static/chunks/app/[...slug]/loading.js"
-    ],
-    "/[...slug]/page": [
-      "static/chunks/webpack.js",
-      "static/chunks/main-app.js",
-      "static/chunks/app/[...slug]/page.js"
-    ]
-  }
-}

package/src/dev/.next/build-manifest.json

@@ -1,31 +0,0 @@
-{
-  "polyfillFiles": [
-    "static/chunks/polyfills.js"
-  ],
-  "devFiles": [
-    "static/chunks/react-refresh.js"
-  ],
-  "ampDevFiles": [],
-  "lowPriorityFiles": [
-    "static/development/_buildManifest.js",
-    "static/development/_ssgManifest.js"
-  ],
-  "rootMainFiles": [
-    "static/chunks/webpack.js",
-    "static/chunks/main-app.js"
-  ],
-  "rootMainFilesTree": {},
-  "pages": {
-    "/_app": [
-      "static/chunks/webpack.js",
-      "static/chunks/main.js",
-      "static/chunks/pages/_app.js"
-    ],
-    "/_error": [
-      "static/chunks/webpack.js",
-      "static/chunks/main.js",
-      "static/chunks/pages/_error.js"
-    ]
-  },
-  "ampFirstPages": []
-}

package/src/dev/.next/cache/.rscinfo

@@ -1 +0,0 @@
-{"encryption.key":"3SIKRvTdjH2KvDXOUMwtVkaVmj4v5oCsYq33R2HYXtM=","encryption.expire_at":1772814750891}

package/src/dev/.next/cache/next-devtools-config.json

@@ -1 +0,0 @@
-{}

package/src/dev/.next/package.json

@@ -1 +0,0 @@
-{"type": "commonjs"}

package/src/dev/.next/prerender-manifest.json

@@ -1,11 +0,0 @@
-{
-  "version": 4,
-  "routes": {},
-  "dynamicRoutes": {},
-  "notFoundRoutes": [],
-  "preview": {
-    "previewModeId": "b628b03ee18bb42bb63fcc51ca49946f",
-    "previewModeSigningKey": "f82f45cc5833fe189f9cc960b8dd1be2c6c51a3c05cf345f3497ced03b8c7b0d",
-    "previewModeEncryptionKey": "ab192619b9dd28eb198eda117db9c62df8ca0dba79469500b34cdcdf2b290da3"
-  }
-}

package/src/dev/.next/react-loadable-manifest.json

@@ -1 +0,0 @@
-{}

package/src/dev/.next/routes-manifest.json

@@ -1 +0,0 @@
-{"version":3,"caseSensitive":false,"basePath":"","rewrites":{"beforeFiles":[],"afterFiles":[],"fallback":[]},"redirects":[{"source":"/:path+/","destination":"/:path+","permanent":true,"internal":true,"regex":"^(?:\\/((?:[^\\/]+?)(?:\\/(?:[^\\/]+?))*))\\/$"}],"headers":[]}