docusaurus-plugin-generate-schema-docs 1.1.1 → 1.3.0

package/index.js

@@ -1,50 +1,149 @@
+import { getPathsForVersion } from './helpers/path-helpers.js';
+import updateSchemaIds from './helpers/update-schema-ids.js';
+import fs from 'fs';
 import validateSchemas from './validateSchemas.js';
 import generateEventDocs from './generateEventDocs.js';
 import path from 'path';
-import { fileURLToPath } from 'url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
-
-export default function (context, options) {
-    return {
-        name: 'docusaurus-plugin-generate-schema-docs',
-
-        getThemePath() {
-            return path.resolve(__dirname, './components');
-        },
-
-        extendCli(cli) {
-            cli
-                .command('validate-schemas')
-                .description('Validate JSON Schemas with the examples inside the schemas')
-                .action(async () => {
-                    console.log('Validating GTM Schemas...');
-                    // You might get the path from 'options' or assume a default
-                    const schemaPath = options?.path || path.join(context.siteDir, 'schemas');
-
-                    const success = await validateSchemas(schemaPath);
-
-                    if (!success)
-                    {
-                        console.error('Validation failed.');
-                        process.exit(1); // Important for CI to fail!
-                    }
-                    console.log('✅ All schemas and examples are valid!');
-                });
-
-            cli
-                .command('generate schema-docs')
-                .description('Generate schema documentation from JSON schemas')
-                .action(async () => {
-                    // You can pass options here if generateEventDocs needs the path too
-                    // e.g., await generateEventDocs(options.path || './static/schemas');
-                    await generateEventDocs();
-                });
-        },
-
-        async loadContent() {
-            await generateEventDocs();
-        },
-    };
-}
+
+export default async function (context) {
+  const { siteDir } = context;
+  const { organizationName, projectName, url } = context.siteConfig;
+  const options = { organizationName, projectName, siteDir, url };
+  const versionsJsonPath = path.join(siteDir, 'versions.json');
+  const isVersioned = fs.existsSync(versionsJsonPath);
+
+  const extendCli = (cli) => {
+    cli
+      .command('validate-schemas [version]')
+      .description('Validate JSON Schemas with the examples inside the schemas')
+      .action(async (version) => {
+        console.log('Validating GTM Schemas...');
+        const schemaVersion = version || 'next';
+        const { schemaDir } = getPathsForVersion(
+          schemaVersion,
+          context.siteDir,
+        );
+        const success = await validateSchemas(schemaDir);
+        if (!success) {
+          console.error('Validation failed.');
+          process.exit(1);
+        }
+        console.log('✅ All schemas and examples are valid!');
+      });
+
+    cli
+      .command('generate-schema-docs')
+      .description('Generate schema documentation from JSON schemas')
+      .action(async () => {
+        if (isVersioned) {
+          const versions = JSON.parse(
+            fs.readFileSync(versionsJsonPath, 'utf8'),
+          );
+          for (const version of versions) {
+            await generateEventDocs({ ...options, version });
+          }
+          await generateEventDocs({ ...options, version: 'current' });
+        } else {
+          await generateEventDocs(options);
+        }
+      });
+
+    cli
+      .command('update-schema-ids [version]')
+      .description('Update the $id of the versioned schemas')
+      .action((version) => {
+        updateSchemaIds(siteDir, url, version);
+      });
+
+    cli
+      .command('version-with-schemas <version>')
+      .description(
+        'Create a new docs version and copy schemas from next to versioned folder',
+      )
+      .action(async (version) => {
+        const { execSync } = await import('child_process');
+
+        console.log(`📦 Creating docs version ${version}...`);
+        try {
+          // Run the standard docusaurus docs:version command
+          execSync(`npx docusaurus docs:version ${version}`, {
+            cwd: siteDir,
+            stdio: 'inherit',
+          });
+        } catch (error) {
+          console.error('❌ Failed to create docs version');
+          process.exit(1);
+        }
+
+        console.log(`📂 Copying schemas from next to ${version}...`);
+        const nextSchemasDir = path.join(siteDir, 'static/schemas/next');
+        const versionedSchemasDir = path.join(
+          siteDir,
+          'static/schemas',
+          version,
+        );
+
+        if (!fs.existsSync(nextSchemasDir)) {
+          console.error(
+            `❌ Source schemas directory not found: ${nextSchemasDir}`,
+          );
+          process.exit(1);
+        }
+
+        // Copy the schemas
+        try {
+          fs.cpSync(nextSchemasDir, versionedSchemasDir, { recursive: true });
+          console.log(`✅ Schemas copied to ${versionedSchemasDir}`);
+        } catch (error) {
+          console.error(`❌ Failed to copy schemas: ${error.message}`);
+          process.exit(1);
+        }
+
+        // Update schema IDs for the new version
+        console.log(`🔄 Updating schema $ids for version ${version}...`);
+        updateSchemaIds(siteDir, url, version);
+
+        // Generate documentation for the new version
+        console.log(`📝 Generating documentation for version ${version}...`);
+        await generateEventDocs({ ...options, version });
+
+        console.log(`\n✅ Version ${version} created successfully!`);
+        console.log(`\nNext steps:`);
+        console.log(`  1. Review the changes in static/schemas/${version}/`);
+        console.log(
+          `  2. Review the changes in versioned_docs/version-${version}/`,
+        );
+        console.log(`  3. Commit the changes to version control`);
+      });
+  };
+
+  const schemasPath = isVersioned
+    ? path.join(siteDir, 'static/schemas/next')
+    : path.join(siteDir, 'static/schemas');
+
+  return {
+    name: 'docusaurus-plugin-generate-schema-docs',
+
+    getPathsToWatch() {
+      return [schemasPath];
+    },
+
+    async loadContent() {
+      if (isVersioned) {
+        const versions = JSON.parse(fs.readFileSync(versionsJsonPath, 'utf8'));
+        for (const version of versions) {
+          await generateEventDocs({ ...options, version });
+        }
+        await generateEventDocs({ ...options, version: 'current' });
+      } else {
+        await generateEventDocs(options);
+      }
+    },
+
+    getThemePath() {
+      return './components';
+    },
+
+    extendCli,
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",
@@ -10,11 +10,14 @@
   },
   "dependencies": {
     "@apidevtools/json-schema-ref-parser": "^15.1.3",
-    "fs-extra": "^11.2.0",
+    "fs-extra": "^11.3.3",
     "json-schema-merge-allof": "^0.8.1"
   },
   "publishConfig": {
     "access": "public",
     "provenance": true
+  },
+  "devDependencies": {
+    "jest": "^30.2.0"
   }
-}
+}

package/validateSchemas.js

@@ -2,85 +2,71 @@ import fs from 'fs';
 import path from 'path';
 import buildExampleFromSchema from './helpers/buildExampleFromSchema';
 import Ajv2020 from 'ajv/dist/2020.js';
-import $RefParser from "@apidevtools/json-schema-ref-parser";
-import mergeJsonSchema from "json-schema-merge-allof";
+import addFormats from 'ajv-formats';
+import processSchema from './helpers/processSchema';
 
 const validateSchemas = async (schemaPath) => {
-    const ajv = new Ajv2020();
-    ajv.addKeyword('x-gtm-clear');
+  const ajv = new Ajv2020();
+  addFormats(ajv);
+  ajv.addKeyword('x-gtm-clear');
 
-    const getAllFiles = (dir, allFiles = []) => {
-        const files = fs.readdirSync(dir);
+  const getAllFiles = (dir, allFiles = []) => {
+    const files = fs.readdirSync(dir);
 
-        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);
-                }
-            }
-        });
-        return allFiles;
-    };
+    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);
+        }
+      }
+    });
+    return allFiles;
+  };
 
-    const allSchemaFiles = getAllFiles('schemas');
-    for (const file of allSchemaFiles)
-    {
-        const schemaContent = fs.readFileSync(file, 'utf-8');
-        const schema = JSON.parse(schemaContent);
-        ajv.addSchema(schema);
-    }
+  const allSchemaFiles = getAllFiles(schemaPath);
+  for (const file of allSchemaFiles) {
+    const schemaContent = fs.readFileSync(file, 'utf-8');
+    const schema = JSON.parse(schemaContent);
+    ajv.addSchema(schema);
+  }
 
-    const schemaFiles = fs.readdirSync(schemaPath).filter(file => file.endsWith('.json'));
-    let allValid = true;
-    for (const file of schemaFiles)
-    {
-        const filePath = path.join(schemaPath, file);
-        
-        // Dereference and merge, same as in generateEventDocs.js
-        const clonedSchema = await $RefParser.dereference(filePath, {
-            mutateInputSchema: false, dereference: {
-                circular: 'ignore'
-            }
-        });
-        const mergedSchema = mergeJsonSchema(clonedSchema, {
-            resolvers: {
-                defaultResolver: mergeJsonSchema.options.resolvers.title
-            }
-        });
+  const schemaFiles = fs
+    .readdirSync(schemaPath)
+    .filter((file) => file.endsWith('.json'));
+  let allValid = true;
+  for (const file of schemaFiles) {
+    const filePath = path.join(schemaPath, file);
 
-        const example_data = buildExampleFromSchema(mergedSchema);
+    const mergedSchema = await processSchema(filePath);
 
-        if (!example_data)
-        {
-            console.error(`❌ 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(`❌ Could not find compiled schema for ${originalSchema.$id}`);
-                allValid = false;
-                continue;
-            }
-            if (validate(example_data))
-            {
-                console.log(`✅ Schema ${file} produced a valid example.`);
-            } else
-            {
-                console.error(`❌ Schema ${file} example data failed validation:`);
-                console.error(validate.errors);
-                allValid = false;
-            }
-        }
+    const example_data = buildExampleFromSchema(mergedSchema);
+
+    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;
+      }
     }
-    return allValid;
+  }
+  return allValid;
 };
 
 export default validateSchemas;