gitxplain 0.1.0

package/.env.example

@@ -0,0 +1,28 @@
+LLM_PROVIDER=openai
+LLM_MODEL=
+
+OPENAI_API_KEY=
+OPENAI_MODEL=gpt-4.1-mini
+OPENAI_BASE_URL=https://api.openai.com/v1
+
+GROQ_API_KEY=
+GROQ_MODEL=llama-3.3-70b-versatile
+GROQ_BASE_URL=https://api.groq.com/openai/v1
+
+OPENROUTER_API_KEY=
+OPENROUTER_MODEL=openai/gpt-4.1-mini
+OPENROUTER_BASE_URL=https://openrouter.ai/api/v1
+OPENROUTER_SITE_URL=https://github.com
+OPENROUTER_APP_NAME=gitxplain
+
+GEMINI_API_KEY=
+GEMINI_MODEL=gemini-2.5-flash
+GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta
+
+OLLAMA_API_KEY=ollama
+OLLAMA_MODEL=llama3.2
+OLLAMA_BASE_URL=http://127.0.0.1:11434/v1
+
+CHUTES_API_KEY=
+CHUTES_MODEL=deepseek-ai/DeepSeek-V3-0324
+CHUTES_BASE_URL=https://llm.chutes.ai/v1

package/README.md

@@ -0,0 +1,268 @@
+# gitxplain
+
+`gitxplain` is a Node.js CLI that analyzes Git commits, commit ranges, and branch diffs to generate structured, human-readable explanations with AI.
+
+Supported providers:
+
+- OpenAI
+- Groq
+- OpenRouter
+- Gemini
+- Ollama
+- Chutes AI
+
+## Features
+
+- Explains what a commit does, why it exists, and how the fix works
+- Supports focused output modes like summary, issue, fix, impact, review, security, and line-by-line walkthroughs
+- Supports single commits, commit ranges, and branch-vs-base comparisons
+- Truncates oversized diffs before sending them to the model and reports that truncation
+- Streams output for supported providers
+- Caches responses locally to reduce repeat API costs
+- Supports plain, JSON, Markdown, and HTML output
+- Supports clipboard copy, verbosity controls, and hook installation
+- Supports project-level and user-level config files
+- Falls back to an interactive prompt when no analysis flag is supplied
+- Returns plain text or JSON output
+- Uses native Node APIs only, so the MVP has no runtime dependencies
+
+## Requirements
+
+- Node.js 18+
+- A Git repository in your current working directory
+- An API key for your chosen provider, or a local Ollama instance
+
+Optional environment variables:
+
+- `LLM_PROVIDER` default: `openai`
+- `LLM_MODEL` optional shared model override
+- `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` optional, default: `ollama`
+- `OLLAMA_MODEL`, `OLLAMA_BASE_URL` default: `http://127.0.0.1:11434/v1`
+- `CHUTES_API_KEY`, `CHUTES_MODEL`, `CHUTES_BASE_URL`
+
+Optional config files:
+
+- Project: `.gitxplainrc` or `.gitxplainrc.json`
+- User: `~/.gitxplain/config.json`
+
+You can start from:
+
+```bash
+cp .env.example .env
+```
+
+## Usage
+
+```bash
+gitxplain help
+gitxplain <commit-id>
+gitxplain <commit-id> --summary
+gitxplain <commit-id> --issues
+gitxplain <commit-id> --fix
+gitxplain <commit-id> --impact
+gitxplain <commit-id> --full
+gitxplain <commit-id> --lines
+gitxplain <commit-id> --review
+gitxplain <commit-id> --security
+gitxplain <commit-id> --json
+gitxplain <commit-id> --markdown
+gitxplain <commit-id> --html
+gitxplain <commit-id> --stream
+gitxplain <commit-id> --clipboard
+gitxplain <commit-id> --verbose
+gitxplain <commit-id> --quiet
+gitxplain <start>..<end> --markdown
+gitxplain --branch main --review
+gitxplain --pr origin/main --security
+gitxplain install-hook
+gitxplain <commit-id> --provider openrouter --model anthropic/claude-3.7-sonnet
+gitxplain <commit-id> --provider chutes --model deepseek-ai/DeepSeek-V3-0324
+```
+
+Examples:
+
+```bash
+npm start -- HEAD~1 --summary
+npm start -- a1b2c3d --full
+npm start -- HEAD~1 --lines
+npm start -- HEAD~5..HEAD --markdown
+npm start -- --branch main --review
+npm start -- HEAD~1 --provider groq --model llama-3.3-70b-versatile
+npm start -- HEAD~1 --provider gemini --model gemini-2.5-flash
+npm start -- HEAD~1 --provider chutes --model deepseek-ai/DeepSeek-V3-0324
+```
+
+## Running The CLI
+
+To use the actual `gitxplain` command directly:
+
+```bash
+cd /home/guru/Dev/gitxplain
+npm link
+```
+
+Then from any Git repository:
+
+```bash
+gitxplain help
+gitxplain HEAD~1 --full
+gitxplain a1b2c3d --summary
+gitxplain HEAD~1 --lines
+gitxplain HEAD~5..HEAD --markdown
+gitxplain --branch main --review
+```
+
+The `gitxplain help` command also prints quick API-key setup examples for:
+
+- OpenAI
+- Groq
+- OpenRouter
+- Gemini
+- Ollama
+- Chutes AI
+
+If you do not want to link it globally, you can still run it locally:
+
+```bash
+node /home/guru/Dev/gitxplain/cli/index.js HEAD~1 --full
+```
+
+## Output Modes
+
+- `--summary`: one-sentence commit summary
+- `--issues`: bug or issue-oriented analysis
+- `--fix`: junior-friendly explanation of the fix
+- `--impact`: before-vs-after explanation focused on behavior changes
+- `--full`: full structured analysis
+- `--lines`: file-by-file, line-by-line walkthrough of the changed code
+- `--review`: code review findings with actionable suggestions
+- `--security`: security-focused analysis of the change
+- `--json`: return structured JSON instead of formatted text
+- `--markdown`: return Markdown output
+- `--html`: return HTML output
+
+If no analysis flag is supplied, the CLI asks what kind of explanation you want.
+
+## Comparison Modes
+
+Single commit:
+
+```bash
+gitxplain HEAD~1 --full
+```
+
+Commit range:
+
+```bash
+gitxplain HEAD~5..HEAD --markdown
+```
+
+Branch or PR-style comparison:
+
+```bash
+gitxplain --branch main --review
+gitxplain --pr origin/main --security
+```
+
+`--branch` and `--pr` compare the current branch to a base ref using the merge base with `HEAD`.
+
+## Config File
+
+Example `.gitxplainrc`:
+
+```json
+{
+  "provider": "groq",
+  "model": "llama-3.3-70b-versatile",
+  "mode": "full",
+  "format": "markdown",
+  "maxDiffLines": 600,
+  "stream": true,
+  "verbose": false
+}
+```
+
+CLI flags still override config values for a single command.
+
+## Clipboard, Streaming, And Hooks
+
+Copy the final output to your clipboard:
+
+```bash
+gitxplain HEAD~1 --markdown --clipboard
+```
+
+Stream long responses as they arrive:
+
+```bash
+gitxplain HEAD~1 --full --stream
+```
+
+Install a post-commit hook that saves a Markdown explanation under `.git/gitxplain/last-explanation.md`:
+
+```bash
+gitxplain install-hook
+```
+
+## Provider Setup
+
+OpenAI:
+
+```bash
+export LLM_PROVIDER=openai
+export OPENAI_API_KEY=your_key
+```
+
+Groq:
+
+```bash
+export LLM_PROVIDER=groq
+export GROQ_API_KEY=your_key
+```
+
+OpenRouter:
+
+```bash
+export LLM_PROVIDER=openrouter
+export OPENROUTER_API_KEY=your_key
+```
+
+Gemini:
+
+```bash
+export LLM_PROVIDER=gemini
+export GEMINI_API_KEY=your_key
+```
+
+Ollama:
+
+```bash
+export LLM_PROVIDER=ollama
+export OLLAMA_MODEL=llama3.2
+```
+
+Chutes AI:
+
+```bash
+export LLM_PROVIDER=chutes
+export CHUTES_API_KEY=your_key
+export CHUTES_MODEL=deepseek-ai/DeepSeek-V3-0324
+```
+
+## Development
+
+```bash
+npm run lint
+npm test
+```
+
+To make the command globally available during local development:
+
+```bash
+npm link
+```

package/cli/index.js

@@ -0,0 +1,413 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import process from "node:process";
+import { fileURLToPath } from "node:url";
+import { realpathSync } from "node:fs";
+import { generateExplanation } from "./services/aiService.js";
+import { copyToClipboard } from "./services/clipboardService.js";
+import { loadConfig } from "./services/configService.js";
+import {
+  buildBranchRange,
+  fetchCommitData,
+  getDefaultBaseRef,
+  isGitRepository
+} from "./services/gitService.js";
+import { installHook } from "./services/hookService.js";
+import {
+  formatFooter,
+  formatHtmlOutput,
+  formatJsonOutput,
+  formatMarkdownOutput,
+  formatOutput,
+  formatPreamble
+} from "./services/outputFormatter.js";
+
+const MODE_FLAGS = new Map([
+  ["--summary", "summary"],
+  ["--issues", "issues"],
+  ["--fix", "fix"],
+  ["--impact", "impact"],
+  ["--full", "full"],
+  ["--lines", "lines"],
+  ["--review", "review"],
+  ["--security", "security"]
+]);
+
+const FORMAT_FLAGS = new Map([
+  ["--json", "json"],
+  ["--markdown", "markdown"],
+  ["--html", "html"]
+]);
+
+function printHelp() {
+  console.log(`gitxplain - AI-powered Git and branch explainer
+
+Usage:
+  gitxplain help
+  gitxplain --help
+  gitxplain install-hook [hook-name]
+  gitxplain <commit-id> [options]
+  gitxplain <start>..<end> [options]
+  gitxplain --branch [base-ref] [options]
+  gitxplain --pr [base-ref] [options]
+
+Modes:
+  --summary    Generate a one-line summary
+  --issues     Focus on bug or issue analysis
+  --fix        Explain the fix in simple terms
+  --impact     Explain before-vs-after behavior changes
+  --full       Generate a full structured analysis
+  --lines      Explain the changed code line by line
+  --review     Generate a code review with risks and suggestions
+  --security   Focus on security risks introduced by the change
+
+Output:
+  --json       Print JSON output
+  --markdown   Print Markdown output
+  --html       Print HTML output
+  --quiet      Print only the explanation body
+  --verbose    Print provider, model, cache, latency, and usage details
+  --clipboard  Copy the final output to the system clipboard
+  --stream     Stream the explanation as it is generated when supported
+
+Providers:
+  --provider   LLM provider: openai, groq, openrouter, gemini, ollama, chutes
+  --model      Override the model name
+
+Diff Budget:
+  --max-diff-lines <n>   Limit diff lines sent to the model
+
+Comparison:
+  --branch [base-ref]    Analyze current branch against base branch
+  --pr [base-ref]        Alias for --branch, useful for PR-style summaries
+
+Examples:
+  gitxplain HEAD~1 --full
+  gitxplain HEAD~5..HEAD --markdown
+  gitxplain --branch main --review
+  gitxplain --pr origin/main --security --stream
+  gitxplain HEAD~1 --provider chutes --model deepseek-ai/DeepSeek-V3-0324
+
+Provider Setup:
+  OpenAI:
+    export LLM_PROVIDER=openai
+    export OPENAI_API_KEY=your_key
+
+  Groq:
+    export LLM_PROVIDER=groq
+    export GROQ_API_KEY=your_key
+
+  OpenRouter:
+    export LLM_PROVIDER=openrouter
+    export OPENROUTER_API_KEY=your_key
+
+  Gemini:
+    export LLM_PROVIDER=gemini
+    export GEMINI_API_KEY=your_key
+
+  Ollama:
+    export LLM_PROVIDER=ollama
+    export OLLAMA_MODEL=llama3.2
+
+  Chutes:
+    export LLM_PROVIDER=chutes
+    export CHUTES_API_KEY=your_key
+
+Config:
+  Project config: .gitxplainrc or .gitxplainrc.json
+  User config: ~/.gitxplain/config.json
+
+Hook Installation:
+  gitxplain install-hook
+  gitxplain install-hook post-commit
+
+Notes:
+  Run gitxplain inside a Git repository.
+  Use --provider or --model to override your config or environment for one command.
+`);
+}
+
+function getFlagValue(args, flagName) {
+  const directIndex = args.findIndex((arg) => arg === flagName);
+  if (directIndex >= 0) {
+    const nextArg = args[directIndex + 1];
+    if (nextArg && !nextArg.startsWith("--")) {
+      return nextArg;
+    }
+
+    return null;
+  }
+
+  const inline = args.find((arg) => arg.startsWith(`${flagName}=`));
+  return inline ? inline.slice(flagName.length + 1) : null;
+}
+
+function parseNumber(value, fallback = null) {
+  if (value == null || value === "") {
+    return fallback;
+  }
+
+  const parsed = Number.parseInt(value, 10);
+  if (Number.isNaN(parsed) || parsed <= 0) {
+    throw new Error(`Invalid numeric value: ${value}`);
+  }
+
+  return parsed;
+}
+
+export function parseArgs(argv) {
+  const args = argv.slice(2);
+  const subcommand = args[0];
+  const flags = new Set(args.filter((arg) => arg.startsWith("--")));
+  const valueFlags = new Set(["--provider", "--model", "--max-diff-lines", "--branch", "--pr"]);
+  const positional = [];
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (!arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+
+    if (arg.includes("=")) {
+      continue;
+    }
+
+    if (valueFlags.has(arg)) {
+      const nextArg = args[index + 1];
+      if (nextArg && !nextArg.startsWith("--")) {
+        index += 1;
+      }
+    }
+  }
+
+  const explicitMode = [...MODE_FLAGS.entries()].find(([flag]) => flags.has(flag))?.[1] ?? null;
+  const explicitFormat = [...FORMAT_FLAGS.entries()].find(([flag]) => flags.has(flag))?.[1] ?? null;
+  const isInstallHook = subcommand === "install-hook";
+
+  return {
+    subcommand,
+    help: flags.has("--help") || subcommand === "help",
+    installHook: isInstallHook,
+    hookName: isInstallHook ? positional[1] ?? "post-commit" : null,
+    commitRef: isInstallHook || subcommand === "help" ? null : positional[0] ?? null,
+    mode: explicitMode,
+    format: explicitFormat,
+    provider: getFlagValue(args, "--provider"),
+    model: getFlagValue(args, "--model"),
+    maxDiffLines: parseNumber(getFlagValue(args, "--max-diff-lines")),
+    hasBranchFlag: flags.has("--branch") || args.some((arg) => arg.startsWith("--branch=")),
+    branchBase: getFlagValue(args, "--branch"),
+    hasPrFlag: flags.has("--pr") || args.some((arg) => arg.startsWith("--pr=")),
+    prBase: getFlagValue(args, "--pr"),
+    clipboard: flags.has("--clipboard"),
+    stream: flags.has("--stream"),
+    verbose: flags.has("--verbose"),
+    quiet: flags.has("--quiet")
+  };
+}
+
+function askQuestion(prompt) {
+  return new Promise((resolve) => {
+    process.stdout.write(prompt);
+    process.stdin.resume();
+    process.stdin.setEncoding("utf8");
+    process.stdin.once("data", (input) => {
+      process.stdin.pause();
+      resolve(input.trim());
+    });
+  });
+}
+
+async function chooseModeInteractively() {
+  const answer = await askQuestion(
+    [
+      "What do you want to know?",
+      "1. Summary",
+      "2. Issues Fixed",
+      "3. Fix Explanation",
+      "4. Impact",
+      "5. Full Analysis",
+      "6. Line-by-Line Code Walkthrough",
+      "7. Code Review",
+      "8. Security Review",
+      "> "
+    ].join("\n")
+  );
+
+  const selections = {
+    "1": "summary",
+    "2": "issues",
+    "3": "fix",
+    "4": "impact",
+    "5": "full",
+    "6": "lines",
+    "7": "review",
+    "8": "security"
+  };
+
+  return selections[answer] ?? "full";
+}
+
+function resolveRuntimeOptions(parsed, config) {
+  return {
+    mode: parsed.mode ?? config.mode ?? "full",
+    format: parsed.format ?? config.format ?? "plain",
+    provider: parsed.provider ?? config.provider ?? null,
+    model: parsed.model ?? config.model ?? null,
+    maxDiffLines: parsed.maxDiffLines ?? config.maxDiffLines ?? 800,
+    clipboard: parsed.clipboard || config.clipboard === true,
+    stream: parsed.stream || config.stream === true,
+    verbose: parsed.verbose || config.verbose === true,
+    quiet: parsed.quiet || config.quiet === true
+  };
+}
+
+function resolveTargetRef(parsed, cwd) {
+  if (parsed.commitRef) {
+    return parsed.commitRef;
+  }
+
+  if (parsed.hasBranchFlag || parsed.hasPrFlag) {
+    const baseRef = parsed.branchBase || parsed.prBase || getDefaultBaseRef(cwd);
+    return buildBranchRange(baseRef, cwd);
+  }
+
+  return null;
+}
+
+function renderFinalOutput({ runtimeOptions, mode, commitData, explanation, responseMeta, promptMeta }) {
+  if (runtimeOptions.format === "json") {
+    return formatJsonOutput({ mode, commitData, explanation, responseMeta, promptMeta });
+  }
+
+  if (runtimeOptions.format === "markdown") {
+    return formatMarkdownOutput({ mode, commitData, explanation, responseMeta, promptMeta });
+  }
+
+  if (runtimeOptions.format === "html") {
+    return formatHtmlOutput({ mode, commitData, explanation, responseMeta, promptMeta });
+  }
+
+  return formatOutput({
+    mode,
+    commitData,
+    explanation,
+    responseMeta,
+    promptMeta,
+    options: runtimeOptions
+  });
+}
+
+export async function main(argv = process.argv) {
+  const cwd = process.cwd();
+  const config = loadConfig(cwd);
+  const parsed = parseArgs(argv);
+
+  if (parsed.help) {
+    printHelp();
+    return 0;
+  }
+
+  if (!isGitRepository(cwd)) {
+    console.error("gitxplain must be run inside a Git repository.");
+    return 1;
+  }
+
+  if (parsed.installHook) {
+    const hookPath = installHook({ cwd, hookName: parsed.hookName });
+    console.log(`Installed ${parsed.hookName} hook at ${hookPath}`);
+    return 0;
+  }
+
+  const runtimeOptions = resolveRuntimeOptions(parsed, config);
+  const targetRef = resolveTargetRef(parsed, cwd);
+
+  if (!targetRef) {
+    printHelp();
+    return 1;
+  }
+
+  const mode = parsed.mode ?? config.mode ?? (await chooseModeInteractively());
+  const commitData = fetchCommitData(targetRef, cwd);
+  const canStream = runtimeOptions.stream && runtimeOptions.format === "plain";
+  let streamStarted = false;
+
+  const { explanation, responseMeta, promptMeta } = await generateExplanation({
+    mode,
+    commitData,
+    providerOverride: runtimeOptions.provider,
+    modelOverride: runtimeOptions.model,
+    maxDiffLines: runtimeOptions.maxDiffLines,
+    stream: canStream,
+    onStart: canStream
+      ? ({ promptMeta: streamPromptMeta }) => {
+          if (!runtimeOptions.quiet && !streamStarted) {
+            process.stdout.write(
+              formatPreamble({
+                mode,
+                commitData,
+                responseMeta: null,
+                promptMeta: streamPromptMeta,
+                options: runtimeOptions
+              })
+            );
+            streamStarted = true;
+          }
+        }
+      : null,
+    onChunk: canStream ? (chunk) => process.stdout.write(chunk) : null
+  });
+
+  let renderedOutput;
+
+  if (canStream) {
+    process.stdout.write("\n");
+    if (runtimeOptions.verbose) {
+      process.stdout.write(formatFooter({ responseMeta, promptMeta, options: runtimeOptions }));
+    }
+
+    renderedOutput = renderFinalOutput({
+      runtimeOptions,
+      mode,
+      commitData,
+      explanation,
+      responseMeta,
+      promptMeta
+    });
+  } else {
+    renderedOutput = renderFinalOutput({
+      runtimeOptions,
+      mode,
+      commitData,
+      explanation,
+      responseMeta,
+      promptMeta
+    });
+    console.log(renderedOutput);
+  }
+
+  if (runtimeOptions.clipboard) {
+    copyToClipboard(renderedOutput);
+    if (!runtimeOptions.quiet) {
+      console.error("Copied output to clipboard.");
+    }
+  }
+
+  return 0;
+}
+
+const entryFile = fileURLToPath(import.meta.url);
+const executedFile = process.argv[1] ? realpathSync(path.resolve(process.argv[1])) : "";
+
+if (executedFile === entryFile) {
+  main().then(
+    (code) => process.exit(code),
+    (error) => {
+      console.error(error.message);
+      process.exit(1);
+    }
+  );
+}