@carllee1983/tagsmith 0.2.0

package/dist/core/plan.d.ts

@@ -0,0 +1,33 @@
+import type { BumpLevel, TagLine, VersionModel } from "../types.js";
+import { type Analysis } from "./analyze.js";
+export interface NextPlan {
+    /** The full next tag name, e.g. "v1.2.4". */
+    tag: string;
+    /** The next version string (without pattern), e.g. "1.2.4". */
+    version: string;
+    /** The version this was derived from, or null when starting fresh. */
+    fromVersion: string | null;
+    /** Whether the initialVersion was used (no prior conforming tag). */
+    fresh: boolean;
+    analysis: Analysis;
+}
+export declare class PlanError extends Error {
+}
+/**
+ * Compute the next tag for the repo given existing tags. Guarantees the result
+ * is strictly greater than the current highest conforming version.
+ */
+export declare function planNext(line: TagLine, model: VersionModel, existingTags: readonly string[], level?: BumpLevel): NextPlan;
+export interface ValidateOptions {
+    allowOutOfOrder?: boolean;
+}
+export interface ValidationResult {
+    ok: boolean;
+    errors: string[];
+}
+/**
+ * Validate that an explicit version is safe to create: it must parse, render
+ * to a tag that does not already exist, and (unless overridden) be strictly
+ * greater than the current highest conforming version.
+ */
+export declare function validateExplicit(line: TagLine, model: VersionModel, explicitVersion: string, existingTags: readonly string[], opts?: ValidateOptions): ValidationResult;

package/dist/core/plan.js

@@ -0,0 +1,59 @@
+import { compilePattern } from "./pattern.js";
+import { analyzeTags } from "./analyze.js";
+export class PlanError extends Error {
+}
+/**
+ * Compute the next tag for the repo given existing tags. Guarantees the result
+ * is strictly greater than the current highest conforming version.
+ */
+export function planNext(line, model, existingTags, level = "patch") {
+    const pattern = compilePattern(line.pattern);
+    const analysis = analyzeTags(existingTags, pattern, model);
+    if (analysis.latest === null) {
+        const initial = model.initial(line.initialVersion);
+        return {
+            tag: pattern.render(model.format(initial)),
+            version: model.format(initial),
+            fromVersion: null,
+            fresh: true,
+            analysis,
+        };
+    }
+    const current = analysis.latest.version;
+    const next = model.bump(current, level);
+    if (model.compare(next, current) <= 0) {
+        throw new PlanError(`Bumping ${model.format(current)} by "${level}" did not increase the version.`);
+    }
+    return {
+        tag: pattern.render(model.format(next)),
+        version: model.format(next),
+        fromVersion: model.format(current),
+        fresh: false,
+        analysis,
+    };
+}
+/**
+ * Validate that an explicit version is safe to create: it must parse, render
+ * to a tag that does not already exist, and (unless overridden) be strictly
+ * greater than the current highest conforming version.
+ */
+export function validateExplicit(line, model, explicitVersion, existingTags, opts = {}) {
+    const pattern = compilePattern(line.pattern);
+    const errors = [];
+    const parsed = model.parse(explicitVersion);
+    if (parsed === null) {
+        errors.push(`Version "${explicitVersion}" is not valid for the ${model.type} model.`);
+        return { ok: false, errors };
+    }
+    const tagName = pattern.render(model.format(parsed));
+    if (existingTags.includes(tagName)) {
+        errors.push(`Tag "${tagName}" already exists.`);
+    }
+    const analysis = analyzeTags(existingTags, pattern, model);
+    if (analysis.latest !== null && !opts.allowOutOfOrder) {
+        if (model.compare(parsed, analysis.latest.version) <= 0) {
+            errors.push(`Version "${model.format(parsed)}" is not greater than the latest "${model.format(analysis.latest.version)}". Use --allow-out-of-order to override.`);
+        }
+    }
+    return { ok: errors.length === 0, errors };
+}

package/dist/git/git.d.ts

@@ -0,0 +1,23 @@
+export declare class GitError extends Error {
+}
+export interface GitOptions {
+    /** Working directory for git commands. */
+    cwd: string;
+}
+/** Throw a friendly error when cwd is not inside a git work tree. */
+export declare function ensureRepo(opts: GitOptions): Promise<void>;
+/** List all tag names in the repo. */
+export declare function listTags(opts: GitOptions): Promise<string[]>;
+export interface CreateTagOptions extends GitOptions {
+    name: string;
+    /** When provided, creates an annotated tag with this message. */
+    message?: string;
+    /** Target ref/commit; defaults to HEAD. */
+    ref?: string;
+}
+export declare function createTag(opts: CreateTagOptions): Promise<void>;
+export interface PushTagOptions extends GitOptions {
+    name: string;
+    remote?: string;
+}
+export declare function pushTag(opts: PushTagOptions): Promise<void>;

package/dist/git/git.js

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+const execFileAsync = promisify(execFile);
+export class GitError extends Error {
+}
+async function git(args, cwd) {
+    try {
+        const { stdout } = await execFileAsync("git", args, { cwd });
+        return stdout;
+    }
+    catch (err) {
+        const e = err;
+        throw new GitError(`git ${args.join(" ")} failed: ${(e.stderr ?? e.message ?? "unknown error").trim()}`);
+    }
+}
+/** Throw a friendly error when cwd is not inside a git work tree. */
+export async function ensureRepo(opts) {
+    try {
+        await git(["rev-parse", "--is-inside-work-tree"], opts.cwd);
+    }
+    catch {
+        throw new GitError(`Not a git repository: ${opts.cwd}. Run \`git init\` first.`);
+    }
+}
+/** List all tag names in the repo. */
+export async function listTags(opts) {
+    const out = await git(["tag", "--list"], opts.cwd);
+    return out
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+export async function createTag(opts) {
+    const args = ["tag"];
+    if (opts.message !== undefined) {
+        args.push("-a", opts.name, "-m", opts.message);
+    }
+    else {
+        args.push(opts.name);
+    }
+    if (opts.ref !== undefined)
+        args.push(opts.ref);
+    await git(args, opts.cwd);
+}
+export async function pushTag(opts) {
+    await git(["push", opts.remote ?? "origin", opts.name], opts.cwd);
+}

package/dist/types.d.ts

@@ -0,0 +1,66 @@
+/** Bump levels understood by version models. Not every model supports every level. */
+export type BumpLevel = "major" | "minor" | "patch" | "prerelease" | "auto";
+/**
+ * A version model knows how to parse, compare, format and bump a particular
+ * versioning scheme (semver, calver, build number…). Implementations are pure:
+ * no IO, no clock access (the current date is injected where needed).
+ */
+export interface VersionModel<V = unknown> {
+    readonly type: string;
+    /** Parse a raw version string; return null when it does not conform. */
+    parse(raw: string): V | null;
+    /** Standard comparator: negative if a<b, 0 if equal, positive if a>b. */
+    compare(a: V, b: V): number;
+    /** Render a parsed version back to its canonical string. */
+    format(v: V): string;
+    /** Produce the next version for the given level. */
+    bump(v: V, level: BumpLevel): V;
+    /** Build the starting version from the config's initialVersion. */
+    initial(raw: string): V;
+}
+export type ModelType = "semver" | "calver" | "build";
+export interface SemverModelConfig {
+    type: "semver";
+    allowPrerelease?: boolean;
+}
+export interface CalverModelConfig {
+    type: "calver";
+    /** Format tokens: YYYY, YY, MM, DD, MICRO. e.g. "YYYY.MM.MICRO". */
+    format: string;
+}
+export interface BuildModelConfig {
+    type: "build";
+    /** Zero-pad the number to this width (0 = no padding). */
+    padding?: number;
+}
+export type ModelConfig = SemverModelConfig | CalverModelConfig | BuildModelConfig;
+/** 一條獨立的 tag 線:有自己的 pattern、版本模型、起始版本與 push 設定。 */
+export interface TagLine {
+    /** 線名,唯一,用於 CLI 選線。 */
+    name: string;
+    /** Tag 模板;MUST 含且僅含一個 `{version}`。 */
+    pattern: string;
+    model: ModelConfig;
+    /** 無對應 tag 時的起始版本。 */
+    initialVersion: string;
+    /** 建立時是否預設 push。 */
+    push: boolean;
+}
+/** 內部正規化後的設定:一律為多線結構。 */
+export interface TagsmithConfig {
+    lines: TagLine[];
+    /** 預設線名,正規化後一定指向有效的 line.name。 */
+    default: string;
+}
+/** A tag parsed against the configured pattern + model. */
+export interface ParsedTag {
+    /** Raw git tag name. */
+    raw: string;
+    /** Version substring extracted by the pattern, when it matched. */
+    versionString: string | null;
+    /** Parsed version value (model-specific), when parseable. */
+    version: unknown | null;
+    /** Why a tag is considered non-conforming, if so. */
+    anomaly: TagAnomaly | null;
+}
+export type TagAnomaly = "pattern-mismatch" | "unparseable-version" | "duplicate-version";

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@carllee1983/tagsmith",
+  "version": "0.2.0",
+  "description": "Define git tag specs, view tags, and generate the next git tag safely — avoiding ordering or format anomalies.",
+  "type": "module",
+  "publishConfig": { "access": "public" },
+  "bin": {
+    "tagsmith": "dist/cli/index.js"
+  },
+  "files": [
+    "dist",
+    "schema.json"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "dev": "tsx src/cli/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "git",
+    "tag",
+    "semver",
+    "calver",
+    "cli",
+    "release",
+    "versioning"
+  ],
+  "license": "MIT",
+  "author": "carl",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CarlLee1983/Tagsmith.git"
+  },
+  "homepage": "https://github.com/CarlLee1983/Tagsmith#readme",
+  "bugs": {
+    "url": "https://github.com/CarlLee1983/Tagsmith/issues"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "commander": "^12.1.0",
+    "picocolors": "^1.0.1",
+    "semver": "^7.6.3",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^22.5.0",
+    "@types/semver": "^7.5.8",
+    "@vitest/coverage-v8": "^2.0.5",
+    "tsx": "^4.19.0",
+    "typescript": "^5.5.4",
+    "vitest": "^2.0.5"
+  }
+}

package/schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://github.com/CMG/tagsmith/schema.json",
+  "title": "Tagsmith config",
+  "description": "Tag specification for the tagsmith CLI (.tagsmith.json).",
+  "type": "object",
+  "required": ["pattern", "model", "initialVersion"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "pattern": {
+      "type": "string",
+      "description": "Tag template; must contain the {version} placeholder.",
+      "pattern": "\\{version\\}"
+    },
+    "model": {
+      "oneOf": [
+        {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "semver" },
+            "allowPrerelease": { "type": "boolean" }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type", "format"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "calver" },
+            "format": {
+              "type": "string",
+              "description": "Token sequence using YYYY YY MM DD MICRO, e.g. YYYY.MM.MICRO."
+            }
+          }
+        },
+        {
+          "type": "object",
+          "required": ["type"],
+          "additionalProperties": false,
+          "properties": {
+            "type": { "const": "build" },
+            "padding": { "type": "integer", "minimum": 0 }
+          }
+        }
+      ]
+    },
+    "initialVersion": {
+      "type": "string",
+      "description": "Version used when no conforming tag exists yet."
+    },
+    "push": {
+      "type": "boolean",
+      "description": "Default push behaviour for `tagsmith create`."
+    }
+  }
+}