| 128 | const parseContext = options.parseContext ?? makeParser(contextConfig, { allowLeftovers: true }) as any |
| 129 | |
| 130 | const buildHelpDoc = (commandPath: ReadonlyArray<string>): HelpDoc => { |
| 131 | const args: Array<ArgDoc> = [] |
| 132 | const flags: Array<FlagDoc> = [] |
| 133 | |
| 134 | for (const arg of config.arguments) { |
| 135 | const singles = Param.extractSingleParams(arg) |
| 136 | const metadata = Param.getParamMetadata(arg) |
| 137 | for (const single of singles) { |
| 138 | args.push({ |
| 139 | name: single.name, |
| 140 | type: single.typeName ?? Primitive.getTypeName(single.primitiveType), |
| 141 | description: single.description, |
| 142 | required: !metadata.isOptional && |
| 143 | (!metadata.isVariadic || Option.exists(metadata.variadicMin, (min) => min > 0)), |
| 144 | variadic: metadata.isVariadic |
| 145 | }) |
| 146 | } |
| 147 | } |
| 148 | |
| 149 | let usage = commandPath.length > 0 ? commandPath.join(" ") : options.name |
| 150 | // Only render `<subcommand>` in usage when at least one visible subcommand |
| 151 | // exists; an all-unlisted subcommand tree should look like a leaf command. |
| 152 | if (subcommands.some((group) => group.commands.some((c) => !c.unlisted))) { |
| 153 | usage += " <subcommand>" |
| 154 | } |
| 155 | usage += " [flags]" |
| 156 | for (const arg of args) { |
| 157 | const argName = arg.variadic ? `<${arg.name}...>` : `<${arg.name}>` |
| 158 | usage += ` ${arg.required ? argName : `[${argName}]`}` |
| 159 | } |
| 160 | |
| 161 | for (const option of config.flags) { |
| 162 | const singles = Param.extractSingleParams(option) |
| 163 | const metadata = Param.getParamMetadata(option) |
| 164 | for (const single of singles) { |
| 165 | // Hidden flags still parse on the command line but are omitted from |
| 166 | // generated --help output. |
| 167 | if (single.hidden) continue |
| 168 | flags.push(toFlagDoc(single, metadata)) |
| 169 | } |
| 170 | } |
| 171 | |
| 172 | const subcommandDocs: Array<SubcommandGroupDoc> = [] |
| 173 | |
| 174 | for (const group of subcommands) { |
| 175 | // Unlisted subcommands still parse on the command line but are omitted |
| 176 | // from --help. Drop the whole group when nothing visible remains so we |
| 177 | // don't render an empty heading. |
| 178 | const visible = group.commands.filter((c) => !c.unlisted) |
| 179 | if (visible.length === 0) continue |
| 180 | subcommandDocs.push({ |
| 181 | group: group.group, |
| 182 | commands: Arr.map(visible as unknown as Arr.NonEmptyReadonlyArray<Command.Any>, (subcommand) => ({ |
| 183 | name: subcommand.name, |
| 184 | alias: subcommand.alias, |
| 185 | shortDescription: subcommand.shortDescription, |
| 186 | description: subcommand.description ?? "" |
| 187 | })) |