better-commits 1.20.0-cli-flags → 1.20.1-temp.0

package/docs/valibot.md

@@ -1,228 +0,0 @@
-# Valibot Usage
-
-`better-commits` uses [`valibot`](https://valibot.dev) (`^0.30.0`) for all runtime schema validation, type inference, and config parsing. Valibot defines the shape of every configuration object, commit state, and branch state in the application.
-
-## Files
-
-| File                    | Role                                                               |
-| ----------------------- | ------------------------------------------------------------------ |
-| `src/valibot-consts.ts` | Shared picklist schemas and constant arrays                        |
-| `src/valibot-state.ts`  | Core schema definitions for `Config`, `CommitState`, `BranchState` |
-| `src/utils.ts`          | Config loading, `parse`, and `ValiError` handling                  |
-| `src/index.ts`          | Parses `CommitState`; uses `Output<>` types                        |
-| `src/branch.ts`         | Parses `BranchState`; uses `Output<>` types                        |
-| `src/init.ts`           | Calls `parse(Config, {})` to generate a default config file        |
-
-## Schema Overview
-
-### `src/valibot-consts.ts` — Picklist Constants
-
-Defines shared enum-like schemas used across the codebase:
-
-```ts
-export const V_BRANCH_ACTIONS = v.picklist(["branch", "worktree"]);
-export const V_FOOTER_OPTIONS = v.picklist([
-  "closes",
-  "trailer",
-  "breaking-change",
-  "deprecated",
-  "custom",
-]);
-export const V_BRANCH_FIELDS = v.picklist([
-  "user",
-  "version",
-  "type",
-  "ticket",
-  "description",
-]);
-export const V_BRANCH_CONFIG_FIELDS = v.picklist([
-  "branch_user",
-  "branch_version",
-  "branch_type",
-  "branch_ticket",
-  "branch_description",
-]);
-```
-
-Constant arrays are typed using `v.Output<>` to derive element types directly from the schemas:
-
-```ts
-export const FOOTER_OPTION_VALUES: v.Output<typeof V_FOOTER_OPTIONS>[] = [...];
-export const BRANCH_ORDER_DEFAULTS: v.Output<typeof V_BRANCH_FIELDS>[] = [...];
-```
-
----
-
-### `src/valibot-state.ts` — Core Schemas
-
-#### `Config`
-
-The main application config schema. Validates `.better-commits.json`. Parsing an empty object `{}` produces a fully-defaulted config.
-
-Key fields and their validators:
-
-| Field                    | Schema                                                        | Default    |
-| ------------------------ | ------------------------------------------------------------- | ---------- |
-| `check_status`           | `v.optional(v.boolean(), true)`                               | `true`     |
-| `cache_last_value`       | `v.optional(v.boolean(), true)`                               | `true`     |
-| `confirm_with_editor`    | `v.optional(v.boolean(), false)`                              | `false`    |
-| `confirm_commit`         | `v.optional(v.boolean(), true)`                               | `true`     |
-| `print_commit_output`    | `v.optional(v.boolean(), true)`                               | `true`     |
-| `enable_worktrees`       | `v.optional(v.boolean(), true)`                               | `true`     |
-| `branch_pre_commands`    | `v.optional(v.array(v.string()), [])`                         | `[]`       |
-| `branch_post_commands`   | `v.optional(v.array(v.string()), [])`                         | `[]`       |
-| `worktree_pre_commands`  | `v.optional(v.array(v.string()), [])`                         | `[]`       |
-| `worktree_post_commands` | `v.optional(v.array(v.string()), [])`                         | `[]`       |
-| `branch_action_default`  | `v.optional(V_BRANCH_ACTIONS, "branch")`                      | `"branch"` |
-| `branch_order`           | `v.optional(v.array(V_BRANCH_FIELDS), BRANCH_ORDER_DEFAULTS)` | all fields |
-
-**Notable nested validators:**
-
-- `commit_type.options[].emoji` — `v.string([v.emoji()])` validates the value is a real emoji character
-- `commit_type.max_items` / `commit_scope.max_items` — `v.number([v.minValue(1)])` enforces minimum of 1
-- `check_ticket.prepend_hashtag` — `v.picklist(["Never", "Always", "Prompt"])`
-- `check_ticket.surround` — `v.picklist(["", "()", "[]", "{}"])`
-- `check_ticket.title_position` — `v.picklist(["start", "end", "before-colon", "beginning"])`
-- `branch_*.separator` — `v.picklist(["/", "-", "_"])` (branch_description also allows `""`)
-
-**Cross-field validation with `v.custom`:**
-
-Both `commit_type` and `commit_scope` use `v.custom` to ensure `initial_value` exists within their `options` array:
-
-```ts
-v.custom(
-  (val) =>
-    !val.initial_value ||
-    val.options.some((o) => o.value === val.initial_value),
-  (val) =>
-    `Type: initial_value "${val.input.initial_value}" must exist in options`,
-);
-```
-
-**Post-parse transformation with `v.transform`:**
-
-- `commit_type` — when `append_emoji_to_label` is `true`, prepends emoji to each option's label
-- `commit_scope` — when `custom_scope` is `true`, injects `{ label: "custom", value: "custom", hint: "..." }` into options if not already present
-
----
-
-#### `CommitState`
-
-Models the mutable in-memory state of an in-progress commit. All fields are `v.optional(v.string(), "")`.
-
-| Field              | Purpose                     |
-| ------------------ | --------------------------- |
-| `type`             | Commit type (e.g. `"feat"`) |
-| `scope`            | Commit scope (e.g. `"app"`) |
-| `title`            | Short commit title          |
-| `body`             | Long commit body            |
-| `closes`           | "Closes: " footer token     |
-| `ticket`           | Issue/ticket number         |
-| `breaking_title`   | Breaking change summary     |
-| `breaking_body`    | Breaking change description |
-| `deprecates`       | Deprecation marker          |
-| `deprecates_title` | Deprecation summary         |
-| `deprecates_body`  | Deprecation description     |
-| `custom_footer`    | Custom footer text          |
-| `trailer`          | Git trailer string          |
-
----
-
-#### `BranchState`
-
-Models the mutable in-memory state for the `better-branch` CLI flow. All fields are `v.optional(v.string(), "")`.
-
-| Field         | Purpose                             |
-| ------------- | ----------------------------------- |
-| `user`        | Git username portion of branch name |
-| `type`        | Branch type (mirrors commit type)   |
-| `ticket`      | Ticket/issue number                 |
-| `description` | Short branch description            |
-| `version`     | Version number                      |
-
----
-
-## Runtime Usage
-
-### Parsing with defaults
-
-All three state objects are initialized by parsing an empty object, which triggers all `v.optional` defaults:
-
-```ts
-// src/index.ts
-const commit_state = parse(CommitState, {});
-
-// src/branch.ts
-const branch_state = parse(BranchState, {});
-
-// src/init.ts
-const default_config = parse(Config, {});
-```
-
-### Config validation in `src/utils.ts`
-
-`validate_config` wraps `parse(Config, config)` to produce human-friendly errors:
-
-```ts
-function validate_config(config: unknown) {
-  try {
-    return parse(Config, config);
-  } catch (err) {
-    if (err instanceof ValiError) {
-      const path = err.issues[0].path?.map((p) => p.key).join(".");
-      p.log.error(`Invalid config at: ${path}`);
-      process.exit(1);
-    }
-  }
-}
-```
-
-### TypeScript types via `Output<>`
-
-`Output<typeof Schema>` is used throughout as the TypeScript type for parsed objects, avoiding manual interface duplication:
-
-```ts
-// Function signatures
-function build_commit_string(
-  state: Output<typeof CommitState>,
-  config: Output<typeof Config>
-): string { ... }
-
-// Variable types
-const checkout_type: Output<typeof V_BRANCH_ACTIONS> = ...;
-```
-
----
-
-## Valibot API Summary
-
-| API                           | Purpose                                                                |
-| ----------------------------- | ---------------------------------------------------------------------- |
-| `v.object({...})`             | Defines all three top-level schemas and all nested sub-objects         |
-| `v.optional(schema, default)` | Makes fields optional with a fallback default                          |
-| `v.boolean()`                 | Validates boolean config flags                                         |
-| `v.string()`                  | Validates string fields                                                |
-| `v.number([...])`             | Validates number fields with optional pipe validators                  |
-| `v.array(schema)`             | Validates array fields                                                 |
-| `v.picklist([...])`           | Validates enum-like string fields                                      |
-| `v.minValue(1)`               | Pipe validator: enforces a minimum numeric value                       |
-| `v.emoji()`                   | Pipe validator: ensures a string is a valid emoji character            |
-| `v.custom(fn, msgFn)`         | Cross-field validation with a custom predicate                         |
-| `v.transform(schema, fn)`     | Post-parse transformation of validated data                            |
-| `parse(schema, data)`         | Parses and validates data, applying all defaults and transforms        |
-| `Output<typeof Schema>`       | TypeScript utility to extract the inferred output type                 |
-| `ValiError`                   | Error class caught to produce human-readable validation error messages |
-
----
-
-## Known Quirk
-
-`src/branch.ts` contains a bare no-op reference to `CommitState` at the bottom of the file:
-
-```ts
-// TODO: No idea what's happening here
-// If you don't use CommitState, (even in unreachable code), parse fails on Config
-CommitState;
-```
-
-This is a workaround for a bundler/tree-shaking issue: without this reference, `parse(Config, ...)` fails at runtime. The root cause is likely that `CommitState` imports something from `valibot-state.ts` that is needed for `Config` to work correctly at runtime, but the bundler eliminates it as dead code without this reference.

package/src/args.test.ts

@@ -1,102 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parse_runtime_flags } from "./args";
-
-describe("parse_runtime_flags", () => {
-  it("uses interactive mode by default", () => {
-    const parsed = parse_runtime_flags([]);
-
-    expect(parsed.no_interactive).toBe(false);
-    expect(parsed.dry_run).toBe(false);
-    expect(parsed.git_args).toBe("");
-    expect(parsed.commit_state).toEqual({});
-  });
-
-  it("parses --no-interactive and --dry-run", () => {
-    const parsed = parse_runtime_flags(["--no-interactive", "--dry-run"]);
-
-    expect(parsed.no_interactive).toBe(true);
-    expect(parsed.dry_run).toBe(true);
-  });
-
-  it("parses --version and -v", () => {
-    const long_flag = parse_runtime_flags(["--version"]);
-    const short_flag = parse_runtime_flags(["-v"]);
-
-    expect(long_flag.version).toBe(true);
-    expect(short_flag.version).toBe(true);
-  });
-
-  it("maps commit flags into commit_state keys", () => {
-    const parsed = parse_runtime_flags([
-      "--type",
-      "feat",
-      "--title",
-      "ship feature",
-      "--breaking-title",
-      "api changed",
-      "--custom-footer",
-      "Reviewed-by: Jane",
-    ]);
-
-    expect(parsed.commit_state).toEqual({
-      type: "feat",
-      title: "ship feature",
-      breaking_title: "api changed",
-      custom_footer: "Reviewed-by: Jane",
-    });
-  });
-
-  it("builds git args from --git-dir and --work-tree", () => {
-    const parsed = parse_runtime_flags([
-      "--git-dir",
-      "/tmp/repo/.git",
-      "--work-tree",
-      "/tmp/repo",
-    ]);
-
-    expect(parsed.git_args).toBe(
-      "--git-dir=/tmp/repo/.git --work-tree=/tmp/repo",
-    );
-  });
-
-  it("builds git args when only one git location flag is provided", () => {
-    const with_git_dir = parse_runtime_flags(["--git-dir", "/tmp/repo/.git"]);
-    const with_work_tree = parse_runtime_flags(["--work-tree", "/tmp/repo"]);
-
-    expect(with_git_dir.git_args).toBe("--git-dir=/tmp/repo/.git");
-    expect(with_work_tree.git_args).toBe("--work-tree=/tmp/repo");
-  });
-
-  it("maps dashed commit flags to snake_case commit_state keys", () => {
-    const parsed = parse_runtime_flags([
-      "--breaking-body",
-      "major impact",
-      "--deprecates-title",
-      "legacy endpoint",
-      "--deprecates-body",
-      "use v2 endpoint",
-      "--custom-footer",
-      "Reviewed-by: Alex",
-      "--breaking-title",
-      "v1 removed",
-    ]);
-
-    expect(parsed.commit_state).toEqual({
-      breaking_body: "major impact",
-      deprecates_title: "legacy endpoint",
-      deprecates_body: "use v2 endpoint",
-      custom_footer: "Reviewed-by: Alex",
-      breaking_title: "v1 removed",
-    });
-  });
-
-  it("honors interactive flag semantics", () => {
-    const default_flags = parse_runtime_flags([]);
-    const explicit_interactive = parse_runtime_flags(["--interactive"]);
-    const no_interactive = parse_runtime_flags(["--no-interactive"]);
-
-    expect(default_flags.no_interactive).toBe(false);
-    expect(explicit_interactive.no_interactive).toBe(false);
-    expect(no_interactive.no_interactive).toBe(true);
-  });
-});

package/src/args.ts

@@ -1,106 +0,0 @@
-import { parse } from "@bomb.sh/args";
-import { InferOutput } from "valibot";
-import { CommitState } from "./valibot-state";
-
-type CommitStateRuntime = InferOutput<typeof CommitState>;
-
-type ParsedRuntimeFlags = {
-  help: boolean;
-  version: boolean;
-  git_args: string;
-  no_interactive: boolean;
-  dry_run: boolean;
-  commit_state: Partial<CommitStateRuntime>;
-};
-
-export const COMMIT_OPTIONS = [
-  "type",
-  "scope",
-  "title",
-  "body",
-  "closes",
-  "ticket",
-  "trailer",
-  "deprecates",
-  "breaking-title",
-  "breaking-body",
-  "deprecates-title",
-  "deprecates-body",
-  "custom-footer",
-] as const;
-
-export const GIT_OPTIONS = ["git-dir", "work-tree"] as const;
-
-export const BOOLEAN_FLAGS = [
-  "interactive",
-  "dry-run",
-  "help",
-  "version",
-] as const;
-
-class Flags {
-  #runtime: ParsedRuntimeFlags;
-
-  constructor(runtime: ParsedRuntimeFlags) {
-    this.#runtime = runtime;
-  }
-
-  get git_args(): string {
-    return this.#runtime.git_args;
-  }
-
-  get interactive(): boolean {
-    return !this.#runtime.no_interactive;
-  }
-
-  get dry_run(): boolean {
-    return this.#runtime.dry_run;
-  }
-
-  get help(): boolean {
-    return this.#runtime.help;
-  }
-
-  get version(): boolean {
-    return this.#runtime.version;
-  }
-
-  get commit_state(): Partial<CommitStateRuntime> {
-    return this.#runtime.commit_state;
-  }
-}
-
-export const flags = new Flags(parse_runtime_flags(process.argv.slice(2)));
-
-export function parse_runtime_flags(argv: string[]): ParsedRuntimeFlags {
-  const parsed = parse(argv, {
-    alias: { h: "help", v: "version" },
-    boolean: BOOLEAN_FLAGS,
-    string: [...COMMIT_OPTIONS, ...GIT_OPTIONS],
-  });
-
-  const commit_state: Partial<CommitStateRuntime> = {};
-  COMMIT_OPTIONS.forEach((value) => {
-    const cli_value = parsed[value];
-    if (cli_value) {
-      const str = value.replace("-", "_") as keyof CommitStateRuntime;
-      commit_state[str] = cli_value;
-    }
-  });
-
-  return {
-    help: parsed["help"] === true,
-    version: parsed["version"] === true,
-    git_args: get_git_args(parsed["git-dir"], parsed["work-tree"]),
-    no_interactive: parsed.interactive === false,
-    dry_run: parsed["dry-run"] === true,
-    commit_state,
-  };
-}
-
-function get_git_args(
-  git_dir: string | undefined,
-  work_tree: string | undefined,
-): string {
-  return `${git_dir ? `--git-dir=${git_dir}` : ""} ${work_tree ? `--work-tree=${work_tree}` : ""}`.trim();
-}

package/src/branch-args.test.ts

@@ -1,72 +0,0 @@
-import { describe, expect, it } from "vitest";
-import { parse_branch_runtime_flags } from "./branch-args";
-
-describe("parse_branch_runtime_flags", () => {
-  it("maps branch flags into branch_state keys", () => {
-    const parsed = parse_branch_runtime_flags([
-      "--user",
-      "erik",
-      "--type",
-      "feat",
-      "--ticket",
-      "ABC-123",
-      "--description",
-      "add-parser",
-      "--branch-version",
-      "1.2.0",
-    ]);
-
-    expect(parsed.branch_state).toEqual({
-      user: "erik",
-      type: "feat",
-      ticket: "ABC-123",
-      description: "add-parser",
-      version: "1.2.0",
-    });
-  });
-
-  it("maps --checkout into checkout", () => {
-    const parsed = parse_branch_runtime_flags(["--checkout", "worktree"]);
-
-    expect(parsed.branch_state).toEqual({
-      checkout: "worktree",
-    });
-  });
-
-  it("does not set checkout when --checkout is omitted", () => {
-    const parsed = parse_branch_runtime_flags([
-      "--type",
-      "feat",
-      "--description",
-      "add-parser",
-    ]);
-
-    expect(parsed.branch_state).toEqual({
-      type: "feat",
-      description: "add-parser",
-    });
-  });
-
-  it("honors interactive flag semantics", () => {
-    const default_flags = parse_branch_runtime_flags([]);
-    const explicit_interactive = parse_branch_runtime_flags(["--interactive"]);
-    const no_interactive = parse_branch_runtime_flags(["--no-interactive"]);
-
-    expect(default_flags.no_interactive).toBe(false);
-    expect(explicit_interactive.no_interactive).toBe(false);
-    expect(no_interactive.no_interactive).toBe(true);
-  });
-
-  it("parses git-dir and work-tree into git_args", () => {
-    const parsed = parse_branch_runtime_flags([
-      "--git-dir",
-      "/tmp/repo/.git",
-      "--work-tree",
-      "/tmp/repo",
-    ]);
-
-    expect(parsed.git_args).toBe(
-      "--git-dir=/tmp/repo/.git --work-tree=/tmp/repo",
-    );
-  });
-});

package/src/branch-args.ts

@@ -1,106 +0,0 @@
-import { parse } from "@bomb.sh/args";
-import { InferOutput } from "valibot";
-import { BranchState } from "./valibot-state";
-
-type BranchStateRuntime = InferOutput<typeof BranchState>;
-
-type ParsedRuntimeFlags = {
-  help: boolean;
-  version: boolean;
-  git_args: string;
-  no_interactive: boolean;
-  dry_run: boolean;
-  branch_state: Partial<BranchStateRuntime>;
-};
-
-const BRANCH_OPTIONS = [
-  "user",
-  "type",
-  "description",
-  "ticket",
-  "branch-version",
-  "checkout",
-] as const;
-
-export const GIT_OPTIONS = ["git-dir", "work-tree"] as const;
-
-export const BOOLEAN_FLAGS = [
-  "interactive",
-  "dry-run",
-  "help",
-  "version",
-] as const;
-
-class BranchFlags {
-  #runtime: ParsedRuntimeFlags;
-
-  constructor(runtime: ParsedRuntimeFlags) {
-    this.#runtime = runtime;
-  }
-
-  get interactive(): boolean {
-    return !this.#runtime.no_interactive;
-  }
-
-  get dry_run(): boolean {
-    return this.#runtime.dry_run;
-  }
-
-  get help(): boolean {
-    return this.#runtime.help;
-  }
-
-  get version(): boolean {
-    return this.#runtime.version;
-  }
-
-  get git_args(): string {
-    return this.#runtime.git_args;
-  }
-
-  get branch_state(): Partial<BranchStateRuntime> {
-    return this.#runtime.branch_state;
-  }
-}
-
-export const branch_flags = new BranchFlags(
-  parse_branch_runtime_flags(process.argv.slice(2)),
-);
-
-export function parse_branch_runtime_flags(argv: string[]): ParsedRuntimeFlags {
-  const parsed = parse(argv, {
-    alias: { h: "help", v: "version" },
-    boolean: BOOLEAN_FLAGS,
-    string: [...BRANCH_OPTIONS, ...GIT_OPTIONS],
-  });
-
-  const branch_state: Partial<BranchStateRuntime> = {};
-  BRANCH_OPTIONS.forEach((value) => {
-    const cli_value = parsed[value];
-    if (cli_value) {
-      const str = (value === "branch-version"
-        ? "version"
-        : value.replace("-", "_")) as keyof BranchStateRuntime;
-      if (str === "checkout")
-        branch_state[str] =
-          (cli_value as "worktree" | "branch" | undefined) ?? "branch";
-      else branch_state[str] = cli_value;
-    }
-  });
-
-  return {
-    help: parsed["help"] === true,
-    version: parsed["version"] === true,
-    git_args: get_git_args(parsed["git-dir"], parsed["work-tree"]),
-    no_interactive: parsed["interactive"] === false,
-    dry_run: parsed["dry-run"] === true,
-    branch_state: branch_state,
-  };
-}
-
-function get_git_args(
-  git_dir: string | undefined,
-  work_tree: string | undefined,
-): string {
-  return `${git_dir ? `--git-dir=${git_dir}` : ""} ${work_tree ? `--work-tree=${work_tree}` : ""}`.trim();
-}