opa-toolchain

What this skill does

# OPA Toolchain

Reference for the OPA CLI, Regal linter, and ecosystem tooling. Covers the complete policy development lifecycle from authoring through deployment.

## OPA CLI Reference

### Core Commands

| Command | Purpose | Common Flags |
|---------|---------|-------------|
| `opa eval` | Evaluate a Rego query | `-d`, `-i`, `--format`, `--explain`, `--partial` |
| `opa test` | Run unit tests | `-v`, `--coverage`, `--threshold`, `--run`, `--bench` |
| `opa check` | Validate syntax | `--strict`, `--schema`, `-b` |
| `opa fmt` | Format Rego files | `-w` (write), `--rego-v1` (migrate) |
| `opa build` | Create bundles | `-b`, `-o`, `--optimize`, `--target` |
| `opa run` | REPL or server | `--server`, `--addr`, `-b` |
| `opa bench` | Benchmark queries | `--benchmem`, `-d`, `-i` |
| `opa inspect` | Analyze bundles | (bundle path) |
| `opa sign` | Sign bundles | `--signing-key`, `--signing-alg` |
| `opa exec` | Batch evaluate | `-b`, `--decision` |
| `opa deps` | Show dependencies | `-d` |
| `opa parse` | Show AST | `--format json` |

### Evaluation

```bash
# Evaluate a query against policy and input
opa eval -d policy.rego -i input.json "data.authz.allow"

# Pretty-print result
opa eval -d policy.rego -i input.json "data.authz.allow" --format pretty

# Trace evaluation (debugging)
opa eval -d policy.rego -i input.json "data.authz.allow" --explain=notes

# Full trace
opa eval -d policy.rego -i input.json "data.authz.allow" --explain=full

# Profiling
opa eval -d policy.rego -i input.json "data.authz.allow" --profile

# Partial evaluation (optimize)
opa eval -d policy.rego --partial -i input.json "data.authz.allow"

# With bundle
opa eval -b bundle/ -i input.json "data.authz.allow"
```

### Syntax Checking

```bash
# Basic check
opa check policy.rego

# Strict mode (catches more issues)
opa check --strict policy.rego

# With JSON schema validation
opa check --schema schema/ policy.rego

# Check all files in directory
opa check ./policies/

# Check bundle
opa check -b bundle/
```

### Formatting

```bash
# Preview formatting changes
opa fmt policy.rego

# Write changes in-place
opa fmt -w policy.rego

# Format all Rego files
opa fmt -w ./policies/

# Migrate to Rego v1 syntax
opa fmt --rego-v1 -w policy.rego

# List files that would change
opa fmt -l ./policies/
```

---

## Bundle Management

Bundles package policies and data for distribution.

### Build

```bash
# Build from directory
opa build -b ./policies/ -o bundle.tar.gz

# With optimization (removes dead code)
opa build -b ./policies/ -o bundle.tar.gz --optimize=1

# Optimization levels:
#   0 = no optimization (default)
#   1 = inline partial rules
#   2 = more aggressive inlining

# Set entrypoints for optimization
opa build -b ./policies/ --entrypoint authz/allow -o bundle.tar.gz

# Build Wasm bundle
opa build -b ./policies/ --target wasm --entrypoint authz/allow -o policy.wasm
```

### Sign and Verify

```bash
# Generate signing key
openssl genrsa -out key.pem 2048
openssl rsa -in key.pem -pubout -out pubkey.pem

# Sign bundle
opa sign --signing-key key.pem --bundle bundle.tar.gz

# OPA verifies signatures on bundle download automatically
# Configure in OPA config:
# bundles:
#   authz:
#     signing:
#       keyid: my_key
```

### Inspect

```bash
# View bundle contents
opa inspect bundle.tar.gz

# Output: namespaces, entrypoints, revision, metadata
```

### Bundle Structure

```
bundle.tar.gz
├── data.json          # Static data
├── policies/
│   ├── authz.rego
│   └── helpers.rego
├── .manifest           # Bundle metadata
└── .signatures.json    # Cryptographic signatures
```

---

## Regal Linter

Regal is the official Rego linter with 60+ rules.

### Installation

```bash
# macOS
brew install styrainc/packages/regal

# Go install
go install github.com/styrainc/regal@latest

# GitHub Actions
- uses: styrainc/setup-regal@v2
```

### Usage

```bash
# Lint all Rego files
regal lint ./policies/

# Lint specific file
regal lint policy.rego

# Output as JSON
regal lint --format json ./policies/

# Fix auto-fixable issues
regal fix ./policies/
```

### Configuration

Create `.regal/config.yaml`:

```yaml
rules:
  style:
    opa-fmt:
      level: error
    prefer-some-in-iteration:
      level: error
    use-assignment-operator:
      level: error
  bugs:
    constant-condition:
      level: error
    unused-return-value:
      level: error
  testing:
    test-outside-test-package:
      level: warning
  imports:
    prefer-package-imports:
      level: warning
  custom:
    naming-convention:
      level: warning
      conventions:
        - pattern: "^[a-z_][a-z0-9_]*$"
          targets:
            - rule
            - function
```

### Key Rule Categories

| Category | Focus |
|----------|-------|
| `bugs` | Logic errors, constant conditions, unused values |
| `style` | Formatting, naming, operator usage |
| `imports` | Import organization, redundancy |
| `testing` | Test file conventions, coverage |
| `performance` | Inefficient patterns |
| `custom` | User-defined naming and style rules |

---

## Regal Language Server

Regal provides LSP support for IDE integration:

| Feature | Description |
|---------|-------------|
| Diagnostics | Real-time linting warnings/errors |
| Completion | Rule names, built-ins, packages |
| Hover | Documentation for built-in functions |
| Go to definition | Navigate to rule/function definitions |
| Code actions | Quick fixes for linting issues |
| Formatting | `opa fmt` integration |

---

## Benchmarking

```bash
# Benchmark a query
opa bench -d policy.rego -i input.json "data.authz.allow"

# With memory stats
opa bench -d policy.rego -i input.json "data.authz.allow" --benchmem

# Output:
# BenchmarkEval     5000    234567 ns/op    12345 B/op    123 allocs/op
```

---

## Environment Variables

OPA CLI commands support env var overrides:

```bash
# Pattern: OPA_<COMMAND>_<FLAG>
export OPA_EVAL_STRICT=true
export OPA_CHECK_STRICT=true
export OPA_FMT_REGO_V1=true
```

---

## CI/CD Pipeline Integration

```yaml
# GitHub Actions
- name: Setup OPA
  uses: open-policy-agent/setup-opa@v2
  with:
    version: latest

- name: Setup Regal
  uses: styrainc/setup-regal@v2

- name: Check Syntax
  run: opa check --strict ./policies/

- name: Lint
  run: regal lint ./policies/

- name: Test with Coverage
  run: opa test ./policies/ -v --coverage --threshold 80

- name: Build Bundle
  run: opa build -b ./policies/ -o bundle.tar.gz
```

---

## Additional Resources

### Reference Files

- **`references/opa-server.md`** - OPA server mode, REST API, management APIs (bundles, decision logs, status)
- **`references/ci-cd-patterns.md`** - Detailed CI/CD integration patterns for GitHub Actions, GitLab CI, Jenkins, ArgoCD