@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

next
ts 168 lines 5.29 KB
Raw
1 /**
2 * Verify published KB guides against current production data.
3 *
4 * Runs from docs/: `bun run verify:kb [--check-links] [--json] [--markdown <path>]`
5 *
6 * Designed to run inside `docs-update-data.yml`, immediately after that job
7 * refreshes `public/data/toolkits.json` and the OpenAPI specs. Freshness is then
8 * checked against the same production snapshot the docs site ships, on every
9 * production deploy, rather than on a review calendar.
10 */
11
12 import { readFileSync, writeFileSync } from 'node:fs';
13 import { join } from 'node:path';
14 import { buildKbCatalog } from '@/lib/kb/catalog';
15 import { createKbArticleReader, readKbManifest } from '@/lib/kb/repository';
16 import {
17 buildProductCatalog,
18 renderVerifyReport,
19 verifyKb,
20 type CatalogToolkit,
21 type KbVerifyReport,
22 } from '@/lib/kb/verify';
23 import type { KbManifest } from '@/lib/kb/types';
24
25 const KB_ROOT = join(process.cwd(), 'kb');
26 const TOOLKITS_PATH = join(process.cwd(), 'public/data/toolkits.json');
27 const LINK_CONCURRENCY = 8;
28 const LINK_TIMEOUT_MS = 10_000;
29
30 interface CliOptions {
31 checkLinks: boolean;
32 json: boolean;
33 markdownPath: string | null;
34 warningsAsErrors: boolean;
35 }
36
37 function parseOptions(argumentsList: string[]): CliOptions {
38 const allowed = new Set([
39 '--check-links',
40 '--json',
41 '--markdown',
42 '--warnings-as-errors',
43 ]);
44 const options: CliOptions = {
45 checkLinks: argumentsList.includes('--check-links'),
46 json: argumentsList.includes('--json'),
47 markdownPath: null,
48 warningsAsErrors: argumentsList.includes('--warnings-as-errors'),
49 };
50
51 for (let index = 0; index < argumentsList.length; index += 1) {
52 const argument = argumentsList[index];
53 if (!argument?.startsWith('--')) continue;
54 if (!allowed.has(argument)) throw new Error(`Unknown option: ${argument}`);
55 if (argument === '--markdown') {
56 const value = argumentsList[index + 1];
57 if (!value || value.startsWith('--')) throw new Error('Missing path after --markdown');
58 options.markdownPath = value;
59 index += 1;
60 }
61 }
62
63 return options;
64 }
65
66 /**
67 * `buildKbCatalog` rejects expired time-sensitive guides. The verifier must still
68 * report them, so catalog assembly runs with a floor date and `verifyKb` checks
69 * every published guide's review deadline against the real clock.
70 */
71 function loadCatalogIgnoringExpiry() {
72 const manifest = readKbManifest(KB_ROOT);
73 const catalog = buildKbCatalog(
74 manifest,
75 (sourcePath) => readFileSync(join(KB_ROOT, 'source', sourcePath), 'utf8'),
76 new Date(0),
77 createKbArticleReader(join(KB_ROOT, 'articles'))
78 );
79 return catalog;
80 }
81
82 async function resolveLinkStatuses(urls: string[]): Promise<Map<string, number | 'unreachable'>> {
83 const statuses = new Map<string, number | 'unreachable'>();
84 const queue = [...urls];
85
86 async function worker(): Promise<void> {
87 for (let url = queue.shift(); url; url = queue.shift()) {
88 statuses.set(url, await probe(url));
89 }
90 }
91
92 await Promise.all(Array.from({ length: LINK_CONCURRENCY }, () => worker()));
93 return statuses;
94 }
95
96 async function probe(url: string): Promise<number | 'unreachable'> {
97 // Some provider docs reject HEAD but serve GET, so a failed HEAD is retried
98 // as a GET before the link is called dead.
99 for (const method of ['HEAD', 'GET'] as const) {
100 try {
101 const response = await fetch(url, {
102 method,
103 redirect: 'follow',
104 signal: AbortSignal.timeout(LINK_TIMEOUT_MS),
105 headers: { 'user-agent': 'composio-docs-kb-verify' },
106 });
107 if (response.ok || method === 'GET') return response.status;
108 } catch {
109 if (method === 'GET') return 'unreachable';
110 }
111 }
112 return 'unreachable';
113 }
114
115 function exitCodeFor(report: KbVerifyReport, options: CliOptions): number {
116 const failing = report.findings.filter(
117 (finding) => finding.severity === 'error' || options.warningsAsErrors
118 );
119 return failing.length ? 1 : 0;
120 }
121
122 export async function runVerifyKb(argumentsList: string[]): Promise<number> {
123 const options = parseOptions(argumentsList);
124 const catalog = loadCatalogIgnoringExpiry();
125 const toolkits = JSON.parse(readFileSync(TOOLKITS_PATH, 'utf8')) as CatalogToolkit[];
126 if (!Array.isArray(toolkits)) {
127 throw new Error('Expected public/data/toolkits.json to contain an array');
128 }
129 const productCatalog = buildProductCatalog(toolkits);
130
131 // First pass collects the external links; the network probe only runs when asked.
132 const dryRun = verifyKb({
133 manifest: catalog.manifest,
134 guides: catalog.guides,
135 catalog: productCatalog,
136 now: new Date(),
137 });
138
139 const linkStatuses = options.checkLinks
140 ? await resolveLinkStatuses(dryRun.externalLinks)
141 : undefined;
142
143 const report =
144 linkStatuses
145 ? verifyKb({
146 manifest: catalog.manifest,
147 guides: catalog.guides,
148 catalog: productCatalog,
149 now: new Date(),
150 options: { linkStatuses },
151 })
152 : dryRun;
153
154 const markdown = renderVerifyReport(report);
155 if (options.markdownPath) writeFileSync(options.markdownPath, `${markdown}\n`);
156 console.log(options.json ? JSON.stringify(report, null, 2) : markdown);
157
158 return exitCodeFor(report, options);
159 }
160
161 if (import.meta.main) {
162 runVerifyKb(process.argv.slice(2))
163 .then((code) => process.exit(code))
164 .catch((error) => {
165 console.error('Fatal error:', error);
166 process.exit(2);
167 });
168 }