1
+/**
2
+ * API version identity in the markdown channels.
3
+ *
4
+ * Agents read `.md`, not the browser rendering path. Every signal that
5
+ * separates v3.1 from v3.0 used to live in client components the markdown
6
+ * converter dropped, so `reference.md` published an empty `Base URL` bullet
7
+ * and the tag pages published an empty `Endpoints` section — while the
8
+ * superseded v3.0 operation pages published a complete working curl example.
9
+ *
10
+ * These tests lock the three properties that fix costs the most to lose:
11
+ * 1. `mdxToCleanMarkdown` renders `ApiBaseUrl` and `ApiEndpointsTable` at the
12
+ * version the page URL implies, and degrades (no table, no throw) on a
13
+ * malformed payload rather than 500ing the whole `.md` response.
14
+ * 2. `getLLMText` emits a version pointer on `/reference/**` and nowhere else.
15
+ * 3. The guidance text is single-sourced in `lib/api-version-guidance.ts` —
16
+ * asserted by containment of the exported constant, not by matching a
17
+ * copied literal, which is what proves the guardrail files compose rather
18
+ * than restate.
19
+ */
20
+import { describe, expect, test } from 'bun:test';
21
+
22
+import {
23
+ REST_VERSION_GUIDANCE,
24
+ TOOL_VERSION_GUIDANCE,
25
+ TOOL_VERSION_PATHS,
26
+ apiVersionPointer,
27
+ isToolVersionPath,
28
+} from '../../lib/api-version-guidance';
29
+import { detectReferenceApiVersion, toCurrentVersionUrl } from '../../lib/api-version';
30
+import {
31
+ getLLMText,
32
+ getReferenceSource,
33
+ mdxToCleanMarkdown,
34
+ type LLMPage,
35
+} from '../../lib/source';
36
+import { DIRECT_EXECUTION_GUARDRAILS, SESSION_GUARDRAILS } from '../../lib/llm-guardrails';
37
+
38
+const V31_BASE = 'https://backend.composio.dev/api/v3.1';
39
+const V30_BASE = 'https://backend.composio.dev/api/v3';
40
+
41
+/** A current-tree tag page and its legacy twin. */
42
+const CURRENT_URL = '/reference/api-reference/tools';
43
+const LEGACY_URL = '/reference/v3/api-reference/tools';
44
+
45
+/** The authored MDX shape, which `lib/search-index.ts` reads from the file. */
46
+function endpointsTable(endpoints: unknown[]): string {
47
+ return `## Endpoints\n\n<ApiEndpointsTable endpoints={${JSON.stringify(endpoints)}} />\n`;
48
+}
49
+
50
+/**
51
+ * The shape `getLLMText` actually receives: fumadocs' processed markdown
52
+ * re-serializes the JSX expression attribute as a quoted string with the inner
53
+ * quotes entity-escaped. Matching only the authored shape above still passes a
54
+ * unit test while leaving every live tag page's Endpoints section empty, which
55
+ * is exactly the defect this work exists to fix — so the production shape gets
56
+ * its own fixture.
57
+ */
58
+function processedEndpointsTable(endpoints: unknown[]): string {
59
+ const escaped = JSON.stringify(endpoints).replace(/"/g, '"');
60
+ return `## Endpoints\n\n<ApiEndpointsTable endpoints="${escaped}" />\n`;
61
+}
62
+
63
+const TOOLS_ENDPOINT = {
64
+ method: 'GET',
65
+ pathV31: '/api/v3.1/tools',
66
+ pathV3: '/api/v3/tools',
67
+ summary: 'List tools',
68
+ href: '/reference/api-reference/tools/getTools',
69
+};
70
+
71
+function llmPage(url: string, content: string, data: Partial<LLMPage['data']> = {}): LLMPage {
72
+ return {
73
+ url,
74
+ data: { title: 'Tools', getText: async () => content, ...data },
75
+ };
76
+}
77
+
78
+describe('mdxToCleanMarkdown — ApiBaseUrl', () => {
79
+ test('renders the v3.1 base URL on a current-tree URL', () => {
80
+ expect(mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />', CURRENT_URL)).toContain(V31_BASE);
81
+ });
82
+
83
+ test('renders the v3 base URL on a legacy-tree URL', () => {
84
+ const markdown = mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />', LEGACY_URL);
85
+ expect(markdown).toContain(`\`${V30_BASE}\``);
86
+ expect(markdown).not.toContain(V31_BASE);
87
+ });
88
+
89
+ test('renders the v3.1 base URL with no url argument — the changelog call site', () => {
90
+ expect(mdxToCleanMarkdown('**Base URL**: <ApiBaseUrl />')).toContain(V31_BASE);
91
+ });
92
+});
93
+
94
+describe('mdxToCleanMarkdown — ApiEndpointsTable', () => {
95
+ test('emits one row per endpoint using pathV31 on a current-tree URL', () => {
96
+ const markdown = mdxToCleanMarkdown(
97
+ endpointsTable([
98
+ TOOLS_ENDPOINT,
99
+ {
100
+ method: 'POST',
101
+ pathV31: '/api/v3.1/tools/execute/{tool_slug}',
102
+ pathV3: '/api/v3/tools/execute/{tool_slug}',
103
+ summary: 'Execute a tool',
104
+ href: '/reference/api-reference/tools/executeTool',
105
+ },
106
+ ]),
107
+ CURRENT_URL
108
+ );
109
+
110
+ expect(markdown).toContain('/api/v3.1/tools');
111
+ expect(markdown).toContain('/api/v3.1/tools/execute/{tool_slug}');
112
+ expect(markdown).not.toContain('/api/v3/tools');
113
+ // href kept as a relative link, summary preserved
114
+ expect(markdown).toContain('[List tools](/reference/api-reference/tools/getTools)');
115
+ expect(markdown).toContain('[Execute a tool](/reference/api-reference/tools/executeTool)');
116
+ });
117
+
118
+ test('renders the processed-markdown shape getLLMText actually receives', () => {
119
+ const markdown = mdxToCleanMarkdown(
120
+ processedEndpointsTable([
121
+ TOOLS_ENDPOINT,
122
+ {
123
+ method: 'GET',
124
+ pathV31: '/api/v3.1/tools/{tool_slug}',
125
+ pathV3: '/api/v3/tools/{tool_slug}',
126
+ summary: 'Get tool by slug',
127
+ href: '/reference/api-reference/tools/getToolsByToolSlug',
128
+ },
129
+ ]),
130
+ CURRENT_URL
131
+ );
132
+
133
+ expect(markdown).toContain('[List tools](/reference/api-reference/tools/getTools)');
134
+ expect(markdown).toContain('`/api/v3.1/tools/{tool_slug}`');
135
+ // The escaping must actually be reversed, not carried through.
136
+ expect(markdown).not.toContain('"');
137
+ });
138
+
139
+ test('uses pathV3 on a legacy-tree URL', () => {
140
+ const markdown = mdxToCleanMarkdown(endpointsTable([TOOLS_ENDPOINT]), LEGACY_URL);
141
+ expect(markdown).toContain('`/api/v3/tools`');
142
+ expect(markdown).not.toContain('/api/v3.1/tools');
143
+ });
144
+
145
+ test('renders a visible legacy marker for a deprecated endpoint', () => {
146
+ const markdown = mdxToCleanMarkdown(
147
+ endpointsTable([{ ...TOOLS_ENDPOINT, legacy: true }]),
148
+ CURRENT_URL
149
+ );
150
+ expect(markdown).toContain('Legacy');
151
+ });
152
+
153
+ test('preserves backslashes and pipes in endpoint summaries', () => {
154
+ const markdown = mdxToCleanMarkdown(
155
+ endpointsTable([{ ...TOOLS_ENDPOINT, summary: String.raw`Path \| pipe` }]),
156
+ CURRENT_URL
157
+ );
158
+
159
+ expect(markdown).toContain(String.raw`[Path \\\| pipe]`);
160
+ });
161
+
162
+ test('emits no table and does not throw on a truncated payload', () => {
163
+ const content = 'Surrounding prose.\n\n<ApiEndpointsTable endpoints={[{"method":"GET"} />\n';
164
+ const markdown = mdxToCleanMarkdown(content, CURRENT_URL);
165
+ // The rest of the page survives — one bad table must not take the whole
166
+ // .md response down.
167
+ expect(markdown).toContain('Surrounding prose.');
168
+ expect(markdown).not.toContain('| Method |');
169
+ });
170
+
171
+ test('emits no table on a structurally invalid payload a bare JSON.parse would accept', () => {
172
+ // Valid JSON, pathV31 missing.
173
+ const markdown = mdxToCleanMarkdown(
174
+ `Surrounding prose.\n\n${endpointsTable([
175
+ { method: 'GET', pathV3: '/api/v3/tools', summary: 'List tools', href: '/x' },
176
+ ])}`,
177
+ CURRENT_URL
178
+ );
179
+ expect(markdown).toContain('Surrounding prose.');
180
+ expect(markdown).not.toContain('| Method |');
181
+ expect(markdown).not.toContain('List tools');
182
+ });
183
+});
184
+
185
+describe('getLLMText — version pointer', () => {
186
+ test('a current /reference/** page carries the v3.1 pointer and base URL', async () => {
187
+ const text = await getLLMText(llmPage(CURRENT_URL, '# Tools'), { includeGuardrails: false });
188
+ expect(text).toContain('**API version:**');
189
+ expect(text).toContain(V31_BASE);
190
+ });
191
+
192
+ test('a legacy /reference/v3/** page carries the v3.0 pointer and links its v3.1 page', async () => {
193
+ const text = await getLLMText(llmPage(LEGACY_URL, '# Tools'), { includeGuardrails: false });
194
+ expect(text).toContain('**API version:**');
195
+ expect(text).toContain('v3.0');
196
+ expect(text).toContain(V31_BASE);
197
+ expect(text).toContain('/reference/api-reference/tools.md');
198
+ expect(text).not.toContain('https://docs.composio.dev/reference/api-reference/tools.md');
199
+ });
200
+
201
+ test('a /docs/** page gets no API version pointer — the pointer is reference-scoped', async () => {
202
+ const text = await getLLMText(llmPage('/docs/quickstart', '# Quickstart'));
203
+ expect(text).not.toContain('**API version:**');
204
+ });
205
+
206
+ test('an SDK reference page gets no REST version pointer', async () => {
207
+ const text = await getLLMText(
208
+ llmPage('/reference/sdk-reference/typescript/tools', '# Tools')
209
+ );
210
+ expect(text).not.toContain('**API version:**');
211
+ });
212
+
213
+ test('the glossary gets no REST version pointer', async () => {
214
+ const text = await getLLMText(llmPage('/reference/glossary', '# Glossary'));
215
+ expect(text).not.toContain('**API version:**');
216
+ });
217
+
218
+ test('the legacy authentication page links to its renamed current counterpart', async () => {
219
+ const text = await getLLMText(
220
+ llmPage('/reference/v3/authentication', '# Authentication'),
221
+ { includeGuardrails: false }
222
+ );
223
+ expect(text).toContain('/reference/authenticating-to-composio.md');
224
+ });
225
+
226
+ test('every published legacy page links to an existing current-version page', async () => {
227
+ const reference = await getReferenceSource();
228
+ const routes = new Set(reference.getPages().map(page => page.url));
229
+ const legacyRoutes = [...routes].filter(
230
+ url => detectReferenceApiVersion(url) === '3.0'
231
+ );
232
+ const invalidPointers = legacyRoutes.flatMap(source => {
233
+ const target = toCurrentVersionUrl(source);
234
+ const pointer = apiVersionPointer(source);
235
+ return routes.has(target) &&
236
+ detectReferenceApiVersion(target) === '3.1' &&
237
+ pointer.includes(`${target}.md`)
238
+ ? []
239
+ : [`${source} -> ${target}`];
240
+ });
241
+
242
+ expect(legacyRoutes.some(url => /^\/reference\/v3\/[^/]+$/.test(url))).toBe(true);
243
+ expect(
244
+ legacyRoutes.some(url => /^\/reference\/v3\/api-reference\/[^/]+$/.test(url))
245
+ ).toBe(true);
246
+ expect(
247
+ legacyRoutes.some(url => /^\/reference\/v3\/api-reference\/[^/]+\/[^/]+$/.test(url))
248
+ ).toBe(true);
249
+ expect(
250
+ invalidPointers,
251
+ `invalid current-version pointers:\n${invalidPointers.join('\n')}`
252
+ ).toEqual([]);
253
+ });
254
+
255
+ test('a legacy: true page keeps its legacy note and still emits no guardrails', async () => {
256
+ const text = await getLLMText(
257
+ llmPage('/docs/tools-direct/executing-tools', '# Executing tools', { legacy: true })
258
+ );
259
+ expect(text).toContain('**Legacy');
260
+ // legacy: true gates the whole guardrail block at source.ts, before the
261
+ // llmGuardrails selector ever runs. Deliberate: appending "enforce the
262
+ // CURRENT patterns" to a point-in-time migration guide contradicts it.
263
+ expect(text).not.toContain('Instructions for AI Code Generators');
264
+ });
265
+});
266
+
267
+describe('detectReferenceApiVersion', () => {
268
+ test.each([
269
+ ['/reference/api-reference/tools', '3.1'],
270
+ ['/reference/v3/api-reference/tools', '3.0'],
271
+ ['/reference/glossary', null],
272
+ ['/reference/sdk-reference', null],
273
+ ['/reference/sdk-reference/typescript/tools', null],
274
+ ] as const)('%s is classified as %s', (url, expected) => {
275
+ expect(detectReferenceApiVersion(url)).toBe(expected);
276
+ });
277
+});
278
+
279
+describe('guardrail sets compose the guidance rather than restating it', () => {
280
+ // Containment of the exported constant, not a substring of prose. A test
281
+ // matching a copied literal would pass just as happily against two strings
282
+ // that currently agree and are free to drift.
283
+ test.each([
284
+ ['SESSION_GUARDRAILS', SESSION_GUARDRAILS],
285
+ ['DIRECT_EXECUTION_GUARDRAILS', DIRECT_EXECUTION_GUARDRAILS],
286
+ ])('%s contains both guidance constants verbatim', (_name, guardrails) => {
287
+ expect(guardrails).toContain(REST_VERSION_GUIDANCE);
288
+ expect(guardrails).toContain(TOOL_VERSION_GUIDANCE);
289
+ });
290
+});
291
+
292
+describe('API version guidance constants', () => {
293
+ test('the REST baseline names v3.1 without claiming route parity', () => {
294
+ expect(REST_VERSION_GUIDANCE).toContain('https://backend.composio.dev/api/v3.1');
295
+ expect(TOOL_VERSION_GUIDANCE).toContain(
296
+ 'This version-default change is limited to the five endpoints above.'
297
+ );
298
+ expect(TOOL_VERSION_GUIDANCE).not.toMatch(/every non-tool endpoint.*unchanged/i);
299
+ });
300
+
301
+ test('exactly five tool paths need explicit version-default guidance', () => {
302
+ expect(TOOL_VERSION_PATHS).toHaveLength(5);
303
+ });
304
+});
305
+
306
+describe('isToolVersionPath normalization contract', () => {
307
+ // Every key below appears verbatim in a committed spec. The predicate takes
308
+ // the raw spec path key; no caller pre-strips anything.
309
+ const cases: Array<[path: string, expected: boolean, why: string]> = [
310
+ ['/api/v3.1/tools', true, ''],
311
+ ['/api/v3.1/tools/{tool_slug}', true, 'fails if /api/v3 is stripped before /api/v3.1'],
312
+ ['/api/v3.1/tools/execute/{tool_slug}', true, ''],
313
+ ['/api/v3.1/tools/execute/{tool_slug}/input', true, ''],
314
+ ['/api/v3.1/tools/scopes/required', true, 'v3.1-only; has no v3 counterpart'],
315
+ ['/api/v3/tools', true, ''],
316
+ ['/api/v3/tools/{tool_slug}', true, ''],
317
+ ['/api/v3/tools/execute/{tool_slug}', true, ''],
318
+ ['/api/v3/tools/execute/{tool_slug}/input', true, ''],
319
+ ['/api/v3.1/tools/enum', false, 'under /tools, not affected — breaks a prefix match'],
320
+ ['/api/v3.1/tools/execute/proxy', false, 'under /tools/execute, not affected'],
321
+ [
322
+ '/api/v3.1/tool_router/session/{session_id}/tools',
323
+ false,
324
+ 'ends in /tools — breaks a substring match',
325
+ ],
326
+ ['/api/v3.1/auth_configs', false, 'plain non-tool'],
327
+ ['/api/v3.1/triggers_types', false, 'triggers already default to latest'],
328
+ ['/tools/{tool_slug}', false, 'no version prefix; the predicate normalizes, it does not guess'],
329
+ ];
330
+
331
+ for (const [path, expected, why] of cases) {
332
+ test(`${path} -> ${expected}${why ? ` (${why})` : ''}`, () => {
333
+ expect(isToolVersionPath(path)).toBe(expected);
334
+ });
335
+ }
336
+});