new-branch 0.6.0 → 0.8.0

package/dist/config/sources/rc.loader.js

@@ -1,10 +1,25 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+/** Default filename for the RC configuration file. */
 export const RC_FILENAME = ".newbranchrc.json";
+/**
+ * Type guard for Node.js filesystem errors with a `code` property.
+ *
+ * @param e - The caught error value.
+ * @returns `true` if `e` has a `code` property.
+ */
 function isNodeFsError(e) {
     return typeof e === "object" && e !== null && "code" in e;
 }
+/**
+ * Config loader that reads from a `.newbranchrc.json` file in the
+ * current working directory.
+ *
+ * @remarks
+ * Returns `found: false` when the RC file does not exist.
+ * Throws for any other filesystem or JSON parse error.
+ */
 export const rcLoader = {
     source: "rc",
     async load() {

package/dist/config/types.js

@@ -1,8 +1,10 @@
 /**
- * @fileoverview
- * Core types for `new-branch` configuration system.
+ * @module config/types
  *
- * Naming consistency:
- * Always use `new-branch` (never `newBranch` or `newbranch`).
+ * Core types for the `new-branch` configuration system.
+ *
+ * @remarks
+ * Naming consistency: always use `new-branch`
+ * (never `newBranch` or `newbranch`).
  */
 export {};

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");
@@ -48,6 +90,21 @@ export function validateProjectConfigSource(raw, source) {
         invariant(isString(obj.defaultType), source, "defaultType must be a string");
         cfg.defaultType = trimOrUndefined(obj.defaultType);
     }
+    if ("patterns" in obj) {
+        const patternsVal = obj.patterns;
+        invariant(isObject(patternsVal), source, "patterns must be an object");
+        const entries = Object.entries(patternsVal);
+        const normalized = {};
+        for (const [key, val] of entries) {
+            invariant(isString(val), source, `patterns["${key}"] must be a string`);
+            const trimmed = trimOrUndefined(val);
+            invariant(trimmed, source, `patterns["${key}"] cannot be empty`);
+            normalized[key] = trimmed;
+        }
+        if (Object.keys(normalized).length > 0) {
+            cfg.patterns = normalized;
+        }
+    }
     if ("types" in obj) {
         const typesVal = obj.types;
         invariant(Array.isArray(typesVal), source, "types must be an array");
@@ -56,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

@@ -0,0 +1,94 @@
+/**
+ * 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 = [];
+    lines.push("Pipeline explanation:\n");
+    // 1. Pattern
+    lines.push(`  Pattern:        ${input.pattern}`);
+    lines.push(`  Pattern source: ${input.patternSource}`);
+    // 2. Variables used
+    const vars = input.ast.variablesUsed;
+    lines.push(`\n  Variables used:  ${vars.length > 0 ? vars.join(", ") : "(none)"}`);
+    // 3. Builtin values
+    const builtinEntries = Object.entries(input.builtinValues).filter(([, v]) => v !== undefined);
+    if (builtinEntries.length > 0) {
+        lines.push(`\n  Builtin values:`);
+        for (const [k, v] of builtinEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 4. Git values
+    const gitEntries = Object.entries(input.gitValues).filter(([, v]) => v !== undefined);
+    if (gitEntries.length > 0) {
+        lines.push(`\n  Git values:`);
+        for (const [k, v] of gitEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 5. CLI values
+    const cliEntries = Object.entries(input.cliValues).filter(([, v]) => v !== undefined);
+    if (cliEntries.length > 0) {
+        lines.push(`\n  CLI values:`);
+        for (const [k, v] of cliEntries) {
+            lines.push(`    ${k} = "${v}"`);
+        }
+    }
+    // 6. Transforms applied — with intermediate values
+    const transformNodes = input.ast.nodes.filter((n) => n.kind === "variable" && n.transforms.length > 0);
+    if (transformNodes.length > 0) {
+        lines.push(`\n  Transforms applied:`);
+        for (const node of transformNodes) {
+            if (node.kind !== "variable")
+                continue;
+            const initial = input.resolvedValues[node.name] ?? "";
+            lines.push(`    {${node.name}} = "${initial}"`);
+            let current = initial;
+            for (const t of node.transforms) {
+                const fn = input.transforms[t.name];
+                if (fn) {
+                    current = fn(current, t.args);
+                }
+                const argsStr = t.args.length > 0 ? `:${t.args.join(":")}` : "";
+                lines.push(`      → ${t.name}${argsStr} → "${current}"`);
+            }
+        }
+    }
+    // 7. Final result
+    lines.push(`\n  Rendered:       ${input.rendered}`);
+    if (input.rendered !== input.sanitized) {
+        lines.push(`  Sanitized:      ${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

@@ -0,0 +1,25 @@
+/**
+ * Formats a human-readable table of all available transforms.
+ *
+ * @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 = [];
+    lines.push("Available transforms:\n");
+    const maxName = Math.max(...transforms.map((t) => t.name.length));
+    for (const t of transforms) {
+        const name = t.name.padEnd(maxName + 2);
+        const summary = t.doc?.summary ?? "(no description)";
+        const usage = t.doc?.usage?.[0] ?? "";
+        lines.push(`  ${name}${summary}`);
+        if (usage) {
+            lines.push(`  ${"".padEnd(maxName + 2)}Example: ${usage}`);
+        }
+    }
+    return lines.join("\n");
+}

package/dist/didactic/printConfig.js

@@ -0,0 +1,28 @@
+/**
+ * Formats the resolved project configuration for display.
+ *
+ * @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 = [];
+    lines.push("Resolved configuration:\n");
+    lines.push(`  Source:       ${source}`);
+    lines.push(`  Pattern:      ${config.pattern ?? "(not set)"}`);
+    lines.push(`  Default type: ${config.defaultType ?? "(not set)"}`);
+    if (config.types && config.types.length > 0) {
+        lines.push(`  Types:`);
+        for (const t of config.types) {
+            lines.push(`    - ${t.value} (${t.label})`);
+        }
+    }
+    else {
+        lines.push(`  Types:        (not configured)`);
+    }
+    return lines.join("\n");
+}

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]));
@@ -9,3 +24,40 @@ export async function getGitConfig(key) {
         return undefined;
     }
 }
+/**
+ * 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
+ * ```ts
+ * const entries = await getGitConfigRegexp("^new-branch\\.patterns\\.");
+ * // => [["new-branch.patterns.hotfix", "hotfix/{id}"], ...]
+ * ```
+ */
+export async function getGitConfigRegexp(pattern) {
+    try {
+        const { stdout } = (await execa("git", ["config", "--get-regexp", pattern]));
+        const raw = String(stdout ?? "").trim();
+        if (!raw.length)
+            return [];
+        return raw.split("\n").reduce((acc, line) => {
+            const idx = line.indexOf(" ");
+            if (idx === -1)
+                return acc;
+            const key = line.slice(0, idx);
+            const value = line.slice(idx + 1);
+            if (key && value)
+                acc.push([key, value]);
+            return acc;
+        }, []);
+    }
+    catch {
+        return [];
+    }
+}

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 {