new-branch 0.7.0 → 0.8.0

package/dist/config/validate.js

@@ -1,29 +1,61 @@
 /**
- * @fileoverview
- * Validation + normalization logic for `new-branch` configuration.
+ * @module config/validate
  *
- * Strategy:
- * 1) validateProjectConfigSource → structural validation per source
- * 2) validateProjectConfigFinal → cross-field business rules
+ * Validation and normalisation logic for `new-branch` configuration.
+ *
+ * @remarks
+ * The validation pipeline consists of two stages:
+ * 1. {@link validateProjectConfigSource} — structural validation per source.
+ * 2. {@link validateProjectConfigFinal} — cross-field business rules.
  */
 /**
- * Throws a standardized configuration error.
+ * Throws a standardised configuration error when `condition` is falsy.
+ *
+ * @param condition - The value to assert.
+ * @param source    - Label identifying the config source (for error messages).
+ * @param message   - Human-readable description of the violated rule.
  */
 function invariant(condition, source, message) {
     if (!condition) {
         throw new Error(`Invalid new-branch config from ${source}: ${message}`);
     }
 }
+/**
+ * Checks whether `v` is a non-null object.
+ *
+ * @param v - The value to check.
+ * @returns `true` if `v` is an object and not `null`.
+ */
 function isObject(v) {
     return typeof v === "object" && v !== null;
 }
+/**
+ * Type guard for strings.
+ *
+ * @param v - The value to check.
+ * @returns `true` if `v` is a `string`.
+ */
 function isString(v) {
     return typeof v === "string";
 }
+/**
+ * Trims a string and returns `undefined` when the result is empty.
+ *
+ * @param v - The string to trim.
+ * @returns The trimmed string, or `undefined` if blank.
+ */
 function trimOrUndefined(v) {
     const t = v.trim();
     return t.length > 0 ? t : undefined;
 }
+/**
+ * Normalises a raw branch-type entry into a validated {@link BranchType}.
+ *
+ * @param raw    - The unknown value to normalise.
+ * @param source - Config source label (for error messages).
+ * @returns A valid {@link BranchType}.
+ * @throws {@link Error} If `value` or `label` is missing/empty.
+ */
 function normalizeBranchType(raw, source) {
     invariant(isObject(raw), source, "types[] must be an object");
     const obj = raw;
@@ -34,7 +66,17 @@ function normalizeBranchType(raw, source) {
     return { value, label };
 }
 /**
- * Structural validation for a single source.
+ * Performs structural validation for a single configuration source.
+ *
+ * @remarks
+ * Validates shapes but does **not** check cross-field rules
+ * (e.g. `defaultType` existing in `types`). Use
+ * {@link validateProjectConfigFinal} for that.
+ *
+ * @param raw    - The raw config object to validate.
+ * @param source - Config source label (for error messages).
+ * @returns A validated {@link ProjectConfig}.
+ * @throws {@link Error} On any structural violation.
  */
 export function validateProjectConfigSource(raw, source) {
     invariant(isObject(raw), source, "config must be an object");
@@ -71,7 +113,18 @@ export function validateProjectConfigSource(raw, source) {
     return cfg;
 }
 /**
- * Final cross-field validation.
+ * Performs cross-field (semantic) validation on an already-structurally-valid config.
+ *
+ * @remarks
+ * Rules enforced:
+ * - `types`, when present, must not be empty.
+ * - `defaultType`, when present alongside `types`, must match one of
+ *   the declared type values.
+ *
+ * @param cfg    - The structurally-valid config to check.
+ * @param source - Config source label (for error messages).
+ * @returns The same config if all rules pass.
+ * @throws {@link Error} On any semantic violation.
  */
 export function validateProjectConfigFinal(cfg, source) {
     if (cfg.types) {

package/dist/didactic/explain.js

@@ -1,8 +1,24 @@
 /**
- * Produces a structured breakdown of the full branch-name pipeline.
+ * Produces a structured, human-readable breakdown of the full
+ * branch-name pipeline.
  *
+ * @remarks
  * No branch is created — this is purely informational.
  * Used by the `--explain` CLI flag.
+ *
+ * Sections printed:
+ * 1. Pattern and source
+ * 2. Variables used
+ * 3. Builtin values
+ * 4. Git values
+ * 5. CLI values
+ * 6. Transform chain with intermediate values
+ * 7. Rendered / Sanitized output
+ * 8. Max-length truncation (when applicable)
+ * 9. Final branch name
+ *
+ * @param input - The collected pipeline data.
+ * @returns A multi-line string ready to be printed to stdout.
  */
 export function explain(input) {
     const lines = [];
@@ -62,6 +78,17 @@ export function explain(input) {
     if (input.rendered !== input.sanitized) {
         lines.push(`  Sanitized:      ${input.sanitized}`);
     }
-    lines.push(`\n  Final branch:   ${input.sanitized}`);
+    // 8. Max-length truncation
+    if (input.maxLength !== undefined) {
+        lines.push(`  Max length:     ${input.maxLength}`);
+        if (input.truncated !== undefined && input.truncated !== input.sanitized) {
+            lines.push(`  Truncated:      ${input.truncated}`);
+        }
+        else {
+            lines.push(`  Truncated:      (no truncation needed)`);
+        }
+    }
+    const finalName = input.truncated ?? input.sanitized;
+    lines.push(`\n  Final branch:   ${finalName}`);
     return lines.join("\n");
 }

package/dist/didactic/listTransforms.js

@@ -1,8 +1,12 @@
 /**
- * Prints a formatted table of all available transforms.
+ * Formats a human-readable table of all available transforms.
  *
- * Each transform is listed with its name, summary and usage example.
- * This is used by the `--list-transforms` CLI flag.
+ * @remarks
+ * Each transform is listed with its name, summary, and an optional
+ * usage example. Used by the `--list-transforms` CLI flag.
+ *
+ * @param transforms - The ordered list of {@link TransformDef} definitions.
+ * @returns A multi-line formatted string ready to be printed to stdout.
  */
 export function listTransforms(transforms) {
     const lines = [];

package/dist/didactic/printConfig.js

@@ -1,8 +1,13 @@
 /**
- * Formats the resolved configuration for display.
+ * Formats the resolved project configuration for display.
  *
- * Shows the final resolved values from whichever source took precedence.
- * This is used by the `--print-config` CLI flag.
+ * @remarks
+ * Shows the final resolved values from whichever source took
+ * precedence. Used by the `--print-config` CLI flag.
+ *
+ * @param config - The resolved {@link ProjectConfig}.
+ * @param source - Human-readable label identifying the winning source.
+ * @returns A multi-line formatted string ready to be printed to stdout.
  */
 export function printConfig(config, source) {
     const lines = [];

package/dist/git/createBranch.js

@@ -2,11 +2,18 @@ import { execa } from "execa";
 /**
  * Creates and switches to a new Git branch.
  *
- * Strategy:
+ * @remarks
+ * Uses a two-step strategy for maximum compatibility:
  * 1. Try `git switch -c <name>` (modern Git ≥ 2.23).
- * 2. Fallback to `git checkout -b <name>` if switch is unavailable.
+ * 2. Fallback to `git checkout -b <name>` if `switch` is unavailable.
  *
- * @throws Error if branch creation fails.
+ * @param name - The name of the branch to create.
+ * @throws {@link Error} If both `git switch -c` and `git checkout -b` fail.
+ *
+ * @example
+ * ```ts
+ * await createBranch("feat/my-feature");
+ * ```
  */
 export async function createBranch(name) {
     try {

package/dist/git/gitBuiltins.js

@@ -1,5 +1,8 @@
 import { getGitConfig } from "../git/gitConfig.js";
 import { execa } from "execa";
+/**
+ * Ordered list of all supported {@link GitBuiltinKey} values.
+ */
 export const GIT_BUILTIN_KEYS = [
     "shortSha",
     "currentBranch",
@@ -7,12 +10,30 @@ export const GIT_BUILTIN_KEYS = [
     "repoName",
     "lastTag",
 ];
+/**
+ * Deduplicates an array of {@link GitBuiltinKey} values.
+ *
+ * @param keys - Array of keys that may contain duplicates.
+ * @returns A new array with unique keys only.
+ */
 function uniqueKeys(keys) {
     return Array.from(new Set(keys));
 }
+/**
+ * Returns the requested keys, or all supported keys when none are specified.
+ *
+ * @param keys - Optional subset of keys to resolve.
+ * @returns The keys to resolve (deduplicated).
+ */
 function pickAllKeysIfUndefined(keys) {
     return keys?.length ? uniqueKeys(keys) : GIT_BUILTIN_KEYS;
 }
+/**
+ * Executes a git command and returns its trimmed stdout, or `undefined` on failure.
+ *
+ * @param args - Arguments to pass to the `git` command.
+ * @returns The trimmed stdout output, or `undefined` if the command fails or produces no output.
+ */
 async function safeExec(args) {
     try {
         const { stdout } = (await execa("git", args));
@@ -23,10 +44,23 @@ async function safeExec(args) {
         return undefined;
     }
 }
+/**
+ * Derives the repository name from the absolute path to the repo root.
+ *
+ * @param repoRoot - Absolute path returned by `git rev-parse --show-toplevel`.
+ * @returns The last segment of the path, or `undefined` if the path is empty.
+ */
 function deriveRepoName(repoRoot) {
     const parts = repoRoot.split(/[\\/]/).filter(Boolean);
     return parts.length ? parts[parts.length - 1] : undefined;
 }
+/**
+ * Resolver map for each supported {@link GitBuiltinKey}.
+ *
+ * @remarks
+ * Each resolver is an async function that returns the resolved value
+ * or `undefined` when unavailable.
+ */
 const RESOLVERS = {
     shortSha: () => safeExec(["rev-parse", "--short", "HEAD"]),
     currentBranch: async () => {
@@ -43,6 +77,12 @@ const RESOLVERS = {
         return value ?? process.env.USER ?? process.env.USERNAME ?? undefined;
     },
 };
+/**
+ * Internal resolver that resolves the requested git builtin keys in parallel.
+ *
+ * @param keys - Optional subset of keys to resolve. When omitted, all keys are resolved.
+ * @returns An object containing the resolved values.
+ */
 async function resolveGitBuiltins(keys) {
     const wanted = pickAllKeysIfUndefined(keys);
     const entries = await Promise.all(wanted.map(async (key) => {
@@ -57,22 +97,49 @@ async function resolveGitBuiltins(keys) {
 /**
  * Resolves git-based built-in variables.
  *
- * - If `keys` is omitted, resolves all supported git builtins.
- * - If `keys` is provided, resolves only those keys.
+ * @remarks
+ * Each variable maps to a git command executed in the current repository.
+ * Resolution is done in parallel for performance.
+ *
+ * @param keys - Optional subset of {@link GitBuiltinKey} values to resolve.
+ *   When omitted, all supported git builtins are resolved.
+ * @returns A promise resolving to a {@link GitBuiltins} object.
+ *
+ * @example
+ * ```ts
+ * // Resolve only what is needed
+ * const builtins = await getGitBuiltins(["shortSha", "currentBranch"]);
+ * builtins.shortSha;       // "abc1234"
+ * builtins.currentBranch;  // "main"
+ * ```
  */
 export async function getGitBuiltins(keys) {
     return resolveGitBuiltins(keys);
 }
 /**
- * Returns true if the pattern contains at least one git builtin key.
- * (Call this before `getGitBuiltins()` if you want to avoid running git at all.)
+ * Checks whether a pattern string references at least one git builtin key.
+ *
+ * @remarks
+ * Use this before calling {@link getGitBuiltins} to avoid spawning
+ * unnecessary git subprocesses.
+ *
+ * @param pattern - The raw pattern string to check.
+ * @returns `true` if the pattern contains at least one {@link GitBuiltinKey}.
  */
 export function patternNeedsGitBuiltins(pattern) {
     return GIT_BUILTIN_KEYS.some((key) => pattern.includes(key));
 }
 /**
- * Extracts which git builtin keys are present in the pattern.
- * (Use the returned keys to resolve only what you need.)
+ * Extracts which {@link GitBuiltinKey} values are present in a pattern.
+ *
+ * @param pattern - The raw pattern string to inspect.
+ * @returns An array of {@link GitBuiltinKey} values found in the pattern.
+ *
+ * @example
+ * ```ts
+ * extractGitBuiltinKeysFromPattern("{currentBranch}-{shortSha}");
+ * // => ["shortSha", "currentBranch"]
+ * ```
  */
 export function extractGitBuiltinKeysFromPattern(pattern) {
     return GIT_BUILTIN_KEYS.filter((key) => pattern.includes(key));

package/dist/git/gitConfig.js

@@ -1,4 +1,19 @@
 import { execa } from "execa";
+/**
+ * Retrieves a single Git config value by key.
+ *
+ * @remarks
+ * Runs `git config --get <key>` as a subprocess. Returns `undefined`
+ * when the key is not set or the command fails (e.g. outside a repo).
+ *
+ * @param key - The Git config key to look up (e.g. `"user.name"`).
+ * @returns The trimmed config value, or `undefined` if not found.
+ *
+ * @example
+ * ```ts
+ * const name = await getGitConfig("user.name"); // "Alice" | undefined
+ * ```
+ */
 export async function getGitConfig(key) {
     try {
         const { stdout } = (await execa("git", ["config", "--get", key]));
@@ -10,11 +25,20 @@ export async function getGitConfig(key) {
     }
 }
 /**
- * Returns all git config entries matching a key prefix using `--get-regexp`.
- * Each entry is returned as a `[key, value]` tuple.
+ * Returns all git config entries matching a key pattern using `--get-regexp`.
+ *
+ * @remarks
+ * Each entry is returned as a `[key, value]` tuple. Returns an empty
+ * array if no entries match or if the command fails.
+ *
+ * @param pattern - A regular expression pattern passed to `git config --get-regexp`.
+ * @returns An array of `[key, value]` tuples.
  *
- * Example: `getGitConfigRegexp("new-branch.patterns\\.")` returns
- * `[["new-branch.patterns.hotfix", "hotfix/{id}"], ...]`
+ * @example
+ * ```ts
+ * const entries = await getGitConfigRegexp("^new-branch\\.patterns\\.");
+ * // => [["new-branch.patterns.hotfix", "hotfix/{id}"], ...]
+ * ```
  */
 export async function getGitConfigRegexp(pattern) {
     try {

package/dist/git/sanitizeGitRef.js

@@ -1,10 +1,28 @@
 /**
- * Performs a lightweight sanitization before delegating
- * full validation to Git.
+ * Performs a lightweight sanitization of a Git ref name.
  *
- * This does NOT try to fully reimplement Git rules.
- * Final validation must be done via:
- *   git check-ref-format --branch
+ * @remarks
+ * This function applies a set of heuristic cleanups to make the input
+ * more likely to pass `git check-ref-format --branch`. It does **not**
+ * fully reimplement all Git ref rules — final validation must still be
+ * delegated to Git itself via {@link validateBranchName}.
+ *
+ * Sanitization steps:
+ * 1. Trim whitespace and replace internal whitespace with `-`.
+ * 2. Remove characters forbidden by Git (`~ ^ : ? * [ ] \`).
+ * 3. Remove `@{` sequences.
+ * 4. Collapse multiple slashes and repeated dots.
+ * 5. Strip leading dashes/slashes and trailing slashes/dots.
+ * 6. Remove `.lock` suffix.
+ *
+ * @param input - The raw ref name to sanitize.
+ * @returns The sanitized ref name.
+ *
+ * @example
+ * ```ts
+ * sanitizeGitRef("feat/My Feature!!"); // => "feat/My-Feature"
+ * sanitizeGitRef("--leading/slash");   // => "leading/slash"
+ * ```
  */
 export function sanitizeGitRef(input) {
     let name = input.trim();

package/dist/git/truncateEnd.js

@@ -0,0 +1,31 @@
+/**
+ * Truncates a string from the end to ensure it does not exceed `maxLength`.
+ *
+ * @remarks
+ * This is intentionally simple and deterministic:
+ * - If the string length is `<= maxLength`, return it unchanged.
+ * - Otherwise, cut from the end.
+ *
+ * Used by the `--max-length` CLI option after sanitization and before
+ * branch-name validation.
+ *
+ * @param value - The string to truncate.
+ * @param maxLength - The maximum allowed length. Must be a positive integer (`>= 1`).
+ * @returns The (possibly truncated) string.
+ * @throws {@link Error} If `maxLength` is not a positive integer.
+ *
+ * @example
+ * ```ts
+ * truncateEnd("feat/my-feature", 10); // => "feat/my-fe"
+ * truncateEnd("short", 100);          // => "short"
+ * ```
+ */
+export function truncateEnd(value, maxLength) {
+    if (!Number.isInteger(maxLength) || maxLength < 1) {
+        throw new Error(`--max-length must be a positive integer (>= 1), got "${maxLength}".`);
+    }
+    if (value.length <= maxLength) {
+        return value;
+    }
+    return value.slice(0, maxLength);
+}

package/dist/git/validateBranchName.js

@@ -2,10 +2,19 @@ import { execa } from "execa";
 /**
  * Validates a branch name by delegating to Git itself.
  *
- * Uses:
- *   git check-ref-format --branch <name>
+ * @remarks
+ * Invokes `git check-ref-format --branch <name>` as a subprocess.
+ * This ensures the name complies with all rules enforced by the
+ * installed version of Git.
  *
- * Throws if invalid.
+ * @param name - The branch name to validate.
+ * @throws {@link Error} If the branch name does not pass `git check-ref-format`.
+ *
+ * @example
+ * ```ts
+ * await validateBranchName("feat/my-branch"); // resolves
+ * await validateBranchName("..");              // throws
+ * ```
  */
 export async function validateBranchName(name) {
     try {

package/dist/parseArgs.js

@@ -1,4 +1,18 @@
+/**
+ * @module parseArgs
+ *
+ * CLI argument parser built on top of {@link https://github.com/cacjs/cac | cac}.
+ * Defines every flag accepted by `new-branch` and coerces raw `process.argv`
+ * values into a strongly-typed {@link ParsedArgs} object.
+ */
 import { cac } from "cac";
+/**
+ * Remove the bare `"--"` separator from an argv array so that `cac` does not
+ * choke on it. Everything before and after the separator is preserved.
+ *
+ * @param argv - Raw argument vector (typically `process.argv`).
+ * @returns A new array with the `"--"` element removed, if present.
+ */
 function stripDoubleDash(argv) {
     const idx = argv.indexOf("--");
     if (idx === -1)
@@ -6,6 +20,24 @@ function stripDoubleDash(argv) {
     // keep node + script, remove the "--" separator and retain the rest
     return [...argv.slice(0, idx), ...argv.slice(idx + 1)];
 }
+/**
+ * Parse a raw argument vector into a typed {@link ParsedArgs} object.
+ *
+ * @remarks
+ * String-like option values are coerced via `String()` and numeric ones via
+ * `Number()`, so callers always receive the expected primitive types regardless
+ * of how the shell delivers them.
+ *
+ * @param argv - The argument vector to parse (defaults to `process.argv`).
+ * @returns Parsed and coerced CLI arguments.
+ *
+ * @example
+ * ```ts
+ * const { options } = parseArgs(["node", "new-branch", "--type", "feat", "--id", "42"]);
+ * // options.type === "feat"
+ * // options.id   === "42"
+ * ```
+ */
 export function parseArgs(argv = process.argv) {
     const cli = cac("new-branch");
     cli
@@ -20,6 +52,7 @@ export function parseArgs(argv = process.argv) {
         .option("--explain", "Show a detailed breakdown of the branch pipeline without creating a branch")
         .option("--list-transforms", "List all available transforms")
         .option("--print-config", "Print the resolved configuration")
+        .option("-L, --max-length <n>", "Maximum length for the final branch name")
         .help();
     const cleaned = stripDoubleDash(argv);
     const parsed = cli.parse(cleaned);
@@ -40,6 +73,7 @@ export function parseArgs(argv = process.argv) {
         explain: typeof opts.explain === "boolean" ? opts.explain : undefined,
         listTransforms: typeof opts.listTransforms === "boolean" ? opts.listTransforms : undefined,
         printConfig: typeof opts.printConfig === "boolean" ? opts.printConfig : undefined,
+        maxLength: opts.maxLength !== undefined ? Number(opts.maxLength) : undefined,
     };
     return {
         options,

package/dist/pattern/parsePattern.js

@@ -121,6 +121,14 @@ export function parsePattern(input) {
         variablesUsed: uniquePreserveOrder(variablesUsed),
     };
 }
+/**
+ * Parses a single transform segment like `"slugify"` or `"max:25"`
+ * into a {@link TransformNode}.
+ *
+ * @param segment - The raw transform string (e.g. `"replace:_:-"`).
+ * @returns The parsed {@link TransformNode}.
+ * @throws {@link Error} If the segment is empty or has no name.
+ */
 function parseTransform(segment) {
     // segment examples:
     // - "slugify"
@@ -134,6 +142,12 @@ function parseTransform(segment) {
     }
     return { name, args };
 }
+/**
+ * Deduplicates a string array while preserving the original order.
+ *
+ * @param items - The array of strings to deduplicate.
+ * @returns A new array containing only the first occurrence of each item.
+ */
 function uniquePreserveOrder(items) {
     const seen = new Set();
     const out = [];

package/dist/pattern/transforms/after.js

@@ -1,3 +1,18 @@
+/**
+ * Transform: **after**
+ *
+ * @remarks
+ * Appends a suffix to the value. If the value is empty, returns
+ * an empty string (the suffix is not added to avoid dangling separators).
+ *
+ * Pattern syntax: `{variable:after:suffix}`
+ *
+ * @example
+ * ```ts
+ * after.fn("feat", ["-wip"]); // => "feat-wip"
+ * after.fn("", ["-wip"]);     // => ""
+ * ```
+ */
 export const after = {
     name: "after",
     fn: (value, [suffix]) => {

package/dist/pattern/transforms/before.js

@@ -1,3 +1,18 @@
+/**
+ * Transform: **before**
+ *
+ * @remarks
+ * Prepends a prefix to the value. If the value is empty, returns
+ * an empty string (the prefix is not added to avoid dangling separators).
+ *
+ * Pattern syntax: `{variable:before:prefix}`
+ *
+ * @example
+ * ```ts
+ * before.fn("fix", ["hotfix-"]); // => "hotfix-fix"
+ * before.fn("", ["hotfix-"]);    // => ""
+ * ```
+ */
 export const before = {
     name: "before",
     fn: (value, [prefix]) => {

package/dist/pattern/transforms/camel.js

@@ -1,14 +1,20 @@
 import { splitWords, upperFirst } from "./helpers/words.js";
 /**
- * Transform: camel
+ * Transform: **camel**
  *
- * Converts an input string into camelCase. Uses `splitWords` to extract word
- * boundaries and lower-cases the words before joining. The first word is kept
- * in lower-case; subsequent words are capitalized using `upperFirst`.
+ * @remarks
+ * Converts an input string into camelCase. Uses {@link splitWords} to
+ * extract word boundaries and lower-cases the words before joining.
+ * The first word is kept in lower-case; subsequent words are
+ * capitalised with {@link upperFirst}.
  *
- * Examples:
- * - "My Task" -> "myTask"
- * - "HTTP Server" -> "httpServer"
+ * Pattern syntax: `{variable:camel}`
+ *
+ * @example
+ * ```ts
+ * camel.fn("My Task", []);     // => "myTask"
+ * camel.fn("HTTP Server", []); // => "httpServer"
+ * ```
  */
 export const camel = {
     name: "camel",

package/dist/pattern/transforms/helpers/words.js

@@ -1,3 +1,9 @@
+/**
+ * @module helpers/words
+ *
+ * Word-splitting utilities used by case-conversion transforms
+ * (camel, kebab, snake, title, etc.).
+ */
 /**
  * Splits an input string into word-like segments.
  *

package/dist/pattern/transforms/ifEmpty.js

@@ -1,3 +1,18 @@
+/**
+ * Transform: **ifEmpty**
+ *
+ * @remarks
+ * Provides a fallback value when the current value is an empty string.
+ * Useful for guaranteeing a non-empty segment in the branch name.
+ *
+ * Pattern syntax: `{variable:ifEmpty:fallback}`
+ *
+ * @example
+ * ```ts
+ * ifEmpty.fn("", ["no-title"]);    // => "no-title"
+ * ifEmpty.fn("hello", ["unused"]); // => "hello"
+ * ```
+ */
 export const ifEmpty = {
     name: "ifEmpty",
     fn: (value, [fallback]) => {