Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
ts 174 lines 10.8 KB
Raw
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 });