# glreview

GitLab code review tracking for scientific software.

## Features

- **Track review status** of source modules with git commit precision
- **GitLab integration** - creates issues, verifies completion, closes on cancel
- **AI-assisted review** - Claude Code integration for automated analysis
- **Change detection** - warns if code changes during review
- **Module analysis** - shows classes/functions in review issues
- **Customizable templates** - Jinja2-based issue templates
- **CI-friendly** - exit codes for automated checks
- **Priority rules** - pattern-based priority assignment

## Installation

```bash
pip install glreview
```

## GitLab Authentication

For GitLab integration, set an environment variable:

```bash
export GITLAB_PRIVATE_TOKEN=glpat-xxxxxxxxxxxx

# For self-hosted GitLab
export GITLAB_URL=https://gitlab.example.com
```

In CI pipelines, `CI_JOB_TOKEN` is used automatically.

## Quick Start

```bash
# Initialize in your project
glreview init

# Check status
glreview status

# Start a review (creates GitLab issue)
glreview start src/mymodule/core.py --assignee @reviewer

# After review is complete (issue closed)
glreview signoff src/mymodule/core.py
```

## Commands

| Command | Description |
|---------|-------------|
| `glreview init` | Initialize (idempotent - safe to re-run) |
| `glreview status` | Show review progress and module status |
| `glreview start PATH` | Start a review (creates GitLab issue) |
| `glreview signoff PATH` | Sign off on a completed review |
| `glreview cancel PATH` | Cancel or restart a review |
| `glreview claude-review PATH` | Run AI-assisted review with Claude |
| `glreview report` | Generate coverage report (markdown/json/badge) |
| `glreview list` | List all modules |
| `glreview reviewers` | List available reviewers |
| `glreview check` | CI check for changes |
| `glreview sync` | Sync registry with filesystem |
| `glreview ci-config` | Print recommended GitLab CI configuration |

## Review Lifecycle

```
  ┌─────────────┐
  │ needs_review│◄──────────────────┐
  └──────┬──────┘                   │
         │ start                    │ cancel
         ▼                          │
  ┌─────────────┐                   │
  │ in_progress │───────────────────┤
  └──────┬──────┘                   │
         │ signoff                  │
         ▼                          │
  ┌─────────────┐   code changes    │
  │  reviewed   │───────────────────┘
  └─────────────┘   (re-review)
```

**Key behaviors:**
- `signoff` warns if file changed during review (use `--acknowledge` to proceed)
- `cancel` closes the GitLab issue by default (use `--leave-open` to skip)
- `cancel --restart` keeps the issue open and updates the start commit

## AI-Assisted Review

Use Claude Code for automated code analysis:

```bash
# Run review (requires claude CLI)
glreview claude-review src/module.py

# Post findings to GitLab issue
glreview claude-review src/module.py --post

# Preview prompt without running
glreview claude-review src/module.py --dry-run
```

Reviews check: correctness, scientific rigor, robustness, and maintainability.
Large files are automatically chunked.

## Configuration

Add to `pyproject.toml`:

```toml
[tool.glreview]
sources = ["src/**/*.py"]
exclude = ["**/_version.py", "**/test_*.py"]

# Custom issue template (optional)
issue_template = ".glreview/issue_template.md"

# Priority rules (first match wins)
[[tool.glreview.priority]]
pattern = "src/**/core.py"
level = "critical"
reviewers_required = 2

[[tool.glreview.priority]]
pattern = "src/**/*.py"
level = "medium"
reviewers_required = 1
```

## CI Integration

glreview can automatically sync and report on every push:

```bash
# Print full CI configuration
glreview ci-config
```

**Basic setup** - sync registry and generate coverage on MRs and main:

```yaml
review-sync:
  script:
    - pip install glreview
    - glreview report --sync --commit -m "chore: update review registry [skip ci]"
    - git push  # Push updated registry
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

**Release gate** - require 100% coverage for releases:

```yaml
release-gate:
  script:
    - pip install glreview
    - glreview report --format json | python -c "
        import sys,json
        c = json.load(sys.stdin)['coverage_pct']
        sys.exit(0 if c == 100 else 1)
      "
  rules:
    - if: $CI_COMMIT_TAG
```

Run `glreview ci-config` for complete configuration with proper git push setup.

## License

MIT
