# Reviewer Verification Checklist

## Overview

This checklist provides a systematic approach for reviewing changes in the Runtime Role Matrix project. Use this document alongside `scripts/smoke-test.sh` for automated verification.

## Verification Commands

### Automated Smoke Test

```bash
# Run smoke test with stdout output
./scripts/smoke-test.sh

# Run smoke test with JSON output
./scripts/smoke-test.sh --json

# Run smoke test and save to file
./scripts/smoke-test.sh --json --output verification-report.json

# Specify reviewer name
./scripts/smoke-test.sh --json --checked-by "your-name"
```

### Individual Verification Steps

If running individual checks instead of the smoke test:

```bash
# Build verification
mvn compile -q

# Unit tests
mvn test -q

# Code format compliance (requires checkstyle configuration)
mvn checkstyle:check

# JavaDoc generation
mvn javadoc:javadoc

# Package verification
mvn package -DskipTests -q

# Dependency analysis
mvn dependency:tree -q

# Static analysis (if spotbugs is configured)
mvn spotbugs:check

# Integration tests
mvn verify -q
```

## Checklist Items

### 1. Build & Compile

- [ ] **Maven Build**: Project compiles without errors
  - Command: `mvn compile -q`
  - Expected: BUILD SUCCESS

- [ ] **Package Verification**: JAR/package builds successfully
  - Command: `mvn package -DskipTests -q`
  - Expected: BUILD SUCCESS, artifact created

- [ ] **Dependency Check**: All dependencies resolve correctly
  - Command: `mvn dependency:tree -q`
  - Expected: No unresolved dependencies

### 2. Code Quality

- [ ] **Code Format Compliance**: Code follows project style guidelines
  - Command: `mvn checkstyle:check`
  - Expected: No checkstyle violations
  - Note: Requires checkstyle configuration in pom.xml

- [ ] **JavaDoc Existence**: All public APIs have JavaDoc documentation
  - Command: `mvn javadoc:javadoc`
  - Expected: JavaDoc generation completes without errors
  - Note: Check for missing/warning JavaDoc in output

- [ ] **Static Analysis**: No critical bugs detected by static analysis
  - Command: `mvn spotbugs:check`
  - Expected: No high/critical issues
  - Note: SKIP if spotbugs-maven-plugin not configured

### 3. Testing

- [ ] **Unit Tests**: All unit tests pass
  - Command: `mvn test -q`
  - Expected: All tests pass, BUILD SUCCESS

- [ ] **Integration Tests**: Integration tests pass (if configured)
  - Command: `mvn verify -q`
  - Expected: All integration tests pass
  - Note: SKIP if no integration tests exist

### 4. Documentation

- [ ] **CHANGELOG Updated**: Changes documented in CHANGELOG
- [ ] **README Updated**: Documentation reflects new functionality
- [ ] **API Documentation**: Public API changes documented

### 5. Security & Compliance

- [ ] **No Hardcoded Secrets**: No credentials or secrets in code
- [ ] **Dependency Vulnerabilities**: No known CVEs in dependencies
  - Command: `mvn dependency-check:check` (if configured)

## Report Generation

### Using smoke-test.sh (Recommended)

1. Run the smoke test with JSON output:
   ```bash
   ./scripts/smoke-test.sh --json --output smoke-report.json
   ```

2. Review the generated JSON file

3. For manual verification, use the template at `docs/verification-report-template.json`

### Manual Report Creation

Create a JSON report matching `verification-report-template.json`:

```json
{
  "checkedAt": "2026-07-14T15:22:00Z",
  "checkedBy": "reviewer-name",
  "summary": {
    "total": 8,
    "passed": 7,
    "failed": 1
  },
  "items": [
    { "name": "Maven Build", "status": "PASS" },
    { "name": "Unit Tests", "status": "PASS" },
    { "name": "Code Format Compliance", "status": "PASS" },
    { "name": "JavaDoc Existence", "status": "PASS" },
    { "name": "Package Verification", "status": "PASS" },
    { "name": "Dependency Check", "status": "PASS" },
    { "name": "Static Analysis", "status": "SKIP", "reason": "not configured" },
    { "name": "Integration Tests", "status": "FAIL", "command": "mvn verify" }
  ]
}
```

## Exit Codes

| Code | Meaning |
|------|---------|
| 0 | All checks passed |
| 1 | One or more checks failed |
| 2 | Invalid arguments |

## Troubleshooting

### Common Issues

1. **Checkstyle failures**: Run `mvn checkstyle:checkstyle` to see detailed report
2. **Test failures**: Run `mvn test` without `-q` for detailed output
3. **Build failures**: Check Maven version compatibility (requires 3.6+)

### Script Location

The smoke test script is located at: `scripts/smoke-test.sh`

This path is relative to the project root directory.