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 156 lines 5.88 KB
Raw
1 /**
2 * Every `composio …` command a user-facing string names (hints, help examples, error messages,
3 * intros) is a real command registration on the tree it names: `composio dev orgs switch` would
4 * fail, since `orgs` is a root command only.
5 *
6 * Collects the text of every string and template literal under `src/` with the TypeScript
7 * compiler, finds each `composio <words>` in it, and walks the words down the command tree
8 * (`test/__utils__/command-tree.ts`). The walk stops at the first word that is not a subcommand;
9 * the reference is broken when it stopped at a group whose next word looks like a subcommand
10 * name, or before any command at all, unless that text is prose listed in `NOT_COMMANDS`.
11 *
12 * A help page's examples are checked again as the page renders them, since a definition
13 * registered on both trees renders one set of examples on two pages: each example must name a
14 * command on the tree of the page that shows it.
15 */
16 import * as fs from 'node:fs';
17 import * as path from 'node:path';
18 import { describe, expect, it } from '@effect/vitest';
19 import { Effect } from 'effect';
20 import type { Command } from 'effect/cli';
21 import ts from 'typescript';
22 import { cli, MockConsole, TestLive } from 'test/__utils__';
23 import { registrationsOf } from 'test/__utils__/command-tree';
24
25 const srcDir = path.resolve(import.meta.dirname, '../../../src');
26
27 const sourceFiles = fs
28 .readdirSync(srcDir, { recursive: true, encoding: 'utf8' })
29 .filter(file => /\.tsx?$/.test(file) && !file.endsWith('.d.ts'))
30 .map(file => path.join(srcDir, file));
31
32 /** The text of every string literal and template literal piece in `file`. */
33 const literalsOf = (file: string): ReadonlyArray<string> => {
34 const source = ts.createSourceFile(
35 file,
36 fs.readFileSync(file, 'utf8'),
37 ts.ScriptTarget.Latest,
38 true
39 );
40 const texts: string[] = [];
41 const visit = (node: ts.Node) => {
42 if (
43 ts.isStringLiteral(node) ||
44 ts.isNoSubstitutionTemplateLiteral(node) ||
45 ts.isTemplateHead(node) ||
46 ts.isTemplateMiddle(node) ||
47 ts.isTemplateTail(node)
48 ) {
49 texts.push(node.text);
50 }
51 ts.forEachChild(node, visit);
52 };
53 visit(source);
54 return texts;
55 };
56
57 const REFERENCE = /(?<![\w@/.-])composio((?: [a-z][a-z0-9-]*)+)/g;
58
59 const references = sourceFiles.flatMap(file =>
60 literalsOf(file).flatMap(text =>
61 [...text.matchAll(REFERENCE)].map(match => ({
62 file: path.relative(srcDir, file).split(path.sep).join('/'),
63 words: match[1]!.trim().split(' '),
64 }))
65 )
66 );
67
68 const root = registrationsOf()[0]!.command;
69
70 const childNamed = (command: Command.Command.Any, word: string) =>
71 command.subcommands
72 .flatMap(group => group.commands)
73 .find(child => child.name === word || child.alias === word);
74
75 /** The command path `words` resolves to, and the first word past it, if any. */
76 const resolve = (words: ReadonlyArray<string>) => {
77 const walk = (
78 command: Command.Command.Any,
79 names: ReadonlyArray<string>,
80 rest: ReadonlyArray<string>
81 ): {
82 readonly command: Command.Command.Any;
83 readonly names: ReadonlyArray<string>;
84 readonly next: string | undefined;
85 } => {
86 const [word, ...tail] = rest;
87 const child = word === undefined ? undefined : childNamed(command, word);
88 return child === undefined
89 ? { command, names, next: word }
90 : walk(child, [...names, child.name], tail);
91 };
92 return walk(root, [], words);
93 };
94
95 /** Prose that reads like a command reference, as `<file>: composio <words>`. */
96 const NOT_COMMANDS: ReadonlyArray<string> = [
97 // The approval page's title: "The composio cli wants to execute TOOL".
98 'services/tool-permissions.ts: composio cli wants to execute',
99 ];
100
101 const unresolved = references.flatMap(({ file, words }) => {
102 const { command, names, next } = resolve(words);
103 const stoppedInGroup =
104 next !== undefined && (names.length === 0 || command.subcommands.length > 0);
105 return stoppedInGroup ? [`${file}: composio ${words.join(' ')}`] : [];
106 });
107
108 describe('command references in user-facing strings', () => {
109 it('finds the references', () => {
110 expect(references.length).toBeGreaterThan(100);
111 });
112
113 it('name real commands on the tree they name', () => {
114 expect(unresolved.filter(reference => !NOT_COMMANDS.includes(reference))).toEqual([]);
115 });
116
117 it('lists no prose that is gone', () => {
118 expect(NOT_COMMANDS.filter(reference => !unresolved.includes(reference))).toEqual([]);
119 });
120 });
121
122 /** The tree a command path is on: everything under `dev` is the dev tree. */
123 const treeOf = (names: ReadonlyArray<string>) => (names[0] === 'dev' ? 'dev' : 'root');
124
125 /** The `composio …` lines of the EXAMPLES section of a rendered help page. */
126 const examplesOf = (help: string): ReadonlyArray<string> => {
127 const [, section = ''] = help.split(/^EXAMPLES$/m);
128 return section
129 .split('\n')
130 .map(line => line.trim())
131 .filter(line => line.startsWith('composio '));
132 };
133
134 const helpPages = registrationsOf()
135 .filter(({ identity, unlisted }) => identity.path.length > 0 && !unlisted)
136 .filter(({ identity }) => identity.path[0] !== 'help')
137 .map(({ identity }) => ({ path: identity.path, page: identity.path.join(' ') }));
138
139 describe('help examples', () => {
140 // A fresh layer per page, so one page's output is not read as the next one's.
141 it.effect.each(helpPages)('on `composio $page --help` name commands on its tree', ({ path }) =>
142 Effect.gen(function* () {
143 yield* cli([...path, '--help']);
144 const help = (yield* MockConsole.getLines({ stripAnsi: true, stream: 'stdout' })).join('\n');
145 const offTree = examplesOf(help).flatMap(example =>
146 [...example.matchAll(REFERENCE)].flatMap(match => {
147 const { names } = resolve(match[1]!.trim().split(' '));
148 return names.length > 0 && treeOf(names) !== treeOf(path)
149 ? [`${example} (names \`composio ${names.join(' ')}\`)`]
150 : [];
151 })
152 );
153 expect(offTree).toEqual([]);
154 }).pipe(Effect.provide(TestLive()))
155 );
156 });