1
+/**
2
+ * Dashboard link policy tests.
3
+ *
4
+ * Authored content must follow three rules for Composio dashboard links:
5
+ * 1. No app.composio.dev or platform.composio.dev hosts anywhere.
6
+ * 2. Every dashboard.composio.dev link carries utm_source, utm_medium, and
7
+ * utm_campaign so sign-ups can be attributed to docs.
8
+ * 3. Any dashboard.composio.dev link with a path must be a go-link
9
+ * (/~/project/... or /~/org/...) or /login, so it resolves to the right
10
+ * page inside the user's workspace.
11
+ *
12
+ * Code fences and inline mentions are exempt from rules 2-3; rule 1 applies
13
+ * to all file content. content/reference is generated upstream and excluded.
14
+ * TS/TSX is enforced by the no-restricted-syntax rules in eslint.config.mjs.
15
+ */
16
+import { describe, test, expect } from "bun:test";
17
+import { readdir, readFile } from "fs/promises";
18
+import { join, relative } from "path";
19
+
20
+const CONTENT_DIRS = ["docs", "examples", "changelog"].map((dir) =>
21
+ join(import.meta.dir, "../../content", dir),
22
+);
23
+const CONTENT_ROOT = join(import.meta.dir, "../../content");
24
+
25
+const DASHBOARD_LINK_RE = /\]\((https:\/\/dashboard\.composio\.dev[^)\s]*)\)/g;
26
+const BANNED_HOST_RE = /(?<![a-z0-9-])(?:app|platform)\.composio\.dev/;
27
+const GO_LINK_PATH_RE = /^\/(?:~\/(?:project|org)(?:[/?#]|$)|login(?:[/?#]|$))/;
28
+const REQUIRED_PARAMS = ["utm_source=", "utm_medium=", "utm_campaign="];
29
+
30
+async function findMdxFiles(dir: string): Promise<string[]> {
31
+ const results: string[] = [];
32
+ let entries;
33
+ try {
34
+ entries = await readdir(dir, { withFileTypes: true });
35
+ } catch {
36
+ return results;
37
+ }
38
+
39
+ for (const entry of entries) {
40
+ const fullPath = join(dir, entry.name);
41
+ if (entry.isDirectory()) {
42
+ results.push(...(await findMdxFiles(fullPath)));
43
+ } else if (entry.name.endsWith(".mdx")) {
44
+ results.push(fullPath);
45
+ }
46
+ }
47
+ return results;
48
+}
49
+
50
+function dashboardLinks(content: string): { line: number; url: string }[] {
51
+ const links: { line: number; url: string }[] = [];
52
+ let inFence = false;
53
+ content.split("\n").forEach((line, index) => {
54
+ if (/^\s*(```|~~~)/.test(line)) {
55
+ inFence = !inFence;
56
+ return;
57
+ }
58
+ if (inFence) return;
59
+ for (const match of line.matchAll(DASHBOARD_LINK_RE)) {
60
+ links.push({ line: index + 1, url: match[1] });
61
+ }
62
+ });
63
+ return links;
64
+}
65
+
66
+async function collectViolations(
67
+ check: (content: string) => { line: number; url: string }[],
68
+): Promise<string[]> {
69
+ const violations: string[] = [];
70
+ for (const dir of CONTENT_DIRS) {
71
+ for (const file of await findMdxFiles(dir)) {
72
+ const content = await readFile(file, "utf-8");
73
+ for (const violation of check(content)) {
74
+ violations.push(
75
+ `${relative(CONTENT_ROOT, file)}:${violation.line} ${violation.url}`,
76
+ );
77
+ }
78
+ }
79
+ }
80
+ return violations;
81
+}
82
+
83
+describe("Content - dashboard link policy", () => {
84
+ test("no app/platform composio hosts anywhere", async () => {
85
+ const banned = await collectViolations((content) => {
86
+ const violations: { line: number; url: string }[] = [];
87
+ content.split("\n").forEach((line, index) => {
88
+ const match = line.match(BANNED_HOST_RE);
89
+ if (match) violations.push({ line: index + 1, url: match[0] });
90
+ });
91
+ return violations;
92
+ });
93
+
94
+ expect(
95
+ banned,
96
+ `banned hosts found (use dashboard go-links instead):\n${banned.join("\n")}`,
97
+ ).toEqual([]);
98
+ });
99
+
100
+ test("all dashboard links carry utm params", async () => {
101
+ const untagged = await collectViolations((content) =>
102
+ dashboardLinks(content).filter(
103
+ ({ url }) => !REQUIRED_PARAMS.every((param) => url.includes(param)),
104
+ ),
105
+ );
106
+
107
+ expect(
108
+ untagged,
109
+ `dashboard links missing utm_source=/utm_medium=/utm_campaign=:\n${untagged.join("\n")}`,
110
+ ).toEqual([]);
111
+ });
112
+
113
+ test("all dashboard links with a path are go-links or /login", async () => {
114
+ const invalid = await collectViolations((content) =>
115
+ dashboardLinks(content).filter(({ url }) => {
116
+ const path = url
117
+ .replace(/^https:\/\/dashboard\.composio\.dev/, "")
118
+ .split("?")[0];
119
+ return path !== "" && path !== "/" && !GO_LINK_PATH_RE.test(path);
120
+ }),
121
+ );
122
+
123
+ expect(
124
+ invalid,
125
+ `dashboard links must use /~/project/..., /~/org/..., or /login paths:\n${invalid.join("\n")}`,
126
+ ).toEqual([]);
127
+ });
128
+});