jstar-reviewer 2.4.3 → 3.0.0

package/README.md

@@ -1,150 +1,49 @@
-# 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.  **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 `GEMINI_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)**.
-
-
----
-
-```
-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
-GEMINI_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
+# J-Star Code Reviewer
+
+Local-first, context-aware code review with a deterministic security audit layer.
+
+## What it does
+
+- Builds a local vector index for repo-aware reviews
+- Runs hybrid reviews with deterministic checks plus LLM analysis
+- Produces machine-readable review output for automation
+- Runs a standalone deterministic security audit with markdown and JSON reports
+
+## Quick start
+
+```bash
+pnpm install
+pnpm run index:init
+git add .
+pnpm run review
+pnpm run audit
+```
+
+Review output:
+- `.jstar/last-review.md`
+- `.jstar/session.json`
+
+Audit output:
+- `.jstar/audit_report.md`
+- `.jstar/audit_report.json`
+
+## CLI
+
+```bash
+jstar setup
+jstar init
+jstar review
+jstar review --pr
+jstar audit
+jstar audit --path src
+jstar audit --json
+jstar chat --headless
+```
+
+## Notes
+
+- `review` requires `GEMINI_API_KEY` and `GROQ_API_KEY`
+- `audit` and `detect` do not require model keys
+- deterministic audit ignores live in `.jstar/audit-ignore.json`
+
+See [ONBOARDING.md](./ONBOARDING.md) and [docs/features/cli-commands.md](./docs/features/cli-commands.md) for details.

package/bin/jstar.js

@@ -29,7 +29,7 @@ function log(msg) {
 
 function printHelp() {
     log(`
-${COLORS.bold}🌟 J-Star Reviewer v2.4.3${COLORS.reset}
+${COLORS.bold}🌟 J-Star Reviewer v3.0.0${COLORS.reset}
 
 ${COLORS.dim}AI-powered code review with local embeddings${COLORS.reset}
 
@@ -39,6 +39,7 @@ ${COLORS.bold}USAGE:${COLORS.reset}
 ${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}audit${COLORS.reset}     Run deterministic security audit checks
   ${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
@@ -47,6 +48,7 @@ ${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.yellow}--all${COLORS.reset}       Scan all files (including build artifacts like .next) in 'detect' mode
+  ${COLORS.yellow}--full${COLORS.reset}      For 'audit', scan the full workspace (default)
 
 ${COLORS.bold}REVIEW OPTIONS:${COLORS.reset}
   ${COLORS.yellow}--pr${COLORS.reset}        Review a Pull Request (compare against main/base)
@@ -62,6 +64,9 @@ ${COLORS.bold}EXAMPLES:${COLORS.reset}
   ${COLORS.dim}# Review staged changes (default)${COLORS.reset}
   jstar review
 
+  ${COLORS.dim}# Run a full deterministic security audit${COLORS.reset}
+  jstar audit
+
   ${COLORS.dim}# Review a Pull Request${COLORS.reset}
   jstar review --pr
   jstar review --pr --base develop
@@ -157,11 +162,12 @@ function runScript(scriptName) {
     });
 }
 
-const REQUIRED_ENV_VARS = {
-    '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'
-};
+const REQUIRED_ENV_VARS = {
+    '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',
+    'GEMINI_EMBEDDING_MODEL': '# Optional: Override the embedding model\n# GEMINI_EMBEDDING_MODEL=gemini-embedding-001',
+    'REVIEW_MODEL_NAME': '# Optional: Override the default model\n# REVIEW_MODEL_NAME=moonshotai/kimi-k2-instruct-0905'
+};
 
 function createSetupFiles() {
     const cwd = process.cwd();
@@ -237,6 +243,9 @@ switch (command) {
     case 'review':
         runScript('reviewer.ts');
         break;
+    case 'audit':
+        runScript('audit.ts');
+        break;
     case 'chat':
         runScript('chat.ts');
         break;

package/dist/scripts/audit-report.js

@@ -0,0 +1,70 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.renderAuditReport = renderAuditReport;
+const SEVERITY_EMOJI = {
+    CRITICAL: "🛑",
+    HIGH: "⚠️",
+    WARNING: "📝",
+    INFO: "ℹ️",
+};
+function renderFindingRow(finding) {
+    const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+    return `| ${SEVERITY_EMOJI[finding.severity]} ${finding.severity} | ${finding.category} | \`${location}\` | **${finding.ruleId}** ${finding.title}<br>${finding.message} | ${finding.recommendation} |`;
+}
+function renderAuditReport(report) {
+    let markdown = `# J-Star Security Audit Report
+
+**Date:** \`${report.date}\`  
+**Scope:** \`${report.mode}\`  
+**Target:** \`${report.target}\`  
+**Ruleset:** \`${report.rulesVersion}\`
+
+---
+
+## Summary
+
+| Metric | Value |
+| --- | --- |
+| Files scanned | ${report.summary.filesScanned} |
+| Active findings | ${report.summary.findings} |
+| Critical | ${report.summary.critical} |
+| High | ${report.summary.high} |
+| Warning | ${report.summary.warning} |
+| Info | ${report.summary.info} |
+| Ignored | ${report.summary.ignored} |
+
+> ${report.recommendedAction}
+
+---
+
+## Findings
+
+`;
+    if (report.findings.length === 0) {
+        markdown += "No deterministic security findings detected.\n";
+    }
+    else {
+        markdown += `| Severity | Category | Location | Issue | Recommendation |
+| --- | --- | --- | --- | --- |
+`;
+        report.findings.forEach((finding) => {
+            markdown += renderFindingRow(finding) + "\n";
+        });
+    }
+    if (report.ignoredFindings.length > 0) {
+        markdown += `
+
+---
+
+## Ignored Findings
+
+| Severity | Category | Location | Issue | Ignore Reason |
+| --- | --- | --- | --- | --- |
+`;
+        report.ignoredFindings.forEach((finding) => {
+            const location = finding.line ? `${finding.file}:${finding.line}` : finding.file;
+            markdown += `| ${SEVERITY_EMOJI[finding.severity]} ${finding.severity} | ${finding.category} | \`${location}\` | **${finding.ruleId}** ${finding.title} | ${finding.ignoreReason ?? "Ignored"} |\n`;
+        });
+    }
+    return markdown + "\n";
+}

package/dist/scripts/audit.js

@@ -0,0 +1,135 @@
+"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 });
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const chalk_1 = __importDefault(require("chalk"));
+const simple_git_1 = __importDefault(require("simple-git"));
+require("./config");
+const audit_report_1 = require("./audit-report");
+const deterministic_audit_1 = require("./core/deterministic-audit");
+const review_target_1 = require("./core/review-target");
+const logger_1 = require("./utils/logger");
+const MARKDOWN_OUTPUT = path.join(process.cwd(), ".jstar", "audit_report.md");
+const JSON_OUTPUT = path.join(process.cwd(), ".jstar", "audit_report.json");
+function hasDiffFlags(args) {
+    return ["--staged", "--last", "--commit", "--range", "--pr"].some((flag) => args.includes(flag));
+}
+function resolveCustomPath(args) {
+    const pathArgIndex = args.indexOf("--path");
+    if (pathArgIndex === -1 || !args[pathArgIndex + 1]) {
+        return null;
+    }
+    const resolved = path.resolve(process.cwd(), args[pathArgIndex + 1]);
+    if (!fs.existsSync(resolved)) {
+        throw new Error(`Path not found: ${resolved}`);
+    }
+    const stat = fs.statSync(resolved);
+    if (stat.isDirectory()) {
+        return {
+            target: path.relative(process.cwd(), resolved).replace(/\\/g, "/") || ".",
+            rootDir: resolved,
+        };
+    }
+    return {
+        target: path.relative(process.cwd(), resolved).replace(/\\/g, "/"),
+        filePaths: [resolved],
+    };
+}
+async function main() {
+    logger_1.Logger.init();
+    const args = process.argv.slice(2);
+    const git = (0, simple_git_1.default)();
+    const diffMode = hasDiffFlags(args) || args.includes("--staged");
+    const customPath = resolveCustomPath(args);
+    logger_1.Logger.info(chalk_1.default.blue("🔐 J-Star Security Audit: Running deterministic checks...\n"));
+    const report = diffMode
+        ? await runDiffAudit(git, args)
+        : await runFullAudit(customPath);
+    fs.mkdirSync(path.dirname(MARKDOWN_OUTPUT), { recursive: true });
+    fs.writeFileSync(MARKDOWN_OUTPUT, (0, audit_report_1.renderAuditReport)(report));
+    fs.writeFileSync(JSON_OUTPUT, JSON.stringify(report, null, 2));
+    if (logger_1.Logger.isHeadless()) {
+        logger_1.Logger.json(report);
+        return;
+    }
+    logger_1.Logger.info(chalk_1.default.bold.green("🔐 SECURITY AUDIT COMPLETE"));
+    logger_1.Logger.info(`   Scope: ${report.mode}`);
+    logger_1.Logger.info(`   Target: ${report.target}`);
+    logger_1.Logger.info(`   Files scanned: ${report.summary.filesScanned}`);
+    logger_1.Logger.info(`   Critical: ${report.summary.critical}`);
+    logger_1.Logger.info(`   High: ${report.summary.high}`);
+    logger_1.Logger.info(`   Warning: ${report.summary.warning}`);
+    logger_1.Logger.info(`   Info: ${report.summary.info}`);
+    logger_1.Logger.info(chalk_1.default.dim(`   Markdown: ${MARKDOWN_OUTPUT}`));
+    logger_1.Logger.info(chalk_1.default.dim(`   JSON: ${JSON_OUTPUT}`));
+    logger_1.Logger.info(`\n💡 ${report.recommendedAction}`);
+}
+async function runDiffAudit(git, args) {
+    const reviewTarget = await (0, review_target_1.resolveReviewTarget)(git, args);
+    if (!reviewTarget.diff) {
+        return (0, deterministic_audit_1.runDeterministicAudit)({
+            mode: "DIFF_SCAN",
+            target: reviewTarget.label,
+            filePaths: [],
+            includeRepositoryChecks: false,
+        });
+    }
+    const filePaths = (0, review_target_1.extractDiffFileNames)(reviewTarget.diff)
+        .map((filePath) => path.resolve(process.cwd(), filePath))
+        .filter((filePath) => fs.existsSync(filePath));
+    return (0, deterministic_audit_1.runDeterministicAudit)({
+        mode: "DIFF_SCAN",
+        target: reviewTarget.label,
+        filePaths,
+        includeRepositoryChecks: false,
+    });
+}
+async function runFullAudit(customPath) {
+    return (0, deterministic_audit_1.runDeterministicAudit)({
+        mode: "FULL_SCAN",
+        target: customPath?.target ?? ".",
+        rootDir: customPath?.rootDir ?? process.cwd(),
+        filePaths: customPath?.filePaths,
+        includeRepositoryChecks: true,
+    });
+}
+main().catch((error) => {
+    logger_1.Logger.error(`❌ Security audit failed: ${error.message}`);
+    process.exit(1);
+});

package/dist/scripts/config.js

@@ -44,6 +44,7 @@ const path = __importStar(require("path"));
 const REQUIRED_ENV_VARS = {
     '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',
+    'GEMINI_EMBEDDING_MODEL': '# Optional: Override the embedding model\n# GEMINI_EMBEDDING_MODEL=gemini-embedding-001',
     'REVIEW_MODEL_NAME': '# Optional: Override the default model\n# REVIEW_MODEL_NAME=moonshotai/kimi-k2-instruct-0905'
 };
 function ensureSetup() {