From 832984c2ccc77a627b0c2f6bce2093e55ba1bc6a Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Mon, 16 Nov 2026 10:35:14 +0800 Subject: [PATCH] fix(cli): describe a contract option whose description sits inside .optional() (#11661) * fix(cli): describe a contract option whose description sits inside .optional() zod does not carry a wrapped schema's description to its .optional() wrapper. Since #10798 projected analyze_javascript_application from its contract, source_paths is javaScriptSourcePathsSchema.optional(), so 'analyze --help' and 'analyze-javascript-application --help' listed --source-path with no description and cliOptionAliases.test.ts fails on main. The contract option projection now reads the field's description through its wrappers (describedThroughWrappers), once for every argv branch, in place of three per-branch copies that read only the outer schema. The opener and member option projections use the same reader. * test(cli): assert the exact help text of a wrapped contract field and of a projection override --- src/cli/contractCliDescription.ts | 51 +++++++++++-------- .../cli/cliWrappedFieldDescription.test.ts | 37 ++++++++++++++ 2 files changed, 68 insertions(+), 20 deletions(-) create mode 100644 tests/boundary/cli/cliWrappedFieldDescription.test.ts diff --git a/src/cli/contractCliDescription.ts b/src/cli/contractCliDescription.ts index 2128fe78d7..9ddc6575e0 100644 --- a/src/cli/contractCliDescription.ts +++ b/src/cli/contractCliDescription.ts @@ -753,20 +753,32 @@ const camelCase = (field: string): string => const admitsOmission = (field: z.ZodType): boolean => z.object({ value: field }).safeParse({}).success; +const isWrapper = (value: z.ZodType) => + value instanceof z.ZodOptional || + value instanceof z.ZodExactOptional || + value instanceof z.ZodDefault || + value instanceof z.ZodPrefault || + value instanceof z.ZodNullable || + value instanceof z.ZodReadonly; + const core = (value: z.ZodType): z.ZodType => { let current = value; - while ( - current instanceof z.ZodOptional || - current instanceof z.ZodExactOptional || - current instanceof z.ZodDefault || - current instanceof z.ZodPrefault || - current instanceof z.ZodNullable || - current instanceof z.ZodReadonly - ) - current = current.unwrap() as z.ZodType; + while (isWrapper(current)) current = current.unwrap() as z.ZodType; return current; }; +/** + * The description of a field, read through wrappers such as `.optional()`: + * zod does not carry a wrapped schema's description to its wrapper, and the + * advertised JSON Schema shows the wrapped description. + */ +const describedThroughWrappers = (value: z.ZodType): string | undefined => { + let current = value; + while (current.description === undefined && isWrapper(current)) + current = current.unwrap() as z.ZodType; + return current.description; +}; + /** * Accept only field forms argv can carry, so a new contract field cannot * reach the CLI with an unreviewed spelling. @@ -1401,7 +1413,8 @@ const describeTargetOpening = ( throw new Error(`${opener}.${field} does not admit ${value}`); schema = z.enum(projected.values).optional(); } - const description = projected.description ?? declared.description; + const description = + projected.description ?? describedThroughWrappers(declared); if (description !== undefined) schema = schema.describe(description); return { field, @@ -1895,16 +1908,12 @@ export const describeContractCommand = < : text; if (viewSelection && viewDelivery !== undefined) schema = schema.describe(viewOptionHelp(viewDelivery)); - else if (declared.description !== undefined) - schema = schema.describe(declared.description); } else if (nullFlag !== undefined) { // The flag spells null, so the option itself takes only a value. if (!declared.safeParse(null).success) throw new Error(`${contract.name}.${field} does not admit null`); assertArgvField(contract.name, field, declared); schema = argvDecimal(core(declared).optional()); - if (declared.description !== undefined) - schema = schema.describe(declared.description); } else if (delivery) schema = viewDelivery?.viewSelectsSummary === true @@ -1917,8 +1926,6 @@ export const describeContractCommand = < ? z.array(localPathStringSchema) : localPathStringSchema; schema = admitsOmission(declared) ? admitted.optional() : admitted; - if (declared.description !== undefined) - schema = schema.describe(declared.description); } else { assertArgvField(contract.name, field, declared); schema = argvDecimal(argvOptional(declared)); @@ -1935,9 +1942,12 @@ export const describeContractCommand = < schema = schema.default(projected.default as never); if (described !== undefined) schema = schema.describe(described); } - if (projected?.description !== undefined) - schema = schema.describe(projected.description); - const description = schema.description; + const description = + projected?.description ?? + schema.description ?? + describedThroughWrappers(declared); + if (description !== undefined && description !== schema.description) + schema = schema.describe(description); const value = core(declared); const selector = selectorOptions[field]; let selectorOption: ContractCliSelectorOption | undefined; @@ -2060,7 +2070,8 @@ export const describeContractCommand = < // An omitted member stays omitted; the contract applies its default. schema = argvDecimal(omittable(withoutDefault(memberDeclared))); } - const description = projected.description ?? memberDeclared.description; + const description = + projected.description ?? describedThroughWrappers(memberDeclared); if (description !== undefined) schema = schema.describe(description); const value = core(memberDeclared); return [ diff --git a/tests/boundary/cli/cliWrappedFieldDescription.test.ts b/tests/boundary/cli/cliWrappedFieldDescription.test.ts new file mode 100644 index 0000000000..49a54c6fe7 --- /dev/null +++ b/tests/boundary/cli/cliWrappedFieldDescription.test.ts @@ -0,0 +1,37 @@ +import { expect, it } from "vitest"; + +import { createCli } from "../../../src/cli.js"; +import { javaScriptSourcePathsSchema } from "../../../src/domain/javascript/javascriptSourceSelection.js"; + +const help = async (command: string): Promise => { + let stdout = ""; + await createCli({}).serve([command, "--help"], { + env: {}, + exit: () => undefined, + stdout: (text) => { + stdout += text; + }, + }); + return stdout; +}; + +/** The help line of one option, with its description. */ +const optionLine = (text: string, option: string): string | undefined => + text.split("\n").find((line) => line.trimStart().startsWith(`${option} `)); + +// `source_paths` is `javaScriptSourcePathsSchema.optional()`; zod keeps the +// description on the wrapped schema only. A projection description replaces +// the contract's (`format` is shown as "Application artifact format"). +it.each(["analyze-javascript-application", "analyze"])( + "%s --help describes a wrapped contract field and keeps the projection's override", + async (command) => { + const text = await help(command); + const description = javaScriptSourcePathsSchema.description!; + expect(optionLine(text, "--source-path")).toContain( + description.slice(0, 60), + ); + expect(optionLine(text, "--artifact-format")).toContain( + "Application artifact format", + ); + }, +);