From 4a3e25beabfa713712fc343b5647fe378a5758b1 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Mon, 31 Aug 2026 23:06:49 -0500 Subject: [PATCH] feat(codemode): compact schema constraint comments (#46521) --- packages/codemode/src/tool-schema.ts | 20 ++- packages/codemode/test/signature.test.ts | 172 +++++++++++++------- packages/core/test/codemode/catalog.test.ts | 4 +- 3 files changed, 123 insertions(+), 73 deletions(-) diff --git a/packages/codemode/src/tool-schema.ts b/packages/codemode/src/tool-schema.ts index 98a90215161..4e39cb9ed63 100644 --- a/packages/codemode/src/tool-schema.ts +++ b/packages/codemode/src/tool-schema.ts @@ -79,15 +79,19 @@ const docTags = (schema: JsonSchema): Array => { } // Neutralize `*\/` so model-provided schema text cannot terminate generated documentation. -const jsdoc = (description: string | undefined, tags: ReadonlyArray, pad: string): string => { - const lines = [...(description === undefined ? [] : description.split("\n")), ...tags].map((line) => - line.replaceAll("*/", "* /").replace(/\s+$/, ""), - ) +const jsdoc = (description: string | undefined, summary: string, pad: string): string => { + const lines = (description ?? "").split("\n").map((line) => line.replace(/\s+$/, "")) while (lines.length > 0 && lines[0]!.trim() === "") lines.shift() while (lines.length > 0 && lines[lines.length - 1]!.trim() === "") lines.pop() - if (lines.length === 0) return "" - if (lines.length === 1) return `${pad}/** ${lines[0]} */\n` - const body = lines.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n") + const inline = lines.length === 1 ? `${lines[0]}${lines[0].endsWith(".") ? "" : "."} ${summary}` : summary + const content = + summary && lines.length === 1 && !summary.includes("\n") && pad.length + inline.length + 7 <= 120 + ? [inline] + : [...lines, ...(summary ? summary.split("\n") : [])] + if (content.length === 0) return "" + const escaped = content.map((line) => line.replaceAll("*/", "* /")) + if (escaped.length === 1 && pad.length + escaped[0].length + 7 <= 120) return `${pad}/** ${escaped[0]} */\n` + const body = escaped.map((line) => `${pad} *${line === "" ? "" : ` ${line}`}`).join("\n") return `${pad}/**\n${body}\n${pad} */\n` } @@ -167,7 +171,7 @@ const renderSchema = ( if (properties.length === 0 && indexType === undefined) return "{}" const pad = " ".repeat(depth + 1) const lines = properties.map( - (entry) => `${jsdoc(entry[1].description, docTags(entry[1]), pad)}${pad}${field(entry)},`, + (entry) => `${jsdoc(entry[1].description, docTags(entry[1]).join(" "), pad)}${pad}${field(entry)},`, ) if (indexType !== undefined) lines.push(`${pad}[key: string]: ${indexType},`) return `{\n${lines.join("\n")}\n${" ".repeat(depth)}}` diff --git a/packages/codemode/test/signature.test.ts b/packages/codemode/test/signature.test.ts index ce57fc4efad..dde58de1223 100644 --- a/packages/codemode/test/signature.test.ts +++ b/packages/codemode/test/signature.test.ts @@ -36,7 +36,7 @@ const lookupOrder = Tool.make({ }) describe("pretty signature rendering", () => { - test("described fields get JSDoc comments; undescribed and untagged fields get none", () => { + test("described fields get compact JSDoc; undescribed and unconstrained fields get none", () => { expect(inputTypeScript(listIssues, true)).toBe( [ "{", @@ -44,16 +44,9 @@ describe("pretty signature rendering", () => { " owner: string,", " /** Cursor from the previous response's pageInfo */", " after?: string,", - " /**", - " * Results per page", - " * @default 30", - " */", + " /** Results per page. @default 30 */", " perPage?: number,", - " /**", - " * Filter by labels", - " * @minItems 1", - " * @maxItems 10", - " */", + " /** Filter by labels. @minItems 1 @maxItems 10 */", " labels?: Array,", ' state?: "open" | "closed",', "}", @@ -105,7 +98,7 @@ describe("pretty signature rendering", () => { ) }) - test("constraints TypeScript cannot express surface as JSDoc tags", () => { + test("constraints and annotations share compact tagged JSDoc", () => { const pretty = jsonSchemaToTypeScript( { type: "object", @@ -119,19 +112,10 @@ describe("pretty signature rendering", () => { ) expect(pretty).toContain(" /** @deprecated */\n legacy?: string") expect(pretty).toContain(" /** @format uri */\n homepage?: string") - expect(pretty).toContain( - [ - " /**", - ' * @default ["a","b"]', - " * @minItems 2", - " * @maxItems 5", - " */", - " tags?: Array", - ].join("\n"), - ) + expect(pretty).toContain(' /** @default ["a","b"] @minItems 2 @maxItems 5 */\n tags?: Array') }) - test("skips an unserializable default rather than emitting a broken tag", () => { + test("skips an unserializable default rather than emitting a broken summary", () => { const pretty = jsonSchemaToTypeScript( { type: "object", properties: { size: { type: "number", default: 1n } } }, true, @@ -151,9 +135,18 @@ describe("pretty signature rendering", () => { [{ type: "array", minItems: 0 }, "@minItems 0", "Array"], [{ type: "array", maxItems: 0 }, "@maxItems 0", "Array"], [{ type: "array", uniqueItems: true }, "@uniqueItems true", "Array"], - ] as const)("renders constraint %j without changing the compact type", (value, tag, type) => { + [{ type: "string", minLength: 0, maxLength: 0 }, "@minLength 0 @maxLength 0", "string"], + [{ type: "array", minItems: 0, maxItems: 0 }, "@minItems 0 @maxItems 0", "Array"], + [ + { type: "array", minItems: 1, maxItems: 10, uniqueItems: true }, + "@minItems 1 @maxItems 10 @uniqueItems true", + "Array", + ], + ] as const)("renders constraint %j without changing the compact type", (value, summary, type) => { const schema = { type: "object", properties: { value } } - expect(jsonSchemaToTypeScript(schema, true)).toBe(["{", ` /** ${tag} */`, ` value?: ${type},`, "}"].join("\n")) + expect(jsonSchemaToTypeScript(schema, true)).toBe( + ["{", ` /** ${summary} */`, ` value?: ${type},`, "}"].join("\n"), + ) expect(jsonSchemaToTypeScript(schema)).toBe(`{ value?: ${type} }`) }) @@ -188,30 +181,19 @@ describe("pretty signature rendering", () => { ) }) - test.each([false, null, ""])("preserves default %j alongside constraint tags", (value) => { + test.each([false, null, ""])("preserves default %j alongside constraints", (value) => { expect(jsonSchemaToTypeScript({ properties: { value: { default: value, minLength: 0 } } }, true)).toContain( - ` * @default ${JSON.stringify(value)}\n * @minLength 0\n`, + ` /** @default ${JSON.stringify(value)} @minLength 0 */\n`, ) }) - test("escapes comment terminators in tag values", () => { + test("escapes comment terminators in summary values", () => { expect( jsonSchemaToTypeScript( { properties: { value: { type: "string", default: "*/", format: "*/", pattern: "^a*/b$" } } }, true, ), - ).toBe( - [ - "{", - " /**", - ' * @default "* /"', - " * @format * /", - " * @pattern ^a* /b$", - " */", - " value?: string,", - "}", - ].join("\n"), - ) + ).toBe(["{", ' /** @default "* /" @format * / @pattern ^a* /b$ */', " value?: string,", "}"].join("\n")) }) test("neutralizes */ inside descriptions so nothing closes the comment early", () => { @@ -236,6 +218,88 @@ describe("pretty signature rendering", () => { ) }) + test("preserves inclusive and exclusive numeric bounds together", () => { + expect( + jsonSchemaToTypeScript( + { + properties: { + value: { + type: "integer", + minimum: -10, + maximum: 10, + exclusiveMinimum: -5, + exclusiveMaximum: 5, + multipleOf: 2, + }, + }, + }, + true, + ), + ).toContain( + " /** @integer @minimum -10 @maximum 10 @exclusiveMinimum -5 @exclusiveMaximum 5 @multipleOf 2 */\n value?: number,", + ) + }) + + test.each([ + ["Maximum attempts", "Maximum attempts."], + ["Maximum attempts.", "Maximum attempts."], + ["Maximum attempts!", "Maximum attempts!."], + ])("combines a short description (%s) with its summary", (description, expected) => { + expect( + jsonSchemaToTypeScript( + { properties: { attempts: { description, type: "integer", minimum: 1, default: 3 } } }, + true, + ), + ).toContain(` /** ${expected} @default 3 @integer @minimum 1 */\n`) + }) + + test("keeps multiline descriptions intact and appends a compact summary", () => { + expect( + jsonSchemaToTypeScript( + { + properties: { + attempts: { + description: "\nMaximum attempts\n\nIncludes the initial request.\n", + type: "integer", + minimum: 1, + }, + }, + }, + true, + ), + ).toBe( + [ + "{", + " /**", + " * Maximum attempts", + " *", + " * Includes the initial request.", + " * @integer @minimum 1", + " */", + " attempts?: number,", + "}", + ].join("\n"), + ) + }) + + test("uses a block for long descriptions without truncating or rewriting them", () => { + const description = "A detailed description. ".repeat(8).trim() + expect(jsonSchemaToTypeScript({ properties: { name: { type: "string", description, minLength: 1 } } }, true)).toBe( + ["{", " /**", ` * ${description}`, " * @minLength 1", " */", " name?: string,", "}"].join("\n"), + ) + }) + + test("preserves pattern backslashes and prefixes every line of multiline summary values", () => { + expect( + jsonSchemaToTypeScript( + { properties: { value: { type: "string", pattern: "^\\d+\n*/$", default: "a\nb" } } }, + true, + ), + ).toBe( + ["{", " /**", ' * @default "a\\nb" @pattern ^\\d+', " * * /$", " */", " value?: string,", "}"].join("\n"), + ) + }) + test("stays total on cyclic $refs and pathological nesting in both modes", () => { const cyclic = { $ref: "#/$defs/Node", @@ -486,22 +550,11 @@ describe("JSDoc signatures in catalogs and search results", () => { }) const type = [ "{", - " /**", - " * @integer", - " * @minimum 0", - " * @maximum 10", - " */", + " /** @integer @minimum 0 @maximum 10 */", " count: number,", - " /**", - " * @minLength 1", - " * @maxLength 20", - " * @pattern ^[a-z]+$", - " */", + " /** @minLength 1 @maxLength 20 @pattern ^[a-z]+$ */", " name: string,", - " /**", - " * @minItems 1", - " * @maxItems 5", - " */", + " /** @minItems 1 @maxItems 5 */", " labels: Array,", "}", ].join("\n") @@ -522,7 +575,7 @@ describe("JSDoc signatures in catalogs and search results", () => { return result.value as { items: Array<{ path: string; signature: string }>; remaining: number } } - test("a raw JSON Schema (MCP-style) tool's result signature carries field JSDoc and tags", async () => { + test("a raw JSON Schema (MCP-style) tool's result signature carries field JSDoc and summaries", async () => { const { items } = await search("list issues repository") const item = items.find(({ path }) => path === "tools.github.list_issues")! expect(item.signature).toBe( @@ -532,16 +585,9 @@ describe("JSDoc signatures in catalogs and search results", () => { " owner: string,", " /** Cursor from the previous response's pageInfo */", " after?: string,", - " /**", - " * Results per page", - " * @default 30", - " */", + " /** Results per page. @default 30 */", " perPage?: number,", - " /**", - " * Filter by labels", - " * @minItems 1", - " * @maxItems 10", - " */", + " /** Filter by labels. @minItems 1 @maxItems 10 */", " labels?: Array,", ' state?: "open" | "closed",', "}): Promise", diff --git a/packages/core/test/codemode/catalog.test.ts b/packages/core/test/codemode/catalog.test.ts index a4ec34c28d1..301b7f52543 100644 --- a/packages/core/test/codemode/catalog.test.ts +++ b/packages/core/test/codemode/catalog.test.ts @@ -136,8 +136,8 @@ describe("CodeModeInstructions.render", () => { ) expect(partial).not.toContain("surrounding top-level agent tools") expect(partial).toContain("- search(input: {") - expect(partial).toContain(" /**\n * @integer\n * @exclusiveMinimum 0\n */\n limit?: number,") - expect(partial).toContain(" /**\n * @integer\n * @minimum 0\n */\n offset?: number,") + expect(partial).toContain(" /** @integer @exclusiveMinimum 0 */\n limit?: number,") + expect(partial).toContain(" /** @integer @minimum 0 */\n offset?: number,") expect(partial).not.toContain("tools.orders.lookup(input:") })