@devries-cameron20 / composio Mirror · read-only
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 03:37 UTC

next
ts 441 lines 13.2 KB
Raw
1 #!/usr/bin/env bun
2
3 import fs from 'node:fs';
4 import path from 'node:path';
5 import process from 'node:process';
6 import { z } from 'zod';
7
8 const repoRoot = process.cwd();
9
10 // Canonical taxonomy gate. Keep in sync with the skill-routing list in `AGENTS.md`
11 // and the taxonomy in `GOAL.md`; adding/removing a skill means editing all three.
12 // This list is used ONLY to assert the on-disk taxonomy — the command scan below
13 // derives its file set from disk so it cannot drift from this literal.
14 const expectedSkills = [
15 'bug-fixing',
16 'cli-command',
17 'cli-e2e',
18 'cli-release',
19 'cross-sdk-parity',
20 'docs-decisions',
21 'effect-v4',
22 'eve',
23 'good-docs-audit',
24 'good-docs-writing',
25 'python-providers',
26 'python-release',
27 'python-sdk',
28 'python-testing',
29 'repo-guidance',
30 'skill-maintenance',
31 'typescript-providers',
32 'typescript-sdk',
33 'typescript-testing',
34 'verify-change',
35 ];
36
37 const requiredAgentFiles = [
38 'AGENTS.md',
39 'docs/AGENTS.md',
40 'ts/AGENTS.md',
41 'ts/packages/core/AGENTS.md',
42 'ts/packages/providers/AGENTS.md',
43 'ts/packages/cli/AGENTS.md',
44 'ts/e2e-tests/AGENTS.md',
45 'python/AGENTS.md',
46 'python/providers/AGENTS.md',
47 ];
48
49 const errors: string[] = [];
50
51 const fail = (message: string) => errors.push(message);
52 const manifestSchema = z.object({ scripts: z.record(z.string(), z.string()).optional() });
53 const readJson = (relativePath: string) =>
54 manifestSchema.parse(JSON.parse(fs.readFileSync(path.join(repoRoot, relativePath), 'utf8')));
55
56 const rootScripts = new Set(Object.keys(readJson('package.json').scripts ?? {}));
57 const docsScripts = new Set(Object.keys(readJson('docs/package.json').scripts ?? {}));
58
59 const makefile = fs.readFileSync(path.join(repoRoot, 'python/Makefile'), 'utf8');
60 const makeTargets = new Set([...makefile.matchAll(/^([A-Za-z0-9_-]+):/gm)].map(match => match[1]));
61
62 const noxfile = fs.readFileSync(path.join(repoRoot, 'python/noxfile.py'), 'utf8');
63 const noxSessions = new Set(
64 [...noxfile.matchAll(/^def ([A-Za-z0-9_]+)\(/gm)].map(match => match[1])
65 );
66
67 for (const match of makefile.matchAll(/\bnox\s+-s\s+([A-Za-z0-9_]+)/g)) {
68 const session = match[1];
69 if (!noxSessions.has(session)) {
70 fail(`python/Makefile calls missing nox session "${session}"`);
71 }
72 }
73
74 const frontmatterSchema = z.object({ name: z.string(), description: z.string() });
75 const parseFrontmatter = (content: string, relativePath: string) => {
76 const match = content.match(/^---\n([\s\S]*?)\n---\n?/);
77 if (!match) {
78 fail(`${relativePath}: missing YAML frontmatter`);
79 return null;
80 }
81
82 const data: Record<string, string> = {};
83 for (const line of match[1].split('\n')) {
84 const keyMatch = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
85 if (!keyMatch) {
86 fail(`${relativePath}: unsupported frontmatter line "${line}"`);
87 continue;
88 }
89 data[keyMatch[1]] = keyMatch[2].replace(/^"(.*)"$/, '$1').trim();
90 }
91
92 const keys = Object.keys(data).sort();
93 const allowed = ['description', 'name'];
94 const extra = keys.filter(key => !allowed.includes(key));
95 if (extra.length > 0) {
96 fail(`${relativePath}: frontmatter has unsupported keys ${extra.join(', ')}`);
97 }
98
99 for (const key of allowed) {
100 if (!data[key]) {
101 fail(`${relativePath}: missing frontmatter key ${key}`);
102 }
103 }
104
105 const parsed = frontmatterSchema.safeParse(data);
106 return parsed.success ? { data: parsed.data } : null;
107 };
108
109 const skillsRoot = path.join(repoRoot, '.agents/skills');
110 const skillDirNames = fs.existsSync(skillsRoot)
111 ? fs
112 .readdirSync(skillsRoot, { withFileTypes: true })
113 .filter(entry => entry.isDirectory())
114 .map(entry => entry.name)
115 : [];
116
117 if (!fs.existsSync(skillsRoot)) {
118 fail('.agents/skills does not exist');
119 } else {
120 const actualSkills = [...skillDirNames].sort();
121
122 const expected = [...expectedSkills].sort();
123 if (actualSkills.join('\n') !== expected.join('\n')) {
124 fail(
125 `.agents/skills taxonomy mismatch.\nExpected:\n${expected.join('\n')}\nActual:\n${actualSkills.join('\n')}`
126 );
127 }
128
129 for (const skillName of actualSkills) {
130 const skillDir = path.join(skillsRoot, skillName);
131 const skillMd = path.join(skillDir, 'SKILL.md');
132 const relativeSkillMd = path.relative(repoRoot, skillMd);
133
134 if (!fs.existsSync(skillMd)) {
135 fail(`${skillName}: missing SKILL.md`);
136 continue;
137 }
138
139 const content = fs.readFileSync(skillMd, 'utf8');
140 const parsed = parseFrontmatter(content, relativeSkillMd);
141 if (!parsed) {
142 continue;
143 }
144
145 if (parsed.data.name !== skillName) {
146 fail(`${relativeSkillMd}: name "${parsed.data.name}" must match directory "${skillName}"`);
147 }
148
149 if (!/^[a-z0-9-]+$/.test(parsed.data.name)) {
150 fail(`${relativeSkillMd}: name must use lowercase letters, digits, and hyphens`);
151 }
152
153 if (parsed.data.description.length > 1024) {
154 fail(`${relativeSkillMd}: description exceeds 1024 characters`);
155 }
156
157 if (!/\bUse\b/.test(parsed.data.description)) {
158 fail(`${relativeSkillMd}: description must include trigger boundaries with "Use"`);
159 }
160
161 const lineCount = content.split('\n').length;
162 if (lineCount > 80) {
163 fail(`${relativeSkillMd}: SKILL.md should stay short; found ${lineCount} lines`);
164 }
165
166 const referencesDir = path.join(skillDir, 'references');
167 if (!fs.existsSync(referencesDir)) {
168 fail(`${skillName}: missing references directory`);
169 continue;
170 }
171
172 const referenceEntries = fs.readdirSync(referencesDir, { withFileTypes: true });
173 const referenceFiles = referenceEntries.filter(
174 entry => entry.isFile() && entry.name.endsWith('.md')
175 );
176 if (referenceFiles.length === 0) {
177 fail(`${skillName}: references directory must contain markdown files`);
178 }
179
180 for (const entry of referenceEntries) {
181 if (entry.isDirectory()) {
182 fail(`${skillName}: references must be first-level files, found directory ${entry.name}`);
183 }
184 if (entry.isFile() && !entry.name.endsWith('.md')) {
185 fail(`${skillName}: reference ${entry.name} must be markdown`);
186 }
187 }
188
189 for (const reference of referenceFiles) {
190 const marker = `references/${reference.name}`;
191 if (!content.includes(marker)) {
192 fail(`${relativeSkillMd}: does not link ${marker}`);
193 }
194 }
195 }
196 }
197
198 const claudeSkills = path.join(repoRoot, '.claude/skills');
199 if (!fs.existsSync(claudeSkills)) {
200 fail('.claude/skills is missing');
201 } else {
202 const stat = fs.lstatSync(claudeSkills);
203 if (!stat.isSymbolicLink()) {
204 fail('.claude/skills must be a symlink to .agents/skills');
205 } else {
206 const linkTarget = fs.readlinkSync(claudeSkills);
207 if (linkTarget !== '../.agents/skills') {
208 fail(`.claude/skills points to ${linkTarget}, expected ../.agents/skills`);
209 }
210 }
211 }
212
213 for (const relativePath of requiredAgentFiles) {
214 if (!fs.existsSync(path.join(repoRoot, relativePath))) {
215 fail(`missing required nested guidance file ${relativePath}`);
216 }
217 }
218
219 if (fs.existsSync(path.join(repoRoot, 'docs', '.claude'))) {
220 fail('docs-specific guidance must live under docs/agent-guidance and docs/decisions');
221 }
222
223 if (fs.existsSync(path.join(repoRoot, 'ts/packages/cli', '.cursor'))) {
224 fail('CLI Cursor-specific metadata should be retired after migration');
225 }
226
227 if (fs.existsSync(path.join(repoRoot, '.claude', 'rules'))) {
228 fail('Claude-only rule files should be migrated into neutral guidance');
229 }
230
231 for (const relativePath of ['docs/decisions/README.md', 'docs/agent-guidance/README.md']) {
232 if (!fs.existsSync(path.join(repoRoot, relativePath))) {
233 fail(`missing ${relativePath}`);
234 }
235 }
236
237 const ignoredDirs = new Set([
238 '.git',
239 '.artifacts',
240 '.generated',
241 'node_modules',
242 '.turbo',
243 '.ruff_cache',
244 '.venv',
245 'dist',
246 'build',
247 // Vendored trees (see AGENTS.md "Generated And Vendored Paths") are read-only
248 // third-party snapshots. Their docs legitimately mention other tools'
249 // rule-file conventions, so the stale-guidance walk must not police them —
250 // only first-party guidance files are in scope. Invariant: every `vendor`
251 // directory in this repo is third-party; revisit this skip if a first-party
252 // one ever appears.
253 // (Keep this comment free of the stalePatterns literals: this file is
254 // itself scanned by the walk below.)
255 'vendor',
256 ]);
257
258 const ignoredFiles = new Set(['GOAL.md', 'PLAN.md', 'HANDOFF.md', 'RELEASE_NOTES.md']);
259 const textExtensions = new Set([
260 '.md',
261 '.mdx',
262 '.ts',
263 '.tsx',
264 '.js',
265 '.mjs',
266 '.cjs',
267 '.json',
268 '.yml',
269 '.yaml',
270 '.toml',
271 ]);
272
273 const stalePatterns = [
274 ['docs', '.claude'].join('/'),
275 ['.claude', 'context'].join('/'),
276 ['.claude', 'decisions'].join('/'),
277 ['.claude', 'guides'].join('/'),
278 ['.claude', 'rules'].join('/'),
279 ['.Codex', 'rules'].join('/'),
280 ['.cursor', 'rules'].join('/'),
281 ['', 'workspace', 'zen'].join('/'),
282 'CLI' + '.md',
283 ];
284
285 const walk = (dir: string): void => {
286 const entries = fs.readdirSync(dir, { withFileTypes: true });
287 for (const entry of entries) {
288 const absolutePath = path.join(dir, entry.name);
289 const relativePath = path.relative(repoRoot, absolutePath);
290
291 if (entry.isDirectory()) {
292 if (ignoredDirs.has(entry.name)) {
293 continue;
294 }
295 walk(absolutePath);
296 continue;
297 }
298
299 if (!entry.isFile() || ignoredFiles.has(relativePath)) {
300 continue;
301 }
302
303 if (!textExtensions.has(path.extname(entry.name))) {
304 continue;
305 }
306
307 const text = fs.readFileSync(absolutePath, 'utf8');
308 for (const pattern of stalePatterns) {
309 if (text.includes(pattern)) {
310 fail(`${relativePath}: stale guidance reference "${pattern}"`);
311 }
312 }
313 }
314 };
315
316 walk(repoRoot);
317
318 const validatePnpmCommands = (relativePath: string, text: string) => {
319 const commandLines = text
320 .split('\n')
321 .map(line => line.trim().replace(/^\$\s+/, ''))
322 .filter(line => line.startsWith('pnpm ') || line.startsWith('pnpm run '));
323
324 for (const line of commandLines) {
325 const match = line.match(/^pnpm(?:\s+run)?\s+([^\s`]+)/);
326 if (!match) {
327 continue;
328 }
329 const command = match[1];
330 if (
331 command.startsWith('-') ||
332 command === 'install' ||
333 command === 'exec' ||
334 command === 'turbo' ||
335 command === 'dlx'
336 ) {
337 continue;
338 }
339 if (!rootScripts.has(command)) {
340 fail(`${relativePath}: pnpm command "${command}" is not a root package.json script`);
341 }
342 }
343 };
344
345 const validateBunRunCommands = (relativePath: string, text: string) => {
346 const commandLines = text
347 .split('\n')
348 .map(line => line.trim().replace(/^\$\s+/, ''))
349 .filter(line => line.startsWith('bun run '));
350
351 for (const line of commandLines) {
352 const match = line.match(/^bun\s+run\s+([^\s`]+)/);
353 if (!match) {
354 continue;
355 }
356 const command = match[1];
357 if (!docsScripts.has(command) && !rootScripts.has(command)) {
358 fail(
359 `${relativePath}: bun run command "${command}" is not a root or docs package.json script`
360 );
361 }
362 }
363 };
364
365 const validateMakeCommands = (relativePath: string, text: string) => {
366 const commandLines = text
367 .split('\n')
368 .map(line => line.trim().replace(/^\$\s+/, ''))
369 .filter(line => line.startsWith('make '));
370
371 for (const line of commandLines) {
372 const match = line.match(/^make\s+([A-Za-z0-9_-]+)/);
373 if (!match) {
374 continue;
375 }
376 const command = match[1];
377 if (!makeTargets.has(command)) {
378 fail(`${relativePath}: make target "${command}" is not in python/Makefile`);
379 }
380 }
381 };
382
383 const validateNoxCommands = (relativePath: string, text: string) => {
384 const commandLines = text
385 .split('\n')
386 .map(line => line.trim().replace(/^\$\s+/, ''))
387 .filter(line => line.startsWith('nox -s '));
388
389 for (const line of commandLines) {
390 const match = line.match(/^nox\s+-s\s+([A-Za-z0-9_]+)/);
391 if (!match) {
392 continue;
393 }
394 const command = match[1];
395 if (!noxSessions.has(command)) {
396 fail(`${relativePath}: nox session "${command}" is not in python/noxfile.py`);
397 }
398 }
399 };
400
401 // Derive the command-scan file set from the skills actually on disk so it can never
402 // drift from `expectedSkills` (which serves only as the taxonomy gate above).
403 const commandFiles = [
404 ...skillDirNames.flatMap(skillName => {
405 const skillDir = path.join(skillsRoot, skillName);
406 const files: string[] = [];
407 const collect = (dir: string): void => {
408 for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
409 const absolutePath = path.join(dir, entry.name);
410 if (entry.isDirectory()) {
411 collect(absolutePath);
412 } else if (entry.isFile() && entry.name.endsWith('.md')) {
413 files.push(absolutePath);
414 }
415 }
416 };
417 collect(skillDir);
418 return files;
419 }),
420 ...requiredAgentFiles.map(relativePath => path.join(repoRoot, relativePath)),
421 path.join(repoRoot, 'CONTRIBUTING.md'),
422 ];
423
424 for (const absolutePath of commandFiles) {
425 if (!fs.existsSync(absolutePath)) {
426 continue;
427 }
428 const relativePath = path.relative(repoRoot, absolutePath);
429 const text = fs.readFileSync(absolutePath, 'utf8');
430 validatePnpmCommands(relativePath, text);
431 validateBunRunCommands(relativePath, text);
432 validateMakeCommands(relativePath, text);
433 validateNoxCommands(relativePath, text);
434 }
435
436 if (errors.length > 0) {
437 console.error(errors.map(error => `- ${error}`).join('\n'));
438 process.exit(1);
439 }
440
441 console.log(`Validated ${expectedSkills.length} canonical agent skills and guidance invariants.`);