gitxplain 0.1.0

package/cli/services/outputFormatter.js

@@ -0,0 +1,197 @@
+import process from "node:process";
+
+const ANSI = {
+  reset: "\u001b[0m",
+  bold: "\u001b[1m",
+  cyan: "\u001b[36m",
+  yellow: "\u001b[33m",
+  green: "\u001b[32m",
+  red: "\u001b[31m",
+  gray: "\u001b[90m"
+};
+
+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 formatTargetLabel(commitData) {
+  return commitData.analysisType === "range" ? "Range" : "Commit";
+}
+
+function highlightLine(line) {
+  if (/^([0-9]+\.)?\s*(Summary|Issue|Root Cause|Fix|Impact|Risk Level|Technical Breakdown|Security Findings|Suggestions|Review Findings):/i.test(line)) {
+    return colorize(line, ANSI.bold + ANSI.cyan);
+  }
+
+  if (/risk/i.test(line) && /\blow\b/i.test(line)) {
+    return colorize(line, ANSI.green);
+  }
+
+  if (/risk/i.test(line) && /\bmedium\b/i.test(line)) {
+    return colorize(line, ANSI.yellow);
+  }
+
+  if (/risk/i.test(line) && /\bhigh\b/i.test(line)) {
+    return colorize(line, ANSI.red);
+  }
+
+  return line;
+}
+
+function formatExplanation(explanation) {
+  return explanation
+    .split("\n")
+    .map((line) => highlightLine(line))
+    .join("\n");
+}
+
+export function formatPreamble({ mode, commitData, options, promptMeta }) {
+  if (options.quiet) {
+    return "";
+  }
+
+  const header = [
+    `${colorize(formatTargetLabel(commitData), ANSI.bold + ANSI.cyan)}: ${commitData.displayRef}`,
+    `Files Changed: ${commitData.filesChanged.length}`,
+    `Stats: ${commitData.stats}`,
+    `Mode: ${mode}`
+  ];
+
+  if (commitData.analysisType === "range") {
+    header.splice(1, 0, `Commits: ${commitData.commitCount}`);
+  }
+
+  if (promptMeta?.warnings?.length) {
+    header.push(...promptMeta.warnings.map((warning) => colorize(`Warning: ${warning}`, ANSI.yellow)));
+  }
+
+  return `${header.join("\n")}\n\n`;
+}
+
+export function formatFooter({ responseMeta, promptMeta, options }) {
+  if (!options.verbose || !responseMeta) {
+    return "";
+  }
+
+  const lines = [
+    "",
+    colorize("Meta:", ANSI.bold + ANSI.gray),
+    `Provider: ${responseMeta.provider}`,
+    `Model: ${responseMeta.model}`,
+    `Cache: ${responseMeta.cacheHit ? "hit" : "miss"}`,
+    `Latency: ${responseMeta.latencyMs}ms`
+  ];
+
+  if (responseMeta.usage) {
+    lines.push(`Usage: ${JSON.stringify(responseMeta.usage)}`);
+  }
+
+  if (promptMeta?.warnings?.length) {
+    lines.push(...promptMeta.warnings);
+  }
+
+  return `${lines.join("\n")}\n`;
+}
+
+export function formatOutput({ mode, commitData, explanation, responseMeta, promptMeta, options }) {
+  return `${formatPreamble({ mode, commitData, options, promptMeta })}${formatExplanation(explanation)}${formatFooter({ responseMeta, promptMeta, options })}`;
+}
+
+export function formatMarkdownOutput({ mode, commitData, explanation, responseMeta, promptMeta }) {
+  const lines = [
+    `# gitxplain`,
+    ``,
+    `- Target: ${commitData.displayRef}`,
+    `- Type: ${commitData.analysisType}`,
+    `- Files Changed: ${commitData.filesChanged.length}`,
+    `- Stats: ${commitData.stats}`,
+    `- Mode: ${mode}`
+  ];
+
+  if (commitData.analysisType === "range") {
+    lines.push(`- Commits: ${commitData.commitCount}`);
+  }
+
+  if (responseMeta) {
+    lines.push(`- Provider: ${responseMeta.provider}`);
+    lines.push(`- Model: ${responseMeta.model}`);
+  }
+
+  if (promptMeta?.warnings?.length) {
+    lines.push(...promptMeta.warnings.map((warning) => `- Warning: ${warning}`));
+  }
+
+  lines.push("", explanation);
+  return lines.join("\n");
+}
+
+function escapeHtml(text) {
+  return text
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}
+
+export function formatHtmlOutput({ mode, commitData, explanation, responseMeta, promptMeta }) {
+  const metaItems = [
+    `<li><strong>Target:</strong> ${escapeHtml(commitData.displayRef)}</li>`,
+    `<li><strong>Type:</strong> ${escapeHtml(commitData.analysisType)}</li>`,
+    `<li><strong>Files Changed:</strong> ${commitData.filesChanged.length}</li>`,
+    `<li><strong>Stats:</strong> ${escapeHtml(commitData.stats)}</li>`,
+    `<li><strong>Mode:</strong> ${escapeHtml(mode)}</li>`
+  ];
+
+  if (commitData.analysisType === "range") {
+    metaItems.push(`<li><strong>Commits:</strong> ${commitData.commitCount}</li>`);
+  }
+
+  if (responseMeta) {
+    metaItems.push(`<li><strong>Provider:</strong> ${escapeHtml(responseMeta.provider)}</li>`);
+    metaItems.push(`<li><strong>Model:</strong> ${escapeHtml(responseMeta.model)}</li>`);
+  }
+
+  if (promptMeta?.warnings?.length) {
+    metaItems.push(
+      ...promptMeta.warnings.map((warning) => `<li><strong>Warning:</strong> ${escapeHtml(warning)}</li>`)
+    );
+  }
+
+  return [
+    "<!doctype html>",
+    "<html><head><meta charset=\"utf-8\"><title>gitxplain</title></head><body>",
+    "<h1>gitxplain</h1>",
+    `<ul>${metaItems.join("")}</ul>`,
+    `<pre>${escapeHtml(explanation)}</pre>`,
+    "</body></html>"
+  ].join("");
+}
+
+export function formatJsonOutput({ mode, commitData, explanation, responseMeta, promptMeta }) {
+  return JSON.stringify(
+    {
+      mode,
+      commit: {
+        id: commitData.commitId,
+        ref: commitData.displayRef,
+        type: commitData.analysisType,
+        count: commitData.commitCount,
+        message: commitData.commitMessage,
+        filesChanged: commitData.filesChanged,
+        stats: commitData.stats
+      },
+      prompt: promptMeta,
+      response: responseMeta,
+      explanation
+    },
+    null,
+    2
+  );
+}

package/cli/services/promptService.js

@@ -0,0 +1,83 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const PROMPT_DIR = path.resolve(__dirname, "../../prompts");
+
+const PROMPT_FILES = {
+  full: "master.txt",
+  summary: "summary.txt",
+  issues: "issue.txt",
+  fix: "junior.txt",
+  impact: "impact.txt",
+  lines: "lines.txt",
+  review: "review.txt",
+  security: "security.txt"
+};
+
+function fillTemplate(template, values) {
+  return Object.entries(values).reduce((result, [key, value]) => {
+    return result.replaceAll(`{{${key}}}`, value);
+  }, template);
+}
+
+function truncateDiff(diff, maxDiffLines) {
+  const diffLines = diff.split("\n");
+
+  if (diffLines.length <= maxDiffLines) {
+    return {
+      diff,
+      truncated: false,
+      diffLineCount: diffLines.length,
+      keptDiffLines: diffLines.length,
+      warning: null
+    };
+  }
+
+  const keptLines = diffLines.slice(0, maxDiffLines);
+  return {
+    diff: `${keptLines.join("\n")}\n\n[Diff truncated: kept ${maxDiffLines} of ${diffLines.length} lines.]`,
+    truncated: true,
+    diffLineCount: diffLines.length,
+    keptDiffLines: maxDiffLines,
+    warning: `Diff truncated to ${maxDiffLines} of ${diffLines.length} lines before sending to the model.`
+  };
+}
+
+function buildRangePrelude(commitData) {
+  if (commitData.analysisType !== "range") {
+    return "";
+  }
+
+  return [
+    "This analysis covers a range of commits rather than a single commit.",
+    "Treat the output like a changelog or release summary when appropriate.",
+    `Commit Count: ${commitData.commitCount}`,
+    `Commit List:\n${commitData.commits.map((commit) => `- ${commit.hash.slice(0, 7)} ${commit.subject}`).join("\n")}`,
+    ""
+  ].join("\n");
+}
+
+export function buildPrompt(mode, commitData, options = {}) {
+  const filename = PROMPT_FILES[mode] ?? PROMPT_FILES.full;
+  const template = readFileSync(path.join(PROMPT_DIR, filename), "utf8");
+  const truncation = truncateDiff(commitData.diff, options.maxDiffLines ?? 800);
+  const prompt = fillTemplate(`${buildRangePrelude(commitData)}${template}`, {
+    commit_message: commitData.commitMessage,
+    files_changed: commitData.filesChanged.join("\n"),
+    stats: commitData.stats,
+    diff: truncation.diff
+  });
+
+  return {
+    prompt,
+    promptMeta: {
+      truncated: truncation.truncated,
+      diffLineCount: truncation.diffLineCount,
+      keptDiffLines: truncation.keptDiffLines,
+      warnings: truncation.warning ? [truncation.warning] : []
+    }
+  };
+}

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "gitxplain",
+  "version": "0.1.0",
+  "description": "AI-powered Git commit explainer CLI",
+  "type": "module",
+  "bin": {
+    "gitxplain": "./cli/index.js"
+  },
+  "scripts": {
+    "start": "node ./cli/index.js",
+    "lint": "node --check ./cli/index.js && node --check ./cli/services/aiService.js && node --check ./cli/services/cacheService.js && node --check ./cli/services/clipboardService.js && node --check ./cli/services/configService.js && node --check ./cli/services/gitService.js && node --check ./cli/services/hookService.js && node --check ./cli/services/promptService.js && node --check ./cli/services/outputFormatter.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "git",
+    "cli",
+    "ai",
+    "developer-tools"
+  ],
+  "license": "MIT"
+}

package/prompts/impact.txt

@@ -0,0 +1,15 @@
+Compare the code before and after this commit.
+
+Explain:
+- Key differences
+- Improvements made
+- Behavioral changes
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Diff:
+{{diff}}

package/prompts/issue.txt

@@ -0,0 +1,18 @@
+Determine if this commit fixes a bug.
+
+If yes:
+- Describe the issue
+- Explain how it was fixed
+- Mention affected components
+
+If no:
+- Explain the main purpose of the commit instead
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Diff:
+{{diff}}

package/prompts/junior.txt

@@ -0,0 +1,15 @@
+Explain this commit in simple terms for a junior developer.
+
+Focus on:
+- What changed
+- Why it changed
+- Simple explanation of logic
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Diff:
+{{diff}}

package/prompts/lines.txt

@@ -0,0 +1,22 @@
+Explain every changed line in this commit in a developer-friendly way.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Diff:
+{{diff}}
+
+Instructions:
+- Go file by file
+- For each diff hunk, explain what the removed lines did before
+- Explain what each added line does now
+- Call out important renamed variables, condition changes, function call changes, and control-flow changes
+- Keep the order aligned with the diff so a developer can read the explanation side by side with the patch
+- If a line is context-only and unchanged, mention it only when it helps explain surrounding modifications
+- End each file section with a short summary of the behavior change in that file

package/prompts/master.txt

@@ -0,0 +1,38 @@
+You are a senior software engineer and code reviewer.
+
+Analyze the following Git commit and generate a structured explanation.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Code Diff:
+{{diff}}
+
+Return the output in the following structured format:
+
+1. Summary:
+- One clear sentence explaining the purpose of the commit
+
+2. Issue:
+- What problem or bug was being addressed?
+
+3. Root Cause:
+- Why did the issue occur?
+
+4. Fix:
+- How was the issue resolved?
+
+5. Impact:
+- What effect does this change have on the system?
+
+6. Risk Level:
+- Low / Medium / High with reasoning
+
+7. Technical Breakdown:
+- Explain code changes in a clear, developer-friendly way

package/prompts/review.txt

@@ -0,0 +1,26 @@
+Review this commit like a senior engineer performing code review.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Diff:
+{{diff}}
+
+Return:
+
+1. Review Findings:
+- List actionable findings ordered by severity
+- Include likely bugs, regressions, correctness risks, performance concerns, and maintainability issues
+- If there are no significant findings, say so explicitly
+
+2. Suggestions:
+- Give concrete follow-up improvements or tests to add
+
+3. Risk Level:
+- Low / Medium / High with reasoning

package/prompts/security.txt

@@ -0,0 +1,33 @@
+Analyze this commit from a security perspective.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Stats:
+{{stats}}
+
+Diff:
+{{diff}}
+
+Focus on:
+- Input validation issues
+- Injection risks
+- Authentication or authorization regressions
+- Sensitive data exposure
+- Insecure defaults
+- Dependency or configuration risks
+
+Return:
+
+1. Security Findings:
+- List any vulnerabilities or suspicious changes
+- If none are apparent, say so clearly
+
+2. Severity:
+- Low / Medium / High with reasoning
+
+3. Recommended Mitigations:
+- Suggest concrete hardening steps or tests

package/prompts/summary.txt

@@ -0,0 +1,10 @@
+Summarize this commit in one sentence.
+
+Commit Message:
+{{commit_message}}
+
+Files Changed:
+{{files_changed}}
+
+Diff:
+{{diff}}