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

package/__tests__/helpers/buildExampleFromSchema.test.js

@@ -234,4 +234,244 @@ describe('buildExampleFromSchema', () => {
     expect(example.shipping).toHaveProperty('method', 'express');
     expect(example.shipping).toHaveProperty('priority', 'high');
   });
+
+  it('should use example value from a primitive schema that has examples (L19)', () => {
+    // primitive with examples — must return example value, not placeholder
+    const schema = { type: 'string', examples: ['hello'] };
+    expect(buildExampleFromSchema(schema)).toBe('hello');
+  });
+
+  it('should use example value from integer schema with examples (L19)', () => {
+    const schema = { type: 'integer', examples: [42] };
+    expect(buildExampleFromSchema(schema)).toBe(42);
+  });
+
+  it('should use the first option from oneOf when items length > 0 (L25)', () => {
+    const schema = {
+      type: 'object',
+      properties: { event: { type: 'string', examples: ['purchase'] } },
+      oneOf: [
+        {
+          title: 'Option A',
+          properties: { extra: { type: 'string', examples: ['a'] } },
+        },
+        {
+          title: 'Option B',
+          properties: { extra: { type: 'string', examples: ['b'] } },
+        },
+      ],
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toHaveProperty('extra', 'a');
+    expect(example).toHaveProperty('event', 'purchase');
+  });
+
+  it('should use the first option from anyOf when items length > 0 (L25)', () => {
+    const schema = {
+      anyOf: [
+        { type: 'string', examples: ['first'] },
+        { type: 'string', examples: ['second'] },
+      ],
+    };
+    expect(buildExampleFromSchema(schema)).toBe('first');
+  });
+
+  it('should skip if/then branch when there is only if but no then (L34)', () => {
+    // schema.if && schema.then — the branch is only entered when both are present
+    const schema = {
+      type: 'object',
+      properties: {
+        event: { type: 'string', examples: ['test'] },
+        extra: { type: 'string', examples: ['value'] },
+      },
+      if: { properties: { event: { const: 'test' } } },
+      // deliberately no then
+      else: {
+        properties: {
+          error_code: { type: 'integer', examples: [404] },
+        },
+      },
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toHaveProperty('event', 'test');
+    expect(example).toHaveProperty('extra', 'value');
+    expect(example).not.toHaveProperty('error_code');
+  });
+
+  it('should infer object type from properties when no type is specified (L52)', () => {
+    const schema = {
+      properties: {
+        name: { type: 'string', examples: ['Alice'] },
+        age: { type: 'integer', examples: [30] },
+      },
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toEqual({ name: 'Alice', age: 30 });
+  });
+
+  it('should return undefined for object with type but no properties (L52)', () => {
+    const schema = { type: 'object' };
+    expect(buildExampleFromSchema(schema)).toBeUndefined();
+  });
+
+  it('should handle array type with items (L69)', () => {
+    const schema = {
+      type: 'array',
+      items: { type: 'string', examples: ['tag'] },
+    };
+    expect(buildExampleFromSchema(schema)).toEqual(['tag']);
+  });
+
+  it('should return undefined for array type with no items (L69)', () => {
+    const schema = { type: 'array' };
+    expect(buildExampleFromSchema(schema)).toBeUndefined();
+  });
+
+  it('should return empty string placeholder for string type without examples (L71 fallback)', () => {
+    const schema = { type: 'string' };
+    expect(buildExampleFromSchema(schema)).toBe('');
+  });
+
+  it('should return undefined for an unknown type (L71 fallback)', () => {
+    const schema = { type: 'unknown-type' };
+    expect(buildExampleFromSchema(schema)).toBeUndefined();
+  });
+
+  it('should return false placeholder for boolean type', () => {
+    const schema = { type: 'boolean' };
+    expect(buildExampleFromSchema(schema)).toBe(false);
+  });
+
+  it('should return 0 placeholder for number type', () => {
+    const schema = { type: 'number' };
+    expect(buildExampleFromSchema(schema)).toBe(0);
+  });
+
+  it('should use first type when schema.type is an array (L52)', () => {
+    const schema = {
+      type: ['string', 'null'],
+      examples: ['hello'],
+    };
+    expect(buildExampleFromSchema(schema)).toBe('hello');
+  });
+
+  it('should use first type placeholder when schema.type is array and no examples (L52)', () => {
+    const schema = { type: ['integer', 'null'] };
+    expect(buildExampleFromSchema(schema)).toBe(0);
+  });
+
+  // --- Mutant-killing tests ---
+
+  it('should return undefined for null/undefined schema (L19 guard)', () => {
+    expect(buildExampleFromSchema(null)).toBeUndefined();
+    expect(buildExampleFromSchema(undefined)).toBeUndefined();
+    expect(buildExampleFromSchema(0)).toBeUndefined();
+    expect(buildExampleFromSchema(false)).toBeUndefined();
+  });
+
+  it('should fall through to primitive placeholder when type is not object/array (L13 default)', () => {
+    // Ensures the default branch in getPrimitivePlaceholder returns undefined
+    // for unrecognized types, killing the ConditionalExpression mutant on L13-14
+    const schema = { type: 'null' };
+    expect(buildExampleFromSchema(schema)).toBeUndefined();
+  });
+
+  it('should skip oneOf branch when oneOf is an empty array (L25 length > 0)', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', examples: ['Alice'] },
+      },
+      oneOf: [],
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toEqual({ name: 'Alice' });
+  });
+
+  it('should skip anyOf branch when anyOf is an empty array (L25 length > 0)', () => {
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', examples: ['Bob'] },
+      },
+      anyOf: [],
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toEqual({ name: 'Bob' });
+  });
+
+  it('should not infer object type when type is explicitly set to a non-object type (L52 && vs ||)', () => {
+    // type is 'string' and properties exist — should NOT be treated as object
+    // Kills the LogicalOperator mutant that changes && to || on L52
+    const schema = {
+      type: 'string',
+      properties: {
+        name: { type: 'string', examples: ['ignored'] },
+      },
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toBe('');
+  });
+
+  it('should not enter object branch when inferredType is not object (L55 ConditionalExpression true)', () => {
+    // type is 'string' with properties — should return string placeholder, not object
+    const schema = {
+      type: 'string',
+      properties: {
+        foo: { type: 'integer', examples: [99] },
+      },
+    };
+    expect(buildExampleFromSchema(schema)).toBe('');
+  });
+
+  it('should not enter array branch when type is not array but items exists (L69 && vs ||)', () => {
+    // type is 'string' with items — should return string placeholder, not array
+    const schema = {
+      type: 'string',
+      items: { type: 'string', examples: ['ignored'] },
+    };
+    expect(buildExampleFromSchema(schema)).toBe('');
+  });
+
+  it('should not enter array branch when type is array but items is missing (L69 ConditionalExpression true)', () => {
+    // Already tested above but with strict assertion
+    const schema = { type: 'array' };
+    const result = buildExampleFromSchema(schema);
+    // Should fall through to getPrimitivePlaceholder which returns undefined for 'array'
+    expect(result).toBeUndefined();
+  });
+
+  it('should return undefined for array items that resolve to undefined (L71)', () => {
+    // Array with items that produce undefined — the whole array should be undefined
+    const schema = {
+      type: 'array',
+      items: { type: 'object' }, // object with no properties returns undefined
+    };
+    expect(buildExampleFromSchema(schema)).toBeUndefined();
+  });
+
+  it('should wrap array items value in array, not return empty string (L71 StringLiteral)', () => {
+    // Kills the StringLiteral mutant that replaces [itemValue] with ""
+    const schema = {
+      type: 'array',
+      items: { type: 'integer' },
+    };
+    const result = buildExampleFromSchema(schema);
+    expect(result).toEqual([0]);
+    expect(Array.isArray(result)).toBe(true);
+    expect(result).not.toBe('');
+  });
+
+  it('should handle oneOf with null/undefined choiceType length gracefully (L25 OptionalChaining)', () => {
+    // oneOf is present but not an array — optional chaining should prevent crash
+    const schema = {
+      type: 'object',
+      properties: {
+        name: { type: 'string', examples: ['test'] },
+      },
+      oneOf: null,
+    };
+    const example = buildExampleFromSchema(schema);
+    expect(example).toEqual({ name: 'test' });
+  });
 });

package/__tests__/helpers/constraintSchemaPaths.test.js

@@ -0,0 +1,208 @@
+import path from 'path';
+import { resolveConstraintSchemaPath } from '../../helpers/constraintSchemaPaths';
+
+jest.mock('fs');
+import fs from 'fs';
+
+// A stable resolved root path that mocked existsSync returns truthy for
+const MOCK_ROOT = path.resolve(
+  process.cwd(),
+  'packages',
+  'tracking-target-constraints',
+);
+
+beforeEach(() => {
+  jest.clearAllMocks();
+  // By default, make the first candidate exist
+  fs.existsSync.mockImplementation((p) => p === MOCK_ROOT);
+});
+
+describe('resolveConstraintSchemaPath — input validation', () => {
+  it('returns null for null uri', () => {
+    expect(resolveConstraintSchemaPath(null)).toBeNull();
+  });
+
+  it('returns null for undefined uri', () => {
+    expect(resolveConstraintSchemaPath(undefined)).toBeNull();
+  });
+
+  it('returns null for empty string', () => {
+    expect(resolveConstraintSchemaPath('')).toBeNull();
+  });
+
+  it('returns null for a number', () => {
+    expect(resolveConstraintSchemaPath(42)).toBeNull();
+  });
+
+  it('returns null for an object', () => {
+    expect(resolveConstraintSchemaPath({})).toBeNull();
+  });
+
+  it('rejects non-string via typeof check, not just falsiness', () => {
+    // 0 is falsy AND not a string — both checks reject it
+    expect(resolveConstraintSchemaPath(0)).toBeNull();
+    // true is not a string but truthy — only typeof check catches it
+    expect(resolveConstraintSchemaPath(true)).toBeNull();
+  });
+});
+
+describe('resolveConstraintSchemaPath — when package root not found', () => {
+  it('returns null when no candidate directory exists', () => {
+    fs.existsSync.mockReturnValue(false);
+    expect(resolveConstraintSchemaPath('/constraints/foo.json')).toBeNull();
+  });
+
+  it('checks multiple candidate paths (at least the primary one)', () => {
+    fs.existsSync.mockReturnValue(false);
+    resolveConstraintSchemaPath('/constraints/foo.json');
+    expect(fs.existsSync).toHaveBeenCalledWith(
+      path.resolve(process.cwd(), 'packages', 'tracking-target-constraints'),
+    );
+  });
+
+  it('falls back to second candidate (one level up) when primary missing', () => {
+    const secondCandidate = path.resolve(
+      process.cwd(),
+      '..',
+      'packages',
+      'tracking-target-constraints',
+    );
+    fs.existsSync.mockImplementation((p) => p === secondCandidate);
+    const result = resolveConstraintSchemaPath('/constraints/foo.json');
+    expect(result).toBe(path.join(secondCandidate, 'foo.json'));
+  });
+
+  it('falls back to third candidate (two levels up) when both others missing', () => {
+    const thirdCandidate = path.resolve(
+      process.cwd(),
+      '..',
+      '..',
+      'packages',
+      'tracking-target-constraints',
+    );
+    fs.existsSync.mockImplementation((p) => p === thirdCandidate);
+    const result = resolveConstraintSchemaPath('/constraints/foo.json');
+    expect(result).toBe(path.join(thirdCandidate, 'foo.json'));
+  });
+
+  it('falls back to node_modules package when monorepo candidates are missing', () => {
+    const installedPackageCandidate = path.resolve(
+      process.cwd(),
+      'node_modules',
+      'tracking-target-constraints',
+    );
+    fs.existsSync.mockImplementation((p) => p === installedPackageCandidate);
+
+    const result = resolveConstraintSchemaPath('/constraints/foo.json');
+
+    expect(result).toBe(path.join(installedPackageCandidate, 'foo.json'));
+  });
+});
+
+describe('resolveConstraintSchemaPath — HTTP/HTTPS URIs', () => {
+  it('resolves https URI with /constraints/ pathname', () => {
+    const result = resolveConstraintSchemaPath(
+      'https://example.com/constraints/schemas/foo.json',
+    );
+    expect(result).toBe(path.join(MOCK_ROOT, 'schemas/foo.json'));
+  });
+
+  it('resolves http URI with /constraints/ pathname', () => {
+    const result = resolveConstraintSchemaPath(
+      'http://example.com/constraints/bar.json',
+    );
+    expect(result).toBe(path.join(MOCK_ROOT, 'bar.json'));
+  });
+
+  it('returns null for https URI whose pathname does not start with /constraints/', () => {
+    expect(
+      resolveConstraintSchemaPath('https://example.com/other/schemas/foo.json'),
+    ).toBeNull();
+  });
+
+  it('returns null for https URI with empty pathname', () => {
+    expect(resolveConstraintSchemaPath('https://example.com/')).toBeNull();
+  });
+
+  it('strips leading /constraints/ from the pathname before joining', () => {
+    const result = resolveConstraintSchemaPath(
+      'https://example.com/constraints/nested/schema.json',
+    );
+    expect(result).toBe(path.join(MOCK_ROOT, 'nested/schema.json'));
+  });
+
+  it('uses startsWith not endsWith for http/https detection', () => {
+    // A local URI containing "http://" somewhere other than the start should not match
+    // this test validates the startsWith constraint; local URIs fall into the next branch
+    const result = resolveConstraintSchemaPath('/constraints/foo.json');
+    // Should resolve via local path branch, not via URL parsing
+    expect(result).toBe(path.join(MOCK_ROOT, 'foo.json'));
+  });
+});
+
+describe('resolveConstraintSchemaPath — local constraint URIs', () => {
+  it('resolves /constraints/ absolute path', () => {
+    const result = resolveConstraintSchemaPath('/constraints/schemas/foo.json');
+    expect(result).toBe(path.join(MOCK_ROOT, 'schemas/foo.json'));
+  });
+
+  it('resolves constraints/ relative path (no leading slash)', () => {
+    const result = resolveConstraintSchemaPath('constraints/schemas/bar.json');
+    expect(result).toBe(path.join(MOCK_ROOT, 'schemas/bar.json'));
+  });
+
+  it('strips /constraints/ prefix correctly (not just constraints/)', () => {
+    const withSlash = resolveConstraintSchemaPath('/constraints/foo.json');
+    const withoutSlash = resolveConstraintSchemaPath('constraints/foo.json');
+    // Both should resolve to the same file
+    expect(withSlash).toBe(withoutSlash);
+  });
+
+  it('returns null for a local path that does not start with /constraints/ or constraints/', () => {
+    expect(resolveConstraintSchemaPath('/other/foo.json')).toBeNull();
+  });
+
+  it('returns null for a path starting with /constraint/ (missing trailing s)', () => {
+    expect(resolveConstraintSchemaPath('/constraint/foo.json')).toBeNull();
+  });
+
+  it('returns null for a plain filename with no path prefix', () => {
+    expect(resolveConstraintSchemaPath('foo.json')).toBeNull();
+  });
+
+  it('uses OR not AND — resolves both /constraints/ and constraints/ variants', () => {
+    const absolute = resolveConstraintSchemaPath('/constraints/x.json');
+    const relative = resolveConstraintSchemaPath('constraints/x.json');
+    expect(absolute).not.toBeNull();
+    expect(relative).not.toBeNull();
+  });
+
+  it('uses startsWith not endsWith for local path detection', () => {
+    // A URI ending in constraints/ should NOT resolve
+    expect(resolveConstraintSchemaPath('foo/constraints/')).toBeNull();
+  });
+});
+
+describe('resolveConstraintSchemaPath — regex stripping', () => {
+  it('strips leading /constraints/ from pathname', () => {
+    const result = resolveConstraintSchemaPath(
+      '/constraints/deep/nested/file.json',
+    );
+    expect(result).toBe(path.join(MOCK_ROOT, 'deep/nested/file.json'));
+  });
+
+  it('strips leading constraints/ (no slash) from pathname', () => {
+    const result = resolveConstraintSchemaPath(
+      'constraints/deep/nested/file.json',
+    );
+    expect(result).toBe(path.join(MOCK_ROOT, 'deep/nested/file.json'));
+  });
+
+  it('only strips the prefix once, not globally', () => {
+    const result = resolveConstraintSchemaPath(
+      '/constraints/constraints/nested.json',
+    );
+    // After stripping /constraints/ prefix, we should have constraints/nested.json remaining
+    expect(result).toContain('constraints/nested.json');
+  });
+});