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

package/__tests__/helpers/schemaToTableData.test.js

@@ -0,0 +1,222 @@
+import { schemaToTableData } from '../../helpers/schemaToTableData';
+import choiceEventSchema from '../__fixtures__/static/schemas/choice-event.json';
+import rootAnyOfEventSchema from '../__fixtures__/static/schemas/root-any-of-event.json';
+
+describe('schemaToTableData', () => {
+  it('handles "oneOf" and "anyOf" correctly for a complex schema', () => {
+    const tableData = schemaToTableData(choiceEventSchema);
+
+    // Expect 3 top-level items: event property, user_id choice, payment_method property
+    const topLevelRows = tableData.filter((row) => row.level === 0);
+    expect(topLevelRows).toHaveLength(3);
+
+    // 1. Test 'event' property
+    const eventProp = tableData.find(
+      (row) =>
+        row.type === 'property' && row.name === 'event' && row.level === 0,
+    );
+    expect(eventProp).toBeDefined();
+    expect(eventProp.propertyType).toBe('string');
+    expect(eventProp.required).toBe(true);
+
+    // 2. Test 'user_id' property (oneOf)
+    const userIdChoice = tableData.find(
+      (row) =>
+        row.type === 'choice' &&
+        row.path.length === 1 &&
+        row.path[0] === 'user_id',
+    );
+    expect(userIdChoice).toBeDefined();
+    expect(userIdChoice.level).toBe(0);
+    expect(userIdChoice.choiceType).toBe('oneOf');
+    expect(userIdChoice.options).toHaveLength(2);
+    expect(userIdChoice.description).toBe("The user's ID.");
+
+    // Check the options for user_id
+    const userIdOption1 = userIdChoice.options[0];
+    expect(userIdOption1.title).toBe('User ID as String');
+    expect(userIdOption1.rows).toHaveLength(1);
+    const userIdOption1Prop = userIdOption1.rows[0];
+    expect(userIdOption1Prop.type).toBe('property');
+    expect(userIdOption1Prop.name).toBe('user_id');
+    expect(userIdOption1Prop.level).toBe(0);
+    expect(userIdOption1Prop.required).toBe(true);
+
+    const userIdOption2 = userIdChoice.options[1];
+    expect(userIdOption2.title).toBe('User ID as Integer');
+    const userIdOption2Prop = userIdOption2.rows[0];
+    expect(userIdOption2Prop.name).toBe('user_id');
+    expect(userIdOption2Prop.level).toBe(0);
+    expect(userIdOption2Prop.required).toBe(true);
+
+    // 3. Test 'payment_method' property (anyOf)
+    const paymentMethodProp = tableData.find(
+      (row) => row.name === 'payment_method' && row.level === 0,
+    );
+    expect(paymentMethodProp).toBeDefined();
+    expect(paymentMethodProp.type).toBe('property');
+    expect(paymentMethodProp.propertyType).toBe('object');
+    expect(paymentMethodProp.required).toBe(true);
+
+    const paymentMethodChoice = tableData.find(
+      (row) =>
+        row.type === 'choice' &&
+        row.path.length === 2 &&
+        row.path[0] === 'payment_method' &&
+        row.path[1] === 'anyOf',
+    );
+    expect(paymentMethodChoice).toBeDefined();
+    expect(paymentMethodChoice.level).toBe(1); // Should be nested
+    expect(paymentMethodChoice.choiceType).toBe('anyOf');
+    expect(paymentMethodChoice.options).toHaveLength(2);
+
+    // Check the options for payment_method
+    const paymentOption1 = paymentMethodChoice.options[0]; // Credit Card
+    expect(paymentOption1.title).toBe('Credit Card');
+    expect(paymentOption1.rows.length).toBe(3);
+    const cardPaymentType = paymentOption1.rows.find(
+      (r) => r.name === 'payment_type',
+    );
+    expect(cardPaymentType).toBeDefined();
+    expect(cardPaymentType.level).toBe(1);
+    expect(cardPaymentType.path).toEqual(['payment_type']);
+
+    const paymentOption2 = paymentMethodChoice.options[1]; // PayPal
+    expect(paymentOption2.title).toBe('PayPal');
+    expect(paymentOption2.rows.length).toBe(2);
+    const payPalEmail = paymentOption2.rows.find((r) => r.name === 'email');
+    expect(payPalEmail).toBeDefined();
+    expect(payPalEmail.level).toBe(1);
+    expect(payPalEmail.path).toEqual(['email']);
+  });
+
+  it('handles schemas with both properties and oneOf', () => {
+    const schema = {
+      properties: {
+        common_prop: { type: 'string' },
+      },
+      oneOf: [
+        {
+          title: 'Option A',
+          properties: { prop_a: { type: 'string' } },
+        },
+      ],
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    // It should contain one property row and one choice row.
+    expect(tableData).toHaveLength(2);
+
+    const propRow = tableData.find((row) => row.type === 'property');
+    const choiceRow = tableData.find((row) => row.type === 'choice');
+
+    expect(propRow).toBeDefined();
+    expect(propRow.name).toBe('common_prop');
+
+    expect(choiceRow).toBeDefined();
+    expect(choiceRow.choiceType).toBe('oneOf');
+  });
+
+  it('correctly processes the "examples" array', () => {
+    const schema = {
+      properties: {
+        prop_with_examples: {
+          type: 'string',
+          examples: ['first-example', 'second-example'],
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    expect(tableData).toHaveLength(1);
+    const propRow = tableData[0];
+
+    expect(propRow.name).toBe('prop_with_examples');
+    expect(propRow.example).toEqual(['first-example', 'second-example']);
+  });
+
+  it('handles singular "example" if "examples" is not present', () => {
+    const schema = {
+      properties: {
+        prop_with_example: {
+          type: 'string',
+          example: 'singular-example',
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+    expect(tableData[0].example).toBe('singular-example');
+  });
+
+  it('handles "oneOf" nested inside a property', () => {
+    const schema = {
+      properties: {
+        user_id: {
+          description: "The user's ID.",
+          oneOf: [
+            { title: 'User ID as String', type: 'string' },
+            { title: 'User ID as Integer', type: 'integer' },
+          ],
+        },
+      },
+    };
+
+    const tableData = schemaToTableData(schema);
+
+    // Expect a single 'choice' row that correctly represents the property.
+    expect(tableData).toHaveLength(1);
+
+    const choiceRow = tableData[0];
+    expect(choiceRow.type).toBe('choice');
+    expect(choiceRow.level).toBe(0);
+    expect(choiceRow.path).toEqual(['user_id']);
+    expect(choiceRow.options).toHaveLength(2);
+    expect(choiceRow.description).toBe("The user's ID.");
+
+    // Check that the options' rows are generated correctly
+    const firstOptionRows = choiceRow.options[0].rows;
+    expect(firstOptionRows).toHaveLength(1);
+    expect(firstOptionRows[0].type).toBe('property');
+    expect(firstOptionRows[0].name).toBe('user_id');
+    expect(firstOptionRows[0].propertyType).toBe('string');
+  });
+
+  it('handles "anyOf" at the root level correctly', () => {
+    const tableData = schemaToTableData(rootAnyOfEventSchema);
+
+    const topLevelRows = tableData.filter((row) => row.level === 0);
+    // event property + the choice itself
+    expect(topLevelRows).toHaveLength(2);
+
+    // Test 'event' property
+    const eventProp = tableData.find(
+      (row) =>
+        row.type === 'property' && row.name === 'event' && row.level === 0,
+    );
+    expect(eventProp).toBeDefined();
+
+    const rootChoice = tableData.find(
+      (row) => row.type === 'choice' && row.level === 0,
+    );
+    expect(rootChoice).toBeDefined();
+    expect(rootChoice.choiceType).toBe('anyOf');
+    expect(rootChoice.options).toHaveLength(2);
+
+    const optionC = rootChoice.options.find((o) => o.title === 'Has Param C');
+    expect(optionC).toBeDefined();
+    expect(optionC.rows).toHaveLength(1);
+    const paramC = optionC.rows[0];
+    expect(paramC.name).toBe('param_c');
+    expect(paramC.level).toBe(0); // This is the core of the test
+
+    const optionD = rootChoice.options.find((o) => o.title === 'Has Param D');
+    expect(optionD).toBeDefined();
+    expect(optionD.rows).toHaveLength(1);
+    const paramD = optionD.rows[0];
+    expect(paramD.name).toBe('param_d');
+    expect(paramD.level).toBe(0); // This is the core of the test
+  });
+});

package/__tests__/helpers/update-schema-ids.test.js

@@ -0,0 +1,107 @@
+import { vol } from 'memfs';
+import updateSchemaIds from '../../helpers/update-schema-ids';
+
+// Mock the file system
+jest.mock('fs', () => require('memfs').vol);
+
+describe('updateSchemaIds', () => {
+  const siteDir = '/test-site';
+  const url = 'https://example.com';
+
+  beforeEach(() => {
+    vol.reset();
+  });
+
+  it('should recursively update schema IDs for all versions', () => {
+    // Create a mock file system
+    const versions = ['1.0.0', '2.0.0'];
+    const schemaFiles = {
+      'versions.json': JSON.stringify(versions),
+      'static/schemas/1.0.0/main.json': JSON.stringify({ title: 'Main 1.0.0' }),
+      'static/schemas/1.0.0/components/comp.json': JSON.stringify({
+        title: 'Comp 1.0.0',
+      }),
+      'static/schemas/2.0.0/main.json': JSON.stringify({ title: 'Main 2.0.0' }),
+      'static/schemas/2.0.0/components/comp.json': JSON.stringify({
+        title: 'Comp 2.0.0',
+      }),
+    };
+    vol.fromJSON(schemaFiles, siteDir);
+
+    // Run the function
+    updateSchemaIds(siteDir, url);
+
+    // Check if the IDs were updated
+    const schema1 = JSON.parse(
+      vol.readFileSync(`${siteDir}/static/schemas/1.0.0/main.json`, 'utf-8'),
+    );
+    expect(schema1.$id).toBe('https://example.com/schemas/1.0.0/main.json');
+
+    const schema2 = JSON.parse(
+      vol.readFileSync(
+        `${siteDir}/static/schemas/1.0.0/components/comp.json`,
+        'utf-8',
+      ),
+    );
+    expect(schema2.$id).toBe(
+      'https://example.com/schemas/1.0.0/components/comp.json',
+    );
+
+    const schema3 = JSON.parse(
+      vol.readFileSync(`${siteDir}/static/schemas/2.0.0/main.json`, 'utf-8'),
+    );
+    expect(schema3.$id).toBe('https://example.com/schemas/2.0.0/main.json');
+
+    const schema4 = JSON.parse(
+      vol.readFileSync(
+        `${siteDir}/static/schemas/2.0.0/components/comp.json`,
+        'utf-8',
+      ),
+    );
+    expect(schema4.$id).toBe(
+      'https://example.com/schemas/2.0.0/components/comp.json',
+    );
+  });
+
+  it('should update schema IDs for a single version', () => {
+    // Create a mock file system
+    const versions = ['1.0.0', '2.0.0'];
+    const schemaFiles = {
+      'versions.json': JSON.stringify(versions),
+      'static/schemas/1.0.0/main.json': JSON.stringify({ title: 'Main 1.0.0' }),
+      'static/schemas/2.0.0/main.json': JSON.stringify({ title: 'Main 2.0.0' }),
+    };
+    vol.fromJSON(schemaFiles, siteDir);
+
+    // Run the function for a single version
+    updateSchemaIds(siteDir, url, '1.0.0');
+
+    // Check if only the specified version was updated
+    const schema1 = JSON.parse(
+      vol.readFileSync(`${siteDir}/static/schemas/1.0.0/main.json`, 'utf-8'),
+    );
+    expect(schema1.$id).toBe('https://example.com/schemas/1.0.0/main.json');
+
+    const schema2 = JSON.parse(
+      vol.readFileSync(`${siteDir}/static/schemas/2.0.0/main.json`, 'utf-8'),
+    );
+    expect(schema2.$id).toBeUndefined();
+  });
+
+  it('should not do anything if versions.json does not exist', () => {
+    // Create a mock file system without versions.json
+    const schemaFiles = {
+      'static/schemas/1.0.0/main.json': JSON.stringify({ title: 'Main 1.0.0' }),
+    };
+    vol.fromJSON(schemaFiles, siteDir);
+
+    // Run the function
+    updateSchemaIds(siteDir, url);
+
+    // Check that no files were modified
+    const schema1 = JSON.parse(
+      vol.readFileSync(`${siteDir}/static/schemas/1.0.0/main.json`, 'utf-8'),
+    );
+    expect(schema1.$id).toBeUndefined();
+  });
+});

package/__tests__/update-schema-ids.test.js

@@ -0,0 +1,39 @@
+/**
+ * @jest-environment node
+ */
+
+import fs from 'fs';
+import path from 'path';
+import updateSchemaIds from '../helpers/update-schema-ids';
+
+describe('updateSchemaIds', () => {
+  const siteDir = path.resolve(__dirname, '__fixtures_versioned__');
+  const url = 'https://tracking-docs-demo.buchert.digital/';
+
+  // Create a temporary copy of the fixtures so we don't modify the originals
+  const tempSiteDir = path.resolve(__dirname, '__temp_fixtures_versioned__');
+
+  beforeEach(() => {
+    fs.cpSync(siteDir, tempSiteDir, { recursive: true });
+  });
+
+  afterEach(() => {
+    fs.rmSync(tempSiteDir, { recursive: true });
+  });
+
+  it('should update the $id of the schemas in the versioned directories', () => {
+    updateSchemaIds(tempSiteDir, url);
+
+    const schemaPath = path.join(
+      tempSiteDir,
+      'static/schemas',
+      '1.1.1',
+      'add-to-cart-event.json',
+    );
+    const schema = JSON.parse(fs.readFileSync(schemaPath, 'utf8'));
+
+    expect(schema.$id).toBe(
+      'https://tracking-docs-demo.buchert.digital/schemas/1.1.1/add-to-cart-event.json',
+    );
+  });
+});

package/__tests__/validateSchemas.test.js

@@ -8,93 +8,130 @@ import os from 'os';
 import validateSchemas from '../validateSchemas';
 
 describe('validateSchemas', () => {
-    let tmpDir;
-    let consoleErrorSpy;
-    let consoleLogSpy;
-
-    beforeEach(() => {
-        tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-test-'));
-        consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => { });
-        consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => { });
-    });
-
-    afterEach(() => {
-        fs.rmSync(tmpDir, { recursive: true, force: true });
-        jest.restoreAllMocks();
-    });
-
-    const writeSchema = (dir, fileName, content) => {
-        const filePath = path.join(dir, fileName);
-        fs.mkdirSync(path.dirname(filePath), { recursive: true });
-        fs.writeFileSync(filePath, JSON.stringify(content, null, 2));
+  let tmpDir;
+  let consoleErrorSpy;
+  let consoleLogSpy;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'schema-test-'));
+    consoleErrorSpy = jest.spyOn(console, 'error').mockImplementation(() => {});
+    consoleLogSpy = jest.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+    jest.restoreAllMocks();
+  });
+
+  const writeSchema = (dir, fileName, content) => {
+    const filePath = path.join(dir, fileName);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(content, null, 2));
+  };
+
+  const loadFixture = (fixtureName) => {
+    const fixturePath = path.resolve(
+      __dirname,
+      '__fixtures__',
+      'validateSchemas',
+      fixtureName,
+    );
+    const schemaContent = fs.readFileSync(fixturePath, 'utf8');
+    return JSON.parse(schemaContent);
+  };
+
+  it('should return true when all schemas are valid', async () => {
+    const validSchema = loadFixture('valid-schema.json');
+    writeSchema(tmpDir, 'valid-schema.json', validSchema);
+
+    const result = await validateSchemas(tmpDir);
+    expect(result).toBe(true);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'OK Schema valid-schema.json produced a valid example.',
+    );
+  });
+
+  it('should return false if an example fails validation', async () => {
+    const invalidExampleSchema = loadFixture('invalid-example-schema.json');
+    writeSchema(tmpDir, 'invalid-example-schema.json', invalidExampleSchema);
+
+    const result = await validateSchemas(tmpDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      'x Schema invalid-example-schema.json example data failed validation:',
+    );
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      expect.arrayContaining([
+        expect.objectContaining({
+          instancePath: '/age',
+          keyword: 'type',
+          message: 'must be number',
+        }),
+      ]),
+    );
+  });
+
+  it('should fail validation for missing required property', async () => {
+    const noValidExampleSchema = loadFixture('no-example-schema.json');
+    writeSchema(tmpDir, 'no-valid-example-schema.json', noValidExampleSchema);
+
+    const result = await validateSchemas(tmpDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalledWith(
+      'x Schema no-valid-example-schema.json does not produce a valid example.',
+    );
+  });
+
+  it('should handle schemas with $refs correctly', async () => {
+    const componentSchema = loadFixture(
+      path.join('components', 'referenced.json'),
+    );
+    const mainSchema = loadFixture('main-schema-with-ref.json');
+
+    writeSchema(
+      path.join(tmpDir, 'components'),
+      'referenced.json',
+      componentSchema,
+    );
+    writeSchema(tmpDir, 'main-schema-with-ref.json', mainSchema);
+
+    const result = await validateSchemas(tmpDir);
+    expect(result).toBe(true);
+    expect(consoleLogSpy).toHaveBeenCalledWith(
+      'OK Schema main-schema-with-ref.json produced a valid example.',
+    );
+  });
+
+  it('should reject if a referenced schema is missing', async () => {
+    const mainSchema = loadFixture('main-schema-with-missing-ref.json');
+    writeSchema(tmpDir, 'main-schema-with-missing-ref.json', mainSchema);
+
+    const expectedErrorPath = path.join(tmpDir, 'non-existent-component.json');
+    await expect(validateSchemas(tmpDir)).rejects.toThrow(
+      expect.objectContaining({
+        message: expect.stringContaining(
+          `Error opening file ${expectedErrorPath}`,
+        ),
+      }),
+    );
+  });
+
+  it('should throw an error if duplicate schema IDs are found', async () => {
+    const schemaA = {
+      $id: 'duplicate-id',
+      type: 'object',
+      properties: { a: { type: 'string' } },
     };
-
-    const loadFixture = (fixtureName) => {
-        const fixturePath = path.resolve(__dirname, '__fixtures__', 'validateSchemas', fixtureName);
-        const schemaContent = fs.readFileSync(fixturePath, 'utf8');
-        return JSON.parse(schemaContent);
+    const schemaB = {
+      $id: 'duplicate-id',
+      type: 'object',
+      properties: { b: { type: 'string' } },
     };
-
-    it('should return true when all schemas are valid', async () => {
-        const validSchema = loadFixture('valid-schema.json');
-        writeSchema(tmpDir, 'valid-schema.json', validSchema);
-
-        const result = await validateSchemas(tmpDir);
-        expect(result).toBe(true);
-        expect(consoleLogSpy).toHaveBeenCalledWith('✅ Schema valid-schema.json produced a valid example.');
-    });
-
-    it('should return false if an example fails validation', async () => {
-        const invalidExampleSchema = loadFixture('invalid-example-schema.json');
-        writeSchema(tmpDir, 'invalid-example-schema.json', invalidExampleSchema);
-
-        const result = await validateSchemas(tmpDir);
-        expect(result).toBe(false);
-        expect(consoleErrorSpy).toHaveBeenCalledWith('❌ Schema invalid-example-schema.json example data failed validation:');
-        expect(consoleErrorSpy).toHaveBeenCalledWith(expect.arrayContaining([
-            expect.objectContaining({
-                instancePath: '/age',
-                keyword: 'type',
-                message: 'must be number'
-            })
-        ]));
-    });
-
-    it('should fail validation for missing required property', async () => {
-        const noValidExampleSchema = loadFixture('no-example-schema.json');
-        writeSchema(tmpDir, 'no-valid-example-schema.json', noValidExampleSchema);
-
-        const result = await validateSchemas(tmpDir);
-        expect(result).toBe(false);
-        expect(consoleErrorSpy).toHaveBeenCalledWith('❌ Schema no-valid-example-schema.json example data failed validation:');
-        expect(consoleErrorSpy).toHaveBeenCalledWith(expect.arrayContaining([
-            expect.objectContaining({
-                keyword: 'required',
-                params: { missingProperty: 'some_prop' },
-            })
-        ]));
-    });
-
-    it('should handle schemas with $refs correctly', async () => {
-        const componentSchema = loadFixture(path.join('components', 'referenced.json'));
-        const mainSchema = loadFixture('main-schema-with-ref.json');
-
-        writeSchema(path.join(tmpDir, 'components'), 'referenced.json', componentSchema);
-        writeSchema(tmpDir, 'main-schema-with-ref.json', mainSchema);
-
-        const result = await validateSchemas(tmpDir);
-        expect(result).toBe(true);
-        expect(consoleLogSpy).toHaveBeenCalledWith('✅ Schema main-schema-with-ref.json produced a valid example.');
-    });
-
-    it('should reject if a referenced schema is missing', async () => {
-        const mainSchema = loadFixture('main-schema-with-missing-ref.json');
-        writeSchema(tmpDir, 'main-schema-with-missing-ref.json', mainSchema);
-
-        const expectedErrorPath = path.join(tmpDir, 'non-existent-component.json');
-        await expect(validateSchemas(tmpDir)).rejects.toThrow(expect.objectContaining({
-            message: expect.stringContaining(`Error opening file ${expectedErrorPath}`)
-        }));
-    });
-
-});
+    writeSchema(path.join(tmpDir, 'A'), 'schema-A.json', schemaA);
+    writeSchema(path.join(tmpDir, 'B'), 'schema-B.json', schemaB);
+
+    await expect(validateSchemas(tmpDir)).rejects.toThrow(
+      'schema with key or id "duplicate-id" already exists',
+    );
+  });
+});