@pablozaiden/terminatui 0.1.0

package/src/__tests__/help.test.ts

@@ -0,0 +1,412 @@
+import { test, expect, describe } from "bun:test";
+import {
+  generateHelp,
+  formatUsage,
+  formatCommands,
+  formatOptions,
+  formatExamples,
+  getCommandSummary,
+  formatGlobalOptions,
+  generateCommandHelp,
+} from "../cli/help.ts";
+import { defineCommand } from "../types/command.ts";
+
+describe("Help Generation", () => {
+  describe("formatUsage", () => {
+    test("formats basic usage", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test command",
+        execute: () => {},
+      });
+
+      const usage = formatUsage(cmd, "myapp");
+      expect(usage).toContain("myapp");
+      expect(usage).toContain("test");
+    });
+
+    test("includes [command] for commands with subcommands", () => {
+      const cmd = defineCommand({
+        name: "parent",
+        description: "Parent command",
+        subcommands: {
+          child: defineCommand({
+            name: "child",
+            description: "Child",
+            execute: () => {},
+          }),
+        },
+        execute: () => {},
+      });
+
+      const usage = formatUsage(cmd);
+      expect(usage).toContain("[command]");
+    });
+
+    test("includes [options] for commands with options", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test command",
+        options: {
+          verbose: { type: "boolean", description: "Verbose" },
+        },
+        execute: () => {},
+      });
+
+      const usage = formatUsage(cmd);
+      expect(usage).toContain("[options]");
+    });
+  });
+
+  describe("formatCommands", () => {
+    test("formats subcommands list", () => {
+      const cmd = defineCommand({
+        name: "parent",
+        description: "Parent",
+        subcommands: {
+          child: defineCommand({
+            name: "child",
+            description: "Child command",
+            execute: () => {},
+          }),
+        },
+        execute: () => {},
+      });
+
+      const commands = formatCommands(cmd);
+      expect(commands).toContain("child");
+      expect(commands).toContain("Child command");
+    });
+
+    test("excludes hidden commands", () => {
+      const cmd = defineCommand({
+        name: "parent",
+        description: "Parent",
+        subcommands: {
+          visible: defineCommand({
+            name: "visible",
+            description: "Visible",
+            execute: () => {},
+          }),
+          hidden: defineCommand({
+            name: "hidden",
+            description: "Hidden",
+            hidden: true,
+            execute: () => {},
+          }),
+        },
+        execute: () => {},
+      });
+
+      const commands = formatCommands(cmd);
+      expect(commands).toContain("visible");
+      expect(commands).not.toMatch(/\bhidden\b/);
+    });
+
+    test("shows command aliases", () => {
+      const cmd = defineCommand({
+        name: "parent",
+        description: "Parent",
+        subcommands: {
+          list: defineCommand({
+            name: "list",
+            description: "List items",
+            aliases: ["ls", "l"],
+            execute: () => {},
+          }),
+        },
+        execute: () => {},
+      });
+
+      const commands = formatCommands(cmd);
+      expect(commands).toContain("ls");
+      expect(commands).toContain("l");
+    });
+
+    test("returns empty for no subcommands", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        execute: () => {},
+      });
+
+      const commands = formatCommands(cmd);
+      expect(commands).toBe("");
+    });
+  });
+
+  describe("formatOptions", () => {
+    test("formats options with descriptions", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          verbose: { type: "boolean", description: "Enable verbose" },
+        },
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("--verbose");
+      expect(options).toContain("Enable verbose");
+    });
+
+    test("shows option aliases", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          verbose: { type: "boolean", alias: "v", description: "Verbose" },
+        },
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("-v");
+    });
+
+    test("shows default values", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          count: { type: "number", default: 10, description: "Count" },
+        },
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("10");
+    });
+
+    test("shows required marker", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          name: { type: "string", required: true, description: "Name" },
+        },
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("*");
+    });
+
+    test("shows enum values", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          level: {
+            type: "string",
+            enum: ["low", "high"],
+            description: "Level",
+          },
+        },
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toContain("low");
+      expect(options).toContain("high");
+    });
+
+    test("returns empty for no options", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        execute: () => {},
+      });
+
+      const options = formatOptions(cmd);
+      expect(options).toBe("");
+    });
+  });
+
+  describe("formatExamples", () => {
+    test("formats examples list", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        examples: [
+          { command: "test --verbose", description: "Run with verbose" },
+        ],
+        execute: () => {},
+      });
+
+      const examples = formatExamples(cmd);
+      expect(examples).toContain("test --verbose");
+      expect(examples).toContain("Run with verbose");
+    });
+
+    test("returns empty for no examples", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        execute: () => {},
+      });
+
+      const examples = formatExamples(cmd);
+      expect(examples).toBe("");
+    });
+  });
+
+  describe("generateHelp", () => {
+    test("generates help with app name and version", () => {
+      const cmd = defineCommand({
+        name: "root",
+        description: "Root command",
+        execute: () => {},
+      });
+
+      const help = generateHelp(cmd, { appName: "myapp", version: "1.0.0" });
+      expect(help).toContain("myapp");
+      expect(help).toContain("1.0.0");
+    });
+
+    test("includes usage section", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        execute: () => {},
+      });
+
+      const help = generateHelp(cmd);
+      expect(help).toContain("Usage:");
+    });
+
+    test("includes command description", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "A test command for testing",
+        execute: () => {},
+      });
+
+      const help = generateHelp(cmd);
+      expect(help).toContain("A test command for testing");
+    });
+
+    test("includes options section", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test",
+        options: {
+          verbose: { type: "boolean", description: "Verbose mode" },
+        },
+        execute: () => {},
+      });
+
+      const help = generateHelp(cmd);
+      expect(help).toContain("Options:");
+      expect(help).toContain("--verbose");
+    });
+
+    test("generates root help with commands", () => {
+      const cmd = defineCommand({
+        name: "root",
+        description: "Root",
+        subcommands: {
+          run: defineCommand({
+            name: "run",
+            description: "Run something",
+            execute: () => {},
+          }),
+        },
+        execute: () => {},
+      });
+
+      const help = generateHelp(cmd);
+      expect(help).toContain("Commands:");
+      expect(help).toContain("run");
+    });
+  });
+
+  describe("getCommandSummary", () => {
+    test("returns command summary", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "A test command",
+        execute: () => {},
+      });
+
+      const summary = getCommandSummary(cmd);
+      expect(summary).toContain("test");
+      expect(summary).toContain("A test command");
+    });
+
+    test("includes aliases in summary", () => {
+      const cmd = defineCommand({
+        name: "list",
+        description: "List items",
+        aliases: ["ls"],
+        execute: () => {},
+      });
+
+      const summary = getCommandSummary(cmd);
+      expect(summary).toContain("ls");
+    });
+  });
+
+  describe("formatGlobalOptions", () => {
+    test("includes --log-level option", () => {
+      const result = formatGlobalOptions();
+      expect(result).toContain("--log-level");
+      expect(result).toContain("Set log level");
+    });
+
+    test("includes log level choices", () => {
+      const result = formatGlobalOptions();
+      expect(result).toContain("silly");
+      expect(result).toContain("trace");
+      expect(result).toContain("debug");
+      expect(result).toContain("info");
+      expect(result).toContain("warn");
+      expect(result).toContain("error");
+      expect(result).toContain("fatal");
+    });
+
+    test("includes --detailed-logs option", () => {
+      const result = formatGlobalOptions();
+      expect(result).toContain("--detailed-logs");
+    });
+
+    test("includes --no-detailed-logs option", () => {
+      const result = formatGlobalOptions();
+      expect(result).toContain("--no-detailed-logs");
+    });
+  });
+
+  describe("generateCommandHelp with global options", () => {
+    test("includes Global Options section", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test command",
+        execute: () => {},
+      });
+
+      const help = generateCommandHelp(cmd, "myapp");
+      expect(help).toContain("Global Options:");
+      expect(help).toContain("--log-level");
+      expect(help).toContain("--detailed-logs");
+    });
+
+    test("global options appear after command options", () => {
+      const cmd = defineCommand({
+        name: "test",
+        description: "Test command",
+        options: {
+          verbose: { type: "boolean", description: "Verbose output" },
+        },
+        execute: () => {},
+      });
+
+      const help = generateCommandHelp(cmd, "myapp");
+      const optionsIndex = help.indexOf("Options:");
+      const globalOptionsIndex = help.indexOf("Global Options:");
+      
+      expect(optionsIndex).toBeGreaterThan(-1);
+      expect(globalOptionsIndex).toBeGreaterThan(optionsIndex);
+    });
+  });
+});

package/src/__tests__/parser.test.ts

@@ -0,0 +1,268 @@
+import { test, expect, describe } from "bun:test";
+import {
+  extractCommandChain,
+  schemaToParseArgsOptions,
+  parseOptionValues,
+  validateOptions,
+  parseCliArgs,
+} from "../cli/parser.ts";
+import type { OptionSchema } from "../types/command.ts";
+import { defineCommand } from "../types/command.ts";
+
+describe("extractCommandChain", () => {
+  test("extracts command path with no flags", () => {
+    const result = extractCommandChain(["run", "test"]);
+    expect(result.commands).toEqual(["run", "test"]);
+    expect(result.remaining).toEqual([]);
+  });
+
+  test("separates commands from flags", () => {
+    const result = extractCommandChain(["run", "--verbose", "file.ts"]);
+    expect(result.commands).toEqual(["run"]);
+    expect(result.remaining).toEqual(["--verbose", "file.ts"]);
+  });
+
+  test("handles args starting with flags", () => {
+    const result = extractCommandChain(["--help"]);
+    expect(result.commands).toEqual([]);
+    expect(result.remaining).toEqual(["--help"]);
+  });
+
+  test("handles short flags", () => {
+    const result = extractCommandChain(["run", "-v"]);
+    expect(result.commands).toEqual(["run"]);
+    expect(result.remaining).toEqual(["-v"]);
+  });
+
+  test("handles empty args", () => {
+    const result = extractCommandChain([]);
+    expect(result.commands).toEqual([]);
+    expect(result.remaining).toEqual([]);
+  });
+
+  test("extracts nested command path", () => {
+    const result = extractCommandChain(["config", "set", "--key", "value"]);
+    expect(result.commands).toEqual(["config", "set"]);
+    expect(result.remaining).toEqual(["--key", "value"]);
+  });
+});
+
+describe("schemaToParseArgsOptions", () => {
+  test("converts string option", () => {
+    const schema: OptionSchema = {
+      name: { type: "string", description: "Name" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    expect(result.options!["name"]?.type).toBe("string");
+  });
+
+  test("converts boolean option", () => {
+    const schema: OptionSchema = {
+      verbose: { type: "boolean", description: "Verbose" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    expect(result.options!["verbose"]?.type).toBe("boolean");
+  });
+
+  test("converts alias to short", () => {
+    const schema: OptionSchema = {
+      verbose: { type: "boolean", alias: "v", description: "Verbose" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    expect(result.options!["verbose"]?.short).toBe("v");
+  });
+
+  test("converts array option to multiple", () => {
+    const schema: OptionSchema = {
+      files: { type: "array", description: "Files" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    expect(result.options!["files"]?.multiple).toBe(true);
+  });
+
+  test("includes default values", () => {
+    const schema: OptionSchema = {
+      count: { type: "number", default: 10, description: "Count" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    // parseArgs expects string defaults for non-boolean types
+    expect(result.options!["count"]?.default).toBe("10");
+  });
+
+  test("includes default values for boolean", () => {
+    const schema: OptionSchema = {
+      verbose: { type: "boolean", default: false, description: "Verbose" },
+    };
+    const result = schemaToParseArgsOptions(schema);
+    // Boolean defaults remain as boolean
+    expect(result.options!["verbose"]?.default).toBe(false);
+  });
+});
+
+describe("parseOptionValues", () => {
+  test("passes through string values", () => {
+    const schema: OptionSchema = {
+      name: { type: "string", description: "Name" },
+    };
+    const result = parseOptionValues(schema, { name: "test" });
+    expect(result["name"]).toBe("test");
+  });
+
+  test("coerces number values", () => {
+    const schema: OptionSchema = {
+      count: { type: "number", description: "Count" },
+    };
+    const result = parseOptionValues(schema, { count: "42" });
+    expect(result["count"]).toBe(42);
+  });
+
+  test("coerces boolean values", () => {
+    const schema: OptionSchema = {
+      verbose: { type: "boolean", description: "Verbose" },
+    };
+    const result = parseOptionValues(schema, { verbose: "true" });
+    expect(result["verbose"]).toBe(true);
+  });
+
+  test("applies default values", () => {
+    const schema: OptionSchema = {
+      count: { type: "number", default: 5, description: "Count" },
+    };
+    const result = parseOptionValues(schema, {});
+    expect(result["count"]).toBe(5);
+  });
+
+  test("reads from environment variables", () => {
+    process.env["TEST_VALUE"] = "env-value";
+    const schema: OptionSchema = {
+      value: { type: "string", env: "TEST_VALUE", description: "Value" },
+    };
+    const result = parseOptionValues(schema, {});
+    expect(result["value"]).toBe("env-value");
+    delete process.env["TEST_VALUE"];
+  });
+
+  test("validates enum values", () => {
+    const schema: OptionSchema = {
+      level: {
+        type: "string",
+        enum: ["low", "medium", "high"],
+        description: "Level",
+      },
+    };
+    const result = parseOptionValues(schema, { level: "medium" });
+    expect(result["level"]).toBe("medium");
+  });
+
+  test("throws on invalid enum value", () => {
+    const schema: OptionSchema = {
+      level: {
+        type: "string",
+        enum: ["low", "medium", "high"],
+        description: "Level",
+      },
+    };
+    expect(() => parseOptionValues(schema, { level: "invalid" })).toThrow();
+  });
+});
+
+describe("validateOptions", () => {
+  test("returns empty array for valid options", () => {
+    const schema: OptionSchema = {
+      name: { type: "string", description: "Name" },
+    };
+    const errors = validateOptions(schema, { name: "test" });
+    expect(errors).toEqual([]);
+  });
+
+  test("returns error for missing required option", () => {
+    const schema: OptionSchema = {
+      name: { type: "string", required: true, description: "Name" },
+    };
+    const errors = validateOptions(schema, {} as Record<string, unknown>);
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]?.type).toBe("missing_required");
+  });
+
+  test("validates number min/max", () => {
+    const schema: OptionSchema = {
+      count: { type: "number", min: 1, max: 10, description: "Count" },
+    };
+    const errors = validateOptions(schema, { count: 0 });
+    expect(errors.length).toBeGreaterThan(0);
+    expect(errors[0]?.type).toBe("validation");
+  });
+});
+
+describe("parseCliArgs", () => {
+  test("parses command name", () => {
+    const cmd = defineCommand({
+      name: "run",
+      description: "Run command",
+      execute: () => {},
+    });
+
+    const result = parseCliArgs({
+      args: ["run"],
+      commands: { run: cmd },
+    });
+
+    expect(result.command).toBe(cmd);
+    expect(result.commandPath).toEqual(["run"]);
+  });
+
+  test("detects help flag", () => {
+    const cmd = defineCommand({
+      name: "run",
+      description: "Run command",
+      execute: () => {},
+    });
+
+    const result = parseCliArgs({
+      args: ["run", "--help"],
+      commands: { run: cmd },
+    });
+
+    expect(result.showHelp).toBe(true);
+  });
+
+  test("detects -h flag", () => {
+    const cmd = defineCommand({
+      name: "run",
+      description: "Run command",
+      execute: () => {},
+    });
+
+    const result = parseCliArgs({
+      args: ["run", "-h"],
+      commands: { run: cmd },
+    });
+
+    expect(result.showHelp).toBe(true);
+  });
+
+  test("returns error for unknown command", () => {
+    const result = parseCliArgs({
+      args: ["unknown"],
+      commands: {},
+    });
+
+    expect(result.error?.type).toBe("unknown_command");
+  });
+
+  test("uses default command if provided", () => {
+    const cmd = defineCommand({
+      name: "default",
+      description: "Default command",
+      execute: () => {},
+    });
+
+    const result = parseCliArgs({
+      args: [],
+      commands: { default: cmd },
+      defaultCommand: "default",
+    });
+
+    expect(result.command).toBe(cmd);
+  });
+});