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 240 lines 7.9 KB
Raw
1 /**
2 * Navigation completeness tests.
3 *
4 * Validates that every entry in meta.json files maps to a real .mdx file or
5 * directory, and that every content file is referenced in its parent meta.json.
6 */
7 import { describe, test, expect } from "bun:test";
8 import { readdir, readFile, stat } from "fs/promises";
9 import { join, basename, dirname, relative } from "path";
10
11 const CONTENT_DIR = join(import.meta.dir, "../../content/docs");
12 const LAYOUT_OPTIONS = join(import.meta.dir, "../../lib/layout.shared.tsx");
13 const GLOBAL_SEARCH = join(import.meta.dir, "../../components/custom-search-dialog.tsx");
14
15 /** Separator entries in meta.json start with --- */
16 function isSeparator(entry: string): boolean {
17 return entry.startsWith("---");
18 }
19
20 /** Link entries are rendered directly by fumadocs and do not resolve locally. */
21 function isLink(entry: string): boolean {
22 return /^(?:external:)?(?:\[[^\]]+\])?\[[^\]]+\]\([^)]+\)$/.test(entry);
23 }
24
25 /** Recursively find all meta.json files under a directory */
26 async function findMetaFiles(dir: string): Promise<string[]> {
27 const results: string[] = [];
28 const entries = await readdir(dir, { withFileTypes: true });
29
30 for (const entry of entries) {
31 const fullPath = join(dir, entry.name);
32 if (entry.isDirectory()) {
33 results.push(...(await findMetaFiles(fullPath)));
34 } else if (entry.name === "meta.json") {
35 results.push(fullPath);
36 }
37 }
38 return results;
39 }
40
41 /** Check if a path exists as a file or directory */
42 async function exists(path: string): Promise<boolean> {
43 try {
44 await stat(path);
45 return true;
46 } catch {
47 return false;
48 }
49 }
50
51 describe("Navigation - meta.json validity", () => {
52 test("root navigation separates current and legacy paths", async () => {
53 const metaPath = join(CONTENT_DIR, "meta.json");
54 const meta = JSON.parse(await readFile(metaPath, "utf-8"));
55 const pages = meta.pages as string[];
56 const separators = pages.filter(isSeparator);
57
58 expect(separators).toEqual([
59 "---Get Started---",
60 "---Core concepts---",
61 "---Governance---",
62 "---Guides---",
63 "---Direct execution (legacy)---",
64 "---Security and Compliance---",
65 "---Migration---",
66 ]);
67
68 expect(pages.slice(1, pages.indexOf("---Core concepts---"))).toEqual([
69 "index",
70 "quickstart",
71 "providers",
72 "agent-plugins",
73 "using-composio-skill",
74 "cli",
75 "composio-connect",
76 "agent-setup",
77 ]);
78
79 expect(
80 pages.slice(
81 pages.indexOf("---Governance---") + 1,
82 pages.indexOf("---Guides---")
83 )
84 ).toEqual([
85 "governance/action-permissions",
86 "governance/tool-hints",
87 "governance/approvals",
88 "firewall",
89 ]);
90
91 expect(
92 pages.slice(
93 pages.indexOf("---Direct execution (legacy)---") + 1,
94 pages.indexOf("---Security and Compliance---")
95 )
96 ).toEqual([
97 "sessions-vs-direct-execution",
98 "tools-direct",
99 "auth-configuration",
100 ]);
101 });
102
103 test("Knowledge Base appears between Docs and Examples", async () => {
104 const source = await readFile(LAYOUT_OPTIONS, "utf-8");
105 const docsIndex = source.indexOf("text: 'Docs'");
106 const kbIndex = source.indexOf("text: 'Knowledge Base'");
107 const examplesIndex = source.indexOf("text: 'Examples'");
108
109 expect(docsIndex).toBeGreaterThan(-1);
110 expect(kbIndex).toBeGreaterThan(docsIndex);
111 expect(examplesIndex).toBeGreaterThan(kbIndex);
112 });
113
114 test("global search uses canonical knowledge URLs and shared source labels", async () => {
115 const source = await readFile(GLOBAL_SEARCH, "utf-8");
116 expect(source).toContain("KNOWLEDGE_SOURCE_LABELS");
117 expect(source).toContain("canonical_url");
118 expect(source).toContain("source_type");
119 expect(source).toContain("algoliaHitMetaRef.current.get(href)");
120 });
121
122 test("root meta.json entries all resolve to files or directories", async () => {
123 const metaPath = join(CONTENT_DIR, "meta.json");
124 const meta = JSON.parse(await readFile(metaPath, "utf-8"));
125 const missing: string[] = [];
126
127 for (const entry of meta.pages as string[]) {
128 if (isSeparator(entry) || isLink(entry)) continue;
129 if (entry === "...") continue;
130
131 const asFile = join(CONTENT_DIR, `${entry}.mdx`);
132 const asDir = join(CONTENT_DIR, entry);
133
134 const fileExists = await exists(asFile);
135 const dirExists = await exists(asDir);
136
137 if (!fileExists && !dirExists) {
138 missing.push(entry);
139 }
140 }
141
142 expect(missing).toEqual([]);
143 });
144
145 test("all nested meta.json entries resolve to files or directories", async () => {
146 const metaFiles = await findMetaFiles(CONTENT_DIR);
147 const errors: string[] = [];
148
149 for (const metaPath of metaFiles) {
150 const dir = dirname(metaPath);
151 const meta = JSON.parse(await readFile(metaPath, "utf-8"));
152 const relDir = relative(CONTENT_DIR, dir);
153
154 for (const entry of (meta.pages || []) as string[]) {
155 if (isSeparator(entry) || isLink(entry)) continue;
156
157 // Handle "..." (rest) entries which are valid fumadocs syntax
158 if (entry === "...") continue;
159
160 const link = entry.match(/^\[[^\]]+\]\((\/[^)]+)\)$/);
161 if (link) {
162 const target = join(CONTENT_DIR, '..', link[1].slice(1));
163 if (!await exists(`${target}.mdx`) && !await exists(join(target, 'index.mdx'))) {
164 errors.push(`${relDir}/meta.json → "${entry}" (link target not found)`);
165 }
166 continue;
167 }
168
169 const asFile = join(dir, `${entry}.mdx`);
170 const asDir = join(dir, entry);
171
172 const fileExists = await exists(asFile);
173 const dirExists = await exists(asDir);
174
175 if (!fileExists && !dirExists) {
176 errors.push(`${relDir}/meta.json → "${entry}" (no .mdx file or directory found)`);
177 }
178 }
179 }
180
181 expect(errors).toEqual([]);
182 });
183
184 test("no orphan .mdx files missing from meta.json", async () => {
185 const metaFiles = await findMetaFiles(CONTENT_DIR);
186 const orphans: string[] = [];
187
188 // Check root level
189 const rootMetaPath = join(CONTENT_DIR, "meta.json");
190 const rootMeta = JSON.parse(await readFile(rootMetaPath, "utf-8"));
191 const rootEntries = new Set(
192 (rootMeta.pages as string[]).filter((e: string) => !isSeparator(e) && e !== "...")
193 );
194 // "..." means "include everything else", so skip orphan check for root
195 if (rootEntries.has("...")) return;
196 const rootFiles = await readdir(CONTENT_DIR, { withFileTypes: true });
197
198 for (const file of rootFiles) {
199 if (file.name === "meta.json") continue;
200 const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
201 if (file.isFile() && !file.name.endsWith(".mdx")) continue;
202 if (!rootEntries.has(name)) {
203 orphans.push(`docs/${file.name}`);
204 }
205 }
206
207 // Check each nested directory that has a meta.json
208 for (const metaPath of metaFiles) {
209 if (metaPath === rootMetaPath) continue;
210 const dir = dirname(metaPath);
211 const meta = JSON.parse(await readFile(metaPath, "utf-8"));
212 const entries = new Set(
213 ((meta.pages || []) as string[]).filter((e: string) => !isSeparator(e))
214 );
215 // "..." means "include everything else", so skip orphan check
216 if (entries.has("...")) continue;
217
218 const files = await readdir(dir, { withFileTypes: true });
219 const relDir = relative(CONTENT_DIR, dir);
220
221 for (const file of files) {
222 if (file.name === "meta.json") continue;
223 const name = file.isFile() ? basename(file.name, ".mdx") : file.name;
224 if (file.isFile() && !file.name.endsWith(".mdx")) continue;
225 if (!entries.has(name)) {
226 orphans.push(`${relDir}/${file.name}`);
227 }
228 }
229 }
230
231 if (orphans.length > 0) {
232 console.warn(
233 `Found ${orphans.length} orphan file(s) not in any meta.json:\n` +
234 orphans.map((o) => ` - ${o}`).join("\n")
235 );
236 }
237 // Warn but don't fail — orphans aren't necessarily bugs
238 expect(orphans.length).toBeLessThan(20);
239 });
240 });