docusaurus-plugin-generate-schema-docs 1.8.3 → 1.8.5

package/helpers/schemaTraversal.cjs

@@ -0,0 +1,148 @@
+function visitSchemaNodes(schema, visitor, path = []) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  visitor(schema, { path });
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.entries(schema.properties).forEach(([key, propertySchema]) => {
+      visitSchemaNodes(propertySchema, visitor, [...path, 'properties', key]);
+    });
+  }
+
+  if (schema.items && typeof schema.items === 'object') {
+    visitSchemaNodes(schema.items, visitor, [...path, 'items']);
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf.forEach((optionSchema, index) => {
+      visitSchemaNodes(optionSchema, visitor, [...path, 'oneOf', index]);
+    });
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    schema.anyOf.forEach((optionSchema, index) => {
+      visitSchemaNodes(optionSchema, visitor, [...path, 'anyOf', index]);
+    });
+  }
+
+  if (schema.if && typeof schema.if === 'object') {
+    visitSchemaNodes(schema.if, visitor, [...path, 'if']);
+  }
+
+  if (schema.then && typeof schema.then === 'object') {
+    visitSchemaNodes(schema.then, visitor, [...path, 'then']);
+  }
+
+  if (schema.else && typeof schema.else === 'object') {
+    visitSchemaNodes(schema.else, visitor, [...path, 'else']);
+  }
+}
+
+function visitPropertyEntryBranches(
+  schema,
+  visitor,
+  { prefix = '', path = [], skipArraySubProperties = false } = {},
+) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  if (Array.isArray(schema.oneOf)) {
+    schema.oneOf.forEach((optionSchema, index) => {
+      visitSchemaPropertyEntries(optionSchema, visitor, {
+        prefix,
+        path: [...path, 'oneOf', index],
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  if (Array.isArray(schema.anyOf)) {
+    schema.anyOf.forEach((optionSchema, index) => {
+      visitSchemaPropertyEntries(optionSchema, visitor, {
+        prefix,
+        path: [...path, 'anyOf', index],
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  if (schema.then && typeof schema.then === 'object') {
+    visitSchemaPropertyEntries(schema.then, visitor, {
+      prefix,
+      path: [...path, 'then'],
+      skipArraySubProperties,
+    });
+  }
+
+  if (schema.else && typeof schema.else === 'object') {
+    visitSchemaPropertyEntries(schema.else, visitor, {
+      prefix,
+      path: [...path, 'else'],
+      skipArraySubProperties,
+    });
+  }
+}
+
+function visitSchemaPropertyEntries(
+  schema,
+  visitor,
+  { prefix = '', path = [], skipArraySubProperties = false } = {},
+) {
+  if (!schema || typeof schema !== 'object') {
+    return;
+  }
+
+  if (schema.properties && typeof schema.properties === 'object') {
+    Object.entries(schema.properties).forEach(([key, propertySchema]) => {
+      const currentName = prefix ? `${prefix}.${key}` : key;
+      const currentPath = [...path, 'properties', key];
+
+      visitor(propertySchema, {
+        key,
+        name: currentName,
+        path: currentPath,
+        parentSchema: schema,
+      });
+
+      if (propertySchema?.type === 'object' && propertySchema.properties) {
+        visitSchemaPropertyEntries(propertySchema, visitor, {
+          prefix: currentName,
+          path: currentPath,
+          skipArraySubProperties,
+        });
+      }
+
+      if (
+        propertySchema?.type === 'array' &&
+        propertySchema.items?.properties &&
+        !skipArraySubProperties
+      ) {
+        visitSchemaPropertyEntries(propertySchema.items, visitor, {
+          prefix: `${currentName}.0`,
+          path: [...currentPath, 'items'],
+          skipArraySubProperties,
+        });
+      }
+
+      visitPropertyEntryBranches(propertySchema, visitor, {
+        prefix: currentName,
+        path: currentPath,
+        skipArraySubProperties,
+      });
+    });
+  }
+
+  visitPropertyEntryBranches(schema, visitor, {
+    prefix,
+    path,
+    skipArraySubProperties,
+  });
+}
+
+module.exports = {
+  visitSchemaNodes,
+  visitSchemaPropertyEntries,
+};

package/helpers/trackingTargets.js

@@ -10,6 +10,28 @@ export const SUPPORTED_TRACKING_TARGETS = [
 
 const TARGET_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+){2,}$/;
 
+function isReferenceAggregatorSchema(schema) {
+  if (!schema || typeof schema !== 'object') {
+    return false;
+  }
+
+  const hasChoiceAggregation =
+    Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf);
+  const hasPropertiesKeyword = Object.hasOwn(schema, 'properties');
+  const hasValidPropertiesMap =
+    hasPropertiesKeyword &&
+    schema.properties &&
+    typeof schema.properties === 'object' &&
+    !Array.isArray(schema.properties);
+  const hasOwnProperties =
+    hasValidPropertiesMap && Object.keys(schema.properties).length > 0;
+
+  return (
+    hasChoiceAggregation &&
+    (!hasPropertiesKeyword || (hasValidPropertiesMap && !hasOwnProperties))
+  );
+}
+
 export function resolveTrackingTargets(
   schema,
   { schemaFile = 'schema', isQuiet = false } = {},
@@ -17,9 +39,10 @@ export function resolveTrackingTargets(
   const configuredTargets = schema?.['x-tracking-targets'];
 
   if (configuredTargets == null) {
-    const warning = isQuiet
-      ? null
-      : `Schema ${schemaFile} is missing x-tracking-targets. Falling back to "${DEFAULT_TRACKING_TARGET}".`;
+    const warning =
+      isQuiet || isReferenceAggregatorSchema(schema)
+        ? null
+        : `Schema ${schemaFile} is missing x-tracking-targets. Falling back to "${DEFAULT_TRACKING_TARGET}".`;
     return {
       targets: [DEFAULT_TRACKING_TARGET],
       warning,

package/helpers/validator.js

@@ -9,14 +9,29 @@ import { promises as fs } from 'fs';
 import { URL } from 'url';
 import { resolveConstraintSchemaPath } from './constraintSchemaPaths.js';
 
+const schemaFileCache = new Map();
+
+export function clearSchemaFileCache() {
+  schemaFileCache.clear();
+}
+
+function readSchemaFile(filePath) {
+  if (!schemaFileCache.has(filePath)) {
+    schemaFileCache.set(
+      filePath,
+      fs.readFile(filePath, 'utf-8').then(JSON.parse),
+    );
+  }
+  return schemaFileCache.get(filePath);
+}
+
 function createAjvInstance(schemas, mainSchema, schemaPath) {
   const schemaVersion = mainSchema?.$schema;
 
   const loadSchema = async (uri) => {
     const constraintPath = resolveConstraintSchemaPath(uri);
     if (constraintPath) {
-      const schemaContent = await fs.readFile(constraintPath, 'utf-8');
-      return JSON.parse(schemaContent);
+      return readSchemaFile(constraintPath);
     }
 
     let localPath;
@@ -29,8 +44,7 @@ function createAjvInstance(schemas, mainSchema, schemaPath) {
     } else {
       localPath = path.resolve(schemaPath, uri);
     }
-    const schemaContent = await fs.readFile(localPath, 'utf-8');
-    return JSON.parse(schemaContent);
+    return readSchemaFile(localPath);
   };
 
   const options = {

package/index.js

@@ -7,8 +7,7 @@ import path from 'path';
 import { execSync } from 'child_process';
 import { fileURLToPath } from 'url';
 
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = path.dirname(__filename);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default async function (context, options) {
   const { siteDir } = context;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "docusaurus-plugin-generate-schema-docs",
-  "version": "1.8.3",
+  "version": "1.8.5",
   "description": "Docusaurus plugin to generate documentation from JSON schemas.",
   "main": "index.js",
   "license": "MIT",

package/scripts/sync-gtm.js

@@ -3,6 +3,9 @@ const path = require('path');
 const { execSync } = require('child_process');
 const RefParser = require('@apidevtools/json-schema-ref-parser');
 const mergeAllOf = require('json-schema-merge-allof');
+const {
+  visitSchemaPropertyEntries,
+} = require('../helpers/schemaTraversal.cjs');
 
 const logger = {
   _isQuiet: false,
@@ -86,48 +89,57 @@ function findJsonFiles(dir) {
   return results;
 }
 
+function isRootTrackingSchema(schema) {
+  return Boolean(schema?.properties?.event || schema?.['x-tracking-targets']);
+}
+
 function parseSchema(schema, options, prefix = '') {
-  if (!schema || !schema.properties) {
-    return [];
-  }
+  const variables = [];
+
+  visitSchemaPropertyEntries(
+    schema,
+    (property, context) => {
+      variables.push({
+        name: context.name,
+        description: property.description,
+        type: property.type,
+      });
+    },
+    {
+      prefix,
+      skipArraySubProperties: options.skipArraySubProperties,
+    },
+  );
 
-  let variables = [];
-  for (const key in schema.properties) {
-    const property = schema.properties[key];
-    const currentPath = prefix ? `${prefix}.${key}` : key;
-    variables.push({
-      name: currentPath,
-      description: property.description,
-      type: property.type,
-    });
-    if (
-      property.type === 'array' &&
-      property.items &&
-      !options.skipArraySubProperties
-    ) {
-      if (property.items.properties) {
-        variables.push(
-          ...parseSchema(property.items, options, `${currentPath}.0`),
-        );
-      }
-    } else if (property.type === 'object' && property.properties) {
-      variables.push(...parseSchema(property, options, currentPath));
-    }
-  }
   return variables;
 }
 
+function shouldIncludeSchemaForGtm(schema) {
+  if (!isRootTrackingSchema(schema)) {
+    return false;
+  }
+
+  const trackingTargets = schema?.['x-tracking-targets'];
+
+  return (
+    Array.isArray(trackingTargets) &&
+    trackingTargets.includes('web-datalayer-js')
+  );
+}
+
 async function getVariablesFromSchemas(
   schemaPath,
   { skipArraySubProperties = false },
 ) {
   const allVariables = new Map();
   const jsonFiles = findJsonFiles(schemaPath);
-  const eventFiles = jsonFiles.filter((f) => !f.includes('components'));
 
-  for (const file of eventFiles) {
+  for (const file of jsonFiles) {
     try {
       let schema = await RefParser.bundle(file);
+      if (!shouldIncludeSchemaForGtm(schema)) {
+        continue;
+      }
       schema = mergeAllOf(schema);
       const fileVariables = parseSchema(schema, { skipArraySubProperties });
       for (const variable of fileVariables) {
@@ -205,19 +217,27 @@ function createGtmVariables(variablesToCreate) {
 
 function deleteGtmVariables(variablesToDelete) {
   logger.log(`Found ${variablesToDelete.length} variables to delete.`);
+  const deleted = [];
+  const failedDeletes = [];
   for (const v of variablesToDelete) {
     const command = `gtm variables delete --variable-id ${v.variableId} --force --quiet`;
     logger.log(`Executing: ${command}`);
-    execSync(command, { stdio: 'inherit' });
+    try {
+      execSync(command, { stdio: 'inherit' });
+      deleted.push(v.parameter.find((p) => p.key === 'name').value);
+    } catch {
+      failedDeletes.push({
+        name: v.parameter.find((p) => p.key === 'name').value,
+        variableId: v.variableId,
+      });
+    }
   }
-  return variablesToDelete.map(
-    (v) => v.parameter.find((p) => p.key === 'name').value,
-  );
+  return { deleted, failedDeletes };
 }
 
 async function syncGtmVariables(
   schemaVariables,
-  { skipArraySubProperties = false },
+  { skipArraySubProperties = false } = {},
 ) {
   const gtmVariables = getGtmVariables();
 
@@ -235,12 +255,13 @@ async function syncGtmVariables(
   );
 
   const created = createGtmVariables(toCreate);
-  const deleted = deleteGtmVariables(toDelete);
+  const { deleted, failedDeletes } = deleteGtmVariables(toDelete);
 
   logger.log('GTM variable synchronization complete.');
   return {
     created,
     deleted,
+    failedDeletes,
     inSync: inSync.map((v) => v.name),
   };
 }
@@ -348,6 +369,14 @@ async function main(argv, deps) {
         ),
       );
     } else {
+      if (summary.failedDeletes?.length > 0) {
+        log.log(
+          `Skipped deleting ${summary.failedDeletes.length} GTM variables (GTM rejected the delete, they may still be referenced):`,
+        );
+        for (const failed of summary.failedDeletes) {
+          log.log(`- ${failed.name} (ID: ${failed.variableId})`);
+        }
+      }
       log.log('Synchronization successful!');
       log.log(
         `All changes applied in GTM workspace: "${workspaceName}" (ID: ${workspaceId})`,
@@ -385,9 +414,11 @@ module.exports = {
   main,
   getVariablesToCreate,
   getVariablesToDelete,
+  getGtmVariables,
   createGtmVariables,
   deleteGtmVariables,
   parseSchema,
+  shouldIncludeSchemaForGtm,
   findJsonFiles,
   safeJsonParse,
   logger,

package/test-data/payloadContracts.js

@@ -118,6 +118,41 @@ const PAYLOAD_CONTRACTS = [
       },
     },
   },
+  {
+    id: 'login-with-user-properties',
+    class: 'user_properties',
+    example: {
+      event: 'login',
+      method: 'email',
+      user_properties: {
+        sign_up_method: 'email',
+        allow_ad_personalization_signals: 'false',
+      },
+    },
+    expected: {
+      web: {
+        eventName: 'login',
+        payload: {
+          event: 'login',
+          method: 'email',
+          user_properties: {
+            sign_up_method: 'email',
+            allow_ad_personalization_signals: 'false',
+          },
+        },
+      },
+      firebase: {
+        eventName: 'login',
+        parameters: {
+          method: 'email',
+        },
+        userProperties: {
+          sign_up_method: 'email',
+          allow_personalized_ads: 'false',
+        },
+      },
+    },
+  },
   {
     id: 'web-fallback-json-serialization',
     class: 'fallback_json_serialization',

package/validateSchemas.js

@@ -43,7 +43,7 @@ const validateSingleSchema = async (filePath, schemaPath) => {
         fileHasAnyExample = true;
         const { example, title } = option;
 
-        if (!example) {
+        if (typeof example === 'undefined') {
           errors.push(
             `x Schema ${file} (option: ${title}) does not produce a valid example.`,
           );