@carllee1983/tagsmith 0.2.0

package/dist/core/config.js

@@ -0,0 +1,152 @@
+import { readFile, writeFile, access } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { DEFAULT_SEMVER_LINE } from "./defaults.js";
+import { hasConformingTag, inferPattern } from "./infer.js";
+import { createModel } from "./models/index.js";
+export const CONFIG_FILENAME = ".tagsmith.json";
+const semverModelSchema = z.object({
+    type: z.literal("semver"),
+    allowPrerelease: z.boolean().optional(),
+});
+const calverModelSchema = z.object({
+    type: z.literal("calver"),
+    format: z.string().min(1),
+});
+const buildModelSchema = z.object({
+    type: z.literal("build"),
+    padding: z.number().int().min(0).optional(),
+});
+const modelSchema = z.discriminatedUnion("type", [
+    semverModelSchema,
+    calverModelSchema,
+    buildModelSchema,
+]);
+const patternSchema = z
+    .string()
+    .refine((p) => p.includes("{version}"), {
+    message: "pattern must contain the {version} placeholder",
+});
+const lineSchema = z.object({
+    name: z.string().min(1),
+    pattern: patternSchema,
+    model: modelSchema,
+    initialVersion: z.string().min(1),
+    push: z.boolean().default(false),
+});
+const multiConfigSchema = z.object({
+    tags: z.array(lineSchema).min(1),
+    default: z.string().optional(),
+});
+const legacyConfigSchema = z.object({
+    pattern: patternSchema,
+    model: modelSchema,
+    initialVersion: z.string().min(1),
+    push: z.boolean().default(false),
+});
+export class ConfigError extends Error {
+}
+/** Thrown by loadConfig when no config file exists (vs. a malformed one). */
+export class MissingConfigError extends ConfigError {
+}
+/** Build semver defaults, inferring pattern from existing tag names when possible. */
+export function buildImplicitConfig(tags) {
+    const model = createModel(DEFAULT_SEMVER_LINE.model);
+    const pattern = inferPattern(tags, model);
+    const line = { ...DEFAULT_SEMVER_LINE, pattern };
+    const config = { lines: [line], default: "default" };
+    const source = tags.length > 0 && hasConformingTag(tags, pattern, model)
+        ? "inferred"
+        : "default";
+    return { config, source };
+}
+/** Parse, normalise and validate a raw config. Throws ConfigError on failure. */
+export function parseConfig(raw) {
+    const isMulti = typeof raw === "object" &&
+        raw !== null &&
+        Array.isArray(raw["tags"]);
+    if (isMulti) {
+        const result = multiConfigSchema.safeParse(raw);
+        if (!result.success)
+            throw configError(result.error);
+        return finalizeMulti(result.data.tags, result.data.default);
+    }
+    const result = legacyConfigSchema.safeParse(raw);
+    if (!result.success)
+        throw configError(result.error);
+    const line = {
+        name: "default",
+        pattern: result.data.pattern,
+        model: result.data.model,
+        initialVersion: result.data.initialVersion,
+        push: result.data.push,
+    };
+    return { lines: [line], default: "default" };
+}
+function finalizeMulti(lines, def) {
+    const names = lines.map((l) => l.name);
+    const dupes = names.filter((n, i) => names.indexOf(n) !== i);
+    if (dupes.length > 0) {
+        throw new ConfigError(`Invalid ${CONFIG_FILENAME}:\n  - tags: duplicate line name(s): ${[...new Set(dupes)].join(", ")}`);
+    }
+    // names is guaranteed non-empty because the zod schema has .min(1).
+    const resolvedDefault = def ?? names[0];
+    if (!names.includes(resolvedDefault)) {
+        throw new ConfigError(`Invalid ${CONFIG_FILENAME}:\n  - default: "${resolvedDefault}" does not match any line name (${names.join(", ")})`);
+    }
+    return { lines, default: resolvedDefault };
+}
+function configError(error) {
+    const issues = error.issues
+        .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
+        .join("\n");
+    return new ConfigError(`Invalid ${CONFIG_FILENAME}:\n${issues}`);
+}
+export function configPath(cwd) {
+    return path.join(cwd, CONFIG_FILENAME);
+}
+export async function configExists(cwd) {
+    try {
+        await access(configPath(cwd));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Load and validate the config from `cwd`. Throws ConfigError when missing. */
+export async function loadConfig(cwd) {
+    const file = configPath(cwd);
+    let text;
+    try {
+        text = await readFile(file, "utf8");
+    }
+    catch {
+        throw new MissingConfigError(`No ${CONFIG_FILENAME} found in ${cwd}. Run \`tagsmith init\` first.`);
+    }
+    let json;
+    try {
+        json = JSON.parse(text);
+    }
+    catch (err) {
+        throw new ConfigError(`${CONFIG_FILENAME} is not valid JSON: ${err.message}`);
+    }
+    return parseConfig(json);
+}
+export async function writeConfig(cwd, config) {
+    const file = configPath(cwd);
+    const fileShape = {
+        tags: config.lines.map((l) => ({
+            name: l.name,
+            pattern: l.pattern,
+            model: l.model,
+            initialVersion: l.initialVersion,
+            push: l.push,
+        })),
+        default: config.default,
+    };
+    // Never persist a broken config: validate the on-disk shape first.
+    parseConfig(fileShape);
+    const body = JSON.stringify(fileShape, null, 2);
+    await writeFile(file, `${body}\n`, "utf8");
+}

package/dist/core/defaults.d.ts

@@ -0,0 +1,6 @@
+import type { ModelConfig, TagLine, TagsmithConfig } from "../types.js";
+export declare const DEFAULT_SEMVER_MODEL: ModelConfig;
+export declare const DEFAULT_INITIAL_VERSION = "0.1.0";
+export declare const DEFAULT_SEMVER_LINE: TagLine;
+/** Hard-coded semver defaults when no config file and no inferrable tags exist. */
+export declare function defaultConfig(): TagsmithConfig;

package/dist/core/defaults.js

@@ -0,0 +1,16 @@
+export const DEFAULT_SEMVER_MODEL = {
+    type: "semver",
+    allowPrerelease: true,
+};
+export const DEFAULT_INITIAL_VERSION = "0.1.0";
+export const DEFAULT_SEMVER_LINE = {
+    name: "default",
+    pattern: "v{version}",
+    model: DEFAULT_SEMVER_MODEL,
+    initialVersion: DEFAULT_INITIAL_VERSION,
+    push: false,
+};
+/** Hard-coded semver defaults when no config file and no inferrable tags exist. */
+export function defaultConfig() {
+    return { lines: [{ ...DEFAULT_SEMVER_LINE }], default: "default" };
+}

package/dist/core/infer.d.ts

@@ -0,0 +1,6 @@
+import type { VersionModel } from "../types.js";
+export declare const INFER_CANDIDATE_PATTERNS: readonly ["v{version}", "{version}", "release/{version}", "release-{version}", "release/v{version}"];
+/** Pick the candidate pattern that matches the most semver-parseable tags. */
+export declare function inferPattern(tags: readonly string[], model: VersionModel): string;
+/** True when at least one tag conforms to the pattern + model. */
+export declare function hasConformingTag(tags: readonly string[], pattern: string, model: VersionModel): boolean;

package/dist/core/infer.js

@@ -0,0 +1,35 @@
+import { compilePattern } from "./pattern.js";
+export const INFER_CANDIDATE_PATTERNS = [
+    "v{version}",
+    "{version}",
+    "release/{version}",
+    "release-{version}",
+    "release/v{version}",
+];
+function scorePattern(tags, pattern, model) {
+    const compiled = compilePattern(pattern);
+    let score = 0;
+    for (const tag of tags) {
+        const ver = compiled.extract(tag);
+        if (ver !== null && model.parse(ver) !== null)
+            score++;
+    }
+    return score;
+}
+/** Pick the candidate pattern that matches the most semver-parseable tags. */
+export function inferPattern(tags, model) {
+    let best = INFER_CANDIDATE_PATTERNS[0];
+    let bestScore = 0;
+    for (const p of INFER_CANDIDATE_PATTERNS) {
+        const s = scorePattern(tags, p, model);
+        if (s > bestScore) {
+            bestScore = s;
+            best = p;
+        }
+    }
+    return best;
+}
+/** True when at least one tag conforms to the pattern + model. */
+export function hasConformingTag(tags, pattern, model) {
+    return scorePattern(tags, pattern, model) > 0;
+}

package/dist/core/lines.d.ts

@@ -0,0 +1,13 @@
+import type { TagLine, TagsmithConfig } from "../types.js";
+export interface LineAssignment {
+    /** 線名 → 屬於該線的原始 git tag 名(宣告順序、首條命中者勝)。 */
+    byLine: Map<string, string[]>;
+    /** 不被任何線命中的 tag。 */
+    orphans: string[];
+}
+/** 把 git tag 依「宣告順序第一條命中的 pattern」歸屬到各線桶。 */
+export declare function assignTagsToLines(tags: readonly string[], lines: readonly TagLine[]): LineAssignment;
+export declare class LineNotFoundError extends Error {
+}
+/** 取得指定線(省略則取 default);不存在時丟出列有可用線名的錯誤。 */
+export declare function selectLine(config: TagsmithConfig, name?: string): TagLine;

package/dist/core/lines.js

@@ -0,0 +1,27 @@
+import { compilePattern } from "./pattern.js";
+/** 把 git tag 依「宣告順序第一條命中的 pattern」歸屬到各線桶。 */
+export function assignTagsToLines(tags, lines) {
+    const compiled = lines.map((l) => ({ name: l.name, p: compilePattern(l.pattern) }));
+    const byLine = new Map(lines.map((l) => [l.name, []]));
+    const orphans = [];
+    for (const tag of tags) {
+        const hit = compiled.find((c) => c.p.extract(tag) !== null);
+        if (hit)
+            byLine.get(hit.name).push(tag);
+        else
+            orphans.push(tag);
+    }
+    return { byLine, orphans };
+}
+export class LineNotFoundError extends Error {
+}
+/** 取得指定線(省略則取 default);不存在時丟出列有可用線名的錯誤。 */
+export function selectLine(config, name) {
+    const target = name ?? config.default;
+    const line = config.lines.find((l) => l.name === target);
+    if (!line) {
+        const names = config.lines.map((l) => l.name).join(", ");
+        throw new LineNotFoundError(`No tag line named "${target}". Available: ${names}`);
+    }
+    return line;
+}

package/dist/core/models/build.d.ts

@@ -0,0 +1,13 @@
+import type { VersionModel } from "../../types.js";
+export interface BuildValue {
+    n: number;
+}
+export interface BuildOptions {
+    /** Zero-pad to this width (0 = none). */
+    padding?: number;
+}
+/**
+ * Monotonic build-number model: a single non-negative integer that only ever
+ * increments. Any bump level advances it by one.
+ */
+export declare function createBuildModel(opts?: BuildOptions): VersionModel<BuildValue>;

package/dist/core/models/build.js

@@ -0,0 +1,33 @@
+/**
+ * Monotonic build-number model: a single non-negative integer that only ever
+ * increments. Any bump level advances it by one.
+ */
+export function createBuildModel(opts = {}) {
+    const padding = opts.padding ?? 0;
+    return {
+        type: "build",
+        parse(raw) {
+            // Cap digits so the value stays within Number.MAX_SAFE_INTEGER; beyond
+            // that, compare/bump lose precision and the monotonic invariant breaks.
+            if (!/^\d{1,15}$/.test(raw))
+                return null;
+            return { n: Number(raw) };
+        },
+        compare(a, b) {
+            return a.n - b.n;
+        },
+        format(v) {
+            return padding > 0 ? String(v.n).padStart(padding, "0") : String(v.n);
+        },
+        bump(v, _level) {
+            return { n: v.n + 1 };
+        },
+        initial(raw) {
+            const parsed = this.parse(raw);
+            if (parsed === null) {
+                throw new Error(`initialVersion "${raw}" is not a valid build number.`);
+            }
+            return parsed;
+        },
+    };
+}

package/dist/core/models/calver.d.ts

@@ -0,0 +1,19 @@
+import type { VersionModel } from "../../types.js";
+export interface CalverValue {
+    year: number;
+    month: number;
+    day: number;
+    micro: number;
+}
+export interface CalverOptions {
+    format: string;
+    /** Injected "today" so the model stays pure and testable. */
+    now?: Date;
+}
+/**
+ * Calendar versioning. The `format` string is a sequence of tokens
+ * (YYYY, YY, MM, DD, MICRO) joined by literal separators, e.g. "YYYY.MM.MICRO".
+ * Bumping always rolls to the injected current date; MICRO increments when the
+ * date is unchanged and resets otherwise.
+ */
+export declare function createCalverModel(opts: CalverOptions): VersionModel<CalverValue>;

package/dist/core/models/calver.js

@@ -0,0 +1,166 @@
+const TOKEN_ORDER = ["YYYY", "YY", "MM", "DD", "MICRO"];
+/**
+ * Calendar versioning. The `format` string is a sequence of tokens
+ * (YYYY, YY, MM, DD, MICRO) joined by literal separators, e.g. "YYYY.MM.MICRO".
+ * Bumping always rolls to the injected current date; MICRO increments when the
+ * date is unchanged and resets otherwise.
+ */
+export function createCalverModel(opts) {
+    const tokens = parseFormatTokens(opts.format);
+    const now = opts.now ?? new Date();
+    const model = {
+        type: "calver",
+        parse(raw) {
+            const { regex } = buildMatcher(opts.format, tokens);
+            const m = regex.exec(raw);
+            if (m === null || m.groups === undefined)
+                return null;
+            const g = m.groups;
+            const value = {
+                year: g.YYYY !== undefined
+                    ? Number(g.YYYY)
+                    : g.YY !== undefined
+                        ? 2000 + Number(g.YY)
+                        : 0,
+                month: g.MM !== undefined ? Number(g.MM) : 0,
+                day: g.DD !== undefined ? Number(g.DD) : 0,
+                micro: g.MICRO !== undefined ? Number(g.MICRO) : 0,
+            };
+            if (value.month > 12 || value.day > 31)
+                return null;
+            // Reject anything that does not round-trip to its canonical form (e.g.
+            // unpadded "2026.6.7" or leading-zero MICRO "...007"), so a non-canonical
+            // tag can never masquerade as — or duplicate — a canonical one.
+            if (renderTokens(opts.format, tokens, value) !== raw)
+                return null;
+            return value;
+        },
+        compare(a, b) {
+            return (a.year - b.year ||
+                a.month - b.month ||
+                a.day - b.day ||
+                a.micro - b.micro);
+        },
+        format(v) {
+            return renderTokens(opts.format, tokens, v);
+        },
+        bump(v, _level) {
+            const today = dateValue(now, tokens);
+            const sameDate = today.year === v.year &&
+                today.month === v.month &&
+                today.day === v.day;
+            if (!tokens.includes("MICRO")) {
+                if (this.compare(today, v) <= 0) {
+                    throw new Error(`CalVer format "${opts.format}" has no MICRO token; cannot create a second tag for the same date period.`);
+                }
+                return today;
+            }
+            // Same date → next MICRO. Future date → reset MICRO. If `today` is not
+            // strictly after `v` (clock skew, or a future-dated latest tag), stay on
+            // v's date and bump MICRO so the result is always strictly greater.
+            if (sameDate)
+                return { ...today, micro: v.micro + 1 };
+            return this.compare(today, v) > 0
+                ? { ...today, micro: 0 }
+                : { ...v, micro: v.micro + 1 };
+        },
+        initial(raw) {
+            const parsed = this.parse(raw);
+            if (parsed === null) {
+                throw new Error(`initialVersion "${raw}" does not match calver format "${opts.format}".`);
+            }
+            return parsed;
+        },
+    };
+    return model;
+}
+function parseFormatTokens(format) {
+    const found = [];
+    let i = 0;
+    while (i < format.length) {
+        const token = TOKEN_ORDER.find((t) => format.startsWith(t, i));
+        if (token !== undefined) {
+            found.push(token);
+            i += token.length;
+        }
+        else {
+            i += 1; // literal separator char
+        }
+    }
+    if (found.length === 0) {
+        throw new Error(`CalVer format "${format}" contains no recognised tokens.`);
+    }
+    return found;
+}
+// Fixed-width matchers prevent a greedy `\d+` from eating across an adjacent
+// numeric token (e.g. format "YYYYMM" on "202606" must split 2026|06, not
+// 20260|6). MICRO is the only unbounded token.
+const TOKEN_REGEX = {
+    YYYY: "\\d{4}",
+    YY: "\\d{2}",
+    MM: "\\d{2}",
+    DD: "\\d{2}",
+    MICRO: "\\d+",
+};
+function buildMatcher(format, tokens) {
+    let pattern = "";
+    let i = 0;
+    const used = new Set();
+    while (i < format.length) {
+        const token = tokens.find((t) => format.startsWith(t, i) && !used.has(t))
+            ?? TOKEN_ORDER.find((t) => format.startsWith(t, i));
+        if (token !== undefined && !used.has(token)) {
+            used.add(token);
+            pattern += `(?<${token}>${TOKEN_REGEX[token]})`;
+            i += token.length;
+        }
+        else {
+            pattern += escapeRegex(format[i] ?? "");
+            i += 1;
+        }
+    }
+    return { regex: new RegExp(`^${pattern}$`) };
+}
+function renderTokens(format, tokens, v) {
+    let out = "";
+    let i = 0;
+    const used = new Set();
+    while (i < format.length) {
+        const token = tokens.find((t) => format.startsWith(t, i) && !used.has(t));
+        if (token !== undefined) {
+            used.add(token);
+            out += renderToken(token, v);
+            i += token.length;
+        }
+        else {
+            out += format[i] ?? "";
+            i += 1;
+        }
+    }
+    return out;
+}
+function renderToken(token, v) {
+    switch (token) {
+        case "YYYY":
+            return String(v.year).padStart(4, "0");
+        case "YY":
+            return String(v.year % 100).padStart(2, "0");
+        case "MM":
+            return String(v.month).padStart(2, "0");
+        case "DD":
+            return String(v.day).padStart(2, "0");
+        case "MICRO":
+            return String(v.micro);
+    }
+}
+function dateValue(now, tokens) {
+    return {
+        year: tokens.some((t) => t === "YYYY" || t === "YY") ? now.getFullYear() : 0,
+        month: tokens.includes("MM") ? now.getMonth() + 1 : 0,
+        day: tokens.includes("DD") ? now.getDate() : 0,
+        micro: 0,
+    };
+}
+function escapeRegex(ch) {
+    return ch.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/dist/core/models/index.d.ts

@@ -0,0 +1,10 @@
+import type { ModelConfig, VersionModel } from "../../types.js";
+export { createSemverModel } from "./semver.js";
+export { createCalverModel } from "./calver.js";
+export { createBuildModel } from "./build.js";
+export interface ModelFactoryOptions {
+    /** Injected current date for calver; ignored by other models. */
+    now?: Date;
+}
+/** Construct the version model described by a config block. */
+export declare function createModel(config: ModelConfig, opts?: ModelFactoryOptions): VersionModel;

package/dist/core/models/index.js

@@ -0,0 +1,21 @@
+import { createSemverModel } from "./semver.js";
+import { createCalverModel } from "./calver.js";
+import { createBuildModel } from "./build.js";
+export { createSemverModel } from "./semver.js";
+export { createCalverModel } from "./calver.js";
+export { createBuildModel } from "./build.js";
+/** Construct the version model described by a config block. */
+export function createModel(config, opts = {}) {
+    switch (config.type) {
+        case "semver":
+            return createSemverModel({ allowPrerelease: config.allowPrerelease });
+        case "calver":
+            return createCalverModel({ format: config.format, now: opts.now });
+        case "build":
+            return createBuildModel({ padding: config.padding });
+        default: {
+            const exhaustive = config;
+            throw new Error(`Unknown model type: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+}

package/dist/core/models/semver.d.ts

@@ -0,0 +1,13 @@
+import type { VersionModel } from "../../types.js";
+export interface SemverValue {
+    /** Canonical semver string, e.g. "1.2.3" or "1.2.3-rc.1". */
+    value: string;
+}
+export interface SemverOptions {
+    allowPrerelease?: boolean;
+}
+/**
+ * SemVer model backed by the `semver` package. Comparison and bumping follow
+ * standard SemVer precedence, including prerelease handling.
+ */
+export declare function createSemverModel(opts?: SemverOptions): VersionModel<SemverValue>;

package/dist/core/models/semver.js

@@ -0,0 +1,57 @@
+import semver from "semver";
+/**
+ * SemVer model backed by the `semver` package. Comparison and bumping follow
+ * standard SemVer precedence, including prerelease handling.
+ */
+export function createSemverModel(opts = {}) {
+    const allowPrerelease = opts.allowPrerelease ?? true;
+    return {
+        type: "semver",
+        parse(raw) {
+            const cleaned = semver.valid(raw, { loose: false });
+            if (cleaned === null)
+                return null;
+            if (!allowPrerelease && semver.prerelease(cleaned) !== null)
+                return null;
+            return { value: cleaned };
+        },
+        compare(a, b) {
+            return semver.compare(a.value, b.value);
+        },
+        format(v) {
+            return v.value;
+        },
+        bump(v, level) {
+            const release = toReleaseType(level);
+            const next = semver.inc(v.value, release);
+            if (next === null) {
+                throw new Error(`Cannot bump semver "${v.value}" by "${level}".`);
+            }
+            return { value: next };
+        },
+        initial(raw) {
+            const parsed = this.parse(raw);
+            if (parsed === null) {
+                throw new Error(`initialVersion "${raw}" is not a valid semver.`);
+            }
+            return parsed;
+        },
+    };
+}
+function toReleaseType(level) {
+    switch (level) {
+        case "major":
+            return "major";
+        case "minor":
+            return "minor";
+        case "prerelease":
+            return "prerelease";
+        case "patch":
+        case "auto":
+            return "patch";
+        default: {
+            const exhaustive = level;
+            throw new Error(`Unsupported semver bump level: ${String(exhaustive)}`);
+        }
+    }
+}

package/dist/core/pattern.d.ts

@@ -0,0 +1,15 @@
+export declare class PatternError extends Error {
+}
+/**
+ * A tag pattern is a template containing exactly one `{version}` placeholder,
+ * e.g. "v{version}" or "release/{version}". This compiles it into a matcher
+ * that can extract the version substring and re-render full tag names.
+ */
+export interface CompiledPattern {
+    readonly template: string;
+    /** Extract the version substring from a tag name, or null if it doesn't match. */
+    extract(tag: string): string | null;
+    /** Render a full tag name from a version string. */
+    render(version: string): string;
+}
+export declare function compilePattern(template: string): CompiledPattern;

package/dist/core/pattern.js

@@ -0,0 +1,29 @@
+const PLACEHOLDER = "{version}";
+export class PatternError extends Error {
+}
+export function compilePattern(template) {
+    const first = template.indexOf(PLACEHOLDER);
+    if (first === -1) {
+        throw new PatternError(`Pattern "${template}" must contain the ${PLACEHOLDER} placeholder.`);
+    }
+    if (template.indexOf(PLACEHOLDER, first + PLACEHOLDER.length) !== -1) {
+        throw new PatternError(`Pattern "${template}" must contain ${PLACEHOLDER} exactly once.`);
+    }
+    const prefix = template.slice(0, first);
+    const suffix = template.slice(first + PLACEHOLDER.length);
+    // The version capture is non-greedy-safe because prefix/suffix are anchored.
+    const regex = new RegExp(`^${escapeRegex(prefix)}(.+)${escapeRegex(suffix)}$`);
+    return {
+        template,
+        extract(tag) {
+            const m = regex.exec(tag);
+            return m === null ? null : (m[1] ?? null);
+        },
+        render(version) {
+            return `${prefix}${version}${suffix}`;
+        },
+    };
+}
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}