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

package/__tests__/index.test.js

@@ -0,0 +1,436 @@
+/**
+ * @jest-environment @stryker-mutator/jest-runner/jest-env/node
+ */
+
+import createPlugin from '../index.js';
+
+jest.mock('url', () => ({
+  fileURLToPath: jest.fn(
+    () => '/mocked/packages/docusaurus-plugin-generate-schema-docs/index.js',
+  ),
+  pathToFileURL: jest.fn((p) => ({ href: 'file://' + p })),
+}));
+
+jest.mock('../generateEventDocs.js', () => jest.fn().mockResolvedValue());
+jest.mock('../validateSchemas.js', () => jest.fn().mockResolvedValue(true));
+jest.mock('../helpers/update-schema-ids.js', () => jest.fn());
+jest.mock('child_process', () => ({ execSync: jest.fn() }));
+jest.mock('../helpers/path-helpers.js', () => ({
+  getPathsForVersion: jest
+    .fn()
+    .mockReturnValue({ schemaDir: '/site/static/schemas/next' }),
+}));
+
+jest.mock('fs', () => ({
+  existsSync: jest.fn(),
+  readFileSync: jest.fn(),
+  cpSync: jest.fn(),
+}));
+
+import generateEventDocs from '../generateEventDocs.js';
+import validateSchemas from '../validateSchemas.js';
+import updateSchemaIds from '../helpers/update-schema-ids.js';
+import { getPathsForVersion } from '../helpers/path-helpers.js';
+import fs from 'fs';
+import { execSync } from 'child_process';
+
+const makeContext = (overrides = {}) => ({
+  siteDir: '/site',
+  siteConfig: {
+    organizationName: 'org',
+    projectName: 'proj',
+    url: 'https://example.com',
+  },
+  ...overrides,
+});
+
+const makeOptions = () => ({ dataLayerName: 'dataLayer' });
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  fs.existsSync.mockReturnValue(false);
+});
+
+describe('loadContent', () => {
+  it('calls generateEventDocs once without version when not versioned', async () => {
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    await plugin.loadContent();
+
+    expect(generateEventDocs).toHaveBeenCalledTimes(1);
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.not.objectContaining({ version: expect.anything() }),
+    );
+  });
+
+  it('calls generateEventDocs for each version plus current when versioned', async () => {
+    fs.existsSync.mockReturnValue(true);
+    fs.readFileSync.mockReturnValue(JSON.stringify(['1.0', '2.0']));
+
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    await plugin.loadContent();
+
+    expect(fs.readFileSync).toHaveBeenCalledWith('/site/versions.json', 'utf8');
+    expect(generateEventDocs).toHaveBeenCalledTimes(3);
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: '1.0' }),
+    );
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: '2.0' }),
+    );
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: 'current' }),
+    );
+  });
+});
+
+describe('extendCli - validate-schemas', () => {
+  const makeCli = (targetCommand = 'validate-schemas [version]') => {
+    const action = { fn: null };
+    const cli = {
+      command: jest.fn((name) => {
+        const cmd = {
+          description: jest.fn().mockReturnThis(),
+          option: jest.fn().mockReturnThis(),
+          action: jest.fn((fn) => {
+            if (name === targetCommand) action.fn = fn;
+            return cmd;
+          }),
+        };
+        return cmd;
+      }),
+    };
+    return { cli, action };
+  };
+
+  it('calls validateSchemas with schemaDir for given version', async () => {
+    const { cli, action } = makeCli();
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+
+    // first command registered is validate-schemas
+    expect(cli.command).toHaveBeenCalledWith('validate-schemas [version]');
+    await action.fn('next');
+
+    expect(validateSchemas).toHaveBeenCalledWith('/site/static/schemas/next');
+  });
+
+  it('defaults to "next" version when no version argument given', async () => {
+    const { cli, action } = makeCli();
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+
+    await action.fn(undefined);
+    expect(getPathsForVersion).toHaveBeenCalledWith('next', '/site');
+    expect(validateSchemas).toHaveBeenCalledWith('/site/static/schemas/next');
+  });
+
+  it('exits with code 1 when validation fails', async () => {
+    validateSchemas.mockResolvedValue(false);
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {});
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+
+    const { cli, action } = makeCli();
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+
+    await action.fn('next');
+    expect(exitSpy).toHaveBeenCalledWith(1);
+
+    exitSpy.mockRestore();
+  });
+});
+
+describe('plugin structure', () => {
+  it('returns plugin with name docusaurus-plugin-generate-schema-docs', async () => {
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    expect(plugin.name).toBe('docusaurus-plugin-generate-schema-docs');
+  });
+
+  it('passes all pluginOptions properties to generateEventDocs', async () => {
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    await plugin.loadContent();
+
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({
+        organizationName: 'org',
+        projectName: 'proj',
+        siteDir: '/site',
+        url: 'https://example.com',
+        dataLayerName: 'dataLayer',
+      }),
+    );
+  });
+
+  it('checks for versions.json inside siteDir', async () => {
+    await createPlugin(makeContext(), makeOptions());
+    expect(fs.existsSync).toHaveBeenCalledWith('/site/versions.json');
+  });
+
+  it('getPathsToWatch returns static/schemas/next path when versioned', async () => {
+    fs.existsSync.mockReturnValue(true);
+    fs.readFileSync.mockReturnValue(JSON.stringify(['1.0']));
+
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    const paths = plugin.getPathsToWatch();
+    expect(paths).toContain('/site/static/schemas/next');
+  });
+
+  it('getPathsToWatch returns static/schemas path when not versioned', async () => {
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    const paths = plugin.getPathsToWatch();
+    expect(paths).toContain('/site/static/schemas');
+    expect(paths).not.toContain('/site/static/schemas/next');
+  });
+
+  it('has a getThemePath method that returns ./components', async () => {
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    expect(typeof plugin.getThemePath).toBe('function');
+    expect(plugin.getThemePath()).toBe('./components');
+  });
+});
+
+describe('extendCli - generate-schema-docs', () => {
+  const getActionForCommand = async (commandName) => {
+    let capturedAction = null;
+    const cli = {
+      command: jest.fn((name) => {
+        const cmd = {
+          description: jest.fn().mockReturnThis(),
+          option: jest.fn().mockReturnThis(),
+          action: jest.fn((fn) => {
+            if (name === commandName) capturedAction = fn;
+            return cmd;
+          }),
+        };
+
+        return cmd;
+      }),
+    };
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+    return capturedAction;
+  };
+
+  it('calls generateEventDocs once when not versioned', async () => {
+    const action = await getActionForCommand('generate-schema-docs');
+    await action();
+    expect(generateEventDocs).toHaveBeenCalledTimes(1);
+  });
+
+  it('calls generateEventDocs for each version plus current when versioned', async () => {
+    fs.existsSync.mockReturnValue(true);
+    fs.readFileSync.mockReturnValue(JSON.stringify(['1.0']));
+
+    const action = await getActionForCommand('generate-schema-docs');
+    await action();
+
+    expect(fs.readFileSync).toHaveBeenCalledWith('/site/versions.json', 'utf8');
+    expect(generateEventDocs).toHaveBeenCalledTimes(2);
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: '1.0' }),
+    );
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: 'current' }),
+    );
+  });
+});
+
+describe('extendCli - update-schema-ids', () => {
+  const getAction = async () => {
+    let captured = null;
+    const cli = {
+      command: jest.fn((name) => {
+        const cmd = {
+          description: jest.fn().mockReturnThis(),
+          option: jest.fn().mockReturnThis(),
+          action: jest.fn((fn) => {
+            if (name === 'update-schema-ids [version]') captured = fn;
+            return cmd;
+          }),
+        };
+        return cmd;
+      }),
+    };
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+    return captured;
+  };
+
+  it('calls updateSchemaIds with siteDir, url, and version', async () => {
+    const action = await getAction();
+    action('1.0.0');
+    expect(updateSchemaIds).toHaveBeenCalledWith(
+      '/site',
+      'https://example.com',
+      '1.0.0',
+    );
+  });
+});
+
+describe('extendCli - sync-gtm', () => {
+  const getAction = async () => {
+    let captured = null;
+    const cli = {
+      command: jest.fn((name) => {
+        const cmd = {
+          description: jest.fn().mockReturnThis(),
+          option: jest.fn().mockReturnThis(),
+          action: jest.fn((fn) => {
+            if (name === 'sync-gtm') captured = fn;
+            return cmd;
+          }),
+        };
+        return cmd;
+      }),
+    };
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+    return captured;
+  };
+
+  it('runs the sync-gtm script with the default path', async () => {
+    const action = await getAction();
+    action({ path: '/site' });
+    const cmd = execSync.mock.calls[0][0];
+    expect(cmd).toContain('scripts/sync-gtm.js');
+    expect(cmd).toContain('--path=/site');
+    expect(execSync).toHaveBeenCalledWith(cmd, {
+      cwd: '/site',
+      stdio: 'inherit',
+    });
+  });
+
+  it('joins multiple args with spaces', async () => {
+    const action = await getAction();
+    action({ path: '/site', json: true, quiet: true });
+    const cmd = execSync.mock.calls[0][0];
+    expect(cmd).toContain('--path=/site --json --quiet');
+  });
+
+  it('appends --json flag when json option is set', async () => {
+    const action = await getAction();
+    action({ path: '/site', json: true });
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('--json'),
+      expect.any(Object),
+    );
+  });
+
+  it('appends --quiet flag when quiet option is set', async () => {
+    const action = await getAction();
+    action({ path: '/site', quiet: true });
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('--quiet'),
+      expect.any(Object),
+    );
+  });
+
+  it('appends --skip-array-sub-properties flag when option is set', async () => {
+    const action = await getAction();
+    action({ path: '/site', skipArraySubProperties: true });
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('--skip-array-sub-properties'),
+      expect.any(Object),
+    );
+  });
+
+  it('does not append optional flags when options are falsy', async () => {
+    const action = await getAction();
+    action({ path: '/site' });
+    const cmd = execSync.mock.calls[0][0];
+    expect(cmd).not.toContain('--json');
+    expect(cmd).not.toContain('--quiet');
+    expect(cmd).not.toContain('--skip-array-sub-properties');
+  });
+});
+
+describe('extendCli - version-with-schemas', () => {
+  const getAction = async () => {
+    let captured = null;
+    const cli = {
+      command: jest.fn((name) => {
+        const cmd = {
+          description: jest.fn().mockReturnThis(),
+          option: jest.fn().mockReturnThis(),
+          action: jest.fn((fn) => {
+            if (name === 'version-with-schemas <version>') captured = fn;
+            return cmd;
+          }),
+        };
+        return cmd;
+      }),
+    };
+    const plugin = await createPlugin(makeContext(), makeOptions());
+    plugin.extendCli(cli);
+    return captured;
+  };
+
+  beforeEach(() => {
+    jest.spyOn(console, 'log').mockImplementation(() => {});
+    jest.spyOn(console, 'error').mockImplementation(() => {});
+    // versions.json absent (not versioned); nextSchemasDir present
+    fs.existsSync.mockImplementation((p) => !p.includes('versions.json'));
+  });
+
+  it('creates version, copies schemas, updates IDs and generates docs on success', async () => {
+    const action = await getAction();
+    await action('1.2.0');
+
+    expect(execSync).toHaveBeenCalledWith(
+      expect.stringContaining('docs:version 1.2.0'),
+      { cwd: '/site', stdio: 'inherit' },
+    );
+    expect(fs.cpSync).toHaveBeenCalledWith(
+      '/site/static/schemas/next',
+      '/site/static/schemas/1.2.0',
+      { recursive: true },
+    );
+    expect(updateSchemaIds).toHaveBeenCalledWith(
+      '/site',
+      'https://example.com',
+      '1.2.0',
+    );
+    expect(generateEventDocs).toHaveBeenCalledWith(
+      expect.objectContaining({ version: '1.2.0' }),
+    );
+  });
+
+  it('exits with code 1 when docusaurus docs:version fails', async () => {
+    execSync.mockImplementation(() => {
+      throw new Error('cmd failed');
+    });
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {});
+
+    const action = await getAction();
+    await action('1.2.0');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+
+  it('exits with code 1 when next schemas directory does not exist', async () => {
+    execSync.mockImplementation(() => {});
+    fs.existsSync.mockReturnValue(false); // nextSchemasDir also missing
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {});
+
+    const action = await getAction();
+    await action('1.2.0');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+
+  it('exits with code 1 when schema copy fails', async () => {
+    execSync.mockImplementation(() => {});
+    fs.cpSync.mockImplementation(() => {
+      throw new Error('copy failed');
+    });
+    const exitSpy = jest.spyOn(process, 'exit').mockImplementation(() => {});
+
+    const action = await getAction();
+    await action('1.2.0');
+
+    expect(exitSpy).toHaveBeenCalledWith(1);
+    exitSpy.mockRestore();
+  });
+});

package/__tests__/syncGtm.test.js

@@ -1,6 +1,6 @@
 /* eslint-env jest */
 /**
- * @jest-environment node
+ * @jest-environment @stryker-mutator/jest-runner/jest-env/node
  */
 const fs = require('fs');
 const path = require('path');
@@ -168,6 +168,31 @@ describe('getVariablesFromSchemas', () => {
       screen_name: { type: 'string', description: 'Screen name.' },
     },
   };
+  const mobileConditionalSchema = {
+    title: 'Mobile Conditional Event',
+    'x-tracking-targets': ['android-firebase-kotlin-sdk'],
+    type: 'object',
+    allOf: [
+      {
+        if: {
+          properties: {
+            mobile_platform_hint: { const: 'ios' },
+          },
+          required: ['mobile_platform_hint'],
+        },
+        then: {
+          required: ['att_status'],
+        },
+        else: {
+          required: ['ad_personalization_enabled'],
+        },
+      },
+    ],
+    properties: {
+      event: { type: 'string', const: 'screen_view' },
+      mobile_platform_hint: { type: 'string' },
+    },
+  };
   const untaggedEventSchema = {
     title: 'Untagged Event',
     type: 'object',
@@ -309,6 +334,52 @@ describe('getVariablesFromSchemas', () => {
     );
   });
 
+  it('should skip non-web schemas before mergeAllOf can fail on unsupported keywords', async () => {
+    const mobileConditionalPath = path.join(
+      SCHEMA_PATH,
+      'mobile-conditional-event.json',
+    );
+    mockFiles[SCHEMA_PATH].push('mobile-conditional-event.json');
+    mockFileContents[mobileConditionalPath] = JSON.stringify(
+      mobileConditionalSchema,
+    );
+
+    const bundledWebSchema = JSON.parse(JSON.stringify(complexEventSchema));
+    bundledWebSchema.properties.user_data.properties.addresses.items =
+      addressSchema;
+    const loggerErrorSpy = jest
+      .spyOn(console, 'error')
+      .mockImplementation(() => {});
+
+    RefParser.bundle.mockImplementation(async (filePath) => {
+      if (filePath.endsWith('complex-event.json')) {
+        return bundledWebSchema;
+      }
+      if (filePath.endsWith('mobile-event.json')) {
+        return mobileEventSchema;
+      }
+      if (filePath.endsWith('mobile-conditional-event.json')) {
+        return mobileConditionalSchema;
+      }
+      if (filePath.endsWith('address.json')) {
+        return addressSchema;
+      }
+      throw new Error(`Unexpected schema file: ${filePath}`);
+    });
+
+    const result = await gtmScript.getVariablesFromSchemas(SCHEMA_PATH, {});
+
+    expect(result.map((variable) => variable.name)).not.toContain(
+      'mobile_platform_hint',
+    );
+    expect(loggerErrorSpy).not.toHaveBeenCalledWith(
+      expect.stringContaining(
+        `Error processing schema ${mobileConditionalPath}`,
+      ),
+      expect.any(Error),
+    );
+  });
+
   it('should include root tracking schemas based on content instead of path names', async () => {
     const nestedSchemaDir = path.join(SCHEMA_PATH, 'event-components-demo');
     const nestedSchemaPath = path.join(nestedSchemaDir, 'checkout-event.json');
@@ -494,18 +565,61 @@ describe('GTM Synchronization Logic', () => {
   });
 
   describe('deleteGtmVariables', () => {
-    it('should call execSync to delete variables and return their names', () => {
+    it('should delete variables and return their names', () => {
       const toDelete = gtmScript.getVariablesToDelete(
         schemaVariables,
         gtmVariables,
       );
-      const deleted = gtmScript.deleteGtmVariables(toDelete);
+      const { deleted, failedDeletes } = gtmScript.deleteGtmVariables(toDelete);
       expect(execSync).toHaveBeenCalledTimes(1);
       expect(execSync).toHaveBeenCalledWith(
         'gtm variables delete --variable-id 123 --force --quiet',
         { stdio: 'inherit' },
       );
       expect(deleted).toEqual(['old_variable']);
+      expect(failedDeletes).toEqual([]);
+    });
+
+    it('should capture failed deletes when GTM rejects the deletion', () => {
+      execSync.mockImplementation(() => {
+        throw new Error('Returned an error response for your request.');
+      });
+
+      const toDelete = gtmScript.getVariablesToDelete(
+        schemaVariables,
+        gtmVariables,
+      );
+      const { deleted, failedDeletes } = gtmScript.deleteGtmVariables(toDelete);
+
+      expect(deleted).toEqual([]);
+      expect(failedDeletes).toEqual([
+        { name: 'old_variable', variableId: '123' },
+      ]);
+    });
+  });
+
+  describe('syncGtmVariables', () => {
+    it('should report failed deletes when GTM rejects a deletion', async () => {
+      const syncedSchemaVariables = [
+        { name: 'event', description: 'The event name.' },
+      ];
+
+      execSync.mockImplementation((command) => {
+        if (command === 'gtm variables list -o json --quiet') {
+          return Buffer.from(JSON.stringify(gtmVariables));
+        }
+        if (command.startsWith('gtm variables delete')) {
+          throw new Error('Returned an error response for your request.');
+        }
+        throw new Error(`Unexpected command: ${command}`);
+      });
+
+      const summary = await gtmScript.syncGtmVariables(syncedSchemaVariables);
+
+      expect(summary.deleted).toEqual([]);
+      expect(summary.failedDeletes).toEqual([
+        { name: 'old_variable', variableId: '123' },
+      ]);
     });
   });
 });
@@ -525,6 +639,12 @@ describe('main function', () => {
       syncGtmVariables: jest.fn().mockResolvedValue({
         created: ['var1'],
         deleted: ['var2'],
+        failedDeletes: [
+          {
+            name: 'legacy_field',
+            variableId: '88',
+          },
+        ],
         inSync: ['var3'],
       }),
       getVariablesFromSchemas: jest
@@ -558,6 +678,12 @@ describe('main function', () => {
       workspace: { workspaceName: 'test-workspace', workspaceId: '123' },
       created: ['var1'],
       deleted: ['var2'],
+      failedDeletes: [
+        {
+          name: 'legacy_field',
+          variableId: '88',
+        },
+      ],
       inSync: ['var3'],
     });
   });
@@ -567,4 +693,14 @@ describe('main function', () => {
     await gtmScript.main(argv, mockDeps);
     expect(mockDeps.getLatestSchemaPath).toHaveBeenCalledWith('./my-demo');
   });
+
+  it('should report failed deletions in human-readable output', async () => {
+    const argv = ['node', 'script.js'];
+    await gtmScript.main(argv, mockDeps);
+
+    expect(logSpy).toHaveBeenCalledWith(
+      'Skipped deleting 1 GTM variables (GTM rejected the delete, they may still be referenced):',
+    );
+    expect(logSpy).toHaveBeenCalledWith('- legacy_field (ID: 88)');
+  });
 });