@sirojar/tcgen 0.1.0

package/README.md

@@ -0,0 +1,166 @@
+# tcgen
+
+AI-powered test case generator from git commits. Reads your commit diffs, combines them with a customizable prompt template, and uses Claude or Gemini to generate structured test cases as JSON.
+
+## Install
+
+```bash
+npm install -g tcgen
+```
+
+## Quick Start
+
+```bash
+# In any git repository:
+tcgen init                        # Creates prompt-template.md
+# Edit prompt-template.md to describe your project
+
+# Generate test cases (Claude - default)
+ANTHROPIC_API_KEY=sk-... tcgen generate --all
+
+# Generate test cases (Gemini)
+GEMINI_API_KEY=... tcgen generate --all --provider gemini
+```
+
+## Commands
+
+### `tcgen init`
+
+Creates a `prompt-template.md` in the current directory with a starter template. Edit this file to describe your project — the more specific you are, the better the generated test cases.
+
+### `tcgen generate [options]`
+
+Generates test cases from git commits.
+
+| Option | Description | Default |
+|--------|-------------|---------|
+| `--from <commit>` | Start from this commit (exclusive) | Last processed commit |
+| `--to <commit>` | End at this commit (inclusive) | `HEAD` |
+| `--all` | Process all commits from the beginning | `false` |
+| `--output <dir>` | Output directory | `test-cases` |
+| `--prompt <file>` | Prompt template file | `prompt-template.md` |
+| `--provider <name>` | AI provider: `claude` or `gemini` | `claude` |
+| `--model <model>` | Model to use | Per provider default |
+| `--dry-run` | Preview prompt without calling AI | `false` |
+
+## Environment Variables
+
+| Variable | Required for | Description |
+|----------|-------------|-------------|
+| `ANTHROPIC_API_KEY` | `--provider claude` | Your Claude API key |
+| `GEMINI_API_KEY` | `--provider gemini` | Your Google Gemini API key |
+
+## AI Providers
+
+### Claude (default)
+
+```bash
+ANTHROPIC_API_KEY=sk-... tcgen generate --all
+ANTHROPIC_API_KEY=sk-... tcgen generate --all --model claude-sonnet-4-20250514
+```
+
+Default model: `claude-sonnet-4-20250514`
+
+### Gemini
+
+```bash
+GEMINI_API_KEY=... tcgen generate --all --provider gemini
+GEMINI_API_KEY=... tcgen generate --all --provider gemini --model gemini-2.0-flash
+```
+
+Default model: `gemini-2.0-flash`
+
+## Prompt Template
+
+The `prompt-template.md` file is fully editable. It uses two placeholders that get replaced at runtime:
+
+- `{{COMMIT_LOG}}` — list of commits being processed
+- `{{DIFF}}` — the git diff of those commits
+
+Everything else in the template is yours to customize: project description, instructions, emphasis on edge cases vs happy path, etc.
+
+### Example
+
+```markdown
+# Project Context
+
+This is a banking API with the following features:
+- User accounts and KYC verification
+- Fund transfers (domestic and international)
+- Transaction history and statements
+
+# Instructions
+
+You are a QA engineer. Analyze the git diff below and generate test cases...
+
+## Changed commits:
+{{COMMIT_LOG}}
+
+## Diff:
+{{DIFF}}
+```
+
+## Output Format
+
+Test cases are written as JSON files in the output directory (default: `test-cases/`):
+
+```json
+{
+  "metadata": {
+    "generatedAt": "2026-04-07T14:30:22.000Z",
+    "fromCommit": "a1b2c3d",
+    "toCommit": "e4f5g6h",
+    "commitCount": 3,
+    "model": "claude-sonnet-4-20250514"
+  },
+  "testCases": [
+    {
+      "id": "TC-20260407-001",
+      "title": "Verify cart total updates when item quantity changes",
+      "description": "The commit modified the cart subtotal calculation...",
+      "preconditions": ["User is logged in", "At least one item in cart"],
+      "steps": [
+        {
+          "stepNumber": 1,
+          "action": "Navigate to the shopping cart page",
+          "expectedOutcome": "Cart page loads with item list"
+        }
+      ],
+      "expectedResult": "Cart total correctly reflects the updated quantity",
+      "priority": "high",
+      "tags": ["cart", "calculation"],
+      "relatedCommit": "e4f5g6h",
+      "generatedAt": "2026-04-07T14:30:22.000Z"
+    }
+  ]
+}
+```
+
+## How It Works
+
+1. **Reads commits** — finds new commits since the last run (tracked in `.tcgen-state.json`)
+2. **Extracts diff** — gets the combined diff of those commits
+3. **Builds prompt** — loads your `prompt-template.md` and injects the diff + commit log
+4. **Calls AI** — sends the prompt to Claude or Gemini
+5. **Writes JSON** — saves structured test cases to the output directory
+6. **Updates state** — records the last processed commit for next run
+
+## Typical Workflow
+
+```bash
+# First run — process all existing commits
+tcgen generate --all
+
+# After new commits — only processes what's new
+tcgen generate
+
+# Preview what would be sent to AI
+tcgen generate --dry-run
+
+# Use a different provider
+tcgen generate --provider gemini
+```
+
+## License
+
+MIT

package/dist/ai.js

@@ -0,0 +1,107 @@
+import Anthropic from "@anthropic-ai/sdk";
+import { GoogleGenerativeAI } from "@google/generative-ai";
+const SYSTEM_PROMPT = "You are a QA test case generator. Respond only with valid JSON — a JSON array of test case objects. No markdown, no explanation, just the JSON array.";
+export async function generateTestCases(prompt, provider, model) {
+    let rawText;
+    if (provider === "gemini") {
+        rawText = await callGemini(prompt, model);
+    }
+    else {
+        rawText = await callClaude(prompt, model);
+    }
+    return parseTestCases(rawText);
+}
+async function callClaude(prompt, model) {
+    const apiKey = process.env.ANTHROPIC_API_KEY;
+    if (!apiKey) {
+        console.error("Error: ANTHROPIC_API_KEY environment variable is required.");
+        process.exit(1);
+    }
+    const client = new Anthropic({ apiKey });
+    let response;
+    try {
+        response = await client.messages.create({
+            model,
+            max_tokens: 4096,
+            system: SYSTEM_PROMPT,
+            messages: [{ role: "user", content: prompt }],
+        });
+    }
+    catch (error) {
+        if (error instanceof Anthropic.APIError) {
+            if (error.status === 401) {
+                console.error("Error: Claude API authentication failed. Check your ANTHROPIC_API_KEY.");
+                process.exit(1);
+            }
+            if (error.status === 429) {
+                console.error("Error: Rate limited by Claude API. Wait a moment and try again.");
+                process.exit(1);
+            }
+            console.error(`Error: Claude API returned status ${error.status}: ${error.message}`);
+            process.exit(1);
+        }
+        throw error;
+    }
+    const textBlock = response.content.find((block) => block.type === "text");
+    if (!textBlock || textBlock.type !== "text") {
+        console.error("Error: No text response from Claude API.");
+        process.exit(1);
+    }
+    return textBlock.text.trim();
+}
+async function callGemini(prompt, model) {
+    const apiKey = process.env.GEMINI_API_KEY;
+    if (!apiKey) {
+        console.error("Error: GEMINI_API_KEY environment variable is required.");
+        process.exit(1);
+    }
+    const genAI = new GoogleGenerativeAI(apiKey);
+    const genModel = genAI.getGenerativeModel({
+        model,
+        systemInstruction: SYSTEM_PROMPT,
+    });
+    let result;
+    try {
+        result = await genModel.generateContent(prompt);
+    }
+    catch (error) {
+        const err = error;
+        if (err.status === 401 || err.status === 403) {
+            console.error("Error: Gemini API authentication failed. Check your GEMINI_API_KEY.");
+            process.exit(1);
+        }
+        if (err.status === 429) {
+            console.error("Error: Rate limited by Gemini API. Wait a moment and try again.");
+            process.exit(1);
+        }
+        console.error(`Error: Gemini API error: ${err.message || error}`);
+        process.exit(1);
+    }
+    const text = result.response.text();
+    if (!text) {
+        console.error("Error: No text response from Gemini API.");
+        process.exit(1);
+    }
+    return text.trim();
+}
+function parseTestCases(raw) {
+    // Try direct JSON parse first
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        // Try extracting from markdown code fences
+        const fenceMatch = raw.match(/```(?:json)?\s*\n?([\s\S]*?)\n?```/);
+        if (fenceMatch) {
+            try {
+                return JSON.parse(fenceMatch[1]);
+            }
+            catch {
+                // fall through
+            }
+        }
+        console.error("Error: Failed to parse AI response as JSON.");
+        console.error("Raw response:", raw);
+        process.exit(1);
+    }
+}

package/dist/git.js

@@ -0,0 +1,75 @@
+import fs from "node:fs";
+import path from "node:path";
+import { simpleGit } from "simple-git";
+const STATE_FILE = ".tcgen-state.json";
+const MAX_DIFF_CHARS = 90_000;
+let git;
+function getGit(cwd) {
+    if (!git) {
+        git = simpleGit(cwd);
+    }
+    return git;
+}
+export async function ensureGitRepo(cwd) {
+    const isRepo = await getGit(cwd).checkIsRepo();
+    if (!isRepo) {
+        console.error("Error: Not a git repository. Run this from a project with git initialized.");
+        process.exit(1);
+    }
+}
+export function getLastProcessedCommit() {
+    const statePath = path.resolve(STATE_FILE);
+    if (!fs.existsSync(statePath)) {
+        return null;
+    }
+    const content = fs.readFileSync(statePath, "utf-8");
+    return JSON.parse(content);
+}
+export function saveLastProcessedCommit(sha) {
+    const state = {
+        lastProcessedCommit: sha,
+        lastRunAt: new Date().toISOString(),
+    };
+    fs.writeFileSync(path.resolve(STATE_FILE), JSON.stringify(state, null, 2), "utf-8");
+}
+export async function getCommitRange(from, to) {
+    const g = getGit();
+    if (from) {
+        const log = await g.log({ from, to });
+        return log.all.map((c) => ({
+            hash: c.hash,
+            message: c.message,
+            author: c.author_name,
+            date: c.date,
+        }));
+    }
+    // No "from" means get all commits up to "to"
+    const log = await g.log([to]);
+    return log.all.map((c) => ({
+        hash: c.hash,
+        message: c.message,
+        author: c.author_name,
+        date: c.date,
+    }));
+}
+export async function getDiff(from, to) {
+    const g = getGit();
+    let diff;
+    if (from) {
+        diff = await g.diff([from, to]);
+    }
+    else {
+        // No "from" — show full tree diff from root
+        diff = await g.raw(["diff-tree", "-p", "--root", to]);
+    }
+    if (diff.length > MAX_DIFF_CHARS) {
+        console.warn(`Warning: Diff is ${diff.length} characters, truncating to ${MAX_DIFF_CHARS}.`);
+        diff = diff.substring(0, MAX_DIFF_CHARS) + "\n\n[DIFF TRUNCATED]";
+    }
+    return diff;
+}
+export function formatCommitLog(commits) {
+    return commits
+        .map((c) => `- ${c.hash.substring(0, 7)} ${c.message} (${c.author}, ${c.date})`)
+        .join("\n");
+}

package/dist/index.js

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { ensureGitRepo, getLastProcessedCommit, saveLastProcessedCommit, getCommitRange, getDiff, formatCommitLog, } from "./git.js";
+import { loadTemplate, buildPrompt } from "./prompt.js";
+import { generateTestCases } from "./ai.js";
+import { writeTestCases } from "./output.js";
+const DEFAULT_MODELS = {
+    claude: "claude-sonnet-4-20250514",
+    gemini: "gemini-2.0-flash",
+};
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const program = new Command();
+program
+    .name("tcgen")
+    .description("AI-powered test case generator from git commits")
+    .version("0.1.0");
+// ---- init command ----
+program
+    .command("init")
+    .description("Initialize prompt-template.md in the current directory")
+    .action(() => {
+    const dest = path.resolve("prompt-template.md");
+    if (fs.existsSync(dest)) {
+        console.log("prompt-template.md already exists. Skipping.");
+        return;
+    }
+    // Copy bundled template
+    const templateSrc = path.resolve(__dirname, "..", "templates", "prompt-template.md");
+    if (!fs.existsSync(templateSrc)) {
+        console.error("Error: Bundled template not found. Reinstall tcgen.");
+        process.exit(1);
+    }
+    fs.copyFileSync(templateSrc, dest);
+    console.log("Created prompt-template.md — edit it to describe your project.");
+});
+// ---- generate command ----
+program
+    .command("generate")
+    .description("Generate test cases from git commits")
+    .option("--from <commit>", "Start from this commit (exclusive)")
+    .option("--to <commit>", "End at this commit (inclusive)", "HEAD")
+    .option("--all", "Process all commits from the beginning", false)
+    .option("--output <dir>", "Output directory", "test-cases")
+    .option("--prompt <file>", "Prompt template file", "prompt-template.md")
+    .option("--provider <provider>", "AI provider: claude or gemini", "claude")
+    .option("--model <model>", "Model to use (defaults per provider)")
+    .option("--dry-run", "Preview prompt without calling AI", false)
+    .action(async (opts) => {
+    await ensureGitRepo();
+    // Validate provider
+    const provider = opts.provider;
+    if (provider !== "claude" && provider !== "gemini") {
+        console.error(`Error: Unknown provider "${opts.provider}". Use "claude" or "gemini".`);
+        process.exit(1);
+    }
+    const model = opts.model || DEFAULT_MODELS[provider];
+    // Resolve from-commit
+    let fromCommit = opts.from || null;
+    if (!fromCommit && !opts.all) {
+        const state = getLastProcessedCommit();
+        if (state) {
+            fromCommit = state.lastProcessedCommit;
+        }
+        else {
+            console.error('Error: No previous run found. Use --all to process all commits or --from <commit> to specify a starting point.');
+            process.exit(1);
+        }
+    }
+    const config = {
+        fromCommit,
+        toCommit: opts.to,
+        outputDir: opts.output,
+        promptFile: opts.prompt,
+        provider,
+        model,
+        dryRun: opts.dryRun,
+        all: opts.all,
+    };
+    // Get commits
+    const commits = await getCommitRange(config.fromCommit, config.toCommit);
+    if (commits.length === 0) {
+        console.log(`No new commits${fromCommit ? ` since ${fromCommit.substring(0, 7)}` : ""}.`);
+        process.exit(0);
+    }
+    console.log(`Found ${commits.length} commit(s) to process.`);
+    // Get diff
+    const diff = await getDiff(config.fromCommit, config.toCommit);
+    if (!diff.trim()) {
+        console.log("No changes found in the diff. Nothing to generate.");
+        process.exit(0);
+    }
+    // Build prompt
+    const commitLog = formatCommitLog(commits);
+    const template = loadTemplate(path.resolve(config.promptFile));
+    const prompt = buildPrompt(template, diff, commitLog);
+    // Dry run — print and exit
+    if (config.dryRun) {
+        console.log("\n--- Constructed Prompt ---\n");
+        console.log(prompt);
+        console.log("\n--- End Prompt ---");
+        console.log(`\nCharacters: ${prompt.length}`);
+        return;
+    }
+    // Call AI
+    console.log(`Generating test cases with ${config.provider}/${config.model}...`);
+    const testCases = await generateTestCases(prompt, config.provider, config.model);
+    if (testCases.length === 0) {
+        console.log("AI returned no test cases (changes may be trivial).");
+        process.exit(0);
+    }
+    // Write output
+    const latestCommitHash = commits[0].hash;
+    const metadata = {
+        generatedAt: new Date().toISOString(),
+        fromCommit: config.fromCommit || "initial",
+        toCommit: latestCommitHash,
+        commitCount: commits.length,
+        model: config.model,
+    };
+    const filePath = writeTestCases(config, metadata, testCases);
+    console.log(`Generated ${testCases.length} test case(s) → ${filePath}`);
+    // Save state
+    saveLastProcessedCommit(latestCommitHash);
+});
+program.parse();

package/dist/output.js

@@ -0,0 +1,21 @@
+import fs from "node:fs";
+import path from "node:path";
+export function writeTestCases(config, metadata, testCases) {
+    const output = {
+        metadata,
+        testCases,
+    };
+    // Create output directory if it doesn't exist
+    const outputDir = path.resolve(config.outputDir);
+    fs.mkdirSync(outputDir, { recursive: true });
+    // Generate filename with timestamp
+    const timestamp = new Date()
+        .toISOString()
+        .replace(/[:.]/g, "-")
+        .replace("T", "-")
+        .substring(0, 19);
+    const fileName = `tc-${timestamp}.json`;
+    const filePath = path.join(outputDir, fileName);
+    fs.writeFileSync(filePath, JSON.stringify(output, null, 2), "utf-8");
+    return filePath;
+}

package/dist/prompt.js

@@ -0,0 +1,13 @@
+import fs from "node:fs";
+export function loadTemplate(filePath) {
+    if (!fs.existsSync(filePath)) {
+        console.error(`Error: Prompt template not found at "${filePath}". Run "tcgen init" to create one or use --prompt to specify a path.`);
+        process.exit(1);
+    }
+    return fs.readFileSync(filePath, "utf-8");
+}
+export function buildPrompt(template, diff, commitLog) {
+    return template
+        .replace("{{COMMIT_LOG}}", commitLog)
+        .replace("{{DIFF}}", diff);
+}

package/dist/types.js

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

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@sirojar/tcgen",
+  "version": "0.1.0",
+  "description": "AI-powered test case generator from git commits",
+  "type": "module",
+  "bin": {
+    "tcgen": "./dist/index.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js"
+  },
+  "keywords": [
+    "test",
+    "test-case",
+    "generator",
+    "qa",
+    "git",
+    "ai",
+    "claude"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "@anthropic-ai/sdk": "^0.39.0",
+    "@google/generative-ai": "^0.24.1",
+    "commander": "^12.1.0",
+    "simple-git": "^3.27.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}

package/templates/prompt-template.md

@@ -0,0 +1,53 @@
+# Project Context
+
+This is an e-commerce application with the following features:
+- User authentication (login, register, password reset)
+- Product catalog with search and filtering
+- Shopping cart and checkout flow
+- Order management and history
+- Payment processing
+
+Edit this section to describe YOUR project. The more specific you are, the better the generated test cases will be.
+
+---
+
+# Instructions
+
+You are a QA engineer. Analyze the git diff below and generate test cases.
+
+For each meaningful change, produce test cases that cover:
+- Happy path (normal usage)
+- Edge cases and boundary conditions
+- Error/failure scenarios where relevant
+
+Focus on **functional** test cases a manual QA tester could execute.
+Do NOT generate test cases for trivial changes (typo fixes, comment-only changes, formatting).
+
+If the diff contains no testable changes, return an empty JSON array `[]`.
+
+## Changed commits:
+{{COMMIT_LOG}}
+
+## Diff:
+{{DIFF}}
+
+Respond ONLY with a JSON array of test case objects matching this schema:
+[
+  {
+    "id": "TC-YYYYMMDD-NNN",
+    "title": "Short description of what is being tested",
+    "description": "Detailed explanation of what and why",
+    "preconditions": ["Setup needed before test"],
+    "steps": [
+      {
+        "stepNumber": 1,
+        "action": "What the tester does",
+        "expectedOutcome": "What should happen"
+      }
+    ],
+    "expectedResult": "Overall expected outcome",
+    "priority": "high | medium | low",
+    "tags": ["relevant", "tags"],
+    "relatedCommit": "short SHA"
+  }
+]