feat: support complex flag relationships

src/config/config.ts

@@ -751,6 +751,7 @@ export async function toCached(c: Command.Class, plugin?: IPlugin): Promise<Comm
         helpGroup: flag.helpGroup,
         allowNo: flag.allowNo,
         dependsOn: flag.dependsOn,
+        relationships: flag.relationships,
         exclusive: flag.exclusive,
       }
     } else {
@@ -768,6 +769,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

@@ -112,6 +112,16 @@ export type FlagProps = {
   hidden?: boolean;
   required?: boolean;
   dependsOn?: string[];
+  relationships?: {
+    dependsOn?: {
+      type: 'all' | 'atLeastOne';
+      flags: string[];
+    };
+    exclusive?: {
+      type: 'all' | 'atLeastOne';
+      flags: string[];
+    }
+  };
   exclusive?: string[];
 }
 

src/parser/validate.ts

@@ -6,7 +6,7 @@ import {
   RequiredFlagError,
   UnexpectedArgsError,
 } from './errors'
-import {ParserArg, ParserInput, ParserOutput, Flag} from '../interfaces'
+import {ParserArg, ParserInput, ParserOutput, Flag, CompletableFlag} from '../interfaces'
 
 export function validate(parse: {
   input: ParserInput;
@@ -57,44 +57,104 @@ export function validate(parse: {
   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}=`,
-            )
+        validateRelationships(name, flag)
+        validateDependsOn(name, flag.dependsOn ?? [])
+        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) {
+        validateAcrossFlags(flag)
+      }
+    }
+  }
+
+  function validateExclusive(name: string, exclusive: string[]) {
+    for (const also of 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}=`,
+        )
+      }
+    }
+  }
+
+  function validateExactlyOne(name: string, exactlyOne: string[]) {
+    for (const also of exactlyOne || []) {
+      if (also !== name && parse.output.flags[also]) {
+        throw new CLIError(
+          `--${also}= cannot also be provided when using --${name}=`,
+        )
+      }
+    }
+  }
+
+  function validateDependsOn(name: string, dependsOn: string[]) {
+    for (const also of dependsOn || []) {
+      if (!parse.output.flags[also]) {
+        throw new CLIError(
+          `--${also}= must also be provided when using --${name}=`,
+        )
+      }
+    }
+  }
+
+  function validateRelationships(name: string, flag: CompletableFlag<any>) {
+    if (!flag.relationships) return
+
+    if (flag.relationships?.dependsOn) {
+      const dependsOnFlags = flag.relationships.dependsOn.flags ?? []
+      if (flag.relationships?.dependsOn.type === 'all') {
+        validateDependsOn(name, dependsOnFlags)
+      }
+
+      if (flag.relationships.dependsOn.type === 'atLeastOne') {
+        let foundAtLeastOne = false
+        for (const flag of dependsOnFlags) {
+          if (parse.output.flags[flag]) {
+            foundAtLeastOne = true
+            break
           }
         }
 
-        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}=`,
-            )
-          }
+        if (!foundAtLeastOne) {
+          const flags = (dependsOnFlags ?? []).map(f => `--${f}`).join(', ')
+          throw new CLIError(`One of the following must be provided when using --${name}: ${flags}`)
         }
+      }
+    }
+
+    if (flag.relationships?.exclusive) {
+      const exclusiveFlags = flag.relationships.exclusive.flags ?? []
 
-        for (const also of flag.exactlyOne || []) {
-          if (also !== name && parse.output.flags[also]) {
-            throw new CLIError(
-              `--${also}= cannot also be provided when using --${name}=`,
-            )
+      if (flag.relationships.exclusive.type === 'all') {
+        validateExclusive(name, exclusiveFlags)
+      }
+
+      if (flag.relationships.exclusive.type === 'atLeastOne') {
+        let foundAtLeastOne = false
+        for (const flag of exclusiveFlags) {
+          if (parse.output.flags[flag]) {
+            foundAtLeastOne = true
+            break
           }
         }
-      } else if (flag.required) {
-        throw new RequiredFlagError({parse, flag})
-      } else if (flag.exactlyOne && flag.exactlyOne.length > 0) {
-        validateAcrossFlags(flag)
+
+        if (!foundAtLeastOne) {
+          const flags = (exclusiveFlags ?? []).map(f => `--${f}`).join(', ')
+          throw new CLIError(`The following cannot be provided when using --${name}: ${flags}`)
+        }
       }
     }
   }