@devries-cameron20 / composio-1 / commits / 3335bb301
Fork 0

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

fix(docs): restore API reference pages dropped by undeclared tags (#3973)

This PR: - fixes a regression introduced by https://github.com/ComposioHQ/composio/pull/3956: fumadocs-openapi 11's `groupBy: 'tag'` silently skips operations whose tag is not declared in the document's top-level `tags` array, which 404'd all 16 Projects and Organization Management operation pages (e.g. `/reference/api-reference/projects/postProjectUsageSummary`) on both v3.1 and v3, and dropped them from the sitemap and search index - adds `declareOperationTags()` (`docs/lib/openapi-tags.ts`), applied at spec load time in `lib/openapi.ts` (covers build-time-fetched specs) and at sync time in `scripts/fetch-openapi.mjs`, which now also warns when the upstream payload omits tags; the checked-in specs are normalized accordingly (purely additive) - adds CI guards in `tests/static/api-reference-routes.test.ts`: spec invariants (every visible operation has a tag and `operationId`), bidirectional spec-vs-generated-routes set equality through the production loader path, a negative test pinning fumadocs' silent-drop behavior (fails when upstream fixes it, signaling the workaround can be retired), and validation that every `ApiEndpointsTable` quick-link href resolves to a generated page - extends `Docs - Check Links` with a nightly (02:30 UTC) + manual external-URL sweep via a new `lint:links:external` script; the validator only fails on evidence a link is dead (404/410 or repeated network errors, with UA/timeout/GET-fallback/retry and per-URL caching) and scheduled failures file a deduplicated tracking issue; PR runs keep the fast internal-only check - fixes six dead external links the first sweep found (moved Claude Agent SDK docs, stale dashboard settings URL ×2, a `master`-branch path now pinned to tag `0.5.0+post.1`, and two removed `ComposioHQ` example repos whose mentions were dropped — their code is embedded in the pages via `RepoBrowser`) ## Context fumadocs-openapi 10 generated a page for any tag string found on an operation; v11 requires the tag to be declared top-level and skips silently otherwise (`preset-auto.js`: `builder.fromTagName(tag)` → `continue`, no warning). The backend spec generator omits `Projects`, `Organization Management`, and `Invite Codes` from `tags`, so their operation pages vanished while the checked-in MDX tag landing pages kept rendering with dead quick links. With the normalizer, the generated URL set is byte-identical to the pre-#3956 set (234 routes, verified via `getReferenceSource().getPages()` diff); no revert needed. Existing checks missed this because `lint:links` only extracts markdown links and `Card` hrefs (the dead links live in `ApiEndpointsTable`'s array prop) and validates against the same loader that shrank, and the integration suite samples fixed routes under tags that survived. The new completeness guard derives expectations from the specs themselves, so routine data syncs don't churn it.

Alberto Schiabel committed Jul 29, 2026 at 03:05 UTC 3335bb30134f97b5e12a1c54d6daa821e0d8106e
20 files changed +662 -33
.github/workflows/docs-check-links.yml
+54 -1
@@ -8,6 +8,11 @@ on:
8 - '.github/workflows/docs-check-links.yml'
9 - 'mise.toml'
10 - 'mise.lock'
11 + schedule:
12 + # Nightly external-link sweep. HEAD/GET-checking every external URL is
13 + # slow and depends on third-party uptime, so it never runs on the PR path.
14 + - cron: '30 2 * * *'
15 + workflow_dispatch:
16
17 concurrency:
18 group: ${{ github.workflow }}-${{ github.event_name == 'pull_request' && github.ref || github.run_id }}
@@ -22,6 +27,9 @@ jobs:
27 defaults:
28 run:
29 working-directory: ./docs
30 + permissions:
31 + contents: read
32 + issues: write
33
34 steps:
35 - name: Checkout repository
@@ -41,5 +49,50 @@ jobs:
49 - name: Install dependencies
50 run: bun install
51
44 - - name: Validate links
52 + - name: Validate internal links
53 + if: github.event_name == 'pull_request'
54 run: bun run lint:links
55 +
56 + - name: Validate internal and external links
57 + if: github.event_name != 'pull_request'
58 + run: bun run lint:links:external
59 +
60 + # A red scheduled run is invisible unless someone watches the Actions
61 + # tab. File one tracking issue and leave it open until the cause is
62 + # fixed; PR runs skip this because their failures are already visible.
63 + - name: Open tracking issue on failure
64 + if: failure() && github.event_name != 'pull_request'
65 + continue-on-error: true
66 + # Override the job-level `./docs` default: that path only exists after
67 + # checkout, and a pre-checkout failure would otherwise leave the runner
68 + # unable to start this shell, silently losing the alert.
69 + working-directory: ${{ github.workspace }}
70 + env:
71 + GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
72 + GH_REPO: ${{ github.repository }}
73 + LABEL: docs-external-links-failure
74 + RUN_URL: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}
75 + EVENT_NAME: ${{ github.event_name }}
76 + run: |
77 + gh label create "$LABEL" \
78 + --color B60205 \
79 + --description "Nightly docs external-link check is failing" 2>/dev/null || true
80 +
81 + existing=$(gh issue list --label "$LABEL" --state open --limit 1 --json number --jq '.[0].number // empty')
82 + if [ -n "$existing" ]; then
83 + echo "Issue #$existing is already open for this failure; not filing a duplicate."
84 + exit 0
85 + fi
86 +
87 + gh issue create \
88 + --title "Nightly docs external-link check is failing" \
89 + --label "$LABEL" \
90 + --body "The scheduled \`Docs - Check Links\` external sweep failed.
91 +
92 + - Run: $RUN_URL
93 + - Trigger: \`$EVENT_NAME\`
94 +
95 + The failing URLs are listed in the run log. External links only fail on
96 + evidence they are dead (404/410, or repeated network errors), so this
97 + usually means a linked page moved or was taken down — fix or remove the
98 + link in \`docs/content\`."
docs/content/docs/migration-guide/new-sdk.mdx
+1 -1
@@ -1124,7 +1124,7 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
1124
1125 ### Local tools
1126
1127 -Previously, the Python SDK included *[local tools](https://github.com/ComposioHQ/composio/tree/master/python/composio/tools/local)*. These were tools defined within the SDK and consisted of local shell and code-related tools such as "clipboard", "sqltool", and "shelltool".
1127 +Previously, the Python SDK included *[local tools](https://github.com/ComposioHQ/composio/tree/0.5.0%2Bpost.1/python/composio/tools/local)*. These were tools defined within the SDK and consisted of local shell and code-related tools such as "clipboard", "sqltool", and "shelltool".
1128
1129 This feature is currently in development for both Python and TypeScript SDKs, with newly created tools built for improved agent accuracy.
1130
docs/content/docs/providers/anthropic.mdx
+1 -1
@@ -7,7 +7,7 @@ keywords: [claude, messages api, claude agent sdk, agents sdk]
7 The Anthropic provider formats Composio tools for Claude and executes the tool calls Claude returns. It works two ways:
8
9 - The [Claude Messages API](https://docs.anthropic.com/en/api/messages), where you run the tool-call loop yourself.
10 -- The [Claude Agent SDK](https://docs.anthropic.com/en/docs/agents-and-tools/claude-agent-sdk), where the SDK runs the loop and Composio tools are exposed as an in-process MCP server.
10 +- The [Claude Agent SDK](https://platform.claude.com/docs/en/agent-sdk/overview), where the SDK runs the loop and Composio tools are exposed as an in-process MCP server.
11
12 Pick the tab that matches your integration.
13
docs/content/examples/general-agent-with-pi.mdx
-2
@@ -100,8 +100,6 @@ The two files above are the spine. The real project rounds them out with grouped
100
101 <RepoBrowser />
102
103 -The complete project lives on GitHub: [composio-slack-bot](https://github.com/ComposioHQ/composio-slack-bot).
104 -
103 ## Run it
104
105 Run `bun install.ts` once to set up the bot, start the server with `bun bot.ts`, then `@mention` the bot in any channel. It opens a session as you, finds the tool it needs, runs it against your connections, and replies in thread as the workspace bot, usually within a few seconds. Ask it to do something in an app you haven't connected yet and it DMs you a link first, then continues once you approve.
docs/content/examples/local-sandbox-pr-reviewer.mdx
-2
@@ -90,8 +90,6 @@ The file above is the spine. The real project rounds it out with a CLI, a smoke/
90
91 <RepoBrowser source="local-workbench" />
92
93 -The complete project lives on GitHub: [local-pr-reviewer](https://github.com/ComposioHQ/local-pr-reviewer).
94 -
93 ## Run it
94
95 Dry-run first to validate your input with no credentials, network calls, or sandbox startup, then run it for real:
docs/content/reference/errors.mdx
+1 -1
@@ -52,7 +52,7 @@ Composio uses two types of API keys:
52
53 | Error | Cause |
54 |-------|-------|
55 -| Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://dashboard.composio.dev/settings). |
55 +| Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://dashboard.composio.dev/~/project/settings/api-keys). |
56 | No authentication provided | The request is missing the `x-api-key` or `x-org-api-key` header. |
57 | Invalid organization key | The organization API key is incorrect or revoked. Verify in Organization Settings. |
58 | Insufficient permissions | The API key doesn't have access to this resource. |
docs/content/reference/v3/errors.mdx
+1 -1
@@ -52,7 +52,7 @@ Composio uses two types of API keys:
52
53 | Error | Cause |
54 |-------|-------|
55 -| Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://dashboard.composio.dev/settings). |
55 +| Invalid API key | The API key is incorrect or revoked. Verify in [Settings](https://dashboard.composio.dev/~/project/settings/api-keys). |
56 | No authentication provided | The request is missing the `x-api-key` or `x-org-api-key` header. |
57 | Invalid organization key | The organization API key is incorrect or revoked. Verify in Organization Settings. |
58 | Insufficient permissions | The API key doesn't have access to this resource. |
docs/lib/openapi-tags.ts new
+46
@@ -0,0 +1,46 @@
1 +export type OpenAPIOperation = {
2 + security?: Record<string, string[]>[];
3 + tags?: string[];
4 +};
5 +
6 +export type OpenAPIDocument = {
7 + tags?: { name: string }[];
8 + paths?: Record<string, Record<string, OpenAPIOperation | undefined>>;
9 + webhooks?: Record<string, Record<string, OpenAPIOperation | undefined>>;
10 +};
11 +
12 +/**
13 + * fumadocs-openapi's tag grouping only generates pages for operations whose
14 + * tags are declared in the document's top-level `tags` array; operations with
15 + * undeclared tags are silently skipped. The backend generator omits some tags
16 + * (e.g. Projects) from that array, so declare every tag used by an operation.
17 + *
18 + * Applied both when syncing specs (scripts/fetch-openapi.mjs) so the committed
19 + * documents are complete, and again at load time (lib/openapi.ts) as a safety
20 + * net for snapshots that predate the sync-time normalization.
21 + */
22 +export function declareOperationTags<T extends OpenAPIDocument>(document: T): T {
23 + const declared = new Set((document.tags ?? []).map((tag) => tag.name));
24 + const undeclared: string[] = [];
25 + for (const group of [document.paths, document.webhooks]) {
26 + for (const pathItem of Object.values(group ?? {})) {
27 + for (const operation of Object.values(pathItem ?? {})) {
28 + if (!operation || typeof operation !== 'object') continue;
29 + for (const tag of operation.tags ?? []) {
30 + if (declared.has(tag)) continue;
31 + declared.add(tag);
32 + undeclared.push(tag);
33 + }
34 + }
35 + }
36 + }
37 +
38 + if (undeclared.length > 0) {
39 + document.tags = [
40 + ...(document.tags ?? []),
41 + ...undeclared.map((name) => ({ name })),
42 + ];
43 + }
44 +
45 + return document;
46 +}
docs/lib/openapi.ts
+4 -8
@@ -1,6 +1,9 @@
1 import { readFile } from 'node:fs/promises';
2 import { join } from 'path';
3 import { createOpenAPI } from 'fumadocs-openapi/server';
4 +import { declareOperationTags, type OpenAPIDocument } from './openapi-tags';
5 +
6 +export { declareOperationTags } from './openapi-tags';
7
8 const openapiPath = join(process.cwd(), 'public/openapi.json');
9 const openapiWebhooksPath = join(
@@ -9,13 +12,6 @@ const openapiWebhooksPath = join(
12 );
13 const openapiV3Path = join(process.cwd(), 'public/openapi-v3.json');
14
12 -type OpenAPIDocument = {
13 - paths?: Record<
14 - string,
15 - Record<string, { security?: Record<string, string[]>[] } | undefined>
16 - >;
17 -};
18 -
15 // v3.1 (latest) — clean operationIds, default API reference.
16 // The webhook-events spec (openapi-webhooks.json) is a separate OpenAPI 3.1
17 // document whose top-level `webhooks` block documents the payloads Composio
@@ -38,7 +34,7 @@ export const openapiV3 = createOpenAPI({
34
35 async function loadOpenAPISchema(path: string) {
36 const document = JSON.parse(await readFile(path, 'utf8')) as OpenAPIDocument;
41 - return normalizeNoAuthSecurity(document);
37 + return declareOperationTags(normalizeNoAuthSecurity(document));
38 }
39
40 export function normalizeNoAuthSecurity<T extends OpenAPIDocument>(document: T): T {
docs/lib/repo-browser-markdown.ts new
+22
@@ -0,0 +1,22 @@
1 +const REPO_BROWSER_PATTERN = /<RepoBrowser\b([^>]*)\/>/g;
2 +
3 +const REPO_BROWSER_NOTICES: Record<string, string> = {
4 + 'slack-bot':
5 + 'The Slack bot browser is a documentation snapshot; a public repository is not available.',
6 + 'local-workbench':
7 + 'The local PR reviewer browser is a documentation snapshot; a public repository is not available.',
8 + standup:
9 + 'The standup bot browser is a documentation snapshot; a public repository is not available.',
10 + imessage:
11 + 'The iMessage implementation is maintained in [platform-imessage](https://github.com/ComposioHQ/platform-imessage).',
12 +};
13 +
14 +export function replaceRepoBrowserMarkdown(markdown: string): string {
15 + return markdown.replace(REPO_BROWSER_PATTERN, (_, props: string) => {
16 + const source = props.match(/\bsource="([^"]+)"/)?.[1] ?? 'slack-bot';
17 + const notice =
18 + REPO_BROWSER_NOTICES[source] ??
19 + 'This code browser is a documentation snapshot; a public repository is not available.';
20 + return `\n> ${notice}\n`;
21 + });
22 +}
docs/lib/source.ts
+2 -12
@@ -6,6 +6,7 @@ import { openapiSource, openapiPlugin } from 'fumadocs-openapi/server';
6 import { getGuardrails } from './llm-guardrails';
7 import { HIDDEN_API_TAGS } from './filter-api-version';
8 import { FILE_BUILDS } from './file-builds';
9 +import { replaceRepoBrowserMarkdown } from './repo-browser-markdown';
10 import { deprecatedApiSidebarTransformer } from './deprecated-api-sidebar';
11
12 /**
@@ -297,18 +298,7 @@ export function mdxToCleanMarkdown(content: string): string {
298 }
299 );
300
300 - // RepoBrowser is an interactive file tree. The iMessage page intentionally
301 - // shows a source slice while its public runnable fixture is still pending.
302 - result = result.replace(
303 - /<RepoBrowser\b(?=[^>]*\bsource="imessage")[^>]*\/>/g,
304 - '\n> The iMessage code browser is an implementation slice, not a standalone fixture. The complete runnable project will be published in the Composio examples repo.\n'
305 - );
306 -
307 - // Point the existing Slack browser at its real repository.
308 - result = result.replace(
309 - /<RepoBrowser\b[^>]*\/>/g,
310 - '\n> The complete project is on GitHub: [composio-slack-bot](https://github.com/ComposioHQ/composio-slack-bot).\n'
311 - );
301 + result = replaceRepoBrowserMarkdown(result);
302
303 result = result.replace(/<\/?(ProviderGrid|Tabs|Frame|div|QuickstartFlow|IntegrationTabs|Accordions|ToolTypeFlow|ToolkitsLanding|TemplateGrid|Glossary|ConnectFlow|ConnectClientOption)[^>]*>/g, '');
304
docs/package.json
+1
@@ -16,6 +16,7 @@
16 "postinstall": "fumadocs-mdx",
17 "lint": "oxlint .",
18 "lint:links": "bun scripts/validate-links.ts",
19 + "lint:links:external": "bun scripts/validate-links.ts --external",
20 "sync:search": "bun scripts/sync-algolia-search.ts",
21 "test:search": "bun scripts/test-algolia-search.ts",
22 "eval:agent": "eve eval docs-agent --skip-report",
docs/public/openapi-v3.json
+6
@@ -104,6 +104,12 @@
104 {
105 "name": "Tool Router",
106 "description": "(Labs) Tool router endpoints"
107 + },
108 + {
109 + "name": "Organization Management"
110 + },
111 + {
112 + "name": "Projects"
113 }
114 ],
115 "components": {
docs/public/openapi.json
+9
@@ -104,6 +104,15 @@
104 {
105 "name": "Tool Router",
106 "description": "(Labs) Tool router endpoints"
107 + },
108 + {
109 + "name": "Invite Codes"
110 + },
111 + {
112 + "name": "Projects"
113 + },
114 + {
115 + "name": "Organization Management"
116 }
117 ],
118 "components": {
docs/scripts/fetch-openapi.mjs
+18 -4
@@ -23,6 +23,7 @@ import { dirname, join } from 'node:path';
23 import { fileURLToPath } from 'node:url';
24 import { z } from 'zod';
25 import { fetchWithRetry } from './fetch-with-retry';
26 +import { declareOperationTags } from '../lib/openapi-tags';
27 import {
28 PRODUCTION_BASE_URL,
29 PRODUCTION_API_V3_URL,
@@ -180,7 +181,7 @@ function forEachOperation(paths, callback) {
181 }
182
183 /**
183 - * Filter paths: remove ignored/internal tags, keep first tag only.
184 + * Filter paths: remove ignored/internal tags, keep the first public tag only.
185 */
186 function filterPaths(paths) {
187 const filteredPaths = {};
@@ -195,13 +196,14 @@ function filterPaths(paths) {
196
197 const tags = operation.tags ?? [];
198 const isInternal = operation['x-internal'] === true || tags.includes('x-internal');
198 - const hasOnlyIgnoredTags = tags.length > 0 && tags.every(tag => IGNORED_TAGS.has(tag));
199 + const publicTags = tags.filter(tag => !IGNORED_TAGS.has(tag));
200 + const hasOnlyIgnoredTags = tags.length > 0 && publicTags.length === 0;
201
202 if (isInternal || hasOnlyIgnoredTags) {
203 delete filteredPathItem[method];
204 removedCount++;
203 - } else if (tags.length > 1) {
204 - filteredPathItem[method] = { ...operation, tags: [tags[0]] };
205 + } else if (publicTags.length > 0) {
206 + filteredPathItem[method] = { ...operation, tags: [publicTags[0]] };
207 }
208 }
209
@@ -340,6 +342,18 @@ function postProcessSpec(spec) {
342 if (spec.tags) {
343 spec.tags = spec.tags.filter(tag => !IGNORED_TAGS.has(tag.name));
344 }
345 + // fumadocs-openapi only generates pages for operations whose tags are
346 + // declared top-level; the backend generator omits some (e.g. Projects).
347 + const declaredUpstream = new Set((spec.tags ?? []).map(tag => tag.name));
348 + declareOperationTags(spec);
349 + const addedTags = (spec.tags ?? []).filter(tag => !declaredUpstream.has(tag.name));
350 + if (addedTags.length > 0) {
351 + console.warn(
352 + `WARN: upstream spec uses tags missing from its top-level tags array: ${addedTags
353 + .map(tag => tag.name)
354 + .join(', ')}. Declared them automatically; the backend generator should emit them.`
355 + );
356 + }
357
358 removeCookieAuthentication(spec);
359 normalizeLargeObjectUnions(spec);
docs/scripts/validate-links.ts
+69
@@ -15,6 +15,13 @@ import {
15 toolkitsSource,
16 } from '../lib/source';
17
18 +/**
19 + * `--external` additionally HEAD/GET-checks every external URL. Slow and
20 + * dependent on third-party uptime, so it runs on a schedule (nightly CI),
21 + * never on the PR path.
22 + */
23 +const checkExternalLinks = process.argv.includes('--external');
24 +
25 type AnySource =
26 | typeof source
27 | Awaited<ReturnType<typeof getReferenceSource>>
@@ -90,6 +97,67 @@ async function getDynamicToolkitEntries() {
97 return toolkits.map((t) => ({ value: { slug: [t.slug] }, hashes: [] as string[] }));
98 }
99
100 +const EXTERNAL_FETCH_HEADERS = {
101 + // Some hosts reject requests without a browser-like UA (bot filters).
102 + 'user-agent':
103 + 'Mozilla/5.0 (compatible; composio-docs-link-check; +https://docs.composio.dev)',
104 + accept: 'text/html,application/xhtml+xml;q=0.9,*/*;q=0.8',
105 +};
106 +
107 +async function fetchStatus(url: URL, method: 'HEAD' | 'GET'): Promise<number> {
108 + const response = await fetch(url, {
109 + method,
110 + headers: EXTERNAL_FETCH_HEADERS,
111 + redirect: 'follow',
112 + signal: AbortSignal.timeout(15_000),
113 + });
114 + await response.body?.cancel();
115 + return response.status;
116 +}
117 +
118 +const externalResultCache = new Map<
119 + string,
120 + Promise<{ success: true } | { success: false; message?: string }>
121 +>();
122 +
123 +/**
124 + * Replaces next-validate-link's default external validator (bare HEAD, no
125 + * timeout, no UA, no retry). This one only fails on evidence the link is dead
126 + * — 404/410, or a network error after a retry. Auth walls, rate limits, and
127 + * transient 5xx count as reachable: the nightly job hunts dead links, not
128 + * third-party uptime.
129 + */
130 +function validateExternalUrl(url: URL) {
131 + if (url.hostname === 'localhost' || url.hostname === '127.0.0.1') {
132 + return Promise.resolve({ success: true as const });
133 + }
134 + const cached = externalResultCache.get(url.href);
135 + if (cached) return cached;
136 +
137 + const result = (async () => {
138 + for (let attempt = 0; attempt < 2; attempt++) {
139 + try {
140 + let status = await fetchStatus(url, 'HEAD');
141 + // Many servers reject HEAD (405, bot filters); confirm with GET.
142 + if (status >= 400) status = await fetchStatus(url, 'GET');
143 + if (status === 404 || status === 410) {
144 + return { success: false as const, message: `responded status ${status}` };
145 + }
146 + return { success: true as const };
147 + } catch (error) {
148 + if (attempt === 0) continue;
149 + return {
150 + success: false as const,
151 + message: error instanceof Error ? error.message : 'fetch failed',
152 + };
153 + }
154 + }
155 + return { success: false as const };
156 + })();
157 + externalResultCache.set(url.href, result);
158 + return result;
159 +}
160 +
161 async function checkLinks() {
162 const referenceSource = await getReferenceSource();
163 const [docsEntries, refEntries, exampleEntries, toolkitEntries, dynamicToolkitEntries] = await Promise.all([
@@ -119,6 +187,7 @@ async function checkLinks() {
187 },
188 },
189 checkRelativePaths: 'as-url',
190 + checkExternal: checkExternalLinks ? { validate: validateExternalUrl } : false,
191 });
192
193 // Filter out API route URLs (these are valid but not detected as pages)
docs/tests/static/api-reference-routes.test.ts new
+281
@@ -0,0 +1,281 @@
1 +/**
2 + * API reference route guards.
3 + *
4 + * fumadocs-openapi's tag grouping silently drops any operation whose tag is
5 + * not declared in the document's top-level `tags` array (preset-auto:
6 + * `builder.fromTagName(tag)` returns undefined -> `continue`, no warning).
7 + * The v10 -> v11 upgrade shipped exactly that: 16 operation pages vanished
8 + * from the site, sitemap, and search while the checked-in tag landing pages
9 + * kept rendering quick links that 404ed. Nothing else can catch this class:
10 + * validate-links only sees markdown links (ApiEndpointsTable hrefs live in a
11 + * JSX prop), and the integration suite samples fixed routes.
12 + *
13 + * Two guards, both derived from the shipped specs rather than snapshots so
14 + * routine spec syncs (docs-update-data) never churn them:
15 + * 1. Completeness — every operation/webhook a spec implies maps 1:1 to a page
16 + * the production loader path actually generates, regardless of the drop
17 + * mechanism.
18 + * 2. Quick links — every href serialized into an ApiEndpointsTable in
19 + * content/reference resolves to a generated page.
20 + */
21 +import { describe, expect, test } from 'bun:test';
22 +import { readFileSync, readdirSync } from 'node:fs';
23 +import { join, relative } from 'node:path';
24 +import { loader, multiple } from 'fumadocs-core/source';
25 +import { createOpenAPI, openapiSource } from 'fumadocs-openapi/server';
26 +
27 +import { openapi, openapiV3 } from '../../lib/openapi';
28 +import { HIDDEN_API_TAGS } from '../../lib/filter-api-version';
29 +
30 +const DOCS_DIR = join(import.meta.dir, '../..');
31 +
32 +const HTTP_METHODS = [
33 + 'get',
34 + 'put',
35 + 'post',
36 + 'delete',
37 + 'options',
38 + 'head',
39 + 'patch',
40 + 'trace',
41 +] as const;
42 +
43 +interface SpecOperation {
44 + operationId?: string;
45 + tags?: string[];
46 +}
47 +
48 +interface SpecDocument {
49 + paths?: Record<string, Record<string, unknown>>;
50 + webhooks?: Record<string, Record<string, unknown>>;
51 +}
52 +
53 +/** Mirrors the default slugify in fumadocs-openapi's auto preset. */
54 +function slugifyTag(tag: string): string {
55 + return tag.replace(/\s+/g, '-').toLowerCase();
56 +}
57 +
58 +/** Mirrors the hidden-tag URL filter applied in lib/source.ts. */
59 +function isHiddenReferenceUrl(url: string): boolean {
60 + for (const tag of HIDDEN_API_TAGS) {
61 + if (
62 + url.startsWith(`/reference/api-reference/${tag}/`) ||
63 + url.startsWith(`/reference/v3/api-reference/${tag}/`)
64 + ) {
65 + return true;
66 + }
67 + }
68 + return false;
69 +}
70 +
71 +function* specOperations(document: SpecDocument): Generator<{
72 + location: string;
73 + operation: SpecOperation;
74 +}> {
75 + for (const group of [document.paths, document.webhooks]) {
76 + for (const [key, pathItem] of Object.entries(group ?? {})) {
77 + for (const method of HTTP_METHODS) {
78 + const operation = pathItem?.[method];
79 + if (!operation || typeof operation !== 'object') continue;
80 + yield { location: `${method.toUpperCase()} ${key}`, operation };
81 + }
82 + }
83 + }
84 +}
85 +
86 +/**
87 + * URLs the spec implies: one page per visible (operation, tag) pair, named by
88 + * operationId — the scheme both fumadocs-openapi (groupBy: 'tag', name
89 + * algorithm v2) and generate-api-index.ts encode.
90 + */
91 +function expectedReferenceUrls(document: SpecDocument, baseDir: string): Set<string> {
92 + const urls = new Set<string>();
93 + for (const { operation } of specOperations(document)) {
94 + for (const tag of operation.tags ?? []) {
95 + const tagSlug = slugifyTag(tag);
96 + if (HIDDEN_API_TAGS.has(tagSlug)) continue;
97 + urls.add(`/reference/${baseDir}/${tagSlug}/${operation.operationId}`);
98 + }
99 + }
100 + return urls;
101 +}
102 +
103 +function loadSpec(fileName: string): SpecDocument {
104 + return JSON.parse(readFileSync(join(DOCS_DIR, 'public', fileName), 'utf-8'));
105 +}
106 +
107 +/**
108 + * The reference URLs production actually serves, built through the same
109 + * pipeline as lib/source.ts getReferenceSource (minus the checked-in MDX
110 + * collection, which bun test cannot load and which contributes no operation
111 + * pages).
112 + */
113 +async function generatedReferenceUrls(): Promise<Set<string>> {
114 + const [latest, v3] = await Promise.all([
115 + openapiSource(openapi, { groupBy: 'tag', baseDir: 'api-reference' }),
116 + openapiSource(openapiV3, { groupBy: 'tag', baseDir: 'v3/api-reference' }),
117 + ]);
118 + const referenceLoader = loader({
119 + baseUrl: '/reference',
120 + source: multiple({ openapi: latest, 'openapi-v3': v3 }),
121 + });
122 + return new Set(
123 + referenceLoader
124 + .getPages()
125 + .map((page) => page.url)
126 + .filter((url) => !isHiddenReferenceUrl(url)),
127 + );
128 +}
129 +
130 +const generatedUrlsPromise = generatedReferenceUrls();
131 +
132 +describe('API reference route completeness', () => {
133 + test('every visible operation declares a tag and an operationId', () => {
134 + const violations: string[] = [];
135 + for (const fileName of ['openapi.json', 'openapi-v3.json', 'openapi-webhooks.json']) {
136 + for (const { location, operation } of specOperations(loadSpec(fileName))) {
137 + const visibleTags = (operation.tags ?? []).filter(
138 + (tag) => !HIDDEN_API_TAGS.has(slugifyTag(tag)),
139 + );
140 + // Untagged operations fall into fumadocs' synthetic "unknown" tag,
141 + // which is never declared — the page silently vanishes.
142 + if ((operation.tags ?? []).length === 0) {
143 + violations.push(`${fileName}: ${location} has no tags`);
144 + }
145 + // Without an operationId, fumadocs falls back to a path-derived file
146 + // name while generate-api-index derives the href from the summary —
147 + // the quick link is guaranteed to 404.
148 + if (visibleTags.length > 0 && !operation.operationId) {
149 + violations.push(`${fileName}: ${location} has no operationId`);
150 + }
151 + }
152 + }
153 +
154 + expect(violations, violations.join('\n')).toEqual([]);
155 + });
156 +
157 + test('every spec operation and webhook yields exactly one generated page', async () => {
158 + const expected = new Set<string>([
159 + ...expectedReferenceUrls(loadSpec('openapi.json'), 'api-reference'),
160 + ...expectedReferenceUrls(loadSpec('openapi-webhooks.json'), 'api-reference'),
161 + ...expectedReferenceUrls(loadSpec('openapi-v3.json'), 'v3/api-reference'),
162 + ]);
163 + const generated = await generatedUrlsPromise;
164 +
165 + const missing = [...expected].filter((url) => !generated.has(url)).sort();
166 + const extra = [...generated].filter((url) => !expected.has(url)).sort();
167 +
168 + expect(expected.size).toBeGreaterThan(0);
169 + expect(
170 + missing,
171 + `pages implied by the OpenAPI specs but not generated (silently dropped):\n${missing.join('\n')}`,
172 + ).toEqual([]);
173 + expect(
174 + extra,
175 + `generated pages not implied by the OpenAPI specs:\n${extra.join('\n')}`,
176 + ).toEqual([]);
177 + });
178 +
179 + test('the completeness diff flags operations whose tag is undeclared', async () => {
180 + // The exact v10 -> v11 regression, in miniature: "Projects" is used by an
181 + // operation but missing from the top-level tags array, and lib/openapi's
182 + // declareOperationTags normalization is deliberately not applied.
183 + const document = {
184 + openapi: '3.0.0',
185 + info: { title: 'Guard fixture', version: '1' },
186 + tags: [{ name: 'Auth' }],
187 + paths: {
188 + '/v3.1/project/usage/summary': {
189 + post: {
190 + tags: ['Projects'],
191 + operationId: 'postProjectUsageSummary',
192 + summary: 'Usage summary',
193 + responses: { '200': { description: 'ok' } },
194 + },
195 + },
196 + '/v3.1/auth/session': {
197 + get: {
198 + tags: ['Auth'],
199 + operationId: 'getSession',
200 + summary: 'Session',
201 + responses: { '200': { description: 'ok' } },
202 + },
203 + },
204 + },
205 + };
206 +
207 + const server = createOpenAPI({ input: { 'guard-fixture.json': document } });
208 + const source = await openapiSource(server, { groupBy: 'tag', baseDir: 'api-reference' });
209 + const generated = new Set(
210 + loader({ baseUrl: '/reference', source }).getPages().map((page) => page.url),
211 + );
212 + const missing = [...expectedReferenceUrls(document, 'api-reference')].filter(
213 + (url) => !generated.has(url),
214 + );
215 +
216 + // fumadocs-openapi still silently drops the undeclared tag...
217 + expect(generated.has('/reference/api-reference/auth/getSession')).toBe(true);
218 + // ...and the completeness diff is what surfaces the loss. If this ever
219 + // fails with `missing` empty, upstream fixed the silent drop and the
220 + // declareOperationTags workaround in lib/openapi.ts can be retired.
221 + expect(missing).toEqual([
222 + '/reference/api-reference/projects/postProjectUsageSummary',
223 + ]);
224 + });
225 +});
226 +
227 +describe('API reference quick links', () => {
228 + function mdxFiles(dir: string): string[] {
229 + const files: string[] = [];
230 + for (const entry of readdirSync(dir, { withFileTypes: true })) {
231 + const fullPath = join(dir, entry.name);
232 + if (entry.isDirectory()) files.push(...mdxFiles(fullPath));
233 + else if (entry.name.endsWith('.mdx')) files.push(fullPath);
234 + }
235 + return files;
236 + }
237 +
238 + /** Parses the serialized endpoints of every ApiEndpointsTable in a file. */
239 + function parseEndpointHrefs(content: string, file: string): string[] {
240 + const hrefs: string[] = [];
241 + const prefix = /<ApiEndpointsTable endpoints=\{/g;
242 + let match: RegExpExecArray | null;
243 + while ((match = prefix.exec(content)) !== null) {
244 + const start = match.index + match[0].length;
245 + const end = content.indexOf('} />', start);
246 + expect(end, `${file}: unterminated ApiEndpointsTable`).toBeGreaterThan(start);
247 + const endpoints: { href: string }[] = JSON.parse(content.slice(start, end));
248 + hrefs.push(...endpoints.map((endpoint) => endpoint.href));
249 + }
250 + // A file mentioning the component but yielding no parsed table means the
251 + // generator's serialization drifted from this extractor — fail loudly
252 + // instead of silently checking nothing.
253 + if (content.includes('<ApiEndpointsTable')) {
254 + expect(hrefs.length, `${file}: found ApiEndpointsTable but extracted no hrefs`).toBeGreaterThan(0);
255 + }
256 + return hrefs;
257 + }
258 +
259 + test('every ApiEndpointsTable href resolves to a generated reference page', async () => {
260 + const generated = await generatedUrlsPromise;
261 + const dead: string[] = [];
262 + let totalHrefs = 0;
263 +
264 + for (const file of mdxFiles(join(DOCS_DIR, 'content/reference'))) {
265 + const content = readFileSync(file, 'utf-8');
266 + for (const href of parseEndpointHrefs(content, relative(DOCS_DIR, file))) {
267 + totalHrefs++;
268 + if (!generated.has(href)) {
269 + dead.push(`${relative(DOCS_DIR, file)}: ${href}`);
270 + }
271 + }
272 + }
273 +
274 + // Sanity: the extractor must have found the generated landing pages.
275 + expect(totalHrefs).toBeGreaterThan(0);
276 + expect(
277 + dead,
278 + `quick links pointing at reference pages that are never generated (would 404):\n${dead.join('\n')}`,
279 + ).toEqual([]);
280 + });
281 +});
docs/tests/static/openapi-tags.test.ts new
+89
@@ -0,0 +1,89 @@
1 +import { describe, expect, test } from 'bun:test';
2 +
3 +import { declareOperationTags } from '../../lib/openapi';
4 +
5 +describe('declareOperationTags', () => {
6 + test('declares operation tags missing from the top-level tags array', () => {
7 + const document = {
8 + tags: [{ name: 'Auth', description: 'Auth endpoints' }],
9 + paths: {
10 + '/project/usage/summary': {
11 + post: { tags: ['Projects'] },
12 + },
13 + '/auth/session': {
14 + get: { tags: ['Auth'] },
15 + },
16 + '/org/members': {
17 + get: { tags: ['Organization Management', 'Projects'] },
18 + },
19 + },
20 + };
21 +
22 + declareOperationTags(document);
23 +
24 + expect(document.tags).toEqual([
25 + { name: 'Auth', description: 'Auth endpoints' },
26 + { name: 'Projects' },
27 + { name: 'Organization Management' },
28 + ]);
29 + });
30 +
31 + test('covers webhook operations and documents without a tags array', () => {
32 + const document: {
33 + tags?: { name: string }[];
34 + webhooks: Record<string, Record<string, { tags?: string[] }>>;
35 + } = {
36 + webhooks: {
37 + 'trigger.fired': {
38 + post: { tags: ['Webhook Events'] },
39 + },
40 + },
41 + };
42 +
43 + declareOperationTags(document);
44 +
45 + expect(document.tags).toEqual([{ name: 'Webhook Events' }]);
46 + });
47 +
48 + test('leaves a fully declared document unchanged', () => {
49 + const tags = [{ name: 'Auth' }];
50 + const document = {
51 + tags,
52 + paths: {
53 + '/auth/session': {
54 + get: { tags: ['Auth'] },
55 + },
56 + },
57 + };
58 +
59 + declareOperationTags(document);
60 +
61 + expect(document.tags).toBe(tags);
62 + });
63 +
64 + test('every shipped spec declares all operation tags', async () => {
65 + for (const specPath of [
66 + 'public/openapi.json',
67 + 'public/openapi-v3.json',
68 + 'public/openapi-webhooks.json',
69 + ]) {
70 + const document = JSON.parse(
71 + await Bun.file(new URL(`../../${specPath}`, import.meta.url)).text(),
72 + );
73 + const declared = new Set(
74 + (document.tags ?? []).map((tag: { name: string }) => tag.name),
75 + );
76 + for (const group of [document.paths, document.webhooks]) {
77 + for (const pathItem of Object.values(group ?? {})) {
78 + for (const operation of Object.values(
79 + pathItem as Record<string, { tags?: string[] } | undefined>,
80 + )) {
81 + for (const tag of operation?.tags ?? []) {
82 + expect(declared.has(tag)).toBe(true);
83 + }
84 + }
85 + }
86 + }
87 + }
88 + });
89 +});
docs/tests/static/source.test.ts new
+26
@@ -0,0 +1,26 @@
1 +import { describe, expect, test } from 'bun:test';
2 +
3 +import { replaceRepoBrowserMarkdown } from '../../lib/repo-browser-markdown';
4 +
5 +describe('replaceRepoBrowserMarkdown', () => {
6 + test('emits source-aware RepoBrowser availability notices', () => {
7 + const markdown = replaceRepoBrowserMarkdown(`
8 +<RepoBrowser />
9 +<RepoBrowser source="local-workbench" />
10 +<RepoBrowser source="standup" />
11 +<RepoBrowser source="imessage" />
12 +<RepoBrowser source="unknown" />
13 +`);
14 +
15 + expect(markdown).toContain('The Slack bot browser is a documentation snapshot');
16 + expect(markdown).toContain('The local PR reviewer browser is a documentation snapshot');
17 + expect(markdown).toContain('The standup bot browser is a documentation snapshot');
18 + expect(markdown).toContain(
19 + '[platform-imessage](https://github.com/ComposioHQ/platform-imessage)',
20 + );
21 + expect(markdown).toContain(
22 + 'This code browser is a documentation snapshot; a public repository is not available.',
23 + );
24 + expect(markdown).not.toContain('composio-slack-bot');
25 + });
26 +});
docs/tests/static/webhook-openapi.test.ts
+31
@@ -135,4 +135,35 @@ describe('REST OpenAPI processing', () => {
135 ]);
136 expect(payload.paths['/visible'].get.operationId).toBe('getV3_1Visible');
137 });
138 +
139 + test('declares operation tags missing from the top-level tags array', () => {
140 + const payload = createApiSpec();
141 + (payload.paths as Record<string, unknown>)['/project/usage/summary'] = {
142 + post: {
143 + tags: ['Projects'],
144 + operationId: 'postProjectUsageSummary',
145 + },
146 + };
147 +
148 + const { spec } = prepareApiSpec(payload, '3.1');
149 +
150 + expect(spec.tags).toEqual([{ name: 'Public' }, { name: 'Projects' }]);
151 + });
152 +
153 + test('keeps the first non-ignored tag from mixed-tag operations', () => {
154 + const payload = createApiSpec();
155 + payload.tags.push({ name: 'Admin' });
156 + (payload.paths as Record<string, unknown>)['/projects'] = {
157 + get: {
158 + tags: ['Admin', 'Projects'],
159 + operationId: 'getProjects',
160 + },
161 + };
162 +
163 + const { spec } = prepareApiSpec(payload, '3.1');
164 +
165 + expect(spec.paths['/projects'].get.tags).toEqual(['Projects']);
166 + expect(spec.tags).toContainEqual({ name: 'Projects' });
167 + expect(spec.tags).not.toContainEqual({ name: 'Admin' });
168 + });
169 });