@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 178 lines 7.17 KB
Raw
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();