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

package/helpers/schemaToTableData.js

@@ -0,0 +1,311 @@
+import { getConstraints } from './getConstraints';
+
+function processOptions(
+  choices,
+  level,
+  path,
+  isNestedInProperty,
+  requiredArray = [],
+  continuingLevels = [],
+) {
+  return choices.map((optionSchema, index) => {
+    const optionTitle = optionSchema.title || 'Option';
+
+    // Determine if this is the last option in the list.
+    // If it is NOT the last option, its children must not close the visual tree branch.
+    const isLastOption = index === choices.length - 1;
+
+    let optionRows = [];
+
+    // This is a primitive type (string, number, etc.) within a choice
+    if (optionSchema.type && !optionSchema.properties) {
+      const isRequired = requiredArray.includes(path[path.length - 1]);
+      const constraints = getConstraints(optionSchema);
+      if (isRequired) {
+        constraints.unshift('required');
+      }
+
+      optionRows.push({
+        type: 'property',
+        // The name of the property is the name of the parent property that holds the choice
+        name: path.length > 0 ? path[path.length - 1] : optionTitle,
+        path: [...path, `(${optionTitle})`],
+        // If it's a top-level choice (like user_id), the level is the same as the choice itself.
+        // Otherwise, it's nested.
+        level: level,
+        required: isRequired,
+        propertyType: optionSchema.type,
+        description: optionSchema.description,
+        example: optionSchema.examples || optionSchema.example,
+        constraints: constraints,
+        isLastInGroup: isLastOption, // Updated: Uses the calculated flag instead of always true
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+      });
+    } else {
+      // This is a complex object within a choice
+      optionRows = schemaToTableData(
+        optionSchema,
+        // If nested in a property (like payment_method), the sub-properties start at the same level as the choice
+        // Otherwise, they are one level deeper.
+        level,
+        isNestedInProperty ? [] : path,
+        continuingLevels,
+        isLastOption,
+      );
+    }
+
+    return {
+      title: optionTitle,
+      description: optionSchema.description,
+      rows: optionRows,
+    };
+  });
+}
+
+export function schemaToTableData(
+  schema,
+  level = 0,
+  path = [],
+  parentContinuingLevels = [],
+  isLastOption = true,
+) {
+  const flatRows = [];
+
+  function isEffectivelyEmpty(schemaNode) {
+    if (
+      schemaNode.type !== 'object' &&
+      typeof schemaNode.properties === 'undefined'
+    ) {
+      return false;
+    }
+    if (schemaNode.oneOf || schemaNode.anyOf) {
+      return false;
+    }
+    if (
+      !schemaNode.properties ||
+      Object.keys(schemaNode.properties).length === 0
+    ) {
+      return true;
+    }
+    return Object.values(schemaNode.properties).every(isEffectivelyEmpty);
+  }
+
+  function buildRows(
+    subSchema,
+    currentLevel,
+    currentPath,
+    requiredFromParent = [],
+    continuingLevels = [],
+  ) {
+    if (!subSchema) return;
+
+    if (subSchema.properties) {
+      const propKeys = Object.keys(subSchema.properties);
+      const hasSiblingChoices = !!(subSchema.oneOf || subSchema.anyOf);
+
+      // Filter out properties that should be skipped to get accurate count
+      const visiblePropKeys = propKeys.filter((name) => {
+        const propSchema = subSchema.properties[name];
+        return !(
+          propSchema['x-gtm-clear'] === true && isEffectivelyEmpty(propSchema)
+        );
+      });
+
+      visiblePropKeys.forEach((name, index) => {
+        const propSchema = subSchema.properties[name];
+        const newPath = [...currentPath, name];
+
+        const isLastProp =
+          index === visiblePropKeys.length - 1 && !hasSiblingChoices;
+
+        // Updated Logic:
+        // A property is visually "last" only if it is the last property
+        // AND (it is deeper in the hierarchy OR the parent option itself is the last one).
+        const isLast = isLastProp && (currentLevel !== level || isLastOption);
+
+        const isChoiceWrapper = !!(propSchema.oneOf || propSchema.anyOf);
+
+        // Determine if this property has children and what type
+        const hasNestedProperties = !!propSchema.properties;
+        const hasArrayItems =
+          propSchema.type === 'array' && !!propSchema.items?.properties;
+        const hasNestedChoice = isChoiceWrapper;
+        const hasChildren =
+          hasNestedProperties || hasArrayItems || hasNestedChoice;
+
+        // Determine container type for the symbol
+        let containerType = null;
+        if (
+          hasNestedProperties ||
+          (isChoiceWrapper && propSchema.type === 'object')
+        ) {
+          containerType = 'object';
+        } else if (hasArrayItems) {
+          containerType = 'array';
+        }
+
+        // Calculate continuing levels for children
+        // If this is not the last item, add current level to continuing levels for children
+        // If this IS the last item, remove the immediate parent level (currentLevel - 1) because
+        // that line stops at this item and should not continue through its children
+        const childContinuingLevels = isLast
+          ? continuingLevels.filter((lvl) => lvl !== currentLevel - 1)
+          : [...continuingLevels, currentLevel];
+
+        // This is a "simple" choice property like user_id.
+        // It gets unwrapped into a choice row directly.
+        if (
+          isChoiceWrapper &&
+          !propSchema.properties &&
+          propSchema.type !== 'object'
+        ) {
+          const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
+          const choices = propSchema[choiceType];
+          flatRows.push({
+            type: 'choice',
+            choiceType,
+            path: newPath,
+            level: currentLevel,
+            title: propSchema.title,
+            description: propSchema.description,
+            isLastInGroup: isLast,
+            hasChildren: false,
+            containerType: null,
+            continuingLevels: [...continuingLevels],
+            options: processOptions(
+              choices,
+              currentLevel,
+              newPath,
+              false,
+              subSchema.required || requiredFromParent,
+              childContinuingLevels,
+            ),
+          });
+        } else {
+          // This is a "normal" property or a complex one with a nested choice.
+          const isRequired =
+            (subSchema.required || requiredFromParent)?.includes(name) || false;
+          const constraints = getConstraints(propSchema);
+          if (isRequired) {
+            constraints.unshift('required');
+          }
+
+          flatRows.push({
+            type: 'property',
+            name,
+            path: newPath,
+            level: currentLevel,
+            required: isRequired,
+            propertyType:
+              propSchema.type || (propSchema.enum ? 'enum' : 'object'),
+            description: propSchema.description,
+            example: propSchema.examples || propSchema.example,
+            constraints,
+            isLastInGroup: isLast,
+            hasChildren,
+            containerType,
+            continuingLevels: [...continuingLevels],
+          });
+
+          if (propSchema.properties) {
+            buildRows(
+              propSchema,
+              currentLevel + 1,
+              newPath,
+              propSchema.required,
+              childContinuingLevels,
+            );
+          } else if (
+            propSchema.type === 'array' &&
+            propSchema.items?.properties
+          ) {
+            buildRows(
+              propSchema.items,
+              currentLevel + 1,
+              [...newPath, '[n]'],
+              propSchema.items.required,
+              childContinuingLevels,
+            );
+          } else if (isChoiceWrapper) {
+            // This handles the "complex" choice property like payment_method.
+            // A property row has already been created above, now we add the choice row.
+            const choiceType = propSchema.oneOf ? 'oneOf' : 'anyOf';
+            const choices = propSchema[choiceType];
+            flatRows.push({
+              type: 'choice',
+              choiceType,
+              path: [...newPath, choiceType], // Make path unique
+              level: currentLevel + 1,
+              title: propSchema.title,
+              description: null,
+              isLastInGroup: true,
+              hasChildren: false,
+              containerType: null,
+              continuingLevels: childContinuingLevels,
+              options: processOptions(
+                choices,
+                currentLevel + 1,
+                newPath,
+                true,
+                propSchema.required,
+                childContinuingLevels,
+              ),
+            });
+          }
+        }
+      });
+    }
+
+    // This handles choices at the root of a schema
+    const choiceType = subSchema.oneOf
+      ? 'oneOf'
+      : subSchema.anyOf
+        ? 'anyOf'
+        : null;
+    if (choiceType) {
+      const choices = subSchema[choiceType];
+      flatRows.push({
+        type: 'choice',
+        choiceType,
+        path: currentPath,
+        level: currentLevel,
+        title: subSchema.title,
+        description: subSchema.description,
+        isLastInGroup: true,
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+        options: processOptions(
+          choices,
+          currentLevel,
+          currentPath,
+          false,
+          subSchema.required || requiredFromParent,
+          continuingLevels,
+        ),
+      });
+    } else if (!subSchema.properties && subSchema.type) {
+      // This handles a schema that is just a single primitive type
+      flatRows.push({
+        type: 'property',
+        name: subSchema.title || '<value>',
+        path: currentPath,
+        level: currentLevel,
+        required: false,
+        propertyType: subSchema.type,
+        description: subSchema.description,
+        example: subSchema.examples || subSchema.example,
+        constraints: getConstraints(subSchema),
+        isLastInGroup: true,
+        hasChildren: false,
+        containerType: null,
+        continuingLevels: [...continuingLevels],
+      });
+    }
+  }
+
+  buildRows(schema, level, path, schema.required, parentContinuingLevels);
+  return flatRows;
+}

package/helpers/update-schema-ids.js

@@ -0,0 +1,47 @@
+import fs from 'fs';
+import path from 'path';
+
+export default function updateSchemaIds(siteDir, url, version = null) {
+  const versionsJsonPath = path.join(siteDir, 'versions.json');
+  if (!fs.existsSync(versionsJsonPath)) {
+    console.log('No versions.json file found, skipping schema ID update.');
+    return;
+  }
+
+  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;
+  };
+
+  const versions = version
+    ? [version]
+    : JSON.parse(fs.readFileSync(versionsJsonPath, 'utf8'));
+
+  for (const version of versions) {
+    const schemaDir = path.join(siteDir, 'static/schemas', version);
+    if (!fs.existsSync(schemaDir)) {
+      continue;
+    }
+    const files = getAllFiles(schemaDir);
+
+    for (const file of files) {
+      const schema = JSON.parse(fs.readFileSync(file, 'utf8'));
+      const baseUrl = url.endsWith('/') ? url.slice(0, -1) : url;
+      const relativePath = path.relative(path.join(siteDir, 'static'), file);
+      schema.$id = `${baseUrl}/${relativePath.replace(/\\/g, '/')}`;
+      fs.writeFileSync(file, JSON.stringify(schema, null, 2));
+      console.log(`Updated $id for ${file} in version ${version}`);
+    }
+  }
+}

package/index.js

@@ -1,60 +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';
 
 export default async function (context) {
-    const { siteDir } = context;
-    const { organizationName, projectName } = context.siteConfig;
-    const options = { organizationName, projectName, siteDir };
-    const schemasPath = path.join(siteDir, 'static/schemas');
-
-    // Generate docs on startup
-    await generateEventDocs(options);
-
-    return {
-        name: 'docusaurus-plugin-generate-schema-docs',
-
-        getPathsToWatch() {
-            // Watch the schemas directory for changes
-            return [schemasPath];
-        },
-
-        async loadContent() {
-            // Generate event documentation when watched files change
-            await generateEventDocs(options);
-        },
-
-        getThemePath() {
-            return './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, 'static/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();
-                });
-        },
-    };
+  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.2.0",
+  "version": "1.3.0",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",