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

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,14 @@
+/**
+ * @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/processSchema.test.js

@@ -0,0 +1,36 @@
+/**
+ * @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('#');
+    });
+});

package/__tests__/validateSchemas.test.js

@@ -0,0 +1,100 @@
+/**
+ * @jest-environment node
+ */
+
+import path from 'path';
+import fs from 'fs';
+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));
+    };
+
+    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('✅ 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}`)
+        }));
+    });
+
+});

package/components/ExampleDataLayer.js

@@ -4,7 +4,7 @@ import buildExampleFromSchema from '../helpers/buildExampleFromSchema';
 
 export default function ExampleDataLayer({ schema }) {
     // 1. Identify properties that need to be reset (cleared) first
-    const propertiesToReset = findComplexPropertiesToReset(schema || {});
+    const clearableProperties = findClearableProperties(schema || {});
 
     // 2. Build the main example data
     const example = buildExampleFromSchema(schema || {});
@@ -12,11 +12,14 @@ export default function ExampleDataLayer({ schema }) {
     // 3. Construct the code snippet
     let codeSnippet = '';
 
+    // Filter properties to reset to only those present in the example
+    const propertiesToClear = clearableProperties.filter(prop => prop in example);
+
     // If there are properties to reset, push them as null first
-    if (propertiesToReset.length > 0)
+    if (propertiesToClear.length > 0)
     {
         const resetObject = {};
-        propertiesToReset.forEach(prop => {
+        propertiesToClear.forEach(prop => {
             resetObject[prop] = null;
         });
         codeSnippet += `window.dataLayer.push(${JSON.stringify(resetObject, null, 2)});\n`;
@@ -28,11 +31,10 @@ export default function ExampleDataLayer({ schema }) {
     return <CodeBlock language="javascript">{codeSnippet}</CodeBlock>
 };
 
-const findComplexPropertiesToReset = (schema) => {
+export const findClearableProperties = (schema) => {
     if (!schema || !schema.properties) return [];
 
     return Object.entries(schema.properties)
         .filter(([key, definition]) => definition["x-gtm-clear"] === true)
         .map(([key]) => key);
 }
-

package/components/PropertiesTable.js

@@ -1,19 +1,14 @@
+import React from 'react';
 import SchemaRows from './SchemaRows';
+import TableHeader from './TableHeader';
+import { getConstraints } from '../helpers/getConstraints';
 
 export default function PropertiesTable({ schema }) {
 
     return <table>
-        <thead>
-            <tr>
-                <th width="20%">Property</th>
-                <th width="15%">Type</th>
-                <th width="10%">Req</th>
-                <th with="15%">Examples</th>
-                <th>Description</th>
-            </tr>
-        </thead>
+        <TableHeader />
         <tbody>
-            <SchemaRows properties={schema.properties} requiredList={schema.required} />
+            <SchemaRows properties={schema.properties} requiredList={schema.required} getConstraints={getConstraints} />
         </tbody>
     </table>
 }

package/components/PropertyRow.js

@@ -0,0 +1,74 @@
+import React from 'react';
+import clsx from 'clsx';
+
+// Helper to format the property type
+const getPropertyType = (type) => {
+    return Array.isArray(type) ? type.join(' | ') : type;
+};
+
+// Helper to format examples
+const formatExamples = (examples) => {
+    if (!examples)
+    {
+        return '';
+    }
+    return examples
+        .map((example) =>
+            typeof example === 'object' ? JSON.stringify(example) : example
+        )
+        .join(', ');
+};
+
+const PropertyRow = ({ propertyKey, prop, requiredList, getConstraints }) => {
+    const isReq = requiredList.includes(propertyKey);
+    const constraints = getConstraints(prop, isReq);
+
+    const childProperties = prop.properties || (prop.items && prop.items.properties);
+    const hasChildren = childProperties && Object.keys(childProperties).length > 0;
+
+    const isObject = prop.type === 'object';
+    const isArrayOfObjects = prop.type === 'array' && prop.items && prop.items.type === 'object';
+
+    if ((isObject || isArrayOfObjects) && !hasChildren)
+    {
+        return null;
+    }
+
+    const numRows = Math.max(1, constraints.length);
+    const [firstConstraint, ...remainingConstraints] = constraints;
+
+    return (
+        <React.Fragment>
+            <tr className={clsx(isReq && 'required-row')}>
+                <td rowSpan={numRows}>
+                    <strong>{propertyKey}</strong>
+                    {hasChildren && <span style={{ fontSize: '0.8em', marginLeft: '5px' }}>⤵</span>}
+                </td>
+                <td rowSpan={numRows}><code>{getPropertyType(prop.type)}</code></td>
+                <td>
+                    {firstConstraint && (
+                        <code className={clsx('constraint-code', firstConstraint === 'required' && 'required')}>
+                            {firstConstraint}
+                        </code>
+                    )}
+                </td>
+                <td rowSpan={numRows}>
+                    {formatExamples(prop.examples)}
+                </td>
+                <td rowSpan={numRows}>{prop.description || ''}</td>
+            </tr>
+
+            {remainingConstraints.map((constraint, index) => (
+                <tr className={clsx(isReq && 'required-row')} key={`${propertyKey}-constraint-${index}`}>
+                    <td>
+                        <code className={clsx('constraint-code', constraint === 'required' && 'required')}>
+                            {constraint}
+                        </code>
+                    </td>
+                </tr>
+            ))}
+        </React.Fragment>
+    );
+};
+
+export default PropertyRow;

package/components/SchemaJsonViewer.js

@@ -1,10 +1,11 @@
+import React from 'react';
 import CodeBlock from '@theme/CodeBlock';
 
 export default function SchemaJsonViewer({ schema }) {
 
     return (
-        <details>
+        <details className="schema-json-viewer">
             <summary>View Raw JSON Schema</summary>
             <CodeBlock language="json">{JSON.stringify(schema, null, 2)}</CodeBlock>
         </details>);
-}
+}

package/components/SchemaRows.css

@@ -0,0 +1,28 @@
+.required-row {
+    background-color: rgba(255, 0, 0, 0.05);
+}
+
+.constraint-code {
+    white-space: pre-wrap;
+    margin-right: 4px;
+    display: inline-block;
+    margin-bottom: 4px;
+}
+
+.constraint-code.required {
+    font-weight: bold;
+    color: #c7254e;
+    /* A reddish color */
+    background-color: #f9f2f4;
+    padding: 2px 4px;
+    border-radius: 4px;
+}
+
+.nested-table-container {
+    padding-left: 20px;
+    border-left: 4px solid #eee;
+}
+
+.schema-json-viewer {
+    margin-bottom: 1em;
+}

package/components/SchemaRows.js

@@ -1,71 +1,43 @@
 import React from 'react';
+import './SchemaRows.css';
+import PropertyRow from './PropertyRow';
+import TableHeader from './TableHeader';
 
-const SchemaRows = ({ properties, requiredList = [], level = 0 }) => {
+const SchemaRows = ({ properties, requiredList = [], level = 0, getConstraints }) => {
     return (
         <>
             {Object.entries(properties).map(([key, prop]) => {
-                const isReq = requiredList.includes(key);
-
-                // 1. Calculate if it has children (Same as before)
-                const hasChildren =
-                    (prop.type === 'object' &&
-                        prop.properties &&
-                        Object.keys(prop.properties).length > 0) ||
-                    (prop.type === 'array' &&
-                        prop.items &&
-                        prop.items.properties &&
-                        Object.keys(prop.items.properties).length > 0);
-
-                const isObject = prop.type === 'object';
-                const isArrayOfObjects = prop.type === 'array' && prop.items && prop.items.type === 'object';
-
-                if ((isObject || isArrayOfObjects) && !hasChildren)
-                {
-                    return null;
-                }
+                const childProperties = prop.properties || (prop.items && prop.items.properties);
+                const hasChildren = childProperties && Object.keys(childProperties).length > 0;
 
                 return (
                     <React.Fragment key={key}>
-                        {/* Main property row */}
-                        <tr style={{ backgroundColor: isReq ? 'rgba(255,0,0,0.05)' : 'transparent' }}>
-                            <td>
-                                <strong>{key}</strong>
-                                {hasChildren && <span style={{ fontSize: '0.8em', marginLeft: '5px' }}>⤵</span>}
-                            </td>
-                            <td><code>{Array.isArray(prop.type) ? prop.type.join('|') : prop.type}</code></td>
-                            <td style={{ textAlign: 'center' }}>{isReq ? '✅' : ''}</td>
-                            <td>{prop.examples ? prop.examples.join(', ') : ''}</td>
-                            <td>{prop.description || ''}</td>
-                        </tr>
-
-                        {/* Nested children rendered immediately after parent */}
+                        <PropertyRow
+                            propertyKey={key}
+                            prop={prop}
+                            requiredList={requiredList}
+                            level={level}
+                            getConstraints={getConstraints}
+                        />
                         {hasChildren && (
-                            <tr>
-                                <td colSpan="5" style={{ paddingLeft: '20px', borderLeft: '4px solid #eee' }}>
+                            <tr key={`${key}-nested`}>
+                                <td colSpan="5" className="nested-table-container">
                                     <strong>{prop.type === 'array' ? `${key} [ ]` : `${key} { }`}</strong>
                                     <table style={{ width: '100%', marginTop: '5px' }}>
-                                        <thead>
-                                            <tr>
-                                                <th width="20%">Property</th>
-                                                <th width="15%">Type</th>
-                                                <th width="10%">Req</th>
-                                                <th width="15%">Examples</th>
-                                                <th>Description</th>
-                                            </tr>
-                                        </thead>
+                                        <TableHeader />
                                         <tbody>
                                             <SchemaRows
                                                 properties={prop.type === 'object' ? prop.properties : prop.items.properties}
                                                 requiredList={prop.type === 'object' ? prop.required || [] : prop.items.required || []}
                                                 level={level + 1}
+                                                getConstraints={getConstraints}
                                             />
                                         </tbody>
                                     </table>
                                 </td>
                             </tr>
-                        )
-                        }
-                    </React.Fragment >
+                        )}
+                    </React.Fragment>
                 );
             })}
         </>

package/components/SchemaViewer.js

@@ -1,3 +1,5 @@
+import React from 'react';
+import Heading from '@theme/Heading';
 import ExampleDataLayer from './ExampleDataLayer';
 import PropertiesTable from './PropertiesTable';
 
@@ -9,10 +11,10 @@ export default function SchemaViewer({ schema }) {
 
     return (
         <div>
-            <h2>DataLayer Example</h2>
+            <Heading as="h2">DataLayer Example</Heading>
             <ExampleDataLayer schema={schema} />
 
-            <h2>Event Properties</h2>
+            <Heading as="h2">Event Properties</Heading>
             <PropertiesTable schema={schema} />
         </div>
     );

package/components/TableHeader.js

@@ -0,0 +1,15 @@
+import React from 'react';
+
+export default function TableHeader() {
+    return (
+        <thead>
+            <tr>
+                <th width="20%">Property</th>
+                <th width="15%">Type</th>
+                <th width="25%">Constraints</th>
+                <th width="15%">Examples</th>
+                <th>Description</th>
+            </tr>
+        </thead>
+    );
+}

package/generateEventDocs.js

@@ -1,12 +1,16 @@
-import $RefParser from "@apidevtools/json-schema-ref-parser";
-import mergeJsonSchema from "json-schema-merge-allof";
 import fs from 'fs';
 import path from 'path';
+import loadSchema from './helpers/loadSchema';
+import processSchema from './helpers/processSchema';
+import MdxTemplate from './helpers/mdx-template.js';
 
-export default async function generateEventDocs() {
+export default async function generateEventDocs(options) {
+    const { organizationName, projectName, siteDir } = options || {};
+    const baseEditUrl = `https://github.com/${organizationName}/${projectName}/edit/main`;
     // CONFIGURATION
-    const SCHEMA_DIR = 'schemas'; // Where your JSON files are
-    const OUTPUT_DIR = 'docs/events'; // Where MDX goes
+    const SCHEMA_DIR = path.join(siteDir, 'static/schemas'); // Where your JSON files are
+    const OUTPUT_DIR = path.join(siteDir, 'docs/events'); // Where MDX goes
+    const PARTIALS_DIR = path.join(siteDir, 'docs/partials'); // Where your partials are
 
     // Ensure output dir exists
     if (!fs.existsSync(OUTPUT_DIR))
@@ -22,41 +26,38 @@ export default async function generateEventDocs() {
     for (const file of files)
     {
         const filePath = path.join(SCHEMA_DIR, file);
-        const rawContent = fs.readFileSync(filePath, 'utf-8');
-        const schema = JSON.parse(rawContent);
+        const schema = loadSchema(filePath);
+        const mergedSchema = await processSchema(filePath);
+        const eventName = file.replace('.json', '');
 
-        // First, dereference all $ref properties
-        const clonedSchema = await $RefParser.dereference(filePath, {
-            mutateInputSchema: false, dereference: {
-                circular: 'ignore'
-            }
-        });
-
-        // Then merge allOf properties
-        const mergedSchema = mergeJsonSchema(clonedSchema, {
-            resolvers: {
-                defaultResolver: mergeJsonSchema.options.resolvers.title
-            }
-        });
+        // Check for partials
+        const topPartialPath = path.join(PARTIALS_DIR, `${eventName}.mdx`);
+        const bottomPartialPath = path.join(PARTIALS_DIR, `${eventName}_bottom.mdx`);
 
-        // Define the MDX Content
-        // We embed the JSON directly into the file to avoid Webpack import issues
-        const mdxContent = `---
-title: ${schema.title}
-description: ${schema.description}
-sidebar_label: ${schema.title}
----
+        let topPartialImport = '';
+        let topPartialComponent = '';
+        if (fs.existsSync(topPartialPath)) {
+            topPartialImport = `import TopPartial from '@site/docs/partials/${eventName}.mdx';`;
+            topPartialComponent = '<TopPartial />';
+        }
 
-import SchemaViewer from '@theme/SchemaViewer';
-import SchemaJsonViewer from '@theme/SchemaJsonViewer';
+        let bottomPartialImport = '';
+        let bottomPartialComponent = '';
+        if (fs.existsSync(bottomPartialPath)) {
+            bottomPartialImport = `import BottomPartial from '@site/docs/partials/${eventName}_bottom.mdx';`;
+            bottomPartialComponent = '<BottomPartial />';
+        }
 
-# ${schema.title}
-
-${schema.description}
-
-<SchemaViewer schema={${JSON.stringify(mergedSchema)}} />
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
-`;
+        const mdxContent = MdxTemplate({
+            schema,
+            mergedSchema,
+            baseEditUrl,
+            file,
+            topPartialImport,
+            bottomPartialImport,
+            topPartialComponent,
+            bottomPartialComponent
+        });
 
         // Write the .mdx file
         const outputFilename = file.replace('.json', '.mdx');

package/helpers/buildExampleFromSchema.js

@@ -28,7 +28,7 @@ const buildExampleFromSchema = (schema) => {
                 return obj;
             }
             // Object with no properties defined
-            return {};
+            return undefined;
         }
 
         if (type === 'array')
@@ -43,7 +43,7 @@ const buildExampleFromSchema = (schema) => {
                 }
             }
             // Empty array or array of undefined items
-            return [];
+            return undefined;
         }
 
         switch (type)
@@ -80,4 +80,4 @@ const buildExampleFromSchema = (schema) => {
 
     return {};
 }
-export default buildExampleFromSchema;
+export default buildExampleFromSchema;