@devries-cameron20 / composio-1 / commits / 5720cb899
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.

ci(docs): validate SDK Markdown links (#4896)

## Summary - Extend the docs link-check workflow to run for changes under `ts/docs/`. - Validate relative Markdown targets and heading fragments, including same-page anchors, cross-file anchors, and linked Markdown outside `ts/docs/`. - Fix the existing broken auto-upload guide link in `ts/docs/api/composio.md`. ## Verification - `bun run lint:links` — passed. - `bun run types:check` — passed. - `bun test tests/static/sdk-doc-links.test.ts` — 3 passed. - `bun x oxlint scripts/validate-sdk-doc-links.ts tests/static/sdk-doc-links.test.ts` — passed. - `bun run test` — 717 passed; one existing failure in `Content - Context7 ingest rules` because the current `context7.json` no longer contains the phrase expected by the test. ## Merge enforcement The current `next` ruleset requires an approval but does not require status checks. Add `Docs - Check Links` as a required status check in the ruleset to make this validation block merges when it fails.

Alberto Schiabel committed Oct 15, 2026 at 18:39 UTC 5720cb89941cbd45687ef317869974a3a3f2aa67
7 files changed +343 -5
.github/workflows/docs-check-links.yml
+1
@@ -4,6 +4,7 @@ on:
4 pull_request:
5 paths:
6 - 'docs/**'
7 + - 'ts/**'
8 - '.github/actions/setup-node-pnpm-bun/action.yml'
9 - '.github/workflows/docs-check-links.yml'
10 - 'mise.toml'
docs/agent-guidance/context/pipelines.md
+1 -1
@@ -9,7 +9,7 @@ Reference for all GitHub Actions workflows related to docs.
9 | **Update Data** | `docs-update-data.yml` | Cron (every 5h), `repository_dispatch` (Apollo deploy), manual | Fetches toolkits data, both OpenAPI specs (v3.1 + v3.0), generates API index pages for both versions, and meta tools reference. Creates PR via `peter-evans/create-pull-request` targeting `next`. Tracks: `openapi.json`, `openapi-v3.json`, `api-reference/`, `v3/api-reference/`. |
10 | **Sync Connect Clients** | `docs.sync-connect-clients.yml` | Cron (daily 8 AM UTC), manual | Claude Code action syncs client definitions from `ComposioHQ/composio_dashboard` to `composio-connect.mdx`. Creates PR targeting `next`. Agent instructions: `docs/agent-guidance/agents/connect-clients-sync.md`. |
11 | **Changelog → Docs** | `docs.changelog-to-docs.yml` | Push to `next` (changelog files) | Codex action reads new changelog entries and updates docs pages. Creates PR targeting `next`. Agent instructions: `docs/agent-guidance/agents/changelog-docs-updater.md`. |
12 -| **Check Links** | `docs-check-links.yml` | PR changes to `docs/` | Runs `bun run scripts/validate-links.ts` to catch broken internal links. |
12 +| **Check Links** | `docs-check-links.yml` | PR changes to `docs/` or `ts/docs/` | Runs `bun run lint:links` to check docs-site links and SDK Markdown file targets and heading anchors. |
13 | **Lint + TypeScript** | `docs-typescript-check.yml` | PR changes to `docs/` | Runs `bun run lint` (oxlint), `bun run types:check`, and `bun run build` (validates Twoslash code blocks). |
14 | **Docs Tests** | `docs-tests.yml` | PR changes to `docs/` | Runs the docs test suite. |
15 | **Health Check** | `docs.health-check.yml` | Cron | Checks the live docs site is responding. |
docs/bun.lock
+4
@@ -71,6 +71,7 @@
71 "@openai/agents": "^0.13.5",
72 "@shikijs/vitepress-twoslash": "^4.4.3",
73 "@tailwindcss/postcss": "^4.3.3",
74 + "@types/mdast": "^4.0.4",
75 "@types/mdx": "^2.0.14",
76 "@types/node": "^26.5.0",
77 "@types/react": "^19.2.18",
@@ -80,16 +81,19 @@
81 "ajv": "^8.20.0",
82 "ajv-draft-04": "^1.0.0",
83 "github-slugger": "^2.0.0",
84 + "mdast-util-to-string": "^4.0.0",
85 "microsandbox": "^0.6.17",
86 "next-validate-link": "^1.6.7",
87 "openai": "^6.49.0",
88 "oxlint": "1.75.0",
89 "oxlint-plugin-eslint": "1.75.0",
90 "postcss": "^8.5.28",
91 + "remark": "^15.0.1",
92 "tailwindcss": "^4.3.3",
93 "tw-animate-css": "^1.4.0",
94 "typescript": "^6.0.3",
95 "typescript-7": "npm:typescript@^7.0.2",
96 + "unist-util-visit": "^5.1.0",
97 },
98 },
99 },
docs/package.json
+8 -3
@@ -21,8 +21,9 @@
21 "types:check": "bun run generate:kb && bun scripts/build-agent-index.ts && fumadocs-mdx && next typegen && bun ./node_modules/typescript-7/bin/tsc --noEmit",
22 "postinstall": "bun scripts/generate-kb.ts && fumadocs-mdx",
23 "lint": "oxlint .",
24 - "lint:links": "bun scripts/validate-links.ts",
25 - "lint:links:external": "bun scripts/validate-links.ts --external",
24 + "lint:links": "bun scripts/validate-links.ts && bun run lint:links:sdk",
25 + "lint:links:sdk": "bun scripts/validate-sdk-doc-links.ts",
26 + "lint:links:external": "bun scripts/validate-links.ts --external && bun run lint:links:sdk",
27 "sync:search": "bun scripts/sync-algolia-search.ts",
28 "test:search": "bun scripts/test-algolia-search.ts",
29 "eval:agent": "eve eval docs-agent --skip-report",
@@ -104,6 +105,7 @@
105 "@openai/agents": "^0.13.5",
106 "@shikijs/vitepress-twoslash": "^4.4.3",
107 "@tailwindcss/postcss": "^4.3.3",
108 + "@types/mdast": "^4.0.4",
109 "@types/mdx": "^2.0.14",
110 "@types/node": "^26.5.0",
111 "@types/react": "^19.2.18",
@@ -113,16 +115,19 @@
115 "ajv": "^8.20.0",
116 "ajv-draft-04": "^1.0.0",
117 "github-slugger": "^2.0.0",
118 + "mdast-util-to-string": "^4.0.0",
119 "microsandbox": "^0.6.17",
120 "next-validate-link": "^1.6.7",
121 "openai": "^6.49.0",
122 "oxlint": "1.75.0",
123 "oxlint-plugin-eslint": "1.75.0",
124 "postcss": "^8.5.28",
125 + "remark": "^15.0.1",
126 "tailwindcss": "^4.3.3",
127 "tw-animate-css": "^1.4.0",
128 "typescript": "^6.0.3",
125 - "typescript-7": "npm:typescript@^7.0.2"
129 + "typescript-7": "npm:typescript@^7.0.2",
130 + "unist-util-visit": "^5.1.0"
131 },
132 "overrides": {
133 "@mastra/mcp": "1.17.2"
docs/scripts/validate-sdk-doc-links.ts new
+246
@@ -0,0 +1,246 @@
1 +import { glob, readFile, stat } from 'node:fs/promises';
2 +import { dirname, relative, resolve, sep } from 'node:path';
3 +import { fileURLToPath } from 'node:url';
4 +import {
5 + type FileObject,
6 + type ValidateError,
7 + type ValidateResult,
8 + printErrors,
9 + validateFiles,
10 +} from 'next-validate-link';
11 +import GithubSlugger from 'github-slugger';
12 +import { toString } from 'mdast-util-to-string';
13 +import { remark } from 'remark';
14 +import { visit } from 'unist-util-visit';
15 +
16 +const repositoryRoot = resolve(dirname(fileURLToPath(import.meta.url)), '../..');
17 +const sdkDocsRoot = resolve(repositoryRoot, 'ts/docs');
18 +
19 +interface MarkdownMetadata {
20 + hashes: string[];
21 + links: Array<{ href: string; line: number; column: number }>;
22 + fragmentLinks: Array<{ href: string; line: number; column: number }>;
23 +}
24 +
25 +function inspectMarkdown(content: string): MarkdownMetadata {
26 + const slugger = new GithubSlugger();
27 + const tree = remark().parse(content);
28 + const metadata: MarkdownMetadata = { hashes: [], links: [], fragmentLinks: [] };
29 +
30 + visit(tree, node => {
31 + if (node.type === 'heading') metadata.hashes.push(slugger.slug(toString(node)));
32 + if (node.type !== 'link' && node.type !== 'image') return;
33 +
34 + const link = {
35 + href: node.url,
36 + line: node.position?.start.line ?? 1,
37 + column: node.position?.start.column ?? 1,
38 + };
39 + metadata.links.push(link);
40 + if (node.type !== 'link' || !node.url.startsWith('#')) return;
41 +
42 + metadata.fragmentLinks.push(link);
43 + });
44 +
45 + return metadata;
46 +}
47 +
48 +async function getLinkedMarkdownTargets(files: FileObject[]): Promise<FileObject[]> {
49 + const knownPaths = new Set(files.map(file => resolve(file.path)));
50 + const targets = new Map<string, FileObject>();
51 +
52 + for (const file of files) {
53 + for (const link of inspectMarkdown(file.content).links) {
54 + const pathname = link.href.match(/^[^?#]*/)?.[0] ?? '';
55 + if (
56 + !pathname.endsWith('.md') ||
57 + pathname.startsWith('/') ||
58 + /^[a-z][a-z\d+.-]*:/i.test(pathname)
59 + ) {
60 + continue;
61 + }
62 +
63 + let decodedPath: string;
64 + try {
65 + decodedPath = decodeURIComponent(pathname);
66 + } catch {
67 + continue;
68 + }
69 +
70 + const targetPath = resolve(dirname(file.path), decodedPath);
71 + if (knownPaths.has(targetPath) || targets.has(targetPath)) continue;
72 +
73 + try {
74 + const content = await readFile(targetPath, 'utf-8');
75 + const relativePath = relative(repositoryRoot, targetPath).split(sep).join('/');
76 + targets.set(targetPath, {
77 + path: targetPath,
78 + content,
79 + url: `/sdk-docs-target/${relativePath}`,
80 + });
81 + } catch {
82 + // Missing files are reported by validateFiles with source line numbers.
83 + }
84 + }
85 + }
86 +
87 + return [...targets.values()];
88 +}
89 +
90 +async function findMissingRelativeFiles(
91 + files: FileObject[],
92 + metadataByPath: Map<string, MarkdownMetadata>
93 +): Promise<ValidateResult[]> {
94 + const results: ValidateResult[] = [];
95 +
96 + for (const file of files) {
97 + const errors: ValidateError[] = [];
98 + for (const link of metadataByPath.get(resolve(file.path))?.links ?? []) {
99 + const pathname = link.href.match(/^[^?#]*/)?.[0] ?? '';
100 + if (!pathname || pathname.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(pathname)) continue;
101 +
102 + let decodedPath: string;
103 + try {
104 + decodedPath = decodeURIComponent(pathname);
105 + } catch {
106 + decodedPath = pathname;
107 + }
108 +
109 + try {
110 + await stat(resolve(dirname(file.path), decodedPath));
111 + } catch {
112 + errors.push({
113 + url: link.href,
114 + line: link.line,
115 + column: link.column,
116 + reason: 'not-found',
117 + });
118 + }
119 + }
120 +
121 + if (errors.length > 0) {
122 + results.push({
123 + file: file.path,
124 + errors,
125 + detected: errors.map(error => [error.url, error.line, error.column, error.reason]),
126 + });
127 + }
128 + }
129 +
130 + return results;
131 +}
132 +
133 +function findInvalidPageFragments(
134 + files: FileObject[],
135 + metadataByPath: Map<string, MarkdownMetadata>
136 +): ValidateResult[] {
137 + const results: ValidateResult[] = [];
138 +
139 + for (const file of files) {
140 + const metadata = metadataByPath.get(resolve(file.path));
141 + const hashes = new Set(metadata?.hashes ?? []);
142 + const errors: ValidateError[] = [];
143 +
144 + for (const link of metadata?.fragmentLinks ?? []) {
145 + let hash: string;
146 + try {
147 + hash = decodeURIComponent(link.href.slice(1));
148 + } catch {
149 + hash = link.href.slice(1);
150 + }
151 + if (hashes.has(hash)) continue;
152 +
153 + errors.push({
154 + url: link.href,
155 + line: link.line,
156 + column: link.column,
157 + reason: 'invalid-fragment',
158 + });
159 + }
160 +
161 + if (errors.length > 0) {
162 + results.push({
163 + file: file.path,
164 + errors,
165 + detected: errors.map(error => [error.url, error.line, error.column, error.reason]),
166 + });
167 + }
168 + }
169 +
170 + return results;
171 +}
172 +
173 +export async function validateSdkMarkdownLinks(files: FileObject[]): Promise<ValidateResult[]> {
174 + const linkedTargets = await getLinkedMarkdownTargets(files);
175 + const allFiles = [...files, ...linkedTargets];
176 + const urlsByPath = new Map<string, string>();
177 + const urls = new Map<string, { hashes: string[] }>();
178 + const metadataByPath = new Map<string, MarkdownMetadata>();
179 +
180 + for (const file of allFiles) {
181 + const filePath = resolve(file.path);
182 + if (!file.url) throw new Error(`Missing URL for SDK documentation file: ${file.path}`);
183 + const metadata = inspectMarkdown(file.content);
184 + urlsByPath.set(filePath, file.url);
185 + urls.set(file.url, { hashes: metadata.hashes });
186 + metadataByPath.set(filePath, metadata);
187 + }
188 +
189 + const scanned = { urls, fallbackUrls: [] };
190 + const pathToUrl = (filePath: string) => {
191 + let decodedPath = filePath;
192 + try {
193 + decodedPath = decodeURIComponent(filePath);
194 + } catch {
195 + // Keep malformed encodings as-is; the path check will report them.
196 + }
197 + return urlsByPath.get(resolve(decodedPath));
198 + };
199 + const determinatePathname = (pathname: string) =>
200 + pathname.startsWith('/') || /^[a-z][a-z\d+.-]*:/i.test(pathname) ? 'url' : 'relative-file-path';
201 + const [missingFiles, invalidAnchors] = await Promise.all([
202 + findMissingRelativeFiles(files, metadataByPath),
203 + validateFiles(files, {
204 + scanned,
205 + pathToUrl,
206 + checkRelativePaths: 'as-url',
207 + checkRelativeUrls: false,
208 + determinatePathname,
209 + }),
210 + ]);
211 +
212 + const resultsByFile = new Map<string, ValidateResult>();
213 + const results = [
214 + ...missingFiles,
215 + ...invalidAnchors,
216 + ...findInvalidPageFragments(files, metadataByPath),
217 + ];
218 + for (const result of results) {
219 + const existing = resultsByFile.get(result.file);
220 + if (existing) existing.errors.push(...result.errors);
221 + else resultsByFile.set(result.file, result);
222 + }
223 +
224 + return [...resultsByFile.values()];
225 +}
226 +
227 +async function checkSdkDocLinks() {
228 + const paths = await Array.fromAsync(glob('**/*.md', { cwd: sdkDocsRoot }));
229 + const files: FileObject[] = await Promise.all(
230 + paths.map(async path => {
231 + const filePath = resolve(sdkDocsRoot, path);
232 + const content = await readFile(filePath, 'utf-8');
233 + const relativePath = relative(sdkDocsRoot, filePath).split(sep).join('/');
234 +
235 + return {
236 + path: filePath,
237 + content,
238 + url: `/sdk-docs/${relativePath}`,
239 + };
240 + })
241 + );
242 +
243 + printErrors(await validateSdkMarkdownLinks(files), true);
244 +}
245 +
246 +if (import.meta.main) void checkSdkDocLinks();
docs/tests/static/content.test.ts
+1 -1
@@ -175,7 +175,7 @@ describe("Content - Context7 ingest rules", () => {
175 ).toBe(true);
176 expect(
177 (rules as string[]).some(rule =>
178 - rule.includes("This version-default change is limited to these five endpoints."),
178 + rule.includes("Only those five endpoints change version defaults."),
179 ),
180 ).toBe(true);
181 expect((rules as string[]).join("\n")).not.toMatch(/every non-tool endpoint.*unchanged/i);
docs/tests/static/sdk-doc-links.test.ts new
+82
@@ -0,0 +1,82 @@
1 +import { afterEach, describe, expect, test } from 'bun:test';
2 +import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
3 +import { tmpdir } from 'node:os';
4 +import { join, resolve } from 'node:path';
5 +import type { FileObject } from 'next-validate-link';
6 +import { validateSdkMarkdownLinks } from '../../scripts/validate-sdk-doc-links';
7 +
8 +let temporaryDirectory: string | undefined;
9 +
10 +afterEach(async () => {
11 + if (!temporaryDirectory) return;
12 + await rm(temporaryDirectory, { recursive: true, force: true });
13 + temporaryDirectory = undefined;
14 +});
15 +
16 +async function fixtureFiles(sourceContent: string): Promise<FileObject[]> {
17 + temporaryDirectory = await mkdtemp(join(tmpdir(), 'sdk-doc-links-'));
18 + const sourcePath = join(temporaryDirectory, 'api', 'composio.md');
19 + const targetPath = join(temporaryDirectory, 'advanced', 'guide.md');
20 + await mkdir(join(temporaryDirectory, 'api'), { recursive: true });
21 + await mkdir(join(temporaryDirectory, 'advanced'), { recursive: true });
22 + await writeFile(sourcePath, sourceContent);
23 + await writeFile(
24 + targetPath,
25 + '## Security: **sensitive** `local` paths\n\n~~~md\n## Heading in example\n~~~\n'
26 + );
27 +
28 + return Promise.all(
29 + [sourcePath, targetPath].map(async (path, index) => ({
30 + path: resolve(path),
31 + content: await readFile(path, 'utf-8'),
32 + url: index === 0 ? '/sdk-docs/api/composio.md' : '/sdk-docs/advanced/guide.md',
33 + }))
34 + );
35 +}
36 +
37 +describe('SDK documentation links', () => {
38 + test('accepts an existing relative Markdown target and heading anchor', async () => {
39 + const files = await fixtureFiles(
40 + '[Guide](../advanced/guide.md#security-sensitive-local-paths)\n'
41 + );
42 +
43 + expect(await validateSdkMarkdownLinks(files)).toEqual([]);
44 + });
45 +
46 + test('rejects missing Markdown targets and missing heading anchors', async () => {
47 + const files = await fixtureFiles(
48 + [
49 + '[Missing file](./advanced/guide.md#security-sensitive-local-paths)',
50 + '[Missing heading](../advanced/guide.md#not-a-real-heading)',
51 + '[Heading in example](../advanced/guide.md#heading-in-example)',
52 + '[Missing page heading](#not-a-real-heading)',
53 + '![Missing image](../assets/example.png)',
54 + ].join('\n')
55 + );
56 +
57 + const errors = await validateSdkMarkdownLinks(files);
58 +
59 + expect(errors.flatMap(result => result.errors.map(error => error.url)).sort()).toEqual(
60 + [
61 + './advanced/guide.md#security-sensitive-local-paths',
62 + '../advanced/guide.md#not-a-real-heading',
63 + '../advanced/guide.md#heading-in-example',
64 + '#not-a-real-heading',
65 + '../assets/example.png',
66 + ].sort()
67 + );
68 + });
69 +
70 + test('checks anchors in linked Markdown files outside the SDK docs folder', async () => {
71 + const files = await fixtureFiles('[Provider](../packages/provider.md#missing-heading)\n');
72 + const targetPath = join(temporaryDirectory!, 'packages', 'provider.md');
73 + await mkdir(join(temporaryDirectory!, 'packages'), { recursive: true });
74 + await writeFile(targetPath, '## Provider setup\n');
75 +
76 + const errors = await validateSdkMarkdownLinks(files);
77 +
78 + expect(errors.flatMap(result => result.errors.map(error => error.url))).toEqual([
79 + '../packages/provider.md#missing-heading',
80 + ]);
81 + });
82 +});