@writedocs/generator 0.4.12 → 0.6.0

package/src/lib/content-check.js

@@ -9,6 +9,9 @@
 //   - an .mdx file doesn't parse as MDX
 //   - 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 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)
@@ -17,6 +20,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';
@@ -26,6 +33,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. */
@@ -58,7 +67,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 {
@@ -90,6 +99,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));
@@ -118,6 +129,28 @@ async function checkPage(contentDir, rel, errors, warnings) {
     );
     return;
   }
+  // 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) => {
+    const url = String(node.url ?? '');
+    if (!url || url.startsWith('/') || url.startsWith('#') || /^[a-z][a-z0-9+.-]*:/i.test(url) || url.startsWith('//')) return;
+    let target;
+    try {
+      target = path.resolve(path.dirname(path.join(contentDir, rel)), decodeURI(url.split(/[?#]/)[0]));
+    } catch {
+      return;
+    }
+    if (fs.existsSync(target)) return;
+    const line = node.position?.start?.line;
+    errors.push(
+      issue(
+        rel,
+        line ? line + lineOffset : undefined,
+        `Image ${url} doesn't exist - the build fails on it.`,
+        'The path is relative to this page\'s folder. Fix it, or use a path from the project root, like "/images/example.png".'
+      )
+    );
+  });
   for (const { name, line } of findUnknownComponents(tree)) {
     warnings.push(
       issue(
@@ -185,6 +218,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
@@ -194,7 +344,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) {
@@ -243,6 +394,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);