npm package: @rootplatform/review-my-pr
Description: CLI tool that generates a code review prompt from a git diff and copies it to the clipboard
Latest version: 1.0.0

# review-my-pr

CLI tool that generates a code review prompt from your git diff and copies it to the clipboard. Paste it into any LLM chat to get an instant code review.


## Usage

Run from any git repository on a feature branch:

```bash
# Auto-detects main/master as the base branch
review-my-pr

# Specify a base branch
review-my-pr --base develop

# Exclude additional file patterns
review-my-pr --exclude "*.generated.ts" --exclude "docs/**"
```

### Options

| Flag | Description |
|---|---|
| `-b, --base <branch>` | Base branch to diff against. Auto-detects `origin/main`, `origin/master`, `main`, or `master` if not specified. |
| `-e, --exclude <pattern>` | Additional git pathspec exclusion pattern. Can be repeated for multiple patterns. |
| `-V, --version` | Show version number |
| `-h, --help` | Show help |

### Example Output

```
Generating diff from origin/master...
✅ Diff generated successfully
✅ Found 2 changed file(s) (65 lines)

✅ Review prompt copied to clipboard!
Just paste it into your chat with Cmd+V
```

## Configuration

Create a `.review-my-pr/` directory in your repository root to customize the review prompt. The directory contains two files:

```
.review-my-pr/
  prompt.md       # The review prompt template
  config.json     # Category definitions and settings
```

If this directory is not present, a sensible default prompt is used.

### `prompt.md` - Prompt Template

Use these placeholders in your template and they will be replaced with actual values:

| Placeholder | Description |
|---|---|
| `{{DIFF}}` | The full git diff content |
| `{{BASE_BRANCH}}` | The base branch name (e.g. `origin/master`) |
| `{{CHANGED_FILES}}` | List of all changed files |
| `{{SRC_FILES}}` | Source files only (excludes tests, mocks, fixtures) |
| `{{TEST_FILES}}` | Test/spec files only |
| `{{MIGRATION_FILES}}` | Database migration files |
| `{{HTTP_FILES}}` | HTTP layer files |
| `{{PR_TITLE}}` | PR title (requires `gh` CLI) |
| `{{PR_BODY}}` | PR description body (requires `gh` CLI) |
| `{{PR_METADATA}}` | Formatted PR title + description block |
| `{{CATEGORY.NAME}}` | Custom category defined in `config.json` (see below) |

If `{{DIFF}}` is not present in your template, the diff will be appended automatically at the end.

### `config.json` - Custom File Categories

Define custom file categories to group changed files by regex patterns. Reference them in `prompt.md` with `{{CATEGORY.NAME}}`.

```json
{
  "categories": {
    "SRC_FILES": {
      "exclude": "\\.(test|spec)\\.(ts|tsx|js|jsx)$|__mocks__|fixtures"
    },
    "TEST_FILES": {
      "pattern": "\\.(test|spec)\\.(ts|tsx|js|jsx)$"
    },
    "MIGRATION_FILES": {
      "pattern": "migrations/\\d+_.*\\.(ts|js)$"
    },
    "SCHEMAS": {
      "pattern": "\\.graphql$|\\.schema\\.ts$"
    }
  }
}
```

| Property | Description |
|---|---|
| `pattern` | Regex to include matching files. If omitted, all files are included (before `exclude` is applied). |
| `exclude` | Regex to exclude matching files. Applied after `pattern`. |

Categories are independent -- a file can appear in multiple categories.

### Example

`.review-my-pr/config.json`:

```json
{
  "categories": {
    "SRC_FILES": { "exclude": "\\.(test|spec)\\.(ts|tsx|js|jsx)$|__mocks__|fixtures" },
    "TEST_FILES": { "pattern": "\\.(test|spec)\\.(ts|tsx|js|jsx)$" }
  }
}
```

`.review-my-pr/prompt.md`:

```markdown
You are an expert code reviewer for our TypeScript backend.

## Context
- Stack: TypeScript, Node.js, PostgreSQL
- Focus: bugs, security, performance, test coverage

## Source Files
{{CATEGORY.SRC_FILES}}

## Test Files
{{CATEGORY.TEST_FILES}}

## Diff

\`\`\`diff
{{DIFF}}
\`\`\`
```

The built-in placeholders (`{{SRC_FILES}}`, `{{TEST_FILES}}`, etc.) still work and use the default categorization patterns. Custom categories via `{{CATEGORY.*}}` give you full control over the regex patterns.

## Default Exclusions

The following file patterns are always excluded from the diff:

- `**/package-lock.json`
- `**/yarn.lock`
- `**/pnpm-lock.yaml`
- `**/test-results/**`
- `**/playwright-report/**`

Use `--exclude` to add more patterns on top of these.

## PR Metadata

If you have the [GitHub CLI](https://cli.github.com/) (`gh`) installed and your branch has an open PR, the tool will automatically include the PR title and description in the prompt.

## Development

```bash
git clone <repo-url>
cd review-my-pr
npm install
npm run build
npm link   # makes `review-my-pr` available globally
```