@writedocs/generator 0.4.12 → 0.6.0

package/bin/writedocs.js

@@ -8,7 +8,7 @@ import { runDev } from '../src/cli/dev.js';
 import { runBuild } from '../src/cli/build.js';
 import { runInit } from '../src/cli/init.js';
 import { requireBuildKey } from '../src/cli/build-auth.js';
-import { log, step, plural, color, CliExit, errorText } from '../src/cli/output.js';
+import { log, step, plural, color, CliExit, errorText, stopActiveStep } from '../src/cli/output.js';
 // O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
 // que a plataforma importa por `@writedocs/generator/config-schema` - e o que
 // faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
@@ -170,6 +170,71 @@ program
     }
   });
 
+program
+  // Like `validate`: no key, no build, no network - reads the project and
+  // exits 0 (no broken links) or 1, so it works as a CI step.
+  .command('broken-links')
+  .description('Check every internal link - pages, anchors and files - in the pages and writedocs.json')
+  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
+  .action(async (dir) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    const { preflightCheck } = await import('../src/cli/preflight.js');
+    preflightCheck(contentDir);
+    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const checking = step('Checking links');
+    // Generated OpenAPI pages are link targets too - same step dev/build run.
+    const { generateApiPages } = await import('../src/cli/generate-api-pages.js');
+    await generateApiPages({ contentDir });
+    const { checkLinks } = await import('../src/lib/link-check.js');
+    const { formatContentIssues } = await import('../src/lib/content-check.js');
+    const result = await checkLinks(contentDir, configText);
+    checking.stop();
+
+    const summary = `${plural(result.links, 'link')} in ${plural(result.pages, 'page')}${
+      result.external ? color.dim(` (${plural(result.external, 'external link')} not checked)`) : ''
+    }`;
+    if (result.broken.length === 0) {
+      log.success(`No broken links - checked ${summary}`);
+      return;
+    }
+    log.error(plural(result.broken.length, 'broken link'));
+    log.line();
+    log.line(formatContentIssues(result.broken));
+    log.line();
+    log.error(`${plural(result.broken.length, 'broken link')} - checked ${summary}`);
+    throw new CliExit(1);
+  });
+
+program
+  // Same shape as `broken-links`: reads the project, exits 0 (nothing
+  // found) or 1.
+  .command('a11y')
+  .description('Check accessibility - color contrast, image alt text, headings, link text')
+  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
+  .action(async (dir) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    const { preflightCheck } = await import('../src/cli/preflight.js');
+    preflightCheck(contentDir);
+    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const checking = step('Checking accessibility');
+    const { checkAccessibility } = await import('../src/lib/a11y-check.js');
+    const { formatContentIssues } = await import('../src/lib/content-check.js');
+    const result = await checkAccessibility(contentDir, configText);
+    checking.stop();
+
+    if (result.issues.length === 0) {
+      log.success(`No accessibility issues - checked writedocs.json and ${plural(result.pages, 'page')}`);
+      return;
+    }
+    const count = plural(result.issues.length, 'accessibility issue');
+    log.error(count);
+    log.line();
+    log.line(formatContentIssues(result.issues));
+    log.line();
+    log.error(`${count} - checked writedocs.json and ${plural(result.pages, 'page')}`);
+    throw new CliExit(1);
+  });
+
 program
   .command('convert')
   .description("Convert another docs tool's config into writedocs.json")
@@ -203,6 +268,7 @@ program
 
 program.parseAsync(process.argv).catch((err) => {
   // A command that already printed its own error throws CliExit.
+  stopActiveStep();
   if (err instanceof CliExit) process.exit(err.code);
   log.error(errorText(err));
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.12",
+  "version": "0.6.0",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/cli/astro-output.js

@@ -3,6 +3,7 @@
 // author's file and line, and the reason in one sentence - instead of a
 // bundler error with a stack trace; a log line is either something the
 // author should see or noise to hide.
+import fs from 'node:fs';
 import path from 'node:path';
 
 const ANSI = /\x1b\[[0-9;]*m/g;
@@ -12,10 +13,14 @@ export const stripAnsi = (text) => String(text ?? '').replace(ANSI, '');
 // append these sections after the message itself.
 const SECTION = /\n\s*(Stack trace|Hint|Error reference|Location|Caused by):/;
 
-function relativeTo(contentDir, file) {
-  if (!file) return null;
+function absolutePath(file, root) {
   const clean = file.replace(/^file:\/\/\/?/, '').replace(/[?#].*$/, '');
-  const abs = path.resolve(clean);
+  return path.resolve(root ?? process.cwd(), clean);
+}
+
+function relativeTo(contentDir, file, root) {
+  if (!file) return null;
+  const abs = absolutePath(file, root);
   const rel = path.relative(contentDir, abs);
   if (rel.startsWith('..') || path.isAbsolute(rel)) return null;
   return rel.split(path.sep).join('/');
@@ -28,8 +33,9 @@ function position(line, column) {
 
 /** Everything an Astro/Vite error can say, as { where, message, hint }.
  *  `input` is a serialized error (astro-worker.js serializeError) or the
- *  text of an error log line. */
-export function describeError(input, contentDir) {
+ *  text of an error log line. `root`: the folder relative paths in it are
+ *  relative to - Astro's working folder, the package root. */
+export function describeError(input, contentDir, { root } = {}) {
   const error = typeof input === 'string' ? { message: input } : input ?? {};
   let text = stripAnsi(error.message).replace(/\r/g, '');
   let file = error.loc?.file ?? null;
@@ -58,6 +64,27 @@ export function describeError(input, contentDir) {
     }
   }
 
+  // A rolldown diagnostic, with a code frame of the *compiled* module
+  // (whose line numbers aren't the page's):
+  //   [UNRESOLVED_IMPORT] Could not resolve './pic.png' in ../docs/page.mdx
+  //      ╭─[ ../docs/page.mdx:9:29 ]
+  const diagnostic = text.match(/^\[([A-Z][A-Z_]+)\]\s+([^\n]*)/);
+  if (diagnostic) {
+    const unresolved = diagnostic[2].match(/^Could not resolve '([^']+)' in (.+)$/);
+    if (unresolved) {
+      const [, spec, from] = unresolved;
+      file = file ?? from.trim();
+      text = `Can't find ${spec}, which this page uses.`;
+      // The line it's on in the page itself.
+      try {
+        const index = fs.readFileSync(absolutePath(file, root), 'utf8').split('\n').findIndex((l) => l.includes(spec));
+        if (index !== -1) line = index + 1;
+      } catch {}
+    } else {
+      text = diagnostic[2];
+    }
+  }
+
   // Astro's own sections: keep the hint, and take the file from the first
   // stack frame when it's one of the author's files.
   const sectionAt = text.search(SECTION);
@@ -93,7 +120,7 @@ export function describeError(input, contentDir) {
 
   if (name === 'YAMLException') text = `Frontmatter isn't valid YAML: ${text}`;
 
-  const rel = relativeTo(contentDir, file);
+  const rel = relativeTo(contentDir, file, root);
   return {
     where: rel ? `${rel}${position(line, column)}` : null,
     message: text || 'Unknown error.',

package/src/cli/build.js

@@ -72,7 +72,7 @@ export async function runBuild({ contentDir, packageRoot, verbose = false }) {
   if (fatal || code !== 0) {
     building.fail('Build failed');
     if (fatal) {
-      const problem = describeError(fatal, contentDir);
+      const problem = describeError(fatal, contentDir, { root: packageRoot });
       log.line();
       log.line(formatProblems([{ where: problem.where, message: problem.message }]));
       if (problem.hint) log.line(`\n${color.dim(`  Hint: ${problem.hint}`)}`);

package/src/cli/dev.js

@@ -112,7 +112,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
           return;
         case 'astro-log': {
           if (event.level === 'error') {
-            showError(describeError(stripAnsi(event.message), contentDir));
+            showError(describeError(stripAnsi(event.message), contentDir, { root: packageRoot }));
             return;
           }
           const request = requestLog(event);
@@ -151,7 +151,7 @@ export async function runDev({ contentDir, packageRoot, port, verbose = false })
   if (!ready) starting.fail('Could not start the local preview');
   else log.error('The local preview stopped unexpectedly.');
   if (fatal) {
-    const problem = describeError(fatal, contentDir);
+    const problem = describeError(fatal, contentDir, { root: packageRoot });
     log.line();
     log.line(formatProblems([{ where: problem.where, message: problem.message }]));
     if (problem.hint) log.line(`\n${color.dim(`  Hint: ${problem.hint}`)}`);

package/src/cli/generate-api-pages.js

@@ -5,8 +5,8 @@ import matter from 'gray-matter';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { parseOpenApiRef, openApiOperationKey, specDirName } from '../lib/openapi-ref.js';
 import { findAllPages } from '../lib/pages.js';
+import { HTTP_METHODS, collectOpenApiGroups } from '../lib/openapi-spec.js';
 
-const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 
 /** Canonical "METHOD /path" key used everywhere an operation needs to be
  *  identified: the manifest, a hand-written page's `openapi:` frontmatter,
@@ -172,61 +172,6 @@ function rmrf(dir) {
   fs.rmSync(dir, { recursive: true, force: true });
 }
 
-/** Walks writedocs.json's raw `navigation` tree (any shape - a bare array, or
- *  an object choosing tabs/versions/languages/dropdowns/products, plus
- *  `global.dropdowns`) looking for group nodes shaped like
- *  `{ group, openapi: { src, path } }`, however deeply nested inside
- *  hand-authored groups or containers. Runs directly against the raw
- *  JSON (before writedocs.json's own zod validation even happens - this CLI
- *  step runs first, see generateApiPages() below), so it deliberately
- *  doesn't import anything from lib/config.ts and just duck-types each
- *  node the same way lib/config.ts's own walkSections()/
- *  expandOpenApiInContainer() do. */
-function collectOpenApiGroups(navigation) {
-  const found = [];
-
-  function fromPagesItem(item) {
-    if (!item || typeof item !== 'object') return; // plain page-slug string - not a group
-    if (item.group && item.openapi) {
-      found.push(item);
-      return;
-    }
-    if (Array.isArray(item.pages)) {
-      for (const child of item.pages) fromPagesItem(child);
-    }
-    // otherwise a { label, href } link leaf - nothing to collect
-  }
-
-  function fromContainer(node) {
-    if (!node || typeof node !== 'object') return;
-    if (Array.isArray(node.pages)) {
-      for (const item of node.pages) fromPagesItem(item);
-    } else if (Array.isArray(node.tabs)) {
-      for (const t of node.tabs) fromContainer(t);
-    } else if (Array.isArray(node.versions)) {
-      for (const v of node.versions) fromContainer(v);
-    } else if (Array.isArray(node.languages)) {
-      for (const l of node.languages) fromContainer(l);
-    } else if (Array.isArray(node.dropdowns)) {
-      for (const d of node.dropdowns) fromContainer(d);
-    } else if (Array.isArray(node.products)) {
-      for (const p of node.products) fromContainer(p);
-    }
-    // otherwise a bare { href } container - nothing to collect
-  }
-
-  if (Array.isArray(navigation)) {
-    for (const item of navigation) fromPagesItem(item);
-  } else if (navigation && typeof navigation === 'object') {
-    if (Array.isArray(navigation.global?.dropdowns)) {
-      for (const d of navigation.global.dropdowns) fromContainer(d);
-    }
-    fromContainer(navigation);
-  }
-
-  return found;
-}
-
 /** Generates every page for one `{ group, openapi: { src, path } }`
  *  navigation node: dereferences its spec, writes a stub page per
  *  operation (unless a hand-written override already claims it), and

package/src/cli/output.js

@@ -67,6 +67,11 @@ export function indent(text, spaces) {
     .join('\n');
 }
 
+/** Ends whatever step is still spinning - for an error thrown mid-step. */
+export function stopActiveStep() {
+  activeSpinner?.stop();
+}
+
 const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
 
 /** A step in progress: a spinner with `text` on a terminal, nothing
@@ -76,6 +81,7 @@ export function step(text) {
   let frame = 0;
   let timer = null;
   const spinner = {
+    stop: () => end(),
     clear() {
       stream.write('\r\x1b[2K');
     },

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 };
+}