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 157 lines 6.87 KB
Raw
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();