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 | * Type-check authored examples outside the production Twoslash build: canonical |
| 3 | * API overviews, authored reference pages, and plain Markdown FAQ/KB inputs. |
| 4 | * Every diagnostic is retained; snippets are never executed. |
| 5 | */ |
| 6 | import { fileURLToPath } from 'node:url'; |
| 7 | import ts from 'typescript'; |
| 8 | import { resolve } from 'node:path'; |
| 9 | import { createTwoslasher, type TwoslashInstance } from 'twoslash'; |
| 10 | import { listCodeExampleFiles, parseCodeExamples, walkCodeExamples, type CodeExampleFile } from '../lib/code-examples'; |
| 11 | |
| 12 | export type TypeScriptSnippet = { path: string; line: number; code: string; lang: string }; |
| 13 | export type TypeScriptSnippetViolation = { |
| 14 | path: string; |
| 15 | line: number; |
| 16 | rule: 'typescript-api' | 'typescript-directive' | 'typescript-checker'; |
| 17 | message: string; |
| 18 | }; |
| 19 | |
| 20 | const LANGUAGES: Record<string, string> = { |
| 21 | typescript: 'ts', ts: 'ts', tsx: 'tsx', javascript: 'js', js: 'js', jsx: 'jsx', |
| 22 | }; |
| 23 | const DOCS_ROOT = fileURLToPath(new URL('..', import.meta.url)); |
| 24 | |
| 25 | /** Generated API/SDK copies are excluded by the shared canonical inventory. */ |
| 26 | export function isUncoveredTypeScriptSource(path: string): boolean { |
| 27 | return path.startsWith('api-overviews/') || path.startsWith('content/reference/') || path.endsWith('.md'); |
| 28 | } |
| 29 | |
| 30 | export function collectTypeScriptSnippets(files: readonly CodeExampleFile[]): TypeScriptSnippet[] { |
| 31 | const snippets: TypeScriptSnippet[] = []; |
| 32 | for (const file of files) { |
| 33 | if (!isUncoveredTypeScriptSource(file.path)) continue; |
| 34 | walkCodeExamples(parseCodeExamples(file.source, file.path).units, (unit) => { |
| 35 | if (unit.type === 'fence' && LANGUAGES[unit.lang]) { |
| 36 | snippets.push({ path: file.path, line: unit.line, code: unit.code, lang: LANGUAGES[unit.lang] }); |
| 37 | } |
| 38 | }); |
| 39 | } |
| 40 | return snippets; |
| 41 | } |
| 42 | |
| 43 | export function createSnippetTwoslasher(docsRoot = DOCS_ROOT): TwoslashInstance { |
| 44 | return createTwoslasher({ |
| 45 | vfsRoot: resolve(docsRoot), |
| 46 | compilerOptions: { |
| 47 | target: ts.ScriptTarget.ES2022, |
| 48 | module: ts.ModuleKind.ESNext, |
| 49 | moduleResolution: ts.ModuleResolutionKind.Bundler, |
| 50 | moduleDetection: ts.ModuleDetectionKind.Force, |
| 51 | strict: true, |
| 52 | allowJs: true, |
| 53 | checkJs: true, |
| 54 | jsx: ts.JsxEmit.ReactJSX, |
| 55 | jsxImportSource: 'react', |
| 56 | types: ['node'], |
| 57 | ignoreDeprecations: '6.0', |
| 58 | }, |
| 59 | handbookOptions: { |
| 60 | // Return actual compiler errors instead of throwing about @errors labels. |
| 61 | // This does NOT suppress, classify, or remove any compiler diagnostic. |
| 62 | noErrorValidation: true, |
| 63 | noErrors: false, |
| 64 | noErrorsCutted: false, |
| 65 | noStaticSemanticInfo: true, |
| 66 | keepNotations: true, |
| 67 | }, |
| 68 | }); |
| 69 | } |
| 70 | |
| 71 | /** Reject suppression comments without mistaking string literals for directives. */ |
| 72 | function withoutBlanketSuppressions(code: string): { code: string; lines: number[] } { |
| 73 | const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, ts.LanguageVariant.Standard, code); |
| 74 | const changes: { start: number; end: number }[] = []; |
| 75 | const lines: number[] = []; |
| 76 | for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) { |
| 77 | if (token !== ts.SyntaxKind.SingleLineCommentTrivia && token !== ts.SyntaxKind.MultiLineCommentTrivia) continue; |
| 78 | if (!/^[/*\s]*@(?:noErrors(?:Cutted)?|noCheck|ts-nocheck)\b/.test(scanner.getTokenText())) continue; |
| 79 | const start = scanner.getTokenPos(); |
| 80 | changes.push({ start, end: scanner.getTextPos() }); |
| 81 | lines.push(code.slice(0, start).split('\n').length); |
| 82 | } |
| 83 | for (const { start, end } of changes.reverse()) { |
| 84 | code = code.slice(0, start) + code.slice(start, end).replace(/[^\r\n]/g, ' ') + code.slice(end); |
| 85 | } |
| 86 | return { code, lines }; |
| 87 | } |
| 88 | |
| 89 | export function checkTypeScriptSnippets( |
| 90 | snippets: readonly TypeScriptSnippet[], |
| 91 | twoslasher = createSnippetTwoslasher(), |
| 92 | ): TypeScriptSnippetViolation[] { |
| 93 | const violations: TypeScriptSnippetViolation[] = []; |
| 94 | for (const snippet of snippets) { |
| 95 | const cleaned = withoutBlanketSuppressions(snippet.code); |
| 96 | for (const line of cleaned.lines) { |
| 97 | violations.push({ |
| 98 | path: snippet.path, line: snippet.line + line, rule: 'typescript-directive', |
| 99 | message: 'Blanket TypeScript/Twoslash diagnostic suppression is not allowed; correct the example or document a precise typing gap.', |
| 100 | }); |
| 101 | } |
| 102 | try { |
| 103 | let source = cleaned.code; |
| 104 | let result = twoslasher(source, snippet.lang); |
| 105 | let preludeLines = 0; |
| 106 | // Ask the compiler, not a regex or a whole-fence binding scan, whether the |
| 107 | // conventional fragment variable is genuinely unresolved in this scope. |
| 108 | // Local declarations and nested parameters retain their original types. |
| 109 | const needsComposio = result.errors.some((error) => |
| 110 | (error.code === 2304 || error.code === 2552) && source.slice(error.start, error.start + error.length) === 'composio'); |
| 111 | if (needsComposio) { |
| 112 | let binding = '__DocsFragmentComposio'; |
| 113 | while (source.includes(binding)) binding += '_'; |
| 114 | const prelude = snippet.lang === 'js' || snippet.lang === 'jsx' |
| 115 | ? `import { Composio as ${binding} } from "@composio/core";\nconst composio = new ${binding}();\n` |
| 116 | : `import type { Composio as ${binding} } from "@composio/core";\ndeclare const composio: ${binding};\n`; |
| 117 | preludeLines = prelude.split('\n').length - 1; |
| 118 | source = prelude + source; |
| 119 | result = twoslasher(source, snippet.lang); |
| 120 | } |
| 121 | for (const error of result.errors) { |
| 122 | if (error.level && error.level !== 'error') continue; |
| 123 | const line = error.line + 1 - preludeLines; |
| 124 | violations.push({ |
| 125 | path: snippet.path, |
| 126 | line: snippet.line + Math.max(1, line), |
| 127 | rule: line < 1 ? 'typescript-checker' : 'typescript-api', |
| 128 | message: `${error.text} [TS${error.code ?? 'unknown'}]`, |
| 129 | }); |
| 130 | } |
| 131 | } catch (error) { |
| 132 | violations.push({ path: snippet.path, line: snippet.line, rule: 'typescript-checker', message: String(error) }); |
| 133 | } |
| 134 | } |
| 135 | return violations.sort((a, b) => a.path.localeCompare(b.path) || a.line - b.line || a.message.localeCompare(b.message)); |
| 136 | } |
| 137 | |
| 138 | function main(): void { |
| 139 | const args = process.argv.slice(2); |
| 140 | if (args.some((arg) => arg !== '--json')) { |
| 141 | console.error('Usage: bun scripts/check-typescript-snippets.ts [--json]'); |
| 142 | process.exit(2); |
| 143 | } |
| 144 | const snippets = collectTypeScriptSnippets(listCodeExampleFiles(DOCS_ROOT)); |
| 145 | const violations = checkTypeScriptSnippets(snippets); |
| 146 | if (args.includes('--json')) { |
| 147 | console.log(JSON.stringify({ snippets: snippets.length, violations }, null, 2)); |
| 148 | } else if (violations.length) { |
| 149 | for (const violation of violations) console.log(`${violation.path}:${violation.line} ${violation.rule} ${violation.message}`); |
| 150 | console.log(`\n${violations.length} TypeScript violation(s); ${snippets.length} snippet(s) checked.`); |
| 151 | } else { |
| 152 | console.log(`No TypeScript snippet violations in ${snippets.length} snippet(s).`); |
| 153 | } |
| 154 | process.exit(violations.length ? 1 : 0); |
| 155 | } |
| 156 | |
| 157 | if (import.meta.main) main(); |