@writedocs/generator 0.5.0 → 0.7.0

package/src/lib/a11y-check.js

@@ -0,0 +1,291 @@
+// `writedocs a11y`: accessibility problems that can be found in the source,
+// without building - the ones an author introduces and can fix in a page or
+// in writedocs.json. Plain JavaScript, loaded by plain Node from an
+// installed package (see lib/icons.js's comment on why not TypeScript).
+//
+//   - contrast (WCAG 2 AA, 4.5:1 for text) of the colors writedocs.json sets:
+//     links (styles.colors.primary) on the light and dark backgrounds, body
+//     text (styles.colors.text) on them, white text on primary (step
+//     numbers, the info banner), and the navbar's text on its own color.
+//     Only colors the project sets are checked - writedocs' own defaults
+//     aren't something the author wrote.
+//   - images without alt text: a Markdown image with empty alt, an
+//     <img>/<Image> with no `alt` at all (alt="" is how an image is marked
+//     decorative, so it's accepted)
+//   - an <iframe> without a `title`
+//   - a link with no text
+//   - headings: a skipped level (the page title is the h1, so the first
+//     section heading is ##), and a # heading in the page body - a second h1.
+//     A custom or blank page has no title h1 (it builds its own layout), so
+//     its own h1 is expected there.
+//
+// Issues are shaped like lib/content-check.js's: { file, line?, message,
+// suggestion? }.
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { visit } from 'unist-util-visit';
+import { findAllPages } from './pages.js';
+import { createJsonLocator } from './config-schema.js';
+
+const processors = {};
+async function parse(text, format) {
+  if (!processors[format]) {
+    const { createProcessor } = await import('@mdx-js/mdx');
+    processors[format] = createProcessor({ format });
+  }
+  return processors[format].parse(text);
+}
+
+// --- Contrast -------------------------------------------------------------
+
+// The theme's own fallbacks (src/layout/BaseLayout.astro).
+const DEFAULT_BACKGROUND = { light: '#ffffff', dark: '#0b1120' };
+const DEFAULT_TEXT = { light: '#0f172a', dark: '#e2e8f0' };
+const MIN_TEXT_CONTRAST = 4.5;
+
+function parseHex(value) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(value ?? '').trim());
+  if (!m) return null;
+  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
+}
+
+function luminance(rgb) {
+  const [r, g, b] = rgb.map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio of two hex colors, or null when either isn't hex. */
+export function contrastRatio(a, b) {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  if (!x || !y) return null;
+  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Black or white - the same rule BaseLayout.astro uses for text on a
+ *  configured navbar color (contrastTextColor() in lib/config.ts). */
+function navbarTextFor(hex) {
+  const rgb = parseHex(hex);
+  if (!rgb) return '#ffffff';
+  const [r, g, b] = rgb;
+  return (299 * r + 587 * g + 114 * b) / 1000 > 150 ? '#000000' : '#ffffff';
+}
+
+function checkColors(config, locate) {
+  const issues = [];
+  const styles = config?.styles ?? {};
+  const colors = styles.colors ?? {};
+  const background = {
+    light: styles.background?.colors?.light ?? DEFAULT_BACKGROUND.light,
+    dark: styles.background?.colors?.dark ?? DEFAULT_BACKGROUND.dark,
+  };
+  const at = (...trail) => locate(['styles', ...trail])?.line;
+  const ratioText = (r) => `${r.toFixed(2)}:1`;
+  const low = (fg, bg) => {
+    const r = contrastRatio(fg, bg);
+    return r !== null && r < MIN_TEXT_CONTRAST ? r : null;
+  };
+  const push = (line, message, suggestion) => issues.push({ file: 'writedocs.json', line, message, suggestion });
+
+  const primary = { light: colors.primary, dark: colors.dark?.primary ?? colors.primary };
+  const text = { light: colors.text, dark: colors.dark?.text };
+  const setBackground = { light: styles.background?.colors?.light, dark: styles.background?.colors?.dark };
+
+  for (const mode of ['light', 'dark']) {
+    // Links: primary on the page background. Checked when either one is
+    // the project's own choice.
+    const primaryIsSet = mode === 'light' ? colors.primary !== undefined : colors.dark?.primary !== undefined || colors.primary !== undefined;
+    if (primary[mode] && (primaryIsSet || setBackground[mode])) {
+      const r = low(primary[mode], background[mode]);
+      if (r) {
+        const line = mode === 'dark' && colors.dark?.primary ? at('colors', 'dark', 'primary') : colors.primary ? at('colors', 'primary') : at('background', 'colors', mode);
+        push(
+          line,
+          `Links are hard to read in ${mode} mode: the primary color ${primary[mode]} on the ${mode} background ${background[mode]} has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
+          mode === 'dark' && !colors.dark?.primary
+            ? 'Set a lighter styles.colors.dark.primary for dark mode.'
+            : `Use a ${mode === 'light' ? 'darker' : 'lighter'} primary color, or change the background.`
+        );
+      }
+    }
+    // Body text.
+    if (text[mode] || setBackground[mode]) {
+      const fg = text[mode] ?? DEFAULT_TEXT[mode];
+      const r = low(fg, background[mode]);
+      if (r) {
+        push(
+          text[mode] ? at('colors', ...(mode === 'dark' ? ['dark', 'text'] : ['text'])) : at('background', 'colors', mode),
+          `Body text is hard to read in ${mode} mode: ${fg} on ${background[mode]} has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`
+        );
+      }
+    }
+  }
+
+  // White text on the primary color (step numbers, the info banner).
+  const primaries = [...new Set([colors.primary, colors.dark?.primary].filter(Boolean))];
+  for (const color of primaries) {
+    const r = low('#ffffff', color);
+    if (r) {
+      push(
+        color === colors.primary ? at('colors', 'primary') : at('colors', 'dark', 'primary'),
+        `White text on the primary color ${color} (step numbers, the info banner) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
+        'Use a darker primary color.'
+      );
+    }
+  }
+
+  // The navbar's text on its own color - black or white, picked by a rough
+  // brightness rule that can land on the weaker of the two.
+  for (const mode of ['light', 'dark']) {
+    const side = styles.navbar?.[mode];
+    const bg = typeof side === 'string' ? side : side?.background;
+    if (!bg) continue;
+    const fg = navbarTextFor(bg);
+    const r = low(fg, bg);
+    if (r) {
+      push(
+        at('navbar', mode, ...(typeof side === 'string' ? [] : ['background'])),
+        `The navbar's ${fg === '#ffffff' ? 'white' : 'black'} text on ${bg} (${mode} mode) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
+        'Use a darker or a lighter navbar color - mid-tones can\'t reach 4.5:1 with either black or white text.'
+      );
+    }
+  }
+  return issues;
+}
+
+// --- Pages ----------------------------------------------------------------
+
+function attribute(node, name) {
+  const attr = node.attributes?.find((a) => a.type === 'mdxJsxAttribute' && a.name === name);
+  if (!attr) return undefined;
+  return typeof attr.value === 'string' ? attr.value : null; // null: an expression - can't tell, so not reported
+}
+
+function textOf(node) {
+  if (typeof node.value === 'string' && (node.type === 'text' || node.type === 'inlineCode')) return node.value;
+  if (node.type === 'image') return node.alt ?? '';
+  return (node.children ?? []).map(textOf).join('');
+}
+
+/** Issues in one page (`headings`: true) or snippet (false). */
+async function checkFile(contentDir, abs, { headings }) {
+  let raw;
+  try {
+    raw = fs.readFileSync(abs, 'utf-8').replace(/\r\n/g, '\n');
+  } catch {
+    return { issues: [], imports: [] };
+  }
+  let parsed;
+  try {
+    parsed = matter(raw, {});
+  } catch {
+    return { issues: [], imports: [] }; // `writedocs validate` reports it
+  }
+  const bodyStart = raw.lastIndexOf(parsed.content);
+  const lineOffset = bodyStart > 0 ? raw.slice(0, bodyStart).split('\n').length - 1 : 0;
+  let tree;
+  try {
+    tree = await parse(parsed.content, /\.mdx$/i.test(abs) ? 'mdx' : 'md');
+  } catch {
+    return { issues: [], imports: [] }; // `writedocs validate` reports it
+  }
+  const file = path.relative(contentDir, abs).split(path.sep).join('/');
+  const issues = [];
+  const imports = [];
+  const lineOf = (node) => (node.position?.start?.line ? node.position.start.line + lineOffset : undefined);
+  const push = (node, message, suggestion) => issues.push({ file, line: lineOf(node), message, suggestion });
+  // The layout renders the page title as the h1 - except in the canvas
+  // modes (custom, blank: see [...slug].astro), where the page builds its
+  // own layout and its own h1.
+  const ownsH1 = ['custom', 'blank'].includes(parsed.data?.mode);
+  let previousLevel = ownsH1 ? 0 : 1;
+
+  visit(tree, (node) => {
+    switch (node.type) {
+      case 'image':
+        if (!String(node.alt ?? '').trim()) {
+          push(node, `Image ${node.url} has no alt text.`, 'Describe the image in the brackets: ![What it shows](...).');
+        }
+        break;
+      case 'link':
+        if (!textOf(node).trim()) push(node, `Link to ${node.url} has no text - a screen reader reads out the address instead.`);
+        break;
+      case 'heading':
+        if (!headings) break;
+        if (node.depth === 1 && !ownsH1) {
+          push(node, 'A # heading in the page is a second h1 - the page title is already the h1.', 'Use ## for the page\'s sections.');
+        } else if (node.depth > previousLevel + 1) {
+          push(
+            node,
+            `Heading level skips from h${previousLevel} to h${node.depth} ("${textOf(node).trim()}").`,
+            `Use ${'#'.repeat(previousLevel + 1)} here, or add the missing level above it.`
+          );
+        }
+        previousLevel = node.depth;
+        break;
+      case 'html':
+        // Raw HTML in a .md page.
+        for (const m of node.value.matchAll(/<img\b[^>]*>/gi)) {
+          if (!/\balt\s*=/i.test(m[0])) push(node, 'An <img> has no alt attribute.', 'Add alt="what it shows", or alt="" if it\'s decorative.');
+        }
+        for (const m of node.value.matchAll(/<iframe\b[^>]*>/gi)) {
+          if (!/\btitle\s*=/i.test(m[0])) push(node, 'An <iframe> has no title.', 'Add title="what it shows" - screen readers announce it.');
+        }
+        break;
+      case 'mdxjsEsm':
+        for (const m of node.value.matchAll(/\bfrom\s*['"]([^'"]+\.mdx?)['"]/g)) imports.push(m[1]);
+        break;
+      case 'mdxJsxFlowElement':
+      case 'mdxJsxTextElement': {
+        const name = node.name ?? '';
+        if (/^(img|Image)$/.test(name) && attribute(node, 'alt') === undefined) {
+          push(node, `<${name}${attribute(node, 'src') ? ` src="${attribute(node, 'src')}"` : ''}> has no alt attribute.`, 'Add alt="what it shows", or alt="" if it\'s decorative.');
+        }
+        if (/^iframe$/i.test(name) && attribute(node, 'title') === undefined) {
+          push(node, 'An <iframe> has no title.', 'Add title="what it shows" - screen readers announce it.');
+        }
+        const level = /^h([1-6])$/.exec(name);
+        if (headings && level) {
+          const depth = Number(level[1]);
+          if (depth === 1 && !ownsH1) push(node, 'An <h1> in the page is a second h1 - the page title is already the h1.', 'Use <h2> for the page\'s sections.');
+          else if (depth > previousLevel + 1) push(node, `Heading level skips from h${previousLevel} to h${depth}.`, `Use <h${previousLevel + 1}> here, or add the missing level above it.`);
+          previousLevel = depth;
+        }
+        break;
+      }
+    }
+  });
+  return { issues, imports };
+}
+
+/**
+ * Checks `contentDir`. `configText`: writedocs.json's raw text (valid JSON -
+ * the CLI checks that first). Returns { pages, issues }.
+ */
+export async function checkAccessibility(contentDir, configText) {
+  const config = JSON.parse(configText);
+  const issues = checkColors(config, createJsonLocator(configText));
+  const pages = findAllPages(contentDir);
+  const snippetsDone = new Set();
+  async function withSnippets(abs, options) {
+    const result = await checkFile(contentDir, abs, options);
+    issues.push(...result.issues);
+    for (const spec of result.imports) {
+      const snippet = spec.startsWith('/') ? path.join(contentDir, spec) : path.resolve(path.dirname(abs), spec);
+      if (snippetsDone.has(snippet)) continue;
+      snippetsDone.add(snippet);
+      // A snippet's headings sit wherever the page puts it, so only its
+      // images, iframes and links are checked.
+      await withSnippets(snippet, { headings: false });
+    }
+  }
+  for (const rel of pages) await withSnippets(path.join(contentDir, rel), { headings: true });
+  issues.sort((a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0));
+  return { pages: pages.length, issues };
+}

package/src/lib/content-check.js

@@ -10,6 +10,10 @@
 //   - writedocs.json's navigation lists a page that doesn't exist
 //   - a redirect is a pattern (`/old/:slug`) rather than one exact path
 //   - a Markdown image with a relative path names a file that doesn't exist
+//   - an import the build can't resolve: a Docusaurus path (@site/...), or a
+//     relative or /snippets/ import of a file that isn't there
+//   - an OpenAPI group's spec is missing or doesn't parse, or two groups
+//     share one `openapi.path`
 // Warnings - the build succeeds, but not as written:
 //   - an unknown component (the build shows only its content - see
 //     lib/mdx-unknown-components.js)
@@ -18,6 +22,10 @@
 //     writedocs.json
 //   - a built-in component inside a page component that runs as React,
 //     where it renders simplified (lib/mdx-inline-react.js)
+//   - a page's `openapi:` names an operation no spec has, or a spec that's
+//     missing or doesn't parse (the page shows a notice instead of the API
+//     playground)
+//   - a spec that parses but isn't valid OpenAPI
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
@@ -27,6 +35,8 @@ import { iconExists } from './icons.js';
 import { findUnknownComponents } from './mdx-unknown-components.js';
 import { findInteractiveComponents, simplifiedBuiltinMessage } from './mdx-inline-react.js';
 import { pageFrontmatterSchema, createJsonLocator } from './config-schema.js';
+import { parseOpenApiRef } from './openapi-ref.js';
+import { collectOpenApiGroups, operationKeys } from './openapi-spec.js';
 
 /** An issue: { file, line?, message, suggestion? } - `file` relative to the
  *  content directory, POSIX slashes. */
@@ -59,7 +69,7 @@ async function parseMdx(text) {
   return mdxProcessor.parse(text);
 }
 
-async function checkPage(contentDir, rel, errors, warnings) {
+async function checkPage(contentDir, rel, errors, warnings, openapiRefs) {
   const raw = fs.readFileSync(path.join(contentDir, rel), 'utf-8').replace(/\r\n/g, '\n');
   let parsed;
   try {
@@ -91,6 +101,8 @@ async function checkPage(contentDir, rel, errors, warnings) {
       errors.push(issue(rel, key ? lineOfFrontmatterKey(frontmatterText, key) : 2, `Frontmatter ${where}${i.message}`));
     }
   }
+  const ref = parseOpenApiRef(parsed.data.openapi);
+  if (ref) openapiRefs.push({ rel, line: lineOfFrontmatterKey(frontmatterText, 'openapi'), ref, value: parsed.data.openapi });
   if (typeof parsed.data.icon === 'string' && !iconExists(parsed.data.icon)) {
     const { message, suggestion } = unknownIconMessage(parsed.data.icon);
     warnings.push(issue(rel, lineOfFrontmatterKey(frontmatterText, 'icon'), message, suggestion));
@@ -119,6 +131,45 @@ async function checkPage(contentDir, rel, errors, warnings) {
     );
     return;
   }
+  // Imports the build can't resolve fail it: Docusaurus' path aliases
+  // (common in pages from the previous writedocs), and a relative or
+  // /snippets/ import of a file that isn't there. Package imports aren't
+  // checked - whether they resolve depends on what's installed.
+  visit(tree, 'mdxjsEsm', (node) => {
+    const code = String(node.value ?? '');
+    for (const m of code.matchAll(/\b(?:import|export)\b[^'";]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]/g)) {
+      const spec = m[1] ?? m[2];
+      const at = node.position?.start?.line ? node.position.start.line + lineOffset + code.slice(0, m.index).split('\n').length - 1 : undefined;
+      if (/^@(site|theme|docusaurus|generated)(\/|$)/.test(spec)) {
+        errors.push(
+          issue(
+            rel,
+            at,
+            `Imports "${spec}", a Docusaurus path - the build fails on it.`,
+            /^@site\/src\/components\/?$/.test(spec)
+              ? "writedocs' components (Card, Callout, Tabs, Accordion, ...) need no import - remove this line."
+              : spec.startsWith('@site/src/components/')
+                ? 'A custom component of the old site - move it into a snippet (snippets/), or remove it and what uses it.'
+                : 'Remove the import, and what uses it.'
+          )
+        );
+        continue;
+      }
+      let target = null;
+      if (spec.startsWith('./') || spec.startsWith('../')) target = path.resolve(path.dirname(path.join(contentDir, rel)), spec);
+      else if (spec.startsWith('/snippets/')) target = path.join(contentDir, spec);
+      if (!target) continue;
+      const exists = ['', '.mdx', '.md', '.js', '.jsx', '.ts', '.tsx', '.json'].some((ext) => {
+        try {
+          return fs.statSync(target + ext).isFile();
+        } catch {
+          return false;
+        }
+      });
+      if (!exists) errors.push(issue(rel, at, `Imports ${spec}, which doesn't exist - the build fails on it.`));
+    }
+  });
+
   // A Markdown image with a relative path is imported by the build (Astro's
   // image pipeline), so a missing file fails the whole build.
   visit(tree, 'image', (node) => {
@@ -208,6 +259,123 @@ function configIcons(config) {
   return found;
 }
 
+/** The JSON path of `target` (an object inside `root`), for line lookup. */
+function jsonPathOf(root, target, trail = []) {
+  if (root === target) return trail;
+  if (!root || typeof root !== 'object') return null;
+  for (const [key, value] of Object.entries(root)) {
+    const found = jsonPathOf(value, target, [...trail, Array.isArray(root) ? Number(key) : key]);
+    if (found) return found;
+  }
+  return null;
+}
+
+const posix = (p) => p.split(path.sep).join('/');
+
+/** OpenAPI: the specs writedocs.json's groups point at (the build fails
+ *  without them - src/cli/generate-api-pages.js), the specs pages name, and
+ *  every page's `openapi:` operation. `config` is null when writedocs.json
+ *  isn't valid JSON - then only the pages' own specs are checked. */
+async function checkOpenApi(contentDir, config, locate, openapiRefs, errors, warnings) {
+  const groups = config ? collectOpenApiGroups(config.navigation) : [];
+  if (groups.length === 0 && openapiRefs.length === 0) return;
+  const { default: SwaggerParser } = await import('@apidevtools/swagger-parser');
+
+  // Each spec loaded once: { keys } or { missing } or { error }.
+  const specs = new Map();
+  async function load(abs) {
+    if (specs.has(abs)) return specs.get(abs);
+    let result;
+    if (!fs.existsSync(abs)) result = { missing: true };
+    else {
+      try {
+        const spec = await SwaggerParser.dereference(abs);
+        result = { keys: operationKeys(spec) };
+        // Parses, but may still not be valid OpenAPI - the build takes it
+        // as it is, so that's only worth a warning.
+        try {
+          await SwaggerParser.validate(abs);
+        } catch (err) {
+          result.invalid = String(err.message).split('\n')[0];
+        }
+      } catch (err) {
+        result = { error: String(err.message).split('\n')[0] };
+      }
+    }
+    specs.set(abs, result);
+    return result;
+  }
+  const reported = new Set();
+  const once = (list, key, value) => {
+    if (reported.has(key)) return;
+    reported.add(key);
+    list.push(value);
+  };
+
+  const seenPaths = new Map();
+  for (const group of groups) {
+    const trail = jsonPathOf(config.navigation, group) ?? [];
+    const line = (key) => locate?.([ 'navigation', ...trail, 'openapi', key])?.line;
+    const src = String(group.openapi?.src ?? '');
+    const mountedAt = String(group.openapi?.path ?? '').replace(/^\/+|\/+$/g, '');
+    if (seenPaths.has(mountedAt)) {
+      errors.push(
+        issue('writedocs.json', line('path'), `Two OpenAPI groups are both at openapi.path "${group.openapi.path}" ("${seenPaths.get(mountedAt)}" and "${group.group}").`, "Give each group's openapi.path a different value.")
+      );
+    } else seenPaths.set(mountedAt, group.group);
+    if (/^[a-z][a-z0-9+.-]*:\/\//i.test(src)) {
+      errors.push(issue('writedocs.json', line('src'), `The "${group.group}" group's OpenAPI spec is a URL (${src}) - it has to be a file in the project.`, 'Download the spec into the project and point openapi.src at the file.'));
+      continue;
+    }
+    const abs = path.resolve(contentDir, src);
+    const spec = await load(abs);
+    if (spec.missing) {
+      errors.push(issue('writedocs.json', line('src'), `The "${group.group}" group's OpenAPI spec "${src}" doesn't exist.`, "openapi.src is relative to the folder writedocs.json is in."));
+    } else if (spec.error) {
+      once(errors, `error ${abs}`, issue(posix(path.relative(contentDir, abs)), undefined, `This OpenAPI spec doesn't parse: ${spec.error}`));
+    } else if (spec.invalid) {
+      once(warnings, `invalid ${abs}`, issue(posix(path.relative(contentDir, abs)), undefined, `This OpenAPI spec isn't valid OpenAPI: ${spec.invalid}`, 'The build uses it as it is - the API pages may be incomplete.'));
+    }
+  }
+
+  // Every operation any loaded spec defines - where a page's short form
+  // (`openapi: "GET /pets"`) is looked up (findOperationFile() in
+  // lib/openapi-render.ts).
+  const pageSpecs = [...new Set(openapiRefs.filter((r) => r.ref.spec).map((r) => path.resolve(contentDir, r.ref.spec)))];
+  for (const abs of pageSpecs) await load(abs);
+  const allKeys = new Set();
+  for (const spec of specs.values()) for (const key of spec.keys ?? []) allKeys.add(key);
+
+  for (const { rel, line, ref, value } of openapiRefs) {
+    const key = `${ref.method} ${ref.path}`;
+    if (ref.spec) {
+      const abs = path.resolve(contentDir, ref.spec);
+      const spec = specs.get(abs);
+      if (spec.missing) {
+        warnings.push(issue(rel, line, `openapi names the spec "${ref.spec}", which doesn't exist - the page shows a notice instead of the API playground.`, 'The spec path is relative to the folder writedocs.json is in.'));
+        continue;
+      }
+      if (spec.error) {
+        warnings.push(issue(rel, line, `openapi names the spec "${ref.spec}", which doesn't parse - the page shows a notice instead of the API playground.`));
+        once(warnings, `error ${abs}`, issue(posix(path.relative(contentDir, abs)), undefined, `This OpenAPI spec doesn't parse: ${spec.error}`));
+        continue;
+      }
+      if (spec.keys.has(key) || allKeys.has(key)) continue;
+    } else if (allKeys.has(key)) continue;
+    const specsLoaded = [...specs.values()].some((s) => s.keys);
+    warnings.push(
+      issue(
+        rel,
+        line,
+        `openapi: "${value}" - ${specsLoaded ? 'no OpenAPI spec has this operation' : 'there is no OpenAPI spec to find it in'}, so the page shows a notice instead of the API playground.`,
+        specsLoaded
+          ? 'Check the method and the path - they have to match the spec exactly, like "GET /pets/{petId}".'
+          : 'Add an OpenAPI group to writedocs.json\'s navigation, or name the spec in the page: openapi: "/openapi.yaml GET /pets".'
+      )
+    );
+  }
+}
+
 /**
  * Checks a content directory. `configText` is writedocs.json's raw text, or
  * null when it isn't valid JSON (then only the pages themselves are
@@ -217,7 +385,8 @@ export async function checkContent(contentDir, configText) {
   const errors = [];
   const warnings = [];
   const pages = findAllPages(contentDir);
-  for (const rel of pages) await checkPage(contentDir, rel, errors, warnings);
+  const openapiRefs = [];
+  for (const rel of pages) await checkPage(contentDir, rel, errors, warnings, openapiRefs);
 
   let config = null;
   if (configText !== null) {
@@ -266,6 +435,7 @@ export async function checkContent(contentDir, configText) {
       warnings.push(issue('writedocs.json', locate(jsonPath)?.line, message, suggestion));
     }
   }
+  await checkOpenApi(contentDir, config, config ? createJsonLocator(configText) : null, openapiRefs, errors, warnings);
 
   const byLocation = (a, b) => a.file.localeCompare(b.file) || (a.line ?? 0) - (b.line ?? 0);
   errors.sort(byLocation);