jstar-reviewer 2.4.0 → 2.4.2

package/bin/jstar.js

@@ -29,7 +29,7 @@ function log(msg) {
 
 function printHelp() {
     log(`
-${COLORS.bold}🌟 J-Star Reviewer v2.4.0${COLORS.reset}
+${COLORS.bold}🌟 J-Star Reviewer v2.4.2${COLORS.reset}
 
 ${COLORS.dim}AI-powered code review with local embeddings${COLORS.reset}
 
@@ -40,20 +40,34 @@ ${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}chat${COLORS.reset}      Resume an interactive session from the last review
+  ${COLORS.green}detect${COLORS.reset}    Run static analysis (Detective Engine)
   ${COLORS.green}setup${COLORS.reset}     Create .env.example and .jstar/ in current directory
 
 ${COLORS.bold}OPTIONS:${COLORS.reset}
   ${COLORS.yellow}--json${COLORS.reset}      Output machine-readable JSON (for CI/CD)
   ${COLORS.yellow}--headless${COLORS.reset}  Enable stdin/stdout protocol (for AI agents)
 
+${COLORS.bold}REVIEW OPTIONS:${COLORS.reset}
+  ${COLORS.yellow}--pr${COLORS.reset}        Review a Pull Request (compare against main/base)
+  ${COLORS.yellow}--base <br>${COLORS.reset} Specify base branch for PR review (default: main)
+  ${COLORS.yellow}--last${COLORS.reset}      Review the very last commit (HEAD~1..HEAD)
+  ${COLORS.yellow}--commit <h>${COLORS.reset} Review a specific commit hash
+  ${COLORS.yellow}--range <a> <b>${COLORS.reset} Review diff between two refs
+
 ${COLORS.bold}EXAMPLES:${COLORS.reset}
   ${COLORS.dim}# First time setup${COLORS.reset}
   jstar init
 
-  ${COLORS.dim}# Review staged changes${COLORS.reset}
-  git add .
+  ${COLORS.dim}# Review staged changes (default)${COLORS.reset}
   jstar review
 
+  ${COLORS.dim}# Review a Pull Request${COLORS.reset}
+  jstar review --pr
+  jstar review --pr --base develop
+
+  ${COLORS.dim}# Review the last commit${COLORS.reset}
+  jstar review --last
+
   ${COLORS.dim}# JSON output for CI${COLORS.reset}
   jstar review --json > report.json
 
@@ -225,6 +239,10 @@ switch (command) {
     case 'chat':
         runScript('chat.ts');
         break;
+    case 'detect':
+    case 'det':
+        runScript('detective.ts');
+        break;
     case 'setup':
         createSetupFiles();
         break;

package/dist/scripts/chat.js

@@ -58,7 +58,11 @@ async function loadSession() {
     }
     catch (e) {
         if (e.code === 'ENOENT') {
-            return null; // File doesn't exist
+            return null; // File doesn't exist, start fresh
+        }
+        if (e instanceof SyntaxError) {
+            logger_1.Logger.warn(chalk_1.default.yellow("⚠️  Session file corrupted. Starting fresh."));
+            return null;
         }
         logger_1.Logger.error(`Failed to load session: ${e.message}`);
         return null;

package/dist/scripts/core/debate.js

@@ -1,21 +1,18 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.debateIssue = debateIssue;
 const llamaindex_1 = require("llamaindex");
 const ai_1 = require("ai");
 const groq_1 = require("@ai-sdk/groq");
 const config_1 = require("../config");
-const chalk_1 = __importDefault(require("chalk"));
+const logger_1 = require("../utils/logger");
 const groq = (0, groq_1.createGroq)({ apiKey: process.env.GROQ_API_KEY });
 async function debateIssue(issueTitle, issueDescription, fileName, userArgument, index) {
     // 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_1.default.dim("   🧠  Thinking... (Consulting the Brain)"));
+    logger_1.Logger.dim("   🧠  Thinking... (Consulting the Brain)");
     // 1. Extract keywords/context
     const query = `${userArgument} ${issueTitle}`;
     // 2. Retrieve new context
@@ -23,11 +20,11 @@ async function debateIssue(issueTitle, issueDescription, fileName, userArgument,
     const contextNodes = await retriever.retrieve(query);
     const newContext = contextNodes.map(n => n.node.getContent(llamaindex_1.MetadataMode.NONE)).join("\n\n").slice(0, 2000);
     if (newContext.length >= 2000) {
-        console.log(chalk_1.default.yellow("   ⚠️  Context truncated to 2000 chars"));
+        logger_1.Logger.warn("   ⚠️  Context truncated to 2000 chars");
     }
     const sources = contextNodes.map(n => n.node.metadata?.['file_name']).filter(Boolean).join(', ');
     if (sources) {
-        console.log(chalk_1.default.dim(`   🔍  Found relevant context from: ${sources}`));
+        logger_1.Logger.dim(`   🔍  Found relevant context from: ${sources}`);
     }
     // 3. Ask the Judge
     const systemPrompt = `You are a Senior Code Reviewer in a debate with a developer.

package/dist/scripts/detective.js

@@ -52,7 +52,8 @@ const RULES = [
         id: 'ARCH-001',
         severity: 'medium',
         message: 'Avoid using console.log in production code',
-        pattern: /console\.log\(/
+        pattern: /console\.log\(/,
+        excludePattern: /(bin[\\/]jstar\.js|scripts[\\/]utils[\\/]logger\.ts|setup\.js|test[\\/])/
     },
 ];
 // File-level rules that check the whole content
@@ -60,15 +61,17 @@ 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?$/
+        message: 'Next.js "use client" must be at the very top of the file (before imports)',
+        pattern: /^(?!(?:\s*|(?:\/\/[^\n]*\n)|(?:\/\*[\s\S]*?\*\/))*['"]use client['"]).*['"]use client['"]/s,
+        filePattern: /\.tsx?$/,
+        excludePattern: /(scripts|test)[\\/]/
     }
 ];
 class Detective {
-    constructor(directory) {
+    constructor(directory, options = {}) {
         this.directory = directory;
         this.violations = [];
+        this.includeBuildFiles = options.includeBuildFiles ?? false;
     }
     async scan() {
         this.walk(this.directory);
@@ -82,9 +85,12 @@ class Detective {
             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);
+                // Ignore common build/config directories
+                const ignoredDirs = ['node_modules', '.git', '.jstar', 'dist', 'coverage', '.next'];
+                if (!this.includeBuildFiles && ignoredDirs.includes(file)) {
+                    continue;
                 }
+                this.walk(filePath);
             }
             else {
                 this.checkFile(filePath);
@@ -94,12 +100,17 @@ class Detective {
     checkFile(filePath) {
         if (!filePath.match(/\.(ts|tsx|js|jsx)$/))
             return;
+        // Skip .d.ts files
+        if (filePath.endsWith('.d.ts'))
+            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;
+            if (rule.excludePattern && filePath.match(rule.excludePattern))
+                continue;
             lines.forEach((line, index) => {
                 if (rule.pattern.test(line)) {
                     this.addViolation(filePath, index + 1, rule);
@@ -110,6 +121,8 @@ class Detective {
         for (const rule of FILE_RULES) {
             if (rule.filePattern && !filePath.match(rule.filePattern))
                 continue;
+            if (rule.excludePattern && filePath.match(rule.excludePattern))
+                continue;
             if (rule.pattern.test(content)) {
                 this.addViolation(filePath, 1, rule);
             }
@@ -145,7 +158,10 @@ class Detective {
 exports.Detective = Detective;
 // CLI Integration
 if (require.main === module) {
-    const detective = new Detective(path.join(process.cwd(), 'src'));
+    const args = process.argv.slice(2);
+    const includeBuildFiles = args.includes('--all');
+    // Scan current directory by default
+    const detective = new Detective(process.cwd(), { includeBuildFiles });
     detective.scan();
     detective.report();
 }

package/dist/scripts/gemini-embedding.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.GeminiEmbedding = void 0;
 const generative_ai_1 = require("@google/generative-ai");
+const logger_1 = require("./utils/logger");
 class GeminiEmbedding {
     constructor() {
         // Stubs for BaseEmbedding compliance
@@ -27,7 +28,7 @@ class GeminiEmbedding {
                 if (e.message.includes("fetch failed") || e.message.includes("network")) {
                     retries++;
                     const waitTime = Math.pow(2, retries) * 1000;
-                    console.warn(`⚠️ Network error. Retrying in ${waitTime / 1000}s... (${retries}/${maxRetries})`);
+                    logger_1.Logger.warn(`⚠️ Network error. Retrying in ${waitTime / 1000}s... (${retries}/${maxRetries})`);
                     await new Promise(resolve => setTimeout(resolve, waitTime));
                 }
                 else {
@@ -42,7 +43,7 @@ class GeminiEmbedding {
     }
     async getTextEmbeddings(texts) {
         const embeddings = [];
-        console.log(`Creating embeddings for ${texts.length} chunks (Batching to avoid rate limits)...`);
+        logger_1.Logger.info(`Creating embeddings for ${texts.length} chunks (Batching to avoid rate limits)...`);
         // Process in smaller batches with delay
         const BATCH_SIZE = 1; // Strict serial for safety on free tier
         const DELAY_MS = 1000; // 1s delay between calls
@@ -58,17 +59,17 @@ class GeminiEmbedding {
                         success = true;
                         // Standard delay between calls
                         await new Promise(resolve => setTimeout(resolve, DELAY_MS));
-                        process.stdout.write("."); // Progress indicator
+                        logger_1.Logger.inline("."); // Progress indicator
                     }
                     catch (e) {
                         if (e.message.includes("429") || e.message.includes("quota")) {
                             retries++;
                             const waitTime = Math.pow(2, retries) * 2000; // 2s, 4s, 8s, 16s...
-                            console.warn(`\n⚠️  Rate limit hit. Retrying in ${waitTime / 1000}s...`);
+                            logger_1.Logger.warn(`\n⚠️  Rate limit hit. Retrying in ${waitTime / 1000}s...`);
                             await new Promise(resolve => setTimeout(resolve, waitTime));
                         }
                         else {
-                            console.error("\n❌ Embedding failed irreversibly:", e.message);
+                            logger_1.Logger.error("\n❌ Embedding failed irreversibly: " + e.message);
                             throw e;
                         }
                     }
@@ -78,7 +79,7 @@ class GeminiEmbedding {
                 }
             }
         }
-        console.log("\n✅ Done embedding.");
+        logger_1.Logger.success("\n✅ Done embedding.");
         return embeddings;
     }
     similarity(embedding1, embedding2) {

package/dist/scripts/indexer.js

@@ -42,6 +42,7 @@ const mock_llm_1 = require("./mock-llm");
 const path = __importStar(require("path"));
 const fs = __importStar(require("fs"));
 const chalk_1 = __importDefault(require("chalk"));
+const logger_1 = require("./utils/logger");
 // IMPORTANT: Import config for side effects (loads dotenv from cwd)
 require("./config");
 // Configuration
@@ -57,7 +58,7 @@ function getSourceDir() {
         if (fs.existsSync(customPath)) {
             return customPath;
         }
-        console.error(chalk_1.default.red(`❌ Custom path not found: ${customPath}`));
+        logger_1.Logger.error(`❌ Custom path not found: ${customPath}`);
         process.exit(1);
     }
     // 2. Try common source directories
@@ -76,30 +77,49 @@ function getSourceDir() {
     return cwd;
 }
 async function main() {
+    logger_1.Logger.init(); // Initialize Logger (auto-detects modes)
     // 0. Environment Validation
     const geminiKey = process.env.GEMINI_API_KEY || process.env.GOOGLE_API_KEY || process.env.GOOGLE_GENERATIVE_AI_API_KEY;
     if (!geminiKey) {
-        console.error(chalk_1.default.red("❌ Missing GEMINI_API_KEY (or GOOGLE_API_KEY)!"));
-        console.log(chalk_1.default.yellow("\nPlease ensure you have a .env.local file. Check .env.example for a template.\n"));
+        logger_1.Logger.error("❌ Missing GEMINI_API_KEY (or GOOGLE_API_KEY)!");
+        logger_1.Logger.warn("\nPlease ensure you have a .env.local file. Check .env.example for a template.\n");
         process.exit(1);
     }
     const args = process.argv.slice(2);
     const isWatch = args.includes("--watch");
     const SOURCE_DIR = getSourceDir();
-    console.log(chalk_1.default.blue("🧠 J-Star Indexer: Scanning codebase..."));
-    console.log(chalk_1.default.dim(`   Source: ${SOURCE_DIR}`));
+    logger_1.Logger.info(chalk_1.default.blue("🧠 J-Star Indexer: Scanning codebase..."));
+    logger_1.Logger.dim(`   Source: ${SOURCE_DIR}`);
     // 1. Load documents (Your Code)
     if (!fs.existsSync(SOURCE_DIR)) {
-        console.error(chalk_1.default.red(`❌ Source directory not found: ${SOURCE_DIR}`));
+        logger_1.Logger.error(`❌ Source directory not found: ${SOURCE_DIR}`);
         process.exit(1);
     }
     const reader = new llamaindex_1.SimpleDirectoryReader();
     const documents = await reader.loadData({ directoryPath: SOURCE_DIR });
-    console.log(chalk_1.default.yellow(`📄 Found ${documents.length} files to index.`));
+    // --- SECURITY FILTER ---
+    // Exclude sensitive files (like .env) and build artifacts
+    const EXCLUDED_PATTERNS = [
+        /pnpm-lock\.yaml/,
+        /package-lock\.json/,
+        /yarn\.lock/,
+        /\.env/,
+        /\.DS_Store/,
+        /node_modules/,
+        /\.git/,
+        /\.jstar/,
+        /\.json$/, // Prefer code over JSON data for context unless docs
+    ];
+    const filteredDocuments = documents.filter(doc => {
+        const filePath = doc.metadata?.file_path || doc.id_ || '';
+        // Check strict exclusions
+        const isExcluded = EXCLUDED_PATTERNS.some(pattern => pattern.test(filePath));
+        return !isExcluded;
+    });
+    logger_1.Logger.info(chalk_1.default.yellow(`📄 Found ${documents.length} files. Indexing ${filteredDocuments.length} valid files (filtered ${documents.length - filteredDocuments.length} excluded).`));
     const isInit = args.includes("--init");
     try {
         // 2. Setup Service Context with Google Gemini Embeddings
-        // using 'models/text-embedding-004' which is a strong, recent model
         const embedModel = new gemini_embedding_1.GeminiEmbedding();
         const llm = new mock_llm_1.MockLLM();
         const serviceContext = (0, llamaindex_1.serviceContextFromDefaults)({
@@ -109,13 +129,13 @@ async function main() {
         // 3. Create the Storage Context
         let storageContext;
         if (isInit) {
-            console.log(chalk_1.default.blue("✨ Initializing fresh Local Brain..."));
+            logger_1.Logger.info(chalk_1.default.blue("✨ Initializing fresh Local Brain..."));
             storageContext = await (0, llamaindex_1.storageContextFromDefaults)({});
         }
         else {
             // Try to load
             if (!fs.existsSync(STORAGE_DIR)) {
-                console.log(chalk_1.default.yellow("⚠️  Storage not found. Running fresh init..."));
+                logger_1.Logger.warn("⚠️  Storage not found. Running fresh init...");
                 storageContext = await (0, llamaindex_1.storageContextFromDefaults)({});
             }
             else {
@@ -125,12 +145,11 @@ async function main() {
             }
         }
         // 4. Generate the Index
-        const index = await llamaindex_1.VectorStoreIndex.fromDocuments(documents, {
+        const index = await llamaindex_1.VectorStoreIndex.fromDocuments(filteredDocuments, {
             storageContext,
             serviceContext,
         });
         // 4. Persist (Save the Brain)
-        // Manual persistence for LlamaIndex TS compatibility
         const ctxToPersist = index.storageContext;
         if (ctxToPersist.docStore)
             await ctxToPersist.docStore.persist(path.join(STORAGE_DIR, "doc_store.json"));
@@ -140,17 +159,17 @@ async function main() {
             await ctxToPersist.indexStore.persist(path.join(STORAGE_DIR, "index_store.json"));
         if (ctxToPersist.propStore)
             await ctxToPersist.propStore.persist(path.join(STORAGE_DIR, "property_store.json"));
-        console.log(chalk_1.default.green("✅ Indexing Complete. Brain is updated."));
+        logger_1.Logger.success("✅ Indexing Complete. Brain is updated.");
         if (isWatch) {
-            console.log(chalk_1.default.blue("👀 Watch mode enabled."));
+            logger_1.Logger.info(chalk_1.default.blue("👀 Watch mode enabled."));
         }
     }
     catch (e) {
-        console.error(chalk_1.default.red("❌ Indexing Failed:"), e.message);
+        logger_1.Logger.error("❌ Indexing Failed: " + e.message);
         if (e.message.includes("API") || e.message.includes("key")) {
-            console.log(chalk_1.default.yellow("👉 Tip: Make sure you have GEMINI_API_KEY in your .env.local file."));
+            logger_1.Logger.warn("👉 Tip: Make sure you have GEMINI_API_KEY in your .env.local file.");
         }
         process.exit(1);
     }
 }
-main().catch(console.error);
+main().catch(err => logger_1.Logger.error(err));

package/dist/scripts/session.js

@@ -52,8 +52,8 @@ async function startInteractiveSession(findings, index) {
     if (interactiveFindings.length === 0 || interactiveFindings.every(f => f.issues.length === 0)) {
         return { updatedFindings: interactiveFindings, hasUpdates: false };
     }
-    console.log(chalk_1.default.bold.magenta("\n🗣️  Interactive Review Session"));
-    console.log(chalk_1.default.dim("   Use arrow keys to navigate. Select an issue to debate."));
+    logger_1.Logger.info(chalk_1.default.bold.magenta("\n🗣️  Interactive Review Session"));
+    logger_1.Logger.dim("   Use arrow keys to navigate. Select an issue to debate.");
     while (active) {
         // Re-calculate choices every loop to reflect status changes
         // Flatten
@@ -92,33 +92,33 @@ async function startInteractiveSession(findings, index) {
         const selected = flatIssues[selectedIdx];
         const { issue, file } = selected;
         // Show Details
-        console.log(chalk_1.default.cyan(`\nTitle: ${issue.title}`));
-        console.log(chalk_1.default.white(issue.description));
-        console.log(chalk_1.default.dim(`File: ${file}`));
+        logger_1.Logger.info(chalk_1.default.cyan(`\nTitle: ${issue.title}`));
+        logger_1.Logger.info(chalk_1.default.white(issue.description));
+        logger_1.Logger.dim(`File: ${file}`);
         if (issue.confidenceScore)
-            console.log(chalk_1.default.yellow(`Confidence: ${issue.confidenceScore}/5`));
+            logger_1.Logger.info(chalk_1.default.yellow(`Confidence: ${issue.confidenceScore}/5`));
         if (issue.status)
-            console.log(chalk_1.default.green(`Status: ${issue.status}`));
+            logger_1.Logger.success(`Status: ${issue.status}`);
         // Action Menu
         const action = await (0, interaction_1.showActionMenu)(issue.title);
         if (action === 'discuss') {
             const argument = await (0, interaction_1.askForArgument)();
             const result = await (0, debate_1.debateIssue)(issue.title, issue.description, file, argument, index);
-            console.log(chalk_1.default.yellow(`\n🤖 Bot: ${result.text}`));
+            logger_1.Logger.info(chalk_1.default.yellow(`\n🤖 Bot: ${result.text}`));
             if (result.severity === 'LGTM') {
-                console.log(chalk_1.default.green("✅ Issue withdrawn by AI!"));
+                logger_1.Logger.success("✅ Issue withdrawn by AI!");
                 // Direct update to our state
                 interactiveFindings[selected.fileIndex].issues[selected.issueIndex].status = 'resolved';
                 hasUpdates = true;
             }
         }
         else if (action === 'ignore') {
-            console.log(chalk_1.default.dim('Issue ignored locally.'));
+            logger_1.Logger.dim('Issue ignored locally.');
             interactiveFindings[selected.fileIndex].issues[selected.issueIndex].status = 'ignored';
             hasUpdates = true;
         }
         else if (action === 'accept') {
-            console.log(chalk_1.default.green('Issue accepted.'));
+            logger_1.Logger.success('Issue accepted.');
         }
         else if (action === 'exit') {
             active = false;

package/package.json

@@ -1,10 +1,19 @@
 {
   "name": "jstar-reviewer",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "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",
@@ -56,13 +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",
-    "chat": "ts-node scripts/chat.ts",
-    "detect": "ts-node scripts/detective.ts"
   }
 }

package/scripts/chat.ts

@@ -27,7 +27,11 @@ async function loadSession(): Promise<SessionState | null> {
         return JSON.parse(content);
     } catch (e: any) {
         if (e.code === 'ENOENT') {
-            return null; // File doesn't exist
+            return null; // File doesn't exist, start fresh
+        }
+        if (e instanceof SyntaxError) {
+            Logger.warn(chalk.yellow("⚠️  Session file corrupted. Starting fresh."));
+            return null;
         }
         Logger.error(`Failed to load session: ${e.message}`);
         return null;

package/scripts/core/debate.ts

@@ -2,6 +2,7 @@ import { VectorStoreIndex, MetadataMode } from "llamaindex";
 import { generateText } from "ai";
 import { createGroq } from "@ai-sdk/groq";
 import { Config } from "../config";
+import { Logger } from "../utils/logger";
 import chalk from "chalk";
 
 const groq = createGroq({ apiKey: process.env.GROQ_API_KEY });
@@ -24,7 +25,7 @@ export async function debateIssue(
         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)"));
+    Logger.dim("   🧠  Thinking... (Consulting the Brain)");
 
     // 1. Extract keywords/context
     const query = `${userArgument} ${issueTitle}`;
@@ -35,12 +36,12 @@ export async function debateIssue(
     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"));
+        Logger.warn("   ⚠️  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}`));
+        Logger.dim(`   🔍  Found relevant context from: ${sources}`);
     }
 
     // 3. Ask the Judge

package/scripts/detective.ts

@@ -17,6 +17,7 @@ interface Rule {
     message: string;
     pattern: RegExp;
     filePattern?: RegExp; // Only check files matching this pattern
+    excludePattern?: RegExp; // Exclude files matching this pattern
 }
 
 const RULES: Rule[] = [
@@ -30,7 +31,8 @@ const RULES: Rule[] = [
         id: 'ARCH-001',
         severity: 'medium',
         message: 'Avoid using console.log in production code',
-        pattern: /console\.log\(/
+        pattern: /console\.log\(/,
+        excludePattern: /(bin[\\/]jstar\.js|scripts[\\/]utils[\\/]logger\.ts|setup\.js|test[\\/])/
     },
 ];
 
@@ -39,16 +41,20 @@ const FILE_RULES: Rule[] = [
     {
         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?$/
+        message: 'Next.js "use client" must be at the very top of the file (before imports)',
+        pattern: /^(?!(?:\s*|(?:\/\/[^\n]*\n)|(?:\/\*[\s\S]*?\*\/))*['"]use client['"]).*['"]use client['"]/s,
+        filePattern: /\.tsx?$/,
+        excludePattern: /(scripts|test)[\\/]/
     }
 ];
 
 export class Detective {
     violations: Violation[] = [];
+    private includeBuildFiles: boolean;
 
-    constructor(private directory: string) { }
+    constructor(private directory: string, options: { includeBuildFiles?: boolean } = {}) {
+        this.includeBuildFiles = options.includeBuildFiles ?? false;
+    }
 
     async scan(): Promise<Violation[]> {
         this.walk(this.directory);
@@ -63,9 +69,12 @@ export class Detective {
             const stat = fs.statSync(filePath);
 
             if (stat.isDirectory()) {
-                if (file !== 'node_modules' && file !== '.git' && file !== '.jstar') {
-                    this.walk(filePath);
+                // Ignore common build/config directories
+                const ignoredDirs = ['node_modules', '.git', '.jstar', 'dist', 'coverage', '.next'];
+                if (!this.includeBuildFiles && ignoredDirs.includes(file)) {
+                    continue;
                 }
+                this.walk(filePath);
             } else {
                 this.checkFile(filePath);
             }
@@ -74,6 +83,8 @@ export class Detective {
 
     private checkFile(filePath: string) {
         if (!filePath.match(/\.(ts|tsx|js|jsx)$/)) return;
+        // Skip .d.ts files
+        if (filePath.endsWith('.d.ts')) return;
 
         const content = fs.readFileSync(filePath, 'utf-8');
         const lines = content.split('\n');
@@ -81,6 +92,7 @@ export class Detective {
         // Line-based rules
         for (const rule of RULES) {
             if (rule.filePattern && !filePath.match(rule.filePattern)) continue;
+            if (rule.excludePattern && filePath.match(rule.excludePattern)) continue;
 
             lines.forEach((line, index) => {
                 if (rule.pattern.test(line)) {
@@ -92,6 +104,8 @@ export class Detective {
         // File-based rules
         for (const rule of FILE_RULES) {
             if (rule.filePattern && !filePath.match(rule.filePattern)) continue;
+            if (rule.excludePattern && filePath.match(rule.excludePattern)) continue;
+
             if (rule.pattern.test(content)) {
                 this.addViolation(filePath, 1, rule);
             }
@@ -132,7 +146,11 @@ export class Detective {
 
 // CLI Integration
 if (require.main === module) {
-    const detective = new Detective(path.join(process.cwd(), 'src'));
+    const args = process.argv.slice(2);
+    const includeBuildFiles = args.includes('--all');
+
+    // Scan current directory by default
+    const detective = new Detective(process.cwd(), { includeBuildFiles });
     detective.scan();
     detective.report();
 }

package/scripts/gemini-embedding.ts

@@ -1,4 +1,5 @@
 import { GoogleGenerativeAI } from "@google/generative-ai";
+import { Logger } from "./utils/logger";
 
 export class GeminiEmbedding {
     private genAI: GoogleGenerativeAI;
@@ -26,7 +27,7 @@ export class GeminiEmbedding {
                 if (e.message.includes("fetch failed") || e.message.includes("network")) {
                     retries++;
                     const waitTime = Math.pow(2, retries) * 1000;
-                    console.warn(`⚠️ Network error. Retrying in ${waitTime / 1000}s... (${retries}/${maxRetries})`);
+                    Logger.warn(`⚠️ Network error. Retrying in ${waitTime / 1000}s... (${retries}/${maxRetries})`);
                     await new Promise(resolve => setTimeout(resolve, waitTime));
                 } else {
                     throw e;
@@ -42,7 +43,7 @@ export class GeminiEmbedding {
 
     async getTextEmbeddings(texts: string[]): Promise<number[][]> {
         const embeddings: number[][] = [];
-        console.log(`Creating embeddings for ${texts.length} chunks (Batching to avoid rate limits)...`);
+        Logger.info(`Creating embeddings for ${texts.length} chunks (Batching to avoid rate limits)...`);
 
         // Process in smaller batches with delay
         const BATCH_SIZE = 1; // Strict serial for safety on free tier
@@ -60,15 +61,15 @@ export class GeminiEmbedding {
                         success = true;
                         // Standard delay between calls
                         await new Promise(resolve => setTimeout(resolve, DELAY_MS));
-                        process.stdout.write("."); // Progress indicator
+                        Logger.inline("."); // Progress indicator
                     } catch (e: any) {
                         if (e.message.includes("429") || e.message.includes("quota")) {
                             retries++;
                             const waitTime = Math.pow(2, retries) * 2000; // 2s, 4s, 8s, 16s...
-                            console.warn(`\n⚠️  Rate limit hit. Retrying in ${waitTime / 1000}s...`);
+                            Logger.warn(`\n⚠️  Rate limit hit. Retrying in ${waitTime / 1000}s...`);
                             await new Promise(resolve => setTimeout(resolve, waitTime));
                         } else {
-                            console.error("\n❌ Embedding failed irreversibly:", e.message);
+                            Logger.error("\n❌ Embedding failed irreversibly: " + e.message);
                             throw e;
                         }
                     }
@@ -78,7 +79,7 @@ export class GeminiEmbedding {
                 }
             }
         }
-        console.log("\n✅ Done embedding.");
+        Logger.success("\n✅ Done embedding.");
         return embeddings;
     }
 

package/scripts/indexer.ts

@@ -9,6 +9,7 @@ import { MockLLM } from "./mock-llm";
 import * as path from "path";
 import * as fs from "fs";
 import chalk from "chalk";
+import { Logger } from "./utils/logger";
 // IMPORTANT: Import config for side effects (loads dotenv from cwd)
 import "./config";
 
@@ -27,7 +28,7 @@ function getSourceDir(): string {
         if (fs.existsSync(customPath)) {
             return customPath;
         }
-        console.error(chalk.red(`❌ Custom path not found: ${customPath}`));
+        Logger.error(`❌ Custom path not found: ${customPath}`);
         process.exit(1);
     }
 
@@ -49,11 +50,13 @@ function getSourceDir(): string {
 }
 
 async function main() {
+    Logger.init(); // Initialize Logger (auto-detects modes)
+
     // 0. Environment Validation
     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"));
+        Logger.error("❌ Missing GEMINI_API_KEY (or GOOGLE_API_KEY)!");
+        Logger.warn("\nPlease ensure you have a .env.local file. Check .env.example for a template.\n");
         process.exit(1);
     }
 
@@ -61,25 +64,48 @@ async function main() {
     const isWatch = args.includes("--watch");
     const SOURCE_DIR = getSourceDir();
 
-    console.log(chalk.blue("🧠 J-Star Indexer: Scanning codebase..."));
-    console.log(chalk.dim(`   Source: ${SOURCE_DIR}`));
+    Logger.info(chalk.blue("🧠 J-Star Indexer: Scanning codebase..."));
+    Logger.dim(`   Source: ${SOURCE_DIR}`);
 
     // 1. Load documents (Your Code)
     if (!fs.existsSync(SOURCE_DIR)) {
-        console.error(chalk.red(`❌ Source directory not found: ${SOURCE_DIR}`));
+        Logger.error(`❌ Source directory not found: ${SOURCE_DIR}`);
         process.exit(1);
     }
 
     const reader = new SimpleDirectoryReader();
     const documents = await reader.loadData({ directoryPath: SOURCE_DIR });
 
-    console.log(chalk.yellow(`📄 Found ${documents.length} files to index.`));
+    // --- SECURITY FILTER ---
+    // Exclude sensitive files (like .env) and build artifacts
+    const EXCLUDED_PATTERNS = [
+        /pnpm-lock\.yaml/,
+        /package-lock\.json/,
+        /yarn\.lock/,
+        /\.env/,
+        /\.DS_Store/,
+        /node_modules/,
+        /\.git/,
+        /\.jstar/,
+        /\.json$/, // Prefer code over JSON data for context unless docs
+    ];
+
+    const filteredDocuments = documents.filter(doc => {
+        const filePath = (doc.metadata as any)?.file_path || (doc as any).id_ || '';
+
+        // Check strict exclusions
+        const isExcluded = EXCLUDED_PATTERNS.some(pattern => pattern.test(filePath));
+
+        return !isExcluded;
+    });
+
+    Logger.info(chalk.yellow(`📄 Found ${documents.length} files. Indexing ${filteredDocuments.length} valid files (filtered ${documents.length - filteredDocuments.length} excluded).`));
+
 
     const isInit = args.includes("--init");
 
     try {
         // 2. Setup Service Context with Google Gemini Embeddings
-        // using 'models/text-embedding-004' which is a strong, recent model
         const embedModel = new GeminiEmbedding();
         const llm = new MockLLM();
         const serviceContext = serviceContextFromDefaults({
@@ -90,12 +116,12 @@ async function main() {
         // 3. Create the Storage Context
         let storageContext;
         if (isInit) {
-            console.log(chalk.blue("✨ Initializing fresh Local Brain..."));
+            Logger.info(chalk.blue("✨ Initializing fresh Local Brain..."));
             storageContext = await storageContextFromDefaults({});
         } else {
             // Try to load
             if (!fs.existsSync(STORAGE_DIR)) {
-                console.log(chalk.yellow("⚠️  Storage not found. Running fresh init..."));
+                Logger.warn("⚠️  Storage not found. Running fresh init...");
                 storageContext = await storageContextFromDefaults({});
             } else {
                 storageContext = await storageContextFromDefaults({
@@ -105,32 +131,31 @@ async function main() {
         }
 
         // 4. Generate the Index
-        const index = await VectorStoreIndex.fromDocuments(documents, {
+        const index = await VectorStoreIndex.fromDocuments(filteredDocuments, {
             storageContext,
             serviceContext,
         });
 
         // 4. Persist (Save the Brain)
-        // Manual persistence for LlamaIndex TS compatibility
         const ctxToPersist: any = index.storageContext;
         if (ctxToPersist.docStore) await ctxToPersist.docStore.persist(path.join(STORAGE_DIR, "doc_store.json"));
         if (ctxToPersist.vectorStore) await ctxToPersist.vectorStore.persist(path.join(STORAGE_DIR, "vector_store.json"));
         if (ctxToPersist.indexStore) await ctxToPersist.indexStore.persist(path.join(STORAGE_DIR, "index_store.json"));
         if (ctxToPersist.propStore) await ctxToPersist.propStore.persist(path.join(STORAGE_DIR, "property_store.json"));
 
-        console.log(chalk.green("✅ Indexing Complete. Brain is updated."));
+        Logger.success("✅ Indexing Complete. Brain is updated.");
 
         if (isWatch) {
-            console.log(chalk.blue("👀 Watch mode enabled."));
+            Logger.info(chalk.blue("👀 Watch mode enabled."));
         }
 
     } catch (e: any) {
-        console.error(chalk.red("❌ Indexing Failed:"), e.message);
+        Logger.error("❌ Indexing Failed: " + e.message);
         if (e.message.includes("API") || e.message.includes("key")) {
-            console.log(chalk.yellow("👉 Tip: Make sure you have GEMINI_API_KEY in your .env.local file."));
+            Logger.warn("👉 Tip: Make sure you have GEMINI_API_KEY in your .env.local file.");
         }
         process.exit(1);
     }
 }
 
-main().catch(console.error);
+main().catch(err => Logger.error(err));

package/scripts/mock-llm.ts

@@ -8,11 +8,11 @@ export class MockLLM {
         tokenizer: undefined,
     };
 
-    async chat(messages: any[], parentEvent?: any): Promise<any> {
+    async chat(messages: { content: string, role: string }[], parentEvent?: any): Promise<{ message: { content: string } }> {
         return { message: { content: "Mock response" } };
     }
 
-    async complete(prompt: string, parentEvent?: any): Promise<any> {
+    async complete(prompt: string, parentEvent?: any): Promise<{ text: string }> {
         return { text: "Mock response" };
     }
 }

package/scripts/session.ts

@@ -21,8 +21,8 @@ export async function startInteractiveSession(
         return { updatedFindings: interactiveFindings, hasUpdates: false };
     }
 
-    console.log(chalk.bold.magenta("\n🗣️  Interactive Review Session"));
-    console.log(chalk.dim("   Use arrow keys to navigate. Select an issue to debate."));
+    Logger.info(chalk.bold.magenta("\n🗣️  Interactive Review Session"));
+    Logger.dim("   Use arrow keys to navigate. Select an issue to debate.");
 
     while (active) {
         // Re-calculate choices every loop to reflect status changes
@@ -74,11 +74,11 @@ export async function startInteractiveSession(
         const { issue, file } = selected;
 
         // Show Details
-        console.log(chalk.cyan(`\nTitle: ${issue.title}`));
-        console.log(chalk.white(issue.description));
-        console.log(chalk.dim(`File: ${file}`));
-        if (issue.confidenceScore) console.log(chalk.yellow(`Confidence: ${issue.confidenceScore}/5`));
-        if (issue.status) console.log(chalk.green(`Status: ${issue.status}`));
+        Logger.info(chalk.cyan(`\nTitle: ${issue.title}`));
+        Logger.info(chalk.white(issue.description));
+        Logger.dim(`File: ${file}`);
+        if (issue.confidenceScore) Logger.info(chalk.yellow(`Confidence: ${issue.confidenceScore}/5`));
+        if (issue.status) Logger.success(`Status: ${issue.status}`);
 
         // Action Menu
         const action = await showActionMenu(issue.title);
@@ -93,21 +93,21 @@ export async function startInteractiveSession(
                 index
             );
 
-            console.log(chalk.yellow(`\n🤖 Bot: ${result.text}`));
+            Logger.info(chalk.yellow(`\n🤖 Bot: ${result.text}`));
 
             if (result.severity === 'LGTM') {
-                console.log(chalk.green("✅ Issue withdrawn by AI!"));
+                Logger.success("✅ Issue withdrawn by AI!");
                 // Direct update to our state
                 interactiveFindings[selected.fileIndex].issues[selected.issueIndex].status = 'resolved';
                 hasUpdates = true;
             }
 
         } else if (action === 'ignore') {
-            console.log(chalk.dim('Issue ignored locally.'));
+            Logger.dim('Issue ignored locally.');
             interactiveFindings[selected.fileIndex].issues[selected.issueIndex].status = 'ignored';
             hasUpdates = true;
         } else if (action === 'accept') {
-            console.log(chalk.green('Issue accepted.'));
+            Logger.success('Issue accepted.');
         } else if (action === 'exit') {
             active = false;
         }