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 | * Compile every rendered Python fence (including exempted/legacy examples) and |
| 3 | * type-check current SDK examples against the local Python SDK and providers. |
| 4 | * |
| 5 | * The Python helper attributes diagnostics using mypy's resolved AST symbols |
| 6 | * and fully qualified types, not error-message class names. SDK call, |
| 7 | * attribute, import, TypedDict, SDK-model indexing, SDK-result assignment, and |
| 8 | * misspelled SDK-binding errors fail the gate; unrelated Python/third-party |
| 9 | * errors are returned separately by the helper. A `# type: ignore` must name |
| 10 | * its codes, carry an explanation, and still suppress an error. |
| 11 | * |
| 12 | * Requires uv and the locked python/pyproject.toml docs-snippets group. |
| 13 | */ |
| 14 | import { spawnSync } from 'node:child_process'; |
| 15 | import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'; |
| 16 | import { tmpdir } from 'node:os'; |
| 17 | import { join } from 'node:path'; |
| 18 | import { fileURLToPath } from 'node:url'; |
| 19 | import { z } from 'zod'; |
| 20 | import { |
| 21 | listCodeExampleFiles, |
| 22 | parseCodeExamples, |
| 23 | walkCodeExamples, |
| 24 | type CodeExampleFile, |
| 25 | } from '../lib/code-examples'; |
| 26 | |
| 27 | export type PythonSnippet = { |
| 28 | /** Module name for the temp file; unique per run. */ |
| 29 | id: string; |
| 30 | path: string; |
| 31 | /** Line of the opening fence; snippet line N is MDX line `line + N`. */ |
| 32 | line: number; |
| 33 | code: string; |
| 34 | /** False for legacy-SDK fences, which are only syntax-checked. */ |
| 35 | typeCheck: boolean; |
| 36 | }; |
| 37 | |
| 38 | export type PythonSnippetRule = 'python-syntax' | 'python-api' | 'python-directive'; |
| 39 | |
| 40 | export type PythonSnippetViolation = { path: string; line: number; rule: PythonSnippetRule; message: string }; |
| 41 | |
| 42 | |
| 43 | const PYTHON_LANGS: Record<string, true> = { python: true, py: true }; |
| 44 | const LEGACY_RE = /\(previous\)/i; |
| 45 | |
| 46 | /** Every Python fence in `files`, in file and document order. */ |
| 47 | export function collectPythonSnippets(files: CodeExampleFile[]): PythonSnippet[] { |
| 48 | const snippets: PythonSnippet[] = []; |
| 49 | for (const file of files) { |
| 50 | walkCodeExamples(parseCodeExamples(file.source, file.path).units, (unit, ancestors) => { |
| 51 | if (unit.type !== 'fence' || PYTHON_LANGS[unit.lang] !== true) return; |
| 52 | const legacy = |
| 53 | LEGACY_RE.test(unit.info) || |
| 54 | ancestors.some((ancestor) => ancestor.type === 'tab' && LEGACY_RE.test(ancestor.value ?? '')); |
| 55 | snippets.push({ |
| 56 | id: `snippet_${String(snippets.length).padStart(4, '0')}`, |
| 57 | path: file.path, |
| 58 | line: unit.line, |
| 59 | code: unit.code, |
| 60 | typeCheck: !legacy, |
| 61 | }); |
| 62 | }); |
| 63 | } |
| 64 | return snippets; |
| 65 | } |
| 66 | |
| 67 | const Diagnostic = z.object({ id: z.string(), line: z.number(), message: z.string() }); |
| 68 | const HelperResult = z.object({ |
| 69 | syntax: z.array(Diagnostic), |
| 70 | api: z.array(Diagnostic), |
| 71 | /** Diagnostic evidence kept separate from SDK API violations. */ |
| 72 | other: z.array(Diagnostic), |
| 73 | /** Unexplained, code-less, or unused `# type: ignore` comments. */ |
| 74 | directives: z.array(Diagnostic), |
| 75 | mypy: z.array(z.string()), |
| 76 | }); |
| 77 | |
| 78 | export type PythonHelperResult = z.infer<typeof HelperResult>; |
| 79 | |
| 80 | /** Map snippet-relative helper diagnostics to their rendered documentation source. */ |
| 81 | export function pythonSnippetViolations( |
| 82 | snippets: PythonSnippet[], |
| 83 | result: PythonHelperResult, |
| 84 | ): PythonSnippetViolation[] { |
| 85 | const byId = new Map(snippets.map((snippet) => [snippet.id, snippet])); |
| 86 | return [ |
| 87 | ...result.syntax.map((diagnostic) => ({ ...diagnostic, rule: 'python-syntax' as const })), |
| 88 | ...result.api.map((diagnostic) => ({ ...diagnostic, rule: 'python-api' as const })), |
| 89 | ...result.directives.map((diagnostic) => ({ ...diagnostic, rule: 'python-directive' as const })), |
| 90 | ].map(({ id, line, message, rule }) => { |
| 91 | const snippet = byId.get(id); |
| 92 | if (!snippet) throw new Error(`Python helper returned unknown snippet ${id}`); |
| 93 | return { path: snippet.path, line: snippet.line + line, rule, message }; |
| 94 | }); |
| 95 | } |
| 96 | |
| 97 | const DOCS_ROOT = fileURLToPath(new URL('..', import.meta.url)); |
| 98 | const PYTHON_ROOT = join(DOCS_ROOT, '../python'); |
| 99 | // The SDK is a uv workspace member; keep its env in the gitignored python/.venv |
| 100 | // rather than an env at the workspace root. |
| 101 | const SDK_ENV = join(PYTHON_ROOT, '.venv'); |
| 102 | const SDK_PYTHON = join(SDK_ENV, process.platform === 'win32' ? 'Scripts/python.exe' : 'bin/python'); |
| 103 | const HELPER = join(DOCS_ROOT, 'scripts/python-snippets/check_snippets.py'); |
| 104 | |
| 105 | /** Runs the Python helper in the SDK env; exits 2 when `uv` is unavailable or the helper fails. */ |
| 106 | export function runPythonHelper(snippets: PythonSnippet[], syntaxOnly = false): PythonHelperResult { |
| 107 | const workDir = mkdtempSync(join(tmpdir(), 'python-snippets-')); |
| 108 | try { |
| 109 | const requestPath = join(workDir, 'request.json'); |
| 110 | writeFileSync( |
| 111 | requestPath, |
| 112 | JSON.stringify({ |
| 113 | workDir, |
| 114 | sdkPython: SDK_PYTHON, |
| 115 | syntaxOnly, |
| 116 | snippets: snippets.map(({ id, code, typeCheck }) => ({ id, code, typeCheck })), |
| 117 | }), |
| 118 | ); |
| 119 | const result = spawnSync( |
| 120 | 'uv', |
| 121 | [ |
| 122 | 'run', '--quiet', '--frozen', '--project', PYTHON_ROOT, '--python', '3.12', |
| 123 | '--no-default-groups', '--group', 'docs-snippets', 'python', HELPER, requestPath, |
| 124 | ], |
| 125 | { |
| 126 | encoding: 'utf8', |
| 127 | maxBuffer: 256 * 1024 * 1024, |
| 128 | stdio: ['ignore', 'pipe', 'inherit'], |
| 129 | env: { ...process.env, UV_PROJECT_ENVIRONMENT: SDK_ENV }, |
| 130 | }, |
| 131 | ); |
| 132 | if (result.error && 'code' in result.error && result.error.code === 'ENOENT') { |
| 133 | console.error('uv is required to check Python snippets: https://docs.astral.sh/uv/getting-started/installation/'); |
| 134 | process.exit(2); |
| 135 | } |
| 136 | if (result.status !== 0) { |
| 137 | console.error(`Python snippet helper failed (exit ${result.status ?? result.signal}).`); |
| 138 | process.exit(2); |
| 139 | } |
| 140 | return HelperResult.parse(JSON.parse(result.stdout)); |
| 141 | } finally { |
| 142 | rmSync(workDir, { recursive: true, force: true }); |
| 143 | } |
| 144 | } |
| 145 | |
| 146 | function main(): void { |
| 147 | const USAGE = 'Usage: bun scripts/check-python-snippets.ts [--json] [--syntax-only]'; |
| 148 | const args = process.argv.slice(2); |
| 149 | const unknown = args.filter((arg) => arg !== '--json' && arg !== '--syntax-only'); |
| 150 | if (unknown.length) { |
| 151 | console.error(`Unknown argument(s): ${unknown.join(' ')}\n${USAGE}`); |
| 152 | process.exit(2); |
| 153 | } |
| 154 | |
| 155 | const snippets = collectPythonSnippets(listCodeExampleFiles(DOCS_ROOT)); |
| 156 | const helper = runPythonHelper(snippets, args.includes('--syntax-only')); |
| 157 | const violations = pythonSnippetViolations(snippets, helper); |
| 158 | violations.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line); |
| 159 | |
| 160 | const counts: Record<string, number> = {}; |
| 161 | for (const violation of violations) counts[violation.rule] = (counts[violation.rule] ?? 0) + 1; |
| 162 | |
| 163 | if (args.includes('--json')) { |
| 164 | console.log(JSON.stringify({ snippets: snippets.length, violations, counts }, null, 2)); |
| 165 | } else if (violations.length) { |
| 166 | for (const { path, line, rule, message } of violations) console.log(`${path}:${line} ${rule} ${message}`); |
| 167 | const fileCount = new Set(violations.map((violation) => violation.path)).size; |
| 168 | console.log( |
| 169 | `\n${violations.length} Python snippet violation(s) in ${fileCount} file(s), ${snippets.length} snippet(s) checked:`, |
| 170 | ); |
| 171 | for (const rule of Object.keys(counts).sort()) console.log(` ${rule}: ${counts[rule]}`); |
| 172 | } else { |
| 173 | console.log(`No Python snippet violations in ${snippets.length} snippet(s).`); |
| 174 | } |
| 175 | process.exit(violations.length ? 1 : 0); |
| 176 | } |
| 177 | |
| 178 | if (import.meta.main) main(); |