npm package: @pulkit004/mr-principle-review-agent
Description: Open-source GitLab/GitHub principles review agent powered by OpenAI.
Latest version: 0.1.0

# MR Principles Review Agent

[![CI](https://github.com/pulkit004/mr-principle-review-agent/actions/workflows/ci.yml/badge.svg)](https://github.com/pulkit004/mr-principle-review-agent/actions/workflows/ci.yml)
[![npm version](https://img.shields.io/npm/v/%40pulkit004%2Fmr-principle-review-agent)](https://www.npmjs.com/package/@pulkit004/mr-principle-review-agent)
[![License](https://img.shields.io/github/license/pulkit004/mr-principle-review-agent)](./LICENSE)

Open-source reviewer for GitLab merge requests and GitHub pull requests. It checks changed code against your engineering principles and posts concise findings back to the review thread.

## Features
- VCS support: GitLab + GitHub
- Repo/principles agnostic via environment variables
- OpenAI structured review output
- Findings-only note with copyable `Agent prompt`
- Diff-hash dedupe to avoid repeat spend
- Cost/scope guardrails

## Installation

Run directly with npx:

```bash
npx --yes @pulkit004/mr-principle-review-agent
```

Or install in your project:

```bash
npm install --save-dev @pulkit004/mr-principle-review-agent
```

Then run:

```bash
npx mr-principles-review
```

## Quick Start

1. Provide required environment variables for your provider and OpenAI.
2. Provide principles via `MR_REVIEW_PRINCIPLES_TEXT` or `MR_REVIEW_PRINCIPLES_FILE`.
3. Run:

```bash
npx --yes @pulkit004/mr-principle-review-agent
```

For local development in this repository:

```bash
npm ci
npm start
```

## Provider Selection
- Explicit: `MR_REVIEW_VCS_PROVIDER=gitlab` or `github`
- Auto-detect:
  - GitHub when `GITHUB_REPOSITORY` or `GITHUB_ACTIONS` exists
  - otherwise GitLab

## Required Environment Variables
Common:
- `OPENAI_API_KEY`
- `MR_REVIEW_PRINCIPLES_TEXT` or `MR_REVIEW_PRINCIPLES_FILE`

GitLab mode:
- `GITLAB_TOKEN` (or `CI_JOB_TOKEN`)
- `CI_API_V4_URL`
- `CI_PROJECT_ID`
- `CI_MERGE_REQUEST_IID`

GitHub mode:
- `GITHUB_TOKEN` (or `GH_TOKEN`)
- `GITHUB_REPOSITORY` (`owner/repo`)
- PR number from one of:
  - `GITHUB_PR_NUMBER`
  - `GITHUB_REF` (`refs/pull/<id>/merge`)
  - `GITHUB_EVENT_PATH`

## Optional Environment Variables
- `OPENAI_MODEL` (default: `gpt-4.1-mini`)
- `MR_REVIEW_VCS_PROVIDER` (`gitlab|github`)
- `MR_REVIEW_CODE_FILE_REGEX` (default: `\\.(ts|tsx|js|jsx)$`)
- `MR_REVIEW_TARGET_BRANCHES` (default: `main`)
- `MR_REVIEW_MAX_DIFF_CHARS` (default: `60000`)
- `MR_REVIEW_MAX_OUTPUT_TOKENS` (default: `700`)
- `MR_REVIEW_MAX_FINDINGS` (default: `3`)
- `MR_REVIEW_MIN_SEVERITY` (default: `low`)
- `MR_REVIEW_FORCE_REVIEW` (`true/false`)
- `MR_REVIEW_BLOCKING` (`true/false`)
- `MR_REVIEW_GUARDRAIL_ENFORCE` (default: `true`)
- `MR_REVIEW_MAX_ESTIMATED_RUN_COST_USD` (default: `0.20`)
- `MR_REVIEW_ESTIMATED_OUTPUT_TOKENS` (default: `900`, used for pre-run cost estimate)
- `MR_REVIEW_MONTHLY_MR_COUNT` (default: `120`)
- `MR_REVIEW_MONTHLY_BUDGET_USD` (default: `30`)
- `MR_REVIEW_PRICE_GPT41_MINI_INPUT_PER_1M` (default: `0.40`)
- `MR_REVIEW_PRICE_GPT41_MINI_OUTPUT_PER_1M` (default: `1.60`)
- `MR_REVIEW_PRICE_GPT41_INPUT_PER_1M` (default: `2.00`)
- `MR_REVIEW_PRICE_GPT41_OUTPUT_PER_1M` (default: `8.00`)

## CI Templates
- GitLab: [`templates/gitlab-ci.yml`](./templates/gitlab-ci.yml)
- GitHub Actions: [`templates/github-pr-review.yml`](./templates/github-pr-review.yml)

## Output
The posted comment contains:
- Severity + principle
- File
- Issue
- Agent prompt in a copyable fenced block

## Security Reporting
See [`SECURITY.md`](./SECURITY.md) for private vulnerability reporting.

## Contributing
See [`CONTRIBUTING.md`](./CONTRIBUTING.md), [`CODE_OF_CONDUCT.md`](./CODE_OF_CONDUCT.md), and [`SUPPORT.md`](./SUPPORT.md).

## Release Process
- CI runs on pushes and pull requests across Node 20 and 22.
- Releases are tag-driven (`vX.Y.Z`) through GitHub Actions.
- Publish requires `NPM_TOKEN` in repository secrets.

## Test
```bash
npm test
```