ira-review 0.5.0 → 0.7.0

package/README.github.md

@@ -1,122 +1,199 @@
-# ira-review
+# IRA - AI-Powered Code Reviews for Pull Requests
 
-**AI-powered PR reviews with optional SonarQube, JIRA, and Slack/Teams integration.**
+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.
 
-IRA (Intelligent Review Assistant) reviews your pull requests using AI. Point it at a PR and it posts inline comments with plain-English explanations, impact assessments, and suggested fixes. It works in two modes:
+**Works with any language.** Supports GitHub and Bitbucket Cloud.
 
-- **AI-only** - reviews your PR diff directly, finds bugs, security issues, and performance problems
-- **Sonar + AI** - pulls SonarQube issues and enriches them with AI-powered explanations and fixes
+## What can IRA do?
 
-Works with **any language**. Supports **GitHub** and **Bitbucket** (Cloud & Server). Runs as a CLI tool in your pipeline - your project doesn't need to be JavaScript.
+- **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
 
-## 30-second demo
+## Try it in 30 seconds
 
 ```bash
-# Try it right now - no install needed
-export IRA_AI_API_KEY=sk-xxxxx
-
 npx ira-review review \
   --pr 42 \
   --scm-provider github \
-  --github-token ghp_xxxxx \
+  --github-token 'ghp_xxxxx' \
   --github-repo owner/repo \
+  --ai-api-key 'sk-xxxxx' \
   --dry-run
 ```
 
-Drop `--dry-run` to post comments directly on the PR.
+This prints the review in your terminal. Drop `--dry-run` to post it on the PR.
 
 ## Install
 
 ```bash
-npx ira-review review --pr 42 --dry-run          # run once, no install
-npm install --save-dev ira-review                  # add to project
-npm install -g ira-review                          # install globally
+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
 ```
 
----
+## How to use IRA
 
-## Quick start
+Pick the combination that fits your workflow. Each example builds on the previous one.
 
-### AI-only review (no SonarQube)
+### 1. AI-only review
 
-IRA fetches your PR diff and runs a full AI code review - finding bugs, security issues, and performance problems.
+The simplest setup. IRA reads your PR diff and finds bugs, security issues, and performance problems.
 
+**GitHub:**
 ```bash
 npx ira-review review \
   --pr 42 \
   --scm-provider github \
-  --github-token ghp_xxxxx \
-  --github-repo owner/repo
+  --github-token 'ghp_xxxxx' \
+  --github-repo owner/repo \
+  --ai-api-key 'sk-xxxxx'
 ```
 
-### Sonar + AI review
+**Bitbucket Cloud:**
+```bash
+npx ira-review review \
+  --pr 42 \
+  --bitbucket-token 'bb_xxxxx' \
+  --repo my-workspace/my-repo \
+  --ai-api-key 'sk-xxxxx'
+```
 
-Add your SonarQube config to get issue-level analysis with AI explanations:
+### 2. Review with JIRA (requirement tracking + AC validation)
+
+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.
 
 ```bash
 npx ira-review review \
   --pr 42 \
-  --sonar-url https://sonarcloud.io \
-  --sonar-token sqa_xxxxx \
-  --project-key my-org_my-project \
-  --bitbucket-token bb_xxxxx \
-  --repo my-workspace/my-repo
+  --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
 ```
 
-### Choose your AI provider
+Example output posted on your PR:
 
-IRA supports four AI providers. Set your provider with `--ai-provider`:
+```
+📊 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
+
+  ⚠️ Edge Cases Not Covered:
+     - What happens when Google OAuth is unreachable?
+     - Token refresh during concurrent requests?
+```
+
+### 3. Review with JIRA + test generation
 
-<table>
-<tr><th>Provider</th><th>Command</th></tr>
-<tr><td><b>OpenAI</b> (default)</td><td>
+Add `--generate-tests` to any review command and IRA will generate test scaffolding alongside the code review.
 
 ```bash
-export IRA_AI_API_KEY=sk-xxxxx
-npx ira-review review --pr 42 --dry-run
+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
 ```
 
-</td></tr>
-<tr><td><b>Azure OpenAI</b></td><td>
+### 4. Standalone test generation (no review)
+
+Don't need a review? Generate test cases directly from a JIRA ticket.
 
 ```bash
-export IRA_AI_API_KEY=xxxxx
-npx ira-review review --pr 42 \
-  --ai-provider azure-openai \
-  --ai-base-url https://my-instance.openai.azure.com \
-  --ai-deployment gpt-4o \
-  --ai-api-version 2024-08-01-preview \
-  --dry-run
+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
 ```
 
-</td></tr>
-<tr><td><b>Anthropic</b></td><td>
+Add `--pr 42 --scm-provider github --github-repo owner/repo` to include code context from a PR for higher precision.
 
-```bash
-export IRA_AI_API_KEY=sk-ant-xxxxx
-npx ira-review review --pr 42 \
-  --ai-provider anthropic \
-  --ai-model claude-sonnet-4-20250514 \
-  --dry-run
-```
+Add `--output tests/auth.test.ts` to save the generated tests to a file.
 
-</td></tr>
-<tr><td><b>Ollama</b> (local, no key)</td><td>
+### 5. Sonar + AI review
+
+Already using SonarQube? IRA pulls your Sonar issues and enriches each one with AI explanations and suggested fixes.
 
 ```bash
-npx ira-review review --pr 42 \
-  --ai-provider ollama \
-  --ai-model codellama \
-  --ai-base-url http://localhost:11434 \
-  --dry-run
+npx ira-review review \
+  --pr 42 \
+  --scm-provider github \
+  --github-token 'ghp_xxxxx' \
+  --github-repo owner/repo \
+  --ai-api-key 'sk-xxxxx' \
+  --sonar-url https://sonarcloud.io \
+  --sonar-token 'sqa_xxxxx' \
+  --project-key my-org_my-project
 ```
 
-</td></tr>
-</table>
+You can combine this with JIRA, test generation, and notifications too.
 
-> **Tip:** Use `--ai-model-critical gpt-4o` to route BLOCKER/CRITICAL issues to a stronger model while keeping costs low for everything else.
+## 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
 
@@ -135,18 +212,25 @@ jobs:
       - uses: actions/setup-node@v4
         with:
           node-version: 20
-
-      - run: npx ira-review review
-             --pr ${{ github.event.pull_request.number }}
-             --scm-provider github
-             --github-token ${{ secrets.GITHUB_TOKEN }}
-             --github-repo ${{ github.repository }}
-             --no-config-file
+      - run: |
+          npx ira-review review \
+            --pr ${{ github.event.pull_request.number }} \
+            --scm-provider github \
+            --github-token ${{ secrets.GITHUB_TOKEN }} \
+            --github-repo ${{ github.repository }} \
+            --no-config-file
         env:
           IRA_AI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
 ```
 
-> Add `IRA_SONAR_URL`, `IRA_SONAR_TOKEN`, and `IRA_PROJECT_KEY` env vars for Sonar + AI mode. Without them, IRA runs in AI-only mode.
+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
 
@@ -166,361 +250,152 @@ pipelines:
             IRA_BITBUCKET_TOKEN: $BB_TOKEN
 ```
 
-### Any language, any CI
+> Use `--no-config-file` in CI pipelines that run on untrusted PRs (forks, external contributors).
 
-IRA is an npm package, but your project can be anything - Java, Python, Go, Rust, C#, PHP, Ruby. If Node.js is available (and it almost always is), just add `npx ira-review review ...` as a step.
+## Smart notifications
 
-```bash
-# No Node.js? Use Docker
-docker run --rm node:20-slim npx ira-review review --pr $PR_ID --dry-run
-```
+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.
 
-> **Security:** Use `--no-config-file` in CI pipelines that run on untrusted PRs (forks, external contributors). This prevents a malicious `.irarc.json` in the PR from altering review behavior.
+### How it works
 
----
+| 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 |
 
-## What IRA posts on your PR
+### Example: only ping on high risk PRs
 
-### Inline comments
+```bash
+npx ira-review review \
+  --pr 42 \
+  --scm-provider github \
+  --github-token 'ghp_xxxxx' \
+  --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.
 
-Each issue gets an inline comment on the exact line:
+### Example: catch risky PRs and incomplete requirements
 
+```bash
+--notify-min-risk high --notify-on-ac-fail
 ```
-🔍 IRA Review - typescript:S1854 (BLOCKER)
 
-> Remove this useless assignment to local variable "data".
+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.
 
-Explanation: The variable "data" is assigned a value that is never used
-before being reassigned on line 15. This is dead code that adds confusion.
+### What triggers a notification?
 
-Impact: Dead code makes the codebase harder to read and maintain. It can
-also mask real bugs if developers assume the assignment has a purpose.
+Here's exactly when your Slack or Teams channel gets a message:
 
-Suggested Fix: Remove the assignment on line 10 entirely, or if the
-variable is needed later, move the declaration to where it's first used.
-```
+| 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 |
 
-### Summary comment
+### Configuration
 
-Every PR also gets a summary with risk score, issue breakdown, complexity hotspots, and JIRA validation results:
+All three ways to set this up:
 
-```
-# 🔍 IRA Review Summary
+```bash
+# CLI flags
+--notify-min-risk high --notify-on-ac-fail
 
-## 🟠 Risk: HIGH (45/100)
+# Environment variables (works in CI)
+IRA_NOTIFY_MIN_RISK=high
+IRA_NOTIFY_ON_AC_FAIL=true
 
-| Factor           | Score | Detail                        |
-|-------------------|-------|-------------------------------|
-| Blocker Issues    | 20/30 | 2 blocker issues found        |
-| Security Concerns | 10/20 | 1 security-related issue      |
-| Code Complexity   | 10/15 | 2 high-complexity files       |
-| Critical Issues   | 5/20  | 1 critical issue found        |
-| Issue Density     | 0/15  | 0.5 issues per file changed   |
+# Config file (.irarc.json)
+{ "notifyMinRisk": "high", "notifyOnAcFail": true }
 ```
 
----
+## PR risk visibility
 
-## Features
+IRA makes risk visible directly in your PR list so tech leads can prioritize without opening each PR.
 
-### PR risk scoring
+### GitHub: risk labels
 
-Every review calculates a risk score (0-100) from five factors:
+IRA applies color-coded labels to your PRs after each review:
 
-| Factor | Max | What it measures |
+| Label | Score | Color |
 |---|---|---|
-| Blocker Issues | 30 | Number of blocker-level issues |
-| Critical Issues | 20 | Number of critical-level issues |
-| Issue Density | 15 | Issues per file changed |
-| Security Concerns | 20 | Vulnerabilities, CWE/OWASP-tagged issues |
-| Code Complexity | 15 | Files with cyclomatic/cognitive complexity > 15 |
-
-**LOW** (0-19) · **MEDIUM** (20-39) · **HIGH** (40-59) · **CRITICAL** (60+)
-
-### Framework detection
+| `ira:critical` | 60 to 100 | 🔴 Red |
+| `ira:high` | 40 to 59 | 🟠 Orange |
+| `ira:medium` | 20 to 39 | 🟡 Yellow |
+| `ira:low` | 0 to 19 | 🟢 Green |
 
-IRA auto-detects your framework and tailors AI suggestions to match its conventions:
+Labels update automatically when risk changes. Filter your PR list with `label:ira:critical label:ira:high` to prioritize reviews.
 
-| Framework | Detection |
-|---|---|
-| React | `react` in `package.json` dependencies |
-| Angular | `@angular/core` in `package.json` dependencies |
-| Vue | `vue` in `package.json` dependencies |
-| NestJS | `@nestjs/core` in `package.json` dependencies |
-| Node.js | `package.json` exists (fallback) |
+### Bitbucket: build status
 
-### Comment deduplication
+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.
 
-Re-running IRA on the same PR (e.g., after pushing a fix) skips issues that were already commented on. Each comment is tracked by file, line, and rule - so different issues on the same line are preserved while true duplicates are skipped. No configuration needed.
-
-### JIRA acceptance criteria
+| Risk level | Build status | Icon in PR list |
+|---|---|---|
+| CRITICAL | FAILED | 🔴 Red X |
+| HIGH | FAILED | 🔴 Red X |
+| MEDIUM | INPROGRESS | 🟡 Yellow dot |
+| LOW | SUCCESSFUL | 🟢 Green check |
 
-Validate your PR against JIRA acceptance criteria using AI:
+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.
 
-```bash
-npx ira-review review --pr 42 \
-  --jira-url https://yourcompany.atlassian.net \
-  --jira-email dev@company.com \
-  --jira-token jira_xxxxx \
-  --jira-ticket PROJ-123
-```
+## What IRA posts on your PR
 
-Output:
+**Inline comments** on the exact lines:
 
 ```
-✅ JIRA: PROJ-123 - Add user authentication
-   ✅ Authentication endpoint implemented
-   ❌ Input validation - Critical security issue in login handler
-```
+🔍 IRA Review - ai/security (CRITICAL)
 
-Use `--jira-ac-field customfield_10042` if your acceptance criteria live in a custom field (default: `customfield_10035`).
+> User input used directly in SQL query without sanitization.
 
-### Slack & Teams notifications
+Explanation: The username parameter is concatenated into a SQL string,
+creating a SQL injection vector.
 
-```bash
---slack-webhook https://hooks.slack.com/services/xxx/yyy/zzz
---teams-webhook https://outlook.office.com/webhook/xxx
-```
+Impact: Attacker could execute arbitrary SQL and gain database control.
 
-Both can be used at the same time. Notifications include risk score, issue count, and framework detected.
-
----
-
-## How it works
-
-```mermaid
-sequenceDiagram
-    participant Dev as Developer
-    participant CI as CI/CD Pipeline
-    participant Sonar as SonarQube (optional)
-    participant IRA as IRA Review
-    participant AI as AI Provider
-    participant SCM as GitHub / Bitbucket
-    participant JIRA as JIRA (optional)
-    participant Notify as Slack / Teams (optional)
-
-    Dev->>CI: Push code / Open PR
-    opt SonarQube configured
-        CI->>Sonar: Run static analysis
-        Sonar-->>CI: Analysis complete
-    end
-    CI->>IRA: Run ira-review
-    IRA->>SCM: Fetch PR diff + source files
-    opt SonarQube configured
-        IRA->>Sonar: Fetch PR issues
-    end
-    IRA->>AI: Review each file/issue
-    AI-->>IRA: Explanation + Impact + Fix
-    IRA->>IRA: Calculate risk score + deduplicate
-    opt JIRA configured
-        IRA->>JIRA: Fetch acceptance criteria
-        IRA->>AI: Validate AC against findings
-    end
-    IRA->>SCM: Post inline comments + summary
-    opt Notifications configured
-        IRA->>Notify: Send review summary
-    end
+Suggested Fix: Use parameterized queries:
+  db.query('SELECT * FROM users WHERE name = $1', [username])
 ```
 
----
-
-## Configuration
+**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` or `ira.config.json` in your project root:
+Create `.irarc.json` in your project root to set defaults:
 
 ```json
 {
-  "projectKey": "my-org_my-project",
   "scmProvider": "github",
   "githubRepo": "owner/repo",
   "aiModel": "gpt-4o-mini",
-  "minSeverity": "MAJOR",
-  "dryRun": false
+  "minSeverity": "MAJOR"
 }
 ```
 
-**Priority:** CLI flags > environment variables > config file.
-
-> **⚠️ Security:** Config files only accept non-sensitive settings (repo names, model selection, severity, flags). Tokens, API keys, service URLs, and webhooks are **automatically ignored** if found in config files. Use environment variables or CLI flags for those. Use `--no-config-file` in CI with untrusted PRs.
-
-### Environment variables
-
-All settings can be configured via env vars. Copy `.env.example` to `.env` to get started.
-
-| Variable | Description |
-|---|---|
-| **AI** | |
-| `IRA_AI_API_KEY` | AI provider API key (**required**, except Ollama). Also accepts `OPENAI_API_KEY` |
-| `IRA_AI_BASE_URL` | AI provider base URL (Azure endpoint, Ollama URL) |
-| `IRA_AI_API_VERSION` | Azure OpenAI API version |
-| `IRA_AI_DEPLOYMENT_NAME` | Azure OpenAI deployment name |
-| **SonarQube** *(optional)* | |
-| `IRA_SONAR_URL` | SonarQube/SonarCloud URL |
-| `IRA_SONAR_TOKEN` | Sonar API token |
-| `IRA_PROJECT_KEY` | Sonar project key |
-| **SCM** | |
-| `IRA_PR` | Pull request ID |
-| `IRA_SCM_PROVIDER` | `bitbucket` (default) or `github` |
-| `IRA_BITBUCKET_TOKEN` | Bitbucket API token |
-| `IRA_BITBUCKET_URL` | Bitbucket Server base URL (self-hosted only) |
-| `IRA_REPO` | Bitbucket `workspace/repo-slug` |
-| `IRA_GITHUB_TOKEN` | GitHub API token |
-| `IRA_GITHUB_REPO` | GitHub `owner/repo` |
-| `IRA_GITHUB_URL` | GitHub Enterprise base URL (self-hosted only) |
-| **Review** | |
-| `IRA_MIN_SEVERITY` | Minimum severity: `BLOCKER`, `CRITICAL` (default), `MAJOR`, `MINOR`, `INFO` |
-| **JIRA** *(optional)* | |
-| `IRA_JIRA_URL` | JIRA base URL |
-| `IRA_JIRA_EMAIL` | JIRA account email |
-| `IRA_JIRA_TOKEN` | JIRA API token |
-| `IRA_JIRA_TICKET` | JIRA ticket key (e.g. `PROJ-123`) |
-| **Notifications** *(optional)* | |
-| `IRA_SLACK_WEBHOOK` | Slack incoming webhook URL |
-| `IRA_TEAMS_WEBHOOK` | Microsoft Teams webhook URL |
-
-### CLI reference
-
-```
-ira-review review [options]
-
-Required:
-  --pr <id>                    Pull request ID (or IRA_PR)
-
-SCM:
-  --scm-provider <provider>    bitbucket (default) or github
-  --bitbucket-token <token>    Bitbucket API token
-  --repo <repo>                Bitbucket workspace/repo-slug
-  --bitbucket-url <url>        Bitbucket Server base URL
-  --github-token <token>       GitHub API token
-  --github-repo <repo>         GitHub owner/repo
-  --github-url <url>           GitHub Enterprise base URL
-
-AI:
-  --ai-provider <provider>     openai (default), azure-openai, anthropic, ollama
-  --ai-model <model>           AI model (default: gpt-4o-mini)
-  --ai-model-critical <model>  Stronger model for BLOCKER/CRITICAL issues
-  --ai-base-url <url>          AI provider base URL
-  --ai-api-version <version>   Azure OpenAI API version
-  --ai-deployment <name>       Azure OpenAI deployment name
-
-SonarQube (optional):
-  --sonar-url <url>            SonarQube/SonarCloud base URL
-  --sonar-token <token>        Sonar API token
-  --project-key <key>          Sonar project key
-
-Review:
-  --min-severity <level>       BLOCKER, CRITICAL (default), MAJOR, MINOR, INFO
-  --dry-run                    Print to terminal instead of posting
-
-JIRA (optional):
-  --jira-url <url>             JIRA base URL
-  --jira-email <email>         JIRA account email
-  --jira-token <token>         JIRA API token
-  --jira-ticket <key>          JIRA ticket key (e.g. PROJ-123)
-  --jira-ac-field <field>      Custom field ID for acceptance criteria
-
-Notifications (optional):
-  --slack-webhook <url>        Slack webhook URL
-  --teams-webhook <url>        Microsoft Teams webhook URL
-
-Config:
-  --config <path>              Path to config file
-  --no-config-file             Disable auto-loading config from repo
-```
-
----
-
-## Programmatic API
-
-Use IRA as a library for custom integrations:
-
-```typescript
-import { ReviewEngine } from "ira-review";
-
-const engine = new ReviewEngine({
-  scmProvider: "github",
-  scm: {
-    token: process.env.GITHUB_TOKEN!,
-    owner: "my-org",
-    repo: "my-repo",
-  },
-  ai: {
-    provider: "openai",
-    apiKey: process.env.IRA_AI_API_KEY!,
-  },
-  pullRequestId: "42",
-  // Optional: add Sonar, JIRA, notifications
-  // sonar: { baseUrl: "...", token: "...", projectKey: "..." },
-  // jira: { baseUrl: "...", email: "...", token: "..." },
-  // jiraTicket: "PROJ-123",
-  // notifications: { slackWebhookUrl: "...", teamsWebhookUrl: "..." },
-});
-
-const result = await engine.run();
-
-console.log(`Risk: ${result.risk?.level} (${result.risk?.score}/${result.risk?.maxScore})`);
-console.log(`Issues: ${result.totalIssues} found, ${result.reviewedIssues} reviewed`);
-console.log(`Comments: ${result.commentsPosted} posted`);
-```
-
-Add `dryRun: true` to preview without posting.
-
----
+CLI flags override env vars, which override the config file. Tokens and keys are blocked from config files for security.
 
 ## Security
 
-- **Runs on your servers** - IRA is an npm package that runs in your CI. Your tokens never leave your infrastructure.
-- **No telemetry** - zero analytics, tracking, or phone-home calls. The only network calls are to APIs you configure.
-- **Config file protection** - tokens, keys, URLs, and webhooks are automatically blocked from config files. Only non-sensitive settings are accepted.
-- **Prompt injection safety** - untrusted content (diffs, source code, JIRA text) is escaped and delimited to prevent prompt injection attacks.
-- **Open source** - every line is auditable. Only compiled `dist/` ships to npm.
-
-## Built-in reliability
-
-- **Automatic retries** - all API calls retry up to 3x with exponential backoff and jitter
-- **Timeout protection** - every HTTP call has a 30-second timeout
-- **Concurrency control** - AI calls capped at 3 concurrent requests
-- **Soft failures** - optional features (complexity, JIRA, notifications) fail gracefully with warnings
-- **Full pagination** - Sonar issues and complexity metrics paginate through all results
-
----
-
-## Development
-
-```bash
-npm install          # install deps
-npm run typecheck    # type check
-npm test             # run all tests (133 tests, 19 files)
-npm run test:watch   # watch mode
-npm run build        # build ESM + CJS + types
-```
-
-### Project structure
-
-```
-src/
-  core/           reviewEngine, riskScorer, sonarClient, complexityAnalyzer,
-                  acceptanceValidator, summaryBuilder, issueProcessor
-  ai/             aiClient (OpenAI, Azure, Anthropic, Ollama), promptBuilder
-  scm/            github, bitbucket, commentTracker
-  integrations/   jiraClient, notifier (Slack, Teams)
-  frameworks/     detector (React, Angular, Vue, NestJS, Node)
-  utils/          retry, concurrency, env, configFile
-  types/          config, sonar, review, risk, jira
-```
+- Runs in your CI. Tokens never leave your infrastructure
+- No telemetry, analytics, or tracking
+- Config files block sensitive fields automatically
+- Open source. Every line is auditable
 
 ## Requirements
 
 - Node.js 18+
-- AI provider API key (OpenAI, Azure OpenAI, Anthropic) or Ollama running locally
-- GitHub or Bitbucket repo with an open pull request
-- SonarQube/SonarCloud *(optional)*
-- JIRA Cloud *(optional)*
-- Slack/Teams webhooks *(optional)*
+- An AI provider API key (or Ollama running locally)
+- A GitHub or Bitbucket repo with an open PR
 
 ## License
 
-AGPL-3.0 - see [LICENSE](LICENSE) for details.
+[AGPL-3.0](LICENSE). For commercial licensing, contact [patilmayur5572@gmail.com](mailto:patilmayur5572@gmail.com).
 
-For commercial licensing (use IRA in proprietary projects without AGPL obligations), contact [patilmayur5572@gmail.com](mailto:patilmayur5572@gmail.com).
+📖 **Full CLI reference:** Run `npx ira-review review --help`