Metadata-Version: 2.4
Name: glreview
Version: 0.2.0
Summary: GitLab code review tracking for scientific software
Author-email: Chad Hanna <chad.hanna@ligo.org>
License: MIT
Project-URL: Homepage, https://git.ligo.org/chad.hanna/glreview
Project-URL: Documentation, https://git.ligo.org/chad.hanna/glreview
Project-URL: Repository, https://git.ligo.org/chad.hanna/glreview
Project-URL: Issues, https://git.ligo.org/chad.hanna/glreview/-/issues
Keywords: gitlab,code-review,scientific-software,ci-cd
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: Software Development :: Version Control :: Git
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: click>=8.0
Requires-Dist: jinja2>=3.0
Requires-Dist: python-gitlab>=4.0
Requires-Dist: tomli>=2.0; python_version < "3.11"
Provides-Extra: test
Requires-Dist: pytest>=8.0; extra == "test"
Requires-Dist: pytest-cov; extra == "test"
Provides-Extra: lint
Requires-Dist: black; extra == "lint"
Requires-Dist: flake8; extra == "lint"
Requires-Dist: flake8-bandit; extra == "lint"
Requires-Dist: flake8-black; extra == "lint"
Requires-Dist: flake8-bugbear; extra == "lint"
Requires-Dist: flake8-future-annotations; extra == "lint"
Requires-Dist: flake8-isort; extra == "lint"
Requires-Dist: flake8-pyproject; extra == "lint"
Requires-Dist: isort; extra == "lint"
Requires-Dist: mypy; extra == "lint"
Provides-Extra: dev
Requires-Dist: glreview[test]; extra == "dev"
Requires-Dist: glreview[lint]; extra == "dev"

# 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
- **AI-generated context** - Claude analyzes your project to enhance reviews
- **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 claude-init` | Generate AI project context |
| `glreview claude-sync` | Update AI context for changed files |
| `glreview claude-context [PATH]` | View AI-generated context |
| `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 evaluate: organization, readability, purpose, error handling, test coverage,
corner cases, documentation, integration, performance, and security.

Large files are automatically chunked.

### AI-Generated Project Context

For better reviews, let Claude analyze your project structure:

```bash
# Generate project context (one-time setup)
glreview claude-init

# View the generated context
glreview claude-context                    # Project overview
glreview claude-context src/module.py      # Module-specific context

# Update after significant changes
glreview claude-sync
```

This creates `.glreview/context.json` which should be committed to version control.
Claude analyzes your codebase to identify:

- **Project conventions** - coding patterns, architecture, style
- **Test associations** - which test files cover which modules (regardless of naming conventions)
- **Import relationships** - what depends on what
- **Module purposes** - what each module does

When you run `claude-review`, this context is automatically included, giving Claude:
- The actual test file content for the module being reviewed
- Project conventions to check against
- Understanding of how the module fits in the larger codebase

The context file is human-editable - you can refine Claude's analysis or add notes.

## 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.

### Setup

1. **Create a Project Access Token** with `write_repository` scope:
   - Settings → Access Tokens → Add new token
   - Role: Maintainer, Scopes: `write_repository`

2. **Add it as a CI variable**:
   - Settings → CI/CD → Variables
   - Key: `PUSH_TOKEN`, Value: the token, Masked: yes

3. **Add CI configuration**:
   ```bash
   glreview ci-config
   ```

### Example Configuration

```yaml
review-sync:
  variables:
    GIT_TERMINAL_PROMPT: "0"
  script:
    - pip install glreview
    - git config user.email "gitlab-ci@$CI_SERVER_HOST"
    - git config user.name "GitLab CI"
    - git remote set-url origin "https://oauth2:${PUSH_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git"
    - git checkout $CI_COMMIT_BRANCH
    - glreview report --sync --format markdown --output REVIEW_COVERAGE.md
    - git add REVIEW_COVERAGE.md review_registry.json || true
    - 'git diff --cached --quiet || git commit -m "chore: update review registry"'
    - 'git diff origin/$CI_COMMIT_BRANCH --quiet && echo "No changes to push" || git push origin HEAD:$CI_COMMIT_BRANCH -o ci.skip'
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
```

Run `glreview ci-config` for complete configuration including MR sync and release gates.

## License

MIT
