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

package/__tests__/generateEventDocs.nested.test.js

@@ -0,0 +1,80 @@
+/**
+ * @jest-environment node
+ */
+
+import generateEventDocs from '../generateEventDocs';
+import fs from 'fs';
+import path from 'path';
+
+jest.mock('fs', () => {
+  const memfs = require('memfs');
+  return memfs;
+});
+
+describe('generateEventDocs (nested oneOf)', () => {
+  const testSiteDir = path.resolve(__dirname, '__fixtures_nested__');
+  const options = {
+    organizationName: 'test-org',
+    projectName: 'test-project',
+    siteDir: testSiteDir,
+    url: 'https://tracking-docs-demo.buchert.digital',
+  };
+  const baseOutputDir = path.join(options.siteDir, 'docs');
+
+  beforeEach(() => {
+    fs.vol.reset();
+    const realFs = jest.requireActual('fs');
+    const nestedSchemasDir = path.resolve(
+      __dirname,
+      '__fixtures__/static/schemas/nested',
+    );
+    const targetSchemasDir = path.join(testSiteDir, 'static/schemas');
+    fs.vol.mkdirSync(targetSchemasDir, { recursive: true });
+
+    const files = realFs.readdirSync(nestedSchemasDir, { withFileTypes: true });
+    for (const file of files) {
+      const filePath = path.join(nestedSchemasDir, file.name);
+      const content = realFs.readFileSync(filePath);
+      fs.vol.writeFileSync(path.join(targetSchemasDir, file.name), content);
+    }
+  });
+
+  it('should generate nested documentation correctly', async () => {
+    console.log = jest.fn(); // suppress console.log
+
+    await generateEventDocs(options);
+
+    const parentDir = path.join(baseOutputDir, 'parent-event');
+    // The child directory is prefixed because it's an item in the parent's oneOf
+    const childDir = path.join(parentDir, '01-child-event');
+
+    // Check for directory structure
+    expect(fs.existsSync(parentDir)).toBe(true);
+    expect(fs.existsSync(childDir)).toBe(true);
+
+    const parentIndex = fs.readFileSync(
+      path.join(parentDir, 'index.mdx'),
+      'utf-8',
+    );
+    expect(parentIndex).toMatchSnapshot();
+
+    const childIndex = fs.readFileSync(
+      path.join(childDir, 'index.mdx'),
+      'utf-8',
+    );
+    expect(childIndex).toMatchSnapshot();
+
+    // Check content of generated files
+    const grandchildA = fs.readFileSync(
+      path.join(childDir, '01-grandchild-a.mdx'),
+      'utf-8',
+    );
+    expect(grandchildA).toMatchSnapshot();
+
+    const grandchildB = fs.readFileSync(
+      path.join(childDir, '02-grandchild-b.mdx'),
+      'utf-8',
+    );
+    expect(grandchildB).toMatchSnapshot();
+  });
+});

package/__tests__/generateEventDocs.test.js

@@ -0,0 +1,90 @@
+/**
+ * @jest-environment node
+ */
+
+import generateEventDocs from '../generateEventDocs';
+import fs from 'fs';
+import path from 'path';
+
+jest.mock('fs', () => {
+  const memfs = require('memfs');
+  return memfs;
+});
+
+describe('generateEventDocs (non-versioned)', () => {
+  const options = {
+    organizationName: 'test-org',
+    projectName: 'test-project',
+    // Use the fixtures directory as the siteDir for tests
+    siteDir: path.resolve(__dirname, '__fixtures__'),
+    url: 'https://tracking-docs-demo.buchert.digital',
+  };
+  const outputDir = path.join(options.siteDir, 'docs');
+
+  beforeEach(() => {
+    fs.vol.reset();
+    const realFs = jest.requireActual('fs');
+    const fixturesDir = path.resolve(__dirname, '__fixtures__');
+
+    function readDirRecursive(dir) {
+      const files = realFs.readdirSync(dir, { withFileTypes: true });
+      for (const file of files) {
+        const filePath = path.join(dir, file.name);
+        if (file.isDirectory()) {
+          fs.vol.mkdirSync(filePath, { recursive: true });
+          readDirRecursive(filePath);
+        } else {
+          const content = realFs.readFileSync(filePath);
+          fs.vol.writeFileSync(filePath, content);
+        }
+      }
+    }
+    readDirRecursive(fixturesDir);
+  });
+
+  it('should generate documentation correctly', async () => {
+    console.log = jest.fn(); // suppress console.log
+
+    await generateEventDocs(options);
+
+    const choiceEventDir = path.join(outputDir, 'root-choice-event');
+    expect(fs.existsSync(choiceEventDir)).toBe(true);
+
+    // Check content of generated files
+    const addToCart = fs.readFileSync(
+      path.join(outputDir, 'add-to-cart-event.mdx'),
+      'utf-8',
+    );
+    expect(addToCart).toMatchSnapshot();
+
+    const choiceEvent = fs.readFileSync(
+      path.join(outputDir, 'choice-event.mdx'),
+      'utf-8',
+    );
+    expect(choiceEvent).toMatchSnapshot();
+
+    const rootAnyOf = fs.readFileSync(
+      path.join(outputDir, 'root-any-of-event.mdx'),
+      'utf-8',
+    );
+    expect(rootAnyOf).toMatchSnapshot();
+
+    const rootChoiceIndex = fs.readFileSync(
+      path.join(choiceEventDir, 'index.mdx'),
+      'utf-8',
+    );
+    expect(rootChoiceIndex).toMatchSnapshot();
+
+    const rootChoiceA = fs.readFileSync(
+      path.join(choiceEventDir, '01-option-a.mdx'),
+      'utf-8',
+    );
+    expect(rootChoiceA).toMatchSnapshot();
+
+    const rootChoiceB = fs.readFileSync(
+      path.join(choiceEventDir, '02-option-b.mdx'),
+      'utf-8',
+    );
+    expect(rootChoiceB).toMatchSnapshot();
+  });
+});

package/__tests__/generateEventDocs.versioned.test.js

@@ -0,0 +1,69 @@
+/**
+ * @jest-environment node
+ */
+
+import generateEventDocs from '../generateEventDocs';
+import fs from 'fs';
+import path from 'path';
+
+jest.mock('fs', () => {
+  const originalFs = jest.requireActual('fs');
+  return {
+    ...originalFs,
+    writeFileSync: jest.fn(),
+    mkdirSync: jest.fn(),
+    existsSync: jest.fn(),
+    readdirSync: originalFs.readdirSync,
+    readFileSync: originalFs.readFileSync,
+  };
+});
+
+describe('generateEventDocs (versioned)', () => {
+  const options = {
+    organizationName: 'test-org',
+    projectName: 'test-project',
+    url: 'https://tracking-docs-demo.buchert.digital/',
+    // Use the fixtures_versioned directory as the siteDir for tests
+    siteDir: path.resolve(__dirname, '__fixtures_versioned__'),
+  };
+  const partialsDir = path.join(options.siteDir, 'docs/partials');
+
+  beforeEach(() => {
+    // Clear all instances and calls to constructor and all methods:
+    fs.writeFileSync.mockClear();
+    fs.mkdirSync.mockClear();
+    fs.existsSync.mockClear();
+  });
+
+  it('should generate documentation for "current" version', async () => {
+    // Mock fs.writeFileSync to capture the output
+    fs.writeFileSync = jest.fn();
+
+    const currentOptions = { ...options, version: 'current' };
+    await generateEventDocs(currentOptions);
+
+    expect(fs.writeFileSync).toHaveBeenCalled();
+    const [filePath, content] = fs.writeFileSync.mock.calls[0];
+    const outputDir = path.join(options.siteDir, 'docs');
+    expect(filePath).toBe(path.join(outputDir, 'add-to-cart-event.mdx'));
+    expect(content).toMatchSnapshot();
+  });
+
+  it('should generate documentation for a specific version', async () => {
+    // Mock fs.writeFileSync to capture the output
+    fs.writeFileSync = jest.fn();
+
+    const versionedOptions = { ...options, version: '1.1.1' };
+    await generateEventDocs(versionedOptions);
+
+    expect(fs.writeFileSync).toHaveBeenCalled();
+    const [filePath, content] = fs.writeFileSync.mock.calls[0];
+    const outputDir = path.join(
+      options.siteDir,
+      'versioned_docs',
+      'version-1.1.1',
+    );
+    expect(filePath).toBe(path.join(outputDir, 'add-to-cart-event.mdx'));
+    expect(content).toMatchSnapshot();
+  });
+});

package/__tests__/helpers/buildExampleFromSchema.test.js

@@ -0,0 +1,188 @@
+import buildExampleFromSchema from '../../helpers/buildExampleFromSchema.js';
+
+describe('buildExampleFromSchema', () => {
+  it('should build a basic example from a schema', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string' },
+        age: { type: 'integer' },
+        isStudent: { type: 'boolean' },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+
+    expect(example).toEqual({
+      name: '',
+      age: 0,
+      isStudent: false,
+    });
+  });
+
+  it('should handle nested objects and arrays', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        user: {
+          type: 'object',
+          properties: {
+            name: { type: 'string' },
+          },
+        },
+        posts: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              title: { type: 'string' },
+              tags: {
+                type: 'array',
+                items: { type: 'string' },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+
+    expect(example).toEqual({
+      user: {
+        name: '',
+      },
+      posts: [
+        {
+          title: '',
+          tags: [''],
+        },
+      ],
+    });
+  });
+
+  it('should use examples, const, and default values', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: {
+          type: 'string',
+          examples: ['John Doe'],
+        },
+        role: {
+          type: 'string',
+          const: 'admin',
+        },
+        level: {
+          type: 'integer',
+          default: 1,
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+
+    expect(example).toEqual({
+      name: 'John Doe',
+      role: 'admin',
+      level: 1,
+    });
+  });
+
+  it('should build a complex example', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: {
+          type: 'string',
+          examples: ['purchase'],
+        },
+        ecommerce: {
+          type: 'object',
+          properties: {
+            transaction_id: {
+              type: 'string',
+              examples: ['T_12345'],
+            },
+            value: {
+              type: 'number',
+              default: 10.0,
+            },
+            items: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  item_id: { type: 'string', examples: ['SKU_123'] },
+                  item_name: { type: 'string', examples: ['Stan Smith Shoes'] },
+                  price: { type: 'number' },
+                  quantity: { type: 'integer', default: 1 },
+                },
+              },
+            },
+          },
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+
+    expect(example).toEqual({
+      event: 'purchase',
+      ecommerce: {
+        transaction_id: 'T_12345',
+        value: 10.0,
+        items: [
+          {
+            item_id: 'SKU_123',
+            item_name: 'Stan Smith Shoes',
+            price: 0,
+            quantity: 1,
+          },
+        ],
+      },
+    });
+  });
+  it('should not include empty objects for properties with no defined value', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test_event'] },
+        user_data: {
+          type: 'object',
+        },
+        ecommerce: {
+          type: 'object',
+          properties: {
+            items: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  item_id: { type: 'string', examples: ['SKU_123'] },
+                },
+              },
+            },
+          },
+        },
+        empty_object: {
+          type: 'object',
+          properties: {},
+        },
+      },
+    };
+
+    const example = buildExampleFromSchema(schema);
+
+    expect(example).toEqual({
+      event: 'test_event',
+      ecommerce: {
+        items: [
+          {
+            item_id: 'SKU_123',
+          },
+        ],
+      },
+    });
+  });
+});

package/__tests__/helpers/file-system.test.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import path from 'path';
+import { readSchemas, writeDoc, createDir } from '../../helpers/file-system';
+
+jest.mock('fs', () => {
+  const memfs = require('memfs');
+  return memfs;
+});
+
+describe('file-system helpers', () => {
+  beforeEach(() => {
+    fs.vol.reset();
+    fs.vol.fromJSON({
+      '/schemas/schema1.json': '{}',
+      '/schemas/schema2.json': '{}',
+      '/schemas/not-a-schema.txt': 'hello',
+    });
+  });
+
+  describe('readSchemas', () => {
+    it('should read all json files from a directory', () => {
+      const schemas = readSchemas('/schemas');
+      expect(schemas).toHaveLength(2);
+      expect(schemas[0].fileName).toBe('schema1.json');
+      expect(schemas[1].fileName).toBe('schema2.json');
+    });
+  });
+
+  describe('writeDoc', () => {
+    it('should write a file to the specified directory', () => {
+      fs.mkdirSync('/output', { recursive: true });
+      writeDoc('/output', 'doc1.mdx', 'content');
+      const content = fs.readFileSync('/output/doc1.mdx', 'utf-8');
+      expect(content).toBe('content');
+    });
+  });
+
+  describe('createDir', () => {
+    it('should create a directory if it does not exist', () => {
+      createDir('/new-dir');
+      expect(fs.existsSync('/new-dir')).toBe(true);
+    });
+  });
+});

package/__tests__/helpers/getConstraints.test.js

@@ -0,0 +1,58 @@
+import { getConstraints } from '../../helpers/getConstraints';
+
+describe('getConstraints', () => {
+  it('should return "required" if isReq is true', () => {
+    const constraints = getConstraints({}, true);
+    expect(constraints).toContain('required');
+  });
+
+  it('should handle simple key-value constraints', () => {
+    const prop = {
+      minLength: 1,
+      maxLength: 10,
+      minimum: 0,
+      maximum: 100,
+      minItems: 1,
+      maxItems: 5,
+    };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toEqual([
+      'minLength: 1',
+      'maxLength: 10',
+      'minimum: 0',
+      'maximum: 100',
+      'minItems: 1',
+      'maxItems: 5',
+    ]);
+  });
+
+  it('should handle pattern constraint', () => {
+    const prop = { pattern: '^[a-z]+$' };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toContain('pattern: /^[a-z]+$/');
+  });
+
+  it('should handle uniqueItems constraint', () => {
+    const prop = { uniqueItems: true };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toContain('uniqueItems: true');
+  });
+
+  it('should handle additionalProperties constraint', () => {
+    const prop = { additionalProperties: false };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toContain('additionalProperties: false');
+  });
+
+  it('should handle enum constraint', () => {
+    const prop = { enum: ['a', 'b', 'c'] };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toContain('enum: [a, b, c]');
+  });
+
+  it('should handle const constraint', () => {
+    const prop = { const: 'a' };
+    const constraints = getConstraints(prop, false);
+    expect(constraints).toContain('const: "a"');
+  });
+});

package/__tests__/helpers/loadSchema.test.js

@@ -0,0 +1,20 @@
+/**
+ * @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/__tests__/helpers/path-helpers.test.js

@@ -0,0 +1,34 @@
+import { getPathsForVersion } from '../../helpers/path-helpers';
+import path from 'path';
+
+describe('getPathsForVersion', () => {
+  const siteDir = '/test/site';
+
+  it('should return paths for a specific version', () => {
+    const version = '1.0.0';
+    const { schemaDir, outputDir } = getPathsForVersion(version, siteDir);
+    expect(schemaDir).toBe(path.join(siteDir, 'static/schemas', version));
+    expect(outputDir).toBe(
+      path.join(siteDir, 'versioned_docs', `version-${version}`),
+    );
+  });
+
+  it('should return paths for the "current" version', () => {
+    const version = 'current';
+    const { schemaDir, outputDir } = getPathsForVersion(version, siteDir);
+    expect(schemaDir).toBe(path.join(siteDir, 'static/schemas', 'next'));
+    expect(outputDir).toBe(path.join(siteDir, 'docs'));
+  });
+
+  it('should return paths for a non-versioned site', () => {
+    const { schemaDir, outputDir } = getPathsForVersion(null, siteDir);
+    expect(schemaDir).toBe(path.join(siteDir, 'static/schemas'));
+    expect(outputDir).toBe(path.join(siteDir, 'docs'));
+  });
+
+  it('should handle undefined version', () => {
+    const { schemaDir, outputDir } = getPathsForVersion(undefined, siteDir);
+    expect(schemaDir).toBe(path.join(siteDir, 'static/schemas'));
+    expect(outputDir).toBe(path.join(siteDir, 'docs'));
+  });
+});

package/__tests__/helpers/processSchema.test.js

@@ -0,0 +1,56 @@
+/**
+ * @jest-environment node
+ */
+
+import path from 'path';
+import processSchema from '../../helpers/processSchema';
+
+describe('processSchema', () => {
+  it('should bundle refs and return a merged schema', async () => {
+    const filePath = path.join(
+      __dirname,
+      '..',
+      '__fixtures__',
+      'validateSchemas',
+      'main-schema-with-ref.json',
+    );
+    const mergedSchema = await processSchema(filePath);
+
+    expect(mergedSchema.title).toBe('Main Schema with Ref');
+    expect(mergedSchema.properties.component.$ref).toBeUndefined();
+    expect(mergedSchema.properties.component.type).toBe('object');
+    expect(mergedSchema.properties.component.properties.prop.type).toBe(
+      'string',
+    );
+  });
+
+  it('should handle circular references correctly', async () => {
+    const filePath = path.join(
+      __dirname,
+      '..',
+      '__fixtures__',
+      'validateSchemas',
+      'circular-schema.json',
+    );
+    const mergedSchema = await processSchema(filePath);
+
+    expect(mergedSchema.title).toBe('Circular Schema');
+    expect(mergedSchema.properties.parent.$ref).toBe('#');
+  });
+
+  it('should handle multi-file circular references and produce a self-contained schema', async () => {
+    const filePath = path.join(
+      __dirname,
+      '..',
+      '__fixtures__',
+      'validateSchemas',
+      'schema-A.json',
+    );
+    const mergedSchema = await processSchema(filePath);
+
+    expect(mergedSchema.title).toBe('Schema A');
+    expect(mergedSchema.properties.b.$ref).toBeUndefined();
+    expect(mergedSchema.properties.b.title).toBe('Schema B');
+    expect(mergedSchema.properties.b.properties.a.$ref).toBe('#');
+  });
+});