66 */
77
88import { join } from 'node:path' ;
9- import { asString , Dictionary , ensureObject , ensureString } from '@salesforce/ts-types' ;
9+ import { asString , Dictionary , ensureObject , ensureString , Optional } from '@salesforce/ts-types' ;
1010import { CommandClass , CommandData , CommandParameterData , punctuate , replaceConfigVariables } from '../utils.js' ;
1111import { Ditamap } from './ditamap.js' ;
1212
@@ -21,14 +21,18 @@ type FlagInfo = {
2121 default : string | ( ( ) => Promise < string > ) ;
2222} ;
2323
24- const getDefault = async ( flag ? : FlagInfo ) : Promise < string > => {
24+ const getDefault = async ( flag : FlagInfo , flagName : string ) : Promise < string > => {
2525 if ( ! flag ) {
2626 return '' ;
2727 }
28+ if ( flagName === 'target-org' || flagName === 'target-dev-hub' ) {
29+ // special handling to prevent global/local default usernames from appearing in the docs, but they do appear in user's help
30+ return '' ;
31+ }
2832 if ( typeof flag . default === 'function' ) {
2933 try {
3034 const help = await flag . default ( ) ;
31- return help || '' ;
35+ return help . includes ( '[object Object]' ) ? '' : help ?? '' ;
3236 } catch {
3337 return '' ;
3438 }
@@ -50,23 +54,23 @@ export class Command extends Ditamap {
5054 ) {
5155 const commandWithUnderscores = ensureString ( command . id ) . replace ( / : / g, '_' ) ;
5256 const filename = Ditamap . file ( `cli_reference_${ commandWithUnderscores } , 'xml' ) ;
53-
5457 super ( filename , undefined ) ;
5558
5659 this . flags = ensureObject ( command . flags ) ;
5760 this . commandMeta = commandMeta ;
61+ const binary = readBinary ( this . commandMeta ) ;
5862
5963 const summary = punctuate ( command . summary ) ;
6064 this . commandName = command . id . replace ( / : / g, asString ( this . commandMeta . topicSeparator , ':' ) ) ;
6165
6266 const description = command . description
63- ? replaceConfigVariables ( command . description , asString ( this . commandMeta . binary , 'unknown' ) , this . commandName )
67+ ? replaceConfigVariables ( command . description , binary , this . commandName )
6468 : undefined ;
6569
6670 // Help are all the lines after the first line in the description. Before oclif, there was a 'help' property so continue to
6771 // support that.
6872
69- const help = this . formatParagraphs ( description ) ;
73+ const help = formatParagraphs ( description ) ;
7074
7175 let trailblazerCommunityUrl : string | undefined ;
7276 let trailblazerCommunityName : string | undefined ;
@@ -90,10 +94,8 @@ export class Command extends Ditamap {
9094 }
9195
9296 return {
93- description : replaceConfigVariables ( desc ?? '' , asString ( this . commandMeta . binary , 'unknown' ) , this . commandName ) ,
94- commands : commands . map ( ( cmd ) =>
95- replaceConfigVariables ( cmd , asString ( this . commandMeta . binary , 'unknown' ) , this . commandName )
96- ) ,
97+ description : replaceConfigVariables ( desc ?? '' , binary , this . commandName ) ,
98+ commands : commands . map ( ( cmd ) => replaceConfigVariables ( cmd , binary , this . commandName ) ) ,
9799 } ;
98100 } ) ;
99101
@@ -102,7 +104,7 @@ export class Command extends Ditamap {
102104 name : this . commandName ,
103105 summary,
104106 description,
105- binary : 'binary' in commandMeta && typeof commandMeta . binary === 'string' ? commandMeta . binary : 'unknown' ,
107+ binary,
106108 commandWithUnderscores,
107109 deprecated : ( command . deprecated as boolean ) ?? state === 'deprecated' ?? false ,
108110 examples,
@@ -120,34 +122,24 @@ export class Command extends Ditamap {
120122 }
121123
122124 public async getParametersForTemplate ( flags : Dictionary < FlagInfo > ) : Promise < CommandParameterData [ ] > {
123- const final : CommandParameterData [ ] = [ ] ;
124-
125- for ( const [ flagName , flag ] of Object . entries ( flags ) ) {
126- if ( ! flag || flag . hidden ) continue ;
127- const description = replaceConfigVariables (
128- Array . isArray ( flag ?. description ) ? flag ?. description . join ( '\n' ) : flag ?. description ?? '' ,
129- asString ( this . commandMeta . binary , 'unknown' ) ,
130- this . commandName
131- ) ;
132- const entireDescription = flag . summary
133- ? `${ replaceConfigVariables (
134- flag . summary ,
135- asString ( this . commandMeta . binary , 'unknown' ) ,
136- this . commandName
137- ) } \n${ description }
138- : description ;
139- const updated = Object . assign ( { } , flag , {
140- name : flagName ,
141- description : this . formatParagraphs ( entireDescription ) ,
142- optional : ! flag ?. required ,
143- kind : flag ?. kind ?? flag ?. type ,
144- hasValue : flag ?. type !== 'boolean' ,
145- // eslint-disable-next-line no-await-in-loop
146- defaultFlagValue : await getDefault ( flag ) ,
147- } ) ;
148- final . push ( updated ) ;
149- }
150- return final ;
125+ const descriptionBuilder = buildDescription ( this . commandName ) ( readBinary ( this . commandMeta ) ) ;
126+ return Promise . all (
127+ [ ...Object . entries ( flags ) ]
128+ . filter ( flagIsDefined )
129+ . filter ( ( [ , flag ] ) => ! flag . hidden )
130+ . map (
131+ async ( [ flagName , flag ] ) =>
132+ ( {
133+ ...flag ,
134+ name : flagName ,
135+ description : descriptionBuilder ( flag ) ,
136+ optional : ! flag . required ,
137+ kind : flag . kind ?? flag . type ,
138+ hasValue : flag . type !== 'boolean' ,
139+ defaultFlagValue : await getDefault ( flag , flagName ) ,
140+ } satisfies CommandParameterData )
141+ )
142+ ) ;
151143 }
152144
153145 // eslint-disable-next-line class-methods-use-this
@@ -161,3 +153,25 @@ export class Command extends Ditamap {
161153 return super . transformToDitamap ( ) ;
162154 }
163155}
156+
157+ const flagIsDefined = ( input : [ string , Optional < FlagInfo > ] ) : input is [ string , FlagInfo ] => input [ 1 ] !== undefined ;
158+
159+ const buildDescription =
160+ ( commandName : string ) =>
161+ ( binary : string ) =>
162+ ( flag : FlagInfo ) : string [ ] => {
163+ const description = replaceConfigVariables (
164+ Array . isArray ( flag ?. description ) ? flag ?. description . join ( '\n' ) : flag ?. description ?? '' ,
165+ binary ,
166+ commandName
167+ ) ;
168+ return formatParagraphs (
169+ flag . summary ? `${ replaceConfigVariables ( flag . summary , binary , commandName ) } ${ description } : description
170+ ) ;
171+ } ;
172+
173+ const formatParagraphs = ( textToFormat ?: string ) : string [ ] =>
174+ textToFormat ? textToFormat . split ( '\n' ) . filter ( ( n ) => n !== '' ) : [ ] ;
175+
176+ const readBinary = ( commandMeta : Record < string , unknown > ) : string =>
177+ 'binary' in commandMeta && typeof commandMeta . binary === 'string' ? commandMeta . binary : 'unknown' ;
0 commit comments