Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 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 | } |