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
| 1 | /** |
| 2 | * Inventories rendered examples using the same Markdown/MDX grammar as the site. |
| 3 | * Exemptions attach only to adjacent syntax nodes, never text inside code or strings. |
| 4 | */ |
| 5 | import { readdirSync, readFileSync } from 'node:fs'; |
| 6 | import { join, relative, sep } from 'node:path'; |
| 7 | import { toString } from 'mdast-util-to-string'; |
| 8 | import { FILE_BUILDS } from './file-builds'; |
| 9 | import { EXAMPLE_SOURCES, EXAMPLE_SOURCE_REASONS, EXAMPLE_BUILD_SOURCES } from './example-sources'; |
| 10 | import { z } from 'zod'; |
| 11 | import { SESSION_GUARDRAILS, DIRECT_EXECUTION_GUARDRAILS } from './llm-guardrails'; |
| 12 | import { apiCodeUsages } from './api-code-usages'; |
| 13 | import { attributeValue, markdownLanguageGroups, parseExampleDocument, type ExampleNode } from './example-document'; |
| 14 | |
| 15 | export type CodeExampleRule = |
| 16 | | 'language-items' |
| 17 | | 'language-empty-tab' |
| 18 | | 'language-cross-fence' |
| 19 | | 'standalone-sdk-fence' |
| 20 | | 'standalone-api-fence' |
| 21 | | 'marker-invalid' |
| 22 | | 'api-missing' |
| 23 | | 'example-syntax' |
| 24 | | 'external-example'; |
| 25 | |
| 26 | export type CodeExampleViolation = { path: string; line: number; rule: CodeExampleRule; message: string }; |
| 27 | export type CodeExampleFile = { path: string; source: string }; |
| 28 | |
| 29 | export type MarkerUnit = { |
| 30 | type: 'marker'; |
| 31 | line: number; |
| 32 | form: 'mdx' | 'html'; |
| 33 | kind: string | undefined; |
| 34 | reason: string | undefined; |
| 35 | wellFormed: boolean; |
| 36 | api?: { rule: string; operation: string; field?: string }; |
| 37 | }; |
| 38 | |
| 39 | export type FenceUnit = { |
| 40 | type: 'fence'; |
| 41 | line: number; |
| 42 | lang: string; |
| 43 | info: string; |
| 44 | code: string; |
| 45 | markers: MarkerUnit[]; |
| 46 | }; |
| 47 | |
| 48 | export type ComponentUnit = { |
| 49 | type: 'package-install' | 'callout' | 'table' | 'external'; |
| 50 | line: number; |
| 51 | markers: MarkerUnit[]; |
| 52 | content?: string; |
| 53 | name?: string; |
| 54 | source?: string; |
| 55 | }; |
| 56 | |
| 57 | export type TabUnit = { |
| 58 | type: 'tab'; |
| 59 | line: number; |
| 60 | value: string | undefined; |
| 61 | markers: MarkerUnit[]; |
| 62 | children: CodeExampleUnit[]; |
| 63 | }; |
| 64 | |
| 65 | export type TabsUnit = { |
| 66 | type: 'tabs'; |
| 67 | line: number; |
| 68 | groupId: string | undefined; |
| 69 | items: string[] | undefined; |
| 70 | markers: MarkerUnit[]; |
| 71 | children: CodeExampleUnit[]; |
| 72 | }; |
| 73 | |
| 74 | export type CodeExampleUnit = MarkerUnit | FenceUnit | ComponentUnit | TabUnit | TabsUnit; |
| 75 | export type ParsedCodeExamples = { path: string; units: CodeExampleUnit[] }; |
| 76 | |
| 77 | const MARKER_TARGETS: Record<string, string> = { |
| 78 | 'single-language': 'a standalone example or a non-language <Tabs>', |
| 79 | 'single-language-page': 'a page about a language-specific framework', |
| 80 | 'no-api': 'a language group with no HTTP equivalent', |
| 81 | 'unchecked-api': 'a shell fence, scoped by rule and operation', |
| 82 | }; |
| 83 | const PYTHON_LANGS: Record<string, true> = { python: true, py: true }; |
| 84 | const TYPESCRIPT_LANGS: Record<string, true> = { typescript: true, ts: true, tsx: true, javascript: true, js: true }; |
| 85 | const SDK_LANGS: Record<string, true> = { ...PYTHON_LANGS, ...TYPESCRIPT_LANGS }; |
| 86 | const SHELL_LANGS: Record<string, true> = { bash: true, sh: true, shell: true, curl: true }; |
| 87 | const NO_LANGS: Record<string, true> = {}; |
| 88 | const CANONICAL_ITEMS = [['Python', 'TypeScript'], ['Python', 'TypeScript', 'API']]; |
| 89 | const VERSION_SUFFIX_RE = /^\(.+\)$|^v\d+$/; |
| 90 | |
| 91 | function parseMarker(body: string, form: MarkerUnit['form'], line: number): MarkerUnit { |
| 92 | const match = /^\s*code-example:\s*(\S+)\s*([\s\S]*)$/.exec(body); |
| 93 | const attributes: Record<string, string> = {}; |
| 94 | let remainder = match?.[2] ?? ''; |
| 95 | let wellFormed = Boolean(match); |
| 96 | while (remainder.trim()) { |
| 97 | const attribute = /^\s*([a-z-]+)="([^"]*)"\s*/.exec(remainder); |
| 98 | if (!attribute || Object.hasOwn(attributes, attribute[1])) { |
| 99 | wellFormed = false; |
| 100 | break; |
| 101 | } |
| 102 | attributes[attribute[1]] = attribute[2]; |
| 103 | remainder = remainder.slice(attribute[0].length); |
| 104 | } |
| 105 | const kind = match?.[1]; |
| 106 | const allowed = kind === 'unchecked-api' ? ['reason', 'rule', 'operation', 'field'] : ['reason']; |
| 107 | wellFormed &&= Object.keys(attributes).every((key) => allowed.includes(key)); |
| 108 | const marker: MarkerUnit = { type: 'marker', line, form, kind, reason: attributes.reason, wellFormed }; |
| 109 | if (kind === 'unchecked-api') { |
| 110 | wellFormed &&= Boolean(attributes.rule && attributes.operation); |
| 111 | marker.wellFormed = wellFormed; |
| 112 | marker.api = { rule: attributes.rule ?? '', operation: attributes.operation ?? '', ...(attributes.field ? { field: attributes.field } : {}) }; |
| 113 | } |
| 114 | return marker; |
| 115 | } |
| 116 | |
| 117 | |
| 118 | function markerFromNode(node: ExampleNode): MarkerUnit | undefined { |
| 119 | let body: string | undefined; |
| 120 | if (node.type === 'mdxFlowExpression' || node.type === 'mdxTextExpression') { |
| 121 | body = /^\s*\/\*\s*(code-example:[\s\S]*?)\*\/\s*$/.exec(node.value)?.[1]; |
| 122 | } else if (node.type === 'html') { |
| 123 | body = /^\s*<!--\s*(code-example:[\s\S]*?)-->\s*$/.exec(node.value)?.[1]; |
| 124 | } |
| 125 | return body === undefined ? undefined : parseMarker(body, node.type === 'html' ? 'html' : 'mdx', node.position?.start.line ?? 1); |
| 126 | } |
| 127 | |
| 128 | /** Parses only real syntax nodes; arbitrary wrappers preserve their nested examples. */ |
| 129 | export function parseCodeExamples(source: string, path: string): ParsedCodeExamples { |
| 130 | const tree = parseExampleDocument(source, path); |
| 131 | const convert = (nodes: readonly ExampleNode[], fragment = source): CodeExampleUnit[] => { |
| 132 | const units: CodeExampleUnit[] = []; |
| 133 | let pending: MarkerUnit[] = []; |
| 134 | let pendingEnd = 0; |
| 135 | const flush = () => { units.push(...pending); pending = []; }; |
| 136 | for (const node of nodes) { |
| 137 | const line = node.position?.start.line ?? 1; |
| 138 | const marker = markerFromNode(node); |
| 139 | if (marker) { |
| 140 | if (marker.kind === 'single-language-page') { |
| 141 | flush(); |
| 142 | units.push(marker); |
| 143 | } else { |
| 144 | if (pending.length && fragment.slice(pendingEnd, node.position?.start.offset).trim()) flush(); |
| 145 | pending.push(marker); |
| 146 | pendingEnd = node.position?.end.offset ?? 0; |
| 147 | } |
| 148 | continue; |
| 149 | } |
| 150 | const adjacent = pending.length && !fragment.slice(pendingEnd, node.position?.start.offset).trim(); |
| 151 | const markers = adjacent ? pending : []; |
| 152 | if (adjacent) pending = []; |
| 153 | else flush(); |
| 154 | if (node.type === 'code') { |
| 155 | units.push({ type: 'fence', line, lang: (node.lang ?? '').toLowerCase(), info: [node.lang, node.meta].filter(Boolean).join(' '), code: node.value, markers }); |
| 156 | } else if (node.type === 'table') { |
| 157 | units.push({ type: 'table', line, markers, content: toString(node) }); |
| 158 | } else if (node.type === 'mdxJsxFlowElement' || node.type === 'mdxJsxTextElement') { |
| 159 | const value = attributeValue(node, 'value'); |
| 160 | const groupId = attributeValue(node, 'groupId'); |
| 161 | const items = attributeValue(node, 'items'); |
| 162 | if (node.name === 'Tabs') { |
| 163 | units.push({ type: 'tabs', line, groupId: typeof groupId === 'string' ? groupId : undefined, items: Array.isArray(items) ? items : undefined, markers, children: convert(node.children, fragment) }); |
| 164 | } else if (node.name === 'Tab') { |
| 165 | units.push({ type: 'tab', line, value: typeof value === 'string' ? value : undefined, markers, children: convert(node.children, fragment) }); |
| 166 | } else if (node.name === 'Callout' || node.name === 'PackageInstall') { |
| 167 | units.push({ type: node.name === 'Callout' ? 'callout' : 'package-install', line, markers, content: toString(node) }); |
| 168 | units.push(...convert(node.children, fragment)); |
| 169 | } else if (node.name === 'FileBuildup' || node.name === 'RepoBrowser') { |
| 170 | const key = attributeValue(node, node.name === 'FileBuildup' ? 'name' : 'source'); |
| 171 | units.push({ type: 'external', line, markers, name: node.name, source: typeof key === 'string' ? key : node.name === 'RepoBrowser' ? 'slack-bot' : undefined }); |
| 172 | } else { |
| 173 | units.push(...markers, ...convert(node.children, fragment)); |
| 174 | } |
| 175 | } else if (node.type === 'blockquote' && /^\[!NOTE\](?:\s|$)/.test(toString(node))) { |
| 176 | units.push({ type: 'callout', line, markers, content: toString(node).replace(/^\[!NOTE\]\s*/, '') }); |
| 177 | units.push(...convert(node.children, fragment)); |
| 178 | } else if ('children' in node) { |
| 179 | units.push(...markers, ...convert(node.children, fragment)); |
| 180 | } else { |
| 181 | units.push(...markers); |
| 182 | } |
| 183 | } |
| 184 | flush(); |
| 185 | return units; |
| 186 | }; |
| 187 | if (!path.endsWith('.md')) return { path, units: convert(tree.children) }; |
| 188 | const groups = markdownLanguageGroups(source); |
| 189 | if (!groups.length) return { path, units: convert(tree.children) }; |
| 190 | const units: CodeExampleUnit[] = []; |
| 191 | let offset = 0; |
| 192 | const shiftLines = (children: CodeExampleUnit[], delta: number) => walkCodeExamples(children, (unit) => { |
| 193 | unit.line += delta; |
| 194 | if ('markers' in unit) for (const marker of unit.markers) marker.line += delta; |
| 195 | }); |
| 196 | for (const group of groups) { |
| 197 | const before = source.slice(offset, group.start); |
| 198 | const beforeNodes = parseExampleDocument(before, 'part.md').children; |
| 199 | const markers: MarkerUnit[] = []; |
| 200 | let end = before.length; |
| 201 | for (const node of [...beforeNodes].reverse()) { |
| 202 | const marker = markerFromNode(node); |
| 203 | const nodeEnd = node.position?.end.offset; |
| 204 | if (!marker || nodeEnd === undefined || before.slice(nodeEnd, end).trim()) break; |
| 205 | markers.unshift(marker); |
| 206 | end = node.position!.start.offset!; |
| 207 | } |
| 208 | const beforeUnits = convert(beforeNodes.slice(0, beforeNodes.length - markers.length), before); |
| 209 | const lineOffset = source.slice(0, offset).split('\n').length - 1; |
| 210 | shiftLines(beforeUnits, lineOffset); |
| 211 | for (const marker of markers) marker.line += lineOffset; |
| 212 | units.push(...beforeUnits); |
| 213 | const tabs: TabsUnit = { type: 'tabs', line: group.line, groupId: 'language', items: group.tabs.map((tab) => tab.value), markers, children: [] }; |
| 214 | for (const tab of group.tabs) { |
| 215 | const children = parseCodeExamples(tab.source, 'part.md').units; |
| 216 | shiftLines(children, tab.line - 1); |
| 217 | tabs.children.push({ type: 'tab', line: tab.line, value: tab.value, markers: [], children }); |
| 218 | } |
| 219 | units.push(tabs); |
| 220 | offset = group.end; |
| 221 | } |
| 222 | const tail = source.slice(offset); |
| 223 | const trailing = convert(parseExampleDocument(tail, 'part.md').children, tail); |
| 224 | const lineOffset = source.slice(0, offset).split('\n').length - 1; |
| 225 | shiftLines(trailing, lineOffset); |
| 226 | units.push(...trailing); |
| 227 | return { path, units }; |
| 228 | } |
| 229 | |
| 230 | /** |
| 231 | * Visits every unit depth-first in document order. `ancestors` is the enclosing |
| 232 | * Tabs/Tab chain, outermost first; it is never mutated, so visitors may keep it. |
| 233 | */ |
| 234 | export function walkCodeExamples( |
| 235 | units: CodeExampleUnit[], |
| 236 | visit: (unit: CodeExampleUnit, ancestors: (TabsUnit | TabUnit)[]) => void, |
| 237 | ancestors: (TabsUnit | TabUnit)[] = [], |
| 238 | ): void { |
| 239 | for (const unit of units) { |
| 240 | visit(unit, ancestors); |
| 241 | if (unit.type === 'tab' || unit.type === 'tabs') walkCodeExamples(unit.children, visit, [...ancestors, unit]); |
| 242 | } |
| 243 | } |
| 244 | |
| 245 | function descendants(units: CodeExampleUnit[]): CodeExampleUnit[] { |
| 246 | const out: CodeExampleUnit[] = []; |
| 247 | walkCodeExamples(units, (unit) => out.push(unit)); |
| 248 | return out; |
| 249 | } |
| 250 | |
| 251 | const hasMarker = (markers: MarkerUnit[], kind: string) => markers.some((marker) => marker.kind === kind); |
| 252 | const formatItems = (items: string[]) => `[${items.map((item) => `'${item}'`).join(', ')}]`; |
| 253 | |
| 254 | /** Returns the shared suffix when items are a versioned `['Python <S>', 'TypeScript <S>']` pair. */ |
| 255 | function versionSuffix(items: string[] | undefined): string | undefined { |
| 256 | if (!items || ![2, 3].includes(items.length) || !items[0].startsWith('Python ') || !items[1].startsWith('TypeScript ') || |
| 257 | (items.length === 3 && items[2] !== 'API')) { |
| 258 | return undefined; |
| 259 | } |
| 260 | const suffix = items[0].slice('Python '.length); |
| 261 | return suffix === items[1].slice('TypeScript '.length) && VERSION_SUFFIX_RE.test(suffix) ? suffix : undefined; |
| 262 | } |
| 263 | |
| 264 | function validLanguageItems(items: string[] | undefined): boolean { |
| 265 | if (!items) return false; |
| 266 | return ( |
| 267 | CANONICAL_ITEMS.some( |
| 268 | (canonical) => canonical.length === items.length && canonical.every((item, i) => item === items[i]), |
| 269 | ) || versionSuffix(items) !== undefined |
| 270 | ); |
| 271 | } |
| 272 | |
| 273 | function checkFile(parsed: ParsedCodeExamples, requireApi: boolean): CodeExampleViolation[] { |
| 274 | const violations: CodeExampleViolation[] = []; |
| 275 | const report = (line: number, rule: CodeExampleRule, message: string) => |
| 276 | violations.push({ path: parsed.path, line, rule, message }); |
| 277 | const pageMarker = descendants(parsed.units).some( |
| 278 | (unit) => unit.type === 'marker' && unit.kind === 'single-language-page', |
| 279 | ); |
| 280 | |
| 281 | /** Reports marker problems; `appliesTo` says whether the marker's kind fits the construct it precedes. */ |
| 282 | const checkMarkers = (markers: MarkerUnit[], appliesTo: (kind: string) => boolean) => { |
| 283 | for (const marker of markers) { |
| 284 | if (!marker.kind || !Object.hasOwn(MARKER_TARGETS, marker.kind)) { |
| 285 | report( |
| 286 | marker.line, |
| 287 | 'marker-invalid', |
| 288 | `unknown code-example marker kind "${marker.kind ?? ''}"; expected one of ${Object.keys(MARKER_TARGETS).join(', ')}`, |
| 289 | ); |
| 290 | continue; |
| 291 | } |
| 292 | if (!marker.wellFormed || !marker.reason?.trim()) { |
| 293 | report(marker.line, 'marker-invalid', `code-example ${marker.kind} marker needs a non-empty reason="..."`); |
| 294 | } |
| 295 | if (!appliesTo(marker.kind)) { |
| 296 | report( |
| 297 | marker.line, |
| 298 | 'marker-invalid', |
| 299 | `code-example ${marker.kind} marker must be directly followed (only blank lines between) by ${MARKER_TARGETS[marker.kind]}`, |
| 300 | ); |
| 301 | } |
| 302 | } |
| 303 | }; |
| 304 | |
| 305 | const checkLanguageGroup = (tabs: TabsUnit) => { |
| 306 | const items = tabs.items; |
| 307 | if (!validLanguageItems(items)) { |
| 308 | report( |
| 309 | tabs.line, |
| 310 | 'language-items', |
| 311 | `language Tabs items must be ['Python', 'TypeScript'], ['Python', 'TypeScript', 'API'], or a versioned pair ['Python <S>', 'TypeScript <S>']; got ${items ? formatItems(items) : 'missing or non-literal items'}`, |
| 312 | ); |
| 313 | } |
| 314 | const tabUnits = tabs.children.filter((unit): unit is TabUnit => unit.type === 'tab'); |
| 315 | const seen = new Set<string>(); |
| 316 | for (const tab of tabUnits) { |
| 317 | if (tab.value === undefined) { |
| 318 | report(tab.line, 'language-items', '<Tab> in a language group has no value'); |
| 319 | } else if (seen.has(tab.value)) { |
| 320 | report(tab.line, 'language-items', `duplicate <Tab value="${tab.value}">`); |
| 321 | } else { |
| 322 | seen.add(tab.value); |
| 323 | if (items && !items.includes(tab.value)) { |
| 324 | report(tab.line, 'language-items', `<Tab value="${tab.value}"> is not one of items ${formatItems(items)}`); |
| 325 | } |
| 326 | } |
| 327 | } |
| 328 | for (const item of items ?? []) { |
| 329 | if (!seen.has(item)) report(tabs.line, 'language-items', `item '${item}' has no matching <Tab>`); |
| 330 | } |
| 331 | |
| 332 | for (const tab of tabUnits) { |
| 333 | const content = descendants(tab.children); |
| 334 | const fences = content.filter((unit): unit is FenceUnit => unit.type === 'fence'); |
| 335 | const hasCallout = content.some((unit) => unit.type === 'callout' && Boolean(unit.content?.trim())); |
| 336 | if (fences.some((fence) => !fence.code.trim()) || |
| 337 | (!fences.length && !hasCallout && !content.some((unit) => unit.type === 'package-install' || unit.type === 'table'))) { |
| 338 | report( |
| 339 | tab.line, |
| 340 | 'language-empty-tab', |
| 341 | `<Tab value="${tab.value ?? ''}"> has no code fence, Markdown table, <PackageInstall>, or <Callout>`, |
| 342 | ); |
| 343 | continue; |
| 344 | } |
| 345 | const value = tab.value ?? ''; |
| 346 | const forbidden = |
| 347 | value === 'API' |
| 348 | ? SDK_LANGS |
| 349 | : value.startsWith('Python') |
| 350 | ? TYPESCRIPT_LANGS |
| 351 | : value.startsWith('TypeScript') |
| 352 | ? PYTHON_LANGS |
| 353 | : NO_LANGS; |
| 354 | for (const fence of fences) { |
| 355 | if (forbidden[fence.lang] === true) { |
| 356 | report(fence.line, 'language-cross-fence', `\`${fence.lang}\` fence inside <Tab value="${value}">`); |
| 357 | } |
| 358 | } |
| 359 | const sdkLanguages = value.startsWith('Python') ? PYTHON_LANGS : value.startsWith('TypeScript') ? TYPESCRIPT_LANGS : undefined; |
| 360 | const shellInstructions = fences.every((fence) => { |
| 361 | if (!SHELL_LANGS[fence.lang]) return true; |
| 362 | const install = /(?:^|\n)\s*(?:pip(?:3)? install|python(?:3(?:\.\d+)?)? -m (?:pip install|venv)|npm (?:install|i)|pnpm add|bun add|yarn add|uv (?:add|pip install))\b/.test(fence.code); |
| 363 | const run = value.startsWith('Python') ? /(?:^|\n)\s*(?:python(?:3(?:\.\d+)?)?|uv run python)\s+(?:\S+\.py\b|-[cm]\s)/.test(fence.code) : |
| 364 | value.startsWith('TypeScript') && /(?:^|\n)\s*(?:npx (?:tsx|ts-node)|bun|node)\s+(?:--input-type=module\s+)?(?:\S+\.(?:ts|js)\b|-e\s)/.test(fence.code); |
| 365 | return install || run; |
| 366 | }); |
| 367 | if (sdkLanguages && !hasCallout && !content.some((unit) => unit.type === 'table' || unit.type === 'package-install') && |
| 368 | !fences.some((fence) => sdkLanguages[fence.lang]) && |
| 369 | !shellInstructions && fences.some((fence) => SHELL_LANGS[fence.lang])) { |
| 370 | report(tab.line, 'language-cross-fence', `<Tab value="${value}"> contains shell operations instead of a ${value} example`); |
| 371 | } |
| 372 | if (value === 'API' && !hasCallout && !fences.some((fence) => fence.lang === 'bash')) { |
| 373 | report(tab.line, 'language-cross-fence', '<Tab value="API"> must contain a bash fence or a <Callout>'); |
| 374 | } |
| 375 | } |
| 376 | |
| 377 | // Install-only groups (PackageInstall, pip/npm commands) have no API counterpart. |
| 378 | const hasSdkFence = descendants(tabs.children).some((unit) => unit.type === 'fence' && SDK_LANGS[unit.lang] === true); |
| 379 | if ( |
| 380 | requireApi && |
| 381 | hasSdkFence && |
| 382 | !items?.includes('API') && |
| 383 | !hasMarker(tabs.markers, 'no-api') |
| 384 | ) { |
| 385 | report( |
| 386 | tabs.line, |
| 387 | 'api-missing', |
| 388 | `language Tabs has no 'API' item; add an API tab or a {/* code-example: no-api reason="..." */} marker`, |
| 389 | ); |
| 390 | } |
| 391 | }; |
| 392 | |
| 393 | const walk = (units: CodeExampleUnit[], inLanguage: boolean, enclosingTabs: TabsUnit | undefined) => { |
| 394 | for (const unit of units) { |
| 395 | switch (unit.type) { |
| 396 | case 'marker': |
| 397 | checkMarkers([unit], (kind) => kind === 'single-language-page'); |
| 398 | break; |
| 399 | case 'fence': { |
| 400 | const standaloneSdk = SDK_LANGS[unit.lang] === true && !inLanguage; |
| 401 | const standaloneApi = SHELL_LANGS[unit.lang] === true && /\bcurl\b[\s\S]*(?:backend\.composio\.dev|\$COMPOSIO_BASE_URL)/.test(unit.code) && !inLanguage; |
| 402 | checkMarkers(unit.markers, (kind) => |
| 403 | kind === 'single-language' ? standaloneSdk || standaloneApi : kind === 'unchecked-api' && SHELL_LANGS[unit.lang] === true, |
| 404 | ); |
| 405 | if ( |
| 406 | standaloneSdk && |
| 407 | !pageMarker && |
| 408 | !hasMarker(unit.markers, 'single-language') && |
| 409 | !(enclosingTabs && hasMarker(enclosingTabs.markers, 'single-language')) |
| 410 | ) { |
| 411 | report( |
| 412 | unit.line, |
| 413 | 'standalone-sdk-fence', |
| 414 | `\`${unit.lang}\` fence outside a <Tabs groupId="language"> group; pair it with the other SDK or add a code-example single-language marker`, |
| 415 | ); |
| 416 | } |
| 417 | if (standaloneApi && !hasMarker(unit.markers, 'single-language')) { |
| 418 | report(unit.line, 'standalone-api-fence', 'Composio curl example needs Python, TypeScript, and API options; use SDK-gap Callouts for unavailable operations'); |
| 419 | } |
| 420 | break; |
| 421 | } |
| 422 | case 'tabs': { |
| 423 | const isLanguage = unit.groupId === 'language'; |
| 424 | checkMarkers(unit.markers, (kind) => (isLanguage ? kind === 'no-api' : kind === 'single-language')); |
| 425 | if (isLanguage) checkLanguageGroup(unit); |
| 426 | walk(unit.children, inLanguage || isLanguage, unit); |
| 427 | break; |
| 428 | } |
| 429 | case 'tab': |
| 430 | checkMarkers(unit.markers, () => false); |
| 431 | walk(unit.children, inLanguage, enclosingTabs); |
| 432 | break; |
| 433 | case 'external': { |
| 434 | checkMarkers(unit.markers, (kind) => kind === 'single-language'); |
| 435 | const exists = unit.name === 'FileBuildup' |
| 436 | ? unit.source !== undefined && Object.hasOwn(FILE_BUILDS, unit.source) |
| 437 | : unit.source !== undefined && Object.hasOwn(EXAMPLE_SOURCES, unit.source); |
| 438 | if (!exists) report(unit.line, 'external-example', `${unit.name} must select an inventoried static source`); |
| 439 | const framework = unit.name === 'FileBuildup' ? EXAMPLE_BUILD_SOURCES[unit.source ?? ''] : unit.source; |
| 440 | if (!framework || !Object.hasOwn(EXAMPLE_SOURCE_REASONS, framework)) { |
| 441 | report(unit.line, 'external-example', `${unit.name} needs a registered language-specific runtime or language alternatives`); |
| 442 | } |
| 443 | break; |
| 444 | } |
| 445 | default: |
| 446 | checkMarkers(unit.markers, () => false); |
| 447 | } |
| 448 | } |
| 449 | }; |
| 450 | |
| 451 | walk(parsed.units, false, undefined); |
| 452 | return violations; |
| 453 | } |
| 454 | |
| 455 | /** Checks every file and returns violations sorted by path, line, rule, and message. */ |
| 456 | export function checkCodeExamples( |
| 457 | files: readonly CodeExampleFile[], |
| 458 | options: { requireApi: boolean }, |
| 459 | ): CodeExampleViolation[] { |
| 460 | return files.flatMap((file): CodeExampleViolation[] => { |
| 461 | try { |
| 462 | return checkFile(parseCodeExamples(file.source, file.path), options.requireApi); |
| 463 | } catch (error) { |
| 464 | return [{ path: file.path, line: 1, rule: 'example-syntax', message: String(error) }]; |
| 465 | } |
| 466 | }) |
| 467 | .sort( |
| 468 | (a, b) => |
| 469 | a.path.localeCompare(b.path) || |
| 470 | a.line - b.line || |
| 471 | a.rule.localeCompare(b.rule) || |
| 472 | a.message.localeCompare(b.message), |
| 473 | ); |
| 474 | } |
| 475 | |
| 476 | // Generated copies are inventoried below; their canonical authored inputs are checked once. |
| 477 | const SCOPE_DIRS = ['content/docs', 'content/examples', 'content/reference', 'content/toolkits', 'api-overviews', 'kb/source', 'kb/articles']; |
| 478 | const EXCLUDED_DIRS = ['content/reference/sdk-reference', 'content/reference/api-reference', 'content/reference/v3/api-reference']; |
| 479 | |
| 480 | /** Lists authored `.md`/`.mdx` pages in code example scope, with paths relative to `docsRoot`. */ |
| 481 | export function listCodeExampleFiles(docsRoot: string): CodeExampleFile[] { |
| 482 | const files: CodeExampleFile[] = []; |
| 483 | const visit = (dir: string) => { |
| 484 | const entries = readdirSync(dir, { withFileTypes: true }); |
| 485 | for (const entry of entries) { |
| 486 | const fullPath = join(dir, entry.name); |
| 487 | const path = relative(docsRoot, fullPath).split(sep).join('/'); |
| 488 | if (entry.isDirectory()) { |
| 489 | if (!EXCLUDED_DIRS.includes(path)) visit(fullPath); |
| 490 | } else if (/\.mdx?$/.test(entry.name)) { |
| 491 | files.push({ path, source: readFileSync(fullPath, 'utf8') }); |
| 492 | } |
| 493 | } |
| 494 | }; |
| 495 | for (const dir of SCOPE_DIRS) visit(join(docsRoot, dir)); |
| 496 | for (const [name, source] of [['session', SESSION_GUARDRAILS], ['direct-execution', DIRECT_EXECUTION_GUARDRAILS]]) { |
| 497 | const path = `lib/llm-guardrails/${name}.ts`; |
| 498 | const declaration = readFileSync(join(docsRoot, path), 'utf8').split('\n').findIndex((line) => line.startsWith('export const ')); |
| 499 | if (declaration < 0) throw new Error(`${path} has no guardrail declaration`); |
| 500 | // A Markdown projection of a TS template literal; padding retains source line numbers. |
| 501 | files.push({ path: `${path}#rendered.md`, source: '\n'.repeat(declaration) + source }); |
| 502 | } |
| 503 | return files.sort((a, b) => a.path.localeCompare(b.path)); |
| 504 | } |
| 505 | |
| 506 | |
| 507 | export type CodeExampleInventoryEntry = { |
| 508 | path: string; |
| 509 | line: number; |
| 510 | kind: string; |
| 511 | language?: string; |
| 512 | options: string[]; |
| 513 | validation: 'maintained' | 'generated-copy' | 'symbol-reference' | 'historical' | 'framework-source'; |
| 514 | reason?: string; |
| 515 | }; |
| 516 | |
| 517 | /** Includes published Markdown surfaces and every committed file-backed example. */ |
| 518 | export function inventoryCodeExamples(docsRoot: string): CodeExampleInventoryEntry[] { |
| 519 | const entries: CodeExampleInventoryEntry[] = []; |
| 520 | const maintained = new Set(listCodeExampleFiles(docsRoot).map((file) => file.path)); |
| 521 | const visit = (directory: string) => { |
| 522 | for (const entry of readdirSync(directory, { withFileTypes: true })) { |
| 523 | const full = join(directory, entry.name); |
| 524 | if (entry.isDirectory()) visit(full); |
| 525 | else if (/\.mdx?$/.test(entry.name)) { |
| 526 | const path = relative(docsRoot, full).split(sep).join('/'); |
| 527 | const parsed = parseCodeExamples(readFileSync(full, 'utf8'), path); |
| 528 | const pageReason = descendants(parsed.units).find((unit) => unit.type === 'marker' && unit.kind === 'single-language-page'); |
| 529 | walkCodeExamples(parsed.units, (unit, ancestors) => { |
| 530 | if (unit.type !== 'fence' && unit.type !== 'external' && unit.type !== 'package-install') return; |
| 531 | const group = ancestors.findLast((ancestor) => ancestor.type === 'tabs' && ancestor.groupId === 'language'); |
| 532 | const validation = maintained.has(path) ? 'maintained' : path.startsWith('content/changelog/') ? 'historical' : |
| 533 | path.startsWith('content/reference/sdk-reference/') ? 'symbol-reference' : 'generated-copy'; |
| 534 | const marker = unit.markers.find((item) => item.reason) ?? (pageReason?.type === 'marker' ? pageReason : undefined); |
| 535 | const reason = marker?.reason ?? (validation === 'symbol-reference' |
| 536 | ? 'Language-specific SDK symbol documentation includes signatures and partial API usage; maintained cross-language operation examples live in the guides' |
| 537 | : validation === 'historical' ? 'Immutable release history is inventoried, not rewritten as current API guidance' |
| 538 | : validation === 'generated-copy' ? 'Generated presentation; canonical api-overviews or kb/source content is checked' : undefined); |
| 539 | entries.push({ path, line: unit.line, kind: unit.type === 'external' ? unit.name ?? 'external' : unit.type, |
| 540 | ...(unit.type === 'fence' ? { language: unit.lang } : {}), options: group?.type === 'tabs' ? group.items ?? [] : [], validation, |
| 541 | ...(reason ? { reason } : {}) }); |
| 542 | }); |
| 543 | } |
| 544 | } |
| 545 | }; |
| 546 | for (const directory of ['content', 'api-overviews', 'kb/source', 'kb/articles']) visit(join(docsRoot, directory)); |
| 547 | for (const file of listCodeExampleFiles(docsRoot).filter((entry) => entry.path.includes('#rendered.md'))) { |
| 548 | walkCodeExamples(parseCodeExamples(file.source, file.path).units, (unit, ancestors) => { |
| 549 | if (unit.type !== 'fence') return; |
| 550 | const group = ancestors.findLast((ancestor) => ancestor.type === 'tabs' && ancestor.groupId === 'language'); |
| 551 | entries.push({ path: file.path, line: unit.line, kind: 'agent Markdown fence', language: unit.lang, |
| 552 | options: group?.type === 'tabs' ? group.items ?? [] : [], validation: 'maintained' }); |
| 553 | }); |
| 554 | } |
| 555 | const specSchema = z.object({ |
| 556 | paths: z.record(z.string(), z.record(z.string(), z.unknown())).optional(), |
| 557 | webhooks: z.record(z.string(), z.record(z.string(), z.unknown())).optional(), |
| 558 | }); |
| 559 | for (const filename of ['openapi.json', 'openapi-v3.json', 'openapi-webhooks.json']) { |
| 560 | const spec = specSchema.parse(JSON.parse(readFileSync(join(docsRoot, 'public', filename), 'utf8'))); |
| 561 | for (const [section, paths] of Object.entries(spec)) { |
| 562 | for (const [path, methods] of Object.entries(paths ?? {})) { |
| 563 | for (const method of Object.keys(methods)) { |
| 564 | if (!['get', 'post', 'put', 'patch', 'delete', 'head', 'options'].includes(method)) continue; |
| 565 | entries.push({ path: `public/${filename}#/${section}/${path}/${method}`, line: 1, |
| 566 | kind: 'generated API operation', options: [...apiCodeUsages.map().values()].map((generator) => generator.label ?? generator.lang), validation: 'generated-copy', |
| 567 | reason: 'Request examples are generated directly from this OpenAPI operation by the shared API reference code-usage registry' }); |
| 568 | } |
| 569 | } |
| 570 | } |
| 571 | } |
| 572 | for (const [name, build] of Object.entries(FILE_BUILDS)) { |
| 573 | const framework = EXAMPLE_BUILD_SOURCES[name]; |
| 574 | if (!framework) throw new Error(`FileBuildup ${name} has no documented source runtime`); |
| 575 | for (const [index] of build.stages.entries()) { |
| 576 | entries.push({ path: `lib/file-builds.ts#${name}/${index + 1}/${build.file}`, line: 1, kind: 'FileBuildup source', |
| 577 | language: build.file.endsWith('.py') ? 'python' : 'typescript', options: [], validation: 'framework-source', |
| 578 | reason: EXAMPLE_SOURCE_REASONS[framework] }); |
| 579 | } |
| 580 | } |
| 581 | for (const [name, files] of Object.entries(EXAMPLE_SOURCES)) { |
| 582 | for (const file of files) { |
| 583 | entries.push({ path: `lib/${name}-source.json#${file.path}`, line: 1, kind: 'RepoBrowser source', options: [], |
| 584 | language: file.path.endsWith('.py') ? 'python' : /\.(?:ts|tsx|js)$/.test(file.path) ? 'typescript' : 'text', |
| 585 | validation: 'framework-source', reason: EXAMPLE_SOURCE_REASONS[name as keyof typeof EXAMPLE_SOURCE_REASONS] }); |
| 586 | } |
| 587 | } |
| 588 | return entries.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line); |
| 589 | } |