feat: support complex flag relationships

src/config/config.ts

@@ -768,6 +768,7 @@ export async function toCached(c: Command.Class, plugin?: IPlugin): Promise<Comm
         multiple: flag.multiple,
         options: flag.options,
         dependsOn: flag.dependsOn,
+        relationships: flag.relationships,
         exclusive: flag.exclusive,
         default: await defaultToCached(flag),
       }

src/interfaces/parser.ts

@@ -86,6 +86,12 @@ export type DefaultContext<T> = {
 export type Default<T> = T | ((context: DefaultContext<T>) => Promise<T>)
 export type DefaultHelp<T> = T | ((context: DefaultContext<T>) => Promise<string | undefined>)
 
+export type FlagRelationship = string | {name: string; when: (flags: Record<string, unknown>) => Promise<boolean>};
+export type Relationship = {
+  type: 'all' | 'some' | 'none';
+  flags: FlagRelationship[];
+}
+
 export type FlagProps = {
   name: string;
   char?: AlphabetLowercase | AlphabetUppercase;
@@ -112,6 +118,7 @@ export type FlagProps = {
   hidden?: boolean;
   required?: boolean;
   dependsOn?: string[];
+  relationships?: Relationship[];
   exclusive?: string[];
 }
 

src/parser/index.ts

@@ -27,7 +27,7 @@ export async function parse<TFlags, GFlags, TArgs extends { [name: string]: stri
   }
   const parser = new Parser(input)
   const output = await parser.parse()
-  m.validate({input, output})
+  await m.validate({input, output})
   return output as ParserOutput<TFlags, GFlags, TArgs>
 }
 

src/parser/validate.ts

@@ -1,3 +1,4 @@
+/* eslint-disable no-await-in-loop */
 import {CLIError} from '../errors'
 
 import {
@@ -6,9 +7,10 @@ import {
   RequiredFlagError,
   UnexpectedArgsError,
 } from './errors'
-import {ParserArg, ParserInput, ParserOutput, Flag} from '../interfaces'
+import {ParserArg, ParserInput, ParserOutput, Flag, CompletableFlag} from '../interfaces'
+import {FlagRelationship} from '../interfaces/parser'
 
-export function validate(parse: {
+export async function validate(parse: {
   input: ParserInput;
   output: ParserOutput;
 }) {
@@ -54,43 +56,13 @@ export function validate(parse: {
     }
   }
 
-  function validateFlags() {
+  async function validateFlags() {
     for (const [name, flag] of Object.entries(parse.input.flags)) {
       if (parse.output.flags[name] !== undefined) {
-        for (const also of flag.dependsOn || []) {
-          if (!parse.output.flags[also]) {
-            throw new CLIError(
-              `--${also}= must also be provided when using --${name}=`,
-            )
-          }
-        }
-
-        for (const also of flag.exclusive || []) {
-          // do not enforce exclusivity for flags that were defaulted
-          if (
-            parse.output.metadata.flags[also] &&
-            parse.output.metadata.flags[also].setFromDefault
-          )
-            continue
-          if (
-            parse.output.metadata.flags[name] &&
-            parse.output.metadata.flags[name].setFromDefault
-          )
-            continue
-          if (parse.output.flags[also]) {
-            throw new CLIError(
-              `--${also}= cannot also be provided when using --${name}=`,
-            )
-          }
-        }
-
-        for (const also of flag.exactlyOne || []) {
-          if (also !== name && parse.output.flags[also]) {
-            throw new CLIError(
-              `--${also}= cannot also be provided when using --${name}=`,
-            )
-          }
-        }
+        await validateRelationships(name, flag)
+        await validateDependsOn(name, flag.dependsOn ?? [])
+        await validateExclusive(name, flag.exclusive ?? [])
+        validateExactlyOne(name, flag.exactlyOne ?? [])
       } else if (flag.required) {
         throw new RequiredFlagError({parse, flag})
       } else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
@@ -99,6 +71,96 @@ export function validate(parse: {
     }
   }
 
+  async function resolveFlags(flags: FlagRelationship[]): Promise<Record<string, unknown>> {
+    const promises = flags.map(async flag => {
+      if (typeof flag === 'string') {
+        return [flag, parse.output.flags[flag]]
+      }
+
+      const result = await flag.when(parse.output.flags)
+      return result ? [flag.name, parse.output.flags[flag.name]] : null
+    })
+    const resolved = await Promise.all(promises)
+    return Object.fromEntries(resolved.filter(r => r !== null) as [string, unknown][])
+  }
+
+  async function validateExclusive(name: string, flags: FlagRelationship[]) {
+    const resolved = await resolveFlags(flags)
+    const keys = Object.keys(resolved).reduce((acc, key) => {
+      if (resolved[key]) acc.push(key)
+      return acc
+    }, [] as string[])
+
+    for (const flag of keys) {
+      // do not enforce exclusivity for flags that were defaulted
+      if (
+        parse.output.metadata.flags[flag] &&
+        parse.output.metadata.flags[flag].setFromDefault
+      )
+        continue
+      if (
+        parse.output.metadata.flags[name] &&
+        parse.output.metadata.flags[name].setFromDefault
+      )
+        continue
+      if (parse.output.flags[flag]) {
+        throw new CLIError(
+          `--${flag}=${parse.output.flags[flag]} cannot also be provided when using --${name}`,
+        )
+      }
+    }
+  }
+
+  function validateExactlyOne(name: string, exactlyOne: FlagRelationship[]) {
+    for (const flag of exactlyOne || []) {
+      const flagName = typeof flag === 'string' ? flag : flag.name
+      if (flagName !== name && parse.output.flags[flagName]) {
+        throw new CLIError(
+          `--${flagName} cannot also be provided when using --${name}`,
+        )
+      }
+    }
+  }
+
+  async function validateDependsOn(name: string, flags: FlagRelationship[]) {
+    const resolved = await resolveFlags(flags)
+    const foundAll = Object.values(resolved).every(Boolean)
+    if (!foundAll) {
+      const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ')
+      throw new CLIError(
+        `All of the following must be provided when using --${name}: ${formattedFlags}`,
+      )
+    }
+  }
+
+  async function validateSome(name: string, flags: FlagRelationship[]) {
+    const resolved = await resolveFlags(flags)
+    const foundAtLeastOne = Object.values(resolved).some(Boolean)
+    if (!foundAtLeastOne) {
+      const formattedFlags = Object.keys(resolved).map(f => `--${f}`).join(', ')
+      throw new CLIError(`One of the following must be provided when using --${name}: ${formattedFlags}`)
+    }
+  }
+
+  async function validateRelationships(name: string, flag: CompletableFlag<any>) {
+    if (!flag.relationships) return
+    for (const relationship of flag.relationships) {
+      const flags = relationship.flags ?? []
+
+      if (relationship.type === 'all') {
+        await validateDependsOn(name, flags)
+      }
+
+      if (relationship.type === 'some') {
+        await validateSome(name, flags)
+      }
+
+      if (relationship.type === 'none') {
+        await validateExclusive(name, flags)
+      }
+    }
+  }
+
   validateArgs()
-  validateFlags()
+  await validateFlags()
 }

test/parser/parse.test.ts

@@ -903,7 +903,7 @@ See more help with --help`)
         message = error.message
       }
 
-      expect(message).to.equal('--bar= must also be provided when using --foo=')
+      expect(message).to.equal('All of the following must be provided when using --foo: --bar')
     })
   })
 
@@ -940,7 +940,7 @@ See more help with --help`)
         message = error.message
       }
 
-      expect(message).to.equal('--bar= cannot also be provided when using --foo=')
+      expect(message).to.equal('--bar=b cannot also be provided when using --foo')
     })
   })
 
@@ -974,7 +974,7 @@ See more help with --help`)
         message = error.message
       }
 
-      expect(message).to.equal('--bar= cannot also be provided when using --foo=')
+      expect(message).to.equal('--bar cannot also be provided when using --foo')
     })
 
     it('succeeds if exactly one', async () => {
@@ -1035,7 +1035,7 @@ See more help with --help`)
         message = error.message
       }
 
-      expect(message).to.equal('--else= cannot also be provided when using --foo=')
+      expect(message).to.equal('--else cannot also be provided when using --foo')
     })
 
     it('handles cross-references/pairings that don\'t make sense', async () => {
@@ -1053,7 +1053,7 @@ See more help with --help`)
         message1 = error.message
       }
 
-      expect(message1).to.equal('--bar= cannot also be provided when using --foo=')
+      expect(message1).to.equal('--bar cannot also be provided when using --foo')
 
       let message2 = ''
       try {
@@ -1064,7 +1064,7 @@ See more help with --help`)
         message2 = error.message
       }
 
-      expect(message2).to.equal('--else= cannot also be provided when using --bar=')
+      expect(message2).to.equal('--else cannot also be provided when using --bar')
 
       const out = await parse(['--foo', 'a', '--else', '4'], {
         flags: crazyFlags,