@readme/cli 0.0.31 → 0.2.0

package/src/commands/lint.js

@@ -1,20 +1,20 @@
-import { collectFiles, runValidators } from '../utils/lint.js'
-import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js'
-import { printHeader, isAgenticCli } from '../utils/eyes.js'
-import * as styles from '../utils/styles.js'
-import { writeGithubActionsOutputs } from '../utils/gha-output.js'
-import pkg from '../../package.json' with { type: 'json' }
+import pkg from '../../package.json' with { type: 'json' };
+import { printHeader, isAgenticCli } from '../utils/eyes.js';
+import { writeGithubActionsOutputs } from '../utils/gha-output.js';
+import { collectFiles, runValidators } from '../utils/lint.js';
+import { createHumanReporter, createJsonReporter, createGithubReporter } from '../utils/reporter.js';
+import * as styles from '../utils/styles.js';
 
-export const command = 'lint'
-export const order = 1
-export const aliases = ['validate']
-export const category = 'Linting'
-export const description = 'Lint and validate your ReadMe docs'
+export const command = 'lint';
+export const order = 1;
+export const aliases = ['validate'];
+export const category = 'Linting';
+export const description = 'Lint and validate your ReadMe docs';
 
 export function args(cmd) {
-  cmd.option('--json', 'Output results as JSON (for CI and automation)')
-  cmd.option('--github', 'Output a GitHub PR comment body as markdown')
-  cmd.option('--fix', 'Automatically fix issues where possible')
+  cmd.option('--json', 'Output results as JSON (for CI and automation)');
+  cmd.option('--github', 'Output a GitHub PR comment body as markdown');
+  cmd.option('--fix', 'Automatically fix issues where possible');
 }
 
 /**
@@ -31,37 +31,41 @@ export function args(cmd) {
  * @returns {Promise<{ gitRoot: string, files: string[], results: object[], hasErrors: boolean }>}
  */
 export async function lint({ cwd, fix = false, nonInteractive = false, onFile, onBeforeCrossFile } = {}) {
-  const gitRoot = cwd || process.cwd()
-  const files = collectFiles(gitRoot)
-  const results = await runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive })
-  const hasErrors = results.some((r) => r.severity !== 'warning')
-  return { gitRoot, files, results, hasErrors }
+  const gitRoot = cwd || process.cwd();
+  const files = collectFiles(gitRoot);
+  const results = await runValidators(files, gitRoot, { onFile, onBeforeCrossFile, fix, nonInteractive });
+  const hasErrors = results.some(r => r.severity !== 'warning');
+  return { gitRoot, files, results, hasErrors };
 }
 
 export async function run(options, _cmd, ctx) {
-  const { gitRoot } = ctx
+  const { gitRoot } = ctx;
 
   if (!options.json && !options.github && !isAgenticCli()) {
-    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' })
-    console.log()
+    printHeader({ version: pkg.version, binName: styles.binName(), indent: '  ' });
+    console.log();
   }
 
-  const reporter = options.github ? createGithubReporter() : options.json ? createJsonReporter() : createHumanReporter()
+  const reporter = options.github
+    ? createGithubReporter()
+    : options.json
+      ? createJsonReporter()
+      : createHumanReporter();
 
   const { files, results, hasErrors } = await lint({
     cwd: gitRoot,
     fix: options.fix,
-    onFile: (f) => reporter.onFile(f),
+    onFile: f => reporter.onFile(f),
     onBeforeCrossFile: () => reporter.pause(),
-  })
+  });
 
-  reporter.finish(files.length, results, files, { fix: options.fix, gitRoot })
+  reporter.finish(files.length, results, files, { fix: options.fix, gitRoot });
 
-  writeGithubActionsOutputs({ 'has-errors': String(hasErrors), results })
+  writeGithubActionsOutputs({ 'has-errors': String(hasErrors), results });
 
   if (hasErrors) {
     // Wait for stdout to flush (important when piped to a file), then exit
-    await new Promise((resolve) => process.stdout.write('', resolve))
-    process.exit(1)
+    await new Promise(resolve => process.stdout.write('', resolve));
+    process.exit(1);
   }
 }

package/src/commands/oas-bundle.js

@@ -0,0 +1,89 @@
+import fs from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+
+import { bundle } from '@readme/openapi-parser';
+
+import * as styles from '../utils/styles.js';
+
+const require = createRequire(import.meta.url);
+const yaml = require('js-yaml');
+
+export const command = 'oas:bundle';
+export const order = 4;
+export const category = 'OAS Tooling';
+export const description = 'Bundle a multi-file OpenAPI spec into a single file';
+// The input spec usually lives outside a ReadMe docs repo (e.g. the API's
+// source repo in CI), so don't require a version branch or docs/ dir.
+export const skipBootstrap = true;
+
+export function args(cmd) {
+  cmd
+    .argument('<spec>', 'Path to the root OpenAPI spec file (JSON or YAML)')
+    .option('-o, --out <path>', 'Write the bundled spec to this file instead of stdout');
+}
+
+/** Resolve external $refs into one document with only internal (#/...) pointers. */
+export async function bundleOas({ file, cwd } = {}) {
+  const specPath = path.resolve(cwd || process.cwd(), file);
+  if (!fs.existsSync(specPath)) {
+    throw new Error(`Spec file not found: ${specPath}`);
+  }
+  // Pass the path, not contents: openapi-parser then resolves relative $refs
+  // against the file's directory. oas-normalize reads first and loses that.
+  return bundle(specPath);
+}
+
+export function formatForPath(outPath) {
+  return /\.ya?ml$/i.test(outPath) ? 'yaml' : 'json';
+}
+
+export function serializeSpec(spec, format) {
+  if (format === 'yaml') return yaml.dump(spec, { noRefs: true, lineWidth: -1 });
+  return `${JSON.stringify(spec, null, 2)}\n`;
+}
+
+/** Bundle `file` and write it to `out` (format follows the extension). */
+export async function writeBundle({ file, out, cwd } = {}) {
+  const root = cwd || process.cwd();
+  const spec = await bundleOas({ file, cwd: root });
+  const outPath = path.resolve(root, out);
+  const format = formatForPath(outPath);
+
+  fs.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, serializeSpec(spec, format));
+
+  return { spec, outPath, format };
+}
+
+export async function run(specArg, options) {
+  try {
+    if (options.out) {
+      const { spec, outPath } = await writeBundle({ file: specArg, out: options.out });
+      const opCount = countOperations(spec);
+      const rel = path.relative(process.cwd(), outPath);
+      const shown = rel && !rel.startsWith('..') ? rel : outPath;
+      styles.ok(
+        `Bundled ${styles.bold(spec.info?.title || specArg)} (${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'}) → ${shown}`,
+      );
+      return;
+    }
+
+    const spec = await bundleOas({ file: specArg });
+    process.stdout.write(serializeSpec(spec, formatForPath(specArg)));
+  } catch (err) {
+    styles.error(`Bundle failed: ${err.message || String(err)}`);
+    process.exit(1);
+  }
+}
+
+const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
+
+function countOperations(spec) {
+  let n = 0;
+  for (const item of Object.values(spec.paths || {})) {
+    if (!item || typeof item !== 'object') continue;
+    for (const key of Object.keys(item)) if (HTTP_METHODS.has(key)) n += 1;
+  }
+  return n;
+}

package/src/commands/oas-sync.js

@@ -1,12 +1,11 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { createRequire } from 'node:module';
-import matter from 'gray-matter';
-import * as styles from '../utils/styles.js';
-import { writeGithubActionsOutputs } from '../utils/gha-output.js';
 
-const require = createRequire(import.meta.url);
-const yaml = require('js-yaml');
+import { CORE_SCHEMA, load as loadYAML, mergeTag } from 'js-yaml';
+
+import { writeGithubActionsOutputs } from '../utils/gha-output.js';
+import { parseFrontmatter, toFrontmatter, frontmatterWriteError } from '../utils/markdown.js';
+import * as styles from '../utils/styles.js';
 
 export const command = 'oas:sync';
 export const order = 2;
@@ -15,6 +14,9 @@ export const description = 'Sync reference pages with OpenAPI specs';
 
 const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
 
+// js-yaml 5's CORE_SCHEMA omits YAML merge keys (`<<: *anchor`). OpenAPI specs commonly
+// reuse path items via merges — keep that working when reading YAML specs.
+const OAS_YAML_SCHEMA = CORE_SCHEMA.withTags(mergeTag);
 
 /**
  * Find OAS files at the root of reference/ (JSON or YAML).
@@ -30,7 +32,7 @@ export function findOasFiles(refDir) {
 
     try {
       const raw = fs.readFileSync(filePath, 'utf-8');
-      const parsed = entry.endsWith('.json') ? JSON.parse(raw) : yaml.load(raw);
+      const parsed = entry.endsWith('.json') ? JSON.parse(raw) : loadYAML(raw, { schema: OAS_YAML_SCHEMA });
 
       if (parsed && (parsed.openapi || parsed.swagger)) {
         oasFiles.push({ filename: entry, spec: parsed });
@@ -139,7 +141,7 @@ function resolveXInternal(operation, spec) {
  * `webhook POST newPet`) for lint to warn about.
  */
 export function findIgnoredInternalExtensions(spec) {
-  const hasInternal = (obj) => {
+  const hasInternal = obj => {
     const xReadme = obj?.['x-readme'];
     return !!xReadme && typeof xReadme === 'object' && 'internal' in xReadme;
   };
@@ -147,7 +149,10 @@ export function findIgnoredInternalExtensions(spec) {
   const locations = [];
   if (hasInternal(spec)) locations.push('root');
 
-  for (const [entries, isWebhook] of [[spec?.paths, false], [spec?.webhooks, true]]) {
+  for (const [entries, isWebhook] of [
+    [spec?.paths, false],
+    [spec?.webhooks, true],
+  ]) {
     for (const [name, rawItem] of Object.entries(entries || {})) {
       for (const [method, operation] of Object.entries(resolveLocalPathItemRef(rawItem, spec) || {})) {
         if (!HTTP_METHODS.has(method) || !hasInternal(operation)) continue;
@@ -199,7 +204,7 @@ export function extractOperations(spec) {
           summary: operation.summary || null,
           description: operation.description || null,
           // The platform groups by the first *non-empty* tag.
-          tag: (Array.isArray(operation.tags) && operation.tags.find((t) => t)) || null,
+          tag: (Array.isArray(operation.tags) && operation.tags.find(t => t)) || null,
           path: pathStr,
           isWebhook,
           xInternal: resolveXInternal(operation, spec),
@@ -228,19 +233,15 @@ export function collectExistingPages(refDir) {
       if (stat.isDirectory()) {
         walk(full);
       } else if (entry.endsWith('.md')) {
-        try {
-          const content = fs.readFileSync(full, 'utf-8');
-          const { data } = matter(content);
-          if (data.api && data.api.file && data.api.operationId) {
-            pages.push({
-              filePath: full,
-              relativePath: path.relative(refDir, full),
-              data,
-              content,
-            });
-          }
-        } catch {
-          // Skip unparseable files.
+        const content = fs.readFileSync(full, 'utf-8');
+        const { data } = parseFrontmatter(content);
+        if (data.api && data.api.file && data.api.operationId) {
+          pages.push({
+            filePath: full,
+            relativePath: path.relative(refDir, full),
+            data,
+            content,
+          });
         }
       }
     }
@@ -259,13 +260,18 @@ function yamlSafeSlug(slug) {
 function parseOrderYaml(content) {
   return content
     .split('\n')
-    .map((line) => line.trim())
-    .filter((line) => line.startsWith('- '))
-    .map((line) => line.slice(2).trim().replace(/^["'](.+)["']$/, '$1'));
+    .map(line => line.trim())
+    .filter(line => line.startsWith('- '))
+    .map(line =>
+      line
+        .slice(2)
+        .trim()
+        .replace(/^["'](.+)["']$/, '$1'),
+    );
 }
 
 function writeOrderYaml(filePath, slugs) {
-  const content = slugs.map((s) => `- ${yamlSafeSlug(s)}`).join('\n') + '\n';
+  const content = `${slugs.map(s => `- ${yamlSafeSlug(s)}`).join('\n')}\n`;
   fs.mkdirSync(path.dirname(filePath), { recursive: true });
   fs.writeFileSync(filePath, content);
 }
@@ -286,7 +292,7 @@ function addToOrder(orderPath, slug) {
 function removeFromOrder(orderPath, slug) {
   if (!fs.existsSync(orderPath)) return;
   const content = fs.readFileSync(orderPath, 'utf-8');
-  const slugs = parseOrderYaml(content).filter((s) => s !== slug);
+  const slugs = parseOrderYaml(content).filter(s => s !== slug);
   if (slugs.length > 0) {
     writeOrderYaml(orderPath, slugs);
   } else {
@@ -306,19 +312,7 @@ function safeSegment(value, fallback) {
 
 function isWithin(baseDir, target) {
   const rel = path.relative(baseDir, target);
-  return (
-    rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel)
-  );
-}
-
-/**
- * Render a frontmatter-only page. `matter.stringify` always appends a blank
- * body after the closing fence (even for an empty body); the platform's own
- * generated pages end immediately after the fence with no trailing newline,
- * so trim it to match.
- */
-function stringifyFrontmatter(frontmatter) {
-  return matter.stringify('', frontmatter).replace(/\n+$/, '');
+  return rel !== '' && rel !== '..' && !rel.startsWith(`..${path.sep}`) && !path.isAbsolute(rel);
 }
 
 function buildPageContent({ oasFilename, operationId, isWebhook, hidden = false }) {
@@ -339,7 +333,7 @@ function buildPageContent({ oasFilename, operationId, isWebhook, hidden = false
     hidden,
   };
 
-  return stringifyFrontmatter(frontmatter);
+  return toFrontmatter(frontmatter);
 }
 
 /**
@@ -354,7 +348,7 @@ function buildTagIndexContent(title, description) {
   // As with operation pages, upload always stamps hidden: false on new pages.
   frontmatter.hidden = false;
 
-  return stringifyFrontmatter(frontmatter);
+  return toFrontmatter(frontmatter);
 }
 
 /**
@@ -493,17 +487,16 @@ function reserveSlug(takenSlugs, base) {
 /**
  * Rewrite a page's frontmatter in place, keeping its body. `mutate` receives
  * a copy of the parsed frontmatter and edits it. Returns true if the file
- * changed. A copy matters: gray-matter caches parse results by input string,
- * so mutating the returned `data` would poison later parses of that content.
+ * changed.
  */
 function updateFrontmatter(filePath, mutate) {
   const content = fs.readFileSync(filePath, 'utf-8');
-  const parsed = matter(content);
+  const parsed = parseFrontmatter(content);
+  // Refuse to rewrite from empty `data` when YAML failed to parse.
+  if (frontmatterWriteError(parsed)) return false;
   const data = structuredClone(parsed.data);
   mutate(data);
-  const next = parsed.content.trim()
-    ? matter.stringify(parsed.content, data)
-    : stringifyFrontmatter(data);
+  const next = parsed.content.trim() ? toFrontmatter(data, parsed.content) : toFrontmatter(data);
   if (next === content || JSON.stringify(data) === JSON.stringify(parsed.data)) return false;
   fs.writeFileSync(filePath, next);
   return true;
@@ -527,7 +520,7 @@ export function applyOASOrder(currentOrder, orderedSlugs) {
   const order = [...new Set(currentOrder)];
   if (!order.length) return desired;
 
-  const slots = order.map((s, i) => (desiredSet.has(s) ? i : -1)).filter((i) => i > -1);
+  const slots = order.map((s, i) => (desiredSet.has(s) ? i : -1)).filter(i => i > -1);
   if (!slots.length) return [...order, ...desired];
 
   const remaining = [...desired];
@@ -561,21 +554,17 @@ const INDEX_FILES = ['index.md', 'index.mdx', 'index.html'];
  * deleting it. A stale page can be removed by hand; a deleted edit is gone.
  */
 function isGeneratedTagIndex(indexPath, specDescriptions) {
-  let parsed;
-  try {
-    parsed = matter(fs.readFileSync(indexPath, 'utf-8'));
-  } catch {
-    return false;
-  }
-  const { data, content } = parsed;
-  if (content.trim()) return false;
+  const { data, content, error } = parseFrontmatter(fs.readFileSync(indexPath, 'utf-8'));
+  if (error || content.trim()) return false;
   if (typeof data.title !== 'string' || !('hidden' in data)) return false;
-  if (Object.keys(data).some((k) => !['title', 'hidden', 'excerpt'].includes(k))) return false;
+  if (Object.keys(data).some(k => !['title', 'hidden', 'excerpt'].includes(k))) return false;
   if ('excerpt' in data && !specDescriptions.has(data.excerpt)) return false;
 
   const dirSlug = slugifyFolder(path.basename(path.dirname(indexPath)));
   const titleSlug = slugifyFolder(data.title);
-  return dirSlug === titleSlug || new RegExp(`^${titleSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+$`).test(dirSlug);
+  return (
+    dirSlug === titleSlug || new RegExp(`^${titleSlug.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}-\\d+$`).test(dirSlug)
+  );
 }
 
 /**
@@ -592,12 +581,12 @@ function cleanupTagFolder(dir, { refDir, specDescriptions, takenSlugs, changes }
   } catch {
     return;
   }
-  const others = entries.filter((e) => !INDEX_FILES.includes(e) && e !== '_order.yaml');
+  const others = entries.filter(e => !INDEX_FILES.includes(e) && e !== '_order.yaml');
   if (others.length) return;
 
   const parentDir = path.dirname(dir);
   const slug = path.basename(dir);
-  const indexFile = entries.find((e) => INDEX_FILES.includes(e));
+  const indexFile = entries.find(e => INDEX_FILES.includes(e));
 
   if (!indexFile || isGeneratedTagIndex(path.join(dir, indexFile), specDescriptions)) {
     fs.rmSync(dir, { recursive: true, force: true });
@@ -625,10 +614,7 @@ function cleanupTagFolder(dir, { refDir, specDescriptions, takenSlugs, changes }
  */
 function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   const specOps = extractOperations(spec);
-  const infoTitle = safeSegment(
-    spec.info?.title || path.basename(oasFilename, path.extname(oasFilename)),
-    'api',
-  );
+  const infoTitle = safeSegment(spec.info?.title || path.basename(oasFilename, path.extname(oasFilename)), 'api');
 
   // Hyphen vs. space in a group's folder name is not a meaningful difference
   // — "shipping-labels" and "shipping labels" are the same folder to a
@@ -639,16 +625,11 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   const apiDir = path.join(refDir, infoTitle);
   const foldersBySlug = existingFoldersBySlug(apiDir);
 
-  const existingPages = collectExistingPages(refDir).filter(
-    (p) => p.data.api.file === oasFilename,
-  );
+  const existingPages = collectExistingPages(refDir).filter(p => p.data.api.file === oasFilename);
 
   const pagesByOpId = new Map();
   for (const page of existingPages) {
-    pagesByOpId.set(
-      operationKey({ operationId: page.data.api.operationId, isWebhook: !!page.data.api.webhook }),
-      page,
-    );
+    pagesByOpId.set(operationKey({ operationId: page.data.api.operationId, isWebhook: !!page.data.api.webhook }), page);
   }
 
   const changes = { added: [], deleted: [], moved: [], updated: [], skipped: [] };
@@ -661,9 +642,7 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   // Tag descriptions from the spec's top-level `tags` array, used for the
   // per-tag category landing page (index.md).
   const tagDescriptions = new Map(
-    (Array.isArray(spec.tags) ? spec.tags : [])
-      .filter((t) => t && t.name)
-      .map((t) => [t.name, t.description || null]),
+    (Array.isArray(spec.tags) ? spec.tags : []).filter(t => t && t.name).map(t => [t.name, t.description || null]),
   );
   // Every description the spec supplies, regardless of which tag: what an
   // emptied tag folder's excerpt is checked against (see `isGeneratedTagIndex`).
@@ -714,13 +693,34 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
   // listed in `tags`) keeps its natural encounter order, appended after every
   // declared tag.
   const declaredOrder = (Array.isArray(spec.tags) ? spec.tags : [])
-    .filter((t) => t && t.name)
-    .map((t) => slugifyFolder(safeSegment(t.name, 'Other')) || 'other');
+    .filter(t => t && t.name)
+    .map(t => slugifyFolder(safeSegment(t.name, 'Other')) || 'other');
   const orderedFolders = [
-    ...declaredOrder.filter((folder) => groupsByFolder.has(folder)),
-    ...[...groupsByFolder.keys()].filter((folder) => !declaredOrder.includes(folder)),
+    ...declaredOrder.filter(folder => groupsByFolder.has(folder)),
+    ...[...groupsByFolder.keys()].filter(folder => !declaredOrder.includes(folder)),
   ];
 
+  // Groups that will hold at least one of this spec's pages after this run:
+  // a new page is created in its folder, an existing page already lives
+  // anywhere under it (a direct child, or nested in a hand-made subfolder),
+  // or `apply-tag-changes` will move one in (see the move pass below). A group
+  // whose pages were all moved somewhere else (another category, or a folder
+  // spelled differently) gets no category page — creating one would leave an
+  // empty index.md with no children.
+  const populatedFolders = new Set();
+  for (const [key, op] of specOps) {
+    const { folder } = operationGroup(op);
+    const page = pagesByOpId.get(key);
+    const tagDir = path.join(apiDir, foldersBySlug.get(folder) || folder);
+    if (
+      !page ||
+      isWithin(tagDir, page.filePath) ||
+      (applyTagChanges && isWithin(apiDir, page.filePath) && path.basename(page.filePath) !== 'index.md')
+    ) {
+      populatedFolders.add(folder);
+    }
+  }
+
   const groupDirs = new Map();
   const createdIndexes = new Set();
   for (const folder of orderedFolders) {
@@ -728,9 +728,11 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     const actualFolder = foldersBySlug.get(folder) || folder;
     const pageDir = path.join(refDir, infoTitle, actualFolder);
     if (!isWithin(refDir, pageDir)) continue;
-    groupDirs.set(folder, pageDir);
 
     const indexPath = path.join(pageDir, 'index.md');
+    if (!populatedFolders.has(folder) && !fs.existsSync(indexPath)) continue;
+    groupDirs.set(folder, pageDir);
+
     if (!fs.existsSync(indexPath)) {
       // Never overwrite an existing index.md — it may be a hand-written category.
       fs.mkdirSync(pageDir, { recursive: true });
@@ -745,7 +747,7 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
       // With `apply-tag-changes`, the spec owns the category page's title and
       // excerpt too (a tag with no description clears the excerpt). Its body
       // and any other frontmatter are the user's and are kept.
-      const updated = updateFrontmatter(indexPath, (data) => {
+      const updated = updateFrontmatter(indexPath, data => {
         data.title = title;
         if (description) data.excerpt = description;
         else delete data.excerpt;
@@ -801,7 +803,7 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     // its own `hidden` — removing the extension never unhides a page.
     if (op.xInternal.present) {
       const hidden = Boolean(op.xInternal.value);
-      const updated = updateFrontmatter(filePath, (data) => {
+      const updated = updateFrontmatter(filePath, data => {
         data.hidden = hidden;
       });
       if (updated) changes.updated.push(path.relative(refDir, filePath));
@@ -861,9 +863,9 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
     const indexPath = path.join(dir, 'index.md');
     if (!fs.existsSync(indexPath)) continue;
     const isNew = createdIndexes.has(indexPath);
-    const allHidden = children.every((x) => x.present && (isNew ? Boolean(x.value) : x.value === true));
+    const allHidden = children.every(x => x.present && (isNew ? Boolean(x.value) : x.value === true));
     if (!allHidden) continue;
-    const updated = updateFrontmatter(indexPath, (data) => {
+    const updated = updateFrontmatter(indexPath, data => {
       data.hidden = true;
     });
     if (updated && !isNew) changes.updated.push(path.relative(refDir, indexPath));
@@ -925,7 +927,7 @@ function syncOneOas(refDir, oasFilename, spec, takenSlugs) {
  *   Returns null if there's no reference/ dir or no specs.
  */
 export function syncOas(input) {
-  const gitRoot = typeof input === 'string' ? input : (input?.cwd || process.cwd());
+  const gitRoot = typeof input === 'string' ? input : input?.cwd || process.cwd();
   const refDir = path.join(gitRoot, 'reference');
   if (!fs.existsSync(refDir)) return null;
 
@@ -977,7 +979,9 @@ export function printSyncResults(results) {
 
     const dot = hasChanges ? styles.warn('●') : styles.success('●');
     console.log();
-    console.log(`  ${dot} ${styles.bold(title)} ${styles.dim(`(${filename} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`);
+    console.log(
+      `  ${dot} ${styles.bold(title)} ${styles.dim(`(${filename} · ${opCount} ${opCount === 1 ? 'endpoint' : 'endpoints'})`)}`,
+    );
 
     if (!hasChanges) {
       continue;
@@ -996,9 +1000,7 @@ export function printSyncResults(results) {
       console.log(`    ${styles.warn('~')} Updated ${file}`);
     }
     for (const { path: file, operationId } of changes.skipped) {
-      console.log(
-        `    ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`,
-      );
+      console.log(`    ${styles.warn('!')} Skipped ${file} for "${operationId}" (destination already exists)`);
       skipped.push({ filename, path: file, operationId });
     }
 
@@ -1046,8 +1048,7 @@ export async function run(_options, _cmd, ctx) {
     return;
   }
 
-  const { totalAdded, totalDeleted, totalMoved, totalUpdated, totalSkipped, skipped } =
-    printSyncResults(results);
+  const { totalAdded, totalDeleted, totalMoved, totalUpdated, totalSkipped, skipped } = printSyncResults(results);
 
   console.log();
   const total = totalAdded + totalDeleted + totalMoved + totalUpdated;
@@ -1064,7 +1065,9 @@ export async function run(_options, _cmd, ctx) {
   // to whoever wraps this command in CI to notice and fail on it themselves.
   if (totalSkipped > 0) {
     const syncedNote = total > 0 ? ` (${totalAdded} added, ${totalDeleted} deleted${extraNote})` : '';
-    styles.error(`${totalSkipped} ${totalSkipped === 1 ? 'page' : 'pages'} skipped${syncedNote} — see above for which, and why.`);
+    styles.error(
+      `${totalSkipped} ${totalSkipped === 1 ? 'page' : 'pages'} skipped${syncedNote} — see above for which, and why.`,
+    );
   } else if (total === 0) {
     styles.ok('Reference pages are already in sync.');
   } else {

package/src/commands/oas-validate.js

@@ -1,9 +1,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
+
 import OASNormalize from 'oas-normalize';
-import { findOasFiles, extractOperations } from './oas-sync.js';
-import * as styles from '../utils/styles.js';
+
 import { writeGithubActionsOutputs } from '../utils/gha-output.js';
+import * as styles from '../utils/styles.js';
+
+import { findOasFiles, extractOperations } from './oas-sync.js';
 
 export const command = 'oas:validate';
 export const order = 3;
@@ -114,7 +117,7 @@ export async function validateOas({ cwd, dereference = false } = {}) {
       continue;
     }
 
-    const errors = normalizerResult.valid ? [] : (normalizerResult.errors || []);
+    const errors = normalizerResult.valid ? [] : normalizerResult.errors || [];
     const warnings = normalizerResult.warnings || [];
 
     if (dereference) {
@@ -158,9 +161,7 @@ export async function validateOasFiles(gitRoot, { dereference = false } = {}) {
 
   for (const r of summary.results) {
     const meta = `${r.filename} · ${r.version} · ${r.opCount} ${r.opCount === 1 ? 'endpoint' : 'endpoints'}`;
-    const dot = r.errors.length > 0
-      ? styles.err('●')
-      : r.warnings.length > 0 ? styles.warn('●') : styles.success('●');
+    const dot = r.errors.length > 0 ? styles.err('●') : r.warnings.length > 0 ? styles.warn('●') : styles.success('●');
 
     console.log();
     console.log(`  ${dot} ${styles.bold(r.title)} ${styles.dim(`(${meta})`)}`);
@@ -224,7 +225,9 @@ export async function run(options, _cmd, ctx) {
     styles.error(`${parts.join(' and ')} across ${fileCount} ${fileCount === 1 ? 'spec' : 'specs'}.`);
     process.exit(1);
   } else if (totalWarnings > 0) {
-    styles.warning(`${totalValid} of ${fileCount} specs valid with ${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}.`);
+    styles.warning(
+      `${totalValid} of ${fileCount} specs valid with ${totalWarnings} ${totalWarnings === 1 ? 'warning' : 'warnings'}.`,
+    );
   } else {
     styles.ok(`${fileCount} ${fileCount === 1 ? 'spec' : 'specs'} validated — all good!`);
   }