@djibrilm/lazy-review 0.0.2 → 0.0.3

package/README.md

@@ -1,43 +1,50 @@
 <p align="center">
-  <img src="./logo.png" width="200" alt="Lazy Review Logo">
+  <img src="https://github.com/DjibrilM/lazy-review/raw/develop/frontend/public/resources/images/logo.png" width="200" alt="Lazy Review Logo">
 </p>
 
-# Lazy Review
+# Lazy Review — PR Review Assistant
 
-A fully offline AI code reviewer. Run it once and it spins up a local Express server with a React UI — no cloud, no subscriptions, no code leaving your machine.
+A CLI tool that reviews GitHub pull requests using local AI models. Point it at a repository, select a PR, and it posts a structured review comment back to GitHub — no cloud inference, no API keys beyond GitHub OAuth.
 
-It connects to GitHub to fetch your PRs, runs a multi-agent review pipeline against your local models, and posts the review back as a GitHub comment.
+## Overview
 
-## Features
+Lazy Review fetches PR diffs from GitHub and runs them through a multi-agent pipeline on your machine. The output is a structured GitHub PR review comment with categorized findings (`approve` / `request_changes` / `comment`), severity scores, and file-level annotations.
 
-**Offline-first by design** — The entire stack runs locally. AI inference is handled by the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk), which downloads and manages open-weight models directly on your machine. A coding LLM (~5 GB RAM) handles review generation; a separate embedding model (~2 GB RAM) handles semantic search.
+It uses two models:
 
-**Multi-agent review pipeline** — A single LLM call isn't enough for a thorough review. Lazy Review orchestrates five specialized agents:
+- A coding LLM (~5 GB RAM) for review generation
+- An embedding model (~2 GB RAM) for semantic codebase search
 
-- **Change Analyzer** — reads the diff and decides which review lenses are needed (security, performance, concurrency, correctness, architecture, maintainability)
-- **Specialist Reviewer** — investigates the PR through a specific lens, forming hypotheses without reading raw files directly
-- **Repository Explorer** — a sub-agent with deterministic file tools (`read_file`, `search_symbol`, `semantic_search`) that the Reviewer delegates evidence-gathering to
-- **Finding Verifier** — acts as a red team. Before anything is reported, it actively tries to _disprove_ each finding by searching for cleanup handlers, timeouts, or lifecycle methods that would make the issue impossible
-- **Secret Scanner** — scans diff file names for sensitive candidates (`.env`, private keys, credential bundles), then reads the actual diff content to confirm before flagging anything
+Both are downloaded and managed via the [QVAC SDK](https://www.npmjs.com/package/@qvac/sdk).
 
-**Semantic codebase indexing** — When you add a repository, Lazy Review walks the source tree, extracts symbols via Tree-sitter (TypeScript, JavaScript, Python, Rust, Go), and stores embeddings in a local SQLite vector database using `sqlite-vec`. Content is chunked at safe token boundaries to fit within the embedding model's 512-token context window without truncation.
+## Review pipeline
 
-**Resilient tool-call parsing** — Local models don't always produce perfectly structured output. The agent loop includes a JSON fallback parser and a regex parser for non-standard tool-call formats (e.g., `<|tool_call|>` dialect) so the pipeline keeps running even when the model's output is messy. Tool results from fallback-parsed calls are injected as `user` messages to bypass strict API structural validation.
+A review goes through five sequential stages:
 
-**Real-time streaming** — Project creation logs and agent progress are streamed to the frontend over WebSockets via `socket.io`. Model download progress is also streamed byte-by-byte so you can see exactly what's happening.
+1. **Change Analyzer** — classifies the PR diff and selects which specialist reviewers are needed (e.g. `security`, `performance`, `concurrency`, `correctness`, `architecture`, `maintainability`)
+2. **Specialist Reviewers** — each runs a ReAct loop, forming hypotheses and querying the Repository Explorer for evidence rather than reading files directly
+3. **Repository Explorer** — a sub-agent with deterministic tools (`read_file`, `search_symbol`, `semantic_search`) that answers evidence queries from the Specialist Reviewers
+4. **Finding Verifier** — receives each candidate finding and attempts to disprove it by searching for cleanup handlers, timeouts, or lifecycle methods that would make the issue a false positive
+5. **Secret Scanner** — independently scans diff file names for sensitive candidates (`.env`, private keys, credential bundles), reads the actual diff content to confirm before reporting
 
-**Model preloading** — At startup, both models are loaded into memory in the background before any request comes in. The HTTP server starts accepting connections immediately, so if preloading finishes before the first review request, the cold-start latency disappears entirely.
+Confirmed findings are deduplicated by a hash of their text and location, ranked by `Impact × Likelihood`, and included in the final review verdict (`approve` / `request_changes` / `comment`).
 
-## How a review works
+## Codebase indexing
 
-1. You select a GitHub repository and a PR from the UI.
-2. Lazy Review fetches the PR diff and description via the GitHub API.
-3. The **Change Analyzer** classifies the change and decides which specialist agents to spawn.
-4. Each **Specialist Reviewer** forms hypotheses, then delegates evidence queries to the **Repository Explorer**, which has access to the local filesystem and the semantic index.
-5. Every candidate finding is passed to the **Finding Verifier**, which attempts to disprove it. Only confirmed findings make it through.
-6. The **Secret Scanner** runs independently, checking for leaked credentials.
-7. Surviving findings are deduplicated by a hash of their text and location, then ranked by `Impact × Likelihood`.
-8. The final structured review (`approve` / `request_changes` / `comment`) is posted as a GitHub PR comment.
+When you add a repository, Lazy Review scans the source tree and builds a local vector index. It:
+
+- Parses symbols from TypeScript, JavaScript, Python, Rust, and Go files using Tree-sitter
+- Chunks content at safe token boundaries (the embedding model has a 512-token context window)
+- Stores embeddings in SQLite using the `sqlite-vec` extension
+
+The index is used during reviews to provide semantic context to the agents.
+
+## Tool-call parsing
+
+Local models don't always return well-structured tool calls. The agent loop handles two fallback cases:
+
+- A regex parser for non-standard formats (e.g. the `<|tool_call|>` dialect used by some quantized models)
+- Tool results from fallback-parsed calls are injected as `user` messages to avoid strict API validation errors
 
 ## Tech stack
 
@@ -53,36 +60,31 @@ It connects to GitHub to fetch your PRs, runs a multi-agent review pipeline agai
 
 ## Hardware requirements
 
-Developed and tested on a Mac Mini (Apple Silicon). You need enough free RAM to hold both models simultaneously:
+Tested on a Mac Mini (Apple Silicon). You need ~7 GB of free RAM to hold both models simultaneously:
 
-| Model           | RAM            |
-| --------------- | -------------- |
-| Coding LLM      | ~5 GB          |
-| Embedding Model | ~2 GB          |
-| **Total**       | **~7 GB free** |
+| Model           | RAM   |
+| --------------- | ----- |
+| Coding LLM      | ~5 GB |
+| Embedding Model | ~2 GB |
 
-GPU inference is available and can be toggled in Settings. If you hit crashes during model initialization on an older GPU, switch to CPU inference — it's slower but stable.
+Since the models alone take up around 7 GB and other computer operations also need space, a good environment should have around 12 GB to 16 GB of total RAM.
 
-## Getting started
+GPU inference can be toggled in Settings. If the app crashes during model initialization (common on older GPUs), switch to CPU inference.
 
-### Install from npm (recommended)
+## Installation
+
+### From npm
 
 ```bash
 npm install -g @djibrilm/lazy-review
 lrv run
 ```
 
-Open `http://localhost:16500` in your browser.
-
-You can also specify a custom port:
-
-```bash
-lazy-review run --port 8080
-```
+Starts the server on `http://localhost:16500`.
 
-### Run from source
+### From source
 
-**Prerequisites:** Node.js 18+, pnpm
+Requires Node.js 18+ and pnpm.
 
 ```bash
 git clone https://github.com/djibrilm/lazy-review
@@ -91,14 +93,26 @@ pnpm install
 pnpm run dev
 ```
 
-This starts the Express backend on port `16500` and the Vite dev server concurrently.
+This starts both the Express server (port `16500`) and the Vite dev server concurrently.
+
+## CLI Commands
+
+The CLI is available as either `lazy-review` or the `lrv` shorthand.
+
+### `run`
+
+Starts the Lazy Review server.
+
+```bash
+lrv run
+```
 
-## First-time setup
+## Setup
 
-1. Go to **Settings → Local AI Models** and download both models. The download progress is shown live.
-2. Go to **Settings → GitHub Authentication** and connect your GitHub account.
-3. Add a repository from the dashboard. Lazy Review will clone it and index the codebase using Tree-sitter and local embeddings.
-4. Open any PR from the repository view and click **Run Review**.
+1. Open Settings → Local AI Models and download both models.
+2. Open Settings → GitHub Authentication and connect your GitHub account.
+3. Add a repository from the dashboard. Lazy Review will clone it and index the codebase.
+4. Select a PR from the repository view and run a review.
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "type": "module",
   "name": "@djibrilm/lazy-review",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "",
   "bin": {
     "lazy-review": "./dist/bin.js",
@@ -91,6 +91,7 @@
     "link": "pnpm run postbuild && pnpm run prod:build && pnpm link --global",
     "link-watch": "nodemon --watch dist --ext js --exec \"pnpm link --global\"",
     "lint": "eslint \"src/**/*.ts\"",
-    "format": "prettier --write \"**/*.{ts,js,json,md}\""
+    "format": "prettier --write \"**/*.{ts,js,json,md}\"",
+    "release": "pnpm run prod:build && pnpm publish --access public"
   }
 }