jstar-reviewer 2.0.3 → 2.1.0

package/README.md

@@ -37,10 +37,13 @@ curl -fsSL https://raw.githubusercontent.com/JStaRFilms/jstar-code-review/v2.0.0
 
 ### 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
+1.  **Check Config**: The tool now **auto-creates** `.env.example` and `.jstar/` when you run it.
+2.  **Add Keys**: Copy `.env.example` → `.env.local` and add your `GOOGLE_API_KEY` and `GROQ_API_KEY`.
+3.  **Index**: Run `jstar init` (or `pnpm run index:init`) to build the brain.
+4.  **Review**: Stage changes (`git add`) and run `jstar review` (or `pnpm run review`).
+
+For a detailed walkthrough, see **[ONBOARDING.md](./ONBOARDING.md)**.
+
 
 ---
 

package/bin/jstar.js

@@ -70,27 +70,51 @@ function commandExists(cmd) {
 }
 
 function runScript(scriptName) {
+    // Look for transpiled files in dist/
+    // .ts becomes .js in dist
+    const jsName = scriptName.replace('.ts', '.js');
+    const distDir = path.join(__dirname, '..', 'dist', 'scripts');
+    const jsPath = path.join(distDir, jsName);
+
+    // Fallback for local development if dist doesn't exist
     const scriptsDir = path.join(__dirname, '..', 'scripts');
-    const scriptPath = path.join(scriptsDir, scriptName);
+    const tsPath = path.join(scriptsDir, scriptName);
+
+    const isWin = process.platform === 'win32';
+
+    if (fs.existsSync(jsPath)) {
+        log(`${COLORS.dim}Running ${jsName}...${COLORS.reset}`);
+        const child = spawn('node', [jsPath, ...process.argv.slice(3)], {
+            cwd: process.cwd(),
+            stdio: 'inherit',
+            shell: isWin,
+            env: {
+                ...process.env,
+                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);
+        });
+        return;
+    }
 
-    if (!fs.existsSync(scriptPath)) {
+    if (!fs.existsSync(tsPath)) {
         log(`${COLORS.red}Error: Script not found: ${scriptPath}${COLORS.reset}`);
         process.exit(1);
     }
 
-    // Prioritize pnpm if available
+    // Fallback to ts-node if dist is not built (mostly for local development)
     const hasPnpm = commandExists('pnpm');
     const runner = hasPnpm ? 'pnpm' : 'npx';
     const runnerArgs = hasPnpm ? ['dlx', 'ts-node'] : ['ts-node'];
 
-    log(`${COLORS.dim}Using ${runner} to run ${scriptName}...${COLORS.reset}`);
+    log(`${COLORS.dim}Using ${runner} (fallback) to run ${scriptName}...${COLORS.reset}`);
 
-    // On Windows, global commands like pnpm/npx are .cmd files.
-    // spawn without shell: true often fails with EINVAL or ENOENT on Windows.
-    // We use shell: true only on Windows for reliability.
-    const isWin = process.platform === 'win32';
-
-    const child = spawn(runner, [...runnerArgs, scriptPath, ...process.argv.slice(3)], {
+    const child = spawn(runner, [...runnerArgs, tsPath, ...process.argv.slice(3)], {
         cwd: process.cwd(),
         stdio: 'inherit',
         shell: isWin,
@@ -110,35 +134,48 @@ function runScript(scriptName) {
     });
 }
 
+const REQUIRED_ENV_VARS = {
+    'GOOGLE_API_KEY': '# Required: Google API key for Gemini embeddings\nGOOGLE_API_KEY=your_google_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'
+};
+
 function createSetupFiles() {
     const cwd = process.cwd();
 
-    // Create .jstar directory
+    // 1. 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
-`;
+    // 2. Create/Update .env.example
+    const envExamplePath = path.join(cwd, '.env.example');
+    if (fs.existsSync(envExamplePath)) {
+        let content = fs.readFileSync(envExamplePath, 'utf-8');
+        let addedKeys = [];
+
+        for (const [key, template] of Object.entries(REQUIRED_ENV_VARS)) {
+            if (!content.includes(key)) {
+                content += '\n' + template + '\n';
+                addedKeys.push(key);
+            }
+        }
 
-    const envPath = path.join(cwd, '.env.example');
-    if (!fs.existsSync(envPath)) {
-        fs.writeFileSync(envPath, envExample);
-        log(`${COLORS.green}✓${COLORS.reset} Created .env.example`);
+        if (addedKeys.length > 0) {
+            fs.writeFileSync(envExamplePath, content);
+            log(`${COLORS.green}✓${COLORS.reset} Updated .env.example with missing keys: ${addedKeys.join(', ')}`);
+        } else {
+            log(`${COLORS.dim}  .env.example already exists and is up to date${COLORS.reset}`);
+        }
     } else {
-        log(`${COLORS.dim}  .env.example already exists${COLORS.reset}`);
+        const initialEnv = "# J-Star Code Reviewer\n" + Object.values(REQUIRED_ENV_VARS).join("\n") + "\n";
+        fs.writeFileSync(envExamplePath, initialEnv);
+        log(`${COLORS.green}✓${COLORS.reset} Created .env.example`);
     }
 
+
     // Update .gitignore
     const gitignorePath = path.join(cwd, '.gitignore');
     const gitignoreAdditions = `

package/dist/scripts/config.js

@@ -0,0 +1,91 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Config = void 0;
+const dotenv_1 = __importDefault(require("dotenv"));
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// --- 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',
+    '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'
+};
+function ensureSetup() {
+    const cwd = process.cwd();
+    const jstarDir = path.join(cwd, ".jstar");
+    const envExamplePath = path.join(cwd, ".env.example");
+    // 1. Ensure .jstar exists
+    if (!fs.existsSync(jstarDir)) {
+        fs.mkdirSync(jstarDir, { recursive: true });
+    }
+    // 2. Ensure .env.example is up to date
+    if (fs.existsSync(envExamplePath)) {
+        let content = fs.readFileSync(envExamplePath, 'utf-8');
+        let missing = false;
+        for (const [key, template] of Object.entries(REQUIRED_ENV_VARS)) {
+            if (!content.includes(key)) {
+                content += `\n${template}\n`;
+                missing = true;
+            }
+        }
+        if (missing) {
+            fs.writeFileSync(envExamplePath, content);
+        }
+    }
+    else {
+        const initialEnv = "# J-Star Code Reviewer\n" + Object.values(REQUIRED_ENV_VARS).join("\n") + "\n";
+        fs.writeFileSync(envExamplePath, initialEnv);
+    }
+}
+// Run setup check
+ensureSetup();
+// Load .env.local first, then .env
+dotenv_1.default.config({ path: ".env.local" });
+dotenv_1.default.config();
+/**
+ * Default fallback values.
+ */
+const DEFAULT_MODEL = "moonshotai/kimi-k2-instruct-0905";
+exports.Config = {
+    MODEL_NAME: process.env.REVIEW_MODEL_NAME || DEFAULT_MODEL,
+    DEFAULT_SEVERITY: 'P2_MEDIUM',
+    THRESHOLDS: {
+        MEDIUM: 5
+    }
+};

package/dist/scripts/dashboard.js

@@ -0,0 +1,217 @@
+"use strict";
+/**
+ * J-Star Dashboard Renderer
+ * Generates professional markdown dashboard from review findings
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderDashboard = renderDashboard;
+exports.determineStatus = determineStatus;
+exports.generateRecommendation = generateRecommendation;
+const config_1 = require("./config");
+const SEVERITY_EMOJI = {
+    'P0_CRITICAL': '🛑',
+    'P1_HIGH': '⚠️',
+    'P2_MEDIUM': '📝',
+    'LGTM': '✅'
+};
+const SEVERITY_LABEL = {
+    'P0_CRITICAL': 'CRITICAL',
+    'P1_HIGH': 'HIGH',
+    'P2_MEDIUM': 'MEDIUM',
+    'LGTM': 'PASSED'
+};
+function getStatusEmoji(status) {
+    switch (status) {
+        case 'CRITICAL_FAILURE': return '🔴';
+        case 'NEEDS_REVIEW': return '🟡';
+        case 'APPROVED': return '🟢';
+    }
+}
+function formatDate() {
+    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, issue, severity) {
+    // 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) {
+    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) {
+    if (!report || typeof report !== 'object')
+        return false;
+    const r = report;
+    // 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;
+    const requiredMetrics = ['filesScanned', 'totalTokens', 'violations', 'critical', 'high', 'medium', 'lgtm'];
+    for (const key of requiredMetrics) {
+        if (typeof m[key] !== 'number')
+            return false;
+    }
+    return true;
+}
+function renderDashboard(report) {
+    // 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;
+}
+function determineStatus(metrics) {
+    if (metrics.critical > 0)
+        return 'CRITICAL_FAILURE';
+    if (metrics.high > 0 || metrics.medium > config_1.Config.THRESHOLDS.MEDIUM)
+        return 'NEEDS_REVIEW';
+    return 'APPROVED';
+}
+function generateRecommendation(metrics) {
+    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! 🚀`;
+}

package/dist/scripts/detective.js

@@ -0,0 +1,150 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Detective = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const RULES = [
+    {
+        id: 'SEC-001',
+        severity: 'high',
+        message: 'Possible Hardcoded Secret detected',
+        pattern: /(api_key|secret|password|token)\s*[:=]\s*['"`][a-zA-Z0-9_\-\.]{10,}['"`]/i
+    },
+    {
+        id: 'ARCH-001',
+        severity: 'medium',
+        message: 'Avoid using console.log in production code',
+        pattern: /console\.log\(/
+    },
+];
+// File-level rules that check the whole content
+const FILE_RULES = [
+    {
+        id: 'ARCH-002',
+        severity: 'high',
+        message: 'Next.js "use client" must be at the very top of the file',
+        pattern: /^(?!['"]use client['"]).*['"]use client['"]/s,
+        filePattern: /\.tsx?$/
+    }
+];
+class Detective {
+    constructor(directory) {
+        this.directory = directory;
+        this.violations = [];
+    }
+    async scan() {
+        this.walk(this.directory);
+        return this.violations;
+    }
+    walk(dir) {
+        if (!fs.existsSync(dir))
+            return;
+        const files = fs.readdirSync(dir);
+        for (const file of files) {
+            const filePath = path.join(dir, file);
+            const stat = fs.statSync(filePath);
+            if (stat.isDirectory()) {
+                if (file !== 'node_modules' && file !== '.git' && file !== '.jstar') {
+                    this.walk(filePath);
+                }
+            }
+            else {
+                this.checkFile(filePath);
+            }
+        }
+    }
+    checkFile(filePath) {
+        if (!filePath.match(/\.(ts|tsx|js|jsx)$/))
+            return;
+        const content = fs.readFileSync(filePath, 'utf-8');
+        const lines = content.split('\n');
+        // Line-based rules
+        for (const rule of RULES) {
+            if (rule.filePattern && !filePath.match(rule.filePattern))
+                continue;
+            lines.forEach((line, index) => {
+                if (rule.pattern.test(line)) {
+                    this.addViolation(filePath, index + 1, rule);
+                }
+            });
+        }
+        // File-based rules
+        for (const rule of FILE_RULES) {
+            if (rule.filePattern && !filePath.match(rule.filePattern))
+                continue;
+            if (rule.pattern.test(content)) {
+                this.addViolation(filePath, 1, rule);
+            }
+        }
+    }
+    addViolation(filePath, line, rule) {
+        this.violations.push({
+            file: path.relative(process.cwd(), filePath),
+            line,
+            message: rule.message,
+            severity: rule.severity,
+            code: rule.id
+        });
+    }
+    report() {
+        if (this.violations.length === 0) {
+            console.log(chalk_1.default.green("✅ Detective Engine: No violations found."));
+            return;
+        }
+        console.log(chalk_1.default.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_1.default.red : chalk_1.default.yellow;
+            console.log(color(`[${v.code}] ${v.file}:${v.line} - ${v.message}`));
+        });
+        if (total > 10) {
+            console.log(chalk_1.default.dim(`... and ${total - 10} more.`));
+        }
+    }
+}
+exports.Detective = Detective;
+// CLI Integration
+if (require.main === module) {
+    const detective = new Detective(path.join(process.cwd(), 'src'));
+    detective.scan();
+    detective.report();
+}