@devries-cameron20 / composio-1 / commits / 33fe3ba35
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.

fix(core): restore source type names in the TS SDK reference (#4848)

This PR: - fixes the cut-off `executeMeta()` signature flagged in https://github.com/ComposioHQ/composio/pull/4844#discussion_r4259885596 - pins TypeDoc's `--displayBasePath` to the package directory, so `sources[].fileName` no longer depends on which files TypeDoc happens to visit - resolves source paths against that directory in `getSourceFileText()` and lets a failed read throw instead of returning `undefined` - cuts over-long unions between members in `simplifyTypeForSignature()` and `simplifyTypeForTable()`, so a truncated type never ends inside a string literal - adds regression tests for the TypeDoc argument, the source lookup, and union truncation ## Context The generator has preferred the type names written in source since f6b550573. TypeDoc reports source paths relative to the common directory of every file it visited; once that moved from `src/` to the repo root, the lookup read `src/ts/packages/core/src/...`, the `catch` hid the error, and every signature fell back to TypeDoc's expanded types. The reference silently flipped in #4575 (`mcpConfig: MCPConfigCreationParams` became an inline object shape), and long unions such as `ToolRouterSessionMetaToolSlug` were then cut at 97 characters. The regenerated pages are not included here. Merging this triggers `generate-sdk-docs.yml`, which updates #4844. Expect that diff to touch 20 files: signatures go back to named types such as `Promise<MCPItem>` and `Promise<ToolRouterSessionExecuteResponse>`. ## Checks - `pnpm exec vitest run test/scripts/generate-docs.test.ts` in `ts/packages/core`: 20 passed - `pnpm run generate:docs` locally: `executeMeta()` renders `slug: ToolRouterSessionMetaToolSlug` and `Promise<ToolRouterSessionExecuteResponse>`

Alberto Schiabel committed Oct 13, 2026 at 19:34 UTC 33fe3ba35d44a4a563534cbd2ab1cd16d29f8c8f
2 files changed +113 -19
ts/packages/core/scripts/generate-docs.ts
+44 -18
@@ -84,13 +84,19 @@ export async function discoverModelFiles(modelsDir: string = MODELS_DIR): Promis
84 // never joined into a shell command line.
85 function buildTypeDocArgs(
86 entryPoints: readonly string[],
87 - outputJson: string = TEMP_JSON
87 + outputJson: string = TEMP_JSON,
88 + packageDir: string = PACKAGE_DIR
89 ): string[] {
90 return [
91 '--json',
92 outputJson,
93 '--tsconfig',
94 'tsconfig.json',
95 + // Without this, TypeDoc reports source paths relative to the common
96 + // directory of every file it visited, which moves whenever a model pulls in
97 + // a file outside `src/`. Pinning it keeps `sources[].fileName` resolvable.
98 + '--displayBasePath',
99 + packageDir,
100 '--excludePrivate',
101 '--excludeProtected',
102 '--excludeInternal',
@@ -113,10 +119,14 @@ export function runTypeDocCommand(
119 typedocBin = TYPEDOC_BIN,
120 }: TypeDocCommandOptions = {}
121 ): void {
116 - execFileSync(process.execPath, [typedocBin, ...buildTypeDocArgs(entryPoints, outputJson)], {
117 - stdio: 'pipe',
118 - cwd: packageDir,
119 - });
122 + execFileSync(
123 + process.execPath,
124 + [typedocBin, ...buildTypeDocArgs(entryPoints, outputJson, packageDir)],
125 + {
126 + stdio: 'pipe',
127 + cwd: packageDir,
128 + }
129 + );
130 }
131
132 // Discover classes to document from TypeDoc output
@@ -350,18 +360,18 @@ function extractTag(comment: TypeDocReflection['comment'] | undefined, tagName:
360 return comment.blockTags.filter(t => t.tag === tagName).map(t => extractText(t.content));
361 }
362
353 -function getSourceFileText(fileName: string): string | undefined {
354 - const filePath = join(PACKAGE_DIR, 'src', fileName);
363 +// TypeDoc source paths are relative to `--displayBasePath`, which is the package
364 +// directory. A path that does not resolve means the two have drifted apart, and
365 +// every signature would silently fall back to TypeDoc's expanded types, so the
366 +// read is left to throw.
367 +export function getSourceFileText(fileName: string, packageDir: string = PACKAGE_DIR): string {
368 + const filePath = resolve(packageDir, fileName);
369 const cached = sourceFileCache.get(filePath);
370 if (cached !== undefined) return cached;
371
358 - try {
359 - const text = readFileSync(filePath, 'utf-8');
360 - sourceFileCache.set(filePath, text);
361 - return text;
362 - } catch {
363 - return undefined;
364 - }
372 + const text = readFileSync(filePath, 'utf-8');
373 + sourceFileCache.set(filePath, text);
374 + return text;
375 }
376
377 function getLineOffset(text: string, line: number): number {
@@ -665,8 +675,6 @@ function getSourceSignatureTypes(signature: TypeDocSignature): SourceSignatureTy
675 if (!source) return undefined;
676
677 const text = getSourceFileText(source.fileName);
668 - if (!text) return undefined;
669 -
678 return parseSourceSignatureTypesAtLine(text, source.line);
679 }
680
@@ -1118,6 +1126,24 @@ function isInlineObjectType(type: string): boolean {
1126 return type.startsWith('{') || type.includes(': {');
1127 }
1128
1129 +// Shorten a type to at most `maxLength` characters. A union is cut between
1130 +// members, or elided entirely when not even its first member fits, so it never
1131 +// ends inside a string literal.
1132 +function truncateType(type: string, maxLength: number): string {
1133 + const members = splitTopLevel(type, '|');
1134 + if (members.length > 1) {
1135 + const suffix = ' | ...';
1136 + let kept = members[0];
1137 + for (const member of members.slice(1)) {
1138 + const next = `${kept} | ${member}`;
1139 + if (next.length + suffix.length > maxLength) break;
1140 + kept = next;
1141 + }
1142 + return kept.length + suffix.length <= maxLength ? kept + suffix : '...';
1143 + }
1144 + return type.substring(0, maxLength - 3) + '...';
1145 +}
1146 +
1147 // Simplify complex types for table display while preserving public object shapes.
1148 export function simplifyTypeForTable(type: string): string {
1149 // First clean up internal generics
@@ -1144,7 +1170,7 @@ export function simplifyTypeForTable(type: string): string {
1170
1171 // Truncate very long types
1172 if (cleaned.length > 80) {
1147 - return cleaned.substring(0, 77) + '...';
1173 + return truncateType(cleaned, 80);
1174 }
1175 }
1176 return cleaned;
@@ -1184,7 +1210,7 @@ export function simplifyTypeForSignature(type: string): string {
1210
1211 // Truncate very long types
1212 if (cleaned.length > 100) {
1187 - return cleaned.substring(0, 97) + '...';
1213 + return truncateType(cleaned, 100);
1214 }
1215
1216 return cleaned;
ts/packages/core/test/scripts/generate-docs.test.ts
+69 -1
@@ -1,4 +1,4 @@
1 -import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
1 +import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
2 import { tmpdir } from 'node:os';
3 import { join } from 'node:path';
4 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -8,6 +8,7 @@ import {
8 escapeTextForMdx,
9 escapeTypeForMdx,
10 generateClassMdx,
11 + getSourceFileText,
12 isParameterRequired,
13 parseSourceSignatureTypesAtLine,
14 runTypeDocCommand,
@@ -158,6 +159,72 @@ class Example {
159 });
160 });
161
162 +describe('generate-docs type truncation', () => {
163 + const slugUnion = [
164 + 'COMPOSIO_GET_TOOL_SCHEMAS',
165 + 'COMPOSIO_SEARCH_TOOLS',
166 + 'COMPOSIO_MULTI_EXECUTE_TOOL',
167 + 'COMPOSIO_MANAGE_CONNECTIONS',
168 + 'COMPOSIO_WAIT_FOR_CONNECTIONS',
169 + ]
170 + .map(slug => `'${slug}'`)
171 + .join(' | ');
172 +
173 + it('cuts a long union between members in signatures', () => {
174 + expect(simplifyTypeForSignature(slugUnion)).toBe(
175 + "'COMPOSIO_GET_TOOL_SCHEMAS' | 'COMPOSIO_SEARCH_TOOLS' | 'COMPOSIO_MULTI_EXECUTE_TOOL' | ..."
176 + );
177 + });
178 +
179 + it('cuts a long union between members in parameter tables', () => {
180 + expect(simplifyTypeForTable(slugUnion)).toBe(
181 + "'COMPOSIO_GET_TOOL_SCHEMAS' | 'COMPOSIO_SEARCH_TOOLS' | ..."
182 + );
183 + });
184 +
185 + it('does not split a union member that contains a pipe', () => {
186 + const type = `'${'a|'.repeat(30)}' | 'COMPOSIO_SEARCH_TOOLS' | ${slugUnion}`;
187 +
188 + expect(simplifyTypeForSignature(type)).toBe(
189 + `'${'a|'.repeat(30)}' | 'COMPOSIO_SEARCH_TOOLS' | ...`
190 + );
191 + });
192 +
193 + it('elides a union whose first member does not fit', () => {
194 + const type = `'${'a'.repeat(110)}' | 'COMPOSIO_SEARCH_TOOLS'`;
195 +
196 + expect(simplifyTypeForSignature(type)).toBe('...');
197 + expect(simplifyTypeForTable(type)).toBe('...');
198 + });
199 +});
200 +
201 +describe('generate-docs source lookup', () => {
202 + let packageDir: string;
203 +
204 + beforeEach(async () => {
205 + packageDir = await mkdtemp(join(tmpdir(), 'composio-generate-docs-'));
206 + });
207 +
208 + afterEach(async () => {
209 + await rm(packageDir, { recursive: true, force: true });
210 + });
211 +
212 + it('resolves TypeDoc source paths against the package directory', async () => {
213 + await mkdir(join(packageDir, 'src/models'), { recursive: true });
214 + await writeFile(join(packageDir, 'src/models/Example.ts'), 'export class Example {}\n');
215 +
216 + expect(getSourceFileText('src/models/Example.ts', packageDir)).toBe(
217 + 'export class Example {}\n'
218 + );
219 + });
220 +
221 + it('throws when a TypeDoc source path does not resolve', () => {
222 + expect(() => getSourceFileText('ts/packages/core/src/models/Example.ts', packageDir)).toThrow(
223 + /ENOENT/
224 + );
225 + });
226 +});
227 +
228 describe('generate-docs command construction', () => {
229 let modelsDir: string;
230
@@ -210,6 +277,7 @@ writeFileSync(outputJson, args.join('\\n'));
277 const args = (await readFile(outputJson, 'utf8')).split('\n');
278 expect(args[0]).toBe('--json');
279 expect(args).toContain('src/models/a b.ts');
280 + expect(args[args.indexOf('--displayBasePath') + 1]).toBe(modelsDir);
281 expect(args.some(arg => arg.includes('npx'))).toBe(false);
282 expect(args.slice(-2)).toEqual(['src/composio.ts', 'src/models/a b.ts']);
283 });