new-branch 0.6.0 → 0.8.0

package/README.md

@@ -4,28 +4,19 @@
   <img src="./logo.svg" width="180" alt="new-branch logo" />
 </p>
 
-> “Explicit is better than implicit.”
-> — The Zen of Python (PEP 20)
-
-A composable CLI to generate and optionally create standardized Git branch names using a pattern + transform pipeline.
+A composable CLI to generate and create standardized Git branch names using a pattern + transform pipeline.
 
 ![demo](./demo.gif)
 
 [![CI](https://github.com/teles/new-branch/actions/workflows/ci.yml/badge.svg)](https://github.com/teles/new-branch/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/teles/new-branch/branch/main/graph/badge.svg)](https://codecov.io/gh/teles/new-branch)
 
----
-
-## Why
-
-Keep branch names consistent across your team using a declarative pattern language.
+📖 **[Full Documentation](https://teles.github.io/new-branch/)**
 
 ---
 
 ## Install
 
-Run without installing:
-
 ```bash
 npx new-branch
 ```
@@ -36,227 +27,54 @@ Or install globally:
 npm install -g new-branch
 ```
 
----
-
-## Usage
-
-Generate a branch name:
+## Quick Start
 
 ```bash
 new-branch \
   --pattern "{type}/{title:slugify;max:25}-{id}" \
   --type feat \
-  --title "My task" \
-  --id STK-123
-```
-
-Create the branch automatically:
-
-```bash
-new-branch \
-  --pattern "{type}/{title:slugify}-{id}" \
-  --type feat \
-  --title "My task" \
-  --id STK-123 \
+  --title "Add login page" \
+  --id PROJ-123 \
   --create
 ```
 
----
-
-## Pattern Language
-
-Patterns are composed of variables and ordered transforms.
-
-Example:
-
-```
-{type}/{title:slugify;max:25}-{id}
-```
-
-### Syntax
-
 ```
-{variable:transform1;transform2:arg}
+✅ Branch created and switched to: feat/add-login-page-PROJ-123
 ```
 
-- Variables are wrapped in `{}`
-- Transforms run left-to-right
-- Multiple transforms are separated by `;`
-- Transform arguments use `:`
-
----
-
-## Built-in Variables
-
-### Core Variables
-
-- `type`
-- `title`
-- `id`
-
-### Date Built-ins (derived from local system time)
-
-- `year` → YYYY
-- `month` → MM (zero padded)
-- `day` → DD (zero padded)
-- `date` → YYYY-MM-DD
-- `dateCompact` → YYYYMMDD
-
-### Git Built-ins (derived from current Git repository)
-
-- `currentBranch` → Current Git branch name (e.g. `main`, `feature/PROJ-123`)
-- `shortSha` → Short SHA of `HEAD` (e.g. `a1b2c3d`)
-- `repoName` → Repository directory name
-- `userName` → Git user name (`git config user.name`)
-- `lastTag` → Most recent Git tag (`git describe --tags --abbrev=0`)
-
-> Note:
->
-> - Git built-ins are resolved lazily and only when referenced in the pattern.
-> - They are never prompted interactively.
-> - When unavailable (e.g. outside a Git repository), they resolve to an empty string.
-
-#### Example with Git built-ins
-
-```bash
-new-branch \
-  --pattern "{currentBranch}-{shortSha}-{type}-{title:slugify}" \
-  --type feat \
-  --title "Improve logging"
-```
-
-Example output:
-
-```
-main-a1b2c3d-feat-improve-logging
-```
-
----
-
-## Built-in Transforms
-
-| Transform | Description                |
-| --------- | -------------------------- |
-| `slugify` | Convert to URL-safe slug   |
-| `lower`   | Convert to lowercase       |
-| `upper`   | Convert to uppercase       |
-| `camel`   | Convert to camelCase       |
-| `kebab`   | Convert to kebab-case      |
-| `snake`   | Convert to snake_case      |
-| `title`   | Convert to Title Case      |
-| `words:n` | Keep at most `n` words     |
-| `max:n`   | Truncate to `n` characters |
-
-All transforms are pure functions and composable.
-
----
-
-## Interactive Mode
-
-If variables referenced by the pattern are missing, the CLI prompts for them by default.
-
-Disable prompts with:
-
-```bash
---no-prompt
-```
-
----
-
-## CLI Options
-
-| Option                    | Description                         |
-| ------------------------- | ----------------------------------- |
-| `-p, --pattern <pattern>` | Branch pattern                      |
-| `--type <type>`           | Branch type                         |
-| `--title <title>`         | Task title                          |
-| `--id <id>`               | Task identifier                     |
-| `--create`                | Create branch using `git switch -c` |
-| `--no-prompt`             | Fail instead of prompting           |
-| `--quiet`                 | Suppress output                     |
-
----
-
-## Project Configuration and precedence
-
-Configuration for `new-branch` may come from several places. The CLI resolves the first _non-empty_ configuration it finds according to the following precedence (highest → lowest):
-
-1. CLI flags (explicit `--pattern`, `--type`, etc.)
-2. `.newbranchrc.json` (a repository-local JSON config file)
-3. `package.json` under the `new-branch` key
-4. Git config (`new-branch.pattern`) — local then global
-5. Interactive prompt (only if enabled and a value is still missing)
-
-This means that if a higher-precedence source provides a non-empty value, lower-precedence sources are not consulted or merged.
-
-Examples
-
-1. `.newbranchrc.json` (preferred when present and non-empty):
+Save your pattern so you don't have to type it every time:
 
 ```json
 {
   "pattern": "{type}/{title:slugify}-{id}",
   "types": [
     { "value": "feat", "label": "Feature" },
-    { "value": "fix", "label": "Fix" }
-  ],
-  "defaultType": "feat"
-}
-```
-
-2. `package.json` fallback:
-
-```json
-{
-  "new-branch": {
-    "pattern": "{type}/{title:slugify}-{id}",
-    "defaultType": "fix"
-  }
+    { "value": "fix", "label": "Bug Fix" }
+  ]
 }
 ```
 
-3. Git config fallback (local takes precedence over global):
-
-```bash
-git config --local new-branch.pattern "{type}/{title:slugify}-{id}"
-git config --global new-branch.pattern "{type}/{title:slugify}-{id}"
-```
-
-Notes about `type` and `defaultType`
-
-- Order for resolving the branch `type` follows the SPEC behavior we implemented:
-  1. CLI `--type` (explicit flag) overrides everything.
-  2. `defaultType` from the selected configuration source is used next (if present).
-  3. If the project config declares exactly one `type` in `types[]`, that single type is used as a convenience.
-  4. If the type is still not resolved and interactive prompting is allowed, the CLI will prompt for it.
-  5. If the type is still missing and `--no-prompt` (or `prompt: false`) is in effect, the CLI will fail with a helpful error.
+## Features
 
-- Validation: when a configuration source provides both `types[]` and `defaultType`, the `defaultType` must match one of the declared `types[].value`. If it does not, configuration validation will surface an error.
+- **Pattern language** — declarative syntax with variables, transforms, and arguments
+- **16 built-in transforms** — `slugify`, `kebab`, `camel`, `max`, `replace`, `stripAccents`, and more
+- **Flexible config** — `.newbranchrc.json`, `package.json`, or `git config`
+- **Pattern aliases** — define named patterns and switch with `--use feature`
+- **Interactive mode** — prompts for missing values, disable with `--no-prompt`
+- **Git safety** — sanitized and validated via `git check-ref-format`
+- **Didactic modes** — `--explain`, `--list-transforms`, `--print-config`
 
-- Interactive prompts: when `types[]` are present in the chosen project config, those entries are exposed as choices to the interactive `type` select prompt so users see and can pick project-defined types.
+## Documentation
 
-To remove the pattern from Git config:
-
-```bash
-# Remove from local repository
-git config --unset --local new-branch.pattern
-
-# Remove from global config
-git config --unset --global new-branch.pattern
-```
-
----
-
-## Git Safety
-
-After rendering, branch names are:
-
-1. Lightly sanitized
-2. Validated via `git check-ref-format --branch`
-
-Invalid names cause the command to fail.
-
----
+| Section                                                                     | Description                          |
+| --------------------------------------------------------------------------- | ------------------------------------ |
+| [Getting Started](https://teles.github.io/new-branch/guide/getting-started) | Installation and first branch        |
+| [Patterns](https://teles.github.io/new-branch/guide/patterns)               | Pattern language syntax and examples |
+| [Transforms](https://teles.github.io/new-branch/guide/transforms)           | All 16 transforms with I/O tables    |
+| [Configuration](https://teles.github.io/new-branch/guide/configuration)     | Config sources and precedence        |
+| [Pattern Aliases](https://teles.github.io/new-branch/guide/pattern-aliases) | Named patterns with `--use`          |
+| [CLI Reference](https://teles.github.io/new-branch/reference/cli-options)   | All flags and options                |
+| [Recipes](https://teles.github.io/new-branch/recipes/github-flow)           | GitHub Flow, Gitflow, Monorepo       |
 
 ## Development
 
@@ -266,8 +84,6 @@ pnpm test:run
 pnpm build
 ```
 
----
-
 ## License
 
 MIT

package/dist/cli.js

@@ -1,25 +1,68 @@
 #!/usr/bin/env node
+/**
+ * @module cli
+ *
+ * Entry point for the `new-branch` CLI.
+ *
+ * @remarks
+ * This module orchestrates the full branch-name pipeline:
+ * pattern → AST → resolve values → render → sanitize →
+ * truncate → validate → (optional) git create → output.
+ */
 import { parseArgs } from "./parseArgs.js";
 import { parsePattern } from "./pattern/parsePattern.js";
-import { defaultTransforms } from "./pattern/transforms/index.js";
+import { allTransforms, defaultTransforms } from "./pattern/transforms/index.js";
 import { renderPattern } from "./pattern/transforms/renderPattern.js";
 import { resolveMissingValues } from "./runtime/resolveMissingValues.js";
 import { getBuiltinValues } from "./runtime/builtins.js";
-import { loadConfig } from "./config/loadConfig.js";
+import { loadConfigWithSource } from "./config/loadConfig.js";
 import { getGitConfig } from "./git/gitConfig.js";
 import { extractGitBuiltinKeysFromPattern, getGitBuiltins, patternNeedsGitBuiltins, } from "./git/gitBuiltins.js";
 import { sanitizeGitRef } from "./git/sanitizeGitRef.js";
+import { truncateEnd } from "./git/truncateEnd.js";
 import { validateBranchName } from "./git/validateBranchName.js";
 import { createBranch } from "./git/createBranch.js";
+import { listTransforms } from "./didactic/listTransforms.js";
+import { printConfig } from "./didactic/printConfig.js";
+import { explain } from "./didactic/explain.js";
+/**
+ * Wraps a value in an {@link Ok} result.
+ *
+ * @typeParam T - Value type.
+ * @param value - The success value.
+ * @returns An `Ok<T>` result.
+ */
 const ok = (value) => ({ ok: true, value });
+/**
+ * Wraps an error in an {@link Err} result.
+ *
+ * @param error - The failure reason.
+ * @returns An `Err` result.
+ */
 const err = (error) => ({ ok: false, error });
+/**
+ * Type-narrowing guard that checks whether `r` is an {@link Ok} result.
+ */
 const isOk = (r) => r.ok;
+/**
+ * Prints an error message and exits the process with code 1.
+ *
+ * @param msg - Human-readable error headline.
+ * @param e   - Optional underlying error to print.
+ */
 function fail(msg, e) {
     console.error(`\n❌ ${msg}`);
     if (e)
         console.error(e);
     process.exit(1);
 }
+/**
+ * Wraps a synchronous function in a {@link Result}.
+ *
+ * @typeParam T - Return type of `fn`.
+ * @param fn - The function to execute.
+ * @returns `Ok<T>` on success, `Err` on thrown exception.
+ */
 function safe(fn) {
     try {
         return ok(fn());
@@ -28,6 +71,13 @@ function safe(fn) {
         return err(e);
     }
 }
+/**
+ * Wraps an asynchronous function in a {@link Result}.
+ *
+ * @typeParam T - Resolved type of the returned promise.
+ * @param fn - The async function to execute.
+ * @returns `Ok<T>` on success, `Err` on rejection.
+ */
 async function safeAsync(fn) {
     try {
         return ok(await fn());
@@ -36,12 +86,25 @@ async function safeAsync(fn) {
         return err(e);
     }
 }
+/**
+ * Validates that a pattern string was provided.
+ *
+ * @param pattern - The resolved pattern string (may be `undefined`).
+ * @returns `Ok<string>` when valid, `Err` when missing or blank.
+ */
 function requirePattern(pattern) {
     if (!pattern || pattern.trim().length === 0) {
         return err(new Error("Pattern is required. Use --pattern to specify it."));
     }
     return ok(pattern);
 }
+/**
+ * Extracts CLI-provided values (`id`, `title`, `type`) from parsed arguments
+ * into a {@link RenderValues} map.
+ *
+ * @param args - The parsed CLI arguments.
+ * @returns A partial {@link RenderValues} map.
+ */
 function toInitialValues(args) {
     return {
         id: args.options.id,
@@ -49,6 +112,25 @@ function toInitialValues(args) {
         type: args.options.type,
     };
 }
+/**
+ * Main CLI entry point.
+ *
+ * @remarks
+ * Orchestrates the full branch-name pipeline:
+ *
+ * 1. Parse and normalise `process.argv`.
+ * 2. Load project configuration (RC / `package.json` / git config).
+ * 3. Resolve the pattern (CLI flag → `--use` alias → config → git config).
+ * 4. Parse the pattern into an AST.
+ * 5. Resolve built-in and git built-in values.
+ * 6. Prompt for any missing values (unless `--no-prompt`).
+ * 7. Render, sanitize, truncate (`--max-length`), and validate.
+ * 8. Optionally create the branch (`--create`).
+ * 9. Print the branch name (unless `--quiet`).
+ *
+ * Didactic modes (`--help`, `--list-transforms`, `--print-config`,
+ * `--explain`) short-circuit the pipeline and return early.
+ */
 export async function run() {
     // Normalize argv so it works consistently across:
     // - node dist/cli.js --id 123
@@ -74,17 +156,52 @@ export async function run() {
     if (wantsHelp) {
         return;
     }
+    // --- Didactic mode: --list-transforms ---
+    if (args.options.listTransforms) {
+        console.log(listTransforms(allTransforms));
+        return;
+    }
     const quiet = args.options.quiet === true;
     const create = args.options.create === true;
     const prompt = args.options.prompt !== false;
+    const isExplain = args.options.explain === true;
     // Pipeline: pattern -> AST -> resolve values -> render -> sanitize -> validate -> (optional) git -> output
-    const projectConfig = await loadConfig();
+    const { config: projectConfig, source: configSource } = await loadConfigWithSource();
+    // --- Didactic mode: --print-config ---
+    if (args.options.printConfig) {
+        console.log(printConfig(projectConfig, configSource));
+        return;
+    }
     // Git config (respects local -> global precedence automatically)
     let gitPattern;
-    if (!args.options.pattern && !projectConfig.pattern) {
+    if (!args.options.pattern && !args.options.use && !projectConfig.pattern) {
         gitPattern = await getGitConfig("new-branch.pattern");
     }
-    const resolvedPattern = args.options.pattern ?? projectConfig.pattern ?? gitPattern;
+    // Resolution logic for --use:
+    // If --pattern is provided, use it directly (highest precedence).
+    // If --use is provided, resolve from patterns config. Error if alias not found.
+    // Otherwise, fall back to configured pattern or git config.
+    let useAliasPattern;
+    if (!args.options.pattern && args.options.use) {
+        const aliasName = args.options.use;
+        const aliasPattern = projectConfig.patterns?.[aliasName];
+        if (!aliasPattern) {
+            fail(`Unknown pattern alias "${aliasName}". Available aliases: ${projectConfig.patterns
+                ? Object.keys(projectConfig.patterns).join(", ")
+                : "(none configured)"}`);
+        }
+        useAliasPattern = aliasPattern;
+    }
+    const resolvedPattern = args.options.pattern ?? useAliasPattern ?? projectConfig.pattern ?? gitPattern;
+    const patternSource = args.options.pattern
+        ? "CLI --pattern"
+        : useAliasPattern
+            ? `CLI --use (${args.options.use})`
+            : projectConfig.pattern
+                ? configSource
+                : gitPattern
+                    ? "git config"
+                    : "(none)";
     const patternRes = requirePattern(resolvedPattern);
     if (!isOk(patternRes))
         fail("Invalid CLI arguments.", patternRes.error);
@@ -135,7 +252,34 @@ export async function run() {
     if (!isOk(renderedRes))
         fail("Failed to render branch name.", renderedRes.error);
     const sanitized = sanitizeGitRef(renderedRes.value);
-    const validateRes = await safeAsync(() => validateBranchName(sanitized));
+    // Apply --max-length truncation (after sanitization, before validation)
+    const maxLength = args.options.maxLength;
+    let finalBranchName = sanitized;
+    if (maxLength !== undefined) {
+        const truncateRes = safe(() => truncateEnd(sanitized, maxLength));
+        if (!isOk(truncateRes))
+            fail("Invalid --max-length value.", truncateRes.error);
+        finalBranchName = truncateRes.value;
+    }
+    // --- Didactic mode: --explain ---
+    if (isExplain) {
+        console.log(explain({
+            pattern: patternRes.value,
+            patternSource,
+            ast: astRes.value,
+            resolvedValues: valuesRes.value,
+            cliValues: toInitialValues(args),
+            builtinValues,
+            gitValues,
+            rendered: renderedRes.value,
+            sanitized,
+            maxLength,
+            truncated: finalBranchName,
+            transforms: defaultTransforms,
+        }));
+        return;
+    }
+    const validateRes = await safeAsync(() => validateBranchName(finalBranchName));
     if (!isOk(validateRes))
         fail("Branch name is not valid for git.", validateRes.error);
     const ctx = {
@@ -145,7 +289,7 @@ export async function run() {
         pattern: patternRes.value,
         ast: astRes.value,
         values: valuesRes.value,
-        branchName: sanitized,
+        branchName: finalBranchName,
     };
     const createRes = create ? await safeAsync(() => createBranch(ctx.branchName)) : ok(undefined);
     if (!isOk(createRes))

package/dist/config/loadConfig.js

@@ -1,31 +1,45 @@
 /**
- * @fileoverview
+ * @module config/loadConfig
+ *
  * Aggregates configuration sources without merging.
  *
- * Precedence:
- * 1) .new-branchrc.json
- * 2) package.json
- * 3) git config
+ * @remarks
+ * Precedence (first-found wins):
+ * 1. `.new-branchrc.json`
+ * 2. `package.json`
+ * 3. `git config`
  */
 import { rcLoader } from "./sources/rc.loader.js";
 import { packageJsonLoader } from "./sources/packageJson.loader.js";
 import { gitLoader } from "./sources/git.loader.js";
 /**
- * Loads the first configuration found.
- * No merging is performed.
+ * Loads the first configuration found across all supported sources.
+ *
+ * @remarks
+ * No merging is performed — the first source that returns a
+ * non-empty config wins.
+ *
+ * @returns The resolved {@link ProjectConfig}.
  */
 export async function loadConfig() {
-    // Load rc loader first and prefer a non-empty config. Avoid calling the
-    // git loader unless necessary because it depends on external git state
-    // and may import modules that are platform-sensitive.
+    const { config } = await loadConfigWithSource();
+    return config;
+}
+/**
+ * Loads the first configuration found and reports which source provided it.
+ *
+ * @returns An object with the resolved {@link ProjectConfig} and a
+ *   human-readable `source` label (e.g. `".newbranchrc.json"`).
+ */
+export async function loadConfigWithSource() {
     const rcRes = await rcLoader.load();
     if (rcRes.found && rcRes.config && Object.keys(rcRes.config).length > 0)
-        return rcRes.config;
+        return { config: rcRes.config, source: ".newbranchrc.json" };
     const pkgRes = await packageJsonLoader.load();
     if (pkgRes.found && pkgRes.config && Object.keys(pkgRes.config).length > 0)
-        return pkgRes.config;
+        return { config: pkgRes.config, source: "package.json" };
     const gitRes = await gitLoader.load();
     if (gitRes.found)
-        return gitRes.config ?? {};
-    return {};
+        return { config: gitRes.config ?? {}, source: "git config" };
+    return { config: {}, source: "(none)" };
 }

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

@@ -1,5 +1,15 @@
-import { getGitConfig } from "../../git/gitConfig.js";
+import { getGitConfig, getGitConfigRegexp } from "../../git/gitConfig.js";
 import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+/**
+ * Parses a comma-separated git config value into {@link BranchType} entries.
+ *
+ * @remarks
+ * Each entry may be either `"value"` (label defaults to value) or
+ * `"value:label"` (colon-separated).
+ *
+ * @param raw - The raw comma-separated string from git config.
+ * @returns An array of {@link BranchType} objects.
+ */
 function parseGitTypes(raw) {
     return raw
         .split(",")
@@ -16,13 +26,44 @@ function parseGitTypes(raw) {
         };
     });
 }
+/** Prefix used for per-alias pattern keys in git config. */
+const PATTERNS_PREFIX = "new-branch.patterns.";
+/**
+ * Converts raw `git config --get-regexp` entries into a patterns map.
+ *
+ * @param entries - Key/value tuples from `getGitConfigRegexp`.
+ * @returns A record of pattern aliases, or `undefined` when empty.
+ */
+function parseGitPatterns(entries) {
+    if (entries.length === 0)
+        return undefined;
+    const result = {};
+    for (const [key, value] of entries) {
+        const name = key.slice(PATTERNS_PREFIX.length);
+        if (name && value) {
+            result[name] = value;
+        }
+    }
+    return Object.keys(result).length > 0 ? result : undefined;
+}
+/**
+ * Config loader that reads `new-branch.*` keys from git config.
+ *
+ * @remarks
+ * Supported keys:
+ * - `new-branch.pattern`
+ * - `new-branch.defaultType`
+ * - `new-branch.types` (comma-separated)
+ * - `new-branch.patterns.<alias>` (named patterns)
+ */
 export const gitLoader = {
     source: "git",
     async load() {
         const pattern = await getGitConfig("new-branch.pattern");
         const defaultType = await getGitConfig("new-branch.defaultType");
         const typesRaw = await getGitConfig("new-branch.types");
-        if (!pattern && !defaultType && !typesRaw) {
+        const patternsEntries = await getGitConfigRegexp("^new-branch\\.patterns\\.");
+        if (!pattern && !defaultType && !typesRaw && patternsEntries.length === 0) {
             return { found: false, source: "git", config: undefined };
         }
         const cfg = {};
@@ -32,6 +73,9 @@ export const gitLoader = {
             cfg.defaultType = defaultType;
         if (typesRaw)
             cfg.types = parseGitTypes(typesRaw);
+        const patterns = parseGitPatterns(patternsEntries);
+        if (patterns)
+            cfg.patterns = patterns;
         const sourceValidated = validateProjectConfigSource(cfg, "git config");
         const finalValidated = validateProjectConfigFinal(sourceValidated, "git config");
         return { found: true, source: "git", config: finalValidated };

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

@@ -1,9 +1,22 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
+/**
+ * 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 the `"new-branch"` key from `package.json`.
+ *
+ * @remarks
+ * Returns `found: false` when `package.json` does not exist or
+ * does not contain a `"new-branch"` key.
+ */
 export const packageJsonLoader = {
     source: "package.json",
     async load() {