@flowscripter/dynamic-cli-framework 1.1.5 → 1.1.6

package/index.ts

@@ -64,6 +64,7 @@ export { default as ShutdownServiceProvider } from "./src/service/shutdown/Shutd
 
 export { SYNTAX_HIGHLIGHTER_SERVICE_ID } from "./src/api/service/core/SyntaxHighlighterService.ts";
 export type { default as SyntaxHighlighterService } from "./src/api/service/core/SyntaxHighlighterService.ts";
+export type { ColorScheme } from "./src/api/service/core/SyntaxHighlighterService.ts";
 export { default as DefaultSyntaxHighlighterService } from "./src/service/syntaxHighlighter/DefaultSyntaxHighlighterService.ts";
 export { default as SyntaxHighlighterServiceProvider } from "./src/service/syntaxHighlighter/SyntaxHighlighterServiceProvider.ts";
 

package/package.json

@@ -18,7 +18,7 @@
   ],
   "module": "index.ts",
   "type": "module",
-  "version": "1.1.5",
+  "version": "1.1.6",
   "publishConfig": {
     "access": "public"
   },

package/src/api/argument/Argument.ts

@@ -13,10 +13,25 @@ export default interface Argument {
   readonly type: ArgumentValueTypeName;
 
   /**
-   * Optional list of values that the value must match.
+   * Optional list of values that the value must match. This is not supported for {@link ArgumentValueTypeName.BOOLEAN}.
    */
   readonly allowableValues?: ReadonlyArray<ArgumentSingleValueType>;
 
+  /**
+   * Optional (default is `false`) for {@link ArgumentValueTypeName.STRING} when comparing a value against {@link allowableValues}.
+   */
+  readonly isCaseInsensitive?: boolean;
+
+  /**
+   * Optional for {@link ArgumentValueTypeName.INTEGER} or {@link ArgumentValueTypeName.NUMBER} when validating a value.
+   */
+  readonly minValueInclusive?: number;
+
+  /**
+   * Optional for {@link ArgumentValueTypeName.INTEGER} or {@link ArgumentValueTypeName.NUMBER} when validating a value.
+   */
+  readonly maxValueInclusive?: number;
+
   /**
    * Optional configuration key to use for the argument. Must consist of alphanumeric non-whitespace uppercase
    * ASCII or `_` characters. Must not start with a digit.

package/src/api/argument/ArgumentValueTypes.ts

@@ -48,7 +48,7 @@ export enum ArgumentValueTypeName {
   NUMBER = 1,
   INTEGER = 2,
   BOOLEAN = 3,
-  SECRET,
+  SECRET = 4,
 }
 
 /**

package/src/api/command/SubCommand.ts

@@ -21,7 +21,7 @@ export default interface SubCommand extends Command {
   readonly positionals: ReadonlyArray<Positional>;
 
   /**
-   * Optional grouping topic of the command to structuring of help output.
+   * Optional grouping topic of the command for structuring of help output.
    */
   readonly helpTopic?: string;
 

package/src/command/MultiCommandCliHelpCommand.ts

@@ -3,7 +3,6 @@ import type Option from "../api/argument/Option.ts";
 import type SubCommand from "../api/command/SubCommand.ts";
 import type GlobalCommand from "../api/command/GlobalCommand.ts";
 import type GroupCommand from "../api/command/GroupCommand.ts";
-import { distance } from "fastest-levenshtein";
 import {
   type ArgumentSingleValueType,
   type ArgumentValues,
@@ -12,6 +11,7 @@ import {
 import type Context from "../api/Context.ts";
 import type { HelpSection } from "../util/helpHelper.ts";
 import {
+  findPossibleCommandNames,
   getCommandArgsHelpSections,
   getCommandExamplesHelpSections,
   getGlobalArgumentHelpEntry,
@@ -44,34 +44,6 @@ abstract class MultiCommandCliAbstractHelpCommand {
     this.#commandRegistry = commandRegistry;
   }
 
-  #findPossibleCommandNames(
-    commandName: string,
-    groupCommands: ReadonlyArray<GroupCommand>,
-    subCommands: ReadonlyArray<SubCommand>,
-  ): string[] {
-    const levenCommandArray = new Array<[number, string]>();
-    subCommands.forEach((subCommand) => {
-      levenCommandArray.push([
-        distance(subCommand.name, commandName),
-        subCommand.name,
-      ]);
-    });
-    groupCommands.forEach((groupCommand) => {
-      groupCommand.memberSubCommands.forEach((memberCommand) => {
-        const memberName = `${groupCommand.name}:${memberCommand.name}`;
-        levenCommandArray.push([
-          distance(memberName, commandName),
-          memberName,
-        ]);
-      });
-    });
-    return levenCommandArray
-      .sort((a, b) => a[0] - b[0])
-      .slice(0, 2)
-      .filter((value) => value[0] < 3)
-      .map((value) => value[1]);
-  }
-
   #getGlobalCommandsHelpSection(
     context: Context,
     title: string,
@@ -273,7 +245,7 @@ abstract class MultiCommandCliAbstractHelpCommand {
       );
 
       // look for other possible matches
-      const possibleCommandNames = this.#findPossibleCommandNames(
+      const possibleCommandNames = findPossibleCommandNames(
         commandName,
         groupCommands,
         subCommands,

package/src/runtime/command/CommandValidator.ts

@@ -36,6 +36,7 @@ function validateValueType(
   value: ArgumentSingleValueType,
   argumentName: string,
   isDefaultValue: boolean,
+  isRangeValue: boolean,
 ): void {
   switch (type) {
     case ArgumentValueTypeName.BOOLEAN:
@@ -51,7 +52,7 @@ function validateValueType(
       if ((typeof value !== "number") || !Number.isFinite(value)) {
         throw new Error(
           `Specified ${
-            isDefaultValue ? "default" : "allowable"
+            isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"
           } value: '${value}' for argument: '${argumentName}' should be a finite number`,
         );
       }
@@ -60,7 +61,7 @@ function validateValueType(
       if ((typeof value !== "number") || !Number.isInteger(value)) {
         throw new Error(
           `Specified ${
-            isDefaultValue ? "default" : "allowable"
+            isDefaultValue ? "default" : isRangeValue ? "range" : "allowable"
           } value: '${value}' for argument: '${argumentName}' should be an integer`,
         );
       }
@@ -112,10 +113,73 @@ function validateArgument(argument: Argument, name: string): void {
     );
   }
   if (argument.allowableValues) {
+    if (argument.type === ArgumentValueTypeName.BOOLEAN) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with allowable values specified`,
+      );
+    }
     argument.allowableValues.forEach((value) => {
-      validateValueType(argument.type, value, name, false);
+      validateValueType(argument.type, value, name, false, false);
     });
   }
+  if (argument.isCaseInsensitive !== undefined) {
+    if (
+      (argument.type === ArgumentValueTypeName.BOOLEAN) &&
+      (argument.isCaseInsensitive === false)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' must always be case insensitive`,
+      );
+    } else if (argument.type !== ArgumentValueTypeName.STRING) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with case insensitive specified`,
+      );
+    }
+  }
+  if (argument.minValueInclusive !== undefined) {
+    if (
+      (argument.type !== ArgumentValueTypeName.NUMBER) &&
+      (argument.type !== ArgumentValueTypeName.INTEGER)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with min value specified`,
+      );
+    }
+    if (argument.allowableValues) {
+      throw new Error(
+        `Illegal combination of allowable values and min value for argument: '${name}'`,
+      );
+    }
+    validateValueType(
+      argument.type,
+      argument.minValueInclusive,
+      name,
+      false,
+      true,
+    );
+  }
+  if (argument.maxValueInclusive !== undefined) {
+    if (
+      (argument.type !== ArgumentValueTypeName.NUMBER) &&
+      (argument.type !== ArgumentValueTypeName.INTEGER)
+    ) {
+      throw new Error(
+        `Illegal type: '${argument.type}' for argument: '${name}' with max value specified`,
+      );
+    }
+    if (argument.allowableValues) {
+      throw new Error(
+        `Illegal combination of allowable values and max value for argument: '${name}'`,
+      );
+    }
+    validateValueType(
+      argument.type,
+      argument.maxValueInclusive,
+      name,
+      false,
+      true,
+    );
+  }
 }
 
 function validateSubCommandArgument(

package/src/runtime/runner.ts

@@ -12,6 +12,7 @@ import type {
 import getLogger from "../util/logger.ts";
 import {
   printCommandExecutionError,
+  printNoCommandRecognisedError,
   printNoCommandSpecifiedError,
   printParseResultError,
   printUnusedArgsWarning,
@@ -690,7 +691,15 @@ export async function run(
   }
 
   // give up if we haven't successfully parsed a non-modifier Command by now
-  await printNoCommandSpecifiedError(context);
+  if (availableArgs.length > 0) {
+    await printNoCommandRecognisedError(
+      context,
+      commandRegistry,
+      availableArgs.flat(),
+    );
+  } else {
+    await printNoCommandSpecifiedError(context);
+  }
   return {
     runState: RunState.NO_COMMAND,
   };

package/src/runtime/values/argumentValueValidation.ts

@@ -111,15 +111,54 @@ function validatePrimitiveValue(
   }
 
   // check if the value is valid
-  if (argument.allowableValues && !argument.allowableValues.includes(value)) {
-    return {
-      invalidArgument: {
-        argument,
-        value,
-        reason: InvalidArgumentReason.ILLEGAL_VALUE,
-      },
-    };
+
+  if (argument.allowableValues) {
+    let searchValue = convertedValue;
+    let allowableValues = argument.allowableValues;
+
+    if (
+      (argument.type === ArgumentValueTypeName.STRING) &&
+      argument.isCaseInsensitive
+    ) {
+      searchValue = convertedValue.toLowerCase();
+      allowableValues = argument.allowableValues.map((v) =>
+        (v as string).toLowerCase()
+      );
+    }
+    if (!allowableValues.includes(searchValue)) {
+      return {
+        invalidArgument: {
+          argument,
+          value,
+          reason: InvalidArgumentReason.ILLEGAL_VALUE,
+        },
+      };
+    }
+  }
+  if (argument.minValueInclusive !== undefined) {
+    if (convertedValue < argument.minValueInclusive) {
+      return {
+        invalidArgument: {
+          argument,
+          value,
+          reason: InvalidArgumentReason.ILLEGAL_VALUE,
+        },
+      };
+    }
   }
+
+  if (argument.maxValueInclusive !== undefined) {
+    if (convertedValue > argument.maxValueInclusive) {
+      return {
+        invalidArgument: {
+          argument,
+          value,
+          reason: InvalidArgumentReason.ILLEGAL_VALUE,
+        },
+      };
+    }
+  }
+
   return { validValue: convertedValue };
 }
 

package/src/service/printer/command/LogLevelCommand.ts

@@ -23,6 +23,7 @@ export default class LogLevelCommand implements GlobalModifierCommand {
       "WARN",
       "ERROR",
     ],
+    isCaseInsensitive: true,
     defaultValue: "INFO",
     configurationKey: "LOG_LEVEL",
   };
@@ -44,7 +45,7 @@ export default class LogLevelCommand implements GlobalModifierCommand {
   ): Promise<void> {
     const logLevel = argumentValue as string;
 
-    switch (logLevel) {
+    switch (logLevel.toUpperCase()) {
       case "DEBUG":
         this.#printerServiceProvider.printerService!.setLevel(
           Level.DEBUG,

package/src/util/helpHelper.ts

@@ -1,3 +1,4 @@
+import { distance } from "fastest-levenshtein";
 import type GlobalCommand from "../api/command/GlobalCommand.ts";
 import type GlobalCommandArgument from "../api/argument/GlobalCommandArgument.ts";
 import {
@@ -267,6 +268,20 @@ export function getGlobalArgumentHelpEntry(
         notesItems.push("number value");
         break;
     }
+    if (
+      (argument.minValueInclusive !== undefined) ||
+      (argument.maxValueInclusive !== undefined)
+    ) {
+      let range = "..";
+
+      if (argument.minValueInclusive !== undefined) {
+        range = argument.minValueInclusive + range;
+      }
+      if (argument.maxValueInclusive !== undefined) {
+        range += argument.maxValueInclusive;
+      }
+      notesItems.push(range);
+    }
   }
 
   if (argument.defaultValue !== undefined) {
@@ -399,6 +414,21 @@ function getOptionHelpEntry(
       }
     }
   }
+  if (
+    (option.minValueInclusive !== undefined) ||
+    (option.maxValueInclusive !== undefined)
+  ) {
+    let range = "..";
+
+    if (option.minValueInclusive !== undefined) {
+      range = option.minValueInclusive + range;
+    }
+    if (option.maxValueInclusive !== undefined) {
+      range += option.maxValueInclusive;
+    }
+    notesItems.push(range);
+  }
+
   if (option.defaultValue !== undefined) {
     notesItems.push(
       `default: ${
@@ -480,6 +510,20 @@ function getPositionalHelpEntry(
         break;
     }
   }
+  if (
+    (positional.minValueInclusive !== undefined) ||
+    (positional.maxValueInclusive !== undefined)
+  ) {
+    let range = "..";
+
+    if (positional.minValueInclusive !== undefined) {
+      range = positional.minValueInclusive + range;
+    }
+    if (positional.maxValueInclusive !== undefined) {
+      range += positional.maxValueInclusive;
+    }
+    notesItems.push(range);
+  }
 
   if (positional.isVarargOptional) {
     notesItems.push("optional");
@@ -633,7 +677,7 @@ export function getMultiCommandAppSyntax(
   let argOptional = false;
   let argValueOptional = false;
   let multipleArg = false;
-  const commandClauses = [];
+  const commandClauses: string[] = [];
   if (globalCommands.length > 0) {
     commandClauses.push(`<${globalPrefix}command>`);
     arg = globalCommands.some((
@@ -749,3 +793,31 @@ export function getMultiCommandAppSyntax(
   }
   return syntax;
 }
+
+export function findPossibleCommandNames(
+  commandName: string,
+  groupCommands: ReadonlyArray<GroupCommand>,
+  subCommands: ReadonlyArray<SubCommand>,
+): string[] {
+  const levenCommandArray = new Array<[number, string]>();
+  subCommands.forEach((subCommand) => {
+    levenCommandArray.push([
+      distance(subCommand.name, commandName),
+      subCommand.name,
+    ]);
+  });
+  groupCommands.forEach((groupCommand) => {
+    groupCommand.memberSubCommands.forEach((memberCommand) => {
+      const memberName = `${groupCommand.name}:${memberCommand.name}`;
+      levenCommandArray.push([
+        distance(memberName, commandName),
+        memberName,
+      ]);
+    });
+  });
+  return levenCommandArray
+    .sort((a, b) => a[0] - b[0])
+    .slice(0, 2)
+    .filter((value) => value[0] < 3)
+    .map((value) => value[1]);
+}

package/src/util/runnerHelper.ts

@@ -10,6 +10,8 @@ import {
 } from "../runtime/command/CommandTypeGuards.ts";
 import type Context from "../api/Context.ts";
 import { getInvalidArgumentString } from "../runtime/values/argumentValueValidation.ts";
+import CommandRegistry from "../runtime/registry/CommandRegistry.ts";
+import { findPossibleCommandNames } from "./helpHelper.ts";
 
 function getCommandString(
   printerService: PrinterService,
@@ -91,6 +93,45 @@ export async function printNoCommandSpecifiedError(context: Context) {
   await printerService.error("No command specified\n\n");
 }
 
+export async function printNoCommandRecognisedError(
+  context: Context,
+  commandRegistry: CommandRegistry,
+  availableArgs: ReadonlyArray<string>,
+) {
+  const printerService = context.getServiceById(
+    PRINTER_SERVICE_ID,
+  ) as PrinterService;
+  await printerService.error("No command recognised\n\n");
+
+  if (availableArgs.length > 0) {
+    const groupCommands = commandRegistry.getGroupCommands();
+    const subCommands = commandRegistry.getSubCommands();
+
+    const allPossibleCommandNames: string[] = [];
+    for (const arg of availableArgs) {
+      // look for other possible matches
+      const possibleCommandNames = findPossibleCommandNames(
+        arg,
+        groupCommands,
+        subCommands,
+      );
+      // add the possible command names to the list if not already present
+      for (const possibleCommandName of possibleCommandNames) {
+        if (!allPossibleCommandNames.includes(possibleCommandName)) {
+          allPossibleCommandNames.push(possibleCommandName);
+        }
+      }
+    }
+
+    if (allPossibleCommandNames.length > 0) {
+      await printerService.print(
+        `Possible matches: ${allPossibleCommandNames.join(", ")}\n\n`,
+        Icon.INFORMATION,
+      );
+    }
+  }
+}
+
 export async function printUnusedArgsWarning(
   context: Context,
   overallUnusedArgs: ReadonlyArray<string>,

package/tests/runtime/command/CommandValidator.test.ts

@@ -90,6 +90,77 @@ describe("CommandValidator tests", () => {
       .toThrow();
   });
 
+  test(
+    "SubCommand validation fails due to boolean argument type not supporting allowable values",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.BOOLEAN,
+        allowableValues: ["goo"],
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
+  test(
+    "SubCommand validation fails due to boolean argument type not supporting case sensitivity",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.BOOLEAN,
+        isCaseInsensitive: true,
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
+  test(
+    "SubCommand validation fails due to number argument type not supporting case insensitivity",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.NUMBER,
+        isCaseInsensitive: false,
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
+  test(
+    "SubCommand validation fails due to string argument type not supporting value range",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.STRING,
+        minValueInclusive: 1,
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
+  test(
+    "SubCommand validation fails due to number argument type not supporting value range and allowable values",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.NUMBER,
+        allowableValues: [1],
+        minValueInclusive: 1,
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
   test(
     "SubCommand validation fails due to option default value" +
       " not matching any values specified in argument valid values",
@@ -106,6 +177,38 @@ describe("CommandValidator tests", () => {
     },
   );
 
+  test(
+    "SubCommand validation fails due to option default value" +
+      " not matching any values specified in argument valid values with case sensitivity",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.STRING,
+        defaultValue: "bar",
+        allowableValues: ["BAR"],
+      }], []);
+
+      expect(() => new CommandValidator(getCLIConfig()).validate(command))
+        .toThrow();
+    },
+  );
+
+  test(
+    "SubCommand validation successed with option default value" +
+      " matching value specified in argument valid values with case insensitivity",
+    () => {
+      const command = getSubCommand("command", [{
+        name: "foo",
+        type: ArgumentValueTypeName.STRING,
+        defaultValue: "bar",
+        allowableValues: ["BAR"],
+        isCaseInsensitive: true,
+      }], []);
+
+      new CommandValidator(getCLIConfig()).validate(command);
+    },
+  );
+
   test(
     "SubCommand validation fails due to the type of option defaultValue" +
       " not matching the type specified in argument type",

package/tests/runtime/runner.test.ts

@@ -689,6 +689,42 @@ describe("runner tests", () => {
     expect(hasRun).toBeFalse();
   });
 
+  test("No command recognised", async () => {
+    const streamString = new StreamString();
+    let hasRun = false;
+    const option = {
+      name: "foo",
+      type: ArgumentValueTypeName.STRING,
+      shortAlias: "f",
+    };
+    const subCommand = getSubCommand("command", [option], []);
+
+    subCommand.execute = (): Promise<void> => {
+      hasRun = true;
+      return Promise.resolve();
+    };
+
+    const commandRegistry = new DefaultCommandRegistry([subCommand]);
+    const runResult = await run(
+      ["blah", "comman", "ommand"],
+      commandRegistry,
+      getServiceProviderRegistry(),
+      undefined,
+      getContext(streamString),
+    );
+
+    expect(runResult.runState).toEqual(RunState.NO_COMMAND);
+    expectStringIncludes(
+      streamString.getString(),
+      "No command recognised",
+    );
+    expectStringIncludes(
+      streamString.getString(),
+      "Possible matches: command\n",
+    );
+    expect(hasRun).toBeFalse();
+  });
+
   test("Unknown arg warning in non-global run", async () => {
     const streamString = new StreamString();
     let hasRun = false;

package/tests/runtime/values/argumentValueValidation.test.ts

@@ -286,7 +286,7 @@ describe("argumentValueValidation tests", () => {
     }]);
   });
 
-  test("Invalid option argument value", () => {
+  test("Invalid option argument value - not an allowable value", () => {
     let option: Option = {
       name: "foo",
       type: ArgumentValueTypeName.STRING,
@@ -312,6 +312,27 @@ describe("argumentValueValidation tests", () => {
     }]);
   });
 
+  test("Invalid option argument value - not within range", () => {
+    const option: Option = {
+      name: "foo",
+      type: ArgumentValueTypeName.INTEGER,
+      minValueInclusive: 1,
+    };
+    const invalidArguments: Array<InvalidArgument> = [];
+    expect(validateOptionValue(option, "1", invalidArguments), "1");
+    expect(invalidArguments).toEqual([]);
+
+    expect(
+      validateOptionValue(option, "0", invalidArguments),
+    ).toBeUndefined();
+    expect(invalidArguments).toEqual([{
+      argument: option,
+      name: "foo",
+      value: "0",
+      reason: InvalidArgumentReason.ILLEGAL_VALUE,
+    }]);
+  });
+
   test("Complex options", () => {
     const option: ComplexOption = {
       name: "foo",

package/tests/service/printer/command/LogLevelCommand.test.ts

@@ -45,7 +45,7 @@ describe("LogLevelCommand tests", () => {
       Level.INFO,
     );
 
-    await logLevelCommand.execute(context, "ERROR");
+    await logLevelCommand.execute(context, "eRror");
 
     expect(
       printerServiceProvider.printerService!.getLevel(),