jstar-reviewer 2.1.3 → 2.2.0

package/dist/scripts/utils/logger.js

@@ -0,0 +1,110 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const chalk_1 = __importDefault(require("chalk"));
+/**
+ * Logger Utility
+ * Centralizes all CLI output to support both human-readable (TTY) and machine-readable (JSON) modes.
+ *
+ * Usage:
+ *   Logger.init(); // Auto-detects --json flag
+ *   Logger.info("Starting..."); // Suppressed in JSON mode
+ *   Logger.json({ status: "ok" }); // Only outputs in JSON mode
+ */
+let jsonMode = false;
+exports.Logger = {
+    /**
+     * Initialize the logger.
+     * Auto-detects --json or --headless flags from process.argv.
+     */
+    init() {
+        jsonMode = process.argv.includes('--json') || process.argv.includes('--headless');
+    },
+    /**
+     * Check if we are in headless/JSON mode.
+     */
+    isHeadless() {
+        return jsonMode;
+    },
+    /**
+     * Alias for isHeadless for backwards compatibility.
+     */
+    isJsonMode() {
+        return jsonMode;
+    },
+    /**
+     * Standard informational message (suppressed in JSON mode).
+     */
+    info(message) {
+        if (!jsonMode) {
+            console.log(message);
+        }
+    },
+    /**
+     * Success message with green styling (suppressed in JSON mode).
+     */
+    success(message) {
+        if (!jsonMode) {
+            console.log(chalk_1.default.green(message));
+        }
+    },
+    /**
+     * Warning message with yellow styling (suppressed in JSON mode).
+     */
+    warn(message) {
+        if (!jsonMode) {
+            console.log(chalk_1.default.yellow(message));
+        }
+    },
+    /**
+     * Error message - always outputs to stderr.
+     */
+    error(message) {
+        console.error(chalk_1.default.red(message));
+    },
+    /**
+     * Dim/faded message for secondary info (suppressed in JSON mode).
+     */
+    dim(message) {
+        if (!jsonMode) {
+            console.log(chalk_1.default.dim(message));
+        }
+    },
+    /**
+     * Write inline (no newline) for progress indicators (suppressed in JSON mode).
+     * Alias: progress()
+     */
+    inline(message) {
+        if (!jsonMode) {
+            process.stdout.write(message);
+        }
+    },
+    /**
+     * Progress indicator - writes inline without newline.
+     */
+    progress(message) {
+        if (!jsonMode) {
+            process.stdout.write(message);
+        }
+    },
+    /**
+     * Output structured JSON to stdout.
+     * Only outputs in JSON mode. For API/AI consumption.
+     */
+    json(data) {
+        if (jsonMode) {
+            console.log(JSON.stringify(data, null, 2));
+        }
+    },
+    /**
+     * Output a single-line JSON object (for streaming events).
+     */
+    jsonLine(data) {
+        if (jsonMode) {
+            console.log(JSON.stringify(data));
+        }
+    }
+};

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "jstar-reviewer",
-  "version": "2.1.3",
+  "version": "2.2.0",
   "description": "Local-First, Context-Aware AI Code Reviewer - Works with any language",
   "bin": {
     "jstar": "bin/jstar.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "index:init": "ts-node scripts/indexer.ts --init",
+    "index:watch": "ts-node scripts/indexer.ts --watch",
+    "review": "ts-node scripts/reviewer.ts",
+    "chat": "ts-node scripts/chat.ts",
+    "detect": "ts-node scripts/detective.ts",
+    "prepare": "husky install"
+  },
   "keywords": [
     "code-review",
     "ai",
@@ -29,13 +38,15 @@
     "chalk": "^4.1.2",
     "dotenv": "^16.3.1",
     "llamaindex": "^0.1.0",
+    "prompts": "^2.4.2",
     "simple-git": "^3.20.0"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",
+    "@types/prompts": "^2.4.9",
+    "husky": "^8.0.3",
     "ts-node": "^10.9.1",
-    "typescript": "^5.2.2",
-    "husky": "^8.0.3"
+    "typescript": "^5.2.2"
   },
   "engines": {
     "node": ">=18"
@@ -54,12 +65,5 @@
   "type": "commonjs",
   "bugs": {
     "url": "https://github.com/JStaRFilms/jstar-code-review/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "index:init": "ts-node scripts/indexer.ts --init",
-    "index:watch": "ts-node scripts/indexer.ts --watch",
-    "review": "ts-node scripts/reviewer.ts",
-    "detect": "ts-node scripts/detective.ts"
   }
 }

package/scripts/chat.ts

@@ -0,0 +1,130 @@
+import { startInteractiveSession, startHeadlessSession } from "./session";
+import {
+    VectorStoreIndex,
+    storageContextFromDefaults,
+    serviceContextFromDefaults
+} from "llamaindex";
+import { GeminiEmbedding } from "./gemini-embedding";
+import { MockLLM } from "./mock-llm";
+import { Logger } from "./utils/logger";
+import * as path from "path";
+import * as fs from "fs";
+import chalk from "chalk";
+import { SessionState, DashboardReport } from "./types";
+import { renderDashboard, determineStatus, generateRecommendation } from "./dashboard";
+
+const STORAGE_DIR = path.join(process.cwd(), ".jstar", "storage");
+const SESSION_FILE = path.join(process.cwd(), ".jstar", "session.json");
+const OUTPUT_FILE = path.join(process.cwd(), ".jstar", "last-review.md");
+
+const embedModel = new GeminiEmbedding();
+const llm = new MockLLM();
+const serviceContext = serviceContextFromDefaults({ embedModel, llm: llm as any });
+
+async function loadSession(): Promise<SessionState | null> {
+    try {
+        const content = fs.readFileSync(SESSION_FILE, 'utf-8');
+        return JSON.parse(content);
+    } catch (e: any) {
+        if (e.code === 'ENOENT') {
+            return null; // File doesn't exist
+        }
+        Logger.error(`Failed to load session: ${e.message}`);
+        return null;
+    }
+}
+
+async function main() {
+    // Initialize logger mode
+    Logger.init();
+
+    Logger.info(chalk.bold.magenta("\n💬 J-Star Chat: Resuming Session...\n"));
+
+    // 1. Load Session
+    const session = await loadSession();
+    if (!session) {
+        Logger.error(chalk.red("❌ No active session found."));
+        Logger.info(chalk.yellow("Run 'jstar review' first to analyze the codebase."));
+        return;
+    }
+
+    Logger.info(chalk.dim(`   📅 Loaded session from: ${session.date}`));
+    Logger.info(chalk.dim(`   🔍 Loaded ${session.findings.reduce((acc, f) => acc + f.issues.length, 0)} issues.`));
+
+    // 2. Load Brain (Fast)
+    if (!fs.existsSync(STORAGE_DIR)) {
+        Logger.error(chalk.red("❌ Local Brain not found. Run 'pnpm index:init' first."));
+        return;
+    }
+    const storageContext = await storageContextFromDefaults({ persistDir: STORAGE_DIR });
+    const index = await VectorStoreIndex.init({ storageContext, serviceContext });
+
+    // 3. Start Chat (Headless or Interactive)
+    let updatedFindings;
+    let hasUpdates;
+
+    if (Logger.isHeadless()) {
+        // Headless mode: stdin/stdout JSON protocol
+        const result = await startHeadlessSession(session.findings, index);
+        updatedFindings = result.updatedFindings;
+        hasUpdates = result.hasUpdates;
+    } else {
+        // Normal TUI mode
+        const result = await startInteractiveSession(session.findings, index);
+        updatedFindings = result.updatedFindings;
+        hasUpdates = result.hasUpdates;
+    }
+
+    // 4. Update Session & Report if changed
+    if (hasUpdates) {
+        Logger.info(chalk.blue("\n🔄 Updating Session & Dashboard..."));
+
+        // Recalculate metrics based on new findings
+        const newMetrics = {
+            ...session.metrics, // keep files/tokens same
+            violations: updatedFindings.reduce((sum, f) => sum + f.issues.length, 0),
+            critical: updatedFindings.filter(f => f.severity === 'P0_CRITICAL').length,
+            high: updatedFindings.filter(f => f.severity === 'P1_HIGH').length,
+            medium: updatedFindings.filter(f => f.severity === 'P2_MEDIUM').length,
+            lgtm: updatedFindings.filter(f => f.severity === 'LGTM').length,
+        };
+
+        // Save Session
+        const newSession: SessionState = {
+            date: new Date().toISOString().split('T')[0],
+            findings: updatedFindings,
+            metrics: newMetrics
+        };
+
+        try {
+            fs.writeFileSync(SESSION_FILE, JSON.stringify(newSession, null, 2));
+        } catch (err: any) {
+            Logger.error(`Failed to save session: ${err.message}`);
+            return;
+        }
+
+        // Save Dashboard
+        const report: DashboardReport = {
+            date: newSession.date,
+            reviewer: 'J-Star Chat',
+            status: determineStatus(newMetrics),
+            metrics: newMetrics,
+            findings: updatedFindings,
+            recommendedAction: generateRecommendation(newMetrics)
+        };
+        const dashboard = renderDashboard(report);
+
+        try {
+            fs.writeFileSync(OUTPUT_FILE, dashboard);
+        } catch (err: any) {
+            Logger.error(`Failed to save dashboard: ${err.message}`);
+            return;
+        }
+
+        Logger.info(chalk.bold.green("✅ Saved."));
+    } else {
+        Logger.info(chalk.dim("   No changes made."));
+    }
+}
+
+main().catch(console.error);

package/scripts/config.ts

@@ -5,7 +5,7 @@ import { Severity } from "./types";
 
 // --- Auto-Setup Logic ---
 const REQUIRED_ENV_VARS = {
-    'GOOGLE_API_KEY': '# Required: Google API key for Gemini embeddings\nGOOGLE_API_KEY=your_google_api_key_here',
+    'GEMINI_API_KEY': '# Required: Gemini API key (or GOOGLE_API_KEY)\nGEMINI_API_KEY=your_gemini_api_key_here',
     'GROQ_API_KEY': '# Required: Groq API key for LLM reviews\nGROQ_API_KEY=your_groq_api_key_here',
     'REVIEW_MODEL_NAME': '# Optional: Override the default model\n# REVIEW_MODEL_NAME=moonshotai/kimi-k2-instruct-0905'
 };
@@ -55,9 +55,13 @@ const DEFAULT_MODEL = "moonshotai/kimi-k2-instruct-0905";
 
 export const Config = {
     MODEL_NAME: process.env.REVIEW_MODEL_NAME || DEFAULT_MODEL,
+    CRITIQUE_MODEL_NAME: process.env.CRITIQUE_MODEL_NAME || process.env.REVIEW_MODEL_NAME || DEFAULT_MODEL,
     DEFAULT_SEVERITY: 'P2_MEDIUM' as Severity,
     THRESHOLDS: {
         MEDIUM: 5
-    }
+    },
+    // Smart Review Settings
+    CONFIDENCE_THRESHOLD: 3,      // Minimum confidence (1-5) to include an issue
+    ENABLE_SELF_CRITIQUE: true,   // Enable second-pass validation
 };
 

package/scripts/core/critique.ts

@@ -0,0 +1,162 @@
+/**
+ * Self-Critique Module
+ * Second-pass validation to filter out false positives
+ */
+
+import { generateText } from "ai";
+import { createGroq } from "@ai-sdk/groq";
+import chalk from "chalk";
+import { Logger } from "../utils/logger";
+import { Config } from "../config";
+import { FileFinding, ReviewIssue } from "../types";
+
+const groq = createGroq({ apiKey: process.env.GROQ_API_KEY });
+
+interface CritiqueResult {
+    issueTitle: string;
+    verdict: 'VALID' | 'FALSE_POSITIVE' | 'NEEDS_CONTEXT';
+    reason: string;
+}
+
+interface CritiqueResponse {
+    results: CritiqueResult[];
+}
+
+/**
+ * Runs a self-critique pass on the initial findings.
+ * Returns filtered findings with only validated issues.
+ */
+export async function critiqueFindings(
+    findings: FileFinding[],
+    diff: string
+): Promise<FileFinding[]> {
+    // Collect all issues across all files for batch critique
+    const allIssues: { file: string; issue: ReviewIssue; index: number }[] = [];
+    findings.forEach((f, fIdx) => {
+        f.issues.forEach((issue, iIdx) => {
+            allIssues.push({ file: f.file, issue, index: fIdx * 1000 + iIdx });
+        });
+    });
+
+    if (allIssues.length === 0) {
+        return findings;
+    }
+
+    Logger.info(chalk.blue("\n🔍 Self-Critique Pass: Validating findings...\n"));
+
+    // Build the critique prompt
+    const issueList = allIssues.map((item, idx) =>
+        `[${idx}] File: ${item.file}\n    Title: ${item.issue.title}\n    Description: ${item.issue.description}`
+    ).join("\n\n");
+
+    const systemPrompt = `You are a code review validator. Your job is to filter out FALSE POSITIVES.
+
+For each issue below, decide:
+- VALID: This is a real problem that should be reported
+- FALSE_POSITIVE: This is NOT a real issue (test mock, intentional pattern, already handled, etc.)
+- NEEDS_CONTEXT: Can't determine without more code context (treat as valid)
+
+Return JSON with this structure:
+{
+  "results": [
+    { "issueTitle": "...", "verdict": "VALID" | "FALSE_POSITIVE" | "NEEDS_CONTEXT", "reason": "..." }
+  ]
+}
+
+IMPORTANT:
+- Be SKEPTICAL. If the code looks intentional, it's probably not a bug.
+- Test files, mocks, and stubs are NOT bugs.
+- "Missing error handling" in utility modules may be intentional.
+- Return ONLY valid JSON.`;
+
+    const userPrompt = `ORIGINAL DIFF:
+\`\`\`
+${diff.slice(0, 4000)}
+\`\`\`
+
+ISSUES TO VALIDATE:
+${issueList}`;
+
+    try {
+        const { text } = await generateText({
+            model: groq(Config.CRITIQUE_MODEL_NAME),
+            system: systemPrompt,
+            prompt: userPrompt,
+            temperature: 0.1,
+        });
+
+        // Parse critique response
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (!jsonMatch) {
+            Logger.warn(chalk.yellow("   ⚠️ Could not parse critique response, keeping all issues"));
+            return findings;
+        }
+
+        let response: CritiqueResponse;
+        try {
+            const parsed = JSON.parse(jsonMatch[0]);
+            // Validate structure
+            if (!parsed || !Array.isArray(parsed.results)) {
+                throw new Error("Invalid response structure");
+            }
+            response = parsed;
+        } catch (parseError) {
+            Logger.warn(chalk.yellow("   ⚠️ Invalid JSON from critique, keeping all issues"));
+            return findings;
+        }
+
+        // Build a map of verdicts by title
+        const verdictMap = new Map<string, CritiqueResult>();
+        for (const result of response.results) {
+            verdictMap.set(result.issueTitle.toLowerCase(), result);
+        }
+
+        // Filter findings
+        const filteredFindings: FileFinding[] = [];
+        let removedCount = 0;
+
+        for (const finding of findings) {
+            const validIssues: ReviewIssue[] = [];
+
+            for (const issue of finding.issues) {
+                const verdict = verdictMap.get(issue.title.toLowerCase());
+
+                if (verdict?.verdict === 'FALSE_POSITIVE') {
+                    removedCount++;
+                    Logger.info(chalk.dim(`   ❌ Removed: "${issue.title}" (${verdict.reason})`));
+                } else {
+                    validIssues.push(issue);
+                    if (verdict?.verdict === 'VALID') {
+                        Logger.info(chalk.green(`   ✓ Kept: "${issue.title}"`));
+                    }
+                }
+            }
+
+            if (validIssues.length > 0) {
+                filteredFindings.push({
+                    ...finding,
+                    issues: validIssues,
+                    // Upgrade to LGTM if no issues remain? No, keep severity for record
+                });
+            } else if (finding.issues.length > 0) {
+                // All issues were false positives - mark as LGTM
+                filteredFindings.push({
+                    ...finding,
+                    severity: 'LGTM',
+                    issues: []
+                });
+            } else {
+                filteredFindings.push(finding);
+            }
+        }
+
+        Logger.info(chalk.blue(`\n   📊 Self-Critique: ${removedCount} false positive(s) removed\n`));
+
+        return filteredFindings;
+
+    } catch (error: any) {
+        Logger.warn(chalk.yellow(`   ⚠️ Self-critique failed: ${error.message.slice(0, 100)}`));
+        Logger.warn(chalk.yellow("   Keeping all issues as fallback."));
+        return findings;
+    }
+}

package/scripts/core/debate.ts

@@ -0,0 +1,111 @@
+import { VectorStoreIndex, MetadataMode } from "llamaindex";
+import { generateText } from "ai";
+import { createGroq } from "@ai-sdk/groq";
+import { Config } from "../config";
+import chalk from "chalk";
+
+const groq = createGroq({ apiKey: process.env.GROQ_API_KEY });
+
+export interface DebateResult {
+    text: string;
+    severity: 'P0_CRITICAL' | 'P1_HIGH' | 'P2_MEDIUM' | 'LGTM' | 'UNCHANGED';
+}
+
+export async function debateIssue(
+    issueTitle: string,
+    issueDescription: string,
+    fileName: string,
+    userArgument: string,
+    index: VectorStoreIndex
+): Promise<DebateResult> {
+
+    // Validate API key before making any calls
+    if (!process.env.GROQ_API_KEY) {
+        throw new Error("GROQ_API_KEY is required for debate mode. Please set it in your .env.local file.");
+    }
+
+    console.log(chalk.dim("   🧠  Thinking... (Consulting the Brain)"));
+
+    // 1. Extract keywords/context
+    const query = `${userArgument} ${issueTitle}`;
+
+    // 2. Retrieve new context
+    const retriever = index.asRetriever({ similarityTopK: 2 });
+    const contextNodes = await retriever.retrieve(query);
+    const newContext = contextNodes.map(n => n.node.getContent(MetadataMode.NONE)).join("\n\n").slice(0, 2000);
+
+    if (newContext.length >= 2000) {
+        console.log(chalk.yellow("   ⚠️  Context truncated to 2000 chars"));
+    }
+
+    const sources = contextNodes.map(n => n.node.metadata?.['file_name']).filter(Boolean).join(', ');
+    if (sources) {
+        console.log(chalk.dim(`   🔍  Found relevant context from: ${sources}`));
+    }
+
+    // 3. Ask the Judge
+    const systemPrompt = `You are a Senior Code Reviewer in a debate with a developer.
+    
+    ORIGINAL FINDING: "${issueTitle} - ${issueDescription}" in file ${fileName}.
+    USER DEFENSE: "${userArgument}"
+    
+    NEW CONTEXT FOUND IN REPO:
+    ${newContext}
+    
+    TASK:
+    Analyze the USER INPUT.
+    
+    1. **IS IT A QUESTION?** (e.g., "What does this mean?", "Why is this wrong?")
+       - If yes, **EXPLAIN** the technical reasoning behind the finding. 
+       - Reference the specific code/context.
+       - Do NOT withdraw the issue (Severity: UNCHANGED).
+       - Tone: Educational and helpful.
+
+    2. **IS IT A DEFENSE/ARGUMENT?** (e.g., "This is handled in utils.ts", "It's a false positive because...")
+       - Evaluate if the user is correct based on the NEW CONTEXT.
+       - If user is RIGHT: Apologize and withdraw (Severity: LGTM).
+       - If user is WRONG: Explain why, citing the context. (Severity: UNCHANGED).
+    
+    RETURN JSON:
+    {
+      "response": "Conversational response (explanation or verdict).",
+      "severity": "P0_CRITICAL" | "P1_HIGH" | "P2_MEDIUM" | "LGTM" | "UNCHANGED"
+    }
+    `;
+
+    try {
+        const { text } = await generateText({
+            model: groq(Config.MODEL_NAME),
+            system: systemPrompt,
+            prompt: "What is your verdict?",
+            temperature: 0.2,
+        });
+
+        const jsonMatch = text.match(/\{[\s\S]*\}/);
+        if (jsonMatch) {
+            try {
+                const parsed = JSON.parse(jsonMatch[0]);
+                // Validate expected structure
+                if (parsed && typeof parsed.response === 'string' && parsed.severity) {
+                    return {
+                        text: parsed.response,
+                        severity: parsed.severity
+                    };
+                }
+            } catch (parseError) {
+                // JSON parse failed, fall through to default response
+            }
+        }
+
+        return {
+            text: text,
+            severity: 'UNCHANGED'
+        };
+
+    } catch (error: any) {
+        return {
+            text: `Failed to debate: ${error.message}`,
+            severity: 'UNCHANGED'
+        };
+    }
+}

package/scripts/detective.ts

@@ -1,6 +1,7 @@
 import * as fs from 'fs';
 import * as path from 'path';
 import chalk from 'chalk';
+import { Logger } from './utils/logger';
 
 interface Violation {
     file: string;
@@ -109,22 +110,22 @@ export class Detective {
 
     report() {
         if (this.violations.length === 0) {
-            console.log(chalk.green("✅ Detective Engine: No violations found."));
+            Logger.info(chalk.green("✅ Detective Engine: No violations found."));
             return;
         }
 
-        console.log(chalk.red(`🚨 Detective Engine found ${this.violations.length} violations:`));
+        Logger.info(chalk.red(`🚨 Detective Engine found ${this.violations.length} violations:`));
         // Only show first 10 to avoid wall of text
         const total = this.violations.length;
         const toShow = this.violations.slice(0, 10);
 
         toShow.forEach(v => {
             const color = v.severity === 'high' ? chalk.red : chalk.yellow;
-            console.log(color(`[${v.code}] ${v.file}:${v.line} - ${v.message}`));
+            Logger.info(color(`[${v.code}] ${v.file}:${v.line} - ${v.message}`));
         });
 
         if (total > 10) {
-            console.log(chalk.dim(`... and ${total - 10} more.`));
+            Logger.dim(`... and ${total - 10} more.`);
         }
     }
 }

package/scripts/gemini-embedding.ts

@@ -5,9 +5,9 @@ export class GeminiEmbedding {
     private model: any;
 
     constructor() {
-        const apiKey = process.env.GOOGLE_API_KEY;
+        const apiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
         if (!apiKey) {
-            throw new Error("GOOGLE_API_KEY is missing from environment variables.");
+            throw new Error("GEMINI_API_KEY is missing from environment variables.");
         }
         this.genAI = new GoogleGenerativeAI(apiKey);
         // User requested 'text-embedding-004', which has better rate limits

package/scripts/indexer.ts

@@ -50,8 +50,9 @@ function getSourceDir(): string {
 
 async function main() {
     // 0. Environment Validation
-    if (!process.env.GOOGLE_API_KEY) {
-        console.error(chalk.red("❌ Missing GOOGLE_API_KEY!"));
+    const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
+    if (!geminiKey) {
+        console.error(chalk.red("❌ Missing GEMINI_API_KEY (or GOOGLE_API_KEY)!"));
         console.log(chalk.yellow("\nPlease ensure you have a .env.local file. Check .env.example for a template.\n"));
         process.exit(1);
     }
@@ -126,7 +127,7 @@ async function main() {
     } catch (e: any) {
         console.error(chalk.red("❌ Indexing Failed:"), e.message);
         if (e.message.includes("API") || e.message.includes("key")) {
-            console.log(chalk.yellow("👉 Tip: Make sure you have GOOGLE_API_KEY in your .env.local file."));
+            console.log(chalk.yellow("👉 Tip: Make sure you have GEMINI_API_KEY in your .env.local file."));
         }
         process.exit(1);
     }