Skip to content

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(sdk): run typedoc without a shell in generate-docs (SEC-899) (#4416)

Saransh Ranaa69f82d6761f
diff --git a/ts/packages/core/scripts/generate-docs.ts b/ts/packages/core/scripts/generate-docs.ts
index 19a5f183b..3f6297e51 100644
--- a/ts/packages/core/scripts/generate-docs.ts
+++ b/ts/packages/core/scripts/generate-docs.ts
@@ -10,7 +10,7 @@
import { readFileSync } from 'fs';
import { mkdir, writeFile, rm, readdir, readFile } from 'fs/promises';
import { join, dirname, resolve } from 'path';
-import { execSync } from 'child_process';
+import { execFileSync } from 'child_process';
import { fileURLToPath, pathToFileURL } from 'url';
// Paths (relative to ts/packages/core)
@@ -19,6 +19,11 @@ const PACKAGE_DIR = join(SCRIPT_DIR, '..');
const MODELS_DIR = join(PACKAGE_DIR, 'src/models');
const OUTPUT_DIR = join(PACKAGE_DIR, '../../../docs/content/reference/sdk-reference/typescript');
const TEMP_JSON = join(PACKAGE_DIR, '.typedoc-output.json');
+const TYPEDOC_BIN = join(
+ dirname(fileURLToPath(import.meta.resolve('typedoc/package.json'))),
+ 'bin',
+ 'typedoc'
+);
// Internal classes that should NOT be documented (accessed via other APIs)
const INTERNAL_CLASSES = new Set([
@@ -55,14 +60,65 @@ function slugFor(className: string): string {
return SLUG_OVERRIDES[className] ?? toKebabCase(className);
}
+// Model file names become typedoc arguments. They are never interpolated into a
+// shell, but a name outside this charset is still not a model and is skipped
+// rather than passed through.
+const MODEL_FILE_NAME = /^[A-Za-z0-9_.-]+\.ts$/;
+
// Discover model files automatically
-async function discoverModelFiles(): Promise<string[]> {
- const files = await readdir(MODELS_DIR);
+export async function discoverModelFiles(modelsDir: string = MODELS_DIR): Promise<string[]> {
+ const files = await readdir(modelsDir);
return files
.filter(f => f.endsWith('.ts') && !f.includes('.test.') && !f.includes('.spec.'))
+ .filter(f => {
+ if (MODEL_FILE_NAME.test(f)) {
+ return true;
+ }
+ console.warn(` Skipping model file with an unexpected name: ${JSON.stringify(f)}`);
+ return false;
+ })
.map(f => `src/models/${f}`);
}
+// TypeDoc arguments, one array element per argument so the entry points are
+// never joined into a shell command line.
+function buildTypeDocArgs(
+ entryPoints: readonly string[],
+ outputJson: string = TEMP_JSON
+): string[] {
+ return [
+ '--json',
+ outputJson,
+ '--tsconfig',
+ 'tsconfig.json',
+ '--excludePrivate',
+ '--excludeProtected',
+ '--excludeInternal',
+ '--skipErrorChecking', // Skip TS errors, we just want the documentation
+ ...entryPoints,
+ ];
+}
+
+interface TypeDocCommandOptions {
+ outputJson?: string;
+ packageDir?: string;
+ typedocBin?: string;
+}
+
+export function runTypeDocCommand(
+ entryPoints: readonly string[],
+ {
+ outputJson = TEMP_JSON,
+ packageDir = PACKAGE_DIR,
+ typedocBin = TYPEDOC_BIN,
+ }: TypeDocCommandOptions = {}
+): void {
+ execFileSync(process.execPath, [typedocBin, ...buildTypeDocArgs(entryPoints, outputJson)], {
+ stdio: 'pipe',
+ cwd: packageDir,
+ });
+}
+
// Discover classes to document from TypeDoc output
function discoverClassesToDocument(project: TypeDocProject): string[] {
const classes: string[] = [];
@@ -1132,21 +1188,8 @@ async function runTypeDoc(): Promise<TypeDocProject> {
console.log(` Found ${entryPoints.length} entry points`);
- const cmd = [
- 'npx typedoc',
- '--json',
- TEMP_JSON,
- '--tsconfig',
- 'tsconfig.json',
- '--excludePrivate',
- '--excludeProtected',
- '--excludeInternal',
- '--skipErrorChecking', // Skip TS errors, we just want the documentation
- ...entryPoints,
- ].join(' ');
-
try {
- execSync(cmd, { stdio: 'pipe', cwd: PACKAGE_DIR });
+ runTypeDocCommand(entryPoints);
} catch (error) {
console.error('TypeDoc failed:', error);
throw error;
diff --git a/ts/packages/core/test/scripts/generate-docs.test.ts b/ts/packages/core/test/scripts/generate-docs.test.ts
index 1d6d8ef68..dddd0d4b6 100644
--- a/ts/packages/core/test/scripts/generate-docs.test.ts
+++ b/ts/packages/core/test/scripts/generate-docs.test.ts
@@ -1,8 +1,13 @@
-import { describe, expect, it } from 'vitest';
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
import {
+ discoverModelFiles,
escapeTextForMdx,
escapeTypeForMdx,
parseSourceSignatureTypesAtLine,
+ runTypeDocCommand,
simplifyTypeForSignature,
simplifyTypeForTable,
} from '../../scripts/generate-docs';
@@ -119,3 +124,60 @@ class Example {
expect(signature?.returnType).toBe('void');
});
});
+
+describe('generate-docs command construction', () => {
+ let modelsDir: string;
+
+ beforeEach(async () => {
+ modelsDir = await mkdtemp(join(tmpdir(), 'composio-generate-docs-'));
+ });
+
+ afterEach(async () => {
+ await rm(modelsDir, { recursive: true, force: true });
+ vi.restoreAllMocks();
+ });
+
+ it('keeps only plainly named model files and drops shell metacharacter names', async () => {
+ vi.spyOn(console, 'warn').mockImplementation(() => undefined);
+ for (const name of [
+ 'Files.ts',
+ 'tool_router.ts',
+ 'x;touch pwned.ts',
+ '$(id).ts',
+ 'a b.ts',
+ 'Files.test.ts',
+ 'notes.md',
+ ]) {
+ await writeFile(join(modelsDir, name), '');
+ }
+
+ const discovered = await discoverModelFiles(modelsDir);
+
+ expect(discovered.sort()).toEqual(['src/models/Files.ts', 'src/models/tool_router.ts']);
+ });
+
+ it('runs TypeDoc with Node and passes every entry point as its own argument', async () => {
+ const typedocBin = join(modelsDir, 'typedoc');
+ const outputJson = join(modelsDir, 'typedoc-args.txt');
+ await writeFile(
+ typedocBin,
+ `const { writeFileSync } = require('node:fs');
+const args = process.argv.slice(2);
+const outputJson = args[args.indexOf('--json') + 1];
+writeFileSync(outputJson, args.join('\\n'));
+`
+ );
+
+ runTypeDocCommand(['src/composio.ts', 'src/models/a b.ts'], {
+ outputJson,
+ packageDir: modelsDir,
+ typedocBin,
+ });
+
+ const args = (await readFile(outputJson, 'utf8')).split('\n');
+ expect(args[0]).toBe('--json');
+ expect(args).toContain('src/models/a b.ts');
+ expect(args.some(arg => arg.includes('npx'))).toBe(false);
+ expect(args.slice(-2)).toEqual(['src/composio.ts', 'src/models/a b.ts']);
+ });
+});