alignfirst 0.1.1 → 0.2.0

package/dist/commands/guide.js

@@ -128,9 +128,10 @@ function renderCoreGuide(ctx, placeholders) {
 }
 function buildGuidePlaceholders(ctx, protocol) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
-    const detection = pattern === undefined ? undefined : detectTicketFromBranch(ctx.cwd, pattern);
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
     return {
-        ticketCommand: detection?.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
+        ticketCommand: detection.kind === "detected" ? "{{CMD}} ticket" : "{{CMD}} ticket <id>",
         ticketDetection: renderTicketDetection(pattern, detection),
         plansState: renderPlansState(ctx),
         commitRule: renderCommitRule(ctx),
@@ -138,11 +139,11 @@ function buildGuidePlaceholders(ctx, protocol) {
     };
 }
 function renderTicketDetection(pattern, detection) {
+    if (detection.kind === "detected")
+        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
     if (pattern === undefined)
         return "Ask the user for the ticket ID when it is not given.";
-    if (detection?.kind === "detected")
-        return `Current ticket: \`${detection.id}\` (from branch \`${detection.branch}\`). The id argument of \`{{CMD}} ticket\` is optional and defaults to it; pass an id only when the user names another ticket.`;
-    if (detection?.kind === "noMatch")
+    if (detection.kind === "noMatch")
         return `No ticket id on branch \`${detection.branch}\`. Ask the user for the id.`;
     return "No ticket id: detached HEAD. Ask the user for the id.";
 }

package/dist/commands/ticket.js

@@ -5,7 +5,7 @@ import { formatLocalTimestamp, formatSize } from "../format.js";
 import { parseCommandArgs } from "../parse-args.js";
 import { renderCatchup } from "../plans/catchup.js";
 import { assertPlansGate } from "../plans/layout.js";
-import { deduceTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
+import { detectTicketFromBranch, deduceTicketFromExisting, nextFilePosition, peekSideTicket, reserveSideTicket, resolveTicketDir, validateTicketId, } from "../plans/ticket.js";
 const USAGE = `Usage:
   {{FORM}} ticket [<id>] [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
   {{FORM}} ticket --side [--next [<filename>]] [--new-cycle] [--json] [--dry-run]
@@ -70,10 +70,11 @@ function parseTicketArgs(ctx, args, usage) {
     if (values.catchup &&
         (values.side || values.next !== undefined || values.json || values["dry-run"]))
         throw new CliError(`--catchup cannot be combined with --side, --next, --json, or --dry-run.\n\n${usage}`);
+    const next = values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage);
     const resolution = resolveTicketId(ctx, positionals[0], values);
     return {
         ...resolution,
-        next: values.next === undefined ? undefined : resolveNextRequest(normalized.requests, usage),
+        next,
         newCycle: values["new-cycle"],
         json: values.json,
         dryRun: values["dry-run"],
@@ -125,16 +126,23 @@ function validateNextFilename(filename) {
 function resolveTicketId(ctx, positional, flags) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (positional !== undefined) {
-        validateTicketId(positional, pattern);
+        validateTicketId(positional);
         return { id: positional };
     }
     if (flags.side)
         return { id: flags["dry-run"] ? peekSideTicket(ctx.cwd) : reserveSideTicket(ctx.cwd) };
+    const template = ctx.projectConfig?.config.git?.branchNameTemplate;
+    const detection = detectTicketFromBranch(ctx.cwd, pattern, template);
+    if (detection.kind === "detected") {
+        validateTicketId(detection.id);
+        return detection;
+    }
     if (pattern === undefined)
         return deduceTicketFromExisting(ctx.cwd, { sideAllowed: !flags.catchup });
-    const deduced = deduceTicketFromBranch(ctx.cwd, pattern);
-    validateTicketId(deduced.id, pattern);
-    return deduced;
+    if (detection.kind === "noBranch")
+        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
+    const templateDetail = template?.includes("{TICKET_ID}") ? ` and template "${template}"` : "";
+    throw new CliError(`Cannot deduce a ticket id from branch "${detection.branch}" with pattern "${pattern}"${templateDetail}.`);
 }
 function resolveTicket(ctx, options) {
     if (options.side && !options.dryRun)

package/dist/conventions.js

@@ -18,8 +18,8 @@ export function renderConventions(ctx) {
 function renderTicketIds(ctx) {
     const pattern = ctx.projectConfig?.config.ticketIdPattern;
     if (pattern === undefined)
-        return "Ticket IDs: no configured format; ask the user for the ID. Without an external ticket, use the next `side-N`.";
-    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without an external ticket, use the next \`side-N\`.`;
+        return "Ticket IDs: no configured format; ask the user for the ID. Without a ticket, or when the user asks for a side ticket, use the next `side-N`.";
+    return `Ticket IDs: \`${pattern}\`; infer a matching ID from the branch. Without a ticket, or when the user asks for a side ticket, use the next \`side-N\`.`;
 }
 function renderBranchNames(ctx) {
     const template = ctx.projectConfig?.config.git?.branchNameTemplate;
@@ -50,10 +50,10 @@ function renderPlans(ctx) {
     try {
         const mode = resolvePlansMode(ctx.cwd, ctx.form);
         const folder = ctx.projectConfig?.config.plans?.folder;
-        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`)`;
+        const sharedFolder = folder === undefined ? "" : ` (shared folder \`${folder}\`, a separate git repository)`;
         const base = mode.kind === "shared"
-            ? `Plans: use \`.plans\`${sharedFolder}; keep it out of product commits, and run \`${ctx.form} sync\` after changes.`
-            : "Plans: use `.plans`; keep it out of product commits.";
+            ? `Plans: use \`.plans\`${sharedFolder}; run \`${ctx.form} sync\` after changes.`
+            : "Plans: use `.plans`.";
         const archival = ctx.projectConfig?.config.plans?.autoArchive === true
             ? " Automatic archival is enabled."
             : "";

package/dist/plans/ticket.d.ts

@@ -37,11 +37,10 @@ export interface NextFilePosition {
 export declare function nextFilePosition(entries: readonly string[], newCycle: boolean): NextFilePosition;
 export declare function listEntries(dir: string): TicketEntry[];
 export declare function isPathSafeTicketId(id: string): boolean;
-export declare function validateTicketId(id: string, pattern?: string): void;
-export declare function detectTicketFromBranch(cwd: string, pattern: string): TicketDetection;
+export declare function validateTicketId(id: string): void;
+export declare function detectTicketFromBranch(cwd: string, pattern?: string, template?: string): TicketDetection;
 export interface DeduceFromExistingOptions {
     sideAllowed: boolean;
 }
 /** Without a ticket id pattern, the branch can still name an existing ticket directory. */
 export declare function deduceTicketFromExisting(cwd: string, { sideAllowed }: DeduceFromExistingOptions): DeducedTicket;
-export declare function deduceTicketFromBranch(cwd: string, pattern: string): DeducedTicket;

package/dist/plans/ticket.js

@@ -7,9 +7,10 @@ import { gitOutputOrUndefined } from "../git.js";
 import { archivesDir, isTicketName, plansDir } from "./layout.js";
 const FILE_PREFIX = /^([A-Z])(\d+)-/;
 const SIDE_TICKET = /^side-(\d+)$/;
+const BRANCH_SEPARATORS = "[/_.-]";
+const SIDE_TICKET_BRANCH = new RegExp(`^side-\\d+(?=$|${BRANCH_SEPARATORS})`);
 const PATH_SAFE_TICKET = /^[A-Za-z0-9._-]+$/;
 const ENTRY_ORDER = new Intl.Collator("en", { numeric: true });
-const BRANCH_SEPARATORS = "[/_.-]";
 const LISTED_TICKETS = 10;
 export function resolveTicketDir(cwd, id, { dryRun }) {
     const dir = join(plansDir(cwd), id);
@@ -104,22 +105,49 @@ function statOrLink(path) {
 export function isPathSafeTicketId(id) {
     return id !== "." && !id.includes("..") && PATH_SAFE_TICKET.test(id);
 }
-export function validateTicketId(id, pattern) {
+export function validateTicketId(id) {
     if (!isPathSafeTicketId(id) || !isTicketName(id))
         throw new CliError(`Invalid ticket id: ${id}`);
-    if (pattern !== undefined && !new RegExp(pattern).test(id) && !SIDE_TICKET.test(id))
-        throw new CliError(`Ticket id "${id}" does not match ticketIdPattern "${pattern}".`);
 }
-export function detectTicketFromBranch(cwd, pattern) {
+export function detectTicketFromBranch(cwd, pattern, template) {
     const branch = currentBranch(cwd);
     if (branch === undefined)
         return { kind: "noBranch" };
-    const unanchored = pattern.replace(/^\^/, "").replace(/\$$/, "");
-    const match = new RegExp(unanchored).exec(branch);
+    const sideTicket = SIDE_TICKET_BRANCH.exec(branch);
+    if (sideTicket)
+        return { kind: "detected", id: sideTicket[0], branch };
+    if (pattern === undefined)
+        return { kind: "noMatch", branch };
+    if (template?.includes("{TICKET_ID}")) {
+        const match = branchPatternFromTemplate(template, unanchorPattern(pattern)).exec(branch);
+        const id = match?.[1];
+        if (id === undefined || !isPathSafeTicketId(id) || !isTicketName(id))
+            return { kind: "noMatch", branch };
+        return { kind: "detected", id, branch };
+    }
+    const match = new RegExp(unanchorPattern(pattern)).exec(branch);
     if (!match)
         return { kind: "noMatch", branch };
     return { kind: "detected", id: match[0], branch };
 }
+function unanchorPattern(pattern) {
+    return pattern.replace(/^\^/, "").replace(/\$$/, "");
+}
+function branchPatternFromTemplate(template, ticketPattern) {
+    const placeholder = /\{[^{}]+\}/g;
+    let source = "";
+    let cursor = 0;
+    for (const match of template.matchAll(placeholder)) {
+        source += escapeRegexLiteral(template.slice(cursor, match.index));
+        source += match[0] === "{TICKET_ID}" ? `((?:${ticketPattern})|side-\\d+)` : ".+";
+        cursor = match.index + match[0].length;
+    }
+    source += escapeRegexLiteral(template.slice(cursor));
+    return new RegExp(`^${source}$`);
+}
+function escapeRegexLiteral(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
 function currentBranch(cwd) {
     const branch = gitOutputOrUndefined(cwd, "branch", "--show-current");
     return branch === undefined || branch === "" ? undefined : branch;
@@ -157,7 +185,7 @@ function newestModification(dir) {
     return new Date(Math.max(...entries.map((entry) => entry.modifiedAt.getTime())));
 }
 function branchNamesTicket(branch, id) {
-    const escaped = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const escaped = escapeRegexLiteral(id);
     return new RegExp(`(^|${BRANCH_SEPARATORS})${escaped}($|${BRANCH_SEPARATORS})`).test(branch);
 }
 function renderMissingTicketId(tickets, sideAllowed) {
@@ -175,11 +203,3 @@ function renderMissingTicketId(tickets, sideAllowed) {
         lines.push(`  … ${rest} more`);
     return `No ticket id given. Existing tickets:\n${lines.join("\n")}\n${hint}`;
 }
-export function deduceTicketFromBranch(cwd, pattern) {
-    const result = detectTicketFromBranch(cwd, pattern);
-    if (result.kind === "noBranch")
-        throw new CliError("Cannot deduce a ticket id from a detached HEAD.");
-    if (result.kind === "noMatch")
-        throw new CliError(`Cannot deduce a ticket id from branch "${result.branch}" with pattern "${pattern}".`);
-    return result;
-}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "alignfirst",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "license": "CC0-1.0",
   "author": "Thomas MUR",
   "description": "The AlignFirst CLI: protocols, plans and docs in one command.",

package/templates/guide/core.md

@@ -2,7 +2,7 @@
 
 ## Ticket Directory
 
-TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID or `side-N` for work without an external ticket.
+TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID is the external ticket ID, or `side-N` for a side ticket: work without a ticket.
 
 {{TICKET_DETECTION}}
 
@@ -10,7 +10,7 @@ TICKET_DIR holds a ticket's work files and includes a trailing slash. TICKET_ID
 
 {{PLANS_STATE}}
 
-When the user says there is no external ticket, run `{{CMD}} ticket --side` and use the returned TICKET_ID in subsequent ticket commands. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
+When the user says there is no ticket or asks for a side ticket, run `{{CMD}} ticket --side` and use the returned TICKET_ID in subsequent ticket commands. Reuse an existing `side-N` directory when the user refers to earlier work. Omit the ticket ID from commit messages.
 
 ## Work Files
 

package/templates/guide/protocols/aad.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 

package/templates/guide/protocols/description.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Steps
 

package/templates/guide/protocols/merge.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ---
 

package/templates/guide/protocols/plan.md

@@ -6,7 +6,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - a **spec file** in the TICKET_DIR
 
 Identify TICKET_DIR and the spec file before starting the protocol. If either is missing, STOP AND ASK THE USER.

package/templates/guide/protocols/review.md

@@ -4,7 +4,7 @@
 
 You need:
 
-- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` when there is no external ticket)
+- the TICKET_DIR and ticket directory context — run `{{TICKET_CMD}}` once (`{{CMD}} ticket --side` for a side ticket, when there is no ticket)
 - {{BASE_BRANCH_RULE}}
 
 Identify TICKET_DIR and the base branch before starting the protocol.

package/templates/guide/protocols/spec.md

@@ -2,7 +2,7 @@
 
 ## Prerequisites
 
-Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` when there is no external ticket).
+Run `{{TICKET_CMD}}` once to identify TICKET_DIR and load the ticket directory context (`{{CMD}} ticket --side` for a side ticket, when there is no ticket).
 
 ## Phases