signature.test.ts 12 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341
  1. import { describe, expect, test } from "bun:test"
  2. import { Effect, Schema } from "effect"
  3. import { CodeMode } from "../src/index.js"
  4. import { Tool, inputTypeScript, jsonSchemaToTypeScript, outputTypeScript } from "../src/tool.js"
  5. // A raw JSON Schema tool in the shape an MCP adapter produces: render-only input schema
  6. // whose property descriptions and constraints must surface as JSDoc in pretty signatures.
  7. const listIssues = Tool.make({
  8. description: "List issues in a repository",
  9. input: {
  10. type: "object",
  11. properties: {
  12. owner: { type: "string", description: "Repository owner" },
  13. after: { type: "string", description: "Cursor from the previous response's pageInfo" },
  14. perPage: { type: "number", description: "Results per page", default: 30 },
  15. labels: { type: "array", items: { type: "string" }, description: "Filter by labels", minItems: 1, maxItems: 10 },
  16. state: { type: "string", enum: ["open", "closed"] },
  17. },
  18. required: ["owner"],
  19. },
  20. run: () => Effect.succeed("[]"),
  21. })
  22. // An Effect Schema tool whose field annotations must flow through the emitted JSON Schema.
  23. const lookupOrder = Tool.make({
  24. description: "Look up an order",
  25. input: Schema.Struct({
  26. id: Schema.String.annotate({ description: "Order identifier" }),
  27. verbose: Schema.optionalKey(Schema.Boolean),
  28. }),
  29. output: Schema.Struct({
  30. status: Schema.String.annotate({ description: "Current order status" }),
  31. }),
  32. run: () => Effect.succeed({ status: "open" }),
  33. })
  34. describe("pretty signature rendering", () => {
  35. test("described fields get JSDoc comments; undescribed and untagged fields get none", () => {
  36. expect(inputTypeScript(listIssues, true)).toBe(
  37. [
  38. "{",
  39. " /** Repository owner */",
  40. " owner: string",
  41. " /** Cursor from the previous response's pageInfo */",
  42. " after?: string",
  43. " /**",
  44. " * Results per page",
  45. " * @default 30",
  46. " */",
  47. " perPage?: number",
  48. " /**",
  49. " * Filter by labels",
  50. " * @minItems 1",
  51. " * @maxItems 10",
  52. " */",
  53. " labels?: Array<string>",
  54. ' state?: "open" | "closed"',
  55. "}",
  56. ].join("\n"),
  57. )
  58. })
  59. test("compact mode output is unchanged by the pretty machinery", () => {
  60. expect(inputTypeScript(listIssues)).toBe(
  61. '{ owner: string; after?: string; perPage?: number; labels?: Array<string>; state?: "open" | "closed" }',
  62. )
  63. expect(inputTypeScript(lookupOrder)).toBe("{ id: string; verbose?: boolean }")
  64. expect(outputTypeScript(lookupOrder)).toBe("{ status: string }")
  65. })
  66. test("nested objects recurse with increasing indent and their own JSDoc", () => {
  67. const pretty = jsonSchemaToTypeScript(
  68. {
  69. type: "object",
  70. properties: {
  71. filter: {
  72. type: "object",
  73. description: "Search filter",
  74. properties: { state: { type: "string", description: "Issue state" } },
  75. },
  76. },
  77. },
  78. true,
  79. )
  80. expect(pretty).toBe(
  81. ["{", " /** Search filter */", " filter?: {", " /** Issue state */", " state?: string", " }", "}"].join(
  82. "\n",
  83. ),
  84. )
  85. })
  86. test("Effect Schema annotations become JSDoc on input and output fields", () => {
  87. expect(inputTypeScript(lookupOrder, true)).toBe(
  88. ["{", " /** Order identifier */", " id: string", " verbose?: boolean", "}"].join("\n"),
  89. )
  90. expect(outputTypeScript(lookupOrder, true)).toBe(
  91. ["{", " /** Current order status */", " status: string", "}"].join("\n"),
  92. )
  93. })
  94. test("constraints TypeScript cannot express surface as JSDoc tags", () => {
  95. const pretty = jsonSchemaToTypeScript(
  96. {
  97. type: "object",
  98. properties: {
  99. legacy: { type: "string", deprecated: true },
  100. homepage: { type: "string", format: "uri" },
  101. tags: { type: "array", items: { type: "string" }, minItems: 2, maxItems: 5, default: ["a", "b"] },
  102. },
  103. },
  104. true,
  105. )
  106. expect(pretty).toContain(" /** @deprecated */\n legacy?: string")
  107. expect(pretty).toContain(" /** @format uri */\n homepage?: string")
  108. expect(pretty).toContain(
  109. [
  110. " /**",
  111. ' * @default ["a","b"]',
  112. " * @minItems 2",
  113. " * @maxItems 5",
  114. " */",
  115. " tags?: Array<string>",
  116. ].join("\n"),
  117. )
  118. })
  119. test("skips an unserializable default rather than emitting a broken tag", () => {
  120. const pretty = jsonSchemaToTypeScript(
  121. { type: "object", properties: { size: { type: "number", default: 1n } } },
  122. true,
  123. )
  124. expect(pretty).toBe(["{", " size?: number", "}"].join("\n"))
  125. })
  126. test("neutralizes */ inside descriptions so nothing closes the comment early", () => {
  127. const pretty = jsonSchemaToTypeScript(
  128. { type: "object", properties: { note: { type: "string", description: "Ends */ early" } } },
  129. true,
  130. )
  131. expect(pretty).toContain(" /** Ends * / early */")
  132. expect(pretty).not.toContain("Ends */")
  133. })
  134. test("multiline descriptions become *-prefixed blocks with blank edges trimmed", () => {
  135. const pretty = jsonSchemaToTypeScript(
  136. {
  137. type: "object",
  138. properties: { query: { type: "string", description: "\nFirst line\n\nSecond line\n" } },
  139. },
  140. true,
  141. )
  142. expect(pretty).toBe(
  143. ["{", " /**", " * First line", " *", " * Second line", " */", " query?: string", "}"].join("\n"),
  144. )
  145. })
  146. test("stays total on cyclic $refs and pathological nesting in both modes", () => {
  147. const cyclic = {
  148. $ref: "#/$defs/Node",
  149. $defs: { Node: { type: "object", properties: { child: { $ref: "#/$defs/Node" }, name: { type: "string" } } } },
  150. } as const
  151. expect(jsonSchemaToTypeScript(cyclic)).toBe("{ child?: Node; name?: string }")
  152. expect(jsonSchemaToTypeScript(cyclic, true)).toContain("child?: Node")
  153. let deep: Record<string, unknown> = { type: "string" }
  154. for (let level = 0; level < 12; level += 1) deep = { type: "object", properties: { next: deep } }
  155. for (const pretty of [false, true]) {
  156. const rendered = jsonSchemaToTypeScript(deep, pretty)
  157. expect(rendered).toContain("unknown")
  158. expect(rendered).toContain("next?:")
  159. }
  160. })
  161. })
  162. describe("non-identifier property names render as quoted keys", () => {
  163. // MCP-style schemas routinely carry property names that are not bare TS identifiers
  164. // (`foo-bar`, `@type`, dotted names); the rendered signature must quote them so the
  165. // model sees a valid TypeScript object type. Bare identifiers stay unquoted.
  166. const rawSchema = {
  167. type: "object",
  168. properties: {
  169. "foo-bar": { type: "string" },
  170. "@type": { type: "string" },
  171. "x.y": { type: "number", description: "Dotted name" },
  172. "123": { type: "number" },
  173. plain: { type: "boolean" },
  174. },
  175. required: ["@type"],
  176. } as const
  177. test("compact rendering quotes non-identifier keys and leaves identifiers bare", () => {
  178. expect(jsonSchemaToTypeScript(rawSchema)).toBe(
  179. '{ "123"?: number; "foo-bar"?: string; "@type": string; "x.y"?: number; plain?: boolean }',
  180. )
  181. })
  182. test("pretty rendering quotes non-identifier keys and keeps their JSDoc", () => {
  183. expect(jsonSchemaToTypeScript(rawSchema, true)).toBe(
  184. [
  185. "{",
  186. ' "123"?: number',
  187. ' "foo-bar"?: string',
  188. ' "@type": string',
  189. " /** Dotted name */",
  190. ' "x.y"?: number',
  191. " plain?: boolean",
  192. "}",
  193. ].join("\n"),
  194. )
  195. })
  196. test("JSON Schema input and output signatures of a tool both quote", () => {
  197. const tool = Tool.make({
  198. description: "Adapter tool with awkward field names",
  199. input: rawSchema,
  200. output: {
  201. type: "object",
  202. properties: { "content-type": { type: "string" } },
  203. required: ["content-type"],
  204. } as const,
  205. run: () => Effect.succeed({ "content-type": "text/plain" }),
  206. })
  207. expect(inputTypeScript(tool)).toContain('"foo-bar"?: string')
  208. expect(outputTypeScript(tool)).toBe('{ "content-type": string }')
  209. expect(outputTypeScript(tool, true)).toBe(["{", ' "content-type": string', "}"].join("\n"))
  210. })
  211. test("Effect Schema structs with non-identifier field names quote too", () => {
  212. const tool = Tool.make({
  213. description: "Schema tool with awkward field names",
  214. input: Schema.Struct({ "foo-bar": Schema.String, plain: Schema.optionalKey(Schema.Number) }),
  215. run: () => Effect.succeed(null),
  216. })
  217. expect(inputTypeScript(tool)).toBe('{ "foo-bar": string; plain?: number }')
  218. expect(inputTypeScript(tool, true)).toBe(["{", ' "foo-bar": string', " plain?: number", "}"].join("\n"))
  219. })
  220. })
  221. describe("union schemas render every alternative", () => {
  222. test("anyOf with a number branch keeps sibling alternatives", () => {
  223. const schema = {
  224. anyOf: [{ type: "string" }, { type: "number" }],
  225. } as const
  226. expect(jsonSchemaToTypeScript(schema)).toBe("string | number")
  227. expect(jsonSchemaToTypeScript(schema, true)).toBe("string | number")
  228. })
  229. test("nullable numeric unions keep null", () => {
  230. const schema = {
  231. oneOf: [{ type: "number" }, { type: "null" }],
  232. } as const
  233. expect(jsonSchemaToTypeScript(schema)).toBe("number | null")
  234. expect(jsonSchemaToTypeScript(schema, true)).toBe("number | null")
  235. })
  236. test("tool input and output signatures preserve numeric unions", () => {
  237. const tool = Tool.make({
  238. description: "Tool with numeric unions",
  239. input: {
  240. type: "object",
  241. properties: {
  242. value: { anyOf: [{ type: "string" }, { type: "number" }] },
  243. },
  244. } as const,
  245. output: { anyOf: [{ type: "number" }, { type: "boolean" }] } as const,
  246. run: () => Effect.succeed(1),
  247. })
  248. expect(inputTypeScript(tool)).toBe("{ value?: string | number }")
  249. expect(outputTypeScript(tool)).toBe("number | boolean")
  250. })
  251. })
  252. describe("pretty signatures in search results", () => {
  253. const runtime = CodeMode.make({ tools: { github: { list_issues: listIssues }, orders: { lookup: lookupOrder } } })
  254. const search = async (query: string) => {
  255. const result = await Effect.runPromise(
  256. runtime.execute(`return await tools.$codemode.search({ query: ${JSON.stringify(query)} })`),
  257. )
  258. expect(result.ok).toBe(true)
  259. if (!result.ok) throw new Error("search failed")
  260. return result.value as { items: Array<{ path: string; signature: string }>; total: number }
  261. }
  262. test("a raw JSON Schema (MCP-style) tool's result signature carries field JSDoc and tags", async () => {
  263. const { items } = await search("list issues repository")
  264. const item = items.find(({ path }) => path === "tools.github.list_issues")!
  265. expect(item.signature).toBe(
  266. [
  267. "tools.github.list_issues(input: {",
  268. " /** Repository owner */",
  269. " owner: string",
  270. " /** Cursor from the previous response's pageInfo */",
  271. " after?: string",
  272. " /**",
  273. " * Results per page",
  274. " * @default 30",
  275. " */",
  276. " perPage?: number",
  277. " /**",
  278. " * Filter by labels",
  279. " * @minItems 1",
  280. " * @maxItems 10",
  281. " */",
  282. " labels?: Array<string>",
  283. ' state?: "open" | "closed"',
  284. "}): Promise<unknown>",
  285. ].join("\n"),
  286. )
  287. })
  288. test("an annotated Effect Schema tool's result signature carries field JSDoc (exact-path lookup too)", async () => {
  289. for (const query of ["look up order", "tools.orders.lookup"]) {
  290. const { items } = await search(query)
  291. const item = items.find(({ path }) => path === "tools.orders.lookup")!
  292. expect(item.signature).toBe(
  293. [
  294. "tools.orders.lookup(input: {",
  295. " /** Order identifier */",
  296. " id: string",
  297. " verbose?: boolean",
  298. "}): Promise<{",
  299. " /** Current order status */",
  300. " status: string",
  301. "}>",
  302. ].join("\n"),
  303. )
  304. }
  305. })
  306. test("the inline catalog line for the same tool stays single-line compact", () => {
  307. const instructions = runtime.instructions()
  308. expect(instructions).toContain(
  309. ' - tools.github.list_issues(input: { owner: string; after?: string; perPage?: number; labels?: Array<string>; state?: "open" | "closed" }): Promise<unknown> // List issues in a repository',
  310. )
  311. expect(instructions).toContain(
  312. " - tools.orders.lookup(input: { id: string; verbose?: boolean }): Promise<{ status: string }> // Look up an order",
  313. )
  314. expect(instructions).not.toContain("/**")
  315. })
  316. })