From 02440f67158cfb0a827be2e578d9f836a659a524 Mon Sep 17 00:00:00 2001 From: Aiden Cline <63023139+rekram1-node@users.noreply.github.com> Date: Mon, 31 Aug 2026 23:54:58 -0500 Subject: [PATCH] feat(codemode): label item and value schema comments (#46542) --- packages/codemode/src/tool-schema.ts | 41 +++-- packages/codemode/test/signature.test.ts | 191 ++++++++++++++++++++++- 2 files changed, 217 insertions(+), 15 deletions(-) diff --git a/packages/codemode/src/tool-schema.ts b/packages/codemode/src/tool-schema.ts index 4e39cb9ed63..f1ab3866206 100644 --- a/packages/codemode/src/tool-schema.ts +++ b/packages/codemode/src/tool-schema.ts @@ -78,16 +78,39 @@ const docTags = (schema: JsonSchema): Array => { return tags } -// Neutralize `*\/` so model-provided schema text cannot terminate generated documentation. -const jsdoc = (description: string | undefined, summary: string, pad: string): string => { - const lines = (description ?? "").split("\n").map((line) => line.replace(/\s+$/, "")) +const docLines = (schema: JsonSchema, width: number): Array => { + const summary = docTags(schema).join(" ") + const lines = (schema.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() 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") : [])] + return summary && lines.length === 1 && !summary.includes("\n") && width + inline.length + 7 <= 120 + ? [inline] + : [...lines, ...(summary ? summary.split("\n") : [])] +} + +// Neutralize `*\/` so model-provided schema text cannot terminate generated documentation. +const jsdoc = (schema: JsonSchema, pad: string): string => { + const content = docLines(schema, pad.length) + const types = typeof schema.type === "string" ? [schema.type] : (schema.type ?? []) + + const append = (label: string, child: JsonSchema) => { + docLines(child, pad.length + label.length + 2).forEach((line, index) => { + if (index === 0) { + content.push(`${label}: ${line}`) + return + } + content.push(line ? ` ${line}` : "") + }) + } + + // Document only the immediate contents; recursive labels obscure which level a constraint belongs to. + if (types.includes("array") && schema.items) append("Each item", schema.items) + if ((types.includes("object") || schema.properties) && typeof schema.additionalProperties === "object") { + const label = Object.keys(schema.properties ?? {}).length > 0 ? "Each additional value" : "Each value" + append(label, schema.additionalProperties) + } + 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` @@ -170,9 +193,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]).join(" "), pad)}${pad}${field(entry)},`, - ) + const lines = properties.map((entry) => `${jsdoc(entry[1], 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 dde58de1223..2dcce370062 100644 --- a/packages/codemode/test/signature.test.ts +++ b/packages/codemode/test/signature.test.ts @@ -123,6 +123,175 @@ describe("pretty signature rendering", () => { expect(pretty).toBe(["{", " size?: number,", "}"].join("\n")) }) + test("labels immediate item and dictionary value metadata above the field", () => { + const schema = { + properties: { + recipients: { + type: "array", + description: "People to notify", + minItems: 1, + items: { type: "string", description: "Email address", format: "email" }, + }, + scores: { type: "object", additionalProperties: { type: "number", minimum: 0 } }, + names: { type: "array", items: { type: "string", description: "Display name" } }, + plain: { type: "object", additionalProperties: { type: "string" } }, + }, + } + expect(jsonSchemaToTypeScript(schema, true)).toBe( + [ + "{", + " /**", + " * People to notify. @minItems 1", + " * Each item: Email address. @format email", + " */", + " recipients?: Array,", + " /** Each value: @minimum 0 */", + " scores?: {", + " [key: string]: number,", + " },", + " /** Each item: Display name */", + " names?: Array,", + " plain?: {", + " [key: string]: string,", + " },", + "}", + ].join("\n"), + ) + expect(jsonSchemaToTypeScript(schema)).toBe( + "{ recipients?: Array; scores?: { [key: string]: number }; names?: Array; plain?: { [key: string]: string } }", + ) + }) + + test("does not apply additional property metadata to named properties", () => { + expect( + jsonSchemaToTypeScript( + { + properties: { + scores: { + type: "object", + properties: { title: { type: "string", description: "Score title" } }, + additionalProperties: { type: "number", minimum: 0 }, + }, + }, + }, + true, + ), + ).toBe( + [ + "{", + " /** Each additional value: @minimum 0 */", + " scores?: {", + " /** Score title */", + " title?: string,", + " [key: string]: number,", + " },", + "}", + ].join("\n"), + ) + }) + + test("labels array and dictionary contents in type-array unions", () => { + expect( + jsonSchemaToTypeScript( + { + properties: { + recipients: { type: ["array", "null"], items: { type: "string", format: "email" } }, + scores: { type: ["object", "null"], additionalProperties: { type: "number", minimum: 0 } }, + either: { + type: ["array", "object"], + items: { type: "string", minLength: 1 }, + additionalProperties: { type: "number", minimum: 0 }, + }, + }, + }, + true, + ), + ).toBe( + [ + "{", + " /** Each item: @format email */", + " recipients?: Array | null,", + " /** Each value: @minimum 0 */", + " scores?: {", + " [key: string]: number,", + " } | null,", + " /**", + " * Each item: @minLength 1", + " * Each value: @minimum 0", + " */", + " either?: Array | {", + " [key: string]: number,", + " },", + "}", + ].join("\n"), + ) + }) + + test("keeps multiline item metadata indented under its label and escapes terminators", () => { + expect( + jsonSchemaToTypeScript( + { + properties: { + values: { + type: "array", + minItems: 1, + items: { type: "string", description: "\nFirst */ line\n\nSecond line\n", pattern: "^\\d+\n*/$" }, + }, + }, + }, + true, + ), + ).toBe( + [ + "{", + " /**", + " * @minItems 1", + " * Each item: First * / line", + " *", + " * Second line", + " * @pattern ^\\d+", + " * * /$", + " */", + " values?: Array,", + "}", + ].join("\n"), + ) + }) + + test("does not flatten nested containers, reference targets, or branches into item metadata", () => { + expect( + jsonSchemaToTypeScript( + { + $defs: { Email: { type: "string", format: "email" } }, + properties: { + matrix: { type: "array", items: { type: "array", minItems: 2, items: { type: "integer", minimum: 0 } } }, + refs: { type: "array", items: { $ref: "#/$defs/Email", description: "Recipient" } }, + choices: { + type: "array", + items: { + anyOf: [ + { type: "string", minLength: 1 }, + { type: "number", minimum: 0 }, + ], + }, + }, + }, + }, + true, + ), + ).toBe( + [ + "{", + " /** Each item: @minItems 2 */", + " matrix?: Array>,", + " /** Each item: Recipient */", + " refs?: Array,", + " choices?: Array,", + "}", + ].join("\n"), + ) + }) + test.each([ [{ type: "number", minimum: 0 }, "@minimum 0", "number"], [{ type: "number", maximum: 0 }, "@maximum 0", "number"], @@ -524,9 +693,10 @@ describe("JSDoc signatures in catalogs and search results", () => { properties: { count: { type: "integer", minimum: 0, maximum: 10 }, name: { type: "string", minLength: 1, maxLength: 20, pattern: "^[a-z]+$" }, - labels: { type: "array", items: { type: "string" }, minItems: 1, maxItems: 5 }, + labels: { type: "array", items: { type: "string", minLength: 1 }, minItems: 1, maxItems: 5 }, + scores: { type: "object", additionalProperties: { type: "integer", minimum: 0 } }, }, - required: ["count", "name", "labels"], + required: ["count", "name", "labels", "scores"], }, }, { @@ -534,7 +704,11 @@ describe("JSDoc signatures in catalogs and search results", () => { schema: Schema.Struct({ count: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0), Schema.isLessThanOrEqualTo(10)), name: Schema.String.check(Schema.isMinLength(1), Schema.isMaxLength(20), Schema.isPattern(/^[a-z]+$/)), - labels: Schema.Array(Schema.String).check(Schema.isMinLength(1), Schema.isMaxLength(5)), + labels: Schema.Array(Schema.String.check(Schema.isMinLength(1))).check( + Schema.isMinLength(1), + Schema.isMaxLength(5), + ), + scores: Schema.Record(Schema.String, Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))), }), }, ])("$source constraints survive input/output catalog and search signatures", async ({ schema }) => { @@ -544,7 +718,7 @@ describe("JSDoc signatures in catalogs and search results", () => { description: "Constrained tool", input: schema, output: schema, - execute: () => Effect.succeed({ count: 1, name: "test", labels: ["test"] }), + execute: () => Effect.succeed({ count: 1, name: "test", labels: ["test"], scores: { test: 1 } }), }), }, }) @@ -554,8 +728,15 @@ describe("JSDoc signatures in catalogs and search results", () => { " count: number,", " /** @minLength 1 @maxLength 20 @pattern ^[a-z]+$ */", " name: string,", - " /** @minItems 1 @maxItems 5 */", + " /**", + " * @minItems 1 @maxItems 5", + " * Each item: @minLength 1", + " */", " labels: Array,", + " /** Each value: @integer @minimum 0 */", + " scores: {", + " [key: string]: number,", + " },", "}", ].join("\n") const signature = `tools.constrained(input: ${type}): Promise<${type}>`