@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
md 77 lines 4.6 KB
Rendered Raw
1 # TypeScript snippet checking
2
3 Production Twoslash validates TypeScript fences in build-covered MDX collections. `check:typescript-snippets` covers maintained API overviews, authored reference pages, and plain-Markdown FAQ/KB inputs that the build does not type-check. These are complementary checks, not a claim that every rendered code block is compiled.
4
5 Python has a separate syntax/mypy gate; see `code-examples.md`.
6
7 ## Commands and coverage
8
9 Run from `docs/`:
10
11 ```bash
12 bun run check:typescript-snippets
13 GITHUB_ACTIONS=true bun run build
14 ```
15
16 - Build-time Twoslash is disabled during `bun dev` to avoid its development memory cost.
17 - `source.config.ts` configures collection-level MDX behavior. The reference and historical changelog collections have no Twoslash transformer. Maintained reference examples are checked by the standalone command; historical release examples remain inventory-only.
18 - Plain-Markdown FAQs and canonical/curated KB inputs are checked before their presentation conversion. Generated KB TypeScript stays TypeScript and is also checked when built.
19 - Generated SDK symbol-reference signatures/partial fragments and historical changelogs are inventory-only, not certified by the maintained-example gates.
20 - `.github/workflows/docs-typescript-check.yml` runs standalone regressions, the standalone gate, lint, type checking, and the production build.
21 - Imports resolve to the versions installed from `docs/package.json` and `docs/bun.lock`. This does not type-check against the local TypeScript SDK workspace.
22 - Release notes can describe an API newer than the installed docs SDK. Keep their ordinary Markdown, Mermaid, and code themes; do not copy their checking exemption into maintained guides or examples. Merge maintained new-API examples after compatible packages are published and their normal checks pass.
23
24 ## Complete examples and hidden setup
25
26 Prefer explicit imports and initialization. Use `// ---cut---` when setup is necessary but should not be displayed; hidden code is still checked.
27
28 ````md
29 ```typescript
30 import { Composio } from '@composio/core';
31 const composio = new Composio({ apiKey: 'key' });
32 const userId = 'user_123';
33 // ---cut---
34 const tools = await composio.tools.get(userId, { toolkits: ['GITHUB'] });
35 ```
36 ````
37
38 The standalone checker can supply the conventional `composio` fragment binding only when the compiler reports that name unresolved. It does not replace a local declaration, imported alias, or nested parameter. New complete examples should not depend on that compatibility prelude.
39
40 ## Callback types
41
42 Use SDK-exported types instead of recreating callback interfaces:
43
44 ````md
45 ```typescript
46 import type { TransformToolSchemaModifier } from '@composio/core';
47
48 const modifySchema: TransformToolSchemaModifier = ({ schema }) => schema;
49 ```
50 ````
51
52 Other exported modifier types include `beforeExecuteModifier` and `afterExecuteModifier`.
53
54 ## Diagnostics and annotations
55
56 | Annotation | Effect |
57 |---|---|
58 | `// ---cut---` | Hide setup from readers, not the compiler |
59 | `// ^?` | Show the inferred type |
60 | `// @errors: 2322` | Twoslash presentation metadata; the standalone gate still reports actual errors |
61 | `// @ts-expect-error` | Suppress one documented typing mismatch; must explain the verified SDK/type gap |
62
63 Do not add blanket `@noErrors`, `@noErrorsCutted`, `@noCheck`, or `@ts-nocheck` to make a current example pass. The standalone checker rejects these directives and reports the underlying diagnostics. Some older build-only examples retain Twoslash suppression; their presence is a validation limit, not evidence that the code compiles.
64
65 For an unavailable dependency, add the dependency through the package manager when it belongs in the supported docs toolchain. For a genuine missing SDK operation, keep the language option and explain the gap in a Callout. Do not invent types or broadly suppress errors to make the tabs appear equivalent.
66
67 ## Troubleshooting
68
69 | Failure | Action |
70 |---|---|
71 | Import cannot resolve | Check the installed docs dependencies and lockfile |
72 | Name cannot resolve | Add explicit initialization or a narrowly scoped hidden declaration |
73 | Argument or callback mismatch | Compare with the installed SDK signature; use exported types |
74 | Generated KB error | Edit its `kb/articles` source and corresponding canonical `kb/source` article, then regenerate |
75 | Reference example error | Edit `api-overviews` for generated overviews, or the authored reference source |
76
77 Static type checking does not establish that requests have equivalent defaults, filters, identities, permissions, or output. Review those against SDK behavior and the OpenAPI contract, then inspect the built tabs and agent Markdown.