jstar-reviewer 2.0.0

package/README.md

@@ -0,0 +1,147 @@
+# J-Star Code Reviewer
+
+**Local-first, context-aware AI code reviewer** powered by LlamaIndex + Groq.
+
+Works with **any language** — TypeScript, Python, Rust, Go, you name it.
+
+## ✨ Features
+
+- **Local Vector Index** — Embeddings stored locally, no external DB
+- **Gemini Embeddings** — Free tier friendly, no OpenAI key needed
+- **Chunked Reviews** — Handles large diffs without rate limits
+- **Detective Engine** — Deterministic checks for common issues
+- **Dashboard Output** — Professional review reports with fix prompts
+- **Global CLI** — Install once, use in any project
+
+---
+
+## 🚀 Quick Install
+
+### Option 1: Global CLI (Recommended)
+
+```bash
+# Install globally
+npm install -g jstar-reviewer
+
+# In any project directory:
+jstar setup      # Create config files
+jstar init       # Index the codebase
+jstar review     # Review staged changes
+```
+
+### Option 2: One-Curl (Adds to current project)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/JStaRFilms/jstar-code-review/v2.0.0/setup.js | node
+```
+
+### After Install:
+
+1. Copy `.env.example` → `.env.local`
+2. Add your `GOOGLE_API_KEY` and `GROQ_API_KEY`
+3. Run `jstar init` to build the brain
+4. Run `jstar review` to review staged changes
+
+---
+
+```
+git diff --staged
+       │
+       ▼
+┌──────────────────┐
+│  Detective       │  ← Static analysis (secrets, console.log, "use client")
+│  Engine          │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  Local Brain     │  ← Gemini embeddings via LlamaIndex
+│  (Retrieval)     │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  Chunked Review  │  ← Splits diff by file, delays between calls
+│  Queue           │
+└────────┬─────────┘
+         │
+         ▼
+┌──────────────────┐
+│  Groq LLM        │  ← moonshotai/kimi-k2-instruct-0905
+│  (The Judge)     │
+└────────┬─────────┘
+         │
+         ▼
+   📝 Review Report
+```
+
+## 🚀 Quick Start
+
+### 1. Install Dependencies
+
+```bash
+pnpm install
+```
+
+### 2. Set Environment Variables
+
+Create `.env.local`:
+
+```env
+GOOGLE_API_KEY=your_gemini_key
+GROQ_API_KEY=your_groq_key
+```
+
+### 3. Index Your Codebase
+
+```bash
+pnpm run index:init
+```
+
+### 4. Review Staged Changes
+
+```bash
+git add <files>
+pnpm run review
+```
+
+## 📁 Project Structure
+
+```
+scripts/
+├── indexer.ts          # Scans codebase, builds vector index
+├── reviewer.ts         # Orchestrates review pipeline
+├── detective.ts        # Static analysis engine
+├── gemini-embedding.ts # Google Gemini adapter
+└── mock-llm.ts         # LlamaIndex compatibility stub
+
+.jstar/
+└── storage/            # Persisted embeddings (gitignored)
+
+docs/features/
+├── architecture-v2.md  # Full architecture docs
+├── detective.md        # Static analysis rules
+├── analyst.md          # LLM reviewer (The Judge)
+└── ...
+```
+
+## ⚙️ Configuration
+
+Edit `scripts/reviewer.ts`:
+
+```typescript
+const MODEL_NAME = "moonshotai/kimi-k2-instruct-0905";
+const MAX_TOKENS_PER_REQUEST = 8000;
+const DELAY_BETWEEN_CHUNKS_MS = 2000;
+```
+
+## 📚 Documentation
+
+- [Architecture v2](docs/features/architecture-v2.md)
+- [Detective Engine](docs/features/detective.md)
+- [Token Budget](docs/features/token-budget.md)
+- [Chunked Reviews](docs/features/map-reduce.md)
+
+---
+
+Built with ⚡ by J Star Studios

package/bin/jstar.js

@@ -0,0 +1,170 @@
+#!/usr/bin/env node
+/**
+ * J-Star Reviewer CLI
+ * Global command-line tool for AI-powered code review
+ * 
+ * Usage:
+ *   jstar init     - Index the current directory
+ *   jstar review   - Review staged changes
+ *   jstar setup    - Set up config in current project
+ */
+
+const { spawn } = require('child_process');
+const path = require('path');
+const fs = require('fs');
+
+const COLORS = {
+    reset: '\x1b[0m',
+    green: '\x1b[32m',
+    yellow: '\x1b[33m',
+    blue: '\x1b[34m',
+    red: '\x1b[31m',
+    dim: '\x1b[2m',
+    bold: '\x1b[1m'
+};
+
+function log(msg) {
+    console.log(msg);
+}
+
+function printHelp() {
+    log(`
+${COLORS.bold}🌟 J-Star Reviewer v2${COLORS.reset}
+
+${COLORS.dim}AI-powered code review with local embeddings${COLORS.reset}
+
+${COLORS.bold}USAGE:${COLORS.reset}
+  jstar <command> [options]
+
+${COLORS.bold}COMMANDS:${COLORS.reset}
+  ${COLORS.green}init${COLORS.reset}      Index the current codebase (build the brain)
+  ${COLORS.green}review${COLORS.reset}    Review staged git changes
+  ${COLORS.green}setup${COLORS.reset}     Create .env.example and .jstar/ in current directory
+
+${COLORS.bold}EXAMPLES:${COLORS.reset}
+  ${COLORS.dim}# First time setup${COLORS.reset}
+  jstar init
+
+  ${COLORS.dim}# Review staged changes${COLORS.reset}
+  git add .
+  jstar review
+
+${COLORS.bold}ENVIRONMENT:${COLORS.reset}
+  GOOGLE_API_KEY    Required for Gemini embeddings
+  GROQ_API_KEY      Required for Groq LLM reviews
+
+${COLORS.dim}Report issues: https://github.com/JStaRFilms/jstar-code-review${COLORS.reset}
+`);
+}
+
+function runScript(scriptName) {
+    const scriptsDir = path.join(__dirname, '..', 'scripts');
+    const scriptPath = path.join(scriptsDir, scriptName);
+
+    if (!fs.existsSync(scriptPath)) {
+        log(`${COLORS.red}Error: Script not found: ${scriptPath}${COLORS.reset}`);
+        process.exit(1);
+    }
+
+    // Use ts-node to run TypeScript files
+    const child = spawn('npx', ['ts-node', scriptPath, ...process.argv.slice(3)], {
+        cwd: process.cwd(),
+        stdio: 'inherit',
+        shell: true,
+        env: {
+            ...process.env,
+            // Pass through the working directory for the scripts
+            JSTAR_CWD: process.cwd()
+        }
+    });
+
+    child.on('close', (code) => {
+        process.exit(code || 0);
+    });
+
+    child.on('error', (err) => {
+        log(`${COLORS.red}Error running script: ${err.message}${COLORS.reset}`);
+        process.exit(1);
+    });
+}
+
+function createSetupFiles() {
+    const cwd = process.cwd();
+
+    // Create .jstar directory
+    const jstarDir = path.join(cwd, '.jstar');
+    if (!fs.existsSync(jstarDir)) {
+        fs.mkdirSync(jstarDir, { recursive: true });
+        log(`${COLORS.green}✓${COLORS.reset} Created .jstar/`);
+    }
+
+    // Create .env.example
+    const envExample = `# J-Star Reviewer Configuration
+# Copy this to .env.local and fill in your keys
+
+# Required: Google API key for Gemini embeddings
+GOOGLE_API_KEY=your_google_api_key_here
+
+# Required: Groq API key for LLM reviews
+GROQ_API_KEY=your_groq_api_key_here
+`;
+
+    const envPath = path.join(cwd, '.env.example');
+    if (!fs.existsSync(envPath)) {
+        fs.writeFileSync(envPath, envExample);
+        log(`${COLORS.green}✓${COLORS.reset} Created .env.example`);
+    } else {
+        log(`${COLORS.dim}  .env.example already exists${COLORS.reset}`);
+    }
+
+    // Update .gitignore
+    const gitignorePath = path.join(cwd, '.gitignore');
+    const gitignoreAdditions = `
+# J-Star Reviewer
+.jstar/
+.env.local
+`;
+
+    if (fs.existsSync(gitignorePath)) {
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        if (!content.includes('.jstar/')) {
+            fs.appendFileSync(gitignorePath, gitignoreAdditions);
+            log(`${COLORS.green}✓${COLORS.reset} Updated .gitignore`);
+        }
+    } else {
+        fs.writeFileSync(gitignorePath, gitignoreAdditions.trim());
+        log(`${COLORS.green}✓${COLORS.reset} Created .gitignore`);
+    }
+
+    log(`
+${COLORS.bold}Next steps:${COLORS.reset}
+  1. Copy .env.example to .env.local
+  2. Add your API keys
+  3. Run: jstar init
+  4. Stage changes and run: jstar review
+`);
+}
+
+// Main
+const command = process.argv[2];
+
+switch (command) {
+    case 'init':
+        runScript('indexer.ts');
+        break;
+    case 'review':
+        runScript('reviewer.ts');
+        break;
+    case 'setup':
+        createSetupFiles();
+        break;
+    case '--help':
+    case '-h':
+    case undefined:
+        printHelp();
+        break;
+    default:
+        log(`${COLORS.red}Unknown command: ${command}${COLORS.reset}`);
+        printHelp();
+        process.exit(1);
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "jstar-reviewer",
+  "version": "2.0.0",
+  "description": "Local-First, Context-Aware AI Code Reviewer - Works with any language",
+  "bin": {
+    "jstar": "bin/jstar.js"
+  },
+  "scripts": {
+    "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",
+    "prepare": "husky install"
+  },
+  "keywords": [
+    "code-review",
+    "ai",
+    "llm",
+    "cli",
+    "groq",
+    "gemini",
+    "static-analysis"
+  ],
+  "author": "J Star Studios",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/JStaRFilms/jstar-code-review.git"
+  },
+  "homepage": "https://github.com/JStaRFilms/jstar-code-review#readme",
+  "dependencies": {
+    "@ai-sdk/google": "^2.0.49",
+    "@ai-sdk/groq": "^2.0.33",
+    "@google/generative-ai": "^0.24.1",
+    "ai": "^5.0.115",
+    "chalk": "^4.1.2",
+    "dotenv": "^16.3.1",
+    "llamaindex": "^0.1.0",
+    "simple-git": "^3.20.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "ts-node": "^10.9.1",
+    "typescript": "^5.2.2",
+    "husky": "^8.0.3"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "README.md"
+  ],
+  "main": "setup.js",
+  "directories": {
+    "doc": "docs",
+    "test": "test"
+  },
+  "type": "commonjs",
+  "bugs": {
+    "url": "https://github.com/JStaRFilms/jstar-code-review/issues"
+  }
+}

package/scripts/config.ts

@@ -0,0 +1,21 @@
+import dotenv from "dotenv";
+import { Severity } from "./types";
+
+// Load .env.local first, then .env
+dotenv.config({ path: ".env.local" });
+dotenv.config();
+
+/**
+ * Default fallback values.
+ * These are intentional fallbacks when environment variables are not configured.
+ * Override via REVIEW_MODEL_NAME env var for production use.
+ */
+const DEFAULT_MODEL = "moonshotai/kimi-k2-instruct-0905";
+
+export const Config = {
+    MODEL_NAME: process.env.REVIEW_MODEL_NAME || DEFAULT_MODEL,
+    DEFAULT_SEVERITY: 'P2_MEDIUM' as Severity,
+    THRESHOLDS: {
+        MEDIUM: 5
+    }
+};

package/scripts/dashboard.ts

@@ -0,0 +1,227 @@
+/**
+ * J-Star Dashboard Renderer
+ * Generates professional markdown dashboard from review findings
+ */
+
+import { DashboardReport, FileFinding, ReviewIssue, Severity } from './types';
+import { Config } from './config';
+
+const SEVERITY_EMOJI: Record<Severity, string> = {
+    'P0_CRITICAL': '🛑',
+    'P1_HIGH': '⚠️',
+    'P2_MEDIUM': '📝',
+    'LGTM': '✅'
+};
+
+const SEVERITY_LABEL: Record<Severity, string> = {
+    'P0_CRITICAL': 'CRITICAL',
+    'P1_HIGH': 'HIGH',
+    'P2_MEDIUM': 'MEDIUM',
+    'LGTM': 'PASSED'
+};
+
+function getStatusEmoji(status: DashboardReport['status']): string {
+    switch (status) {
+        case 'CRITICAL_FAILURE': return '🔴';
+        case 'NEEDS_REVIEW': return '🟡';
+        case 'APPROVED': return '🟢';
+    }
+}
+
+function formatDate(): string {
+    return new Date().toISOString().split('T')[0];
+}
+
+/**
+ * Renders a single issue row for the markdown table.
+ * Includes fallback handling for unexpected severity values to ensure
+ * the dashboard renders gracefully even if parsing produced invalid data.
+ */
+function renderIssueRow(file: string, issue: ReviewIssue, severity: Severity): string {
+    // Fallback to '❓' and raw severity if the value is not in our known maps
+    const emoji = SEVERITY_EMOJI[severity] ?? '❓';
+    const label = SEVERITY_LABEL[severity] ?? severity;
+    return `| \`${file}\` | ${emoji} **${label}** | ${issue.title} |`;
+}
+
+function renderFixPrompt(issue: ReviewIssue): string {
+    if (!issue.fixPrompt) return '';
+    return `
+<details>
+<summary>🤖 <strong>Fix Prompt:</strong> ${issue.title}</summary>
+
+\`\`\`
+${issue.fixPrompt}
+\`\`\`
+
+</details>
+`;
+}
+
+/**
+ * Validates that the report object has the required structure.
+ * This guards against runtime errors from malformed LLM responses or corrupted data.
+ */
+function validateReport(report: unknown): report is DashboardReport {
+    if (!report || typeof report !== 'object') return false;
+    const r = report as Record<string, unknown>;
+
+    // Check required fields exist
+    if (typeof r.status !== 'string') return false;
+    if (typeof r.recommendedAction !== 'string') return false;
+    if (!Array.isArray(r.findings)) return false;
+    if (!r.metrics || typeof r.metrics !== 'object') return false;
+
+    // Validate metrics structure
+    const m = r.metrics as Record<string, unknown>;
+    const requiredMetrics = ['filesScanned', 'totalTokens', 'violations', 'critical', 'high', 'medium', 'lgtm'];
+    for (const key of requiredMetrics) {
+        if (typeof m[key] !== 'number') return false;
+    }
+
+    return true;
+}
+
+export function renderDashboard(report: DashboardReport): string {
+    // Runtime validation to catch malformed reports early
+    if (!validateReport(report)) {
+        throw new Error('Invalid DashboardReport: missing or malformed required fields');
+    }
+
+    const { metrics, findings, status, recommendedAction } = report;
+
+    // Group findings by severity
+    const critical = findings.filter(f => f.severity === 'P0_CRITICAL');
+    const high = findings.filter(f => f.severity === 'P1_HIGH');
+    const medium = findings.filter(f => f.severity === 'P2_MEDIUM');
+    const lgtm = findings.filter(f => f.severity === 'LGTM');
+
+    let md = `# 📊 J-STAR CODE REVIEW DASHBOARD
+
+**Date:** \`${formatDate()}\` | **Reviewer:** \`Detective Engine & Judge\` | **Status:** ${getStatusEmoji(status)} **${status.replace('_', ' ')}**
+
+---
+
+## 1. 📈 EXECUTIVE SUMMARY
+
+| Metric | Value | Status |
+| --- | --- | --- |
+| **Files Scanned** | **${metrics.filesScanned}** | 🔎 Complete |
+| **Total Tokens** | **~${metrics.totalTokens.toLocaleString()}** | ⚖️ Processed |
+| **Total Violations** | **${metrics.violations}** | ${metrics.violations > 0 ? '🚨 Action Required' : '✅ Clean'} |
+| **Critical (P0)** | **${metrics.critical}** | ${metrics.critical > 0 ? '🛑 **BLOCKER**' : '✅ None'} |
+| **High (P1)** | **${metrics.high}** | ${metrics.high > 0 ? '⚠️ Needs Fix' : '✅ None'} |
+| **Medium (P2)** | **${metrics.medium}** | ${metrics.medium > 0 ? '📝 Review' : '✅ None'} |
+| **Passed (LGTM)** | **${metrics.lgtm}** | ✅ Clean |
+
+---
+
+`;
+
+    // Critical Section
+    if (critical.length > 0) {
+        md += `## 2. 🛑 CRITICAL SECURITY VULNERABILITIES (P0)
+
+> **These files contain blockers that must be fixed before any merge.**
+
+| File | Severity | Issue |
+| --- | --- | --- |
+`;
+        for (const finding of critical) {
+            for (const issue of finding.issues) {
+                md += renderIssueRow(finding.file, issue, 'P0_CRITICAL') + '\n';
+            }
+        }
+        md += '\n### 🤖 Fix Prompts (P0)\n\n';
+        for (const finding of critical) {
+            for (const issue of finding.issues) {
+                md += renderFixPrompt(issue);
+            }
+        }
+        md += '\n---\n\n';
+    }
+
+    // High Section
+    if (high.length > 0) {
+        md += `## 3. ⚠️ HIGH PRIORITY ISSUES (P1)
+
+> **Architecture and logic issues requiring significant attention.**
+
+| File | Severity | Issue |
+| --- | --- | --- |
+`;
+        for (const finding of high) {
+            for (const issue of finding.issues) {
+                md += renderIssueRow(finding.file, issue, 'P1_HIGH') + '\n';
+            }
+        }
+        md += '\n### 🤖 Fix Prompts (P1)\n\n';
+        for (const finding of high) {
+            for (const issue of finding.issues) {
+                md += renderFixPrompt(issue);
+            }
+        }
+        md += '\n---\n\n';
+    }
+
+    // Medium Section
+    if (medium.length > 0) {
+        md += `## 4. 📝 MEDIUM PRIORITY ISSUES (P2)
+
+> **Code quality and maintenance items.**
+
+| File | Severity | Issue |
+| --- | --- | --- |
+`;
+        for (const finding of medium) {
+            for (const issue of finding.issues) {
+                md += renderIssueRow(finding.file, issue, 'P2_MEDIUM') + '\n';
+            }
+        }
+        md += '\n---\n\n';
+    }
+
+    // LGTM Section
+    if (lgtm.length > 0) {
+        md += `## 5. ✅ PASSED REVIEW (LGTM)
+
+> **No issues found in these files.**
+
+`;
+        for (const finding of lgtm) {
+            md += `- \`${finding.file}\`\n`;
+        }
+        md += '\n---\n\n';
+    }
+
+    // Recommended Action
+    md += `## 🎯 RECOMMENDED ACTION
+
+> ${recommendedAction}
+
+---
+
+*Generated by J-Star Code Reviewer v2*
+`;
+
+    return md;
+}
+
+export function determineStatus(metrics: DashboardReport['metrics']): DashboardReport['status'] {
+    if (metrics.critical > 0) return 'CRITICAL_FAILURE';
+    if (metrics.high > 0 || metrics.medium > Config.THRESHOLDS.MEDIUM) return 'NEEDS_REVIEW';
+    return 'APPROVED';
+}
+
+export function generateRecommendation(metrics: DashboardReport['metrics']): string {
+    if (metrics.critical > 0) {
+        return `**BLOCK MERGE:** Fix ${metrics.critical} critical issue(s) immediately. Review P0 fix prompts above.`;
+    }
+    if (metrics.high > 0) {
+        return `**Request Changes:** Address ${metrics.high} high-priority issue(s) before merging.`;
+    }
+    if (metrics.medium > 0) {
+        return `**Approve with Notes:** ${metrics.medium} medium issues found. Consider fixing in follow-up PR.`;
+    }
+    return `**Approve:** All files passed review. Ship it! 🚀`;
+}