docusaurus-plugin-generate-schema-docs 1.4.0 → 1.5.1

package/helpers/validator.js

@@ -0,0 +1,108 @@
+import Ajv from 'ajv';
+import Ajv2020 from 'ajv/dist/2020.js';
+import Ajv2019 from 'ajv/dist/2019.js';
+import AjvDraft4 from 'ajv-draft-04';
+import addFormats from 'ajv-formats';
+import ajvKeywords from 'ajv-keywords';
+import path from 'path';
+import { promises as fs } from 'fs';
+import { URL } from 'url';
+
+function createAjvInstance(schemas, mainSchema, schemaPath) {
+  const schemaVersion = mainSchema?.$schema;
+
+  const loadSchema = async (uri) => {
+    let localPath;
+    if (uri.startsWith('http')) {
+      const url = new URL(uri);
+      const pathFromUrl = url.pathname.startsWith('/schemas/')
+        ? url.pathname.substring('/schemas/'.length)
+        : url.pathname;
+      localPath = path.join(schemaPath, pathFromUrl);
+    } else {
+      localPath = path.resolve(schemaPath, uri);
+    }
+    const schemaContent = await fs.readFile(localPath, 'utf-8');
+    return JSON.parse(schemaContent);
+  };
+
+  const options = { allErrors: true, schemas: schemas };
+
+  let ajv;
+  if (schemaVersion?.includes('2020-12')) {
+    options.strict = false;
+    options.loadSchema = loadSchema;
+    ajv = new Ajv2020(options);
+  } else if (schemaVersion?.includes('2019-09')) {
+    options.strict = false;
+    options.loadSchema = loadSchema;
+    ajv = new Ajv2019(options);
+  } else if (schemaVersion?.includes('draft-07')) {
+    options.strict = false;
+    options.loadSchema = loadSchema;
+    ajv = new Ajv(options);
+  } else if (schemaVersion?.includes('draft-06')) {
+    options.strict = false;
+    options.loadSchema = loadSchema;
+    ajv = new Ajv(options);
+  } else if (schemaVersion?.includes('draft-04')) {
+    ajv = new AjvDraft4();
+    schemas.forEach((s) => ajv.addSchema(s));
+  } else {
+    options.strict = false;
+    options.loadSchema = loadSchema;
+    ajv = new Ajv(options);
+  }
+
+  addFormats(ajv);
+  if (ajv.addKeyword) {
+    ajv.addKeyword('x-gtm-clear');
+  }
+  ajvKeywords(ajv);
+
+  return ajv;
+}
+
+/**
+ * Creates a validation function for a given set of JSON schemas.
+ *
+ * @param {object[]} schemas An array of all JSON schemas.
+ * @param {object} mainSchema The main JSON schema to validate against.
+ * @returns {function(object): {valid: boolean, errors: object[]}} A function that takes data and returns a validation result.
+ */
+export async function createValidator(schemas, mainSchema, schemaPath) {
+  if (!mainSchema) {
+    mainSchema = schemas;
+    schemas = [mainSchema];
+  }
+  const ajv = createAjvInstance(schemas, mainSchema, schemaPath);
+
+  let validate;
+  if (mainSchema?.$schema?.includes('draft-04')) {
+    validate = mainSchema['$id']
+      ? ajv.getSchema(mainSchema['$id'])
+      : ajv.compile(mainSchema);
+  } else if (ajv.compileAsync) {
+    validate = await ajv.compileAsync(mainSchema);
+  } else {
+    validate = mainSchema['$id']
+      ? ajv.getSchema(mainSchema['$id'])
+      : ajv.compile(mainSchema);
+  }
+
+  if (!validate) {
+    throw new Error(
+      `Could not compile schema or find compiled schema for ${
+        mainSchema['$id'] || 'main schema'
+      }`,
+    );
+  }
+
+  return (data) => {
+    const valid = validate(data);
+    if (!valid) {
+      return { valid: false, errors: validate.errors };
+    }
+    return { valid: true, errors: [] };
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.4.0",
+  "version": "1.5.1",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",
@@ -10,8 +10,9 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.1.3",
-    "fs-extra": "^11.3.3",
-    "json-schema-merge-allof": "^0.8.1"
+    "json-schema-merge-allof": "^0.8.1",
+    "ajv": "^8.17.1",
+    "ajv-draft-04": "^1.0.0"
   },
   "publishConfig": {
     "access": "public",

package/validateSchemas.js

@@ -1,74 +1,89 @@
+import { createValidator } from './helpers/validator.js';
 import fs from 'fs';
 import path from 'path';
-import buildExampleFromSchema from './helpers/buildExampleFromSchema';
-import Ajv2020 from 'ajv/dist/2020.js';
-import addFormats from 'ajv-formats';
-import processSchema from './helpers/processSchema';
+import processSchema from './helpers/processSchema.js';
+import { schemaToExamples } from './helpers/schemaToExamples.js';
 
-const validateSchemas = async (schemaPath) => {
-  const ajv = new Ajv2020();
-  addFormats(ajv);
-  ajv.addKeyword('x-gtm-clear');
-  // see https://github.com/ajv-validator/ajv/issues/1854
-  ajv.addKeyword('$anchor');
+const validateSingleSchema = async (filePath, schemaPath) => {
+  const file = path.basename(filePath);
+  const errors = [];
+  let allValid = true;
+
+  try {
+    const mergedSchema = await processSchema(filePath);
+    const exampleGroups = schemaToExamples(mergedSchema);
+    const originalSchema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
+    const validate = await createValidator([], originalSchema, schemaPath);
+
+    if (exampleGroups.length === 0) {
+      errors.push(`x Schema ${file} does not produce any examples.`);
+      return { allValid: false, errors };
+    }
 
-  const getAllFiles = (dir, allFiles = []) => {
-    const files = fs.readdirSync(dir);
+    let fileHasValidExample = false;
+    let fileHasAnyExample = false;
 
-    files.forEach((file) => {
-      const filePath = path.join(dir, file);
-      if (fs.statSync(filePath).isDirectory()) {
-        getAllFiles(filePath, allFiles);
-      } else {
-        if (file.endsWith('.json')) {
-          allFiles.push(filePath);
+    for (const group of exampleGroups) {
+      for (const option of group.options) {
+        fileHasAnyExample = true;
+        const { example, title } = option;
+
+        if (!example) {
+          errors.push(
+            `x Schema ${file} (option: ${title}) does not produce a valid example.`,
+          );
+          allValid = false;
+          continue;
+        }
+
+        const result = validate(example);
+        if (result.valid) {
+          fileHasValidExample = true;
+        } else {
+          errors.push(
+            `x Schema ${file} (option: ${title}) example data failed validation:`,
+          );
+          errors.push(JSON.stringify(result.errors, null, 2));
+          allValid = false;
         }
       }
-    });
-    return allFiles;
-  };
+    }
 
-  const allSchemaFiles = getAllFiles(schemaPath);
-  for (const file of allSchemaFiles) {
-    const schemaContent = fs.readFileSync(file, 'utf-8');
-    const schema = JSON.parse(schemaContent);
-    ajv.addSchema(schema);
+    if (fileHasAnyExample && !fileHasValidExample) {
+      errors.push(
+        `x Schema ${file} had examples, but none of them were valid.`,
+      );
+      allValid = false;
+    }
+  } catch (error) {
+    errors.push(`x Error processing ${file}: ${error.message}`);
+    allValid = false;
   }
 
-  const schemaFiles = fs
+  return { allValid, errors };
+};
+
+const validateSchemas = async (schemaPath) => {
+  const topLevelSchemaFiles = fs
     .readdirSync(schemaPath)
     .filter((file) => file.endsWith('.json'));
-  let allValid = true;
-  for (const file of schemaFiles) {
-    const filePath = path.join(schemaPath, file);
 
-    const mergedSchema = await processSchema(filePath);
+  const results = await Promise.all(
+    topLevelSchemaFiles.map((file) => {
+      const filePath = path.join(schemaPath, file);
+      return validateSingleSchema(filePath, schemaPath);
+    }),
+  );
 
-    const example_data = buildExampleFromSchema(mergedSchema);
+  const allSucceeded = results.every((r) => r.allValid);
 
-    if (!example_data) {
-      console.error(`x Schema ${file} does not produce a valid example.`);
-      allValid = false;
-    } else {
-      const originalSchema = JSON.parse(fs.readFileSync(filePath, 'utf-8'));
-      const validate = ajv.getSchema(originalSchema.$id);
-      if (!validate) {
-        console.error(
-          `x Could not find compiled schema for ${originalSchema.$id}`,
-        );
-        allValid = false;
-        continue;
-      }
-      if (validate(example_data)) {
-        console.log(`OK Schema ${file} produced a valid example.`);
-      } else {
-        console.error(`x Schema ${file} example data failed validation:`);
-        console.error(validate.errors);
-        allValid = false;
-      }
-    }
+  if (!allSucceeded) {
+    results.forEach((r) => {
+      r.errors.forEach((e) => console.error(e));
+    });
   }
-  return allValid;
+
+  return allSucceeded;
 };
 
 export default validateSchemas;

package/__tests__/helpers/loadSchema.test.js

@@ -1,20 +0,0 @@
-/**
- * @jest-environment node
- */
-
-import path from 'path';
-import loadSchema from '../../helpers/loadSchema';
-
-describe('loadSchema', () => {
-  it('should load and parse a JSON file', () => {
-    const filePath = path.join(
-      __dirname,
-      '..',
-      '__fixtures__',
-      'validateSchemas',
-      'circular-schema.json',
-    );
-    const schema = loadSchema(filePath);
-    expect(schema.title).toBe('Circular Schema');
-  });
-});

package/helpers/loadSchema.js

@@ -1,11 +0,0 @@
-import fs from 'fs';
-
-/**
- * Loads a JSON schema file and returns its content as a JSON object.
- * @param {string} filePath Path to the JSON schema file.
- * @returns {object} The parsed JSON schema.
- */
-export default function loadSchema(filePath) {
-  const rawContent = fs.readFileSync(filePath, 'utf-8');
-  return JSON.parse(rawContent);
-}