gha-expression-proof 1.0.0

# gha-expression-proof

`gha-expression-proof` evaluates GitHub Actions expressions without needing GitHub. It parses `${{ ... }}` expressions, evaluates them against supplied context JSON, and emits text, JSON, or Markdown receipts that offline CI systems can attach to workflow planning and execution evidence.

It is built for local runners, action authors, and tools like `ci-forge` that need to explain how `if:`, `env:`, `with:`, matrix values, and templates resolved.

## Install

```powershell
cargo install gha-expression-proof --locked
```

## Use

Evaluate an expression against a `gha-eventsmith` context bundle:

```powershell
gha-expression-proof eval `
  --expr "github.ref == 'refs/heads/main' && contains(github.event.issue.labels.*.name, 'bug')" `
  --github-context fixtures/push/github-context.json `
  --format json
```

Evaluate a workflow `if:` condition with GitHub's implicit `success()` default:

```powershell
gha-expression-proof eval `
  --expr "github.ref == 'refs/heads/main'" `
  --github-context fixtures/push/github-context.json `
  --if-condition `
  --job-status success
```

Render a string containing expression interpolations:

```powershell
gha-expression-proof template `
  --template 'deploy-${{ github.ref_name }}-${{ github.sha }}' `
  --github-context fixtures/push/github-context.json
```

Evaluate `hashFiles()` from a workspace:

```powershell
gha-expression-proof eval `
  --expr "hashFiles('Cargo.lock') != ''" `
  --workspace .
```

Load additional contexts:

```powershell
gha-expression-proof eval `
  --expr "fromJSON(env.timeout) > 5" `
  --context-json 'env={"timeout":"10"}'
```

## Supported Surface

- Literals: `null`, booleans, numbers, hex numbers, and single-quoted strings.
- Operators: `!`, `<`, `<=`, `>`, `>=`, `==`, `!=`, `&&`, `||`.
- Context dereference: `github.ref`, `steps.build.outputs.hash`, `matrix.os`.
- Index access: `github.event.pull_request.labels[0].name`.
- Object filters: `github.event.issue.labels.*.name`.
- Functions: `contains`, `startsWith`, `endsWith`, `format`, `join`, `toJSON`, `fromJSON`, `hashFiles`, `success`, `failure`, `cancelled`, `always`, and `case`.
- Template interpolation for strings containing one or more `${{ ... }}` expressions.
- JSON, Markdown, or text receipts.

The expression behavior is modeled from GitHub's Actions expression documentation: <https://docs.github.com/en/actions/reference/workflows-and-actions/expressions>.

## GitHub Action

```yaml
jobs:
  expression-proof:
    runs-on: ubuntu-latest
    steps:
      - uses: wildmason/gha-expression-proof@v1
        with:
          mode: eval
          expr: "github.ref == 'refs/heads/main'"
          github-context: fixtures/push/github-context.json
          format: markdown
          output: expression-proof.md
```

The action wrapper installs the published crate with `cargo install`. For air-gapped runners, install the binary in the runner image and call the CLI directly.

## Receipts

Receipts include:

- tool name and version
- expression or template input
- result value, type, string rendering, and truthiness
- loaded context roots
- referenced context roots
- called functions
- pass/warn/fail/skip summary
- stable check IDs

## Limits

`gha-expression-proof` is an expression oracle, not a full workflow runner. It does not parse workflow YAML, expand matrices, execute steps, resolve actions, evaluate every runner-side context lifecycle rule, or call GitHub APIs. Object/array equality is modeled by context-origin identity where possible and is intentionally conservative for values created by functions.

See [docs/spec.md](docs/spec.md) for compatibility notes and [docs/RULES.md](docs/RULES.md) for receipt check IDs.

## License

Licensed under either of:

- Apache License, Version 2.0 ([LICENSE-APACHE](LICENSE-APACHE))
- MIT license ([LICENSE-MIT](LICENSE-MIT))

at your option.