Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | import { describe, expect, test } from 'bun:test'; |
| 2 | import { join } from 'node:path'; |
| 3 | import { |
| 4 | checkCodeExamples, listCodeExampleFiles, inventoryCodeExamples, |
| 5 | parseCodeExamples, walkCodeExamples, |
| 6 | } from '../../lib/code-examples'; |
| 7 | import { componentsToMarkdown } from '../../lib/example-document'; |
| 8 | import { mdxToCleanMarkdown } from '../../lib/source'; |
| 9 | import { parseToolkitFaq } from '../../lib/toolkit-faq'; |
| 10 | |
| 11 | const root = join(import.meta.dir, '../..'); |
| 12 | const fence = (language: string, code: string) => `\`\`\`${language}\n${code}\n\`\`\``; |
| 13 | const tab = (value: string, content: string) => `<Tab value="${value}">\n\n${content}\n\n</Tab>`; |
| 14 | const python = fence('python', 'print("hello")'); |
| 15 | const typescript = fence('typescript', 'console.log("hello")'); |
| 16 | const api = fence('bash', 'curl https://backend.composio.dev/api/v3.1/tools -H "x-api-key: $COMPOSIO_API_KEY"'); |
| 17 | const group = (py = python, ts = typescript, rest: string | null = api) => |
| 18 | `<Tabs groupId="language" items={['Python', 'TypeScript'${rest === null ? '' : ", 'API'"}]} persist>\n${tab('Python', py)}\n${tab('TypeScript', ts)}\n${rest === null ? '' : tab('API', rest)}\n</Tabs>`; |
| 19 | function violations(source: string, path = 'page.mdx') { |
| 20 | return checkCodeExamples([{ source, path }], { requireApi: true }); |
| 21 | } |
| 22 | |
| 23 | // These are consumer-visible acceptance cases, not snapshots of an internal parse tree. |
| 24 | describe('rendered example boundaries', () => { |
| 25 | test('checks fences in blockquotes and lists instead of losing them', () => { |
| 26 | for (const source of [python.split('\n').map((line) => `> ${line}`).join('\n'), `- ${python.replaceAll('\n', '\n ')}`]) { |
| 27 | expect(violations(source).map((item) => item.rule)).toEqual(['standalone-sdk-fence']); |
| 28 | } |
| 29 | }); |
| 30 | |
| 31 | test('does not turn comments, quoted JSX attributes, strings, or inline code into examples or exemptions', () => { |
| 32 | expect(violations(`{/*\n${python}\n*/}`)).toEqual([]); |
| 33 | expect(violations(group().replace('persist>', 'data-note={\'<Tab value="not a real tab">\'} persist>'))).toEqual([]); |
| 34 | for (const literal of [ |
| 35 | `{'{/* code-example: single-language-page reason="rendered string" */}'}`, |
| 36 | '`{/* code-example: single-language-page reason="inline code" */}`', |
| 37 | ]) expect(violations(`${literal}\n\n${python}`).map((item) => item.rule)).toEqual(['standalone-sdk-fence']); |
| 38 | }); |
| 39 | |
| 40 | test('respects tilde fences and longer fences containing shorter ones', () => { |
| 41 | expect(violations(`\`\`\`\`mdx\n${python}\n\`\`\`\``)).toEqual([]); |
| 42 | expect(violations(python.replaceAll('```', '~~~')).map((item) => item.rule)).toEqual(['standalone-sdk-fence']); |
| 43 | }); |
| 44 | |
| 45 | test('keeps fences inside Callouts in the checked surface', () => { |
| 46 | const source = group(`<Callout>\n\n${typescript}\n\n</Callout>`); |
| 47 | expect(violations(source).some((item) => item.rule === 'language-cross-fence')).toBe(true); |
| 48 | }); |
| 49 | |
| 50 | test('checks nested language groups and multiline literal attributes', () => { |
| 51 | const inner = group().replace('groupId="language" items=', 'groupId={"language"}\n items='); |
| 52 | const source = `<Tabs items={['Bearer', 'API key']}>\n${tab('Bearer', inner)}\n${tab('API key', inner)}\n</Tabs>`; |
| 53 | expect(violations(source)).toEqual([]); |
| 54 | expect(violations(source.replace("['Python', 'TypeScript', 'API']", "['TypeScript', 'Python', 'API']")).some((item) => item.rule === 'language-items')).toBe(true); |
| 55 | }); |
| 56 | }); |
| 57 | |
| 58 | describe('language option contract', () => { |
| 59 | test('rejects missing, duplicate, empty, and wrong-language options', () => { |
| 60 | expect(violations(group().replace(tab('TypeScript', typescript), '')).some((item) => item.rule === 'language-items')).toBe(true); |
| 61 | expect(violations(group().replace(tab('TypeScript', typescript), tab('Python', python))).some((item) => item.message.includes('duplicate'))).toBe(true); |
| 62 | expect(violations(group(fence('python', ''))).map((item) => item.rule)).toContain('language-empty-tab'); |
| 63 | expect(violations(group(fence('bash', 'echo wrong'))).map((item) => item.rule)).toContain('language-cross-fence'); |
| 64 | expect(violations(group(python, python)).map((item) => item.rule)).toContain('language-cross-fence'); |
| 65 | expect(violations(group(python, typescript, fence('json', '{}'))).map((item) => item.rule)).toContain('language-cross-fence'); |
| 66 | }); |
| 67 | |
| 68 | test('accepts genuine installation instructions and explicit SDK-gap Callouts', () => { |
| 69 | expect(violations(group('<PackageInstall ecosystem="python" packages="composio" />', fence('bash', 'npm install @composio/core'), null))).toEqual([]); |
| 70 | expect(violations(group('<Callout>Use the API: this SDK does not implement this operation.</Callout>'))).toEqual([]); |
| 71 | expect(violations(group('<Callout />')).map((item) => item.rule)).toContain('language-empty-tab'); |
| 72 | }); |
| 73 | |
| 74 | test('requires counterparts for SDK-only and API-only operations', () => { |
| 75 | expect(violations(python).map((item) => item.rule)).toEqual(['standalone-sdk-fence']); |
| 76 | expect(violations(api).map((item) => item.rule)).toEqual(['standalone-api-fence']); |
| 77 | const sdkOnly = `<Tabs groupId="language" items={['Python', 'TypeScript']}>\n${tab('Python', python)}\n${tab('TypeScript', typescript)}\n</Tabs>`; |
| 78 | expect(violations(sdkOnly).map((item) => item.rule)).toEqual(['api-missing']); |
| 79 | const versioned = sdkOnly.replaceAll('Python', 'Python (current)').replaceAll('TypeScript', 'TypeScript (current)'); |
| 80 | expect(violations(versioned).map((item) => item.rule)).toEqual(['api-missing']); |
| 81 | expect(violations(`{/* code-example: no-api reason="local schema modifiers have no HTTP operation" */}\n${sdkOnly}`)).toEqual([]); |
| 82 | }); |
| 83 | |
| 84 | test('rejects misplaced, malformed, and unscoped API exceptions', () => { |
| 85 | expect(violations(`{/* code-example: single-language reason="local Python helper" */}\nProse.\n${python}`).map((item) => item.rule)).toContain('marker-invalid'); |
| 86 | expect(violations(`{/* code-example: single-language reason="" */}\n${python}`).map((item) => item.rule)).toContain('marker-invalid'); |
| 87 | expect(violations(`{/* code-example: unchecked-api reason="old spec" */}\n${api}`).map((item) => item.rule)).toContain('marker-invalid'); |
| 88 | }); |
| 89 | }); |
| 90 | |
| 91 | describe('Markdown options and agent output', () => { |
| 92 | const source = `## Question\n\nIntro.\n\n### Python\n\n${python}\n\n### TypeScript\n\n${typescript}\n\n### API\n\n${api}\n\n## Next question\n\nOther answer.`; |
| 93 | |
| 94 | test('plain Markdown exposes checked options and FAQ HTML for all three variants', () => { |
| 95 | expect(violations(source, 'faq.md')).toEqual([]); |
| 96 | const faq = parseToolkitFaq(source); |
| 97 | const options = faq[0].answer.find((part) => part.type === 'languages'); |
| 98 | expect(options?.type === 'languages' && options.tabs.map((item) => item.value)).toEqual(['Python', 'TypeScript', 'API']); |
| 99 | expect(options?.type === 'languages' && options.tabs.every((item) => item.html.includes('<code'))).toBe(true); |
| 100 | expect(faq[1].question).toBe('Next question'); |
| 101 | }); |
| 102 | |
| 103 | test('end-languages keeps shared prose after the group visible for every option', () => { |
| 104 | const shared = source.replace('\n\n## Next question', '\n\n<!-- end-languages -->\n\nShared follow-up.\n\n## Next question'); |
| 105 | expect(violations(shared, 'faq.md')).toEqual([]); |
| 106 | const [options, after] = parseToolkitFaq(shared)[0].answer.slice(1); |
| 107 | expect(options.type === 'languages' && options.tabs.some((item) => item.html.includes('Shared follow-up'))).toBe(false); |
| 108 | expect(after).toEqual({ type: 'html', html: '<p>Shared follow-up.</p>' }); |
| 109 | }); |
| 110 | |
| 111 | test('a Markdown group exception cannot exempt the following operation', () => { |
| 112 | const pair = `### Python\n\n${python}\n\n### TypeScript\n\n${typescript}\n`; |
| 113 | const local = `<!-- code-example: no-api reason="local schema transformation" -->\n${pair}\n## Remote operation\n\n${pair}`; |
| 114 | const missing = violations(local, 'faq.md'); |
| 115 | expect(missing.map((item) => item.rule)).toEqual(['api-missing']); |
| 116 | expect(missing[0].line).toBe(local.split('\n').findLastIndex((line) => line === '### Python') + 1); |
| 117 | expect(violations(source.replace(python, '> [!NOTE]\n> This SDK has no endpoint for this operation.'), 'faq.md')).toEqual([]); |
| 118 | }); |
| 119 | |
| 120 | test('preserves nested labels and code literals in agent Markdown', () => { |
| 121 | const nested = `<Tabs items={['Bearer']}>\n${tab('Bearer', group())}\n</Tabs>`; |
| 122 | const markdown = componentsToMarkdown(nested); |
| 123 | for (const label of ['Bearer', 'Python', 'TypeScript', 'API']) expect(markdown).toContain(`**${label}:**`); |
| 124 | const literal = fence('mdx', '<Tab value="do not rewrite">example</Tab>'); |
| 125 | expect(componentsToMarkdown(literal)).toBe(literal); |
| 126 | }); |
| 127 | |
| 128 | test('a card without a description cannot swallow later examples from agent Markdown', () => { |
| 129 | const page = [ |
| 130 | '<Cards>', |
| 131 | ' <Card title="Guide" href="/docs/guide">', |
| 132 | ' Read the guide.', |
| 133 | ' </Card>', |
| 134 | '</Cards>', |
| 135 | '', |
| 136 | group(), |
| 137 | '', |
| 138 | '<Card icon={<span />} title="Next" href="/docs/next" description="Continue here" />', |
| 139 | ].join('\n'); |
| 140 | const markdown = mdxToCleanMarkdown(page); |
| 141 | expect(markdown).toContain('- [Guide](/docs/guide): Read the guide.'); |
| 142 | expect(markdown).toContain('- [Next](/docs/next): Continue here'); |
| 143 | for (const label of ['Python', 'TypeScript', 'API']) expect(markdown).toContain(`**${label}:**`); |
| 144 | for (const language of ['python', 'typescript', 'bash']) expect(markdown).toContain(`\`\`\`${language}`); |
| 145 | expect(markdown).not.toContain('<Card'); |
| 146 | }); |
| 147 | |
| 148 | test('source line reporting survives Markdown grouping', () => { |
| 149 | const entries: number[] = []; |
| 150 | walkCodeExamples(parseCodeExamples(source, 'faq.md').units, (unit) => { if (unit.type === 'fence') entries.push(unit.line); }); |
| 151 | expect(entries).toEqual(source.split('\n').flatMap((line, index) => line.startsWith('```') && line !== '```' ? [index + 1] : [])); |
| 152 | }); |
| 153 | }); |
| 154 | |
| 155 | describe('maintained and rendered surfaces', () => { |
| 156 | test('all maintained sources follow the option contract', () => { |
| 157 | const files = listCodeExampleFiles(root); |
| 158 | expect(files.some((file) => file.path.startsWith('kb/source/'))).toBe(true); |
| 159 | expect(files.some((file) => file.path.startsWith('kb/articles/'))).toBe(true); |
| 160 | expect(checkCodeExamples(files, { requireApi: true })).toEqual([]); |
| 161 | }); |
| 162 | |
| 163 | test('inventory includes generated, historical, and component-backed code with explicit reasons', () => { |
| 164 | const inventory = inventoryCodeExamples(root); |
| 165 | for (const validation of ['generated-copy', 'symbol-reference', 'historical', 'framework-source']) { |
| 166 | const entries = inventory.filter((entry) => entry.validation === validation); |
| 167 | expect(entries.map((entry) => entry.validation)).toContain(validation); |
| 168 | expect(entries.every((entry) => Boolean(entry.reason))).toBe(true); |
| 169 | } |
| 170 | expect(inventory.some((entry) => entry.kind === 'FileBuildup source')).toBe(true); |
| 171 | expect(inventory.some((entry) => entry.kind === 'RepoBrowser source')).toBe(true); |
| 172 | expect(inventory.some((entry) => entry.kind === 'generated API operation' && entry.path.includes('/api/v3.1/tools/get'))).toBe(true); |
| 173 | }); |
| 174 | }); |