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

package/generateEventDocs.js

@@ -1,7 +1,12 @@
 import path from 'path';
 import fs from 'fs';
 import { getPathsForVersion } from './helpers/path-helpers.js';
-import { readSchemas, writeDoc, createDir } from './helpers/file-system.js';
+import {
+  readSchemas,
+  readSchemaSources,
+  writeDoc,
+  createDir,
+} from './helpers/file-system.js';
 import { processOneOfSchema, slugify } from './helpers/schema-processing.js';
 import SchemaDocTemplate from './helpers/schema-doc-template.js';
 import ChoiceIndexTemplate from './helpers/choice-index-template.js';
@@ -12,15 +17,129 @@ function buildEditUrl(organizationName, projectName, siteDir, filePath) {
   return `${baseEditUrl}/${path.relative(path.join(siteDir, '..'), filePath)}`;
 }
 
-function resolvePartial(partialPath, relativePartialsDir, componentPrefix) {
-  if (!fs.existsSync(partialPath)) return { import: '', component: '' };
-  const fileName = path.basename(partialPath);
+function toSiteImportPath(siteDir, absolutePath) {
+  return `@site/${path.relative(siteDir, absolutePath).split(path.sep).join('/')}`;
+}
+
+function resolvePartial({
+  scopedPartialPath,
+  fallbackPartialPath,
+  componentPrefix,
+  siteDir,
+  allowFallback,
+}) {
+  const selectedPartialPath = fs.existsSync(scopedPartialPath)
+    ? scopedPartialPath
+    : allowFallback && fs.existsSync(fallbackPartialPath)
+      ? fallbackPartialPath
+      : null;
+
+  if (!selectedPartialPath) return { import: '', component: '' };
+  const fileImportPath = toSiteImportPath(siteDir, selectedPartialPath);
   return {
-    import: `import ${componentPrefix} from '@site/${relativePartialsDir}/${fileName}';`,
+    import: `import ${componentPrefix} from '${fileImportPath}';`,
     component: `<${componentPrefix} />`,
   };
 }
 
+function isPlainObject(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function toSchemaSourceKey(schemaDir, filePath) {
+  return path.relative(schemaDir, filePath).split(path.sep).join('/');
+}
+
+function resolveLocalSchemaRef(currentPath, ref) {
+  if (!ref || ref.startsWith('#') || /^[a-zA-Z][a-zA-Z\d+\-.]*:/.test(ref)) {
+    return null;
+  }
+
+  const [fileRef] = ref.split('#');
+  return path
+    .normalize(path.join(path.dirname(currentPath), fileRef))
+    .split(path.sep)
+    .join('/');
+}
+
+function collectReachableSchemaSources(sourcePath, allSchemaSources) {
+  if (!sourcePath || !allSchemaSources[sourcePath]) return {};
+
+  const visited = new Set();
+  const reachableSources = {};
+
+  function walkSchema(currentPath) {
+    if (visited.has(currentPath) || !allSchemaSources[currentPath]) return;
+    visited.add(currentPath);
+
+    const schema = allSchemaSources[currentPath];
+    reachableSources[currentPath] = schema;
+
+    function walkNode(node) {
+      if (Array.isArray(node)) {
+        node.forEach(walkNode);
+        return;
+      }
+
+      if (!isPlainObject(node)) return;
+
+      if (typeof node.$ref === 'string') {
+        const resolvedRefPath = resolveLocalSchemaRef(currentPath, node.$ref);
+        if (resolvedRefPath) {
+          walkSchema(resolvedRefPath);
+        }
+      }
+
+      Object.values(node).forEach(walkNode);
+    }
+
+    walkNode(schema);
+  }
+
+  walkSchema(sourcePath);
+  return reachableSources;
+}
+
+async function collectLeafEventNames(schema, filePath, eventNames) {
+  if (!schema.oneOf) {
+    eventNames.push(path.basename(filePath, '.json'));
+    return;
+  }
+
+  const processed = await processOneOfSchema(schema, filePath);
+  for (const { slug, schema: processedSchema, sourceFilePath } of processed) {
+    if (processedSchema.oneOf) {
+      await collectLeafEventNames(
+        processedSchema,
+        sourceFilePath || filePath,
+        eventNames,
+      );
+      continue;
+    }
+    eventNames.push(slug);
+  }
+}
+
+async function getPartialNameConflicts(schemas) {
+  const eventNames = [];
+
+  for (const { fileName, filePath, schema } of schemas) {
+    if (schema.oneOf) {
+      await collectLeafEventNames(schema, filePath, eventNames);
+      continue;
+    }
+    eventNames.push(fileName.replace('.json', ''));
+  }
+
+  const counts = new Map();
+  eventNames.forEach((name) => counts.set(name, (counts.get(name) || 0) + 1));
+  return new Set(
+    [...counts.entries()]
+      .filter(([, count]) => count > 1)
+      .map(([name]) => name),
+  );
+}
+
 async function generateAndWriteDoc(
   filePath,
   schema,
@@ -29,27 +148,39 @@ async function generateAndWriteDoc(
   options,
   alreadyMergedSchema = null,
   editFilePath = null,
+  partialNameConflicts = new Set(),
+  schemaSources = {},
+  schemaDir,
 ) {
   const { organizationName, projectName, siteDir, dataLayerName, version } =
     options;
 
   const { outputDir: versionOutputDir } = getPathsForVersion(version, siteDir);
   const PARTIALS_DIR = path.join(versionOutputDir, 'partials');
-  const relativePartialsDir = path.relative(siteDir, PARTIALS_DIR);
+  const docRelativeDir = path.relative(versionOutputDir, outputDir);
+  const scopedPartialsDir =
+    !docRelativeDir || docRelativeDir === '.'
+      ? PARTIALS_DIR
+      : path.join(PARTIALS_DIR, docRelativeDir);
+  const allowBasenameFallback = !partialNameConflicts.has(eventName);
 
   const mergedSchema = alreadyMergedSchema || (await processSchema(filePath));
 
-  // Check for partials
-  const top = resolvePartial(
-    path.join(PARTIALS_DIR, `_${eventName}.mdx`),
-    relativePartialsDir,
-    'TopPartial',
-  );
-  const bottom = resolvePartial(
-    path.join(PARTIALS_DIR, `_${eventName}_bottom.mdx`),
-    relativePartialsDir,
-    'BottomPartial',
-  );
+  // Resolve scoped partials first; basename fallback is disabled for ambiguous names.
+  const top = resolvePartial({
+    scopedPartialPath: path.join(scopedPartialsDir, `_${eventName}.mdx`),
+    fallbackPartialPath: path.join(PARTIALS_DIR, `_${eventName}.mdx`),
+    componentPrefix: 'TopPartial',
+    siteDir,
+    allowFallback: allowBasenameFallback,
+  });
+  const bottom = resolvePartial({
+    scopedPartialPath: path.join(scopedPartialsDir, `_${eventName}_bottom.mdx`),
+    fallbackPartialPath: path.join(PARTIALS_DIR, `_${eventName}_bottom.mdx`),
+    componentPrefix: 'BottomPartial',
+    siteDir,
+    allowFallback: allowBasenameFallback,
+  });
 
   const editUrl = buildEditUrl(
     organizationName,
@@ -68,6 +199,11 @@ async function generateAndWriteDoc(
     topPartialComponent: top.component,
     bottomPartialComponent: bottom.component,
     dataLayerName,
+    sourcePath: toSchemaSourceKey(schemaDir, editFilePath || filePath),
+    schemaSources: collectReachableSchemaSources(
+      toSchemaSourceKey(schemaDir, editFilePath || filePath),
+      schemaSources,
+    ),
   });
 
   const outputFilename = path.basename(filePath).replace('.json', '.mdx');
@@ -80,6 +216,9 @@ async function generateOneOfDocs(
   filePath,
   outputDir,
   options,
+  partialNameConflicts,
+  schemaSources,
+  schemaDir,
 ) {
   const { organizationName, projectName, siteDir } = options;
   const editUrl = buildEditUrl(
@@ -98,6 +237,11 @@ async function generateOneOfDocs(
     schema,
     processedOptions: processed,
     editUrl,
+    sourcePath: toSchemaSourceKey(schemaDir, filePath),
+    schemaSources: collectReachableSchemaSources(
+      toSchemaSourceKey(schemaDir, filePath),
+      schemaSources,
+    ),
   });
   writeDoc(eventOutputDir, 'index.mdx', indexPageContent);
 
@@ -115,6 +259,9 @@ async function generateOneOfDocs(
         sourceFilePath || filePath,
         eventOutputDir,
         options,
+        partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     } else {
       await generateAndWriteDoc(
@@ -125,6 +272,9 @@ async function generateOneOfDocs(
         options,
         processedSchema,
         sourceFilePath || filePath,
+        partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     }
   }
@@ -136,6 +286,8 @@ export default async function generateEventDocs(options) {
 
   createDir(outputDir);
   const schemas = readSchemas(schemaDir);
+  const schemaSources = readSchemaSources(schemaDir);
+  const partialNameConflicts = await getPartialNameConflicts(schemas);
 
   console.log(`🚀 Generating documentation for ${schemas.length} schemas...`);
 
@@ -152,7 +304,16 @@ export default async function generateEventDocs(options) {
     }
 
     if (schema.oneOf) {
-      await generateOneOfDocs(eventName, schema, filePath, outputDir, options);
+      await generateOneOfDocs(
+        eventName,
+        schema,
+        filePath,
+        outputDir,
+        options,
+        partialNameConflicts,
+        schemaSources,
+        schemaDir,
+      );
     } else {
       await generateAndWriteDoc(
         filePath,
@@ -160,6 +321,11 @@ export default async function generateEventDocs(options) {
         eventName,
         outputDir,
         options,
+        null,
+        null,
+        partialNameConflicts,
+        schemaSources,
+        schemaDir,
       );
     }
   }

package/helpers/buildExampleFromSchema.js

@@ -1,5 +1,5 @@
 import { getSingleExampleValue } from './example-helper';
-import mergeJsonSchema from 'json-schema-merge-allof';
+import { mergeSchema } from './mergeSchema.js';
 
 const getPrimitivePlaceholder = (type) => {
   switch (type) {
@@ -26,7 +26,7 @@ const buildExampleFromSchema = (schema) => {
     const newSchema = { ...schema };
     const choice = newSchema[choiceType][0];
     delete newSchema[choiceType];
-    const merged = mergeJsonSchema({ allOf: [newSchema, choice] });
+    const merged = mergeSchema({ allOf: [newSchema, choice] });
     return buildExampleFromSchema(merged);
   }
 
@@ -37,7 +37,7 @@ const buildExampleFromSchema = (schema) => {
     delete newSchema.if;
     delete newSchema.then;
     delete newSchema.else;
-    const merged = mergeJsonSchema({ allOf: [newSchema, thenBranch] });
+    const merged = mergeSchema({ allOf: [newSchema, thenBranch] });
     return buildExampleFromSchema(merged);
   }
 

package/helpers/choice-index-template.js

@@ -1,5 +1,5 @@
 export default function ChoiceIndexTemplate(data) {
-  const { schema, processedOptions, editUrl } = data;
+  const { schema, processedOptions, editUrl, sourcePath, schemaSources } = data;
 
   return `---
 title: ${schema.title}
@@ -18,6 +18,10 @@ ${processedOptions
   .map((option) => `- [${option.schema.title}](./${option.slug})`)
   .join('\n')}
 
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+<SchemaJsonViewer
+  schema={${JSON.stringify(schema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
+/>
 `;
 }

package/helpers/constraintSchemaPaths.js

@@ -0,0 +1,46 @@
+import path from 'path';
+import fs from 'fs';
+
+function getConstraintsPackageRoot() {
+  const candidates = [
+    path.resolve(process.cwd(), 'packages', 'tracking-target-constraints'),
+    path.resolve(
+      process.cwd(),
+      '..',
+      'packages',
+      'tracking-target-constraints',
+    ),
+    path.resolve(
+      process.cwd(),
+      '..',
+      '..',
+      'packages',
+      'tracking-target-constraints',
+    ),
+  ];
+
+  return candidates.find((candidate) => fs.existsSync(candidate));
+}
+
+function stripConstraintsPrefix(value) {
+  return value.replace(/^\/?constraints\//, '');
+}
+
+export function resolveConstraintSchemaPath(uri) {
+  if (!uri || typeof uri !== 'string') return null;
+
+  const constraintsPackageRoot = getConstraintsPackageRoot();
+  if (!constraintsPackageRoot) return null;
+
+  if (uri.startsWith('http://') || uri.startsWith('https://')) {
+    const { pathname } = new URL(uri);
+    if (!pathname.startsWith('/constraints/')) return null;
+    return path.join(constraintsPackageRoot, stripConstraintsPrefix(pathname));
+  }
+
+  if (uri.startsWith('/constraints/') || uri.startsWith('constraints/')) {
+    return path.join(constraintsPackageRoot, stripConstraintsPrefix(uri));
+  }
+
+  return null;
+}

package/helpers/file-system.js

@@ -23,6 +23,34 @@ export function readSchemas(directory) {
   });
 }
 
+export function readSchemaSources(directory) {
+  const schemaSources = {};
+
+  function walk(currentDirectory) {
+    const entries = fs.readdirSync(currentDirectory, { withFileTypes: true });
+
+    entries.forEach((entry) => {
+      const entryPath = path.join(currentDirectory, entry.name);
+      if (entry.isDirectory()) {
+        walk(entryPath);
+        return;
+      }
+
+      if (!entry.name.endsWith('.json')) return;
+      const relativePath = path
+        .relative(directory, entryPath)
+        .split(path.sep)
+        .join('/');
+      schemaSources[relativePath] = JSON.parse(
+        fs.readFileSync(entryPath, 'utf-8'),
+      );
+    });
+  }
+
+  walk(directory);
+  return schemaSources;
+}
+
 export function writeDoc(outputDir, fileName, content) {
   fs.writeFileSync(path.join(outputDir, fileName), content);
   console.log(

package/helpers/mergeSchema.js

@@ -0,0 +1,16 @@
+import mergeJsonSchema from 'json-schema-merge-allof';
+
+const baseResolvers = {
+  $defs: mergeJsonSchema.options.resolvers.definitions,
+  defaultResolver: mergeJsonSchema.options.resolvers.title,
+};
+
+export function mergeSchema(schema, options = {}) {
+  return mergeJsonSchema(schema, {
+    ...options,
+    resolvers: {
+      ...baseResolvers,
+      ...(options.resolvers || {}),
+    },
+  });
+}

package/helpers/processSchema.js

@@ -1,5 +1,7 @@
 import $RefParser from '@apidevtools/json-schema-ref-parser';
-import mergeJsonSchema from 'json-schema-merge-allof';
+import fs from 'fs';
+import { resolveConstraintSchemaPath } from './constraintSchemaPaths.js';
+import { mergeSchema } from './mergeSchema.js';
 
 /**
  * Processes a JSON schema file by bundling external references,
@@ -12,6 +14,21 @@ export default async function processSchema(filePath) {
   // 1. Bundle all external references into a single, self-contained schema
   const bundledSchema = await $RefParser.bundle(filePath, {
     mutateInputSchema: false,
+    resolve: {
+      constraints: {
+        order: 1,
+        canRead: (file) => Boolean(resolveConstraintSchemaPath(file.url)),
+        read: (file) => {
+          const localPath = resolveConstraintSchemaPath(file.url);
+          if (!localPath) {
+            throw new Error(
+              `Could not resolve local path for constraint ref: ${file.url}`,
+            );
+          }
+          return fs.readFileSync(localPath, 'utf8');
+        },
+      },
+    },
   });
 
   // 2. Dereference the bundled schema to resolve internal refs for allOf merging
@@ -22,11 +39,7 @@ export default async function processSchema(filePath) {
   });
 
   // Then merge allOf properties
-  const mergedSchema = mergeJsonSchema(dereferencedSchema, {
-    resolvers: {
-      defaultResolver: mergeJsonSchema.options.resolvers.title,
-    },
-  });
+  const mergedSchema = mergeSchema(dereferencedSchema);
 
   return mergedSchema;
 }

package/helpers/schema-doc-template.js

@@ -9,6 +9,8 @@ export default function MdxTemplate(data) {
     topPartialComponent,
     bottomPartialComponent,
     dataLayerName,
+    sourcePath,
+    schemaSources,
   } = data;
 
   return `---
@@ -33,7 +35,11 @@ ${topPartialComponent}
   schema={${JSON.stringify(mergedSchema)}}
   ${dataLayerName ? ` dataLayerName={'${dataLayerName}'}` : ''}
 />
-<SchemaJsonViewer schema={${JSON.stringify(schema)}} />
+<SchemaJsonViewer
+  schema={${JSON.stringify(schema)}}
+  sourcePath={${JSON.stringify(sourcePath)}}
+  schemaSources={${JSON.stringify(schemaSources)}}
+/>
 
 ${bottomPartialComponent}
 `;

package/helpers/schema-processing.js

@@ -1,7 +1,7 @@
 import path from 'path';
 import fs from 'fs';
 import processSchema from './processSchema.js';
-import mergeJsonSchema from 'json-schema-merge-allof';
+import { mergeSchema } from './mergeSchema.js';
 
 function mergePropertySchemas(baseProperties = {}, optionProperties = {}) {
   const mergedProperties = {
@@ -14,16 +14,9 @@ function mergePropertySchemas(baseProperties = {}, optionProperties = {}) {
       continue;
     }
 
-    mergedProperties[key] = mergeJsonSchema(
-      {
-        allOf: [baseProperties[key], optionProperties[key]],
-      },
-      {
-        resolvers: {
-          defaultResolver: mergeJsonSchema.options.resolvers.title,
-        },
-      },
-    );
+    mergedProperties[key] = mergeSchema({
+      allOf: [baseProperties[key], optionProperties[key]],
+    });
   }
 
   return mergedProperties;

package/helpers/schemaToExamples.js

@@ -1,5 +1,5 @@
 import buildExampleFromSchema from './buildExampleFromSchema';
-import mergeJsonSchema from 'json-schema-merge-allof';
+import { mergeSchema } from './mergeSchema.js';
 
 const findChoicePoints = (subSchema, path = []) => {
   if (!subSchema) {
@@ -47,7 +47,7 @@ const generateExampleForChoice = (rootSchema, path, option) => {
   if (path.length === 0) {
     delete schemaVariant.oneOf;
     delete schemaVariant.anyOf;
-    const newSchemaVariant = mergeJsonSchema({
+    const newSchemaVariant = mergeSchema({
       allOf: [schemaVariant, option],
     });
     return buildExampleFromSchema(newSchemaVariant);
@@ -112,7 +112,7 @@ const generateConditionalExample = (rootSchema, path, branch) => {
     delete schemaVariant.else;
     if (branchSchema) {
       const merged = pruneSiblingConditionalProperties(
-        mergeJsonSchema({ allOf: [schemaVariant, branchSchema] }),
+        mergeSchema({ allOf: [schemaVariant, branchSchema] }),
         branchSchema,
         siblingBranchSchema,
         baseRequired,
@@ -134,7 +134,7 @@ const generateConditionalExample = (rootSchema, path, branch) => {
   delete target.else;
   if (branchSchema) {
     const merged = pruneSiblingConditionalProperties(
-      mergeJsonSchema({ allOf: [target, branchSchema] }),
+      mergeSchema({ allOf: [target, branchSchema] }),
       branchSchema,
       siblingBranchSchema,
       baseRequired,