better-commits 1.20.0-cli-flags → 1.20.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.