new-branch 0.6.0 → 0.7.0

package/dist/cli.js

@@ -1,16 +1,19 @@
 #!/usr/bin/env node
 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 { 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";
 const ok = (value) => ({ ok: true, value });
 const err = (error) => ({ ok: false, error });
 const isOk = (r) => r.ok;
@@ -74,17 +77,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,6 +173,22 @@ export async function run() {
     if (!isOk(renderedRes))
         fail("Failed to render branch name.", renderedRes.error);
     const sanitized = sanitizeGitRef(renderedRes.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,
+            transforms: defaultTransforms,
+        }));
+        return;
+    }
     const validateRes = await safeAsync(() => validateBranchName(sanitized));
     if (!isOk(validateRes))
         fail("Branch name is not valid for git.", validateRes.error);

package/dist/config/loadConfig.js

@@ -15,17 +15,21 @@ import { gitLoader } from "./sources/git.loader.js";
  * No merging is performed.
  */
 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.
+ */
+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,4 +1,4 @@
-import { getGitConfig } from "../../git/gitConfig.js";
+import { getGitConfig, getGitConfigRegexp } from "../../git/gitConfig.js";
 import { validateProjectConfigSource, validateProjectConfigFinal } from "../validate.js";
 function parseGitTypes(raw) {
     return raw
@@ -16,13 +16,27 @@ function parseGitTypes(raw) {
         };
     });
 }
+const PATTERNS_PREFIX = "new-branch.patterns.";
+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;
+}
 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 +46,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/validate.js

@@ -48,6 +48,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");

package/dist/didactic/explain.js

@@ -0,0 +1,67 @@
+/**
+ * Produces a structured breakdown of the full branch-name pipeline.
+ *
+ * No branch is created — this is purely informational.
+ * Used by the `--explain` CLI flag.
+ */
+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}`);
+    }
+    lines.push(`\n  Final branch:   ${input.sanitized}`);
+    return lines.join("\n");
+}

package/dist/didactic/listTransforms.js

@@ -0,0 +1,21 @@
+/**
+ * Prints a formatted 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.
+ */
+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,23 @@
+/**
+ * Formats the resolved configuration for display.
+ *
+ * Shows the final resolved values from whichever source took precedence.
+ * This is used by the `--print-config` CLI flag.
+ */
+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/gitConfig.js

@@ -9,3 +9,31 @@ export async function getGitConfig(key) {
         return undefined;
     }
 }
+/**
+ * Returns all git config entries matching a key prefix using `--get-regexp`.
+ * Each entry is returned as a `[key, value]` tuple.
+ *
+ * Example: `getGitConfigRegexp("new-branch.patterns\\.")` returns
+ * `[["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/parseArgs.js

@@ -10,12 +10,16 @@ export function parseArgs(argv = process.argv) {
     const cli = cac("new-branch");
     cli
         .option("-p, --pattern <pattern>", "Branch pattern")
+        .option("--use <name>", "Use a named pattern alias from configuration")
         .option("--id <id>", "Task id")
         .option("--title <title>", "Task title")
         .option("--type <type>", "Branch type")
         .option("--create", "Create branch")
         .option("--no-prompt", "Fail instead of prompting for missing values")
         .option("--quiet", "Suppress non-essential output")
+        .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")
         .help();
     const cleaned = stripDoubleDash(argv);
     const parsed = cli.parse(cleaned);
@@ -23,6 +27,7 @@ export function parseArgs(argv = process.argv) {
     const options = {
         // Accept numeric or string-like values and coerce to string when present.
         pattern: opts.pattern !== undefined ? String(opts.pattern) : undefined,
+        use: opts.use !== undefined ? String(opts.use) : undefined,
         id: opts.id !== undefined ? String(opts.id) : undefined,
         title: opts.title !== undefined ? String(opts.title) : undefined,
         type: opts.type !== undefined ? String(opts.type) : undefined,
@@ -32,6 +37,9 @@ export function parseArgs(argv = process.argv) {
         prompt: typeof opts.prompt === "boolean" ? opts.prompt : undefined,
         quiet: typeof opts.quiet === "boolean" ? opts.quiet : undefined,
         help: typeof opts.help === "boolean" ? opts.help : undefined,
+        explain: typeof opts.explain === "boolean" ? opts.explain : undefined,
+        listTransforms: typeof opts.listTransforms === "boolean" ? opts.listTransforms : undefined,
+        printConfig: typeof opts.printConfig === "boolean" ? opts.printConfig : undefined,
     };
     return {
         options,

package/dist/pattern/transforms/after.js

@@ -0,0 +1,12 @@
+export const after = {
+    name: "after",
+    fn: (value, [suffix]) => {
+        if (suffix === undefined)
+            throw new Error("after requires one argument: {var:after:suffix}");
+        return value === "" ? "" : value + suffix;
+    },
+    doc: {
+        summary: "Adds a suffix only if the value is not empty.",
+        usage: ["{title:after:-wip}"],
+    },
+};

package/dist/pattern/transforms/before.js

@@ -0,0 +1,12 @@
+export const before = {
+    name: "before",
+    fn: (value, [prefix]) => {
+        if (prefix === undefined)
+            throw new Error("before requires one argument: {var:before:prefix}");
+        return value === "" ? "" : prefix + value;
+    },
+    doc: {
+        summary: "Adds a prefix only if the value is not empty.",
+        usage: ["{title:before:hotfix-}"],
+    },
+};

package/dist/pattern/transforms/ifEmpty.js

@@ -0,0 +1,12 @@
+export const ifEmpty = {
+    name: "ifEmpty",
+    fn: (value, [fallback]) => {
+        if (fallback === undefined)
+            throw new Error("ifEmpty requires one argument: {var:ifEmpty:fallback}");
+        return value === "" ? fallback : value;
+    },
+    doc: {
+        summary: "Provides a fallback value if the result is empty.",
+        usage: ["{title:slugify:ifEmpty:no-title}"],
+    },
+};

package/dist/pattern/transforms/index.js

@@ -8,6 +8,13 @@ import { kebab } from "../../pattern/transforms/kebab.js";
 import { snake } from "../../pattern/transforms/snake.js";
 import { title } from "../../pattern/transforms/title.js";
 import { words } from "../../pattern/transforms/words.js";
+import { replace } from "../../pattern/transforms/replace.js";
+import { replaceAll } from "../../pattern/transforms/replaceAll.js";
+import { remove } from "../../pattern/transforms/remove.js";
+import { stripAccents } from "../../pattern/transforms/stripAccents.js";
+import { ifEmpty } from "../../pattern/transforms/ifEmpty.js";
+import { before } from "../../pattern/transforms/before.js";
+import { after } from "../../pattern/transforms/after.js";
 export const allTransforms = [
     lower,
     upper,
@@ -18,5 +25,12 @@ export const allTransforms = [
     snake,
     title,
     words,
+    replace,
+    replaceAll,
+    remove,
+    stripAccents,
+    ifEmpty,
+    before,
+    after,
 ];
 export const defaultTransforms = buildRegistry(allTransforms);

package/dist/pattern/transforms/remove.js

@@ -0,0 +1,12 @@
+export const remove = {
+    name: "remove",
+    fn: (value, [target]) => {
+        if (target === undefined)
+            throw new Error("remove requires one argument: {var:remove:substring}");
+        return value.replaceAll(target, "");
+    },
+    doc: {
+        summary: "Removes all occurrences of a substring.",
+        usage: ["{title:remove:temp}"],
+    },
+};

package/dist/pattern/transforms/replace.js

@@ -0,0 +1,12 @@
+export const replace = {
+    name: "replace",
+    fn: (value, [search, replacement]) => {
+        if (search === undefined || replacement === undefined)
+            throw new Error("replace requires two arguments: {var:replace:search:replacement}");
+        return value.replace(search, replacement);
+    },
+    doc: {
+        summary: "Replaces the first occurrence of a substring.",
+        usage: ["{title:replace:foo:bar}"],
+    },
+};

package/dist/pattern/transforms/replaceAll.js

@@ -0,0 +1,12 @@
+export const replaceAll = {
+    name: "replaceAll",
+    fn: (value, [search, replacement]) => {
+        if (search === undefined || replacement === undefined)
+            throw new Error("replaceAll requires two arguments: {var:replaceAll:search:replacement}");
+        return value.replaceAll(search, replacement);
+    },
+    doc: {
+        summary: "Replaces all occurrences of a substring.",
+        usage: ["{title:replaceAll:foo:bar}"],
+    },
+};

package/dist/pattern/transforms/stripAccents.js

@@ -0,0 +1,9 @@
+export const stripAccents = {
+    name: "stripAccents",
+    fn: (value) => value.normalize("NFD").replace(/[\u0300-\u036f]/g, ""),
+    doc: {
+        summary: "Removes diacritics from characters.",
+        usage: ["{title:stripAccents}"],
+        examples: ["José → Jose"],
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "new-branch",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "Generate and create standardized git branch names from a pattern.",
   "keywords": [
     "git",