feat: command call mode on command context (#114)

Author: kazupon

src/cli.test.ts

@@ -17,6 +17,7 @@ describe('execute command', () => {
     const mockFn = vi.fn()
     await cli([], mockFn)
     expect(mockFn).toBeCalled()
+    expect(mockFn.mock.calls[0][0].callMode).toEqual('entry')
   })
 
   test('entry command', async () => {
@@ -25,6 +26,7 @@ describe('execute command', () => {
       run: mockFn
     })
     expect(mockFn).toBeCalled()
+    expect(mockFn.mock.calls[0][0].callMode).toEqual('entry')
   })
 
   test('entry command with name', async () => {
@@ -34,6 +36,7 @@ describe('execute command', () => {
       run: mockFn
     })
     expect(mockFn).toBeCalled()
+    expect(mockFn.mock.calls[0][0].callMode).toEqual('entry')
   })
 
   test('entry command with arguments', async () => {
@@ -49,6 +52,7 @@ describe('execute command', () => {
     })
     expect(mockFn.mock.calls[0][0].values).toEqual({ outDir: 'dist/' })
     expect(mockFn.mock.calls[0][0].positionals).toEqual(['foo', 'bar'])
+    expect(mockFn.mock.calls[0][0].callMode).toEqual('entry')
   })
 
   test('entry command without arguments', async () => {
@@ -58,6 +62,7 @@ describe('execute command', () => {
     })
     expect(mockFn.mock.calls[0][0].values).toEqual({})
     expect(mockFn.mock.calls[0][0].positionals).toEqual(['dist/', 'test/'])
+    expect(mockFn.mock.calls[0][0].callMode).toEqual('entry')
   })
 
   test('entry strictly command + sub commands', async () => {
@@ -99,12 +104,15 @@ describe('execute command', () => {
     await cli(['command2', '--bar=1', 'position2'], show, options)
 
     expect(mockShow).toBeCalledTimes(2)
+    expect(mockShow.mock.calls[0][0].callMode).toEqual('entry')
     expect(mockCommand1).toBeCalledTimes(1)
     expect(mockCommand1.mock.calls[0][0].values).toEqual({ foo: 'foo' })
     expect(mockCommand1.mock.calls[0][0].positionals).toEqual(['command1', 'position1'])
+    expect(mockCommand1.mock.calls[0][0].callMode).toEqual('subCommand')
     expect(mockCommand2).toBeCalledTimes(1)
     expect(mockCommand2.mock.calls[0][0].values).toEqual({ bar: 1 })
     expect(mockCommand2.mock.calls[0][0].positionals).toEqual(['command2', 'position2'])
+    expect(mockCommand2.mock.calls[0][0].callMode).toEqual('subCommand')
   })
 
   test('entry loose command + sub commands', async () => {

src/cli.ts

@@ -10,7 +10,13 @@ import { renderHeader, renderUsage, renderValidationErrors } from './renderer.ts
 import { create, resolveLazyCommand } from './utils.ts'
 
 import type { Args, ArgToken } from 'args-tokens'
-import type { Command, CommandContext, CommandOptions, CommandRunner } from './types.ts'
+import type {
+  Command,
+  CommandCallMode,
+  CommandContext,
+  CommandOptions,
+  CommandRunner
+} from './types.ts'
 
 /**
  * Run the command.
@@ -28,7 +34,12 @@ export async function cli<A extends Args = Args>(
 
   const subCommand = getSubCommand(tokens)
   const resolvedCommandOptions = resolveCommandOptions(opts, entry)
-  const [name, command] = await resolveCommand(subCommand, entry, resolvedCommandOptions, true)
+  const [name, command, callMode] = await resolveCommand(
+    subCommand,
+    entry,
+    resolvedCommandOptions,
+    true
+  )
   if (!command) {
     throw new Error(`Command not found: ${name || ''}`)
   }
@@ -48,6 +59,7 @@ export async function cli<A extends Args = Args>(
     argv,
     tokens,
     omitted,
+    callMode,
     command,
     commandOptions: resolvedCommandOptions
   })
@@ -161,27 +173,31 @@ async function resolveCommand<A extends Args>(
   entry: Command<A> | CommandRunner<A>,
   options: CommandOptions<A>,
   needRunResolving: boolean = false
-): Promise<[string | undefined, Command<A> | undefined]> {
+): Promise<[string | undefined, Command<A> | undefined, CommandCallMode]> {
   const omitted = !sub
   if (typeof entry === 'function') {
-    return [undefined, { run: entry }]
+    return [undefined, { run: entry }, 'entry']
   } else {
     if (omitted) {
       return typeof entry === 'object'
-        ? [resolveEntryName(entry), await resolveLazyCommand(entry, '', needRunResolving)]
-        : [undefined, undefined]
+        ? [resolveEntryName(entry), await resolveLazyCommand(entry, '', needRunResolving), 'entry']
+        : [undefined, undefined, 'unexpected']
     } else {
       if (options.subCommands == null || options.subCommands.size === 0) {
-        return [resolveEntryName(entry), await resolveLazyCommand(entry, '', needRunResolving)]
+        return [
+          resolveEntryName(entry),
+          await resolveLazyCommand(entry, '', needRunResolving),
+          'entry'
+        ]
       }
 
       const cmd = options.subCommands?.get(sub)
 
       if (cmd == null) {
-        return [sub, undefined]
+        return [sub, undefined, 'unexpected']
       }
 
-      return [sub, await resolveLazyCommand(cmd, sub, needRunResolving)]
+      return [sub, await resolveLazyCommand(cmd, sub, needRunResolving), 'subCommand']
     }
   }
 }

src/context.test.ts

@@ -61,6 +61,7 @@ test('basic', async () => {
     argv: ['bar'],
     tokens: [], // dummy, due to test
     omitted: true,
+    callMode: 'entry',
     command,
     commandOptions: {
       cwd: '/path/to/cmd1',
@@ -152,6 +153,7 @@ test('default', async () => {
     tokens: [], // dummy, due to test
     command,
     omitted: false,
+    callMode: 'entry',
     commandOptions: {}
   })
 
@@ -198,6 +200,7 @@ describe('translation', () => {
       tokens: [], // dummy, due to test
       command,
       omitted: false,
+      callMode: 'entry',
       commandOptions: {}
     })
 
@@ -258,6 +261,7 @@ describe('translation', () => {
       tokens: [], // dummy, due to test
       command,
       omitted: false,
+      callMode: 'entry',
       commandOptions: {}
     })
 
@@ -332,6 +336,7 @@ describe('translation', () => {
       tokens: [], // dummy, due to test
       command,
       omitted: false,
+      callMode: 'entry',
       commandOptions: {
         description: 'this is cmd1',
         locale: new Intl.Locale(loadLocale)
@@ -403,6 +408,7 @@ describe('translation adapter', () => {
       tokens: [], // dummy, due to test
       command,
       omitted: false,
+      callMode: 'entry',
       commandOptions: {
         description: 'this is cmd1',
         locale: new Intl.Locale(loadLocale),
@@ -459,6 +465,7 @@ describe('translation adapter', () => {
       tokens: [], // dummy, due to test
       command,
       omitted: false,
+      callMode: 'entry',
       commandOptions: {
         description: 'this is cmd1',
         locale: new Intl.Locale(loadLocale),

src/context.ts

@@ -32,6 +32,7 @@ import type { Args, ArgSchema, ArgToken, ArgValues } from 'args-tokens'
 import type {
   Command,
   CommandBuiltinKeys,
+  CommandCallMode,
   CommandContext,
   CommandEnvironment,
   CommandOptions,
@@ -72,6 +73,10 @@ interface CommandContextParams<A extends Args, V> {
    * Whether the command is omitted
    */
   omitted: boolean
+  /**
+   * Command call mode.
+   */
+  callMode: CommandCallMode
   /**
    * A target {@link Command | command}
    */
@@ -99,6 +104,7 @@ export async function createCommandContext<
   tokens,
   command,
   commandOptions,
+  callMode = 'entry',
   omitted = false
 }: CommandContextParams<A, V>): Promise<Readonly<CommandContext<A, V>>> {
   /**
@@ -200,6 +206,7 @@ export async function createCommandContext<
       name: command.name,
       description: command.description,
       omitted,
+      callMode,
       locale,
       env,
       args: _args,

src/renderer.test.ts

@@ -97,6 +97,7 @@ describe('renderHeader', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: true,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -118,6 +119,7 @@ describe('renderHeader', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: true,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -138,6 +140,7 @@ describe('renderHeader', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: true,
+      callMode: 'entry',
       command,
       commandOptions: { cwd: '/path/to/cmd1' }
     })
@@ -154,6 +157,7 @@ describe('renderHeader', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: true,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -205,6 +209,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -233,6 +238,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -275,6 +281,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -311,6 +318,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -357,6 +365,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -405,6 +414,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         cwd: '/path/to/cmd1',
@@ -454,6 +464,7 @@ describe('renderUsage', () => {
       argv: [],
       tokens: [], // dummy, due to test
       omitted: false,
+      callMode: 'entry',
       command,
       commandOptions: {
         usageOptionType: true,
@@ -473,6 +484,7 @@ describe('renderUsage', () => {
       args: SHOW.args!,
       values: {},
       omitted: true,
+      callMode: 'entry',
       positionals: [],
       rest: [],
       argv: [],
@@ -499,6 +511,7 @@ test('renderValidationErrors', async () => {
     argv: [],
     tokens: [], // dummy, due to test
     omitted: false,
+    callMode: 'entry',
     command: SHOW,
     commandOptions: {
       cwd: '/path/to/cmd1',

src/types.ts

@@ -221,6 +221,11 @@ export interface CommandOptions<A extends Args = Args> {
   translationAdapterFactory?: TranslationAdapterFactory
 }
 
+/**
+ * Command call mode.
+ */
+export type CommandCallMode = 'entry' | 'subCommand' | 'unexpected'
+
 /**
  * Command context.
  * Command context is the context of the command execution.
@@ -277,6 +282,11 @@ export interface CommandContext<A extends Args = Args, V = ArgValues<A>> {
    * Whether the currently executing command has been executed with the sub-command name omitted.
    */
   omitted: boolean
+  /**
+   * Command call mode.
+   * The command call mode is `entry` when the command is executed as an entry command, and `subCommand` when the command is executed as a sub-command.
+   */
+  callMode: CommandCallMode
   /**
    * Output a message.
    * If {@link CommandEnvironment.usageSilent} is true, the message is not output.