gitxplain 0.1.8 → 0.1.9

package/cli/services/configService.js

@@ -24,7 +24,20 @@ const ENV_CONFIG_KEYS = new Set([
   "OLLAMA_BASE_URL",
   "CHUTES_API_KEY",
   "CHUTES_MODEL",
-  "CHUTES_BASE_URL"
+  "CHUTES_BASE_URL",
+  "ANTHROPIC_API_KEY",
+  "ANTHROPIC_MODEL",
+  "ANTHROPIC_BASE_URL",
+  "MISTRAL_API_KEY",
+  "MISTRAL_MODEL",
+  "MISTRAL_BASE_URL",
+  "AZURE_OPENAI_API_KEY",
+  "AZURE_OPENAI_MODEL",
+  "AZURE_OPENAI_BASE_URL",
+  "AZURE_OPENAI_DEPLOYMENT",
+  "AZURE_OPENAI_API_VERSION",
+  "LLM_INPUT_COST_PER_MTOK",
+  "LLM_OUTPUT_COST_PER_MTOK"
 ]);
 
 const PROVIDER_API_KEY_FIELDS = {
@@ -33,7 +46,10 @@ const PROVIDER_API_KEY_FIELDS = {
   openrouter: "OPENROUTER_API_KEY",
   gemini: "GEMINI_API_KEY",
   ollama: "OLLAMA_API_KEY",
-  chutes: "CHUTES_API_KEY"
+  chutes: "CHUTES_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  mistral: "MISTRAL_API_KEY",
+  "azure-openai": "AZURE_OPENAI_API_KEY"
 };
 
 function readJsonConfig(filePath) {

package/cli/services/envLoader.js

@@ -2,7 +2,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 
-export function loadEnvFile() {
+export function loadEnvFile(cwd = process.cwd()) {
   try {
     // Get the directory of the CLI installation
     const __filename = fileURLToPath(import.meta.url);
@@ -11,7 +11,7 @@ export function loadEnvFile() {
     const envPath = path.join(projectDir, ".env");
 
     // Also check current working directory
-    const cwdEnvPath = path.join(process.cwd(), ".env");
+    const cwdEnvPath = path.join(cwd, ".env");
     const finalEnvPath = fs.existsSync(envPath) ? envPath : (fs.existsSync(cwdEnvPath) ? cwdEnvPath : null);
 
     if (finalEnvPath && fs.existsSync(finalEnvPath)) {

package/cli/services/gitService.js

@@ -1,26 +1,9 @@
 import { execFileSync, spawnSync } from "node:child_process";
 import os from "node:os";
-import { mkdtempSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, rmSync, unlinkSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
-
-const ANSI = {
-  reset: "\u001b[0m",
-  green: "\u001b[32m",
-  red: "\u001b[31m"
-};
-
-function supportsColor() {
-  return Boolean(process.stdout?.isTTY) && process.env.NO_COLOR == null;
-}
-
-function colorize(text, color) {
-  if (!supportsColor()) {
-    return text;
-  }
-
-  return `${color}${text}${ANSI.reset}`;
-}
+import { ANSI, colorize } from "./colorSupport.js";
 
 export function runGitCommand(args, cwd) {
   try {
@@ -88,10 +71,20 @@ export function runGitCommandUnchecked(args, cwd) {
 }
 
 export function listGitSubcommands() {
-  const output = execFileSync("git", ["help", "-a"], {
-    encoding: "utf8",
-    stdio: ["ignore", "pipe", "pipe"]
-  });
+  let output;
+  try {
+    output = execFileSync("git", ["help", "-a"], {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("git is not installed or not available in PATH.");
+    }
+
+    const stderr = error.stderr?.toString().trim();
+    throw new Error(stderr || "Unable to list git subcommands.");
+  }
 
   return new Set(
     output
@@ -289,6 +282,36 @@ export function listTags(cwd) {
     .filter(Boolean);
 }
 
+export function listTagTargets(cwd) {
+  const result = runGitCommandUnchecked(["show-ref", "--tags", "-d"], cwd);
+  if (result.exitCode !== 0) {
+    return [];
+  }
+
+  const output = result.stdout;
+  const tagTargets = new Map();
+
+  for (const line of output.split("\n").map((entry) => entry.trim()).filter(Boolean)) {
+    const [sha, ref] = line.split(" ");
+    if (!sha || !ref?.startsWith("refs/tags/")) {
+      continue;
+    }
+
+    const rawTagName = ref.slice("refs/tags/".length);
+    const isDereferenced = rawTagName.endsWith("^{}");
+    const tagName = isDereferenced ? rawTagName.slice(0, -3) : rawTagName;
+    const existing = tagTargets.get(tagName) ?? {};
+
+    tagTargets.set(tagName, {
+      tagName,
+      tagSha: isDereferenced ? existing.tagSha ?? null : sha,
+      targetSha: isDereferenced ? sha : existing.targetSha ?? sha
+    });
+  }
+
+  return [...tagTargets.values()];
+}
+
 export function hasStagedChanges(cwd) {
   const result = runGitCommandUnchecked(["diff", "--cached", "--quiet"], cwd);
 
@@ -666,6 +689,193 @@ function parseUniqueFiles(...groups) {
   return [...new Set(groups.flatMap((group) => group.split("\n").map((line) => line.trim()).filter(Boolean)))];
 }
 
+function buildFileScopedDisplayRef(targetRef, filePath) {
+  return `${targetRef} :: ${filePath}`;
+}
+
+function extractConflictBlocks(fileContent) {
+  const lines = fileContent.split("\n");
+  const blocks = [];
+  let index = 0;
+
+  while (index < lines.length) {
+    if (!lines[index].startsWith("<<<<<<<")) {
+      index += 1;
+      continue;
+    }
+
+    const startLine = index + 1;
+    const currentLabel = lines[index].slice("<<<<<<<".length).trim() || "current";
+    index += 1;
+
+    const currentLines = [];
+    while (index < lines.length && !lines[index].startsWith("=======")) {
+      currentLines.push(lines[index]);
+      index += 1;
+    }
+
+    if (index >= lines.length) {
+      break;
+    }
+
+    index += 1;
+    const incomingLines = [];
+    while (index < lines.length && !lines[index].startsWith(">>>>>>>")) {
+      incomingLines.push(lines[index]);
+      index += 1;
+    }
+
+    if (index >= lines.length) {
+      break;
+    }
+
+    const incomingLabel = lines[index].slice(">>>>>>>".length).trim() || "incoming";
+    const endLine = index + 1;
+    index += 1;
+
+    blocks.push({
+      startLine,
+      endLine,
+      currentLabel,
+      incomingLabel,
+      currentText: currentLines.join("\n"),
+      incomingText: incomingLines.join("\n")
+    });
+  }
+
+  return blocks;
+}
+
+function buildConflictAnalysisDiff(conflicts) {
+  return conflicts
+    .map((fileConflict) => {
+      const blockText = fileConflict.blocks
+        .map(
+          (block, idx) =>
+            [
+              `Conflict ${idx + 1} (${fileConflict.filePath}:${block.startLine}-${block.endLine})`,
+              `Current Side (${block.currentLabel}):`,
+              block.currentText || "<empty>",
+              `Incoming Side (${block.incomingLabel}):`,
+              block.incomingText || "<empty>"
+            ].join("\n")
+        )
+        .join("\n\n");
+
+      return [`File: ${fileConflict.filePath}`, blockText].join("\n");
+    })
+    .join("\n\n");
+}
+
+function formatIsoDateFromUnixTimestamp(value) {
+  const timestampMs = Number.parseInt(value, 10) * 1000;
+  if (Number.isNaN(timestampMs)) {
+    return "unknown-date";
+  }
+
+  return new Date(timestampMs).toISOString().slice(0, 10);
+}
+
+function parseBlamePorcelain(porcelain) {
+  const records = [];
+  const lines = porcelain.split("\n");
+  let index = 0;
+
+  while (index < lines.length) {
+    const header = lines[index]?.trim();
+    if (!header) {
+      index += 1;
+      continue;
+    }
+
+    const headerMatch = header.match(/^([0-9a-f]{7,40}|\^?[0-9a-f]{7,40})\s+\d+\s+(\d+)\s+(\d+)$/i);
+    if (!headerMatch) {
+      index += 1;
+      continue;
+    }
+
+    const [, commitSha, finalLineRaw, lineCountRaw] = headerMatch;
+    const record = {
+      commitSha,
+      finalLine: Number.parseInt(finalLineRaw, 10),
+      lineCount: Number.parseInt(lineCountRaw, 10),
+      author: "Unknown Author",
+      authorMail: "",
+      authorTime: "",
+      summary: "",
+      code: ""
+    };
+
+    index += 1;
+    while (index < lines.length) {
+      const line = lines[index];
+      if (line.startsWith("\t")) {
+        record.code = line.slice(1);
+        index += 1;
+        break;
+      }
+
+      if (line.startsWith("author ")) {
+        record.author = line.slice("author ".length).trim();
+      } else if (line.startsWith("author-mail ")) {
+        record.authorMail = line.slice("author-mail ".length).trim();
+      } else if (line.startsWith("author-time ")) {
+        record.authorTime = line.slice("author-time ".length).trim();
+      } else if (line.startsWith("summary ")) {
+        record.summary = line.slice("summary ".length).trim();
+      }
+
+      index += 1;
+    }
+
+    records.push(record);
+  }
+
+  return records;
+}
+
+function buildBlameAnalysisDiff(filePath, records) {
+  const byAuthor = new Map();
+
+  for (const record of records) {
+    const key = `${record.author}|${record.authorMail}`;
+    const existing = byAuthor.get(key) ?? {
+      author: record.author,
+      authorMail: record.authorMail,
+      lineCount: 0,
+      commitShas: new Set(),
+      summaries: new Set()
+    };
+
+    existing.lineCount += 1;
+    existing.commitShas.add(record.commitSha);
+    if (record.summary) {
+      existing.summaries.add(record.summary);
+    }
+    byAuthor.set(key, existing);
+  }
+
+  const authorSection = [...byAuthor.values()]
+    .sort((left, right) => right.lineCount - left.lineCount)
+    .map(
+      (entry) =>
+        `- ${entry.author}${entry.authorMail ? ` ${entry.authorMail}` : ""}: ${entry.lineCount} line(s), ${entry.commitShas.size} commit(s), notable commits: ${[...entry.summaries].slice(0, 3).join("; ") || "n/a"}`
+    )
+    .join("\n");
+
+  const lineSection = records
+    .map((record) => {
+      const endLine = record.finalLine + record.lineCount - 1;
+      const lineLabel = record.lineCount > 1 ? `L${record.finalLine}-L${endLine}` : `L${record.finalLine}`;
+      const shortSha = record.commitSha.replace(/^\^/, "").slice(0, 8);
+      const authorDate = formatIsoDateFromUnixTimestamp(record.authorTime);
+      return `${lineLabel} | ${record.author} | ${authorDate} | ${shortSha} | ${record.summary || "no summary"} | ${record.code}`;
+    })
+    .join("\n");
+
+  return [`Blame summary for ${filePath}`, "", "Authors:", authorSection || "- none", "", "Line annotations:", lineSection].join("\n");
+}
+
 export function fetchWorkingTreeData(cwd) {
   const stagedDiff = getUncheckedCommandOutput(["diff", "--cached"], cwd);
   const unstagedDiff = getUncheckedCommandOutput(["diff"], cwd);
@@ -708,6 +918,87 @@ export function fetchWorkingTreeData(cwd) {
   };
 }
 
+export function fetchBlameData(filePath, cwd, runner = runGitCommand) {
+  const porcelain = runner(["blame", "--line-porcelain", "--", filePath], cwd);
+  const records = parseBlamePorcelain(porcelain);
+  const authorCount = new Set(records.map((record) => `${record.author}|${record.authorMail}`)).size;
+
+  return {
+    analysisType: "blame",
+    targetRef: `blame:${filePath}`,
+    displayRef: filePath,
+    commitId: null,
+    commitCount: records.length,
+    commits: [],
+    commitMessage: `Blame analysis for ${filePath}`,
+    diff: buildBlameAnalysisDiff(filePath, records),
+    filesChanged: [filePath],
+    stats: `${records.length} line annotation${records.length === 1 ? "" : "s"} across ${authorCount} author${authorCount === 1 ? "" : "s"}`
+  };
+}
+
+export function fetchStashData(stashRef = null, cwd, filePath = null, runner = runGitCommand) {
+  const resolvedStashRef = resolveStashRef(stashRef);
+  const fileArgs = filePath ? ["--", filePath] : [];
+  const commitMessage = runner(["log", "-1", "--pretty=format:%gs", resolvedStashRef], cwd);
+  const diff = runner(["stash", "show", "-p", resolvedStashRef, ...fileArgs], cwd);
+  const filesChangedRaw = runner(["stash", "show", "--name-only", resolvedStashRef, ...fileArgs], cwd);
+  const statsRaw = runner(["stash", "show", "--stat", resolvedStashRef, ...fileArgs], cwd);
+
+  return {
+    analysisType: "stash",
+    targetRef: resolvedStashRef,
+    displayRef: filePath ? buildFileScopedDisplayRef(resolvedStashRef, filePath) : resolvedStashRef,
+    commitId: resolvedStashRef,
+    commitCount: 1,
+    commits: [{ hash: resolvedStashRef, subject: commitMessage, body: commitMessage }],
+    commitMessage: commitMessage || `Stash entry ${resolvedStashRef}`,
+    diff,
+    filesChanged: parseFilesChanged(filesChangedRaw),
+    stats: parseStatsLine(statsRaw)
+  };
+}
+
+export function fetchConflictData(cwd, filePath = null, runner = runGitCommand) {
+  const fileArgs = filePath ? ["--", filePath] : [];
+  const conflictedFilesRaw = runner(["diff", "--name-only", "--diff-filter=U", ...fileArgs], cwd);
+  const conflictedFiles = parseFilesChanged(conflictedFilesRaw);
+
+  if (conflictedFiles.length === 0) {
+    throw new Error(filePath ? `No unresolved merge conflicts found for ${filePath}.` : "No unresolved merge conflicts found in the working tree.");
+  }
+
+  const conflicts = conflictedFiles.map((relativePath) => {
+    const absolutePath = path.resolve(cwd, relativePath);
+    const content = readFileSync(absolutePath, "utf8");
+    const blocks = extractConflictBlocks(content);
+
+    return {
+      filePath: relativePath,
+      blocks
+    };
+  }).filter((entry) => entry.blocks.length > 0);
+
+  if (conflicts.length === 0) {
+    throw new Error(filePath ? `Conflict markers were not found in ${filePath}.` : "Git reports unresolved conflicts, but no conflict markers were found in the conflicted files.");
+  }
+
+  const conflictCount = conflicts.reduce((sum, entry) => sum + entry.blocks.length, 0);
+
+  return {
+    analysisType: "conflict",
+    targetRef: filePath ? `conflict:${filePath}` : "conflict",
+    displayRef: filePath ?? "working-tree conflicts",
+    commitId: null,
+    commitCount: conflictCount,
+    commits: [],
+    commitMessage: filePath ? `Merge conflict analysis for ${filePath}` : "Merge conflict analysis for the working tree",
+    diff: buildConflictAnalysisDiff(conflicts),
+    filesChanged: conflicts.map((entry) => entry.filePath),
+    stats: `${conflictCount} conflict block${conflictCount === 1 ? "" : "s"} across ${conflicts.length} file${conflicts.length === 1 ? "" : "s"}`
+  };
+}
+
 function fetchSingleCommitData(commitId, cwd, runner) {
   const commitMessage = runner(["log", "-1", "--pretty=format:%B", commitId], cwd);
   const diff = runner(["diff", `${commitId}^!`], cwd);
@@ -729,6 +1020,27 @@ function fetchSingleCommitData(commitId, cwd, runner) {
   };
 }
 
+function fetchSingleCommitFileData(commitId, filePath, cwd, runner) {
+  const commitMessage = runner(["log", "-1", "--pretty=format:%B", commitId], cwd);
+  const diff = runner(["diff", `${commitId}^!`, "--", filePath], cwd);
+  const filesChangedRaw = runner(["show", "--pretty=format:", "--name-only", commitId, "--", filePath], cwd);
+  const statsRaw = runner(["show", "--stat", "--oneline", "--format=%h %s", commitId, "--", filePath], cwd);
+  const subject = runner(["log", "-1", "--pretty=format:%s", commitId], cwd);
+
+  return {
+    analysisType: "commit",
+    targetRef: commitId,
+    displayRef: buildFileScopedDisplayRef(commitId, filePath),
+    commitId,
+    commitCount: 1,
+    commits: [{ hash: commitId, subject, body: commitMessage }],
+    commitMessage,
+    diff,
+    filesChanged: parseFilesChanged(filesChangedRaw),
+    stats: parseStatsLine(statsRaw)
+  };
+}
+
 function fetchRangeData(rangeRef, cwd, runner) {
   const diff = runner(["diff", rangeRef], cwd);
   const filesChangedRaw = runner(["diff", "--name-only", rangeRef], cwd);
@@ -757,8 +1069,42 @@ function fetchRangeData(rangeRef, cwd, runner) {
   };
 }
 
+function fetchRangeFileData(rangeRef, filePath, cwd, runner) {
+  const diff = runner(["diff", rangeRef, "--", filePath], cwd);
+  const filesChangedRaw = runner(["diff", "--name-only", rangeRef, "--", filePath], cwd);
+  const statsRaw = runner(["diff", "--stat", rangeRef, "--", filePath], cwd);
+  const commitLogRaw = runner(
+    ["log", "--reverse", "--pretty=format:%H%x1f%s%x1f%B", rangeRef, "--", filePath],
+    cwd
+  );
+
+  const commits = parseCommitLog(commitLogRaw);
+  if (commits.length === 0) {
+    throw new Error(`No commits found in range ${rangeRef} for file ${filePath}`);
+  }
+
+  return {
+    analysisType: "range",
+    targetRef: rangeRef,
+    displayRef: buildFileScopedDisplayRef(rangeRef, filePath),
+    commitId: null,
+    commitCount: commits.length,
+    commits,
+    commitMessage: buildCommitMessage(commits),
+    diff,
+    filesChanged: parseFilesChanged(filesChangedRaw),
+    stats: parseStatsLine(statsRaw)
+  };
+}
+
 export function fetchCommitData(targetRef, cwd, runner = runGitCommand) {
   return isRangeRef(targetRef)
     ? fetchRangeData(targetRef, cwd, runner)
     : fetchSingleCommitData(targetRef, cwd, runner);
 }
+
+export function fetchCommitDataForFile(targetRef, filePath, cwd, runner = runGitCommand) {
+  return isRangeRef(targetRef)
+    ? fetchRangeFileData(targetRef, filePath, cwd, runner)
+    : fetchSingleCommitFileData(targetRef, filePath, cwd, runner);
+}

package/cli/services/hookService.js

@@ -1,7 +1,34 @@
-import { chmodSync, mkdirSync, writeFileSync } from "node:fs";
+import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { runGitCommand } from "./gitService.js";
 
+const HOOK_MARKER = "# gitxplain-hook";
+
+function buildHookScript(hookName, outputDir) {
+  if (hookName === "post-commit") {
+    return `#!/bin/sh
+${HOOK_MARKER}
+gitxplain HEAD --summary --markdown --quiet > "${path.join(outputDir, "last-explanation.md")}" 2>/dev/null || true
+`;
+  }
+
+  if (hookName === "post-merge") {
+    return `#!/bin/sh
+${HOOK_MARKER}
+gitxplain HEAD --summary --markdown --quiet > "${path.join(outputDir, "last-merge-explanation.md")}" 2>/dev/null || true
+`;
+  }
+
+  if (hookName === "pre-push") {
+    return `#!/bin/sh
+${HOOK_MARKER}
+gitxplain HEAD --security --markdown --quiet > "${path.join(outputDir, "last-pre-push-security.md")}" 2>/dev/null || true
+`;
+  }
+
+  throw new Error(`Unsupported hook "${hookName}". Supported hooks: post-commit, post-merge, pre-push.`);
+}
+
 export function installHook({ cwd, hookName = "post-commit" }) {
   const gitDir = runGitCommand(["rev-parse", "--git-dir"], cwd);
   const hookDir = path.resolve(cwd, gitDir, "hooks");
@@ -11,9 +38,14 @@ export function installHook({ cwd, hookName = "post-commit" }) {
   mkdirSync(hookDir, { recursive: true });
   mkdirSync(outputDir, { recursive: true });
 
-  const script = `#!/bin/sh
-gitxplain HEAD --summary --markdown --quiet > "${path.join(outputDir, "last-explanation.md")}" 2>/dev/null || true
-`;
+  const script = buildHookScript(hookName, outputDir);
+
+  if (existsSync(hookPath)) {
+    const existing = readFileSync(hookPath, "utf8");
+    if (!existing.includes(HOOK_MARKER)) {
+      throw new Error(`Hook ${hookName} already exists at ${hookPath}. Refusing to overwrite a non-gitxplain hook.`);
+    }
+  }
 
   writeFileSync(hookPath, script, "utf8");
   chmodSync(hookPath, 0o755);

package/cli/services/mergeService.js

@@ -1,4 +1,3 @@
-import process from "node:process";
 import {
   createCommitFromTree,
   getCommitMetadata,
@@ -15,19 +14,13 @@ import {
   listBranchCommits,
   listCommitsAfter,
   listTags,
+  listTagTargets,
   localBranchExists,
   resolveTreeSha,
   resolveCommitSha,
   runGitCommand
 } from "./gitService.js";
-
-const ANSI = {
-  reset: "\u001b[0m",
-  bold: "\u001b[1m",
-  cyan: "\u001b[36m",
-  yellow: "\u001b[33m",
-  green: "\u001b[32m"
-};
+import { ANSI, colorize } from "./colorSupport.js";
 
 const RELEASE_BRANCH = "release";
 const VERSION_PATTERN = /\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?\b/g;
@@ -36,18 +29,6 @@ const SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$
 const INTEGER_PATTERN = /^\d+$/;
 const TAG_VERSION_PATTERN = /^v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?|\d+)$/;
 
-function supportsColor() {
-  return Boolean(process.stdout?.isTTY) && process.env.NO_COLOR == null;
-}
-
-function colorize(text, color) {
-  if (!supportsColor()) {
-    return text;
-  }
-
-  return `${color}${text}${ANSI.reset}`;
-}
-
 function unique(values) {
   return [...new Set(values)];
 }
@@ -335,21 +316,38 @@ export function selectReleaseWindows(sourceCommits, releaseCommits = []) {
   };
 }
 
-export function selectReleaseTags(sourceCommits, existingTagNames = []) {
+export function selectReleaseTags(sourceCommits, existingTagNames = [], existingTagTargets = []) {
   const windows = selectLatestWindowsPerVersion(buildReleaseWindows(sourceCommits));
   const taggedVersions = extractTaggedVersions(existingTagNames);
+  const targetByVersion = new Map(
+    existingTagTargets
+      .map((tag) => {
+        const version = tag.tagName?.match(TAG_VERSION_PATTERN)?.[1] ?? null;
+        return version ? [version, tag.targetSha] : null;
+      })
+      .filter(Boolean)
+  );
   const tags = windows
-    .filter((window) => !taggedVersions.has(window.version))
     .map((window) => {
       const targetCommit = window.commits.at(-1) ?? null;
+      const existingTargetSha = targetByVersion.get(window.version) ?? null;
+      const windowCommitShas = new Set(window.commits.map((commit) => commit.sha));
+
       return {
         ...window,
         tagName: window.version,
+        existingTargetSha,
+        needsMove:
+          existingTargetSha != null &&
+          targetCommit?.sha != null &&
+          windowCommitShas.has(existingTargetSha) &&
+          existingTargetSha !== targetCommit.sha,
         targetSha: targetCommit?.sha ?? null,
         targetShortSha: targetCommit?.shortSha ?? null,
         targetSubject: targetCommit?.subject ?? null
       };
     })
+    .filter((tag) => !taggedVersions.has(tag.version) || tag.needsMove)
     .filter((tag) => tag.targetSha != null);
 
   return {
@@ -370,7 +368,8 @@ function findLatestTaggedSourceVersion(sourceCommits, taggedVersions) {
 function buildReleaseTagPlanForSource(sourceBranch, sourceRef, cwd) {
   const sourceCommits = listBranchCommits(sourceRef, cwd).map((sha) => inspectCommit(sha, cwd));
   const existingTagNames = listTags(cwd);
-  const selection = selectReleaseTags(sourceCommits, existingTagNames);
+  const existingTagTargets = listTagTargets(cwd);
+  const selection = selectReleaseTags(sourceCommits, existingTagNames, existingTagTargets);
 
   return {
     sourceBranch,
@@ -655,15 +654,18 @@ export function formatReleaseTagPlan(plan) {
   ];
 
   if (plan.tags.length === 0) {
-    lines.push(colorize("No unreleased release tags detected. Nothing to tag.", ANSI.green));
+    lines.push(colorize("No release tag changes detected. Nothing to tag.", ANSI.green));
     return lines.join("\n");
   }
 
   for (const tag of plan.tags) {
     lines.push("");
-    lines.push(colorize(`tag ${tag.tagName}`, ANSI.bold + ANSI.yellow));
+    lines.push(colorize(`${tag.needsMove ? "move tag" : "tag"} ${tag.tagName}`, ANSI.bold + ANSI.yellow));
     lines.push(`${colorize("Commit Range:", ANSI.bold + ANSI.cyan)} ${tag.startRef}..${tag.endRef}`);
     lines.push(`${colorize("Target Commit:", ANSI.bold + ANSI.cyan)} ${tag.targetShortSha} ${tag.targetSubject}`);
+    if (tag.needsMove) {
+      lines.push(`${colorize("Action:", ANSI.bold + ANSI.cyan)} move existing tag to the latest commit for ${tag.tagName}`);
+    }
 
     for (const commit of tag.commits) {
       lines.push(`${colorize(commit.shortSha, ANSI.bold + ANSI.cyan)} ${commit.subject}`);
@@ -817,13 +819,17 @@ export function executeReleaseMerge(plan, cwd) {
 
 export function executeReleaseTagPlan(plan, cwd) {
   if (plan.tags.length === 0) {
-    throw new Error("No unreleased release tags detected. Nothing to tag.");
+    throw new Error("No release tag changes detected. Nothing to tag.");
   }
 
   const createdTags = [];
 
   try {
     for (const tag of plan.tags) {
+      if (tag.needsMove) {
+        gitDeleteTag(tag.tagName, cwd);
+      }
+
       gitCreateAnnotatedTag(tag.tagName, tag.targetSha, `release ${tag.tagName}`, cwd);
       createdTags.push(tag.tagName);
     }