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

package/__tests__/validateSchemas.test.js

@@ -1,5 +1,5 @@
 /**
- * @jest-environment node
+ * @jest-environment @stryker-mutator/jest-runner/jest-env/node
  */
 
 import path from 'path';
@@ -102,4 +102,195 @@ describe('validateSchemas', () => {
     expect(consoleErrorSpy).toHaveBeenCalled();
     expect(consoleErrorSpy.mock.calls[0][0]).toContain('x-tracking-targets');
   });
+
+  it('should treat falsy scalar examples as valid examples', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'event.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+          event: {
+            type: 'string',
+            const: 'test_event',
+          },
+          is_enabled: {
+            type: 'boolean',
+            example: false,
+          },
+          retry_count: {
+            type: 'integer',
+            example: 0,
+          },
+          note: {
+            type: 'string',
+            example: '',
+          },
+        },
+        required: ['event', 'is_enabled', 'retry_count', 'note'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+  });
+
+  it('should allow a top-level falsy example value', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.writeFileSync(
+      path.join(schemaDir, 'flag.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'boolean',
+        example: false,
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(true);
+  });
+
+  it('should return false and log errors when a schema produces no examples', async () => {
+    const fixturePath = path.resolve(
+      __dirname,
+      '__fixtures__',
+      'validateSchemas',
+      'no-example-schema.json',
+    );
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.copyFileSync(
+      fixturePath,
+      path.join(schemaDir, 'no-example-schema.json'),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    const errorMessages = consoleErrorSpy.mock.calls
+      .map((c) => c[0])
+      .join('\n');
+    expect(errorMessages).toContain('does not produce any examples');
+  });
+
+  it('should return false and log error when processing a schema throws', async () => {
+    const fixturePath = path.resolve(
+      __dirname,
+      '__fixtures__',
+      'validateSchemas',
+      'main-schema-with-missing-ref.json',
+    );
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+    fs.copyFileSync(
+      fixturePath,
+      path.join(schemaDir, 'main-schema-with-missing-ref.json'),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    const errorMessages = consoleErrorSpy.mock.calls
+      .map((c) => c[0])
+      .join('\n');
+    expect(errorMessages).toContain('Error processing');
+  });
+
+  it('should report errors for all failing schemas when multiple schemas exist', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+
+    // First schema: valid
+    fs.writeFileSync(
+      path.join(schemaDir, 'valid.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: { event: { type: 'string', const: 'ok' } },
+        required: ['event'],
+      }),
+    );
+
+    // Second schema: no examples produced
+    fs.writeFileSync(
+      path.join(schemaDir, 'no-examples.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: { untyped: { description: 'no type or example' } },
+        required: ['untyped'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+  });
+
+  it('should return false when a oneOf option produces an undefined example', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+
+    // Schema with a oneOf where one option has no resolvable example
+    fs.writeFileSync(
+      path.join(schemaDir, 'undef-option.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        oneOf: [
+          {
+            title: 'ValidOption',
+            properties: { event: { type: 'string', const: 'test' } },
+            required: ['event'],
+          },
+          {
+            title: 'UndefinedOption',
+            properties: { mystery: { description: 'no type, no example' } },
+            required: ['mystery'],
+          },
+        ],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    const errorMessages = consoleErrorSpy.mock.calls
+      .map((c) => c[0])
+      .join('\n');
+    expect(errorMessages).toContain('does not produce a valid example');
+  });
+
+  it('should report all examples invalid when every example fails validation', async () => {
+    const schemaDir = path.join(tmpDir, 'schemas');
+    fs.mkdirSync(schemaDir, { recursive: true });
+
+    // Schema where every oneOf option produces an example that fails schema validation
+    fs.writeFileSync(
+      path.join(schemaDir, 'all-invalid.json'),
+      JSON.stringify({
+        $schema: 'https://json-schema.org/draft/2020-12/schema',
+        type: 'object',
+        properties: {
+          count: {
+            type: 'integer',
+            minimum: 100,
+            example: 1,
+          },
+        },
+        required: ['count'],
+      }),
+    );
+
+    const result = await validateSchemas(schemaDir);
+    expect(result).toBe(false);
+    expect(consoleErrorSpy).toHaveBeenCalled();
+    const errorMessages = consoleErrorSpy.mock.calls
+      .map((c) => c[0])
+      .join('\n');
+    expect(errorMessages).toContain('example data failed validation');
+  });
 });

package/components/PropertiesTable.js

@@ -5,9 +5,39 @@ import WordWrapButton from './WordWrapButton';
 import { schemaToTableData } from '../helpers/schemaToTableData';
 import styles from './PropertiesTable.module.css';
 
-export default function PropertiesTable({ schema }) {
+function filterInheritedTopLevelProperties(schema, sourceSchema) {
+  if (!schema?.properties || !sourceSchema?.properties) {
+    return schema;
+  }
+
+  const sourceKeys = new Set(Object.keys(sourceSchema.properties));
+  const filteredEntries = Object.entries(schema.properties).filter(
+    ([key, propSchema]) => {
+      if (sourceKeys.has(key)) {
+        return true;
+      }
+
+      const hasDescription =
+        typeof propSchema?.description === 'string' &&
+        propSchema.description.trim().length > 0;
+      const hasExamples =
+        Array.isArray(propSchema?.examples) && propSchema.examples.length > 0;
+      const hasExample = propSchema?.example !== undefined;
+
+      return hasDescription || hasExamples || hasExample;
+    },
+  );
+
+  return {
+    ...schema,
+    properties: Object.fromEntries(filteredEntries),
+  };
+}
+
+export default function PropertiesTable({ schema, sourceSchema }) {
   const [isWordWrapOn, setIsWordWrapOn] = useState(true);
-  const tableData = schemaToTableData(schema);
+  const tableSchema = filterInheritedTopLevelProperties(schema, sourceSchema);
+  const tableData = schemaToTableData(tableSchema);
   const stripeState = { current: 0 };
 
   return (

package/components/PropertyRow.js

@@ -26,6 +26,19 @@ const getContainerSymbol = (containerType) => {
   return '';
 };
 
+const formatPropertyType = (value) => {
+  if (Array.isArray(value)) {
+    return value.join(', ');
+  }
+  if (typeof value === 'string') {
+    return value;
+  }
+  if (value === undefined || value === null) {
+    return '';
+  }
+  return JSON.stringify(value);
+};
+
 const KEYWORD_HELP_TEXT = {
   additionalProperties:
     'Controls properties not listed in properties and not matched by patternProperties.',
@@ -33,6 +46,8 @@ const KEYWORD_HELP_TEXT = {
     'Applies the subschema to property names that match the given regular expression.',
 };
 
+const SCHEMA_KEYWORD_BADGE_TEXT = 'Schema constraint';
+
 function splitKeywordLabel(name) {
   const match = /^patternProperties (\/.+\/)$/.exec(name);
   if (!match) {
@@ -45,6 +60,15 @@ function splitKeywordLabel(name) {
   };
 }
 
+function buildKeywordHelpId(name, rowPath) {
+  if (!rowPath || rowPath.length === 0) {
+    return `schema-keyword-help-${name}`;
+  }
+
+  const normalizedPath = rowPath.join('-').replace(/[^a-zA-Z0-9_-]/g, '_');
+  return `schema-keyword-help-${normalizedPath}`;
+}
+
 /**
  * Renders a single property row in the schema table.
  * All data is passed in via the `row` prop, which comes from `tableData`.
@@ -145,7 +169,7 @@ export default function PropertyRow({
     : name;
   const keywordHelpText = KEYWORD_HELP_TEXT[keywordHelpKey];
   const keywordHelpId = keywordHelpText
-    ? `schema-keyword-help-${name}`
+    ? buildKeywordHelpId(name, row.path)
     : undefined;
   const zebraClassName =
     stripeIndex === undefined
@@ -208,6 +232,9 @@ export default function PropertyRow({
                     {name}
                   </code>
                 )}
+                <span className="property-keyword-badge">
+                  {SCHEMA_KEYWORD_BADGE_TEXT}
+                </span>
                 <span
                   id={keywordHelpId}
                   className="property-keyword-tooltip"
@@ -222,7 +249,7 @@ export default function PropertyRow({
           </span>
         </td>
         <td rowSpan={rowSpan}>
-          <code>{propertyType}</code>
+          <code>{formatPropertyType(propertyType)}</code>
         </td>
 
         {/* The first constraint cell */}