ira-review 1.0.1 → 1.2.0

package/README.github.md

@@ -1,213 +1,302 @@
-# IRA - AI-Powered Code Reviews for Pull Requests
+# IRA - Intelligent Review Assistant
+
+IRA reviews pull requests before your team does. It reads the full PR diff, runs each changed file through an AI model, scores the overall risk, and optionally validates the changes against JIRA acceptance criteria. The output is a set of inline comments posted directly on the PR with explanations, impact assessments, and suggested fixes.
+
+It runs as a CLI tool, a VS Code extension, or inside CI pipelines. Everything executes locally. No code or credentials leave your infrastructure.
 
 [![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/ira-review.ira-review-vscode?label=VS%20Code%20Marketplace&color=blue)](https://marketplace.visualstudio.com/items?itemName=ira-review.ira-review-vscode)
 [![npm](https://img.shields.io/npm/v/ira-review?color=red)](https://www.npmjs.com/package/ira-review)
 
-IRA (Intelligent Review Assistant) reviews your pull requests using AI. It posts inline comments with explanations, impact assessments, and suggested fixes directly on your PR.
+---
 
-**Works with any language.** Supports GitHub, GitHub Enterprise, Bitbucket Cloud, and Bitbucket Server/Data Center.
+## Why This Exists
 
-> 🆕 **Now available as a [VS Code Extension](#vs-code-extension)** - get AI code reviews right inside your editor using GitHub Copilot.
+Code review is a bottleneck in most teams. PRs sit for hours or days waiting for a human reviewer. When the review finally happens, a significant portion of the comments are mechanical: missing input validation, hardcoded secrets, unhandled edge cases, acceptance criteria not covered.
 
-## What's New in v1.0.1
+These are all things a machine can catch.
 
-- **Generate Tests** — generate test cases from JIRA acceptance criteria in the VS Code extension (Cmd+Shift+P → IRA: Generate Tests)
-- **Review Current File** — review the currently open file without needing a PR (Cmd+Shift+P → IRA: Review Current File)
-- **CLI version fix** — CLI now correctly reports 1.0.1 (was showing 0.7.0)
-- **Feature table** — updated to reflect all available features
+IRA does not replace human reviewers. It handles the first pass so that when a human does review, they can focus on architecture, design, and business logic instead of pointing out that you forgot to sanitize user input.
 
-## What can IRA do?
+The specific gap IRA fills:
+- **Linters** catch syntax and style issues. They do not understand intent.
+- **SAST tools** scan for known vulnerability patterns. They do not assess business logic.
+- **Copilot** helps you write code. It does not review code you already wrote.
+- **IRA** reviews the complete PR diff with AI, scores the risk, and validates against the actual JIRA ticket. It bridges the gap between static analysis and human judgment.
 
-- **Review your code** using AI and post inline comments with explanation, impact, and fix
-- **Score PR risk** from 0 to 100 and auto-label your PRs on GitHub
-- **Track requirement completion** against JIRA acceptance criteria with percentage and per-criterion status
-- **Generate test cases** from JIRA tickets in 8 frameworks (Jest, Vitest, Mocha, Playwright, Cypress, Gherkin, Pytest, JUnit)
-- **Enrich SonarQube issues** with AI-powered explanations when Sonar is connected
-- **Notify your team** via Slack or Microsoft Teams after each review
+---
 
-## Try it in 30 seconds
+## How It Works
 
-```bash
-npx ira-review review \
-  --pr 42 \
-  --scm-provider github \
-  --github-token 'ghp_xxxxx' \
-  --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx' \
-  --dry-run
-```
+IRA runs a 13-step pipeline for each review. Every step after step 1 is designed to soft-fail, so a partial configuration (e.g., no SonarQube, no JIRA) still produces useful output.
 
-This prints the review in your terminal. Drop `--dry-run` to post it on the PR.
+```
+1.  Fetch SonarQube issues (if configured)
+2.  Filter issues by minimum severity threshold
+3.  Detect project framework (React, Angular, Vue, NestJS, Node)
+4.  Load team review rules from .ira-rules.json (if present)
+5.  Analyze code complexity metrics (if SonarQube is connected)
+6.  Fetch PR diff from GitHub/Bitbucket
+7.  Fetch source files for changed files (for full-file context)
+8.  Run AI review on each file/issue (concurrent, configurable model)
+9.  Calculate risk score (0-100) from issue severity, complexity, and security signals
+10. Validate JIRA acceptance criteria against the diff (if configured)
+11. Deduplicate: skip issues already commented on in previous runs
+12. Post summary + inline comments to the PR
+13. Send Slack/Teams notification (if configured, respects risk threshold)
+```
 
-## Install
+Two review modes:
+- **Sonar + AI mode**: SonarQube finds issues, AI explains each one with context, impact, and a fix
+- **Standalone AI mode**: AI reviews the raw diff directly and identifies issues on its own
+
+Both modes produce the same output format: inline comments on specific lines with severity, explanation, impact, and suggested fix.
+
+---
+
+## Architecture
+
+```mermaid
+flowchart LR
+    subgraph Input
+        SCM[GitHub / Bitbucket]
+        Sonar[SonarQube]
+        JIRA[JIRA]
+        RulesFile[".ira-rules.json"]
+    end
+
+    subgraph Core["Review Engine"]
+        Diff[Fetch PR Diff]
+        Issues[Fetch Sonar Issues]
+        Rules[Team Rules]
+        AI[AI Review]
+        Risk[Risk Scorer]
+        AC[AC Validator]
+        Dedup[Deduplicator]
+    end
+
+    subgraph Output
+        Comments[Inline PR Comments]
+        Labels[Risk Labels]
+        Notify[Slack / Teams]
+    end
+
+    SCM --> Diff
+    Sonar --> Issues
+    Diff --> AI
+    Issues --> AI
+    RulesFile --> Rules
+    Rules --> AI
+    AI --> Risk
+    JIRA --> AC
+    Diff --> AC
+    Risk --> Dedup
+    AC --> Comments
+    Dedup --> Comments
+    Risk --> Labels
+    Risk --> Notify
+```
 
-```bash
-npx ira-review review --help            # no install needed
-npm install -g ira-review                # or install globally
-npm install --save-dev ira-review        # or add to your project
+```
+src/
+  ai/           AI provider abstraction (OpenAI, Anthropic, Azure, Ollama)
+  core/         Review engine, risk scorer, acceptance validator, test generator
+  scm/          GitHub and Bitbucket clients (diff, comments, labels, build status)
+  integrations/ JIRA client, Slack/Teams notifier
+  frameworks/   Framework detector (React, Angular, Vue, NestJS, Node)
+  types/        Shared TypeScript interfaces
+  utils/        Config resolution, concurrency helpers
+  cli.ts        CLI entry point (Commander.js)
+
+packages/
+  vscode/       VS Code extension (diagnostics, CodeLens, TreeView, dashboard)
 ```
 
-## How to use IRA
+The core review engine (`src/core/reviewEngine.ts`) is a single orchestrator that wires together all components. The VS Code extension and CLI both call the same engine, so behavior is identical across surfaces.
 
-Pick the combination that fits your workflow. Each example builds on the previous one.
+---
 
-### 1. AI-only review
+## Key Features
 
-The simplest setup. IRA reads your PR diff and finds bugs, security issues, and performance problems.
+### Risk Scoring (0-100)
 
-**GitHub:**
-```bash
-npx ira-review review \
-  --pr 42 \
-  --scm-provider github \
-  --github-token 'ghp_xxxxx' \
-  --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx'
-```
+Every review produces a composite risk score based on:
+- Number and severity of blocker/critical/major issues
+- Security-related findings (SQL injection, hardcoded secrets, auth bypasses)
+- Code complexity metrics (when SonarQube is connected)
 
-**Bitbucket Cloud:**
-```bash
-npx ira-review review \
-  --pr 42 \
-  --bitbucket-token 'bb_xxxxx' \
-  --repo my-workspace/my-repo \
-  --ai-api-key 'sk-xxxxx'
+The score maps to a level: LOW (0-19), MEDIUM (20-39), HIGH (40-59), CRITICAL (60-100). On GitHub, IRA applies color-coded labels (`ira:critical`, `ira:high`, etc.) to the PR. On Bitbucket, it posts a build status.
+
+### JIRA Acceptance Criteria Validation
+
+IRA fetches the linked JIRA ticket, extracts the acceptance criteria, and uses the AI model to determine which criteria the PR diff covers and which it does not. The output includes:
+- Per-criterion pass/fail status with coverage percentage
+- Edge cases the AC implies but the code does not handle
+- A summary posted as a PR comment
+
+This is the feature that catches "does this actually match the ticket?" before a human has to ask.
+
+### Inline AI Comments
+
+Each issue is posted as an inline comment on the exact line in the PR, containing:
+- **Rule**: Category (e.g., `IRA/security`, `IRA/best-practice`)
+- **Severity**: BLOCKER, CRITICAL, MAJOR, MINOR, INFO
+- **Explanation**: What the problem is
+- **Impact**: What happens if it is not fixed
+- **Suggested Fix**: Code-level recommendation
+
+### Comment Deduplication
+
+IRA tracks which comments it has already posted on a PR. Re-running a review on the same PR will only post new findings, not duplicate previous ones.
+
+### Test Case Generation
+
+Given a JIRA ticket, IRA generates test cases from the acceptance criteria in your chosen framework. Supported: Jest, Vitest, Mocha, Playwright, Cypress, Gherkin, Pytest, JUnit.
+
+### Smart Notifications
+
+Slack and Teams notifications can be filtered by risk threshold and AC failure status. You control exactly when your team gets notified.
+
+### Custom Review Rules
+
+Teams define their own review standards in a `.ira-rules.json` file committed to the repo root. Rules are loaded at review time and injected into the AI prompt alongside the diff, so the model checks for team-specific violations in the same pass as general issues. No separate analysis pass, no extra API calls.
+
+Each rule has a `message` (what to tell the developer), a `severity` (BLOCKER, CRITICAL, MAJOR, MINOR), and optionally `bad`/`good` code examples and `paths` to scope the rule to specific directories.
+
+```json
+{
+  "rules": [
+    {
+      "message": "Use parameterized queries for all SQL operations",
+      "bad": "db.query(`SELECT * FROM users WHERE id = ${userId}`)",
+      "good": "db.query('SELECT * FROM users WHERE id = $1', [userId])",
+      "severity": "CRITICAL",
+      "paths": ["src/db/**", "src/api/**"]
+    },
+    {
+      "message": "Never use console.log in production code, use the logger service",
+      "bad": "console.log('User created:', user);",
+      "good": "logger.info('User created', { userId: user.id });",
+      "severity": "MINOR"
+    }
+  ]
+}
 ```
 
-### 2. Review with JIRA (requirement tracking + AC validation)
+Rules without `paths` apply to all files. Rules with `paths` are only checked against matching files. The file is validated at load time: invalid severity values and missing required fields are skipped with a warning. Maximum 30 rules per file. IRA rules are for nuanced, context-dependent standards that linters cannot express. Deterministic checks (naming conventions, import order, formatting) belong in ESLint.
 
-Connect a JIRA ticket and IRA will tell you how much of the acceptance criteria is actually implemented, with per-criterion pass/fail and edge case warnings.
+Rules are enforced in all review surfaces (CLI, CI/CD, VS Code extension) with no license gating. In the VS Code extension, run `IRA: Init Rules File` from the command palette to scaffold an empty `.ira-rules.json`. The extension ships a JSON Schema for the file, so you get autocomplete and validation as you edit.
 
-```bash
-npx ira-review review \
-  --pr 42 \
-  --scm-provider github \
-  --github-token 'ghp_xxxxx' \
-  --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx' \
-  --jira-url https://yourcompany.atlassian.net \
-  --jira-email you@company.com \
-  --jira-token 'jira_xxxxx' \
-  --jira-ticket AUTH-234
+---
+
+## Privacy and Local-First Design
+
+IRA is not a SaaS product. There is no hosted service, no telemetry, no analytics, and no token forwarding.
+
+| Surface | How secrets are stored |
+|---|---|
+| VS Code Extension | OS keychain via SecretStorage (macOS Keychain, Windows Credential Manager, Linux libsecret) |
+| CLI | Environment variables, read at runtime, never written to disk |
+| CI Pipelines | Your CI secrets manager (GitHub Actions secrets, Jenkins credentials, etc.) |
+
+- GitHub auth uses VS Code's built-in OAuth (same mechanism as Copilot)
+- Config files (`.irarc.json`) block token fields by design
+- AI API calls go directly from your machine to your chosen provider. IRA is not a proxy
+- The authentication module is a single file with full test coverage
+
+---
+
+## CLI vs VS Code Extension
+
+| | CLI | VS Code Extension |
+|---|---|---|
+| **Use case** | CI pipelines, scripting, headless environments | Interactive development |
+| **AI default** | OpenAI (requires API key) | GitHub Copilot (zero config) |
+| **Auth** | Environment variables or CLI flags | VS Code OAuth + OS keychain |
+| **Output** | Terminal + PR comments | Inline diagnostics, CodeLens, TreeView, risk badge |
+| **JIRA/Sonar** | CLI flags or env vars | VS Code settings |
+| **Pro features** | Not applicable | Auto-review on save, one-click fix, history/trends |
+
+Both surfaces use the same core review engine. The review logic, risk scoring, and AI prompts are identical.
+
+---
+
+## Example Output
+
+**Risk summary posted on the PR:**
+
+```
+# IRA Review Summary
+
+## Risk: MEDIUM (47/100)
+
+| Factor        | Score | Detail                          |
+|---------------|-------|---------------------------------|
+| Blocker Issues| 10/30 | 1 blocker issue found           |
+| Critical Issues| 8/25 | 1 critical issue found         |
+| Major Issues  | 5/15  | 1 major issue found             |
+| Security      | 14/20 | 2 security-related issues       |
+| Complexity    | 0/10  | 0 high-complexity files         |
 ```
 
-Example output posted on your PR:
+**JIRA acceptance criteria validation:**
 
 ```
-📊 Requirements: AUTH-234 - 67% Complete (4/6 AC met)
+Requirements: AUTH-234 - 67% Complete (4/6 AC met)
 
-  ✅ OAuth2 login flow implemented with Google provider
-  ✅ JWT tokens generated on successful authentication
-  ✅ Refresh token rotation with 7-day expiry
-  ❌ Input validation on login endpoint - no email format check
-  ✅ Logout endpoint clears session and revokes token
-  ❌ Rate limiting on login attempts - not implemented
+  [PASS] OAuth2 login flow implemented with Google provider
+  [PASS] JWT tokens generated on successful authentication
+  [PASS] Refresh token rotation with 7-day expiry
+  [FAIL] Input validation on login endpoint - no email format check
+  [PASS] Logout endpoint clears session and revokes token
+  [FAIL] Rate limiting on login attempts - not implemented
 
-  ⚠️ Edge Cases Not Covered:
+  Edge Cases Not Covered:
      - What happens when Google OAuth is unreachable?
      - Token refresh during concurrent requests?
 ```
 
-### 3. Review with JIRA + test generation
+**Inline comment on the PR:**
 
-Add `--generate-tests` to any review command and IRA will generate test scaffolding alongside the code review.
-
-```bash
-npx ira-review review \
-  --pr 42 \
-  --scm-provider github \
-  --github-token 'ghp_xxxxx' \
-  --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx' \
-  --jira-url https://yourcompany.atlassian.net \
-  --jira-email you@company.com \
-  --jira-token 'jira_xxxxx' \
-  --jira-ticket AUTH-234 \
-  --generate-tests \
-  --test-framework vitest
 ```
+IRA/security (CRITICAL) - src/routes/auth.ts:42
 
-### 4. Standalone test generation (no review)
+User input used directly in SQL query without sanitization.
+
+Explanation: The username parameter is concatenated into a SQL string,
+creating a SQL injection vector.
 
-Don't need a review? Generate test cases directly from a JIRA ticket.
+Impact: Attacker could execute arbitrary SQL and gain database control.
 
-```bash
-npx ira-review generate-tests \
-  --jira-ticket AUTH-234 \
-  --jira-url https://yourcompany.atlassian.net \
-  --jira-email you@company.com \
-  --jira-token 'jira_xxxxx' \
-  --ai-api-key 'sk-xxxxx' \
-  --test-framework playwright
+Suggested Fix: Use parameterized queries:
+  db.query('SELECT * FROM users WHERE name = $1', [username])
 ```
 
-Add `--pr 42 --scm-provider github --github-repo owner/repo` to include code context from a PR for higher precision.
+---
+
+## Quick Start
 
-Add `--output tests/auth.test.ts` to save the generated tests to a file.
+### VS Code (recommended for individual developers)
 
-### 5. Sonar + AI review
+1. Install from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ira-review.ira-review-vscode)
+2. Open a project with a GitHub or Bitbucket remote
+3. `Cmd+Shift+P` > `IRA: Review Current PR`
+4. Enter your PR number
 
-Already using SonarQube? IRA pulls your Sonar issues and enriches each one with AI explanations and suggested fixes.
+If you have GitHub Copilot, that is all you need. No API keys, no configuration.
+
+### CLI
 
 ```bash
 npx ira-review review \
   --pr 42 \
   --scm-provider github \
-  --github-token 'ghp_xxxxx' \
+  --github-token "$GITHUB_TOKEN" \
   --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx' \
-  --sonar-url https://sonarcloud.io \
-  --sonar-token 'sqa_xxxxx' \
-  --project-key my-org_my-project
+  --ai-api-key "$OPENAI_API_KEY" \
+  --dry-run
 ```
 
-You can combine this with JIRA, test generation, and notifications too.
-
-## Quick reference
-
-| What you want | What to add | Example |
-|---|---|---|
-| AI-only review | `--pr`, SCM token, `--ai-api-key` | `npx ira-review review --pr 42 --scm-provider github --github-token ghp_xxx --github-repo owner/repo --ai-api-key sk-xxx` |
-| + SonarQube | `--sonar-url`, `--sonar-token`, `--project-key` | `... --sonar-url https://sonarcloud.io --sonar-token sqa_xxx --project-key my-org_my-project` |
-| + JIRA validation | `--jira-url`, `--jira-email`, `--jira-token`, `--jira-ticket` | `... --jira-url https://acme.atlassian.net --jira-email dev@acme.com --jira-token xxx --jira-ticket AUTH-234` |
-| + Test generation | `--generate-tests`, `--test-framework` | `... --generate-tests --test-framework vitest` |
-| + Slack notifications | `--slack-webhook` | `... --slack-webhook https://hooks.slack.com/services/xxx` |
-| + Teams notifications | `--teams-webhook` | `... --teams-webhook https://outlook.office.com/webhook/xxx` |
-| Notify only high risk | `--notify-min-risk` | `... --slack-webhook https://hooks.slack.com/xxx --notify-min-risk high` (only HIGH and CRITICAL trigger a notification) |
-| Notify on AC failure | `--notify-on-ac-fail` | `... --slack-webhook https://hooks.slack.com/xxx --notify-on-ac-fail` (notify when JIRA acceptance criteria fail, regardless of risk) |
-| Risk labels | Automatic on GitHub | Labels like `ira:critical`, `ira:high`, `ira:medium`, `ira:low` are applied automatically |
-| Preview in terminal | `--dry-run` | `... --dry-run` (prints output, doesn't post on PR) |
-| Use Anthropic | `--ai-provider anthropic` | `... --ai-provider anthropic --ai-api-key sk-ant-xxx` |
-| Use Ollama (free) | `--ai-provider ollama` | `... --ai-provider ollama` (no API key needed) |
-| Save on AI costs | `--ai-model` + `--ai-model-critical` | `... --ai-model gpt-4o-mini --ai-model-critical gpt-4o` |
-| Generate tests only | `generate-tests` command | `npx ira-review generate-tests --jira-ticket AUTH-234 --test-framework jest --ai-api-key sk-xxx` |
-| Save tests to file | `--output` | `... generate-tests --jira-ticket AUTH-234 --test-framework vitest --output tests/auth.test.ts` |
-
-## Supported test frameworks
-
-| Framework | Language | Style |
-|---|---|---|
-| `jest` | JavaScript/TypeScript | `describe` / `it` / `expect` |
-| `vitest` | JavaScript/TypeScript | `describe` / `it` / `expect` |
-| `mocha` | JavaScript/TypeScript | `describe` / `it` + Chai |
-| `playwright` | TypeScript | `test` / `page` / E2E |
-| `cypress` | JavaScript | `cy.visit` / `cy.get` / E2E |
-| `gherkin` | Any (BDD) | `Given` / `When` / `Then` |
-| `pytest` | Python | `def test_` / `assert` |
-| `junit` | Java/Kotlin | `@Test` / `assertEquals` |
-
-## AI providers
-
-| Provider | Flag | Notes |
-|---|---|---|
-| **OpenAI** (default) | `--ai-provider openai` | Pass key with `--ai-api-key` or set `IRA_AI_API_KEY` |
-| **Azure OpenAI** | `--ai-provider azure-openai` | Also needs `--ai-base-url` and `--ai-deployment` |
-| **Anthropic** | `--ai-provider anthropic` | Pass key with `--ai-api-key` or set `IRA_AI_API_KEY` |
-| **Ollama** (local) | `--ai-provider ollama` | Runs locally, no API key needed |
-
-> **Tip:** Use `--ai-model gpt-4o-mini` for most issues and `--ai-model-critical gpt-4o` for blockers. This keeps costs low without sacrificing quality on critical findings.
-
-## CI/CD setup
+Drop `--dry-run` to post comments directly on the PR.
 
 ### GitHub Actions
 
@@ -235,15 +324,6 @@ jobs:
           IRA_AI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 ```
 
-Want JIRA validation in CI? Add these flags to the run command:
-
-```
---jira-url ${{ vars.JIRA_URL }} \
---jira-email ${{ vars.JIRA_EMAIL }} \
---jira-token ${{ secrets.JIRA_TOKEN }} \
---jira-ticket AUTH-234
-```
-
 ### Bitbucket Pipelines
 
 ```yaml
@@ -262,123 +342,67 @@ pipelines:
             IRA_BITBUCKET_TOKEN: $BB_TOKEN
 ```
 
-> Use `--no-config-file` in CI pipelines that run on untrusted PRs (forks, external contributors).
-
-## Smart notifications
-
-By default, IRA sends a Slack or Teams notification after every review. You can control exactly when notifications fire so your team only hears about what matters.
+---
 
-### How it works
+## Adding JIRA and SonarQube
 
-| Setup | What happens | Best for |
-|---|---|---|
-| No flags set | Every review triggers a notification | Small teams that want full visibility |
-| `--notify-min-risk high` | Only HIGH (40+) and CRITICAL (60+) PRs trigger notifications. LOW and MEDIUM stay silent | Reducing noise, focusing on risky PRs |
-| `--notify-min-risk high --notify-on-ac-fail` | Notifies on HIGH/CRITICAL risk **or** when JIRA acceptance criteria fail, even on low risk PRs | **Recommended for tech leads.** Catches both risky code and incomplete requirements |
-| `--notify-on-ac-fail` alone | Every review still triggers a notification (no risk filter), but AC failures are guaranteed to notify | Teams that want full visibility but never want to miss an AC failure |
-
-### Example: only ping on high risk PRs
+Both integrations are optional and additive. IRA works with just an SCM provider and an AI key.
 
+**JIRA:**
 ```bash
 npx ira-review review \
   --pr 42 \
   --scm-provider github \
-  --github-token 'ghp_xxxxx' \
+  --github-token "$GITHUB_TOKEN" \
   --github-repo owner/repo \
-  --ai-api-key 'sk-xxxxx' \
-  --slack-webhook 'https://hooks.slack.com/services/xxx' \
-  --notify-min-risk high
-```
-
-Your `#code-reviews` channel only gets pinged for HIGH and CRITICAL PRs. Everything else reviews silently.
-
-### Example: catch risky PRs and incomplete requirements
-
-```bash
---notify-min-risk high --notify-on-ac-fail
+  --ai-api-key "$OPENAI_API_KEY" \
+  --jira-url https://yourcompany.atlassian.net \
+  --jira-email you@company.com \
+  --jira-token "$JIRA_TOKEN" \
+  --jira-ticket AUTH-234
 ```
 
-Tech leads get notified for two things: risky PRs and PRs that don't fully implement the JIRA requirements. Low risk, well-implemented PRs stay quiet.
-
-### What triggers a notification?
-
-Here's exactly when your Slack or Teams channel gets a message:
-
-| PR risk | AC status | No flags | `--notify-min-risk high` | `+ --notify-on-ac-fail` |
-|---|---|---|---|---|
-| LOW (5) | AC passes | ✅ Notified | Silent | Silent |
-| LOW (12) | AC fails | ✅ Notified | Silent | ✅ Notified |
-| MEDIUM (25) | AC passes | ✅ Notified | Silent | Silent |
-| HIGH (45) | AC passes | ✅ Notified | ✅ Notified | ✅ Notified |
-| CRITICAL (72) | AC fails | ✅ Notified | ✅ Notified | ✅ Notified |
-
-### Configuration
-
-All three ways to set this up:
-
+**SonarQube:**
 ```bash
-# CLI flags
---notify-min-risk high --notify-on-ac-fail
-
-# Environment variables (works in CI)
-IRA_NOTIFY_MIN_RISK=high
-IRA_NOTIFY_ON_AC_FAIL=true
-
-# Config file (.irarc.json)
-{ "notifyMinRisk": "high", "notifyOnAcFail": true }
+npx ira-review review \
+  --pr 42 \
+  --scm-provider github \
+  --github-token "$GITHUB_TOKEN" \
+  --github-repo owner/repo \
+  --ai-api-key "$OPENAI_API_KEY" \
+  --sonar-url https://sonarcloud.io \
+  --sonar-token "$SONAR_TOKEN" \
+  --project-key my-org_my-project
 ```
 
-## PR risk visibility
-
-IRA makes risk visible directly in your PR list so tech leads can prioritize without opening each PR.
-
-### GitHub: risk labels
-
-IRA applies color-coded labels to your PRs after each review:
-
-| Label | Score | Color |
-|---|---|---|
-| `ira:critical` | 60 to 100 | 🔴 Red |
-| `ira:high` | 40 to 59 | 🟠 Orange |
-| `ira:medium` | 20 to 39 | 🟡 Yellow |
-| `ira:low` | 0 to 19 | 🟢 Green |
-
-Labels update automatically when risk changes. Filter your PR list with `label:ira:critical label:ira:high` to prioritize reviews.
+---
 
-### Bitbucket: build status
+## Supported Providers
 
-Bitbucket doesn't support PR labels, so IRA posts a **build status** on the PR commit instead. This shows as a status icon (✅ ❌ 🟡) in the PR list.
+### SCM
 
-| Risk level | Build status | Icon in PR list |
-|---|---|---|
-| CRITICAL | FAILED | 🔴 Red X |
-| HIGH | FAILED | 🔴 Red X |
-| MEDIUM | INPROGRESS | 🟡 Yellow dot |
-| LOW | SUCCESSFUL | 🟢 Green check |
-
-Hover over the icon to see the full risk score. You can also configure Bitbucket branch permissions to **block merging** when the IRA Risk status is FAILED, preventing high-risk PRs from being merged without review.
+| Provider | Status |
+|---|:---:|
+| GitHub | Supported |
+| GitHub Enterprise | Supported |
+| Bitbucket Cloud | Supported |
+| Bitbucket Server / Data Center | Supported |
 
-## What IRA posts on your PR
+### AI
 
-**Inline comments** on the exact lines:
+| Provider | Notes |
+|---|---|
+| GitHub Copilot | VS Code only, zero config, uses existing session |
+| OpenAI | Default for CLI |
+| Azure OpenAI | Requires `--ai-base-url` and `--ai-deployment` |
+| Anthropic | Pass key with `--ai-api-key` |
+| Ollama | Fully local, no API key needed |
 
-```
-🔍 IRA Review — IRA/security (CRITICAL)
+**Cost optimization:** Use `--ai-model gpt-4o-mini` for most issues and `--ai-model-critical gpt-4o` for blockers. This keeps costs low without sacrificing quality on critical findings.
 
-> User input used directly in SQL query without sanitization.
-
-Explanation: The username parameter is concatenated into a SQL string,
-creating a SQL injection vector.
+---
 
-Impact: Attacker could execute arbitrary SQL and gain database control.
-
-Suggested Fix: Use parameterized queries:
-  db.query('SELECT * FROM users WHERE name = $1', [username])
-```
-
-**Summary comment** with risk score, issue breakdown, requirement completion (if JIRA is connected), and complexity hotspots (if Sonar is connected).
-
-## Config file
+## Config File
 
 Create `.irarc.json` in your project root to set defaults:
 
@@ -391,59 +415,22 @@ Create `.irarc.json` in your project root to set defaults:
 }
 ```
 
-CLI flags override env vars, which override the config file. Tokens and keys are blocked from config files for security.
-
-## VS Code Extension
-
-Use IRA directly inside your editor. No terminal needed.
-
-### Install
-
-Search **"IRA - AI Code Reviews"** in the VS Code Extensions panel, or:
-
-```bash
-code --install-extension ira-review.ira-review-vscode
-```
-
-### Features
-
-- **Zero config** - uses your existing GitHub Copilot subscription (or bring OpenAI, Anthropic, Ollama)
-- **Review Current File** - review the currently open file without a PR
-- **Generate Tests** - generate test cases from JIRA acceptance criteria
-- **Diagnostics** - issues show up as squiggly lines with severity levels
-- **CodeLens** - inline annotations on affected lines
-- **TreeView** - sidebar panel with all issues grouped by file
-- **Risk Score** - status bar badge showing LOW / MEDIUM / HIGH / CRITICAL
-- **Multi-SCM** - GitHub, GitHub Enterprise, Bitbucket Cloud, Bitbucket Server/Data Center
-- **Auto-review on Save** ⭐ Pro - automatically reviews files when you save
-- **Apply Fix** ⭐ Pro - one-click AI-generated fix via CodeLens
-- **Review History** ⭐ Pro - browse past reviews in a sidebar tree
-- **Trends Dashboard** ⭐ Pro - visualize issues over time
-- **Generate PR Description** - AI-powered PR descriptions with JIRA ticket detection
-- **Slack & Teams Notifications** - get notified after reviews
-
-### Quick Start
-
-1. Open a project with a git remote
-2. Run `IRA: Review Current PR` from the Command Palette (`Cmd+Shift+P`)
-3. Enter the PR number. IRA reviews every changed file and shows results inline
-
-📖 **Full extension docs:** [`packages/vscode/README.md`](packages/vscode/README.md)
-
-## Security
-
-- Runs in your CI. Tokens never leave your infrastructure
-- No telemetry, analytics, or tracking
-- Config files block sensitive fields automatically
+CLI flags override environment variables, which override the config file. Token fields are blocked from config files by design.
 
 ## Requirements
 
 - Node.js 18+
-- An AI provider API key (or Ollama running locally)
+- An AI provider API key (or Ollama running locally, or GitHub Copilot for the VS Code extension)
 - A GitHub or Bitbucket repo with an open PR
 
 ## License
 
 [Proprietary](LICENSE). See LICENSE file for details.
 
-📖 **Full CLI reference:** Run `npx ira-review review --help`
+Full CLI reference: `npx ira-review review --help`
+
+## Links
+
+- [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=ira-review.ira-review-vscode)
+- [npm package](https://www.npmjs.com/package/ira-review)
+- Support: patilmayur5572@gmail.com