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", + ); + }, +);