@mintlify/scraping 4.0.1109 → 4.0.1111

package/__test__/sdk-typedoc.test.ts

@@ -235,4 +235,616 @@ describe('convertTypedoc', () => {
       }).slug
     ).toBe('classes/Client/login');
   });
+
+  describe('member-level @category tags', () => {
+    const client = {
+      id: 1,
+      name: 'Auth0Client',
+      kind: 128,
+      comment: { summary: [{ kind: 'text', text: 'SDK for SPAs.' }] },
+      children: [
+        {
+          id: 2,
+          name: 'constructor',
+          kind: 512,
+          signatures: [
+            {
+              id: 3,
+              name: 'new Auth0Client',
+              kind: 16384,
+              parameters: [
+                {
+                  id: 4,
+                  name: 'options',
+                  kind: 32768,
+                  type: { type: 'intrinsic', name: 'object' },
+                },
+              ],
+              type: { type: 'reference', name: 'Auth0Client', target: 1 },
+            },
+          ],
+        },
+        {
+          id: 5,
+          name: 'mfa',
+          kind: 1024,
+          type: { type: 'intrinsic', name: 'object' },
+          comment: { summary: [{ kind: 'text', text: 'MFA API.' }] },
+        },
+        {
+          id: 6,
+          name: 'checkSession',
+          kind: 2048,
+          signatures: [
+            { id: 7, name: 'checkSession', kind: 4096, type: { type: 'intrinsic', name: 'void' } },
+          ],
+        },
+        {
+          id: 8,
+          name: 'getTokenSilently',
+          kind: 2048,
+          signatures: [
+            {
+              id: 9,
+              name: 'getTokenSilently',
+              kind: 4096,
+              type: { type: 'intrinsic', name: 'string' },
+            },
+          ],
+        },
+        {
+          id: 10,
+          name: 'logout',
+          kind: 2048,
+          signatures: [
+            { id: 11, name: 'logout', kind: 4096, type: { type: 'intrinsic', name: 'void' } },
+          ],
+        },
+        {
+          id: 12,
+          name: 'secret',
+          kind: 1024,
+          flags: { isPrivate: true },
+          type: { type: 'intrinsic', name: 'string' },
+        },
+      ],
+    };
+
+    async function convert(classNode: object) {
+      const artifact = path.join(directory, 'typedoc.json');
+      await writeFile(
+        artifact,
+        JSON.stringify({ id: 0, name: '@auth0/example', kind: 1, children: [classNode] })
+      );
+      const reference = await convertTypedoc(artifact);
+      return reference.pages.find((page) => page.slug === 'classes/Auth0Client')?.content ?? '';
+    }
+
+    function headings(content: string): string[] {
+      return content.split('\n').filter((line) => /^#{2,5} /.test(line));
+    }
+
+    it('renders one section per category in artifact order', async () => {
+      const content = await convert({
+        ...client,
+        groups: [
+          { title: 'Constructors', children: [2] },
+          { title: 'Properties', children: [5, 12] },
+          { title: 'Methods', children: [6, 8, 10] },
+        ],
+        categories: [
+          { title: 'Constructor', children: [2] },
+          { title: 'Sub-clients', children: [5, 12] },
+          { title: 'Authentication', children: [6] },
+          { title: 'Tokens', children: [8] },
+          { title: 'Other', children: [10] },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Constructor',
+        '### Parameters',
+        '### Returns',
+        '## Sub-clients',
+        '## Authentication',
+        '### checkSession()',
+        '## Tokens',
+        '### getTokenSilently()',
+        '#### Returns',
+        '## Other',
+        '### logout()',
+      ]);
+      expect(content).toContain('<ResponseField name={"mfa"} type={"object"} required>');
+      expect(content).not.toContain('secret');
+      expect(content).not.toContain('## Methods');
+    });
+
+    it('nests categories under kind groups when typedoc categorizes by group', async () => {
+      const content = await convert({
+        ...client,
+        groups: [
+          {
+            title: 'Constructors',
+            children: [2],
+            categories: [{ title: 'Constructor', children: [2] }],
+          },
+          {
+            title: 'Properties',
+            children: [5],
+            categories: [{ title: 'Sub-clients', children: [5] }],
+          },
+          {
+            title: 'Methods',
+            children: [6, 8, 10],
+            categories: [
+              { title: 'Authentication', children: [6] },
+              { title: 'Other', children: [10] },
+              { title: 'Tokens', children: [8] },
+            ],
+          },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Constructors',
+        '### Constructor',
+        '#### Parameters',
+        '#### Returns',
+        '## Properties',
+        '### Sub-clients',
+        '## Methods',
+        '### Authentication',
+        '#### checkSession()',
+        '### Other',
+        '#### logout()',
+        '### Tokens',
+        '#### getTokenSilently()',
+      ]);
+      expect(content).toContain(
+        '#### getTokenSilently()\n\n```typescript\ngetTokenSilently(): string\n```\n\n**Returns**\n\n`string`'
+      );
+    });
+
+    it('renders a member once even when its id is repeated across categories', async () => {
+      const content = await convert({
+        ...client,
+        categories: [
+          { title: 'Primary', children: Array.from({ length: 500 }, () => 6) },
+          { title: 'Secondary', children: [6, 8] },
+        ],
+      });
+
+      expect(content.match(/### checkSession\(\)/g)).toHaveLength(1);
+      expect(headings(content)).toEqual([
+        '## Primary',
+        '### checkSession()',
+        '## Secondary',
+        '### getTokenSilently()',
+        '#### Returns',
+      ]);
+    });
+
+    it('escapes category titles used as headings', async () => {
+      const content = await convert({
+        ...client,
+        categories: [
+          { title: 'Collections <T>', children: [5] },
+          { title: 'Login {redirect}', children: [6, 8, 10] },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Collections',
+        '## Login \\{redirect}',
+        '### checkSession()',
+        '### getTokenSilently()',
+        '#### Returns',
+        '### logout()',
+      ]);
+      expect(content).not.toContain('<T>');
+    });
+
+    it('keeps multi-line titles inside a single heading', async () => {
+      const content = await convert({
+        ...client,
+        categories: [
+          { title: 'Auth\nexport const x = alert(1)', children: [5] },
+          { title: 'A\n\n# Big', children: [6] },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Auth export const x = alert(1)',
+        '## A # Big',
+        '### checkSession()',
+      ]);
+      expect(content).not.toMatch(/^export /m);
+      expect(content).not.toMatch(/^# Big/m);
+    });
+
+    it('mirrors custom member @group titles', async () => {
+      const content = await convert({
+        ...client,
+        groups: [
+          { title: 'Constructors', children: [2] },
+          { title: 'Sub-clients', children: [5] },
+          { title: 'Methods', children: [6, 8, 10] },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Constructors',
+        '### Parameters',
+        '### Returns',
+        '## Sub-clients',
+        '## Methods',
+        '### checkSession()',
+        '### getTokenSilently()',
+        '#### Returns',
+        '### logout()',
+      ]);
+    });
+
+    it('keeps the kind-based layout when members only have default groups', async () => {
+      const content = await convert({
+        ...client,
+        groups: [
+          { title: 'Constructors', children: [2] },
+          { title: 'Properties', children: [5, 12] },
+          { title: 'Methods', children: [6, 8, 10] },
+        ],
+      });
+
+      expect(headings(content)).toEqual([
+        '## Constructor',
+        '### Parameters',
+        '### Returns',
+        '## Properties',
+        '## Methods',
+        '### checkSession()',
+        '### getTokenSilently()',
+        '#### Returns',
+        '### logout()',
+      ]);
+    });
+  });
+
+  describe('@category and @group tags', () => {
+    const categorized = {
+      id: 0,
+      name: '@auth0/example',
+      kind: 1,
+      children: [
+        { id: 1, name: 'helper', kind: 64, signatures: [] },
+        {
+          id: 3,
+          name: 'MfaApiClient',
+          kind: 128,
+          comment: {
+            summary: [{ kind: 'text', text: 'Client for MFA.' }],
+            blockTags: [{ tag: '@category', content: [{ kind: 'text', text: 'Authentication' }] }],
+          },
+          children: [],
+        },
+        { id: 9, name: 'ChallengeAuthenticatorParams', kind: 256, children: [] },
+        { id: 11, name: 'ChallengeResponse', kind: 256, children: [] },
+        { id: 14, name: 'UsersClient', kind: 128, children: [] },
+        { id: 19, name: 'Plain', kind: 256, children: [] },
+        { id: 21, name: 'UserId', kind: 2097152, type: { type: 'intrinsic', name: 'string' } },
+        { id: 30, name: 'Secret', kind: 128, flags: { isPrivate: true }, children: [] },
+      ],
+    };
+
+    async function convert(project: object) {
+      const artifact = path.join(directory, 'typedoc.json');
+      await writeFile(artifact, JSON.stringify(project));
+      return convertTypedoc(artifact);
+    }
+
+    it('mirrors top-level categories from the artifact', async () => {
+      const reference = await convert({
+        ...categorized,
+        groups: [
+          { title: 'Classes', children: [3, 14] },
+          { title: 'Interfaces', children: [9, 11, 19] },
+          { title: 'Type Aliases', children: [21] },
+          { title: 'Functions', children: [1] },
+        ],
+        categories: [
+          { title: 'Authentication', children: [3, 9, 11, 30] },
+          { title: 'Management', children: [14, 21] },
+          { title: 'Other', children: [19, 1] },
+        ],
+      });
+
+      expect(reference.groups).toEqual([
+        {
+          group: 'Authentication',
+          pages: [
+            'classes/MfaApiClient',
+            'interfaces/ChallengeAuthenticatorParams',
+            'interfaces/ChallengeResponse',
+          ],
+        },
+        { group: 'Management', pages: ['classes/UsersClient', 'types/UserId'] },
+        { group: 'Other', pages: ['interfaces/Plain', 'functions/helper'] },
+      ]);
+      const mfa = reference.pages.find((page) => page.slug === 'classes/MfaApiClient');
+      expect(mfa?.content).not.toContain('@category');
+      expect(mfa?.content).not.toContain('Authentication');
+    });
+
+    it('nests categories inside groups when typedoc categorizes by group', async () => {
+      const reference = await convert({
+        ...categorized,
+        groups: [
+          {
+            title: 'Classes',
+            children: [3, 14],
+            categories: [
+              { title: 'Authentication', children: [3] },
+              { title: 'Management', children: [14] },
+            ],
+          },
+          {
+            title: 'Interfaces',
+            children: [9, 11, 19],
+            categories: [
+              { title: 'Authentication', children: [9, 11] },
+              { title: 'Other', children: [19] },
+            ],
+          },
+          { title: 'Functions', children: [1] },
+        ],
+      });
+
+      expect(reference.groups).toEqual([
+        {
+          group: 'Classes',
+          pages: [
+            { group: 'Authentication', pages: ['classes/MfaApiClient'] },
+            { group: 'Management', pages: ['classes/UsersClient'] },
+          ],
+        },
+        {
+          group: 'Interfaces',
+          pages: [
+            {
+              group: 'Authentication',
+              pages: ['interfaces/ChallengeAuthenticatorParams', 'interfaces/ChallengeResponse'],
+            },
+            { group: 'Other', pages: ['interfaces/Plain'] },
+          ],
+        },
+        { group: 'Functions', pages: ['functions/helper'] },
+      ]);
+    });
+
+    it('mirrors custom @group titles in artifact order', async () => {
+      const reference = await convert({
+        ...categorized,
+        groups: [
+          { title: 'Helpers', children: [1] },
+          { title: 'Classes', children: [3, 14] },
+          { title: 'Interfaces', children: [9, 11, 19] },
+          { title: 'Type Aliases', children: [21] },
+        ],
+      });
+
+      expect(reference.groups.map((group) => group.group)).toEqual([
+        'Helpers',
+        'Classes',
+        'Interfaces',
+        'Type Aliases',
+      ]);
+      expect(reference.groups[0]).toEqual({ group: 'Helpers', pages: ['functions/helper'] });
+    });
+
+    it('detects a @group that borrows a default title for a different kind', async () => {
+      const reference = await convert({
+        ...categorized,
+        groups: [
+          { title: 'Classes', children: [3, 14, 9] },
+          { title: 'Interfaces', children: [11, 19] },
+          { title: 'Type Aliases', children: [21] },
+          { title: 'Functions', children: [1] },
+        ],
+      });
+
+      expect(reference.groups[0]).toEqual({
+        group: 'Classes',
+        pages: [
+          'classes/MfaApiClient',
+          'classes/UsersClient',
+          'interfaces/ChallengeAuthenticatorParams',
+        ],
+      });
+    });
+
+    it('keeps kind-based groups when the artifact only has default groups', async () => {
+      const reference = await convert({
+        ...categorized,
+        groups: [
+          { title: 'Functions', children: [1] },
+          { title: 'Classes', children: [3, 14] },
+          { title: 'Interfaces', children: [9, 11, 19] },
+          { title: 'Type Aliases', children: [21] },
+        ],
+      });
+
+      expect(reference.groups.map((group) => group.group)).toEqual([
+        'Classes',
+        'Interfaces',
+        'Functions',
+        'Type Aliases',
+      ]);
+    });
+
+    it('detects a @group that only contains namespaces', async () => {
+      const reference = await convert({
+        id: 0,
+        name: '@auth0/example',
+        kind: 1,
+        children: [
+          {
+            id: 1,
+            name: 'Admin',
+            kind: 4,
+            children: [{ id: 2, name: 'Users', kind: 128, children: [] }],
+            groups: [{ title: 'Classes', children: [2] }],
+          },
+          { id: 3, name: 'Client', kind: 128, children: [] },
+        ],
+        groups: [
+          { title: 'Classes', children: [3] },
+          { title: 'Admin APIs', children: [1] },
+        ],
+      });
+
+      expect(reference.groups).toEqual([
+        { group: 'Classes', pages: ['classes/Client'] },
+        {
+          group: 'Admin APIs',
+          pages: [
+            { group: 'Admin', pages: [{ group: 'Classes', pages: ['Admin/classes/Users'] }] },
+          ],
+        },
+      ]);
+    });
+
+    it('collapses a wrapped @category title onto one line', async () => {
+      const reference = await convert({
+        ...categorized,
+        categories: [{ title: 'Multi-factor\nauthentication', children: [3] }],
+      });
+
+      expect(reference.groups).toEqual([
+        { group: 'Multi-factor authentication', pages: ['classes/MfaApiClient'] },
+      ]);
+    });
+
+    it('lists a page under every category that references it', async () => {
+      const reference = await convert({
+        ...categorized,
+        categories: [
+          { title: 'Clients', children: [3, 1] },
+          { title: 'Helpers', children: [1, 1] },
+          { title: 'Utilities', children: [1] },
+        ],
+      });
+
+      expect(reference.groups).toEqual([
+        { group: 'Clients', pages: ['classes/MfaApiClient', 'functions/helper'] },
+        { group: 'Helpers', pages: ['functions/helper'] },
+        { group: 'Utilities', pages: ['functions/helper'] },
+      ]);
+    });
+
+    it('fails the build when a page is listed in more than 8 groups', async () => {
+      await expect(
+        convert({
+          ...categorized,
+          categories: Array.from({ length: 9 }, (_, index) => ({
+            title: `Category ${index}`,
+            children: [1],
+          })),
+        })
+      ).rejects.toThrow('"helper" is listed in more than 8 navigation groups');
+    });
+
+    it('fails the build when a declaration name exceeds 512 characters', async () => {
+      await expect(
+        convert({
+          ...categorized,
+          children: [{ id: 1, name: 'x'.repeat(513), kind: 64, signatures: [] }],
+        })
+      ).rejects.toThrow('exceeds 512 characters');
+    });
+
+    it('expands each namespace once even when ids are repeated across the layout', async () => {
+      const depth = 24;
+      let child: Record<string, unknown> = {
+        id: depth + 1,
+        name: 'Leaf',
+        kind: 128,
+        children: [],
+      };
+      for (let level = depth; level >= 1; level -= 1) {
+        const childId = child.id as number;
+        child = {
+          id: level,
+          name: `Ns${level}`,
+          kind: 4,
+          children: [child],
+          groups: [{ title: 'Namespaces', children: [childId, childId] }],
+          categories: [
+            { title: 'A', children: [childId, childId] },
+            { title: 'B', children: [childId] },
+          ],
+        };
+      }
+      const reference = await convert({
+        id: 0,
+        name: '@auth0/example',
+        kind: 1,
+        children: [child],
+        categories: [{ title: 'Root', children: [1, 1] }],
+      });
+
+      const serialized = JSON.stringify(reference.groups);
+      expect(serialized.length).toBeLessThan(5_000);
+      expect(serialized.match(/Leaf/g)).toHaveLength(2);
+      expect(reference.groups).toEqual([
+        {
+          group: 'Root',
+          pages: [expect.objectContaining({ group: 'Ns1' })],
+        },
+      ]);
+    });
+
+    it('nests namespaces that carry their own categories', async () => {
+      const reference = await convert({
+        id: 0,
+        name: '@auth0/example',
+        kind: 1,
+        children: [
+          {
+            id: 1,
+            name: 'Admin',
+            kind: 4,
+            children: [
+              { id: 2, name: 'Users', kind: 128, children: [] },
+              { id: 3, name: 'Roles', kind: 128, children: [] },
+            ],
+            groups: [{ title: 'Classes', children: [2, 3] }],
+            categories: [
+              { title: 'Identity', children: [2] },
+              { title: 'Access', children: [3] },
+            ],
+          },
+          { id: 4, name: 'Client', kind: 128, children: [] },
+        ],
+        groups: [
+          { title: 'Namespaces', children: [1] },
+          { title: 'Classes', children: [4] },
+        ],
+      });
+
+      expect(reference.groups).toEqual([
+        {
+          group: 'Namespaces',
+          pages: [
+            {
+              group: 'Admin',
+              pages: [
+                { group: 'Identity', pages: ['Admin/classes/Users'] },
+                { group: 'Access', pages: ['Admin/classes/Roles'] },
+              ],
+            },
+          ],
+        },
+        { group: 'Classes', pages: ['classes/Client'] },
+      ]);
+    });
+  });
 });