feat(codemode): label item and value schema comments (#46542)

This commit is contained in:
Aiden Cline
2026-08-31 23:54:58 -05:00
committed by GitHub
Unverified
parent d46ed9e9db
commit 02440f6715
2 changed files with 217 additions and 15 deletions
+31 -10
View File
@@ -78,16 +78,39 @@ const docTags = (schema: JsonSchema): Array<string> => {
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<string> => {
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)}}`
}
+186 -5
View File
@@ -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<string>,",
" /** Each value: @minimum 0 */",
" scores?: {",
" [key: string]: number,",
" },",
" /** Each item: Display name */",
" names?: Array<string>,",
" plain?: {",
" [key: string]: string,",
" },",
"}",
].join("\n"),
)
expect(jsonSchemaToTypeScript(schema)).toBe(
"{ recipients?: Array<string>; scores?: { [key: string]: number }; names?: Array<string>; 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<string> | null,",
" /** Each value: @minimum 0 */",
" scores?: {",
" [key: string]: number,",
" } | null,",
" /**",
" * Each item: @minLength 1",
" * Each value: @minimum 0",
" */",
" either?: Array<string> | {",
" [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<string>,",
"}",
].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<Array<number>>,",
" /** Each item: Recipient */",
" refs?: Array<string>,",
" choices?: Array<string | number>,",
"}",
].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<string>,",
" /** Each value: @integer @minimum 0 */",
" scores: {",
" [key: string]: number,",
" },",
"}",
].join("\n")
const signature = `tools.constrained(input: ${type}): Promise<${type}>`