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.

docs(core): trim verbose JSDoc and consolidate mastra-ref test setup

jkomyno90680d796586
diff --git a/ts/packages/core/src/utils/jsonSchema.ts b/ts/packages/core/src/utils/jsonSchema.ts
index 153e755d1..046cd4077 100644
--- a/ts/packages/core/src/utils/jsonSchema.ts
+++ b/ts/packages/core/src/utils/jsonSchema.ts
@@ -51,49 +51,15 @@ const resolvePointer = (root: Record<string, unknown>, pointer: string): unknown
};
/**
- * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and the
- * legacy `#/definitions/...`) so the returned schema can be safely handed
- * to consumers — like AJV in `@mastra/schema-compat` — that don't tolerate
- * unresolved references.
+ * Inlines internal JSON Schema `$ref` pointers (`#/$defs/...` and legacy
+ * `#/definitions/...`) so the returned schema can be safely handed to
+ * consumers that don't tolerate unresolved references (e.g. AJV in
+ * `@mastra/schema-compat`). External (`http://`, `https://`, …) refs are
+ * left untouched. Cycles are broken with `{ type: 'object',
+ * additionalProperties: true }`. The input is never mutated.
*
- * The traversal is reflective (no allow-list of JSON Schema keywords), so
- * future applicators (`unevaluatedProperties`, `dependentSchemas`, …) are
- * covered automatically. Sibling keywords next to `$ref` are shallow-merged
- * per Draft 2020-12 semantics — the sibling wins on collision so a caller's
- * `description` or `default` overrides the target's. Recursive `$ref`
- * chains are broken with `{ type: 'object', additionalProperties: true }`,
- * matching the upstream Mastra recommendation in
- * {@link https://github.com/mastra-ai/mastra/issues/15341 mastra-ai/mastra#15341}.
- *
- * The input schema is not mutated: every node is deep-cloned. `$defs` and
- * `definitions` are stripped from the returned root once everything
- * reachable is inlined — AJV strict-mode otherwise complains about unused
- * definitions.
- *
- * External `$ref` pointers (`http://`, `https://`, `file://`, …) are left
- * untouched: the caller may forward them to a consumer that resolves them
- * natively.
- *
- * @param schema - The JSON Schema to dereference. May be any plain object.
- * @returns A new schema with internal `$ref` pointers inlined.
- *
- * @throws {JsonSchemaRefResolutionError} When an internal pointer is
- * malformed, points at a missing target, or chains past the depth cap.
- *
- * @example
- * ```ts
- * dereferenceJsonSchema({
- * type: 'object',
- * properties: { user: { $ref: '#/$defs/User' } },
- * $defs: { User: { type: 'object', properties: { id: { type: 'string' } } } },
- * });
- * // {
- * // type: 'object',
- * // properties: {
- * // user: { type: 'object', properties: { id: { type: 'string' } } },
- * // },
- * // }
- * ```
+ * @throws {JsonSchemaRefResolutionError} on malformed pointers, missing
+ * targets, or chains past the depth cap.
*/
export function dereferenceJsonSchema<T = unknown>(schema: T): T {
if (!isPlainObject(schema)) return schema;
@@ -101,9 +67,8 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {
const root = schema as Record<string, unknown>;
const visiting = new WeakSet<object>();
- // Filter `__proto__`/`constructor`/`prototype` keys to avoid altering the
- // prototype of the cloned output node (which can break downstream
- // `Object.keys` / `in` checks even though the global prototype is safe).
+ // POLLUTING_KEYS filter prevents an attacker-shaped $defs entry from altering
+ // the cloned node's prototype.
const cloneChildren = (
obj: Record<string, unknown>,
visitedRefs: ReadonlySet<string>,
@@ -116,8 +81,7 @@ export function dereferenceJsonSchema<T = unknown>(schema: T): T {
.map(([k, v]) => [k, walk(v, visitedRefs, chainDepth, nodeDepth + 1)])
);
- // Function declaration so `cloneChildren` can reference `walk` despite being
- // declared earlier (function declarations are hoisted within the closure).
+ // `function` (not `const`) so `cloneChildren` above can call it via hoisting.
function walk(
node: unknown,
visitedRefs: ReadonlySet<string>,
diff --git a/ts/packages/providers/mastra/test/mastra-ref.test.ts b/ts/packages/providers/mastra/test/mastra-ref.test.ts
index fbdfce1e8..8a28bd381 100644
--- a/ts/packages/providers/mastra/test/mastra-ref.test.ts
+++ b/ts/packages/providers/mastra/test/mastra-ref.test.ts
@@ -1,20 +1,15 @@
/**
- * Integration test for the Mastra provider against the **real**
- * `@mastra/schema-compat` package (no `vi.mock` for it). This is the regression
- * test for [PLEN-2244]: a Composio tool whose `inputParameters` carry a `$ref`
- * (legal under both Draft 7 and 2020-12).
+ * Regression test for the Mastra provider against the **real**
+ * `@mastra/schema-compat` (no `vi.mock` for it). Without dereferencing,
+ * `applyCompatLayer` silently degrades a `$ref`-typed property to a permissive
+ * `anyOf` of all primitives — losing the type info from `$defs`. We assert
+ * the post-wrap schemas preserve the structure described by `$defs`.
*
- * Without dereferencing, `applyCompatLayer` silently *degrades* the `$ref`-typed
- * property to a permissive `anyOf` of all primitives — losing the type
- * information from `$defs`. This test asserts the post-wrap `inputSchema`
- * preserves the structure described by `$defs`, which is only possible if
- * `$ref` is resolved before the conversion.
- *
- * Vitest mock scoping is per-file by default, so the top-level `vi.mock` for
- * `@mastra/schema-compat` in `mastra.test.ts` does **not** leak into this file.
+ * Vitest mock scoping is per-file by default, so the top-level `vi.mock`
+ * for `@mastra/schema-compat` in `mastra.test.ts` does not leak here.
*/
-import { describe, it, expect, vi } from 'vitest';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
import type { Tool } from '@composio/core';
import { MastraProvider } from '../src';
@@ -27,22 +22,17 @@ const containsRef = (value: unknown): boolean => {
const findProperty = (schema: unknown, key: string): Record<string, unknown> | undefined => {
if (schema === null || typeof schema !== 'object') return undefined;
- const node = schema as Record<string, unknown>;
- if (node.properties && typeof node.properties === 'object') {
- const props = node.properties as Record<string, unknown>;
- if (key in props) return props[key] as Record<string, unknown>;
- for (const value of Object.values(props)) {
- const found = findProperty(value, key);
- if (found) return found;
- }
- }
- for (const value of Object.values(node)) {
+ for (const value of Object.values(schema as Record<string, unknown>)) {
if (Array.isArray(value)) {
for (const item of value) {
const found = findProperty(item, key);
if (found) return found;
}
} else if (typeof value === 'object' && value !== null) {
+ const props = value as Record<string, unknown> as Record<string, unknown>;
+ if (key in props && typeof props[key] === 'object') {
+ return props[key] as Record<string, unknown>;
+ }
const found = findProperty(value, key);
if (found) return found;
}
@@ -63,72 +53,41 @@ const refTool: Tool = {
properties: { user: { $ref: '#/$defs/User' } as never },
required: ['user'],
$defs: {
- User: {
- type: 'object',
- properties: { id: { type: 'string' } },
- required: ['id'],
- },
+ User: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
},
} as unknown as Tool['inputParameters'],
outputParameters: {
type: 'object',
properties: { item: { $ref: '#/definitions/Item' } as never },
definitions: {
- Item: {
- type: 'object',
- properties: { sku: { type: 'string' } },
- required: ['sku'],
- },
+ Item: { type: 'object', properties: { sku: { type: 'string' } }, required: ['sku'] },
},
} as unknown as Tool['outputParameters'],
};
-describe('MastraProvider regression: PLEN-2244 ($ref in JSON Schema)', () => {
- it('does not throw when wrapping a tool whose schema uses $ref / $defs', () => {
- const provider = new MastraProvider();
- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
- provider._setExecuteToolFn(executeToolFn);
-
- expect(() => provider.wrapTool(refTool, executeToolFn)).not.toThrow();
- });
+describe('MastraProvider regression: $ref in JSON Schema', () => {
+ let wrapped: { inputSchema: unknown; outputSchema: unknown };
- it('preserves type information from $defs (does not degrade $ref to permissive anyOf)', () => {
+ beforeEach(() => {
const provider = new MastraProvider();
- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
- provider._setExecuteToolFn(executeToolFn);
-
- const wrapped = provider.wrapTool(refTool, executeToolFn) as { inputSchema: unknown };
+ const exec = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
+ provider._setExecuteToolFn(exec);
+ wrapped = provider.wrapTool(refTool, exec) as typeof wrapped;
+ });
- // Without the dereference step, `$ref` is silently dropped during
- // JSON-Schema → Zod → JSON-Schema round-trip and the `id` field disappears
- // entirely (the property gets degraded to a permissive `anyOf`).
+ it('preserves type info from $defs (no degraded permissive anyOf)', () => {
const idProp = findProperty(wrapped.inputSchema, 'id');
expect(idProp).toBeDefined();
expect(idProp?.type).toBe('string');
});
- it('preserves type information from `definitions` on outputParameters (Draft 7)', () => {
- const provider = new MastraProvider();
- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
- provider._setExecuteToolFn(executeToolFn);
-
- const wrapped = provider.wrapTool(refTool, executeToolFn) as { outputSchema: unknown };
-
+ it('preserves type info from Draft-7 `definitions` on the output schema', () => {
const skuProp = findProperty(wrapped.outputSchema, 'sku');
expect(skuProp).toBeDefined();
expect(skuProp?.type).toBe('string');
});
- it('does not leave any $ref in the produced schemas', () => {
- const provider = new MastraProvider();
- const executeToolFn = vi.fn().mockResolvedValue({ data: {}, error: null, successful: true });
- provider._setExecuteToolFn(executeToolFn);
-
- const wrapped = provider.wrapTool(refTool, executeToolFn) as {
- inputSchema: unknown;
- outputSchema: unknown;
- };
-
+ it('leaves no $ref in the produced schemas', () => {
expect(containsRef(wrapped.inputSchema)).toBe(false);
expect(containsRef(wrapped.outputSchema)).toBe(false);
});