@flowscripter/dynamic-cli-framework 1.0.0

package/src/runtime/parser.ts

@@ -0,0 +1,219 @@
+import type Command from "../api/command/Command.ts";
+import type GroupCommand from "../api/command/GroupCommand.ts";
+import type {
+  ArgumentValueType,
+  PopulatedArgumentSingleValueType,
+  PopulatedArgumentValues,
+} from "../api/argument/ArgumentValueTypes.ts";
+import type { InvalidArgument } from "../api/RunResult.ts";
+import type { CommandClause } from "./scanner.ts";
+import populateGlobalCommandValue from "./values/globalCommandValuePopulation.ts";
+import {
+  validateGlobalCommandArgumentValue,
+  validateOptionValue,
+  validatePositionalValue,
+} from "./values/argumentValueValidation.ts";
+import getLogger from "../util/logger.ts";
+import populateSubCommandValues from "./values/subCommandValuePopulation.ts";
+import type GlobalCommand from "../api/command/GlobalCommand.ts";
+import type SubCommand from "../api/command/SubCommand.ts";
+
+const logger = getLogger("parser");
+
+/**
+ * A container holding the result of a {@link CommandClause} parsing operation.
+ */
+export interface ParseResult {
+  /**
+   * The {@link Command} to execute if the parse result is valid (i.e. {@link invalidArguments} is empty).
+   */
+  readonly command: Command;
+
+  /**
+   * Optional parent {@link GroupCommand} if the parsed {@link command} was a member {@link SubCommand},
+   */
+  readonly groupCommand?: GroupCommand;
+
+  /**
+   * The argument values populated from the command line args. If the parse result is valid
+   * (i.e. {@link invalidArguments} is empty), this can be used to execute the specified {@link command}.
+   * {@link PopulatedArgumentSingleValueType} is for {@link GlobalCommand} values, {@link PopulatedArgumentValues} is for
+   * {@link SubCommand} values.
+   */
+  readonly populatedArgumentValues:
+    | PopulatedArgumentValues
+    | PopulatedArgumentSingleValueType;
+
+  /**
+   * Any arguments which were invalid.
+   */
+  readonly invalidArguments: ReadonlyArray<InvalidArgument>;
+
+  /**
+   * Any arguments which were unused in the parsing operation.
+   */
+  readonly unusedArgs: ReadonlyArray<string>;
+}
+
+/**
+ * Parse the arguments for the specified {@link CommandClause} assuming it contains a {@link SubCommand}.
+ *
+ * @param commandClause the clause to parse.
+ * @param defaultValues optional default {@link PopulatedArgumentValues} to use for population before parsing the provided arguments.
+ */
+export function parseSubCommandClause(
+  commandClause: CommandClause,
+  defaultValues?: PopulatedArgumentValues,
+): ParseResult {
+  const command = commandClause.command as SubCommand;
+  const potentialArgs = commandClause.potentialArgs;
+  const groupCommand = commandClause.groupCommand;
+
+  const invalidArguments: Array<InvalidArgument> = [];
+
+  // check if we need to process any arguments at all
+  if ((command.options.length === 0) && (command.positionals.length === 0)) {
+    return {
+      command,
+      groupCommand,
+      populatedArgumentValues: {},
+      invalidArguments,
+      unusedArgs: potentialArgs,
+    };
+  }
+
+  const { populatedArgumentValues, unusedArgs, invalidArgument } =
+    populateSubCommandValues(
+      command,
+      potentialArgs,
+      defaultValues,
+    );
+
+  if (invalidArgument) {
+    invalidArguments.push(invalidArgument);
+  }
+
+  if (invalidArguments.length === 0) {
+    // validate the option values
+    command.options.forEach((option) => {
+      const validatedValue = validateOptionValue(
+        option,
+        populatedArgumentValues[option.name] || option.defaultValue,
+        invalidArguments,
+      );
+      if (validatedValue !== undefined) {
+        populatedArgumentValues[option.name] = validatedValue;
+      }
+    });
+
+    logger.debug(
+      "Command arguments after options validated: %j with invalid args: %j",
+      populatedArgumentValues,
+      invalidArguments,
+    );
+
+    if (invalidArguments.length === 0) {
+      // validate the positional values
+      command.positionals.forEach((positional) => {
+        const validatedValue = validatePositionalValue(
+          positional,
+          populatedArgumentValues[positional.name] as ArgumentValueType,
+          invalidArguments,
+        );
+        if (validatedValue !== undefined) {
+          populatedArgumentValues[positional.name] = validatedValue;
+        }
+      });
+      logger.debug(
+        "Command arguments after positionals validated: %j with invalid args: %j",
+        populatedArgumentValues,
+        invalidArguments,
+      );
+    }
+  }
+  if (groupCommand) {
+    return {
+      command,
+      populatedArgumentValues,
+      groupCommand,
+      invalidArguments,
+      unusedArgs,
+    };
+  }
+  return {
+    command,
+    populatedArgumentValues,
+    invalidArguments,
+    unusedArgs: unusedArgs,
+  };
+}
+
+/**
+ * Parse the arguments for the specified {@link CommandClause} assuming it contains a {@link GlobalCommand} or {@link GlobalModifierCommand}.
+ *
+ * @param commandClause the clause to parse.
+ * @param defaultValue optional default {@link PopulatedArgumentSingleValueType} to use for population before parsing the provided arguments.
+ */
+export function parseGlobalCommandClause(
+  commandClause: CommandClause,
+  defaultValue?: PopulatedArgumentSingleValueType,
+): ParseResult {
+  const command = commandClause.command as GlobalCommand;
+  const potentialArgs = commandClause.potentialArgs;
+  const invalidArguments: Array<InvalidArgument> = [];
+
+  // check if we need to process an argument at all
+  if (!command.argument) {
+    return {
+      command,
+      populatedArgumentValues: undefined,
+      invalidArguments,
+      unusedArgs: potentialArgs,
+    };
+  }
+
+  let { populatedArgumentValue, unusedArgs, invalidArgument } =
+    populateGlobalCommandValue(
+      command,
+      potentialArgs,
+      defaultValue,
+    );
+
+  if (invalidArgument) {
+    invalidArguments.push(invalidArgument);
+  }
+
+  logger.debug(
+    "Command arguments for command: %s after value population: %j with invalid args: %j and unused args: %j",
+    command.name,
+    populatedArgumentValue,
+    invalidArguments,
+    unusedArgs,
+  );
+
+  // don't validate the value if the argument is already invalid
+  if (invalidArguments.length === 0) {
+    const validatedValue = validateGlobalCommandArgumentValue(
+      command,
+      populatedArgumentValue,
+      invalidArguments,
+    );
+    if (validatedValue !== undefined) {
+      populatedArgumentValue = validatedValue;
+    }
+  }
+
+  logger.debug(
+    "Command arguments for command: %s after value validation: %j with invalid args: %j",
+    command.name,
+    populatedArgumentValue,
+    invalidArguments,
+  );
+
+  return {
+    command,
+    populatedArgumentValues: populatedArgumentValue,
+    invalidArguments,
+    unusedArgs,
+  };
+}

package/src/runtime/registry/CommandRegistry.ts

@@ -0,0 +1,121 @@
+import type GroupCommand from "../../api/command/GroupCommand.ts";
+import type SubCommand from "../../api/command/SubCommand.ts";
+import type GlobalCommand from "../../api/command/GlobalCommand.ts";
+import type GlobalModifierCommand from "../../api/command/GlobalModifierCommand.ts";
+import type Command from "../../api/command/Command.ts";
+
+/**
+ * Interface used by a {@link CLI} to register {@link Command} instances.
+ */
+export default interface CommandRegistry {
+  /**
+   * Get all registered {@link SubCommand} instances.
+   */
+  getSubCommands(): ReadonlyArray<SubCommand>;
+
+  /**
+   * Get all registered {@link GroupCommand} instances.
+   */
+  getGroupCommands(): ReadonlyArray<GroupCommand>;
+
+  /**
+   * Get all registered {@link GlobalCommand} instances.
+   */
+  getGlobalCommands(): ReadonlyArray<GlobalCommand>;
+
+  /**
+   * Get all registered {@link GlobalModifierCommand} instances.
+   */
+  getGlobalModifierCommands(): ReadonlyArray<GlobalModifierCommand>;
+
+  /**
+   * Get a registered {@link SubCommand} by name.
+   */
+  getSubCommandByName(name: string): SubCommand | undefined;
+
+  /**
+   * Get a registered {@link GroupCommand} by name.
+   */
+  getGroupCommandByName(name: string): GroupCommand | undefined;
+
+  /**
+   * Get a registered {@link GroupCommand} and member {@link SubCommand} by
+   * combined name e.g. `<group-command-name>:<member-sub-command-name>`.
+   */
+  getGroupCommandAndMemberSubCommandByJoinedName(
+    getGroupCommandAndMemberSubCommandByName: string,
+  ): { groupCommand: GroupCommand; command: SubCommand } | undefined;
+
+  /**
+   * Get a registered {@link GlobalCommand} by name.
+   */
+  getGlobalCommandByName(name: string): GlobalCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalCommand} by short alias.
+   */
+  // getGlobalCommandByShortAlias(shortAlias: string): GlobalCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalModifierCommand} by name.
+   */
+  getGlobalModifierCommandByName(
+    name: string,
+  ): GlobalModifierCommand | undefined;
+
+  /**
+   * Get a registered {@link GlobalModifierCommand} by short alias.
+   */
+  // getGlobalModifierCommandByShortAlias(
+  //   shortAlias: string,
+  // ): GlobalModifierCommand | undefined;
+
+  /**
+   * Get a map of all registered {@link GroupCommand} and member {@link SubCommand} instance combinations by
+   * combined name e.g. `<group-command-name>:<member-sub-command-name>`.
+   */
+  getGroupAndMemberCommandsByJoinedName(): ReadonlyMap<
+    string,
+    { groupCommand: GroupCommand; command: SubCommand }
+  >;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by name provided by the specified service.
+   */
+  getGlobalModifierCommandsByNameProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand>;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by short alias provided by the specified service.
+   */
+  getGlobalModifierCommandsByShortAliasProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand>;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by name not provided by a service.
+   */
+  getGlobalModifierCommandsByNameNotProvidedByService(): ReadonlyMap<
+    string,
+    GlobalModifierCommand
+  >;
+
+  /**
+   * Get a map of all registered {@link GlobalModifierCommand} instances by short alias not provided by a service.
+   */
+  getGlobalModifierCommandsByShortAliasNotProvidedByService(): ReadonlyMap<
+    string,
+    GlobalModifierCommand
+  >;
+
+  /**
+   * Get a map of all registered non-modifier {@link Command} instances by name.
+   */
+  getNonModifierCommandsByName(): ReadonlyMap<string, Command>;
+
+  /**
+   * Get a map of all registered {@link GlobalCommand} instances by short alias.
+   */
+  getGlobalCommandsByShortAlias(): ReadonlyMap<string, GlobalCommand>;
+}

package/src/runtime/registry/DefaultCommandRegistry.ts

@@ -0,0 +1,318 @@
+import type CommandRegistry from "./CommandRegistry.ts";
+import type GlobalCommand from "../../api/command/GlobalCommand.ts";
+import type GlobalModifierCommand from "../../api/command/GlobalModifierCommand.ts";
+import type GroupCommand from "../../api/command/GroupCommand.ts";
+import type SubCommand from "../../api/command/SubCommand.ts";
+import type Command from "../../api/command/Command.ts";
+import {
+  isGlobalCommand,
+  isGlobalModifierCommand,
+  isGroupCommand,
+  isSubCommand,
+} from "../command/CommandTypeGuards.ts";
+import getLogger from "../../util/logger.ts";
+import type CommandValidator from "../command/CommandValidator.ts";
+
+const logger = getLogger("DefaultCommandRegistry");
+
+/**
+ * Default implementation of a {@link CommandRegistry}.
+ */
+export default class DefaultCommandRegistry implements CommandRegistry {
+  readonly #commandValidator: CommandValidator | undefined;
+  readonly #subCommandsByName: Map<string, SubCommand> = new Map();
+  readonly #groupCommandsByName: Map<string, GroupCommand> = new Map();
+  readonly #groupCommandsAndMemberSubCommandsByName: Map<
+    string,
+    { groupCommand: GroupCommand; command: SubCommand }
+  > = new Map();
+  readonly #globalCommandsByName: Map<string, GlobalCommand> = new Map();
+  readonly #globalCommandsByShortAlias: Map<string, GlobalCommand> = new Map();
+  readonly #globalModifierCommandsByName: Map<
+    string,
+    GlobalModifierCommand
+  > = new Map();
+  readonly #globalModifierCommandsByShortAlias: Map<
+    string,
+    GlobalModifierCommand
+  > = new Map();
+  readonly #globalModifierCommandsByNameByServiceId: Map<
+    string,
+    Map<string, GlobalModifierCommand>
+  > = new Map();
+  readonly #globalModifierCommandsByShortAliasByServiceId: Map<
+    string,
+    Map<string, GlobalModifierCommand>
+  > = new Map();
+  readonly #globalModifierCommandsByNameWithoutServiceId: Map<
+    string,
+    GlobalModifierCommand
+  > = new Map();
+  readonly #globalModifierCommandsByShortAliasWithoutServiceId: Map<
+    string,
+    GlobalModifierCommand
+  > = new Map();
+  readonly #nonModifierCommandsByName: Map<string, Command> = new Map();
+
+  /**
+   * Constructor taking an optional initial list of {@link Command} instances to register.
+   *
+   * @param commands optional list of {@link Command} instances.
+   * @param commandValidator optional {@link CommandValidator} to use for all registered {@link Command} instances.
+   */
+  public constructor(
+    commands?: ReadonlyArray<Command>,
+    commandValidator?: CommandValidator,
+  ) {
+    this.#commandValidator = commandValidator;
+    commands?.forEach((command) => this.addCommand(command));
+  }
+
+  /**
+   * Validate a {@link GlobalCommand} or by extension a {@link GlobalModifierCommand} against those registered so far.
+   *
+   * @throws {Error} if the name of the provided {@link GlobalCommand} is already registered.
+   */
+  #validateGlobalCommandWithOtherGlobalCommands(
+    globalCommand: GlobalCommand,
+  ): void {
+    if (this.#globalCommandsByName.has(globalCommand.name)) {
+      throw new Error(
+        `Command name: ${globalCommand.name} duplicates the name of an existing command`,
+      );
+    }
+    if (this.#globalModifierCommandsByName.has(globalCommand.name)) {
+      throw new Error(
+        `Command name: ${globalCommand.name} duplicates the name of an existing command`,
+      );
+    }
+    if (globalCommand.shortAlias !== undefined) {
+      if (this.#globalCommandsByShortAlias.has(globalCommand.shortAlias)) {
+        throw new Error(
+          `Command name: ${globalCommand.shortAlias} duplicates the short alias of an existing command`,
+        );
+      }
+      if (
+        this.#globalModifierCommandsByShortAlias.has(globalCommand.shortAlias)
+      ) {
+        throw new Error(
+          `Command name: ${globalCommand.shortAlias} duplicates the short alias of an existing command`,
+        );
+      }
+    }
+  }
+
+  /**
+   * Validate a non-global {@link Command} against those registered so far.
+   *
+   * @throws {Error} if the name of the provided {@link Command} is already registered.
+   */
+  #validateNonGlobalCommandWithOtherNonGlobalCommands(
+    command: Command,
+  ): void {
+    if (this.#subCommandsByName.has(command.name)) {
+      throw new Error(
+        `Command name: ${command.name} duplicates the name of an existing command`,
+      );
+    }
+    if (this.#groupCommandsByName.has(command.name)) {
+      throw new Error(
+        `Command name: ${command.name} duplicates the name of an existing command`,
+      );
+    }
+  }
+
+  public getSubCommands(): ReadonlyArray<SubCommand> {
+    return Array.from(this.#subCommandsByName.values());
+  }
+
+  public getGroupCommands(): ReadonlyArray<GroupCommand> {
+    return Array.from(this.#groupCommandsByName.values());
+  }
+
+  public getGlobalCommands(): ReadonlyArray<GlobalCommand> {
+    return Array.from(this.#globalCommandsByName.values());
+  }
+
+  public getGlobalModifierCommands(): ReadonlyArray<GlobalModifierCommand> {
+    return Array.from(this.#globalModifierCommandsByName.values());
+  }
+
+  /**
+   * Add a {@link Command} to the registry optionally specifying a service ID if the command
+   * was provided by a {@link ServiceProvider}.
+   *
+   * @param command the {@link Command} to register.
+   * @param serviceId the service ID if the command was provided by a {@link ServiceProvider}.
+   */
+  public addCommand(command: Command, serviceId?: string): void {
+    logger.debug("Adding command: %s", command.name);
+
+    if (this.#commandValidator !== undefined) {
+      this.#commandValidator.validate(command);
+    }
+
+    if (isSubCommand(command)) {
+      this.#validateNonGlobalCommandWithOtherNonGlobalCommands(command);
+      this.#subCommandsByName.set(command.name, command);
+      this.#nonModifierCommandsByName.set(command.name, command);
+      return;
+    }
+
+    if (isGroupCommand(command)) {
+      this.#validateNonGlobalCommandWithOtherNonGlobalCommands(command);
+      this.#groupCommandsByName.set(command.name, command);
+      this.#nonModifierCommandsByName.set(command.name, command);
+      const groupCommand = command as GroupCommand;
+      groupCommand.memberSubCommands.forEach((command) => {
+        this.#groupCommandsAndMemberSubCommandsByName.set(
+          `${groupCommand.name}:${command.name}`,
+          {
+            groupCommand,
+            command,
+          },
+        );
+      });
+      return;
+    }
+
+    if (isGlobalCommand(command)) {
+      this.#validateGlobalCommandWithOtherGlobalCommands(command);
+      this.#globalCommandsByName.set(command.name, command);
+      if (command.shortAlias !== undefined) {
+        this.#globalCommandsByShortAlias.set(command.shortAlias, command);
+      }
+      this.#nonModifierCommandsByName.set(command.name, command);
+      return;
+    }
+
+    if (isGlobalModifierCommand(command)) {
+      this.#validateGlobalCommandWithOtherGlobalCommands(command);
+      this.#globalModifierCommandsByName.set(command.name, command);
+      if (command.shortAlias !== undefined) {
+        this.#globalModifierCommandsByShortAlias.set(
+          command.shortAlias,
+          command,
+        );
+      }
+      if (serviceId === undefined) {
+        this.#globalModifierCommandsByNameWithoutServiceId.set(
+          command.name,
+          command,
+        );
+        if (command.shortAlias !== undefined) {
+          this.#globalModifierCommandsByShortAliasWithoutServiceId.set(
+            command.shortAlias,
+            command,
+          );
+        }
+      } else {
+        if (!this.#globalModifierCommandsByNameByServiceId.has(serviceId)) {
+          this.#globalModifierCommandsByNameByServiceId.set(
+            serviceId,
+            new Map(),
+          );
+        }
+        this.#globalModifierCommandsByNameByServiceId.get(serviceId)!.set(
+          command.name,
+          command,
+        );
+        if (command.shortAlias !== undefined) {
+          if (
+            !this.#globalModifierCommandsByShortAliasByServiceId.has(serviceId)
+          ) {
+            this.#globalModifierCommandsByShortAliasByServiceId.set(
+              serviceId,
+              new Map(),
+            );
+          }
+          this.#globalModifierCommandsByShortAliasByServiceId.get(serviceId)!
+            .set(command.shortAlias, command);
+        }
+      }
+      return;
+    }
+  }
+
+  public getSubCommandByName(name: string): SubCommand | undefined {
+    return this.#subCommandsByName.get(name);
+  }
+
+  public getGroupCommandByName(name: string): GroupCommand | undefined {
+    return this.#groupCommandsByName.get(name);
+  }
+
+  public getGroupCommandAndMemberSubCommandByJoinedName(
+    groupAndMemberSubCommandName: string,
+  ): { groupCommand: GroupCommand; command: SubCommand } | undefined {
+    return this.#groupCommandsAndMemberSubCommandsByName.get(
+      groupAndMemberSubCommandName,
+    );
+  }
+
+  public getGlobalCommandByName(name: string): GlobalCommand | undefined {
+    return this.#globalCommandsByName.get(name);
+  }
+
+  public getGlobalModifierCommandByName(
+    name: string,
+  ): GlobalModifierCommand | undefined {
+    return this.#globalModifierCommandsByName.get(name);
+  }
+
+  public getGroupAndMemberCommandsByJoinedName(): ReadonlyMap<
+    string,
+    { groupCommand: GroupCommand; command: SubCommand }
+  > {
+    return this.#groupCommandsAndMemberSubCommandsByName;
+  }
+
+  public getGlobalModifierCommandsByNameProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand> {
+    const getGlobalModifierCommandByName = this
+      .#globalModifierCommandsByNameByServiceId.get(serviceId);
+
+    if (getGlobalModifierCommandByName !== undefined) {
+      return getGlobalModifierCommandByName;
+    }
+    return new Map();
+  }
+
+  public getGlobalModifierCommandsByShortAliasProvidedByService(
+    serviceId: string,
+  ): ReadonlyMap<string, GlobalModifierCommand> {
+    const getGlobalModifierCommandByShortAlias = this
+      .#globalModifierCommandsByShortAliasByServiceId.get(serviceId);
+
+    if (getGlobalModifierCommandByShortAlias !== undefined) {
+      return getGlobalModifierCommandByShortAlias;
+    }
+    return new Map();
+  }
+
+  public getGlobalModifierCommandsByNameNotProvidedByService(): ReadonlyMap<
+    string,
+    GlobalModifierCommand
+  > {
+    return this.#globalModifierCommandsByNameWithoutServiceId;
+  }
+
+  public getGlobalModifierCommandsByShortAliasNotProvidedByService(): ReadonlyMap<
+    string,
+    GlobalModifierCommand
+  > {
+    return this.#globalModifierCommandsByShortAliasWithoutServiceId;
+  }
+
+  public getNonModifierCommandsByName(): ReadonlyMap<
+    string,
+    Command
+  > {
+    return this.#nonModifierCommandsByName;
+  }
+
+  public getGlobalCommandsByShortAlias(): ReadonlyMap<string, GlobalCommand> {
+    return this.#globalCommandsByShortAlias;
+  }
+}

package/src/runtime/registry/DefaultServiceProviderRegistry.ts

@@ -0,0 +1,26 @@
+import type ServiceProviderRegistry from "./ServiceProviderRegistry.ts";
+import type { ServiceProvider } from "../../api/service/ServiceProvider.ts";
+
+/**
+ * Default implementation of a {@link ServiceProviderRegistry}.
+ */
+export default class DefaultServiceProviderRegistry
+  implements ServiceProviderRegistry {
+  readonly #serviceProviders: Array<ServiceProvider> = [];
+
+  public constructor(serviceProviders?: ReadonlyArray<ServiceProvider>) {
+    if (serviceProviders !== undefined) {
+      this.#serviceProviders.push(...serviceProviders);
+    }
+  }
+
+  public addServiceProvider(serviceProvider: ServiceProvider): void {
+    this.#serviceProviders.push(serviceProvider);
+  }
+
+  public getServiceProviders(): ReadonlyArray<ServiceProvider> {
+    return this.#serviceProviders.sort((a, b) =>
+      b.servicePriority - a.servicePriority
+    );
+  }
+}

package/src/runtime/registry/ServiceProviderRegistry.ts

@@ -0,0 +1,11 @@
+import type { ServiceProvider } from "../../api/service/ServiceProvider.ts";
+
+/**
+ * Interface used by a {@link CLI} to register {@link ServiceProvider} instances.
+ */
+export default interface ServiceProviderRegistry {
+  /**
+   * Return all {@link ServiceProvider} instances registered in order of descending {@link ServiceProvider.servicePriority}
+   */
+  getServiceProviders(): ReadonlyArray<ServiceProvider>;
+}