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 325 lines 12.4 KB
Raw
1 /**
2 * API reference route guards.
3 *
4 * Up to 11.3, fumadocs-openapi's tag grouping silently dropped any operation
5 * whose tag was not declared in the document's top-level `tags` array
6 * (preset-auto: `builder.fromTagName(tag)` returned undefined -> `continue`,
7 * no warning). The v10 -> v11 upgrade shipped exactly that: 16 operation pages
8 * vanished from the site, sitemap, and search while the checked-in tag landing
9 * pages kept rendering quick links that 404ed. 11.4 fixed the drop, so these
10 * guards now stand as regression tripwires — the loss has already reappeared
11 * once, on a routine upgrade. Nothing else can catch this class:
12 * validate-links only sees markdown links (ApiEndpointsTable hrefs live in a
13 * JSX prop), and the integration suite samples fixed routes.
14 *
15 * Two guards, both derived from the shipped specs rather than snapshots so
16 * routine spec syncs (docs-update-data) never churn them:
17 * 1. Completeness — every operation/webhook a spec implies maps 1:1 to a page
18 * the production loader path actually generates, regardless of the drop
19 * mechanism.
20 * 2. Quick links — every href serialized into an ApiEndpointsTable in
21 * content/reference resolves to a generated page.
22 */
23 import { describe, expect, test } from 'bun:test';
24 import { readFileSync, readdirSync } from 'node:fs';
25 import { join, relative } from 'node:path';
26 import { loader, multiple } from 'fumadocs-core/source';
27 import { createOpenAPI, openapiSource } from 'fumadocs-openapi/server';
28 import { z } from 'zod';
29
30 import { openapi, openapiV3 } from '../../lib/openapi';
31 import { apiEndpointsSchema } from '../../lib/api-endpoints-table-schema';
32 import { HIDDEN_API_TAGS } from '../../lib/filter-api-version';
33 import { getReferenceSource } from '../../lib/source';
34
35 const DOCS_DIR = join(import.meta.dir, '../..');
36
37 const HTTP_METHODS = [
38 'get',
39 'put',
40 'post',
41 'delete',
42 'options',
43 'head',
44 'patch',
45 'trace',
46 ] as const;
47
48 interface SpecOperation {
49 operationId?: string;
50 tags?: string[];
51 }
52
53 interface SpecDocument {
54 paths?: Record<string, Record<string, unknown>>;
55 webhooks?: Record<string, Record<string, unknown>>;
56 }
57
58 /** Mirrors the default slugify in fumadocs-openapi's auto preset. */
59 function slugifyTag(tag: string): string {
60 return tag.replace(/\s+/g, '-').toLowerCase();
61 }
62
63 /** Mirrors the hidden-tag URL filter applied in lib/source.ts. */
64 function isHiddenReferenceUrl(url: string): boolean {
65 for (const tag of HIDDEN_API_TAGS) {
66 if (
67 url.startsWith(`/reference/api-reference/${tag}/`) ||
68 url.startsWith(`/reference/v3/api-reference/${tag}/`)
69 ) {
70 return true;
71 }
72 }
73 return false;
74 }
75
76 function* specOperations(document: SpecDocument): Generator<{
77 location: string;
78 operation: SpecOperation;
79 }> {
80 for (const group of [document.paths, document.webhooks]) {
81 for (const [key, pathItem] of Object.entries(group ?? {})) {
82 for (const method of HTTP_METHODS) {
83 const operation = pathItem?.[method];
84 if (!operation || typeof operation !== 'object') continue;
85 yield { location: `${method.toUpperCase()} ${key}`, operation };
86 }
87 }
88 }
89 }
90
91 /**
92 * URLs the spec implies: one page per visible (operation, tag) pair, named by
93 * operationId — the scheme both fumadocs-openapi (groupBy: 'tag', name
94 * algorithm v2) and generate-api-index.ts encode.
95 */
96 function expectedReferenceUrls(document: SpecDocument, baseDir: string): Set<string> {
97 const urls = new Set<string>();
98 for (const { operation } of specOperations(document)) {
99 for (const tag of operation.tags ?? []) {
100 const tagSlug = slugifyTag(tag);
101 if (HIDDEN_API_TAGS.has(tagSlug)) continue;
102 urls.add(`/reference/${baseDir}/${tagSlug}/${operation.operationId}`);
103 }
104 }
105 return urls;
106 }
107
108 function loadSpec(fileName: string): SpecDocument {
109 return JSON.parse(readFileSync(join(DOCS_DIR, 'public', fileName), 'utf-8'));
110 }
111
112 /**
113 * The reference URLs production actually serves, built through the same
114 * pipeline as lib/source.ts getReferenceSource (minus the checked-in MDX
115 * collection, which bun test cannot load and which contributes no operation
116 * pages).
117 */
118 async function generatedReferenceUrls(): Promise<Set<string>> {
119 const [latest, v3] = await Promise.all([
120 openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
121 openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
122 ]);
123 const referenceLoader = loader({
124 baseUrl: '/reference',
125 source: multiple({ openapi: latest, 'openapi-v3': v3 }),
126 });
127 return new Set(
128 referenceLoader
129 .getPages()
130 .map((page) => page.url)
131 .filter((url) => !isHiddenReferenceUrl(url)),
132 );
133 }
134
135 const generatedUrlsPromise = generatedReferenceUrls();
136
137 describe('API reference route completeness', () => {
138 test('sidebar operations follow read, create, update, delete order', async () => {
139 const source = await getReferenceSource();
140 const operationIds = source.pageTree.children
141 .flatMap(function pages(node): string[] {
142 if (node.type === 'page') return [node.url];
143 if (node.type === 'folder') return node.children.flatMap(pages);
144 return [];
145 })
146 .filter(url => url.startsWith('/reference/api-reference/auth-configs/'))
147 .map(url => url.slice(url.lastIndexOf('/') + 1));
148
149 expect(operationIds).toEqual([
150 'getAuthConfigs',
151 'getAuthConfigsByNanoid',
152 'postAuthConfigs',
153 'patchAuthConfigsByNanoid',
154 'patchAuthConfigsByNanoidByStatus',
155 'deleteAuthConfigsByNanoid',
156 ]);
157 });
158
159 test('every visible operation declares a tag and an operationId', () => {
160 const violations: string[] = [];
161 for (const fileName of ['openapi.json', 'openapi-v3.json', 'openapi-webhooks.json']) {
162 for (const { location, operation } of specOperations(loadSpec(fileName))) {
163 const visibleTags = (operation.tags ?? []).filter(
164 (tag) => !HIDDEN_API_TAGS.has(slugifyTag(tag)),
165 );
166 // Untagged operations fall into fumadocs' synthetic "unknown" tag,
167 // which is never declared — the page silently vanishes.
168 if ((operation.tags ?? []).length === 0) {
169 violations.push(`${fileName}: ${location} has no tags`);
170 }
171 // Without an operationId, fumadocs falls back to a path-derived file
172 // name while generate-api-index derives the href from the summary —
173 // the quick link is guaranteed to 404.
174 if (visibleTags.length > 0 && !operation.operationId) {
175 violations.push(`${fileName}: ${location} has no operationId`);
176 }
177 }
178 }
179
180 expect(violations, violations.join('\n')).toEqual([]);
181 });
182
183 test('every spec operation and webhook yields exactly one generated page', async () => {
184 const expected = new Set<string>([
185 ...expectedReferenceUrls(loadSpec('openapi.json'), 'api-reference'),
186 ...expectedReferenceUrls(loadSpec('openapi-webhooks.json'), 'api-reference'),
187 ...expectedReferenceUrls(loadSpec('openapi-v3.json'), 'v3/api-reference'),
188 ]);
189 const generated = await generatedUrlsPromise;
190
191 const missing = [...expected].filter((url) => !generated.has(url)).sort();
192 const extra = [...generated].filter((url) => !expected.has(url)).sort();
193
194 expect(expected.size).toBeGreaterThan(0);
195 expect(
196 missing,
197 `pages implied by the OpenAPI specs but not generated (silently dropped):\n${missing.join('\n')}`,
198 ).toEqual([]);
199 expect(
200 extra,
201 `generated pages not implied by the OpenAPI specs:\n${extra.join('\n')}`,
202 ).toEqual([]);
203 });
204
205 test('operations whose tag is undeclared are no longer dropped', async () => {
206 // The exact v10 -> v11 regression, in miniature: "Projects" is used by an
207 // operation but missing from the top-level tags array, and lib/openapi's
208 // declareOperationTags normalization is deliberately not applied.
209 // fumadocs-openapi 11.4 generates the page anyway, so this fixture now
210 // asserts the fix rather than the loss.
211 const document = {
212 openapi: '3.0.0',
213 info: { title: 'Guard fixture', version: '1' },
214 tags: [{ name: 'Auth' }],
215 paths: {
216 '/v3.1/project/usage/summary': {
217 post: {
218 tags: ['Projects'],
219 operationId: 'postProjectUsageSummary',
220 summary: 'Usage summary',
221 responses: { '200': { description: 'ok' } },
222 },
223 },
224 '/v3.1/auth/session': {
225 get: {
226 tags: ['Auth'],
227 operationId: 'getSession',
228 summary: 'Session',
229 responses: { '200': { description: 'ok' } },
230 },
231 },
232 },
233 };
234
235 const server = createOpenAPI({ input: { 'guard-fixture.json': document } });
236 const source = await openapiSource(server, { groupBy: 'tag', baseDir: 'api-reference' });
237 const generated = new Set(
238 loader({ baseUrl: '/reference', source }).getPages().map((page) => page.url),
239 );
240 const missing = [...expectedReferenceUrls(document, 'api-reference')].filter(
241 (url) => !generated.has(url),
242 );
243
244 expect(generated.has('/reference/api-reference/auth/getSession')).toBe(true);
245 // Upstream fixed the silent drop, so the undeclared-tag operation now gets
246 // a page without help from declareOperationTags. That normalization is kept
247 // as a safety net for older fumadocs-openapi behaviour; if this ever fails
248 // with `missing` non-empty again, the drop has regressed upstream. The
249 // positive check guards against `missing` being vacuously empty because
250 // expectedReferenceUrls stopped yielding the projects URL.
251 expect(generated.has('/reference/api-reference/projects/postProjectUsageSummary')).toBe(true);
252 expect(missing).toEqual([]);
253 });
254 });
255
256 describe('API reference quick links', () => {
257 function mdxFiles(dir: string): string[] {
258 const files: string[] = [];
259 for (const entry of readdirSync(dir, { withFileTypes: true })) {
260 const fullPath = join(dir, entry.name);
261 if (entry.isDirectory()) files.push(...mdxFiles(fullPath));
262 else if (entry.name.endsWith('.mdx')) files.push(fullPath);
263 }
264 return files;
265 }
266
267 /**
268 * Parses the serialized endpoints of every ApiEndpointsTable in a file.
269 *
270 * Validated through the same schema the runtime uses, not a bare
271 * JSON.parse: `mdxToCleanMarkdown` degrades a malformed payload to an empty
272 * table so one bad page cannot 500 the whole .md response, which means a
273 * structurally broken committed payload would otherwise render nothing with
274 * no failure signal anywhere. This is that signal.
275 */
276 function parseEndpointHrefs(content: string, file: string): string[] {
277 const hrefs: string[] = [];
278 const prefix = /<ApiEndpointsTable endpoints=\{/g;
279 let match: RegExpExecArray | null;
280 while ((match = prefix.exec(content)) !== null) {
281 const start = match.index + match[0].length;
282 const end = content.indexOf('} />', start);
283 expect(end, `${file}: unterminated ApiEndpointsTable`).toBeGreaterThan(start);
284 const parsed = apiEndpointsSchema.safeParse(JSON.parse(content.slice(start, end)));
285 expect(
286 parsed.success,
287 `${file}: ApiEndpointsTable payload fails apiEndpointsSchema:\n${
288 parsed.success ? '' : z.prettifyError(parsed.error)
289 }`,
290 ).toBe(true);
291 if (!parsed.success) continue;
292 hrefs.push(...parsed.data.map((endpoint) => endpoint.href));
293 }
294 // A file mentioning the component but yielding no parsed table means the
295 // generator's serialization drifted from this extractor — fail loudly
296 // instead of silently checking nothing.
297 if (content.includes('<ApiEndpointsTable')) {
298 expect(hrefs.length, `${file}: found ApiEndpointsTable but extracted no hrefs`).toBeGreaterThan(0);
299 }
300 return hrefs;
301 }
302
303 test('every ApiEndpointsTable href resolves to a generated reference page', async () => {
304 const generated = await generatedUrlsPromise;
305 const dead: string[] = [];
306 let totalHrefs = 0;
307
308 for (const file of mdxFiles(join(DOCS_DIR, 'content/reference'))) {
309 const content = readFileSync(file, 'utf-8');
310 for (const href of parseEndpointHrefs(content, relative(DOCS_DIR, file))) {
311 totalHrefs++;
312 if (!generated.has(href)) {
313 dead.push(`${relative(DOCS_DIR, file)}: ${href}`);
314 }
315 }
316 }
317
318 // Sanity: the extractor must have found the generated landing pages.
319 expect(totalHrefs).toBeGreaterThan(0);
320 expect(
321 dead,
322 `quick links pointing at reference pages that are never generated (would 404):\n${dead.join('\n')}`,
323 ).toEqual([]);
324 });
325 });