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 589 lines 28 KB
Raw
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 }