gitxplain 0.1.6 → 0.1.9

package/cli/services/configService.js

@@ -1,7 +1,57 @@
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
+const ENV_CONFIG_KEYS = new Set([
+  "LLM_PROVIDER",
+  "LLM_MODEL",
+  "OPENAI_API_KEY",
+  "OPENAI_MODEL",
+  "OPENAI_BASE_URL",
+  "GROQ_API_KEY",
+  "GROQ_MODEL",
+  "GROQ_BASE_URL",
+  "OPENROUTER_API_KEY",
+  "OPENROUTER_MODEL",
+  "OPENROUTER_BASE_URL",
+  "OPENROUTER_SITE_URL",
+  "OPENROUTER_APP_NAME",
+  "GEMINI_API_KEY",
+  "GEMINI_MODEL",
+  "GEMINI_BASE_URL",
+  "OLLAMA_API_KEY",
+  "OLLAMA_MODEL",
+  "OLLAMA_BASE_URL",
+  "CHUTES_API_KEY",
+  "CHUTES_MODEL",
+  "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 = {
+  openai: "OPENAI_API_KEY",
+  groq: "GROQ_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+  gemini: "GEMINI_API_KEY",
+  ollama: "OLLAMA_API_KEY",
+  chutes: "CHUTES_API_KEY",
+  anthropic: "ANTHROPIC_API_KEY",
+  mistral: "MISTRAL_API_KEY",
+  "azure-openai": "AZURE_OPENAI_API_KEY"
+};
+
 function readJsonConfig(filePath) {
   if (!existsSync(filePath)) {
     return {};
@@ -14,9 +64,16 @@ function readJsonConfig(filePath) {
   }
 }
 
+export function getUserConfigPath() {
+  return path.join(os.homedir(), ".gitxplain", "config.json");
+}
+
+export function loadUserConfig() {
+  return readJsonConfig(getUserConfigPath());
+}
+
 export function loadConfig(cwd) {
-  const homeDir = os.homedir();
-  const userConfigPath = path.join(homeDir, ".gitxplain", "config.json");
+  const userConfigPath = getUserConfigPath();
   const projectConfigPath = path.join(cwd, ".gitxplainrc");
   const projectJsonConfigPath = path.join(cwd, ".gitxplainrc.json");
 
@@ -26,3 +83,34 @@ export function loadConfig(cwd) {
     ...readJsonConfig(projectJsonConfigPath)
   };
 }
+
+export function applyConfigEnvironment(config) {
+  for (const [key, value] of Object.entries(config)) {
+    if (!ENV_CONFIG_KEYS.has(key)) {
+      continue;
+    }
+
+    if (typeof value === "string" && value !== "" && !process.env[key]) {
+      process.env[key] = value;
+    }
+  }
+}
+
+export function getProviderApiKeyField(provider) {
+  const normalized = provider?.toLowerCase();
+  return normalized ? PROVIDER_API_KEY_FIELDS[normalized] ?? null : null;
+}
+
+export function writeUserConfig(nextConfig) {
+  const configPath = getUserConfigPath();
+  mkdirSync(path.dirname(configPath), { recursive: true });
+  writeFileSync(configPath, `${JSON.stringify(nextConfig, null, 2)}\n`, "utf8");
+  return configPath;
+}
+
+export function updateUserConfig(updates) {
+  const currentConfig = loadUserConfig();
+  const nextConfig = { ...currentConfig, ...updates };
+  const configPath = writeUserConfig(nextConfig);
+  return { configPath, config: nextConfig };
+}

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);